@symbiote-native/navigation 1.0.0

package/src/angular/linking.ts

@@ -0,0 +1,55 @@
+// injectLinkingIntegration: 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 (call this from the component hosting `<Stack #nav>`,
+// passing `nav` itself, since Stack now implements INavigatorHandle directly), the same
+// top-level-prop shape @react-navigation keeps `linking` in on NavigationContainer rather than
+// baking it into the router itself. Mirrors react/linking.ts's useLinkingIntegration; Angular
+// needs none of its `configRef`/`handleRef` staleness workaround - this function runs its
+// subscription ONCE per call (the natural `inject()` call-site convention), and Stack's methods
+// already read live `this` state off the component instance, so there is no stale-closure risk to
+// guard against here.
+
+import { DestroyRef, inject } from '@angular/core';
+import { Linking, dlog } from '@symbiote-native/engine';
+import type { IUrlEvent } from '@symbiote-native/engine';
+import { resolveRouteFromUrl } from '../core';
+import type { ILinkingConfig } from '../core';
+import type { INavigatorHandle } from './stack';
+
+export function injectLinkingIntegration(
+  config: ILinkingConfig,
+  navigatorHandle: INavigatorHandle,
+): void {
+  const destroyRef = inject(DestroyRef);
+
+  function applyRoute(url: string, dispatch: (name: string, params?: unknown) => void): void {
+    const route = resolveRouteFromUrl(config, url);
+    if (route === null) {
+      dlog(`injectLinkingIntegration: no route resolved for "${url}"`);
+      return;
+    }
+    dispatch(route.name, route.params);
+  }
+
+  let cancelled = false;
+
+  Linking.getInitialURL()
+    .then(url => {
+      if (cancelled || url === null) return;
+      dlog(`injectLinkingIntegration: initial URL "${url}"`);
+      applyRoute(url, navigatorHandle.replace);
+    })
+    .catch((error: unknown) => {
+      dlog(`injectLinkingIntegration: getInitialURL failed: ${String(error)}`);
+    });
+
+  const subscription = Linking.addEventListener('url', (event: IUrlEvent) => {
+    dlog(`injectLinkingIntegration: url event "${event.url}"`);
+    applyRoute(event.url, navigatorHandle.push);
+  });
+
+  destroyRef.onDestroy(() => {
+    cancelled = true;
+    subscription.remove();
+  });
+}

package/src/angular/navigation-context.service.ts

@@ -0,0 +1,68 @@
+// The lifecycle half of the framework-agnostic emitter (../core/navigation-events), Angular's
+// twin of react/navigation-context.ts's NavigationContext. React re-scopes a plain Context per
+// screen via NavigationContext.Provider; Angular's equivalent of "nearest-provider lookup" is
+// hierarchical DI - NavigationScopeDirective (./navigation-scope.directive) re-`providers: [...]`
+// a fresh NavigationContextService instance per route, and this service's own constructor injects
+// its PARENT instance (`@Optional() @SkipSelf()`), which Angular resolves to the nearest ANCESTOR
+// provider automatically - the exact `parent` linked list react/navigation-context.ts builds by
+// hand via `ambientContext`. A screen nested inside e.g. a Stack-screen-renders-a-Tab composition
+// reaches the enclosing Stack the same way a React screen does: one hop up `parent`.
+//
+// Every navigator kind a screen might be rendered under; consumers narrow the union themselves
+// ('push' in handle picks out a Stack handle) - mirrors react/navigation-context.ts's
+// IAnyNavigatorHandle exactly, minus the React-specific import cycle avoidance (Angular's `inject`
+// resolves this service by TOKEN, so no circular value import exists here at all - only the
+// type-only imports below, erased at compile time).
+
+import { Injectable, inject, signal, type Signal } from '@angular/core';
+import type { INavigationEmitter, IRoute, IAnyNavigatorHandle } from '../core';
+
+export type { IAnyNavigatorHandle } from '../core';
+
+// NOT `providedIn: 'root'` - deliberately component-scoped (see CLAUDE.md's design note for this
+// package): every NavigationScopeDirective usage re-provides this token, so DI naturally mints one
+// instance per route/screen, exactly like a fresh React Context value per screen.
+@Injectable()
+export class NavigationContextService {
+  private readonly ambientParent = inject(NavigationContextService, {
+    optional: true,
+    skipSelf: true,
+  });
+
+  // `route` is the one field that legitimately changes over a mounted screen's lifetime (a
+  // setParams call swaps in a new route OBJECT with the same key/name) while the screen itself
+  // stays mounted - a plain field would go stale the moment a consumer reads it once (e.g. in a
+  // constructor, the natural `inject()` call site). A signal lets `injectRoute()`
+  // (./injectors/inject-route) hand back a live, reactive value with zero per-consumer
+  // subscription plumbing, matching this
+  // package's zoneless/signals-first convention. `navigation`/`emitter` are stable for a screen's
+  // whole lifetime, so they stay plain fields - no reactivity needed there.
+  private readonly routeSignal = signal<IRoute<unknown> | undefined>(undefined);
+  readonly route: Signal<IRoute<unknown> | undefined> = this.routeSignal.asReadonly();
+
+  navigation!: IAnyNavigatorHandle;
+  emitter!: INavigationEmitter;
+
+  get parent(): NavigationContextService | undefined {
+    return this.ambientParent ?? undefined;
+  }
+
+  setRoute(route: IRoute<unknown>): void {
+    this.routeSignal.set(route);
+  }
+}
+
+// Every injectX function (./injectors/*) opens with the same optional-inject-then-throw guard;
+// this centralizes it so the "must be used within a screen rendered by..." message stays
+// identical everywhere instead of six independently-typed copies. Must be called from an
+// injection context, same requirement `inject()` itself has - every call site is the first line
+// of an injectX function, which callers already only invoke from their own injection context.
+export function requireNavigationContext(injectorName: string): NavigationContextService {
+  const context = inject(NavigationContextService, { optional: true });
+  if (!context) {
+    throw new Error(
+      `${injectorName} must be used within a screen rendered by <Stack>, <Tab>, or <Drawer>`,
+    );
+  }
+  return context;
+}

