@orkestrel/test 0.0.19 → 0.0.20

package/dist/src/browser/index.d.ts

@@ -975,6 +975,54 @@ export declare function describeFocus(element: Element): string;
  */
 export declare function describeTree(element: Element): string;
 
+/**
+ * Holds the primary pointer button on the control a resolver returns, through the browser provider.
+ *
+ * @param resolve - The resolver that returns the target, called after the held-pointer refusal.
+ * @param name - The target's name, as the refusals voice it.
+ * @returns A promise resolving after the control enters its pressed state.
+ * @throws Thrown when a pointer is already held, the resolver refuses, the target stays outside
+ * the viewport after scrolling, or the press misses. A missed press that also fails to release
+ * carries the release rejection as its cause.
+ *
+ * @remarks
+ * This is the one pointer drive every hold verb shares: the held-marker refusal, a scroll that
+ * brings a wholly off-viewport target into view and a refusal for one that stays outside, the
+ * centre mapped through the tester iframe's painted scale into page coordinates, the trusted move
+ * and press, the marker, a frame wait, and the `:active` read-back that releases before refusing a
+ * missed press. The refusal precedes resolution, so a double hold is refused before an absent
+ * name is.
+ *
+ * @example
+ * ```ts
+ * await driveHold(() => resolveAccessible('Apply'), 'Apply')
+ * await releasePointer()
+ * ```
+ */
+export declare function driveHold(resolve: () => HTMLElement, name: string): Promise<void>;
+
+/**
+ * Reaches the control a resolver returns, only through natural forward Tab traversal from the
+ * current focus.
+ *
+ * @param resolve - The resolver that returns the target, called before the first step and again on
+ * every step, because a framework may replace the node between resolution and focus arrival.
+ * @param name - The target's name, as the refusal voices it.
+ * @returns The target after the browser moves focus to it.
+ * @throws When the resolver refuses, or one complete traversal cannot reach the target.
+ *
+ * @remarks
+ * This is the one loop every traversal verb shares. A step counts only when focus lands on an
+ * element, the traversal is over when focus revisits one, and the cap is counted off
+ * {@link FOCUSABLE_SELECTOR}.
+ *
+ * @example
+ * ```ts
+ * await driveTraversal(() => resolveRendered('Evaluate'), 'Evaluate')
+ * ```
+ */
+export declare function driveTraversal(resolve: () => HTMLElement, name: string): Promise<HTMLElement>;
+
 /**
  * Configures one built element: its class list, its text, and its attributes.
  *
@@ -1292,7 +1340,7 @@ export declare const HEADER_ROLES: Readonly<Record<string, string>>;
  * reading verifies delivery. A missed press releases before refusing; if that release also
  * rejects, the refusal carries it as its cause. Register {@link releasePointer} in teardown
  * before holding; release can produce a click on the pressed control. A rejected button-down send
- * leaves no hold marker.
+ * leaves no hold marker. The hold itself is {@link driveHold}.
  *
  * @example
  * ```ts
@@ -1319,6 +1367,30 @@ export declare function holdAccessible(name: string): Promise<void>;
  */
 export declare function holdAccessible(role: string, name: string): Promise<void>;
 
+/**
+ * Holds the primary pointer button on one 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 the control enters its pressed state.
+ * @throws Thrown when a pointer is already held, the region refuses the target, or the press
+ * misses. A missed press that also fails to release carries the release rejection as its cause.
+ *
+ * @remarks
+ * The resolution is {@link resolveAccessibleWithin} and the hold is {@link driveHold}, so a twin
+ * of the same name in another region is left alone. Register {@link releasePointer} in teardown
+ * before holding.
+ *
+ * @example
+ * ```ts
+ * await holdAccessibleWithin('Ledger', 'button', 'Apply')
+ * await releasePointer()
+ * ```
+ */
+export declare function holdAccessibleWithin(region: string, role: string, name: string): Promise<void>;
+
 /**
  * Hovers one visible, focus-reachable control by its accessible name through the browser provider.
  *
@@ -1617,12 +1689,14 @@ export declare function measureLuminance(color: Color): number;
  */
 export declare const MEDIA_STAGE = "data-media-stage";
 
