@symbiote-native/navigation 1.0.0

package/src/core/screen-options.ts

@@ -0,0 +1,181 @@
+// Pure folds from a route's agnostic IScreenOptions into the native view-props shapes
+// (RNSScreen + RNSScreenStackHeaderConfig + RNSSearchBar paint from). Framework-agnostic and
+// shared verbatim by every adapter - the adapter's own job is only wiring identity (screenId),
+// position (activityState via computeActivityState) and the lifecycle event handlers into
+// `passthrough`.
+//
+// The header bar-button payload+dispatch cluster (id-tagging, onPress lookup) lives in
+// header-bar-buttons.ts - self-contained, consumed here only as a black box by
+// resolveHeaderConfigView.
+
+import type {
+  IHeaderConfigViewProps,
+  INavigatorPlatform,
+  IOptionalBooleanNativeProp,
+  IScreenOptions,
+  IScreenViewProps,
+  ISearchBarOptions,
+  ISearchBarViewProps,
+  ISheetAllowedDetents,
+  ISheetInitialDetent,
+  ISheetLargestUndimmedDetent,
+} from './navigator-props';
+import { buildHeaderBarButtonDispatch, prepareHeaderBarButtonItems } from './header-bar-buttons';
+
+// These sentinels must be kept in sync with react-native-screens' native side - they are RNS's
+// own compat values for the 'fitToContents'/'large'/'medium'/'all' legacy presets, replicated
+// here because we drive RNSScreen directly (no react-native-screens JS component in the path).
+const SHEET_FIT_TO_CONTENTS: number[] = [-1];
+const SHEET_COMPAT_LARGE: number[] = [1.0];
+const SHEET_COMPAT_MEDIUM: number[] = [0.5];
+const SHEET_COMPAT_ALL: number[] = [0.5, 1.0];
+const SHEET_DIMMED_ALWAYS = -1;
+
+function resolveSheetAllowedDetents(compat: ISheetAllowedDetents | undefined): number[] {
+  if (compat === undefined) return SHEET_COMPAT_LARGE;
+  if (Array.isArray(compat)) return compat;
+  switch (compat) {
+    case 'fitToContents':
+      return SHEET_FIT_TO_CONTENTS;
+    case 'large':
+      return SHEET_COMPAT_LARGE;
+    case 'medium':
+      return SHEET_COMPAT_MEDIUM;
+    case 'all':
+      return SHEET_COMPAT_ALL;
+  }
+}
+
+function resolveSheetLargestUndimmedDetent(
+  compat: ISheetLargestUndimmedDetent | undefined,
+  lastDetentIndex: number,
+): number {
+  if (typeof compat === 'number') return compat;
+  switch (compat) {
+    case 'last':
+      return lastDetentIndex;
+    case 'large':
+      return 1;
+    case 'medium':
+      return 0;
+    case 'none':
+    case 'all':
+    case undefined:
+      return SHEET_DIMMED_ALWAYS;
+  }
+}
+
+function resolveSheetInitialDetent(
+  compat: ISheetInitialDetent | undefined,
+  lastDetentIndex: number,
+): number {
+  if (compat === 'last') return lastDetentIndex;
+  if (compat === undefined) return 0;
+  return compat;
+}
+
+function toOptionalBooleanNativeProp(value: boolean | undefined): IOptionalBooleanNativeProp {
+  if (value === undefined) return 'undefined';
+  return value ? 'true' : 'false';
+}
+
+export function resolveHeaderConfigView(
+  options: IScreenOptions | undefined,
+  platform: INavigatorPlatform,
+  passthrough: Record<string, unknown> = {},
+): IHeaderConfigViewProps {
+  return {
+    title: options?.title,
+    hidden: options?.headerShown === false,
+    backTitle: options?.headerBackTitle,
+    backTitleVisible: platform.defaultHeaderBackTitleVisible,
+    backButtonDisplayMode: options?.headerBackButtonDisplayMode,
+    largeTitle: options?.headerLargeTitle,
+    translucent: options?.headerTranslucent,
+    color: options?.headerTintColor,
+    titleColor: options?.headerTitleColor,
+    backgroundColor: options?.headerStyle?.backgroundColor,
+    largeTitleBackgroundColor: options?.headerLargeStyle?.backgroundColor,
+    userInterfaceStyle: options?.headerUserInterfaceStyle,
+    headerLeftBarButtonItems: prepareHeaderBarButtonItems(
+      options?.headerLeftBarButtonItems,
+      'left',
+    ),
+    headerRightBarButtonItems: prepareHeaderBarButtonItems(
+      options?.headerRightBarButtonItems,
+      'right',
+    ),
+    ...buildHeaderBarButtonDispatch(
+      options?.headerLeftBarButtonItems,
+      options?.headerRightBarButtonItems,
+    ),
+    passthrough,
+  };
+}
+
+export function resolveScreenView(
+  screenId: string,
+  activityState: number,
+  options: IScreenOptions | undefined,
+  passthrough: Record<string, unknown> = {},
+): IScreenViewProps {
+  const sheetAllowedDetents = resolveSheetAllowedDetents(options?.sheetAllowedDetents);
+  const lastDetentIndex = sheetAllowedDetents.length - 1;
+  return {
+    screenId,
+    activityState,
+    gestureEnabled: options?.gestureEnabled,
+    stackAnimation: options?.stackAnimation,
+    stackPresentation: options?.stackPresentation,
+    transitionDuration: options?.transitionDuration,
+    sheetAllowedDetents,
+    sheetLargestUndimmedDetent: resolveSheetLargestUndimmedDetent(
+      options?.sheetLargestUndimmedDetentIndex,
+      lastDetentIndex,
+    ),
+    sheetInitialDetent: resolveSheetInitialDetent(
+      options?.sheetInitialDetentIndex,
+      lastDetentIndex,
+    ),
+    sheetGrabberVisible: options?.sheetGrabberVisible,
+    sheetCornerRadius: options?.sheetCornerRadius,
+    sheetExpandsWhenScrolledToEdge: options?.sheetExpandsWhenScrolledToEdge,
+    sheetElevation: options?.sheetElevation,
+    sheetShouldOverflowTopInset: options?.sheetShouldOverflowTopInset,
+    sheetDefaultResizeAnimationEnabled: options?.sheetDefaultResizeAnimationEnabled,
+    statusBarStyle: options?.statusBarStyle,
+    statusBarHidden: options?.statusBarHidden,
+    statusBarAnimation: options?.statusBarAnimation,
+    screenOrientation: options?.screenOrientation,
+    passthrough,
+  };
+}
+
+// RNSSearchBar is a standalone Fabric leaf (react-native-screens mounts it as a header-subview
+// child in its own JS component) - resolveSearchBarView only folds the static config surface;
+// where/how the adapter mounts the resulting leaf in the header tree is an adapter concern.
+export function resolveSearchBarView(
+  options: ISearchBarOptions | undefined,
+  passthrough: Record<string, unknown> = {},
+): ISearchBarViewProps {
+  return {
+    placeholder: options?.placeholder,
+    autoCapitalize: options?.autoCapitalize,
+    placement: options?.placement,
+    hideWhenScrolling: options?.hideWhenScrolling,
+    allowToolbarIntegration: options?.allowToolbarIntegration,
+    obscureBackground: toOptionalBooleanNativeProp(options?.obscureBackground),
+    hideNavigationBar: toOptionalBooleanNativeProp(options?.hideNavigationBar),
+    cancelButtonText: options?.cancelButtonText,
+    barTintColor: options?.barTintColor,
+    tintColor: options?.tintColor,
+    textColor: options?.textColor,
+    autoFocus: options?.autoFocus,
+    disableBackButtonOverride: options?.disableBackButtonOverride,
+    inputType: options?.inputType,
+    hintTextColor: options?.hintTextColor,
+    headerIconColor: options?.headerIconColor,
+    shouldShowHintSearchIcon: options?.shouldShowHintSearchIcon,
+    passthrough,
+  };
+}

