@ankhorage/surface 0.1.5 → 0.1.7

package/src/primitives/heading/resolveHeadingStyle.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createTheme } from '../../theme/createTheme';
+import { resolveHeadingTextStyle } from './resolveHeadingStyle';
+
+describe('resolveHeadingTextStyle', () => {
+  it('maps heading levels to theme-driven typography tokens', () => {
+    const theme = createTheme();
+    const style = resolveHeadingTextStyle(theme, 4, 'center');
+
+    expect(style.fontSize).toBe(18);
+    expect(style.lineHeight).toBe(24);
+    expect(style.fontWeight).toBe('600');
+    expect(style.color).toBe(theme.colors.text);
+    expect(style.textAlign).toBe('center');
+  });
+
+  it('uses the themed font family when one is configured', () => {
+    const theme = createTheme(undefined, 'light', 'space grotesk');
+    const style = resolveHeadingTextStyle(theme, 1);
+
+    expect(style.fontFamily).toBe('SpaceGrotesk_700Regular');
+  });
+
+  it('shares the default content tone with the text primitive', () => {
+    const theme = createTheme();
+    const style = resolveHeadingTextStyle(theme, 2);
+
+    expect(style.color).toBe(theme.semantics.content.default);
+  });
+});

package/src/primitives/heading/resolveHeadingStyle.ts

@@ -0,0 +1,17 @@
+import type { TextStyle } from 'react-native';
+
+import { resolveTextColor } from '../../internal/resolvers/resolveTextColor';
+import { resolveTextStyles } from '../../internal/resolvers/resolveTextStyles';
+import type { AnkhTheme } from '../../theme/types';
+import type { HeadingLevel, HeadingProps } from './types';
+
+export function resolveHeadingTextStyle(
+  theme: AnkhTheme,
+  level: HeadingLevel,
+  align?: HeadingProps['align'],
+): TextStyle {
+  return {
+    ...resolveTextStyles(theme, { align, level }),
+    color: resolveTextColor(theme, 'default'),
+  };
+}

package/src/primitives/heading/types.ts

@@ -0,0 +1,13 @@
+import type React from 'react';
+
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface HeadingProps {
+  text?: string;
+  children?: React.ReactNode;
+  level?: HeadingLevel;
+  align?: 'auto' | 'left' | 'right' | 'center' | 'justify';
+  numberOfLines?: number;
+  i18nKey?: string;
+  testID?: string;
+}

package/src/primitives/icon/Icon.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { type StyleProp, type TextStyle } from 'react-native';
+
+import { resolveToken } from '../../theme/resolveToken';
+import { useTheme } from '../../theme/ThemeContext';
+import type { AnkhTheme } from '../../theme/types';
+import { resolveExpoIconComponent } from './resolveExpoIconComponent';
+
+export type IconProvider = string;
+
+export interface IconProps {
+  name: string;
+  provider?: IconProvider;
+  size?: keyof AnkhTheme['spacing'] | number;
+  color?: keyof AnkhTheme['colors'] | string;
+  style?: StyleProp<TextStyle>;
+  testID?: string;
+}
+
+export function Icon({
+  name,
+  provider = 'Ionicons',
+  size = 'm',
+  color = 'text',
+  style,
+  testID,
+}: IconProps) {
+  const { theme } = useTheme();
+  const IconComponent = resolveExpoIconComponent(provider);
+  const resolvedSize = typeof size === 'number' ? size : resolveToken(theme.spacing, size);
+  const resolvedColor = resolveToken(theme.colors, color);
+
+  return React.createElement(IconComponent, {
+    color: resolvedColor,
+    name,
+    size: resolvedSize,
+    style,
+    testID,
+  });
+}

package/src/primitives/icon/index.ts

@@ -0,0 +1,2 @@
+export type { IconProps, IconProvider } from './Icon';
+export { Icon } from './Icon';

