@reticlehq/browser 3.5.0 → 3.7.0

package/dist/actions/action-report.d.ts

@@ -0,0 +1,54 @@
+import { type SettleReason } from '@reticlehq/core';
+export interface ActionEffect {
+    dispatched: true;
+    targetMatched: boolean;
+    visible: boolean;
+    enabled: boolean;
+    defaultPrevented: boolean;
+    focusMoved: string | null;
+    valueChanged: boolean;
+    autofillSafe?: true;
+    domMutatedWithin: number;
+    appeared?: string;
+    occluded: boolean;
+    occludedBy: string | null;
+    scrolledIntoView: boolean;
+    heldMs?: number;
+    alreadyAtValue?: true;
+}
+export interface ActionResult {
+    ok: true;
+    ref: string;
+    action: string;
+    dispatched: boolean;
+    settled: boolean;
+    settleReason: SettleReason | null;
+    effect: ActionEffect;
+    testid?: string;
+    component?: string;
+    role?: string;
+    name?: string;
+    nth?: number;
+    of?: number;
+    source?: {
+        file: string;
+        line: number;
+        column?: number;
+    };
+    warning?: string;
+}
+export interface CapturedAnchor {
+    testid?: string;
+    component?: string;
+    source?: {
+        file: string;
+        line: number;
+        column?: number;
+    };
+    role?: string;
+    name?: string;
+    nth?: number;
+    of?: number;
+}
+export declare function anchorOf(el: Element): CapturedAnchor;
+export declare const result: (ref: string, action: string, effect: ActionEffect, settled: boolean, settleReason: SettleReason | null, anchor: CapturedAnchor, warning?: string) => ActionResult;

package/dist/actions/action-report.js

@@ -0,0 +1,60 @@
+import { readTestId } from '../dom/addressing/testid-attr.js';
+import { QueryBy } from '@reticlehq/core';
+import { elementsMatching } from '../dom/query.js';
+import { getAccessibleName, getRole } from '../dom/a11y.js';
+import { identifyComponent } from '../registry/stores/adapters.js';
+export function anchorOf(el) {
+    const testid = readTestId(el) ?? undefined;
+    const info = identifyComponent(el);
+    const out = {};
+    if (testid !== undefined)
+        out.testid = testid;
+    const component = info?.componentStack[0];
+    if (component !== undefined)
+        out.component = component;
+    if (info?.source !== undefined)
+        out.source = info.source;
+    const role = getRole(el);
+    const name = getAccessibleName(el);
+    if (role.length > 0)
+        out.role = role;
+    if (name.length > 0)
+        out.name = name;
+    if (role.length > 0 && name.length > 0) {
+        const same = elementsMatching({ by: QueryBy.ROLE, value: role, name });
+        const at = same.indexOf(el);
+        if (1 < same.length && 0 <= at) {
+            out.nth = at;
+            out.of = same.length;
+        }
+    }
+    return out;
+}
+export const result = (ref, action, effect, settled, settleReason, anchor, warning) => {
+    const base = {
+        ok: true,
+        ref,
+        action,
+        dispatched: true,
+        settled,
+        settleReason,
+        effect,
+    };
+    if (anchor.testid !== undefined)
+        base.testid = anchor.testid;
+    if (anchor.component !== undefined)
+        base.component = anchor.component;
+    if (anchor.source !== undefined)
+        base.source = anchor.source;
+    if (anchor.role !== undefined)
+        base.role = anchor.role;
+    if (anchor.name !== undefined)
+        base.name = anchor.name;
+    if (anchor.nth !== undefined)
+        base.nth = anchor.nth;
+    if (anchor.of !== undefined)
+        base.of = anchor.of;
+    if (warning !== undefined)
+        base.warning = warning;
+    return base;
+};

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

