hazo_pdf 1.7.0 → 2.0.0

package/SETUP_CHECKLIST.md

@@ -0,0 +1,693 @@
+# Hazo PDF Setup Checklist
+
+This guide walks you through setting up and using the Hazo PDF library in your React application.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- [ ] **Node.js 18+** installed on your system
+- [ ] **npm** or **yarn** package manager
+- [ ] A **React 18+** application (Next.js, Vite, Create React App, etc.)
+- [ ] **TypeScript** support (recommended but optional)
+
+## Installation Steps
+
+### 1. Install the Package
+
+```bash
+npm install hazo_pdf
+```
+
+Or with yarn:
+
+```bash
+yarn add hazo_pdf
+```
+
+#### Optional: Install hazo_logs for Logging
+
+For structured logging and debugging, optionally install hazo_logs:
+
+```bash
+npm install hazo_logs
+```
+
+Or with yarn:
+
+```bash
+yarn add hazo_logs
+```
+
+Note: hazo_logs is an optional peer dependency. If not installed, hazo_pdf will use console-based logging.
+
+#### Optional: Install hazo_files for Remote Storage
+
+For remote file storage integration (Google Drive, Dropbox, local filesystem), optionally install hazo_files:
+
+```bash
+npm install hazo_files
+```
+
+Or with yarn:
+
+```bash
+yarn add hazo_files
+```
+
+Note: hazo_files is an optional peer dependency. When installed, it enables loading and saving PDFs from remote storage providers.
+
+### 2. Import Styles
+
+Choose the appropriate CSS file based on your application setup:
+
+**Option A: For apps with existing styles (Recommended)**
+
+Import `styles.css` - this does NOT include Tailwind preflight/base resets:
+
+```tsx
+import 'hazo_pdf/styles.css';
+```
+
+**Option B: For standalone apps**
+
+Import `styles-full.css` - includes Tailwind preflight/base styles:
+
+```tsx
+import 'hazo_pdf/styles-full.css';
+```
+
+### 3. Import the Component
+
+```tsx
+import { PdfViewer } from 'hazo_pdf';
+```
+
+Or for dialog/modal usage:
+
+```tsx
+import { PdfViewerDialog } from 'hazo_pdf';
+```
+
+For TypeScript projects, also import types:
+
+```tsx
+import type {
+  PdfViewerProps,
+  PdfViewerDialogProps,
+  PdfAnnotation,
+  PdfViewerRef,
+  HighlightFieldInfo
+} from 'hazo_pdf';
+```
+
+### 4. Create a Container with Explicit Dimensions
+
+The PDF viewer requires its parent container to have explicit width and height:
+
+```tsx
+<div style={{ width: '100%', height: '600px' }}>
+  <PdfViewer url="/document.pdf" />
+</div>
+```
+
+### 5. Verify the Setup
+
+Create a simple test component to verify everything works:
+
+```tsx
+import { PdfViewer } from 'hazo_pdf';
+import 'hazo_pdf/styles.css';
+
+export default function TestViewer() {
+  return (
+    <div style={{ width: '100%', height: '800px' }}>
+      <PdfViewer
+        url="/path/to/test.pdf"
+        on_load={(pdf) => console.log('PDF loaded:', pdf.numPages, 'pages')}
+        on_error={(error) => console.error('PDF error:', error)}
+      />
+    </div>
+  );
+}
+```
+
+## Configuration (Optional)
+
+### 6. Create a Configuration File
+
+For advanced styling customization, create a configuration INI file:
+
+```bash
+mkdir -p config
+touch config/hazo_pdf_config.ini
+```
+
+Example configuration:
+
+```ini
+[viewer]
+viewer_background_color = #f5f5f5
+append_timestamp_to_text_edits = true
+annotation_text_suffix_fixed_text = user_x
+
+[freetext_annotation]
+freetext_text_color = #0066cc
+freetext_background_color = rgb(230, 243, 255)
+freetext_background_opacity = 0.1
+freetext_border_color = #003366
+freetext_border_width = 1
+
+[toolbar]
+toolbar_background_color = rgb(240, 248, 255)
+toolbar_font_color = rgb(30, 58, 138)
+toolbar_button_background_color = rgb(219, 234, 254)
+toolbar_button_save_background_color = rgb(34, 197, 94)
+```
+
+### 7. Use Configuration File
+
+Pass the config file path to the component:
+
+```tsx
+<PdfViewer
+  url="/document.pdf"
+  config_file="config/hazo_pdf_config.ini"
+/>
+```
+
+## Using the Ref API (Optional)
+
+If you need programmatic control over highlights, set up a ref:
+
+### 8. Create a Ref
+
+```tsx
+import { useRef } from 'react';
+import { PdfViewer, PdfViewerRef } from 'hazo_pdf';
+
+function MyComponent() {
+  const viewer_ref = useRef<PdfViewerRef>(null);
+
+  return <PdfViewer ref={viewer_ref} url="/document.pdf" />;
+}
+```
+
+### 9. Use Ref Methods
+
+The ref exposes three methods for highlight management:
+
+```tsx
+// Create a highlight
+const highlight_id = viewer_ref.current?.highlight_region(
+  0,                      // page_index (zero-based)
+  [100, 500, 300, 550],   // rect in PDF coordinates [x1, y1, x2, y2]
+  {
+    border_color: '#FF0000',
+    background_color: '#FFFF00',
+    background_opacity: 0.4
+  }
+);
+
+// Remove a specific highlight
+const removed = viewer_ref.current?.remove_highlight(highlight_id);
+
+// Clear all API-created highlights
+viewer_ref.current?.clear_all_highlights();
+```
+
+### 10. Understand PDF Coordinates
+
+Important notes about the coordinate system:
+
+- Coordinates are in PDF space (points), not screen pixels
+- Origin is at the **bottom-left** corner (Y increases upward)
+- Rectangle format: `[x1, y1, x2, y2]` where (x1, y1) is bottom-left, (x2, y2) is top-right
+
+## Troubleshooting
+
+### PDF Not Displaying
+
+- [ ] Verify the parent container has explicit width and height
+- [ ] Check the PDF URL is correct and accessible
+- [ ] Check browser console for errors
+- [ ] Ensure CSS file is imported
+- [ ] Verify the PDF file is not corrupted
+
+### Styles Not Applying
+
+- [ ] Confirm you imported either `styles.css` or `styles-full.css`
+- [ ] Check for CSS conflicts with existing styles
+- [ ] Try using `styles-full.css` if using `styles.css` doesn't work
+- [ ] Verify configuration file path is correct (if using config file)
+
+### TypeScript Errors
+
+- [ ] Ensure you're using TypeScript 4.5+
+- [ ] Import types from `hazo_pdf`: `import type { PdfViewerRef } from 'hazo_pdf';`
+- [ ] Check that React types are installed: `npm install --save-dev @types/react`
+
+### Ref Not Working
+
+- [ ] Verify you imported `PdfViewerRef` type: `import type { PdfViewerRef } from 'hazo_pdf';`
+- [ ] Ensure you're using `useRef<PdfViewerRef>(null)`
+- [ ] Check that the ref is attached: `<PdfViewer ref={viewer_ref} ... />`
+- [ ] Verify you're accessing ref methods after component mounts: `viewer_ref.current?.highlight_region(...)`
+
+### Highlights Not Appearing
+
+- [ ] Verify coordinates are in PDF space, not screen space
+- [ ] Check that page_index is zero-based (first page = 0)
+- [ ] Ensure rectangle coordinates are valid (x1 < x2, y1 < y2)
+- [ ] Verify the PDF has loaded before calling highlight methods
+- [ ] Check colors are in valid hex format (e.g., "#FF0000")
+
+## Post-Installation Configuration
+
+### Enable Logging (Optional)
+
+To enable structured logging with hazo_logs:
+
+#### 1. Create Logger Configuration File
+
+```bash
+mkdir -p config
+touch config/hazo_logs_config.ini
+```
+
+Example configuration:
+
+```ini
+[logging]
+log_level = DEBUG
+log_format = json
+output_file = logs/hazo_pdf.log
+
+[console]
+enabled = true
+log_level = INFO
+```
+
+#### 2. Initialize Logger in Your App
+
+```tsx
+import { PdfViewer } from 'hazo_pdf';
+import { create_logger } from 'hazo_logs';
+import 'hazo_pdf/styles.css';
+
+// Create logger instance
+const logger = create_logger('my_app', 'config/hazo_logs_config.ini');
+
+function App() {
+  return (
+    <div style={{ width: '100%', height: '800px' }}>
+      <PdfViewer
+        url="/document.pdf"
+        logger={logger}
+        on_load={(pdf) => console.log('PDF loaded:', pdf.numPages, 'pages')}
+      />
+    </div>
+  );
+}
+```
+
+#### 3. Alternative: Custom Logger
+
+You can also provide a custom logger that matches the Logger interface:
+
+```tsx
+import { PdfViewer } from 'hazo_pdf';
+
+const custom_logger = {
+  info: (message, data) => console.log('[INFO]', message, data),
+  debug: (message, data) => console.debug('[DEBUG]', message, data),
+  warn: (message, data) => console.warn('[WARN]', message, data),
+  error: (message, data) => console.error('[ERROR]', message, data),
+};
+
+<PdfViewer
+  url="/document.pdf"
+  logger={custom_logger}
+/>
+```
+
+**What Gets Logged:**
+- PDF conversion operations (image, text, Excel to PDF)
+- PDF loading and rendering events
+- Annotation operations (create, update, delete)
+- Error conditions and warnings
+
+**Note:** If no logger is provided, hazo_pdf automatically falls back to console logging with `[hazo_pdf]` prefix.
+
+### Enable Metadata Sidepanel (Optional)
+
+To display metadata in a sidepanel:
+
+```tsx
+import type { MetadataInput } from 'hazo_pdf';
+
+const metadata: MetadataInput = {
+  header: [
+    { style: 'h1', label: 'Document Information' }
+  ],
+  data: [
+    {
+      label: 'Title',
+      style: 'h3',
+      value: 'My Document',
+      editable: true
+    }
+  ],
+  footer: [
+    { style: 'body', label: 'Version 1.0' }
+  ]
+};
+
+<PdfViewer
+  url="/document.pdf"
+  sidepanel_metadata_enabled={true}
+  metadata_input={metadata}
+  on_metadata_change={(updatedRow, allData) => {
+    console.log('Metadata updated:', updatedRow);
+    return { updatedRow, allData };
+  }}
+/>
+```
+
+### Add Custom Stamps (Optional)
+
+Configure custom stamps for quick annotation:
+
+```tsx
+const custom_stamps = JSON.stringify([
+  {
+    name: "Approved",
+    text: "✓",
+    order: 1,
+    time_stamp_suffix_enabled: true,
+    background_color: "rgb(200, 255, 200)",
+    border_size: 1,
+    font_color: "#000000",
+    font_weight: "bold",
+    font_size: 16
+  }
+]);
+
+<PdfViewer
+  url="/document.pdf"
+  right_click_custom_stamps={custom_stamps}
+/>
+```
+
+### Enable Multi-File Support (Optional)
+
+Manage and view multiple PDF files:
+
+```tsx
+import type { FileItem, UploadResult } from 'hazo_pdf';
+
+const [files, setFiles] = useState<FileItem[]>([]);
+
+const handle_upload = async (file: File, converted_pdf?: Uint8Array): Promise<UploadResult> => {
+  // Upload to server
+  const formData = new FormData();
+  formData.append('file', converted_pdf || file);
+
+  const response = await fetch('/api/upload', {
+    method: 'POST',
+    body: formData
+  });
+
+  const result = await response.json();
+
+  return result.success
+    ? { success: true, file_id: result.file_id, url: result.url }
+    : { success: false, error: result.error };
+};
+
+<PdfViewer
+  files={files}
+  on_files_change={setFiles}
+  on_upload={handle_upload}
+/>
+```
+
+### Enable hazo_files Integration (Optional)
+
+Load and save PDFs from remote storage:
+
+```tsx
+import { FileManager } from 'hazo_files';
+
+// Initialize FileManager
+const file_manager = new FileManager({
+  storage_type: 'google_drive',
+  config_file: 'config/hazo_files_config.ini'
+});
+
+await file_manager.initialize();
+
+<PdfViewer
+  url="/remote/path/document.pdf"
+  file_manager={file_manager}
+  save_path="/remote/path/document.pdf"
+/>
+```
+
+### Enable Data Extraction (Optional)
+
+Extract structured data using LLM prompts:
+
+```tsx
+<PdfViewer
+  url="/invoice.pdf"
+  show_extract_button={true}
+  extract_prompt_area="invoices"
+  extract_prompt_key="extract_invoice_data"
+  extract_api_endpoint="/api/extract"
+  on_extract_complete={(data) => console.log('Extracted:', data)}
+  on_extract_error={(error) => console.error('Error:', error)}
+/>
+```
+
+### Use Server-Side Extraction (Optional)
+
+For server-side extraction in API routes, use `hazo_pdf/server`:
+
+```typescript
+// In Next.js API route or server action
+import { extract_document_data } from 'hazo_pdf/server';
+
+const result = await extract_document_data(
+  { file_path: '/path/to/document.pdf' },
+  {
+    prompt_area: 'invoices',
+    prompt_key: 'extract_invoice_data',
+    save_to_hazo_files: true,
+  }
+);
+
+if (result.success) {
+  console.log('Extracted:', result.data);
+}
+```
+
+**Note:** Requires `hazo_llm_api` package to be installed.
+
+### Use Text Snippet Extraction (Optional)
+
+Extract a cropped image snippet from a PDF with matching text highlighted:
+
+```typescript
+import { extract_text_snippet } from 'hazo_pdf/server';
+
+const result = await extract_text_snippet(
+  { file_path: '/path/to/document.pdf' },
+  {
+    search_text: '$16,578.20',
+    snippet_size: 'half',    // 'full' | 'half' | 'quarter'
+    match_mode: 'first',     // 'first' | 'all'
+  }
+);
+
+if (result.success) {
+  const snippet = result.snippets[0];
+  // snippet.image_buffer  - PNG Buffer
+  // snippet.image_base64  - Base64 PNG
+}
+```
+
+**Note:** Requires `@napi-rs/canvas` (usually already installed via `pdfjs-dist`). Server-only.
+
+### Use PdfViewerDialog for Modals (Optional)
+
+Display PDFs in a modal dialog with built-in backdrop and escape key handling:
+
+```tsx
+import { useState } from 'react';
+import { PdfViewerDialog } from 'hazo_pdf';
+
+function App() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Open PDF</button>
+      <PdfViewerDialog
+        open={isOpen}
+        on_open_change={setIsOpen}
+        url="/document.pdf"
+        dialog_width="90vw"
+        dialog_height="90vh"
+        // All PdfViewer props also work
+        on_load={(pdf) => console.log('Loaded', pdf.numPages)}
+      />
+    </>
+  );
+}
+```
+
+### Enable Auto-Highlighting (Optional)
+
+Automatically highlight extracted field values in the PDF:
+
+```tsx
+import type { HighlightFieldInfo } from 'hazo_pdf';
+
+// Highlighted fields (automatically searches and highlights in PDF)
+const highlight_fields_info: HighlightFieldInfo[] = [
+  { field_name: 'invoice_number', value: 'INV-2024-001', page_index: 0 },
+  { field_name: 'total_amount', value: '$1,250.00', page_index: 0 },
+  { field_name: 'customer_name', value: 'Acme Corp', page_index: 0 },
+];
+
+<PdfViewer
+  url="/invoice.pdf"
+  highlight_fields_info={highlight_fields_info}
+  show_file_info_button={true}
+/>
+```
+
+**Features:**
+- Automatically searches for field values in the PDF text layer
+- Creates visual highlight boxes at found positions
+- Displays field names and values in File Info sidepanel
+- Smart text matching (exact first, then partial with normalization)
+- Configurable colors, opacity, and search behavior
+
+**Customize highlight appearance:**
+
+```tsx
+<PdfViewer
+  url="/invoice.pdf"
+  highlight_fields_info={highlight_fields_info}
+  auto_highlight_options={{
+    border_color: '#0066CC',
+    background_color: '#E6F2FF',
+    background_opacity: 0.4,
+  }}
+/>
+```
+
+### Enable File Info Sidepanel (Optional)
+
+Display extracted document data in a sidepanel:
+
+```tsx
+import type { HighlightFieldInfo } from 'hazo_pdf';
+
+// Document-level data
+const doc_data = {
+  invoice_number: 'INV-2024-001',
+  total_amount: 1250.00,
+  customer_name: 'Acme Corp',
+};
+
+// Highlighted fields (auto-highlighted and shown in sidepanel)
+const highlight_fields_info: HighlightFieldInfo[] = [
+  { field_name: 'invoice_number', value: 'INV-2024-001', page_index: 0 },
+  { field_name: 'total_amount', value: '$1,250.00', page_index: 0 },
+  { field_name: 'customer_name', value: 'Acme Corp', page_index: 0 },
+];
+
+<PdfViewer
+  url="/invoice.pdf"
+  doc_data={doc_data}
+  highlight_fields_info={highlight_fields_info}
+  show_file_info_button={true}
+/>
+```
+
+**Alternative: Legacy File Metadata Format**
+
+For file-based metadata with filename matching:
+
+```tsx
+import type { FileMetadataInput } from 'hazo_pdf';
+
+const file_metadata: FileMetadataInput = [
+  {
+    filename: 'invoice.pdf',
+    file_data: {
+      invoice_number: 'INV-2024-001',
+      total_amount: '$1,250.00',
+      line_items: [
+        { item: 'Widget A', quantity: '10', price: '$50.00' },
+        { item: 'Widget B', quantity: '15', price: '$50.00' }
+      ]
+    }
+  }
+];
+
+<PdfViewer
+  url="/invoice.pdf"
+  file_metadata={file_metadata}
+  show_file_info_button={true}
+/>
+```
+
+**Alternative: hazo_files Extraction Data**
+
+For displaying extraction history from hazo_files `file_data.raw_data`:
+
+```tsx
+import type { ExtractionEntry } from 'hazo_pdf';
+
+const extractions: ExtractionEntry[] = [
+  {
+    id: 'ext_123',
+    extracted_at: '2026-03-30T10:00:00Z',
+    source: 'autofill',
+    data: {
+      document_date: '30 June 2024',
+      total_amount: '$29,696.60',
+    },
+  },
+];
+
+<PdfViewer
+  url="/invoice.pdf"
+  extractions={extractions}
+  show_file_info_button={true}
+/>
+```
+
+## Next Steps
+
+- [ ] Read the [README.md](./README.md) for detailed API documentation
+- [ ] Explore the [Auto-Highlighting](./README.md#auto-highlighting) feature for automatic field highlighting
+- [ ] Explore the [Programmatic Highlight API](./README.md#programmatic-highlight-api) section for manual highlight control
+- [ ] Review configuration options in `config/hazo_pdf_config.ini`
+- [ ] Check out example implementations in the README
+- [ ] Test annotation features (Square, FreeText, Stamps)
+- [ ] Implement save functionality with `on_save` callback
+
+## Support
+
+If you encounter issues not covered in this checklist:
+
+1. Check the [README.md](./README.md) for detailed documentation
+2. Review the configuration file (`config/hazo_pdf_config.ini`) for all available options
+3. Examine the test app code in the `app/` directory for working examples
+4. Check browser console for error messages
+5. Verify all prerequisites are met