@reticlehq/browser 3.8.1 → 3.9.0

package/dist/actions/actions-dom.d.ts

@@ -1,4 +1,6 @@
 import type { ActionTarget } from '../dom/realm.js';
+import { ClickButton } from '@reticlehq/core';
+import { type ModifierFlags } from './actions-press.js';
 interface ClickGeometry {
     occluded: boolean;
     occludedBy: string | null;
@@ -9,14 +11,21 @@ interface ClickGeometry {
 }
 export declare const NO_GEOMETRY: ClickGeometry;
 export declare function mouseEventFor(el: Element, type: string, init?: MouseEventInit): MouseEvent;
+export interface ClickInput {
+    modifiers: ModifierFlags;
+    button: ClickButton;
+}
+export declare const PLAIN_CLICK: ClickInput;
+export declare function clickInputOf(args: Record<string, unknown>): ClickInput;
 export declare function fireClickSequence(el: ActionTarget, hold?: {
     ms: number;
     sleep: (ms: number) => Promise<void>;
     now: () => number;
-}, detail?: number): Promise<{
+}, detail?: number, input?: ClickInput): Promise<{
     prevented: boolean;
     heldMs: number;
 }>;
+export declare function scrollIntoViewNow(el: Element, options?: ScrollIntoViewOptions): void;
 export declare function isOffViewport(el: Element, rect: DOMRect): boolean;
 export declare function clickGeometry(el: ActionTarget): ClickGeometry;
 export declare function firePointer(el: Element, type: string, relatedTarget?: EventTarget | null): void;

package/dist/actions/actions-dom.js

@@ -4,6 +4,8 @@ import { getAccessibleName, getRole } from '../dom/a11y.js';
 import { hitTestOccluder } from '../dom/occlusion.js';
 import { nativeFrame } from '../timers/native/native-timers.js';
 import { asSyntheticInput } from './synthetic/synthetic-input.js';
