@symbiote-native/navigation 1.0.0

package/build/core/navigator-props.d.ts

@@ -0,0 +1,216 @@
+import type { IColorValue, ISymbioteEvent } from '@symbiote-native/engine';
+import type { IImageSourceProp } from '@symbiote-native/components';
+export type IStackAnimation = 'default' | 'flip' | 'simple_push' | 'none' | 'fade' | 'slide_from_right' | 'slide_from_left' | 'slide_from_bottom' | 'fade_from_bottom' | 'ios_from_right' | 'ios_from_left';
+export type IStackPresentation = 'push' | 'modal' | 'transparentModal' | 'fullScreenModal' | 'formSheet' | 'pageSheet' | 'containedModal' | 'containedTransparentModal';
+export type IHeaderBackButtonDisplayMode = 'minimal' | 'default' | 'generic';
+export type IHeaderUserInterfaceStyle = 'unspecified' | 'light' | 'dark';
+export type IOptionalBooleanNativeProp = 'undefined' | 'false' | 'true';
+export type ISheetAllowedDetents = number[] | 'fitToContents' | 'large' | 'medium' | 'all';
+export type ISheetLargestUndimmedDetent = number | 'last' | 'none' | 'all' | 'large' | 'medium';
+export type ISheetInitialDetent = number | 'last';
+export type IHeaderBarButtonIcon = {
+    type: 'sfSymbol';
+    name: string;
+} | {
+    type: 'xcasset';
+    name: string;
+} | {
+    type: 'imageSource';
+    imageSource: IImageSourceProp;
+} | {
+    type: 'templateSource';
+    templateSource: IImageSourceProp;
+};
+export type IHeaderBarButtonItemBadge = {
+    value: string;
+    style?: {
+        color?: IColorValue;
+        backgroundColor?: IColorValue;
+        fontFamily?: string;
+        fontSize?: number;
+        fontWeight?: string;
+    };
+};
+type ISharedHeaderBarButtonItem = {
+    index?: number;
+    title?: string;
+    titleStyle?: {
+        fontFamily?: string;
+        fontSize?: number;
+        fontWeight?: string;
+        color?: IColorValue;
+    };
+    icon?: IHeaderBarButtonIcon;
+    variant?: 'plain' | 'done' | 'prominent';
+    tintColor?: IColorValue;
+    disabled?: boolean;
+    width?: number;
+    hidesSharedBackground?: boolean;
+    sharesBackground?: boolean;
+    identifier?: string;
+    badge?: IHeaderBarButtonItemBadge;
+    accessibilityLabel?: string;
+    accessibilityHint?: string;
+};
+export type IHeaderBarButtonItemAction = ISharedHeaderBarButtonItem & {
+    type: 'button';
+    onPress: () => void;
+    selected?: boolean;
+};
+export type IHeaderBarButtonMenuAction = {
+    type: 'action';
+    title?: string;
+    subtitle?: string;
+    onPress: () => void;
+    icon?: IHeaderBarButtonIcon;
+    state?: 'on' | 'off' | 'mixed';
+    disabled?: boolean;
+    destructive?: boolean;
+    hidden?: boolean;
+    keepsMenuPresented?: boolean;
+    discoverabilityLabel?: string;
+};
+export type IHeaderBarButtonSubmenu = {
+    type: 'submenu';
+    title?: string;
+    icon?: IHeaderBarButtonIcon;
+    items: (IHeaderBarButtonMenuAction | IHeaderBarButtonSubmenu)[];
+    displayInline?: boolean;
+    destructive?: boolean;
+    singleSelection?: boolean;
+    displayAsPalette?: boolean;
+};
+export type IHeaderBarButtonItemMenu = ISharedHeaderBarButtonItem & {
+    type: 'menu';
+    menu: {
+        title?: string;
+        items: (IHeaderBarButtonMenuAction | IHeaderBarButtonSubmenu)[];
+        singleSelection?: boolean;
+        displayAsPalette?: boolean;
+    };
+    changesSelectionAsPrimaryAction?: boolean;
+};
+export type IHeaderBarButtonItemSpacing = {
+    type: 'spacing';
+    spacing: number;
+};
+export type IHeaderBarButtonItem = IHeaderBarButtonItemAction | IHeaderBarButtonItemMenu | IHeaderBarButtonItemSpacing;
+export type ISearchBarAutoCapitalize = 'systemDefault' | 'none' | 'words' | 'sentences' | 'characters';
+export type ISearchBarPlacement = 'automatic' | 'inline' | 'stacked' | 'integrated' | 'integratedButton' | 'integratedCentered';
+export type ISearchBarOptions = {
+    placeholder?: string;
+    autoCapitalize?: ISearchBarAutoCapitalize;
+    placement?: ISearchBarPlacement;
+    hideWhenScrolling?: boolean;
+    allowToolbarIntegration?: boolean;
+    obscureBackground?: boolean;
+    hideNavigationBar?: boolean;
+    cancelButtonText?: string;
+    barTintColor?: IColorValue;
+    tintColor?: IColorValue;
+    textColor?: IColorValue;
+    autoFocus?: boolean;
+    disableBackButtonOverride?: boolean;
+    inputType?: string;
+    hintTextColor?: IColorValue;
+    headerIconColor?: IColorValue;
+    shouldShowHintSearchIcon?: boolean;
+    onChangeText?: (text: string) => void;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    onCancelButtonPress?: () => void;
+    onSearchButtonPress?: (text: string) => void;
+    onClose?: () => void;
+    onOpen?: () => void;
+};
+export type IScreenOrientation = 'default' | 'all' | 'portrait' | 'portrait_up' | 'portrait_down' | 'landscape' | 'landscape_left' | 'landscape_right';
+export interface IScreenOptions {
+    title?: string;
+    headerShown?: boolean;
+    headerTitleColor?: IColorValue;
+    headerStyle?: {
+        backgroundColor?: IColorValue;
+    };
+    headerTintColor?: IColorValue;
+    headerBackTitle?: string;
+    headerBackButtonDisplayMode?: IHeaderBackButtonDisplayMode;
+    headerLargeTitle?: boolean;
+    headerLargeStyle?: {
+        backgroundColor?: IColorValue;
+    };
+    headerUserInterfaceStyle?: IHeaderUserInterfaceStyle;
+    headerTranslucent?: boolean;
+    headerLeftBarButtonItems?: IHeaderBarButtonItem[];
+    headerRightBarButtonItems?: IHeaderBarButtonItem[];
+    headerSearchBarOptions?: ISearchBarOptions;
+    gestureEnabled?: boolean;
+    stackAnimation?: IStackAnimation;
+    stackPresentation?: IStackPresentation;
+    transitionDuration?: number;
+    sheetAllowedDetents?: ISheetAllowedDetents;
+    sheetLargestUndimmedDetentIndex?: ISheetLargestUndimmedDetent;
+    sheetInitialDetentIndex?: ISheetInitialDetent;
+    sheetGrabberVisible?: boolean;
+    sheetCornerRadius?: number;
+    sheetExpandsWhenScrolledToEdge?: boolean;
+    sheetElevation?: number;
+    sheetShouldOverflowTopInset?: boolean;
+    sheetDefaultResizeAnimationEnabled?: boolean;
+    statusBarStyle?: 'inverted' | 'auto' | 'light' | 'dark';
+    statusBarHidden?: boolean;
+    statusBarAnimation?: 'none' | 'fade' | 'slide';
+    screenOrientation?: IScreenOrientation;
+}
+export type INavigatorPlatform = {
+    defaultHeaderBackTitleVisible: boolean;
+};
+export type IScreenViewProps = {
+    screenId: string;
+    activityState: number;
+    gestureEnabled?: boolean;
+    stackAnimation?: IStackAnimation;
+    stackPresentation?: IStackPresentation;
+    transitionDuration?: number;
+    sheetAllowedDetents?: number[];
+    sheetLargestUndimmedDetent?: number;
+    sheetInitialDetent?: number;
+    sheetGrabberVisible?: boolean;
+    sheetCornerRadius?: number;
+    sheetExpandsWhenScrolledToEdge?: boolean;
+    sheetElevation?: number;
+    sheetShouldOverflowTopInset?: boolean;
+    sheetDefaultResizeAnimationEnabled?: boolean;
+    statusBarStyle?: 'inverted' | 'auto' | 'light' | 'dark';
+    statusBarHidden?: boolean;
+    statusBarAnimation?: 'none' | 'fade' | 'slide';
+    screenOrientation?: IScreenOrientation;
+    passthrough: Record<string, unknown>;
+};
+export type IHeaderConfigViewProps = {
+    title?: string;
+    hidden: boolean;
+    backTitle?: string;
+    backTitleVisible: boolean;
+    backButtonDisplayMode?: IHeaderBackButtonDisplayMode;
+    largeTitle?: boolean;
+    translucent?: boolean;
+    color?: IColorValue;
+    titleColor?: IColorValue;
+    backgroundColor?: IColorValue;
+    largeTitleBackgroundColor?: IColorValue;
+    userInterfaceStyle?: IHeaderUserInterfaceStyle;
+    headerLeftBarButtonItems?: unknown[];
+    headerRightBarButtonItems?: unknown[];
+    onPressHeaderBarButtonItem?: (event: ISymbioteEvent) => void;
+    onPressHeaderBarButtonMenuItem?: (event: ISymbioteEvent) => void;
+    passthrough: Record<string, unknown>;
+};
+export type IStackViewProps = {
+    passthrough: Record<string, unknown>;
+};
+export type ISearchBarViewProps = Omit<ISearchBarOptions, 'obscureBackground' | 'hideNavigationBar' | 'onChangeText' | 'onFocus' | 'onBlur' | 'onCancelButtonPress' | 'onSearchButtonPress' | 'onClose' | 'onOpen'> & {
+    obscureBackground?: IOptionalBooleanNativeProp;
+    hideNavigationBar?: IOptionalBooleanNativeProp;
+    passthrough: Record<string, unknown>;
+};
+export {};

