@symbiote-native/navigation 2.0.3 → 2.2.0

package/build/solid/tabs/index.js

@@ -0,0 +1,228 @@
+// Tab, the Solid lifecycle half. The focused-index router (tab-router-state) and the tab-bar
+// Descriptor builder (render-tabs) live in @symbiote-native/navigation core, shared verbatim with
+// every other adapter; here Solid supplies the lifecycle - a signal for the dispatched router
+// state, a callback `ref` for the jumpTo/setParams handle - plus the descriptor bridge for the
+// tab-bar leaf. Unlike Stack, a bottom-tabs bar is a PURE-JS UI painting ordinary
+// `symbiote-view`/`symbiote-text` primitives, so there is no react-native-screens ViewConfig to
+// register here.
+//
+// TWO SOLID-ONLY REBUILD BOUNDARIES, both invisible in every other adapter:
+//
+// 1. THE TAB BAR'S SHAPE FOLLOWS ITS DATA. renderTabBar emits one child per item, and each item
+//    emits an icon wrapper only when it has an icon or a badge - so adding a screen, or a badge
+//    appearing, CHANGES the Descriptor's shape, which descriptorToSolid's shape guard rejects by
+//    design (it builds once and updates props in place). `barSignature` captures exactly the parts
+//    of the data the shape depends on, and the bar is rebuilt when that string changes and only
+//    then. Every other adapter re-renders the whole bar every time and never meets this.
+//
+// 2. ONLY THE FOCUSED SCREEN IS MOUNTED, so a focus change is a genuine rebuild while a
+//    `setParams` on the focused route must NOT be. The content memo therefore depends on the
+//    focused route KEY and its component identity alone, with the build `untrack`ed
+//    (.claude/rules/solid-descriptor-bridge.md §5); the route object itself reaches the screen
+//    through the scope accessor, which is what keeps useRoute() live without rebuilding anything.
+import { createEffect, createMemo, createSignal, untrack } from 'solid-js';
+import { descriptorToSolid } from '@symbiote-native/solid';
+// createComponent from solid-js, insert from the renderer - see stack/index.ts's note.
+import { createComponent } from 'solid-js';
+import { insert } from '@symbiote-native/solid/renderer';
+import { dlog } from '@symbiote-native/engine';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS, createInitialTabState, createNavigationEmitter, diffFocusedRoute, isFocusedRoute, reconcileTabRoutes, renderTabBar, tabRouterReducer, } from '../../core/index.js';
+import { hostElement } from '../host.js';
+import { NavigationScopeProvider, useNavigationScope, } from '../navigation-context.js';
+import { ScreenCollectorProvider, createScreenSignal, toRegistry, } from '../screen-registry.js';
+import { TabScreen } from '../screen.js';
+const TAB_CONTENT_STYLE = { flex: 1 };
+const TAB_ROOT_STYLE = { flex: 1 };
+let navigatorSequence = 0;
+function resolveTabOptions(entry, args, screenOptions) {
+    const own = typeof entry.options === 'function' ? entry.options(args) : entry.options;
+    return { ...screenOptions, ...own };
+}
+// A Descriptor icon is spliced into the bar verbatim, so only its ROOT type is visible here - an
+// app that swaps one Descriptor icon for another of the same type but a different child count
+// would still trip the bridge's shape guard, with the guard's own message. That is the honest
+// boundary: this signature covers the shape decisions render-tabs.ts itself makes.
+function iconKind(icon) {
+    if (icon === undefined)
+        return '-';
+    return typeof icon === 'string' ? 'glyph' : icon.type;
+}
+function barSignature(items) {
+    return items
+        .map(item => `${item.key}:${iconKind(item.icon)}:${item.badge === undefined ? 0 : 1}`)
+        .join('|');
+}
+function TabImpl(props) {
+    // Read BEFORE this Tab provides its own per-screen scope - becomes the `parent` link a nested
+    // screen's useNavigation().getParent() walks. undefined when this Tab is the nesting root.
+    const parentScope = useNavigationScope();
+    const { screens, collector } = createScreenSignal('tab');
+    const registry = createMemo(() => toRegistry(screens()));
+    navigatorSequence += 1;
+    const routeIdPrefix = `tab-${navigatorSequence}`;
+    // Route keys are derived from the screen NAME, never a counter: a Tab's route list is rebuilt
+    // from the registry on every registration change, and a counter would mint a fresh key each time,
+    // re-mounting every screen for an unrelated marker edit.
+    const routes = createMemo(() => [...registry().entries()].map(([name, entry]) => ({
+        key: `${routeIdPrefix}-${name}`,
+        name,
+        params: entry.initialParams,
+    })));
+    // `null` means nothing has dispatched yet, which is what keeps initialRouteName honored when the
+    // markers arrive after the body has already run (screen-registry.ts).
+    const [dispatched, setDispatched] = createSignal(null);
+    const state = createMemo(() => {
+        const current = routes();
+        const previous = dispatched();
+        return previous === null
+            ? createInitialTabState(current, props.initialRouteName)
+            : reconcileTabRoutes(previous, current);
+    });
+    function dispatch(action) {
+        setDispatched(tabRouterReducer(state(), action));
+    }
+    const jumpTo = (name, params) => dispatch({ type: 'jumpTo', name, params });
+    const setParams = (params, key) => dispatch({ type: 'setParams', key, params });
+    const handle = { jumpTo, setParams };
+    props.ref?.(handle);
+    // One emitter per route.key, created lazily and cached for the navigator's whole lifetime. Emitter
+    // IDENTITY (stable, looked up by key) is deliberately decoupled from emit TIMING (deferred below):
+    // a scheme that recreated the emitter on each focus change raced the build of the very screen that
+    // was supposed to subscribe to it.
+    const emitters = new Map();
+    function emitterFor(routeKey) {
+        let emitter = emitters.get(routeKey);
+        if (emitter === undefined) {
+            emitter = createNavigationEmitter();
+            emitters.set(routeKey, emitter);
+        }
+        return emitter;
+    }
+    const focusedKey = createMemo(() => {
+        const current = state();
+        return current.routes[current.index]?.key;
+    });
+    // Tab paints its own bar in pure JS - there is no native onAppear/onDisappear to hook (unlike
+    // Stack's RNSScreen), so focus/blur is synthesized here. The emit is deferred to a microtask,
+    // which resolves only after Solid's whole effect flush has drained - including the build of the
+    // newly focused screen and the subscriptions createIsFocused/createFocusEffect register inside
+    // it. Emitting inline would reach zero subscribers.
+    let lastFocusedKey;
+    createEffect(() => {
+        const nextKey = focusedKey();
+        const { blurKey, focusKey } = diffFocusedRoute(lastFocusedKey, nextKey);
+        if (blurKey === undefined && focusKey === undefined)
+            return;
+        lastFocusedKey = nextKey;
+        queueMicrotask(() => {
+            if (blurKey !== undefined) {
+                dlog(`Tab: route "${blurKey}" blurred at t=${Date.now()}`);
+                emitterFor(blurKey).emit(NAVIGATION_EVENT_BLUR);
+            }
+            if (focusKey !== undefined) {
+                dlog(`Tab: route "${focusKey}" focused at t=${Date.now()}`);
+                emitterFor(focusKey).emit(NAVIGATION_EVENT_FOCUS);
+            }
+        });
+    });
+    const items = createMemo(() => {
+        const current = state();
+        const entries = registry();
+        return current.routes.map((route, index) => {
+            const entry = entries.get(route.name);
+            const focused = isFocusedRoute(index, current.index);
+            if (entry === undefined) {
+                dlog(`Tab: no screen registered for route name "${route.name}"`);
+                return { key: route.key, focused, label: route.name, passthrough: {} };
+            }
+            const options = resolveTabOptions(entry, { route, navigation: handle }, props.screenOptions);
+            return {
+                key: route.key,
+                focused,
+                label: options.tabBarLabel ?? options.title ?? route.name,
+                icon: options.tabBarIcon,
+                badge: options.tabBarBadge,
+                activeTintColor: options.tabBarActiveTintColor,
+                inactiveTintColor: options.tabBarInactiveTintColor,
+                passthrough: {
+                    onPress: () => jumpTo(route.name),
+                    accessibilityRole: 'tab',
+                    accessibilityState: { selected: focused },
+                },
+            };
+        });
+    });
+    const focusedOptions = createMemo(() => {
+        const current = state();
+        const route = current.routes[current.index];
+        const entry = route === undefined ? undefined : registry().get(route.name);
+        if (entry === undefined || route === undefined)
+            return props.screenOptions;
+        return resolveTabOptions(entry, { route, navigation: handle }, props.screenOptions);
+    });
+    // Header note 1: the bar is rebuilt only when its Descriptor SHAPE would change; every tint,
+    // label and badge-value change flows through descriptorToSolid's prop diff on the live nodes.
+    const barShape = createMemo(() => barSignature(items()));
+    const tabBar = createMemo(() => {
+        barShape();
+        return untrack(() => descriptorToSolid(() => renderTabBar({
+            items: items(),
+            style: focusedOptions()?.tabBarStyle,
+            passthrough: {},
+        })));
+    });
+    // Header note 2. Only the focused route's screen is ever mounted (unlike Stack, which keeps every
+    // pushed route alive), so the previous screen's whole subtree - and every listener it registered
+    // - is torn down by Solid's ordinary disposal when focus moves on.
+    const focusedComponent = createMemo(() => {
+        const current = state();
+        const route = current.routes[current.index];
+        return route === undefined
+            ? undefined
+            : registry().get(route.name)?.component;
+    });
+    const content = createMemo(() => {
+        const routeKey = focusedKey();
+        const Component = focusedComponent();
+        return untrack(() => {
+            if (routeKey === undefined || Component === undefined)
+                return undefined;
+            const scope = () => ({
+                route: routeFor(routeKey),
+                navigation: handle,
+                emitter: emitterFor(routeKey),
+                parent: parentScope?.(),
+            });
+            return createComponent(NavigationScopeProvider, {
+                value: scope,
+                // No route/navigation props: the screen reads both through the primitives off the scope
+                // provided here (useRoute / useTabNavigation).
+                get children() {
+                    return createComponent(Component, {});
+                },
+            });
+        });
+    });
+    // Reads the CURRENT object for a key rather than closing over the one that was focused at build
+    // time - the accessor is what makes `setParams` reach a mounted screen's useRoute().
+    function routeFor(routeKey) {
+        const found = state().routes.find(route => route.key === routeKey);
+        return found ?? { key: routeKey, name: '', params: undefined };
+    }
+    const contentHost = hostElement('symbiote-view', () => ({
+        style: TAB_CONTENT_STYLE,
+    }));
+    insert(contentHost, content);
+    const root = hostElement('symbiote-view', () => ({ style: TAB_ROOT_STYLE }));
+    // ONE array insert rather than two: a second `insert` on the same parent would find the first
+    // child already there and REPLACE it (solid-js/universal's insertExpression), while an array is
+    // reconciled by identity - contentHost keeps its node, only the bar is swapped when it rebuilds.
+    insert(root, () => [contentHost, tabBar()]);
+    return createComponent(ScreenCollectorProvider, {
+        value: collector,
+        get children() {
+            return [props.children, root];
+        },
+    });
+}
+export const Tab = Object.assign(TabImpl, { Screen: TabScreen });

