@blocksdiy/react-common 1.70.2 → 1.71.1

package/dist/comments/pin-view.js

@@ -0,0 +1,248 @@
+import { intersectRects } from "./layout.js";
+const PIN_SIZE = 28;
+/** What each face after the first adds to a pin's width: a face, less the overlap. */
+const PIN_FACE_STEP = 14;
+/** How far a pin keeps inside the window when its point is near an edge. */
+const PIN_EDGE_MARGIN = 4;
+/**
+ * The gap between a pin (or a new comment's point) and its panel: room for the open pin's glow (7px)
+ * and its growth (110%, from its pointed corner), with air past them.
+ */
+const PANEL_GAP = 20;
+/**
+ * The height a panel is given room for while its own height isn't known (`panelHeight`), the window
+ * allowing: its header, its comments' minimum and a composer at its tallest. In a short window the
+ * panel slides along the pin's side for it.
+ */
+const PANEL_MIN_ROOM = 384;
+/** Faces a pin shows before "+N". */
+const PIN_FACES_MAX = 3;
+/** A pin's width: one face fills it, and each more face (or "+N") adds what shows past the overlap. */
+export const pinWidth = (faceCount) => PIN_SIZE + Math.max(0, faceCount - 1) * PIN_FACE_STEP;
+/** The gap between what a comment is on (or its pin) and a panel above or below it. */
+const TARGET_GAP = 8;
+/**
+ * Where the panel goes by a pin `width` wide whose pointed corner is on `point` (a new comment's:
+ * the one-face pin it becomes), keeping clear of `target` where it can. The pin's box is worked out
+ * as `Pin` places it: above the point and toward the line's end, slid back inside the window at its
+ * edges. Where it stands is `side` (else as `panelSide` opens one): past the pin's end side or
+ * before its start, level with the pin's top (`down`) or with its bottom (`up`), or further along
+ * when that leaves it less than `PANEL_MIN_ROOM`; or below or above the target, its end edge level
+ * with the pin's. It is never taller than the room it has, so its replies scroll and its composer
+ * stays on screen. With a `shift` it then moves by it, keeping its height: it goes out of the
+ * window with its pin.
+ */
+export const panelPosition = (point, width, panelWidth, { viewport: frame, shift, side, target, panelHeight }) => {
+    const geometry = besidePin(point, width, panelWidth, frame, target, panelHeight);
+    const taken = side ?? panelSide(point, width, panelWidth, undefined, frame, target, panelHeight);
+    const box = panelBox(taken, geometry);
+    const dx = shift?.x ?? 0;
+    const dy = shift?.y ?? 0;
+    const hangsUp = taken.place === "above" || (taken.place !== "below" && taken.block === "up");
+    if (hangsUp) {
+        return {
+            left: box.left + dx,
+            bottom: frame.height - box.bottom - dy,
+            width: panelWidth,
+            maxHeight: box.bottom - geometry.margin,
+        };
+    }
+    return {
+        left: box.left + dx,
+        top: box.top + dy,
+        width: panelWidth,
+        maxHeight: frame.height - box.top - geometry.margin,
+    };
+};
+/**
+ * How far a panel's place may run short of the room it wants (its height down the window, its
+ * width across), or cover what the comment is on, before it moves: the two switch points are this
+ * far apart at least, so a page scrolled back and forth by a few pixels never makes it flap.
+ */
+const PANEL_SIDE_SLACK = 48;
+/**
+ * Where a panel stands by its pin (`panelPosition`'s `side`), sticky. As it opens: level with the
+ * pin's top, hanging down, when it fits between there and the window's bottom margin; hanging up
+ * from the pin's bottom only when it doesn't and does fit above (`block`); and the first place
+ * (`PanelSide`) that fits inside the window's margins (a panel below or above the target with the
+ * room it wants) without covering `target` (`ThreadLayout.target`), else before the pin's start.
+ * The room it wants is `panelHeight` when known, else `PANEL_MIN_ROOM`. Then, given where it
+ * stood (`previous`): hanging down and standing past the pin's end side are where it rests, kept
+ * while they fit within `PANEL_SIDE_SLACK` (a panel kept within the slack slides along for room,
+ * still beside the pin); any other side or place is held only until the resting one fits again
+ * with no slack, then kept while it fits within the slack. The two switch points are the slack
+ * apart, so a page scrolled back and forth by a few pixels never makes it flap. A `previous`
+ * chosen before the height was known is not kept once it is (`isMeasured`). Without a target only
+ * the places beside the pin are taken.
+ */
+export const panelSide = (point, width, panelWidth, previous, viewport, target, panelHeight) => {
+    const geometry = besidePin(point, width, panelWidth, viewport, target, panelHeight);
+    const { margin, pin, room } = geometry;
+    const isMeasured = panelHeight !== undefined;
+    const kept = previous && (previous.isMeasured || !isMeasured) ? previous : undefined;
+    const roomDown = viewport.height - margin - pin.top;
+    const roomUp = pin.bottom - margin;
+    // Down is where it rests: it hangs up only while down is short by more than the slack, and comes
+    // back down as soon as down fits.
+    const block = kept?.block === "down"
+        ? roomDown < room - PANEL_SIDE_SLACK && roomUp >= room
+            ? "up"
+            : "down"
+        : kept?.block === "up"
+            ? roomDown >= room
+                ? "down"
+                : "up"
+            : roomDown < room && roomUp >= room
+                ? "up"
+                : "down";
+    const otherBlock = block === "down" ? "up" : "down";
+    const order = [
+        { block, place: "end" },
+        { block: otherBlock, place: "end" },
+        { block, place: "below" },
+        { block, place: "above" },
+        { block, place: "start" },
+    ];
+    if (kept) {
+        // Beside the pin is where it rests too: a panel below, above or over the target goes back
+        // there as soon as it fits; one beside it stays while it fits within the slack.
+        const backBeside = kept.place === "end" ? undefined : order.slice(0, 2).find((candidate) => fits(candidate, geometry, 0));
+        if (backBeside) {
+            return { ...backBeside, isMeasured };
+        }
+        if (fits({ block, place: kept.place }, geometry, PANEL_SIDE_SLACK)) {
+            return { block, place: kept.place, isMeasured };
+        }
+    }
+    const side = order.find((candidate) => fits(candidate, geometry, 0)) ?? { block, place: kept?.place ?? "start" };
+    return { ...side, isMeasured };
+};
+/**
+ * The pin's box as `Pin` places it, where a panel would go on each side of it, and what the panel
+ * keeps clear of: the target and the pin together.
+ */
+const besidePin = (point, width, panelWidth, viewport, target, panelHeight) => {
+    const margin = 8;
+    const pinLeft = viewport.isRtl
+        ? Math.max(PIN_EDGE_MARGIN, point.x - width)
+        : Math.min(point.x, viewport.width - PIN_EDGE_MARGIN - width);
+    const pinRight = pinLeft + width;
+    const pinTop = Math.max(PIN_EDGE_MARGIN, point.y - PIN_SIZE);
+    const pin = { left: pinLeft, right: pinRight, top: pinTop, bottom: pinTop + PIN_SIZE };
+    return {
+        margin,
+        panelWidth,
+        viewport,
+        pin,
+        target,
+        /** The target and the pin together: what a panel below or above them stands clear of. */
+        avoid: target
+            ? {
+                top: Math.min(target.top, pin.top),
+                left: Math.min(target.left, pin.left),
+                right: Math.max(target.right, pin.right),
+                bottom: Math.max(target.bottom, pin.bottom),
+            }
+            : null,
+        pastEnd: viewport.isRtl ? pinLeft - PANEL_GAP - panelWidth : pinRight + PANEL_GAP,
+        beforeStart: viewport.isRtl ? pinRight + PANEL_GAP : pinLeft - PANEL_GAP - panelWidth,
+        /** A panel's left edge with its end edge level with the pin's. */
+        endAligned: viewport.isRtl ? pinLeft : pinRight - panelWidth,
+        room: Math.min(panelHeight ?? PANEL_MIN_ROOM, viewport.height - 2 * margin),
+    };
+};
+/** The panel's box at `side`, as tall as the room it wants, kept inside the window's margins. */
+const panelBox = (side, geometry) => {
+    const { margin, panelWidth, viewport, pin, room } = geometry;
+    const avoid = geometry.avoid ?? pin;
+    // The lowest top that still leaves the panel its room.
+    const farthest = viewport.height - margin - room;
+    const inMargins = (left) => Math.min(Math.max(margin, left), viewport.width - margin - panelWidth);
+    const box = (left, top) => ({
+        left,
+        right: left + panelWidth,
+        top,
+        bottom: top + room,
+    });
+    switch (side.place) {
+        case "below":
+            return box(inMargins(geometry.endAligned), Math.max(margin, Math.min(avoid.bottom + TARGET_GAP, farthest)));
+        case "above":
+            return box(inMargins(geometry.endAligned), Math.min(viewport.height - margin, Math.max(avoid.top - TARGET_GAP, margin + room)) - room);
+        default: {
+            const left = inMargins(side.place === "end" ? geometry.pastEnd : geometry.beforeStart);
+            if (side.block === "up") {
+                const bottom = Math.max(margin, Math.min(viewport.height - pin.bottom, farthest));
+                return box(left, viewport.height - bottom - room);
+            }
+            return box(left, Math.max(margin, Math.min(pin.top, farthest)));
+        }
+    }
+};
+/** How far two boxes overlap: the lesser of their overlaps across and down, zero when apart. */
+const overlapDepth = (a, b) => {
+    const overlap = intersectRects(a, b);
+    return overlap ? Math.min(overlap.right - overlap.left, overlap.bottom - overlap.top) : 0;
+};
+/**
+ * Whether a panel at `side` fits within `slack`: beside the pin, across the window's margins;
+ * below or above a target, with the room it wants (a panel short of room slides over the target);
+ * and, but for the last resort (`start`), covering the target and its pin (each on its own, not
+ * the empty corner between them) by no more than `slack`.
+ */
+const fits = (side, geometry, slack) => {
+    const { target, pin } = geometry;
+    if (side.place === "start") {
+        return fitsAt(geometry.beforeStart, geometry, slack);
+    }
+    if (side.place === "end" ? !fitsAt(geometry.pastEnd, geometry, slack) : !target) {
+        return false;
+    }
+    if (!target) {
+        return true;
+    }
+    const box = panelBox(side, geometry);
+    return overlapDepth(box, target) <= slack && overlapDepth(box, pin) <= slack;
+};
+/** Whether a panel whose left edge is at `left` fits across the window, within `slack` past its margins. */
+const fitsAt = (left, geometry, slack) => left >= geometry.margin - slack && left + geometry.panelWidth <= geometry.viewport.width - geometry.margin + slack;
+export const participantKey = (participant) => participant.type === "user" ? `u${participant.userId}` : `a${participant.agentId}`;
+/**
+ * Everyone in a pin's threads, by first comment, each once: up to three as faces, the working
+ * agent's last (on top, so its spinner badge shows), and how many more there are, as "+N".
+ */
+export const pinParticipants = (threads, workingAgentId) => {
+    const seen = new Set();
+    const others = threads
+        // Participants count only comments still there: a thread whose comments were all deleted
+        // shows its author.
+        .flatMap((thread) => thread.participants.length > 0 ? thread.participants : [{ type: "user", userId: thread.createdByUserId }])
+        .filter((participant) => {
+        const key = participantKey(participant);
+        const isNew = !seen.has(key) && !(participant.type === "agent" && participant.agentId === workingAgentId);
+        seen.add(key);
+        return isNew;
+    });
+    const shown = workingAgentId
+        ? [...others.slice(0, PIN_FACES_MAX - 1), { type: "agent", agentId: workingAgentId }]
+        : others.slice(0, PIN_FACES_MAX);
+    return {
+        shown,
+        moreCount: others.length + (workingAgentId ? 1 : 0) - shown.length,
+    };
+};
+/** How far a panel with nothing to stand beside keeps from the window's bottom and end edges. */
+const CORNER_INSET = 16;
+/**
+ * Where a pin `width` wide goes for a panel with nothing on the page to stand beside (a thread
+ * opened from its link whose element isn't there): so that `panelPosition` from it puts the panel
+ * in the window's bottom end corner, 16px in, with the pin just past the panel's start side, its
+ * bottom level with the panel's.
+ */
+export const cornerPoint = (viewport, width, panelWidth) => {
+    const fromEnd = CORNER_INSET + panelWidth + PANEL_GAP + width;
+    return {
+        x: viewport.isRtl ? fromEnd : viewport.width - fromEnd,
+        y: viewport.height - CORNER_INSET,
+    };
+};

