@itmetsam/samurai-framework 0.21.2 → 0.21.4

package/dist/locator/chain-resolver.js

@@ -2,10 +2,12 @@ import { BiDiError } from "../transport/bidi-error.js";
 import { UnsupportedOperationError } from "../transport/unsupported.js";
 import { ElementHandle } from "../script/element-handle.js";
 import { isDocumentSwap } from "./document-swap.js";
-import { LABEL_LOCATE } from "./label-locator.js";
+import { intersect, union } from "./combine-step.js";
+import { applyFilter } from "./filter-step.js";
+import { SORT_IN_DOCUMENT_ORDER } from "./page-search.js";
 import { InvalidSelectorError } from "./selector-errors.js";
+import { pageSearch, textSearch } from "./page-step.js";
 import { describeSelector, toBiDiLocator } from "./selector.js";
-import { TEXT_LOCATE } from "./text-locator.js";
 /** Locator types a connection's browser rejected, so they are not tried again on every poll */
 const unsupportedByConnector = new WeakMap();
 function unsupportedTypes(connector) {
@@ -14,6 +16,19 @@ function unsupportedTypes(connector) {
         unsupportedByConnector.set(connector, (types = new Set()));
     return types;
 }
+/**
+ * How many matches step `index` has to find: `max` for the last step; for a step an `nth` follows, only
+ * as many as that index needs, when one start node (or none) makes the search order the document's
+ */
+function stepLimit(chain, index, from, max) {
+    if (index === chain.length - 1)
+        return max;
+    const next = chain[index + 1];
+    const single = (from?.length ?? 0) <= 1;
+    return next.kind === "nth" && next.index >= 0 && single
+        ? next.index + 1
+        : undefined;
+}
 /** Finds the elements a chain of selector steps matches: every step searches inside the previous step's matches */
 export class ChainResolver {
     constructor(connector, contextId, call) {
@@ -21,17 +36,50 @@ export class ChainResolver {
         this.contextId = contextId;
         this.call = call;
     }
-    /** In document order; `max` limits the final result. Nothing is cached: the first match can change between polls */
-    async resolveChain(chain, max) {
+    /**
+     * In document order; `max` limits the final result. Nothing is cached: the first match can change between polls.
+     * `start` makes the chain relative to those elements: its first step searches inside them, like a later step.
+     */
+    async resolveChain(chain, max, start) {
         let nodes;
         for (const [index, selector] of chain.entries()) {
+            const from = nodes ?? start;
             if (selector.kind === "nth") {
-                const picked = nodes?.[selector.index];
+                const picked = nodes?.[selector.index < 0 ? nodes.length + selector.index : selector.index];
                 nodes = picked ? [picked] : [];
             }
+            else if (selector.kind === "and" || selector.kind === "or") {
+                try {
+                    nodes = await this.combine(selector, from, stepLimit(chain, index, from, max));
+                }
+                catch (err) {
+                    if (isDocumentSwap(err))
+                        return [];
+                    throw err;
+                }
+            }
+            else if (selector.kind === "filter") {
+                try {
+                    nodes = from
+                        ? await applyFilter(from, selector, {
+                            call: this.call,
+                            findInside: (inner, element) => this.resolveChain(inner, 1, [element]),
+                        })
+                        : [];
+                }
+                catch (err) {
+                    if (isDocumentSwap(err))
+                        return [];
+                    throw err;
+                }
+            }
             else {
                 try {
-                    nodes = await this.locateStep(selector, index > 0, nodes, index === chain.length - 1 ? max : undefined);
+                    nodes = await this.locateStep(selector, from !== undefined, from, stepLimit(chain, index, from, max));
+                    // Results per start node are not in document order, which an index into them needs
+                    if (chain[index + 1]?.kind === "nth" && (from?.length ?? 0) > 1) {
+                        nodes = await this.inDocumentOrder(nodes);
+                    }
                 }
                 catch (err) {
                     // The page is swapping documents: nothing matches right now, and the waits that poll try again
@@ -45,12 +93,36 @@ export class ChainResolver {
         }
         return nodes ?? [];
     }
+    /**
+     * `and` keeps what both chains match; `or` what either matches, in document order. Both chains search from
+     * scratch (or inside `from`, when the whole chain is relative). An `or` needs no more than `max` of each
+     */
+    async combine({ kind, left, right }, from, max) {
+        const limit = kind === "or" ? max : undefined;
+        const first = await this.resolveChain(left, limit, from);
+        const second = await this.resolveChain(right, limit, from);
+        if (kind === "and") {
+            const both = intersect(first, second);
+            return max === undefined ? both : both.slice(0, max);
+        }
+        if (first.length === 0 || second.length === 0) {
+            return (first.length === 0 ? second : first).slice(0, max);
+        }
+        const ordered = await this.inDocumentOrder(union(first, second));
+        return max === undefined ? ordered : ordered.slice(0, max);
+    }
+    async inDocumentOrder(nodes) {
+        if (nodes.length < 2)
+            return nodes;
+        return this.call(SORT_IN_DOCUMENT_ORDER, [nodes]);
+    }
     async locateStep(selector, scoped, startNodes, max) {
-        if (selector.kind === "label")
-            return this.locateInPage(LABEL_LOCATE, selector, startNodes, max);
+        const inPage = pageSearch(selector);
+        if (inPage)
+            return this.locateInPage(inPage, startNodes, max);
         if (selector.kind === "text" &&
             unsupportedTypes(this.connector).has("innerText")) {
-            return this.locateInPage(TEXT_LOCATE, selector, startNodes, max);
+            return this.locateInPage(textSearch(selector), startNodes, max);
         }
         try {
             return await this.locateNatively(selector, scoped, startNodes, max);
@@ -63,7 +135,7 @@ export class ChainResolver {
                 if (selector.kind === "text") {
                     // The browser has no innerText locator (Firefox): remember that and search in the page instead
                     unsupportedTypes(this.connector).add("innerText");
-                    return this.locateInPage(TEXT_LOCATE, selector, startNodes, max);
+                    return this.locateInPage(textSearch(selector), startNodes, max);
                 }
                 throw new UnsupportedOperationError(`${describeSelector(selector, scoped)}: this kind of locator is not supported by the browser (${err.message})`);
             }
@@ -89,13 +161,11 @@ export class ChainResolver {
         }
         return [...found.values()];
     }
-    /** Runs a page-side search `(starts, value, match, ignoreCase) => elements` */
-    async locateInPage(fn, selector, startNodes, max) {
+    /** Runs a page-side search `(starts, ...args) => elements` */
+    async locateInPage({ fn, args }, startNodes, max) {
         const found = await this.call(fn, [
             startNodes ?? [],
-            selector.value,
-            selector.match,
-            selector.ignoreCase,
+            ...args,
         ]);
         return max === undefined ? found : found.slice(0, max);
     }

package/dist/locator/check-actions.d.ts

@@ -0,0 +1,15 @@
+import type { ActionOptions } from "./actionability.js";
+import { type ElementAccess } from "./element-access.js";
+export interface CheckOptions extends ActionOptions {
+    /** Wait for the element to be actionable, but do not click (and so do not change anything) */
+    trial?: boolean;
+}
+/** Which of the three public methods asked, for the messages */
+type CheckMethod = "check" | "uncheck" | "setChecked";
+/**
+ * Brings a checkbox, radio or `role=checkbox|radio|switch` element to `checked`. Already there: nothing is clicked.
+ * Otherwise waits until the control (or one of its labels, for a hidden input) can be clicked, clicks it with real
+ * pointer input and verifies the state changed.
+ */
+export declare function setChecked(access: ElementAccess, method: CheckMethod, checked: boolean, options?: CheckOptions): Promise<void>;
+export {};

package/dist/locator/check-actions.js

@@ -0,0 +1,44 @@
+import { callOnExistingElement } from "./element-access.js";
+import { clickRect } from "./input-actions.js";
+import { ATTACHED_ONLY, CLICK_CHECKS } from "./page-scripts.js";
+/** Body run in the page as `(el) => { ... }`: what kind of control the element is, and whether it is checked */
+const CONTROL_INFO_BODY = `
+  const type = (el.getAttribute("type") || "").toLowerCase();
+  const role = (el.getAttribute("role") || "").trim().split(/\\s+/)[0].toLowerCase();
+  let kind = null;
+  if (el.tagName === "INPUT" && (type === "checkbox" || type === "radio")) kind = type;
+  else if (role === "checkbox" || role === "switch" || role === "menuitemcheckbox") kind = "checkbox";
+  else if (role === "radio" || role === "menuitemradio") kind = "radio";
+  const native = el.tagName === "INPUT" && (type === "checkbox" || type === "radio");
+  return { kind, checked: native ? el.checked : el.getAttribute("aria-checked") === "true" };`;
+function readControl(access, method) {
+    return callOnExistingElement(access, CONTROL_INFO_BODY, method);
+}
+/**
+ * Brings a checkbox, radio or `role=checkbox|radio|switch` element to `checked`. Already there: nothing is clicked.
+ * Otherwise waits until the control (or one of its labels, for a hidden input) can be clicked, clicks it with real
+ * pointer input and verifies the state changed.
+ */
+export async function setChecked(access, method, checked, options) {
+    const { trial, ...action } = options ?? {};
+    await access.waitForActionable(method, ATTACHED_ONLY, { scroll: false, hitTest: false }, action);
+    const before = await readControl(access, method);
+    if (before.kind === null) {
+        throw new Error(`${method}(): element is not a checkbox, radio, or role=checkbox/radio/switch`);
+    }
+    if (before.checked === checked)
+        return;
+    if (before.kind === "radio" && !checked) {
+        throw new Error(`${method}(): a radio button cannot be unchecked`);
+    }
+    const state = await access.waitForActionable(method, 
+    // The same checks as a click; the probe's `control` mode decides what counts as the target
+    CLICK_CHECKS, { scroll: true, hitTest: true, control: true }, action);
+    if (trial)
+        return;
+    // "attached" is always required, so the box is present
+    await clickRect(access.connector, access.contextId, state.box);
+    if ((await readControl(access, method)).checked !== checked) {
+        throw new Error(`${method}(): clicking the ${before.kind} did not change its state`);
+    }
+}

package/dist/locator/combine-step.d.ts

@@ -0,0 +1,5 @@
+import type { ElementHandle } from "../script/element-handle.js";
+/** The elements in both lists, in the order of the first */
+export declare function intersect(left: readonly ElementHandle[], right: readonly ElementHandle[]): ElementHandle[];
+/** Both lists joined, each element once (the same node has the same `sharedId` in every search) */
+export declare function union(left: readonly ElementHandle[], right: readonly ElementHandle[]): ElementHandle[];

package/dist/locator/combine-step.js

@@ -0,0 +1,15 @@
+/** The elements in both lists, in the order of the first */
+export function intersect(left, right) {
+    const wanted = new Set(right.map(({ sharedId }) => sharedId));
+    return left.filter(({ sharedId }) => wanted.has(sharedId));
+}
+/** Both lists joined, each element once (the same node has the same `sharedId` in every search) */
+export function union(left, right) {
+    const seen = new Set();
+    return [...left, ...right].filter(({ sharedId }) => {
+        if (seen.has(sharedId))
+            return false;
+        seen.add(sharedId);
+        return true;
+    });
+}

package/dist/locator/control-probe.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Page-side branch of the actionability probe for checkboxes, radios and switches (`ProbeOptions.control`).
+ * These are often hidden on purpose: a native input at `opacity: 0` (or 1px, or `display: none`) with a styled
+ * `<label>` on top. A user clicks the label, so the probe accepts the input itself or any of its labels as the
+ * click target: the first one that is shown and reached by a click at its centre. The reported `box` is that
+ * target's, so the click lands where a user's would. Other actions keep the stricter probe.
+ *
+ * Runs inside `PROBE_ELEMENT` with `el` and `options` in scope; a string for the same reason it is (no helpers).
+ */
+export declare const CONTROL_PROBE_BRANCH = "\n  if (options.control) {\n    const labels = Array.from(el.labels || []);\n    const shown = (node) => {\n      const r = node.getBoundingClientRect();\n      const s = getComputedStyle(node);\n      return r.width > 0 && r.height > 0 && s.display !== \"none\" && s.visibility !== \"hidden\";\n    };\n    const candidates = [el, ...labels].filter(shown);\n    const reaches = (node, top) => node === top || node.contains(top) ||\n      (node === el && labels.some((label) => label === top || label.contains(top)));\n    const bringIntoView = (node) => {\n      const r = node.getBoundingClientRect();\n      const inside = r.top >= 0 && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth;\n      if (options.scroll && !inside) node.scrollIntoView({ block: \"center\", inline: \"center\" });\n    };\n    let chosen = candidates[0] || el;\n    let hitTarget = null;\n    if (options.hitTest) {\n      for (const node of candidates) {\n        bringIntoView(node);\n        const r = node.getBoundingClientRect();\n        const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);\n        const hit = !top ? \"nothing\" : reaches(node, top) ? \"self\"\n          : top.tagName.toLowerCase() + (top.id ? \"#\" + top.id : \"\") +\n            Array.from(top.classList, (name) => \".\" + name).join(\"\");\n        if (node === candidates[0]) hitTarget = hit;\n        if (hit === \"self\") { chosen = node; hitTarget = \"self\"; break; }\n      }\n    } else if (candidates.length) {\n      bringIntoView(chosen);\n    }\n    const box = chosen.getBoundingClientRect();\n    return {\n      attached: true, visible: candidates.length > 0,\n      enabled: !el.matches(\":disabled\") && el.getAttribute(\"aria-disabled\") !== \"true\",\n      editable: false,\n      box: { x: box.left, y: box.top, width: box.width, height: box.height },\n      hitTarget,\n    };\n  }";

package/dist/locator/control-probe.js

@@ -0,0 +1,50 @@
+/**
+ * Page-side branch of the actionability probe for checkboxes, radios and switches (`ProbeOptions.control`).
+ * These are often hidden on purpose: a native input at `opacity: 0` (or 1px, or `display: none`) with a styled
+ * `<label>` on top. A user clicks the label, so the probe accepts the input itself or any of its labels as the
+ * click target: the first one that is shown and reached by a click at its centre. The reported `box` is that
+ * target's, so the click lands where a user's would. Other actions keep the stricter probe.
+ *
+ * Runs inside `PROBE_ELEMENT` with `el` and `options` in scope; a string for the same reason it is (no helpers).
+ */
+export const CONTROL_PROBE_BRANCH = `
+  if (options.control) {
+    const labels = Array.from(el.labels || []);
+    const shown = (node) => {
+      const r = node.getBoundingClientRect();
+      const s = getComputedStyle(node);
+      return r.width > 0 && r.height > 0 && s.display !== "none" && s.visibility !== "hidden";
+    };
+    const candidates = [el, ...labels].filter(shown);
+    const reaches = (node, top) => node === top || node.contains(top) ||
+      (node === el && labels.some((label) => label === top || label.contains(top)));
+    const bringIntoView = (node) => {
+      const r = node.getBoundingClientRect();
+      const inside = r.top >= 0 && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth;
+      if (options.scroll && !inside) node.scrollIntoView({ block: "center", inline: "center" });
+    };
+    let chosen = candidates[0] || el;
+    let hitTarget = null;
+    if (options.hitTest) {
+      for (const node of candidates) {
+        bringIntoView(node);
+        const r = node.getBoundingClientRect();
+        const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+        const hit = !top ? "nothing" : reaches(node, top) ? "self"
+          : top.tagName.toLowerCase() + (top.id ? "#" + top.id : "") +
+            Array.from(top.classList, (name) => "." + name).join("");
+        if (node === candidates[0]) hitTarget = hit;
+        if (hit === "self") { chosen = node; hitTarget = "self"; break; }
+      }
+    } else if (candidates.length) {
+      bringIntoView(chosen);
+    }
+    const box = chosen.getBoundingClientRect();
+    return {
+      attached: true, visible: candidates.length > 0,
+      enabled: !el.matches(":disabled") && el.getAttribute("aria-disabled") !== "true",
+      editable: false,
+      box: { x: box.left, y: box.top, width: box.width, height: box.height },
+      hitTarget,
+    };
+  }`;

package/dist/locator/element-access.d.ts

@@ -0,0 +1,26 @@
+import type { ElementHandle } from "../script/element-handle.js";
+import type { Arg } from "../script/serialize.js";
+import type { ElementContext } from "./file-actions.js";
+/** What reads and actions need of a locator: its page, its description, and finding its element */
+export interface ElementAccess extends ElementContext {
+    /**
+     * The element the locator matches first. With a `method` name and strict selectors on, several matches
+     * throw instead (`method` is the public method that asked, for the message)
+     */
+    resolveOne(method?: string): Promise<ElementHandle | null>;
+    /** Every element the locator matches now, in document order; never strict, never waits */
+    resolveAll(): Promise<ElementHandle[]>;
+}
+/** Calls `fn` in the page; a throwing function becomes a "Failed to locate element" error */
+export declare function callInPage<T>(access: Pick<ElementAccess, "connector" | "contextId" | "selector">, fn: string, args: Arg[], sandbox?: string): Promise<T>;
+/**
+ * Calls a function on the first matching element: `body` sees it as `el`, followed by `params`.
+ * Answers `whenMissing` when nothing matches, or the element disappeared meanwhile.
+ */
+export declare function callOnElement<T>(access: ElementAccess, whenMissing: T, body: string, params?: string[], args?: Arg[], method?: string): Promise<T>;
+/** Like `callOnElement`, for operations that cannot go on without the element */
+export declare function callOnExistingElement<T>(access: ElementAccess, body: string, method?: string): Promise<T>;
+/** The error for an operation that needs an element when none matches */
+export declare function noElementError(selector: string): Error;
+/** The element the locator matches now; throws when none does */
+export declare function requireElement(access: ElementAccess): Promise<ElementHandle>;

package/dist/locator/element-access.js

@@ -0,0 +1,53 @@
+import { BiDiError } from "../transport/bidi-error.js";
+import { callFunction, ScriptError } from "../script/call-function.js";
+/** Calls `fn` in the page; a throwing function becomes a "Failed to locate element" error */
+export async function callInPage(access, fn, args, sandbox) {
+    try {
+        return await callFunction(access.connector, access.contextId, fn, args, {
+            awaitPromise: false,
+            ...(sandbox !== undefined && { sandbox }),
+        });
+    }
+    catch (err) {
+        if (err instanceof ScriptError) {
+            throw new Error(`Failed to locate element ${access.selector}. Details: ${err.text}`);
+        }
+        throw err;
+    }
+}
+/**
+ * Calls a function on the first matching element: `body` sees it as `el`, followed by `params`.
+ * Answers `whenMissing` when nothing matches, or the element disappeared meanwhile.
+ */
+export async function callOnElement(access, whenMissing, body, params = [], args = [], method) {
+    const el = await access.resolveOne(method);
+    if (!el)
+        return whenMissing;
+    try {
+        return await access.call(`(el${params.map((param) => `, ${param}`).join("")}) => { ${body} }`, [el, ...args]);
+    }
+    catch (err) {
+        if (err instanceof BiDiError && err.code === "no such node")
+            return whenMissing;
+        throw err;
+    }
+}
+/** Like `callOnElement`, for operations that cannot go on without the element */
+export async function callOnExistingElement(access, body, method) {
+    const missing = Symbol("missing");
+    const result = await callOnElement(access, missing, body, [], [], method);
+    if (result === missing)
+        throw noElementError(access.selector);
+    return result;
+}
+/** The error for an operation that needs an element when none matches */
+export function noElementError(selector) {
+    return new Error(`Failed to locate element ${selector}. Details: no element matches`);
+}
+/** The element the locator matches now; throws when none does */
+export async function requireElement(access) {
+    const el = await access.resolveOne();
+    if (!el)
+        throw noElementError(access.selector);
+    return el;
+}

package/dist/locator/element-actions.d.ts

@@ -0,0 +1,17 @@
+import { type ElementScreenshotOptions } from "../browser/screenshot.js";
+import type { ActionOptions } from "./actionability.js";
+import { type ElementAccess } from "./element-access.js";
+/** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
+export declare function clickElement(access: ElementAccess, options?: ActionOptions): Promise<void>;
+/** Takes a screenshot of just the element, after scrolling it into view and waiting until it is attached and visible */
+export declare function screenshotElement(access: ElementAccess, options?: ElementScreenshotOptions & {
+    timeout?: number;
+}): Promise<Buffer>;
+/** Waits until the element is attached, then focuses it */
+export declare function focusElement(access: ElementAccess, options?: ActionOptions): Promise<void>;
+/** Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input */
+export declare function pressOnElement(access: ElementAccess, key: string, options?: ActionOptions): Promise<void>;
+/** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
+export declare function fillElement(access: ElementAccess, value: string, options?: ActionOptions & {
+    output?: string;
+}): Promise<void>;

package/dist/locator/element-actions.js

@@ -0,0 +1,51 @@
+import { bindOutput } from "../wait/output-sink.js";
+import { takeScreenshot, } from "../browser/screenshot.js";
+import { callOnElement, callOnExistingElement, requireElement, } from "./element-access.js";
+import { clickRect, DEFAULT_PAUSE_MS, NAMED_KEYS, pause, pressKey, typeText, } from "./input-actions.js";
+import { ATTACHED_ONLY, CLICK_CHECKS, FILL_CHECKS, PRESS_CHECKS, SCREENSHOT_CHECKS, } from "./page-scripts.js";
+/** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
+export async function clickElement(access, options) {
+    const state = await access.waitForActionable("click", CLICK_CHECKS, { scroll: true, hitTest: true }, options);
+    // "attached" is always required, so the box is present
+    await clickRect(access.connector, access.contextId, state.box);
+}
+/** Takes a screenshot of just the element, after scrolling it into view and waiting until it is attached and visible */
+export async function screenshotElement(access, options = {}) {
+    const { timeout, ...capture } = options;
+    await access.waitForActionable("screenshot", SCREENSHOT_CHECKS, { scroll: true, hitTest: false }, timeout === undefined ? undefined : { timeout });
+    const el = await requireElement(access);
+    return takeScreenshot(access.connector, access.contextId, capture, {
+        sharedId: el.sharedId,
+    });
+}
+/** Waits until the element is attached, then focuses it */
+export async function focusElement(access, options) {
+    await access.waitForActionable("focus", ATTACHED_ONLY, { scroll: false, hitTest: false }, options);
+    await callOnExistingElement(access, `el.focus();`);
+}
+/** Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input */
+export async function pressOnElement(access, key, options) {
+    const code = NAMED_KEYS[key] ?? (Array.from(key).length === 1 ? key : "");
+    if (code === "") {
+        throw new Error(`press(): unknown key "${key}". Use one of ${Object.keys(NAMED_KEYS).join(", ")} or a single character`);
+    }
+    await access.waitForActionable("press", PRESS_CHECKS, { scroll: true, hitTest: false }, options);
+    await callOnElement(access, undefined, `el.focus();`);
+    await pressKey(access.connector, access.contextId, code);
+}
+/** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
+export async function fillElement(access, value, options) {
+    // Taken when the call starts, so a fill that outlives its test saves into that test's closed sink
+    const save = options?.output === undefined
+        ? undefined
+        : bindOutput("fill()", options.output);
+    const state = await access.waitForActionable("fill", FILL_CHECKS, { scroll: true, hitTest: true }, options);
+    // Typing over the selected existing value replaces it; Backspace clears it for an empty value
+    const keys = value === "" ? NAMED_KEYS.Backspace : value;
+    await clickRect(access.connector, access.contextId, state.box);
+    // Lets the focus the click caused (and the page's focus handlers) settle before the text is selected and typed over
+    await pause(access.connector, access.contextId, DEFAULT_PAUSE_MS);
+    await callOnElement(access, undefined, `if (typeof el.select === "function") el.select();`);
+    await typeText(access.connector, access.contextId, keys);
+    save?.(value);
+}

package/dist/locator/element-reads.d.ts

@@ -1,4 +1,46 @@
-/** Body run in the page as `(el) => { ... }`: a checked checkbox or radio input, or `aria-checked="true"` */
-export declare const IS_CHECKED_BODY = "\n  const type = (el.getAttribute(\"type\") || \"\").toLowerCase();\n  const input = el.tagName === \"INPUT\" && (type === \"checkbox\" || type === \"radio\");\n  return (input && el.checked) || el.getAttribute(\"aria-checked\") === \"true\";";
-/** The CSS property name for `getPropertyValue`: camelCase becomes kebab-case (`backgroundColor` to `background-color`), `--custom` and kebab-case names are kept */
-export declare function cssPropertyName(name: string): string;
+import type { ElementRectangle } from "../types/bidi-modules/browsing-context.js";
+import { type ActionabilityContext } from "./actionability.js";
+import { type ElementAccess } from "./element-access.js";
+/** Trimmed text content, or null when the element is missing */
+export declare function readTextContent(access: ElementAccess): Promise<string | null>;
+/** Rendered text (what a person would copy: line breaks, no hidden text), untrimmed, or null when the element is missing */
+export declare function readInnerText(access: ElementAccess): Promise<string | null>;
+/** The markup inside the element, or null when the element is missing */
+export declare function readInnerHTML(access: ElementAccess): Promise<string | null>;
+/** `textContent` of every match, as the page has it (untrimmed); an empty array when none match */
+export declare function readAllTextContents(access: ElementAccess): Promise<string[]>;
+/** `innerText` of every match; an empty array when none match */
+export declare function readAllInnerTexts(access: ElementAccess): Promise<string[]>;
+/** The element's box in CSS pixels from the viewport's top left */
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The element's box, or null when it is missing or not rendered (`display: none`, detached): it has no boxes then */
+export declare function readBoundingBox(access: ElementAccess): Promise<BoundingBox | null>;
+/** The accessible name (see `ACCESSIBLE_NAME_JS`), "" when it has none, or null when the element is missing */
+export declare function readAccessibleName(access: ElementAccess): Promise<string | null>;
+/** The accessible description, "" when it has none, or null when the element is missing */
+export declare function readAccessibleDescription(access: ElementAccess): Promise<string | null>;
+/** Value of an input/textarea/select, or null when missing */
+export declare function readInputValue(access: ElementAccess): Promise<string | null>;
+/** Attribute value, or null when the element or attribute is missing */
+export declare function readAttribute(access: ElementAccess, name: string): Promise<string | null>;
+/** Whether a checkbox or radio input is checked or the element has `aria-checked="true"`; null when the element is missing */
+export declare function readIsChecked(access: ElementAccess): Promise<boolean | null>;
+/** The class attribute as written ("" when the element has none), or null when the element is missing */
+export declare function readClassAttribute(access: ElementAccess): Promise<string | null>;
+/** Computed value of a CSS property (camelCase names become kebab-case, `--custom` is kept), or null when the element is missing */
+export declare function readCssValue(access: ElementAccess, name: string): Promise<string | null>;
+/** The browser's getBoundingClientRect result for the element */
+export declare function readBoundingClientRect(access: ElementAccess): Promise<ElementRectangle>;
+/** Whether the element exists, has a non-empty box and is not hidden by CSS */
+export declare function readIsVisible(ctx: ActionabilityContext): Promise<boolean>;
+/** Whether the element exists and is not disabled; does not wait */
+export declare function readIsEnabled(ctx: ActionabilityContext): Promise<boolean>;
+/** Like `readIsEnabled`, but null when the element is missing, so callers can tell "disabled" from "not there"; does not wait */
+export declare function readEnabledState(ctx: ActionabilityContext): Promise<boolean | null>;
+/** Whether the element exists and accepts typing (enabled, not readonly, a text field); does not wait */
+export declare function readIsEditable(ctx: ActionabilityContext): Promise<boolean>;

package/dist/locator/element-reads.js

@@ -1,11 +1,123 @@
+import { probeState } from "./actionability.js";
+import { callOnElement, callOnExistingElement, } from "./element-access.js";
+import { describeType } from "./element-state.js";
+import { ACCESSIBLE_NAME_JS } from "./accessible-name.js";
+import { evaluateOnAll } from "./evaluate.js";
 /** Body run in the page as `(el) => { ... }`: a checked checkbox or radio input, or `aria-checked="true"` */
-export const IS_CHECKED_BODY = `
+const IS_CHECKED_BODY = `
   const type = (el.getAttribute("type") || "").toLowerCase();
   const input = el.tagName === "INPUT" && (type === "checkbox" || type === "radio");
   return (input && el.checked) || el.getAttribute("aria-checked") === "true";`;
 /** The CSS property name for `getPropertyValue`: camelCase becomes kebab-case (`backgroundColor` to `background-color`), `--custom` and kebab-case names are kept */
-export function cssPropertyName(name) {
+function cssPropertyName(name) {
     if (name.startsWith("--"))
         return name;
     return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
 }
+function booleanOrNull(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (value === null)
+        return null;
+    throw new Error(`Expected a boolean or null but received "${describeType(value)}"`);
+}
+function stringOrNull(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === null)
+        return null;
+    throw new Error(`Expected a string or null but received "${describeType(value)}"`);
+}
+/** Trimmed text content, or null when the element is missing */
+export async function readTextContent(access) {
+    return stringOrNull(await callOnElement(access, null, `return el.textContent.trim();`, [], [], "textContent"));
+}
+/** Rendered text (what a person would copy: line breaks, no hidden text), untrimmed, or null when the element is missing */
+export async function readInnerText(access) {
+    return stringOrNull(await callOnElement(access, null, `return el.innerText;`, [], [], "innerText"));
+}
+/** The markup inside the element, or null when the element is missing */
+export async function readInnerHTML(access) {
+    return stringOrNull(await callOnElement(access, null, `return el.innerHTML;`, [], [], "innerHTML"));
+}
+/** `textContent` of every match, as the page has it (untrimmed); an empty array when none match */
+export function readAllTextContents(access) {
+    return evaluateOnAll(access, `(els) => els.map((el) => el.textContent ?? "")`, undefined);
+}
+/** `innerText` of every match; an empty array when none match */
+export function readAllInnerTexts(access) {
+    return evaluateOnAll(access, `(els) => els.map((el) => el.innerText ?? "")`, undefined);
+}
+/** The element's box, or null when it is missing or not rendered (`display: none`, detached): it has no boxes then */
+export async function readBoundingBox(access) {
+    const box = await callOnElement(access, null, `
+      if (el.getClientRects().length === 0) return null;
+      const { x, y, width, height } = el.getBoundingClientRect();
+      return { x, y, width, height };
+    `, [], [], "boundingBox");
+    if (box === null)
+        return null;
+    if (typeof box !== "object") {
+        throw new Error(`Expected to receive an object but instead received "${describeType(box)}"`);
+    }
+    return box;
+}
+/** The accessible name (see `ACCESSIBLE_NAME_JS`), "" when it has none, or null when the element is missing */
+export async function readAccessibleName(access) {
+    return stringOrNull(await callOnElement(access, null, `${ACCESSIBLE_NAME_JS} return accessibleName(el);`, [], [], "accessibleName"));
+}
+/** The accessible description, "" when it has none, or null when the element is missing */
+export async function readAccessibleDescription(access) {
+    return stringOrNull(await callOnElement(access, null, `${ACCESSIBLE_NAME_JS} return accessibleDescription(el);`, [], [], "accessibleDescription"));
+}
+/** Value of an input/textarea/select, or null when missing */
+export async function readInputValue(access) {
+    return stringOrNull(await callOnElement(access, null, `return typeof el.value === "string" ? el.value : null;`, [], [], "inputValue"));
+}
+/** Attribute value, or null when the element or attribute is missing */
+export async function readAttribute(access, name) {
+    return stringOrNull(await callOnElement(access, null, `return el.getAttribute(name);`, ["name"], [name], "getAttribute"));
+}
+/** Whether a checkbox or radio input is checked or the element has `aria-checked="true"`; null when the element is missing */
+export async function readIsChecked(access) {
+    return booleanOrNull(await callOnElement(access, null, IS_CHECKED_BODY, [], [], "isChecked"));
+}
+/** The class attribute as written ("" when the element has none), or null when the element is missing */
+export async function readClassAttribute(access) {
+    return stringOrNull(await callOnElement(access, null, `return el.getAttribute("class") ?? "";`, [], [], "classAttribute"));
+}
+/** Computed value of a CSS property (camelCase names become kebab-case, `--custom` is kept), or null when the element is missing */
+export async function readCssValue(access, name) {
+    return stringOrNull(await callOnElement(access, null, `return getComputedStyle(el).getPropertyValue(name);`, ["name"], [cssPropertyName(name)], "cssValue"));
+}
+/** The browser's getBoundingClientRect result for the element */
+export async function readBoundingClientRect(access) {
+    const rect = await callOnExistingElement(access, `
+      const { x, y, width, height, top, right, bottom, left } = el.getBoundingClientRect();
+      return { x, y, width, height, top, right, bottom, left };
+    `, "getBoundingClientRect");
+    if (typeof rect !== "object" || rect === null) {
+        throw new Error(`Expected to receive an object but instead received "${describeType(rect)}"`);
+    }
+    return rect;
+}
+/** Whether the element exists, has a non-empty box and is not hidden by CSS */
+export async function readIsVisible(ctx) {
+    const state = await probeState(ctx, { scroll: false, hitTest: false }, "isVisible");
+    return state.attached && state.visible;
+}
+/** Whether the element exists and is not disabled; does not wait */
+export async function readIsEnabled(ctx) {
+    const state = await probeState(ctx, { scroll: false, hitTest: false }, "isEnabled");
+    return state.attached && state.enabled;
+}
+/** Like `readIsEnabled`, but null when the element is missing, so callers can tell "disabled" from "not there"; does not wait */
+export async function readEnabledState(ctx) {
+    const state = await probeState(ctx, { scroll: false, hitTest: false }, "enabledState");
+    return state.attached ? state.enabled : null;
+}
+/** Whether the element exists and accepts typing (enabled, not readonly, a text field); does not wait */
+export async function readIsEditable(ctx) {
+    const state = await probeState(ctx, { scroll: false, hitTest: false }, "isEditable");
+    return state.attached && state.editable;
+}