@teaflask/assistant 0.0.0 → 0.6.0

package/dist/reader/snapshot-compaction.js

@@ -0,0 +1,166 @@
+import { _normalizedNodeName } from "./snapshot-node.js";
+export function _mergeStringChildren(node) {
+    for (const child of node.children) {
+        if (typeof child !== "string") {
+            _mergeStringChildren(child);
+        }
+    }
+    const merged = [];
+    let buffer = [];
+    const flush = () => {
+        const text = _mergedTextOf(buffer);
+        if (text !== "") {
+            merged.push(text);
+        }
+        buffer = [];
+    };
+    for (const child of node.children) {
+        if (typeof child === "string") {
+            buffer.push(child);
+        }
+        else if (_isBareTextParagraph(child)) {
+            buffer.push(_mergedTextOf(child.children.filter((c) => typeof c === "string")));
+        }
+        else {
+            flush();
+            merged.push(child);
+        }
+    }
+    flush();
+    node.children = merged;
+    if (node.children.length === 1 &&
+        typeof node.children[0] === "string" &&
+        node.children[0] === node.name) {
+        node.children = [];
+    }
+}
+function _isBareTextParagraph(node) {
+    return (node.role === "paragraph" &&
+        node.refId === null &&
+        !node.hidden &&
+        !node.scrollable &&
+        node.children.every((child) => typeof child === "string"));
+}
+export function _unwrapBareGenerics(node, showHidden) {
+    const result = [];
+    for (const child of node.children) {
+        if (typeof child === "string") {
+            result.push(child);
+            continue;
+        }
+        _unwrapBareGenerics(child, showHidden);
+        if (!showHidden &&
+            child.hidden &&
+            child.refId === null &&
+            !_hasRefInSubtree(child)) {
+            continue;
+        }
+        if (child.role === "paragraph" &&
+            child.refId === null &&
+            child.children.length === 1 &&
+            typeof child.children[0] !== "string" &&
+            child.children[0].role === "paragraph") {
+            result.push(child.children[0]);
+            continue;
+        }
+        if (child.role === "generic" &&
+            !child.hidden &&
+            child.name === "" &&
+            child.children.length === 1 &&
+            typeof child.children[0] !== "string" &&
+            child.children[0].refId !== null) {
+            result.push(child.children[0]);
+            continue;
+        }
+        result.push(child);
+    }
+    node.children = result;
+}
+function _hasRefInSubtree(node) {
+    if (node.refId !== null) {
+        return true;
+    }
+    return node.children.some((child) => typeof child !== "string" && _hasRefInSubtree(child));
+}
+const TEXT_LEAF_ROLES = new Set(["generic", "heading", "paragraph", "label"]);
+export function _foldTextLeaves(node) {
+    for (const child of node.children) {
+        if (typeof child !== "string") {
+            _foldTextLeaves(child);
+        }
+    }
+    if (node.refId === null) {
+        return;
+    }
+    if (node.children.length < 1 || node.children.length > 3) {
+        return;
+    }
+    const texts = [];
+    for (const child of node.children) {
+        if (typeof child === "string") {
+            texts.push(child);
+            continue;
+        }
+        const isFoldableLeaf = !child.hidden &&
+            TEXT_LEAF_ROLES.has(child.role) &&
+            child.name !== "" &&
+            child.children.length === 0 &&
+            child.refId === null;
+        if (!isFoldableLeaf) {
+            return;
+        }
+        texts.push(child.name);
+    }
+    const mergedText = _normalizedNodeName(texts.join(" "));
+    if (node.name === "") {
+        node.name = mergedText;
+        node.children = [];
+    }
+    else if (node.name.replace(/\s+/g, "") === mergedText.replace(/\s+/g, "")) {
+        node.children = [];
+    }
+}
+function _mergedTextOf(parts) {
+    let merged = "";
+    for (const part of parts) {
+        if (part === "") {
+            continue;
+        }
+        if (merged === "") {
+            merged = part;
+            continue;
+        }
+        if (_wordsMeetAtTheSeam(merged, part)) {
+            merged += " ";
+        }
+        merged += part;
+    }
+    return merged.trim();
+}
+function _wordsMeetAtTheSeam(left, right) {
+    if (/\s$/u.test(left) || /^\s/u.test(right)) {
+        return false;
+    }
+    return /[\p{L}\p{N}]$/u.test(left) && /^[\p{L}\p{N}]/u.test(right);
+}
+export function _duplicateRefOf(node) {
+    const seen = new Set();
+    const walk = (current) => {
+        if (current.refId !== null) {
+            if (seen.has(current.refId)) {
+                return current.refId;
+            }
+            seen.add(current.refId);
+        }
+        for (const child of current.children) {
+            if (typeof child !== "string") {
+                const duplicate = walk(child);
+                if (duplicate !== null) {
+                    return duplicate;
+                }
+            }
+        }
+        return null;
+    };
+    return walk(node);
+}