package/src/angular/navigation-scope.directive.ts

@@ -0,0 +1,31 @@
+// The Angular twin of react/navigation-context.ts's `NavigationContext.Provider` usage in
+// stack.ts/tabs.ts/drawer.ts's render loops: one directive instance = one fresh scope. Applying
+// `[symbioteNavigationScope]` to an element re-`providers: [NavigationContextService]`
+// (component/directive-level DI), so every usage mints its OWN service instance - the DI twin of
+// `createElement(NavigationContext.Provider, { value }, content)`. Descendants (a screen's own
+// component tree, reached through `*ngComponentOutlet`) call `inject(NavigationContextService)`
+// and resolve to the NEAREST enclosing instance, exactly like `useContext(NavigationContext)`
+// walks to the nearest Provider.
+
+import { Directive, Input, inject, type OnChanges } from '@angular/core';
+import type { INavigationEmitter, IRoute } from '../core';
+import { NavigationContextService, type IAnyNavigatorHandle } from './navigation-context.service';
+
+@Directive({
+  selector: '[symbioteNavigationScope]',
+  standalone: true,
+  providers: [NavigationContextService],
+})
+export class NavigationScopeDirective implements OnChanges {
+  @Input({ required: true, alias: 'symbioteNavigationScope' }) route!: IRoute<unknown>;
+  @Input({ required: true }) navigation!: IAnyNavigatorHandle;
+  @Input({ required: true }) emitter!: INavigationEmitter;
+
+  private readonly context = inject(NavigationContextService);
+
+  ngOnChanges(): void {
+    this.context.setRoute(this.route);
+    this.context.navigation = this.navigation;
+    this.context.emitter = this.emitter;
+  }
+}

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

