factory-forms

Factory forms

Each section leads with Principle (one sentence, stack-agnostic), then Why (constraint → option → tradeoff), then Recipe (the react-hook-form / Zod / Mantine or shadcn shape), and Failure mode when there's one to name. Sections that are pure style with no deeper truth are marked Recipe only.

Stack

Recipe only.

• react-hook-form — form state, validation, submission
• Zod — schemas
• Resolver — mantine-form-zod-resolver (Mantine) or @hookform/resolvers/zod (shadcn)
• Server submission — server action or tRPC mutation (see factory-api.md)

Three Zod schema variants — server strict, client lenient, patch partial

Principle. Maintain three schema variants per entity: server strict, client lenient, patch partial. Don't try to unify them.

Why. HTML inputs in controlled React forms initialize to ''; the server expects null or a valid value. A unified schema accommodates both by sprinkling .or(z.literal('')) everywhere, which leaves the server schema enforcing nothing. Three schemas keeps each contract sharp: the server enforces real shape, the client tolerates the input flux, the patch shape is structurally partial (only-what-changed). Cost: more schema. Benefit: each layer's invariants stay enforceable.

Recipe.

// features/customers/schema.ts

// Server input — strict types, server enforces these
export const customerInputSchema = z.object({
  orgId: z.string().uuid(),
  name: z.string().min(1),
  email: z.string().email(),
  phone: z.string().regex(/^\+?[0-9-]+$/),
  industry: z.enum(['retail', 'wholesale', 'manufacturing']),
});

// Client form — lenient, accepts empty strings (controlled-input compat)
export const customerFormSchema = z.object({
  orgId: z.string().uuid(),
  name: z.string().min(1, 'Required'),
  email: z.string().email().or(z.literal('')).optional(),
  phone: z.string().or(z.literal('')).optional(),
  industry: z.enum(['retail', 'wholesale', 'manufacturing']).or(z.literal('')).optional(),
});

// Patch — partial updates
export const customerPatchSchema = customerInputSchema.partial();