@siyahi/tools 0.1.9-next.27 → 0.1.9-next.29

package/README.md

@@ -97,7 +97,7 @@ counted (`moved=` against `in-view=`) and listed, but do not fail it. Run `npx p
 ## siyahi-shots
 
 ```sh
-npx siyahi-shots http://localhost:5173/#/page [more URLs] [--out shots] [--gutter 16] [--font Geist] [--chrome '[data-slot="sidebar"]'] [--wait-for h1] [--report] [--widths 1920,390]
+npx siyahi-shots http://localhost:5173/#/page [more URLs] [--out shots] [--gutter 16] [--font Geist] [--chrome '[data-slot="sidebar"]'] [--wait-for h1] [--report] [--widths 1920,390] [--script probe.mjs]
 ```
 
 Renders each URL in Chromium at 1920 and 390 pixels wide, light and dark, and
@@ -129,9 +129,33 @@ for other pages. Run `npx playwright install chromium` once.
 
 Pass `--widths 320,390,768,1366,1920` to include small phones, tablets and laptops;
 each width runs in light and dark. The check also rejects a scrolling table whose
-frozen columns occupy more than half its available width. These captures
-complement interaction checks for scrolling, state retention, keyboard navigation
-and touch readouts.
+frozen columns occupy more than half its available width.
+
+A page error or a console error, such as a failed request, fails the mode and is
+printed under it.
+
+To check a control, hover or tooltip, pass `--script` a module whose default
+export takes Playwright's `page` and the mode (`{ name, width, height, dark }`).
+It runs in every mode once the page is ready, at the mode's screen size; whatever
+it returns is printed as `data=<JSON>` under the mode, and the checks measure the
+page as the script left it. The full-page shot is taken after the viewport grows
+to the page's height, which can undo a hover or close a tooltip, so take the
+picture of an interaction inside the script, in the state it made. A locator's
+`screenshot` gives just the card:
+
+```js
+// hover.mjs: the tooltip of a chart's first bar, as text and as a picture
+export default async (page, mode) => {
+  const card = page.locator('[data-slot="card"]', { hasText: "Revenue by channel" });
+  await card.locator(".recharts-bar-rectangle").first().hover();
+  await card.screenshot({ path: `shots/hover-${mode.name}.png` });
+  return (await card.locator(".recharts-tooltip-wrapper").innerText()).split("\n");
+};
+```
+
+```sh
+npx siyahi-shots http://localhost:4173/#/data/bar-chart --script hover.mjs
+```
 
 ## siyahi-contrast
 

package/contrast.mjs

@@ -23,13 +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; `positive@heat-5` takes the share from the theme's --heat-5.
+ * a treemap tile; `positive@heat-5` and `negative/wash` take the share from the
+ * theme's --heat-5 or --wash.
  * @typedef {string} Paint
  */
 /**
  * `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
+ * hover band. A list of paints for `bg` lays each over the one before, such as a footer band over an exception's wash.
+ * @typedef {{ fg: Paint, bg: Paint | Paint[], min: number, scheme?: Scheme, surface?: "background" | "card" }} Pair
  */
 
 const TEXT = 4.5;