package/src/primitives/icon/resolveExpoIconComponent.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, mock, test } from 'bun:test';
+
+const Ionicons = () => null;
+const MaterialIcons = () => null;
+
+describe('resolveExpoIconComponent', () => {
+  test('returns the requested Expo icon family when it exists', async () => {
+    await mock.module('@expo/vector-icons', () => ({
+      Ionicons,
+      MaterialIcons,
+    }));
+
+    const { resolveExpoIconComponent } = await import('./resolveExpoIconComponent');
+
+    expect(resolveExpoIconComponent('Ionicons')).toBe(Ionicons);
+    expect(resolveExpoIconComponent('MaterialIcons')).toBe(MaterialIcons);
+  });
+
+  test('falls back to Ionicons when the provider is unknown', async () => {
+    await mock.module('@expo/vector-icons', () => ({
+      Ionicons,
+      MaterialIcons,
+    }));
+
+    const { resolveExpoIconComponent } = await import('./resolveExpoIconComponent');
+
+    expect(resolveExpoIconComponent('MissingIconFamily')).toBe(Ionicons);
+  });
+});

package/src/primitives/icon/resolveExpoIconComponent.ts

@@ -0,0 +1,20 @@
+import * as ExpoIcons from '@expo/vector-icons';
+import type React from 'react';
+import { type StyleProp, type TextStyle } from 'react-native';
+
+export type ExpoIconComponent = React.ElementType<{
+  color?: string;
+  name?: string;
+  size?: number;
+  style?: StyleProp<TextStyle>;
+  testID?: string;
+}>;
+
+export function resolveExpoIconComponent(provider: string): ExpoIconComponent {
+  const candidate = (ExpoIcons as Record<string, unknown>)[provider];
+  if (typeof candidate === 'function') {
+    return candidate as ExpoIconComponent;
+  }
+
+  return ExpoIcons.Ionicons as ExpoIconComponent;
+}

package/src/primitives/text/Text.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import { Text as ReactNativeText } from 'react-native';
+
+import { useTranslationContext } from '../../context/TranslationContext';
+import { resolveTextColor, resolveTextStyles } from '../../internal/resolvers';
+import { useTheme } from '../../theme/ThemeContext';
+import type { TextProps } from './types';
+
+function resolveTextContent(
+  children: TextProps['children'],
+  i18nKey: TextProps['i18nKey'],
+  translate: (key: string) => string,
+) {
+  if (children !== undefined) {
+    return children;
+  }
+
+  if (!i18nKey) {
+    return null;
+  }
+
+  try {
+    const translated = translate(i18nKey);
+    return translated && translated !== i18nKey ? translated : i18nKey;
+  } catch (error) {
+    console.warn('[Text] Translation error:', error);
+    return i18nKey;
+  }
+}
+
+export function Text({
+  children,
+  i18nKey,
+  variant = 'body',
+  tone = 'default',
+  color,
+  align,
+  weight,
+  italic = false,
+  numberOfLines,
+  testID,
+}: TextProps) {
+  const { theme } = useTheme();
+  const { t } = useTranslationContext();
+  const content = resolveTextContent(children, i18nKey, t);
+
+  return (
+    <ReactNativeText
+      numberOfLines={numberOfLines}
+      testID={testID}
+      style={[
+        resolveTextStyles(theme, {
+          align,
+          italic,
+          variant,
+          weight,
+        }),
+        {
+          color: resolveTextColor(theme, tone, color),
+        },
+      ]}
+    >
+      {content}
+    </ReactNativeText>
+  );
+}

package/src/primitives/text/index.ts

@@ -0,0 +1,2 @@
+export { Text } from './Text';
+export type { TextProps } from './types';

package/src/primitives/text/types.ts

@@ -0,0 +1,18 @@
+import type React from 'react';
+import type { TextStyle } from 'react-native';
+
+import type { TextColorValue, TextTone } from '../../internal/resolvers/resolveTextColor';
+import type { TextVariant, TextWeight } from '../../internal/resolvers/resolveTextStyles';
+
+export interface TextProps {
+  children?: React.ReactNode;
+  i18nKey?: string;
+  variant?: TextVariant;
+  tone?: TextTone;
+  color?: TextColorValue;
+  align?: TextStyle['textAlign'];
+  weight?: TextWeight;
+  italic?: boolean;
+  numberOfLines?: number;
+  testID?: string;
+}

