@sigx/lynx-navigation 0.2.0 → 0.4.1

package/src/components/Stack.tsx

@@ -5,11 +5,8 @@ import {
     onUnmounted,
     untrack,
     useSharedValue,
-    type ComponentFactory,
     type Define,
-    type SharedValue,
 } from '@sigx/lynx';
-import { Suspense, isLazyComponent } from '@sigx/lynx';
 import { createNavigatorState } from '../navigator/core.js';
 import { useNav, type Nav } from '../hooks/use-nav.js';
 import {
@@ -19,9 +16,9 @@ import {
     type NavInternals,
 } from '../hooks/use-nav-internal.js';
 import type { Presentation, StackEntry } from '../types.js';
-import { ScreenContainer } from './ScreenContainer.js';
+import { animationVariant, computeLayers, isOverlayPresentation } from '../internal/layer-plan.js';
 import { EdgeBackHandle } from './EdgeBackHandle.js';
-import { EntryScope } from './EntryScope.js';
+import { Layer } from './Layer.js';
 import { useTabScreenName, useTabs } from './Tabs.js';
 
 type StackProps =
@@ -42,7 +39,19 @@ type StackProps =
     /** 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>>;
+    & 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;
 
@@ -74,22 +83,33 @@ let _nestedKeyCounter = 0;
  * walks to root and overlays the whole UI. `replace` stays strictly local
  * (asymmetric with `push`) so a modal `replace` never wipes the root stack.
  *
- * **Render strategy** (same in both modes):
- *  - **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).
- *  - **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.
+ * **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:
  *
- * `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.
+ *  - **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<StackProps>(({ props }) => {
+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
@@ -226,89 +246,113 @@ export const Stack = component<StackProps>(({ props }) => {
         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 transition = nav.transition;
-        const top = nav.current;
+        const chrome = slots.default?.();
+        const layers = computeLayers(nav.stack, nav.transition, internals.progress);
 
-        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>
-            );
-        }
+        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.
 
-        // 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>;
+        // 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;
 
-        return (
+        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.tsx

@@ -1,29 +1,28 @@
 /**
- * `<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,
@@ -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>

package/src/components/Tabs.tsx

@@ -208,13 +208,27 @@ const TabsScreen = component<TabsScreenProps>(({ props, slots }) => {
         // `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 (
             <view
                 style={{
                     display: active ? 'flex' : 'none',
+                    flexDirection: 'column',
                     width: '100%',
-                    height: '100%',
+                    flexGrow: 1,
+                    flexShrink: 1,
+                    flexBasis: 0,
+                    minHeight: 0,
                 }}
             >
                 {slots.default?.()}

package/src/hooks/use-nav-internal.ts

@@ -19,6 +19,20 @@ export const useCurrentEntry = defineInjectable<StackEntry>(() => {
     );
 });
 
+/**
+ * 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<StackEntry | null>(
+    () => null,
+);
+
 /**
  * Internal injectable: the route registry passed into `<NavigationRoot>`.
  * Components (Stack, Screen) read this to look up route definitions by name.
@@ -64,7 +78,14 @@ export interface NavInternals {
      */
     readonly screens: {
         register(registry: ScreenRegistry): void;
-        unregister(entryKey: string): void;
+        /**
+         * Identity-checked: only removes the entry if `registry` is the
+         * one currently registered under its `entry.key`. A no-op when
+         * a newer registry has already taken that slot (which happens
+         * at the transition→idle handoff, where a fresh `<EntryScope>`
+         * for the same entry mounts before the old one's unmount fires).
+         */
+        unregister(registry: ScreenRegistry): void;
         get(entryKey: string): ScreenRegistry | undefined;
     };
 }

package/src/hooks/use-screen-chrome.ts

