@sigx/lynx-navigation 0.1.0 → 0.1.2

package/src/components/Tabs.tsx

@@ -0,0 +1,216 @@
+/**
+ * `<Tabs>` — Lynx tab navigator.
+ *
+ * Usage:
+ *
+ * ```tsx
+ * <NavigationRoot routes={routes}>
+ *   <Tabs initialTab="feed">
+ *     <Tabs.Screen name="feed" icon={<FeedIcon />} label="Feed">
+ *       <FeedView />
+ *     </Tabs.Screen>
+ *     <Tabs.Screen name="me" icon={<MeIcon />} label="Profile">
+ *       <ProfileView />
+ *     </Tabs.Screen>
+ *   </Tabs>
+ * </NavigationRoot>
+ * ```
+ *
+ * Scope of this slice (v0.1): pure UI primitive. Each tab's body stays
+ * mounted for state preservation (the inactive ones render with
+ * `display: 'none'`). Active tab is reactive via `useTabs()`.
+ *
+ * Out of scope (deferred to a nested-navigators slice):
+ *   - Per-tab `<Stack>` with its own navigator state machine
+ *   - `nav.parent` chain into the Tabs nav
+ *   - Named navigators (`useNav('root')`)
+ *
+ * Those build on multi-navigator-state plumbing that isn't ready yet.
+ * For now, the inner content of a `<Tabs.Screen>` shares the same nav as
+ * its outer `<NavigationRoot>` — usable for shallow tab apps, but full
+ * nested routing comes later.
+ */
+import {
+    component,
+    compound,
+    defineInjectable,
+    defineProvide,
+    onUnmounted,
+    signal,
+    untrack,
+    type Define,
+    type JSXElement,
+    type Signal,
+} from '@sigx/lynx';
+
+/** Metadata about a registered `<Tabs.Screen>`. */
+export interface TabInfo {
+    /** Stable tab id, used by `setActive`. */
+    readonly name: string;
+    /** Optional icon node — passed through to the default tab bar. */
+    readonly icon?: JSXElement;
+    /** Optional human-readable label. Defaults to `name`. */
+    readonly label?: string;
+    /**
+     * Accessibility label announced by screen readers. Falls back to
+     * `label`, then `name`. Surfaced as `accessibility-label` on the
+     * default `<TabBar>` button.
+     */
+    readonly accessibilityLabel?: string;
+}
+
+/** Reactive controller exposed by `useTabs()`. */
+export interface TabsNav {
+    /** Currently-active tab name. Reactive — accessing inside render/effect tracks. */
+    readonly active: string;
+    /** Switch the active tab. Triggers reactive updates in any consumer. */
+    setActive(name: string): void;
+    /** Snapshot of registered tabs in registration order. Reactive. */
+    readonly tabs: ReadonlyArray<TabInfo>;
+}
+
+/**
+ * Access the enclosing Tabs navigator. Throws when called outside `<Tabs>`.
+ */
+export const useTabs = defineInjectable<TabsNav>(() => {
+    throw new Error(
+        '[lynx-navigation] useTabs() called outside of a <Tabs> component.',
+    );
+});
+
+/**
+ * Internal registrar used by `<Tabs.Screen>` to announce itself to the
+ * parent `<Tabs>`. Splitting registration off the public `useTabs()` keeps
+ * the public surface read-only.
+ */
+interface TabsRegistrar {
+    register(info: TabInfo): void;
+    unregister(name: string): void;
+    /** Reactive list — mirrors `TabsNav.tabs`, used by `<Tabs.Screen>` to
+     *  decide whether it's the active tab. */
+    readonly tabs: Signal<TabInfo[]>;
+    readonly activeSignal: Signal<{ value: string | null }>;
+}
+
+const useTabsRegistrar = defineInjectable<TabsRegistrar>(() => {
+    throw new Error(
+        '[lynx-navigation] <Tabs.Screen> rendered outside a <Tabs> component.',
+    );
+});
+
+type TabsProps =
+    & Define.Prop<'initialTab', string>
+    & Define.Slot<'default'>;
+
+const _Tabs = component<TabsProps>(({ props, slots }) => {
+    // Tabs are stored as a deeply-reactive proxy signal so `tabs` consumers
+    // re-render when registration changes. `activeSignal` uses the wrapped
+    // `{value}` pattern so we can write a `string | null` without the
+    // proxy treating the inner string as an object.
+    const tabs = signal<TabInfo[]>([]);
+    const activeSignal: Signal<{ value: string | null }> = signal({
+        value: props.initialTab ?? null,
+    });
+
+    const registrar: TabsRegistrar = {
+        register(info) {
+            // Wrap in untrack so registration writes inside `<Tabs.Screen>`'s
+            // setup phase don't notify the same setup effect that issued them
+            // — sigx's setup runs in a tracked scope by default.
+            untrack(() => {
+                const idx = tabs.findIndex((t) => t.name === info.name);
+                if (idx === -1) tabs.push(info);
+                else tabs[idx] = info;
+                if (activeSignal.value === null) {
+                    activeSignal.value = info.name;
+                }
+            });
+        },
+        unregister(name) {
+            untrack(() => {
+                const idx = tabs.findIndex((t) => t.name === name);
+                if (idx !== -1) tabs.splice(idx, 1);
+                if (activeSignal.value === name) {
+                    activeSignal.value = tabs[0]?.name ?? null;
+                }
+            });
+        },
+        tabs,
+        activeSignal,
+    };
+
+    const nav: TabsNav = {
+        get active() {
+            // Empty-tabs state is rare in practice (no <Tabs.Screen> yet) but
+            // possible during initial render; expose '' rather than null so
+            // consumers can compare strings without narrowing.
+            return activeSignal.value ?? '';
+        },
+        setActive(name) {
+            // Silently ignore unknown names rather than writing them and
+            // hiding every tab body. Surfacing as a no-op gives consumers a
+            // predictable failure mode for typos / dynamic name sources.
+            if (!tabs.some((t) => t.name === name)) return;
+            activeSignal.value = name;
+        },
+        get tabs() {
+            return tabs;
+        },
+    };
+
+    defineProvide(useTabs, () => nav);
+    defineProvide(useTabsRegistrar, () => registrar);
+
+    return () => slots.default?.();
+});
+
+type TabsScreenProps =
+    & Define.Prop<'name', string, true>
+    & Define.Prop<'icon', JSXElement>
+    & Define.Prop<'label', string>
+    & Define.Prop<'accessibilityLabel', string>
+    & Define.Slot<'default'>;
+
+const TabsScreen = component<TabsScreenProps>(({ props, slots }) => {
+    const registrar = useTabsRegistrar();
+    // Capture `name` once at setup. Props is reactive in sigx, but using a
+    // changing `name` for an already-registered screen would be ambiguous
+    // (rename vs re-register?) — pin it and require callers to remount on
+    // identity change. This matches React Navigation's contract.
+    const name = props.name;
+    registrar.register({
+        name,
+        icon: props.icon,
+        label: props.label,
+        accessibilityLabel: props.accessibilityLabel,
+    });
+    onUnmounted(() => registrar.unregister(name));
+
+    return () => {
+        // `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.
+        const active = registrar.activeSignal.value === name;
+        return (
+            <view
+                style={{
+                    display: active ? 'flex' : 'none',
+                    width: '100%',
+                    height: '100%',
+                }}
+            >
+                {slots.default?.()}
+            </view>
+        );
+    };
+});
+
+/**
+ * Compound export. `Tabs` is the parent component; `Tabs.Screen` registers
+ * an individual tab. Matches the `Screen` / `Screen.Header` shape used
+ * elsewhere in this package and the daisyui `Modal` / `Modal.Header`
+ * convention.
+ */
+export const Tabs = compound(_Tabs, {
+    Screen: TabsScreen,
+});