package/build/core/navigator-props.js

@@ -0,0 +1,7 @@
+// Navigator prop types. Per CLAUDE.md <prop_types_split_agnostic_vs_per_adapter>: screen
+// options (title, header styling, transition/presentation) are entirely scalar/color-typed, so
+// they live here as the shared agnostic base every adapter re-exports. The Stack/Screen PUBLIC
+// component props are NOT here - they carry framework children (the screen content) and a
+// framework ref (the navigator handle), so each adapter declares its own flavored type over
+// this base, same split as IPressableProps.
+export {};

package/build/core/navigator-state/index.d.ts

@@ -0,0 +1,36 @@
+export type IRoute<TParams = undefined> = Readonly<{
+    key: string;
+    name: string;
+    params: TParams;
+}>;
+type IRouteEntry = IRoute<unknown>;
+export type INavigatorState = Readonly<{
+    routes: readonly IRouteEntry[];
+}>;
+export type INavigatorAction = {
+    type: 'push';
+    route: IRouteEntry;
+} | {
+    type: 'pop';
+    count?: number;
+} | {
+    type: 'popToTop';
+} | {
+    type: 'popTo';
+    key: string;
+} | {
+    type: 'replace';
+    route: IRouteEntry;
+} | {
+    type: 'setParams';
+    key?: string;
+    params: unknown;
+} | {
+    type: 'reset';
+    state: INavigatorState;
+};
+export declare function createInitialNavigatorState(initialRoute: IRouteEntry): INavigatorState;
+export declare function navigatorReducer(state: INavigatorState, action: INavigatorAction): INavigatorState;
+export declare function computeActivityState(index: number, routesLength: number): number;
+export declare function isTopRoute(index: number, routesLength: number): boolean;
+export {};

