@ankhorage/zora 18.0.1 → 19.0.1

package/src/features/theme/themeScopeStructure.test.ts

@@ -0,0 +1,228 @@
+/**
+ * Keep structural guards for the public Surface boundary alongside ZoraThemeScope behavior tests.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'bun:test';
+
+const themeDir = import.meta.dir;
+const srcDir = join(themeDir, '..', '..');
+
+function readSource(...segments: readonly string[]) {
+  return readFileSync(join(themeDir, ...segments), 'utf8');
+}
+
+function collectSourceFiles(rootDir: string) {
+  const files: string[] = [];
+
+  function visit(current: string) {
+    for (const entry of readdirSync(current)) {
+      const full = join(current, entry);
+      const stat = statSync(full);
+      if (stat.isDirectory()) {
+        visit(full);
+        continue;
+      }
+
+      if (full.endsWith('.test.ts') || full.endsWith('.test.tsx')) {
+        continue;
+      }
+
+      if (full.endsWith('.ts') || full.endsWith('.tsx')) {
+        files.push(full);
+      }
+    }
+  }
+
+  visit(rootDir);
+  return files;
+}
+
+const zoraProviderSource = readSource('adapters', 'inbound', 'ZoraProvider.tsx');
+const themeScopeSource = readSource('adapters', 'inbound', 'ZoraThemeScope.tsx');
+const hocSource = readSource('adapters', 'inbound', 'withZoraThemeScope.tsx');
+
+const scopeGuardDirs = [join(srcDir, 'features')] as const;
+const themeFeatureDir = join(srcDir, 'features', 'theme');
+
+const scopeGuardFiles = scopeGuardDirs
+  .flatMap(collectSourceFiles)
+  .filter((filePath) => !filePath.startsWith(`${themeFeatureDir}/`));
+
+const scopedComponentFiles = [
+  join(srcDir, 'features', 'layout', 'adapters', 'inbound', 'AppShell.tsx'),
+  join(srcDir, 'features', 'layout', 'adapters', 'inbound', 'Screen.tsx'),
+  join(srcDir, 'features', 'section', 'adapters', 'inbound', 'ScreenSection.tsx'),
+  join(srcDir, 'features', 'layout', 'adapters', 'inbound', 'ScrollView.tsx'),
+  join(srcDir, 'features', 'layout', 'adapters', 'inbound', 'View.tsx'),
+  join(srcDir, 'features', 'content-rail', 'adapters', 'inbound', 'ContentRail.tsx'),
+  join(srcDir, 'features', 'palette-item', 'adapters', 'inbound', 'PaletteItem.tsx'),
+  join(srcDir, 'features', 'list', 'adapters', 'inbound', 'FlatList.tsx'),
+  join(srcDir, 'features', 'list', 'adapters', 'inbound', 'SectionList.tsx'),
+  join(srcDir, 'features', 'bottom-sheet', 'adapters', 'inbound', 'BottomSheet.tsx'),
+  join(srcDir, 'features', 'app-bar', 'adapters', 'inbound', 'AppBar.tsx'),
+  join(srcDir, 'features', 'accordion', 'adapters', 'inbound', 'Accordion.tsx'),
+  join(srcDir, 'features', 'accordion', 'adapters', 'inbound', 'AccordionItem.tsx'),
+  join(srcDir, 'features', 'badge', 'adapters', 'inbound', 'Badge.tsx'),
+  join(srcDir, 'features', 'breadcrumbs', 'adapters', 'inbound', 'Breadcrumbs.tsx'),
+  join(srcDir, 'features', 'button', 'adapters', 'inbound', 'Button.tsx'),
+  join(srcDir, 'features', 'button', 'adapters', 'inbound', 'ButtonGroup.tsx'),
+  join(srcDir, 'features', 'card', 'adapters', 'inbound', 'Card.tsx'),
+  join(srcDir, 'features', 'card', 'adapters', 'inbound', 'MediaCard.tsx'),
+  join(srcDir, 'features', 'card', 'adapters', 'inbound', 'MetricCard.tsx'),
+  join(srcDir, 'features', 'date-picker', 'adapters', 'inbound', 'DatePicker.native.tsx'),
+  join(srcDir, 'features', 'date-picker', 'adapters', 'inbound', 'DatePicker.web.tsx'),
+  join(srcDir, 'features', 'dialog', 'adapters', 'inbound', 'Dialog.tsx'),
+  join(srcDir, 'features', 'form', 'checkbox', 'adapters', 'inbound', 'Checkbox.tsx'),
+  join(srcDir, 'features', 'form', 'checkbox', 'adapters', 'inbound', 'CheckboxGroup.tsx'),
+  join(srcDir, 'features', 'form', 'adapters', 'inbound', 'Form.tsx'),
+  join(srcDir, 'features', 'form', 'adapters', 'inbound', 'FormActions.tsx'),
+  join(srcDir, 'features', 'form', 'adapters', 'inbound', 'FormError.tsx'),
+  join(srcDir, 'features', 'form', 'field', 'adapters', 'inbound', 'Field.tsx'),
+  join(srcDir, 'features', 'form', 'search-input', 'adapters', 'inbound', 'SearchInput.tsx'),
+  join(srcDir, 'features', 'form', 'select', 'adapters', 'inbound', 'Select.native.tsx'),
+  join(srcDir, 'features', 'form', 'select', 'adapters', 'inbound', 'Select.web.tsx'),
+  join(srcDir, 'features', 'typography', 'adapters', 'inbound', 'Heading.tsx'),
+  join(srcDir, 'features', 'icon', 'adapters', 'inbound', 'Icon.tsx'),
+  join(srcDir, 'features', 'button', 'adapters', 'inbound', 'IconButton.tsx'),
+  join(srcDir, 'features', 'form', 'text-input', 'adapters', 'inbound', 'TextInput.tsx'),
+  join(srcDir, 'features', 'pagination', 'adapters', 'inbound', 'Pagination.tsx'),
+  join(srcDir, 'features', 'popover-menu', 'adapters', 'inbound', 'PopoverMenu.tsx'),
+  join(srcDir, 'features', 'progress', 'adapters', 'inbound', 'Progress.tsx'),
+  join(srcDir, 'features', 'form', 'radio', 'adapters', 'inbound', 'Radio.tsx'),
+  join(srcDir, 'features', 'form', 'radio', 'adapters', 'inbound', 'RadioGroup.tsx'),
+  join(srcDir, 'features', 'rating', 'adapters', 'inbound', 'Rating.tsx'),
+  join(srcDir, 'features', 'tabs', 'adapters', 'inbound', 'Tab.tsx'),
+  join(srcDir, 'features', 'tabs', 'adapters', 'inbound', 'TabList.tsx'),
+  join(srcDir, 'features', 'tabs', 'adapters', 'inbound', 'TabPanel.tsx'),
+  join(srcDir, 'features', 'tabs', 'adapters', 'inbound', 'Tabs.tsx'),
+  join(srcDir, 'features', 'time-picker', 'adapters', 'inbound', 'TimePicker.native.tsx'),
+  join(srcDir, 'features', 'time-picker', 'adapters', 'inbound', 'TimePicker.web.tsx'),
+  join(srcDir, 'features', 'toast', 'adapters', 'inbound', 'Toast.tsx'),
+  join(srcDir, 'features', 'toolbar', 'adapters', 'inbound', 'Toolbar.tsx'),
+  join(srcDir, 'features', 'typography', 'adapters', 'inbound', 'Text.tsx'),
+
+  join(srcDir, 'features', 'auth', 'adapters', 'inbound', 'ForgotPasswordForm.tsx'),
+  join(srcDir, 'features', 'auth', 'adapters', 'inbound', 'OtpForm.tsx'),
+  join(srcDir, 'features', 'auth', 'adapters', 'inbound', 'SignInForm.tsx'),
+  join(srcDir, 'features', 'auth', 'adapters', 'inbound', 'SignUpForm.tsx'),
+  join(srcDir, 'features', 'gradient', 'adapters', 'inbound', 'Gradient.tsx'),
+  join(srcDir, 'features', 'collection-editor', 'adapters', 'inbound', 'CollectionEditor.tsx'),
+  join(srcDir, 'features', 'empty-state', 'adapters', 'inbound', 'EmptyState.tsx'),
+  join(srcDir, 'features', 'list', 'adapters', 'inbound', 'List.tsx'),
+  join(srcDir, 'features', 'list', 'adapters', 'inbound', 'ListItem.tsx'),
+  join(srcDir, 'features', 'list', 'adapters', 'inbound', 'ListSection.tsx'),
+  join(srcDir, 'features', 'section', 'adapters', 'inbound', 'SectionHeader.tsx'),
+  join(srcDir, 'features', 'form', 'switch', 'adapters', 'inbound', 'Switch.tsx'),
+  join(srcDir, 'features', 'timeline', 'adapters', 'inbound', 'Timeline.tsx'),
+  join(srcDir, 'features', 'tree-view', 'adapters', 'inbound', 'TreeItem.tsx'),
+  join(srcDir, 'features', 'tree-view', 'adapters', 'inbound', 'TreeView.tsx'),
+
+  join(srcDir, 'features', 'layout', 'adapters', 'inbound', 'Divider.tsx'),
+  join(srcDir, 'features', 'layout', 'adapters', 'inbound', 'Grid.tsx'),
+  join(srcDir, 'features', 'surface', 'adapters', 'inbound', 'Surface.tsx'),
+] as const;
+
+const scopedPropTypeFiles = [
+  join(srcDir, 'types', 'layout.ts'),
+  join(srcDir, 'types', 'palette-item.ts'),
+  join(srcDir, 'types', 'app-bar.ts'),
+  join(srcDir, 'types', 'accordion.ts'),
+  join(srcDir, 'types', 'badge.ts'),
+  join(srcDir, 'types', 'breadcrumbs.ts'),
+  join(srcDir, 'types', 'button.ts'),
+  join(srcDir, 'types', 'button-group.ts'),
+  join(srcDir, 'types', 'card.ts'),
+  join(srcDir, 'types', 'media-card.ts'),
+  join(srcDir, 'types', 'metric-card.ts'),
+  join(srcDir, 'types', 'checkbox.ts'),
+  join(srcDir, 'types', 'date-picker.ts'),
+  join(srcDir, 'types', 'dialog.ts'),
+  join(srcDir, 'types', 'form.ts'),
+  join(srcDir, 'types', 'heading.ts'),
+  join(srcDir, 'types', 'icon.ts'),
+  join(srcDir, 'types', 'icon-button.ts'),
+  join(srcDir, 'types', 'pagination.ts'),
+  join(srcDir, 'types', 'popover-menu.ts'),
+  join(srcDir, 'types', 'progress.ts'),
+  join(srcDir, 'types', 'radio.ts'),
+  join(srcDir, 'types', 'rating.ts'),
+  join(srcDir, 'types', 'search-input.ts'),
+  join(srcDir, 'types', 'select.ts'),
+  join(srcDir, 'types', 'tabs.ts'),
+  join(srcDir, 'types', 'text-input.ts'),
+  join(srcDir, 'types', 'text.ts'),
+  join(srcDir, 'types', 'time-picker.ts'),
+  join(srcDir, 'types', 'toast.ts'),
+  join(srcDir, 'types', 'toolbar.ts'),
+
+  join(srcDir, 'types', 'auth.ts'),
+  join(srcDir, 'types', 'gradient.ts'),
+  join(srcDir, 'types', 'collection-editor.ts'),
+  join(srcDir, 'types', 'empty-state.ts'),
+  join(srcDir, 'types', 'list.ts'),
+  join(srcDir, 'types', 'section.ts'),
+  join(srcDir, 'types', 'switch.ts'),
+  join(srcDir, 'types', 'timeline.ts'),
+  join(srcDir, 'types', 'tree-view.ts'),
+] as const;
+
+describe('theme scope structure', () => {
+  it('keeps ZoraProvider lightweight (no extra ResponsiveProvider nesting)', () => {
+    expect(zoraProviderSource).toMatch(/ThemeProvider/);
+    expect(zoraProviderSource).toMatch(/<ZoraThemeRuntimeContext\s+value=/u);
+    expect(zoraProviderSource).not.toMatch(/ResponsiveProvider/);
+  });
+
+  it('delegates nested Surface runtime ownership to the public ThemeScope boundary', () => {
+    expect(themeScopeSource).toMatch(/import \{ ThemeScope \} from '@ankhorage\/surface'/u);
+    expect(themeScopeSource).toMatch(/<ThemeScope\s+mode=/u);
+    expect(themeScopeSource).not.toMatch(/ThemeContext/u);
+    expect(themeScopeSource).not.toMatch(/useFontContext/u);
+    expect(themeScopeSource).not.toMatch(/createTheme\(/u);
+    expect(themeScopeSource).not.toMatch(/_hasProvider/u);
+    expect(themeScopeSource).not.toMatch(/<ThemeProvider\b/u);
+  });
+
+  it('wraps components only when mode/themeId overrides are present', () => {
+    expect(hocSource).toMatch(/props\.mode === undefined/u);
+    expect(hocSource).toMatch(/props\.themeId === undefined/u);
+    expect(hocSource).toMatch(/<ZoraThemeScope/u);
+  });
+
+  it('adopts the inner + HOC pattern across the public surface', () => {
+    for (const filePath of scopedComponentFiles) {
+      const source = readFileSync(filePath, 'utf8');
+      expect(source).toMatch(/themeId: _themeId/u);
+      expect(source).toMatch(/mode: _mode/u);
+      expect(source).toMatch(/withZoraThemeScope/u);
+    }
+  });
+
+  it('adds ZoraBaseProps to public component prop types', () => {
+    for (const filePath of scopedPropTypeFiles) {
+      const source = readFileSync(filePath, 'utf8');
+      expect(source).toMatch(/ZoraBaseProps/u);
+      expect(source).toMatch(/extends\s+ZoraBaseProps|ZoraBaseProps\s*&|&\s*ZoraBaseProps/u);
+    }
+  });
+
+  it('does not implement theme scoping outside the theme module', () => {
+    for (const filePath of scopeGuardFiles) {
+      const source = readFileSync(filePath, 'utf8');
+      expect(source).not.toMatch(/<ThemeContext(?:\.Provider)?\b/u);
+      expect(source).not.toMatch(/ThemeProvider/u);
+      expect(source).not.toMatch(/<ZoraThemeScope/u);
+      expect(source).not.toMatch(/createTheme\(/u);
+    }
+  });
+
+  it('does not introduce a hook override API', () => {
+    const srcFiles = collectSourceFiles(srcDir);
+    for (const filePath of srcFiles) {
+      const source = readFileSync(filePath, 'utf8');
+      expect(source).not.toMatch(/useZoraTheme\(\s*\{/u);
+    }
+  });
+});

package/src/features/theme/utils/resolveThemeModeToggleState.ts

@@ -0,0 +1,21 @@
+import type { ZoraThemeMode } from '../../../types/theme';
+
+interface ThemeModeToggleState {
+  readonly iconName: 'moon-outline' | 'sunny-outline';
+  readonly label: 'Use dark mode' | 'Use light mode';
+  readonly nextMode: ZoraThemeMode;
+}
+
+export function resolveThemeModeToggleState(mode: ZoraThemeMode): ThemeModeToggleState {
+  return mode === 'dark'
+    ? {
+        iconName: 'sunny-outline',
+        label: 'Use light mode',
+        nextMode: 'light',
+      }
+    : {
+        iconName: 'moon-outline',
+        label: 'Use dark mode',
+        nextMode: 'dark',
+      };
+}

package/src/features/theme/utils/resolveZoraScopedThemeId.ts

@@ -0,0 +1,25 @@
+import type { ZoraThemeId } from '../../../types/theme';
+
+export function resolveZoraScopedThemeId({
+  desiredThemeId,
+  inheritedThemeId,
+}: {
+  desiredThemeId: ZoraThemeId | undefined;
+  inheritedThemeId: ZoraThemeId;
+}): ZoraThemeId {
+  if (desiredThemeId === undefined || desiredThemeId === inheritedThemeId) {
+    return inheritedThemeId;
+  }
+
+  const message = [
+    `Unknown ZORA theme id '${desiredThemeId}'.`,
+    'Theme registries are not available yet; register the theme before using themeId scopes.',
+  ].join(' ');
+
+  if (process.env.NODE_ENV === 'production') {
+    console.warn(message);
+    return inheritedThemeId;
+  }
+
+  throw new Error(message);
+}

package/src/features/theme/utils/resolveZoraThemeRecipe.ts

@@ -0,0 +1,91 @@
+import type { ThemeConfig, ThemeRecipeOverrideValue } from '@ankhorage/contracts';
+
+import type { ZoraThemeRecipeFieldMeta, ZoraThemeTokenFamily } from '../../../types/theme-recipe';
+import { ZORA_THEME_RECIPE_META } from '../../authoring/themeRecipeMeta';
+
+interface ZoraThemeRecipeRuntimeTheme {
+  readonly config: ThemeConfig;
+  readonly colors: object;
+  readonly spacing: object;
+  readonly radii: object;
+  readonly shadows: object;
+  readonly typography: {
+    readonly sizes: object;
+    readonly weights: object;
+    readonly headings: object;
+  };
+}
+
+const recipeMetaByName = new Map(Object.entries(ZORA_THEME_RECIPE_META));
+
+export function resolveZoraThemeRecipe(
+  theme: ZoraThemeRecipeRuntimeTheme,
+  recipeName: string,
+): Readonly<Record<string, ThemeRecipeOverrideValue>> {
+  const meta = recipeMetaByName.get(recipeName);
+  if (!meta) throw new RangeError(`Unknown ZORA theme recipe: ${recipeName}.`);
+
+  const recipes =
+    meta.kind === 'component' ? theme.config.recipes?.components : theme.config.recipes?.patterns;
+  const overrides = new Map(Object.entries(recipes ?? {})).get(recipeName);
+  const overrideByField = new Map(Object.entries(overrides ?? {}));
+  const resolved: [string, ThemeRecipeOverrideValue][] = [];
+
+  for (const [fieldName, fieldMeta] of Object.entries(meta.fields)) {
+    const override = overrideByField.get(fieldName);
+    if (override !== undefined) {
+      validateFieldValue(theme, recipeName, fieldName, fieldMeta, override);
+      resolved.push([fieldName, override]);
+    } else if (fieldMeta.default !== undefined) {
+      resolved.push([fieldName, fieldMeta.default]);
+    }
+  }
+
+  return Object.fromEntries(resolved);
+}
+
+function validateFieldValue(
+  theme: ZoraThemeRecipeRuntimeTheme,
+  recipeName: string,
+  fieldName: string,
+  meta: ZoraThemeRecipeFieldMeta,
+  value: ThemeRecipeOverrideValue,
+): void {
+  if (meta.type === 'boolean') {
+    if (typeof value !== 'boolean') {
+      throw new TypeError(`Theme recipe ${recipeName}.${fieldName} must be boolean.`);
+    }
+    return;
+  }
+  if (typeof value !== 'string') {
+    throw new TypeError(`Theme recipe ${recipeName}.${fieldName} must be a string.`);
+  }
+  if (meta.type === 'choice' && !meta.options.includes(value)) {
+    throw new RangeError(`Invalid theme recipe choice for ${recipeName}.${fieldName}: ${value}.`);
+  }
+  if (meta.type === 'token' && !hasThemeToken(theme, meta.tokenFamily, value)) {
+    throw new RangeError(
+      `Unknown ${meta.tokenFamily} token for ${recipeName}.${fieldName}: ${value}.`,
+    );
+  }
+}
+
+function hasThemeToken(
+  theme: ZoraThemeRecipeRuntimeTheme,
+  family: ZoraThemeTokenFamily,
+  token: string,
+): boolean {
+  if (family === 'colors') return hasOwn(theme.colors, token);
+  if (family === 'spacing') return hasOwn(theme.spacing, token);
+  if (family === 'radii') return hasOwn(theme.radii, token);
+  if (family === 'shadows') return hasOwn(theme.shadows, token);
+  return (
+    hasOwn(theme.typography.sizes, token) ||
+    hasOwn(theme.typography.weights, token) ||
+    hasOwn(theme.typography.headings, token)
+  );
+}
+
+function hasOwn(value: object, key: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}

package/src/features/theme/zoraDefaultTheme.ts

@@ -0,0 +1,9 @@
+import type { ZoraTheme } from '../../types/theme';
+
+export const zoraDefaultTheme: ZoraTheme = {
+  id: 'zora',
+  name: 'ZORA',
+  appCategory: 'developer_tools',
+  primaryColor: '#0f766e',
+  harmony: 'analogous',
+};

package/src/features/time-picker/adapters/inbound/TimePicker.native.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { TimePickerProps } from '../../../../types/time-picker';
 import { useBottomSheet } from '../../../bottom-sheet/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { TimePickerContent } from '../../composition/TimePickerContent';
 import { TimePickerField } from '../../composition/TimePickerField';
 import { TimePickerTrigger } from '../../composition/TimePickerTrigger';

package/src/features/time-picker/adapters/inbound/TimePicker.web.tsx

@@ -1,9 +1,9 @@
 import { Popover } from '@ankhorage/surface';
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { TimePickerProps } from '../../../../types/time-picker';
 import { Surface } from '../../../surface/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { TimePickerContent } from '../../composition/TimePickerContent';
 import { TimePickerField } from '../../composition/TimePickerField';
 import { TimePickerTrigger } from '../../composition/TimePickerTrigger';

package/src/features/time-picker/public.test.ts

@@ -1,6 +1,6 @@
 import { expect, test } from 'bun:test';
 
-import { ZORA_COMPONENT_META } from '../../metadata/componentMeta';
+import { ZORA_COMPONENT_META } from '../authoring/componentMeta';
 
 test('TimePicker keeps one manifest contract across native and web presentation hosts', async () => {
   const nativeSource = await Bun.file(

package/src/features/time-picker/timePickerMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 export const timePickerMeta = {
   name: 'TimePicker',

package/src/features/timeline/adapters/inbound/Timeline.tsx

@@ -0,0 +1,127 @@
+import type { RoleSemantics, SurfaceTheme } from '@ankhorage/surface';
+import React from 'react';
+
+import type { ZoraColor } from '../../../../types/theme';
+import type { TimelineItem, TimelineProps } from '../../../../types/timeline';
+import { Icon } from '../../../icon/public';
+import { resolveIconSize } from '../../../icon/utils/resolveIconSize';
+import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
+import { Heading } from '../../../typography/public';
+import { Text } from '../../../typography/public';
+
+function resolveRoleSemantics(theme: SurfaceTheme, color: ZoraColor): RoleSemantics {
+  switch (color) {
+    case 'secondary':
+      return theme.semantics.secondary;
+    case 'tertiary':
+      return theme.semantics.accent;
+    case 'quaternary':
+      return theme.semantics.highlight;
+    case 'error':
+      return theme.semantics.error;
+    case 'info':
+      return theme.semantics.info;
+    case 'primary':
+      return theme.semantics.action.primary;
+    case 'danger':
+      return theme.semantics.action.danger;
+    case 'success':
+      return theme.semantics.success;
+    case 'warning':
+      return theme.semantics.warning;
+    case 'neutral':
+    default:
+      return theme.semantics.action.neutral;
+  }
+}
+
+function TimelineInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy: _interactionPolicy,
+  testID,
+  items,
+  compact = false,
+}: TimelineProps) {
+  const { theme } = useZoraTheme();
+  const gap = compact ? 'm' : 'l';
+  const connectorHeight = compact ? 20 : 36;
+
+  const renderItem = (item: TimelineItem, index: number) => {
+    const status = item.status ?? 'neutral';
+    const role = resolveRoleSemantics(theme, status);
+    const showConnector = index < items.length - 1;
+    const iconSize = Math.max(12, resolveIconSize('s'));
+
+    return (
+      <View
+        direction="row"
+        key={item.id}
+        align="flex-start"
+        gap="m"
+        testID={item.testID}
+        wrap="nowrap"
+      >
+        <View align="center" flexShrink={0} gap="xs" style={{ width: 24 }}>
+          <View
+            bg={status === 'neutral' ? theme.semantics.neutral.surface : role.softBg}
+            borderColor={status === 'neutral' ? theme.semantics.neutral.divider : role.base}
+            borderWidth={1}
+            height={20}
+            radius="full"
+            width={20}
+            style={{ alignItems: 'center', justifyContent: 'center' }}
+          >
+            {item.icon ? (
+              <Icon
+                {...item.icon}
+                color={status === 'neutral' ? theme.semantics.content.muted : role.base}
+                size={iconSize}
+              />
+            ) : null}
+          </View>
+
+          {showConnector ? (
+            <View
+              bg={theme.semantics.neutral.divider}
+              height={connectorHeight}
+              radius="full"
+              style={{ width: 2 }}
+            />
+          ) : null}
+        </View>
+
+        <View flex={1} gap="xs" testID={testID}>
+          <View direction="row" align="flex-start" gap="s" justify="space-between" wrap="wrap">
+            <Heading level={compact ? 4 : 3}>{item.title}</Heading>
+            {item.meta ? (
+              <Text emphasis="muted" variant="caption">
+                {item.meta}
+              </Text>
+            ) : null}
+          </View>
+          {item.description ? (
+            <Text emphasis="muted" variant="bodySmall">
+              {item.description}
+            </Text>
+          ) : null}
+        </View>
+      </View>
+    );
+  };
+
+  return (
+    <View gap={gap} testID={testID}>
+      {items.map(renderItem)}
+    </View>
+  );
+}
+
+/***
+ * Timeline pattern for displaying a sequence of events.
+ *
+ 
+ */
+export const Timeline = withZoraThemeScope(TimelineInner);

