teamsync-pdf-viewer 2.2.1 → 2.2.2

package/CHANGELOG.md

@@ -2,7 +2,47 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
-## [2.2.1] — 2026-11-03
+## [2.2.2] — 2026-11-05
+
+### Added & Enhanced
+- **AcroForm In-Place Updates & Round-Trip Export (F1)**:
+  - Form fields already present in a PDF are updated in-place during export via `form.getFields()` rather than failing with `FieldAlreadyExistsError` or skipping value updates.
+- **Interactive Radio Group Export (F2)**:
+  - Radio options are exported into native interactive PDF radio groups using `form.createRadioGroup()` with calculated bounding boxes, Helvetica text labels, and selection state.
+- **Hierarchical Checklist Export (F3)**:
+  - Multi-select checklist fields export with standardized hierarchical naming (`fieldName.OptionName`) and drawn text labels.
+- **Clean Signature Page Stream & Flatten Option (F4, F5)**:
+  - Unsigned signature placeholders no longer burn permanent ink artifacts onto the PDF content stream unless `flatten: true` is explicitly configured in `getFileData()`.
+  - Added `field.readOnly` checkbox in `FormFieldEditorModal` locking fields against modification, and enforced `enableReadOnly()` on AcroForms.
+  - Added `{ flatten?: boolean }` export option to flatten interactive fields into static page content when desired.
+- **Duplicate Field Key Collision Prevention (F6)**:
+  - Added duplicate name detection banner in the field configuration modal and deterministic suffix naming (`name_1`, `name_2`) during export to prevent collisions.
+- **Electronic vs Digital Signature Clarification (F7, F10)**:
+  - Electronic signatures are explicitly labeled `"Signed electronically by ..."` without misrepresenting visual signatures as digital certificates.
+  - Removed misleading pseudo-random hex strings; digital certificate signatures now show genuine status indicators.
+  - Strict signature value validation rejecting raw strings (e.g. `[object Object]` or `hello`) while accepting structured signature objects and Base64 images.
+- **Manager-Level Role Locking & Security (F8)**:
+  - `FormManager` enforces role assignment and read-only checks on `setValue()` and `setValues()`, blocking unauthorized edits unless `{ force: true }` is passed.
+- **Proportional Option Font Scaling (F9)**:
+  - Replaced rigid 10px minimum clamp on radio and checklist options with proportional scaling down to 7px, eliminating overflow clipping and scrollbars on zoom-out.
+- **Aligned Validation & Unassigned Role Policies (F11)**:
+  - Configurable `unassignedFieldsRole` (`'all' | 'none' | roleId`) ensuring completion counters and `validate()` agree. Validation errors now include role names (e.g., `(Buyer)`).
+- **Native AcroForm & XFDF Form Ingestion (F12, F13)**:
+  - Introduced `extractAcroFormFields` to detect and parse existing PDF `Widget` annotations into interactive form field models.
+  - Introduced `parseXfdfFormFields` to parse XFDF `<widget>` and `<field>` tags directly into `FormManager` without creating dead grey outline annotations.
+- **Form Role Metadata (F14)**:
+  - Added `partyType` (`'signer' | 'viewer' | 'notary'`), `signingOrder`, and custom `metadata` to `FormRole`.
+- **Programmatic Tab Navigation & Granular Events (F15, F18)**:
+  - Added `instance.UI.setActiveTab(tab)` and `instance.UI.getActiveTab()` with `tabChanged` event emission.
+  - Added granular event hooks: `fieldValueChanged`, `signatureApplied`, `signatureCleared`, `fieldAdded`, `fieldRemoved`, `fieldUpdated`.
+- **Role Field Highlighting (F16)**:
+  - Added `instance.highlightRoleFields(roleId)` with accent glow across matching fields.
+- **Adopted Signature Caching & 1-Click Sign All (F17)**:
+  - Added session-level adopted signature persistence with 1-click application across all pending signature fields for the active role.
+- **Prop Synchronization & Undo Isolation (F19)**:
+  - Props passed to `<TeamSyncViewer>` (`formFields`, `formData`) synchronize cleanly without resetting state or polluting undo history stacks.
+- **Dynamic Schema Versioning (F20)**:
+  - Exported field templates now dynamically reflect library version `2.2.2`.
 
 ### Security
 - **Cryptographically Secure Identifier Generation**: Replaced pseudo-random number generator routines with cryptographically secure random values (`crypto.randomUUID()` and `crypto.getRandomValues()`) across fallback blob URLs, manual redactions, and form roles, resolving CodeQL alert CWE-338.

