@sigx/lynx-navigation 0.4.0 → 0.4.1

package/dist/components/Tabs.js

@@ -0,0 +1,168 @@
+import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+/**
+ * `<Tabs>` — Lynx tab navigator.
+ *
+ * Usage:
+ *
+ * ```tsx
+ * <NavigationRoot routes={routes} initialRoute="root">
+ *   <Stack />
+ * </NavigationRoot>
+ *
+ * // The route "root" component renders:
+ * <Tabs initialTab="feed">
+ *   <Tabs.Screen name="feed" icon={<FeedIcon />} label="Feed">
+ *     <Stack initialRoute="feedHome" />
+ *   </Tabs.Screen>
+ *   <Tabs.Screen name="me" icon={<MeIcon />} label="Profile">
+ *     <Stack initialRoute="profileHome" />
+ *   </Tabs.Screen>
+ *   <TabBar />
+ * </Tabs>
+ * ```
+ *
+ * Tab bodies stay mounted across switches (the inactive ones render with
+ * `display: 'none'`), so each tab's nested `<Stack>` keeps its history when
+ * the user flips back to it. The active tab is reactive via `useTabs()`.
+ *
+ * Per-tab stacks: each `<Tabs.Screen>` can host a `<Stack initialRoute="…">`
+ * which mints its own navigator. `useNav()` inside that subtree resolves to
+ * the tab's stack, so `nav.push('card-route', …)` stays inside the tab.
+ * Routes presented as `modal` / `fullScreen` / `transparent-modal` escalate
+ * up `nav.parent` to the root navigator automatically — they overlay the
+ * tabs UI (TabBar included) and dismiss back into the originating tab.
+ */
+import { component, compound, defineInjectable, defineProvide, onUnmounted, signal, untrack, } from '@sigx/lynx';
+/**
+ * Access the enclosing Tabs navigator. Throws when called outside `<Tabs>`.
+ */
+export const useTabs = defineInjectable(() => {
+    throw new Error('[lynx-navigation] useTabs() called outside of a <Tabs> component.');
+});
+const useTabsRegistrar = defineInjectable(() => {
+    throw new Error('[lynx-navigation] <Tabs.Screen> rendered outside a <Tabs> component.');
+});
+/**
+ * @internal
+ * Provided by each `<Tabs.Screen>` so a nested `<Stack initialRoute>` can
+ * discover *which* tab it's hosted by, and gate its focus state on that
+ * tab being active. Throws when called outside a `<Tabs.Screen>` body so
+ * the gate degrades to "always active" via the caller's try/catch.
+ */
+export const useTabScreenName = defineInjectable(() => {
+    throw new Error('[lynx-navigation] useTabScreenName() called outside a <Tabs.Screen> body.');
+});
+const _Tabs = component(({ props, slots }) => {
+    // Tabs are stored as a deeply-reactive proxy signal so `tabs` consumers
+    // re-render when registration changes. `activeSignal` uses the wrapped
+    // `{value}` pattern so we can write a `string | null` without the
+    // proxy treating the inner string as an object.
+    const tabs = signal([]);
+    const activeSignal = signal({
+        value: props.initialTab ?? null,
+    });
+    const registrar = {
+        register(info) {
+            // Wrap in untrack so registration writes inside `<Tabs.Screen>`'s
+            // setup phase don't notify the same setup effect that issued them
+            // — sigx's setup runs in a tracked scope by default.
+            untrack(() => {
+                const idx = tabs.findIndex((t) => t.name === info.name);
+                if (idx === -1)
+                    tabs.push(info);
+                else
+                    tabs[idx] = info;
+                if (activeSignal.value === null) {
+                    activeSignal.value = info.name;
+                }
+            });
+        },
+        unregister(name) {
+            untrack(() => {
+                const idx = tabs.findIndex((t) => t.name === name);
+                if (idx !== -1)
+                    tabs.splice(idx, 1);
+                if (activeSignal.value === name) {
+                    activeSignal.value = tabs[0]?.name ?? null;
+                }
+            });
+        },
+        tabs,
+        activeSignal,
+    };
+    const nav = {
+        get active() {
+            // Empty-tabs state is rare in practice (no <Tabs.Screen> yet) but
+            // possible during initial render; expose '' rather than null so
+            // consumers can compare strings without narrowing.
+            return activeSignal.value ?? '';
+        },
+        setActive(name) {
+            // Silently ignore unknown names rather than writing them and
+            // hiding every tab body. Surfacing as a no-op gives consumers a
+            // predictable failure mode for typos / dynamic name sources.
+            if (!tabs.some((t) => t.name === name))
+                return;
+            activeSignal.value = name;
+        },
+        get tabs() {
+            return tabs;
+        },
+    };
+    defineProvide(useTabs, () => nav);
+    defineProvide(useTabsRegistrar, () => registrar);
+    return () => slots.default?.();
+});
+const TabsScreen = component(({ props, slots }) => {
+    const registrar = useTabsRegistrar();
+    // Capture `name` once at setup. Props is reactive in sigx, but using a
+    // changing `name` for an already-registered screen would be ambiguous
+    // (rename vs re-register?) — pin it and require callers to remount on
+    // identity change. This matches React Navigation's contract.
+    const name = props.name;
+    registrar.register({
+        name,
+        icon: props.icon,
+        label: props.label,
+        accessibilityLabel: props.accessibilityLabel,
+    });
+    onUnmounted(() => registrar.unregister(name));
+    // Expose this screen's tab name so a nested `<Stack initialRoute>` body
+    // can gate its locally-focused state on `tabs.active === name`.
+    defineProvide(useTabScreenName, () => name);
+    return () => {
+        // `display: none` keeps the body mounted so per-tab state survives
+        // tab switches. Read activeSignal here so re-activating triggers a
+        // re-render with display restored.
+        //
+        // Flex-fill long-form (`flex-grow/shrink/basis`) instead of
+        // `height: '100%'`. The percentage form only resolves against an
+        // explicit parent height, which means consumers had to wrap us
+        // in a `flexFill + height: '100%'` view to make us visible — and
+        // every Lynx app got that wrong (myself included) until we hit
+        // it on the showcase. With flex-fill we just take whatever space
+        // our parent flex container gives us; the parent only needs to
+        // be a flex column with a known height (e.g. SafeAreaView, which
+        // now defaults to that).
+        const active = registrar.activeSignal.value === name;
+        return (_jsx("view", { style: {
+                display: active ? 'flex' : 'none',
+                flexDirection: 'column',
+                width: '100%',
+                flexGrow: 1,
+                flexShrink: 1,
+                flexBasis: 0,
+                minHeight: 0,
+            }, children: slots.default?.() }));
+    };
+});
+/**
+ * Compound export. `Tabs` is the parent component; `Tabs.Screen` registers
+ * an individual tab. Matches the `Screen` / `Screen.Header` shape used
+ * elsewhere in this package and the daisyui `Modal` / `Modal.Header`
+ * convention.
+ */
+export const Tabs = compound(_Tabs, {
+    Screen: TabsScreen,
+});
+//# sourceMappingURL=Tabs.js.map

