@symbiote-native/navigation 1.0.0 → 2.0.1

package/build/react/drawer-screen.d.ts

@@ -1,14 +0,0 @@
-import type { FC, ReactElement } from 'react';
-import type { IDrawerNavigatorHandle, IDrawerScreenOptions, IRoute } from '../core';
-export type IDrawerScreenOptionsArgs = {
-    route: IRoute<unknown>;
-    navigation: IDrawerNavigatorHandle;
-};
-export type IDrawerScreenOptionsResolver = (args: IDrawerScreenOptionsArgs) => IDrawerScreenOptions;
-export type IDrawerScreenProps = {
-    name: string;
-    component: FC;
-    options?: IDrawerScreenOptions | IDrawerScreenOptionsResolver;
-    initialParams?: unknown;
-};
-export declare function DrawerScreen(_props: IDrawerScreenProps): ReactElement | null;

package/build/react/drawer-screen.js

@@ -1,8 +0,0 @@
-// Drawer.Screen: a declarative marker, never rendered on its own - Drawer reads its props via
-// React.Children to build the static name -> {component, options} registry, then mounts the
-// FOCUSED route's component. Mirrors react/tab-screen.ts (Tab's twin - the closer sibling, both
-// are fixed-route-list/no-push navigators) and react/screen.ts (Stack's twin); see CLAUDE.md
-// <third_party_rn_packages_are_react_only> - this and Drawer import nothing from react-native.
-export function DrawerScreen(_props) {
-    return null;
-}

package/build/react/hooks/index.d.ts

@@ -1,12 +0,0 @@
-export { useNavigation } from './use-navigation';
-export type { INavigationHandle } from './use-navigation';
-export { useStackNavigation } from './use-stack-navigation';
-export type { IStackNavigationHandle } from './use-stack-navigation';
-export { useTabNavigation } from './use-tab-navigation';
-export type { ITabNavigationHandle } from './use-tab-navigation';
-export { useDrawerNavigation } from './use-drawer-navigation';
-export type { IDrawerNavigationHandle } from './use-drawer-navigation';
-export { useRoute } from './use-route';
-export { useIsFocused } from './use-is-focused';
-export { useFocusEffect } from './use-focus-effect';
-export { useNavigationState } from './use-navigation-state';

package/build/react/hooks/index.js

@@ -1,8 +0,0 @@
-export { useNavigation } from './use-navigation.js';
-export { useStackNavigation } from './use-stack-navigation.js';
-export { useTabNavigation } from './use-tab-navigation.js';
-export { useDrawerNavigation } from './use-drawer-navigation.js';
-export { useRoute } from './use-route.js';
-export { useIsFocused } from './use-is-focused.js';
-export { useFocusEffect } from './use-focus-effect.js';
-export { useNavigationState } from './use-navigation-state/index.js';

package/build/react/hooks/use-drawer-navigation.d.ts

@@ -1,4 +0,0 @@
-import type { IDrawerNavigatorHandle } from '../../core';
-import type { INavigationHandle } from './use-navigation';
-export type IDrawerNavigationHandle = IDrawerNavigatorHandle & Pick<INavigationHandle, 'addListener' | 'getParent'>;
-export declare function useDrawerNavigation(): IDrawerNavigationHandle;

package/build/react/hooks/use-drawer-navigation.js

@@ -1,12 +0,0 @@
-// Twin of use-stack-navigation.ts, narrowing to a Drawer handle instead. See that file's header
-// for why this exists: it hides the union-narrowing guard inside the library instead of every call site.
-import { isDrawerNavigatorHandle } from '../../core/index.js';
-import { useNavigation } from './use-navigation.js';
-export function useDrawerNavigation() {
-    const navigation = useNavigation();
-    if (!isDrawerNavigatorHandle(navigation)) {
-        throw new Error('useDrawerNavigation() was called from a component whose nearest navigator is not a Drawer. ' +
-            'Use useNavigation() instead if this component can render under more than one navigator kind.');
-    }
-    return navigation;
-}

