feat: add a hidden option for a form field's visibility - #1791
Merged
blikblum merged 1 commit intoSep 5, 2026
Conversation
KaiPressmar
changed the title
pdfkit deliberately restricted AcroForm options to documented mappings and a small set of raw escape hatches, with a stated intent to shrink and eventually remove even those. Building a field that starts hidden (e.g. for an interactive action to reveal later) had no supported way to reach the API at all: the Widget annotation's own visibility flags (F, distinct from the field's own Ff flags) are always defaulted to 4 (print only) with no override. Add a dedicated hidden option instead, consistent with the project's stated direction of adding purpose-built options rather than widening raw dictionary access: it needs no PDF dictionary or flag-value knowledge, and reads as what it does.
KaiPressmar
force-pushed
the
acroform-annotation-flag-option
branch
from
September 5, 2026 12:13
b5177c7 to
4c1883a
Compare
KaiPressmar
changed the title
Contributor
Author
|
Updated: same reasoning as #1790 — replaced the raw |
Contributor
Author
|
Note: the f-before.pdf/f-after.pdf attached above were built against an earlier version of this PR (a raw |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What kind of change does this PR introduce?
Feature. Fixes #1793.
A small, purpose-built option, along the lines invited in
docs/forms.md's Advanced Form Field Use section ("If an option is not supported, open an issue on Github and it will be considered for addition to the API").Context
There's no supported way to build a field that starts hidden — e.g. one an interactive action (see #1790) reveals later. The Widget annotation's own visibility/print flags (
F, distinct from the field's ownFfflags) are always defaulted to4(print only) byformAnnotation(), with no override, and no option maps toFat all.The change
Adds a
hiddenoption, accepted by all form annotation methods, mapped by a newmapVisibility(options, pdfObject)step (mirroring the other unconditional mappers):hidden: truesetsFto6(Hidden + Print — not shown or interactive until revealed, but still printable once it is), instead of the usual default of4.Demo
Attached: a minimal PDF pair (two push buttons, one built with
hidden: true, before/after this change) plus screenshots from Adobe Acrobat/Reader. Before: both buttons show. After: the one built withhidden: trueis actually hidden.Testing
yarn test:unit— all existing tests pass unchanged, plus two new ones: a field built withhidden: true, and confirming the usual default still applies when it isn't given.yarn lint/yarn format— clean.Checklist:
cc @blikblum for review.