@studiolambda/router 0.1.0

package/dist/src/react/createRouter.d.ts

@@ -0,0 +1,187 @@
+import { ComponentType } from 'react';
+import { Matcher } from '../router/matcher';
+import { FormHandler, Handler, MiddlewareProps, PrefetchFunc, RedirectTarget } from './router';
+/**
+ * Chainable route builder returned by the `route()` factory.
+ * Accumulates handler configuration through method calls and
+ * terminates with `.render()`, `.redirect()`, or `.group()`.
+ *
+ * Chainable methods (return the builder for further chaining):
+ * - `.middleware()` — appends middleware components
+ * - `.prefetch()` — adds a prefetch function to the chain
+ * - `.scroll()` — sets scroll restoration behavior
+ * - `.focusReset()` — sets focus reset behavior
+ * - `.formHandler()` — sets the form submission handler
+ *
+ * Terminal methods:
+ * - `.render()` — registers a route with a component
+ * - `.redirect()` — registers a precommit redirect
+ * - `.group()` — returns a scoped `RouteFactory` that
+ *   inherits this builder's config
+ */
+export interface RouteBuilder {
+    /**
+     * Appends middleware components to this route or group.
+     * Middlewares are applied outermost-first: inherited group
+     * middlewares wrap before this route's middlewares, and
+     * within the array the first element wraps outermost.
+     *
+     * @param list - Middleware components to append.
+     * @returns The builder for further chaining.
+     */
+    middleware(list: ComponentType<MiddlewareProps>[]): RouteBuilder;
+    /**
+     * Adds a prefetch function to the chain for this route
+     * or group. When multiple prefetch functions are chained
+     * (from parent groups and the route itself), they execute
+     * sequentially: parent prefetches run first, then this
+     * route's, in the order they were added.
+     *
+     * @param fn - The prefetch function to add.
+     * @returns The builder for further chaining.
+     */
+    prefetch(fn: PrefetchFunc): RouteBuilder;
+    /**
+     * Sets the scroll restoration behavior for this route.
+     * - `'after-transition'` — browser handles scroll after
+     *   the handler promise resolves (default).
+     * - `'manual'` — disables automatic scrolling so the
+     *   route component can call `event.scroll()` manually.
+     *
+     * @param behavior - The scroll behavior to use.
+     * @returns The builder for further chaining.
+     */
+    scroll(behavior: NavigationScrollBehavior): RouteBuilder;
+    /**
+     * Sets the focus reset behavior for this route.
+     * - `'after-transition'` — focuses the first autofocus
+     *   element after the handler resolves (default).
+     * - `'manual'` — disables automatic focus reset.
+     *
+     * @param behavior - The focus reset behavior to use.
+     * @returns The builder for further chaining.
+     */
+    focusReset(behavior: NavigationFocusReset): RouteBuilder;
+    /**
+     * Sets the form submission handler for this route. When
+     * a navigation includes FormData and matches this route,
+     * the form handler is called instead of rendering the
+     * component.
+     *
+     * @param fn - The form handler function.
+     * @returns The builder for further chaining.
+     */
+    formHandler(fn: FormHandler): RouteBuilder;
+    /**
+     * Terminal method that registers this route on the matcher
+     * with the given component. Merges inherited and local
+     * configuration into a `Handler` and registers it at the
+     * full path (group prefix + route path).
+     *
+     * @param component - The React component to render.
+     * @throws When no path was provided to the `route()` call
+     *   and no group prefix exists.
+     */
+    render(component: ComponentType): void;
+    /**
+     * Terminal method that registers a precommit redirect.
+     * When the Navigation API matches this route, the
+     * precommit handler calls `controller.redirect(target)`
+     * before the URL commits, avoiding any component render
+     * or visual flash.
+     *
+     * The target can be a static absolute path string, or a
+     * callback that receives the prefetch context and returns
+     * the path. The callback form enables dynamic redirects
+     * that carry route parameters to the new location.
+     *
+     * The resolved target path is absolute and is NOT prefixed
+     * by parent groups.
+     *
+     * @param target - The redirect target: a static path or a
+     *   callback receiving `PrefetchContext` and returning one.
+     * @throws When no path was provided to the `route()` call
+     *   and no group prefix exists.
+     *
+     * @example
+     * ```ts
+     * // Static redirect
+     * route('/old').redirect('/new')
+     *
+     * // Dynamic redirect using route params
+     * route('/old-user/:id').redirect(({ params }) => `/user/${params.id}`)
+     * ```
+     */
+    redirect(target: RedirectTarget): void;
+    /**
+     * Terminal method that creates a nested route scope.
+     * Returns a `RouteFactory` whose routes inherit this
+     * builder's middleware and prefetch configuration. When
+     * a path was provided, it is prepended to all child
+     * route paths as a prefix.
+     *
+     * @returns A scoped `RouteFactory` for defining child
+     *   routes that inherit this builder's config.
+     *
+     * @example
+     * ```ts
+     * const admin = route('/admin').middleware([Auth]).group()
+     * admin('/dashboard').render(Dashboard)
+     * admin('/settings').render(Settings)
+     * ```
+     */
+    group(): RouteFactory;
+}
+/**
+ * Factory function that creates a route builder for a given
+ * path. When path is omitted, the builder is used purely for
+ * group-level configuration (middleware, prefetch) without
+ * contributing a path segment.
+ *
+ * @param path - Optional path pattern for this route. May
+ *   contain dynamic (`:param`) and wildcard (`*param`)
+ *   segments.
+ * @returns A chainable route builder.
+ */
+export type RouteFactory = (path?: string) => RouteBuilder;
+/**
+ * Creates a route matcher using a declarative builder API.
+ * Routes are defined inside a callback that receives a
+ * `route` factory function for chainable route configuration.
+ *
+ * The builder supports middleware inheritance, prefetch
+ * chaining, nested groups with path prefixing, redirects,
+ * and all handler options (scroll, focusReset, formHandler).
+ *
+ * Returns a `Matcher<Handler>` that plugs directly into the
+ * `<Router matcher={...}>` component.
+ *
+ * @param callback - A function that defines routes using the
+ *   provided `route` factory.
+ * @returns A populated matcher ready for the Router.
+ *
+ * @example
+ * ```tsx
+ * const router = createRouter(function (route) {
+ *   route('/').render(Home)
+ *   route('/old').redirect('/new')
+ *
+ *   route('/other')
+ *     .prefetch(prefetchOther)
+ *     .scroll('after-transition')
+ *     .render(Other)
+ *
+ *   const authed = route().middleware([Auth]).group()
+ *   authed('/dashboard').render(Dashboard)
+ *   authed('/user/:id').render(User)
+ *
+ *   const admin = authed('/admin')
+ *     .middleware([AdminOnly])
+ *     .group()
+ *   admin('/settings').render(Settings)
+ * })
+ *
+ * <Router matcher={router} />
+ * ```
+ */
+export declare function createRouter(callback: (route: RouteFactory) => void): Matcher<Handler>;

