react-pdf-highlighter-plus 1.1.4 → 1.2.0

package/README.md

@@ -46,8 +46,13 @@
 | **PDF Search** | Search through all PDF text with next/previous navigation |
 | **PDF Export** | Export annotated PDF with all highlights embedded |
 | **Local PDF Worker** | Uses the packaged PDF.js worker by default |
-| **Light/Dark Theme** | Eye-friendly dark mode with customizable intensity |
-| **Zoom Support** | Full zoom functionality with position-independent data |
+| **Light/Dark Theme** | Hue-preserving dark mode (OKLab recolor) — photos & colors stay readable |
+| **Zoom Support** | Buttons, **pinch / ctrl+wheel zoom**, position-independent data |
+| **Smooth Scroll** | Animated scroll-to-highlight (respects reduced-motion) |
+| **Deep Linking** | `initialPage` + `onPageChange` for `?page=N` style navigation |
+| **Locate Text** | `getTextPosition` — turn any quote into a precise highlight (citations) |
+| **Read Aloud** | Text-to-speech that highlights & follows each sentence (recipe) |
+| **Fast Loading** | Progressive range loading, auth headers, document caching |
 | **Fully Customizable** | Exposed styling on all components |
 
 ## Quick Links
@@ -299,10 +304,13 @@ highlighterUtilsRef.current?.clearSearch();
 
 ## Light/Dark Theme
 
-Toggle between light and dark modes with customizable styling for comfortable reading.
+Dark mode recolors each page **at render time** using a hue-preserving OKLab map —
+white paper maps to a dark background and black text to a light foreground, while
+**colors keep their hue and embedded photos keep their pixels** (unlike a CSS
+`invert()` filter). Highlights, the text selection, and the left panel all adapt.
 
 ```tsx
-// Enable dark mode
+// Enable dark mode (warm-gray default palette)
 <PdfHighlighter
   pdfDocument={pdfDocument}
   theme={{ mode: "dark" }}
@@ -311,12 +319,15 @@ Toggle between light and dark modes with customizable styling for comfortable re
   <HighlightContainer />
 </PdfHighlighter>
 
-// Customize dark mode intensity and colors
+// Customize the dark palette
 <PdfHighlighter
   pdfDocument={pdfDocument}
   theme={{
     mode: "dark",
-    darkModeInvertIntensity: 0.85,  // Softer (0.8-1.0)
+    darkModeColors: {
+      background: "#141210", // replaces white paper
+      foreground: "#eae6e0", // replaces black text / line-art
+    },
     containerBackgroundColor: "#3a3a3a",
     scrollbarThumbColor: "#6b6b6b",
     scrollbarTrackColor: "#2c2c2c",
@@ -327,25 +338,146 @@ Toggle between light and dark modes with customizable styling for comfortable re
 </PdfHighlighter>
 ```
 
