@ankhorage/surface 0.1.5 → 0.1.7

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;
+}