formstand 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,8 +1,90 @@
 # Changelog
 
+## 0.4.0 — 2026-07-08
+
+### Breaking
+
+- The deprecated `useFormState` / `useFormStateShallow` aliases are removed —
+  use `useFormSelector` / `useFormSelectorShallow` (renamed in 0.2.0 because
+  React DOM ships its own, deprecated, `useFormState`).
+- Bound components' `path` prop is schema-typed when `form` is a
+  `Form<TSchema>` (`PathsOf<F>`): typo'd paths are now compile errors, and
+  runtime-built strings need the documented cast. A structural `FieldFormApi`
+  form keeps plain `string`.
+- `focusFirstError`'s root-`""` fallback no longer fires under the default
+  `document` scope when the page holds more than one `<form>` — "first
+  control" would be a guess, so it returns `false`. Pass the form element
+  (e.g. via a ref) as `root`.
+- `SubmitResult` gained `{ kind: "error", error }`: when `onValid` throws or
+  rejects, `submit` now **resolves** with that result instead of rejecting
+  (so `handleSubmit` never leaves an unhandled rejection). Code that relied
+  on catching the rejection must check `result.kind === "error"`.
+- `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.
+
+### Added
+
+- `focusField(path, root?)` — imperative focus by path (the `setFocus` of
+  react-hook-form), sharing `focusFirstError`'s focusability rules.
+- `emptyValueForSchema(schema)` is exported — the schema-introspection rule
+  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.
+- Docs: a migrating-from-react-hook-form guide with the full API mapping
+  table.
+
+### Fixed
+
+- 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.
+- `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
+  actually **holds** focus — hidden, disabled, closed-`<dialog>`, and
+  focus-refusing matches are passed over for the next candidate in DOM
+  order.
+- `dirtyFields()` / `diff()` report an object that diverges only by an
+  `undefined`-valued key, agreeing with `useIsDirty`.
+- `SelectField` tolerates duplicate option values (React keys no longer
+  collide).
+- `useField` typo errors blame the path argument against the full
+  `FieldPath` union instead of blaming the form argument.
+
+## 0.3.0 — 2026-07-04
+
+### Added
+
+- `numberToInputText`, `parseNumberText` (and the `ParsedNumberText` type)
+  are exported — the number-text rules the built-in bindings use, so
+  adapters for third-party UI kits can share them instead of re-deriving.
+  This is the minimum formstand version for `formstand-gen --ui mui` output.
+
+### Docs & examples (no package changes)
+
+- Five Material UI 9 playground demos plus the ~60-line formstand→MUI
+  adapter pattern they showcase.
+- `formstand-cli` (`formstand-gen`) lives in the repo: generates form
+  components from a zod schema or TypeScript type. Published separately.
+
 ## 0.2.0 — 2026-07-02
 
-The result of a full-repo review pass (see `TODO.md` items 1–34).
+The result of a full-repo review pass (37 items across correctness, API
+gaps, robustness, testing, tooling, and docs — the working log lived in
+`TODO.md`, retired after release; see the git history for the play-by-play).
 
 ### Breaking
 

package/README.md

@@ -1,5 +1,7 @@
 # formstand
 
