@symbiote-native/navigation 2.1.0 → 3.0.0

package/build/solid/primitives/create-is-focused.js

@@ -0,0 +1,31 @@
+// Mirrors @react-navigation's useIsFocused.
+//
+// `create*`, not `use*`: this OWNS a signal and two emitter subscriptions. Solid reserves `use*`
+// for consuming something that already exists, so a primitive that creates its own state and
+// lifecycle is `createX` (<adapter_src_follows_framework_idioms>; the same reason the adapter
+// spells its colour-scheme primitive `createColorScheme`).
+//
+// Starts `false` rather than guessing from stack position: the route's emitter only fires 'focus'
+// once RNSScreen's native onAppear lands (../stack) or the screen mounts focused (../tabs,
+// ../drawer) - a screen genuinely isn't focused at the instant it mounts, the same async gap real
+// native transitions have.
+//
+// Subscribing SYNCHRONOUSLY in the body rather than from onMount, unlike React/Vue/Svelte: those
+// have to defer past render, and Solid does not. It also matters here - the navigators emit the
+// first 'focus' from a queued microtask after the screen subtree is built, and an onMount-based
+// subscription would still be in the same effect queue, i.e. a race this simply does not enter.
+import { createSignal, onCleanup } from 'solid-js';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS } from '../../core/index.js';
+import { requireNavigationScope } from '../navigation-context.js';
+export function createIsFocused() {
+    const scope = requireNavigationScope('createIsFocused');
+    const [isFocused, setIsFocused] = createSignal(false);
+    const { emitter } = scope();
+    const unsubscribeFocus = emitter.addListener(NAVIGATION_EVENT_FOCUS, () => setIsFocused(true));
+    const unsubscribeBlur = emitter.addListener(NAVIGATION_EVENT_BLUR, () => setIsFocused(false));
+    onCleanup(() => {
+        unsubscribeFocus();
+        unsubscribeBlur();
+    });
+    return isFocused;
+}

package/build/solid/primitives/create-navigation-state.d.ts

@@ -0,0 +1,3 @@
+import type { Accessor } from 'solid-js';
+import type { INavigatorState } from '../../core';
+export declare function createNavigationState<TResult>(selector: (state: INavigatorState) => TResult): Accessor<TResult>;

package/build/solid/primitives/create-navigation-state.js

@@ -0,0 +1,30 @@
+// Mirrors @react-navigation's useNavigationState. The reducer/dispatch machinery lives in
+// core/navigator-state.ts (tab-router-state.ts / drawer-router-state.ts for the other two
+// navigators) - this only wires the subscription to the `state` broadcast each navigator re-emits
+// after its router state changes.
+//
+// `create*`: it owns a signal and a subscription.
+//
+// Seeded from a single-route snapshot ({ routes: [route] }) rather than left undefined: the real
+// broadcast lands after the screen is built, so a selector reading e.g. `state.routes.at(-1)?.name`
+// still resolves correctly on first paint for the common single-route case - the same async gap
+// createIsFocused documents.
+import { createSignal, onCleanup } from 'solid-js';
+import { NAVIGATION_EVENT_STATE, isRecord } from '../../core/index.js';
+import { requireNavigationScope } from '../navigation-context.js';
+function isNavigatorState(value) {
+    return isRecord(value) && Array.isArray(value.routes);
+}
+export function createNavigationState(selector) {
+    const scope = requireNavigationScope('createNavigationState');
+    const [result, setResult] = createSignal(selector({ routes: [scope().route] }));
+    const unsubscribe = scope().emitter.addListener(NAVIGATION_EVENT_STATE, (state) => {
+        if (!isNavigatorState(state))
+            return;
+        // The updater form, not a bare value: a selector legitimately returns a FUNCTION for a
+        // navigation-driven callback, and `setResult(fn)` would otherwise be read as an updater.
+        setResult(() => selector(state));
+    });
+    onCleanup(unsubscribe);
+    return result;
+}

