hazo_pdf 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,593 @@
+import React from 'react';
+import { PDFDocumentProxy, PDFPageProxy } from 'pdfjs-dist';
+
+/**
+ * Configuration types for hazo_pdf
+ * Defines all configurable styling values
+ */
+/**
+ * PDF Viewer Configuration Interface
+ * Contains all configurable styling values organized by category
+ */
+interface PdfViewerConfig {
+    fonts: {
+        /** Font family for FreeText annotations */
+        freetext_font_family: string;
+        /** Minimum font size for FreeText annotations (in pixels) */
+        freetext_font_size_min: number;
+        /** Maximum font size for FreeText annotations (in pixels) */
+        freetext_font_size_max: number;
+        /** Default font size for FreeText annotations (in pixels) */
+        freetext_font_size_default: number;
+        /** Default font foreground (text) color for all text annotations (hex format: #RRGGBB or rgb(r, g, b)) */
+        font_foreground_color: string;
+    };
+    highlight_annotation: {
+        /** Fill color for highlight annotations (hex format) */
+        highlight_fill_color: string;
+        /** Fill opacity for highlight annotations (0.0 to 1.0) */
+        highlight_fill_opacity: number;
+        /** Border/stroke color for highlight annotations (hex format) */
+        highlight_border_color: string;
+        /** Border color on hover (hex format) */
+        highlight_border_color_hover: string;
+        /** Fill opacity on hover (0.0 to 1.0) */
+        highlight_fill_opacity_hover: number;
+    };
+    square_annotation: {
+        /** Fill color for square annotations (hex format) */
+        square_fill_color: string;
+        /** Fill opacity for square annotations (0.0 to 1.0) */
+        square_fill_opacity: number;
+        /** Border/stroke color for square annotations (hex format) */
+        square_border_color: string;
+        /** Border color on hover (hex format) */
+        square_border_color_hover: string;
+        /** Fill opacity on hover (0.0 to 1.0) */
+        square_fill_opacity_hover: number;
+    };
+    freetext_annotation: {
+        /** Text color for FreeText annotations (hex format) */
+        freetext_text_color: string;
+        /** Text color on hover (hex format) */
+        freetext_text_color_hover: string;
+        /** Border color for FreeText annotation box (hex format, empty string for no border) */
+        freetext_border_color: string;
+        /** Border width for FreeText annotation box (0 for no border) */
+        freetext_border_width: number;
+        /** Background color for FreeText annotation box (hex format, empty string for transparent) */
+        freetext_background_color: string;
+        /** Background opacity for FreeText annotation box (0.0 to 1.0, only used if background_color is set) */
+        freetext_background_opacity: number;
+        /** Font weight (normal, bold, etc.) */
+        freetext_font_weight: string;
+        /** Font style (normal, italic, etc.) */
+        freetext_font_style: string;
+        /** Text decoration (none, underline, line-through, etc.) */
+        freetext_text_decoration: string;
+        /** Horizontal padding inside the annotation box (left and right) in pixels */
+        freetext_padding_horizontal: number;
+        /** Vertical padding inside the annotation box (top and bottom) in pixels */
+        freetext_padding_vertical: number;
+    };
+    page_styling: {
+        /** Border color for PDF pages (hex format) */
+        page_border_color: string;
+        /** Box shadow CSS value for PDF pages */
+        page_box_shadow: string;
+        /** Background color for PDF pages (hex format) */
+        page_background_color: string;
+    };
+    viewer: {
+        /** Background color for PDF viewer area (hex format) */
+        viewer_background_color: string;
+        /** Whether to append timestamp to annotated text edits (default: false) */
+        /** When enabled, appends a newline followed by timestamp in format [YYYY-MM-DD h:mmam/pm] */
+        append_timestamp_to_text_edits: boolean;
+        /** Fixed text to add in square brackets before timestamp (default: empty) */
+        /** If provided and timestamp is enabled, format will be: text\n[fixed_text] [timestamp] */
+        annotation_text_suffix_fixed_text: string;
+        /** Whether to add enclosing brackets (default: true) */
+        add_enclosing_brackets_to_suffixes: boolean;
+        /** Enclosing bracket pair for suffixes (default: "[]", must be 2 characters) */
+        suffix_enclosing_brackets: string;
+        /** Placement of suffix text relative to input text (default: below_multi_line) */
+        /** Valid values: "adjacent", "below_single_line", "below_multi_line" */
+        suffix_text_position: 'adjacent' | 'below_single_line' | 'below_multi_line';
+    };
+    context_menu: {
+        /** Background color for context menu (hex format) */
+        context_menu_background_color: string;
+        /** Border color for context menu (hex format) */
+        context_menu_border_color: string;
+        /** Background color for context menu item on hover (hex format) */
+        context_menu_item_hover_background: string;
+        /** Opacity for disabled context menu items (0.0 to 1.0) */
+        context_menu_item_disabled_opacity: number;
+        /** Custom stamps for right-click menu (JSON array string) */
+        /** Each stamp has: name, text, order, time_stamp_suffix_enabled (default false), fixed_text_suffix_enabled (default false) */
+        /** Example: '[{"name":"Verified","text":"XXX","order":1,"time_stamp_suffix_enabled":true,"fixed_text_suffix_enabled":true}]' */
+        right_click_custom_stamps: string;
+    };
+    dialog: {
+        /** Opacity for dialog backdrop (0.0 to 1.0) */
+        dialog_backdrop_opacity: number;
+        /** Background color for dialog (hex format) */
+        dialog_background_color: string;
+        /** Border color for dialog (hex format) */
+        dialog_border_color: string;
+        /** Submit button color (hex format) */
+        dialog_button_submit_color: string;
+        /** Submit button color on hover (hex format) */
+        dialog_button_submit_color_hover: string;
+        /** Cancel button color (hex format) */
+        dialog_button_cancel_color: string;
+        /** Cancel button color on hover (hex format) */
+        dialog_button_cancel_color_hover: string;
+        /** Opacity for disabled dialog buttons (0.0 to 1.0) */
+        dialog_button_disabled_opacity: number;
+    };
+}
+
+/**
+ * Type definitions for hazo_pdf package
+ * Adheres to PDF annotation standard
+ */
+
+/**
+ * Props for the main PdfViewer component
+ */
+interface PdfViewerProps {
+    /** URL or path to the PDF file */
+    url: string;
+    /** Optional class name for styling */
+    className?: string;
+    /** Initial zoom level (default: 1.0) */
+    scale?: number;
+    /** Callback when PDF is loaded */
+    on_load?: (pdf: PDFDocumentProxy) => void;
+    /** Callback when an error occurs */
+    on_error?: (error: Error) => void;
+    /** Existing annotations to display */
+    annotations?: PdfAnnotation[];
+    /** Callback when annotation is created */
+    on_annotation_create?: (annotation: PdfAnnotation) => void;
+    /** Callback when annotation is updated */
+    on_annotation_update?: (annotation: PdfAnnotation) => void;
+    /** Callback when annotation is deleted */
+    on_annotation_delete?: (annotation_id: string) => void;
+    /** Callback when PDF is saved with annotations */
+    on_save?: (pdf_bytes: Uint8Array, filename: string) => void;
+    /** Background color for areas outside PDF pages (default: dark grey) */
+    background_color?: string;
+    /** Optional path to configuration INI file (e.g., "hazo_pdf_config.ini") */
+    config_file?: string;
+    /** Whether to append timestamp to annotated text edits (default: false) */
+    append_timestamp_to_text_edits?: boolean;
+    /** Fixed text to add in square brackets before timestamp (default: empty) */
+    /** If provided and timestamp is enabled, format will be: text\n[fixed_text] [timestamp] */
+    annotation_text_suffix_fixed_text?: string;
+    /** Custom stamps for right-click menu (JSON array string) */
+    /** Each stamp has: name, text, order, time_stamp_suffix_enabled (default false), fixed_text_suffix_enabled (default false) */
+    /** Example: '[{"name":"Verified","text":"XXX","order":1,"time_stamp_suffix_enabled":true,"fixed_text_suffix_enabled":true}]' */
+    right_click_custom_stamps?: string;
+}
+/**
+ * PDF Annotation interface matching PDF standard
+ * Uses PDF coordinate space (rect as [x1, y1, x2, y2])
+ */
+interface PdfAnnotation {
+    /** Unique identifier for the annotation */
+    id: string;
+    /** Type of annotation following PDF standard */
+    type: 'Highlight' | 'Square' | 'FreeText' | 'CustomBookmark';
+    /** Zero-based page index */
+    page_index: number;
+    /** Rectangle coordinates in PDF space [x1, y1, x2, y2] */
+    rect: [number, number, number, number];
+    /** Author of the annotation */
+    author: string;
+    /** Creation/modification date in ISO format */
+    date: string;
+    /** Text content or comment */
+    contents: string;
+    /** Color in hex format (e.g., "#FF0000") */
+    color?: string;
+    /** Subject/title of the annotation */
+    subject?: string;
+    /** Flags for annotation behavior */
+    flags?: string;
+}
+/**
+ * PDF Bookmark/Outline interface
+ */
+interface PdfBookmark {
+    /** Unique identifier */
+    id: string;
+    /** Title of the bookmark */
+    title: string;
+    /** Page index this bookmark points to */
+    page_index: number;
+    /** Y coordinate on the page */
+    y?: number;
+    /** Action type */
+    action?: string;
+}
+/**
+ * Custom stamp configuration for right-click menu
+ */
+interface CustomStamp {
+    /** Name of the stamp (displayed as menu item) */
+    name: string;
+    /** Text content to add to PDF */
+    text: string;
+    /** Order/position in menu (lower numbers appear first) */
+    order: number;
+    /** Whether to append timestamp suffix (default: false) */
+    time_stamp_suffix_enabled?: boolean;
+    /** Whether to append fixed text suffix (default: false) */
+    fixed_text_suffix_enabled?: boolean;
+    /** Background color for the annotation box (hex format: #RRGGBB or rgb(r, g, b), empty string for transparent) */
+    background_color?: string;
+    /** Border size/width in pixels (0 means no border, default: uses config default) */
+    border_size?: number;
+    /** Font color for the text (hex format: #RRGGBB or rgb(r, g, b), default: uses config default) */
+    font_color?: string;
+    /** Font weight (normal, bold, etc., default: uses config default) */
+    font_weight?: string;
+    /** Font style (normal, italic, etc., default: uses config default) */
+    font_style?: string;
+    /** Font size in pixels (default: uses config default) */
+    font_size?: number;
+    /** Font family/name (e.g., "Arial, sans-serif", default: uses config default) */
+    font_name?: string;
+}
+/**
+ * Coordinate mapping utilities
+ * Converts between PDF space and Screen space
+ */
+interface CoordinateMapper {
+    /** Convert screen coordinates to PDF coordinates */
+    to_pdf: (x_screen: number, y_screen: number) => [number, number];
+    /** Convert PDF coordinates to screen coordinates */
+    to_screen: (x_pdf: number, y_pdf: number) => [number, number];
+}
+/**
+ * Page dimensions in screen space
+ */
+interface PageDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * PDF Document Proxy type
+ */
+type PdfDocument = PDFDocumentProxy;
+/**
+ * PDF Page Proxy type
+ */
+type PdfPage = PDFPageProxy;
+
+/**
+ * PDF Viewer Component
+ * Main component for displaying and interacting with PDF documents
+ * Integrates PDF rendering, annotation overlay, and layout management
+ */
+
+/**
+ * PDF Viewer Component
+ * Main entry point for PDF viewing and annotation
+ */
+declare const PdfViewer: React.FC<PdfViewerProps>;
+
+/**
+ * PDF Viewer Layout Component
+ * Main layout container with scrollable viewport
+ * Manages page rendering and annotation overlay
+ */
+
+/**
+ * Props for PdfViewerLayout component
+ */
+interface PdfViewerLayoutProps {
+    pdf_document: PDFDocumentProxy;
+    scale: number;
+    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_annotation_click: (annotation: PdfAnnotation, screen_x: number, screen_y: number, mapper: CoordinateMapper) => void;
+    background_color?: string;
+    config: PdfViewerConfig | null;
+    className?: string;
+}
+/**
+ * PDF Viewer Layout Component
+ * Manages page rendering and annotation overlay coordination
+ */
+declare const PdfViewerLayout: React.FC<PdfViewerLayoutProps>;
+
+/**
+ * PDF Page Renderer Component
+ * Renders a single PDF page to a canvas element
+ * Provides coordinate mapping utilities for annotations
+ */
+
+/**
+ * Props for PDFPageRenderer component
+ */
+interface PdfPageRendererProps {
+    /** PDF page proxy object */
+    page: PDFPageProxy;
+    /** Zero-based page index */
+    page_index: number;
+    /** Zoom/scale factor */
+    scale: number;
+    /** Optional class name */
+    className?: string;
+    /** Callback to provide coordinate mapper to parent */
+    on_coordinate_mapper_ready?: (mapper: CoordinateMapper, dimensions: PageDimensions) => void;
+    /** Configuration object for styling */
+    config?: PdfViewerConfig | null;
+}
+/**
+ * PDF Page Renderer Component
+ * Handles rendering of a single PDF page to canvas
+ */
+declare const PdfPageRenderer: React.FC<PdfPageRendererProps>;
+
+/**
+ * Annotation Overlay Component
+ * DOM/SVG layer for handling annotation interactions
+ * Positioned above the canvas layer
+ */
+
+/**
+ * Props for AnnotationOverlay component
+ */
+interface AnnotationOverlayProps {
+    /** Page dimensions in screen space */
+    width: number;
+    height: number;
+    /** Zero-based page index */
+    page_index: number;
+    /** Coordinate mapper for PDF ↔ Screen conversion */
+    map_coords: CoordinateMapper;
+    /** Existing annotations for this page */
+    annotations?: PdfAnnotation[];
+    /** Current annotation tool type */
+    current_tool?: 'Square' | 'Highlight' | 'FreeText' | 'CustomBookmark' | null;
+    /** 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;
+    /** Callback when annotation is clicked */
+    on_annotation_click?: (annotation: PdfAnnotation, screen_x: number, screen_y: number) => void;
+    /** Configuration object for styling */
+    config?: PdfViewerConfig | null;
+    /** Optional class name */
+    className?: string;
+}
+/**
+ * Annotation Overlay Component
+ * Handles mouse interactions for creating annotations
+ */
+declare const AnnotationOverlay: React.FC<AnnotationOverlayProps>;
+
+/**
+ * PDF Worker Setup
+ * Configures pdfjs-dist to use Web Workers for PDF processing
+ * This ensures PDF parsing and rendering happens off the main thread
+ *
+ * IMPORTANT: This module uses dynamic imports to prevent SSR evaluation
+ * PDF.js can only run in the browser, so we must avoid importing it during SSR
+ */
+
+/**
+ * Load a PDF document from a URL or ArrayBuffer
+ * For local files (like in Storybook), fetch as ArrayBuffer for better compatibility
+ * @param source - URL string, ArrayBuffer, or Uint8Array
+ * @returns Promise resolving to PDFDocumentProxy
+ */
+declare function load_pdf_document(source: string | ArrayBuffer | Uint8Array): Promise<PDFDocumentProxy>;
+
+/**
+ * XFDF Generator Utility
+ * Converts annotation and bookmark data to XFDF (XML Forms Data Format)
+ * XFDF is the standard format for PDF annotations
+ */
+
+/**
+ * Generate XFDF XML from annotations and bookmarks
+ * @param annotations - Array of annotations
+ * @param bookmarks - Array of bookmarks (optional)
+ * @param pdf_file_name - Name of the PDF file
+ * @returns XFDF XML string
+ */
+declare function generate_xfdf(annotations: PdfAnnotation[], bookmarks?: PdfBookmark[], pdf_file_name?: string): string;
+/**
+ * Download XFDF file
+ * @param xfdf_content - XFDF XML content
+ * @param file_name - Name for the downloaded file
+ */
+declare function download_xfdf(xfdf_content: string, file_name?: string): void;
+/**
+ * Generate and download XFDF file
+ * @param annotations - Array of annotations
+ * @param bookmarks - Array of bookmarks (optional)
+ * @param pdf_file_name - Name of the PDF file
+ * @param file_name - Name for the downloaded file
+ */
+declare function export_annotations_to_xfdf(annotations: PdfAnnotation[], bookmarks?: PdfBookmark[], pdf_file_name?: string, file_name?: string): void;
+
+/**
+ * PDF Saver Utility
+ * Saves annotations directly into PDF documents using pdf-lib
+ * This allows annotations to be embedded in the PDF file itself
+ */
+
+/**
+ * Save annotations into a PDF document
+ * This function fetches the PDF, adds annotations, and downloads the modified PDF
+ * @param pdf_url - URL of the PDF file
+ * @param annotations - Array of annotations to save
+ * @param output_filename - Name for the saved PDF file (default: original filename with '_annotated' suffix)
+ * @param config - Optional configuration for styling values
+ * @returns Promise that resolves when the PDF is saved
+ */
+declare function save_annotations_to_pdf(pdf_url: string, annotations: PdfAnnotation[], _output_filename?: string, // Currently unused, kept for API compatibility
+config?: PdfViewerConfig | null): Promise<Uint8Array>;
+/**
+ * Download PDF bytes as a file
+ * @param pdf_bytes - PDF file bytes
+ * @param filename - Name for the downloaded file
+ */
+declare function download_pdf(pdf_bytes: Uint8Array, filename: string): void;
+/**
+ * Save annotations to PDF and download
+ * @param pdf_url - URL of the PDF file
+ * @param annotations - Array of annotations to save
+ * @param output_filename - Name for the saved PDF file (default: original filename with '_annotated' suffix)
+ * @param config - Optional configuration for styling values
+ */
+declare function save_and_download_pdf(pdf_url: string, annotations: PdfAnnotation[], output_filename?: string, config?: PdfViewerConfig | null): Promise<void>;
+
+/**
+ * Coordinate Mapper Utilities
+ * Handles conversion between PDF coordinate space and Screen coordinate space
+ * PDF coordinates use bottom-left origin, Screen coordinates use top-left origin
+ */
+
+/**
+ * Create a coordinate mapper for a specific page and scale
+ * @param page - PDF page proxy
+ * @param scale - Zoom/scale factor
+ * @returns CoordinateMapper with to_pdf and to_screen methods
+ */
+declare function create_coordinate_mapper(page: PDFPageProxy, scale: number): CoordinateMapper;
+/**
+ * Get viewport dimensions for a page at a specific scale
+ * @param page - PDF page proxy
+ * @param scale - Zoom/scale factor
+ * @returns Object with width and height in screen pixels
+ */
+declare function get_viewport_dimensions(page: PDFPageProxy, scale: number): {
+    width: number;
+    height: number;
+};
+
+/**
+ * Annotation Utility Functions
+ * Helper functions for annotation calculations and transformations
+ */
+/**
+ * Point coordinates
+ */
+interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Rectangle coordinates (normalized)
+ */
+interface Rectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Calculates a normalized rectangle bounding box (x, y, width, height)
+ * given any two diagonal points
+ * @param p1 - First point
+ * @param p2 - Second point
+ * @returns Normalized rectangle with top-left origin
+ */
+declare function calculate_rectangle_coords(p1: Point, p2: Point): Rectangle;
+/**
+ * Convert rectangle to PDF rect format [x1, y1, x2, y2]
+ * @param rect - Rectangle with x, y, width, height
+ * @returns PDF rect array [x1, y1, x2, y2]
+ */
+declare function rectangle_to_pdf_rect(rect: Rectangle): [number, number, number, number];
+/**
+ * Convert PDF rect format [x1, y1, x2, y2] to rectangle
+ * @param pdf_rect - PDF rect array [x1, y1, x2, y2]
+ * @returns Rectangle with x, y, width, height
+ */
+declare function pdf_rect_to_rectangle(pdf_rect: [number, number, number, number]): Rectangle;
+/**
+ * Check if a rectangle is too small (likely a click, not a drag)
+ * @param rect - Rectangle to check
+ * @param min_size - Minimum size in pixels (default: 5)
+ * @returns True if rectangle is too small
+ */
+declare function is_rectangle_too_small(rect: Rectangle, min_size?: number): boolean;
+
+/**
+ * Configuration loader for hazo_pdf
+ * Loads configuration from INI file using hazo_config package (Node.js) or fetch (browser)
+ * Falls back to defaults if config file is missing or invalid
+ */
+
+/**
+ * Load config asynchronously (works in both browser and Node.js)
+ * Uses hazo_config in Node.js, fetch + manual parsing in browser
+ * @param config_file - Path to config file
+ * @returns Promise resolving to PdfViewerConfig
+ */
+declare function load_pdf_config_async(config_file: string): Promise<PdfViewerConfig>;
+/**
+ * Build config object from INI values (shared between browser and Node.js)
+ * @param get_value - Function to get a value from INI (section, key) -> value
+ * @returns Complete PdfViewerConfig object
+ */
+declare function build_config_from_ini(get_value: (section: string, key: string) => string | undefined): PdfViewerConfig;
+/**
+ * Parse a color value from config (hex format)
+ * @param value - Color value from config
+ * @param default_value - Default color if parsing fails
+ * @returns Parsed color value
+ */
+declare function parse_color(value: string | undefined, default_value: string): string;
+/**
+ * Parse an opacity value from config (0.0 to 1.0)
+ * @param value - Opacity value from config
+ * @param default_value - Default opacity if parsing fails
+ * @returns Parsed opacity value
+ */
+declare function parse_opacity(value: string | undefined, default_value: number): number;
+/**
+ * Parse a number value from config
+ * @param value - Number value from config
+ * @param default_value - Default number if parsing fails
+ * @returns Parsed number value
+ */
+declare function parse_number(value: string | undefined, default_value: number): number;
+/**
+ * Parse a string value from config
+ * @param value - String value from config
+ * @param default_value - Default string if value is missing
+ * @returns Parsed string value
+ */
+declare function parse_string(value: string | undefined, default_value: string): string;
+/**
+ * Load PDF viewer configuration from INI file
+ * Supports both Node.js (using hazo_config) and browser (using fetch) environments
+ * @param config_file - Optional path to config file. If not provided, returns defaults
+ * @returns Configuration object with loaded values merged with defaults
+ */
+declare function load_pdf_config(config_file?: string): PdfViewerConfig;
+
+/**
+ * Default configuration values for hazo_pdf
+ * All styling defaults organized by category
+ */
+
+/**
+ * Default PDF Viewer Configuration
+ * These values are used when no config file is provided or when values are missing
+ */
+declare const default_config: PdfViewerConfig;
+
+export { AnnotationOverlay, type CoordinateMapper, type CustomStamp, 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 };