@uniaria/testing 0.0.0-stage → 0.1.0

package/dist/scenario-DMaR4JJc.d.ts

@@ -0,0 +1,383 @@
+//#region src/conformance/template.d.ts
+/**
+ * Adapter-neutral markup for conformance scenarios. A scenario describes the
+ * DOM a consumer would write — part elements, their content and the
+ * attributes the consumer owns — and each adapter renders it its own way:
+ * React spreads part props onto these elements, the custom element wraps them
+ * in its host. Scenarios never import a definition, so they can be written
+ * before the implementation exists.
+ */
+interface TemplateElement {
+  /** Tag name, as the consumer would write it (`button`, `a`, `div`). */
+  readonly tag: string;
+  /** The UniAria part this element is, if any (`root`, `trigger`). */
+  readonly part?: string;
+  /** Consumer-owned attributes, with DOM names (`class`, `for`, `aria-label`). */
+  readonly attrs: Readonly<Record<string, string>>;
+  readonly children: readonly TemplateNode[];
+}
+/**
+ * Another UniAria component inside the markup, such as a checkbox in its group.
+ * React renders it with its own `useComponent()`; custom elements wrap its
+ * children in its own host.
+ */
+interface TemplateComponent {
+  /** The nested component's definition name: `checkbox`. */
+  readonly component: string;
+  /** Its props, passed the way the adapter's consumers pass them. */
+  readonly props: Readonly<Record<string, unknown>>;
+  /** Its markup: part elements in it are its own parts. */
+  readonly children: readonly TemplateNode[];
+}
+/** What a `rows()` node renders from (Listbox virtualization spec). */
+interface RenderedRows {
+  /** The component's `renderedKeys`: the options to render, in list order. */
+  readonly keys: readonly string[];
+  /** Its `renderedSections`: the groups to render, in list order. */
+  readonly sections: readonly string[];
+}
+/**
+ * Rows the consumer renders from the component's public state rather than
+ * from every item, as a virtualized list's consumer does. React renders
+ * them in a child component that selects `renderedKeys` and
+ * `renderedSections`, so the owner never renders again for them; custom
+ * elements render them again on `renderedkeyschange`, synchronously,
+ * keeping each element whose part and `data-key` stay.
+ */
+interface TemplateRows {
+  readonly rows: (rendered: RenderedRows) => readonly TemplateNode[];
+}
+/** An element, a nested component, rows or a text node. */
+type TemplateNode = TemplateElement | TemplateComponent | TemplateRows | string;
+type TemplateAttrs = Readonly<Record<string, string>> & {
+  readonly part?: string;
+};
+/**
+ * Builds a template element: `h('button', { part: 'root' }, 'Save')`. The
+ * `part` key names the UniAria part; every other key is a consumer-owned
+ * attribute.
+ */
+declare function h(tag: string, attrs?: TemplateAttrs | null, ...children: TemplateNode[]): TemplateElement;
+/**
+ * Nests another component: `nested('checkbox', { value: 'email' }, …)`.
+ * Its children's `part`s are its own parts.
+ */
+declare function nested(component: string, props?: Readonly<Record<string, unknown>> | null, ...children: TemplateNode[]): TemplateComponent;
+/**
+ * Rows rendered from the component's `renderedKeys` and `renderedSections`:
+ * `rows(({ keys }) => keys.map((key) => h('li', { part: 'option', 'data-key': key }, key)))`.
+ * Each row's top element carries `data-key`, as a consumer's keyed list does.
+ */
+declare function rows(render: (rendered: RenderedRows) => readonly TemplateNode[]): TemplateRows;
+/** Whether a node is a nested component. */
+declare function isNested(node: TemplateNode): node is TemplateComponent;
+/** Whether a node is rows rendered from the component's state. */
+declare function isRows(node: TemplateNode): node is TemplateRows;
+/**
+ * Stands for `virtualizer` from `@uniaria/core/virtual` in a scenario's
+ * props: scenarios never import the implementation, so each adapter passes
+ * the real one in its place.
+ */
+declare const VIRTUALIZER: unique symbol;
+/**
+ * The component's part elements in document order, for adapters that render
+ * templates; nested components' parts and rows are left out.
+ */
+declare function templateParts(nodes: readonly TemplateNode[]): TemplateElement[];
+/**
+ * The CSS selector for a part of `component` (root AGENTS.md → Part
+ * markers): the root by `data-uni`, a part outside the root by
+ * `data-uni-part`, any other part by its `data-element` inside the root,
+ * minus those inside another component's root. A part no root is around
+ * counts too, as in a component rendered without its root, which has nothing
+ * else to scope its parts by. One compound, so `[data-key="…"]` can follow
+ * it.
+ */
+declare function partSelector(component: string, part: string): string;
+/** Which part of `component` an element is, by its markers. */
+declare function partName(element: Element, component: string): string | undefined;
+/** How `renderTemplate()` renders what only the adapter knows. */
+interface RenderTemplateOptions {
+  /** Adds attributes to part elements as they are created. */
+  readonly decorate?: (element: HTMLElement, node: TemplateElement) => void;
+  /** Creates the element for a nested component; its children go into it. */
+  readonly host?: (node: TemplateComponent) => HTMLElement;
+  /** Is told where a `rows()` node goes, and renders it there itself. */
+  readonly rowsIn?: (node: TemplateRows, parent: ParentNode) => void;
+  /** A component's parts outside its root: its definition's `outsideParts`. */
+  readonly outsideParts?: (component: string) => readonly string[];
+}
+/**
+ * Renders a template of the component `component` to real DOM, marking part
+ * elements the way a consumer of the custom elements would (`partMarker()`):
+ * the root with `data-uni`, a part outside the root with `data-uni-part`,
+ * the others with `data-element`.
+ */
+declare function renderTemplate(nodes: readonly TemplateNode[], doc: Document, component: string, { decorate, host, rowsIn, outsideParts }?: RenderTemplateOptions): DocumentFragment;
+//#endregion
+//#region src/conformance/contract.d.ts
+/** What the runner asks an adapter to render. */
+interface MountRequest {
+  /** Definition name: `button`. */
+  readonly component: string;
+  /** Initial props, passed the way the adapter's consumers pass them. */
+  readonly props: Readonly<Record<string, unknown>>;
+  /** The consumer's markup. Part elements carry `part`. */
+  readonly template: readonly TemplateNode[];
+  /** Component events to observe; call `record` whenever one fires. */
+  readonly events: readonly string[];
+  record(event: string, detail: unknown): void;
+  /** An empty element already attached to `document.body`. Render into it. */
+  readonly container: HTMLElement;
+}
+/**
+ * What an adapter returns from `mount()`.
+ *
+ * Guarantees every adapter must keep, because scenarios assert right after an
+ * awaited interaction:
+ * - Attribute writes for a state change are visible when the interaction that
+ *   caused it resolves (the DOM binder writes synchronously after a flush).
+ * - `setProps()` resolves once the DOM reflects the new props.
+ */
+interface AdapterMount {
+  /** Merges props, the way the adapter's consumers update them. */
+  setProps(props: Readonly<Record<string, unknown>>): Promise<void>;
+  /**
+   * Calls one of the component's public actions (`open`), the way the
+   * adapter's consumers do: the React handle's `actions`, the element's
+   * method. Resolves once the DOM reflects it.
+   */
+  call(action: string): Promise<void>;
+  /** The object the definition's `expose()` returns right now. */
+  state(): Readonly<Record<string, unknown>>;
+  /**
+   * How many times the framework rendered the component that owns the
+   * instance, including the first render. Adapters without renders (custom
+   * elements) return 0.
+   */
+  renderCount(): number;
+  /** Removes everything rendered and stops the instance. */
+  unmount(): Promise<void>;
+}
+interface ConformanceAdapter {
+  /** `react`, `elements`. Appears in test names. */
+  readonly name: string;
+  mount(request: MountRequest): Promise<AdapterMount>;
+}
+interface RecordedEvent {
+  /** camelCase event name: `press`. */
+  readonly name: string;
+  /** The event payload: the React callback argument or the DOM event's `detail`. */
+  readonly detail: unknown;
+}
+interface MountOptions<Props> {
+  /** The consumer's markup: one node or several. */
+  readonly template: TemplateNode | readonly TemplateNode[];
+  readonly props?: Partial<Props>;
+  /** Component events to record, camelCase. */
+  readonly events?: readonly string[];
+}
+/** A mounted component, as scenarios see it. */
+interface Mounted<Props, State> {
+  /** The element the adapter rendered into. */
+  readonly container: HTMLElement;
+  /**
+   * The element of a part of the mounted component (`root` by default)
+   * inside the container, found by `partSelector()`: the root by
+   * `data-uni="<component>"`, a part outside the root by
+   * `data-uni-part="<component>-<part>"`, any other part by its
+   * `data-element` inside the root. Throws when there is none or more than one, so a
+   * missing marker fails loudly.
+   */
+  part(name?: string): HTMLElement;
+  parts(name: string): HTMLElement[];
+  /** Every recorded event so far, in order. */
+  readonly events: readonly RecordedEvent[];
+  /** Just the names of the recorded events, in order. */
+  eventNames(): string[];
+  clearEvents(): void;
+  state(): State;
+  setProps(props: Partial<Props>): Promise<void>;
+  /** Calls a public action of the component, such as `open`. */
+  call(action: string): Promise<void>;
+  renderCount(): number;
+}
+//#endregion
+//#region src/conformance/scenario.d.ts
+type MouseButton = 'left' | 'right' | 'middle';
+/** Real mouse input through Playwright, at the target's centre. */
+interface PointerInput {
+  /** Moves to the target and presses a button (left by default). */
+  down(target: Element, options?: {
+    button?: MouseButton;
+  }): Promise<void>;
+  /** Moves to the target's centre with the button state unchanged. */
+  move(target: Element): Promise<void>;
+  /** Moves to a point 24px below the target. */
+  moveOutside(target: Element): Promise<void>;
+  /** Releases a button (left by default) wherever the pointer is. */
+  up(options?: {
+    button?: MouseButton;
+  }): Promise<void>;
+  /**
+   * Turns the wheel wherever the pointer is, with the modifier keys held
+   * down: a negative `deltaY` scrolls up. One call is one `wheel` event.
+   */
+  wheel(delta: {
+    deltaX?: number;
+    deltaY?: number;
+  }): Promise<void>;
+  /** `down` on the target, then `up`. */
+  click(target: Element, options?: {
+    button?: MouseButton;
+  }): Promise<void>;
+}
+/**
+ * Real keyboard input through Playwright, sent to the focused element. Key
+ * names follow Playwright: `Enter`, `Space`, `Escape`, `ArrowDown`.
+ */
+interface KeyboardInput {
+  /** Presses and holds a key. Calling it again while held sends a repeat. */
+  down(key: string): Promise<void>;
+  up(key: string): Promise<void>;
+  /** `down`, then `up`. */
+  press(key: string): Promise<void>;
+  /** Moves focus with Tab, or Shift+Tab with `isBackward`. */
+  tab(options?: {
+    isBackward?: boolean;
+  }): Promise<void>;
+}
+/**
+ * Real touch input, one finger at a time, through DevTools: only Chromium
+ * takes it, so scenarios that use it declare `needs: ['touch']`. The browser
+ * turns it into touch and pointer events, compatibility mouse events and a
+ * click, and a finger that moves away starts a scroll.
+ */
+interface TouchInput {
+  /** Puts a finger down on the target's centre. */
+  down(target: Element): Promise<void>;
+  /** Moves the finger to the target's centre. */
+  move(target: Element): Promise<void>;
+  /** Moves the finger 24px below the target. */
+  moveOutside(target: Element): Promise<void>;
+  /** Lifts the finger wherever it is. */
+  up(): Promise<void>;
+  /** `down` on the target, then `up`. */
+  tap(target: Element): Promise<void>;
+}
+/** Which real screen reader a scenario runs with. */
+type ScreenReaderName = 'voiceover' | 'nvda';
+/**
+ * A real screen reader driven through Guidepup: VoiceOver on macOS, NVDA on
+ * Windows, both with Chromium. Keys go through the operating system, so the
+ * screen reader hears them as a user's and speaks what they do. Only in
+ * scenarios that declare `needs: ['screenReader']`, which run nightly.
+ *
+ * The screen readers word things differently (`check box` in NVDA,
+ * `checkbox` in VoiceOver), so scenarios match what they need to hear, not
+ * whole phrases.
+ */
+interface ScreenReaderInput {
+  /** Which screen reader runs. */
+  readonly name: ScreenReaderName;
+  /**
+   * Clicks `element` (a text field before the component), waits for the
+   * screen reader to speak it and forgets what it said: the scenario starts
+   * from there, usually with Tab into the component.
+   */
+  startFrom(element: HTMLElement): Promise<void>;
+  /**
+   * Presses a key through the screen reader (Playwright's names: `Tab`,
+   * `ArrowDown`, `Shift+Tab`) and waits until it stops speaking.
+   */
+  press(key: string): Promise<void>;
+  /** Types text through the screen reader, a key per character. */
+  type(text: string): Promise<void>;
+  /** Moves the screen reader's own cursor to the next item. */
+  next(): Promise<void>;
+  /**
+   * What the screen reader holds for the element with keyboard focus: NVDA
+   * reads it again (NVDA+Tab), VoiceOver gives its cursor's item text. A
+   * check that holds when the speech on arrival is cut short.
+   */
+  readFocus(): Promise<string>;
+  /**
+   * What it has said since `startFrom` or the last call: each key's phrases
+   * in order, joined with ` / `.
+   */
+  spoken(): Promise<string>;
+}
+/** Input a scenario needs beyond mouse and keyboard. */
+type InputNeed = 'touch' | 'screenReader';
+interface ScenarioContext<Props, State> {
+  /** Mounts the suite's component through the adapter under test. */
+  mount(options: MountOptions<Props>): Promise<Mounted<Props, State>>;
+  pointer: PointerInput;
+  keyboard: KeyboardInput;
+  /** Only in scenarios that declare `needs: ['touch']`. */
+  touch: TouchInput;
+  /** Only in scenarios that declare `needs: ['screenReader']`. */
+  screenReader: ScreenReaderInput;
+  /**
+   * Reads the whole document with the virtual screen reader and returns every
+   * phrase, from `document` to `end of document`.
+   */
+  spoken(): Promise<string[]>;
+  /**
+   * Starts hearing live regions with the virtual screen reader. The returned
+   * function gives what they have announced since, in order, each phrase
+   * prefixed with its politeness: `assertive: Saved`. Listening lasts until
+   * the scenario ends, and `spoken()` can't run meanwhile.
+   */
+  listen(): Promise<() => Promise<string[]>>;
+}
+type ScenarioRun<Props, State> = (context: ScenarioContext<Props, State>) => Promise<void>;
+interface ScenarioOptions {
+  /** Roadmap phase whose features the scenario needs. Default 1. */
+  readonly phase?: number;
+  /**
+   * Input beyond mouse and keyboard. Where the browser can't take it, the
+   * scenario is skipped; a scenario that needs a real screen reader runs
+   * only where one runs.
+   */
+  readonly needs?: readonly InputNeed[];
+}
+interface Scenario<Props, State> {
+  readonly kind: 'scenario';
+  readonly name: string;
+  readonly phase: number;
+  readonly needs: readonly InputNeed[];
+  readonly run: ScenarioRun<Props, State>;
+}
+interface ScenarioGroup<Props, State> {
+  readonly kind: 'group';
+  readonly name: string;
+  readonly children: readonly (Scenario<Props, State> | ScenarioGroup<Props, State>)[];
+}
+interface ConformanceSuite<Props, State> {
+  /** Definition name: `button`. */
+  readonly component: string;
+  readonly children: readonly (Scenario<Props, State> | ScenarioGroup<Props, State>)[];
+}
+interface ConformanceBuilder<Props, State> {
+  scenario(name: string, run: ScenarioRun<Props, State>, options?: ScenarioOptions): void;
+  group(name: string, define: () => void): void;
+}
+/**
+ * Declares a component's conformance suite:
+ *
+ * ```ts
+ * export const buttonConformance = defineConformance<ButtonProps, ButtonState>(
+ *   'button',
+ *   ({ scenario, group }) => {
+ *     group('keyboard', () => {
+ *       scenario('Enter presses on keyup', async ({ mount, keyboard }) => { … });
+ *     });
+ *   },
+ * );
+ * ```
+ */
+declare function defineConformance<Props, State>(component: string, define: (builder: ConformanceBuilder<Props, State>) => void): ConformanceSuite<Props, State>;
+//#endregion
+export { h as A, RenderedRows as C, TemplateNode as D, TemplateElement as E, partSelector as F, renderTemplate as I, rows as L, isRows as M, nested as N, TemplateRows as O, partName as P, templateParts as R, RenderTemplateOptions as S, TemplateComponent as T, ConformanceAdapter as _, MouseButton as a, Mounted as b, ScenarioContext as c, ScenarioRun as d, ScreenReaderInput as f, AdapterMount as g, defineConformance as h, KeyboardInput as i, isNested as j, VIRTUALIZER as k, ScenarioGroup as l, TouchInput as m, ConformanceSuite as n, PointerInput as o, ScreenReaderName as p, InputNeed as r, Scenario as s, ConformanceBuilder as t, ScenarioOptions as u, MountOptions as v, TemplateAttrs as w, RecordedEvent as x, MountRequest as y };
+//# sourceMappingURL=scenario-DMaR4JJc.d.ts.map

