formstand 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,299 @@
 # Changelog
 
+## 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). 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
+  to a focusable control carrying `id={path}`; the hidden input claimed the
+  path as "named" even though it can never take focus, so the id element
+  was never tried. Whether a path counts as name-matched is now judged
+  against focus-CANDIDATE controls only.
+- **`focusFirstError` / `focusField` harden against control characters in
+  paths** — the CSS-string escaping behind the `[id=path]` fallback now
+  hex-escapes control characters (`\n`, DEL, ...), so a hostile or
+  accidental newline in a path builds a valid selector that matches
+  nothing instead of making `querySelectorAll` throw.
+
+## formstand-cli 0.9.1 — 2026-07-29
+
+### Fixed
+
+- **Hoisted `${var}NumberProps` consts respect the identifier registry.** A
+  schema field literally named like the derived const of a kit number
+  binding (`price` + `priceNumberProps`) generated a duplicate `const`
+  declaration — the file failed tsc — in single-file union bodies AND
+  module-layout rows/tuple/union sections. Number bindings now reserve BOTH
+  their own var and the derived `${var}NumberProps` name through the
+  identifier-suffix machinery at allocation time, so the colliding field
+  suffixes (`priceNumberProps2`) instead.
+- **Array-level error lines announce in every kit**: the mui / chakra /
+  mantine array errors (both the single-file emitters and the module
+  layout's list shells) now carry `role="alert"`, matching plain, shadcn,
+  and antd — a `z.array().min()` message is announced to assistive tech,
+  not just painted.
+- **Version-floor wording updated for the shipped release**: the emitted
+  antd comment, its non-emitted twin, the inline `useNumberText` note, and
+  the README now say "formstand >= 0.11.0" for the focus-helper `[id=path]`
+  fallback (previously "formstand > 0.10.0", written before 0.11.0 had a
+  number).
+
+### Changed
+
+- **HELP's `--ui` line is built from structure, not regex surgery**: the
+  flag spelling derives from the new `UI_KITS` list plus `MUI_VERSIONS`
+  (exported from `uiTarget.ts`, which `UI_CHOICES` also derives from), so a
+  new kit or MUI major updates every listing at once. The rendered text is
+  unchanged.
+- Internal consolidation: the string/date adapter names at the module
+  layout's import sites and the single-file Bound* component bodies now
+  route through `kitScalarBinding` — one production feeds both the import
+  and JSX spellings per kit — and `ModuleUi` derives from the exported
+  `KitUi` union instead of restating the kit list.
+
 ## 0.11.0 — 2026-07-29
 
 ### Added

package/README.md

@@ -181,6 +181,10 @@ Selector-style subscription. Use `useFormSelectorShallow` for selectors that ret
 > ships its own (deprecated) `useFormState` and auto-imports regularly grabbed
 > the wrong one. The old names were removed in 0.4.0.
 
+### `useFormValues(form)`
+
+The whole values object, reactively — sugar for `useFormSelector(form, (s) => s.values)`, reference-compared so it re-renders exactly when some value changes (never on touched/error churn); the render-side sibling of `form.watchValues`.
+
 ### `useFormError(form)`
 
 Shortcut for the root-level error (errors at the `""` key from a schema-level `.refine`).

package/dist/index.cjs

@@ -181,6 +181,14 @@ var slotAtPath = (obj, path) => {
   );
   return walked.ok ? { exists: true, value: walked.current } : { exists: false };
 };
