@symbiote-native/navigation 2.0.3 → 2.2.0

package/src/core/render-tabs.ts

@@ -9,7 +9,12 @@
 
 import { el, txt } from '@symbiote-native/components';
 import type { IDescriptor } from '@symbiote-native/components';
-import type { IColorValue, IViewStyle, ITextStyle, IStyleProp } from '@symbiote-native/engine';
+import type {
+  IColorValue,
+  IViewStyle,
+  ITextStyle,
+  IStyleProp,
+} from '@symbiote-native/engine';
 import type { ITabBarIcon } from './tab-options';
 
 // react-navigation's own bottom-tabs default to the surrounding theme's primary/text colors;
@@ -96,14 +101,19 @@ function resolveTintColor(item: ITabBarItemView): IColorValue {
 // for a vector-icon-font label); an IDescriptor icon (an <Image>/vector-icon element the adapter
 // already resolved) is spliced in verbatim, exactly like renderHeaderConfig treats a pre-built
 // Descriptor child.
-function renderIcon(icon: ITabBarIcon | undefined, color: IColorValue): IDescriptor | undefined {
+function renderIcon(
+  icon: ITabBarIcon | undefined,
+  color: IColorValue,
+): IDescriptor | undefined {
   if (icon === undefined) return undefined;
   if (typeof icon === 'string')
     return txt({ style: { color, fontSize: TAB_ICON_FONT_SIZE } }, [icon]);
   return icon;
 }
 
-function renderBadge(badge: string | number | undefined): IDescriptor | undefined {
+function renderBadge(
+  badge: string | number | undefined,
+): IDescriptor | undefined {
   if (badge === undefined) return undefined;
   return el('symbiote-view', { style: BADGE_STYLE }, [
     txt({ style: BADGE_TEXT_STYLE }, [String(badge)]),
@@ -121,8 +131,12 @@ export function renderTabBarItem(item: ITabBarItemView): IDescriptor {
 
   const children: IDescriptor[] = [];
   if (iconChildren.length > 0)
-    children.push(el('symbiote-view', { style: ICON_WRAPPER_STYLE }, iconChildren));
-  children.push(txt({ style: { color, fontSize: TAB_LABEL_FONT_SIZE } }, [item.label]));
+    children.push(
+      el('symbiote-view', { style: ICON_WRAPPER_STYLE }, iconChildren),
+    );
+  children.push(
+    txt({ style: { color, fontSize: TAB_LABEL_FONT_SIZE } }, [item.label]),
+  );
 
   return el(
     'symbiote-view',
@@ -134,5 +148,9 @@ export function renderTabBarItem(item: ITabBarItemView): IDescriptor {
 
 export function renderTabBar(view: ITabBarViewProps): IDescriptor {
   const items = view.items.map(renderTabBarItem);
-  return el('symbiote-view', { ...view.passthrough, style: [TAB_BAR_STYLE, view.style] }, items);
+  return el(
+    'symbiote-view',
+    { ...view.passthrough, style: [TAB_BAR_STYLE, view.style] },
+    items,
+  );
 }

package/src/core/screen-options.ts

@@ -20,7 +20,10 @@ import type {
   ISheetInitialDetent,
   ISheetLargestUndimmedDetent,
 } from './navigator-props';
-import { buildHeaderBarButtonDispatch, prepareHeaderBarButtonItems } from './header-bar-buttons';
+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
@@ -31,7 +34,9 @@ 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[] {
+function resolveSheetAllowedDetents(
+  compat: ISheetAllowedDetents | undefined,
+): number[] {
   if (compat === undefined) return SHEET_COMPAT_LARGE;
   if (Array.isArray(compat)) return compat;
   switch (compat) {
@@ -74,7 +79,9 @@ function resolveSheetInitialDetent(
   return compat;
 }
 
-function toOptionalBooleanNativeProp(value: boolean | undefined): IOptionalBooleanNativeProp {
+function toOptionalBooleanNativeProp(
+  value: boolean | undefined,
+): IOptionalBooleanNativeProp {
   if (value === undefined) return 'undefined';
   return value ? 'true' : 'false';
 }
@@ -119,7 +126,9 @@ export function resolveScreenView(
   options: IScreenOptions | undefined,
   passthrough: Record<string, unknown> = {},
 ): IScreenViewProps {
-  const sheetAllowedDetents = resolveSheetAllowedDetents(options?.sheetAllowedDetents);
+  const sheetAllowedDetents = resolveSheetAllowedDetents(
+    options?.sheetAllowedDetents,
+  );
   const lastDetentIndex = sheetAllowedDetents.length - 1;
   return {
     screenId,
@@ -142,7 +151,8 @@ export function resolveScreenView(
     sheetExpandsWhenScrolledToEdge: options?.sheetExpandsWhenScrolledToEdge,
     sheetElevation: options?.sheetElevation,
     sheetShouldOverflowTopInset: options?.sheetShouldOverflowTopInset,
-    sheetDefaultResizeAnimationEnabled: options?.sheetDefaultResizeAnimationEnabled,
+    sheetDefaultResizeAnimationEnabled:
+      options?.sheetDefaultResizeAnimationEnabled,
     statusBarStyle: options?.statusBarStyle,
     statusBarHidden: options?.statusBarHidden,
     statusBarAnimation: options?.statusBarAnimation,

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

@@ -5,7 +5,11 @@
 // 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';
+import {
+  dispatchViewCommand,
+  dlog,
+  type ISymbioteNode,
+} from '@symbiote-native/engine';
 
 export interface ISearchBarCommands {
   focus(): void;
@@ -21,7 +25,10 @@ export interface ISearchBarCommands {
 // 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 {
+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()}`,
@@ -45,7 +52,9 @@ function makeCommand(
 
 // `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 {
+export function buildSearchBarHandle(
+  getNode: () => ISymbioteNode | null,
+): ISearchBarCommands {
   return {
     focus: makeCommand(getNode, 'focus'),
     blur: makeCommand(getNode, 'blur'),

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

@@ -0,0 +1,52 @@
+// StackRouter: the registry-reconciliation half (framework-agnostic, zero render). A Stack's route
+// list is navigation HISTORY, not a projection of the registered `<Stack.Screen>` markers the way a
+// Tab's is (tab-router-state) - it seeds exactly one route and grows only through push/replace. So
+// a marker that unregisters while its route still sits in the history (a marker behind an `{#if}`,
+// a data-driven screen list) leaves behind an entry nothing can render: the route stays, the
+// adapter's componentFor() finds no screen, and the user is parked on a blank RNSScreen with no
+// way to tell what happened. Mirrors @react-navigation/routers' StackRouter.getStateForRouteNames-
+// Change, which filters those routes out of the history and pulls the focused index back into
+// range.
+//
+// Deliberately NOT a navigatorReducer action: this is not something a caller dispatches, it is a
+// reaction to the registry changing underneath an unchanged history, and each adapter observes
+// that change through its own lifecycle. Keeping it a separate pure function lets every adapter
+// wire it its own way without teaching the reducer about a registry it has never seen.
+
+import type { INavigatorState } from '../navigator-state';
+
+// The contract, and the two places it deliberately parts from upstream:
+//
+// - SURVIVORS KEEP THEIR IDENTITY. A stack route's key is COUNTER-derived (every adapter's
+//   createRoute increments a per-navigator sequence), not name-derived like a tab route's, so
+//   re-deriving the list from the registry would hand every survivor a brand-new key and remount
+//   live screens. Only the phantom entries go; every other route object passes through by
+//   reference, params included.
+//
+// - THE FOCUSED ROUTE IS THE TOP ONE. This state carries no `index` field: the focused route is
+//   always the last one (see computeActivityState's comment for why no route can outrank it), so
+//   upstream's `index: Math.min(state.index, routes.length - 1)` degenerates here to "the last
+//   survivor". Dropping the FOCUSED route therefore lands the user on the nearest still-registered
+//   route beneath it - where a pop() would have left them - rather than on nothing.
+//
+// - THE ROUTE LIST IS NEVER EMPTIED. `routes.length - 1` IS the focused index, so an empty list
+//   means no focused route at all - the blank screen this function exists to prevent. When nothing
+//   in the history survives (every marker gone, or the whole screen set swapped for new names) the
+//   state is returned UNCHANGED. Upstream instead pushes a freshly nanoid()-keyed route for
+//   initialRouteName; we cannot, because minting a route key belongs to the caller here
+//   (navigator-state.ts's header) and a derivation that mints one would allocate a new key on every
+//   re-run. Unchanged is also the right answer for the usual cause of a momentarily empty registry
+//   - markers unregistering and re-registering across a re-render - since the next run reconciles
+//   for real.
+export function reconcileStackRoutes(
+  state: INavigatorState,
+  registeredNames: readonly string[],
+): INavigatorState {
+  const routes = state.routes.filter(route =>
+    registeredNames.includes(route.name),
+  );
+  // filter preserves order, so an unchanged length means nothing was dropped.
+  if (routes.length === state.routes.length || routes.length === 0)
+    return state;
+  return { routes };
+}

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

@@ -11,11 +11,19 @@ import { isRecord } from '../guards';
 // 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';
+  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);
+  return (
+    isRecord(value) &&
+    Array.isArray(value.routes) &&
+    value.routes.every(isRoute)
+  );
 }
 
 export function serializeNavigatorState(state: INavigatorState): unknown {
@@ -24,7 +32,9 @@ export function serializeNavigatorState(state: INavigatorState): unknown {
 
 export function deserializeNavigatorState(raw: unknown): INavigatorState {
   if (!isNavigatorState(raw)) {
-    throw new Error('deserializeNavigatorState: persisted value is not a valid navigator state');
+    throw new Error(
+      'deserializeNavigatorState: persisted value is not a valid navigator state',
+    );
   }
   return raw;
 }

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

@@ -29,11 +29,37 @@ export function createInitialTabState(
   routes: readonly IRouteEntry[],
   initialRouteName?: string,
 ): ITabRouterState {
-  if (initialRouteName === undefined) return { routes, index: INITIAL_FOCUSED_INDEX };
+  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 };
 }
 
+// A screen marker can appear or disappear after mount (a marker behind an `{#if}`, a data-driven
+// screen list), so a navigator's route list has to follow its registry instead of staying frozen
+// at whatever createInitialTabState saw first. Mirrors TabRouter.getStateForRouteNamesChange:
+// membership and order come from `nextRoutes`, but a route that survives keeps its IDENTITY (its
+// key) and everything jumpTo/setParams accumulated onto its params - only genuinely new names
+// take their entry from `nextRoutes`. Focus follows the previously focused route's NAME, so an
+// unrelated screen disappearing never moves the user; when the focused route is the one that
+// disappeared, focus falls back to the first route, the same landing spot every unresolvable
+// focus gets here (createInitialTabState's own fallback).
+export function reconcileTabRoutes(
+  state: ITabRouterState,
+  nextRoutes: readonly IRouteEntry[],
+): ITabRouterState {
+  const routes = nextRoutes.map(
+    next => state.routes.find(route => route.name === next.name) ?? next,
+  );
+  const isUnchanged =
+    routes.length === state.routes.length &&
+    routes.every((route, at) => route === state.routes[at]);
+  if (isUnchanged) return state;
+  const focusedName = state.routes[state.index]?.name;
+  const index = routes.findIndex(route => route.name === focusedName);
+  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
@@ -52,7 +78,10 @@ export function tabRouterReducer(
       }
       const target = state.routes[index];
       const routes = state.routes.slice();
-      routes[index] = { ...target, params: mergeParams(target.params, action.params) };
+      routes[index] = {
+        ...target,
+        params: mergeParams(target.params, action.params),
+      };
       return { ...state, index, routes };
     }
 
@@ -61,7 +90,10 @@ export function tabRouterReducer(
       if (index === -1) return state;
       const target = state.routes[index];
       const routes = state.routes.slice();
-      routes[index] = { ...target, params: mergeParams(target.params, action.params) };
+      routes[index] = {
+        ...target,
+        params: mergeParams(target.params, action.params),
+      };
       return { ...state, routes };
     }