@ankhorage/zora 1.0.0 → 1.0.2

package/src/audit.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Plan 5 — Semantic theme usage audit regression guards.
+ *
+ * These tests verify that stale or forbidden APIs from before Plan 3/4 do not
+ * re-appear in the ZORA source, examples, or public exports.
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+const ROOT = process.cwd();
+const SRC_ROOT = join(ROOT, 'src');
+const EXAMPLES_ROOT = join(ROOT, 'examples');
+const README_PATH = join(ROOT, 'README.md');
+const PACKAGE_JSON_PATH = join(ROOT, 'package.json');
+
+const IGNORED_DIRECTORY_NAMES = new Set([
+  '.expo',
+  '.git',
+  '.turbo',
+  '.vercel',
+  'coverage',
+  'dist',
+  'node_modules',
+]);
+
+function listFiles(root: string, excludeTests = false): string[] {
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.isDirectory() && IGNORED_DIRECTORY_NAMES.has(entry.name)) {
+      return [];
+    }
+
+    const absolutePath = join(root, entry.name);
+    if (entry.isDirectory()) {
+      return listFiles(absolutePath, excludeTests);
+    }
+
+    if (!entry.isFile() || !/\.[cm]?tsx?$/.test(entry.name)) {
+      return [];
+    }
+
+    if (excludeTests && /\.test\.[cm]?tsx?$/.test(entry.name)) {
+      return [];
+    }
+
+    return [absolutePath];
+  });
+}
+
+function readSource(root: string, excludeTests = false): string {
+  return listFiles(root, excludeTests)
+    .map((filePath) => readFileSync(filePath, 'utf8'))
+    .join('\n');
+}
+
+function isPathWithin(filePath: string, directoryPath: string): boolean {
+  return filePath === directoryPath || filePath.startsWith(`${directoryPath}/`);
+}
+
+const srcSource = readSource(SRC_ROOT, true); // exclude test files from stale-API scan
+const examplesSource = readSource(EXAMPLES_ROOT);
+const readmeSource = readFileSync(README_PATH, 'utf8');
+const packageJsonSource = readFileSync(PACKAGE_JSON_PATH, 'utf8');
+
+const allSource = [srcSource, examplesSource, readmeSource, packageJsonSource].join('\n');
+
+describe('Plan 5 audit — no stale color-tone APIs', () => {
+  test('no ColorTone / colorTone / ZORA_COLOR_TONES / ZoraColorTone references', () => {
+    expect(allSource).not.toMatch(/ColorTone|colorTone|ZORA_COLOR_TONES|ZoraColorTone/);
+  });
+
+  test('no ZORA_COLOR_HARMONIES / ZoraColorHarmony references', () => {
+    expect(allSource).not.toMatch(/ZORA_COLOR_HARMONIES|ZoraColorHarmony/);
+  });
+
+  test('no ZoraHexColor references', () => {
+    expect(allSource).not.toMatch(/ZoraHexColor/);
+  });
+
+  test('no AnkhTheme references', () => {
+    expect(allSource).not.toMatch(/AnkhTheme/);
+  });
+
+  test('no direct culori imports', () => {
+    expect(allSource).not.toMatch(/from 'culori'|from "culori"/);
+    // also check package.json does not list culori as a direct dependency
+    // (it may appear in the source text via color-theory transitive deps, but
+    // ZORA must not import it directly)
+    const pkg = JSON.parse(packageJsonSource) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    expect(Object.keys(pkg.dependencies ?? {})).not.toContain('culori');
+    expect(Object.keys(pkg.devDependencies ?? {})).not.toContain('culori');
+  });
+
+  test('no ThemeComposerRecommendation / suggestedColorTone / hueDegreesToZoraHexColor / generatedColorRoles', () => {
+    expect(allSource).not.toMatch(
+      /ThemeComposerRecommendation|suggestedColorTone|hueDegreesToZoraHexColor|generatedColorRoles/,
+    );
+  });
+
+  test('no ColorMood / AppMood / APP_MOODS references', () => {
+    expect(allSource).not.toMatch(/ColorMood|colorMood|AppMood|appMood|APP_MOODS/);
+  });
+});
+
+describe('Plan 5 audit — no showcase bridge or direct Surface imports in examples', () => {
+  test('examples do not use a local zora bridge (./zora, ../zora, ../../zora)', () => {
+    expect(examplesSource).not.toMatch(/from ['"]\.\.?\/.*zora['"]/);
+  });
+
+  test('examples do not import from @ankhorage/surface directly', () => {
+    expect(examplesSource).not.toContain("from '@ankhorage/surface'");
+    expect(examplesSource).not.toContain('from "@ankhorage/surface"');
+  });
+});
+
+describe('Plan 5 audit — product-facing src imports ZORA foundation, not Surface directly', () => {
+  /**
+   * Components, layouts, and patterns that compose ZORA primitives should import
+   * foundation primitives from the local ZORA foundation layer, not directly
+   * from @ankhorage/surface.
+   *
+   * Foundation wrappers, theme infrastructure, internal recipes, and explicit
+   * Surface-wrapping boundary components are exempt.
+   */
+  const EXEMPT_PATHS = new Set([
+    // Foundation wrappers — they ARE the Surface abstraction layer.
+    join(SRC_ROOT, 'foundation'),
+    // Theme infrastructure legitimately integrates with Surface theme/runtime types.
+    join(SRC_ROOT, 'theme'),
+    // Internal recipes may consume SurfaceTheme types as the typed recipe boundary.
+    join(SRC_ROOT, 'internal'),
+    // Explicit Surface primitive wrappers.
+    join(SRC_ROOT, 'components', 'checkbox', 'Checkbox.tsx'),
+    join(SRC_ROOT, 'components', 'icon', 'Icon.tsx'),
+    join(SRC_ROOT, 'components', 'icon-button', 'IconButton.tsx'),
+    join(SRC_ROOT, 'components', 'modal', 'Modal.tsx'),
+    join(SRC_ROOT, 'components', 'textarea', 'Textarea.tsx'),
+    join(SRC_ROOT, 'components', 'text', 'Text.tsx'),
+    join(SRC_ROOT, 'components', 'form', 'FormField.tsx'),
+    join(SRC_ROOT, 'patterns', 'form-field', 'FormField.tsx'),
+    // Type-only imports that intentionally expose Surface-compatible prop specs.
+    join(SRC_ROOT, 'components', 'checkbox', 'types.ts'),
+    join(SRC_ROOT, 'components', 'form', 'types.ts'),
+    join(SRC_ROOT, 'components', 'icon-button', 'types.ts'),
+    join(SRC_ROOT, 'components', 'tabs', 'types.ts'),
+    join(SRC_ROOT, 'components', 'text', 'types.ts'),
+    join(SRC_ROOT, 'components', 'textarea', 'types.ts'),
+    join(SRC_ROOT, 'components', 'toolbar', 'types.ts'),
+    join(SRC_ROOT, 'patterns', 'form-field', 'types.ts'),
+    join(SRC_ROOT, 'patterns', 'tile-grid', 'types.ts'),
+  ]);
+
+  function isExempt(filePath: string): boolean {
+    for (const exemptPath of EXEMPT_PATHS) {
+      if (isPathWithin(filePath, exemptPath)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  const PRODUCT_FACING_DIRS = [
+    join(SRC_ROOT, 'components'),
+    join(SRC_ROOT, 'layout'),
+    join(SRC_ROOT, 'patterns'),
+  ];
+
+  const FOUNDATION_PRIMITIVES_PATTERN =
+    /import \{[^}]*\b(Box|Stack|Center|Container|Grid|Inline|Spacer|Divider)\b[^}]*\} from '@ankhorage\/surface'/;
+
+  test('component, layout, and pattern files do not import foundation primitives directly from @ankhorage/surface', () => {
+    for (const dir of PRODUCT_FACING_DIRS) {
+      for (const filePath of listFiles(dir)) {
+        if (isExempt(filePath)) continue;
+
+        const source = readFileSync(filePath, 'utf8');
+        const match = FOUNDATION_PRIMITIVES_PATTERN.exec(source);
+
+        expect(
+          match,
+          `${filePath} imports Surface foundation primitive '${match?.[1]}' directly. ` +
+            `Use the ZORA foundation import ('../../foundation') instead.`,
+        ).toBeNull();
+      }
+    }
+  });
+});
+
+describe('Plan 5 audit — no hard-coded runtime colors', () => {
+  const RUNTIME_COLOR_LITERAL_PATTERN = /#[0-9A-Fa-f]{3,8}|rgba?\(|hsla?\(/;
+  const EXEMPT_COLOR_LITERAL_FILES = new Set([
+    // This is source-theme data, not component chrome. Plan 5 explicitly allows theme seed literals.
+    join(SRC_ROOT, 'theme', 'zoraDefaultTheme.ts'),
+  ]);
+
+  test('non-test src files do not contain raw runtime color literals', () => {
+    for (const filePath of listFiles(SRC_ROOT, true)) {
+      if (EXEMPT_COLOR_LITERAL_FILES.has(filePath)) continue;
+
+      const source = readFileSync(filePath, 'utf8');
+      const match = RUNTIME_COLOR_LITERAL_PATTERN.exec(source);
+
+      expect(
+        match,
+        `${filePath} contains raw runtime color literal '${match?.[0]}'. ` +
+          'Use a theme token, recipe, or explicit documented exemption instead.',
+      ).toBeNull();
+    }
+  });
+});
+
+describe('Plan 5 audit — public exports carry no legacy types', () => {
+  test('src/index.ts does not export ZoraHexColor', () => {
+    const indexSource = readFileSync(join(SRC_ROOT, 'index.ts'), 'utf8');
+
+    expect(indexSource).not.toContain('ZoraHexColor');
+  });
+
+  test('src/index.ts does not export ZoraColorTone or ZORA_COLOR_TONES', () => {
+    const indexSource = readFileSync(join(SRC_ROOT, 'index.ts'), 'utf8');
+
+    expect(indexSource).not.toMatch(/ZoraColorTone|ZORA_COLOR_TONES/);
+  });
+
+  test('src/index.ts does not export ZoraColorHarmony or ZORA_COLOR_HARMONIES', () => {
+    const indexSource = readFileSync(join(SRC_ROOT, 'index.ts'), 'utf8');
+
+    expect(indexSource).not.toMatch(/ZoraColorHarmony|ZORA_COLOR_HARMONIES/);
+  });
+
+  test('src/index.ts does not export AnkhTheme', () => {
+    const indexSource = readFileSync(join(SRC_ROOT, 'index.ts'), 'utf8');
+
+    expect(indexSource).not.toContain('AnkhTheme');
+  });
+});

package/src/components/card/Card.tsx

@@ -1,6 +1,7 @@
-import { Box, Card as SurfaceCard, Stack } from '@ankhorage/surface';
+import { Card as SurfaceCard } from '@ankhorage/surface';
 import React from 'react';
 
+import { Box, Stack } from '../../foundation';
 import { resolveCardVariant } from '../../internal/recipes';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Heading } from '../heading';

package/src/components/checkbox/CheckboxGroup.tsx

@@ -1,7 +1,8 @@
-import { Checkbox, Stack } from '@ankhorage/surface';
+import { Checkbox } from '@ankhorage/surface';
 import React from 'react';
 import { View } from 'react-native';
 
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Text } from '../text';
 import type { CheckboxGroupOption, CheckboxGroupProps } from './types';

package/src/components/drawer/Drawer.tsx

@@ -1,6 +1,7 @@
-import { Box, Drawer as SurfaceDrawer, Stack } from '@ankhorage/surface';
+import { Drawer as SurfaceDrawer } from '@ankhorage/surface';
 import React, { useCallback, useEffect, useRef } from 'react';
 
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Heading } from '../heading';
 import { Text } from '../text';

