@symbiote-native/navigation 2.1.0 → 3.0.0

package/src/solid/index.ts

@@ -0,0 +1,87 @@
+// @symbiote-native/navigation/solid: the Solid native-stack navigator over react-native-screens'
+// native view primitives. Importing this barrel first registers the native views' ViewConfigs
+// (../register, a side-effect import of the codegen specs - never react-native-screens' own React
+// components), then exposes Stack (with Stack.Screen attached) and the navigator handle. Mirrors
+// vue/index.ts's and svelte/index.ts's barrel shape.
+//
+// The lifecycle helpers split by what they DO, not by a blanket prefix: `use*` for the ones that
+// only consume the navigation scope already on the owner chain (useNavigation / useRoute and the
+// three narrowing variants - Solid's own `useContext` sense), `create*` for the ones that own a
+// signal, an effect or a subscription (createIsFocused / createFocusEffect / createNavigationState
+// / createLinkingIntegration). Same rule the adapter's `createColorScheme` follows; a blanket `use`
+// would read as a foreign ecosystem's convention (<adapter_src_follows_framework_idioms>).
+
+import '../register';
+
+export { Stack } from './stack';
+export type { INavigatorHandle, IStackProps } from './stack';
+export { Screen, TabScreen, DrawerScreen } from './screen';
+export type {
+  IScreenOptionsArgs,
+  IScreenOptionsResolver,
+  IScreenProps,
+  ISolidScreenOptions,
+  ISolidSearchBarOptions,
+} from './screen-props';
+export type {
+  IScreenOptions,
+  IStackAnimation,
+  IStackPresentation,
+} from '../core';
+
+export {
+  useNavigation,
+  useStackNavigation,
+  useTabNavigation,
+  useDrawerNavigation,
+  useRoute,
+  createIsFocused,
+  createFocusEffect,
+  createNavigationState,
+} from './primitives';
+export type {
+  INavigationHandle,
+  IStackNavigationHandle,
+  ITabNavigationHandle,
+  IDrawerNavigationHandle,
+} from './primitives';
+export type {
+  INavigationScopeValue,
+  IAnyNavigatorHandle,
+} from './navigation-context';
+
+export { createLinkingIntegration } from './linking';
+export type { ILinkingConfig, IScreenLinkingConfig } from '../core';
+
+// Tab: the bottom-tabs navigator, a PURE-JS UI (no react-native-screens views involved, so no extra
+// ViewConfig registration is needed beyond the ../register import above).
+export { Tab } from './tabs';
+export type { ITabNavigatorHandle, ITabProps } from './tabs';
+export type {
+  ITabScreenOptionsArgs,
+  ITabScreenOptionsResolver,
+  ITabScreenProps,
+} from './tab-screen-props';
+export type { ITabOptions, ITabBarIcon } from '../core';
+
+// Drawer: the swipeable drawer navigator, a PURE-JS UI (PanResponder + Animated). See
+// drawer/index.ts's header for the feasibility note re: react-native-gesture-handler /
+// react-native-reanimated parity gaps.
+export { Drawer } from './drawer';
+export type {
+  IDrawerContentSlotProps,
+  IDrawerNavigatorHandle,
+  IDrawerProps,
+  IDrawerDescriptorMap,
+} from './drawer';
+export type {
+  IDrawerScreenOptionsArgs,
+  IDrawerScreenOptionsResolver,
+  IDrawerScreenProps,
+} from './drawer-screen-props';
+export type {
+  IDrawerOptions,
+  IDrawerScreenOptions,
+  IDrawerType,
+  IDrawerPosition,
+} from '../core';

package/src/solid/linking.ts