package/build/react/hooks/use-focus-effect.d.ts

@@ -1,2 +0,0 @@
-import type { EffectCallback } from 'react';
-export declare function useFocusEffect(effect: EffectCallback): void;

package/build/react/hooks/use-focus-effect.js

@@ -1,29 +0,0 @@
-// Thin useEffect wrapper: runs `effect` while the route is focused and runs its own returned
-// cleanup on blur - exactly React.useEffect's contract, just re-armed on every focus/blur pair
-// instead of once on mount - mirrors @react-navigation's useFocusEffect. Callers should memoize
-// `effect` (React.useCallback), same requirement the upstream hook documents, since a new
-// `effect` identity re-subscribes here like any other useEffect dependency change.
-import { useEffect } from 'react';
-import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS } from '../../core/index.js';
-import { useRequiredNavigationContext } from '../navigation-context.js';
-export function useFocusEffect(effect) {
-    const context = useRequiredNavigationContext('useFocusEffect');
-    const { emitter } = context;
-    useEffect(() => {
-        let cleanup;
-        const runEffect = () => {
-            cleanup = effect();
-        };
-        const runCleanup = () => {
-            cleanup?.();
-            cleanup = undefined;
-        };
-        const unsubscribeFocus = emitter.addListener(NAVIGATION_EVENT_FOCUS, runEffect);
-        const unsubscribeBlur = emitter.addListener(NAVIGATION_EVENT_BLUR, runCleanup);
-        return () => {
-            unsubscribeFocus();
-            unsubscribeBlur();
-            runCleanup();
-        };
-    }, [emitter, effect]);
-}

package/build/react/hooks/use-is-focused.d.ts

@@ -1 +0,0 @@
-export declare function useIsFocused(): boolean;

package/build/react/hooks/use-is-focused.js

@@ -1,22 +0,0 @@
-// Thin useEffect wrapper: subscribes to the route's focus/blur pair and returns whether it's
-// currently focused, re-rendering on change - mirrors @react-navigation's useIsFocused. Starts
-// `false` rather than guessing from stack position: the route's emitter only fires 'focus' once
-// RNSScreen's native onAppear actually lands (stack.ts), so a screen genuinely isn't focused yet
-// at the instant it mounts - same async gap real native transitions have.
-import { useEffect, useState } from 'react';
-import { NAVIGATION_EVENT_BLUR, NAVIGATION_EVENT_FOCUS } from '../../core/index.js';
-import { useRequiredNavigationContext } from '../navigation-context.js';
-export function useIsFocused() {
-    const context = useRequiredNavigationContext('useIsFocused');
-    const { emitter } = context;
-    const [isFocused, setIsFocused] = useState(false);
-    useEffect(() => {
-        const unsubscribeFocus = emitter.addListener(NAVIGATION_EVENT_FOCUS, () => setIsFocused(true));
-        const unsubscribeBlur = emitter.addListener(NAVIGATION_EVENT_BLUR, () => setIsFocused(false));
-        return () => {
-            unsubscribeFocus();
-            unsubscribeBlur();
-        };
-    }, [emitter]);
-    return isFocused;
-}

package/build/react/hooks/use-navigation-state/index.d.ts

@@ -1,2 +0,0 @@
-import type { INavigatorState } from '../../../core';
-export declare function useNavigationState<TResult>(selector: (state: INavigatorState) => TResult): TResult;

package/build/react/hooks/use-navigation-state/index.js