@@ -0,0 +1,122 @@
+/**
+ * `useScreenChrome` — reactive read of the currently-focused screen's
+ * options + slot fills, plus navigation helpers a header would need
+ * (canGoBack, pop).
+ *
+ * The built-in `<Header />` reads this same data via internal hooks.
+ * `useScreenChrome` exposes it as a public API so theme packages
+ * (`@sigx/lynx-daisyui`, custom designs) can build their own header
+ * components without depending on internal modules.
+ *
+ * Resolution rules:
+ *
+ *  - **Inside a screen body** (i.e. inside an EntryScope whose entry is
+ *    on the nearest `useNav()`'s stack), bind to **this entry's**
+ *    registry. Useful for modal screens that render their own
+ *    NavHeader inside — the chrome slides with the sheet.
+ *  - **Outside any matching EntryScope** (slot of `<Stack>`, persistent
+ *    root-level Header, etc.), bind to the *destination* entry of the
+ *    current nav state — what the navigator is settling on once the
+ *    in-flight transition completes. Push: the new top (already at
+ *    nav.current). Pop: the entry being revealed
+ *    (`transition.underneathEntry`), *not* the one being animated off.
+ *    Using the destination means the bar reflects what the user is
+ *    navigating *to*, immediately, with no end-of-animation snap.
+ *
+ * Every property is a getter — reading inside a render / `computed`
+ * subscribes to the underlying signal, so consumers re-render when
+ * title / slots change.
+ */
+import { useNav } from './use-nav.js';
+import { useCurrentEntryOptional, useNavInternals } from './use-nav-internal.js';
+import type { ScreenSlotFills, StackEntry } from '../types.js';
+
+export interface ScreenChrome {
+    /** Resolved screen title — `options.title` (string or getter) or the route name as fallback. Reactive. */
+    readonly title: string;
+    /** Whether the header should render. Defaults to true unless the screen set `headerShown: false`. Reactive. */
+    readonly headerShown: boolean;
+    /** True when the current stack has more than one entry — i.e. there's something to pop back to. Reactive. */
+    readonly canGoBack: boolean;
+    /** Pop the top entry. No-op when `!canGoBack`. */
+    pop(): void;
+    /** Full header override slot, if `<Screen.Header>` was set. Render its return value in place of the default layout. */
+    readonly header: ScreenSlotFills['header'] | undefined;
+    /** Left-aligned slot (typically a back button). Reactive. */
+    readonly headerLeft: ScreenSlotFills['headerLeft'] | undefined;
+    /** Right-aligned slot (typically actions). Reactive. */
+    readonly headerRight: ScreenSlotFills['headerRight'] | undefined;
+}
+
+export function useScreenChrome(): ScreenChrome {
+    const nav = useNav();
+    const internals = useNavInternals();
+
+    // The candidate "scoped" entry, if we happen to be rendered inside
+    // an EntryScope. May belong to a DIFFERENT nav than `nav` — e.g.
+    // when NavHeader is placed in a per-tab `<Stack>`'s chrome slot,
+    // it sees the outer (root) EntryScope's entry but its `useNav()`
+    // returns the inner per-tab nav. We only honor the pin when the
+    // entry is actually on this nav's stack; otherwise we're crossing
+    // scopes and the destination-entry path is correct.
+    //
+    // `useCurrentEntryOptional` is the soft companion to
+    // `useCurrentEntry` — it returns `null` outside any EntryScope
+    // rather than throwing, which is the right semantic for a chrome
+    // consumer that *might* be a Stack slot.
+    const candidate: StackEntry | null = useCurrentEntryOptional();
+
+    const getDestinationEntry = (): StackEntry => {
+        const t = nav.transition;
+        if (t) {
+            return t.kind === 'pop' ? t.underneathEntry : t.topEntry;
+        }
+        return nav.current;
+    };
+
+    const getEntry = (): StackEntry => {
+        if (candidate) {
+            const stack = nav.stack;
+            if (stack.some((e) => e.key === candidate!.key)) {
+                return candidate;
+            }
+        }
+        return getDestinationEntry();
+    };
+
+    return {
+        get title() {
+            const entry = getEntry();
+            const reg = internals.screens.get(entry.key);
+            const t = reg?.options.title;
+            if (typeof t === 'function') return t();
+            if (typeof t === 'string') return t;
+            return entry.route;
+        },
+        get headerShown() {
+            const reg = internals.screens.get(getEntry().key);
+            return reg?.options.headerShown !== false;
+        },
+        get canGoBack() {
+            const entry = getEntry();
+            const stack = nav.stack;
+            const idx = stack.findIndex((e) => e.key === entry.key);
+            return idx > 0;
+        },
+        pop() {
+            nav.pop();
+        },
+        get header() {
+            const reg = internals.screens.get(getEntry().key);
+            return reg?.slots.header;
+        },
+        get headerLeft() {
+            const reg = internals.screens.get(getEntry().key);
+            return reg?.slots.headerLeft;
+        },
+        get headerRight() {
+            const reg = internals.screens.get(getEntry().key);
+            return reg?.slots.headerRight;
+        },
+    };
+}

package/src/index.ts

@@ -16,6 +16,8 @@ export { useLinkingNav } from './hooks/use-linking-nav.js';
 export type { UseLinkingNavOptions } from './hooks/use-linking-nav.js';
 export { useIsFocused, useFocusEffect } from './hooks/use-focus.js';
 export { useScreenOptions } from './hooks/use-screen-options.js';
+export { useScreenChrome } from './hooks/use-screen-chrome.js';
+export type { ScreenChrome } from './hooks/use-screen-chrome.js';
 export {
     useNavSerializer,
     NAV_SNAPSHOT_VERSION,