@@ -0,0 +1,189 @@
+// Co-located Angular-driven test proving the DI "parent" chain: NavigationContextService reads
+// the ambient (parent-scope) instance via `@Optional() @SkipSelf() inject(...)` in its own
+// constructor (navigation-context.service.ts) BEFORE NavigationScopeDirective re-provides a fresh
+// one for its own content, 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 injectNavigation().getParent()
+// to reach the enclosing Stack's handle - with ZERO manual threading (unlike react/
+// nested-navigation.test.tsx, which needs an explicit `ambientContext` read + re-provide in every
+// navigator; Angular's own hierarchical DI does this automatically, see navigation-context.
+// service.ts's header comment). Mirrors stack.test.ts's fixture since a real Stack is part of
+// this composition; Tab needs no ViewConfig of its own.
+
+import '@angular/compiler';
+import { Component, CUSTOM_ELEMENTS_SCHEMA, Input, ViewChild, type Type } from '@angular/core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mount, unmount, setNativeViewConfigSource } from '@symbiote-native/angular';
+import type { INativeViewConfig } from '@symbiote-native/engine';
+import { installFabric, type IFakeNode } from '@symbiote-native/test-utils';
+import { Stack } from './stack';
+import { ScreenDirective } from './screen.directive';
+import { Tab } from './tabs';
+import { TabScreenDirective } from './tab-screen.directive';
+import { injectNavigation } from './injectors';
+import type { IAnyNavigatorHandle } from './navigation-context.service';
+
+const ROOT_TAG = 5140;
+const SCREEN_VIEW = 'RNSScreen';
+const STACK_VIEW = 'RNSScreenStack';
+const HEADER_CONFIG_VIEW = 'RNSScreenStackHeaderConfig';
+
+function directEvent(registrationName: string): { registrationName: string } {
+  return { registrationName };
+}
+
+const VIEW_CONFIGS: Record<string, INativeViewConfig> = {
+  [SCREEN_VIEW]: {
+    directEventTypes: {
+      topAppear: directEvent('onAppear'),
+      topDisappear: directEvent('onDisappear'),
+    },
+    validAttributes: { screenId: true, activityState: true },
+  },
+  [STACK_VIEW]: { directEventTypes: {}, validAttributes: {} },
+  [HEADER_CONFIG_VIEW]: { directEventTypes: {}, validAttributes: {} },
+};
+
+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;
+}
+
+@Component({
+  selector: 'root-plain-screen',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<symbiote-text>root</symbiote-text>`,
+})
+class RootPlainScreenComponent {}
+
+@Component({
+  selector: 'stack-details-screen',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<symbiote-text>stack-details</symbiote-text>`,
+})
+class StackDetailsScreenComponent {}
+
+let capturedParent: IAnyNavigatorHandle | undefined;
+let getParentCalled = false;
+
+@Component({
+  selector: 'root-getparent-screen',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<symbiote-text>root</symbiote-text>`,
+})
+class RootGetParentScreenComponent {
+  constructor() {
+    capturedParent = injectNavigation().getParent();
+    getParentCalled = true;
+  }
+}
+
+@Component({
+  selector: 'nested-tab-home-screen',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<symbiote-text>tab-home</symbiote-text>`,
+})
+class NestedTabHomeScreenComponent {
+  constructor() {
+    capturedParent = injectNavigation().getParent();
+  }
+}
+
+// The Stack screen's own content: a Tab navigator, nested exactly the way a real app composes
+// navigators (a Stack screen's content IS another navigator). Angular's DI naturally threads the
+// `parent` chain - this component does NOT need to read or forward any ambient context itself.
+@Component({
+  selector: 'root-renders-tab-screen',
+  standalone: true,
+  imports: [Tab, TabScreenDirective],
+  template: `
+    <Tab initialRouteName="TabHome">
+      <ng-template symbioteTabScreen name="TabHome" [component]="tabHomeComponent"></ng-template>
+    </Tab>
+  `,
+})
+class RootRendersTabScreenComponent {
+  tabHomeComponent = NestedTabHomeScreenComponent;
+}
+
+let capturedHost: NestedTestHost | undefined;
+
+@Component({
+  selector: 'nested-test-host',
+  standalone: true,
+  imports: [Stack, ScreenDirective],
+  template: `
+    <Stack #nav initialRouteName="Root">
+      <ng-template symbioteScreen name="Root" [component]="rootComponent"></ng-template>
+      <ng-template symbioteScreen name="Details" [component]="detailsComponent"></ng-template>
+    </Stack>
+  `,
+})
+class NestedTestHost {
+  @ViewChild('nav') nav!: Stack;
+
+  @Input() rootComponent: Type<unknown> = RootPlainScreenComponent;
+  detailsComponent = StackDetailsScreenComponent;
+
+  constructor() {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    capturedHost = this;
+  }
+}
+
+describe('Angular nested navigators (DI parent chain)', () => {
+  it("a root Stack screen's injectNavigation().getParent() is undefined (no ambient navigator above it)", async () => {
+    capturedParent = undefined;
+    getParentCalled = false;
+    capturedHost = undefined;
+    mount(ROOT_TAG, NestedTestHost, {
+      initialProps: { rootComponent: RootGetParentScreenComponent },
+    });
+    await tick();
+
+    expect(getParentCalled).toBe(true);
+    expect(capturedParent).toBeUndefined();
+  });
+
+  it('injectNavigation().getParent() from inside a Tab screen nested in a Stack screen reaches the enclosing Stack, and pushing through it adds a Stack route', async () => {
+    capturedParent = undefined;
+    capturedHost = undefined;
+    mount(ROOT_TAG, NestedTestHost, {
+      initialProps: { rootComponent: RootRendersTabScreenComponent },
+    });
+    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 is now narrowed to INavigatorHandle by the 'push in' guard above.
+    capturedParent.push('Details');
+    await tick();
+
+    expect(findAllText(fabric.committed)).toContain('stack-details');
+    expect(capturedHost!.nav.canGoBack()).toBe(true);
+  });
+});

package/src/angular/screen.directive.ts

