feat(react): support hook-level defaultValues overrides

.changeset/rare-eels-juggle.md

@@ -0,0 +1,6 @@
+---
+"@tanstack-isomorphic-form/core": patch
+"@tanstack-isomorphic-form/react": patch
+---
+
+Allow `useIsomorphicForm(loaderData, options)` in the React package to accept hook-level `defaultValues`, using those values to seed idle form state for a specific hook instance while preserving the existing sanitizer behavior.

libs/react/README.md

@@ -158,13 +158,19 @@ Represents an unexpected exception thrown while running the form action or loade
 - `formDataOptions`: optional parsing delimiters for nested keys
 - `returnedValueSanitizer`: optional function to normalize values stored in `formState`
 
-### `useIsomorphicForm(loaderData)`
+### `useIsomorphicForm(loaderData, options?)`
 
 Turns loader data into:
 
 - `formProps`: props to spread onto the `<form>`
 - `formState`: reactive state representing the current form lifecycle
 
+Hook options:
+
+- `defaultValues`: optional initial values for this hook instance; these seed `formState.values` and take precedence over defaults passed to the loader, which themselves take precedence over defaults configured on `createIsomorphicForm`
+- `onSuccess`: optional callback invoked after a successful action
+- `onError`: optional callback invoked for form-level errors and unexpected failures
+
 ### `formState`
 
 `formState.status` can be:

libs/react/src/form-hook.ts

@@ -46,21 +46,19 @@ type IsomorphicFormHookOptions<
 
 export const createIsomorphicFormHook =
   <const TSchema extends FormDataSchema, const TActionFn extends FormAction<TSchema>>({
-    defaultValues,
     formDataExtractor,
     actionFn,
     returnedValueSanitizer,
     schema,
   }: {
-    defaultValues?: InferFormDataSchemaExtract<TSchema> | undefined;
     formDataExtractor: FormDataExtractor<TSchema>;
     schema: TSchema;
     returnedValueSanitizer?: ValueSanitizer<TSchema> | undefined;
     actionFn: TActionFn;
   }): IsomorphicFormHook<TSchema, TActionFn> =>
   <const TActionUrl extends string>(
     { actionUrl, state }: Awaited<FormLoaderReturn<TSchema, TActionFn, TActionUrl>>,
-    { onError, onSuccess }: IsomorphicFormHookOptions<TSchema, TActionFn> = {},
+    { defaultValues, onError, onSuccess }: IsomorphicFormHookOptions<TSchema, TActionFn> = {},
   ) =>
     useIsomorphicForm({
       actionFn,
@@ -103,7 +101,12 @@ const useIsomorphicForm = <
 }): IsomorphicFormHookReturn<TSchema, TActionFn, TActionUrl> => {
   const navigate = useNavigate();
   const [formState, setFormState] = useState(
-    state.status === "idle" && defaultValues ? { ...state, values: defaultValues } : state,
+    state.status === "idle" && defaultValues
+      ? {
+          ...state,
+          values: returnedValueSanitizer ? returnedValueSanitizer(defaultValues) : defaultValues,
+        }
+      : state,
   );
   const submitRef = useRef(false);
 

libs/react/src/isomorphic-form.ts

@@ -41,7 +41,6 @@ export const createIsomorphicForm = <
     }),
     useIsomorphicForm: createIsomorphicFormHook({
       actionFn,
-      defaultValues,
       formDataExtractor,
       returnedValueSanitizer,
       schema,