From 69fc91bfbeeabea37b1ccff06e366ba63f35dd80 Mon Sep 17 00:00:00 2001 From: Luis Amorim Date: Mon, 9 Nov 2026 10:44:27 -0300 Subject: [PATCH 1/3] feat(forms): add generic form-field editing session Introduce createFormEditor on top of the #84 field/widget model, with optional overlay sync, selection, interactive placement, and silent page restore via moveObjectToPage. Signed-off-by: Luis Amorim --- src/components/PDFElements.vue | 46 + src/index.ts | 16 + src/types.ts | 11 + src/utils/formEditing.ts | 922 +++++++++++++++++++ tests/components/formEditing.overlay.spec.ts | 420 +++++++++ tests/utils/formEditing.spec.ts | 676 ++++++++++++++ 6 files changed, 2091 insertions(+) create mode 100644 src/utils/formEditing.ts create mode 100644 tests/components/formEditing.overlay.spec.ts create mode 100644 tests/utils/formEditing.spec.ts diff --git a/src/components/PDFElements.vue b/src/components/PDFElements.vue index 28e6a2e..753a8cc 100644 --- a/src/components/PDFElements.vue +++ b/src/components/PDFElements.vue @@ -1196,6 +1196,52 @@ export default defineComponent({ this.updateObjectInPage(docIndex, currentPageIndex, objectId, payload) }, + moveObjectToPage(docIndex, objectId, pageIndex, payload = {}) { + if (docIndex < 0 || docIndex >= this.pdfDocuments.length) return false + const doc = this.pdfDocuments[docIndex] + if (pageIndex < 0 || pageIndex >= doc.pages.length) return false + + const cacheKey = `${docIndex}-${objectId}` + let currentPageIndex = this.objectIndexCache[cacheKey] + if (currentPageIndex === undefined) { + currentPageIndex = findObjectPageIndex(doc, objectId) + if (currentPageIndex !== undefined) { + this.objectIndexCache[cacheKey] = currentPageIndex + } + } + if (currentPageIndex === undefined) return false + + const currentObjects = doc.allObjects[currentPageIndex] + const objectIndex = currentObjects?.findIndex((object) => object.id === objectId) ?? -1 + if (!currentObjects || objectIndex === -1) return false + + const currentObject = currentObjects[objectIndex] + const nextObject = { + ...currentObject, + ...payload, + id: objectId, + } + const { width: pageWidth, height: pageHeight } = this.getPageSize(docIndex, pageIndex) + if ( + nextObject.x < 0 + || nextObject.y < 0 + || nextObject.x + nextObject.width > pageWidth + || nextObject.y + nextObject.height > pageHeight + ) { + return false + } + + if (currentPageIndex === pageIndex) { + currentObjects.splice(objectIndex, 1, nextObject) + return true + } + + currentObjects.splice(objectIndex, 1) + doc.allObjects[pageIndex].push(nextObject) + this.objectIndexCache[cacheKey] = pageIndex + return true + }, + deleteObject(docIndex, objectId) { if (docIndex < 0 || docIndex >= this.pdfDocuments.length) return const doc = this.pdfDocuments[docIndex] diff --git a/src/index.ts b/src/index.ts index 33bd198..559ce01 100644 --- a/src/index.ts +++ b/src/index.ts @@ -22,12 +22,28 @@ export { serializeFormModel, validateFormModelRelationships, } from './utils/formModel' +export { + createFormEditor, + createFormEditorOverlayAdapter, +} from './utils/formEditing' export type { CreateFormFieldInput, CreateFormWidgetInput, FormModelRelationshipIssue, FormWidgetToElementOptions, } from './utils/formModel' +export type { + BeginPlaceWidgetInput, + CompleteWidgetPlacementInput, + CreateFormEditorOptions, + FormEditorAddObjectResult, + FormEditorOverlayAdapter, + FormEditorSelection, + FormFieldUpdate, + FormWidgetUpdate, + PDFFormEditor, + PlaceFormWidgetOptions, +} from './utils/formEditing' export type { PDFDocumentEntry, PDFElementObject, diff --git a/src/types.ts b/src/types.ts index 9dbf5fc..ae36d2a 100644 --- a/src/types.ts +++ b/src/types.ts @@ -47,6 +47,17 @@ export interface PDFElementsPublicApi { addObjectToPage: (object: PDFElementObject, pageIndex?: number, docIndex?: number) => boolean getAllObjects: (docIndex?: number) => PDFElementObject[] updateObject: (docIndex: number, objectId: string, payload: Partial) => void + /** + * Moves an overlay object to another page in the same document without emitting + * `pdf-elements:delete-object`. Used for internal restoration (for example form + * editor spill rollback) so hosts do not treat the move as a user delete. + */ + moveObjectToPage: ( + docIndex: number, + objectId: string, + pageIndex: number, + payload?: Partial + ) => boolean deleteObject: (docIndex: number, objectId: string) => void duplicateObject: (docIndex: number, objectId: string) => void cancelAdding: () => void diff --git a/src/utils/formEditing.ts b/src/utils/formEditing.ts new file mode 100644 index 0000000..7480d7a --- /dev/null +++ b/src/utils/formEditing.ts @@ -0,0 +1,922 @@ +// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors +// SPDX-License-Identifier: AGPL-3.0-or-later + +import type { + PDFElementObject, + PDFElementsPublicApi, + PDFFormField, + PDFFormFieldId, + PDFFormFieldOption, + PDFFormFieldType, + PDFFormFieldValue, + PDFFormModel, + PDFFormWidget, + PDFFormWidgetId, +} from '../types' +import { + addWidgetToField, + createFormField, + createFormModel, + createFormWidgetId, + elementObjectToFormWidgetPlacement, + formWidgetToElementObject, + getFormFieldById, + getFormWidgetById, + getWidgetsForField, + parseFormModel, + serializeFormModel, + type CreateFormFieldInput, + type CreateFormWidgetInput, + type FormWidgetToElementOptions, +} from './formModel' + +/** + * Result of placing an overlay rectangle. + * Prefer returning the stored {@link PDFElementObject} so the editor can read the + * final id when the host regenerates ids on collision. + */ +export type FormEditorAddObjectResult = boolean | PDFElementObject + +/** + * Optional bridge to the generic overlay editor ({@link PDFElementsPublicApi}). + * Form editing keeps its own model; overlays stay optional visuals. + */ +export interface FormEditorOverlayAdapter { + /** + * Places an overlay object. Return the stored object (or at least `{ id }`) + * whenever the host may rewrite ids. `false` means placement failed. + * `true` is accepted only when the submitted id is known to have been kept. + */ + addObjectToPage: ( + object: PDFElementObject, + pageIndex?: number, + docIndex?: number + ) => FormEditorAddObjectResult + /** + * Optional existence check used to link a widget to an already-present overlay + * without inserting a duplicate rectangle. When `pageIndex` is provided, the + * object must exist on that page. + */ + hasObject?: (docIndex: number, objectId: string, pageIndex?: number) => boolean + /** + * Returns `false` when the host rejected the update (for example out of bounds). + * `void` / `undefined` means the host does not report success/failure. + */ + updateObject?: ( + docIndex: number, + objectId: string, + payload: Partial + ) => boolean | void + /** + * Preferred spill/page restore path. Must not emit a user-facing delete event. + * Falls back to delete+add only when absent (hosts must ignore deletes during + * {@link FormEditorOverlayAdapter.isInternalMutation}). + */ + moveObjectToPage?: ( + docIndex: number, + objectId: string, + pageIndex: number, + payload?: Partial + ) => boolean + deleteObject?: (docIndex: number, objectId: string) => void + startAddingElement?: (templateObject: PDFElementObject) => void + cancelAdding?: () => void + /** True while the adapter restores overlay state after a rejected update. */ + isInternalMutation?: () => boolean +} + +/** Logical selection: a field, optionally narrowed to one of its widgets. */ +export interface FormEditorSelection { + fieldId: PDFFormFieldId | null + widgetId: PDFFormWidgetId | null +} + +/** Shared field properties that may be edited. Placement stays on widgets. */ +export interface FormFieldUpdate { + type?: PDFFormFieldType + name?: string + value?: PDFFormFieldValue + defaultValue?: PDFFormFieldValue + required?: boolean + readOnly?: boolean + options?: PDFFormFieldOption[] + metadata?: Record +} + +/** Widget-specific properties. Owning field id is fixed after creation. */ +export interface FormWidgetUpdate { + pageIndex?: number + docIndex?: number + x?: number + y?: number + width?: number + height?: number + exportValue?: string + elementId?: string + metadata?: Record +} + +export interface CreateFormEditorOptions { + model?: PDFFormModel + overlay?: FormEditorOverlayAdapter + /** Defaults applied when bridging widgets to overlay elements. */ + bridgeOptions?: FormWidgetToElementOptions +} + +export interface PlaceFormWidgetOptions { + /** When an overlay adapter is present, also place a visual rectangle. Default true. */ + syncOverlay?: boolean + bridgeOptions?: FormWidgetToElementOptions +} + +export interface BeginPlaceWidgetInput { + fieldId: PDFFormFieldId + width?: number + height?: number + exportValue?: string + metadata?: Record + bridgeOptions?: FormWidgetToElementOptions +} + +export interface CompleteWidgetPlacementInput { + object: PDFElementObject + pageIndex: number + docIndex?: number + exportValue?: string + metadata?: Record +} + +interface PendingWidgetPlacement { + fieldId: PDFFormFieldId + width: number + height: number + exportValue?: string + metadata?: Record + bridgeOptions?: FormWidgetToElementOptions +} + +type OverlayObjectSnapshot = PDFElementObject & { pageIndex?: number } + +function geometryMatches( + object: Pick, + payload: Partial +): boolean { + if (payload.x !== undefined && object.x !== payload.x) return false + if (payload.y !== undefined && object.y !== payload.y) return false + if (payload.width !== undefined && object.width !== payload.width) return false + if (payload.height !== undefined && object.height !== payload.height) return false + return true +} + +const OVERLAY_ENRICHMENT_KEYS = new Set([ + 'pageIndex', + 'pageNumber', + 'scale', + 'normalizedCoordinates', +]) + +function toPlainOverlayElement( + object: OverlayObjectSnapshot, + geometry: Pick +): PDFElementObject { + const plain: PDFElementObject = { + x: geometry.x, + y: geometry.y, + width: geometry.width, + height: geometry.height, + } + for (const [key, value] of Object.entries(object)) { + if (OVERLAY_ENRICHMENT_KEYS.has(key)) continue + if (key === 'x' || key === 'y' || key === 'width' || key === 'height') continue + plain[key] = value + } + return plain +} + +function assertUniqueElementIds(model: PDFFormModel) { + const seen = new Set() + for (const widget of model.widgets) { + if (!widget.elementId) continue + const key = `${resolveDocIndex(widget)}:${widget.elementId}` + if (seen.has(key)) { + throw new Error( + `Duplicate elementId "${widget.elementId}" in document ${resolveDocIndex(widget)}` + ) + } + seen.add(key) + } +} + +const emptySelection = (): FormEditorSelection => ({ + fieldId: null, + widgetId: null, +}) + +function cloneOptions(options?: PDFFormFieldOption[]): PDFFormFieldOption[] | undefined { + if (options === undefined) return undefined + return options.map((option) => ({ ...option })) +} + +function cloneMetadata( + metadata?: Record +): Record | undefined { + if (metadata === undefined) return undefined + return { ...metadata } +} + +function requireField(model: PDFFormModel, fieldId: PDFFormFieldId): PDFFormField { + const field = getFormFieldById(model, fieldId) + if (!field) { + throw new Error(`Form field "${fieldId}" was not found`) + } + return field +} + +function requireWidget(model: PDFFormModel, widgetId: PDFFormWidgetId): PDFFormWidget { + const widget = getFormWidgetById(model, widgetId) + if (!widget) { + throw new Error(`Form widget "${widgetId}" was not found`) + } + return widget +} + +function defaultGeometry(width?: number, height?: number) { + return { + width: width ?? 120, + height: height ?? 24, + } +} + +function resolveDocIndex(widget: PDFFormWidget, fallback = 0): number { + return widget.docIndex ?? fallback +} + +function resolvePlacedElementId( + submitted: PDFElementObject, + result: FormEditorAddObjectResult +): string { + if (result === false) { + throw new Error('Overlay placement failed') + } + if (result !== true) { + if (!result.id) { + throw new Error('Overlay adapter returned a placed object without an id') + } + return result.id + } + if (!submitted.id) { + throw new Error( + 'Overlay adapter returned true without a stable id; return the stored object instead' + ) + } + return submitted.id +} + +/** + * Builds an overlay adapter that recovers the real object id after + * {@link PDFElementsPublicApi.addObjectToPage} rewrites colliding ids. + */ +export function createFormEditorOverlayAdapter( + api: PDFElementsPublicApi +): FormEditorOverlayAdapter { + let internalMutationDepth = 0 + const runInternalMutation = (work: () => T): T => { + internalMutationDepth += 1 + try { + return work() + } finally { + internalMutationDepth -= 1 + } + } + + return { + isInternalMutation: () => internalMutationDepth > 0, + addObjectToPage(object, pageIndex, docIndex) { + const before = new Set( + api.getAllObjects(docIndex).map((entry) => entry.id).filter(Boolean) as string[] + ) + const ok = api.addObjectToPage(object, pageIndex, docIndex) + if (!ok) return false + const after = api.getAllObjects(docIndex) + const created = after.find((entry) => entry.id && !before.has(entry.id)) + if (created) return created + const same = after.find((entry) => entry.id === object.id) + return same ?? true + }, + hasObject(docIndex, objectId, pageIndex) { + return api.getAllObjects(docIndex).some((entry) => { + const snapshot = entry as OverlayObjectSnapshot + if (snapshot.id !== objectId) return false + if (pageIndex === undefined) return true + return snapshot.pageIndex === pageIndex + }) + }, + moveObjectToPage: (docIndex, objectId, pageIndex, payload) => ( + api.moveObjectToPage(docIndex, objectId, pageIndex, payload) + ), + updateObject: (docIndex, objectId, payload) => { + const before = api.getAllObjects(docIndex) + .find((entry) => entry.id === objectId) as OverlayObjectSnapshot | undefined + if (!before) return false + + const previous = { + x: before.x, + y: before.y, + width: before.width, + height: before.height, + } + const previousPageIndex = before.pageIndex + + api.updateObject(docIndex, objectId, payload) + + const after = api.getAllObjects(docIndex) + .find((entry) => entry.id === objectId) as OverlayObjectSnapshot | undefined + if (!after) return false + + const geometryRequested = payload.x !== undefined + || payload.y !== undefined + || payload.width !== undefined + || payload.height !== undefined + if (!geometryRequested) return true + + const pageMoved = previousPageIndex !== undefined + && after.pageIndex !== undefined + && after.pageIndex !== previousPageIndex + if (pageMoved || !geometryMatches(after, payload)) { + if ( + pageMoved + && previousPageIndex !== undefined + && after.pageIndex !== undefined + ) { + return runInternalMutation(() => { + // Prefer silent page restore so hosts do not treat rollback as a user delete. + if ( + typeof api.moveObjectToPage === 'function' + && api.moveObjectToPage(docIndex, objectId, previousPageIndex, previous) + ) { + return false + } + // Fallback when moveObjectToPage is missing or returns false. + // Hosts must honor isInternalMutation() if they sync delete-object → removeWidget. + api.deleteObject(docIndex, objectId) + const restored = toPlainOverlayElement(before, previous) + restored.id = objectId + api.addObjectToPage(restored, previousPageIndex, docIndex) + return false + }) + } + api.updateObject(docIndex, objectId, previous) + return false + } + return true + }, + deleteObject: (docIndex, objectId) => { + api.deleteObject(docIndex, objectId) + }, + startAddingElement: (template) => { + api.startAddingElement(template) + }, + cancelAdding: () => { + api.cancelAdding() + }, + } +} + +/** + * Public form-editing facade. Holds a plain {@link PDFFormModel}, optional + * overlay sync, and logical selection. Does not depend on Vue component state. + */ +export interface PDFFormEditor { + getModel: () => PDFFormModel + getSnapshot: () => PDFFormModel + loadModel: (input: PDFFormModel | string) => PDFFormModel + createField: (input: CreateFormFieldInput) => PDFFormField + updateField: (fieldId: PDFFormFieldId, patch: FormFieldUpdate) => PDFFormField + removeField: (fieldId: PDFFormFieldId, options?: PlaceFormWidgetOptions) => void + placeWidget: ( + input: CreateFormWidgetInput, + options?: PlaceFormWidgetOptions + ) => PDFFormWidget + beginPlaceWidget: (input: BeginPlaceWidgetInput) => void + completeWidgetPlacement: (input: CompleteWidgetPlacementInput) => PDFFormWidget + cancelPlaceWidget: () => void + isPlacingWidget: () => boolean + updateWidget: ( + widgetId: PDFFormWidgetId, + patch: FormWidgetUpdate, + options?: PlaceFormWidgetOptions + ) => PDFFormWidget + removeWidget: (widgetId: PDFFormWidgetId, options?: PlaceFormWidgetOptions) => void + selectField: (fieldId: PDFFormFieldId | null) => FormEditorSelection + selectWidget: (widgetId: PDFFormWidgetId | null) => FormEditorSelection + getSelection: () => FormEditorSelection + clearSelection: () => FormEditorSelection + getField: (fieldId: PDFFormFieldId) => PDFFormField | undefined + getWidget: (widgetId: PDFFormWidgetId) => PDFFormWidget | undefined + getWidgetsForField: (fieldId: PDFFormFieldId) => PDFFormWidget[] + getWidgetByElementId: ( + elementId: string, + docIndex?: number + ) => PDFFormWidget | undefined + syncFromOverlay: ( + element: PDFElementObject, + location: { pageIndex: number; docIndex?: number } + ) => PDFFormWidget | undefined +} + +/** + * Creates a form editor session on top of the field/widget model from #84. + * Overlay editing remains available for non-form elements via the adapter. + */ +export function createFormEditor( + options: CreateFormEditorOptions = {} +): PDFFormEditor { + let model: PDFFormModel = options.model + ? parseFormModel(options.model) + : createFormModel() + if (options.model) { + assertUniqueElementIds(model) + } + let selection = emptySelection() + let pendingPlacement: PendingWidgetPlacement | null = null + const overlay = options.overlay + const defaultBridge = options.bridgeOptions ?? {} + const widgetBridgeOverrides = new Map() + + const getSelection = (): FormEditorSelection => ({ ...selection }) + + const clearSelection = (): FormEditorSelection => { + selection = emptySelection() + return getSelection() + } + + const clearPendingPlacement = (cancelOverlay: boolean) => { + if (!pendingPlacement) return + pendingPlacement = null + if (cancelOverlay) { + overlay?.cancelAdding?.() + } + } + + const rememberWidgetBridge = ( + widgetId: PDFFormWidgetId, + bridgeOptions?: FormWidgetToElementOptions + ) => { + if (!bridgeOptions) return + widgetBridgeOverrides.set(widgetId, { ...bridgeOptions }) + } + + const assertElementIdAvailable = ( + elementId: string | undefined, + widgetId: PDFFormWidgetId, + docIndex = 0 + ) => { + if (!elementId) return + const owner = model.widgets.find((entry) => ( + entry.id !== widgetId + && entry.elementId === elementId + && resolveDocIndex(entry) === docIndex + )) + if (owner) { + throw new Error( + `elementId "${elementId}" is already linked to widget "${owner.id}"` + ) + } + } + + const findWidgetByElementId = ( + elementId: string, + docIndex?: number + ): PDFFormWidget | undefined => { + const matches = model.widgets.filter((entry) => entry.elementId === elementId) + if (docIndex === undefined) return matches[0] + return matches.find((entry) => resolveDocIndex(entry) === docIndex) + } + + const pruneSelection = () => { + if (selection.fieldId && !getFormFieldById(model, selection.fieldId)) { + selection = emptySelection() + return + } + if (selection.widgetId) { + const widget = getFormWidgetById(model, selection.widgetId) + if (!widget || (selection.fieldId && widget.fieldId !== selection.fieldId)) { + selection = { + fieldId: selection.fieldId && getFormFieldById(model, selection.fieldId) + ? selection.fieldId + : null, + widgetId: null, + } + } + } + } + + const deleteOverlayForWidget = (widget: PDFFormWidget) => { + if (!overlay?.deleteObject || !widget.elementId) return + overlay.deleteObject(resolveDocIndex(widget), widget.elementId) + } + + const syncOverlayGeometry = (widget: PDFFormWidget): boolean => { + if (!overlay?.updateObject || !widget.elementId) return true + const result = overlay.updateObject(resolveDocIndex(widget), widget.elementId, { + x: widget.x, + y: widget.y, + width: widget.width, + height: widget.height, + }) + return result !== false + } + + const syncOverlayFieldAppearance = (field: PDFFormField) => { + if (!overlay?.updateObject) return + + for (const widget of getWidgetsForField(model, field.id)) { + if (!widget.elementId) continue + const overrides = { + ...defaultBridge, + ...widgetBridgeOverrides.get(widget.id), + } + const payload: Partial = {} + if (overrides.type === undefined) payload.type = field.type + if (overrides.label === undefined) payload.label = field.name + if (Object.keys(payload).length === 0) continue + overlay.updateObject(resolveDocIndex(widget), widget.elementId, payload) + } + } + + const placeOverlayForWidget = ( + widget: PDFFormWidget, + field: PDFFormField, + bridgeOptions?: FormWidgetToElementOptions + ) => { + if (!overlay) { + throw new Error('Cannot sync overlay: no overlay adapter was configured') + } + + const docIndex = resolveDocIndex(widget) + assertElementIdAvailable(widget.elementId, widget.id, docIndex) + if ( + widget.elementId + && overlay.hasObject?.(docIndex, widget.elementId, widget.pageIndex) + ) { + rememberWidgetBridge(widget.id, bridgeOptions) + return + } + + if (!widget.elementId) { + widget.elementId = `form-el-${createFormWidgetId()}` + } + + const element = formWidgetToElementObject(widget, field, { + ...defaultBridge, + ...bridgeOptions, + }) + const result = overlay.addObjectToPage(element, widget.pageIndex, docIndex) + if (result === false) { + throw new Error( + `Failed to place overlay element for widget "${widget.id}" on page ${widget.pageIndex}` + ) + } + widget.elementId = resolvePlacedElementId(element, result) + rememberWidgetBridge(widget.id, bridgeOptions) + } + + const createField = (input: CreateFormFieldInput): PDFFormField => { + if (input.widgetIds && input.widgetIds.length > 0) { + throw new Error('createField does not accept widgetIds; use placeWidget to attach widgets') + } + const field = createFormField({ ...input, widgetIds: [] }) + if (getFormFieldById(model, field.id)) { + throw new Error(`Cannot create field: id "${field.id}" already exists`) + } + model.fields.push(field) + return field + } + + const updateField = ( + fieldId: PDFFormFieldId, + patch: FormFieldUpdate + ): PDFFormField => { + const field = requireField(model, fieldId) + + if (patch.type !== undefined) field.type = patch.type + if (patch.name !== undefined) field.name = patch.name + if (patch.value !== undefined) field.value = patch.value + if (patch.defaultValue !== undefined) field.defaultValue = patch.defaultValue + if (patch.required !== undefined) field.required = patch.required + if (patch.readOnly !== undefined) field.readOnly = patch.readOnly + if (patch.options !== undefined) field.options = cloneOptions(patch.options) + if (patch.metadata !== undefined) field.metadata = cloneMetadata(patch.metadata) + + if (patch.type !== undefined || patch.name !== undefined) { + syncOverlayFieldAppearance(field) + } + + return field + } + + const removeWidget = ( + widgetId: PDFFormWidgetId, + placeOptions: PlaceFormWidgetOptions = {} + ) => { + const widget = requireWidget(model, widgetId) + const field = getFormFieldById(model, widget.fieldId) + const syncOverlay = placeOptions.syncOverlay !== false + + if (syncOverlay) { + deleteOverlayForWidget(widget) + } + + model.widgets = model.widgets.filter((entry) => entry.id !== widgetId) + if (field) { + field.widgetIds = field.widgetIds.filter((id) => id !== widgetId) + } + widgetBridgeOverrides.delete(widgetId) + + if (selection.widgetId === widgetId) { + selection = { fieldId: selection.fieldId, widgetId: null } + } + pruneSelection() + } + + const removeField = ( + fieldId: PDFFormFieldId, + placeOptions: PlaceFormWidgetOptions = {} + ) => { + requireField(model, fieldId) + const widgets = getWidgetsForField(model, fieldId) + for (const widget of [...widgets]) { + removeWidget(widget.id, placeOptions) + } + model.fields = model.fields.filter((field) => field.id !== fieldId) + if (selection.fieldId === fieldId) { + selection = emptySelection() + } + if (pendingPlacement?.fieldId === fieldId) { + clearPendingPlacement(true) + } + } + + const placeWidget = ( + input: CreateFormWidgetInput, + placeOptions: PlaceFormWidgetOptions = {} + ): PDFFormWidget => { + const field = requireField(model, input.fieldId) + assertElementIdAvailable( + input.elementId, + input.id ?? '', + input.docIndex ?? 0 + ) + const widget = addWidgetToField(model, input) + const syncOverlay = placeOptions.syncOverlay !== false && !!overlay + + if (syncOverlay) { + try { + placeOverlayForWidget(widget, field, placeOptions.bridgeOptions) + } catch (error) { + model.widgets = model.widgets.filter((entry) => entry.id !== widget.id) + field.widgetIds = field.widgetIds.filter((id) => id !== widget.id) + widgetBridgeOverrides.delete(widget.id) + throw error + } + } else { + rememberWidgetBridge(widget.id, placeOptions.bridgeOptions) + } + + return widget + } + + const beginPlaceWidget = (input: BeginPlaceWidgetInput) => { + const field = requireField(model, input.fieldId) + const geometry = defaultGeometry(input.width, input.height) + clearPendingPlacement(true) + pendingPlacement = { + fieldId: field.id, + width: geometry.width, + height: geometry.height, + exportValue: input.exportValue, + metadata: cloneMetadata(input.metadata), + bridgeOptions: input.bridgeOptions ? { ...input.bridgeOptions } : undefined, + } + + if (!overlay?.startAddingElement) { + return + } + + const template = formWidgetToElementObject( + { + id: 'pending-form-widget', + fieldId: field.id, + pageIndex: 0, + x: 0, + y: 0, + width: geometry.width, + height: geometry.height, + exportValue: input.exportValue, + metadata: pendingPlacement.metadata, + }, + field, + { ...defaultBridge, ...input.bridgeOptions } + ) + delete template.id + overlay.startAddingElement(template) + } + + const completeWidgetPlacement = ( + input: CompleteWidgetPlacementInput + ): PDFFormWidget => { + if (!pendingPlacement) { + throw new Error('No widget placement is in progress') + } + + const { fieldId, width, height, exportValue, metadata, bridgeOptions } = pendingPlacement + requireField(model, fieldId) + + const object = input.object + const widgetInput: CreateFormWidgetInput = { + fieldId, + pageIndex: input.pageIndex, + x: object.x, + y: object.y, + width: object.width ?? width, + height: object.height ?? height, + } + + if (input.docIndex !== undefined) widgetInput.docIndex = input.docIndex + const resolvedExport = input.exportValue ?? exportValue + if (resolvedExport !== undefined) widgetInput.exportValue = resolvedExport + const resolvedMetadata = input.metadata ?? metadata + if (resolvedMetadata !== undefined) { + widgetInput.metadata = cloneMetadata(resolvedMetadata) + } + if (object.id) widgetInput.elementId = object.id + + pendingPlacement = null + // Overlay already contains the placed object; only update the form model. + return placeWidget(widgetInput, { + syncOverlay: false, + bridgeOptions, + }) + } + + const cancelPlaceWidget = () => { + clearPendingPlacement(true) + } + + const updateWidget = ( + widgetId: PDFFormWidgetId, + patch: FormWidgetUpdate, + placeOptions: PlaceFormWidgetOptions = {} + ): PDFFormWidget => { + const widget = requireWidget(model, widgetId) + const syncOverlay = placeOptions.syncOverlay !== false && !!overlay + + if (syncOverlay) { + const pageChanged = patch.pageIndex !== undefined && patch.pageIndex !== widget.pageIndex + const docChanged = patch.docIndex !== undefined && patch.docIndex !== widget.docIndex + const elementChanged = patch.elementId !== undefined && patch.elementId !== widget.elementId + if (pageChanged || docChanged) { + throw new Error( + 'Cannot change widget pageIndex/docIndex while syncing overlay; ' + + 'remove and re-place the widget, or call updateWidget with syncOverlay: false' + ) + } + if (elementChanged) { + throw new Error( + 'Cannot change widget elementId while syncing overlay; ' + + 'call updateWidget with syncOverlay: false after updating visuals yourself' + ) + } + } + + const nextDocIndex = patch.docIndex ?? resolveDocIndex(widget) + if (patch.elementId !== undefined) { + assertElementIdAvailable(patch.elementId, widget.id, nextDocIndex) + } else if ( + patch.docIndex !== undefined + && patch.docIndex !== resolveDocIndex(widget) + && widget.elementId + ) { + assertElementIdAvailable(widget.elementId, widget.id, patch.docIndex) + } + + const previousGeometry = { + x: widget.x, + y: widget.y, + width: widget.width, + height: widget.height, + } + const geometryPatch = patch.x !== undefined + || patch.y !== undefined + || patch.width !== undefined + || patch.height !== undefined + + if (patch.x !== undefined) widget.x = patch.x + if (patch.y !== undefined) widget.y = patch.y + if (patch.width !== undefined) widget.width = patch.width + if (patch.height !== undefined) widget.height = patch.height + + if (syncOverlay && geometryPatch) { + if (!syncOverlayGeometry(widget)) { + widget.x = previousGeometry.x + widget.y = previousGeometry.y + widget.width = previousGeometry.width + widget.height = previousGeometry.height + throw new Error( + `Overlay rejected geometry update for widget "${widget.id}"` + ) + } + } + + if (patch.pageIndex !== undefined) widget.pageIndex = patch.pageIndex + if (patch.docIndex !== undefined) widget.docIndex = patch.docIndex + if (patch.exportValue !== undefined) widget.exportValue = patch.exportValue + if (patch.elementId !== undefined) widget.elementId = patch.elementId + if (patch.metadata !== undefined) widget.metadata = cloneMetadata(patch.metadata) + + return widget + } + + const selectField = (fieldId: PDFFormFieldId | null): FormEditorSelection => { + if (fieldId === null) { + return clearSelection() + } + requireField(model, fieldId) + selection = { fieldId, widgetId: null } + return getSelection() + } + + const selectWidget = (widgetId: PDFFormWidgetId | null): FormEditorSelection => { + if (widgetId === null) { + selection = { fieldId: selection.fieldId, widgetId: null } + return getSelection() + } + const widget = requireWidget(model, widgetId) + selection = { fieldId: widget.fieldId, widgetId: widget.id } + return getSelection() + } + + const syncFromOverlay = ( + element: PDFElementObject, + location: { pageIndex: number; docIndex?: number } + ): PDFFormWidget | undefined => { + if (!element.id) return undefined + const byElementId = findWidgetByElementId(element.id, location.docIndex) + const widget = byElementId + ?? model.widgets.find((entry) => { + if (entry.elementId || entry.id !== element.id) return false + if (location.docIndex === undefined) return true + return resolveDocIndex(entry) === location.docIndex + }) + if (!widget) return undefined + + const placement = elementObjectToFormWidgetPlacement(element, location) + widget.x = placement.x + widget.y = placement.y + widget.width = placement.width + widget.height = placement.height + widget.pageIndex = placement.pageIndex + if (placement.docIndex !== undefined) { + widget.docIndex = placement.docIndex + } + if (placement.elementId !== undefined) { + widget.elementId = placement.elementId + } + + return widget + } + + return { + getModel: () => model, + getSnapshot: () => serializeFormModel(model), + loadModel: (input) => { + const next = parseFormModel(input) + assertUniqueElementIds(next) + clearPendingPlacement(true) + model = next + selection = emptySelection() + widgetBridgeOverrides.clear() + return model + }, + createField, + updateField, + removeField, + placeWidget, + beginPlaceWidget, + completeWidgetPlacement, + cancelPlaceWidget, + isPlacingWidget: () => pendingPlacement !== null, + updateWidget, + removeWidget, + selectField, + selectWidget, + getSelection, + clearSelection, + getField: (fieldId) => getFormFieldById(model, fieldId), + getWidget: (widgetId) => getFormWidgetById(model, widgetId), + getWidgetsForField: (fieldId) => getWidgetsForField(model, fieldId), + getWidgetByElementId: (elementId, docIndex) => + findWidgetByElementId(elementId, docIndex), + syncFromOverlay, + } +} diff --git a/tests/components/formEditing.overlay.spec.ts b/tests/components/formEditing.overlay.spec.ts new file mode 100644 index 0000000..f7a50f5 --- /dev/null +++ b/tests/components/formEditing.overlay.spec.ts @@ -0,0 +1,420 @@ +// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors +// SPDX-License-Identifier: AGPL-3.0-or-later + +import { describe, expect, it, vi } from 'vitest' +import { shallowMount } from '@vue/test-utils' +import PDFElements from '../../src/components/PDFElements.vue' +import { + createFormEditor, + createFormEditorOverlayAdapter, +} from '../../src/utils/formEditing' + +const makeDoc = () => ({ + name: 'doc', + file: null, + pdfDoc: null, + numPages: 2, + pages: [Promise.resolve(), Promise.resolve()], + pageWidths: [300, 300], + pagesScale: [1, 1], + allObjects: [[], []] as Record[][], +}) + +describe('form editing over PDFElements overlay API', () => { + it('places and moves form widgets through the public overlay methods', () => { + const wrapper = shallowMount(PDFElements, { + props: { initFiles: [] }, + global: { + stubs: { + PDFPage: true, + DraggableElement: true, + }, + }, + }) + + const ctx = wrapper.vm as any + const doc = makeDoc() + ctx.pdfDocuments = [doc] + ctx.selectedDocIndex = 0 + ctx.selectedPageIndex = 0 + ctx.getPageComponent = vi.fn(() => ({ + getCanvasMeasurement: () => ({ canvasWidth: 300, canvasHeight: 400 }), + })) + ctx.getPageCanvasElement = vi.fn(() => ({ + width: 300, + height: 400, + getBoundingClientRect: () => ({ + width: 300, + height: 400, + left: 0, + right: 300, + top: 0, + bottom: 400, + }), + })) + + const editor = createFormEditor({ + overlay: createFormEditorOverlayAdapter(ctx), + }) + + const field = editor.createField({ + type: 'text', + name: 'address', + required: true, + }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 20, + y: 30, + width: 100, + height: 24, + }) + + expect(doc.allObjects[0]).toHaveLength(1) + expect(doc.allObjects[0][0]).toMatchObject({ + id: widget.elementId, + type: 'text', + label: 'address', + x: 20, + y: 30, + }) + + editor.updateWidget(widget.id, { x: 40, y: 50 }) + expect(doc.allObjects[0][0]).toMatchObject({ x: 40, y: 50 }) + + editor.syncFromOverlay( + { ...doc.allObjects[0][0], x: 60, y: 70 } as any, + { pageIndex: 0, docIndex: 0 } + ) + expect(editor.getWidget(widget.id)).toMatchObject({ x: 60, y: 70 }) + + // Non-form overlay remains independent of the form model. + expect( + ctx.addObjectToPage({ + id: 'signature-1', + type: 'signature', + x: 10, + y: 10, + width: 80, + height: 40, + }) + ).toBe(true) + expect(doc.allObjects[0]).toHaveLength(2) + expect(editor.getModel().widgets).toHaveLength(1) + + // Existing elementId links in place (migration) without duplicating the rectangle. + doc.allObjects[0].push({ + id: 'annotation', + x: 1, + y: 1, + width: 12, + height: 12, + type: 'marker', + }) + const linked = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 1, + y: 1, + width: 12, + height: 12, + elementId: 'annotation', + }) + expect(linked.elementId).toBe('annotation') + expect(doc.allObjects[0].filter((object) => object.id === 'annotation')).toHaveLength(1) + + editor.removeWidget(widget.id) + editor.removeWidget(linked.id, { syncOverlay: false }) + expect(doc.allObjects[0].some((object) => object.id === 'signature-1')).toBe(true) + expect(doc.allObjects[0].some((object) => object.id === 'annotation')).toBe(true) + expect(doc.allObjects[0].some((object) => object.id === widget.elementId)).toBe(false) + }) + + it('rolls back model geometry when PDFElements rejects an out-of-bounds update', () => { + const wrapper = shallowMount(PDFElements, { + props: { initFiles: [] }, + global: { + stubs: { + PDFPage: true, + DraggableElement: true, + }, + }, + }) + + const ctx = wrapper.vm as any + const doc = makeDoc() + ctx.pdfDocuments = [doc] + ctx.selectedDocIndex = 0 + ctx.selectedPageIndex = 0 + ctx.getPageComponent = vi.fn(() => ({ + getCanvasMeasurement: () => ({ canvasWidth: 300, canvasHeight: 400 }), + })) + ctx.getPageCanvasElement = vi.fn(() => ({ + width: 300, + height: 400, + getBoundingClientRect: () => ({ + width: 300, + height: 400, + left: 0, + right: 300, + top: 0, + bottom: 400, + }), + })) + ctx.getPageSize = vi.fn(() => ({ width: 300, height: 400 })) + ctx.getPageWidth = vi.fn(() => 300) + ctx.getPageHeight = vi.fn(() => 400) + + const editor = createFormEditor({ + overlay: createFormEditorOverlayAdapter(ctx), + }) + const field = editor.createField({ type: 'text', name: 'bounds' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 10, + y: 10, + width: 20, + height: 20, + }) + + expect(() => editor.updateWidget(widget.id, { x: -1 })).toThrow(/rejected geometry/) + expect(editor.getWidget(widget.id)?.x).toBe(10) + expect(doc.allObjects[0][0]).toMatchObject({ x: 10, y: 10 }) + }) + + it('restores overlay page membership after a rejected cross-page spill', () => { + const wrapper = shallowMount(PDFElements, { + props: { initFiles: [] }, + global: { + stubs: { + PDFPage: true, + DraggableElement: true, + }, + }, + }) + + const ctx = wrapper.vm as any + const doc = makeDoc() + doc.pageWidths = [300, 600] + ctx.pdfDocuments = [doc] + ctx.selectedDocIndex = 0 + ctx.selectedPageIndex = 0 + ctx.getPageComponent = vi.fn((_docIndex: number, pageIndex: number) => ({ + getCanvasMeasurement: () => ({ + canvasWidth: pageIndex === 0 ? 300 : 600, + canvasHeight: 400, + }), + })) + ctx.getPageCanvasElement = vi.fn(() => ({ + width: 300, + height: 400, + getBoundingClientRect: () => ({ + width: 300, + height: 400, + left: 0, + right: 300, + top: 0, + bottom: 400, + }), + })) + ctx.getPageSize = vi.fn((_docIndex: number, pageIndex: number) => ({ + width: pageIndex === 0 ? 300 : 600, + height: 400, + })) + ctx.getPageWidth = vi.fn((_docIndex: number, pageIndex: number) => ( + pageIndex === 0 ? 300 : 600 + )) + ctx.getPageHeight = vi.fn(() => 400) + + const overlay = createFormEditorOverlayAdapter(ctx) + const editor = createFormEditor({ overlay }) + const field = editor.createField({ type: 'text', name: 'spill' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 10, + y: 10, + width: 20, + height: 20, + }) + + const deleteSpy = vi.spyOn(ctx, 'deleteObject') + const moveSpy = vi.spyOn(ctx, 'moveObjectToPage') + + expect(() => editor.updateWidget(widget.id, { x: 400 })).toThrow(/rejected geometry/) + expect(editor.getWidget(widget.id)).toMatchObject({ + x: 10, + y: 10, + pageIndex: 0, + }) + expect(editor.getWidgetsForField(field.id)).toHaveLength(1) + // Silent page restore: hosts listening for delete-object must not see a user delete. + expect(moveSpy).toHaveBeenCalledWith( + 0, + widget.elementId, + 0, + expect.objectContaining({ x: 10, y: 10, width: 20, height: 20 }) + ) + expect(deleteSpy).not.toHaveBeenCalled() + expect(wrapper.emitted()['pdf-elements:delete-object']).toBeUndefined() + expect(doc.allObjects[0].some((object) => object.id === widget.elementId)).toBe(true) + expect(doc.allObjects[1].some((object) => object.id === widget.elementId)).toBe(false) + expect(doc.allObjects[0].find((object) => object.id === widget.elementId)).toMatchObject({ + x: 10, + y: 10, + }) + }) + + it('keeps the widget when a delete-object host handler is wired during spill restore', () => { + const wrapper = shallowMount(PDFElements, { + props: { initFiles: [] }, + global: { + stubs: { + PDFPage: true, + DraggableElement: true, + }, + }, + }) + + const ctx = wrapper.vm as any + const doc = makeDoc() + doc.pageWidths = [300, 600] + ctx.pdfDocuments = [doc] + ctx.selectedDocIndex = 0 + ctx.selectedPageIndex = 0 + ctx.getPageComponent = vi.fn((_docIndex: number, pageIndex: number) => ({ + getCanvasMeasurement: () => ({ + canvasWidth: pageIndex === 0 ? 300 : 600, + canvasHeight: 400, + }), + })) + ctx.getPageCanvasElement = vi.fn(() => ({ + width: 300, + height: 400, + getBoundingClientRect: () => ({ + width: 300, + height: 400, + left: 0, + right: 300, + top: 0, + bottom: 400, + }), + })) + ctx.getPageSize = vi.fn((_docIndex: number, pageIndex: number) => ({ + width: pageIndex === 0 ? 300 : 600, + height: 400, + })) + ctx.getPageWidth = vi.fn((_docIndex: number, pageIndex: number) => ( + pageIndex === 0 ? 300 : 600 + )) + ctx.getPageHeight = vi.fn(() => 400) + + const overlay = createFormEditorOverlayAdapter(ctx) + const editor = createFormEditor({ overlay }) + const field = editor.createField({ type: 'text', name: 'spill-host' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 10, + y: 10, + width: 20, + height: 20, + }) + + // Simulate a compliant host that removes widgets on delete-object. + // If rollback used deleteObject, this would empty the model mid-restore. + const removeOnDelete = vi.fn((objectId: string) => { + if (overlay.isInternalMutation?.()) return + const target = editor.getWidgetByElementId(objectId, 0) + if (target) editor.removeWidget(target.id) + }) + const originalDelete = ctx.deleteObject.bind(ctx) + ctx.deleteObject = (docIndex: number, objectId: string) => { + originalDelete(docIndex, objectId) + removeOnDelete(objectId) + } + + expect(() => editor.updateWidget(widget.id, { x: 400 })).toThrow(/rejected geometry/) + expect(removeOnDelete).not.toHaveBeenCalled() + expect(editor.getWidgetsForField(field.id)).toEqual([ + expect.objectContaining({ id: widget.id, x: 10, pageIndex: 0 }), + ]) + }) + + it('recovers a rewritten overlay id when placeWidget collides on PDFElements', () => { + const wrapper = shallowMount(PDFElements, { + props: { initFiles: [] }, + global: { + stubs: { + PDFPage: true, + DraggableElement: true, + }, + }, + }) + + const ctx = wrapper.vm as any + const doc = makeDoc() + doc.allObjects[0].push({ + id: 'annotation', + x: 0, + y: 0, + width: 12, + height: 12, + type: 'marker', + }) + ctx.pdfDocuments = [doc] + ctx.selectedDocIndex = 0 + ctx.selectedPageIndex = 0 + ctx.objectIndexCache = { '0-annotation': 0 } + ctx.getPageComponent = vi.fn(() => ({ + getCanvasMeasurement: () => ({ canvasWidth: 300, canvasHeight: 400 }), + })) + ctx.getPageCanvasElement = vi.fn(() => ({ + width: 300, + height: 400, + getBoundingClientRect: () => ({ + width: 300, + height: 400, + left: 0, + right: 300, + top: 0, + bottom: 400, + }), + })) + + // Bypass hasObject linking so addObjectToPage must rewrite the colliding id. + const stock = createFormEditorOverlayAdapter(ctx) + const editor = createFormEditor({ + overlay: { + ...stock, + hasObject: undefined, + }, + }) + const field = editor.createField({ type: 'text', name: 'collide' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 20, + y: 20, + width: 30, + height: 18, + elementId: 'annotation', + }) + + expect(widget.elementId).not.toBe('annotation') + expect(doc.allObjects[0].some((object) => object.id === 'annotation')).toBe(true) + expect(doc.allObjects[0].some((object) => object.id === widget.elementId)).toBe(true) + + editor.removeWidget(widget.id) + expect(doc.allObjects[0].some((object) => object.id === 'annotation')).toBe(true) + expect(doc.allObjects[0].some((object) => object.id === widget.elementId)).toBe(false) + }) +}) diff --git a/tests/utils/formEditing.spec.ts b/tests/utils/formEditing.spec.ts new file mode 100644 index 0000000..a1380a4 --- /dev/null +++ b/tests/utils/formEditing.spec.ts @@ -0,0 +1,676 @@ +// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors +// SPDX-License-Identifier: AGPL-3.0-or-later + +import { describe, expect, it, vi } from 'vitest' +import type { PDFElementObject } from '../../src/types' +import { createFormEditor } from '../../src/utils/formEditing' +import { + serializeFormModel, + validateFormModelRelationships, +} from '../../src/utils/formModel' + +function createOverlayAdapter(options: { rewriteIds?: boolean } = {}) { + const objects: PDFElementObject[] = [] + return { + objects, + adapter: { + addObjectToPage: vi.fn((object: PDFElementObject) => { + const requestedId = object.id + const id = options.rewriteIds + || (requestedId && objects.some((entry) => entry.id === requestedId)) + ? `obj-rewritten-${objects.length + 1}` + : (requestedId ?? `obj-${objects.length + 1}`) + const placed = { ...object, id } + objects.push(placed) + return placed + }), + hasObject: vi.fn((docIndex: number, objectId: string) => { + void docIndex + return objects.some((entry) => entry.id === objectId) + }), + updateObject: vi.fn((docIndex: number, objectId: string, payload: Partial) => { + void docIndex + const target = objects.find((entry) => entry.id === objectId) + if (!target) return false + if (typeof payload.x === 'number' && payload.x < 0) return false + Object.assign(target, payload) + }), + deleteObject: vi.fn((docIndex: number, objectId: string) => { + void docIndex + const index = objects.findIndex((entry) => entry.id === objectId) + if (index >= 0) objects.splice(index, 1) + }), + startAddingElement: vi.fn(), + cancelAdding: vi.fn(), + }, + } +} + +describe('createFormEditor', () => { + it('creates fields and places multiple widgets without mixing property levels', () => { + const editor = createFormEditor() + const field = editor.createField({ + type: 'radio', + name: 'color', + options: [ + { value: 'red', label: 'Red' }, + { value: 'blue', label: 'Blue' }, + ], + required: true, + }) + + const first = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + x: 10, + y: 20, + width: 16, + height: 16, + exportValue: 'red', + }) + const second = editor.placeWidget({ + fieldId: field.id, + pageIndex: 2, + docIndex: 0, + x: 40, + y: 80, + width: 16, + height: 16, + exportValue: 'blue', + }) + + expect(field).not.toHaveProperty('x') + expect(field).not.toHaveProperty('pageIndex') + expect(first).not.toHaveProperty('value') + expect(first).not.toHaveProperty('required') + expect(editor.getWidgetsForField(field.id)).toHaveLength(2) + expect(first.fieldId).toBe(field.id) + expect(second.fieldId).toBe(field.id) + expect(validateFormModelRelationships(editor.getModel())).toEqual([]) + }) + + it('edits shared field properties and widget-specific properties separately', () => { + const editor = createFormEditor() + const field = editor.createField({ + type: 'dropdown', + name: 'city', + options: [{ value: 'sp', label: 'São Paulo' }], + }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + x: 1, + y: 2, + width: 100, + height: 24, + exportValue: 'sp', + }) + + editor.updateField(field.id, { + value: 'sp', + required: true, + readOnly: false, + options: [ + { value: 'sp', label: 'São Paulo' }, + { value: 'rj', label: 'Rio' }, + ], + }) + editor.updateWidget(widget.id, { + x: 15, + y: 30, + width: 140, + exportValue: 'rj', + }) + + expect(editor.getField(field.id)).toMatchObject({ + value: 'sp', + required: true, + readOnly: false, + }) + expect(editor.getField(field.id)?.options).toHaveLength(2) + expect(editor.getWidget(widget.id)).toMatchObject({ + x: 15, + y: 30, + width: 140, + exportValue: 'rj', + }) + expect(editor.getField(field.id)).not.toHaveProperty('x') + expect(editor.getWidget(widget.id)).not.toHaveProperty('value') + }) + + it('selects fields and widgets while keeping one field linked to many widgets', () => { + const editor = createFormEditor() + const field = editor.createField({ type: 'checkbox', name: 'accept' }) + const first = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + x: 0, + y: 0, + width: 12, + height: 12, + }) + const second = editor.placeWidget({ + fieldId: field.id, + pageIndex: 1, + x: 0, + y: 0, + width: 12, + height: 12, + }) + + expect(editor.selectField(field.id)).toEqual({ + fieldId: field.id, + widgetId: null, + }) + expect(editor.selectWidget(second.id)).toEqual({ + fieldId: field.id, + widgetId: second.id, + }) + + editor.removeWidget(first.id) + expect(editor.getSelection()).toEqual({ + fieldId: field.id, + widgetId: second.id, + }) + expect(editor.getWidgetsForField(field.id)).toEqual([ + expect.objectContaining({ id: second.id }), + ]) + }) + + it('syncs overlay placement, geometry updates and deletion through the adapter', () => { + const { adapter, objects } = createOverlayAdapter() + const editor = createFormEditor({ overlay: adapter }) + const field = editor.createField({ type: 'text', name: 'full-name' }) + + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 10, + y: 20, + width: 120, + height: 24, + }) + + expect(objects).toHaveLength(1) + expect(widget.elementId).toBe(objects[0].id) + expect(objects[0]).toMatchObject({ + type: 'text', + label: 'full-name', + x: 10, + y: 20, + width: 120, + height: 24, + }) + + editor.updateWidget(widget.id, { x: 50, y: 60, width: 200 }) + expect(adapter.updateObject).toHaveBeenCalledWith(0, widget.elementId, { + x: 50, + y: 60, + width: 200, + height: 24, + }) + + editor.updateField(field.id, { name: 'legal-name', type: 'text' }) + expect(adapter.updateObject).toHaveBeenCalledWith(0, widget.elementId, { + type: 'text', + label: 'legal-name', + }) + + const moved = editor.syncFromOverlay( + { id: widget.elementId!, x: 70, y: 90, width: 180, height: 30 }, + { pageIndex: 1, docIndex: 0 } + ) + expect(moved).toMatchObject({ + id: widget.id, + x: 70, + y: 90, + width: 180, + height: 30, + pageIndex: 1, + docIndex: 0, + }) + + editor.removeField(field.id) + expect(adapter.deleteObject).toHaveBeenCalledWith(0, widget.elementId) + expect(objects).toHaveLength(0) + expect(editor.getModel()).toEqual({ fields: [], widgets: [] }) + }) + + it('completes interactive placement without duplicating the overlay object', () => { + const { adapter, objects } = createOverlayAdapter() + const editor = createFormEditor({ overlay: adapter }) + const field = editor.createField({ type: 'text', name: 'title' }) + + editor.beginPlaceWidget({ + fieldId: field.id, + width: 160, + height: 28, + exportValue: 'draft', + }) + expect(editor.isPlacingWidget()).toBe(true) + expect(adapter.startAddingElement).toHaveBeenCalledTimes(1) + + const placedObject: PDFElementObject = { + id: 'obj-placed', + x: 12, + y: 34, + width: 160, + height: 28, + type: 'text', + label: 'title', + } + objects.push(placedObject) + + const widget = editor.completeWidgetPlacement({ + object: placedObject, + pageIndex: 0, + docIndex: 0, + }) + + expect(editor.isPlacingWidget()).toBe(false) + expect(widget).toMatchObject({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 12, + y: 34, + width: 160, + height: 28, + exportValue: 'draft', + elementId: 'obj-placed', + }) + expect(objects).toHaveLength(1) + expect(adapter.addObjectToPage).not.toHaveBeenCalled() + }) + + it('cancels interactive placement and leaves the model unchanged', () => { + const { adapter } = createOverlayAdapter() + const editor = createFormEditor({ overlay: adapter }) + const field = editor.createField({ type: 'text', name: 'notes' }) + + editor.beginPlaceWidget({ fieldId: field.id }) + editor.cancelPlaceWidget() + + expect(editor.isPlacingWidget()).toBe(false) + expect(adapter.cancelAdding).toHaveBeenCalledTimes(1) + expect(editor.getWidgetsForField(field.id)).toEqual([]) + }) + + it('keeps model-only editing working without an overlay adapter', () => { + const editor = createFormEditor() + const field = editor.createField({ type: 'unknown-custom', name: 'x' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + x: 1, + y: 1, + width: 10, + height: 10, + }) + + editor.updateWidget(widget.id, { x: 5 }) + expect(editor.getWidget(widget.id)?.x).toBe(5) + expect(editor.getSnapshot()).toEqual(serializeFormModel(editor.getModel())) + }) + + it('does not attach form editing state to Vue-like hosts', () => { + const editor = createFormEditor() + expect(editor).not.toHaveProperty('$') + expect(editor).not.toHaveProperty('_isVue') + expect(typeof editor.getModel).toBe('function') + }) + + it('keeps widget.elementId on the stored overlay id after collisions', () => { + const objects: PDFElementObject[] = [{ + id: 'annotation', + x: 0, + y: 0, + width: 10, + height: 10, + type: 'signature', + }] + // No hasObject: simulates a host that only returns the stored object after rewrite. + const adapter = { + addObjectToPage: vi.fn((object: PDFElementObject) => { + const id = objects.some((entry) => entry.id === object.id) + ? `obj-rewritten-${objects.length + 1}` + : (object.id ?? `obj-${objects.length + 1}`) + const placed = { ...object, id } + objects.push(placed) + return placed + }), + deleteObject: vi.fn((docIndex: number, objectId: string) => { + void docIndex + const index = objects.findIndex((entry) => entry.id === objectId) + if (index >= 0) objects.splice(index, 1) + }), + } + const editor = createFormEditor({ overlay: adapter }) + const field = editor.createField({ type: 'text', name: 'name' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 5, + y: 5, + width: 40, + height: 16, + elementId: 'annotation', + }) + + expect(widget.elementId).not.toBe('annotation') + expect(widget.elementId).toBe(objects[1].id) + expect(objects).toHaveLength(2) + + editor.removeWidget(widget.id) + expect(objects.some((entry) => entry.id === 'annotation')).toBe(true) + expect(objects).toHaveLength(1) + }) + + it('links to an existing overlay without inserting a duplicate', () => { + const { adapter, objects } = createOverlayAdapter() + objects.push({ + id: 'existing-field', + x: 8, + y: 9, + width: 50, + height: 20, + type: 'text', + }) + const editor = createFormEditor({ overlay: adapter }) + const field = editor.createField({ type: 'text', name: 'migrated' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 8, + y: 9, + width: 50, + height: 20, + elementId: 'existing-field', + }) + + expect(widget.elementId).toBe('existing-field') + expect(objects).toHaveLength(1) + expect(adapter.addObjectToPage).not.toHaveBeenCalled() + }) + + it('cancels overlay adding when loadModel replaces the session', () => { + const { adapter } = createOverlayAdapter() + const editor = createFormEditor({ overlay: adapter }) + const field = editor.createField({ type: 'text', name: 'a' }) + editor.beginPlaceWidget({ fieldId: field.id }) + expect(editor.isPlacingWidget()).toBe(true) + + editor.loadModel({ fields: [], widgets: [] }) + expect(editor.isPlacingWidget()).toBe(false) + expect(adapter.cancelAdding).toHaveBeenCalled() + expect(editor.getModel()).toEqual({ fields: [], widgets: [] }) + }) + + it('rejects createField widgetIds and page moves while syncing overlay', () => { + const { adapter } = createOverlayAdapter() + const editor = createFormEditor({ overlay: adapter }) + + expect(() => editor.createField({ + type: 'text', + name: 'broken', + widgetIds: ['ghost'], + })).toThrow(/widgetIds/) + + const field = editor.createField({ type: 'text', name: 'ok' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 1, + y: 1, + width: 10, + height: 10, + }) + + expect(() => editor.updateWidget(widget.id, { pageIndex: 1 })).toThrow(/pageIndex\/docIndex/) + editor.updateWidget(widget.id, { pageIndex: 1 }, { syncOverlay: false }) + expect(editor.getWidget(widget.id)?.pageIndex).toBe(1) + }) + + it('rolls back geometry when the overlay rejects an update', () => { + const { adapter } = createOverlayAdapter() + const editor = createFormEditor({ overlay: adapter }) + const field = editor.createField({ type: 'text', name: 'geo' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 10, + y: 10, + width: 20, + height: 20, + }) + + expect(() => editor.updateWidget(widget.id, { x: -1 })).toThrow(/rejected geometry/) + expect(editor.getWidget(widget.id)?.x).toBe(10) + }) + + it('preserves bridge type/label overrides when updating field appearance', () => { + const { adapter, objects } = createOverlayAdapter() + const editor = createFormEditor({ + overlay: adapter, + bridgeOptions: { type: 'custom-box', label: 'Fixed' }, + }) + const field = editor.createField({ type: 'text', name: 'raw' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 1, + y: 1, + width: 10, + height: 10, + }) + + expect(objects[0]).toMatchObject({ + id: widget.elementId, + type: 'custom-box', + label: 'Fixed', + }) + + editor.updateField(field.id, { name: 'renamed', type: 'dropdown' }) + expect(adapter.updateObject).not.toHaveBeenCalledWith( + 0, + widget.elementId, + expect.objectContaining({ type: 'dropdown' }) + ) + expect(adapter.updateObject).not.toHaveBeenCalledWith( + 0, + widget.elementId, + expect.objectContaining({ label: 'renamed' }) + ) + }) + + it('preserves per-widget bridge overrides across updateField', () => { + const { adapter, objects } = createOverlayAdapter() + const editor = createFormEditor({ overlay: adapter }) + const field = editor.createField({ type: 'text', name: 'raw' }) + const widget = editor.placeWidget( + { + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 1, + y: 1, + width: 10, + height: 10, + }, + { bridgeOptions: { type: 'custom-box', label: 'Fixed' } } + ) + + expect(objects[0]).toMatchObject({ + id: widget.elementId, + type: 'custom-box', + label: 'Fixed', + }) + + editor.updateField(field.id, { name: 'renamed', type: 'dropdown' }) + expect(adapter.updateObject).not.toHaveBeenCalledWith( + 0, + widget.elementId, + expect.objectContaining({ type: 'dropdown' }) + ) + expect(adapter.updateObject).not.toHaveBeenCalledWith( + 0, + widget.elementId, + expect.objectContaining({ label: 'renamed' }) + ) + }) + + it('scopes overlay sync and lookup by document when element ids repeat', () => { + const editor = createFormEditor() + const field = editor.createField({ type: 'text', name: 'shared' }) + const first = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 1, + y: 1, + width: 10, + height: 10, + elementId: 'same', + }) + const second = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 1, + x: 2, + y: 2, + width: 10, + height: 10, + elementId: 'same', + }) + + const synced = editor.syncFromOverlay( + { id: 'same', x: 9, y: 9, width: 10, height: 10 }, + { pageIndex: 0, docIndex: 1 } + ) + expect(synced?.id).toBe(second.id) + expect(editor.getWidget(first.id)).toMatchObject({ x: 1, y: 1, docIndex: 0 }) + expect(editor.getWidget(second.id)).toMatchObject({ x: 9, y: 9, docIndex: 1 }) + expect(editor.getWidgetByElementId('same', 0)?.id).toBe(first.id) + expect(editor.getWidgetByElementId('same', 1)?.id).toBe(second.id) + }) + + it('rejects linking the same elementId to two widgets in one document', () => { + const { adapter } = createOverlayAdapter() + const editor = createFormEditor({ overlay: adapter }) + const field = editor.createField({ type: 'text', name: 'a' }) + editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 1, + y: 1, + width: 10, + height: 10, + elementId: 'shared-el', + }) + + expect(() => editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 2, + y: 2, + width: 10, + height: 10, + elementId: 'shared-el', + })).toThrow(/already linked/) + }) + + it('rejects elementId changes while overlay sync is enabled', () => { + const { adapter } = createOverlayAdapter() + const editor = createFormEditor({ overlay: adapter }) + const field = editor.createField({ type: 'text', name: 'a' }) + const widget = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 1, + y: 1, + width: 10, + height: 10, + }) + + expect(() => editor.updateWidget(widget.id, { elementId: 'other' })) + .toThrow(/elementId while syncing overlay/) + editor.updateWidget(widget.id, { elementId: 'other' }, { syncOverlay: false }) + expect(editor.getWidget(widget.id)?.elementId).toBe('other') + }) + + it('rejects duplicate elementId when changing docIndex or loading a model', () => { + const editor = createFormEditor() + const field = editor.createField({ type: 'text', name: 'a' }) + const first = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 0, + x: 1, + y: 1, + width: 10, + height: 10, + elementId: 'shared-el', + }) + const second = editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + docIndex: 1, + x: 2, + y: 2, + width: 10, + height: 10, + elementId: 'shared-el', + }) + + expect(() => editor.updateWidget( + second.id, + { docIndex: 0 }, + { syncOverlay: false } + )).toThrow(/already linked/) + + expect(() => editor.loadModel({ + fields: [{ + id: 'f1', + type: 'text', + name: 'n', + widgetIds: ['w1', 'w2'], + }], + widgets: [ + { + id: 'w1', + fieldId: 'f1', + pageIndex: 0, + docIndex: 0, + x: 1, + y: 1, + width: 10, + height: 10, + elementId: 'dup', + }, + { + id: 'w2', + fieldId: 'f1', + pageIndex: 1, + docIndex: 0, + x: 2, + y: 2, + width: 10, + height: 10, + elementId: 'dup', + }, + ], + })).toThrow(/Duplicate elementId/) + + expect(editor.getWidget(first.id)?.docIndex).toBe(0) + expect(editor.getWidget(second.id)?.docIndex).toBe(1) + }) +}) From 3fe527ac45899eb805f25123a067b508931e5ec6 Mon Sep 17 00:00:00 2001 From: Luis Amorim Date: Mon, 9 Nov 2026 10:44:27 -0300 Subject: [PATCH 2/3] docs(forms): document generic form-field editing API Add FORM_EDITING.md and cross-links covering the public editor session, overlay adapter contract, and coexistence with generic overlays. Signed-off-by: Luis Amorim --- README.md | 3 +- docs/API.md | 9 +++ docs/FORM_EDITING.md | 156 +++++++++++++++++++++++++++++++++++++++++++ docs/FORM_MODEL.md | 6 +- 4 files changed, 170 insertions(+), 4 deletions(-) create mode 100644 docs/FORM_EDITING.md diff --git a/README.md b/README.md index d110698..a675b13 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ A Vue 3 PDF viewer for building interactive document workflows with draggable, r Use it to build signature placement, form-field positioning, annotations, review tools, document preparation flows and other PDF experiences where users need to place or manipulate elements on top of a document. -**[Try the live demo](https://libresign.github.io/pdf-elements/)** · [Getting started](docs/GETTING_STARTED.md) · [API](docs/API.md) · [Form model](docs/FORM_MODEL.md) · [Examples](examples/) · [Contributing](CONTRIBUTING.md) +**[Try the live demo](https://libresign.github.io/pdf-elements/)** · [Getting started](docs/GETTING_STARTED.md) · [API](docs/API.md) · [Form model](docs/FORM_MODEL.md) · [Form editing](docs/FORM_EDITING.md) · [Examples](examples/) · [Contributing](CONTRIBUTING.md) ![The pdf-elements demo with a sample PDF loaded and a signature element placed on the first page](img/screenshot/demo.png) @@ -51,5 +51,6 @@ PDF Elements can be used for: - [Getting started](docs/GETTING_STARTED.md) - [API reference](docs/API.md) - [Form field and widget model](docs/FORM_MODEL.md) +- [Form field editing](docs/FORM_EDITING.md) - [Basic example](examples/basic/) - [Contributing](CONTRIBUTING.md) diff --git a/docs/API.md b/docs/API.md index 6e3fe7e..73e88a3 100644 --- a/docs/API.md +++ b/docs/API.md @@ -7,6 +7,8 @@ SPDX-License-Identifier: AGPL-3.0-or-later For the logical field / visual widget data model (plain serializable types, relationships and overlay coexistence), see [Form field and widget model](./FORM_MODEL.md). +For generic form-field editing on top of that model (create/place/select/update, multi-widget fields, overlay sync), see [Form field editing](./FORM_EDITING.md). + ## Props | Prop | Type | Default | Description | @@ -49,6 +51,13 @@ For the logical field / visual widget data model (plain serializable types, rela - `startAddingElement(templateObject)` - Starts interactive placement mode. - `cancelAdding()` - Cancels the current placement session and emits `pdf-elements:adding-ended` with `{ reason: 'cancelled' }` when a session was active. +- `addObjectToPage(object, pageIndex?, docIndex?)` - Places an overlay object programmatically. +- `getAllObjects(docIndex?)` - Returns overlay objects for a document. +- `updateObject(docIndex, objectId, payload)` - Updates overlay geometry or properties. +- `moveObjectToPage(docIndex, objectId, pageIndex, payload?)` - Moves an object between pages without emitting `pdf-elements:delete-object`. +- `deleteObject(docIndex, objectId)` / `duplicateObject(docIndex, objectId)` - Overlay lifecycle helpers. + +Form-field editing is not stored inside the Vue component. Use `createFormEditor({ overlay })` from the package entry and pass these methods through a `FormEditorOverlayAdapter`. See [Form field editing](./FORM_EDITING.md). ## Slots diff --git a/docs/FORM_EDITING.md b/docs/FORM_EDITING.md new file mode 100644 index 0000000..52a0ba6 --- /dev/null +++ b/docs/FORM_EDITING.md @@ -0,0 +1,156 @@ + + +# Form field editing + +Generic editing behavior for the [field/widget model](./FORM_MODEL.md). The editor is a plain TypeScript session: it owns a `PDFFormModel`, tracks logical selection, and optionally syncs visuals through the existing overlay API. It does not read Vue component internals. + +Concrete per-type controls (text input UX, checkbox toggling, radio exclusive selection UI, dropdown pickers) are out of scope here. Hosts reuse this foundation when adding those types. + +## Concepts + +| Concern | Owner | +|---------|--------| +| Shared field data (`value`, `required`, `options`, …) | `PDFFormField` via `createField` / `updateField` | +| Placement and widget-only data (`exportValue`, geometry) | `PDFFormWidget` via `placeWidget` / `updateWidget` | +| Visual rectangles | Optional `FormEditorOverlayAdapter` → `PDFElements` methods | +| Logical selection | `selectField` / `selectWidget` on the editor session | + +One field may have many widgets. Selecting a widget also selects its field. Non-form overlays continue to use `PDFElementObject` alone. + +## Quick start + +```ts +import { + createFormEditor, + createFormEditorOverlayAdapter, + type PDFElementsPublicApi, +} from '@libresign/pdf-elements' + +const overlay = pdfRef.value as PDFElementsPublicApi +const editor = createFormEditor({ + // Prefer the helper: it recovers rewritten ids after addObjectToPage collisions. + overlay: createFormEditorOverlayAdapter(overlay), +}) + +const field = editor.createField({ + type: 'radio', + name: 'color', + options: [ + { value: 'red', label: 'Red' }, + { value: 'blue', label: 'Blue' }, + ], + required: true, +}) + +editor.placeWidget({ + fieldId: field.id, + pageIndex: 0, + x: 40, + y: 80, + width: 18, + height: 18, + exportValue: 'red', +}) + +editor.placeWidget({ + fieldId: field.id, + pageIndex: 1, + x: 40, + y: 120, + width: 18, + height: 18, + exportValue: 'blue', +}) + +editor.selectWidget(editor.getWidgetsForField(field.id)[0].id) +editor.updateField(field.id, { value: 'red' }) +``` + +## Interactive placement + +1. `editor.beginPlaceWidget({ fieldId, width, height, exportValue })` starts overlay placement when an adapter with `startAddingElement` is configured. +2. Listen for `pdf-elements:adding-ended`. +3. On `{ reason: 'placed', object, pageIndex, docIndex }`, call `editor.completeWidgetPlacement({ object, pageIndex, docIndex })`. +4. On cancel, call `editor.cancelPlaceWidget()` (also used if the host cancels placement). + +`completeWidgetPlacement` only updates the form model and links `widget.elementId` to the placed overlay id. It does not add a second overlay rectangle. + +`loadModel` and a second `beginPlaceWidget` cancel any in-progress overlay adding session before replacing editor state. + +## Move / resize + +Supported foundation path: programmatic `updateWidget` (optionally synced to the overlay) and host-driven `syncFromOverlay` when the host already knows the new geometry. + +`PDFElements` drag/resize currently updates overlays internally without a dedicated public geometry event. Until such an event exists, hosts that need canvas drag to update the form model must observe their own integration points and call: + +```ts +editor.syncFromOverlay(object, { pageIndex, docIndex }) +``` + +Matching uses `widget.elementId`. `widget.id` is used only when `elementId` is absent. + +When deleting from the overlay UI, listen for `pdf-elements:delete-object` and call `editor.removeWidget(...)` (or `removeField`) so the model stays aligned. Skip that removal while `overlay.isInternalMutation?.()` is true: spill rollback may restore page membership without a user delete. Prefer `createFormEditorOverlayAdapter`, which uses `moveObjectToPage` (no delete event) for that restore. + +### Page / document changes + +With overlay sync enabled, `updateWidget` **rejects** `pageIndex` / `docIndex` / `elementId` changes. Relocate by removing and re-placing the widget, or pass `{ syncOverlay: false }` and update visuals yourself. + +Programmatic geometry updates that would make `PDFElements` move the rectangle to another page are treated as failure by `createFormEditorOverlayAdapter`: the helper restores the object on the original page via `moveObjectToPage` (without emitting `pdf-elements:delete-object`), then returns `false` so the editor rolls the widget back. + +`loadModel` and editor construction reject models that reuse the same `elementId` inside one document. Changing `docIndex` with `{ syncOverlay: false }` also re-checks that invariant. + +## Model access + +| Method | Meaning | +|--------|---------| +| `getModel()` | Live session store. Mutating it bypasses overlay sync and editor invariants. | +| `getSnapshot()` | Deep JSON clone for persistence / transport. | +| `loadModel(...)` | Replaces the session via `parseFormModel` (relationship checks included) and cancels placement. | + +`createField` does not accept pre-filled `widgetIds`. Attach visuals with `placeWidget`. + +## Overlay adapter notes + +- Prefer `createFormEditorOverlayAdapter(pdf)` so rewritten ids after collisions are recovered. +- That helper also re-reads overlay geometry after `updateObject`. If `PDFElements` drops or relocates the write, the helper restores the previous geometry when possible and returns `false`, so the editor can roll the widget back. +- If you hand-roll an adapter, return the **stored** object from `addObjectToPage` whenever ids may change. Returning bare `true` is only safe when the submitted id was kept. +- Optional `hasObject(docIndex, objectId, pageIndex?)` lets the editor link to an existing rectangle without inserting a duplicate. +- An `elementId` may be linked to only one widget. `syncFromOverlay` / `getWidgetByElementId` accept `docIndex` when the same id appears in more than one document. +- Optional `updateObject` may return `false` to reject geometry; the editor then rolls the widget back. +- If `updateObject` / `deleteObject` are omitted, model edits still succeed and overlay cleanup is skipped (orphan overlays possible). + +Session `bridgeOptions` and per-`placeWidget` / `beginPlaceWidget` `bridgeOptions` (`type` / `label`) are remembered for appearance sync after `updateField`. + +## Public surface + +```ts +import { + createFormEditor, + createFormEditorOverlayAdapter, +} from '@libresign/pdf-elements' +import type { + FormEditorOverlayAdapter, + FormEditorSelection, + FormFieldUpdate, + FormWidgetUpdate, + PDFFormEditor, +} from '@libresign/pdf-elements' +``` + +| Method | Role | +|--------|------| +| `createField` / `updateField` / `removeField` | Field lifecycle and shared properties | +| `placeWidget` / `updateWidget` / `removeWidget` | Widget lifecycle and placement | +| `beginPlaceWidget` / `completeWidgetPlacement` / `cancelPlaceWidget` | Interactive placement | +| `selectField` / `selectWidget` / `getSelection` | Logical selection | +| `syncFromOverlay` | Copy overlay geometry onto the linked widget | +| `getModel` / `getSnapshot` / `loadModel` | Live store vs persistence | + +## Compatibility + +- Generic signature/annotation overlays keep using `PDFElements` as before. +- Form editing is additive: omit the overlay adapter for model-only editing. +- Do not store LibreSign/Nextcloud workflow concepts on fields or widgets; use `metadata` or host state outside this package. diff --git a/docs/FORM_MODEL.md b/docs/FORM_MODEL.md index e188b89..cdb9c00 100644 --- a/docs/FORM_MODEL.md +++ b/docs/FORM_MODEL.md @@ -145,7 +145,7 @@ If a host previously encoded form semantics only on overlay objects (for example 1. Create `PDFFormField` entries for shared properties (`type`, `name`, value, required, options). 2. Create one `PDFFormWidget` per visual rectangle, including `pageIndex` and geometry. -3. Optionally set `elementId` to the existing overlay object id so the editor can keep using `PDFElementObject` until form editing lands (#85). +3. Optionally set `elementId` to the existing overlay object id so the editor can keep using `PDFElementObject` while adopting form editing ([Form field editing](./FORM_EDITING.md)). 4. Stop duplicating field-level properties onto each overlay object once the form model is the source of truth. ## Out of scope @@ -154,9 +154,9 @@ This package model does **not** implement: - PDF AcroForm parsing or writing - PDF mutation or cryptographic signing -- Full per-type editor behavior (tracked separately) +- Full per-type editor behavior (text/checkbox/radio/dropdown UX) -Those belong outside this issue and, for editor behavior, in follow-up work that builds on this model. +Generic create/place/select/update editing that reuses this model lives in [Form field editing](./FORM_EDITING.md). Per-type controls remain follow-up work. Parsing validates required properties, finite geometry, non-negative integer page/document indices, non-negative sizes and plain JSON data (including metadata). Runtime objects, From ab333470894c5d172464c50381f1c42812c864c0 Mon Sep 17 00:00:00 2001 From: Luis Amorim Date: Mon, 9 Nov 2026 12:30:13 -0300 Subject: [PATCH 3/3] fix(forms): harden spill restore and placement commit Signed-off-by: Luis Amorim --- src/types.ts | 3 ++- src/utils/formEditing.ts | 34 ++++++++++++++++++++++++++-------- 2 files changed, 28 insertions(+), 9 deletions(-) diff --git a/src/types.ts b/src/types.ts index ae36d2a..ce2f109 100644 --- a/src/types.ts +++ b/src/types.ts @@ -51,8 +51,9 @@ export interface PDFElementsPublicApi { * Moves an overlay object to another page in the same document without emitting * `pdf-elements:delete-object`. Used for internal restoration (for example form * editor spill rollback) so hosts do not treat the move as a user delete. + * Optional for 1.x typed wrappers; {@link PDFElements} implements it. */ - moveObjectToPage: ( + moveObjectToPage?: ( docIndex: number, objectId: string, pageIndex: number, diff --git a/src/utils/formEditing.ts b/src/utils/formEditing.ts index 7480d7a..41bf180 100644 --- a/src/utils/formEditing.ts +++ b/src/utils/formEditing.ts @@ -311,9 +311,11 @@ export function createFormEditorOverlayAdapter( return snapshot.pageIndex === pageIndex }) }, - moveObjectToPage: (docIndex, objectId, pageIndex, payload) => ( - api.moveObjectToPage(docIndex, objectId, pageIndex, payload) - ), + moveObjectToPage: (docIndex, objectId, pageIndex, payload) => { + const move = api.moveObjectToPage + if (typeof move !== 'function') return false + return move(docIndex, objectId, pageIndex, payload) + }, updateObject: (docIndex, objectId, payload) => { const before = api.getAllObjects(docIndex) .find((entry) => entry.id === objectId) as OverlayObjectSnapshot | undefined @@ -350,18 +352,32 @@ export function createFormEditorOverlayAdapter( ) { return runInternalMutation(() => { // Prefer silent page restore so hosts do not treat rollback as a user delete. + const move = api.moveObjectToPage if ( - typeof api.moveObjectToPage === 'function' - && api.moveObjectToPage(docIndex, objectId, previousPageIndex, previous) + typeof move === 'function' + && move(docIndex, objectId, previousPageIndex, previous) ) { return false } // Fallback when moveObjectToPage is missing or returns false. // Hosts must honor isInternalMutation() if they sync delete-object → removeWidget. + const spilledPageIndex = after.pageIndex + const spilledGeometry = { + x: after.x, + y: after.y, + width: after.width, + height: after.height, + } api.deleteObject(docIndex, objectId) const restored = toPlainOverlayElement(before, previous) restored.id = objectId - api.addObjectToPage(restored, previousPageIndex, docIndex) + if (api.addObjectToPage(restored, previousPageIndex, docIndex)) { + return false + } + // Keep a visual if the original page rejects the restore. + const spilled = toPlainOverlayElement(after, spilledGeometry) + spilled.id = objectId + api.addObjectToPage(spilled, spilledPageIndex, docIndex) return false }) } @@ -751,12 +767,14 @@ export function createFormEditor( } if (object.id) widgetInput.elementId = object.id - pendingPlacement = null // Overlay already contains the placed object; only update the form model. - return placeWidget(widgetInput, { + // Keep pendingPlacement until place succeeds so hosts can retry or cancel. + const widget = placeWidget(widgetInput, { syncOverlay: false, bridgeOptions, }) + pendingPlacement = null + return widget } const cancelPlaceWidget = () => {