package/src/hooks/use-focus.ts

@@ -0,0 +1,88 @@
+import {
+    computed,
+    effect,
+    onUnmounted,
+    untrack,
+    type Computed,
+} from '@sigx/lynx';
+import { useNav } from './use-nav.js';
+import { useCurrentEntry } from './use-nav-internal.js';
+
+/**
+ * Reactive "is this screen the focused entry?" signal.
+ *
+ * Must be called from inside a component rendered as a route by `<Stack>` (or
+ * any other navigator that uses `<EntryScope>`); throws otherwise. The
+ * returned `Computed` reads `nav.current.key` and compares it to the entry
+ * the calling screen was mounted for, so any nav mutation that changes the
+ * top entry flips the value.
+ *
+ * Note: screens stay mounted when something is pushed on top of them — they
+ * just lose focus. Pop the new top off and they regain focus.
+ *
+ * @example
+ * ```tsx
+ * const Profile = component(() => {
+ *     const isFocused = useIsFocused();
+ *     return () => <text>{isFocused.value ? 'visible' : 'hidden'}</text>;
+ * });
+ * ```
+ */
+export function useIsFocused(): Computed<boolean> {
+    const nav = useNav();
+    // Capture the entry's key once at setup. The entry object provided
+    // through `defineProvide` may carry reactive dependencies; we only care
+    // about the immutable key of the entry this screen was mounted for.
+    const myKey = useCurrentEntry().key;
+    return computed(() => nav.current.key === myKey);
+}
+
+/**
+ * Run `cb` whenever this screen gains focus; run the returned cleanup when it
+ * loses focus or unmounts. Mirrors React Navigation's `useFocusEffect`.
+ *
+ * Lifecycle:
+ *  - cb runs immediately if the screen is already focused at mount.
+ *  - When the screen loses focus (something pushed on top), cleanup runs.
+ *  - When focus returns (the cover is popped), `cb` runs again — yielding a
+ *    fresh cleanup for the next blur.
+ *  - On unmount, cleanup runs once if still focused.
+ *
+ * Common uses: subscribe to a data source while visible, track an analytics
+ * "screen view" event, start/stop a polling loop.
+ *
+ * @example
+ * ```tsx
+ * useFocusEffect(() => {
+ *     const id = setInterval(refresh, 5000);
+ *     return () => clearInterval(id);
+ * });
+ * ```
+ */
+export function useFocusEffect(cb: () => void | (() => void)): void {
+    const isFocused = useIsFocused();
+    let cleanup: (() => void) | void;
+    const runner = effect(() => {
+        const focused = isFocused.value;
+        // Always tear down any previous focus session before starting a new
+        // one (or before going dormant on blur). Wrap `cb` in `untrack` so
+        // signals read inside the user-provided callback can't retrigger the
+        // outer effect and stack subscriptions.
+        if (typeof cleanup === 'function') {
+            const fn = cleanup;
+            cleanup = undefined;
+            fn();
+        }
+        if (focused) {
+            cleanup = untrack(() => cb());
+        }
+    });
+    onUnmounted(() => {
+        if (typeof cleanup === 'function') {
+            const fn = cleanup;
+            cleanup = undefined;
+            fn();
+        }
+        runner.stop();
+    });
+}

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

