@crossworks/share-ui 0.230.43

package/themes/model.mjs

@@ -0,0 +1,213 @@
+/**
+ * Colour model for the theme generator — OKLab/OKLCH math, WCAG contrast, and
+ * the anchored AA solver.
+ *
+ * THE PRINCIPLE. A theme's identity is its surfaces and fills; text colour is a
+ * pure function of (hue, surface, target ratio). So every text token is SOLVED,
+ * not authored: keep the anchor's hue and chroma (the theme's identity), scan
+ * lightness outward from the anchor in small steps, and take the first value
+ * that clears the required ratio against every surface it must sit on. The
+ * anchor is the authored value wherever one exists, so a token that already
+ * passes is emitted byte-for-byte unchanged, and one that fails moves the
+ * minimum perceptible amount. Measured across the 172 ink tokens shipped in
+ * v0.206.12: 0 infeasible, max |ΔL| 0.43, most far smaller.
+ *
+ * TRAP (cost a real session): validate the ROUNDED 8-BIT HEX you will emit,
+ * not the float candidate. Values that clear 4.5:1 in float land at 4.483 once
+ * written as hex. Every solver in this file round-trips through `toHex` before
+ * measuring.
+ *
+ * The sRGB<->OKLab matrices mirror the ones proven in
+ * `src/lib/themes.test.ts`; the test recomputes every pair independently, so a
+ * transcription error here fails CI rather than shipping.
+ */
+
+export const clamp01 = (x) => Math.min(1, Math.max(0, x));
+const srgbToLin = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const linToSrgb = (c) => (c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055);
+
+/** Any notation used in theme sources -> sRGB [r,g,b] in 0..1 (gamut-clamped,
+ *  which is what a browser renders for out-of-gamut oklch()). */
+export function parseColor(value) {
+  const v = value.trim();
+  if (v.startsWith('#')) {
+    let h = v.slice(1);
+    if (h.length === 3) h = [...h].map((c) => c + c).join('');
+    if (h.length === 8) h = h.slice(0, 6);
+    if (!/^[0-9a-f]{6}$/i.test(h)) throw new Error(`bad hex: ${value}`);
+    return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
+  }
+  const args = v
+    .slice(v.indexOf('(') + 1, v.lastIndexOf(')'))
+    .split('/')[0]
+    .trim()
+    .split(/[\s,]+/);
+  if (v.startsWith('oklch')) {
+    const L = args[0].endsWith('%') ? parseFloat(args[0]) / 100 : parseFloat(args[0]);
+    const C = args[1].endsWith('%') ? (parseFloat(args[1]) / 100) * 0.4 : parseFloat(args[1]);
+    const H = parseFloat(args[2] ?? '0') || 0;
+    return oklchToSrgb([L, C, H]);
+  }
+  if (v.startsWith('hsl')) {
+    const [h, sPct, lPct] = args.map(parseFloat);
+    const [S, L] = [sPct / 100, lPct / 100];
+    const k = (n) => (n + h / 30) % 12;
+    const a = S * Math.min(L, 1 - L);
+    const f = (n) => L - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+    return [f(0), f(8), f(4)];
+  }
+  throw new Error(`unsupported colour notation: ${value}`);
+}
+
+/** OKLCH [L, C, H°] -> sRGB 0..1, per-channel gamut clamp. */
+export function oklchToSrgb([L, C, Hdeg]) {
+  const H = (Hdeg * Math.PI) / 180;
+  const [a, b] = [C * Math.cos(H), C * Math.sin(H)];
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [
+    clamp01(linToSrgb(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s)),
+    clamp01(linToSrgb(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s)),
+    clamp01(linToSrgb(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s)),
+  ];
+}
+
+/** sRGB 0..1 -> OKLab [L, a, b]. */
+export function srgbToOklab([r, g, b]) {
+  const [lr, lg, lb] = [r, g, b].map(srgbToLin);
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ];
+}
+
+/** sRGB 0..1 -> OKLCH [L, C, H°]. */
+export function srgbToOklch(rgb) {
+  const [L, a, b] = srgbToOklab(rgb);
+  const C = Math.hypot(a, b);
+  let H = (Math.atan2(b, a) * 180) / Math.PI;
+  if (H < 0) H += 360;
+  return [L, C, H];
+}
+
+export const parseOklch = (css) => srgbToOklch(parseColor(css));
+
+export function toHex(rgb) {
+  return (
+    '#' +
+    rgb
+      .map((c) =>
+        Math.round(clamp01(c) * 255)
+          .toString(16)
+          .padStart(2, '0'),
+      )
+      .join('')
+  );
+}
+
+/** Normalise any supported notation to the 6-digit hex a browser renders. */
+export const cssToHex = (css) => toHex(parseColor(css));
+
+export const luminance = ([r, g, b]) => {
+  const [lr, lg, lb] = [r, g, b].map(srgbToLin);
+  return 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
+};
+
+/** WCAG 2.1 contrast between two CSS values, measured AS RENDERED — both sides
+ *  are first snapped to the 8-bit hex the browser will actually paint. */
+export function contrast(cssA, cssB) {
+  const [a, b] = [luminance(parseColor(cssToHex(cssA))), luminance(parseColor(cssToHex(cssB)))];
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+
+/** Perceptual distance in OKLab. Rule of thumb: <0.01 imperceptible, <0.02
+ *  barely noticeable side by side, >0.05 clearly a different colour. */
+export function deltaE(cssA, cssB) {
+  const [l1, a1, b1] = srgbToOklab(parseColor(cssA));
+  const [l2, a2, b2] = srgbToOklab(parseColor(cssB));
+  return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+}
+
+export function hueDistance(a, b) {
+  const d = Math.abs(a - b) % 360;
+  return d > 180 ? 360 - d : d;
+}
+
+const L_STEP = 0.0025;
+
+/**
+ * The anchored AA solver.
+ *
+ * Finds the colour nearest the anchor (in lightness, then chroma) whose EMITTED
+ * HEX clears `ratio` against every surface in `against`. Returns
+ * `{ hex, dL, dC, feasible }`; `feasible: false` only when even the achromatic
+ * extremes fail, which for AA text against real surfaces does not happen —
+ * pure black or white clears 4.5:1 against anything a UI uses as a surface.
+ *
+ * Order of preference:
+ *   1. anchor as-is (a passing authored value is emitted unchanged),
+ *   2. lightness moved outward, smallest |ΔL| first (hue + chroma untouched),
+ *   3. only then chroma reduced (needed for 2 of 172 tokens in the ink split).
+ */
+export function solveText(anchorCss, against, { ratio = 4.5 } = {}) {
+  const [L0, C0, H] = parseOklch(anchorCss);
+  const surfaces = against.map(cssToHex);
+  const passes = (hex) => surfaces.every((s) => contrast(hex, s) >= ratio);
+
+  for (let scale = 1; scale >= -1e-9; scale -= 0.1) {
+    const C = C0 * Math.max(0, scale);
+    // Scan L outward from the anchor, both directions, nearest first.
+    for (let i = 0; ; i++) {
+      const up = L0 + i * L_STEP;
+      const down = L0 - i * L_STEP;
+      if (up > 1 + L_STEP && down < -L_STEP) break;
+      for (const L of i === 0 ? [L0] : [down, up]) {
+        if (L < 0 || L > 1) continue;
+        const hex = toHex(oklchToSrgb([L, C, H]));
+        if (passes(hex)) {
+          return { hex, dL: L - L0, dC: C - C0, feasible: true };
+        }
+      }
+    }
+  }
+  return { hex: toHex(oklchToSrgb([L0, C0, H])), dL: 0, dC: 0, feasible: false };
+}
+
+/**
+ * Joint solve for a fill and its own -foreground.
+ *
+ * WHY THE FILL MAY MOVE AT ALL. A white foreground on a mid-saturation brand
+ * fill (3.9:1, the most common authored defect) has no light value that clears
+ * 4.5:1 — the nearest one-sided fix is near-black text, an identity flip far
+ * louder than deepening the fill a step. The v0.206.7 accent repair set the
+ * precedent by hand: "move the LIGHTNESS of whichever of the two shifts
+ * least". This does that mechanically: scan fill ΔL outward (hue and chroma
+ * pinned), give the foreground a minimal solve against each candidate, and
+ * take the pair with the least total movement — fill weighted heavier, since a
+ * fill repaints every component wearing it. A pair that already passes costs 0
+ * and ships byte-for-byte as authored.
+ */
+export function solvePair(fillCss, fgAnchorCss, { ratio = 4.5, fillWeight = 1.5 } = {}) {
+  const [fL, fC, fH] = parseOklch(fillCss);
+  let best = null;
+  for (let i = 0; i * L_STEP * 2 <= 1; i++) {
+    const dLf = i * L_STEP * 2;
+    if (best && fillWeight * dLf >= best.cost) break; // no candidate can win
+    for (const sign of i === 0 ? [0] : [-1, 1]) {
+      const L = fL + sign * dLf;
+      if (L < 0 || L > 1) continue;
+      const fillHex = toHex(oklchToSrgb([L, fC, fH]));
+      const fg = solveText(fgAnchorCss, [fillHex], { ratio });
+      if (!fg.feasible) continue;
+      const cost = fillWeight * dLf + Math.abs(fg.dL) + Math.abs(fg.dC);
+      if (!best || cost < best.cost) best = { fill: fillHex, fg: fg.hex, cost };
+    }
+  }
+  if (!best) throw new Error(`no feasible pair for fill ${fillCss}`);
+  return best;
+}

package/themes/preview.html

@@ -0,0 +1,145 @@
+<!doctype html>
+<!-- Theme preview harness — renders the GENERATED themes.css with zero app
+     code, so a seeds/generator change can be eyeballed across all themes and
+     both modes before it ships. Serve the package directory statically
+     (e.g. `python3 -m http.server -d packages/web-ui 4173`) and open
+     /themes/preview.html. Nothing here ships to a browser in production. -->
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>Mantle theme preview</title>
+<link rel="stylesheet" href="../styles/themes.css" />
+<style>
+  html { font-family: var(--font-sans, Inter, sans-serif); }
+  body { margin: 0; background: var(--background); color: var(--foreground); transition: background 0.15s; }
+  .bar { display: flex; gap: 0.75rem; align-items: center; padding: 0.75rem 1rem; border-bottom: 1px solid var(--border); position: sticky; top: 0; background: var(--card); z-index: 2; flex-wrap: wrap; }
+  main { padding: 1rem; display: grid; gap: 1rem; grid-template-columns: repeat(auto-fit, minmax(340px, 1fr)); }
+  section { border: 1px solid var(--border); border-radius: var(--radius, 8px); background: var(--card); color: var(--card-foreground); padding: 1rem; }
+  h2 { margin: 0 0 0.6rem; font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted-foreground); }
+  .row { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 0.5rem; }
+  .btn { border: 0; border-radius: var(--radius, 8px); padding: 0.45rem 0.9rem; font-weight: 600; font-size: 0.85rem; }
+  .chip { border-radius: 999px; padding: 0.2rem 0.7rem; font-size: 0.75rem; font-weight: 600; }
+  .surface { border-radius: var(--radius, 8px); padding: 0.6rem 0.8rem; font-size: 0.85rem; }
+  pre { background: var(--muted); color: var(--foreground); border-radius: var(--radius, 8px); padding: 0.8rem 1rem; font-family: var(--font-mono, monospace); font-size: 0.8rem; line-height: 1.5; overflow-x: auto; }
+  .callout { border-left: 3px solid; border-radius: var(--radius, 8px); padding: 0.5rem 0.9rem; font-size: 0.85rem; margin-bottom: 0.5rem; }
+  .swatches { display: flex; height: 2rem; border-radius: var(--radius, 8px); overflow: hidden; }
+  .swatches div { flex: 1; }
+  .inks span { display: block; font-size: 0.85rem; padding: 0.1rem 0; }
+  select, .toggle { font: inherit; padding: 0.3rem 0.5rem; border-radius: 6px; border: 1px solid var(--border); background: var(--background); color: var(--foreground); }
+  a { color: var(--primary-ink); font-weight: 500; text-decoration: none; }
+</style>
+</head>
+<body>
+<div class="bar">
+  <select id="theme"></select>
+  <button class="toggle" id="mode">dark ⇄ light</button>
+  <span id="label" style="font-size:0.8rem;color:var(--muted-foreground)"></span>
+</div>
+<main>
+  <section>
+    <h2>Fills + on-fill text</h2>
+    <div class="row">
+      <button class="btn" style="background:var(--primary);color:var(--primary-foreground)">Primary</button>
+      <button class="btn" style="background:var(--secondary);color:var(--secondary-foreground)">Secondary</button>
+      <button class="btn" style="background:var(--accent);color:var(--accent-foreground)">Accent</button>
+      <button class="btn" style="background:var(--destructive);color:var(--destructive-foreground)">Delete</button>
+    </div>
+    <div class="row">
+      <button class="btn" style="background:var(--success);color:var(--success-foreground)">Success</button>
+      <button class="btn" style="background:var(--warning);color:var(--warning-foreground)">Warning</button>
+      <button class="btn" style="background:var(--info);color:var(--info-foreground)">Info</button>
+    </div>
+    <h2>Inks on surfaces</h2>
+    <div class="row">
+      <div class="surface inks" style="background:var(--background);border:1px solid var(--border)">
+        <span style="color:var(--primary-ink)">primary-ink</span>
+        <span style="color:var(--destructive-ink)">destructive-ink</span>
+        <span style="color:var(--success-ink)">success-ink</span>
+        <span style="color:var(--warning-ink)">warning-ink</span>
+        <span style="color:var(--info-ink)">info-ink</span>
+        <span style="color:var(--muted-foreground)">muted-foreground</span>
+      </div>
+      <div class="surface inks" style="background:var(--muted)">
+        <span style="color:var(--primary-ink)">primary-ink</span>
+        <span style="color:var(--destructive-ink)">destructive-ink</span>
+        <span style="color:var(--success-ink)">success-ink</span>
+        <span style="color:var(--warning-ink)">warning-ink</span>
+        <span style="color:var(--info-ink)">info-ink</span>
+        <span style="color:var(--muted-foreground)">muted-foreground</span>
+      </div>
+      <div class="surface inks" style="background:var(--sidebar);color:var(--sidebar-foreground)">
+        <span>sidebar-foreground</span>
+        <span style="color:var(--primary-ink)">primary-ink</span>
+        <span style="color:var(--muted-foreground)">muted-foreground</span>
+      </div>
+    </div>
+  </section>
+  <section>
+    <h2>Code (the --code-* palette on --muted)</h2>
+    <pre><span style="color:var(--code-keyword)">export function</span> <span style="color:var(--code-title)">solveInk</span>(<span style="color:var(--code-variable)">anchor</span>, <span style="color:var(--code-variable)">surfaces</span>) {
+  <span style="color:var(--code-keyword)">const</span> <span style="color:var(--code-variable)">ratio</span> = <span style="color:var(--code-number)">4.5</span>; <span style="color:var(--muted-foreground);font-style:italic">// AA, measured on the emitted hex</span>
+  <span style="color:var(--code-keyword)">return</span> <span style="color:var(--code-title)">scan</span>(<span style="color:var(--code-string)">'lightness'</span>, <span style="color:var(--code-variable)">anchor</span>);
+}</pre>
+    <h2>Callouts</h2>
+    <div class="callout" style="border-color:var(--info);background:color-mix(in oklab, var(--info) 8%, transparent)">ℹ️ Info — border + 8% tint from <b>--info</b>.</div>
+    <div class="callout" style="border-color:var(--success);background:color-mix(in oklab, var(--success) 8%, transparent)">✅ Success — the role, not chart-4.</div>
+    <div class="callout" style="border-color:var(--warning);background:color-mix(in oklab, var(--warning) 8%, transparent)">⚠️ Warning — the role, not chart-5.</div>
+    <div class="callout" style="border-color:var(--destructive);background:color-mix(in oklab, var(--destructive) 8%, transparent)">🛑 Danger — destructive, as before.</div>
+  </section>
+  <section>
+    <h2>Charts (categorical)</h2>
+    <div class="swatches" id="charts"></div>
+    <h2>Prose accents</h2>
+    <div style="color:var(--primary-ink);font-size:1.3rem;font-weight:700">Heading (primary-ink)</div>
+    <div style="color:var(--info-ink);font-weight:600">h4 accent (info-ink)</div>
+    <p style="margin:0.4rem 0">Body text with <a href="#">a themed link</a> and a <span style="border-radius:0.3rem;background:color-mix(in oklab, var(--info) 16%, transparent);color:var(--info-ink);padding:0.05em 0.3em;font-weight:500">@node mention</span>.</p>
+    <h2>All themes</h2>
+    <div id="grid" style="display:grid;grid-template-columns:repeat(auto-fill,minmax(120px,1fr));gap:0.4rem"></div>
+  </section>
+</main>
+<script type="module">
+  // The registry is TS; scrape ids straight from the stylesheet instead so the
+  // harness has zero build steps.
+  const css = await (await fetch('../styles/themes.css')).text();
+  const ids = ['clean-slate', ...new Set([...css.matchAll(/^\[data-color-theme="([^"]+)"\]/gm)].map((m) => m[1]))];
+  const sel = document.getElementById('theme');
+  for (const id of ids) sel.add(new Option(id, id));
+  const apply = () => {
+    const id = sel.value;
+    const root = document.documentElement;
+    if (id === 'clean-slate') delete root.dataset.colorTheme;
+    else root.dataset.colorTheme = id;
+    document.getElementById('label').textContent =
+      `${id} — ${root.classList.contains('dark') ? 'dark' : 'light'}`;
+    const charts = document.getElementById('charts');
+    charts.innerHTML = '';
+    for (let n = 1; n <= 5; n++) {
+      const d = document.createElement('div');
+      d.style.background = `var(--chart-${n})`;
+      charts.appendChild(d);
+    }
+  };
+  sel.onchange = apply;
+  document.getElementById('mode').onclick = () => {
+    document.documentElement.classList.toggle('dark');
+    apply();
+  };
+  const grid = document.getElementById('grid');
+  for (const id of ids) {
+    const card = document.createElement('button');
+    card.style.cssText = 'border:1px solid var(--border);border-radius:6px;padding:0.3rem;background:var(--card);color:var(--card-foreground);cursor:pointer;font-size:0.65rem';
+    card.dataset.colorTheme = id === 'clean-slate' ? '' : id;
+    if (id !== 'clean-slate') card.setAttribute('data-color-theme', id);
+    card.innerHTML = `<div style="display:flex;height:1.1rem;border-radius:4px;overflow:hidden">
+      <div style="flex:1;background:var(--primary)"></div>
+      <div style="flex:1;background:var(--accent)"></div>
+      <div style="flex:1;background:var(--success)"></div>
+      <div style="flex:1;background:var(--warning)"></div>
+      <div style="flex:1;background:var(--info)"></div></div>${id}`;
+    card.onclick = () => { sel.value = id; apply(); };
+    grid.appendChild(card);
+  }
+  apply();
+</script>
+</body>
+</html>

package/themes/seeds.d.mts

@@ -0,0 +1,16 @@
+/** Hand-written declarations for seeds.mjs. */
+export type ThemeModeSeed = {
+  charts?: string[];
+  extras?: Record<string, string>;
+} & {
+  [token: string]: string | string[] | Record<string, string> | undefined;
+};
+
+export interface ThemeSeed {
+  id: string;
+  label: string;
+  light: ThemeModeSeed;
+  dark: ThemeModeSeed;
+}
+
+export const THEME_SEEDS: ThemeSeed[];