@tawqi3i/pdf-viewer 0.1.0

package/index.d.ts

@@ -0,0 +1,350 @@
+import * as React from "react";
+
+// ---------------------------------------------------------------------------
+// Core types
+// ---------------------------------------------------------------------------
+
+export declare const TOOL: {
+  readonly TEXT: "text";
+  readonly STAMP: "stamp";
+  readonly SIGNATURE: "Esig";
+};
+export type AnnotationType = (typeof TOOL)[keyof typeof TOOL];
+
+export interface Stamp {
+  id: string;
+  label: string;
+  /** CSS color for label stamps */
+  color?: string;
+  /** CSS background color for label stamps */
+  bg?: string;
+  /** Data URL — when set, the stamp renders as an image */
+  imageUrl?: string;
+}
+
+export declare const DEFAULT_STAMPS: Stamp[];
+
+/** Coordinates are normalized (0–1) relative to the page they sit on. */
+export interface Annotation {
+  id: string;
+  type: AnnotationType;
+  pageIndex: number;
+  normX: number;
+  normY: number;
+  normW: number;
+  normH: number;
+  /** TOOL.TEXT only */
+  content?: string;
+  /** TOOL.STAMP only */
+  stamp?: Stamp;
+  /** TOOL.SIGNATURE only — PNG data URL */
+  imageData?: string;
+}
+
+export interface PendingSignature {
+  imageData: string;
+  w: number;
+  h: number;
+}
+
+/** GemBox toolbar-button visibility flags. */
+export interface ViewerVisibility {
+  open?: boolean;
+  download?: boolean;
+  print?: boolean;
+  [key: string]: boolean | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// PdfViewer — display-only wrapper around GemBox PDF Viewer
+// ---------------------------------------------------------------------------
+
+export interface PdfViewerProps {
+  /** URL string opened directly by the viewer. Ignored when fileBlob is set. */
+  fileUrl?: string | null;
+  /** Blob/File source; takes precedence over fileUrl. */
+  fileBlob?: Blob | null;
+  height?: string;
+  width?: string;
+  className?: string;
+  /** GemBox license key. Defaults to the free limited key. */
+  licenseKey?: string;
+  theme?: string | null;
+  /** Hides open/download/print unless overridden via visibility. */
+  readOnly?: boolean;
+  visibility?: ViewerVisibility | null;
+  onLoad?: () => void;
+  onError?: (err: unknown) => void;
+}
+
+export declare const PdfViewer: React.NamedExoticComponent<PdfViewerProps>;
+
+// ---------------------------------------------------------------------------
+// PdfAnnotator — turn-key viewer + annotation workspace
+// ---------------------------------------------------------------------------
+
+export interface PdfAnnotatorLabels {
+  completeButton?: string;
+  completeSending?: string;
+  completeSuccess?: string;
+  completeErrorPrefix?: string;
+  noFileOpen?: string;
+  loadingDocument?: string;
+  openFile?: string;
+  changeFile?: string;
+  renderError?: string;
+  saveUnavailable?: string;
+}
+
+export interface PdfAnnotatorProps {
+  /** Controlled document source. Internal uploads sync back via onFileChange. */
+  fileBlob?: File | Blob | null;
+  /** URL source used when no blob is set (display only — baking needs a blob). */
+  fileUrl?: string | null;
+  /** Show the built-in open/change/close buttons and drag-drop empty state. */
+  allowFileUpload?: boolean;
+  /** Branding slot rendered at the left of the header bar. */
+  header?: React.ReactNode;
+  /** Show a loading spinner while the host app fetches a remote document. */
+  loading?: boolean;
+  stamps?: Stamp[];
+  licenseKey?: string;
+  theme?: string | null;
+  visibility?: ViewerVisibility | null;
+  /** Hide all annotation UI; view only. */
+  readOnly?: boolean;
+  /** Marks the document as signed (changes the save button tooltip). */
+  isSigned?: boolean;
+  saveAlwaysEnabled?: boolean;
+  /** Tooltip shown on the filename in the header. */
+  documentTitle?: string | null;
+  /** Host-supplied error (e.g. remote fetch failure) shown in the empty state. */
+  errorMessage?: string | null;
+  labels?: PdfAnnotatorLabels;
+  /** Fired when the user opens or closes a file through the built-in UI. */
+  onFileChange?: (file: File | null) => void;
+  /** Save/download button behavior — entirely host-defined. */
+  onSave?: (file: File | Blob | null, annotations: Annotation[]) => void;
+  /**
+   * Complete button behavior (e.g. seal/send an envelope). Async errors are
+   * shown in the built-in snackbar; on success annotations are cleared.
+   * The button renders only when this prop is provided.
+   */
+  onComplete?: (
+    file: File | Blob,
+    annotations: Annotation[],
+  ) => void | Promise<void>;
+  onError?: (err: unknown) => void;
+  className?: string;
+}
+
+export declare function PdfAnnotator(props: PdfAnnotatorProps): React.JSX.Element;
+
+// ---------------------------------------------------------------------------
+// useAnnotations — annotation state machine for custom layouts
+// ---------------------------------------------------------------------------
+
+export interface UseAnnotationsOptions {
+  stamps?: Stamp[];
+}
+
+export interface UseAnnotationsResult {
+  annotations: Annotation[];
+  setAnnotations: React.Dispatch<React.SetStateAction<Annotation[]>>;
+  activeTool: AnnotationType | null;
+  selectedStamp: Stamp | null;
+  setSelectedStamp: (stamp: Stamp) => void;
+  showSignatureModal: boolean;
+  setShowSignatureModal: (open: boolean) => void;
+  pendingSignature: PendingSignature | null;
+  handleToolSelect: (tool: AnnotationType | null) => void;
+  handleSignatureConfirm: (imageData: string, w: number, h: number) => void;
+  handlePlace: (
+    pageIndex: number,
+    normX: number,
+    normY: number,
+    pageW: number,
+    pageH: number,
+  ) => void;
+  handleDelete: (id: string) => void;
+  handleMove: (id: string, pageIndex: number, normX: number, normY: number) => void;
+  handleResize: (id: string, normW: number, normH: number) => void;
+  handleTextChange: (id: string, content: string) => void;
+  handleUndo: () => void;
+  handleClearAll: () => void;
+  reset: () => void;
+  unsignedCount: number;
+  hint: string | null;
+}
+
+export declare function useAnnotations(
+  options?: UseAnnotationsOptions,
+): UseAnnotationsResult;
+
+// ---------------------------------------------------------------------------
+// Building blocks
+// ---------------------------------------------------------------------------
+
+export interface AnnotationLayerProps {
+  annotations: Annotation[];
+  activeTool: AnnotationType | null;
+  pendingSignature: PendingSignature | null;
+  onPlace: UseAnnotationsResult["handlePlace"];
+  onDelete: UseAnnotationsResult["handleDelete"];
+  onMove: UseAnnotationsResult["handleMove"];
+  onResize: UseAnnotationsResult["handleResize"];
+  onTextChange: UseAnnotationsResult["handleTextChange"];
+}
+export declare function AnnotationLayer(
+  props: AnnotationLayerProps,
+): React.JSX.Element;
+
+export declare function AnnotationItem(props: {
+  ann: Annotation;
+  pos: { x: number; y: number; w: number; h: number } | undefined;
+  onDelete: (id: string) => void;
+  onDragStart: (e: React.MouseEvent, id: string) => void;
+  onResizeStart: (e: React.MouseEvent, id: string) => void;
+  onTextChange: (id: string, content: string) => void;
+}): React.JSX.Element | null;
+
+export interface AnnotationToolbarProps {
+  activeTool: AnnotationType | null;
+  onToolSelect: (tool: AnnotationType | null) => void;
+  selectedStamp: Stamp | null;
+  onStampSelect: (stamp: Stamp) => void;
+  onUndo: () => void;
+  onClearAll: () => void;
+  onSave: () => void;
+  count: number;
+  saveAlwaysEnabled?: boolean;
+  isSigned?: boolean;
+  stamps?: Stamp[];
+}
+export declare function AnnotationToolbar(
+  props: AnnotationToolbarProps,
+): React.JSX.Element;
+
+export declare function ToolBtn(props: {
+  active: boolean;
+  onClick: () => void;
+  title: string;
+  disabled?: boolean;
+  danger?: boolean;
+  primary?: boolean;
+  children?: React.ReactNode;
+}): React.JSX.Element;
+
+export declare function SignatureModal(props: {
+  onConfirm: (imageData: string, w: number, h: number) => void;
+  onClose: () => void;
+}): React.JSX.Element;
+
+export declare function StampPicker(props: {
+  selected: Stamp | null;
+  onSelect: (stamp: Stamp) => void;
+  customStamps: Stamp[];
+  onImageUpload: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  stamps?: Stamp[];
+}): React.JSX.Element;
+
+export interface SnackbarMessage {
+  message: string;
+  severity?: "success" | "warning" | "error" | "info";
+  duration?: number;
+  title?: string;
+  key?: number | string;
+}
+export declare function Snackbar(props: {
+  snackbar: SnackbarMessage | null;
+  onDismiss: () => void;
+}): React.JSX.Element | null;
+export declare const SNACKBAR_VARIANTS: Record<
+  "success" | "warning" | "error" | "info",
+  {
+    accent: string;
+    outline: string;
+    icon: React.FC<{ className?: string }>;
+    title: string;
+  }
+>;
+
+export declare function EmptyState(props: {
+  isDragging: boolean;
+  error?: string | null;
+  onDrop: (e: React.DragEvent) => void;
+  onDragOver: (e: React.DragEvent) => void;
+  onDragLeave: () => void;
+  onBrowse: () => void;
+}): React.JSX.Element;
+
+// ---------------------------------------------------------------------------
+// DOM helpers (GemBox page contract: [data-page-number], 1-based)
+// ---------------------------------------------------------------------------
+
+export declare function findPageElementAt(
+  clientX: number,
+  clientY: number,
+): HTMLElement | null;
+export declare function findPageElementByIndex(
+  pageIndex: number,
+): HTMLElement | null;
+
+// ---------------------------------------------------------------------------
+// PDF utilities
+// ---------------------------------------------------------------------------
+
+/** Flattens annotations into the PDF (pdf-lib) and returns base64. */
+export declare function bakeAnnotationsToBase64(
+  pdfFile: Blob,
+  annotations: Annotation[],
+): Promise<string>;
+
+export interface AnnotationField {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+  pageNumber: number;
+  type: AnnotationType;
+  value: string | null;
+}
+/** Converts annotations to coordinate field objects (PDF points, top-left origin). */
+export declare function annotationsToFields(
+  pdfFile: Blob,
+  annotations: Annotation[],
+): Promise<AnnotationField[]>;
+
+export declare function blobToBase64(blob: Blob): Promise<string>;
+export declare function base64ToFile(
+  base64: string,
+  filename: string,
+  mimeType?: string,
+): File;
+export declare function dataUrlToBytes(dataUrl: string): Uint8Array;
+export declare function stripDataUrl(s: string | null): string | null;
+export declare function hexToRgb01(hex: string): unknown;
+export declare function makeUuid(): string;
+
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+
+type IconComponent = React.FC<{ className?: string }>;
+export declare const PdfIcon: IconComponent;
+export declare const UploadIcon: IconComponent;
+export declare const CloseIcon: IconComponent;
+export declare const DropIcon: IconComponent;
+export declare const ErrorIcon: IconComponent;
+export declare const TextIcon: IconComponent;
+export declare const StampIcon: IconComponent;
+export declare const SignatureIcon: IconComponent;
+export declare const TrashIcon: IconComponent;
+export declare const UndoIcon: IconComponent;
+export declare const ImageIcon: IconComponent;
+export declare const SaveIcon: IconComponent;
+export declare const WarningIcon: IconComponent;
+export declare const CheckIcon: IconComponent;
+export declare const InfoIcon: IconComponent;
+export declare const SendIcon: IconComponent;
+export declare const SpinnerIcon: IconComponent;

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@tawqi3i/pdf-viewer",
+  "version": "0.1.0",
+  "description": "React PDF viewer and annotation SDK built on GemBox PDF Viewer — view, annotate, stamp, and sign PDFs.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "pdf",
+    "viewer",
+    "annotations",
+    "signature",
+    "esign",
+    "gembox"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./vite": {
+      "types": "./vite-plugin.d.ts",
+      "import": "./vite-plugin.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "vite-plugin.js",
+    "vite-plugin.d.ts",
+    "index.d.ts",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "dev:lib": "vite build --watch",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint ."
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@gembox/pdfviewer": "^2026.6.101",
+    "pdf-lib": "^1.17.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.30.1",
+    "@tailwindcss/vite": "^4.2.4",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@vitejs/plugin-react": "^4.6.0",
+    "eslint": "^9.30.1",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "globals": "^16.3.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "tailwindcss": "^4.2.4",
+    "vite": "^7.0.4"
+  }
+}

