@studiolambda/router 0.1.1 → 2.0.0

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

@@ -153,12 +153,17 @@ export type RouteFactory = (path?: string) => RouteBuilder;
  * chaining, nested groups with path prefixing, redirects,
  * and all handler options (scroll, focusReset, formHandler).
  *
+ * After all routes are registered, static redirect targets
+ * are checked for cycles. Self-redirects and multi-hop loops
+ * throw an error at registration time.
+ *
  * 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.
+ * @throws When a static redirect cycle is detected.
  *
  * @example
  * ```tsx

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

@@ -1,8 +1,7 @@
 /**
  * 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.
+ * correctly. Returns `'/'` when the input is null or undefined.
  *
  * Used by the Router (to extract pathname from navigation
  * destination URLs), Link (for active link comparison), and

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

@@ -17,7 +17,8 @@ export interface UseBackResult {
     /**
      * Whether backward navigation is possible. Mirrors
      * `navigation.canGoBack` from the Navigation API.
-     * When false, calling `back()` will throw.
+     * Reactively updates when navigations change the
+     * history stack. When false, calling `back()` will throw.
      */
     readonly canGoBack: boolean;
 }
@@ -27,6 +28,11 @@ export interface UseBackResult {
  * `canGoBack` boolean that reflects whether the history
  * stack has a previous entry to traverse to.
  *
+ * The `canGoBack` value is kept in React state and
+ * updated via the `currententrychange` event, ensuring
+ * it stays reactive across navigations — including those
+ * triggered outside of React (e.g. browser back button).
+ *
  * Must be used inside a `<Router>` component tree.
  *
  * @returns An object with `back` and `canGoBack`.

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

@@ -17,7 +17,9 @@ export interface UseForwardResult {
     /**
      * Whether forward navigation is possible. Mirrors
      * `navigation.canGoForward` from the Navigation API.
-     * When false, calling `forward()` will throw.
+     * Reactively updates when navigations change the
+     * history stack. When false, calling `forward()` will
+     * throw.
      */
     readonly canGoForward: boolean;
 }
@@ -27,6 +29,11 @@ export interface UseForwardResult {
  * `canGoForward` boolean that reflects whether the history
  * stack has a next entry to traverse to.
  *
+ * The `canGoForward` value is kept in React state and
+ * updated via the `currententrychange` event, ensuring
+ * it stays reactive across navigations — including those
+ * triggered outside of React (e.g. browser forward button).
+ *
  * Must be used inside a `<Router>` component tree.
  *
  * @returns An object with `forward` and `canGoForward`.

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

@@ -6,5 +6,20 @@
  *
  * @returns A navigate function that accepts a URL string and
  *   optional `NavigationNavigateOptions`.
+ *
+ * @example
+ * ```tsx
+ * function LogoutButton() {
+ *   const navigate = useNavigate()
+ *
+ *   return (
+ *     <button onClick={function () {
+ *       navigate('/login', { history: 'replace' })
+ *     }}>
+ *       Log Out
+ *     </button>
+ *   )
+ * }
+ * ```
  */
 export declare function useNavigate(): (url: string, options?: NavigationNavigateOptions) => NavigationResult;

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

@@ -9,5 +9,15 @@
  *
  * @returns The Navigation object from the nearest provider.
  * @throws When used outside a NavigationContext provider.
+ *
+ * @example
+ * ```tsx
+ * function HistoryDebug() {
+ *   const navigation = useNavigation()
+ *   const entries = navigation.entries()
+ *
+ *   return <pre>{JSON.stringify(entries.map(e => e.url))}</pre>
+ * }
+ * ```
  */
 export declare function useNavigation(): Navigation;

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

@@ -39,5 +39,23 @@ export interface NavigationEventHandlers {
  * @param navigation - The Navigation object to subscribe to.
  * @param handlers - Callbacks for each navigation lifecycle
  *   event. All are optional.
+ *
+ * @example
+ * ```tsx
+ * function NavigationLogger() {
+ *   const navigation = useNavigation()
+ *
+ *   useNavigationEvents(navigation, {
+ *     onNavigateSuccess() {
+ *       console.log('navigation completed')
+ *     },
+ *     onNavigateError(error) {
+ *       console.error('navigation failed', error)
+ *     },
+ *   })
+ *
+ *   return null
+ * }
+ * ```
  */
 export declare function useNavigationEvents(navigation: Navigation, handlers: NavigationEventHandlers): void;

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

@@ -40,6 +40,15 @@ export interface PrecommitHandlerOptions {
  *   provides TransitionContext.
  * @throws When no transition tuple is provided and the
  *   hook is used outside a TransitionContext provider.
+ *
+ * @example
+ * ```tsx
+ * function CustomRouter() {
+ *   const transition = useTransition()
+ *   const { createHandler } = useNavigationHandlers(transition)
+ *   // use createHandler to build intercept handlers
+ * }
+ * ```
  */
 export declare function useNavigationHandlers(transition?: ReturnType<typeof useTransition>): {
     createPrecommitHandler: (options: PrecommitHandlerOptions) => ((controller: NavigationPrecommitController) => Promise<void>) | undefined;

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

@@ -8,6 +8,21 @@
  * Returns `null` before any navigation event has occurred
  * (i.e. on the initial render).
  *
+ * Must be used inside a `<Router>` component tree.
+ *
  * @returns The current AbortSignal or null.
+ * @throws When used outside a Router or NavigationSignalContext
+ *   provider.
+ *
+ * @example
+ * ```tsx
+ * function UserProfile({ id }: { id: string }) {
+ *   const signal = useNavigationSignal()
+ *
+ *   useEffect(function () {
+ *     fetch(`/api/user/${id}`, { signal })
+ *   }, [id, signal])
+ * }
+ * ```
  */
 export declare function useNavigationSignal(): AbortSignal | null;

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

@@ -7,6 +7,24 @@
  * Returns `null` before any navigation event has occurred
  * (i.e. on the initial render).
  *
+ * Must be used inside a `<Router>` component tree.
+ *
  * @returns The current NavigationType or null.
+ * @throws When used outside a Router or NavigationTypeContext
+ *   provider.
+ *
+ * @example
+ * ```tsx
+ * function PageTransition({ children }: { children: ReactNode }) {
+ *   const type = useNavigationType()
+ *   const isTraversal = type === 'traverse'
+ *
+ *   return (
+ *     <div className={isTraversal ? 'slide' : 'fade'}>
+ *       {children}
+ *     </div>
+ *   )
+ * }
+ * ```
  */
 export declare function useNavigationType(): NavigationType | null;

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

@@ -22,5 +22,16 @@ export interface NextMatchOptions {
  * @param options - Optional matcher override.
  * @returns A resolver function that takes a destination URL
  *   and a not-found component, returning the resolved match.
+ *
+ * @example
+ * ```tsx
+ * function CustomRouter() {
+ *   const resolve = useNextMatch()
+ *   const match = resolve(window.location.href, NotFound)
+ *   const Component = match.handler.component
+ *
+ *   return <Component />
+ * }
+ * ```
  */
 export declare function useNextMatch(options?: NextMatchOptions): (destination: string | null, notFound: ComponentType) => Resolved<Handler>;

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

@@ -8,6 +8,7 @@
  * `ParamsContext` is provided.
  *
  * @returns A record of parameter names to their string values.
+ * @throws When used outside a Router or ParamsContext provider.
  *
  * @example
  * ```tsx

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

