@superdoc-dev/esign 1.0.0-next.2 → 1.0.0-next.3

package/README.md

@@ -1,6 +1,6 @@
 # @superdoc-dev/esign
 
-A React eSignature component for SuperDoc that handles document acceptance workflows.
+React eSignature component for document signing workflows with SuperDoc.
 
 ## Installation
 
@@ -11,164 +11,427 @@ npm install @superdoc-dev/esign superdoc
 ## Quick Start
 
 ```jsx
-import React, { useRef, useState } from 'react';
 import SuperDocESign from '@superdoc-dev/esign';
 import 'superdoc/dist/style.css';
 
 function App() {
-  const esignRef = useRef();
-  const [status, setStatus] = useState({});
-
-  const handleAccept = async () => {
-    const auditData = await esignRef.current?.accept();
-    if (auditData) {
-      // Send to your API
-      await api.saveSignature(auditData);
-    }
-  };
-
   return (
-    <div>
-      {/* Document viewer */}
-      <SuperDocESign
-        ref={esignRef}
-        document="https://example.com/agreement.docx"
-        requirements={{
-          scroll: true,
-          signature: true,
-          consents: ['terms', 'privacy']
-        }}
-        onChange={setStatus}
-        onAccept={handleAccept}
-      />
-
-      {/* Your signature UI */}
-      <input
-        type="text"
-        data-esign-signature
-        placeholder="Type your full name"
-        disabled={!status.scroll}
-      />
-
-      {/* Your consent UI */}
-      <label>
-        <input
-          type="checkbox"
-          data-esign-consent="terms"
-          disabled={!status.scroll || !status.signature}
-        />
-        I accept the terms
-      </label>
-
-      {/* Accept button */}
-      <button
-        onClick={() => esignRef.current?.accept()}
-        disabled={!status.isValid}
-      >
-        Accept Agreement
-      </button>
-    </div>
+    <SuperDocESign
+      eventId="unique-session-id"
+      
+      document={{
+        source: "contract.pdf",
+        mode: "full",
+        displayOptions: {
+          scrollRequired: true
+        }
+      }}
+      
+      fields={{
+        document: [
+          { alias: 'company', value: 'Acme Corp' }
+        ],
+        signer: [
+          {
+            id: 'signature',
+            type: 'signature',
+            validation: { required: true },
+            label: 'Your Signature'
+          }
+        ]
+      }}
+      
+      onSubmit={async (data) => {
+        await api.saveSignature(data);
+      }}
+    />
   );
 }
 ```
 
-## Props
+## API Reference
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `eventId` | string | ✓ | Unique identifier for signing session |
+| `document` | object | ✓ | Document configuration |
+| `fields` | object | | Field definitions |
+| `download` | object | | Download button config |
+| `submit` | object | | Submit button config |
+| `onSubmit` | function | ✓ | Submit handler |
+| `onDownload` | function | | Download handler |
+| `onStateChange` | function | | State change handler |
+| `onFieldChange` | function | | Field change handler |
+| `isDisabled` | boolean | | Disable all interactions |
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `document` | `string \| File \| Blob` | Document to display |
-| `requirements` | `Object` | What users must complete |
-| `fields` | `Array` | Initial field values |
-| `signatureSelector` | `string` | CSS selector for signature element (default: `[data-esign-signature]`) |
-| `consentSelector` | `string` | CSS selector for consent checkboxes (default: `[data-esign-consent]`) |
-| `onChange` | `(status) => void` | Called when requirements change |
-| `onAccept` | `(data) => void` | Called when document is accepted |
-| `onReady` | `() => void` | Called when component is ready |
-| `onFieldsDiscovered` | `(fields) => void` | Called when document fields are found |
+### Document Configuration
 
-## Methods (via ref)
+```jsx
+document={{
+  source: File | Blob | string,  // Required
+  mode: 'full' | 'download_only' | 'preview',
+  displayOptions: {
+    scrollRequired: boolean,
+    watermark: boolean
+  }
+}}
+```
 
-- `accept()` - Process acceptance and return audit data
-- `reset()` - Clear all state
-- `updateFields(fields)` - Update document field values
-- `getStatus()` - Get current requirement status
-- `getFields()` - Get all document fields
+### Field Reference System
 
-## Requirements
+Fields can be referenced using either `id` or `alias`:
 
