@ankhorage/surface 0.1.4 → 0.1.6

package/src/theme/createTheme.ts

@@ -0,0 +1,121 @@
+import { generatePalette } from './colorEngine';
+import type { AnkhTheme, FontWeight, ThemeConfig, ThemeTokens } from './types';
+
+export const DEFAULT_TOKENS: Omit<ThemeTokens, 'colors' | 'scales' | 'semantics'> = {
+  spacing: {
+    none: 0,
+    xs: 4,
+    s: 8,
+    m: 16,
+    l: 24,
+    xl: 32,
+    xxl: 48,
+  },
+  radii: {
+    none: 0,
+    s: 4,
+    m: 8,
+    l: 16,
+    full: 9999,
+  },
+  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: {} as Record<FontWeight, string | undefined>,
+      italic: {} as Record<FontWeight, string | undefined>,
+    },
+  },
+  shadows: {
+    soft: 2,
+    medium: 4,
+    hard: 8,
+  },
+};
+
+export const DEFAULT_CONFIG: ThemeConfig = {
+  id: 'default',
+  name: 'Default',
+  light: {
+    primaryColor: '#3B82F6',
+    harmony: 'monochromatic',
+    systemTone: 'neutral',
+  },
+  dark: {
+    primaryColor: '#3B82F6',
+    harmony: 'monochromatic',
+    systemTone: 'neutral',
+  },
+};
+
+/**
+ * Normalizes font family name to PascalCase for consistent key generation
+ * matches GoogleFontsPlugin logic.
+ */
+function toPascalCase(str: string) {
+  return str
+    .split(/[- ]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+}
+
+export function createTheme(
+  config: ThemeConfig = DEFAULT_CONFIG,
+  mode: 'light' | 'dark' = 'light',
+  activeFontId?: string | null,
+): AnkhTheme {
+  const { colors, scales, semantics } = generatePalette(config, mode);
+
+  const theme = {
+    ...DEFAULT_TOKENS,
+    colors: colors as AnkhTheme['colors'],
+    scales,
+    semantics,
+    config,
+  };
+
+  if (activeFontId) {
+    const familyName = toPascalCase(activeFontId);
+    const weights: FontWeight[] = ['100', '200', '300', '400', '500', '600', '700', '800', '900'];
+
+    weights.forEach((w) => {
+      // Convention from GoogleFonts plugin: Family_WeightRegular
+      theme.typography.fonts.normal[w] = `${familyName}_${w}Regular`;
+      theme.typography.fonts.italic[w] = `${familyName}_${w}Italic`;
+    });
+  }
+
+  return theme;
+}

package/src/theme/index.ts

@@ -0,0 +1,5 @@
+export * from './colorEngine';
+export * from './createTheme';
+export * from './resolveToken';
+export * from './ThemeContext';
+export * from './types';

package/src/theme/resolveToken.ts

@@ -0,0 +1,32 @@
+/**
+ * 1. Define the Conditional Logic
+ * If TValue is a key of TMap, return the map's value type.
+ * Otherwise, return TValue itself.
+ */
+type ResolvedToken<TMap, TValue> = TValue extends keyof TMap ? TMap[TValue] : TValue;
+
+/**
+ * 2. The Generic Function
+ */
+export function resolveToken<
+  TMap extends Record<string | number, unknown>,
+  TValue extends string | number | undefined,
+>(map: TMap, value: TValue): ResolvedToken<TMap, TValue> {
+  // Undefined check
+  if (value === undefined) {
+    return undefined as ResolvedToken<TMap, TValue>;
+  }
+
+  // Runtime check: Is 'value' a key in 'map'?
+  if (
+    (typeof value === 'string' || typeof value === 'number') &&
+    Object.prototype.hasOwnProperty.call(map, value)
+  ) {
+    // Return the mapped token
+    // We cast to the specific conditional type, strictly safer than 'any'
+    return map[value as keyof TMap] as ResolvedToken<TMap, TValue>;
+  }
+
+  // Fallback: Return raw value
+  return value as ResolvedToken<TMap, TValue>;
+}

package/src/theme/types.ts

@@ -0,0 +1,188 @@
+import type { ThemeConfig as ContractsThemeConfig } from '@ankhorage/contracts';
+
+export type { ColorHarmony, SystemTone, ThemeConfig, ThemeModeConfig } from '@ankhorage/contracts';
+
+export type ColorTone = 'jewel' | 'earth' | 'fluorescent' | 'grayscale' | 'pastel';
+
+export interface ColorScale {
+  [key: number]: string;
+  50: string;
+  100: string;
+  200: string;
+  300: string;
+  400: string;
+  500: string;
+  600: string;
+  700: string;
+  800: string;
+  900: string;
+  950: string;
+}
+
+export interface NeutralSemantics {
+  bg: string;
+  bgSubtle: string;
+  surface: string;
+  surfaceHover: string;
+  surfaceActive: string;
+  border: string;
+  borderStrong: string;
+  divider: string;
+  text: string;
+  textMuted: string;
+  textSubtle: string;
+}
+
+export interface RoleSemantics {
+  base: string;
+  hover: string;
+  strong: string;
+  softBg: string;
+  softHover: string;
+  softActive: string;
+  outline: string;
+  onSolidText: string;
+}
+
+export interface SurfaceSemantics {
+  default: string;
+  subtle: string;
+  raised: string;
+}
+
+export interface ContentSemantics {
+  default: string;
+  muted: string;
+  subtle: string;
+  inverse: string;
+}
+
+export interface BorderSemantics {
+  default: string;
+  strong: string;
+  focus: string;
+}
+
+export interface ActionSemantics {
+  primary: RoleSemantics;
+  neutral: RoleSemantics;
+  danger: RoleSemantics;
+}
+
+export interface ThemeSemantics {
+  neutral: NeutralSemantics;
+  brand: RoleSemantics;
+  secondary: RoleSemantics;
+  accent: RoleSemantics;
+  highlight: RoleSemantics;
+  danger: RoleSemantics;
+  success: RoleSemantics;
+  warning: RoleSemantics;
+  surface: SurfaceSemantics;
+  content: ContentSemantics;
+  border: BorderSemantics;
+  action: ActionSemantics;
+}
+
+export type FontWeight =
+  | '100'
+  | '200'
+  | '300'
+  | '400'
+  | '500'
+  | '600'
+  | '700'
+  | '800'
+  | '900'
+  | 'bold'
+  | 'normal';
+
+export interface ThemeTokens {
+  colors: {
+    primary: string;
+    secondary: string;
+    accent: string;
+    highlight: string;
+    background: string;
+    surface: string;
+    text: string;
+    textSecondary: string;
+    border: string;
+    error: string;
+    success: string;
+    warning: string;
+    [key: string]: string;
+  };
+  scales: Record<string, ColorScale>;
+  semantics: ThemeSemantics;
+  spacing: {
+    none: 0;
+    xs: number;
+    s: number;
+    m: number;
+    l: number;
+    xl: number;
+    xxl: number;
+    [key: string]: number;
+  };
+  radii: {
+    none: 0;
+    s: number;
+    m: number;
+    l: number;
+    full: number;
+  };
+  typography: {
+    headings: Record<
+      1 | 2 | 3 | 4 | 5 | 6,
+      {
+        size: number;
+        lineHeight: number;
+        weight: 'regular' | 'medium' | 'semiBold' | 'bold';
+      }
+    >;
+    sizes: {
+      xs: number;
+      s: number;
+      m: number;
+      l: number;
+      xl: number;
+      xxl: number;
+      '3xl': number;
+      h1: number;
+      h2: number;
+      h3: number;
+      h4: number;
+      h5: number;
+      h6: number;
+      [key: string]: number;
+    };
+    weights: {
+      thin: FontWeight;
+      extraLight: FontWeight;
+      light: FontWeight;
+      regular: FontWeight;
+      medium: FontWeight;
+      semiBold: FontWeight;
+      bold: FontWeight;
+      extraBold: FontWeight;
+      black: FontWeight;
+    };
+    fonts: {
+      /** Map of weight -> fontFamily name for normal style */
+      normal: Record<FontWeight, string | undefined>;
+      /** Map of weight -> fontFamily name for italic style */
+      italic: Record<FontWeight, string | undefined>;
+    };
+  };
+  shadows: {
+    soft: number;
+    medium: number;
+    hard: number;
+    [key: string]: number;
+  };
+}
+
+export interface AnkhTheme extends ThemeTokens {
+  config: ContractsThemeConfig;
+}

package/src/utils/deepEqual.ts

@@ -0,0 +1,34 @@
+/**
+ * Simple deep equality check for JSON-serializable objects.
+ * Efficient enough for UI manifests.
+ */
+export const isDeepEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    if (Array.isArray(a)) {
+      if (!Array.isArray(b) || a.length !== b.length) return false;
+      for (let i = 0; i < a.length; i++) {
+        if (!isDeepEqual(a[i], b[i])) return false;
+      }
+      return true;
+    }
+
+    if (Array.isArray(b)) return false;
+
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+
+    const objA = a as Record<string, unknown>;
+    const objB = b as Record<string, unknown>;
+
+    for (const key of keysA) {
+      if (!Object.prototype.hasOwnProperty.call(objB, key)) return false;
+      if (!isDeepEqual(objA[key], objB[key])) return false;
+    }
+    return true;
+  }
+
+  return Number.isNaN(a) && Number.isNaN(b);
+};

