Add spec: tn-forms-v4

Modular Zod + Formik toolkit to replace class-based Form/FormField/Validator API.
12 assertions on feature/v4 branch covering:
- Core (framework-agnostic): createFormConfig, fieldMeta, createArrayHelpers,
  createAsyncValidate, createStepValidator, snapshotValues
- React hooks: useFormField, useFormArray, useStepForm, useFormSubmit
- Package setup with subpath exports (/core, /react)
- Migration guide from v3

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Pari Work Temp

specs/tn-forms-v4/assertions/async-validate.md

@@ -0,0 +1,27 @@
+---
+id: async-validate
+parent: tn-forms-v4
+created: 2026-03-07T20:00:00Z
+priority: 1
+status: not_started
+depends-on: create-form-config
+branch: feature/v4
+---
+
+# createAsyncValidate bridges async Zod refines to Formik's validate prop
+
+`createAsyncValidate(zodSchema)` returns an async function compatible with Formik's `validate` prop that supports async Zod refinements (e.g., server-side email uniqueness checks, API-based zip code validation).
+
+Formik supports async validation via `validate` (function prop) but NOT via `validationSchema`. `zod-formik-adapter`'s `toFormikValidationSchema` only handles synchronous validation. This leaves a gap for schemas with `.refine(async ...)`.
+
+## Success Criteria
+
+- `createAsyncValidate(schemaWithAsyncRefines)` returns `async (values) => errors`
+- Returned function matches Formik's `validate` signature: accepts values object, returns errors object (or empty object if valid)
+- Errors are keyed by field name matching Zod's error path
+- Async refines run and their errors appear on the correct field
+- Sync refines in the same schema also work (mixed sync/async)
+- Cross-field async refines (e.g., `.refine(async (data) => ...)`) map errors to the correct `path` field
+- Debounce-friendly: does not introduce its own debouncing (consumers handle that)
+- Can be used alongside `validationSchema` for sync rules + `validate` for async rules
+- Tests verify: async field validation, async cross-field validation, error path mapping, mixed sync/async schemas

specs/tn-forms-v4/assertions/create-array-helpers.md

@@ -0,0 +1,26 @@
+---
+id: create-array-helpers
+parent: tn-forms-v4
+created: 2026-03-07T20:00:00Z
+priority: 1
+status: not_started
+depends-on: create-form-config
+branch: feature/v4
+---
+
+# createArrayHelpers provides typed add/remove/defaults for Formik FieldArrays
+
+`createArrayHelpers(zodArrayItemSchema)` returns helpers for managing dynamic form arrays with Formik's `<FieldArray>`, replacing tn-forms v3's `FormArray` class.
+
+tn-forms v3 `FormArray` provided: typed `add()` with default values from the FormClass, `remove(index)`, `groups` array, `value` extraction, and `replicate()`. Formik's `<FieldArray>` gives raw `push`/`remove` but no typed defaults for new rows.
+
+## Success Criteria
+
+- `createArrayHelpers(addressSchema)` returns `{ defaultItem, fieldNames }`
+- `defaultItem` is a fully-typed object with defaults extracted from the item schema (uses same logic as `createFormConfig`)
+- `fieldNames` is a typed tuple of the item schema's field names
+- Works with Formik's `<FieldArray>` — `arrayHelpers.push(defaultItem)` adds a typed row
+- Handles nested schemas: `z.object({ street: z.string().default(''), city: z.string().default('') })`
+- Handles nullable fields in array items: `z.string().nullable().default(null)`
+- Tests verify: creating default items, type inference on items, integration with Formik FieldArray push
+- Replaces tn-forms v3 patterns: `new FormArray({ FormClass, groups: [] })`, `.add()`, `.remove()`, `.groups[i].field`

specs/tn-forms-v4/assertions/create-form-config.md