@@ -26,4 +26,5 @@ export declare function fireTapSequence(el: ActionTarget, hold: {
     prevented: boolean;
     heldMs: number;
 }>;
+export declare function assertNotLeaving(el: Element): void;
 export {};

package/dist/actions/actions-dom.js

@@ -16,12 +16,32 @@ function pointerEventFor(el, type, init) {
         ? new PointerEvent(type, full)
         : new MouseEvent(type, full);
 }
+const BUTTON_HELD = 1;
+const BUTTON_RELEASED = 0;
+function fireAt(el, type, at, buttons, related, detail = 0) {
+    const init = {
+        bubbles: !(type.endsWith('enter') || type.endsWith('leave')),
+        cancelable: true,
+        detail,
+        clientX: at.x,
+        clientY: at.y,
+        screenX: at.x,
+        screenY: at.y,
+        buttons,
+        button: 0,
+        ...(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) {
     const doc = el.ownerDocument;
     const from = doc.activeElement ?? doc.body;
-    const init = { bubbles: true, cancelable: true, detail: detail ?? 0 };
-    firePointer(el, 'pointerdown', from);
-    asSyntheticInput(() => el.dispatchEvent(mouseEventFor(el, 'mousedown', init)));
+    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)
         el.focus();
     let heldMs = 0;
@@ -30,9 +50,9 @@ export async function fireClickSequence(el, hold, detail) {
         await hold.sleep(hold.ms);
         heldMs = hold.now() - startedAt;
     }
-    firePointer(el, 'pointerup', from);
-    asSyntheticInput(() => el.dispatchEvent(mouseEventFor(el, 'mouseup', init)));
-    const notPrevented = asSyntheticInput(() => el.dispatchEvent(mouseEventFor(el, 'click', init)));
+    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));
     return { prevented: !notPrevented, heldMs };
 }
 function isMeasurable(rect) {
@@ -86,8 +106,6 @@ function makeDataTransfer(data) {
     }
     return dt;
 }
