@orkestrel/test 0.0.4 → 0.0.6

package/dist/src/browser/index.js

@@ -0,0 +1,619 @@
+import { page, userEvent } from "vitest/browser";
+//#region src/browser/constants.ts
+/**
+* The interactive ARIA roles a bare accessible name is searched across.
+*
+* @remarks
+* A person names a control, not a role, so the one-argument resolver searches every role a control
+* can compute. The two-argument form searches exactly the role it is given, which is how a name
+* shared by a tab and its panel is disambiguated.
+*/
+var ACCESSIBLE_ROLES = Object.freeze([
+	"button",
+	"checkbox",
+	"combobox",
+	"link",
+	"listbox",
+	"menuitem",
+	"option",
+	"radio",
+	"searchbox",
+	"slider",
+	"spinbutton",
+	"switch",
+	"tab",
+	"tabpanel",
+	"textbox",
+	"treeitem"
+]);
+//#endregion
+//#region src/browser/helpers.ts
+/**
+* Determines whether a rectangle lies wholly outside the browser viewport.
+*
+* @param rectangle - The measured client rectangle to inspect.
+* @returns `true` when no part of the rectangle intersects the viewport.
+*
+* @example
+* ```ts
+* isOutsideViewport(element.getBoundingClientRect())
+* ```
+*/
+function isOutsideViewport(rectangle) {
+	return rectangle.bottom <= 0 || rectangle.right <= 0 || rectangle.top >= window.innerHeight || rectangle.left >= window.innerWidth;
+}
+/**
+* Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
+* viewport yet.
+*
+* @param first - The accessible name, or the exact ARIA role when `second` is present.
+* @param second - The accessible name when `first` supplies the role.
+* @returns The one rendered element carrying that name and optional role.
+* @throws When no matching element exists, every match is hidden or unreachable, or several
+* rendered matches make the name ambiguous.
+*
+* @remarks
+* This is the resolver the acting verbs use, so a click does not fail on a target the act itself
+* scrolls into view. Use {@link resolveAccessible} wherever the target must already be on screen.
+*
+* @example
+* ```ts
+* resolveRendered('tab', 'Drafts')
+* ```
+*/
+function resolveRendered(first, second) {
+	const name = second ?? first;
+	const roles = second === void 0 ? ACCESSIBLE_ROLES : [first];
+	const matches = [];
+	for (const role of roles) for (const element of page.getByRole(role, {
+		name,
+		exact: true,
+		includeHidden: true
+	}).elements()) if (element instanceof HTMLElement && !matches.includes(element)) matches.push(element);
+	if (matches.length === 0) throw new Error(`No interactive element has the accessible name "${name}"`);
+	const reachable = matches.filter((element) => {
+		const rectangle = element.getBoundingClientRect();
+		return element.isConnected && element.checkVisibility({
+			checkOpacity: true,
+			checkVisibilityCSS: true
+		}) && rectangle.width > 0 && rectangle.height > 0 && element.tabIndex >= 0 && !element.matches(":disabled, [aria-disabled=\"true\"]") && element.closest("[inert]") === null;
+	});
+	if (reachable.length === 0) throw new Error(`Interactive target "${name}" is not visible and focus-reachable`);
+	if (reachable.length > 1) throw new Error(`Interactive target "${name}" is ambiguous across ${reachable.length} elements`);
+	const [target] = reachable;
+	if (target === void 0) throw new Error(`Interactive target "${name}" could not be resolved`);
+	return target;
+}
+function resolveAccessible(first, second) {
+	const target = resolveRendered(first, second);
+	let rectangle = target.getBoundingClientRect();
+	if (isOutsideViewport(rectangle)) {
+		target.scrollIntoView({
+			block: "nearest",
+			behavior: "instant"
+		});
+		rectangle = target.getBoundingClientRect();
+	}
+	if (isOutsideViewport(rectangle)) throw new Error(`Interactive target "${second ?? first}" is unreachable after scrolling`);
+	return target;
+}
+async function clickAccessible(first, second) {
+	const target = resolveRendered(first, second);
+	await userEvent.click(target);
+}
+/**
+* Clicks one human-reachable control by role and accessible-name text inside a named region.
+*
+* @param region - The containing region's exact accessible name.
+* @param role - The control's exact ARIA role.
+* @param name - The rendered accessible-name text that identifies the control in that region.
+* @returns A promise resolving after trusted activation completes.
+* @throws When the named control is absent, unreachable, or ambiguous inside the region.
+*
+* @remarks
+* Use this form when repeated short verbs such as `Add`, or a line whose status completes its
+* accessible name, need the same region context a person uses to disambiguate them.
+*
+* @example
+* ```ts
+* await clickAccessibleWithin('Ledger', 'button', 'Monthly income')
+* ```
+*/
+async function clickAccessibleWithin(region, role, name) {
+	const reachable = page.getByRole("region", {
+		name: region,
+		exact: true
+	}).getByRole(role, {
+		name,
+		exact: false,
+		includeHidden: true
+	}).elements().filter((element) => {
+		if (!(element instanceof HTMLElement)) return false;
+		const rectangle = element.getBoundingClientRect();
+		return element.isConnected && element.checkVisibility({
+			checkOpacity: true,
+			checkVisibilityCSS: true
+		}) && rectangle.width > 0 && rectangle.height > 0 && element.tabIndex >= 0 && !element.matches(":disabled, [aria-disabled=\"true\"]") && element.closest("[inert]") === null;
+	});
+	if (reachable.length === 0) throw new Error(`Interactive target "${name}" is not reachable inside "${region}"`);
+	if (reachable.length > 1) throw new Error(`Interactive target "${name}" is ambiguous across ${reachable.length} elements inside "${region}"`);
+	const [target] = reachable;
+	if (!(target instanceof HTMLElement)) throw new Error(`Interactive target "${name}" could not be resolved inside "${region}"`);
+	await userEvent.click(target);
+}
+/**
+* Opens or closes one native details disclosure by its rendered summary.
+*
+* @param name - The summary text a person reads.
+* @returns A promise resolving after trusted activation completes.
+* @throws When no visible, focus-reachable native summary has that rendered name, or several do.
+*
+* @remarks
+* Chromium exposes `<summary>` as a native disclosure rather than through an ARIA role accepted by
+* `getByRole`, so this resolver names the platform element and its rendered text directly.
+*
+* @example
+* ```ts
+* await clickDisclosure('Advanced')
+* ```
+*/
+async function clickDisclosure(name) {
+	const reachable = [...document.querySelectorAll("summary")].filter((element) => element.innerText.replaceAll(/\s+/g, " ").trim() === name).filter((element) => {
+		const rectangle = element.getBoundingClientRect();
+		return element.isConnected && element.checkVisibility({
+			checkOpacity: true,
+			checkVisibilityCSS: true
+		}) && rectangle.width > 0 && rectangle.height > 0 && element.tabIndex >= 0 && element.closest("[inert]") === null;
+	});
+	if (reachable.length === 0) throw new Error(`Native disclosure "${name}" is not visible and focus-reachable`);
+	if (reachable.length > 1) throw new Error(`Native disclosure "${name}" is ambiguous across ${reachable.length} elements`);
+	const [target] = reachable;
+	if (target === void 0) throw new Error(`Native disclosure "${name}" could not be resolved`);
+	await userEvent.click(target);
+}
+/**
+* Replaces a named field's value through focus, select-all, deletion, and real keystrokes.
+*
+* @param name - The field's exact accessible name.
+* @param text - The text to type.
+* @returns A promise resolving after every keystroke completes.
+*
+* @example
+* ```ts
+* await typeAccessible('Runs', '3')
+* ```
+*/
+async function typeAccessible(name, text) {
+	await userEvent.click(resolveRendered(name));
+	await userEvent.keyboard("{Control>}a{/Control}{Backspace}");
+	if (text === "") return;
+	await userEvent.keyboard(text.replaceAll("{", "{{").replaceAll("[", "[["));
+}
+/**
+* Replaces a named field's value in one operation, for text too long to type key by key.
+*
+* @param name - The field's exact accessible name.
+* @param text - The text to place in the field.
+* @returns A promise resolving after the browser commits the value.
+*
+* @remarks
+* The provider drives the real element, so the field publishes the same input event a person's
+* typing publishes. Use {@link typeAccessible} wherever the keystrokes themselves are the subject.
+*
+* @example
+* ```ts
+* await fillAccessible('Payload', '{"status":"ready"}')
+* ```
+*/
+async function fillAccessible(name, text) {
+	await userEvent.fill(resolveRendered(name), text);
+}
+/**
+* Presses a browser-keyboard sequence using Vitest's installed user-event syntax.
+*
+* @param keys - The keys or key descriptors to press.
+* @returns A promise resolving after the sequence completes.
+*
+* @example
+* ```ts
+* await pressKeys('{ArrowRight}{Enter}')
+* ```
+*/
+async function pressKeys(keys) {
+	await userEvent.keyboard(keys);
+}
+/**
+* Reaches a named control only through natural forward Tab traversal from the current focus.
+*
+* @param name - The target's exact accessible name.
+* @returns The target after the browser moves focus to it.
+* @throws When one complete traversal cannot reach the target.
+*
+* @example
+* ```ts
+* await traverseAccessible('Evaluate')
+* ```
+*/
+async function traverseAccessible(name) {
+	resolveRendered(name);
+	const cap = document.querySelectorAll("a[href], button, input, select, textarea, [tabindex]").length * 3 + 10;
+	const visited = /* @__PURE__ */ new Set();
+	const trail = [];
+	for (let attempt = 0; attempt < cap; attempt += 1) {
+		await userEvent.tab();
+		const focused = document.activeElement;
+		if (!(focused instanceof HTMLElement) || focused === document.body) continue;
+		let current;
+		try {
+			current = resolveRendered(name);
+		} catch {
+			continue;
+		}
+		if (focused === current) return current;
+		if (visited.has(focused)) break;
+		visited.add(focused);
+		trail.push(`${focused.tagName}:${focused.innerText.slice(0, 20)}`);
+	}
+	throw new Error(`Interactive target "${name}" is not reachable through forward Tab traversal: ${trail.join(" > ")}`);
+}
+/**
+* Reads the normalized visible text of one named region, dialog, table, tab panel, or alert.
+*
+* @param name - The region's exact accessible name.
+* @returns The text a screen reader can perceive in the visible region, including descendant
+* visually-hidden content.
+* @throws When the named region is absent, hidden, or ambiguous.
+*
+* @example
+* ```ts
+* readPerception('Run')
+* ```
+*/
+function readPerception(name) {
+	const matches = [];
+	for (const role of [
+		"alert",
+		"alertdialog",
+		"dialog",
+		"region",
+		"status",
+		"table",
+		"tabpanel"
+	]) for (const element of page.getByRole(role, {
+		name,
+		exact: true,
+		includeHidden: true
+	}).elements()) if (element instanceof HTMLElement && !matches.includes(element)) matches.push(element);
+	const visible = matches.filter((element) => {
+		const rectangle = element.getBoundingClientRect();
+		return element.isConnected && element.checkVisibility({
+			checkOpacity: true,
+			checkVisibilityCSS: true
+		}) && rectangle.width > 0 && rectangle.height > 0;
+	});
+	if (visible.length === 0) throw new Error(`Named region "${name}" is not visible`);
+	if (visible.length > 1) throw new Error(`Named region "${name}" is ambiguous across ${visible.length} elements`);
+	const [region] = visible;
+	if (region === void 0) throw new Error(`Named region "${name}" could not be resolved`);
+	return region.innerText.replaceAll(/\s+/g, " ").trim();
+}
+/**
+* Reads the normalized visible text of the whole page.
+*
+* @returns Every rendered word in the document body, its whitespace runs collapsed and trimmed.
+*
+* @remarks
+* This is the reader for a sentence that spans two regions and for a vocabulary sweep over the
+* words an interface uses. Reach for {@link readPerception} wherever one named region is the
+* subject, because that one throws when the region is missing and this one returns whatever is
+* there.
+*
+* @example
+* ```ts
+* readPage().includes('No cases yet')
+* ```
+*/
+function readPage() {
+	return document.body.innerText.replaceAll(/\s+/g, " ").trim();
+}
+/**
+* Reads the rendered text of the element that currently holds focus.
+*
+* @returns The focused HTML element's trimmed rendered text, including an empty string, or
+* `undefined` when focus rests on a non-HTML element. When nothing holds focus, the browser
+* reports the document body as active, so the whole page's rendered text returns.
+*
+* @example
+* ```ts
+* await traverseAccessible('Evaluate')
+* readFocus() // 'Evaluate'
+* ```
+*/
+function readFocus() {
+	const focused = document.activeElement;
+	return focused instanceof HTMLElement ? focused.innerText.trim() : void 0;
+}
+/**
+* Reads the value a resolved control renders.
+*
+* @param role - The control's exact ARIA role.
+* @param name - The control's exact accessible name.
+* @returns The control's current value.
+* @throws When the target does not resolve, or resolves to an element that carries no value.
+*
+* @remarks
+* A control's value is a rendered fact a person can read, not internal state, so it is read from
+* the resolved element rather than from the component that produced it.
+*
+* @example
+* ```ts
+* readValue('spinbutton', 'Runs') // '3'
+* ```
+*/
+function readValue(role, name) {
+	const control = resolveAccessible(role, name);
+	if (!(control instanceof HTMLInputElement) && !(control instanceof HTMLTextAreaElement) && !(control instanceof HTMLSelectElement)) throw new Error(`Interactive target "${name}" does not carry a value`);
+	return control.value;
+}
+/**
+* Waits for one animation frame to settle pending browser paint work.
+*
+* @returns A promise resolving after one `requestAnimationFrame`.
+*
+* @example
+* ```ts
+* await waitForFrame()
+* ```
+*/
+function waitForFrame() {
+	return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}
+/**
+* Renders trusted fixture markup into a container attached to the document.
+*
+* @param markup - The fixture markup to render.
+* @returns The attached container.
+*
+* @example
+* ```ts
+* const container = render('<button type="button">Save</button>')
+* container.remove()
+* ```
+*/
+function render(markup) {
+	const container = document.createElement("div");
+	container.innerHTML = markup;
+	document.body.append(container);
+	return container;
+}
+/**
+* Measures the WCAG 2.x contrast ratio between an element's computed text and background colors.
+*
+* @param element - The element whose rendered text contrast to measure.
+* @returns The relative-luminance contrast ratio.
+* @throws When the browser does not expose parseable computed colors.
+*
+* @remarks
+* A transparent or translucent background resolves through the element's ancestors: every painted
+* layer from the element up to the first opaque one composites top-over-bottom onto that opaque
+* base, so a 3% surface tint reads as a tint over what shows through it rather than as a
+* full-strength paint. A translucent foreground then resolves against that effective background
+* before luminance is measured.
+*
+* Every element from the target upwards must be reachable, and at least one of them must paint:
+* the measurement throws rather than assuming a white canvas when nothing in the chain declares a
+* background color. The element itself must expose a computed foreground color — a detached
+* element exposes none, and the measurement throws rather than guessing one.
+*
+* @example
+* ```ts
+* const container = render('<p style="background: #000; color: #fff">Ready</p>')
+* contrast(requireValue(container.firstElementChild)) // 21
+* ```
+*/
+function contrast(element) {
+	const foreground = getComputedStyle(element).color.match(/\d+(?:\.\d+)?/g);
+	if (foreground === null || foreground.length < 3) throw new Error("Computed foreground color is unavailable");
+	const layers = [];
+	let current = element;
+	let opaque = false;
+	while (current !== null) {
+		const channels = getComputedStyle(current).backgroundColor.match(/\d+(?:\.\d+)?/g);
+		if (channels !== null && channels.length >= 3) {
+			const layerAlpha = channels[3] === void 0 ? 1 : Number(channels[3]);
+			if (layerAlpha > 0) layers.push([...channels.slice(0, 3).map(Number), layerAlpha]);
+			if (layerAlpha >= 1) {
+				opaque = true;
+				break;
+			}
+		}
+		current = current.parentElement;
+	}
+	if (layers.length === 0) throw new Error("Computed background color is unavailable");
+	const base = layers[layers.length - 1];
+	if (base === void 0) throw new Error("Computed background color is unavailable");
+	let composed = base.slice(0, 3).map((channel) => channel / 255);
+	if (!opaque) composed = [
+		1,
+		1,
+		1
+	];
+	const start = opaque ? layers.length - 2 : layers.length - 1;
+	for (let index = start; index >= 0; index -= 1) {
+		const layer = layers[index];
+		if (layer === void 0) continue;
+		const layerAlpha = layer[3] ?? 1;
+		composed = composed.map((channel, position) => {
+			return (layer[position] ?? 0) / 255 * layerAlpha + channel * (1 - layerAlpha);
+		});
+	}
+	const alpha = foreground[3] === void 0 ? 1 : Number(foreground[3]);
+	const backgroundChannels = composed;
+	const foregroundLinear = foreground.slice(0, 3).map((channel, index) => {
+		const behind = backgroundChannels[index];
+		if (behind === void 0) throw new Error("Computed background channel is unavailable");
+		return Number(channel) / 255 * alpha + behind * (1 - alpha);
+	}).map((channel) => channel <= .04045 ? channel / 12.92 : ((channel + .055) / 1.055) ** 2.4);
+	const backgroundLinear = backgroundChannels.map((channel) => channel <= .04045 ? channel / 12.92 : ((channel + .055) / 1.055) ** 2.4);
+	const foregroundLuminance = .2126 * (foregroundLinear[0] ?? 0) + .7152 * (foregroundLinear[1] ?? 0) + .0722 * (foregroundLinear[2] ?? 0);
+	const backgroundLuminance = .2126 * (backgroundLinear[0] ?? 0) + .7152 * (backgroundLinear[1] ?? 0) + .0722 * (backgroundLinear[2] ?? 0);
+	const lighter = Math.max(foregroundLuminance, backgroundLuminance);
+	const darker = Math.min(foregroundLuminance, backgroundLuminance);
+	return (lighter + .05) / (darker + .05);
+}
+/**
+* Collects every class token the stylesheets loaded into this document actually define.
+*
+* @returns The set of class names reachable in the shipped cascade.
+*
+* @remarks
+* The set is what an authored-class conformance check measures against, so a class no loaded
+* stylesheet defines — an invented utility, a misspelled framework name — is absent from it.
+*
+* @example
+* ```ts
+* readCascade().has('card')
+* ```
+*/
+function readCascade() {
+	const known = /* @__PURE__ */ new Set();
+	const rules = [];
+	for (const sheet of document.styleSheets) rules.push(...sheet.cssRules);
+	while (rules.length > 0) {
+		const rule = rules.pop();
+		if (rule instanceof CSSGroupingRule) rules.push(...rule.cssRules);
+		if (!(rule instanceof CSSStyleRule)) continue;
+		for (const match of rule.selectorText.matchAll(/\.([a-zA-Z][\w-]*)/g)) known.add(String(match[1]));
+	}
+	return known;
+}
+/**
+* Reads the normalized visible text of every element a selector matches, in document order.
+*
+* @param root - The subtree to search.
+* @param selector - The CSS selector naming the rows.
+* @returns One line per matched element, its text runs collapsed and single-space joined.
+*
+* @remarks
+* The line is built from the row's text nodes rather than from `textContent`, because adjacent
+* inline elements carry no whitespace between them in compiled template output and would otherwise
+* read as one run-together word.
+*
+* @example
+* ```ts
+* readRows(container, 'li')
+* ```
+*/
+function readRows(root, selector) {
+	const rows = [];
+	for (const row of root.querySelectorAll(selector)) {
+		const parts = [];
+		const walker = document.createTreeWalker(row, NodeFilter.SHOW_TEXT);
+		while (walker.nextNode() !== null) {
+			const text = (walker.currentNode.textContent ?? "").replaceAll(/\s+/g, " ").trim();
+			if (text !== "") parts.push(text);
+		}
+		rows.push(parts.join(" "));
+	}
+	return rows;
+}
+/**
+* Reads one resolved CSS property from a real browser element.
+*
+* @param element - The element whose resolved style to inspect.
+* @param property - The CSS property name.
+* @returns The browser's resolved property value.
+*
+* @example
+* ```ts
+* style(button, 'padding-left')
+* ```
+*/
+function style(element, property) {
+	return getComputedStyle(element).getPropertyValue(property);
+}
+/**
+* Expands a capture registry across every variant into the filenames a complete portfolio holds.
+*
+* @param states - The registered state names.
+* @param variants - The variants the portfolio is rendered in.
+* @returns One `<state>--<variant>.png` name per pair, each state's variants together, in registry
+* order.
+*
+* @remarks
+* The expansion is the portfolio's own definition of complete, so a duplicate in it is a registry
+* defect a proof reads directly rather than a collision discovered on disk.
+*
+* @example
+* ```ts
+* expandCaptures(['start'], [{ name: 'dark-390', width: 390, height: 844 }])
+* // ['start--dark-390.png']
+* ```
+*/
+function expandCaptures(states, variants) {
+	const files = [];
+	for (const state of states) for (const variant of variants) files.push(`${state}--${variant.name}.png`);
+	return files;
+}
+//#endregion
+//#region src/browser/factories.ts
+/**
+* Creates the capture portfolio one run places its screenshots through.
+*
+* @param options - The state registry, the variant matrix, the variant this run renders, the
+* directory it writes into, and whether it writes at all.
+* @returns The portfolio: its registry expansion, what it has placed, and `place`.
+* @throws When no registered variant carries the name `variant` names.
+*
+* @remarks
+* A disabled portfolio is the ordinary run. `place` then resizes nothing, writes nothing, and
+* records nothing, so a journey calls it unconditionally and a suite with the flag unset pays for
+* none of it. The portfolio refuses an unregistered variant at creation. An enabled run refuses an
+* unregistered state name and a second placement of one state.
+*
+* @example
+* ```ts
+* const portfolio = createPortfolio({
+* 	states: ['start-empty'],
+* 	variants: [{ name: 'dark-390', width: 390, height: 844 }],
+* 	variant: 'dark-390',
+* 	directory: '../../tmp/capture/states',
+* })
+* await portfolio.place('start-empty')
+* ```
+*/
+function createPortfolio(options) {
+	const selected = options.variants.find((candidate) => candidate.name === options.variant);
+	if (selected === void 0) throw new Error(`Capture variant "${options.variant}" is not registered`);
+	const registry = [...options.states];
+	const files = expandCaptures(registry, options.variants);
+	const enabled = options.enabled ?? false;
+	const placed = [];
+	const paths = [];
+	return {
+		variant: options.variant,
+		files,
+		get states() {
+			return [...placed];
+		},
+		get paths() {
+			return [...paths];
+		},
+		async place(state) {
+			if (!enabled) return void 0;
+			if (!registry.includes(state)) throw new Error(`Capture state "${state}" is not registered`);
+			if (placed.includes(state)) throw new Error(`Capture state "${state}" is already placed`);
+			const file = `${state}--${options.variant}.png`;
+			selected.apply?.();
+			if (window.innerWidth !== selected.width || window.innerHeight !== selected.height) await page.viewport(selected.width, selected.height);
+			const written = await page.screenshot({ path: `${options.directory}/${file}` });
+			placed.push(state);
+			paths.push(written);
+			return written;
+		}
+	};
+}
+//#endregion
+export { ACCESSIBLE_ROLES, clickAccessible, clickAccessibleWithin, clickDisclosure, contrast, createPortfolio, expandCaptures, fillAccessible, isOutsideViewport, pressKeys, readCascade, readFocus, readPage, readPerception, readRows, readValue, render, resolveAccessible, resolveRendered, style, traverseAccessible, typeAccessible, waitForFrame };
+
+//# sourceMappingURL=index.js.map