@symbiote-native/navigation 1.0.0

package/src/vue/linking.ts

@@ -0,0 +1,69 @@
+// useLinkingIntegration: wires the framework-agnostic linking config (../core's
+// resolveRouteFromUrl) onto an existing Stack's INavigatorHandle. Deliberately NOT called from
+// inside stack.ts - 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.
+//
+// Vue-shape difference from React: React's twin takes the RESOLVED `navigatorHandle:
+// INavigatorHandle` directly, because a React hook is called fresh on EVERY render with the
+// caller's current value, and useImperativeHandle's ref assignment (a layout effect) is
+// guaranteed to run before this hook's OWN mount effect, so `handleRef.current` is already
+// populated by the time it's read. Vue's setup() runs exactly ONCE per component instance, so
+// there is no "fresh call every render" to re-supply a resolved value, and a template/h() `ref`
+// only resolves to Stack's expose()d handle AFTER mount - an eagerly-resolved argument evaluated
+// at composable-call time (during setup, before mount) would be null. This composable therefore
+// takes the Stack's `Ref<INavigatorHandle | null>` itself (the ref object, not its resolved
+// value) and reads `.value` lazily inside onMounted - Vue's own onMounted hooks fire bottom-up
+// (children before parents), giving the same "already populated" guarantee React's layout-effect
+// ordering does.
+
+import { onMounted, onUnmounted } from '@vue/runtime-core';
+import type { Ref } from '@vue/runtime-core';
+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 useLinkingIntegration(
+  config: ILinkingConfig,
+  navigatorHandle: Ref<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(`useLinkingIntegration: no route resolved for "${url}"`);
+      return;
+    }
+    dispatch(route.name, route.params);
+  }
+
+  onMounted(() => {
+    const handle = navigatorHandle.value;
+    if (handle === null) {
+      dlog('useLinkingIntegration: navigatorHandle is not yet available at mount time');
+      return;
+    }
+
+    Linking.getInitialURL()
+      .then(url => {
+        if (cancelled || url === null) return;
+        dlog(`useLinkingIntegration: initial URL "${url}"`);
+        applyRoute(url, handle.replace);
+      })
+      .catch((error: unknown) => {
+        dlog(`useLinkingIntegration: getInitialURL failed: ${String(error)}`);
+      });
+
+    subscription = Linking.addEventListener('url', (event: IUrlEvent) => {
+      dlog(`useLinkingIntegration: url event "${event.url}"`);
+      applyRoute(event.url, handle.push);
+    });
+  });
+
+  onUnmounted(() => {
+    cancelled = true;
+    subscription?.remove();
+  });
+}

package/src/vue/navigation-context.ts

