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

Example Package (install via GitHub)

-> silentsolutionsdigital#2

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2493b99

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?

[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

[chrisdevereux]

would be great to get this reviewed and merged if possible!

[natterstefan]

would be great to get this reviewed and merged if possible!

Hi, I agree with you and I hope we can merge it soon. We need it as well urgently in one of our projects.

@diegomura please, take a look and let's get this done! ✅ thank you

[natterstefan]

Hey @diegomura. I would be happy if you could give feedback in the next few days. I think some people are waiting for this a well. We also had to use a temporary workaround to be able to use it for our customers already. Please let me know where and how I can help you. Thank you and have a nice day.

[jub-nick]

Hey, I would love to see this getting merged.
@natterstefan Is there any way, that you could expand the scope of this pull request a bit and add the possibility to embed signature fields?
If I understand it correctly pdfkit needs to be extended here. According to the Acrobat Javascript API reference the field type would be signature.
Would love to hear your opinion on this. Thanks in advance!

[natterstefan]

Hi @jub-nick,

Thanks for your interest! I appreciate the suggestion to expand the scope of this pull request to include signature fields. It sounds interesting and I am sure it would add even more value to react-pdf.

However, at the moment, I suggest adding another PR for your request to get this PR live asap. I am also not 100% sure if I added all supported props of the signature field. Having said that here is a draft PR that is ready once this one is merged: silentsolutionsdigital#3.

Additionally I added another one for radiobutton but that one is not working yet, especially on macOS: silentsolutionsdigital#4. I am also more than happy to prepare it further once this PR is merged.

Looking forward to any contributions—thanks again for your input!

[diegomura]

Thanks for the hard work here! And I apologize again for the delays 😞 It's been very hard to find time lately. I'll take care of the small rename in a separate PR so we can merge this now

If you guys can work on the docs that would be great 🙏🏻