Struct ClientRouter 

pub struct ClientRouter { /* private fields */ }

Available on crate feature client-router only.

The main client-side router.

ClientRouter renders views using the Page type.

Clone semantics

The Clone impl is shallow by design. Signal fields share their underlying reactive state across clones, and on WASM the navigation observer state (held behind Rc) is shared as well; only the route table (Vec<ClientRoute> / HashMap<String, usize>) is copied independently. As a result two clones see the same navigation state but can diverge if either is mutated to register new routes — this is not a deep clone of the router.

In practice Clone is only invoked by collect_client_router_from_inventory (Refs #4453) as the fallback path for Arc::try_unwrap when the underlying factory Arc is shared, and ClientLauncher::register_routes_from_inventory() is the only caller. Application code should NOT call .clone() directly to “branch” routers; treat the router as a single owned value moved into the launcher. Refs Copilot review on PR #4477.

Implementations

impl ClientRouter

pub fn new() -> ClientRouter

Available on crate feature pages only.

Creates a new router.

pub fn merge(self, other: ClientRouter) -> ClientRouter

Available on crate feature pages only.

Combine another ClientRouter into this one.

Routes and named-route mappings from other are appended to self, preserving the order in which routes were originally registered. The reactive signals (current_path, current_params, current_route_name) and the not_found handler from other are discarded — self’s observation state is the one that drives the merged router.

Named-route collisions

If both routers register the same named route, the entry from other overwrites the entry from self (last-wins). This matches the way UnifiedRouter::mount_unified already composes per-app routers, and keeps merge callable in chains where the caller does not want to handle errors. Use ClientRouter::try_merge for a fallible variant that surfaces collisions instead of silently shadowing them.

Examples

Composing per-app SPA routers into the single ClientRouter that ClientLauncher::router_client expects:

let router = polls_client_url_patterns()
    .merge(users_client_url_patterns());

pub fn try_merge(self, other: ClientRouter) -> Result<ClientRouter, MergeError>

Available on crate feature pages only.

Like ClientRouter::merge, but fail if any named route collides.

Validates first, so on Err self is dropped without being mutated. On success the semantics are identical to merge (routes appended, other’s signals and not_found discarded).

Errors

Returns MergeError::NameCollision carrying a colliding name when at least one named route is registered in both routers. When several names collide, the returned name is one of them; the choice is unspecified because named routes are stored in a HashMap.

Examples

match polls_client_url_patterns().try_merge(users_client_url_patterns()) {
    Ok(router) => launcher.router_client(|| router),
    Err(MergeError::NameCollision { name }) => {
        panic!("two apps register the route `{name}`");
    }
}

pub fn with_namespace(self, namespace: &str) -> ClientRouter

Available on crate feature pages only.

Prefix all named route keys with "namespace:".

This is the client-side equivalent of ServerRouter::with_namespace(). Called by client/unified route declarations to ensure registered names match the "app:route" format used by per-app resolver structs.

pub fn with_route_metadata( self, name: &str, metadata: RouteMetadata, ) -> ClientRouter

Available on crate feature pages only.

Adds metadata to an already-registered named route.

Panics

Panics if name is not registered.

pub fn route<F>(self, name: &str, pattern: &str, component: F) -> ClientRouter

where F: Fn() -> Page + Send + Sync + 'static,

Available on crate feature pages only.

Adds a named route to the router.

Every route requires a unique name for reverse URL lookup.

Panics

Panics if name duplicates an already-registered route name.

pub fn route_params<F, T>( self, name: &str, pattern: &str, handler: F, ) -> ClientRouter

where F: Fn(Path<T>) -> Page + Send + Sync + 'static, T: FromPath + Send + Sync + 'static,

Available on crate feature pages only.

Adds a named route with typed path parameters.

Panics

Panics if name duplicates an already-registered route name.

pub fn route_result<F, T, E>( self, name: &str, pattern: &str, handler: F, ) -> ClientRouter

where F: Fn(Path<T>) -> Result<Page, E> + Send + Sync + 'static, T: FromPath + Send + Sync + 'static, E: Into<RouterError> + Send + Sync + 'static,

Available on crate feature pages only.

Adds a named route with typed path parameters that returns a Result.

Panics

Panics if name duplicates an already-registered route name.

pub fn page<F, P>(self, name: &str, pattern: &str, handler: F) -> ClientRouter

where F: Fn(P) -> Page + Send + Sync + 'static, P: FromRequest + Send + Sync + 'static,

Available on crate feature pages only.

Adds a named route whose handler receives a single Props struct constructed via FromRequest (Manouche DSL v2 spec §4.3).

This is the canonical v2 route-handler shape: the same Props struct can be used both as a Component (passed via the Component { ... } invocation syntax) and as a page function (registered here). Path / query extraction errors surface as a Page::Text describing the failure rather than panicking.

Example

use reinhardt_urls::routers::ClientRouter;
use reinhardt_urls::routers::client_router::from_request::{
    ExtractError, FromRequest, PathParam, RouteContext,
};

struct UserPageProps { id: PathParam<i32> }

impl FromRequest for UserPageProps {
    fn from_request(ctx: &RouteContext) -> Result<Self, ExtractError> {
        Ok(Self { id: PathParam::extract(ctx, "id")? })
    }
}

fn user_page(props: UserPageProps) -> reinhardt_core::types::page::Page {
    reinhardt_core::types::page::Page::Text(
        format!("user {}", props.id.into_inner()).into(),
    )
}

let router = ClientRouter::new().page("user", "/users/{id}/", user_page);

Panics

Panics if the pattern is invalid (exceeds length/segment limits or invalid regex). Use ClientPathPattern::new directly for fallible construction. Also panics if name duplicates an already-registered route name.

pub fn component<F, P>(self, handler: F) -> ClientRouter

where F: Fn(P) -> Page + Send + Sync + 'static, P: FromRequest + ComponentInfo + Send + Sync + 'static,

Available on crate feature pages only.

Adds a named route from metadata generated by #[component].

This mirrors the server-side endpoint registration style: the handler function supplies the props type, and the props type supplies route metadata through ComponentInfo.

Example

use reinhardt_pages::{Page, Path, component, page};
use reinhardt_urls::routers::ClientRouter;

#[component("/users/{id}/", "user-detail")]
fn user_page(Path(id): Path<i64>) -> Page {
    page!(|id: i64| { div { { id.to_string() } } })(id)
}

let router = ClientRouter::new().component(user_page);

pub fn guarded_route<F, G>( self, pattern: &str, component: F, guard: G, ) -> ClientRouter

where F: Fn() -> Page + Send + Sync + 'static, G: Fn(&ClientRouteMatch) -> bool + Send + Sync + 'static,

Available on crate feature pages only.

Adds a route with a guard.

pub fn route_path<H, Args>( self, name: &str, pattern: &str, handler: H, ) -> ClientRouter

where H: Handler<Args>,

Available on crate feature pages only.

Adds a named route with one to eight path parameters using Path<T> extractors.

The handler closure may take any number of Path<T> arguments from 1 to 8. The compiler infers the arity from the closure signature via the sealed Handler<Args> trait, so the same method name covers every supported arity. Refs Issue #4637.

Examples

// One path parameter
let router = ClientRouter::new()
    .route_path("user_detail", "/users/{id}/", |Path(id): Path<i64>| user_detail(id));

// Two path parameters
let router = router.route_path(
    "user_post_detail",
    "/users/{user_id}/posts/{post_id}/",
    |Path(user_id): Path<i64>, Path(post_id): Path<i64>| {
        user_post_detail(user_id, post_id)
    },
);

// Three path parameters
let router = router.route_path(
    "issue_detail",
    "/org/{org}/repos/{repo}/issues/{issue}/",
    |Path(org): Path<String>, Path(repo): Path<String>, Path(issue): Path<i32>| {
        issue_detail(org, repo, issue)
    },
);

Panics

Panics if the pattern is invalid or if name duplicates an already-registered route name.

pub fn not_found<F>(self, component: F) -> ClientRouter

where F: Fn() -> Page + Send + Sync + 'static,

Available on crate feature pages only.

Sets the not found handler.

pub fn current_path(&self) -> &Signal<String>

Available on crate feature pages only.

Returns the current path signal.

pub fn current_params(&self) -> &Signal<HashMap<String, String>>

Available on crate feature pages only.

Returns the current params signal.

pub fn current_route_name(&self) -> &Signal<Option<String>>

Available on crate feature pages only.

Returns the current route name signal.

pub fn route_patterns(&self) -> impl Iterator<Item = (&str, Option<&str>)>

Available on crate feature pages only.

Returns an iterator over registered route patterns and their optional names.

Each item is (pattern_str, name) where name is Some for named routes. Intended for diagnostic output (e.g., the runserver startup banner).

pub fn match_path(&self, path: &str) -> Option<ClientRouteMatch>

Available on crate feature pages only.

Matches a path against registered routes.

Strips an optional ?query suffix before matching and stores the captured query (without the leading ?) on ClientRouteMatch::query. Patterns therefore match against the path portion only; the query is delivered to handlers via the match struct (used by ClientRouter::page / QueryParam).

pub fn push(&self, path: &str) -> Result<(), RouterError>

Available on crate feature pages only.

Navigates to a path using pushState.

pub fn replace(&self, path: &str) -> Result<(), RouterError>

Available on crate feature pages only.

Navigates to a path using replaceState.

pub fn on_navigate<F>(&self, listener: F) -> NavigationSubscription

where F: Fn(&str, &HashMap<String, String>) + 'static,

Available on crate feature pages only.

Register a listener for navigation events.

Returns a NavigationSubscription handle. Drop the handle to deregister the listener. The router itself only retains a Weak reference, so dropping the subscription frees the listener closure immediately. The stale Weak entry in navigation_observers is pruned lazily on the next notify_observers call (the listener itself is already gone by then).

Robust against nested reactive nodes spawned during view rendering because this subscription is independent of the reactive Effect / Signal auto-tracking system.

Mirrors pages::Router::on_navigate. (Refs #4234)

On native targets (Fixes #4258) this is effectively a no-op: the returned NavigationSubscription is unbound to any observer storage because reactive observation only fires from the wasm popstate listener. The method is still callable on native so that the SpaRouter trait impl in reinhardt-pages (which dispatches into on_navigate from cross-target launcher code) keeps compiling.

pub fn reverse( &self, name: &str, params: &[(&str, &str)], ) -> Result<String, RouterError>

Available on crate feature pages only.

Generates a URL by route name with parameters.

pub fn render_current(&self) -> Page

Available on crate feature pages only.

Renders the current route’s component.

Returns the registered not_found page when no route matches, or a default 404 page if no not_found handler has been set.

pub fn route_count(&self) -> usize

Available on crate feature pages only.

Returns the number of registered routes.

pub fn has_route(&self, name: &str) -> bool

Available on crate feature pages only.

Checks if a route name exists.

pub fn setup_history_listener(&self)

Available on native and crate feature pages only.

Non-WASM version of setup_history_listener.

Trait Implementations

impl Clone for ClientRouter

fn clone(&self) -> ClientRouter

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ClientRouter

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for ClientRouter

fn default() -> ClientRouter

Returns the “default value” for a type.