@ankhorage/zora 0.6.3 → 0.7.0

package/dist/patterns/tile-grid/PaletteItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PaletteItem.d.ts","sourceRoot":"","sources":["../../../src/patterns/tile-grid/PaletteItem.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,WAAW,EACX,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,MAAM,GACP,EAAE,gBAAgB,qBAiClB"}
+{"version":3,"file":"PaletteItem.d.ts","sourceRoot":"","sources":["../../../src/patterns/tile-grid/PaletteItem.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,WAAW,EACX,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,MAAM,GACP,EAAE,gBAAgB,qBAiClB"}

package/dist/patterns/tile-grid/PaletteItem.js

@@ -1,6 +1,7 @@
-import { Box, Heading, useTheme } from '@ankhorage/surface';
+import { Box, useTheme } from '@ankhorage/surface';
 import React from 'react';
 import { Card } from '../../components/card';
+import { Heading } from '../../components/heading';
 import { Text } from '../../components/text';
 export function PaletteItem({ title, description, icon, badge, selected, disabled, onPress, testID, }) {
     const { theme } = useTheme();

package/dist/patterns/tile-grid/PaletteItem.js.map

@@ -1 +1 @@
-{"version":3,"file":"PaletteItem.js","sourceRoot":"","sources":["../../../src/patterns/tile-grid/PaletteItem.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAG7C,MAAM,UAAU,WAAW,CAAC,EAC1B,KAAK,EACL,WAAW,EACX,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,MAAM,GACW;IACjB,MAAM,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,CAAC;IAE7B,OAAO,CACL,CAAC,IAAI,CACH,OAAO,CACP,QAAQ,CAAC,CAAC,QAAQ,CAAC,CACnB,OAAO,CAAC,CAAC,OAAO,CAAC,CACjB,MAAM,CAAC,CAAC,MAAM,CAAC,CACf,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CACtC,KAAK,CAAC,CACJ,QAAQ;YACN,CAAC,CAAC;gBACE,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO;gBACjC,WAAW,EAAE,CAAC;aACf;YACH,CAAC,CAAC,SACN,CAAC,CAED;MAAA,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAC1C;QAAA,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,oBAAoB,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CACvD;QAAA,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAC/B;UAAA,CAAC,KAAK,CACR;QAAA,EAAE,OAAO,CACT;QAAA,CAAC,WAAW,CAAC,CAAC,CAAC,CACb,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CACjD;YAAA,CAAC,WAAW,CACd;UAAA,EAAE,IAAI,CAAC,CACR,CAAC,CAAC,CAAC,IAAI,CACR;QAAA,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAC5C;MAAA,EAAE,GAAG,CACP;IAAA,EAAE,IAAI,CAAC,CACR,CAAC;AACJ,CAAC","sourcesContent":["import { Box, Heading, useTheme } from '@ankhorage/surface';\nimport React from 'react';\n\nimport { Card } from '../../components/card';\nimport { Text } from '../../components/text';\nimport type { PaletteItemProps } from './types';\n\nexport function PaletteItem({\n  title,\n  description,\n  icon,\n  badge,\n  selected,\n  disabled,\n  onPress,\n  testID,\n}: PaletteItemProps) {\n  const { theme } = useTheme();\n\n  return (\n    <Card\n      compact\n      disabled={disabled}\n      onPress={onPress}\n      testID={testID}\n      tone={selected ? 'default' : 'subtle'}\n      style={\n        selected\n          ? {\n              borderColor: theme.colors.primary,\n              borderWidth: 2,\n            }\n          : undefined\n      }\n    >\n      <Box p=\"xs\" style={{ alignItems: 'center' }}>\n        {icon ? <Box pb=\"s\">{/* Icon spec here */}</Box> : null}\n        <Heading level={5} align=\"center\">\n          {title}\n        </Heading>\n        {description ? (\n          <Text align=\"center\" tone=\"muted\" variant=\"caption\">\n            {description}\n          </Text>\n        ) : null}\n        {badge ? <Box pt=\"xs\">{badge}</Box> : null}\n      </Box>\n    </Card>\n  );\n}\n"]}
+{"version":3,"file":"PaletteItem.js","sourceRoot":"","sources":["../../../src/patterns/tile-grid/PaletteItem.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAG7C,MAAM,UAAU,WAAW,CAAC,EAC1B,KAAK,EACL,WAAW,EACX,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,MAAM,GACW;IACjB,MAAM,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,CAAC;IAE7B,OAAO,CACL,CAAC,IAAI,CACH,OAAO,CACP,QAAQ,CAAC,CAAC,QAAQ,CAAC,CACnB,OAAO,CAAC,CAAC,OAAO,CAAC,CACjB,MAAM,CAAC,CAAC,MAAM,CAAC,CACf,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CACtC,KAAK,CAAC,CACJ,QAAQ;YACN,CAAC,CAAC;gBACE,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO;gBACjC,WAAW,EAAE,CAAC;aACf;YACH,CAAC,CAAC,SACN,CAAC,CAED;MAAA,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAC1C;QAAA,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,oBAAoB,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CACvD;QAAA,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAC/B;UAAA,CAAC,KAAK,CACR;QAAA,EAAE,OAAO,CACT;QAAA,CAAC,WAAW,CAAC,CAAC,CAAC,CACb,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CACjD;YAAA,CAAC,WAAW,CACd;UAAA,EAAE,IAAI,CAAC,CACR,CAAC,CAAC,CAAC,IAAI,CACR;QAAA,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAC5C;MAAA,EAAE,GAAG,CACP;IAAA,EAAE,IAAI,CAAC,CACR,CAAC;AACJ,CAAC","sourcesContent":["import { Box, useTheme } from '@ankhorage/surface';\nimport React from 'react';\n\nimport { Card } from '../../components/card';\nimport { Heading } from '../../components/heading';\nimport { Text } from '../../components/text';\nimport type { PaletteItemProps } from './types';\n\nexport function PaletteItem({\n  title,\n  description,\n  icon,\n  badge,\n  selected,\n  disabled,\n  onPress,\n  testID,\n}: PaletteItemProps) {\n  const { theme } = useTheme();\n\n  return (\n    <Card\n      compact\n      disabled={disabled}\n      onPress={onPress}\n      testID={testID}\n      tone={selected ? 'default' : 'subtle'}\n      style={\n        selected\n          ? {\n              borderColor: theme.colors.primary,\n              borderWidth: 2,\n            }\n          : undefined\n      }\n    >\n      <Box p=\"xs\" style={{ alignItems: 'center' }}>\n        {icon ? <Box pb=\"s\">{/* Icon spec here */}</Box> : null}\n        <Heading level={5} align=\"center\">\n          {title}\n        </Heading>\n        {description ? (\n          <Text align=\"center\" tone=\"muted\" variant=\"caption\">\n            {description}\n          </Text>\n        ) : null}\n        {badge ? <Box pt=\"xs\">{badge}</Box> : null}\n      </Box>\n    </Card>\n  );\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {

package/src/components/card/Card.tsx

@@ -1,7 +1,8 @@
-import { Box, Card as SurfaceCard, Heading, Stack } from '@ankhorage/surface';
+import { Box, Card as SurfaceCard, Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { resolveCardVariant } from '../../internal/recipes';
+import { Heading } from '../heading';
 import { Text } from '../text';
 import type { CardProps } from './types';
 

package/src/components/drawer/Drawer.tsx

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

package/src/components/heading/Heading.tsx

@@ -0,0 +1,95 @@
+import { resolveResponsive, useResponsiveRuntime, useTranslationContext } from '@ankhorage/surface';
+import React from 'react';
+import { Text as ReactNativeText } from 'react-native';
+
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { resolveHeadingRecipe, resolveHeadingSizeFromLevel } from './resolveHeadingRecipe';
+import type { HeadingProps } from './types';
+
+function resolveHeadingContent({
+  children,
+  text,
+  i18nKey,
+  translate,
+}: {
+  children: HeadingProps['children'];
+  text: HeadingProps['text'];
+  i18nKey: HeadingProps['i18nKey'];
+  translate: (key: string) => string;
+}): React.ReactNode {
+  if (children !== undefined) {
+    return children;
+  }
+
+  if (text !== undefined) {
+    return text;
+  }
+
+  if (!i18nKey) {
+    return null;
+  }
+
+  try {
+    const translated = translate(i18nKey);
+    return translated && translated !== i18nKey ? translated : i18nKey;
+  } catch (error) {
+    console.warn('[ZoraHeading] Translation error:', error);
+    return i18nKey;
+  }
+}
+
+export function Heading({
+  children,
+  text,
+  i18nKey,
+  level = 2,
+  size,
+  tone = 'default',
+  align,
+  weight,
+  italic = false,
+  numberOfLines,
+  ellipsizeMode,
+  selectable,
+  accessibilityLabel,
+  accessibilityHint,
+  accessibilityRole = 'header',
+  nativeID,
+  testID,
+}: HeadingProps) {
+  const { theme } = useZoraTheme();
+  const { breakpoint } = useResponsiveRuntime();
+  const { t } = useTranslationContext();
+  const content = resolveHeadingContent({ children, text, i18nKey, translate: t });
+  const resolvedSize = resolveResponsive(size, breakpoint) ?? resolveHeadingSizeFromLevel(level);
+  const resolvedTone = resolveResponsive(tone, breakpoint) ?? 'default';
+  const resolvedAlign = resolveResponsive(align, breakpoint);
+  const resolvedWeight = resolveResponsive(weight, breakpoint);
+
+  if (content === null || content === undefined) {
+    return null;
+  }
+
+  return (
+    <ReactNativeText
+      accessibilityHint={accessibilityHint}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole={accessibilityRole}
+      ellipsizeMode={ellipsizeMode}
+      nativeID={nativeID}
+      numberOfLines={numberOfLines}
+      selectable={selectable}
+      testID={testID}
+      style={resolveHeadingRecipe(theme, {
+        align: resolvedAlign,
+        italic,
+        level,
+        size: resolvedSize,
+        tone: resolvedTone,
+        weight: resolvedWeight,
+      })}
+    >
+      {content}
+    </ReactNativeText>
+  );
+}

package/src/components/heading/index.ts

@@ -0,0 +1,9 @@
+export { Heading } from './Heading';
+export type {
+  HeadingAlign,
+  HeadingLevel,
+  HeadingProps,
+  HeadingSize,
+  HeadingTone,
+  HeadingWeight,
+} from './types';

package/src/components/heading/resolveHeadingRecipe.test.ts

@@ -0,0 +1,264 @@
+import type { AnkhTheme, FontWeight, RoleSemantics } from '@ankhorage/surface';
+import { describe, expect, test } from 'bun:test';
+
+import { resolveHeadingRecipe, resolveHeadingSizeFromLevel } from './resolveHeadingRecipe';
+
+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(): AnkhTheme {
+  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',
+        systemTone: 'jewel',
+      },
+      dark: {
+        primaryColor: '#2dd4bf',
+        harmony: 'analogous',
+        systemTone: 'jewel',
+      },
+    },
+    radii: {
+      none: 0,
+      s: 4,
+      m: 8,
+      l: 16,
+      full: 9999,
+    },
+    scales: {},
+    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 tones to theme colors', () => {
+    expect(resolveHeadingRecipe(theme, { level: 2, tone: 'primary' }).color).toBe(
+      theme.semantics.brand.base,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, tone: 'muted' }).color).toBe(
+      theme.semantics.content.muted,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, tone: 'subtle' }).color).toBe(
+      theme.semantics.content.subtle,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, tone: 'inverse' }).color).toBe(
+      theme.semantics.content.inverse,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, tone: 'danger' }).color).toBe(
+      theme.semantics.danger.base,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, tone: 'success' }).color).toBe(
+      theme.semantics.success.base,
+    );
+    expect(resolveHeadingRecipe(theme, { level: 2, tone: 'warning' }).color).toBe(
+      theme.semantics.warning.base,
+    );
+  });
+
+  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/components/heading/resolveHeadingRecipe.ts