-Configure what users must complete before accepting:
+- **`id`**: System identifier (e.g., "field_123")
+- **`alias`**: Human-readable name (e.g., "customer_name")
+
+This allows the same value to appear multiple places in a document:
 
 ```jsx
-<SuperDocESign
-  requirements={{
-    scroll: true,        // Must scroll to bottom
-    signature: true,     // Must provide signature
-    consents: ['terms', 'privacy']  // Must check these boxes
-  }}
-/>
+// Document template might have:
+// "Dear {{customer_name}},"
+// "Agreement between {{company}} and {{customer_name}}"
+// "Signed by: {{customer_name}}"
+
+fields={{
+  document: [
+    { 
+      alias: 'customer_name',  // Used in document {{customer_name}}
+      value: 'John Doe' 
+    },
+    { 
+      alias: 'company', 
+      value: 'Acme Corp' 
+    },
+    { 
+      id: 'date_field',
+      alias: 'sign_date',  // Can have both id and alias
+      value: '2024-01-15' 
+    }
+  ],
+  
+  signer: [
+    {
+      id: 'sig_001',
+      alias: 'signature',  // Document shows {{signature}} 
+      type: 'signature',
+      validation: { required: true }
+    },
+    {
+      id: 'consent_terms',
+      alias: 'terms_accepted',  // Can reference as {{terms_accepted}}
+      type: 'consent',
+      label: 'I accept the terms'
+    }
+  ]
+}}
 ```
 
-## Signature Input
+**How it works:**
+1. Document fields are injected on load using their id/alias
+2. Signer fields are collected and can replace placeholders using their alias
+3. The same alias can appear multiple times in the document
+4. All instances get the same value
 
-Use the `data-esign-signature` attribute on any input or canvas:
+### Field Configuration
 
 ```jsx
-{/* Text input */}
-<input type="text" data-esign-signature placeholder="Type your name" />
+fields={{
+  // Values to inject into document
+  document: [
+    { 
+      id: 'field_id',      // Optional
+      alias: 'field_name', // Optional (at least one of id or alias required)
+      value: 'any value' 
+    }
+  ],
+  
+  // Fields for signer to complete
+  signer: [
+    {
+      id: 'unique_id',     // Required for signer fields
+      alias: 'field_ref',  // Optional alias for document references
+      type: 'signature' | 'consent' | 'checkbox' | 'text',
+      validation: {
+        required: boolean,
+        minLength: number,
+        maxLength: number
+      },
+      label: 'Field Label',
+      component: CustomComponent // Optional - consistent with download/submit!
+    }
+  ]
+}}
+```
 
-{/* Canvas signature pad */}
-<canvas data-esign-signature width="400" height="200" />
+### UI Customization
 
-{/* Custom component */}
-<SignaturePad data-esign-signature data-signed={isSigned} />
+Simple customization:
+```jsx
+download={{
+  fileName: "contract.pdf",
+  label: "Download Contract",
+  variant: "secondary"
+}}
+
+submit={{
+  label: "Sign Document",
+  loadingLabel: "Processing...",
+  variant: "primary"
+}}
 ```
 
-## Consent Checkboxes
+Full custom components:
+```jsx
+download={{
+  component: ({ onClick, fileName, isDisabled }) => (
+    <CustomButton onClick={onClick} disabled={isDisabled}>
+      Download {fileName}
+    </CustomButton>
+  )
+}}
+
+submit={{
+  component: ({ onClick, isValid, isDisabled, isSubmitting }) => (
+    <CustomButton 
+      onClick={onClick} 
+      disabled={!isValid || isDisabled}
+    >
+      {isSubmitting ? 'Processing...' : 'Sign & Submit'}
+    </CustomButton>
+  )
+}}
+```
 
-Use the `data-esign-consent` attribute with a unique name:
+### Custom Field Components
 
 ```jsx
-<label>
-  <input type="checkbox" data-esign-consent="terms" />
-  I accept the terms
-</label>
-
-<label>
-  <input type="checkbox" data-esign-consent="privacy" />
-  I acknowledge the privacy policy
-</label>
+// Custom signature pad component
+const CustomSignaturePad = ({ value, onChange, isDisabled, label }) => (
+  <div className="custom-signature">
+    <label>{label}</label>
+    <canvas 
+      // ... canvas signature implementation
+      onMouseUp={(e) => onChange(canvasDataURL)}
+      style={{ border: '1px solid #000', cursor: 'crosshair' }}
+    />
+  </div>
+);
+
+// Use it in fields
+fields={{
+  signer: [
+    {
+      id: 'signature',
+      type: 'signature',
+      validation: { required: true },
+      component: CustomSignaturePad  // Consistent with download/submit!
+    }
+  ]
+}}
 ```
 