package/dist/components/Tabs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tabs.js","sourceRoot":"","sources":["../../src/components/Tabs.tsx"],"names":[],"mappings":"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"}

package/dist/define-routes.d.ts

@@ -1,4 +1,4 @@
-import type { RouteMap } from './types';
+import type { RouteMap } from './types.js';
 /**
  * Define a typed route registry.
  *

package/dist/define-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-routes.d.ts","sourceRoot":"","sources":["../src/define-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEnE"}
+{"version":3,"file":"define-routes.d.ts","sourceRoot":"","sources":["../src/define-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEnE"}

package/{src/define-routes.d.ts → dist/define-routes.js}

@@ -1,4 +1,3 @@
-import type { RouteMap } from './types';
 /**
  * Define a typed route registry.
  *
@@ -27,4 +26,7 @@ import type { RouteMap } from './types';
  * }
  * ```
  */
-export declare function defineRoutes<const T extends RouteMap>(routes: T): T;
+export function defineRoutes(routes) {
+    return routes;
+}
+//# sourceMappingURL=define-routes.js.map

package/dist/define-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-routes.js","sourceRoot":"","sources":["../src/define-routes.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,YAAY,CAA2B,MAAS;IAC5D,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/hooks/use-focus.js

@@ -0,0 +1,87 @@
+import { computed, effect, onUnmounted, untrack, } from '@sigx/lynx';
+import { useNav } from './use-nav.js';
+import { useCurrentEntry } from './use-nav-internal.js';
+/**
+ * Reactive "is this screen the focused entry?" signal.
+ *
+ * Must be called from inside a component rendered as a route by `<Stack>` (or
+ * any other navigator that uses `<EntryScope>`); throws otherwise. The
+ * returned `Computed` reads `nav.current.key` and compares it to the entry
+ * the calling screen was mounted for, so any nav mutation that changes the
+ * top entry flips the value.
+ *
+ * Note: screens stay mounted when something is pushed on top of them — they
+ * just lose focus. Pop the new top off and they regain focus.
+ *
+ * @example
+ * ```tsx
+ * const Profile = component(() => {
+ *     const isFocused = useIsFocused();
+ *     return () => <text>{isFocused.value ? 'visible' : 'hidden'}</text>;
+ * });
+ * ```
+ */
+export function useIsFocused() {
+    const nav = useNav();
+    // Capture the entry's key once at setup. The entry object provided
+    // through `defineProvide` may carry reactive dependencies; we only care
+    // about the immutable key of the entry this screen was mounted for.
+    const myKey = useCurrentEntry().key;
+    // AND in `nav.isLocallyFocused` so a screen in a nested stack (e.g. a
+    // per-tab `<Stack>`) reports unfocused when its enclosing tab is
+    // inactive, or when a modal on the root nav covers everything — even
+    // though it's still the top of its own (paused) stack. Root nav's
+    // `isLocallyFocused` is permanently true, so this reduces to the
+    // previous behavior for un-nested apps.
+    return computed(() => nav.current.key === myKey && nav.isLocallyFocused);
+}
+/**
+ * Run `cb` whenever this screen gains focus; run the returned cleanup when it
+ * loses focus or unmounts. Mirrors React Navigation's `useFocusEffect`.
+ *
+ * Lifecycle:
+ *  - cb runs immediately if the screen is already focused at mount.
+ *  - When the screen loses focus (something pushed on top), cleanup runs.
+ *  - When focus returns (the cover is popped), `cb` runs again — yielding a
+ *    fresh cleanup for the next blur.
+ *  - On unmount, cleanup runs once if still focused.
+ *
+ * Common uses: subscribe to a data source while visible, track an analytics
+ * "screen view" event, start/stop a polling loop.
+ *
+ * @example
+ * ```tsx
+ * useFocusEffect(() => {
+ *     const id = setInterval(refresh, 5000);
+ *     return () => clearInterval(id);
+ * });
+ * ```
+ */
+export function useFocusEffect(cb) {
+    const isFocused = useIsFocused();
+    let cleanup;
+    const runner = effect(() => {
+        const focused = isFocused.value;
+        // Always tear down any previous focus session before starting a new
+        // one (or before going dormant on blur). Wrap `cb` in `untrack` so
+        // signals read inside the user-provided callback can't retrigger the
+        // outer effect and stack subscriptions.
+        if (typeof cleanup === 'function') {
+            const fn = cleanup;
+            cleanup = undefined;
+            fn();
+        }
+        if (focused) {
+            cleanup = untrack(() => cb());
+        }
+    });
+    onUnmounted(() => {
+        if (typeof cleanup === 'function') {
+            const fn = cleanup;
+            cleanup = undefined;
+            fn();
+        }
+        runner.stop();
+    });
+}
+//# sourceMappingURL=use-focus.js.map

