react-pdf-highlighter-plus 1.1.4 → 1.3.0

package/dist/esm/index.d.ts

@@ -459,6 +459,16 @@ type PdfHighlighterUtils = {
      * Clear active search highlights.
      */
     clearSearch(): void;
+    /**
+     * Marks a highlight as selected/deselected (its floating toolbar is open).
+     * Counter-backed, so overlapping select/deselect from different highlights
+     * resolves correctly. Used to suppress hover tips while a toolbar is shown.
+     */
+    setHighlightSelected(selected: boolean): void;
+    /**
+     * Whether any highlight is currently selected (toolbar showing).
+     */
+    isHighlightSelected(): boolean;
 };
 /**
  * Custom hook for providing {@link PdfHighlighterUtils}. Must be used
@@ -476,8 +486,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 +514,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 +553,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 +737,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.
@@ -779,13 +826,25 @@ interface TextHighlightProps {
      * Default: ["rgba(255, 226, 143, 1)", "#ffcdd2", "#c8e6c9", "#bbdefb", "#e1bee7"]
      */
     colorPresets?: string[];
+    /**
+     * Extra buttons rendered in the same toolbar row, after the copy button.
+     * Use this to add consumer-defined actions (e.g. a comment toggle) without
+     * needing a second, separate popup.
+     */
+    extraButtons?: ReactNode;
+    /**
+     * Extra content rendered below the toolbar row, in the same slot as the
+     * built-in style panel (e.g. a comment editor opened by an extraButtons
+     * toggle).
+     */
+    extraPanel?: ReactNode;
 }
 /**
  * A component for displaying a highlighted text area.
  *
  * @category Component
  */
-declare const TextHighlight: ({ highlight, onClick, onMouseOver, onMouseOut, isScrolledTo, onContextMenu, style, highlightColor, highlightStyle, onStyleChange, onDelete, styleIcon, deleteIcon, copyText, colorPresets, }: TextHighlightProps) => React.JSX.Element;
+declare const TextHighlight: React.MemoExoticComponent<({ highlight, onClick, onMouseOver, onMouseOut, isScrolledTo, onContextMenu, style, highlightColor, highlightStyle, onStyleChange, onDelete, styleIcon, deleteIcon, copyText, colorPresets, extraButtons, extraPanel, }: TextHighlightProps) => React.JSX.Element>;
 
 /**
  * The props type for {@link MonitoredHighlightContainer}.
@@ -886,10 +945,6 @@ interface AreaHighlightProps {
      * Callback triggered when the delete button is clicked.
      */
     onDelete?(): void;
-    /**
-     * Custom style icon. Replaces the default palette icon.
-     */
-    styleIcon?: ReactNode;
     /**
      * Custom delete icon. Replaces the default trash icon.
      */
@@ -899,13 +954,25 @@ interface AreaHighlightProps {
      * Default: ["rgba(255, 226, 143, 1)", "#ffcdd2", "#c8e6c9", "#bbdefb", "#e1bee7"]
      */
     colorPresets?: string[];
+    /**
+     * Extra buttons rendered in the same toolbar row, after the copy button.
+     * Use this to add consumer-defined actions (e.g. a comment toggle) without
+     * needing a second, separate popup.
+     */
+    extraButtons?: ReactNode;
+    /**
+     * Extra content rendered below the toolbar row, in the same slot as the
+     * built-in style panel (e.g. a comment editor opened by an extraButtons
+     * toggle).
+     */
+    extraPanel?: ReactNode;
 }
 /**
  * Renders a resizeable and interactive rectangular area for a highlight.
  *
  * @category Component
  */
-declare const AreaHighlight: ({ highlight, onChange, isScrolledTo, bounds, onContextMenu, onEditStart, style, highlightColor, onStyleChange, onDelete, styleIcon, deleteIcon, copyText, colorPresets, }: AreaHighlightProps) => React.JSX.Element;
+declare const AreaHighlight: React.MemoExoticComponent<({ highlight, onChange, isScrolledTo, bounds, onContextMenu, onEditStart, style, highlightColor, onStyleChange, onDelete, deleteIcon, copyText, colorPresets, extraButtons, extraPanel, }: AreaHighlightProps) => React.JSX.Element>;
 
 /**
  * Style options for freetext highlight appearance.
@@ -1082,13 +1149,20 @@ interface ImageHighlightProps {
      * Custom delete icon. Replaces the default trash icon.
      */
     deleteIcon?: ReactNode;
+    /**
+     * Callback triggered when the image is rotated 90°. Receives the
+     * re-rendered PNG data URL (rotated, dimensions swapped to match).
+     * Pair with `onChange` to persist the swapped bounding rect this
+     * component already computes and passes to it.
+     */
+    onImageChange?(newImage: string): void;
 }
 /**
  * Renders a draggable, resizable image/signature annotation.
  *
  * @category Component
  */
-declare const ImageHighlight: ({ highlight, onChange, isScrolledTo, bounds, onContextMenu, onEditStart, onEditEnd, style, dragIcon, onDelete, deleteIcon, }: ImageHighlightProps) => React.JSX.Element;
+declare const ImageHighlight: ({ highlight, onChange, isScrolledTo, bounds, onContextMenu, onEditStart, onEditEnd, style, dragIcon, onDelete, deleteIcon, onImageChange, }: ImageHighlightProps) => React.JSX.Element;
 
 /**
  * The props type for {@link SignaturePad}.
@@ -1408,12 +1482,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 +1515,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
@@ -1517,7 +1615,7 @@ type PdfExtractedPage = {
     textItems: PdfTextItem[];
     columns?: PdfTextColumn[];
 };
-type PdfTextUnitType = "paragraph" | "title" | "heading" | "author" | "affiliation" | "footnote" | "reference" | "unknown";
+type PdfTextUnitType = "paragraph" | "title" | "heading" | "author" | "affiliation" | "footnote" | "reference" | "caption" | "figureLabel" | "unknown";
 type PdfTextUnit = {
     id: string;
     type: PdfTextUnitType;
@@ -1566,6 +1664,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 +1975,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 +2162,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 };