@rangojs/router 0.0.0-experimental.0b82333f

package/dist/browser/react/use-handle.js

@@ -0,0 +1,144 @@
+"use client";
+import { useContext, useState, useEffect, useRef, useOptimistic, startTransition, } from "react";
+import { getCollectFn } from "../../handle.js";
+import { NavigationStoreContext } from "./context.js";
+/**
+ * SSR module-level state.
+ * Populated by initHandleDataSync before React renders.
+ * Used by useState initializer during SSR.
+ */
+let ssrHandleData = {};
+let ssrSegmentOrder = [];
+/**
+ * Filter segment IDs to only include routes and layouts.
+ * Excludes parallels (contain .@) and loaders (contain D followed by digit).
+ */
+function filterSegmentOrder(matched) {
+    return matched.filter((id) => {
+        if (id.includes(".@"))
+            return false;
+        if (/D\d+\./.test(id))
+            return false;
+        return true;
+    });
+}
+/**
+ * Resolve the collect function for a handle.
+ * Handle objects are plain { __brand, $$id } - collect is stored in the registry
+ * (populated when createHandle runs on the client).
+ */
+function resolveCollect(handle) {
+    // Look up collect from the registry (populated when the handle module is imported).
+    const registered = getCollectFn(handle.$$id);
+    if (registered) {
+        return registered;
+    }
+    // Fall back to default flat collect with a dev warning.
+    if (process.env.NODE_ENV !== "production") {
+        console.warn(`[rsc-router] Handle "${handle.$$id}" was passed as a prop but its collect ` +
+            `function could not be resolved. Falling back to flat array. ` +
+            `Import the handle module in a client component to register its collect function.`);
+    }
+    return ((segments) => segments.flat());
+}
+/**
+ * Collect handle data from segments and transform to final value.
+ */
+function collectHandle(handle, data, segmentOrder) {
+    const collect = resolveCollect(handle);
+    const segmentData = data[handle.$$id];
+    if (!segmentData) {
+        return collect([]);
+    }
+    // Build array of segment arrays in parent -> child order
+    const segmentArrays = [];
+    for (const segmentId of segmentOrder) {
+        const entries = segmentData[segmentId];
+        if (entries && entries.length > 0) {
+            segmentArrays.push(entries);
+        }
+    }
+    // Call collect once with all segment data
+    return collect(segmentArrays);
+}
+/**
+ * Shallow equality check for selector results.
+ */
+function shallowEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" ||
+        a === null ||
+        typeof b !== "object" ||
+        b === null) {
+        return false;
+    }
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const key of keysA) {
+        if (!Object.hasOwn(b, key) ||
+            !Object.is(a[key], b[key])) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Initialize handle data synchronously for SSR.
+ * Called before rendering to populate state for useState initializer.
+ *
+ * @param data - Handle data from RSC payload
+ * @param matched - Segment order for reduction
+ */
+export function initHandleDataSync(data, matched) {
+    ssrHandleData = data;
+    ssrSegmentOrder = filterSegmentOrder(matched ?? []);
+}
+export function useHandle(handle, selector) {
+    const ctx = useContext(NavigationStoreContext);
+    // Initial state from SSR module state or event controller
+    const [value, setValue] = useState(() => {
+        // During SSR, use module-level state
+        if (typeof document === "undefined" || !ctx) {
+            const collected = collectHandle(handle, ssrHandleData, ssrSegmentOrder);
+            return selector ? selector(collected) : collected;
+        }
+        // On client, use event controller state
+        const state = ctx.eventController.getHandleState();
+        const collected = collectHandle(handle, state.data, state.segmentOrder);
+        return selector ? selector(collected) : collected;
+    });
+    const [optimisticValue, setOptimisticValue] = useOptimistic(value);
+    // Track previous value for shallow comparison
+    const prevValueRef = useRef(value);
+    prevValueRef.current = value;
+    // Memoize selector ref
+    const selectorRef = useRef(selector);
+    selectorRef.current = selector;
+    // Subscribe to handle data changes (client only)
+    useEffect(() => {
+        if (!ctx)
+            return;
+        return ctx.eventController.subscribeToHandles(() => {
+            const state = ctx.eventController.getHandleState();
+            const isAction = ctx.eventController.getState().inflightActions.length > 0;
+            const collected = collectHandle(handle, state.data, state.segmentOrder);
+            const nextValue = selectorRef.current
+                ? selectorRef.current(collected)
+                : collected;
+            if (!shallowEqual(nextValue, prevValueRef.current)) {
+                prevValueRef.current = nextValue;
+                startTransition(() => {
+                    // Skip optimistic update during actions to prevent Suspense fallback
+                    if (!isAction)
+                        setOptimisticValue(nextValue);
+                    setValue(nextValue);
+                });
+            }
+        });
+    }, [handle]);
+    return optimisticValue;
+}
+//# sourceMappingURL=use-handle.js.map

package/dist/browser/react/use-handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-handle.js","sourceRoot":"","sources":["../../../src/browser/react/use-handle.ts"],"names":[],"mappings":"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"}

package/dist/browser/react/use-href.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Client-side hook for mount-aware URL resolution.
+ *
+ * Returns an href function that automatically prepends the current
+ * include() mount prefix. Inside an include("/shop", ...) scope,
+ * the returned function resolves local paths relative to /shop.
+ *
+ * For absolute paths (outside the current mount), use the bare
+ * href() function directly instead.
+ *
+ * @returns A function that prepends the mount prefix to paths
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useHref, href } from "@rangojs/router/client";
+ *
+ * // Inside include("/shop", shopPatterns)
+ * function ShopNav() {
+ *   const href = useHref();
+ *
+ *   return (
+ *     <>
+ *       {// Local paths - auto-prefixed with /shop}
+ *       <Link to={href("/cart")}>Cart</Link>
+ *       <Link to={href("/product/widget")}>Widget</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useHref(): (path: `/${string}`) => string;
+//# sourceMappingURL=use-href.d.ts.map

package/dist/browser/react/use-href.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-href.d.ts","sourceRoot":"","sources":["../../../src/browser/react/use-href.tsx"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,MAAM,EAAE,KAAK,MAAM,CAGxD"}

package/dist/browser/react/use-href.js

@@ -0,0 +1,39 @@
+"use client";
+import { href } from "../../href-client.js";
+import { useMount } from "./use-mount.js";
+/**
+ * Client-side hook for mount-aware URL resolution.
+ *
+ * Returns an href function that automatically prepends the current
+ * include() mount prefix. Inside an include("/shop", ...) scope,
+ * the returned function resolves local paths relative to /shop.
+ *
+ * For absolute paths (outside the current mount), use the bare
+ * href() function directly instead.
+ *
+ * @returns A function that prepends the mount prefix to paths
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useHref, href } from "@rangojs/router/client";
+ *
+ * // Inside include("/shop", shopPatterns)
+ * function ShopNav() {
+ *   const href = useHref();
+ *
+ *   return (
+ *     <>
+ *       {// Local paths - auto-prefixed with /shop}
+ *       <Link to={href("/cart")}>Cart</Link>
+ *       <Link to={href("/product/widget")}>Widget</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useHref() {
+    const mount = useMount();
+    return (path) => href(path, mount);
+}
+//# sourceMappingURL=use-href.js.map

package/dist/browser/react/use-href.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-href.js","sourceRoot":"","sources":["../../../src/browser/react/use-href.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,IAAI,EAAmB,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,OAAO,CAAC,IAAkB,EAAE,EAAE,CAAC,IAAI,CAAC,IAAkB,EAAE,KAAK,CAAC,CAAC;AACjE,CAAC"}

package/dist/browser/react/use-link-status.d.ts

@@ -0,0 +1,37 @@
+import { type Context } from "react";
+/**
+ * Context for Link component to provide its destination URL
+ * Used by useLinkStatus to determine if this specific link is pending
+ */
+export declare const LinkContext: Context<string | null>;
+/**
+ * Link status returned by useLinkStatus hook
+ */
+export interface LinkStatus {
+    /** Whether navigation to this link's destination is in progress */
+    pending: boolean;
+}
+/**
+ * Hook to track the pending state of a Link component
+ *
+ * Must be used inside a Link component. Returns `{ pending: true }`
+ * when navigation to this link's destination is in progress.
+ *
+ * Useful for showing inline loading indicators on individual links.
+ *
+ * @example
+ * ```tsx
+ * function LoadingIndicator() {
+ *   const { pending } = useLinkStatus();
+ *   return pending ? <Spinner /> : null;
+ * }
+ *
+ * // In your component:
+ * <Link to="/dashboard">
+ *   Dashboard
+ *   <LoadingIndicator />
+ * </Link>
+ * ```
+ */
+export declare function useLinkStatus(): LinkStatus;
+//# sourceMappingURL=use-link-status.d.ts.map

package/dist/browser/react/use-link-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-link-status.d.ts","sourceRoot":"","sources":["../../../src/browser/react/use-link-status.ts"],"names":[],"mappings":"AAEA,OAAO,EAQL,KAAK,OAAO,EACb,MAAM,OAAO,CAAC;AAGf;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAsC,CAAC;AAEtF;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;CAClB;AA8BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAuD1C"}

package/dist/browser/react/use-link-status.js

@@ -0,0 +1,99 @@
+"use client";
+import { createContext, useContext, useState, useEffect, useRef, useOptimistic, startTransition, } from "react";
+import { NavigationStoreContext } from "./context.js";
+/**
+ * Context for Link component to provide its destination URL
+ * Used by useLinkStatus to determine if this specific link is pending
+ */
+export const LinkContext = createContext(null);
+/**
+ * Normalize URL for comparison
+ * Handles relative URLs and ensures consistent format
+ */
+function normalizeUrl(url, origin) {
+    try {
+        const parsed = new URL(url, origin);
+        // Return pathname + search + hash for comparison
+        return parsed.pathname + parsed.search + parsed.hash;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Check if this link's destination matches the pending navigation URL
+ */
+function isPendingFor(linkTo, pendingUrl, origin) {
+    if (linkTo === null || pendingUrl === null) {
+        return false;
+    }
+    return normalizeUrl(pendingUrl, origin) === normalizeUrl(linkTo, origin);
+}
+/**
+ * Hook to track the pending state of a Link component
+ *
+ * Must be used inside a Link component. Returns `{ pending: true }`
+ * when navigation to this link's destination is in progress.
+ *
+ * Useful for showing inline loading indicators on individual links.
+ *
+ * @example
+ * ```tsx
+ * function LoadingIndicator() {
+ *   const { pending } = useLinkStatus();
+ *   return pending ? <Spinner /> : null;
+ * }
+ *
+ * // In your component:
+ * <Link to="/dashboard">
+ *   Dashboard
+ *   <LoadingIndicator />
+ * </Link>
+ * ```
+ */
+export function useLinkStatus() {
+    const linkTo = useContext(LinkContext);
+    const ctx = useContext(NavigationStoreContext);
+    // Get origin for URL normalization (stable across renders)
+    const origin = typeof window !== "undefined"
+        ? window.location.origin
+        : "http://localhost";
+    // Base state for useOptimistic
+    const [basePending, setBasePending] = useState(() => {
+        if (!ctx || linkTo === null) {
+            return false;
+        }
+        const state = ctx.eventController.getState();
+        return isPendingFor(linkTo, state.pendingUrl, origin);
+    });
+    const prevPending = useRef(basePending);
+    // useOptimistic allows immediate updates during transitions
+    const [pending, setOptimisticPending] = useOptimistic(basePending);
+    useEffect(() => {
+        if (!ctx || linkTo === null) {
+            return;
+        }
+        // Subscribe to navigation state changes
+        return ctx.eventController.subscribe(() => {
+            const state = ctx.eventController.getState();
+            const isPending = isPendingFor(linkTo, state.pendingUrl, origin);
+            if (isPending !== prevPending.current) {
+                prevPending.current = isPending;
+                // Use optimistic update for immediate feedback during navigation
+                if (state.state !== "idle") {
+                    startTransition(() => {
+                        setOptimisticPending(isPending);
+                    });
+                }
+                // Always update base state
+                setBasePending(isPending);
+            }
+        });
+    }, [linkTo, origin]);
+    // If not inside a Link, return not pending
+    if (linkTo === null) {
+        return { pending: false };
+    }
+    return { pending };
+}
+//# sourceMappingURL=use-link-status.js.map

package/dist/browser/react/use-link-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-link-status.js","sourceRoot":"","sources":["../../../src/browser/react/use-link-status.ts"],"names":[],"mappings":"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"}

package/dist/browser/react/use-mount.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Returns the current include() mount path.
+ *
+ * Inside `include("/articles", blogPatterns)`, returns "/articles".
+ * For nested includes, returns the nearest mount path.
+ * At root level (no include), returns "/".
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useMount, href } from "@rangojs/router/client";
+ *
+ * function BlogNav({ slug }: { slug: string }) {
+ *   const mount = useMount(); // "/articles"
+ *   return (
+ *     <>
+ *       <Link to={href("/", mount)}>Blog Home</Link>
+ *       <Link to={href(`/${slug}`, mount)}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useMount(): string;
+//# sourceMappingURL=use-mount.d.ts.map

package/dist/browser/react/use-mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-mount.d.ts","sourceRoot":"","sources":["../../../src/browser/react/use-mount.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAEjC"}

package/dist/browser/react/use-mount.js

@@ -0,0 +1,30 @@
+"use client";
+import { useContext } from "react";
+import { MountContext } from "./mount-context.js";
+/**
+ * Returns the current include() mount path.
+ *
+ * Inside `include("/articles", blogPatterns)`, returns "/articles".
+ * For nested includes, returns the nearest mount path.
+ * At root level (no include), returns "/".
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useMount, href } from "@rangojs/router/client";
+ *
+ * function BlogNav({ slug }: { slug: string }) {
+ *   const mount = useMount(); // "/articles"
+ *   return (
+ *     <>
+ *       <Link to={href("/", mount)}>Blog Home</Link>
+ *       <Link to={href(`/${slug}`, mount)}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useMount() {
+    return useContext(MountContext);
+}
+//# sourceMappingURL=use-mount.js.map

package/dist/browser/react/use-mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-mount.js","sourceRoot":"","sources":["../../../src/browser/react/use-mount.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,UAAU,CAAC,YAAY,CAAC,CAAC;AAClC,CAAC"}

package/dist/browser/react/use-navigation.d.ts

@@ -0,0 +1,27 @@
+import type { PublicNavigationState, NavigateOptions } from "../types.js";
+/**
+ * Navigation methods returned by useNavigation
+ */
+export interface NavigationMethods {
+    navigate: (url: string, options?: NavigateOptions) => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Full value returned when no selector is provided
+ */
+export type NavigationValue = PublicNavigationState & NavigationMethods;
+/**
+ * Hook to access navigation state with optional selector for performance
+ *
+ * Uses the event controller for reactive state management.
+ * State is derived from source of truth (currentNavigation, inflightActions).
+ *
+ * @example
+ * ```tsx
+ * const state = useNavigation(nav => nav.state);
+ * const isLoading = useNavigation(nav => nav.state === 'loading');
+ * ```
+ */
+export declare function useNavigation(): NavigationValue;
+export declare function useNavigation<T>(selector: (state: PublicNavigationState) => T): T;
+//# sourceMappingURL=use-navigation.d.ts.map

package/dist/browser/react/use-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-navigation.d.ts","sourceRoot":"","sources":["../../../src/browser/react/use-navigation.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAuC1E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,qBAAqB,GAAG,iBAAiB,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,IAAI,eAAe,CAAC;AACjD,wBAAgB,aAAa,CAAC,CAAC,EAC7B,QAAQ,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,CAAC,GAC5C,CAAC,CAAC"}

package/dist/browser/react/use-navigation.js

@@ -0,0 +1,87 @@
+"use client";
+import { useContext, useState, useEffect, useOptimistic, startTransition, useRef, } from "react";
+import { NavigationStoreContext } from "./context.js";
+/**
+ * Shallow equality check for selector results
+ */
+function shallowEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" ||
+        a === null ||
+        typeof b !== "object" ||
+        b === null) {
+        return false;
+    }
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const key of keysA) {
+        if (!Object.hasOwn(b, key) ||
+            !Object.is(a[key], b[key])) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Convert derived state to public version (strips inflightActions)
+ */
+function toPublicState(state) {
+    const { inflightActions: _, ...publicState } = state;
+    return publicState;
+}
+export function useNavigation(selector) {
+    const ctx = useContext(NavigationStoreContext);
+    if (!ctx) {
+        throw new Error("useNavigation must be used within NavigationStoreContext.Provider");
+    }
+    // Base state for useOptimistic
+    const [baseValue, setBaseValue] = useState(() => {
+        const publicState = toPublicState(ctx.eventController.getState());
+        return selector ? selector(publicState) : publicState;
+    });
+    const prevState = useRef(baseValue);
+    // useOptimistic allows immediate updates during transitions/actions
+    const [value, setOptimisticValue] = useOptimistic(baseValue);
+    // Store selector in a ref to avoid re-subscribing when an inline
+    // function is passed (its identity changes every render).
+    const selectorRef = useRef(selector);
+    selectorRef.current = selector;
+    // Subscribe to event controller state changes (only runs on client)
+    useEffect(() => {
+        // Subscribe to updates from event controller
+        return ctx.eventController.subscribe(() => {
+            const currentState = ctx.eventController.getState();
+            const publicState = toPublicState(currentState);
+            const nextSelected = selectorRef.current
+                ? selectorRef.current(publicState)
+                : publicState;
+            // Check if selected value has changed
+            if (!shallowEqual(nextSelected, prevState.current)) {
+                prevState.current = nextSelected;
+                // Check if any actions are in progress for optimistic updates
+                const hasInflightActions = ctx.eventController.getInflightActions().size > 0;
+                if (hasInflightActions || publicState.state !== "idle") {
+                    // Use optimistic update for immediate feedback during transitions
+                    startTransition(() => {
+                        setOptimisticValue(nextSelected);
+                    });
+                }
+                // Always update base state so UI reflects current state
+                setBaseValue(nextSelected);
+            }
+        });
+    }, []);
+    // If no selector, include navigation methods
+    if (!selector) {
+        return {
+            ...value,
+            navigate: ctx.navigate,
+            refresh: ctx.refresh,
+        };
+    }
+    return value;
+}
+//# sourceMappingURL=use-navigation.js.map

package/dist/browser/react/use-navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-navigation.js","sourceRoot":"","sources":["../../../src/browser/react/use-navigation.ts"],"names":[],"mappings":"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"}

package/dist/browser/react/use-segments.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Segments state returned by useSegments hook
+ */
+export interface SegmentsState {
+    /** URL path segments (e.g., /shop/products/123 → ["shop", "products", "123"]) */
+    path: readonly string[];
+    /** Matched segment IDs in order (layouts and routes only, e.g., ["L0", "L0L1", "L0L1R0"]) */
+    segmentIds: readonly string[];
+    /** Current URL location */
+    location: URL;
+}
+/**
+ * Initialize segments data synchronously for SSR.
+ * Called before rendering to populate state for useState initializer.
+ *
+ * @param matched - Segment order from RSC metadata
+ * @param pathname - Current pathname
+ */
+export declare function initSegmentsSync(matched?: string[], pathname?: string): void;
+/**
+ * Hook to access current route segments with optional selector for performance
+ *
+ * Provides information about the current URL path and matched route segments.
+ * Uses the event controller for reactive state management.
+ *
+ * @example
+ * ```tsx
+ * // Get full segments state
+ * const { path, segmentIds, location } = useSegments();
+ *
+ * // Use selector for specific values (better performance)
+ * const path = useSegments(s => s.path);
+ * const isShopRoute = useSegments(s => s.path[0] === "shop");
+ * ```
+ */
+export declare function useSegments(): SegmentsState;
+export declare function useSegments<T>(selector: (state: SegmentsState) => T): T;
+//# sourceMappingURL=use-segments.d.ts.map

package/dist/browser/react/use-segments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-segments.d.ts","sourceRoot":"","sources":["../../../src/browser/react/use-segments.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,6FAA6F;IAC7F,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,2BAA2B;IAC3B,QAAQ,EAAE,GAAG,CAAC;CACf;AAsBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAG5E;AA+DD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,IAAI,aAAa,CAAC;AAC7C,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,CAAC,GAAG,CAAC,CAAC"}