@sigx/lynx-navigation 0.1.3 → 0.4.0

package/src/components/Stack.tsx

@@ -1,117 +1,358 @@
-import { component, type ComponentFactory, type SharedValue } from '@sigx/lynx';
-import { Suspense, isLazyComponent } from '@sigx/lynx';
-import { useNav } from '../hooks/use-nav.js';
-import { useNavInternals, useNavRoutes } from '../hooks/use-nav-internal.js';
-import { ScreenContainer } from './ScreenContainer.js';
-import { EdgeBackHandle } from './EdgeBackHandle.js';
-import { EntryScope } from './EntryScope.js';
+import {
+    component,
+    defineProvide,
+    effect,
+    onUnmounted,
+    untrack,
+    useSharedValue,
+    type Define,
+} from '@sigx/lynx';
+import { createNavigatorState } from '../navigator/core';
+import { useNav, type Nav } from '../hooks/use-nav';
+import {
+    useCurrentEntry,
+    useNavInternals,
+    useNavRoutes,
+    type NavInternals,
+} from '../hooks/use-nav-internal';
+import type { Presentation, StackEntry } from '../types';
+import { animationVariant, computeLayers, isOverlayPresentation } from '../internal/layer-plan';
+import { EdgeBackHandle } from './EdgeBackHandle';
+import { Layer } from './Layer';
+import { useTabScreenName, useTabs } from './Tabs';
+
+type StackProps =
+    /**
+     * Mint a nested navigator with this route at its base. When set, the
+     * `<Stack>` becomes the owner of a new `NavigatorState` and provides
+     * `useNav` / `useNavInternals` / `useNavRoutes` to its subtree, so
+     * `nav.push('card-route', …)` from inside the stack stays *inside* it
+     * (e.g. for per-tab stacks). Routes presented as `modal` / `fullScreen` /
+     * `transparent-modal` automatically escalate to the parent navigator
+     * via `nav.parent`, walking up until they reach the root — so modals
+     * still overlay the whole app.
+     *
+     * Omit to render the *enclosing* navigator's stack (the default — this
+     * is how `<NavigationRoot> → <Stack />` works).
+     */
+    & Define.Prop<'initialRoute', string>
+    /** Initial params for the nested-stack base entry. */
+    & Define.Prop<'initialParams', Record<string, unknown>>
+    /** Initial search for the nested-stack base entry. */
+    & Define.Prop<'initialSearch', Record<string, unknown>>
+    /**
+     * Optional chrome rendered *above* the active screen, **inside this
+     * Stack's nav scope**. The intended use is `<Header />`, which needs
+     * to resolve `useNav()` to the per-stack nav (not the enclosing one)
+     * so it can react to pushes inside this stack — e.g. show a back
+     * button when a card is pushed onto a per-tab stack.
+     *
+     * Without this, a `<Header />` placed as a sibling of `<Stack>`
+     * would see the enclosing nav and never update when pushes happen
+     * inside the nested stack.
+     */
+    & Define.Slot<'default'>;
+
+let _nestedKeyCounter = 0;
 
 /**
  * Stack navigator — renders the topmost stack entry's component at rest, or
  * the top + underneath entries during a transition.
  *
- * **Idle**: just the top entry, full-bleed, no transform. The screen
- * component mounts directly so it can use its own layout (no extra absolute
- * positioning that would break percentage heights).
+ * Two modes:
+ *
+ * **Bound** (no `initialRoute`): renders the enclosing navigator's stack.
+ * This is the shape used directly under `<NavigationRoot>` and is what
+ * single-stack apps want.
+ *
+ * **Nested-owner** (`initialRoute="…"`): mints a fresh `NavigatorState` with
+ * its own progress `SharedValue` and edge-back gesture, and provides
+ * `useNav` / `useNavInternals` / `useNavRoutes` to its subtree. `useNav()`
+ * inside this stack returns the nested nav; `nav.parent` points to the
+ * enclosing one. Per-tab stacks are the canonical use case:
+ *
+ * ```tsx
+ * <Tabs initialTab="trips">
+ *   <Tabs.Screen name="trips"><Stack initialRoute="tripsHome" /></Tabs.Screen>
+ *   <Tabs.Screen name="map"><Stack initialRoute="mapHome" /></Tabs.Screen>
+ * </Tabs>
+ * ```
  *
- * **Transitioning**: two `<ScreenContainer>` instances stacked absolutely,
- * each with an MT-driven `translateX` that reads from the navigator's
- * progress `SharedValue`. The host's BG thread doesn't tick per frame —
- * `useAnimatedStyle` runs the interpolation entirely on MT.
+ * Modal/fullScreen pushes escalate up the parent chain automatically — so
+ * `nav.push('newTrip')` from inside Trips (where `newTrip` is `modal`)
+ * walks to root and overlays the whole UI. `replace` stays strictly local
+ * (asymmetric with `push`) so a modal `replace` never wipes the root stack.
  *
- * `key={top.key}` keeps the idle render's component instance stable across
- * unrelated re-renders. During transitions, composite keys
- * (`${entry.key}-${role}-${kind}`) ensure a fresh mount per role/kind pair so
- * the `useAnimatedStyle` binding is set with the right input/output ranges.
+ * **Render strategy.** Stack always emits the same JSX shape — a
+ * relative wrapper containing one `<Layer>` per entry returned by
+ * `computeLayers(stack, transition, progress)`. Each Layer is an
+ * absolutely-positioned host view with optional MT-bound translate
+ * animation. The pure layer-plan function decides:
+ *
+ *  - **Idle.** Topmost non-overlay base + any overlays above it. All
+ *    static (no transform). Overlays (`modal` / `fullScreen` /
+ *    `transparent-modal`) keep their underneath mounted; cards
+ *    replace their underneath in the base layer.
+ *  - **Card transition.** Both top and underneath animate (slide-in
+ *    + parallax). After settle, idle rules apply — the underneath
+ *    unmounts because the new top is the sole base.
+ *  - **Overlay transition.** The full idle layer stack up through
+ *    the underneath stays static; only the animated top has a
+ *    transform. After settle, the overlay either joins the static
+ *    idle stack (push) or unmounts (pop).
+ *
+ * Layer keys are `layer-${entry.key}-${animationVariant}`. The variant
+ * suffix forces a remount when an entry transitions from animated to
+ * static (or vice versa) — `useAnimatedStyle` binds once at setup and
+ * can't switch its mapper at runtime. Modal underneath layers never
+ * animate, so their key is stable across the modal lifecycle and the
+ * subtree's state (per-tab Stack navigators, scroll positions,
+ * in-flight inputs) survives.
  */