package/src/components/form/Form.tsx

@@ -1,6 +1,6 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { FormActions } from './FormActions';
 import { FormError } from './FormError';

package/src/components/form/FormActions.tsx

@@ -1,6 +1,6 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Button } from '../button';
 import type { FormActionsProps } from './types';

package/src/components/form/FormError.tsx

@@ -1,6 +1,6 @@
-import { Box } from '@ankhorage/surface';
 import React from 'react';
 
+import { Box } from '../../foundation';
 import { useZoraTheme } from '../../theme/useZoraTheme';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Text } from '../text';

package/src/components/form/FormField.tsx

@@ -1,6 +1,7 @@
-import { Field, Stack } from '@ankhorage/surface';
+import { Field } from '@ankhorage/surface';
 import React from 'react';
 
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Input } from '../input';
 import { Text } from '../text';

package/src/components/modal/Modal.tsx

@@ -1,6 +1,7 @@
-import { Box, Modal as SurfaceModal, Stack } from '@ankhorage/surface';
+import { Modal as SurfaceModal } from '@ankhorage/surface';
 import React, { useCallback, useEffect, useRef } from 'react';
 
+import { Box, Stack } from '../../foundation';
 import { resolveDialogWidth } from '../../internal/recipes';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Heading } from '../heading';