@@ -1,39 +0,0 @@
-// Thin selector wrapper: subscribes to the router's `state` broadcast (stack.ts's render loop
-// re-emits the full INavigatorState to every route's emitter after each commit) and returns
-// `selector(state)`, re-rendering only when the emitted state changes - mirrors
-// @react-navigation's useNavigationState. The reducer/dispatch machinery it selects over lives in
-// core/navigator-state.ts; this hook only wires the subscription + local re-render.
-//
-// Seeded from a single-route snapshot ({ routes: [route] }) rather than left undefined: the real
-// broadcast lands a tick later (post-commit useEffect), so a selector reading e.g.
-// `state.routes.at(-1)?.name` still resolves correctly on first paint for the common single-route
-// case, closing the same async gap useIsFocused documents.
-//
-// Live updates currently only arrive under <Stack> - it's the only navigator that emits
-// NAVIGATION_EVENT_STATE (its post-commit useEffect in stack.ts); <Tab>/<Drawer> don't broadcast
-// it, so under those this hook silently stays on its initial snapshot.
-import { useEffect, useRef, useState } from 'react';
-import { NAVIGATION_EVENT_STATE, isRecord } from '../../../core/index.js';
-import { useRequiredNavigationContext } from '../../navigation-context.js';
-export function useNavigationState(selector) {
-    const context = useRequiredNavigationContext('useNavigationState');
-    const { route, emitter } = context;
-    const [result, setResult] = useState(() => selector({ routes: [route] }));
-    // selector is typically an inline arrow at the call site (`useNavigationState(s => ...)`), a
-    // fresh identity every render - read through a ref so the effect below doesn't need `selector`
-    // in its deps, and doesn't unsubscribe/resubscribe on every render because of it (the same trap
-    // useFocusEffect's own comment documents for its `effect` argument).
-    const selectorRef = useRef(selector);
-    selectorRef.current = selector;
-    useEffect(() => {
-        return emitter.addListener(NAVIGATION_EVENT_STATE, (state) => {
-            if (!isNavigatorState(state))
-                return;
-            setResult(selectorRef.current(state));
-        });
-    }, [emitter]);
-    return result;
-}
-function isNavigatorState(value) {
-    return isRecord(value) && Array.isArray(value.routes);
-}

package/build/react/hooks/use-navigation.d.ts

@@ -1,7 +0,0 @@
-import type { INavigationEventListener, INavigationEventName } from '../../core';
-import type { IAnyNavigatorHandle } from '../navigation-context';
-export type INavigationHandle = IAnyNavigatorHandle & {
-    addListener: (event: INavigationEventName, listener: INavigationEventListener) => () => void;
-    getParent: () => IAnyNavigatorHandle | undefined;
-};
-export declare function useNavigation(): INavigationHandle;

package/build/react/hooks/use-navigation.js

@@ -1,16 +0,0 @@
-// Thin lifecycle wrapper: returns the current screen's navigator handle (push/pop/replace/... for a
-// Stack screen, jumpTo/setParams for a Tab screen, openDrawer/... for a Drawer screen) plus
-// addListener bound to that route's own emitter - mirrors @react-navigation's
-// `navigation.addListener('focus', cb)` surface. All pub/sub logic lives in
-// ../../core/navigation-events; this hook only reads NavigationContext and binds identity.
-import { useMemo } from 'react';
-import { useRequiredNavigationContext } from '../navigation-context.js';
-export function useNavigation() {
-    const context = useRequiredNavigationContext('useNavigation');
-    const { navigation, emitter, parent } = context;
-    return useMemo(() => ({
-        ...navigation,
-        addListener: emitter.addListener,
-        getParent: () => parent?.navigation,
-    }), [navigation, emitter, parent]);
-}

package/build/react/hooks/use-route.d.ts

@@ -1,2 +0,0 @@
-import type { IRoute } from '../../core';
-export declare function useRoute(): IRoute<unknown>;

package/build/react/hooks/use-route.js

@@ -1,8 +0,0 @@
-// Thin lifecycle wrapper: returns the current screen's IRoute from NavigationContext - mirrors
-// @react-navigation's useRoute. Zero logic of its own; the route object itself is built by
-// stack.ts's render loop from the core reducer's state.
-import { useRequiredNavigationContext } from '../navigation-context.js';
-export function useRoute() {
-    const context = useRequiredNavigationContext('useRoute');
-    return context.route;
-}

package/build/react/hooks/use-stack-navigation.d.ts

