@firtoz/router-toolkit 5.4.0 → 5.5.1

package/README.md

@@ -283,16 +283,21 @@ export default function ContactForm() {
 
 Run multiple submissions to the same action in parallel, each tracked independently. No single fetcher; each call returns `{ id, promise }` and adds an entry to `operations` with `submittedData` (for optimistic UI) and `data` when done.
 
+- **`submitJson(data)`** — POST JSON; `submittedData` is the payload you send.
+- **`submitFormData(formData, submittedData?)`** — POST multipart/form-data (e.g. file uploads). Optional `submittedData` is a serializable object for the operations list (e.g. `{ type: "upload", label: "photo.jpg" }`); FormData/File are not stored in state.
+
 ```tsx
 import { useConcurrentDynamicSubmitter } from '@firtoz/router-toolkit';
 
 function UploadList() {
-  const { operations, submitJson } = useConcurrentDynamicSubmitter<
+  const { operations, submitFormData } = useConcurrentDynamicSubmitter<
     typeof import("./api.upload")
   >("/api/upload");
 
-  const handleUpload = (file: { name: string; size: number }) => {
-    submitJson({ fileName: file.name, size: file.size });
+  const handleUpload = (file: File) => {
+    const fd = new FormData();
+    fd.set("file", file);
+    submitFormData(fd, { type: "upload", label: file.name });
   };
 
   return (
@@ -300,7 +305,7 @@ function UploadList() {
       {Object.values(operations).map((op) => (
         <li key={op.id}>
           {op.status === "pending" && (
-            <Skeleton>{op.submittedData.fileName}</Skeleton>
+            <Skeleton>{(op.submittedData as { label?: string }).label}</Skeleton>
           )}
           {op.status === "done" && (
             <span>Saved: {op.data?.id}</span>
@@ -315,8 +320,9 @@ function UploadList() {
 }
 ```
 
-- **`operations`**: `Record<string, Operation<T>>` — each operation has `id`, `status` (`"pending"` | `"done"` | `"error"`), `submittedData` (payload sent), and when done `data` (action response).
-- **`submitJson(data)`**: returns `{ id, promise }`; use `id` to look up in `operations`, `promise` to await.
+- **`operations`**: `Record<string, Operation<T>>` — each operation has `id`, `status` (`"pending"` | `"done"` | `"error"`), `submittedData` (payload or display object), and when done `data` (action response).
+- **`submitJson(data)`**: returns `{ id, promise }`.
+- **`submitFormData(formData, submittedData?)`**: returns `{ id, promise }`; `submittedData` defaults to `{}` and is used only for display in the operations list.
 
 ### `useFetcherStateChanged`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/router-toolkit",
-	"version": "5.4.0",
+	"version": "5.5.1",
 	"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/useConcurrentDynamicSubmitter.tsx

@@ -12,12 +12,14 @@
  * const a = submitJson({ fileId: "1", name: "a.pdf" });
  * const b = submitJson({ fileId: "2", name: "b.pdf" });
  *
- * // Map operations: show submittedData optimistically (skeleton/list), then response when done
+ * // FormData: pass serializable submittedData for display (no File/FormData in state)
+ * submitFormData(formData, { type: "upload", label: "photo.jpg" });
+ * submitFormData(convertFormData, { type: "convert", label: "anim.gif" });
+ * // Map operations: op.submittedData for labels, op.data when done
  * {Object.values(operations).map((op) => (
  *   <div key={op.id}>
- *     {op.status === "pending" && <Skeleton />}
+ *     {op.status === "pending" && <Skeleton>{op.submittedData.label}</Skeleton>}
  *     {op.status === "done" && <Item data={op.data} />}
- *     <span>{op.submittedData.name}</span>
  *   </div>
  * ))}
  * ```
@@ -54,7 +56,7 @@ export type Operation<TResponse, TFormData = unknown> = {
 	error?: unknown;
 };
 
-/** Result of submitJson: id to look up in operations, promise to await */
+/** Result of submitJson / submitFormData: id to look up in operations, promise to await */
 export type SubmitJsonResult<T> = {
 	id: string;
 	promise: Promise<T>;
@@ -64,9 +66,17 @@ type SubmitJsonOptions = {
 	method?: "POST" | "PUT" | "PATCH" | "DELETE";
 };
 
+/** Optional serializable payload for FormData submissions (for display in operations list; FormData/File are not stored in state). */
+export type FormDataSubmittedData = Record<string, unknown>;
+
+/** Options for submitFormData (e.g. Accept: application/json so the action returns JSON instead of redirecting). */
+export type SubmitFormDataOptions = {
+	headers?: HeadersInit;
+	method?: "POST" | "PUT" | "PATCH" | "DELETE";
+};
+
 /**
  * Submits JSON to the action URL via fetch and returns the parsed JSON.
- * Used so we can run N requests in parallel without N fetchers.
  */
 async function submitJsonToAction<T>(
 	actionUrl: string,
@@ -87,6 +97,29 @@ async function submitJsonToAction<T>(
 	return json;
 }
 
+/**
+ * Submits FormData to the action URL. No Content-Type header — browser sets multipart/form-data with boundary.
+ * Optional headers (e.g. Accept: application/json) let the action return JSON instead of redirecting.
+ */
+async function submitFormDataToAction<T>(
+	actionUrl: string,
+	formData: FormData,
+	options: SubmitFormDataOptions & { fetchFn?: typeof fetch },
+): Promise<T> {
+	const { method = "POST", headers, fetchFn = fetch } = options;
+	const res = await fetchFn(actionUrl, {
+		method,
+		...(headers && { headers }),
+		body: formData,
+	});
+	if (!res.ok) {
+		const text = await res.text();
+		throw new Error(`Action failed: ${res.status} ${text}`);
+	}
+	const json = (await res.json()) as T;
+	return json;
+}
+
 /**
  * Hook for multiple concurrent submissions to a dynamic route action.
  * Each submission gets an id and appears in `operations` as pending → done (or error).
@@ -95,7 +128,7 @@ async function submitJsonToAction<T>(
  * @template TInfo - Route module type (e.g. `typeof import("./api.upload")`)
  * @param path - Route path
  * @param args - Route params if path has segments
- * @returns operations map (id → Operation), submitJson (returns { id, promise })
+ * @returns operations map (id → Operation), submitJson, submitFormData (each returns { id, promise })
  */
 export function useConcurrentDynamicSubmitter<TInfo extends RouteModule>(
 	path: TInfo["route"],
@@ -105,27 +138,38 @@ export function useConcurrentDynamicSubmitter<TInfo extends RouteModule>(
 ): {
 	operations: Record<
 		string,
-		Operation<ActionResult<TInfo>, z.infer<TInfo["formSchema"]>>
+		Operation<
+			ActionResult<TInfo>,
+			z.infer<TInfo["formSchema"]> | FormDataSubmittedData
+		>
 	>;
 	submitJson: (
 		data: z.infer<TInfo["formSchema"]>,
 		options?: SubmitJsonOptions,
 	) => SubmitJsonResult<ActionResult<TInfo>>;
+	submitFormData: (
+		formData: FormData,
+		submittedData?: FormDataSubmittedData,
+		options?: SubmitFormDataOptions,
+	) => SubmitJsonResult<ActionResult<TInfo>>;
 } {
 	const actionUrl = useMemo(() => {
 		// biome-ignore lint/suspicious/noExplicitAny: Intentional
 		return href(path, ...(args as any));
 	}, [path, args]);
 
-	type FormData = z.infer<TInfo["formSchema"]>;
-	type Op = Operation<ActionResult<TInfo>, FormData>;
+	type JsonFormData = z.infer<TInfo["formSchema"]>;
+	type Op = Operation<
+		ActionResult<TInfo>,
+		JsonFormData | FormDataSubmittedData
+	>;
 
 	const nextIdRef = useRef(0);
 	const [operations, setOperations] = useState<Record<string, Op>>({});
 
 	const submitJson = useCallback(
 		(
-			data: FormData,
+			data: JsonFormData,
 			options: SubmitJsonOptions = {},
 		): SubmitJsonResult<ActionResult<TInfo>> => {
 			const id = `op-${++nextIdRef.current}`;
@@ -169,5 +213,52 @@ export function useConcurrentDynamicSubmitter<TInfo extends RouteModule>(
 		[actionUrl],
 	);
 
-	return { operations, submitJson };
+	const submitFormData = useCallback(
+		(
+			formData: FormData,
+			submittedData: FormDataSubmittedData = {},
+			options: SubmitFormDataOptions = {},
+		): SubmitJsonResult<ActionResult<TInfo>> => {
+			const id = `op-${++nextIdRef.current}`;
+			setOperations((prev) => ({
+				...prev,
+				[id]: { id, status: "pending", submittedData },
+			}));
+
+			const promise = submitFormDataToAction<ActionResult<TInfo>>(
+				actionUrl,
+				formData,
+				options,
+			)
+				.then((responseData) => {
+					setOperations((prev) => ({
+						...prev,
+						[id]: {
+							id,
+							status: "done",
+							submittedData,
+							data: responseData,
+						},
+					}));
+					return responseData;
+				})
+				.catch((error) => {
+					setOperations((prev) => ({
+						...prev,
+						[id]: {
+							id,
+							status: "error",
+							submittedData,
+							error,
+						},
+					}));
+					throw error;
+				});
+
+			return { id, promise };
+		},
+		[actionUrl],
+	);
+
+	return { operations, submitJson, submitFormData };
 }