automatica11y 0.3.3 → 0.4.1

package/src/frameworks/vue.js

@@ -0,0 +1,90 @@
+/**
+ * The Vue adapter, for Vue 3 packages. Libraries ship compiled components, so nothing here compiles single-file components.
+ * Fixtures are JSX that esbuild turns into `h()` calls (a small shim supplies Vue's `h` and `Fragment`, so a fixture doesn't import them),
+ * and a fixture's default export is a component. An optional `setup(app)` export installs plugins before the app mounts.
+ * Every framework adapter has this shape (see index.js).
+ */
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { vueDialect } from "../harness/generate/dialects.js";
+import { generateJsx } from "../harness/generate/jsx.js";
+
+/** Mounts a fixture's default export as the root component, after its optional setup(app) has installed what it needs. */
+export const entry = (fixturePath, _pkg) => `import { createApp } from "vue";
+import * as fixture from ${JSON.stringify(fixturePath)};
+const libA11y = new URLSearchParams(location.search).get("libA11y") === "on";
+const app = createApp(fixture.default, { libA11y });
+if (typeof fixture.setup === "function") await fixture.setup(app);
+app.mount(document.getElementById("root"));
+`;
+
+/** Loads the whole package, lists its exports, and records compound parts such as Dialog.Trigger. Same as for React. */
+export const discoverEntry = (pkg) => `import * as lib from ${JSON.stringify(pkg)};
+const out = [];
+for (const name of Object.keys(lib)) {
+  const value = lib[name];
+  const type = typeof value;
+  if (value === null || (type !== "function" && type !== "object")) continue;
+  const parts = Object.keys(value).filter((key) => /^[A-Z]/.test(key)).slice(0, 30);
+  out.push({ name, type, parts });
+}
+window.__a11yExports = out;
+`;
+
+/** A fixture for the simple archetypes, from the export name alone. A function default export is a functional component. */
+export function template(archetype, pkg, exportName) {
+  const body = {
+    button: `<Component data-a11y-trigger data-a11y-root type="button">Save</Component>`,
+    link: `<Component data-a11y-trigger data-a11y-root href="#top">Read more</Component>`,
+  }[archetype];
+  if (!body) return null;
+  return `import { ${exportName} as Component } from ${JSON.stringify(pkg)};
+export default function Fixture() {
+  return ${body};
+}
+`;
+}
+
+/** Vue 3 or later? A range like "^3.2.0 || ^2.7" counts when any part allows 3. A bare "*" counts too. */
+function allowsVue3(range) {
+  return String(range)
+    .split("||")
+    .some((part) => {
+      const major = /(\d+)/.exec(part);
+      return !major || Number(major[1]) >= 3 || /^[\s*x]*$/.test(part);
+    });
+}
+
+export default {
+  id: "vue",
+  label: "Vue",
+  kind: "npm-vue",
+  noun: "export",
+  extension: "jsx",
+  runtime: ["vue"],
+  detect(meta) {
+    const peers = meta.peerDependencies ?? {};
+    const deps = meta.dependencies ?? {};
+    const range = peers.vue ?? deps.vue;
+    if (range === undefined) return null;
+    if (!allowsVue3(range)) return { kind: "npm-unsupported", framework: "Vue 2", reason: `The package needs Vue ${range}. Only Vue 3 is supported.` };
+    return { kind: "npm-vue", framework: "Vue", reason: `The package lists vue as a ${"vue" in peers ? "peer dependency" : "dependency"}.` };
+  },
+  /** Writes the shim that supplies `h` and `Fragment`, then returns the settings. */
+  bundle(workDir) {
+    const shim = join(workDir, "a11y-vue-jsx-shim.js");
+    writeFileSync(shim, 'export { h, Fragment } from "vue";\n');
+    return {
+      // One copy of Vue for the library and the fixture, or reactivity breaks.
+      alias: { vue: join(workDir, "node_modules", "vue") },
+      define: { __VUE_OPTIONS_API__: "true", __VUE_PROD_DEVTOOLS__: "false", __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: "false" },
+      // Vue has no JSX runtime of its own, so JSX becomes h() calls. The shim is injected wherever h or Fragment is used without being declared.
+      esbuild: { jsx: "transform", jsxFactory: "h", jsxFragment: "Fragment", inject: [shim] },
+    };
+  },
+  entry,
+  discoverEntry,
+  template,
+  generate: (input) => generateJsx(vueDialect, input),
+  describe: (npm) => `Vue${npm.vue ? ` (vue ${npm.vue})` : ""}`,
+};

package/src/frameworks/wc.js

@@ -0,0 +1,55 @@
+/**
+ * The web component adapter: framework-free entries, templates, and generation from what an element says about itself.
+ * Every framework adapter has this shape (see index.js).
+ */
+import { generateWc } from "../harness/generate/wc-recipes.js";
+
+
+/** Loads the package so its custom elements get defined, then calls the fixture's default export, `mount(container)`. */
+export const entry = (fixturePath, pkg) => `// A package's own "sideEffects" list can mark its entry as removable, which would drop a bare import and leave its elements undefined.
+// Using the namespace keeps the package and its registration code.
+import * as library from ${JSON.stringify(pkg)};
+globalThis.__a11yLibrary = library;
+import mount from ${JSON.stringify(fixturePath)};
+const libA11y = new URLSearchParams(location.search).get("libA11y") === "on";
+await mount(document.getElementById("root"), { libA11y });
+`;
+
+/** Loads the whole package. The page's init script records every custom element the package defines. */
+export const discoverEntry = (pkg) => `import * as lib from ${JSON.stringify(pkg)};
+window.__a11yExports = Object.keys(lib).map((name) => ({ name, type: typeof lib[name], parts: [] }));
+`;
+
+/** A fixture for the simple archetypes, from the tag name alone. */
+export function template(archetype, _pkg, tag) {
+  const attrs = {
+    button: `el.textContent = "Save";`,
+    link: `el.setAttribute("href", "#top");\n  el.textContent = "Read more";`,
+  }[archetype];
+  if (!attrs) return null;
+  return `export default function mount(container) {
+  const el = document.createElement(${JSON.stringify(tag)});
+  el.setAttribute("data-a11y-trigger", "");
+  el.setAttribute("data-a11y-root", "");
+  ${attrs}
+  container.append(el);
+}
+`;
+}
+
+export default {
+  id: "wc",
+  label: "Web components",
+  kind: "npm-wc",
+  noun: "custom element",
+  extension: "js",
+  runtime: [],
+  /** A package is detected as web components by a manifest or a base library, which index.js orders against the other adapters. */
+  detect: () => null,
+  bundle: () => ({ alias: {}, esbuild: {} }),
+  entry,
+  discoverEntry,
+  template,
+  generate: (input) => generateWc(input),
+  describe: (npm) => `web components (${npm.tags?.length ? npm.tags.slice(0, 6).join(", ") : "no tags found"})`,
+};

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()],
+  };
+}