formstand 0.17.0 → 0.19.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { P as PathDepth, D as DefaultPathDepth, F as Form, C as CreateFormOptions, a as FieldValidationResult, S as SettledFieldValidationResult, b as FormState, c as FieldPath, d as FieldValue, E as ErrorMap } from './createForm-D0xLZH-Q.cjs';
-export { B as BoolMap, e as FieldSnapshot, f as FieldsValidationResult, I as InvalidSubmitHandler, R as ReadonlyStoreApi, g as ResetOptions, h as SettledFieldsValidationResult, i as SettledValidationResult, j as SubmitHandler, k as SubmitOptions, l as SubmitResult, V as ValidationMode, m as ValidationResult, n as ValidationTrigger, o as createForm, p as emptyValueForSchema, q as flattenIssues, r as isAsyncRequiredError, s as shouldValidateOn, v as validateAsync, t as validateSync } from './createForm-D0xLZH-Q.cjs';
+import { P as PathDepth, D as DefaultPathDepth, F as Form, C as CreateFormOptions, I as InvalidSubmitHandler, a as FieldValidationResult, S as SettledFieldValidationResult, b as FormState, c as FieldPath, d as FieldValue, E as ErrorMap } from './createForm-B73p1TgL.cjs';
+export { B as BoolMap, e as FieldSnapshot, f as FieldsValidationResult, R as ReadonlyStoreApi, g as ResetOptions, h as SettledFieldsValidationResult, i as SettledValidationResult, j as SubmitHandler, k as SubmitOptions, l as SubmitResult, V as ValidationMode, m as ValidationResult, n as ValidationTrigger, o as createForm, p as emptyValueForSchema, q as flattenIssues, r as isAsyncRequiredError, s as isClearableSchema, t as shouldValidateOn, v as validateAsync, u as validateSync } from './createForm-B73p1TgL.cjs';
 import { z } from 'zod';
 import * as react from 'react';
 import { ReactNode, ChangeEvent } from 'react';
@@ -23,7 +23,7 @@ type PersistOptions<TSchema extends z.ZodType> = Readonly<{
     apply?: "adopt" | "restore" | "manual";
 }>;
 type PersistHandle = Readonly<{
-    restore: () => boolean;
+    load: () => boolean;
     clear: () => void;
     dispose: () => void;
 }>;
@@ -33,6 +33,15 @@ declare const usePersistForm: <TSchema extends z.ZodType, D extends PathDepth =
 
 declare const useForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(schema: TSchema, options: CreateFormOptions<TSchema, D>) => Form<TSchema, D>;
 
