@formu/forms-engine

Schema, types, and validation for Formu — a form platform built for pixel-perfect digitization of paper forms (overlay filler, mobile reflow, server-side PDF export with CJK support).

Pure TypeScript, zero dependencies, no React.

Install

npm install @formu/forms-engine

What's inside

The core model separates layout from data, joined by fieldId — the same schema renders as a desktop pixel-perfect overlay, a mobile flow, or a stamped PDF:

import type { Page, LayoutItem, FieldSchema } from '@formu/forms-engine';

// Layout layer — pixel bboxes on a page canvas
const items: LayoutItem[] = [
  { id: 'i1', type: 'text', content: '姓名', bbox: { x: 28, y: 100, w: 80, h: 14 } },
  { id: 'i2', type: 'field', fieldId: 'f_name', bbox: { x: 112, y: 96, w: 200, h: 24 } },
];

// Data layer — type / label / validation / mobile flow order
const fields: FieldSchema[] = [
  { id: 'f_name', type: 'text', label: '姓名', required: true, flowOrder: 0 },
];

Field types include the usual inputs plus two server-computed types:

• calculated — formula evaluated at submit ({price} * {qty}, SUM, AVG, COUNT, DAYS_BETWEEN)
• serial (流水號) — auto-issued document numbers like WP-2026-0001; the date tokens in the format double as the reset period

import { validateSubmissionFull, formatSerial, validateSerialFormat } from '@formu/forms-engine';

formatSerial({ format: 'PR-{YYYY}-{seq}' }, 42, new Date()); // 'PR-2026-0042'
validateSerialFormat('PR-{YYYY}'); // { code: 'missingSeq' }

Tables are a mini-schema of their own (static / field / covered cells, Excel-style border presets), and visibility rules drive conditional show/hide.

Used by

• The Formu web app (designer / filler) and API (validation, PDF export, serial issuance)
• formu-cli — build and update Formu templates from the command line

License

MIT © Tim Kao