package/src/core/search-bar-commands.ts

@@ -0,0 +1,57 @@
+// The imperative API react-native-screens' own SearchBarProps exposes via its `ref` field
+// (SearchBarCommands): each method dispatches a native view command on the RNSSearchBar node
+// (SearchBarNativeComponent's supportedCommands: blur/focus/clearText/toggleCancelButton/
+// setText/cancelSearch). Framework-agnostic - mirrors @symbiote-native/components'
+// buildScrollViewHandle exactly (same lazy-getter shape); the adapter supplies the node getter
+// and its own framework-specific ref field (see react/screen.ts's IReactSearchBarOptions - the
+// ref itself is per-adapter, same split as IPressableProps).
+import { dispatchViewCommand, dlog, type ISymbioteNode } from '@symbiote-native/engine';
+
+export interface ISearchBarCommands {
+  focus(): void;
+  blur(): void;
+  clearText(): void;
+  setText(text: string): void;
+  cancelSearch(): void;
+  toggleCancelButton(show: boolean): void;
+}
+
+// dispatchViewCommand itself dlogs a "node not committed" skip; this null case (the ref never
+// attached to a live RNSSearchBar at all - e.g. the header's search bar isn't mounted, or a
+// stale handle outlived its screen) was the one unlogged gap, silently indistinguishable from
+// "the command fired but did nothing". Investigation instrumentation (HeaderOptionsScreen
+// unresponsive-buttons bug); kept behind DEBUG per <keep_logs_gate_behind_DEBUG>, never removed.
+function warnIfDetached(command: string, node: ISymbioteNode | null): node is ISymbioteNode {
+  if (node !== null) return true;
+  dlog(
+    `SearchBarCommands.${command}: skipped, node is null (ref never attached) at t=${Date.now()}`,
+  );
+  return false;
+}
+
+// Every command is the same 3-line dance: get the (lazily-read) node, bail with a dlog'd warning
+// if it's detached, dispatch the native view command. Factored once so the six methods below
+// differ only in which command name they dispatch.
+function makeCommand(
+  getNode: () => ISymbioteNode | null,
+  command: string,
+): (...args: unknown[]) => void {
+  return (...args: unknown[]): void => {
+    const node = getNode();
+    if (!warnIfDetached(command, node)) return;
+    dispatchViewCommand(node, command, args);
+  };
+}
+
+// `getNode` is a LAZY getter, read on every call - see buildScrollViewHandle's comment for why
+// an eager capture would freeze `null`.
+export function buildSearchBarHandle(getNode: () => ISymbioteNode | null): ISearchBarCommands {
+  return {
+    focus: makeCommand(getNode, 'focus'),
+    blur: makeCommand(getNode, 'blur'),
+    clearText: makeCommand(getNode, 'clearText'),
+    setText: makeCommand(getNode, 'setText'),
+    cancelSearch: makeCommand(getNode, 'cancelSearch'),
+    toggleCancelButton: makeCommand(getNode, 'toggleCancelButton'),
+  };
+}