package/build/core/navigator-state/index.js

@@ -0,0 +1,81 @@
+// Navigator: the logic half (framework-agnostic, zero render). A pure reducer over a route
+// stack - push/pop/popToTop/popTo/replace - mirroring what @react-navigation/native-stack keeps
+// in its router, minus the React-specific action-creator/linking machinery. Route identity
+// (`key`) is generated by the CALLER (the adapter, via React's useId or an equivalent) - the
+// reducer never invents identity itself, so it stays a pure (state, action) => state function.
+import { SCREEN_ACTIVITY_STATE_FOCUSED, SCREEN_ACTIVITY_STATE_INACTIVE } from '../constants.js';
+import { mergeParams } from '../guards.js';
+export function createInitialNavigatorState(initialRoute) {
+    return { routes: [initialRoute] };
+}
+// The stack never pops its last route - mirrors the library refusing to pop the initial screen;
+// the caller (e.g. a hardware back handler) decides what a pop-at-root means for the host app.
+export function navigatorReducer(state, action) {
+    switch (action.type) {
+        case 'push':
+            return { routes: [...state.routes, action.route] };
+        case 'pop': {
+            if (state.routes.length <= 1)
+                return state;
+            const count = action.count ?? 1;
+            const nextLength = Math.max(1, state.routes.length - count);
+            return { routes: state.routes.slice(0, nextLength) };
+        }
+        case 'popToTop':
+            return state.routes.length <= 1 ? state : { routes: state.routes.slice(0, 1) };
+        case 'popTo': {
+            const index = state.routes.findIndex(route => route.key === action.key);
+            if (index === -1)
+                return state;
+            return { routes: state.routes.slice(0, index + 1) };
+        }
+        case 'replace': {
+            if (state.routes.length === 0)
+                return { routes: [action.route] };
+            return { routes: [...state.routes.slice(0, -1), action.route] };
+        }
+        // Mirrors @react-navigation's CommonActions.setParams: merges onto the route matched by
+        // `key`, defaulting to the focused (top-of-stack) route when omitted - same shape as its
+        // `source`-defaults-to-focused-route behavior, minus the cross-navigator target routing this
+        // single-navigator reducer has no need for.
+        case 'setParams': {
+            const targetKey = action.key ?? state.routes[state.routes.length - 1]?.key;
+            if (targetKey === undefined)
+                return state;
+            const index = state.routes.findIndex(route => route.key === targetKey);
+            if (index === -1)
+                return state;
+            const target = state.routes[index];
+            const nextRoute = {
+                ...target,
+                params: mergeParams(target.params, action.params),
+            };
+            return {
+                routes: [...state.routes.slice(0, index), nextRoute, ...state.routes.slice(index + 1)],
+            };
+        }
+        // Mirrors @react-navigation's CommonActions.reset / BaseRouter's RESET handler: the payload
+        // state replaces the current one verbatim, no merge - full rehydration (e.g. restoring a
+        // persisted stack) is just a reset with the deserialized state as the payload.
+        case 'reset':
+            return action.state;
+        default:
+            return state;
+    }
+}
+// Mirrors @react-navigation/native-stack's actual algorithm (NativeStackView.native.tsx:
+// `activityState={isInactive ? 0 : 2}`, where isInactive = index > state.index) - NOT a
+// three-way top/one-below/rest split. A route index beyond the focused one only exists for a
+// preloaded-but-not-yet-navigated-to screen, a feature this reducer doesn't implement, so the
+// focused index is always routesLength - 1 (the last route) and every currently-mounted route is
+// FOCUSED. This is required, not just simpler: react-native-screens' native RNSScreen.mm asserts
+// an already-mounted NativeStack screen's activityState can never decrease via a plain prop
+// update ("activityState can only progress in NativeStack") - since no mounted route's index ever
+// exceeds routesLength - 1, this formula never produces a decrease across a push or pop.
+export function computeActivityState(index, routesLength) {
+    const focusedIndex = routesLength - 1;
+    return index > focusedIndex ? SCREEN_ACTIVITY_STATE_INACTIVE : SCREEN_ACTIVITY_STATE_FOCUSED;
+}
+export function isTopRoute(index, routesLength) {
+    return index === routesLength - 1;
+}