package/dist/src/react/example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/react/examples/Auth.d.ts

@@ -0,0 +1,11 @@
+import { PropsWithChildren } from 'react';
+/**
+ * Example authentication middleware component that suspends
+ * while verifying credentials. Uses React's `use()` hook to
+ * suspend rendering until the auth promise resolves, causing
+ * the nearest Suspense boundary to show its fallback.
+ *
+ * In a real application, this would check session tokens or
+ * call an authentication API.
+ */
+export default function Auth({ children }: PropsWithChildren): import('react').ReactNode;

package/dist/src/react/examples/HelloWorld.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Example route component that renders a simple greeting.
+ * Registered at the root `/` path in the example application.
+ */
+export default function HelloWorld(): import("react/jsx-runtime").JSX.Element;

package/dist/src/react/examples/Other.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Example route component for the `/other` path. Demonstrates
+ * a route with prefetch configuration and scroll behavior
+ * in the example application.
+ */
+export default function Other(): import("react/jsx-runtime").JSX.Element;

package/dist/src/react/examples/User.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Example route component for the `/user/:id` path.
+ * Demonstrates reading dynamic route parameters via the
+ * `useParams` hook and rendering them in the UI.
+ */
+export default function User(): import("react/jsx-runtime").JSX.Element;

package/dist/src/react/extractPathname.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Extracts the pathname portion from a URL string. Uses a
+ * dummy base URL to handle both absolute and relative paths
+ * correctly. Returns `'/'` when the input is null, undefined,
+ * or an empty string.
+ *
+ * Used by the Router (to extract pathname from navigation
+ * destination URLs), Link (for active link comparison), and
+ * usePrefetch (to match URLs against registered routes).
+ *
+ * @param url - The URL string to extract a pathname from.
+ *   May be absolute (`https://example.com/foo`), relative
+ *   (`/foo/bar`), or nullish.
+ * @returns The pathname string, or `'/'` when no URL is
+ *   provided.
+ */
+export declare function extractPathname(url: string | null | undefined): string;

