@reticlehq/browser 3.8.0 → 3.8.1

package/dist/dom/query.js

@@ -1,50 +1,29 @@
-import { ALTERNATIVE_TESTID_ATTRS, DEFAULT_TESTID_ATTR, DATA_RETICLE_SOURCE_ATTR, ElementState, QueryBy, REDACTED_VALUE, TRANSPORT_LIMITS, } from '@reticlehq/core';
-import { isActionTarget, isElement, isFrame, isInput, isSelect, isTextArea } from './realm.js';
+import { ALTERNATIVE_TESTID_ATTRS, DEFAULT_TESTID_ATTR, ElementState, QueryBy, REDACTED_VALUE, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { isActionTarget, isElement, isFrame } from './realm.js';
 import { capturedRootOf } from './shadow-registry.js';
-import { getAccessibleName, getRole, describe, getStates, isHiddenByAriaOnly, isInViewport, isRenderedOutsideAriaHidden, isVisible, } from './a11y.js';
+import { getAccessibleName, getRole, describe, getStates } from './a11y.js';
+import { isHiddenByAriaOnly, isInViewport, isRenderedOutsideAriaHidden, isVisible, } from './visibility.js';
 import { dialogCovering, isIgnored, isReticleOverlay, isWordsIgnored } from './dom-ignore.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { declaredTestids } from '../registry/capabilities.js';
-import { identifyComponent } from '../registry/stores/adapters.js';
 import { refs } from './addressing/refs.js';
 import { getTestIdAttr, readTestId, testIdSelector } from './addressing/testid-attr.js';
 import { stableSelectorFor } from './stable-selector.js';
-import { exactVisibleText, fuzzyVisibleText, normaliseVisibleText, comparableText, foldTypography, paintedCase, textMatches, unreadableMatch, } from './text-match.js';
+import { fuzzyVisibleText, normaliseVisibleText, comparableText, foldTypography, textMatches, unreadableMatch, } from './text-match.js';
 import { pageRoute } from '../security/page-location.js';
-const SOURCE_ATTR = DATA_RETICLE_SOURCE_ATTR;
+import { elementsUnder, findIn, isNonRendered, queryByRoleAndName } from './query-finders.js';
 const MAX_PRESENT_TESTIDS = 12;
-const MAX_COMPONENT_CANDIDATES = 2000;
-const componentCandidateSelector = () => `[${SOURCE_ATTR}], ${testIdSelector()}, button, a, input, select, textarea, [role]`;
-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'];
-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 visibleTextOf(el, memo) {
-    if (isNonRendered(el) || isWordsIgnored(el))
+    if (isNonRendered(el) || isWordsIgnored(el)) {
         return '';
+    }
     const visible = isVisible(el, memo);
     const apart = laysOutApart(el);
     let text = '';
     for (const node of Array.from(el.childNodes)) {
-        if (Node.TEXT_NODE === node.nodeType && visible)
+        if (Node.TEXT_NODE === node.nodeType && visible) {
             text += node.textContent ?? '';
+        }
         else if (isElement(node)) {
             const own = visibleTextOf(node, memo);
             text += apart || ownBox(node) ? ` ${own} ` : own;
@@ -60,185 +39,24 @@ function ownBox(el) {
     const display = el.ownerDocument.defaultView?.getComputedStyle(el).display ?? 'inline';
     return !display.startsWith('inline') && 'contents' !== display;
 }
-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 resolveContainer(scope) {
-    if (scope === undefined)
+    if (scope === undefined) {
         return { container: document.body, scopeMissing: false };
+    }
     const byRef = refs.resolve(scope);
-    if (isActionTarget(byRef))
+    if (isActionTarget(byRef)) {
         return { container: byRef, scopeMissing: false };
+    }
     try {
         const found = document.querySelector(scope);
-        if (isActionTarget(found))
+        if (isActionTarget(found)) {
             return { container: found, scopeMissing: false };
+        }
     }
     catch {
     }
     return { container: null, scopeMissing: true };
 }
-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;
-}
-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);
-    });
-}
-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 [];
-}
 function readableFrameBody(frame) {
     try {
         return frame.contentDocument?.body ?? null;
@@ -258,13 +76,16 @@ function embeddedRootsUnder(root) {
                 walk(shadow, depth);
                 continue;
             }
-            if (depth >= FRAME_DEPTH_MAX)
+            if (depth >= FRAME_DEPTH_MAX) {
                 continue;
-            if (!isFrame(el))
+            }
+            if (!isFrame(el)) {
                 continue;
+            }
             const body = readableFrameBody(el);
-            if (null === body)
+            if (null === body) {
                 continue;
+            }
             found.push(body);
             walk(body, depth + 1);
         }
@@ -274,11 +95,13 @@ function embeddedRootsUnder(root) {
 }
 function findCandidates(query) {
     const { container, scopeMissing } = resolveContainer(query.scope);
-    if (null === container)
+    if (null === container) {
         return { candidates: [], scopeMissing: true };
+    }
     if (true === query.self) {
-        if (query.scope === undefined)
+        if (query.scope === undefined) {
             return { candidates: [], scopeMissing };
+        }
         if (query.text !== undefined &&
             !textMatches(visibleTextOf(container, new Map()), query, query.text)) {
             return { candidates: [], scopeMissing };
@@ -290,17 +113,20 @@ function findCandidates(query) {
     const ignored = wantedTextOf(query) === undefined ? isIgnored : isWordsIgnored;
     const collect = (els) => {
         for (const el of els) {
-            if (seen.has(el))
+            if (seen.has(el)) {
                 continue;
-            if (ignored(el))
+            }
+            if (ignored(el)) {
                 continue;
+            }
             seen.add(el);
             out.push(el);
         }
     };
     collect(findIn(container, query));
-    for (const embedded of embeddedRootsUnder(container))
+    for (const embedded of embeddedRootsUnder(container)) {
         collect(findIn(embedded, query));
+    }
     return { candidates: out, scopeMissing };
 }
 export const ATTR_VALUE_MAX = 512;
@@ -309,15 +135,17 @@ function projectAttrs(el, keys) {
     const out = {};
     for (const key of keys.slice(0, ATTR_KEYS_MAX)) {
         const raw = el.getAttribute(key);
-        if (null === raw)
+        if (null === raw) {
             continue;
+        }
         out[key] = isSensitiveKey(key) ? REDACTED_VALUE : raw.slice(0, ATTR_VALUE_MAX);
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
 function inState(el, state, memo) {
-    if (ElementState.IN_VIEWPORT === state)
+    if (ElementState.IN_VIEWPORT === state) {
         return isInViewport(el, memo);
+    }
     return getStates(el, isVisible(el, memo)).includes(state);
 }
 const MAX_DESCRIBED = TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS;
@@ -340,8 +168,9 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = tr
             !base.states.includes(ElementState.IN_VIEWPORT)) {
             base = { ...base, states: [...base.states, ElementState.IN_VIEWPORT] };
         }
-        if (attrs === undefined || 0 === attrs.length)
+        if (attrs === undefined || 0 === attrs.length) {
             return base;
+        }
         const projected = projectAttrs(el, attrs);
         return projected === undefined ? base : { ...base, attrs: projected };
     });
@@ -359,8 +188,9 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = tr
 }
 function resolveLabelledBy(el) {
     const ids = el.getAttribute('aria-labelledby');
-    if (null === ids)
+    if (null === ids) {
         return undefined;
+    }
     const text = ids
         .split(/\s+/)
         .map((id) => id.length > 0 ? (el.ownerDocument.getElementById(id)?.textContent?.trim() ?? '') : '')
@@ -392,8 +222,9 @@ function buildPresentRegions(query) {
     for (const role of CONTAINER_ROLES) {
         const containers = queryByRoleAndName(container, role, undefined);
         for (const el of containers) {
-            if (isReticleOverlay(el))
+            if (isReticleOverlay(el)) {
                 continue;
+            }
             const name = el.getAttribute('aria-label') ??
                 resolveLabelledBy(el) ??
                 readTestId(el) ??
@@ -401,8 +232,9 @@ function buildPresentRegions(query) {
             const children = el.querySelectorAll('[role]');
             const sample = [];
             for (const child of Array.from(children)) {
-                if (sample.length >= 3)
+                if (sample.length >= 3) {
                     break;
+                }
                 const childRole = child.getAttribute('role');
                 const childName = child.getAttribute('aria-label') ??
                     readTestId(child) ??
@@ -413,11 +245,13 @@ function buildPresentRegions(query) {
                 }
             }
             const region = { role, childCount: children.length, sample };
-            if (name !== undefined && name.length > 0)
+            if (name !== undefined && name.length > 0) {
                 region.name = name;
+            }
             regions.push(region);
-            if (regions.length >= 10)
+            if (regions.length >= 10) {
                 return regions;
+            }
         }
     }
     return regions;
@@ -427,13 +261,16 @@ function splitTextOwner(container, wanted, query) {
     let bestDepth = -1;
     const memo = new Map();
     for (const el of elementsUnder(container)) {
-        if (isIgnored(el))
+        if (isIgnored(el)) {
             continue;
-        if (!textMatches(visibleTextOf(el, memo), query, wanted))
+        }
+        if (!textMatches(visibleTextOf(el, memo), query, wanted)) {
             continue;
+        }
         let depth = 0;
-        for (let parent = el.parentElement; parent !== null; parent = parent.parentElement)
+        for (let parent = el.parentElement; parent !== null; parent = parent.parentElement) {
             depth++;
+        }
         if (depth > bestDepth) {
             best = el;
             bestDepth = depth;
@@ -443,16 +280,19 @@ function splitTextOwner(container, wanted, query) {
 }
 function caseOnlyMatch(container, wanted) {
     const target = comparableText(wanted).toLowerCase();
-    if (0 === target.length)
+    if (0 === target.length) {
         return undefined;
+    }
     const memo = new Map();
     for (const el of elementsUnder(container)) {
-        if (isIgnored(el))
+        if (isIgnored(el)) {
             continue;
+        }
         const text = normaliseVisibleText(visibleTextOf(el, memo));
         const at = foldTypography(text).toLowerCase().indexOf(target);
-        if (-1 !== at)
+        if (-1 !== at) {
             return text.slice(at, at + target.length);
+        }
     }
     return undefined;
 }
@@ -468,71 +308,88 @@ function textOnly(query) {
         Object.keys(query).every((key) => TEXT_ONLY_FIELDS.has(key)));
 }
 function wantedTextOf(query) {
-    if (query.text !== undefined)
+    if (query.text !== undefined) {
         return query.text;
+    }
     return QueryBy.TEXT === query.by ? query.value : undefined;
 }
 const MAX_NAME_NEAR_MISSES = 5;
 function nameNearMisses(container, query) {
     const role = QueryBy.ROLE === query.by ? query.value : query.role;
     const wanted = query.name;
-    if (role === undefined || wanted === undefined || 0 === wanted.length)
+    if (role === undefined || wanted === undefined || 0 === wanted.length) {
         return [];
+    }
     const target = comparableText(wanted).toLowerCase();
-    if (0 === target.length)
+    if (0 === target.length) {
         return [];
+    }
     const out = [];
     for (const el of elementsUnder(container)) {
-        if (isIgnored(el) || getRole(el) !== role)
+        if (isIgnored(el) || getRole(el) !== role) {
             continue;
+        }
         const name = normaliseVisibleText(getAccessibleName(el));
-        if (0 === name.length)
+        if (0 === name.length) {
             continue;
+        }
         const folded = foldTypography(name).toLowerCase();
-        if (!folded.includes(target) && !target.includes(folded))
+        if (!folded.includes(target) && !target.includes(folded)) {
             continue;
-        if (!out.includes(name))
+        }
+        if (!out.includes(name)) {
             out.push(name);
-        if (out.length >= MAX_NAME_NEAR_MISSES)
+        }
+        if (out.length >= MAX_NAME_NEAR_MISSES) {
             break;
+        }
     }
     return out;
 }
 function testidFoundUnder(container, query) {
-    if (QueryBy.TESTID !== query.by || undefined === query.value)
+    if (QueryBy.TESTID !== query.by || undefined === query.value) {
         return undefined;
+    }
     const configured = getTestIdAttr();
     for (const attr of [DEFAULT_TESTID_ATTR, ...ALTERNATIVE_TESTID_ATTRS]) {
-        if (attr === configured)
+        if (attr === configured) {
             continue;
+        }
         const found = elementsUnder(container).some((el) => el.getAttribute(attr) === query.value && !isIgnored(el));
-        if (found)
+        if (found) {
             return attr;
+        }
     }
     return undefined;
 }
 function textInAriaHidden(container, wanted) {
     let inAriaHidden = false;
     for (const el of elementsUnder(container)) {
-        if (isIgnored(el))
+        if (isIgnored(el)) {
             continue;
-        if (!isHiddenByAriaOnly(el))
+        }
+        if (!isHiddenByAriaOnly(el)) {
             continue;
+        }
         if (fuzzyVisibleText(el.textContent ?? '', wanted)) {
             inAriaHidden = true;
             break;
         }
     }
-    if (!inAriaHidden)
+    if (!inAriaHidden) {
         return false;
+    }
     const memo = new Map();
     for (const el of elementsUnder(container)) {
-        if (isIgnored(el))
+        if (isIgnored(el)) {
             continue;
-        if (!isRenderedOutsideAriaHidden(el))
+        }
+        if (!isRenderedOutsideAriaHidden(el)) {
             continue;
-        if (fuzzyVisibleText(visibleTextOf(el, memo), wanted))
+        }
+        if (fuzzyVisibleText(visibleTextOf(el, memo), wanted)) {
             return false;
+        }
     }
     return true;
 }
@@ -542,14 +399,17 @@ function buildEmptyHint(query, state, diagnose = true) {
     const present = [];
     const seen = new Set();
     for (const el of Array.from(all)) {
-        if (isIgnored(el))
+        if (isIgnored(el)) {
             continue;
+        }
         const id = readTestId(el);
-        if (null === id || 0 === id.length || seen.has(id))
+        if (null === id || 0 === id.length || seen.has(id)) {
             continue;
+        }
         seen.add(id);
-        if (present.length < MAX_PRESENT_TESTIDS)
+        if (present.length < MAX_PRESENT_TESTIDS) {
             present.push(id);
+        }
     }
     const registered = declaredTestids();
     const knownEmptyState = present.some((id) => registered.includes(id));
@@ -571,23 +431,27 @@ function buildEmptyHint(query, state, diagnose = true) {
         }
         else if (true === query.matchCase) {
             const shown = caseOnlyMatch(container, wanted);
-            if (shown !== undefined)
+            if (shown !== undefined) {
                 hint.caseMiss = shown;
+            }
         }
     }
     if (diagnose &&
         wanted !== undefined &&
         hint.splitText === undefined &&
         (state === undefined || ElementState.VISIBLE === state || ElementState.IN_VIEWPORT === state)) {
-        if (textInAriaHidden(container, wanted))
+        if (textInAriaHidden(container, wanted)) {
             hint.ariaHiddenMatch = true;
+        }
     }
     const near = nameNearMisses(container, query);
-    if (near.length > 0)
+    if (near.length > 0) {
         hint.nameNearMiss = near;
+    }
     const elsewhere = testidFoundUnder(container, query);
-    if (elsewhere !== undefined)
+    if (elsewhere !== undefined) {
         hint.testidFoundUnder = elsewhere;
+    }
     return hint;
 }
 export function elementsMatching(query) {

package/dist/dom/snapshot.js

@@ -1,7 +1,8 @@
 import { ElementState, SnapshotMode } from '@reticlehq/core';
 import { capturedRootOf } from './shadow-registry.js';
 import { isElement, isFrame } from './realm.js';
-import { getAccessibleName, getRole, getStates, getValue, isVisible } from './a11y.js';
+import { getAccessibleName, getRole, getStates, getValue } from './a11y.js';
+import { isVisible } from './visibility.js';
 import { refs } from './addressing/refs.js';
 import { readTestId } from './addressing/testid-attr.js';
 import { identifyComponent } from '../registry/stores/adapters.js';

package/dist/dom/visibility.d.ts

@@ -0,0 +1,7 @@
+export declare const HTML_DETAILS_TAG = "details";
+export declare const HTML_DETAILS_OPEN_ATTRIBUTE = "open";
+export declare const HTML_SUMMARY_TAG = "summary";
+export declare function isHiddenByAriaOnly(el: Element): boolean;
+export declare function isRenderedOutsideAriaHidden(el: Element): boolean;
+export declare function isInViewport(el: Element, memo?: Map<Element, boolean>): boolean;
+export declare function isVisible(el: Element, memo?: Map<Element, boolean>): boolean;