@blocksdiy/react-common 1.70.2 → 1.71.1

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

@@ -0,0 +1,76 @@
+import { type Rect } from "./layout.js";
+import { type TextPoint } from "./text-pick.js";
+import type { CommentAnchor } from "./types.js";
+/**
+ * Pointing at something on the page: what comment mode and the agent chat's pointer share. While
+ * active, hovering outlines the element under the pointer and a click (or the first tap on a touch
+ * screen) picks it, with any text selected inside it as the quote. Nothing in the app reacts to
+ * that click: no link opens, no handler runs. UI marked with `PICK_IGNORE_ATTRIBUTE` (the comments'
+ * own, the chat) is neither picked nor blocked.
+ *
+ * Over text, the pointer is a text cursor on the word under it, and a drag points at just the text
+ * it covers — never past the row it started in — picking its element with that text as the quote,
+ * on buttons and links too (the picker's own range, not the browser's selection). A press without
+ * a drag still picks the whole element.
+ */
+export interface PagePick {
+    anchor: CommentAnchor;
+    element: HTMLElement;
+}
+export interface UsePagePickOptions {
+    isActive: boolean;
+    /** The page's pathname, stored on the anchor. */
+    routePath: string;
+    onPick: (pick: PagePick) => void;
+    /** Esc while pointing. */
+    onCancel?: () => void;
+}
+/** Pointing at text: the word under the pointer, or the text a drag covers. */
+export interface PagePickText {
+    range: Range;
+    /** The caret position under the pointer; null while dragging. */
+    caret: TextPoint | null;
+    isSelecting: boolean;
+}
+export interface PagePickHover {
+    element: HTMLElement;
+    rect: Rect;
+    /** What the element is called, as its pick would be (`pickLabel`): its text, else its component's name, else the page. */
+    label: string;
+    /** Over text: what to tint (on screen, clipped) and where the caret bar goes. */
+    text?: {
+        rects: Rect[];
+        caret: {
+            x: number;
+            top: number;
+            bottom: number;
+        } | null;
+        isSelecting: boolean;
+    };
+}
+/**
+ * What the hover label shows for an element: what picking it would be labelled (`anchorLabel`) —
+ * its text, else its component's name, else the page; never its tag.
+ */
+export declare const pickLabel: (element: HTMLElement, routePath: string) => string;
+export interface PagePickListeners {
+    /** The page's pathname at the moment of the pick. */
+    routePath: () => string;
+    onPick: (pick: PagePick) => void;
+    onCancel: () => void;
+    /** The element the pointer is over (null when it left the page or is over ignored UI). */
+    onHover: (element: HTMLElement | null) => void;
+    /** The text the pointer is on, or a drag covers; null off text. */
+    onText?: (text: PagePickText | null) => void;
+}
+/** How the picker finds text under the pointer: the browser's caret, unless a test gives its own. */
+export interface PagePickTextLookup {
+    /** The text position under the pointer, only when it is on a word. */
+    textPointAt: (x: number, y: number) => TextPoint | null;
+    /** The nearest text position, wherever the pointer is (where a drag ends). */
+    caretAt: (x: number, y: number) => TextPoint | null;
+}
+/** Starts listening on `doc` for a pick; returns the stop. What `usePagePick` runs while active. */
+export declare const listenForPagePick: (doc: Document, listeners: PagePickListeners, lookup?: PagePickTextLookup) => (() => void);
+export declare const usePagePick: ({ isActive, routePath, onPick, onCancel }: UsePagePickOptions) => PagePickHover | null;
+//# sourceMappingURL=page-pick.d.ts.map

