@tawqi3i/pdf-viewer 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# @tawqi3i/pdf-viewer
+
+React PDF viewer and annotation SDK built on [GemBox PDF Viewer](https://www.gemboxsoftware.com/pdf-viewer). View PDFs, place text fields, stamps, and drawn signatures, then bake them into the document with pdf-lib or convert them to coordinate fields for a server-side signing API.
+
+## Installation
+
+```bash
+npm install @tawqi3i/pdf-viewer react react-dom
+```
+
+## Setup (Vite)
+
+Add the SDK's Vite plugin — it applies the GemBox build workarounds (pdfjs UMD fix, Vue 3 define flags, dep-optimizer exclusion) that the viewer needs:
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tawqi3iPdfViewer from '@tawqi3i/pdf-viewer/vite'
+
+export default defineConfig({
+  plugins: [react(), tawqi3iPdfViewer()],
+})
+```
+
+Import the stylesheet once (e.g. in your entry file):
+
+```js
+import '@tawqi3i/pdf-viewer/styles.css'
+```
+
+## Quick start — turn-key annotator
+
+`PdfAnnotator` is a complete viewer + annotation workspace. Your app injects behavior through callbacks; the component owns the UI mechanics (toolbar, drag/resize, signature capture, snackbars).
+
+```jsx
+import { PdfAnnotator, bakeAnnotationsToBase64 } from '@tawqi3i/pdf-viewer'
+
+function App() {
+  return (
+    <PdfAnnotator
+      className="h-screen"
+      header={<img src="/logo.svg" alt="My app" className="h-8" />}
+      onSave={(file, annotations) => {/* download / persist */}}
+      onComplete={async (file, annotations) => {
+        // e.g. flatten annotations and send to your signing API.
+        // Throw to show an error snackbar; resolve to show success.
+        const data = await bakeAnnotationsToBase64(file, annotations)
+        await fetch('/api/envelopes/seal', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name: file.name, data }),
+        })
+      }}
+    />
+  )
+}
+```
+
+Give the component a sized container (`h-screen`, a flex cell, etc.) — it fills its parent.
+
+Key props (see `index.d.ts` for the full list):
+
+| Prop | Purpose |
+| --- | --- |
+| `fileBlob` / `fileUrl` | Document source. Local upload/drag-drop is built in (`allowFileUpload`). |
+| `onFileChange(file)` | Fired when the user opens or closes a file. |
+| `onSave(file, annotations)` | Save/download button behavior — entirely yours. |
+| `onComplete(file, annotations)` | Async "Complete" action (seal/send). Button appears only when provided. |
+| `header` | Branding slot at the left of the header bar. |
+| `loading` / `errorMessage` | Remote-fetch spinner and error display driven by your app. |
+| `isSigned`, `saveAlwaysEnabled` | Save-button state flags. |
+| `stamps` | Custom stamp presets (defaults to APPROVED / REJECTED / REVIEWED / VOID). |
+| `labels` | Override built-in UI strings (e.g. `completeSuccess`). |
+| `readOnly` | Display-only mode; hides all annotation UI. |
+| `licenseKey` | GemBox license key (defaults to the free limited key). |
+
+## Display-only viewer
+
+```jsx
+import { PdfViewer } from '@tawqi3i/pdf-viewer'
+
+<PdfViewer
+  fileBlob={blob}                     // or fileUrl="https://…/doc.pdf"
+  height="100%"
+  visibility={{ open: false, download: false, print: false }}
+  onError={(err) => console.error(err)}
+/>
+```
+
+## Building blocks
+
+For custom layouts, compose the pieces yourself:
+
+```jsx
+import {
+  PdfViewer, AnnotationLayer, AnnotationToolbar, SignatureModal,
+  useAnnotations, bakeAnnotationsToBase64,
+} from '@tawqi3i/pdf-viewer'
+
+function CustomWorkspace({ blob }) {
+  const ann = useAnnotations()
+  return (
+    <div className="relative h-full">
+      <PdfViewer fileBlob={blob} height="100%" />
+      <AnnotationLayer
+        annotations={ann.annotations}
+        activeTool={ann.activeTool}
+        pendingSignature={ann.pendingSignature}
+        onPlace={ann.handlePlace}
+        onDelete={ann.handleDelete}
+        onMove={ann.handleMove}
+        onResize={ann.handleResize}
+        onTextChange={ann.handleTextChange}
+      />
+      <AnnotationToolbar
+        activeTool={ann.activeTool}
+        onToolSelect={ann.handleToolSelect}
+        selectedStamp={ann.selectedStamp}
+        onStampSelect={ann.setSelectedStamp}
+        onUndo={ann.handleUndo}
+        onClearAll={ann.handleClearAll}
+        onSave={() => {/* … */}}
+        count={ann.annotations.length}
+      />
+      {ann.showSignatureModal && (
+        <SignatureModal
+          onConfirm={ann.handleSignatureConfirm}
+          onClose={() => ann.setShowSignatureModal(false)}
+        />
+      )}
+    </div>
+  )
+}
+```
+
+The annotation overlay positions itself by querying GemBox's rendered pages via their `data-page-number` attributes — keep the overlay inside the same `position: relative` container as the viewer.
+
+## Utilities
+
+- `bakeAnnotationsToBase64(file, annotations)` — flatten annotations into the PDF (pdf-lib), returns base64.
+- `annotationsToFields(file, annotations)` — convert annotations to coordinate field objects (PDF points) for server-side placement.
+- `base64ToFile(base64, filename)` / `blobToBase64(blob)` — conversion helpers.
+
+## Theming
+
+The stylesheet ships its design tokens as CSS variables — override them to re-brand:
+
+```css
+:root {
+  --color-brand: #7c3aed;
+  --color-brand-dark: #5b21b6;
+}
+```
+
+The stylesheet contains no CSS reset/preflight, so it won't interfere with your app's base styles.
+
+## Development (this repo)
+
+- `npm run dev` — local dev harness at `index.html`
+- `npm run build` — build the library to `dist/`
+- `npm run dev:lib` — rebuild on change (for workspace consumers)