@embedpdf/models 2.9.0 → 2.10.0

package/dist/pdf.d.ts

@@ -1187,9 +1187,21 @@ export declare enum PDF_FORM_FIELD_FLAG {
     NOEXPORT = 4,
     TEXT_MULTIPLINE = 4096,
     TEXT_PASSWORD = 8192,
+    TEXT_FILESELECT = 1048576,
+    TEXT_DONOTSPELLCHECK = 4194304,
+    TEXT_DONOTSCROLL = 8388608,
+    TEXT_COMB = 16777216,
+    TEXT_RICHTEXT = 33554432,
+    BUTTON_NOTOGGLETOOFF = 16384,
+    BUTTON_RADIO = 32768,
+    BUTTON_PUSHBUTTON = 65536,
+    BUTTON_RADIOSINUNISON = 33554432,
     CHOICE_COMBO = 131072,
     CHOICE_EDIT = 262144,
-    CHOICE_MULTL_SELECT = 2097152
+    CHOICE_SORT = 524288,
+    CHOICE_MULTL_SELECT = 2097152,
+    CHOICE_DONOTSPELLCHECK = 4194304,
+    CHOICE_COMMITONSELCHANGE = 67108864
 }
 /**
  * Type of pdf object
@@ -1245,53 +1257,207 @@ export declare function flagsToNames(raw: number): PdfAnnotationFlagName[];
  */
 export declare function namesToFlags(names: readonly PdfAnnotationFlagName[]): PdfAnnotationFlags;
 /**
- * Field of PDF widget annotation
+ * Shared properties across all widget annotation field types
  *
  * @public
  */
