@ankhorage/contracts 10.1.0 → 11.1.0

package/src/appManifest/screens.ts

@@ -1,30 +1,13 @@
 import { COLOR_HARMONIES } from '@ankhorage/color-theory';
 
-import {
-  CUSTOM_TABS_PRESENTATIONS,
-  FIXED_CUSTOM_TABS_PRESENTATIONS,
-  JAVASCRIPT_TABS_PRESENTATIONS,
-  NAVIGATOR_PRESETS,
-  NAVIGATOR_TYPES,
-} from '../navigator';
 import { APP_CATEGORIES } from '../types';
 import { isBindingValueSource, isScreenDataLoaderDefinition } from './bindings';
-import { isIconSpec } from './icon';
-import {
-  isOptionalBoolean,
-  isOptionalNumber,
-  isOptionalString,
-  isRecord,
-  isStringArray,
-} from './shared';
+import { isOptionalNumber, isOptionalString, isRecord } from './shared';
+
+export { isAppNavigatorManifest } from './navigator';
 
 const APP_CATEGORY_SET = new Set<string>(APP_CATEGORIES);
 const COLOR_HARMONY_SET = new Set<string>(COLOR_HARMONIES);
-const CUSTOM_TABS_PRESENTATION_SET = new Set<string>(CUSTOM_TABS_PRESENTATIONS);
-const FIXED_CUSTOM_TABS_PRESENTATION_SET = new Set<string>(FIXED_CUSTOM_TABS_PRESENTATIONS);
-const JAVASCRIPT_TABS_PRESENTATION_SET = new Set<string>(JAVASCRIPT_TABS_PRESENTATIONS);
-const NAVIGATOR_PRESET_SET = new Set<string>(NAVIGATOR_PRESETS);
-const NAVIGATOR_TYPE_SET = new Set<string>(NAVIGATOR_TYPES);
 const SPLASH_SCREEN_RESIZE_MODE_SET = new Set<string>(['contain', 'cover', 'native']);
 
 export function isManifestMetadata(value: unknown): boolean {
@@ -51,19 +34,6 @@ export function isThemeConfig(value: unknown): boolean {
   );
 }
 
