@sigx/lynx-navigation 0.2.0 → 0.4.0

package/src/components/Screen.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `<Screen>` — declarative per-screen options + slot fills.
+ *
+ * Usage:
+ *
+ * ```tsx
+ * const ProfileScreen = component(() => () => (
+ *   <Screen title="Profile" headerShown gestureEnabled>
+ *     <Screen.HeaderRight>
+ *       <text bindtap={onEdit}>Edit</text>
+ *     </Screen.HeaderRight>
+ *     <view>body…</view>
+ *   </Screen>
+ * ));
+ * ```
+ *
+ * `<Screen>` itself renders its `default` slot inline — so the body lives
+ * where you'd expect with no extra layout wrapper. The sub-components
+ * (`Screen.Header`, `Screen.HeaderLeft`, `Screen.HeaderRight`,
+ * `Screen.TabBarItem`) render `null` and write into the entry's
+ * `ScreenRegistry`. The navigator's persistent chrome reads from there.
+ *
+ * Note: `<Screen.TabBarItem>` registers a scoped slot fill on the entry's
+ * `ScreenRegistry`, but the built-in `<TabBar>` doesn't read it yet — the
+ * fill is exposed for custom tab-bar renderers (pass `renderTab` and look
+ * up the active entry's registry yourself).
+ *
+ * Sub-component placement inside `<Screen>` is conventional — sigx scopes
+ * are by component tree, so they work anywhere under the same EntryScope.
+ * Placing them as direct children of `<Screen>` keeps the call site
+ * declarative and grep-friendly.
+ */
+import { type Define } from '@sigx/lynx';
+type ScreenProps = Define.Prop<'title', string | (() => string)> & Define.Prop<'headerShown', boolean> & Define.Prop<'gestureEnabled', boolean> & Define.Slot<'default'>;
+type SimpleSlotProps = Define.Slot<'default'>;
+/**
+ * `<Screen.TabBarItem>` — scoped slot. The default slot is a function that
+ * receives `{ active }`; whatever it returns is the tab-bar item content.
+ *
+ * Sigx's `Define.Slot<'default', { active: boolean }>` would express this
+ * directly on the component, but since `<Screen.TabBarItem>`'s parent
+ * (the user's tree, not the navigator) doesn't actually pass `active`, we
+ * accept a plain default slot whose body is itself a function. The
+ * navigator's TabBar invokes that function with the active flag.
+ */
+type TabBarItemProps = Define.Slot<'default'>;
+/**
+ * Compound export. `Screen` is callable as a JSX element and exposes the
+ * sub-components as properties (`Screen.Header`, etc.) for the declarative
+ * call site shown in the file header.
+ */
+export declare const Screen: ((props: {
+    gestureEnabled?: boolean | undefined;
+    headerShown?: boolean | undefined;
+    title?: string | (() => string) | undefined;
+} & {} & {
+    slots?: Partial<{
+        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+    }> | undefined;
+} & {} & JSX.IntrinsicAttributes & import("@sigx/runtime-core").ComponentAttributeExtensions & {
+    ref?: import("@sigx/runtime-core").Ref<void> | undefined;
+    children?: any;
+}) => import("@sigx/runtime-core").JSXElement) & {
+    __setup: import("@sigx/runtime-core").SetupFn<{
+        gestureEnabled?: boolean | undefined;
+        headerShown?: boolean | undefined;
+        title?: string | (() => string) | undefined;
+    }, ScreenProps, void, {
+        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+    }>;
+    __name?: string;
+    __islandId?: string;
+    __props: {
+        gestureEnabled?: boolean | undefined;
+        headerShown?: boolean | undefined;
+        title?: string | (() => string) | undefined;
+    };
+    __events: ScreenProps;
+    __ref: void;
+    __slots: {
+        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+    };
+} & {
+    Header: import("@sigx/runtime-core").ComponentFactory<SimpleSlotProps, void, {
+        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+    }>;
+    HeaderLeft: import("@sigx/runtime-core").ComponentFactory<SimpleSlotProps, void, {
+        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+    }>;
+    HeaderRight: import("@sigx/runtime-core").ComponentFactory<SimpleSlotProps, void, {
+        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+    }>;
+    TabBarItem: import("@sigx/runtime-core").ComponentFactory<TabBarItemProps, void, {
+        default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+    }>;
+};
+export {};

package/src/components/Screen.tsx

@@ -31,8 +31,9 @@
  * declarative and grep-friendly.
  */
 import { component, onUnmounted, type Define } from '@sigx/lynx';
-import { useScreenRegistry } from '../hooks/use-nav-internal.js';
-import { mergeOptions, setSlot } from '../internal/screen-registry.js';
+import { useScreenRegistry } from '../hooks/use-nav-internal';
+import { mergeOptions, setSlot } from '../internal/screen-registry';
+import type { ScreenOptions } from '../types';
 
 type ScreenProps =
     & Define.Prop<'title', string | (() => string)>
@@ -42,15 +43,16 @@ type ScreenProps =
 
 const ScreenRoot = component<ScreenProps>(({ props, slots }) => {
     const registry = useScreenRegistry();
-    // Apply options whenever the component sets up. Options are reactive
-    // through the registry's `options` signal — chrome consumers re-render
-    // on the next merge. We don't bother diffing here: the patch is small
-    // and writes only happen during setup + explicit prop changes upstream.
-    mergeOptions(registry, {
-        title: props.title,
-        headerShown: props.headerShown,
-        gestureEnabled: props.gestureEnabled,
-    });
+    // Apply options whenever the component sets up. Only set keys that
+    // were actually passed — `mergeOptions` treats `undefined` as "clear
+    // this key", so building the patch from raw `props.X` would wipe
+    // every option a previous `useScreenOptions(...)` (or another `<Screen>`)
+    // had set on this same entry.
+    const patch: ScreenOptions = {};
+    if (props.title !== undefined) patch.title = props.title;
+    if (props.headerShown !== undefined) patch.headerShown = props.headerShown;
+    if (props.gestureEnabled !== undefined) patch.gestureEnabled = props.gestureEnabled;
+    mergeOptions(registry, patch);
     return () => slots.default?.();
 });
 

package/src/components/Stack.d.ts

@@ -0,0 +1,90 @@
+import { type Define } from '@sigx/lynx';
+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'>;
+/**
+ * Stack navigator — renders the topmost stack entry's component at rest, or
+ * the top + underneath entries during a transition.
+ *
+ * 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>
+ * ```
+ *
+ * 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.
+ *
+ * **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 declare const Stack: import("@sigx/runtime-core").ComponentFactory<StackProps, void, {
+    default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+}>;
+export {};

package/src/components/Stack.tsx

@@ -5,24 +5,21 @@ 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 { createNavigatorState } from '../navigator/core';
+import { useNav, type Nav } from '../hooks/use-nav';
 import {
     useCurrentEntry,
     useNavInternals,
     useNavRoutes,
     type NavInternals,
-} from '../hooks/use-nav-internal.js';
-import type { Presentation, StackEntry } from '../types.js';
-import { ScreenContainer } from './ScreenContainer.js';
-import { EdgeBackHandle } from './EdgeBackHandle.js';
-import { EntryScope } from './EntryScope.js';
-import { useTabScreenName, useTabs } from './Tabs.js';
+} 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 =
     /**
@@ -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.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>