formstand 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # 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
+
+- 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 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
+
+- `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`. 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.
+
+### 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).
+- 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
+  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

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,17 +262,19 @@ 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];
 };
 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;
@@ -359,6 +394,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 +441,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,18 +467,18 @@ var createForm = (schema, options) => {
     };
   };
   const sequences = /* @__PURE__ */ new Map();
-  const nextSeq = (key) => {
-    const next = (sequences.get(key) ?? 0) + 1;
-    sequences.set(key, next);
-    return next;
+  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 }));
@@ -455,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,
@@ -470,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) => ({
@@ -504,7 +552,14 @@ var createForm = (schema, options) => {
     return requestedValid;
   };
   const validateFieldAsync = async (path) => {
-    const seq = nextSeq(path);
+    warnMissingSchemaPath("validateFieldAsync", path);
+    if (path === "") {
+      const result = await validateAsyncOnForm();
+      return fieldResult(
+        result.kind === "invalid" ? result.errors : emptyErrors
+      );
+    }
+    const pass = claimPass(path);
     const valuesAtStart = store.getState().values;
     store.setState((state) => ({
       ...state,
@@ -512,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) => ({
@@ -563,7 +618,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 +646,44 @@ var createForm = (schema, options) => {
       submitCount: state.submitCount + 1
     }));
     try {
-      const result = await validateAsync(schema, store.getState().values);
+      const pass = claimPass(SUBMIT_SEQ_KEY);
+      const valuesAtStart = store.getState().values;
+      const result = await validateAsync(schema, valuesAtStart);
+      const stale = sequences.get(SUBMIT_SEQ_KEY) !== pass || 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 (!stale) {
+          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 = stale ? result.errors : store.getState().errors;
         onInvalid?.(merged);
         return { kind: "invalid", errors: merged };
       }
-      store.setState((state) => ({
-        ...state,
-        ...commitFullPass(state, emptyErrors)
-      }));
-      await onValid(result.data);
+      if (!stale) {
+        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 +815,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) => {
@@ -849,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
       };
     })
   });
@@ -908,8 +991,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[""])
@@ -1007,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(
@@ -1206,7 +1290,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 +1339,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,24 +1353,43 @@ 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 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 holdsFocus(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) => {
+  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 = [];
@@ -1390,7 +1503,9 @@ 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;
@@ -1408,8 +1523,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;