@@ -0,0 +1,74 @@
+// createLinkingIntegration: wires the framework-agnostic linking config (../core's
+// resolveRouteFromUrl) onto an existing Stack's INavigatorHandle. Deliberately NOT called from
+// inside ./stack - app code owns the wiring, the same top-level-prop shape @react-navigation keeps
+// `linking` in on NavigationContainer rather than baking it into the router itself.
+//
+// `create*`, not `use*`: it owns a Linking subscription and its teardown. (Vue and Svelte spell it
+// `useLinkingIntegration` because their ecosystems put every lifecycle helper behind `use`; Solid
+// reserves that prefix for consuming something that already exists -
+// <adapter_src_follows_framework_idioms>.)
+//
+// Takes an ACCESSOR of the handle, not the handle: `<Stack ref={setHandle}>` resolves after the
+// navigator has been created, so an eagerly-passed value would be `null` at the call site. Reading
+// it lazily inside onMount gives the same "already populated" guarantee React's layout-effect
+// ordering does - a Solid `ref` on a component is called during that component's own creation,
+// which is strictly before any effect runs.
+
+import { onCleanup, onMount } from 'solid-js';
+import type { Accessor } from 'solid-js';
+import { Linking, dlog } from '@symbiote-native/engine';
+import type { IEventSubscription, IUrlEvent } from '@symbiote-native/engine';
+import { resolveRouteFromUrl } from '../core';
+import type { ILinkingConfig, INavigatorHandle } from '../core';
+
+export function createLinkingIntegration(
+  config: ILinkingConfig,
+  navigatorHandle: Accessor<INavigatorHandle | null>,
+): void {
+  let cancelled = false;
+  let subscription: IEventSubscription | undefined;
+
+  function applyRoute(
+    url: string,
+    dispatch: (name: string, params?: unknown) => void,
+  ): void {
+    const route = resolveRouteFromUrl(config, url);
+    if (route === null) {
+      dlog(`createLinkingIntegration: no route resolved for "${url}"`);
+      return;
+    }
+    dispatch(route.name, route.params);
+  }
+
+  onMount(() => {
+    const handle = navigatorHandle();
+    if (handle === null) {
+      dlog(
+        'createLinkingIntegration: navigatorHandle is not yet available at mount time',
+      );
+      return;
+    }
+
+    Linking.getInitialURL()
+      .then(url => {
+        if (cancelled || url === null) return;
+        dlog(`createLinkingIntegration: initial URL "${url}"`);
+        applyRoute(url, handle.replace);
+      })
+      .catch((error: unknown) => {
+        dlog(
+          `createLinkingIntegration: getInitialURL failed: ${String(error)}`,
+        );
+      });
+
+    subscription = Linking.addEventListener('url', (event: IUrlEvent) => {
+      dlog(`createLinkingIntegration: url event "${event.url}"`);
+      applyRoute(event.url, handle.push);
+    });
+  });
+
+  onCleanup(() => {
+    cancelled = true;
+    subscription?.remove();
+  });
+}

package/src/solid/navigation-context.ts

@@ -0,0 +1,56 @@
+// The lifecycle half of the framework-agnostic emitter (../core/navigation-events). Solid's twin of
+// React's Context / Vue's provide-inject / Svelte's setContext is `createContext` + a Provider over
+// one shared key, resolved along the OWNER chain - so a screen's subtree reads its own route,
+// navigator handle and per-route emitter without prop-drilling.
+//
+// THE VALUE IS AN ACCESSOR, never a route object. A Solid component body runs once and a context
+// value is captured once, so handing over `{ route, ... }` directly would freeze every consumer at
+// the route as it looked when the screen mounted - `setParams` produces a NEW route object under
+// the same key and would never reach `useRoute()`. This is the same accessors-not-values rule
+// descriptorToSolid is built on, one layer up (.claude/rules/solid-descriptor-bridge.md).
+//
+// Each navigator mounts ONE Provider per live route (keyed by route.key, exactly like React's
+// per-route `<NavigationContext.Provider>`), so sibling screens never see each other's scope -
+// an inherent property of any hierarchical dependency-injection scheme, not a React artifact.
+//
+// `parent` threads the ambient value a navigator read on ITS OWN mount (undefined at the root) into
+// the value it provides to its own screens, forming a linked list - this is what lets a screen
+// nested inside e.g. a Stack-screen-renders-a-Tab composition reach the enclosing Stack via
+// useNavigation().getParent().
+
+import { createContext, useContext } from 'solid-js';
+import type { Accessor } from 'solid-js';
+import type { IAnyNavigatorHandle, INavigationEmitter, IRoute } from '../core';
+export type { IAnyNavigatorHandle };
+
+export type INavigationScopeValue = {
+  route: IRoute<unknown>;
+  navigation: IAnyNavigatorHandle;
+  emitter: INavigationEmitter;
+  parent?: INavigationScopeValue;
+};
+
+export type INavigationScope = Accessor<INavigationScopeValue>;
+
+const NavigationScopeContext = createContext<INavigationScope>();
+
+export const NavigationScopeProvider = NavigationScopeContext.Provider;
+
+// undefined simply means "no ancestor scope", which is a legitimate state (the nesting root a
+// navigator itself reads on its own mount) rather than an error - callers that require one go
+// through requireNavigationScope below.
+export function useNavigationScope(): INavigationScope | undefined {
+  return useContext(NavigationScopeContext);
+}
+
+// The "throw if missing" half every primitive in ./primitives needs - they all read the scope and
+// threw the same shaped error, differing only in which function name the message names.
+export function requireNavigationScope(functionName: string): INavigationScope {
+  const scope = useNavigationScope();
+  if (scope === undefined) {
+    throw new Error(
+      `${functionName} must be used within a screen rendered by <Stack>, <Tab>, or <Drawer>`,
+    );
+  }
+  return scope;
+}