@@ -1,4 +0,0 @@
-import type { INavigatorHandle } from '../../core';
-import type { INavigationHandle } from './use-navigation';
-export type IStackNavigationHandle = INavigatorHandle & Pick<INavigationHandle, 'addListener' | 'getParent'>;
-export declare function useStackNavigation(): IStackNavigationHandle;

package/build/react/hooks/use-stack-navigation.js

@@ -1,14 +0,0 @@
-// useNavigation() returns a union (IAnyNavigatorHandle) since it doesn't know which navigator
-// mounted the calling component. When a component genuinely knows it only ever renders under a
-// Stack (the common case for anything nested a few levels below a Stack screen), this hook
-// narrows that union ONCE, here, so call sites never write their own 'push' in navigation check.
-import { isStackNavigatorHandle } from '../../core/index.js';
-import { useNavigation } from './use-navigation.js';
-export function useStackNavigation() {
-    const navigation = useNavigation();
-    if (!isStackNavigatorHandle(navigation)) {
-        throw new Error('useStackNavigation() was called from a component whose nearest navigator is not a Stack. ' +
-            'Use useNavigation() instead if this component can render under more than one navigator kind.');
-    }
-    return navigation;
-}

package/build/react/hooks/use-tab-navigation.d.ts

@@ -1,4 +0,0 @@
-import type { ITabNavigatorHandle } from '../../core';
-import type { INavigationHandle } from './use-navigation';
-export type ITabNavigationHandle = ITabNavigatorHandle & Pick<INavigationHandle, 'addListener' | 'getParent'>;
-export declare function useTabNavigation(): ITabNavigationHandle;

package/build/react/hooks/use-tab-navigation.js

