@caelo-cms/shared 0.10.21 → 0.10.23

package/dist/theme-ramp.js

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * v0.11.1 (issue #76) — OKLCh primary-color ramp generator.
+ *
+ * Given a seed color, derive a 10-stop ramp (`50`,`100`,…,`900`) by
+ * walking lightness linearly outward from the seed while preserving its
+ * chroma + hue. Anchored so the `500` stop equals the seed.
+ *
+ * Returns a DTCG group ready to merge at `color.primary`: each stop is
+ * a token leaf carrying `$value: "oklch(L C H)"` + `$type: "color"` +
+ * `_derived: true` annotation, plus a DTCG alias token at `DEFAULT`
+ * pointing at `{color.primary.500}` so existing `--color-primary`
+ * references continue to resolve via the v0.11.0 alias resolver.
+ *
+ * Simplest-possible math (Material 3 inspiration, OKLCh execution); the
+ * issue explicitly calls out HCT as future-tuning, not current scope.
+ */
+import Color from "colorjs.io";
+/**
+ * v0.11.1 — failure surface for the OKLCh ramp generator. Carries the
+ * supported color input formats so the AI's next turn can fix the
+ * input without round-tripping (CLAUDE.md §11 AI-actionable errors).
+ */
+export class InvalidSeedColor extends Error {
+    kind = "InvalidSeedColor";
+    input;
+    supportedFormats;
+    constructor(input) {
+        const formats = [
+            "#rrggbb",
+            "#rgb",
+            "oklch(L C H)",
+            "rgb(r g b)",
+            "hsl(h s% l%)",
+            "lab(L a b)",
+            "lch(L C H)",
+        ];
+        super(`seed color '${input}' is not a recognised CSS color — pass one of: ${formats.join(", ")}.`);
+        this.name = "InvalidSeedColor";
+        this.input = input;
+        this.supportedFormats = formats;
+    }
+}
+/**
+ * Linearly-spaced lightness values for the 10 stops. The `500` slot is
+ * intentionally a placeholder — the seed's measured lightness replaces
+ * it at runtime so the brand color shows up unmodified at its anchor.
+ *
+ * Curve picked to match Tailwind's perceptual feel: light tints at
+ * 50/100 stay near-white, deep shades at 800/900 stay near-black.
+ */
+const RAMP_KEYS = ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900"];
+const RAMP_LIGHTNESS = [0.97, 0.94, 0.87, 0.78, 0.67, 0.55, 0.45, 0.35, 0.25, 0.18];
+const SEED_INDEX = RAMP_KEYS.indexOf("500");
+/**
+ * Derive a 10-stop OKLCh primary-color ramp from a seed color.
+ *
+ * @param seedColor — any CSS color string. The seed's chroma + hue are
+ *                    preserved; lightness shifts to each ramp stop.
+ * @returns A DTCG group ready to write at `color.primary`.
+ * @throws InvalidSeedColor when the input doesn't parse as a CSS color.
+ */
+export function deriveOklchPrimaryRamp(seedColor) {
+    if (typeof seedColor !== "string" || seedColor.trim().length === 0) {
+        throw new InvalidSeedColor(String(seedColor));
+    }
+    let seed;
+    try {
+        seed = new Color(seedColor);
+    }
+    catch (_e) {
+        throw new InvalidSeedColor(seedColor);
+    }
+    // Convert to OKLCh; the conversion is lossless within colorjs.io's
+    // gamut model (clamps to displayable sRGB on output).
+    const oklch = seed.to("oklch");
+    const coords = oklch.coords; // [L, C, H]
+    const seedL = coords[0];
+    const chroma = Number.isFinite(coords[1]) ? coords[1] : 0;
+    // Achromatic colors (#888, white, black) have NaN hue — preserve 0
+    // so the OKLCh string parses; chroma is 0 anyway.
+    const hue = Number.isFinite(coords[2]) ? coords[2] : 0;
+    const tokens = {};
+    const derivedPaths = [];
+    for (let i = 0; i < RAMP_KEYS.length; i += 1) {
+        const key = RAMP_KEYS[i];
+        // Anchor the seed's lightness at the 500 stop; the rest follow the
+        // pre-computed curve. Clamp to [0.001, 0.999] so OKLCh emits a
+        // valid color (pure black/white can clip chroma in edge cases).
+        const rawL = i === SEED_INDEX ? seedL : RAMP_LIGHTNESS[i];
+        const L = Math.max(0.001, Math.min(0.999, rawL));
+        const value = formatOklch(L, chroma, hue);
+        tokens[key] = { $value: value, $type: "color", _derived: true };
+        derivedPaths.push(`color.primary.${key}`);
+    }
+    // DTCG alias so callers / CSS-vars that reference `color.primary`
+    // continue to resolve to the 500 stop. The renderer's alias resolver
+    // (v0.11.0) handles the indirection; no renderer changes needed.
+    tokens.DEFAULT = {
+        $value: "{color.primary.500}",
+        $type: "color",
+        _derived: true,
+    };
+    derivedPaths.push("color.primary.DEFAULT");
+    return { tokens, derivedPaths };
+}
+/**
+ * Merge a ramp result into a tokens document at `color.primary`,
+ * preserving any operator-supplied explicit stops in `overrides`
+ * (`{"color.primary.500": "#ff0000"}` keeps the explicit stop AND the
+ * derived ramp around it — explicit-wins precedence per Risk §6.2).
+ *
+ * Returns a fresh document; input is not mutated.
+ */
+export function mergeRampIntoTokens(baseTokens, ramp, explicitOverrides) {
+    const out = JSON.parse(JSON.stringify(baseTokens));
+    const colorGroup = out.color;
+    const nextColor = { ...(colorGroup ?? {}) };
+    // REPLACE the previous color.primary entry with the derived ramp
+    // group. The replacement is total — a leaf `{"$value": "…"}` becomes
+    // a group `{50: {…}, 100: {…}, …, DEFAULT: {…}}`. Other color tokens
+    // (foreground, secondary, etc.) are untouched.
+    nextColor.primary = { ...ramp.tokens };
+    out.color = nextColor;
+    // Layer explicit operator-supplied `color.primary.<stop>` overrides
+    // on top of the derived ramp. Only `color.primary.*` paths matter
+    // here; other overrides flow through the existing applyDtcgWrites
+    // call upstream.
+    for (const [path, value] of Object.entries(explicitOverrides)) {
+        if (!path.startsWith("color.primary."))
+            continue;
+        const stopKey = path.slice("color.primary.".length);
+        if (!stopKey || stopKey.includes("."))
+            continue;
+        const primary = out.color.primary;
+        primary[stopKey] = {
+            $value: value,
+            $type: "color",
+        };
+    }
+    return out;
+}
+function formatOklch(L, C, H) {
+    // Three decimal places — enough for visual fidelity (OKLCh's perceptual
+    // step is ~0.005L), small enough for cache-friendly stable bytes.
+    const fmt = (n) => n.toFixed(3).replace(/\.?0+$/, "") || "0";
+    return `oklch(${fmt(L)} ${fmt(C)} ${fmt(H)})`;
+}
+//# sourceMappingURL=theme-ramp.js.map

package/dist/theme-ramp.js.map

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

package/dist/theme-render.d.ts

@@ -0,0 +1,105 @@
+/**
+ * v0.11.0 — DTCG-aligned theme renderer (#45 Phase 3).
+ *
+ * Walks a `ThemeDocument` (DTCG tokens jsonb) and emits CSS custom
+ * properties under the Tailwind 4 namespace convention so module CSS
+ * can `var(--color-primary)` / `var(--spacing-lg)` etc. without
+ * mental-translation from DTCG paths.
+ *
+ * Namespace mapping (matches Tailwind 4's `@theme { … }` directive):
+ *
+ *   color.X             → --color-X
+ *   typography.X        → --font-X (fontFamily) + --text-X (fontSize)
+ *                         + --font-weight-X + --leading-X + --tracking-X
+ *   spacing.X           → --spacing-X
+ *   radius.X            → --radius-X
+ *   shadow.X            → --shadow-X (expanded to `<x> <y> <blur> [spread] <color> [inset]`)
+ *   breakpoint.X        → --breakpoint-X
+ *   duration.X          → --duration-X
+ *   ease.X              → --ease-X (cubic-bezier expansion)
+ *
+ * Color tokens carrying `{ light, dark }` emit the light value inside
+ * `:root { … }` AND the dark value inside `:root.dark { … }` so a
+ * single declaration drives both surfaces.
+ *
+ * DTCG aliases (`"{group.token}"`) are resolved before emission.
+ * Cyclic aliases produce a structured error rather than infinite-
+ * looping. Pure function — no IO, dependency-free, testable in unit
+ * isolation.
+ */
+import { type ThemeDocument } from "./themes.js";
+/** Renderer-level error for cyclic / unresolved aliases. */
+export declare class ThemeRenderError extends Error {
+    readonly kind: "cyclic-alias" | "missing-alias";
+    readonly path: string;
+    constructor(kind: "cyclic-alias" | "missing-alias", path: string, message: string);
+}
+/**
+ * Optional render options. The `selector` parameter (v0.11.1, issue #76)
+ * scopes the emitted CSS variables under a custom selector so the admin
+ * live-preview pane can render the byte-identical CSS without leaking
+ * the theme's tokens onto the surrounding admin chrome. Default `:root`
+ * keeps the static-gen + chat-runner paths unchanged.
+ */
+export interface RenderThemeCssOptions {
+    /**
+     * Selector to wrap the emitted rule blocks. Defaults to `:root`. The
+     * dark-variant block becomes `${selector}.dark` so a single `.dark`
+     * class toggle on the scoping element flips both surfaces — same
+     * behaviour as the public site's `:root` / `:root.dark` pairing.
+     */
+    readonly selector?: string;
+}
+/**
+ * Emit the `:root { … }` (+ optional `:root.dark { … }`) CSS for the
+ * supplied tokens document. Returns the bare CSS body — caller wraps
+ * it in `<style data-source="theme">…</style>` and injects it ahead of
+ * module CSS in the document head.
+ *
+ * Pass `options.selector` (v0.11.1) to scope the rule blocks under a
+ * custom selector instead of `:root`. The admin live preview uses
+ * `.theme-preview` so the operator's edits don't leak onto the admin
+ * UI. Public + chat paths omit the option and get the default.
+ */
+export declare function renderThemeCss(tokens: ThemeDocument, options?: RenderThemeCssOptions): string;
+/**
+ * Named export of the `:root { … }` CSS-vars form. Alias for
+ * `renderThemeCss(tokens)` — exists so the AI tool's `as: "css-vars"`
+ * dispatch table reads symmetrically with the other format names.
+ */
+export declare function formatThemeAsCssVars(tokens: ThemeDocument): string;
+/**
+ * v0.11.4 (issue #76 follow-up) — return JUST the CSS variable names
+ * the renderer would emit for this token document. The AI uses this in
+ * the system-prompt `## Theme` block so it knows exactly which
+ * `var(--…)` names exist before authoring module CSS.
+ *
+ * Without this surface the AI guesses var names (e.g. `--color-text`,
+ * `--color-surface`) that look reasonable but don't exist in the
+ * shadcn-style theme — its CSS then falls through to hardcoded
+ * fallbacks and the page renders monochrome regardless of token values.
+ *
+ * Returns a sorted, de-duplicated array. Emits the same names as the
+ * `renderThemeCss` light branch (the dark variant uses the same names
+ * with different values, so listing them once is correct).
+ */
+export declare function listThemeCssVarNames(tokens: ThemeDocument): readonly string[];
+/**
+ * Emit a Tailwind 4 `@theme inline { … }` block. The body re-uses the
+ * same per-category emission as `renderThemeCss` so the variable names
+ * match what `app.css` exposes — feeding this output into the Tailwind
+ * importer round-trips to the same DTCG document.
+ */
+export declare function formatThemeAsTailwind(tokens: ThemeDocument): string;
+/**
+ * Emit a terse one-line summary of the tokens document — primary color
+ * shorthand, body font, default radius, and category counts. Used by
+ * the system-prompt `## Theme` block so the AI sees the theme's feel
+ * without spending tokens on the full DTCG document.
+ *
+ * Format: `primary=<hex|oklch>, body=<fontFamily-first-name>, radius=<value>, <category counts>`.
+ * Falls back to category counts only when the canonical paths aren't
+ * populated (e.g. an empty or unusual theme).
+ */
+export declare function formatThemeSummary(tokens: ThemeDocument): string;
+//# sourceMappingURL=theme-render.d.ts.map

package/dist/theme-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-render.d.ts","sourceRoot":"","sources":["../src/theme-render.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAqC,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEpF,4DAA4D;AAC5D,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,eAAe,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,cAAc,GAAG,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMlF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAgBjG;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAElE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,CAmB7E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAgBnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CA8ChE"}