feat: add Form Annotation support

packages/primitives/src/index.js

@@ -8,6 +8,12 @@ export const Note = 'NOTE';
 export const Path = 'PATH';
 export const Rect = 'RECT';
 export const Line = 'LINE';
+export const Form = 'FORM';
+export const FormField = 'FORM_FIELD';
+export const FormText = 'FORM_TEXT';
+export const FormPushButton = 'FORM_PUSH_BUTTON';
+export const FormCombo = 'FORM_COMBO';
+export const FormList = 'FORM_LIST';
 export const Stop = 'STOP';
 export const Defs = 'DEFS';
 export const Image = 'IMAGE';

packages/primitives/tests/index.test.js

@@ -37,6 +37,30 @@ describe('primitives', () => {
     expect(primitives.Line).toBeTruthy();
   });
 
+  test('should export form', () => {
+    expect(primitives.Form).toBeTruthy();
+  });
+
+  test('should export form field', () => {
+    expect(primitives.FormField).toBeTruthy();
+  });
+
+  test('should export form text', () => {
+    expect(primitives.FormText).toBeTruthy();
+  });
+
+  test('should export form list', () => {
+    expect(primitives.FormList).toBeTruthy();
+  });
+
+  test('should export form combo', () => {
+    expect(primitives.FormCombo).toBeTruthy();
+  });
+
+  test('should export form push button', () => {
+    expect(primitives.FormPushButton).toBeTruthy();
+  });
+
   test('should export stop', () => {
     expect(primitives.Stop).toBeTruthy();
   });

packages/render/src/primitives/form/renderForm.js

@@ -0,0 +1,13 @@
+import renderNode from '../renderNode';
+
+const renderForm = (ctx, node, options) => {
+  ctx.save();
+  ctx.initForm();
+
+  const children = node.children || [];
+  children.forEach((child) => renderNode(ctx, child, options))
+
+  ctx.restore();
+};
+
+export default renderForm;

packages/render/src/primitives/form/renderFormCombo.js

@@ -0,0 +1,12 @@
+import {parseComboAndListFieldOptions} from '../../utils/parseFormOptions';
+
+const renderFormCombo = (ctx, node) => {
+    const { top, left, width, height } = node.box || {};
+
+    // Element's name
+    const name = node.props?.name || '';
+
+    ctx.formCombo(name, left, top, width, height, parseComboAndListFieldOptions(node));
+};
+
+export default renderFormCombo;

packages/render/src/primitives/form/renderFormField.js

@@ -0,0 +1,12 @@
+import renderNode from '../renderNode';
+
+const renderFormField = (ctx, node, options) => {
+    const name = node.props?.name || '';
+
+    const formField = ctx.formField(name);
+
+    const children = node.children || [];
+    children.forEach((child) => renderNode(ctx, child, {...options, formField}))
+};
+
+export default renderFormField;

packages/render/src/primitives/form/renderFormList.js

@@ -0,0 +1,12 @@
+import {parseComboAndListFieldOptions} from '../../utils/parseFormOptions';
+
+const renderFormList = (ctx, node) => {
+    const { top, left, width, height } = node.box || {};
+
+    // Element's name
+    const name = node.props?.name || '';
+
+    ctx.formList(name, left, top, width, height, parseComboAndListFieldOptions(node));
+};
+
+export default renderFormList;

packages/render/src/primitives/form/renderFormPushButton.js

@@ -0,0 +1,12 @@
+import {parseButtonFieldOptions} from '../../utils/parseFormOptions';
+
+const renderFormPushButton = (ctx, node) => {
+    const { top, left, width, height } = node.box || {};
+
+    // Element's name
+    const name = node.props?.name || '';
+
+    ctx.formPushButton(name, left, top, width, height, parseButtonFieldOptions(node));
+};
+
+export default renderFormPushButton;

packages/render/src/primitives/form/renderFormText.js

@@ -0,0 +1,15 @@
+import {parseTextFieldOptions} from '../../utils/parseFormOptions';
+
+const renderFormText = (ctx, node, options) => {
+    const { top, left, width, height } = node.box || {};
+
+    // Element's name
+    const name = node.props?.name || '';
+
+    if(!options.formField)
+        throw new Error('The FormText element must be a children of a FormField element.')
+
+    ctx.formText(name, left, top, width, height, parseTextFieldOptions(node, options.formField));
+};
+
+export default renderFormText;