package/build/solid/primitives/index.d.ts

@@ -0,0 +1,12 @@
+export { useNavigation } from './use-navigation';
+export type { INavigationHandle } from './use-navigation';
+export { useStackNavigation } from './use-stack-navigation';
+export type { IStackNavigationHandle } from './use-stack-navigation';
+export { useTabNavigation } from './use-tab-navigation';
+export type { ITabNavigationHandle } from './use-tab-navigation';
+export { useDrawerNavigation } from './use-drawer-navigation';
+export type { IDrawerNavigationHandle } from './use-drawer-navigation';
+export { useRoute } from './use-route';
+export { createIsFocused } from './create-is-focused';
+export { createFocusEffect } from './create-focus-effect';
+export { createNavigationState } from './create-navigation-state';

package/build/solid/primitives/index.js

@@ -0,0 +1,8 @@
+export { useNavigation } from './use-navigation.js';
+export { useStackNavigation } from './use-stack-navigation.js';
+export { useTabNavigation } from './use-tab-navigation.js';
+export { useDrawerNavigation } from './use-drawer-navigation.js';
+export { useRoute } from './use-route.js';
+export { createIsFocused } from './create-is-focused.js';
+export { createFocusEffect } from './create-focus-effect.js';
+export { createNavigationState } from './create-navigation-state.js';

package/build/solid/primitives/use-drawer-navigation.d.ts

@@ -0,0 +1,5 @@
+import type { Accessor } from 'solid-js';
+import type { IDrawerNavigatorHandle } from '../../core';
+import type { INavigationHandle } from './use-navigation';
+export type IDrawerNavigationHandle = IDrawerNavigatorHandle & Pick<INavigationHandle, 'addListener' | 'getParent'>;
+export declare function useDrawerNavigation(): Accessor<IDrawerNavigationHandle>;

package/build/solid/primitives/use-drawer-navigation.js

@@ -0,0 +1,15 @@
+// Twin of use-stack-navigation.ts, narrowing to a Drawer handle instead.
+import { createMemo } from 'solid-js';
+import { isDrawerNavigatorHandle } from '../../core/index.js';
+import { useNavigation } from './use-navigation.js';
+export function useDrawerNavigation() {
+    const navigation = useNavigation();
+    return createMemo(() => {
+        const value = navigation();
+        if (!isDrawerNavigatorHandle(value)) {
+            throw new Error('useDrawerNavigation() was called from a component whose nearest navigator is not a Drawer. ' +
+                'Use useNavigation() instead if this component can render under more than one navigator kind.');
+        }
+        return value;
+    });
+}

package/build/solid/primitives/use-navigation.d.ts

@@ -0,0 +1,8 @@
+import type { Accessor } from 'solid-js';
+import type { INavigationEventListener, INavigationEventName } from '../../core';
+import type { IAnyNavigatorHandle } from '../navigation-context';
+export type INavigationHandle = IAnyNavigatorHandle & {
+    addListener: (event: INavigationEventName, listener: INavigationEventListener) => () => void;
+    getParent: () => IAnyNavigatorHandle | undefined;
+};
+export declare function useNavigation(): Accessor<INavigationHandle>;

package/build/solid/primitives/use-navigation.js

@@ -0,0 +1,23 @@
+// Mirrors @react-navigation's `navigation.addListener('focus', cb)` surface. All pub/sub logic
+// lives in ../../core/navigation-events; this only reads the injected scope and binds identity.
+//
+// `use*`, not `create*`: it CONSUMES an existing context and owns no state or subscription of its
+// own - the same distinction Solid itself draws between `useContext`/`useTransition` and
+// `createSignal`/`createEffect` (adapters/solid/src/primitives/create-color-scheme.ts's header).
+//
+// Returns an ACCESSOR for the reason every value crossing a boundary in this adapter does: a Solid
+// component body runs once, so a returned object would freeze at the scope the screen mounted with
+// and `getParent()` would keep answering with a stale ancestor after a nested navigator re-scoped.
+import { createMemo } from 'solid-js';
+import { requireNavigationScope } from '../navigation-context.js';
+export function useNavigation() {
+    const scope = requireNavigationScope('useNavigation');
+    return createMemo(() => {
+        const { navigation, emitter, parent } = scope();
+        return {
+            ...navigation,
+            addListener: emitter.addListener,
+            getParent: () => parent?.navigation,
+        };
+    });
+}