-## Field Population
+## Examples
 
-Replace placeholders in your document with dynamic data:
+### Basic Agreement
 
 ```jsx
 <SuperDocESign
-  fields={[
-    { alias: 'userName', value: 'John Doe' },
-    { alias: 'date', value: new Date().toLocaleDateString() },
-    { alias: 'company', value: 'Acme Inc.' }
-  ]}
+  eventId="session-123"
+  document={{ source: "terms.pdf" }}
+  fields={{
+    signer: [
+      {
+        id: 'accept',
+        type: 'consent',
+        validation: { required: true },
+        label: 'I accept the terms'
+      }
+    ]
+  }}
+  onSubmit={handleSubmit}
 />
 ```
 
-## Audit Data
+### Employment Offer with Repeated Fields
 
-When a user accepts, you receive comprehensive audit data:
+```jsx
+// Example: Employment offer with repeated fields
+<SuperDocESign
+  eventId="offer-123"
+  
+  document={{
+    source: offerLetter,  // Contains {{employee_name}}, {{salary}}, etc.
+    mode: "full",
+    displayOptions: {
+      scrollRequired: true
+    }
+  }}
+  
+  fields={{
+    document: [
+      { 
+        alias: 'employee_name',  // Appears 5 times in document
+        value: 'Jane Smith' 
+      },
+      { 
+        alias: 'position',       // Appears 3 times
+        value: 'Senior Engineer' 
+      },
+      { 
+        alias: 'salary',         // Appears 2 times
+        value: '$120,000' 
+      },
+      {
+        alias: 'start_date',
+        value: 'February 1, 2024'
+      }
+    ],
+    
+    signer: [
+      {
+        id: 'employee_signature',
+        alias: 'employee_sig',   // {{employee_sig}} in document
+        type: 'signature',
+        validation: { required: true },
+        label: 'Your Signature'
+      },
+      {
+        id: 'accept_offer',
+        alias: 'offer_accepted',
+        type: 'consent',
+        validation: { required: true },
+        label: 'I accept this offer'
+      }
+    ]
+  }}
+  
+  submit={{
+    label: 'Accept Offer'
+  }}
+  
+  onSubmit={handleAcceptOffer}
+/>
+```
 
-```typescript
-{
-  timestamp: "2024-01-15T10:30:00.000Z",
-  duration: 45,  // seconds spent on document
-  fields: [
-    { id: "field1", alias: "userName", value: "John Doe" }
-  ],
-  scrolled: true,
-  signed: true,
-  consents: ["terms", "privacy"],
-  signatureImage: "data:image/png;base64,..."  // if canvas
-}
+### Full Contract with All Features
+
+```jsx
+<SuperDocESign
+  eventId="contract-456"
+  
+  document={{
+    source: serviceAgreement,
+    mode: "full",
+    displayOptions: {
+      scrollRequired: true,
+      watermark: true
+    }
+  }}
+  
+  fields={{
+    document: [
+      { alias: 'client_name', value: 'John Doe' },
+      { alias: 'company', value: 'Acme Corp' },
+      { alias: 'service_type', value: 'Premium Support' },
+      { alias: 'contract_date', value: new Date().toLocaleDateString() }
+    ],
+    signer: [
+      {
+        id: 'client_signature',
+        alias: 'signature',
+        type: 'signature',
+        validation: { required: true },
+        label: 'Your Signature'
+      },
+      {
+        id: 'consent_terms',
+        type: 'consent',
+        validation: { required: true },
+        label: 'I agree to the terms and conditions'
+      },
+      {
+        id: 'consent_privacy',
+        type: 'consent',
+        validation: { required: true },
+        label: 'I acknowledge the privacy policy'
+      },
+      {
+        id: 'email_updates',
+        type: 'checkbox',
+        validation: { required: false },
+        label: 'Send me email updates'
+      }
+    ]
+  }}
+  
+  download={{
+    fileName: 'service_agreement_signed.pdf',
+    label: 'Download Agreement',
+    variant: 'secondary'
+  }}
+  
+  submit={{
+    label: 'Sign Agreement',
+    loadingLabel: 'Processing...',
+    invalidLabel: 'Please complete all required fields',
+    variant: 'success'
+  }}
+  
+  onSubmit={async (data) => {
+    await api.saveSignedContract(data);
+    console.log('Signed by:', data.signerFields);
+  }}
+  
+  onDownload={(blob, fileName) => {
+    console.log('Downloaded:', fileName);
+  }}
+  
+  onStateChange={(state) => {
+    console.log('Valid:', state.isValid);
+  }}
+  
+  isDisabled={false}
+/>
+```
+
+## Progressive Customization
+
+The component supports three levels of customization:
+
+```jsx
+// Level 1: Use all defaults
+<SuperDocESign 
+  eventId="session-1"
+  document={{ source: "doc.pdf" }} 
+  onSubmit={handleSubmit} 
+/>
+
+// Level 2: Simple customization
+<SuperDocESign
+  eventId="session-2"
+  document={{ source: "doc.pdf" }}
+  submit={{ label: "I Agree", variant: "success" }}
+  download={{ label: "Get Copy" }}
+  onSubmit={handleSubmit}
+/>
+
+// Level 3: Full custom components
+<SuperDocESign
+  eventId="session-3"
+  document={{ source: "doc.pdf" }}
+  submit={{ component: CustomSubmitButton }}
+  download={{ component: CustomDownloadButton }}
+  fields={{
+    signer: [{
+      id: 'sig',
+      type: 'signature',
+      component: CustomSignaturePad
+    }]
+  }}
+  onSubmit={handleSubmit}
+/>
 ```
 
 ## TypeScript
@@ -176,30 +439,17 @@ When a user accepts, you receive comprehensive audit data:
 Full TypeScript support with exported types:
 
 ```typescript