package/build/core/render-drawer.d.ts

@@ -0,0 +1,13 @@
+import { type IDescriptor } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '@symbiote-native/engine';
+import { type IDrawerOptions } from './drawer-options';
+export type IDrawerSlot = 'content' | 'overlay' | 'panel';
+export declare function drawerChildOrder(options: IDrawerOptions): readonly IDrawerSlot[];
+export type IDrawerViewProps = {
+    overlayColor?: string;
+    drawerStyle?: IStyleProp<IViewStyle>;
+    contentPassthrough: Record<string, unknown>;
+    overlayPassthrough: Record<string, unknown>;
+    panelPassthrough: Record<string, unknown>;
+};
+export declare function renderDrawer(view: IDrawerViewProps, options: IDrawerOptions): IDescriptor;

package/build/core/render-drawer.js

@@ -0,0 +1,88 @@
+// Drawer: the render half (framework-agnostic). Like render-stack.ts's screen content, both the
+// drawer panel's content (renderDrawerContent) and the wrapped screen content are arbitrary
+// framework subtrees the adapter owns - so, mirroring render-modal.ts's container-slot precedent,
+// renderDrawer hands back one root Descriptor whose structural children are EMPTY placeholder
+// nodes (`content` / `overlay?` / `panel`) that the adapter fills with real framework children.
+// Paint order (and therefore which slot is present) is drawerType-dependent, so `drawerChildOrder`
+// is exported alongside renderDrawer as the single source of truth the adapter zips its own
+// children against - no adapter re-derives the ordering itself.
+//
+// All positioning here is STATIC (position/top/bottom/side/width) - the animated slide transform
+// and overlay opacity are NOT baked into this Descriptor. They are computed once per drawerType
+// via drawer-options.ts's resolveDrawerGeometry() and then driven per-frame by the adapter's own
+// Animated value (Animated.View), because "how to animate a style" is a framework-lifecycle
+// concern (React: Animated.View; a future Vue adapter: a reactive style binding) - see
+// CLAUDE.md <adapters_stay_thin>.
+import { el } from '@symbiote-native/components';
+import { isDrawerOverlayVisible, resolveDrawerPosition, resolveDrawerType, resolveDrawerWidth, } from './drawer-options/index.js';
+// front: content, overlay (dims it), panel (paints on top, last-sibling-on-top).
+// back: panel (stationary, behind), content (slides away to reveal it) - no overlay. Both are
+// absolutely positioned, so sibling order here only decides z-stacking, not screen side.
+// slide: panel, overlay, content (both panel and content animate; content stays visually on top).
+// permanent: NOT absolutely positioned (an ordinary flexDirection:'row' sidebar), so sibling
+// order IS the left-to-right screen position - it must follow drawerPosition.
+export function drawerChildOrder(options) {
+    const type = resolveDrawerType(options);
+    switch (type) {
+        case 'back':
+            return ['panel', 'content'];
+        case 'slide':
+            return ['panel', 'overlay', 'content'];
+        case 'permanent':
+            return resolveDrawerPosition(options) === 'left'
+                ? ['panel', 'content']
+                : ['content', 'panel'];
+        case 'front':
+        default:
+            return ['content', 'overlay', 'panel'];
+    }
+}
+const ROOT_STYLE = { flex: 1 };
+const CONTENT_STYLE = { flex: 1 };
+// Fabric paints later siblings on top; position:absolute + inset:0 is enough for the overlay
+// (its own sibling order, not zIndex, decides whether it sits above the content).
+const OVERLAY_BASE_STYLE = {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+};
+const DRAWER_PANEL_DEFAULT_BACKGROUND_COLOR = 'white';
+function panelBaseStyle(options) {
+    const type = resolveDrawerType(options);
+    const width = resolveDrawerWidth(options);
+    const side = resolveDrawerPosition(options);
+    if (type === 'permanent') {
+        // A sidebar: an ordinary flex child, no absolute positioning, no translate needed.
+        return { width, backgroundColor: DRAWER_PANEL_DEFAULT_BACKGROUND_COLOR };
+    }
+    return {
+        position: 'absolute',
+        top: 0,
+        bottom: 0,
+        width,
+        backgroundColor: DRAWER_PANEL_DEFAULT_BACKGROUND_COLOR,
+        [side]: 0,
+    };
+}
+export function renderDrawer(view, options) {
+    const type = resolveDrawerType(options);
+    const content = el('symbiote-view', { ...view.contentPassthrough, style: CONTENT_STYLE }, []);
+    const panel = el('symbiote-view', { ...view.panelPassthrough, style: [panelBaseStyle(options), view.drawerStyle] }, []);
+    const slots = { content, panel };
+    if (isDrawerOverlayVisible(options)) {
+        slots.overlay = el('symbiote-view', {
+            ...view.overlayPassthrough,
+            style: [OVERLAY_BASE_STYLE, { backgroundColor: view.overlayColor }],
+        }, []);
+    }
+    const children = drawerChildOrder(options).reduce((acc, slot) => {
+        const descriptor = slots[slot];
+        if (descriptor !== undefined)
+            acc.push(descriptor);
+        return acc;
+    }, []);
+    const rootStyle = type === 'permanent' ? { ...ROOT_STYLE, flexDirection: 'row' } : ROOT_STYLE;
+    return el('symbiote-view', { style: rootStyle }, children);
+}