package/build/svelte/attachments.d.ts

@@ -0,0 +1,5 @@
+import type { ISearchBarCommands } from '../core';
+export declare function hostProps(props: Record<string, unknown>): (node: unknown) => void;
+export declare function searchBarRef(ref: {
+    current: ISearchBarCommands | null;
+} | undefined): (node: unknown) => (() => void) | void;

package/build/svelte/attachments.js

@@ -0,0 +1,61 @@
+// Svelte attachments (`{@attach ...}`) for the react-native-screens native leaves.
+//
+// WHY THESE EXIST AT ALL: every react-native-screens Fabric view name is capitalized and
+// un-hyphenated (RNSScreen, RNSScreenStack, RNSScreenStackHeaderConfig, RNSSearchBar, ...), so a
+// literal `<RNSScreen>` in a Svelte template parses as a COMPONENT reference, not an element -
+// the same wall @symbiote-native/slider's 'RNCSlider' leaf hit. Slider sidestepped it by mounting
+// the whole leaf through the Descriptor bridge, which works because that leaf carries no live
+// framework children. A stack screen DOES (the app's own screen component lives inside
+// RNSScreenContentWrapper), so the bridge is not an option here.
+//
+// The way through is `<svelte:element this={'RNSScreen'}>`: it creates the element via
+// `document.createElement(tag)` with a plain runtime string the compiler never inspects, and it
+// accepts ordinary framework children. Its one catch is documented in svelte-adapter-dom-shim
+// skill §15 - a dynamic tag compiles through Svelte's generic setAttribute/property-diffing
+// codegen, NOT the custom-element `p=` property-SET path, so writing `p={bag}` as an ATTRIBUTE on
+// it silently fails. An attachment bypasses that entirely: it is handed the raw element and
+// assigns the property from plain JS, then re-runs whenever the props it read change. Verified
+// against the real compiler + the real shim before this was built on.
+import { dlog, isSymbioteNode } from '@symbiote-native/engine';
+import { buildSearchBarHandle } from '../core/index.js';
+// `unknown` rather than `Element`: the value Svelte hands an attachment is one of the DOM shim's
+// own element classes, not a real DOM Element, and a function accepting `unknown` is still
+// assignable everywhere Svelte expects `(element: Element) => ...`.
+function isShimElement(value) {
+    return typeof value === 'object' && value !== null && 'engineNode' in value;
+}
+// The object-bag prop set, the same entry point every adapter's props go through (routeProp).
+// Re-runs on every change of `props`, and the shim's own `p` setter diffs per key from there.
+export function hostProps(props) {
+    return node => {
+        if (!isShimElement(node)) {
+            dlog('navigation: hostProps attached to a non-shim element, ignored');
+            return;
+        }
+        node.p = props;
+    };
+}
+// The Svelte twin of Angular's SearchBarRefDirective / React's and Vue's callback `ref` on the
+// RNSSearchBar element: fills the app-supplied cell once the native node exists and clears it on
+// teardown. buildSearchBarHandle's own getter is LAZY, so handing it the node here is safe even
+// before the first commit.
+export function searchBarRef(ref) {
+    return node => {
+        if (ref === undefined)
+            return;
+        if (!isShimElement(node)) {
+            ref.current = null;
+            return;
+        }
+        const engineNode = node.engineNode;
+        if (!isSymbioteNode(engineNode)) {
+            dlog('navigation: search bar attachment ran before the shim went live');
+            ref.current = null;
+            return;
+        }
+        ref.current = buildSearchBarHandle(() => engineNode);
+        return () => {
+            ref.current = null;
+        };
+    };
+}