@@ -0,0 +1,159 @@
+import { onMounted } from '@sigx/lynx';
+import { Linking } from '@sigx/lynx-linking';
+import { parseHref, type Href } from '../href.js';
+import { useNav, type Nav } from './use-nav.js';
+import { useNavRoutes } from './use-nav-internal.js';
+import type { RouteMap } from '../types.js';
+
+export interface UseLinkingNavOptions {
+    /**
+     * Schemes/prefixes to strip before parsing. Matched in order; the first
+     * match wins. Example: `['myapp://', 'https://myapp.com']` lets
+     * `https://myapp.com/users/42` parse against the same routes as
+     * `/users/42`.
+     *
+     * After stripping, a leading `/` is added if missing so the result is a
+     * valid pathname.
+     */
+    prefixes?: string[];
+
+    /**
+     * Custom handler invoked instead of the default dispatch. Use this when
+     * you need to intercept (e.g. for auth callbacks, analytics) before
+     * routing. If you call `nav.push` / `nav.replace` from here, the default
+     * dispatch is skipped — return `void`.
+     */
+    onURL?: (url: string, nav: Nav) => void;
+
+    /**
+     * Called when an incoming URL doesn't match any registered route's `path`
+     * template (or fails schema validation). Defaults to a no-op so unknown
+     * URLs are dropped silently. Use this to surface "page not found" UX or
+     * to forward to a catch-all route.
+     */
+    onUnmatched?: (url: string) => void;
+
+    /**
+     * Whether to use `nav.replace` instead of `nav.push` for the cold-start
+     * initial URL. Defaults to `true` — restoring an app into a deep link
+     * shouldn't leave a stray "initial route" entry beneath it that the back
+     * button can return to.
+     *
+     * Runtime URLs (from `addEventListener`) always `push`.
+     */
+    replaceInitial?: boolean;
+}
+
+/**
+ * Bridge `@sigx/lynx-linking` URL events into a `@sigx/lynx-navigation`
+ * navigator. Call once inside a `<NavigationRoot>` subtree.
+ *
+ * Handles both delivery modes:
+ *   - **cold start** — `Linking.getInitialURL()` is read on mount and, if
+ *     present, dispatched (replacing the initial route by default).
+ *   - **warm start** — `Linking.addEventListener('url', ...)` subscribes for
+ *     URLs delivered while the app is already running; each one is pushed.
+ *
+ * URL → route dispatch goes through `parseHref`, which matches the URL's
+ * pathname against the route registry seeded by `<NavigationRoot>`. Routes
+ * without a `path` template are never matched by deep links — only typed
+ * `<Link>` / `nav.push` calls reach them.
+ *
+ * @example
+ * ```tsx
+ * import { useLinkingNav } from '@sigx/lynx-navigation';
+ *
+ * const DeepLinks = component(() => {
+ *     useLinkingNav({
+ *         prefixes: ['myapp://', 'https://myapp.com'],
+ *         onUnmatched: (url) => console.warn('Unknown deep link:', url),
+ *     });
+ *     return () => null;
+ * });
+ *
+ * <NavigationRoot routes={routes}>
+ *     <DeepLinks />
+ *     <Stack />
+ * </NavigationRoot>
+ * ```
+ */
+export function useLinkingNav(opts: UseLinkingNavOptions = {}): void {
+    const nav = useNav();
+    const routes = useNavRoutes();
+
+    const dispatch = (url: string, kind: 'push' | 'replace'): void => {
+        if (opts.onURL) {
+            opts.onURL(url, nav);
+            return;
+        }
+        const stripped = _stripPrefix(url, opts.prefixes);
+        const href = parseHref(stripped);
+        if (!href) {
+            opts.onUnmatched?.(url);
+            return;
+        }
+        _navigateToHref(nav, routes, href, kind);
+    };
+
+    onMounted(() => {
+        const initial = Linking.getInitialURL();
+        if (initial) {
+            dispatch(initial, opts.replaceInitial === false ? 'push' : 'replace');
+        }
+        const sub = Linking.addEventListener('url', (e) => dispatch(e.url, 'push'));
+        return () => sub.remove();
+    });
+}
+
+/**
+ * Strip the first matching prefix from `url`, returning a pathname-like
+ * string. If no prefixes are provided, or none match, the original URL is
+ * returned unchanged so `parseHref` can still handle scheme-prefixed forms
+ * via `@sigx/lynx-linking`'s `parse`.
+ *
+ * Exported for unit testing — not part of the package public API.
+ */
+export function _stripPrefix(url: string, prefixes?: string[]): string {
+    if (!prefixes || prefixes.length === 0) return url;
+    for (const prefix of prefixes) {
+        if (url.startsWith(prefix)) {
+            const rest = url.slice(prefix.length);
+            return rest.startsWith('/') ? rest : `/${rest}`;
+        }
+    }
+    return url;
+}
+
+/**
+ * Call the right `nav.push` / `nav.replace` overload for `href`. The
+ * overloads differ in positional layout: routes with a params schema take
+ * `(name, params, search?, options?)`; routes without take `(name, search?,
+ * options?)`. Calling the wrong shape silently shifts `search` into the
+ * `options` slot, so we look the route up in the registry and branch.
+ *
+ * Exported for unit testing — not part of the package public API.
+ */
+export function _navigateToHref(
+    nav: Nav,
+    routes: RouteMap,
+    href: Href,
+    kind: 'push' | 'replace',
+): void {
+    const def = routes[href.route];
+    // Defensive: `parseHref` already validated against the registry, so this
+    // really shouldn't happen — but if the registry was cleared between
+    // parse and dispatch (multi-NavigationRoot scenarios), bail rather than
+    // throw.
+    if (!def) return;
+    const hasParams = !!def.params;
+    const action = kind === 'replace' ? nav.replace : nav.push;
+    if (hasParams) {
+        (action as (n: string, p: unknown, s?: unknown) => void)(
+            href.route,
+            href.params,
+            href.search,
+        );
+    } else {
+        (action as (n: string, s?: unknown) => void)(href.route, href.search);
+    }
+}

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