package/dist/hooks/use-focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-focus.js","sourceRoot":"","sources":["../../src/hooks/use-focus.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,QAAQ,EACR,MAAM,EACN,WAAW,EACX,OAAO,GAEV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY;IACxB,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,mEAAmE;IACnE,wEAAwE;IACxE,oEAAoE;IACpE,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC,GAAG,CAAC;IACpC,sEAAsE;IACtE,iEAAiE;IACjE,qEAAqE;IACrE,kEAAkE;IAClE,iEAAiE;IACjE,wCAAwC;IACxC,OAAO,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,KAAK,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAAC,EAA6B;IACxD,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,IAAI,OAA4B,CAAC;IACjC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,EAAE;QACvB,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC;QAChC,oEAAoE;QACpE,mEAAmE;QACnE,qEAAqE;QACrE,wCAAwC;QACxC,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;YAChC,MAAM,EAAE,GAAG,OAAO,CAAC;YACnB,OAAO,GAAG,SAAS,CAAC;YACpB,EAAE,EAAE,CAAC;QACT,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACV,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAClC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,WAAW,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;YAChC,MAAM,EAAE,GAAG,OAAO,CAAC;YACnB,OAAO,GAAG,SAAS,CAAC;YACpB,EAAE,EAAE,CAAC;QACT,CAAC;QACD,MAAM,CAAC,IAAI,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/hooks/use-hardware-back.js

