hazo_pdf 1.2.1 → 1.3.0

package/README.md

@@ -6,6 +6,7 @@ A React component library for viewing and annotating PDF documents with support
 
 - 📄 **PDF Viewing** - Render PDF documents with customizable zoom levels
 - ✏️ **Annotations** - Square and FreeText annotation tools
+- 🔍 **Programmatic Highlights** - Ref-based API for creating and managing highlights programmatically
 - 🎨 **Customizable Styling** - Extensive configuration options via INI file
 - ⏰ **Timestamp Support** - Automatic timestamp appending to annotations
 - 🏷️ **Custom Stamps** - Add quick-insert stamps via right-click menu
@@ -413,6 +414,204 @@ See `config/hazo_pdf_config.ini` in the project root for all available configura
 
 ---
 
+## Programmatic Highlight API
+
+The PDF viewer exposes a ref-based API for programmatically creating, removing, and managing highlights. This allows external code to control highlights without user interaction.
+
+### Basic Usage
+
+```tsx
+import { PdfViewer, PdfViewerRef } from 'hazo_pdf';
+import { useRef } from 'react';
+import 'hazo_pdf/styles.css';
+
+function HighlightExample() {
+  const viewer_ref = useRef<PdfViewerRef>(null);
+
+  const add_highlight = () => {
+    // Highlight region on page 0 at PDF coordinates [100, 500, 300, 550]
+    const id = viewer_ref.current?.highlight_region(0, [100, 500, 300, 550], {
+      border_color: '#FF0000',
+      background_color: '#FFFF00',
+      background_opacity: 0.4
+    });
+    console.log('Created highlight:', id);
+  };
+
+  const remove_specific_highlight = (id: string) => {
+    const removed = viewer_ref.current?.remove_highlight(id);
+    console.log('Highlight removed:', removed);
+  };
+
+  const clear_all = () => {
+    viewer_ref.current?.clear_all_highlights();
+  };
+
+  return (
+    <div style={{ width: '100%', height: '800px' }}>
+      <button onClick={add_highlight}>Add Highlight</button>
+      <button onClick={clear_all}>Clear All Highlights</button>
+
+      <PdfViewer
+        ref={viewer_ref}
+        url="/document.pdf"
+      />
+    </div>
+  );
+}
+```
+
+### PdfViewerRef Interface
+
+The ref exposes three methods for highlight management:
+
+#### `highlight_region(page_index, rect, options?)`
+
+Creates a new highlight annotation on the specified page.
+
+**Parameters:**
+- `page_index` (number): Zero-based page index where the highlight should appear
+- `rect` ([number, number, number, number]): Rectangle coordinates in PDF space [x1, y1, x2, y2]
+- `options` (HighlightOptions, optional): Styling options
+
+**Returns:** `string` - The unique ID of the created highlight annotation
+
+**HighlightOptions:**
+```typescript
+{
+  border_color?: string;       // Hex color (e.g., "#FF0000")
+  background_color?: string;   // Hex color (e.g., "#FFFF00")
+  background_opacity?: number; // 0-1 (e.g., 0.4)
+}
+```
+
+**Example:**
+```tsx
+const id = viewer_ref.current?.highlight_region(
+  0,                      // Page 0
+  [100, 500, 300, 550],   // PDF coordinates
+  {
+    border_color: '#FF0000',
+    background_color: '#FFFF00',
+    background_opacity: 0.4
+  }
+);
+```
+
+#### `remove_highlight(id)`
+
+Removes a specific highlight by its ID.
+
+**Parameters:**
+- `id` (string): The highlight ID returned from `highlight_region()`
+
+**Returns:** `boolean` - `true` if the highlight was found and removed, `false` otherwise
+
+**Example:**
+```tsx
+const removed = viewer_ref.current?.remove_highlight('highlight-123');
+if (removed) {
+  console.log('Highlight removed successfully');
+}
+```
+
+#### `clear_all_highlights()`
+
+Removes all highlights created via the `highlight_region()` API. Does not affect user-created annotations.
+
+**Example:**
+```tsx
+viewer_ref.current?.clear_all_highlights();
+```
+
+### Advanced Example: Search Results Highlighting
+
+A common use case is highlighting search results in a PDF:
+
+```tsx
+import { useState, useRef } from 'react';
+import { PdfViewer, PdfViewerRef } from 'hazo_pdf';
+import 'hazo_pdf/styles.css';
+
+interface SearchResult {
+  page: number;
+  rect: [number, number, number, number];
+  text: string;
+}
+
+function SearchableViewer() {
+  const viewer_ref = useRef<PdfViewerRef>(null);
+  const [highlight_ids, set_highlight_ids] = useState<string[]>([]);
+
+  // Simulated search results
+  const search_results: SearchResult[] = [
+    { page: 0, rect: [100, 500, 300, 550], text: 'Result 1' },
+    { page: 0, rect: [100, 400, 300, 450], text: 'Result 2' },
+    { page: 1, rect: [150, 600, 350, 650], text: 'Result 3' }
+  ];
+
+  const highlight_search_results = () => {
+    // Clear previous highlights
+    viewer_ref.current?.clear_all_highlights();
+
+    // Add new highlights
+    const ids = search_results.map(result =>
+      viewer_ref.current?.highlight_region(result.page, result.rect, {
+        border_color: '#3B82F6',
+        background_color: '#DBEAFE',
+        background_opacity: 0.3
+      })
+    ).filter(Boolean) as string[];
+
+    set_highlight_ids(ids);
+  };
+
+  const clear_search = () => {
+    viewer_ref.current?.clear_all_highlights();
+    set_highlight_ids([]);
+  };
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div style={{ padding: '1rem', background: '#f0f0f0' }}>
+        <button onClick={highlight_search_results}>
+          Highlight Search Results ({search_results.length})
+        </button>
+        <button onClick={clear_search}>Clear Highlights</button>
+        <span>Highlighted: {highlight_ids.length} results</span>
+      </div>
+
+      <div style={{ flex: 1 }}>
+        <PdfViewer
+          ref={viewer_ref}
+          url="/document.pdf"
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Coordinate System Notes
+
+- Highlights use PDF coordinate space (points), not screen pixels
+- PDF coordinates start at the bottom-left corner (Y increases upward)
+- The `rect` parameter format is `[x1, y1, x2, y2]` where:
+  - `x1, y1`: Bottom-left corner
+  - `x2, y2`: Top-right corner
+- If you need to convert screen coordinates to PDF coordinates, you'll need to use the PDF page viewport (see the test app for examples)
+
+### Styling Defaults
+
+If no `options` are provided to `highlight_region()`, the highlight uses default colors from the configuration file:
+- `border_color`: From `highlight_border_color` config setting
+- `background_color`: From `highlight_fill_color` config setting
+- `background_opacity`: From `highlight_fill_opacity` config setting
+
+You can override any or all of these on a per-highlight basis.
+
+---
+
 ## API Reference
 
 ### PdfViewer Props
@@ -573,6 +772,40 @@ interface PdfAnnotation {
 }
 ```
 
