Forms

Tome's native form engine: code-defined multi-step form definitions (defineForm), a conditional-logic expression evaluator, server-authoritative zod validation, and the tomeForm Payload block render surface. domain layer per root ARCHITECTURE.md — depends on @wabbit/tome-core. Its CSS modules read @wabbit/tome-ui's Layer-2 tokens through var(--tome-*) with fallbacks, so @wabbit/tome-ui is not a peer.

What `TomeForm` renders. TomeForm takes either a form definition or a slug. A definition — from defineForm() in code, or from loadAdminForm() for a form an editor built in the admin forms collection — is rendered as given. A slug is looked up in the in-memory registry that createFormsLayer() (or its deprecated alias initForms()) seeds with your code-defined forms; an unknown slug renders a hidden placeholder <section data-tome-forms-placeholder>. Admin documents are never put into that registry automatically, so render an admin form by loading it:

// Server Component
import { loadAdminForm } from '@wabbit/tome-forms/server'

const form = await loadAdminForm({ payload, slug: 'contact' }) // published documents only
if (form) return <TomeForm form={form} action={submitContact} renderRichText={renderRichText} />

The bound action needs the same definition: build it inside your 'use server' function (submitFormAction(await loadAdminForm({ payload, slug }), payload)(formData)). The loader resolves forms-fields library references into inline fields and runs the result through defineForm, so an admin form gets the same structural validation as a code form and a malformed document throws TomeFormsConfigError. The admin Redirect URL field (submission.redirectUrl) carries over as the definition's redirectUrl: a same-origin path such as /thanks or an absolute http(s):// URL (the admin field and defineForm both reject anything else). On a successful submit the result carries it, so the browser redirects and the thankYou content is skipped — the redirect takes precedence, as the field's description says. Two things do not carry over from an admin document: a custom submission target (it needs a handler function, so loading throws) and named validation.pattern values (email/tel/url — the field type already validates those).

Code-defined forms take precedence. A slug seeded from code owns that slug in the registry. Saving an admin forms document runs its afterChange hook, which drops the registry entry for that slug only when the entry did not come from code, so an editor saving a document with the same slug as a code-defined form never blanks the live form. Only an explicit replaceForm()/invalidateForm() call changes a code-seeded entry.

Rich text. The definition's description renders above the form, and step intro and thankYou render in place, all through the renderRichText prop; without it they are omitted and a successful submit shows a plain "Thank you for your submission." line. defineForm accepts description and thankYou as any value your renderer understands. renderRichText runs on the server only: TomeForm renders the description, each step intro and the thank-you there and hands the client component the rendered nodes (the thank-you is rendered up front and shown after a successful submit), never the function, so a host can pass any renderRichText from a Server Component without hitting "Functions cannot be passed directly to Client Components". TomeFormClient's renderRichText prop is replaced by stepIntros and thankYou nodes; only code that rendered TomeFormClient directly is affected.