packages/render/src/primitives/renderNode.js

@@ -12,8 +12,14 @@ import setLink from '../operations/setLink';
 import clipNode from '../operations/clipNode';
 import transform from '../operations/transform';
 import setDestination from '../operations/setDestination';
+import renderForm from './form/renderForm';
+import renderFormField from './form/renderFormField';
+import renderFormText from './form/renderFormText';
+import renderFormPushButton from './form/renderFormPushButton';
+import renderFormCombo from './form/renderFormCombo';
+import renderFormList from './form/renderFormList';
 
-const isRecursiveNode = node => node.type !== P.Text && node.type !== P.Svg;
+const isRecursiveNode = node => node.type !== P.Text && node.type !== P.Svg && node.type !== P.Form && node.type !== P.FormField;
 
 const renderChildren = (ctx, node, options) => {
   ctx.save();
@@ -34,6 +40,12 @@ const renderFns = {
   [P.Text]: renderText,
   [P.Note]: renderNote,
   [P.Image]: renderImage,
+  [P.Form]: renderForm,
+  [P.FormField]: renderFormField,
+  [P.FormText]: renderFormText,
+  [P.FormPushButton]: renderFormPushButton,
+  [P.FormCombo]: renderFormCombo,
+  [P.FormList]: renderFormList,
   [P.Canvas]: renderCanvas,
   [P.Svg]: renderSvg,
   [P.Link]: setLink,

packages/render/src/utils/parseFormOptions.js

@@ -0,0 +1,59 @@
+const clean = options => {
+  const opt = { ...options };
+
+  // We need to ensure the elements are no present if not true
+  Object.entries(opt).forEach(pair => {
+    if (!pair[1]) {
+      delete opt[pair[0]];
+    }
+  });
+
+  return opt;
+};
+
+const parseCommonFormOptions = node => {
+  // Common Options
+  return {
+    required: node.props?.required || false,
+    noExport: node.props?.noExport || false,
+    readOnly: node.props?.readOnly || false,
+    value: node.props?.value || undefined,
+    defaultValue: node.props?.defaultValue || undefined,
+  };
+};
+
+const parseTextFieldOptions = (node, formField) => {
+  return clean({
+    ...parseCommonFormOptions(node),
+    parent: formField || undefined,
+    align: node.props?.align || 'left',
+    multiline: node.props?.multiline || undefined,
+    password: node.props?.password || false,
+    noSpell: node.props?.noSpell || false,
+    format: node.props?.format || undefined,
+  });
+};
+
+const parseComboAndListFieldOptions = node => {
+  return clean({
+    ...parseCommonFormOptions(node),
+    sort: node.props?.sort || false,
+    edit: node.props?.edit || false,
+    multiSelect: node.props?.multiSelect || false,
+    noSpell: node.props?.noSpell || false,
+    select: node.props?.select || [''],
+  });
+};
+
+const parseButtonFieldOptions = node => {
+  return clean({
+    ...parseCommonFormOptions(node),
+    label: node.props?.label || '???',
+  });
+};
+
+export {
+  parseTextFieldOptions,
+  parseComboAndListFieldOptions,
+  parseButtonFieldOptions,
+};

packages/render/tests/ctx.js

@@ -46,6 +46,8 @@ const createCTX = () => {
   instance.lineCap = jest.fn().mockReturnValue(instance);
   instance.text = jest.fn().mockReturnValue(instance);
   instance.font = jest.fn().mockReturnValue(instance);
+  instance.formField = jest.fn().mockReturnValue(instance);
+  instance.formText = jest.fn().mockReturnValue(instance);
 
   return instance;
 };

packages/render/tests/primitives/renderForm.test.js

@@ -0,0 +1,49 @@
+import * as P from '@react-pdf/primitives';
+
+import createCTX from '../ctx';
+import renderFormField from '../../src/primitives/form/renderFormField';
+
+describe('primitive renderFormField', () => {
+  test('should render FormField correctly', () => {
+    const ctx = createCTX();
+    const args = 'example';
+    const props = { name: args };
+    const node = { type: P.FormField, props };
+
+    renderFormField(ctx, node);
+
+    expect(ctx.formField.mock.calls).toHaveLength(1);
+    expect(ctx.formField.mock.calls[0]).toHaveLength(1);
+    expect(ctx.formField.mock.calls[0][0]).toBe(args);
+  });
+
+  test('FormField with one formText direct child', () => {
+    const ctx = createCTX();
+    const node = { type: P.FormField, children: [{type: P.FormText}]};
+
+    renderFormField(ctx, node);
+
+    expect(ctx.formText.mock.calls).toHaveLength(1);
+  });
+
+  test('FormField with one formText indirect child', () => {
+    const ctx = createCTX();
+    const node = {
+      type: P.FormField,
+      children: [
+          {
+            type: P.View,
+            children: [
+              {
+                type: P.FormText
+              }
+            ]
+          }
+      ]
+    };
+
+    renderFormField(ctx, node);
+
+    expect(ctx.formText.mock.calls).toHaveLength(1);
+  });
+});

packages/renderer/index.d.ts

@@ -208,6 +208,67 @@ declare namespace ReactPDF {
    */
   class Link extends React.Component<LinkProps> {}
 
+  /**
+   * The fundamental component for building a Form.
+   */
+  class Form extends React.Component<NodeProps> {}
+
+  interface FormCommonProps extends NodeProps {
+    name?: string;
+    required?: boolean;
+    noExport?: boolean;
+    readOnly?: boolean;
+    value ?: number | string;
+    defaultValue?: number | string;
+  }
+
+  interface FormFieldProps extends NodeProps {
+    name: string;
+  }
+
+  class FormField extends React.Component<FormFieldProps> {}
+
+  // see http://pdfkit.org/docs/forms.html#text_field_formatting
+  interface TextFieldFormatting {
+    type: 'date' | 'time' | 'percent' | 'number' | 'zip' | 'zipPlus4' | 'phone' | 'ssn';
+    param?: string;
+    nDec?: number;
+    sepComma?: boolean;
+    negStyle?: 'MinusBlack' | 'Red' | 'ParensBlack' | 'ParensRed';
+    currency?: string;
+    currencyPrepend?: boolean;
+  }
+
+  // see http://pdfkit.org/docs/forms.html#text_field_formatting
+  interface FormTextProps extends FormCommonProps {
+    align?: string;
+    multiline?: boolean;
+    password?: boolean;
+    noSpell?: boolean;
+    format?: TextFieldFormatting
+  }
+
+  class FormText extends React.Component<FormTextProps> {}
+
+  interface FormComboAndListProps extends FormCommonProps {
+    sort?: boolean;
+    edit?: boolean;
+    multiSelect?: boolean;
+    noSpell?: boolean;
+    select?: string[];
+  }
+
+  class FormCombo extends React.Component<FormComboAndListProps> {}
+
+  class FormList extends React.Component<FormComboAndListProps> {}
+
+  // see http://pdfkit.org/docs/forms.html#button_field_options
+  interface FormButtonProps extends FormCommonProps {
+    label?: string;
+  }
+
+  class FormPushButton extends React.Component<FormButtonProps> {}
+
   interface NoteProps extends NodeProps {
     children: string;
   }
@@ -519,6 +580,12 @@ declare const Image: typeof ReactPDF.Image;
 declare const Text: typeof ReactPDF.Text;
 declare const Canvas: typeof ReactPDF.Canvas;
 declare const Link: typeof ReactPDF.Link;
+declare const Form: typeof ReactPDF.Form;
+declare const FormField: typeof ReactPDF.FormField;
+declare const FormText: typeof ReactPDF.FormText;
+declare const FormCombo: typeof ReactPDF.FormCombo;
+declare const FormList: typeof ReactPDF.FormList;
+declare const FormPushButton: typeof ReactPDF.FormPushButton;
 declare const Note: typeof ReactPDF.Note;
 declare const Svg: typeof ReactPDF.Svg;
 declare const Line: typeof ReactPDF.Line;