package/build/solid/primitives/use-route.d.ts

@@ -0,0 +1,3 @@
+import type { Accessor } from 'solid-js';
+import type { IRoute } from '../../core';
+export declare function useRoute(): Accessor<IRoute<unknown>>;

package/build/solid/primitives/use-route.js

@@ -0,0 +1,14 @@
+// Mirrors @react-navigation's useRoute. Zero logic of its own - the route object is built by the
+// navigators' route derivation from the shared core reducer's state.
+//
+// THE ACCESSOR IS THE WHOLE POINT HERE. React re-runs a screen's body on every navigation, so its
+// useRoute() can hand back a plain object; Solid runs the body ONCE. A `useRoute()` returning
+// `IRoute` would therefore paint the params the screen was pushed with and never update again -
+// `navigation.setParams({...})` produces a new route object under the SAME key, and nothing would
+// re-read it. Pinned by "setParams reaches a mounted screen" in ../solid.test.tsx.
+import { createMemo } from 'solid-js';
+import { requireNavigationScope } from '../navigation-context.js';
+export function useRoute() {
+    const scope = requireNavigationScope('useRoute');
+    return createMemo(() => scope().route);
+}

package/build/solid/primitives/use-stack-navigation.d.ts

@@ -0,0 +1,5 @@
+import type { Accessor } from 'solid-js';
+import type { INavigatorHandle } from '../../core';
+import type { INavigationHandle } from './use-navigation';
+export type IStackNavigationHandle = INavigatorHandle & Pick<INavigationHandle, 'addListener' | 'getParent'>;
+export declare function useStackNavigation(): Accessor<IStackNavigationHandle>;

package/build/solid/primitives/use-stack-navigation.js

@@ -0,0 +1,19 @@
+// useNavigation() returns a union (IAnyNavigatorHandle), since it does not know which navigator
+// mounted the calling component. When a component genuinely only ever renders under a Stack, this
+// narrows that union ONCE, here, so call sites never write their own `'push' in navigation` check.
+//
+// `use*`: a pure consumer of useNavigation()'s accessor, no state of its own.
+import { createMemo } from 'solid-js';
+import { isStackNavigatorHandle } from '../../core/index.js';
+import { useNavigation } from './use-navigation.js';
+export function useStackNavigation() {
+    const navigation = useNavigation();
+    return createMemo(() => {
+        const value = navigation();
+        if (!isStackNavigatorHandle(value)) {
+            throw new Error('useStackNavigation() was called from a component whose nearest navigator is not a Stack. ' +
+                'Use useNavigation() instead if this component can render under more than one navigator kind.');
+        }
+        return value;
+    });
+}

package/build/solid/primitives/use-tab-navigation.d.ts

@@ -0,0 +1,5 @@
+import type { Accessor } from 'solid-js';
+import type { ITabNavigatorHandle } from '../../core';
+import type { INavigationHandle } from './use-navigation';
+export type ITabNavigationHandle = ITabNavigatorHandle & Pick<INavigationHandle, 'addListener' | 'getParent'>;
+export declare function useTabNavigation(): Accessor<ITabNavigationHandle>;

package/build/solid/primitives/use-tab-navigation.js