+type FormActionHandler<TSchema extends z.ZodType> = (data: z.output<TSchema>, formData: FormData) => void | Promise<void>;
+type FormActionStateHandler<TSchema extends z.ZodType, S> = (prevState: S, data: z.output<TSchema>, formData: FormData) => S | Promise<S>;
+type FormActionOptions = Readonly<{
+    onInvalid?: InvalidSubmitHandler;
+    onError?: (error: unknown) => void;
+}>;
+declare const useFormAction: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, onValid: FormActionHandler<TSchema>, options?: FormActionOptions) => ((formData: FormData) => Promise<void>);
+declare const useFormActionState: <TSchema extends z.ZodType, S, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, action: FormActionStateHandler<TSchema, S>, initialState: S, options?: FormActionOptions) => [state: S, formAction: (formData: FormData) => void, isPending: boolean];
+
 type FormProviderProps<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = Readonly<{
     form: Form<TSchema, D>;
     children: ReactNode;
@@ -62,6 +71,7 @@ type UseFieldReturn<TValue> = Readonly<{
     value: TValue;
     initialValue: TValue;
     emptyValue: null | undefined;
+    clearable: boolean;
     error: readonly string[] | undefined;
     firstError: string | undefined;
     touched: boolean;
@@ -379,4 +389,4 @@ declare const dateInputProps: <T extends Date | null | undefined>(field: UseFiel
 declare const checkboxProps: <T extends boolean | null | undefined>(field: UseFieldReturn<T>) => CheckboxProps;
 declare const selectProps: <T extends string | null | undefined>(field: UseFieldReturn<T>) => SelectProps;
 
-export { type BoundUseField, type BoundUseFieldArray, type BoundUseFlag, type BoundUseSelector, CheckboxField, type CheckboxFieldProps, type CheckboxProps, CreateFormOptions, DateField, type DateFieldProps, type DateInputProps, DefaultPathDepth, ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, FieldPath, type FieldPathArg, type FieldRef, FieldValidationResult, FieldValue, Form, type FormContextApi, type FormHooks, type FormProviderProps, FormState, type FormStateApi, NumberField, type NumberFieldProps, type NumberInputBinding, type NumberInputProps, type ParsedDateText, type ParsedNumberText, PathDepth, type PathSegment, type PathsOf, type PersistHandle, type PersistOptions, type PersistStorage, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, SettledFieldValidationResult, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, type UseFieldsReturn, checkboxProps, createFormContext, createFormHooks, dateInputProps, dateToInputText, focusField, focusFirstError, getAtPath, hasFieldError, numberInputProps, numberToInputText, parseDateText, parseNumberText, parsePath, persistForm, selectProps, setAtPath, textInputProps, useField, useFieldArray, useFields, useForm, useFormError, useFormSelector, useFormSelectorShallow, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useNumberInput, usePersistForm, useSubmitCount, useVariantField };
+export { type BoundUseField, type BoundUseFieldArray, type BoundUseFlag, type BoundUseSelector, CheckboxField, type CheckboxFieldProps, type CheckboxProps, CreateFormOptions, DateField, type DateFieldProps, type DateInputProps, DefaultPathDepth, ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, FieldPath, type FieldPathArg, type FieldRef, FieldValidationResult, FieldValue, Form, type FormActionHandler, type FormActionOptions, type FormActionStateHandler, type FormContextApi, type FormHooks, type FormProviderProps, FormState, type FormStateApi, InvalidSubmitHandler, NumberField, type NumberFieldProps, type NumberInputBinding, type NumberInputProps, type ParsedDateText, type ParsedNumberText, PathDepth, type PathSegment, type PathsOf, type PersistHandle, type PersistOptions, type PersistStorage, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, SettledFieldValidationResult, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, type UseFieldsReturn, checkboxProps, createFormContext, createFormHooks, dateInputProps, dateToInputText, focusField, focusFirstError, getAtPath, hasFieldError, numberInputProps, numberToInputText, parseDateText, parseNumberText, parsePath, persistForm, selectProps, setAtPath, textInputProps, useField, useFieldArray, useFields, useForm, useFormAction, useFormActionState, useFormError, useFormSelector, useFormSelectorShallow, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useNumberInput, usePersistForm, useSubmitCount, useVariantField };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PathDepth, D as DefaultPathDepth, F as Form, C as CreateFormOptions, a as FieldValidationResult, S as SettledFieldValidationResult, b as FormState, c as FieldPath, d as FieldValue, E as ErrorMap } from './createForm-D0xLZH-Q.js';
-export { B as BoolMap, e as FieldSnapshot, f as FieldsValidationResult, I as InvalidSubmitHandler, R as ReadonlyStoreApi, g as ResetOptions, h as SettledFieldsValidationResult, i as SettledValidationResult, j as SubmitHandler, k as SubmitOptions, l as SubmitResult, V as ValidationMode, m as ValidationResult, n as ValidationTrigger, o as createForm, p as emptyValueForSchema, q as flattenIssues, r as isAsyncRequiredError, s as shouldValidateOn, v as validateAsync, t as validateSync } from './createForm-D0xLZH-Q.js';
+import { P as PathDepth, D as DefaultPathDepth, F as Form, C as CreateFormOptions, I as InvalidSubmitHandler, a as FieldValidationResult, S as SettledFieldValidationResult, b as FormState, c as FieldPath, d as FieldValue, E as ErrorMap } from './createForm-B73p1TgL.js';
+export { B as BoolMap, e as FieldSnapshot, f as FieldsValidationResult, R as ReadonlyStoreApi, g as ResetOptions, h as SettledFieldsValidationResult, i as SettledValidationResult, j as SubmitHandler, k as SubmitOptions, l as SubmitResult, V as ValidationMode, m as ValidationResult, n as ValidationTrigger, o as createForm, p as emptyValueForSchema, q as flattenIssues, r as isAsyncRequiredError, s as isClearableSchema, t as shouldValidateOn, v as validateAsync, u as validateSync } from './createForm-B73p1TgL.js';
 import { z } from 'zod';
 import * as react from 'react';
 import { ReactNode, ChangeEvent } from 'react';
@@ -23,7 +23,7 @@ type PersistOptions<TSchema extends z.ZodType> = Readonly<{
     apply?: "adopt" | "restore" | "manual";
 }>;
 type PersistHandle = Readonly<{
-    restore: () => boolean;
+    load: () => boolean;
     clear: () => void;
     dispose: () => void;
 }>;
@@ -33,6 +33,15 @@ declare const usePersistForm: <TSchema extends z.ZodType, D extends PathDepth =
 
 declare const useForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(schema: TSchema, options: CreateFormOptions<TSchema, D>) => Form<TSchema, D>;
 
+type FormActionHandler<TSchema extends z.ZodType> = (data: z.output<TSchema>, formData: FormData) => void | Promise<void>;
+type FormActionStateHandler<TSchema extends z.ZodType, S> = (prevState: S, data: z.output<TSchema>, formData: FormData) => S | Promise<S>;
+type FormActionOptions = Readonly<{
+    onInvalid?: InvalidSubmitHandler;
+    onError?: (error: unknown) => void;
+}>;
+declare const useFormAction: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, onValid: FormActionHandler<TSchema>, options?: FormActionOptions) => ((formData: FormData) => Promise<void>);
+declare const useFormActionState: <TSchema extends z.ZodType, S, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, action: FormActionStateHandler<TSchema, S>, initialState: S, options?: FormActionOptions) => [state: S, formAction: (formData: FormData) => void, isPending: boolean];
+
 type FormProviderProps<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = Readonly<{
     form: Form<TSchema, D>;
     children: ReactNode;
@@ -62,6 +71,7 @@ type UseFieldReturn<TValue> = Readonly<{
     value: TValue;
     initialValue: TValue;
     emptyValue: null | undefined;
+    clearable: boolean;
     error: readonly string[] | undefined;
     firstError: string | undefined;
     touched: boolean;
@@ -379,4 +389,4 @@ declare const dateInputProps: <T extends Date | null | undefined>(field: UseFiel
 declare const checkboxProps: <T extends boolean | null | undefined>(field: UseFieldReturn<T>) => CheckboxProps;
 declare const selectProps: <T extends string | null | undefined>(field: UseFieldReturn<T>) => SelectProps;
 
-export { type BoundUseField, type BoundUseFieldArray, type BoundUseFlag, type BoundUseSelector, CheckboxField, type CheckboxFieldProps, type CheckboxProps, CreateFormOptions, DateField, type DateFieldProps, type DateInputProps, DefaultPathDepth, ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, FieldPath, type FieldPathArg, type FieldRef, FieldValidationResult, FieldValue, Form, type FormContextApi, type FormHooks, type FormProviderProps, FormState, type FormStateApi, NumberField, type NumberFieldProps, type NumberInputBinding, type NumberInputProps, type ParsedDateText, type ParsedNumberText, PathDepth, type PathSegment, type PathsOf, type PersistHandle, type PersistOptions, type PersistStorage, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, SettledFieldValidationResult, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, type UseFieldsReturn, checkboxProps, createFormContext, createFormHooks, dateInputProps, dateToInputText, focusField, focusFirstError, getAtPath, hasFieldError, numberInputProps, numberToInputText, parseDateText, parseNumberText, parsePath, persistForm, selectProps, setAtPath, textInputProps, useField, useFieldArray, useFields, useForm, useFormError, useFormSelector, useFormSelectorShallow, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useNumberInput, usePersistForm, useSubmitCount, useVariantField };
+export { type BoundUseField, type BoundUseFieldArray, type BoundUseFlag, type BoundUseSelector, CheckboxField, type CheckboxFieldProps, type CheckboxProps, CreateFormOptions, DateField, type DateFieldProps, type DateInputProps, DefaultPathDepth, ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, FieldPath, type FieldPathArg, type FieldRef, FieldValidationResult, FieldValue, Form, type FormActionHandler, type FormActionOptions, type FormActionStateHandler, type FormContextApi, type FormHooks, type FormProviderProps, FormState, type FormStateApi, InvalidSubmitHandler, NumberField, type NumberFieldProps, type NumberInputBinding, type NumberInputProps, type ParsedDateText, type ParsedNumberText, PathDepth, type PathSegment, type PathsOf, type PersistHandle, type PersistOptions, type PersistStorage, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, SettledFieldValidationResult, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, type UseFieldsReturn, checkboxProps, createFormContext, createFormHooks, dateInputProps, dateToInputText, focusField, focusFirstError, getAtPath, hasFieldError, numberInputProps, numberToInputText, parseDateText, parseNumberText, parsePath, persistForm, selectProps, setAtPath, textInputProps, useField, useFieldArray, useFields, useForm, useFormAction, useFormActionState, useFormError, useFormSelector, useFormSelectorShallow, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useNumberInput, usePersistForm, useSubmitCount, useVariantField };

package/dist/index.js

@@ -3,7 +3,7 @@ export { getAtPath, parsePath, setAtPath, useFormSelector, useFormSelectorShallo
 import { createStore } from 'zustand/vanilla';
 import { devtools } from 'zustand/middleware';
 import { z } from 'zod';
-import { useRef, useEffect, useMemo, createContext, useCallback, useState, useContext, useId } from 'react';
+import { useRef, useEffect, useMemo, useCallback, useActionState, createContext, useState, useContext, useId } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { useStore } from 'zustand/react';
 import { useShallow } from 'zustand/react/shallow';
@@ -142,6 +142,7 @@ var emptyValueForSchema = (schema) => {
   };
   return walk(schema, false);
 };
+var isClearableSchema = (schema) => schema instanceof z.ZodOptional || schema instanceof z.ZodNullable || schema instanceof z.ZodDefault || schema instanceof z.ZodPrefault;
 var unwrapForWalk = (s) => {
   if (s instanceof z.ZodOptional || s instanceof z.ZodNullable) {
     return s.unwrap();
@@ -1063,7 +1064,7 @@ 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;
@@ -1108,7 +1109,7 @@ var persistForm = (form, options) => {
     }
   };
   if (apply !== "manual") {
-    restore();
+    load();
   }
   const unsubscribe = form.watchValues((values) => {
     cancelPending();
@@ -1122,7 +1123,7 @@ var persistForm = (form, options) => {
     }
   });
   return Object.freeze({
-    restore,
+    load,
     clear: () => {
       cancelPending();
       try {
@@ -1153,7 +1154,7 @@ var usePersistForm = (form, options) => {
   }, [form, key]);
   return useMemo(
     () => ({
-      restore: () => inner.current?.restore() ?? false,
+      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
@@ -1182,6 +1183,51 @@ var useForm = (schema, options) => {
   }, [form, schema, options.initialValues]);
   return form;
 };
+var warnUnobserved = (result, options, site) => {
+  if (result.kind === "error" && options?.onError === void 0 && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[formstand] action handler threw and nothing observed it \u2014 the form shows no feedback. Pass { onError } to ${site} (or setError inside your handler):`,
+      result.error
+    );
+  }
+};
+var useFormAction = (form, onValid, options) => {
+  const latest = useRef({ onValid, options });
+  useEffect(() => {
+    latest.current = { onValid, options };
+  });
+  return useCallback(
+    async (formData) => {
+      const { onValid: handler, options: opts } = latest.current;
+      const result = await form.submit(
+        (data) => handler(data, formData),
+        opts?.onInvalid,
+        opts?.onError === void 0 ? void 0 : { onError: opts.onError }
+      );
+      warnUnobserved(result, opts, "useFormAction");
+    },
+    [form]
+  );
+};
+var useFormActionState = (form, action, initialState, options) => {
+  const [state, formAction, isPending] = useActionState(
+    async (prevState, formData) => {
+      const prev = prevState;
+      const nextRef = { current: prev };
+      const result = await form.submit(
+        async (data) => {
+          nextRef.current = await action(prev, data, formData);
+        },
+        options?.onInvalid,
+        options?.onError === void 0 ? void 0 : { onError: options.onError }
+      );
+      warnUnobserved(result, options, "useFormActionState");
+      return nextRef.current;
+    },
+    initialState
+  );
+  return [state, formAction, isPending];
+};
 var createFormContext = () => {
   const Context = createContext(null);
   const Provider = ({ form, children }) => /* @__PURE__ */ jsx(Context.Provider, { value: form, children });
@@ -1217,12 +1263,17 @@ function useField(form, pathArg, options) {
   const path = slice.path;
   const formSchema = form.schema;
   const initialValue = slice.initialValue;
-  const emptyValue = useMemo(() => {
+  const { emptyValue, clearable } = 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 = useRef(null);
@@ -1308,6 +1359,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],
@@ -1322,7 +1374,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]
   );
 }
 
@@ -1657,9 +1709,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
 });
@@ -1733,9 +1783,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
 });
@@ -1942,7 +1990,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__ */ jsx(
@@ -2031,6 +2079,6 @@ var focusField = (path, root) => {
   return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(namedControls(scope).filter(isFocusCandidate)) : focusFirstOf(pathCandidates(scope, [path]).filter(isFocusCandidate));
 };
 
-export { CheckboxField, DateField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, createFormHooks, dateInputProps, dateToInputText, emptyValueForSchema, flattenIssues, focusField, focusFirstError, hasFieldError, isAsyncRequiredError, numberInputProps, numberToInputText, parseDateText, parseNumberText, persistForm, selectProps, shouldValidateOn, textInputProps, useField, useFieldArray, useFields, useForm, useFormError, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useNumberInput, usePersistForm, useSubmitCount, useVariantField, validateAsync, validateSync };
+export { CheckboxField, DateField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, createFormHooks, dateInputProps, dateToInputText, emptyValueForSchema, flattenIssues, focusField, focusFirstError, hasFieldError, isAsyncRequiredError, isClearableSchema, numberInputProps, numberToInputText, parseDateText, parseNumberText, persistForm, selectProps, shouldValidateOn, textInputProps, useField, useFieldArray, useFields, useForm, useFormAction, useFormActionState, useFormError, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useNumberInput, usePersistForm, useSubmitCount, useVariantField, validateAsync, validateSync };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map