formstand 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,264 @@
 # 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
+pushed during the August 6 GitHub Actions outage and GitHub dropped the
+tag event outright, so the Publish workflow never ran and 0.15.1 never
+reached npm. The Publish workflow only fires on tag pushes by design (the
+trusted-publishing trust is bound to that trigger), so the recovery is a
+new version under a new tag. No code changes.
+
+## formstand-cli 0.11.1 — 2026-08-11
+
+Identical to formstand-cli 0.11.0, republished under a fresh tag for the
+same reason as 0.15.2 above: the cli-v0.11.0 tag event was dropped in the
+August 6 outage and the version never reached npm. No code changes.
+
+## 0.15.1 — 2026-08-06
+
+### Fixed
+
+- **Tuple element paths type as their exact element.** `FieldValue` resolved
+  a path like `"pair.0"` into `[string, number]` through the generic array
+  arm, so the value typed as `string | number` instead of `string`. The
+  bundled field components hid this by asserting their own value type; the
+  raw hooks exposed it, and a CLI module tuple section over a mixed tuple
+  did not compile because its per-kind prop builders need the exact element.
+  Tuple index paths now resolve positionally. Types only, no runtime change.
+
+## formstand-cli 0.11.0 — 2026-08-06
+
+### Fixed
+
+- **Four edge-config compile and layout bugs in the container migration**,
+  all one family: a gate that decides imports or exports did not count every
+  shape that renders section chrome.
+  - A module union section at `--columns 2|3` rendered its vertical `Stack`
+    shell while importing for the grid it no longer renders, a TS2304 in
+    mantine and mui output. Imports and shell now derive from one visual.
+  - A tuple-only root emitted section chrome (`Typography`/`Title`/`Heading`
+    headings, and at `--columns 2|3` the `Row`/`Col` or `Grid` pair) without
+    importing any of it; the section-import gate now counts tuples.
+  - A module tuple section imported the bound field hook from `hooks.ts`,
+    which never exported it for a tuple-only root; the export gate now
+    mirrors the tuple section's own import rule.
+  - A module nested `<fieldset>` lost its full-row span for the CSS-grid
+    backends (plain, shadcn, chakra), collapsing a nested section into one
+    grid cell; the span now rides the fieldset whenever no cell wrapper
+    exists to carry it.
+
+  The version matrix now generates tuple-only and root-union schemas against
+  every kit's real declarations (`cli/matrix/edgeSchemas.ts`), and the CI
+  suite grew matching regression tests, so the class cannot ship green again.
+
+### Changed
+
+- **`--columns` output is responsive.** `--columns 2` now means "two columns
+  when there is room, one on a phone" in every backend's own dialect: MUI gets
+  an `sx` breakpoint object, chakra a responsive `gridTemplateColumns` style
+  prop, mantine `SimpleGrid cols={{ base: 1, sm: N }}`, and the inline-style
+  backends (plain, antd) a `repeat(auto-fit, minmax(...))` track whose calc
+  caps the column count at N while a 220px floor collapses columns that would
+  squeeze inputs below a usable width. shadcn already collapsed via
+  `md:grid-cols-N`. Fixed grid tracks were why generated multi-column forms
+  were unusable on phones; regenerate to pick the new grids up.
+- **antd sections lay out with `Row`/`Col`** instead of an inline CSS grid:
+  the kit's own 24-column idiom, responsive via `xs`/`sm` props, in both
+  layouts. Nested sections, arrays, unions, and tuples ride spanning or item
+  `Col`s; a union section keeps its vertical shell, since its children are
+  conditional fragments that cannot each be a `Col`. This is also the shape
+  that makes a per-field span a one-prop change later.
+- **mantine sections lay out with `Grid`/`Grid.Col`** instead of
+  `SimpleGrid`: responsive span objects (`span={{ base: 12, sm: 6 }}`), and
+  the container that can express a per-field span at all, which `SimpleGrid`
+  cannot. Same cell rules as antd: leaves ride item Cols, nested content
+  spans, 1-column chrome reads as a `Stack`. The version matrix caught one
+  invented prop on the way in (`Grid` has no `gutter` in v9), which is
+  exactly the drift it exists to catch.
+- **mui sections lay out with `Grid` containers** instead of `sx` CSS grids
+  — the same component the hand-written playground demos use — with the
+  spelling the pinned major actually accepts: `size={{ xs: 12, sm: 6 }}` on
+  v7/v9, legacy `item xs={12} sm={6}` on v5 **and** v6 (v6's size-prop grid
+  is the separate `Grid2` import; the matrix against real v6 declarations is
+  what established that). 1-column chrome keeps the historical Stack and
+  CardContent output.
+
 ## 0.15.0 — 2026-08-04
 
 ### Fixed