package/src/core/state-persistence/index.ts

@@ -0,0 +1,30 @@
+// Lightweight state persistence: pure serialize/deserialize for INavigatorState, the primitive
+// @react-navigation's `initialState`/`onStateChange` persistence recipe is built on. Routes are
+// already `{key, name, params}` - plain data, no functions/refs/class instances - so a JSON-safe
+// passthrough is sufficient; no framework wiring lives here yet (that's an adapter-level task).
+
+import type { INavigatorState } from '../navigator-state';
+import type { IRoute } from '../navigator-state';
+import { isRecord } from '../guards';
+
+// No `'params' in value` check: a route pushed with no params serializes to `{key, name,
+// params: undefined}`, and JSON.stringify drops undefined-valued keys - a JSON round trip of a
+// perfectly valid route legitimately arrives here without a `params` key at all.
+function isRoute(value: unknown): value is IRoute<unknown> {
+  return isRecord(value) && typeof value.key === 'string' && typeof value.name === 'string';
+}
+
+function isNavigatorState(value: unknown): value is INavigatorState {
+  return isRecord(value) && Array.isArray(value.routes) && value.routes.every(isRoute);
+}
+
+export function serializeNavigatorState(state: INavigatorState): unknown {
+  return state;
+}
+
+export function deserializeNavigatorState(raw: unknown): INavigatorState {
+  if (!isNavigatorState(raw)) {
+    throw new Error('deserializeNavigatorState: persisted value is not a valid navigator state');
+  }
+  return raw;
+}

package/src/core/state-persistence/state-persistence.test.ts