@@ -1,12 +0,0 @@
-// Twin of use-stack-navigation.ts, narrowing to a Tab handle instead. See that file's header for
-// why this exists: it hides the union-narrowing guard inside the library instead of every call site.
-import { isTabNavigatorHandle } from '../../core/index.js';
-import { useNavigation } from './use-navigation.js';
-export function useTabNavigation() {
-    const navigation = useNavigation();
-    if (!isTabNavigatorHandle(navigation)) {
-        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 navigation;
-}

package/build/react/index.d.ts

@@ -1,24 +0,0 @@
-import '../register';
-export { Stack } from './stack';
-export type { INavigatorHandle, IStackProps } from './stack';
-export { Screen } from './screen';
-export type { IScreenOptionsArgs, IScreenOptionsResolver, IScreenProps } from './screen';
-export type { IScreenOptions, IStackAnimation, IStackPresentation } from '../core';
-export { useNavigation, useRoute, useIsFocused, useFocusEffect, useNavigationState } from './hooks';
-export type { INavigationHandle } from './hooks';
-export { useStackNavigation, useTabNavigation, useDrawerNavigation } from './hooks';
-export type { IStackNavigationHandle, ITabNavigationHandle, IDrawerNavigationHandle, } from './hooks';
-export { NavigationContext } from './navigation-context';
-export type { INavigationContextValue, IAnyNavigatorHandle } from './navigation-context';
-export { useLinkingIntegration } from './linking';
-export type { ILinkingConfig, IScreenLinkingConfig } from '../core';
-export { Tab } from './tabs';
-export type { ITabNavigatorHandle, ITabProps } from './tabs';
-export { TabScreen } from './tab-screen';
-export type { ITabScreenOptionsArgs, ITabScreenOptionsResolver, ITabScreenProps, } from './tab-screen';
-export type { ITabOptions, ITabBarIcon } from '../core';
-export { Drawer } from './drawer';
-export type { IDrawerNavigatorHandle, IDrawerProps, IDrawerDescriptorMap } from './drawer';
-export { DrawerScreen } from './drawer-screen';
-export type { IDrawerScreenOptionsArgs, IDrawerScreenOptionsResolver, IDrawerScreenProps, } from './drawer-screen';
-export type { IDrawerOptions, IDrawerScreenOptions, IDrawerType, IDrawerPosition } from '../core';

package/build/react/index.js

@@ -1,21 +0,0 @@
-// @symbiote-native/navigation/react: the React native-stack navigator over react-native-screens'
-// native view primitives. Importing this barrel first registers the native views' ViewConfigs
-// (../register, a side-effect import of the three codegen specs - never react-native-screens' own
-// React components), then exposes Stack (with Stack.Screen attached) and the navigator handle.
-import '../register';
-export { Stack } from './stack/index.js';
-export { Screen } from './screen.js';
-export { useNavigation, useRoute, useIsFocused, useFocusEffect, useNavigationState } from './hooks/index.js';
-export { useStackNavigation, useTabNavigation, useDrawerNavigation } from './hooks/index.js';
-export { NavigationContext } from './navigation-context.js';
-export { useLinkingIntegration } from './linking.js';
-// Tab: the bottom-tabs navigator, a PURE-JS UI (no react-native-screens views involved, so no
-// extra ViewConfig registration is needed beyond the ../register import above).
-export { Tab } from './tabs/index.js';
-export { TabScreen } from './tab-screen.js';
-// Drawer: the swipeable drawer navigator, a PURE-JS UI (PanResponder + Animated, no
-// react-native-screens views involved, so no extra ViewConfig registration is needed beyond the
-// ../register import above). See react/drawer.ts's header for the feasibility note re:
-// react-native-gesture-handler / react-native-reanimated parity gaps.
-export { Drawer } from './drawer/index.js';
-export { DrawerScreen } from './drawer-screen.js';

package/build/react/linking.d.ts

@@ -1,3 +0,0 @@
-import type { ILinkingConfig } from '../core';
-import type { INavigatorHandle } from '../core';
-export declare function useLinkingIntegration(config: ILinkingConfig, navigatorHandle: INavigatorHandle): void;

package/build/react/linking.js

@@ -1,47 +0,0 @@
-// useLinkingIntegration: wires the framework-agnostic linking config (../core's
-// resolveRouteFromUrl) onto an existing Stack ref's INavigatorHandle. Deliberately NOT called
-// from inside stack.ts - app code owns the wiring (a <Stack ref={...}> plus this hook alongside
-// it), the same top-level-prop shape @react-navigation keeps `linking` in on NavigationContainer
-// rather than baking it into the router itself.
-import { useEffect, useRef } from 'react';
-import { Linking, dlog } from '@symbiote-native/engine';
-import { resolveRouteFromUrl } from '../core/index.js';
-export function useLinkingIntegration(config, navigatorHandle) {
-    // Refs, not effect deps: `navigatorHandle` is re-created by Stack on every push/pop
-    // (see stack.ts's useMemo deps including `state.routes.length`), so depending on it directly
-    // would resubscribe on every navigation instead of once on mount.
-    const configRef = useRef(config);
-    configRef.current = config;
-    const handleRef = useRef(navigatorHandle);
-    handleRef.current = navigatorHandle;
-    useEffect(() => {
-        function applyRoute(url, dispatch) {
-            const route = resolveRouteFromUrl(configRef.current, url);
-            if (route === null) {
-                dlog(`useLinkingIntegration: no route resolved for "${url}"`);
-                return;
-            }
-            dispatch(route.name, route.params);
-        }
-        let cancelled = false;
-        Linking.getInitialURL()
-            .then(url => {
-            if (cancelled || url === null)
-                return;
-            dlog(`useLinkingIntegration: initial URL "${url}"`);
-            applyRoute(url, handleRef.current.replace);
-        })
-            .catch((error) => {
-            dlog(`useLinkingIntegration: getInitialURL failed: ${String(error)}`);
-        });
-        const subscription = Linking.addEventListener('url', (event) => {
-            dlog(`useLinkingIntegration: url event "${event.url}"`);
-            applyRoute(event.url, handleRef.current.push);
-        });
-        return () => {
-            cancelled = true;
-            subscription.remove();
-        };
-        // Mount-once: freshness of config/navigatorHandle is read through the refs above.
-    }, []);
-}

package/build/react/navigation-context.d.ts

@@ -1,10 +0,0 @@
-import type { INavigationEmitter, IRoute, IAnyNavigatorHandle } from '../core';
-export type { IAnyNavigatorHandle } from '../core';
-export type INavigationContextValue = {
-    route: IRoute<unknown>;
-    navigation: IAnyNavigatorHandle;
-    emitter: INavigationEmitter;
-    parent?: INavigationContextValue;
-};
-export declare const NavigationContext: import("react").Context<INavigationContextValue | undefined>;
-export declare function useRequiredNavigationContext(hookName: string): INavigationContextValue;

package/build/react/navigation-context.js

@@ -1,22 +0,0 @@
-// The lifecycle half of the framework-agnostic emitter (../core/navigation-events): a plain
-// React Context so a screen's subtree can read its own route, navigator handle, and per-route
-// emitter without prop-drilling - the same role @react-navigation's NavigationContext /
-// NavigationRouteContext play, collapsed into one context since a symbiote screen only ever needs
-// its OWN route (no per-navigator param-list generics in v1 scope - see screen.ts). Provided
-// per-screen by each of stack.ts/tabs.ts/drawer.ts's render loop, consumed by the hooks in
-// ./hooks. `parent` threads the ambient context 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 { createContext, useContext } from 'react';
-export const NavigationContext = createContext(undefined);
-// Every hook in ./hooks needs the same `useContext(NavigationContext)` + missing-provider throw,
-// so it's co-located here instead of repeated per hook. `hookName` keeps each hook's own name in
-// the thrown message.
-export function useRequiredNavigationContext(hookName) {
-    const context = useContext(NavigationContext);
-    if (!context) {
-        throw new Error(`${hookName} must be used within a screen rendered by <Stack>, <Tab>, or <Drawer>`);
-    }
-    return context;
-}

package/build/react/screen.d.ts

@@ -1,22 +0,0 @@
-import type { FC, ReactElement, RefObject } from 'react';
-import type { IRoute } from '../core';
-import type { ISearchBarCommands, ISearchBarOptions, IScreenOptions } from '../core';
-import type { INavigatorHandle } from '../core';
-export type IReactSearchBarOptions = ISearchBarOptions & {
-    ref?: RefObject<ISearchBarCommands | null>;
-};
-export type IReactScreenOptions = Omit<IScreenOptions, 'headerSearchBarOptions'> & {
-    headerSearchBarOptions?: IReactSearchBarOptions;
-};
-export type IScreenOptionsArgs = {
-    route: IRoute<unknown>;
-    navigation: INavigatorHandle;
-};
-export type IScreenOptionsResolver = (args: IScreenOptionsArgs) => IReactScreenOptions;
-export type IScreenProps = {
-    name: string;
-    component: FC;
-    options?: IReactScreenOptions | IScreenOptionsResolver;
-    initialParams?: unknown;
-};
-export declare function Screen(_props: IScreenProps): ReactElement | null;

package/build/react/screen.js

@@ -1,7 +0,0 @@
-// Stack.Screen: a declarative marker, never rendered on its own - Stack reads its props via
-// React.Children to build the static name -> {component, options} registry, then mounts the
-// registered component itself for each pushed route. Mirrors @react-navigation's JSX-config
-// screens, minus the linking/param-list generics (v1 scope).
-export function Screen(_props) {
-    return null;
-}

package/build/react/stack/index.d.ts

@@ -1,13 +0,0 @@
-import type { ReactNode } from 'react';
-import type { INavigatorHandle } from '../../core';
-import { Screen } from '../screen';
-import type { IReactScreenOptions } from '../screen';
-export type { INavigatorHandle } from '../../core';
-export type IStackProps = {
-    initialRouteName?: string;
-    screenOptions?: IReactScreenOptions;
-    children?: ReactNode;
-};
-export declare const Stack: import("react").ForwardRefExoticComponent<IStackProps & import("react").RefAttributes<INavigatorHandle>> & {
-    Screen: typeof Screen;
-};