formstand 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.11.0 — 2026-07-29
+
+### Added
+
+- **`useNumberInput` is exported** (along with its `NumberInputBinding`
+  return type) — the text-preserving number binding behind `NumberField`.
+  It was implemented and tested (via `NumberField`) all along, just never
+  exported: local raw text while editing (partial entries like `-`, `1.`,
+  `85000.` stay visible), keystrokes that parse pushed to the form via the
+  shared `parseNumberText` rules, blur snapping the display to the
+  canonical value, and an external form-value change while editing
+  resetting the local text. Spread it onto an `<input type="text">` for
+  custom number inputs and UI-kit adapters — a naive controlled
+  `value={String(n)}` binding eats the `.` of `85000.50` and the `-` of
+  `-5` as they are typed.
+
+### Fixed
+
+- **`focusFirstError` / `focusField` gain an `[id=path]` fallback** for
+  paths that match NO named control: composite widgets that render no
+  `name` anywhere — Ant Design's `Select`, notably, which has no
+  form-posting input — were unreachable by the name walk even though they
+  forward `id={path}` to their real focusable control. When a path has no
+  name-matched control, the helpers now try the element whose `id` is
+  exactly that path (EXACT match only — descendant semantics stay with the
+  name walk, since an id names one element), with the same focusability
+  filter, post-focus verification, and DOM-order merging as name matches.
+  Paths with any named control never consult ids, so existing behavior is
+  unchanged wherever a `name` exists.
+
 ## 0.10.0 — 2026-07-28
 
 ### Breaking
@@ -137,6 +167,241 @@
 - `FieldPathArg` is now actually used by the `useField` / `useFieldArray`
   overloads it describes (it was exported dead).
 
