@siyahi/tools 0.1.9-next.26 → 0.1.9-next.28

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

@@ -90,6 +90,9 @@ const PAIRS = [
   ...["", "muted", "muted/50"].map((bg) => ({ fg: "input", bg, min: MARK })),
   { fg: "input", bg: "input/30", min: MARK, scheme: "dark" },
   ...["ring", "destructive"].map((fg) => ({ fg, bg: "", min: MARK })),
+  // A toggle's focus ring also meets the button it rings: a selected one's
+  // foreground fill, or a hovered one's muted fill.
+  ...["foreground", "muted"].map((bg) => ({ fg: "ring", bg, min: MARK })),
   // A tone's icon or StatusBadge dot against the tone's own wash (lib/tone.ts).
   ...[
     ["link", "chart-1/8"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siyahi/tools",
-  "version": "0.1.9-next.26",
+  "version": "0.1.9-next.28",
   "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}`);
   }
 }