RFC: #[nest] attribute for first-class nested routing

[Madoshakalaka]

Summary

Add #[nest("/prefix")] to the Routable derive macro. A route enum can
delegate a URL subtree to a nested Routable type that defines routes relative
to the mount point. No inner Switch needed.

#[derive(Clone, Routable, PartialEq)]
enum MainRoute {
    #[at("/")]
    Home,
    #[nest("/settings")]
    Settings(SettingsRoute),
    #[not_found]
    #[at("/404")]
    NotFound,
}

#[derive(Clone, Routable, PartialEq)]
enum SettingsRoute {
    #[at("/")]
    Profile,
    #[at("/friends")]
    Friends,
    #[at("/theme")]
    Theme,
}

/settings/friends resolves to MainRoute::Settings(SettingsRoute::Friends).

Motivation

This is what nested routing looks like today:

#[derive(Clone, Routable, PartialEq)]
enum MainRoute {
    #[at("/")]
    Home,
    #[at("/settings")]
    SettingsRoot,
    #[at("/settings/")]                   // trailing slash hack
    SettingsSlash,
    #[at("/settings/{*_rest}")]           // catch-all for sub-paths
    Settings { _rest: String },
    #[not_found]
    #[at("/404")]
    NotFound,
}

#[derive(Clone, Routable, PartialEq)]
enum SettingsRoute {
    #[at("/settings")]                    // prefix repeated
    Profile,
    #[at("/settings/friends")]            // prefix repeated
    Friends,
    #[at("/settings/theme")]              // prefix repeated
    Theme,
    #[not_found]
    #[at("/settings/404")]
    NotFound,
}

fn switch_main(route: MainRoute) -> Html {
    match route {
        MainRoute::Home => html! { <h1>{"Home"}</h1> },
        MainRoute::SettingsRoot | MainRoute::Settings { .. } => {
            html! { <Switch<SettingsRoute> render={switch_settings} /> }
        }
        // /settings/ can't pipe into inner Switch (inner doesn't match "/settings/")
        MainRoute::SettingsSlash => html! { <Redirect<MainRoute> to={MainRoute::SettingsRoot}/> },
        MainRoute::NotFound => html! { <h1>{"Not Found"}</h1> },
    }
}

Three outer variants just to delegate. Every inner route repeats /settings.
Two Switch components match independently. /settings/ needs a redirect hack
because matchit's catch-all requires >= 1 char.

#[nest] eliminates all of this: inner routes are relative, outer enum has one
variant, one Switch resolves the full tree.

Design

Usage

The variant must be a tuple variant with one Routable field. #[nest] and
#[at] are mutually exclusive. #[not_found] is not allowed on #[nest].

fn switch_main(route: MainRoute) -> Html {
    match route {
        MainRoute::Home => html! { <h1>{"Home"}</h1> },
        MainRoute::Settings(inner) => switch_settings(inner),
        MainRoute::NotFound => html! { <h1>{"404"}</h1> },
    }
}

Multi-level nesting composes naturally:

#[derive(Clone, Routable, PartialEq)]
enum AdminRoute {
    #[at("/")]
    Dashboard,
    #[nest("/users")]
    Users(UserRoute),
}

/admin/users/42 resolves to
AppRoute::Admin(AdminRoute::Users(UserRoute::Detail { id: 42 })).

Static routes coexist with nests under the same prefix (matchit gives static
routes priority over catch-alls).

matchit registration

For #[nest("/settings")], the macro registers two patterns:

1. /settings (exact) - sub-path = "/"
2. /settings/{*__nested_N} (catch-all) - sub-path = "/{captured}"

Verified: matchit 0.9 supports exact + catch-all + sibling static routes under
the same prefix. /settings/ matches neither pattern (catch-all needs >= 1
char), consistent with PR #4110 trailing slash semantics.

Generated recognize()

// Nest patterns branch: compute sub-path, delegate to inner
"/settings" | "/settings/{*__nested_0}" => {
    let sub_path = match params.get("__nested_0") {
        Some(rest) => format!("/{rest}"),
        None => "/".to_string(),
    };
    SettingsRoute::recognize(&sub_path)
        .map(Self::Settings)
        .or_else(Self::not_found_route)
}

Nest variants are resolved entirely in recognize(). from_path() is
unchanged and only handles #[at] variants.

Generated to_path()

Self::Settings(inner) => {
    let inner_path = inner.to_path();
    if inner_path == "/" {
        "/settings".to_string()
    } else {
        format!("/settings{inner_path}")
    }
}

The "/" special case avoids generating "/settings/" for the inner root.

not_found interaction

If the inner type has #[not_found], unrecognized sub-paths produce
Some(MainRoute::Settings(SettingsRoute::NotFound)). The switch function
decides what to do (sub-404, redirect to outer 404, etc.). If the inner type
has no #[not_found], the outer not_found_route() is used instead.

What does not change

The Routable trait, Switch, use_route, Navigator, and basename logic.

Drawbacks

1. use_route::<SettingsRoute>() does not work. The hook reads the full
   pathname; the inner router uses relative paths. Route must be passed via
   props or context.

2. routes() includes internal catch-all patterns. Users calling
   routes() for sitemap generation would see "/settings/{*__nested_0}".

Future possibilities

• Parameterized prefixes: #[nest("/users/{id}")] with mixed fields
• Router-level trailing slash policy: normalize URL before matching
• use_nested_route hook: access sub-route without prop drilling
• Multiple #[at] per variant: match /about and /about/ on one variant