@teaflask/assistant 0.7.0 → 0.8.0

package/README.md

@@ -63,7 +63,7 @@ import { TeaflaskAssistant } from "@teaflask/assistant";
 
 ## What your agent can do
 
-- **Take actions.** It calls your API on the user's behalf, with the user's own session. You set every action to Allow, Ask or Deny.
+- **Take actions.** It calls your API on the user's behalf, with the user's own session. You set every action to Allow, Ask or Deny. On a [GraphQL](https://docs.teaflask.com/adapters#graphql) API, it runs them through your app's own client.
 - **Follow your workflows.** Write a procedure once, like how refunds work or when to escalate, and the agent follows it.
 - **Guide users around your app.** It takes people to the right page and highlights what to click.
 - **Fill in forms.** It fills the fields; the user reviews and submits.

package/dist/affordances/aria-dropdowns.js

@@ -0,0 +1,315 @@
+import { CLOSE_SETTLE_MS, clicked, OPEN_SETTLE_MS, PICK_SETTLE_MS, pressKey, pressLikeAPointer, settledReading, theClickWouldSubmitOrLeaveThePage, theControlIsInert, } from "./page-gestures.js";
+import { CONTROL_REDRAWN_REASON, CURATED_OPTIONS_REASON, DROPDOWN_NEVER_OPENED_REASON, DROPDOWN_PICK_DID_NOT_LAND_REASON, INERT_FIELD_REASON, MULTI_CHOICE_REASON, NO_OPTIONS_SHOWN_REASON, noMatchingOptionReasonListing, SUBMITTING_CONTROL_REASON, unavailableOptionReason, } from "./prefill-reasons.js";
+import { accessibleNameOf, } from "../reader/accessible-name.js";
+import { ariaBooleanOf, roleOf, theControlIsDisabled, } from "../reader/roles.js";
+import { alreadyShowsTheValue, comboboxOwnerOf, confirmsLabel, displayNamesTheMatch, ownDisplayIsReliable, ownerShowsThePick, shownTextOf, } from "./dropdown-display.js";
+import { _normalizedNodeName } from "../reader/snapshot-node.js";
+import { lastReadIgnoreSelectors } from "../reader/snapshot.js";
+import { theElementSitsInACuratedSubtree } from "../reader/snapshot-root.js";
+import { visibilityOracleOf } from "../reader/visibility.js";
+export async function customDropdownRefusalOf(element, value, probe, listingBudget, whenNoListOpens) {
+    const entryRefusal = _dropdownEntryRefusalOf(element);
+    if (entryRefusal !== null) {
+        return entryRefusal;
+    }
+    const want = value.trim();
+    if (ownDisplayIsReliable(element) &&
+        alreadyShowsTheValue(element, want, probe, null)) {
+        return null;
+    }
+    if (!(element instanceof HTMLInputElement) &&
+        theClickWouldSubmitOrLeaveThePage(element)) {
+        return SUBMITTING_CONTROL_REASON;
+    }
+    const found = await _openedListboxFor(element, probe);
+    const listbox = found.listbox;
+    const closedIfOurs = async () => {
+        if (found.provenance === "ours") {
+            await _closedPopup(element, listbox, probe);
+        }
+    };
+    if (listbox === null) {
+        if (!element.isConnected) {
+            return CONTROL_REDRAWN_REASON;
+        }
+        if (found.gesturesWereDispatched) {
+            await _closedPopup(element, listbox, probe);
+        }
+        return whenNoListOpens !== undefined
+            ? whenNoListOpens(DROPDOWN_NEVER_OPENED_REASON)
+            : DROPDOWN_NEVER_OPENED_REASON;
+    }
+    if (!element.isConnected) {
+        return CONTROL_REDRAWN_REASON;
+    }
+    if (!ownDisplayIsReliable(element) &&
+        alreadyShowsTheValue(element, want, probe, listbox)) {
+        await closedIfOurs();
+        return null;
+    }
+    if (theElementSitsInACuratedSubtree(listbox, lastReadIgnoreSelectors())) {
+        await closedIfOurs();
+        return CURATED_OPTIONS_REASON;
+    }
+    if (ariaBooleanOf(listbox.getAttribute("aria-multiselectable")) === true) {
+        await closedIfOurs();
+        return MULTI_CHOICE_REASON;
+    }
+    const options = _visibleOptionsOf(listbox, probe);
+    if (options.length === 0) {
+        await closedIfOurs();
+        return whenNoListOpens !== undefined
+            ? whenNoListOpens(NO_OPTIONS_SHOWN_REASON)
+            : NO_OPTIONS_SHOWN_REASON;
+    }
+    const cache = new Map();
+    const nameOf = (option) => accessibleNameOf(option, probe, cache).trim();
+    const match = _optionMatching(options, want, value, nameOf);
+    if (match === null) {
+        await closedIfOurs();
+        return _noMatchRefusalOf(element, options, nameOf, listingBudget);
+    }
+    const label = nameOf(match) !== "" ? nameOf(match) : want;
+    if (match.getAttribute("aria-selected") === "true" &&
+        displayNamesTheMatch(shownTextOf(element, probe, listbox), label, options, nameOf)) {
+        await closedIfOurs();
+        return null;
+    }
+    if (theControlIsDisabled(match, "option")) {
+        await closedIfOurs();
+        return unavailableOptionReason(label);
+    }
+    if (theClickWouldSubmitOrLeaveThePage(match)) {
+        await closedIfOurs();
+        return SUBMITTING_CONTROL_REASON;
+    }
+    return _confirmedPickRefusalOf(element, listbox, match, label, probe);
+}
+async function _confirmedPickRefusalOf(element, listbox, match, label, probe) {
+    const beforeText = shownTextOf(element, probe, listbox);
+    clicked(match);
+    const after = await settledReading(() => shownTextOf(element, probe, listbox), (text) => !element.isConnected ||
+        (text !== beforeText && confirmsLabel(text, label)), PICK_SETTLE_MS);
+    await _closedPopup(element, listbox, probe);
+    if (!element.isConnected) {
+        return CONTROL_REDRAWN_REASON;
+    }
+    const landed = after !== beforeText && confirmsLabel(after, label);
+    return landed ? null : DROPDOWN_PICK_DID_NOT_LAND_REASON;
+}
+export async function listboxPickRefusalOf(element, value, probe, listingBudget) {
+    if (theControlIsInert(element)) {
+        return INERT_FIELD_REASON;
+    }
+    if (ariaBooleanOf(element.getAttribute("aria-multiselectable")) === true) {
+        return MULTI_CHOICE_REASON;
+    }
+    const options = _visibleOptionsOf(element, probe);
+    if (options.length === 0) {
+        return NO_OPTIONS_SHOWN_REASON;
+    }
+    const cache = new Map();
+    const nameOf = (option) => accessibleNameOf(option, probe, cache).trim();
+    const want = value.trim();
+    const match = _optionMatching(options, want, value, nameOf);
+    if (match === null) {
+        return _noMatchRefusalOf(element, options, nameOf, listingBudget);
+    }
+    if (match.getAttribute("aria-selected") === "true") {
+        return null;
+    }
+    const label = nameOf(match) !== "" ? nameOf(match) : want;
+    if (theControlIsDisabled(match, "option")) {
+        return unavailableOptionReason(label);
+    }
+    if (theClickWouldSubmitOrLeaveThePage(match)) {
+        return SUBMITTING_CONTROL_REASON;
+    }
+    const owner = comboboxOwnerOf(element);
+    const ownerBefore = owner === null ? "" : shownTextOf(owner, probe, element);
+    clicked(match);
+    const selected = await settledReading(() => match.getAttribute("aria-selected"), (state) => state === "true" || !element.isConnected || !match.isConnected, PICK_SETTLE_MS);
+    if (element.isConnected && match.isConnected) {
+        return selected === "true" ? null : DROPDOWN_PICK_DID_NOT_LAND_REASON;
+    }
+    if (owner !== null) {
+        return (await ownerShowsThePick(owner, ownerBefore, label, probe))
+            ? null
+            : DROPDOWN_PICK_DID_NOT_LAND_REASON;
+    }
+    return CONTROL_REDRAWN_REASON;
+}
+async function _openedListboxFor(element, probe) {
+    if (element.getAttribute("aria-expanded") === "true") {
+        const alreadyOpen = _openedListboxOf(element, probe, new Set(), (candidate) => _popupBelongsToTrigger(candidate, element, probe));
+        return {
+            listbox: alreadyOpen,
+            provenance: alreadyOpen !== null ? "users" : "unattributed",
+            gesturesWereDispatched: false,
+        };
+    }
+    const alreadyShowing = visibilityOracleOf(probe);
+    const before = new Set(Array.from(document.querySelectorAll('[role="listbox"]')).filter((candidate) => alreadyShowing.isVisible(candidate)));
+    if (element instanceof HTMLElement) {
+        element.focus();
+    }
+    pressKey(element, "ArrowDown");
+    const viaKeyboard = await settledReading(() => _openedListboxOf(element, probe, before, () => true), (listbox) => listbox !== null || !element.isConnected, OPEN_SETTLE_MS);
+    if (viaKeyboard !== null) {
+        return {
+            listbox: viaKeyboard,
+            provenance: "ours",
+            gesturesWereDispatched: true,
+        };
+    }
+    if (!element.isConnected ||
+        theClickWouldSubmitOrLeaveThePage(element) ||
+        element.getAttribute("aria-expanded") === "true") {
+        return {
+            listbox: null,
+            provenance: "unattributed",
+            gesturesWereDispatched: true,
+        };
+    }
+    pressLikeAPointer(element);
+    const viaPointer = await settledReading(() => _openedListboxOf(element, probe, before, () => true), (listbox) => listbox !== null || !element.isConnected, OPEN_SETTLE_MS);
+    return {
+        listbox: viaPointer,
+        provenance: viaPointer !== null ? "ours" : "unattributed",
+        gesturesWereDispatched: true,
+    };
+}
+const KINSHIP_CLIMB_MAX = 5;
+function _popupBelongsToTrigger(candidate, trigger, probe) {
+    if (candidate.contains(trigger) || trigger.contains(candidate)) {
+        return true;
+    }
+    const oracle = visibilityOracleOf(probe);
+    const body = trigger.ownerDocument.body;
+    let current = trigger.parentElement;
+    for (let depth = 0; depth < KINSHIP_CLIMB_MAX && current !== null && current !== body; depth++) {
+        const visibleInside = Array.from(current.querySelectorAll('[role="listbox"]')).filter((listbox) => oracle.isVisible(listbox));
+        if (visibleInside.length > 0) {
+            return visibleInside.length === 1 && visibleInside[0] === candidate;
+        }
+        current = current.parentElement;
+    }
+    return false;
+}
+function _openedListboxOf(trigger, probe, before, unlinkedIsOurs) {
+    const oracle = visibilityOracleOf(probe);
+    const byId = _idReferencedListboxOf(trigger, "aria-controls") ??
+        _idReferencedListboxOf(trigger, "aria-owns");
+    if (byId !== null && oracle.isVisible(byId)) {
+        return byId;
+    }
+    const active = _resolvedIdNear(trigger, trigger.getAttribute("aria-activedescendant"));
+    const viaActive = active?.closest('[role="listbox"]') ?? null;
+    if (viaActive !== null && oracle.isVisible(viaActive)) {
+        return viaActive;
+    }
+    for (const candidate of Array.from(document.querySelectorAll('[role="listbox"]'))) {
+        if (!before.has(candidate) &&
+            oracle.isVisible(candidate) &&
+            unlinkedIsOurs(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function _idReferencedListboxOf(trigger, attribute) {
+    const ids = (trigger.getAttribute(attribute) ?? "")
+        .split(/\s+/)
+        .filter((id) => id !== "");
+    for (const id of ids) {
+        const hit = _resolvedIdNear(trigger, id);
+        if (hit === null) {
+            continue;
+        }
+        if (roleOf(hit) === "listbox") {
+            return hit;
+        }
+        const inner = hit.querySelector('[role="listbox"]');
+        if (inner !== null) {
+            return inner;
+        }
+    }
+    return null;
+}
+function _resolvedIdNear(trigger, id) {
+    if (id === null || id === "") {
+        return null;
+    }
+    const root = trigger.getRootNode();
+    if (root instanceof Document || root instanceof ShadowRoot) {
+        return root.getElementById(id);
+    }
+    return document.getElementById(id);
+}
+function _optionMatching(options, want, rawValue, nameOf) {
+    if (want === "") {
+        return null;
+    }
+    return (options.find((option) => nameOf(option) === want) ??
+        options.find((option) => nameOf(option).toLowerCase() === want.toLowerCase()) ??
+        options.find((option) => {
+            const shownToTheModel = _normalizedNodeName(nameOf(option));
+            const comparable = shownToTheModel.trimEnd();
+            return (shownToTheModel !== nameOf(option) &&
+                (comparable === want || comparable.toLowerCase() === want.toLowerCase()));
+        }) ??
+        options.find((option) => option.getAttribute("data-value") === rawValue) ??
+        null);
+}
+function _visibleOptionsOf(listbox, probe) {
+    const oracle = visibilityOracleOf(probe);
+    const ignoreSelectors = lastReadIgnoreSelectors();
+    return Array.from(listbox.querySelectorAll('[role="option"]')).filter((option) => oracle.isVisible(option) &&
+        !theElementSitsInACuratedSubtree(option, ignoreSelectors));
+}
+async function _closedPopup(control, listbox, probe) {
+    if (_popupLooksClosed(control, listbox, probe)) {
+        return;
+    }
+    const active = control.ownerDocument.activeElement;
+    const focused = active !== null &&
+        (control.contains(active) || (listbox?.contains(active) ?? false))
+        ? active
+        : null;
+    if (focused instanceof HTMLInputElement) {
+        focused.blur();
+    }
+    else if (control instanceof HTMLInputElement) {
+        control.blur();
+    }
+    else {
+        pressKey(focused ?? control, "Escape");
+    }
+    await settledReading(() => _popupLooksClosed(control, listbox, probe), (closed) => closed, CLOSE_SETTLE_MS);
+}
+function _popupLooksClosed(control, listbox, probe) {
+    if (!control.isConnected) {
+        return true;
+    }
+    if (control.hasAttribute("aria-expanded")) {
+        return control.getAttribute("aria-expanded") !== "true";
+    }
+    return !_popupShowing(listbox, probe);
+}
+function _popupShowing(listbox, probe) {
+    return (listbox !== null &&
+        listbox.isConnected &&
+        visibilityOracleOf(probe).isVisible(listbox));
+}
+function _dropdownEntryRefusalOf(element) {
+    if (theControlIsInert(element) || theControlIsDisabled(element, "combobox")) {
+        return INERT_FIELD_REASON;
+    }
+    return null;
+}
+function _noMatchRefusalOf(element, options, nameOf, listingBudget) {
+    const labels = options
+        .filter((option) => !theControlIsDisabled(option, "option"))
+        .map(nameOf);
+    return noMatchingOptionReasonListing(labels, listingBudget, element instanceof HTMLInputElement && !element.readOnly);
+}

package/dist/affordances/aria-toggles.js

@@ -0,0 +1,39 @@
+import { clicked, settledReading, theClickWouldSubmitOrLeaveThePage, theControlIsInert, TOGGLE_SETTLE_MS, } from "./page-gestures.js";
+import { CHECKBOX_VALUE_REASON, CHECKED_STATE_UNKNOWN_REASON, CONTROL_REDRAWN_REASON, INERT_FIELD_REASON, RADIO_VALUE_REASON, SUBMITTING_CONTROL_REASON, VALUE_DID_NOT_LAND_REASON, } from "./prefill-reasons.js";
+import { roleOf } from "../reader/roles.js";
+export async function ariaToggleRefusalOf(element, value) {
+    if (roleOf(element) === "radio" && value !== "true") {
+        return RADIO_VALUE_REASON;
+    }
+    if (value !== "true" && value !== "false") {
+        return CHECKBOX_VALUE_REASON;
+    }
+    if (theControlIsInert(element)) {
+        return INERT_FIELD_REASON;
+    }
+    const state = _rawCheckedOf(element);
+    if (state === null) {
+        return CHECKED_STATE_UNKNOWN_REASON;
+    }
+    if (state === value) {
+        return null;
+    }
+    if (theClickWouldSubmitOrLeaveThePage(element)) {
+        return SUBMITTING_CONTROL_REASON;
+    }
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const before = _rawCheckedOf(element);
+        clicked(element);
+        const after = await settledReading(() => _rawCheckedOf(element), (read) => read === value || !element.isConnected, TOGGLE_SETTLE_MS);
+        if (after === value || after === before) {
+            break;
+        }
+    }
+    if (!element.isConnected) {
+        return CONTROL_REDRAWN_REASON;
+    }
+    return _rawCheckedOf(element) === value ? null : VALUE_DID_NOT_LAND_REASON;
+}
+function _rawCheckedOf(element) {
+    return element.getAttribute("aria-checked")?.toLowerCase() ?? null;
+}

package/dist/affordances/dropdown-display.js

@@ -0,0 +1,129 @@
+import { PICK_SETTLE_MS, settledReading } from "./page-gestures.js";
+import { roleOf } from "../reader/roles.js";
+import { lastReadIgnoreSelectors } from "../reader/snapshot.js";
+import { _theSubtreeIsCurated } from "../reader/snapshot-root.js";
+import { visibilityOracleOf, } from "../reader/visibility.js";
+export function shownTextOf(control, probe, excluding) {
+    if (control instanceof HTMLInputElement) {
+        const own = _normalized(control.value);
+        if (own !== "") {
+            return own;
+        }
+        return _nearestAncestorTextOf(control, probe, excluding);
+    }
+    const text = _visibleTextOf(control, probe, excluding);
+    if (text !== "") {
+        return text;
+    }
+    const inner = Array.from(control.querySelectorAll("input")).find((candidate) => !excluding?.contains(candidate));
+    return inner === undefined ? "" : _normalized(inner.value);
+}
+export function ownDisplayIsReliable(element) {
+    return element instanceof HTMLInputElement
+        ? element.value.trim() !== ""
+        : element.querySelector('[role="listbox"]') === null;
+}
+export function alreadyShowsTheValue(element, want, probe, excluding) {
+    return (want !== "" &&
+        _normalized(shownTextOf(element, probe, excluding)).toLowerCase() ===
+            _normalized(want).toLowerCase());
+}
+export function confirmsLabel(text, label) {
+    const shown = _normalized(text).toLowerCase();
+    const wanted = _normalized(label).toLowerCase();
+    if (shown === wanted) {
+        return true;
+    }
+    return _containsAsAWholeToken(shown, wanted);
+}
+export function displayNamesTheMatch(shown, matchLabel, options, nameOf) {
+    if (!confirmsLabel(shown, matchLabel)) {
+        return false;
+    }
+    return options.every((option) => {
+        const other = nameOf(option);
+        return other.length <= matchLabel.length || !confirmsLabel(shown, other);
+    });
+}
+export function comboboxOwnerOf(listbox) {
+    const id = listbox.id;
+    if (id === "") {
+        return null;
+    }
+    const root = listbox.getRootNode();
+    const scope = root instanceof Document || root instanceof ShadowRoot ? root : document;
+    for (const candidate of Array.from(scope.querySelectorAll("[aria-controls], [aria-owns]"))) {
+        const named = [
+            candidate.getAttribute("aria-controls") ?? "",
+            candidate.getAttribute("aria-owns") ?? "",
+        ]
+            .join(" ")
+            .split(/\s+/)
+            .filter((token) => token !== "");
+        if (named.includes(id) && roleOf(candidate) === "combobox") {
+            return candidate;
+        }
+    }
+    return null;
+}
+export async function ownerShowsThePick(owner, ownerBefore, label, probe) {
+    const after = await settledReading(() => shownTextOf(owner, probe, null), (text) => text !== ownerBefore && confirmsLabel(text, label), PICK_SETTLE_MS);
+    return after !== ownerBefore && confirmsLabel(after, label);
+}
+function _containsAsAWholeToken(shown, wanted) {
+    if (wanted === "") {
+        return false;
+    }
+    for (let from = 0;; from += 1) {
+        const at = shown.indexOf(wanted, from);
+        if (at === -1) {
+            return false;
+        }
+        const before = at === 0 ? "" : shown[at - 1];
+        const after = at + wanted.length >= shown.length ? "" : shown[at + wanted.length];
+        if (!_isWordCharacter(before) && !_isWordCharacter(after)) {
+            return true;
+        }
+        from = at;
+    }
+}
+function _isWordCharacter(character) {
+    return character !== "" && /[\p{L}\p{N}_]/u.test(character);
+}
+function _nearestAncestorTextOf(control, probe, excluding) {
+    const body = control.ownerDocument.body;
+    let current = control.parentElement;
+    for (let depth = 0; depth < 5 && current !== null && current !== body; depth++) {
+        const text = _visibleTextOf(current, probe, excluding);
+        if (text !== "") {
+            return text;
+        }
+        current = current.parentElement;
+    }
+    return "";
+}
+function _visibleTextOf(root, probe, excluding) {
+    return _normalized(_textWithin(root, visibilityOracleOf(probe), excluding));
+}
+function _textWithin(node, oracle, excluding) {
+    if (node.nodeType === Node.TEXT_NODE) {
+        return node.textContent ?? "";
+    }
+    if (!(node instanceof Element) || node === excluding) {
+        return "";
+    }
+    if (node.getAttribute("aria-hidden") === "true" || !oracle.isVisible(node)) {
+        return "";
+    }
+    if (_theSubtreeIsCurated(node, lastReadIgnoreSelectors())) {
+        return "";
+    }
+    let text = "";
+    for (const child of Array.from(node.childNodes)) {
+        text += _textWithin(child, oracle, excluding);
+    }
+    return text;
+}
+function _normalized(text) {
+    return text.replace(/\s+/g, " ").trim();
+}

package/dist/affordances/page-gestures.js

@@ -0,0 +1,91 @@
+import { ariaBooleanOf, roleOf, theControlIsDisabled, } from "../reader/roles.js";
+export const TOGGLE_SETTLE_MS = 500;
+export const OPEN_SETTLE_MS = 750;
+export const PICK_SETTLE_MS = 750;
+export const CLOSE_SETTLE_MS = 500;
+const SETTLE_POLL_MS = 25;
+export function typeLikeAUser(control, value) {
+    const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(control), "value");
+    if (descriptor?.set !== undefined) {
+        descriptor.set.call(control, value);
+    }
+    else {
+        control.value = value;
+    }
+    control.dispatchEvent(new Event("input", { bubbles: true }));
+    control.dispatchEvent(new Event("change", { bubbles: true }));
+}
+export function pressKey(target, key) {
+    const init = {
+        key,
+        code: key,
+        bubbles: true,
+        cancelable: true,
+    };
+    target.dispatchEvent(new KeyboardEvent("keydown", init));
+    target.dispatchEvent(new KeyboardEvent("keyup", init));
+}
+export function pressLikeAPointer(target) {
+    const armed = target.dispatchEvent(_pointerEventOf("pointerdown"));
+    if (armed) {
+        target.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true }));
+    }
+    target.dispatchEvent(_pointerEventOf("pointerup"));
+    if (armed) {
+        target.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true }));
+    }
+    clicked(target);
+}
+export function clicked(target) {
+    if (target instanceof HTMLElement) {
+        target.click();
+    }
+    else {
+        target.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+    }
+}
+function _pointerEventOf(type) {
+    const init = { bubbles: true, cancelable: true, pointerId: 1 };
+    return typeof PointerEvent === "function"
+        ? new PointerEvent(type, init)
+        : new MouseEvent(type, init);
+}
+export async function settledReading(read, isSettled, budgetMs) {
+    const deadline = Date.now() + budgetMs;
+    await _afterMs(0);
+    let value = read();
+    while (!isSettled(value) && Date.now() < deadline) {
+        await _afterMs(SETTLE_POLL_MS);
+        value = read();
+    }
+    return value;
+}
+export function settledValueOf(read) {
+    return settledReading(read, () => true, 0);
+}
+function _afterMs(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export function theClickWouldSubmitOrLeaveThePage(element) {
+    if (element.closest("a[href], area[href]") !== null) {
+        return true;
+    }
+    const button = element.closest("button");
+    return button !== null && button.form !== null && button.type !== "button";
+}
+export function theControlIsInert(element) {
+    if (theControlIsDisabled(element, roleOf(element))) {
+        return true;
+    }
+    if (ariaBooleanOf(element.getAttribute("aria-readonly")) === true) {
+        return true;
+    }
+    const group = element.closest('[role="radiogroup"]');
+    if (group !== null &&
+        ariaBooleanOf(group.getAttribute("aria-readonly")) === true) {
+        return true;
+    }
+    return element.closest("[inert]") !== null;
+}

package/dist/affordances/prefill-reasons.js

@@ -0,0 +1,75 @@
+export const SECRET_FIELD_REASON = "This field holds a secret (a password or payment detail) — the user " +
+    "must type it themselves.";
+export const FILE_FIELD_REASON = "File pickers cannot be filled by the assistant — the user must choose " +
+    "the file themselves.";
+export const INERT_FIELD_REASON = "This field is disabled or read-only and cannot take a value right now.";
+export const NOT_FILLABLE_REASON = "This element is not a fillable form field — take a fresh read and " +
+    "pick a textbox, dropdown, checkbox, radio button, switch, or editor ref.";
+export const CHECKBOX_VALUE_REASON = 'A checkbox or switch takes "true" or "false", nothing else — call ' +
+    "again with one of those.";
+export const RADIO_VALUE_REASON = 'A radio button can only be selected — pass "true" on the option to ' +
+    "select instead.";
+const NO_MATCHING_OPTION_REASON = "No option in this dropdown matches that value — read the page to see " +
+    "the options it offers.";
+export const VALUE_DID_NOT_LAND_REASON = "The page's own scripts rejected this value — it did not stay in the " +
+    "field.";
+export const EDITOR_UNAVAILABLE_REASON = "This editor cannot be filled on this page — tell the user what to " +
+    "type instead.";
+export const MIRROR_INPUT_REASON = "This checkbox is the page's hidden mirror of a styled control — take " +
+    "a fresh read and fill the visible checkbox or switch beside it instead.";
+export const CHECKED_STATE_UNKNOWN_REASON = "This control does not report its checked state — tell the user to " +
+    "toggle it themselves.";
+export const CONTROL_REDRAWN_REASON = "The page redrew this control while it was being set — take a fresh " +
+    "read and use the new ref.";
+export const SUBMITTING_CONTROL_REASON = "Clicking this control would submit the form or leave the page — tell " +
+    "the user to set it themselves.";
+export const DROPDOWN_NEVER_OPENED_REASON = "This dropdown would not open its options — tell the user to pick the " +
+    "option themselves.";
+export const CURATED_OPTIONS_REASON = "This dropdown's options sit in a part of the page that has opted out " +
+    "of page reads — tell the user to pick it themselves.";
+export const MULTI_CHOICE_REASON = "This control takes several choices at once, which prefill cannot set " +
+    "safely — tell the user which options to pick themselves.";
+export const NO_OPTIONS_SHOWN_REASON = "This dropdown opened with nothing to pick — tell the user to fill it " +
+    "themselves.";
+export const DROPDOWN_PICK_DID_NOT_LAND_REASON = "Picking that option did not change the dropdown's value — tell the " +
+    "user to pick it themselves.";
+const OPTION_LIST_MAX = 15;
+const OPTION_LABEL_MAX = 60;
+const LISTING_REPORT_BUDGET_CHARS = 8_000;
+export function reportListingBudget() {
+    return { remainingChars: LISTING_REPORT_BUDGET_CHARS };
+}
+export function noMatchingOptionReasonListing(labels, budget, freeTextHint = false) {
+    const named = labels.filter((label) => label !== "");
+    const shown = named.slice(0, OPTION_LIST_MAX);
+    if (shown.length === 0) {
+        return NO_MATCHING_OPTION_REASON;
+    }
+    const more = named.length - shown.length;
+    const overflow = more > 0 ? `, and ${String(more)} more` : "";
+    const next = shown.some((label) => label.length > OPTION_LABEL_MAX)
+        ? "— a label ending in … is cut short here: read the page for its " +
+            "full text, then call prefill_form again with one exactly."
+        : "— call prefill_form again with one of these exactly.";
+    const hint = freeTextHint
+        ? " If this field accepts typed text instead, tell the user the " +
+            "exact value to enter."
+        : "";
+    const listed = "No option in this dropdown matches that value. It offers: " +
+        `${shown.map(_quotedLabel).join(", ")}${overflow} ${next}${hint}`;
+    if (listed.length > budget.remainingChars) {
+        return NO_MATCHING_OPTION_REASON;
+    }
+    budget.remainingChars -= listed.length;
+    return listed;
+}
+export function unavailableOptionReason(label) {
+    return (`The option ${_quotedLabel(label)} is disabled right now — call ` +
+        "again with a different option or tell the user to pick it themselves.");
+}
+function _quotedLabel(label) {
+    const cut = label.length > OPTION_LABEL_MAX
+        ? `${label.slice(0, OPTION_LABEL_MAX)}…`
+        : label;
+    return `"${cut}"`;
+}