@@ -0,0 +1,130 @@
+import type { AnkhTheme, FontWeight } from '@ankhorage/surface';
+import type { TextStyle } from 'react-native';
+
+import type { HeadingAlign, HeadingLevel, HeadingSize, HeadingTone, HeadingWeight } from './types';
+
+interface ResolveHeadingRecipeOptions {
+  level: HeadingLevel;
+  size?: HeadingSize;
+  tone?: HeadingTone;
+  align?: HeadingAlign;
+  weight?: HeadingWeight;
+  italic?: boolean;
+}
+
+interface HeadingRecipe {
+  fontSize: number;
+  lineHeight: number;
+  weight: HeadingWeight;
+}
+
+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';
+  }
+}
+
+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: AnkhTheme, 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 resolveToneColor(theme: AnkhTheme, tone: HeadingTone): string {
+  switch (tone) {
+    case 'muted':
+      return theme.semantics.content.muted;
+    case 'subtle':
+      return theme.semantics.content.subtle;
+    case 'inverse':
+      return theme.semantics.content.inverse;
+    case 'primary':
+      return theme.semantics.brand.base;
+    case 'danger':
+      return theme.semantics.danger.base;
+    case 'success':
+      return theme.semantics.success.base;
+    case 'warning':
+      return theme.semantics.warning.base;
+    case 'default':
+    default:
+      return theme.semantics.content.default;
+  }
+}
+
+function resolveWeight(theme: AnkhTheme, weight: HeadingWeight): FontWeight {
+  return theme.typography.weights[weight];
+}
+
+function resolveFontFamily({
+  theme,
+  weight,
+  italic,
+}: {
+  theme: AnkhTheme;
+  weight: FontWeight;
+  italic: boolean;
+}): string | undefined {
+  return theme.typography.fonts[italic ? 'italic' : 'normal'][weight];
+}
+
+export function resolveHeadingRecipe(
+  theme: AnkhTheme,
+  { align, italic = false, level, size, tone = 'default', weight }: ResolveHeadingRecipeOptions,
+): TextStyle {
+  const recipe = resolveSizeRecipe(theme, size ?? resolveHeadingSizeFromLevel(level));
+  const resolvedWeight = resolveWeight(theme, weight ?? recipe.weight);
+
+  return {
+    color: resolveToneColor(theme, tone),
+    elevation: 0,
+    fontFamily: resolveFontFamily({ theme, weight: resolvedWeight, italic }),
+    fontSize: recipe.fontSize,
+    fontStyle: italic ? 'italic' : 'normal',
+    fontWeight: resolvedWeight,
+    lineHeight: recipe.lineHeight,
+    textAlign: align,
+  };
+}

