@blocksdiy/react-common 1.71.0 → 1.71.2

package/dist/comments/pin-view.d.ts

@@ -0,0 +1,107 @@
+import type * as React from "react";
+import { type Rect } from "./layout.js";
+import type { PinPoint } from "./pins.js";
+import type { CommentParticipantDto } from "./types.js";
+/** The window as a placement sees it: its layer's width (less a classic scrollbar), its height, its direction. */
+export interface PlacementViewport {
+    width: number;
+    height: number;
+    isRtl: boolean;
+}
+export interface PanelPositionOptions {
+    /**
+     * The window, read where the caller renders on each frame: a call the React Compiler caches on
+     * its arguments then never keeps a stale place after a resize, a zoom or a change of direction.
+     */
+    viewport: PlacementViewport;
+    /**
+     * How far the pin's element has gone past the window's edge (`ThreadLayout.hidden.shift`): the
+     * panel is placed as for `point`, where the pin stood as the element left, and moves with it.
+     */
+    shift?: PinPoint;
+    /**
+     * Where to stand (`panelSide`, kept per open panel): without it, as `panelSide` opens one.
+     */
+    side?: PanelSide;
+    /**
+     * What the comment is on (`ThreadLayout.target`, a new comment's `pickPlacement`), in the same
+     * coordinates as the point, before any shift: the panel keeps clear of it where it can
+     * (`panelSide`). Without it the panel goes beside the pin only.
+     */
+    target?: Rect;
+    /**
+     * The panel's height as last drawn, when the caller measured it (and its `maxHeight` didn't cut
+     * it): the room it wants. Without it, `PANEL_MIN_ROOM`.
+     */
+    panelHeight?: number;
+}
+/** A pin's width: one face fills it, and each more face (or "+N") adds what shows past the overlap. */
+export declare const pinWidth: (faceCount: number) => number;
+/**
+ * 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 declare const panelPosition: (point: PinPoint, width: number, panelWidth: number, { viewport: frame, shift, side, target, panelHeight }: PanelPositionOptions) => React.CSSProperties;
+/**
+ * Where a panel stands by its pin. `place`, in the order a panel tries them:
+ * - `end`: past the pin's end side (the right, or the left on a right-to-left page), level with it;
+ * - `below`, `above`: below or above what the comment is on (and its pin), its end edge level with
+ *   the pin's end edge;
+ * - `start`: before the pin's start side, level with it: over what the comment is on, the last
+ *   resort.
+ *
+ * `block`, beside the pin (`end`, `start`): `down` hangs it from the pin's top (its top level with
+ * the pin's), `up` above the pin's bottom (its bottom level with the pin's).
+ *
+ * `isMeasured`: chosen knowing the panel's own height (`panelHeight`). One chosen without it is
+ * chosen afresh once the height is known, so a panel's first, unmeasured frame doesn't decide
+ * where it stays.
+ */
+export interface PanelSide {
+    block: "up" | "down";
+    place: "end" | "below" | "above" | "start";
+    isMeasured?: boolean;
+}
+/**
+ * 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 declare const panelSide: (point: PinPoint, width: number, panelWidth: number, previous: PanelSide | undefined, viewport: PlacementViewport, target?: Rect, panelHeight?: number) => PanelSide;
+export declare const participantKey: (participant: CommentParticipantDto) => string;
+/**
+ * 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 declare const pinParticipants: (threads: readonly {
+    participants: readonly CommentParticipantDto[];
+    createdByUserId: number;
+}[], workingAgentId: string | null) => {
+    shown: CommentParticipantDto[];
+    moreCount: number;
+};
+/**
+ * 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 declare const cornerPoint: (viewport: PlacementViewport, width: number, panelWidth: number) => PinPoint;
+//# sourceMappingURL=pin-view.d.ts.map

package/dist/comments/pin-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pin-view.d.ts","sourceRoot":"","sources":["../../src/comments/pin-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,OAAO,EAAkB,KAAK,IAAI,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAQrD,kHAAkH;AAClH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC;IACd;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAqBD,uGAAuG;AACvG,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,WAA0D,CAAC;AAKrG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,QAAQ,EACf,OAAO,MAAM,EACb,YAAY,MAAM,EAClB,uDAAuD,oBAAoB,KAC1E,KAAK,CAAC,aAqBR,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,IAAI,GAAG,MAAM,CAAC;IACrB,KAAK,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IAC3C,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AASD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,GACpB,OAAO,QAAQ,EACf,OAAO,MAAM,EACb,YAAY,MAAM,EAClB,UAAU,SAAS,GAAG,SAAS,EAC/B,UAAU,iBAAiB,EAC3B,SAAS,IAAI,EACb,cAAc,MAAM,KACnB,SA2CF,CAAC;AA6GF,eAAO,MAAM,cAAc,GAAI,aAAa,qBAAqB,WACmB,CAAC;AAErF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,SAAS;IAChB,YAAY,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC/C,eAAe,EAAE,MAAM,CAAC;CACzB,EAAE,EACH,gBAAgB,MAAM,GAAG,IAAI,KAC5B;IAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAqBrD,CAAC;AAKF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,iBAAiB,EAAE,OAAO,MAAM,EAAE,YAAY,MAAM,KAAG,QAM5F,CAAC"}

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

@@ -1,11 +1,6 @@
 import { type AnchorState, resolveAnchor } from "./anchor.js";
 import { type Rect } from "./layout.js";
 import type { CommentAnchor } from "./types.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.
- */
 /** How far a pin keeps from the viewport's edges. */
 export declare const PIN_EDGE_MARGIN = 12;
 export interface PinPoint {
@@ -13,13 +8,19 @@ export interface PinPoint {
     y: number;
 }
 /**
- * The pin's point, in viewport coordinates.
- * - A quote: the end of its last line.
- * - An element: where it was clicked, scaled to the element's box now; else its top-right corner.
+ * 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;
@@ -27,6 +28,7 @@ export declare const pinPoint: (target: {
         x: number;
         y: number;
     };
+    isRtl?: boolean;
 }) => PinPoint;
 /** `point` kept `margin` inside the viewport. */
 export declare const keepInViewport: (point: PinPoint, viewport: {
@@ -56,17 +58,69 @@ export interface ThreadLayout {
     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";
-/** Lays out one anchor whose element is known. */
-export declare const layoutAnchor: (anchor: CommentAnchor, resolved: ReturnType<typeof resolveAnchor>) => ThreadLayout;
-/** Where each thread is on the page now, re-measured at most once per frame while `isActive`. */
+/**
+ * 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) => ReadonlyMap<string | number, ThreadLayout>;
+}[], isActive: boolean, isRtl?: boolean) => ReadonlyMap<string | number, ThreadLayout>;
 //# sourceMappingURL=pins.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"pins.d.ts","sourceRoot":"","sources":["../../src/comments/pins.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAoC,aAAa,EAAE,MAAM,UAAU,CAAC;AAC7F,OAAO,EAAe,KAAK,IAAI,EAA0C,MAAM,UAAU,CAAC;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;GAIG;AAEH,qDAAqD;AACrD,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GACnB,QAAQ;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAC5G,QAYF,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,cAAc,GACzB,OAAO,QAAQ,EACf,UAAU;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC3C,eAAwB;;;CAIxB,CAAC;AAEH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,CAAC,EAAE,CAAC;CACZ;AAED,kGAAkG;AAClG,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,MAAM,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,EAAE,KAAG,QAAQ,CAAC,CAAC,CAAC,EAWpG,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,4GAA4G;IAC5G,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID;;;GAGG;AACH,eAAO,MAAM,wBAAwB,+BAA+B,CAAC;AAmBrE,kDAAkD;AAClD,eAAO,MAAM,YAAY,GAAI,QAAQ,aAAa,EAAE,UAAU,UAAU,CAAC,OAAO,aAAa,CAAC,KAAG,YAsBhG,CAAC;AAkBF,iGAAiG;AACjG,eAAO,MAAM,cAAc,GACzB,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,EAAE,EAClE,UAAU,OAAO,KAChB,WAAW,CAAC,MAAM,GAAG,MAAM,EAAE,YAAY,CAgB3C,CAAC"}
+{"version":3,"file":"pins.d.ts","sourceRoot":"","sources":["../../src/comments/pins.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAoC,aAAa,EAAE,MAAM,UAAU,CAAC;AAC7F,OAAO,EAAe,KAAK,IAAI,EAA0C,MAAM,UAAU,CAAC;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAY7C,qDAAqD;AACrD,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,GACnB,QACI;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,KACrF,QAIF,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,cAAc,GACzB,OAAO,QAAQ,EACf,UAAU;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC3C,eAAwB;;;CAIxB,CAAC;AAEH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,CAAC,EAAE,CAAC;CACZ;AAED,kGAAkG;AAClG,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,MAAM,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,EAAE,KAAG,QAAQ,CAAC,CAAC,CAAC,EAWpG,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,4GAA4G;IAC5G,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC;IACd;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE;QACP,EAAE,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;QACxC,KAAK,EAAE,QAAQ,CAAC;QAChB,KAAK,EAAE,QAAQ,CAAC;KACjB,CAAC;CACH;AAID;;;GAGG;AACH,eAAO,MAAM,wBAAwB,+BAA+B,CAAC;AAmBrE;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,IAAI,EAAE,UAAU;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAG,QAGlF,CAAC;AAyEH,mGAAmG;AACnG,eAAO,MAAM,YAAY,GAAI,UAAU,UAAU,CAAC,OAAO,aAAa,CAAC,EAAE,OAAO,OAAO,KAAG,YA8BzF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,aAAa,EACrB,SAAS,WAAW,EACpB,QAAO,OAAqB,KAC3B;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAGjC,CAAC;AAKF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,aAAa,sCAWxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GACzB,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,EAAE,EAClE,UAAU,OAAO,EACjB,QAAQ,OAAO,KACd,WAAW,CAAC,MAAM,GAAG,MAAM,EAAE,YAAY,CAkB3C,CAAC"}