package/dist/src/react/hooks/useActiveLinkProps.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Options for the `useActiveLinkProps` hook.
+ */
+export interface ActiveLinkOptions {
+    /**
+     * When true, the link is only considered active when
+     * the current pathname exactly matches the href
+     * pathname. When false, the link is active when the
+     * current pathname starts with the href pathname,
+     * which is useful for parent navigation items that
+     * should highlight when any child route is active.
+     *
+     * Defaults to `true`.
+     */
+    exact?: boolean;
+}
+/**
+ * Props returned by the hook to spread onto an anchor
+ * element for active link styling and accessibility.
+ */
+export interface ActiveLinkProps {
+    /**
+     * Present (set to `true`) when the link is active.
+     * Absent (`undefined`) when inactive. Use the
+     * `a[data-active]` CSS selector for styling.
+     */
+    'data-active': true | undefined;
+    /**
+     * Set to `'page'` when the link is active to indicate
+     * to assistive technologies that this link represents
+     * the current page. Absent when inactive.
+     */
+    'aria-current': 'page' | undefined;
+}
+/**
+ * Computes active link attributes for an anchor element
+ * by comparing its href against the current pathname from
+ * the Router's PathnameContext.
+ *
+ * Returns a props object containing `data-active` and
+ * `aria-current` attributes ready to spread onto an `<a>`
+ * element or any element that should reflect active state.
+ *
+ * Also returns an `isActive` boolean for conditional logic
+ * like dynamic class names.
+ *
+ * Must be used inside a `<Router>` component tree where
+ * `PathnameContext` is provided.
+ *
+ * @param href - The href to compare against the current
+ *   pathname. When undefined, the link is never active.
+ * @param options - Optional configuration for exact vs
+ *   prefix matching.
+ * @returns An object with `isActive` boolean and `props`
+ *   to spread onto the element.
+ *
+ * @example
+ * ```tsx
+ * function NavItem({ href, children }: NavItemProps) {
+ *   const { isActive, props } = useActiveLinkProps(href)
+ *
+ *   return (
+ *     <a href={href} className={isActive ? 'active' : ''} {...props}>
+ *       {children}
+ *     </a>
+ *   )
+ * }
+ * ```
+ */
+export declare function useActiveLinkProps(href: string | undefined, options?: ActiveLinkOptions): {
+    isActive: boolean;
+    props: ActiveLinkProps;
+};