@@ -0,0 +1,87 @@
+// The lifecycle half of the framework-agnostic emitter (../core/navigation-events): Vue has no
+// "Context" concept the way React does. The equivalent here is a plain provide/inject
+// getter/setter pair over one shared InjectionKey (mirrors this codebase's own pd-widgets
+// convention: `provideX(value)` writes, `injectX()` reads and throws if nothing was provided), so
+// a screen's subtree can read its own route, navigator handle, and per-route emitter without
+// prop-drilling - the Vue twin of react/navigation-context.ts's React Context, collapsed into one
+// key the same way (a symbiote screen only ever needs its OWN route, no per-navigator
+// param-list generics in v1 scope, see screen.ts).
+//
+// Vue's provide() must run once, synchronously, inside a component's OWN setup(). Unlike React,
+// which re-creates a fresh `<Context.Provider value={...}>` element (and therefore a fresh value)
+// on every render loop iteration, Vue's provide/inject is scoped to the component INSTANCE, not to
+// a render-time position. Stack/Tab/Drawer keep every mounted route's screen alive as a SEPARATE
+// sibling subtree (Stack keeps every pushed route mounted; see stack.ts), and each one needs its
+// OWN distinct provided value (its own route/emitter) invisible to its siblings - that is an
+// inherent property of any hierarchical dependency-injection scheme, provide/inject included, not
+// a React artifact. NavigationScope is the small setup-boundary component that gives each route
+// subtree its own instance to call provideNavigationScope from: stack.ts/tabs.ts/drawer.ts's
+// render loop mounts ONE NavigationScope per route (keyed by route.key, exactly like React's
+// per-route `<NavigationContext.Provider>`), and that instance's setup() calls the setter ONCE,
+// refreshed from the latest `value` prop on every one of ITS OWN re-renders - consumers read
+// `.value` off the injected ref, so a later change (e.g. setParams producing a new route object
+// for the same key) still reaches them reactively.
+//
+// `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 { defineComponent, inject, provide, shallowRef } from '@vue/runtime-core';
+import type { InjectionKey, ShallowRef } from '@vue/runtime-core';
+import type { INavigationEmitter, IRoute, IAnyNavigatorHandle } from '../core';
+export type { IAnyNavigatorHandle };
+
+export type INavigationScopeValue = {
+  route: IRoute<unknown>;
+  navigation: IAnyNavigatorHandle;
+  emitter: INavigationEmitter;
+  parent?: INavigationScopeValue;
+};
+
+const NAVIGATION_SCOPE_KEY: InjectionKey<ShallowRef<INavigationScopeValue>> =
+  Symbol('navigation-scope');
+
+// The setter half of the pair - writes the CURRENT route's scope onto the shared key. Called only
+// from NavigationScope's own setup below (never directly by app code).
+function provideNavigationScope(value: ShallowRef<INavigationScopeValue>): void {
+  provide(NAVIGATION_SCOPE_KEY, value);
+}
+
+// The getter half of the pair - every composable in ./composables and every navigator
+// (stack.ts/tabs.ts/drawer.ts, reading the AMBIENT/parent scope on their own mount) calls this
+// directly; undefined simply means "no ancestor NavigationScope", which is a legitimate state (the
+// nesting root) rather than an error - callers that require one throw their own message.
+export function injectNavigationScope(): ShallowRef<INavigationScopeValue> | undefined {
+  return inject(NAVIGATION_SCOPE_KEY, undefined);
+}
+
+// The "throw if missing" half every composable in ./composables needs (useNavigation, useRoute,
+// useIsFocused, useFocusEffect, useNavigationState) - they all called injectNavigationScope() and
+// threw the same shaped error, differing only in which hook name the message names. Centralized
+// here so a wording change lands once instead of five times.
+export function requireNavigationScope(hookName: string): ShallowRef<INavigationScopeValue> {
+  const scope = injectNavigationScope();
+  if (scope === undefined) {
+    throw new Error(
+      `${hookName} must be used within a screen rendered by <Stack>, <Tab>, or <Drawer>`,
+    );
+  }
+  return scope;
+}
+
+// The setup-boundary component described above. `props: ['value']` is a REQUIRED runtime
+// declaration here, not stylistic - without it Vue would route the incoming `value` into `attrs`
+// instead of a tracked reactive `props` field, and the render closure's refresh below would
+// silently keep re-reading a stale initial snapshot.
+export const NavigationScope = defineComponent<{ value: INavigationScopeValue }>(
+  (props, { slots }) => {
+    const current = shallowRef(props.value);
+    provideNavigationScope(current);
+    return () => {
+      current.value = props.value;
+      return slots.default?.() ?? null;
+    };
+  },
+  { name: 'NavigationScope', props: ['value'] },
+);

package/src/vue/nested-navigation.test.ts

