formstand 0.9.0 → 0.11.0

package/README.md

@@ -85,10 +85,10 @@ const form = createForm(schema, {
 | `setError(path, errors)` / `setErrors(map)` / `clearErrors(path?)` | the app-owned **server error channel** (`state.serverErrors`) — validation never touches it; `setError` accepts a single string or an array; `clearErrors(path)` clears both channels at the path and its descendants (`clearErrors("")` clears just the root entry; `clearErrors()` clears everything); `setErrors` replaces the whole server channel |
 | `setMode` / `setReValidateMode` | switch modes at runtime |
 | `reset(nextInitial?, options?)` | reset to initial; optional partial overrides (shallow-merged for record roots, replaced wholesale otherwise) and `{ keepErrors, keepTouched, keepSubmitCount }` (no `keepDirty` — dirtiness derives from values vs initial, and reset makes them equal) |
-| `resetField(path)` | reset one field to its initial value, clearing its (and descendants') error/touched state (dirtiness clears by definition — the value now equals initial) |
+| `resetField(path)` | reset one field to its initial value, clearing its (and descendants') error/touched state (dirtiness clears by definition — the value now equals initial); a path with no initial counterpart (an appended array row) keeps its value and only clears field state |
 | `adoptValues(values)` | mid-session rebase: replaces `values` + `initialValues` and clears `errors` and in-flight validation flags (`isValidating`/`isValidatingForm` — the rebase disowns in-flight passes), but **preserves** interaction state (`touched`, `submitCount`, `isSubmitting`, `mode`). Use `reset()` for a full wipe |
 | `updateState(updater)` | atomic multi-field patch; `errors` is derived from `schemaErrors`/`serverErrors`, so patch the channels — the patch type omits `errors` entirely, and a plain-JS `errors` patch is warned about and ignored |
-| `validate()` / `validateField(path)` / `validateFields(paths)` | sync validation; on an async schema they transparently start the async pass instead (`validate`/`validateField` return `{ kind: "pending", promise }`, `validateFields` returns the `Promise<boolean>` itself) |
+| `validate()` / `validateField(path)` / `validateFields(paths)` | sync validation; on an async schema all three transparently start the async pass instead and return `{ kind: "pending", promise }` |
 | `validateAsync()` / `validateFieldAsync(path)` / `validateFieldsAsync(paths)` | async; supports `async .refine` |
 | `submit(onValid, onInvalid?, { force? })` → `Promise<SubmitResult>` | full submit flow; resolves `{ kind: "valid", data }`, `{ kind: "invalid", errors }` (errored fields are also marked touched), `{ kind: "skipped" }` when another submit is in flight, or `{ kind: "error", error }` when `onValid` throws/rejects — submit resolves instead of rejecting, so `handleSubmit` never produces an unhandled rejection from an `onValid` throw |
 | `handleSubmit(onValid, onInvalid?)(event?)` | event handler wrapper that calls `preventDefault` |
@@ -108,7 +108,7 @@ const form = createForm(schema, {
 - `mode: "all"`: validate on every change and blur.
 - `reValidateMode` (default `"onChange"`) kicks in once `submitCount > 0`.
 
-For schemas with `async .refine`, sync `validate()` / `validateField()` / `validateFields()` no longer throw: they detect the async requirement, start the async pass themselves, and hand you the in-flight work (`{ kind: "pending", promise }` from `validate`/`validateField`; the `Promise<boolean>` itself from `validateFields`). If the *field being validated* is itself sync, `validateField` still settles synchronously even when other fields carry async refines — field validation parses just that field's subschema when it can (see below).
+For schemas with `async .refine`, sync `validate()` / `validateField()` / `validateFields()` don't throw: they detect the async requirement, start the async pass themselves, and hand you the in-flight work as `{ kind: "pending", promise }` (never a bare truthy `Promise` — a boolean gate can't silently pass). The requirement is also remembered per scope, so later sync calls skip straight to the async pass instead of re-paying a doomed sync parse per keystroke. If the *field being validated* is itself sync, `validateField` still settles synchronously even when other fields carry async refines — field validation parses just that field's subschema when it can (see below).
 
 ## React hooks
 
@@ -165,12 +165,13 @@ users.insert(i, item);
 users.error;   // array-level error (e.g. min(1))
 ```
 
-`fields` IDs are reconciled against item identity each render, so a row's `id`
-stays glued to its item across reorders, inserts, and removes — including
-mutations made outside this hook (`form.arrayMove`, `setValue`, `restore`, or a
-second `useFieldArray` on the same path). Editing a field keeps its row's `id`
-(the row updates instead of remounting); a genuinely new item gets a fresh `id`.
-IDs reset when the hook's `path` changes.
+`fields` IDs are shared per `(form, path)` — every hook on the same array sees
+the same ids. Array ops (hook-issued or imperative `form.arrayMove` etc.)
+record their exact index mapping and id derivation replays it, so even rows
+with equal values keep the right ids through ops; whole-array writes
+(`setValue`, `restore`) reconcile by item identity with a positional fallback,
+so editing a field keeps its row's `id` (the row updates instead of
+remounting). A genuinely new item gets a fresh `id`.
 
 ### `useFormSelector(form, selector)` / `useFormSelectorShallow(form, selector)`
 
@@ -347,9 +348,12 @@ decided by the **existing container**: arrays take numeric segments as indices,
 plain objects take any segment as a string key — so a `z.record` keyed `"0"`
 reads and writes the record key instead of silently becoming an array. Only
 when the container doesn't exist yet does the segment type pick what's created
-(numeric → array, otherwise object). Two limitations: keys containing `.` are
-not addressable, and array writes beyond index 100 000 are refused (a typo'd
-index must not allocate gigabytes).
+(numeric → array, otherwise object). Three limitations: keys containing `.`
+are not addressable; array writes beyond index 100 000 are refused (a typo'd
+index must not allocate gigabytes); and the typed `FieldPath` union stops at
+9 segments by default — the runtime walks any depth, and `createForm`'s
+type-level `pathDepth` option widens the union per form (a deliberate
+compile-time trade; see the [typed paths guide](https://scrumrot.github.io/formstand/guide/typed-paths)).
 
 ## Subscriptions (non-React)
 
@@ -408,7 +412,7 @@ Note `submit` still proceeds when the schema is valid even if server errors are
 
 ## Field arrays with nested arrays
 
-Both work — `arrayPush("users.0.tags", tag)` mutates the inner array; outer reorders correctly re-key meta for all nested paths. `useFieldArray`'s stable IDs reset when the hook's path changes (so an inner field array inside a reordered outer item gets fresh IDs).
+Both work — `arrayPush("users.0.tags", tag)` mutates the inner array; outer reorders correctly re-key meta for all nested paths. Inner row ids live per `(form, path)` and reconcile by value when the outer index re-seats a different item at the path — pass a `key` from the outer `fields` so each row's whole subtree moves with its item.
 
 ## Optimistic UI