Struct Router 

pub struct Router<State>
where
    State: 'static,
{ /* private fields */ }

The declarative router vocabulary (a go_router-subset layer), flat-re-exported from frust-widgets so app code never names that crate directly: Router resolves a location against a Route table (built via RouteBuilder) into Resolution/ResolvedPages driving a NavigatorController, with :param/query parsing (Location/PathPattern/RouteParams), per-route/top-level Redirects (loop-guarded at DEFAULT_REDIRECT_LIMIT), and an ErrorBuilder fallback for an unmatched location.

A page builder receives the location’s query merged under its path captures, so /terminal?session=abc reads its own parameter.

RouteNavigator is the seam a screen navigates through: a Send + Sync queue of NavRequest data (paths and names, never closures) that rides provide_context — the Router itself cannot, since it holds Rc page builders. RouterDeepLinks::track drains it every rebuild, so a request queued in an event handler (on any thread — the queue never panics off-thread) applies on the next frame.

shell_route is the nested-navigator binding: its children resolve onto a second NavigatorController the app owns and its own page — the chrome wrapping that inner navigator — stays retained while they do, so navigating between siblings inside the shell never rebuilds the chrome. See its docs for the keep rule and the per-verb table. A declarative router over a navigator. See the module docs.

Implementations

impl<State> Router<State>

where State: 'static,

pub fn new(routes: Vec<Route<State>>) -> Router<State>

A router over routes with a fresh NavigatorController, the default error page, and the default redirect limit (DEFAULT_REDIRECT_LIMIT).

pub fn with_controller( controller: &NavigatorController<State>, routes: Vec<Route<State>>, ) -> Router<State>

A router driving controller (so an app can hand the same controller to navigator).

pub fn redirect( self, redirect: impl Fn(&Location) -> Option<String> + 'static, ) -> Router<State>

Set a top-level redirect, consulted before matching on every resolution.

pub fn error_builder( self, error_builder: impl Fn(&Location) -> AnyView<State> + 'static, ) -> Router<State>

Replace the error-page builder (default: a simple themed “not found” page).

pub fn redirect_limit(self, limit: usize) -> Router<State>

Override the redirect loop limit (default DEFAULT_REDIRECT_LIMIT).

pub fn controller(&self) -> &NavigatorController<State>

The controller this router drives — hand it to navigator so the app’s page stack and the router share one op queue.

pub fn resolve(&self, raw: &str) -> Resolution<State>

Resolve a location string into a Resolution (pure; no controller side effects). Applies top-level and per-route redirects under the loop guard; an unmatched location or an over-limit redirect chain yields Resolution::Error.

pub fn route_navigator(&self) -> RouteNavigator

The RouteNavigator screens navigate through: a Send + Sync handle safe to hold under provide_context, in a callback, or on a background thread. Requests queued on it are applied by this router’s next pump — see the module docs’ “Reaching the router from a screen”.

pub fn pump(&self)

Drain the route_navigator’s queue and apply each request, in order. Idempotent when the queue is empty, so it is meant to be called unconditionally once per rebuild (the facade’s RouterDeepLinks::track does exactly that). Must run on the UI thread — it drives the Rc-backed NavigatorController; queuing is what is thread-free.

pub fn go(&self, location: &str)

Reset the stack to the matched chain (replace semantics — the current top’s state is dropped). See the module docs’s deferred note on arbitrary-depth reset.

Each resolved page is stamped with its own ResolvedPage::location (R-B1) — NavigatorController::route_stack tracks the resulting page-to-route mapping, so no consumer needs to re-derive it.

A chain crossing a shell_route boundary is split across the two controllers instead, under the keep rule — see shell_route’s table.

pub fn push(&self, location: &str)

Push the matched leaf page onto the stack (the page below is retained).

Stamps the leaf’s ResolvedPage::location — see go’s doc. Across a shell_route boundary the leaf lands on the shell’s inner controller — see shell_route’s table.

pub fn replace(&self, location: &str)

Replace the top page with the matched leaf (the top’s state is dropped; the stack depth is unchanged). go’s single-page case, minus the chain push — the op a NavRequest::Replace applies.

Stamps the leaf’s ResolvedPage::location — see go’s doc. Across a shell_route boundary the replaced top is the shell’s inner one — see shell_route’s table.

pub fn pop(&self)

Pop the top page of the router’s own controller (a no-op on the root page — see NavigatorController::pop).

Deliberately not shell-aware: popping “one page, wherever the user actually is” is back arbitration’s job (the facade’s back handler routes a press innermost-first), not the router’s. See the module docs’ deferred note and shell_route’s Back section.

pub fn handle_location(&self, location: &str)

The single entry point a deep link resolves through — same reset semantics as go. The facade tracks the deep-link signal and calls this; this crate stays reactive-free.

pub fn go_named(&self, name: &str, params: &BTreeMap<String, String>)

Resolve name + params into a path, then go to it. An unknown name routes to the error page.

pub fn push_named(&self, name: &str, params: &BTreeMap<String, String>)

Resolve name + params into a path, then push it. An unknown name routes to the error page.

pub fn path_for_name( &self, name: &str, params: &BTreeMap<String, String>, ) -> Option<String>

Build the full path for a named route, substituting :params from params (composing nested parent + child patterns). Params not consumed by a path segment become query parameters (go_router parity). None if no route has the name.