@soulcraft/theme 1.0.0

package/tests/oklch.test.ts

@@ -0,0 +1,256 @@
+/**
+ * @module tests/oklch
+ * @description Unit tests for OKLCH color space conversion utilities.
+ *
+ * Tests the full hex↔OKLCH round-trip conversion, parse/format fidelity,
+ * rgba conversion, and oklch arithmetic helpers (withAlpha, adjustL, rotateH).
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  hexToOklch,
+  oklchToHex,
+  parseOklch,
+  formatOklch,
+  rgbaToOklch,
+  withAlpha,
+  adjustL,
+  rotateH,
+} from '../src/oklch.js';
+
+// ─── hexToOklch ──────────────────────────────────────────────────────────────
+
+describe('hexToOklch', () => {
+  it('converts a 6-digit hex to oklch format', () => {
+    const result = hexToOklch('#2a9d8f');
+    expect(result).toMatch(/^oklch\(/);
+    expect(result).toMatch(/\)$/);
+  });
+
+  it('produces parseable oklch for black', () => {
+    expect(parseOklch(hexToOklch('#000000'))).not.toBeNull();
+  });
+
+  it('produces white-like lightness for #ffffff', () => {
+    const parsed = parseOklch(hexToOklch('#ffffff'));
+    expect(parsed).not.toBeNull();
+    expect(parsed![0]).toBeCloseTo(1, 1);
+    expect(parsed![1]).toBeCloseTo(0, 2);
+  });
+
+  it('expands 3-digit hex identically to 6-digit equivalent', () => {
+    expect(hexToOklch('#abc')).toBe(hexToOklch('#aabbcc'));
+  });
+
+  it('preserves alpha from 8-digit hex', () => {
+    const result = hexToOklch('#ffffff0d');
+    expect(result).toContain(' / ');
+    const parsed = parseOklch(result);
+    expect(parsed![3]).toBeCloseTo(0.051, 1); // 0x0d / 0xff ≈ 0.051
+  });
+});
+
+// ─── oklchToHex ──────────────────────────────────────────────────────────────
+
+describe('oklchToHex', () => {
+  it('round-trips #2a9d8f within ±1 per channel', () => {
+    const hex = '#2a9d8f';
+    const back = oklchToHex(hexToOklch(hex));
+    for (let i = 0; i < 3; i++) {
+      const offset = 1 + i * 2;
+      const original = parseInt(hex.slice(offset, offset + 2), 16);
+      const recovered = parseInt(back.slice(offset, offset + 2), 16);
+      expect(Math.abs(original - recovered)).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it('round-trips #0a0e1a (deep dark) within ±1 per channel', () => {
+    const hex = '#0a0e1a';
+    const back = oklchToHex(hexToOklch(hex));
+    for (let i = 0; i < 3; i++) {
+      const offset = 1 + i * 2;
+      const original = parseInt(hex.slice(offset, offset + 2), 16);
+      const recovered = parseInt(back.slice(offset, offset + 2), 16);
+      expect(Math.abs(original - recovered)).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it('returns #000000 for invalid input', () => {
+    expect(oklchToHex('not-a-color')).toBe('#000000');
+    expect(oklchToHex('')).toBe('#000000');
+  });
+
+  it('encodes alpha as 8-digit hex when present', () => {
+    const result = oklchToHex('oklch(1 0 0 / 0.05)');
+    expect(result).toHaveLength(9); // '#rrggbbaa'
+    expect(result).toMatch(/^#[0-9a-f]{8}$/);
+  });
+
+  it('returns 6-digit hex when no alpha', () => {
+    const result = oklchToHex('oklch(0.624 0.082 181.4)');
+    expect(result).toHaveLength(7);
+    expect(result).toMatch(/^#[0-9a-f]{6}$/);
+  });
+});
+
+// ─── parseOklch ──────────────────────────────────────────────────────────────
+
+describe('parseOklch', () => {
+  it('parses a standard oklch string', () => {
+    const result = parseOklch('oklch(0.624 0.082 181.4)');
+    expect(result).not.toBeNull();
+    expect(result![0]).toBeCloseTo(0.624, 3);
+    expect(result![1]).toBeCloseTo(0.082, 3);
+    expect(result![2]).toBeCloseTo(181.4, 1);
+    expect(result![3]).toBeUndefined();
+  });
+
+  it('parses oklch with alpha channel', () => {
+    const result = parseOklch('oklch(1 0 0 / 0.05)');
+    expect(result).not.toBeNull();
+    expect(result![0]).toBeCloseTo(1, 3);
+    expect(result![1]).toBeCloseTo(0, 3);
+    expect(result![3]).toBeCloseTo(0.05, 3);
+  });
+
+  it('returns null for hex strings', () => {
+    expect(parseOklch('#2a9d8f')).toBeNull();
+  });
+
+  it('returns null for rgb strings', () => {
+    expect(parseOklch('rgb(42, 157, 143)')).toBeNull();
+  });
+
+  it('returns null for empty string', () => {
+    expect(parseOklch('')).toBeNull();
+  });
+
+  it('returns null for malformed oklch', () => {
+    expect(parseOklch('oklch(0.5 0.1)')).toBeNull(); // missing H
+  });
+});
+
+// ─── formatOklch ─────────────────────────────────────────────────────────────
+
+describe('formatOklch', () => {
+  it('formats without alpha for opaque colors', () => {
+    expect(formatOklch(0.624, 0.082, 181.4)).toBe('oklch(0.6240 0.0820 181.4)');
+  });
+
+  it('includes alpha when alpha < 1', () => {
+    const result = formatOklch(1, 0, 0, 0.05);
+    expect(result).toContain(' / 0.05');
+  });
+
+  it('omits alpha when alpha is 1', () => {
+    const result = formatOklch(0.5, 0.1, 180, 1);
+    expect(result).not.toContain(' / ');
+  });
+
+  it('produces valid parseable output', () => {
+    const formatted = formatOklch(0.5, 0.15, 270, 0.5);
+    expect(parseOklch(formatted)).not.toBeNull();
+  });
+});
+
+// ─── rgbaToOklch ─────────────────────────────────────────────────────────────
+
+describe('rgbaToOklch', () => {
+  it('converts rgba string preserving alpha', () => {
+    const result = rgbaToOklch('rgba(255, 255, 255, 0.05)');
+    expect(result).toMatch(/^oklch\(/);
+    const parsed = parseOklch(result);
+    expect(parsed![3]).toBeCloseTo(0.05, 2);
+  });
+
+  it('converts rgb string without alpha', () => {
+    const result = rgbaToOklch('rgb(42, 157, 143)');
+    expect(result).toMatch(/^oklch\(/);
+    expect(result).not.toContain(' / ');
+  });
+
+  it('returns white fallback for unparseable input', () => {
+    expect(rgbaToOklch('not-a-color')).toBe('oklch(1 0 0)');
+  });
+});
+
+// ─── withAlpha ───────────────────────────────────────────────────────────────
+
+describe('withAlpha', () => {
+  it('adds alpha to an opaque color', () => {
+    const result = withAlpha('oklch(0.624 0.082 181.4)', 0.13);
+    expect(parseOklch(result)![3]).toBeCloseTo(0.13, 3);
+  });
+
+  it('replaces existing alpha', () => {
+    const result = withAlpha('oklch(0.624 0.082 181.4 / 0.5)', 0.13);
+    expect(parseOklch(result)![3]).toBeCloseTo(0.13, 3);
+  });
+
+  it('preserves L, C, H components', () => {
+    const result = withAlpha('oklch(0.624 0.082 181.4)', 0.5);
+    const parsed = parseOklch(result)!;
+    expect(parsed[0]).toBeCloseTo(0.624, 3);
+    expect(parsed[1]).toBeCloseTo(0.082, 3);
+    expect(parsed[2]).toBeCloseTo(181.4, 1);
+  });
+});
+
+// ─── adjustL ─────────────────────────────────────────────────────────────────
+
+describe('adjustL', () => {
+  it('increases lightness by delta', () => {
+    const result = adjustL('oklch(0.5 0.1 180)', 0.1);
+    expect(parseOklch(result)![0]).toBeCloseTo(0.6, 3);
+  });
+
+  it('decreases lightness by negative delta', () => {
+    const result = adjustL('oklch(0.5 0.1 180)', -0.1);
+    expect(parseOklch(result)![0]).toBeCloseTo(0.4, 3);
+  });
+
+  it('clamps lightness to 1 at the top', () => {
+    const result = adjustL('oklch(0.95 0.1 180)', 0.2);
+    expect(parseOklch(result)![0]).toBeLessThanOrEqual(1);
+    expect(parseOklch(result)![0]).toBeGreaterThanOrEqual(0);
+  });
+
+  it('clamps lightness to 0 at the bottom', () => {
+    const result = adjustL('oklch(0.05 0.1 180)', -0.2);
+    expect(parseOklch(result)![0]).toBeGreaterThanOrEqual(0);
+  });
+
+  it('preserves C and H components', () => {
+    const result = adjustL('oklch(0.5 0.12 200)', 0.1);
+    const parsed = parseOklch(result)!;
+    expect(parsed[1]).toBeCloseTo(0.12, 3);
+    expect(parsed[2]).toBeCloseTo(200, 1);
+  });
+});
+
+// ─── rotateH ─────────────────────────────────────────────────────────────────
+
+describe('rotateH', () => {
+  it('rotates hue forward by given degrees', () => {
+    const result = rotateH('oklch(0.624 0.082 181.4)', 150);
+    expect(parseOklch(result)![2]).toBeCloseTo(331.4, 1);
+  });
+
+  it('wraps hue forward past 360', () => {
+    const result = rotateH('oklch(0.624 0.082 350)', 30);
+    expect(parseOklch(result)![2]).toBeCloseTo(20, 1);
+  });
+
+  it('handles negative rotation (counter-clockwise)', () => {
+    const result = rotateH('oklch(0.624 0.082 10)', -30);
+    expect(parseOklch(result)![2]).toBeCloseTo(340, 1);
+  });
+
+  it('split-complementary rotation is 150 degrees', () => {
+    // Accent is derived from primary hue + 150 in deriveFullPalette
+    const primary = 'oklch(0.624 0.082 181.4)';
+    const accent = rotateH(primary, 150);
+    const diff = Math.abs(parseOklch(accent)![2] - parseOklch(primary)![2]);
+    expect(Math.min(diff, 360 - diff)).toBeCloseTo(150, 0);
+  });
+});

package/tests/resolve.test.ts

@@ -0,0 +1,192 @@
+/**
+ * @module tests/resolve
+ * @description Unit tests for the 4-level theme cascade resolver.
+ *
+ * Validates cascade priority (catalog → kit → custom → user), short-circuit
+ * behavior of userThemeId, ThemeSeed derivation, and override merging.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { resolveTheme } from '../src/resolve.js';
+import { CATALOG_BY_ID } from '../src/catalog.js';
+
+const COLOR_KEYS = [
+  'bgBase', 'bgSurface', 'bgElevated',
+  'textPrimary', 'textSecondary',
+  'primary', 'primaryLight', 'primaryDark',
+  'accent', 'accentLight',
+  'glass', 'glassBorder',
+  'success', 'warning', 'error',
+] as const;
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+describe('resolveTheme — defaults', () => {
+  it('defaults to soulcraft-dark with an empty input', () => {
+    const theme = resolveTheme({});
+    expect(theme.meta.id).toBe('soulcraft-dark');
+  });
+
+  it('returns a complete ThemeDefinition with all 15 color properties', () => {
+    const theme = resolveTheme({});
+    for (const key of COLOR_KEYS) {
+      expect(theme.colors[key], `missing: ${key}`).toBeTruthy();
+    }
+  });
+
+  it('returns a theme with font properties', () => {
+    const theme = resolveTheme({});
+    expect(theme.fonts.displayFont).toBeTruthy();
+    expect(theme.fonts.bodyFont).toBeTruthy();
+  });
+});
+
+// ─── Layer 1: Catalog theme ───────────────────────────────────────────────────
+
+describe('resolveTheme — catalogId (layer 1)', () => {
+  it('resolves a named catalog theme', () => {
+    const theme = resolveTheme({ catalogId: 'tokyo-night' });
+    expect(theme.meta.id).toBe('tokyo-night');
+  });
+
+  it('returns colors matching the catalog entry', () => {
+    const theme = resolveTheme({ catalogId: 'tokyo-night' });
+    const catalog = CATALOG_BY_ID.get('tokyo-night')!;
+    expect(theme.colors.primary).toBe(catalog.colors.primary);
+    expect(theme.colors.bgBase).toBe(catalog.colors.bgBase);
+  });
+
+  it('resolves any catalogId and still returns all 15 color properties', () => {
+    // The resolver uses the catalogId as-is; unknown IDs fall back in catalog lookup
+    const theme = resolveTheme({ catalogId: 'tokyo-night' });
+    for (const key of COLOR_KEYS) {
+      expect(theme.colors[key]).toBeTruthy();
+    }
+  });
+});
+
+// ─── Layer 2: Kit seed ────────────────────────────────────────────────────────
+
+describe('resolveTheme — kitSeed (layer 2)', () => {
+  it('overrides primary from the kit seed', () => {
+    const kitPrimary = 'oklch(0.72 0.15 25)';
+    const theme = resolveTheme({
+      catalogId: 'soulcraft-dark',
+      kitSeed: { primary: kitPrimary, bgBase: 'oklch(0.05 0.02 261)' },
+    });
+    expect(theme.colors.primary).toBe(kitPrimary);
+  });
+
+  it('overrides bgBase from the kit seed', () => {
+    const kitBgBase = 'oklch(0.96 0.02 80)';
+    const theme = resolveTheme({
+      kitSeed: { primary: 'oklch(0.72 0.15 25)', bgBase: kitBgBase },
+    });
+    expect(theme.colors.bgBase).toBe(kitBgBase);
+  });
+
+  it('derives remaining colors from the seed (all 15 present)', () => {
+    const theme = resolveTheme({
+      kitSeed: { primary: 'oklch(0.72 0.15 25)', bgBase: 'oklch(0.96 0.02 80)' },
+    });
+    for (const key of COLOR_KEYS) {
+      expect(theme.colors[key], `kit-derived theme missing: ${key}`).toBeTruthy();
+    }
+  });
+
+  it('uses explicit seed accent instead of deriving it', () => {
+    const explicitAccent = 'oklch(0.80 0.12 75)';
+    const theme = resolveTheme({
+      kitSeed: {
+        primary: 'oklch(0.72 0.15 25)',
+        bgBase: 'oklch(0.96 0.02 80)',
+        accent: explicitAccent,
+      },
+    });
+    expect(theme.colors.accent).toBe(explicitAccent);
+  });
+});
+
+// ─── Layer 3: Custom overrides ────────────────────────────────────────────────
+
+describe('resolveTheme — customOverrides (layer 3)', () => {
+  it('overrides a specific color on top of catalog theme', () => {
+    const customPrimary = 'oklch(0.80 0.20 120)';
+    const theme = resolveTheme({
+      catalogId: 'soulcraft-dark',
+      customOverrides: { primary: customPrimary },
+    });
+    expect(theme.colors.primary).toBe(customPrimary);
+  });
+
+  it('overrides font settings', () => {
+    const theme = resolveTheme({
+      catalogId: 'soulcraft-dark',
+      customOverrides: { displayFont: 'Fraunces', bodyFont: 'Inter' },
+    });
+    expect(theme.fonts.displayFont).toBe('Fraunces');
+    expect(theme.fonts.bodyFont).toBe('Inter');
+  });
+
+  it('does not affect other colors beyond the override', () => {
+    const base = CATALOG_BY_ID.get('soulcraft-dark')!;
+    const theme = resolveTheme({
+      catalogId: 'soulcraft-dark',
+      customOverrides: { primary: 'oklch(0.80 0.20 120)' },
+    });
+    // bgBase should be unchanged from catalog
+    expect(theme.colors.bgBase).toBe(base.colors.bgBase);
+  });
+
+  it('overrides win over kit seed colors', () => {
+    const seedPrimary = 'oklch(0.72 0.15 25)';
+    const overridePrimary = 'oklch(0.80 0.20 120)';
+    const theme = resolveTheme({
+      kitSeed: { primary: seedPrimary, bgBase: 'oklch(0.05 0.02 261)' },
+      customOverrides: { primary: overridePrimary },
+    });
+    expect(theme.colors.primary).toBe(overridePrimary);
+  });
+});
+
+// ─── Layer 4: User preference ─────────────────────────────────────────────────
+
+describe('resolveTheme — userThemeId (layer 4, short-circuit)', () => {
+  it('user preference overrides a kit seed', () => {
+    const theme = resolveTheme({
+      catalogId: 'soulcraft-dark',
+      kitSeed: { primary: 'oklch(0.72 0.15 25)', bgBase: 'oklch(0.96 0.02 80)' },
+      userThemeId: 'nord',
+    });
+    expect(theme.meta.id).toBe('nord');
+  });
+
+  it('user preference overrides custom overrides', () => {
+    const theme = resolveTheme({
+      catalogId: 'soulcraft-dark',
+      customOverrides: { primary: 'oklch(0.80 0.20 120)' },
+      userThemeId: 'dracula',
+    });
+    expect(theme.meta.id).toBe('dracula');
+    const dracula = CATALOG_BY_ID.get('dracula')!;
+    expect(theme.colors.primary).toBe(dracula.colors.primary);
+  });
+
+  it('user preference returns the full catalog theme unchanged', () => {
+    const theme = resolveTheme({
+      catalogId: 'soulcraft-dark',
+      userThemeId: 'monokai',
+    });
+    const monokai = CATALOG_BY_ID.get('monokai')!;
+    expect(theme.colors.bgBase).toBe(monokai.colors.bgBase);
+    expect(theme.meta.name).toBe(monokai.meta.name);
+  });
+
+  it('invalid userThemeId falls through to the rest of the cascade', () => {
+    const theme = resolveTheme({
+      catalogId: 'tokyo-night',
+      userThemeId: 'this-theme-does-not-exist',
+    });
+    expect(theme.meta.id).toBe('tokyo-night');
+  });
+});

package/tsconfig.base.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "customConditions": ["svelte"],
+    "noEmit": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  }
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.base.json",
+  "include": ["src/**/*.ts", "src/**/*.svelte.ts", "src/**/*.svelte.d.ts", "tests/**/*.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+/**
+ * @module vitest.config
+ * @description Vitest configuration for @soulcraft/theme unit tests.
+ * Tests cover oklch conversion accuracy, catalog completeness, cascade resolution,
+ * and CSS output correctness.
+ */
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    environment: 'node'
+  }
+});