@symbiote-native/navigation 1.0.0

package/src/core/linking-config/linking-config.test.ts

@@ -0,0 +1,109 @@
+// Co-located unit test (ADR 0025) for the pure linking-config resolver: URL->route and
+// route->URL, over a flat route and a ':param' route, plus the nested-config flattening and the
+// prefix-vs-bare-path forms called out in the task ('myapp://user/42' and '/user/42').
+
+import { describe, expect, it } from 'vitest';
+import { resolveRouteFromUrl, resolveUrlFromRoute } from './index';
+import type { ILinkingConfig } from './index';
+import type { IRoute } from '../navigator-state';
+
+const CONFIG: ILinkingConfig = {
+  prefixes: ['myapp://', 'https://example.com'],
+  config: {
+    screens: {
+      Home: '',
+      User: 'user/:id',
+      Settings: {
+        path: 'settings',
+        screens: {
+          Profile: 'profile',
+        },
+      },
+    },
+  },
+};
+
+describe('resolveRouteFromUrl', () => {
+  it('resolves a flat route with no params, scheme prefix', () => {
+    expect(resolveRouteFromUrl(CONFIG, 'myapp://')).toEqual({
+      key: 'Home',
+      name: 'Home',
+      params: undefined,
+    });
+  });
+
+  it('resolves a :param route through a scheme prefix', () => {
+    expect(resolveRouteFromUrl(CONFIG, 'myapp://user/42')).toEqual({
+      key: 'User',
+      name: 'User',
+      params: { id: '42' },
+    });
+  });
+
+  it('resolves the same :param route through a bare path (no configured prefix match)', () => {
+    expect(resolveRouteFromUrl(CONFIG, '/user/42')).toEqual({
+      key: 'User',
+      name: 'User',
+      params: { id: '42' },
+    });
+  });
+
+  it('resolves a :param route through an https prefix', () => {
+    expect(resolveRouteFromUrl(CONFIG, 'https://example.com/user/7')).toEqual({
+      key: 'User',
+      name: 'User',
+      params: { id: '7' },
+    });
+  });
+
+  it('resolves a nested screen to its leaf name, path accumulated from the group', () => {
+    expect(resolveRouteFromUrl(CONFIG, 'myapp://settings/profile')).toEqual({
+      key: 'Profile',
+      name: 'Profile',
+      params: undefined,
+    });
+  });
+
+  it('decodes a percent-encoded param segment', () => {
+    expect(resolveRouteFromUrl(CONFIG, 'myapp://user/john%20doe')).toEqual({
+      key: 'User',
+      name: 'User',
+      params: { id: 'john doe' },
+    });
+  });
+
+  it('returns null for a url matching no configured screen', () => {
+    expect(resolveRouteFromUrl(CONFIG, 'myapp://nowhere')).toBeNull();
+  });
+
+  it('returns null for a url matching no configured prefix and no leading slash', () => {
+    expect(resolveRouteFromUrl(CONFIG, 'otherapp://user/42')).toBeNull();
+  });
+});
+
+describe('resolveUrlFromRoute', () => {
+  it('builds a url for a flat route with no params', () => {
+    const route: IRoute<unknown> = { key: 'k', name: 'Home', params: undefined };
+    expect(resolveUrlFromRoute(CONFIG, route)).toBe('myapp://');
+  });
+
+  it('builds a url for a :param route', () => {
+    const route: IRoute<unknown> = { key: 'k', name: 'User', params: { id: '42' } };
+    expect(resolveUrlFromRoute(CONFIG, route)).toBe('myapp://user/42');
+  });
+
+  it('builds a url for a nested screen using its accumulated path', () => {
+    const route: IRoute<unknown> = { key: 'k', name: 'Profile', params: undefined };
+    expect(resolveUrlFromRoute(CONFIG, route)).toBe('myapp://settings/profile');
+  });
+
+  it('returns null when a required param is missing', () => {
+    const route: IRoute<unknown> = { key: 'k', name: 'User', params: {} };
+    expect(resolveUrlFromRoute(CONFIG, route)).toBeNull();
+  });
+
+  it('returns null for an unconfigured route name', () => {
+    const route: IRoute<unknown> = { key: 'k', name: 'Nowhere', params: undefined };
+    expect(resolveUrlFromRoute(CONFIG, route)).toBeNull();
+  });
+});

