@reticlehq/browser 3.8.1 → 3.8.2

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,11 +11,17 @@ 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;
 }>;

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,31 +47,42 @@ 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) {
@@ -62,8 +90,9 @@ function isMeasurable(rect) {
 }
 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,23 +105,27 @@ 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' });
@@ -109,15 +142,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 +209,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 +226,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 +251,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 +289,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, 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: {
@@ -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);

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;
+}