package/dist/src/react/hooks/useBack.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Return value from the `useBack` hook, providing both
+ * a traversal function and a boolean indicating whether
+ * backward navigation is possible.
+ */
+export interface UseBackResult {
+    /**
+     * Navigates backward in the session history. Delegates
+     * to `navigation.back()` from the Navigation API.
+     *
+     * @param options - Optional navigation options such as
+     *   `info` to pass data to the navigate event handler.
+     * @returns The NavigationResult with `committed` and
+     *   `finished` promises.
+     */
+    readonly back: (options?: NavigationOptions) => NavigationResult;
+    /**
+     * Whether backward navigation is possible. Mirrors
+     * `navigation.canGoBack` from the Navigation API.
+     * When false, calling `back()` will throw.
+     */
+    readonly canGoBack: boolean;
+}
+/**
+ * Provides backward navigation capabilities using the
+ * Navigation API. Returns a `back` function and a
+ * `canGoBack` boolean that reflects whether the history
+ * stack has a previous entry to traverse to.
+ *
+ * Must be used inside a `<Router>` component tree.
+ *
+ * @returns An object with `back` and `canGoBack`.
+ *
+ * @example
+ * ```tsx
+ * function BackButton() {
+ *   const { back, canGoBack } = useBack()
+ *
+ *   return (
+ *     <button onClick={back} disabled={!canGoBack}>
+ *       Go Back
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export declare function useBack(): UseBackResult;

package/dist/src/react/hooks/useForward.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Return value from the `useForward` hook, providing both
+ * a traversal function and a boolean indicating whether
+ * forward navigation is possible.
+ */
+export interface UseForwardResult {
+    /**
+     * Navigates forward in the session history. Delegates
+     * to `navigation.forward()` from the Navigation API.
+     *
+     * @param options - Optional navigation options such as
+     *   `info` to pass data to the navigate event handler.
+     * @returns The NavigationResult with `committed` and
+     *   `finished` promises.
+     */
+    readonly forward: (options?: NavigationOptions) => NavigationResult;
+    /**
+     * Whether forward navigation is possible. Mirrors
+     * `navigation.canGoForward` from the Navigation API.
+     * When false, calling `forward()` will throw.
+     */
+    readonly canGoForward: boolean;
+}
+/**
+ * Provides forward navigation capabilities using the
+ * Navigation API. Returns a `forward` function and a
+ * `canGoForward` boolean that reflects whether the history
+ * stack has a next entry to traverse to.
+ *
+ * Must be used inside a `<Router>` component tree.
+ *
+ * @returns An object with `forward` and `canGoForward`.
+ *
+ * @example
+ * ```tsx
+ * function ForwardButton() {
+ *   const { forward, canGoForward } = useForward()
+ *
+ *   return (
+ *     <button onClick={forward} disabled={!canGoForward}>
+ *       Go Forward
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export declare function useForward(): UseForwardResult;

package/dist/src/react/hooks/useIsPending.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Returns whether a navigation transition is currently pending.
+ * This reflects the `isPending` value from the `useTransition`
+ * tuple managed by the Router component.
+ *
+ * Useful for displaying loading indicators, progress bars, or
+ * adjusting UI opacity while a route transition is in progress.
+ *
+ * Must be used inside a `<Router>` component tree or a
+ * `<TransitionContext>` provider.
+ *
+ * @returns `true` while a navigation transition is pending,
+ *   `false` otherwise.
+ * @throws When used outside a TransitionContext provider.
+ *
+ * @example
+ * ```tsx
+ * function NavBar() {
+ *   const isPending = useIsPending()
+ *
+ *   return (
+ *     <nav style={{ opacity: isPending ? 0.7 : 1 }}>
+ *       ...
+ *     </nav>
+ *   )
+ * }
+ * ```
+ */
+export declare function useIsPending(): boolean;

package/dist/src/react/hooks/useNavigate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns a function to programmatically navigate to a URL
+ * with full Navigation API options support (`state`, `info`,
+ * `history`). This is a thin convenience wrapper around
+ * `navigation.navigate()`.
+ *
+ * @returns A navigate function that accepts a URL string and
+ *   optional `NavigationNavigateOptions`.
+ */
+export declare function useNavigate(): (url: string, options?: NavigationNavigateOptions) => NavigationResult;