-/*** Validate the complete serialized `AppManifest.navigator` slice. */
-export function isAppNavigatorManifest(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    isNavigatorNode(value) &&
-    (value.preset === undefined ||
-      (typeof value.preset === 'string' && NAVIGATOR_PRESET_SET.has(value.preset))) &&
-    (value.flows === undefined || isNavigatorFlows(value.flows)) &&
-    (value.defaults === undefined || isNavigatorDefaults(value.defaults)) &&
-    (value.platforms === undefined || isNavigatorPlatforms(value.platforms))
-  );
-}
-
 export function isScreenRegistry(value: unknown): boolean {
   return (
     isRecord(value) &&
@@ -130,143 +100,6 @@ function isScreenSpec(value: unknown): boolean {
   );
 }
 
-/*** Validate one nested navigator node independently from app-level authoring metadata. */
-function isNavigatorNode(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    typeof value.type === 'string' &&
-    NAVIGATOR_TYPE_SET.has(value.type) &&
-    isOptionalString(value.initialRouteName) &&
-    Array.isArray(value.routes) &&
-    value.routes.every(isRouteDefinition) &&
-    (value.options === undefined || isRecord(value.options)) &&
-    (value.type !== 'tabs' || isTabsImplementationConfig(value))
-  );
-}
-
-function isRouteDefinition(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    typeof value.name === 'string' &&
-    isOptionalString(value.path) &&
-    isOptionalString(value.label) &&
-    (value.icon === undefined || isIconSpec(value.icon)) &&
-    isOptionalBoolean(value.showInPrimaryNavigation) &&
-    (value.guards === undefined || isStringArray(value.guards)) &&
-    isOptionalString(value.screenId) &&
-    (value.navigator === undefined || isNavigatorNode(value.navigator))
-  );
-}
-
-/*** Validate tabs implementation desired state, with omitted implementation meaning adaptive. */
-function isTabsImplementationConfig(value: Record<string, unknown>): boolean {
-  if (value.implementation === undefined || value.implementation === 'adaptive') {
-    return (
-      (value.native === undefined || isNativeTabsConfig(value.native)) &&
-      (value.web === undefined || isCustomTabsWebConfig(value.web))
-    );
-  }
-
-  if (value.implementation === 'native') return true;
-
-  if (value.implementation === 'javascript') {
-    return (
-      value.presentation === undefined ||
-      (typeof value.presentation === 'string' &&
-        JAVASCRIPT_TABS_PRESENTATION_SET.has(value.presentation))
-    );
-  }
-
-  return value.implementation === 'custom' && isCustomTabsConfig(value);
-}
-
-/*** Validate the native branch used by adaptive tabs. */
-function isNativeTabsConfig(value: unknown): boolean {
-  return isRecord(value) && value.implementation === 'native';
-}
-
-/*** Validate a full custom-tabs implementation config. */
-function isCustomTabsConfig(value: Record<string, unknown>): boolean {
-  return value.implementation === 'custom' && isCustomTabsPresentationConfig(value);
-}
-
-/*** Validate the implementation-free custom-tabs Web branch inside adaptive tabs. */
-function isCustomTabsWebConfig(value: unknown): boolean {
-  return (
-    isRecord(value) && value.implementation === undefined && isCustomTabsPresentationConfig(value)
-  );
-}
-
-/*** Validate custom-tab presentation and its conditional serializable configuration. */
-function isCustomTabsPresentationConfig(value: Record<string, unknown>): boolean {
-  if (
-    typeof value.presentation !== 'string' ||
-    !CUSTOM_TABS_PRESENTATION_SET.has(value.presentation)
-  ) {
-    return false;
-  }
-
-  if (value.responsive !== undefined && !isResponsiveTabsPresentation(value.responsive)) {
-    return false;
-  }
-
-  if (!isOptionalString(value.customPresentationId)) return false;
-  if (value.presentation === 'responsive' && value.responsive === undefined) return false;
-
-  return (
-    value.presentation !== 'custom' ||
-    (typeof value.customPresentationId === 'string' && value.customPresentationId.length > 0)
-  );
-}
-
-/*** Validate semantic compact/medium/expanded custom-tab presentation mapping. */
-function isResponsiveTabsPresentation(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    typeof value.compact === 'string' &&
-    FIXED_CUSTOM_TABS_PRESENTATION_SET.has(value.compact) &&
-    (value.medium === undefined ||
-      (typeof value.medium === 'string' && FIXED_CUSTOM_TABS_PRESENTATION_SET.has(value.medium))) &&
-    typeof value.expanded === 'string' &&
-    FIXED_CUSTOM_TABS_PRESENTATION_SET.has(value.expanded)
-  );
-}
-
-/*** Validate optional app-level navigator flow intent. */
-function isNavigatorFlows(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    isOptionalBoolean(value.onboarding) &&
-    isOptionalBoolean(value.authentication)
-  );
-}
-
-/*** Validate package-owned navigator defaults without requiring a navigator node type. */
-function isNavigatorDefaults(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    (value.tabs === undefined || (isRecord(value.tabs) && isTabsImplementationConfig(value.tabs)))
-  );
-}
-
-/*** Validate per-platform navigator implementation overrides. */
-function isNavigatorPlatforms(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    (value.android === undefined || isNavigatorPlatformConfig(value.android)) &&
-    (value.ios === undefined || isNavigatorPlatformConfig(value.ios)) &&
-    (value.web === undefined || isNavigatorPlatformConfig(value.web))
-  );
-}
-
-/*** Validate one platform-specific navigator override slice. */
-function isNavigatorPlatformConfig(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    (value.tabs === undefined || (isRecord(value.tabs) && isTabsImplementationConfig(value.tabs)))
-  );
-}
-
 function isSplashScreenModeSpec(value: unknown): boolean {
   return (
     isRecord(value) &&

package/src/contracts.test.ts

@@ -80,7 +80,7 @@ describe('contracts', () => {
   });
 
   it('exports stable platform constants', () => {
-    expect(NAVIGATOR_TYPES).toEqual(['stack', 'tabs', 'drawer']);
+    expect(NAVIGATOR_TYPES).toEqual(['slot', 'stack', 'tabs', 'drawer', 'split-view', 'custom']);
     expect(APP_CATEGORIES).toEqual([
       'books_reading',
       'business_productivity',

package/src/navigator/extensions.ts

@@ -0,0 +1,26 @@
+import type { CustomNavigatorNode } from '../navigator';
+import type { NavigatorApiStability, NavigatorRuntimePlatform } from './planning';
+export interface CustomNavigatorConfigIssue {
+  code: string;
+  message: string;
+  path?: string;
+}
+
+export interface CustomNavigatorRegistration {
+  readonly id: string;
+  readonly platforms: readonly NavigatorRuntimePlatform[];
+  readonly stability: NavigatorApiStability;
+  readonly integration: 'expo-router-standard';
+  readonly router: 'stack' | 'tab';
+  readonly module: string;
+  readonly exportName: string;
+  readonly validateConfig: (
+    config: CustomNavigatorNode['config'],
+  ) => readonly CustomNavigatorConfigIssue[];
+}
+
+export type CustomNavigatorRegistry = Readonly<Record<string, CustomNavigatorRegistration>> & {
+  readonly [CUSTOM_NAVIGATOR_REGISTRY]: true;
+};
+
+declare const CUSTOM_NAVIGATOR_REGISTRY: unique symbol;

package/src/navigator/generation.ts

@@ -0,0 +1,28 @@
+export interface NavigatorGeneratedFile {
+  path: string;
+  contents: string;
+}
+
+export interface NavigatorGenerationBindings {
+  screens: Readonly<Record<string, NavigatorScreenModule>>;
+  guards: Readonly<Record<string, NavigatorScreenModule>>;
+  iconSourceResolver?: NavigatorScreenModule;
+  flows?: {
+    onboardingRoute?: string;
+    authenticationRoute?: string;
+  };
+  tabPresentations?: Readonly<Record<string, NavigatorScreenModule>>;
+}
+
+/** Options for placing Navigator-owned files inside a consumer-owned Expo Router app shell. */
+export interface NavigatorGenerationOptions {
+  /** Directory that receives the root navigator layout. Must be `src/app` or one of its safe descendants. */
+  rootDirectory?: string;
+  /** Emit routed screen re-export modules in addition to layouts. Defaults to true. */
+  includeScreenFiles?: boolean;
+}
+
+export interface NavigatorScreenModule {
+  module: string;
+  exportName: string;
+}

package/src/navigator/planning.ts

@@ -0,0 +1,146 @@
+import type {
+  CustomNavigatorNode,
+  DrawerNavigatorOptions,
+  NavigatorType,
+  RouteDefinition,
+  StackImplementation,
+  StackScreenOptions,
+} from '../navigator';
+import type { CustomNavigatorRegistry } from './extensions';
+
+export interface ResolvedCustomTabsPresentation {
+  presentation: ResolvedTabsPresentation;
+  customPresentationId?: string;
+}
+
+export type ResolvedTabsImplementation = 'custom' | 'javascript' | 'native';
+
+export type ResolvedTabsPresentation = 'bottom' | 'top' | 'rail' | 'sidebar' | 'custom';
+
+/**
+ * Disposable adapter plan for a `tabs` topology.
+ *
+ * The implementation selects the Router runtime. Presentation only selects its visual chrome and
+ * never creates another route topology.
+ */
+export interface TabsNavigatorPlan {
+  implementation: ResolvedTabsImplementation;
+  module: ExpoRouterNavigatorModule;
+  exportName: string;
+  stability: NavigatorApiStability;
+  presentation?: ResolvedTabsPresentation;
+  presentations?: Readonly<Record<NavigatorResponsiveSize, ResolvedTabsPresentation>>;
+  customPresentationId?: string;
+  minimizeBehavior?: 'automatic' | 'never' | 'onScrollDown' | 'onScrollUp';
+  bottomAccessoryScreenId?: string;
+}
+
+export interface CreateNavigatorPlanOptions {
+  platform: NavigatorRuntimePlatform;
+  expoRouterVersion: string;
+  responsiveSize?: NavigatorResponsiveSize;
+  customNavigators?: CustomNavigatorRegistry;
+}
+
+export type ExpoRouterNavigatorModule =
+  | 'expo-router'
+  | 'expo-router/drawer'
+  | 'expo-router/js-stack'
+  | 'expo-router/js-tabs'
+  | 'expo-router/js-top-tabs'
+  | 'expo-router/ui'
+  | 'expo-router/unstable-split-view'
+  | 'expo-router/unstable-native-tabs';
+
+export type NavigatorAdapterId =
+  | 'slot'
+  | 'stack.native'
+  | 'stack.javascript'
+  | 'stack.experimental'
+  | 'drawer'
+  | 'tabs.native'
+  | 'tabs.javascript'
+  | 'tabs.custom'
+  | 'split-view'
+  | 'custom';
+
+export interface NavigatorAdapterPlan {
+  id: NavigatorAdapterId;
+  /** Built-in Expo Router entry point or an explicitly registered custom module. */
+  module?: string;
+  exportName?: string;
+  support: NavigatorSupportStatus;
+  stability: NavigatorApiStability;
+  limitations: readonly string[];
+}
+
+export type NavigatorApiStability = 'stable' | 'alpha';
+
+export interface NavigatorDiagnostic {
+  code: string;
+  severity: 'error' | 'warning';
+  path: string;
+  message: string;
+}
+
+export interface NavigatorNodePlan {
+  type: NavigatorType;
+  pointer: string;
+  adapter: NavigatorAdapterPlan;
+  initialRouteName?: string;
+  routes: readonly NavigatorRoutePlan[];
+  stack?: {
+    implementation: StackImplementation;
+    options?: StackScreenOptions;
+  };
+  drawer?: {
+    options?: DrawerNavigatorOptions;
+  };
+  tabs?: TabsNavigatorPlan;
+  splitView?: {
+    columns: {
+      primary: string;
+      supplementary?: string;
+    };
+    inspector?: string;
+    topColumnForCollapsing?: 'primary' | 'secondary' | 'supplementary';
+  };
+  custom?: {
+    navigatorId: string;
+    config?: CustomNavigatorNode['config'];
+  };
+}
+
+export interface NavigatorPlan {
+  context: NavigatorValidationContext;
+  root: NavigatorNodePlan;
+  diagnostics: readonly NavigatorDiagnostic[];
+  supported: boolean;
+  flows: {
+    onboarding: boolean;
+    authentication: boolean;
+  };
+}
+
+export type NavigatorResponsiveSize = 'compact' | 'medium' | 'expanded';
+
+export interface NavigatorRoutePlan {
+  name: string;
+  path?: string;
+  label?: string;
+  icon?: RouteDefinition['icon'];
+  showInPrimaryNavigation?: boolean;
+  guards: readonly string[];
+  screenId?: string;
+  stackOptions?: StackScreenOptions;
+  navigator?: NavigatorNodePlan;
+}
+
+export type NavigatorRuntimePlatform = 'android' | 'ios' | 'web';
+
+export type NavigatorSupportStatus = 'supported' | 'unavailable';
+
+export interface NavigatorValidationContext {
+  platform: NavigatorRuntimePlatform;
+  expoRouterVersion: string;
+}

package/src/navigator-runtime-contracts.test.ts

@@ -0,0 +1,53 @@
+import { expect, test } from 'bun:test';
+
+import type {
+  CustomNavigatorRegistration,
+  NavigatorGeneratedFile,
+  NavigatorGenerationBindings,
+  NavigatorPlan,
+} from './navigator';
+
+test('keeps generation bindings and plan output portable across package boundaries', () => {
+  const bindings: NavigatorGenerationBindings = {
+    screens: { home: { module: '@/screens/Home', exportName: 'Home' } },
+    guards: {},
+  };
+  const file: NavigatorGeneratedFile = {
+    path: 'src/app/index.tsx',
+    contents: 'export default Home;',
+  };
+  const plan: NavigatorPlan = {
+    context: { platform: 'web', expoRouterVersion: '57.0.18' },
+    root: {
+      type: 'slot',
+      pointer: '',
+      adapter: {
+        id: 'slot',
+        module: 'expo-router',
+        exportName: 'Slot',
+        support: 'supported',
+        stability: 'stable',
+        limitations: [],
+      },
+      routes: [],
+    },
+    diagnostics: [],
+    supported: true,
+    flows: { onboarding: false, authentication: false },
+  };
+  expect(JSON.parse(JSON.stringify({ bindings, file, plan }))).toEqual({ bindings, file, plan });
+});
+
+test('describes a custom extension without importing Navigator or a UI runtime', () => {
+  const registration: CustomNavigatorRegistration = {
+    id: 'example',
+    platforms: ['web'],
+    stability: 'stable',
+    integration: 'expo-router-standard',
+    router: 'stack',
+    module: '@example/navigation',
+    exportName: 'ExampleNavigator',
+    validateConfig: () => [],
+  };
+  expect(registration.validateConfig({ mode: 'compact' })).toEqual([]);
+});

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',
+    });
+  });
+});