package/src/utils/deepMerge.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'bun:test';
+
+import { deepMerge } from './deepMerge';
+
+type UnknownObject = Record<string, unknown>;
+
+describe('deepMerge', () => {
+  it('should merge top-level properties', () => {
+    const target: UnknownObject = { a: 1, b: 2 };
+    const source: UnknownObject = { b: 3, c: 4 };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1, b: 3, c: 4 });
+  });
+
+  it('should deeply merge nested objects', () => {
+    const target: UnknownObject = {
+      theme: {
+        colors: { primary: 'blue', background: 'white' },
+        spacing: { m: 10 },
+      },
+    };
+    const source: UnknownObject = {
+      theme: {
+        colors: { primary: 'red' },
+        spacing: { l: 20 },
+      },
+    };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({
+      theme: {
+        colors: { primary: 'red', background: 'white' },
+        spacing: { m: 10, l: 20 },
+      },
+    });
+  });
+
+  it('should handle undefined in source by keeping target value', () => {
+    const target = { a: 1 };
+    const source = { a: undefined };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1 });
+  });
+
+  it('should handle null in source by overwriting target value', () => {
+    const target: UnknownObject = { a: { b: 1 } };
+    const source: UnknownObject = { a: null };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: null });
+  });
+
+  it('should not merge arrays, but overwrite them', () => {
+    const target = { list: [1, 2] };
+    const source = { list: [3] };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ list: [3] });
+  });
+
+  it('should handle merging an object into a non-object target value', () => {
+    const target: UnknownObject = { a: 1 };
+    const source: UnknownObject = { a: { b: 2 } };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: { b: 2 } });
+  });
+
+  it('should handle merging a non-object into an object target value', () => {
+    const target: UnknownObject = { a: { b: 1 } };
+    const source: UnknownObject = { a: 2 };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 2 });
+  });
+
+  it('should return a new object and not mutate target', () => {
+    const target = { a: { b: 1 } };
+    const source = { a: { b: 2 } };
+    const result = deepMerge(target, source);
+    expect(result).not.toBe(target);
+    expect(result.a).not.toBe(target.a);
+    expect(target.a.b).toBe(1);
+  });
+
+  it('should handle complex ThemeConfig structures', () => {
+    const target: UnknownObject = {
+      id: 'theme-1',
+      name: 'Default',
+      light: {
+        primaryColor: 'blue',
+        harmony: 'monochromatic',
+        systemTone: 'neutral',
+      },
+      dark: {
+        primaryColor: 'blue',
+        harmony: 'monochromatic',
+        systemTone: 'neutral',
+      },
+    };
+    const source: UnknownObject = {
+      light: {
+        primaryColor: 'red',
+      },
+    };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({
+      id: 'theme-1',
+      name: 'Default',
+      light: {
+        primaryColor: 'red',
+        harmony: 'monochromatic',
+        systemTone: 'neutral',
+      },
+      dark: {
+        primaryColor: 'blue',
+        harmony: 'monochromatic',
+        systemTone: 'neutral',
+      },
+    });
+  });
+});

package/src/utils/deepMerge.ts

@@ -0,0 +1,29 @@
+/**
+ * Performs a deep merge of `source` into `target`.
+ * Specifically handles the nested structure of ThemeConfig (light/dark objects).
+ */
+export function deepMerge<T extends object>(target: T, source: Partial<T>): T {
+  const result = { ...target };
+
+  (Object.keys(source) as (keyof T)[]).forEach((key) => {
+    const sourceValue = source[key];
+    const targetValue = target[key];
+
+    if (
+      sourceValue &&
+      typeof sourceValue === 'object' &&
+      !Array.isArray(sourceValue) &&
+      targetValue &&
+      typeof targetValue === 'object' &&
+      !Array.isArray(targetValue)
+    ) {
+      // Recursively merge nested objects
+      result[key] = deepMerge(targetValue as object, sourceValue as object) as T[keyof T];
+    } else if (sourceValue !== undefined) {
+      // Direct assignment for non-object values or if target doesn't have an object to merge with
+      result[key] = sourceValue as T[keyof T];
+    }
+  });
+
+  return result;
+}