package/README.md

@@ -78,7 +78,7 @@ Explore detailed SDK guides, parameter options, code snippets, and architecture
 
 ---
 
-## ✨ Uncompromised Feature Set
+## ✨ Feature Set
 
 Everything you need to build collaborative, secure document workflows.
 

package/dist/src/annotations/AnnotationManager.d.ts

@@ -31,6 +31,8 @@ export declare class AnnotationManager {
     private readOnly;
     private canEditOthers;
     private resolver;
+    private formManager;
+    setFormManager(fm: any): void;
     setDocument(doc: PDFDocumentProxy | null): void;
     hasDocument(): boolean;
     setCurrentUser(name: string, id?: string): void;

package/dist/src/annotations/xfdf.d.ts

@@ -1,4 +1,5 @@
 import { Annotation } from './types';
+import { FormField, FormDataRecord } from '../forms/types';
 import { GeometryResolver } from './geometry';
 export declare const XFDF_NS = "http://ns.adobe.com/xfdf/";
 export interface XfdfExportOptions {
@@ -16,3 +17,10 @@ export declare function annotationToXfdfFragment(a: Annotation, resolve: Geometr
 /** Serialize annotations to a complete XFDF document. */
 export declare function annotationsToXfdf(annotations: Annotation[], resolve: GeometryResolver, opts?: XfdfExportOptions): Promise<string>;
 export declare function parseXfdf(xml: string, resolve: GeometryResolver): Promise<Annotation[]>;
+/**
+ * Extracts form field definitions (<widget>) and field values (<fields>) from an XFDF document (F13).
+ */
+export declare function parseXfdfFormFields(xml: string, resolve?: GeometryResolver, roleMapper?: (customData: Record<string, string>) => string | undefined): Promise<{
+    fields: FormField[];
+    values: FormDataRecord;
+}>;

package/dist/src/components/DocumentViewer.d.ts

@@ -90,6 +90,7 @@ interface DocumentViewerProps {
     formManager?: FormManager;
     setActiveTab?: (tab: string) => void;
     onDownloadFilledPdf?: () => void;
+    highlightedRoleId?: string | null;
 }
-export default function DocumentViewer({ leftSidebarOpen, rightSidebarOpen, activeTab, annotationManager, initialDoc, loadNonce, withCredentials, httpHeaders, customHeaders, rangeChunkSize, disableStream, disableAutoFetch, disableRange, password, assets, sidebars, redactions, regexRedactions, scale, setScale, sidebarTab, setSidebarTab, onAnnotationsChange, onRedactionsChange, onRedactionsApplied, onDocumentLoaded, onLoadError, onFirstPageRendered, onPageRendered, onPageChange, pageTransition, pageLayout, rotation, setRotation, watermark, watermarkText, enableAnnotations: _enableAnnotations, initialPage, page, transientHighlights, permissions, hideAnnotationsUntilPageRendered, enableTextSelection, defaultTool, showSelectionTooltip, initialScale, initialWidthRatio, responsive, instance, targetViewer, resolveLinkUrl, onLinkClick, formManager, setActiveTab, onDownloadFilledPdf, }: DocumentViewerProps): React.JSX.Element;
+export default function DocumentViewer({ leftSidebarOpen, rightSidebarOpen, activeTab, annotationManager, initialDoc, loadNonce, withCredentials, httpHeaders, customHeaders, rangeChunkSize, disableStream, disableAutoFetch, disableRange, password, assets, sidebars, redactions, regexRedactions, scale, setScale, sidebarTab, setSidebarTab, onAnnotationsChange, onRedactionsChange, onRedactionsApplied, onDocumentLoaded, onLoadError, onFirstPageRendered, onPageRendered, onPageChange, pageTransition, pageLayout, rotation, setRotation, watermark, watermarkText, enableAnnotations: _enableAnnotations, initialPage, page, transientHighlights, permissions, hideAnnotationsUntilPageRendered, enableTextSelection, defaultTool, showSelectionTooltip, initialScale, initialWidthRatio, responsive, instance, targetViewer, resolveLinkUrl, onLinkClick, formManager, setActiveTab, onDownloadFilledPdf, highlightedRoleId, }: DocumentViewerProps): React.JSX.Element;
 export {};

package/dist/src/components/FormFieldEditorModal.d.ts

@@ -3,6 +3,7 @@ import { FormField, FormRole } from '../forms/types';
 interface FormFieldEditorModalProps {
     field: FormField;
     roles?: FormRole[];
+    existingFields?: FormField[];
     onAddRole?: (role: FormRole) => void;
     onSave: (updated: Partial<FormField>) => void;
     onClose: () => void;

package/dist/src/components/FormFieldLayer.d.ts

@@ -14,6 +14,7 @@ interface FormFieldLayerProps {
     canFillForms?: boolean;
     showFlowOrder?: boolean;
     selectedRoleFilter?: string | null;
+    highlightedRoleId?: string | null;
 }
 export declare const FormFieldLayer: React.FC<FormFieldLayerProps>;
 export {};

package/dist/src/components/FormSignatureModal.d.ts

@@ -6,6 +6,7 @@ interface FormSignatureModalProps {
     role?: FormRole;
     currentUser?: ViewerUser | null;
     currentValue?: FormSignatureValue | any;
+    adoptedSignature?: FormSignatureValue | null;
     defaultSignerName?: string;
     onSave: (value: FormSignatureValue) => void;
     onClear?: () => void;

package/dist/src/components/PageRenderer.d.ts

@@ -49,7 +49,8 @@ interface PageRendererProps {
     canFillForms?: boolean;
     showFlowOrder?: boolean;
     selectedRoleFilter?: string | null;
+    highlightedRoleId?: string | null;
 }
-declare function PageRendererComponent({ pageNum, pdfDoc, scale, rotation, containerWidth: _containerWidth, containerHeight: _containerHeight, scrollTop: _scrollTop, scrollLeft: _scrollLeft, pageTop, pageLeft, basePageWidth, basePageHeight, activeTab, activeTool, annotations, selectedAnnotationId, activeSearchResult, transientHighlights, onMouseDown, onMouseMove, onMouseUp, onAnnotationClick, onAnnotationDoubleClick, onStartResize, onStartMove, onAnnotationMouseEnter, onClearSelection, watermark, watermarkText, redactions, onDiscardRedaction, onRendered, hideAnnotationsUntilPageRendered, onLinkClick, formManager, activeFormTool, setActiveFormTool, canFillForms, showFlowOrder, selectedRoleFilter }: PageRendererProps): React.JSX.Element;
+declare function PageRendererComponent({ pageNum, pdfDoc, scale, rotation, containerWidth: _containerWidth, containerHeight: _containerHeight, scrollTop: _scrollTop, scrollLeft: _scrollLeft, pageTop, pageLeft, basePageWidth, basePageHeight, activeTab, activeTool, annotations, selectedAnnotationId, activeSearchResult, transientHighlights, onMouseDown, onMouseMove, onMouseUp, onAnnotationClick, onAnnotationDoubleClick, onStartResize, onStartMove, onAnnotationMouseEnter, onClearSelection, watermark, watermarkText, redactions, onDiscardRedaction, onRendered, hideAnnotationsUntilPageRendered, onLinkClick, formManager, activeFormTool, setActiveFormTool, canFillForms, showFlowOrder, selectedRoleFilter, highlightedRoleId }: PageRendererProps): React.JSX.Element;
 declare const PageRenderer: React.MemoExoticComponent<typeof PageRendererComponent>;
 export default PageRenderer;

package/dist/src/components/TeamSyncViewer.d.ts

@@ -1,6 +1,7 @@
 import { default as React } from 'react';
 import { DocumentLoadErrorInfo } from './DocumentViewer';
 import { WebViewerInstance } from '../core/ViewerInstance';
+import { FormField, FormDataRecord } from '../forms/types';
 import { WebViewerOptions, Redaction, TransientHighlight, LinkClickEvent } from '../core/types';
 import { Annotation } from '../annotations/types';
 import { OfficeConverterConfig, OfficeFileType } from '../office';
@@ -97,6 +98,16 @@ export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
         error: Error;
         url?: string;
     }) => void;
+    /** Initial active UI mode tab: 'View' | 'Annotate' | 'Forms' (default 'View') (F15). */
+    initialTab?: string;
+    /** Initial form fields definition (F19). */
+    initialFormFields?: FormField[];
+    /** Initial form data values (F19). */
+    initialFormData?: FormDataRecord;
+    /** Fires when active UI tab changes (F15). */
+    onTabChanged?: (info: {
+        tab: string;
+    }) => void;
     className?: string;
     style?: React.CSSProperties;
 }

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

@@ -65,6 +65,7 @@ export interface ViewerBinding {
     }): void;
     getTransientHighlights(): TransientHighlight[];
     setTransientHighlights(highlights: TransientHighlight[]): void;
+    getActiveTab?(): string;
 }
 export declare class WebViewerInstance {
     private static instances;
@@ -89,7 +90,15 @@ export declare class WebViewerInstance {
     private unmountRoot;
     private destroyed;
     private targetViewerTarget;
+    private currentActiveTab;
     constructor(bus: ViewerBus, annotationManager?: AnnotationManager, id?: string, formManager?: FormManager);
+    /**
+     * Visually highlights form fields belonging to a specific role with an accent glow (F16).
+     * Pass null to clear active highlights.
+     */
+    highlightRoleFields(roleId: string | null): void;
+    /** Returns current active tab in the viewer (F15). */
+    getActiveTab(): string;
     /** Sets the target viewer instance, ref, getter, or ID to receive cross-document links. */
     setTargetViewer(target: WebViewerInstance | React.RefObject<WebViewerInstance | null> | (() => WebViewerInstance | null) | string | null): void;
     /** Resolves the target viewer instance if configured. */
@@ -266,6 +275,10 @@ export declare class WebViewerInstance {
      */
     copySelectedText(): Promise<boolean>;
     readonly UI: {
+        /** Sets active UI mode tab: 'View' | 'Annotate' | 'Forms' (F15). */
+        setActiveTab: (tab: "View" | "Annotate" | "Forms" | string) => void;
+        /** Returns currently active tab (F15). */
+        getActiveTab: () => string;
         /** Theming is not implemented; kept for API compatibility. */
         setTheme: (_theme: string) => void;
         goToPage: (pageNumber: number) => void;

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

@@ -16,11 +16,15 @@ export interface ExportInput {
     signerName?: string;
     formFields?: FormField[];
     formData?: FormDataRecord;
+    /** Whether to lock and flatten form fields into static page content on export (F5). */
+    flatten?: boolean;
 }
 export interface ExportOptions {
     /** Bake exactly these annotations instead of the live list. */
     explicitAnnotations?: Annotation[];
     /** Accepted for API compatibility; annotations are always taken from the live list / explicitAnnotations. */
     xfdfString?: string;
+    /** Whether to lock and flatten form fields into static page content on export (F5). */
+    flatten?: boolean;
 }
 export declare function buildPdfBytes(input: ExportInput, options?: ExportOptions): Promise<Uint8Array>;

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

@@ -6,7 +6,7 @@ import { PdfAssetPaths } from './pdfAssets';
 import { WebViewerInstance } from './ViewerInstance';
 import { OfficeConverterConfig, OfficeFileType } from '../office/types';
 import { FormManager } from '../forms/FormManager';
-import { FormField, FormDataRecord, FormRole, FormFeatureOptions } from '../forms/types';
+import { FormField, FormDataRecord, FormRole, FormFeatureOptions, FormFieldValueChangedEvent, FormSignatureAppliedEvent, FormSignatureClearedEvent, FormFieldAddedEvent, FormFieldRemovedEvent, FormFieldUpdatedEvent } from '../forms/types';
 export type { PdfAssetPaths, WebViewerInstance, OfficeConverterConfig, OfficeFileType, FormManager, FormField, FormDataRecord, FormRole, FormFeatureOptions, };
 export interface SearchBounds {
     x: number;
@@ -302,6 +302,30 @@ export interface ViewerEventMap {
         text: string;
     };
     linkClicked: LinkClickEvent;
+    /** Fires when active UI tab changes (View / Annotate / Forms). */
+    tabChanged: {
+        tab: string;
+    };
+    /** Granular form field value change event (F18). */
+    fieldValueChanged: FormFieldValueChangedEvent;
+    /** Granular signature applied event (F18). */
+    signatureApplied: FormSignatureAppliedEvent;
+    /** Granular signature cleared event (F18). */
+    signatureCleared: FormSignatureClearedEvent;
+    /** Form field schema added (F18). */
+    fieldAdded: FormFieldAddedEvent;
+    /** Form field schema removed (F18). */
+    fieldRemoved: FormFieldRemovedEvent;
+    /** Form field schema updated (F18). */
+    fieldUpdated: FormFieldUpdatedEvent;
+    /** Full form data changed event. */
+    formDataChanged: {
+        data: Record<string, any>;
+    };
+    /** Full form fields schema changed event. */
+    formFieldsChanged: {
+        fields: FormField[];
+    };
     /** Fires when an Office document begins conversion. */
     officeConverting: {
         fileType: OfficeFileType;

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

@@ -1,4 +1,4 @@
-import { FormField, FormDataRecord, FormValidationResult, FormRole, FormFeatureOptions } from './types';
+import { FormField, FormDataRecord, FormValidationResult, FormRole, FormFeatureOptions, FormSignatureValue, FormFieldValueChangedEvent, FormSignatureAppliedEvent, FormSignatureClearedEvent, FormFieldAddedEvent, FormFieldRemovedEvent, FormFieldUpdatedEvent } from './types';
 import { ViewerUser } from '../core/types';
 export declare const DEFAULT_FORM_OPTIONS: FormFeatureOptions;
 export declare const DEFAULT_ROLES: FormRole[];
@@ -25,10 +25,31 @@ export declare class FormManager {
     private activeFieldListeners;
     private optionsListeners;
     private userListeners;
+    private fieldValueListeners;
+    private signatureAppliedListeners;
+    private signatureClearedListeners;
+    private fieldAddedListeners;
+    private fieldRemovedListeners;
+    private fieldUpdatedListeners;
+    private adoptedSignature;
     private readOnly;
     constructor(initialFields?: FormField[], initialValues?: FormDataRecord, initialRoles?: FormRole[], initialOptions?: Partial<FormFeatureOptions>, initialUser?: ViewerUser | null);
     onFieldsChange(listener: FormFieldsChangeListener): () => void;
     onDataChange(listener: FormDataChangeListener): () => void;
+    onFieldValueChanged(listener: (event: FormFieldValueChangedEvent) => void): () => void;
+    onSignatureApplied(listener: (event: FormSignatureAppliedEvent) => void): () => void;
+    onSignatureCleared(listener: (event: FormSignatureClearedEvent) => void): () => void;
+    onFieldAdded(listener: (event: FormFieldAddedEvent) => void): () => void;
+    onFieldRemoved(listener: (event: FormFieldRemovedEvent) => void): () => void;
+    onFieldUpdated(listener: (event: FormFieldUpdatedEvent) => void): () => void;
+    private notifyFieldValueChanged;
+    private notifySignatureApplied;
+    private notifySignatureCleared;
+    private notifyFieldAdded;
+    private notifyFieldRemoved;
+    private notifyFieldUpdated;
+    getAdoptedSignature(): FormSignatureValue | null;
+    setAdoptedSignature(sig: FormSignatureValue | null): void;
     private notifyFieldsChange;
     private notifyDataChange;
     private pushHistory;
@@ -40,15 +61,28 @@ export declare class FormManager {
     getFieldsForPage(pageIndex: number): FormField[];
     getField(id: string): FormField | undefined;
     getFieldByName(name: string): FormField | undefined;
-    setFields(fields: FormField[]): void;
+    setFields(fields: FormField[], recordHistory?: boolean): void;
     addField(field: FormField): void;
     updateField(id: string, updates: Partial<Omit<FormField, 'id'>>, recordHistory?: boolean): boolean;
     deleteField(id: string): boolean;
+    /** Alias for deleteField (F18). */
+    removeField(id: string): boolean;
     clearFields(): void;
     getValues(): FormDataRecord;
     getValue(name: string): any;
-    setValue(name: string, value: any): void;
-    setValues(newValues: FormDataRecord): void;
+    /**
+     * Checks whether a form field can currently be modified based on form read-only state,
+     * field-level read-only setting, and the active role assignment (F8).
+     */
+    canEditField(fieldOrName: FormField | string): boolean;
+    setValue(name: string, value: any, options?: {
+        force?: boolean;
+        source?: 'user' | 'code';
+    }): boolean;
+    setValues(newValues: FormDataRecord, options?: {
+        force?: boolean;
+        source?: 'user' | 'code';
+    }): void;
     clearValues(): void;
     setReadOnly(readOnly: boolean): void;
     isReadOnly(): boolean;

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

@@ -0,0 +1,6 @@
+import { FormField, FormDataRecord } from './types';
+import { GeometryResolver } from '../annotations/geometry';
+export declare function extractAcroFormFields(pdfDoc: any, resolver?: GeometryResolver): Promise<{
+    fields: FormField[];
+    values: FormDataRecord;
+}>;

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

@@ -98,6 +98,37 @@ export interface FormRole {
     color: string;
     /** Optional human-readable description for the role */
     description?: string;
+    /** Optional party type classification (e.g. 'internal', 'external', 'signer', 'viewer') */
+    partyType?: 'internal' | 'external' | string;
+    /** Optional signing order or sequence index in a multi-party workflow */
+    signingOrder?: number;
+    /** Optional custom host-specific metadata attributes */
+    metadata?: Record<string, any>;
+}
+export interface FormFieldValueChangedEvent {
+    fieldName: string;
+    oldValue: any;
+    newValue: any;
+    source: 'user' | 'code';
+}
+export interface FormSignatureAppliedEvent {
+    fieldName: string;
+    signature: FormSignatureValue;
+    signerName?: string;
+}
+export interface FormSignatureClearedEvent {
+    fieldName: string;
+}
+export interface FormFieldAddedEvent {
+    field: FormField;
+}
+export interface FormFieldRemovedEvent {
+    fieldId: string;
+    fieldName: string;
+}
+export interface FormFieldUpdatedEvent {
+    field: FormField;
+    changes: Partial<FormField>;
 }
 export type FormDataRecord = Record<string, any>;
 export interface FormValidationResult {
@@ -176,4 +207,11 @@ export interface FormFeatureOptions {
      * Controls which fields and signature flags are active for the current user.
      */
     currentRole?: string | null;
+    /**
+     * Defines which role unassigned fields (fields with no roleId) belong to during validation:
+     * - 'all': unassigned fields are required for everyone (default)
+     * - 'none': unassigned fields are never treated as required for any specific role
+     * - string: role ID that unassigned fields belong to
+     */
+    unassignedFieldsRole?: 'all' | 'none' | string;
 }

package/dist/src/index.d.ts

@@ -51,4 +51,6 @@ export type { OfficeConverterConfig, OfficeConversionConfig, OfficeConversionSta
 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';
+export { extractAcroFormFields } from './forms/acroFormIngestion';
+export { parseXfdfFormFields } from './annotations/xfdf';
+export type { FormField, FormFieldType, DateTimeFormat, SignatureType, FormSignatureValue, FormRole, FormDataRecord, FormValidationResult, FormToolType, FormFeatureOptions, FormFieldValueChangedEvent, FormSignatureAppliedEvent, FormSignatureClearedEvent, FormFieldAddedEvent, FormFieldRemovedEvent, FormFieldUpdatedEvent, } from './forms/types';

package/dist/src/version.d.ts

@@ -1 +1,2 @@
 export declare const VERSION: string;
+export declare const LIB_VERSION: string;