Redirect after submit. defineForm({ …, redirectUrl: '/thanks' }) sends the browser to that path (or absolute http(s):// URL) after every successful submit, in place of the thankYou state. When a submission target returns its own redirectUrl (a custom handler, for instance), the target's wins. Without redirectUrl, behavior is unchanged: the thank-you state shows unless the target returned a redirect.

@wabbit/tome-core is a required peer (peerDependencies not dependencies — this package declares no dependencies field at all).

60-second quickstart

Define a form (pure, no Payload/DB touch — defineForm validates and deep-freezes at module load):

import { defineForm } from '@wabbit/tome-forms'

export const contactForm = defineForm({
  slug: 'contact',
  steps: [{ stepName: 'main', fields: [{ name: 'email', type: 'email' }] }],
  submission: { target: 'intake' },
})

Register the block + collections in payload.config.ts:

import { tomeFormBlock, createFormsLayer, createFormsCollections } from '@wabbit/tome-forms'
// blocks: [tomeFormBlock], collections: [...createFormsCollections()]
// createFormsLayer(options) is the top-level layer entry — seeds + freezes the
// in-memory registries, calls createFormsCollections, registers the layer, and
// returns { collections, plugin }. initForms is a deprecated pure alias.

Bind a server action and render (verified pattern from blocks/index.ts's own usage doc comment):

// app/(frontend)/contact/actions.ts — 'use server'
import { submitFormAction } from '@wabbit/tome-forms/server'
import { contactForm } from '@/lib/forms/contact'
export const submitContact = submitFormAction(contactForm, payload)

// app/(frontend)/contact/page.tsx (RSC)
import { TomeForm } from '@wabbit/tome-forms/blocks'
import { submitContact } from './actions'

<TomeForm form={contactForm} action={submitContact} />

Stacked steps, submit note and per-placement defaults

• `appearance.stepsDisplay`: 'wizard' (default, one step at a time) or 'stacked'. Stacked renders every step at once as a numbered <fieldset> whose <legend data-form-step-legend> holds <span data-form-step-number> and the step label, with one submit button. The submit validates every visible step; a step a skipStep rule skips stays hidden (and is not validated), and steps after the one marked isFinalStep are not shown. The root <section> gains data-form-steps="stacked".
• `appearance.submitNote`: a line beside the submit button, <p data-form-submit-note> (e.g. a response-time promise). Shown wherever the submit button is. The button row is end-aligned by default; --tome-forms-submit-justify places it (flex-start puts the button first at the start, the note after it).
• Checkboxes and radios show their box. @wabbit/tome-ui's base stylesheet resets every input to appearance: none with no border or fill, which left a checkbox or a radio in a form an invisible box. The field styles now restore the platform control (appearance: auto, tinted by accent-color), so an unthemed form shows its choices; a theme that draws its own box sets appearance: none again.
• `appearance.optionalMarker`: text after each optional field's label, e.g. '(optional)', in <span data-field-optional>, styled muted (tokens --tome-forms-optional-color, --tome-forms-optional-weight, --tome-forms-optional-size). Unset shows no marker; a lone checkbox never shows it. Set it on the form (code appearance, or the admin forms Appearance group).
• `appearance.hideSingleStepLegend`: opt-in, default off. A form with exactly one step renders <legend data-form-step-legend> with the step label, which usually only repeats the form heading. Set this to hide it visually with an sr-only class while it stays in the accessibility tree (the fieldset keeps its name for screen readers). The TomeForm prop hideSingleStepLegend sets it per placement (true or false; omit to use the form's setting). Forms with two or more steps ignore it. Set it on the form (code appearance, or the admin forms Appearance group, checkbox "Hide Legend On Single-Step Forms").
• `fieldDefaults`: per-placement starting values, [{ name, value }], so the same form placed on two pages can arrive with different preselections. Values are text, converted for the field (true/false, numbers, a comma list for multi-choice fields, an option's value or label for selects). They layer over the definition's own defaultValues and under a draft restored from localStorage, and never replace what the visitor types.

Three of these can be set per placement on the tomeForm block (appearance.stepsDisplay, appearance.submitNote, fieldDefaults[]); the first two can also be set on the form (code appearance, or the admin forms Appearance group). Render the block with TomeFormBlock, which forwards exactly those options:

import { TomeFormBlock } from '@wabbit/tome-forms/blocks'

// in your block map
tomeForm: (block) => <TomeFormBlock {...block} action={actionFor(block.form)} renderRichText={renderRichText} />

TomeFormBlock forwards fieldDefaults, acceptPrefill, prefillNote and, from the block's appearance group, only stepsDisplay and submitNote when they are set. The block's older options (layout, progressIndicator, themeOverride) have never been forwarded, and they still are not, because they always carry their select defaults and would override the form's own settings. A block without the new options renders exactly as <TomeForm form action />. A direct TomeForm caller can pass appearance (any key with a value overrides) and fieldDefaults itself.

Starting values (a field's defaultValue and the placement's fieldDefaults) are rendered into the server HTML (selected, value, checked), so the first paint already shows them. A draft saved in localStorage is applied right after mount and wins over them.

Submitting without JavaScript

A single-step form submits with JavaScript turned off, as long as the action you pass to TomeForm is a server action (the 'use server' export shown in the quickstart). TomeForm then renders <form action={action}>, and a browser that cannot run scripts, or posts before they load, posts the form to that same action. With JavaScript running nothing changes: the client submit handler takes over, and the form behaves as it always did.

• Several choices. multiselect and checkboxGroup post one entry per choice; the action reads them all (FormData.getAll, for any field type whose descriptor sets multiple: true), drops blanks and duplicates, and validates each against the options, so an unknown value is rejected and a required group with nothing chosen says "Required". A failed no-JavaScript post echoes the chosen set.
• Same pipeline. The action accepts a bare FormData (the client handler) and the (previousState, formData) shape React uses for a posted form. Both go through the same sanitizing, server rule evaluation, derivations, zod validation and target dispatch, so a no-JavaScript post is validated exactly like any other.
• After the post. If the form has a redirectUrl (or the target returns one), the action redirects server-side with Next's redirect(). Otherwise the page reloads and shows the thankYou content. A failed post comes back as the form again, with the visitor's answers kept and one message under each field that needs fixing (see "A failed post without JavaScript" below).
• Honeypot. In this mode the _hp field sits inside the form so it is posted; on the JavaScript path the client reads it from the form's section and sends it. Either way a filled honeypot is flagged (_honeypotTriggered; flagged, not rejected).
• What the no-JavaScript path cannot do. There is no client-side validation, live rule-driven show/hide (the rules run once per post, on the server render; see below), draft saving or time-to-submit stamp (_timeToSubmitMs arrives empty). Rate limits and CAPTCHA checks are not part of @wabbit/tome-forms: any you add around the action run on this path too, because it is the same action. A check that needs a browser script, such as a Turnstile widget, cannot pass without JavaScript, so set requireJavaScript on that form's action: submitFormAction(form, payload, { requireJavaScript: true }) refuses a no-JavaScript post with an error before anything is validated or stored (it fails closed). An intake form whose intake verification provider is not 'none' already refuses every submission from this layer, with or without JavaScript, because the layer does not forward a verification token.
• Multi-step forms still need JavaScript. Back and Next are buttons that run script, so only a form with exactly one step renders as a real form post. Pass progressiveSubmit={false} to TomeForm to keep the JavaScript-only form for a single-step form too.
• Default render. When the action is a plain function (not a server action), or the form has more than one step, the markup is byte-identical to before.

Number fields and their messages

number, range and rating never show zod's own wording (such as "Invalid input: expected number, received NaN"). A blank answer (empty, spaces, or the NaN an empty number input reads as) is "not provided": an optional field passes and a required one says "Required". Text that is not a number says "Enter a number." (rating: "Enter a whole number."), and min/max say "Enter a number of 1 or more." / "Enter a number of 40 or less." validation.customMessage replaces every one of these, as it does for the other types.

A failed post without JavaScript

Without script, the rules cannot react while the visitor types: a field a rule hides on the starting values is simply not on the first page. So the round trip carries the answers back to the server render:

1. The post returns the answers and one message per field. On the form-post shape only, a failed result adds fieldErrors (field name to message, the same messages the zod schema and validation.customMessage give) and values (the visitor's own answers). The joined error string stays, for anything that reads it. A submission target's own fieldErrors (for a check only the target can make, such as a capacity limit) are passed through and win.
2. The re-render runs the rules on those answers. The answers are laid over the starting values (definition defaultValues and the placement's fieldDefaults), so a visitor who picked a type and posted gets that type's fields on the returned page, with their answers and their messages. A field that was not on the page when it was posted keeps its starting value.
3. Each message sits under its field, at {fieldId}-error with role="alert", tied to the control by aria-describedby (with the help text, when there is one) and aria-invalid="true". The error summary above the form lists the messages in field order, as "Label: message", each linking to its control (for a radio or checkbox set, the chosen option, else the first). The first invalid field on the page gets autofocus, so the browser lands on it with no script.

What is never echoed back: file inputs (a browser cannot prefill one), author-declared hidden fields (they re-render with the author's value, so a tampered value is not reflected), section and repeater fields, the honeypot and the other engine fields (_hp, _timeToSubmitMs, attribution), names the form does not define, a choice outside a field's options, and any field the rules hid, or a skipped step removed, on the submitted answers. So a value typed into a field that a later answer hid is dropped: it is neither echoed nor sent to the target, exactly as the server already treated it. The page re-renders the visitor's own answers and nothing else: no stored data, no other submission. The client also checks the echoed answers against the definition (known field, echoed type, right shape) before using them.

With JavaScript running none of this applies: the client submit handler calls the action with a bare FormData, gets the same result as before (no fieldErrors, no values), and validates in the browser as it always did; every render with no errors is byte-identical to before. When a Next or submit fails validation, the client shows the same error summary the round trip does (one "Label: message" line per invalid field in field order, each linking to its control, in the role="alert" box), and focus moves to that box. The list follows the visitor's fixes and is gone when the last error is. A no-JavaScript result can also reach a page where script has since loaded (React replays a form posted before hydration); it seeds the form the same way, beats an older localStorage draft, and the messages give way to the browser's own once the visitor submits again.

Limits: the round trip applies to single-step forms only (multi-step forms need JavaScript, see above). A rule that reads a field which is itself hidden still sees that field's posted value on the server, while the re-render sees its starting value, so a chain of rules (C depends on B, B hidden by A) can differ between the two; keep no-JavaScript-critical rules one level deep.

Link prefill

A page can send a visitor to a form with one answer already chosen. It is off until a placement sets acceptPrefill, and then it works two ways:

• From the URL: /contact?path=project preselects the path field on load.
• From an in-page link: <a href="#contact" data-form-prefill="path=ongoing">Write to me</a> applies the value when clicked, moves focus to the changed field, and scrolls to the form (a link with a #fragment keeps the browser's own scroll; a link to the same page with no fragment scrolls with scrollIntoView, instant under prefers-reduced-motion). A link counts only when it points at this page and either has no fragment or names an element that contains the form, so links to other pages and other anchors are left alone. Modified clicks (Ctrl, Cmd, Shift, Alt) are left to the browser.

Only the allowlisted field names are set, and a value must fit the control: a radio or select needs one of its options (matched by value, then by label), a text-like input takes the text (capped at 500 characters). Anything else is ignored. A field the visitor's saved localStorage draft already answers is left alone on load; a click on a link is an explicit choice and applies.

Set it on the tomeForm block (acceptPrefill[] rows of { field }, and an optional prefillNote) or pass acceptPrefill (names, or the block rows) and prefillNote to TomeForm. After a prefill the note is written into <p data-form-prefill-note aria-live="polite">, which is in the markup (empty) as soon as the allowlist is set so the change is announced; prefillNote is a template where {label} is the chosen option's label, and the default reads "{label} is preselected from the link you followed. Change it if you like." The field's wrapper gains data-form-prefilled. The note takes --tome-forms-prefill-note-size, --tome-forms-prefill-note-color and --tome-forms-prefill-note-gap. With no allowlist the markup is byte-for-byte what it was.

The block gains two Payload fields (acceptPrefill, prefillNote), so on Postgres generate a migration after upgrading.

TomeFormBlock also forwards three optional block fields to TomeForm: errorSummaryLabel (text; the error summary heading, with {count} for the number of invalid fields, e.g. "{count} things need fixing:"), errorSummaryLabelOne (text; the heading used when exactly one field is invalid, e.g. "1 thing needs fixing:", so the plural never reads "1 things"; empty falls back to errorSummaryLabel) and focusOnError (select, field | summary; where focus goes after a failed Next or submit with script on). All three are empty by default, and a block that leaves them empty renders byte-identically. They are plain (not localized) text and select fields; on Postgres generate a migration after upgrading.

A form that does not use the forms engine can reuse the same behavior through the framework-free helper, which lives in @wabbit/tome-core/utilities/formPrefill (free tier) and is re-exported from this package's @wabbit/tome-forms/prefill subpath. It works on the markup (it sets the control and fires input and change, so a form library sees an ordinary edit), reads its window from the element, and returns a function that removes its click listener:

import { applyFormPrefill } from '@wabbit/tome-core/utilities/formPrefill'

// in an effect, once the form is in the DOM
const stop = applyFormPrefill(formElement, {
  allow: ['path'],
  noteElement: noteElement, // an aria-live="polite" element rendered up front
  note: '{label} is preselected.',
})

Data policy: contact-only

Forms were built for lead capture, so by default (dataPolicy: 'standard') every declared value is stored and a form can ask for anything. A form, or a whole site, can opt in to 'contact-only', which limits what the form asks for and where the answers travel.

import { defineForm, createFormsLayer } from '@wabbit/tome-forms'

const inquiry = defineForm({
  slug: 'inquiry',
  dataPolicy: 'contact-only',
  dataNotice: 'Please do not include medical details here.', // optional; replaces the default notice
  steps: [
    {
      stepName: 'main',
      stepLabel: 'Get in touch',
      fields: [
        { name: 'name', type: 'text', label: 'Name', required: true },
        { name: 'email', type: 'email', label: 'Email', required: true },
        { name: 'message', type: 'textarea', label: 'Message', validation: { maxLength: 500 } },
      ],
    },
  ],
  submission: { target: 'intake' },
})

createFormsLayer({
  forms: [inquiry],
  // Site-wide: `default` applies to forms that set no policy; `lock` refuses a form that sets 'standard';
  // `sensitiveTerms` refuses a field whose name or label contains one (case-insensitive, substring).
  policy: { default: 'contact-only', lock: true, sensitiveTerms: ['symptom'], retention: { contactOnlyDays: 90 } },
})

What it does under 'contact-only':

What it does not do: it does not scan or filter what a person types into the message box, and it cannot stop someone entering anything there. The message is stored until a retention policy removes it, and staff can read it in the admin. It does not encrypt data beyond what your host provides, and it does not make your email provider, host or database a party to any agreement. It is not a legal or regulatory determination: using it does not make a site compliant with anything, so have counsel review how you describe and use it.

standard forms behave exactly as before. A payload target still stores the full declared payload for them.

Retention

formsRetentionPolicies({ days, formSlugs }) returns @wabbit/tome-core/gdpr/retention policy rows: hard-delete forms-submissions rows whose submittedAt is older than days, in the listed forms only. Without arguments it covers every registered contact-only form and uses policy.retention.contactOnlyDays. It builds rows and runs nothing: schedule them yourself, and run runRetention({ dryRun: true }) first to read each policy's matched count, because a hard delete is permanent.

import { formsRetentionPolicies } from '@wabbit/tome-forms'
import { defineRetentionPolicies, createRetentionEndpoint } from '@wabbit/tome-core/gdpr/retention'

const policies = defineRetentionPolicies(formsRetentionPolicies({ days: 90, formSlugs: ['inquiry'] }))
// then: createRetentionEndpoint({ policies, lock }) or createRetentionTask({ policies, lock })

createFormsLayer logs one warning at startup for a contact-only form when policy.retention.contactOnlyDays is not set; it does not refuse, because scheduling lives outside this package.

Export and erasure

createFormsLayer registers forms-submissions with core's GDPR registry, matched on a new indexed email column that is filled from the form's first email field (for every form that has one). Core's data export and account-erasure pipelines then find those rows. The column is an additive schema change, so a database that applies migrations needs one. Rows written before this release have no email value and are not found until it is backfilled.

Public API

Server / client posture

The block render layer is a deliberate two-file split:

• `blocks/TomeForm.server.tsx` — no 'use client' directive; a genuine RSC. Uses the definition it is given, or loads it by slug via getForm(), renders the description through renderRichText, compiles the per-step schema via compileFormSchema (isomorphic — safe in RSC), renders the outer shell (<section>, data-theme, aria-live announcer, honeypot field), and forwards the consumer-bound server action untouched to the client boundary. Does not call getPayload() itself and does not import @wabbit/tome-motion.
• `blocks/TomeForm.client.tsx` — the 'use client' boundary; owns interactive state (react-hook-form, step navigation, client-side rule evaluation via the re-exported evaluator).

Only these two files (plus the top-level blocks/tomeFormBlock.ts, which is React-free config) touch React directly. hooks/beforeValidate.ts carries no server-only import guard — the only match for "server-only" in that file is a comment ("server-only path") — but it's a Payload collection hook, never bundled client-side by construction. Everything else (engine/evaluator.ts, engine/fieldRegistry.ts, engine/registry.ts, defineForm.ts) is plain TypeScript with no browser or Node-specific API, safe to import from either side — which is exactly what lets the evaluator be re-exported from @wabbit/tome-forms/server and consumed by the client component in the same module instance (the "dual-evaluation contract").

The root barrel deliberately excludes the React-bearing TomeForm/TomeFormClient (they live on @wabbit/tome-forms/blocks) so that importing @wabbit/tome-forms in a payload.config.ts for collection/field registration never risks pulling React or CSS Modules into the config-evaluation path.

Extending

New field types register via registerFieldType() before freezeFieldRegistry() is called (typically at createFormsLayer() time). New submission targets are a switch arm in defineForm.ts's validateSubmissionConfig plus a corresponding target module under server/targets/.

Design history

• Original design centered on the field/rule/derivation contract: a topologically-sorted derivation graph, a pluggable field-type registry, and the RSC/client split described above (the "dual-evaluation contract" that lets the same evaluator run server-side and client-side).
• docs/claude-gotchas.md → Payload / Typing / Layer Design section — "RichText render contracts differ per pack — always render-walk" and "Config-time vs view split for tsx-evaluated modules" both apply directly to this package's block/collection split