feat: added Form Annotation support

[natterstefan]

Tasks

• fix dependency cycle (also mentioned here). @diegomura: I am not sure how though... #need-help
• discuss component names (see feat: added Form Annotation support #2845 (comment), and feat: added Form Annotation support #2845 (comment))
• fix macOS (feat: added Form Annotation support #2845 (comment))

Related PR

• Form Annotation Docs react-pdf-site#145

Notes

• based on the September 2022 PR feat: add Form Annotation support #2013 initially started by @axel7083
• used @runelk's branch as the base branch for this one
• applied initForm fix by @kjossendal, see feat: add Form Annotation support #2013 (comment)

Docs

• https://pdfkit.org/docs/forms.html

Example PDF

Example 2.0.pdf

[changeset-bot]

⚠️ No Changeset found

Latest commit: 944c020

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[natterstefan]

What do you think of keeping the initial names of these components to keep them aligned with the form annotation methods of PDFKit?

formText( name, x, y, width, height, options)
formPushButton( name, x, y, width, height, name, options)
formCombo( name, x, y, width, height, options)
formList( name, x, y, width, height, options)

(src)

[PhilippBloss]

Right now, push buttons don't have any purpose. They are only there to exist. They cannot hold any value. There should be an option for the user to specify an 8.6.4 action (from PDF Reference 1.7) for this button. Even if it's just on a basic level. Going too detailed e.g. with 8.5.3 actions would go beyond the scope of the pr. What do you think?

[diegomura]

@PhilippBloss thanks for the review here. Would love to take this to the finish line. Are you still open to take care of the docs? 🙏🏻

[PhilippBloss]

@PhilippBloss thanks for the review here. Would love to take this to the finish line. Are you still open to take care of the docs? 🙏🏻

Initially I wanted to wait for a decision on the component names, but I made a todo: diegomura/react-pdf-site#145

[natterstefan]

Hi @diegomura,
Hi @PhilippBloss,

I just made the branch compatible with 4.x and took care of @PhilippBloss' feedback. The only that is left now is deciding which names we choose for the components:

Option 1 - align with pdfkit

• <FormField />
• <FormText />
• <FormCombo />
• <FormCheckbox />
• <FormList />

Option 2 - web standards

• <Fieldset />
• <InputText /> (not 100% aligned as it would be <input type="text" />)
• <Select />
• <Checkbox /> (Alternative InputCheckbox, anyway not 100% aligned as it would be <input type="checkbox" />)
• <List /> (also not 100% aligned but there are ol and ul lists)

I favour Option 1 more as there is a connect to the used library used for forms. What do you think?

(previous discussion: #2845 (comment), and #2845 (comment))

[natterstefan]

Hey @diegomura, Hey @PhilippBloss,

can you take a look at my last thoughts please? Thank you!

[natterstefan]

**Reminder**

Hey @diegomura, Hey @PhilippBloss,

can you take a look at my last thoughts please? Thank you!

[diegomura]

Hi @natterstefan

Sorry for my slow response here. I took a long vacation on the last couple of weeks.

Thanks for listing both options. In my opinion something like option 2 is what we need. Being coherent with pdfkit is not really important, as pdfkit is an implementation detail and not something users are really aware of.

React-pdf always followed react-native primitives, so if an element is already defined there we should use the same naming (ex. TextInput instead of InputText or FormText)

[natterstefan]

Hi @diegomura,

no worries. I hope you had a wonderful time. :)

This seems reasonable and let's follow that approach here as well.

It works for text input, but what about other components of this PR?

Checkbox is not part of react native anymore: https://reactnative.dev/docs/checkbox, also forms in general.

[diegomura]

Thanks @natterstefan !

Here are my thoughts:

• FormField: Why do we need this one? It's not semantic nor clear what this does for the user. Pdfkit docs says that to express hierarchy a name can be passed to each form element
• TextInput: Like the react-native primitive
• Select: not in primitives but good name
• Checkbox: not in primitives but good name
• List: Can be merged with Select maybe, and add a type="list" prop? I feel they are basically the same element, it's just rendered differently

[natterstefan]

Hi @diegomura,

let's see what I can add to our discussion.

• FormField: Why do we need this one? It's not semantic nor clear what this does for the user. Pdfkit docs says that to express hierarchy a name can be passed to each form element

That is true, it's usefulness is "limited" (possibly an uninformed opinion) to creating a hierarchy of nodes as this can be achieved with name only as well. Setting defaults (such as the default font) for all child form annotations (docs) is another feature. I understand that you question its purpose in the react-pdf context. Maybe if we can answer this you can make the final decision: Does FormField help creating a cleaner, more hierarchical PDF (e.g. using parent of pdfkit)? If one prefers another component layer instead of using name only then yes. Does it help to simplify shared styling/attributes? Yes, but one can achieve this also by sharing props or styles (correct?). So what about removing it and if people request it add it (again) in another release?

Edit: but if we remove it, do we need to keep https://github.com/traveltechdeluxe/react-pdf/blob/0b6f34ed42101aedbefe6c5dd74d6e542ebca51b/packages/pdfkit/src/mixins/acroform.js#L105-L117?
Edit 2: I would keep them for now and consider deprecating them later if feedback suggests they add no value.

• TextInput: Like the react-native primitive
• Select: not in primitives but good name
• Checkbox: not in primitives but good name

Works for me.

• List: Can be merged with Select maybe, and add a type="list" prop? I feel they are basically the same element, it's just rendered differently

They even share the same props as far as I am aware of. Sounds reasonable. What about type="combo|list then as possible type values (in sync with pdfkit)?

Edit: After reconsidering it during the merge, I believe it’s better to keep the two separate (List and Select). This approach not only simplifies the overall structure but also reduces the number of branches in the code, making it easier to maintain and debug. By maintaining clear separation, it also improves readability and ensures that each function (aka Component) has a distinct responsibility, although they look similar.

[natterstefan]

Hey @diegomura, 👋

Have you seen my reply? I am hopeful that this will be merged asap. :)

[natterstefan]

Hi @diegomura, please take a look at my latest changes and edited answer thoughts here. //cc @PhilippBloss