package/dist/comments/pins.d.ts

@@ -0,0 +1,126 @@
+import { type AnchorState, resolveAnchor } from "./anchor.js";
+import { type Rect } from "./layout.js";
+import type { CommentAnchor } from "./types.js";
+/** How far a pin keeps from the viewport's edges. */
+export declare const PIN_EDGE_MARGIN = 12;
+export interface PinPoint {
+    x: number;
+    y: number;
+}
+/**
+ * The pin's point, in viewport coordinates: the top-end corner of what the comment is on (top-right
+ * on a left-to-right page, top-left with `isRtl`; without it, as the page reads), so the pin,
+ * standing above its point and past the end side (`Pin`), stays outside it.
+ * - A quote: its first line's corner (`firstLine`), the pin above the words, never over them;
+ *   given only `lastLine` (a copy from before `firstLine`), that line's corner.
+ * - An element: its box's corner. Where it was clicked (`point`, stored on the anchor) doesn't
+ *   place the pin; it is taken so a copy that passes it keeps working.
+ */
+export declare const pinPoint: (target: {
+    kind: "quote";
+    lastLine: Rect;
+    firstLine?: Rect;
+    isRtl?: boolean;
+} | {
+    kind: "element";
+    rect: Rect;
+    point?: {
+        x: number;
+        y: number;
+    };
+    isRtl?: boolean;
+}) => PinPoint;
+/** `point` kept `margin` inside the viewport. */
+export declare const keepInViewport: (point: PinPoint, viewport: {
+    width: number;
+    height: number;
+}, margin?: number) => {
+    x: number;
+    y: number;
+};
+export interface PinGroup<T> {
+    key: string;
+    point: PinPoint;
+    items: T[];
+}
+/** Pins on the same element become one group, at the first one's point (items in input order). */
+export declare const groupPins: <T>(pins: readonly {
+    key: string;
+    point: PinPoint;
+    item: T;
+}[]) => PinGroup<T>[];
+export interface ThreadLayout {
+    state: AnchorState;
+    element: HTMLElement | null;
+    /** Where the pin goes; null when there is nothing on screen to pin to (scrolled away, covered, missing). */
+    point: PinPoint | null;
+    /** Threads with the same key point at the same element. */
+    groupKey: string | null;
+    /** What the anchored text says now, when it changed. */
+    currentText?: string;
+    /**
+     * What the comment is on, in window coordinates, for its panel to keep clear of: the quote's
+     * lines' bounding box, else the element's box, cut to the part of it in view (to the window's
+     * edge, a line with no height or width, while it is out of view). Absent when the element is
+     * missing, and on a platform from before it.
+     */
+    target?: Rect;
+    /**
+     * Why `point` is null though the element is on the page, and where its pin would go: what an
+     * open thread needs to keep its pin and panel with the element. Absent while the pin shows, when
+     * the element is missing, and on a platform from before it.
+     * - `offscreen`: the element is outside the window. `point` is where the pin stood as the element
+     *   left (kept inside the window, as a shown pin is), and `shift` is how far the element has gone
+     *   past the window's edge since: the pin and its panel move by it, so they slide out with the
+     *   page instead of jumping or staying at the edge.
+     * - `clipped`: the element's box is in the window but a scroll container hides it (or it has no
+     *   box): nothing of it can be seen, and nothing should float over what is there instead.
+     * - `covered`: it is in view under other UI (a dialog, a menu). `shift` is zero then and for
+     *   `clipped`.
+     */
+    hidden?: {
+        by: "offscreen" | "clipped" | "covered";
+        point: PinPoint;
+        shift: PinPoint;
+    };
+}
+/**
+ * The comments' own layer (pins, threads) marks its root with this attribute: what it draws over an
+ * element doesn't hide the element. Other ignored UI (the agent chat's panel) does.
+ */
+export declare const COMMENTS_LAYER_ATTRIBUTE = "data-blocks-comments-layer";
+/**
+ * How far `box` lies past the window's edges: negative past the start (left, top), positive past
+ * the end, zero along an axis where it overlaps the window.
+ */
+export declare const pastWindow: (box: Rect, viewport: {
+    width: number;
+    height: number;
+}) => PinPoint;
+/** Lays out one anchor whose element is known, on a page that reads right to left with `isRtl`. */
+export declare const layoutAnchor: (resolved: ReturnType<typeof resolveAnchor>, isRtl: boolean) => ThreadLayout;
+/**
+ * Where a new comment's pin goes and what its panel keeps clear of, as it is picked (`usePagePick`'s
+ * `onPick`): the same corner and target as a thread on it gets (`layoutAnchor`), its quote found in
+ * `element`. Reads the page; call it from the pick, not while rendering.
+ */
+export declare const pickPlacement: (anchor: CommentAnchor, element: HTMLElement, isRtl?: boolean) => {
+    point: PinPoint;
+    target: Rect;
+};
+/**
+ * Finds an anchor again, re-checking only its text while its element is still in the page and
+ * still inside the same row. One found on the row itself is found anew each time: what the row
+ * must say depends on how the thread came to be on it (`resolveAnchor`).
+ */
+export declare const resolveAnchorCached: (anchor: CommentAnchor) => import("./anchor.js").ResolvedAnchor;
+/**
+ * Where each thread is on the page now, re-measured at most once per frame while `isActive`, on a
+ * page that reads right to left with `isRtl` (the caller's window as it read it; read here on each
+ * render when absent).
+ */
+export declare const useCommentPins: (anchors: readonly {
+    id: string | number;
+    anchor: CommentAnchor;
+}[], isActive: boolean, isRtl?: boolean) => ReadonlyMap<string | number, ThreadLayout>;
+//# sourceMappingURL=pins.d.ts.map

