@ankhorage/zora 2.11.0 → 2.13.0

package/src/components/heading/meta.ts

@@ -1,21 +1,19 @@
 import { ZORA_COLORS, ZORA_EMPHASES } from '../../internal/colorModel';
 import type { ZoraComponentMeta } from '../../metadata';
 
+const themeAuthoring = {
+  authority: 'theme',
+  scope: 'component',
+  allowInstanceOverride: true,
+} as const;
+
 export const headingMeta = {
   name: 'Heading',
   category: 'component',
   directManifestNode: true,
   allowedChildren: [],
-  blueprint: {
-    label: 'Heading',
-    defaultProps: {
-      text: 'Heading',
-      level: 2,
-    },
-  },
-  i18n: {
-    fields: [{ keyProp: 'i18nKey', defaultTextProp: 'text' }],
-  },
+  blueprint: { label: 'Heading', defaultProps: { text: 'Heading', level: 2 } },
+  i18n: { fields: [{ keyProp: 'i18nKey', defaultTextProp: 'text' }] },
   props: {
     text: {
       type: 'string',
@@ -43,43 +41,37 @@ export const headingMeta = {
       category: 'Typography',
       label: 'Size',
       enum: ['display', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
     color: {
       type: 'enum',
       category: 'Style',
       label: 'Color',
       enum: ZORA_COLORS,
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
     emphasis: {
       type: 'enum',
       category: 'Style',
       label: 'Emphasis',
       enum: ZORA_EMPHASES,
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
     align: {
       type: 'enum',
       category: 'Layout',
       label: 'Align',
       enum: ['auto', 'left', 'right', 'center', 'justify'],
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
     weight: {
       type: 'enum',
       category: 'Typography',
       label: 'Weight',
       enum: ['regular', 'medium', 'semiBold', 'bold'],
-      authoring: { authority: 'theme', scope: 'component' },
-    },
-    italic: {
-      type: 'boolean',
-      category: 'Typography',
-      label: 'Italic',
-      default: false,
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
+    italic: { type: 'boolean', category: 'Typography', label: 'Italic', authoring: themeAuthoring },
     numberOfLines: {
       type: 'number',
       category: 'Layout',

package/src/components/heading/resolveHeadingThemeRecipe.ts

@@ -0,0 +1,55 @@
+import type { ThemeRecipeOverrideValue } from '@ankhorage/contracts';
+
+import type {
+  HeadingAlign,
+  HeadingColor,
+  HeadingEmphasis,
+  HeadingSize,
+  HeadingWeight,
+} from './types';
+
+export function resolveHeadingThemeRecipe(
+  fields: Readonly<Record<string, ThemeRecipeOverrideValue>>,
+) {
+  return {
+    size: readSize(fields.size),
+    color: readColor(fields.color),
+    emphasis: readEmphasis(fields.emphasis),
+    align: readAlign(fields.align),
+    weight: readWeight(fields.weight),
+    italic: typeof fields.italic === 'boolean' ? fields.italic : undefined,
+  };
+}
+
+function readSize(value: ThemeRecipeOverrideValue | undefined): HeadingSize | undefined {
+  if (value === 'display' || value === 'h1' || value === 'h2' || value === 'h3') return value;
+  if (value === 'h4' || value === 'h5' || value === 'h6') return value;
+  return undefined;
+}
+
+function readColor(value: ThemeRecipeOverrideValue | undefined): HeadingColor | undefined {
+  if (typeof value !== 'string') return undefined;
+  if (value === 'primary' || value === 'secondary' || value === 'tertiary') return value;
+  if (value === 'quaternary' || value === 'neutral' || value === 'danger') return value;
+  if (value === 'success' || value === 'warning' || value === 'error' || value === 'info')
+    return value;
+  return undefined;
+}
+
+function readEmphasis(value: ThemeRecipeOverrideValue | undefined): HeadingEmphasis | undefined {
+  if (value === 'default' || value === 'muted' || value === 'subtle' || value === 'inverse')
+    return value;
+  return undefined;
+}
+
+function readAlign(value: ThemeRecipeOverrideValue | undefined): HeadingAlign | undefined {
+  if (value === 'auto' || value === 'left' || value === 'right') return value;
+  if (value === 'center' || value === 'justify') return value;
+  return undefined;
+}
+
+function readWeight(value: ThemeRecipeOverrideValue | undefined): HeadingWeight | undefined {
+  if (value === 'regular' || value === 'medium' || value === 'semiBold' || value === 'bold')
+    return value;
+  return undefined;
+}

package/src/components/heading/themeRecipeMeta.ts

@@ -0,0 +1,33 @@
+import { ZORA_COLORS, ZORA_EMPHASES } from '../../internal/colorModel';
+import type { ZoraThemeRecipeMeta } from '../../metadata/themeRecipeTypes';
+
+export const headingThemeRecipeMeta = {
+  name: 'Heading',
+  kind: 'component',
+  description: 'Maps Heading presentation defaults without replacing semantic heading levels.',
+  fields: {
+    size: {
+      type: 'choice',
+      label: 'Size',
+      options: ['display', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+    },
+    color: { type: 'choice', label: 'Color', options: ZORA_COLORS },
+    emphasis: {
+      type: 'choice',
+      label: 'Emphasis',
+      options: ZORA_EMPHASES,
+      default: 'default',
+    },
+    align: {
+      type: 'choice',
+      label: 'Align',
+      options: ['auto', 'left', 'right', 'center', 'justify'],
+    },
+    weight: {
+      type: 'choice',
+      label: 'Weight',
+      options: ['regular', 'medium', 'semiBold', 'bold'],
+    },
+    italic: { type: 'boolean', label: 'Italic', default: false },
+  },
+} as const satisfies ZoraThemeRecipeMeta;

package/src/components/image/meta.ts

@@ -3,8 +3,23 @@ import type { ZoraComponentMeta } from '../../metadata';
 export const imageMeta = {
   name: 'Image',
   category: 'component',
-  directManifestNode: false,
+  description: 'Displays an image from the app media registry or a resolved runtime source.',
+  directManifestNode: true,
   allowedChildren: [],
-  note: 'Media component; not represented as a manifest node in v1.',
-  props: {},
+  blueprint: { label: 'Image' },
+  props: {
+    source: {
+      type: 'media',
+      category: 'Content',
+      label: 'Source',
+      mediaKinds: ['image'],
+      authoring: { authority: 'instance' },
+    },
+    alt: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Alt text',
+      authoring: { authority: 'instance' },
+    },
+  },
 } as const satisfies ZoraComponentMeta;

package/src/components/text/Text.tsx

@@ -3,8 +3,10 @@ import React from 'react';
 import { Platform, Text as ReactNativeText, type TextStyle } from 'react-native';
 
 import { useZoraTheme } from '../../theme/useZoraTheme';
+import { useZoraThemeRecipe } from '../../theme/useZoraThemeRecipe';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { resolveTextStyle } from './resolveTextRecipe';
+import { resolveTextThemeRecipe } from './resolveTextThemeRecipe';
 import type { TextProps } from './types';
 
 const textLayoutStyle = {
@@ -29,18 +31,9 @@ function resolveTextContent({
   text: TextProps['text'];
   i18nKey: TextProps['i18nKey'];
 }): React.ReactNode {
-  if (children !== undefined) {
-    return children;
-  }
-
-  if (text !== undefined) {
-    return text;
-  }
-
-  if (!i18nKey) {
-    return null;
-  }
-
+  if (children !== undefined) return children;
+  if (text !== undefined) return text;
+  if (i18nKey === undefined || i18nKey === '') return null;
   return i18nKey;
 }
 
@@ -50,12 +43,12 @@ function TextInner({
   children,
   text,
   i18nKey,
-  variant = 'body',
+  variant,
   color,
-  emphasis = 'default',
+  emphasis,
   align,
   weight,
-  italic = false,
+  italic,
   numberOfLines,
   ellipsizeMode,
   selectable,
@@ -69,22 +62,21 @@ function TextInner({
 }: TextProps) {
   const { theme } = useZoraTheme();
   const { breakpoint } = useResponsiveRuntime();
+  const themeRecipe = resolveTextThemeRecipe(useZoraThemeRecipe('Text'));
   const content = resolveTextContent({ children, text, i18nKey });
-  const resolvedVariant = resolveResponsive(variant, breakpoint) ?? 'body';
+  const resolvedVariant = resolveResponsive(variant ?? themeRecipe.variant, breakpoint) ?? 'body';
   const resolvedStyle = resolveTextStyle({
     theme,
     breakpoint,
     variant: resolvedVariant,
-    color,
-    emphasis,
-    align,
-    weight,
-    italic,
+    color: color ?? themeRecipe.color,
+    emphasis: emphasis ?? themeRecipe.emphasis,
+    align: align ?? themeRecipe.align,
+    weight: weight ?? themeRecipe.weight,
+    italic: italic ?? themeRecipe.italic ?? false,
   });
 
-  if (content === null || content === undefined) {
-    return null;
-  }
+  if (content === null || content === undefined) return null;
 
   return (
     <ReactNativeText
@@ -109,7 +101,6 @@ function TextInner({
  * `Text` owns normal body, caption, label, code, and supporting-copy variants so
  * consumers do not need to import lower-level Surface typography directly.
  *
-
  * @example Muted supporting copy
  * ```tsx
  * <Text variant="bodySmall" emphasis="muted">Updated just now</Text>

package/src/components/text/meta.ts

@@ -1,22 +1,19 @@
 import { ZORA_COLORS, ZORA_EMPHASES } from '../../internal/colorModel';
 import type { ZoraComponentMeta } from '../../metadata';
 
+const themeAuthoring = {
+  authority: 'theme',
+  scope: 'component',
+  allowInstanceOverride: true,
+} as const;
+
 export const textMeta = {
   name: 'Text',
   category: 'component',
   directManifestNode: true,
   allowedChildren: [],
-  blueprint: {
-    label: 'Text',
-    defaultProps: {
-      text: 'Text',
-      emphasis: 'default',
-      variant: 'body',
-    },
-  },
-  i18n: {
-    fields: [{ keyProp: 'i18nKey', defaultTextProp: 'text' }],
-  },
+  blueprint: { label: 'Text', defaultProps: { text: 'Text' } },
+  i18n: { fields: [{ keyProp: 'i18nKey', defaultTextProp: 'text' }] },
   props: {
     text: {
       type: 'string',
@@ -36,45 +33,37 @@ export const textMeta = {
       category: 'Typography',
       label: 'Variant',
       enum: ['body', 'lead', 'bodySmall', 'caption', 'label', 'eyebrow', 'code'],
-      default: 'body',
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
     color: {
       type: 'enum',
       category: 'Style',
       label: 'Color',
       enum: ZORA_COLORS,
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
     emphasis: {
       type: 'enum',
       category: 'Style',
       label: 'Emphasis',
       enum: ZORA_EMPHASES,
-      default: 'default',
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
     align: {
       type: 'enum',
       category: 'Layout',
       label: 'Align',
       enum: ['auto', 'left', 'right', 'center', 'justify'],
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
     weight: {
       type: 'enum',
       category: 'Typography',
       label: 'Weight',
       enum: ['regular', 'medium', 'semiBold', 'bold'],
-      authoring: { authority: 'theme', scope: 'component' },
-    },
-    italic: {
-      type: 'boolean',
-      category: 'Typography',
-      label: 'Italic',
-      default: false,
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
+    italic: { type: 'boolean', category: 'Typography', label: 'Italic', authoring: themeAuthoring },
     numberOfLines: {
       type: 'number',
       category: 'Layout',

package/src/components/text/resolveTextThemeRecipe.ts

@@ -0,0 +1,48 @@
+import type { ThemeRecipeOverrideValue } from '@ankhorage/contracts';
+
+import type { TextAlign, TextColor, TextEmphasis, TextVariant, TextWeight } from './types';
+
+export function resolveTextThemeRecipe(fields: Readonly<Record<string, ThemeRecipeOverrideValue>>) {
+  return {
+    variant: readVariant(fields.variant),
+    color: readColor(fields.color),
+    emphasis: readEmphasis(fields.emphasis),
+    align: readAlign(fields.align),
+    weight: readWeight(fields.weight),
+    italic: typeof fields.italic === 'boolean' ? fields.italic : undefined,
+  };
+}
+
+function readVariant(value: ThemeRecipeOverrideValue | undefined): TextVariant | undefined {
+  if (value === 'body' || value === 'lead' || value === 'bodySmall' || value === 'caption')
+    return value;
+  if (value === 'label' || value === 'eyebrow' || value === 'code') return value;
+  return undefined;
+}
+
+function readColor(value: ThemeRecipeOverrideValue | undefined): TextColor | undefined {
+  if (typeof value !== 'string') return undefined;
+  if (value === 'primary' || value === 'secondary' || value === 'tertiary') return value;
+  if (value === 'quaternary' || value === 'neutral' || value === 'danger') return value;
+  if (value === 'success' || value === 'warning' || value === 'error' || value === 'info')
+    return value;
+  return undefined;
+}
+
+function readEmphasis(value: ThemeRecipeOverrideValue | undefined): TextEmphasis | undefined {
+  if (value === 'default' || value === 'muted' || value === 'subtle' || value === 'inverse')
+    return value;
+  return undefined;
+}
+
+function readAlign(value: ThemeRecipeOverrideValue | undefined): TextAlign | undefined {
+  if (value === 'auto' || value === 'left' || value === 'right') return value;
+  if (value === 'center' || value === 'justify') return value;
+  return undefined;
+}
+
+function readWeight(value: ThemeRecipeOverrideValue | undefined): TextWeight | undefined {
+  if (value === 'regular' || value === 'medium' || value === 'semiBold' || value === 'bold')
+    return value;
+  return undefined;
+}

package/src/components/text/themeRecipeMeta.ts

@@ -1,33 +1,34 @@
+import { ZORA_COLORS, ZORA_EMPHASES } from '../../internal/colorModel';
 import type { ZoraThemeRecipeMeta } from '../../metadata/themeRecipeTypes';
 
 export const textThemeRecipeMeta = {
   name: 'Text',
   kind: 'component',
-  description: 'Maps shared typography and color tokens into Text presentation.',
+  description: 'Maps semantic Text presentation defaults into runtime props.',
   fields: {
     variant: {
-      type: 'token',
-      tokenFamily: 'typography',
+      type: 'choice',
       label: 'Typography variant',
+      options: ['body', 'lead', 'bodySmall', 'caption', 'label', 'eyebrow', 'code'],
       default: 'body',
     },
-    color: {
-      type: 'token',
-      tokenFamily: 'colors',
-      label: 'Color',
-      default: 'text',
-    },
+    color: { type: 'choice', label: 'Color', options: ZORA_COLORS },
     emphasis: {
       type: 'choice',
       label: 'Emphasis',
-      options: ['default', 'muted', 'subtle', 'inverse'],
+      options: ZORA_EMPHASES,
       default: 'default',
     },
+    align: {
+      type: 'choice',
+      label: 'Align',
+      options: ['auto', 'left', 'right', 'center', 'justify'],
+    },
     weight: {
       type: 'choice',
       label: 'Weight',
       options: ['regular', 'medium', 'semiBold', 'bold'],
-      default: 'regular',
     },
+    italic: { type: 'boolean', label: 'Italic', default: false },
   },
 } as const satisfies ZoraThemeRecipeMeta;

package/src/metadata/authoringMeta.test.ts

@@ -2,70 +2,44 @@ import { describe, expect, test } from 'bun:test';
 
 import { ZORA_COMPONENT_META, type ZoraComponentPropAuthoring } from './index';
 
+const componentMetaByName = new Map(Object.entries(ZORA_COMPONENT_META));
+
 describe('ZORA component prop authoring authority', () => {
-  test('supports the canonical instance and theme scope combinations', () => {
+  test('supports instance and theme authority with explicit instance override capability', () => {
     const values: readonly ZoraComponentPropAuthoring[] = [
       { authority: 'instance' },
       { authority: 'theme', scope: 'global' },
-      { authority: 'theme', scope: 'component' },
-      { authority: 'theme', scope: 'pattern' },
+      { authority: 'theme', scope: 'component', allowInstanceOverride: true },
+      { authority: 'theme', scope: 'pattern', allowInstanceOverride: true },
     ];
-
-    expect(values).toEqual([
-      { authority: 'instance' },
-      { authority: 'theme', scope: 'global' },
-      { authority: 'theme', scope: 'component' },
-      { authority: 'theme', scope: 'pattern' },
-    ]);
+    expect(values).toHaveLength(4);
   });
 
-  test('classifies representative instance content without exposing arbitrary styling', () => {
-    expect(ZORA_COMPONENT_META.Button.props.children?.authoring).toEqual({
-      authority: 'instance',
-    });
+  test('keeps representative content and semantics instance-owned', () => {
+    expect(ZORA_COMPONENT_META.Button.props.children?.authoring).toEqual({ authority: 'instance' });
     expect(ZORA_COMPONENT_META.Card.props.title?.authoring).toEqual({ authority: 'instance' });
-    expect(ZORA_COMPONENT_META.Heading.props.text?.authoring).toEqual({ authority: 'instance' });
     expect(ZORA_COMPONENT_META.Heading.props.level?.authoring).toEqual({ authority: 'instance' });
     expect(ZORA_COMPONENT_META.Text.props.text?.authoring).toEqual({ authority: 'instance' });
-    expect(ZORA_COMPONENT_META.Panel.props.description?.authoring).toEqual({
-      authority: 'instance',
-    });
   });
 
-  test('classifies component and pattern styling as theme authority', () => {
-    expect(ZORA_COMPONENT_META.Button.props.size?.authoring).toEqual({
-      authority: 'theme',
-      scope: 'component',
-    });
-    expect(ZORA_COMPONENT_META.Card.props.tone?.authoring).toEqual({
-      authority: 'theme',
-      scope: 'component',
-    });
-    expect(ZORA_COMPONENT_META.Heading.props.size?.authoring).toEqual({
-      authority: 'theme',
-      scope: 'component',
-    });
-    expect(ZORA_COMPONENT_META.Text.props.variant?.authoring).toEqual({
-      authority: 'theme',
-      scope: 'component',
-    });
-    expect(ZORA_COMPONENT_META.Panel.props.compact?.authoring).toEqual({
-      authority: 'theme',
-      scope: 'pattern',
-    });
+  test('marks recipe props theme-owned while allowing explicit instance overrides', () => {
+    for (const name of ['Button', 'Card', 'Heading', 'Text', 'Panel']) {
+      const meta = componentMetaByName.get(name);
+      expect(meta, name).toBeDefined();
+      for (const prop of Object.values(meta?.props ?? {})) {
+        if (prop.authoring?.authority !== 'theme') continue;
+        expect(prop.authoring.allowInstanceOverride, name).toBe(true);
+      }
+    }
   });
 
-  test('keeps Heading blueprint content useful before instance editing', () => {
+  test('keeps Heading blueprint semantic content useful', () => {
     expect(ZORA_COMPONENT_META.Heading.blueprint?.defaultProps).toEqual({
       text: 'Heading',
       level: 2,
     });
   });
 
-  test('treats absent authoring metadata as not authorable', () => {
-    expect(ZORA_COMPONENT_META.Progress.props.value?.authoring).toBeUndefined();
-  });
-
   test('does not introduce a system authority', () => {
     expect(JSON.stringify(ZORA_COMPONENT_META)).not.toContain('"authority":"system"');
   });

package/src/metadata/bindableComponentMeta.test.ts

@@ -2,6 +2,7 @@ import type { UiComponentMetaRegistry } from '@ankhorage/contracts';
 import { describe, expect, it } from 'bun:test';
 
 import { ZORA_BINDABLE_COMPONENT_META } from './bindableComponentMeta';
+import { ZORA_COMPONENT_META } from './componentMeta';
 
 describe('ZORA bindable component metadata', () => {
   it('matches the shared UI metadata registry shape', () => {
@@ -15,4 +16,16 @@ describe('ZORA bindable component metadata', () => {
     expect(registry.Image?.bindings?.props?.source?.value.type).toBe('imageAsset');
     expect(registry.DataTable?.bindings?.props?.rows?.value.type).toBe('array');
   });
+
+  it('shares canonical Image authoring metadata while preserving dynamic image bindings', () => {
+    const image = ZORA_BINDABLE_COMPONENT_META.Image;
+
+    expect(image.props.source).toMatchObject({
+      type: 'media',
+      mediaKinds: ['image'],
+    });
+    expect(image.props).toEqual(ZORA_COMPONENT_META.Image.props);
+    expect(image.directManifestNode).toBe(ZORA_COMPONENT_META.Image.directManifestNode);
+    expect(image.bindings.props.source.value.type).toBe('imageAsset');
+  });
 });

package/src/metadata/bindableComponentMeta.ts

@@ -1,5 +1,7 @@
 import type { UiComponentMetaRegistry } from '@ankhorage/contracts';
 
+import { imageMeta } from '../components/image/meta';
+
 export const ZORA_BINDABLE_COMPONENT_META = {
   Text: {
     name: 'Text',
@@ -107,16 +109,12 @@ export const ZORA_BINDABLE_COMPONENT_META = {
     },
   },
   Image: {
-    name: 'Image',
-    category: 'component',
-    description: 'Displays an image asset or remote image source.',
-    directManifestNode: true,
-    allowedChildren: [],
+    ...imageMeta,
     bindings: {
       props: {
         source: {
           label: 'Source',
-          description: 'Image source or asset descriptor.',
+          description: 'Dynamic image source or asset descriptor.',
           value: {
             type: 'imageAsset',
             fields: [
@@ -131,13 +129,6 @@ export const ZORA_BINDABLE_COMPONENT_META = {
         },
       },
     },
-    props: {
-      source: {
-        type: 'imageAsset',
-        category: 'Content',
-        label: 'Source',
-      },
-    },
   },
   Input: {
     name: 'Input',

package/src/metadata/componentMeta.test.ts

@@ -124,6 +124,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'Textarea',
       'Text',
       'Heading',
+      'Image',
       'Divider',
       'ChatListItem',
       'CameraPermissionView',
@@ -172,6 +173,19 @@ describe('ZORA_COMPONENT_META invariants', () => {
     }
   });
 
+  test('Image is a direct manifest leaf with canonical media authoring metadata', () => {
+    expect(ZORA_COMPONENT_META.Image.directManifestNode).toBe(true);
+    expect(ZORA_COMPONENT_META.Image.allowedChildren).toEqual([]);
+    expect(ZORA_COMPONENT_META.Image.props.source).toEqual({
+      type: 'media',
+      category: 'Content',
+      label: 'Source',
+      mediaKinds: ['image'],
+      authoring: { authority: 'instance' },
+    });
+    expect(ZORA_COMPONENT_META.Image.props.alt?.authoring).toEqual({ authority: 'instance' });
+  });
+
   test('ThemeModeToggle is a direct manifest leaf with serializable defaults', () => {
     expect(ZORA_COMPONENT_META.ThemeModeToggle.directManifestNode).toBe(true);
     expect(ZORA_COMPONENT_META.ThemeModeToggle.allowedChildren).toEqual([]);