-/** Configures the tester's print medium and motion preference. */
+/** Configures the tester's print medium, motion preference, and forced colours. */
 export declare interface MediaOptions {
     /** Determines whether the tester lays out for print. Omit it to leave the medium alone. */
     readonly print?: boolean;
     /** Determines whether the tester prefers motion. Omit it to leave the preference alone. */
     readonly motion?: boolean;
+    /** Determines whether the tester runs under forced colours. Omit it to leave the colours alone. */
+    readonly forced?: boolean;
 }
 
 /**
@@ -2618,6 +2692,28 @@ export declare function resolveAccessible(name: string): HTMLElement;
  */
 export declare function resolveAccessible(role: string, name: string): HTMLElement;
 
+/**
+ * Resolves 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 The one reachable element carrying that role and name inside the region.
+ * @throws When the named control is absent, unreachable, or ambiguous inside the region.
+ *
+ * @remarks
+ * The region's name is matched exactly and the control's name loosely, over a computed name that
+ * includes hidden subtrees, so a glyph joins the text rather than displacing it. One pass answers
+ * this: a control the region cannot reach is refused whether it is absent or hidden. This is the
+ * resolver the region-scoped verbs share.
+ *
+ * @example
+ * ```ts
+ * resolveAccessibleWithin('Ledger', 'button', 'Monthly income')
+ * ```
+ */
+export declare function resolveAccessibleWithin(region: string, role: string, name: string): HTMLElement;
+
 /**
  * Resolves one rendered, focus-reachable interactive element without requiring it to intersect the
  * viewport yet.
@@ -2663,17 +2759,20 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
 export declare function sendProtocol(method: string, params: Readonly<Record<string, unknown>>): Promise<void>;
 
 /**
- * Stages the tester's print medium and motion preference through the browser provider.
+ * Stages the tester's print medium, motion preference, and forced colours through the browser
+ * provider.
  *
  * @param options - The media axes to override.
- * @returns A promise resolving after a bounded read-back for `print: true` and either
- * `motion` value. A `print: false` stage is sent and followed by a frame wait without a read-back.
+ * @returns A promise resolving after a bounded read-back for `print: true`, either `motion` value,
+ * and either `forced` value. A `print: false` stage is sent and followed by a frame wait without a
+ * read-back.
  * @throws Thrown when no axis is supplied or a staged query does not reach the tester.
  *
  * @remarks
  * If `print` is true, uses print; if false, uses screen. If `motion` is true, uses no preference;
- * if false, uses reduced motion. The print medium, reduced motion, colour scheme, and forced colours
- * keep their effective readings when omitted. Any other emulated feature the provider configured
+ * if false, uses reduced motion. If `forced` is true, uses active forced colours; if false, uses
+ * none. The print medium, reduced motion, colour scheme, and forced colours keep their effective
+ * readings when omitted. Any other emulated feature the provider configured
  * is cleared. Each staged query waits up to 1000 milliseconds, polling every 10 milliseconds.
  * A refused read-back restores the carried pre-call readings before throwing and can take two
  * budgets. A restoration failure is attached as the refusal's cause. Register
@@ -2781,6 +2880,9 @@ export declare interface StorageOptions {
  * @returns The target after the browser moves focus to it.
  * @throws When one complete traversal cannot reach the target.
  *
+ * @remarks
+ * The loop is {@link driveTraversal} over {@link resolveRendered}.
+ *
  * @example
  * ```ts
  * await traverseAccessible('Evaluate')
@@ -2788,6 +2890,27 @@ export declare interface StorageOptions {
  */
 export declare function traverseAccessible(name: string): Promise<HTMLElement>;
 
