@sigx/lynx-navigation 0.1.2 → 0.2.0

package/src/components/Tabs.tsx

@@ -4,31 +4,32 @@
  * Usage:
  *
  * ```tsx
- * <NavigationRoot routes={routes}>
- *   <Tabs initialTab="feed">
- *     <Tabs.Screen name="feed" icon={<FeedIcon />} label="Feed">
- *       <FeedView />
- *     </Tabs.Screen>
- *     <Tabs.Screen name="me" icon={<MeIcon />} label="Profile">
- *       <ProfileView />
- *     </Tabs.Screen>
- *   </Tabs>
+ * <NavigationRoot routes={routes} initialRoute="root">
+ *   <Stack />
  * </NavigationRoot>
- * ```
  *
- * Scope of this slice (v0.1): pure UI primitive. Each tab's body stays
- * mounted for state preservation (the inactive ones render with
- * `display: 'none'`). Active tab is reactive via `useTabs()`.
+ * // 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>
+ * ```
  *
- * Out of scope (deferred to a nested-navigators slice):
- *   - Per-tab `<Stack>` with its own navigator state machine
- *   - `nav.parent` chain into the Tabs nav
- *   - Named navigators (`useNav('root')`)
+ * 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()`.
  *
- * Those build on multi-navigator-state plumbing that isn't ready yet.
- * For now, the inner content of a `<Tabs.Screen>` shares the same nav as
- * its outer `<NavigationRoot>` — usable for shallow tab apps, but full
- * nested routing comes later.
+ * 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,
@@ -98,6 +99,19 @@ const useTabsRegistrar = defineInjectable<TabsRegistrar>(() => {
     );
 });
 
+/**
+ * @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<string>(() => {
+    throw new Error(
+        '[lynx-navigation] useTabScreenName() called outside a <Tabs.Screen> body.',
+    );
+});
+
 type TabsProps =
     & Define.Prop<'initialTab', string>
     & Define.Slot<'default'>;
@@ -186,6 +200,10 @@ const TabsScreen = component<TabsScreenProps>(({ props, slots }) => {
     });
     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

package/src/hooks/use-focus.ts

@@ -34,7 +34,13 @@ export function useIsFocused(): Computed<boolean> {
     // 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;
-    return computed(() => nav.current.key === myKey);
+    // 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);
 }
 
 /**

package/src/hooks/use-hardware-back.ts

@@ -1,19 +1,26 @@
 import { onMounted } from '@sigx/lynx';
 import { BackHandler } from '@sigx/lynx-linking';
-import { useNav } from './use-nav.js';
+import { useNav, type Nav } 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:
+ * `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 `nav.canGoBack` → `nav.pop()`.
+ *   - 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.
@@ -35,13 +42,40 @@ export function useHardwareBack(): void {
     const nav = useNav();
     onMounted(() => {
         const sub = BackHandler.addEventListener(() => {
-            if (nav.canGoBack) {
-                nav.pop();
-                return true;
+            // 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 = 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: Nav | null = active;
+            while (cur) {
+                if (cur.canGoBack) {
+                    cur.pop();
+                    return true;
+                }
+                cur = cur.parent;
             }
-            // At the root — 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).
+            // 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;
         });

package/src/hooks/use-nav.ts

@@ -93,9 +93,46 @@ export interface Nav {
     /** Whether the user can go back from the current entry. Reactive. */
     readonly canGoBack: boolean;
 
-    /** Parent navigator (e.g. the Tabs above this Stack), or null at the root. */
+    /**
+     * Parent navigator (e.g. the root nav above a per-tab `<Stack>`), or null
+     * at the root. Set when a `<Stack>` mints its own navigator via
+     * `<Stack initialRoute="…">` — that stack's `useNav()` returns a nav
+     * whose `parent` is the enclosing nav.
+     *
+     * `push` calls for routes whose resolved presentation is non-`card`
+     * (`modal` / `fullScreen` / `transparent-modal`) escalate up the
+     * `parent` chain automatically — you don't normally need to reach
+     * through `parent` to present modals. `parent` is exposed as an escape
+     * hatch for power users (e.g. imperative `parent.pop()` from a child
+     * stack). Avoid pushing card routes onto `parent` directly — that
+     * defeats per-tab stack isolation.
+     */
     readonly parent: Nav | null;
 
+    /**
+     * Whether this navigator is part of the currently-focused chain. True
+     * for the root nav at all times; for a nested nav (e.g. a per-tab
+     * stack), true only when its host entry is the top of `parent`, the
+     * parent itself is locally focused, and any extra gate (e.g. the
+     * enclosing tab is active) reports active.
+     *
+     * Reactive. `useIsFocused()` ANDs `nav.current.key === myKey` with
+     * `nav.isLocallyFocused`.
+     */
+    readonly isLocallyFocused: boolean;
+
+    /**
+     * @internal
+     * Set of child navigators (per-tab `<Stack>` instances) that have
+     * registered themselves under this nav. Used by `useHardwareBack` to
+     * find the deepest currently-focused nav and route the back press
+     * there before falling back up the chain.
+     *
+     * Not part of the public API — leading-underscore marks it as
+     * implementation detail.
+     */
+    readonly _children: Set<Nav>;
+
     /**
      * In-flight transition, or null when navigation is at rest. Reactive —
      * `<Stack>` reads this to decide whether to render one screen or two

package/src/navigator/core.ts

@@ -64,6 +64,14 @@ export interface NavigatorState {
         unregister(entryKey: string): void;
         get(entryKey: string): ScreenRegistry | undefined;
     };
+    /**
+     * Internal: set `nav.isLocallyFocused` from outside.
+     *
+     * `<Stack>` calls this when its host entry's locally-focused state
+     * changes (top of parent + parent focused + enclosing tab active). For
+     * the root nav this stays `true` for the lifetime of the navigator.
+     */
+    readonly _setLocallyFocused: (focused: boolean) => void;
 }
 
 /**
@@ -146,6 +154,24 @@ export interface CreateNavigatorOptions {
      * that don't have an MT runtime.
      */
     progress?: SharedValue<number>;