package/src/core/navigation-events/index.ts

@@ -0,0 +1,94 @@
+// The framework-agnostic half of what @react-navigation exposes as `navigation.addListener` /
+// `useFocusEffect` / `useIsFocused` / `useNavigationState`: a plain pub/sub emitter, zero React.
+// addListener is NOT React-specific there either - React's hooks are thin useEffect wrappers
+// around exactly this subscribe/unsubscribe shape (confirmed against the 8.x docs: `const
+// unsubscribe = navigation.addListener('focus', cb); return unsubscribe;` inside a bare
+// `useEffect`). One emitter per route (created by the adapter, e.g. stack.ts's per-route
+// `emitters` map) carries that route's own focus/blur/state lifecycle; every adapter's lifecycle
+// hooks subscribe to it, matching this file's single responsibility split from `constants.ts`
+// (which only names Fabric view/prop-key strings, not this JS-only event system).
+//
+// diffFocusedRoute below centralizes the "which route lost focus, which gained it" comparison
+// that tabs.ts and drawer.ts independently reimplemented in all three adapters (each watching its
+// own router state for the focused index/key changing, then manually emitting BLUR to the old key
+// and FOCUS to the new one, plus an initial FOCUS seed on first mount) - the diff is pure and
+// identical everywhere; only WHEN to run it differs per framework (a `useEffect` dependency array,
+// a Vue `watch`, an idempotent-per-read Angular method), so that half stays adapter-owned.
+
+import { dlog } from '@symbiote-native/engine';
+
+export const NAVIGATION_EVENT_FOCUS = 'focus';
+export const NAVIGATION_EVENT_BLUR = 'blur';
+export const NAVIGATION_EVENT_STATE = 'state';
+export const NAVIGATION_EVENT_BEFORE_REMOVE = 'beforeRemove';
+
+export type INavigationEventName =
+  | typeof NAVIGATION_EVENT_FOCUS
+  | typeof NAVIGATION_EVENT_BLUR
+  | typeof NAVIGATION_EVENT_STATE
+  | typeof NAVIGATION_EVENT_BEFORE_REMOVE;
+
+export type INavigationEventListener<TData = unknown> = (data: TData) => void;
+
+export type INavigationEmitter = {
+  emit: (event: INavigationEventName, data?: unknown) => void;
+  addListener: (event: INavigationEventName, listener: INavigationEventListener) => () => void;
+};
+
+export function createNavigationEmitter(): INavigationEmitter {
+  const listenersByEvent = new Map<INavigationEventName, Set<INavigationEventListener>>();
+
+  function addListener(
+    event: INavigationEventName,
+    listener: INavigationEventListener,
+  ): () => void {
+    let listeners = listenersByEvent.get(event);
+    if (!listeners) {
+      listeners = new Set();
+      listenersByEvent.set(event, listeners);
+    }
+    listeners.add(listener);
+
+    return () => {
+      listeners?.delete(listener);
+    };
+  }
+
+  function emit(event: INavigationEventName, data?: unknown): void {
+    const listeners = listenersByEvent.get(event);
+    // Investigation instrumentation (flicker-on-focus bug): every emission, whether or not a
+    // listener is attached, so the log stream shows if focus/blur ever fires with 0 subscribers
+    // (a silent no-op) vs racing an actual effect. Kept behind DEBUG, never removed.
+    dlog(
+      `Navigation emitter: emit "${event}" (${listeners?.size ?? 0} listener(s)) at t=${Date.now()}`,
+    );
+    if (!listeners) return;
+    for (const listener of listeners) listener(data);
+  }
+
+  return { emit, addListener };
+}
+
+// The keys, if any, that should be blurred/focused when the focused route's key changes from
+// `prevKey` to `nextKey` - a pure comparison, no emitter, no timing. Covers all three shapes every
+// adapter's lifecycle trigger needs: first mount (`prevKey` undefined -> `focusKey` only, no
+// blur), unmount/no-longer-focused (`nextKey` undefined -> `blurKey` only), an ordinary focus
+// change (both), and a no-op re-run with the same key (neither field set, e.g. a setParams-only
+// change that leaves the focused key untouched). The caller looks up (or lazily creates) each
+// key's own emitter and calls `.emit(NAVIGATION_EVENT_BLUR)` / `.emit(NAVIGATION_EVENT_FOCUS)` -
+// this function only decides WHICH keys, never WHEN or on WHICH emitter.
+export type IFocusTransition = {
+  blurKey?: string;
+  focusKey?: string;
+};
+
+export function diffFocusedRoute(
+  prevKey: string | undefined,
+  nextKey: string | undefined,
+): IFocusTransition {
+  if (prevKey === nextKey) return {};
+  const transition: IFocusTransition = {};
+  if (prevKey !== undefined) transition.blurKey = prevKey;
+  if (nextKey !== undefined) transition.focusKey = nextKey;
+  return transition;
+}