package/src/theme/ThemeContext.tsx

@@ -0,0 +1,95 @@
+import React, { createContext, useContext, useMemo } from 'react';
+
+import { useFontContext } from '../context/FontContext';
+import { ResponsiveProvider } from '../core/responsive/ResponsiveProvider';
+import { OverlayProvider } from '../internal/overlay/OverlayProvider';
+import { isDeepEqual } from '../utils/deepEqual';
+import { deepMerge } from '../utils/deepMerge';
+import { createTheme } from './createTheme';
+import type { AnkhTheme, ThemeConfig } from './types';
+
+const defaultTheme = createTheme();
+
+export const ThemeContext = createContext<{
+  theme: AnkhTheme;
+  mode: 'light' | 'dark';
+  setThemeConfig: (config: Partial<ThemeConfig>) => void;
+  setMode: (mode: 'light' | 'dark') => void;
+  _hasProvider?: boolean;
+}>({
+  theme: defaultTheme,
+  mode: 'light',
+  setThemeConfig: () => {
+    /* fallback */
+  },
+  setMode: () => {
+    /* fallback */
+  },
+  _hasProvider: false,
+});
+
+export const ThemeProvider = ({
+  children,
+  initialConfig,
+  initialMode = 'light',
+}: {
+  children: React.ReactNode;
+  initialConfig?: Partial<ThemeConfig>;
+  initialMode?: 'light' | 'dark';
+}) => {
+  const [config, setConfig] = React.useState<ThemeConfig>(() =>
+    initialConfig ? deepMerge(defaultTheme.config, initialConfig) : defaultTheme.config,
+  );
+  const [mode, setMode] = React.useState<'light' | 'dark'>(initialMode);
+  const { activeFontId } = useFontContext();
+
+  // Keep state in sync with prop for real-time Studio updates
+  React.useEffect(() => {
+    if (initialConfig) {
+      setConfig((prev) => {
+        const merged = deepMerge(prev, initialConfig);
+        if (isDeepEqual(prev, merged)) return prev;
+        return merged;
+      });
+    }
+  }, [initialConfig]);
+
+  const theme = useMemo(
+    () => createTheme(config, mode, activeFontId),
+    [config, mode, activeFontId],
+  );
+
+  const value = useMemo(
+    () => ({
+      theme,
+      mode,
+      setThemeConfig: (newConfig: Partial<ThemeConfig>) =>
+        setConfig((prev) => deepMerge(prev, newConfig)),
+      setMode,
+      _hasProvider: true,
+    }),
+    [theme, mode],
+  );
+
+  return (
+    <ResponsiveProvider>
+      <ThemeContext.Provider value={value}>
+        <OverlayProvider>{children}</OverlayProvider>
+      </ThemeContext.Provider>
+    </ResponsiveProvider>
+  );
+};
+
+export const useTheme = () => {
+  return useContext(ThemeContext);
+};
+
+export const useThemeConfig = () => {
+  const { setThemeConfig } = useTheme();
+  return setThemeConfig;
+};
+
+export const useThemeMode = () => {
+  const { mode, setMode } = useTheme();
+  return { mode, setMode };
+};

