@reticlehq/browser 3.7.0 → 3.8.1

package/dist/dom/snapshot.js

@@ -1,10 +1,15 @@
 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';
+import { auditLayout } from './layout-audit.js';
+import { pageRoute } from '../security/page-location.js';
 import { isIgnored, isReticleOverlay } from './dom-ignore.js';
-const INTERACTIVE = new Set([
+export const INTERACTIVE = new Set([
     'button',
     'link',
     'textbox',
@@ -23,8 +28,9 @@ const INTERACTIVE = new Set([
 const SKIP_TAGS = new Set(['script', 'style', 'noscript', 'template', 'head', 'meta', 'link']);
 const ANNOUNCE_ROLES = new Set(['alert', 'status']);
 function announces(el, role) {
-    if (ANNOUNCE_ROLES.has(role))
+    if (ANNOUNCE_ROLES.has(role)) {
         return true;
+    }
     const live = el.getAttribute('aria-live');
     return live !== null && 'off' !== live;
 }
@@ -56,30 +62,36 @@ function readingParts(el) {
 function isInlineIn(el) {
     const view = el.ownerDocument.defaultView;
     const parent = el.parentElement;
-    if (null === view || null === parent)
+    if (null === view || null === parent) {
         return false;
+    }
     const around = view.getComputedStyle(parent).display;
-    if (around.includes('flex') || around.includes('grid'))
+    if (around.includes('flex') || around.includes('grid')) {
         return false;
+    }
     return 'inline' === view.getComputedStyle(el).display;
 }
 function foldsIntoParent(el) {
-    if (skipEarly(el) || !isInlineIn(el))
+    if (skipEarly(el) || !isInlineIn(el)) {
         return false;
+    }
     const role = getRole(el);
     return !INTERACTIVE.has(role) && !announces(el, role) && 0 === getAccessibleName(el).length;
 }
 export const MAX_UNREAD_BRANCHES = 50;
 function hiddenByMarkup(el) {
-    if ('true' === el.getAttribute('aria-hidden'))
+    if ('true' === el.getAttribute('aria-hidden')) {
         return true;
+    }
     return el instanceof HTMLElement && el.hidden;
 }
 function skipEarly(el) {
-    if (SKIP_TAGS.has(el.tagName.toLowerCase()))
+    if (SKIP_TAGS.has(el.tagName.toLowerCase())) {
         return true;
-    if (isIgnored(el))
+    }
+    if (isIgnored(el)) {
         return true;
+    }
     return hiddenByMarkup(el);
 }
 function stateSuffix(el) {
@@ -90,7 +102,7 @@ function stateSuffix(el) {
         s === ElementState.FOCUSED);
     return states.length > 0 ? ` [${states.join(',')}]` : '';
 }
-function formatLine(el, depth, role, name, layout, ownText = '') {
+function formatLine(el, depth, role, name, layout, ownText = '', withTestId = false) {
     const indent = '  '.repeat(depth);
     const value = getValue(el);
     const label = name;
@@ -99,14 +111,27 @@ function formatLine(el, depth, role, name, layout, ownText = '') {
     const valuePart = value !== undefined && value.length > 0 ? ` [value="${value}"]` : '';
     const layoutPart = layout.length > 0 ? ` [${layout}]` : '';
     const textPart = ownText.length > 0 ? ` [text="${ownText}"]` : '';
-    return `${indent}- ${role}${namePart}${refPart}${valuePart}${textPart}${layoutPart}${stateSuffix(el)}`;
+    const testid = withTestId ? readTestId(el) : null;
+    const info = withTestId ? identifyComponent(el) : null;
+    const component = null === testid ? info?.componentStack[0] : undefined;
+    const where = info?.source;
+    let who = '';
+    if (null !== testid) {
+        who = ` [testid=${testid}]`;
+    }
+    else if (component !== undefined) {
+        who = ` [component=${component}]`;
+    }
+    const idPart = `${who}${where === undefined ? '' : ` [src=${where.file}:${String(where.line)}]`}`;
+    return `${indent}- ${role}${namePart}${refPart}${valuePart}${textPart}${layoutPart}${stateSuffix(el)}${idPart}`;
 }
 function formatTextLine(depth, text) {
     return `${'  '.repeat(depth)}- text "${text}"`;
 }
 function layoutSignature(style) {
-    if (null === style)
+    if (null === style) {
         return '';
+    }
     const display = style.display;
     if ('grid' === display || 'inline-grid' === display) {
         const cols = style.gridTemplateColumns;
@@ -127,13 +152,15 @@ function recordUnread(branches, ctx) {
 function pierceChildren(parent) {
     const out = [...parent.children];
     const shadow = parent.shadowRoot ?? capturedRootOf(parent);
-    if (shadow !== null)
+    if (shadow !== null) {
         out.push(...shadow.children);
+    }
     if (isFrame(parent)) {
         try {
             const body = parent.contentDocument?.body;
-            if (body !== null && body !== undefined)
+            if (body !== null && body !== undefined) {
                 out.push(...body.children);
+            }
         }
         catch {
         }
@@ -146,8 +173,9 @@ function visit(child, depth, ctx, inLive) {
         !isIgnored(child) &&
         !(child instanceof HTMLElement && child.hidden);
     if (!stampedOnly && skipEarly(child)) {
-        if (hiddenByMarkup(child))
+        if (hiddenByMarkup(child)) {
             ctx.hiddenSkipped += 1;
+        }
         return;
     }
     const view = child.ownerDocument.defaultView;
@@ -170,13 +198,14 @@ function visit(child, depth, ctx, inLive) {
     const actionable = interactive;
     const meaningful = actionable || role !== 'generic' || name.length > 0 || text.length > 0 || layout.length > 0;
     const include = lean ? actionable : meaningful;
-    if (lean && !include && meaningful)
+    if (lean && !include && meaningful) {
         ctx.leanSkipped += 1;
+    }
     if (include) {
         ctx.nodes += 1;
         ctx.lines.push('generic' === role && text.length > 0 && 0 === layout.length
             ? formatTextLine(depth, text)
-            : formatLine(child, depth, role, name, layout, text));
+            : formatLine(child, depth, role, name, layout, text, true === ctx.ids));
         walk(child, depth + 1, ctx, announce);
     }
     else {
@@ -199,31 +228,36 @@ function walk(parent, depth, ctx, inLive = false) {
             return;
         }
         const child = children[index];
-        if (child !== undefined)
+        if (child !== undefined) {
             visit(child, depth, ctx, inLive);
+        }
     }
 }
 function collectDialogs(root) {
     const nodes = root.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]');
     const names = [];
     for (const node of nodes) {
-        if (isReticleOverlay(node))
+        if (isReticleOverlay(node)) {
             continue;
-        if (isVisible(node))
+        }
+        if (isVisible(node)) {
             names.push(getAccessibleName(node) || '(unnamed dialog)');
+        }
     }
     return names;
 }
 const MODAL_SELECTOR = '[role="dialog"], [role="alertdialog"], dialog[open], [aria-modal="true"]';
 function overlayHidingPage(root) {
-    if (root !== document.body)
+    if (root !== document.body) {
         return undefined;
+    }
     const dialogs = document.body.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]');
     let modal;
     let hiddenCandidate;
     for (const d of dialogs) {
-        if (isReticleOverlay(d))
+        if (isReticleOverlay(d)) {
             continue;
+        }
         if (isVisible(d)) {
             modal = d;
             break;
@@ -231,14 +265,17 @@ function overlayHidingPage(root) {
         hiddenCandidate ??= d;
     }
     modal ??= hiddenCandidate;
-    if (modal === undefined)
+    if (modal === undefined) {
         return undefined;
+    }
     const modalEl = modal;
     const outside = Array.from(document.body.children).filter((c) => !c.contains(modalEl));
-    if (0 === outside.length)
+    if (0 === outside.length) {
         return undefined;
-    if (!outside.every((c) => 'true' === c.getAttribute('aria-hidden')))
+    }
+    if (!outside.every((c) => 'true' === c.getAttribute('aria-hidden'))) {
         return undefined;
+    }
     return ('the rest of the page is aria-hidden behind an open overlay (a focus-trap modal), so this ' +
         'snapshot shows only the overlay. If it will not close its cleanup may be stuck on a throttled ' +
         'tab: dismiss the overlay, or snapshot with { scope } inside it.');
@@ -247,7 +284,7 @@ function buildStatus(root) {
     const visibleDialogs = collectDialogs(root);
     const overlay = overlayHidingPage(root);
     return {
-        route: `${location.pathname}${location.search}${location.hash}`,
+        route: pageRoute(),
         title: document.title,
         ...(visibleDialogs.length > 0 ? { visibleDialogs } : {}),
         ...(overlay !== undefined ? { overlayHidingPage: overlay } : {}),
@@ -255,11 +292,20 @@ function buildStatus(root) {
 }
 export function buildSnapshot(options = {}) {
     const mode = options.mode ?? SnapshotMode.FULL;
-    const scopeEl = options.scope !== undefined
-        ? (refs.resolve(options.scope) ?? document.querySelector(options.scope))
-        : document.body;
-    const scopeMissing = options.scope !== undefined && !(scopeEl instanceof Element);
-    const root = scopeEl instanceof Element ? scopeEl : document.body;
+    const scope = options.scope?.trim();
+    let scopeEl = document.body;
+    if (undefined !== scope && '' !== scope) {
+        scopeEl = refs.resolve(scope);
+        if (null === scopeEl) {
+            try {
+                scopeEl = document.querySelector(scope);
+            }
+            catch {
+            }
+        }
+    }
+    const scopeMissing = null === scopeEl;
+    const root = scopeEl ?? document.body;
     const status = buildStatus(root);
     if (scopeMissing) {
         return { tree: '', status, nodes: 0, truncated: false, scopeMissing: true };
@@ -278,16 +324,21 @@ export function buildSnapshot(options = {}) {
         maxDepth: options.maxDepth ?? 20,
         unread: [],
         unreadOverflow: false,
+        ...(true === options.ids ? { ids: true } : {}),
     };
-    if (true === options.includeRoot)
+    if (true === options.includeRoot) {
         visit(root, 0, ctx, false);
-    else
+    }
+    else {
         walk(root, 0, ctx);
+    }
     if (0 === ctx.nodes && root === document.body) {
         ctx.throughOverlay = true;
-        for (const child of Array.from(root.children))
-            if (overlayStamped(child) && null !== child.querySelector(MODAL_SELECTOR))
+        for (const child of Array.from(root.children)) {
+            if (overlayStamped(child) && null !== child.querySelector(MODAL_SELECTOR)) {
                 visit(child, 0, ctx, false);
+            }
+        }
         ctx.throughOverlay = false;
     }
     return {
@@ -300,5 +351,6 @@ export function buildSnapshot(options = {}) {
         ...(ctx.hiddenSkipped > 0 ? { hiddenSkipped: ctx.hiddenSkipped } : {}),
         ...(ctx.unread.length > 0 ? { unread: ctx.unread } : {}),
         ...(ctx.unreadOverflow ? { unreadOverflow: true } : {}),
+        ...(true === options.audit ? { audit: auditLayout(root) } : {}),
     };
 }

package/dist/dom/stable-selector.d.ts

@@ -0,0 +1 @@
+export declare function stableSelectorFor(el: HTMLElement): string | undefined;

package/dist/dom/stable-selector.js

@@ -0,0 +1,19 @@
+import { getTestIdAttr, readTestId } from './addressing/testid-attr.js';
+export function stableSelectorFor(el) {
+    const candidate = candidateSelectorFor(el);
+    if (undefined === candidate)
+        return undefined;
+    const matches = el.ownerDocument.querySelectorAll(candidate);
+    return 1 === matches.length && matches[0] === el ? candidate : undefined;
+}
+function candidateSelectorFor(el) {
+    const testid = readTestId(el);
+    if (null !== testid && 0 < testid.length) {
+        const escaped = testid.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        return `[${getTestIdAttr()}="${escaped}"]`;
+    }
+    const id = el.getAttribute('id');
+    if (null !== id && /^[A-Za-z_][A-Za-z0-9_-]*$/.test(id))
+        return `#${id}`;
+    return undefined;
+}

package/dist/dom/text-match.d.ts

@@ -0,0 +1,12 @@
+import type { ElementQuery } from '@reticlehq/core';
+export declare function normaliseVisibleText(value: string): string;
+export declare function foldTypography(value: string): string;
+export declare function comparableText(value: string): string;
+export declare function fuzzyVisibleText(actual: string, expected: string): boolean;
+export declare function textMatches(actual: string, query: ElementQuery, expected: string): boolean;
+export declare function exactVisibleText(actual: string, expected: string): boolean;
+export declare function paintedCase(el: Element, text: string): string | undefined;
+export declare const UNREADABLE_CONTRAST = 1.5;
+export declare const UNREADABLE_OPACITY = 0.05;
+export declare function unreadableText(el: Element): string | undefined;
+export declare function unreadableMatch(matches: readonly Element[]): string | undefined;

package/dist/dom/text-match.js

@@ -0,0 +1,115 @@
+import { parentAcrossShadowBoundary } from './shadow-registry.js';
+export function normaliseVisibleText(value) {
+    return value.replace(/\s+/g, ' ').trim().normalize('NFC');
+}
+const SINGLE_QUOTES = /[\u2018\u2019]/g;
+const DOUBLE_QUOTES = /[\u201c\u201d]/g;
+const DASHES = /[\u2013\u2014]/g;
+export function foldTypography(value) {
+    return value.replace(SINGLE_QUOTES, "'").replace(DOUBLE_QUOTES, '"').replace(DASHES, '-');
+}
+export function comparableText(value) {
+    return foldTypography(normaliseVisibleText(value));
+}
+export function fuzzyVisibleText(actual, expected) {
+    return comparableText(actual).toLowerCase().includes(comparableText(expected).toLowerCase());
+}
+export function textMatches(actual, query, expected) {
+    if (true !== query.matchCase) {
+        return fuzzyVisibleText(actual, expected);
+    }
+    return comparableText(actual).includes(comparableText(expected));
+}
+export function exactVisibleText(actual, expected) {
+    return comparableText(actual) === comparableText(expected);
+}
+const CASE_TRANSFORMS = {
+    uppercase: (text) => text.toUpperCase(),
+    lowercase: (text) => text.toLowerCase(),
+    capitalize: (text) => text.replace(/(^|\s)(\p{L})/gu, (_, gap, c) => gap + c.toUpperCase()),
+};
+export function paintedCase(el, text) {
+    const transform = el.ownerDocument.defaultView?.getComputedStyle(el).textTransform ?? '';
+    return CASE_TRANSFORMS[transform]?.(text);
+}
+export const UNREADABLE_CONTRAST = 1.5;
+export const UNREADABLE_OPACITY = 0.05;
+const CANVAS = [255, 255, 255, 1];
+function parseRgb(value) {
+    const m = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+))?\s*\)$/.exec(value);
+    if (null === m) {
+        return undefined;
+    }
+    return [Number(m[1]), Number(m[2]), Number(m[3]), m[4] === undefined ? 1 : Number(m[4])];
+}
+function over(top, under) {
+    const a = top[3];
+    const mix = (t, u) => t * a + u * (1 - a);
+    return [mix(top[0], under[0]), mix(top[1], under[1]), mix(top[2], under[2]), 1];
+}
+function linear(v) {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+}
+function luminance(c) {
+    return 0.2126 * linear(c[0]) + 0.7152 * linear(c[1]) + 0.0722 * linear(c[2]);
+}
+function contrast(a, b) {
+    const la = luminance(a);
+    const lb = luminance(b);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+function show(c) {
+    return `rgb(${[c[0], c[1], c[2]].map((v) => String(Math.round(v))).join(', ')})`;
+}
+function outlined(style) {
+    const stroke = Number.parseFloat(style.getPropertyValue('-webkit-text-stroke-width'));
+    return /\dpx/.test(style.textShadow) || stroke > 0;
+}
+export function unreadableText(el) {
+    const view = el.ownerDocument.defaultView;
+    if (null === view) {
+        return undefined;
+    }
+    const own = view.getComputedStyle(el);
+    const ink = parseRgb(own.color);
+    if (ink === undefined || outlined(own)) {
+        return undefined;
+    }
+    let opacity = 1;
+    const layers = [];
+    let opaque = false;
+    for (let node = el; null !== node; node = parentAcrossShadowBoundary(node)) {
+        const style = view.getComputedStyle(node);
+        const alpha = Number.parseFloat(style.opacity);
+        opacity *= Number.isNaN(alpha) ? 1 : alpha;
+        if (opaque) {
+            continue;
+        }
+        if ('' !== style.backgroundImage && 'none' !== style.backgroundImage) {
+            return undefined;
+        }
+        const fill = parseRgb(style.backgroundColor);
+        if (fill === undefined) {
+            return undefined;
+        }
+        if (fill[3] > 0) {
+            layers.push(fill);
+        }
+        opaque = fill[3] >= 1;
+    }
+    if (opacity < UNREADABLE_OPACITY) {
+        return `the composed opacity is ${opacity.toFixed(2)}`;
+    }
+    const back = layers.reduceRight((under, top) => over(top, under), CANVAS);
+    const painted = over(ink, back);
+    const ratio = contrast(painted, back);
+    if (ratio >= UNREADABLE_CONTRAST) {
+        return undefined;
+    }
+    return `text ${show(painted)} on ${show(back)}: contrast ${ratio.toFixed(2)}:1`;
+}
+export function unreadableMatch(matches) {
+    const reasons = matches.map(unreadableText);
+    return reasons.length > 0 && reasons.every((r) => r !== undefined) ? reasons[0] : undefined;
+}

package/dist/dom/theme.d.ts

@@ -1,3 +1,4 @@
+export declare function tokenNames(): Set<string>;
 interface ThemeReport {
     colorToken: string | null;
     colorTokens: string[];

package/dist/dom/theme.js

@@ -1,5 +1,24 @@
 const THEME_ATTRIBUTE = 'data-theme';
-function tokenNames() {
+const MAX_TOKEN_RULE_DEPTH = 8;
+function isGroupingRule(rule) {
+    return 'cssRules' in rule && rule.cssRules instanceof CSSRuleList;
+}
+function collectTokenNames(rules, names, depth) {
+    if (depth <= 0)
+        return;
+    for (const rule of Array.from(rules)) {
+        if (rule instanceof CSSStyleRule) {
+            for (const prop of Array.from(rule.style)) {
+                if (prop.startsWith('--'))
+                    names.add(prop);
+            }
+        }
+        else if (isGroupingRule(rule)) {
+            collectTokenNames(rule.cssRules, names, depth - 1);
+        }
+    }
+}
+export function tokenNames() {
     const names = new Set();
     for (const sheet of Array.from(document.styleSheets)) {
         let rules = null;
@@ -11,14 +30,7 @@ function tokenNames() {
         }
         if (null === rules)
             continue;
-        for (const rule of Array.from(rules)) {
-            if (!(rule instanceof CSSStyleRule))
-                continue;
-            for (const prop of Array.from(rule.style)) {
-                if (prop.startsWith('--'))
-                    names.add(prop);
-            }
-        }
+        collectTokenNames(rules, names, MAX_TOKEN_RULE_DEPTH);
     }
     return names;
 }

package/dist/dom/virtualized.js

@@ -25,8 +25,12 @@ export function unmountedRowsIn(container) {
     let top = Infinity;
     let bottom = 0;
     let totalHeight = 0;
+    const bounds = container.getBoundingClientRect();
+    const scaleY = container.offsetHeight > 0 && bounds.height > 0 ? bounds.height / container.offsetHeight : 1;
     for (const row of rows) {
-        const rowTop = row.offsetTop;
+        const rowTop = (row.getBoundingClientRect().top - bounds.top) / scaleY -
+            container.clientTop +
+            container.scrollTop;
         const rowBottom = rowTop + row.offsetHeight;
         if (rowTop < top)
             top = rowTop;

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;