@@ -0,0 +1,27 @@
+---
+id: create-form-config
+parent: tn-forms-v4
+created: 2026-03-07T20:00:00Z
+priority: 1
+status: not_started
+branch: feature/v4
+---
+
+# createFormConfig returns initialValues, validationSchema, and fieldNames from a Zod schema
+
+`createFormConfig(zodSchema)` accepts any `z.ZodObject` or `z.ZodEffects` (refined object) and returns:
+
+- `initialValues` — extracted from `.default()` values on each field. Handles `ZodDefault`, `ZodOptional`, `ZodNullable`, `ZodArray`, `ZodBoolean`, `ZodNumber`, `ZodUnion`, and `ZodEffects` (refinements). Does NOT call `schema.parse({})` (which throws on required fields).
+- `validationSchema` — Formik-compatible validation schema via `zod-formik-adapter`'s `toFormikValidationSchema`
+- `fieldNames` — typed tuple of all top-level field names from the schema shape
+
+## Success Criteria
+
+- `createFormConfig(z.object({ name: z.string().default(''), age: z.number().default(0) }))` returns `{ initialValues: { name: '', age: 0 }, validationSchema: <FormikSchema>, fieldNames: ['name', 'age'] }`
+- Handles `z.string().nullable().default(null)` → `null`
+- Handles `z.array(z.string()).default([])` → `[]`
+- Handles `z.boolean().default(false)` → `false`
+- Handles schemas with `.refine()` — extracts defaults from the inner `z.ZodObject`
+- `fieldNames` is typed as `readonly` tuple of literal string keys, not `string[]`
+- Exported from package index
+- Tests cover all Zod type permutations from tn-forms v3 test suite (string, number, boolean, date, null, arrays, nested objects)

specs/tn-forms-v4/assertions/field-meta.md

@@ -0,0 +1,25 @@
+---
+id: field-meta
+parent: tn-forms-v4
+created: 2026-03-07T20:00:00Z
+priority: 2
+status: not_started
+branch: feature/v4
+---
+
+# fieldMeta co-locates UI metadata with Zod schema fields
+
+`fieldMeta(zodSchema, metaMap)` associates UI metadata (label, placeholder, type, icon) with schema field names in a type-safe way.
+
+Zod schemas carry validation but no UI information. tn-forms v3 stored `label`, `placeholder`, and `type` on each `FormField`. This utility preserves that pattern without coupling UI concerns into the validation schema.
+
+## Success Criteria
+
+- `fieldMeta(schema, { name: { label: 'Full Name', placeholder: 'Enter name' } })` returns a typed metadata object
+- TypeScript errors if a key in `metaMap` doesn't exist in the schema shape
+- TypeScript errors if metadata fields don't match the `FieldMeta` interface (`{ label?: string, placeholder?: string, type?: string }` — extensible via generic)
+- Metadata object is indexable by field name: `meta.name.label`
+- Works with `z.ZodObject` and `z.ZodEffects` (refined schemas)
+- Does NOT modify or wrap the Zod schema — it's a parallel data structure
+- Exported from package index
+- Tests verify type safety and runtime access

specs/tn-forms-v4/assertions/migration-guide.md

@@ -0,0 +1,30 @@
+---
+id: migration-guide
+parent: tn-forms-v4
+created: 2026-03-07T20:00:00Z
+priority: 2
+status: not_started
+depends-on: package-setup
+branch: feature/v4
+---
+
+# Migration guide documents path from tn-forms v3 to v4
+
+A migration guide exists that maps every tn-forms v3 pattern to its v4 equivalent, with before/after code examples. Published as the package README.
+
+## Success Criteria
+
+- README.md contains a migration guide section with before/after examples for:
+  - `new FormField({ validators: [...] })` → Zod schema field with `.min()`, `.email()`, etc.
+  - `new Form(values) as TUserForm` → `createFormConfig(schema)` + Formik `<Formik>`
+  - `form.value` → Formik `values`
+  - `form.isValid` / `field.isValid` → Formik `isValid` / `!errors.fieldName`
+  - `form.validate()` → Formik `validateForm()`
+  - `FormArray` add/remove → `createArrayHelpers` + Formik `<FieldArray>`
+  - `FormLevelValidator` / `MustMatchValidator` → Zod `.refine()` on object
+  - `form.replicate()` → `snapshotForm` / `restoreForm`
+  - Field metadata (label, placeholder) → `fieldMeta()`
+  - `isRequired: false` pattern → Zod `.optional()` or conditional `.refine()`
+- Each example shows the v3 code and the v4 equivalent side by side
+- Guide mentions breaking changes (removed classes, peer deps required)
+- Guide includes a "Quick Start" section for new projects (not migrating)

specs/tn-forms-v4/assertions/package-setup.md

