@sigx/lynx-navigation 0.1.3 → 0.4.0

package/src/components/NavigationRoot.tsx

@@ -1,10 +1,10 @@
 import { component, defineProvide, useSharedValue, type Define } from '@sigx/lynx';
-import { createNavigatorState } from '../navigator/core.js';
-import { useNav } from '../hooks/use-nav.js';
-import { useNavInternals, useNavRoutes } from '../hooks/use-nav-internal.js';
-import type { RouteId } from '../register.js';
-import type { Presentation, RouteMap, StackEntry } from '../types.js';
-import { _setRouteRegistry } from '../url/registry.js';
+import { createNavigatorState } from '../navigator/core';
+import { useNav } from '../hooks/use-nav';
+import { useNavInternals, useNavRoutes } from '../hooks/use-nav-internal';
+import type { RouteId } from '../register';
+import type { Presentation, RouteMap, StackEntry } from '../types';
+import { _setRouteRegistry } from '../url/registry';
 
 type NavigationRootProps =
     & Define.Prop<'routes', RouteMap, true>

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 {};