react-pdf-highlighter-plus 1.1.3 → 1.2.0

package/README.md

@@ -20,7 +20,7 @@
 </p>
 
 <p align="center">
-  Text highlights • Area highlights • Freetext notes • Images & signatures • Freehand drawing • PDF export
+  Text highlights • Area highlights • Freetext notes • Images & signatures • Freehand drawing • Shapes • Search • PDF export
 </p>
 
 ---
@@ -29,18 +29,30 @@
 
 `react-pdf-highlighter-plus` provides a highly customizable annotation experience for PDF documents in React applications. Built on [PDF.js](https://github.com/mozilla/pdf.js), it stores highlight positions in viewport-independent coordinates, making them portable across different screen sizes.
 
+<p align="center">
+  <img src="docs/react-pdf-highlight-plus.png" alt="react-pdf-highlighter-plus internal architecture" width="900">
+</p>
+
 ## Features
 
 | Feature | Description |
 |---------|-------------|
-| **Text Highlights** | Select and highlight text passages |
-| **Area Highlights** | Draw rectangular regions on PDFs |
-| **Freetext Notes** | Draggable, editable sticky notes with custom styling |
+| **Text Highlights** | Select and highlight text passages, restyle them, and copy their text |
+| **Area Highlights** | Draw rectangular regions on PDFs and copy intersecting PDF text |
+| **Freetext Notes** | Draggable, editable sticky notes with custom styling and compact mode |
 | **Images & Signatures** | Upload images or draw signatures directly on PDFs |
 | **Freehand Drawing** | Draw freehand annotations with customizable stroke |
+| **Shapes** | Add rectangles, circles, and arrows with editable stroke style |
+| **PDF Search** | Search through all PDF text with next/previous navigation |
 | **PDF Export** | Export annotated PDF with all highlights embedded |
-| **Light/Dark Theme** | Eye-friendly dark mode with customizable intensity |
-| **Zoom Support** | Full zoom functionality with position-independent data |
+| **Local PDF Worker** | Uses the packaged PDF.js worker by default |
+| **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
@@ -65,6 +77,8 @@ npm install react-pdf-highlighter-plus
 import "react-pdf-highlighter-plus/style/style.css";
 ```
 
+PDF.js worker setup is handled by the package by default. The build copies the local `pdf.worker.min.mjs` into the package output, so most apps do not need to configure `workerSrc` manually.
+
 ---
 
 ## Quick Start
@@ -126,6 +140,10 @@ Select text in the PDF to create highlights.
 />
 ```
 
+Text and area highlight toolbars include a copy button. After copying, the icon changes to a check mark for 1.5 seconds.
+
+[Full Documentation →](docs/text-area-highlights.md)
+
 ### 2. Area Highlights
 
 Hold `Alt` and drag to create rectangular highlights.
@@ -211,14 +229,12 @@ Draw freehand annotations directly on PDFs.
 import { DrawingHighlight } from "react-pdf-highlighter-plus";
 
 <PdfHighlighter
-  enableDrawingCreation={() => drawingMode}
-  onDrawingComplete={(position, dataUrl) => {
+  enableDrawingMode={drawingMode}
+  onDrawingComplete={(dataUrl, position, strokes) => {
     addHighlight({ type: "drawing", position, content: { image: dataUrl } });
   }}
-  drawingConfig={{
-    strokeColor: "#ff0000",
-    strokeWidth: 2,
-  }}
+  drawingStrokeColor="#ff0000"
+  drawingStrokeWidth={2}
 >
 
 // In your highlight container:
@@ -238,12 +254,63 @@ import { DrawingHighlight } from "react-pdf-highlighter-plus";
 
 ---
 
+## Shapes
+
+Create rectangle, circle, and arrow annotations with editable stroke color and width.
+
+```tsx
+<PdfHighlighter
+  enableShapeMode={shapeMode} // "rectangle" | "circle" | "arrow" | null
+  onShapeComplete={(position, shape) => {
+    addHighlight({ type: "shape", position, content: { shape } });
+  }}
+  shapeStrokeColor="#000000"
+  shapeStrokeWidth={2}
+>
+  <HighlightContainer />
+</PdfHighlighter>
+```
+
+Shape geometry stays in the normal highlight layer while the style controls render in the higher config layer.
+
+[Full Documentation →](docs/shape-highlights.md)
+
+---
+
+## PDF Search
+
+Use `utilsRef` to access document-wide search helpers backed by PDF.js `PDFFindController`.
+
+```tsx
+const highlighterUtilsRef = useRef<PdfHighlighterUtils>();
+
+<PdfHighlighter
+  pdfDocument={pdfDocument}
+  highlights={highlights}
+  utilsRef={(utils) => (highlighterUtilsRef.current = utils)}
+>
+  <HighlightContainer />
+</PdfHighlighter>
+
+highlighterUtilsRef.current?.search("TypeScript", {
+  highlightAll: true,
+  caseSensitive: false,
+});
+highlighterUtilsRef.current?.findNext();
+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" }}
@@ -252,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",
@@ -268,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.
@@ -318,6 +509,7 @@ const handleExport = async () => {
 - Freetext notes (background + wrapped text)
 - Images & signatures (embedded PNG/JPG)
 - Freehand drawings (embedded PNG)
+- Shapes (rectangle, circle, arrow)
 
 [Full Documentation →](docs/pdf-export.md)
 
@@ -325,28 +517,19 @@ const handleExport = async () => {
 
 ## Component Architecture
 
-```
-┌─────────────────────────────────────────────────────┐
-│                    PdfLoader                         │
-│  Loads PDF document via PDF.js                       │
-│                                                      │
-│  ┌───────────────────────────────────────────────┐  │
-│  │               PdfHighlighter                   │  │
-│  │  Manages viewer, events, coordinate systems   │  │
-│  │                                               │  │
-│  │  ┌─────────────────────────────────────────┐  │  │
-│  │  │      User-defined HighlightContainer    │  │  │
-│  │  │  Renders highlights using context hooks │  │  │
-│  │  │                                         │  │  │
-│  │  │  • TextHighlight                        │  │  │
-│  │  │  • AreaHighlight                        │  │  │
-│  │  │  • FreetextHighlight                    │  │  │
-│  │  │  • ImageHighlight                       │  │  │
-│  │  │  • DrawingHighlight                     │  │  │
-│  │  └─────────────────────────────────────────┘  │  │
-│  └───────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────┘
-```
+The package renders React annotation components into PDF.js page overlay layers:
+
+| Layer | Mount point | Purpose |
+|-------|-------------|---------|
+| `.PdfHighlighter__highlight-layer` | Inside PDF.js `.textLayer` | Annotation geometry for text, area, image/signature, drawing, and shape |
+| `.PdfHighlighter__note-layer` | Direct child of PDF.js `.page` | Freetext notes and compact note markers above PDF content |
+| `.PdfHighlighter__config-layer` | Direct child of PDF.js `.page` | Toolbars, style panels, copy buttons, and controls above PDF content |
+
+Internal flow diagram:
+
+- [Architecture PNG](docs/react-pdf-highlight-plus.png)
+- [Draw.io source](docs/package-build-and-features.drawio)
+- [Draw.io XML copy](docs/package-build-and-features.xml)
 
 ### Context Hooks