package/dist/reader/snapshot-node.d.ts

@@ -0,0 +1,4 @@
+import type { SnapshotNode, WalkContext } from "./snapshot.js";
+export declare function _snapshotNodeOf(element: Element, context: WalkContext, refFor: (element: Element, role: string, name: string) => string): SnapshotNode | null;
+export declare function _normalizedNodeName(name: string): string;
+export declare function _fragmentNode(): SnapshotNode;

package/dist/reader/snapshot-node.js

@@ -0,0 +1,113 @@
+import { accessibleNameOf } from "./accessible-name.js";
+import { CONTENT_REF_ROLES, INTERACTIVE_REF_ROLES, interactivitySignalsOf, isScrollable, } from "./interactivity.js";
+import { textboxValueOf } from "./redaction.js";
+import { ariaBooleanOf, ariaLevelOf, ARIA_CHECKED_ROLES, ARIA_DISABLED_ROLES, ARIA_SELECTED_ROLES, roleOf, } from "./roles.js";
+import { parentAcrossShadowBoundaryOf } from "./visibility.js";
+const MAX_NODE_NAME_LENGTH = 100;
+export function _snapshotNodeOf(element, context, refFor) {
+    const { options, oracle, nameCache } = context;
+    const role = roleOf(element);
+    const roleLower = role.toLowerCase();
+    const interactivity = interactivitySignalsOf(element, options.probe);
+    const name = _normalizedNodeName(accessibleNameOf(element, options.probe, nameCache));
+    const hidden = !oracle.isVisible(element);
+    const scrollable = isScrollable(element, options.probe);
+    const shouldHaveRef = roleLower === "iframe" ||
+        roleLower === "canvas" ||
+        scrollable ||
+        interactivity.interactive ||
+        INTERACTIVE_REF_ROLES.has(roleLower) ||
+        (CONTENT_REF_ROLES.has(roleLower) && name.length > 0);
+    const refId = shouldHaveRef ? refFor(element, role, name) : null;
+    if (role === "generic" && refId === null && !hidden) {
+        return null;
+    }
+    const hints = interactivity.interactive && !interactivity.isInteractiveTag
+        ? interactivity.hints
+        : [];
+    const value = textboxValueOf(element);
+    return {
+        role,
+        name,
+        level: ariaLevelOf(element, role),
+        hidden,
+        scrollable,
+        checked: _checkedStateOf(element, roleLower),
+        selected: _selectedStateOf(element, roleLower),
+        focused: element.ownerDocument.activeElement === element,
+        disabled: _disabledStateOf(element, roleLower),
+        offscreen: !hidden && oracle.isOffscreen(element),
+        refId,
+        hints,
+        placeholder: element.getAttribute("placeholder"),
+        element,
+        children: value !== null && value !== "" ? [value] : [],
+    };
+}
+function _checkedStateOf(element, role) {
+    if (element instanceof HTMLInputElement &&
+        (element.type === "checkbox" || element.type === "radio")) {
+        return element.checked;
+    }
+    if (!ARIA_CHECKED_ROLES.has(role)) {
+        return false;
+    }
+    return ariaBooleanOf(element.getAttribute("aria-checked")) === true;
+}
+function _selectedStateOf(element, role) {
+    if (element instanceof HTMLOptionElement) {
+        return element.selected;
+    }
+    if (!ARIA_SELECTED_ROLES.has(role)) {
+        return false;
+    }
+    return ariaBooleanOf(element.getAttribute("aria-selected")) === true;
+}
+function _disabledStateOf(element, role) {
+    if (!ARIA_DISABLED_ROLES.has(role)) {
+        return false;
+    }
+    if (_isNativelyDisabled(element)) {
+        return true;
+    }
+    for (let current = element; current !== null; current = parentAcrossShadowBoundaryOf(current)) {
+        if (ariaBooleanOf(current.getAttribute("aria-disabled")) === true) {
+            return true;
+        }
+    }
+    return false;
+}
+function _isNativelyDisabled(element) {
+    const tag = element.tagName.toLowerCase();
+    if (!["button", "input", "select", "textarea", "option", "optgroup"].includes(tag)) {
+        return false;
+    }
+    try {
+        return element.matches(":disabled");
+    }
+    catch {
+        return false;
+    }
+}
+export function _normalizedNodeName(name) {
+    return name.replace(/\s+/g, " ").trim().substring(0, MAX_NODE_NAME_LENGTH);
+}
+export function _fragmentNode() {
+    return {
+        role: "fragment",
+        name: "",
+        level: null,
+        hidden: false,
+        scrollable: false,
+        checked: false,
+        selected: false,
+        focused: false,
+        disabled: false,
+        offscreen: false,
+        refId: null,
+        hints: [],
+        placeholder: null,
+        element: null,
+        children: [],
+    };
+}

