@blocksdiy/react-common 1.71.0 → 1.71.1

package/dist/comments/pins.js

@@ -6,25 +6,23 @@ import { clipRectsOf, toRect, usePageLayoutTick, visiblePart } from "./layout.js
  * 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.
- * - 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 const pinPoint = (target) => {
-    if (target.kind === "quote") {
-        return { x: target.lastLine.right, y: (target.lastLine.top + target.lastLine.bottom) / 2 };
-    }
-    const { rect, point } = target;
-    if (!point) {
-        return { x: rect.right, y: rect.top };
-    }
-    return {
-        x: rect.left + point.x * (rect.right - rect.left),
-        y: rect.top + point.y * (rect.bottom - rect.top),
-    };
+    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) => ({
@@ -66,36 +64,125 @@ const keyOf = (element) => {
     }
     return key;
 };
-/** Lays out one anchor whose element is known. */
-export const layoutAnchor = (anchor, resolved) => {
+/**
+ * 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 = toRect(element.getBoundingClientRect());
-    const visible = visiblePart(box, clipRectsOf(element));
-    if (!visible || !isUncovered(element, visible)) {
-        return { state, element, 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 };
     }
-    const lines = range ? Array.from(range.getClientRects()).filter((rect) => rect.width > 0 || rect.height > 0) : [];
-    const lastLine = lines.at(-1);
-    const point = lastLine
-        ? pinPoint({ kind: "quote", lastLine: toRect(lastLine) })
-        : pinPoint({ kind: "element", rect: box, point: anchor.point });
-    return {
-        state,
-        element,
-        currentText,
-        point: keepInViewport(point, { width: window.innerWidth, height: window.innerHeight }),
-        groupKey: keyOf(element),
-    };
+    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 in the same row. */
-const resolveCached = (anchor) => {
+/**
+ * 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 stillThere = known?.isConnected && (!anchor.item || findAnchorItemElement(anchor)?.contains(known) === true);
+    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);
@@ -105,12 +192,18 @@ const resolveCached = (anchor) => {
     }
     return resolved;
 };
-/** Where each thread is on the page now, re-measured at most once per frame while `isActive`. */
-export const useCommentPins = (anchors, isActive) => {
+/**
+ * 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();
@@ -118,8 +211,8 @@ export const useCommentPins = (anchors, isActive) => {
             return layouts;
         }
         for (const { id, anchor } of anchors) {
-            layouts.set(id, layoutAnchor(anchor, resolveCached(anchor)));
+            layouts.set(id, layoutAnchor(resolveAnchorCached(anchor), rtl));
         }
         return layouts;
-    }, [anchors, isActive, tick]);
+    }, [anchors, isActive, tick, rtl]);
 };

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

@@ -39,7 +39,17 @@ export declare const rangeBetween: (doc: Document, a: Boundary, b: Boundary) =>
 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 caret position the browser puts under `(x, y)`, when it is in a text node. */
+/** 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

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

@@ -1 +1 @@
-{"version":3,"file":"text-pick.d.ts","sourceRoot":"","sources":["../../src/comments/text-pick.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,IAAI,EAAU,MAAM,UAAU,CAAC;AAE7C;;;;;GAKG;AAEH,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8EAA8E;AAC9E,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAgBnC;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,EAAE,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAoC7G,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,cAAc,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,SAAS,IAAI,EAAE,EAAE,aAAQ,KAAG,OAGrF,CAAC;AAEJ,mDAAmD;AACnD,eAAO,MAAM,OAAO,GAAI,GAAG,QAAQ,EAAE,GAAG,QAAQ,KAAG,OAMlD,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,YAAY,GAAI,KAAK,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,QAAQ,KAAG,KAMtE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,KAAG,OAAO,GAAG,IAGjD,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,EAAE,OAAO,QAAQ,KAAG,QAM5D,CAAC;AAOF,qFAAqF;AACrF,eAAO,MAAM,cAAc,GAAI,KAAK,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,SAAS,GAAG,IAchF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,SAAS,GAAG,IAgB7E,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,WAAW,GAAI,KAAK,QAAQ,EAAE,OAAO,SAAS,KAAG,KAAK,GAAG,IASrE,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,WAAW,GAAI,KAAK,QAAQ,EAAE,OAAO,SAAS,KAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAmB1G,CAAC"}
+{"version":3,"file":"text-pick.d.ts","sourceRoot":"","sources":["../../src/comments/text-pick.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,IAAI,EAAU,MAAM,UAAU,CAAC;AAE7C;;;;;GAKG;AAEH,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8EAA8E;AAC9E,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAgBnC;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,EAAE,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAoC7G,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,cAAc,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,SAAS,IAAI,EAAE,EAAE,aAAQ,KAAG,OAGrF,CAAC;AAEJ,mDAAmD;AACnD,eAAO,MAAM,OAAO,GAAI,GAAG,QAAQ,EAAE,GAAG,QAAQ,KAAG,OAMlD,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,YAAY,GAAI,KAAK,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,QAAQ,KAAG,KAMtE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,IAAI,KAAG,OAAO,GAAG,IAGjD,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,EAAE,OAAO,QAAQ,KAAG,QAM5D,CAAC;AAOF,+FAA+F;AAC/F,eAAO,MAAM,cAAc,MAAM,CAAC;AA6IlC;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,SAAS,GAAG,IAYhF,CAAC;AAkBF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,SAAS,GAAG,IAgB7E,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,WAAW,GAAI,KAAK,QAAQ,EAAE,OAAO,SAAS,KAAG,KAAK,GAAG,IASrE,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,WAAW,GAAI,KAAK,QAAQ,EAAE,OAAO,SAAS,KAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAmB1G,CAAC"}

package/dist/comments/text-pick.js

@@ -91,8 +91,150 @@ export const clampToRoot = (root, point) => {
     const end = { node: root, offset: root.childNodes.length };
     return isAfter(point, end) ? end : { node: root, offset: 0 };
 };
-/** The caret position the browser puts under `(x, y)`, when it is in a text node. */
+/** The most characters a lookup measures to correct the browser's answer before keeping it. */
+export const CARET_SCAN_MAX = 256;
+let graphemes;
+const graphemeSegmenter = () => {
+    if (graphemes === undefined) {
+        graphemes =
+            typeof Intl !== "undefined" && typeof Intl.Segmenter === "function"
+                ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+                : null;
+    }
+    return graphemes;
+};
+const clustersByNode = new WeakMap();
+/**
+ * Where each character of `node`'s text starts as a reader sees it (a grapheme cluster: an emoji,
+ * a letter with its marks), then the text's end. Without `Intl.Segmenter`, code points. Kept per
+ * node while its text is the same.
+ */
+const clusterBounds = (node) => {
+    const data = node.data;
+    const known = clustersByNode.get(node);
+    if (known?.data === data) {
+        return known.bounds;
+    }
+    const bounds = [];
+    const segmenter = graphemeSegmenter();
+    if (segmenter) {
+        for (const segment of segmenter.segment(data)) {
+            bounds.push(segment.index);
+        }
+    }
+    else {
+        for (let index = 0; index < data.length; index += data.codePointAt(index) > 0xffff ? 2 : 1) {
+            bounds.push(index);
+        }
+    }
+    bounds.push(data.length);
+    clustersByNode.set(node, { data, bounds });
+    return bounds;
+};
+/** The character `offset` is in or starts (its index in `bounds`); the count of them at the end. */
+const clusterAt = (bounds, offset) => {
+    let low = 0;
+    let high = bounds.length - 1;
+    while (low < high) {
+        const middle = (low + high + 1) >> 1;
+        if (bounds[middle] <= offset) {
+            low = middle;
+        }
+        else {
+            high = middle - 1;
+        }
+    }
+    return low;
+};
+/** The box of character `index` (as `clusterBounds` counts them), if it has one with width. */
+const clusterRect = (doc, node, bounds, index) => {
+    if (index < 0 || index >= bounds.length - 1) {
+        return null;
+    }
+    const range = doc.createRange();
+    range.setStart(node, bounds[index]);
+    range.setEnd(node, bounds[index + 1]);
+    const rects = Array.from(range.getClientRects());
+    return rects.find((rect) => rect.right > rect.left) ?? null;
+};
+const holds = (rect, x, y) => !!rect && x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom;
+/**
+ * Whether character `index` (its box `rect`) is in a run read left to right: from a neighbour
+ * touching it on its line, else from its element's direction.
+ */
+const readsLeftToRight = (doc, node, bounds, index, rect) => {
+    for (const neighbour of [index + 1, index - 1]) {
+        const box = clusterRect(doc, node, bounds, neighbour);
+        if (!box || Math.abs(box.top - rect.top) > 1) {
+            continue;
+        }
+        if (Math.abs(box.left - rect.right) < 1) {
+            return neighbour > index;
+        }
+        if (Math.abs(box.right - rect.left) < 1) {
+            return neighbour < index;
+        }
+    }
+    const element = node.parentElement;
+    return !element || doc.defaultView?.getComputedStyle(element).direction !== "rtl";
+};
+/**
+ * The caret position at `(x, y)` from the boxes of `node`'s characters, looked for outward from
+ * the browser's answer (`near`, its character index): before the character under it when on its
+ * leading half, else after it. Null when the pointer isn't on `node`'s text, or no character
+ * within `CARET_SCAN_MAX` of the answer is under it.
+ */
+const caretOnCharacters = (doc, node, bounds, near, x, y) => {
+    const whole = doc.createRange();
+    whole.selectNodeContents(node);
+    if (!isPointInRects(x, y, Array.from(whole.getClientRects(), toRect), 0)) {
+        return null;
+    }
+    const count = bounds.length - 1;
+    let measured = 0;
+    for (let distance = 0; measured < CARET_SCAN_MAX; distance += 1) {
+        const after = near + distance;
+        const before = near - distance - 1;
+        if (after >= count && before < 0) {
+            return null;
+        }
+        for (const index of [after, before]) {
+            if (index < 0 || index >= count || measured >= CARET_SCAN_MAX) {
+                continue;
+            }
+            measured += 1;
+            const rect = clusterRect(doc, node, bounds, index);
+            if (rect && holds(rect, x, y)) {
+                const isLeading = x < (rect.left + rect.right) / 2 === readsLeftToRight(doc, node, bounds, index, rect);
+                return { node, offset: bounds[isLeading ? index : index + 1] };
+            }
+        }
+    }
+    return null;
+};
+/**
+ * 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 const caretFromPoint = (doc, x, y) => {
+    const point = browserCaretAt(doc, x, y);
+    if (!point) {
+        return null;
+    }
+    const bounds = clusterBounds(point.node);
+    const index = clusterAt(bounds, point.offset);
+    const beside = bounds[index] === point.offset ? [index - 1, index] : [index];
+    if (beside.some((at) => holds(clusterRect(doc, point.node, bounds, at), x, y))) {
+        return point;
+    }
+    return caretOnCharacters(doc, point.node, bounds, index, x, y) ?? point;
+};
+const browserCaretAt = (doc, x, y) => {
     const caretDoc = doc;
     let node = null;
     let offset = 0;

package/dist/comments/types.d.ts

@@ -46,7 +46,10 @@ export interface CommentAnchor {
     item?: CommentAnchorItem;
     element?: CommentAnchorElement;
     text?: CommentAnchorText;
-    /** Where in the element the comment was dropped, as fractions of its box (0..1). */
+    /**
+     * Where in the element the comment was dropped, as fractions of its box (0..1). Stored only: the
+     * pin goes at the top-end corner of the element or its quote (`pinPoint`), not here.
+     */
     point?: {
         x: number;
         y: number;

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

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

package/dist/comments/use-comment-menu.d.ts

@@ -0,0 +1,69 @@
+import { type FocusEvent, type KeyboardEvent, type MouseEvent } from "react";
+/**
+ * A comment menu's open content carries this attribute: the layer asks at a press on the page
+ * whether one is open, so that click only closes it.
+ */
+export declare const COMMENT_MENU_ATTRIBUTE = "data-blocks-comment-menu";
+export interface UseCommentMenuOptions {
+    /** Which edge of the trigger the menu lines up with: its start (a picker) or its end (a ⋯). */
+    align: "start" | "end";
+    /** The height the menu asks for, to open below its trigger or, without room there, above. */
+    height: number;
+}
+/**
+ * A menu button of the comments, headless (the registry draws it): the menu is fixed in the window
+ * beside its trigger (`menuPosition`), portalled to the comments' layer (`container`) so no
+ * panel's overflow clips it and no app menu stack hides it. Opening it (a click, or ↓ on the
+ * trigger) moves focus to its checked item, else its first, and ↑ on the trigger to its last
+ * (WAI-ARIA's menu button); ↓ ↑ Home End move between items (they
+ * take focus by keys only: give them `tabIndex={-1}`); Esc, Tab or Shift+Tab close it with focus
+ * back on the trigger, and Esc goes no further (not the thread, not comment mode); focus leaving
+ * it, the page scrolling or the window resizing closes it (it stands where its trigger was). A
+ * press in it keeps focus where it is, so a browser that doesn't focus buttons on click doesn't
+ * blur it shut before the click lands.
+ *
+ * Spread `rootProps` on an element around the trigger (events from the portalled menu reach it as
+ * React bubbles them), `triggerProps` on the button and `menuProps` on the menu's root.
+ */
+export declare const useCommentMenu: ({ align, height }: UseCommentMenuOptions) => {
+    isOpen: boolean;
+    /** Closes it with focus back on its trigger, as a pick does (WAI-ARIA's menu button). */
+    close: () => void;
+    /** Where to portal the menu while it is open: the comments' layer the trigger is in, else the body. */
+    container: Element | null;
+    rootProps: {
+        ref: import("react").RefObject<HTMLDivElement | null>;
+        onBlur: (event: FocusEvent<HTMLElement>) => void;
+        onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    };
+    triggerProps: {
+        ref: import("react").RefObject<HTMLButtonElement | null>;
+        id: string;
+        "aria-haspopup": "menu";
+        "aria-expanded": boolean;
+        "aria-controls": string | undefined;
+        "data-state": "open" | "closed";
+        onClick: () => void;
+        onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    };
+    menuProps: {
+        ref: import("react").RefObject<HTMLDivElement | null>;
+        id: string;
+        role: "menu";
+        "aria-labelledby": string;
+        "data-blocks-comment-menu": string;
+        "data-state": "open";
+        "data-side": "top" | "bottom" | undefined;
+        style: {
+            top?: number | undefined;
+            bottom?: number | undefined;
+            left?: number | undefined;
+            right?: number | undefined;
+            maxHeight?: number | undefined;
+        };
+        onMouseDown: (event: MouseEvent<HTMLElement>) => void;
+        onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    };
+};
+export type CommentMenuState = ReturnType<typeof useCommentMenu>;
+//# sourceMappingURL=use-comment-menu.d.ts.map

package/dist/comments/use-comment-menu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-comment-menu.d.ts","sourceRoot":"","sources":["../../src/comments/use-comment-menu.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,UAAU,EAMhB,MAAM,OAAO,CAAC;AAMf;;;GAGG;AACH,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AAMjE,MAAM,WAAW,qBAAqB;IACpC,+FAA+F;IAC/F,KAAK,EAAE,OAAO,GAAG,KAAK,CAAC;IACvB,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,GAAI,mBAAmB,qBAAqB;;IAsEnE,yFAAyF;;IAEzF,uGAAuG;;;;wBAIrF,UAAU,CAAC,WAAW,CAAC;2BAKpB,aAAa,CAAC,WAAW,CAAC;;;;;;;;;;2BAgB1B,aAAa,CAAC,WAAW,CAAC;;;;;;;;;;;;;;;;;6BAgBxB,UAAU,CAAC,WAAW,CAAC;2BACzB,aAAa,CAAC,WAAW,CAAC;;CAUlD,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/comments/use-comment-menu.js

@@ -0,0 +1,140 @@
+import { useCallback, useEffect, useId, useRef, useState, } from "react";
+import { toRect } from "./layout.js";
+import { menuKeyTarget, menuPosition } from "./menu.js";
+import { COMMENTS_LAYER_ATTRIBUTE } from "./pins.js";
+/**
+ * A comment menu's open content carries this attribute: the layer asks at a press on the page
+ * whether one is open, so that click only closes it.
+ */
+export const COMMENT_MENU_ATTRIBUTE = "data-blocks-comment-menu";
+const ITEM_SELECTOR = '[role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"]';
+const itemsIn = (menu) => Array.from(menu?.querySelectorAll(ITEM_SELECTOR) ?? []);
+/**
+ * A menu button of the comments, headless (the registry draws it): the menu is fixed in the window
+ * beside its trigger (`menuPosition`), portalled to the comments' layer (`container`) so no
+ * panel's overflow clips it and no app menu stack hides it. Opening it (a click, or ↓ on the
+ * trigger) moves focus to its checked item, else its first, and ↑ on the trigger to its last
+ * (WAI-ARIA's menu button); ↓ ↑ Home End move between items (they
+ * take focus by keys only: give them `tabIndex={-1}`); Esc, Tab or Shift+Tab close it with focus
+ * back on the trigger, and Esc goes no further (not the thread, not comment mode); focus leaving
+ * it, the page scrolling or the window resizing closes it (it stands where its trigger was). A
+ * press in it keeps focus where it is, so a browser that doesn't focus buttons on click doesn't
+ * blur it shut before the click lands.
+ *
+ * Spread `rootProps` on an element around the trigger (events from the portalled menu reach it as
+ * React bubbles them), `triggerProps` on the button and `menuProps` on the menu's root.
+ */
+export const useCommentMenu = ({ align, height }) => {
+    // Where it stands and where it is portalled, both read from the trigger as it opens.
+    const [opened, setOpened] = useState(null);
+    const position = opened?.position ?? null;
+    const isOpen = opened !== null;
+    const rootRef = useRef(null);
+    const triggerRef = useRef(null);
+    const menuRef = useRef(null);
+    const triggerId = useId();
+    const menuId = useId();
+    const open = (focus = "checked") => {
+        const trigger = triggerRef.current;
+        if (!trigger) {
+            return;
+        }
+        setOpened({
+            position: menuPosition(toRect(trigger.getBoundingClientRect()), {
+                height,
+                align,
+                isRtl: getComputedStyle(trigger).direction === "rtl",
+                viewportWidth: document.documentElement.clientWidth,
+                viewportHeight: window.innerHeight,
+            }),
+            // The comments' layer the trigger is in, else the body.
+            container: trigger.closest(`[${COMMENTS_LAYER_ATTRIBUTE}]`) ?? document.body,
+            focus,
+        });
+    };
+    const close = useCallback(() => setOpened(null), []);
+    const closeToTrigger = () => {
+        close();
+        triggerRef.current?.focus();
+    };
+    const focusFrom = opened?.focus;
+    useEffect(() => {
+        if (!focusFrom) {
+            return;
+        }
+        const all = itemsIn(menuRef.current);
+        (focusFrom === "last"
+            ? all.at(-1)
+            : (all.find((item) => item.getAttribute("aria-checked") === "true") ?? all[0]))?.focus();
+        // A scroll inside its own list doesn't move it.
+        const onScroll = (event) => {
+            if (!menuRef.current?.contains(event.target)) {
+                close();
+            }
+        };
+        window.addEventListener("scroll", onScroll, true);
+        window.addEventListener("resize", close);
+        return () => {
+            window.removeEventListener("scroll", onScroll, true);
+            window.removeEventListener("resize", close);
+        };
+    }, [focusFrom, close]);
+    const isInside = (node) => !!node && (!!rootRef.current?.contains(node) || !!menuRef.current?.contains(node));
+    const { side, ...style } = position ?? {};
+    return {
+        isOpen,
+        /** Closes it with focus back on its trigger, as a pick does (WAI-ARIA's menu button). */
+        close: closeToTrigger,
+        /** Where to portal the menu while it is open: the comments' layer the trigger is in, else the body. */
+        container: opened?.container ?? null,
+        rootProps: {
+            ref: rootRef,
+            onBlur: (event) => {
+                if (!isInside(event.relatedTarget)) {
+                    close();
+                }
+            },
+            onKeyDown: (event) => {
+                if (isOpen && (event.key === "Escape" || event.key === "Tab")) {
+                    event.preventDefault();
+                    event.stopPropagation();
+                    closeToTrigger();
+                }
+            },
+        },
+        triggerProps: {
+            ref: triggerRef,
+            id: triggerId,
+            "aria-haspopup": "menu",
+            "aria-expanded": isOpen,
+            "aria-controls": isOpen ? menuId : undefined,
+            "data-state": isOpen ? "open" : "closed",
+            onClick: () => (isOpen ? close() : open()),
+            onKeyDown: (event) => {
+                if (!isOpen && (event.key === "ArrowDown" || event.key === "ArrowUp")) {
+                    event.preventDefault();
+                    open(event.key === "ArrowUp" ? "last" : "checked");
+                }
+            },
+        },
+        menuProps: {
+            ref: menuRef,
+            id: menuId,
+            role: "menu",
+            "aria-labelledby": triggerId,
+            [COMMENT_MENU_ATTRIBUTE]: "",
+            "data-state": "open",
+            "data-side": side,
+            style,
+            onMouseDown: (event) => event.preventDefault(),
+            onKeyDown: (event) => {
+                const all = itemsIn(menuRef.current);
+                const next = menuKeyTarget(event.key, all.indexOf(document.activeElement), all.length);
+                if (next !== null) {
+                    event.preventDefault();
+                    all[next]?.focus();
+                }
+            },
+        },
+    };
+};

package/dist/comments/use-held.d.ts

@@ -0,0 +1,3 @@
+/** True once `isOn` has held for `ms` under the same `key`; false again the moment it doesn't. */
+export declare const useHeld: (isOn: boolean, ms: number, key: unknown) => boolean;
+//# sourceMappingURL=use-held.d.ts.map