package/dist/src/react/hooks/useNavigation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns the native browser Navigation object from context.
+ * Gives full access to the Navigation API: `entries()`,
+ * `traverseTo()`, `updateCurrentEntry()`, `canGoBack`,
+ * `canGoForward`, `transition`, `currentEntry`, etc.
+ *
+ * Must be used inside a `<Router>` or a component tree
+ * that provides a `<NavigationContext>` value.
+ *
+ * @returns The Navigation object from the nearest provider.
+ * @throws When used outside a NavigationContext provider.
+ */
+export declare function useNavigation(): Navigation;

package/dist/src/react/hooks/useNavigationEvents.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Callbacks for navigation lifecycle events. All callbacks
+ * are optional — only provided callbacks are subscribed.
+ */
+export interface NavigationEventHandlers {
+    /**
+     * Called when a same-document navigation is initiated.
+     * The Router uses this to intercept the event, match
+     * the destination URL, and trigger a React transition.
+     */
+    readonly onNavigate?: (event: NavigateEvent) => void;
+    /**
+     * Called after a navigation completes successfully.
+     * Fires in sync with the Navigation API's
+     * `navigatesuccess` event.
+     */
+    readonly onNavigateSuccess?: () => void;
+    /**
+     * Called when a navigation fails. Receives the error
+     * extracted from the Navigation API's `navigateerror`
+     * ErrorEvent.
+     *
+     * @param error - The error that caused the navigation
+     *   to fail.
+     */
+    readonly onNavigateError?: (error: unknown) => void;
+}
+/**
+ * Subscribes to the Navigation API's `navigate`,
+ * `navigatesuccess`, and `navigateerror` events on the
+ * given navigation object. All callbacks are wrapped in
+ * `useEffectEvent` so the effects only depend on the
+ * navigation instance itself — inline arrow functions
+ * from the caller don't cause unnecessary re-subscriptions.
+ *
+ * Cleans up all listeners on unmount or when the navigation
+ * instance changes.
+ *
+ * @param navigation - The Navigation object to subscribe to.
+ * @param handlers - Callbacks for each navigation lifecycle
+ *   event. All are optional.
+ */
+export declare function useNavigationEvents(navigation: Navigation, handlers: NavigationEventHandlers): void;

package/dist/src/react/hooks/useNavigationHandlers.d.ts

@@ -0,0 +1,47 @@
+import { TransitionFunction, useTransition } from 'react';
+import { PrefetchFunc } from '../router';
+/**
+ * Options for creating a precommit handler that forwards
+ * route context to the prefetch function.
+ */
+export interface PrecommitHandlerOptions {
+    /**
+     * The prefetch function from the matched route handler.
+     * When undefined, no precommit handler is created.
+     */
+    readonly prefetch?: PrefetchFunc;
+    /**
+     * Dynamic route parameters extracted from the matched
+     * URL pattern.
+     */
+    readonly params: Record<string, string>;
+    /**
+     * The destination URL being navigated to.
+     */
+    readonly url: URL;
+}
+/**
+ * Creates handler functions for the Navigation API's
+ * `event.intercept()` method. The precommit handler runs
+ * prefetch logic before the URL commits; the handler runs
+ * the React state transition after the URL commits.
+ *
+ * Accepts an optional `transition` tuple to use directly.
+ * When omitted, reads from TransitionContext instead. The
+ * Router component passes its own transition tuple here to
+ * avoid a circular dependency — the Router provides the
+ * TransitionContext in its JSX return, but needs the
+ * handlers during render before that provider exists in
+ * the tree.
+ *
+ * @param transition - Optional `useTransition()` tuple to
+ *   use instead of reading from TransitionContext. Pass
+ *   this when calling from within the component that
+ *   provides TransitionContext.
+ * @throws When no transition tuple is provided and the
+ *   hook is used outside a TransitionContext provider.
+ */
+export declare function useNavigationHandlers(transition?: ReturnType<typeof useTransition>): {
+    createPrecommitHandler: (options: PrecommitHandlerOptions) => ((controller: NavigationPrecommitController) => Promise<void>) | undefined;
+    createHandler: (callback: TransitionFunction) => () => Promise<void>;
+};

