docxodus 12.0.1 → 12.2.0

package/dist/editor.js

@@ -37,6 +37,14 @@ function blockPreviewText(unit) {
     const text = (unit.textContent ?? "").trim().replace(/\s+/g, " ");
     return text.length > 48 ? `${text.slice(0, 48)}…` : text;
 }
+/** The floating handle's own box and its gap to the block, as `ensureBlockDragStyles` sizes it. */
+const BLOCK_HANDLE_WIDTH = 26;
+const BLOCK_HANDLE_HEIGHT = 28;
+const BLOCK_HANDLE_GAP = 6;
+/** `value` pulled into [`low`, `high`]; `low` wins when the range is narrower than the box. */
+function clampToRange(value, low, high) {
+    return Math.max(low, Math.min(value, high));
+}
 function ensureBlockDragStyles(doc) {
     if (blockDragStyledDocuments.has(doc))
         return;
@@ -606,16 +614,20 @@ function selectionSpanIn(block) {
     const span = trimmedSpan(block, { start: Math.min(start, end), length: Math.abs(end - start) });
     return span.length > 0 ? span : null;
 }
-/** Restore a content-text selection spanning [start, start+length) within `el` (skips markers). */
-function selectRange(el, start, length) {
-    const sel = typeof window !== "undefined" ? window.getSelection() : null;
+/**
+ * A DOM Range over the content text spanning [start, start+length) within `el` (skips markers),
+ * or null when the block is detached or the offsets do not resolve. Building the range is kept
+ * separate from selecting it so a caller that only wants to PAINT a span (find preview) does not
+ * have to touch the selection — and therefore focus — at all.
+ */
+function contentRangeIn(el, start, length) {
     // The block may have been swapped out of the document by a re-render before this runs
     // (e.g. a focus-stealing toolbar control firing twice). addRange on a detached range
     // throws "the given range isn't in document" — skip rather than warn.
-    if (!sel || !el.isConnected)
-        return;
-    el.focus();
-    const range = document.createRange();
+    if (!el.isConnected)
+        return null;
+    const doc = el.ownerDocument;
+    const range = doc.createRange();
     const from = contentPositionIn(el, start);
     const to = contentPositionIn(el, start + length);
     try {
@@ -623,11 +635,66 @@ function selectRange(el, start, length) {
         range.setEnd(to.node, to.offset);
     }
     catch {
-        return;
+        return null;
     }
+    return range;
+}
+/** Restore a content-text selection spanning [start, start+length) within `el` (skips markers). */
+function selectRange(el, start, length) {
+    const sel = typeof window !== "undefined" ? window.getSelection() : null;
+    if (!sel || !el.isConnected)
+        return;
+    el.focus();
+    const range = contentRangeIn(el, start, length);
+    if (!range)
+        return;
     sel.removeAllRanges();
     sel.addRange(range);
 }
+// ─── Find painting ──────────────────────────────────────────────────────────
+//
+// A find box has to show WHERE the hits are while the user is still typing into it, so it cannot
+// express "the current match" as a selection: putting a caret in a contenteditable block focuses
+// that block, and the next keystroke lands in the document instead of the search field. These
+// highlights paint the same information with no focus and no DOM mutation — the CSS Custom
+// Highlight API takes plain Ranges over the live text and styles them from the stylesheet.
+/** Every match currently on screen. */
+const FIND_HIGHLIGHT = "docxodus-find";
+/** The one the find bar's counter is pointing at. */
+const FIND_HIGHLIGHT_ACTIVE = "docxodus-find-active";
+/** Ranges are cheap, but a pathological query ("e" in a book) is not worth painting in full. */
+const FIND_PAINT_LIMIT = 500;
+const findHighlightStyledDocuments = new WeakSet();
+/**
+ * Which editor last painted into the shared registry. Only that instance may clear it, so a
+ * second surface on the page cannot wipe the first one's find painting when its own find bar
+ * closes. Two live searches still share one painting — the newer one wins, which is what a
+ * single visible "current match" should mean.
+ */
+let findPaintOwner = null;
+function ensureFindHighlightStyles(doc) {
+    if (findHighlightStyledDocuments.has(doc))
+        return;
+    findHighlightStyledDocuments.add(doc);
+    const style = doc.createElement("style");
+    style.dataset.docxodusFindHighlight = "true";
+    style.textContent = `
+::highlight(${FIND_HIGHLIGHT}) { background-color: rgba(15, 118, 110, .16); }
+::highlight(${FIND_HIGHLIGHT_ACTIVE}) { background-color: rgba(15, 118, 110, .38); }
+`;
+    (doc.head ?? doc.documentElement).appendChild(style);
+}
+function highlightRegistry() {
+    if (typeof CSS === "undefined")
+        return null;
+    const registry = CSS.highlights;
+    const ctor = globalThis.Highlight;
+    return registry && typeof ctor === "function" ? registry : null;
+}
+function makeHighlight(ranges) {
+    const ctor = globalThis.Highlight;
+    return new ctor(...ranges);
+}
 /**
  * True when `el`'s immediate parent is a paragraph-border `<div>` the full render wrapped it in
  * (CreateBorderDivs groups visibly-bordered paragraphs into a div). The body wrapper div has no
@@ -697,6 +764,10 @@ export class DocxEditor {
         this.blockMoveMenu = null;
         this.blockMoveLive = null;
         this.blockDragSource = null;
+        /** Whether hover or focus currently wants a handle for `blockDragSource`.
+         *  Tracked apart from the handle's `display`, which the viewport clip also drives: a handle
+         *  withdrawn because its block scrolled out of view has to come back when it scrolls in. */
+        this.blockHandleWanted = false;
         this.blockDragCleanup = [];
         /** Block boxes measured at drag start — see `BlockDropZone`. Empty when no drag is in flight. */
         this.dropZones = [];
@@ -1009,6 +1080,7 @@ export class DocxEditor {
             document.removeEventListener("mouseup", this.onMouseUp, true);
         }
         this.clearDragSelection();
+        this.clearFindMatches();
         this.teardownBlockDrag();
         this.gutter?.dispose();
         this.gutter = null;
@@ -1151,12 +1223,49 @@ export class DocxEditor {
         }
         return null;
     }
+    /**
+     * The rectangle the floating handle may occupy: the window, narrowed by every ancestor that
+     * clips its overflow.
+     *
+     * The handle is `position: fixed`, so it is placed in viewport coordinates and no ancestor's
+     * overflow clips it for us. But the editor is routinely mounted inside a bounded scroller —
+     * the ribbon puts its surface in one, inside a clipped card — and a block scrolled out of that
+     * scroller has to take its handle with it rather than leave it parked over the host's chrome.
+     *
+     * Gated on the computed `overflow` rather than on whether an element scrolls right now, so the
+     * answer does not depend on how much content happens to be loaded.
+     */
+    blockHandleClipRect() {
+        const view = this.container.ownerDocument.defaultView;
+        const clip = {
+            top: 0,
+            left: 0,
+            right: view?.innerWidth ?? Number.MAX_SAFE_INTEGER,
+            bottom: view?.innerHeight ?? Number.MAX_SAFE_INTEGER,
+        };
+        for (let el = this.editRoot; el; el = el.parentElement) {
+            const style = view?.getComputedStyle(el);
+            if (!style || (style.overflowX === "visible" && style.overflowY === "visible"))
+                continue;
+            const box = el.getBoundingClientRect();
+            if (style.overflowY !== "visible") {
+                clip.top = Math.max(clip.top, box.top);
+                clip.bottom = Math.min(clip.bottom, box.bottom);
+            }
+            if (style.overflowX !== "visible") {
+                clip.left = Math.max(clip.left, box.left);
+                clip.right = Math.min(clip.right, box.right);
+            }
+        }
+        return clip;
+    }
     showBlockHandle(unit) {
         const handle = this.blockDragHandle;
         if (!handle || !this.isMovableBlockUnit(unit))
             return;
         const changed = unit !== this.blockDragSource;
         this.blockDragSource = unit;
+        this.blockHandleWanted = true;
         // A block the engine will not move anywhere — one owning a section break, or already carrying
         // revision markup a tracked move would have to re-wrap — gets no handle rather than a handle
         // that always fails. Asking costs an engine round trip, so hovering only ever CONSUMES a
@@ -1170,21 +1279,40 @@ export class DocxEditor {
         if (changed && known === undefined)
             this.prefetchBlockMoveTargets(unit);
         const rect = unit.getBoundingClientRect();
+        // The handle belongs to the editor's viewport, not the window's. A block scrolled out of that
+        // viewport gets no handle at all: clamping one back into view would leave a grip sitting next
+        // to a block that is not there — and clamping to the WINDOW, as this used to, parked it on
+        // whatever chrome the host draws above the editor.
+        const clip = this.blockHandleClipRect();
+        if (rect.bottom <= clip.top || rect.top >= clip.bottom
+            || rect.right <= clip.left || rect.left >= clip.right) {
+            // A gesture in flight owns the handle: it is the drag's own source element, and an open
+            // move menu is anchored to it and hands focus back to it on Escape. Withdrawing it
+            // mid-gesture is the same mistake as leaving it behind — mirror `hideBlockHandle`'s guard
+            // and leave it where the gesture put it.
+            if (!this.blockDragging && this.blockMoveMenu?.style.display !== "block")
+                handle.style.display = "none";
+            return;
+        }
         handle.style.display = "flex";
-        handle.style.left = `${Math.max(4, rect.left - 32)}px`;
-        handle.style.top = `${Math.max(4, rect.top + (unit.tagName === "TABLE" ? 6 : Math.max(0, (rect.height - 28) / 2)))}px`;
+        // A block only partly in view keeps its handle, pulled to the edge it is disappearing past.
+        const top = rect.top
+            + (unit.tagName === "TABLE" ? 6 : Math.max(0, (rect.height - BLOCK_HANDLE_HEIGHT) / 2));
+        handle.style.left = `${clampToRange(rect.left - (BLOCK_HANDLE_WIDTH + BLOCK_HANDLE_GAP), clip.left, clip.right - BLOCK_HANDLE_WIDTH)}px`;
+        handle.style.top = `${clampToRange(top, clip.top, clip.bottom - BLOCK_HANDLE_HEIGHT)}px`;
         const preview = blockPreviewText(unit);
         handle.setAttribute("aria-label", preview ? `Move block: ${preview}` : "Move block");
     }
     hideBlockHandle() {
         if (this.blockDragging || this.blockMoveMenu?.style.display === "block")
             return;
+        this.blockHandleWanted = false;
         if (this.blockDragHandle)
             this.blockDragHandle.style.display = "none";
     }
     positionBlockHandle() {
         const source = this.currentBlockDragSource();
-        if (source && this.blockDragHandle?.style.display !== "none")
+        if (source && this.blockHandleWanted)
             this.showBlockHandle(source);
     }
     /** Draw the drop line on `zone`'s requested edge, or take it away when there is no target. */
@@ -1663,6 +1791,7 @@ export class DocxEditor {
         this.blockMoveMenu = null;
         this.blockMoveLive = null;
         this.blockDragSource = null;
+        this.blockHandleWanted = false;
         this.blockDragging = false;
         this.blockDragPointerDown = false;
     }
@@ -3642,16 +3771,75 @@ export class DocxEditor {
         }
         return out;
     }
-    /** Select a match and scroll it into view. */
+    /**
+     * Select a match, focus its block and scroll it into view — the caret lands on the hit, so
+     * typing continues in the document. A find box that is still being typed into wants
+     * `showFindMatches` instead; this is the commit step (closing the bar, jumping in to edit).
+     */
     selectMatch(match) {
         if (!match.block.isConnected)
             return;
+        this.clearFindMatches();
         this.activeBlock = match.block;
         selectRange(match.block, match.start, match.length);
         match.block.scrollIntoView({ block: "center", behavior: "smooth" });
     }
-    /** Replace one match's text (formatting of the surrounding run is inherited). */
-    replaceMatch(match, replacement) {
+    /**
+     * Paint `matches` and scroll the one at `activeIndex` into view WITHOUT moving focus or the
+     * caret. This is what a find field calls on every keystroke: the document shows where the hits
+     * are and rides to the current one, while the keyboard stays in the search box.
+     *
+     * Falls back to the document selection where the CSS Custom Highlight API is missing — still
+     * without focusing the block, so the next character typed goes to the search field either way.
+     */
+    showFindMatches(matches, activeIndex) {
+        const active = matches[activeIndex];
+        this.clearFindMatches();
+        if (!active || !active.block.isConnected)
+            return;
+        this.activeBlock = active.block;
+        const activeRange = contentRangeIn(active.block, active.start, active.length);
+        const registry = highlightRegistry();
+        if (registry && activeRange) {
+            ensureFindHighlightStyles(this.container.ownerDocument);
+            const rest = [];
+            for (let i = 0; i < matches.length && rest.length < FIND_PAINT_LIMIT; i++) {
+                if (i === activeIndex)
+                    continue;
+                const range = contentRangeIn(matches[i].block, matches[i].start, matches[i].length);
+                if (range)
+                    rest.push(range);
+            }
+            if (rest.length > 0)
+                registry.set(FIND_HIGHLIGHT, makeHighlight(rest));
+            registry.set(FIND_HIGHLIGHT_ACTIVE, makeHighlight([activeRange]));
+            findPaintOwner = this;
+        }
+        else if (activeRange) {
+            // No highlight registry (older Firefox/Safari): the document selection is the only paint
+            // available. It is not registry-owned, so `clearFindMatches` leaves it — the next
+            // `showFindMatches` or the closing `selectMatch` overwrites it.
+            const sel = this.container.ownerDocument.defaultView?.getSelection();
+            sel?.removeAllRanges();
+            sel?.addRange(activeRange);
+        }
+        active.block.scrollIntoView({ block: "center", behavior: "smooth" });
+    }
+    /** Drop the find painting (closing the find bar, or committing a match to the caret). */
+    clearFindMatches() {
+        if (findPaintOwner !== this)
+            return;
+        const registry = highlightRegistry();
+        registry?.delete(FIND_HIGHLIGHT);
+        registry?.delete(FIND_HIGHLIGHT_ACTIVE);
+        findPaintOwner = null;
+    }
+    /**
+     * Replace one match's text (formatting of the surrounding run is inherited). `focus: false`
+     * leaves the keyboard where it is — a Replace button pressed from the find bar must not drag
+     * the caret into the document mid-search.
+     */
+    replaceMatch(match, replacement, options = {}) {
         const block = match.block;
         if (this.closed || !block.isConnected)
             return false;
@@ -3669,7 +3857,7 @@ export class DocxEditor {
         if (!res.success)
             return false;
         const fresh = this.swapBlock(block, unid, res.modified?.[0]);
-        if (fresh)
+        if (fresh && options.focus !== false)
             selectRange(fresh, span.start, replacement.length);
         return true;
     }
@@ -3692,7 +3880,7 @@ export class DocxEditor {
                 if (!current.isConnected)
                     break;
                 const before = current;
-                if (this.replaceMatch({ block: current, start: m.start, length: m.length }, replacement)) {
+                if (this.replaceMatch({ block: current, start: m.start, length: m.length }, replacement, { focus: options.focus })) {
                     count++;
                     // swapBlock replaced the node; keep following it.
                     current = this.activeBlock && this.activeBlock !== before ? this.activeBlock : current;