@@ -0,0 +1,155 @@
+// Co-located Vue-driven test, the Vue twin of react/nested-navigation.test.tsx. Proves the
+// scope "parent" chain: a navigator reads the ambient scope BEFORE establishing its own, so when
+// one navigator's screen renders ANOTHER navigator (here, a Stack screen renders a Tab), a screen
+// deep inside the nested Tab can call useNavigation().getParent() to reach the enclosing Stack's
+// handle. Mirrors stack.test.ts's fixture (an injected codegen-shaped RNSScreen ViewConfig) since
+// a real Stack is part of this composition; Tab needs no ViewConfig of its own (tabs.test.ts).
+
+import { defineComponent, h, ref } from '@vue/runtime-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mount, unmount, setNativeViewConfigSource } from '@symbiote-native/vue';
+import type { INativeViewConfig } from '@symbiote-native/engine';
+import { installFabric, type IFakeNode } from '@symbiote-native/test-utils';
+import { Stack } from './stack';
+import type { INavigatorHandle } from './stack';
+import { Tab } from './tabs';
+import { useNavigation } from './composables';
+import type { IAnyNavigatorHandle } from './navigation-context';
+
+const ROOT_TAG = 4768;
+const SCREEN_VIEW = 'RNSScreen';
+const STACK_VIEW = 'RNSScreenStack';
+const HEADER_CONFIG_VIEW = 'RNSScreenStackHeaderConfig';
+
+function directEvent(registrationName: string) {
+  return { registrationName };
+}
+
+const VIEW_CONFIGS: Record<string, INativeViewConfig> = {
+  [SCREEN_VIEW]: {
+    directEventTypes: {
+      topAppear: directEvent('onAppear'),
+      topDisappear: directEvent('onDisappear'),
+      topWillAppear: directEvent('onWillAppear'),
+      topWillDisappear: directEvent('onWillDisappear'),
+      topDismissed: directEvent('onDismissed'),
+      topHeaderBackButtonClicked: directEvent('onHeaderBackButtonClicked'),
+    },
+    validAttributes: {
+      screenId: true,
+      activityState: true,
+      gestureEnabled: true,
+      stackAnimation: true,
+      stackPresentation: true,
+      transitionDuration: true,
+    },
+  },
+  [STACK_VIEW]: {
+    directEventTypes: { topFinishTransitioning: directEvent('onFinishTransitioning') },
+    validAttributes: {},
+  },
+  [HEADER_CONFIG_VIEW]: {
+    directEventTypes: { topPressHeaderBarButtonItem: directEvent('onPressHeaderBarButtonItem') },
+    validAttributes: { title: true, hidden: true, backTitle: true, backTitleVisible: true },
+  },
+};
+
+const fabric = installFabric();
+setNativeViewConfigSource(name => VIEW_CONFIGS[name]);
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+beforeEach(() => fabric.reset());
+afterEach(() => unmount(ROOT_TAG));
+
+function findAllText(nodes: readonly IFakeNode[]): string[] {
+  const found: string[] = [];
+  const collect = (list: readonly IFakeNode[]): void => {
+    for (const node of list) {
+      if (node.viewName === 'RCTRawText' && typeof node.props.text === 'string') {
+        found.push(node.props.text);
+      }
+      collect(node.children);
+    }
+  };
+  collect(nodes);
+  return found;
+}
+
+function StackDetailsScreen() {
+  return h('symbiote-text', {}, 'stack-details');
+}
+
+describe('nested navigators (scope parent chain)', () => {
+  it("a root Stack screen's useNavigation().getParent() is undefined (no ambient navigator above it)", async () => {
+    let capturedParent: IAnyNavigatorHandle | undefined;
+    let getParentCalled = false;
+    // Plain functions used as `component:` are stateless functional components - Vue calls them
+    // fresh on every render and treats their return value as vnodes directly, NOT as a "setup
+    // returns a render fn" component. A screen calling a composable needs a real setup-based
+    // component, hence defineComponent here instead of a bare function.
+    const RootScreen = defineComponent(() => {
+      const navigation = useNavigation();
+      capturedParent = navigation.value.getParent();
+      getParentCalled = true;
+      return () => h('symbiote-text', {}, 'root');
+    });
+
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Stack, { initialRouteName: 'Root' }, () => [
+            h(Stack.Screen, { name: 'Root', component: RootScreen }),
+          ]),
+      }),
+    );
+    await tick();
+
+    expect(getParentCalled).toBe(true);
+    expect(capturedParent).toBeUndefined();
+  });
+
+  it('useNavigation().getParent() from inside a Tab screen nested in a Stack screen reaches the enclosing Stack, and pushing through it adds a Stack route', async () => {
+    let capturedParent: IAnyNavigatorHandle | undefined;
+
+    const NestedTabHomeScreen = defineComponent(() => {
+      const navigation = useNavigation();
+      capturedParent = navigation.value.getParent();
+      return () => h('symbiote-text', {}, 'tab-home');
+    });
+
+    // The Stack screen's own component: a Tab navigator, nested exactly the way a real app
+    // composes navigators (a Stack screen's content IS another navigator). No composable of its
+    // own, so a plain function (returning vnodes directly) is fine here.
+    function RootScreenRendersTab() {
+      return h(Tab, { initialRouteName: 'TabHome' }, () => [
+        h(Tab.Screen, { name: 'TabHome', component: NestedTabHomeScreen }),
+      ]);
+    }
+
+    const handleRef = ref<INavigatorHandle | null>(null);
+    mount(
+      ROOT_TAG,
+      defineComponent({
+        setup: () => () =>
+          h(Stack, { ref: handleRef, initialRouteName: 'Root' }, () => [
+            h(Stack.Screen, { name: 'Root', component: RootScreenRendersTab }),
+            h(Stack.Screen, { name: 'Details', component: StackDetailsScreen }),
+          ]),
+      }),
+    );
+    await tick();
+
+    expect(findAllText(fabric.committed)).toContain('tab-home');
+
+    if (!capturedParent) throw new Error('getParent() returned undefined');
+    if (!('push' in capturedParent)) {
+      throw new Error('parent handle is not a Stack handle (missing push)');
+    }
+    capturedParent.push('Details');
+    await tick();
+
+    expect(findAllText(fabric.committed)).toContain('stack-details');
+    expect(handleRef.value?.canGoBack()).toBe(true);
+  });
+});

