@signiphi/page-assembly 0.2.0-beta.1 → 0.2.0-beta.3

package/README.md

@@ -1,19 +1,24 @@
 # @signiphi/page-assembly
 
-React component for PDF and image page manipulation - upload, reorder, delete, and combine pages into a single document.
+> A powerful React component for PDF and image page manipulation - upload, reorder, delete, and combine pages into a single document.
 
-## Features
+[![npm version](https://img.shields.io/npm/v/@signiphi/page-assembly.svg)](https://www.npmjs.com/package/@signiphi/page-assembly)
+[![License](https://img.shields.io/npm/l/@signiphi/page-assembly.svg)](https://github.com/signiphi/signiphi)
 
-- 📄 **File Upload** - Upload multiple PDF files and images
-- 🔄 **Drag & Drop** - Reorder pages and files with intuitive drag-and-drop
-- ✂️ **Multi-Select** - Select multiple pages with Ctrl+Click, Shift+Click, or checkboxes
-- 🗑️ **Bulk Operations** - Move or delete multiple pages at once
+## ✨ Features
+
+- 📄 **Multi-File Upload** - Upload multiple PDF files and images simultaneously
+- 🔄 **Drag & Drop Interface** - Intuitive drag-and-drop for reordering pages and files
+- ✂️ **Advanced Selection** - Multi-select pages with Ctrl+Click, Shift+Click, or checkboxes
+- 🗑️ **Bulk Operations** - Move or delete multiple pages at once with ease
 - 🖼️ **Image Support** - Convert and combine images (PNG, JPEG, WebP) into PDFs
-- 📦 **PDF Assembly** - Generate a final assembled PDF with all selected pages
-- ♻️ **State Management** - Save and restore page assembly state
-- 🎨 **Customizable** - Scoped styles that don't leak to parent application
+- 📦 **PDF Assembly** - Generate a final assembled PDF with all selected pages in order
+- ♻️ **State Management** - Save and restore page assembly state for persistence
+- 🎨 **Scoped Styling** - CSS is scoped and won't conflict with your application styles
+- ⚡ **Performance** - Optimized for handling large documents with many pages
+- 🔒 **Client-Side** - All processing happens in the browser, no server required
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @signiphi/page-assembly
@@ -28,12 +33,22 @@ yarn add @signiphi/page-assembly
 This package requires the following peer dependencies:
 
 ```bash
-npm install react react-dom lucide-react @radix-ui/react-alert-dialog @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-select @radix-ui/react-tooltip
+npm install react react-dom lucide-react \
+  @radix-ui/react-alert-dialog \
+  @radix-ui/react-dialog \
+  @radix-ui/react-dropdown-menu \
+  @radix-ui/react-label \
+  @radix-ui/react-select \
+  @radix-ui/react-tooltip
 ```
 
-## Usage
+Or install them all at once:
+
+```bash
+npm install @signiphi/page-assembly react react-dom lucide-react @radix-ui/react-alert-dialog @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-select @radix-ui/react-tooltip
+```
 
-### Basic Example
+## 🚀 Quick Start
 
 ```tsx
 import { useRef } from 'react';
@@ -78,8 +93,12 @@ function App() {
 }
 ```
 
+## 📖 Usage Examples
+
 ### With Initial PDF
 
+Load an existing PDF as the starting point:
+
 ```tsx
 import { PageAssembler } from '@signiphi/page-assembly';
 import '@signiphi/page-assembly/styles';
@@ -110,6 +129,8 @@ function App() {
 
 ### With State Persistence
 
+Save and restore the page assembly state:
+
 ```tsx
 import { PageAssembler, PageAssemblerState } from '@signiphi/page-assembly';
 import '@signiphi/page-assembly/styles';
@@ -148,57 +169,166 @@ function App() {
 }
 ```
 
-## API Reference
+### Template Mode (Disable File Upload)
+
+Use when you want users to only manipulate pages from a pre-loaded document:
+
+```tsx
+import { PageAssembler } from '@signiphi/page-assembly';
+import '@signiphi/page-assembly/styles';
+
+function App() {
+  const [templatePdf, setTemplatePdf] = useState<Uint8Array | null>(null);
+
+  useEffect(() => {
+    // Load template PDF
+    fetch('/template.pdf')
+      .then(res => res.arrayBuffer())
+      .then(buffer => setTemplatePdf(new Uint8Array(buffer)));
+  }, []);
+
+  return (
+    <div className="signiphi-page-assembly">
+      <PageAssembler 
+        initialPdf={templatePdf || undefined}
+        disableFileUpload={true}
+      />
+    </div>
+  );
+}
+```
+
+### Upload to Server
+
+Assemble and upload the PDF to your backend:
+
+```tsx
+const handleAssembleAndUpload = async () => {
+  if (!assemblerRef.current) return;
+  
+  try {
+    // Assemble the PDF
+    const pdfBlob = await assemblerRef.current.assemble();
+    
+    // Create form data
+    const formData = new FormData();
+    formData.append('pdf', pdfBlob, 'assembled.pdf');
+    
+    // Upload to server
+    const response = await fetch('/api/documents/upload', {
+      method: 'POST',
+      body: formData
+    });
+    
+    if (response.ok) {
+      const result = await response.json();
+      console.log('Upload successful:', result);
+    }
+  } catch (error) {
+    console.error('Failed to assemble/upload PDF:', error);
+  }
+};
+```
+
+### Custom Image Sizing
+
+Control how images are converted to PDF pages:
+
+```tsx
+const handleAssemble = async () => {
+  if (!assemblerRef.current) return;
+  
+  // Use original image dimensions
+  const pdfBlob = await assemblerRef.current.assemble({
+    imageSizing: 'original-size'
+  });
+  
+  // Or use auto letter sizing (default)
+  const pdfBlob2 = await assemblerRef.current.assemble({
+    imageSizing: 'auto-letter'
+  });
+};
+```
+
+### Monitor State Changes
+
+Track when users add, remove, or reorder pages:
+
+```tsx
+function App() {
+  const handleStateChange = (state: PageAssemblerState) => {
+    const totalPages = state.files.reduce((acc, file) => acc + file.pages.length, 0);
+    console.log(`Total files: ${state.files.length}`);
+    console.log(`Total pages: ${totalPages}`);
+    console.log(`Selected pages: ${state.selection.length}`);
+  };
+
+  return (
+    <div className="signiphi-page-assembly">
+      <PageAssembler 
+        onChange={handleStateChange}
+        onValidityChange={(isValid) => {
+          if (!isValid) {
+            console.warn('No pages to assemble');
+          }
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## 📚 API Reference
 
 ### PageAssembler Props
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `initialPdf` | `File \| Blob \| ArrayBuffer \| Uint8Array` | Optional initial PDF to pre-load |
-| `initialState` | `PageAssemblerState` | Optional initial state to restore previous session |
-| `onChange` | `(state: PageAssemblerState) => void` | Called when state changes (files/pages added/removed/reordered) |
-| `onValidityChange` | `(isValid: boolean) => void` | Called when validity changes (e.g., 0 pages) |
-| `limits` | `{ maxFileSizeMB?: number; maxTotalPages?: number }` | Optional file size and page count limits |
-| `disableFileUpload` | `boolean` | Disable file upload UI (for template-only flows) |
-| `className` | `string` | Optional className passthrough |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `initialPdf` | `File \| Blob \| ArrayBuffer \| Uint8Array` | `undefined` | Optional initial PDF to pre-load into the assembler |
+| `initialState` | `PageAssemblerState` | `undefined` | Optional initial state to restore previous session |
+| `onChange` | `(state: PageAssemblerState) => void` | `undefined` | Called when state changes (files/pages added/removed/reordered) |
+| `onValidityChange` | `(isValid: boolean) => void` | `undefined` | Called when validity changes (e.g., when there are 0 pages) |
+| `limits` | `{ maxFileSizeMB?: number; maxTotalPages?: number }` | `undefined` | Optional file size and page count limits |
+| `disableFileUpload` | `boolean` | `false` | Disable file upload UI (useful for template-only workflows) |
+| `className` | `string` | `undefined` | Optional className passthrough for custom styling |
 
 ### PageAssemblerHandle Methods
 
-The `ref` provides access to imperative methods:
+Access these methods via the `ref`:
 
 | Method | Type | Description |
 |--------|------|-------------|
-| `assemble` | `(opts?: AssembleOptions) => Promise<Blob>` | Assembles current pages into a single PDF |
-| `getSummary` | `() => { totalFiles: number; totalPages: number }` | Returns summary of current state |
-| `isBusy` | `() => boolean` | Returns true if loading/assembling |
-| `getState` | `() => PageAssemblerState` | Returns current state |
+| `assemble` | `(opts?: AssembleOptions) => Promise<Blob>` | Assembles current pages into a single PDF blob |
+| `getSummary` | `() => { totalFiles: number; totalPages: number }` | Returns summary information about current state |
+| `isBusy` | `() => boolean` | Returns true if currently loading or assembling |
+| `getState` | `() => PageAssemblerState` | Returns the current state (files, pages, selection) |
 
 ### Types
 
 ```typescript
 interface PageInfo {
-  id: string;
-  srcIndex: number;
-  thumbUrl: string;
-  width?: number;
-  height?: number;
-  mime: string;
-  originalFileId?: string;
+  id: string;              // Unique page identifier
+  srcIndex: number;        // Original page index in source document
+  thumbUrl: string;        // Data URL for thumbnail preview
+  width?: number;          // Page width in points
+  height?: number;         // Page height in points
+  mime: string;           // MIME type (application/pdf or image/*)
+  originalFileId?: string; // ID of the source file
 }
 
 interface FileInfo {
-  id: string;
-  name: string;
-  type: "pdf" | "image";
-  originalFile: File;
-  originalBytes: Uint8Array;
-  pages: PageInfo[];
+  id: string;              // Unique file identifier
+  name: string;            // Original filename
+  type: "pdf" | "image";   // File type
+  originalFile: File;      // Original File object
+  originalBytes: Uint8Array; // Original file bytes
+  pages: PageInfo[];       // Array of pages from this file
 }
 
 interface PageAssemblerState {
-  files: FileInfo[];
-  selection: string[];
-  lastSelectedPageId?: string;
+  files: FileInfo[];           // All uploaded files
+  selection: string[];         // IDs of currently selected pages
+  lastSelectedPageId?: string; // ID of last selected page (for shift-click)
 }
 
 interface AssembleOptions {
@@ -206,91 +336,152 @@ interface AssembleOptions {
 }
 ```
 
-## Styling
+## 🎨 Styling
+
+The package includes scoped Tailwind CSS styles that won't conflict with your application.
 
-The package includes scoped Tailwind CSS styles. Import the styles in your application:
+### Import Styles
 
 ```tsx
 import '@signiphi/page-assembly/styles';
 ```
 
-All styles are prefixed with `.signiphi-page-assembly` to prevent conflicts with your application's styles.
+All styles are prefixed with `.signiphi-page-assembly` to prevent conflicts.
 
 ### Custom Styling
 
-You can override the default styles by wrapping the component in a container with custom CSS:
+Override default styles by wrapping the component:
 
 ```tsx
-<div className="my-custom-page-assembly signiphi-page-assembly">
+<div className="my-custom-styles signiphi-page-assembly">
   <PageAssembler />
 </div>
 ```
 
-## Advanced Usage
+Then add your custom CSS:
 
-### Working with Assembled PDF
+```css
+.my-custom-styles {
+  /* Your custom styles here */
+}
+```
 
-```tsx
-const handleAssemble = async () => {
-  if (!assemblerRef.current) return;
-  
-  const pdfBlob = await assemblerRef.current.assemble();
-  
-  // Upload to server
-  const formData = new FormData();
-  formData.append('pdf', pdfBlob, 'assembled.pdf');
-  
-  await fetch('/api/upload', {
-    method: 'POST',
-    body: formData
-  });
-};
+## 🏗️ Architecture
+
+The PageAssembler component is built with:
+
+- **PDF Processing**: Uses `pdf-lib` for PDF manipulation and assembly
+- **PDF Rendering**: Uses `pdfjs-dist` for rendering PDF thumbnails
+- **Drag & Drop**: Uses `react-dnd` for intuitive page reordering
+- **UI Components**: Uses Radix UI for accessible, unstyled component primitives
+- **State Management**: React hooks for efficient state management
+- **Performance**: Optimized with React.memo, useMemo, and useCallback
+
+### Component Structure
+
+```
+PageAssembler
+├── FileUploadArea (drag & drop, file selection)
+├── FileList (list of uploaded files)
+│   └── FileCard (individual file with pages)
+│       └── PageThumbnail[] (draggable page previews)
+└── BulkActions (multi-select operations)
 ```
 
-### Getting Summary Information
+## 🔧 Troubleshooting
+
+### PDF.js Worker Issues
+
+If you encounter errors related to PDF.js worker, make sure you're properly configured:
 
 ```tsx
-const assemblerRef = useRef<PageAssemblerHandle>(null);
+// In your app's entry point (e.g., main.tsx or App.tsx)
+import { GlobalWorkerOptions } from 'pdfjs-dist';
 
-const summary = assemblerRef.current?.getSummary();
-console.log(`Total files: ${summary.totalFiles}`);
-console.log(`Total pages: ${summary.totalPages}`);
+// Set the worker source
+GlobalWorkerOptions.workerSrc = `//unpkg.com/pdfjs-dist@5.3.93/build/pdf.worker.min.mjs`;
 ```
 
-### Checking if Busy
+### Large File Performance
+
+For better performance with large files:
 
+1. Set appropriate limits:
+```tsx
+<PageAssembler 
+  limits={{
+    maxFileSizeMB: 10,      // Limit individual file size
+    maxTotalPages: 50       // Limit total page count
+  }}
+/>
+```
+
+2. Implement loading states:
 ```tsx
 const isBusy = assemblerRef.current?.isBusy();
 if (isBusy) {
-  console.log('Page assembler is currently processing...');
+  return <LoadingSpinner />;
 }
 ```
 
-## Browser Support
+### Memory Management
+
+When working with many large files, consider:
+
+- Limiting the number of concurrent file uploads
+- Clearing state when unmounting
+- Using the `onChange` callback to implement auto-save and state cleanup
+
+## 🌐 Browser Support
+
+| Browser | Minimum Version |
+|---------|-----------------|
+| Chrome | Latest 2 versions |
+| Edge | Latest 2 versions |
+| Firefox | Latest 2 versions |
+| Safari | Latest 2 versions |
+
+**Note**: This component requires modern browser APIs including:
+- Web Workers (for PDF.js)
+- FileReader API
+- Blob API
+- Drag and Drop API
+
+## 📦 Dependencies
+
+### Core Dependencies
+- `pdf-lib` (^1.17.1) - PDF manipulation and assembly
+- `pdfjs-dist` (5.3.93) - PDF rendering and parsing
+- `react-dnd` (^16.0.1) - Drag and drop functionality
+- `react-dnd-html5-backend` (^16.0.1) - HTML5 backend for react-dnd
+
+### UI Dependencies (Peer Dependencies)
+- `react` (^18.2.0 || ^19.0.0)
+- `react-dom` (^18.2.0 || ^19.0.0)
+- `lucide-react` (^0.454.0) - Icon components
+- `@radix-ui/react-*` - Accessible UI primitives
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read the [contributing guidelines](https://github.com/signiphi/signiphi/blob/main/CONTRIBUTING.md) before submitting PRs.
 
-- Chrome/Edge: Latest 2 versions
-- Firefox: Latest 2 versions
-- Safari: Latest 2 versions
+## 📄 License
 
-## Dependencies
+See the [LICENSE](https://github.com/signiphi/signiphi/blob/main/LICENSE) file in the root of the repository.
 
-- `react` - ^18.2.0 || ^19.0.0
-- `react-dom` - ^18.2.0 || ^19.0.0
-- `pdf-lib` - ^1.17.1 (PDF manipulation)
-- `pdfjs-dist` - 5.3.93 (PDF rendering)
-- `react-dnd` - ^16.0.1 (Drag and drop)
-- `react-dnd-html5-backend` - ^16.0.1
-- Radix UI components (see peer dependencies)
-- `lucide-react` - ^0.454.0 (Icons)
+## 💬 Support
 
-## License
+- 📚 [Documentation](https://github.com/signiphi/signiphi)
+- 🐛 [Report Issues](https://github.com/signiphi/signiphi/issues)
+- 💡 [Feature Requests](https://github.com/signiphi/signiphi/issues)
 
-See the LICENSE file in the root of the repository.
+## 🔗 Related Packages
 
-## Contributing
+Part of the Signiphi ecosystem:
 
-Contributions are welcome! Please read the contributing guidelines in the repository.
+- [`@signiphi/pdf-signer`](https://www.npmjs.com/package/@signiphi/pdf-signer) - PDF signing and form filling
+- [`@signiphi/document-prepare`](https://www.npmjs.com/package/@signiphi/document-prepare) - Document preparation workflow
 
-## Support
+---
 
-For issues and questions, please visit the [GitHub repository](https://github.com/signiphi/signiphi).
+Made with ❤️ by the Signiphi team

package/dist/index.js

@@ -1624,7 +1624,7 @@ var PageAssembler = React7.forwardRef(
           const fileMap = /* @__PURE__ */ new Map();
           for (const file of state.files) {
             fileMap.set(file.id, file);
-            if (file.type === "pdf" && file.originalBytes) {
+            if (file.type === "pdf" && file.originalBytes && file.originalBytes.length > 0) {
               try {
                 const sourcePdf = await PDFDocument2.load(file.originalBytes);
                 loadedPdfs.set(file.id, sourcePdf);
@@ -1672,7 +1672,8 @@ var PageAssembler = React7.forwardRef(
             }
           }
           const pdfBytes = await combinedDoc.save();
-          const blob = new Blob([pdfBytes.buffer], { type: "application/pdf" });
+          const arrayBuffer = pdfBytes.buffer.slice(pdfBytes.byteOffset, pdfBytes.byteOffset + pdfBytes.byteLength);
+          const blob = new Blob([arrayBuffer], { type: "application/pdf" });
           return blob;
         } catch (error) {
           console.error("Error assembling PDF:", error);
@@ -1686,7 +1687,7 @@ var PageAssembler = React7.forwardRef(
       isBusy: () => isLoading,
       getState: () => state
     }), [state, summary, isLoading]);
-    return /* @__PURE__ */ jsxRuntime.jsx(TooltipProvider, { children: /* @__PURE__ */ jsxRuntime.jsx(reactDnd.DndProvider, { backend: reactDndHtml5Backend.HTML5Backend, children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: cn("space-y-6 pb-6", className), children: [
+    return /* @__PURE__ */ jsxRuntime.jsx(TooltipProvider, { children: /* @__PURE__ */ jsxRuntime.jsx(reactDnd.DndProvider, { backend: reactDndHtml5Backend.HTML5Backend, children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: cn("space-y-3", className), children: [
       /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center justify-between", children: [
         /* @__PURE__ */ jsxRuntime.jsxs("div", { children: [
           /* @__PURE__ */ jsxRuntime.jsx("h3", { className: "text-lg font-medium", children: "Page Assembly" }),
@@ -1777,9 +1778,9 @@ var PageAssembler = React7.forwardRef(
           ]
         }
       ) : !disableFileUpload && /* @__PURE__ */ jsxRuntime.jsx(
-        Card,
+        "div",
         {
-          className: "p-12 border-dashed border-2 border-gray-300 hover:border-gray-400 transition-colors cursor-pointer",
+          className: "p-12 rounded-lg bg-card text-card-foreground cursor-pointer transition-all border-2 border-dashed border-border hover:border-primary/60 hover:bg-primary/10",
           onClick: handleFileUpload,
           onDrop: handleDrop,
           onDragOver: handleDragOver,