package/src/components/radio/RadioGroup.tsx

@@ -1,7 +1,8 @@
-import { Radio, Stack } from '@ankhorage/surface';
+import { Radio } from '@ankhorage/surface';
 import React from 'react';
 import { View } from 'react-native';
 
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Text } from '../text';
 import type { RadioGroupOption, RadioGroupProps } from './types';

package/src/components/select/Select.tsx

@@ -1,7 +1,7 @@
-import { Box } from '@ankhorage/surface';
 import { Picker } from '@react-native-picker/picker';
 import React from 'react';
 
+import { Box } from '../../foundation';
 import { useZoraTheme } from '../../theme/useZoraTheme';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { SelectProps } from './types';

package/src/components/tabs/Tabs.tsx

@@ -1,6 +1,6 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
+import { Box, Stack } from '../../foundation';
 import { useZoraTheme } from '../../theme/useZoraTheme';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Button } from '../button';

package/src/components/toolbar/Toolbar.tsx

@@ -1,6 +1,6 @@
-import { Stack } from '@ankhorage/surface';
 import React from 'react';
 
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Card } from '../card';
 import type { ToolbarProps } from './types';

package/src/layout/app-shell/AppShell.tsx

@@ -1,7 +1,7 @@
-import { Box } from '@ankhorage/surface';
 import React from 'react';
 import { StyleSheet, View } from 'react-native';
 
