formstand 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,141 @@
 # Changelog
 
+## formstand-cli Unreleased
+
+- Generated array hooks drop the explicit item type
+  (`useFieldArray(form, "items")`): formstand ≥ 0.5 infers it from the
+  schema through the path — and rejects the old explicit spelling on typed
+  forms. On formstand 0.4 the generated code still compiles, with untyped
+  items.
+- Generated shadcn output defines one `ariaInvalid` helper (used by the
+  inlined adapters and the select trigger) instead of repeating the ternary
+  four times, and the generated `FieldError` computes the message once —
+  cosmetic; runtime behavior unchanged. Internally the MUI and shadcn
+  backends now share their emitted snippets (error helper, `BoundFieldProps`,
+  the leaf switch), so the generators can't drift.
+
+## 0.5.0 — 2026-07-09
+
+### Breaking
+
+- `useFieldArray` infers the item type from a `Form<TSchema>` and a typed
+  path — `useFieldArray(form, "users")` (and template paths like
+  `` `albums.${index}.tracks` ``) needs no type argument, and `push`/`insert`
+  are typed against the schema's item. Consequently the old explicit
+  `useFieldArray<TItem>(form, path)` spelling is a **compile error on typed
+  forms** (drop the generic); it remains the way to bind schema-less
+  `FieldFormApi` forms, where there is nothing to infer from. A non-array
+  path types the items as `never`; a typo'd path is rejected against the
+  full `FieldPath` union, like `useField`. Path selectors return
+  `UseFieldArrayReturn<unknown>` (dynamic paths carry no type), also like
+  `useField`.
+
+### Fixed (site only)
+
+- The deployed playground bundled two copies of React (the formstand alias
+  reaches outside the examples package, so its imports resolved the repo
+  root's copy) — every tab crashed at startup with a null hooks
+  dispatcher. The examples build now dedupes react/zustand/zod and CI
+  asserts the bundle holds exactly one React.
+
+### Docs & examples (no package changes)
+
+- The playground demos bind shadcn's `Input`/`Textarea` with the library's
+  own exported `textInputProps`/`numberInputProps` — the shadcn adapter now
+  covers only the Radix dialect, and the "field has an error" predicate
+  lives once in `examples/src/fieldErrors.ts` (shared by both adapters).
+- The copy-in shadcn kit is trimmed to what the demos render (Badge/Button
+  variants, dead peer-disabled label classes) and every component exports a
+  `Readonly` props type.
+
+## formstand-cli 0.2.1 — 2026-07-09
+
+### Fixed
+
+- Leaf-free schemas (no scalar fields anywhere, e.g. an object of empty
+  objects) no longer generate non-compiling output in the `mui` and
+  `shadcn` backends — the emitted `BoundFieldProps` type referenced
+  `FieldFormApi` without importing it. All three backends now have a
+  leaf-free typecheck test.
+- The shadcn backend's generated output is additionally typechecked in CI
+  against the repo's real Radix-based components (not just the structural
+  stub), so a shadcn/Radix prop-contract change fails our suite instead of
+  the consumer's build.
+
+### Docs & examples (no library package changes)
+
+- Playground: the page chrome stylesheet is unlayered again — cascade
+  layers can't be transpiled, so pre-15.4 WebKit (the es2019 target's
+  audience) was losing every tab's styling; its selectors are class-scoped,
+  so the shadcn utilities are unaffected. The layer-order statement now
+  pins Tailwind's canonical `components` slot below `utilities`.
+- shadcn kit: sliders take an `aria-label` routed to the Radix Thumb (the
+  Root is a `<span>`, so `htmlFor`/`id` never named it); radio-group items
+  show error styling via `group-aria-invalid` (Radix doesn't propagate the
+  Root's `aria-invalid` to items); the Team demo's rows are memoized with
+  stable handlers so keystrokes in one row stop re-rendering the rest.
+- Publish workflow: `--provenance` is explicit again (fail-closed — the
+  automatic path silently skips attestation when conditions aren't met) and
+  the Node pin is `>=24.8`, the first line whose bundled npm meets trusted
+  publishing's 11.5.1 floor. CI asserts the root and examples lockfiles
+  agree on the deduped UI packages, so the smoke test can't silently
+  certify a different build than the deployed playground.
+
+## formstand-cli 0.2.0 — 2026-07-08
+
+### Added
+
+- `--ui shadcn`: generates forms against [shadcn/ui](https://ui.shadcn.com/)
+  conventions — components imported from the app's `@/components/ui/*` alias
+  (what `npx shadcn add` scaffolds), an inlined adapter speaking the Radix
+  dialect (`onCheckedChange`/`onValueChange`, dropdown-close as the blur
+  trigger), and `aria-invalid` error styling with a message line. Generated
+  output is typechecked in CI against the library source and a structural
+  stub of the shadcn components, like the other backends.
+- `emitShadcnForm` joins the programmatic API.
+
+### Docs & examples (no library package changes)
+
+- Four shadcn/ui playground demos (Signup, Checkout, Settings, Team) plus
+  the formstand→shadcn adapter pattern they showcase —
+  `examples/src/shadcn/shadcnAdapter.ts` bridges `useField` to both native
+  inputs and the Radix-based widgets (Checkbox, Switch, Select, Slider,
+  RadioGroup).
+- The playground carries its own copy-in shadcn component kit under a
+  scoped Tailwind 4 setup (no preflight; the plain-CSS and MUI demos are
+  untouched).
+
+## 0.4.1 — 2026-07-08
+
+### Fixed
+
+- `submit`'s stale-write guard now uses pass ownership (cleared by
+  `reset`/`adoptValues`) in addition to the values-reference check — a bare
+  `reset()` on a pristine form during an in-flight submit no longer gets
+  stale errors and touched marks committed (reference equality couldn't see
+  it: reset restores the same `initialValues` reference).
+- `restore()` no longer resurrects in-flight validation flags captured in a
+  snapshot (`isValidating`/`isValidatingForm` are transient, owned by live
+  passes — a restored copy could stick forever).
+- `focusFirstError`/`focusField` verify focus against the element's own root
+  node, fixing a regression that walked past every candidate inside a shadow
+  root and reported failure after moving focus to the wrong control.
+- `focusField("")` focuses the form's first focusable control (whole-form
+  scope, like its imperative siblings), with the same multi-form
+  refuse-to-guess rule as `focusFirstError`.
+- `field.setError("string")` is normalized to an array before reaching
+  `FieldFormApi.setError`, shielding pre-0.4 custom implementations typed
+  for `readonly string[]`.
+
+### Internal
+
+- Validation pass ownership uses unique `Symbol()` tokens — collisions after
+  `reset`/`adoptValues` are impossible by construction rather than guarded
+  by a never-reset counter invariant.
+- Publish workflow fails fast when the pushed tag doesn't match
+  `package.json`'s version; the CLI release checklist pushes the release
+  commit, not just the tag.
+
 ## 0.4.0 — 2026-07-08
 
 ### Breaking
@@ -22,10 +158,13 @@
 - `adoptValues` now clears the in-flight validation flags
   (`isValidating` / `isValidatingForm`) along with the errors it already
   cleared — the rebase disowns in-flight passes.
-- `submit` skips its error/touched state writes when `values` changed while
-  validation was in flight (a `reset` during an in-flight submit no longer
-  gets stale errors committed over the fresh form); `onValid`/`onInvalid`
-  still run and the result still reports the outcome.
+- `submit` skips its error/touched state writes when the form was rebased
+  while validation was in flight: when `values` changed, when `reset` /
+  `adoptValues` ran (including a bare `reset()` on a pristine form, where the
+  values reference doesn't change), or when a concurrent
+  `submit({ force: true })` re-claimed ownership (the LAST submit's writes
+  land). `onValid`/`onInvalid` still run and the result still reports the
+  outcome.
 
 ### Added
 
@@ -35,11 +174,16 @@
   behind `useField().emptyValue`, alongside its adapter siblings
   `numberToInputText` / `parseNumberText`.
 - `field.setError` (from `useField`) accepts a single string, matching
-  `form.setError`.
-- Dev-mode warning (once per path) when `validateField` /
-  `validateFieldAsync` target a path the schema provably cannot contain —
-  protects the docs-sanctioned dynamic-path casts from silent always-valid
-  results.
+  `form.setError`. The hook normalizes the shorthand to a one-element array
+  before forwarding, so custom `FieldFormApi` implementations typed for
+  `readonly string[]` never receive a bare string.
+- `focusField("")` focuses the first focusable control in scope (the
+  whole-form `""` semantics of the imperative surface); under the default
+  `document` scope it refuses to guess between multiple `<form>`s, like
+  `focusFirstError`'s root-`""` fallback.
+- `validateField` / `validateFieldAsync` targeting a path the schema
+  provably cannot contain now warn (once per path per form) — protects the
+  docs-sanctioned dynamic-path casts from silent always-valid results.
 - Docs: a migrating-from-react-hook-form guide with the full API mapping
   table.
 
@@ -48,9 +192,16 @@
 - Array ops no longer strand in-flight `isValidating` flags: flags under the
   path are dropped rather than re-keyed (the completing pass clears the
   original key, so a re-keyed flag could never be cleared).
-- The validation sequence counter is globally monotonic and never resets, so
-  a superseded pre-reset validation pass can no longer collide with a
-  post-reset one and clobber its state.
+- In-flight validation passes are owned via unique symbol tokens (unique by
+  construction), so a superseded pre-reset validation pass can never collide
+  with a post-reset one and clobber its state.
+- `restore(snapshot)` clears the transient in-flight flags (`isValidating` /
+  `isValidatingForm`) instead of restoring them — in-flight state is owned
+  by live passes, never by snapshots, so a restored flag would stick forever.
+- `focusFirstError` / `focusField` verify focus against the element's own
+  root (`getRootNode().activeElement`), so controls inside a shadow root are
+  no longer reported as unfocused (`document.activeElement` retargets to the
+  shadow host).
 - `validateFieldAsync("")` delegates to the whole-form pass, so its pending
   state lives in `isValidatingForm` instead of `isValidating[""]`.
 - `focusFirstError` / `focusField` report success only when a control

package/dist/index.cjs

@@ -274,6 +274,7 @@ var dirtyPathsOf = (values, initial, prefix) => {
   return [prefix];
 };
 var FORM_SEQ_KEY = "__form__";
+var SUBMIT_SEQ_KEY = "__submit__";
 var stringArraysEqual = (a, b) => a === b || a.length === b.length && a.every((v, i) => v === b[i]);
 var reuseErrorRefs = (next, prev) => {
   if (next === prev) return prev;
@@ -466,19 +467,18 @@ var createForm = (schema, options) => {
     };
   };
   const sequences = /* @__PURE__ */ new Map();
-  const seqRef = { current: 0 };
-  const nextSeq = (key) => {
-    seqRef.current += 1;
-    sequences.set(key, seqRef.current);
-    return seqRef.current;
+  const claimPass = (key) => {
+    const pass = Symbol(key);
+    sequences.set(key, pass);
+    return pass;
   };
   const validateAsyncOnForm = async () => {
-    const seq = nextSeq(FORM_SEQ_KEY);
+    const pass = claimPass(FORM_SEQ_KEY);
     const valuesAtStart = store.getState().values;
     store.setState((state) => ({ ...state, isValidatingForm: true }));
     const result = await validateAsync(schema, valuesAtStart);
     const live = store.getState();
-    const stillOwns = sequences.get(FORM_SEQ_KEY) === seq;
+    const stillOwns = sequences.get(FORM_SEQ_KEY) === pass;
     if (!stillOwns || live.values !== valuesAtStart) {
       if (stillOwns) {
         store.setState((state) => ({ ...state, isValidatingForm: false }));
@@ -501,7 +501,7 @@ var createForm = (schema, options) => {
       const result2 = await validateAsyncOnForm();
       return result2.kind === "valid";
     }
-    const seqs = new Map(paths.map((p) => [p, nextSeq(p)]));
+    const passes = new Map(paths.map((p) => [p, claimPass(p)]));
     const valuesAtStart = store.getState().values;
     store.setState((state) => ({
       ...state,
@@ -516,7 +516,9 @@ var createForm = (schema, options) => {
       (k) => !inScopeOfAny(k, paths)
     );
     const live = store.getState();
-    const stillCurrent = paths.filter((p) => sequences.get(p) === seqs.get(p));
+    const stillCurrent = paths.filter(
+      (p) => sequences.get(p) === passes.get(p)
+    );
     if (live.values !== valuesAtStart) {
       if (stillCurrent.length > 0) {
         store.setState((state) => ({
@@ -557,7 +559,7 @@ var createForm = (schema, options) => {
         result.kind === "invalid" ? result.errors : emptyErrors
       );
     }
-    const seq = nextSeq(path);
+    const pass = claimPass(path);
     const valuesAtStart = store.getState().values;
     store.setState((state) => ({
       ...state,
@@ -565,7 +567,7 @@ var createForm = (schema, options) => {
     }));
     const scoped = await scopedFieldErrorsAsync(path, valuesAtStart);
     const live = store.getState();
-    const stillOwns = sequences.get(path) === seq;
+    const stillOwns = sequences.get(path) === pass;
     if (!stillOwns || live.values !== valuesAtStart) {
       if (stillOwns) {
         store.setState((state) => ({
@@ -644,11 +646,12 @@ var createForm = (schema, options) => {
       submitCount: state.submitCount + 1
     }));
     try {
+      const pass = claimPass(SUBMIT_SEQ_KEY);
       const valuesAtStart = store.getState().values;
       const result = await validateAsync(schema, valuesAtStart);
-      const staleValues = store.getState().values !== valuesAtStart;
+      const stale = sequences.get(SUBMIT_SEQ_KEY) !== pass || store.getState().values !== valuesAtStart;
       if (result.kind === "invalid") {
-        if (!staleValues) {
+        if (!stale) {
           store.setState((state) => {
             const committed = commitFullPass(state, result.errors);
             return {
@@ -666,11 +669,11 @@ var createForm = (schema, options) => {
             };
           });
         }
-        const merged = staleValues ? result.errors : store.getState().errors;
+        const merged = stale ? result.errors : store.getState().errors;
         onInvalid?.(merged);
         return { kind: "invalid", errors: merged };
       }
-      if (!staleValues) {
+      if (!stale) {
         store.setState((state) => ({
           ...state,
           ...commitFullPass(state, emptyErrors)
@@ -923,7 +926,13 @@ var createForm = (schema, options) => {
         errors: reuseErrorRefs(
           mergeErrorChannels(schemaErrors, serverErrors),
           snap.errors ?? emptyErrors
-        )
+        ),
+        // In-flight state is owned by live passes, never by snapshots: a
+        // snapshotted flag has no pass left to clear it (the pass that set
+        // it cleared its ORIGINAL entry when it settled), so restoring one
+        // would stick it forever.
+        isValidating: emptyBools,
+        isValidatingForm: false
       };
     })
   });
@@ -1079,7 +1088,10 @@ function useField(form, pathArg, options) {
     [form, path]
   );
   const setError = react.useCallback(
-    (errors) => form.setError(path, errors),
+    // Normalize the string shorthand HERE, before forwarding: custom
+    // FieldFormApi implementations written against the pre-0.4 surface are
+    // typed for readonly string[] and must never receive a bare string.
+    (errors) => form.setError(path, typeof errors === "string" ? [errors] : errors),
     [form, path]
   );
   const clearError = react.useCallback(
@@ -1348,9 +1360,14 @@ var focusableControls = (scope) => [
 ].filter(
   (el) => !el.matches(':disabled, [type="hidden"]') && el.closest("dialog:not([open])") === null
 );
+var holdsFocus = (el) => {
+  const rootNode = el.getRootNode();
+  const active = rootNode instanceof Document || rootNode instanceof ShadowRoot ? rootNode.activeElement : document.activeElement;
+  return active === el;
+};
 var focusFirstOf = (candidates) => candidates.some((el) => {
   el.focus();
-  return document.activeElement === el;
+  return holdsFocus(el);
 });
 var nameMatchesAny = (el, paths) => {
   const name = el.getAttribute("name");
@@ -1370,11 +1387,10 @@ var focusFirstError = (errors, root) => {
   const candidates = fieldMatches.length > 0 ? fieldMatches : rootFallbackApplies ? controls : [];
   return focusFirstOf(candidates);
 };
-var focusField = (path, root) => focusFirstOf(
-  focusableControls(root ?? document).filter(
-    (el) => nameMatchesAny(el, [path])
-  )
-);
+var focusField = (path, root) => {
+  const controls = focusableControls(root ?? document);
+  return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(controls) : focusFirstOf(controls.filter((el) => nameMatchesAny(el, [path])));
+};
 var EMPTY_ID_STATE = { items: [], ids: [], counter: 0 };
 var EMPTY_ITEMS = [];
 var reconcileIds = (prev, nextItems) => {
@@ -1413,7 +1429,7 @@ var reconcileIds = (prev, nextItems) => {
     counter: prev.counter + Math.max(0, unmatched - leftover.length)
   };
 };
-var useFieldArray = (form, pathArg) => {
+function useFieldArray(form, pathArg) {
   const path = react$1.useStore(
     form.store,
     (state) => typeof pathArg === "function" ? pathArg(state) : pathArg
@@ -1478,7 +1494,7 @@ var useFieldArray = (form, pathArg) => {
     }),
     [fields, items, error, push, remove, insert, move, swap]
   );
-};
+}
 
 exports.CheckboxField = CheckboxField;
 exports.NumberField = NumberField;