@bendyline/squisq 1.3.0 → 1.4.0

package/dist/schemas/themeCompile.js

@@ -0,0 +1,160 @@
+/**
+ * Theme Compilation
+ *
+ * Turns a partial Theme (typically authored by the customizer panel from
+ * a few seed colors and preset choices) into a complete, validated Theme
+ * by:
+ *
+ *   1. Filling unspecified fields from a hardcoded `STARTER_THEME`.
+ *   2. Deriving missing color slots from `seedColors` via OKLCh math.
+ *   3. Validating the result.
+ *
+ * Built-in themes ship as fully-specified Theme JSON and skip this step.
+ */
+import { THEME_SCHEMA_VERSION, createTheme } from './Theme.js';
+import { assertTheme } from './themeValidator.js';
+import { oklchLighten, oklchDarken, oklchSetChroma, pickContrastingText, relativeLuminance, } from './colorUtils.js';
+/** Internal default theme used to fill in fields the customizer doesn't expose. */
+const STARTER_BODY_FONT = { stackId: 'system-sans' };
+const STARTER_TITLE_FONT = { stackId: 'system-serif' };
+const STARTER_MONO_FONT = { stackId: 'system-mono' };
+const STARTER_COLOR_SCHEMES = {
+    blue: { bg: '#1a365d', text: '#63b3ed', accent: '#90cdf4' },
+    green: { bg: '#22543d', text: '#9ae6b4', accent: '#68d391' },
+    purple: { bg: '#44337a', text: '#d6bcfa', accent: '#b794f4' },
+    red: { bg: '#742a2a', text: '#fc8181', accent: '#feb2b2' },
+    orange: { bg: '#744210', text: '#fbd38d', accent: '#f6ad55' },
+    teal: { bg: '#234e52', text: '#81e6d9', accent: '#4fd1c5' },
+};
+export const STARTER_THEME = {
+    schemaVersion: THEME_SCHEMA_VERSION,
+    id: 'custom',
+    name: 'Custom Theme',
+    description: 'Customizer starter — gets overridden by user choices.',
+    colors: {
+        primary: '#3182ce',
+        secondary: '#4a5568',
+        background: '#1a202c',
+        backgroundLight: '#2d3748',
+        text: '#f7fafc',
+        textMuted: '#a0aec0',
+        highlight: '#4299e1',
+        warning: '#fc8181',
+    },
+    typography: {
+        bodyFont: STARTER_BODY_FONT,
+        titleFont: STARTER_TITLE_FONT,
+        monoFont: STARTER_MONO_FONT,
+        titleWeight: 'bold',
+    },
+    style: {
+        textShadow: true,
+        overlayOpacity: 0.45,
+        animationSpeed: 1.0,
+        borderRadius: 6,
+    },
+    renderStyle: {
+        name: 'standard',
+        defaultTextAnimation: 'fadeIn',
+        defaultImageAnimation: 'slowZoom',
+        ambientMotion: true,
+        defaultTransition: { type: 'fade', duration: 0.7 },
+    },
+    colorSchemes: STARTER_COLOR_SCHEMES,
+};
+/**
+ * Derive a full `ThemeColorPalette` from `seedColors`, with any explicit
+ * `partialColors` taking precedence over derived values. Background and
+ * text are guessed from luminance when the user gave only a primary.
+ */
+export function deriveColorPalette(seeds, partialColors = {}, opts = {}) {
+    const spread = opts.contrast === 'high' ? 0.22 : opts.contrast === 'subtle' ? 0.08 : 0.15;
+    const primary = seeds.primary;
+    const secondary = seeds.secondary ?? oklchSetChroma(oklchLighten(primary, 0.05), 0.5);
+    const accent = seeds.accent ?? oklchLighten(primary, spread);
+    // Decide light vs dark surface from the explicit background, the seed background,
+    // or default to dark.
+    const bgSeed = partialColors.background ?? seeds.background;
+    let background;
+    if (bgSeed) {
+        background = bgSeed;
+    }
+    else {
+        // Pick a dark or light background that contrasts with primary
+        background = relativeLuminance(primary) > 0.5 ? '#0a0a0a' : '#1a202c';
+    }
+    const isLightSurface = relativeLuminance(background) > 0.5;
+    const backgroundLight = partialColors.backgroundLight ??
+        (isLightSurface ? oklchDarken(background, 0.04) : oklchLighten(background, 0.04));
+    const text = partialColors.text ?? seeds.text ?? pickContrastingText(background, '#f7fafc', '#1a202c');
+    const textMuted = partialColors.textMuted ??
+        (isLightSurface ? oklchLighten(text, 0.25) : oklchDarken(text, 0.25));
+    const highlight = partialColors.highlight ?? accent;
+    const warning = partialColors.warning ?? '#fc8181';
+    return {
+        primary: partialColors.primary ?? primary,
+        secondary: partialColors.secondary ?? secondary,
+        background,
+        backgroundLight,
+        text,
+        textMuted,
+        highlight,
+        warning,
+    };
+}
+/**
+ * Compile a partial Theme into a complete one. Fills missing fields from
+ * `STARTER_THEME`, derives missing color slots from `seedColors` (when
+ * present), and validates the result.
+ */
+export function compileTheme(partial, opts = {}) {
+    // Step 1: deep-merge over the starter
+    const merged = createTheme(STARTER_THEME, partial);
+    merged.schemaVersion = THEME_SCHEMA_VERSION;
+    // Step 1b: typography fonts are discriminated unions ({stackId} | {custom}),
+    // so deep-merge would leave stale keys from the starter when the partial
+    // switches form. Replace each font wholesale when explicitly provided.
+    const partialTypography = partial.typography;
+    if (partialTypography) {
+        if (partialTypography.titleFont !== undefined) {
+            merged.typography.titleFont = partialTypography.titleFont;
+        }
+        if (partialTypography.bodyFont !== undefined) {
+            merged.typography.bodyFont = partialTypography.bodyFont;
+        }
+        if (partialTypography.monoFont !== undefined) {
+            merged.typography.monoFont = partialTypography.monoFont;
+        }
+    }
+    // Step 2: derive missing color slots from seeds, if present
+    if (merged.seedColors) {
+        const partialColors = (partial.colors ?? {});
+        merged.colors = deriveColorPalette(merged.seedColors, partialColors, {
+            contrast: opts.contrast,
+        });
+    }
+    // Step 3: validate
+    return assertTheme(merged, `compiled theme "${merged.id}"`);
+}
+/**
+ * Parse a JSON string into a validated Theme. Throws on invalid input.
+ */
+export function parseTheme(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid theme JSON: ${msg}`);
+    }
+    return assertTheme(parsed, 'parsed theme');
+}
+/**
+ * Serialize a Theme to a stable, pretty-printed JSON string. Round-trips
+ * cleanly through `parseTheme`.
+ */
+export function serializeTheme(theme) {
+    return JSON.stringify(theme, null, 2);
+}
+//# sourceMappingURL=themeCompile.js.map

package/dist/schemas/themeCompile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"themeCompile.js","sourceRoot":"","sources":["../../src/schemas/themeCompile.ts"],"names":[],"mappings":"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"}

package/dist/schemas/themeLibrary.d.ts

@@ -1,38 +1,34 @@
 /**
  * Built-in Theme Library
  *
- * Ships 8 curated themes covering documentary, editorial, minimal, and
- * cinematic styles. Each theme is fully JSON-serializable.
+ * Public entry point for theme lookup. Built-in themes live as JSON
+ * sidecars in [./themes/](./themes/) — they share the exact same shape
+ * as customizer-authored themes (no two-tier distinction).
  *
  * Usage:
  * ```ts
  * import { THEMES, resolveTheme } from '@bendyline/squisq/schemas';
  *
- * const theme = resolveTheme('minimalist'); // look up by id
- * const theme = THEMES.documentary;         // direct access
+ * const theme = resolveTheme('minimalist'); // by id, with registry override
+ * const theme = THEMES.documentary;         // direct access to a built-in
  * ```
  */
 import type { Theme } from './Theme.js';
-/**
- * All built-in themes, keyed by id.
- */
+/** All built-in themes, keyed by id. */
 export declare const THEMES: Record<string, Theme>;
 /** The default theme id. */
 export declare const DEFAULT_THEME_ID = "standard";
 /** The default theme (standard — safe system fonts, no external dependencies). */
 export declare const DEFAULT_THEME: Theme;
 /**
- * Resolve a theme by id. Returns the default theme when `id` is
- * undefined or not found in the library.
+ * Resolve a theme by id. Custom themes registered via `registerTheme()`
+ * take precedence over built-ins; otherwise built-ins are searched and
+ * the default theme is returned for unknown ids.
  */
 export declare function resolveTheme(id: string | undefined): Theme;
-/**
- * Get all available theme ids.
- */
+/** Get all built-in theme ids. */
 export declare function getAvailableThemes(): string[];
-/**
- * Get a summary of all themes (id + name + description) for theme pickers.
- */
+/** Get a summary of all built-in themes (id + name + description) for theme pickers. */
 export declare function getThemeSummaries(): Array<{
     id: string;
     name: string;

package/dist/schemas/themeLibrary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"themeLibrary.d.ts","sourceRoot":"","sources":["../../src/schemas/themeLibrary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAoB,MAAM,YAAY,CAAC;AA0jB1D;;GAEG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAWxC,CAAC;AAEF,4BAA4B;AAC5B,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAE3C,kFAAkF;AAClF,eAAO,MAAM,aAAa,EAAE,KAAgB,CAAC;AAE7C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,CAG1D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAM7F"}
+{"version":3,"file":"themeLibrary.d.ts","sourceRoot":"","sources":["../../src/schemas/themeLibrary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAIxC,wCAAwC;AACxC,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAkB,CAAC;AAE5D,4BAA4B;AAC5B,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAE3C,kFAAkF;AAClF,eAAO,MAAM,aAAa,EAAE,KAAgC,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,CAK1D;AAED,kCAAkC;AAClC,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,IAAI,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAM7F"}