@soulcraft/theme 1.0.0

package/tests/catalog.test.ts

@@ -0,0 +1,199 @@
+/**
+ * @module tests/catalog
+ * @description Unit tests for the @soulcraft/theme theme catalog.
+ *
+ * Validates that all 23 predefined themes are present, structurally complete
+ * (all 15 color properties + fonts + meta), and use valid OKLCH color strings.
+ * Also tests catalog lookup, category filtering, and grouped access.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  THEME_CATALOG,
+  CATALOG_BY_ID,
+  getThemesByCategory,
+  getThemesGrouped,
+} from '../src/catalog.js';
+import { parseOklch } from '../src/oklch.js';
+import type { ThemeName } from '../src/types.js';
+
+// All 23 theme IDs expected in the catalog
+const ALL_THEME_IDS: ThemeName[] = [
+  'soulcraft-dark',
+  'soulcraft-light',
+  'tokyo-night',
+  'catppuccin-mocha',
+  'gruvbox-dark',
+  'material-theme-darker',
+  'material-theme-palenight',
+  'ayu-dark',
+  'synthwave-84',
+  'one-dark-pro',
+  'dracula',
+  'nord',
+  'monokai',
+  'night-owl',
+  'solarized-dark',
+  'github-dark',
+  'github-dark-dimmed',
+  'catppuccin-latte',
+  'gruvbox-light',
+  'solarized-light',
+  'github-light',
+  'one-light',
+  'material-theme-lighter',
+];
+
+const COLOR_KEYS = [
+  'bgBase', 'bgSurface', 'bgElevated',
+  'textPrimary', 'textSecondary',
+  'primary', 'primaryLight', 'primaryDark',
+  'accent', 'accentLight',
+  'glass', 'glassBorder',
+  'success', 'warning', 'error',
+] as const;
+
+// ─── THEME_CATALOG ────────────────────────────────────────────────────────────
+
+describe('THEME_CATALOG', () => {
+  it('contains exactly 23 themes', () => {
+    expect(THEME_CATALOG).toHaveLength(23);
+  });
+
+  it('contains all expected theme IDs', () => {
+    const catalogIds = new Set(THEME_CATALOG.map(t => t.meta.id));
+    for (const id of ALL_THEME_IDS) {
+      expect(catalogIds.has(id), `missing theme: ${id}`).toBe(true);
+    }
+  });
+
+  it('every theme has all 15 color properties as valid OKLCH', () => {
+    for (const theme of THEME_CATALOG) {
+      for (const key of COLOR_KEYS) {
+        const value = theme.colors[key];
+        expect(value, `${theme.meta.id}.colors.${key} is missing`).toBeTruthy();
+        expect(
+          parseOklch(value),
+          `${theme.meta.id}.colors.${key} is not valid OKLCH: "${value}"`
+        ).not.toBeNull();
+      }
+    }
+  });
+
+  it('every theme has non-empty font properties', () => {
+    for (const theme of THEME_CATALOG) {
+      expect(theme.fonts.displayFont, `${theme.meta.id} missing displayFont`).toBeTruthy();
+      expect(theme.fonts.bodyFont, `${theme.meta.id} missing bodyFont`).toBeTruthy();
+    }
+  });
+
+  it('every theme has complete metadata', () => {
+    for (const theme of THEME_CATALOG) {
+      expect(theme.meta.id).toBeTruthy();
+      expect(theme.meta.name).toBeTruthy();
+      expect(['soulcraft', 'dark', 'light']).toContain(theme.meta.category);
+      expect(typeof theme.meta.isDark).toBe('boolean');
+    }
+  });
+
+  it('soulcraft themes are marked isDark correctly', () => {
+    const dark = THEME_CATALOG.find(t => t.meta.id === 'soulcraft-dark')!;
+    const light = THEME_CATALOG.find(t => t.meta.id === 'soulcraft-light')!;
+    expect(dark.meta.isDark).toBe(true);
+    expect(light.meta.isDark).toBe(false);
+  });
+
+  it('all theme IDs are unique', () => {
+    const ids = THEME_CATALOG.map(t => t.meta.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+});
+
+// ─── CATALOG_BY_ID ───────────────────────────────────────────────────────────
+
+describe('CATALOG_BY_ID', () => {
+  it('has 23 entries', () => {
+    expect(CATALOG_BY_ID.size).toBe(23);
+  });
+
+  it('retrieves soulcraft-dark by ID', () => {
+    const theme = CATALOG_BY_ID.get('soulcraft-dark');
+    expect(theme).toBeDefined();
+    expect(theme!.meta.id).toBe('soulcraft-dark');
+    expect(theme!.meta.isDark).toBe(true);
+    expect(theme!.meta.category).toBe('soulcraft');
+  });
+
+  it('retrieves catppuccin-latte (light theme) by ID', () => {
+    const theme = CATALOG_BY_ID.get('catppuccin-latte');
+    expect(theme).toBeDefined();
+    expect(theme!.meta.isDark).toBe(false);
+    expect(theme!.meta.category).toBe('light');
+  });
+
+  it('retrieves nord by ID and verifies it has colors', () => {
+    const theme = CATALOG_BY_ID.get('nord');
+    expect(theme).toBeDefined();
+    expect(parseOklch(theme!.colors.primary)).not.toBeNull();
+  });
+
+  it('returns undefined for an unknown ID', () => {
+    expect(CATALOG_BY_ID.get('nonexistent-theme')).toBeUndefined();
+    expect(CATALOG_BY_ID.get('')).toBeUndefined();
+  });
+
+  it('all 23 IDs are retrievable', () => {
+    for (const id of ALL_THEME_IDS) {
+      expect(CATALOG_BY_ID.get(id), `${id} not found in CATALOG_BY_ID`).toBeDefined();
+    }
+  });
+});
+
+// ─── getThemesByCategory ──────────────────────────────────────────────────────
+
+describe('getThemesByCategory', () => {
+  it('returns only soulcraft themes for "soulcraft"', () => {
+    const themes = getThemesByCategory('soulcraft');
+    expect(themes.length).toBeGreaterThan(0);
+    expect(themes.every(t => t.meta.category === 'soulcraft')).toBe(true);
+  });
+
+  it('returns only dark themes for "dark"', () => {
+    const themes = getThemesByCategory('dark');
+    expect(themes.length).toBeGreaterThan(0);
+    expect(themes.every(t => t.meta.category === 'dark')).toBe(true);
+  });
+
+  it('returns only light themes for "light"', () => {
+    const themes = getThemesByCategory('light');
+    expect(themes.length).toBeGreaterThan(0);
+    expect(themes.every(t => t.meta.category === 'light')).toBe(true);
+  });
+
+  it('soulcraft has exactly 2 themes', () => {
+    expect(getThemesByCategory('soulcraft')).toHaveLength(2);
+  });
+});
+
+// ─── getThemesGrouped ─────────────────────────────────────────────────────────
+
+describe('getThemesGrouped', () => {
+  it('returns all three group keys', () => {
+    const grouped = getThemesGrouped();
+    expect(grouped).toHaveProperty('soulcraft');
+    expect(grouped).toHaveProperty('dark');
+    expect(grouped).toHaveProperty('light');
+  });
+
+  it('group totals sum to 23 themes', () => {
+    const grouped = getThemesGrouped();
+    const total = grouped.soulcraft.length + grouped.dark.length + grouped.light.length;
+    expect(total).toBe(23);
+  });
+
+  it('groups match getThemesByCategory results', () => {
+    const grouped = getThemesGrouped();
+    const byCategory = getThemesByCategory('dark');
+    expect(grouped.dark.map(t => t.meta.id)).toEqual(byCategory.map(t => t.meta.id));
+  });
+});

package/tests/css.test.ts

@@ -0,0 +1,250 @@
+/**
+ * @module tests/css
+ * @description Unit tests for the CSS custom property builder functions.
+ *
+ * Validates that buildThemeCss() produces all 17 required CSS vars, that the
+ * static alias builders contain the expected Workshop/Venue variable names,
+ * and that buildFontUrl() produces valid Google Fonts URLs.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  buildThemeCss,
+  buildWorkshopAliasCss,
+  buildBrandAliasCss,
+  buildWorkshopDerivedCss,
+  buildFontUrl,
+  buildExportStyles,
+} from '../src/css.js';
+import { CATALOG_BY_ID } from '../src/catalog.js';
+import type { ThemeDefinition } from '../src/types.js';
+
+const soulcraftDark = CATALOG_BY_ID.get('soulcraft-dark')!;
+
+// ─── buildThemeCss ────────────────────────────────────────────────────────────
+
+describe('buildThemeCss', () => {
+  const EXPECTED_VARS = [
+    '--theme-bg-base',
+    '--theme-bg-surface',
+    '--theme-bg-elevated',
+    '--theme-text-primary',
+    '--theme-text-secondary',
+    '--theme-primary',
+    '--theme-primary-light',
+    '--theme-primary-dark',
+    '--theme-accent',
+    '--theme-accent-light',
+    '--theme-glass',
+    '--theme-glass-border',
+    '--theme-success',
+    '--theme-warning',
+    '--theme-error',
+    '--theme-font-display',
+    '--theme-font-body',
+  ];
+
+  it('contains all 17 CSS custom properties', () => {
+    const css = buildThemeCss(soulcraftDark);
+    for (const v of EXPECTED_VARS) {
+      expect(css, `missing ${v}`).toContain(v);
+    }
+  });
+
+  it('embeds the theme color values directly', () => {
+    const css = buildThemeCss(soulcraftDark);
+    expect(css).toContain(soulcraftDark.colors.primary);
+    expect(css).toContain(soulcraftDark.colors.bgBase);
+  });
+
+  it('embeds font names', () => {
+    const css = buildThemeCss(soulcraftDark);
+    expect(css).toContain(soulcraftDark.fonts.displayFont);
+    expect(css).toContain(soulcraftDark.fonts.bodyFont);
+  });
+
+  it('splits into exactly 17 semicolon-separated declarations', () => {
+    const css = buildThemeCss(soulcraftDark);
+    const parts = css.split(';').filter(Boolean);
+    expect(parts).toHaveLength(17);
+  });
+
+  it('works for all 23 catalog themes without throwing', () => {
+    for (const theme of CATALOG_BY_ID.values()) {
+      expect(() => buildThemeCss(theme)).not.toThrow();
+      expect(buildThemeCss(theme)).toContain('--theme-primary');
+    }
+  });
+});
+
+// ─── buildWorkshopAliasCss ────────────────────────────────────────────────────
+
+describe('buildWorkshopAliasCss', () => {
+  it('contains Workshop legacy core palette aliases', () => {
+    const css = buildWorkshopAliasCss();
+    const expected = [
+      '--bg-dark', '--bg-medium', '--bg-light',
+      '--text-primary', '--text-secondary',
+      '--primary', '--primary-light', '--primary-dark',
+      '--accent', '--accent-light',
+      '--glass', '--glass-border',
+      '--success', '--warning', '--error',
+    ];
+    for (const v of expected) {
+      expect(css, `missing ${v}`).toContain(v);
+    }
+  });
+
+  it('contains Workshop semantic surface aliases', () => {
+    const css = buildWorkshopAliasCss();
+    expect(css).toContain('--surface-primary');
+    expect(css).toContain('--surface-secondary');
+    expect(css).toContain('--border-subtle');
+    expect(css).toContain('--text-muted');
+  });
+
+  it('maps all aliases to --theme-* vars (not hardcoded values)', () => {
+    const css = buildWorkshopAliasCss();
+    expect(css).toContain('var(--theme-bg-base)');
+    expect(css).toContain('var(--theme-primary)');
+    expect(css).toContain('var(--theme-text-secondary)');
+  });
+
+  it('is a pure static string (no theme argument)', () => {
+    // Calling twice returns identical string
+    expect(buildWorkshopAliasCss()).toBe(buildWorkshopAliasCss());
+  });
+});
+
+// ─── buildBrandAliasCss ───────────────────────────────────────────────────────
+
+describe('buildBrandAliasCss', () => {
+  it('contains all Venue brand variables', () => {
+    const css = buildBrandAliasCss();
+    expect(css).toContain('--brand-primary');
+    expect(css).toContain('--brand-background');
+    expect(css).toContain('--brand-accent');
+    expect(css).toContain('--brand-text');
+    expect(css).toContain('--brand-font-display');
+    expect(css).toContain('--brand-font-body');
+  });
+
+  it('maps to --theme-* vars', () => {
+    const css = buildBrandAliasCss();
+    expect(css).toContain('var(--theme-primary)');
+    expect(css).toContain('var(--theme-bg-base)');
+    expect(css).toContain('var(--theme-text-primary)');
+  });
+
+  it('is a pure static string', () => {
+    expect(buildBrandAliasCss()).toBe(buildBrandAliasCss());
+  });
+});
+
+// ─── buildWorkshopDerivedCss ──────────────────────────────────────────────────
+
+describe('buildWorkshopDerivedCss', () => {
+  it('includes --accent-subtle with alpha', () => {
+    const css = buildWorkshopDerivedCss(soulcraftDark);
+    expect(css).toContain('--accent-subtle');
+    // The derived var should have an alpha modifier
+    expect(css).toContain(' / ');
+  });
+
+  it('includes --success-subtle with alpha', () => {
+    const css = buildWorkshopDerivedCss(soulcraftDark);
+    expect(css).toContain('--success-subtle');
+  });
+
+  it('works for all 23 themes without throwing', () => {
+    for (const theme of CATALOG_BY_ID.values()) {
+      expect(() => buildWorkshopDerivedCss(theme)).not.toThrow();
+    }
+  });
+});
+
+// ─── buildFontUrl ─────────────────────────────────────────────────────────────
+
+describe('buildFontUrl', () => {
+  it('returns null when both fonts are system-ui', () => {
+    const theme: ThemeDefinition = {
+      ...soulcraftDark,
+      fonts: { displayFont: 'system-ui', bodyFont: 'system-ui' },
+    };
+    expect(buildFontUrl(theme)).toBeNull();
+  });
+
+  it('returns a Google Fonts URL for a named display font', () => {
+    const theme: ThemeDefinition = {
+      ...soulcraftDark,
+      fonts: { displayFont: 'Inter', bodyFont: 'system-ui' },
+    };
+    const url = buildFontUrl(theme);
+    expect(url).not.toBeNull();
+    expect(url).toContain('fonts.googleapis.com');
+    expect(url).toContain('Inter');
+  });
+
+  it('includes both fonts in the URL when both are named', () => {
+    const theme: ThemeDefinition = {
+      ...soulcraftDark,
+      fonts: { displayFont: 'Fraunces', bodyFont: 'Inter' },
+    };
+    const url = buildFontUrl(theme);
+    expect(url).not.toBeNull();
+    expect(url).toContain('Fraunces');
+    expect(url).toContain('Inter');
+  });
+
+  it('handles Fraunces with optical-size axes (special case)', () => {
+    const theme: ThemeDefinition = {
+      ...soulcraftDark,
+      fonts: { displayFont: 'Fraunces', bodyFont: 'system-ui' },
+    };
+    const url = buildFontUrl(theme);
+    expect(url).not.toBeNull();
+    // Fraunces needs optical-size axes in the URL
+    expect(url).toContain('Fraunces');
+  });
+
+  it('returns a valid URL format', () => {
+    const theme: ThemeDefinition = {
+      ...soulcraftDark,
+      fonts: { displayFont: 'DM Sans', bodyFont: 'system-ui' },
+    };
+    const url = buildFontUrl(theme);
+    if (url) {
+      expect(() => new URL(url)).not.toThrow();
+    }
+  });
+});
+
+// ─── buildExportStyles ────────────────────────────────────────────────────────
+
+describe('buildExportStyles', () => {
+  it('produces a <style> block', () => {
+    const styles = buildExportStyles(soulcraftDark);
+    expect(styles).toContain('<style>');
+    expect(styles).toContain('</style>');
+  });
+
+  it('includes :root with color variable declarations', () => {
+    const styles = buildExportStyles(soulcraftDark);
+    expect(styles).toContain(':root');
+    // buildExportStyles uses legacy export var names (--primary, --bg, etc.)
+    expect(styles).toContain('--primary');
+    expect(styles).toContain('oklch(');
+  });
+
+  it('includes body styling for immediate visual feedback', () => {
+    const styles = buildExportStyles(soulcraftDark);
+    expect(styles).toContain('body');
+    expect(styles).toContain('background');
+  });
+
+  it('works for all 23 catalog themes without throwing', () => {
+    for (const theme of CATALOG_BY_ID.values()) {
+      expect(() => buildExportStyles(theme)).not.toThrow();
+    }
+  });
+});