package/dist/comments/pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.d.ts","sourceRoot":"","sources":["../../src/comments/pins.ts"],"names":[],"mappings":"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"}

package/dist/comments/pins.js

@@ -0,0 +1,218 @@
+import { useMemo } from "react";
+import { checkText, findAnchorItemElement, resolveAnchor } from "./anchor.js";
+import { clipRectsOf, toRect, usePageLayoutTick, visiblePart } from "./layout.js";
+/**
+ * Where each thread's pin goes on the page as it is now. Never stored: worked out from the anchor
+ * every time the page moves, so a pin follows its element across screen sizes, re-sorted lists and
+ * scrolling.
+ */
+/** The page's direction, as the comments read it (left to right with no page). */
+const isPageRtl = () => typeof document !== "undefined" && getComputedStyle(document.documentElement).direction === "rtl";
+/** How far a pin keeps from the viewport's edges. */
+export const PIN_EDGE_MARGIN = 12;
+/**
+ * The pin's point, in viewport coordinates: the top-end corner of what the comment is on (top-right
+ * on a left-to-right page, top-left with `isRtl`; without it, as the page reads), so the pin,
+ * standing above its point and past the end side (`Pin`), stays outside it.
+ * - A quote: its first line's corner (`firstLine`), the pin above the words, never over them;
+ *   given only `lastLine` (a copy from before `firstLine`), that line's corner.
+ * - An element: its box's corner. Where it was clicked (`point`, stored on the anchor) doesn't
+ *   place the pin; it is taken so a copy that passes it keeps working.
+ */
+export const pinPoint = (target) => {
+    const box = target.kind === "quote" ? (target.firstLine ?? target.lastLine) : target.rect;
+    const isRtl = target.isRtl ?? isPageRtl();
+    return { x: isRtl ? box.left : box.right, y: box.top };
+};
+/** `point` kept `margin` inside the viewport. */
+export const keepInViewport = (point, viewport, margin = PIN_EDGE_MARGIN) => ({
+    x: Math.min(Math.max(point.x, margin), Math.max(margin, viewport.width - margin)),
+    y: Math.min(Math.max(point.y, margin), Math.max(margin, viewport.height - margin)),
+});
+/** Pins on the same element become one group, at the first one's point (items in input order). */
+export const groupPins = (pins) => {
+    const groups = new Map();
+    for (const pin of pins) {
+        const group = groups.get(pin.key);
+        if (group) {
+            group.items.push(pin.item);
+        }
+        else {
+            groups.set(pin.key, { key: pin.key, point: pin.point, items: [pin.item] });
+        }
+    }
+    return [...groups.values()];
+};
+const HIDDEN = { point: null, groupKey: null };
+/**
+ * The comments' own layer (pins, threads) marks its root with this attribute: what it draws over an
+ * element doesn't hide the element. Other ignored UI (the agent chat's panel) does.
+ */
+export const COMMENTS_LAYER_ATTRIBUTE = "data-blocks-comments-layer";
+/** Whether the element can be seen at `visible`'s centre, or only the comments' own layer is over it. */
+const isUncovered = (element, visible) => {
+    const hit = document.elementFromPoint((visible.left + visible.right) / 2, (visible.top + visible.bottom) / 2);
+    return !hit || element.contains(hit) || hit.closest(`[${COMMENTS_LAYER_ATTRIBUTE}]`) !== null;
+};
+const elementKeys = new WeakMap();
+let nextElementKey = 0;
+const keyOf = (element) => {
+    let key = elementKeys.get(element);
+    if (!key) {
+        key = `el-${++nextElementKey}`;
+        elementKeys.set(element, key);
+    }
+    return key;
+};
+/**
+ * How far `box` lies past the window's edges: negative past the start (left, top), positive past
+ * the end, zero along an axis where it overlaps the window.
+ */
+export const pastWindow = (box, viewport) => ({
+    x: Math.min(0, box.right) + Math.max(0, box.left - viewport.width),
+    y: Math.min(0, box.bottom) + Math.max(0, box.top - viewport.height),
+});
+const NO_SHIFT = { x: 0, y: 0 };
+/** A scroll container's box, each edge at or past the window's taken on without end. */
+const reachingWindowEdges = (clip, viewport) => ({
+    top: clip.top <= 0 ? -Infinity : clip.top,
+    left: clip.left <= 0 ? -Infinity : clip.left,
+    right: clip.right >= viewport.width ? Infinity : clip.right,
+    bottom: clip.bottom >= viewport.height ? Infinity : clip.bottom,
+});
+/** `rect` squeezed into `bounds`: each edge kept inside it (a line or a point at its edge when outside). */
+const clampRect = (rect, bounds) => {
+    const clampX = (x) => Math.min(Math.max(x, bounds.left), bounds.right);
+    const clampY = (y) => Math.min(Math.max(y, bounds.top), bounds.bottom);
+    return { top: clampY(rect.top), left: clampX(rect.left), right: clampX(rect.right), bottom: clampY(rect.bottom) };
+};
+/**
+ * A quote's line boxes (several to a line where it crosses inline elements): its first line (the
+ * boxes level with the first one, as one) and the box around them all.
+ */
+const quoteLines = (lines) => {
+    const first = lines[0];
+    const onFirstLine = lines.filter((line) => {
+        const middle = (line.top + line.bottom) / 2;
+        return middle >= first.top && middle <= first.bottom;
+    });
+    const around = (rects) => ({
+        top: Math.min(...rects.map((rect) => rect.top)),
+        left: Math.min(...rects.map((rect) => rect.left)),
+        right: Math.max(...rects.map((rect) => rect.right)),
+        bottom: Math.max(...rects.map((rect) => rect.bottom)),
+    });
+    return { firstLine: around(onFirstLine), bounds: around(lines) };
+};
+/**
+ * Where a comment's pin goes and what its panel keeps clear of, measured now: the top-end corner of
+ * its quote's first line, else of its element's box (`pinPoint`), kept on the part of the element in
+ * view and inside the window. A thread's pin (`layoutAnchor`) and a new comment's (`pickPlacement`)
+ * both come from here.
+ */
+const measure = (element, range, isRtl) => {
+    const box = toRect(element.getBoundingClientRect());
+    const clips = clipRectsOf(element);
+    const visible = visiblePart(box, clips);
+    const boxes = range
+        ? Array.from(range.getClientRects())
+            .filter((rect) => rect.width > 0 || rect.height > 0)
+            .map(toRect)
+        : [];
+    // A drag from just past a line's last letter leaves an empty box at that line's end: not where
+    // the words start, unless nothing else is there.
+    const wide = boxes.filter((rect) => rect.right > rect.left);
+    const lines = wide.length > 0 ? wide : boxes;
+    const quote = lines.length > 0 ? quoteLines(lines) : null;
+    const viewport = { width: window.innerWidth, height: window.innerHeight };
+    const corner = quote
+        ? pinPoint({ kind: "quote", firstLine: quote.firstLine, lastLine: lines.at(-1), isRtl })
+        : pinPoint({ kind: "element", rect: box, isRtl });
+    const shown = visible ?? clips[0];
+    const point = keepInViewport({
+        x: Math.min(Math.max(corner.x, shown.left), shown.right),
+        y: Math.min(Math.max(corner.y, shown.top), shown.bottom),
+    }, viewport);
+    return { box, clips, visible, viewport, point, target: clampRect(quote?.bounds ?? box, shown) };
+};
+/** Lays out one anchor whose element is known, on a page that reads right to left with `isRtl`. */
+export const layoutAnchor = (resolved, isRtl) => {
+    const { element, state, range, currentText } = resolved;
+    if (!element) {
+        return { state, element: null, currentText, ...HIDDEN };
+    }
+    const { box, clips, visible, viewport, point, target } = measure(element, range, isRtl);
+    if (!visible) {
+        // Off screen: only the window hides it. A scroll container's edge counts as the window's only
+        // where it reaches the window's edge (a page that scrolls in a full-window container); outside
+        // a container through an edge inside the window (below a fixed header, a list mid-page), it is
+        // clipped, and stays so once its box leaves the window too: its pin never pops back at the
+        // window's edge. So is an element with no box at all.
+        const [windowClip, ...containers] = clips;
+        const isBox = box.right > box.left && box.bottom > box.top;
+        const isOffscreen = isBox &&
+            !visiblePart(box, [windowClip]) &&
+            !!visiblePart(box, containers.map((clip) => reachingWindowEdges(clip, viewport)));
+        const hidden = isOffscreen
+            ? { by: "offscreen", point, shift: pastWindow(box, viewport) }
+            : { by: "clipped", point, shift: NO_SHIFT };
+        return { state, element, currentText, target, ...HIDDEN, hidden };
+    }
+    if (!isUncovered(element, visible)) {
+        return { state, element, currentText, target, ...HIDDEN, hidden: { by: "covered", point, shift: NO_SHIFT } };
+    }
+    return { state, element, currentText, target, point, groupKey: keyOf(element) };
+};
+/**
+ * Where a new comment's pin goes and what its panel keeps clear of, as it is picked (`usePagePick`'s
+ * `onPick`): the same corner and target as a thread on it gets (`layoutAnchor`), its quote found in
+ * `element`. Reads the page; call it from the pick, not while rendering.
+ */
+export const pickPlacement = (anchor, element, isRtl = isPageRtl()) => {
+    const { point, target } = measure(element, checkText(anchor, element).range, isRtl);
+    return { point, target };
+};
+/** The element each anchor was last found at: an anchor's object stays the same while its thread is unchanged. */
+const foundByAnchor = new WeakMap();
+/**
+ * Finds an anchor again, re-checking only its text while its element is still in the page and
+ * still inside the same row. One found on the row itself is found anew each time: what the row
+ * must say depends on how the thread came to be on it (`resolveAnchor`).
+ */
+export const resolveAnchorCached = (anchor) => {
+    const known = foundByAnchor.get(anchor);
+    const row = anchor.item ? findAnchorItemElement(anchor) : null;
+    const stillThere = known?.isConnected && (!anchor.item || (row !== known && row?.contains(known) === true));
+    const resolved = stillThere ? checkText(anchor, known) : resolveAnchor(anchor);
+    if (resolved.element) {
+        foundByAnchor.set(anchor, resolved.element);
+    }
+    else {
+        foundByAnchor.delete(anchor);
+    }
+    return resolved;
+};
+/**
+ * Where each thread is on the page now, re-measured at most once per frame while `isActive`, on a
+ * page that reads right to left with `isRtl` (the caller's window as it read it; read here on each
+ * render when absent).
+ */
+export const useCommentPins = (anchors, isActive, isRtl) => {
+    // Not for the React Compiler (app-render compiles this module): the memo's input is the page's
+    // layout, read through `tick`, which the compiler would drop from the deps as unused.
+    "use no memo";
+    const tick = usePageLayoutTick(isActive);
+    // A change of direction moves no tick: it is a dependency of its own.
+    const rtl = isRtl ?? (isActive && isPageRtl());
+    return useMemo(() => {
+        void tick;
+        const layouts = new Map();
+        if (!isActive || typeof document === "undefined") {
+            return layouts;
+        }
+        for (const { id, anchor } of anchors) {
+            layouts.set(id, layoutAnchor(resolveAnchorCached(anchor), rtl));
+        }
+        return layouts;
+    }, [anchors, isActive, tick, rtl]);
+};

