Interactive Forms & Multi Role Signatures

Interactive Forms & Multi-Role Signatures

The TeamSync PDF Viewer v2.0 Forms Engine provides a comprehensive client-side form builder, interactive form filler, multi-role template assignment system, signature sticky index flags, and audit-grade electronic & digital certificate signing.

---

🏗️ Architecture & Core Concepts

The multi-user forms system cleanly decouples Form Template Roles from Host Application Users:

┌────────────────────────────────────────────────────────┐
│ Document Form Template                                 │
│  - Field: "tenant_signature" (roleId: "tenant")        │
│  - Field: "landlord_signature" (roleId: "landlord")    │
│  - Form Roles: [ { id: "tenant" }, { id: "landlord" } ]│
└────────────────────────────────────────────────────────┘
                           ▲
                           │ binds dynamically
                           ▼
┌────────────────────────────────────────────────────────┐
│ Host Application User Session                          │
│  - Current User: { id: "u1", name: "Jane", role: "tenant" }│
│  - Automatically activates "tenant" fields and flags   │
└────────────────────────────────────────────────────────┘

1. Form Roles (FormRole):

   • Template roles defining who fills what field (e.g., 'applicant', 'tenant', 'landlord', 'reviewer').
   • Fields define roleId?: string referencing FormRole.id.
   • Templates can be saved, exported, and reused across different signers without hardcoding user IDs.

2. Current User (ViewerUser):

   • The actual logged-in user profile passed by your application:

     interface ViewerUser {
       id: string;
       name: string;
       email?: string;
       role?: string; // Fulfills matching FormRole.id
       avatar?: string;
     }

   • When set, the viewer automatically associates the user with their designated form role, personalizes the toolbar ("Filling as: Jane Doe (Tenant)"), and displays their required signature flags.

---

🔖 Signature Sticky / Index Flags

Signature Sticky / Index Flags make multi-page document signing effortless:

• Docked Viewport Flags: Sticky flags appear on the right side of the viewer pane for every signature field assigned to the current user's role.
• Cross-Page Accessibility: Even when the user is reading Page 1, signature flags for Page 2 or later remain visible in the viewport sidebar.
• 1-Click Jump & Sign (v2.1): Clicking a flag automatically navigates to the target page, smoothly scrolls the field into the center of the viewport (scrollIntoView), triggers a glowing pulse highlight animation, and focuses the field.
• Role-Filtered: Only flags assigned to the current user's role are shown, preventing confusion between multiple signers.
• Enterprise Security Hardening (v2.1):
  • Typed signatures strictly escape XML entities before SVG generation to prevent stored SVG injection.
  • Image uploads enforce strict MIME type whitelisting (image/png, image/jpeg, image/webp).
  • AcroForm export decodes signature Data URLs in memory without triggering network requests.

---

✍️ Form Field Controls & Signatures

Field Type	Supported Properties	Description
Textbox	placeholder, defaultValue, required	Single-line text input
Text Area	placeholder, defaultValue, required	Expandable multi-line text input
Date & Time	dateFormat: 'date' | 'time' | 'datetime'	Native calendar and clock picker
Checklist	options: string[]	Multi-select checkboxes or single checkbox
Dropdown	options: string[], defaultValue	Single-choice select dropdown
Radio Group	options: string[], defaultValue	Mutually exclusive options
Electronic Signature	signTagText, roleId	Canvas drawing, typed handwriting, or uploaded image
Digital Signature	signatureType: 'digital', SHA-256 seal	Cryptographic audit trail with timestamp and reason

---

⚙️ Programmatic Form SDK

The SDK provides full programmatic control over form roles, user assignment, form values, and feature permissions.

WebViewer Instance Methods

// 1. Manage Form Roles
const roles = instance.getFormRoles();
instance.setFormRoles([
  { id: 'tenant', name: 'Tenant', color: '#2563eb' },
  { id: 'landlord', name: 'Landlord', color: '#10b981' },
]);
instance.addFormRole({ id: 'guarantor', name: 'Guarantor', color: '#f59e0b' });

// 2. Set Current User & Role
instance.setCurrentUser({
  id: 'usr_49201',
  name: 'Robert Davis',
  email: 'robert@example.com',
  role: 'tenant', // Automatically activates 'tenant' role
});

// Or switch active role directly
instance.setCurrentRole('tenant');

// 3. Form Data Binding
const data = instance.getFormData();
instance.setFormData({ applicant_name: 'Robert Davis', lease_term: '12 Months' });
instance.clearFormData();

// 4. Per-Role Navigation & Validation
const validation = instance.validateForm('tenant'); // Validates only tenant fields
if (!validation.valid) {
  console.warn('Incomplete fields:', validation.errors);
}
instance.nextFormField('tenant');
instance.previousFormField('tenant');

---

🎛️ Controlling Form Feature Visibility (FormFeatureOptions)

Host applications can programmatically configure what form tools and controls are visible:

instance.setFormOptions({
  // Lock respondent to their assigned role (removes role switching dropdown)
  allowRoleSwitching: false,
  showRoleSelector: false,

  // Control visibility of fields assigned to other roles
  // 'interactive' | 'view-only' | 'hidden'
  otherRoleFieldsMode: 'view-only',

  // Sticky signature index flags
  showSignatureFlags: true,

  // Toolbar feature visibility
  showFlowNavigation: true,
  showValidation: true,
  showReset: false,
  showExport: false,
  hideToolbar: false,
});

---

💻 React Integration Example

import React, { useRef } from 'react';
import { TeamSyncViewer, WebViewerInstance } from 'teamsync-pdf-viewer';
import 'teamsync-pdf-viewer/style.css';

export function TenantSigningPortal() {
  const viewerRef = useRef<WebViewerInstance | null>(null);

  const currentUser = {
    id: 'usr_102',
    name: 'Sarah Connor',
    email: 'sarah@example.com',
    role: 'tenant',
  };

  const formRoles = [
    { id: 'tenant', name: 'Tenant', color: '#2563eb' },
    { id: 'landlord', name: 'Landlord', color: '#10b981' },
  ];

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <TeamSyncViewer
        initialDoc="/documents/lease-agreement.pdf"
        currentUser={currentUser}
        formRoles={formRoles}
        formOptions={{
          allowRoleSwitching: false, // Locked to tenant
          otherRoleFieldsMode: 'view-only', // Cannot edit landlord fields
          showSignatureFlags: true, // Display sticky signature flags
        }}
        onViewerReady={(instance) => {
          viewerRef.current = instance;
        }}
      />
    </div>
  );
}

---

📄 Native AcroForm Export

Interactive forms filled inside TeamSync PDF Viewer can be baked into standard PDF AcroForms upon export using pdf-lib. Exported files are fully standard-compliant and readable in Adobe Acrobat, Apple Preview, and web browsers.