automatica11y 0.4.1 → 0.6.0

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

@@ -0,0 +1,360 @@
+/**
+ * Candidate Angular fixtures, built from what discovery read off each exported class: its kind, selectors, inputs, outputs,
+ * `exportAs` names, and a service's methods. A selector says which element and attribute turn a class on, an input named
+ * after a selector attribute (`matMenuTriggerFor`) points at another class, and `exportAs` says how a template names it.
+ * Nothing here knows any one library. A candidate is a guess until the probe has seen it behave (see probe.js).
+ */
+import { markupFor } from "../../frameworks/angular-selectors.js";
+import { score } from "../../plan/mapping.js";
+import { ARCHETYPE_PATTERNS } from "../storybook.js";
+import { markingSource } from "./marking.js";
+import { ATTEMPT_LIMIT, GENERATABLE } from "./shared.js";
+
+const words = (text) => String(text).replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z])([A-Z][a-z])/g, "$1 $2").replace(/[-_[\]]/g, " ");
+
+/** The shape of one record discovery wrote for a class. */
+/** @typedef {{ name: string, angular: { kind: string, selectors?: unknown[][], inputs?: string[], outputs?: string[], exportAs?: string[], standalone?: boolean, moduleName?: string | null, methods?: string[] } }} Part */
+
+const selectorText = (part) => (part.angular.selectors ?? []).flat().filter((x) => typeof x === "string").join(" ");
+
+/** Does the class's name or selector say it belongs to this archetype? */
+const fits = (archetype, part) => ARCHETYPE_PATTERNS[archetype].test(words(`${part.name} ${selectorText(part)}`));
+
+/** The classes of a package that look like this archetype, plain Angular classes only, best fit first. */
+function pool(archetype, exports) {
+  return exports
+    .filter((e) => e.angular && ["component", "directive", "service"].includes(e.angular.kind) && fits(archetype, e))
+    .sort((a, b) => score(archetype, b.name) - score(archetype, a.name) || a.name.localeCompare(b.name));
+}
+
+/** Can a template use this class? A standalone one is imported by name, and another is imported through the module that declares it. */
+const importName = (part) => (part.angular.kind === "service" || part.angular.standalone ? part.name : part.angular.moduleName ?? null);
+
+const usable = (...parts) => parts.every((part) => part && importName(part));
+
+/**
+ * One element that turns a class on, as markup. `extra` holds attributes the recipe adds, and `bind` turns an attribute that is also
+ * an input into a binding (`[matMenuTriggerFor]="m"`). `values` gives a text value to an attribute or input of that name.
+ * @param {Part} part
+ * @param {{ prefer?: string, fallback?: string, extra?: string[], bind?: Record<string, string>, values?: Record<string, string>, inner?: string }} [options]
+ * @returns {string | null}
+ */
+function element(part, { prefer, fallback = "div", extra = [], bind = {}, values = {}, inner = "" } = {}) {
+  // A selector that names its own element (`mat-tab`) can't be put on the preferred one, so it keeps its element.
+  const markup = markupFor(part.angular.selectors, { prefer, fallback }) ?? markupFor(part.angular.selectors, { fallback });
+  if (!markup) return null;
+  const attrs = markup.attrs.map(([name, value]) => {
+    if (name in bind) return `[${name}]="${bind[name]}"`;
+    if (name in values) return `${name}="${values[name]}"`;
+    return value ? `${name}="${value}"` : name;
+  });
+  for (const [name, value] of Object.entries(bind)) if (!markup.attrs.some(([attr]) => attr === name)) attrs.push(`[${name}]="${value}"`);
+  for (const [name, value] of Object.entries(values)) if (!markup.attrs.some(([attr]) => attr === name)) attrs.push(`${name}="${value}"`);
+  const open = [markup.tag, ...extra, ...attrs].join(" ");
+  return VOID.has(markup.tag) ? `<${open}>` : `<${open}>${inner}</${markup.tag}>`;
+}
+
+const VOID = new Set(["input", "img", "br", "hr", "area", "base", "col", "embed", "link", "meta", "source", "track", "wbr"]);
+
+const exportRef = (part) => part.angular.exportAs?.[0] ?? null;
+
+/** The classes that can point at another (`[matMenuTriggerFor]`), with the input that does it, matched to classes that have an `exportAs`. */
+function linked(archetype, exports, targetPattern) {
+  const all = pool(archetype, exports);
+  // The class that is pointed at needn't have the archetype's own name (a listbox for a combobox), so a name pattern widens it.
+  const targets = [...new Set([...all, ...exports.filter((e) => e.angular && targetPattern.test(e.name))])].filter((e) => e.angular?.kind !== "service");
+  const pairs = [];
+  for (const pointer of all) {
+    const inputs = pointer.angular.inputs ?? [];
+    const attrs = new Set((pointer.angular.selectors ?? []).flat().filter((x) => typeof x === "string"));
+    const input = inputs.find((name) => attrs.has(name) && /For$|^for$|Trigger|Target|Menu|Panel|Content|Overlay/.test(name)) ?? inputs.find((name) => /For$/.test(name)) ?? inputs.find((name) => name === archetype || /^(menu|panel|popup|listbox|content|target|overlay|origin)$/.test(name)) ?? inputs.find((name) => attrs.has(name));
+    if (!input) continue;
+    // A library names its parts alike (`MatMenuTrigger`, `MatMenu`), so a target that starts the same way comes first and the rest are left out.
+    const prefix = pointer.name.match(/^[A-Z][a-z0-9]*/)?.[0] ?? "";
+    const near = targets.filter((target) => target.name.startsWith(prefix));
+    // The plainest name first: `Menu` before `MenuBar`.
+    for (const target of (near.length ? near : targets).slice().sort((a, b) => a.name.length - b.name.length)) {
+      if (target !== pointer && exportRef(target) && usable(pointer, target)) pairs.push({ pointer, target, input });
+    }
+  }
+  return pairs;
+}
+
+const nameMatches = (parts, pattern) => parts.filter((part) => pattern.test(part.name));
+
+/**
+ * The first text-like input of a class, such as `label` or `title`, so a recipe can fill it in. A directive that carries its
+ * value on its own attribute (`brnTabsTrigger="one"`) counts too.
+ */
+const textInput = (part, pattern = /^(label|title|header|heading|summary|text|value|name)$/) => {
+  const inputs = part.angular.inputs ?? [];
+  const attrs = new Set((part.angular.selectors ?? []).flat().filter((x) => typeof x === "string"));
+  return inputs.find((name) => pattern.test(name)) ?? inputs.find((name) => attrs.has(name) && part.angular.kind === "directive") ?? null;
+};
+
+/**
+ * The source of one fixture. The marking code runs outside Angular's zone, so its polling doesn't trigger change detection.
+ * @param {{ archetype: string, pkg: string, parts: Part[], template: string, fields?: string, before?: string, extraImports?: string[] }} input
+ */
+function fixture({ archetype, pkg, parts, template, fields = "", before = "", extraImports = [] }) {
+  const names = [...new Set(parts.map(importName))].filter(Boolean);
+  const imports = parts.filter((part) => part.angular.kind !== "service").map(importName);
+  const core = ["Component", "NgZone", "inject", "signal", ...extraImports];
+  return `import { ${[...new Set(core)].join(", ")} } from "@angular/core";
+import { ${names.join(", ")} } from ${JSON.stringify(pkg)};
+
+${markingSource(archetype)}${before}
+class Fixture {
+  zone = inject(NgZone);
+${fields ? `${fields}\n` : ""}  constructor() {
+    this.zone.runOutsideAngular(() => startMarking());
+  }
+}
+Component({ selector: "app-fixture", imports: [${[...new Set(imports)].join(", ")}], template: ${JSON.stringify(template)} })(Fixture);
+export default Fixture;
+`;
+}
+
+const candidate = (id, summary, parts, source) => ({ id, summary, source, used: [...new Set(parts.map((part) => part.name))] });
+
+const ITEMS = "[{ label: 'One', value: 'one', title: 'One', header: 'One', text: 'One', id: 'one', key: 'one', content: 'First panel.' }, { label: 'Two', value: 'two', title: 'Two', header: 'Two', text: 'Two', id: 'two', key: 'two', content: 'Second panel.' }]";
+const itemsInput = (part) => (part.angular.inputs ?? []).find((name) => /^(items|tabs|options|panels|model|data|links)$/.test(name)) ?? null;
+
+// ---- tooltip ----
+
+function tooltips(pkg, exports) {
+  const out = [];
+  for (const part of pool("tooltip", exports).filter((p) => p.angular.kind !== "service" && usable(p))) {
+    const attrs = new Set((part.angular.selectors ?? []).flat().filter((x) => typeof x === "string"));
+    const input = (part.angular.inputs ?? []).find((name) => attrs.has(name)) ?? (part.angular.inputs ?? []).find((name) => /^(tip|tooltip|content|text|label|message|description)$/i.test(name) || /tooltip$/i.test(name));
+    if (!input) continue;
+    const host = element(part, { prefer: "button", extra: ['type="button"', "data-a11y-trigger"], values: { [input]: "Saves your work." }, inner: "Save" });
+    if (host) out.push(candidate(`tooltip-${input}`, `a button with ${part.name} and its ${input} text`, [part], fixture({ archetype: "tooltip", pkg, parts: [part], template: host })));
+  }
+  return out;
+}
+
+// ---- live region ----
+
+function messages(pkg, exports) {
+  const out = [];
+  const all = pool("live-region", exports);
+  for (const part of all.filter((p) => p.angular.kind !== "service" && usable(p))) {
+    const shownBy = (part.angular.inputs ?? []).find((name) => /^(open|opened|visible|show|shown|isOpen|display)$/.test(name));
+    const message = element(part, { extra: [], inner: "Saved." });
+    if (!message) continue;
+    out.push(candidate(`message-if-${part.name}`, `${part.name} added when the trigger is pressed`, [part], fixture({
+      archetype: "live-region", pkg, parts: [part], fields: "  shown = signal(false);",
+      template: `<button type="button" data-a11y-trigger (click)="shown.set(true)">Show message</button>@if (shown()) {${message}}`,
+    })));
+    if (shownBy) {
+      const flagged = element(part, { bind: { [shownBy]: "shown()" }, inner: "Saved." });
+      out.push(candidate(`message-input-${part.name}`, `${part.name} shown through its ${shownBy} input`, [part], fixture({
+        archetype: "live-region", pkg, parts: [part], fields: "  shown = signal(false);",
+        template: `<button type="button" data-a11y-trigger (click)="shown.set(true)">Show message</button>${flagged}`,
+      })));
+    }
+  }
+  for (const service of all.filter((p) => p.angular.kind === "service")) {
+    const method = (service.angular.methods ?? []).find((name) => /^(open|show|notify|add|success|info|error|warn|message|announce)/i.test(name));
+    if (!method) continue;
+    out.push(candidate(`message-service-${service.name}`, `${service.name}.${method}() called when the trigger is pressed`, [service], fixture({
+      archetype: "live-region", pkg, parts: [service], fields: `  service = inject(${service.name});`,
+      template: `<button type="button" data-a11y-trigger (click)="service.${method}('Saved.')">Show message</button>`,
+    })));
+  }
+  return out;
+}
+
+// ---- form field ----
+
+function fields(pkg, exports) {
+  const out = [];
+  const all = pool("form-field", exports).filter((p) => p.angular.kind !== "service" && usable(p));
+  const wrappers = all.filter((p) => /Field|Form|Group|Wrapper|Control/.test(p.name) && !/Label|Input|Error|Hint/.test(p.name.replace(/(Form|Input)Field/, "")));
+  const labels = nameMatches(all, /Label/);
+  const inputs = all.filter((p) => /Input|Control|TextField|Textarea|Native|Field/.test(p.name) && !/Label|Error|Hint|Prefix|Suffix/.test(p.name));
+  for (const input of inputs.slice(0, 3)) {
+    const field = element(input, { prefer: "input", extra: ['id="name"', "data-a11y-trigger"] });
+    if (!field) continue;
+    const label = '<label for="name">Name</label>';
+    for (const wrapper of wrappers.filter((w) => w !== input).slice(0, 2)) {
+      const labelPart = labels.find((l) => l !== wrapper);
+      const labelText = labelPart && usable(labelPart) ? element(labelPart, { prefer: "label", extra: ['for="name"'], inner: "Name" }) : label;
+      const wrapped = element(wrapper, { inner: `${labelText ?? label}${field}` });
+      if (wrapped) out.push(candidate(`field-wrapper-${wrapper.name}`, `${wrapper.name} around a label and ${input.name}`, [wrapper, input, ...(labelPart ? [labelPart] : [])], fixture({ archetype: "form-field", pkg, parts: [wrapper, input, ...(labelPart && usable(labelPart) ? [labelPart] : [])], template: wrapped })));
+    }
+    out.push(candidate(`field-bare-${input.name}`, `${input.name} on a native input with its own label`, [input], fixture({ archetype: "form-field", pkg, parts: [input], template: `${label}${field}` })));
+  }
+  for (const part of all.filter((p) => p.angular.kind === "component" && (p.angular.inputs ?? []).some((name) => /^(label|placeholder|value)$/.test(name)))) {
+    const labelInput = (part.angular.inputs ?? []).find((name) => name === "label");
+    const self = element(part, { prefer: "div", extra: ["data-a11y-trigger"], values: labelInput ? { label: "Name" } : {} });
+    if (self) out.push(candidate(`field-component-${part.name}`, `${part.name} as the whole field`, [part], fixture({ archetype: "form-field", pkg, parts: [part], template: self })));
+  }
+  return out;
+}
+
+// ---- tabs and accordion: a group with child parts, or a data-driven component ----
+
+function groups(archetype, pkg, exports, { groupPattern, childPattern, childTag }) {
+  const out = [];
+  const all = pool(archetype, exports).filter((p) => p.angular.kind !== "service" && usable(p));
+  const containers = all.filter((p) => groupPattern.test(p.name));
+  const plain = (p) => p.angular && p.angular.kind !== "service" && usable(p) && childPattern.test(p.name) && !groupPattern.test(p.name);
+  // A child needn't have the archetype's own name (`MatExpansionPanel`), so a part named like its container (`Mat…`) counts too.
+  const near = (container) => exports.filter((p) => plain(p) && p.name.startsWith(container.name.match(/^[A-Z][a-z0-9]*/)?.[0] ?? "\0"));
+  // The plainest child comes first: `MatTab` before `MatTabLabel`, which only works inside the other.
+  const byLength = (a, b) => a.name.length - b.name.length;
+  const stemOf = (name) => name.replace(/(Group|s)$/, "");
+  /** A part that sits beside the children (`AccordionHeader`, `TabList`): named like the child or like the container. */
+  const partOf = (pattern, child, container) => exports.find((p) => p.angular && p.angular.kind !== "service" && usable(p) && pattern.test(p.name) && (p.name.startsWith(child.name) || (container && p.name.startsWith(stemOf(container.name)))));
+  const isAccordion = archetype === "accordion";
+  const headerFor = (child, container) => (isAccordion ? partOf(/Header$/, child, container) : null);
+  const triggerFor = (child, container) => (isAccordion ? partOf(/Trigger$/, child, container) : null);
+  const contentFor = (child, container) => (archetype === "tabs" || isAccordion ? partOf(/Content$/, child, container) : null);
+  const listFor = (child, container) => (archetype === "tabs" ? partOf(/List$/, child, container) : null);
+  /** One child with its header, trigger, and content parts, when the library has them. */
+  const panel = (child, text, parts) => {
+    const labelInput = textInput(child);
+    const trigger = parts.trigger ? element(parts.trigger, { prefer: "button", extra: ['type="button"'], values: textInput(parts.trigger) ? { [textInput(parts.trigger)]: text } : {}, inner: text }) : null;
+    // A header that doesn't name its own element is a heading, which is what a disclosure trigger sits in.
+    const header = parts.header ? element(parts.header, { prefer: "h3", inner: trigger ?? text }) : trigger;
+    const body = `${text} content.`;
+    const content = parts.content && archetype === "accordion" ? element(parts.content, { prefer: "div", inner: body }) : null;
+    // A text input (`label`) names the child, so the text between the tags is its content. A value input only tells children apart.
+    const named = labelInput && /^(label|title|header|heading|summary|text|name)$/.test(labelInput);
+    const markup = element(child, { prefer: childTag, extra: [], values: labelInput ? { [labelInput]: text } : {}, inner: header ? `${header}${content ?? body}` : named ? body : text });
+    return markup && childTag === "button" && markup.startsWith("<button ") ? markup.replace("<button ", '<button type="button" ') : markup;
+  };
+  /** A tab's content panel sits outside the list, tied to its tab by the same value. */
+  const contents = (content, labels) => (content ? labels.map((text) => element(content, { prefer: "div", values: textInput(content) ? { [textInput(content)]: text } : {}, inner: `${text} content.` })).join("") : "");
+  for (const container of containers.slice(0, 2)) {
+    const children = [...new Set([...all.filter(plain), ...near(container)])].sort(byLength);
+    for (const child of children.slice(0, 2)) {
+      const parts = { header: headerFor(child, container), trigger: triggerFor(child, container), content: contentFor(child, container) };
+      const list = listFor(child, container);
+      const one = panel(child, "One", parts);
+      const two = panel(child, "Two", parts);
+      const valueInput = textInput(container);
+      const first = valueInput ? { [valueInput]: "One" } : {};
+      const used = [container, child, ...[parts.header, parts.trigger, parts.content, list].filter(Boolean)];
+      if (!one || !two) continue;
+      if (list) {
+        const wrappedList = element(list, { prefer: "div", inner: `${one}${two}` });
+        const nested = wrappedList && element(container, { values: first, inner: `${wrappedList}${contents(parts.content, ["One", "Two"])}` });
+        if (nested) out.push(candidate(`${archetype}-list-${container.name}-${list.name}-${child.name}`, `${container.name} holding ${list.name} with two ${child.name}`, used, fixture({ archetype, pkg, parts: used, template: nested })));
+      }
+      const wrapped = element(container, { values: first, inner: `${one}${two}` });
+      if (wrapped) out.push(candidate(`${archetype}-group-${container.name}-${child.name}`, `${container.name} holding two ${child.name}`, used, fixture({ archetype, pkg, parts: used, template: wrapped })));
+    }
+  }
+  if (archetype === "accordion") {
+    // A single disclosure panel, with no container around it.
+    for (const child of [...new Set([...all.filter(plain), ...containers.flatMap(near)])].sort(byLength).slice(0, 2)) {
+      const parts = { header: headerFor(child, null), trigger: triggerFor(child, null), content: contentFor(child, null) };
+      const alone = panel(child, "Details", parts);
+      const used = [child, ...[parts.header, parts.trigger, parts.content].filter(Boolean)];
+      if (alone) out.push(candidate(`${archetype}-single-${child.name}`, `${child.name} on its own`, used, fixture({ archetype, pkg, parts: used, template: alone })));
+    }
+  }
+  for (const part of all.filter((p) => itemsInput(p))) {
+    const input = itemsInput(part);
+    const host = element(part, { bind: { [input]: "items" } });
+    if (host) out.push(candidate(`${archetype}-items-${part.name}`, `${part.name} given its ${input} input`, [part], fixture({ archetype, pkg, parts: [part], fields: `  items = ${ITEMS};`, template: host })));
+  }
+  return out;
+}
+
+const tabs = (pkg, exports) => groups("tabs", pkg, exports, { groupPattern: /(Tabs|TabGroup|TabList|TabNav|TabNavBar|TabBar|TabView)$|^Tab(s|List|Group|Nav|Bar)$/, childPattern: /Tabs?(Link|Item|Label|Panel|Trigger)?$/, childTag: "button" });
+
+function accordions(pkg, exports) {
+  const out = groups("accordion", pkg, exports, { groupPattern: /(Accordion|Expansion|Collapse|Collapsible)s?$/, childPattern: /(Panel|Item|Section|Tab|Disclosure)$/, childTag: "div" });
+  for (const { pointer, target, input } of linked("accordion", exports, /Panel|Content|Collaps/)) {
+    const ref = "panel";
+    const trigger = element(pointer, { prefer: "button", extra: ['type="button"', "data-a11y-trigger"], bind: { [input]: ref }, inner: "Details" });
+    const body = element(target, { extra: [`#${ref}="${exportRef(target)}"`], inner: "More about this." });
+    if (trigger && body) out.push(candidate(`accordion-ref-${pointer.name}-${target.name}`, `${pointer.name} pointing at ${target.name}`, [pointer, target], fixture({ archetype: "accordion", pkg, parts: [pointer, target], template: `${trigger}${body}` })));
+  }
+  return out;
+}
+
+// ---- menu and combobox: a pointer directive and a panel it points at, with item parts ----
+
+function menus(pkg, exports) {
+  const out = [];
+  const items = exports.filter((p) => p.angular && /Menu.*Item|Item/.test(p.name) && fits("menu", p) && p.angular.kind !== "service" && usable(p));
+  for (const { pointer, target, input } of linked("menu", exports, /Menu|Panel/)) {
+    const trigger = element(pointer, { prefer: "button", extra: ['type="button"', "data-a11y-trigger"], bind: { [input]: "m" }, inner: "Actions" });
+    for (const item of [items[0] ?? null]) {
+      const entry = item ? element(item, { prefer: "button", extra: ['type="button"'], inner: "Copy" }) : '<button type="button">Copy</button>';
+      const panel = element(target, { extra: [`#m="${exportRef(target)}"`], inner: entry ?? "" });
+      if (trigger && panel) out.push(candidate(`menu-ref-${pointer.name}-${target.name}`, `${pointer.name} pointing at ${target.name}`, [pointer, target, ...(item ? [item] : [])], fixture({ archetype: "menu", pkg, parts: [pointer, target, ...(item ? [item] : [])], template: `${trigger}${panel}` })));
+    }
+  }
+  for (const part of pool("menu", exports).filter((p) => p.angular.kind !== "service" && usable(p) && itemsInput(p))) {
+    const input = itemsInput(part);
+    const host = element(part, { bind: { [input]: "items" } });
+    if (host) out.push(candidate(`menu-items-${part.name}`, `${part.name} given its ${input} input`, [part], fixture({ archetype: "menu", pkg, parts: [part], fields: `  items = ${ITEMS};`, template: host })));
+  }
+  return out;
+}
+
+function comboboxes(pkg, exports) {
+  const out = [];
+  const options = exports.filter((p) => p.angular && /Option/.test(p.name) && p.angular.kind !== "service" && usable(p));
+  for (const { pointer, target, input } of linked("combobox", exports, /Listbox|Options|Panel|Autocomplete|Overlay|Popup/)) {
+    const field = element(pointer, { prefer: "input", extra: ['type="text"', 'aria-label="Fruit"', "data-a11y-trigger"], bind: { [input]: "l" } });
+    const option = options[0] ? element(options[0], { prefer: "div", inner: "Apple" }) : '<div role="option">Apple</div>';
+    const panel = element(target, { extra: [`#l="${exportRef(target)}"`], inner: option ?? "" });
+    const used = [pointer, target, ...(options[0] ? [options[0]] : [])];
+    if (field && panel) out.push(candidate(`combobox-ref-${pointer.name}-${target.name}`, `${pointer.name} pointing at ${target.name}`, used, fixture({ archetype: "combobox", pkg, parts: used, template: `${field}${panel}` })));
+  }
+  for (const part of pool("combobox", exports).filter((p) => p.angular.kind === "component" && usable(p) && (p.angular.inputs ?? []).some((name) => /^(options|items|suggestions)$/.test(name)))) {
+    const input = (part.angular.inputs ?? []).find((name) => /^(options|items|suggestions)$/.test(name));
+    const host = element(part, { prefer: "div", bind: { [input]: "items" }, extra: ['aria-label="Fruit"'] });
+    if (host) out.push(candidate(`combobox-items-${part.name}`, `${part.name} given its ${input} input`, [part], fixture({ archetype: "combobox", pkg, parts: [part], fields: `  items = ${ITEMS};`, template: host })));
+  }
+  return out;
+}
+
+// ---- dialog ----
+
+const CONTENT = `Component({ selector: "app-dialog-content", template: '<h2>Edit profile</h2><p>Update your details.</p><button type="button">Close</button>' })(DialogContent);\n`;
+
+function dialogs(pkg, exports) {
+  const out = [];
+  const all = pool("dialog", exports);
+  for (const service of all.filter((p) => p.angular.kind === "service")) {
+    const method = (service.angular.methods ?? []).find((name) => /^open/i.test(name));
+    if (!method) continue;
+    out.push(candidate(`dialog-service-${service.name}`, `${service.name}.${method}() with a small content component`, [service], fixture({
+      archetype: "dialog", pkg, parts: [service], before: `class DialogContent {}\n${CONTENT}`, fields: `  dialog = inject(${service.name});\n  content = DialogContent;`,
+      template: `<button type="button" data-a11y-trigger (click)="dialog.${method}(content)">Open dialog</button>`,
+    })));
+  }
+  for (const part of all.filter((p) => p.angular.kind === "component" && usable(p))) {
+    const shownBy = (part.angular.inputs ?? []).find((name) => /^(open|opened|visible|show|isOpen|display)$/.test(name));
+    if (!shownBy) continue;
+    const closers = (part.angular.outputs ?? []).filter((name) => /close|hide|Change$/.test(name)).map((name) => (/Change$/.test(name) ? `(${name})="shown.set($event === true)"` : `(${name})="shown.set(false)"`));
+    const host = element(part, { extra: closers, bind: { [shownBy]: "shown()" }, inner: '<h2>Edit profile</h2><p>Update your details.</p><button type="button" (click)="shown.set(false)">Close</button>' });
+    if (host) out.push(candidate(`dialog-input-${part.name}`, `${part.name} shown through its ${shownBy} input`, [part], fixture({ archetype: "dialog", pkg, parts: [part], fields: "  shown = signal(false);", template: `<button type="button" data-a11y-trigger (click)="shown.set(true)">Open dialog</button>${host}` })));
+  }
+  return out;
+}
+
+const BUILDERS = { dialog: dialogs, menu: menus, tooltip: tooltips, tabs, accordion: accordions, combobox: comboboxes, "form-field": fields, "live-region": messages };
+
+/**
+ * Candidates for an Angular package, from what discovery read off its classes.
+ * @param {{ archetype: string, pkg: string, exports: Array<{ name: string, angular?: AngularExportInfo }> }} input
+ * @returns {{ candidates: Array<{ id: string, summary: string, source: string, used: string[] }>, reason: string | null }}
+ */
+export function generateAngular({ archetype, pkg, exports }) {
+  if (!GENERATABLE.has(archetype)) return { candidates: [], reason: `Nothing is generated for the ${archetype} archetype.` };
+  const found = BUILDERS[archetype](pkg, exports);
+  const seen = new Set();
+  const candidates = found.filter((c) => (seen.has(c.id) ? false : seen.add(c.id))).slice(0, ATTEMPT_LIMIT);
+  return candidates.length
+    ? { candidates, reason: null }
+    : { candidates: [], reason: `No Angular class looks like the ${archetype} archetype and shows a way to wire one (a selector, an input, or a service method), so a fixture has to be written.` };
+}