-export interface PdfWidgetAnnoField {
+export interface PdfWidgetAnnoFieldBase {
+    flag: PDF_FORM_FIELD_FLAG;
+    name: string;
+    alternateName: string;
+    value: string;
+    fieldObjectId?: number;
+}
+/**
+ * @public
+ */
+export interface PdfTextWidgetAnnoField extends PdfWidgetAnnoFieldBase {
+    type: PDF_FORM_FIELD_TYPE.TEXTFIELD;
+    maxLen?: number;
+}
+/**
+ * @public
+ */
+export interface PdfCheckboxWidgetAnnoField extends PdfWidgetAnnoFieldBase {
+    type: PDF_FORM_FIELD_TYPE.CHECKBOX;
+}
+/**
+ * @public
+ */
+export interface PdfRadioButtonWidgetAnnoField extends PdfWidgetAnnoFieldBase {
+    type: PDF_FORM_FIELD_TYPE.RADIOBUTTON;
+    options: PdfWidgetAnnoOption[];
+}
+/**
+ * @public
+ */
+export interface PdfComboboxWidgetAnnoField extends PdfWidgetAnnoFieldBase {
+    type: PDF_FORM_FIELD_TYPE.COMBOBOX;
+    options: PdfWidgetAnnoOption[];
+}
+/**
+ * @public
+ */
+export interface PdfListboxWidgetAnnoField extends PdfWidgetAnnoFieldBase {
+    type: PDF_FORM_FIELD_TYPE.LISTBOX;
+    options: PdfWidgetAnnoOption[];
+}
+/**
+ * @public
+ */
+export interface PdfPushButtonWidgetAnnoField extends PdfWidgetAnnoFieldBase {
+    type: PDF_FORM_FIELD_TYPE.PUSHBUTTON;
+}
+/**
+ * @public
+ */
+export interface PdfSignatureWidgetAnnoField extends PdfWidgetAnnoFieldBase {
+    type: PDF_FORM_FIELD_TYPE.SIGNATURE;
+}
+/**
+ * @public
+ */
+export interface PdfUnknownWidgetAnnoField extends PdfWidgetAnnoFieldBase {
+    type: PDF_FORM_FIELD_TYPE.UNKNOWN | PDF_FORM_FIELD_TYPE.XFA | PDF_FORM_FIELD_TYPE.XFA_CHECKBOX | PDF_FORM_FIELD_TYPE.XFA_COMBOBOX | PDF_FORM_FIELD_TYPE.XFA_IMAGEFIELD | PDF_FORM_FIELD_TYPE.XFA_LISTBOX | PDF_FORM_FIELD_TYPE.XFA_PUSHBUTTON | PDF_FORM_FIELD_TYPE.XFA_SIGNATURE | PDF_FORM_FIELD_TYPE.XFA_TEXTFIELD;
+}
+/**
+ * Discriminated union of all widget annotation field types
+ *
+ * @public
+ */
+export type PdfWidgetAnnoField = PdfTextWidgetAnnoField | PdfCheckboxWidgetAnnoField | PdfRadioButtonWidgetAnnoField | PdfComboboxWidgetAnnoField | PdfListboxWidgetAnnoField | PdfPushButtonWidgetAnnoField | PdfSignatureWidgetAnnoField | PdfUnknownWidgetAnnoField;
+/**
+ * PDF widget object
+ *
+ * @public
+ */
+export interface PdfWidgetAnnoObject extends PdfAnnotationObjectBase {
+    /** {@inheritDoc PdfAnnotationObjectBase.type} */
+    type: PdfAnnotationSubtype.WIDGET;
     /**
-     * flag of field
+     * Field of pdf widget object
      */
-    flag: PDF_FORM_FIELD_FLAG;
+    field: PdfWidgetAnnoField;
     /**
-     * name of field
+     * The non-"Off" appearance state key from the widget's /AP/N dictionary.
+     * For checkboxes this is typically "Yes"; for radio buttons it is a unique
+     * identifier (usually the widget's NM). Checked state is derived:
+     * `field.value === exportValue`.
      */
-    name: string;
+    exportValue?: string;
     /**
-     * alternate name of field
+     * font family of pdf widget object
      */
-    alternateName: string;
+    fontFamily: PdfStandardFont;
     /**
-     * type of field
+     * font size of pdf widget object
      */
-    type: PDF_FORM_FIELD_TYPE;
+    fontSize: number;
     /**
-     * value of field
+     * font color of pdf widget object
      */
-    value: string;
+    fontColor: string;
     /**
-     * whether field is checked
+     * MK border color (BC) as web hex string, e.g. '#FF0000'
      */
-    isChecked: boolean;
+    strokeColor?: string;
     /**
-     * options of field
+     * MK background color (BG) as web hex string, e.g. '#FFFFFF'
      */
-    options: PdfWidgetAnnoOption[];
+    color?: string;
+    /**
+     * Border width in points (BS width)
+     */
+    strokeWidth?: number;
 }
 /**
- * PDF widget object
+ * Returns whether a toggle widget (checkbox / radio button) is currently
+ * in its "on" state by comparing the shared field value against this
+ * widget's unique export value from the /AP/N dictionary.
  *
  * @public
  */
-export interface PdfWidgetAnnoObject extends PdfAnnotationObjectBase {
-    /** {@inheritDoc PdfAnnotationObjectBase.type} */
-    type: PdfAnnotationSubtype.WIDGET;
+export declare function isWidgetChecked(widget: PdfWidgetAnnoObject): boolean;
+/**
+ * Widget additional-action event types exposed by PDFium.
+ *
+ * @public
+ */
+export declare enum PDF_ANNOT_AACTION_EVENT {
+    KEY_STROKE = 12,
+    FORMAT = 13,
+    VALIDATE = 14,
+    CALCULATE = 15
+}
+/**
+ * Normalized widget JavaScript trigger names.
+ *
+ * @public
+ */
+export declare enum PdfJavaScriptWidgetEventType {
+    Keystroke = "keystroke",
+    Format = "format",
+    Validate = "validate",
+    Calculate = "calculate"
+}
+/**
+ * Normalized JavaScript action trigger names.
+ *
+ * @public
+ */
+export declare enum PdfJavaScriptActionTrigger {
+    DocumentNamed = "document_named",
+    WidgetKeystroke = "widget_keystroke",
+    WidgetFormat = "widget_format",
+    WidgetValidate = "widget_validate",
+    WidgetCalculate = "widget_calculate"
+}
+/**
+ * Base shape shared by extracted PDF JavaScript actions.
+ *
+ * @public
+ */
+export interface PdfJavaScriptActionObjectBase {
     /**
-     * Field of pdf widget object
+     * Stable identifier for the extracted action within the current document snapshot.
      */
-    field: PdfWidgetAnnoField;
+    id: string;
+    /**
+     * Normalized trigger classification used by higher layers.
+     */
+    trigger: PdfJavaScriptActionTrigger;
+    /**
+     * Raw JavaScript source extracted from the PDF.
+     */
+    script: string;
+}
+/**
+ * A named document-level JavaScript action from the document JavaScript name tree.
+ *
+ * @public
+ */
+export interface PdfDocumentJavaScriptActionObject extends PdfJavaScriptActionObjectBase {
+    trigger: PdfJavaScriptActionTrigger.DocumentNamed;
+    name: string;
 }
+/**
+ * A widget-level JavaScript additional action.
+ *
+ * @public
+ */
+export interface PdfWidgetJavaScriptActionObject extends PdfJavaScriptActionObjectBase {
+    trigger: PdfJavaScriptActionTrigger.WidgetKeystroke | PdfJavaScriptActionTrigger.WidgetFormat | PdfJavaScriptActionTrigger.WidgetValidate | PdfJavaScriptActionTrigger.WidgetCalculate;
+    eventType: PdfJavaScriptWidgetEventType;
+    pageIndex: number;
+    annotationId: string;
+    fieldName: string;
+}
+/**
+ * Discriminated union of supported extracted PDF JavaScript actions.
+ *
+ * @public
+ */
+export type PdfJavaScriptActionObject = PdfDocumentJavaScriptActionObject | PdfWidgetJavaScriptActionObject;
 /**
  * Pdf file attachments annotation
  *
@@ -1967,6 +2133,14 @@ export interface PdfUnsupportedAnnoObject extends PdfAnnotationObjectBase {
  * @public
  */
 export type PdfAnnotationObject = PdfSupportedAnnoObject | PdfUnsupportedAnnoObject;
+/**
+ * Extracts the concrete annotation object type for a specific subtype.
+ *
+ * @public
+ */
+export type PdfAnnotationOf<S extends PdfAnnotationSubtype> = Extract<PdfAnnotationObject, {
+    type: S;
+}>;
 /**
  * Pdf attachment
  *
@@ -2345,7 +2519,7 @@ export type FormFieldValue = {
     isSelected: boolean;
 } | {
     kind: 'checked';
-    isChecked: boolean;
+    checked: boolean;
 };
 /**
  * Transformation that will be applied to annotation
@@ -2867,6 +3041,34 @@ export interface PdfEngine<T = Blob> {
      * @returns task contains the annotations or error
      */
     getPageAnnotations: (doc: PdfDocumentObject, page: PdfPageObject) => PdfTask<PdfAnnotationObject[]>;
+    /**
+     * Extract named document JavaScript actions without executing them.
+     * @param doc - pdf document
+     * @returns task that contains all named document JavaScript actions
+     */
+    getDocumentJavaScriptActions: (doc: PdfDocumentObject) => PdfTask<PdfDocumentJavaScriptActionObject[]>;
+    /**
+     * Get form fields of pdf page
+     * @param doc - pdf document
+     * @param page - pdf page
+     * @returns task contains the form fields or error
+     */
+    getPageAnnoWidgets: (doc: PdfDocumentObject, page: PdfPageObject) => PdfTask<PdfWidgetAnnoObject[]>;
+    /**
+     * Extract widget additional JavaScript actions for a page without executing them.
+     * @param doc - pdf document
+     * @param page - pdf page
+     * @returns task containing page widget JavaScript actions
+     */
+    getPageWidgetJavaScriptActions: (doc: PdfDocumentObject, page: PdfPageObject) => PdfTask<PdfWidgetJavaScriptActionObject[]>;
+    /**
+     * Regenerate appearance streams for specific widget annotations on a page.
+     * @param doc - pdf document
+     * @param page - pdf page
+     * @param annotationIds - NM values of the annotations to regenerate
+     * @returns task indicating whether any appearances were regenerated
+     */
+    regenerateWidgetAppearances: (doc: PdfDocumentObject, page: PdfPageObject, annotationIds: string[]) => PdfTask<boolean>;
     /**
      * Create a annotation on specified page
      * @param doc - pdf document
@@ -2953,6 +3155,35 @@ export interface PdfEngine<T = Blob> {
      * @param text - text value
      */
     setFormFieldValue: (doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfWidgetAnnoObject, value: FormFieldValue) => PdfTask<boolean>;
+    /**
+     * Restore a widget annotation to the full field state described by `field`.
+     * Unlike `setFormFieldValue`, this accepts a complete `PdfWidgetAnnoField`
+     * snapshot and applies all writable state in a single call.
+     * @param doc - pdf document
+     * @param page - pdf page
+     * @param annotation - pdf widget annotation
+     * @param field - the desired field state to apply
+     */
+    setFormFieldState: (doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfWidgetAnnoObject, field: PdfWidgetAnnoField) => PdfTask<boolean>;
+    /**
+     * Rename the logical form field associated with a widget annotation.
+     * This updates the field dictionary rather than patching only a single widget snapshot.
+     * @param doc - pdf document
+     * @param page - pdf page containing the widget annotation
+     * @param annotation - pdf widget annotation
+     * @param name - the desired partial field name (/T)
+     */
+    renameWidgetField: (doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfWidgetAnnoObject, name: string) => PdfTask<boolean>;
+    /**
+     * Attach the source widget's logical field to the target widget's logical field.
+     * This is a structural field operation and may merge multiple widget kids under one parent.
+     * @param doc - pdf document
+     * @param sourcePage - page containing the source widget annotation
+     * @param sourceAnnotation - widget whose field should be shared into the target field
+     * @param targetPage - page containing the target widget annotation
+     * @param targetAnnotation - widget whose logical field should be reused
+     */
+    shareWidgetField: (doc: PdfDocumentObject, sourcePage: PdfPageObject, sourceAnnotation: PdfWidgetAnnoObject, targetPage: PdfPageObject, targetAnnotation: PdfWidgetAnnoObject) => PdfTask<boolean>;
     /**
      * Flatten annotations and form fields into the page contents.
      * @param doc - pdf document
@@ -3171,7 +3402,14 @@ export interface IPdfiumExecutor {
     addAttachment(doc: PdfDocumentObject, params: PdfAddAttachmentParams): PdfTask<boolean>;
     removeAttachment(doc: PdfDocumentObject, attachment: PdfAttachmentObject): PdfTask<boolean>;
     readAttachmentContent(doc: PdfDocumentObject, attachment: PdfAttachmentObject): PdfTask<ArrayBuffer>;
+    getDocumentJavaScriptActions(doc: PdfDocumentObject): PdfTask<PdfDocumentJavaScriptActionObject[]>;
+    getPageAnnoWidgets(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfWidgetAnnoObject[]>;
+    getPageWidgetJavaScriptActions(doc: PdfDocumentObject, page: PdfPageObject): PdfTask<PdfWidgetJavaScriptActionObject[]>;
+    regenerateWidgetAppearances(doc: PdfDocumentObject, page: PdfPageObject, annotationIds: string[]): PdfTask<boolean>;
     setFormFieldValue(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfWidgetAnnoObject, value: FormFieldValue): PdfTask<boolean>;
+    setFormFieldState(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfWidgetAnnoObject, field: PdfWidgetAnnoField): PdfTask<boolean>;
+    renameWidgetField(doc: PdfDocumentObject, page: PdfPageObject, annotation: PdfWidgetAnnoObject, name: string): PdfTask<boolean>;
+    shareWidgetField(doc: PdfDocumentObject, sourcePage: PdfPageObject, sourceAnnotation: PdfWidgetAnnoObject, targetPage: PdfPageObject, targetAnnotation: PdfWidgetAnnoObject): PdfTask<boolean>;
     flattenPage(doc: PdfDocumentObject, page: PdfPageObject, options?: PdfFlattenPageOptions): PdfTask<PdfPageFlattenResult>;
     extractPages(doc: PdfDocumentObject, pageIndexes: number[]): PdfTask<ArrayBuffer>;
     extractText(doc: PdfDocumentObject, pageIndexes: number[]): PdfTask<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embedpdf/models",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "private": false,
   "description": "Shared type definitions, data models, and utility helpers (geometry, tasks, logging, PDF primitives) that underpin every package in the EmbedPDF ecosystem.",
   "type": "module",