@ankhorage/zora 2.10.0 → 2.12.0

package/src/components/card/resolveCardThemeRecipe.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveCardThemeRecipe } from './resolveCardThemeRecipe';
+
+describe('resolveCardThemeRecipe', () => {
+  test('preserves compact-aware padding when theme padding is unset', () => {
+    expect(
+      resolveCardThemeRecipe({ themeFields: { tone: 'default', compact: true, radius: 'l' } }),
+    ).toEqual({
+      tone: 'default',
+      compact: true,
+      padding: 'm',
+      radius: 'l',
+    });
+  });
+
+  test('lets explicit instance props win over theme values', () => {
+    expect(
+      resolveCardThemeRecipe({
+        tone: 'outline',
+        compact: false,
+        padding: 'hero',
+        radius: 'pill',
+        themeFields: { tone: 'subtle', compact: true, padding: 'm', radius: 'l' },
+      }),
+    ).toEqual({ tone: 'outline', compact: false, padding: 'hero', radius: 'pill' });
+  });
+});

package/src/components/card/resolveCardThemeRecipe.ts

@@ -0,0 +1,33 @@
+import type { ThemeRecipeOverrideValue } from '@ankhorage/contracts';
+
+import type { ZoraCardTone } from '../../internal/recipes';
+
+export function resolveCardThemeRecipe(input: {
+  readonly tone?: ZoraCardTone;
+  readonly compact?: boolean;
+  readonly padding?: string;
+  readonly radius?: string;
+  readonly themeFields: Readonly<Record<string, ThemeRecipeOverrideValue>>;
+}) {
+  const tone = input.tone ?? readTone(input.themeFields.tone) ?? 'default';
+  const compact = input.compact ?? readBoolean(input.themeFields.compact) ?? false;
+  return {
+    tone,
+    compact,
+    padding: input.padding ?? readString(input.themeFields.padding) ?? (compact ? 'm' : 'l'),
+    radius: input.radius ?? readString(input.themeFields.radius) ?? 'l',
+  };
+}
+
+function readTone(value: ThemeRecipeOverrideValue | undefined): ZoraCardTone | undefined {
+  if (value === 'default' || value === 'subtle' || value === 'outline') return value;
+  return undefined;
+}
+
+function readBoolean(value: ThemeRecipeOverrideValue | undefined): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function readString(value: ThemeRecipeOverrideValue | undefined): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}

package/src/components/card/themeRecipeMeta.ts

@@ -15,7 +15,7 @@ export const cardThemeRecipeMeta = {
       type: 'token',
       tokenFamily: 'spacing',
       label: 'Padding',
-      default: 'l',
+      description: 'When unset, Card keeps its compact-aware spacing default.',
     },
     radius: {
       type: 'token',

package/src/components/card/types.ts

@@ -14,4 +14,6 @@ export interface CardProps
   footer?: React.ReactNode;
   tone?: ZoraCardTone;
   compact?: boolean;
+  padding?: string;
+  radius?: string;
 }

package/src/components/contentFallback.test.ts

@@ -9,15 +9,15 @@ const headingSource = readFileSync(join(import.meta.dir, 'heading', 'Heading.tsx
 describe('content fallback ownership', () => {
   it('keeps Text free of translation context coupling', () => {
     expect(textSource).not.toMatch(/useTranslationContext/);
-    expect(textSource).toMatch(/if \(children !== undefined\) \{/);
-    expect(textSource).toMatch(/if \(text !== undefined\) \{/);
+    expect(textSource).toMatch(/if \(children !== undefined\) return children;/);
+    expect(textSource).toMatch(/if \(text !== undefined\) return text;/);
     expect(textSource).toMatch(/return i18nKey;/);
   });
 
   it('keeps Heading free of translation context coupling', () => {
     expect(headingSource).not.toMatch(/useTranslationContext/);
-    expect(headingSource).toMatch(/if \(children !== undefined\) \{/);
-    expect(headingSource).toMatch(/if \(text !== undefined\) \{/);
+    expect(headingSource).toMatch(/if \(children !== undefined\) return children;/);
+    expect(headingSource).toMatch(/if \(text !== undefined\) return text;/);
     expect(headingSource).toMatch(/return i18nKey;/);
   });
 });

package/src/components/heading/Heading.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 { resolveHeadingRecipe, resolveHeadingSizeFromLevel } from './resolveHeadingRecipe';
+import { resolveHeadingThemeRecipe } from './resolveHeadingThemeRecipe';
 import type { HeadingProps } from './types';
 
 const headingLayoutStyle = {
@@ -24,23 +26,10 @@ function resolveHeadingContent({
   children,
   text,
   i18nKey,
-}: {
-  children: HeadingProps['children'];
-  text: HeadingProps['text'];
-  i18nKey: HeadingProps['i18nKey'];
-}): React.ReactNode {
-  if (children !== undefined) {
-    return children;
-  }
-
-  if (text !== undefined) {
-    return text;
-  }
-
-  if (!i18nKey) {
-    return null;
-  }
-
+}: Pick<HeadingProps, 'children' | 'text' | 'i18nKey'>) {
+  if (children !== undefined) return children;
+  if (text !== undefined) return text;
+  if (i18nKey === undefined || i18nKey === '') return null;
   return i18nKey;
 }
 
@@ -53,10 +42,10 @@ function HeadingInner({
   level = 2,
   size,
   color,
-  emphasis = 'default',
+  emphasis,
   align,
   weight,
-  italic = false,
+  italic,
   numberOfLines,
   ellipsizeMode,
   selectable,
@@ -70,16 +59,17 @@ function HeadingInner({
 }: HeadingProps) {
   const { theme } = useZoraTheme();
   const { breakpoint } = useResponsiveRuntime();
+  const themeRecipe = resolveHeadingThemeRecipe(useZoraThemeRecipe('Heading'));
   const content = resolveHeadingContent({ children, text, i18nKey });
-  const resolvedSize = resolveResponsive(size, breakpoint) ?? resolveHeadingSizeFromLevel(level);
-  const resolvedColor = resolveResponsive(color, breakpoint);
-  const resolvedEmphasis = resolveResponsive(emphasis, breakpoint) ?? 'default';
-  const resolvedAlign = resolveResponsive(align, breakpoint);
-  const resolvedWeight = resolveResponsive(weight, breakpoint);
+  const resolvedSize =
+    resolveResponsive(size ?? themeRecipe.size, breakpoint) ?? resolveHeadingSizeFromLevel(level);
+  const resolvedColor = resolveResponsive(color ?? themeRecipe.color, breakpoint);
+  const resolvedEmphasis =
+    resolveResponsive(emphasis ?? themeRecipe.emphasis, breakpoint) ?? 'default';
+  const resolvedAlign = resolveResponsive(align ?? themeRecipe.align, breakpoint);
+  const resolvedWeight = resolveResponsive(weight ?? themeRecipe.weight, breakpoint);
 
-  if (content === null || content === undefined) {
-    return null;
-  }
+  if (content === null) return null;
 
   return (
     <ReactNativeText
@@ -95,7 +85,7 @@ function HeadingInner({
         headingLayoutStyle,
         resolveHeadingRecipe(theme, {
           align: resolvedAlign,
-          italic,
+          italic: italic ?? themeRecipe.italic ?? false,
           level,
           size: resolvedSize,
           color: resolvedColor,

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/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/allowedChildren.ts

@@ -8,6 +8,7 @@ export const CONTAINER_ALLOWED_CHILDREN = [
   'Heading',
   'Button',
   'ButtonGroup',
+  'ThemeModeToggle',
   'Input',
   'Textarea',
   'FormField',