+[![CI](https://github.com/Scrumrot/formstand/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Scrumrot/formstand/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/formstand)](https://www.npmjs.com/package/formstand) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Scrumrot/formstand/blob/main/LICENSE)
+
 Zod-schema-first form state for React 19, backed by zustand.
 
 **[Documentation](https://scrumrot.github.io/formstand/)** · **[Live playground](https://scrumrot.github.io/formstand/examples/)** · **[API reference](https://scrumrot.github.io/formstand/api/)**
@@ -84,11 +86,11 @@ const form = createForm(schema, {
 | `setMode` / `setReValidateMode` | switch modes at runtime |
 | `reset(nextInitial?, options?)` | reset to initial; optional partial overrides (shallow-merged for record roots, replaced wholesale otherwise) and `{ keepErrors, keepTouched, keepSubmitCount }` (no `keepDirty` — dirtiness derives from values vs initial, and reset makes them equal) |
 | `resetField(path)` | reset one field to its initial value, clearing its (and descendants') error/touched state (dirtiness clears by definition — the value now equals initial) |
-| `adoptValues(values)` | mid-session rebase: replaces `values` + `initialValues` and clears `errors`, but **preserves** interaction state (`touched`, `submitCount`, `isSubmitting`, `isValidating`, `mode`). Use `reset()` for a full wipe |
+| `adoptValues(values)` | mid-session rebase: replaces `values` + `initialValues` and clears `errors` and in-flight validation flags (`isValidating`/`isValidatingForm` — the rebase disowns in-flight passes), but **preserves** interaction state (`touched`, `submitCount`, `isSubmitting`, `mode`). Use `reset()` for a full wipe |
 | `updateState(updater)` | atomic multi-field patch; `errors` is derived from `schemaErrors`/`serverErrors`, so patch the channels — the patch type omits `errors` entirely, and a plain-JS `errors` patch is warned about and ignored |
 | `validate()` / `validateField(path)` / `validateFields(paths)` | sync validation; on an async schema they transparently start the async pass instead (`validate`/`validateField` return `{ kind: "pending", promise }`, `validateFields` returns the `Promise<boolean>` itself) |
 | `validateAsync()` / `validateFieldAsync(path)` / `validateFieldsAsync(paths)` | async; supports `async .refine` |
-| `submit(onValid, onInvalid?, { force? })` → `Promise<SubmitResult>` | full submit flow; resolves `{ kind: "valid", data }`, `{ kind: "invalid", errors }` (errored fields are also marked touched), or `{ kind: "skipped" }` when another submit is in flight |
+| `submit(onValid, onInvalid?, { force? })` → `Promise<SubmitResult>` | full submit flow; resolves `{ kind: "valid", data }`, `{ kind: "invalid", errors }` (errored fields are also marked touched), `{ kind: "skipped" }` when another submit is in flight, or `{ kind: "error", error }` when `onValid` throws/rejects — submit resolves instead of rejecting, so `handleSubmit` never produces an unhandled rejection from an `onValid` throw |
 | `handleSubmit(onValid, onInvalid?)(event?)` | event handler wrapper that calls `preventDefault` |
 | `getField(path)` | typed one-shot value read |
 | `getFieldState(path)` | typed one-shot read of a field's full slice (value/error/touched/dirty/isValidating) |
@@ -127,7 +129,7 @@ name.dirty;
 name.isValidating;
 name.setValue(v);
 name.setTouched();
-name.setError([...]);
+name.setError("taken");  // or ["taken", "reserved"]
 name.clearError();
 name.validate();
 name.validateAsync();
@@ -176,7 +178,7 @@ Selector-style subscription. Use `useFormSelectorShallow` for selectors that ret
 
 > Formerly `useFormState` / `useFormStateShallow` — renamed because React DOM
 > ships its own (deprecated) `useFormState` and auto-imports regularly grabbed
-> the wrong one. The old names still work as deprecated aliases.
+> the wrong one. The old names were removed in 0.4.0.
 
 ### `useFormError(form)`
 
@@ -256,6 +258,20 @@ works out of the box. Wire it into the invalid-submit handler:
 <form onSubmit={form.handleSubmit(onValid, (errors) => focusFirstError(errors))}>
 ```
 
+On a page with several forms, pass the form element (e.g. via a ref) as `root`
+so the search stays inside your form — without it the whole document is
+scanned, and a root-`""` error's first-control fallback refuses to guess
+between forms (it returns `false` when the document holds more than one
+`<form>`):
+
+```tsx
+<form ref={formRef} onSubmit={form.handleSubmit(onValid, (errors) => focusFirstError(errors, formRef.current ?? undefined))}>
+```
+
+It returns `true` only when a control actually received focus — disabled or
+hidden controls, controls inside a closed `<dialog>`, and controls that refuse
+focus (e.g. `display: none`) are passed over for the next match.
+
 For custom focus logic, every bound component also takes a `ref` to its input.
 
 ## Sharing a form across components
@@ -409,6 +425,12 @@ form.handleSubmit(async (data) => {
 });
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) — note the repo has three
+independent npm roots (`.`, `examples/`, `cli/`), and the root test suite
+needs `examples/` installed.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -188,6 +188,39 @@ var emptyValueForSchema = (schema) => {
   };
   return walk(schema, false);
 };
+var unwrapForWalk = (s) => {
+  if (s instanceof zod.z.ZodOptional || s instanceof zod.z.ZodNullable) {
+    return s.unwrap();
+  }
+  if (s instanceof zod.z.ZodDefault || s instanceof zod.z.ZodPrefault || s instanceof zod.z.ZodCatch || s instanceof zod.z.ZodReadonly || s instanceof zod.z.ZodNonOptional) {
+    return s.def.innerType;
+  }
+  if (s instanceof zod.z.ZodPipe) return s.def.in;
+  return null;
+};
+var isLeafSchema = (s) => s instanceof zod.z.ZodString || s instanceof zod.z.ZodNumber || s instanceof zod.z.ZodBoolean || s instanceof zod.z.ZodBigInt || s instanceof zod.z.ZodDate || s instanceof zod.z.ZodEnum || s instanceof zod.z.ZodLiteral || s instanceof zod.z.ZodNull || s instanceof zod.z.ZodUndefined || s instanceof zod.z.ZodVoid || s instanceof zod.z.ZodNaN || s instanceof zod.z.ZodSymbol;
+var SCHEMA_WALK_BUDGET = 64;
+var schemaHasPath = (schema, path) => {
+  const walk = (s, segments, budget) => {
+    if (budget <= 0) return true;
+    const inner = unwrapForWalk(s);
+    if (inner !== null) return walk(inner, segments, budget - 1);
+    const [head, ...rest] = segments;
+    if (head === void 0) return true;
+    if (s instanceof zod.z.ZodObject) {
+      const shape = s.shape;
+      const child = shape[String(head)];
+      if (child !== void 0) return walk(child, rest, budget - 1);
+      const catchall = s.def.catchall;
+      return catchall !== void 0 && !(catchall instanceof zod.z.ZodNever);
+    }
+    if (s instanceof zod.z.ZodArray) {
+      return typeof head === "number" ? walk(s.element, rest, budget - 1) : false;
+    }
+    return !isLeafSchema(s);
+  };
+  return walk(schema, parsePath(path), SCHEMA_WALK_BUDGET);
+};
 var hasChecks = (s) => {
   const checks = s.def.checks;
   return checks !== void 0 && checks.length > 0;
@@ -229,13 +262,14 @@ var dirtyPathsOf = (values, initial, prefix) => {
   if (valuesEqual(values, initial)) return [];
   if (isPlainObject(values) && isPlainObject(initial)) {
     const keys = /* @__PURE__ */ new Set([...Object.keys(values), ...Object.keys(initial)]);
-    return [...keys].flatMap(
+    const childPaths = [...keys].flatMap(
       (k) => dirtyPathsOf(
         values[k],
         initial[k],
         prefix === "" ? k : `${prefix}.${k}`
       )
     );
+    return childPaths.length > 0 ? childPaths : [prefix];
   }
   return [prefix];
 };
@@ -359,6 +393,16 @@ var createForm = (schema, options) => {
     subschemaCache.set(path, sub);
     return sub;
   };
+  const checkedSchemaPaths = /* @__PURE__ */ new Set();
+  const warnMissingSchemaPath = (fn, path) => {
+    if (path === "" || checkedSchemaPaths.has(path)) return;
+    checkedSchemaPaths.add(path);
+    if (!schemaHasPath(schema, path)) {
+      console.warn(
+        `[formstand] ${fn}("${path}"): path does not exist in the schema \u2014 result will always be valid.`
+      );
+    }
+  };
   const fieldScopeFor = (path, values) => {
     const sub = path === "" ? null : subschemaAt(path);
     if (sub === null) {
@@ -396,6 +440,7 @@ var createForm = (schema, options) => {
     serverErrors: omitScope(state.serverErrors, [path])
   });
   const validateField = (path) => {
+    warnMissingSchemaPath("validateField", path);
     try {
       const scoped = scopedFieldErrors(path);
       store.setState((state) => ({
@@ -421,10 +466,11 @@ var createForm = (schema, options) => {
     };
   };
   const sequences = /* @__PURE__ */ new Map();
+  const seqRef = { current: 0 };
   const nextSeq = (key) => {
-    const next = (sequences.get(key) ?? 0) + 1;
-    sequences.set(key, next);
-    return next;
+    seqRef.current += 1;
+    sequences.set(key, seqRef.current);
+    return seqRef.current;
   };
   const validateAsyncOnForm = async () => {
     const seq = nextSeq(FORM_SEQ_KEY);
@@ -504,6 +550,13 @@ var createForm = (schema, options) => {
     return requestedValid;
   };
   const validateFieldAsync = async (path) => {
+    warnMissingSchemaPath("validateFieldAsync", path);
+    if (path === "") {
+      const result = await validateAsyncOnForm();
+      return fieldResult(
+        result.kind === "invalid" ? result.errors : emptyErrors
+      );
+    }
     const seq = nextSeq(path);
     const valuesAtStart = store.getState().values;
     store.setState((state) => ({
@@ -563,7 +616,13 @@ var createForm = (schema, options) => {
           )
         }),
         touched: reKeyByArrayPath(state.touched, path, mapper),
-        isValidating: reKeyByArrayPath(state.isValidating, path, mapper)
+        // Drop (don't re-key) in-flight flags under the array: the op changes
+        // `values`, so every pass they belong to fails its values-changed
+        // guard and never commits — but each pass's cleanup omits its
+        // ORIGINAL key, so a re-keyed entry would be orphaned and stick
+        // forever. Dropped, the flag is gone now and the cleanup is a
+        // harmless no-op.
+        isValidating: omitScope(state.isValidating, [path])
       };
     });
   };
@@ -585,33 +644,43 @@ var createForm = (schema, options) => {
       submitCount: state.submitCount + 1
     }));
     try {
-      const result = await validateAsync(schema, store.getState().values);
+      const valuesAtStart = store.getState().values;
+      const result = await validateAsync(schema, valuesAtStart);
+      const staleValues = store.getState().values !== valuesAtStart;
       if (result.kind === "invalid") {
-        store.setState((state) => {
-          const committed = commitFullPass(state, result.errors);
-          return {
-            ...state,
-            ...committed,
-            // Mark every errored field touched so touched-gated error UIs
-            // show something after the canonical first failed submit. The
-            // "" key (schema-level refine) has no field to touch.
-            touched: {
-              ...state.touched,
-              ...Object.fromEntries(
-                Object.keys(committed.errors).filter((k) => k !== "").map((k) => [k, true])
-              )
-            }
-          };
-        });
-        const merged = store.getState().errors;
+        if (!staleValues) {
+          store.setState((state) => {
+            const committed = commitFullPass(state, result.errors);
+            return {
+              ...state,
+              ...committed,
+              // Mark every errored field touched so touched-gated error UIs
+              // show something after the canonical first failed submit. The
+              // "" key (schema-level refine) has no field to touch.
+              touched: {
+                ...state.touched,
+                ...Object.fromEntries(
+                  Object.keys(committed.errors).filter((k) => k !== "").map((k) => [k, true])
+                )
+              }
+            };
+          });
+        }
+        const merged = staleValues ? result.errors : store.getState().errors;
         onInvalid?.(merged);
         return { kind: "invalid", errors: merged };
       }
-      store.setState((state) => ({
-        ...state,
-        ...commitFullPass(state, emptyErrors)
-      }));
-      await onValid(result.data);
+      if (!staleValues) {
+        store.setState((state) => ({
+          ...state,
+          ...commitFullPass(state, emptyErrors)
+        }));
+      }
+      try {
+        await onValid(result.data);
+      } catch (error) {
+        return { kind: "error", error };
+      }
       return { kind: "valid", data: result.data };
     } finally {
       inFlight.count -= 1;
@@ -743,7 +812,12 @@ var createForm = (schema, options) => {
         ...errorChannels(state, {
           schemaErrors: emptyErrors,
           serverErrors: emptyErrors
-        })
+        }),
+        // Clearing `sequences` disowns every in-flight pass, including its
+        // flag cleanup (the ownership check fails, so it never writes) —
+        // clear the flags here too, mirroring reset(), or they'd stick.
+        isValidating: emptyBools,
+        isValidatingForm: false
       }));
     },
     reset: (nextInitial, resetOptions) => {
@@ -908,8 +982,6 @@ function useFormSelector(form, selector) {
 function useFormSelectorShallow(form, selector) {
   return react$1.useStore(form.store, shallow.useShallow(selector));
 }
-var useFormState = useFormSelector;
-var useFormStateShallow = useFormSelectorShallow;
 var useFormError = (form) => react$1.useStore(
   form.store,
   shallow.useShallow((state) => state.errors[""])
@@ -1206,7 +1278,12 @@ var NumberField = ({
     /* @__PURE__ */ jsxRuntime.jsx(ErrorText, { id: errorId, error: field.error })
   ] });
 };
-var CheckboxField = ({ form, path, label, ref }) => {
+var CheckboxField = ({
+  form,
+  path,
+  label,
+  ref
+}) => {
   const id = react.useId();
   const errorId = `${id}-error`;
   const field = useField(form, path);
@@ -1250,7 +1327,12 @@ var SelectField = ({
         "aria-describedby": hasError(field.error) ? errorId : void 0,
         children: [
           showEmptyOption ? /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", disabled: true, children: placeholder ?? "" }) : null,
-          options.map((opt) => /* @__PURE__ */ jsxRuntime.jsx("option", { value: opt.value, children: opt.label }, opt.value))
+          options.map((opt, index) => (
+            // Index-qualified: option lists may legitimately repeat a value
+            // (e.g. differently-labelled aliases), and bare value keys would
+            // collide.
+            /* @__PURE__ */ jsxRuntime.jsx("option", { value: opt.value, children: opt.label }, `${index}-${opt.value}`)
+          ))
         ]
       }
     ),
@@ -1259,25 +1341,40 @@ var SelectField = ({
 };
 
 // src/react/focusError.ts
+var focusableControls = (scope) => [
+  ...scope.querySelectorAll(
+    "input[name], select[name], textarea[name]"
+  )
+].filter(
+  (el) => !el.matches(':disabled, [type="hidden"]') && el.closest("dialog:not([open])") === null
+);
+var focusFirstOf = (candidates) => candidates.some((el) => {
+  el.focus();
+  return document.activeElement === el;
+});
+var nameMatchesAny = (el, paths) => {
+  const name = el.getAttribute("name");
+  return name !== null && paths.some((p) => isPathOrChild(name, p));
+};
 var focusFirstError = (errors, root) => {
   const scope = root ?? document;
   const erroredPaths = Object.keys(errors).filter(
     (k) => k !== "" && (errors[k]?.length ?? 0) > 0
   );
   const hasRootError = (errors[""]?.length ?? 0) > 0;
-  const controls = [
-    ...scope.querySelectorAll(
-      "input[name], select[name], textarea[name]"
-    )
-  ].filter((el) => !el.matches(':disabled, [type="hidden"]'));
-  const fieldMatch = controls.find((el) => {
-    const name = el.getAttribute("name");
-    return name !== null && erroredPaths.some((k) => isPathOrChild(name, k));
-  });
-  const target = fieldMatch ?? (hasRootError ? controls[0] : void 0);
-  target?.focus();
-  return target !== void 0;
+  const controls = focusableControls(scope);
+  const fieldMatches = controls.filter(
+    (el) => nameMatchesAny(el, erroredPaths)
+  );
+  const rootFallbackApplies = hasRootError && (root !== void 0 || document.querySelectorAll("form").length <= 1);
+  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 EMPTY_ID_STATE = { items: [], ids: [], counter: 0 };
 var EMPTY_ITEMS = [];
 var reconcileIds = (prev, nextItems) => {
@@ -1390,11 +1487,15 @@ exports.TextField = TextField;
 exports.checkboxProps = checkboxProps;
 exports.createForm = createForm;
 exports.createFormContext = createFormContext;
+exports.emptyValueForSchema = emptyValueForSchema;
 exports.flattenIssues = flattenIssues;
+exports.focusField = focusField;
 exports.focusFirstError = focusFirstError;
 exports.getAtPath = getAtPath;
 exports.isAsyncRequiredError = isAsyncRequiredError;
 exports.numberInputProps = numberInputProps;
+exports.numberToInputText = numberToInputText;
+exports.parseNumberText = parseNumberText;
 exports.parsePath = parsePath;
 exports.selectProps = selectProps;
 exports.setAtPath = setAtPath;
@@ -1406,8 +1507,6 @@ exports.useForm = useForm;
 exports.useFormError = useFormError;
 exports.useFormSelector = useFormSelector;
 exports.useFormSelectorShallow = useFormSelectorShallow;
-exports.useFormState = useFormState;
-exports.useFormStateShallow = useFormStateShallow;
 exports.useIsDirty = useIsDirty;
 exports.useIsSubmitting = useIsSubmitting;
 exports.useIsValid = useIsValid;