@@ -0,0 +1,15 @@
+// Twin of use-stack-navigation.ts, narrowing to a Tab handle instead.
+import { createMemo } from 'solid-js';
+import { isTabNavigatorHandle } from '../../core/index.js';
+import { useNavigation } from './use-navigation.js';
+export function useTabNavigation() {
+    const navigation = useNavigation();
+    return createMemo(() => {
+        const value = navigation();
+        if (!isTabNavigatorHandle(value)) {
+            throw new Error('useTabNavigation() was called from a component whose nearest navigator is not a Tab. ' +
+                'Use useNavigation() instead if this component can render under more than one navigator kind.');
+        }
+        return value;
+    });
+}

package/build/solid/screen-props.d.ts

@@ -0,0 +1,19 @@
+import type { Component } from 'solid-js';
+import type { INavigatorHandle, IRoute, IScreenOptions, ISearchBarCommands, ISearchBarOptions } from '../core';
+export type ISolidSearchBarOptions = ISearchBarOptions & {
+    ref?: (commands: ISearchBarCommands | null) => void;
+};
+export type ISolidScreenOptions = Omit<IScreenOptions, 'headerSearchBarOptions'> & {
+    headerSearchBarOptions?: ISolidSearchBarOptions;
+};
+export type IScreenOptionsArgs = {
+    route: IRoute<unknown>;
+    navigation: INavigatorHandle;
+};
+export type IScreenOptionsResolver = (args: IScreenOptionsArgs) => ISolidScreenOptions;
+export type IScreenProps = {
+    name: string;
+    component: Component;
+    options?: ISolidScreenOptions | IScreenOptionsResolver;
+    initialParams?: unknown;
+};

package/build/solid/screen-props.js

@@ -0,0 +1,9 @@
+// Stack.Screen's public prop types, split out of the marker component itself so screen-registry.ts
+// can name `IScreenProps['options']` without importing a component (which would make the two
+// modules circular).
+//
+// Declared here rather than re-exported from another adapter: `component` is a Solid `Component`
+// and the search-bar `ref` is a Solid callback ref, both framework values, which is exactly the
+// test <prop_types_split_agnostic_vs_per_adapter> applies. The agnostic FIELD BASE (IScreenOptions,
+// ISearchBarOptions, IRoute, INavigatorHandle) is shared from ../core verbatim.
+export {};

package/build/solid/screen-registry.d.ts

@@ -0,0 +1,31 @@
+import type { Accessor, Component } from 'solid-js';
+import type { IScreenProps } from './screen-props';
+import type { ITabScreenProps } from './tab-screen-props';
+import type { IDrawerScreenProps } from './drawer-screen-props';
+export type INavigatorKind = 'stack' | 'tab' | 'drawer';
+export type IRegisteredScreen<TOptions> = {
+    readonly name: string;
+    readonly component: Component;
+    readonly options: TOptions;
+    readonly initialParams: unknown;
+};
+type IScreenCollector<TKind extends INavigatorKind, TOptions> = {
+    readonly kind: TKind;
+    register(screen: IRegisteredScreen<TOptions>): void;
+    unregister(screen: IRegisteredScreen<TOptions>): void;
+};
+export type IStackScreenCollector = IScreenCollector<'stack', IScreenProps['options']>;
+export type ITabScreenCollector = IScreenCollector<'tab', ITabScreenProps['options']>;
+export type IDrawerScreenCollector = IScreenCollector<'drawer', IDrawerScreenProps['options']>;
+export type IAnyScreenCollector = IStackScreenCollector | ITabScreenCollector | IDrawerScreenCollector;
+export declare const ScreenCollectorProvider: import("solid-js").ContextProviderComponent<IAnyScreenCollector | undefined>;
+export declare function collectStackScreen(screen: IRegisteredScreen<IScreenProps['options']>): void;
+export declare function collectTabScreen(screen: IRegisteredScreen<ITabScreenProps['options']>): void;
+export declare function collectDrawerScreen(screen: IRegisteredScreen<IDrawerScreenProps['options']>): void;
+export declare function toRegistry<TOptions>(screens: readonly IRegisteredScreen<TOptions>[]): Map<string, IRegisteredScreen<TOptions>>;
+export type IScreenSignal<TKind extends INavigatorKind, TOptions> = {
+    screens: Accessor<readonly IRegisteredScreen<TOptions>[]>;
+    collector: IScreenCollector<TKind, TOptions>;
+};
+export declare function createScreenSignal<TKind extends INavigatorKind, TOptions>(kind: TKind): IScreenSignal<TKind, TOptions>;
+export {};

