@ankhorage/contracts 9.0.0 → 10.1.0

package/src/navigator.test.ts

@@ -0,0 +1,144 @@
+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,
+  type TabsNavigatorConfig,
+} from './navigator';
+
+function createAdaptiveTabs(): AppNavigatorManifest {
+  return {
+    type: 'tabs',
+    preset: 'tabs-stack',
+    implementation: 'adaptive',
+    web: {
+      presentation: 'responsive',
+      responsive: {
+        compact: 'bottom',
+        medium: 'rail',
+        expanded: 'sidebar',
+      },
+    },
+    flows: { onboarding: true },
+    routes: [{ name: 'home', path: '/', screenId: 'home' }],
+  };
+}
+
+describe('app navigator manifest topology', () => {
+  it('keeps canonical topology presets finite and authorable', () => {
+    expect(NAVIGATOR_PRESETS).toContain('root-stack-tabs-stack');
+    expect(NAVIGATOR_PRESETS).toContain('root-stack-drawer-tabs-stack');
+  });
+
+  it('accepts adaptive native/Web tabs with responsive custom presentation', () => {
+    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: [] };
+
+    expect(isAppNavigatorManifest(navigator)).toBe(true);
+  });
+});
+
+describe('app navigator manifest custom presentation', () => {
+  it('accepts fixed and registered custom Web presentations', () => {
+    expect(
+      isAppNavigatorManifest({
+        type: 'tabs',
+        implementation: 'custom',
+        presentation: 'sidebar',
+        routes: [],
+      }),
+    ).toBe(true);
+
+    expect(
+      isAppNavigatorManifest({
+        type: 'tabs',
+        implementation: 'custom',
+        presentation: 'custom',
+        customPresentationId: 'workspace-tabs',
+        routes: [],
+      }),
+    ).toBe(true);
+  });
+
+  it('rejects incomplete responsive and custom presentation configuration', () => {
+    expect(
+      isAppNavigatorManifest({
+        type: 'tabs',
+        implementation: 'custom',
+        presentation: 'responsive',
+        routes: [],
+      }),
+    ).toBe(false);
+
+    expect(
+      isAppNavigatorManifest({
+        type: 'tabs',
+        implementation: 'custom',
+        presentation: 'custom',
+        routes: [],
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('app navigator manifest composition', () => {
+  it('keeps nested topology separate from app-level flow metadata', () => {
+    expect(
+      isAppNavigatorManifest({
+        type: 'stack',
+        flows: { authentication: true },
+        routes: [
+          {
+            name: 'app',
+            navigator: {
+              type: 'tabs',
+              routes: [{ name: 'home', screenId: 'home' }],
+            },
+          },
+        ],
+      }),
+    ).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 }>;
+    };
+
+    expect(packageJson.exports?.['./navigator']).toEqual({
+      types: './dist/navigator.d.ts',
+      default: './dist/navigator.js',
+    });
+  });
+});

package/src/navigator.ts

@@ -0,0 +1,136 @@
+import type { IconSpec } from './types';
+
+export const NAVIGATOR_TYPES = ['stack', 'tabs', 'drawer'] as const;
+export type NavigatorType = (typeof NAVIGATOR_TYPES)[number];
+
+export const NAVIGATOR_PRESETS = [
+  'stack',
+  'tabs',
+  'tabs-stack',
+  'drawer',
+  'drawer-stack',
+  'drawer-tabs',
+  'drawer-tabs-stack',
+  'root-stack-tabs',
+  'root-stack-tabs-stack',
+  'root-stack-drawer',
+  'root-stack-drawer-stack',
+  'root-stack-drawer-tabs',
+  'root-stack-drawer-tabs-stack',
+] as const;
+export type NavigatorPreset = (typeof NAVIGATOR_PRESETS)[number];
+
+export const FIXED_CUSTOM_TABS_PRESENTATIONS = ['bottom', 'top', 'rail', 'sidebar'] as const;
+export type FixedCustomTabsPresentation = (typeof FIXED_CUSTOM_TABS_PRESENTATIONS)[number];
+
+export const CUSTOM_TABS_PRESENTATIONS = [
+  ...FIXED_CUSTOM_TABS_PRESENTATIONS,
+  'responsive',
+  'custom',
+] as const;
+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 interface ResponsiveTabsPresentation {
+  compact: FixedCustomTabsPresentation;
+  medium?: FixedCustomTabsPresentation;
+  expanded: FixedCustomTabsPresentation;
+}
+
+export interface CustomTabsConfig {
+  implementation: 'custom';
+  presentation: CustomTabsPresentation;
+  responsive?: ResponsiveTabsPresentation;
+  /** Serializable registered presentation id used when `presentation` is `custom`. */
+  customPresentationId?: string;
+}
+
+export interface NativeTabsConfig {
+  implementation: 'native';
+}
+
+export interface JavaScriptTabsConfig {
+  implementation: 'javascript';
+  presentation?: JavaScriptTabsPresentation;
+}
+
+export interface AdaptiveTabsConfig {
+  /** Omission selects the canonical adaptive default. */
+  implementation?: 'adaptive';
+  /** Android/iOS branch. Expo Router may expose this implementation as unstable. */
+  native?: NativeTabsConfig;
+  /** Web branch rendered through headless custom tabs. */
+  web?: Omit<CustomTabsConfig, 'implementation'>;
+}
+
+export type TabsImplementationConfig =
+  AdaptiveTabsConfig | CustomTabsConfig | JavaScriptTabsConfig | NativeTabsConfig;
+
+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 DrawerNavigatorNode extends NavigatorNodeBase {
+  type: 'drawer';
+}
+
+export type TabsNavigatorConfig = {
+  type: 'tabs';
+} & TabsImplementationConfig;
+
+export type TabsNavigatorNode = NavigatorNodeBase & TabsNavigatorConfig;
+
+export type NavigatorNode = DrawerNavigatorNode | StackNavigatorNode | TabsNavigatorNode;
+
+export interface RouteDefinition {
+  name: string;
+  path?: string;
+  label?: string;
+  icon?: IconSpec;
+  /** Hide this route from primary Tabs/Drawer presentation without making it unnavigable. */
+  showInPrimaryNavigation?: boolean;
+  guards?: string[];
+  screenId?: string;
+  navigator?: NavigatorNode;
+}
+
+export interface NavigatorFlows {
+  onboarding?: boolean;
+  authentication?: boolean;
+}
+
+export interface NavigatorDefaults {
+  tabs?: TabsImplementationConfig;
+}
+
+export interface NavigatorPlatformConfig {
+  tabs?: TabsImplementationConfig;
+}
+
+export interface NavigatorPlatforms {
+  android?: NavigatorPlatformConfig;
+  ios?: NavigatorPlatformConfig;
+  web?: NavigatorPlatformConfig;
+}
+
+/**
+ * Serializable desired state for `AppManifest.navigator`.
+ *
+ * The manifest slice is the root navigator tree itself; optional authoring metadata does not add
+ * a redundant `root` wrapper. The standalone Navigator capability consumes this slice directly.
+ */
+export type AppNavigatorManifest = NavigatorNode & {
+  preset?: NavigatorPreset;
+  flows?: NavigatorFlows;
+  defaults?: NavigatorDefaults;
+  platforms?: NavigatorPlatforms;
+};

package/src/types.ts

@@ -8,7 +8,8 @@ import type {
 } from './bindings';
 import type { ApiDefinitionList, DataSourceRegistry } from './data';
 import type { AppDeployManifest } from './deploy';
-import type { MediaManifest } from './media';
+import type { MediaAssetReference, MediaManifest } from './media';
+import type { AppNavigatorManifest } from './navigator';
 import type { RepositoryManifest } from './repository';
 import type { ScreenRequirements } from './requirements';
 import type { ThemeGlobalTokenOverrides, ThemeRecipeOverrides } from './theme';
@@ -135,9 +136,6 @@ export type ComponentEventDtoKind =
 export type KnownComponentEventDto =
   ButtonPressEventDto | CollectionItemPressEventDto | FormSubmitEventDto;
 
-export const NAVIGATOR_TYPES = ['stack', 'tabs', 'drawer'] as const;
-export type NavigatorType = (typeof NAVIGATOR_TYPES)[number];
-
 export const APP_CATEGORIES = [
   'books_reading',
   'business_productivity',
@@ -224,13 +222,25 @@ export type AuthProfileCreateStrategy = (typeof AUTH_PROFILE_CREATE_STRATEGIES)[
 export const AUTH_PROFILE_UPDATE_STRATEGIES = ['api', 'app'] as const;
 export type AuthProfileUpdateStrategy = (typeof AUTH_PROFILE_UPDATE_STRATEGIES)[number];
 
-export interface IconSpec {
-  name: string;
-  provider?: string;
+interface IconPresentationSpec {
   size?: number | string;
   color?: string;
 }
 
+export interface NamedIconSpec extends IconPresentationSpec {
+  name: string;
+  provider?: string;
+  source?: never;
+}
+
+export interface SvgIconSpec extends IconPresentationSpec {
+  source: MediaAssetReference;
+  name?: never;
+  provider?: never;
+}
+
+export type IconSpec = NamedIconSpec | SvgIconSpec;
+
 export interface UiNodeRepeatSpec {
   source: BindingValueSource;
   itemAlias?: string;
@@ -258,31 +268,6 @@ export interface ScreenSpec {
   requires?: ScreenRequirements;
 }
 
-export interface NavigatorSpec {
-  type: NavigatorType;
-  initialRouteName?: string;
-  routes: RouteDefinition[];
-  options?: Record<string, unknown>;
-}
-
-export interface RouteDefinition {
-  name: string;
-  path?: string;
-  label?: string;
-  icon?: IconSpec;
-  /**
-   * Whether this route appears in Tabs and Drawer primary navigation.
-   *
-   * Omitted routes are visible by default. Setting this to `false` hides the
-   * route from primary navigation without making it unnavigable. Stack
-   * navigators preserve the value but do not present primary navigation.
-   */
-  showInPrimaryNavigation?: boolean;
-  guards?: string[];
-  screenId?: string;
-  navigator?: NavigatorSpec;
-}
-
 export type SplashScreenResizeMode = 'contain' | 'cover' | 'native';
 
 export interface SplashScreenAssetSpec {
@@ -396,7 +381,7 @@ export interface AppManifest {
   /** App distribution desired state. Infrastructure deployment remains under `infra.deployment`. */
   deploy?: AppDeployManifest;
   infra: InfraManifest;
-  navigator: NavigatorSpec;
+  navigator: AppNavigatorManifest;
   screens: Record<string, ScreenSpec>;
   dataSources?: DataSourceRegistry;
   dataBindings?: ComponentDataBindingRegistry;