@symbiote-native/navigation 1.0.0

package/src/react/tabs/index.ts

@@ -0,0 +1,204 @@
+// Tab, the React lifecycle half. The focused-index router (tab-router-state) and the tab-bar
+// Descriptor builder (render-tabs) live in @symbiote-native/navigation core, shared verbatim
+// with the Vue/Angular adapters; here React supplies the lifecycle - useReducer for the focused
+// index, useId for route-key generation, useImperativeHandle for the jumpTo/setParams handle -
+// plus the descriptor bridge for the tab-bar leaf, exactly like Stack bridges its header config
+// (react/stack.ts). Unlike Stack, a bottom-tabs bar is a PURE-JS UI: it paints ordinary
+// `symbiote-view`/`symbiote-text` primitives via the shared render fn, so there is no
+// react-native-screens ViewConfig to register here - Tab needs no `../register` import.
+
+import {
+  createElement,
+  forwardRef,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useMemo,
+  useReducer,
+} from 'react';
+import type { ReactElement, ReactNode } from 'react';
+import { descriptorToReact } from '@symbiote-native/react';
+import { dlog } from '@symbiote-native/engine';
+import {
+  NAVIGATION_EVENT_BLUR,
+  NAVIGATION_EVENT_FOCUS,
+  createInitialTabState,
+  createNavigationEmitter,
+  isFocusedRoute,
+  renderTabBar,
+  tabRouterReducer,
+} from '../../core';
+import type { IRoute, ITabBarItemView, ITabNavigatorHandle, ITabOptions } from '../../core';
+import { collectRegistry } from '../collect-registry';
+import { NavigationContext } from '../navigation-context';
+import { TabScreen } from '../tab-screen';
+import type { ITabScreenOptionsArgs, ITabScreenProps } from '../tab-screen';
+
+export type { ITabNavigatorHandle } from '../../core';
+
+export type ITabProps = {
+  initialRouteName?: string;
+  screenOptions?: ITabOptions;
+  children?: ReactNode;
+};
+
+type ITabRegistryEntry = Omit<ITabScreenProps, 'name'>;
+
+function isTabScreenElement(child: ReactNode): child is ReactElement<ITabScreenProps> {
+  return isValidElement(child) && child.type === TabScreen;
+}
+
+function resolveTabOptions(
+  entry: ITabRegistryEntry,
+  optionsArgs: ITabScreenOptionsArgs,
+  screenOptions: ITabOptions | undefined,
+): ITabOptions {
+  const own = typeof entry.options === 'function' ? entry.options(optionsArgs) : entry.options;
+  return { ...screenOptions, ...own };
+}
+
+const TAB_CONTENT_STYLE = { flex: 1 };
+const TAB_ROOT_STYLE = { flex: 1 };
+
+const TabImpl = forwardRef<ITabNavigatorHandle, ITabProps>((props, forwardedRef) => {
+  // Read BEFORE establishing this Tab's own Context value below - becomes the `parent` link a
+  // nested screen's useNavigation().getParent() walks (e.g. this Tab rendered as a Stack screen's
+  // content reaches that Stack via this value). undefined when this Tab is the nesting root.
+  const ambientContext = useContext(NavigationContext);
+  const registry = useMemo(
+    () => collectRegistry(props.children, isTabScreenElement),
+    [props.children],
+  );
+  const routeIdPrefix = useId();
+
+  const routes = useMemo<IRoute<unknown>[]>(
+    () =>
+      Array.from(registry.entries()).map(([name, entry]) => ({
+        key: `${routeIdPrefix}-${name}`,
+        name,
+        params: entry.initialParams,
+      })),
+    [registry, routeIdPrefix],
+  );
+
+  const [state, dispatch] = useReducer(tabRouterReducer, undefined, () =>
+    createInitialTabState(routes, props.initialRouteName),
+  );
+
+  if (routes.length === 0) dlog('Tab: no <Tab.Screen> children registered');
+
+  const jumpTo = useCallback(
+    (name: string, params?: unknown) => dispatch({ type: 'jumpTo', name, params }),
+    [],
+  );
+  const setParams = useCallback(
+    (params: unknown, key: string) => dispatch({ type: 'setParams', key, params }),
+    [],
+  );
+
+  const handle = useMemo<ITabNavigatorHandle>(() => ({ jumpTo, setParams }), [jumpTo, setParams]);
+
+  useImperativeHandle(forwardedRef, () => handle, [handle]);
+
+  const focusedRoute: IRoute<unknown> | undefined = state.routes[state.index];
+
+  const items: ITabBarItemView[] = state.routes.map((route, index) => {
+    const entry = registry.get(route.name);
+    const focused = isFocusedRoute(index, state.index);
+    if (!entry) {
+      dlog(`Tab: no screen registered for route name "${route.name}"`);
+      return {
+        key: route.key,
+        focused,
+        label: route.name,
+        passthrough: {},
+      };
+    }
+
+    const options = resolveTabOptions(entry, { route, navigation: handle }, props.screenOptions);
+
+    return {
+      key: route.key,
+      focused,
+      label: options.tabBarLabel ?? options.title ?? route.name,
+      icon: options.tabBarIcon,
+      badge: options.tabBarBadge,
+      activeTintColor: options.tabBarActiveTintColor,
+      inactiveTintColor: options.tabBarInactiveTintColor,
+      passthrough: {
+        onPress: () => jumpTo(route.name),
+        accessibilityRole: 'tab',
+        accessibilityState: { selected: focused },
+      },
+    };
+  });
+
+  const focusedEntry = focusedRoute ? registry.get(focusedRoute.name) : undefined;
+  const focusedOptions: ITabOptions | undefined =
+    focusedEntry && focusedRoute
+      ? resolveTabOptions(
+          focusedEntry,
+          { route: focusedRoute, navigation: handle },
+          props.screenOptions,
+        )
+      : props.screenOptions;
+
+  const tabBar = descriptorToReact(
+    renderTabBar({ items, style: focusedOptions?.tabBarStyle, passthrough: {} }),
+  );
+
+  // Only the focused route's screen is ever mounted (unlike Stack, which keeps every pushed route
+  // alive), so a fresh emitter per focus change is sufficient - no per-route emitter map to prune,
+  // because the previous screen's whole subtree (and any listeners it registered) is torn down by
+  // an ordinary React unmount when focus moves on. Keyed on the route KEY rather than the route
+  // object so a setParams-only change (new route object, same key) doesn't spuriously re-fire
+  // focus/blur.
+  const focusedRouteKey = focusedRoute?.key;
+  const routeEmitter = useMemo(() => createNavigationEmitter(), [focusedRouteKey]);
+
+  // Tab paints its own bar in pure JS - there is no native onAppear/onDisappear to hook (unlike
+  // Stack's RNSScreen), so focus/blur is synthesized here: mount = focus, cleanup = blur, exactly
+  // what an effect keyed on focusedRouteKey already encodes - no diffFocusedRoute indirection
+  // needed (unlike Vue/Angular, which diff real prev/next keys inside an imperative watch/CD
+  // callback that has no mount/cleanup pairing of its own).
+  useEffect(() => {
+    if (focusedRouteKey === undefined) return undefined;
+    dlog(`Tab: route "${focusedRoute?.name}" focused`);
+    routeEmitter.emit(NAVIGATION_EVENT_FOCUS);
+    return () => {
+      dlog(`Tab: route "${focusedRoute?.name}" blurred`);
+      routeEmitter.emit(NAVIGATION_EVENT_BLUR);
+    };
+    // focusedRoute omitted deliberately: only its .key (tracked via focusedRouteKey) should
+    // re-run this effect - see the comment above on focusedRouteKey.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [routeEmitter, focusedRouteKey]);
+
+  const content =
+    focusedEntry && focusedRoute
+      ? createElement(
+          NavigationContext.Provider,
+          {
+            value: {
+              route: focusedRoute,
+              navigation: handle,
+              emitter: routeEmitter,
+              parent: ambientContext,
+            },
+          },
+          createElement(focusedEntry.component),
+        )
+      : null;
+
+  return createElement(
+    'symbiote-view',
+    { style: TAB_ROOT_STYLE },
+    createElement('symbiote-view', { style: TAB_CONTENT_STYLE }, content),
+    tabBar,
+  );
+});
+
+export const Tab = Object.assign(TabImpl, { Screen: TabScreen });

package/src/react/tabs/tabs.test.tsx

@@ -0,0 +1,256 @@
+// Co-located React-driven test (ADR 0025) for the @symbiote-native/navigation React Tab
+// navigator. Unlike Stack (which drives real native RNSScreen views and needs an injected
+// codegen-shaped ViewConfig - see stack.test.tsx), the tab bar is a PURE-JS UI painted from
+// ordinary `symbiote-view`/`symbiote-text` primitives, so no ViewConfig source is needed here at
+// all. Proves: only the focused route's screen mounts, jumpTo() moves focus, a tap (synthesized
+// by the engine from a topTouchStart/topTouchEnd pair - core/engine/src/events/index.ts - on the
+// tab button) drives the same jumpTo, and per-tab options (label/badge/tint) reach the tab bar.
+
+import { act, createElement, createRef, useCallback } from 'react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mount, unmount } from '@symbiote-native/react';
+import { installFabric, type IFakeNode } from '@symbiote-native/test-utils';
+import { Tab } from './index';
+import type { ITabNavigatorHandle } from './index';
+import { useFocusEffect, useIsFocused, useNavigation, useRoute } from '../hooks';
+
+const ROOT_TAG = 640;
+const TOUCH_START = 'topTouchStart';
+const TOUCH_END = 'topTouchEnd';
+
+const fabric = installFabric();
+
+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;
+}
+
+// The tab bar row: the second child of Tab's root `symbiote-view` (content wrapper first, bar
+// second - see react/tabs.ts's final createElement).
+function tabBarRow(): IFakeNode {
+  const root = fabric.appRoot();
+  const tabRoot = root.children[0];
+  const bar = tabRoot?.children[1];
+  if (!bar) throw new Error('no tab bar row was committed');
+  return bar;
+}
+
+function tapItem(index: number): void {
+  const item = tabBarRow().children[index];
+  if (!item) throw new Error(`no tab item at index ${index}`);
+  act(() => {
+    fabric.fireEvent(item.instanceHandle, TOUCH_START, {
+      touches: [{ identifier: 1, pageX: 0, pageY: 0 }],
+      changedTouches: [{ identifier: 1, pageX: 0, pageY: 0 }],
+    });
+    fabric.fireEvent(item.instanceHandle, TOUCH_END, {
+      touches: [],
+      changedTouches: [{ identifier: 1, pageX: 0, pageY: 0 }],
+    });
+  });
+}
+
+function HomeScreen(): ReturnType<typeof createElement> {
+  return createElement('symbiote-text', {}, 'home');
+}
+
+function ProfileScreen(): ReturnType<typeof createElement> {
+  return createElement('symbiote-text', {}, 'profile');
+}
+
+describe('React Tab navigator', () => {
+  it('mounts only the initial focused route content, and the tab bar for every registered route', () => {
+    mount(
+      ROOT_TAG,
+      createElement(
+        Tab,
+        { initialRouteName: 'Home' },
+        createElement(Tab.Screen, {
+          name: 'Home',
+          component: HomeScreen,
+          options: { tabBarLabel: 'Home' },
+        }),
+        createElement(Tab.Screen, {
+          name: 'Profile',
+          component: ProfileScreen,
+          options: { tabBarLabel: 'Profile' },
+        }),
+      ),
+    );
+    expect(findAllText(fabric.committed)).toContain('home');
+    expect(findAllText(fabric.committed)).not.toContain('profile');
+    expect(tabBarRow().children).toHaveLength(2);
+    expect(findAllText(tabBarRow().children)).toEqual(['Home', 'Profile']);
+  });
+
+  it('jumpTo() switches the focused screen content', () => {
+    const ref = createRef<ITabNavigatorHandle>();
+    mount(
+      ROOT_TAG,
+      createElement(
+        Tab,
+        { ref, initialRouteName: 'Home' },
+        createElement(Tab.Screen, { name: 'Home', component: HomeScreen }),
+        createElement(Tab.Screen, { name: 'Profile', component: ProfileScreen }),
+      ),
+    );
+    act(() => ref.current?.jumpTo('Profile'));
+    expect(findAllText(fabric.committed)).toContain('profile');
+    expect(findAllText(fabric.committed)).not.toContain('home');
+  });
+
+  it('a tap on a tab bar item drives the same jumpTo as the imperative handle', () => {
+    mount(
+      ROOT_TAG,
+      createElement(
+        Tab,
+        { initialRouteName: 'Home' },
+        createElement(Tab.Screen, { name: 'Home', component: HomeScreen }),
+        createElement(Tab.Screen, { name: 'Profile', component: ProfileScreen }),
+      ),
+    );
+    expect(findAllText(fabric.committed)).toContain('home');
+    tapItem(1);
+    expect(findAllText(fabric.committed)).toContain('profile');
+    expect(findAllText(fabric.committed)).not.toContain('home');
+  });
+
+  it('jumpTo() to an unknown route name is a no-op', () => {
+    const ref = createRef<ITabNavigatorHandle>();
+    mount(
+      ROOT_TAG,
+      createElement(
+        Tab,
+        { ref, initialRouteName: 'Home' },
+        createElement(Tab.Screen, { name: 'Home', component: HomeScreen }),
+        createElement(Tab.Screen, { name: 'Profile', component: ProfileScreen }),
+      ),
+    );
+    act(() => ref.current?.jumpTo('Nowhere'));
+    expect(findAllText(fabric.committed)).toContain('home');
+  });
+
+  it('exposes route.params to the focused screen component via useRoute() after jumpTo', () => {
+    let receivedParams: unknown;
+    function ParamsScreen(): ReturnType<typeof createElement> {
+      receivedParams = useRoute().params;
+      return createElement('symbiote-text', {}, 'params');
+    }
+    const ref = createRef<ITabNavigatorHandle>();
+    mount(
+      ROOT_TAG,
+      createElement(
+        Tab,
+        { ref, initialRouteName: 'Home' },
+        createElement(Tab.Screen, { name: 'Home', component: HomeScreen }),
+        createElement(Tab.Screen, { name: 'Profile', component: ParamsScreen }),
+      ),
+    );
+    act(() => ref.current?.jumpTo('Profile', { id: 42 }));
+    expect(receivedParams).toEqual({ id: 42 });
+  });
+
+  it('resolves tabBarBadge onto the focused-agnostic tab item', () => {
+    mount(
+      ROOT_TAG,
+      createElement(
+        Tab,
+        { initialRouteName: 'Home' },
+        createElement(Tab.Screen, {
+          name: 'Home',
+          component: HomeScreen,
+          options: { tabBarBadge: 3 },
+        }),
+        createElement(Tab.Screen, { name: 'Profile', component: ProfileScreen }),
+      ),
+    );
+    expect(findAllText(tabBarRow().children)).toContain('3');
+  });
+
+  // Before this fix, Tab never wrapped its focused screen in NavigationContext.Provider at all,
+  // so every one of these hooks threw "must be used within a screen rendered by <Stack>" the
+  // moment a Tab screen called them - a real gap, not just a nesting concern (see this package's
+  // task notes). These cases prove the context is now provided and the focus semantics are wired.
+  it('useNavigation()/useRoute() are usable inside a Tab screen, and useIsFocused() reflects the focused tab', () => {
+    let homeIsFocused: boolean | undefined;
+    let homeRouteName: string | undefined;
+    let profileIsFocused: boolean | undefined;
+
+    function TrackedHomeScreen(): ReturnType<typeof createElement> {
+      const navigation = useNavigation();
+      homeIsFocused = useIsFocused();
+      homeRouteName = useRoute().name;
+      // Merely proving the handle is a real ITabNavigatorHandle (jumpTo/setParams), not the
+      // Stack-only shape this Context value was hard-typed to before the widened union.
+      expect(typeof navigation.jumpTo).toBe('function');
+      return createElement('symbiote-text', {}, 'home');
+    }
+    function TrackedProfileScreen(): ReturnType<typeof createElement> {
+      profileIsFocused = useIsFocused();
+      return createElement('symbiote-text', {}, 'profile');
+    }
+
+    const ref = createRef<ITabNavigatorHandle>();
+    // Tab's own focus-emitting effect runs in the same commit as the initial mount, but the
+    // setIsFocused(true) it triggers inside useIsFocused's listener lands in a follow-up render -
+    // act() is what drains that cascade synchronously (mirrors every other state-changing call in
+    // this file already being act()-wrapped).
+    act(() => {
+      mount(
+        ROOT_TAG,
+        createElement(
+          Tab,
+          { ref, initialRouteName: 'Home' },
+          createElement(Tab.Screen, { name: 'Home', component: TrackedHomeScreen }),
+          createElement(Tab.Screen, { name: 'Profile', component: TrackedProfileScreen }),
+        ),
+      );
+    });
+    expect(homeIsFocused).toBe(true);
+    expect(homeRouteName).toBe('Home');
+
+    act(() => ref.current?.jumpTo('Profile'));
+    expect(profileIsFocused).toBe(true);
+  });
+
+  it('useFocusEffect runs on Tab focus and its cleanup once jumpTo moves focus away', () => {
+    const events: string[] = [];
+    function TrackedHomeScreen(): ReturnType<typeof createElement> {
+      useFocusEffect(
+        useCallback(() => {
+          events.push('effect');
+          return () => events.push('cleanup');
+        }, []),
+      );
+      return createElement('symbiote-text', {}, 'home');
+    }
+
+    const ref = createRef<ITabNavigatorHandle>();
+    mount(
+      ROOT_TAG,
+      createElement(
+        Tab,
+        { ref, initialRouteName: 'Home' },
+        createElement(Tab.Screen, { name: 'Home', component: TrackedHomeScreen }),
+        createElement(Tab.Screen, { name: 'Profile', component: ProfileScreen }),
+      ),
+    );
+    // Tab paints no native RNSScreen (unlike Stack), so there is no onAppear to wait for - the
+    // focused screen's useFocusEffect runs as soon as it mounts.
+    expect(events).toEqual(['effect']);
+
+    act(() => ref.current?.jumpTo('Profile'));
+    expect(events).toEqual(['effect', 'cleanup']);
+  });
+});

package/src/register.ts

@@ -0,0 +1,59 @@
+// Side-effect: register RNSScreen/RNSScreenStack/RNSScreenStackHeaderConfig/
+// RNSScreenStackHeaderSubview/RNSSearchBar/RNSScreenContentWrapper's ViewConfigs in RN's
+// ReactNativeViewConfigRegistry. Evaluating each codegen native-component spec
+// (codegenNativeComponent('RNSScreen', ...) etc.) registers the getter the engine reads via
+// setNativeViewConfigSource, so events + color processors derive on first commit. We import the
+// codegen SPECS, never react-native-screens' React components (ScreenStack.tsx et al - hooks,
+// crashes a non-React adapter) - these modules have no hooks, so they are framework-agnostic and
+// shared by every adapter entry. Each adapter barrel imports this; the component modules and
+// their headless tests stay free of it. See CLAUDE.md <third_party_rn_packages_are_react_only>.
+//
+// RNSSearchBar (headerSearchBarOptions' native leaf, nested by render-stack.ts's
+// renderHeaderConfig) was missing from this list - its ViewConfig was never registered, so Fabric
+// had no component descriptor for 'RNSSearchBar' and crashed on mount the moment a screen set
+// headerSearchBarOptions. That is the root cause of the search-bar crash, not a deeper
+// Fabric-interop gap.
+//
+// RNSScreenStackHeaderSubview (the wrapper renderHeaderConfig nests the search bar leaf inside,
+// per RNSScreenStackHeaderConfig.mm's mountChildComponentView requiring every header child to be
+// one) needs the same registration, or the same class of mount crash follows.
+//
+// RNSScreenContentWrapper (the RNS_SCREEN_CONTENT_WRAPPER_VIEW_NAME wrapper stack.ts wraps every
+// screen's content in - see its comment in core/constants.ts) additionally needs a NATIVE-side
+// registration: this file alone is not enough. The native iOS registry
+// (RCTThirdPartyComponentsProvider.mm, generated by codegen from THIS package's own
+// package.json#codegenConfig.ios.componentProvider map, NOT from react-native-screens') has no
+// entry for 'RNSScreenContentWrapper' by default, so without it Fabric falls back to its
+// "Unimplemented component" placeholder view regardless of this file's import. Both registries
+// are independently required for a never-before-used react-native-screens view: this file (JS
+// ViewConfig, read by @symbiote-native/engine's registry.ts) and package.json's componentProvider
+// map (native ComponentDescriptor, read by codegen at `pod install` time).
+//
+// RNSModalScreen's gap on both registries isn't a mount crash but a silent mispositioning bug.
+// react-native-screens' own Screen.tsx picks
+// ModalScreenNativeComponent ('RNSModalScreen') instead of ScreenNativeComponent ('RNSScreen')
+// whenever stackPresentation isn't push/containedModal/containedTransparentModal, because
+// RNSScreen.mm's updateLayoutMetrics: checks `[self isKindOfClass:RNSModalScreen.class]` and, for
+// that class, DELIBERATELY skips applying Yoga's computed frame (its own comment: "the available
+// space is most likely restricted & differs from what Yoga resolves during first layout - we want
+// to rely on native layout here"). Emitting a plain 'RNSScreen' for a formSheet/modal presentation
+// (as resolveScreenViewName below used to do unconditionally) means that check never matches, so
+// Yoga's frame - computed as if the screen were still a normal flexed sibling in its outer
+// RNSScreenStack's push-oriented column layout - gets applied verbatim and never corrected,
+// visually shifting the whole modal down by one full screen's height. Fixed in
+// core/render-stack.ts's resolveScreenViewName, which now mirrors Screen.tsx's own
+// shouldUseModalScreenComponent condition exactly.
+//
+// Unlike @symbiote-native/slider (which deep-imports @react-native-community/slider's compiled
+// `dist/`), react-native-screens declares `"react-native": "src/index"` in its package.json -
+// Metro's resolverMainFields prioritizes that field, so it resolves the library straight to raw
+// TypeScript source and transforms it like first-party code. The deep import below targets that
+// same `src/fabric/` tree rather than a compiled output.
+
+import 'react-native-screens/src/fabric/ScreenNativeComponent';
+import 'react-native-screens/src/fabric/ModalScreenNativeComponent';
+import 'react-native-screens/src/fabric/ScreenStackNativeComponent';
+import 'react-native-screens/src/fabric/ScreenStackHeaderConfigNativeComponent';
+import 'react-native-screens/src/fabric/ScreenStackHeaderSubviewNativeComponent';
+import 'react-native-screens/src/fabric/SearchBarNativeComponent';
+import 'react-native-screens/src/fabric/ScreenContentWrapperNativeComponent';