package/build/solid/screen-registry.js

@@ -0,0 +1,86 @@
+// How a navigator learns about its `<Stack.Screen>` / `<Tab.Screen>` / `<Drawer.Screen>` markers.
+//
+// React reads `children` as an inspectable array; Vue scans the default slot's vnodes
+// (`vnode.type === Screen`); Angular queries `@ContentChildren`. Solid can do NONE of those:
+// `props.children` is a getter that CREATES the children when read, and what comes back is
+// already-built host nodes (or, for a marker that paints nothing, `undefined`) - there is no
+// element description left to inspect. So registration is INVERTED here, exactly as on Svelte:
+// the navigator publishes a collector on the context, each marker registers ITSELF from its own
+// body, and the navigator's route list derives from what came back.
+//
+// The consequence that shapes every navigator in this folder: the registry is EMPTY while the
+// navigator's own body runs. Solid's Provider evaluates its children inside a render effect, i.e.
+// after the body returned, so nothing may be computed eagerly from the registry. Route lists,
+// seeds and options folds are all memos over `screens()` instead.
+//
+// ONE context key, not one per navigator kind: nearest-navigator-wins shadowing falls out of
+// Solid's own owner-chain context lookup, so a Stack nested inside a Tab screen captures its own
+// markers. The `kind` tag then rejects a MISMATCHED marker (a `<Tab.Screen>` written inside a
+// `<Stack>`) instead of letting it register with some far-away ancestor Tab - the failure mode a
+// per-kind key would have.
+//
+// Narrowing back out of the context is done by the three `collect*Screen` functions rather than by
+// a generic one taking `kind` as a parameter: a literal comparison is what lets TypeScript
+// discriminate the union, and a generic parameter would force a cast the project bans.
+import { createContext, createSignal, onCleanup, useContext } from 'solid-js';
+import { dlog } from '@symbiote-native/engine';
+const ScreenCollectorContext = createContext();
+export const ScreenCollectorProvider = ScreenCollectorContext.Provider;
+function collectorFor(kind, name) {
+    const collector = useContext(ScreenCollectorContext);
+    if (collector === undefined) {
+        dlog(`navigation: <${kind} screen "${name}"> rendered outside any navigator, ignored`);
+        return undefined;
+    }
+    if (collector.kind !== kind) {
+        dlog(`navigation: a ${kind} screen marker ("${name}") was rendered inside a ` +
+            `${collector.kind} navigator, ignored`);
+        return undefined;
+    }
+    return collector;
+}
+// Registration is undone on cleanup, so a marker behind a `<Show>` disappears from the registry
+// exactly like a removed Vue slot vnode stops being scanned.
+function bind(collector, screen) {
+    collector.register(screen);
+    onCleanup(() => collector.unregister(screen));
+}
+export function collectStackScreen(screen) {
+    const collector = collectorFor('stack', screen.name);
+    if (collector === undefined || collector.kind !== 'stack')
+        return;
+    bind(collector, screen);
+}
+export function collectTabScreen(screen) {
+    const collector = collectorFor('tab', screen.name);
+    if (collector === undefined || collector.kind !== 'tab')
+        return;
+    bind(collector, screen);
+}
+export function collectDrawerScreen(screen) {
+    const collector = collectorFor('drawer', screen.name);
+    if (collector === undefined || collector.kind !== 'drawer')
+        return;
+    bind(collector, screen);
+}
+// name -> entry, last registration wins, exactly like Vue's collectRegistry Map.
+export function toRegistry(screens) {
+    const registry = new Map();
+    for (const screen of screens)
+        registry.set(screen.name, screen);
+    return registry;
+}
+// The navigator half: the signal every navigator derives its route list from, plus the collector
+// it publishes on the context. `unregister` filters by IDENTITY, never by name - two markers can
+// briefly share a name while one is being replaced, and dropping by name would evict the survivor.
+export function createScreenSignal(kind) {
+    const [screens, setScreens] = createSignal([]);
+    return {
+        screens,
+        collector: {
+            kind,
+            register: screen => setScreens(list => [...list, screen]),
+            unregister: screen => setScreens(list => list.filter(candidate => candidate !== screen)),
+        },
+    };
+}