package/dist/comments/text-pick.d.ts

@@ -0,0 +1,69 @@
+import { type Rect } from "./layout.js";
+/**
+ * Pointing at part of a text, as the picker does over text: the caret position under the pointer,
+ * the word around it, and the range a drag covers — clamped to the row it started in, so a quote
+ * never spans two records. The geometry is the browser's; what can be computed without it is pure
+ * (word bounds, hit tests, ordering) and tested on its own.
+ */
+/** A position in a text node: before the character at `offset`. */
+export interface TextPoint {
+    node: Text;
+    offset: number;
+}
+/** A position between nodes or characters, as a Range's boundary takes it. */
+export interface Boundary {
+    node: Node;
+    offset: number;
+}
+/** How far the pointer moves from a press on text before it is a drag, not a click. */
+export declare const DRAG_THRESHOLD_PX = 4;
+/**
+ * The word around `offset` in `text` — the one it is in, else the one ending right before it —
+ * as `[start, end)`; null over spaces and punctuation. Words in any script (`Intl.Segmenter`), a
+ * whitespace split where it is missing.
+ */
+export declare const wordBoundsAt: (text: string, offset: number, locale?: string) => {
+    start: number;
+    end: number;
+} | null;
+/** Whether `(x, y)` is on one of `rects`, with `slop` px around each. */
+export declare const isPointInRects: (x: number, y: number, rects: readonly Rect[], slop?: number) => boolean;
+/** Whether `a` comes after `b` in the document. */
+export declare const isAfter: (a: Boundary, b: Boundary) => boolean;
+/** The range between two positions, in document order. */
+export declare const rangeBetween: (doc: Document, a: Boundary, b: Boundary) => Range;
+/**
+ * What a drag that starts at `node` may cover: the record it is in (the nearest `itemAnchorProps`
+ * element), else the element a click there would pick. A quote never leaves it.
+ */
+export declare const dragRootOf: (node: Node) => Element | null;
+/** `point` kept inside `root`: a position past its end is its end, one before its start is its start. */
+export declare const clampToRoot: (root: Element, point: Boundary) => Boundary;
+/** The most characters a lookup measures to correct the browser's answer before keeping it. */
+export declare const CARET_SCAN_MAX = 256;
+/**
+ * The caret position the browser puts under `(x, y)`, when it is in a text node. Where a run reads
+ * the other way than its line (Latin words on a right-to-left page), the browser can answer at a
+ * run's edge with a position beside other characters, far from the pointer (Chrome: the line's
+ * end for the left half of the run's first letter, the run's start for the right half of its
+ * last): when neither character beside its answer is under the pointer, the one that is decides,
+ * found near the answer (`CARET_SCAN_MAX`), else the answer stands. Characters are what a reader
+ * sees as one (an emoji, a letter with its marks): a corrected position is never inside one.
+ */
+export declare const caretFromPoint: (doc: Document, x: number, y: number) => TextPoint | null;
+/**
+ * The text position under the pointer, only when the pointer is ON the text: the browser answers
+ * with the nearest text from anywhere in an element, so the characters beside the caret decide
+ * (a space between words counts, so the cursor doesn't flicker along a line). Null over empty
+ * space, in ignored UI or an editable field.
+ */
+export declare const textPointAt: (doc: Document, x: number, y: number) => TextPoint | null;
+/** The word under a text position, as a range: what the hover tints. */
+export declare const wordRangeAt: (doc: Document, point: TextPoint) => Range | null;
+/** Where the caret bar goes for a text position: the edge of the character beside it. */
+export declare const caretRectAt: (doc: Document, point: TextPoint) => {
+    x: number;
+    top: number;
+    bottom: number;
+} | null;
+//# sourceMappingURL=text-pick.d.ts.map