factory-forms-builder

Apply the forms-builder specialist workflow. Build forms grounded in the factory's conventions, not generic react-hook-form code. Load factory-forms through the host's skill capability when needed.

How to think (in order)

1. What kind of form? Pick one:

   • Single-step drawer-CRUD form — create/edit one entity → use the drawer mode union from factory-frontend.md
   • Single-step page form — login, settings, simple intake → vanilla react-hook-form
   • Multi-step wizard — onboarding, complex intake → section files + field registry
   • Inline edit — DataTable cell editing → different pattern, see factory-frontend.md

2. How many fields?

   • < 10 — inline schemas, hand-written JSX
   • 10–30 — section files but no registry needed
   • 30+ or AI-context-aware — field registry

3. Schemas — three variants (see factory-forms.md):

   • Server input — strict (real types, no empty-string fallbacks)
   • Client form — lenient (accepts empty strings because controlled inputs default to '')
   • Patch — partial input for updates

4. Conditional visibility? If any field's display depends on another's value:

   • Declarative rules in src/lib/utils/conditional-visibility.ts
   • Auto-cleanup when parent toggles off — set hidden child's value to undefined
   • Otherwise stale conditional data sneaks into submissions

5. Sensitive fields? SSN, EIN, government IDs, financial accounts:

   • Masked input (mask="99-9999999" etc.)
   • KMS encryption at rest — see factory-security.md
   • Mask in display, decrypt only at the handler that returns plaintext

6. Auto-save? If the form takes more than a couple minutes to fill out:

   • 2s debounce on field blur
   • 3min safety-net interval flush
   • Server accepts the lenient schema during auto-save; strict schema on submission

7. Dynamic field arrays? (contacts, beneficial owners, line items)

   • useFieldArray from react-hook-form
   • Max-count rule via rules: { maxLength: { value: N, message: '...' } }
   • Add/remove buttons; consider drag-reorder for ordered arrays

8. File uploads? Direct-to-S3 with presigned URLs (don't proxy through your server):

   • Server action generates upload URL
   • Client PUTs file to S3
   • Server action confirms upload (records fileKey)

9. Submission UX?

   • useTransition wrapping the async submit
   • isPending gates the submit button
   • Toast on success / error
   • Invalidate the right TanStack Query keys on success