@@ -0,0 +1,42 @@
+// Co-located unit test (ADR 0025) for the pure serialize/deserialize passthrough. No framework,
+// no wiring - just the JSON-safe round trip and the deserialize-side runtime guard rejecting
+// malformed persisted data (a corrupted AsyncStorage entry, a schema change across app versions).
+
+import { describe, expect, it } from 'vitest';
+import { deserializeNavigatorState, serializeNavigatorState } from './index';
+import type { INavigatorState } from '../navigator-state';
+
+describe('serializeNavigatorState / deserializeNavigatorState', () => {
+  it('round-trips a navigator state through JSON', () => {
+    const state: INavigatorState = {
+      routes: [{ key: 'home-1', name: 'Home', params: { tab: 'feed' } }],
+    };
+    const roundTripped = deserializeNavigatorState(
+      JSON.parse(JSON.stringify(serializeNavigatorState(state))),
+    );
+    expect(roundTripped).toEqual(state);
+  });
+
+  it('rejects a payload missing the routes array', () => {
+    expect(() => deserializeNavigatorState({ notRoutes: [] })).toThrow();
+  });
+
+  it('rejects a payload whose routes are not route-shaped', () => {
+    expect(() => deserializeNavigatorState({ routes: [{ key: 'r1' }] })).toThrow();
+  });
+
+  it('rejects a non-object payload', () => {
+    expect(() => deserializeNavigatorState('not a state')).toThrow();
+    expect(() => deserializeNavigatorState(null)).toThrow();
+  });
+
+  it('round-trips a route pushed without params (JSON.stringify drops the undefined key)', () => {
+    const state: INavigatorState = {
+      routes: [{ key: 'menu-1', name: 'Menu', params: undefined }],
+    };
+    const roundTripped = deserializeNavigatorState(
+      JSON.parse(JSON.stringify(serializeNavigatorState(state))),
+    );
+    expect(roundTripped).toEqual(state);
+  });
+});

package/src/core/tab-options.ts

@@ -0,0 +1,25 @@
+// Per-tab agnostic options. Mirrors @react-navigation/bottom-tabs' `options` surface (title,
+// tabBarLabel, tabBarIcon, tabBarBadge, tint colors, tabBarStyle) minus anything that requires a
+// framework element: `tabBarIcon` there is a render prop returning a platform icon element, but
+// per <prop_types_split_agnostic_vs_per_adapter> a render-callback-returning-a-framework-element
+// field can't live in the shared agnostic type, so here it is EITHER a pre-built `IDescriptor`
+// (an adapter can bridge any host node it already resolved, image or vector icon) or a bare icon
+// NAME string the renderer paints as a label-style glyph - both framework-agnostic. An adapter
+// wanting a `(props) => ReactNode`-style callback resolves it to one of these two forms itself,
+// same split as IPressableProps's per-adapter children.
+
+import type { IColorValue } from '@symbiote-native/engine';
+import type { IViewStyle, IStyleProp } from '@symbiote-native/engine';
+import type { IDescriptor } from '@symbiote-native/components';
+
+export type ITabBarIcon = IDescriptor | string;
+
+export type ITabOptions = {
+  title?: string;
+  tabBarLabel?: string;
+  tabBarIcon?: ITabBarIcon;
+  tabBarBadge?: string | number;
+  tabBarActiveTintColor?: IColorValue;
+  tabBarInactiveTintColor?: IColorValue;
+  tabBarStyle?: IStyleProp<IViewStyle>;
+};

package/src/core/tab-router-state/index.ts

@@ -0,0 +1,75 @@
+// TabRouter: the logic half (framework-agnostic, zero render). A pure reducer over a FOCUSED
+// INDEX into a fixed route list - jumpTo/setParams - mirroring what @react-navigation/routers'
+// TabRouter keeps, minus the React-specific action-creator/linking machinery. The key structural
+// difference from navigator-state's Stack: tabs never push/pop a route, they move a focused
+// index between a fixed set (mirrors TabRouter.getInitialState / getStateForAction for
+// JUMP_TO - see the tab-actions docs: jumpTo takes a route NAME, not a stack push). Route
+// identity (`key`) is generated by the CALLER, same convention as navigator-state.ts - reused
+// verbatim from there so Stack and Tabs share one route shape.
+
+import { mergeParams } from '../guards';
+import type { IRoute } from '../navigator-state';
+
+export type { IRoute } from '../navigator-state';
+
+type IRouteEntry = IRoute<unknown>;
+
+export type ITabRouterState = Readonly<{
+  routes: readonly IRouteEntry[];
+  index: number;
+}>;
+
+export type ITabRouterAction =
+  | { type: 'jumpTo'; name: string; params?: unknown }
+  | { type: 'setParams'; key: string; params: unknown };
+
+const INITIAL_FOCUSED_INDEX = 0;
+
+export function createInitialTabState(
+  routes: readonly IRouteEntry[],
+  initialRouteName?: string,
+): ITabRouterState {
+  if (initialRouteName === undefined) return { routes, index: INITIAL_FOCUSED_INDEX };
+  const index = routes.findIndex(route => route.name === initialRouteName);
+  return { routes, index: index === -1 ? INITIAL_FOCUSED_INDEX : index };
+}
+
+// jumpTo moves the focused index to an existing route by name and optionally merges params
+// (navigation.jumpTo(name, params) - the tab-actions doc's own signature); it never adds,
+// removes, or reorders routes (mirrors TabRouter: JUMP_TO is a no-op when the target name isn't
+// registered, same as navigatorReducer's popTo bailing on an unknown key). setParams merges into
+// the target route's params by key (CommonActions.setParams semantics - a merge, not a replace).
+export function tabRouterReducer(
+  state: ITabRouterState,
+  action: ITabRouterAction,
+): ITabRouterState {
+  switch (action.type) {
+    case 'jumpTo': {
+      const index = state.routes.findIndex(route => route.name === action.name);
+      if (index === -1) return state;
+      if (action.params === undefined) {
+        return index === state.index ? state : { ...state, index };
+      }
+      const target = state.routes[index];
+      const routes = state.routes.slice();
+      routes[index] = { ...target, params: mergeParams(target.params, action.params) };
+      return { ...state, index, routes };
+    }
+
+    case 'setParams': {
+      const index = state.routes.findIndex(route => route.key === action.key);
+      if (index === -1) return state;
+      const target = state.routes[index];
+      const routes = state.routes.slice();
+      routes[index] = { ...target, params: mergeParams(target.params, action.params) };
+      return { ...state, routes };
+    }
+
+    default:
+      return state;
+  }
+}
+
+export function isFocusedRoute(index: number, focusedIndex: number): boolean {
+  return index === focusedIndex;
+}