package/build/core/render-stack.d.ts

@@ -0,0 +1,35 @@
+import type { IDescriptor } from '@symbiote-native/components';
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import type { IHeaderConfigViewProps, INavigatorPlatform, IScreenOptions, IScreenViewProps, ISearchBarOptions, ISearchBarViewProps, IStackPresentation, IStackViewProps } from './navigator-props';
+export declare function resolveScreenViewName(stackPresentation: IStackPresentation | undefined, isAndroid: boolean): string;
+export declare function resolveScreenContentWrapperStyle(stackPresentation: IStackPresentation | undefined, headerHidden: boolean, headerTranslucent: boolean | undefined, isAndroid: boolean): Record<string, unknown>;
+export declare function isHeaderInModal(stackPresentation: IStackPresentation | undefined, headerHidden: boolean, isAndroid: boolean): boolean;
+export declare function resolveHeaderInModalStackStyle(): Record<string, unknown>;
+export declare function resolveHeaderInModalScreenStyle(): Record<string, unknown>;
+export declare function resolveScreenProps(view: IScreenViewProps): Record<string, unknown>;
+export declare function resolveStackProps(view: IStackViewProps): Record<string, unknown>;
+export declare function renderHeaderConfig(view: IHeaderConfigViewProps, searchBarProps?: Record<string, unknown>): IDescriptor;
+export declare function resolveSearchBarProps(view: ISearchBarViewProps): Record<string, unknown>;
+export declare function buildSearchBarPassthrough(options: ISearchBarOptions, log?: (message: string) => void): Record<string, (event: ISymbioteEvent) => void>;
+export type IScreenRenderPlanInput = {
+    screenId: string;
+    index: number;
+    routeCount: number;
+    options: IScreenOptions | undefined;
+    platform: INavigatorPlatform;
+    isAndroid: boolean;
+    screenPassthrough: Record<string, unknown>;
+    searchBarPassthrough?: Record<string, unknown>;
+};
+export type IScreenRenderPlan = {
+    activityState: number;
+    screenViewName: string;
+    screenProps: Record<string, unknown>;
+    headerConfig: IDescriptor;
+    searchBarProps: Record<string, unknown> | undefined;
+    contentWrapperProps: Record<string, unknown>;
+    inModal: boolean;
+    innerStackStyle: Record<string, unknown>;
+    innerScreenStyle: Record<string, unknown>;
+};
+export declare function resolveScreenRenderPlan(input: IScreenRenderPlanInput): IScreenRenderPlan;