package/src/features/timeline/meta.ts

@@ -0,0 +1,10 @@
+import type { ZoraComponentMeta } from '../authoring';
+
+export const timelineMeta = {
+  name: 'Timeline',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Timeline pattern component; not represented as a manifest node in v1.',
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/features/timeline/public.ts

@@ -0,0 +1,2 @@
+export type { TimelineItem, TimelineProps } from '../../types/timeline';
+export { Timeline } from './adapters/inbound/Timeline';

package/src/features/toast/adapters/inbound/Toast.tsx

@@ -1,8 +1,8 @@
 import { Toast as SurfaceToast } from '@ankhorage/surface';
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { ToastProps } from '../../../../types/toast';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Renders a toast notification message with ZORA theme scoping. */
 export const Toast = withZoraThemeScope(ToastInner);

package/src/features/toast/public.test.ts

@@ -1,13 +1,13 @@
 import { expect, test } from 'bun:test';
 
-import { ZORA_COMPONENT_META } from '../../metadata/componentMeta';
+import { ZORA_COMPONENT_META } from '../authoring/componentMeta';
 
 test('Toast stays imperative and installs its host only when the ZoraProvider capability is enabled', async () => {
   const [publicSource, providerSource, webCapabilities, nativeCapabilities] = await Promise.all([
     Bun.file('src/features/toast/public.ts').text(),
-    Bun.file('src/theme/ZoraProvider.tsx').text(),
-    Bun.file('src/theme/ZoraRuntimeCapabilities.web.tsx').text(),
-    Bun.file('src/theme/ZoraRuntimeCapabilities.native.tsx').text(),
+    Bun.file('src/features/theme/adapters/inbound/ZoraProvider.tsx').text(),
+    Bun.file('src/features/theme/composition/ZoraRuntimeCapabilities.web.tsx').text(),
+    Bun.file('src/features/theme/composition/ZoraRuntimeCapabilities.native.tsx').text(),
   ]);
 
   expect(ZORA_COMPONENT_META.Toast?.directManifestNode).toBe(false);

package/src/features/toast/toastMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 export const toastMeta = {
   name: 'Toast',

package/src/features/toast/toastProviderMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 export const toastProviderMeta = {
   name: 'ToastProvider',

package/src/features/toolbar/adapters/inbound/Toolbar.tsx

@@ -1,7 +1,7 @@
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { ToolbarProps } from '../../../../types/toolbar';
 import { Card } from '../../../card/public';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Renders a visible horizontal group of contextual actions and controls. */
 export const Toolbar = withZoraThemeScope(ToolbarInner);

package/src/features/toolbar/toolbarMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 
 export const toolbarMeta = {
   name: 'Toolbar',