@ankhorage/contracts 10.0.0 → 11.0.0

package/src/appManifest/screens.ts

@@ -1,29 +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 {
-  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 {
@@ -50,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) &&
@@ -129,155 +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))
-  );
-}
-
-function isIconSpec(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    typeof value.name === 'string' &&
-    isOptionalString(value.provider) &&
-    (value.size === undefined ||
-      typeof value.size === 'string' ||
-      typeof value.size === 'number') &&
-    isOptionalString(value.color)
-  );
-}
-
-/*** 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-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');
   });
@@ -38,6 +96,29 @@ describe('app navigator manifest topology', () => {
     expect(isAppNavigatorManifest(createAdaptiveTabs())).toBe(true);
   });
 
+  it('accepts SVG media icon references without a provider', () => {
+    const navigator = createAdaptiveTabs();
+    navigator.routes[0] = {
+      ...navigator.routes[0],
+      icon: { source: { mediaId: 'navigation-home' } },
+    };
+
+    expect(isAppNavigatorManifest(navigator)).toBe(true);
+  });
+
+  it('rejects icon definitions that mix named and media sources', () => {
+    const navigator = createAdaptiveTabs();
+    navigator.routes[0] = {
+      ...navigator.routes[0],
+      icon: {
+        name: 'home-outline',
+        source: { mediaId: 'navigation-home' },
+      } as never,
+    };
+
+    expect(isAppNavigatorManifest(navigator)).toBe(false);
+  });
+
   it('treats omitted tabs implementation as the canonical adaptive default', () => {
     const tabs: TabsNavigatorConfig = { type: 'tabs' };
     const navigator: AppNavigatorManifest = { ...tabs, routes: [] };
@@ -46,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(
@@ -89,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(
@@ -108,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',
     });
   });
 });