-import SuperDocESign, { 
-  SuperDocESignHandle, 
-  Status, 
-  AuditData, 
-  FieldUpdate 
+import SuperDocESign from '@superdoc-dev/esign';
+import type { 
+  SuperDocESignProps,
+  SubmitData, 
+  SigningState,
+  DocumentField,
+  SignerField,
+  FieldComponentProps
 } from '@superdoc-dev/esign';
-
-const esignRef = useRef<SuperDocESignHandle>(null);
-const [status, setStatus] = useState<Status>({
-  scroll: false,
-  signature: false,
-  consents: [],
-  isValid: false
-});
-
-const handleAccept = async (data: AuditData) => {
-  // Process acceptance
-};
 ```
 
-## Examples
-
-See the [examples](./examples) directory for complete implementations.
-
 ## License
 
 MIT

package/dist/defaults/ConsentCheckbox.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { FieldComponentProps } from '../types';
+export declare const ConsentCheckbox: React.FC<FieldComponentProps>;
+//# sourceMappingURL=ConsentCheckbox.d.ts.map

package/dist/defaults/ConsentCheckbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsentCheckbox.d.ts","sourceRoot":"","sources":["../../src/defaults/ConsentCheckbox.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAoBzD,CAAC"}

package/dist/defaults/DownloadButton.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { DownloadButtonProps, DownloadConfig } from '../types';
+export declare const createDownloadButton: (config?: DownloadConfig) => React.FC<DownloadButtonProps>;
+//# sourceMappingURL=DownloadButton.d.ts.map

package/dist/defaults/DownloadButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DownloadButton.d.ts","sourceRoot":"","sources":["../../src/defaults/DownloadButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEpE,eAAO,MAAM,oBAAoB,GAAI,SAAS,cAAc,kCA+B3D,CAAC"}

package/dist/defaults/SignatureInput.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { FieldComponentProps } from '../types';
+export declare const SignatureInput: React.FC<FieldComponentProps>;
+//# sourceMappingURL=SignatureInput.d.ts.map

package/dist/defaults/SignatureInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SignatureInput.d.ts","sourceRoot":"","sources":["../../src/defaults/SignatureInput.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmB,MAAM,OAAO,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAiDxD,CAAC"}

package/dist/defaults/SubmitButton.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { SubmitButtonProps, SubmitConfig } from '../types';
+export declare const createSubmitButton: (config?: SubmitConfig) => React.FC<SubmitButtonProps>;
+//# sourceMappingURL=SubmitButton.d.ts.map

package/dist/defaults/SubmitButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubmitButton.d.ts","sourceRoot":"","sources":["../../src/defaults/SubmitButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEhE,eAAO,MAAM,kBAAkB,GAAI,SAAS,YAAY,gCAkCvD,CAAC"}

package/dist/defaults/index.d.ts

@@ -0,0 +1,5 @@
+export { SignatureInput } from './SignatureInput';
+export { ConsentCheckbox } from './ConsentCheckbox';
+export { createDownloadButton } from './DownloadButton';
+export { createSubmitButton } from './SubmitButton';
+//# sourceMappingURL=index.d.ts.map

package/dist/defaults/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/defaults/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}