formstand 0.15.2 → 0.17.0

package/dist/index.cjs

@@ -297,7 +297,7 @@ var schemaHasPath = (schema, path) => {
     if (head === void 0) return true;
     if (s instanceof zod.z.ZodObject) {
       const shape = s.shape;
-      const child = shape[String(head)];
+      const child = Object.hasOwn(shape, String(head)) ? shape[String(head)] : void 0;
       if (child !== void 0) return walk(child, rest, budget - 1);
       const catchall = s.def.catchall;
       return catchall !== void 0 && !(catchall instanceof zod.z.ZodNever);
@@ -317,7 +317,7 @@ var fieldSchemaAtPath = (schema, path) => parsePath(path).reduce((current, segme
   if (current === null || hasChecks(current)) return null;
   if (current instanceof zod.z.ZodObject && typeof segment === "string") {
     const shape = current.shape;
-    return shape[segment] ?? null;
+    return Object.hasOwn(shape, segment) ? shape[segment] ?? null : null;
   }
   if (current instanceof zod.z.ZodArray && typeof segment === "number") {
     return current.element;
@@ -722,7 +722,7 @@ var createForm = (schema, options) => {
   };
   const applyArrayOp = (path, nextArray, mapper, indexInBounds) => {
     const current = getAtPath(store.getState().values, path);
-    if (current !== void 0 && !Array.isArray(current)) {
+    if (current !== void 0 && current !== null && !Array.isArray(current)) {
       console.warn(
         `[formstand] array op on "${path}" but the value at that path is not an array (got ${typeof current}). Operation skipped.`
       );
@@ -831,6 +831,7 @@ var createForm = (schema, options) => {
       try {
         await onValid(result.data);
       } catch (error) {
+        submitOptions?.onError?.(error);
         return { kind: "error", error };
       }
       return { kind: "valid", data: result.data };
@@ -938,6 +939,17 @@ var createForm = (schema, options) => {
       ...state,
       ...errorChannels(state, { serverErrors: errors })
     })),
+    addErrors: (errors) => store.setState((state) => ({
+      ...state,
+      ...errorChannels(state, {
+        serverErrors: Object.entries(errors).reduce(
+          // Computed keys throughout, so a server field named
+          // "__proto__" lands as an own property like everywhere else.
+          (acc, [key, list]) => list === void 0 || list.length === 0 ? omitKey(acc, key) : { ...acc, [key]: list },
+          state.serverErrors
+        )
+      })
+    })),
     clearErrors: (path) => store.setState((state) => {
       const scrub = (map) => path === void 0 ? emptyErrors : omitScope(map, [path]);
       return {
@@ -1077,7 +1089,14 @@ var createForm = (schema, options) => {
     ),
     handleSubmit: (onValid, onInvalid, opts) => async (event) => {
       event?.preventDefault();
-      return submit(onValid, onInvalid, opts);
+      const result = await submit(onValid, onInvalid, opts);
+      if (result.kind === "error" && opts?.onError === void 0 && process.env.NODE_ENV !== "production") {
+        console.warn(
+          "[formstand] submit handler threw and nothing observed it \u2014 the form shows no feedback. Pass { onError } to handleSubmit (or setError inside your handler):",
+          result.error
+        );
+      }
+      return result;
     },
     diff: () => {
       const state = store.getState();
@@ -1185,6 +1204,9 @@ var persistForm = (form, options) => {
       const parsed = JSON.parse(raw);
       const versioned = options.version !== void 0 && typeof parsed === "object" && parsed !== null && "__v" in parsed;
       if (options.version !== void 0 && !versioned) return false;
+      if (options.version === void 0 && typeof parsed === "object" && parsed !== null && Object.hasOwn(parsed, "__v") && Object.hasOwn(parsed, "values")) {
+        return false;
+      }
       const wrapper = parsed;
       if (versioned && wrapper.__v !== options.version) return false;
       if (versioned && wrapper.values === void 0) return false;
@@ -1248,6 +1270,33 @@ var persistForm = (form, options) => {
     }
   });
 };
+var usePersistForm = (form, options) => {
+  const inner = react.useRef(null);
+  const latestOptions = react.useRef(options);
+  react.useEffect(() => {
+    latestOptions.current = options;
+  });
+  const key = options.key;
+  react.useEffect(() => {
+    const handle = persistForm(form, latestOptions.current);
+    inner.current = handle;
+    return () => {
+      inner.current = null;
+      handle.dispose();
+    };
+  }, [form, key]);
+  return react.useMemo(
+    () => ({
+      restore: () => inner.current?.restore() ?? false,
+      clear: () => inner.current?.clear(),
+      // dispose stops THIS component's watching early; the effect cleanup
+      // still runs its own dispose harmlessly (persistForm's dispose is
+      // idempotent by construction — it only cancels and unsubscribes).
+      dispose: () => inner.current?.dispose()
+    }),
+    []
+  );
+};
 var useForm = (schema, options) => {
   const formRef = react.useRef(null);
   if (formRef.current === null) {
@@ -1324,9 +1373,13 @@ function useField(form, pathArg, options) {
       if (debounceTimerRef.current !== null) {
         clearTimeout(debounceTimerRef.current);
       }
+      const scheduled = getAtPath(form.store.getState().values, path);
       debounceTimerRef.current = setTimeout(() => {
-        void form.validateFieldAsync(path);
         debounceTimerRef.current = null;
+        const state = form.store.getState();
+        if (state.values === state.initialValues) return;
+        if (!Object.is(getAtPath(state.values, path), scheduled)) return;
+        void form.validateFieldAsync(path);
       }, debounceMs);
       return;
     }
@@ -1390,6 +1443,8 @@ function useField(form, pathArg, options) {
       initialValue: slice.initialValue,
       emptyValue,
       error: slice.error,
+      // `?.[0]` covers both the undefined channel and an empty array.
+      firstError: slice.error?.[0],
       touched: slice.touched,
       dirty: slice.dirty,
       isValidating: slice.isValidating,
@@ -1585,25 +1640,64 @@ function useFieldArray(form, pathArg) {
     })),
     [items, ids]
   );
+  const setError = react.useCallback(
+    // Same string-shorthand normalization as useField.setError, so custom
+    // implementations typed for readonly string[] never receive a bare
+    // string.
+    (errors) => form.setError?.(path, typeof errors === "string" ? [errors] : errors),
+    [form, path]
+  );
+  const clearError = react.useCallback(() => form.clearErrors?.(path), [form, path]);
   return react.useMemo(
     () => ({
+      path,
       fields,
       items,
       length: items.length,
       error,
+      firstError: error?.[0],
+      setError,
+      clearError,
       push,
       remove,
       insert,
       move,
       swap
     }),
-    [fields, items, error, push, remove, insert, move, swap]
+    [path, fields, items, error, setError, clearError, push, remove, insert, move, swap]
   );
 }
 var useFormError = (form) => react$1.useStore(
   form.store,
   shallow.useShallow((state) => state.errors[""])
 );
+function useFormValues(form) {
+  return react$1.useStore(form.store, (state) => state.values);
+}
+
+// src/react/useFields.ts
+function useFields(form, paths) {
+  const fields = paths.map(
+    (path) => (
+      // eslint-disable-next-line react-hooks/rules-of-hooks -- a fixed hook count by the stable-arity contract above; each element must be a REAL UseFieldReturn so it spreads into the prop builders
+      useField(form, path)
+    )
+  );
+  const merged = [...new Set(fields.flatMap((field) => field.error ?? []))];
+  return {
+    fields,
+    error: merged.length > 0 ? merged : void 0,
+    firstError: merged[0],
+    touched: fields.some((field) => field.touched),
+    dirty: fields.some((field) => field.dirty),
+    isValidating: fields.some((field) => field.isValidating),
+    onBlur: () => {
+      fields.forEach((field) => {
+        field.onBlur();
+      });
+    }
+  };
+}
 function useIsDirty(form, path) {
   return react$1.useStore(
     form.store,
@@ -1624,6 +1718,19 @@ function useIsValid(form, path) {
     return true;
   });
 }
+function useIsValidating(form, path) {
+  return react$1.useStore(form.store, (state) => {
+    if (path === void 0 || path === "") {
+      if (state.isValidatingForm) return true;
+    }
+    for (const k in state.isValidating) {
+      if (state.isValidating[k] === true && (path === void 0 || path === "" || isPathOrChild(k, path))) {
+        return true;
+      }
+    }
+    return false;
+  });
+}
 var useIsSubmitting = (form) => react$1.useStore(form.store, (state) => state.isSubmitting);
 var useSubmitCount = (form) => react$1.useStore(form.store, (state) => state.submitCount);
 function useFormSelector(form, selector) {
@@ -1649,7 +1756,13 @@ var createFormHooks = (form, name) => {
   const useBoundError = () => useFormError(structural);
   const useBoundIsDirty = (path) => useIsDirty(structural, path);
   const useBoundIsValid = (path) => useIsValid(structural, path);
+  const useBoundIsValidating = (path) => useIsValidating(structural, path);
   const useBoundIsSubmitting = () => useIsSubmitting(structural);
+  const useBoundValues = () => useFormValues(structural);
+  const useBoundFields = (paths) => useFields(
+    structural,
+    paths
+  );
   const useBoundSubmitCount = () => useSubmitCount(structural);
   const prefix = capitalize(name ?? "");
   return {
@@ -1661,13 +1774,13 @@ var createFormHooks = (form, name) => {
     [`use${prefix}Error`]: useBoundError,
     [`use${prefix}IsDirty`]: useBoundIsDirty,
     [`use${prefix}IsValid`]: useBoundIsValid,
+    [`use${prefix}IsValidating`]: useBoundIsValidating,
     [`use${prefix}IsSubmitting`]: useBoundIsSubmitting,
-    [`use${prefix}SubmitCount`]: useBoundSubmitCount
+    [`use${prefix}SubmitCount`]: useBoundSubmitCount,
+    [`use${prefix}Values`]: useBoundValues,
+    [`use${prefix}Fields`]: useBoundFields
   };
 };
-function useFormValues(form) {
-  return react$1.useStore(form.store, (state) => state.values);
-}
 
 // src/react/inputProps.ts
 var hasFieldError = (error) => error !== void 0 && error.length > 0;
@@ -1697,6 +1810,7 @@ var numberInputProps = (field) => ({
   "aria-invalid": ariaInvalid(field),
   onChange: (e) => {
     const parsed = parseNumberText(e.target.value);
+    if (parsed.kind === "invalid") return;
     field.setValue(
       parsed.kind === "number" ? parsed.value : field.emptyValue
     );
@@ -2087,6 +2201,7 @@ exports.shouldValidateOn = shouldValidateOn;
 exports.textInputProps = textInputProps;
 exports.useField = useField;
 exports.useFieldArray = useFieldArray;
+exports.useFields = useFields;
 exports.useForm = useForm;
 exports.useFormError = useFormError;
 exports.useFormSelector = useFormSelector;
@@ -2095,7 +2210,9 @@ exports.useFormValues = useFormValues;
 exports.useIsDirty = useIsDirty;
 exports.useIsSubmitting = useIsSubmitting;
 exports.useIsValid = useIsValid;
+exports.useIsValidating = useIsValidating;
 exports.useNumberInput = useNumberInput;
+exports.usePersistForm = usePersistForm;
 exports.useSubmitCount = useSubmitCount;
 exports.useVariantField = useVariantField;
 exports.validateAsync = validateAsync;