Skip to content

Custom forms and validation

View as Markdown

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.

Use one owner for each kind of state:

StateOwner
Draft values, dirty state, local validation, submit stateTanStack Form
Table metadata, semantic draft decoding, generated CRUD requestsSapporta frontend APIs
Domain request shape, success destination, cache effects, layoutApplication screen
Write policy, row scope, authoritative validation, transactionsServer route
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.

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"
/>
);
}

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.

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.

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.

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.

selectedCaption decides where the chosen row’s caption is drawn:

ValueDraws 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.

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.

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.

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.

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.

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.Subscribe in JSX. useStore is deprecated.
  • isDirty never resets — use !isDefaultValue to stop nagging once values match what was loaded.
  • Dependent fields: field listeners.onChange + validators.onChangeListenTo, never useEffect.
  • validationLogic: revalidateLogic() — validate on submit, then live.
  • Submit button: aria-disabled, not disabled; gate on !canSubmit || isPristine.
  • Also: onSubmitInvalid, formOptions().