@signiphi/page-assembly 0.2.0-beta.1

package/README.md

@@ -0,0 +1,296 @@
+# @signiphi/page-assembly
+
+React component for PDF and image page manipulation - upload, reorder, delete, and combine pages into a single document.
+
+## Features
+
+- 📄 **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
+- 🖼️ **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
+
+## Installation
+
+```bash
+npm install @signiphi/page-assembly
+# or
+pnpm add @signiphi/page-assembly
+# or
+yarn add @signiphi/page-assembly
+```
+
+### Peer Dependencies
+
+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
+```
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { useRef } from 'react';
+import { PageAssembler, PageAssemblerHandle } from '@signiphi/page-assembly';
+import '@signiphi/page-assembly/styles';
+
+function App() {
+  const assemblerRef = useRef<PageAssemblerHandle>(null);
+
+  const handleAssemble = async () => {
+    if (!assemblerRef.current) return;
+    
+    try {
+      const pdfBlob = await assemblerRef.current.assemble();
+      
+      // Download the assembled PDF
+      const url = URL.createObjectURL(pdfBlob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = 'assembled-document.pdf';
+      a.click();
+      URL.revokeObjectURL(url);
+    } catch (error) {
+      console.error('Failed to assemble PDF:', error);
+    }
+  };
+
+  return (
+    <div className="signiphi-page-assembly">
+      <PageAssembler 
+        ref={assemblerRef}
+        onChange={(state) => {
+          console.log('State changed:', state);
+        }}
+        onValidityChange={(isValid) => {
+          console.log('Valid:', isValid);
+        }}
+      />
+      <button onClick={handleAssemble}>Assemble PDF</button>
+    </div>
+  );
+}
+```
+
+### With Initial PDF
+
+```tsx
+import { PageAssembler } from '@signiphi/page-assembly';
+import '@signiphi/page-assembly/styles';
+
+function App() {
+  const [pdfBytes, setPdfBytes] = useState<Uint8Array | null>(null);
+
+  // Load initial PDF
+  useEffect(() => {
+    fetch('/document.pdf')
+      .then(res => res.arrayBuffer())
+      .then(buffer => setPdfBytes(new Uint8Array(buffer)));
+  }, []);
+
+  return (
+    <div className="signiphi-page-assembly">
+      <PageAssembler 
+        initialPdf={pdfBytes || undefined}
+        limits={{
+          maxFileSizeMB: 20,
+          maxTotalPages: 100
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### With State Persistence
+
+```tsx
+import { PageAssembler, PageAssemblerState } from '@signiphi/page-assembly';
+import '@signiphi/page-assembly/styles';
+
+function App() {
+  const [savedState, setSavedState] = useState<PageAssemblerState | null>(null);
+  const assemblerRef = useRef<PageAssemblerHandle>(null);
+
+  const handleSave = () => {
+    if (!assemblerRef.current) return;
+    const state = assemblerRef.current.getState();
+    localStorage.setItem('pageAssemblerState', JSON.stringify(state));
+  };
+
+  const handleRestore = () => {
+    const stateJson = localStorage.getItem('pageAssemblerState');
+    if (stateJson) {
+      setSavedState(JSON.parse(stateJson));
+    }
+  };
+
+  return (
+    <div className="signiphi-page-assembly">
+      <PageAssembler 
+        ref={assemblerRef}
+        initialState={savedState || undefined}
+        onChange={(state) => {
+          // Auto-save state changes
+          localStorage.setItem('pageAssemblerState', JSON.stringify(state));
+        }}
+      />
+      <button onClick={handleSave}>Save State</button>
+      <button onClick={handleRestore}>Restore State</button>
+    </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 |
+
+### PageAssemblerHandle Methods
+
+The `ref` provides access to imperative methods:
+
+| 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 |
+
+### Types
+
+```typescript
+interface PageInfo {
+  id: string;
+  srcIndex: number;
+  thumbUrl: string;
+  width?: number;
+  height?: number;
+  mime: string;
+  originalFileId?: string;
+}
+
+interface FileInfo {
+  id: string;
+  name: string;
+  type: "pdf" | "image";
+  originalFile: File;
+  originalBytes: Uint8Array;
+  pages: PageInfo[];
+}
+
+interface PageAssemblerState {
+  files: FileInfo[];
+  selection: string[];
+  lastSelectedPageId?: string;
+}
+
+interface AssembleOptions {
+  imageSizing?: "auto-letter" | "original-size";
+}
+```
+
+## Styling
+
+The package includes scoped Tailwind CSS styles. Import the styles in your application:
+
+```tsx
+import '@signiphi/page-assembly/styles';
+```
+
+All styles are prefixed with `.signiphi-page-assembly` to prevent conflicts with your application's styles.
+
+### Custom Styling
+
+You can override the default styles by wrapping the component in a container with custom CSS:
+
+```tsx
+<div className="my-custom-page-assembly signiphi-page-assembly">
+  <PageAssembler />
+</div>
+```
+
+## Advanced Usage
+
+### Working with Assembled PDF
+
+```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
+  });
+};
+```
+
+### Getting Summary Information
+
+```tsx
+const assemblerRef = useRef<PageAssemblerHandle>(null);
+
+const summary = assemblerRef.current?.getSummary();
+console.log(`Total files: ${summary.totalFiles}`);
+console.log(`Total pages: ${summary.totalPages}`);
+```
+
+### Checking if Busy
+
+```tsx
+const isBusy = assemblerRef.current?.isBusy();
+if (isBusy) {
+  console.log('Page assembler is currently processing...');
+}
+```
+
+## Browser Support
+
+- Chrome/Edge: Latest 2 versions
+- Firefox: Latest 2 versions
+- Safari: Latest 2 versions
+
+## Dependencies
+
+- `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)
+
+## License
+
+See the LICENSE file in the root of the repository.
+
+## Contributing
+
+Contributions are welcome! Please read the contributing guidelines in the repository.
+
+## Support
+
+For issues and questions, please visit the [GitHub repository](https://github.com/signiphi/signiphi).

package/dist/index.d.mts

@@ -0,0 +1,178 @@
+import * as React from 'react';
+import React__default from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+
+/**
+ * Represents a single page in the page assembly system
+ */
+type PageInfo = {
+    /** Unique identifier for the page */
+    id: string;
+    /** Index of this page in the original source file */
+    srcIndex: number;
+    /** Data URL for the page thumbnail */
+    thumbUrl: string;
+    /** Page width in points (for PDFs) or pixels (for images) */
+    width?: number;
+    /** Page height in points (for PDFs) or pixels (for images) */
+    height?: number;
+    /** MIME type of the page */
+    mime: string;
+    /** ID of the original file this page came from (for tracking across moves) */
+    originalFileId?: string;
+};
+/**
+ * Represents a file (PDF or image) in the page assembly system
+ */
+type FileInfo = {
+    /** Unique identifier for the file */
+    id: string;
+    /** Original file name */
+    name: string;
+    /** File type */
+    type: "pdf" | "image";
+    /** Original File object */
+    originalFile: File;
+    /** Raw bytes of the file */
+    originalBytes: Uint8Array;
+    /** Pages extracted from this file */
+    pages: PageInfo[];
+};
+/**
+ * State of the page assembler
+ */
+type PageAssemblerState = {
+    /** Files currently in the assembler */
+    files: FileInfo[];
+    /** IDs of currently selected pages */
+    selection: string[];
+    /** ID of the last selected page (for range selection) */
+    lastSelectedPageId?: string;
+};
+/**
+ * Options for assembling the final PDF
+ */
+type AssembleOptions = {
+    /** How to handle image pages: "auto-letter" (default) or "original-size" */
+    imageSizing?: "auto-letter" | "original-size";
+};
+/**
+ * Imperative handle exposed by PageAssembler component
+ */
+type PageAssemblerHandle = {
+    /** Assemble the current canvas into a single PDF Blob */
+    assemble: (opts?: AssembleOptions) => Promise<Blob>;
+    /** Get derived info for the parent (total files and pages) */
+    getSummary: () => {
+        totalFiles: number;
+        totalPages: number;
+    };
+    /** True while loading/assembling */
+    isBusy: () => boolean;
+    /** Get current state */
+    getState: () => PageAssemblerState;
+};
+/**
+ * Props for the PageAssembler component
+ */
+type PageAssemblerProps = {
+    /** Optional initial PDF to pre-load */
+    initialPdf?: File | Blob | ArrayBuffer | Uint8Array;
+    /** Optional initial state to restore previous session */
+    initialState?: PageAssemblerState;
+    /** Notified on any structural change (files/pages added/removed/reordered) */
+    onChange?: (state: PageAssemblerState) => void;
+    /** Called when internal validity changes (e.g., 0 pages) */
+    onValidityChange?: (isValid: boolean) => void;
+    /** Optional limits */
+    limits?: {
+        maxFileSizeMB?: number;
+        maxTotalPages?: number;
+    };
+    /** Disable file upload (e.g., for template-only flows) */
+    disableFileUpload?: boolean;
+    /** Optional className passthrough */
+    className?: string;
+};
+/**
+ * Represents a page image extracted from a PDF
+ */
+type PageImage = {
+    /** Data URL for the image */
+    imageUrl: string;
+    /** Page width in points */
+    width: number;
+    /** Page height in points */
+    height: number;
+};
+
+declare const PageAssembler: React__default.ForwardRefExoticComponent<PageAssemblerProps & React__default.RefAttributes<PageAssemblerHandle>>;
+
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Converts a PDF document to an array of rendered page images
+ *
+ * @param pdfBytes - The PDF document as a Uint8Array
+ * @param options - Optional configuration
+ * @param options.hideFormFields - If true, hides existing form fields during rendering
+ * @returns Promise resolving to array of PageImage objects with rendered images
+ * @throws {Error} If PDF is invalid or rendering fails
+ *
+ * @example
+ * ```ts
+ * const pages = await pdfToImages(pdfBytes, { hideFormFields: true });
+ * console.log(`Rendered ${pages.length} pages`);
+ * ```
+ */
+declare function pdfToImages(pdfBytes: Uint8Array, options?: {
+    hideFormFields?: boolean;
+}): Promise<PageImage[]>;
+/**
+ * Converts an image file to a PDF document with a single page
+ *
+ * @param imageFile - The image file to convert (supports common image formats)
+ * @returns Promise resolving to PDF bytes as Uint8Array
+ * @throws {Error} If image fails to load or convert
+ *
+ * @example
+ * ```ts
+ * const pdfBytes = await imageToPdf(imageFile);
+ * ```
+ */
+declare function imageToPdf(imageFile: File): Promise<Uint8Array>;
+/**
+ * Create a blob URL from PDF bytes for preview
+ *
+ * @param pdfBytes - The PDF document as Uint8Array
+ * @returns Blob URL string
+ *
+ * @example
+ * ```ts
+ * const url = createPdfBlobUrl(pdfBytes);
+ * // Remember to revoke: URL.revokeObjectURL(url);
+ * ```
+ */
+declare function createPdfBlobUrl(pdfBytes: Uint8Array): string;
+/**
+ * Triggers a browser download of a PDF file
+ *
+ * @param pdfBytes - The PDF document as Uint8Array
+ * @param filename - The filename for the downloaded file (e.g., 'document.pdf')
+ *
+ * @example
+ * ```ts
+ * downloadPdf(pdfBytes, 'assembled-document.pdf');
+ * ```
+ */
+declare function downloadPdf(pdfBytes: Uint8Array, filename: string): void;
+
+export { type AssembleOptions, Button, type FileInfo, PageAssembler, type PageAssemblerHandle, type PageAssemblerProps, type PageAssemblerState, type PageImage, type PageInfo, createPdfBlobUrl, PageAssembler as default, downloadPdf, imageToPdf, pdfToImages };

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import * as React from 'react';
+import React__default from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+
+/**
+ * Represents a single page in the page assembly system
+ */
+type PageInfo = {
+    /** Unique identifier for the page */
+    id: string;
+    /** Index of this page in the original source file */
+    srcIndex: number;
+    /** Data URL for the page thumbnail */
+    thumbUrl: string;
+    /** Page width in points (for PDFs) or pixels (for images) */
+    width?: number;
+    /** Page height in points (for PDFs) or pixels (for images) */
+    height?: number;
+    /** MIME type of the page */
+    mime: string;
+    /** ID of the original file this page came from (for tracking across moves) */
+    originalFileId?: string;
+};
+/**
+ * Represents a file (PDF or image) in the page assembly system
+ */
+type FileInfo = {
+    /** Unique identifier for the file */
+    id: string;
+    /** Original file name */
+    name: string;
+    /** File type */
+    type: "pdf" | "image";
+    /** Original File object */
+    originalFile: File;
+    /** Raw bytes of the file */
+    originalBytes: Uint8Array;
+    /** Pages extracted from this file */
+    pages: PageInfo[];
+};
+/**
+ * State of the page assembler
+ */
+type PageAssemblerState = {
+    /** Files currently in the assembler */
+    files: FileInfo[];
+    /** IDs of currently selected pages */
+    selection: string[];
+    /** ID of the last selected page (for range selection) */
+    lastSelectedPageId?: string;
+};
+/**
+ * Options for assembling the final PDF
+ */
+type AssembleOptions = {
+    /** How to handle image pages: "auto-letter" (default) or "original-size" */
+    imageSizing?: "auto-letter" | "original-size";
+};
+/**
+ * Imperative handle exposed by PageAssembler component
+ */
+type PageAssemblerHandle = {
+    /** Assemble the current canvas into a single PDF Blob */
+    assemble: (opts?: AssembleOptions) => Promise<Blob>;
+    /** Get derived info for the parent (total files and pages) */
+    getSummary: () => {
+        totalFiles: number;
+        totalPages: number;
+    };
+    /** True while loading/assembling */
+    isBusy: () => boolean;
+    /** Get current state */
+    getState: () => PageAssemblerState;
+};
+/**
+ * Props for the PageAssembler component
+ */
+type PageAssemblerProps = {
+    /** Optional initial PDF to pre-load */
+    initialPdf?: File | Blob | ArrayBuffer | Uint8Array;
+    /** Optional initial state to restore previous session */
+    initialState?: PageAssemblerState;
+    /** Notified on any structural change (files/pages added/removed/reordered) */
+    onChange?: (state: PageAssemblerState) => void;
+    /** Called when internal validity changes (e.g., 0 pages) */
+    onValidityChange?: (isValid: boolean) => void;
+    /** Optional limits */
+    limits?: {
+        maxFileSizeMB?: number;
+        maxTotalPages?: number;
+    };
+    /** Disable file upload (e.g., for template-only flows) */
+    disableFileUpload?: boolean;
+    /** Optional className passthrough */
+    className?: string;
+};
+/**
+ * Represents a page image extracted from a PDF
+ */
+type PageImage = {
+    /** Data URL for the image */
+    imageUrl: string;
+    /** Page width in points */
+    width: number;
+    /** Page height in points */
+    height: number;
+};
+
+declare const PageAssembler: React__default.ForwardRefExoticComponent<PageAssemblerProps & React__default.RefAttributes<PageAssemblerHandle>>;
+
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Converts a PDF document to an array of rendered page images
+ *
+ * @param pdfBytes - The PDF document as a Uint8Array
+ * @param options - Optional configuration
+ * @param options.hideFormFields - If true, hides existing form fields during rendering
+ * @returns Promise resolving to array of PageImage objects with rendered images
+ * @throws {Error} If PDF is invalid or rendering fails
+ *
+ * @example
+ * ```ts
+ * const pages = await pdfToImages(pdfBytes, { hideFormFields: true });
+ * console.log(`Rendered ${pages.length} pages`);
+ * ```
+ */
+declare function pdfToImages(pdfBytes: Uint8Array, options?: {
+    hideFormFields?: boolean;
+}): Promise<PageImage[]>;
+/**
+ * Converts an image file to a PDF document with a single page
+ *
+ * @param imageFile - The image file to convert (supports common image formats)
+ * @returns Promise resolving to PDF bytes as Uint8Array
+ * @throws {Error} If image fails to load or convert
+ *
+ * @example
+ * ```ts
+ * const pdfBytes = await imageToPdf(imageFile);
+ * ```
+ */
+declare function imageToPdf(imageFile: File): Promise<Uint8Array>;
+/**
+ * Create a blob URL from PDF bytes for preview
+ *
+ * @param pdfBytes - The PDF document as Uint8Array
+ * @returns Blob URL string
+ *
+ * @example
+ * ```ts
+ * const url = createPdfBlobUrl(pdfBytes);
+ * // Remember to revoke: URL.revokeObjectURL(url);
+ * ```
+ */
+declare function createPdfBlobUrl(pdfBytes: Uint8Array): string;
+/**
+ * Triggers a browser download of a PDF file
+ *
+ * @param pdfBytes - The PDF document as Uint8Array
+ * @param filename - The filename for the downloaded file (e.g., 'document.pdf')
+ *
+ * @example
+ * ```ts
+ * downloadPdf(pdfBytes, 'assembled-document.pdf');
+ * ```
+ */
+declare function downloadPdf(pdfBytes: Uint8Array, filename: string): void;
+
+export { type AssembleOptions, Button, type FileInfo, PageAssembler, type PageAssemblerHandle, type PageAssemblerProps, type PageAssemblerState, type PageImage, type PageInfo, createPdfBlobUrl, PageAssembler as default, downloadPdf, imageToPdf, pdfToImages };