package/build/svelte/descriptor-subtree.d.ts

@@ -0,0 +1,3 @@
+import type { ShimElement } from '@symbiote-native/svelte/native-view-bridge';
+import type { IDescriptorChild } from '@symbiote-native/components';
+export declare function createDescriptorSubtreeSync(): (host: ShimElement | null, children: IDescriptorChild[]) => void;

package/build/svelte/descriptor-subtree.js

@@ -0,0 +1,39 @@
+// A shape-CHANGE-tolerant wrapper over @symbiote-native/svelte's Descriptor bridge.
+//
+// `mountDescriptorChildren` (svelte-adapter-dom-shim skill §19) is deliberately shape-stable: it
+// builds each shim node once and only re-sets props thereafter, throwing if the tree shape ever
+// changes, because every `core/components` render-*.ts produces a constant shape. The navigation
+// package's tab bar is the exception - `renderTabBar` emits one child per registered route, and
+// that count genuinely varies (it is 0 until the `<Tab.Screen>` markers have registered, and
+// changes again if a screen is added or removed). Same situation @symbiote-native/slider's own
+// steps-indicator overlay is in, and the same resolution: keep the fast path for the common
+// "same shape, new prop values" case and rebuild only when the shape actually changed.
+//
+// The shape signature covers types and nesting, not just the top-level count, because a tab bar
+// item's own children vary too (an item gains an icon wrapper only when it has an icon or badge).
+import { mountDescriptorChildren } from '@symbiote-native/svelte/native-view-bridge';
+const TEXT_CHILD_MARK = '#';
+function shapeOf(children) {
+    return children
+        .map(child => typeof child === 'string'
+        ? TEXT_CHILD_MARK
+        : `${child.type}(${shapeOf(child.children)})`)
+        .join(',');
+}
+export function createDescriptorSubtreeSync() {
+    let mounted;
+    let shape;
+    return (host, children) => {
+        if (host === null)
+            return;
+        const nextShape = shapeOf(children);
+        if (mounted === undefined || nextShape !== shape) {
+            for (const child of host.children.slice())
+                host.removeChild(child);
+            mounted = mountDescriptorChildren(host, children);
+            shape = nextShape;
+            return;
+        }
+        mounted.update(children);
+    };
+}