package/dist/reader/snapshot-root.d.ts

@@ -0,0 +1,15 @@
+export declare const IGNORE_ATTRIBUTE = "data-teaflask-ignore";
+export interface RootAddress {
+    rootElement: Element | null;
+    refId: string | null;
+    selector: string | null;
+    ignoreSelectors: string[];
+}
+export declare function _resolvedRootOf(options: RootAddress, elementByRef: ReadonlyMap<string, Element>): {
+    root: Element;
+    error: null;
+} | {
+    root: null;
+    error: string;
+};
+export declare function _theSubtreeIsCurated(element: Element, ignoreSelectors: string[]): boolean;

package/dist/reader/snapshot-root.js

@@ -0,0 +1,85 @@
+import { roleOf } from "./roles.js";
+import { parentAcrossShadowBoundaryOf } from "./visibility.js";
+export const IGNORE_ATTRIBUTE = "data-teaflask-ignore";
+export function _resolvedRootOf(options, elementByRef) {
+    if (options.rootElement !== null) {
+        return _rootUnlessCurated(options.rootElement, options);
+    }
+    if (options.refId !== null) {
+        const remembered = elementByRef.get(options.refId);
+        if (remembered?.isConnected !== true) {
+            return {
+                root: null,
+                error: `The ref "${options.refId}" is not on the current page — ` +
+                    "take a fresh full read and use a ref from it.",
+            };
+        }
+        return _rootUnlessCurated(remembered, options);
+    }
+    if (options.selector !== null) {
+        const matched = _safeQuerySelector(options.selector);
+        if (matched === null) {
+            return {
+                root: null,
+                error: `Nothing on the page matches the selector "${options.selector}" — ` +
+                    "take a full read to see what is there.",
+            };
+        }
+        return _rootUnlessCurated(matched, options);
+    }
+    const body = document.body;
+    if (body === null) {
+        return { root: null, error: "The page has no body to read yet." };
+    }
+    return { root: body, error: null };
+}
+function _rootUnlessCurated(root, options) {
+    for (let current = root; current !== null; current = parentAcrossShadowBoundaryOf(current)) {
+        if (_theSubtreeIsCurated(current, options.ignoreSelectors)) {
+            return {
+                root: null,
+                error: "That part of the page has opted out of page reads — " +
+                    "take a full read to see what is available.",
+            };
+        }
+    }
+    return { root, error: null };
+}
+function _safeQuerySelector(selector) {
+    try {
+        const direct = document.querySelector(selector);
+        if (direct !== null) {
+            return direct;
+        }
+    }
+    catch {
+        return null;
+    }
+    return _firstElementWithImplicitRole(selector);
+}
+function _firstElementWithImplicitRole(selector) {
+    const match = /^\[role=["'](\w+)["']\]$/.exec(selector);
+    if (match === null) {
+        return null;
+    }
+    const targetRole = match[1];
+    for (const element of Array.from(document.querySelectorAll("*"))) {
+        if (roleOf(element) === targetRole) {
+            return element;
+        }
+    }
+    return null;
+}
+export function _theSubtreeIsCurated(element, ignoreSelectors) {
+    if (element.hasAttribute(IGNORE_ATTRIBUTE)) {
+        return true;
+    }
+    return ignoreSelectors.some((selector) => {
+        try {
+            return element.matches(selector);
+        }
+        catch {
+            return false;
+        }
+    });
+}

package/dist/reader/snapshot.d.ts

@@ -0,0 +1,60 @@
+import type { LayoutProbe } from "./layout-probe.js";
+import { type AccessibleNameCache } from "./accessible-name.js";
+import { IGNORE_ATTRIBUTE } from "./snapshot-root.js";
+import { type VisibilityOracle } from "./visibility.js";
+export { IGNORE_ATTRIBUTE };
+export declare const DEFAULT_MAX_DEPTH = 50;
+export interface SnapshotOptions {
+    probe: LayoutProbe;
+    ignoreSelectors: string[];
+    maxDepth: number;
+    interactive: boolean;
+    showHidden: boolean;
+    selector: string | null;
+    refId: string | null;
+    rootElement: Element | null;
+}
+export interface SnapshotNode {
+    role: string;
+    name: string;
+    level: number | null;
+    hidden: boolean;
+    scrollable: boolean;
+    checked: boolean;
+    selected: boolean;
+    focused: boolean;
+    disabled: boolean;
+    offscreen: boolean;
+    refId: string | null;
+    hints: string[];
+    placeholder: string | null;
+    element: Element | null;
+    children: (SnapshotNode | string)[];
+}
+export type SnapshotOutcome = {
+    tree: SnapshotNode;
+    error: null;
+} | {
+    tree: null;
+    error: string;
+};
+export interface WalkContext {
+    options: SnapshotOptions;
+    oracle: VisibilityOracle;
+    nameCache: AccessibleNameCache;
+}
+export declare function snapshotTreeOf(options: SnapshotOptions): SnapshotOutcome;
+export declare function resolvedSnapshotRootOf(options: SnapshotOptions): {
+    root: Element;
+    error: null;
+} | {
+    root: null;
+    error: string;
+};
+export declare function resolvedElementOfRef(refId: string): {
+    element: Element;
+    error: null;
+} | {
+    element: null;
+    error: string;
+};

package/dist/reader/snapshot.js

@@ -0,0 +1,167 @@
+import { accessibleNameOf, } from "./accessible-name.js";
+import { interactivitySignalsOf, isLandmark, isScrollable, } from "./interactivity.js";
+import { roleOf } from "./roles.js";
+import { _duplicateRefOf, _foldTextLeaves, _mergeStringChildren, _unwrapBareGenerics, } from "./snapshot-compaction.js";
+import { _fragmentNode, _normalizedNodeName, _snapshotNodeOf, } from "./snapshot-node.js";
+import { _resolvedRootOf, _theSubtreeIsCurated, IGNORE_ATTRIBUTE, } from "./snapshot-root.js";
+import { lightAndShadowChildNodesOf, visibilityOracleOf, } from "./visibility.js";
+export { IGNORE_ATTRIBUTE };
+export const DEFAULT_MAX_DEPTH = 50;
+const SKIP_TAGS = new Set([
+    "script",
+    "style",
+    "meta",
+    "link",
+    "title",
+    "noscript",
+]);
+let _refCounter = 0;
+const _refBadgeByElement = new WeakMap();
+const _elementByRef = new Map();
+export function snapshotTreeOf(options) {
+    const context = {
+        options,
+        oracle: visibilityOracleOf(options.probe),
+        nameCache: new Map(),
+    };
+    const rooting = _resolvedRootOf(options, _elementByRef);
+    if (rooting.error !== null) {
+        return { tree: null, error: rooting.error };
+    }
+    const root = rooting.root;
+    _elementByRef.clear();
+    const fragment = _fragmentNode();
+    _traverse(root, 0, fragment, context);
+    _mergeStringChildren(fragment);
+    _unwrapBareGenerics(fragment, options.showHidden);
+    _foldTextLeaves(fragment);
+    const duplicate = _duplicateRefOf(fragment);
+    if (duplicate !== null) {
+        return {
+            tree: null,
+            error: `The snapshot minted the ref "${duplicate}" twice; take a fresh read.`,
+        };
+    }
+    return { tree: fragment, error: null };
+}
+export function resolvedSnapshotRootOf(options) {
+    return _resolvedRootOf(options, _elementByRef);
+}
+export function resolvedElementOfRef(refId) {
+    const address = {
+        rootElement: null,
+        refId,
+        selector: null,
+        ignoreSelectors: [],
+    };
+    const rooting = _resolvedRootOf(address, _elementByRef);
+    if (rooting.error !== null) {
+        return { element: null, error: rooting.error };
+    }
+    return { element: rooting.root, error: null };
+}
+function _traverse(element, depth, parentNode, context) {
+    const { options, oracle } = context;
+    const includeAsRoot = options.refId === null && element === document.body;
+    const traversable = _shouldTraverse(element, context);
+    if (!traversable && !includeAsRoot) {
+        return;
+    }
+    const hidden = !oracle.isVisible(element);
+    const include = includeAsRoot ||
+        _shouldIncludeNode(element, context) ||
+        (options.showHidden && hidden);
+    let targetNode = parentNode;
+    if (include) {
+        const node = _snapshotNodeOf(element, context, _refFor);
+        if (node !== null) {
+            parentNode.children.push(node);
+            targetNode = node;
+        }
+    }
+    else if (options.interactive && element.childElementCount === 0) {
+        if (_hoistSkippedLeafName(element, parentNode, context)) {
+            return;
+        }
+    }
+    const before = options.probe.pseudoContentOf(element, "::before");
+    if (before !== "") {
+        targetNode.children.push(before);
+    }
+    if (_descendsIntoChildren(element) && depth < options.maxDepth) {
+        for (const child of lightAndShadowChildNodesOf(element)) {
+            if (child.nodeType === Node.TEXT_NODE) {
+                if (targetNode.role !== "textbox" && child.nodeValue !== null) {
+                    targetNode.children.push(child.nodeValue);
+                }
+            }
+            else if (child.nodeType === Node.ELEMENT_NODE) {
+                _traverse(child, depth + 1, targetNode, context);
+            }
+        }
+    }
+    const after = options.probe.pseudoContentOf(element, "::after");
+    if (after !== "") {
+        targetNode.children.push(after);
+    }
+}
+function _descendsIntoChildren(element) {
+    const tag = element.tagName.toLowerCase();
+    return tag !== "iframe" && tag !== "select";
+}
+function _shouldTraverse(element, context) {
+    const tag = element.tagName.toLowerCase();
+    if (SKIP_TAGS.has(tag)) {
+        return false;
+    }
+    if (_theSubtreeIsCurated(element, context.options.ignoreSelectors)) {
+        return false;
+    }
+    if (!context.options.showHidden && !context.oracle.isVisible(element)) {
+        if (element instanceof HTMLInputElement) {
+            const type = element.type;
+            if (type === "radio" || type === "checkbox") {
+                return true;
+            }
+        }
+        return false;
+    }
+    return true;
+}
+function _shouldIncludeNode(element, context) {
+    const { options, nameCache } = context;
+    const role = roleOf(element);
+    const interactive = interactivitySignalsOf(element, options.probe).interactive;
+    const scrollable = isScrollable(element, options.probe);
+    const landmark = isLandmark(element);
+    if (options.interactive) {
+        return role === "canvas" || interactive || scrollable || landmark;
+    }
+    if (interactive || scrollable || landmark) {
+        return true;
+    }
+    if (accessibleNameOf(element, options.probe, nameCache).length > 0) {
+        return true;
+    }
+    return role !== "generic" && role !== "image";
+}
+function _hoistSkippedLeafName(element, parentNode, context) {
+    const name = _normalizedNodeName(accessibleNameOf(element, context.options.probe, context.nameCache));
+    if (name === "") {
+        return false;
+    }
+    parentNode.children.push(name);
+    return true;
+}
+function _refFor(element, role, name) {
+    const badge = _refBadgeByElement.get(element);
+    if (badge?.role === role && badge.name === name) {
+        _elementByRef.set(badge.ref, element);
+        return badge.ref;
+    }
+    _refCounter += 1;
+    const ref = `e${String(_refCounter)}`;
+    _refBadgeByElement.set(element, { role, name, ref });
+    _elementByRef.set(ref, element);
+    return ref;
+}

package/dist/reader/visibility.d.ts

@@ -0,0 +1,8 @@
+import type { LayoutProbe } from "./layout-probe.js";
+export interface VisibilityOracle {
+    isVisible(element: Element): boolean;
+    isOffscreen(element: Element): boolean;
+}
+export declare function visibilityOracleOf(probe: LayoutProbe): VisibilityOracle;
+export declare function parentAcrossShadowBoundaryOf(element: Element): Element | null;
+export declare function lightAndShadowChildNodesOf(element: Element): Node[];