@@ -0,0 +1,35 @@
+---
+id: package-setup
+parent: tn-forms-v4
+created: 2026-03-07T20:00:00Z
+priority: 1
+status: not_started
+branch: feature/v4
+---
+
+# Package ships submodule architecture with separate entry points for core and react
+
+The `@thinknimble/tn-forms` package (v4) uses package.json `exports` field for subpath imports. Core utilities (Zod-only) are importable without React. React/Formik hooks are a separate entry point with their own peer deps.
+
+## Success Criteria
+
+- `package.json` version is `4.0.0-beta.1`
+- `package.json` `exports` field defines three entry points:
+  - `"."` → `dist/index.js` (re-exports core + react)
+  - `"./core"` → `dist/core/index.js` (Zod utilities only)
+  - `"./react"` → `dist/react/index.js` (React + Formik hooks)
+- Source structure:
+  - `src/core/` — all framework-agnostic utilities
+  - `src/react/` — all React/Formik hooks
+  - `src/index.ts` — barrel re-export of both
+- Peer dependencies:
+  - `zod` — required by core
+  - `formik`, `react`, `zod-formik-adapter` — required by react, marked as optional peers for core-only consumers
+- `peerDependenciesMeta` marks `formik`, `react`, and `zod-formik-adapter` as `optional: true`
+- Old v3 source files (`src/forms.ts`, `src/validators.ts`, `src/interfaces.ts`, `src/types.ts`, `src/utils.ts`, `src/custom-types/`) are removed
+- `email-validator`, `luxon`, `libphonenumber-js`, `@thinknimble/tn-utils`, `babel-loader`, `install` are removed from dependencies
+- `tsup` config builds all three entry points with correct output paths and declaration files
+- `import { createFormConfig } from '@thinknimble/tn-forms/core'` works without React installed
+- `import { useFormField } from '@thinknimble/tn-forms/react'` works when React + Formik are installed
+- `import { createFormConfig, useFormField } from '@thinknimble/tn-forms'` works as barrel import
+- TypeScript builds cleanly, all entry points have `.d.ts` files

specs/tn-forms-v4/assertions/snapshot-restore.md

@@ -0,0 +1,25 @@
+---
+id: snapshot-restore
+parent: tn-forms-v4
+created: 2026-03-07T20:00:00Z
+priority: 2
+status: not_started
+branch: feature/v4
+---
+
+# snapshotValues and restoreValues deep copy plain form value objects
+
+`snapshotValues(values)` creates a deep copy of a plain values object. `restoreValues` is a type-safe identity that ensures the snapshot shape matches. These are framework-agnostic utilities in `/core` — the React layer (`useFormField`, etc.) can use them internally, and consumers can use them for edit/cancel patterns with any framework.
+
+Replaces tn-forms v3's `form.replicate()`. Framework-specific restore (e.g., calling `formik.setValues(snapshot)`) is the consumer's responsibility — this utility only handles the deep copy.
+
+## Success Criteria
+
+- `snapshotValues(values)` returns a deep copy — no shared references with the original
+- Works with nested objects, arrays, null values, Date objects
+- Typed: `snapshotValues<T>(values: T): T` preserves the input type
+- Mutating the original after snapshot does NOT affect the snapshot
+- Mutating the snapshot does NOT affect the original
+- Exported from `@thinknimble/tn-forms/core`
+- No React or Formik dependency
+- Tests verify: deep copy independence, nested objects, arrays, null handling, Date preservation, no shared references

specs/tn-forms-v4/assertions/step-validator.md

