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

package/src/runtime/placement.ts

@@ -0,0 +1,336 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createResolver, type Resolved } from "./capture.js";
+import type { Thread } from "./client.js";
+import type { PlacedStatus } from "./format.js";
+import { whenIdle, type IdleDeadline } from "./idle.js";
+import type { Here } from "./screen.js";
+import { sketchBox } from "./sketch.js";
+
+export type Box = { top: number; left: number; width: number; height: number };
+/** `box` is the anchored element's box, set while the thread is placed. */
+export type Placed = {
+  thread: Thread;
+  status: PlacedStatus;
+  top?: number;
+  left?: number;
+  box?: Box;
+};
+
+/** Above this many elements, the page is only watched with a MutationObserver while the comments panel is open. */
+const LARGE_PAGE_ELEMENTS = 3000;
+/** A resolve someone is waiting on (panel opened, page or threads changed) starts within this many ms. */
+const URGENT_MS = 100;
+/** A resolve after the page changed underneath starts within this many ms. */
+const BACKGROUND_MS = 1000;
+/** Changes are batched this long before anchors are resolved again. */
+const SETTLE_MS = 150;
+/** Resolving may run this long per slice even when the page never goes idle and the slice was forced by its timeout. */
+const SLICE_MS = 8;
+/** Without a MutationObserver, anchors are re-checked this often while pins are on screen. */
+const RECHECK_MS = 10_000;
+/** Attributes that can change which element an anchor resolves to, or whether it counts as hidden. */
+const RESOLVE_ATTRIBUTES = [
+  "data-cs-cmp",
+  "data-cs-file",
+  "data-cs-anchor",
+  "data-testid",
+  "data-test",
+  "id",
+  "role",
+  "aria-label",
+  "aria-labelledby",
+  "aria-hidden",
+  "hidden",
+  "open",
+  "type",
+  "placeholder",
+  "alt",
+];
+/** Attributes that only move or resize elements. */
+const LAYOUT_ATTRIBUTES = ["class", "style"];
+
+export function overlayBounds(host: HTMLElement) {
+  if (host !== document.body) return { width: host.clientWidth, height: host.clientHeight };
+  const view = window.visualViewport;
+  return view
+    ? { width: view.width, height: view.height }
+    : { width: window.innerWidth, height: window.innerHeight };
+}
+
+function overlayHost() {
+  const dialogs = [...document.querySelectorAll("dialog")].filter(
+    (node): node is HTMLDialogElement =>
+      node instanceof HTMLDialogElement && node.open && !node.closest("#cs-root"),
+  );
+  return dialogs.at(-1) ?? document.body;
+}
+
+export function placeAgainst(element: Element, host: HTMLElement): Box | null {
+  const rect = element.getBoundingClientRect();
+  if (rect.width < 1 && rect.height < 1) return null;
+  if (host === document.body)
+    return { top: rect.top, left: rect.left, width: rect.width, height: rect.height };
+  const hostRect = host.getBoundingClientRect();
+  return {
+    top: rect.top - hostRect.top + host.scrollTop,
+    left: rect.left - hostRect.left + host.scrollLeft,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+function sameBoxes(a: Map<string, Box | null>, b: Map<string, Box | null>) {
+  if (a.size !== b.size) return false;
+  for (const [id, box] of a) {
+    const other = b.get(id);
+    if (box === other) continue;
+    if (
+      !box ||
+      !other ||
+      box.top !== other.top ||
+      box.left !== other.left ||
+      box.width !== other.width ||
+      box.height !== other.height
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function sameResolved(a: Map<string, Resolved>, b: Map<string, Resolved>) {
+  if (a.size !== b.size) return false;
+  for (const [id, { resolution, element }] of a) {
+    const other = b.get(id);
+    if (!other || other.element !== element || other.resolution.status !== resolution.status)
+      return false;
+  }
+  return true;
+}
+
+/**
+ * The open <dialog> the toolbar renders inside, since a modal's top layer covers everything else, or <body>.
+ * Instead of a MutationObserver on the whole page: showModal() moves focus into the dialog synchronously, so
+ * focusin moves the toolbar before the click that opened it returns; toggle/close cover the rest, and clicks and
+ * keys re-check once their handlers have run.
+ */
+export function useOverlayHost(enabled: boolean): HTMLElement | null {
+  const [host, setHost] = useState<HTMLElement | null>(null);
+  useEffect(() => {
+    if (!enabled) return;
+    let timer = 0;
+    const sync = () => setHost(overlayHost());
+    const afterHandlers = () => {
+      window.clearTimeout(timer);
+      timer = window.setTimeout(sync, 0);
+    };
+    sync();
+    const documentEvents = ["focusin", "toggle", "close"];
+    const windowEvents = ["pointerup", "keyup"];
+    for (const type of documentEvents) document.addEventListener(type, sync, true);
+    for (const type of windowEvents)
+      window.addEventListener(type, afterHandlers, { capture: true, passive: true });
+    return () => {
+      window.clearTimeout(timer);
+      for (const type of documentEvents) document.removeEventListener(type, sync, true);
+      for (const type of windowEvents) window.removeEventListener(type, afterHandlers, true);
+    };
+  }, [enabled]);
+  return host;
+}
+
+type View = { key: string; resolved: Map<string, Resolved>; boxes: Map<string, Box | null> };
+
+/**
+ * Where each thread's anchor is on this page. Anchors are resolved only while `active` (the panel is open or this
+ * page's pins are shown) and the tab is visible, only for open threads on this screen, in idle-time slices. The page
+ * is watched with a MutationObserver only while the panel is open or the page is small; otherwise clicks, keys,
+ * focus and a slow re-check trigger re-resolves. Scrolling and resizing only re-measure elements already found.
+ */
+export function usePlacement({
+  threads,
+  here,
+  host,
+  active,
+  panelOpen,
+  visible,
+}: {
+  threads: Thread[];
+  here: Here;
+  host: HTMLElement;
+  active: boolean;
+  panelOpen: boolean;
+  visible: boolean;
+}) {
+  const [view, setView] = useState<View>(() => ({
+    key: here.key,
+    resolved: new Map(),
+    boxes: new Map(),
+  }));
+  const elements = useRef(new Map<string, Element>());
+
+  useEffect(() => {
+    if (!active || !visible) return;
+    let cancelPass: (() => void) | null = null;
+    let dirty = false;
+    let settle = 0;
+    let frame = 0;
+    let recheck = 0;
+
+    const measure = () => {
+      const boxes = new Map<string, Box | null>();
+      let lost = false;
+      for (const [id, element] of elements.current) {
+        if (!element.isConnected) lost = true;
+        boxes.set(id, element.isConnected ? placeAgainst(element, host) : null);
+      }
+      return { boxes, lost };
+    };
+    const reposition = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => {
+        const { boxes, lost } = measure();
+        setView((current) => (sameBoxes(current.boxes, boxes) ? current : { ...current, boxes }));
+        if (lost) schedule();
+      });
+    };
+    const pass = (timeout: number) => {
+      const queue = threads.filter((thread) => thread.status === "open" && here.has(thread));
+      const resolved = new Map<string, Resolved>();
+      let index = 0;
+      const slice = (deadline: IdleDeadline) => {
+        if (index === 0) dirty = false;
+        const started = performance.now();
+        const resolver = createResolver(here.route);
+        while (index < queue.length) {
+          const thread = queue[index];
+          index += 1;
+          if (!thread) break;
+          resolved.set(thread.id, resolver.resolve(thread.anchor));
+          if (deadline.timeRemaining() <= 1 && performance.now() - started >= SLICE_MS) break;
+        }
+        if (index < queue.length) {
+          cancelPass = whenIdle(slice, timeout);
+          return;
+        }
+        cancelPass = null;
+        elements.current = new Map();
+        for (const [id, { resolution, element }] of resolved) {
+          if (element && (resolution.status === "pinned" || resolution.status === "drifted"))
+            elements.current.set(id, element);
+        }
+        const { boxes } = measure();
+        setView((current) =>
+          current.key === here.key &&
+          sameResolved(current.resolved, resolved) &&
+          sameBoxes(current.boxes, boxes)
+            ? current
+            : { key: here.key, resolved, boxes },
+        );
+        watch();
+        if (dirty) schedule();
+      };
+      cancelPass = whenIdle(slice, timeout);
+    };
+    const schedule = () => {
+      if (cancelPass) {
+        dirty = true;
+        return;
+      }
+      window.clearTimeout(settle);
+      settle = window.setTimeout(() => pass(BACKGROUND_MS), SETTLE_MS);
+    };
+    const onMutations = (records: MutationRecord[]) => {
+      const toolbar = document.getElementById("cs-root");
+      let move = false;
+      for (const record of records) {
+        if (toolbar?.contains(record.target)) continue;
+        if (
+          record.type === "attributes" &&
+          LAYOUT_ATTRIBUTES.includes(record.attributeName ?? "")
+        ) {
+          move = true;
+          continue;
+        }
+        schedule();
+        return;
+      }
+      if (move) reposition();
+    };
+    const watch = () => {
+      const large = !panelOpen && document.getElementsByTagName("*").length > LARGE_PAGE_ELEMENTS;
+      if (large && !recheck) recheck = window.setInterval(schedule, RECHECK_MS);
+      if (!large && recheck) {
+        window.clearInterval(recheck);
+        recheck = 0;
+      }
+    };
+    const observer = new MutationObserver(onMutations);
+    const watchingAll =
+      panelOpen || document.getElementsByTagName("*").length <= LARGE_PAGE_ELEMENTS;
+    if (watchingAll) {
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: [...RESOLVE_ATTRIBUTES, ...LAYOUT_ATTRIBUTES],
+      });
+    } else if (!recheck) {
+      recheck = window.setInterval(schedule, RECHECK_MS);
+    }
+    const onInteraction = (event: Event) => {
+      if (!(event.target instanceof Element && event.target.closest("#cs-root"))) schedule();
+    };
+    const resizes = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(reposition);
+    resizes?.observe(document.documentElement);
+    const passive = { capture: true, passive: true };
+    window.addEventListener("scroll", reposition, passive);
+    window.addEventListener("resize", reposition, passive);
+    window.addEventListener("pointerup", onInteraction, passive);
+    window.addEventListener("keyup", onInteraction, passive);
+    document.addEventListener("focusin", onInteraction, true);
+    pass(URGENT_MS);
+    watch();
+    return () => {
+      cancelPass?.();
+      window.clearTimeout(settle);
+      window.clearInterval(recheck);
+      cancelAnimationFrame(frame);
+      observer.disconnect();
+      resizes?.disconnect();
+      window.removeEventListener("scroll", reposition, true);
+      window.removeEventListener("resize", reposition, true);
+      window.removeEventListener("pointerup", onInteraction, true);
+      window.removeEventListener("keyup", onInteraction, true);
+      document.removeEventListener("focusin", onInteraction, true);
+    };
+  }, [active, here, host, panelOpen, threads, visible]);
+
+  const placed = useMemo(
+    () =>
+      threads.map((thread): Placed => {
+        if (thread.status === "resolved") return { thread, status: "resolved" };
+        if (!here.has(thread)) return { thread, status: "unavailable" };
+        const found = view.key === here.key ? view.resolved.get(thread.id) : undefined;
+        if (!found) return { thread, status: "pending" };
+        const { status } = found.resolution;
+        if (status !== "pinned" && status !== "drifted") return { thread, status };
+        const box = view.boxes.get(thread.id);
+        if (!box) return { thread, status: "hidden" };
+        // A drawing's pin sits at the drawing's top-right corner, not the element's.
+        const ink = thread.anchor.sketch ? sketchBox(thread.anchor.sketch) : null;
+        return ink
+          ? { thread, status, top: box.top + ink.top, left: box.left + ink.right, box }
+          : { thread, status, top: box.top, left: box.left + box.width, box };
+      }),
+    [here, threads, view],
+  );
+
+  /** The element a thread was last found on, while it's still on the page. */
+  const elementFor = useCallback((threadId: string) => {
+    const element = elements.current.get(threadId);
+    return element?.isConnected ? element : null;
+  }, []);
+
+  return { placed, elementFor };
+}