+/**
+ * Reaches a control by role and accessible-name text inside a named region, only through natural
+ * forward Tab traversal from the current focus.
+ *
+ * @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 The target after the browser moves focus to it.
+ * @throws When the region refuses the target, or one complete traversal cannot reach it.
+ *
+ * @remarks
+ * The resolution is {@link resolveAccessibleWithin} and the loop is {@link driveTraversal}, so a
+ * twin of the same name earlier in the tab order is passed over rather than reached.
+ *
+ * @example
+ * ```ts
+ * await traverseAccessibleWithin('Ledger', 'button', 'Evaluate')
+ * ```
+ */
+export declare function traverseAccessibleWithin(region: string, role: string, name: string): Promise<HTMLElement>;
+
 /**
  * Replaces a named field's value through focus, select-all, deletion, and real keystrokes.
  *

package/dist/src/browser/index.js

@@ -503,6 +503,29 @@ async function clickAccessible(first, second) {
 * ```
 */
 async function clickAccessibleWithin(region, role, name) {
+	await userEvent.click(resolveAccessibleWithin(region, role, name));
+}
+/**
+* Resolves 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 The one reachable element carrying that role and name inside the region.
+* @throws When the named control is absent, unreachable, or ambiguous inside the region.
+*
+* @remarks
+* The region's name is matched exactly and the control's name loosely, over a computed name that
+* includes hidden subtrees, so a glyph joins the text rather than displacing it. One pass answers
+* this: a control the region cannot reach is refused whether it is absent or hidden. This is the
+* resolver the region-scoped verbs share.
+*
+* @example
+* ```ts
+* resolveAccessibleWithin('Ledger', 'button', 'Monthly income')
+* ```
+*/
+function resolveAccessibleWithin(region, role, name) {
 	const reachable = page.getByRole("region", {
 		name: region,
 		exact: true
@@ -515,7 +538,7 @@ async function clickAccessibleWithin(region, role, name) {
 	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);
+	return target;
 }
 /**
 * Opens or closes one native details disclosure by its rendered summary.
@@ -573,10 +596,67 @@ async function hoverAccessible(first, second) {
 	await userEvent.hover(resolveRendered(first, second));
 }
 async function holdAccessible(first, second) {
+	await driveHold(() => second === void 0 ? resolveAccessible(first) : resolveAccessible(first, second), second ?? first);
+}
+/**
+* Holds the primary pointer button on one 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 the control enters its pressed state.
+* @throws Thrown when a pointer is already held, the region refuses the target, or the press
+* misses. A missed press that also fails to release carries the release rejection as its cause.
+*
+* @remarks
+* The resolution is {@link resolveAccessibleWithin} and the hold is {@link driveHold}, so a twin
+* of the same name in another region is left alone. Register {@link releasePointer} in teardown
+* before holding.
+*
+* @example
+* ```ts
+* await holdAccessibleWithin('Ledger', 'button', 'Apply')
+* await releasePointer()
+* ```
+*/
+async function holdAccessibleWithin(region, role, name) {
+	await driveHold(() => resolveAccessibleWithin(region, role, name), name);
+}
+/**
+* Holds the primary pointer button on the control a resolver returns, through the browser provider.
+*
+* @param resolve - The resolver that returns the target, called after the held-pointer refusal.
+* @param name - The target's name, as the refusals voice it.
+* @returns A promise resolving after the control enters its pressed state.
+* @throws Thrown when a pointer is already held, the resolver refuses, the target stays outside
+* the viewport after scrolling, or the press misses. A missed press that also fails to release
+* carries the release rejection as its cause.
+*
+* @remarks
+* This is the one pointer drive every hold verb shares: the held-marker refusal, a scroll that
+* brings a wholly off-viewport target into view and a refusal for one that stays outside, the
+* centre mapped through the tester iframe's painted scale into page coordinates, the trusted move
+* and press, the marker, a frame wait, and the `:active` read-back that releases before refusing a
+* missed press. The refusal precedes resolution, so a double hold is refused before an absent
+* name is.
+*
+* @example
+* ```ts
+* await driveHold(() => resolveAccessible('Apply'), 'Apply')
+* await releasePointer()
+* ```
+*/
+async function driveHold(resolve, name) {
 	const held = document.documentElement.getAttribute(POINTER_HOLD);
 	if (held !== null) throw new Error(`Pointer is already held at ${held}`);
-	const target = second === void 0 ? resolveAccessible(first) : resolveAccessible(first, second);
+	const target = resolve();
+	if (isOutsideViewport(target.getBoundingClientRect())) target.scrollIntoView({
+		block: "nearest",
+		behavior: "instant"
+	});
 	const box = target.getBoundingClientRect();
+	if (isOutsideViewport(box)) throw new Error(`Interactive target "${name}" is unreachable after scrolling`);
 	const frame = window.frameElement?.getBoundingClientRect();
 	const scale = frame === void 0 ? 1 : frame.width / window.innerWidth;
 	const x = (frame?.left ?? 0) + (box.left + box.width / 2) * scale;
@@ -600,9 +680,9 @@ async function holdAccessible(first, second) {
 		try {
 			await releasePointer();
 		} catch (cause) {
-			throw new Error(`Interactive target "${second ?? first}" did not enter the pressed state`, { cause });
+			throw new Error(`Interactive target "${name}" did not enter the pressed state`, { cause });
 		}
-		throw new Error(`Interactive target "${second ?? first}" did not enter the pressed state`);
+		throw new Error(`Interactive target "${name}" did not enter the pressed state`);
 	}
 }
 /**
@@ -734,13 +814,61 @@ async function pressKeys(keys) {
 * @returns The target after the browser moves focus to it.
 * @throws When one complete traversal cannot reach the target.
 *
+* @remarks
+* The loop is {@link driveTraversal} over {@link resolveRendered}.
+*
 * @example
 * ```ts
 * await traverseAccessible('Evaluate')
 * ```
 */
 async function traverseAccessible(name) {
-	resolveRendered(name);
+	return driveTraversal(() => resolveRendered(name), name);
+}
+/**
+* Reaches a control by role and accessible-name text inside a named region, only through natural
+* forward Tab traversal from the current focus.
+*
+* @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 The target after the browser moves focus to it.
+* @throws When the region refuses the target, or one complete traversal cannot reach it.
+*
+* @remarks
+* The resolution is {@link resolveAccessibleWithin} and the loop is {@link driveTraversal}, so a
+* twin of the same name earlier in the tab order is passed over rather than reached.
+*
+* @example
+* ```ts
+* await traverseAccessibleWithin('Ledger', 'button', 'Evaluate')
+* ```
+*/
+async function traverseAccessibleWithin(region, role, name) {
+	return driveTraversal(() => resolveAccessibleWithin(region, role, name), name);
+}
+/**
+* Reaches the control a resolver returns, only through natural forward Tab traversal from the
+* current focus.
+*
+* @param resolve - The resolver that returns the target, called before the first step and again on
+* every step, because a framework may replace the node between resolution and focus arrival.
+* @param name - The target's name, as the refusal voices it.
+* @returns The target after the browser moves focus to it.
+* @throws When the resolver refuses, or one complete traversal cannot reach the target.
+*
+* @remarks
+* This is the one loop every traversal verb shares. A step counts only when focus lands on an
+* element, the traversal is over when focus revisits one, and the cap is counted off
+* {@link FOCUSABLE_SELECTOR}.
+*
+* @example
+* ```ts
+* await driveTraversal(() => resolveRendered('Evaluate'), 'Evaluate')
+* ```
+*/
+async function driveTraversal(resolve, name) {
+	resolve();
 	const cap = document.querySelectorAll(FOCUSABLE_SELECTOR).length * 3 + 10;
 	const visited = /* @__PURE__ */ new Set();
 	const trail = [];
@@ -750,7 +878,7 @@ async function traverseAccessible(name) {
 		if (!(focused instanceof HTMLElement) || focused === document.body) continue;
 		let current;
 		try {
-			current = resolveRendered(name);
+			current = resolve();
 		} catch {
 			continue;
 		}
@@ -2552,17 +2680,20 @@ async function releasePane() {
 	if (Number.isFinite(width) && Number.isFinite(height)) await page.viewport(width, height);
 }
 /**
-* Stages the tester's print medium and motion preference through the browser provider.
+* Stages the tester's print medium, motion preference, and forced colours through the browser
+* provider.
 *
 * @param options - The media axes to override.
-* @returns A promise resolving after a bounded read-back for `print: true` and either
-* `motion` value. A `print: false` stage is sent and followed by a frame wait without a read-back.
+* @returns A promise resolving after a bounded read-back for `print: true`, either `motion` value,
+* and either `forced` value. A `print: false` stage is sent and followed by a frame wait without a
+* read-back.
 * @throws Thrown when no axis is supplied or a staged query does not reach the tester.
 *
 * @remarks
 * If `print` is true, uses print; if false, uses screen. If `motion` is true, uses no preference;
-* if false, uses reduced motion. The print medium, reduced motion, colour scheme, and forced colours
-* keep their effective readings when omitted. Any other emulated feature the provider configured
+* if false, uses reduced motion. If `forced` is true, uses active forced colours; if false, uses
+* none. The print medium, reduced motion, colour scheme, and forced colours keep their effective
+* readings when omitted. Any other emulated feature the provider configured
 * is cleared. Each staged query waits up to 1000 milliseconds, polling every 10 milliseconds.
 * A refused read-back restores the carried pre-call readings before throwing and can take two
 * budgets. A restoration failure is attached as the refusal's cause. Register
@@ -2577,16 +2708,17 @@ async function releasePane() {
 async function stageMedia(options) {
 	const print = options.print;
 	const motion = options.motion;
-	if (print === void 0 && motion === void 0) throw new Error("Media emulation was staged with nothing to emulate");
+	const forced = options.forced;
+	if (print === void 0 && motion === void 0 && forced === void 0) throw new Error("Media emulation was staged with nothing to emulate");
 	const media = matchMedia("print").matches ? "print" : "screen";
 	const reduced = matchMedia("(prefers-reduced-motion: reduce)").matches;
 	const dark = matchMedia("(prefers-color-scheme: dark)").matches;
-	const forced = matchMedia("(forced-colors: active)").matches;
+	const active = matchMedia("(forced-colors: active)").matches;
 	if (!document.documentElement.hasAttribute("data-media-stage")) document.documentElement.setAttribute(MEDIA_STAGE, [
 		media === "print",
 		reduced,
 		dark,
-		forced
+		active
 	].map(Number).join(""));
 	const features = [
 		{
@@ -2595,7 +2727,7 @@ async function stageMedia(options) {
 		},
 		{
 			name: "forced-colors",
-			value: forced ? "active" : "none"
+			value: active ? "active" : "none"
 		},
 		{
 			name: "prefers-reduced-motion",
@@ -2605,11 +2737,15 @@ async function stageMedia(options) {
 	const queries = [];
 	if (print === true) queries.push("print");
 	if (motion !== void 0) queries.push(`(prefers-reduced-motion: ${motion ? "no-preference" : "reduce"})`);
+	if (forced !== void 0) queries.push(`(forced-colors: ${forced ? "active" : "none"})`);
 	await sendProtocol("Emulation.setEmulatedMedia", {
 		media: print === void 0 ? media : print ? "print" : "screen",
 		features: features.map((feature) => feature.name === "prefers-reduced-motion" && motion !== void 0 ? {
 			name: feature.name,
 			value: motion ? "no-preference" : "reduce"
+		} : feature.name === "forced-colors" && forced !== void 0 ? {
+			name: feature.name,
+			value: forced ? "active" : "none"
 		} : feature)
 	});
 	await waitForFrame();
@@ -3531,6 +3667,6 @@ function createHarness(options) {
 	};
 }
 //#endregion
-export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, createChannel, createDragEvent, createHarness, createJournal, createPointerEvent, createPortfolio, createStorage, describeFocus, describeTree, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, holdAccessible, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, pressKeys, readBackdrop, readCascade, readCensus, readClasses, readContrast, readFocus, readFrame, readHit, readLayers, readName, readPage, readPerception, readPixels, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releaseMedia, releasePane, releasePointer, removeDatabase, render, resolveAccessible, resolveRendered, sendProtocol, stageMedia, stagePane, traverseAccessible, typeAccessible, typeInput, waitForAnimations, waitForFrame, waitForState };
+export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, commitInput, computeNamePattern, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, createChannel, createDragEvent, createHarness, createJournal, createPointerEvent, createPortfolio, createStorage, describeFocus, describeTree, driveHold, driveTraversal, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, holdAccessible, holdAccessibleWithin, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, pressKeys, readBackdrop, readCascade, readCensus, readClasses, readContrast, readFocus, readFrame, readHit, readLayers, readName, readPage, readPerception, readPixels, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releaseMedia, releasePane, releasePointer, removeDatabase, render, resolveAccessible, resolveAccessibleWithin, resolveRendered, sendProtocol, stageMedia, stagePane, traverseAccessible, traverseAccessibleWithin, typeAccessible, typeInput, waitForAnimations, waitForFrame, waitForState };
 
 //# sourceMappingURL=index.js.map