+**Note:** Highlights created via the programmatic API (`PdfViewerRef.highlight_region()`) will have `type: 'Highlight'` and `flags: 'api_highlight'` to distinguish them from user-created annotations.
+
+### PdfViewerRef Interface
+
+Interface for the ref exposed by `PdfViewer`. Use with `useRef<PdfViewerRef>()` to access programmatic highlight methods.
+
+```typescript
+interface PdfViewerRef {
+  highlight_region: (
+    page_index: number,
+    rect: [number, number, number, number],
+    options?: HighlightOptions
+  ) => string;
+
+  remove_highlight: (id: string) => boolean;
+
+  clear_all_highlights: () => void;
+}
+```
+
+See [Programmatic Highlight API](#programmatic-highlight-api) for detailed usage.
+
+### HighlightOptions Interface
+
+Options for customizing highlights created via the API.
+
+```typescript
+interface HighlightOptions {
+  border_color?: string;       // Hex format (e.g., "#FF0000")
+  background_color?: string;   // Hex format (e.g., "#FFFF00")
+  background_opacity?: number; // 0-1 (e.g., 0.4)
+}
+```
+
 ### PDFDocumentProxy
 
 Type from `pdfjs-dist`. Contains PDF metadata and page proxies.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import React from 'react';
+import * as React from 'react';
+import React__default from 'react';
 import { PDFDocumentProxy, PDFPageProxy } from 'pdfjs-dist';
 
 /**
@@ -403,18 +404,48 @@ interface MetadataInput {
     /** Array of footer items */
     footer: MetadataFooterItem[];
 }