package/build/solid/screen.d.ts

@@ -0,0 +1,6 @@
+import type { IScreenProps } from './screen-props';
+import type { ITabScreenProps } from './tab-screen-props';
+import type { IDrawerScreenProps } from './drawer-screen-props';
+export declare function Screen(props: IScreenProps): undefined;
+export declare function TabScreen(props: ITabScreenProps): undefined;
+export declare function DrawerScreen(props: IDrawerScreenProps): undefined;

package/build/solid/screen.js

@@ -0,0 +1,69 @@
+// Stack.Screen / Tab.Screen / Drawer.Screen: declarative markers that paint nothing. The navigator
+// reads them through the context collector (screen-registry.ts) rather than by scanning children
+// the way React and Vue can, then mounts the registered component itself.
+//
+// Every field is handed over as a GETTER over this component's own props, never a snapshot: a Solid
+// component body runs ONCE, so `{ name: props.name }` would freeze the marker at its mount-time
+// values and an app that swaps `options` on a live marker would silently keep the old header.
+//
+// The three live in one file because they differ only in which collector they call - three
+// near-identical files would drift the way the two descriptor-shape guards did before they were
+// lifted into @symbiote-native/components.
+//
+// Returning `undefined` (not an empty host element) is what keeps a marker free: Solid inserts
+// nothing for it, and where a following sibling forces a position placeholder the renderer emits an
+// engine ANCHOR, which the commit walk skips. Svelte needed a hidden zero-size host for its markers
+// because its compiler turns the whitespace BETWEEN them into real text nodes; Solid's JSX drops
+// that whitespace, so the hazard does not exist here.
+import { collectDrawerScreen, collectStackScreen, collectTabScreen, } from './screen-registry.js';
+export function Screen(props) {
+    collectStackScreen({
+        get name() {
+            return props.name;
+        },
+        get component() {
+            return props.component;
+        },
+        get options() {
+            return props.options;
+        },
+        get initialParams() {
+            return props.initialParams;
+        },
+    });
+    return undefined;
+}
+export function TabScreen(props) {
+    collectTabScreen({
+        get name() {
+            return props.name;
+        },
+        get component() {
+            return props.component;
+        },
+        get options() {
+            return props.options;
+        },
+        get initialParams() {
+            return props.initialParams;
+        },
+    });
+    return undefined;
+}
+export function DrawerScreen(props) {
+    collectDrawerScreen({
+        get name() {
+            return props.name;
+        },
+        get component() {
+            return props.component;
+        },
+        get options() {
+            return props.options;
+        },
+        get initialParams() {
+            return props.initialParams;
+        },
+    });
+    return undefined;
+}

package/build/solid/stack/index.d.ts

@@ -0,0 +1,15 @@
+import type { JSX } from '@symbiote-native/solid/jsx-runtime';
+import type { INavigatorHandle } from '../../core';
+import { Screen } from '../screen';
+import type { ISolidScreenOptions } from '../screen-props';
+export type { INavigatorHandle } from '../../core';
+export type IStackProps = {
+    initialRouteName?: string;
+    screenOptions?: ISolidScreenOptions;
+    ref?: (handle: INavigatorHandle) => void;
+    children?: JSX.Element;
+};
+declare function StackImpl(props: IStackProps): JSX.Element;
+export declare const Stack: typeof StackImpl & {
+    Screen: typeof Screen;
+};