@polyxd/verifier 0.2.2 → 0.4.0

package/NOTICE

@@ -135,6 +135,51 @@ Upstream: https://github.com/adobe/spectrum-tokens
 
 Vendored under `packages/ds-spectrum/scripts/sources/`, with the upstream licence file beside it.
 
+## Logos
+
+Twelve packs ship their design system's official logo, unaltered, as `logo.svg`
+(Bootstrap and Radix also ship the owner's white version as `logo-white.svg`),
+downloaded from the owner's own site, repository or brand page. Where a design
+system has no mark of its own (Polaris, Spectrum, Primer), the pack ships its
+company's logo. Each is used only to identify the design system a pack is
+modelled on, beside its name. The logos are trademarks of their owners, not
+Polyxd's, and are not covered by Polyxd's licence:
+
+- Material 3 (`@polyxd/ds-material3`) — Google LLC
+- Carbon (`@polyxd/ds-carbon`) — IBM Corp.
+- Fluent 2 (`@polyxd/ds-fluent`) — Microsoft Corporation
+- Polaris (`@polyxd/ds-polaris`) — the Shopify logo, Shopify Inc.
+- Spectrum 2 (`@polyxd/ds-spectrum`) — the Adobe logo, Adobe Inc.
+- Primer (`@polyxd/ds-primer`) — the GitHub logo, GitHub, Inc.
+- shadcn/ui (`@polyxd/ds-shadcn`) — shadcn
+- Ant Design (`@polyxd/ds-antd`) — Ant Group
+- Bootstrap (`@polyxd/ds-bootstrap`) — the Bootstrap team
+- Chakra UI (`@polyxd/ds-chakra`) — Chakra Systems Inc.
+- Mantine (`@polyxd/ds-mantine`) — Vitaly Rtishchev
+- Radix UI (`@polyxd/ds-radix`) — WorkOS
+
+Google, IBM, Microsoft, Shopify, Adobe and GitHub restrict the use of their
+logos without permission; each pack's manifest (`logo`) and README record the
+source and the owner's guidelines. GOV.UK's crown and logotype are protected and
+may not be used by a service that is not on GOV.UK, so `@polyxd/ds-govuk` ships
+no logo and is named in words only.
+
+The twelve template packs' `logo.svg` files are Polyxd's own marks, drawn from
+each template's tokens.
+
+## Template packs
+
+Twelve packs are original Polyxd templates, not readings of any design system:
+`@polyxd/ds-sketch`, `@polyxd/ds-wireframe`, `@polyxd/ds-editorial`,
+`@polyxd/ds-brutalist`, `@polyxd/ds-glass`, `@polyxd/ds-terminal`,
+`@polyxd/ds-pastel`, `@polyxd/ds-civic`, `@polyxd/ds-finance`,
+`@polyxd/ds-health`, `@polyxd/ds-neon` and `@polyxd/ds-mono`. Every value in
+them was chosen for the template, they vendor nothing, and they are Apache-2.0
+like the rest of Polyxd. The typefaces some of them name (Caveat, Patrick Hand,
+Fraunces, Nunito, JetBrains Mono, Space Grotesk) are under the SIL Open Font
+License and are loaded from Google Fonts by the page that uses them, never
+distributed here.
+
 ## Specification
 
 ### A2UI

package/README.md

@@ -3,11 +3,25 @@
 Scores a Polyxd UI document the way it will actually be used: rendered, in every design system, by people and by agents.
 
 ```bash
-npm install -D @polyxd/verifier
+npm install -D @polyxd/verifier playwright
 npx playwright install chromium    # once
 npx polyxd-verify my-ui.json --themes carbon --modes light --widths 390 --json report.json
 ```
 
+Playwright is an optional peer dependency: the rendered checks need it, so install it beside the verifier as above. Nothing loads it until a browser is launched, and without it `launch()` says what to install.
+
+## Document checks only
+
+`@polyxd/verifier/static` is the document checks on their own: `staticAudit(doc, { registry, rules, emphasisBudget, missingData })`. It imports no Playwright and reads no files (the spec's pattern checks are built into it), so it runs in Node, browsers and Workers, and installing the verifier for it alone doesn't pull in Playwright.
+
+```ts
+import { staticAudit } from "@polyxd/verifier/static";
+
+const findings = staticAudit(doc, { registry });
+```
+
+`@polyxd/runtime` uses it as its default checks, and `@polyxd/mcp` and `@polyxd/server` use it for their verify tools. `npm run build:patterns -w @polyxd/verifier` regenerates the pattern checks from the spec; a test fails when they are out of date.
+
 Inside the Polyxd repository, `npm run verify:examples -w @polyxd/verifier` runs every spec example through the full matrix with agent tasks.
 
 ## What it checks
@@ -21,6 +35,12 @@ Inside the Polyxd repository, `npm run verify:examples -w @polyxd/verifier` runs
 
 Default matrix: Material 3, Carbon and Ant Design × light and dark × 390px and 1100px.
 
+## Renderers
+
+The verifier renders through a **harness**: a page that draws `window.__PXD__ = { document, theme, mode }` into `#root` and records what the surface sends (`harness/README.md` is the contract). Two ship: the React renderer's (`harness/`) and the Web Components renderer's (`harness-web/`, `@polyxd/web`'s preview bundle). Pass any renderer's page as `verifyDocument(doc, { harness: { url } | { html } })`; `HARNESSES.react` and `HARNESSES.web` name the shipped ones.
+
+`npm run conformance -w @polyxd/verifier` renders every spec example and every demo document with both shipped renderers in 13 packs × light/dark × 390/1100 and compares the rendered fingerprint (`fingerprint: true` on `verifyDocument`: components in order, ARIA snapshot, visible text; `compareFingerprints` explains a difference), the findings and the agent tasks. Both must score 100 and the fingerprints must match.
+
 ## Score (v0)
 
 Start at 100. Each distinct failing error check costs 20, each distinct warning 4, and failed agent runs cost up to 40 in proportion. A document that fails the schema scores 0. The weights are a starting point; the gold set (`bench/gold`) exists to calibrate them against designers' rankings.

package/dist/browser.d.ts

@@ -1,16 +1,33 @@
-import { type Browser, type Page } from "playwright";
+import type { Browser, Page } from "playwright";
+/**
+ * A page that renders `window.__PXD__` (see harness/README.md): the built-in React harness, the
+ * Web Components harness, or any renderer's own page, by URL or as a directory of static files.
+ */
+export type RendererHarness = {
+    name?: string;
+    url: string;
+} | {
+    name?: string;
+    html: string | URL;
+};
+/** The harnesses this package ships, built by `npm run build:harness`. */
+export declare const HARNESSES: Record<"react" | "web", RendererHarness>;
 export interface RenderTarget {
     theme: string;
     mode: "light" | "dark";
     /** Viewport width in CSS pixels, e.g. 390 (phone) or 1100 (desktop) */
     width: number;
 }
+/**
+ * Starts headless Chromium for the rendered checks. Playwright is an optional peer dependency, so
+ * nothing loads it until now: the document checks (`@polyxd/verifier/static`) never need it.
+ */
 export declare function launch(): Promise<Browser>;
 /**
  * Opens a page with one document rendered in one theme/mode/width. The harness is served from
  * disk through request interception, so nothing listens on a port.
  */
-export declare function renderPage(browser: Browser, document: unknown, target: RenderTarget): Promise<{
+export declare function renderPage(browser: Browser, document: unknown, target: RenderTarget, harness?: RendererHarness): Promise<{
     page: Page;
     errors: string[];
 }>;

package/dist/browser.js

@@ -1,37 +1,70 @@
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { extname } from "node:path";
-import { chromium } from "playwright";
-const HARNESS = new URL("../harness-dist/", import.meta.url);
 const ORIGIN = "http://harness.polyxd.local";
+/** The harnesses this package ships, built by `npm run build:harness`. */
+export const HARNESSES = {
+    react: { name: "react", html: new URL("../harness-dist/index.html", import.meta.url) },
+    web: { name: "web", html: new URL("../harness-web-dist/index.html", import.meta.url) },
+};
 const TYPES = { ".html": "text/html", ".js": "text/javascript", ".css": "text/css", ".svg": "image/svg+xml" };
-const axeSource = readFile(createRequire(import.meta.url).resolve("axe-core/axe.min.js"), "utf8");
+let axeSource;
+const axe = () => (axeSource ??= readFile(createRequire(import.meta.url).resolve("axe-core/axe.min.js"), "utf8"));
+/**
+ * Starts headless Chromium for the rendered checks. Playwright is an optional peer dependency, so
+ * nothing loads it until now: the document checks (`@polyxd/verifier/static`) never need it.
+ */
 export async function launch() {
-    return chromium.launch();
+    let playwright;
+    try {
+        playwright = await import("playwright");
+    }
+    catch (err) {
+        if (err.code !== "ERR_MODULE_NOT_FOUND")
+            throw err;
+        throw new Error("The rendered checks need Playwright, which @polyxd/verifier doesn't install for you: run `npm install -D playwright && npx playwright install chromium`. The document checks alone are in @polyxd/verifier/static.");
+    }
+    return playwright.chromium.launch();
 }
 /**
  * Opens a page with one document rendered in one theme/mode/width. The harness is served from
  * disk through request interception, so nothing listens on a port.
  */
-export async function renderPage(browser, document, target) {
+export async function renderPage(browser, document, target, harness = HARNESSES.react) {
     const page = await browser.newPage({ viewport: { width: target.width, height: 900 }, reducedMotion: "reduce" });
     const errors = [];
     page.on("pageerror", (e) => errors.push(e.message));
     page.on("console", (m) => m.type() === "error" && errors.push(m.text()));
-    await page.route(`${ORIGIN}/**`, async (route) => {
-        const path = new URL(route.request().url()).pathname.slice(1) || "index.html";
-        try {
-            const body = await readFile(new URL(path, HARNESS));
-            await route.fulfill({ body, contentType: TYPES[extname(path)] ?? "application/octet-stream" });
-        }
-        catch {
-            await route.fulfill({ status: 404 });
-        }
-    });
+    let url;
+    if ("url" in harness)
+        url = harness.url;
+    else {
+        // A directory of static files is served from disk through request interception, so nothing listens on a port.
+        const index = harness.html instanceof URL ? harness.html : new URL(harness.html, `file://${process.cwd()}/`);
+        const dir = new URL("./", index);
+        await page.route(`${ORIGIN}/**`, async (route) => {
+            const path = new URL(route.request().url()).pathname.slice(1) || "index.html";
+            try {
+                const body = await readFile(new URL(path, dir));
+                await route.fulfill({ body, contentType: TYPES[extname(path)] ?? "application/octet-stream" });
+            }
+            catch {
+                await route.fulfill({ status: 404 });
+            }
+        });
+        url = `${ORIGIN}/${index.pathname.split("/").pop() ?? "index.html"}`;
+    }
     await page.addInitScript((cfg) => (window.__PXD__ = cfg), { document, theme: target.theme, mode: target.mode });
-    await page.goto(`${ORIGIN}/index.html`);
+    await page.goto(url);
     await page.waitForFunction(() => window.__pxdReady === true, undefined, { timeout: 10_000 });
-    await page.addScriptTag({ content: await axeSource });
+    // Entrances (a panel fading in) finish before anything is measured, so a contrast or layout
+    // reading never depends on how far into an animation a renderer's first paint was. Endless
+    // animations (a spinner) are left running.
+    await page.evaluate(() => {
+        const doc = globalThis.document;
+        return Promise.all(doc.getAnimations().filter((a) => a.effect?.getTiming().iterations !== Infinity).map((a) => a.finished.catch(() => undefined)));
+    });
+    await page.addScriptTag({ content: await axe() });
     return { page, errors };
 }
 /** Actions the rendered UI has sent to the host so far. */

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}

package/dist/fingerprint.d.ts

@@ -0,0 +1,19 @@
+import type { Page } from "playwright";
+/**
+ * What a rendered surface is, independent of who rendered it: the components in reading order,
+ * the accessibility tree (roles, names, states, in order) and the visible text. Two renderers
+ * are conformant when a document gives the same fingerprint in each, in every pack, mode and
+ * width. This is stricter than consistency.ts's signature, which reads the document; this
+ * reads the page.
+ */
+export interface Fingerprint {
+    /** [component id, component name] for every element a component rendered, in DOM order */
+    components: [string, string][];
+    /** Playwright's ARIA snapshot of the surface: roles and accessible names in reading order */
+    aria: string;
+    /** The surface's visible text, whitespace collapsed */
+    text: string;
+}
+export declare function renderedFingerprint(page: Page): Promise<Fingerprint>;
+/** The differences between two fingerprints, in words; empty when they match. */
+export declare function compareFingerprints(a: Fingerprint, b: Fingerprint, aName?: string, bName?: string): string[];

package/dist/fingerprint.js

@@ -0,0 +1,40 @@
+export async function renderedFingerprint(page) {
+    const surface = page.locator(".pxd-surface").first();
+    const [components, text] = await page.evaluate(() => {
+        const root = document.querySelector(".pxd-surface");
+        const components = [...root.querySelectorAll("[data-pxd-id]")].map((el) => [el.dataset.pxdId, el.dataset.pxdComponent ?? ""]);
+        return [components, root.innerText.replace(/\s+/g, " ").trim()];
+    });
+    const aria = normaliseAria(await surface.ariaSnapshot());
+    return { components, aria, text };
+}
+/** Generated ids differ per renderer (React's :r1:, the Web renderer's pxd-…); they name nothing a person sees. */
+function normaliseAria(snapshot) {
+    return snapshot
+        .split("\n")
+        .map((l) => l.replace(/\s+$/, "").replace(/^(\s*- \/url: ")#[^"]*"$/, "$1#id\""))
+        .join("\n");
+}
+/** The differences between two fingerprints, in words; empty when they match. */
+export function compareFingerprints(a, b, aName = "react", bName = "web") {
+    const out = [];
+    if (a.components.length !== b.components.length || a.components.some(([id, c], i) => b.components[i]?.[0] !== id || b.components[i]?.[1] !== c)) {
+        const first = a.components.findIndex(([id, c], i) => b.components[i]?.[0] !== id || b.components[i]?.[1] !== c);
+        const at = first < 0 ? a.components.length : first;
+        out.push(`components differ at #${at}: ${aName} ${JSON.stringify(a.components[at])} vs ${bName} ${JSON.stringify(b.components[at])} (${a.components.length} vs ${b.components.length})`);
+    }
+    if (a.aria !== b.aria) {
+        const al = a.aria.split("\n");
+        const bl = b.aria.split("\n");
+        const i = al.findIndex((l, n) => bl[n] !== l);
+        out.push(`aria differs at line ${i + 1}:\n      ${aName}: ${al[i] ?? "(end)"}\n      ${bName}: ${bl[i] ?? "(end)"}`);
+    }
+    if (a.text !== b.text) {
+        let i = 0;
+        while (i < a.text.length && a.text[i] === b.text[i])
+            i++;
+        out.push(`text differs at ${i}: ${aName} "…${a.text.slice(Math.max(0, i - 30), i + 40)}" vs ${bName} "…${b.text.slice(Math.max(0, i - 30), i + 40)}"`);
+    }
+    return out;
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAkBA,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAAU;IAClD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,CAAC;IACrD,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;QAClD,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAc,cAAc,CAAE,CAAC;QAClE,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,gBAAgB,CAAc,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,KAAM,EAAE,EAAE,CAAC,OAAO,CAAC,YAAY,IAAI,EAAE,CAAqB,CAAC,CAAC;QAChK,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACzD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,mHAAmH;AACnH,SAAS,aAAa,CAAC,QAAgB;IACrC,OAAO,QAAQ;SACZ,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,0BAA0B,EAAE,SAAS,CAAC,CAAC;SAChF,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CAAC,CAAc,EAAE,CAAc,EAAE,KAAK,GAAG,OAAO,EAAE,KAAK,GAAG,KAAK;IAChG,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,UAAU,CAAC,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAChJ,MAAM,KAAK,GAAG,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAChH,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;QACnD,GAAG,CAAC,IAAI,CAAC,yBAAyB,EAAE,KAAK,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,MAAM,OAAO,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3L,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9C,GAAG,CAAC,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,WAAW,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;IACvH,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACtB,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,CAAC,EAAE,CAAC;QACzD,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IACzJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export { staticAudit, type StaticOptions } from "./static.ts";
 export { axeAudit, layoutAudit, type Finding } from "./rendered.ts";
 export { runTask, type Task, type Step, type AgentResult } from "./agent.ts";
 export { compare, signature, type Consistency } from "./consistency.ts";
-export { launch, renderPage, type RenderTarget } from "./browser.ts";
+export { launch, renderPage, HARNESSES, type RenderTarget, type RendererHarness } from "./browser.ts";
+export { renderedFingerprint, compareFingerprints, type Fingerprint } from "./fingerprint.ts";
 export { rewardFor, wiredCapabilities, probeActionable, coverageOf, type Reward, type RequestExpectation } from "./reward.ts";

package/dist/index.js

@@ -3,6 +3,7 @@ export { staticAudit } from "./static.js";
 export { axeAudit, layoutAudit } from "./rendered.js";
 export { runTask } from "./agent.js";
 export { compare, signature } from "./consistency.js";
-export { launch, renderPage } from "./browser.js";
+export { launch, renderPage, HARNESSES } from "./browser.js";
+export { renderedFingerprint, compareFingerprints } from "./fingerprint.js";
 export { rewardFor, wiredCapabilities, probeActionable, coverageOf } from "./reward.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAsD,MAAM,aAAa,CAAC;AAClH,OAAO,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAgB,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,OAAO,EAA0C,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,SAAS,EAAoB,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAqB,MAAM,cAAc,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAwC,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAsD,MAAM,aAAa,CAAC;AAClH,OAAO,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAgB,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,OAAO,EAA0C,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,SAAS,EAAoB,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAA2C,MAAM,cAAc,CAAC;AACtG,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAoB,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAwC,MAAM,aAAa,CAAC"}

package/dist/patterns.generated.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "@polyxd/spec/patterns";
+/** Each spec pattern's checks, by pattern id. */
+export declare const PATTERN_CHECKS: Record<string, Rule[]>;

package/dist/patterns.generated.js

@@ -0,0 +1,312 @@
+/** Each spec pattern's checks, by pattern id. */
+export const PATTERN_CHECKS = {
+    "compare-and-choose": [
+        {
+            "id": "one-comparison",
+            "description": "Exactly one Comparison",
+            "severity": "error",
+            "rule": {
+                "check": "contains",
+                "component": "Comparison",
+                "min": 1,
+                "max": 1
+            }
+        },
+        {
+            "id": "can-choose",
+            "description": "Each option can be chosen",
+            "severity": "error",
+            "rule": {
+                "check": "requires",
+                "component": "Comparison",
+                "props": [
+                    "choose"
+                ]
+            }
+        },
+        {
+            "id": "explains",
+            "description": "A one-line summary or the recommendation's reason helps the decision",
+            "severity": "warning",
+            "rule": {
+                "check": "anyOf",
+                "checks": [
+                    {
+                        "check": "requires",
+                        "component": "Comparison",
+                        "props": [
+                            "summary"
+                        ]
+                    },
+                    {
+                        "check": "requires",
+                        "component": "Comparison",
+                        "props": [
+                            "recommendedReason"
+                        ]
+                    }
+                ]
+            }
+        }
+    ],
+    "confirm-destructive": [
+        {
+            "id": "root-is-confirm",
+            "description": "The surface is a confirmation dialog",
+            "severity": "error",
+            "rule": {
+                "check": "rootIs",
+                "components": [
+                    "Confirm"
+                ]
+            }
+        },
+        {
+            "id": "states-consequence",
+            "description": "It says what will happen and whether it can be undone",
+            "severity": "error",
+            "rule": {
+                "check": "requires",
+                "component": "Confirm",
+                "props": [
+                    "consequence"
+                ]
+            }
+        },
+        {
+            "id": "specific-confirm-label",
+            "description": "The confirm button says what it does, never just 'OK' or 'Yes'",
+            "severity": "error",
+            "rule": {
+                "check": "noLabelMatches",
+                "pattern": "^(OK|Ok|Yes|Confirm|Submit|Done)$"
+            }
+        },
+        {
+            "id": "typed-for-destructive",
+            "description": "Irreversible, high-impact deletions ask the user to type a confirmation",
+            "severity": "warning",
+            "rule": {
+                "check": "requires",
+                "component": "Confirm",
+                "where": {
+                    "severity": "destructive"
+                },
+                "props": [
+                    "typeToConfirm"
+                ]
+            }
+        }
+    ],
+    "filter-and-browse": [
+        {
+            "id": "has-results",
+            "description": "Results are shown as a Collection or Table",
+            "severity": "error",
+            "rule": {
+                "check": "anyOf",
+                "checks": [
+                    {
+                        "check": "contains",
+                        "component": "Collection"
+                    },
+                    {
+                        "check": "contains",
+                        "component": "Table"
+                    }
+                ]
+            }
+        },
+        {
+            "id": "filters-first",
+            "description": "Filters come before the results",
+            "severity": "error",
+            "rule": {
+                "check": "precedes",
+                "before": [
+                    "TextInput",
+                    "Choice",
+                    "RangeInput",
+                    "DateInput"
+                ],
+                "after": [
+                    "Collection",
+                    "Table"
+                ]
+            }
+        },
+        {
+            "id": "empty-state",
+            "description": "Empty results explain what to do",
+            "severity": "error",
+            "rule": {
+                "check": "allOf",
+                "checks": [
+                    {
+                        "check": "requires",
+                        "component": "Collection",
+                        "props": [
+                            "empty"
+                        ]
+                    },
+                    {
+                        "check": "requires",
+                        "component": "Table",
+                        "props": [
+                            "empty"
+                        ]
+                    }
+                ]
+            }
+        }
+    ],
+    "multi-step-form": [
+        {
+            "id": "form-or-steps",
+            "description": "Inputs are collected in a Form or in Steps",
+            "severity": "error",
+            "rule": {
+                "check": "anyOf",
+                "checks": [
+                    {
+                        "check": "contains",
+                        "component": "Form"
+                    },
+                    {
+                        "check": "contains",
+                        "component": "Steps"
+                    }
+                ]
+            }
+        },
+        {
+            "id": "short-views",
+            "description": "No more than 6 inputs are visible at once; longer tasks are split into steps",
+            "severity": "error",
+            "rule": {
+                "check": "maxInputsPerView",
+                "max": 6
+            }
+        },
+        {
+            "id": "specific-submit",
+            "description": "The submit button says what happens next",
+            "severity": "warning",
+            "rule": {
+                "check": "noLabelMatches",
+                "pattern": "^(OK|Ok|Yes|Confirm|Submit|Done)$"
+            }
+        }
+    ],
+    "review-and-submit": [
+        {
+            "id": "has-summary",
+            "description": "What will be submitted is shown as label/value pairs",
+            "severity": "error",
+            "rule": {
+                "check": "contains",
+                "component": "DetailList"
+            }
+        },
+        {
+            "id": "submits",
+            "description": "There is a way to submit",
+            "severity": "error",
+            "rule": {
+                "check": "anyOf",
+                "checks": [
+                    {
+                        "check": "contains",
+                        "component": "Form"
+                    },
+                    {
+                        "check": "contains",
+                        "component": "Steps"
+                    }
+                ]
+            }
+        },
+        {
+            "id": "summary-before-inputs",
+            "description": "Review content comes before any last inputs",
+            "severity": "warning",
+            "rule": {
+                "check": "anyOf",
+                "checks": [
+                    {
+                        "check": "not",
+                        "checks": [
+                            {
+                                "check": "contains",
+                                "component": "Toggle"
+                            }
+                        ]
+                    },
+                    {
+                        "check": "precedes",
+                        "before": [
+                            "DetailList"
+                        ],
+                        "after": [
+                            "Toggle"
+                        ]
+                    }
+                ]
+            }
+        },
+        {
+            "id": "commitment-label",
+            "description": "The submit label states the commitment, not 'Submit'",
+            "severity": "error",
+            "rule": {
+                "check": "noLabelMatches",
+                "pattern": "^(OK|Ok|Yes|Confirm|Submit|Done|Continue)$"
+            }
+        }
+    ],
+    "undo-over-confirm": [
+        {
+            "id": "has-undo-status",
+            "description": "An undo notice says what happened",
+            "severity": "error",
+            "rule": {
+                "check": "contains",
+                "component": "Status",
+                "where": {
+                    "kind": "undo"
+                },
+                "min": 1
+            }
+        },
+        {
+            "id": "undo-has-action",
+            "description": "The notice offers Undo",
+            "severity": "error",
+            "rule": {
+                "check": "requires",
+                "component": "Status",
+                "where": {
+                    "kind": "undo"
+                },
+                "props": [
+                    "action"
+                ]
+            }
+        },
+        {
+            "id": "no-confirm",
+            "description": "Nothing asks for confirmation first",
+            "severity": "warning",
+            "rule": {
+                "check": "not",
+                "checks": [
+                    {
+                        "check": "contains",
+                        "component": "Confirm"
+                    }
+                ]
+            }
+        }
+    ]
+};
+//# sourceMappingURL=patterns.generated.js.map