@embedpdf/plugin-selection 2.14.3 → 2.15.0

package/dist/index.js

@@ -809,6 +809,7 @@ const _SelectionPlugin = class _SelectionPlugin extends BasePlugin {
       getBoundingRectForPage: (p, docId) => selectBoundingRectForPage(this.getDocumentState(getDocId(docId)), p),
       getBoundingRects: (docId) => selectBoundingRectsForAllPages(this.getDocumentState(getDocId(docId))),
       getSelectedText: (docId) => this.getSelectedText(getDocId(docId)),
+      setSelection: (range, docId) => this.applySelection(getDocId(docId), range),
       clear: (docId) => this.clearSelection(getDocId(docId)),
       copyToClipboard: (docId) => this.copyToClipboard(getDocId(docId)),
       getState: (docId) => this.getDocumentState(getDocId(docId)),
@@ -846,6 +847,7 @@ const _SelectionPlugin = class _SelectionPlugin extends BasePlugin {
       getBoundingRectForPage: (p) => selectBoundingRectForPage(this.getDocumentState(documentId), p),
       getBoundingRects: () => selectBoundingRectsForAllPages(this.getDocumentState(documentId)),
       getSelectedText: () => this.getSelectedText(documentId),
+      setSelection: (range) => this.applySelection(documentId, range),
       clear: () => this.clearSelection(documentId),
       copyToClipboard: () => this.copyToClipboard(documentId),
       getState: () => this.getDocumentState(documentId),
@@ -1213,6 +1215,137 @@ const _SelectionPlugin = class _SelectionPlugin extends BasePlugin {
     this.emitMenuPlacement(documentId, null);
     this.notifyAllPages(documentId);
   }
+  /**
+   * Programmatically apply (or restore) a text selection without going through
+   * the pointer drag flow. Useful for restoring a previously persisted selection
+   * or driving selection from code (e.g. search results).
+   *
+   * Geometry for every page spanned by the range is loaded on demand (the data
+   * comes from the WASM engine), so the returned task settles only once the
+   * selection rects have actually been computed.
+   *
+   * Passing `null` is equivalent to calling {@link clearSelection}.
+   *
+   * @returns a task that resolves once the selection has been applied.
+   */
+  applySelection(documentId, range) {
+    if (!this.state.documents[documentId]) {
+      return PdfTaskHelper.reject({
+        code: PdfErrorCode.NotFound,
+        message: `Selection state not found for document: ${documentId}`
+      });
+    }
+    if (range === null) {
+      this.clearSelection(documentId);
+      return PdfTaskHelper.resolve(void 0);
+    }
+    const validationError = this.validateRange(documentId, range);
+    if (validationError) {
+      return PdfTaskHelper.reject(validationError);
+    }
+    const normalized = this.normalizeRange(range);
+    const pages = [];
+    for (let p = normalized.start.page; p <= normalized.end.page; p++) {
+      pages.push(p);
+    }
+    const geoTasks = pages.map((p) => this.getOrLoadGeometry(documentId, p));
+    const result = PdfTaskHelper.create();
+    Task.all(geoTasks).wait(() => {
+      if (!this.state.documents[documentId]) {
+        result.reject({
+          code: PdfErrorCode.NotFound,
+          message: `Selection state not found for document: ${documentId}`
+        });
+        return;
+      }
+      const clamped = this.clampRangeToGeometry(documentId, normalized);
+      if (!clamped) {
+        result.reject({
+          code: PdfErrorCode.NotFound,
+          message: `Cannot apply selection: page(s) ${normalized.start.page}-${normalized.end.page} have no text geometry`
+        });
+        return;
+      }
+      this.selecting.set(documentId, false);
+      this.anchor.set(documentId, void 0);
+      const previouslyHighlighted = Object.keys(this.getDocumentState(documentId).rects).map(
+        Number
+      );
+      this.dispatch(startSelection(documentId));
+      this.dispatch(setSelection(documentId, clamped));
+      this.updateRectsAndSlices(documentId, clamped);
+      this.dispatch(endSelection(documentId));
+      this.selChange$.emit(documentId, clamped);
+      const pagesToNotify = new Set(previouslyHighlighted);
+      for (let p = clamped.start.page; p <= clamped.end.page; p++) {
+        pagesToNotify.add(p);
+      }
+      pagesToNotify.forEach((p) => this.notifyPage(documentId, p));
+      this.recalculateMenuPlacement(documentId);
+      result.resolve(void 0);
+    }, (error) => result.reject(error.reason));
+    return result;
+  }
+  /**
+   * Validate the structure and page bounds of a programmatic selection range.
+   * Returns a rejection reason when the input is invalid, or null when it is
+   * structurally sound. Glyph-index bounds are enforced separately, after the
+   * page geometry has loaded (see {@link clampRangeToGeometry}).
+   */
+  validateRange(documentId, range) {
+    var _a, _b;
+    const isValidPointer = (g) => !!g && typeof g === "object" && Number.isInteger(g.page) && Number.isInteger(g.index);
+    if (!range || typeof range !== "object" || !range.start || !range.end) {
+      return { code: PdfErrorCode.Unknown, message: "Invalid selection range: expected { start, end }" };
+    }
+    if (!isValidPointer(range.start) || !isValidPointer(range.end)) {
+      return {
+        code: PdfErrorCode.Unknown,
+        message: "Invalid selection range: start/end must have integer page and index"
+      };
+    }
+    if (range.start.index < 0 || range.end.index < 0) {
+      return { code: PdfErrorCode.Unknown, message: "Invalid selection range: glyph index cannot be negative" };
+    }
+    const pageCount = ((_b = (_a = this.getCoreDocument(documentId)) == null ? void 0 : _a.document) == null ? void 0 : _b.pageCount) ?? 0;
+    const minPage = Math.min(range.start.page, range.end.page);
+    const maxPage = Math.max(range.start.page, range.end.page);
+    if (minPage < 0 || maxPage >= pageCount) {
+      return {
+        code: PdfErrorCode.NotFound,
+        message: `Invalid selection range: page ${minPage < 0 ? minPage : maxPage} out of bounds [0, ${pageCount})`
+      };
+    }
+    return null;
+  }
+  /**
+   * Clamp the glyph indices of a (normalized) range to the number of glyphs
+   * available on the corresponding pages. Returns null when none of the
+   * spanned pages have any text geometry to select.
+   */
+  clampRangeToGeometry(documentId, range) {
+    const docState = this.getDocumentState(documentId);
+    const lastGlyphIndex = (page) => {
+      const geo = docState.geometry[page];
+      if (!geo || geo.runs.length === 0) return -1;
+      const lastRun = geo.runs[geo.runs.length - 1];
+      return lastRun.charStart + lastRun.glyphs.length - 1;
+    };
+    const startMax = lastGlyphIndex(range.start.page);
+    const endMax = lastGlyphIndex(range.end.page);
+    if (startMax < 0 && endMax < 0) return null;
+    const clampIndex = (index, max) => max < 0 ? 0 : Math.min(Math.max(index, 0), max);
+    return {
+      start: { page: range.start.page, index: clampIndex(range.start.index, startMax) },
+      end: { page: range.end.page, index: clampIndex(range.end.index, endMax) }
+    };
+  }
+  /** Order a range so that `start` never comes after `end`. */
+  normalizeRange(range) {
+    const { start, end } = range;
+    const forward = end.page > start.page || end.page === start.page && end.index >= start.index;
+    return forward ? { start, end } : { start: end, end: start };
+  }
   selectWord(documentId, page, charIndex, modeId) {
     const geo = this.getDocumentState(documentId).geometry[page];
     if (!geo) return;