@@ -0,0 +1,84 @@
+import { onMounted } from '@sigx/lynx';
+import { BackHandler } from '@sigx/lynx-linking';
+import { useNav } from './use-nav.js';
+/**
+ * Wire the Android hardware back button to the active navigator.
+ *
+ * Listens for `hardwareBackPress` events from `@sigx/lynx-linking`'s
+ * `BackHandler` (which the native side dispatches from
+ * `MainActivity.onBackPressed`). On press the handler walks to the
+ * deepest currently-focused navigator (per-tab `<Stack>`s register with
+ * their parent), then walks back up the `parent` chain looking for the
+ * first nav that `canGoBack`:
+ *
+ *   - If any nav in the chain can go back → `nav.pop()` on that nav.
+ *   - Otherwise → `BackHandler.exitApp()` (Android: `moveTaskToBack(true)`,
+ *     keeps the bundle warm; iOS: rejects, since iOS doesn't permit
+ *     programmatic termination).
+ *
+ * The traversal means you only need to call this once at the root — a
+ * back press from inside a tab pops that tab's nested stack first, only
+ * exiting the app once every level is at its base entry.
+ *
+ * Call this once in any component under `<NavigationRoot>` (typically a
+ * thin wrapper sibling to `<Stack />`). iOS doesn't fire the event so the
+ * hook is a no-op there.
+ *
+ * @example
+ * ```tsx
+ * const BackHandlerWiring = component(() => {
+ *     useHardwareBack();
+ *     return () => null;
+ * });
+ *
+ * <NavigationRoot routes={routes}>
+ *     <BackHandlerWiring />
+ *     <Stack />
+ * </NavigationRoot>
+ * ```
+ */
+export function useHardwareBack() {
+    const nav = useNav();
+    onMounted(() => {
+        const sub = BackHandler.addEventListener(() => {
+            // Walk down to the deepest focused nav. Per-tab `<Stack>`s
+            // register themselves via `parent._children.add(nav)`; only one
+            // child per level is `isLocallyFocused` at a time, so the
+            // traversal is unambiguous. Falls back to the starting nav if
+            // no nested stacks are wired up.
+            let active = nav;
+            // Loop instead of recursion so a deeply-nested tree doesn't blow
+            // the stack on a synchronous back press.
+            outer: while (active._children.size > 0) {
+                for (const child of active._children) {
+                    if (child.isLocallyFocused) {
+                        active = child;
+                        continue outer;
+                    }
+                }
+                // No focused child at this level — stop drilling.
+                break;
+            }
+            // Walk back up the chain looking for the first nav that has
+            // something to pop. This is what makes "back press in trips
+            // tab with empty inner stack" fall through to root (which might
+            // have a modal on top) before exiting.
+            let cur = active;
+            while (cur) {
+                if (cur.canGoBack) {
+                    cur.pop();
+                    return true;
+                }
+                cur = cur.parent;
+            }
+            // At the root with nothing to pop — leave the app. Promise is
+            // fire-and-forget; we don't await because we want the back
+            // press to feel instant (Android starts the move-to-back
+            // transition immediately).
+            void BackHandler.exitApp();
+            return true;
+        });
+        return () => sub.remove();
+    });
+}
+//# sourceMappingURL=use-hardware-back.js.map