@@ -1,5 +1,23 @@
 import { defineInjectable, type SharedValue } from '@sigx/lynx';
-import type { RouteMap } from '../types.js';
+import type { ScreenRegistry } from '../internal/screen-registry.js';
+import type { RouteMap, StackEntry } from '../types.js';
+
+/**
+ * Internal injectable: the `StackEntry` the calling screen was rendered for.
+ *
+ * Provided by `<EntryScope>` which `<Stack>` and `<ScreenContainer>` wrap
+ * around each screen component mount. Screens use this to derive their own
+ * focus state (`useIsFocused`, `useFocusEffect`) without having to track
+ * `entry.key` themselves.
+ *
+ * Default throws so calling `useIsFocused()` outside a screen mounted by a
+ * navigator surfaces a clear error rather than silently returning `false`.
+ */
+export const useCurrentEntry = defineInjectable<StackEntry>(() => {
+    throw new Error(
+        '[lynx-navigation] No screen entry in scope. `useIsFocused` / `useFocusEffect` must be called from a component rendered as a route by <Stack>.',
+    );
+});
 
 /**
  * Internal injectable: the route registry passed into `<NavigationRoot>`.
@@ -38,6 +56,17 @@ export interface NavInternals {
     cancelBackGesture(): void;
     /** Whether the user opted into the edge-swipe-back gesture. */
     readonly edgeSwipeEnabled: boolean;