package/dist/src/react/hooks/useNavigationSignal.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns the AbortSignal from the current navigation event.
+ * The signal aborts when the navigation is cancelled (e.g.,
+ * by the user pressing Stop or a new navigation superseding
+ * this one). Pass this to fetch calls or other cancellable
+ * async operations to avoid stale work.
+ *
+ * Returns `null` before any navigation event has occurred
+ * (i.e. on the initial render).
+ *
+ * @returns The current AbortSignal or null.
+ */
+export declare function useNavigationSignal(): AbortSignal | null;

package/dist/src/react/hooks/useNavigationType.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns the navigation type of the most recent navigation
+ * (`push`, `replace`, `reload`, or `traverse`). Useful for
+ * varying animations, skipping prefetch on reload, or
+ * applying different behavior for back/forward traversals.
+ *
+ * Returns `null` before any navigation event has occurred
+ * (i.e. on the initial render).
+ *
+ * @returns The current NavigationType or null.
+ */
+export declare function useNavigationType(): NavigationType | null;

package/dist/src/react/hooks/useNextMatch.d.ts

@@ -0,0 +1,26 @@
+import { ComponentType } from 'react';
+import { Handler } from '../router';
+import { Matcher, Resolved } from '../../router/matcher';
+/**
+ * Options for the `useNextMatch` hook.
+ */
+export interface NextMatchOptions {
+    /**
+     * Optional matcher override. When omitted the hook reads
+     * from `MatcherContext`.
+     */
+    matcher?: Matcher<Handler>;
+}
+/**
+ * Returns a function that resolves a destination URL into a
+ * route match. When no route matches, a fallback `Resolved`
+ * is returned using the provided `notFound` component.
+ *
+ * Used internally by the Router to determine which component
+ * to render for an incoming navigation event.
+ *
+ * @param options - Optional matcher override.
+ * @returns A resolver function that takes a destination URL
+ *   and a not-found component, returning the resolved match.
+ */
+export declare function useNextMatch(options?: NextMatchOptions): (destination: string | null, notFound: ComponentType) => Resolved<Handler>;

package/dist/src/react/hooks/useParams.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns the dynamic route parameters extracted from the
+ * currently matched URL pattern. The keys correspond to the
+ * `:param` names defined in the route pattern, and the values
+ * are the matching URL segments.
+ *
+ * Must be used inside a `<Router>` component tree where
+ * `ParamsContext` is provided.
+ *
+ * @returns A record of parameter names to their string values.
+ *
+ * @example
+ * ```tsx
+ * // Route pattern: "/user/:id"
+ * // URL: "/user/42"
+ * const { id } = useParams() // id === "42"
+ * ```
+ */
+export declare function useParams(): Record<string, string>;

package/dist/src/react/hooks/usePathname.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns the current URL pathname from the Router's state.
+ * The value updates on every navigation and reflects the
+ * pathname of the committed destination URL.
+ *
+ * Useful for active link detection, conditional rendering
+ * based on the current route, or building breadcrumbs.
+ *
+ * Must be used inside a `<Router>` component tree where
+ * `PathnameContext` is provided.
+ *
+ * @returns The current pathname string (e.g. `"/user/42"`).
+ *
+ * @example
+ * ```tsx
+ * function Breadcrumb() {
+ *   const pathname = usePathname()
+ *
+ *   return <span>{pathname}</span>
+ * }
+ * ```
+ */
+export declare function usePathname(): string;