@firtoz/router-toolkit 5.1.0 → 5.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/router-toolkit",
-	"version": "5.1.0",
+	"version": "5.3.0",
 	"description": "Type-safe React Router 7 framework mode helpers with enhanced fetching, form submission, and state management",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",

package/src/formAction.ts

@@ -1,8 +1,12 @@
 /**
  * @fileoverview Type-safe form action utility for React Router 7
  *
- * This module provides a wrapper for React Router actions that handles form data validation
- * using Zod schemas and provides structured error handling with MaybeError.
+ * This module provides a wrapper for React Router actions that handles form data and JSON
+ * validation using Zod schemas and provides structured error handling with MaybeError.
+ *
+ * Supports both:
+ * - **JSON requests** (`Content-Type: application/json`) - parsed with `request.json()` and validated directly
+ * - **FormData requests** (`multipart/form-data` or `application/x-www-form-urlencoded`) - parsed with `request.formData()` and validated with zod-form-data
  *
  * ## Overview
  *
@@ -56,17 +60,18 @@
  * function LoginForm() {
  *   const submitter = useDynamicSubmitter<typeof import("./auth.login")>("/auth/login");
  *
- *   // Option 1: Submit as JSON (recommended for programmatic use)
+ *   // Option 1: Submit as JSON (defaults to POST)
  *   const handleLoginJson = async () => {
- *     await submitter.submitJson(
- *       { email: "user@example.com", password: "secret123", rememberMe: true },
- *       { method: "POST" }
- *     );
+ *     await submitter.submitJson({
+ *       email: "user@example.com",
+ *       password: "secret123",
+ *       rememberMe: true,
+ *     });
  *   };
  *
- *   // Option 2: Use the Form component
+ *   // Option 2: Use the Form component (defaults to POST)
  *   return (
- *     <submitter.Form method="POST">
+ *     <submitter.Form>
  *       <input name="email" type="email" placeholder="Email" />
  *       <input name="password" type="password" placeholder="Password" />
  *       <label>
@@ -229,13 +234,18 @@ export interface FormActionConfig<
 }
 
 /**
- * Creates a type-safe form action handler that validates form data and provides structured error handling.
+ * Creates a type-safe form action handler that validates form data or JSON and provides structured error handling.
  *
  * This function wraps a React Router action to:
- * 1. Parse and validate form data using a Zod schema
- * 2. Call the provided handler with validated data
- * 3. Return structured errors for validation failures, handler errors, or unknown errors
- * 4. Preserve React Router Response objects (redirects, etc.) by re-throwing them
+ * 1. Detect content type (JSON vs FormData) from the request headers
+ * 2. Parse and validate the request body using a Zod schema
+ * 3. Call the provided handler with validated data
+ * 4. Return structured errors for validation failures, handler errors, or unknown errors
+ * 5. Preserve React Router Response objects (redirects, etc.) by re-throwing them
+ *
+ * **Content-Type handling:**
+ * - `application/json`: Uses `request.json()` and validates directly with the schema
+ * - `multipart/form-data` or `application/x-www-form-urlencoded`: Uses `request.formData()` and validates with zod-form-data
  *
  * @template TSchema - The Zod schema type for form validation
  * @template TResult - The success result type from the handler (defaults to undefined)
@@ -302,19 +312,25 @@ export const formAction = <
 		args: ActionArgs,
 	): Promise<MaybeError<TResult, FormActionError<TError, TSchema>>> => {
 		try {
-			const rawFormData = await args.request.formData();
-			const formData = await zfd.formData(schema).safeParseAsync(rawFormData);
+			const contentType = args.request.headers.get("Content-Type");
+			const isJson = contentType?.includes("application/json") ?? false;
+
+			const parseResult = isJson
+				? await schema.safeParseAsync(await args.request.json())
+				: await zfd
+						.formData(schema)
+						.safeParseAsync(await args.request.formData());
 
-			if (!formData.success) {
+			if (!parseResult.success) {
 				return fail({
 					type: "validation" as const,
 					error: z.treeifyError<z.infer<TSchema>>(
-						formData.error as z.core.$ZodError<z.infer<TSchema>>,
+						parseResult.error as z.core.$ZodError<z.infer<TSchema>>,
 					),
 				});
 			}
 
-			const handlerResult = await handler(args, formData.data);
+			const handlerResult = await handler(args, parseResult.data);
 			if (!handlerResult.success) {
 				return fail({
 					type: "handler" as const,

package/src/useDynamicSubmitter.tsx

@@ -55,11 +55,13 @@
  *   // submitter.state is "idle" | "loading" | "submitting"
  *
  *   // Option 1: Submit as JSON (recommended for programmatic submissions)
+ *   // Defaults to POST if no options provided
  *   const handleSubmitJson = async () => {
- *     await submitter.submitJson(
- *       { title: "My Post", content: "Post content here", published: true },
- *       { method: "POST" }
- *     );
+ *     await submitter.submitJson({
+ *       title: "My Post",
+ *       content: "Post content here",
+ *       published: true,
+ *     });
  *   };
  *
  *   // Option 2: Submit with FormData or SubmitTarget
@@ -67,9 +69,9 @@
  *     await submitter.submit(formData, { method: "POST" });
  *   };
  *
- *   // Option 3: Use the Form component
+ *   // Option 3: Use the Form component (defaults to POST)
  *   return (
- *     <submitter.Form method="POST">
+ *     <submitter.Form>
  *       <input name="title" />
  *       <textarea name="content" />
  *       <button type="submit">Save</button>
@@ -98,7 +100,7 @@
  *   }, [submitter.data]);
  *
  *   return (
- *     <submitter.Form method="POST">
+ *     <submitter.Form>
  *       <input name="email" type="email" />
  *       <input name="password" type="password" />
  *       <button disabled={submitter.state !== "idle"}>
@@ -160,6 +162,17 @@ type SubmitFunc<TModule extends RouteModule> = (
 	},
 ) => Promise<void>;
 
+/**
+ * Options for submitJson function.
+ * Method defaults to "POST" if not specified.
+ */
+type SubmitJsonOptions = Omit<
+	SubmitOptions,
+	"action" | "method" | "encType"
+> & {
+	method?: Exclude<SubmitOptions["method"], "GET">;
+};
+
 /**
  * Function type for submitting form data as JSON.
  *
@@ -167,33 +180,44 @@ type SubmitFunc<TModule extends RouteModule> = (
  * Automatically serializes the data as JSON. This is the recommended
  * approach for programmatic form submissions.
  *
+ * Options are optional and default to `{ method: "POST" }`.
+ *
  * @example
  * ```typescript
- * // Submit a plain object - fully type-safe
- * await submitter.submitJson(
- *   { email: "user@example.com", password: "secret123", rememberMe: true },
- *   { method: "POST" }
- * );
+ * // Submit a plain object - fully type-safe (defaults to POST)
+ * await submitter.submitJson({
+ *   email: "user@example.com",
+ *   password: "secret123",
+ *   rememberMe: true,
+ * });
+ *
+ * // Or specify a different method
+ * await submitter.submitJson(data, { method: "PUT" });
  * ```
  */
 type SubmitJsonFunc<TModule extends RouteModule> = (
 	data: z.infer<TModule["formSchema"]>,
-	options: Omit<SubmitOptions, "action" | "method" | "encType"> & {
-		method: Exclude<SubmitOptions["method"], "GET">;
-	},
+	options?: SubmitJsonOptions,
 ) => Promise<void>;
 
 /**
  * Form component type with pre-bound action URL.
  *
  * Renders a form element that automatically submits to the correct route.
+ * Method defaults to "POST" if not specified.
  *
  * @example
  * ```typescript
- * <submitter.Form method="POST">
+ * // Defaults to POST
+ * <submitter.Form>
  *   <input name="title" />
  *   <button type="submit">Submit</button>
  * </submitter.Form>
+ *
+ * // Or specify a different method
+ * <submitter.Form method="PUT">
+ *   ...
+ * </submitter.Form>
  * ```
  */
 type SubmitForm = (
@@ -201,7 +225,7 @@ type SubmitForm = (
 		FetcherFormProps & React.RefAttributes<HTMLFormElement>,
 		"action" | "method"
 	> & {
-		method: Exclude<SubmitOptions["method"], "GET">;
+		method?: Exclude<SubmitOptions["method"], "GET">;
 	},
 ) => React.ReactElement;
 
@@ -245,12 +269,12 @@ type SubmitForm = (
  *   { userId: "123" }
  * );
  *
- * // Submit using submitJson (type-safe, no FormData needed)
+ * // Submit using submitJson (type-safe, no FormData needed, defaults to POST)
  * await submitter.submitJson({
  *   displayName: "John Doe",
  *   email: "john@example.com",
  *   notifications: true,
- * }, { method: "POST" });
+ * });
  *
  * // Check the response
  * if (submitter.data?.success) {
@@ -269,9 +293,9 @@ export const useDynamicSubmitter = <TInfo extends RouteModule>(
 > & {
 	/** Submit with FormData or SubmitTarget (schema type & SubmitTarget) */
 	submit: SubmitFunc<TInfo>;
-	/** Submit a plain object as JSON (schema type only, recommended for programmatic use) */
+	/** Submit a plain object as JSON (schema type only, defaults to POST) */
 	submitJson: SubmitJsonFunc<TInfo>;
-	/** Pre-bound Form component with action URL already set */
+	/** Pre-bound Form component with action URL already set (defaults to POST) */
 	Form: SubmitForm;
 } => {
 	const url = useMemo(() => {
@@ -295,9 +319,10 @@ export const useDynamicSubmitter = <TInfo extends RouteModule>(
 	);
 
 	const submitJson: SubmitJsonFunc<TInfo> = useCallback(
-		(data, options) => {
+		(data, options = {}) => {
 			return fetcher.submit(data as SubmitTarget, {
 				...options,
+				method: options.method ?? "POST",
 				action: url,
 				encType: "application/json",
 			});
@@ -308,8 +333,8 @@ export const useDynamicSubmitter = <TInfo extends RouteModule>(
 	const OriginalForm = fetcher.Form;
 
 	const Form: SubmitForm = useCallback(
-		(props) => {
-			return <OriginalForm action={url} {...props} />;
+		({ method = "POST", ...props }) => {
+			return <OriginalForm action={url} method={method} {...props} />;
 		},
 		[url, OriginalForm],
 	);