formstand 0.9.0 → 0.11.0

package/dist/index.cjs

@@ -20,6 +20,20 @@ var moveFromTo = (from, to) => (n) => {
   return n;
 };
 var swapIndices = (a, b) => (n) => n === a ? b : n === b ? a : n;
+var invertMapper = (mapper, oldLength, newLength) => {
+  const oldByNew = new Map(
+    Array.from({ length: oldLength }, (_, oldIndex) => oldIndex).flatMap(
+      (oldIndex) => {
+        const newIndex = mapper(oldIndex);
+        return newIndex === null ? [] : [[newIndex, oldIndex]];
+      }
+    )
+  );
+  return Array.from(
+    { length: newLength },
+    (_, newIndex) => oldByNew.get(newIndex) ?? -1
+  );
+};
 var indexAndTail = (rest) => {
   const dotIdx = rest.indexOf(".");
   const idxStr = dotIdx === -1 ? rest : rest.slice(0, dotIdx);
@@ -43,6 +57,53 @@ var reKeyByArrayPath = (map, basePath, mapper) => {
   );
 };
 
+// src/core/arrayOpLog.ts
+var OP_LOG_LIMIT = 16;
+var MAX_LOG_PATHS = 256;
+var composeOps = (first, second) => ({
+  from: first.from,
+  to: second.to,
+  mapping: second.mapping.map(
+    (mid) => mid === -1 ? -1 : first.mapping[mid] ?? -1
+  )
+});
+var logs = /* @__PURE__ */ new WeakMap();
+var boundOps = (ops) => {
+  const [head, second] = ops;
+  if (ops.length <= OP_LOG_LIMIT || head === void 0 || second === void 0) {
+    return ops;
+  }
+  return head.to === second.from ? [composeOps(head, second), ...ops.slice(2)] : ops.slice(1);
+};
+var recordArrayOp = (store, path, record) => {
+  const existing = logs.get(store);
+  const byPath = existing ?? /* @__PURE__ */ new Map();
+  if (existing === void 0) logs.set(store, byPath);
+  const bounded = boundOps([...byPath.get(path) ?? [], record]);
+  byPath.delete(path);
+  byPath.set(path, bounded);
+  if (byPath.size > MAX_LOG_PATHS) {
+    const oldest = byPath.keys().next().value;
+    if (oldest !== void 0) byPath.delete(oldest);
+  }
+};
+var arrayOpsFor = (store, path) => logs.get(store)?.get(path) ?? [];
+var clearArrayOps = (store, path) => {
+  logs.get(store)?.delete(path);
+};
+var clearArrayOpsUnder = (store, path, keepSelf = false) => {
+  const byPath = logs.get(store);
+  if (byPath === void 0) return;
+  if (path === "") {
+    byPath.clear();
+    return;
+  }
+  const related = [...byPath.keys()].filter(
+    (p) => p === path && !keepSelf || p.startsWith(`${path}.`)
+  );
+  related.forEach((p) => byPath.delete(p));
+};
+
 // src/core/equality.ts
 var isPlainObject = (v) => {
   if (typeof v !== "object" || v === null) return false;
@@ -178,7 +239,7 @@ var expandIssue = (issue, prefix) => {
   return [{ path: issuePathToFormPath(at), message: issue.message }];
 };
 var flattenIssues = (issues) => issues.flatMap((issue) => expandIssue(issue, [])).reduce((acc, { path, message }) => {
-  const existing = acc[path] ?? [];
+  const existing = (Object.hasOwn(acc, path) ? acc[path] : void 0) ?? [];
   return existing.includes(message) ? acc : { ...acc, [path]: [...existing, message] };
 }, {});
 var validateSync = (schema, values) => {
@@ -311,7 +372,9 @@ var reuseErrorRefs = (next, prev) => {
 };
 var scopeSettledResult = (result, path, viaSubschema) => result.kind !== "invalid" ? emptyErrors : viaSubschema ? prefixErrorKeys(result.errors, path) : path === "" ? result.errors : pickScope(result.errors, [path]);
 var mergeErrorChannels = (schema, server) => {
-  const extra = Object.entries(server).filter(([k]) => schema[k] === void 0);
+  const extra = Object.entries(server).filter(
+    ([k]) => !Object.hasOwn(schema, k)
+  );
   return extra.length === 0 ? schema : { ...schema, ...Object.fromEntries(extra) };
 };
 var errorChannels = (state, patch) => {
@@ -370,8 +433,11 @@ var createForm = (schema, options) => {
     schemaErrors: reuseErrorRefs(next, state.schemaErrors)
   });
   const validate = () => {
+    if (asyncScopes.has("")) {
+      return { kind: "pending", promise: validateAsyncOnForm() };
+    }
     try {
-      const result = validateSync(schema, store.getState().values);
+      const result = validateSyncLatched("", schema, store.getState().values);
       store.setState((state) => ({
         ...state,
         ...commitFullPass(
@@ -388,25 +454,32 @@ var createForm = (schema, options) => {
     }
   };
   const validateFields = (paths) => {
-    if (paths.length === 0) return true;
+    if (paths.length === 0) return { kind: "valid" };
     if (paths.some((p) => p === "")) {
       const result = validate();
-      return result.kind === "pending" ? result.promise.then((r) => r.kind === "valid") : result.kind === "valid";
+      return result.kind === "pending" ? { kind: "pending", promise: result.promise.then(settledFormResult) } : settledFormResult(result);
+    }
+    const values = store.getState().values;
+    const scopes = paths.map((path) => ({
+      path,
+      scope: fieldScopeFor(path, values)
+    }));
+    const allViaSubschema = scopes.every(
+      ({ scope }) => scope.kind === "skip" || scope.kind === "parse" && scope.viaSubschema
+    );
+    const anyLatched = allViaSubschema ? scopes.some(
+      ({ path, scope }) => scope.kind === "parse" && asyncScopes.has(path)
+    ) : asyncScopes.has("");
+    if (anyLatched) {
+      return { kind: "pending", promise: validateFieldsAsync(paths) };
     }
     try {
-      const values = store.getState().values;
-      const scopes = paths.map((path) => ({
-        path,
-        scope: fieldScopeFor(path, values)
-      }));
-      if (scopes.every(
-        ({ scope }) => scope.kind === "skip" || scope.kind === "parse" && scope.viaSubschema
-      )) {
+      if (allViaSubschema) {
         const merged = scopes.reduce(
           (acc, { path, scope }) => scope.kind === "skip" ? acc : {
             ...acc,
             ...scopeSettledResult(
-              validateSync(scope.schema, scope.value),
+              validateSyncLatched(path, scope.schema, scope.value),
               path,
               true
             )
@@ -415,37 +488,31 @@ var createForm = (schema, options) => {
         );
         store.setState((state) => ({
           ...state,
-          ...errorChannels(state, {
-            schemaErrors: reuseErrorRefs(
-              mergeScopedErrors(state.schemaErrors, merged, paths),
-              state.schemaErrors
-            ),
-            serverErrors: omitScope(state.serverErrors, paths)
-          })
+          ...commitScopedErrors(state, merged, paths)
         }));
-        return Object.values(merged).flat().length === 0;
+        return settledFields(merged);
       }
-      const result = validateSync(schema, values);
+      const result = validateSyncLatched("", schema, values);
       const fullErrors = result.kind === "invalid" ? result.errors : emptyErrors;
+      const requestedErrors = pickScope(fullErrors, paths);
       store.setState((state) => ({
         ...state,
-        ...errorChannels(state, {
-          schemaErrors: reuseErrorRefs(
-            mergeScopedErrors(
-              state.schemaErrors,
-              pickScope(fullErrors, paths),
-              paths
-            ),
-            state.schemaErrors
-          ),
-          // A validation explicitly targeting these paths supersedes any
-          // server verdict on them.
-          serverErrors: omitScope(state.serverErrors, paths)
-        })
+        ...commitScopedErrors(state, requestedErrors, paths)
       }));
-      return Object.keys(fullErrors).every((k) => !inScopeOfAny(k, paths));
+      return settledFields(requestedErrors);
+    } catch (e) {
+      if (isAsyncRequiredError(e)) {
+        return { kind: "pending", promise: validateFieldsAsync(paths) };
+      }
+      throw e;
+    }
+  };
+  const asyncScopes = /* @__PURE__ */ new Set();
+  const validateSyncLatched = (key, scopeSchema, value) => {
+    try {
+      return validateSync(scopeSchema, value);
     } catch (e) {
-      if (isAsyncRequiredError(e)) return validateFieldsAsync(paths);
+      if (isAsyncRequiredError(e)) asyncScopes.add(key);
       throw e;
     }
   };
@@ -475,15 +542,6 @@ var createForm = (schema, options) => {
     const slot = slotAtPath(values, path);
     return slot.exists ? { kind: "parse", schema: sub, value: slot.value, viaSubschema: true } : { kind: "skip" };
   };
-  const scopedFieldErrors = (path) => {
-    const values = store.getState().values;
-    const scope = fieldScopeFor(path, values);
-    return scope.kind === "skip" ? emptyErrors : scopeSettledResult(
-      validateSync(scope.schema, scope.value),
-      path,
-      scope.viaSubschema
-    );
-  };
   const scopedFieldErrorsAsync = async (path, values) => {
     const scope = fieldScopeFor(path, values);
     return scope.kind === "skip" ? emptyErrors : scopeSettledResult(
@@ -496,17 +554,32 @@ var createForm = (schema, options) => {
     const messages = Object.values(scoped).flat();
     return messages.length === 0 ? { kind: "valid" } : { kind: "invalid", errors: messages };
   };
-  const commitFieldErrors = (state, scoped, path) => path === "" ? commitFullPass(state, scoped) : errorChannels(state, {
+  const settledFields = (scoped) => Object.keys(scoped).length === 0 ? { kind: "valid" } : { kind: "invalid", errors: scoped };
+  const settledFormResult = (result) => settledFields(result.kind === "invalid" ? result.errors : emptyErrors);
+  const commitScopedErrors = (state, scoped, paths) => errorChannels(state, {
     schemaErrors: reuseErrorRefs(
-      mergeScopedErrors(state.schemaErrors, scoped, [path]),
+      mergeScopedErrors(state.schemaErrors, scoped, paths),
       state.schemaErrors
     ),
-    serverErrors: omitScope(state.serverErrors, [path])
+    serverErrors: omitScope(state.serverErrors, paths)
   });
+  const commitFieldErrors = (state, scoped, path) => path === "" ? commitFullPass(state, scoped) : commitScopedErrors(state, scoped, [path]);
   const validateField = (path) => {
     warnMissingSchemaPath("validateField", path);
+    const scope = fieldScopeFor(path, store.getState().values);
+    if (scope.kind === "parse" && asyncScopes.has(scope.viaSubschema ? path : "")) {
+      return { kind: "pending", promise: validateFieldAsync(path) };
+    }
     try {
-      const scoped = scopedFieldErrors(path);
+      const scoped = scope.kind === "skip" ? emptyErrors : scopeSettledResult(
+        validateSyncLatched(
+          scope.viaSubschema ? path : "",
+          scope.schema,
+          scope.value
+        ),
+        path,
+        scope.viaSubschema
+      );
       store.setState((state) => ({
         ...state,
         ...commitFieldErrors(state, scoped, path)
@@ -559,10 +632,9 @@ var createForm = (schema, options) => {
     return result;
   };
   const validateFieldsAsync = async (paths) => {
-    if (paths.length === 0) return true;
+    if (paths.length === 0) return { kind: "valid" };
     if (paths.some((p) => p === "")) {
-      const result2 = await validateAsyncOnForm();
-      return result2.kind === "valid";
+      return settledFormResult(await validateAsyncOnForm());
     }
     const passes = new Map(paths.map((p) => [p, claimPass(p)]));
     const valuesAtStart = store.getState().values;
@@ -575,9 +647,8 @@ var createForm = (schema, options) => {
     }));
     const result = await validateAsync(schema, valuesAtStart);
     const fullErrors = result.kind === "invalid" ? result.errors : emptyErrors;
-    const requestedValid = Object.keys(fullErrors).every(
-      (k) => !inScopeOfAny(k, paths)
-    );
+    const requestedErrors = pickScope(fullErrors, paths);
+    const requested = settledFields(requestedErrors);
     const live = store.getState();
     const stillCurrent = paths.filter(
       (p) => sequences.get(p) === passes.get(p)
@@ -592,27 +663,21 @@ var createForm = (schema, options) => {
           )
         }));
       }
-      return requestedValid;
+      return requested;
     }
     store.setState((state) => ({
       ...state,
-      ...errorChannels(state, {
-        schemaErrors: reuseErrorRefs(
-          mergeScopedErrors(
-            state.schemaErrors,
-            pickScope(fullErrors, stillCurrent),
-            stillCurrent
-          ),
-          state.schemaErrors
-        ),
-        serverErrors: omitScope(state.serverErrors, stillCurrent)
-      }),
+      ...commitScopedErrors(
+        state,
+        pickScope(fullErrors, stillCurrent),
+        stillCurrent
+      ),
       isValidating: stillCurrent.reduce(
         (acc, p) => omitKey(acc, p),
         state.isValidating
       )
     }));
-    return requestedValid;
+    return requested;
   };
   const validateFieldAsync = async (path) => {
     warnMissingSchemaPath("validateFieldAsync", path);
@@ -662,12 +727,21 @@ var createForm = (schema, options) => {
       );
       return;
     }
+    const arr = Array.isArray(current) ? current : [];
+    const next = nextArray(arr);
+    const written = setAtPath(store.getState().values, path, next);
+    clearArrayOpsUnder(store, path, true);
+    if (Array.isArray(current) && getAtPath(written, path) === next) {
+      recordArrayOp(store, path, {
+        from: current,
+        to: next,
+        mapping: invertMapper(mapper, current.length, next.length)
+      });
+    }
     store.setState((state) => {
-      const live = getAtPath(state.values, path);
-      const arr = Array.isArray(live) ? live : [];
       return {
         ...state,
-        values: setAtPath(state.values, path, nextArray(arr)),
+        values: written,
         ...errorChannels(state, {
           schemaErrors: reKeyByArrayPath(state.schemaErrors, path, mapper),
           // Server entries on rows follow their rows through the index
@@ -808,24 +882,30 @@ var createForm = (schema, options) => {
         }
       });
     },
-    setValue: (path, value) => store.setState((state) => ({
-      ...state,
-      values: setAtPath(state.values, path, value),
-      ...errorChannels(state, {
-        serverErrors: releaseSpine(state.serverErrors, path)
-      })
-    })),
-    setValues: (next) => store.setState((state) => ({
-      ...state,
-      values: next,
-      ...errorChannels(state, {
-        serverErrors: releaseChangedSlices(
-          state.serverErrors,
-          state.values,
-          next
-        )
-      })
-    })),
+    setValue: (path, value) => {
+      clearArrayOpsUnder(store, path);
+      store.setState((state) => ({
+        ...state,
+        values: setAtPath(state.values, path, value),
+        ...errorChannels(state, {
+          serverErrors: releaseSpine(state.serverErrors, path)
+        })
+      }));
+    },
+    setValues: (next) => {
+      clearArrayOpsUnder(store, "");
+      store.setState((state) => ({
+        ...state,
+        values: next,
+        ...errorChannels(state, {
+          serverErrors: releaseChangedSlices(
+            state.serverErrors,
+            state.values,
+            next
+          )
+        })
+      }));
+    },
     setTouched: (path, touched = true) => store.setState((state) => ({
       ...state,
       touched: { ...state.touched, [path]: touched }
@@ -856,25 +936,32 @@ var createForm = (schema, options) => {
         })
       };
     }),
-    updateState: (updater) => store.setState((state) => {
-      const patch = updater(state);
-      if (Object.keys(patch).length === 0) return state;
-      if (patch.errors !== void 0 && patch.errors !== state.errors) {
-        console.warn(
-          "[formstand] `errors` is derived from schemaErrors/serverErrors \u2014 patch those channels instead; the direct `errors` patch is ignored."
-        );
+    updateState: (updater) => {
+      const valuesBefore = store.getState().values;
+      store.setState((state) => {
+        const patch = updater(state);
+        if (Object.keys(patch).length === 0) return state;
+        if (patch.errors !== void 0 && patch.errors !== state.errors) {
+          console.warn(
+            "[formstand] `errors` is derived from schemaErrors/serverErrors \u2014 patch those channels instead; the direct `errors` patch is ignored."
+          );
+        }
+        const next = { ...state, ...patch };
+        return {
+          ...next,
+          ...errorChannels(state, {
+            schemaErrors: next.schemaErrors,
+            serverErrors: next.serverErrors
+          })
+        };
+      });
+      if (store.getState().values !== valuesBefore) {
+        clearArrayOpsUnder(store, "");
       }
-      const next = { ...state, ...patch };
-      return {
-        ...next,
-        ...errorChannels(state, {
-          schemaErrors: next.schemaErrors,
-          serverErrors: next.serverErrors
-        })
-      };
-    }),
+    },
     adoptValues: (values) => {
       sequences.clear();
+      clearArrayOpsUnder(store, "");
       store.setState((state) => ({
         ...state,
         values,
@@ -892,6 +979,7 @@ var createForm = (schema, options) => {
     },
     reset: (nextInitial, resetOptions) => {
       sequences.clear();
+      clearArrayOpsUnder(store, "");
       store.setState((state) => {
         const init = nextInitial === void 0 ? state.initialValues : isPlainObject(state.initialValues) && isPlainObject(nextInitial) ? {
           ...state.initialValues,
@@ -913,23 +1001,33 @@ var createForm = (schema, options) => {
         };
       });
     },
-    resetField: (path) => store.setState((state) => ({
-      ...state,
-      values: setAtPath(
-        state.values,
-        path,
-        getAtPath(state.initialValues, path)
-      ),
-      // A runtime "" path scopes the whole form (the imperative surface is
-      // string-typed even though FieldPath excludes ""). Server entries
-      // follow the setValue release contract (releaseSpine).
-      ...errorChannels(state, {
-        schemaErrors: path === "" ? emptyErrors : omitScope(state.schemaErrors, [path]),
-        serverErrors: releaseSpine(state.serverErrors, path)
-      }),
-      touched: path === "" ? emptyBools : omitScope(state.touched, [path]),
-      isValidating: path === "" ? emptyBools : omitScope(state.isValidating, [path])
-    })),
+    resetField: (path) => {
+      const initialSlot = slotAtPath(
+        store.getState().initialValues,
+        path
+      );
+      if (!initialSlot.exists) {
+        console.warn(
+          `[formstand] resetField("${path}"): path has no initial value (e.g. an appended array row); value left unchanged, field state cleared.`
+        );
+      }
+      if (initialSlot.exists) {
+        clearArrayOpsUnder(store, path);
+      }
+      store.setState((state) => ({
+        ...state,
+        values: initialSlot.exists ? setAtPath(state.values, path, initialSlot.value) : state.values,
+        // A runtime "" path scopes the whole form (the imperative surface is
+        // string-typed even though FieldPath excludes ""). Server entries
+        // follow the setValue release contract (releaseSpine).
+        ...errorChannels(state, {
+          schemaErrors: path === "" ? emptyErrors : omitScope(state.schemaErrors, [path]),
+          serverErrors: releaseSpine(state.serverErrors, path)
+        }),
+        touched: path === "" ? emptyBools : omitScope(state.touched, [path]),
+        isValidating: path === "" ? emptyBools : omitScope(state.isValidating, [path])
+      }));
+    },
     validate,
     validateField,
     validateFields,
@@ -983,29 +1081,32 @@ var createForm = (schema, options) => {
       return dirtyPathsOf(state.values, state.initialValues, "");
     },
     snapshot: () => store.getState(),
-    restore: (snap) => store.setState(() => {
-      const schemaErrors = snap.schemaErrors ?? emptyErrors;
-      const serverErrors = snap.serverErrors ?? emptyErrors;
-      return {
-        ...snap,
-        schemaErrors,
-        serverErrors,
-        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. isSubmitting follows the same rule — a
-        // mid-submit snapshot restored later must not disable submit
-        // buttons forever, so it reflects the LIVE submit count instead of
-        // the snapshotted flag (a live pass's finally still resets it).
-        isValidating: emptyBools,
-        isValidatingForm: false,
-        isSubmitting: inFlight.count > 0
-      };
-    })
+    restore: (snap) => {
+      clearArrayOpsUnder(store, "");
+      store.setState(() => {
+        const schemaErrors = snap.schemaErrors ?? emptyErrors;
+        const serverErrors = snap.serverErrors ?? emptyErrors;
+        return {
+          ...snap,
+          schemaErrors,
+          serverErrors,
+          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. isSubmitting follows the same rule — a
+          // mid-submit snapshot restored later must not disable submit
+          // buttons forever, so it reflects the LIVE submit count instead of
+          // the snapshotted flag (a live pass's finally still resets it).
+          isValidating: emptyBools,
+          isValidatingForm: false,
+          isSubmitting: inFlight.count > 0
+        };
+      });
+    }
   });
 };
 
@@ -1175,15 +1276,7 @@ function useField(form, pathArg, options) {
       }, debounceMs);
       return;
     }
-    try {
-      form.validateField(path);
-    } catch (e) {
-      if (isAsyncRequiredError(e)) {
-        void form.validateFieldAsync(path);
-        return;
-      }
-      throw e;
-    }
+    form.validateField(path);
   }, [form, path, debounceMs]);
   const setValue = react.useCallback(
     (value) => {
@@ -1263,12 +1356,14 @@ function useVariantField(form, unionPath, field) {
     `${unionPath}.${field}`
   );
 }
-var EMPTY_ID_STATE = { items: [], ids: [], counter: 0 };
 var EMPTY_ITEMS = [];
+var mintNumbers = (needsMint) => new Map(
+  needsMint.flatMap((mint, i) => mint ? [i] : []).map((position, k) => [position, k + 1])
+);
 var reconcileIds = (prev, nextItems) => {
   if (prev.items === nextItems) return prev;
   if (prev.items.length === nextItems.length && prev.items.every((item, i) => Object.is(item, nextItems[i]))) {
-    return prev;
+    return { ...prev, items: nextItems };
   }
   const buckets = prev.items.reduce((acc, item, i) => {
     const bucket = acc.get(item);
@@ -1290,15 +1385,77 @@ var reconcileIds = (prev, nextItems) => {
     })
   );
   const reused = matchedIds.map((id, i) => id ?? leftoverAt.get(i) ?? null);
-  const mintCounts = reused.reduce((acc, id) => {
-    const count = acc[acc.length - 1] ?? 0;
-    return [...acc, id === null ? count + 1 : count];
-  }, []);
-  const minted = mintCounts[mintCounts.length - 1] ?? 0;
+  const mints = mintNumbers(reused.map((id) => id === null));
   const ids = reused.map(
-    (id, i) => id ?? `__zfa_${prev.counter + (mintCounts[i] ?? 0)}`
+    (id, i) => id ?? `${prev.prefix}${prev.counter + (mints.get(i) ?? 0)}`
+  );
+  return {
+    items: nextItems,
+    ids,
+    counter: prev.counter + mints.size,
+    prefix: prev.prefix
+  };
+};
+var mappedIdState = (prev, mapping, liveItems) => {
+  if (liveItems.length !== mapping.length) return null;
+  const aligned = mapping.every(
+    (src, i) => src === -1 ? true : prev.ids[src] !== void 0 && Object.is(liveItems[i], prev.items[src])
+  );
+  if (!aligned) return null;
+  const mints = mintNumbers(mapping.map((src) => src === -1));
+  const ids = mapping.map(
+    (src, i) => src === -1 ? `${prev.prefix}${prev.counter + (mints.get(i) ?? 0)}` : prev.ids[src]
   );
-  return { items: nextItems, ids, counter: prev.counter + minted };
+  return {
+    items: liveItems,
+    ids,
+    counter: prev.counter + mints.size,
+    prefix: prev.prefix
+  };
+};
+var MAX_ID_PATHS = 4096;
+var sharedIdEntries = /* @__PURE__ */ new WeakMap();
+var sharedIdEntry = (store, path) => {
+  const existingStore = sharedIdEntries.get(store);
+  const forStore = existingStore ?? { byPath: /* @__PURE__ */ new Map(), seq: 1 };
+  if (existingStore === void 0) sharedIdEntries.set(store, forStore);
+  const existing = forStore.byPath.get(path);
+  if (existing !== void 0) {
+    forStore.byPath.delete(path);
+    forStore.byPath.set(path, existing);
+    return existing;
+  }
+  const created = {
+    state: {
+      items: EMPTY_ITEMS,
+      ids: [],
+      counter: 0,
+      prefix: `__zfa_${forStore.seq}_`
+    }
+  };
+  forStore.seq += 1;
+  forStore.byPath.set(path, created);
+  if (forStore.byPath.size > MAX_ID_PATHS) {
+    const oldest = forStore.byPath.keys().next().value;
+    if (oldest !== void 0) forStore.byPath.delete(oldest);
+  }
+  return created;
+};
+var walkOps = (start, items, ops) => {
+  const walked = ops.reduce((acc, op) => {
+    const base = acc.items === op.from ? acc : reconcileIds(acc, op.from);
+    return mappedIdState(base, op.mapping, op.to) ?? base;
+  }, start);
+  return walked.items === items ? walked : reconcileIds(walked, items);
+};
+var deriveIds = (store, path, items) => {
+  const entry = sharedIdEntry(store, path);
+  if (entry.state.items === items) return entry.state;
+  const ops = arrayOpsFor(store, path);
+  if (ops.length > 0) clearArrayOps(store, path);
+  const next = walkOps(entry.state, items, ops);
+  entry.state = next;
+  return next;
 };
 function useFieldArray(form, pathArg) {
   const path = react$1.useStore(
@@ -1317,13 +1474,7 @@ function useFieldArray(form, pathArg) {
   );
   const items = slice.items;
   const error = slice.error;
-  const [idEntry, setIdEntry] = react.useState({ form, path, state: EMPTY_ID_STATE });
-  const base = idEntry.form === form && idEntry.path === path ? idEntry.state : { ...EMPTY_ID_STATE, counter: idEntry.state.counter };
-  const nextIdState = reconcileIds(base, items);
-  if (idEntry.form !== form || idEntry.path !== path || idEntry.state !== nextIdState) {
-    setIdEntry({ form, path, state: nextIdState });
-  }
-  const ids = nextIdState.ids;
+  const ids = deriveIds(form.store, path, items).ids;
   const push = react.useCallback(
     (item) => form.arrayPush(path, item),
     [form, path]
@@ -1433,7 +1584,8 @@ var createFormHooks = (form, name) => {
 };
 
 // src/react/inputProps.ts
-var ariaInvalid = (field) => field.error !== void 0 && field.error.length > 0 ? true : void 0;
+var hasFieldError = (error) => error !== void 0 && error.length > 0;
+var ariaInvalid = (field) => hasFieldError(field.error) ? true : void 0;
 var numberToInputText = (value) => value === void 0 || value === null || Number.isNaN(value) ? "" : String(value);
 var parseNumberText = (text) => {
   if (text.trim() === "") return { kind: "empty" };
@@ -1527,11 +1679,37 @@ var selectProps = (field) => ({
   },
   onBlur: field.onBlur
 });
-var hasError = (error) => error !== void 0 && error.length > 0;
+var useFieldA11y = (error) => {
+  const id = react.useId();
+  const errorId = `${id}-error`;
+  return {
+    id,
+    errorId,
+    describedBy: hasFieldError(error) ? errorId : void 0
+  };
+};
 var ErrorText = ({
   id,
   error
-}) => hasError(error) ? /* @__PURE__ */ jsxRuntime.jsx("span", { className: "zf-error", id, role: "alert", children: error?.[0] }) : null;
+}) => hasFieldError(error) ? /* @__PURE__ */ jsxRuntime.jsx("span", { className: "zf-error", id, role: "alert", children: error?.[0] }) : null;
+var FieldShell = ({
+  id,
+  errorId,
+  label,
+  error,
+  wrapLabel,
+  children
+}) => /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "zf-field", children: [
+  wrapLabel === true ? /* @__PURE__ */ jsxRuntime.jsxs("label", { htmlFor: id, className: "zf-label", children: [
+    children,
+    " ",
+    label
+  ] }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    label !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
+    children
+  ] }),
+  /* @__PURE__ */ jsxRuntime.jsx(ErrorText, { id: errorId, error })
+] });
 var TextField = ({
   form,
   path,
@@ -1541,25 +1719,29 @@ var TextField = ({
   autoComplete,
   ref
 }) => {
-  const id = react.useId();
-  const errorId = `${id}-error`;
   const field = useField(form, path);
-  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "zf-field", children: [
-    label !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
-    /* @__PURE__ */ jsxRuntime.jsx(
-      "input",
-      {
-        id,
-        ref,
-        ...textInputProps(field),
-        type,
-        placeholder,
-        autoComplete,
-        "aria-describedby": hasError(field.error) ? errorId : void 0
-      }
-    ),
-    /* @__PURE__ */ jsxRuntime.jsx(ErrorText, { id: errorId, error: field.error })
-  ] });
+  const a11y = useFieldA11y(field.error);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    FieldShell,
+    {
+      id: a11y.id,
+      errorId: a11y.errorId,
+      label,
+      error: field.error,
+      children: /* @__PURE__ */ jsxRuntime.jsx(
+        "input",
+        {
+          id: a11y.id,
+          ref,
+          ...textInputProps(field),
+          type,
+          placeholder,
+          autoComplete,
+          "aria-describedby": a11y.describedBy
+        }
+      )
+    }
+  );
 };
 var DateField = ({
   form,
@@ -1569,24 +1751,28 @@ var DateField = ({
   max,
   ref
 }) => {
-  const id = react.useId();
-  const errorId = `${id}-error`;
   const field = useField(form, path);
-  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "zf-field", children: [
-    label !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
-    /* @__PURE__ */ jsxRuntime.jsx(
-      "input",
-      {
-        id,
-        ref,
-        ...dateInputProps(field),
-        min,
-        max,
-        "aria-describedby": hasError(field.error) ? errorId : void 0
-      }
-    ),
-    /* @__PURE__ */ jsxRuntime.jsx(ErrorText, { id: errorId, error: field.error })
-  ] });
+  const a11y = useFieldA11y(field.error);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    FieldShell,
+    {
+      id: a11y.id,
+      errorId: a11y.errorId,
+      label,
+      error: field.error,
+      children: /* @__PURE__ */ jsxRuntime.jsx(
+        "input",
+        {
+          id: a11y.id,
+          ref,
+          ...dateInputProps(field),
+          min,
+          max,
+          "aria-describedby": a11y.describedBy
+        }
+      )
+    }
+  );
 };
 var IDLE_EDIT = { raw: null, pushed: void 0 };
 var useNumberInput = (field) => {
@@ -1600,7 +1786,7 @@ var useNumberInput = (field) => {
     name: field.path,
     value: raw ?? numberToInputText(field.value),
     inputMode: "decimal",
-    "aria-invalid": hasError(field.error) ? true : void 0,
+    "aria-invalid": hasFieldError(field.error) ? true : void 0,
     onChange: (e) => {
       const text = e.target.value;
       const parsed = parseNumberText(text);
@@ -1633,25 +1819,29 @@ var NumberField = ({
   placeholder,
   ref
 }) => {
-  const id = react.useId();
-  const errorId = `${id}-error`;
   const field = useField(form, path);
   const binding = useNumberInput(field);
-  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "zf-field", children: [
-    label !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
-    /* @__PURE__ */ jsxRuntime.jsx(
-      "input",
-      {
-        id,
-        ref,
-        type: "text",
-        ...binding,
-        placeholder,
-        "aria-describedby": hasError(field.error) ? errorId : void 0
-      }
-    ),
-    /* @__PURE__ */ jsxRuntime.jsx(ErrorText, { id: errorId, error: field.error })
-  ] });
+  const a11y = useFieldA11y(field.error);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    FieldShell,
+    {
+      id: a11y.id,
+      errorId: a11y.errorId,
+      label,
+      error: field.error,
+      children: /* @__PURE__ */ jsxRuntime.jsx(
+        "input",
+        {
+          id: a11y.id,
+          ref,
+          type: "text",
+          ...binding,
+          placeholder,
+          "aria-describedby": a11y.describedBy
+        }
+      )
+    }
+  );
 };
 var CheckboxField = ({
   form,
@@ -1659,25 +1849,27 @@ var CheckboxField = ({
   label,
   ref
 }) => {
-  const id = react.useId();
-  const errorId = `${id}-error`;
   const field = useField(form, path);
-  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "zf-field", children: [
-    /* @__PURE__ */ jsxRuntime.jsxs("label", { htmlFor: id, className: "zf-label", children: [
-      /* @__PURE__ */ jsxRuntime.jsx(
+  const a11y = useFieldA11y(field.error);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    FieldShell,
+    {
+      id: a11y.id,
+      errorId: a11y.errorId,
+      label,
+      error: field.error,
+      wrapLabel: true,
+      children: /* @__PURE__ */ jsxRuntime.jsx(
         "input",
         {
-          id,
+          id: a11y.id,
           ref,
           ...checkboxProps(field),
-          "aria-describedby": hasError(field.error) ? errorId : void 0
+          "aria-describedby": a11y.describedBy
         }
-      ),
-      " ",
-      label
-    ] }),
-    /* @__PURE__ */ jsxRuntime.jsx(ErrorText, { id: errorId, error: field.error })
-  ] });
+      )
+    }
+  );
 };
 var SelectField = ({
   form,
@@ -1687,33 +1879,39 @@ var SelectField = ({
   placeholder,
   ref
 }) => {
-  const id = react.useId();
-  const errorId = `${id}-error`;
   const field = useField(form, path);
+  const a11y = useFieldA11y(field.error);
+  const select = selectProps(field);
   const clearable = field.emptyValue === null;
-  const showEmptyOption = clearable || field.value === void 0 || field.value === null || placeholder !== void 0;
-  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "zf-field", children: [
-    label !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
-    /* @__PURE__ */ jsxRuntime.jsxs(
-      "select",
-      {
-        id,
-        ref,
-        ...selectProps(field),
-        "aria-describedby": hasError(field.error) ? errorId : void 0,
-        children: [
-          showEmptyOption ? /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", disabled: !clearable, children: placeholder ?? "" }) : null,
-          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}`)
-          ))
-        ]
-      }
-    ),
-    /* @__PURE__ */ jsxRuntime.jsx(ErrorText, { id: errorId, error: field.error })
-  ] });
+  const hasExplicitEmptyOption = options.some((opt) => opt.value === "");
+  const showEmptyOption = !hasExplicitEmptyOption && (clearable || select.value === "" || placeholder !== void 0);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    FieldShell,
+    {
+      id: a11y.id,
+      errorId: a11y.errorId,
+      label,
+      error: field.error,
+      children: /* @__PURE__ */ jsxRuntime.jsxs(
+        "select",
+        {
+          id: a11y.id,
+          ref,
+          ...select,
+          "aria-describedby": a11y.describedBy,
+          children: [
+            showEmptyOption ? /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", disabled: !clearable, children: placeholder ?? "" }) : null,
+            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}`)
+            ))
+          ]
+        }
+      )
+    }
+  );
 };
 
 // src/react/focusError.ts
@@ -1736,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(
@@ -1743,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;
@@ -1771,6 +1983,7 @@ exports.flattenIssues = flattenIssues;
 exports.focusField = focusField;
 exports.focusFirstError = focusFirstError;
 exports.getAtPath = getAtPath;
+exports.hasFieldError = hasFieldError;
 exports.isAsyncRequiredError = isAsyncRequiredError;
 exports.numberInputProps = numberInputProps;
 exports.numberToInputText = numberToInputText;
@@ -1791,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;