pdf-lite 1.6.4 → 1.7.1

package/dist/acroform/appearance/pdf-button-appearance-stream.js

@@ -39,7 +39,7 @@ export class PdfButtonAppearanceStream extends PdfAppearanceStream {
             g.restore();
         }
         else {
-            const checkSize = size * 0.8;
+            const checkSize = size * 0.65;
             const offset = (size - checkSize) / 2;
             g.save();
             g.beginText();

package/dist/acroform/appearance/pdf-graphics.d.ts

@@ -1,5 +1,15 @@
 import type { PdfDefaultAppearance } from '../fields/pdf-default-appearance.js';
 import { PdfFont } from '../../fonts/pdf-font.js';
+/**
+ * Resource names of font variants to use when rendering styled markdown segments.
+ * When a variant is provided, the appearance stream switches fonts instead of
+ * simulating bold/italic via stroke width or matrix shear.
+ */
+export interface FontVariantNames {
+    bold?: string;
+    italic?: string;
+    boldItalic?: string;
+}
 /**
  * Lightweight builder for PDF content streams.
  * Chains PDF operators via a fluent API and emits the final stream with build().
@@ -9,9 +19,11 @@ export declare class PdfGraphics {
     private lines;
     private resolvedFonts?;
     private defaultAppearance?;
+    private fontVariantNames?;
     constructor(options?: {
         resolvedFonts?: Map<string, PdfFont>;
         defaultAppearance?: PdfDefaultAppearance;
+        fontVariantNames?: FontVariantNames;
     });
     save(): this;
     restore(): this;
@@ -33,6 +45,40 @@ export declare class PdfGraphics {
     fill(): this;
     stroke(): this;
     closePath(): this;
+    static readonly ITALIC_SHEAR = 0.267;
+    static readonly BOLD_STROKE_RATIO = 0.04;
+    /**
+     * Re-attributes styled segments to wrapped lines by tracking character
+     * positions in the flat plain-text. One whitespace character is consumed
+     * at each line boundary (space from word-wrap or newline from paragraph).
+     */
+    private static splitSegmentsToLines;
+    /**
+     * Returns the resource name of the best-matching font variant for the given
+     * bold/italic flags, or undefined if no variant fonts are configured.
+     */
+    private resolveVariantFontName;
+    /**
+     * Measures text width using a specific font from resolvedFonts by resource
+     * name, falling back to measureTextWidth (regular font) if not found.
+     */
+    measureTextWidthWithFont(text: string, fontName: string | undefined, fontSize: number): number;
+    /**
+     * Emits styled text segments into the current BT…ET block.
+     * When font variants are configured, switches fonts mid-stream for true
+     * bold/italic rendering. Falls back to stroke simulation / Tm shear when
+     * no variant fonts are provided (backward compatible).
+     * Each segment is positioned with an absolute Tm so no prior Td is needed.
+     */
+    private showSegments;
+    /**
+     * Parses a markdown string and renders the styled segments into the current
+     * BT…ET block. Pass `multiline` to wrap across multiple lines.
+     */
+    showMarkdown(markdown: string, isUnicode: boolean, reverseEncodingMap: Map<string, number> | undefined, x: number, y: number, fontSize: number, multiline?: {
+        availableWidth: number;
+        lineHeight: number;
+    }): this;
     build(): string;
     private get currentFont();
     /**
@@ -41,6 +87,8 @@ export declare class PdfGraphics {
     measureTextWidth(text: string, fontSize?: number): number;
     /**
      * Wrap text to fit within the specified width, breaking at word boundaries.
+     * When a bold font variant is configured, uses its metrics conservatively
+     * to prevent bold glyphs from overflowing field bounds.
      */
     wrapTextToLines(text: string, maxWidth: number, fontSize?: number): string[];
     /**

package/dist/acroform/appearance/pdf-graphics.js

@@ -1,5 +1,6 @@
 import { encodePdfText } from '../../utils/encodePdfText.js';
 import { PdfFont } from '../../fonts/pdf-font.js';
+import { parseMarkdownSegments, } from '../../utils/parse-markdown-segments.js';
 /**
  * Lightweight builder for PDF content streams.
  * Chains PDF operators via a fluent API and emits the final stream with build().
@@ -9,9 +10,11 @@ export class PdfGraphics {
     lines = [];
     resolvedFonts;
     defaultAppearance;
+    fontVariantNames;
     constructor(options) {
         this.resolvedFonts = options?.resolvedFonts;
         this.defaultAppearance = options?.defaultAppearance;
+        this.fontVariantNames = options?.fontVariantNames;
     }
     save() {
         this.lines.push('q');
@@ -94,6 +97,160 @@ export class PdfGraphics {
         this.lines.push('h');
         return this;
     }
+    // Italic shear: ≈ tan(15°), applied as the c component of the Tm matrix.
+    static ITALIC_SHEAR = 0.267;
+    // Bold stroke width as a fraction of font size (0.04 × 12pt = 0.48pt stroke).
+    static BOLD_STROKE_RATIO = 0.04;
+    /**
+     * Re-attributes styled segments to wrapped lines by tracking character
+     * positions in the flat plain-text. One whitespace character is consumed
+     * at each line boundary (space from word-wrap or newline from paragraph).
+     */
+    static splitSegmentsToLines(segments, lines) {
+        const chars = [];
+        for (const seg of segments) {
+            for (const char of seg.text) {
+                chars.push({ char, bold: seg.bold, italic: seg.italic });
+            }
+        }
+        const result = [];
+        let pos = 0;
+        for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+            if (lineIdx > 0 && pos < chars.length) {
+                const c = chars[pos].char;
+                if (c === ' ' || c === '\n' || c === '\r')
+                    pos++;
+            }
+            const lineSegs = [];
+            let curText = '';
+            let curBold = false;
+            let curItalic = false;
+            const lineLen = lines[lineIdx].replace(/\r/g, '').length;
+            for (let j = 0; j < lineLen && pos < chars.length; j++, pos++) {
+                const { char, bold, italic } = chars[pos];
+                if (curText === '') {
+                    curText = char;
+                    curBold = bold;
+                    curItalic = italic;
+                }
+                else if (bold !== curBold || italic !== curItalic) {
+                    lineSegs.push({
+                        text: curText,
+                        bold: curBold,
+                        italic: curItalic,
+                    });
+                    curText = char;
+                    curBold = bold;
+                    curItalic = italic;
+                }
+                else {
+                    curText += char;
+                }
+            }
+            if (curText)
+                lineSegs.push({
+                    text: curText,
+                    bold: curBold,
+                    italic: curItalic,
+                });
+            result.push(lineSegs);
+        }
+        return result;
+    }
+    /**
+     * Returns the resource name of the best-matching font variant for the given
+     * bold/italic flags, or undefined if no variant fonts are configured.
+     */
+    resolveVariantFontName(bold, italic) {
+        if (bold && italic && this.fontVariantNames?.boldItalic)
+            return this.fontVariantNames.boldItalic;
+        if (bold && this.fontVariantNames?.bold)
+            return this.fontVariantNames.bold;
+        if (italic && this.fontVariantNames?.italic)
+            return this.fontVariantNames.italic;
+        return undefined;
+    }
+    /**
+     * Measures text width using a specific font from resolvedFonts by resource
+     * name, falling back to measureTextWidth (regular font) if not found.
+     */
+    measureTextWidthWithFont(text, fontName, fontSize) {
+        if (!fontName)
+            return this.measureTextWidth(text, fontSize);
+        const font = this.resolvedFonts?.get(fontName);
+        if (!font)
+            return this.measureTextWidth(text, fontSize);
+        let width = 0;
+        for (const char of text) {
+            const w = font.getCharacterWidth(char.charCodeAt(0), fontSize);
+            width += w !== null ? w : fontSize * 0.6;
+        }
+        return width;
+    }
+    /**
+     * Emits styled text segments into the current BT…ET block.
+     * When font variants are configured, switches fonts mid-stream for true
+     * bold/italic rendering. Falls back to stroke simulation / Tm shear when
+     * no variant fonts are provided (backward compatible).
+     * Each segment is positioned with an absolute Tm so no prior Td is needed.
+     */
+    showSegments(lineSegs, isUnicode, reverseEncodingMap, startX, startY, fontSize) {
+        const regularFontName = this.defaultAppearance.fontName;
+        let x = startX;
+        for (const seg of lineSegs) {
+            const variantName = this.resolveVariantFontName(seg.bold, seg.italic);
+            if (variantName) {
+                // True font variant — switch font, no simulation needed
+                const variantFont = this.resolvedFonts?.get(variantName);
+                const segIsUnicode = variantFont?.isUnicode ?? isUnicode;
+                const segEncMap = variantFont?.reverseEncodingMap ?? reverseEncodingMap;
+                this.raw(`1 0 0 1 ${x.toFixed(3)} ${startY.toFixed(3)} Tm`);
+                this.raw(`/${variantName} ${fontSize} Tf`);
+                this.raw(`0 Tr`);
+                this.showText(seg.text, segIsUnicode, segEncMap);
+                x += this.measureTextWidthWithFont(seg.text, variantName, fontSize);
+            }
+            else {
+                // Fallback simulation (no variant font provided)
+                // Always restore regular font in case a variant was active
+                this.raw(`/${regularFontName} ${fontSize} Tf`);
+                const shear = seg.italic ? PdfGraphics.ITALIC_SHEAR : 0;
+                this.raw(`1 0 ${shear} 1 ${x.toFixed(3)} ${startY.toFixed(3)} Tm`);
+                if (seg.bold) {
+                    const sw = (fontSize * PdfGraphics.BOLD_STROKE_RATIO).toFixed(3);
+                    this.raw(`${sw} w 2 Tr`);
+                }
+                else {
+                    this.raw(`0 Tr`);
+                }
+                this.showText(seg.text, isUnicode, reverseEncodingMap);
+                x += this.measureTextWidth(seg.text, fontSize);
+            }
+        }
+        // Restore regular font and fill-only rendering mode
+        this.raw(`/${regularFontName} ${fontSize} Tf`);
+        this.raw(`0 Tr`);
+        return this;
+    }
+    /**
+     * Parses a markdown string and renders the styled segments into the current
+     * BT…ET block. Pass `multiline` to wrap across multiple lines.
+     */
+    showMarkdown(markdown, isUnicode, reverseEncodingMap, x, y, fontSize, multiline) {
+        const segments = parseMarkdownSegments(markdown);
+        if (multiline) {
+            const plainText = segments.map((s) => s.text).join('');
+            const lines = this.wrapTextToLines(plainText, multiline.availableWidth);
+            const styledLines = PdfGraphics.splitSegmentsToLines(segments, lines);
+            for (let i = 0; i < styledLines.length; i++) {
+                this.showSegments(styledLines[i], isUnicode, reverseEncodingMap, x, y - i * multiline.lineHeight, fontSize);
+            }
+        }
+        else {
+            this.showSegments(segments, isUnicode, reverseEncodingMap, x, y, fontSize);
+        }
+        return this;
+    }
     build() {
         return this.lines.join('\n') + '\n';
     }
@@ -142,16 +299,23 @@ export class PdfGraphics {
     }
     /**
      * Wrap text to fit within the specified width, breaking at word boundaries.
+     * When a bold font variant is configured, uses its metrics conservatively
+     * to prevent bold glyphs from overflowing field bounds.
      */
     wrapTextToLines(text, maxWidth, fontSize) {
         if (!this.currentFont) {
             throw new Error('No font set - call setDefaultAppearance() first');
         }
+        const boldFontName = this.fontVariantNames?.bold;
+        const size = fontSize ?? this.currentFont.size;
+        const measure = (t) => boldFontName
+            ? this.measureTextWidthWithFont(t, boldFontName, size)
+            : this.measureTextWidth(t, fontSize);
         // Handle explicit line breaks first
         const paragraphs = text.split('\n');
         const wrappedLines = [];
         for (const paragraph of paragraphs) {
-            if (this.measureTextWidth(paragraph, fontSize) <= maxWidth) {
+            if (measure(paragraph) <= maxWidth) {
                 wrappedLines.push(paragraph);
                 continue;
             }
@@ -160,7 +324,7 @@ export class PdfGraphics {
             let currentLine = '';
             for (const word of words) {
                 const testLine = currentLine ? `${currentLine} ${word}` : word;
-                if (this.measureTextWidth(testLine, fontSize) <= maxWidth) {
+                if (measure(testLine) <= maxWidth) {
                     currentLine = testLine;
                 }
                 else {
@@ -189,6 +353,7 @@ export class PdfGraphics {
         if (!this.currentFont) {
             throw new Error('No font set - call setDefaultAppearance() first');
         }
+        const boldFontName = this.fontVariantNames?.bold;
         const startSize = this.currentFont.size;
         const minSize = 0.5;
         const fits = (size) => {
@@ -199,7 +364,10 @@ export class PdfGraphics {
                 return lines.length * size * lineHeight <= maxHeight;
             }
             // Single-line mode: text must fit within maxWidth.
-            return this.measureTextWidth(text, size) <= maxWidth;
+            return boldFontName
+                ? this.measureTextWidthWithFont(text, boldFontName, size) <=
+                    maxWidth
+                : this.measureTextWidth(text, size) <= maxWidth;
         };
         if (fits(startSize))
             return startSize;
@@ -218,11 +386,16 @@ export class PdfGraphics {
         return lo;
     }
     breakLongWord(word, maxWidth, fontSize) {
+        const boldFontName = this.fontVariantNames?.bold;
+        const size = fontSize ?? this.currentFont?.size ?? 12;
+        const measure = (t) => boldFontName
+            ? this.measureTextWidthWithFont(t, boldFontName, size)
+            : this.measureTextWidth(t, fontSize);
         const lines = [];
         let currentLine = '';
         for (const char of word) {
             const testLine = currentLine + char;
-            if (this.measureTextWidth(testLine, fontSize) <= maxWidth) {
+            if (measure(testLine) <= maxWidth) {
                 currentLine = testLine;
             }
             else {

package/dist/acroform/appearance/pdf-text-appearance-stream.d.ts

@@ -2,6 +2,7 @@ import { PdfDefaultAppearance } from '../fields/pdf-default-appearance.js';
 import { PdfAppearanceStream } from './pdf-appearance-stream.js';
 import type { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
 import type { PdfFont } from '../../fonts/pdf-font.js';
+import { type FontVariantNames } from './pdf-graphics.js';
 /**
  * Appearance stream for text fields (single-line, multiline, comb).
  * Enhanced with word wrapping and automatic font scaling.
@@ -18,5 +19,7 @@ export declare class PdfTextAppearanceStream extends PdfAppearanceStream {
         resolvedFonts?: Map<string, PdfFont>;
         isUnicode?: boolean;
         reverseEncodingMap?: Map<string, number>;
+        markdown?: string;
+        fontVariantNames?: FontVariantNames;
     });
 }

package/dist/acroform/appearance/pdf-text-appearance-stream.js

@@ -21,6 +21,7 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
         // Create graphics with font context for text measurement
         const g = new PdfGraphics({
             resolvedFonts: ctx.resolvedFonts,
+            fontVariantNames: ctx.fontVariantNames,
         });
         g.beginMarkedContent();
         g.save();
@@ -28,8 +29,8 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
         g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, DEFAULT_FONT_SIZE, ctx.da.colorOp));
         // ── Determine font size ──────────────────────────────────────
         let finalFontSize;
-        if (autoSize) {
-            // Acrobat auto-size: default to 12pt with wrapping, then
+        if (autoSize && ctx.multiline) {
+            // Multiline auto-size: default to 12pt with wrapping, then
             // shrink only if the wrapped text still doesn't fit.
             finalFontSize = DEFAULT_FONT_SIZE;
             const testLines = g.wrapTextToLines(value, availableWidth);
@@ -38,6 +39,16 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
             }
             finalFontSize = Math.max(finalFontSize, 0.5);
         }
+        else if (autoSize) {
+            // Single-line auto-size: fit to available height, then
+            // shrink further if text overflows the width.
+            finalFontSize = Math.min(DEFAULT_FONT_SIZE, availableHeight);
+            g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
+            if (g.measureTextWidth(value) > availableWidth) {
+                finalFontSize = g.calculateFittingFontSize(value, availableWidth);
+            }
+            finalFontSize = Math.max(finalFontSize, 0.5);
+        }
         else {
             finalFontSize = ctx.da.fontSize;
         }
@@ -45,30 +56,14 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
         const finalDA = new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp);
         g.setDefaultAppearance(finalDA);
         let lines = [];
-        if (ctx.multiline || autoSize) {
-            if (!autoSize) {
-                const testLines = g.wrapTextToLines(value, availableWidth);
-                const lineHeight = finalFontSize * 1.2;
-                if (testLines.length * lineHeight > availableHeight) {
-                    finalFontSize = g.calculateFittingFontSize(value, availableWidth, availableHeight, 1.2);
-                    g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
-                }
-            }
-            lines = g.wrapTextToLines(value, availableWidth);
-            const renderLineHeight = finalFontSize * 1.2;
-            const startY = height - padding - finalFontSize;
-            g.beginText();
-            g.moveTo(padding, startY);
-            for (let i = 0; i < lines.length; i++) {
-                if (i > 0)
-                    g.moveTo(0, -renderLineHeight);
-                g.showText(lines[i].replace(/\r/g, ''), isUnicode, reverseEncodingMap);
-            }
-            g.endText();
-        }
-        else if (ctx.comb && ctx.maxLen) {
+        if (ctx.comb && ctx.maxLen) {
             const cellWidth = width / ctx.maxLen;
             const chars = [...value];
+            // For auto-size comb, fit font to cell height
+            if (autoSize) {
+                finalFontSize = Math.min(height - 2 * padding, cellWidth);
+                g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
+            }
             let maxCharWidth = 0;
             let widestChar = chars[0] ?? '';
             for (const char of chars) {
@@ -85,26 +80,60 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
             const textY = (height - finalFontSize) / 2 + finalFontSize * 0.2;
             g.beginText();
             for (let i = 0; i < chars.length && i < ctx.maxLen; i++) {
-                const cellX = cellWidth * i + cellWidth / 2 - finalFontSize * 0.3;
+                const charWidth = g.measureTextWidth(chars[i]);
+                const cellX = cellWidth * i + (cellWidth - charWidth) / 2;
                 g.moveTo(cellX, textY);
                 g.showText(chars[i], isUnicode, reverseEncodingMap);
                 g.moveTo(-cellX, -textY);
             }
             g.endText();
         }
+        else if (ctx.multiline) {
+            if (!autoSize) {
+                const testLines = g.wrapTextToLines(value, availableWidth);
+                const lineHeight = finalFontSize * 1.2;
+                if (testLines.length * lineHeight > availableHeight) {
+                    finalFontSize = g.calculateFittingFontSize(value, availableWidth, availableHeight, 1.2);
+                    g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
+                }
+            }
+            lines = g.wrapTextToLines(value, availableWidth);
+            const renderLineHeight = finalFontSize * 1.2;
+            const startY = height - padding - finalFontSize;
+            g.beginText();
+            if (ctx.markdown) {
+                g.showMarkdown(ctx.markdown, isUnicode, reverseEncodingMap, padding, startY, finalFontSize, {
+                    availableWidth,
+                    lineHeight: renderLineHeight,
+                });
+            }
+            else {
+                g.moveTo(padding, startY);
+                for (let i = 0; i < lines.length; i++) {
+                    if (i > 0)
+                        g.moveTo(0, -renderLineHeight);
+                    g.showText(lines[i].replace(/\r/g, ''), isUnicode, reverseEncodingMap);
+                }
+            }
+            g.endText();
+        }
         else {
             // Single line — for non-auto-size, shrink if text overflows
             if (!autoSize) {
-                const textWidth = g.measureTextWidth(value);
-                if (textWidth > availableWidth) {
+                if (g.measureTextWidth(value) > availableWidth) {
                     finalFontSize = g.calculateFittingFontSize(value, availableWidth);
                     g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
                 }
             }
             const textY = (height - finalFontSize) / 2 + finalFontSize * 0.2;
             g.beginText();
-            g.moveTo(padding, textY);
-            g.showText(value, isUnicode, reverseEncodingMap);
+            if (ctx.markdown) {
+                g.showMarkdown(ctx.markdown, isUnicode, reverseEncodingMap, padding, textY, finalFontSize);
+            }
+            else {
+                g.moveTo(padding, textY);
+                g.showText(value, isUnicode, reverseEncodingMap);
+            }
             g.endText();
         }
         g.restore();

package/dist/acroform/fields/pdf-button-form-field.d.ts

@@ -1,14 +1,23 @@
 import { PdfFormField } from './pdf-form-field.js';
 import { PdfString } from '../../core/objects/pdf-string.js';
+import type { PdfAcroForm } from '../pdf-acro-form.js';
+import type { PdfIndirectObject } from '../../core/objects/pdf-indirect-object.js';
 /**
  * Button form field subtype (checkboxes, radio buttons, push buttons).
  */
 export declare class PdfButtonFormField extends PdfFormField {
-    set defaultValue(val: string);
-    protected _storeValue(val: string | PdfString, fieldParent: PdfFormField | undefined): boolean;
+    constructor(other?: PdfIndirectObject | {
+        form?: PdfAcroForm;
+    });
+    private initWidget;
+    set isWidget(val: boolean);
+    get isGroup(): boolean;
+    get value(): string;
+    set value(val: string | PdfString);
     get checked(): boolean;
     set checked(isChecked: boolean);
     generateAppearance(options?: {
         makeReadOnly?: boolean;
+        onStateName?: string;
     }): boolean;
 }

package/dist/acroform/fields/pdf-button-form-field.js

@@ -1,6 +1,5 @@
 import { PdfFormField } from './pdf-form-field.js';
 import { PdfButtonAppearanceStream } from '../appearance/pdf-button-appearance-stream.js';
-import { PdfName } from '../../core/objects/pdf-name.js';
 import { PdfString } from '../../core/objects/pdf-string.js';
 /**
  * Button form field subtype (checkboxes, radio buttons, push buttons).
@@ -9,50 +8,80 @@ export class PdfButtonFormField extends PdfFormField {
     static {
         PdfFormField.registerFieldType('Btn', PdfButtonFormField);
     }
-    set defaultValue(val) {
-        this.content.set('DV', new PdfName(val));
-    }
-    _storeValue(val, fieldParent) {
-        const strVal = val instanceof PdfString ? val.value : val;
-        if (strVal.trim() === '') {
-            this.content.delete('V');
-            fieldParent?.content.delete('V');
-            this.content.delete('AS');
-            return false;
+    constructor(other) {
+        super(other);
+        if (this.isWidget && this.appearanceStates.length === 0) {
+            this.initWidget();
         }
-        // Check if the value matches an existing appearance state;
-        // otherwise map truthy values to the widget's "on" state (the
-        // first state that isn't "Off"), falling back to "Yes".
-        const states = this.appearanceStates;
-        let resolved;
-        if (states.includes(strVal)) {
-            resolved = strVal;
+    }
+    initWidget() {
+        this.rect ||= [0, 0, 50, 50];
+        this.generateAppearance({
+            onStateName: this.onState ?? 'Yes',
+        });
+        this.appearanceState ??= 'Off';
+    }
+    set isWidget(val) {
+        super.isWidget = val;
+        // Only initialize the widget if it has no existing appearances.
+        // `appearanceStream` is write-only on PdfFormField, so instead check
+        // the underlying appearance data structures.
+        if (val &&
+            !this.appearanceStreamDict &&
+            this.appearanceStates.length === 0) {
+            this.initWidget();
         }
-        else if (strVal === 'Off' || strVal === 'No') {
-            resolved = 'Off';
+    }
+    get isGroup() {
+        return this.children.length > 0;
+    }
+    get value() {
+        return super.value;
+    }
+    set value(val) {
+        const strVal = val instanceof PdfString ? val.value : val;
+        this.setRawValue(new PdfString(strVal));
+        if (this.isGroup) {
+            const children = this.children;
+            // 'Off' means explicitly uncheck all children
+            if (strVal === 'Off') {
+                for (const child of children) {
+                    child.appearanceState = 'Off';
+                    if (this._form)
+                        child.form = this._form;
+                }
+            }
+            else {
+                let wasSet = false;
+                for (const child of children) {
+                    const foundState = child.onStates.includes(strVal);
+                    if (!wasSet && foundState) {
+                        wasSet = true;
+                    }
+                    child.appearanceState = foundState ? strVal : 'Off';
+                    if (this._form)
+                        child.form = this._form;
+                }
+                if (!wasSet && children.length > 0) {
+                    // If value doesn't match any on-state, check first child by default
+                    children[0].appearanceState =
+                        children[0].onStates[0] ?? 'Off';
+                }
+            }
         }
         else {
-            resolved = states.find((s) => s !== 'Off') ?? strVal;
+            this.appearanceState = strVal;
         }
-        this.content.set('V', new PdfName(resolved));
-        fieldParent?.content.set('V', new PdfName(resolved));
-        this.content.set('AS', new PdfName(resolved));
-        return true;
     }
     get checked() {
-        const v = this.content.get('V') ?? this.parent?.content.get('V');
-        return v instanceof PdfName && v.value !== 'Off';
+        return !(this.appearanceState === 'Off' || this.value === 'Off');
     }
     set checked(isChecked) {
-        const target = this.parent ?? this;
         if (isChecked) {
-            const onState = this.appearanceStates.find((s) => s !== 'Off') ?? 'Yes';
-            target.content.set('V', new PdfName(onState));
-            this.content.set('AS', new PdfName(onState));
+            this.value = this.onState ?? 'Yes';
         }
         else {
-            target.content.set('V', new PdfName('Off'));
-            this.content.set('AS', new PdfName('Off'));
+            this.value = 'Off';
         }
     }
     generateAppearance(options) {
@@ -71,11 +100,21 @@ export class PdfButtonFormField extends PdfFormField {
             height,
             contentStream: '',
         });
-        const onState = this.appearanceStates.find((s) => s !== 'Off') ?? 'Yes';
-        this.setAppearanceStream({
-            [onState]: yesAppearance,
+        const existingOnState = this.onState;
+        const as = this.appearanceState;
+        const onKey = options?.onStateName ??
+            (as && as !== 'Off' ? as : (existingOnState ?? 'Yes'));
+        if (onKey === 'Off') {
+            throw new Error("Invalid on-state name 'Off' for button field appearance stream");
+        }
+        this.appearanceStream = {
+            [onKey]: yesAppearance,
             Off: noAppearance,
-        });
+        };
+        this.downAppearanceStream = {
+            [onKey]: yesAppearance,
+            Off: noAppearance,
+        };
         if (options?.makeReadOnly) {
             this.readOnly = true;
             this.print = true;