+var hasOwnSlot = (obj, path) => parsePath(path).reduce(
+  (acc, segment) => {
+    const container = acc.current;
+    const owns = Array.isArray(container) ? typeof segment === "number" && segment < container.length : isPlainRecord(container) && Object.hasOwn(container, String(segment));
+    return !acc.ok || !owns ? { ok: false, current: void 0 } : { ok: true, current: readSegment(container, segment) };
+  },
+  { ok: true, current: obj }
+).ok;
 var writeIntoArray = (arr, index, rest, value) => {
   const length = Math.max(arr.length, index + 1);
   return Array.from(
@@ -883,6 +891,10 @@ var createForm = (schema, options) => {
       });
     },
     setValue: (path, value) => {
+      const currentValues = store.getState().values;
+      if (Object.is(getAtPath(currentValues, path), value) && (value !== void 0 || hasOwnSlot(currentValues, path))) {
+        return;
+      }
       clearArrayOpsUnder(store, path);
       store.setState((state) => ({
         ...state,
@@ -1280,8 +1292,10 @@ function useField(form, pathArg, options) {
   }, [form, path, debounceMs]);
   const setValue = react.useCallback(
     (value) => {
+      const before = form.store.getState();
       form.setValue(path, value);
       const state = form.store.getState();
+      if (state === before) return;
       if (shouldValidateOn(
         "change",
         state.mode,
@@ -1475,25 +1489,52 @@ function useFieldArray(form, pathArg) {
   const items = slice.items;
   const error = slice.error;
   const ids = deriveIds(form.store, path, items).ids;
+  const revalidate = react.useCallback(() => {
+    const state = form.store.getState();
+    if (shouldValidateOn(
+      "change",
+      state.mode,
+      state.reValidateMode,
+      state.submitCount > 0,
+      state.touched[path] ?? false
+    )) {
+      form.validateField?.(path);
+    }
+  }, [form, path]);
   const push = react.useCallback(
-    (item) => form.arrayPush(path, item),
-    [form, path]
+    (item) => {
+      form.arrayPush(path, item);
+      revalidate();
+    },
+    [form, path, revalidate]
   );
   const remove = react.useCallback(
-    (index) => form.arrayRemove(path, index),
-    [form, path]
+    (index) => {
+      form.arrayRemove(path, index);
+      revalidate();
+    },
+    [form, path, revalidate]
   );
   const insert = react.useCallback(
-    (index, item) => form.arrayInsert(path, index, item),
-    [form, path]
+    (index, item) => {
+      form.arrayInsert(path, index, item);
+      revalidate();
+    },
+    [form, path, revalidate]
   );
   const move = react.useCallback(
-    (from, to) => form.arrayMove(path, from, to),
-    [form, path]
+    (from, to) => {
+      form.arrayMove(path, from, to);
+      revalidate();
+    },
+    [form, path, revalidate]
   );
   const swap = react.useCallback(
-    (a, b) => form.arraySwap(path, a, b),
-    [form, path]
+    (a, b) => {
+      form.arraySwap(path, a, b);
+      revalidate();
+    },
+    [form, path, revalidate]
   );
   const fields = react.useMemo(
     () => items.map((value, index) => ({
@@ -1582,6 +1623,9 @@ var createFormHooks = (form, name) => {
     [`use${prefix}SubmitCount`]: useBoundSubmitCount
   };
 };
+function useFormValues(form) {
+  return react$1.useStore(form.store, (state) => state.values);
+}
 
 // src/react/inputProps.ts
 var hasFieldError = (error) => error !== void 0 && error.length > 0;
@@ -1934,7 +1978,10 @@ var nameMatchesAny = (el, paths) => {
   const name = el.getAttribute("name");
   return name !== null && paths.some((p) => isPathOrChild(name, p));
 };
-var cssQuoted = (value) => `"${value.replace(/[\\"]/g, (ch) => `\\${ch}`)}"`;
+var cssQuoted = (value) => `"${value.replace(/[\\"]/g, (ch) => `\\${ch}`).replace(
+  /[\x00-\x1f\x7f]/g,
+  (ch) => `\\${ch.codePointAt(0).toString(16)} `
+)}"`;
 var idMatches = (scope, path) => path === "" ? [] : [...scope.querySelectorAll(`[id=${cssQuoted(path)}]`)];
 var inDomOrder = (els) => [...els].sort(
   (a, b) => a === b ? 0 : (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0 ? -1 : 1
@@ -1942,8 +1989,9 @@ var inDomOrder = (els) => [...els].sort(
 var pathCandidates = (scope, paths) => {
   const controls = namedControls(scope);
   const named = controls.filter((el) => nameMatchesAny(el, paths));
+  const focusableControls = controls.filter(isFocusCandidate);
   const unnamedPaths = paths.filter(
-    (p) => !controls.some((el) => nameMatchesAny(el, [p]))
+    (p) => !focusableControls.some((el) => nameMatchesAny(el, [p]))
   );
   const byId = unnamedPaths.flatMap((p) => idMatches(scope, p));
   return inDomOrder([.../* @__PURE__ */ new Set([...named, ...byId])]);
@@ -2001,6 +2049,7 @@ exports.useForm = useForm;
 exports.useFormError = useFormError;
 exports.useFormSelector = useFormSelector;
 exports.useFormSelectorShallow = useFormSelectorShallow;
+exports.useFormValues = useFormValues;
 exports.useIsDirty = useIsDirty;
 exports.useIsSubmitting = useIsSubmitting;
 exports.useIsValid = useIsValid;