package/dist/hooks/use-hardware-back.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-hardware-back.js","sourceRoot":"","sources":["../../src/hooks/use-hardware-back.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAY,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,eAAe;IAC3B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,GAAG,EAAE;QACX,MAAM,GAAG,GAAG,WAAW,CAAC,gBAAgB,CAAC,GAAG,EAAE;YAC1C,2DAA2D;YAC3D,gEAAgE;YAChE,0DAA0D;YAC1D,8DAA8D;YAC9D,iCAAiC;YACjC,IAAI,MAAM,GAAQ,GAAG,CAAC;YACtB,iEAAiE;YACjE,yCAAyC;YACzC,KAAK,EAAE,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBACtC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;oBACnC,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;wBACzB,MAAM,GAAG,KAAK,CAAC;wBACf,SAAS,KAAK,CAAC;oBACnB,CAAC;gBACL,CAAC;gBACD,kDAAkD;gBAClD,MAAM;YACV,CAAC;YACD,4DAA4D;YAC5D,4DAA4D;YAC5D,gEAAgE;YAChE,uCAAuC;YACvC,IAAI,GAAG,GAAe,MAAM,CAAC;YAC7B,OAAO,GAAG,EAAE,CAAC;gBACT,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;oBAChB,GAAG,CAAC,GAAG,EAAE,CAAC;oBACV,OAAO,IAAI,CAAC;gBAChB,CAAC;gBACD,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;YACrB,CAAC;YACD,8DAA8D;YAC9D,2DAA2D;YAC3D,yDAAyD;YACzD,2BAA2B;YAC3B,KAAK,WAAW,CAAC,OAAO,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;IAC9B,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/hooks/use-linking-nav.d.ts