package/vite-plugin.d.ts

@@ -0,0 +1,18 @@
+interface Tawqi3iPdfViewerPlugin {
+  name: string;
+  config(): {
+    define: Record<string, string>;
+    optimizeDeps: { exclude: string[] };
+  };
+  transform(
+    code: string,
+    id: string,
+  ): { code: string; map: null } | undefined;
+}
+
+/**
+ * Vite plugin that applies the GemBox PDF Viewer build workarounds
+ * (UMD pdfjs fix, Vue 3 compile-time flags, dep-optimizer exclusion)
+ * to the consuming app. Add it to the app's vite.config plugins.
+ */
+export default function tawqi3iPdfViewer(): Tawqi3iPdfViewerPlugin;

package/vite-plugin.js

@@ -0,0 +1,50 @@
+// Vite plugin for apps consuming @tawqi3i/pdf-viewer.
+//
+// GemBox PDF Viewer needs three build workarounds in the consuming app:
+//
+// 1. Its pdfjs + worker bundles are UMD IIFEs. In Rollup's production build,
+//    @rollup/plugin-commonjs can introduce an `exports` object into scope
+//    (for React's CJS modules). GemBox's 4-branch UMD checks:
+//      1. typeof exports&&"object"==typeof module  → module.exports=e()   (CJS)
+//      2. typeof define===...&&define.amd          → define(...)          (AMD)
+//      3. "object"==typeof exports                 → exports[key]=e()    (old CJS)
+//      4. (else)                                   → globalThis[key]=e() (browser)
+//    If branch 1 fires, window["pdfjs-dist/build/pdf"] is never set and
+//    GemBox throws "Pdf.js needs to be referenced". We neutralise every
+//    typeof-exports guard so the browser-global branch always runs.
+//
+// 2. GemBox is built on Vue 3, whose runtime expects compile-time constants
+//    that a React project never defines.
+//
+// 3. Vite's dep optimizer can corrupt GemBox's pre-built ESM (internal
+//    Vue/FontAwesome module references), so it must be excluded.
+export default function tawqi3iPdfViewer() {
+  return {
+    name: "tawqi3i-pdf-viewer",
+    config() {
+      return {
+        define: {
+          __VUE_OPTIONS_API__: JSON.stringify(true),
+          __VUE_PROD_DEVTOOLS__: JSON.stringify(false),
+          __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: JSON.stringify(false),
+        },
+        optimizeDeps: {
+          exclude: ["@gembox/pdfviewer"],
+        },
+      };
+    },
+    transform(code, id) {
+      if (!id.includes("@gembox/pdfviewer")) return;
+      const out = code
+        // 4-branch UMD first guard: typeof exports&&"object"==typeof module
+        .replaceAll("typeof exports&&", "(!1)&&")
+        // 4-branch UMD third guard (minified): "object"==typeof exports
+        .replaceAll('"object"==typeof exports', "!1")
+        // 3-branch UMD truthy guard: typeof exports?exports[key]=…
+        .replaceAll("typeof exports?", "(!1)?")
+        // pdfjsViewer UMD (spaced): typeof exports == "object"
+        .replaceAll('typeof exports == "object"', "!1");
+      return { code: out, map: null };
+    },
+  };
+}