@@ -10,6 +10,7 @@
  * `PathnameContext` is provided.
  *
  * @returns The current pathname string (e.g. `"/user/42"`).
+ * @throws When used outside a Router or PathnameContext provider.
  *
  * @example
  * ```tsx

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

@@ -10,12 +10,53 @@ export interface PrefetchOptions {
      */
     matcher?: Matcher<Handler>;
 }
+/**
+ * Clears the prefetch deduplication cache for a specific
+ * matcher instance. After clearing, subsequent calls to the
+ * prefetch function will re-execute handlers for pathnames
+ * that were previously skipped.
+ *
+ * Useful when cached data becomes stale — for example after
+ * a user logs out, a form submission invalidates server
+ * state, or a known data expiry occurs.
+ *
+ * When called without a matcher argument, has no effect.
+ * The cache is automatically garbage-collected when the
+ * matcher instance is no longer referenced, so explicit
+ * clearing is only needed for long-lived matchers.
+ *
+ * @param matcher - The matcher whose prefetch cache should
+ *   be cleared.
+ *
+ * @example
+ * ```tsx
+ * function LogoutButton() {
+ *   const navigate = useNavigate()
+ *   const matcher = use(MatcherContext)
+ *
+ *   return (
+ *     <button onClick={function () {
+ *       clearPrefetchCache(matcher)
+ *       navigate('/login', { history: 'replace' })
+ *     }}>
+ *       Log Out
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export declare function clearPrefetchCache(matcher: Matcher<Handler>): void;
 /**
  * Returns a function that triggers the prefetch logic for a
  * given URL by resolving it against the matcher and calling
  * the route's prefetch function. Used by the Link component
  * for hover and viewport prefetch strategies.
  *
+ * Each pathname is prefetched at most once per matcher
+ * instance per page session. Subsequent calls with the same
+ * pathname are no-ops, preventing thundering-herd problems
+ * when many Links point to the same destination.
+ *
  * Since prefetch triggered from Link happens outside of a
  * navigation event, a stub NavigationPrecommitController is
  * passed (the redirect capability is not meaningful here).
@@ -23,5 +64,21 @@ export interface PrefetchOptions {
  * @param options - Optional matcher override.
  * @returns A function that accepts a URL string and invokes
  *   the matched route's prefetch handler, if any.
+ *
+ * @example
+ * ```tsx
+ * function PrefetchOnHover({ href, children }: Props) {
+ *   const prefetch = usePrefetch()
+ *
+ *   return (
+ *     <a
+ *       href={href}
+ *       onMouseEnter={function () { prefetch(href) }}
+ *     >
+ *       {children}
+ *     </a>
+ *   )
+ * }
+ * ```
  */
 export declare function usePrefetch(options?: PrefetchOptions): (url: string) => void | Promise<void>;

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

@@ -22,11 +22,15 @@ export interface SetSearchParamsOptions {
  * `URLSearchParams` instance and a setter function to
  * update them via navigation.
  *
- * The getter reads from `navigation.currentEntry.url`
- * on each render, so it always reflects the committed
- * URL. The setter performs a navigation with the updated
- * search string, defaulting to `history: 'replace'` to
- * avoid polluting the history stack with parameter changes.
+ * The getter derives search params from `UrlContext` —
+ * React state managed by the Router — rather than reading
+ * the mutable `navigation.currentEntry` during render.
+ * This prevents subscription tearing in concurrent mode
+ * where two components could otherwise see different
+ * search params if a navigation fires mid-render.
+ *
+ * The setter preserves the existing hash fragment when
+ * updating search parameters.
  *
  * The React Compiler handles memoization of the setter,
  * so no manual `useCallback` is needed.

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

@@ -4,11 +4,12 @@ export * from './components/NotFound';
 export * from './components/Link';
 export * from './context/MatcherContext';
 export * from './context/TransitionContext';
-export * from './context/PropsContext';
+export * from './context/ParamsContext';
 export * from './context/NavigationContext';
 export * from './context/NavigationSignalContext';
 export * from './context/NavigationTypeContext';
 export * from './context/PathnameContext';
+export * from './context/UrlContext';
 export * from './hooks/useNavigation';
 export * from './hooks/useNavigate';
 export * from './hooks/useNavigationSignal';

package/dist/src/react/navigation/createMemoryNavigation.d.ts

@@ -17,13 +17,17 @@ export interface MemoryNavigationOptions {
  * browser Navigation API is unavailable.
  *
  * The returned object satisfies the subset of the `Navigation`
- * interface consumed by the Router component:
+ * interface consumed by the Router component and hooks:
  *
  * - `currentEntry.url` — returns the initial URL
  * - `addEventListener` / `removeEventListener` — no-ops
  *   (no events fire in a memory environment)
  * - `navigate()` — no-op that returns a NavigationResult
  *   with immediately-resolved promises
+ * - `back()` / `forward()` — no-ops that return a
+ *   NavigationResult with immediately-resolved promises
+ * - `traverseTo()` — no-op that returns a NavigationResult
+ * - `updateCurrentEntry()` — no-op
  * - `canGoBack` / `canGoForward` — always false
  * - `entries()` — returns a single-entry array
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiolambda/router",
-  "version": "0.1.1",
+  "version": "2.0.0",
   "license": "MIT",
   "keywords": [
     "router",

package/dist/matcher-CTRKcf7I.cjs

@@ -1,2 +0,0 @@
-function e(e){let t=e?.root??{children:new Map};function n(e,n){let r=e.split(`/`).filter(Boolean),i=t;for(let t of r){if(t.startsWith(`*`)){let n=t.length>1?t.slice(1):`*`;if(!i.wildcard)i.wildcard={children:new Map,name:n};else if(i.wildcard.name!==n)throw Error(`conflicting wildcard param name at "${e}": existing "*${i.wildcard.name}" vs new "*${n}"`);i=i.wildcard;continue}if(t.startsWith(`:`)){let n=t.slice(1);if(!i.child)i.child={children:new Map,name:n};else if(i.child.name!==n)throw Error(`conflicting dynamic param name at "${e}": existing ":${i.child.name}" vs new ":${n}"`);i=i.child;continue}let n=i.children.get(t);n||(n={children:new Map},i.children.set(t,n)),i=n}i.handler=n}function r(e){let n=e.split(`/`).filter(Boolean);function r(e,t,i){if(t===n.length)return e.handler===void 0?null:{handler:e.handler,params:i};let a=n[t],o=e.children.get(a);if(o){let e=r(o,t+1,i);if(e)return e}if(e.child&&e.child.name){let n=r(e.child,t+1,{...i,[e.child.name]:a});if(n)return n}if(e.wildcard&&e.wildcard.name&&e.wildcard.handler!==void 0){let r=n.slice(t).join(`/`);return{handler:e.wildcard.handler,params:{...i,[e.wildcard.name]:r}}}return null}return r(t,0,{})}return{register:n,match:r}}Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return e}});
-//# sourceMappingURL=matcher-CTRKcf7I.cjs.map

package/dist/src/react/context/PropsContext.d.ts

@@ -1,10 +0,0 @@
-/**
- * Provides the route parameters extracted from the matched URL
- * pattern as a string-keyed record. Defaults to an empty object
- * when no route has been matched yet.
- *
- * Consumed via the `useParams` hook. The Router component
- * updates this context on every successful navigation with
- * the newly extracted parameters.
- */
-export declare const ParamsContext: import('react').Context<Record<string, string>>;