@symbiote-native/navigation 2.0.3 → 2.2.0

package/src/svelte/runes/use-tab-navigation.svelte.ts

@@ -0,0 +1,29 @@
+// Twin of use-stack-navigation.svelte.ts, narrowing to a Tab handle instead.
+
+import type { ITabNavigatorHandle } from '../../core';
+import { isTabNavigatorHandle } from '../../core';
+import { useNavigation } from './use-navigation.svelte';
+import type { INavigationHandle } from './use-navigation.svelte';
+
+export type ITabNavigationHandle = ITabNavigatorHandle &
+  Pick<INavigationHandle, 'addListener' | 'getParent'>;
+
+export function useTabNavigation(): { readonly current: ITabNavigationHandle } {
+  const navigation = useNavigation();
+  const narrowed = $derived.by<ITabNavigationHandle>(() => {
+    const value = navigation.current;
+    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;
+  });
+
+  return {
+    get current(): ITabNavigationHandle {
+      return narrowed;
+    },
+  };
+}

package/src/svelte/screen-props.ts

@@ -0,0 +1,50 @@
+// Stack.Screen's public prop surface. Split out of `screen.svelte` because plain `tsc --build`
+// resolves an import of a `.svelte` file through svelte's own ambient `declare module '*.svelte'`
+// fallback (a bare default export only) and never parses the real `<script module>` block - so a
+// NAMED type re-exported from a `.svelte` file is invisible to `tsc`. Same rule the Svelte
+// adapter's own `view-props.ts` / `switch-props.ts` follow.
+
+import type { Component } from 'svelte';
+import type {
+  INavigatorHandle,
+  IRoute,
+  IScreenOptions,
+  ISearchBarCommands,
+  ISearchBarOptions,
+} from '../core';
+
+// The imperative search-bar handle (focus/blur/clearText/setText/cancelSearch/
+// toggleCancelButton) is delivered through a MUTABLE CELL the app owns, not a Svelte rune: per
+// CLAUDE.md's <prop_types_split_agnostic_vs_per_adapter> a framework ref cannot live in the
+// shared, agnostic ISearchBarOptions, and Svelte has no `Ref`/`RefObject` type of its own to
+// name here. `{ current }` is the same shape Angular's IAngularSearchBarOptions uses, and an app
+// that wants to react to it simply declares the cell with `$state`.
+export type ISvelteSearchBarOptions = ISearchBarOptions & {
+  ref?: { current: ISearchBarCommands | null };
+};
+
+export type ISvelteScreenOptions = Omit<
+  IScreenOptions,
+  'headerSearchBarOptions'
+> & {
+  headerSearchBarOptions?: ISvelteSearchBarOptions;
+};
+
+// The options resolver runs OUTSIDE render (during the options fold), so it still receives the
+// route + navigator handle explicitly - screens read those through runes, but a resolver has no
+// component scope to read context from.
+export type IScreenOptionsArgs = {
+  route: IRoute<unknown>;
+  navigation: INavigatorHandle;
+};
+
+export type IScreenOptionsResolver = (
+  args: IScreenOptionsArgs,
+) => ISvelteScreenOptions;
+
+export type IScreenProps = {
+  name: string;
+  component: Component;
+  options?: ISvelteScreenOptions | IScreenOptionsResolver;
+  initialParams?: unknown;
+};

package/src/svelte/screen-registry.ts

