@reticlehq/browser 3.8.2 → 3.10.0

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

@@ -31,7 +31,12 @@ export interface ActionResult {
     effect: ActionEffect;
     testid?: string;
     testidOf?: number;
+    testidNth?: number;
     component?: string;
+    componentNth?: number;
+    componentOf?: number;
+    ownText?: string;
+    within?: string[];
     role?: string;
     name?: string;
     nth?: number;
@@ -48,17 +53,26 @@ export interface ActionResult {
 export interface CapturedAnchor {
     testid?: string;
     testidOf?: number;
+    testidNth?: number;
     component?: string;
     source?: {
         file: string;
         line: number;
         column?: number;
     };
+    componentNth?: number;
+    componentOf?: number;
+    ownText?: string;
     role?: string;
     name?: string;
     nth?: number;
     of?: number;
+    within?: string[];
     secret?: true;
 }
+export declare function positionAmongNamesakes(el: Element, role: string, name: string): {
+    nth: number;
+    of: number;
+} | null;
 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

@@ -1,36 +1,80 @@
 import { readTestId } from '../dom/addressing/testid-attr.js';
 import { QueryBy } from '@reticlehq/core';
 import { elementsMatching } from '../dom/query.js';
+import { ownWords } from '../dom/query-finders.js';
 import { getAccessibleName, getRole, isSensitiveField } from '../dom/a11y.js';
 import { identifyComponent } from '../registry/stores/adapters.js';
 import { isReticleUi } from '../dom/dom-ignore.js';
+import { isInViewport } from '../dom/visibility.js';
 const CANVAS_SELECTOR = 'canvas';
 export function visibleCanvases(doc) {
-    const width = doc.defaultView?.innerWidth ?? 0;
-    const height = doc.defaultView?.innerHeight ?? 0;
-    let count = 0;
-    for (const canvas of doc.querySelectorAll(CANVAS_SELECTOR)) {
-        if (isReticleUi(canvas)) {
-            continue;
-        }
-        const box = canvas.getBoundingClientRect();
-        const sized = box.width > 0 && box.height > 0;
-        const onScreen = box.bottom > 0 && box.right > 0 && box.top < height && box.left < width;
-        if (sized && onScreen) {
-            count += 1;
+    return Array.from(doc.querySelectorAll(CANVAS_SELECTOR)).filter((canvas) => !isReticleUi(canvas) && isInViewport(canvas)).length;
+}
+export function positionAmongNamesakes(el, role, name) {
+    const same = name.length > 0
+        ? elementsMatching({ by: QueryBy.ROLE, value: role, name })
+        : elementsMatching({ by: QueryBy.ROLE, value: role }).filter((candidate) => 0 === getAccessibleName(candidate).length);
+    const at = same.indexOf(el);
+    return 1 < same.length && 0 <= at ? { nth: at, of: same.length } : null;
+}
+function positionInComponentAnchor(el, component, source, role) {
+    if (component === undefined && source === undefined) {
+        return null;
+    }
+    const same = elementsMatching({
+        by: QueryBy.COMPONENT,
+        value: component ?? '',
+        ...(component === undefined ? {} : { component }),
+        ...(source === undefined ? {} : { source }),
+        ...(role.length > 0 ? { role } : {}),
+    });
+    const at = same.indexOf(el);
+    return 1 < same.length && 0 <= at ? { nth: at, of: same.length } : null;
+}
+const CONTAINER_ROLES = new Set([
+    'alert',
+    'alertdialog',
+    'dialog',
+    'form',
+    'region',
+    'navigation',
+    'menu',
+    'menubar',
+    'listbox',
+    'list',
+    'listitem',
+    'tabpanel',
+    'table',
+    'grid',
+    'row',
+    'group',
+    'toolbar',
+    'tree',
+    'search',
+]);
+const WITHIN_MAX = 2;
+function containerRoles(el) {
+    const out = [];
+    for (let a = el.parentElement; a !== null && out.length < WITHIN_MAX; a = a.parentElement) {
+        const role = getRole(a);
+        const landmarkNeedsName = 'form' === role || 'region' === role;
+        if (CONTAINER_ROLES.has(role) && (!landmarkNeedsName || getAccessibleName(a).length > 0)) {
+            out.push(role);
         }
     }
-    return count;
+    return out.length > 0 ? out : undefined;
 }
+const OWN_TEXT_MAX = 80;
 export function anchorOf(el) {
     const testid = readTestId(el) ?? undefined;
     const info = identifyComponent(el);
     const out = {};
     if (testid !== undefined) {
         out.testid = testid;
-        const shared = elementsMatching({ by: QueryBy.TESTID, value: testid }).length;
-        if (1 < shared) {
-            out.testidOf = shared;
+        const shared = elementsMatching({ by: QueryBy.TESTID, value: testid });
+        if (1 < shared.length) {
+            out.testidOf = shared.length;
+            out.testidNth = shared.findIndex((match) => match === el);
         }
     }
     const component = info?.componentStack[0];
@@ -42,21 +86,35 @@ export function anchorOf(el) {
     }
     const role = getRole(el);
     const name = getAccessibleName(el);
+    const position = positionInComponentAnchor(el, out.component, out.source, role);
+    if (position !== null) {
+        out.componentNth = position.nth;
+        out.componentOf = position.of;
+    }
     if (role.length > 0) {
         out.role = role;
     }
     if (name.length > 0) {
         out.name = name;
+        const within = containerRoles(el);
+        if (within !== undefined) {
+            out.within = within;
+        }
+    }
+    else if (out.component !== undefined || out.source !== undefined) {
+        const words = ownWords(el);
+        if (0 < words.length && words.length <= OWN_TEXT_MAX) {
+            out.ownText = words;
+        }
     }
     if (isSensitiveField(el)) {
         out.secret = true;
     }
-    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;
+    if (role.length > 0) {
+        const position = positionAmongNamesakes(el, role, name);
+        if (position !== null) {
+            out.nth = position.nth;
+            out.of = position.of;
         }
     }
     return out;
@@ -77,12 +135,27 @@ export const result = (ref, action, effect, settled, settleReason, anchor, warni
     if (anchor.testidOf !== undefined) {
         base.testidOf = anchor.testidOf;
     }
+    if (anchor.testidNth !== undefined) {
+        base.testidNth = anchor.testidNth;
+    }
     if (anchor.component !== undefined) {
         base.component = anchor.component;
     }
     if (anchor.source !== undefined) {
         base.source = anchor.source;
     }
+    if (anchor.componentNth !== undefined) {
+        base.componentNth = anchor.componentNth;
+    }
+    if (anchor.componentOf !== undefined) {
+        base.componentOf = anchor.componentOf;
+    }
+    if (anchor.ownText !== undefined) {
+        base.ownText = anchor.ownText;
+    }
+    if (anchor.within !== undefined) {
+        base.within = anchor.within;
+    }
     if (anchor.role !== undefined) {
         base.role = anchor.role;
     }

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

@@ -1,5 +1,5 @@
 import type { ActionTarget } from '../dom/realm.js';
-import { ClickButton } from '@reticlehq/core';
+import { ClickButton, type BoxFraction } from '@reticlehq/core';
 import { type ModifierFlags } from './actions-press.js';
 interface ClickGeometry {
     occluded: boolean;
@@ -21,20 +21,31 @@ export declare function fireClickSequence(el: ActionTarget, hold?: {
     ms: number;
     sleep: (ms: number) => Promise<void>;
     now: () => number;
-}, detail?: number, input?: ClickInput): Promise<{
+}, detail?: number, input?: ClickInput, point?: BoxFraction): 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;
-export declare function firePointerNonBubbling(el: Element, type: string, relatedTarget?: EventTarget | null): void;
-export declare function dragElement(source: ActionTarget, target: ActionTarget | null, data: unknown): Promise<boolean>;
+export declare function firePointer(el: Element, type: string, relatedTarget?: EventTarget | null, coords?: MouseEventInit): void;
+export declare function leavePreviousHover(next: Element): EventTarget;
+export declare function firePointerNonBubbling(el: Element, type: string, relatedTarget?: EventTarget | null, coords?: MouseEventInit): void;
+interface Point {
+    x: number;
+    y: number;
+}
+export declare function coordsAt(p: Point): MouseEventInit;
+export declare function coordsIn(el: ActionTarget, at: BoxFraction | undefined): MouseEventInit;
+export declare function dragElement(source: ActionTarget, target: ActionTarget | null, data: unknown, points?: {
+    at?: BoxFraction | undefined;
+    to?: BoxFraction | undefined;
+}, input?: ClickInput): Promise<boolean>;
 export declare function fireTapSequence(el: ActionTarget, hold: {
     ms: number;
     sleep: (ms: number) => Promise<void>;
     now: () => number;
-} | undefined): Promise<{
+} | undefined, point?: BoxFraction): Promise<{
     prevented: boolean;
     heldMs: number;
 }>;

package/dist/actions/actions-dom.js

@@ -4,7 +4,7 @@ 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 { ClickButton, clickButtonFromArgs, pointInBox } from '@reticlehq/core';
 import { pressModifiers } from './actions-press.js';
 export const NO_GEOMETRY = {
     occluded: false,
@@ -55,10 +55,10 @@ function fireAt(el, type, at, buttons, related, detail = 0, input = PLAIN_CLICK)
         ? pointerEventFor(el, type, { ...init, pointerId: 1, isPrimary: true })
         : mouseEventFor(el, type, init));
 }
-export async function fireClickSequence(el, hold, detail, input = PLAIN_CLICK) {
+export async function fireClickSequence(el, hold, detail, input = PLAIN_CLICK, point) {
     const doc = el.ownerDocument;
     const from = doc.activeElement ?? doc.body;
-    const at = centreOf(el);
+    const at = pointOf(el, point);
     const d = detail ?? 0;
     const held = BUTTON_CODES[input.button].bit;
     const isLeft = ClickButton.LEFT === input.button;
@@ -88,6 +88,9 @@ export async function fireClickSequence(el, hold, detail, input = PLAIN_CLICK) {
 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) {
@@ -116,30 +119,70 @@ function hasNoSize(el) {
         return false;
     }
     const rects = Array.from(el.getClientRects());
-    return rects.length > 0 && rects.every((r) => 0 === r.width || 0 === r.height);
+    if (0 === rects.length) {
+        return isMeasurable(el.ownerDocument.documentElement.getBoundingClientRect());
+    }
+    return rects.every((r) => 0 === r.width || 0 === r.height);
+}
+function sizedLabelOf(el) {
+    const labels = 'labels' in el ? el.labels : null;
+    for (const label of labels ?? []) {
+        const box = label.getBoundingClientRect();
+        if (0 < box.width && 0 < box.height) {
+            return label;
+        }
+    }
+    return null;
 }
 export function clickGeometry(el) {
     if (typeof el.getBoundingClientRect !== 'function') {
         return NO_GEOMETRY;
     }
     let rect = el.getBoundingClientRect();
+    const sizeless = isMeasurable(rect) ? 0 === rect.width || 0 === rect.height : hasNoSize(el);
+    if (sizeless) {
+        const label = sizedLabelOf(el);
+        if (label !== null) {
+            return clickGeometry(label);
+        }
+        return { ...NO_GEOMETRY, noSize: true };
+    }
     if (!isMeasurable(rect)) {
-        return hasNoSize(el) ? { ...NO_GEOMETRY, noSize: true } : NO_GEOMETRY;
+        return 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();
     }
     const stillOff = scrolledIntoView && isOffViewport(el, rect);
     return { ...hitTest(el, rect), scrolledIntoView, ...(stillOff ? { offViewport: true } : {}) };
 }
-export function firePointer(el, type, relatedTarget = null) {
-    asSyntheticInput(() => el.dispatchEvent(pointerEventFor(el, type, { bubbles: true, cancelable: true, relatedTarget })));
+export function firePointer(el, type, relatedTarget = null, coords = {}) {
+    asSyntheticInput(() => el.dispatchEvent(pointerEventFor(el, type, { bubbles: true, cancelable: true, relatedTarget, ...coords })));
 }
-export function firePointerNonBubbling(el, type, relatedTarget = null) {
-    asSyntheticInput(() => el.dispatchEvent(pointerEventFor(el, type, { bubbles: false, cancelable: true, relatedTarget })));
+const hoveredIn = new WeakMap();
+export function leavePreviousHover(next) {
+    const doc = next.ownerDocument;
+    const prev = hoveredIn.get(doc);
+    hoveredIn.set(doc, next);
+    if (prev === undefined || !prev.isConnected) {
+        return doc.activeElement ?? doc.body;
+    }
+    if (prev === next) {
+        return prev;
+    }
+    firePointer(prev, 'pointerout', next);
+    prev.dispatchEvent(mouseEventFor(prev, 'mouseout', { bubbles: true, relatedTarget: next }));
+    for (let el = prev; el !== null && !el.contains(next); el = el.parentElement) {
+        firePointerNonBubbling(el, 'pointerleave', next);
+        el.dispatchEvent(mouseEventFor(el, 'mouseleave', { relatedTarget: next }));
+    }
+    return prev;
+}
+export function firePointerNonBubbling(el, type, relatedTarget = null, coords = {}) {
+    asSyntheticInput(() => el.dispatchEvent(pointerEventFor(el, type, { bubbles: false, cancelable: true, relatedTarget, ...coords })));
 }
 function makeDataTransfer(data) {
     if (typeof DataTransfer !== 'function') {
@@ -162,18 +205,31 @@ function centreOf(el) {
     const box = el.getBoundingClientRect();
     return { x: box.left + box.width / 2, y: box.top + box.height / 2 };
 }
+function pointOf(el, at) {
+    if (at === undefined) {
+        return centreOf(el);
+    }
+    const box = el.getBoundingClientRect();
+    return pointInBox({ x: box.left, y: box.top, width: box.width, height: box.height }, at);
+}
+export function coordsAt(p) {
+    return { clientX: p.x, clientY: p.y, screenX: p.x, screenY: p.y };
+}
+export function coordsIn(el, at) {
+    return at === undefined ? {} : coordsAt(pointOf(el, at));
+}
 function lerp(a, b, t) {
     return { x: Math.round(a.x + (b.x - a.x) * t), y: Math.round(a.y + (b.y - a.y) * t) };
 }
-export async function dragElement(source, target, data) {
+export async function dragElement(source, target, data, points = {}, input = PLAIN_CLICK) {
     const dest = target ?? source;
-    const from = centreOf(source);
-    const to = centreOf(dest);
+    const from = pointOf(source, points.at);
+    const to = pointOf(dest, points.to);
     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;
-    fireAt(source, 'pointerdown', from, BUTTON_HELD);
-    fireAt(source, 'mousedown', from, BUTTON_HELD);
+    fireAt(source, 'pointerdown', from, BUTTON_HELD, undefined, 0, input);
+    fireAt(source, 'mousedown', from, BUTTON_HELD, undefined, 0, input);
     await nativeFrame();
     let leftSource = false;
     let enteredDest = false;
@@ -181,30 +237,30 @@ export async function dragElement(source, target, data) {
         const at = lerp(from, to, step / DRAG_STEPS);
         if (!leftSource && !crosses(sourceRect, at)) {
             leftSource = true;
-            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);
+            fireAt(source, 'pointerout', at, BUTTON_HELD, dest, 0, input);
+            fireAt(source, 'mouseout', at, BUTTON_HELD, dest, 0, input);
+            fireAt(source, 'pointerleave', at, BUTTON_HELD, dest, 0, input);
+            fireAt(source, 'mouseleave', at, BUTTON_HELD, dest, 0, input);
         }
         if (leftSource && !enteredDest && destRect !== null && crosses(destRect, at)) {
             enteredDest = true;
-            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);
+            fireAt(dest, 'pointerover', at, BUTTON_HELD, source, 0, input);
+            fireAt(dest, 'mouseover', at, BUTTON_HELD, source, 0, input);
+            fireAt(dest, 'pointerenter', at, BUTTON_HELD, source, 0, input);
+            fireAt(dest, 'mouseenter', at, BUTTON_HELD, source, 0, input);
         }
-        fireAt(dest, 'pointermove', at, BUTTON_HELD);
-        fireAt(dest, 'mousemove', at, BUTTON_HELD);
+        fireAt(dest, 'pointermove', at, BUTTON_HELD, undefined, 0, input);
+        fireAt(dest, 'mousemove', at, BUTTON_HELD, undefined, 0, input);
         await nativeFrame();
     }
     if (!enteredDest && destRect !== null) {
-        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);
+        fireAt(dest, 'pointerover', to, BUTTON_HELD, source, 0, input);
+        fireAt(dest, 'mouseover', to, BUTTON_HELD, source, 0, input);
+        fireAt(dest, 'pointerenter', to, BUTTON_HELD, source, 0, input);
+        fireAt(dest, 'mouseenter', to, BUTTON_HELD, source, 0, input);
     }
-    fireAt(dest, 'pointerup', to, BUTTON_RELEASED);
-    fireAt(dest, 'mouseup', to, BUTTON_RELEASED);
+    fireAt(dest, 'pointerup', to, BUTTON_RELEASED, undefined, 0, input);
+    fireAt(dest, 'mouseup', to, BUTTON_RELEASED, undefined, 0, input);
     let dropPrevented = false;
     if ('function' === typeof DragEvent) {
         const dataTransfer = makeDataTransfer(data);
@@ -222,9 +278,10 @@ export async function dragElement(source, target, data) {
     }
     return dropPrevented;
 }
-export async function fireTapSequence(el, hold) {
-    const touches = touchListFor(el);
-    firePointerTouch(el, 'pointerdown');
+export async function fireTapSequence(el, hold, point) {
+    const touches = touchListFor(el, point);
+    const coords = coordsIn(el, point);
+    firePointerTouch(el, 'pointerdown', coords);
     asSyntheticInput(() => el.dispatchEvent(makeTouchEvent('touchstart', touches)));
     if (el.tabIndex >= 0 && 'function' === typeof el.focus) {
         el.focus();
@@ -236,11 +293,11 @@ export async function fireTapSequence(el, hold) {
         heldMs = hold.now() - started;
     }
     asSyntheticInput(() => el.dispatchEvent(makeTouchEvent('touchend', [])));
-    firePointerTouch(el, 'pointerup');
-    const clicked = asSyntheticInput(() => el.dispatchEvent(mouseEventFor(el, 'click', { bubbles: true, cancelable: true })));
+    firePointerTouch(el, 'pointerup', coords);
+    const clicked = asSyntheticInput(() => el.dispatchEvent(mouseEventFor(el, 'click', { bubbles: true, cancelable: true, ...coords })));
     return { prevented: !clicked, heldMs };
 }
-function firePointerTouch(el, type) {
+function firePointerTouch(el, type, coords) {
     asSyntheticInput(() => el.dispatchEvent(pointerEventFor(el, type, {
         bubbles: true,
         cancelable: true,
@@ -248,22 +305,16 @@ function firePointerTouch(el, type) {
         isPrimary: true,
         width: 23,
         height: 23,
+        ...coords,
     })));
 }
-function touchListFor(el) {
+function touchListFor(el, point) {
     if ('function' !== typeof Touch || 'function' !== typeof el.getBoundingClientRect) {
         return [];
     }
-    const rect = el.getBoundingClientRect();
+    const at = pointOf(el, point);
     try {
-        return [
-            new Touch({
-                identifier: 0,
-                target: el,
-                clientX: rect.left + rect.width / 2,
-                clientY: rect.top + rect.height / 2,
-            }),
-        ];
+        return [new Touch({ identifier: 0, target: el, clientX: at.x, clientY: at.y })];
     }
     catch {
         return [];

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

@@ -19,3 +19,13 @@ export declare function keyboardEvent(type: string, init: KeyboardEventInit & {
 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;
+export declare const SPACE_KEY = " ";
+interface Held {
+    metaKey: boolean;
+    ctrlKey: boolean;
+    altKey: boolean;
+    shiftKey: boolean;
+}
+export declare function runKeydownDefault(el: Element, key: string, held: Held): void;
+export declare function runKeyupDefault(el: Element, key: string, held: Held): void;
+export {};