+## formstand-cli 0.9.0 — 2026-07-29
+
+### Added
+
+- **Version-aware `--ui`: `mui@5` … `mui@9`** — `--ui mui` can now pin an
+  `@mui/material` major: `mui@5`, `mui@6`, `mui@7`, `mui@9` (bare `mui`
+  keeps meaning the latest supported major, 9, and its output is
+  byte-identical to before). The config file's `ui` key accepts the same
+  spellings. Scope: only React-19-capable majors — formstand peers
+  `react: ^19`, so MUI 4 and older can never install alongside it — and MUI
+  skipped major 8 entirely (7.x jumps to 9 on the registry), so `mui@8`
+  and `mui@4` fail with explanations, as do `plain@N`/`shadcn@N` (those
+  kits take no version). Internally the flag/config value parses to a
+  structured `UiTarget` (`{ kit: "mui", version }` | `{ kit: "plain" }` |
+  `{ kit: "shadcn" }`, exported with `parseUiTarget` / `MUI_VERSIONS` from
+  `formstand-cli/codegen`), and ONE mui emitter serves every major through
+  a small per-version config. The only prop-surface delta across the
+  emitted component set (verified empirically against each major's .d.ts)
+  is TextField's slot-props API: `mui@5` emits the legacy
+  `InputProps: { inputMode }` / `InputLabelProps: { shrink: true }`, v6+
+  emit `slotProps.{input,inputLabel}` (v9 removed the legacy spelling;
+  v6–7 accept both and get the modern one). Custom `--template` modules
+  compose with a versioned `--ui` exactly as they did with bare `mui`
+  (a template still overrides the ui entirely, `--layout single` only).
+- **`cli/matrix/`: the UI-kit version-matrix typecheck harness** — an isolated
+  workspace (own `package.json` + lockfile; not part of the root or cli
+  installs) with every supported `@mui/material` major installed side by
+  side under npm aliases (`mui5` … `mui9`). `npm run matrix` (from `cli/`)
+  generates a kitchen-sink form plus the nested-array stress form with
+  `--ui mui@N` — both layouts, every section/column variant — and
+  typechecks the output against each major's real type declarations
+  (`@mui/material` path-mapped onto the alias, `formstand` onto the
+  library source). A per-version literal-attribute probe restates the
+  adapter's TextField props style outside a JSX spread (spreads bypass
+  TypeScript's excess-property checks), so a wrong per-version config
+  fails the matrix instead of compiling silently. Run it before releasing
+  any UI-kit backend change; it is deliberately not part of `npm test`.
+  (The chakra, mantine, and antd entries below each extend the harness
+  with their kit's alias and job — it ends this cycle proving seven
+  targets: four mui majors, chakra 3, mantine 9, antd 6.)
+- **First-class `--ui chakra`: a Chakra UI v3 backend** — both layouts
+  (single-file and `--layout module`), the full field-kind surface the mui
+  backend covers (strings/numbers/dates/enums/booleans, nested objects,
+  arrays with add/remove and recursive nested-row extraction, tuples,
+  discriminated unions, TODO degradations), and every `--sections` /
+  `--columns` variant. Emits the v3 compound-component API (verified
+  against the installed 3.36 declarations, not v2's): `Field.Root` (with
+  `invalid`) / `Field.Label` / `Field.ErrorText` for labels and errors,
+  `Input` for text/number/date (native bindings — `inputMode="decimal"`,
+  `type="date"`), `NativeSelect.Root` + `NativeSelect.Field` for enums (a
+  real `<select>`, preferred over the Ark collection `Select` so the
+  adapter speaks DOM change events), and `Switch.Root` /
+  `Switch.HiddenInput` / `Switch.Control` / `Switch.Thumb` /
+  `Switch.Label` for booleans (`checked` + `onCheckedChange` details
+  callback, spread on the root where the state lives). Sections render
+  `Stack`/`Heading` (flat), `Card.Root`/`Card.Body` (panel), or one
+  `Accordion.Root` (`collapsible defaultValue={["section"]}`) per section
+  (collapsible); columns use the same CSS-grid shape as the other kits via
+  chakra style props. The generated file assumes the host app mounts
+  `ChakraProvider` (same policy as the mui backend and its theme). The
+  module layout gains a shared `adapter.ts` (`chakraTextInputProps` /
+  `useChakraNumberInputProps` / `chakraDateInputProps` /
+  `chakraSelectProps` / `chakraSwitchProps` + `fieldError`). chakra takes no version suffix —
+  v3 is the only supported major (v2 and older lack the compound API and
+  predate formstand's React 19 peer) — with `chakra@3` accepted as the
+  explicit spelling and `chakra@1`/`chakra@2` failing with the scope
+  rationale like `mui@0`–`mui@4`. The config file's `ui` key accepts the
+  same spellings, and the matrix harness gained a `chakra3` alias
+  (`npm:@chakra-ui/react@^3`) plus a chakra job — both schemas, both
+  layouts, all section styles, and a literal-attribute probe for the
+  Input/NativeSelect/Switch prop surfaces — so `npm run matrix` now proves
+  five kit targets against their real .d.ts.
+- **First-class `--ui mantine`: a Mantine v9 backend** — both layouts, the
+  full field-kind surface the other kit backends cover (strings/numbers/
+  dates/enums/booleans, nested objects, arrays with add/remove and
+  recursive nested-row extraction, tuples, discriminated unions, TODO
+  degradations), and every `--sections` / `--columns` variant. Mantine
+  field components carry their own `label` + `error` props, so there is no
+  Field wrapper: `TextInput` binds text/number/date natively
+  (`inputMode="decimal"`, `type="date"`; Mantine's `NumberInput` widget is
+  deliberately NOT used — its `onChange` takes `(value: number | string)`,
+  not a DOM event, so it can't share formstand's input-shaped adapters),
+  `NativeSelect` binds enums as a real `<select>` with `<option>` children
+  (same native-first choice as the chakra backend), and `Switch` binds
+  booleans through plain DOM `checked`/`onChange` (a `ChangeEvent`, unlike
+  chakra's details callback). Error text rides inside the adapter builders
+  (`error: fieldError(field)`), so leaves are one-liners like the mui
+  backend's. Sections render `Stack`/`Title` (flat), `Card withBorder` +
+  `SimpleGrid` (panel), or `Accordion`/`Accordion.Item`/`Control`/`Panel`
+  (collapsible, `defaultValue="section"` + `variant="contained"`); columns
+  use `SimpleGrid cols={N}`. The generated file assumes the host app
+  mounts `MantineProvider` (same policy as the mui/chakra providers). The
+  module layout gains a shared `adapter.ts` (`mantineTextInputProps` /
+  `useMantineNumberInputProps` / `mantineDateInputProps` /
+  `mantineSelectProps` / `mantineSwitchProps` + `fieldError`). mantine
+  takes no version suffix — v9 (the current major) is the only supported
+  target, with `mantine@9` accepted as the explicit spelling. The scope is
+  empirical: 9.x peers `react ^19.2` while 7.17+/8.x peer `^18 || ^19`
+  (7.0 was ^18-only, ≤6 predate the v7 emotion→CSS-modules rewrite), and
+  the emitted component surface typechecks IDENTICALLY against 7.17/8.3/9.5
+  except the `bdrs` style prop (absent in 7) — so `mantine@0`–`6` fail
+  with the React-19/styling-rewrite rationale and `mantine@7`/`@8` fail
+  with a precise verified-against-v9-only message instead of a false
+  incompatibility claim. The config file's `ui` key accepts the same
+  spellings, and the matrix harness gained a `mantine9` alias
+  (`npm:@mantine/core@^9.5`, plus its `@mantine/hooks` peer) and a
+  mantine job — both schemas, both layouts, all section styles, and a
+  literal-attribute probe for the TextInput/NativeSelect/Switch spread
+  surfaces — so `npm run matrix` now proves six kit targets against their
+  real .d.ts.
+- **First-class `--ui antd`: an Ant Design v6 backend** — both layouts, the
+  full field-kind surface the other kit backends cover (strings/numbers/
+  dates/enums/booleans, nested objects, arrays with add/remove and
+  recursive nested-row extraction, tuples, discriminated unions, TODO
+  degradations), and every `--sections` / `--columns` variant. The one
+  hard rule: antd's own `Form`/`Form.Item` (name-based bindings, its own
+  state store) is NEVER emitted — formstand owns the form state, so the
+  generated code binds antd's input components as plain controlled
+  components. The bindings, decided empirically against the installed
+  6.5 declarations: `Input` binds text/number/date natively (it extends
+  the DOM input props — `inputMode="decimal"`, `type="date"`; antd's
+  `InputNumber` is rejected on evidence, its `onChange` is
+  `(value: number | null)`, not an event, and the dayjs-value-based
+  `DatePicker` is not used — the CLI pulls no date library); enums bind
+  antd's `Select`, the backend's ONE value-shaped adapter — antd has no
+  native-`<select>` component anywhere, so `onChange` receives the
+  selected value directly, `value ?? null` keeps the placeholder visible,
+  and there is no `name` (antd's Select renders no form-posting input);
+  booleans bind `Checkbox` (its `onChange` is antd's DOM-ish
+  `CheckboxChangeEvent` with `e.target.checked`, and it has a real
+  `onBlur`) — NOT `Switch`, which has no `onBlur` prop at all and a
+  value-shaped `(checked, event)` callback (both rejections verified as
+  failing compiles against the real .d.ts). With no `Form.Item` there is
+  no built-in error slot: every non-boolean control paints
+  `status="error"` (`fieldStatus`) and renders an explicit
+  `Typography.Text type="danger" role="alert"` error line, with a plain
+  `<label htmlFor>`/`id` pair. Sections render `Flex`/`Typography.Title`
+  (flat), `Card variant="outlined"` (panel), or `Collapse` via the items
+  API (collapsible — children-panels are deprecated in antd 5+); columns
+  use the shared inline-style CSS grid. No provider is required
+  (`ConfigProvider` is optional theming). The module layout gains a shared
+  `adapter.tsx` (JSX for its `FieldError` line, like shadcn's):
+  `antdTextInputProps` / `useAntdNumberInputProps` /
+  `antdDateInputProps` / `antdSelectProps` / `antdCheckboxProps` +
+  `fieldError` / `fieldStatus` / `FieldError`. antd takes no version suffix — v6 (the current major) is
+  the only supported target, with `antd@6` accepted as the explicit
+  spelling. The scope is empirical: antd 6.x peers `react >=18` (React 19
+  natively in range), while antd 5 nominally peers `react >=16.9` but
+  needs the `@ant-design/v5-patch-for-react-19` import in the HOST app on
+  React 19 — so `antd@5` fails with a precise
+  verified-against-v6-only message (naming the patch, no false
+  incompatibility claim) and `antd@0`–`4` fail with the missing-surface
+  rationale (no `Flex`, no Collapse items API, no `status` props; 4 and
+  older predate the v5 CSS-in-JS rewrite). The config file's `ui` key
+  accepts the same spellings, and the matrix harness gained an `antd6`
+  alias (`npm:antd@^6.5`) and an antd job — both schemas, both layouts,
+  all section styles, and a literal-attribute probe for the
+  Input/Select/Checkbox spread surfaces, restating the value-shaped
+  Select `onChange` with its explicit parameter type — so
+  `npm run matrix` now proves seven kit targets against their real .d.ts.
+- **Playground: the new kit backends as living demos** — three new
+  Generated tabs (**Gen: Chakra UI**, **Gen: Mantine**, **Gen: Ant
+  Design**) render the SAME Onboarding schema the mui module tab uses,
+  generated single-file with `--ui chakra` / `--ui mantine` / `--ui antd`
+  and the same `--sections panel --columns 2` chrome — a direct kit
+  comparison across the four tabs, with one deliberate second axis: the
+  mui tab is `--layout module` (the module-layout showcase) while these
+  three are single-file. Committed
+  untouched and drift-checked by CI like the other generated demos
+  (`scripts/generate-cli-demos.mjs`), rendered behind scoped provider
+  bridges that follow the playground's light/dark switch (ChakraProvider +
+  a mode class, MantineProvider `forceColorScheme`, antd `ConfigProvider`
+  algorithm — antd needs no provider to function), and smoke-tested in
+  the root suite (mount, label association, array add/remove per kit).
+
+### Fixed
+
+- **Kit number adapters no longer corrupt typed numbers.** The mui, chakra,
+  mantine, and antd backends bound numbers as a controlled text input
+  (`inputMode="decimal"`) whose onChange immediately reparsed and
+  re-rendered the canonical string — so typing `85000.50` yielded
+  `8500050` (the `.` eaten as `85000.` reparsed to `85000`), `-5` yielded
+  `5`, and `0.050` yielded `50` (jsdom-verified). All four now emit an
+  inline `useNumberText` hook replicating formstand's own `useNumberInput`
+  semantics exactly (local raw text while editing, valid keystrokes pushed,
+  partial entries kept, blur snap, external-change reset) — emitted inline
+  rather than imported so generated output keeps its formstand >= 0.3.0
+  floor — and their number adapters became use-prefixed HOOKS
+  (`useMuiNumberFieldProps` / `useChakraNumberInputProps` /
+  `useMantineNumberInputProps` / `useAntdNumberInputProps`) composing kit
+  chrome over it, in both layouts. Union variant blocks are conditional
+  JSX, so number bindings there hoist
+  `const ${var}NumberProps = use...(${var})` next to the field hooks and
+  spread the const (React's rules of hooks). plain and shadcn were never
+  affected (stateless `type="number"` bindings).
+- **Single-file array sections render the array-level error.** All six
+  single-file backends dropped `useFieldArray`'s `.error`, so a
+  `z.array().min(1, "add at least one contact")` message was invisible on
+  submit; the module layout already rendered it per kit. Each backend now
+  emits the same error line its module-layout list shell uses (plain and
+  shadcn `<p role="alert">`, mui `Typography color="error"`, chakra
+  `Text color="red.500"`, mantine `Text c="red"`, antd
+  `Typography.Text role="alert" type="danger"`), between the rows and the
+  Add button.
+- **Version-matrix hardening.** (1) The stale-install gate now derives its
+  required-alias list from the job list itself and fails loudly naming
+  what's missing — it previously checked only 4 of the 7 aliases, so a
+  missing `mui6`/`mui7`/`mui9` silently typechecked against the repo
+  root's @mui/material copy. (2) Every kit gained a module-layout PANEL
+  job (`KitchenSinkPanel`, panel@2col): module-panel emitters were
+  previously typechecked nowhere (a deliberate typo in that arm shipped
+  green), so the matrix now genuinely covers all three section styles in
+  both layouts. (3) The matrix compiles under `exactOptionalPropertyTypes`
+  in addition to `strict` — the strictest consumer configuration — after
+  fixing the stale antd probe lines, which restated `status={undefined}`,
+  a shape the adapter no longer emits (it emits `""`, a member of antd's
+  `InputStatus`). (4) The four ~60-line per-kit generator copies collapsed
+  into one parameterized `generateKit` with the jobs as data.
+- **Docs corrections**: the module layout works with all six uis (the
+  README said three) and the adapter split is named (`adapter.ts` for
+  mui/chakra/mantine, `adapter.tsx` for shadcn/antd); the
+  formstand >= 0.3.0 requirement explicitly covers mantine and antd (they
+  import the same surface); and the playground/README wording about the
+  four "CLI output" tabs now acknowledges both axes — the mui tab is
+  `--layout module` (doubling as the module-layout showcase) while the
+  three kit tabs are single-file, so `--ui` is not the only variable.
+- **antd `fieldStatus` returns `""` — antd's own no-status value — instead
+  of `undefined`** when a field has no error. Spreading
+  `status: "error" | undefined` onto antd's `status?: InputStatus` props
+  fails to compile in host apps built with `exactOptionalPropertyTypes`
+  (which rejects explicit `undefined` for optional properties); `""` sits
+  in antd's `InputStatus` union precisely for "no status". Caught by
+  wiring the playground demo — the examples package compiles with
+  `exactOptionalPropertyTypes` on.
+
 ## formstand-cli 0.8.0 — 2026-07-28
 
 ### Changed

package/dist/index.cjs

@@ -1934,6 +1934,20 @@ 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 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
+);
+var pathCandidates = (scope, paths) => {
+  const controls = namedControls(scope);
+  const named = controls.filter((el) => nameMatchesAny(el, paths));
+  const unnamedPaths = paths.filter(
+    (p) => !controls.some((el) => nameMatchesAny(el, [p]))
+  );
+  const byId = unnamedPaths.flatMap((p) => idMatches(scope, p));
+  return inDomOrder([.../* @__PURE__ */ new Set([...named, ...byId])]);
+};
 var focusFirstError = (errors, root) => {
   const scope = root ?? document;
   const erroredPaths = Object.keys(errors).filter(
@@ -1941,16 +1955,16 @@ var focusFirstError = (errors, root) => {
   );
   const hasRootError = (errors[""]?.length ?? 0) > 0;
   const controls = namedControls(scope);
-  const fieldMatches = controls.filter((el) => nameMatchesAny(el, erroredPaths)).filter(isFocusCandidate);
+  const fieldMatches = pathCandidates(scope, erroredPaths).filter(
+    isFocusCandidate
+  );
   const rootFallbackApplies = hasRootError && (root !== void 0 || document.querySelectorAll("form").length <= 1);
   const candidates = fieldMatches.length > 0 ? fieldMatches : rootFallbackApplies ? controls.filter(isFocusCandidate) : [];
   return focusFirstOf(candidates);
 };
 var focusField = (path, root) => {
-  const controls = namedControls(root ?? document);
-  return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(controls.filter(isFocusCandidate)) : focusFirstOf(
-    controls.filter((el) => nameMatchesAny(el, [path])).filter(isFocusCandidate)
-  );
+  const scope = root ?? document;
+  return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(namedControls(scope).filter(isFocusCandidate)) : focusFirstOf(pathCandidates(scope, [path]).filter(isFocusCandidate));
 };
 
 exports.CheckboxField = CheckboxField;
@@ -1990,6 +2004,7 @@ exports.useFormSelectorShallow = useFormSelectorShallow;
 exports.useIsDirty = useIsDirty;
 exports.useIsSubmitting = useIsSubmitting;
 exports.useIsValid = useIsValid;
+exports.useNumberInput = useNumberInput;
 exports.useSubmitCount = useSubmitCount;
 exports.useVariantField = useVariantField;
 exports.validateAsync = validateAsync;