@kopjra/pdf-sentinel 1.0.1 → 1.1.2

package/README.md

@@ -0,0 +1,607 @@
+# pdf-sentinel Documentation
+
+A powerful React/Preact library for viewing and interacting with PDF forms. Built on top of [embed-pdf-viewer](https://github.com/embedpdf/embed-pdf-viewer), pdf-sentinel provides a complete solution for rendering PDF documents with form fields, custom toolbars, internationalization, and signature management.
+
+<img src="pdf-sentinel.png" alt="logo" height="200"/>
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [API Reference](#api-reference)
+  - [usePdfSentinel Hook](#usepdfsentinel-hook)
+  - [Types](#types)
+  - [Toolbar Customization](#toolbar-customization)
+  - [Internationalization](#internationalization)
+- [Examples](#examples)
+- [Browser Support](#browser-support)
+
+## Installation
+
+```bash
+npm install @kopjra/pdf-sentinel
+```
+
+## Quick Start
+
+```tsx
+import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+import "@kopjra/pdf-sentinel/style.css";
+
+function MyPdfViewer() {
+    const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
+        pdf: "/path/to/document.pdf",
+        name: "My Document",
+    });
+
+    return (
+        <div style={{ height: "100vh" }}>
+            <PdfSentinelContainer>
+                <Toolbar />
+                <PdfSentinel />
+            </PdfSentinelContainer>
+        </div>
+    );
+}
+```
+
+## Features
+
+### Core Functionality
+
+- 📄 **PDF Viewing** - Render PDF documents with zoom, scroll, and navigation
+- 📋 **Form Fields** - Support for text inputs, checkboxes, radio buttons, and signature fields
+- ✍️ **Form Validation** - Built-in validation with error highlighting and auto-scroll to errors
+- 🎨 **Toolbar** - Customizable toolbar with zoom, page navigation, and download
+- 🌍 **Internationalization** - Multi-language support with custom translation overrides
+- 🔧 **Custom Buttons** - Extend the toolbar with custom buttons in left/center/right areas
+- 📝 **Signatures** - Native conditional signature support with automatic group coloring
+- 🎯 **Responsive** - Adaptive layout that responds to zoom and scroll events
+
+### Toolbar Features
+
+- Zoom in/out and fit-to-width
+- Page navigation and page count display
+- PDF download capability
+- Custom button support with spacers
+- Multi-language tooltips and labels
+
+### Form Features
+
+- Text field rendering with readonly support
+- Checkbox field rendering with custom styling
+- Radio button field rendering with custom styling
+- Signature field rendering with conditional group coloring
+- Form state management
+- Field validation with error styling
+- Initial values and readonly properties
+
+## API Reference
+
+### usePdfSentinel Hook
+
+The main hook for initializing and controlling the PDF viewer.
+
+#### Signature
+
+```typescript
+function usePdfSentinel(options: PdfSentinelOptions): PdfSentinelResult
+```
+
+#### Options
+
+```typescript
+interface PdfSentinelOptions {
+    /** PDF document URL or ArrayBuffer */
+    pdf: string | ArrayBuffer;
+    
+    /** Document name/identifier */
+    name: string;
+    
+    /** Initial form field values */
+    initialValues?: InitialValuesType;
+    
+    /** Hide the default toolbar */
+    hideToolbar?: boolean;
+    
+    /** Callback when document finishes loading */
+    onDocumentLoaded?: () => void;
+    
+    /** Locale code (en, it, es, fr, de) */
+    locale?: string;
+    
+    /** Custom translations for any locale */
+    translations?: Record<string, Record<string, string>>;
+    
+    /** Custom toolbar buttons */
+    toolbarButtons?: ToolbarItem[];
+    
+    /** Conditional signature configurations */
+    conditionalSignatures?: ConditionalSignature[];
+}
+```
+
+#### Return Value
+
+```typescript
+interface PdfSentinelResult {
+    /** Container component that wraps the PDF viewer and toolbar */
+    PdfSentinelContainer: React.ComponentType<{children: React.ReactNode}>;
+    
+    /** Toolbar component - should be rendered inside PdfSentinelContainer */
+    Toolbar: React.ComponentType<{}>;
+    
+    /** Main PDF viewer component - should be rendered inside PdfSentinelContainer */
+    PdfSentinel: React.ComponentType<{}>;
+    
+    /** Current form state */
+    form: UsePdfFormsResult | null;
+    
+    /** Current page number (1-indexed) */
+    currentPage: number | null;
+    
+    /** Total number of pages */
+    totalPages: number | null;
+    
+    /** Whether PDF is loading */
+    loadingPdf: boolean;
+    
+    /** Whether there was a loading error */
+    loadingError: boolean;
+    
+    /** PDF engine instance */
+    engine: PdfEngine<Blob> | null;
+    
+    /** Whether PDF has been closed */
+    closedPdf: boolean;
+    
+    /** Helper methods */
+    helpers: {
+        zoomIn: () => void;
+        zoomOut: () => void;
+        resetZoom: () => void;
+        scrollToPage: (pageNumber: number) => void;
+        download: () => void;
+    };
+}
+```
+
+### Types
+
+#### InitialValuesType
+
+```typescript
+type InitialValuesType = Record<string, {
+    value: string | boolean;
+    readonly?: boolean;
+}>;
+```
+
+Initial form field values. Each key is a field name.
+
+**Example:**
+```typescript
+const initialValues: InitialValuesType = {
+    "fullName": { value: "John Doe", readonly: false },
+    "signature": { value: true, readonly: true },
+    "agreeToTerms": { value: true },
+};
+```
+
+#### ConditionalSignature
+
+```typescript
+interface ConditionalSignature {
+    index: string;
+    fieldNames: string[];
+}
+```
+
+Defines a group of signature fields that are conditional on the same value.
+
+**Example:**
+```typescript
+const conditionalSignatures: ConditionalSignature[] = [
+    { index: "1", fieldNames: ["signature1", "signature2"] },
+    { index: "2", fieldNames: ["signature3", "signature4"] },
+];
+```
+
+#### UsePdfFormsResult
+
+```typescript
+interface UsePdfFormsResult {
+    fields: Field[];
+    values: Record<string, string | boolean>;
+    setValue: (name: string, value: string | boolean) => void;
+    validate: () => { valid: boolean; errors: Record<string, string> };
+    reload: () => void;
+    errors?: Record<string, string>;
+    showErrors: boolean;
+    scrollToConditionalSignature: (index: string) => Generator;
+}
+```
+
+Represents the current form state.
+
+#### Field
+
+```typescript
+interface Field {
+    name: string;
+    type: "text" | "checkbox" | "signature" | "radiobutton";
+    pageIndex: number;
+    bbox: { x: number; y: number; width: number; height: number };
+    radioValue?: string;
+    readonly?: boolean;
+    required?: boolean;
+    conditionalIndex?: string;
+}
+```
+
+Represents a single form field.
+
+### Toolbar Customization
+
+#### ToolbarItem
+
+```typescript
+type ToolbarItem = ToolbarButton | ToolbarSpacer;
+```
+
+#### ToolbarButton
+
+```typescript
+interface ToolbarButton {
+    id: string;
+    label: string;
+    icon?: string;           // Font Awesome icon class
+    title?: string;          // Tooltip text
+    onClick: () => void;
+    area: "left" | "right";
+    disabled?: boolean;
+    type: "button";
+}
+```
+
+#### ToolbarSpacer
+
+```typescript
+interface ToolbarSpacer {
+    id: string;
+    type: "spacer";
+    area: "left" | "right";
+}
+```
+
+### Internationalization
+
+#### Supported Locales
+
+- `en` - English (default)
+- `it` - Italian
+- `es` - Spanish
+- `fr` - French
+- `de` - German
+
+#### Default Translation Keys
+
+```typescript
+{
+    zoomIn: string;
+    zoomOut: string;
+    resetZoom: string;
+    download: string;
+    pageNumberTitle: string;
+    signature: string;
+}
+```
+
+#### Custom Translations
+
+Override or add translations for any locale:
+
+```typescript
+const translations = {
+    en: {
+        zoomIn: "Enlarge",
+        zoomOut: "Shrink",
+        customKey: "Custom value",
+    },
+    it: {
+        customKey: "Valore personalizzato",
+    },
+};
+```
+
+## Examples
+
+### Basic PDF Viewer
+
+```tsx
+import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+
+export function BasicViewer() {
+    const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
+        pdf: "https://example.com/document.pdf",
+        name: "Document",
+    });
+
+    return (
+        <div style={{ height: "600px" }}>
+            <PdfSentinelContainer>
+                <Toolbar />
+                <PdfSentinel />
+            </PdfSentinelContainer>
+        </div>
+    );
+}
+```
+
+### PDF with Form Fields
+
+```tsx
+import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+
+export function FormViewer() {
+    const { PdfSentinelContainer, Toolbar, PdfSentinel, form } = usePdfSentinel({
+        pdf: "/document.pdf",
+        name: "Form Document",
+        initialValues: {
+            "firstName": { value: "John" },
+            "lastName": { value: "Doe" },
+        },
+    });
+
+    const handleValidate = () => {
+        if (form?.validate()) {
+            console.log("Form is valid, values:", form.values);
+        }
+    };
+
+    return (
+        <>
+            <div style={{ height: "600px" }}>
+                <PdfSentinelContainer>
+                    <Toolbar />
+                    <PdfSentinel />
+                </PdfSentinelContainer>
+            </div>
+            <button onClick={handleValidate}>Validate</button>
+        </>
+    );
+}
+```
+
+### Custom Toolbar Buttons
+
+```tsx
+import { usePdfSentinel, ToolbarItem } from "@kopjra/pdf-sentinel";
+
+export function CustomToolbar() {
+    const customButtons: ToolbarItem[] = [
+        {
+            id: "print-btn",
+            label: "Print",
+            icon: "fal fa-print",
+            title: "Print document",
+            area: "left",
+            type: "button",
+            onClick: () => window.print(),
+        },
+        {
+            id: "spacer",
+            type: "spacer",
+            area: "left",
+        },
+        {
+            id: "share-btn",
+            label: "Share",
+            icon: "fal fa-share",
+            title: "Share document",
+            area: "right",
+            type: "button",
+            onClick: () => {
+                console.log("Share clicked");
+            },
+        },
+    ];
+
+    const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
+        pdf: "/document.pdf",
+        name: "Document",
+        toolbarButtons: customButtons,
+    });
+
+    return (
+        <div style={{ height: "600px" }}>
+            <PdfSentinelContainer>
+                <Toolbar />
+                <PdfSentinel />
+            </PdfSentinelContainer>
+        </div>
+    );
+}
+```
+
+### Multi-Language Support
+
+```tsx
+import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+import { useState } from "react";
+
+export function MultiLanguageViewer() {
+    const [locale, setLocale] = useState("en");
+
+    const customTranslations = {
+        en: {
+            zoomIn: "Zoom In",
+            download: "Download PDF",
+        },
+        it: {
+            zoomIn: "Ingrandisci",
+            download: "Scarica PDF",
+        },
+    };
+
+    const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
+        pdf: "/document.pdf",
+        name: "Document",
+        locale: locale,
+        translations: customTranslations,
+    });
+
+    return (
+        <div>
+            <select onChange={(e) => setLocale(e.target.value)} value={locale}>
+                <option value="en">English</option>
+                <option value="it">Italiano</option>
+            </select>
+            <div style={{ height: "600px", marginTop: "10px" }}>
+                <PdfSentinelContainer>
+                    <Toolbar />
+                    <PdfSentinel />
+                </PdfSentinelContainer>
+            </div>
+        </div>
+    );
+}
+```
+
+### Conditional Signatures with Groups
+
+```tsx
+import { usePdfSentinel, ConditionalSignature } from "@kopjra/pdf-sentinel";
+
+export function SignatureViewer() {
+    const conditionalSignatures: ConditionalSignature[] = [
+        { index: "1", fieldNames: ["authorizedBy", "authorizedDate"] },
+        { index: "2", fieldNames: ["approvedBy", "approvedDate"] },
+    ];
+
+    const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
+        pdf: "/contract.pdf",
+        name: "Contract",
+        conditionalSignatures: conditionalSignatures,
+    });
+
+    return (
+        <div style={{ height: "600px" }}>
+            <PdfSentinelContainer>
+                <Toolbar />
+                <PdfSentinel />
+            </PdfSentinelContainer>
+        </div>
+    );
+}
+```
+
+### Form Validation with Error Handling
+
+```tsx
+import { usePdfSentinel } from "@kopjra/pdf-sentinel";
+
+export function FormWithValidation() {
+    const { PdfSentinelContainer, Toolbar, PdfSentinel, form } = usePdfSentinel({
+        pdf: "/form.pdf",
+        name: "Application Form",
+        initialValues: {
+            "email": { value: "" },
+            "phone": { value: "" },
+        },
+    });
+
+    const handleSubmit = () => {
+        if (!form) return;
+
+        // Validate required fields
+        let isValid = true;
+        const errors: Record<string, string> = {};
+
+        if (!form.values["email"]) {
+            errors["email"] = "Email is required";
+            isValid = false;
+        }
+
+        if (!form.values["phone"]) {
+            errors["phone"] = "Phone is required";
+            isValid = false;
+        }
+
+        if (!isValid) {
+            // Set errors and show them
+            Object.entries(errors).forEach(([field, error]) => {
+                form.setFieldError(field, error);
+            });
+        } else {
+            console.log("Form submitted:", form.values);
+        }
+    };
+
+    return (
+        <>
+            <div style={{ height: "600px" }}>
+                <PdfSentinelContainer>
+                    <Toolbar />
+                    <PdfSentinel />
+                </PdfSentinelContainer>
+            </div>
+            <button onClick={handleSubmit}>Submit</button>
+        </>
+    );
+}
+```
+
+### Using React and Preact Variants
+
+To use the Preact variant use import from `@kopjra/pdf-sentinel/preact` instead of `@kopjra/pdf-sentinel`.
+The React is the default one, however you can also use the import `@kopjra/pdf-sentinel/react` for clarity.
+
+```tsx
+// React variant
+import { usePdfSentinel } from "@kopjra/pdf-sentinel/react";
+
+// Preact variant (same import, different package)
+import { usePdfSentinel } from "@kopjra/pdf-sentinel/preact";
+
+export function Viewer() {
+    const { PdfSentinelContainer, Toolbar, PdfSentinel } = usePdfSentinel({
+        pdf: "/document.pdf",
+        name: "Document",
+    });
+
+    return (
+        <div style={{ height: "600px" }}>
+            <PdfSentinelContainer>
+                <Toolbar />
+                <PdfSentinel />
+            </PdfSentinelContainer>
+        </div>
+    );
+}
+```
+
+The same code works for both React and Preact - the library automatically uses the correct variant based on your project configuration.
+
+## Browser Support
+
+- Chrome/Chromium (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+1. TypeScript types are correctly defined
+2. All code follows the project style guide
+3. `npm run typecheck` passes
+4. Changes are tested in both React and Preact variants
+
+## License
+
+ISC
+
+1