package/src/components/heading/types.ts

@@ -0,0 +1,41 @@
+import type { Responsive } from '@ankhorage/surface';
+import type React from 'react';
+import type { AccessibilityRole, TextStyle } from 'react-native';
+
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export type HeadingSize = 'display' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+export type HeadingTone =
+  | 'default'
+  | 'muted'
+  | 'subtle'
+  | 'inverse'
+  | 'primary'
+  | 'danger'
+  | 'success'
+  | 'warning';
+
+export type HeadingAlign = NonNullable<TextStyle['textAlign']>;
+
+export type HeadingWeight = 'regular' | 'medium' | 'semiBold' | 'bold';
+
+export interface HeadingProps {
+  children?: React.ReactNode;
+  text?: string;
+  i18nKey?: string;
+  level?: HeadingLevel;
+  size?: Responsive<HeadingSize>;
+  tone?: Responsive<HeadingTone>;
+  align?: Responsive<HeadingAlign>;
+  weight?: Responsive<HeadingWeight>;
+  italic?: boolean;
+  numberOfLines?: number;
+  ellipsizeMode?: 'head' | 'middle' | 'tail' | 'clip';
+  selectable?: boolean;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  accessibilityRole?: AccessibilityRole;
+  nativeID?: string;
+  testID?: string;
+}