package/dist/comments/page-pick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-pick.d.ts","sourceRoot":"","sources":["../../src/comments/page-pick.ts"],"names":[],"mappings":"AAGA,OAAO,EAAe,KAAK,IAAI,EAA0C,MAAM,UAAU,CAAC;AAC1F,OAAO,EAOL,KAAK,SAAS,EAGf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACjC,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,iEAAiE;IACjE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,IAAI,CAAC;IACX,0HAA0H;IAC1H,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,IAAI,CAAC,EAAE;QACL,KAAK,EAAE,IAAI,EAAE,CAAC;QACd,KAAK,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QACzD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,WAAW,EAAE,WAAW,MAAM,KAAG,MAQhE,CAAC;AAeL,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACjC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,0FAA0F;IAC1F,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,mEAAmE;IACnE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC;CAC9C;AAED,qGAAqG;AACrG,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC;IACxD,8EAA8E;IAC9E,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC;CACrD;AAQD,oGAAoG;AACpG,eAAO,MAAM,iBAAiB,GAC5B,KAAK,QAAQ,EACb,WAAW,iBAAiB,EAC5B,SAAQ,kBAGP,KACA,CAAC,MAAM,IAAI,CAkMb,CAAC;AAcF,eAAO,MAAM,WAAW,GAAI,2CAA2C,kBAAkB,KAAG,aAAa,GAAG,IA4C3G,CAAC"}

package/dist/comments/page-pick.js