-const BUTTON_HELD = 1;
-const BUTTON_RELEASED = 0;
 const DRAG_STEPS = 5;
 function centreOf(el) {
     const box = el.getBoundingClientRect();
@@ -100,28 +118,11 @@ export async function dragElement(source, target, data) {
     const dest = target ?? source;
     const from = centreOf(source);
     const to = centreOf(dest);
-    const fire = (el, type, at, buttons, related) => {
-        const bubbles = !(type.endsWith('enter') || type.endsWith('leave'));
-        const init = {
-            bubbles,
-            cancelable: true,
-            clientX: at.x,
-            clientY: at.y,
-            screenX: at.x,
-            screenY: at.y,
-            buttons,
-            button: 0,
-            ...(related !== undefined ? { relatedTarget: related } : {}),
-        };
-        el.dispatchEvent(type.startsWith('pointer')
-            ? pointerEventFor(el, type, { ...init, pointerId: 1, isPrimary: true })
-            : mouseEventFor(el, type, init));
-    };
     const sourceRect = source.getBoundingClientRect();
     const destRect = target !== null ? dest.getBoundingClientRect() : null;
     const crosses = (rect, p) => p.x >= rect.left && p.x <= rect.right && p.y >= rect.top && p.y <= rect.bottom;
-    fire(source, 'pointerdown', from, BUTTON_HELD);
-    fire(source, 'mousedown', from, BUTTON_HELD);
+    fireAt(source, 'pointerdown', from, BUTTON_HELD);
+    fireAt(source, 'mousedown', from, BUTTON_HELD);
     await nativeFrame();
     let leftSource = false;
     let enteredDest = false;
@@ -129,30 +130,30 @@ export async function dragElement(source, target, data) {
         const at = lerp(from, to, step / DRAG_STEPS);
         if (!leftSource && !crosses(sourceRect, at)) {
             leftSource = true;
-            fire(source, 'pointerout', at, BUTTON_HELD, dest);
-            fire(source, 'mouseout', at, BUTTON_HELD, dest);
-            fire(source, 'pointerleave', at, BUTTON_HELD, dest);
-            fire(source, 'mouseleave', at, BUTTON_HELD, dest);
+            fireAt(source, 'pointerout', at, BUTTON_HELD, dest);
+            fireAt(source, 'mouseout', at, BUTTON_HELD, dest);
+            fireAt(source, 'pointerleave', at, BUTTON_HELD, dest);
+            fireAt(source, 'mouseleave', at, BUTTON_HELD, dest);
         }
         if (leftSource && !enteredDest && destRect !== null && crosses(destRect, at)) {
             enteredDest = true;
-            fire(dest, 'pointerover', at, BUTTON_HELD, source);
-            fire(dest, 'mouseover', at, BUTTON_HELD, source);
-            fire(dest, 'pointerenter', at, BUTTON_HELD, source);
-            fire(dest, 'mouseenter', at, BUTTON_HELD, source);
+            fireAt(dest, 'pointerover', at, BUTTON_HELD, source);
+            fireAt(dest, 'mouseover', at, BUTTON_HELD, source);
+            fireAt(dest, 'pointerenter', at, BUTTON_HELD, source);
+            fireAt(dest, 'mouseenter', at, BUTTON_HELD, source);
         }
-        fire(dest, 'pointermove', at, BUTTON_HELD);
-        fire(dest, 'mousemove', at, BUTTON_HELD);
+        fireAt(dest, 'pointermove', at, BUTTON_HELD);
+        fireAt(dest, 'mousemove', at, BUTTON_HELD);
         await nativeFrame();
     }
     if (!enteredDest && destRect !== null) {
-        fire(dest, 'pointerover', to, BUTTON_HELD, source);
-        fire(dest, 'mouseover', to, BUTTON_HELD, source);
-        fire(dest, 'pointerenter', to, BUTTON_HELD, source);
-        fire(dest, 'mouseenter', to, BUTTON_HELD, source);
+        fireAt(dest, 'pointerover', to, BUTTON_HELD, source);
+        fireAt(dest, 'mouseover', to, BUTTON_HELD, source);
+        fireAt(dest, 'pointerenter', to, BUTTON_HELD, source);
+        fireAt(dest, 'mouseenter', to, BUTTON_HELD, source);
     }
-    fire(dest, 'pointerup', to, BUTTON_RELEASED);
-    fire(dest, 'mouseup', to, BUTTON_RELEASED);
+    fireAt(dest, 'pointerup', to, BUTTON_RELEASED);
+    fireAt(dest, 'mouseup', to, BUTTON_RELEASED);
     let dropPrevented = false;
     if ('function' === typeof DragEvent) {
         const dataTransfer = makeDataTransfer(data);
@@ -230,3 +231,15 @@ function makeTouchEvent(type, touches) {
     }
     return new Event(type, { bubbles: true, cancelable: true });
 }
+const POPUP_ROLES = new Set(['menu', 'menubar', 'listbox', 'dialog', 'alertdialog', 'tooltip']);
+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'))
+            continue;
+        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-press.d.ts

@@ -1,14 +1,21 @@
 import { type ActionTarget } from '../dom/realm.js';
 export declare function pressKey(args: Record<string, unknown>): string;
-export declare function pressModifiers(args: Record<string, unknown>): {
+export interface ModifierFlags {
     metaKey: boolean;
     ctrlKey: boolean;
     shiftKey: boolean;
     altKey: boolean;
-};
+}
+export declare function pressModifiers(args: Record<string, unknown>): ModifierFlags;
 export declare function pressCode(args: Record<string, unknown>, key: string): string;
+export declare function dispatchKeypress(el: ActionTarget, key: string, code: string, mods: ModifierFlags, repeat?: boolean): void;
 export declare function focusedOrDocument(): HTMLElement;
 export declare function isReflessDocumentPress(ref: string, action: string, args: Record<string, unknown>): boolean;
 export declare function pressKeys(args: Record<string, unknown>): string[];
-export declare function holdKey(el: ActionTarget, key: string, code: string, mods: Record<string, boolean>, ms: number): Promise<void>;
-export declare function pressCombo(el: ActionTarget, keys: readonly string[], mods: Record<string, boolean>, holdMs: number): Promise<boolean>;
+export declare const legacyKeyCode: (key: string) => number;
+export declare function keyboardEvent(type: string, init: KeyboardEventInit & {
+    key: string;
+}): KeyboardEvent;
+export declare function holdKey(el: ActionTarget, key: string, code: string, mods: ModifierFlags, ms: number): Promise<void>;
+export declare function pressCombo(el: ActionTarget, keys: readonly string[], mods: ModifierFlags, holdMs: number): Promise<boolean>;
+export declare function closeModalOnEscape(el: ActionTarget, key: string, keydownProceeded: boolean): void;

package/dist/actions/actions-press.js

@@ -1,4 +1,4 @@
-import { ActionType, isGlobalPress, pressKeyFromArgs } from '@reticlehq/core';
+import { ActionType, isGlobalPress, pressKeyFromArgs, pressKeysFromArgs } from '@reticlehq/core';
 import { asSyntheticInput } from './synthetic/synthetic-input.js';
 import { nativeSetTimeout } from '../timers/native/native-timers.js';
 const sleep = (ms) => new Promise((r) => nativeSetTimeout(r, ms));
@@ -9,16 +9,38 @@ function asString(value, fallback = '') {
 export function pressKey(args) {
     return pressKeyFromArgs(args);
 }
+const MODIFIER_FLAG_KEYS = [
+    'metaKey',
+    'ctrlKey',
+    'shiftKey',
+    'altKey',
+];
+const MODIFIER_FLAG_ALIASES = {
+    meta: 'metaKey',
+    cmd: 'metaKey',
+    command: 'metaKey',
+    super: 'metaKey',
+    win: 'metaKey',
+    control: 'ctrlKey',
+    ctrl: 'ctrlKey',
+    shift: 'shiftKey',
+    alt: 'altKey',
+    option: 'altKey',
+    opt: 'altKey',
+};
 export function pressModifiers(args) {
     const raw = args['modifiers'];
     const names = Array.isArray(raw) ? raw.map((m) => asString(m).toLowerCase()) : [];
-    const has = (...aliases) => aliases.some((a) => names.includes(a));
-    return {
-        metaKey: has('meta', 'cmd', 'command', 'super', 'win'),
-        ctrlKey: has('control', 'ctrl'),
-        shiftKey: has('shift'),
-        altKey: has('alt', 'option', 'opt'),
-    };
+    const flags = { metaKey: false, ctrlKey: false, shiftKey: false, altKey: false };
+    for (const name of names) {
+        const flag = MODIFIER_FLAG_ALIASES[name];
+        if (flag !== undefined)
+            flags[flag] = true;
+    }
+    return flags;
+}
+function modifierFlagFor(key) {
+    return MODIFIER_FLAG_ALIASES[key.toLowerCase()];
 }
 export function pressCode(args, key) {
     const explicit = args['code'];
@@ -35,6 +57,26 @@ export function pressCode(args, key) {
     }
     return /^[A-Z][A-Za-z0-9]*$/.test(key) && KNOWN_NAMED_KEYS.has(key) ? key : '';
 }
+export function dispatchKeypress(el, key, code, mods, repeat = false) {
+    if (ENTER_KEY !== key && 1 !== key.length)
+        return;
+    const event = new KeyboardEvent('keypress', {
+        key,
+        code,
+        bubbles: true,
+        cancelable: true,
+        repeat,
+        ...mods,
+    });
+    const legacy = ENTER_KEY === key ? ENTER_CHAR_CODE : key.charCodeAt(0);
+    for (const field of LEGACY_KEY_CODE_FIELDS) {
+        Object.defineProperty(event, field, { value: legacy });
+    }
+    asSyntheticInput(() => el.dispatchEvent(event));
+}
+const ENTER_KEY = 'Enter';
+const ENTER_CHAR_CODE = 13;
+const LEGACY_KEY_CODE_FIELDS = ['keyCode', 'charCode', 'which'];
 const KNOWN_NAMED_KEYS = new Set([
     'Enter',
     'Escape',
@@ -79,19 +121,45 @@ export function isReflessDocumentPress(ref, action, args) {
     return 0 === ref.length && isGlobalPress(args) && ActionType.PRESS === action;
 }
 export function pressKeys(args) {
-    const raw = args['keys'];
-    if (!Array.isArray(raw))
-        return [];
-    return raw.map((k) => asString(k)).filter((k) => k.length > 0);
+    return pressKeysFromArgs(args);
 }
 const KEY_REPEAT_MS = 33;
 const KEY_REPEAT_DELAY_MS = 500;
+const LEGACY_KEY_CODES = {
+    Backspace: 8,
+    Tab: 9,
+    Enter: 13,
+    Shift: 16,
+    Control: 17,
+    Alt: 18,
+    Escape: 27,
+    ' ': 32,
+    PageUp: 33,
+    PageDown: 34,
+    End: 35,
+    Home: 36,
+    ArrowLeft: 37,
+    ArrowUp: 38,
+    ArrowRight: 39,
+    ArrowDown: 40,
+    Delete: 46,
+    Meta: 91,
+};
+const SINGLE_ALNUM = /^[a-z0-9]$/i;
+export const legacyKeyCode = (key) => LEGACY_KEY_CODES[key] ?? (SINGLE_ALNUM.test(key) ? key.toUpperCase().charCodeAt(0) : 0);
+export function keyboardEvent(type, init) {
+    const event = new KeyboardEvent(type, init);
+    const code = legacyKeyCode(init.key);
+    for (const legacy of ['keyCode', 'which'])
+        Object.defineProperty(event, legacy, { get: () => code });
+    return event;
+}
 export async function holdKey(el, key, code, mods, ms) {
     const started = Date.now();
     if (ms > KEY_REPEAT_DELAY_MS)
         await sleep(KEY_REPEAT_DELAY_MS);
     while (Date.now() - started < ms) {
-        asSyntheticInput(() => el.dispatchEvent(new KeyboardEvent('keydown', {
+        const down = asSyntheticInput(() => el.dispatchEvent(keyboardEvent('keydown', {
             key,
             code,
             bubbles: true,
@@ -99,22 +167,69 @@ export async function holdKey(el, key, code, mods, ms) {
             repeat: true,
             ...mods,
         })));
+        if (down)
+            dispatchKeypress(el, key, code, mods, true);
         await sleep(Math.min(KEY_REPEAT_MS, Math.max(0, ms - (Date.now() - started))));
     }
 }
 export async function pressCombo(el, keys, mods, holdMs) {
+    const held = { ...mods };
+    const dispatch = (type, key) => {
+        const code = pressCode({}, key);
+        return asSyntheticInput(() => el.dispatchEvent(keyboardEvent(type, { key, code, bubbles: true, cancelable: true, ...held })));
+    };
+    const presses = new Map();
+    for (const flag of MODIFIER_FLAG_KEYS) {
+        if (held[flag])
+            presses.set(flag, 1);
+    }
+    const pressFlag = (flag) => {
+        presses.set(flag, (presses.get(flag) ?? 0) + 1);
+        held[flag] = true;
+    };
+    const releaseFlag = (flag) => {
+        const left = (presses.get(flag) ?? 1) - 1;
+        presses.set(flag, left);
+        if (left <= 0)
+            held[flag] = false;
+    };
     let prevented = false;
     for (const key of keys) {
-        const code = pressCode({}, key);
-        const ok = asSyntheticInput(() => el.dispatchEvent(new KeyboardEvent('keydown', { key, code, bubbles: true, cancelable: true, ...mods })));
+        const flag = modifierFlagFor(key);
+        if (flag !== undefined)
+            pressFlag(flag);
+        const ok = dispatch('keydown', key);
         if (!ok)
             prevented = true;
+        if (ok)
+            dispatchKeypress(el, key, pressCode({}, key), held);
+        closeModalOnEscape(el, key, ok);
     }
     if (holdMs > 0)
         await sleep(holdMs);
     for (const key of [...keys].reverse()) {
-        const code = pressCode({}, key);
-        asSyntheticInput(() => el.dispatchEvent(new KeyboardEvent('keyup', { key, code, bubbles: true, ...mods })));
+        const flag = modifierFlagFor(key);
+        if (flag !== undefined)
+            releaseFlag(flag);
+        dispatch('keyup', key);
     }
     return prevented;
 }
+export function closeModalOnEscape(el, key, keydownProceeded) {
+    if ('Escape' !== key || !keydownProceeded)
+        return;
+    for (let dialog = el.closest('dialog'); null !== dialog; dialog = dialog.parentElement?.closest('dialog') ?? null) {
+        try {
+            if (!dialog.open || !dialog.matches(':modal'))
+                continue;
+        }
+        catch {
+            return;
+        }
+        if ('function' === typeof dialog.requestClose)
+            dialog.requestClose();
+        else if (dialog.dispatchEvent(new Event('cancel', { cancelable: true })))
+            dialog.close();
+        return;
+    }
+}

package/dist/actions/actions.d.ts

@@ -1,39 +1,5 @@
 import { SettleReason } from '@reticlehq/core';
-interface ActionEffect {
-    dispatched: true;
-    targetMatched: boolean;
-    visible: boolean;
-    enabled: boolean;
-    defaultPrevented: boolean;
-    focusMoved: string | null;
-    valueChanged: boolean;
-    domMutatedWithin: number;
-    appeared?: string;
-    occluded: boolean;
-    occludedBy: string | null;
-    scrolledIntoView: boolean;
-    heldMs?: number;
-    alreadyAtValue?: true;
-}
-interface ActionResult {
-    ok: true;
-    ref: string;
-    action: string;
-    dispatched: boolean;
-    settled: boolean;
-    settleReason: SettleReason | null;
-    effect: ActionEffect;
-    testid?: string;
-    component?: string;
-    role?: string;
-    name?: string;
-    source?: {
-        file: string;
-        line: number;
-        column?: number;
-    };
-    warning?: string;
-}
+import { type ActionEffect, type ActionResult } from './action-report.js';
 export declare const ZOOM_NEEDS_REAL_BROWSER_MSG: string;
 export declare function executeAction(ref: string, action: string, args?: Record<string, unknown>): Promise<ActionResult>;
 export interface ActionStep {