-
 /**
- * PDF Viewer Component
- * Main component for displaying and interacting with PDF documents
- * Integrates PDF rendering, annotation overlay, and layout management
+ * Options for programmatic highlight creation via PdfViewerRef
  */
+interface HighlightOptions {
+    /** Border color in hex format (default: from config highlight_border_color) */
+    border_color?: string;
+    /** Background/fill color in hex format (default: from config highlight_fill_color) */
+    background_color?: string;
+    /** Background opacity 0-1 (default: from config highlight_fill_opacity) */
+    background_opacity?: number;
+}
+/**
+ * Ref interface for programmatic PDF viewer control
+ * Use with useRef<PdfViewerRef>() to get access to imperative methods
+ */
+interface PdfViewerRef {
+    /**
+     * Create a highlight on a specific page region
+     * @param page_index - Zero-based page index
+     * @param rect - Rectangle coordinates in PDF space [x1, y1, x2, y2]
+     * @param options - Optional styling overrides (border_color, background_color, background_opacity)
+     * @returns The highlight annotation ID
+     */
+    highlight_region: (page_index: number, rect: [number, number, number, number], options?: HighlightOptions) => string;
+    /**
+     * Remove a specific highlight by ID
+     * @param id - The highlight annotation ID returned from highlight_region
+     * @returns true if highlight was found and removed, false otherwise
+     */
+    remove_highlight: (id: string) => boolean;
+    /**
+     * Remove all highlights created via the highlight_region API
+     * Does not affect user-created annotations
+     */
+    clear_all_highlights: () => void;
+}
 
 /**
  * PDF Viewer Component
  * Main entry point for PDF viewing and annotation
  */
-declare const PdfViewer: React.FC<PdfViewerProps>;
+declare const PdfViewer: React.ForwardRefExoticComponent<PdfViewerProps & React.RefAttributes<PdfViewerRef>>;
 
 /**
  * PDF Viewer Layout Component
@@ -431,7 +462,7 @@ interface PdfViewerLayoutProps {
     annotations: PdfAnnotation[];
     current_tool: 'Square' | 'Highlight' | 'FreeText' | 'CustomBookmark' | null;
     on_annotation_create: (annotation: PdfAnnotation) => void;
-    on_context_menu: (e: React.MouseEvent, page_index: number, screen_x: number, screen_y: number, mapper: CoordinateMapper) => void;
+    on_context_menu: (e: React__default.MouseEvent, page_index: number, screen_x: number, screen_y: number, mapper: CoordinateMapper) => void;
     on_annotation_click: (annotation: PdfAnnotation, screen_x: number, screen_y: number, mapper: CoordinateMapper) => void;
     on_freetext_click?: (page_index: number, screen_x: number, screen_y: number, mapper: CoordinateMapper) => void;
     background_color?: string;
@@ -442,7 +473,7 @@ interface PdfViewerLayoutProps {
  * PDF Viewer Layout Component
  * Manages page rendering and annotation overlay coordination
  */
-declare const PdfViewerLayout: React.FC<PdfViewerLayoutProps>;
+declare const PdfViewerLayout: React__default.FC<PdfViewerLayoutProps>;
 
 /**
  * PDF Page Renderer Component
@@ -471,7 +502,7 @@ interface PdfPageRendererProps {
  * PDF Page Renderer Component
  * Handles rendering of a single PDF page to canvas
  */
-declare const PdfPageRenderer: React.FC<PdfPageRendererProps>;
+declare const PdfPageRenderer: React__default.FC<PdfPageRendererProps>;
 
 /**
  * Annotation Overlay Component
@@ -497,7 +528,7 @@ interface AnnotationOverlayProps {
     /** Callback when annotation is created */
     on_annotation_create?: (annotation: PdfAnnotation) => void;
     /** Callback when right-click occurs */
-    on_context_menu?: (event: React.MouseEvent, screen_x: number, screen_y: number) => void;
+    on_context_menu?: (event: React__default.MouseEvent, screen_x: number, screen_y: number) => void;
     /** Callback when annotation is clicked */
     on_annotation_click?: (annotation: PdfAnnotation, screen_x: number, screen_y: number) => void;
     /** Callback when FreeText tool is active and user clicks on empty area */