@@ -0,0 +1,48 @@
+// [symbioteScreen]: a declarative marker, never rendered on its own - Stack reads its inputs via
+// @ContentChildren to build the static name -> {component, options} registry, then mounts the
+// registered component itself for each pushed route. Angular's twin of react/screen.ts's Screen
+// marker component; mirrors Angular Material's own `@ContentChildren(MatTab) tabs: QueryList<MatTab>`
+// pattern (a directive applied to an inert `<ng-template>`, never instantiated as a view - see
+// stack.ts's header for why that's safe: @ContentChildren resolves the light-DOM declaration,
+// independent of whether the template is ever instantiated).
+
+import { Directive, Input, type Type } from '@angular/core';
+import type { ISearchBarCommands, ISearchBarOptions, IScreenOptions, IRoute } from '../core';
+import type { INavigatorHandle } from '../core';
+
+// The imperative ref (focus/blur/clearText/setText/cancelSearch/toggleCancelButton) carries a
+// framework 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). Angular has no
+// `RefObject` primitive of its own, but the underlying shape (`{ current: T | null }`, mutated
+// once the native view is available) is framework-agnostic in itself - the app constructs a plain
+// mutable object and this adapter assigns `.current` once the search bar's native node exists
+// (search-bar-ref.directive.ts), the same contract react/screen.ts's IReactSearchBarOptions uses.
+export type IAngularSearchBarOptions = ISearchBarOptions & {
+  ref?: { current: ISearchBarCommands | null };
+};
+
+export type IAngularScreenOptions = Omit<IScreenOptions, 'headerSearchBarOptions'> & {
+  headerSearchBarOptions?: IAngularSearchBarOptions;
+};
+
+// A screen's options can be a plain object or a resolver run OUTSIDE the render lifecycle (when
+// Stack folds a route's options): its `navigation` argument is a live navigator handle a bar-button
+// onPress closes over, so this is NOT the props-based navigation the screen body reads via inject -
+// it's a deliberate escape hatch that stays.
+export type IScreenOptionsArgs = {
+  route: IRoute<unknown>;
+  navigation: INavigatorHandle;
+};
+
+export type IScreenOptionsResolver = (args: IScreenOptionsArgs) => IAngularScreenOptions;
+
+@Directive({
+  selector: 'ng-template[symbioteScreen]',
+  standalone: true,
+})
+export class ScreenDirective {
+  @Input({ required: true }) name!: string;
+  @Input({ required: true }) component!: Type<unknown>;
+  @Input() options?: IAngularScreenOptions | IScreenOptionsResolver;
+  @Input() initialParams?: unknown;
+}

package/src/angular/search-bar-ref.directive.ts

@@ -0,0 +1,38 @@
+// Assigns the app-supplied `headerSearchBarOptions.ref` (a plain `{ current }` cell - see
+// screen.directive.ts's IAngularSearchBarOptions) once the RNSSearchBar native node exists.
+// Angular's twin of react/stack.ts's callback `ref` prop on the RNSSearchBar element: a directive
+// applied directly onto the raw `<RNSSearchBar>` tag can `inject(ElementRef)` the same way
+// SymbioteHostPropsDirective does (primitives/shared.ts's own pattern) - ElementRef.nativeElement
+// is the real engine node the moment the element is created (synchronous, no whenCommitted wait
+// needed here: buildSearchBarHandle's own methods are already a LAZY getter over the node,
+// tolerant of the node existing-but-not-yet-committed, same contract every adapter shares).
+
+import { Directive, Input, inject, type OnDestroy, type OnInit, ElementRef } from '@angular/core';
+import { isSymbioteNode, dlog, debugNodeId } from '@symbiote-native/engine';
+import { buildSearchBarHandle } from '../core';
+import type { ISearchBarCommands } from '../core';
+
+@Directive({
+  selector: '[symbioteSearchBarRef]',
+  standalone: true,
+})
+export class SearchBarRefDirective implements OnInit, OnDestroy {
+  @Input('symbioteSearchBarRef') ref: { current: ISearchBarCommands | null } | undefined;
+
+  private readonly elementRef = inject<ElementRef<unknown>>(ElementRef);
+
+  ngOnInit(): void {
+    if (!this.ref) return;
+    const node = this.elementRef.nativeElement;
+    if (!isSymbioteNode(node)) {
+      this.ref.current = null;
+      return;
+    }
+    dlog(`SearchBarRefDirective: attached to node=${debugNodeId(node)}`);
+    this.ref.current = buildSearchBarHandle(() => node);
+  }
+
+  ngOnDestroy(): void {
+    if (this.ref) this.ref.current = null;
+  }
+}