package/src/harness/generate/probe.js

@@ -1,3 +1,4 @@
+import { explainAngularError } from "../../frameworks/angular-errors.js";
 import { installHelpers } from "../../tiers/interactions/helpers.js";
 import { openPage } from "../url.js";
 import { ROOT_ROLES } from "./marking.js";
@@ -25,9 +26,9 @@ export async function probeFixture(browser, url, archetype) {
     opened = await openPage(browser, url, {
       waitUntil: "load",
       beforeGoto: async (page) => {
-        page.on("pageerror", (error) => errors.push(error.message.split("\n")[0]));
+        page.on("pageerror", (error) => errors.push(explainAngularError(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]);
+          if (message.type() === "error" && !/favicon|Failed to load resource/i.test(message.text())) errors.push(explainAngularError(message.text().split("\n")[0]));
         });
         await page.addInitScript(installHelpers);
       },
@@ -60,8 +61,8 @@ export async function probeFixture(browser, url, archetype) {
     } 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(
+    /** Wait for the surface. A tooltip gets a second chance below, so this one is short for it. */
+    const waitForSurface = (timeout) => page.waitForFunction(
         ({ live, needsRoot }) => {
           const state = window.__a11y.live();
           if (live) return state.present && state.visible && Boolean(state.text || state.named);
@@ -71,8 +72,18 @@ export async function probeFixture(browser, url, archetype) {
           return (state.present && state.visible) || trigger?.getAttribute("aria-expanded") === "true";
         },
         { live: archetype === "live-region", needsRoot: Boolean(ROOT_ROLES[archetype]) },
-        { timeout: 4000 },
+        { timeout },
       );
+    try {
+      try {
+        await waitForSurface(archetype === "tooltip" ? 1500 : 4000);
+      } catch (error) {
+        if (archetype !== "tooltip") throw error;
+        // Some tooltips open only for focus that came from the keyboard, so focus the trigger again the way a person would.
+        await page.evaluate(() => /** @type {HTMLElement | null} */ (document.activeElement)?.blur());
+        await page.keyboard.press("Tab");
+        await waitForSurface(3000);
+      }
     } 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` };
     }

package/src/harness/npm-install.js

@@ -35,7 +35,7 @@ export function installedVersion(dir, name) {
  * Install a package into its own directory, never next to another target's install.
  * npm adds the peer dependencies. A React package also needs react-dom, and a Vue package needs vue, so add them when the peers left them out.
  * Install scripts stay off, because the code is untrusted until it runs in the browser sandbox.
- * @param {{ dir: string, name: string, version: string, flavor: "react" | "vue" | "wc" | "unknown", run?: typeof runNpm }} options
+ * @param {{ dir: string, name: string, version: string, flavor: "react" | "vue" | "angular" | "html" | "wc" | "unknown", run?: typeof runNpm }} options
  */
 export async function installPackage({ dir, name, version, flavor, run = runNpm }) {
   mkdirSync(dir, { recursive: true });
@@ -66,23 +66,55 @@ export async function installPackage({ dir, name, version, flavor, run = runNpm
   if (flavor === "react") {
     const react = installedVersion(dir, "react");
     if (!react) {
-      await npm(["install", "react", "react-dom", ...NPM_FLAGS, "--legacy-peer-deps"]);
+      await npm(["install", "react", "react-dom", ...pinnedRuntime(dir, ["react", "react-dom"]), ...NPM_FLAGS, "--legacy-peer-deps"]);
       warnings.push(`${name} didn't bring in react, so the latest react and react-dom were added.`);
     } else if (!installedVersion(dir, "react-dom")) {
       // Name react too. A loose install prunes a package that only arrived as a peer, and react did.
-      await npm(["install", `react@${react}`, `react-dom@${react}`, ...NPM_FLAGS, "--legacy-peer-deps"]);
+      await npm(["install", `react@${react}`, `react-dom@${react}`, ...pinnedRuntime(dir, ["react", "react-dom"]), ...NPM_FLAGS, "--legacy-peer-deps"]);
     }
   }
   if (flavor === "vue" && !installedVersion(dir, "vue")) {
-    await npm(["install", "vue", ...NPM_FLAGS, "--legacy-peer-deps"]);
+    await npm(["install", "vue", ...pinnedRuntime(dir, ["vue"]), ...NPM_FLAGS, "--legacy-peer-deps"]);
     warnings.push(`${name} didn't bring in vue, so the latest vue was added.`);
   }
-  return { dir, warnings, react: installedVersion(dir, "react"), reactDom: installedVersion(dir, "react-dom"), vue: installedVersion(dir, "vue"), version: installedVersion(dir, name) };
+  if (flavor === "angular") {
+    // The Angular packages have to be the same version as core. A library's peers usually bring in core and common, not the compiler or the platform.
+    const core = installedVersion(dir, "@angular/core");
+    const missing = ANGULAR_RUNTIME.filter((pkg) => !installedVersion(dir, pkg));
+    if (!core) {
+      await npm(["install", ...ANGULAR_RUNTIME, ...pinnedRuntime(dir, ANGULAR_RUNTIME), ...NPM_FLAGS, "--legacy-peer-deps"]);
+      warnings.push(`${name} didn't bring in @angular/core, so the latest Angular packages were added.`);
+    } else if (missing.length) {
+      // Name everything already installed too. A loose install prunes a package that only arrived as a peer.
+      const adding = missing.map((pkg) => (pkg.startsWith("@angular/") ? `${pkg}@${core}` : pkg));
+      await npm(["install", ...adding, ...pinnedRuntime(dir, adding), ...NPM_FLAGS, "--legacy-peer-deps"]);
+    }
+  }
+  return { dir, warnings, react: installedVersion(dir, "react"), reactDom: installedVersion(dir, "react-dom"), vue: installedVersion(dir, "vue"), angular: installedVersion(dir, "@angular/core"), version: installedVersion(dir, name) };
 }
 
-/** The installed framework runtimes (React, React DOM, Vue), named again so a loose install can't prune them. */
-function pinnedRuntime(dir) {
-  return ["react", "react-dom", "vue"].flatMap((name) => (installedVersion(dir, name) ? [`${name}@${installedVersion(dir, name)}`] : []));
+/** What an Angular fixture needs beside the library: core, the runtime compiler, the platform, and the pieces core uses. */
+const ANGULAR_RUNTIME = ["@angular/core", "@angular/common", "@angular/compiler", "@angular/platform-browser", "rxjs"];
+
+/**
+ * Every package installed at the top level, as exact specs. A loose install (--legacy-peer-deps) prunes a package that only arrived
+ * as someone's peer, which is how React, and then Angular's CDK, went missing. Naming everything that's already there keeps it all.
+ * A spec for a package in `except` is left out, because the caller is installing that one at a different version.
+ * @param {string} dir
+ * @param {string[]} [except] Package names, or specs such as `name@range`.
+ * @returns {string[]}
+ */
+function pinnedRuntime(dir, except = []) {
+  const skip = new Set(except.map((spec) => spec.replace(/^(@?[^@]+)@.*$/, "$1")));
+  const root = join(dir, "node_modules");
+  /** @type {string[]} */
+  const names = [];
+  for (const entry of existsSync(root) ? readdirSync(root) : []) {
+    if (entry.startsWith(".")) continue;
+    if (entry.startsWith("@")) for (const inner of readdirSync(join(root, entry))) names.push(`${entry}/${inner}`);
+    else names.push(entry);
+  }
+  return names.filter((name) => !skip.has(name)).flatMap((name) => (installedVersion(dir, name) ? [`${name}@${installedVersion(dir, name)}`] : []));
 }
 
 const PACKAGE_SPEC = /^(@[a-z0-9~][\w.~-]*\/)?[a-z0-9~][\w.~-]*(@[\w.^~<>=*|-]+)?$/i;
@@ -98,7 +130,7 @@ export async function installExtraPackages({ dir, specs, run = runNpm }) {
   if (wanted.length === 0) return { installed: [], warnings: [] };
   for (const spec of wanted) if (!PACKAGE_SPEC.test(spec)) throw new Error(`The mapping's install list has "${spec}", which isn't a package name with an optional version.`);
   try {
-    await run(["install", ...wanted, ...pinnedRuntime(dir), "--legacy-peer-deps", ...NPM_FLAGS], dir);
+    await run(["install", ...wanted, ...pinnedRuntime(dir, wanted), "--legacy-peer-deps", ...NPM_FLAGS], dir);
   } catch (error) {
     throw new Error(`npm couldn't install ${wanted.join(", ")}: ${firstLine(error.message)}`);
   }
@@ -145,8 +177,8 @@ export async function installOptionalPeers({ dir, unresolved, run = runNpm }) {
   const wanted = unresolved.filter((name) => declared.has(name) && !installedVersion(dir, name));
   if (wanted.length === 0) return { installed: [], warnings: [] };
   // A loose install prunes packages that only arrived as peers, so name the framework again to keep it.
-  const keep = pinnedRuntime(dir);
-  const specs = [...wanted.map((name) => `${name}@${declared.get(name)}`), ...keep];
+  const adding = wanted.map((name) => `${name}@${declared.get(name)}`);
+  const specs = [...adding, ...pinnedRuntime(dir, adding)];
   try {
     await run(["install", ...specs, "--legacy-peer-deps", ...NPM_FLAGS], dir);
   } catch (error) {

package/src/harness/shadow.js

@@ -18,7 +18,7 @@ export function recordClosedShadowRoots() {
  * @returns {Promise<Record<string, number>>}
  */
 export async function closedShadowHosts(page) {
-  const hosts = await page.evaluate(() => /** @type {any} */ (window).__a11yClosedShadowHosts ?? []).catch(() => []);
+  const hosts = await page.evaluate(() => window.__a11yClosedShadowHosts ?? []).catch(() => []);
   /** @type {Record<string, number>} */
   const counts = {};
   for (const host of hosts) counts[host] = (counts[host] ?? 0) + 1;

package/src/harness/storybook.js

@@ -16,20 +16,32 @@ export const ARCHETYPE_PATTERNS = {
   chart: /\bcharts?\b|\bgraphs?\b|\bplots?\b/i,
 };
 
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {value is unknown[]} */
+function isArray(value) {
+  return Array.isArray(value);
+}
+
 /**
  * Pull the stories out of a Storybook index. Handles `index.json` (`entries`, with docs pages) and the older `stories.json`.
- * @param {any} index
+ * @param {unknown} index
  * @returns {Array<{ id: string, title: string, name: string, tags: string[] }>}
  */
 export function listStories(index) {
-  const table = index.entries ?? index.stories ?? {};
+  const data = isRecord(index) ? index : {};
+  const table = (isRecord(data.entries) ? data.entries : null) ?? (isRecord(data.stories) ? data.stories : {});
   return Object.values(table)
-    .filter((entry) => entry && typeof entry === "object" && (entry.type === undefined || entry.type === "story"))
+    .filter(isRecord)
+    .filter((entry) => entry.type === undefined || entry.type === "story")
     .map((entry) => ({
       id: String(entry.id),
       title: String(entry.title ?? entry.kind ?? ""),
       name: String(entry.name ?? entry.story ?? ""),
-      tags: Array.isArray(entry.tags) ? entry.tags.map(String) : [],
+      tags: isArray(entry.tags) ? entry.tags.map(String) : [],
     }))
     .sort((a, b) => a.id.localeCompare(b.id));
 }
@@ -88,7 +100,8 @@ export function storyUrl(base, id) {
 /**
  * Read a Storybook's index from disk or over HTTP.
  * @param {{ path?: string | null, url?: string | null, index: string }} resolved
- * @param {Function} [doFetch]
+ * @param {(url: URL, options?: { signal?: AbortSignal }) => Promise<{ ok: boolean, status: number, json(): Promise<unknown> }>} [doFetch]
+ * @returns {Promise<unknown>}
  */
 export async function readIndex(resolved, doFetch = globalThis.fetch) {
   if (resolved.path) return JSON.parse(readFileSync(join(resolved.path, resolved.index), "utf8"));

package/src/plan/build-plan.js

@@ -36,6 +36,7 @@ export async function buildPlan({ command, targets, options, browserVersion = nu
       kind: target.kind,
       evidenceLevel: target.evidenceLevel,
       resolved: target.resolved,
+      ...(target.companions?.length ? { companions: target.companions } : {}),
       mapping: null,
     };
   });