formstand 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 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 +53,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 +69,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 +87,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) => {