package/dist/{createForm-C9hZffCQ.d.cts → createForm-jlzK2lCG.d.cts}

@@ -40,7 +40,7 @@ type FieldPath<T, D extends number = DefaultPathDepth> = FieldPathRec<T, Normali
 type FieldPathRec<T, D extends number> = [D] extends [0] ? never : IsArray<T> extends true ? T extends readonly (infer U)[] ? `${number}` | (IsRecord<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : IsArray<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : never) : never : IsRecord<T> extends true ? {
     [K in keyof T & string]: K | (IsRecord<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : IsArray<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : never);
 }[keyof T & string] : never;
-type StepValue<T, K extends string> = T extends readonly (infer U)[] ? K extends `${number}` ? U : never : T extends object ? K extends keyof T ? T[K] : never : never;
+type StepValue<T, K extends string> = T extends readonly (infer U)[] ? K extends keyof T ? T[K] : K extends `${number}` ? U : never : T extends object ? K extends keyof T ? T[K] : never : never;
 type FieldValue<T, P extends string> = [T] extends [NonNullable<T>] ? P extends `${infer Head}.${infer Tail}` ? FieldValue<StepValue<T, Head>, Tail> : StepValue<T, P> : FieldValue<NonNullable<T>, P> | undefined;
 
 type ValidationMode = "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";

package/dist/{createForm-C9hZffCQ.d.ts → createForm-jlzK2lCG.d.ts}

@@ -40,7 +40,7 @@ type FieldPath<T, D extends number = DefaultPathDepth> = FieldPathRec<T, Normali
 type FieldPathRec<T, D extends number> = [D] extends [0] ? never : IsArray<T> extends true ? T extends readonly (infer U)[] ? `${number}` | (IsRecord<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : IsArray<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : never) : never : IsRecord<T> extends true ? {
     [K in keyof T & string]: K | (IsRecord<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : IsArray<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : never);
 }[keyof T & string] : never;
-type StepValue<T, K extends string> = T extends readonly (infer U)[] ? K extends `${number}` ? U : never : T extends object ? K extends keyof T ? T[K] : never : never;
+type StepValue<T, K extends string> = T extends readonly (infer U)[] ? K extends keyof T ? T[K] : K extends `${number}` ? U : never : T extends object ? K extends keyof T ? T[K] : never : never;
 type FieldValue<T, P extends string> = [T] extends [NonNullable<T>] ? P extends `${infer Head}.${infer Tail}` ? FieldValue<StepValue<T, Head>, Tail> : StepValue<T, P> : FieldValue<NonNullable<T>, P> | undefined;
 
 type ValidationMode = "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";

package/dist/devtools/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { z } from 'zod';
-import { F as Form } from '../createForm-C9hZffCQ.cjs';
+import { F as Form } from '../createForm-jlzK2lCG.cjs';
 import 'zustand/vanilla';
 
 type DevtoolsPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";

package/dist/devtools/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { z } from 'zod';
-import { F as Form } from '../createForm-C9hZffCQ.js';
+import { F as Form } from '../createForm-jlzK2lCG.js';
 import 'zustand/vanilla';
 
 type DevtoolsPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";

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;