Define a stable form field and widget data model

[vitormattos]

Before adding individual form field types, pdf-elements needs a stable data model that can represent both generic editor elements and PDF form concepts without coupling the library to LibreSign or Nextcloud.

The current PDFElementObject mainly represents one visual rectangle on one page. PDF forms need an additional distinction: a logical field can have one or more visual widgets. This is important for cases such as radio groups, repeated fields and the same field appearing on different pages.

This issue depends on #80 so the public type changes are protected by the improved type checking and package validation.

What should be done

Separate logical fields from visual widgets

A visual element must not be treated as the complete logical form field.

The model should support:

• one logical field with one widget;
• one logical field with multiple widgets;
• widgets on different pages;
• radio groups where several widgets belong to the same field;
• unknown or future field types without losing their identity.

Keep coordinates and page placement on the visual/widget side. Keep shared field properties on the logical field side.

Define stable public types

Define the minimum public types needed to represent fields and widgets, including stable identifiers and their relationship.

The field model should be able to represent, where applicable:

• type;
• name;
• value and default value;
• required and read-only states;
• options for choice fields;
• extensible metadata for information that does not belong to the core model.

Do not add LibreSign workflow concepts such as recipients, envelopes, signing policies or participant roles to the core library model.

Preserve the generic element use case

pdf-elements must remain useful as a generic Vue 3 PDF overlay editor, including for consumers that do not use PDF forms.

Review how the new field/widget model should coexist with the current PDFElementObject API. Prefer an incremental and understandable evolution over replacing the current public API without need.

If a breaking change is required, document why and define a clear migration path before implementing it.

Define serialization expectations

The public model should be plain serializable data and must not depend on Vue component instances, DOM objects or PDF.js runtime objects.

Document enough of the model so consumers can persist it and restore it later without depending on internal component state.

Do not implement PDF AcroForm parsing or writing in this issue. The model should be able to represent imported form information later, but PDF file mutation belongs outside this package.

Acceptance criteria

• Logical fields and visual widgets are represented as separate concepts.
• One field can reference multiple widgets, including widgets on different pages.
• Stable IDs exist for fields and widgets.
• Shared field properties are not duplicated as visual placement properties.
• The model can represent values, defaults, required/read-only state and choice options where applicable.
• Unknown or future field types can be represented safely.
• The model remains generic and contains no LibreSign- or Nextcloud-specific workflow concepts.
• Existing non-form overlay use cases remain supported.
• Public data is serializable without Vue, DOM or PDF.js runtime objects.
• Public types and their relationships are documented.
• Compatibility with the current PDFElementObject API is reviewed and any required migration is documented.
• Tests cover the model relationships and serialization behavior.
• PDF parsing, AcroForm writing and signing remain outside the scope of this issue.

Additional context

• If you have questions, feel free to ask in this issue.
• Give a ⭐️ to pdf-elements if you find the package useful.
• You can also support the project by giving a ⭐️ to LibreSign.