formstand 0.15.2 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,180 @@
 # Changelog
 
+## 0.16.0 — 2026-09-16
+
+### Added
+
+- **`useFields`: composite fields.** One control backed by several schema
+  paths (a coordinate pair behind a DMS input, a range, a date span)
+  binds them in one call: `useFields(form, ["latitude", "longitude"])`
+  returns the position-typed tuple of full field bindings plus the
+  combined view — `error` merged in path order and deduped (a
+  cross-field `superRefine` stamping both paths reads once),
+  `firstError`, any-of-them `touched`/`dirty`/`isValidating`, and one
+  `onBlur` covering every path. The paths tuple must be render-stable;
+  React itself throws its hooks-count error otherwise, at the exact
+  render that broke the contract.
+- **`field.firstError`.** The first error message or `undefined`, derived
+  on `UseFieldReturn` — the display shorthand every consumer (and every
+  generated kit adapter) re-derived by hand as `error?.[0]` with an
+  empty-array guard. `{field.firstError}` is now the whole helper line;
+  the full `field.error` array is unchanged beside it. The CLI keeps
+  emitting its own helper for now so generated code stays runnable on
+  older formstand; a future major of the generated adapters can lean on
+  this instead.
+
+### Fixed
+
+- **`useVariantField` accepts row-indexed union paths.** A discriminated
+  union that is an array's row item was unbindable: `UnionValueAt`
+  resolved paths through `keyof` only, so any array-index segment (a
+  template `` `pavements.${number}` `` or a literal `"pavements.0"`)
+  collapsed the variant-key set to `never` and the `field` argument
+  rejected everything. The type machinery now resolves the array element
+  through numeric segments, so a row component binds
+  `useVariantField(form, `` `pavements.${index}` ``, "designator")` fully
+  typed, in both the plain and the `createFormHooks`-bound flavors.
+  Runtime behavior was always correct; only the types refused. Found by
+  the airfield-maps trial, whose generated TODO pointed at exactly this
+  call.
+
+## formstand-cli 0.15.0 — 2026-09-16
+
+### Changed
+
+- **`--form-prop` is single-file only.** With `--layout module` the
+  fields are pre-wired to the module's own singleton, so the `form`
+  prop was decorative when it told the truth and silently split state
+  when it lied (the dev-mode guard existed to catch the lie). The CLI
+  now rejects the combination with the fix in the message: the page
+  already owns the module's form by importing the exported instance and
+  driving it directly. The wizard stops asking the question under the
+  module layout, and the playground's command builder disables the
+  checkbox. The programmatic `emitModuleForm` surface keeps the option
+  for callers who accept the singleton contract knowingly.
+
+### Fixed
+
+- **The array-row union TODO gives honest advice.** The single-file
+  spelling claimed the union was "not supported"; the module spelling
+  recommended a `useVariantField` call that did not typecheck before the
+  library fix above. Both now describe the working binding and name the
+  formstand 0.16+ floor for row-indexed union paths.
+
+## formstand-cli 0.14.0 — 2026-09-10
+
+### Added
+
+- **`component: "textarea"` in the config `fields` block.** The second
+  override flavor: a multi-line control for string fields, the binding
+  unchanged. Each kit renders its own control (mui `TextField multiline`,
+  mantine/chakra/shadcn `Textarea`, antd `Input.TextArea`, plain a native
+  `<textarea>`), and it composes with `span` in one entry, so a
+  `span: "full"` cover letter can finally look like one. `optionsProp`
+  and enum targets are rejected loudly.
+- **JSON Schema defaults and string formats reach the generated
+  validator.** A document `default` now emits `.default(value)` in the
+  generated zod schema beside the `initialValues` seed it already fed,
+  and `format: email`/`uri`/`uuid` emits `z.email()`/`z.url()`/
+  `z.uuid()` while the control stays a text field. The emitted schema is
+  the runtime source of truth, so it no longer drops contracts the
+  source document carried. Note zod's `.default()` makes the input
+  optional by design.
+
+### Fixed
+
+- **An optional union starts empty and its select can clear it.** An
+  optional/nullable discriminated union was seeded with its first
+  variant, so an untouched form submitted a variant the user never
+  chose, and the discriminant select offered no way back. The union now
+  starts `undefined`/`null`, and its select reads the discriminant but
+  writes the whole union: the empty choice clears it, a tag starts that
+  variant blank. mui's select gains an explicit None item; shadcn's
+  Radix select cannot hold an empty item, so there the fixed seed alone
+  closes the phantom-submit bug. Required unions are unchanged.
+- **Array add buttons read as the action they perform.** "Add
+  references" becomes "Add reference": a conservative singularizer on
+  the label's last word, with irregulars passing through unchanged.
+- **A union variant with one field no longer wraps it in a fragment.**
+
+## formstand-cli 0.13.0 — 2026-09-03
+
+### Added
+
+- **JSON Schema and OpenAPI inputs.** A `.json` input file is read as a
+  bare JSON Schema (2020-12) or an OpenAPI 3.x document: a third
+  front-end into the same IR, following type mode's path, so the CLI
+  generates the zod schema beside the component (`--schema-out` places
+  it; `--layout module` makes it the module's `schema.ts`). The new
+  `--schema` flag selects inside the document: a component schema name,
+  or a full `#/...` JSON pointer that can reach an operation's request
+  body. What translates: `properties`/`required`, `enum`/`const`,
+  `oneOf` string consts, discriminated `oneOf` into `useVariantField`
+  unions, `allOf` object merging, `$ref` chains, `prefixItems` tuples,
+  `format: date`/`date-time` as date fields, primitive `default`s into
+  `initialValues`, `description` as helper text, `title` as the label,
+  and every nullable dialect (3.1 type arrays, 3.0 `nullable: true`,
+  `oneOf` with a null branch). Everything else degrades to the loud TODO
+  fallback; Swagger 2.0 and YAML are refused with conversion hints. The
+  wizard understands `.json` inputs too, asking `--schema` in place of
+  the zod-or-type question.
+
+### Fixed
+
+- **A PascalCase schema export no longer collides with its module type
+  alias.** `export const MySchema` derives the form name MyForm, whose
+  schema type alias was also named MySchema, so the module barrel
+  exported two different MySchemas (the value from `schema.ts`, the type
+  from `types.ts`) and the generated `index.ts` failed to compile with
+  TS2308. The alias now yields the colliding name to the user's value
+  and becomes `MySchemaType`, both in `types.ts` and in the
+  `--form-prop` component that consumes it.
+
+## formstand-cli 0.12.0 — 2026-08-18
+
+### Added
+
+- **`--wizard`: the flag questions asked one at a time.** Which file, zod
+  export or TS type, which kit, layout, section chrome, columns, name, and
+  where to write — Enter accepts the default on every question, invalid
+  answers re-ask, and an existing output target offers `--force` on the
+  spot. The interview ends by printing the composed `formstand-gen`
+  command before running it, so the run is reproducible without the wizard
+  from then on. Strictly opt-in (never a TTY sniff, and the flag runs
+  alone), prompts on stderr so stdout output stays pipeable, answers
+  pipeable on stdin, and zero new dependencies: numbered readline lists,
+  not a prompts library.
+- **Per-field layout placement: `span` in the config `fields` block.** With
+  `--columns 2|3`, `"employment.notes": { span: "full" }` gives a field the
+  whole row and `{ span: 2 }` two of three columns; it composes with an
+  autocomplete override in the same entry. Each backend emits the span in
+  the dialect its section grids already use (mui `Grid` size objects, with
+  the legacy `item xs/sm` spelling on mui@5/6; mantine `Grid.Col` span
+  objects; antd `Col` `xs`/`sm`; shadcn `md:col-span-N`; chakra a `Box`
+  with responsive `gridColumn`), so every spelling still collapses to one
+  column on a phone. Plain is the one exception, for partial spans only:
+  inline styles cannot carry a media query, so a numeric span widens to the
+  full row with a comment saying so at the site. A span with no grid to act
+  on (a root-level field, array rows, a container, a 1-column form, or a
+  module-layout field below a section's direct children) is a loud
+  generation-time error, never a silent no-op.
+
+### Fixed
+
+- **Generated bodies indent under their real container.** Panel and
+  collapsible chrome nests the body's container deeper than the section tag
+  (Card > CardContent > Grid), but cells were emitted shallower than the
+  container holding them and array row stacks sat beside their wrapper
+  cells instead of inside them. Both layouts now shift bodies to the
+  chrome's true depth, so generated files survive a host Prettier pass
+  without reflowing. Cosmetic only; the demos regenerate with a
+  whitespace-only diff.
+- **A union riding a grid cell keeps its vertical rhythm.** Inside an
+  object section at `--columns 2|3`, a discriminated union's controls are
+  bare siblings in one full-row cell and had lost the spacing the 1-column
+  chrome provides; mui and mantine now wrap them in the kit's Stack. antd
+  needs no wrapper, since each of its controls is already a vertical Flex.
+
 ## 0.15.2 — 2026-08-11
 
 Identical to 0.15.1, republished under a fresh tag. The v0.15.1 tag was

package/dist/index.cjs

@@ -1390,6 +1390,8 @@ function useField(form, pathArg, options) {
       initialValue: slice.initialValue,
       emptyValue,
       error: slice.error,
+      // `?.[0]` covers both the undefined channel and an empty array.
+      firstError: slice.error?.[0],
       touched: slice.touched,
       dirty: slice.dirty,
       isValidating: slice.isValidating,
@@ -1669,6 +1671,30 @@ function useFormValues(form) {
   return react$1.useStore(form.store, (state) => state.values);
 }
 
+// src/react/useFields.ts
+function useFields(form, paths) {
+  const fields = paths.map(
+    (path) => (
+      // eslint-disable-next-line react-hooks/rules-of-hooks -- a fixed hook count by the stable-arity contract above; each element must be a REAL UseFieldReturn so it spreads into the prop builders
+      useField(form, path)
+    )
+  );
+  const merged = [...new Set(fields.flatMap((field) => field.error ?? []))];
+  return {
+    fields,
+    error: merged.length > 0 ? merged : void 0,
+    firstError: merged[0],
+    touched: fields.some((field) => field.touched),
+    dirty: fields.some((field) => field.dirty),
+    isValidating: fields.some((field) => field.isValidating),
+    onBlur: () => {
+      fields.forEach((field) => {
+        field.onBlur();
+      });
+    }
+  };
+}
+
 // src/react/inputProps.ts
 var hasFieldError = (error) => error !== void 0 && error.length > 0;
 var ariaInvalid = (field) => hasFieldError(field.error) ? true : void 0;
@@ -2087,6 +2113,7 @@ exports.shouldValidateOn = shouldValidateOn;
 exports.textInputProps = textInputProps;
 exports.useField = useField;
 exports.useFieldArray = useFieldArray;
+exports.useFields = useFields;
 exports.useForm = useForm;
 exports.useFormError = useFormError;
 exports.useFormSelector = useFormSelector;