@miragon/pulse-widget-shell 0.0.0-bootstrap.0 → 0.21.0

package/dist/testing/colors.js

@@ -0,0 +1,124 @@
+import { readFileSync } from "node:fs";
+import { lineOf, literalText, parseSource, relativePath, sourceFiles, walkNodes, } from "./source-scan.js";
+/**
+ * The colour gate (CLAUDE.md "Design-System", invariant 6; brand-review B1):
+ * components use role names only (`text-danger-ink`, `bg-info-soft`,
+ * `border-focus` …), never Tailwind palette classes or raw colours, so a
+ * brand changes in the theme, not in every widget. brand-lint cannot see
+ * either inside `.ts`/`.tsx` (it checks colours, not Tailwind classes, and
+ * no TS strings), so every widget package runs this in its own tests:
+ *
+ *   expect(scanColors(widgetsDir, { allow: { "x.ts": "why" } })).toEqual([])
+ *
+ * It reads string and template literals (class lists, inline styles), never
+ * comments or visible JSX text. It also fails the retired accents, as a
+ * class (`text-m-blue`, `bg-critical-soft` …) and as a variable reference
+ * (`text-[var(--m-blue)]`, `{ color: "var(--critical)" }`): their variables
+ * left with the Miragon theme, so either would now style nothing — silently.
+ *
+ * Stylesheets get the same rule through {@link stylesheetColorFindings}: a
+ * consumer's CSS overrides role variables on top of the toolkit's theme and
+ * names no raw colour outside comments.
+ */
+const PALETTE = "slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose";
+const UTILITY = "bg|text|border|ring|outline|fill|stroke|from|via|to|divide|decoration|accent|caret|placeholder|shadow|inset-shadow|inset-ring";
+/** `text-red-600`, `hover:bg-purple-500/40`, `border-t-amber-300`, `bg-black/50`. */
+const PALETTE_CLASS = new RegExp(`(?<![\\w-])(?:${UTILITY})(?:-[a-z]+)?-(?:(?:${PALETTE})-(?:50|[1-9]00|950)|black|white)(?![\\w-])`, "g");
+/**
+ * The accent classes the Miragon theme retired (`--m-blue*`, `--m-green*`,
+ * the `critical` tone): `text-m-blue`, `bg-m-blue-soft`, `border-critical`.
+ * Use the roles instead (`text-link`, `bg-accent`, `danger`).
+ */
+const RETIRED_ROLE_CLASS = new RegExp(`(?<![\\w-])(?:${UTILITY})(?:-[a-z]+)?-(?:m-(?:blue|green)(?:-(?:light|soft))?|critical(?:-(?:soft|ink))?)(?![\\w-])`, "g");
+/**
+ * The same retired accents referenced as a variable: in an arbitrary value
+ * (`text-[var(--m-blue)]`, `border-[color:var(--critical)]`), an inline style
+ * (`{ color: "var(--m-blue)" }`) or through Tailwind's registration
+ * (`var(--color-m-blue-soft)`). The variable no longer exists, so the colour
+ * falls back to the inherited or initial value without a build error.
+ */
+const RETIRED_ROLE_VARIABLE = /(?<![\w-])--(?:color-)?(?:m-(?:blue|green)(?:-(?:light|soft))?|critical(?:-(?:soft|ink))?)(?![\w-])/g;
+/** `#fff`, `#1b3b6f80` (3, 4, 6 or 8 hex digits, never part of an id like `#root`). */
+const HEX = /(?<![\w&#])#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})(?![\w-])/g;
+/** `rgba(`, `oklch(`, `hsl(`, `color(` … (`color-mix(` over role variables stays allowed). */
+const COLOR_FUNCTION = /(?<![\w-])(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\(/g;
+/** Every palette class and raw colour in the string and template literals of one source file. */
+export function colorFindings(source, file) {
+    const sf = parseSource(source, file);
+    const findings = [];
+    walkNodes(sf, (node) => {
+        const text = literalText(node);
+        if (text === undefined)
+            return;
+        const matches = [PALETTE_CLASS, RETIRED_ROLE_CLASS, RETIRED_ROLE_VARIABLE, HEX, COLOR_FUNCTION]
+            .flatMap((pattern) => [...text.matchAll(pattern)])
+            .sort((a, b) => a.index - b.index);
+        for (const [match] of matches) {
+            findings.push({ file, line: lineOf(sf, node), match, text: text.trim().slice(0, 80) });
+        }
+    });
+    return findings;
+}
+/**
+ * A stylesheet with its comments blanked out, newlines kept (so line numbers
+ * stay true). A linear scan, not a lazy regex: it reads consumer stylesheets.
+ */
+function blankComments(css) {
+    let out = "";
+    let at = 0;
+    for (;;) {
+        const open = css.indexOf("/*", at);
+        if (open === -1)
+            return out + css.slice(at);
+        out += css.slice(at, open);
+        const close = css.indexOf("*/", open + 2);
+        const end = close === -1 ? css.length : close + 2;
+        out += css.slice(open, end).replace(/[^\n]/g, " ");
+        if (close === -1)
+            return out;
+        at = end;
+    }
+}
+/**
+ * Every raw colour (hex, `rgb()`, `oklch()` …) and every reference to a
+ * retired accent variable (`var(--m-blue)`) in a stylesheet's rules —
+ * comments are skipped, so a commented-out example may hold the values a
+ * customer is meant to fill in. A consumer stylesheet imports the toolkit's
+ * theme and overrides role variables; a brand value it does set belongs in
+ * that override block and its own allowance, never in a component rule.
+ */
+export function stylesheetColorFindings(css, file) {
+    const rules = blankComments(css);
+    const findings = [];
+    const lines = rules.split("\n");
+    lines.forEach((text, index) => {
+        const matches = [RETIRED_ROLE_VARIABLE, HEX, COLOR_FUNCTION]
+            .flatMap((pattern) => [...text.matchAll(pattern)])
+            .sort((a, b) => a.index - b.index);
+        for (const [match] of matches) {
+            findings.push({ file, line: index + 1, match, text: text.trim().slice(0, 80) });
+        }
+    });
+    return findings;
+}
+/**
+ * Scan every `.ts`/`.tsx` source under `dir` (tests and declarations
+ * excluded) for palette classes and raw colours. Findings carry
+ * "/"-separated paths relative to `dir`.
+ */
+export function scanColors(dir, options = {}) {
+    const allow = options.allow ?? {};
+    for (const [file, reason] of Object.entries(allow)) {
+        if (!reason.trim())
+            throw new Error(`The allowance for ${file} needs a reason`);
+    }
+    const perFile = sourceFiles(dir).map((path) => {
+        const file = relativePath(dir, path);
+        return { file, findings: colorFindings(readFileSync(path, "utf8"), file) };
+    });
+    const unused = Object.entries(allow)
+        .filter(([file]) => !perFile.some((f) => f.file === file && f.findings.length > 0))
+        .map(([file, reason]) => ({ file, line: 0, match: "unused allowance", text: reason }));
+    return [...perFile.filter((f) => !(f.file in allow)).flatMap((f) => f.findings), ...unused];
+}
+//# sourceMappingURL=colors.js.map

package/dist/testing/colors.js.map

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

package/dist/testing/colors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=colors.test.d.ts.map

package/dist/testing/colors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.test.d.ts","sourceRoot":"","sources":["../../src/testing/colors.test.ts"],"names":[],"mappings":""}

package/dist/testing/colors.test.js

@@ -0,0 +1,166 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { colorFindings, scanColors, stylesheetColorFindings } from "./colors.js";
+// Raw colours and palette classes are the test data here (closed at the end).
+/* brand-lint-disable */
+const found = (source, file = "w.tsx") => colorFindings(source, file).map((f) => `${f.line}:${f.match}`);
+describe("colorFindings — role names only, never palette classes or raw colours", () => {
+    it("finds Tailwind palette utilities in class strings, variants and templates included", () => {
+        const source = [
+            'export const a = <span className="text-red-600 font-bold">x</span>',
+            'export const b = cn("rounded", ok && "hover:bg-purple-500/40")',
+            "export const c = `border-t-amber-300 ${x} ring-offset-sky-950`",
+            'export const d = { dot: "bg-emerald-500", edge: "dark:border-zinc-700" }',
+            'export const e = "bg-black/50 text-white"',
+            'export const f = "from-indigo-50 via-pink-100 to-rose-900 fill-teal-400 stroke-cyan-200"',
+        ].join("\n");
+        expect(found(source)).toEqual([
+            "1:text-red-600",
+            "2:bg-purple-500",
+            "3:border-t-amber-300",
+            "3:ring-offset-sky-950",
+            "4:bg-emerald-500",
+            "4:border-zinc-700",
+            "5:bg-black",
+            "5:text-white",
+            "6:from-indigo-50",
+            "6:via-pink-100",
+            "6:to-rose-900",
+            "6:fill-teal-400",
+            "6:stroke-cyan-200",
+        ]);
+    });
+    it("finds raw colours: hex, colour functions and arbitrary values", () => {
+        const source = [
+            'export const a = { color: "#fff", background: "#1b3b6f80" }',
+            'export const b = "rgba(0, 0, 255, 0.5)"',
+            'export const c = "oklch(0.7 0.19 22.2)"',
+            'export const d = "bg-[#123456] text-[hsl(0_0%_50%)]"',
+            'export const e = "color(display-p3 1 0 0)"',
+        ].join("\n");
+        expect(found(source)).toEqual([
+            "1:#fff",
+            "1:#1b3b6f80",
+            "2:rgba(",
+            "3:oklch(",
+            "4:#123456",
+            "4:hsl(",
+            "5:color(",
+        ]);
+    });
+    it("finds the accent classes the Miragon theme retired (they would style nothing)", () => {
+        const source = [
+            'export const a = "bg-m-blue-soft text-m-blue font-semibold"',
+            'export const b = "hover:text-m-blue-light border-m-green bg-m-green-soft"',
+            'export const c = "text-critical bg-critical-soft"',
+        ].join("\n");
+        expect(found(source)).toEqual([
+            "1:bg-m-blue-soft",
+            "1:text-m-blue",
+            "2:text-m-blue-light",
+            "2:border-m-green",
+            "2:bg-m-green-soft",
+            "3:text-critical",
+            "3:bg-critical-soft",
+        ]);
+        expect(found('export const ok = "bg-accent text-accent-foreground text-link text-danger-ink"')).toEqual([]);
+    });
+    it("finds the retired accents referenced as a variable: arbitrary values and inline styles", () => {
+        const source = [
+            'export const a = "text-[var(--m-blue)] border-[color:var(--critical)]"',
+            'export const b = { color: "var(--m-blue-light)", background: "var(--m-green-soft)" }',
+            "export const c = `bg-[var(--color-m-blue-soft)] text-[var(--critical-ink)]`",
+        ].join("\n");
+        expect(found(source)).toEqual([
+            "1:--m-blue",
+            "1:--critical",
+            "2:--m-blue-light",
+            "2:--m-green-soft",
+            "3:--color-m-blue-soft",
+            "3:--critical-ink",
+        ]);
+        // Role variables, and names that merely start like a retired one, stay allowed.
+        expect(found('export const ok = "text-[var(--link)] bg-[var(--accent)] [--critical-path:1] var(--m-blueprint)"')).toEqual([]);
+    });
+    it("leaves role classes, role variables, comments and visible text alone", () => {
+        const source = [
+            "// text-red-600 and #fff in a comment",
+            'export const a = "bg-danger-soft text-foreground border-danger ring-focus text-link"',
+            'export const b = "text-muted-foreground bg-card border-border bg-info-soft"',
+            'export const c = "color-mix(in oklab, var(--danger) 20%, transparent)"',
+            'export const d = "bg-[var(--scrim)] text-red-flag gray-500"',
+            "export const e = <p>Issue #123 is fixed, rgb is a word</p>",
+            'export const f = "#root, #main-content, #a1b2c3d4e5"',
+            'export const g = "text-xs text-2xl border-2 ring-1 to-transparent from-50%"',
+        ].join("\n");
+        expect(found(source)).toEqual([]);
+    });
+});
+describe("stylesheetColorFindings — a consumer stylesheet names no raw colour", () => {
+    it("finds hex and colour functions in rules, with their line", () => {
+        const css = [
+            '@import "@miragon/mcp-toolkit-ui/theme.css";',
+            ":root {",
+            "  --primary: #0055aa;",
+            "  --scrim: rgba(0, 0, 0, 0.4);",
+            "}",
+            ".dark { --link: oklch(0.7 0.1 250); }",
+        ].join("\n");
+        expect(stylesheetColorFindings(css, "brand.css").map((f) => `${f.line}:${f.match}`)).toEqual([
+            "3:#0055aa",
+            "4:rgba(",
+            "6:oklch(",
+        ]);
+    });
+    it("finds a reference to a retired accent variable in a rule", () => {
+        const css = [
+            "/* var(--m-blue) in a comment */",
+            ".selected { color: var(--m-blue); border-color: var(--color-critical-soft); }",
+        ].join("\n");
+        expect(stylesheetColorFindings(css, "globals.css").map((f) => `${f.line}:${f.match}`)).toEqual([
+            "2:--m-blue",
+            "2:--color-critical-soft",
+        ]);
+    });
+    it("skips comments (an example block) and role references", () => {
+        const css = [
+            "/*",
+            " * :root { --primary: #0055aa; }",
+            " */",
+            ":root { --link: var(--primary); --scrim: color-mix(in srgb, var(--cd-schwarz) 42%, transparent); }",
+            "#root { display: contents; }",
+        ].join("\n");
+        expect(stylesheetColorFindings(css, "brand.css")).toEqual([]);
+    });
+});
+describe("scanColors — a source tree with a reasoned allow list", () => {
+    const root = mkdtempSync(join(tmpdir(), "colors-"));
+    afterAll(() => rmSync(root, { recursive: true, force: true }));
+    mkdirSync(join(root, "ramp"));
+    writeFileSync(join(root, "a.tsx"), 'export const A = () => <b className="text-red-600">x</b>\n');
+    writeFileSync(join(root, "ramp", "heat.ts"), 'export const R = ["rgba(0, 0, 255, 0)"]\n');
+    writeFileSync(join(root, "clean.ts"), 'export const C = "bg-danger"\n');
+    writeFileSync(join(root, "a.test.tsx"), 'const t = "text-red-600"\n');
+    it("scans sources (tests skipped) and reports '/'-separated paths", () => {
+        expect(scanColors(root).map((f) => `${f.file}:${f.line}:${f.match}`)).toEqual([
+            "a.tsx:1:text-red-600",
+            "ramp/heat.ts:1:rgba(",
+        ]);
+    });
+    it("skips an allowed file and reports an allowance that no longer finds anything", () => {
+        expect(scanColors(root, { allow: { "ramp/heat.ts": "the heat ramp, until M5" } })).toEqual([
+            expect.objectContaining({ file: "a.tsx" }),
+        ]);
+        expect(scanColors(root, {
+            allow: { "a.tsx": "legacy", "ramp/heat.ts": "ramp", "clean.ts": "was red once" },
+        })).toEqual([{ file: "clean.ts", line: 0, match: "unused allowance", text: "was red once" }]);
+        expect(scanColors(root, { allow: { "a.tsx": "legacy", "ramp/heat.ts": "ramp", "gone.ts": "x" } })).toEqual([{ file: "gone.ts", line: 0, match: "unused allowance", text: "x" }]);
+    });
+    it("requires a reason for every allowance", () => {
+        expect(() => scanColors(root, { allow: { "a.tsx": "" } })).toThrow(/reason/);
+    });
+});
+/* brand-lint-enable */
+//# sourceMappingURL=colors.test.js.map

package/dist/testing/colors.test.js.map

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

package/dist/testing/contrast.d.ts

@@ -0,0 +1,77 @@
+/**
+ * WCAG contrast over the THEME as written: reads the custom properties a
+ * stylesheet declares for light (`:root`) and dark (`.dark` and the toolkit's
+ * other dark scopes), resolves `var()` chains, hex, `oklch()` and
+ * `color-mix()` the way the browser would, and measures text/background and
+ * non-text pairs in both modes. Built for tests
+ * (`@miragon/pulse-widget-shell/testing`): a brand override that drops a role
+ * below AA fails the suite that runs it, not a screenshot review.
+ */
+/**
+ * The theme every view ships, as the installed `@miragon/mcp-toolkit-ui`
+ * provides it: the vendored Miragon tokens (`cd-tokens.generated.css`,
+ * which `theme.css` imports first) and `theme.css` with its light and dark
+ * role layer. Pass it to {@link parseThemeVariables} first and a consumer's
+ * brand stylesheet after it:
+ *
+ *   parseThemeVariables(...toolkitThemeStylesheets(), brandCss)
+ */
+export declare function toolkitThemeStylesheets(): string[];
+export type ThemeMode = "light" | "dark";
+/** An sRGB colour with alpha, channels 0–1. */
+export interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** The custom properties of each mode, in cascade order (later wins). */
+export interface ThemeVariables {
+    light: Map<string, string>;
+    dark: Map<string, string>;
+}
+/**
+ * Collect the theme variables of one or more stylesheets the way an `<html>`
+ * element sees them. `@theme` blocks (Tailwind's `--color-*` registrations)
+ * sit in Tailwind's theme layer, below every unlayered rule; then the `:root`
+ * and `.dark` blocks of all stylesheets apply in source order. Light reads
+ * the `:root` blocks; dark (`html.dark`) reads `:root` AND `.dark`, so a later
+ * light-only `:root` override reaches dark too, exactly as in the browser.
+ */
+export declare function parseThemeVariables(...stylesheets: string[]): ThemeVariables;
+/**
+ * Resolve a CSS colour value against a mode's variables. Supports the
+ * shapes the theme uses: `var(--x[, fallback])`, `#rgb[a]`/`#rrggbb[aa]`,
+ * `oklch(L C H [/ A])`, `color-mix(in srgb|oklab, c1 [p%], c2 [q%])`,
+ * `transparent`, `white`, `black`. Anything else throws, so a theme that
+ * grows a new shape fails loudly instead of measuring garbage.
+ */
+export declare function resolveColor(value: string, vars: Map<string, string>, seen?: Set<string>): Rgba;
+/** `fg` painted over an opaque `bg`. */
+export declare function composite(fg: Rgba, bg: Rgba): Rgba;
+/** WCAG 2.x contrast ratio of two opaque colours. */
+export declare function contrastRatio(a: Rgba, b: Rgba): number;
+/**
+ * One measured pair. `fg` and `bg` are variable names (`--danger-ink`);
+ * a translucent `bg` is painted over `over` first (default `--card`), a
+ * translucent `fg` over the result.
+ */
+export interface ContrastPair {
+    label: string;
+    fg: string;
+    bg: string;
+    over?: string;
+    /** 4.5 for text, 3 for non-text (borders, dots, icons, focus rings). */
+    min: number;
+}
+export interface ContrastResult {
+    mode: ThemeMode;
+    label: string;
+    ratio: number;
+    min: number;
+}
+/** Measure every pair in both modes. */
+export declare function measureContrast(theme: ThemeVariables, pairs: readonly ContrastPair[]): ContrastResult[];
+/** The measured pairs that miss their minimum, as `mode: label` lines. */
+export declare function contrastFindings(theme: ThemeVariables, pairs: readonly ContrastPair[]): string[];
+//# sourceMappingURL=contrast.d.ts.map

package/dist/testing/contrast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contrast.d.ts","sourceRoot":"","sources":["../../src/testing/contrast.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAOlD;AAED,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAA;AAExC,+CAA+C;AAC/C,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1B,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC1B;AA8ID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,cAAc,CAmB5E;AAwID;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACzB,IAAI,cAAoB,GACvB,IAAI,CAUN;AAED,wCAAwC;AACxC,wBAAgB,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,IAAI,CAOlD;AAMD,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAGtD;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,wCAAwC;AACxC,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,cAAc,EAAE,CAalB;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,EAAE,CAIhG"}