@@ -0,0 +1,98 @@
+// 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`. Svelte has NO equivalent: a
+// component receives its children as an opaque `Snippet`, with no way to enumerate or inspect
+// what is inside it (the same wall the Svelte adapter's ScrollView hit for
+// `stickyHeaderIndices`, svelte-adapter-dom-shim skill §18). So registration is INVERTED here:
+// the navigator publishes a collector on the context, each marker registers ITSELF during its own
+// init, and the navigator's route list derives from what came back.
+//
+// Ordering works out because Svelte's initial render is synchronous and top-down: a navigator
+// renders the children snippet BEFORE the `{#each}` that paints its routes, so by the time the
+// route list is first read every marker has already registered. Verified against the real
+// compiler, not assumed.
+//
+// ONE key, not one per navigator kind: nearest-navigator-wins shadowing falls out of Svelte's own
+// context lookup, so a Stack nested inside a Tab screen automatically captures its own markers.
+// The `kind` tag then rejects a MISMATCHED marker (a `<Tab.Screen>` written inside a `<Stack>`)
+// instead of letting it silently register with some far-away ancestor Tab - the failure mode a
+// per-kind key would have.
+
+import { getContext, onDestroy, setContext } from 'svelte';
+import type { Component } from 'svelte';
+import { dlog } from '@symbiote-native/engine';
+
+export type INavigatorKind = 'stack' | 'tab' | 'drawer';
+
+// Every field is a GETTER on the marker's own `$props()` bindings, so an app that reassigns
+// `options`/`component` on an already-mounted marker keeps the navigator's view of it live -
+// the same reason Angular's Stack stores the ScreenDirective INSTANCE rather than a snapshot of
+// its fields. `name` is read live too, so renaming a screen re-keys it rather than going stale.
+export type IRegisteredScreen<TOptions> = {
+  readonly name: string;
+  readonly component: Component;
+  readonly options: TOptions | undefined;
+  readonly initialParams: unknown;
+};
+
+export type IScreenCollector<TOptions> = {
+  readonly kind: INavigatorKind;
+  register(screen: IRegisteredScreen<TOptions>): void;
+  unregister(screen: IRegisteredScreen<TOptions>): void;
+};
+
+const SCREEN_COLLECTOR_KEY = Symbol('symbiote-navigation-screen-collector');
+
+// Called once from a navigator's own init, before it renders the children snippet.
+export function setScreenCollector<TOptions>(
+  collector: IScreenCollector<TOptions>,
+): void {
+  setContext(SCREEN_COLLECTOR_KEY, collector);
+}
+
+// Called once from a marker's own init. Registration is undone on destroy, so a marker behind an
+// `{#if}` disappears from the registry exactly like a Vue slot scan stops seeing a removed vnode.
+export function collectScreen<TOptions>(
+  kind: INavigatorKind,
+  screen: IRegisteredScreen<TOptions>,
+): void {
+  const collector = getContext<IScreenCollector<TOptions> | undefined>(
+    SCREEN_COLLECTOR_KEY,
+  );
+  if (collector === undefined) {
+    dlog(
+      `navigation: <${kind} screen "${screen.name}"> rendered outside any navigator, ignored`,
+    );
+    return;
+  }
+  if (collector.kind !== kind) {
+    dlog(
+      `navigation: a ${kind} screen marker ("${screen.name}") was rendered inside a ` +
+        `${collector.kind} navigator, ignored`,
+    );
+    return;
+  }
+  collector.register(screen);
+  onDestroy(() => collector.unregister(screen));
+}
+
+// The navigator side of the pair: a plain, non-reactive list plus the two mutators the collector
+// exposes. The navigator holds the list in `$state.raw` and reassigns it (never mutates in place)
+// so a component reference - a plain function - is never wrapped in a deep reactive proxy, which
+// would break both the getters above and Svelte's own component identity checks.
+export function withoutScreen<TOptions>(
+  screens: readonly IRegisteredScreen<TOptions>[],
+  screen: IRegisteredScreen<TOptions>,
+): IRegisteredScreen<TOptions>[] {
+  return screens.filter(candidate => candidate !== screen);
+}
+
+// name -> entry, last registration wins, exactly like Vue's collectRegistry Map.
+export function toRegistry<TOptions>(
+  screens: readonly IRegisteredScreen<TOptions>[],
+): Map<string, IRegisteredScreen<TOptions>> {
+  const registry = new Map<string, IRegisteredScreen<TOptions>>();
+  for (const screen of screens) registry.set(screen.name, screen);
+  return registry;
+}

package/src/svelte/screen.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+  // Stack.Screen: a declarative marker that paints nothing. Stack reads it through the
+  // context-based collector (screen-registry.ts) rather than by scanning children the way React
+  // and Vue can, then mounts the registered component itself for each pushed route.
+  //
+  // Every field is handed over as a GETTER over this component's own `$props()` bindings, so the
+  // navigator always sees the CURRENT value - reassigning `options` on an already-mounted marker
+  // reaches the next options fold without re-registering.
+  import { collectScreen } from './screen-registry';
+  import type { IScreenProps } from './screen-props';
+
+  let { name, component, options, initialParams }: IScreenProps = $props();
+
+  collectScreen('stack', {
+    get name(): IScreenProps['name'] {
+      return name;
+    },
+    get component(): IScreenProps['component'] {
+      return component;
+    },
+    get options(): IScreenProps['options'] {
+      return options;
+    },
+    get initialParams(): unknown {
+      return initialParams;
+    },
+  });
+</script>