+    /**
+     * Cross-entry screen registry controller. `<EntryScope>` calls
+     * `register` on mount and `unregister` on unmount. Persistent chrome
+     * (HeaderBar / TabBar — later slices) calls `get(entryKey)` to read
+     * the focused screen's options + slot fills without remounting itself.
+     */
+    readonly screens: {
+        register(registry: ScreenRegistry): void;
+        unregister(entryKey: string): void;
+        get(entryKey: string): ScreenRegistry | undefined;
+    };
 }
 
 export const useNavInternals = defineInjectable<NavInternals>(() => {
@@ -45,3 +74,21 @@ export const useNavInternals = defineInjectable<NavInternals>(() => {
         '[lynx-navigation] No <NavigationRoot> found in the component tree.',
     );
 });
+
+/**
+ * Internal injectable: the calling screen's `ScreenRegistry`.
+ *
+ * Provided by `<EntryScope>` alongside `useCurrentEntry`. The `<Screen>`
+ * component and its slot-filling sub-components write options and slot
+ * fills here; the navigator's persistent chrome (HeaderBar, TabBar — later
+ * slices) reads from this registry via `getScreenRegistry(key)` on the
+ * navigator state, which keys into a cross-entry map.
+ *
+ * Throws when used outside an EntryScope so calling `<Screen>` at the app
+ * root surfaces a clear error rather than silently no-op'ing.
+ */
+export const useScreenRegistry = defineInjectable<ScreenRegistry>(() => {
+    throw new Error(
+        '[lynx-navigation] No screen registry in scope. `<Screen>` (and `<Screen.Header>`, etc.) must be used inside a route component rendered by `<Stack>`.',
+    );
+});