+    /**
+     * Parent navigator. Set when this navigator is nested under another
+     * (e.g. a per-tab `<Stack initialRoute>` under root). Drives the
+     * `nav.parent` getter and the modal-escalation behaviour of `push`:
+     * a push of a route whose resolved presentation is not `'card'`
+     * recurses via `parent.push(...)`, walking up the chain until it
+     * lands on a navigator with no parent (the root).
+     *
+     * Leave undefined for the root navigator.
+     */
+    parent?: Nav | null;
+    /**
+     * Whether this navigator is considered "locally focused" at creation
+     * time. Defaults to true for the root nav; nested stacks pass `false`
+     * here and then flip the flag via `_setLocallyFocused` once their
+     * host-entry/tab-active state is computed.
+     */
+    initialLocallyFocused?: boolean;
 }
 
 /**
@@ -154,9 +180,13 @@ export interface CreateNavigatorOptions {
  * can subscribe to it.
  */
 export function createNavigatorState(opts: CreateNavigatorOptions): NavigatorState {
-    const { routes, initial, progress } = opts;
+    const { routes, initial, progress, parent = null } = opts;
 
     const stackSignal: Signal<StackEntry[]> = signal<StackEntry[]>([initial]);
+    const focusedBox: Signal<{ value: boolean }> = signal<{ value: boolean }>({
+        value: opts.initialLocallyFocused ?? true,
+    });
+    const children = new Set<Nav>();
     // `signal(null)` would wrap as a primitive (no `$set`), so wrap in an
     // object to get the standard `{ value }`-style API. Reading `.value`
     // tracks; writing triggers re-render of `<Stack>`.
@@ -231,14 +261,33 @@ export function createNavigatorState(opts: CreateNavigatorOptions): NavigatorSta
     }
 
     const push: Nav['push'] = ((name: string, ...args: unknown[]) => {
-        if (isTransitioning()) return;
-        const { params, search, options } = unpackArgs(name, args, routes);
         if (!routes[name]) {
             throw new Error(
                 `[lynx-navigation] push('${name}'): route is not registered. ` +
                     `Known routes: ${Object.keys(routes).join(', ') || '(none)'}`,
             );
         }
+        const { params, search, options } = unpackArgs(name, args, routes);
+
+        // Escalate non-card presentations up the parent chain. Modals,
+        // fullScreen, and transparent-modal routes belong on the root
+        // navigator so they overlay tab UI and persistent chrome. We resolve
+        // the presentation the same way `makeEntry` does so the escalation
+        // decision matches what would actually be shown.
+        const resolvedPresentation =
+            (options?.presentation ?? routes[name].presentation ?? 'card') as Presentation;
+        if (resolvedPresentation !== 'card' && parent) {
+            // Walk straight to the root — every navigator with a parent
+            // delegates non-card pushes upward, so a chain of any depth
+            // collapses to a single push on the topmost nav.
+            // Forward original args verbatim so overloads (`push(name)`,
+            // `push(name, params)`, `push(name, params, search)`,
+            // `push(name, params, search, options)`) keep their meaning.
+            (parent.push as (n: string, ...a: unknown[]) => void)(name, ...args);
+            return;
+        }
+
+        if (isTransitioning()) return;
         preloadRouteComponent(routes[name].component);
         const newEntry = makeEntry(name, params, search, options, routes);
         const cur = getStack();
@@ -411,18 +460,38 @@ export function createNavigatorState(opts: CreateNavigatorOptions): NavigatorSta
             return stackSignal.length > 1;
         },
         get parent() {
-            return null;
+            return parent;
+        },
+        get isLocallyFocused() {
+            return focusedBox.value;
+        },
+        get _children() {
+            return children;
         },
         get transition() {
             return transitionBox.value;
         },
     };
 
+    if (parent) {
+        // Register with parent so root-level traversals (hardware back,
+        // future deepest-focused queries) can reach this nav. The matching
+        // `_children.delete(nav)` happens when the owning `<Stack>` unmounts;
+        // see Stack.tsx.
+        parent._children.add(nav);
+    }
+
+    function setLocallyFocused(focused: boolean): void {
+        if (focusedBox.value === focused) return;
+        focusedBox.value = focused;
+    }
+
     return {
         nav,
         routes,
         _gesture: { beginBackGesture, commitBackGesture, cancelBackGesture },
         _screens: createScreenRegistries(),
+        _setLocallyFocused: setLocallyFocused,
     };
 }