formstand 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,22 +1,290 @@
 # Changelog
 
-## 0.12.0 — 2026-07-29
+## 0.14.0 — 2026-07-31
+
+### Added
+
+- **`formstand/devtools`**: a form-aware debugging panel, `<FormstandDevtools
+  form={form} />`, shipped as a subpath of the existing package so there is
+  nothing extra to install and no version to keep in step. It renders one row
+  per leaf path with the value, error, and touched/dirty/validating flags;
+  surfaces the errors that belong to no field (the root `""` key, array-level
+  messages, server verdicts on paths that hold no value yet); shows the two
+  error channels separately, including whether a server verdict is visible or
+  sitting behind a schema message at the same key; renders `diff()` as a live
+  PATCH preview; and wires `snapshot()`/`restore()` to buttons for time
+  travel. Renders nothing in production builds, on the same `NODE_ENV` gate
+  `createForm`'s `devtools` option uses.
+
+  It complements rather than replaces that option: the Redux DevTools
+  extension gives a cross-store action log but only ever sees the merged error
+  map, which is exactly the distinction this panel exists to show. Dirtiness
+  comes from `getFieldState` so the panel can't disagree with `useIsDirty`,
+  and styling is inline so no host stylesheet can restyle it into lying.
+
+## formstand-cli 0.10.1 — 2026-07-30
+
+### Fixed
+
+- **The template-hole regex is linear again** (CodeQL `js/polynomial-redos`,
+  high). `pathSegmentCount` strips holes like `${index}` before counting dot
+  segments, and its pattern excluded only the closing brace, so an
+  unterminated run such as `"${{${{${{..."` rescanned to the end of the
+  string from every `${` start: 1.8 seconds at 32k repetitions, growing
+  quadratically. Excluding both braces bounds each scan at the next brace
+  and makes the same input flat. A hole is always a plain identifier, so
+  real paths are unaffected and every committed demo regenerates
+  byte-identical. Matters because `formstand-cli/codegen` is the documented
+  browser-safe surface: the playground's Schema builder runs it on pasted
+  input, and anything built on it may accept a schema it did not author. The
+  binary alone was never really exposed, since generating from a hostile
+  schema already executes that module.
+
+## 0.13.0 — 2026-07-29
+
+### Added
+
+- **`useFormValues(form)`** — whole-values subscription in render: returns
+  the form's current values object, typed `z.input<TSchema>` (structural
+  `FormStateApi` forms read `unknown`). Sugar for
+  `useFormSelector(form, (s) => s.values)`, reference-compared — the store
+  replaces the values object immutably, so the hook re-renders exactly when
+  some value changes and never on touched/error/submit churn. The motivating
+  case: form values driving derived rendering (a map re-rendering from live
+  coordinates). The playground's three whole-values subscriptions (Autosave,
+  the MUI checkout's review step, the Schema builder's live preview) now use
+  it, and the MUI adapter's number binding now goes through the exported
+  `useNumberInput` (as `useMuiNumberFieldProps`) — the same shape
+  `formstand-gen --ui mui` emits.
+
+### Fixed
+
+- **Explicit type arguments on a schema-typed form now fail with a readable
+  error.** `useField<Values>(form, "email")` (any explicit generics on a
+  `Form` — the value type infers from the path, so they were always an
+  error) used to resolve onto the schema-less overload and die with a
+  baffling `"... not assignable to type 'undefined'"` brand mismatch. A
+  trap-guard overload now intercepts that shape and blames the path
+  argument with instructions: `Argument of type '"email"' is not assignable
+  to parameter of type '"Remove the explicit type argument: a schema-typed
+  form infers the value type from the path"'`. Same guard on
+  `useFieldArray` (`"... infers the item type from the path"`) and
+  `useVariantField` (`"... infers the variant value from the union path
+  and field"`). Inferred calls, structural-form explicit generics,
+  selector paths, and explicit instantiation expressions
+  (`typeof useField<Schema, "name">`,
+  `typeof useVariantField<Schema, "payment", "cardNumber">`) are all
+  unaffected — the guard's type parameter defaults to an unexported
+  sentinel no inferred call can produce.
+- **`setValue` with the identical value is now a full no-op.** Writing the
+  value already at the path used to rebuild the values object anyway, so
+  `useFormValues` re-rendered and `watchValues`/`onValuesChange` fired on
+  writes that changed nothing — and a two-way sync that echoes values back
+  (each side writing what it just received) recursed until the stack
+  overflowed. `form.setValue` now identity-guards (`Object.is`) the write:
+  the state reference is unchanged, no dirty/error recompute runs, no
+  subscribers fire, and `useField().setValue` skips its revalidation gate
+  too (nothing changed, so the current error state already reflects the
+  value). The no-op is deliberately FULL: a no-op write also no longer
+  releases server errors on the path or clears array-op records — those
+  side effects belonged to an actual value change. One carve-out: writing
+  `undefined` over an ABSENT key is still a real write (it creates the
+  key — `{}` vs `{ nickname: undefined }` differ in key count, which
+  dirtiness and the persisted shape observe). `setValues`, `adoptValues`,
+  and `updateState` replace wholesale by design and are unchanged.
+
+## formstand-cli 0.10.0 — 2026-07-29
+
+### Added
+
+- **Per-field component overrides — `fields` in `formstand.config.ts`,
+  with an `autocomplete` flavor and a generated options prop.** The
+  motivating case (straight from the dogfood project): an ICAO airport
+  field is a plain `z.string()` whose suggestion list is DATA — an airport
+  list, not a zod enum — so the CLI emitted a bare text input and the page
+  hand-swapped it for the kit's autocomplete on every regeneration. Now
+  the config names the field and the component:
+
+  ```ts
+  export default defineConfig({
+    fields: {
+      "icao": { component: "autocomplete", optionsProp: true },
+      "crew.*.role": { component: "autocomplete", optionsProp: true },
+    },
+  });
+  ```
+
+  Paths are exact dot paths against the walked schema, `*` matching one
+  array-index segment. The semantic is **free text with suggestions** (the
+  one autocomplete meaning every kit shares): the field stays a string the
+  user can type freely; strict select-from-list remains the enum/Select
+  path. Overrides apply to **string** fields (`optionsProp: true` is
+  required — there is no other options source; the generated component
+  gains `{camelPath}Options: readonly string[]`, e.g. `"crew.*.role"` →
+  `crewRoleOptions`, collision-suffixed like every derived identifier) and
+  **enum** fields (the select upgrades to a combobox seeded with the enum
+  values baked in; `optionsProp: true` REPLACES them with the prop).
+  Everything else is a loud generation-time ERROR, exit 1, nothing
+  written: an unknown path (with near-miss suggestions), a non-string/enum
+  target, a string without `optionsProp`, a walker-degraded or
+  over-FieldPath-budget field, an override under a row-nested object with
+  `--layout module` (that layout degrades those to a TODO). Per-kit
+  bindings, each proven against the real installed `.d.ts` by the matrix:
+  MUI `Autocomplete` `freeSolo` bound through the INPUT value
+  (`inputValue`/`onInputChange`, so typing and picking both update the
+  form); Mantine `Autocomplete` (natively this semantic — value-shaped
+  `onChange`, `data` accepts readonly arrays); antd `AutoComplete`
+  (value-shaped like its Select, `status` for errors, `id={path}` for the
+  focus-helper fallback — no `name` exists); plain, shadcn, and Chakra ride
+  an `Input` + native `<datalist>` (shadcn's combobox is a copy-paste
+  recipe, not an installable component; Chakra 3's `Combobox` is Ark's
+  collection-API compound component — disproportionate for generated
+  free-text suggestions, so the DOM-shaped datalist is the honest
+  binding). Both layouts thread the options prop root → section → row/field
+  files (nested-array extractions included); composes with `--live` and
+  `--form-prop` (the props join the same props type); an overridden field
+  wins over a custom `--template`'s per-kind renderer (templates own
+  per-KIND rendering; an override opts the field out of its kind). Each
+  override site carries a short generated comment naming the options
+  source. `component: "autocomplete"` is the only flavor this cycle; the
+  config shape is a discriminated union so future flavors (textarea,
+  slider, ...) slot in. The playground's flight-search demo now generates
+  its origin/destination ICAO fields through the override (the suggestion
+  list passed by the page), making the dogfood project's exact page real
+  CLI output.
+- **`--live` — live/no-submit scaffold mode** (config key `live`). For
+  forms nothing ever submits (a map or preview re-rendering from every
+  value change): the submit scaffold — `handleSubmit`, the submit button,
+  `useIsSubmitting` — is omitted entirely; the generated component instead
+  accepts an optional `onValuesChange?: (values) => void` prop wired
+  through `form.watchValues` in a `useEffect` (watchValues has shipped
+  since formstand 0.2 and returns its own unsubscribe, so generated output
+  keeps a low version floor; the emitted comment names `useFormValues` as
+  the post-0.12 render-side one-liner). The root element stays a `<form>`
+  (label association, the form landmark, kit chrome unchanged) with a
+  `preventDefault` `onSubmit` so the browser's implicit Enter-key
+  submission can't navigate the page. The emitted validation mode defaults
+  to `"onChange"` — a live consumer wants validity that tracks the values,
+  not the library-default `"onBlur"` lag (noted in the emitted comment).
+  Kit `Button` imports stay usage-gated: array add/remove buttons keep
+  them, an array-free live form drops them. Works with all six `--ui`
+  kits, custom `--template`s, and both layouts (`--layout module` defaults
+  the singleton's `createForm` mode and rewires the form file; the
+  pre-wired hook API is unchanged).
+- **`--form-prop` — page-owned-form scaffold mode** (config key
+  `formProp`). The generated component's props gain
+  `form: Form<typeof schema>` and it stops creating its own form; the
+  `useForm` scaffold is still emitted, as an exported `use{Name}Form()`
+  hook the page calls — so one instance can feed the generated UI and any
+  other consumer (the dogfood case: a page-level form driving a map AND
+  the form UI). In `--layout module` the component takes the same prop for
+  its shell (submit/subscription) while the field hooks stay pre-wired to
+  the module singleton — the emitted props comment says to pass that
+  exported instance. Composes with `--live`: the component becomes pure
+  rendering and `onValuesChange` subscribes to the passed form.
+- Internal: the per-kit form shells (single-file backends and the module
+  layout) are restructured into shared open/onSubmit/submit-button/close
+  pieces, so the submit and `--live` shapes are composed from one
+  production and cannot drift per kit. Default-flag output is
+  byte-identical.
+- **Playground: the two modes as a living demo** — a new Generated tab
+  (**Gen: live + form prop**) renders a compact flight-search schema
+  generated with `--live --form-prop` (`--ui plain`, single-file,
+  committed untouched and drift-checked via
+  `scripts/generate-cli-demos.mjs` like the other generated demos) next to
+  a hand-written consumer page: the page owns the form via the exported
+  `useFlightSearchForm()` hook and a live values panel renders only what
+  `onValuesChange` delivers — updating per keystroke, the map-driven case
+  in miniature. Smoke-tested in the root suite (mount, type, assert the
+  panel reflects the keystroke; no submit scaffold in the output).
+- **zod `.describe()` / `.meta({ description })` → generated helper text.**
+  The walkers capture a field's description into the IR — zod v4 stores
+  both spellings in ONE registry entry (`z.globalRegistry`, surfaced by the
+  schema's `description` getter; nothing on `def`), so the rule is simply
+  "the last `.describe()`/`.meta()` call wins", and across wrappers
+  (`z.number().describe("x").optional()` vs `.optional().describe("x")`)
+  the outermost entry present wins. Type mode captures the member's leading
+  JSDoc description the same way (and the generated zod schema re-emits it
+  as `.describe()`, outermost, so it round-trips). Emission per kit, both
+  layouts, union variant fields and tuple elements included: mui routes it
+  into `helperText` as `fieldError(field) ?? description` (the error keeps
+  the one slot while present), shadcn a muted
+  `<p className="text-sm text-muted-foreground">` and antd a
+  `Typography.Text type="secondary"` line — each rendered only while the
+  error line is not — chakra a `Field.HelperText` under the same guard,
+  mantine the native `description` prop (its own slot, coexists with
+  `error`), and plain an always-visible `<p className="zf-help">` line
+  (formstand's built-in components own the error slot internally).
+  Booleans are skipped where the control has no slot (MUI's
+  FormControlLabel/Switch, chakra's Switch.Root, antd's bare Checkbox);
+  shadcn/mantine/plain booleans render it. Custom templates receive the
+  description as `ctx.description` (an expression like `ctx.label`; `""`
+  when absent). Description-free schemas emit byte-identical output.
+  Adornments from `.meta` (unit prefixes/suffixes) are deliberately NOT
+  generated — the four kits' adornment APIs are value-shaped and mutually
+  incompatible (InputAdornment / rightSection / InputElement / suffix);
+  helper text covers the units case. Visible in the playground: the
+  flight-search demo's `cruiseAltitude` now carries `.describe("feet MSL")`.
 
 ### Fixed
 
+- **`--layout module`: autocomplete-only schemas now compile for every
+  kit.** The module adapter file's import gates missed
+  `usage.autocomplete`: a schema whose every string/enum field carries the
+  autocomplete override emitted chakra/shadcn adapters using `ChangeEvent`
+  without importing it (their override rides the kits' text adapter), and
+  the antd adapter's `FieldError` used `Typography` without importing it.
+  The single-file backends already gated these correctly; the module gates
+  now mirror them (mui/mantine/plain were already correct — mui's
+  autocomplete types `SyntheticEvent`, mantine's and antd's are
+  value-shaped).
+- **`--layout module --form-prop`: the emitted component now warns in dev
+  when the passed form is not the module singleton.** The module's field
+  hooks are pre-wired to the exported singleton; a different form of the
+  same schema compiled and rendered but silently split state (the shell on
+  the prop, the fields on the singleton). The generated component now
+  compares the prop against the singleton and `console.warn`s outside
+  production (`NODE_ENV` gate, same shape as the library's own dev
+  warnings), naming the instance to pass. Documented as an emphasized
+  contract note in the CLI README's flags section.
+- **Override near-miss suggestions no longer offer paths the validator
+  would reject.** The "did you mean ...?" candidate list for an unknown
+  `fields` path now filters out dot-containing (unaddressable) names,
+  walker-degraded leaves, and paths past the FieldPath depth budget — the
+  same predicates `applyFieldOverrides` errors on, so a suggestion can
+  always actually be used.
+- Internal: `ownerHookName` and `hasStaticDescriptions` are no longer
+  exported from codegen (no external consumer), and `overridablePaths`
+  left the `formstand-cli/codegen` public surface (it is the validator's
+  internal near-miss walk).
+
+## 0.12.0 — 2026-07-29
+
+### Changed
+
 - **`useFieldArray` ops revalidate the array path** — push/remove/insert/
   move/swap now re-run field validation on the array's own path after the
   op, under the exact change-trigger gate `useField.setValue` applies
-  (`shouldValidateOn` over mode/reValidateMode/submitCount/touched). A
-  visible array-level error (`z.array().min(1)` after a failed submit) used
-  to go stale: adding the row didn't clear the message, and removing below
-  `.min` raised nothing until the next submit. The gate means `onSubmit`
-  forms stay silent before the first submit, exactly like typing in a
-  field. `FieldArrayFormApi` gains an OPTIONAL `validateField` member
-  (probed before use) — hand-rolled implementations without it keep
-  working, their ops simply skip revalidation. The IMPERATIVE
-  `form.arrayPush`/`arrayRemove` stay non-revalidating on purpose, matching
-  the `form.setValue` vs `useField.setValue` layering.
+  (`shouldValidateOn` over mode/reValidateMode/submitCount/touched). This
+  fixes a visible array-level error (`z.array().min(1)` after a failed
+  submit) going stale: adding the row didn't clear the message, and
+  removing below `.min` raised nothing until the next submit. Upgraders
+  note: in `onChange` mode (or after the first submit) array ops now
+  trigger a validation pass — including async refines — where 0.11 stayed
+  silent; `onSubmit` forms remain silent before the first submit, exactly
+  like typing in a field. The IMPERATIVE `form.arrayPush`/`arrayRemove`
+  stay non-revalidating on purpose, matching the `form.setValue` vs
+  `useField.setValue` layering.
+
+### Added
+
+- **`FieldArrayFormApi.validateField` (optional)** — the member the hook
+  probes for the revalidation above. A `Form<TSchema>` always provides it;
+  hand-rolled `FieldArrayFormApi` implementations without it keep working,
+  their ops simply skip revalidation (documented in the API reference's
+  implementing-these-interfaces notes).
+
+### Fixed
 - **`focusFirstError` / `focusField`: a hidden name-carrier no longer
   suppresses the `[id=path]` fallback.** Composite widgets like
   react-select render a hidden `<input name={path}>` for form posting next