# @embedpdf/react — ./form AuthorableFormKind [TypeAliasDeclaration] (from packages/plugin/form/src/tools/definitions.ts): export type AuthorableFormKind = Exclude; Box [InterfaceDeclaration] (from packages/plugin/form/src/model.ts): export interface Box{ readonly x: number; readonly y: number; readonly width: number; readonly height: number; } FORM_DEFAULTS [VariableDeclaration] (from packages/plugin/form/src/contract.ts): FORM_DEFAULTS: FormSettings ={ validation: 'scripts', focus:{ color: null} , fields:{ border: null, background: 'rgb(255 255 255 / 0.92)', color: '#1f2a44'} , fillable: true, } FORM_TOOLS [VariableDeclaration] (from packages/plugin/form/src/tools/definitions.ts): FORM_TOOLS: readonly FormToolDefinition[] = [{ id: 'form-text', fieldKind: 'text', visualKind: 'widget-text', clickCreate:{ width: 160, height: 24} , upright: true, defaults:{ ...FIELD_CHROME, fontSize: 12} , cursor: 'crosshair', } , { id: 'form-checkbox', fieldKind: 'checkbox', visualKind: 'widget-toggle', clickCreate:{ width: 18, height: 18} , upright: true, defaults: FIELD_CHROME, cursor: 'crosshair', } , { id: 'form-radio', fieldKind: 'radio', visualKind: 'widget-radio', clickCreate:{ width: 18, height: 18} , upright: true, defaults: FIELD_CHROME, cursor: 'crosshair', } , { id: 'form-combobox', fieldKind: 'combobox', visualKind: 'widget-choice', clickCreate:{ width: 140, height: 24} , upright: true, defaults:{ ...FIELD_CHROME, fontSize: 12} , cursor: 'crosshair', } , { id: 'form-listbox', fieldKind: 'listbox', visualKind: 'widget-choice', clickCreate:{ width: 140, height: 72} , upright: true, defaults:{ ...FIELD_CHROME, fontSize: 12} , cursor: 'crosshair', } , { id: 'form-button', fieldKind: 'pushbutton', visualKind: 'widget-button', clickCreate:{ width: 100, height: 28} , upright: true, defaults:{ ...FIELD_CHROME, interiorColor: '#e5e7eb', fontSize: 12} , cursor: 'crosshair', } , { id: 'form-signature', fieldKind: 'signature', visualKind: 'widget-box', clickCreate:{ width: 160, height: 48} , upright: true, defaults: FIELD_CHROME, cursor: 'crosshair', } , ] FORM_TOOL_BY_ID [VariableDeclaration] (from packages/plugin/form/src/tools/definitions.ts): FORM_TOOL_BY_ID: ReadonlyMap = new Map( FORM_TOOLS.map((tool) => [tool.id, tool]), ) FillableFields [TypeAliasDeclaration] (from packages/plugin/form/src/contract.ts): export type FillableFields = boolean | readonly FormFieldKind[]; FormBundle [InterfaceDeclaration] (from packages/engine/core/src/transfer/FormBundle.ts): export interface FormBundle{ readonly format: 'embedpdf/form'; readonly version: 1; readonly pages: readonly BundlePage[]; readonly fields: readonly FormBundleField[]; readonly widgets: readonly FormBundleWidget[]; readonly calculationOrder: readonly FormFieldRef[]; readonly resources: Readonly>; } FormCapability [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormCapability extends SettingsApi{ getSnapshot(): FormSnapshot | null; getStatus(): ResourceStatus; getFormKind(): FormKind; list(filter?: FormFilter): readonly FormField[]; get(ref: FormFieldRef): FormField | null; getFieldForWidget(widget: WidgetAddress): FormField | null; getWidget(widget: WidgetAddress): WidgetAnnotation | null; getWidgets(ref: FormFieldRef): readonly WidgetAnnotation[]; getValue(ref: FormFieldRef): FormFieldValue | null; listWidgets(page: PageRef | number): readonly FormWidgetItem[]; getWidgetAt(page: PageRef | number, point:{ x: number; y: number} ): WidgetHit | null; getSelectedField(): FormField | null; getFocusedField(): FormField | null; getFieldSettings(field: FormFieldRef): FormFieldSettings | null; validate(): FormValidation; exportValues(): Readonly>; focus(ref: FormFieldRef, options?: FormFocusOptions): boolean; focusNext(options?: FormFocusNextOptions): boolean; setValue( ref: FormFieldRef, value: FormFieldValue, options?: OperationOptions, ): Promise; setValues( entries: readonly{ readonly ref: FormFieldRef; readonly value: FormFieldValue} [], options?: OperationOptions, ): Promise>; importValues( values: Readonly>, options?: OperationOptions, ): Promise>; reset(refs?: readonly FormFieldRef[], options?: OperationOptions): Promise; activateWidget( widget: AnnotationRef, options?: OperationOptions, ): Promise; export(selection?: FormExportSelection, options?: OperationOptions): Promise; import( bundle: FormBundle, options?: FormImportOptions & OperationOptions & HistoryOptions, ): Promise; refresh(options?: OperationOptions): Promise; create(draft: FormFieldDraft, options?: OperationOptions): Promise; addWidget( ref: FormFieldRef, placement?: Partial, options?: OperationOptions, ): Promise; duplicate( fields: readonly FormFieldRef[], options?: FormDuplicateOptions & OperationOptions, ): Promise; duplicateWidgets( widgets: readonly AnnotationRef[], options?: FormDuplicateOptions & OperationOptions, ): Promise; update( ref: FormFieldRef, patch: FormFieldPatch, options?: OperationOptions, ): Promise; delete(ref: FormFieldRef, options?: OperationOptions): Promise; removeWidget( ref: FormFieldRef, widget: AnnotationRef, options?: OperationOptions, ): Promise; updateWidget( widget: AnnotationRef, patch: WidgetPatch, options?: OperationOptions, ): Promise<{ readonly widget: WidgetAnnotation} >; deleteWidget( widget: AnnotationRef, options?: OperationOptions, ): Promise<{ readonly field: FormField | null} >; reorderCalculations( fields: FormFieldRef[], position: FieldPosition, options?: OperationOptions, ): Promise<{ readonly calculationOrder: readonly FormFieldRef[]} >; repair(options?: FormRepairOptions & OperationOptions): Promise; canRead(): boolean; canFill(field: FormFieldRef): boolean; canDesign(): boolean; canRestoreAttribution(): boolean; canWriteScripts(): boolean; readonly onValueChanged: EventHook; readonly onFieldCreated: EventHook; readonly onFieldUpdated: EventHook; readonly onFieldDeleted: EventHook; readonly onValidationRejected: EventHook; readonly onResynced: EventHook; readonly onFocusChanged: EventHook; } FormCommitResult [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormCommitResult{ readonly status: FormCommitStatus; readonly scripted: boolean; readonly uiEffects: FormUiEffect[]; readonly diagnostics: ScriptDiagnostic[]; readonly error?: ScriptExecutionError; } FormCommitStatus [TypeAliasDeclaration] (from packages/plugin/form/src/contract.ts): export type FormCommitStatus = 'applied' | 'unchanged' | 'rejected' | 'failed'; FormConfig [TypeAliasDeclaration] (from packages/plugin/form/src/contract.ts): export type FormConfig = DeepPartial; FormDuplicateOptions [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormDuplicateOptions{ readonly page?: PageRef | number; readonly offset?:{ readonly x: number; readonly y: number} ; readonly values?: boolean; } FormDuplicateResult [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormDuplicateResult{ readonly fields: readonly FormField[]; readonly widgets: readonly WidgetAnnotation[]; readonly dropped: readonly FormImportDrop[]; } FormExportSelection [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormExportSelection{ readonly fields?: readonly FormFieldRef[]; readonly pages?: readonly (PageRef | number)[]; } FormField [TypeAliasDeclaration] (from packages/engine/core/src/forms/field.ts): export type FormField = | TextField | CheckboxField | RadioField | ComboBoxField | ListBoxField | PushButtonField | SignatureField | UnknownField; FormFieldCreatedEvent [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormFieldCreatedEvent{ readonly field: FormField; readonly origin: EventOrigin; } FormFieldDeletedEvent [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormFieldDeletedEvent{ readonly ref: FormFieldRef; readonly origin: EventOrigin; } FormFieldDraft [TypeAliasDeclaration] (from packages/engine/core/src/forms/draft.ts): export type FormFieldDraft = | TextFieldDraft | CheckboxFieldDraft | RadioFieldDraft | ComboBoxFieldDraft | ListBoxFieldDraft | PushButtonFieldDraft | SignatureFieldDraft; FormFieldFlagSetting [TypeAliasDeclaration] (from packages/plugin/form/src/contract.ts): export type FormFieldFlagSetting = | 'required' | 'readOnly' | 'noExport' | 'multiline' | 'password' | 'comb' | 'radiosInUnison' | 'noToggleToOff' | 'edit' | 'multiSelect'; FormFieldKind [TypeAliasDeclaration] (from packages/engine/core/src/forms/field.ts): export type FormFieldKind = | 'text' | 'checkbox' | 'radio' | 'combobox' | 'listbox' | 'pushbutton' | 'signature' | 'unknown'; FormFieldPatch [TypeAliasDeclaration] (from packages/engine/core/src/forms/patch.ts): export type FormFieldPatch = | TextFieldPatch | CheckboxFieldPatch | RadioFieldPatch | ComboBoxFieldPatch | ListBoxFieldPatch | PushButtonFieldPatch | SignatureFieldPatch; FormFieldRef [TypeAliasDeclaration] (from packages/engine/core/src/identity/FormFieldRef.ts): export type FormFieldRef = |{ kind: 'objectNumber'; objectNumber: number} |{ kind: 'fqn'; name: string} ; FormFieldResult [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormFieldResult{ readonly field: FormField; } FormFieldSetting [TypeAliasDeclaration] (from packages/plugin/form/src/contract.ts): export type FormFieldSetting = |{ readonly key: 'name' | 'alternateName'; readonly control: 'text'; readonly label: string; readonly labelKey: string; } |{ readonly key: FormFieldFlagSetting; readonly control: 'flag'; readonly label: string; readonly labelKey: string; } |{ readonly key: 'maxLength'; readonly control: 'number'; readonly label: string; readonly labelKey: string; readonly min: number; } |{ readonly key: 'defaultValue'; readonly control: 'text'; readonly label: string; readonly labelKey: string; } |{ readonly key: 'defaultValue'; readonly control: 'choice'; readonly label: string; readonly labelKey: string; readonly options: readonly string[]; readonly free: boolean; } |{ readonly key: 'defaultValue'; readonly control: 'choices'; readonly label: string; readonly labelKey: string; readonly options: readonly string[]; } |{ readonly key: 'options'; readonly control: 'options'; readonly label: string; readonly labelKey: string; } ; FormFieldSettings [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormFieldSettings{ readonly properties: readonly FormFieldSetting[]; readonly values: Readonly>; } FormFieldUpdatedEvent [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormFieldUpdatedEvent{ readonly field: FormField; readonly origin: EventOrigin; } FormFieldValue [TypeAliasDeclaration] (from packages/engine/core/src/forms/value.ts): export type FormFieldValue = |{ value: string | null} |{ checked: boolean} |{ selectedValues: string[]} ; FormFilter [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormFilter{ readonly kind?: FormFieldKind; readonly page?: PageRef | number; readonly name?: string; } FormFocusChangedEvent [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormFocusChangedEvent{ readonly field: FormField | null; readonly widget: AnnotationRef | null; } FormFocusNextOptions [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormFocusNextOptions{ from?: FormFieldRef; backward?: boolean; empty?: boolean; wrap?: boolean; } FormFocusOptions [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormFocusOptions{ widget?: WidgetAddress; select?: boolean; } FormImportDrop [InterfaceDeclaration] (from packages/engine/core/src/transfer/formImport.ts): export interface FormImportDrop{ readonly ref: FormFieldRef | null; readonly widget?: AnnotationRef; readonly field?: string; readonly reason: FormImportDropReason; } FormImportDropReason [TypeAliasDeclaration] (from packages/engine/core/src/transfer/formImport.ts): export type FormImportDropReason = | 'name-conflict' | 'no-field' | 'unsupported-kind' | 'script-not-allowed' | 'unsupported-action'; FormImportOptions [InterfaceDeclaration] (from packages/engine/core/src/transfer/formImport.ts): export interface FormImportOptions extends WriteOptions{ readonly pages?: BundleImportPages; readonly attribution?: 'restore' | 'stamp'; readonly values?: boolean; } FormImportResult [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormImportResult{ readonly fields: readonly FormField[]; readonly refMap: ReadonlyArray<{ readonly from: FormFieldRef; readonly to: FormFieldRef} >; readonly dropped: readonly FormImportDrop[]; } FormKind [TypeAliasDeclaration] (from packages/engine/core/src/forms/snapshot.ts): export type FormKind = 'none' | 'acroform' | 'xfa'; FormLayer [FunctionDeclaration]: export function FormLayer(){ const page = usePage(); const form = useCapability(FormHostToken); const colors = useFormColors(); const active = useSelector(InteractionToken, (interaction) => interaction.activeToolEnables('form-fill'), ); usePaintsPagePart(page.ref, 'formFields'); useEffect(() =>{ void form.ensureLoaded(page.ref); } , [form, page.ref]); const items = useSelector( FormHostToken, (capability) => capability.listWidgets(page.ref), shallowArray, ); return (
{ (active ? items : []).map((item) =>{ const key = `${ item.key} :${ item.annotObjectNumber} `; switch (item.control){ case 'text': return ; case 'toggle': return ; case 'choice': return item.kind === 'list' ? ( ) : ( ); case 'button': return ; case 'signature': return ; } } )}
); } FormPlainValue [TypeAliasDeclaration] (from packages/plugin/form/src/contract.ts): export type FormPlainValue = string | boolean | readonly string[] | null; FormRepairOptions [InterfaceDeclaration] (from packages/engine/core/src/engine/DocumentFormsService.ts): export interface FormRepairOptions extends WriteOptions{ bakeAppearances?: boolean; } FormRepairResult [InterfaceDeclaration] (from packages/engine/core/src/mutation/FormMutationResults.ts): export interface FormRepairResult{ acroformCreated: boolean; fieldsLinked: number; widgetsLinked: number; fieldsUnrepairable: number; appearancesBaked: number; needsAppearancesCleared: boolean; meta: MutationMeta; } FormResetResult [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormResetResult{ readonly fields: readonly FormField[]; } FormResyncedEvent [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormResyncedEvent{ readonly snapshot: FormSnapshot; } FormScriptingController [ClassDeclaration] (from packages/plugin/form/src/scripting/controller.ts): export class FormScriptingController{ private disposed = false; private readonly transactionBudget: ScriptBudget | undefined; constructor(private readonly options: FormScriptingControllerOptions){ this.transactionBudget = options.budget; } destroy(): void{ this.disposed = true; } transaction(body: (scripts: FormScripts) => Promise): Promise{ if (this.disposed) return Promise.reject(new Error('Form scripting controller is disposed')); return this.options.transaction((txn) => body({ commit: (form, ref, value) => this.run(txn, form, ref, value), activate: (form, ref, action) => this.run(txn, form, ref, undefined, action), recalculate: (form) => this.run(txn, form, undefined), } ), ); } async warm(form: FormSnapshot): Promise{ if (this.disposed) return; const budget = this.transactionBudget ?? DEFAULT_SCRIPT_BUDGET; await this.options.transaction((txn) => txn.run( '', { fields: scriptFieldsFromSnapshot(form), event:{ kind: 'name-tree-boot'} } , budget, ), ); } commit(form: FormSnapshot, ref: FormFieldRef, value: FormFieldValue): Promise{ return this.transaction((scripts) => scripts.commit(form, ref, value)); } activate( form: FormSnapshot, ref: FormFieldRef, action: PdfActionTree, ): Promise{ return this.transaction((scripts) => scripts.activate(form, ref, action)); } recalculate(form: FormSnapshot): Promise{ return this.transaction((scripts) => scripts.recalculate(form)); } private async run( txn: ScriptTransaction, snapshot: FormSnapshot, refInput: FormFieldRef | undefined, proposed?: FormFieldValue, activation?: PdfActionTree, ): Promise{ const asked = refInput ?? snapshot.calculationOrder.find( (candidate): candidate is FormFieldRef => candidate !== null && snapshotField(snapshot, candidate) !== undefined, ) ?? snapshot.fields[0]?.ref; if (!asked){ return{ status: 'accepted', effects: [], bootEffects: [], uiEffects: [], diagnostics: []} ; } const target = snapshotField(snapshot, asked); if (!target){ return this.failed([], [], scriptError(`Form field '${ refKey(asked)} ' no longer exists`)); } const ref = target.ref; const original = scriptFieldsFromSnapshot(snapshot); const overlay: Overlay ={ original, fields: cloneFields(original), resetKeys: new Set(), appearances: new Map(), } ; const targetInput = fieldByRef(overlay.fields, ref); if (!targetInput){ return this.failed([], [], scriptError(`Form field '${ refKey(ref)} ' has no script view`)); } const hasProposedValue = proposed !== undefined; let proposedValue: ScriptValue = cloneValue(targetInput.value); if (proposed){ try{ proposedValue = scriptValueFromFormValue(targetInput, proposed); } catch (error){ return this.failed( [], [], scriptError(error instanceof Error ? error.message : String(error)), ); } } const uiEffects: FormUiEffect[] = []; const diagnostics: ScriptDiagnostic[] = []; const meta = this.options.document(); const pageNumber = pageNumberFor(meta, target); const budget = this.transactionBudget ?? DEFAULT_SCRIPT_BUDGET; let executionMs = 0; let aggregateOutputSize = 0; const consume = ( output: ScriptOutput, phase: FormUiEffect['phase'], ): ScriptExecutionError | null =>{ aggregateOutputSize += utf8Length(JSON.stringify(output)); uiEffects.push(...output.uiEffects.map((effect) => ({ ...effect, phase} ))); diagnostics.push(...output.diagnostics); if (aggregateOutputSize > budget.maxOutputBytes){ return{ kind: 'budget', message: `Form script transaction output exceeded ${ budget.maxOutputBytes} bytes`, } ; } return output.error ?? null; } ; const remainingBudget = (): ScriptBudget | null =>{ const remaining = budget.maxExecutionMs - executionMs; return remaining <= 0 ? null :{ ...budget, maxExecutionMs: remaining} ; } ; const world = ( fields: ScriptFieldInput[], event: ScriptWorldInput['event'], ): ScriptWorldInput => ({ fields, pageNumber, event, } ); const run = async ( source: string, input: ScriptWorldInput, ): Promise<{ output?: ScriptOutput; error?: ScriptExecutionError} > =>{ const remaining = remainingBudget(); if (!remaining){ return{ error:{ kind: 'budget', message: 'Form script transaction timed out'} } ; } let output: ScriptOutput; try{ const startedAt = Date.now(); output = await txn.run(source, input, remaining); executionMs += Date.now() - startedAt; } catch (error){ return{ error: scriptError(error instanceof Error ? error.message : String(error)), } ; } const error = consume(output, 'user'); return error ?{ error} :{ output} ; } ; { let boot: ScriptOutput | null = null; try{ boot = await txn.boot(world(overlay.fields, { kind: 'name-tree-boot'} ), budget); } catch (error){ diagnostics.push({ code: 'script-error', message: `Document boot script failed (continuing without it): ${ error instanceof Error ? error.message : String(error)} `, } ); } if (boot){ const bootError = consume(boot, 'boot'); if (!bootError) applyEffects(overlay, boot.formEffects); else{ diagnostics.push({ code: 'script-error', message: `Document boot script failed (continuing without it): ${ bootError.message} `, } ); } } } const bootEffects = canonicalEffects(overlay); if (activation){ let program: string; try{ program = javaScriptProgramFromActionTree(activation); } catch (error){ return this.failed( uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)), ); } if (program){ const activated = await run( program, world(overlay.fields, { kind: 'widget-activate', target: ref, source: ref, value: targetInput.value, } ), ); if (activated.error) return this.failed(uiEffects, diagnostics, activated.error); applyEffects(overlay, activated.output!.formEffects); } } if (!activation && hasProposedValue && target.actions?.keystroke && target.kind === 'text'){ let program: string; try{ program = javaScriptProgramFromActionTree(target.actions.keystroke); } catch (error){ return this.failed( uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)), ); } if (program){ const oldValue = String(targetInput.value ?? ''); const typing = await run( program, world(overlay.fields, { kind: 'field-keystroke', target: ref, source: ref, value: oldValue, change: String(proposedValue ?? ''), selStart: 0, selEnd: oldValue.length, willCommit: false, } ), ); if (typing.error && typing.error.kind !== 'exception'){ return this.failed(uiEffects, diagnostics, typing.error); } if (typing.error){ diagnostics.push({ code: 'script-error', message: `Keystroke script failed (kept the typed value): ${ typing.error.message} `, } ); } else{ if (!typing.output!.event.rc){ return this.rejected(bootEffects, uiEffects, diagnostics); } applyEffects(overlay, typing.output!.formEffects); const event = typing.output!.event; const base = String(event.value ?? ''); proposedValue = base.slice(0, event.selStart) + event.change + base.slice(Math.max(event.selStart, event.selEnd)); } const commit = await run( program, world(overlay.fields, { kind: 'field-keystroke', target: ref, source: ref, value: proposedValue, change: '', selStart: 0, selEnd: 0, willCommit: true, } ), ); if (commit.error && commit.error.kind !== 'exception'){ return this.failed(uiEffects, diagnostics, commit.error); } if (commit.error){ diagnostics.push({ code: 'script-error', message: `Keystroke commit script failed (kept the typed value): ${ commit.error.message} `, } ); } else{ if (!commit.output!.event.rc){ return this.rejected(bootEffects, uiEffects, diagnostics); } applyEffects(overlay, commit.output!.formEffects); proposedValue = cloneValue(commit.output!.event.value); } } } if (!activation && hasProposedValue){ targetInput.value = cloneValue(proposedValue); overlay.resetKeys.delete(refKey(ref)); } if (!activation && hasProposedValue && target.actions?.validate){ let program: string; try{ program = javaScriptProgramFromActionTree(target.actions.validate); } catch (error){ return this.failed( uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)), ); } if (program){ const validation = await run( program, world(overlay.fields, { kind: 'field-validate', target: ref, source: ref, value: proposedValue, willCommit: true, } ), ); if (validation.error && validation.error.kind !== 'exception'){ return this.failed(uiEffects, diagnostics, validation.error); } if (validation.error){ diagnostics.push({ code: 'script-error', message: `Validate script failed (accepted the value): ${ validation.error.message} `, } ); } else{ if (!validation.output!.event.rc){ return this.rejected(bootEffects, uiEffects, diagnostics); } targetInput.value = cloneValue(validation.output!.event.value); applyEffects(overlay, validation.output!.formEffects); } } } const formatRefs: FormFieldRef[] = !activation && hasProposedValue ? [ref] : []; for (const calculationRef of activation ? [] : snapshot.calculationOrder){ if (!calculationRef) continue; const calculated = snapshotField(snapshot, calculationRef); const tree = calculated?.actions?.calculate; if (!calculated || !tree) continue; let program: string; try{ program = javaScriptProgramFromActionTree(tree); } catch (error){ return this.failed( uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)), ); } const calculatedInput = fieldByRef(overlay.fields, calculationRef); if (program && calculatedInput){ const calculation = await run( program, world(overlay.fields, { kind: 'field-calculate', target: calculationRef, ...(hasProposedValue ?{ source: ref} :{ } ), value: calculatedInput.value, } ), ); if (calculation.error && calculation.error.kind !== 'exception'){ return this.failed(uiEffects, diagnostics, calculation.error); } if (calculation.error){ diagnostics.push({ code: 'script-error', message: `Calculate script failed (field left unchanged): ${ calculation.error.message} `, } ); } else{ applyEffects(overlay, calculation.output!.formEffects); } } if (!formatRefs.some((candidate) => sameRef(candidate, calculationRef))){ formatRefs.push(calculationRef); } } for (const formatRef of formatRefs){ const field = snapshotField(snapshot, formatRef); const tree = field?.actions?.format; const overlayField = fieldByRef(overlay.fields, formatRef); if (!field || !tree || !overlayField) continue; let program: string; try{ program = javaScriptProgramFromActionTree(tree); } catch (error){ return this.failed( uiEffects, diagnostics, scriptError(error instanceof Error ? error.message : String(error)), ); } if (!program) continue; const format = await run( program, world(overlay.fields, { kind: 'field-format', target: formatRef, ...(hasProposedValue ?{ source: ref} :{ } ), value: overlayField.value, } ), ); if (format.error && format.error.kind !== 'exception'){ return this.failed(uiEffects, diagnostics, format.error); } if (format.error){ diagnostics.push({ code: 'script-error', message: `Format script failed (kept the raw value): ${ format.error.message} `, } ); continue; } applyEffects(overlay, format.output!.formEffects); } const effects = canonicalEffects(overlay); if (effects.length + uiEffects.length > budget.maxEffects){ return this.failed(uiEffects, diagnostics, { kind: 'budget', message: `Form script transaction exceeded ${ budget.maxEffects} effects`, } ); } return{ status: 'accepted', effects, bootEffects, uiEffects, diagnostics} ; } private failed( uiEffects: FormUiEffect[], diagnostics: ScriptDiagnostic[], error: ScriptExecutionError, ): FormScriptResult{ return{ status: 'failed', effects: [], bootEffects: [], uiEffects, diagnostics, error} ; } private rejected( bootEffects: FormEffect[], uiEffects: FormUiEffect[], diagnostics: ScriptDiagnostic[], ): FormScriptResult{ return{ status: 'rejected', effects: [], bootEffects, uiEffects, diagnostics} ; } } FormSetValueResult [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormSetValueResult{ readonly field: FormField; readonly status: FormSetValueStatus; } FormSetValueStatus [TypeAliasDeclaration] (from packages/plugin/form/src/contract.ts): export type FormSetValueStatus = 'applied' | 'unchanged' | 'rejected'; FormSettings [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormSettings{ readonly validation: 'scripts' | 'none'; readonly focus:{ readonly color: string | null; } ; readonly fields:{ readonly border: string | null; readonly background: string; readonly color: string; } ; readonly fillable: FillableFields; } FormSnapshot [InterfaceDeclaration] (from packages/engine/core/src/forms/snapshot.ts): export interface FormSnapshot{ formKind: FormKind; needsAppearances: boolean; fields: FormField[]; widgets: WidgetAnnotation[]; calculationOrder: Array; } FormState [InterfaceDeclaration] (from packages/plugin/form/src/state.ts): export interface FormState{ readonly fields: readonly FormField[]; readonly status: ResourceStatus; readonly formKind: FormKind; readonly selectedField: FormField | null; readonly focusedField: FormField | null; } FormToken [VariableDeclaration] (from packages/plugin/form/src/token.ts): FormToken = createCapabilityToken('form', { hint: `add formPlugin() from '@embedpdf/plugin-form' to your plugins list`, promises:{ setValue: true, setValues: true, importValues: true, reset: true, activateWidget: true, export: true, import: true, refresh: true, create: true, addWidget: true, duplicate: true, duplicateWidgets: true, update: true, delete: true, removeWidget: true, updateWidget: true, deleteWidget: true, reorderCalculations: true, repair: true, } , } ) FormToolDefinition [InterfaceDeclaration] (from packages/plugin/form/src/tools/definitions.ts): export interface FormToolDefinition{ id: string; fieldKind: AuthorableFormKind; visualKind: | 'widget-text' | 'widget-choice' | 'widget-button' | 'widget-toggle' | 'widget-radio' | 'widget-box'; clickCreate: Extract; upright: boolean; defaults: WidgetAppearance; cursor: string; } FormTransfer [VariableDeclaration] (from packages/engine/core/src/transfer/FormTransfer.ts): FormTransfer = bundleCodec({ kind: 'form', keys: FORM_BUNDLE_KEYS, assertManifest: assertFormBundleManifest, } ) FormUiEffect [TypeAliasDeclaration] (from packages/plugin/form/src/contract.ts): export type FormUiEffect = ScriptUiEffect &{ phase: 'boot' | 'user'; origin?: ActionOrigin; } ; FormValidation [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormValidation{ readonly valid: boolean; readonly missing: readonly FormField[]; } FormValidationRejectedEvent [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormValidationRejectedEvent{ readonly field: FormField; readonly issues: readonly ScriptDiagnostic[]; } FormValueChangedEvent [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormValueChangedEvent{ readonly field: FormField; readonly origin: EventOrigin; } FormWidgetAddResult [InterfaceDeclaration] (from packages/plugin/form/src/contract.ts): export interface FormWidgetAddResult{ readonly field: FormField; readonly widget: WidgetAnnotation; } FormWidgetItem [TypeAliasDeclaration] (from packages/plugin/form/src/read/fill-items.ts): export type FormWidgetItem = FormWidgetItemBase & ( |{ control: 'text'; value: string; multiline: boolean; password: boolean; maxLength: number | null; comb: boolean; } |{ control: 'toggle'; kind: 'checkbox' | 'radio'; checked: boolean; exportValue: string; } |{ control: 'choice'; kind: 'combo' | 'list'; edit: boolean; multi: boolean; options: FormFieldOption[]; selected: string[]; } |{ control: 'button'} |{ control: 'signature'; signed: boolean} ); FormWidgetLook [InterfaceDeclaration] (from packages/plugin/form/src/model.ts): export interface FormWidgetLook{ readonly border: string | null; readonly borderWidth: number; readonly borderStyle: 'solid' | 'dashed' | 'beveled' | 'inset' | 'underline'; readonly background: string | null; readonly color: string | null; readonly fontFamily: string | null; readonly fontSize: number | null; readonly textAlign: 'left' | 'center' | 'right'; } WidgetActivationResult [TypeAliasDeclaration] (from packages/plugin/form/src/contract.ts): export type WidgetActivationResult = |{ status: 'form'; result: FormCommitResult} |{ status: 'dispatched'; result: ActionTriggerResult} ; WidgetAddress [TypeAliasDeclaration] (from packages/plugin/form/src/contract.ts): export type WidgetAddress = AnnotationRef | FormWidget; WidgetAnnotation [TypeAliasDeclaration] (from packages/engine/core/src/annotation/kinds/widget/index.ts): export type WidgetAnnotation = ReadOf< typeof WidgetDeclaration, C >; WidgetHit [InterfaceDeclaration] (from packages/plugin/form/src/model.ts): export interface WidgetHit extends WidgetPlace{ readonly annotObjectNumber: number; readonly field: FormField; } WidgetPlace [InterfaceDeclaration] (from packages/plugin/form/src/model.ts): export interface WidgetPlace{ readonly box: Box; readonly rotation: 0 | 90 | 180 | 270; readonly rect: Box; } createFormScriptingController [FunctionDeclaration] (from packages/plugin/form/src/scripting/controller.ts): export function createFormScriptingController( options: FormScriptingControllerOptions, ): FormScriptingController{ return new FormScriptingController(options); } formPlugin [VariableDeclaration] (from packages/plugin/form/src/form.plugin.ts): formPlugin = (config?: FormConfig) => definePlugin({ id: 'form', token: FormToken, scope: 'document', requires: [InteractionToken], optional: [AnnotationToken, ActionsToken, RenderToken, FontsToken], state: initialFormModel, settings:{ defaults: FORM_DEFAULTS, registered: config} , create: createFormController, } ) formState [VariableDeclaration] (from packages/plugin/form/src/state.ts): formState = defineState(FormToken, { read: (form): FormState => ({ fields: form.list(), status: form.getStatus(), formKind: form.getFormKind(), selectedField: form.getSelectedField(), focusedField: form.getFocusedField(), } ), empty:{ fields: NO_FIELDS, status: 'idle', formKind: 'none', selectedField: null, focusedField: null, } , } ) toFieldRef [FunctionDeclaration] (from packages/engine/core/src/identity/FormFieldRef.ts): export function toFieldRef(name: string): FormFieldRef{ return{ kind: 'fqn', name} ; } useForm [FunctionDeclaration]: export function useForm(): FormCapability{ return useCapability(FormToken); } useFormEvent [FunctionDeclaration]: export function useFormEvent( select: (form: FormCapability) => EventHook, handler: (event: T) => void, ): void{ useCapabilityEvent(FormToken, select, handler); } useFormSettings [VariableDeclaration]: useFormSettings = settingsHook(FormToken) useFormState [VariableDeclaration]: useFormState = stateHook(formState) useFormValue [FunctionDeclaration]: export function useFormValue(ref: FormFieldRef): FormFieldValue | null{ const scoped = useDocumentScope(); const key = ref.kind === 'fqn' ? `n:${ ref.name} ` : `o:${ ref.objectNumber} `; const stable = useMemo(() => ref, [key]); return useKernelValue( (kernel) => kernel.tryCapability(FormToken, scoped ?? undefined)?.getValue(stable) ?? null, ); }