@ankhorage/zora 7.0.0 → 9.0.0

package/src/features/typography/headingMeta.ts

@@ -0,0 +1,82 @@
+import { COMPONENT_THEME_AUTHORING } from '../../constants';
+import { ZORA_COLORS, ZORA_EMPHASES } from '../../internal/colorModel';
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const headingMeta = {
+  name: 'Heading',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: { label: 'Heading', defaultProps: { text: 'Heading', level: 2 } },
+  i18n: { fields: [{ keyProp: 'i18nKey', defaultTextProp: 'text' }] },
+  props: {
+    text: {
+      type: 'string',
+      category: 'Content',
+      label: 'Text',
+      default: 'Heading',
+      authoring: { authority: 'instance' },
+    },
+    i18nKey: {
+      type: 'string',
+      category: 'Content',
+      label: 'i18n key',
+      authoring: { authority: 'instance' },
+    },
+    level: {
+      type: 'enum',
+      category: 'Semantics',
+      label: 'Level',
+      enum: [1, 2, 3, 4, 5, 6],
+      default: 2,
+      authoring: { authority: 'instance' },
+    },
+    size: {
+      type: 'enum',
+      category: 'Typography',
+      label: 'Size',
+      enum: ['display', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    color: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Color',
+      enum: ZORA_COLORS,
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    emphasis: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Emphasis',
+      enum: ZORA_EMPHASES,
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    align: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Align',
+      enum: ['auto', 'left', 'right', 'center', 'justify'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    weight: {
+      type: 'enum',
+      category: 'Typography',
+      label: 'Weight',
+      enum: ['regular', 'medium', 'semiBold', 'bold'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    italic: {
+      type: 'boolean',
+      category: 'Typography',
+      label: 'Italic',
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    numberOfLines: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Line clamp',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/typography/public.ts

@@ -0,0 +1,19 @@
+export type {
+  HeadingAlign,
+  HeadingColor,
+  HeadingEmphasis,
+  HeadingLevel,
+  HeadingProps,
+  HeadingSize,
+  HeadingWeight,
+} from '../../types/heading';
+export type {
+  TextAlign,
+  TextColor,
+  TextEmphasis,
+  TextProps,
+  TextVariant,
+  TextWeight,
+} from '../../types/text';
+export { Heading } from './adapters/inbound/Heading';
+export { Text } from './adapters/inbound/Text';

package/src/features/typography/textMeta.ts

@@ -0,0 +1,74 @@
+import { COMPONENT_THEME_AUTHORING } from '../../constants';
+import { ZORA_COLORS, ZORA_EMPHASES } from '../../internal/colorModel';
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const textMeta = {
+  name: 'Text',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: { label: 'Text', defaultProps: { text: 'Text' } },
+  i18n: { fields: [{ keyProp: 'i18nKey', defaultTextProp: 'text' }] },
+  props: {
+    text: {
+      type: 'string',
+      category: 'Content',
+      label: 'Text',
+      default: 'Text',
+      authoring: { authority: 'instance' },
+    },
+    i18nKey: {
+      type: 'string',
+      category: 'Content',
+      label: 'i18n key',
+      authoring: { authority: 'instance' },
+    },
+    variant: {
+      type: 'enum',
+      category: 'Typography',
+      label: 'Variant',
+      enum: ['body', 'lead', 'bodySmall', 'caption', 'label', 'eyebrow', 'code'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    color: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Color',
+      enum: ZORA_COLORS,
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    emphasis: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Emphasis',
+      enum: ZORA_EMPHASES,
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    align: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Align',
+      enum: ['auto', 'left', 'right', 'center', 'justify'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    weight: {
+      type: 'enum',
+      category: 'Typography',
+      label: 'Weight',
+      enum: ['regular', 'medium', 'semiBold', 'bold'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    italic: {
+      type: 'boolean',
+      category: 'Typography',
+      label: 'Italic',
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    numberOfLines: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Line clamp',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/typography/utils/headingThemeRecipeMeta.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/features/typography/utils/resolveHeadingRecipe.test.ts

@@ -0,0 +1,293 @@
+import type { FontWeight, RoleSemantics, SurfaceTheme } from '@ankhorage/surface';
+import { describe, expect, test } from 'bun:test';
+
+import { resolveHeadingRecipe } from './resolveHeadingRecipe';
+import { resolveHeadingSizeFromLevel } from './resolveHeadingSizeFromLevel';
+
+const emptyFonts: Record<FontWeight, string | undefined> = {
+  '100': undefined,
+  '200': undefined,
+  '300': undefined,
+  '400': undefined,
+  '500': undefined,
+  '600': undefined,
+  '700': undefined,
+  '800': undefined,
+  '900': undefined,
+  bold: undefined,
+  normal: undefined,
+};
+
+function createRole(base: string): RoleSemantics {
+  return {
+    base,
+    hover: `${base}-hover`,
+    strong: `${base}-strong`,
+    softBg: `${base}-soft-bg`,
+    softHover: `${base}-soft-hover`,
+    softActive: `${base}-soft-active`,
+    outline: `${base}-outline`,
+    onSolidText: `${base}-on-solid-text`,
+  };
+}
+
+function createTestTheme(): SurfaceTheme {
+  return {
+    colors: {
+      primary: '#0f766e',
+      secondary: '#2563eb',
+      accent: '#7c3aed',
+      highlight: '#f59e0b',
+      background: '#ffffff',
+      surface: '#ffffff',
+      text: '#111827',
+      textSecondary: '#4b5563',
+      border: '#d1d5db',
+      error: '#dc2626',
+      success: '#16a34a',
+      warning: '#d97706',
+    },
+    config: {
+      id: 'zora-test',
+      name: 'ZORA Test',
+      light: {
+        primaryColor: '#0f766e',
+        harmony: 'analogous',
+      },
+      dark: {
+        primaryColor: '#2dd4bf',
+        harmony: 'analogous',
+      },
+    },
+    radii: {
+      none: 0,
+      s: 4,
+      m: 8,
+      l: 16,
+      full: 9999,
+    },
+    swatches: {
+      primary: {
+        50: '#f0fdfa',
+        100: '#ccfbf1',
+        200: '#99f6e4',
+        300: '#5eead4',
+        400: '#2dd4bf',
+        500: '#14b8a6',
+        600: '#0d9488',
+        700: '#0f766e',
+        800: '#115e59',
+        900: '#134e4a',
+        950: '#042f2e',
+      },
+      neutral: {
+        50: '#f9fafb',
+        100: '#f3f4f6',
+        200: '#e5e7eb',
+        300: '#d1d5db',
+        400: '#9ca3af',
+        500: '#6b7280',
+        600: '#4b5563',
+        700: '#374151',
+        800: '#1f2937',
+        900: '#111827',
+        950: '#030712',
+      },
+    },
+    semantics: {
+      neutral: {
+        bg: '#ffffff',
+        bgSubtle: '#f9fafb',
+        surface: '#ffffff',
+        surfaceHover: '#f3f4f6',
+        surfaceActive: '#e5e7eb',
+        border: '#d1d5db',
+        borderStrong: '#9ca3af',
+        divider: '#e5e7eb',
+        text: '#111827',
+        textMuted: '#4b5563',
+        textSubtle: '#6b7280',
+      },
+      brand: createRole('#0f766e'),
+      secondary: createRole('#2563eb'),
+      accent: createRole('#7c3aed'),
+      highlight: createRole('#f59e0b'),
+      danger: createRole('#dc2626'),
+      success: createRole('#16a34a'),
+      warning: createRole('#d97706'),
+      surface: {
+        default: '#ffffff',
+        subtle: '#f9fafb',
+        raised: '#ffffff',
+      },
+      content: {
+        default: '#111827',
+        muted: '#4b5563',
+        subtle: '#6b7280',
+        inverse: '#ffffff',
+      },
+      border: {
+        default: '#d1d5db',
+        strong: '#9ca3af',
+        focus: '#0f766e',
+      },
+      action: {
+        primary: createRole('#0f766e'),
+        neutral: createRole('#4b5563'),
+        danger: createRole('#dc2626'),
+      },
+    },
+    shadows: {
+      soft: 2,
+      medium: 4,
+      hard: 8,
+    },
+    spacing: {
+      none: 0,
+      xs: 4,
+      s: 8,
+      m: 16,
+      l: 24,
+      xl: 32,
+      xxl: 48,
+    },
+    typography: {
+      headings: {
+        1: { size: 32, lineHeight: 40, weight: 'bold' },
+        2: { size: 24, lineHeight: 32, weight: 'bold' },
+        3: { size: 20, lineHeight: 28, weight: 'bold' },
+        4: { size: 18, lineHeight: 24, weight: 'semiBold' },
+        5: { size: 16, lineHeight: 22, weight: 'semiBold' },
+        6: { size: 14, lineHeight: 20, weight: 'semiBold' },
+      },
+      sizes: {
+        xs: 12,
+        s: 14,
+        m: 16,
+        l: 18,
+        xl: 20,
+        xxl: 24,
+        '3xl': 30,
+        h1: 32,
+        h2: 24,
+        h3: 20,
+        h4: 18,
+        h5: 16,
+        h6: 14,
+      },
+      weights: {
+        thin: '100',
+        extraLight: '200',
+        light: '300',
+        regular: '400',
+        medium: '500',
+        semiBold: '600',
+        bold: '700',
+        extraBold: '800',
+        black: '900',
+      },
+      fonts: {
+        normal: { ...emptyFonts },
+        italic: { ...emptyFonts },
+      },
+    },
+  };
+}
+
+const theme = createTestTheme();
+
+describe('resolveHeadingRecipe', () => {
+  test('maps level 1 default size to h1 typography', () => {
+    const style = resolveHeadingRecipe(theme, { level: 1 });
+
+    expect(style.fontSize).toBe(theme.typography.headings[1].size);
+    expect(style.lineHeight).toBe(theme.typography.headings[1].lineHeight);
+    expect(style.fontWeight).toBe(theme.typography.weights.bold);
+    expect(style.color).toBe(theme.semantics.content.default);
+    expect(style.elevation).toBe(0);
+  });
+
+  test('maps level 3 default size to h3 typography', () => {
+    const style = resolveHeadingRecipe(theme, { level: 3 });
+
+    expect(style.fontSize).toBe(theme.typography.headings[3].size);
+    expect(style.lineHeight).toBe(theme.typography.headings[3].lineHeight);
+    expect(style.fontWeight).toBe(theme.typography.weights.bold);
+  });
+
+  test('allows size to override level-derived visual size', () => {
+    const style = resolveHeadingRecipe(theme, { level: 1, size: 'h4' });
+
+    expect(style.fontSize).toBe(theme.typography.headings[4].size);
+    expect(style.lineHeight).toBe(theme.typography.headings[4].lineHeight);
+    expect(style.fontWeight).toBe(theme.typography.weights.semiBold);
+  });
+
+  test('resolves display size from existing theme typography tokens', () => {
+    const style = resolveHeadingRecipe(theme, { level: 1, size: 'display' });
+
+    expect(style.fontSize).toBe(theme.typography.sizes['3xl']);
+    expect(style.lineHeight).toBe(theme.typography.sizes['3xl'] + 8);
+    expect(style.fontWeight).toBe(theme.typography.weights.bold);
+  });
+
+  test('maps semantic emphasis and colors to theme colors', () => {
+    expect(resolveHeadingRecipe(theme, { level: 2, color: 'primary' }).color).toBe(
+      theme.semantics.action.primary.base,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, emphasis: 'muted' }).color).toBe(
+      theme.semantics.content.muted,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, emphasis: 'subtle' }).color).toBe(
+      theme.semantics.content.subtle,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, emphasis: 'inverse' }).color).toBe(
+      theme.semantics.content.inverse,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, color: 'danger' }).color).toBe(
+      theme.semantics.action.danger.base,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, color: 'success' }).color).toBe(
+      theme.semantics.success.base,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, color: 'warning' }).color).toBe(
+      theme.semantics.warning.base,
+    );
+    expect(
+      resolveHeadingRecipe(theme, { level: 2, color: 'primary', emphasis: 'inverse' }).color,
+    ).toBe(theme.semantics.action.primary.onSolidText);
+  });
+
+  test('applies alignment', () => {
+    const style = resolveHeadingRecipe(theme, { level: 2, align: 'center' });
+
+    expect(style.textAlign).toBe('center');
+  });
+
+  test('allows explicit weight to override the recipe weight', () => {
+    const style = resolveHeadingRecipe(theme, { level: 4, weight: 'medium' });
+
+    expect(style.fontWeight).toBe(theme.typography.weights.medium);
+  });
+
+  test('uses italic font family when available', () => {
+    const fontTheme = createTestTheme();
+    fontTheme.typography.fonts.italic[fontTheme.typography.weights.semiBold] = 'ZoraSemiBoldItalic';
+
+    const style = resolveHeadingRecipe(fontTheme, { level: 4, italic: true });
+
+    expect(style.fontStyle).toBe('italic');
+    expect(style.fontFamily).toBe('ZoraSemiBoldItalic');
+  });
+});
+
+describe('resolveHeadingSizeFromLevel', () => {
+  test('maps semantic levels to default visual sizes', () => {
+    expect(resolveHeadingSizeFromLevel(1)).toBe('h1');
+    expect(resolveHeadingSizeFromLevel(2)).toBe('h2');
+    expect(resolveHeadingSizeFromLevel(3)).toBe('h3');
+    expect(resolveHeadingSizeFromLevel(4)).toBe('h4');
+    expect(resolveHeadingSizeFromLevel(5)).toBe('h5');
+    expect(resolveHeadingSizeFromLevel(6)).toBe('h6');
+  });
+});

package/src/features/typography/utils/resolveHeadingRecipe.ts

@@ -0,0 +1,174 @@
+import type { FontWeight, RoleSemantics, SurfaceTheme } from '@ankhorage/surface';
+import type { TextStyle } from 'react-native';
+
+import type {
+  HeadingAlign,
+  HeadingColor,
+  HeadingEmphasis,
+  HeadingLevel,
+  HeadingSize,
+  HeadingWeight,
+} from '../../../types/heading';
+import { resolveHeadingSizeFromLevel } from './resolveHeadingSizeFromLevel';
+export function resolveHeadingRecipe(
+  theme: SurfaceTheme,
+  {
+    align,
+    color,
+    emphasis = 'default',
+    italic = false,
+    level,
+    size,
+    weight,
+  }: ResolveHeadingRecipeOptions,
+): TextStyle {
+  const recipe = resolveSizeRecipe(theme, size ?? resolveHeadingSizeFromLevel(level));
+  const resolvedWeight = resolveWeight(theme, weight ?? recipe.weight);
+
+  return {
+    color: resolveHeadingColor(theme, emphasis, color),
+    elevation: 0,
+    fontFamily: resolveFontFamily({ theme, weight: resolvedWeight, italic }),
+    fontSize: recipe.fontSize,
+    fontStyle: italic ? 'italic' : 'normal',
+    fontWeight: resolvedWeight,
+    lineHeight: recipe.lineHeight,
+    textAlign: align,
+  };
+}
+
+interface ResolveHeadingRecipeOptions {
+  level: HeadingLevel;
+  size?: HeadingSize;
+  color?: HeadingColor;
+  emphasis?: HeadingEmphasis;
+  align?: HeadingAlign;
+  weight?: HeadingWeight;
+  italic?: boolean;
+}
+
+interface HeadingRecipe {
+  fontSize: number;
+  lineHeight: number;
+  weight: HeadingWeight;
+}
+
+function resolveHeadingLevelFromSize(size: Exclude<HeadingSize, 'display'>): HeadingLevel {
+  switch (size) {
+    case 'h1':
+      return 1;
+    case 'h2':
+      return 2;
+    case 'h3':
+      return 3;
+    case 'h4':
+      return 4;
+    case 'h5':
+      return 5;
+    case 'h6':
+      return 6;
+  }
+}
+
+function resolveSizeRecipe(theme: SurfaceTheme, size: HeadingSize): HeadingRecipe {
+  if (size === 'display') {
+    const fontSize = theme.typography.sizes['3xl'];
+
+    return {
+      fontSize,
+      lineHeight: fontSize + 8,
+      weight: 'bold',
+    };
+  }
+
+  const heading = theme.typography.headings[resolveHeadingLevelFromSize(size)];
+
+  return {
+    fontSize: heading.size,
+    lineHeight: heading.lineHeight,
+    weight: heading.weight,
+  };
+}
+
+function resolveRoleSemantics(theme: SurfaceTheme, color: HeadingColor): RoleSemantics {
+  switch (color) {
+    case 'secondary':
+      return theme.semantics.secondary;
+    case 'tertiary':
+      return theme.semantics.accent;
+    case 'quaternary':
+      return theme.semantics.highlight;
+    case 'neutral':
+      return theme.semantics.action.neutral;
+    case 'error':
+      return theme.semantics.error;
+    case 'info':
+      return theme.semantics.info;
+    case 'danger':
+      return theme.semantics.action.danger;
+    case 'success':
+      return theme.semantics.success;
+    case 'warning':
+      return theme.semantics.warning;
+    case 'primary':
+    default:
+      return theme.semantics.action.primary;
+  }
+}
+
+function resolveHeadingColor(
+  theme: SurfaceTheme,
+  emphasis: HeadingEmphasis,
+  color?: HeadingColor,
+): string {
+  if (color) {
+    const role = resolveRoleSemantics(theme, color);
+    return emphasis === 'inverse' ? role.onSolidText : role.base;
+  }
+
+  switch (emphasis) {
+    case 'muted':
+      return theme.semantics.content.muted;
+    case 'subtle':
+      return theme.semantics.content.subtle;
+    case 'inverse':
+      return theme.semantics.content.inverse;
+    case 'default':
+    default:
+      return theme.semantics.content.default;
+  }
+}
+
+function resolveWeight(theme: SurfaceTheme, weight: HeadingWeight): FontWeight {
+  switch (weight) {
+    case 'medium':
+      return theme.typography.weights.medium;
+    case 'semiBold':
+      return theme.typography.weights.semiBold;
+    case 'bold':
+      return theme.typography.weights.bold;
+    case 'regular':
+    default:
+      return theme.typography.weights.regular;
+  }
+}
+
+function resolveFontFamily({
+  theme,
+  weight,
+  italic,
+}: {
+  theme: SurfaceTheme;
+  weight: FontWeight;
+  italic: boolean;
+}): string | undefined {
+  const fonts = italic ? theme.typography.fonts.italic : theme.typography.fonts.normal;
+
+  for (const [fontWeight, fontFamily] of Object.entries(fonts)) {
+    if (fontWeight === weight) {
+      return fontFamily;
+    }
+  }
+
+  return undefined;
+}

package/src/features/typography/utils/resolveHeadingSizeFromLevel.ts

@@ -0,0 +1,19 @@
+import type { HeadingLevel, HeadingSize } from '../../../types/heading';
+
+/*** Maps an accessible heading level to its default semantic visual size. */
+export function resolveHeadingSizeFromLevel(level: HeadingLevel): HeadingSize {
+  switch (level) {
+    case 1:
+      return 'h1';
+    case 2:
+      return 'h2';
+    case 3:
+      return 'h3';
+    case 4:
+      return 'h4';
+    case 5:
+      return 'h5';
+    case 6:
+      return 'h6';
+  }
+}