package/src/theme/colorEngine.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'bun:test';
+import { oklch } from 'culori';
+
+import { generatePalette } from './colorEngine';
+import type { ThemeConfig } from './types';
+
+const mockConfig: ThemeConfig = {
+  id: 'test',
+  name: 'Test Theme',
+  light: {
+    primaryColor: '#3B82F6',
+    harmony: 'triadic',
+    systemTone: 'neutral',
+  },
+  dark: {
+    primaryColor: '#3B82F6',
+    harmony: 'triadic',
+    systemTone: 'neutral',
+  },
+};
+
+describe('colorEngine', () => {
+  it('should generate a stable palette with deterministic chroma hierarchy', () => {
+    const { colors, semantics, scales } = generatePalette(mockConfig, 'light');
+
+    // Primary should be defined
+    expect(colors.primary).toBeDefined();
+
+    // Verify neutral surface chroma is strictly limited
+    const neutralBg = oklch(semantics.neutral.bg);
+    expect(neutralBg?.c).toBeLessThanOrEqual(0.021); // Small epsilon for float
+
+    // Verify presence of new tokens
+    expect(semantics.neutral.bgSubtle).toBeDefined();
+    expect(semantics.brand.onSolidText).toBeDefined();
+    expect(semantics.brand.softBg).toBeDefined();
+    expect(semantics.surface.default).toBe(semantics.neutral.surface);
+    expect(semantics.content.muted).toBe(semantics.neutral.textMuted);
+    expect(semantics.border.focus).toBe(semantics.brand.outline);
+    expect(semantics.action.primary.base).toBe(semantics.brand.base);
+    expect(semantics.action.danger.base).toBe(semantics.danger.base);
+
+    // Verify scale coverage
+    const primaryScale = scales.primary;
+    const neutralScale = scales.neutral;
+    expect(primaryScale).toBeDefined();
+    expect(neutralScale).toBeDefined();
+    if (!primaryScale || !neutralScale) throw new Error('Expected generated scales');
+    expect(Object.keys(primaryScale)).toHaveLength(11);
+    expect(neutralScale[50]).toBeDefined();
+    expect(neutralScale[950]).toBeDefined();
+  });
+
+  it('should respect triadic hue offsets (120 degrees)', () => {
+    const { colors } = generatePalette(mockConfig, 'light');
+
+    const p = oklch(colors.primary);
+    const s = oklch(colors.secondary);
+    const a = oklch(colors.accent);
+
+    if (p && s && a) {
+      const h1 = p.h ?? 0;
+      const h2 = s.h ?? 0;
+      const h3 = a.h ?? 0;
+
+      // Check distance (allowing for small float rounding and perceptual shift)
+      const diff1 = Math.abs((h2 - h1 + 360) % 360);
+      const diff2 = Math.abs((h3 - h1 + 360) % 360);
+
+      expect(diff1).toBeGreaterThan(115);
+      expect(diff1).toBeLessThan(125);
+      expect(diff2).toBeGreaterThan(235);
+      expect(diff2).toBeLessThan(245);
+    }
+  });
+
+  it('should handle monochromatic harmony (one hue)', () => {
+    const config = {
+      ...mockConfig,
+      light: { ...mockConfig.light, harmony: 'monochromatic' as const },
+    };
+    const { colors } = generatePalette(config, 'light');
+
+    const p = oklch(colors.primary);
+    const s = oklch(colors.secondary);
+
+    expect(p?.h).toBeCloseTo(s?.h ?? 0, 0);
+  });
+
+  it('should generate dark mode colors correctly', () => {
+    const { colors, semantics } = generatePalette(mockConfig, 'dark');
+
+    const bg = oklch(colors.background);
+    expect(bg?.l).toBeLessThan(0.2); // Should be dark
+    expect(colors.background).toBe(semantics.neutral.bg);
+    expect(semantics.content.inverse).toBe(semantics.brand.onSolidText);
+  });
+
+  it('should fall back to a default color if primaryColor is invalid', () => {
+    const config = {
+      ...mockConfig,
+      light: { ...mockConfig.light, primaryColor: 'invalid-color' },
+    };
+
+    // Should not throw
+    const { colors } = generatePalette(config, 'light');
+    expect(colors.primary).toBeDefined();
+    // Default fallback blue #3B82F6 in OKLCH
+    const p = oklch(colors.primary);
+    const fallbackBlue = oklch('#3B82F6');
+    expect(fallbackBlue).toBeDefined();
+    expect(p?.h).toBeCloseTo(fallbackBlue?.h ?? 0, 0);
+  });
+});