@reticlehq/browser 3.8.0 → 3.8.1

package/dist/dom/a11y.js

@@ -1,15 +1,11 @@
 import { readTestId } from './addressing/testid-attr.js';
 import { DEFAULT_TESTID_ATTR, ElementState, REDACTED_VALUE, } from '@reticlehq/core';
-import { isButton, isHtmlElement, isImage, isInput, isMeter, isOutput, isProgress, isSelect, isTextArea, } from './realm.js';
+import { isButton, isImage, isInput, isMeter, isOutput, isProgress, isSelect, isTextArea, } from './realm.js';
 import { refs } from './addressing/refs.js';
-import { parentAcrossShadowBoundary } from './shadow-registry.js';
-import { clippingBox, overflowAxes, scrolledInto, } from './paint-context.js';
 import { inspectChart } from './chart.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { formatSource, sourceFromDom } from './addressing/source.js';
-const HTML_DETAILS_TAG = 'details';
-const HTML_DETAILS_OPEN_ATTRIBUTE = 'open';
-const HTML_SUMMARY_TAG = 'summary';
+import { HTML_DETAILS_OPEN_ATTRIBUTE, HTML_DETAILS_TAG, HTML_SUMMARY_TAG, isVisible, } from './visibility.js';
 const NAME_FROM_CONTENT = new Set([
     'button',
     'link',
@@ -364,294 +360,6 @@ export function getValue(el) {
     const valueNow = el.getAttribute('aria-valuenow');
     return valueNow ?? undefined;
 }
-function hiddenInsideClosedDetails(el) {
-    const parent = el.parentElement;
-    if (null === parent) {
-        return false;
-    }
-    const details = parent.closest(HTML_DETAILS_TAG);
-    if (null === details || details.hasAttribute(HTML_DETAILS_OPEN_ATTRIBUTE)) {
-        return false;
-    }
-    const summary = Array.from(details.children).find((child) => HTML_SUMMARY_TAG === child.localName);
-    return summary === undefined || !summary.contains(el);
-}
-function stalledFade(el) {
-    if (!el.ownerDocument.hidden || !('getAnimations' in el)) {
-        return false;
-    }
-    return el.getAnimations().some((a) => 'running' === a.playState || a.pending);
-}
-const OVERLAY_ARIA_HIDDEN = 'data-aria-hidden';
-function hiddenByAnOverlay(el) {
-    return el.hasAttribute(OVERLAY_ARIA_HIDDEN);
-}
-function selfCssHidden(el, style) {
-    if (isHtmlElement(el) && el.hidden) {
-        return true;
-    }
-    if (hiddenInsideClosedDetails(el)) {
-        return true;
-    }
-    if (style !== null) {
-        if ('none' === style.display ||
-            'hidden' === style.visibility ||
-            'collapse' === style.visibility) {
-            return true;
-        }
-        if (0 === Number.parseFloat(style.opacity || '1') && !stalledFade(el)) {
-            return true;
-        }
-    }
-    return false;
-}
-function selfHidden(el, style) {
-    if ('true' === el.getAttribute('aria-hidden') && !hiddenByAnOverlay(el)) {
-        return true;
-    }
-    return selfCssHidden(el, style);
-}
-export function isHiddenByAriaOnly(el) {
-    let foundAriaHidden = false;
-    let current = el;
-    while (null !== current) {
-        if ('true' === current.getAttribute('aria-hidden')) {
-            foundAriaHidden = true;
-        }
-        const style = current.ownerDocument.defaultView?.getComputedStyle(current) ?? null;
-        if (selfCssHidden(current, style)) {
-            return false;
-        }
-        current = parentAcrossShadowBoundary(current);
-    }
-    return foundAriaHidden;
-}
-export function isRenderedOutsideAriaHidden(el) {
-    let current = el;
-    while (null !== current) {
-        if ('true' === current.getAttribute('aria-hidden')) {
-            return false;
-        }
-        const style = current.ownerDocument.defaultView?.getComputedStyle(current) ?? null;
-        if (selfCssHidden(current, style)) {
-            return false;
-        }
-        current = parentAcrossShadowBoundary(current);
-    }
-    return true;
-}
-const CLIPPING_OVERFLOW = new Set(['hidden', 'clip']);
-const SCROLLING_OVERFLOW = new Set(['auto', 'scroll']);
-const NON_CLIPPING_DISPLAY = new Set([
-    'contents',
-    'table-row',
-    'table-row-group',
-    'table-header-group',
-    'table-footer-group',
-    'table-column',
-    'table-column-group',
-]);
-const TRANSFORM_CONTAINING_BLOCK_PROPERTIES = new Set([
-    'transform',
-    'translate',
-    'rotate',
-    'scale',
-    'perspective',
-]);
-const CONTAINING_BLOCK_PROPERTIES = new Set([
-    ...TRANSFORM_CONTAINING_BLOCK_PROPERTIES,
-    'filter',
-    'backdrop-filter',
-]);
-const CONTAINING_BLOCK_CONTAIN = new Set(['layout', 'paint', 'strict', 'content']);
-const REPLACED_INLINE_TAGS = new Set([
-    'img',
-    'video',
-    'audio',
-    'canvas',
-    'iframe',
-    'embed',
-    'object',
-    'input',
-    'textarea',
-    'select',
-]);
-const visibilityInfoMemos = new WeakMap();
-function visibilityInfoMemo(memo) {
-    if (memo === undefined) {
-        return new Map();
-    }
-    let info = visibilityInfoMemos.get(memo);
-    if (info === undefined) {
-        info = new Map();
-        visibilityInfoMemos.set(memo, info);
-    }
-    return info;
-}
-function ownVisibilityInfo(el, memo) {
-    let info = memo.get(el);
-    if (info === undefined) {
-        const style = el.ownerDocument.defaultView?.getComputedStyle(el) ?? null;
-        if (selfHidden(el, style)) {
-            info = {
-                hidden: true,
-                style,
-                parent: null,
-                clipX: false,
-                clipY: false,
-                scrollX: false,
-                scrollY: false,
-                hasClipping: false,
-            };
-            memo.set(el, info);
-            return info;
-        }
-        const parent = parentAcrossShadowBoundary(el);
-        const inherited = null === parent ? undefined : ownVisibilityInfo(parent, memo);
-        const [overflowX, overflowY] = overflowAxes(style);
-        const root = el.ownerDocument.documentElement;
-        const viewportOverflow = el === root ||
-            (el === el.ownerDocument.body &&
-                overflowAxes(ownVisibilityInfo(root, memo).style).every((axis) => 'visible' === axis));
-        const hasClipBox = !viewportOverflow &&
-            !NON_CLIPPING_DISPLAY.has(style?.display ?? '') &&
-            !(isHtmlElement(el) && 'inline' === style?.display);
-        const clipX = hasClipBox && CLIPPING_OVERFLOW.has(overflowX);
-        const clipY = hasClipBox && CLIPPING_OVERFLOW.has(overflowY);
-        info = {
-            hidden: true === inherited?.hidden,
-            style,
-            parent,
-            clipX,
-            clipY,
-            scrollX: hasClipBox && SCROLLING_OVERFLOW.has(overflowX),
-            scrollY: hasClipBox && SCROLLING_OVERFLOW.has(overflowY),
-            hasClipping: clipX || clipY || true === inherited?.hasClipping,
-        };
-        memo.set(el, info);
-    }
-    return info;
-}
-function positionedContainingBlock(el, fixed, memo) {
-    for (let parent = ownVisibilityInfo(el, memo).parent; parent !== null; parent = ownVisibilityInfo(parent, memo).parent) {
-        const style = ownVisibilityInfo(parent, memo).style;
-        if (null === style || 'contents' === style.display) {
-            continue;
-        }
-        if (!fixed && '' !== style.position && 'static' !== style.position) {
-            return parent;
-        }
-        const transformable = !('inline' === style.display &&
-            isHtmlElement(parent) &&
-            !REPLACED_INLINE_TAGS.has(parent.localName)) &&
-            'table-column' !== style.display &&
-            'table-column-group' !== style.display;
-        const applies = (property) => transformable || !TRANSFORM_CONTAINING_BLOCK_PROPERTIES.has(property);
-        if ([...CONTAINING_BLOCK_PROPERTIES].some((property) => {
-            const value = style.getPropertyValue(property);
-            return applies(property) && '' !== value && 'none' !== value;
-        }) ||
-            style.willChange
-                .split(',')
-                .some((property) => CONTAINING_BLOCK_PROPERTIES.has(property.trim()) && applies(property.trim())) ||
-            (transformable &&
-                !NON_CLIPPING_DISPLAY.has(style.display) &&
-                (style.contain.split(/\s+/).some((value) => CONTAINING_BLOCK_CONTAIN.has(value)) ||
-                    'auto' === style.contentVisibility))) {
-            return parent;
-        }
-    }
-    return null;
-}
-function visibleBounds(el, memo, initial, throughScrollers = false) {
-    let bounds = initial;
-    const target = ownVisibilityInfo(el, memo);
-    if (target.hidden) {
-        return null;
-    }
-    if (null === target.parent || !ownVisibilityInfo(target.parent, memo).hasClipping) {
-        return bounds;
-    }
-    let clipFrom;
-    for (let current = el; current !== null; current = ownVisibilityInfo(current, memo).parent) {
-        const info = ownVisibilityInfo(current, memo);
-        if (info.hidden) {
-            return null;
-        }
-        if (current === clipFrom) {
-            clipFrom = undefined;
-        }
-        const style = info.style;
-        if (throughScrollers &&
-            current !== el &&
-            undefined === clipFrom &&
-            (info.scrollX || info.scrollY)) {
-            bounds ??= el.getBoundingClientRect();
-            if (bounds.width > 0 && bounds.height > 0) {
-                bounds = scrolledInto(bounds, clippingBox(current, info), info.scrollX, info.scrollY);
-            }
-        }
-        if (current !== el && undefined === clipFrom && (info.clipX || info.clipY)) {
-            bounds ??= el.getBoundingClientRect();
-            if (bounds.width > 0 && bounds.height > 0) {
-                const clip = clippingBox(current, info);
-                const left = info.clipX ? Math.max(bounds.left, clip.left) : bounds.left;
-                const right = info.clipX ? Math.min(bounds.right, clip.right) : bounds.right;
-                const top = info.clipY ? Math.max(bounds.top, clip.top) : bounds.top;
-                const bottom = info.clipY ? Math.min(bounds.bottom, clip.bottom) : bounds.bottom;
-                if (right <= left || bottom <= top) {
-                    return null;
-                }
-                bounds = { left, right, top, bottom, width: right - left, height: bottom - top };
-            }
-        }
-        if (clipFrom === undefined && ('absolute' === style?.position || 'fixed' === style?.position)) {
-            clipFrom = positionedContainingBlock(current, 'fixed' === style?.position, memo);
-        }
-    }
-    return bounds;
-}
-export function isInViewport(el, memo) {
-    if (!isVisible(el, memo)) {
-        return false;
-    }
-    const view = el.ownerDocument.defaultView;
-    if (null === view) {
-        return false;
-    }
-    const r = visibleBounds(el, visibilityInfoMemo(memo), el.getBoundingClientRect());
-    if (null === r || undefined === r) {
-        return false;
-    }
-    if (r.width <= 0 || r.height <= 0) {
-        return false;
-    }
-    return r.bottom > 0 && r.right > 0 && r.top < view.innerHeight && r.left < view.innerWidth;
-}
-function collapsed(el, memo) {
-    const own = ownVisibilityInfo(el, memo);
-    if (!own.clipX && !own.clipY) {
-        return false;
-    }
-    const rects = Array.from(el.getClientRects());
-    return (rects.length > 0 &&
-        rects.every((r) => (own.clipX && 0 === r.width) || (own.clipY && 0 === r.height)));
-}
-export function isVisible(el, memo) {
-    if (!el.isConnected) {
-        return false;
-    }
-    const cached = memo?.get(el);
-    if (cached !== undefined) {
-        return cached;
-    }
-    const info = visibilityInfoMemo(memo);
-    const result = visibleBounds(el, info, undefined, true) !== null && !collapsed(el, info);
-    if (memo !== undefined) {
-        memo.set(el, result);
-    }
-    return result;
-}
 const MAX_TEXT = 80;
 function getVisibleText(el) {
     const text = collapse(el.textContent ?? '');

package/dist/dom/dom-ignore.js

@@ -1,5 +1,6 @@
 import { RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
 import { capturedRootOf } from './shadow-registry.js';
+import { isVisible } from './visibility.js';
 export const RETICLE_OVERLAY = RETICLE_OVERLAY_SELECTOR;
 const DEV_OVERLAYS = '[data-agentation],#__next-build-watcher,nextjs-portal,[data-nextjs-dialog],[data-nextjs-toast]';
 let extraIgnore = '';
@@ -23,8 +24,9 @@ export function isReticleOverlay(el) {
 }
 const HUD_DOCK = '[data-reticle-dock]';
 export function isUnobserved(el) {
-    if (!isReticleOverlay(el))
+    if (!isReticleOverlay(el)) {
         return false;
+    }
     return !exposed() || null === el.closest(HUD_DOCK);
 }
 export function isReticleUi(node) {
@@ -48,30 +50,38 @@ const NEXT_DIALOG = '[data-nextjs-dialog]';
 const VITE_OVERLAY = 'vite-error-overlay';
 function openFrameworkErrorDialog(doc) {
     const vite = doc.querySelector(VITE_OVERLAY);
-    if (vite !== null)
+    if (vite !== null) {
         return { name: FrameworkErrorDialog.VITE, host: vite };
+    }
     for (const portal of Array.from(doc.querySelectorAll(NEXT_PORTAL))) {
         const root = portal.shadowRoot ?? capturedRootOf(portal);
-        if (null !== (root ?? portal).querySelector(NEXT_DIALOG)) {
+        const dialog = (root ?? portal).querySelector(NEXT_DIALOG);
+        if (null !== dialog && isVisible(dialog)) {
             return { name: FrameworkErrorDialog.NEXT, host: portal };
         }
     }
     const light = doc.querySelector(NEXT_DIALOG);
-    return null === light ? undefined : { name: FrameworkErrorDialog.NEXT, host: light };
+    if (null === light || !isVisible(light)) {
+        return undefined;
+    }
+    return { name: FrameworkErrorDialog.NEXT, host: light };
 }
 export function dialogCovering(matches) {
     const first = matches[0];
-    if (first === undefined)
+    if (first === undefined) {
         return undefined;
+    }
     const dialog = openFrameworkErrorDialog(first.ownerDocument);
-    if (dialog === undefined)
+    if (dialog === undefined) {
         return undefined;
+    }
     return matches.some((el) => !isInsideHost(el, dialog.host)) ? dialog.name : undefined;
 }
 function isInsideHost(el, host) {
     for (let node = el; node !== null;) {
-        if (node === host)
+        if (node === host) {
             return true;
+        }
         const root = node.getRootNode();
         node = node.parentNode ?? (root instanceof ShadowRoot ? root.host : null);
     }
@@ -80,12 +90,15 @@ function isInsideHost(el, host) {
 const APP_MODAL = 'dialog[open], [aria-modal="true"]';
 export function appModalOpen(doc) {
     for (const el of Array.from(doc.querySelectorAll(APP_MODAL))) {
-        if (el.closest(RETICLE_OVERLAY) !== null)
+        if (el.closest(RETICLE_OVERLAY) !== null) {
             continue;
-        if (el instanceof HTMLElement && (el.hidden || null !== el.closest('[hidden]')))
+        }
+        if (el instanceof HTMLElement && (el.hidden || null !== el.closest('[hidden]'))) {
             continue;
-        if (el instanceof HTMLElement && 'none' === getComputedStyle(el).display)
+        }
+        if (el instanceof HTMLElement && 'none' === getComputedStyle(el).display) {
             continue;
+        }
         return true;
     }
     return false;

package/dist/dom/query-finders.d.ts

@@ -0,0 +1,6 @@
+import { type ElementQuery } from '@reticlehq/core';
+export declare function elementsUnder(container: HTMLElement): HTMLElement[];
+export declare function isNonRendered(el: Element): boolean;
+export declare function isHiddenNativeOption(el: HTMLElement): boolean;
+export declare function queryByRoleAndName(container: HTMLElement, role: string, name: string | undefined): HTMLElement[];
+export declare function findIn(container: HTMLElement, query: ElementQuery): HTMLElement[];

package/dist/dom/query-finders.js

@@ -0,0 +1,216 @@
+import { DATA_RETICLE_SOURCE_ATTR, QueryBy } from '@reticlehq/core';
+import { isInput, isSelect, isTextArea } from './realm.js';
+import { getAccessibleName, getRole } from './a11y.js';
+import { isVisible } from './visibility.js';
+import { identifyComponent } from '../registry/stores/adapters.js';
+import { readTestId, testIdSelector } from './addressing/testid-attr.js';
+import { exactVisibleText, fuzzyVisibleText, comparableText, paintedCase, textMatches, } from './text-match.js';
+const SOURCE_ATTR = DATA_RETICLE_SOURCE_ATTR;
+const MAX_COMPONENT_CANDIDATES = 2000;
+const componentCandidateSelector = () => `[${SOURCE_ATTR}], ${testIdSelector()}, button, a, input, select, textarea, [role]`;
+export function elementsUnder(container) {
+    const self = Node.ELEMENT_NODE === container.nodeType ? [container] : [];
+    return [...self, ...Array.from(container.querySelectorAll('*'))];
+}
+const NON_RENDERED_TAGS = ['script', 'style', 'template', 'noscript'];
+export function isNonRendered(el) {
+    return NON_RENDERED_TAGS.includes(el.tagName.toLowerCase());
+}
+function directText(el) {
+    if (isInput(el)) {
+        const type = el.type.toLowerCase();
+        if ('submit' === type || 'button' === type || 'reset' === type) {
+            return el.value;
+        }
+    }
+    if (isNonRendered(el)) {
+        return '';
+    }
+    return Array.from(el.childNodes)
+        .filter((node) => Node.TEXT_NODE === node.nodeType)
+        .map((node) => node.textContent ?? '')
+        .join('');
+}
+function semanticNameTarget(el) {
+    if (isInput(el) || isTextArea(el) || isSelect(el)) {
+        return true;
+    }
+    const tag = el.tagName.toLowerCase();
+    return ('button' === tag ||
+        'meter' === tag ||
+        'output' === tag ||
+        'progress' === tag ||
+        el.hasAttribute('aria-label') ||
+        el.hasAttribute('aria-labelledby'));
+}
+function findBySource(container, source) {
+    const prefix = `${source.file}:${source.line}:`.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    try {
+        return Array.from(container.querySelectorAll(`[${SOURCE_ATTR}^="${prefix}"]`));
+    }
+    catch {
+        return [];
+    }
+}
+function findByComponentName(container, component) {
+    const out = [];
+    let scanned = 0;
+    for (const el of Array.from(container.querySelectorAll(componentCandidateSelector()))) {
+        if (scanned >= MAX_COMPONENT_CANDIDATES) {
+            break;
+        }
+        scanned += 1;
+        const info = identifyComponent(el);
+        if (info !== null && info.componentStack[0] === component) {
+            out.push(el);
+        }
+    }
+    return out;
+}
+function findByComponent(container, query) {
+    if (query.source !== undefined) {
+        const bySource = findBySource(container, query.source);
+        if (bySource.length > 0) {
+            return bySource;
+        }
+    }
+    if (query.component !== undefined && query.component.length > 0) {
+        return findByComponentName(container, query.component);
+    }
+    return [];
+}
+function matchesRole(actual, queried) {
+    if (actual === queried) {
+        return true;
+    }
+    if ('textbox' === queried && 'searchbox' === actual) {
+        return true;
+    }
+    return false;
+}
+const OPTION_ROLE = 'option';
+const HTML_OPTION_TAG = 'option';
+const HTML_SELECT_TAG = 'select';
+const VISUALLY_HIDDEN_MAX_PX = 1;
+export function isHiddenNativeOption(el) {
+    if (HTML_OPTION_TAG !== el.localName) {
+        return false;
+    }
+    const select = el.closest(HTML_SELECT_TAG);
+    if (!isSelect(select)) {
+        return false;
+    }
+    if (!isVisible(select)) {
+        return true;
+    }
+    return isVisuallyHiddenBox(select);
+}
+function isVisuallyHiddenBox(select) {
+    const box = select.getBoundingClientRect();
+    return (box.width > 0 &&
+        box.height > 0 &&
+        box.width <= VISUALLY_HIDDEN_MAX_PX &&
+        box.height <= VISUALLY_HIDDEN_MAX_PX);
+}
+function preferVisibleActionableOption(role, matches) {
+    if (OPTION_ROLE !== role) {
+        return matches;
+    }
+    const kept = matches.filter((el) => !isHiddenNativeOption(el));
+    return kept.length === matches.length ? matches : kept;
+}
+export function queryByRoleAndName(container, role, name) {
+    const matched = elementsUnder(container).filter((el) => matchesRole(getRole(el), role) &&
+        (name === undefined || exactVisibleText(getAccessibleName(el), name)));
+    return preferVisibleActionableOption(role, matched);
+}
+function queryByText(container, value, query) {
+    return elementsUnder(container).filter((el) => {
+        const own = directText(el);
+        if (textMatches(own, query, value)) {
+            return true;
+        }
+        if (true !== query.matchCase || !fuzzyVisibleText(own, value)) {
+            return false;
+        }
+        const painted = paintedCase(el, own);
+        return painted !== undefined && textMatches(painted, query, value);
+    });
+}
+function queryByLabel(container, value) {
+    const expected = comparableText(value).toLowerCase();
+    const exact = [];
+    const fuzzy = [];
+    for (const el of elementsUnder(container)) {
+        if (!semanticNameTarget(el)) {
+            continue;
+        }
+        const name = comparableText(getAccessibleName(el)).toLowerCase();
+        if (!name.includes(expected)) {
+            continue;
+        }
+        (name === expected ? exact : fuzzy).push(el);
+    }
+    return exact.length > 0 ? exact : fuzzy;
+}
+function queryByPlaceholder(container, value) {
+    return elementsUnder(container).filter((el) => {
+        const placeholder = el.getAttribute('placeholder');
+        return placeholder !== null && fuzzyVisibleText(placeholder, value);
+    });
+}
+function queryByTestId(container, value) {
+    return elementsUnder(container).filter((el) => readTestId(el) === value);
+}
+function queryByAlt(container, value) {
+    return elementsUnder(container).filter((el) => {
+        const alt = el.getAttribute('alt');
+        return alt !== null && fuzzyVisibleText(alt, value);
+    });
+}
+export function findIn(container, query) {
+    const by = query.by;
+    const value = query.value;
+    if (by !== undefined && value !== undefined) {
+        switch (by) {
+            case QueryBy.ROLE:
+                return queryByRoleAndName(container, value, query.name);
+            case QueryBy.TEXT:
+                return queryByText(container, value, query);
+            case QueryBy.LABEL:
+                return queryByLabel(container, value);
+            case QueryBy.PLACEHOLDER:
+                return queryByPlaceholder(container, value);
+            case QueryBy.TESTID:
+                return queryByTestId(container, value);
+            case QueryBy.ALT:
+                return queryByAlt(container, value);
+            case QueryBy.COMPONENT:
+                return findByComponent(container, { ...query, component: query.component ?? value });
+            default:
+                throw new Error(`unsupported query strategy '${String(by)}' - use one of: ${Object.values(QueryBy).join(', ')}`);
+        }
+    }
+    if (query.component !== undefined || query.source !== undefined) {
+        return findByComponent(container, query);
+    }
+    if (query.role !== undefined) {
+        return queryByRoleAndName(container, query.role, query.name);
+    }
+    if (query.text !== undefined) {
+        return queryByText(container, query.text, query);
+    }
+    if (query.label !== undefined) {
+        return queryByLabel(container, query.label);
+    }
+    if (query.placeholder !== undefined) {
+        return queryByPlaceholder(container, query.placeholder);
+    }
+    if (query.testid !== undefined) {
+        return queryByTestId(container, query.testid);
+    }
+    if (query.alt !== undefined) {
+        return queryByAlt(container, query.alt);
+    }
+    return [];
+}

package/dist/dom/query.d.ts

@@ -1,5 +1,4 @@
 import { ElementState, type ElementQuery, type MatchResult, type QueryResult } from '@reticlehq/core';
-export declare function isHiddenNativeOption(el: HTMLElement): boolean;
 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 elementsMatching(query: ElementQuery): HTMLElement[];