fix(pdf-server): radio groups misclassified as PDFCheckBox save the chosen widget

Some PDFs (e.g. third-party forms like the IRS f1040 family, and the
demo Form.pdf) omit the /Ff Radio flag bit on button fields, so pdf-lib
classifies a multi-widget radio as PDFCheckBox. The viewer stores
pdf.js's buttonValue (the widget's on-state name, e.g. '0'/'1') as a
string. The PDFCheckBox branch did 'if (value) field.check()', which
always sets the FIRST widget's on-state - so any choice saved as the
first option.

When the value is a string on a PDFCheckBox, treat it as a radio
on-value: write /V and per-widget /AS directly via the low-level
acroField (mirroring PDFAcroRadioButton.setValue minus its
first-widget-only onValues guard). Booleans keep check()/uncheck().

Test: build a radio fixture, clear the Radio flag so reload sees
PDFCheckBox, save with '1', assert /V = /1 and second widget /AS = /1.

Author: ochafik

examples/pdf-server/src/pdf-annotations.test.ts

@@ -1133,6 +1133,48 @@ describe("buildAnnotatedPdfBytes", () => {
       // The throwing field is left at whatever pdf-lib could do with it —
       // we only assert it didn't poison "after".
     });
+
+    it("radio misclassified as PDFCheckBox: string value selects the matching widget", async () => {
+      // Some PDFs (e.g. IRS/third-party forms) omit the /Ff Radio bit, so
+      // pdf-lib hands us a PDFCheckBox. The viewer stored pdf.js's
+      // buttonValue ("0"/"1"), not a boolean — check() would always pick
+      // the first widget. setButtonGroupValue writes /V + per-widget /AS
+      // directly so the chosen widget sticks.
+      const doc = await PDFDocument.create();
+      const page = doc.addPage([612, 792]);
+      const form = doc.getForm();
+      const rg = form.createRadioGroup("Gender");
+      rg.addOptionToPage("Male", page, { x: 10, y: 700 });
+      rg.addOptionToPage("Female", page, { x: 60, y: 700 });
+      // pdf-lib's addOptionToPage writes widget on-values "0","1". Clear the
+      // Radio flag (bit 16) so the reloaded form classifies it as checkbox.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (rg.acroField as any).clearFlag(1 << 15);
+      const fixture = await doc.save();
+
+      // Sanity: reload sees it as PDFCheckBox now.
+      const reForm = (await PDFDocument.load(fixture)).getForm();
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const reField = reForm.getFieldMaybe("Gender") as any;
+      expect(reField?.constructor?.name).toBe("PDFCheckBox");
+
+      const out = await buildAnnotatedPdfBytes(
+        fixture,
+        [],
+        new Map<string, string | boolean>([["Gender", "1"]]),
+      );
+
+      const saved = await PDFDocument.load(out);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const acro = (saved.getForm().getFieldMaybe("Gender") as any).acroField;
+      const v = acro.dict.get(PDFName.of("V"));
+      expect(v).toBeInstanceOf(PDFName);
+      expect((v as PDFName).decodeText()).toBe("1");
+      // Second widget /AS is the on-state, first is /Off.
+      const widgets = acro.getWidgets();
+      expect(widgets[0].getAppearanceState()?.decodeText()).toBe("Off");
+      expect(widgets[1].getAppearanceState()?.decodeText()).toBe("1");
+    });
   });
 });
 

examples/pdf-server/src/pdf-annotations.ts

@@ -801,6 +801,40 @@ export async function addAnnotationDicts(
   }
 }
 
+/**
+ * Select a radio-style button group by widget on-value, bypassing pdf-lib's
+ * type-level guards. Used when pdf-lib classifies a radio as `PDFCheckBox`
+ * (PDF lacks the /Ff Radio bit) — `check()` would always pick the first
+ * widget. Mirrors `PDFAcroRadioButton.setValue` minus its `onValues` throw.
+ */
+function setButtonGroupValue(
+  field: PDFCheckBox | PDFRadioGroup,
+  onValue: string,
+): void {
+  const acro = field.acroField;
+  const off = PDFName.of("Off");
+  const widgets = acro.getWidgets();
+  // Match by PDFName identity (pdf-lib interns names) — the viewer stored
+  // pdf.js's buttonValue, which IS the widget's /AP /N on-state name.
+  let target = onValue && onValue !== "Off" ? PDFName.of(onValue) : off;
+  if (
+    target !== off &&
+    !widgets.some((w: { getOnValue(): PDFName | undefined }) => {
+      return w.getOnValue() === target;
+    })
+  ) {
+    // No widget has this on-state — leave as-is rather than corrupt /V.
+    return;
+  }
+  acro.dict.set(PDFName.of("V"), target);
+  for (const w of widgets) {
+    const on = (w as { getOnValue(): PDFName | undefined }).getOnValue();
+    (w as { setAppearanceState(s: PDFName): void }).setAppearanceState(
+      on === target ? target : off,
+    );
+  }
+}
+
 /**
  * Build annotated PDF bytes from the original document.
  * Applies user annotations and form fills, returns Uint8Array of the new PDF.
@@ -836,8 +870,20 @@ export async function buildAnnotatedPdfBytes(
           if (!field) continue;
 
           if (field instanceof PDFCheckBox) {
-            if (value) field.check();
-            else field.uncheck();
+            if (typeof value === "string") {
+              // A string value on a "checkbox" means pdf-lib misclassified a
+              // radio group (PDF lacks the /Ff Radio flag bit). The viewer
+              // stored pdf.js's buttonValue, which is the widget's appearance
+              // on-state name (e.g. "0"/"1"). check()/uncheck() would set the
+              // FIRST widget's on-state regardless, so write /V and per-widget
+              // /AS directly — same as PDFAcroRadioButton.setValue but without
+              // its onValues guard (which checks the first widget only).
+              setButtonGroupValue(field, value);
+            } else if (value) {
+              field.check();
+            } else {
+              field.uncheck();
+            }
           } else if (field instanceof PDFRadioGroup) {
             // The viewer stores pdf.js's buttonValue, which for PDFs with an
             // /Opt array is a numeric index ("0","1","2") rather than the