Form Builder
Schema-driven form rendering with TanStack Form, Zod validation, and accessible components.
The Form Builder provides a typed toolkit for building data-entry experiences ranging from single-record forms to high-volume CSV imports. It layers reusable primitives on top of TanStack Form, Zod, and Papa Parse.
Getting Started
import { FormBuilder } from "@tilt-legal/cubitt-components/composites";FormBuilder.Single
Schema-driven single-record forms with multi-step wizard support.
FormBuilder.Bulk
Bulk ingestion with CSV/file drop, header mapping, and grid editing.
Form Definitions
Declarative tree of steps, groups, and fields shared across both builders.
Validation
Shared validation patterns for client and server-side error handling.
Core Concepts
Typed Schemas
Every flow starts with a Zod schema. The schema is passed to TanStack Form for client-side validation and can be reused server-side for parity.
import {
z } from "zod";
export const memberSchema = z.object({
firstName: z.string().min(1,
"Required"),
lastName: z.string().min(1,
"Required"),
email: z.string().email("Invalid email"),
});
export type Member = z.infer<typeof memberSchema>;Form Definitions
formDefs is a declarative array describing your form's structure—steps,
groups,
and fields. Both FormBuilder.Single and FormBuilder.Bulk consume the same definitions,
so you maintain one source of truth.
import type { FormDefs } from "@tilt-legal/cubitt-components/composites";
const formDefs = [
{
kind: "group",
title: "Contact",
children: [
{ kind: "field", name: "firstName", label: "First name", component: "text", size: "half" },
{ kind: "field", name: "lastName", label: "Last name", component: "text", size: "half" },
{ kind: "field", name: "email", label: "Email", component: "email", size: "full" },
],
},
] as const satisfies FormDefs<Member>;Submit Contracts
- Single forms:
onSubmit(values)receives the form data. Return aZodErrorfor server-side validation failures. - Bulk forms:
onSubmit({ rows })receives the array of rows. Return aBulkSubmitFailureto surface errors in the grid.
Utilities
The form builder exports several utilities for advanced use cases:
import {
useBulkFormBuilder,
injectFormError,
shapeRows,
mapZodError,
} from "@tilt-legal/cubitt-components/composites";
import {
// Form creation hooks
useFormBuilder,
// Error injection
injectZodErrors,
// Data utilities
flattenFormDefs,
// Field rendering
FieldRenderer,
} from "@tilt-legal/cubitt-components/composites";| Utility | Description |
|---|---|
useFormBuilder | Low-level hook for creating single forms with TanStack Form |
useBulkFormBuilder | Low-level hook for creating bulk forms with validation |
injectZodErrors | Inject ZodError issues into a form's field errors |
injectFormError | Inject form-level error messages |
flattenFormDefs | Flatten nested formDefs into a flat field array |
shapeRows | Coerce raw CSV data using field metadata |
mapZodError | Map ZodError to field paths for display |
FieldRenderer | Render individual fields from formDefs |