-**Features:**
-- Eye-friendly dark mode using CSS filter inversion
-- Customizable inversion intensity (0.8-1.0)
-- Preserve original highlight colors in dark mode
-- Custom scrollbar styling
-- Full theming control for container background
-
-**Inversion Intensity Guide:**
-| Value | Result | Use Case |
-|-------|--------|----------|
-| `1.0` | Pure black | High contrast |
-| `0.9` | Dark gray (~#1a1a1a) | **Recommended** |
-| `0.85` | Softer gray (~#262626) | Long reading sessions |
-| `0.8` | Medium gray (~#333333) | Maximum comfort |
+**Highlights:**
+- Hue-preserving recolor (red stays red, blue links stay blue); photos untouched.
+- Highlights stay readable: translucent fill + a border, with no `mix-blend` wash-out.
+- Scroll **and** zoom are preserved when toggling the theme.
+- `LeftPanel` accepts `mode="dark"` so the outline/thumbnails panel matches.
+- Drawing/shape default ink becomes white in dark mode.
+
+> **Deprecated:** `theme.darkModeInvertIntensity` is ignored — dark mode no longer
+> uses a CSS `invert()` filter. Use `theme.darkModeColors` instead.
 
 [Full Documentation →](docs/theming.md)
 
 ---
 
+## Loading & Performance
+
+`PdfLoader` loads documents progressively and caches them.
+
+```tsx
+<PdfLoader
+  document="https://api.example.com/files/report.pdf"
+  // Fetch only the pages needed to render first (needs server HTTP range support)
+  disableAutoFetch={true}
+  // Auth / cross-origin
+  httpHeaders={{ Authorization: `Bearer ${token}` }}
+  withCredentials={false}
+  // Reuse the same URL instantly on remount / re-open (default true)
+  enableCache={true}
+>
+  {(pdfDocument) => <PdfHighlighter pdfDocument={pdfDocument} /* … */ />}
+</PdfLoader>
+```
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `disableAutoFetch` | `true` | Fetch pages on demand instead of the whole file (first page shows fast on range-capable servers) |
+| `disableStream` | `false` | Disable progressive streaming |
+| `rangeChunkSize` | pdf.js | Size of each range request in bytes |
+| `httpHeaders` | – | Extra request headers (e.g. an auth token) |
+| `withCredentials` | `false` | Send cookies with the request |
+| `enableCache` | `true` | Cache the loaded document by URL (also dedupes StrictMode double-mount) |
+| `beforeLoad` | spinner | Render while loading; receives progress or `null` |
+
+> Progressive loading requires the server to support HTTP range requests
+> (`Accept-Ranges: bytes`) **and** expose `Content-Range` via CORS.
+
+---
+
+## Navigation, Zoom & Smooth Scroll
+
+```tsx
+<PdfHighlighter
+  pdfDocument={pdfDocument}
+  initialPage={12}                         // jump here on first load (deep-link)
+  onPageChange={(page) => syncUrl(page)}    // current page changed
+  onZoomChange={(scale) => setZoom(scale)}  // pinch / ctrl+wheel zoom changed
+  highlights={highlights}
+>
+  <HighlightContainer />
+</PdfHighlighter>
+```
+
+- **Pinch / ctrl(⌘)+wheel zoom** is built in — smooth (GPU transform during the
+  gesture, one crisp re-render on settle), anchored to the cursor.
+- **`scrollToHighlight(highlight)`** (from `usePdfHighlighterContext`) now scrolls
+  **smoothly** and respects `prefers-reduced-motion`.
+- `initialPage` is applied once on load; `onPageChange` fires as the visible page
+  changes — wire them to a `?page=N` URL for deep links.
+
+---
+
+## Locating Text (Citations)
+
+`getTextPosition` finds a piece of text in the PDF and returns a precise
+`ScaledPosition` — turn an external quote (e.g. an AI citation) into a highlight
+you can render or scroll to. Matching ignores whitespace/line-wraps and falls
+back to fuzzy matching.
+
+```tsx
+import { getTextPosition } from "react-pdf-highlighter-plus";
+
+const match = await getTextPosition(pdfDocument, "the exact or near-exact quote");
+if (match) {
+  const citation = {
+    id: "cite-1",
+    type: "text",
+    content: { text: match.matchedText },
+    position: match.position,   // precise rects, page-independent
+  };
+  setHighlights((prev) => [citation, ...prev]);
+  utils.scrollToHighlight(citation); // smooth scroll + flash
+}
+// match: { position, pageNumber, matchedText, confidence: "exact" | "fuzzy" }
+```
+
+---
+
+## Read Aloud (Text-to-Speech)
+
+Build a read-aloud / "PDF to audio" experience: speak the document and
+highlight + auto-scroll to each sentence as it's read. The pieces are already
+here — `extractSentences` gives the ordered script (text + position) and
+`scrollToHighlight` follows along. The TTS engine is yours to choose (the
+browser `speechSynthesis`, or a cloud voice).
+
+```tsx
+import { extractSentences } from "react-pdf-highlighter-plus";
+
+// 1. Build the ordered script once.
+const sentences = (
+  await extractSentences(pdfDocument, { includePositions: true })
+).filter((s) => s.position);
+
+// 2. Speak each sentence; highlight + scroll as it starts.
+function readFrom(index: number) {
+  const s = sentences[index];
+  if (!s) return;
+
+  const reading = {
+    id: "reading",
+    type: "text",
+    content: { text: s.text },
+    position: s.position!,
+  };
+  setHighlights((prev) => [reading, ...prev.filter((h) => h.id !== "reading")]);
+  utils.scrollToHighlight(reading); // smooth follow
+
+  const utter = new SpeechSynthesisUtterance(s.text);
+  utter.onend = () => readFrom(index + 1); // advance
+  speechSynthesis.speak(utter);
+}
+
+readFrom(0);
+```
+
+Swap `speechSynthesis` for any engine — sentence-level sync needs no word
+timing. See the example app for a full transport (play/pause/seek/speed/voice).
+
+---
+
 ## PDF Export
 
 Export your annotated PDF with all highlights embedded.

package/dist/esm/index.d.ts

@@ -476,8 +476,8 @@ declare const usePdfHighlighterContext: () => PdfHighlighterUtils;
  */
 interface PdfHighlighterTheme {
     /**
-     * Theme mode - controls PDF page color inversion.
-     * In dark mode, PDF pages are inverted for comfortable reading.
+     * Theme mode. In dark mode, pages are recolored at draw time (hue-preserving,
+     * photos kept) using {@link PdfHighlighterTheme.darkModeColors}.
      * @default "light"
      */
     mode?: "light" | "dark";
@@ -504,8 +504,24 @@ interface PdfHighlighterTheme {
      * - 0.85 = Softer gray ~#262626 (very comfortable)
      * - 0.8 = Medium gray ~#333333 (maximum softness)
      * @default 0.9
+     * @deprecated Dark mode now recolors at draw time (OKLab, hue-preserving,
+     * photos untouched) instead of a CSS `invert()` filter. This value is
+     * ignored. Use {@link PdfHighlighterTheme.darkModeColors} instead.
      */
     darkModeInvertIntensity?: number;
+    /**
+     * Dark-mode recolor palette. White paper maps to `background` and black
+     * text/line-art to `foreground`, recolored per-color at draw time (OKLab
+     * ramp) so hues are preserved and embedded photos keep their pixels.
+     * Only used when `mode === "dark"`.
+     * @default { background: "#141210", foreground: "#eae6e0" }
+     */
+    darkModeColors?: {
+        /** Replaces the white paper background. */
+        background: string;
+        /** Replaces black text and line art. */
+        foreground: string;
+    };
 }
 /**
  * The props type for {@link PdfHighlighter}.
@@ -527,6 +543,27 @@ interface PdfHighlighterProps {
      * What scale to render the PDF at inside the viewer.
      */
     pdfScaleValue?: PdfScaleValue;
+    /**
+     * Fired when the user changes zoom by pinch / ctrl+wheel gesture, with the new
+     * numeric scale. Use it to keep an external zoom indicator / `pdfScaleValue`
+     * state in sync.
+     *
+     * @param scale - The new numeric scale (e.g. 1.25).
+     */
+    onZoomChange?(scale: number): void;
+    /**
+     * Page to scroll to once the document first finishes loading (1-indexed).
+     * Use for deep-linking (e.g. `?page=12`) or restoring a saved position.
+     * Applied only on initial load, not on subsequent re-renders.
+     */
+    initialPage?: number;
+    /**
+     * Callback fired whenever the current (most visible) page changes, including
+     * the initial page. Use to sync the page into a URL/localStorage.
+     *
+     * @param pageNumber - The new current page (1-indexed).
+     */
+    onPageChange?(pageNumber: number): void;
     /**
      * Callback triggered whenever a user finishes making a mouse selection or has
      * selected text.
@@ -690,7 +727,7 @@ interface PdfHighlighterProps {
  *
  * @category Component
  */
-declare const PdfHighlighter: ({ highlights, onScrollAway, pdfScaleValue, onSelection: onSelectionFinished, onCreateGhostHighlight, onRemoveGhostHighlight, selectionTip, enableAreaSelection, areaSelectionMode, mouseSelectionStyle, pdfDocument, children, textSelectionColor, utilsRef, style, enableFreetextCreation, onFreetextClick, enableImageCreation, onImageClick, enableDrawingMode, onDrawingComplete, onDrawingCancel, drawingStrokeColor, drawingStrokeWidth, enableShapeMode, onShapeComplete, onShapeCancel, shapeStrokeColor, shapeStrokeWidth, theme: userTheme, }: PdfHighlighterProps) => React.JSX.Element;
+declare const PdfHighlighter: ({ highlights, onScrollAway, pdfScaleValue, onZoomChange, initialPage, onPageChange, onSelection: onSelectionFinished, onCreateGhostHighlight, onRemoveGhostHighlight, selectionTip, enableAreaSelection, areaSelectionMode, mouseSelectionStyle, pdfDocument, children, textSelectionColor, utilsRef, style, enableFreetextCreation, onFreetextClick, enableImageCreation, onImageClick, enableDrawingMode, onDrawingComplete, onDrawingCancel, drawingStrokeColor: drawingStrokeColorProp, drawingStrokeWidth, enableShapeMode, onShapeComplete, onShapeCancel, shapeStrokeColor: shapeStrokeColorProp, shapeStrokeWidth, theme: userTheme, }: PdfHighlighterProps) => React.JSX.Element;
 
 /**
  * Style options for text highlight appearance.
@@ -1408,12 +1445,13 @@ interface PdfLoaderProps {
      */
     document: string | URL | TypedArray | DocumentInitParameters;
     /**
-     * Callback to render content before the PDF document is loaded.
+     * Callback to render content before the PDF document is loaded. Receives the
+     * PDF.js progress, or `null` before any progress is known (e.g. a cache hit).
      *
-     * @param progress - PDF.js progress status.
+     * @param progress - PDF.js progress status, or null.
      * @returns - Component to be rendered in space of the PDF document while loading.
      */
-    beforeLoad?(progress: OnProgressParameters): ReactNode;
+    beforeLoad?(progress: OnProgressParameters | null): ReactNode;
     /**
      * Component to render in the case of any PDF loading errors.
      *
@@ -1440,13 +1478,36 @@ interface PdfLoaderProps {
      * worker from the installed pdfjs-dist package so bundlers can emit it locally.
      */
     workerSrc?: string;
+    /**
+     * Only fetch the pages needed to render, instead of background-downloading the
+     * whole file. Makes the first page appear fast for large PDFs served over an
+     * API — provided the server supports HTTP range requests (`Accept-Ranges:
+     * bytes`). Has no effect for servers without range support or for raw bytes.
+     * @default true
+     */
+    disableAutoFetch?: boolean;
+    /** Disable progressive streaming of the response. @default false */
+    disableStream?: boolean;
+    /** Size (bytes) of each range request when streaming. PDF.js default ~64KB. */
+    rangeChunkSize?: number;
+    /** Send credentials (cookies) with the document request. */
+    withCredentials?: boolean;
+    /** Extra HTTP headers for the document request (e.g. an auth token). */
+    httpHeaders?: Record<string, string>;
+    /**
+     * Cache the loaded document so re-opening the same URL (or a StrictMode/
+     * remount) reuses it instead of re-downloading. Only URL-based documents are
+     * cached. Disable if the same URL can return different content.
+     * @default true
+     */
+    enableCache?: boolean;
 }
 /**
  * A component for loading a PDF document and passing it to a child.
  *
  * @category Component
  */
-declare const PdfLoader: ({ document, beforeLoad, errorMessage, children, onError, workerSrc, }: PdfLoaderProps) => React.ReactNode;
+declare const PdfLoader: ({ document, beforeLoad, errorMessage, children, onError, workerSrc, disableAutoFetch, disableStream, rangeChunkSize, withCredentials, httpHeaders, enableCache, }: PdfLoaderProps) => React.ReactNode;
 
 /**
  * A set of utilities for rendering highlights. Designed to be used within a
@@ -1566,6 +1627,37 @@ declare const extractSentences: (pdfDocument: PDFDocumentProxy, options?: Extrac
 declare const sentenceToHighlight: (sentence: PdfSentence, options?: {
     id?: string;
 }) => Highlight;
+/**
+ * The result of {@link getTextPosition}.
+ *
+ * @category Type
+ */
+interface TextPositionMatch {
+    /** Scaled position of the matched text, ready to use as a highlight position. */
+    position: ScaledPosition;
+    /** 1-indexed page the match was found on. */
+    pageNumber: number;
+    /** The exact document text that was matched. */
+    matchedText: string;
+    /** "exact" = whitespace-insensitive verbatim, "fuzzy" = approximate match. */
+    confidence: "exact" | "fuzzy";
+}
+/**
+ * Locate a piece of text in the PDF and return its precise position — the rects
+ * of the exact phrase (sub-item, per-line), not a whole sentence. Use it to turn
+ * an external quote / citation into a highlight you can render or scroll to.
+ *
+ * Robust to PDF quirks: matching ignores whitespace (so line-wraps and spacing
+ * differences don't matter) and falls back to bounded fuzzy matching for minor
+ * differences (hyphenation, OCR, slight paraphrase). Returns the first match
+ * (optionally restrict the page range), or null.
+ *
+ * @category Utility
+ */
+declare const getTextPosition: (pdfDocument: PDFDocumentProxy, query: string, options?: {
+    pages?: "all" | number[];
+    fuzzy?: boolean;
+}) => Promise<TextPositionMatch | null>;
 
 /** Style configuration for outline items */
 interface OutlineItemStyles {
@@ -1846,7 +1938,10 @@ interface LeftPanelProps {
     thumbnailWidth?: number;
     /** Children for custom content */
     children?: React.ReactNode;
-    /** Theme customization */
+    /** Color scheme. "dark" swaps in a dark default palette; `theme` overrides
+     *  individual colors on top of whichever preset is chosen. @default "light" */
+    mode?: "light" | "dark";
+    /** Theme customization (merged over the mode preset) */
     theme?: LeftPanelTheme;
     /** Show page count in footer */
     showFooter?: boolean;
@@ -2030,4 +2125,4 @@ declare function usePageNavigation(options: UsePageNavigationOptions): UsePageNa
 
 declare const exportPdf: typeof exportPdf$1;
 
-export { AreaHighlight, type AreaHighlightProps, type AreaHighlightStyle, type Content, DocumentOutline, type DocumentOutlineClassNames, type DocumentOutlineProps, type DocumentOutlineStyles, DrawingCanvas, type DrawingCanvasProps, DrawingHighlight, type DrawingHighlightProps, type DrawingPoint, type DrawingStroke, type ExportPdfOptions, type ExportableHighlight, type ExtractSentencesOptions, type FooterClassNames, type FooterStyles, FreetextHighlight, type FreetextHighlightProps, type FreetextStyle, type GhostHighlight, type Highlight, type HighlightBindings, type HighlightContainerUtils, type HighlightType, ImageHighlight, type ImageHighlightProps, type LTWH, type LTWHP, LeftPanel, type LeftPanelProps, type LeftPanelTab, type LeftPanelTheme, type LeftPanelUtils, MonitoredHighlightContainer, type MonitoredHighlightContainerProps, OutlineItem, type OutlineItemClassNames, type OutlineItemProps, type OutlineItemRenderProps, type OutlineItemStyles, type Page, type PdfColumnDetection, type PdfExtractedPage, PdfHighlighter, type PdfHighlighterProps, type PdfHighlighterTheme, type PdfHighlighterUtils, PdfLoader, type PdfLoaderProps, type PdfReadingOrder, type PdfScaleValue, type PdfSearchOptions, type PdfSelection, type PdfSentence, type PdfSentenceSource, type PdfTextColumn, type PdfTextItem, type PdfTextUnit, type PdfTextUnitType, type ProcessedOutlineItem, type Scaled, type ScaledPosition, ShapeCanvas, type ShapeCanvasProps, type ShapeData, ShapeHighlight, type ShapeHighlightProps, type ShapeStyle, type ShapeType, SignaturePad, type SignaturePadProps, type TabClassNames, type TabStyles, TextHighlight, type TextHighlightProps, type TextHighlightStyle, type ThumbnailData, ThumbnailItem, type ThumbnailItemProps, ThumbnailPanel, type ThumbnailPanelProps, type Tip, type ToggleButtonClassNames, type ToggleButtonStyles, type ViewportHighlight, type ViewportPosition, exportPdf, extractPageTextItems, extractSentences, extractTextUnits, scaledPositionToViewport, sentenceToHighlight, useDocumentOutline, useHighlightContainerContext, useLeftPanelContext, usePageNavigation, usePdfHighlighterContext, useThumbnails, viewportPositionToScaled };
+export { AreaHighlight, type AreaHighlightProps, type AreaHighlightStyle, type Content, DocumentOutline, type DocumentOutlineClassNames, type DocumentOutlineProps, type DocumentOutlineStyles, DrawingCanvas, type DrawingCanvasProps, DrawingHighlight, type DrawingHighlightProps, type DrawingPoint, type DrawingStroke, type ExportPdfOptions, type ExportableHighlight, type ExtractSentencesOptions, type FooterClassNames, type FooterStyles, FreetextHighlight, type FreetextHighlightProps, type FreetextStyle, type GhostHighlight, type Highlight, type HighlightBindings, type HighlightContainerUtils, type HighlightType, ImageHighlight, type ImageHighlightProps, type LTWH, type LTWHP, LeftPanel, type LeftPanelProps, type LeftPanelTab, type LeftPanelTheme, type LeftPanelUtils, MonitoredHighlightContainer, type MonitoredHighlightContainerProps, OutlineItem, type OutlineItemClassNames, type OutlineItemProps, type OutlineItemRenderProps, type OutlineItemStyles, type Page, type PdfColumnDetection, type PdfExtractedPage, PdfHighlighter, type PdfHighlighterProps, type PdfHighlighterTheme, type PdfHighlighterUtils, PdfLoader, type PdfLoaderProps, type PdfReadingOrder, type PdfScaleValue, type PdfSearchOptions, type PdfSelection, type PdfSentence, type PdfSentenceSource, type PdfTextColumn, type PdfTextItem, type PdfTextUnit, type PdfTextUnitType, type ProcessedOutlineItem, type Scaled, type ScaledPosition, ShapeCanvas, type ShapeCanvasProps, type ShapeData, ShapeHighlight, type ShapeHighlightProps, type ShapeStyle, type ShapeType, SignaturePad, type SignaturePadProps, type TabClassNames, type TabStyles, TextHighlight, type TextHighlightProps, type TextHighlightStyle, type TextPositionMatch, type ThumbnailData, ThumbnailItem, type ThumbnailItemProps, ThumbnailPanel, type ThumbnailPanelProps, type Tip, type ToggleButtonClassNames, type ToggleButtonStyles, type ViewportHighlight, type ViewportPosition, exportPdf, extractPageTextItems, extractSentences, extractTextUnits, getTextPosition, scaledPositionToViewport, sentenceToHighlight, useDocumentOutline, useHighlightContainerContext, useLeftPanelContext, usePageNavigation, usePdfHighlighterContext, useThumbnails, viewportPositionToScaled };