teamsync-pdf-viewer 1.8.1 → 2.2.0

package/dist/src/core/types.d.ts

@@ -5,7 +5,9 @@ import { AnnotationChangedEvent } from '../annotations/AnnotationManager';
 import { PdfAssetPaths } from './pdfAssets';
 import { WebViewerInstance } from './ViewerInstance';
 import { OfficeConverterConfig, OfficeFileType } from '../office/types';
-export type { PdfAssetPaths, WebViewerInstance, OfficeConverterConfig, OfficeFileType };
+import { FormManager } from '../forms/FormManager';
+import { FormField, FormDataRecord, FormRole, FormFeatureOptions } from '../forms/types';
+export type { PdfAssetPaths, WebViewerInstance, OfficeConverterConfig, OfficeFileType, FormManager, FormField, FormDataRecord, FormRole, FormFeatureOptions, };
 export interface SearchBounds {
     x: number;
     y: number;
@@ -51,10 +53,22 @@ export interface SDKPermissions {
     canRedact?: boolean;
     /** Allow editing/deleting annotations authored by other users (default false). */
     canEditOthers?: boolean;
+    /** Allow designing / creating form fields in the Forms builder tab (default true). */
+    canCreateForms?: boolean;
+    /** Allow filling interactive form fields in the View tab (default true). */
+    canFillForms?: boolean;
 }
 export interface ViewerUser {
     id: string;
     name: string;
+    /** Optional email address of the user */
+    email?: string;
+    /** Form template role fulfilled by this user on the document (e.g. 'applicant', 'tenant', 'user_a') */
+    role?: string;
+    /** Alias of role */
+    roleId?: string;
+    /** User visual accent color */
+    color?: string;
 }
 export type InitialScale = number | 'fit-width' | 'fit-page' | {
     type: 'fit-width';
@@ -103,14 +117,66 @@ export interface WebViewerOptions {
     canAddAnnotations?: boolean;
     canEditAnnotations?: boolean;
     canDeleteAnnotations?: boolean;
+    /** Custom or pre-populated FormManager instance. */
+    formManager?: FormManager;
+    /**
+     * Form feature visibility and user interaction controls (e.g. allowUserSwitching, showSignatureFlags,
+     * showFlowNavigation, otherUserFieldsMode, etc.).
+     */
+    formOptions?: FormFeatureOptions;
+    /**
+     * The active form role ID (e.g. 'applicant', 'tenant', 'landlord').
+     * Controls which fields and signature flags are interactive/visible for this role.
+     */
+    currentRole?: string | null;
+    /** Custom list of form template roles. */
+    formRoles?: FormRole[];
+    /** Pre-populated form fields schema. */
+    formFields?: FormField[];
+    /** Pre-filled form values record. */
+    formData?: FormDataRecord;
     /** Shorthand for "no annotation/redaction editing at all". */
     readOnly?: boolean;
-    /** Author attached to annotations created in this viewer. */
+    /**
+     * Current logged-in user details passed by the host application (name, email, role, etc.).
+     * If user has a `role` property, the viewer automatically activates that role for form filling.
+     */
     currentUser?: ViewerUser;
     /** pdf.js worker / CMap / font / wasm locations (see `configurePdfAssets`). */
     assets?: PdfAssetPaths;
     /** Send cookies with the document request (same-origin session-bound URLs). Default false. */
     withCredentials?: boolean;
+    /**
+     * Custom HTTP headers sent with every document request (e.g. Authorization: Bearer <token>).
+     * Passed directly to the underlying PDF.js engine.
+     */
+    httpHeaders?: Record<string, string>;
+    /**
+     * Alias for `httpHeaders` providing an alternative headers option.
+     */
+    customHeaders?: Record<string, string>;
+    /**
+     * Maximum number of bytes fetched per HTTP 206 range request.
+     * Default is 65536 (= 64 KB).
+     */
+    rangeChunkSize?: number;
+    /**
+     * Disable chunked streaming of PDF file data.
+     * Default is false.
+     */
+    disableStream?: boolean;
+    /**
+     * Disable automatic background pre-fetching of remaining PDF file chunks when range requests are enabled.
+     * When true, only pages explicitly navigated to are fetched.
+     * Automatically disables streaming as required by the underlying PDF.js engine.
+     * Default is false.
+     */
+    disableAutoFetch?: boolean;
+    /**
+     * Disable HTTP 206 range requests entirely, forcing the full PDF to download.
+     * Default is false.
+     */
+    disableRange?: boolean;
     /** Render the top toolbar. Default true. */
     toolbar?: boolean;
     /** Render the left (thumbnails) and right (comments/search) panels. Default true. */

package/dist/src/forms/FormManager.d.ts

@@ -0,0 +1,105 @@
+import { FormField, FormDataRecord, FormValidationResult, FormRole, FormFeatureOptions } from './types';
+import { ViewerUser } from '../core/types';
+export declare const DEFAULT_FORM_OPTIONS: FormFeatureOptions;
+export declare const DEFAULT_ROLES: FormRole[];
+export interface FormFieldsChangeEvent {
+    fields: FormField[];
+    action: 'add' | 'update' | 'delete' | 'set' | 'clear';
+}
+export type FormFieldsChangeListener = (event: FormFieldsChangeEvent) => void;
+export type FormDataChangeListener = (data: FormDataRecord) => void;
+export declare class FormManager {
+    private fields;
+    private values;
+    private roles;
+    private currentRoleId;
+    private currentUser;
+    private activeFieldId;
+    private options;
+    private past;
+    private future;
+    private fieldsListeners;
+    private dataListeners;
+    private rolesListeners;
+    private activeRoleListeners;
+    private activeFieldListeners;
+    private optionsListeners;
+    private userListeners;
+    private readOnly;
+    constructor(initialFields?: FormField[], initialValues?: FormDataRecord, initialRoles?: FormRole[], initialOptions?: Partial<FormFeatureOptions>, initialUser?: ViewerUser | null);
+    onFieldsChange(listener: FormFieldsChangeListener): () => void;
+    onDataChange(listener: FormDataChangeListener): () => void;
+    private notifyFieldsChange;
+    private notifyDataChange;
+    private pushHistory;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    getFields(): FormField[];
+    getFieldsForPage(pageIndex: number): FormField[];
+    getField(id: string): FormField | undefined;
+    getFieldByName(name: string): FormField | undefined;
+    setFields(fields: FormField[]): void;
+    addField(field: FormField): void;
+    updateField(id: string, updates: Partial<Omit<FormField, 'id'>>, recordHistory?: boolean): boolean;
+    deleteField(id: string): boolean;
+    clearFields(): void;
+    getValues(): FormDataRecord;
+    getValue(name: string): any;
+    setValue(name: string, value: any): void;
+    setValues(newValues: FormDataRecord): void;
+    clearValues(): void;
+    setReadOnly(readOnly: boolean): void;
+    isReadOnly(): boolean;
+    getRoles(): FormRole[];
+    setRoles(roles: FormRole[]): void;
+    addRole(role: FormRole): void;
+    updateRole(id: string, updates: Partial<Omit<FormRole, 'id'>>): void;
+    removeRole(id: string): void;
+    getRole(id?: string): FormRole | undefined;
+    onRolesChange(listener: (roles: FormRole[]) => void): () => void;
+    getCurrentRole(): string | null;
+    setCurrentRole(roleId: string | null): void;
+    onCurrentRoleChange(listener: (roleId: string | null) => void): () => void;
+    /** Returns the current logged-in user details passed by the host application. */
+    getCurrentUser(): ViewerUser | null;
+    /**
+     * Sets the current logged-in user details passed by the host application.
+     * If the user object specifies a `role`, automatically sets that role as the active role.
+     */
+    setCurrentUser(user: ViewerUser | null): void;
+    /** Subscribes to changes in the current logged-in user details. */
+    onCurrentUserChange(listener: (user: ViewerUser | null) => void): () => void;
+    /**
+     * Returns the effective signer name:
+     * Prioritizes the actual user's real name (from host application),
+     * falling back to the active role name or an empty string.
+     */
+    getEffectiveSignerName(): string;
+    /** Returns the current form feature configuration options. */
+    getOptions(): FormFeatureOptions;
+    /**
+     * Updates form feature options and notifies active listeners.
+     */
+    setOptions(opts: Partial<FormFeatureOptions>): void;
+    /** Subscribes to changes in form feature options. */
+    onOptionsChange(listener: (options: FormFeatureOptions) => void): () => void;
+    getActiveFieldId(): string | null;
+    setActiveFieldId(fieldId: string | null): void;
+    onActiveFieldChange(listener: (fieldId: string | null) => void): () => void;
+    /**
+     * Returns form fields sorted according to flow order.
+     * If roleId is provided, filters to fields assigned to that role.
+     */
+    getFlowFields(roleId?: string | null): FormField[];
+    getNextField(currentFieldId?: string | null, roleId?: string | null): FormField | null;
+    getPreviousField(currentFieldId?: string | null, roleId?: string | null): FormField | null;
+    goToNextField(roleId?: string | null): FormField | null;
+    goToPreviousField(roleId?: string | null): FormField | null;
+    validate(roleId?: string | null): FormValidationResult;
+    exportFieldsJson(): string;
+    importFieldsJson(json: string): boolean;
+    exportDataJson(): string;
+    importDataJson(json: string): boolean;
+}

package/dist/src/forms/types.d.ts

@@ -0,0 +1,179 @@
+/**
+ * © 2026 AngelBot Ai Pvt Ltd. All rights reserved.
+ * Types and interfaces for the PDF Forms Builder and Form Filler engine.
+ */
+export type FormFieldType = 'text' | 'textbox' | 'textarea' | 'datetime' | 'checklist' | 'checkbox' | 'dropdown' | 'radio' | 'signature' | 'digital_signature';
+export type DateTimeFormat = 'date' | 'time' | 'datetime';
+export type SignatureType = 'electronic' | 'digital';
+export interface FormSignatureValue {
+    type: SignatureType;
+    /** PNG data URL for drawn, typed, or uploaded electronic signatures */
+    dataUrl?: string;
+    /** Name of the actual signer */
+    signerName?: string;
+    /** Optional email of the actual signer */
+    signerEmail?: string;
+    /** Optional role identifier or title fulfilled by the signer */
+    signerRole?: string;
+    /** Signing epoch timestamp */
+    timestamp?: number;
+    /** Purpose/reason for digital signing */
+    reason?: string;
+    /** Cryptographic thumbprint/hash preview for digital signature */
+    certificateHash?: string;
+}
+export interface FormField {
+    /** Unique identifier for the form field element */
+    id: string;
+    /** Field name identifier used when extracting form values or submitting (e.g. "applicant_name") */
+    name: string;
+    /** Form field type */
+    type: FormFieldType;
+    /** 1-based page index where this field resides */
+    pageIndex: number;
+    /** X coordinate in PDF page user space (points, 72 DPI) */
+    x: number;
+    /** Y coordinate in PDF page user space (points, 72 DPI) */
+    y: number;
+    /** Width in PDF page user space (points, 72 DPI) */
+    width: number;
+    /** Height in PDF page user space (points, 72 DPI) */
+    height: number;
+    /** Human-readable label displayed for the field */
+    label?: string;
+    /** Placeholder text for text-based inputs */
+    placeholder?: string;
+    /** Whether filling this field is required */
+    required?: boolean;
+    /** Default pre-populated value */
+    defaultValue?: any;
+    /** Current filled value */
+    value?: any;
+    /** List of selectable option strings for checklist, dropdown, or radio fields */
+    options?: string[];
+    /** Date/time picker format mode */
+    dateFormat?: DateTimeFormat;
+    /** Whether the field is locked against user input in filler mode */
+    readOnly?: boolean;
+    /** Foreground text color (hex or CSS color string, e.g. '#0f172a') */
+    textColor?: string;
+    /** Background fill color (hex, rgba, or 'transparent') */
+    backgroundColor?: string;
+    /** Custom border color (defaults to role color or neutral #94a3b8) */
+    borderColor?: string;
+    /** Border stroke width in pixels (1, 2, or 3) */
+    borderWidth?: number;
+    /** Corner border radius in pixels (0, 3, 6, 12) */
+    borderRadius?: number;
+    /** Font family for inputs, labels and choices (e.g. 'sans-serif', 'serif', 'monospace', 'cursive') */
+    fontFamily?: string;
+    /** Base font size in unscaled points (e.g. 10, 12, 14, 16, 18, 20) */
+    fontSize?: number;
+    /** Font weight */
+    fontWeight?: 'normal' | 'bold';
+    /** Font style */
+    fontStyle?: 'normal' | 'italic';
+    /** Text alignment */
+    textAlign?: 'left' | 'center' | 'right';
+    /** Role identifier responsible for filling this field (references FormRole.id) */
+    roleId?: string;
+    /** Explicit step order in the form filling sequence (1, 2, 3...) */
+    flowOrder?: number;
+    /** Specific signature mode: electronic or digital */
+    signatureType?: SignatureType;
+    /** Custom tag text displayed on the 'Sign Here' flag badge (e.g. 'Sign Here', 'Authorized Signature') */
+    signTagText?: string;
+}
+/**
+ * FormRole represents a role/slot defined in a document form template
+ * (e.g. 'applicant', 'tenant', 'landlord', 'reviewer', 'user_a').
+ * The form template assigns fields to roles; the host application passes the actual user details.
+ */
+export interface FormRole {
+    /** Unique role identifier (e.g. 'applicant', 'tenant', 'landlord', 'user_a') */
+    id: string;
+    /** Display label for this role (e.g. 'Applicant', 'Tenant', 'Landlord') */
+    name: string;
+    /** Hex color code for badges, borders and accents (e.g. '#2563eb') */
+    color: string;
+    /** Optional human-readable description for the role */
+    description?: string;
+}
+export type FormDataRecord = Record<string, any>;
+export interface FormValidationResult {
+    valid: boolean;
+    errors: Record<string, string>;
+}
+export type FormToolType = 'select' | 'textbox' | 'textarea' | 'datetime' | 'checklist' | 'dropdown' | 'radio' | 'signature' | 'digital_signature' | null;
+/**
+ * Options controlling which form features and UI controls are accessible to the user.
+ * Allows host applications to programmatically control form filling, design permissions,
+ * user persona switching, and feature visibility.
+ */
+export interface FormFeatureOptions {
+    /**
+     * Allow designing / creating form fields in the Forms builder tab.
+     * When false, the Forms tab is hidden or disabled.
+     * Default: true (or matches SDKPermissions.canCreateForms).
+     */
+    canCreateForms?: boolean;
+    /**
+     * Allow filling interactive form fields in the View tab.
+     * When false, all form inputs and signatures are read-only.
+     * Default: true (or matches SDKPermissions.canFillForms).
+     */
+    canFillForms?: boolean;
+    /**
+     * Whether the end-user can switch roles in the filler toolbar.
+     * When false, the role selector dropdown is locked to the assigned role.
+     * Default: true.
+     */
+    allowRoleSwitching?: boolean;
+    /**
+     * Show or hide the "Filling as:" role selector in the filler toolbar.
+     * Default: true.
+     */
+    showRoleSelector?: boolean;
+    /**
+     * Show or hide the persistent Post-it Signature Sticky / Index Flags on the side of the viewer.
+     * Default: true.
+     */
+    showSignatureFlags?: boolean;
+    /**
+     * Show or hide the step-by-step form flow navigation buttons (Previous / Step X of Y / Next).
+     * Default: true.
+     */
+    showFlowNavigation?: boolean;
+    /**
+     * Show or hide the "Validate" button and validation message in the filler toolbar.
+     * Default: true.
+     */
+    showValidation?: boolean;
+    /**
+     * Show or hide the "Reset" / clear form button in the filler toolbar.
+     * Default: true.
+     */
+    showReset?: boolean;
+    /**
+     * Show or hide the download / export filled PDF button in the filler toolbar.
+     * Default: true.
+     */
+    showExport?: boolean;
+    /**
+     * Controls how form fields assigned to OTHER roles are presented:
+     * - 'locked': rendered with disabled styling and a lock indicator badge (default)
+     * - 'hidden': completely hidden from view for the current user
+     * - 'view-only': rendered cleanly as read-only values without lock styling
+     */
+    otherRoleFieldsMode?: 'locked' | 'hidden' | 'view-only';
+    /**
+     * Hide the entire FormFillerActions toolbar in View mode.
+     * Default: false.
+     */
+    hideToolbar?: boolean;
+    /**
+     * Active form role identifier for form filling (e.g. 'applicant', 'tenant', 'user_a').
+     * Controls which fields and signature flags are active for the current user.
+     */
+    currentRole?: string | null;
+}

package/dist/src/index.d.ts

@@ -7,6 +7,7 @@
  */
 export { createWebViewer, WebViewer } from './core/createWebViewer';
 export { WebViewerInstance } from './core/ViewerInstance';
+export type { LoadDocumentOptions } from './core/ViewerInstance';
 export { TeamSyncViewer } from './components/TeamSyncViewer';
 export type { TeamSyncViewerProps } from './components/TeamSyncViewer';
 export * from './types/compare';
@@ -48,3 +49,6 @@ export { isOfficeDocumentUrl, isOfficeFile, detectOfficeType, isOfficeExtension,
 export { OfficeLoadingOverlay } from './office/OfficeLoadingOverlay';
 export type { OfficeConverterConfig, OfficeConversionConfig, OfficeConversionState, OfficeFileType, OfficeDocumentOptions, OfficeDocumentInfo, } from './office/types';
 export { VERSION } from './version';
+export { FormManager, DEFAULT_FORM_OPTIONS, DEFAULT_ROLES } from './forms/FormManager';
+export type { FormFieldsChangeEvent, FormFieldsChangeListener, FormDataChangeListener } from './forms/FormManager';
+export type { FormField, FormFieldType, DateTimeFormat, SignatureType, FormSignatureValue, FormRole, FormDataRecord, FormValidationResult, FormToolType, FormFeatureOptions, } from './forms/types';

package/dist/src/office/useOfficeDocument.d.ts

@@ -27,10 +27,6 @@ export interface UseOfficeDocumentResult {
     /** Manually trigger conversion or retry */
     convert: () => Promise<string | null>;
 }
-/**
- * React hook that pre-converts Office documents into viewable PDF URLs before viewer mounting.
- * If the input is already a PDF, it passes through immediately with `isConverting: false`.
- */
 export declare function useOfficeDocument(fileOrUrl: string | File | Blob | ArrayBuffer | null | undefined, options?: UseOfficeDocumentOptions): UseOfficeDocumentResult;
 /**
  * Standalone asynchronous preloader for Office documents.

package/dist/src/utils/linkUtils.d.ts

@@ -21,3 +21,9 @@ export declare function isDocumentUrl(url: string): boolean;
  * Parses any link URL into structured destination information, extracting target documents and page numbers.
  */
 export declare function parseLinkTarget(linkUrl: string): ParsedLinkTarget;
+/**
+ * Sanitizes a link URL to guarantee safe usage in anchor attributes (e.g. href).
+ * Rejects dangerous schemes like javascript:, vbscript:, and data:.
+ * Returns '#' if the scheme is unsafe or empty.
+ */
+export declare function sanitizeLinkUrl(url?: string): string;