Custom forms and validation
A custom form composes live TableSchema metadata, TanStack Form draft state,
and the server write path. It should not create a second schema. Load existing
records through the focused
cached table reads guide.
Keep state ownership explicit
Section titled “Keep state ownership explicit”Use one owner for each kind of state:
| State | Owner |
|---|---|
| Draft values, dirty state, local validation, submit state | TanStack Form |
| Table metadata, semantic draft decoding, generated CRUD requests | Sapporta frontend APIs |
| Domain request shape, success destination, cache effects, layout | Application screen |
| Write policy, row scope, authoritative validation, transactions | Server route |
Build a metadata-derived form
Section titled “Build a metadata-derived form”import { useMemo } from "react";import { useForm } from "@tanstack/react-form";import { FormField, buildRecordFormFields, firstFormErrorMessage, useLookupStore,} from "@sapporta/frontend";
function TaskEditor({ task, table }: { task: Task; table: TableSchema }) { const lookups = useLookupStore(); const fields = useMemo( () => buildRecordFormFields({ table, lookups }), [lookups, table], ); const form = useForm({ defaultValues: { title: task.title, project_id: task.project_id, due_date: task.due_date, } as Record<string, unknown>, onSubmit: async ({ value }) => submitTask(value), });
return ( <form onSubmit={(event) => { event.preventDefault(); void form.handleSubmit().catch(() => undefined); }} > {fields.map((fieldModel) => ( <form.Field key={fieldModel.column.name} name={fieldModel.column.name}> {(field) => ( <FormField field={fieldModel} value={field.state.value} issue={firstFormErrorMessage(field.state.meta.errors)} onChange={field.handleChange} /> )} </form.Field> ))} <button type="submit">Save task</button> </form> );}buildRecordFormFields() derives editable fields, semantic control kinds,
select options, and scoped foreign-key lookups from the current table schema.
The form may render only a subset or arrange fields into domain sections. Use
fieldModelForColumn() and foreignKeyFieldModelForColumn() when the layout
names specific fields.
Workflow values that are not table columns remain ordinary TanStack Form fields.
Application-specific controls can consume a Sapporta field model without using
FormField when the default rendering does not fit.
Pick a related row
Section titled “Pick a related row”A foreign-key field from buildRecordFormFields() renders a LookupPicker over
the referenced table. The picker searches the table through its row-scoped
lookup and draws each option with the table’s row display. For a table with a
rowCaption, such as accounts with their parent path, each option shows the
caption under the label, and the chosen row’s caption shows inside the field at
its end. Show rows with their captions and display slots
describes the row display. Over a table that declares meta.tree, the picker
draws the table as a tree instead; Pick from a tree
describes it.
A form that lays out its own fields builds the picker from useTableLookup():
import { LookupPicker, useTableLookup } from "@sapporta/frontend/lookup";
function AccountField({ value, onChange,}: { value: number | null; onChange: (value: number | null) => void;}) { const accounts = useTableLookup<number>("accounts"); return ( <LookupPicker<number> lookup={accounts} value={value} onChange={onChange} placeholder="Select account" /> );}Narrow the choices
Section titled “Narrow the choices”The second argument of useTableLookup() limits the rows that the picker’s
search offers. filter takes conditions in the list filter grammar. This picker
offers only asset accounts:
const assetAccounts = useTableLookup<number>("accounts", { filter: [{ column: "account_type", op: "in", values: ["asset"] }],});A condition has the shape { column, op, value } for one value,
{ column, op: "in" | "nin", values } for a list, or
{ column, op: "is", polarity: "null" | "notnull" }. Several conditions are
combined with AND, and the server combines them with the table’s row scope.
Lookups by id are never narrowed. A chosen row therefore keeps its label after it stops matching, such as an account whose type changed after the form loaded.
Each narrowing has its own caches beside the table’s caches. An equal narrowing built again on each render uses the same caches, so the object can be written inline.
Pick from a tree
Section titled “Pick from a tree”Over a tree table, LookupPicker shows the table as an indented tree when it
opens. Every row that passes the narrowing can be picked, and its ancestors that
do not pass are shown greyed to place it. A branch with nothing to pick is left
out. This picker offers expense accounts, under their greyed parents where a
parent is of another type:
const expenseAccounts = useTableLookup<number>("accounts", { filter: [{ column: "account_type", op: "in", values: ["Expense"] }],});
<LookupPicker<number> lookup={expenseAccounts} value={value} onChange={onChange} placeholder="Select account"/>;Typing searches the table on the server and lists the matches flat, each after
its parent path. The chosen row shows its parent path before its name, inside
the field. Both paths are the table’s tree.path field, so the separator is the
one given to treePath(); without tree.path, the picker shows names only. The
siblings follow the table’s defaultSort, and the top-level rows its
tree.rootOrder. Show a table as a tree
describes the declarations.
The narrowing is applied by the server, as for a flat picker: the form passes
only the conditions, such as the account type, and never walks the tree itself.
Pass tree={false} to draw the flat search list instead.
The server’s search returns the first 50 matches, in the order of the table’s primary key. The tree picker has already read the whole narrowed tree, so it can search that tree in the browser instead, finding every match in tree order without a request per keystroke:
const expenseAccounts = useTableLookup<number>( "accounts", { filter: [{ column: "account_type", op: "in", values: ["Expense"] }] }, { search: "client" },);Both searches match the same rows. Until the tree is read, or when it is too large to send, the picker searches the server. Keep the default for a table that can grow without bound; see Choose where a search runs.
Choose a tree row’s parent
Section titled “Choose a tree row’s parent”On a tree table, picking a row’s own descendant as its parent would make a loop.
notUnder leaves out every row below one row. The tree picker shows that row
where it sits, greyed and marked “(being edited)”, so the person sees where the
account is now:
function ParentAccountField({ accountId, value, onChange,}: { accountId: number | undefined; value: number | null; onChange: (value: number | null) => void;}) { const parents = useTableLookup<number>("accounts", { notUnder: accountId }); return ( <LookupPicker<number> lookup={parents} value={value} onChange={onChange} placeholder="Top-level account" /> );}For a new account, accountId is undefined and the picker offers every
visible account. Pass labels={{ editing: "(this account)" }} for other words
after the edited row; a table’s label slot that draws its own content receives
them as context.editingNote. The walk that finds the rows below accountId goes through
every row of the table, including rows the user cannot see, so a row below the
account through a hidden row is also left out. notUnder and filter can be
combined. Sapporta’s own screens do the same for a tree table’s parent column:
the grid’s parent cell editor and the record sheet’s parent field leave out the
row being edited and every row below it.
In the tree, two accounts named “Fuel” under different parents are told apart by where they sit. In a search, each match shows its parent path.
Draw the options
Section titled “Draw the options”itemDisplay changes how each option is drawn. fields names the columns that
the option shows; the lookup search also matches those columns. Without a
component, the picker draws those columns side by side:
import type { Row } from "@sapporta/shared/contracts";
<LookupPicker<number, Row> lookup={accounts} value={value} onChange={onChange} itemDisplay={{ fields: ["code", "name"] }}/>;The second type argument, Row, is the type of each entry’s meta. It lets
fields name the table’s columns.
A component draws each option itself. It receives the entry (its value,
label, and meta, the row’s visible fields) and defaultContent, which is the
option as the table’s label slot draws it, caption included. Wrap
defaultContent to keep the caption:
import type { LookupPickerItemProps } from "@sapporta/frontend/lookup";import type { Row } from "@sapporta/shared/contracts";
function AccountOption({ entry, defaultContent,}: LookupPickerItemProps<number, Row>) { return ( <span className="flex min-w-0 flex-1 items-center gap-2"> <span className="font-mono text-sap-meta">{String(entry.meta.code)}</span> {defaultContent} </span> );}
<LookupPicker<number, Row> lookup={accounts} value={value} onChange={onChange} itemDisplay={{ fields: ["code", "name"], component: AccountOption }}/>;itemDisplay changes the options only. The chosen value is always drawn with
the table’s label slot.
Place the chosen row’s caption
Section titled “Place the chosen row’s caption”selectedCaption decides where the chosen row’s caption is drawn:
| Value | Draws the caption |
|---|---|
"inline" (default) | inside the field, at its end, hidden while the person types |
"below" | on its own line under the field, at full width |
A tree picker draws no caption; the chosen row’s parent path sits before its
name instead, and selectedCaption has no effect.
"below" suits long captions in narrow dialogs, where the inline caption would
be cut short. The line under the field is kept while it is empty, so choosing a
value does not move the fields that follow. With "below", className applies
to the element that holds the field and the caption line. The generated record
form uses "inline".
Word the picker in the application’s terms
Section titled “Word the picker in the application’s terms”labels replaces the picker’s own words, such as the clear button’s name in a
parent picker, where clearing makes the account a top-level one:
<LookupPicker<number> lookup={parents} value={value} onChange={onChange} placeholder="Top-level account" labels={{ clear: "Make it a top-level account", empty: "No account matches.", loadFailed: "Could not read the chart of accounts.", }}/>Each label left out keeps Sapporta’s wording. Name the picker’s buttons and messages lists them.
Name the form instance’s type
Section titled “Name the form instance’s type”ReturnType<typeof useForm<MealDraft>> and ReactFormExtendedApi<MealDraft>
both fail — twelve type parameters, no defaults. Every form.Field under the
bad annotation then degrades to any. Wrap useForm in one hook per form and
name its return type:
function useMealDraftForm(defaults: MealDraft) { return useForm({/* ... */});}
type MealForm = ReturnType<typeof useMealDraftForm>;Keep validators and onSubmit inside the hook so MealForm covers them. Reach
for createFormHook/withForm only when pieces are shared across forms.
Validate with a Standard Schema
Section titled “Validate with a Standard Schema”validators: { onChange: schema } checks the schema’s input type and
discards the transformed output — z.coerce, .trim() and friends report the
draft valid and leave the form value exactly as typed. Re-parse inside
onSubmit when the server needs the transformed value.
Where fields come from table metadata, prefer no schema at all:
parseCreateDraft() already reports required and invalid columns from the live
TableSchema.
Decode creates at submit time
Section titled “Decode creates at submit time”For an ordinary one-table create, keep raw form text until submit and call
parseCreateDraft() once:
const parsed = parseCreateDraft(table, value);if (!parsed.ok) { throw new FormSubmissionError(parsed.issues);}
await createTableRow(table.name, parsed.value);This decode preserves incomplete editor text during interaction. It omits
optional empty non-text fields, preserves empty text as "", canonicalizes
valid semantic values, and reports required or invalid fields. It does not
replace server validation.
Update forms need an explicit patch transform. Create omission and patch omission have different meanings. A create omission permits a default; a patch omission leaves the stored field unchanged.
Use an application typed endpoint when one submit changes several tables or performs a named domain action. TanStack Form still owns the draft, but the application contract owns the request shape and the server owns the transaction.
Map local and remote issues
Section titled “Map local and remote issues”fieldIssuesForSubmissionError() handles local FormSubmissionError values and
recognized Sapporta API validation details. Nested paths remain names such as
lines.0.quantity. Application code maps server fields when its form uses a
different field vocabulary.
Inside onSubmit, catch the rejection, convert the issues, and call
formApi.setErrorMap({ onSubmit: { form, fields } }). Keep a form-level
fallback for transport failures and details that do not name one field. Clear
stale errors from one form-level listeners.onChange rather than per-field
handlers, and catch the promise returned by form.handleSubmit() after the
errors have been rendered.
Never write from validators.onSubmitAsync — the row exists by the time the
validator reports failure. Use it only for read-only pre-write checks such as a
uniqueness probe.
TanStack Form idioms
Section titled “TanStack Form idioms”Sapporta composes TanStack Form with no wrapper or adapter, so the upstream React guides apply directly. Non-obvious points:
useSelector(form.store, selector)in logic,form.Subscribein JSX.useStoreis deprecated.isDirtynever resets — use!isDefaultValueto stop nagging once values match what was loaded.- Dependent fields: field
listeners.onChange+validators.onChangeListenTo, neveruseEffect. validationLogic: revalidateLogic()— validate on submit, then live.- Submit button:
aria-disabled, notdisabled; gate on!canSubmit || isPristine. - Also:
onSubmitInvalid,formOptions().