@ankhorage/zora 0.16.2 → 1.0.1

package/src/patterns/theme-composer/ThemeComposer.test.ts

@@ -1,25 +1,24 @@
+import { COLOR_HARMONIES, parseHexColorOrThrow } from '@ankhorage/color-theory';
+import { APP_CATEGORIES } from '@ankhorage/contracts';
 import { describe, expect, test } from 'bun:test';
 
-import { ZORA_COLOR_HARMONIES, ZORA_COLOR_TONES } from '../../theme/types';
 import { zoraDefaultTheme } from '../../theme/zoraDefaultTheme';
-import {
-  createThemeFromThemeComposerRecommendation,
-  findThemeComposerRecommendation,
-  formatThemeComposerLabel,
-  hueDegreesToZoraHexColor,
-} from './recommendations';
-import type { ThemeComposerProps, ThemeComposerRecommendation } from './types';
-
-// Validate the exported types compile correctly by asserting shape
+import type { ThemeComposerProps } from './types';
+
+// ---------------------------------------------------------------------------
+// ThemeComposerProps shape tests
+// ---------------------------------------------------------------------------
+
 describe('ThemeComposerProps', () => {
   test('accepts a valid ZoraTheme as value', () => {
     const props: ThemeComposerProps = {
       value: zoraDefaultTheme,
       onChange: () => undefined,
     };
-    expect(props.value.primaryColor).toBe('#0f766e');
+    expect(props.value.primaryColor).toBe(zoraDefaultTheme.primaryColor);
     expect(props.value.harmony).toBe('analogous');
-    expect(props.value.colorTone).toBe('jewel');
+    expect(props.value.appCategory).toBe('developer_tools');
+    expect(props.value.name).toBe('ZORA');
   });
 
   test('accepts optional mode and onModeChange', () => {
@@ -45,58 +44,71 @@ describe('ThemeComposerProps', () => {
     expect(submitted).toBe(true);
   });
 
-  test('accepts optional recommendation inputs', () => {
-    const recommendation: ThemeComposerRecommendation = {
-      appCategory: 'finance_money',
-      appMood: 'trustworthy',
-      suggestedColorTone: 'mineral',
-      suggestedHarmony: 'analogous',
-      suggestedPrimaryHueDegrees: 195,
-    };
+  test('accepts optional appCategories as option list override', () => {
+    const narrow = ['developer_tools', 'utilities_tools'] as const;
     const props: ThemeComposerProps = {
       value: zoraDefaultTheme,
       onChange: () => undefined,
-      appCategory: 'finance_money',
-      appMood: 'trustworthy',
-      recommendations: [recommendation],
+      appCategories: narrow,
     };
-
-    expect(props.recommendations?.[0]?.suggestedColorTone).toBe('mineral');
+    expect(props.appCategories).toEqual(narrow);
   });
 });
 
-describe('ZORA_COLOR_HARMONIES coverage for ThemeComposer', () => {
-  test('all harmony values are present for the Select options', () => {
+// ---------------------------------------------------------------------------
+// COLOR_HARMONIES coverage
+// ---------------------------------------------------------------------------
+
+describe('COLOR_HARMONIES coverage for ThemeComposer', () => {
+  test('all canonical harmony values are present for the Select options', () => {
     const expected = [
       'monochromatic',
       'analogous',
       'complementary',
-      'splitComplementary',
       'triadic',
       'tetradic',
+      'splitComplementary',
     ] as const;
-    expect(ZORA_COLOR_HARMONIES).toEqual(expected);
+    expect(COLOR_HARMONIES).toEqual(expected);
   });
 });
 
-describe('ZORA_COLOR_TONES coverage for ThemeComposer', () => {
-  test('all color tones are present for the Select options', () => {
-    const expected = [
-      'neutral',
-      'pastel',
-      'earth',
-      'mineral',
-      'muted',
-      'jewel',
-      'fluorescent',
-      'obsidian',
-      'vaporwave',
-      'monochromeAccent',
-    ] as const;
-    expect(ZORA_COLOR_TONES).toEqual(expected);
+// ---------------------------------------------------------------------------
+// APP_CATEGORIES default behavior
+// ---------------------------------------------------------------------------
+
+describe('APP_CATEGORIES defaults', () => {
+  test('APP_CATEGORIES from contracts contains expected entries', () => {
+    expect(APP_CATEGORIES).toContain('developer_tools');
+    expect(APP_CATEGORIES).toContain('utilities_tools');
+    expect(APP_CATEGORIES).toContain('lifestyle');
+  });
+
+  test('ThemeComposer appCategories prop is optional — falls back to APP_CATEGORIES', () => {
+    const props: ThemeComposerProps = {
+      value: zoraDefaultTheme,
+      onChange: () => undefined,
+    };
+    // No appCategories provided — component uses APP_CATEGORIES internally.
+    expect(props.appCategories).toBeUndefined();
+  });
+
+  test('ThemeComposer appCategories narrows the available options when provided', () => {
+    const narrow = ['developer_tools', 'utilities_tools'] as const;
+    const props: ThemeComposerProps = {
+      value: zoraDefaultTheme,
+      onChange: () => undefined,
+      appCategories: narrow,
+    };
+    expect(props.appCategories).toHaveLength(2);
+    expect(props.appCategories).toContain('developer_tools');
   });
 });
 
+// ---------------------------------------------------------------------------
+// onChange propagation contracts
+// ---------------------------------------------------------------------------
+
 describe('onChange propagation contract', () => {
   test('onChange receives updated theme with new harmony', () => {
     const received: (typeof zoraDefaultTheme)[] = [];
@@ -110,93 +122,95 @@ describe('onChange propagation contract', () => {
     expect(received[0]?.harmony).toBe('triadic');
   });
 
-  test('onChange receives updated theme with new colorTone', () => {
+  test('onChange receives updated theme with new appCategory', () => {
     const received: (typeof zoraDefaultTheme)[] = [];
     const props: ThemeComposerProps = {
       value: zoraDefaultTheme,
       onChange: (t) => received.push(t),
     };
-    props.onChange({ ...zoraDefaultTheme, colorTone: 'obsidian' });
-    expect(received[0]?.colorTone).toBe('obsidian');
+    props.onChange({ ...zoraDefaultTheme, appCategory: 'lifestyle' });
+    expect(received).toHaveLength(1);
+    expect(received[0]?.appCategory).toBe('lifestyle');
   });
-});
-
-describe('ThemeComposer recommendation helpers', () => {
-  const recommendations: readonly ThemeComposerRecommendation[] = [
-    {
-      appCategory: 'finance_money',
-      appMood: 'trustworthy',
-      suggestedColorTone: 'mineral',
-      suggestedHarmony: 'analogous',
-      suggestedPrimaryHueDegrees: 195,
-    },
-    {
-      appCategory: 'graphics_design',
-      appMood: 'creative',
-      suggestedColorTone: 'vaporwave',
-      suggestedHarmony: 'splitComplementary',
-    },
-  ];
-
-  test('finds a recommendation by app category and mood', () => {
-    const found = findThemeComposerRecommendation({
-      appCategory: 'finance_money',
-      appMood: 'trustworthy',
-      recommendations,
-    });
-
-    expect(found?.suggestedColorTone).toBe('mineral');
-  });
-
-  test('does not find a recommendation with mismatched mood', () => {
-    const found = findThemeComposerRecommendation({
-      appCategory: 'finance_money',
-      appMood: 'creative',
-      recommendations,
-    });
-
-    expect(found).toBeUndefined();
-  });
-
-  test('creates an updated theme only when recommendation is explicitly applied', () => {
-    const [recommendation] = recommendations;
-    if (recommendation === undefined) {
-      throw new Error('Expected fixture recommendation.');
-    }
 
-    const updated = createThemeFromThemeComposerRecommendation({
+  test('onChange receives updated theme with new valid name', () => {
+    const received: (typeof zoraDefaultTheme)[] = [];
+    const props: ThemeComposerProps = {
       value: zoraDefaultTheme,
-      recommendation,
-    });
+      onChange: (t) => received.push(t),
+    };
+    props.onChange({ ...zoraDefaultTheme, name: 'My Custom Theme' });
+    expect(received).toHaveLength(1);
+    expect(received[0]?.name).toBe('My Custom Theme');
+  });
 
-    expect(zoraDefaultTheme.colorTone).toBe('jewel');
-    expect(updated.colorTone).toBe('mineral');
-    expect(updated.harmony).toBe('analogous');
-    expect(updated.primaryColor).not.toBe(zoraDefaultTheme.primaryColor);
+  test('onChange is not called with an empty name', () => {
+    // Simulate the component's name validation logic
+    const received: (typeof zoraDefaultTheme)[] = [];
+    const onChange = (t: typeof zoraDefaultTheme) => received.push(t);
+
+    const newName = '';
+    if (newName.trim().length > 0) {
+      onChange({ ...zoraDefaultTheme, name: newName });
+    }
+    // Empty name should not propagate
+    expect(received).toHaveLength(0);
   });
 
-  test('keeps the current primary color when recommendation has no hue', () => {
-    const [, recommendation] = recommendations;
-    if (recommendation === undefined) {
-      throw new Error('Expected fixture recommendation.');
+  test('onChange is not called with invalid primary color', () => {
+    // Simulate the component's hex validation logic
+    const received: (typeof zoraDefaultTheme)[] = [];
+    const onChange = (t: typeof zoraDefaultTheme) => received.push(t);
+
+    const badColor = '#xyz';
+    try {
+      parseHexColorOrThrow(badColor);
+      // Should not reach here for an invalid color
+      onChange({ ...zoraDefaultTheme, primaryColor: badColor });
+    } catch {
+      // Expected: invalid color — do not call onChange
     }
+    expect(received).toHaveLength(0);
+  });
 
-    const updated = createThemeFromThemeComposerRecommendation({
-      value: zoraDefaultTheme,
-      recommendation,
-    });
+  test('onChange is called with a valid primary color', () => {
+    const received: (typeof zoraDefaultTheme)[] = [];
+    const onChange = (t: typeof zoraDefaultTheme) => received.push(t);
+
+    const goodColor = '#c084fc';
+    try {
+      parseHexColorOrThrow(goodColor);
+      onChange({ ...zoraDefaultTheme, primaryColor: goodColor });
+    } catch {
+      // Should not reach here for a valid color
+    }
+    expect(received).toHaveLength(1);
+    expect(received[0]?.primaryColor).toBe(goodColor);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Legacy API absence checks
+// ---------------------------------------------------------------------------
+
+describe('No legacy APIs', () => {
+  test('ThemeComposerProps value carries no colorTone field', () => {
+    const theme = zoraDefaultTheme;
+    expect('colorTone' in theme).toBe(false);
+  });
 
-    expect(updated.primaryColor).toBe(zoraDefaultTheme.primaryColor);
-    expect(updated.colorTone).toBe('vaporwave');
+  test('ThemeComposerProps value carries no appMood field', () => {
+    const theme = zoraDefaultTheme;
+    expect('appMood' in theme).toBe(false);
   });
 
-  test('formats serialized labels for display', () => {
-    expect(formatThemeComposerLabel('finance_money')).toBe('Finance money');
-    expect(formatThemeComposerLabel('splitComplementary')).toBe('Split Complementary');
+  test('value.name is required — zoraDefaultTheme.name is a non-empty string', () => {
+    expect(typeof zoraDefaultTheme.name).toBe('string');
+    expect(zoraDefaultTheme.name.length).toBeGreaterThan(0);
   });
 
-  test('converts hue degrees to lowercase hex', () => {
-    expect(hueDegreesToZoraHexColor(195)).toMatch(/^#[0-9a-f]{6}$/);
-    expect(hueDegreesToZoraHexColor(555)).toBe(hueDegreesToZoraHexColor(195));
+  test('value.appCategory is required — zoraDefaultTheme.appCategory is set', () => {
+    expect(typeof zoraDefaultTheme.appCategory).toBe('string');
+    expect(zoraDefaultTheme.appCategory.length).toBeGreaterThan(0);
   });
 });

package/src/patterns/theme-composer/ThemeComposer.tsx

@@ -1,3 +1,6 @@
+import { COLOR_HARMONIES, parseHexColorOrThrow } from '@ankhorage/color-theory';
+import type { AppCategory } from '@ankhorage/contracts';
+import { APP_CATEGORIES } from '@ankhorage/contracts';
 import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
@@ -9,63 +12,37 @@ import { Input } from '../../components/input';
 import { Select } from '../../components/select';
 import { Tabs } from '../../components/tabs';
 import { Text } from '../../components/text';
-import {
-  ZORA_COLOR_HARMONIES,
-  ZORA_COLOR_TONES,
-  type ZoraColorTone,
-  type ZoraTheme,
-  type ZoraThemeMode,
-} from '../../theme/types';
+import type { ZoraThemeMode } from '../../theme/types';
 import { useZoraTheme } from '../../theme/useZoraTheme';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
-import {
-  createThemeFromThemeComposerRecommendation,
-  findThemeComposerRecommendation,
-  formatThemeComposerLabel,
-} from './recommendations';
 import type { ThemeComposerProps } from './types';
 
-const HEX_RE = /^#[0-9A-Fa-f]{6}$/;
+const HEX_ERROR_MESSAGE = 'Enter a valid 6-digit hex color (e.g. #0f766e).';
+const NAME_ERROR_MESSAGE = 'Theme name cannot be empty.';
 
 function isValidHex(value: string): boolean {
-  return HEX_RE.test(value);
+  try {
+    parseHexColorOrThrow(value);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
-const HARMONY_OPTIONS = ZORA_COLOR_HARMONIES.map((h) => ({ value: h, label: h }));
+function formatAppCategoryLabel(category: AppCategory): string {
+  return category
+    .split('_')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
 
-const TONE_OPTIONS = ZORA_COLOR_TONES.map((t) => ({ value: t, label: t }));
+const HARMONY_OPTIONS = COLOR_HARMONIES.map((h) => ({ value: h, label: h }));
 
 const MODE_TABS = [
   { value: 'light' as ZoraThemeMode, label: 'Light' },
   { value: 'dark' as ZoraThemeMode, label: 'Dark' },
 ];
 
-const COLOR_TONE_BACKGROUND_TONE: Record<ZoraColorTone, string> = {
-  neutral: 'Neutral',
-  pastel: 'Pastel',
-  earth: 'Earth',
-  mineral: 'Mineral',
-  muted: 'Muted',
-  jewel: 'Neutral',
-  fluorescent: 'Obsidian',
-  obsidian: 'Obsidian',
-  vaporwave: 'Pastel',
-  monochromeAccent: 'Neutral',
-};
-
-const COLOR_TONE_FOREGROUND_TONE: Record<ZoraColorTone, string> = {
-  neutral: 'Jewel',
-  pastel: 'Jewel',
-  earth: 'Mineral',
-  mineral: 'Jewel',
-  muted: 'Jewel',
-  jewel: 'Jewel',
-  fluorescent: 'Fluorescent',
-  obsidian: 'Fluorescent',
-  vaporwave: 'Fluorescent',
-  monochromeAccent: 'Jewel',
-};
-
 function ThemeComposerInner({
   themeId: _themeId,
   value,
@@ -73,9 +50,7 @@ function ThemeComposerInner({
   mode,
   onModeChange,
   onSubmit,
-  appCategory,
-  appMood,
-  recommendations,
+  appCategories,
   testID,
 }: ThemeComposerProps) {
   const { theme } = useZoraTheme();
@@ -83,12 +58,30 @@ function ThemeComposerInner({
   const [hexInput, setHexInput] = React.useState<string>(value.primaryColor);
   const [hexError, setHexError] = React.useState<string | undefined>(undefined);
 
-  // Keep local hex input in sync when value.primaryColor changes externally
+  const [nameInput, setNameInput] = React.useState<string>(value.name);
+  const [nameError, setNameError] = React.useState<string | undefined>(undefined);
+
+  // Keep local inputs in sync when value changes externally
   React.useEffect(() => {
     setHexInput(value.primaryColor);
     setHexError(undefined);
   }, [value.primaryColor]);
 
+  React.useEffect(() => {
+    setNameInput(value.name);
+    setNameError(undefined);
+  }, [value.name]);
+
+  function handleNameChange(text: string) {
+    setNameInput(text);
+    if (text.trim().length === 0) {
+      setNameError(NAME_ERROR_MESSAGE);
+    } else {
+      setNameError(undefined);
+      onChange({ ...value, name: text });
+    }
+  }
+
   function handleHexChange(text: string) {
     // Ensure leading hash
     const normalized = text.startsWith('#') ? text : `#${text}`;
@@ -96,69 +89,87 @@ function ThemeComposerInner({
 
     if (isValidHex(normalized)) {
       setHexError(undefined);
-      onChange({ ...value, primaryColor: normalized as ZoraTheme['primaryColor'] });
+      onChange({ ...value, primaryColor: normalized });
     } else {
-      setHexError('Enter a valid 6-digit hex color (e.g. #0f766e).');
+      setHexError(HEX_ERROR_MESSAGE);
+    }
+  }
+
+  function handleSubmit() {
+    const hasValidName = nameInput.trim().length > 0;
+    const hasValidHex = isValidHex(hexInput);
+
+    if (!hasValidName) {
+      setNameError(NAME_ERROR_MESSAGE);
+    }
+
+    if (!hasValidHex) {
+      setHexError(HEX_ERROR_MESSAGE);
     }
+
+    if (!hasValidName || !hasValidHex) {
+      return;
+    }
+
+    onSubmit?.({
+      ...value,
+      name: nameInput,
+      primaryColor: hexInput,
+    });
   }
 
   const activeMode = mode ?? 'light';
-  const recommendation = findThemeComposerRecommendation({
-    appCategory,
-    appMood,
-    recommendations,
-  });
+  const categoryOptions = (appCategories ?? APP_CATEGORIES).map((c) => ({
+    value: c,
+    label: formatAppCategoryLabel(c),
+  }));
 
   return (
     <Stack gap="l" testID={testID}>
-      {recommendation ? (
-        <Card
-          title="Recommended starting point"
-          description="Use this as an optional starting point. It is only applied when you choose it."
-          actions={
-            <Button
-              size="s"
-              emphasis="soft"
-              tone="primary"
-              onPress={() =>
-                onChange(
-                  createThemeFromThemeComposerRecommendation({
-                    value,
-                    recommendation,
-                  }),
-                )
-              }
-              testID={testID ? `${testID}-apply-recommendation` : undefined}
+      {/* Section: Theme identity */}
+      <Card
+        title="Theme identity"
+        description="Name your theme. The ID is assigned automatically and shown for reference."
+      >
+        <Stack gap="m">
+          <Stack gap="xs">
+            <Text variant="label">Name</Text>
+            <Input
+              value={nameInput}
+              onChangeText={handleNameChange}
+              placeholder="My theme"
+              autoCorrect={false}
+              invalid={nameError !== undefined}
+              testID={testID ? `${testID}-name-input` : undefined}
+            />
+            {nameError ? (
+              <Text tone="danger" variant="bodySmall">
+                {nameError}
+              </Text>
+            ) : null}
+          </Stack>
+          <Stack gap="xs">
+            <Text variant="label">ID</Text>
+            <Text
+              tone="muted"
+              variant="bodySmall"
+              testID={testID ? `${testID}-id-display` : undefined}
             >
-              Apply recommendation
-            </Button>
-          }
-        >
-          <Stack gap="s">
-            <Stack direction="row" gap="s" wrap="wrap">
-              <Badge tone="primary" emphasis="soft">
-                {formatThemeComposerLabel(recommendation.appMood)} mood
-              </Badge>
-              <Badge tone="neutral" emphasis="soft">
-                {formatThemeComposerLabel(recommendation.suggestedColorTone)} color tone
-              </Badge>
-              <Badge tone="neutral" emphasis="soft">
-                {formatThemeComposerLabel(recommendation.suggestedHarmony)} harmony
-              </Badge>
-              {recommendation.suggestedPrimaryHueDegrees === undefined ? null : (
-                <Badge tone="neutral" emphasis="soft">
-                  {recommendation.suggestedPrimaryHueDegrees}° hue
-                </Badge>
-              )}
-            </Stack>
-            <Text tone="muted" variant="bodySmall">
-              Suggested for {formatThemeComposerLabel(recommendation.appCategory)}. The color tone
-              controls palette character, harmony controls accent relationships, and hue sets the
-              starting primary color when available.
+              {value.id}
             </Text>
           </Stack>
-        </Card>
-      ) : null}
+        </Stack>
+      </Card>
+
+      {/* Section: App category */}
+      <Card title="App category" description="Choose the category that best describes this app.">
+        <Select
+          value={value.appCategory}
+          options={categoryOptions}
+          onValueChange={(c) => onChange({ ...value, appCategory: c })}
+          testID={testID ? `${testID}-category-select` : undefined}
+        />
+      </Card>
 
       {/* Section: Primary Color */}
       <Card title="Primary color" description="Set the seed color for your theme palette.">
@@ -209,35 +220,6 @@ function ThemeComposerInner({
         />
       </Card>
 
-      {/* Section: Color tone */}
-      <Card
-        title="Color tone"
-        description="Controls the vibrancy and saturation style of the palette."
-      >
-        <Stack gap="s">
-          <Select
-            value={value.colorTone}
-            options={TONE_OPTIONS}
-            onValueChange={(t) => onChange({ ...value, colorTone: t })}
-            testID={testID ? `${testID}-tone-select` : undefined}
-          />
-          <Stack direction="row" gap="s" align="center">
-            <Text tone="muted" variant="caption">
-              Background:
-            </Text>
-            <Badge tone="neutral" emphasis="soft">
-              {COLOR_TONE_BACKGROUND_TONE[value.colorTone]}
-            </Badge>
-            <Text tone="muted" variant="caption">
-              Foreground:
-            </Text>
-            <Badge tone="neutral" emphasis="soft">
-              {COLOR_TONE_FOREGROUND_TONE[value.colorTone]}
-            </Badge>
-          </Stack>
-        </Stack>
-      </Card>
-
       {/* Section: Mode */}
       <Card title="Mode" description="Switch between light and dark presentation.">
         <Tabs
@@ -252,6 +234,26 @@ function ThemeComposerInner({
       {/* Section: Preview */}
       <Card title="Preview" description="A quick look at how your theme renders common controls.">
         <Stack gap="m">
+          <Stack gap="xs">
+            <Text variant="label">Name</Text>
+            <Text>{value.name}</Text>
+          </Stack>
+          <Stack gap="xs">
+            <Text variant="label">Category</Text>
+            <Text>{formatAppCategoryLabel(value.appCategory)}</Text>
+          </Stack>
+          <Stack gap="xs">
+            <Text variant="label">Primary color</Text>
+            <Text tone="muted" variant="bodySmall">
+              {value.primaryColor}
+            </Text>
+          </Stack>
+          <Stack gap="xs">
+            <Text variant="label">Harmony</Text>
+            <Text tone="muted" variant="bodySmall">
+              {value.harmony}
+            </Text>
+          </Stack>
           <Heading level={4}>Heading</Heading>
           <Text>Body text — this shows default text color and weight.</Text>
           <Text tone="muted" variant="bodySmall">
@@ -294,7 +296,7 @@ function ThemeComposerInner({
         <Button
           tone="primary"
           emphasis="solid"
-          onPress={() => onSubmit(value)}
+          onPress={handleSubmit}
           testID={testID ? `${testID}-submit` : undefined}
         >
           Apply theme

package/src/patterns/theme-composer/index.ts

@@ -1,7 +1,2 @@
 export { ThemeComposer } from './ThemeComposer';
-export type {
-  ThemeComposerAppCategory,
-  ThemeComposerAppMood,
-  ThemeComposerProps,
-  ThemeComposerRecommendation,
-} from './types';
+export type { ThemeComposerProps } from './types';