formstand 0.16.0 → 0.18.0

package/dist/index.cjs

@@ -276,6 +276,7 @@ var emptyValueForSchema = (schema) => {
   };
   return walk(schema, false);
 };
+var isClearableSchema = (schema) => schema instanceof zod.z.ZodOptional || schema instanceof zod.z.ZodNullable || schema instanceof zod.z.ZodDefault || schema instanceof zod.z.ZodPrefault;
 var unwrapForWalk = (s) => {
   if (s instanceof zod.z.ZodOptional || s instanceof zod.z.ZodNullable) {
     return s.unwrap();
@@ -297,7 +298,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 +318,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 +723,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 +832,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 +940,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 +1090,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();
@@ -1178,13 +1198,16 @@ var persistForm = (form, options) => {
       return void 0;
     }
   };
-  const restore = () => {
+  const load = () => {
     try {
       const raw = storage === null ? null : storage.getItem(options.key);
       if (raw === null) return false;
       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;
@@ -1220,7 +1243,7 @@ var persistForm = (form, options) => {
     }
   };
   if (apply !== "manual") {
-    restore();
+    load();
   }
   const unsubscribe = form.watchValues((values) => {
     cancelPending();
@@ -1234,7 +1257,7 @@ var persistForm = (form, options) => {
     }
   });
   return Object.freeze({
-    restore,
+    load,
     clear: () => {
       cancelPending();
       try {
@@ -1248,6 +1271,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(
+    () => ({
+      load: () => inner.current?.load() ?? 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) {
@@ -1302,12 +1352,17 @@ function useField(form, pathArg, options) {
   const path = slice.path;
   const formSchema = form.schema;
   const initialValue = slice.initialValue;
-  const emptyValue = react.useMemo(() => {
+  const { emptyValue, clearable } = react.useMemo(() => {
     if (formSchema !== void 0) {
       const sub = fieldSchemaAtPath(formSchema, path);
-      if (sub !== null) return emptyValueForSchema(sub);
+      if (sub !== null) {
+        return {
+          emptyValue: emptyValueForSchema(sub),
+          clearable: isClearableSchema(sub)
+        };
+      }
     }
-    return initialValue === null ? null : void 0;
+    return initialValue === null ? { emptyValue: null, clearable: true } : { emptyValue: void 0, clearable: false };
   }, [formSchema, path, initialValue]);
   const debounceMs = options?.debounceMs;
   const debounceTimerRef = react.useRef(null);
@@ -1324,9 +1379,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;
     }
@@ -1389,6 +1448,7 @@ function useField(form, pathArg, options) {
       value: slice.value,
       initialValue: slice.initialValue,
       emptyValue,
+      clearable,
       error: slice.error,
       // `?.[0]` covers both the undefined channel and an empty array.
       firstError: slice.error?.[0],
@@ -1403,7 +1463,7 @@ function useField(form, pathArg, options) {
       validateAsync: validateAsync2,
       onBlur
     }),
-    [slice, emptyValue, setValue, setTouched, setError, clearError, validate, validateAsync2, onBlur]
+    [slice, emptyValue, clearable, setValue, setTouched, setError, clearError, validate, validateAsync2, onBlur]
   );
 }
 
@@ -1587,25 +1647,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,
@@ -1626,6 +1725,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) {
@@ -1651,7 +1763,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 {
@@ -1663,37 +1781,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/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();
-      });
-    }
-  };
-}
 
 // src/react/inputProps.ts
 var hasFieldError = (error) => error !== void 0 && error.length > 0;
@@ -1710,9 +1804,7 @@ var textInputProps = (field) => ({
   "aria-invalid": ariaInvalid(field),
   onChange: (e) => {
     const text = e.target.value;
-    field.setValue(
-      text === "" && field.emptyValue === null ? null : text
-    );
+    field.setValue(text === "" && field.clearable ? field.emptyValue : text);
   },
   onBlur: field.onBlur
 });
@@ -1723,6 +1815,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
     );
@@ -1785,9 +1878,7 @@ var selectProps = (field) => ({
   "aria-invalid": ariaInvalid(field),
   onChange: (e) => {
     const v = e.target.value;
-    field.setValue(
-      v === "" && field.emptyValue === null ? null : v
-    );
+    field.setValue(v === "" && field.clearable ? field.emptyValue : v);
   },
   onBlur: field.onBlur
 });
@@ -1994,7 +2085,7 @@ var SelectField = ({
   const field = useField(form, path);
   const a11y = useFieldA11y(field.error);
   const select = selectProps(field);
-  const clearable = field.emptyValue === null;
+  const clearable = field.clearable;
   const hasExplicitEmptyOption = options.some((opt) => opt.value === "");
   const showEmptyOption = !hasExplicitEmptyOption && (clearable || select.value === "" || placeholder !== void 0);
   return /* @__PURE__ */ jsxRuntime.jsx(
@@ -2101,6 +2192,7 @@ exports.focusFirstError = focusFirstError;
 exports.getAtPath = getAtPath;
 exports.hasFieldError = hasFieldError;
 exports.isAsyncRequiredError = isAsyncRequiredError;
+exports.isClearableSchema = isClearableSchema;
 exports.numberInputProps = numberInputProps;
 exports.numberToInputText = numberToInputText;
 exports.parseDateText = parseDateText;
@@ -2122,7 +2214,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;