+import { Box } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { AppShellProps } from './types';
 

package/src/layout/auth-layout/AuthLayout.tsx

@@ -1,7 +1,7 @@
-import { Center, Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Card } from '../../components/card';
+import { Center, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { AuthLayoutProps } from './types';
 

package/src/layout/page/Page.tsx

@@ -1,6 +1,6 @@
-import { Container, Stack } from '@ankhorage/surface';
 import React from 'react';
 
+import { Container, Stack } from '../../foundation';
 import { resolvePageMaxWidth } from '../../internal/recipes';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { PageProps } from './types';

package/src/layout/page-header/PageHeader.tsx

@@ -1,8 +1,8 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Heading } from '../../components/heading';
 import { Text } from '../../components/text';
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { PageHeaderProps } from './types';
 

package/src/layout/page-section/PageSection.tsx

@@ -1,6 +1,6 @@
-import { Stack } from '@ankhorage/surface';
 import React from 'react';
 
+import { Stack } from '../../foundation';
 import { SectionHeader } from '../../patterns/section-header';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { PageSectionProps } from './types';

package/src/layout/sidebar-layout/SidebarLayout.tsx

@@ -1,6 +1,6 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { SidebarLayoutProps } from './types';
 

package/src/layout/topbar-layout/TopbarLayout.tsx

