@spacefast/common 0.0.11 → 0.0.13

package/dist/utils/page-colors.js

@@ -0,0 +1,167 @@
+// Readability engine for Spacefast-authored pages.
+//
+// Theme colors are intent, not CSS: users and agents push any accent or
+// background (dashboard, spacefast.jsonc, API) and the platform guarantees
+// every rendered page stays readable. This module derives the full set of
+// colors the templates actually paint with:
+//
+//   - `onAccent`  — button-label color on accent fills (black or white).
+//   - `link`      — the accent, lightness-adjusted until it meets WCAG AA
+//                   against the surface it sits on. Hue and chroma survive,
+//                   so it still reads as the brand color.
+//   - `pinned`    — when a background is set, a complete coherent scheme
+//                   (fg/muted/surface/border) derived from it and pinned for
+//                   every visitor. A chosen background IS the page; the
+//                   visitor's OS dark-mode setting must not repaint half the
+//                   variables into an unreadable hybrid.
+//
+// Everything is pure and deterministic: publish finalize, dashboard previews,
+// and tests all call the same functions and get the same pixels.
+import { formatHex, oklch, parse, wcagContrast } from "culori";
+/** Default page palette (mirrored into the shared template CSS). */
+export const PAGE_COLOR_DEFAULTS = {
+    accent: "#ff4217",
+    bg: "#f9f8f4",
+    fg: "#1a1913",
+    muted: "#6f6b62",
+    card: "#f9f8f4",
+    border: "#ddd9cf",
+    darkBg: "#141313",
+    darkFg: "#e9e7e2",
+    darkMuted: "#8f8b84",
+    darkCard: "#141313",
+    darkBorder: "#2b2a27",
+};
+/** WCAG AA for body-size text. */
+const TEXT_CONTRAST = 4.5;
+/** Body-size button labels on accent fills. */
+const UI_CONTRAST = 4.5;
+/** Essential control boundaries against their painted surface. */
+const CONTROL_CONTRAST = 3;
+/** Primary foreground meets AA even on mid-tone custom backgrounds. */
+const FG_CONTRAST = 4.5;
+function safeParse(value) {
+    if (!value)
+        return undefined;
+    try {
+        return parse(value.trim());
+    }
+    catch {
+        return undefined;
+    }
+}
+function contrast(a, b) {
+    return wcagContrast(a, b);
+}
+function isLightSurface(surface) {
+    return contrast("#000000", surface) >= contrast("#ffffff", surface);
+}
+/**
+ * Return `color` unchanged when it already meets `target` on `surface`;
+ * otherwise move its OKLCH lightness (hue/chroma preserved) just far enough
+ * to meet it. Falls back to plain black/white when even full lightness range
+ * cannot reach the target (e.g. a mid-gray surface).
+ */
+export function readableOn(color, surface, target) {
+    if (contrast(color, surface) >= target)
+        return color;
+    const parsed = safeParse(color);
+    const converted = parsed ? oklch(parsed) : undefined;
+    if (!converted)
+        return isLightSurface(surface) ? "#000000" : "#ffffff";
+    const base = { mode: "oklch", l: converted.l, c: converted.c, h: converted.h ?? 0 };
+    const darken = isLightSurface(surface);
+    const limit = darken ? 0 : 1;
+    const atLimit = formatHex({ ...base, l: limit });
+    if (contrast(atLimit, surface) < target) {
+        return isLightSurface(surface) ? "#000000" : "#ffffff";
+    }
+    // Binary search for the lightness closest to the original that still meets
+    // the target; contrast is monotonic in lightness on a fixed surface side.
+    let searchLimit = limit;
+    let searchStart = base.l;
+    for (let i = 0; i < 24; i += 1) {
+        const mid = (searchStart + searchLimit) / 2;
+        if (contrast(formatHex({ ...base, l: mid }), surface) >= target) {
+            searchLimit = mid;
+        }
+        else {
+            searchStart = mid;
+        }
+    }
+    return formatHex({ ...base, l: searchLimit });
+}
+/** Button-label color for an accent fill: white when it can carry, else ink. */
+export function onAccentColor(accent) {
+    return contrast("#ffffff", accent) >= UI_CONTRAST ? "#ffffff" : "#000000";
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/** Derive a complete coherent scheme from a pushed background color. */
+function schemeFromBackground(background) {
+    const parsed = safeParse(background);
+    const bg = parsed ? formatHex(parsed) : PAGE_COLOR_DEFAULTS.bg;
+    const base = (parsed ? oklch(parsed) : undefined) ?? {
+        mode: "oklch",
+        l: 0.98,
+        c: 0.004,
+        h: 80,
+    };
+    const hue = base.h ?? 0;
+    const tint = Math.min(base.c ?? 0, 0.02);
+    if (isLightSurface(bg)) {
+        return {
+            polarity: "light",
+            colors: {
+                bg,
+                card: bg,
+                fg: readableOn(PAGE_COLOR_DEFAULTS.fg, bg, FG_CONTRAST),
+                muted: readableOn(formatHex({ mode: "oklch", l: 0.55, c: tint, h: hue }), bg, TEXT_CONTRAST),
+                border: readableOn(formatHex({ mode: "oklch", l: 0.9, c: Math.min(tint, 0.015), h: hue }), bg, CONTROL_CONTRAST),
+                error: readableOn("#a82d1a", bg, TEXT_CONTRAST),
+            },
+        };
+    }
+    const borderL = clamp(base.l + 0.1, 0.28, 0.45);
+    return {
+        polarity: "dark",
+        colors: {
+            bg,
+            card: bg,
+            fg: readableOn(PAGE_COLOR_DEFAULTS.darkFg, bg, FG_CONTRAST),
+            muted: readableOn(formatHex({ mode: "oklch", l: 0.72, c: tint, h: hue }), bg, TEXT_CONTRAST),
+            border: readableOn(formatHex({ mode: "oklch", l: borderL, c: tint, h: hue }), bg, CONTROL_CONTRAST),
+            error: readableOn("#ff8a7a", bg, TEXT_CONTRAST),
+        },
+    };
+}
+/** The one entry point: raw theme in, everything the templates paint with out. */
+export function derivePageColors(theme) {
+    const accentInput = theme.accent?.trim();
+    const accent = safeParse(accentInput) ? accentInput : PAGE_COLOR_DEFAULTS.accent;
+    const onAccent = onAccentColor(accent);
+    const background = theme.background?.trim();
+    if (background && safeParse(background)) {
+        const { polarity, colors } = schemeFromBackground(background);
+        return {
+            scheme: polarity,
+            accent,
+            onAccent,
+            link: readableOn(accent, colors.card, TEXT_CONTRAST),
+            pinned: colors,
+        };
+    }
+    return {
+        scheme: "adaptive",
+        accent,
+        onAccent,
+        link: readableOn(accent, PAGE_COLOR_DEFAULTS.card, TEXT_CONTRAST),
+        linkDark: readableOn(accent, PAGE_COLOR_DEFAULTS.darkCard, TEXT_CONTRAST),
+    };
+}
+/** Hex form of any schema-accepted color, for color-picker inputs. */
+export function pageColorToHex(value) {
+    const parsed = safeParse(value);
+    return parsed ? formatHex(parsed) : null;
+}