package/src/vue/screen.ts

@@ -0,0 +1,52 @@
+// Stack.Screen: a declarative marker, never rendered on its own - Stack reads its props via a
+// default-slot scan (see stack.ts's collectRegistry) to build the static name -> {component,
+// options} registry, then mounts the registered component itself for each pushed route. The Vue
+// twin of react/screen.ts's Screen, using the slot-scanning pattern real Vue component libraries
+// use for this exact declarative-marker-child shape (Element Plus's `<el-collapse-item>`, Ant
+// Design Vue's `<a-menu-item>`): the parent inspects `vnode.type === Screen` and reads
+// `vnode.props` directly, so Screen's own setup() never actually runs.
+
+import { defineComponent } from '@vue/runtime-core';
+import type { Component, Ref } from '@vue/runtime-core';
+import type { IRoute } from '../core';
+import type {
+  ISearchBarCommands,
+  ISearchBarOptions,
+  IScreenOptions,
+  INavigatorHandle,
+} from '../core';
+
+// The imperative ref (focus/blur/clearText/setText/cancelSearch/toggleCancelButton) carries a Vue
+// ref type, so per CLAUDE.md's <prop_types_split_agnostic_vs_per_adapter> it cannot live in
+// the shared, agnostic ISearchBarOptions (core/navigator-props.ts). This adapter-only overlay adds
+// it on top of the agnostic field base, the Vue twin of react/screen.ts's IReactSearchBarOptions
+// (a plain `Ref<T | null>` here instead of React's `RefObject<T | null>`).
+export type IVueSearchBarOptions = ISearchBarOptions & {
+  ref?: Ref<ISearchBarCommands | null>;
+};
+
+export type IVueScreenOptions = Omit<IScreenOptions, 'headerSearchBarOptions'> & {
+  headerSearchBarOptions?: IVueSearchBarOptions;
+};
+
+// The options resolver runs OUTSIDE render (during the options fold), so it still receives the
+// route + navigator handle explicitly - screens read those through composables, but a resolver has
+// no component scope to inject from.
+export type IScreenOptionsArgs = {
+  route: IRoute<unknown>;
+  navigation: INavigatorHandle;
+};
+
+export type IScreenOptionsResolver = (args: IScreenOptionsArgs) => IVueScreenOptions;
+
+export type IScreenProps = {
+  name: string;
+  component: Component;
+  options?: IVueScreenOptions | IScreenOptionsResolver;
+  initialParams?: unknown;
+};
+
+export const Screen = defineComponent<IScreenProps>(() => () => null, {
+  name: 'Screen',
+  inheritAttrs: false,
+});