@@ -1,6 +1,6 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { SidebarLayout } from '../sidebar-layout';
 import type { TopbarLayoutProps } from './types';

package/src/patterns/auth/ForgotPasswordForm.tsx

@@ -1,8 +1,8 @@
-import { Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Button } from '../../components/button';
 import { Form, type FormFieldConfig, type FormValues } from '../../components/form';
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { ForgotPasswordFormProps } from './types';
 import {

package/src/patterns/auth/OtpForm.tsx

@@ -1,8 +1,8 @@
-import { Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Button } from '../../components/button';
 import { Form, type FormFieldConfig, type FormValues } from '../../components/form';
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { OtpFormProps } from './types';
 

package/src/patterns/auth/SignInForm.tsx

@@ -1,8 +1,8 @@
-import { Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Button } from '../../components/button';
 import { Form, type FormFieldConfig, type FormValues } from '../../components/form';
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { SignInFormProps } from './types';
 import {

package/src/patterns/auth/SignUpForm.tsx

@@ -1,8 +1,8 @@
-import { Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Button } from '../../components/button';
 import { Form, type FormFieldConfig, type FormValues } from '../../components/form';
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { SignUpFormProps } from './types';
 

package/src/patterns/collection-editor/CollectionEditor.tsx

@@ -1,9 +1,9 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Button } from '../../components/button';
 import { IconButton } from '../../components/icon-button';
 import { Text } from '../../components/text';
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Panel } from '../panel';
 import type { CollectionEditorProps } from './types';

package/src/patterns/confirm-dialog/ConfirmDialog.tsx

@@ -1,8 +1,8 @@
-import { Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Button } from '../../components/button';
 import { Modal } from '../../components/modal';
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { ConfirmDialogProps } from './types';
 

package/src/patterns/disclosure-section/DisclosureSection.tsx

@@ -1,7 +1,7 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { IconButton } from '../../components/icon-button';
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Panel } from '../panel';
 import type { DisclosureSectionProps } from './types';

package/src/patterns/empty-state/EmptyState.tsx

@@ -1,8 +1,8 @@
-import { Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Button } from '../../components/button';
 import { Card } from '../../components/card';
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { EmptyStateProps } from './types';
 

package/src/patterns/form-field/FormField.tsx

@@ -1,7 +1,8 @@
-import { Field, Stack } from '@ankhorage/surface';
+import { Field } from '@ankhorage/surface';
 import React from 'react';
 
 import { Text } from '../../components/text';
+import { Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { FormFieldProps } from './types';
 

package/src/patterns/inspector-field/InspectorField.tsx

@@ -1,6 +1,6 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { FormField } from '../form-field';
 import type { InspectorFieldProps } from './types';

package/src/patterns/notice/Notice.tsx

@@ -1,8 +1,8 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Badge } from '../../components/badge';
 import { Card } from '../../components/card';
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { NoticeProps } from './types';
 

package/src/patterns/section-header/SectionHeader.tsx

@@ -1,8 +1,8 @@
-import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { Heading } from '../../components/heading';
 import { Text } from '../../components/text';
+import { Box, Stack } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { SectionHeaderProps } from './types';
 

package/src/patterns/settings-row/SettingsRow.tsx

@@ -1,8 +1,8 @@
-import { Box } from '@ankhorage/surface';
 import React from 'react';
 
 import { Card } from '../../components/card';
 import { Text } from '../../components/text';
+import { Box } from '../../foundation';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { SettingsRowProps } from './types';