package/src/core/navigation-events/navigation-events.test.ts

@@ -0,0 +1,56 @@
+// Pure unit coverage for the framework-agnostic pub/sub emitter - zero React, so no fabric/mount
+// scaffolding needed (mirrors navigator-state.test.ts's plain reducer coverage, once that lands).
+
+import { describe, expect, it, vi } from 'vitest';
+import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS, createNavigationEmitter } from './index';
+
+describe('createNavigationEmitter', () => {
+  it('calls a listener registered for the emitted event', () => {
+    const emitter = createNavigationEmitter();
+    const listener = vi.fn();
+    emitter.addListener(NAVIGATION_EVENT_FOCUS, listener);
+
+    emitter.emit(NAVIGATION_EVENT_FOCUS, { some: 'payload' });
+
+    expect(listener).toHaveBeenCalledWith({ some: 'payload' });
+  });
+
+  it('does not call a listener registered for a different event', () => {
+    const emitter = createNavigationEmitter();
+    const listener = vi.fn();
+    emitter.addListener(NAVIGATION_EVENT_BLUR, listener);
+
+    emitter.emit(NAVIGATION_EVENT_FOCUS);
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('supports multiple listeners on the same event', () => {
+    const emitter = createNavigationEmitter();
+    const first = vi.fn();
+    const second = vi.fn();
+    emitter.addListener(NAVIGATION_EVENT_FOCUS, first);
+    emitter.addListener(NAVIGATION_EVENT_FOCUS, second);
+
+    emitter.emit(NAVIGATION_EVENT_FOCUS);
+
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops calling a listener after its unsubscribe is invoked', () => {
+    const emitter = createNavigationEmitter();
+    const listener = vi.fn();
+    const unsubscribe = emitter.addListener(NAVIGATION_EVENT_FOCUS, listener);
+
+    unsubscribe();
+    emitter.emit(NAVIGATION_EVENT_FOCUS);
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('emitting an event with no listeners is a no-op', () => {
+    const emitter = createNavigationEmitter();
+    expect(() => emitter.emit(NAVIGATION_EVENT_FOCUS)).not.toThrow();
+  });
+});

package/src/core/navigator-handles/index.ts

@@ -0,0 +1,63 @@
+// Imperative navigator handles: framework-agnostic (scalars, `unknown`, plain function
+// signatures over `INavigatorState`/`IDrawerScreenOptions` - no framework element, ref, or
+// children in any field), so each shape is declared once here and every adapter re-exports it
+// verbatim (see CLAUDE.md <prop_types_split_agnostic_vs_per_adapter>).
+
+import type { INavigatorState } from '../navigator-state';
+import type { IDrawerScreenOptions } from '../drawer-options';
+
+export type INavigatorHandle = {
+  push: (name: string, params?: unknown) => void;
+  pop: (count?: number) => void;
+  popToTop: () => void;
+  popTo: (key: string) => void;
+  replace: (name: string, params?: unknown) => void;
+  setParams: (params: unknown, key?: string) => void;
+  reset: (state: INavigatorState) => void;
+  canGoBack: () => boolean;
+};
+
+export type ITabNavigatorHandle = {
+  jumpTo: (name: string, params?: unknown) => void;
+  // (params, key) - same order as INavigatorHandle.setParams; key stays required (unlike Stack's
+  // optional key, which defaults to the focused route) since a tab must always be identified
+  // explicitly.
+  setParams: (params: unknown, key: string) => void;
+};
+
+export type IDrawerNavigatorHandle = {
+  openDrawer: () => void;
+  closeDrawer: () => void;
+  toggleDrawer: () => void;
+  jumpTo: (name: string) => void;
+};
+
+// Keyed by route.key, mirroring @react-navigation/drawer's own `descriptors` prop shape - the
+// options a caller's renderDrawerContent/drawerContent reads to label its menu entries (Drawer
+// ships no built-in menu UI, matching react-native-drawer-layout's Drawer primitive).
+export type IDrawerDescriptorMap = Record<
+  string,
+  { options: IDrawerScreenOptions; navigation: IDrawerNavigatorHandle }
+>;
+
+// Every navigator kind a screen might be rendered under. useNavigation()/injectNavigation()
+// return this union since they don't know which navigator mounted the calling component; the
+// three guards below narrow it (used once, inside useStackNavigation/useTabNavigation/
+// useDrawerNavigation and their Vue/Angular equivalents) so app code never writes the guard itself.
+export type IAnyNavigatorHandle = INavigatorHandle | ITabNavigatorHandle | IDrawerNavigatorHandle;
+
+export function isStackNavigatorHandle(handle: IAnyNavigatorHandle): handle is INavigatorHandle {
+  return 'push' in handle;
+}
+
+export function isDrawerNavigatorHandle(
+  handle: IAnyNavigatorHandle,
+): handle is IDrawerNavigatorHandle {
+  return 'openDrawer' in handle;
+}
+
+// jumpTo exists on both Tab and Drawer handles, so a Tab handle is a jumpTo-having handle that
+// isn't a Drawer handle (Drawer's own openDrawer/closeDrawer/toggleDrawer rule it out).
+export function isTabNavigatorHandle(handle: IAnyNavigatorHandle): handle is ITabNavigatorHandle {
+  return 'jumpTo' in handle && !isDrawerNavigatorHandle(handle);
+}

package/src/core/navigator-handles/navigator-handles.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { isDrawerNavigatorHandle, isStackNavigatorHandle, isTabNavigatorHandle } from './index';
+import type { IDrawerNavigatorHandle, INavigatorHandle, ITabNavigatorHandle } from './index';
+
+const stackHandle: INavigatorHandle = {
+  push: () => {},
+  pop: () => {},
+  popToTop: () => {},
+  popTo: () => {},
+  replace: () => {},
+  setParams: () => {},
+  reset: () => {},
+  canGoBack: () => false,
+};
+
+const tabHandle: ITabNavigatorHandle = {
+  jumpTo: () => {},
+  setParams: () => {},
+};
+
+const drawerHandle: IDrawerNavigatorHandle = {
+  openDrawer: () => {},
+  closeDrawer: () => {},
+  toggleDrawer: () => {},
+  jumpTo: () => {},
+};
+
+describe('navigator handle guards', () => {
+  it('identifies a Stack handle by push and rules out Tab/Drawer', () => {
+    expect(isStackNavigatorHandle(stackHandle)).toBe(true);
+    expect(isTabNavigatorHandle(stackHandle)).toBe(false);
+    expect(isDrawerNavigatorHandle(stackHandle)).toBe(false);
+  });
+
+  it('identifies a Tab handle by jumpTo without openDrawer', () => {
+    expect(isTabNavigatorHandle(tabHandle)).toBe(true);
+    expect(isStackNavigatorHandle(tabHandle)).toBe(false);
+    expect(isDrawerNavigatorHandle(tabHandle)).toBe(false);
+  });
+
+  it('identifies a Drawer handle by openDrawer, even though it also has jumpTo', () => {
+    expect(isDrawerNavigatorHandle(drawerHandle)).toBe(true);
+    expect(isTabNavigatorHandle(drawerHandle)).toBe(false);
+    expect(isStackNavigatorHandle(drawerHandle)).toBe(false);
+  });
+});