-export const Stack = component(() => {
-    const nav = useNav();
+export const Stack = component<StackProps>(({ props, slots }) => {
+    // Capture enclosing scope's nav + routes + internals BEFORE any of the
+    // defineProvide calls below override them for descendants. These are
+    // always the "outer" values regardless of whether this Stack is bound
+    // or nested-owner.
+    const parentNav = useNav();
     const routes = useNavRoutes();
-    const internals = useNavInternals();
+    const parentInternals = useNavInternals();
 
-    return () => {
-        const transition = nav.transition;
-        const top = nav.current;
+    // Decide mode at setup. `props.initialRoute` is captured once — the
+    // alternative (reactive switch between bound and nested-owner) would
+    // need to dispose and recreate the inner nav, which would lose all
+    // pushed state. Reasonable to pin it.
+    const initialName = props.initialRoute;
+    const isNested = typeof initialName === 'string' && initialName.length > 0;
+
+    let nav: Nav;
+    let internals: NavInternals;
 
-        if (!transition) {
-            const route = routes[top.route];
-            if (!route) return null;
-            const Comp = route.component as unknown as ComponentFactory<
-                Record<string, unknown>,
-                unknown,
-                unknown
-            >;
-            if (typeof Comp !== 'function') return null;
-            const params = top.params as Record<string, unknown>;
-            // Wrap lazy routes that declare a `fallback` in <Suspense> so the
-            // chunk-load shows the user-provided spinner instead of throwing
-            // up to the nearest outer boundary (which may be wrong layer or
-            // missing entirely).
-            const body = isLazyComponent(Comp) && route.fallback
-                ? (
-                    <Suspense fallback={route.fallback as never}>
-                        <Comp {...params} />
-                    </Suspense>
-                )
-                : <Comp {...params} />;
-            // When canGoBack and edge-swipe is enabled, overlay the gesture
-            // handle so the user can pan from the left edge to start a back
-            // transition. `position: absolute` doesn't disturb the screen's
-            // own layout — the handle only intercepts touches in the leftmost
-            // 20px, and only when they pan rightward past `MIN_DISTANCE`.
-            if (nav.canGoBack && internals.edgeSwipeEnabled) {
-                return (
-                    <view
-                        style={{
-                            position: 'relative',
-                            width: '100%',
-                            height: '100%',
-                        }}
-                    >
-                        <EntryScope key={top.key} entry={top}>
-                            {body}
-                        </EntryScope>
-                        <EdgeBackHandle key="edge-back" />
-                    </view>
-                );
-            }
-            return (
-                <EntryScope key={top.key} entry={top}>
-                    {body}
-                </EntryScope>
+    if (isNested) {
+        if (!routes[initialName]) {
+            throw new Error(
+                `[lynx-navigation] <Stack initialRoute='${initialName}'>: ` +
+                    `route is not registered. Known routes: ` +
+                    `${Object.keys(routes).join(', ') || '(none)'}`,
             );
         }
 
-        // Cast progress: TransitionState carries it as `unknown` to avoid
-        // pinning the contract to `@sigx/lynx`'s SharedValue at the type
-        // level; here at the runtime boundary we know it's a SharedValue<number>.
-        const progress = transition.progress as SharedValue<number>;
+        // Host entry — the parent's current top *when this Stack mounts*.
+        // Used by the focus chain so the nested nav is only "locally
+        // focused" while its host entry is still the top of the parent.
+        // Wrapped in try/catch because `<Stack initialRoute>` *may* be
+        // placed outside an EntryScope (e.g. directly under
+        // `<NavigationRoot>`); in that case there's no host-entry gate to
+        // apply and we just rely on `parent.isLocallyFocused`.
+        let hostEntryKey: string | null = null;
+        try {
+            hostEntryKey = useCurrentEntry().key;
+        } catch {
+            hostEntryKey = null;
+        }
 
-        return (
+        // Enclosing tab name (if any). Lets the focus chain gate on tab
+        // active state — Trips' inner stack reports `isLocallyFocused: false`
+        // while the user is on the Map tab, even though it's the top of
+        // its own stack.
+        let tabName: string | null = null;
+        let tabsHandle: ReturnType<typeof useTabs> | null = null;
+        try {
+            tabName = useTabScreenName();
+            tabsHandle = useTabs();
+        } catch {
+            tabName = null;
+            tabsHandle = null;
+        }
+
+        // Inherit animation enablement from the parent — if the root was
+        // created with `animated={false}` (tests), nested stacks should
+        // also commit instantly so test assertions don't have to wait on
+        // a SharedValue that won't tick.
+        const animationsEnabled = parentInternals.progress !== null;
+        const progressSv = useSharedValue(0);
+
+        const presentation =
+            (routes[initialName].presentation ?? 'card') as Presentation;
+        // Counter-derived suffix keeps base-entry keys unique across
+        // concurrent nested stacks in a tab app. Plain `Math.random` would
+        // do but a counter is deterministic for test snapshots.
+        _nestedKeyCounter += 1;
+        const initial: StackEntry = {
+            key: `nested-${initialName}-${_nestedKeyCounter}`,
+            route: initialName,
+            params: props.initialParams ?? {},
+            search: props.initialSearch ?? {},
+            state: undefined,
+            presentation,
+        };
+
+        const navState = createNavigatorState({
+            routes,
+            initial,
+            progress: animationsEnabled ? progressSv : undefined,
+            parent: parentNav,
+            // Start un-focused; the effect below flips this once we observe
+            // the parent's current entry / tab-active state.
+            initialLocallyFocused: false,
+        });
+
+        nav = navState.nav;
+        internals = {
+            progress: animationsEnabled ? progressSv : null,
+            beginBackGesture: navState._gesture.beginBackGesture,
+            commitBackGesture: navState._gesture.commitBackGesture,
+            cancelBackGesture: navState._gesture.cancelBackGesture,
+            edgeSwipeEnabled:
+                // Gate on animationsEnabled too — if there's no progress
+                // SharedValue (e.g. parent is `animated={false}`), the edge
+                // swipe gesture would call `beginBackGesture()` with a null
+                // progress and leave the stack in an inconsistent state.
+                animationsEnabled && parentInternals.edgeSwipeEnabled,
+            screens: navState._screens,
+        };
+
+        // Reactive focus chain: this nav is locally focused iff
+        //   1. (no host entry captured) OR parent.current.key === hostEntryKey
+        //   2. parent.isLocallyFocused
+        //   3. (no enclosing tab) OR tabs.active === tabName
+        // Effect re-runs on any of those changing — parent's stack
+        // mutating, parent's own focus flipping, or the tab switching.
+        const focusRunner = effect(() => {
+            const hostMatch =
+                hostEntryKey === null || parentNav.current.key === hostEntryKey;
+            const parentFocused = parentNav.isLocallyFocused;
+            const tabActive =
+                tabName === null || tabsHandle === null
+                    ? true
+                    : tabsHandle.active === tabName;
+            const focused = hostMatch && parentFocused && tabActive;
+            // Write outside the read-tracking window — `_setLocallyFocused`
+            // bumps a signal that no consumer in *this* setup reads, but
+            // it's good hygiene anyway.
+            untrack(() => navState._setLocallyFocused(focused));
+        });
+
+        onUnmounted(() => {
+            focusRunner.stop();
+            parentNav._children.delete(nav);
+        });
+
+        defineProvide(useNav, () => nav);
+        defineProvide(useNavRoutes, () => routes);
+        defineProvide(useNavInternals, () => internals);
+    } else {
+        nav = parentNav;
+        internals = parentInternals;
+    }
+
+    // Per-stack chrome (slots.default) renders *inside* this Stack's
+    // nav scope so a `<Header />` placed there resolves `useNav()` to
+    // the per-stack nav. Wrapping the active body in a flex-column
+    // with the slot above does that without disturbing layer-fill
+    // semantics — the slot takes natural height, the body keeps
+    // flex-fill.
+    const flexColumnFill = {
+        flexGrow: 1,
+        flexShrink: 1,
+        flexBasis: 0,
+        minHeight: 0,
+        display: 'flex',
+        flexDirection: 'column',
+    } as const;
+
+    return () => {
+        const chrome = slots.default?.();
+        const layers = computeLayers(nav.stack, nav.transition, internals.progress);
+
+        const renderLayerNode = (layer: typeof layers[number] | undefined) =>
+            layer ? (
+                <Layer
+                    key={`layer-${layer.entry.key}-${animationVariant(layer.animation)}`}
+                    entry={layer.entry}
+                    routes={routes}
+                    animation={layer.animation}
+                />
+            ) : null;
+        // sigx's reconciler treats a single array-valued JSX child as
+        // one "slot": when the array's *length* changes between
+        // renders, keyed children inside can be remounted even if
+        // their keys are stable. To make stacked-overlay state
+        // preservation work (modal A still mounted after modal B
+        // pushes on top), each layer is emitted as its own separate
+        // JSX child slot rather than as an array. The slots are
+        // position-stable across renders — the only thing that
+        // changes is a slot turning from `null` to a Layer (mount) or
+        // vice versa (unmount). MAX_LAYERS caps the supported stack
+        // depth; in practice apps rarely stack more than 2-3 overlays.
+        // If you hit the cap, increase the constant — the unrolled
+        // shape is just verbose, not algorithmically limited.
+
+        // Edge-swipe handle on top, gated on:
+        //  - `internals.edgeSwipeEnabled` — opt-out flag (also off
+        //    when the navigator has no progress SharedValue, i.e.
+        //    animations disabled — no in-flight gesture to animate).
+        //  - `nav.canGoBack` — something to pop back to.
+        //  - `!nav.transition` — no animation already running.
+        //  - The current top is a card (not an overlay). Edge-swipe
+        //    is the iOS-style horizontal pop gesture for card stacks;
+        //    using it to dismiss a modal would be the wrong axis +
+        //    the wrong dismissal semantic.
+        //
+        // The handle only intercepts touches in the leftmost 20px and
+        // ignores small drags, so placing it last (highest z) doesn't
+        // disturb screen touches.
+        const top = nav.current;
+        const edgeHandle = (
+            internals.edgeSwipeEnabled
+            && nav.canGoBack
+            && !nav.transition
+            && !isOverlayPresentation(top.presentation)
+        )
+            ? <EdgeBackHandle key="edge-back" />
+            : null;
+
+        const body = (
             <view
                 style={{
                     position: 'relative',
                     width: '100%',
-                    height: '100%',
+                    // Flex-fill so the layer container has a real
+                    // height — `<Layer>`s anchor via `position:
+                    // absolute; top/right/bottom/left: 0`, which
+                    // needs a sized relative parent.
+                    ...flexColumnFill,
+                    // Clip any animated layer that translates off-
+                    // screen so the slide doesn't bleed past the
+                    // Stack's bounds.
                     overflow: 'hidden',
                 }}
             >
-                <ScreenContainer
-                    key={`${transition.underneathEntry.key}-underneath-${transition.kind}`}
-                    entry={transition.underneathEntry}
-                    routes={routes}
-                    role="underneath"
-                    kind={transition.kind}
-                    progress={progress}
-                />
-                <ScreenContainer
-                    key={`${transition.topEntry.key}-top-${transition.kind}`}
-                    entry={transition.topEntry}
-                    routes={routes}
-                    role="top"
-                    kind={transition.kind}
-                    progress={progress}
-                />
+                {renderLayerNode(layers[0])}
+                {renderLayerNode(layers[1])}
+                {renderLayerNode(layers[2])}
+                {renderLayerNode(layers[3])}
+                {renderLayerNode(layers[4])}
+                {renderLayerNode(layers[5])}
+                {renderLayerNode(layers[6])}
+                {renderLayerNode(layers[7])}
+                {renderLayerNode(layers[8])}
+                {renderLayerNode(layers[9])}
+                {renderLayerNode(layers[10])}
+                {renderLayerNode(layers[11])}
+                {renderLayerNode(layers[12])}
+                {renderLayerNode(layers[13])}
+                {renderLayerNode(layers[14])}
+                {renderLayerNode(layers[15])}
+                {edgeHandle}
+            </view>
+        );
+
+        if (chrome == null) return body as never;
+        return (
+            <view style={flexColumnFill}>
+                {chrome}
+                <view style={flexColumnFill}>{body}</view>
             </view>
         );
     };

package/src/components/TabBar.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `<TabBar>` — headless default chrome for `<Tabs>`.
+ *
+ * Renders the active-tab buttons reading from the enclosing `useTabs()`
+ * navigator. Intentionally **unstyled** — this lives in the (theme-less)
+ * navigation package, so it ships pure structure + accessibility wiring.
+ * Themed chrome belongs in a UI-kit package: see `<NavTabBar />` in
+ * `@sigx/lynx-daisyui` for the daisy-themed equivalent.
+ *
+ * Use this directly only if you want to handle styling yourself via the
+ * `renderTab` prop. For a "looks like a tab bar out of the box" component,
+ * pull `<NavTabBar />` from `@sigx/lynx-daisyui` (or your own UI kit).
+ *
+ * Customization:
+ *   - `renderTab`: a function `(info, ctx) => JSX` that fully replaces the
+ *     default button rendering for each tab. `ctx.active` tells the
+ *     consumer whether this tab is currently focused; `ctx.onPress`
+ *     activates the tab. **Recommended** for any visual treatment.
+ *
+ * Accessibility (baked into the default button — the one structural
+ * concern this component keeps):
+ *   - `accessibility-label` from `info.accessibilityLabel ?? info.label ?? info.name`.
+ *   - `accessibility-element="true"` so screen readers see the whole pill.
+ *   - `accessibility-trait="button"` and a `selected` flag on the active
+ *     one so VoiceOver/TalkBack announces focus state on tab switch.
+ */
+import { type JSXElement } from '@sigx/lynx';
+import { type TabInfo } from './Tabs';
+/** Rendering context passed to a `renderTab` consumer. */
+export interface TabRenderContext {
+    /** True when this tab is currently active. Reactive — re-runs render on change. */
+    readonly active: boolean;
+    /** Activates this tab. Use as a `bindtap` handler on the rendered node. */
+    onPress(): void;
+}
+export declare const TabBar: import("@sigx/runtime-core").ComponentFactory<{
+    renderTab?: ((info: TabInfo, ctx: TabRenderContext) => JSXElement) | undefined;
+}, void, {}>;

package/src/components/TabBar.tsx

@@ -1,36 +1,35 @@
 /**
- * `<TabBar>` — default chrome for `<Tabs>`.
+ * `<TabBar>` — headless default chrome for `<Tabs>`.
  *
- * Renders a row of tab buttons reading from the enclosing `useTabs()`
- * navigator. Active tab is highlighted via the `active` prop on each
- * default button (consumers can re-style via `renderTab`).
+ * Renders the active-tab buttons reading from the enclosing `useTabs()`
+ * navigator. Intentionally **unstyled** — this lives in the (theme-less)
+ * navigation package, so it ships pure structure + accessibility wiring.
+ * Themed chrome belongs in a UI-kit package: see `<NavTabBar />` in
+ * `@sigx/lynx-daisyui` for the daisy-themed equivalent.
  *
- * Customization knobs:
+ * Use this directly only if you want to handle styling yourself via the
+ * `renderTab` prop. For a "looks like a tab bar out of the box" component,
+ * pull `<NavTabBar />` from `@sigx/lynx-daisyui` (or your own UI kit).
+ *
+ * Customization:
  *   - `renderTab`: a function `(info, ctx) => JSX` that fully replaces the
  *     default button rendering for each tab. `ctx.active` tells the
  *     consumer whether this tab is currently focused; `ctx.onPress`
- *     activates the tab.
- *
- * Accessibility:
- *   - Each default button gets `accessibility-label` from
- *     `info.accessibilityLabel ?? info.label ?? info.name`.
- *   - Each default button gets `accessibility-element="true"` so screen
- *     readers see the whole pill, not just the inner `<text>`.
- *   - Each default button gets `accessibility-trait="button"` and a
- *     `selected` flag on the active one so VoiceOver/TalkBack announces
- *     focus state on tab switch.
+ *     activates the tab. **Recommended** for any visual treatment.
  *
- * Placement: mount inside `<Tabs>` alongside the `<Tabs.Screen>`s. Order
- * matters visually (place above or below the screen bodies depending on
- * the layout), and `<Tabs.Screen>` bodies all stack with `display:flex` so
- * the TabBar should be at a deterministic position in the JSX.
+ * Accessibility (baked into the default button — the one structural
+ * concern this component keeps):
+ *   - `accessibility-label` from `info.accessibilityLabel ?? info.label ?? info.name`.
+ *   - `accessibility-element="true"` so screen readers see the whole pill.
+ *   - `accessibility-trait="button"` and a `selected` flag on the active
+ *     one so VoiceOver/TalkBack announces focus state on tab switch.
  */
 import {
     component,
     type Define,
     type JSXElement,
 } from '@sigx/lynx';
-import { useTabs, type TabInfo } from './Tabs.js';
+import { useTabs, type TabInfo } from './Tabs';
 
 /** Rendering context passed to a `renderTab` consumer. */
 export interface TabRenderContext {
@@ -46,8 +45,9 @@ type TabBarProps =
 /**
  * Default per-tab button. Plain `<view>` with a `<text>` inside, an
  * `accessibility-*` cluster for screen readers, and a tap handler. No
- * styling beyond a minimal active-state marker — consumers that want
- * branded chrome pass `renderTab`.
+ * styling beyond a minimal active-state opacity hint — consumers that
+ * want branded chrome pass `renderTab` or use a UI-kit-provided tab bar
+ * (e.g. `<NavTabBar />` from `@sigx/lynx-daisyui`).
  */
 const DefaultTabButton = component<
     & Define.Prop<'info', TabInfo, true>