@@ -0,0 +1,31 @@
+---
+id: step-validator
+parent: tn-forms-v4
+created: 2026-03-07T20:00:00Z
+priority: 1
+status: not_started
+depends-on: create-form-config
+branch: feature/v4
+---
+
+# createStepValidator checks validity of a field subset for multi-step forms
+
+`createStepValidator(zodSchema)` returns a function `isStepValid(values, errors, fieldNames)` that checks whether the specified fields have values and no validation errors. This is a framework-agnostic utility in `/core` — it works with plain objects, not Formik-specific state.
+
+The React hook `useStepForm` wraps this internally, but it's also usable with Vue, Svelte, or any other framework that has a values object and an errors object.
+
+## Success Criteria
+
+- `createStepValidator(schema)` returns `{ isStepValid, getStepErrors }`
+- `isStepValid(values, errors, ['firstName', 'lastName'])` returns `true` only if:
+  - No errors exist for those fields in the errors object
+  - Each field has a non-empty value (not `null`, `undefined`, `''`, or whitespace-only string)
+- `getStepErrors(errors, ['firstName', 'lastName'])` returns only the errors for the specified fields
+- Handles boolean fields: `false` is treated as a valid value (not empty)
+- Handles number fields: `0` is treated as a valid value (not empty)
+- Handles array fields: `[]` is treated as empty, `['item']` is non-empty
+- Works with nested field names (dot notation): `isStepValid(values, errors, ['address.street'])`
+- Type-safe: field names are constrained to keys of `z.infer<typeof schema>`
+- Exported from `@thinknimble/tn-forms/core`
+- No React or Formik dependency
+- Tests verify: valid step, invalid step (errors), invalid step (empty values), nested fields, edge cases (boolean false, number 0, empty arrays)

specs/tn-forms-v4/assertions/use-form-array.md

@@ -0,0 +1,29 @@
+---
+id: use-form-array
+parent: tn-forms-v4
+created: 2026-03-08T00:00:00Z
+priority: 1
+status: not_started
+depends-on: create-array-helpers
+branch: feature/v4
+---
+
+# useFormArray provides typed array management with defaults for Formik FieldArrays
+
+`useFormArray(name, itemSchema)` wraps Formik's `<FieldArray>` logic into a hook that provides typed `addRow()` (with defaults from the Zod item schema), `removeRow(index)`, and access to the current rows — replacing tn-forms v3's `FormArray` class.
+
+## Success Criteria
+
+- `useFormArray('addresses', addressItemSchema)` returns `{ rows, addRow, removeRow, fieldNames }`
+  - `rows` — the current array values, typed as `z.infer<typeof addressItemSchema>[]`
+  - `addRow()` — pushes a new item with defaults extracted from `addressItemSchema` (uses `createArrayHelpers` internally)
+  - `addRow(overrides)` — pushes a new item with defaults merged with provided overrides
+  - `removeRow(index)` — removes the item at the given index
+  - `fieldNames` — typed tuple of the item schema's field names
+- Each row is accessible for per-field wiring: `rows[i]` gives the values, errors accessed via `errors.addresses[i].city`
+- Adding a row does NOT trigger validation on existing rows
+- Removing a row updates indices correctly
+- Works with nested schemas (item schema can have nested objects/arrays)
+- Hook must be called within a `<Formik>` context
+- Exported from `@thinknimble/tn-forms/react`
+- Tests verify: add with defaults, add with overrides, remove, type inference, no validation side effects on add

specs/tn-forms-v4/assertions/use-form-field.md

@@ -0,0 +1,28 @@
+---
+id: use-form-field
+parent: tn-forms-v4
+created: 2026-03-08T00:00:00Z
+priority: 1
+status: not_started
+depends-on: field-meta
+branch: feature/v4
+---
+
+# useFormField combines Formik's useField with fieldMeta into a single hook
+
+`useFormField(name, meta?)` wraps Formik's `useField()` and merges in field metadata (label, placeholder, type) so components get everything they need from one call. Replaces the pattern of manually wiring `useField()` + error display + metadata lookup.
+
+## Success Criteria
+
+- `useFormField('email')` returns `{ field, meta, helpers, error, touched, label, placeholder, type }`
+  - `field` — Formik's field props (`value`, `onChange`, `onBlur`, `name`)
+  - `meta` — Formik's meta (`error`, `touched`, `initialValue`)
+  - `helpers` — Formik's helpers (`setValue`, `setTouched`, `setError`)
+  - `error` — shorthand: `meta.touched && meta.error` (only shows after interaction)
+  - `label`, `placeholder`, `type` — from fieldMeta if provided to a parent `<FormMetaProvider>`
+- `<FormMetaProvider meta={fieldMetaObject}>` context provider makes metadata available to all `useFormField` calls within its tree
+- `useFormField('email', { label: 'Email', placeholder: 'you@example.com' })` accepts inline override that takes precedence over provider
+- Returns are fully typed based on the form values type
+- Hook must be called within a `<Formik>` context (throws clear error if not)
+- Exported from `@thinknimble/tn-forms/react`
+- Tests verify: basic field wiring, metadata from provider, inline meta override, error display after touch, type safety