package/src/solid/primitives/create-focus-effect.ts

@@ -0,0 +1,41 @@
+// Mirrors @react-navigation's useFocusEffect: run `effect` when the screen gains focus, run its
+// returned cleanup when it loses focus (and once more on teardown).
+//
+// `create*`: it owns two subscriptions and the effect's cleanup slot.
+//
+// React's version requires memoizing `effect` (useCallback), since a new identity re-subscribes it
+// like any other useEffect dependency. That does not apply here: a Solid body runs once, so
+// `effect` is read once and closed over directly - there is no dependency array to go stale.
+
+import { onCleanup } from 'solid-js';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+
+export function createFocusEffect(effect: () => (() => void) | void): void {
+  const scope = requireNavigationScope('createFocusEffect');
+
+  let cleanup: (() => void) | void;
+  const runEffect = (): void => {
+    cleanup = effect();
+  };
+  const runCleanup = (): void => {
+    cleanup?.();
+    cleanup = undefined;
+  };
+
+  const { emitter } = scope();
+  const unsubscribeFocus = emitter.addListener(
+    NAVIGATION_EVENT_FOCUS,
+    runEffect,
+  );
+  const unsubscribeBlur = emitter.addListener(
+    NAVIGATION_EVENT_BLUR,
+    runCleanup,
+  );
+
+  onCleanup(() => {
+    unsubscribeFocus();
+    unsubscribeBlur();
+    runCleanup();
+  });
+}

package/src/solid/primitives/create-is-focused.ts

