@studiolambda/router 1.0.0 → 2.0.0

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,6 +10,42 @@ 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
@@ -28,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/index.d.ts

@@ -4,7 +4,7 @@ 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';

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": "1.0.0",
+  "version": "2.0.0",
   "license": "MIT",
   "keywords": [
     "router",

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>>;