+import { ClickButton, clickButtonFromArgs } from '@reticlehq/core';
+import { pressModifiers } from './actions-press.js';
 export const NO_GEOMETRY = {
     occluded: false,
     occludedBy: null,
@@ -20,7 +22,22 @@ function pointerEventFor(el, type, init) {
 }
 const BUTTON_HELD = 1;
 const BUTTON_RELEASED = 0;
-function fireAt(el, type, at, buttons, related, detail = 0) {
+export const PLAIN_CLICK = {
+    modifiers: { metaKey: false, ctrlKey: false, shiftKey: false, altKey: false },
+    button: ClickButton.LEFT,
+};
+const BUTTON_CODES = {
+    [ClickButton.LEFT]: { button: 0, bit: 1 },
+    [ClickButton.RIGHT]: { button: 2, bit: 2 },
+    [ClickButton.MIDDLE]: { button: 1, bit: 4 },
+};
+export function clickInputOf(args) {
+    return {
+        modifiers: pressModifiers(args),
+        button: clickButtonFromArgs(args) ?? ClickButton.LEFT,
+    };
+}
+function fireAt(el, type, at, buttons, related, detail = 0, input = PLAIN_CLICK) {
     const init = {
         bubbles: !(type.endsWith('enter') || type.endsWith('leave')),
         cancelable: true,
@@ -30,40 +47,55 @@ function fireAt(el, type, at, buttons, related, detail = 0) {
         screenX: at.x,
         screenY: at.y,
         buttons,
-        button: 0,
+        button: BUTTON_CODES[input.button].button,
+        ...input.modifiers,
         ...(related !== undefined ? { relatedTarget: related } : {}),
     };
     return el.dispatchEvent(type.startsWith('pointer')
         ? pointerEventFor(el, type, { ...init, pointerId: 1, isPrimary: true })
         : mouseEventFor(el, type, init));
 }
-export async function fireClickSequence(el, hold, detail) {
+export async function fireClickSequence(el, hold, detail, input = PLAIN_CLICK) {
     const doc = el.ownerDocument;
     const from = doc.activeElement ?? doc.body;
     const at = centreOf(el);
     const d = detail ?? 0;
-    asSyntheticInput(() => fireAt(el, 'pointerdown', at, BUTTON_HELD, from, d));
-    asSyntheticInput(() => fireAt(el, 'mousedown', at, BUTTON_HELD, undefined, d));
-    if (el.tabIndex >= 0 && 'function' === typeof el.focus)
+    const held = BUTTON_CODES[input.button].bit;
+    const isLeft = ClickButton.LEFT === input.button;
+    let notPrevented = true;
+    asSyntheticInput(() => fireAt(el, 'pointerdown', at, held, from, d, input));
+    asSyntheticInput(() => fireAt(el, 'mousedown', at, held, undefined, d, input));
+    if (ClickButton.RIGHT === input.button) {
+        notPrevented = asSyntheticInput(() => fireAt(el, 'contextmenu', at, held, undefined, d, input));
+    }
+    if (el.tabIndex >= 0 && 'function' === typeof el.focus) {
         el.focus();
+    }
     let heldMs = 0;
     if (hold !== undefined && hold.ms > 0) {
         const startedAt = hold.now();
         await hold.sleep(hold.ms);
         heldMs = hold.now() - startedAt;
     }
-    asSyntheticInput(() => fireAt(el, 'pointerup', at, BUTTON_RELEASED, from, d));
-    asSyntheticInput(() => fireAt(el, 'mouseup', at, BUTTON_RELEASED, undefined, d));
-    const notPrevented = asSyntheticInput(() => fireAt(el, 'click', at, BUTTON_RELEASED, undefined, d));
+    asSyntheticInput(() => fireAt(el, 'pointerup', at, BUTTON_RELEASED, from, d, input));
+    asSyntheticInput(() => fireAt(el, 'mouseup', at, BUTTON_RELEASED, undefined, d, input));
+    const clicked = asSyntheticInput(() => fireAt(el, isLeft ? 'click' : 'auxclick', at, BUTTON_RELEASED, undefined, d, input));
+    if (ClickButton.RIGHT !== input.button) {
+        notPrevented = clicked;
+    }
     return { prevented: !notPrevented, heldMs };
 }
 function isMeasurable(rect) {
     return rect.width > 0 || rect.height > 0;
 }
+export function scrollIntoViewNow(el, options = {}) {
+    el.scrollIntoView({ ...options, behavior: 'instant' });
+}
 export function isOffViewport(el, rect) {
     const win = el.ownerDocument.defaultView;
-    if (null === win)
+    if (null === win) {
         return false;
+    }
     const cx = rect.left + rect.width / 2;
     const cy = rect.top + rect.height / 2;
     return cx < 0 || cy < 0 || cx > win.innerWidth || cy > win.innerHeight;
@@ -76,26 +108,30 @@ function hitTest(el, rect) {
 }
 function nameOf(el) {
     const testid = readTestId(el);
-    if (testid !== null && testid.length > 0)
+    if (testid !== null && testid.length > 0) {
         return `[data-testid="${testid}"]`;
+    }
     const name = getAccessibleName(el).trim();
     return name.length > 0 ? `${getRole(el)} "${name.slice(0, 40)}"` : el.tagName.toLowerCase();
 }
 function hasNoSize(el) {
-    if (typeof el.getClientRects !== 'function')
+    if (typeof el.getClientRects !== 'function') {
         return false;
+    }
     const rects = Array.from(el.getClientRects());
     return rects.length > 0 && rects.every((r) => 0 === r.width || 0 === r.height);
 }
 export function clickGeometry(el) {
-    if (typeof el.getBoundingClientRect !== 'function')
+    if (typeof el.getBoundingClientRect !== 'function') {
         return NO_GEOMETRY;
+    }
     let rect = el.getBoundingClientRect();
-    if (!isMeasurable(rect))
+    if (!isMeasurable(rect)) {
         return hasNoSize(el) ? { ...NO_GEOMETRY, noSize: true } : NO_GEOMETRY;
+    }
     let scrolledIntoView = false;
     if (isOffViewport(el, rect) && 'function' === typeof el.scrollIntoView) {
-        el.scrollIntoView({ block: 'center', inline: 'center' });
+        scrollIntoViewNow(el, { block: 'center', inline: 'center' });
         scrolledIntoView = true;
         rect = el.getBoundingClientRect();
     }
@@ -109,15 +145,17 @@ export function firePointerNonBubbling(el, type, relatedTarget = null) {
     asSyntheticInput(() => el.dispatchEvent(pointerEventFor(el, type, { bubbles: false, cancelable: true, relatedTarget })));
 }
 function makeDataTransfer(data) {
-    if (typeof DataTransfer !== 'function')
+    if (typeof DataTransfer !== 'function') {
         return null;
+    }
     const dt = new DataTransfer();
     const entries = Array.isArray(data) ? data : data !== undefined ? [data] : [];
     for (const entry of entries) {
         if ('object' === typeof entry && entry !== null) {
             const e = entry;
-            if ('string' === typeof e.mime && 'string' === typeof e.value)
+            if ('string' === typeof e.mime && 'string' === typeof e.value) {
                 dt.setData(e.mime, e.value);
+            }
         }
     }
     return dt;
@@ -174,8 +212,9 @@ export async function dragElement(source, target, data) {
     if ('function' === typeof DragEvent) {
         const dataTransfer = makeDataTransfer(data);
         const init = { bubbles: true, cancelable: true };
-        if (dataTransfer !== null)
+        if (dataTransfer !== null) {
             init.dataTransfer = dataTransfer;
+        }
         source.dispatchEvent(new DragEvent('dragstart', init));
         await nativeFrame();
         dest.dispatchEvent(new DragEvent('dragenter', init));
@@ -190,8 +229,9 @@ export async function fireTapSequence(el, hold) {
     const touches = touchListFor(el);
     firePointerTouch(el, 'pointerdown');
     asSyntheticInput(() => el.dispatchEvent(makeTouchEvent('touchstart', touches)));
-    if (el.tabIndex >= 0 && 'function' === typeof el.focus)
+    if (el.tabIndex >= 0 && 'function' === typeof el.focus) {
         el.focus();
+    }
     let heldMs = 0;
     if (hold !== undefined && hold.ms > 0) {
         const started = hold.now();
@@ -214,8 +254,9 @@ function firePointerTouch(el, type) {
     })));
 }
 function touchListFor(el) {
-    if ('function' !== typeof Touch || 'function' !== typeof el.getBoundingClientRect)
+    if ('function' !== typeof Touch || 'function' !== typeof el.getBoundingClientRect) {
         return [];
+    }
     const rect = el.getBoundingClientRect();
     try {
         return [
@@ -251,10 +292,12 @@ const POPUP_ROLES = new Set(['menu', 'menubar', 'listbox', 'dialog', 'alertdialo
 const CLOSED_STATE = 'closed';
 export function assertNotLeaving(el) {
     for (let up = el.parentElement; up !== null; up = up.parentElement) {
-        if (CLOSED_STATE !== up.getAttribute('data-state'))
+        if (CLOSED_STATE !== up.getAttribute('data-state')) {
             continue;
-        if (!POPUP_ROLES.has(up.getAttribute('role') ?? ''))
+        }
+        if (!POPUP_ROLES.has(up.getAttribute('role') ?? '')) {
             continue;
+        }
         throw new Error(`'${up.getAttribute('role') ?? 'popup'}' holding this element is closing (data-state="closed"), ` +
             'so a person could not click it: look again once it has gone and act on what is open');
     }

package/dist/actions/actions.js

@@ -1,12 +1,13 @@
-import { ActionType, ActionWarning, clampHoldMs, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, NATIVE_INPUT_ARG, SettleReason, } from '@reticlehq/core';
+import { ActionType, ActionWarning, clampHoldMs, clickInputProblem, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, NATIVE_INPUT_ARG, SettleReason, } from '@reticlehq/core';
 import { isHiddenNativeOption } from '../dom/query-finders.js';
 import { isReticleUi } from '../dom/dom-ignore.js';
 import { asSyntheticInput } from './synthetic/synthetic-input.js';
 import { echoRef, refs } from '../dom/addressing/refs.js';
 import { requiresDangerousConfirmation, assertOutwardAllowed, assertPaymentEntryAllowed, submitControlFor, } from './danger-context.js';
 import { assertEditable, assertNotRichText, isAutofillSafeTarget, setNativeValue, } from './value-input.js';
-import { getStates } from '../dom/a11y.js';
+import { getRole, getStates } from '../dom/a11y.js';
 import { isVisible } from '../dom/visibility.js';
+import { selectInCombobox } from './select-combobox.js';
 import { elementHasHoverHandlers } from '../registry/stores/adapters.js';
 import { isActionTarget, isForm, isInput, isSelect, isTextArea, } from '../dom/realm.js';
 import { asSettleBudget, nativeSetTimeout, settle } from '../timers/native/native-timers.js';
@@ -99,7 +100,7 @@ function optionValueFor(options, named) {
     const byLabel = options.filter((option) => option.label.trim() === named.trim());
     return 1 === byLabel.length ? (byLabel[0]?.value ?? named) : named;
 }
-import { NO_GEOMETRY, fireClickSequence, fireTapSequence, clickGeometry, firePointer, firePointerNonBubbling, dragElement, mouseEventFor, assertNotLeaving, } from './actions-dom.js';
+import { NO_GEOMETRY, fireClickSequence, fireTapSequence, clickGeometry, firePointer, firePointerNonBubbling, dragElement, mouseEventFor, assertNotLeaving, scrollIntoViewNow, clickInputOf, } from './actions-dom.js';
 import { scrollFrom } from './scroll.js';
 import { clickHitsNoControl } from './click-target.js';
 function enabledOf(el) {
@@ -121,7 +122,7 @@ function activeRef(el) {
 async function dispatchFor(el, action, args) {
     if (ActionType.CLICK === action) {
         const hold = clampHoldMs(args['holdMs']);
-        return await fireClickSequence(el, 0 === hold ? undefined : { ms: hold, sleep, now: () => Date.now() });
+        return await fireClickSequence(el, 0 === hold ? undefined : { ms: hold, sleep, now: () => Date.now() }, undefined, clickInputOf(args));
     }
     if (ActionType.TAP === action) {
         const hold = clampHoldMs(args['holdMs']);
@@ -132,15 +133,27 @@ async function dispatchFor(el, action, args) {
 export const ZOOM_NEEDS_REAL_BROWSER_MSG = 'cannot zoom from inside the page — CSS zoom changes how it LOOKS without changing the layout ' +
     'viewport, visualViewport or media queries, so a layout that breaks at 200% would be reported as ' +
     'checked and passing. Drive a real browser (reticle drive <url>, or reticle_lease) and zoom there.';
+function isAriaCombobox(el) {
+    return 'combobox' === getRole(el) || 'listbox' === el.getAttribute('aria-haspopup');
+}
+const SELECT_ON_COMBOBOX_MSG = (tag) => `cannot select on a <${tag}> — it is an ARIA combobox, not a native <select>. ` +
+    'Click the combobox to open it, then click the option with { role: "option", name: "<label>" }.';
 function asFiniteNumber(raw) {
     return 'number' === typeof raw && Number.isFinite(raw) ? raw : undefined;
 }
 async function dispatchOther(el, action, args) {
     switch (action) {
-        case ActionType.DBLCLICK:
-            await fireClickSequence(el, undefined, 1);
-            await fireClickSequence(el, undefined, 2);
-            return !asSyntheticInput(() => el.dispatchEvent(mouseEventFor(el, 'dblclick', { bubbles: true, cancelable: true, detail: 2 })));
+        case ActionType.DBLCLICK: {
+            const input = clickInputOf(args);
+            await fireClickSequence(el, undefined, 1, input);
+            await fireClickSequence(el, undefined, 2, input);
+            return !asSyntheticInput(() => el.dispatchEvent(mouseEventFor(el, 'dblclick', {
+                bubbles: true,
+                cancelable: true,
+                detail: 2,
+                ...input.modifiers,
+            })));
+        }
         case ActionType.HOVER: {
             const doc = el.ownerDocument;
             const from = doc.activeElement ?? doc.body;
@@ -215,6 +228,12 @@ async function dispatchOther(el, action, args) {
                 el.dispatchEvent(new Event('change', { bubbles: true }));
                 return false;
             }
+            if (isAriaCombobox(el)) {
+                if (typeof args['value'] !== 'string') {
+                    throw new Error("select requires a string `value` — pass it nested, as args: { value: '…' }.");
+                }
+                return await selectInCombobox(el, args['value'], (target) => fireClickSequence(target), SELECT_ON_COMBOBOX_MSG(el.tagName.toLowerCase()));
+            }
             throw new Error(`cannot select on a <${el.tagName.toLowerCase()}>`);
         case ActionType.CHECK:
         case ActionType.UNCHECK: {
@@ -271,7 +290,7 @@ async function dispatchOther(el, action, args) {
             return !down;
         }
         case ActionType.SCROLL_INTO_VIEW:
-            el.scrollIntoView();
+            scrollIntoViewNow(el);
             return false;
         case ActionType.ZOOM:
             throw new Error(ZOOM_NEEDS_REAL_BROWSER_MSG);
@@ -325,6 +344,12 @@ async function dispatchOther(el, action, args) {
 }
 export async function executeAction(ref, action, args = {}) {
     const named = 0 < ref.length;
+    if (ActionType.CLICK === action || ActionType.DBLCLICK === action) {
+        const problem = clickInputProblem(action, args);
+        if (problem !== undefined) {
+            throw new Error(`cannot ${action}: ${problem}`);
+        }
+    }
     const el = isReflessDocumentPress(ref, action, args) ? focusedOrDocument() : requireElement(ref);
     if (named) {
         assertActionAllowed(el, action, args);
@@ -333,9 +358,19 @@ export async function executeAction(ref, action, args = {}) {
         assertNotLeaving(el);
     }
     const anchor = named ? anchorOf(el) : {};
+    const prevFocus = activeRef(el);
+    if ((ActionType.CLICK === action || ActionType.DBLCLICK === action) && !enabledOf(el)) {
+        const active = el.ownerDocument.activeElement;
+        if (active !== null &&
+            active !== el &&
+            active !== el.ownerDocument.body &&
+            isActionTarget(active)) {
+            active.blur();
+            await Promise.resolve();
+        }
+    }
     const visible = isVisible(el);
     const enabled = enabledOf(el);
-    const prevFocus = activeRef(el);
     const valueBefore = valueOf(el);
     const actedField = watchActedField(el);
     const geometry = CLICK_LIKE.has(action) ? clickGeometry(el) : NO_GEOMETRY;

package/dist/actions/select-combobox.d.ts

@@ -0,0 +1,6 @@
+import type { ActionTarget } from '../dom/realm.js';
+type ClickFn = (el: ActionTarget) => Promise<{
+    prevented: boolean;
+}>;
+export declare function selectInCombobox(trigger: ActionTarget, wanted: string, click: ClickFn, noPopupMessage: string): Promise<boolean>;
+export {};

package/dist/actions/select-combobox.js

@@ -0,0 +1,69 @@
+import { echoRef } from '../dom/addressing/refs.js';
+import { getAccessibleName } from '../dom/a11y.js';
+import { isReticleUi } from '../dom/dom-ignore.js';
+import { isVisible } from '../dom/visibility.js';
+import { nativeFrame } from '../timers/native/native-timers.js';
+const OPEN_WAIT_FRAMES = 30;
+const ROLE_OPTION = 'option';
+function optionName(option) {
+    return getAccessibleName(option).trim();
+}
+function visibleOptions(trigger) {
+    const doc = trigger.ownerDocument;
+    const ids = (trigger.getAttribute('aria-controls') ?? trigger.getAttribute('aria-owns') ?? '')
+        .split(/\s+/)
+        .filter((id) => 0 < id.length);
+    const popups = ids
+        .map((id) => doc.getElementById(id))
+        .filter((popup) => null !== popup);
+    const roots = 0 < popups.length ? popups : [doc];
+    return roots
+        .flatMap((root) => Array.from(root.querySelectorAll(`[role="${ROLE_OPTION}"]`)))
+        .filter((option) => !isReticleUi(option) && isVisible(option));
+}
+async function waitForOptions(trigger) {
+    for (let frame = 0; frame < OPEN_WAIT_FRAMES; frame += 1) {
+        const options = visibleOptions(trigger);
+        if (0 < options.length) {
+            return options;
+        }
+        await nativeFrame();
+    }
+    return [];
+}
+function matches(option, wanted) {
+    const asked = wanted.trim();
+    return (optionName(option) === asked ||
+        option.getAttribute('data-value') === wanted ||
+        option.getAttribute('value') === wanted);
+}
+export async function selectInCombobox(trigger, wanted, click, noPopupMessage) {
+    const openedHere = 'true' !== trigger.getAttribute('aria-expanded');
+    if (openedHere) {
+        await click(trigger);
+    }
+    const options = await waitForOptions(trigger);
+    const found = options.filter((option) => matches(option, wanted));
+    const [match] = found;
+    const problem = 0 === options.length ? noPopupMessage : problemWith(found, options, wanted);
+    if (match === undefined || problem !== undefined) {
+        if (openedHere) {
+            await click(trigger);
+        }
+        throw new Error(problem ?? 'no option');
+    }
+    return (await click(match)).prevented;
+}
+function problemWith(found, options, wanted) {
+    const [match] = found;
+    if (match === undefined) {
+        return `no option '${echoRef(wanted)}' — available: ${options.map(optionName).join(', ')}`;
+    }
+    if (1 < found.length) {
+        return `${found.length} options match '${echoRef(wanted)}' — name one by its exact label`;
+    }
+    if ('true' === match.getAttribute('aria-disabled')) {
+        return `cannot select a disabled option '${echoRef(wanted)}' — a real user could not, so neither will Reticle`;
+    }
+    return undefined;
+}

package/dist/commands/commands.js

@@ -1,4 +1,4 @@
-import { ComponentStateReason, ElementQuerySchema, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
+import { ComponentStateReason, ElementQuerySchema, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, MatchArg, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
 import { buildSnapshot } from '../dom/snapshot.js';
 import { paintContextOf } from '../dom/paint-context.js';
 import { matchQuery, runQuery } from '../dom/query.js';
@@ -19,7 +19,7 @@ import { sanitizeWithReport } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
 import { freezeClock, advanceClock, resetClock, isClockFrozen } from '../timers/clock.js';
 import { scrollContainer } from '../actions/scroll.js';
-import { isOffViewport } from '../actions/actions-dom.js';
+import { isOffViewport, scrollIntoViewNow } from '../actions/actions-dom.js';
 export const RELOAD_CACHE_BUST_PARAM = '_reticle_reload';
 function str(value) {
     return 'string' === typeof value ? value : undefined;
@@ -69,7 +69,7 @@ function inspect(ref, reveal = false) {
         'function' === typeof el.scrollIntoView &&
         isOffViewport(el, el.getBoundingClientRect());
     if (scrolledIntoView) {
-        el.scrollIntoView({ block: 'center', inline: 'center' });
+        scrollIntoViewNow(el, { block: 'center', inline: 'center' });
     }
     const rect = el.getBoundingClientRect();
     const component = identifyComponent(el);
@@ -216,7 +216,7 @@ export function createCommandRegistry() {
         const limit = args['limit'];
         return runQuery(queryFromArgs(args), 'number' === typeof limit ? limit : undefined);
     });
-    reg.set(ReticleCommand.MATCH, (args) => matchQuery(ElementQuerySchema.parse(record(args['query'])), str(args['state']), undefined, undefined, true === args['diagnose']));
+    reg.set(ReticleCommand.MATCH, (args) => matchQuery(ElementQuerySchema.parse(record(args['query'])), str(args['state']), undefined, undefined, true === args['diagnose'], true === args[MatchArg.FULL_TEXT]));
     reg.set(ReticleCommand.ACT, async (args) => {
         const action = str(args['action']) ?? '';
         const result = await executeAction(str(args['ref']) ?? '', action, record(args['args']));

package/dist/dom/a11y.d.ts

@@ -4,4 +4,4 @@ export declare function getAccessibleName(el: Element): string;
 export declare function getStates(el: Element, visible?: boolean): ElementState[];
 export declare function isSensitiveField(el: Element): boolean;
 export declare function getValue(el: Element): string | undefined;
-export declare function describe(el: Element, memo?: Map<Element, boolean>): ElementDescriptor;
+export declare function describe(el: Element, memo?: Map<Element, boolean>, fullText?: boolean): ElementDescriptor;

package/dist/dom/a11y.js

@@ -1,5 +1,5 @@
 import { readTestId } from './addressing/testid-attr.js';
-import { DEFAULT_TESTID_ATTR, ElementState, REDACTED_VALUE, } from '@reticlehq/core';
+import { DEFAULT_TESTID_ATTR, ElementState, REDACTED_VALUE, TRANSPORT_LIMITS, } from '@reticlehq/core';
 import { isButton, isImage, isInput, isMeter, isOutput, isProgress, isSelect, isTextArea, } from './realm.js';
 import { refs } from './addressing/refs.js';
 import { inspectChart } from './chart.js';
@@ -360,14 +360,14 @@ export function getValue(el) {
     const valueNow = el.getAttribute('aria-valuenow');
     return valueNow ?? undefined;
 }
-const MAX_TEXT = 80;
-function getVisibleText(el) {
+function getVisibleText(el, fullText) {
     const text = collapse(el.textContent ?? '');
-    return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}…` : text;
+    const max = fullText ? TRANSPORT_LIMITS.MAX_FULL_TEXT : TRANSPORT_LIMITS.MAX_DESCRIBED_TEXT;
+    return text.length > max ? `${text.slice(0, max)}…` : text;
 }
-export function describe(el, memo) {
+export function describe(el, memo, fullText = false) {
     const value = getValue(el);
-    const text = getVisibleText(el);
+    const text = getVisibleText(el, fullText);
     const name = getAccessibleName(el);
     const visible = isVisible(el, memo);
     const base = {
@@ -380,7 +380,7 @@ export function describe(el, memo) {
     if (value !== undefined && value.length > 0) {
         base.value = value;
     }
-    if (text.length > 0 && text !== name) {
+    if (text.length > 0 && (fullText || text !== name)) {
         base.text = text;
     }
     const source = formatSource(sourceFromDom(el));

package/dist/dom/query.d.ts

@@ -1,5 +1,8 @@
-import { ElementState, type ElementQuery, type MatchResult, type QueryResult } from '@reticlehq/core';
+import { ElementState, type ElementQuery, type MatchResult, type NearestTarget, type QueryResult } from '@reticlehq/core';
 export declare const ATTR_VALUE_MAX = 512;
-export declare function matchQuery(query: ElementQuery, state?: ElementState, limit?: number, wholePhrase?: boolean, diagnose?: boolean): MatchResult;
+export declare function matchQuery(query: ElementQuery, state?: ElementState, limit?: number, wholePhrase?: boolean, diagnose?: boolean, fullText?: boolean): MatchResult;
+export declare const MAX_NEAREST_NAME = 60;
+export declare function nameSimilarity(a: string, b: string): number;
+export declare function nearestTargets(container: HTMLElement, query: ElementQuery): NearestTarget[];
 export declare function elementsMatching(query: ElementQuery): HTMLElement[];
 export declare function runQuery(query: ElementQuery, limit?: number): QueryResult;

package/dist/dom/query.js

@@ -12,6 +12,7 @@ import { stableSelectorFor } from './stable-selector.js';
 import { fuzzyVisibleText, normaliseVisibleText, comparableText, foldTypography, textMatches, unreadableMatch, } from './text-match.js';
 import { pageRoute } from '../security/page-location.js';
 import { elementsUnder, findIn, isNonRendered, queryByRoleAndName } from './query-finders.js';
+import { INTERACTIVE } from './snapshot.js';
 const MAX_PRESENT_TESTIDS = 12;
 function visibleTextOf(el, memo) {
     if (isNonRendered(el) || isWordsIgnored(el)) {
@@ -149,7 +150,7 @@ function inState(el, state, memo) {
     return getStates(el, isVisible(el, memo)).includes(state);
 }
 const MAX_DESCRIBED = TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS;
-export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = true, diagnose = true) {
+export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = true, diagnose = true, fullText = false) {
     const found = findCandidates(query);
     const scopeMissing = found.scopeMissing;
     const wanted = wholePhrase && textOnly(query) ? wantedTextOf(query) : undefined;
@@ -159,10 +160,13 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = tr
     const visMemo = new Map();
     const filtered = state === undefined ? elements : elements.filter((el) => inState(el, state, visMemo));
     const attrs = query.attrs;
-    const described = filtered.slice(0, Math.max(0, Math.min(limit, MAX_DESCRIBED)));
+    const cap = fullText
+        ? Math.min(MAX_DESCRIBED, TRANSPORT_LIMITS.MAX_FULL_TEXT_ELEMENTS)
+        : MAX_DESCRIBED;
+    const described = filtered.slice(0, Math.max(0, Math.min(limit, cap)));
     const stampViewport = described.length > 1 || ElementState.IN_VIEWPORT === state;
     const descriptors = described.map((el) => {
-        let base = describe(el, visMemo);
+        let base = describe(el, visMemo, fullText);
         if (stampViewport &&
             isInViewport(el, visMemo) &&
             !base.states.includes(ElementState.IN_VIEWPORT)) {
@@ -180,6 +184,7 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = tr
         matched: filtered.length > 0,
         count: filtered.length,
         elements: descriptors,
+        ...(fullText ? { fullText: true } : {}),
         ...(scopeMissing ? { scopeMissing: true } : {}),
         ...(covered === undefined ? {} : { coveredBy: covered }),
         ...(unreadable === undefined ? {} : { unreadable }),
@@ -346,6 +351,81 @@ function nameNearMisses(container, query) {
     }
     return out;
 }
+const MAX_NEAREST_TARGETS = 3;
+export const MAX_NEAREST_NAME = 60;
+function bigrams(value) {
+    const padded = ` ${value} `;
+    const out = new Set();
+    for (let i = 0; i < padded.length - 1; i += 1) {
+        out.add(padded.slice(i, i + 2));
+    }
+    return out;
+}
+export function nameSimilarity(a, b) {
+    const left = bigrams(foldTypography(a).toLowerCase());
+    const right = bigrams(foldTypography(b).toLowerCase());
+    let shared = 0;
+    for (const gram of left) {
+        if (right.has(gram)) {
+            shared += 1;
+        }
+    }
+    return (2 * shared) / (left.size + right.size);
+}
+function askedRole(query) {
+    return QueryBy.ROLE === query.by ? query.value : query.role;
+}
+function askedName(query) {
+    const value = QueryBy.ROLE === query.by ? undefined : query.value;
+    const asked = query.name ??
+        value ??
+        query.text ??
+        query.label ??
+        query.placeholder ??
+        query.testid ??
+        query.alt;
+    return asked === undefined ? '' : normaliseVisibleText(asked);
+}
+export function nearestTargets(container, query) {
+    const role = askedRole(query);
+    const name = askedName(query);
+    if (role === undefined && 0 === name.length) {
+        return [];
+    }
+    const memo = new Map();
+    const scored = [];
+    for (const el of elementsUnder(container)) {
+        const elRole = getRole(el);
+        const roleMatch = role !== undefined && elRole === role;
+        if (!roleMatch && !INTERACTIVE.has(elRole)) {
+            continue;
+        }
+        if (isIgnored(el) || !isVisible(el, memo)) {
+            continue;
+        }
+        const elName = normaliseVisibleText(getAccessibleName(el));
+        if (0 === elName.length) {
+            continue;
+        }
+        const score = 0 === name.length ? 0 : nameSimilarity(name, elName);
+        if (!roleMatch && 0 === score) {
+            continue;
+        }
+        scored.push({ el, role: elRole, name: elName, roleMatch, score });
+    }
+    scored.sort((a, b) => Number(b.roleMatch) - Number(a.roleMatch) || b.score - a.score);
+    return scored.slice(0, MAX_NEAREST_TARGETS).map((c) => {
+        const target = {
+            ref: refs.refFor(c.el),
+            role: c.role,
+            name: c.name.slice(0, MAX_NEAREST_NAME),
+        };
+        if (c.name.length > MAX_NEAREST_NAME) {
+            target.nameTruncated = true;
+        }
+        return target;
+    });
+}
 function testidFoundUnder(container, query) {
     if (QueryBy.TESTID !== query.by || undefined === query.value) {
         return undefined;
@@ -452,6 +532,10 @@ function buildEmptyHint(query, state, diagnose = true) {
     if (elsewhere !== undefined) {
         hint.testidFoundUnder = elsewhere;
     }
+    const nearest = diagnose ? nearestTargets(container, query) : [];
+    if (nearest.length > 0) {
+        hint.nearest = nearest;
+    }
     return hint;
 }
 export function elementsMatching(query) {
@@ -464,7 +548,7 @@ export function runQuery(query, limit) {
         return {
             elements: result.elements,
             count: result.count,
-            hint: buildEmptyHint(query),
+            hint: result.hint ?? buildEmptyHint(query),
             ...scopeFields,
         };
     }