@@ -0,0 +1,41 @@
+// 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 type { Accessor } from 'solid-js';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+
+export function createIsFocused(): Accessor<boolean> {
+  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/src/solid/primitives/create-navigation-state.ts

@@ -0,0 +1,44 @@
+// 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 type { Accessor } from 'solid-js';
+import { NAVIGATION_EVENT_STATE, isRecord } from '../../core';
+import type { INavigatorState } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+
+function isNavigatorState(value: unknown): value is INavigatorState {
+  return isRecord(value) && Array.isArray(value.routes);
+}
+
+export function createNavigationState<TResult>(
+  selector: (state: INavigatorState) => TResult,
+): Accessor<TResult> {
+  const scope = requireNavigationScope('createNavigationState');
+  const [result, setResult] = createSignal<TResult>(
+    selector({ routes: [scope().route] }),
+  );
+
+  const unsubscribe = scope().emitter.addListener(
+    NAVIGATION_EVENT_STATE,
+    (state: unknown) => {
+      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/src/solid/primitives/index.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/src/solid/primitives/use-drawer-navigation.ts

@@ -0,0 +1,25 @@
+// Twin of use-stack-navigation.ts, narrowing to a Drawer handle instead.
+
+import { createMemo } from 'solid-js';
+import type { Accessor } from 'solid-js';
+import { isDrawerNavigatorHandle } from '../../core';
+import type { IDrawerNavigatorHandle } from '../../core';
+import { useNavigation } from './use-navigation';
+import type { INavigationHandle } from './use-navigation';
+
+export type IDrawerNavigationHandle = IDrawerNavigatorHandle &
+  Pick<INavigationHandle, 'addListener' | 'getParent'>;
+
+export function useDrawerNavigation(): Accessor<IDrawerNavigationHandle> {
+  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/src/solid/primitives/use-navigation.ts

@@ -0,0 +1,44 @@
+// 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 type { Accessor } from 'solid-js';
+import type {
+  INavigationEventListener,
+  INavigationEventName,
+} from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+import type { IAnyNavigatorHandle } from '../navigation-context';
+
+export type INavigationHandle = IAnyNavigatorHandle & {
+  addListener: (
+    event: INavigationEventName,
+    listener: INavigationEventListener,
+  ) => () => void;
+  // Walks exactly ONE hop up the scope's `parent` chain to the enclosing navigator's handle - e.g.
+  // a Tab screen nested inside a Stack screen calling getParent() to push a new Stack route.
+  // Callers narrow the union themselves ('push' in parent, etc.). Deliberately NOT
+  // react-navigation's getParent(id) or a target-based dispatch by navigator name - plain
+  // immediate-parent walking is v1 scope on every adapter.
+  getParent: () => IAnyNavigatorHandle | undefined;
+};
+
+export function useNavigation(): Accessor<INavigationHandle> {
+  const scope = requireNavigationScope('useNavigation');
+  return createMemo(() => {
+    const { navigation, emitter, parent } = scope();
+    return {
+      ...navigation,
+      addListener: emitter.addListener,
+      getParent: () => parent?.navigation,
+    };
+  });
+}

package/src/solid/primitives/use-route.ts

@@ -0,0 +1,18 @@
+// 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 type { Accessor } from 'solid-js';
+import type { IRoute } from '../../core';
+import { requireNavigationScope } from '../navigation-context';
+
+export function useRoute(): Accessor<IRoute<unknown>> {
+  const scope = requireNavigationScope('useRoute');
+  return createMemo(() => scope().route);
+}

package/src/solid/primitives/use-stack-navigation.ts

@@ -0,0 +1,29 @@
+// 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 type { Accessor } from 'solid-js';
+import { isStackNavigatorHandle } from '../../core';
+import type { INavigatorHandle } from '../../core';
+import { useNavigation } from './use-navigation';
+import type { INavigationHandle } from './use-navigation';
+
+export type IStackNavigationHandle = INavigatorHandle &
+  Pick<INavigationHandle, 'addListener' | 'getParent'>;
+
+export function useStackNavigation(): Accessor<IStackNavigationHandle> {
+  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/src/solid/primitives/use-tab-navigation.ts

@@ -0,0 +1,25 @@
+// Twin of use-stack-navigation.ts, narrowing to a Tab handle instead.
+
+import { createMemo } from 'solid-js';
+import type { Accessor } from 'solid-js';
+import { isTabNavigatorHandle } from '../../core';
+import type { ITabNavigatorHandle } from '../../core';
+import { useNavigation } from './use-navigation';
+import type { INavigationHandle } from './use-navigation';
+
+export type ITabNavigationHandle = ITabNavigatorHandle &
+  Pick<INavigationHandle, 'addListener' | 'getParent'>;
+
+export function useTabNavigation(): Accessor<ITabNavigationHandle> {
+  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/src/solid/screen-props.ts

@@ -0,0 +1,51 @@
+// 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.
+
+import type { Component } from 'solid-js';
+import type {
+  INavigatorHandle,
+  IRoute,
+  IScreenOptions,
+  ISearchBarCommands,
+  ISearchBarOptions,
+} from '../core';
+
+// The imperative search-bar handle (focus/blur/clearText/setText/cancelSearch/
+// toggleCancelButton). React hands it back through a `RefObject`, Vue through a `Ref`; Solid's own
+// spelling of "give me the thing when it exists" is a CALLBACK, which is also what
+// `ref={setCommands}` compiles to. `null` arrives when the host element goes away.
+export type ISolidSearchBarOptions = ISearchBarOptions & {
+  ref?: (commands: ISearchBarCommands | null) => void;
+};
+
+export type ISolidScreenOptions = Omit<
+  IScreenOptions,
+  'headerSearchBarOptions'
+> & {
+  headerSearchBarOptions?: ISolidSearchBarOptions;
+};
+
+// The options resolver runs OUTSIDE any component scope (during the options fold), so it still
+// receives the route + navigator handle explicitly - screens read those through the primitives in
+// ./primitives, but a resolver has no owner to read a context from.
+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;
+};