@@ -511,7 +542,7 @@ interface AnnotationOverlayProps {
  * Annotation Overlay Component
  * Handles mouse interactions for creating annotations
  */
-declare const AnnotationOverlay: React.FC<AnnotationOverlayProps>;
+declare const AnnotationOverlay: React__default.FC<AnnotationOverlayProps>;
 
 /**
  * PDF Worker Setup
@@ -729,4 +760,4 @@ declare function load_pdf_config(config_file?: string): PdfViewerConfig;
  */
 declare const default_config: PdfViewerConfig;
 
-export { AnnotationOverlay, type CoordinateMapper, type CustomStamp, type MetadataDataItem, type MetadataFooterItem, type MetadataFormatType, type MetadataHeaderItem, type MetadataInput, type PageDimensions, type PdfAnnotation, type PdfBookmark, type PdfDocument, type PdfPage, PdfPageRenderer, PdfViewer, type PdfViewerConfig, PdfViewerLayout, type PdfViewerProps, build_config_from_ini, calculate_rectangle_coords, create_coordinate_mapper, default_config, download_pdf, download_xfdf, export_annotations_to_xfdf, generate_xfdf, get_viewport_dimensions, is_rectangle_too_small, load_pdf_config, load_pdf_config_async, load_pdf_document, parse_color, parse_number, parse_opacity, parse_string, pdf_rect_to_rectangle, rectangle_to_pdf_rect, save_and_download_pdf, save_annotations_to_pdf };
+export { AnnotationOverlay, type CoordinateMapper, type CustomStamp, type HighlightOptions, type MetadataDataItem, type MetadataFooterItem, type MetadataFormatType, type MetadataHeaderItem, type MetadataInput, type PageDimensions, type PdfAnnotation, type PdfBookmark, type PdfDocument, type PdfPage, PdfPageRenderer, PdfViewer, type PdfViewerConfig, PdfViewerLayout, type PdfViewerProps, type PdfViewerRef, build_config_from_ini, calculate_rectangle_coords, create_coordinate_mapper, default_config, download_pdf, download_xfdf, export_annotations_to_xfdf, generate_xfdf, get_viewport_dimensions, is_rectangle_too_small, load_pdf_config, load_pdf_config_async, load_pdf_document, parse_color, parse_number, parse_opacity, parse_string, pdf_rect_to_rectangle, rectangle_to_pdf_rect, save_and_download_pdf, save_annotations_to_pdf };

package/dist/index.js

@@ -8,7 +8,7 @@ import {
 } from "./chunk-S3AJUZ7D.js";
 
 // src/components/pdf_viewer/pdf_viewer.tsx
-import { useState as useState6, useEffect as useEffect6, useRef as useRef7, useCallback as useCallback2 } from "react";
+import { useState as useState6, useEffect as useEffect6, useRef as useRef7, useCallback as useCallback2, forwardRef, useImperativeHandle } from "react";
 import { Save, Undo2 as Undo22, Redo2, PanelRight, ZoomIn, ZoomOut, RotateCcw, Square, Type } from "lucide-react";
 
 // src/components/pdf_viewer/pdf_worker_setup.ts
@@ -725,18 +725,29 @@ var AnnotationOverlay = ({
     }
     const get_annotation_props = () => {
       switch (annotation.type) {
-        case "Highlight":
-          const highlight_color = annotation.color || highlight_config.highlight_fill_color;
+        case "Highlight": {
+          let custom_highlight_options = null;
+          if (annotation.subject) {
+            try {
+              custom_highlight_options = JSON.parse(annotation.subject);
+            } catch {
+            }
+          }
+          const highlight_fill_color = custom_highlight_options?.background_color || annotation.color || highlight_config.highlight_fill_color;
+          const highlight_fill_opacity = custom_highlight_options?.background_opacity ?? highlight_config.highlight_fill_opacity;
+          const highlight_border_color = custom_highlight_options?.border_color || highlight_config.highlight_border_color;
           return {
-            fill: hex_to_rgba(highlight_color, highlight_config.highlight_fill_opacity),
-            stroke: highlight_config.highlight_border_color
+            fill: hex_to_rgba(highlight_fill_color, highlight_fill_opacity),
+            stroke: highlight_border_color
           };
-        case "Square":
+        }
+        case "Square": {
           const square_color = annotation.color || square_config.square_fill_color;
           return {
             fill: hex_to_rgba(square_color, square_config.square_fill_opacity),
             stroke: square_config.square_border_color
           };
+        }
         default:
           return {
             fill: "rgba(0, 0, 255, 0.2)",
@@ -2272,7 +2283,7 @@ function load_pdf_config(config_file) {
 
 // src/components/pdf_viewer/pdf_viewer.tsx
 import { Fragment as Fragment4, jsx as jsx7, jsxs as jsxs6 } from "react/jsx-runtime";
-var PdfViewer = ({
+var PdfViewer = forwardRef(({
   url,
   className = "",
   scale: initial_scale = 1,
@@ -2301,7 +2312,7 @@ var PdfViewer = ({
   show_metadata_button,
   show_annotate_button,
   on_close
-}) => {
+}, ref) => {
   const [pdf_document, setPdfDocument] = useState6(null);
   const [loading, setLoading] = useState6(true);
   const [error, setError] = useState6(null);
@@ -2661,6 +2672,60 @@ ${suffix_line}`;
       on_annotation_delete(annotation_id);
     }
   };
+  useImperativeHandle(ref, () => ({
+    /**
+     * Create a highlight on a specific page region
+     * @param page_index - Zero-based page index
+     * @param rect - Rectangle coordinates in PDF space [x1, y1, x2, y2]
+     * @param options - Optional styling overrides
+     * @returns The highlight annotation ID
+     */
+    highlight_region: (page_index, rect, options) => {
+      const highlight_config = config_ref.current?.highlight_annotation || default_config.highlight_annotation;
+      const annotation = {
+        id: `highlight_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+        type: "Highlight",
+        page_index,
+        rect,
+        author: "API",
+        date: (/* @__PURE__ */ new Date()).toISOString(),
+        contents: "",
+        color: options?.background_color || highlight_config.highlight_fill_color,
+        flags: "api_highlight"
+        // Marker to identify API-created highlights
+      };
+      if (options) {
+        annotation.subject = JSON.stringify({
+          border_color: options.border_color,
+          background_color: options.background_color,
+          background_opacity: options.background_opacity
+        });
+      }
+      handle_annotation_create(annotation);
+      return annotation.id;
+    },
+    /**
+     * Remove a specific highlight by ID
+     * @param id - The highlight annotation ID
+     * @returns true if highlight was found and removed
+     */
+    remove_highlight: (id) => {
+      const annotation = annotations.find((a) => a.id === id);
+      if (annotation) {
+        handle_annotation_delete(id);
+        return true;
+      }
+      return false;
+    },
+    /**
+     * Remove all highlights created via the highlight_region API
+     */
+    clear_all_highlights: () => {
+      const api_highlights = annotations.filter((a) => a.flags === "api_highlight");
+      api_highlights.forEach((a) => handle_annotation_delete(a.id));
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }), [annotations, handle_annotation_create, handle_annotation_delete]);
   const handle_undo = useCallback2(() => {
     if (history_index > 0) {
       history_ref.current.saving = true;
@@ -2742,9 +2807,10 @@ ${suffix_line}`;
       const output_filename = `${filename_without_ext}_annotated.pdf`;
       const { save_annotations_to_pdf: save_annotations_to_pdf2, download_pdf: download_pdf2 } = await import("./pdf_saver-P2MJN45S.js");
       const pdf_bytes = await save_annotations_to_pdf2(url, annotations, output_filename, config_ref.current);
-      download_pdf2(pdf_bytes, output_filename);
       if (on_save) {
         on_save(pdf_bytes, output_filename);
+      } else {
+        download_pdf2(pdf_bytes, output_filename);
       }
     } catch (error2) {
       console.error("PdfViewer: Error saving PDF:", error2);
@@ -3271,7 +3337,8 @@ ${suffix_line}`;
       }
     )
   ] });
-};
+});
+PdfViewer.displayName = "PdfViewer";
 
 // src/utils/xfdf_generator.ts
 function format_pdf_date(date) {