package/dist/template-Cn6bp45u.js

@@ -0,0 +1,152 @@
+import { partMarker } from "@uniaria/core";
+//#region src/conformance/template.ts
+/**
+* Adapter-neutral markup for conformance scenarios. A scenario describes the
+* DOM a consumer would write — part elements, their content and the
+* attributes the consumer owns — and each adapter renders it its own way:
+* React spreads part props onto these elements, the custom element wraps them
+* in its host. Scenarios never import a definition, so they can be written
+* before the implementation exists.
+*/
+/**
+* Builds a template element: `h('button', { part: 'root' }, 'Save')`. The
+* `part` key names the UniAria part; every other key is a consumer-owned
+* attribute.
+*/
+function h(tag, attrs, ...children) {
+	const { part, ...rest } = attrs ?? {};
+	return part === void 0 ? {
+		tag,
+		attrs: rest,
+		children
+	} : {
+		tag,
+		part,
+		attrs: rest,
+		children
+	};
+}
+/**
+* Nests another component: `nested('checkbox', { value: 'email' }, …)`.
+* Its children's `part`s are its own parts.
+*/
+function nested(component, props, ...children) {
+	return {
+		component,
+		props: props ?? {},
+		children
+	};
+}
+/**
+* Rows rendered from the component's `renderedKeys` and `renderedSections`:
+* `rows(({ keys }) => keys.map((key) => h('li', { part: 'option', 'data-key': key }, key)))`.
+* Each row's top element carries `data-key`, as a consumer's keyed list does.
+*/
+function rows(render) {
+	return { rows: render };
+}
+/** Whether a node is a nested component. */
+function isNested(node) {
+	return typeof node !== "string" && "component" in node;
+}
+/** Whether a node is rows rendered from the component's state. */
+function isRows(node) {
+	return typeof node !== "string" && "rows" in node;
+}
+/**
+* Stands for `virtualizer` from `@uniaria/core/virtual` in a scenario's
+* props: scenarios never import the implementation, so each adapter passes
+* the real one in its place.
+*/
+const VIRTUALIZER = Symbol.for("uniaria.conformance.virtualizer");
+/**
+* The component's part elements in document order, for adapters that render
+* templates; nested components' parts and rows are left out.
+*/
+function templateParts(nodes) {
+	const found = [];
+	const walk = (list) => {
+		for (const node of list) {
+			if (typeof node === "string" || isNested(node) || isRows(node)) continue;
+			if (node.part !== void 0) found.push(node);
+			walk(node.children);
+		}
+	};
+	walk(nodes);
+	return found;
+}
+/** `[attribute="value"]` for a part's marker. */
+function markerSelector(component, part, isOutside = false) {
+	const [attribute, value] = partMarker(component, part, isOutside);
+	return `[${attribute}="${value}"]`;
+}
+/**
+* The CSS selector for a part of `component` (root AGENTS.md → Part
+* markers): the root by `data-uni`, a part outside the root by
+* `data-uni-part`, any other part by its `data-element` inside the root,
+* minus those inside another component's root. A part no root is around
+* counts too, as in a component rendered without its root, which has nothing
+* else to scope its parts by. One compound, so `[data-key="…"]` can follow
+* it.
+*/
+function partSelector(component, part) {
+	const root = markerSelector(component, "root");
+	if (part === "root") return root;
+	const marker = markerSelector(component, part);
+	return `:is(${markerSelector(component, part, true)}, ${root} ${marker}:not(${root} [data-uni]:not(${root}) *), ${marker}:not([data-uni] *))`;
+}
+/** Which part of `component` an element is, by its markers. */
+function partName(element, component) {
+	if (element.getAttribute("data-uni") === component) return "root";
+	const outside = element.getAttribute("data-uni-part");
+	if (outside?.startsWith(`${component}-`)) return outside.slice(component.length + 1).replace(/-([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+	const marker = element.getAttribute("data-element");
+	if (!marker) return void 0;
+	const part = marker.charAt(0).toLowerCase() + marker.slice(1);
+	return element.matches(partSelector(component, part)) ? part : void 0;
+}
+/**
+* Renders a template of the component `component` to real DOM, marking part
+* elements the way a consumer of the custom elements would (`partMarker()`):
+* the root with `data-uni`, a part outside the root with `data-uni-part`,
+* the others with `data-element`.
+*/
+function renderTemplate(nodes, doc, component, { decorate, host, rowsIn, outsideParts } = {}) {
+	const fragment = doc.createDocumentFragment();
+	const append = (parent, list, owner = component) => {
+		for (const node of list) {
+			if (typeof node === "string") {
+				parent.appendChild(doc.createTextNode(node));
+				continue;
+			}
+			if (isRows(node)) {
+				if (!rowsIn) throw new Error("The template has rows, which need the component.");
+				rowsIn(node, parent);
+				continue;
+			}
+			if (isNested(node)) {
+				if (!host) throw new Error(`The template nests "${node.component}", which needs a host.`);
+				const element = host(node);
+				append(element, node.children, node.component);
+				parent.appendChild(element);
+				continue;
+			}
+			const element = doc.createElement(node.tag);
+			for (const [name, value] of Object.entries(node.attrs)) element.setAttribute(name, value);
+			const { part } = node;
+			if (part !== void 0) {
+				const isOutside = outsideParts?.(owner).includes(part) ?? false;
+				element.setAttribute(...partMarker(owner, part, isOutside));
+			}
+			if (part !== void 0) decorate?.(element, node);
+			append(element, node.children, owner);
+			parent.appendChild(element);
+		}
+	};
+	append(fragment, nodes);
+	return fragment;
+}
+//#endregion
+export { nested as a, renderTemplate as c, isRows as i, rows as l, h as n, partName as o, isNested as r, partSelector as s, VIRTUALIZER as t, templateParts as u };
+
+//# sourceMappingURL=template-Cn6bp45u.js.map

package/dist/template-Cn6bp45u.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-Cn6bp45u.js","names":[],"sources":["../src/conformance/template.ts"],"sourcesContent":["/**\n * Adapter-neutral markup for conformance scenarios. A scenario describes the\n * DOM a consumer would write — part elements, their content and the\n * attributes the consumer owns — and each adapter renders it its own way:\n * React spreads part props onto these elements, the custom element wraps them\n * in its host. Scenarios never import a definition, so they can be written\n * before the implementation exists.\n */\n\nimport { partMarker } from '@uniaria/core';\n\nexport interface TemplateElement {\n  /** Tag name, as the consumer would write it (`button`, `a`, `div`). */\n  readonly tag: string;\n  /** The UniAria part this element is, if any (`root`, `trigger`). */\n  readonly part?: string;\n  /** Consumer-owned attributes, with DOM names (`class`, `for`, `aria-label`). */\n  readonly attrs: Readonly<Record<string, string>>;\n  readonly children: readonly TemplateNode[];\n}\n\n/**\n * Another UniAria component inside the markup, such as a checkbox in its group.\n * React renders it with its own `useComponent()`; custom elements wrap its\n * children in its own host.\n */\nexport interface TemplateComponent {\n  /** The nested component's definition name: `checkbox`. */\n  readonly component: string;\n  /** Its props, passed the way the adapter's consumers pass them. */\n  readonly props: Readonly<Record<string, unknown>>;\n  /** Its markup: part elements in it are its own parts. */\n  readonly children: readonly TemplateNode[];\n}\n\n/** What a `rows()` node renders from (Listbox virtualization spec). */\nexport interface RenderedRows {\n  /** The component's `renderedKeys`: the options to render, in list order. */\n  readonly keys: readonly string[];\n  /** Its `renderedSections`: the groups to render, in list order. */\n  readonly sections: readonly string[];\n}\n\n/**\n * Rows the consumer renders from the component's public state rather than\n * from every item, as a virtualized list's consumer does. React renders\n * them in a child component that selects `renderedKeys` and\n * `renderedSections`, so the owner never renders again for them; custom\n * elements render them again on `renderedkeyschange`, synchronously,\n * keeping each element whose part and `data-key` stay.\n */\nexport interface TemplateRows {\n  readonly rows: (rendered: RenderedRows) => readonly TemplateNode[];\n}\n\n/** An element, a nested component, rows or a text node. */\nexport type TemplateNode =\n  TemplateElement | TemplateComponent | TemplateRows | string;\n\nexport type TemplateAttrs = Readonly<Record<string, string>> & {\n  readonly part?: string;\n};\n\n/**\n * Builds a template element: `h('button', { part: 'root' }, 'Save')`. The\n * `part` key names the UniAria part; every other key is a consumer-owned\n * attribute.\n */\nexport function h(\n  tag: string,\n  attrs?: TemplateAttrs | null,\n  ...children: TemplateNode[]\n): TemplateElement {\n  const { part, ...rest } = attrs ?? {};\n  return part === undefined\n    ? { tag, attrs: rest, children }\n    : { tag, part, attrs: rest, children };\n}\n\n/**\n * Nests another component: `nested('checkbox', { value: 'email' }, …)`.\n * Its children's `part`s are its own parts.\n */\nexport function nested(\n  component: string,\n  props?: Readonly<Record<string, unknown>> | null,\n  ...children: TemplateNode[]\n): TemplateComponent {\n  return { component, props: props ?? {}, children };\n}\n\n/**\n * Rows rendered from the component's `renderedKeys` and `renderedSections`:\n * `rows(({ keys }) => keys.map((key) => h('li', { part: 'option', 'data-key': key }, key)))`.\n * Each row's top element carries `data-key`, as a consumer's keyed list does.\n */\nexport function rows(\n  render: (rendered: RenderedRows) => readonly TemplateNode[],\n): TemplateRows {\n  return { rows: render };\n}\n\n/** Whether a node is a nested component. */\nexport function isNested(node: TemplateNode): node is TemplateComponent {\n  return typeof node !== 'string' && 'component' in node;\n}\n\n/** Whether a node is rows rendered from the component's state. */\nexport function isRows(node: TemplateNode): node is TemplateRows {\n  return typeof node !== 'string' && 'rows' in node;\n}\n\n/**\n * Stands for `virtualizer` from `@uniaria/core/virtual` in a scenario's\n * props: scenarios never import the implementation, so each adapter passes\n * the real one in its place.\n */\nexport const VIRTUALIZER: unique symbol = Symbol.for(\n  'uniaria.conformance.virtualizer',\n);\n\n/**\n * The component's part elements in document order, for adapters that render\n * templates; nested components' parts and rows are left out.\n */\nexport function templateParts(\n  nodes: readonly TemplateNode[],\n): TemplateElement[] {\n  const found: TemplateElement[] = [];\n  const walk = (list: readonly TemplateNode[]) => {\n    for (const node of list) {\n      if (typeof node === 'string' || isNested(node) || isRows(node)) continue;\n      if (node.part !== undefined) found.push(node);\n      walk(node.children);\n    }\n  };\n  walk(nodes);\n  return found;\n}\n\n/** `[attribute=\"value\"]` for a part's marker. */\nfunction markerSelector(component: string, part: string, isOutside = false) {\n  const [attribute, value] = partMarker(component, part, isOutside);\n  return `[${attribute}=\"${value}\"]`;\n}\n\n/**\n * The CSS selector for a part of `component` (root AGENTS.md → Part\n * markers): the root by `data-uni`, a part outside the root by\n * `data-uni-part`, any other part by its `data-element` inside the root,\n * minus those inside another component's root. A part no root is around\n * counts too, as in a component rendered without its root, which has nothing\n * else to scope its parts by. One compound, so `[data-key=\"…\"]` can follow\n * it.\n */\nexport function partSelector(component: string, part: string): string {\n  const root = markerSelector(component, 'root');\n  if (part === 'root') return root;\n  const marker = markerSelector(component, part);\n  return (\n    `:is(${markerSelector(component, part, true)}, ` +\n    `${root} ${marker}:not(${root} [data-uni]:not(${root}) *), ` +\n    `${marker}:not([data-uni] *))`\n  );\n}\n\n/** Which part of `component` an element is, by its markers. */\nexport function partName(\n  element: Element,\n  component: string,\n): string | undefined {\n  if (element.getAttribute('data-uni') === component) return 'root';\n  const outside = element.getAttribute('data-uni-part');\n  if (outside?.startsWith(`${component}-`)) {\n    return outside\n      .slice(component.length + 1)\n      .replace(/-([a-z0-9])/g, (_, letter: string) => letter.toUpperCase());\n  }\n  const marker = element.getAttribute('data-element');\n  if (!marker) return undefined;\n  const part = marker.charAt(0).toLowerCase() + marker.slice(1);\n  return element.matches(partSelector(component, part)) ? part : undefined;\n}\n\n/** How `renderTemplate()` renders what only the adapter knows. */\nexport interface RenderTemplateOptions {\n  /** Adds attributes to part elements as they are created. */\n  readonly decorate?: (element: HTMLElement, node: TemplateElement) => void;\n  /** Creates the element for a nested component; its children go into it. */\n  readonly host?: (node: TemplateComponent) => HTMLElement;\n  /** Is told where a `rows()` node goes, and renders it there itself. */\n  readonly rowsIn?: (node: TemplateRows, parent: ParentNode) => void;\n  /** A component's parts outside its root: its definition's `outsideParts`. */\n  readonly outsideParts?: (component: string) => readonly string[];\n}\n\n/**\n * Renders a template of the component `component` to real DOM, marking part\n * elements the way a consumer of the custom elements would (`partMarker()`):\n * the root with `data-uni`, a part outside the root with `data-uni-part`,\n * the others with `data-element`.\n */\nexport function renderTemplate(\n  nodes: readonly TemplateNode[],\n  doc: Document,\n  component: string,\n  { decorate, host, rowsIn, outsideParts }: RenderTemplateOptions = {},\n): DocumentFragment {\n  const fragment = doc.createDocumentFragment();\n  const append = (\n    parent: ParentNode,\n    list: readonly TemplateNode[],\n    owner = component,\n  ) => {\n    for (const node of list) {\n      if (typeof node === 'string') {\n        parent.appendChild(doc.createTextNode(node));\n        continue;\n      }\n      if (isRows(node)) {\n        if (!rowsIn) {\n          throw new Error('The template has rows, which need the component.');\n        }\n        rowsIn(node, parent);\n        continue;\n      }\n      if (isNested(node)) {\n        if (!host) {\n          throw new Error(\n            `The template nests \"${node.component}\", which needs a host.`,\n          );\n        }\n        const element = host(node);\n        append(element, node.children, node.component);\n        parent.appendChild(element);\n        continue;\n      }\n      const element = doc.createElement(node.tag);\n      for (const [name, value] of Object.entries(node.attrs)) {\n        element.setAttribute(name, value);\n      }\n      const { part } = node;\n      if (part !== undefined) {\n        const isOutside = outsideParts?.(owner).includes(part) ?? false;\n        element.setAttribute(...partMarker(owner, part, isOutside));\n      }\n      if (part !== undefined) decorate?.(element, node);\n      append(element, node.children, owner);\n      parent.appendChild(element);\n    }\n  };\n  append(fragment, nodes);\n  return fragment;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@uniaria/testing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Testing tools for UniAria: test instances without a framework, the conformance suite runner and screen-reader helpers",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "uniaria-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "uniaria-source": "./src/browser.ts",
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./commands": {
+      "uniaria-source": "./src/commands.ts",
+      "types": "./dist/commands.d.ts",
+      "default": "./dist/commands.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tenphi/uniaria.git",
+    "directory": "packages/testing"
+  },
+  "keywords": [
+    "headless",
+    "ui",
+    "testing",
+    "accessibility",
+    "screen-reader"
+  ],
+  "author": "Andrey Yamanov",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/tenphi/uniaria/issues"
+  },
+  "homepage": "https://github.com/tenphi/uniaria#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@guidepup/virtual-screen-reader": "^0.33.0",
+    "@uniaria/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@guidepup/guidepup": "^0.35.0",
+    "@vitest/browser-playwright": "^5.0.0",
+    "vitest": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@guidepup/guidepup": {
+      "optional": true
+    },
+    "@vitest/browser-playwright": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@guidepup/guidepup": "^0.35.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }