boxpdf - npm Package Compare versions

Comparing version 1.12.0 to 1.13.0

dist/index.d.cts

@@ -1,2 +0,2 @@
-import { PDFFont, PDFImage, PDFPage, SaveOptions, PDFDocument } from 'pdf-lib';
+import { PDFFont, PDFImage, PDFDocument, PDFPage, SaveOptions } from 'pdf-lib';
 export { PDFDocument, PDFFont, PDFImage, PDFPage, StandardFonts } from 'pdf-lib';
@@ -289,2 +289,78 @@
 }
+interface FormFieldAppearance extends FlexItemStyle {
+    /** Widget width in PDF points. */
+    width: number;
+    /** Widget height in PDF points. */
+    height: number;
+    /** Outer spacing around the widget. */
+    margin?: EdgesInput;
+    /** Font used to generate text appearances. Defaults to Helvetica. */
+    font?: PDFFont;
+    /** Text size used by text-bearing fields. */
+    fontSize?: number;
+    textColor?: RGB;
+    backgroundColor?: RGB;
+    borderColor?: RGB;
+    borderWidth?: number;
+    hidden?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    /**
+     * Whether the field value is included when a reader exports the form.
+     * Defaults to `true`, except `password: true` text fields default to non-exportable
+     * unless `exported: true` is explicitly provided.
+     */
+    exported?: boolean;
+}
+type FormFieldNode = {
+    kind: "formField";
+    fieldType: "text";
+    name: string;
+    appearance: FormFieldAppearance;
+    value?: string;
+    multiline?: boolean;
+    password?: boolean;
+    maxLength?: number;
+    combed?: boolean;
+    align?: Align;
+} | {
+    kind: "formField";
+    fieldType: "checkbox";
+    name: string;
+    appearance: FormFieldAppearance;
+    checked?: boolean;
+} | {
+    kind: "formField";
+    fieldType: "radio";
+    name: string;
+    appearance: FormFieldAppearance;
+    option: string;
+    selected?: boolean;
+    offToggleable?: boolean;
+    mutuallyExclusive?: boolean;
+} | {
+    kind: "formField";
+    fieldType: "dropdown";
+    name: string;
+    appearance: FormFieldAppearance;
+    options: string[];
+    selected?: string;
+    editable?: boolean;
+    sorted?: boolean;
+} | {
+    kind: "formField";
+    fieldType: "optionList";
+    name: string;
+    appearance: FormFieldAppearance;
+    options: string[];
+    selected?: string | string[];
+    multiselect?: boolean;
+    sorted?: boolean;
+} | {
+    kind: "formField";
+    fieldType: "button";
+    name: string;
+    appearance: FormFieldAppearance;
+    label: string;
+};
 type Node = {
@@ -314,3 +390,3 @@ kind: "vstack";
     props: ParagraphProps;
-} | {
+} | FormFieldNode | {
     kind: "image";
@@ -632,2 +708,60 @@ image: PDFImage;
 
+type FormFieldOptions = FormFieldAppearance;
+interface TextFieldOptions extends FormFieldOptions {
+    name: string;
+    value?: string;
+    multiline?: boolean;
+    password?: boolean;
+    maxLength?: number;
+    combed?: boolean;
+    align?: Align;
+}
+interface CheckboxOptions extends Omit<FormFieldOptions, "font" | "fontSize" | "textColor"> {
+    name: string;
+    checked?: boolean;
+}
+interface RadioOptionOptions extends Omit<FormFieldOptions, "font" | "fontSize" | "textColor"> {
+    name: string;
+    option: string;
+    selected?: boolean;
+    offToggleable?: boolean;
+    mutuallyExclusive?: boolean;
+}
+interface DropdownOptions extends FormFieldOptions {
+    name: string;
+    options: string[];
+    selected?: string;
+    editable?: boolean;
+    sorted?: boolean;
+}
+interface OptionListOptions extends FormFieldOptions {
+    name: string;
+    options: string[];
+    selected?: string | string[];
+    multiselect?: boolean;
+    sorted?: boolean;
+}
+interface ButtonOptions extends FormFieldOptions {
+    name: string;
+    label: string;
+}
+declare function textField(options: TextFieldOptions): FormFieldNode;
+declare function checkbox(options: CheckboxOptions): FormFieldNode;
+declare function radioOption(options: RadioOptionOptions): FormFieldNode;
+declare function dropdown(options: DropdownOptions): FormFieldNode;
+declare function optionList(options: OptionListOptions): FormFieldNode;
+declare function button(options: ButtonOptions): FormFieldNode;
+/** Return the current values of every portable AcroForm field in a document. */
+declare function getFormValues(pdf: PDFDocument): Record<string, string | string[] | boolean | undefined>;
+type FormValue = string | string[] | boolean | undefined;
+/** Set values on existing portable AcroForm fields by their document-global names. */
+declare function setFormValues(pdf: PDFDocument, values: Record<string, FormValue>, options?: {
+    font?: FormFieldAppearance["font"];
+}): void;
+/** Flatten all AcroForm widgets into page content, making them non-interactive. */
+declare function flattenForm(pdf: PDFDocument, options?: {
+    updateFieldAppearances?: boolean;
+    font?: FormFieldAppearance["font"];
+}): void;
+
 type MainAxis = "horizontal" | "vertical";
@@ -1252,2 +1386,2 @@ interface MainAxisLayout {
 
-export { type Align, type AssetSource, type BackgroundImage, type Border, type BorderSides, type BoxStyle, type BoxTransform, type BreakInside, type CellVerticalAlign, Colors, type ColumnSpec, type ColumnWidth, type CrossAxis, type DocumentMetadata, type Edges, type EdgesInput, type FlowOptions, type FlowToPdfOptions, type Fragmentation, type InlineNodeRun, type InlineVerticalAlign, type Justify, type LoadFontOptions, type MainAxis, type MainAxisLayout, type MeasureProfileEvent, type Node, type Overflow, type PageContext, type PageOptions, type PageSize, PageSizes, type ParagraphFloat, type ParagraphFloatLayout, type ParagraphItem, type ParagraphLayout, type ParagraphProps, type ParagraphRun, PdfEncryptionError, type PdfEncryptionErrorCode, type PdfEncryptionOptions, type PdfPermissions, type Position, type RGB, type RelativeLength, type RenderFlowProfileCallback, type RenderFlowProfileEvent, type RenderOptions, type RenderToPdfOptions, type SavePdfOptions, type Size, type StandardFontFamily, type StandardFontSet, type StreamFlowOptions, type StreamPageContext, type TableCell, type TableCellInput, type TableDivider, type TableOptions, type TextOptions, type TextProps, type TextRunStyle, type Theme, type ThemeColors, type ThemeFonts, type ThemeRadii, type ThemeSpacing, type ThemeType, type ThemedTextStyle, type TransformOrigin, aspectRatio, brutalistTheme, cleanTheme, defineStyles, editorialTheme, embedFont, flex, flowContinuation, flowToPdf, formatCurrency, group, hex, hline, hstack, image, imageFit, inlineNode, keepTogether, link, linkRun, loadFont, loadImage, measure, measureContent, nodeAdapter, pageContent, pageInner, paragraph, render, renderFlow, renderToPdf, resolveMainAxis, rgb255, run, savePdf, spacer, standardFonts, streamFlow, stripeTheme, svgPath, table, text, vline, vstack };
+export { type Align, type AssetSource, type BackgroundImage, type Border, type BorderSides, type BoxStyle, type BoxTransform, type BreakInside, type ButtonOptions, type CellVerticalAlign, type CheckboxOptions, Colors, type ColumnSpec, type ColumnWidth, type CrossAxis, type DocumentMetadata, type DropdownOptions, type Edges, type EdgesInput, type FlowOptions, type FlowToPdfOptions, type FormFieldAppearance, type FormFieldNode, type FormFieldOptions, type FormValue, type Fragmentation, type InlineNodeRun, type InlineVerticalAlign, type Justify, type LoadFontOptions, type MainAxis, type MainAxisLayout, type MeasureProfileEvent, type Node, type OptionListOptions, type Overflow, type PageContext, type PageOptions, type PageSize, PageSizes, type ParagraphFloat, type ParagraphFloatLayout, type ParagraphItem, type ParagraphLayout, type ParagraphProps, type ParagraphRun, PdfEncryptionError, type PdfEncryptionErrorCode, type PdfEncryptionOptions, type PdfPermissions, type Position, type RGB, type RadioOptionOptions, type RelativeLength, type RenderFlowProfileCallback, type RenderFlowProfileEvent, type RenderOptions, type RenderToPdfOptions, type SavePdfOptions, type Size, type StandardFontFamily, type StandardFontSet, type StreamFlowOptions, type StreamPageContext, type TableCell, type TableCellInput, type TableDivider, type TableOptions, type TextFieldOptions, type TextOptions, type TextProps, type TextRunStyle, type Theme, type ThemeColors, type ThemeFonts, type ThemeRadii, type ThemeSpacing, type ThemeType, type ThemedTextStyle, type TransformOrigin, aspectRatio, brutalistTheme, button, checkbox, cleanTheme, defineStyles, dropdown, editorialTheme, embedFont, flattenForm, flex, flowContinuation, flowToPdf, formatCurrency, getFormValues, group, hex, hline, hstack, image, imageFit, inlineNode, keepTogether, link, linkRun, loadFont, loadImage, measure, measureContent, nodeAdapter, optionList, pageContent, pageInner, paragraph, radioOption, render, renderFlow, renderToPdf, resolveMainAxis, rgb255, run, savePdf, setFormValues, spacer, standardFonts, streamFlow, stripeTheme, svgPath, table, text, textField, vline, vstack };

dist/index.d.ts

@@ -1,2 +0,2 @@
-import { PDFFont, PDFImage, PDFPage, SaveOptions, PDFDocument } from 'pdf-lib';
+import { PDFFont, PDFImage, PDFDocument, PDFPage, SaveOptions } from 'pdf-lib';
 export { PDFDocument, PDFFont, PDFImage, PDFPage, StandardFonts } from 'pdf-lib';
@@ -289,2 +289,78 @@
 }
+interface FormFieldAppearance extends FlexItemStyle {
+    /** Widget width in PDF points. */
+    width: number;
+    /** Widget height in PDF points. */
+    height: number;
+    /** Outer spacing around the widget. */
+    margin?: EdgesInput;
+    /** Font used to generate text appearances. Defaults to Helvetica. */
+    font?: PDFFont;
+    /** Text size used by text-bearing fields. */
+    fontSize?: number;
+    textColor?: RGB;
+    backgroundColor?: RGB;
+    borderColor?: RGB;
+    borderWidth?: number;
+    hidden?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    /**
+     * Whether the field value is included when a reader exports the form.
+     * Defaults to `true`, except `password: true` text fields default to non-exportable
+     * unless `exported: true` is explicitly provided.
+     */
+    exported?: boolean;
+}
+type FormFieldNode = {
+    kind: "formField";
+    fieldType: "text";
+    name: string;
+    appearance: FormFieldAppearance;
+    value?: string;
+    multiline?: boolean;
+    password?: boolean;
+    maxLength?: number;
+    combed?: boolean;
+    align?: Align;
+} | {
+    kind: "formField";
+    fieldType: "checkbox";
+    name: string;
+    appearance: FormFieldAppearance;
+    checked?: boolean;
+} | {
+    kind: "formField";
+    fieldType: "radio";
+    name: string;
+    appearance: FormFieldAppearance;
+    option: string;
+    selected?: boolean;
+    offToggleable?: boolean;
+    mutuallyExclusive?: boolean;
+} | {
+    kind: "formField";
+    fieldType: "dropdown";
+    name: string;
+    appearance: FormFieldAppearance;
+    options: string[];
+    selected?: string;
+    editable?: boolean;
+    sorted?: boolean;
+} | {
+    kind: "formField";
+    fieldType: "optionList";
+    name: string;
+    appearance: FormFieldAppearance;
+    options: string[];
+    selected?: string | string[];
+    multiselect?: boolean;
+    sorted?: boolean;
+} | {
+    kind: "formField";
+    fieldType: "button";
+    name: string;
+    appearance: FormFieldAppearance;
+    label: string;
+};
 type Node = {
@@ -314,3 +390,3 @@ kind: "vstack";
     props: ParagraphProps;
-} | {
+} | FormFieldNode | {
     kind: "image";
@@ -632,2 +708,60 @@ image: PDFImage;
 
+type FormFieldOptions = FormFieldAppearance;
+interface TextFieldOptions extends FormFieldOptions {
+    name: string;
+    value?: string;
+    multiline?: boolean;
+    password?: boolean;
+    maxLength?: number;
+    combed?: boolean;
+    align?: Align;
+}
+interface CheckboxOptions extends Omit<FormFieldOptions, "font" | "fontSize" | "textColor"> {
+    name: string;
+    checked?: boolean;
+}
+interface RadioOptionOptions extends Omit<FormFieldOptions, "font" | "fontSize" | "textColor"> {
+    name: string;
+    option: string;
+    selected?: boolean;
+    offToggleable?: boolean;
+    mutuallyExclusive?: boolean;
+}
+interface DropdownOptions extends FormFieldOptions {
+    name: string;
+    options: string[];
+    selected?: string;
+    editable?: boolean;
+    sorted?: boolean;
+}
+interface OptionListOptions extends FormFieldOptions {
+    name: string;
+    options: string[];
+    selected?: string | string[];
+    multiselect?: boolean;
+    sorted?: boolean;
+}
+interface ButtonOptions extends FormFieldOptions {
+    name: string;
+    label: string;
+}
+declare function textField(options: TextFieldOptions): FormFieldNode;
+declare function checkbox(options: CheckboxOptions): FormFieldNode;
+declare function radioOption(options: RadioOptionOptions): FormFieldNode;
+declare function dropdown(options: DropdownOptions): FormFieldNode;
+declare function optionList(options: OptionListOptions): FormFieldNode;
+declare function button(options: ButtonOptions): FormFieldNode;
+/** Return the current values of every portable AcroForm field in a document. */
+declare function getFormValues(pdf: PDFDocument): Record<string, string | string[] | boolean | undefined>;
+type FormValue = string | string[] | boolean | undefined;
+/** Set values on existing portable AcroForm fields by their document-global names. */
+declare function setFormValues(pdf: PDFDocument, values: Record<string, FormValue>, options?: {
+    font?: FormFieldAppearance["font"];
+}): void;
+/** Flatten all AcroForm widgets into page content, making them non-interactive. */
+declare function flattenForm(pdf: PDFDocument, options?: {
+    updateFieldAppearances?: boolean;
+    font?: FormFieldAppearance["font"];
+}): void;
+
 type MainAxis = "horizontal" | "vertical";
@@ -1252,2 +1386,2 @@ interface MainAxisLayout {
 
-export { type Align, type AssetSource, type BackgroundImage, type Border, type BorderSides, type BoxStyle, type BoxTransform, type BreakInside, type CellVerticalAlign, Colors, type ColumnSpec, type ColumnWidth, type CrossAxis, type DocumentMetadata, type Edges, type EdgesInput, type FlowOptions, type FlowToPdfOptions, type Fragmentation, type InlineNodeRun, type InlineVerticalAlign, type Justify, type LoadFontOptions, type MainAxis, type MainAxisLayout, type MeasureProfileEvent, type Node, type Overflow, type PageContext, type PageOptions, type PageSize, PageSizes, type ParagraphFloat, type ParagraphFloatLayout, type ParagraphItem, type ParagraphLayout, type ParagraphProps, type ParagraphRun, PdfEncryptionError, type PdfEncryptionErrorCode, type PdfEncryptionOptions, type PdfPermissions, type Position, type RGB, type RelativeLength, type RenderFlowProfileCallback, type RenderFlowProfileEvent, type RenderOptions, type RenderToPdfOptions, type SavePdfOptions, type Size, type StandardFontFamily, type StandardFontSet, type StreamFlowOptions, type StreamPageContext, type TableCell, type TableCellInput, type TableDivider, type TableOptions, type TextOptions, type TextProps, type TextRunStyle, type Theme, type ThemeColors, type ThemeFonts, type ThemeRadii, type ThemeSpacing, type ThemeType, type ThemedTextStyle, type TransformOrigin, aspectRatio, brutalistTheme, cleanTheme, defineStyles, editorialTheme, embedFont, flex, flowContinuation, flowToPdf, formatCurrency, group, hex, hline, hstack, image, imageFit, inlineNode, keepTogether, link, linkRun, loadFont, loadImage, measure, measureContent, nodeAdapter, pageContent, pageInner, paragraph, render, renderFlow, renderToPdf, resolveMainAxis, rgb255, run, savePdf, spacer, standardFonts, streamFlow, stripeTheme, svgPath, table, text, vline, vstack };
+export { type Align, type AssetSource, type BackgroundImage, type Border, type BorderSides, type BoxStyle, type BoxTransform, type BreakInside, type ButtonOptions, type CellVerticalAlign, type CheckboxOptions, Colors, type ColumnSpec, type ColumnWidth, type CrossAxis, type DocumentMetadata, type DropdownOptions, type Edges, type EdgesInput, type FlowOptions, type FlowToPdfOptions, type FormFieldAppearance, type FormFieldNode, type FormFieldOptions, type FormValue, type Fragmentation, type InlineNodeRun, type InlineVerticalAlign, type Justify, type LoadFontOptions, type MainAxis, type MainAxisLayout, type MeasureProfileEvent, type Node, type OptionListOptions, type Overflow, type PageContext, type PageOptions, type PageSize, PageSizes, type ParagraphFloat, type ParagraphFloatLayout, type ParagraphItem, type ParagraphLayout, type ParagraphProps, type ParagraphRun, PdfEncryptionError, type PdfEncryptionErrorCode, type PdfEncryptionOptions, type PdfPermissions, type Position, type RGB, type RadioOptionOptions, type RelativeLength, type RenderFlowProfileCallback, type RenderFlowProfileEvent, type RenderOptions, type RenderToPdfOptions, type SavePdfOptions, type Size, type StandardFontFamily, type StandardFontSet, type StreamFlowOptions, type StreamPageContext, type TableCell, type TableCellInput, type TableDivider, type TableOptions, type TextFieldOptions, type TextOptions, type TextProps, type TextRunStyle, type Theme, type ThemeColors, type ThemeFonts, type ThemeRadii, type ThemeSpacing, type ThemeType, type ThemedTextStyle, type TransformOrigin, aspectRatio, brutalistTheme, button, checkbox, cleanTheme, defineStyles, dropdown, editorialTheme, embedFont, flattenForm, flex, flowContinuation, flowToPdf, formatCurrency, getFormValues, group, hex, hline, hstack, image, imageFit, inlineNode, keepTogether, link, linkRun, loadFont, loadImage, measure, measureContent, nodeAdapter, optionList, pageContent, pageInner, paragraph, radioOption, render, renderFlow, renderToPdf, resolveMainAxis, rgb255, run, savePdf, setFormValues, spacer, standardFonts, streamFlow, stripeTheme, svgPath, table, text, textField, vline, vstack };

package.json

 {
   "name": "boxpdf",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "mcpName": "io.github.earonesty/boxpdf",
@@ -64,2 +64,3 @@ "description": "Tiny box-layout DSL over pdf-lib. Flexbox-lite for server-side PDF generation in any JS runtime (Node, Cloudflare Workers, Deno, browsers).",
     "memory:check:continuation": "tsx scripts/check-continuation-memory.ts",
+    "docs:check": "node scripts/check-docs-site.mjs",
     "example": "tsx examples/index.ts",
@@ -66,0 +67,0 @@ "gallery": "tsx scripts/build-gallery.ts",

README.md

@@ -67,2 +67,3 @@ # boxpdf
 - Declarative layout primitives: `vstack`, `hstack`, `text`, `image`, `hline`, `vline`, `spacer`, `flex`, `keepTogether`, `link`, `svgPath`, `table`.
+- Layout-aware AcroForm fields: text, checkbox, radio, dropdown, option-list, and push-button widgets.
 - Padding, margin, background, background images, borders, borderRadius, overflow clipping, flex-grow, flex-shrink, justify, align.
@@ -159,2 +160,62 @@ - Rich paragraphs with mixed inline runs, inline replaced nodes, hard breaks, hanging indents, and optional paragraph floats.
 
+### AcroForm fields
+
+Form widgets are atomic layout nodes, so they work inside stacks, tables, pagination, and streamed documents without manual page coordinates.
+
+```ts
+import {
+  checkbox,
+  dropdown,
+  flowToPdf,
+  standardFonts,
+  text,
+  textField,
+  vstack
+} from "boxpdf";
+
+const bytes = await flowToPdf(async (pdf) => {
+  const { font } = await standardFonts(pdf);
+  return [
+    vstack({ gap: 10 },
+      text("Registration", { size: 18, font }),
+      textField({
+        name: "person.name",
+        width: 260,
+        height: 26,
+        font,
+        fontSize: 11,
+        required: true
+      }),
+      dropdown({
+        name: "person.state",
+        width: 140,
+        height: 26,
+        font,
+        options: ["CA", "NY", "WA"]
+      }),
+      checkbox({
+        name: "terms.accepted",
+        width: 16,
+        height: 16,
+        required: true
+      })
+    )
+  ];
+});
+```
+
+- `textField({ name, width, height, ... })`. Supports an initial `value`, `multiline`, `password`, `maxLength`, `combed`, alignment, and shared field flags and appearance options. Password text fields are non-exportable by default unless `exported: true` is explicitly set.
+- `checkbox({ name, width, height, checked? })`.
+- `radioOption({ name, option, width, height, selected? })`. Nodes with the same name form one radio group.
+- `dropdown({ name, options, width, height, selected?, editable?, sorted? })`. Kept single-select for consistent viewer behavior.
+- `optionList({ name, options, width, height, selected?, multiselect?, sorted? })`.
+- `button({ name, label, width, height, ... })`. Creates a portable push-button widget and appearance; BoxPDF does not attach PDF JavaScript or submit actions. Standard SubmitForm actions are reader-dependent and browser viewers may block submissions from local PDFs by origin policy.
+
+All fields accept `margin`, `alignSelf`, `readOnly`, `required`, `exported`, `hidden`, `backgroundColor`, `borderColor`, and `borderWidth`. Text-bearing fields also accept `font`, `fontSize`, and `textColor`. Field names are document-global. Reusing a name adds another widget for the same logical field; reusing it for a different field type throws. Password text fields default to `exported: false`, so mark `exported: true` to permit submission/export intentionally. Forms work with ordinary, streamed, and encrypted output; use the encryption `fillForms` permission to control whether conforming readers allow changes.
+For shared logical fields, text, dropdown, and option-list initialization state (`value`, `options`, and initial `selected`) is fixed by the first node. Radio-group flags (`offToggleable`, `mutuallyExclusive`) are also first-node-only. `selected: true` on a `radioOption` marks that option, while `selected: false` does not clear any existing selection.
+
+Use `getFormValues(pdf)`, `setFormValues(pdf, values)`, and `flattenForm(pdf)` when working with a caller-owned `PDFDocument`. When updating non-WinAnsi text, pass the embedded font as `{ font }` to `setFormValues` or `flattenForm` so pdf-lib regenerates the appearances with that font.
+
+AcroForm widgets are PDF annotations rather than page drawing operations. They therefore cannot be placed inside transformed BoxPDF ancestors; BoxPDF throws instead of emitting a misplaced widget. XFA, signature fields, PDF JavaScript, and cryptographic signing are outside the core form layer.
+
 ### Rendering
@@ -161,0 +222,0 @@

No alert changes

Improved metrics

Total package byte prevSize

2978585

3.58%

Lines of code

18006

4.66%

Number of lines in readme file

549

12.5%

No dependency changes