@siyahi/tools 0.1.9-next.24 → 0.1.9-next.25

package/contrast.mjs

@@ -23,10 +23,14 @@ import { readTheme } from "./theme.mjs";
  * What a component paints, written as Tailwind writes it:
  * `muted` is the token, `muted/50` the token at 50% over what lies under it,
  * and `positive@60` is `color-mix(in oklab, var(--positive) 60%, var(--card))`,
- * a treemap tile.
+ * a treemap tile; `positive@heat-5` takes the share from the theme's --heat-5.
  * @typedef {string} Paint
  */
-/** @typedef {{ fg: Paint, bg: Paint, min: number, scheme?: Scheme }} Pair */
+/**
+ * `surface` limits a pair to the canvas or the card, for a paint only one of them ever holds, such as a chart card's
+ * hover band.
+ * @typedef {{ fg: Paint, bg: Paint, min: number, scheme?: Scheme, surface?: "background" | "card" }} Pair
+ */
 
 const TEXT = 4.5;
 const MARK = 3;
@@ -34,14 +38,12 @@ const SURFACES = ["background", "card"];
 const CHARTS = ["chart-1", "chart-2", "chart-3", "chart-4", "chart-5"];
 
 /**
- * The light label on each treemap heat step, both sides.
- * @param {Scheme} scheme @param {number[]} shares
- * @returns {Pair[]}
+ * The label on each heat step, both sides, at the shares the theme's --heat-1 to --heat-5 set.
+ * @type {Pair[]}
  */
-const heatLabels = (scheme, shares) =>
-  ["positive", "negative"].flatMap((side) =>
-    shares.map((share) => ({ fg: "foreground", bg: `${side}@${share}`, min: TEXT, scheme })),
-  );
+const HEAT_LABELS = ["positive", "negative"].flatMap((side) =>
+  [1, 2, 3, 4, 5].map((step) => ({ fg: "foreground", bg: `${side}@heat-${step}`, min: TEXT })),
+);
 
 /** @type {Pair[]} */
 const PAIRS = [
@@ -95,16 +97,27 @@ const PAIRS = [
     ["positive", "positive/8"],
     ["negative", "negative/8"],
   ].map(([fg = "", bg = ""]) => ({ fg, bg, min: MARK })),
+  // A StatusHeatmap's degraded and critical days against a healthy one, its
+  // default 30% grey, so a bad day stands out of a run of good ones.
+  ...["warning", "destructive"].map((fg) => ({ fg, bg: "muted-foreground/30", min: MARK })),
   // The selected tab's fill against its list.
   { fg: "foreground", bg: "muted", min: MARK },
   // Chart marks on the canvas and the card. A dimmed bar keeps its full colour
   // as its outline, so these are the outlines too.
   ...[...CHARTS, "positive", "negative"].map((fg) => ({ fg, bg: "", min: MARK })),
   ...CHARTS.slice(0, -1).map((fg, i) => ({ fg, bg: CHARTS[i + 1] ?? "", min: MARK })),
-  // Treemap labels on every heat step (lib/treemap.ts heatFill): 12% to 60% of
-  // the meaning colour in the card in light, 25% to 60% in dark.
-  ...heatLabels("light", [12, 24, 36, 48, 60]),
-  ...heatLabels("dark", [25, 33.75, 42.5, 51.25, 60]),
+  // A waterfall's rise and fall: the full-colour edge against the tint it
+  // encloses, on the bar and its legend chip; and every bar colour against the
+  // 40% muted band a chart card lays behind a hovered category (lib/chart-frame).
+  ...["positive", "negative"].map((side) => ({ fg: side, bg: `${side}@35`, min: MARK })),
+  ...[...CHARTS, "positive", "negative"].map((fg) => ({ fg, bg: "muted/40", min: MARK, surface: "card" })),
+  // A chart card's footer text, on the footer's muted wash.
+  { fg: "foreground", bg: "muted/50", min: TEXT },
+  // Treemap, ChangeGrid and signed-calendar labels on every heat step
+  // (lib/heat.ts heatFill), at the theme's own --heat-N shares. A ChangeGrid
+  // cell with no change is muted, with its figure in the text colour.
+  { fg: "foreground", bg: "muted", min: TEXT },
+  ...HEAT_LABELS,
 ];
 
 /**
@@ -115,6 +128,12 @@ export function checkContrast(theme) {
   /** @type {Map<string, Check>} */
   const checks = new Map();
   for (const scheme of /** @type {const} */ (["light", "dark"])) {
+    const percentage = (/** @type {string} */ name) => {
+      const value = theme[scheme][name];
+      const match = value === undefined ? null : /^([\d.]+)%$/.exec(value);
+      if (!match) throw new Error(`${scheme}: --${name} is "${value}", not a percentage`);
+      return Number(match[1]);
+    };
     const token = (/** @type {string} */ name) => {
       const value = theme[scheme][name];
       if (value === undefined) throw new Error(`${scheme}: --${name} is not set in the ${scheme} block`);
@@ -127,11 +146,13 @@ export function checkContrast(theme) {
      * @param {Paint} paint @param {{ rgb: [number, number, number], name: string }} under
      */
     const paintOver = (paint, under) => {
-      const [, name = "", sep, amount] = /^([\w-]+)(?:([/@])([\d.]+))?$/.exec(paint) ?? [];
+      const [, name = "", sep, amount = ""] = /^([\w-]+)(?:([/@])([\w.-]+))?$/.exec(paint) ?? [];
       const base = token(name);
       if (sep === "@") {
-        const rgb = oklchToSrgb(mixOklab(base, token("card"), Number(amount) / 100));
-        return { rgb, name: `--${name} ${amount}% in --card` };
+        // A share is a number, or the name of a theme token holding a percentage, such as heat-5.
+        const share = /^[\d.]+$/.test(amount) ? Number(amount) : percentage(amount);
+        const rgb = oklchToSrgb(mixOklab(base, token("card"), share / 100));
+        return { rgb, name: `--${name} ${share}% in --card` };
       }
       const alpha = base.alpha * (sep === "/" ? Number(amount) / 100 : 1);
       if (alpha === 1) return { rgb: oklchToSrgb(base), name: `--${paint}` };
@@ -140,6 +161,7 @@ export function checkContrast(theme) {
     for (const pair of PAIRS) {
       if (pair.scheme && pair.scheme !== scheme) continue;
       for (const surface of SURFACES) {
+        if (pair.surface && pair.surface !== surface) continue;
         const page = { rgb: oklchToSrgb(token(surface)), name: `--${surface}` };
         const bg = pair.bg ? paintOver(pair.bg, page) : page;
         const fg = paintOver(pair.fg, bg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siyahi/tools",
-  "version": "0.1.9-next.24",
+  "version": "0.1.9-next.25",
   "description": "Checks and build helpers for Siyahi pages: a lint plugin, a font preload plugin, a theme contrast check, and screenshot and layout shift scripts.",
   "homepage": "https://siyahi.jatinbansal.com",
   "license": "MIT",

package/types/contrast.d.mts

@@ -17,6 +17,7 @@ export type Pair = {
     bg: Paint;
     min: number;
     scheme?: Scheme;
+    surface?: "background" | "card";
 };
 /**
  * @param {Theme} theme