package/src/core/tab-router-state/tab-router-state.test.ts

@@ -0,0 +1,34 @@
+// Co-located unit test (ADR 0025) for the pure tab-router reducer, targeting the params-merge
+// behavior of jumpTo/setParams directly, framework-free - twin of navigator-state.test.ts's
+// setParams coverage.
+
+import { describe, expect, it } from 'vitest';
+import { tabRouterReducer } from './index';
+import type { ITabRouterState } from './index';
+
+const FEED = { key: 'feed-1', name: 'Feed', params: { sort: 'new' } };
+const PROFILE = { key: 'profile-1', name: 'Profile', params: { id: 1 } };
+
+function twoRouteState(): ITabRouterState {
+  return { routes: [FEED, PROFILE], index: 0 };
+}
+
+describe('tabRouterReducer — params merge guards against array params', () => {
+  it('jumpTo replaces (not merges) params when incoming params is an array', () => {
+    const next = tabRouterReducer(twoRouteState(), {
+      type: 'jumpTo',
+      name: 'Profile',
+      params: [1, 2, 3],
+    });
+    expect(next.routes[1].params).toEqual([1, 2, 3]);
+  });
+
+  it('setParams replaces (not merges) params when incoming params is an array', () => {
+    const next = tabRouterReducer(twoRouteState(), {
+      type: 'setParams',
+      key: 'profile-1',
+      params: [1, 2, 3],
+    });
+    expect(next.routes[1].params).toEqual([1, 2, 3]);
+  });
+});

package/src/globals.d.ts

@@ -0,0 +1,4 @@
+// Runtime global provided by the Hermes/RN host but absent from the ES2022 lib this package
+// builds against (no DOM, no @types/node - see core/engine/src/globals.d.ts's identical
+// declaration, which this package's own tsconfig scope doesn't inherit).
+declare function queueMicrotask(callback: () => void): void;

package/src/react/collect-registry.ts

@@ -0,0 +1,19 @@
+// Shared by stack.ts/tabs.ts/drawer.ts: each navigator registers its own Screen marker
+// component's props into a name -> entry map via React.Children, differing only in the marker
+// component (isMarkerElement) and the props shape (TProps). Stays in react/ rather than core/:
+// Children/isValidElement are React-only APIs (see CLAUDE.md <adapter_src_follows_framework_idioms>).
+
+import { Children, type ReactElement, type ReactNode } from 'react';
+
+export function collectRegistry<TProps extends { name: string }>(
+  children: ReactNode,
+  isMarkerElement: (child: ReactNode) => child is ReactElement<TProps>,
+): Map<string, Omit<TProps, 'name'>> {
+  const registry = new Map<string, Omit<TProps, 'name'>>();
+  Children.forEach(children, child => {
+    if (!isMarkerElement(child)) return;
+    const { name, ...entry } = child.props;
+    registry.set(name, entry);
+  });
+  return registry;
+}