slidemind 0.3.20 → 0.4.0

package/src/builders/design-tokens.mjs

@@ -0,0 +1,347 @@
+// The design's colour tokens, read from the bundle's corporate-design.css, and
+// the snap from an observed colour to the nearest one. The vision spec reports
+// what it sees (`fillHex`, `colorHex`); the design's palette lives here and
+// only here — no second colour vocabulary anywhere.
+import fs from "node:fs";
+import path from "node:path";
+
+export function readTypeRamp(bundleDir) {
+  try {
+    return parseTypeRamp(fs.readFileSync(path.join(bundleDir, "corporate-design.css"), "utf8"));
+  } catch {
+    return { stageWidthPx: null, steps: [] };
+  }
+}
+
+// The design's type ramp: every `--fs-*` step in px, smallest first, and the
+// stage width (`--stage-width-px`, the master's slide width in CSS px) that
+// sets their scale.
+export function parseTypeRamp(css) {
+  const clean = String(css).replace(/\/\*[\s\S]*?\*\//g, "");
+  const px = (v) => { const m = /^\s*(\d+(?:\.\d+)?)px\s*$/.exec(v ?? ""); return m ? Number(m[1]) : null; };
+  const steps = [];
+  let stageWidthPx = null;
+  for (const m of clean.matchAll(/(--[\w-]+)\s*:\s*([^;{}]+)/g)) {
+    if (m[1] === "--stage-width-px") stageWidthPx = px(m[2]);
+    else if (m[1].startsWith("--fs-") && px(m[2]) != null && !steps.some((s) => s.name === m[1])) steps.push({ name: m[1], px: px(m[2]) });
+  }
+  return { stageWidthPx, steps: steps.sort((a, b) => a.px - b.px) };
+}
+
+// Concepts set body copy at ~1.2% of the stage width on every brand (measured
+// on four ramps, 09-30): the slide's text sits on the largest step at or
+// under it. Calibration knob.
+const BODY_SHARE = 0.012;
+// Where two steps share a size, the one a slide's text is named after.
+const PREFERRED = ["--fs-body", "--fs-body-sm", "--fs-caption", "--fs-h3", "--fs-h2", "--fs-h1", "--fs-display"];
+
+/**
+ * One slide's type hierarchy on the design's ramp: titles and body on one
+ * step, labels and captions one step under it, numbers on --fs-h3 (two
+ * steps up without one). `offset` moves the whole ladder along the ramp
+ * (-1: one step down, for a slide whose text does not fit). Null without a
+ * usable ramp.
+ */
+export function typeLadder(ramp, offset = 0) {
+  if (!ramp?.stageWidthPx || !ramp.steps?.length) return null;
+  const sizes = [...new Set(ramp.steps.map((s) => s.px))].sort((a, b) => a - b);
+  const nameOf = (px) => {
+    const names = ramp.steps.filter((s) => s.px === px).map((s) => s.name);
+    return PREFERRED.find((n) => names.includes(n)) ?? names[0];
+  };
+  const body = Math.max(0, sizes.findLastIndex((px) => px <= BODY_SHARE * ramp.stageWidthPx + 0.01));
+  const h3 = ramp.steps.find((s) => s.name === "--fs-h3");
+  const number = Math.max(body, h3 ? sizes.indexOf(h3.px) : Math.min(body + 2, sizes.length - 1));
+  const at = (i) => nameOf(sizes[Math.min(sizes.length - 1, Math.max(0, i + offset))]);
+  return { body: at(body), small: at(body - 1), number: at(number) };
+}
+
+export function readColorTokens(bundleDir) {
+  let css = "";
+  try {
+    css = fs.readFileSync(path.join(bundleDir, "corporate-design.css"), "utf8");
+  } catch {
+    return [];
+  }
+  return parseColorTokens(css);
+}
+
+export function parseColorTokens(css) {
+  // Custom-property names belong to the bundle. Resolve aliases without
+  // assuming a foreground/background naming scheme; cycles stay unresolved.
+  const declarations = new Map();
+  for (const m of String(css).replace(/\/\*[\s\S]*?\*\//g, "").matchAll(/(--[\w-]+)\s*:\s*([^;{}]+)/g)) declarations.set(m[1], m[2].trim());
+  const resolve = (name, seen = new Set()) => {
+    if (seen.has(name)) return null;
+    seen.add(name);
+    const value = (declarations.get(name) ?? "").replace(/\s*!important\s*$/, "");
+    const alias = /^var\(\s*(--[\w-]+)\s*(?:,\s*(.+))?\)$/.exec(value);
+    return alias ? resolve(alias[1], seen) ?? parseOpaqueColor(alias[2]) : parseOpaqueColor(value);
+  };
+  return [...declarations.keys()].flatMap((name) => {
+    const rgb = resolve(name);
+    return rgb ? [{ name, hex: rgbToHex(rgb), rgb }] : [];
+  });
+}
+
+function parseOpaqueColor(value) {
+  if (!value) return null;
+  if (value.startsWith("#")) return hexToRgb(value);
+  const m = /^rgba?\(([^)]+)\)$/i.exec(value);
+  if (!m) return null;
+  const parts = m[1].trim().split(/[\s,\/]+/);
+  if (parts.length < 3 || parts.length > 4) return null;
+  const number = (s, max) => /^[-+]?(?:\d*\.)?\d+%?$/.test(s)
+    ? Number(s.replace(/%$/, "")) * (s.endsWith("%") ? max / 100 : 1) : NaN;
+  if (parts.length === 4 && number(parts[3], 1) !== 1) return null;
+  const rgb = parts.slice(0, 3).map((s) => number(s, 255));
+  return rgb.every((n) => Number.isFinite(n) && n >= 0 && n <= 255) ? rgb.map(Math.round) : null;
+}
+
+export function hexToRgb(hex) {
+  let h = String(hex).trim().replace(/^#/, "");
+  if (!/^(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(h)) return null;
+  if (h.length <= 4) h = h.split("").map((c) => c + c).join("");
+  // Translucent paint needs compositing before contrast can be evaluated.
+  if (h.length === 8 && h.slice(6).toLowerCase() !== "ff") return null;
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+}
+
+// Use declared semantic tokens when present. Extrema are useful neutral
+// fallbacks, but saturation cannot tell a brand accent from a warning colour.
+export function paletteRoles(tokens) {
+  const named = (...names) => names.map((name) => tokens.find((t) => t.name === name)).find(Boolean);
+  const ordered = [...tokens].sort((a, b) => relLuminance(a.rgb) - relLuminance(b.rgb));
+  const dark = named("--fg-1") ?? ordered[0];
+  const light = named("--fg-on-dark") ?? ordered.at(-1);
+  const accent = named("--fg-accent", "--color-accent", "--accent");
+  const muted = named("--fg-3") ?? dark;
+  return {
+    tone: { dark, light, accent, muted },
+    fill: { white: named("--bg-1") ?? light, light: named("--bg-2") ?? light,
+      dark: named("--bg-ink") ?? dark, accent, muted: named("--bg-3") ?? light },
+  };
+}
+
+const rgbToHex = ([r, g, b]) => `#${[r, g, b].map((v) => v.toString(16).padStart(2, "0")).join("").toUpperCase()}`;
+
+// Perceptual-ish distance (redmean weighting) — good enough to tell a green
+// status dot from the brand accent and white from a pale surface.
+export function colorDistance(a, b) {
+  const rm = (a[0] + b[0]) / 2;
+  const dr = a[0] - b[0];
+  const dg = a[1] - b[1];
+  const db = a[2] - b[2];
+  return Math.sqrt((2 + rm / 256) * dr * dr + 4 * dg * dg + (2 + (255 - rm) / 256) * db * db);
+}
+
+export function luminance(rgb) {
+  return (0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2]) / 255;
+}
+
+// Hue angle (0-360) and saturation/lightness of an rgb triple.
+export function hsl([r, g, b]) {
+  const R = r / 255, G = g / 255, B = b / 255;
+  const max = Math.max(R, G, B), min = Math.min(R, G, B), d = max - min;
+  const l = (max + min) / 2;
+  if (!d) return { h: 0, s: 0, l };
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === R) h = ((G - B) / d) % 6;
+  else if (max === G) h = (B - R) / d + 2;
+  else h = (R - G) / d + 4;
+  h *= 60;
+  return { h: h < 0 ? h + 360 : h, s, l };
+}
+
+
+// WCAG relative luminance and contrast ratio. `luminance()` above is a cheap
+// light/dark test; this is the one to use when the question is "can this be
+// read on that", because a mid-grey on a mid-blue passes the cheap test and
+// fails the eye.
+const channel = (v) => {
+  const c = v / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+};
+
+export function relLuminance(rgb) {
+  return 0.2126 * channel(rgb[0]) + 0.7152 * channel(rgb[1]) + 0.0722 * channel(rgb[2]);
+}
+
+export function contrastRatio(hexA, hexB) {
+  const a = hexToRgb(hexA);
+  const b = hexToRgb(hexB);
+  if (!a || !b) return null;
+  const la = relLuminance(a);
+  const lb = relLuminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+// ---- Chart colours: the design's, never the painting's.
+//
+// A chart is painted from the design bundle. Its series take the bundle's chart
+// palette in order; a mark that MEANS something takes the bundle's colour for
+// that role: `highlight` (the one the slide is about), `context` (the rest,
+// shown quietly), `positive` / `negative` (a rise and a fall, a gain and a
+// loss), `reference` (a target, a plan, a benchmark). The CD pipeline writes
+// them into corporate-design.css as `--chart-series-N` and `--chart-<role>`
+// (bundle-canonical/tokens-css.ts, from `chartPaletteFromTheme` below); a
+// bundle written before them derives the same from its own theme slots by the
+// same rule. A painted hex is never copied: x111 QBR 3 mapped two pale painted
+// slices onto the theme and x109's painted blue ramp came out as greys.
+export const CHART_ROLES = ["highlight", "context", "positive", "negative", "reference"];
+const THEME_ORDER = ["accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "tx1", "tx2", "bg1", "bg2"];
+// A filled mark the ground swallows is no colour for a chart: a pale slot on
+// the slide's own ground (statworx: accent6 #EBF0F2 and accent4 #FFFF00 on
+// white, 1.13:1 and 1.07:1) leaves the palette; a light grey context bar
+// (#D9D9D9, 1.35:1) stays.
+const CHART_VISIBLE = 1.25;
+const QUIET_VISIBLE = 1.1;
+const CHROMA = 0.25;
+
+/**
+ * The chart palette and roles a theme yields, as theme slot names
+ * (`"accent1"`): the series cycle is accent1..6 in the theme's own order,
+ * minus the slots its ground (`bg1`) swallows; `highlight` is the brand accent
+ * (`accent1`); `context` the lightest visible neutral and `reference` the next
+ * darker one; `positive` / `negative` the visible chromatic accents nearest
+ * green and red, else the highlight and the reference. `theme` maps slot
+ * names to hex.
+ */
+export function chartPaletteFromTheme(theme) {
+  const has = (n) => typeof theme?.[n] === "string" && hexToRgb(theme[n]);
+  const ground = has("bg1") ? theme.bg1 : "#FFFFFF";
+  const visible = (n) => has(n) && (contrastRatio(theme[n], ground) ?? 0) >= CHART_VISIBLE;
+  const tone = (n) => hsl(hexToRgb(theme[n]));
+  const accents = THEME_ORDER.slice(0, 6).filter(visible);
+  const series = accents.length ? accents : ["tx2", "tx1"].filter(visible).slice(0, 1);
+  const highlight = visible("accent1") ? "accent1" : series[0] ?? null;
+  const lum = (n) => relLuminance(hexToRgb(theme[n]));
+  const neutrals = ["bg2", "accent2", "accent3", "accent4", "accent5", "accent6", "tx2"]
+    .filter((n) => visible(n) && tone(n).s < CHROMA)
+    .sort((a, b) => lum(b) - lum(a));
+  const context = neutrals[0] ?? series[1] ?? highlight;
+  const reference = neutrals.find((n) => n !== context && n !== "tx2") ?? neutrals.find((n) => n !== context) ?? context;
+  // Context marks recede but stay apart: a chart that sets several marks back
+  // (the slices beside a highlighted one, x113 QBR 3: three slices in one grey)
+  // paints them in the theme's neutrals one by one — the context colour, then
+  // the darker neutrals, then the lighter — never the ink (tx1/tx2). A quiet
+  // mark only needs to part from the ground (QUIET_VISIBLE), not to carry a
+  // series of its own.
+  const quietOk = (n) => has(n) && (contrastRatio(theme[n], ground) ?? 0) >= QUIET_VISIBLE && tone(n).s < CHROMA;
+  const quietPool = ["bg2", "accent2", "accent3", "accent4", "accent5", "accent6"].filter((n) => n !== context && quietOk(n));
+  const quiet = [
+    context,
+    ...quietPool.filter((n) => lum(n) < lum(context)).sort((a, b) => lum(b) - lum(a)),
+    ...quietPool.filter((n) => lum(n) >= lum(context)).sort((a, b) => lum(a) - lum(b)),
+  ];
+  const chromatic = accents.filter((n) => tone(n).s >= CHROMA && tone(n).l > 0.15 && tone(n).l < 0.9);
+  const nearest = (hue, within) => {
+    const gap = (n) => { const d = Math.abs(tone(n).h - hue) % 360; return Math.min(d, 360 - d); };
+    return chromatic.filter((n) => gap(n) <= within).sort((a, b) => gap(a) - gap(b))[0] ?? null;
+  };
+  return {
+    series,
+    roles: {
+      highlight,
+      context,
+      positive: nearest(120, 50) ?? highlight,
+      negative: nearest(0, 40) ?? reference,
+      reference,
+    },
+    quiet: quiet.length ? quiet : [context],
+  };
+}
+
+/**
+ * The design's chart palette from the bundle's colour tokens: the
+ * `--chart-*` tokens as theme paints (`{ scheme }`, so the chart stays native
+ * and follows a theme change; a bundle colour no theme slot holds stays as it
+ * is, `{ rgb }`), else the same palette derived from the bundle's `--theme-*`
+ * slots. Null when the bundle declares no theme (a reconstruction's literal
+ * palette): the master then paints its own series.
+ */
+export function chartPalette(tokens) {
+  const theme = Object.fromEntries(
+    THEME_ORDER.map((n) => [n, tokens.find((t) => t.name === `--theme-${n}`)?.hex]).filter(([, hex]) => hex),
+  );
+  if (!Object.keys(theme).length) return null;
+  const paint = (hex) => {
+    const slot = THEME_ORDER.find((n) => theme[n] && theme[n].toUpperCase() === String(hex).toUpperCase());
+    return slot ? { scheme: slot } : { rgb: String(hex).replace(/^#/, "").toUpperCase() };
+  };
+  const token = (name) => tokens.find((t) => t.name === name)?.hex ?? null;
+  const declared = [];
+  for (let i = 1; token(`--chart-series-${i}`); i++) declared.push(paint(token(`--chart-series-${i}`)));
+  const derived = chartPaletteFromTheme(theme);
+  const roles = Object.fromEntries(CHART_ROLES.map((r) => {
+    const hex = token(`--chart-${r}`);
+    return [r, hex ? paint(hex) : derived.roles[r] ? { scheme: derived.roles[r] } : null];
+  }));
+  const series = declared.length ? declared : derived.series.map((n) => ({ scheme: n }));
+  const quietDeclared = [];
+  for (let i = 1; token(`--chart-quiet-${i}`); i++) quietDeclared.push(paint(token(`--chart-quiet-${i}`)));
+  const quiet = quietDeclared.length ? quietDeclared : (derived.quiet ?? []).map((n) => ({ scheme: n }));
+  return series.length ? { series, roles, quiet: quiet.length ? quiet : roles.context ? [roles.context] : [] } : null;
+}
+
+// ---- Perceptual colour distance.
+// CIELAB lightness/opponent axes from sRGB (D65).
+export function labOf(rgb) {
+  const lin = (v) => { const c = v / 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+  const [R, G, B] = rgb.map(lin);
+  const f = (t) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116);
+  const x = f((R * 0.4124 + G * 0.3576 + B * 0.1805) / 0.95047);
+  const y = f(R * 0.2126 + G * 0.7152 + B * 0.0722);
+  const z = f((R * 0.0193 + G * 0.1192 + B * 0.9505) / 1.08883);
+  return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
+}
+
+/**
+ * CIEDE2000 between two colours: which design colour a mockup colour IS,
+ * perceptually — its green is the design's green, its very dark navy is the
+ * design's ink, not its bright blue, its pale grey card stays a pale surface.
+ * Null when either colour does not parse.
+ */
+export function deltaE(hexA, hexB, { kL = 1 } = {}) {
+  const A = hexToRgb(hexA), B = hexToRgb(hexB);
+  if (!A || !B) return null;
+  const [L1, a1, b1] = labOf(A), [L2, a2, b2] = labOf(B);
+  const rad = Math.PI / 180;
+  const C1 = Math.hypot(a1, b1), C2 = Math.hypot(a2, b2), Cb = (C1 + C2) / 2;
+  const G = 0.5 * (1 - Math.sqrt(Cb ** 7 / (Cb ** 7 + 25 ** 7)));
+  const a1p = (1 + G) * a1, a2p = (1 + G) * a2;
+  const C1p = Math.hypot(a1p, b1), C2p = Math.hypot(a2p, b2);
+  const hue = (b, a) => { if (!b && !a) return 0; const t = Math.atan2(b, a) / rad; return t < 0 ? t + 360 : t; };
+  const h1p = hue(b1, a1p), h2p = hue(b2, a2p);
+  const dLp = L2 - L1, dCp = C2p - C1p;
+  let dhp = 0;
+  if (C1p * C2p) { dhp = h2p - h1p; if (dhp > 180) dhp -= 360; else if (dhp < -180) dhp += 360; }
+  const dHp = 2 * Math.sqrt(C1p * C2p) * Math.sin((dhp / 2) * rad);
+  const Lbp = (L1 + L2) / 2, Cbp = (C1p + C2p) / 2;
+  let hbp = h1p + h2p;
+  if (C1p * C2p) hbp = Math.abs(h1p - h2p) > 180 ? (h1p + h2p + (h1p + h2p < 360 ? 360 : -360)) / 2 : (h1p + h2p) / 2;
+  const T = 1 - 0.17 * Math.cos((hbp - 30) * rad) + 0.24 * Math.cos(2 * hbp * rad) + 0.32 * Math.cos((3 * hbp + 6) * rad) - 0.2 * Math.cos((4 * hbp - 63) * rad);
+  const dth = 30 * Math.exp(-(((hbp - 275) / 25) ** 2));
+  const Rc = 2 * Math.sqrt(Cbp ** 7 / (Cbp ** 7 + 25 ** 7));
+  const Sl = 1 + (0.015 * (Lbp - 50) ** 2) / Math.sqrt(20 + (Lbp - 50) ** 2), Sc = 1 + 0.045 * Cbp, Sh = 1 + 0.015 * Cbp * T;
+  const Rt = -Math.sin(2 * dth * rad) * Rc;
+  return Math.sqrt((dLp / (kL * Sl)) ** 2 + (dCp / Sc) ** 2 + (dHp / Sh) ** 2 + Rt * (dCp / Sc) * (dHp / Sh));
+}
+
+/**
+ * Every token, nearest first by `deltaE` to an observed colour. Two tokens
+ * that paint the same colour tie; `prefer` (a name pattern) breaks the tie
+ * toward the role the colour is used in (a white fill is a background, a
+ * white text is foreground).
+ */
+export function rankTokens(hex, tokens, { prefer = null } = {}) {
+  const bias = (t) => (prefer && !prefer.test(t.name) ? 0.5 : 0);
+  return tokens.map((t) => ({ t, d: deltaE(hex, t.hex) })).filter((v) => v.d != null).sort((a, b) => a.d + bias(a.t) - (b.d + bias(b.t)));
+}
+
+/** CIELAB lightness (0–100) of a hex colour, or null. */
+export function lightnessOf(hex) {
+  const rgb = hexToRgb(hex);
+  return rgb ? labOf(rgb)[0] : null;
+}