@nexface/tools 0.1.0

package/src/browser/dom.ts

@@ -0,0 +1,507 @@
+import type {
+  RegexValue,
+  SemanticState,
+  TextMatcher,
+} from "./types.js";
+
+const ROLE_BY_TAG: Record<string, string> = {
+  A: "link",
+  BUTTON: "button",
+  DIALOG: "dialog",
+  FORM: "form",
+  H1: "heading",
+  H2: "heading",
+  H3: "heading",
+  H4: "heading",
+  H5: "heading",
+  H6: "heading",
+  IFRAME: "iframe",
+  LI: "listitem",
+  NAV: "navigation",
+  OL: "list",
+  OPTION: "option",
+  PROGRESS: "progressbar",
+  SELECT: "combobox",
+  TABLE: "table",
+  TBODY: "rowgroup",
+  TD: "cell",
+  TEXTAREA: "textbox",
+  TH: "columnheader",
+  TR: "row",
+  UL: "list",
+};
+
+const ACTIONABLE_ROLES = new Set([
+  "button",
+  "checkbox",
+  "combobox",
+  "link",
+  "menuitem",
+  "option",
+  "radio",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "switch",
+  "tab",
+  "textbox",
+  "treeitem",
+]);
+
+const CONTEXT_ROLES = new Set(["dialog", "row", "listitem"]);
+const ALLOWED_EXPLICIT_ROLES = new Set([
+  ...ACTIONABLE_ROLES,
+  ...CONTEXT_ROLES,
+  "alert",
+  "alertdialog",
+  "cell",
+  "columnheader",
+  "form",
+  "group",
+  "heading",
+  "iframe",
+  "list",
+  "listbox",
+  "main",
+  "menu",
+  "navigation",
+  "progressbar",
+  "region",
+  "rowgroup",
+  "status",
+  "table",
+  "tooltip",
+  "tree",
+]);
+
+const SENSITIVE_INPUT_TYPES = new Set(["file", "hidden", "password"]);
+
+export function normalizeText(value: string | null | undefined): string {
+  return (value ?? "").replace(/\s+/g, " ").trim();
+}
+
+export function composedParent(element: Element): Element | null {
+  if (element.assignedSlot) return element.assignedSlot;
+  if (element.parentElement) return element.parentElement;
+  const root = element.getRootNode();
+  return root instanceof ShadowRoot ? root.host : null;
+}
+
+export function isAgentIgnored(element: Element): boolean {
+  let current: Element | null = element;
+  while (current) {
+    if (current.hasAttribute("data-nexface-ignore")) return true;
+    current = composedParent(current);
+  }
+  return false;
+}
+
+export function composedChildren(node: Element | Document | ShadowRoot): Node[] {
+  if (node instanceof HTMLSlotElement) {
+    const assigned = node.assignedNodes({ flatten: true });
+    if (assigned.length > 0) return assigned;
+  }
+  if (node instanceof Element && node.shadowRoot) {
+    return Array.from(node.shadowRoot.childNodes);
+  }
+  return Array.from(node.childNodes);
+}
+
+export function* walkComposedElements(
+  root: Element | Document | ShadowRoot = document,
+): Generator<Element> {
+  for (const child of composedChildren(root)) {
+    if (!(child instanceof Element)) continue;
+    yield child;
+    yield* walkComposedElements(child);
+  }
+}
+
+function hasGenericInteractionEvidence(element: Element): boolean {
+  if (!(element instanceof HTMLElement)) return false;
+  return (
+    element.tabIndex >= 0 ||
+    element.hasAttribute("onclick") ||
+    element.isContentEditable
+  );
+}
+
+export function computeRole(element: Element): string {
+  const explicit = normalizeText(element.getAttribute("role"))
+    .split(" ")
+    .find((role) => ALLOWED_EXPLICIT_ROLES.has(role));
+  if (explicit) return explicit;
+
+  if (element instanceof HTMLInputElement) {
+    const type = element.type.toLowerCase();
+    if (type === "checkbox") return "checkbox";
+    if (type === "radio") return "radio";
+    if (["button", "submit", "reset"].includes(type)) return "button";
+    if (type === "range") return "slider";
+    if (type === "number") return "spinbutton";
+    if (type === "search") return "searchbox";
+    if (type === "hidden") return "";
+    return "textbox";
+  }
+
+  if (element instanceof HTMLAnchorElement && !element.hasAttribute("href")) {
+    return hasGenericInteractionEvidence(element) ? "actionable" : "";
+  }
+
+  const implicit = ROLE_BY_TAG[element.tagName] ?? "";
+  if (implicit) return implicit;
+  return hasGenericInteractionEvidence(element) ? "actionable" : "";
+}
+
+function referencedText(element: Element, attribute: string): string {
+  const root = element.getRootNode();
+  const ids = normalizeText(element.getAttribute(attribute))
+    .split(" ")
+    .filter(Boolean);
+  return normalizeText(
+    ids
+      .map((id) => {
+        if (root instanceof Document || root instanceof ShadowRoot) {
+          return root.getElementById(id)?.textContent ?? "";
+        }
+        return document.getElementById(id)?.textContent ?? "";
+      })
+      .join(" "),
+  );
+}
+
+export type NameSource = "explicit" | "content" | "fallback";
+
+export interface ComputedName {
+  value: string;
+  source: NameSource;
+}
+
+export function computeNameInfo(element: Element): ComputedName {
+  const labelledBy = referencedText(element, "aria-labelledby");
+  if (labelledBy) return { value: labelledBy, source: "explicit" };
+
+  const ariaLabel = normalizeText(element.getAttribute("aria-label"));
+  if (ariaLabel) return { value: ariaLabel, source: "explicit" };
+
+  if (
+    element instanceof HTMLInputElement ||
+    element instanceof HTMLTextAreaElement ||
+    element instanceof HTMLSelectElement
+  ) {
+    const labels = Array.from(element.labels ?? []);
+    const label = normalizeText(
+      labels.map((item) => item.textContent ?? "").join(" "),
+    );
+    if (label) return { value: label, source: "explicit" };
+  }
+
+  const legend = element.querySelector(":scope > legend");
+  if (legend) {
+    const text = normalizeText(legend.textContent);
+    if (text) return { value: text, source: "explicit" };
+  }
+
+  const alt = normalizeText(element.getAttribute("alt"));
+  if (alt) return { value: alt, source: "explicit" };
+
+  if (element instanceof HTMLTableElement) {
+    const caption = normalizeText(element.caption?.textContent);
+    if (caption) return { value: caption, source: "explicit" };
+  }
+
+  if (
+    element instanceof HTMLInputElement &&
+    ["button", "submit", "reset"].includes(element.type)
+  ) {
+    const value = normalizeText(element.value);
+    if (value) return { value, source: "fallback" };
+  }
+
+  const role = computeRole(element);
+  if (
+    isActionableRole(role) ||
+    [
+      "cell",
+      "columnheader",
+      "heading",
+      "listitem",
+      "option",
+      "row",
+      "tab",
+      "treeitem",
+    ].includes(role)
+  ) {
+    const content = normalizeText(element.textContent);
+    if (content) return { value: content, source: "content" };
+  }
+
+  const title = normalizeText(element.getAttribute("title"));
+  if (title) return { value: title, source: "fallback" };
+
+  if (
+    element instanceof HTMLInputElement ||
+    element instanceof HTMLTextAreaElement
+  ) {
+    return {
+      value: normalizeText(element.placeholder),
+      source: "fallback",
+    };
+  }
+
+  return { value: "", source: "fallback" };
+}
+
+export function computeName(element: Element): string {
+  return computeNameInfo(element).value;
+}
+
+export interface ElementScrollability {
+  x: boolean;
+  y: boolean;
+  scrollLeft: number;
+  scrollTop: number;
+  scrollWidth: number;
+  scrollHeight: number;
+  clientWidth: number;
+  clientHeight: number;
+}
+
+const SCROLLABLE_OVERFLOW = new Set(["auto", "scroll", "overlay", "hidden"]);
+
+export function getElementScrollability(
+  element: Element,
+  style = getComputedStyle(element),
+): ElementScrollability | undefined {
+  if (!(element instanceof HTMLElement)) return undefined;
+
+  const x =
+    SCROLLABLE_OVERFLOW.has(style.overflowX) &&
+    element.scrollWidth > element.clientWidth + 2;
+  const y =
+    SCROLLABLE_OVERFLOW.has(style.overflowY) &&
+    element.scrollHeight > element.clientHeight + 2;
+  if (!x && !y) return undefined;
+
+  return {
+    x,
+    y,
+    scrollLeft: element.scrollLeft,
+    scrollTop: element.scrollTop,
+    scrollWidth: element.scrollWidth,
+    scrollHeight: element.scrollHeight,
+    clientWidth: element.clientWidth,
+    clientHeight: element.clientHeight,
+  };
+}
+
+export function findNearestHeadingText(element: Element): string {
+  let current = composedParent(element);
+  while (current && current !== document.body) {
+    for (const child of composedChildren(current)) {
+      if (!(child instanceof Element) || computeRole(child) !== "heading") {
+        continue;
+      }
+      const name = normalizeText(computeName(child));
+      if (name) return name;
+    }
+    current = composedParent(current);
+  }
+  return "";
+}
+
+export function createScrollableIdentity(element: Element): string {
+  const name = computeNameInfo(element);
+  return JSON.stringify([
+    element.tagName.toLowerCase(),
+    element.id,
+    element.getAttribute("aria-label") ?? "",
+    element.getAttribute("aria-labelledby") ?? "",
+    name.source === "content" ? "" : normalizeText(name.value),
+    findNearestHeadingText(element),
+  ]);
+}
+
+export function isDisabled(element: Element): boolean {
+  let current: Element | null = element;
+  while (current) {
+    if (current.getAttribute("aria-disabled") === "true") return true;
+    current = composedParent(current);
+  }
+  return element.matches(":disabled");
+}
+
+function exposeInputValue(element: HTMLInputElement): boolean {
+  return !SENSITIVE_INPUT_TYPES.has(element.type.toLowerCase());
+}
+
+export function computeState(element: Element): SemanticState {
+  const state: SemanticState = {};
+  let active: Element | null = document.activeElement;
+  while (active?.shadowRoot?.activeElement) {
+    active = active.shadowRoot.activeElement;
+  }
+  if (active === element) state.focused = true;
+  if (isDisabled(element)) state.disabled = true;
+  if (element.getAttribute("aria-expanded") !== null) {
+    state.expanded = element.getAttribute("aria-expanded") === "true";
+  }
+  if (element.getAttribute("aria-checked") === "true") state.checked = true;
+  if (element.getAttribute("aria-selected") === "true") state.selected = true;
+  if (element.getAttribute("aria-invalid") === "true") state.invalid = true;
+  if (element.getAttribute("aria-required") === "true") state.required = true;
+
+  if (element instanceof HTMLInputElement) {
+    if (["checkbox", "radio"].includes(element.type) && element.checked) {
+      state.checked = true;
+    }
+    if (element.required) state.required = true;
+    if (!element.validity.valid) state.invalid = true;
+    if (
+      exposeInputValue(element) &&
+      !["checkbox", "radio", "button", "submit", "reset"].includes(element.type) &&
+      element.value
+    ) {
+      state.value = element.value;
+    }
+  }
+
+  if (element instanceof HTMLTextAreaElement) {
+    if (element.required) state.required = true;
+    if (!element.validity.valid) state.invalid = true;
+    if (element.value) state.value = element.value;
+  }
+
+  if (element instanceof HTMLSelectElement && element.value) {
+    state.value = element.value;
+  }
+
+  return state;
+}
+
+export function isActionableRole(role: string): boolean {
+  return role === "actionable" || ACTIONABLE_ROLES.has(role);
+}
+
+export function isContextRole(role: string): boolean {
+  return CONTEXT_ROLES.has(role);
+}
+
+export function findSemanticContext(element: Element): {
+  element?: Element;
+  role?: "dialog" | "row" | "listitem";
+  text?: string;
+} {
+  let current = composedParent(element);
+  while (current && current !== document.body) {
+    const role = computeRole(current);
+    if (role === "row" || role === "listitem") {
+      return {
+        element: current,
+        role,
+        text: computeName(current),
+      };
+    }
+    if (role === "dialog" || role === "alertdialog") {
+      return {
+        element: current,
+        role: "dialog",
+        text: computeName(current),
+      };
+    }
+    current = composedParent(current);
+  }
+  return {};
+}
+
+export function createIdentity(element: Element): string {
+  const context = findSemanticContext(element);
+  return JSON.stringify([
+    computeRole(element),
+    normalizeText(computeName(element)),
+    context.role ?? "",
+    normalizeText(context.text),
+  ]);
+}
+
+export function isElementRendered(
+  element: Element,
+  style = getComputedStyle(element),
+): boolean {
+  if (!(element instanceof HTMLElement || element instanceof SVGElement)) {
+    return false;
+  }
+  if (isAgentIgnored(element)) return false;
+  if (
+    element.hasAttribute("hidden") ||
+    element.hasAttribute("inert") ||
+    element.getAttribute("aria-hidden") === "true"
+  ) {
+    return false;
+  }
+  return style.display !== "none" && style.visibility !== "hidden";
+}
+
+export function isElementTreeRendered(element: Element): boolean {
+  let current: Element | null = element;
+  while (current) {
+    if (!isElementRendered(current)) return false;
+    current = composedParent(current);
+  }
+  return true;
+}
+
+export function isElementInViewport(
+  element: Element,
+  rect = element.getBoundingClientRect(),
+): boolean {
+  if (rect.width <= 0 || rect.height <= 0) return false;
+  return (
+    rect.right > 0 &&
+    rect.bottom > 0 &&
+    rect.left < window.innerWidth &&
+    rect.top < window.innerHeight
+  );
+}
+
+export function isVisible(element: Element): boolean {
+  if (!isElementTreeRendered(element)) return false;
+  return isElementInViewport(element);
+}
+
+export function describeElement(element: Element): string {
+  const role = computeRole(element) || element.tagName.toLowerCase();
+  const name = computeName(element).slice(0, 120);
+  const context = findSemanticContext(element);
+  return [
+    context.role && context.text
+      ? `${context.role} ${JSON.stringify(context.text.slice(0, 160))}`
+      : "",
+    name ? `${role} ${JSON.stringify(name)}` : role,
+  ]
+    .filter(Boolean)
+    .join(" > ");
+}
+
+function toRegExp(value: RegexValue): RegExp | undefined {
+  try {
+    return new RegExp(value.source, value.flags);
+  } catch {
+    return undefined;
+  }
+}
+
+export function matchesText(
+  value: string,
+  matcher: TextMatcher | undefined,
+  exact = false,
+): boolean {
+  if (matcher === undefined) return true;
+  const normalized = normalizeText(value);
+  if (typeof matcher !== "string") {
+    const regex = toRegExp(matcher);
+    return regex ? regex.test(normalized) : false;
+  }
+  const expected = normalizeText(matcher);
+  return exact ? normalized === expected : normalized.includes(expected);
+}

package/src/browser/feedback.ts

@@ -0,0 +1,5 @@
+export class ActionFeedback {
+  before(_action: string, _element: Element): void {}
+
+  after(_action: string): void {}
+}