package/src/components/modal/Modal.tsx

@@ -1,7 +1,8 @@
-import { Box, Heading, Modal as SurfaceModal, Stack } from '@ankhorage/surface';
+import { Box, Modal as SurfaceModal, Stack } from '@ankhorage/surface';
 import React, { useCallback, useEffect, useRef } from 'react';
 
 import { resolveDialogWidth } from '../../internal/recipes';
+import { Heading } from '../heading';
 import { Text } from '../text';
 import type { ModalProps } from './types';
 

package/src/index.ts

@@ -37,6 +37,15 @@ export {
   validateFields,
   validateValue,
 } from './components/form';
+export type {
+  HeadingAlign,
+  HeadingLevel,
+  HeadingProps,
+  HeadingSize,
+  HeadingTone,
+  HeadingWeight,
+} from './components/heading';
+export { Heading } from './components/heading';
 export type { IconProps } from './components/icon';
 export { Icon } from './components/icon';
 export type { IconButtonProps } from './components/icon-button';

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

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

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

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

package/src/patterns/tile-grid/PaletteItem.tsx

@@ -1,7 +1,8 @@
-import { Box, Heading, useTheme } from '@ankhorage/surface';
+import { Box, useTheme } from '@ankhorage/surface';
 import React from 'react';
 
 import { Card } from '../../components/card';
+import { Heading } from '../../components/heading';
 import { Text } from '../../components/text';
 import type { PaletteItemProps } from './types';