@devaccel-labs/app-comments-toolbar 1.1.0 → 1.3.0

package/src/runtime/capture.ts

@@ -0,0 +1,508 @@
+import type { Anchor, Candidate, Resolution } from "../core/index.js";
+import { resolveAnchor } from "../core/index.js";
+
+const EXPLICIT = ["data-cs-anchor", "data-testid", "data-test", "id"];
+const SKIPPED = new Set(["SCRIPT", "STYLE", "LINK", "META"]);
+/** Most elements one lookup builds candidates for, so a huge page can't stall a resolve. */
+const MAX_ELEMENTS = 8000;
+
+function clip(value: string | null | undefined, max = 160) {
+  const text = (value ?? "").replace(/\s+/g, " ").trim();
+  return text ? text.slice(0, max) : null;
+}
+
+function usableExplicit(attr: string, value: string) {
+  if (!value || value.length > 200) return false;
+  if (attr === "id" || attr === "data-testid" || attr === "data-test") {
+    if (value.startsWith(":") || value.startsWith("radix-") || value.startsWith("headlessui-"))
+      return false;
+  }
+  return true;
+}
+
+function domPath(element: Element) {
+  const parts: number[] = [];
+  let current: Element | null = element;
+  while (current && current !== current.ownerDocument.body) {
+    const parent: Element | null = current.parentElement;
+    if (!parent) break;
+    parts.push([...parent.children].indexOf(current));
+    current = parent;
+  }
+  return parts.reverse().join("/");
+}
+
+function intraPath(element: Element, owner: Element | null) {
+  if (!owner || owner === element) return element === owner ? element.tagName.toLowerCase() : null;
+  const parts: string[] = [];
+  let current: Element | null = element;
+  while (current && current !== owner) {
+    const parent: Element | null = current.parentElement;
+    if (!parent) break;
+    const same = [...parent.children].filter((child) => child.tagName === current!.tagName);
+    const index = same.indexOf(current);
+    const tag = current.tagName.toLowerCase();
+    parts.push(same.length > 1 ? `${tag}[${index}]` : tag);
+    current = parent;
+  }
+  return parts.reverse().join("/") || null;
+}
+
+/**
+ * `clip(element.textContent, max)` without reading the whole subtree: text nodes are visited in order and the walk
+ * stops once `max` normalized characters are in hand, so a page-wide wrapper costs the same as a button.
+ */
+function clippedText(element: Element, max: number) {
+  const walker = element.ownerDocument.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+  let text = "";
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    text = `${text}${node.textContent ?? ""}`.replace(/\s+/g, " ");
+    if (text.trimStart().length >= max) break;
+  }
+  return clip(text, max);
+}
+
+function elementText(element: Element) {
+  let direct = "";
+  for (const node of element.childNodes) {
+    if (node.nodeType === Node.TEXT_NODE) direct += node.textContent ?? "";
+  }
+  const own = clip(direct);
+  if (own) return own;
+  if (element.children.length > 3) return null;
+  return clippedText(element, 80);
+}
+
+function labelFor(element: Element) {
+  const aria = element.getAttribute("aria-label");
+  if (aria) return clip(aria);
+  const labelledby = element.getAttribute("aria-labelledby");
+  if (labelledby) {
+    const text = labelledby
+      .split(/\s+/)
+      .map((id) => element.ownerDocument.getElementById(id)?.textContent ?? "")
+      .join(" ");
+    const clipped = clip(text);
+    if (clipped) return clipped;
+  }
+  if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+    if (element.labels?.[0]?.textContent) return clip(element.labels[0].textContent);
+    if (element.placeholder) return clip(element.placeholder);
+  }
+  if (element instanceof HTMLImageElement && element.alt) return clip(element.alt);
+  return elementText(element);
+}
+
+function roleFor(element: Element) {
+  const explicit = element.getAttribute("role");
+  if (explicit) return explicit;
+  const tag = element.tagName.toLowerCase();
+  if (tag === "button") return "button";
+  if (tag === "a" && element.hasAttribute("href")) return "link";
+  if (tag === "textarea") return "textbox";
+  if (tag === "select") return "combobox";
+  if (tag === "dialog") return "dialog";
+  if (/^h[1-6]$/.test(tag)) return "heading";
+  if (element instanceof HTMLInputElement)
+    return element.type === "checkbox" ? "checkbox" : "textbox";
+  return null;
+}
+
+function overlayFor(element: Element) {
+  const node = element.closest("dialog,[role='dialog'],[role='alertdialog']");
+  if (!node) return null;
+  const role = node.getAttribute("role") || (node.tagName === "DIALOG" ? "dialog" : "dialog");
+  return { role, name: labelFor(node) || "dialog" };
+}
+
+type Fiber = { return?: Fiber | null; type?: unknown; memoizedProps?: unknown };
+
+function fiberOf(element: Element) {
+  const key = Object.keys(element).find(
+    (name) => name.startsWith("__reactFiber$") || name.startsWith("__reactInternalInstance$"),
+  );
+  return key ? (element as unknown as Record<string, Fiber | undefined>)[key] : undefined;
+}
+
+function fiberNames(element: Element) {
+  const names: string[] = [];
+  let fiber = fiberOf(element);
+  for (let guard = 0; fiber && guard < 40; guard++) {
+    const type = fiber.type;
+    if (typeof type === "function") {
+      const fn = type as { displayName?: string; name?: string };
+      const name = fn.displayName || fn.name;
+      if (name && !name.startsWith("_")) names.push(name);
+    }
+    fiber = fiber.return ?? undefined;
+  }
+  return names.reverse();
+}
+
+/** Stamps along React's tree, nearest first. Unlike the DOM, this path runs through portals. */
+function fiberStamps(element: Element) {
+  const stamps: Array<{ name: string; file: string | null }> = [];
+  let fiber = fiberOf(element);
+  for (let guard = 0; fiber && guard < 2000; guard++) {
+    // allow-banned-record-unknown: React fiber props are an open bag; only two data-cs-* keys are read
+    const props = fiber.memoizedProps as Record<string, unknown> | null | undefined;
+    const name = props && typeof props === "object" ? props["data-cs-cmp"] : undefined;
+    if (typeof name === "string" && name) {
+      const file = props?.["data-cs-file"];
+      stamps.push({ name, file: typeof file === "string" ? file : null });
+    }
+    fiber = fiber.return ?? undefined;
+  }
+  return stamps;
+}
+
+/** The element's ancestor that sits directly under <body>: a portal root for popups and modals. */
+function bodyChild(element: Element) {
+  let current: Element | null = element;
+  while (current?.parentElement && current.parentElement !== current.ownerDocument.body)
+    current = current.parentElement;
+  return current?.parentElement ? current : null;
+}
+
+function obviouslyHidden(element: Element) {
+  const dialog = element.closest("dialog");
+  if (dialog instanceof HTMLDialogElement && !dialog.open) return true;
+  if (element.closest("[hidden]")) return true;
+  let current: Element | null = element;
+  while (current) {
+    if (current.getAttribute("aria-hidden") === "true") return true;
+    current = current.parentElement;
+  }
+  return false;
+}
+
+type Owned = {
+  component: { name: string; file: string | null } | null;
+  stack: string[];
+  componentRoot: boolean;
+  owner: Element | null;
+};
+
+function ownership(element: Element): Owned {
+  const stack: string[] = [];
+  let owner: Element | null = null;
+  let current: Element | null = element;
+  while (current) {
+    const name = current.getAttribute("data-cs-cmp");
+    if (name) {
+      if (!owner) owner = current;
+      stack.push(name);
+    }
+    current = current.parentElement;
+  }
+  const top = bodyChild(element);
+  if (top && top !== element && (!owner || !top.contains(owner))) {
+    const stamps = fiberStamps(element);
+    if (stamps.length && (!owner || stamps[0].name !== owner.getAttribute("data-cs-cmp"))) {
+      return {
+        component: stamps[0],
+        stack: stamps.map((stamp) => stamp.name).reverse(),
+        componentRoot: false,
+        owner: top,
+      };
+    }
+  }
+  if (owner) {
+    return {
+      component: {
+        name: owner.getAttribute("data-cs-cmp") || "component",
+        file: owner.getAttribute("data-cs-file"),
+      },
+      stack: stack.reverse(),
+      componentRoot: owner === element,
+      owner,
+    };
+  }
+  const names = fiberNames(element);
+  const name = names.at(-1) ?? null;
+  return {
+    component: name ? { name, file: null } : null,
+    stack: names,
+    componentRoot: false,
+    owner: null,
+  };
+}
+
+function once<T>(compute: () => T): () => T {
+  let done = false;
+  let value: T;
+  return () => {
+    if (!done) {
+      value = compute();
+      done = true;
+    }
+    return value;
+  };
+}
+
+/** Each field is computed when first read, so a resolve only pays for what the match looks at. */
+export function candidateFromElement(
+  element: Element,
+  route: string,
+  key: string,
+  owned = ownership(element),
+  pathOf: (element: Element) => string = domPath,
+): Candidate {
+  const label = once(() => labelFor(element));
+  const visible = once(() => !obviouslyHidden(element));
+  const path = once(() => pathOf(element));
+  const overlay = once(() => overlayFor(element));
+  const role = once(() => roleFor(element));
+  const intra = once(() => intraPath(element, owned.owner));
+  const explicit = once(() =>
+    EXPLICIT.flatMap((attr) => {
+      const value = element.getAttribute(attr);
+      return value && usableExplicit(attr, value) ? [{ attr, value }] : [];
+    }),
+  );
+  return {
+    key,
+    route,
+    get visible() {
+      return visible();
+    },
+    get path() {
+      return path();
+    },
+    componentRoot: owned.componentRoot,
+    get overlay() {
+      return overlay();
+    },
+    get explicit() {
+      return explicit();
+    },
+    component: owned.component,
+    get stack() {
+      return owned.stack;
+    },
+    get role() {
+      return role();
+    },
+    get accName() {
+      return label();
+    },
+    get text() {
+      return label();
+    },
+    tag: element.tagName.toLowerCase(),
+    get intra() {
+      return intra();
+    },
+  };
+}
+
+export function captureAnchor(element: Element, route = window.location.pathname): Anchor {
+  const candidate = candidateFromElement(element, route, "target");
+  return {
+    v: 1,
+    route,
+    overlay: candidate.overlay,
+    explicit: candidate.explicit,
+    component: candidate.component,
+    stack: candidate.stack,
+    role: candidate.role,
+    accName: candidate.accName,
+    text: candidate.text,
+    tag: candidate.tag,
+    intra: candidate.intra,
+  };
+}
+
+export type Resolved = { resolution: Resolution; element: Element | null };
+
+/**
+ * Resolves anchors against the page as it is now, building candidates only for the elements that can decide the
+ * result: those carrying one of the anchor's explicit ids, those owned by a component of the anchor's name, and,
+ * when the label changed, those inside that component's root. Never walks the whole page for a stamped anchor.
+ * Reuse one resolver for anchors resolved together; make a new one once the page may have changed.
+ */
+export function createResolver(route = window.location.pathname) {
+  const body = document.body;
+  const toolbar = document.getElementById("cs-root");
+  const owners = new Map<Element, Owned>();
+  /** Elements reached by walking down from their stamped owner, which is therefore their nearest stamp. */
+  const walkedFrom = new Map<Element, Element>();
+  const candidates = new Map<Element, Candidate>();
+  const elements = new Map<string, Element>();
+  const pools = new Map<string, Element[]>();
+  /** Index paths, shared across the elements of one resolve: a path is its parent's path plus one lookup. */
+  const paths = new Map<Element, string>();
+  /** Each child's index under its parent, read once per parent instead of once per child. */
+  const indexes = new Map<Element, Map<Element, number>>();
+  let unowned: Element[] | null = null;
+
+  const indexUnder = (parent: Element, child: Element) => {
+    let table = indexes.get(parent);
+    if (!table) {
+      table = new Map();
+      let index = 0;
+      for (const node of parent.children) table.set(node, index++);
+      indexes.set(parent, table);
+    }
+    return table.get(child) ?? -1;
+  };
+  /** Same result as `domPath`, built from the parent's cached path. */
+  const pathOf = (element: Element): string => {
+    const known = paths.get(element);
+    if (known !== undefined) return known;
+    const parent = element.parentElement;
+    let path = "";
+    if (element !== body && parent) {
+      const above = pathOf(parent);
+      const index = String(indexUnder(parent, element));
+      path = above ? `${above}/${index}` : index;
+    }
+    paths.set(element, path);
+    return path;
+  };
+
+  const counted = (element: Element) =>
+    !SKIPPED.has(element.tagName) && !(toolbar && toolbar.contains(element));
+  const ownerOf = (element: Element) => {
+    let owned = owners.get(element);
+    if (!owned) {
+      const stamped = walkedFrom.get(element);
+      owned = stamped
+        ? {
+            component: {
+              name: stamped.getAttribute("data-cs-cmp") || "component",
+              file: stamped.getAttribute("data-cs-file"),
+            },
+            componentRoot: stamped === element,
+            owner: stamped,
+            get stack() {
+              return ownership(element).stack;
+            },
+          }
+        : ownership(element);
+      owners.set(element, owned);
+    }
+    return owned;
+  };
+  const candidateOf = (element: Element) => {
+    let candidate = candidates.get(element);
+    if (!candidate) {
+      candidate = candidateFromElement(
+        element,
+        route,
+        `e${candidates.size}`,
+        ownerOf(element),
+        pathOf,
+      );
+      candidates.set(element, candidate);
+      elements.set(candidate.key, element);
+    }
+    return candidate;
+  };
+  const take = (into: Set<Element>, element: Element) => {
+    if (into.size < MAX_ELEMENTS && counted(element)) into.add(element);
+  };
+  /** `start` and its descendants, skipping the subtrees of other stamped components. */
+  const ownedBy = (start: Element, into: Set<Element>) => {
+    const walker = document.createTreeWalker(start, NodeFilter.SHOW_ELEMENT, {
+      acceptNode: (node) =>
+        node === toolbar || (node !== start && (node as Element).hasAttribute("data-cs-cmp"))
+          ? NodeFilter.FILTER_REJECT
+          : NodeFilter.FILTER_ACCEPT,
+    });
+    for (
+      let node: Node | null = start;
+      node && into.size < MAX_ELEMENTS;
+      node = walker.nextNode()
+    ) {
+      take(into, node as Element);
+      walkedFrom.set(node as Element, start);
+    }
+  };
+  /** Elements with no stamped ancestor inside <body>: wrappers and portaled content, credited through React's tree. */
+  const unownedElements = () => {
+    if (unowned) return unowned;
+    const found = new Set<Element>();
+    const walker = document.createTreeWalker(body, NodeFilter.SHOW_ELEMENT, {
+      acceptNode: (node) =>
+        (node as Element).hasAttribute("data-cs-cmp") || node === toolbar
+          ? NodeFilter.FILTER_REJECT
+          : NodeFilter.FILTER_ACCEPT,
+    });
+    for (let node = walker.nextNode(); node && found.size < MAX_ELEMENTS; node = walker.nextNode())
+      take(found, node as Element);
+    unowned = [...found];
+    return unowned;
+  };
+  const explicitHits = (anchor: Anchor, into: Set<Element>) => {
+    for (const { attr, value } of anchor.explicit) {
+      if (!EXPLICIT.includes(attr) || !usableExplicit(attr, value)) continue;
+      for (const element of body.querySelectorAll(`[${attr}="${CSS.escape(value)}"]`))
+        take(into, element);
+    }
+  };
+  /** Every element owned by a component named `name`, found once per resolver. */
+  const ownedByName = (name: string) => {
+    let pool = pools.get(name);
+    if (!pool) {
+      const found = new Set<Element>();
+      for (const root of body.querySelectorAll(`[data-cs-cmp="${CSS.escape(name)}"]`))
+        ownedBy(root, found);
+      for (const element of unownedElements()) {
+        if (ownerOf(element).component?.name === name) take(found, element);
+      }
+      pool = [...found];
+      pools.set(name, pool);
+    }
+    return pool;
+  };
+
+  return {
+    resolve(anchor: Anchor): Resolved {
+      const pool = new Set<Element>();
+      explicitHits(anchor, pool);
+      for (const element of anchor.component?.name ? ownedByName(anchor.component.name) : []) {
+        if (pool.size >= MAX_ELEMENTS) break;
+        pool.add(element);
+      }
+      const inside = (root: Candidate) => {
+        const start = elements.get(root.key);
+        if (!start) return [];
+        const found = new Set<Element>([start]);
+        for (const element of start.querySelectorAll("*")) {
+          if (found.size >= MAX_ELEMENTS) break;
+          if (!anchor.role || roleFor(element) === anchor.role) take(found, element);
+        }
+        return [...found].map(candidateOf);
+      };
+      const resolution = resolveAnchor(anchor, [...pool].map(candidateOf), inside);
+      return {
+        resolution,
+        element: resolution.key ? (elements.get(resolution.key) ?? null) : null,
+      };
+    },
+  };
+}
+
+export function resolveInDocument(anchor: Anchor, route = window.location.pathname): Resolved {
+  return createResolver(route).resolve(anchor);
+}
+
+export function elementAt(x: number, y: number) {
+  const root = document.getElementById("cs-root");
+  for (const element of document.elementsFromPoint(x, y)) {
+    if (element === document.body || element === document.documentElement) continue;
+    if (root && (element === root || root.contains(element))) continue;
+    const tag = element.tagName;
+    if (tag === "SCRIPT" || tag === "STYLE") continue;
+    return element;
+  }
+  return null;
+}
+
+export function describeElement(element: Element) {
+  const name = ownership(element).component?.name;
+  const label = labelFor(element);
+  if (name && label) return `${name} — ${label}`;
+  return name || label || element.tagName.toLowerCase();
+}