@@ -1,6 +1,6 @@
-import { type Href } from '../href';
-import { type Nav } from './use-nav';
-import type { RouteMap } from '../types';
+import { type Href } from '../href.js';
+import { type Nav } from './use-nav.js';
+import type { RouteMap } from '../types.js';
 export interface UseLinkingNavOptions {
     /**
      * Schemes/prefixes to strip before parsing. Matched in order; the first

package/dist/hooks/use-linking-nav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-linking-nav.d.ts","sourceRoot":"","sources":["../../src/hooks/use-linking-nav.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAU,KAAK,GAAG,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,WAAW,oBAAoB;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;IAExC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpC;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,oBAAyB,GAAG,IAAI,CA0BnE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CASrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC3B,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,GAAG,SAAS,GACzB,IAAI,CAkBN"}
+{"version":3,"file":"use-linking-nav.d.ts","sourceRoot":"","sources":["../../src/hooks/use-linking-nav.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAU,KAAK,GAAG,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,oBAAoB;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;IAExC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpC;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,oBAAyB,GAAG,IAAI,CA0BnE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CASrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC3B,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,GAAG,SAAS,GACzB,IAAI,CAkBN"}

package/dist/hooks/use-linking-nav.js

@@ -0,0 +1,109 @@
+import { onMounted } from '@sigx/lynx';
+import { Linking } from '@sigx/lynx-linking';
+import { parseHref } from '../href.js';
+import { useNav } from './use-nav.js';
+import { useNavRoutes } from './use-nav-internal.js';
+/**
+ * Bridge `@sigx/lynx-linking` URL events into a `@sigx/lynx-navigation`
+ * navigator. Call once inside a `<NavigationRoot>` subtree.
+ *
+ * Handles both delivery modes:
+ *   - **cold start** — `Linking.getInitialURL()` is read on mount and, if
+ *     present, dispatched (replacing the initial route by default).
+ *   - **warm start** — `Linking.addEventListener('url', ...)` subscribes for
+ *     URLs delivered while the app is already running; each one is pushed.
+ *
+ * URL → route dispatch goes through `parseHref`, which matches the URL's
+ * pathname against the route registry seeded by `<NavigationRoot>`. Routes
+ * without a `path` template are never matched by deep links — only typed
+ * `<Link>` / `nav.push` calls reach them.
+ *
+ * @example
+ * ```tsx
+ * import { useLinkingNav } from '@sigx/lynx-navigation';
+ *
+ * const DeepLinks = component(() => {
+ *     useLinkingNav({
+ *         prefixes: ['myapp://', 'https://myapp.com'],
+ *         onUnmatched: (url) => console.warn('Unknown deep link:', url),
+ *     });
+ *     return () => null;
+ * });
+ *
+ * <NavigationRoot routes={routes}>
+ *     <DeepLinks />
+ *     <Stack />
+ * </NavigationRoot>
+ * ```
+ */
+export function useLinkingNav(opts = {}) {
+    const nav = useNav();
+    const routes = useNavRoutes();
+    const dispatch = (url, kind) => {
+        if (opts.onURL) {
+            opts.onURL(url, nav);
+            return;
+        }
+        const stripped = _stripPrefix(url, opts.prefixes);
+        const href = parseHref(stripped);
+        if (!href) {
+            opts.onUnmatched?.(url);
+            return;
+        }
+        _navigateToHref(nav, routes, href, kind);
+    };
+    onMounted(() => {
+        const initial = Linking.getInitialURL();
+        if (initial) {
+            dispatch(initial, opts.replaceInitial === false ? 'push' : 'replace');
+        }
+        const sub = Linking.addEventListener('url', (e) => dispatch(e.url, 'push'));
+        return () => sub.remove();
+    });
+}
+/**
+ * Strip the first matching prefix from `url`, returning a pathname-like
+ * string. If no prefixes are provided, or none match, the original URL is
+ * returned unchanged so `parseHref` can still handle scheme-prefixed forms
+ * via `@sigx/lynx-linking`'s `parse`.
+ *
+ * Exported for unit testing — not part of the package public API.
+ */
+export function _stripPrefix(url, prefixes) {
+    if (!prefixes || prefixes.length === 0)
+        return url;
+    for (const prefix of prefixes) {
+        if (url.startsWith(prefix)) {
+            const rest = url.slice(prefix.length);
+            return rest.startsWith('/') ? rest : `/${rest}`;
+        }
+    }
+    return url;
+}
+/**
+ * Call the right `nav.push` / `nav.replace` overload for `href`. The
+ * overloads differ in positional layout: routes with a params schema take
+ * `(name, params, search?, options?)`; routes without take `(name, search?,
+ * options?)`. Calling the wrong shape silently shifts `search` into the
+ * `options` slot, so we look the route up in the registry and branch.
+ *
+ * Exported for unit testing — not part of the package public API.
+ */
+export function _navigateToHref(nav, routes, href, kind) {
+    const def = routes[href.route];
+    // Defensive: `parseHref` already validated against the registry, so this
+    // really shouldn't happen — but if the registry was cleared between
+    // parse and dispatch (multi-NavigationRoot scenarios), bail rather than
+    // throw.
+    if (!def)
+        return;
+    const hasParams = !!def.params;
+    const action = kind === 'replace' ? nav.replace : nav.push;
+    if (hasParams) {
+        action(href.route, href.params, href.search);
+    }
+    else {
+        action(href.route, href.search);
+    }
+}
+//# sourceMappingURL=use-linking-nav.js.map

package/dist/hooks/use-linking-nav.js.map

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

package/dist/hooks/use-nav-internal.d.ts

@@ -1,6 +1,6 @@
 import { type SharedValue } from '@sigx/lynx';
-import type { ScreenRegistry } from '../internal/screen-registry';
-import type { RouteMap, StackEntry } from '../types';
+import type { ScreenRegistry } from '../internal/screen-registry.js';
+import type { RouteMap, StackEntry } from '../types.js';
 /**
  * Internal injectable: the `StackEntry` the calling screen was rendered for.
  *

package/dist/hooks/use-nav-internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-nav-internal.d.ts","sourceRoot":"","sources":["../../src/hooks/use-nav-internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAErD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,uFAI1B,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,8FAEnC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,2DAIvB,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IACzB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C;;;;OAIG;IACH,gBAAgB,IAAI,IAAI,CAAC;IACzB,iEAAiE;IACjE,iBAAiB,IAAI,IAAI,CAAC;IAC1B,iEAAiE;IACjE,iBAAiB,IAAI,IAAI,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE;QACd,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;QACzC;;;;;;WAMG;QACH,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;QAC3C,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;KACrD,CAAC;CACL;AAED,eAAO,MAAM,eAAe,+DAI1B,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,iEAI5B,CAAC"}
+{"version":3,"file":"use-nav-internal.d.ts","sourceRoot":"","sources":["../../src/hooks/use-nav-internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,uFAI1B,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,8FAEnC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,2DAIvB,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IACzB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C;;;;OAIG;IACH,gBAAgB,IAAI,IAAI,CAAC;IACzB,iEAAiE;IACjE,iBAAiB,IAAI,IAAI,CAAC;IAC1B,iEAAiE;IACjE,iBAAiB,IAAI,IAAI,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE;QACd,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;QACzC;;;;;;WAMG;QACH,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;QAC3C,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;KACrD,CAAC;CACL;AAED,eAAO,MAAM,eAAe,+DAI1B,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,iEAI5B,CAAC"}

package/dist/hooks/use-nav-internal.js

@@ -0,0 +1,55 @@
+import { defineInjectable } from '@sigx/lynx';
+/**
+ * Internal injectable: the `StackEntry` the calling screen was rendered for.
+ *
+ * Provided by `<EntryScope>` which `<Stack>` and `<ScreenContainer>` wrap
+ * around each screen component mount. Screens use this to derive their own
+ * focus state (`useIsFocused`, `useFocusEffect`) without having to track
+ * `entry.key` themselves.
+ *
+ * Default throws so calling `useIsFocused()` outside a screen mounted by a
+ * navigator surfaces a clear error rather than silently returning `false`.
+ */
+export const useCurrentEntry = defineInjectable(() => {
+    throw new Error('[lynx-navigation] No screen entry in scope. `useIsFocused` / `useFocusEffect` must be called from a component rendered as a route by <Stack>.');
+});
+/**
+ * Soft companion to {@link useCurrentEntry} — returns the current scope's
+ * entry if any, `null` when called outside an `<EntryScope>` instead of
+ * throwing. Provided alongside the strict version by `<EntryScope>`.
+ *
+ * Used by chrome consumers (`useScreenChrome`) where "no scoped entry"
+ * is a legitimate state (a Stack chrome slot lives outside the screen's
+ * EntryScope) and the caller wants to soft-fallback to the navigator's
+ * destination entry rather than crash.
+ */
+export const useCurrentEntryOptional = defineInjectable(() => null);
+/**
+ * Internal injectable: the route registry passed into `<NavigationRoot>`.
+ * Components (Stack, Screen) read this to look up route definitions by name.
+ *
+ * Not exported from the package barrel — use `useNav()` for navigation, and
+ * the registry is implicit from `<NavigationRoot routes={...}>`.
+ */
+export const useNavRoutes = defineInjectable(() => {
+    throw new Error('[lynx-navigation] No <NavigationRoot> found in the component tree.');
+});
+export const useNavInternals = defineInjectable(() => {
+    throw new Error('[lynx-navigation] No <NavigationRoot> found in the component tree.');
+});
+/**
+ * Internal injectable: the calling screen's `ScreenRegistry`.
+ *
+ * Provided by `<EntryScope>` alongside `useCurrentEntry`. The `<Screen>`
+ * component and its slot-filling sub-components write options and slot
+ * fills here; the navigator's persistent chrome (HeaderBar, TabBar — later
+ * slices) reads from this registry via `getScreenRegistry(key)` on the
+ * navigator state, which keys into a cross-entry map.
+ *
+ * Throws when used outside an EntryScope so calling `<Screen>` at the app
+ * root surfaces a clear error rather than silently no-op'ing.
+ */
+export const useScreenRegistry = defineInjectable(() => {
+    throw new Error('[lynx-navigation] No screen registry in scope. `<Screen>` (and `<Screen.Header>`, etc.) must be used inside a route component rendered by `<Stack>`.');
+});
+//# sourceMappingURL=use-nav-internal.js.map

package/dist/hooks/use-nav-internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-nav-internal.js","sourceRoot":"","sources":["../../src/hooks/use-nav-internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAoB,MAAM,YAAY,CAAC;AAIhE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,CAAa,GAAG,EAAE;IAC7D,MAAM,IAAI,KAAK,CACX,+IAA+I,CAClJ,CAAC;AACN,CAAC,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,gBAAgB,CACnD,GAAG,EAAE,CAAC,IAAI,CACb,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAW,GAAG,EAAE;IACxD,MAAM,IAAI,KAAK,CACX,oEAAoE,CACvE,CAAC;AACN,CAAC,CAAC,CAAC;AA8CH,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,CAAe,GAAG,EAAE;IAC/D,MAAM,IAAI,KAAK,CACX,oEAAoE,CACvE,CAAC;AACN,CAAC,CAAC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,gBAAgB,CAAiB,GAAG,EAAE;IACnE,MAAM,IAAI,KAAK,CACX,sJAAsJ,CACzJ,CAAC;AACN,CAAC,CAAC,CAAC"}

package/dist/hooks/use-nav-serializer.d.ts

@@ -1,4 +1,4 @@
-import type { StackEntry } from '../types';
+import type { StackEntry } from '../types.js';
 /**
  * Plain JSON snapshot of a navigator. The whole point of holding navigation
  * state in signals is that this is a one-liner — `JSON.stringify(nav.stack)`.

package/dist/hooks/use-nav-serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-nav-serializer.d.ts","sourceRoot":"","sources":["../../src/hooks/use-nav-serializer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAC9B,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,WAAW,GAAG,IAAI,CAAC;IACzD,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,uBAAuB;IACpC,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;IAC7C;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,eAAe,GAAG,YAAY,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1G;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAsIvE"}
+{"version":3,"file":"use-nav-serializer.d.ts","sourceRoot":"","sources":["../../src/hooks/use-nav-serializer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAC9B,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,WAAW,GAAG,IAAI,CAAC;IACzD,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,uBAAuB;IACpC,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;IAC7C;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,eAAe,GAAG,YAAY,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1G;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAsIvE"}