@@ -0,0 +1,283 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { anchorLabel, captureAnchor, isPickIgnored, pickTarget, textOf } from "./anchor.js";
+import { clipRectsOf, toRect, usePageLayoutTick, visiblePart } from "./layout.js";
+import { caretFromPoint, caretRectAt, clampToRoot, DRAG_THRESHOLD_PX, dragRootOf, rangeBetween, textPointAt, wordRangeAt, } from "./text-pick.js";
+/**
+ * What the hover label shows for an element: what picking it would be labelled (`anchorLabel`) —
+ * its text, else its component's name, else the page; never its tag.
+ */
+export const pickLabel = (element, routePath) => anchorLabel({
+    v: 1,
+    routePath,
+    element: {
+        devName: element.getAttribute("data-dev-name") ?? undefined,
+        textSnapshot: textOf(element) || undefined,
+    },
+});
+/** The page's text selection, if any: `captureAnchor` quotes it when it is inside the picked element. */
+const selectedRange = () => {
+    const selection = typeof window.getSelection === "function" ? window.getSelection() : null;
+    return selection && selection.rangeCount > 0 ? selection.getRangeAt(0) : null;
+};
+/** Stops the app hearing a press that is part of picking; leaves native text selection alone. */
+const swallow = (event) => {
+    if (!isPickIgnored(event.target)) {
+        event.stopPropagation();
+    }
+};
+/**
+ * The pickers listening now, oldest first. Comment mode and the chat's pointer can both be on:
+ * only the one started last hears the page, and the earlier one resumes when it stops.
+ */
+const listeningPicks = [];
+/** Starts listening on `doc` for a pick; returns the stop. What `usePagePick` runs while active. */
+export const listenForPagePick = (doc, listeners, lookup = {
+    textPointAt: (x, y) => textPointAt(doc, x, y),
+    caretAt: (x, y) => caretFromPoint(doc, x, y),
+}) => {
+    const self = {};
+    listeningPicks.push(self);
+    const isPaused = () => listeningPicks[listeningPicks.length - 1] !== self;
+    // A press on text, until its release: where it started, what it may cover, what it covers.
+    let drag = null;
+    // The click a drag's release makes: the drag already picked.
+    let isSwallowingClick = false;
+    // What was last reported: a move that changes nothing reports nothing (no re-render per pixel).
+    let shown = [null, 0, null, 0];
+    const showText = (text) => {
+        const next = text
+            ? text.isSelecting
+                ? [text.range.startContainer, text.range.startOffset, text.range.endContainer, text.range.endOffset]
+                : [text.caret?.node ?? null, text.caret?.offset ?? 0, null, -1]
+            : [null, 0, null, 0];
+        if (next.every((value, index) => value === shown[index])) {
+            return;
+        }
+        shown = next;
+        listeners.onText?.(text);
+    };
+    const pick = (element, range, event) => listeners.onPick({
+        element,
+        anchor: captureAnchor({
+            routePath: listeners.routePath(),
+            element,
+            range,
+            clientX: event.clientX,
+            clientY: event.clientY,
+        }),
+    });
+    /** A collapsed range at a text position: where a drag starts, the caret between words. */
+    const rangeAt = (point) => {
+        const range = doc.createRange();
+        range.setStart(point.node, point.offset);
+        return range;
+    };
+    const onOver = (event) => {
+        listeners.onHover(isPaused() ? null : pickTarget(event.target));
+    };
+    const onOut = (event) => {
+        if (!event.relatedTarget && !drag) {
+            listeners.onHover(null);
+            showText(null);
+        }
+    };
+    const onMove = (event) => {
+        if (drag) {
+            if (!drag.isMoved && Math.hypot(event.clientX - drag.x, event.clientY - drag.y) < DRAG_THRESHOLD_PX) {
+                return;
+            }
+            drag.isMoved = true;
+            const end = lookup.caretAt(event.clientX, event.clientY);
+            if (end) {
+                drag.range = rangeBetween(doc, drag.start, clampToRoot(drag.root, end));
+            }
+            showText({ range: drag.range, caret: null, isSelecting: true });
+            return;
+        }
+        if (isPaused() || isPickIgnored(event.target)) {
+            showText(null);
+            return;
+        }
+        const point = lookup.textPointAt(event.clientX, event.clientY);
+        if (!point) {
+            showText(null);
+            return;
+        }
+        // Between words: the caret alone, nothing tinted.
+        showText({ range: wordRangeAt(doc, point) ?? rangeAt(point), caret: point, isSelecting: false });
+    };
+    const onPress = (event) => {
+        isSwallowingClick = false;
+        if (isPaused()) {
+            // The picker in front takes this press. Should it stop before the click the press ends in
+            // (a drag's pick, Esc during a drag), that click is still part of its pointing, not a pick
+            // of this one's.
+            isSwallowingClick = event.button === 0 && !isPickIgnored(event.target);
+            return;
+        }
+        if (event.button !== 0 || isPickIgnored(event.target)) {
+            return;
+        }
+        const point = lookup.textPointAt(event.clientX, event.clientY);
+        const root = point ? dragRootOf(point.node) : null;
+        if (!point || !root) {
+            return;
+        }
+        // The picker's own range, not a native selection (which buttons and links don't make).
+        event.preventDefault();
+        drag = { root, start: point, x: event.clientX, y: event.clientY, isMoved: false, range: rangeAt(point) };
+    };
+    const onRelease = (event) => {
+        if (isPaused()) {
+            return;
+        }
+        const finished = drag;
+        drag = null;
+        if (!finished?.isMoved) {
+            // A press without a drag: the click that follows picks the element.
+            return;
+        }
+        event.stopPropagation();
+        showText(null);
+        const { range, root } = finished;
+        if (range.collapsed || !range.toString().trim()) {
+            return;
+        }
+        const target = pickTarget(range.commonAncestorContainer);
+        isSwallowingClick = true;
+        pick(target && root.contains(target) ? target : root, range, event);
+    };
+    const onClick = (event) => {
+        if (isPaused()) {
+            isSwallowingClick = false;
+            return;
+        }
+        if (isSwallowingClick) {
+            isSwallowingClick = false;
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+        }
+        const target = pickTarget(event.target);
+        if (!target) {
+            return;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        pick(target, selectedRange(), event);
+    };
+    const onKeyDown = (event) => {
+        if (event.key === "Escape" && !isPaused() && !isPickIgnored(event.target)) {
+            event.stopPropagation();
+            if (drag) {
+                // Esc mid-drag drops the drag, not the mode, and the click its release makes picks nothing.
+                drag = null;
+                isSwallowingClick = true;
+                showText(null);
+                return;
+            }
+            listeners.onCancel();
+        }
+    };
+    // Menus and drags often act on press, not click: the app doesn't hear those either.
+    const presses = ["pointerdown", "mousedown", "touchstart"];
+    doc.addEventListener("mouseover", onOver);
+    doc.addEventListener("mouseout", onOut);
+    doc.addEventListener("mousemove", onMove, true);
+    doc.addEventListener("mousedown", onPress, true);
+    doc.addEventListener("mouseup", onRelease, true);
+    doc.addEventListener("click", onClick, true);
+    presses.forEach((type) => doc.addEventListener(type, swallow, true));
+    doc.addEventListener("keydown", onKeyDown, true);
+    return () => {
+        const index = listeningPicks.indexOf(self);
+        if (index >= 0) {
+            listeningPicks.splice(index, 1);
+        }
+        doc.removeEventListener("mouseover", onOver);
+        doc.removeEventListener("mouseout", onOut);
+        doc.removeEventListener("mousemove", onMove, true);
+        doc.removeEventListener("mousedown", onPress, true);
+        doc.removeEventListener("mouseup", onRelease, true);
+        doc.removeEventListener("click", onClick, true);
+        presses.forEach((type) => doc.removeEventListener(type, swallow, true));
+        doc.removeEventListener("keydown", onKeyDown, true);
+        // The click a release makes comes right after it, and still isn't the app's when the press
+        // was part of picking. Only that click: the listener is gone a moment later.
+        const swallowNextClick = () => {
+            const swallowClick = (event) => {
+                event.preventDefault();
+                event.stopPropagation();
+            };
+            doc.addEventListener("click", swallowClick, { capture: true, once: true });
+            setTimeout(() => doc.removeEventListener("click", swallowClick, true), 0);
+        };
+        if (isSwallowingClick) {
+            // Stopped by its own drag's pick (the chat's pointer ends on a pick), before the click.
+            isSwallowingClick = false;
+            swallowNextClick();
+        }
+        else if (drag) {
+            // Stopped during a press (Esc ends the chat's pointing mid-drag): the click comes after the
+            // release. A new press first means that release never came here: nothing to swallow.
+            const forget = () => doc.removeEventListener("mouseup", swallowNextClick, true);
+            doc.addEventListener("mouseup", swallowNextClick, { capture: true, once: true });
+            doc.addEventListener("mousedown", forget, { capture: true, once: true });
+            drag = null;
+        }
+    };
+};
+/** A text pick's tint and caret, on screen: each line's box, clipped by what scrolls it. */
+const textGeometry = (text) => {
+    const container = text.range.commonAncestorContainer;
+    const element = container instanceof Element ? container : container.parentElement;
+    const clips = element ? clipRectsOf(element) : [];
+    const rects = Array.from(text.range.getClientRects())
+        .map((rect) => visiblePart(toRect(rect), clips))
+        .filter((rect) => rect !== null && rect.right > rect.left);
+    const doc = element?.ownerDocument ?? document;
+    return { rects, caret: text.caret ? caretRectAt(doc, text.caret) : null, isSelecting: text.isSelecting };
+};
+export const usePagePick = ({ isActive, routePath, onPick, onCancel }) => {
+    // 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 [hovered, setHovered] = useState(null);
+    const [text, setText] = useState(null);
+    const latest = useRef({ routePath, onPick, onCancel });
+    useEffect(() => {
+        latest.current = { routePath, onPick, onCancel };
+    });
+    useEffect(() => {
+        if (!isActive || typeof document === "undefined") {
+            return;
+        }
+        const stop = listenForPagePick(document, {
+            routePath: () => latest.current.routePath,
+            onPick: (pick) => latest.current.onPick(pick),
+            onCancel: () => latest.current.onCancel?.(),
+            onHover: setHovered,
+            onText: setText,
+        });
+        return () => {
+            stop();
+            setHovered(null);
+            setText(null);
+        };
+    }, [isActive]);
+    // Per element, not per layout tick: reading a large element's text isn't free.
+    const label = useMemo(() => (hovered ? pickLabel(hovered, routePath) : ""), [hovered, routePath]);
+    const tick = usePageLayoutTick(isActive && hovered !== null);
+    return useMemo(() => {
+        void tick;
+        if (!isActive || !hovered?.isConnected) {
+            return null;
+        }
+        return {
+            element: hovered,
+            rect: toRect(hovered.getBoundingClientRect()),
+            label,
+            ...(text ? { text: textGeometry(text) } : {}),
+        };
+    }, [hovered, isActive, label, text, tick]);
+};

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

@@ -0,0 +1,11 @@
+import type { ComposerMessageMeta } from "../utils/composer-message.js";
+import { type CommentAnchor } from "./types.js";
+/** The text part a pick sends: the marker line, then the place described for the agent. */
+export declare const pagePickText: (anchor: CommentAnchor) => string;
+/** Arms the composer with a pick. */
+export declare const pagePickComposerMeta: (anchor: CommentAnchor) => ComposerMessageMeta;
+/** The pill's label for a sent or armed pick's text part, or null when the part isn't one. */
+export declare const parsePagePickPart: (text: string) => string | null;
+/** The label of the pick the composer is armed with, or null. */
+export declare const pagePickOf: (meta: ComposerMessageMeta | null | undefined) => string | null;
+//# sourceMappingURL=pick-message.d.ts.map

package/dist/comments/pick-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick-message.d.ts","sourceRoot":"","sources":["../../src/comments/pick-message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,EAAE,KAAK,aAAa,EAA0B,MAAM,SAAS,CAAC;AAiBrE,2FAA2F;AAC3F,eAAO,MAAM,YAAY,GAAI,QAAQ,aAAa,KAAG,MAC+B,CAAC;AAErF,qCAAqC;AACrC,eAAO,MAAM,oBAAoB,GAAI,QAAQ,aAAa,KAAG,mBAE3D,CAAC;AAEH,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,IAMzD,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,UAAU,GAAI,MAAM,mBAAmB,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,IAGlF,CAAC"}

package/dist/comments/pick-message.js

@@ -0,0 +1,33 @@
+import { anchorLabel } from "./anchor.js";
+import { describeAnchorForAgent } from "./types.js";
+/**
+ * Pointing at something from the agent chat (BLK-1636): the pick rides with the next message as
+ * one leading text part — a first line the chat shows as a pill (`[Pointing at: <label>]`), then
+ * what the agent is told about the place, in the same words a comment gives it. Nothing is saved
+ * and no pin is made. The composer has one meta slot: a pick replaces armed feedback and back.
+ */
+const PREFIX = "[Pointing at: ";
+/**
+ * The label as the marker line carries it: as written, on one line. A "]" inside is safe — the
+ * readers find the line's end by "]\n", and the label holds no line break.
+ */
+const markerLabel = (label) => label.replace(/[\r\n]+/g, " ");
+/** The text part a pick sends: the marker line, then the place described for the agent. */
+export const pagePickText = (anchor) => `${PREFIX}${markerLabel(anchorLabel(anchor))}]\n${describeAnchorForAgent(anchor)}`;
+/** Arms the composer with a pick. */
+export const pagePickComposerMeta = (anchor) => ({
+    leadingParts: [{ type: "text", text: pagePickText(anchor) }],
+});
+/** The pill's label for a sent or armed pick's text part, or null when the part isn't one. */
+export const parsePagePickPart = (text) => {
+    if (!text.startsWith(PREFIX)) {
+        return null;
+    }
+    const end = text.indexOf("]\n", PREFIX.length);
+    return end < 0 ? null : text.slice(PREFIX.length, end);
+};
+/** The label of the pick the composer is armed with, or null. */
+export const pagePickOf = (meta) => {
+    const first = meta?.leadingParts?.[0]?.text;
+    return meta && !meta.name && first ? parsePagePickPart(first) : null;
+};

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"}