@ankhorage/contracts 10.1.0 → 11.0.0

package/src/navigator-validation.test.ts

@@ -0,0 +1,153 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'bun:test';
+
+import { isAppNavigatorManifest } from './appManifest/screens';
+import type {
+  CustomNavigatorNode,
+  CustomTabsConfig,
+  NavigatorNode,
+  StackImplementationConfig,
+} from './navigator';
+
+describe('app navigator manifest type discrimination', () => {
+  it('prevents incompatible options and non-serializable configuration at compile time', () => {
+    // @ts-expect-error Slot does not own an arbitrary options bag.
+    const slot: NavigatorNode = { type: 'slot', options: { arbitrary: true }, routes: [] };
+    // @ts-expect-error Experimental Stack has no presentation options.
+    const experimental: StackImplementationConfig = {
+      implementation: 'experimental',
+      options: { presentation: 'modal' },
+    };
+    // @ts-expect-error Fixed custom tabs do not accept a registered custom presentation id.
+    const tabs: CustomTabsConfig = {
+      implementation: 'custom',
+      presentation: 'sidebar',
+      customPresentationId: 'workspace-tabs',
+    };
+    // @ts-expect-error Custom navigator configuration must be serializable manifest values.
+    const custom: CustomNavigatorNode = {
+      type: 'custom',
+      navigatorId: 'workspace',
+      config: { callback: () => undefined },
+      routes: [],
+    };
+
+    expect([slot, experimental, tabs, custom]).toHaveLength(4);
+  });
+});
+
+describe('app navigator manifest stack validation', () => {
+  it('rejects the removed untyped options bag and unsupported stack branch fields', () => {
+    expect(isAppNavigatorManifest({ type: 'slot', options: { arbitrary: true }, routes: [] })).toBe(
+      false,
+    );
+    expect(
+      isAppNavigatorManifest({
+        type: 'stack',
+        implementation: 'experimental',
+        options: { presentation: 'modal' },
+        routes: [],
+      }),
+    ).toBe(false);
+    expect(
+      isAppNavigatorManifest({
+        type: 'stack',
+        implementation: 'javascript',
+        options: { presentation: 'formSheet' },
+        routes: [],
+      }),
+    ).toBe(false);
+    expect(
+      isAppNavigatorManifest({
+        type: 'stack',
+        implementation: 'native',
+        minimizeBehavior: 'never',
+        routes: [],
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('app navigator manifest sheet validation', () => {
+  it('validates native form-sheet detents and their presentation discriminant', () => {
+    for (const sheetAllowedDetents of [[], [0.8, 0.4], [0.4, 0.4], [0], [1.1], [Number.NaN]]) {
+      expect(
+        isAppNavigatorManifest({
+          type: 'stack',
+          options: { presentation: 'formSheet', sheetAllowedDetents },
+          routes: [],
+        }),
+      ).toBe(false);
+    }
+    expect(
+      isAppNavigatorManifest({
+        type: 'stack',
+        options: { presentation: 'modal', sheetGrabberVisible: true },
+        routes: [],
+      }),
+    ).toBe(false);
+    expect(
+      isAppNavigatorManifest({
+        type: 'stack',
+        routes: [
+          {
+            name: 'compose',
+            stackOptions: {
+              presentation: 'formSheet',
+              sheetAllowedDetents: 'fitToContents',
+            },
+          },
+        ],
+      }),
+    ).toBe(true);
+  });
+});
+
+describe('app navigator manifest custom validation', () => {
+  it('rejects non-JSON and cyclic custom navigator configuration', () => {
+    const cyclicConfig: Record<string, unknown> = {};
+    cyclicConfig.self = cyclicConfig;
+
+    for (const invalidConfig of [
+      { callback: () => undefined },
+      { token: Symbol('token') },
+      { count: Number.NaN },
+      { count: Number.POSITIVE_INFINITY },
+      cyclicConfig,
+    ]) {
+      expect(
+        isAppNavigatorManifest({
+          type: 'custom',
+          navigatorId: 'workspace',
+          config: invalidConfig,
+          routes: [],
+        }),
+      ).toBe(false);
+    }
+  });
+
+  it('rejects incomplete Split View bindings', () => {
+    expect(
+      isAppNavigatorManifest({
+        type: 'split-view',
+        columns: {},
+        routes: [],
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('app navigator manifest package boundary', () => {
+  it('publishes the focused navigator contract subpath', async () => {
+    const packageJson = JSON.parse(await readFile(join(process.cwd(), 'package.json'), 'utf8')) as {
+      exports?: Record<string, { default?: string; types?: string }>;
+    };
+
+    expect(packageJson.exports?.['./navigator']).toEqual({
+      types: './dist/navigator.d.ts',
+      default: './dist/navigator.js',
+    });
+  });
+});

package/src/navigator.test.ts

@@ -1,12 +1,12 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-
 import { describe, expect, it } from 'bun:test';
 
 import { isAppNavigatorManifest } from './appManifest/screens';
 import {
   type AppNavigatorManifest,
   NAVIGATOR_PRESETS,
+  NAVIGATOR_TYPES,
+  type NavigatorNode,
+  type StackImplementationConfig,
   type TabsNavigatorConfig,
 } from './navigator';
 
@@ -28,8 +28,66 @@ function createAdaptiveTabs(): AppNavigatorManifest {
   };
 }
 
+const VALID_NAVIGATOR_NODES = [
+  { type: 'slot', routes: [] },
+  {
+    type: 'stack',
+    implementation: 'native',
+    options: {
+      presentation: 'formSheet',
+      sheetAllowedDetents: [0.4, 0.8],
+      sheetGrabberVisible: true,
+    },
+    routes: [],
+  },
+  {
+    type: 'stack',
+    implementation: 'javascript',
+    options: { presentation: 'transparentModal', headerShown: false },
+    routes: [],
+  },
+  {
+    type: 'stack',
+    implementation: 'experimental',
+    options: { title: 'Profile', headerTransparent: true },
+    routes: [],
+  },
+  {
+    type: 'tabs',
+    implementation: 'native',
+    minimizeBehavior: 'onScrollDown',
+    bottomAccessory: { screenId: 'now-playing' },
+    routes: [],
+  },
+  {
+    type: 'drawer',
+    options: { drawerPosition: 'right', drawerType: 'permanent', swipeEnabled: false },
+    routes: [],
+  },
+  {
+    type: 'split-view',
+    columns: {
+      primary: { screenId: 'sidebar' },
+      supplementary: { screenId: 'inspector-list' },
+    },
+    inspector: { screenId: 'inspector' },
+    topColumnForCollapsing: 'secondary',
+    routes: [{ name: 'detail', screenId: 'detail' }],
+  },
+  {
+    type: 'custom',
+    navigatorId: 'workspace',
+    config: { animation: 'spring', thresholds: [0.25, 0.75], enabled: true },
+    routes: [],
+  },
+] as const satisfies readonly NavigatorNode[];
+
 describe('app navigator manifest topology', () => {
   it('keeps canonical topology presets finite and authorable', () => {
+    expect(NAVIGATOR_TYPES).toEqual(['slot', 'stack', 'tabs', 'drawer', 'split-view', 'custom']);
+    expect(NAVIGATOR_PRESETS).toContain('slot');
+    expect(NAVIGATOR_PRESETS).toContain('split-view');
+    expect(NAVIGATOR_PRESETS).toContain('custom');
     expect(NAVIGATOR_PRESETS).toContain('root-stack-tabs-stack');
     expect(NAVIGATOR_PRESETS).toContain('root-stack-drawer-tabs-stack');
   });
@@ -69,6 +127,31 @@ describe('app navigator manifest topology', () => {
   });
 });
 
+describe('app navigator manifest node variants', () => {
+  it('accepts every typed navigator node variant', () => {
+    expect(VALID_NAVIGATOR_NODES.every(isAppNavigatorManifest)).toBe(true);
+  });
+
+  it('accepts stack defaults and per-platform implementation overrides', () => {
+    const experimental = {
+      implementation: 'experimental',
+      options: { headerShown: false },
+    } as const satisfies StackImplementationConfig;
+
+    expect(
+      isAppNavigatorManifest({
+        type: 'stack',
+        routes: [],
+        defaults: { stack: { implementation: 'native' } },
+        platforms: {
+          ios: { stack: experimental },
+          web: { stack: { implementation: 'javascript', options: { presentation: 'card' } } },
+        },
+      }),
+    ).toBe(true);
+  });
+});
+
 describe('app navigator manifest custom presentation', () => {
   it('accepts fixed and registered custom Web presentations', () => {
     expect(
@@ -112,6 +195,50 @@ describe('app navigator manifest custom presentation', () => {
   });
 });
 
+describe('app navigator manifest tabs branch validation', () => {
+  it('rejects fields from incompatible tab branches', () => {
+    expect(
+      isAppNavigatorManifest({
+        type: 'tabs',
+        implementation: 'native',
+        presentation: 'bottom',
+        routes: [],
+      }),
+    ).toBe(false);
+
+    expect(
+      isAppNavigatorManifest({
+        type: 'tabs',
+        implementation: 'javascript',
+        presentation: 'bottom',
+        native: { implementation: 'native' },
+        routes: [],
+      }),
+    ).toBe(false);
+
+    expect(
+      isAppNavigatorManifest({
+        type: 'tabs',
+        implementation: 'custom',
+        presentation: 'sidebar',
+        customPresentationId: 'must-not-apply',
+        routes: [],
+      }),
+    ).toBe(false);
+
+    expect(
+      isAppNavigatorManifest({
+        type: 'tabs',
+        implementation: 'custom',
+        presentation: 'custom',
+        customPresentationId: 'workspace-tabs',
+        responsive: { compact: 'bottom', expanded: 'sidebar' },
+        routes: [],
+      }),
+    ).toBe(false);
+  });
+});
+
 describe('app navigator manifest composition', () => {
   it('keeps nested topology separate from app-level flow metadata', () => {
     expect(
@@ -131,14 +258,30 @@ describe('app navigator manifest composition', () => {
     ).toBe(true);
   });
 
-  it('publishes the focused navigator contract subpath', async () => {
-    const packageJson = JSON.parse(await readFile(join(process.cwd(), 'package.json'), 'utf8')) as {
-      exports?: Record<string, { default?: string; types?: string }>;
-    };
+  it('preserves authored route names, labels, paths, guards, and visibility without inference', () => {
+    const navigator = {
+      type: 'stack',
+      routes: [
+        {
+          name: '(app)',
+          label: 'Application',
+          guards: ['authenticated'],
+          showInPrimaryNavigation: false,
+          navigator: {
+            type: 'tabs',
+            routes: [{ name: 'learn', path: '/learn', label: 'Train', screenId: 'learn' }],
+          },
+        },
+      ],
+    } as const satisfies AppNavigatorManifest;
 
-    expect(packageJson.exports?.['./navigator']).toEqual({
-      types: './dist/navigator.d.ts',
-      default: './dist/navigator.js',
+    expect(isAppNavigatorManifest(navigator)).toBe(true);
+    expect(JSON.parse(JSON.stringify(navigator))).toEqual(navigator);
+    expect(navigator.routes[0].navigator.routes[0]).toEqual({
+      name: 'learn',
+      path: '/learn',
+      label: 'Train',
+      screenId: 'learn',
     });
   });
 });

package/src/navigator.ts

@@ -1,9 +1,10 @@
-import type { IconSpec } from './types';
+import type { IconSpec, ManifestValue } from './types';
 
-export const NAVIGATOR_TYPES = ['stack', 'tabs', 'drawer'] as const;
+export const NAVIGATOR_TYPES = ['slot', 'stack', 'tabs', 'drawer', 'split-view', 'custom'] as const;
 export type NavigatorType = (typeof NAVIGATOR_TYPES)[number];
 
 export const NAVIGATOR_PRESETS = [
+  'slot',
   'stack',
   'tabs',
   'tabs-stack',
@@ -17,9 +18,82 @@ export const NAVIGATOR_PRESETS = [
   'root-stack-drawer-stack',
   'root-stack-drawer-tabs',
   'root-stack-drawer-tabs-stack',
+  'split-view',
+  'custom',
 ] as const;
 export type NavigatorPreset = (typeof NAVIGATOR_PRESETS)[number];
 
+export const STACK_IMPLEMENTATIONS = ['native', 'javascript', 'experimental'] as const;
+export type StackImplementation = (typeof STACK_IMPLEMENTATIONS)[number];
+
+export const STACK_PRESENTATIONS = [
+  'card',
+  'modal',
+  'transparentModal',
+  'containedModal',
+  'containedTransparentModal',
+  'fullScreenModal',
+  'formSheet',
+] as const;
+export type StackPresentation = (typeof STACK_PRESENTATIONS)[number];
+
+export const JAVASCRIPT_STACK_PRESENTATIONS = ['card', 'modal', 'transparentModal'] as const;
+export type JavaScriptStackPresentation = (typeof JAVASCRIPT_STACK_PRESENTATIONS)[number];
+
+export interface StackHeaderOptions {
+  title?: string;
+  headerShown?: boolean;
+  headerTransparent?: boolean;
+  headerBackVisible?: boolean;
+}
+
+export type StackScreenOptions = StackHeaderOptions &
+  (
+    | {
+        presentation?: Exclude<StackPresentation, 'formSheet'>;
+        sheetAllowedDetents?: never;
+        sheetGrabberVisible?: never;
+      }
+    | {
+        presentation: 'formSheet';
+        sheetAllowedDetents?: 'fitToContents' | number[];
+        sheetGrabberVisible?: boolean;
+      }
+  );
+
+export type JavaScriptStackScreenOptions = StackHeaderOptions & {
+  presentation?: JavaScriptStackPresentation;
+};
+
+export type StackImplementationConfig =
+  | {
+      /** Omission selects the stable native stack implementation. */
+      implementation?: 'native';
+      options?: StackScreenOptions;
+    }
+  | {
+      implementation: 'javascript';
+      options?: JavaScriptStackScreenOptions;
+    }
+  | {
+      /** Expo Router Experimental Stack is alpha, native-only, and available from SDK 56. */
+      implementation: 'experimental';
+      options?: StackHeaderOptions;
+    };
+
+export const DRAWER_POSITIONS = ['left', 'right'] as const;
+export type DrawerPosition = (typeof DRAWER_POSITIONS)[number];
+
+export const DRAWER_TYPES = ['front', 'back', 'slide', 'permanent'] as const;
+export type DrawerType = (typeof DRAWER_TYPES)[number];
+
+export interface DrawerNavigatorOptions {
+  drawerPosition?: DrawerPosition;
+  drawerType?: DrawerType;
+  swipeEnabled?: boolean;
+  headerShown?: boolean;
+}
+
 export const FIXED_CUSTOM_TABS_PRESENTATIONS = ['bottom', 'top', 'rail', 'sidebar'] as const;
 export type FixedCustomTabsPresentation = (typeof FIXED_CUSTOM_TABS_PRESENTATIONS)[number];
 
@@ -33,22 +107,54 @@ export type CustomTabsPresentation = (typeof CUSTOM_TABS_PRESENTATIONS)[number];
 export const JAVASCRIPT_TABS_PRESENTATIONS = ['bottom', 'top'] as const;
 export type JavaScriptTabsPresentation = (typeof JAVASCRIPT_TABS_PRESENTATIONS)[number];
 
+export const NATIVE_TABS_MINIMIZE_BEHAVIORS = [
+  'automatic',
+  'never',
+  'onScrollDown',
+  'onScrollUp',
+] as const;
+export type NativeTabsMinimizeBehavior = (typeof NATIVE_TABS_MINIMIZE_BEHAVIORS)[number];
+
 export interface ResponsiveTabsPresentation {
   compact: FixedCustomTabsPresentation;
   medium?: FixedCustomTabsPresentation;
   expanded: FixedCustomTabsPresentation;
 }
 
-export interface CustomTabsConfig {
+export type CustomTabsPresentationConfig =
+  | {
+      presentation: FixedCustomTabsPresentation;
+      responsive?: never;
+      customPresentationId?: never;
+    }
+  | {
+      presentation: 'responsive';
+      responsive: ResponsiveTabsPresentation;
+      customPresentationId?: never;
+    }
+  | {
+      presentation: 'custom';
+      responsive?: never;
+      /** Serializable registered presentation id. */
+      customPresentationId: string;
+    };
+
+export type CustomTabsConfig = {
   implementation: 'custom';
-  presentation: CustomTabsPresentation;
-  responsive?: ResponsiveTabsPresentation;
-  /** Serializable registered presentation id used when `presentation` is `custom`. */
-  customPresentationId?: string;
+} & CustomTabsPresentationConfig;
+
+export type CustomTabsWebConfig = CustomTabsPresentationConfig;
+
+export interface NavigatorScreenReference {
+  screenId: string;
 }
 
 export interface NativeTabsConfig {
   implementation: 'native';
+  /** Expo Router Native Tabs is alpha; minimizing is available on iOS 26+ from SDK 55. */
+  minimizeBehavior?: NativeTabsMinimizeBehavior;
+  /** Registered screen rendered through NativeTabs.BottomAccessory, available from SDK 55. */
+  bottomAccessory?: NavigatorScreenReference;
 }
 
 export interface JavaScriptTabsConfig {
@@ -62,7 +168,7 @@ export interface AdaptiveTabsConfig {
   /** Android/iOS branch. Expo Router may expose this implementation as unstable. */
   native?: NativeTabsConfig;
   /** Web branch rendered through headless custom tabs. */
-  web?: Omit<CustomTabsConfig, 'implementation'>;
+  web?: CustomTabsWebConfig;
 }
 
 export type TabsImplementationConfig =
@@ -71,16 +177,19 @@ export type TabsImplementationConfig =
 interface NavigatorNodeBase {
   initialRouteName?: string;
   routes: RouteDefinition[];
-  /** Typed upstream options can be layered by the owning Navigator package. */
-  options?: Record<string, unknown>;
 }
 
-export interface StackNavigatorNode extends NavigatorNodeBase {
-  type: 'stack';
+export interface SlotNavigatorNode extends NavigatorNodeBase {
+  type: 'slot';
 }
 
+export type StackNavigatorNode = NavigatorNodeBase & {
+  type: 'stack';
+} & StackImplementationConfig;
+
 export interface DrawerNavigatorNode extends NavigatorNodeBase {
   type: 'drawer';
+  options?: DrawerNavigatorOptions;
 }
 
 export type TabsNavigatorConfig = {
@@ -89,7 +198,30 @@ export type TabsNavigatorConfig = {
 
 export type TabsNavigatorNode = NavigatorNodeBase & TabsNavigatorConfig;
 
-export type NavigatorNode = DrawerNavigatorNode | StackNavigatorNode | TabsNavigatorNode;
+export interface SplitViewNavigatorNode extends NavigatorNodeBase {
+  type: 'split-view';
+  columns: {
+    primary: NavigatorScreenReference;
+    supplementary?: NavigatorScreenReference;
+  };
+  inspector?: NavigatorScreenReference;
+  /** Split View is alpha and iOS-only; other platforms fall back to Slot. */
+  topColumnForCollapsing?: 'primary' | 'supplementary' | 'secondary';
+}
+
+export interface CustomNavigatorNode extends NavigatorNodeBase {
+  type: 'custom';
+  navigatorId: string;
+  config?: Readonly<Record<string, ManifestValue>>;
+}
+
+export type NavigatorNode =
+  | CustomNavigatorNode
+  | DrawerNavigatorNode
+  | SlotNavigatorNode
+  | SplitViewNavigatorNode
+  | StackNavigatorNode
+  | TabsNavigatorNode;
 
 export interface RouteDefinition {
   name: string;
@@ -100,6 +232,8 @@ export interface RouteDefinition {
   showInPrimaryNavigation?: boolean;
   guards?: string[];
   screenId?: string;
+  /** Presentation applied by the resolved parent stack implementation. */
+  stackOptions?: StackScreenOptions;
   navigator?: NavigatorNode;
 }
 
@@ -110,10 +244,12 @@ export interface NavigatorFlows {
 
 export interface NavigatorDefaults {
   tabs?: TabsImplementationConfig;
+  stack?: StackImplementationConfig;
 }
 
 export interface NavigatorPlatformConfig {
   tabs?: TabsImplementationConfig;
+  stack?: StackImplementationConfig;
 }
 
 export interface NavigatorPlatforms {