package/src/svelte/stack/index.svelte

@@ -0,0 +1,261 @@
+<script lang="ts" module>
+  // Stack, the Svelte lifecycle half. The route-stack transitions (navigator-state) and the
+  // options/props folds (screen-options, render-stack) live in @symbiote-native/navigation core,
+  // shared verbatim with the React/Vue/Angular entries; here Svelte supplies the lifecycle -
+  // `$state.raw` for the pushed-route stack (its twin of useReducer: reassign from the same pure
+  // reducer), a module counter for route-key generation, `export function`s for the push/pop/
+  // replace navigator handle (Svelte's twin of Vue's expose(), reachable via `bind:this`) - plus
+  // the react-native-screens chrome per route (stack-screen.svelte). Pushing/popping a route is
+  // an ordinary child mount/unmount: RNSScreenStack diffs its RNSScreen children natively, so no
+  // imperative native command is needed here at all. Neither this nor the Screen marker imports
+  // react-native-screens' own React components (ScreenStack.tsx et al - hooks, crashes a
+  // non-React adapter); the native views are driven directly through the ViewConfig ../../register
+  // registers. See CLAUDE.md <third_party_rn_packages_are_react_only>.
+  //
+  // HOW SCREENS ARE DISCOVERED: not by reading `children`, which Svelte hands over as an opaque
+  // Snippet - the markers register themselves through the context collector (../screen-registry.ts)
+  // while the snippet renders, and the route list derives from that. The snippet is rendered
+  // inside a collapsed `symbiote-text` (../registry-host.ts) so whitespace between two markers
+  // can never become an illegal raw-text child of a native view.
+
+  // Route keys must be unique per Stack INSTANCE (Svelte has no useId); a module counter is the
+  // same mechanism the Angular entry uses.
+  let stackInstanceCounter = 0;
+
+  const STACK_ROOT_PROPS: Record<string, unknown> = { style: { flex: 1 } };
+</script>
+
+<script lang="ts">
+  import type { Component } from 'svelte';
+  import { dlog } from '@symbiote-native/engine';
+  import {
+    NAVIGATION_EVENT_STATE,
+    RNS_SCREEN_STACK_VIEW_NAME,
+    STACK_ON_FINISH_TRANSITIONING,
+    createInitialNavigatorState,
+    createNavigationEmitter,
+    navigatorReducer,
+    reconcileStackRoutes,
+    resolveStackProps,
+  } from '../../core';
+  import type {
+    INavigationEmitter,
+    INavigatorAction,
+    INavigatorHandle,
+    INavigatorState,
+    IRoute,
+  } from '../../core';
+  import { hostProps } from '../attachments';
+  import { getNavigationScope } from '../navigation-context';
+  import { SCREEN_REGISTRY_HOST_PROPS } from '../registry-host';
+  import {
+    setScreenCollector,
+    toRegistry,
+    withoutScreen,
+  } from '../screen-registry';
+  import type { IRegisteredScreen } from '../screen-registry';
+  import type { IScreenProps, ISvelteScreenOptions } from '../screen-props';
+  import StackScreen from './stack-screen.svelte';
+  import type { IStackProps } from './stack-props';
+
+  let { initialRouteName, screenOptions, children }: IStackProps = $props();
+
+  // Read BEFORE this Stack establishes its own per-screen NavigationScope - becomes the `parent`
+  // link a nested screen's useNavigation().getParent() walks (e.g. this Stack rendered as a Tab
+  // screen's content reaches that Tab via this value). undefined when this Stack is the nesting
+  // root. Kept as the BOX, not its unwrapped value, so every read below sees the current one.
+  const parentScope = getNavigationScope();
+
+  const routeIdPrefix = `stack-${(stackInstanceCounter += 1)}`;
+
+  // `$state.raw` + reassignment, never a mutated array: an entry holds a component reference (a
+  // plain function) behind live getters, and a deep reactive proxy would wrap both.
+  let screens = $state.raw<IRegisteredScreen<IScreenProps['options']>[]>([]);
+  setScreenCollector<IScreenProps['options']>({
+    kind: 'stack',
+    register: screen => {
+      screens = [...screens, screen];
+    },
+    unregister: screen => {
+      screens = withoutScreen(screens, screen);
+    },
+  });
+
+  const registry = $derived(toRegistry(screens));
+
+  let routeSequence = 0;
+  function createRoute(name: string, params: unknown): IRoute<unknown> {
+    routeSequence += 1;
+    return { key: `${routeIdPrefix}-${name}-${routeSequence}`, name, params };
+  }
+
+  // The pushed stack only exists once something has dispatched; until then the state derives from
+  // whatever the markers registered. `seededState` is a PLAIN local (not `$state`), so memoizing
+  // it inside the derivation below is not a state write during a derivation - it just makes the
+  // one route-key-allocating call happen exactly once, no matter how often the derivation re-runs
+  // as markers register.
+  let pushedState = $state.raw<INavigatorState | null>(null);
+  let seededState: INavigatorState | undefined;
+
+  function seedState(): INavigatorState {
+    if (seededState !== undefined) return seededState;
+    const startRouteName = initialRouteName ?? registry.keys().next().value;
+    if (startRouteName === undefined) {
+      dlog('Stack: no <Stack.Screen> children registered');
+      // Deliberately NOT memoized: markers may still be registering, and the next derivation run
+      // should get a real initial route rather than being stuck on this placeholder.
+      return createInitialNavigatorState({
+        key: routeIdPrefix,
+        name: '',
+        params: undefined,
+      });
+    }
+    seededState = createInitialNavigatorState(
+      createRoute(startRouteName, registry.get(startRouteName)?.initialParams),
+    );
+    return seededState;
+  }
+
+  // A `<Stack.Screen>` marker can unregister while its route is still in the pushed history (a
+  // marker behind an `{#if}`, a data-driven screen list), which would leave that entry with nothing
+  // for componentFor() to mount (reconcileStackRoutes' header). The reconciliation belongs in the
+  // derivation because it is PURE - it hands back the same state reference when nothing changed, so
+  // it writes no state and cannot re-trigger itself; `dispatch` below then persists the pruned
+  // history, since it reduces over this value rather than over `pushedState`.
+  const state = $derived(
+    reconcileStackRoutes(pushedState ?? seedState(), [...registry.keys()]),
+  );
+
+  function dispatch(action: INavigatorAction): void {
+    pushedState = navigatorReducer(state, action);
+  }
+
+  // One emitter per route.key, created lazily the first time a route is rendered and pruned once
+  // it is popped off the stack (the broadcast effect below).
+  const emitters = new Map<string, INavigationEmitter>();
+  function emitterFor(routeKey: string): INavigationEmitter {
+    let emitter = emitters.get(routeKey);
+    if (emitter === undefined) {
+      emitter = createNavigationEmitter();
+      emitters.set(routeKey, emitter);
+    }
+    return emitter;
+  }
+
+  export function push(name: string, params?: unknown): void {
+    dispatch({ type: 'push', route: createRoute(name, params) });
+  }
+  export function pop(count?: number): void {
+    dispatch({ type: 'pop', count });
+  }
+  export function popToTop(): void {
+    dispatch({ type: 'popToTop' });
+  }
+  export function popTo(key: string): void {
+    dispatch({ type: 'popTo', key });
+  }
+  export function replace(name: string, params?: unknown): void {
+    dispatch({ type: 'replace', route: createRoute(name, params) });
+  }
+  export function setParams(params: unknown, key?: string): void {
+    dispatch({ type: 'setParams', key, params });
+  }
+  export function reset(nextState: INavigatorState): void {
+    dispatch({ type: 'reset', state: nextState });
+  }
+  export function canGoBack(): boolean {
+    return state.routes.length > 1;
+  }
+
+  // The same handle, as a value, for everything that needs it INSIDE this component (the options
+  // fold's `navigation` argument, every route's NavigationScope). `bind:this` exposes the
+  // `export function`s above; this object is the internal twin of that surface.
+  const handle: INavigatorHandle = {
+    push,
+    pop,
+    popToTop,
+    popTo,
+    replace,
+    setParams,
+    reset,
+    canGoBack,
+  };
+
+  function popOne(): void {
+    dispatch({ type: 'pop', count: 1 });
+  }
+
+  // Broadcasts the router state to every still-live route's emitter (useNavigationState's source)
+  // after each commit, and prunes emitters for routes popped off the stack. Runs as an $effect
+  // rather than inline in the render path (Vue's shape), so the first broadcast lands AFTER the
+  // initial route's own screen has mounted and subscribed.
+  $effect(() => {
+    const current = state;
+    for (const route of current.routes) {
+      emitterFor(route.key).emit(NAVIGATION_EVENT_STATE, current);
+    }
+    for (const routeKey of [...emitters.keys()]) {
+      if (!current.routes.some(route => route.key === routeKey))
+        emitters.delete(routeKey);
+    }
+  });
+
+  // Investigation instrumentation (flicker-on-focus bug): STACK_ON_FINISH_TRANSITIONING is the
+  // native signal that the WHOLE push/pop animation has finished (as opposed to onAppear/
+  // onDisappear, which are per-screen) - logging it lets the per-screen appear/disappear
+  // timestamps be checked against the actual transition-complete moment. Kept behind DEBUG,
+  // never removed.
+  const stackProps = resolveStackProps({
+    passthrough: {
+      [STACK_ON_FINISH_TRANSITIONING]: () =>
+        dlog(`Stack: onFinishTransitioning at t=${Date.now()}`),
+    },
+  });
+
+  function optionsFor(route: IRoute<unknown>): ISvelteScreenOptions {
+    const entry = registry.get(route.name);
+    const own =
+      entry === undefined
+        ? undefined
+        : typeof entry.options === 'function'
+          ? entry.options({ route, navigation: handle })
+          : entry.options;
+    return { ...screenOptions, ...own };
+  }
+
+  function componentFor(route: IRoute<unknown>): Component | undefined {
+    const entry = registry.get(route.name);
+    if (entry === undefined) {
+      dlog(`Stack: no screen registered for route name "${route.name}"`);
+      return undefined;
+    }
+    return entry.component;
+  }
+</script>
+
+<symbiote-view p={STACK_ROOT_PROPS}>
+  <symbiote-text p={SCREEN_REGISTRY_HOST_PROPS}>
+    {@render children?.()}
+  </symbiote-text>
+  <svelte:element
+    this={RNS_SCREEN_STACK_VIEW_NAME}
+    {@attach hostProps(stackProps)}
+  >
+    {#each state.routes as route, index (route.key)}
+      {@const screenComponent = componentFor(route)}
+      {#if screenComponent !== undefined}
+        <StackScreen
+          {route}
+          {index}
+          routeCount={state.routes.length}
+          options={optionsFor(route)}
+          navigation={handle}
+          emitter={emitterFor(route.key)}
+          parentScope={parentScope?.current}
+          component={screenComponent}
+          onPopRequested={popOne}
+        />
+      {/if}
+    {/each}
+  </svelte:element>
+</symbiote-view>

package/src/svelte/stack/index.ts

@@ -0,0 +1,11 @@
+// `Stack.Screen` alongside the standalone `Screen` export, matching React's and Vue's barrels.
+// A compiled Svelte component is an ordinary function object, so attaching the marker to it is
+// the same Object.assign the other entries do - and `<Stack.Screen />` resolves through Svelte's
+// member-expression component tags (verified against the real compiler).
+import StackImpl from './index.svelte';
+import Screen from '../screen.svelte';
+
+export const Stack = Object.assign(StackImpl, { Screen });
+
+export type { INavigatorHandle } from '../../core';
+export type { IStackProps } from './stack-props';

package/src/svelte/stack/stack-props.ts

@@ -0,0 +1,31 @@
+// Stack's own public prop surface, and the internal per-route prop surface stack-screen.svelte
+// takes. Both live in a plain `.ts` file for the tsc-cannot-see-a-`.svelte`-named-export reason
+// ../screen-props.ts documents.
+
+import type { Component, Snippet } from 'svelte';
+import type { INavigationEmitter, INavigatorHandle, IRoute } from '../../core';
+import type { INavigationScopeValue } from '../navigation-context';
+import type { ISvelteScreenOptions } from '../screen-props';
+
+// React's `children?: ReactNode` / Vue's default slot become a Svelte Snippet holding the
+// `<Stack.Screen>` markers.
+export type IStackProps = {
+  initialRouteName?: string;
+  screenOptions?: ISvelteScreenOptions;
+  children?: Snippet;
+};
+
+export type IStackScreenProps = {
+  route: IRoute<unknown>;
+  index: number;
+  routeCount: number;
+  options: ISvelteScreenOptions;
+  navigation: INavigatorHandle;
+  emitter: INavigationEmitter;
+  // The ambient scope the Stack itself read on mount (undefined at the nesting root) - becomes
+  // the `parent` link a nested screen's useNavigation().getParent() walks.
+  parentScope: INavigationScopeValue | undefined;
+  component: Component;
+  // Fired by RNSScreen's own onDismissed / header back button; the Stack pops one route.
+  onPopRequested: () => void;
+};