package/build/svelte/drawer/drawer-props.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from 'svelte';
+import type { IStyleProp, IViewStyle } from '@symbiote-native/engine';
+import type { IDrawerDescriptorMap, IDrawerNavigatorHandle, IDrawerOptions, IDrawerRouterState } from '../../core';
+export type IDrawerContentSlotProps = {
+    state: IDrawerRouterState;
+    descriptors: IDrawerDescriptorMap;
+    navigation: IDrawerNavigatorHandle;
+};
+export type IDrawerProps = IDrawerOptions & {
+    initialRouteName?: string;
+    drawerStyle?: IStyleProp<IViewStyle>;
+    children?: Snippet;
+    drawerContent?: Snippet<[IDrawerContentSlotProps]>;
+};

package/build/svelte/drawer/drawer-props.js

@@ -0,0 +1,3 @@
+// Drawer's own public prop surface. Plain `.ts` for the tsc-cannot-see-a-`.svelte`-named-export
+// reason ../screen-props.ts documents.
+export {};

package/build/svelte/drawer/index.d.ts

@@ -0,0 +1,10 @@
+export declare const Drawer: import("svelte").Component<import("./drawer-props").IDrawerProps, {
+    openDrawer: () => void;
+    closeDrawer: () => void;
+    toggleDrawer: () => void;
+    jumpTo: (name: string) => void;
+}, ""> & {
+    Screen: import("svelte").Component<import("..").IDrawerScreenProps, {}, "">;
+};
+export type { IDrawerNavigatorHandle, IDrawerDescriptorMap } from '../../core';
+export type { IDrawerContentSlotProps, IDrawerProps } from './drawer-props';

package/build/svelte/drawer/index.js

@@ -0,0 +1,6 @@
+// `Drawer.Screen` alongside the standalone `DrawerScreen` export, matching React's and Vue's
+// barrels - see ../stack/index.ts for why Object.assign is the right mechanism on a compiled
+// Svelte component.
+import DrawerImpl from './index.svelte';
+import DrawerScreen from '../drawer-screen.svelte';
+export const Drawer = Object.assign(DrawerImpl, { Screen: DrawerScreen });