@@ -103,6 +104,29 @@ const PAIRS = [
   // 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 })),
+  // An exception the page marks, washed in its tone at the theme's --wash. A
+  // stat tile mixes the tone into the card, opaque (`@wash`); a table row lays
+  // it over what is under it (`/wash`). On either: text, muted lines, a Delta
+  // icon and --chart-1 (a tile's Sparkline, a row's DataBar; a run of gains or
+  // losses takes --positive or --negative, as the SectionCards rule says). A
+  // tile's footer band sits over its wash, and a StatusBadge's dot on its own
+  // wash over a row's.
+  ...["negative@wash", "negative/wash", "warning@wash", "warning/wash"].flatMap((wash) => [
+    { fg: "foreground", bg: wash, min: TEXT },
+    { fg: "muted-foreground", bg: wash, min: TEXT },
+    { fg: "positive", bg: wash, min: MARK },
+    { fg: "negative", bg: wash, min: MARK },
+    { fg: "chart-1", bg: wash, min: MARK },
+  ]),
+  ...["negative", "warning"].map((tone) => ({
+    fg: "muted-foreground",
+    bg: [`${tone}@wash`, "muted/50"],
+    min: TEXT,
+  })),
+  ...[
+    ["negative", ["negative/wash", "negative/8"]],
+    ["warning", ["warning/wash", "warning/10"]],
+  ].map(([fg, bg]) => ({ fg: String(fg), bg: /** @type {Paint[]} */ (bg), 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
@@ -151,13 +175,13 @@ export function checkContrast(theme) {
     const paintOver = (paint, under) => {
       const [, name = "", sep, amount = ""] = /^([\w-]+)(?:([/@])([\w.-]+))?$/.exec(paint) ?? [];
       const base = token(name);
+      // 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) : sep ? percentage(amount) : 100;
       if (sep === "@") {
-        // 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);
+      const alpha = (base.alpha * share) / 100;
       if (alpha === 1) return { rgb: oklchToSrgb(base), name: `--${paint}` };
       return { rgb: over({ ...base, alpha }, under.rgb), name: `--${paint} over ${under.name}` };
     };
@@ -166,7 +190,7 @@ export function checkContrast(theme) {
       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 bg = [pair.bg].flat().reduce((under, paint) => (paint ? paintOver(paint, under) : under), page);
         const fg = paintOver(pair.fg, bg);
         const [fgHex, bgHex] = [srgbHex(fg.rgb), srgbHex(bg.rgb)];
         const ratio = contrastSrgb(fg.rgb, bg.rgb);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siyahi/tools",
-  "version": "0.1.9-next.27",
+  "version": "0.1.9-next.29",
   "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/shots.mjs

@@ -7,6 +7,16 @@
 //
 //   siyahi-shots <url>... [--out shots] [--gutter 16] [--font Geist]
 //                [--chrome '[data-slot="sidebar"]'] [--wait-for h1] [--report]
+//                [--widths 1920,390] [--script probe.mjs]
+//
+// --script names a module whose default export, async (page, mode) => data,
+// runs in every mode once the page is ready, at the mode's screen size: it
+// clicks, hovers or types with Playwright's page, and whatever it returns is
+// printed as JSON. The checks then measure the page as the script left it. The
+// full-page shot comes after the viewport grows to the page's height, which can
+// undo a hover, so a script takes its own picture of an interaction, in the
+// state it made: await card.screenshot({ path: `hover-${mode.name}.png` }).
+// A page error or console error fails the mode, with or without a script.
 //
 // Measures only once --wait-for (by default the page's h1) is visible, two
 // animation frames have passed and the fonts are ready: a page that renders
@@ -33,6 +43,7 @@
 import { mkdirSync, readdirSync, rmSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
+import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import { chromium, errors } from "playwright";
 
@@ -54,11 +65,12 @@ const { values, positionals } = parseArgs({
     "wait-for": { type: "string", default: "h1" },
     report: { type: "boolean", default: false },
     widths: { type: "string", default: "1920,390" },
+    script: { type: "string" },
   },
 });
 if (positionals.length === 0) {
   console.error(
-    "usage: siyahi-shots <url>... [--out shots] [--gutter 16] [--font Geist] [--chrome <selector>] [--wait-for <selector>] [--report] [--widths 1920,390]",
+    "usage: siyahi-shots <url>... [--out shots] [--gutter 16] [--font Geist] [--chrome <selector>] [--wait-for <selector>] [--report] [--widths 1920,390] [--script probe.mjs]",
   );
   process.exit(2);
 }
@@ -78,6 +90,23 @@ const MODES = [...new Set(widths)].flatMap((width) =>
   })),
 );
 const minGutter = Number(values.gutter);
+/**
+ * Loads --script's default export, or exits 2 before any browser starts, as for any other bad argument.
+ * @param {string} file
+ * @returns {Promise<(page: import("playwright").Page, mode: Mode) => Promise<unknown>>}
+ */
+async function loadScript(file) {
+  const module = await import(pathToFileURL(path.resolve(file)).href).catch((/** @type {Error} */ error) => {
+    console.error(`--script ${file} did not load: ${error.message}`);
+    process.exit(2);
+  });
+  if (typeof module.default !== "function") {
+    console.error(`--script ${file} must export a default async function (page, mode)`);
+    process.exit(2);
+  }
+  return module.default;
+}
+const act = values.script ? await loadScript(values.script) : undefined;
 const waitFor = values["wait-for"];
 mkdirSync(outDir, { recursive: true });
 
@@ -199,7 +228,7 @@ function clearShots(base) {
  * @param {import("playwright").Browser} browser
  * @param {string} url
  * @param {Mode} mode
- * @returns {Promise<{ probe: Probe, ready: boolean, height: number, files: string[] }>}
+ * @returns {Promise<{ probe: Probe, ready: boolean, height: number, files: string[], data: unknown, browserErrors: string[] }>}
  */
 async function shoot(browser, url, mode) {
   const context = await browser.newContext({
@@ -207,6 +236,12 @@ async function shoot(browser, url, mode) {
     colorScheme: mode.dark ? "dark" : "light",
   });
   const page = await context.newPage();
+  /** @type {string[]} */
+  const browserErrors = [];
+  page.on("pageerror", (error) => browserErrors.push(`page error: ${error.message}`));
+  page.on("console", (message) => {
+    if (message.type() === "error") browserErrors.push(`console error: ${message.text()} (${message.location().url})`);
+  });
   await page.goto(url, { waitUntil: "networkidle" });
   const ready = await page.waitForSelector(waitFor, { timeout: WAIT_FOR_TIMEOUT }).then(
     () => true,
@@ -216,6 +251,8 @@ async function shoot(browser, url, mode) {
     },
   );
   await page.evaluate(SETTLE);
+  const data = act && (await act(page, mode));
+  if (act) await page.evaluate(SETTLE);
   /** @type {Probe} */
   const probe = await page.evaluate(PROBE);
   const height = Math.max(probe.docHeight, mode.height);
@@ -234,16 +271,17 @@ async function shoot(browser, url, mode) {
     files.push(file);
   }
   await context.close();
-  return { probe, ready, height, files };
+  return { probe, ready, height, files, data, browserErrors };
 }
 
 /**
  * @param {Probe} p
  * @param {boolean} ready whether --wait-for appeared
+ * @param {string[]} browserErrors
  * @returns {string[]}
  */
-function problemsOf(p, ready) {
-  const problems = [];
+function problemsOf(p, ready, browserErrors) {
+  const problems = [...browserErrors];
   if (!ready) problems.push(`nothing matching ${waitFor} appeared within ${WAIT_FOR_TIMEOUT / 1000}s (--wait-for)`);
   if (p.gutterLeft !== null && p.gutterLeft < minGutter)
     problems.push(`left gutter is ${p.gutterLeft}px, under ${minGutter}px`);
@@ -264,8 +302,8 @@ const browser = await chromium.launch();
 let failed = false;
 for (const url of positionals) {
   for (const mode of MODES) {
-    const { probe, ready, height, files } = await shoot(browser, url, mode);
-    const problems = problemsOf(probe, ready);
+    const { probe, ready, height, files, data, browserErrors } = await shoot(browser, url, mode);
+    const problems = problemsOf(probe, ready, browserErrors);
     failed ||= problems.length > 0;
     const font = values.report && !probe.fontLoaded ? `${probe.font} (report, system fallback allowed)` : probe.font;
     console.log(
@@ -273,6 +311,7 @@ for (const url of positionals) {
         `overflow=${probe.overflow}/${probe.overflowWithScrollbar} clipped=${probe.clipped.length} font=${font} h1=${JSON.stringify(probe.h1)} ` +
         `height=${height} ${files.join(" ")}`,
     );
+    if (data !== undefined) console.log(`     data=${JSON.stringify(data)}`);
     for (const problem of problems) console.log(`     ${problem}`);
   }
 }

package/types/contrast.d.mts

@@ -14,7 +14,7 @@ export type Check = {
 export type Paint = string;
 export type Pair = {
     fg: Paint;
-    bg: Paint;
+    bg: Paint | Paint[];
     min: number;
     scheme?: Scheme;
     surface?: "background" | "card";