@embedpdf/plugin-selection 2.15.0 → 3.0.0-next.0

package/dist/index.d.ts

@@ -1 +1,167 @@
-export * from './lib';
+import { PageObjectNumber, PluginContext } from "@embedpdf/core";
+import { InteractionCapability, InteractionHandler } from "@embedpdf/plugin-interaction";
+import { Point, Rect } from "@embedpdf/core-geometry";
+import { PageGeometrySnapshot, PdfRect } from "@embedpdf/engine-core/runtime";
+//#region src/types.d.ts
+/** A glyph address: a page + a flat glyph index within that page's geometry. */
+interface GlyphPointer {
+  pon: PageObjectNumber;
+  glyph: number;
+}
+/** Anchor = where the drag began, focus = the current end. Inclusive. */
+interface SelectionRange {
+  anchor: GlyphPointer;
+  focus: GlyphPointer;
+}
+interface SelectionEndpoint {
+  pon: PageObjectNumber;
+  rect: Rect;
+}
+interface SelectionSnapshot {
+  pages: Array<{
+    pon: PageObjectNumber;
+    rects: Rect[];
+  }>;
+  start: SelectionEndpoint | null;
+  end: SelectionEndpoint | null;
+  direction: 'forward' | 'backward';
+}
+interface SelectionState {
+  selection: SelectionRange | null;
+  /** Derived highlight rects per page, in CONTENT space (y-down, PDF units). */
+  rects: Record<number, Rect[]>;
+  /** Pages whose text geometry has loaded (so the layer re-renders when ready). */
+  loaded: Record<number, boolean>;
+  /** When a consumer owns the selection visual (e.g. a markup tool draws its own
+   *  preview), the default highlight rects are suppressed. */
+  highlightHidden: boolean;
+}
+type SelectionAction = {
+  type: 'PAGE_LOADED';
+  pon: PageObjectNumber;
+} | {
+  type: 'SET';
+  selection: SelectionRange;
+  rects: Record<number, Rect[]>;
+} | {
+  type: 'CLEAR';
+} | {
+  type: 'SET_HIGHLIGHT_HIDDEN';
+  hidden: boolean;
+};
+interface SelectionCapability {
+  /** Warm a page's text geometry (idempotent). Layers call this when a page mounts. */
+  ensurePage(pon: PageObjectNumber): void;
+  isLoaded(pon: PageObjectNumber): boolean;
+  /** Is a content-space point on (or near) text? Drives the I-beam vs pointer cursor. */
+  isOverText(pon: PageObjectNumber, point: Point): boolean;
+  /** Begin a caret selection at a page point. Returns false if not near any text. */
+  beginAt(pon: PageObjectNumber, point: Point): boolean;
+  /** Double-click: select the word around the point. */
+  selectWord(pon: PageObjectNumber, point: Point): void;
+  /** Triple-click: select the whole visual line around the point. */
+  selectLine(pon: PageObjectNumber, point: Point): void;
+  /** Extend the current selection to a page point (drag). */
+  extendTo(pon: PageObjectNumber, point: Point): void;
+  end(): void;
+  clear(): void;
+  /** Coherent read-model for consumers that create annotations or selection UI. */
+  snapshot(): SelectionSnapshot;
+  /** Highlight rects for a page, in content space — the layer's only input. */
+  rectsForPage(pon: PageObjectNumber): Rect[];
+  hasSelection(): boolean;
+  /** The pages the current selection covers (those with at least one rect) — so a
+   *  cross-page action (e.g. text-markup creation) can fan out per page. */
+  selectedPages(): PageObjectNumber[];
+  /** Fires whenever the selection rects change (e.g. drag-extend) — for live preview. */
+  onChange(cb: () => void): () => void;
+  /** Fires when a selection gesture ends (pointer-up) — the commit point. */
+  onCommit(cb: () => void): () => void;
+  /** Suppress / restore the default highlight visual (a consumer drawing its own). */
+  setHighlightVisible(visible: boolean): void;
+  highlightVisible(): boolean;
+}
+declare const SelectionToken: import("@embedpdf/core").CapabilityToken<SelectionCapability>;
+//#endregion
+//#region src/selection.plugin.d.ts
+/**
+ * Text selection — document-scoped, requires the interaction hub. In `init` it
+ * registers ITS pointer handler with the hub; the hub owns the pointer stream
+ * and arbitration. Works with `<Stage>` or a standalone `<PageView>` — selection
+ * only needs the page coordinate context + the engine's text geometry.
+ */
+declare const selectionPlugin: () => import("@embedpdf/core").PluginDef<SelectionState, SelectionAction, SelectionCapability>;
+//#endregion
+//#region src/capability.d.ts
+/**
+ * The selection capability. The reducer state holds the selection range, the
+ * derived content-space rects (per page), and per-page loaded flags; the (large,
+ * non-serializable) per-page text geometry is cached HERE in the closure.
+ *
+ * Selection is cross-page: glyphs are ordered globally by (pageIndex, glyph), so
+ * a drag from page 2 into page 4 selects the tail of 2, all of 3, and the head of
+ * 4. `recompute` rebuilds the merged line rects for every loaded page in the span
+ * and re-runs whenever a mid-span page finishes loading.
+ */
+declare function createSelectionCapability(ctx: PluginContext<SelectionState, SelectionAction>): SelectionCapability;
+//#endregion
+//#region src/handler.d.ts
+/**
+ * The text-selection pointer handler. It is live only under tools that enable the
+ * `'text-select'` tag (the built-in `pointer` tool does; `pan` does not — so
+ * switching to pan disables text selection with zero special-casing here).
+ *
+ *  - single click        → deselect; records an anchor but selects NOTHING until
+ *                          the pointer moves past the drag threshold (Chrome/Acrobat feel)
+ *  - single-click + drag → caret selection from the anchor (extends across pages)
+ *  - double-click        → select the word
+ *  - triple-click        → select the visual line
+ *  - down off-text       → deselect, and DON'T capture (so it can't block)
+ *  - hover               → I-beam only when over text, else the pointer cursor
+ */
+declare function createTextSelectHandler(selection: SelectionCapability, interaction: InteractionCapability): InteractionHandler;
+//#endregion
+//#region src/reducer.d.ts
+declare const initialSelectionState: SelectionState;
+declare const selectionReducer: (state: SelectionState, action: SelectionAction) => SelectionState;
+//#endregion
+//#region src/geometry.d.ts
+/** One glyph in content space. `loose` builds selection rects; `tight` hit-tests. */
+interface GlyphInfo {
+  loose: Rect;
+  tight?: Rect;
+  flags: number;
+}
+/** A contiguous run of glyphs (a text object). `rect` is its loose enclosing box. */
+interface RunInfo {
+  start: number;
+  count: number;
+  rect: Rect;
+  fontSize?: number;
+}
+/** A page's text laid out in content space: a flat glyph list + the run structure. */
+interface PageText {
+  glyphs: GlyphInfo[];
+  runs: RunInfo[];
+}
+/**
+ * Flatten a page's text geometry into content-space glyphs + runs. Rotation does
+ * NOT enter here — the overlay rides the page's CSS rotation, so glyphs stay in
+ * un-rotated content space (the crop-relative y-flip is the only conversion).
+ */
+declare function buildPageText(snapshot: PageGeometrySnapshot, crop: PdfRect, rotation: 0 | 90 | 180 | 270, userUnit: number): PageText;
+/**
+ * The glyph index at a content-space point, or null when nothing is near (so the
+ * caller can show the pointer cursor off-text). PDFium `GetIndexAtPos`: exact
+ * tight-box containment first, then a tolerance pass (closest by Manhattan
+ * distance within `toleranceFactor × average glyph height`).
+ */
+declare function glyphAt(text: PageText, p: Point, toleranceFactor?: number): number | null;
+/** Double-click: the word around `i` (walk to space/empty glyphs both ways). */
+declare function expandToWord(text: PageText, i: number): [number, number];
+/** Triple-click: the full visual line — runs whose vertical extent overlaps the anchor run's. */
+declare function expandToLine(text: PageText, i: number): [number, number];
+declare function rectsForRange(text: PageText, from: number, to: number): Rect[];
+//#endregion
+export { type GlyphInfo, type GlyphPointer, type PageText, type RunInfo, type SelectionAction, type SelectionCapability, type SelectionEndpoint, type SelectionRange, type SelectionSnapshot, type SelectionState, SelectionToken, buildPageText, createSelectionCapability, createTextSelectHandler, expandToLine, expandToWord, glyphAt, initialSelectionState, rectsForRange, selectionPlugin, selectionReducer };
+//# sourceMappingURL=index.d.ts.map