automatica11y 0.3.3 → 0.4.0

package/src/globals.d.ts

@@ -2,6 +2,7 @@
 interface Window {
   __a11y: any;
   __a11yMeasure: any;
+  __a11yConditions: any;
   __vsr: any;
   __a11yClicks: number;
   __a11yLast: any;

package/src/harness/bundle.js

@@ -22,10 +22,12 @@ export function unresolvedPackages(errors) {
 /**
  * Bundle fixture entries into one folder of browser-ready ES modules, plus one HTML shell per entry.
  * esbuild loads here and only here. It doesn't type-check, and fixtures don't need it to.
- * @param {{ entries: Record<string, string>, outdir: string, workDir: string, react?: boolean }} options
+ * @param {{ entries: Record<string, string>, outdir: string, workDir: string, framework?: import("../frameworks/index.js").Adapter | null }} options
+ *   `framework` is the adapter whose bundle settings apply: which packages to keep to one copy, how JSX is turned into calls, and what to define.
  * @returns {Promise<Record<string, string>>} Entry name to page path, for example `{ dialog: "/dialog.html" }`.
  */
-export async function bundleEntries({ entries, outdir, workDir, react = false }) {
+export async function bundleEntries({ entries, outdir, workDir, framework = null }) {
+  const settings = framework?.bundle(workDir) ?? { alias: {}, esbuild: { jsx: "automatic" } };
   const esbuild = await import("esbuild");
   mkdirSync(outdir, { recursive: true });
   try {
@@ -36,13 +38,12 @@ export async function bundleEntries({ entries, outdir, workDir, react = false })
       format: "esm",
       platform: "browser",
       target: "es2022",
-      jsx: "automatic",
+      ...settings.esbuild,
       absWorkingDir: workDir,
       nodePaths: [join(workDir, "node_modules")],
-      // One copy of React for the library and the fixture, or hooks break.
-      alias: react ? { react: join(workDir, "node_modules", "react"), "react-dom": join(workDir, "node_modules", "react-dom") } : {},
+      alias: settings.alias,
       loader: ASSET_LOADERS,
-      define: { "process.env.NODE_ENV": '"development"' },
+      define: { "process.env.NODE_ENV": '"development"', ...(settings.define ?? {}) },
       logLevel: "silent",
     });
   } catch (error) {

package/src/harness/generate/dialects.js

@@ -0,0 +1,64 @@
+/**
+ * What differs between JSX frameworks when a fixture is generated: how it holds state, how it starts the marking code
+ * and wraps the result, and how a prop is spelled. The recipes in jsx-recipes.js are shared and ask the dialect for these.
+ */
+import { markingSource } from "./marking.js";
+
+const cap = (text) => text.charAt(0).toUpperCase() + text.slice(1);
+const indentBy = (text, spaces) => text.split("\n").map((line) => (line ? " ".repeat(spaces) + line : line)).join("\n");
+
+/** @typedef {{ id: string, extension: string, openProps: string[][], labelFor: string, declare: (name: string, init: string) => string, read: (name: string) => string, write: (name: string, value: string) => string, attr: (name: string, expr: string) => string, frame: (archetype: string, pkg: string, body: string, hooks?: string) => string }} Dialect */
+
+/** @type {Dialect} */
+export const reactDialect = {
+  id: "react",
+  extension: "jsx",
+  openProps: [["open", "onClose"], ["open", "onOpenChange"], ["isOpen", "onOpenChange"], ["isOpen", "onClose"], ["opened", "onClose"]],
+  labelFor: "htmlFor",
+  declare: (name, init) => `const [${name}, set${cap(name)}] = useState(${init});`,
+  read: (name) => name,
+  write: (name, value) => `set${cap(name)}(${value})`,
+  attr: (name, expr) => `${name}={${expr}}`,
+  frame(archetype, pkg, body, hooks = "") {
+    return `import * as Lib from ${JSON.stringify(pkg)};
+import { useEffect, useState } from "react";
+${markingSource(archetype)}
+export default function Fixture() {
+  useEffect(() => startMarking(), []);
+${hooks ? `${indentBy(hooks, 2)}\n` : ""}  return (
+${indentBy(body, 4)}
+  );
+}
+`;
+  },
+};
+
+/** @type {Dialect} */
+export const vueDialect = {
+  id: "vue",
+  extension: "jsx",
+  // Vue components usually take a model value and say they changed it with an update event, or take `open` and emit `update:open`.
+  openProps: [["open", "onUpdate:open"], ["modelValue", "onUpdate:modelValue"], ["visible", "onUpdate:visible"], ["show", "onUpdate:show"], ["open", "onClose"], ["isOpen", "onClose"]],
+  labelFor: "for",
+  declare: (name, init) => `const ${name} = ref(${init});`,
+  read: (name) => `${name}.value`,
+  write: (name, value) => `(${name}.value = ${value})`,
+  // A name with a colon (onUpdate:open) can't be written as a JSX attribute name, so it goes in through a spread.
+  attr: (name, expr) => (/^[\w-]+$/.test(name) ? `${name}={${expr}}` : `{...{ ${JSON.stringify(name)}: ${expr} }}`),
+  frame(archetype, pkg, body, hooks = "") {
+    return `import * as Lib from ${JSON.stringify(pkg)};
+import { defineComponent, onBeforeUnmount, onMounted, ref } from "vue";
+${markingSource(archetype)}
+export default defineComponent({
+  setup() {
+    let stop = null;
+    onMounted(() => { stop = startMarking(); });
+    onBeforeUnmount(() => { if (stop) stop(); });
+${hooks ? `${indentBy(hooks, 4)}\n` : ""}    return () => (
+${indentBy(body, 6)}
+    );
+  },
+});
+`;
+  },
+};

package/src/harness/generate/index.js

@@ -0,0 +1,12 @@
+import { adapterFor } from "../../frameworks/index.js";
+
+export { ATTEMPT_LIMIT, GENERATABLE } from "./shared.js";
+
+/**
+ * Build the candidate fixtures for one archetype of one package, most likely first, using the framework's adapter.
+ * @param {{ flavor: string, archetype: string, pkg: string, entry: { export?: string, tag?: string }, exports: Array<{ name: string, type: string, parts?: string[] }>, facts: Record<string, { attributes: string[], members: string[], slots: string[] }>, explicit?: boolean }} input
+ * @returns {{ candidates: Array<{ id: string, summary: string, source: string, used: string[] }>, reason: string | null }}
+ */
+export function generateCandidates({ flavor, ...input }) {
+  return adapterFor(flavor).generate(input);
+}

package/src/harness/generate/jsx-recipes.js

@@ -0,0 +1,224 @@
+/**
+ * Candidate fixtures for JSX frameworks (React and Vue), built only from the part names a package exports.
+ *
+ * Each builder takes a function that makes a fresh kit (see kit.js), picks the parts it needs by common names, and returns
+ * a candidate `{ id, summary, source, used }`, or null when the package doesn't have the parts. A candidate is a guess.
+ * It only counts once the probe has bundled it, loaded it, and seen the trigger and root behave (see probe.js).
+ *
+ * The recipes follow how compound components are usually put together (a root, a trigger, a content part, and a title,
+ * description, or close part), and how single components are usually switched on (an `open` prop and a close handler).
+ * None of them names a library. What differs between frameworks is only how a fixture holds state, starts its marking code,
+ * and spells a prop, so a dialect carries those three things (see dialects.js) and the recipes are shared.
+ */
+
+const indent = (text, spaces) => text.split("\n").map((line) => (line ? " ".repeat(spaces) + line : line)).join("\n");
+/** A JSX element. Short text stays on one line, and anything longer goes on its own lines. */
+const tag = (ref, props, children) => {
+  if (!children) return `<${ref}${props} />`;
+  return !children.includes("\n") && children.length < 40 && !children.startsWith("<") ? `<${ref}${props}>${children}</${ref}>` : `<${ref}${props}>\n${indent(children, 2)}\n</${ref}>`;
+};
+
+/** Wrap a layer in a portal and a positioner when the package has them. */
+function layered(kit, content) {
+  const positioner = kit.pick("positioner");
+  const positioned = positioner ? tag(positioner, "", content) : content;
+  const portal = kit.pick("portal");
+  return portal ? tag(portal, "", positioned) : positioned;
+}
+
+// ---- dialog ----
+
+function dialogContent(kit) {
+  const title = kit.pick("title", "heading");
+  const description = kit.pick("description", "desc", "contenttext");
+  const close = kit.pick("close", "closebutton", "closetrigger", "dismiss");
+  return [
+    title ? tag(title, "", "Edit profile") : "<h2>Edit profile</h2>",
+    description ? tag(description, "", "Update your details.") : "<p>Update your details.</p>",
+    close ? tag(close, "", "Close") : '<button type="button">Close</button>',
+  ].join("\n");
+}
+
+function dialogCompound(makeKit, pkg, d) {
+  const kit = makeKit();
+  const root = kit.pick("root") ?? kit.self;
+  const trigger = kit.pick("trigger", "opener", "activator");
+  const content = kit.pick("content", "popup", "window", "panel", "surface");
+  if (!root || !trigger || !content) return null;
+  const overlay = kit.pick("overlay", "backdrop");
+  const layer = `${overlay ? `<${overlay} />\n` : ""}${tag(content, "", dialogContent(kit))}`;
+  const body = tag(root, "", `${tag(trigger, " data-a11y-trigger", "Open dialog")}\n${layered(kit, layer)}`);
+  return { id: "dialog-compound", summary: "a root, a trigger, and a content part that opens on its own", source: d.frame("dialog", pkg, body), used: kit.used() };
+}
+
+function dialogControlled([openProp, closeProp]) {
+  return (makeKit, pkg, d) => {
+    const kit = makeKit();
+    const root = kit.pick("root") ?? kit.self;
+    if (!root) return null;
+    const content = kit.pick("content", "panel", "popup", "window", "surface");
+    const inner = content ? tag(content, "", dialogContent(kit)) : dialogContent(kit);
+    const overlay = kit.pick("overlay", "backdrop");
+    const controls = ` ${d.attr(openProp, d.read("open"))} ${d.attr(closeProp, `(next) => ${d.write("open", "next === true")}`)}`;
+    const body = `<>
+  <button type="button" data-a11y-trigger onClick={() => ${d.write("open", "true")}}>Open dialog</button>
+${indent(tag(root, controls, `${overlay ? `<${overlay} />\n` : ""}${inner}`), 2)}
+</>`;
+    return { id: `dialog-controlled-${openProp}-${closeProp}`.replace(/[^\w-]+/g, "-"), summary: `a root controlled with ${openProp} and ${closeProp}`, source: d.frame("dialog", pkg, body, `  ${d.declare("open", "false")}`), used: kit.used() };
+  };
+}
+
+// ---- menu ----
+
+/** How a menu item is written: bare, with a value, or rendered as a div (some libraries render items as a template by default). */
+const MENU_ITEMS = [
+  { id: "", summary: "", props: () => "" },
+  { id: "-values", summary: " that have values", props: (name) => ` value="${name}"` },
+  { id: "-as-div", summary: " rendered as divs", props: () => ' as="div"' },
+];
+
+function menu(variant) {
+  return (makeKit, pkg, d) => {
+    const kit = makeKit();
+    const root = kit.pick("root") ?? kit.self;
+    const trigger = kit.pick("trigger", "button", "opener");
+    const content = kit.pick("content", "popup", "list", "items");
+    const item = kit.pick("item", "menuitem", "option");
+    if (!root || !trigger || !content || !item) return null;
+    const items = [tag(item, variant.props("edit"), "Edit"), tag(item, variant.props("delete"), "Delete")].join("\n");
+    const body = tag(root, "", `${tag(trigger, " data-a11y-trigger", "Open menu")}\n${layered(kit, tag(content, "", items))}`);
+    return { id: `menu-compound${variant.id}`, summary: `a root, a trigger, and a content part with items${variant.summary}`, source: d.frame("menu", pkg, body), used: kit.used() };
+  };
+}
+
+// ---- tooltip ----
+
+function tooltipCompound(makeKit, pkg, d) {
+  const kit = makeKit();
+  const root = kit.pick("root") ?? kit.self;
+  const trigger = kit.pick("trigger");
+  const content = kit.pick("content", "popup", "bubble");
+  if (!root || !trigger || !content) return null;
+  const provider = kit.pick("provider");
+  const inner = tag(root, "", `${tag(trigger, " data-a11y-trigger", "Save")}\n${layered(kit, tag(content, "", "Saves your work."))}`);
+  const body = provider ? tag(provider, "", inner) : inner;
+  return { id: "tooltip-compound", summary: "a root, a trigger, and a content part", source: d.frame("tooltip", pkg, body), used: kit.used() };
+}
+
+const tooltipSingle = (prop) => (makeKit, pkg, d) => {
+  const kit = makeKit();
+  if (!kit.self) return null;
+  const body = `<${kit.self} ${prop}="Saves your work.">\n  <button type="button" data-a11y-trigger>Save</button>\n</${kit.self}>`;
+  return { id: `tooltip-single-${prop}`, summary: `one component that wraps the trigger and takes ${prop}`, source: d.frame("tooltip", pkg, body), used: [kit.base] };
+};
+
+// ---- tabs ----
+
+const TAB_VARIANTS = [
+  { id: "value", rootProps: ' defaultValue="one"', item: (v) => ` value="${v}"`, summary: "tabs matched to panels by value" },
+  { id: "index", rootProps: "", item: () => "", summary: "tabs matched to panels by position" },
+  { id: "default-index", rootProps: " defaultIndex={0}", item: () => "", summary: "tabs matched by position, starting at index 0" },
+];
+
+const tabs = (variant) => (makeKit, pkg, d) => {
+  const kit = makeKit();
+  const root = kit.pick("root") ?? kit.self;
+  const tab = kit.pick("trigger", "tab");
+  const panel = kit.pick("content", "panel", "tabpanel");
+  if (!root || !tab || !panel) return null;
+  const list = kit.pick("list", "tablist", "tabs");
+  const tabsMarkup = `${tag(tab, `${variant.item("one")} data-a11y-trigger`, "One")}\n${tag(tab, variant.item("two"), "Two")}`;
+  const body = tag(root, variant.rootProps, `${list ? tag(list, "", tabsMarkup) : tabsMarkup}\n${tag(panel, variant.item("one"), "First panel")}\n${tag(panel, variant.item("two"), "Second panel")}`);
+  return { id: `tabs-${variant.id}`, summary: variant.summary, source: d.frame("tabs", pkg, body), used: kit.used() };
+};
+
+// ---- accordion ----
+
+const ACCORDION_ROOTS = [["", "no root props"], [' type="single" collapsible', "single, collapsible"], [" collapsible", "collapsible"], [" multiple", "multiple"]];
+
+const accordion = ([rootProps, label]) => (makeKit, pkg, d) => {
+  const kit = makeKit();
+  const root = kit.pick("root") ?? kit.self;
+  const item = kit.pick("item");
+  const trigger = kit.pick("trigger", "button", "summary");
+  const content = kit.pick("content", "panel", "itempanel", "body");
+  if (!root || !trigger || !content) return null;
+  const header = kit.pick("header", "itemheader", "heading");
+  const section = (name) => {
+    const button = tag(trigger, name === "one" ? " data-a11y-trigger" : "", `Section ${name}`);
+    return `${header ? tag(header, "", button) : button}\n${tag(content, "", "More information.")}`;
+  };
+  // Some libraries have no item part: a disclosure is just a root with a button and a panel.
+  if (!item) {
+    if (rootProps) return null;
+    return { id: "accordion-disclosure", summary: "a root with a button and a panel", source: d.frame("accordion", pkg, tag(root, "", section("one"))), used: kit.used() };
+  }
+  const one = (name, value) => tag(item, ` value="${value}"`, section(name));
+  const body = tag(root, rootProps, `${one("one", "one")}\n${one("two", "two")}`);
+  return { id: `accordion-${label.replace(/[^a-z]+/g, "-")}`, summary: `an accordion with ${label}`, source: d.frame("accordion", pkg, body), used: kit.used() };
+};
+
+// ---- combobox ----
+
+const combobox = (itemProps) => (makeKit, pkg, d) => {
+  const kit = makeKit();
+  const root = kit.pick("root") ?? kit.self;
+  const input = kit.pick("input", "control");
+  const content = kit.pick("content", "list", "popup", "listbox");
+  const item = kit.pick("item", "option");
+  if (!root || !input || !content || !item) return null;
+  const items = [tag(item, itemProps ? ' value="apple"' : "", "Apple"), tag(item, itemProps ? ' value="banana"' : "", "Banana")].join("\n");
+  const body = tag(root, "", `${tag(input, ' data-a11y-trigger aria-label="Fruit"', "")}\n${layered(kit, tag(content, "", items))}`);
+  return { id: `combobox-compound${itemProps ? "-values" : ""}`, summary: `a root, an input, and a list of options${itemProps ? " that have values" : ""}`, source: d.frame("combobox", pkg, body), used: kit.used() };
+};
+
+// ---- form field ----
+
+function fieldCompound(makeKit, pkg, d) {
+  const kit = makeKit();
+  const root = kit.pick("root", "field");
+  const label = kit.pick("label");
+  const input = kit.pick("input", "control");
+  if (!root || !label || !input) return null;
+  const body = tag(root, "", `${tag(label, "", "Name")}\n${tag(input, " data-a11y-trigger", "")}`);
+  return { id: "field-compound", summary: "a root, a label, and an input part", source: d.frame("form-field", pkg, body), used: kit.used() };
+}
+
+const fieldSingle = (id, summary, markup) => (makeKit, pkg, d) => {
+  const kit = makeKit();
+  if (!kit.self) return null;
+  return { id, summary, source: d.frame("form-field", pkg, markup(kit.self, d)), used: [kit.base] };
+};
+
+// ---- live region ----
+
+const messageConditional = (makeKit, pkg, d) => {
+  const kit = makeKit();
+  if (!kit.self) return null;
+  const body = `<div>\n  <button type="button" data-a11y-trigger onClick={() => ${d.write("on", "true")}}>Show message</button>\n  <div>{${d.read("on")} && <${kit.self}>Saved.</${kit.self}>}</div>\n</div>`;
+  return { id: "message-mounted", summary: "a message that is mounted when the trigger is pressed", source: d.frame("live-region", pkg, body, `  ${d.declare("on", "false")}`), used: [kit.base] };
+};
+
+const messageControlled = (prop) => (makeKit, pkg, d) => {
+  const kit = makeKit();
+  if (!kit.self) return null;
+  const body = `<div>\n  <button type="button" data-a11y-trigger onClick={() => ${d.write("on", "true")}}>Show message</button>\n  <${kit.self} ${d.attr(prop, d.read("on"))}>Saved.</${kit.self}>\n</div>`;
+  return { id: `message-${prop}`, summary: `a message shown with its ${prop} prop`, source: d.frame("live-region", pkg, body, `  ${d.declare("on", "false")}`), used: [kit.base] };
+};
+
+/** The builders for each archetype, most likely first. */
+export const buildRecipes = (d) => ({
+  dialog: [dialogCompound, ...d.openProps.map(dialogControlled)],
+  menu: MENU_ITEMS.map(menu),
+  tooltip: [tooltipCompound, ...["title", "label", "content", "text", "tip"].map(tooltipSingle)],
+  tabs: TAB_VARIANTS.map(tabs),
+  accordion: ACCORDION_ROOTS.map(accordion),
+  combobox: [combobox(true), combobox(false)],
+  "form-field": [
+    fieldCompound,
+    fieldSingle("field-wrapped-label", "an input inside a wrapping label", (self) => `<label>\n  Name\n  <${self} data-a11y-trigger />\n</label>`),
+    fieldSingle("field-label-prop", "an input that takes a label prop", (self) => `<${self} label="Name" data-a11y-trigger />`),
+    fieldSingle("field-label-for", "an input matched to a label by id", (self, d) => `<div>\n  <label ${d.labelFor}="name-field">Name</label>\n  <${self} id="name-field" data-a11y-trigger />\n</div>`),
+  ],
+  "live-region": [messageConditional, ...["open", "isOpen", "visible", "show"].map(messageControlled)],
+});

package/src/harness/generate/jsx.js

@@ -0,0 +1,76 @@
+import { ARCHETYPE_PATTERNS } from "../storybook.js";
+import { score } from "../../plan/mapping.js";
+import { buildKit } from "./kit.js";
+import { buildRecipes } from "./jsx-recipes.js";
+import { ATTEMPT_LIMIT, GENERATABLE, nameSaysSo } from "./shared.js";
+
+/** The names a part of a compound component ends with. A name that ends in one belongs to a family that shares the rest. */
+const PART_SUFFIX = /(Root|Trigger|Portal|Overlay|Backdrop|Positioner|Content|Popup|Panel|Title|Description|Close|Header|Item|List|Input|Label|Control|Provider)$/;
+
+/**
+ * The prefix a family of flat exports shares. `DialogClose` and `DialogRoot` belong to `Dialog`, even when no export is
+ * named `Dialog`. It counts only when at least two exports start with it.
+ */
+export function inferBase(name, exports) {
+  if (!name) return null;
+  const base = name.replace(PART_SUFFIX, "");
+  if (!base || base === name) return null;
+  return exports.filter((e) => e.name.startsWith(base) && e.name !== base).length >= 2 ? base : null;
+}
+
+const words = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]/g, " ");
+
+/**
+ * The component families in a package that look like this archetype, best first. A family is a base name and the parts that share
+ * it (`DropdownMenuRoot`, `DropdownMenuItem`), a namespaced export with parts, or a single export. A family ranks by how well its
+ * base fits the archetype's own name, then by how many parts it has. At most three are tried, so a library with a context menu,
+ * a dropdown menu, and a menubar gets the plainest ones first.
+ */
+export function familyBases(archetype, exports) {
+  const families = new Map();
+  for (const e of exports) {
+    if (!/^[A-Z]/.test(e.name) || !ARCHETYPE_PATTERNS[archetype].test(words(e.name))) continue;
+    const base = inferBase(e.name, exports) ?? e.name;
+    if (families.has(base)) continue;
+    const size = exports.filter((other) => other.name !== base && other.name.startsWith(base)).length + (exports.find((other) => other.name === base)?.parts?.length ?? 0);
+    families.set(base, { base, fit: score(archetype, base), size });
+  }
+  return [...families.values()].sort((a, b) => b.fit - a.fit || b.size - a.size || a.base.localeCompare(b.base)).slice(0, 3).map((f) => f.base);
+}
+
+/**
+ * Candidate fixtures for a JSX framework: the recipes, run over the parts of the component the mapping found,
+ * then over the package itself when its own name says it is this archetype.
+ * @param {import("./dialects.js").Dialect} dialect
+ * @param {{ archetype: string, pkg: string, entry: { export?: string }, exports: Array<{ name: string, type: string, parts?: string[] }>, explicit?: boolean }} input
+ *   `explicit` means a person named the export in a mapping, so only that component is tried.
+ * @returns {{ candidates: Array<{ id: string, summary: string, source: string, used: string[] }>, reason: string | null }}
+ */
+export function generateJsx(dialect, { archetype, pkg, entry, exports, explicit = false }) {
+  if (!GENERATABLE.has(archetype)) return { candidates: [], reason: `Nothing is generated for the ${archetype} archetype.` };
+  const recipes = buildRecipes(dialect)[archetype] ?? [];
+  const bases = [];
+  if (explicit && entry.export) {
+    bases.push(inferBase(entry.export, exports) ?? entry.export);
+  } else {
+    bases.push(...familyBases(archetype, exports));
+    if (bases.length === 0 && entry.export) bases.push(inferBase(entry.export, exports) ?? entry.export);
+  }
+  if (nameSaysSo(archetype, pkg)) bases.push(null);
+  const candidates = [];
+  const seen = new Set();
+  for (const base of [...new Set(bases)]) {
+    const makeKit = () => buildKit(exports, base);
+    for (const recipe of recipes) {
+      const candidate = recipe(makeKit, pkg, dialect);
+      if (candidate && !seen.has(candidate.source)) {
+        seen.add(candidate.source);
+        candidates.push(candidate);
+      }
+    }
+  }
+  if (candidates.length === 0) {
+    return { candidates: [], reason: `The package's exports don't have the parts a ${archetype} recipe needs${entry.export ? ` (looked at ${entry.export} and the exports that start with it)` : ""}.` };
+  }
+  return { candidates: candidates.slice(0, ATTEMPT_LIMIT), reason: null };
+}

package/src/harness/generate/kit.js

@@ -0,0 +1,50 @@
+/**
+ * Find the parts of a compound component from the names a package exports.
+ *
+ * Two shapes are common. A namespaced export carries its parts as properties (`Dialog.Root`, `Dialog.Trigger`).
+ * A flat set of exports shares a prefix (`DialogRoot`, `DialogTrigger`, or `Dialog` plus `DialogContent`).
+ * A package that is one component's parts, such as a `Root` and a `Trigger` with no `Dialog` in front, works too.
+ * Parts are found by name only. Nothing here knows any one library.
+ */
+
+/**
+ * @param {Array<{ name: string, type: string, parts?: string[] }>} exports
+ * @param {string | null} base The export that names the component, or null when the package itself is the component.
+ */
+export function buildKit(exports, base) {
+  /** @type {Map<string, string>} lower-case part name to the expression that reaches it */
+  const parts = new Map();
+  const baseInfo = base ? exports.find((e) => e.name === base) : null;
+  if (base) {
+    for (const part of baseInfo?.parts ?? []) parts.set(part.toLowerCase(), `Lib.${base}.${part}`);
+    for (const e of exports) {
+      if (e.name === base || !e.name.startsWith(base)) continue;
+      const rest = e.name.slice(base.length);
+      if (/^[A-Z]/.test(rest) && !parts.has(rest.toLowerCase())) parts.set(rest.toLowerCase(), `Lib.${e.name}`);
+    }
+  } else {
+    for (const e of exports) if (/^[A-Z]/.test(e.name) && !parts.has(e.name.toLowerCase())) parts.set(e.name.toLowerCase(), `Lib.${e.name}`);
+  }
+  const used = new Set();
+  return {
+    base,
+    /** The component itself (`Lib.Dialog`), or null for a package with no single base. */
+    self: base && baseInfo ? `Lib.${base}` : null,
+    /** True when any of these part names exists. */
+    has: (...names) => names.some((name) => parts.has(name)),
+    /** The first part that exists, as a JSX tag. Records what was used. */
+    pick(...names) {
+      for (const name of names) {
+        const ref = parts.get(name);
+        if (ref) {
+          used.add(ref.replace(/^Lib\./, ""));
+          return ref;
+        }
+      }
+      return null;
+    },
+    /** What the candidates used, for the report. */
+    used: () => [...used],
+    names: () => [...parts.keys()],
+  };
+}

package/src/harness/generate/marking.js

@@ -0,0 +1,64 @@
+/**
+ * The code a generated fixture carries to mark its trigger and root.
+ *
+ * The harness needs exactly one element with `data-a11y-trigger` and, once the component is showing, one with
+ * `data-a11y-root` on the element that carries the role. A generated fixture can't know how a library forwards props,
+ * so it doesn't rely on that. It passes the trigger attribute where it can, and this code then marks whatever is missing,
+ * by role, every 50 milliseconds, reaching into open shadow roots. The probe that follows checks the result.
+ */
+
+/** What to look for, per archetype. `root` is a selector, or "trigger", "parent", or "controls". */
+export const MARKING = {
+  dialog: { root: "dialog, [role=dialog], [role=alertdialog]", trigger: "[aria-haspopup], [aria-expanded], button, [role=button]" },
+  menu: { root: "[role=menu]", trigger: "[aria-haspopup], [aria-expanded], button, [role=button]" },
+  tooltip: { root: "[role=tooltip]", trigger: "button, [role=button], a[href], input" },
+  tabs: { root: "trigger", trigger: "[role=tab]" },
+  accordion: { root: "controls", trigger: "[aria-expanded], summary, button" },
+  combobox: { root: "[role=listbox]", trigger: "input[role=combobox], [role=combobox], input" },
+  "form-field": { root: "parent", trigger: "input:not([type=hidden]), textarea, select, [role=textbox], [role=combobox], [role=checkbox], [role=switch]" },
+  "live-region": { root: "[role=alert], [role=status], [role=log], [aria-live=polite], [aria-live=assertive]", trigger: "button, [role=button]" },
+};
+
+/** The roles each archetype's root may carry, so the probe can tell a right mark from a wrong one. */
+export const ROOT_ROLES = {
+  dialog: ["dialog", "alertdialog"],
+  menu: ["menu", "menubar"],
+  tooltip: ["tooltip"],
+  tabs: ["tab"],
+  combobox: ["listbox", "combobox", "grid", "tree"],
+  "live-region": ["alert", "status", "log"],
+};
+
+/** The source that goes at the top of a generated fixture. It defines `startMarking()`, which returns a function that stops it. */
+export function markingSource(archetype) {
+  const config = MARKING[archetype];
+  return `function a11yDeepAll(selector, root) {
+  const scope = root || document;
+  const found = [...scope.querySelectorAll(selector)];
+  for (const el of scope.querySelectorAll("*")) if (el.shadowRoot) found.push(...a11yDeepAll(selector, el.shadowRoot));
+  return found;
+}
+function a11yMark() {
+  const config = ${JSON.stringify(config)};
+  if (a11yDeepAll("[data-a11y-trigger]").length === 0) {
+    const fallback = a11yDeepAll(config.trigger).find((el) => el.getClientRects().length > 0);
+    if (fallback) fallback.setAttribute("data-a11y-trigger", "");
+  }
+  const trigger = a11yDeepAll("[data-a11y-trigger]")[0];
+  if (a11yDeepAll("[data-a11y-root]").length > 0) return;
+  let root = null;
+  if (config.root === "trigger") root = trigger;
+  else if (config.root === "parent") root = trigger && trigger.parentElement;
+  else if (config.root === "controls") {
+    const id = trigger && trigger.getAttribute("aria-controls");
+    root = (id && document.getElementById(id)) || a11yDeepAll("[role=region]")[0];
+  } else root = a11yDeepAll(config.root)[0];
+  if (root) root.setAttribute("data-a11y-root", "");
+}
+function startMarking() {
+  a11yMark();
+  const timer = setInterval(a11yMark, 50);
+  return () => clearInterval(timer);
+}
+`;
+}

package/src/harness/generate/probe.js

@@ -0,0 +1,97 @@
+import { installHelpers } from "../../tiers/interactions/helpers.js";
+import { openPage } from "../url.js";
+import { ROOT_ROLES } from "./marking.js";
+
+/** Archetypes whose root appears after the trigger is activated, as the audit expects. */
+const OPENS = new Set(["dialog", "menu", "tooltip", "accordion", "combobox", "live-region"]);
+
+const FOCUSABLE_FIELD = "input:not([type=hidden]), textarea, select, [contenteditable=true], [role=textbox], [role=combobox], [role=checkbox], [role=switch], [role=radio], [role=slider], [role=spinbutton]";
+
+/**
+ * Check that a generated fixture does what the audit needs, before the audit trusts it.
+ * It loads the page, then checks that exactly one element is marked as the trigger, that nothing logged an error,
+ * that activating the trigger shows a root, and that the root carries a role that fits the archetype.
+ * A fixture that fails any of these isn't used, and the reason says which.
+ * @param {import("playwright-core").Browser} browser
+ * @param {string} url
+ * @param {string} archetype
+ * @returns {Promise<{ ok: boolean, reason: string | null }>}
+ */
+export async function probeFixture(browser, url, archetype) {
+  const errors = [];
+  /** @type {Awaited<ReturnType<typeof openPage>> | null} */
+  let opened = null;
+  try {
+    opened = await openPage(browser, url, {
+      waitUntil: "load",
+      beforeGoto: async (page) => {
+        page.on("pageerror", (error) => errors.push(error.message.split("\n")[0]));
+        page.on("console", (message) => {
+          if (message.type() === "error" && !/favicon|Failed to load resource/i.test(message.text())) errors.push(message.text().split("\n")[0]);
+        });
+        await page.addInitScript(installHelpers);
+      },
+    });
+    const page = opened.page;
+    try {
+      await page.waitForFunction(() => window.__a11y?.queryAllDeep("[data-a11y-trigger]").length > 0, undefined, { timeout: 4000 });
+    } catch {
+      return { ok: false, reason: errors.length ? `it logged an error and rendered nothing to mark as the trigger: ${errors[0]}` : "no element could be marked as the trigger" };
+    }
+    await page.waitForTimeout(150);
+    const count = await page.evaluate(() => window.__a11y.queryAllDeep("[data-a11y-trigger]").length);
+    if (count !== 1) return { ok: false, reason: `${count} elements were marked as the trigger` };
+    if (errors.length) return { ok: false, reason: `it logged an error: ${errors[0]}` };
+
+    if (archetype === "form-field") {
+      const field = await page.evaluate((selector) => window.__a11y.queryDeep("[data-a11y-trigger]")?.matches(selector) ?? false, FOCUSABLE_FIELD);
+      return field ? { ok: true, reason: null } : { ok: false, reason: "the element marked as the trigger isn't a field a person can type in" };
+    }
+    if (archetype === "tabs") {
+      const role = await page.evaluate(() => window.__a11y.queryDeep("[data-a11y-trigger]")?.getAttribute("role") ?? null);
+      return role === "tab" ? { ok: true, reason: null } : { ok: false, reason: `the element marked as the trigger has ${role ? `role ${role}` : "no role"}, not tab` };
+    }
+    if (!OPENS.has(archetype)) return { ok: true, reason: null };
+
+    const trigger = page.locator("[data-a11y-trigger]").first();
+    try {
+      if (archetype === "tooltip") await trigger.focus();
+      else await trigger.click({ timeout: 3000 });
+    } catch (error) {
+      return { ok: false, reason: `the trigger couldn't be activated: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}` };
+    }
+    try {
+      await page.waitForFunction(
+        ({ live, needsRoot }) => {
+          const state = window.__a11y.live();
+          if (live) return state.present && state.visible && Boolean(state.text || state.named);
+          // The trigger can say it's expanded an instant before the root is marked, so a role-carrying root has to be there itself.
+          if (needsRoot) return state.present && state.visible;
+          const trigger = window.__a11y.queryDeep("[data-a11y-trigger]");
+          return (state.present && state.visible) || trigger?.getAttribute("aria-expanded") === "true";
+        },
+        { live: archetype === "live-region", needsRoot: Boolean(ROOT_ROLES[archetype]) },
+        { timeout: 4000 },
+      );
+    } catch {
+      return { ok: false, reason: `activating the trigger showed no ${archetype === "live-region" ? "message" : "element marked as the root"}${ROOT_ROLES[archetype] ? ` (looked for an element with role ${ROOT_ROLES[archetype].join(", ")})` : ""}, which can also mean the library doesn't set that role` };
+    }
+    const roles = ROOT_ROLES[archetype];
+    if (roles) {
+      const fits = await page.evaluate((allowed) => {
+        const root = window.__a11y.queryDeep("[data-a11y-root]");
+        if (!root) return null;
+        const role = root.getAttribute("role");
+        return { role, fits: Boolean(role && allowed.includes(role)) || root.localName === "dialog" || root.hasAttribute("aria-live") };
+      }, roles);
+      if (!fits) return { ok: false, reason: "the root wasn't marked" };
+      if (!fits.fits) return { ok: false, reason: `the element marked as the root has ${fits.role ? `role ${fits.role}` : "no role"}, not ${roles.join(" or ")}` };
+    }
+    if (errors.length) return { ok: false, reason: `it logged an error when the trigger was activated: ${errors[0]}` };
+    return { ok: true, reason: null };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message.split("\n")[0] : String(error) };
+  } finally {
+    await opened?.close();
+  }
+}

package/src/harness/generate/shared.js

@@ -0,0 +1,12 @@
+import { ARCHETYPE_PATTERNS } from "../storybook.js";
+
+/** Archetypes a fixture can be generated for. Buttons and links use templates. A chart has nothing to wire. */
+export const GENERATABLE = new Set(["dialog", "menu", "tooltip", "tabs", "accordion", "combobox", "form-field", "live-region"]);
+
+/** The most candidates probed for one archetype, so a package that matches nothing doesn't cost minutes. */
+export const ATTEMPT_LIMIT = 8;
+
+/** Does the package's own name say it is this archetype? `@scope/react-dialog` is a dialog. */
+export function nameSaysSo(archetype, pkg) {
+  return ARCHETYPE_PATTERNS[archetype].test(pkg.replace(/[^a-z0-9]+/gi, " "));
+}