@firtoz/router-toolkit 5.0.1 → 5.1.0

package/README.md

@@ -6,6 +6,8 @@
 
 Type-safe React Router 7 framework mode helpers with enhanced fetching, form submission, and state management for React Router 7 framework mode.
 
+> **⚠️ Early WIP Notice:** This package is in very early development and is **not production-ready**. It is TypeScript-only and may have breaking changes. While I (the maintainer) have limited time, I'm open to PRs for features, bug fixes, or additional support (like JS builds). Please feel free to try it out and contribute! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.
+
 ## Features
 
 - ✅ **Type-safe routing** - Full TypeScript support with React Router 7 framework mode
@@ -1175,7 +1177,7 @@ export const route: RoutePath<"/create-user"> = "/create-user";
 
 export const formSchema = z.object({
   name: z.string().min(1),
-  email: z.string().email(),
+  email: z.email(),
 });
 
 interface ValidationError {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/router-toolkit",
-	"version": "5.0.1",
+	"version": "5.1.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",
@@ -56,9 +56,9 @@
 	},
 	"peerDependencies": {
 		"@firtoz/maybe-error": "^1.5.1",
-		"react": "^19.2.0",
-		"react-router": "^7.9.4",
-		"zod": "^4.1.12"
+		"react": "^19.2.3",
+		"react-router": "^7.12.0",
+		"zod": "^4.3.5"
 	},
 	"engines": {
 		"node": ">=18.0.0"
@@ -70,10 +70,10 @@
 		"zod-form-data": "^3.0.1"
 	},
 	"devDependencies": {
-		"@testing-library/react": "^16.3.0",
+		"@testing-library/react": "^16.3.1",
 		"@types/jsdom": "^27.0.0",
-		"@types/react": "^19.2.2",
-		"bun-types": "^1.3.0",
-		"jsdom": "^27.0.1"
+		"@types/react": "^19.2.8",
+		"bun-types": "^1.3.6",
+		"jsdom": "^27.4.0"
 	}
 }

package/src/formAction.ts

@@ -4,26 +4,176 @@
  * This module provides a wrapper for React Router actions that handles form data validation
  * using Zod schemas and provides structured error handling with MaybeError.
  *
+ * ## Overview
+ *
+ * `formAction` is designed to work seamlessly with `useDynamicSubmitter` and `useDynamicFetcher`
+ * to provide end-to-end type safety for your React Router forms.
+ *
  * @example
+ * ### Basic Route Setup (`app/routes/auth.login.tsx`)
+ *
  * ```typescript
  * import { z } from "zod";
- * import { formAction } from "@firtoz/router-toolkit";
- * import { success } from "@firtoz/maybe-error";
+ * import { formAction, type RoutePath } from "@firtoz/router-toolkit";
+ * import { success, fail } from "@firtoz/maybe-error";
+ *
+ * // 1. Export the route path for type inference
+ * export const route: RoutePath<"/auth/login"> = "/auth/login";
  *
- * const schema = z.object({
- *   email: z.string().email(),
- *   password: z.string().min(8),
+ * // 2. Define your form schema with Zod
+ * export const formSchema = z.object({
+ *   email: z.string().email("Please enter a valid email"),
+ *   password: z.string().min(8, "Password must be at least 8 characters"),
+ *   rememberMe: z.boolean().optional().default(false),
  * });
  *
+ * // 3. Create the action with formAction
  * export const action = formAction({
- *   schema,
- *   handler: async (args, data) => {
- *     // data is fully typed based on the schema
- *     const user = await authenticateUser(data.email, data.password);
- *     return success(user);
+ *   schema: formSchema,
+ *   handler: async ({ request }, data) => {
+ *     // data is fully typed: { email: string, password: string, rememberMe: boolean }
+ *     try {
+ *       const user = await authenticateUser(data.email, data.password);
+ *       if (data.rememberMe) {
+ *         await createPersistentSession(user.id);
+ *       }
+ *       return success({ user });
+ *     } catch (error) {
+ *       return fail("Invalid email or password");
+ *     }
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ### Using with useDynamicSubmitter
+ *
+ * The route above can be used with `useDynamicSubmitter` for type-safe form submissions:
+ *
+ * ```tsx
+ * import { useDynamicSubmitter } from "@firtoz/router-toolkit";
+ *
+ * function LoginForm() {
+ *   const submitter = useDynamicSubmitter<typeof import("./auth.login")>("/auth/login");
+ *
+ *   // Option 1: Submit as JSON (recommended for programmatic use)
+ *   const handleLoginJson = async () => {
+ *     await submitter.submitJson(
+ *       { email: "user@example.com", password: "secret123", rememberMe: true },
+ *       { method: "POST" }
+ *     );
+ *   };
+ *
+ *   // Option 2: Use the Form component
+ *   return (
+ *     <submitter.Form method="POST">
+ *       <input name="email" type="email" placeholder="Email" />
+ *       <input name="password" type="password" placeholder="Password" />
+ *       <label>
+ *         <input name="rememberMe" type="checkbox" /> Remember me
+ *       </label>
+ *       <button disabled={submitter.state !== "idle"}>
+ *         {submitter.state === "submitting" ? "Logging in..." : "Login"}
+ *       </button>
+ *
+ *       {submitter.data && !submitter.data.success && (
+ *         <div className="error">
+ *           {submitter.data.error.type === "validation"
+ *             ? "Please check your inputs"
+ *             : submitter.data.error.type === "handler"
+ *               ? submitter.data.error.error // "Invalid email or password"
+ *               : "An unexpected error occurred"}
+ *         </div>
+ *       )}
+ *     </submitter.Form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ### Combined loader + action route (`app/routes/admin.posts.$id.tsx`)
+ *
+ * You can combine `formAction` with a loader for full CRUD operations:
+ *
+ * ```typescript
+ * import { z } from "zod";
+ * import { formAction, type RoutePath } from "@firtoz/router-toolkit";
+ * import { success, fail } from "@firtoz/maybe-error";
+ * import type { LoaderFunctionArgs } from "react-router";
+ *
+ * export const route: RoutePath<"/admin/posts/:id"> = "/admin/posts/:id";
+ *
+ * // Loader for fetching data (used with useDynamicFetcher)
+ * export const loader = async ({ params }: LoaderFunctionArgs) => {
+ *   const post = await db.posts.findUnique({ where: { id: params.id } });
+ *   return { post };
+ * };
+ *
+ * // Form schema for updates
+ * export const formSchema = z.object({
+ *   title: z.string().min(1, "Title is required"),
+ *   content: z.string().min(10, "Content must be at least 10 characters"),
+ *   published: z.boolean().optional().default(false),
+ * });
+ *
+ * // Action for handling form submissions (used with useDynamicSubmitter)
+ * export const action = formAction({
+ *   schema: formSchema,
+ *   handler: async ({ params }, data) => {
+ *     const updated = await db.posts.update({
+ *       where: { id: params.id },
+ *       data,
+ *     });
+ *     return success({ post: updated });
  *   },
  * });
  * ```
+ *
+ * @example
+ * ### Full CRUD component using both hooks
+ *
+ * ```tsx
+ * import { useDynamicFetcher, useDynamicSubmitter } from "@firtoz/router-toolkit";
+ * import { useEffect } from "react";
+ *
+ * function PostEditor({ postId }: { postId: string }) {
+ *   // Fetch post data
+ *   const fetcher = useDynamicFetcher<typeof import("./admin.posts.$id")>(
+ *     "/admin/posts/:id",
+ *     { id: postId }
+ *   );
+ *
+ *   // Submit updates
+ *   const submitter = useDynamicSubmitter<typeof import("./admin.posts.$id")>(
+ *     "/admin/posts/:id",
+ *     { id: postId }
+ *   );
+ *
+ *   useEffect(() => {
+ *     fetcher.load();
+ *   }, [fetcher.load]);
+ *
+ *   if (fetcher.state === "loading" && !fetcher.data) {
+ *     return <div>Loading...</div>;
+ *   }
+ *
+ *   const post = fetcher.data?.post;
+ *
+ *   return (
+ *     <submitter.Form method="PUT">
+ *       <input name="title" defaultValue={post?.title} />
+ *       <textarea name="content" defaultValue={post?.content} />
+ *       <label>
+ *         <input name="published" type="checkbox" defaultChecked={post?.published} />
+ *         Published
+ *       </label>
+ *       <button disabled={submitter.state !== "idle"}>
+ *         {submitter.state === "submitting" ? "Saving..." : "Save"}
+ *       </button>
+ *     </submitter.Form>
+ *   );
+ * }
+ * ```
  */
 
 import { fail, type MaybeError } from "@firtoz/maybe-error";

package/src/types/HrefArgs.ts

@@ -1,8 +1,23 @@
-import type { href } from "react-router";
 import type { RegisterPages } from "./RegisterPages";
 
-export type HrefArgs<T extends keyof RegisterPages> = Parameters<
-	typeof href<T>
-> extends [string, ...infer Rest]
-	? Rest
-	: [];
+// Helper types matching React Router's internal implementation
+type Equal<X, Y> =
+	(<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2
+		? true
+		: false;
+
+type ToArgs<Params extends Record<string, string | undefined>> =
+	Equal<
+		Params,
+		// biome-ignore lint/complexity/noBannedTypes: This is intentionally empty.
+		{}
+	> extends true
+		? []
+		: Partial<Params> extends Params
+			? [Params] | []
+			: [Params];
+
+// Matches React Router's Args type structure
+export type HrefArgs<T extends keyof RegisterPages> = ToArgs<
+	RegisterPages[T]["params"]
+>;

package/src/useCachedFetch.ts

@@ -19,8 +19,8 @@ export const useCachedFetch = <TInfo extends RouteWithLoaderModule>(
 } => {
 	// Generate URL using href, same as useDynamicFetcher
 	const url = useMemo(() => {
-		// biome-ignore lint/suspicious/noExplicitAny: Typechecks complain about this so we need to cast to any
-		return (href as any)(path, ...args);
+		// biome-ignore lint/suspicious/noExplicitAny: Intentional
+		return href(path, ...(args as any));
 	}, [path, args]);
 
 	// Use the generated URL as the cache key

package/src/useDynamicFetcher.ts

@@ -1,19 +1,227 @@
+/**
+ * @fileoverview Type-safe dynamic data fetching hook for React Router 7
+ *
+ * This module provides a hook that creates a type-safe fetcher for loading data
+ * from dynamic routes with full TypeScript inference for the loader response and route params.
+ *
+ * @example
+ * ### Route Setup (`app/routes/api.users.$userId.ts`)
+ *
+ * First, set up your route with the required exports:
+ *
+ * ```typescript
+ * import type { RoutePath } from "@firtoz/router-toolkit";
+ *
+ * // Export the route path for type inference
+ * export const route: RoutePath<"/api/users/:userId"> = "/api/users/:userId";
+ *
+ * // Define the loader with a typed return value
+ * export const loader = async ({ params }: LoaderFunctionArgs) => {
+ *   const user = await db.users.findUnique({ where: { id: params.userId } });
+ *   return {
+ *     user: {
+ *       id: user.id,
+ *       email: user.email,
+ *       displayName: user.displayName,
+ *       createdAt: user.createdAt.toISOString(),
+ *     },
+ *   };
+ * };
+ * ```
+ *
+ * @example
+ * ### Using the hook in a component
+ *
+ * ```tsx
+ * import { useDynamicFetcher } from "@firtoz/router-toolkit";
+ * import { useEffect } from "react";
+ *
+ * function UserProfile({ userId }: { userId: string }) {
+ *   // Type-safe fetcher with full inference
+ *   const fetcher = useDynamicFetcher<typeof import("./api.users.$userId")>(
+ *     "/api/users/:userId",
+ *     { userId }
+ *   );
+ *
+ *   // Load data on mount
+ *   useEffect(() => {
+ *     fetcher.load();
+ *   }, [fetcher.load]);
+ *
+ *   // fetcher.data is fully typed: { user: { id, email, displayName, createdAt } } | undefined
+ *   if (fetcher.state === "loading") {
+ *     return <div>Loading...</div>;
+ *   }
+ *
+ *   if (!fetcher.data) {
+ *     return <div>No user found</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <h1>{fetcher.data.user.displayName}</h1>
+ *       <p>{fetcher.data.user.email}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ### Loading with query parameters
+ *
+ * ```tsx
+ * function SearchResults() {
+ *   const fetcher = useDynamicFetcher<typeof import("./api.search")>("/api/search");
+ *
+ *   const handleSearch = (query: string, page: number) => {
+ *     // Pass query params to the load function
+ *     fetcher.load({ q: query, page: String(page) });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input onChange={(e) => handleSearch(e.target.value, 1)} />
+ *       {fetcher.data?.results.map((result) => (
+ *         <div key={result.id}>{result.title}</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ### Combining with useDynamicSubmitter for full CRUD
+ *
+ * You can use `useDynamicFetcher` alongside `useDynamicSubmitter` to create
+ * complete CRUD interfaces with type safety:
+ *
+ * ```tsx
+ * import { useDynamicFetcher, useDynamicSubmitter } from "@firtoz/router-toolkit";
+ *
+ * function PostEditor({ postId }: { postId: string }) {
+ *   // Fetch post data
+ *   const fetcher = useDynamicFetcher<typeof import("./api.posts.$postId")>(
+ *     "/api/posts/:postId",
+ *     { postId }
+ *   );
+ *
+ *   // Submit updates
+ *   const submitter = useDynamicSubmitter<typeof import("./api.posts.$postId")>(
+ *     "/api/posts/:postId",
+ *     { postId }
+ *   );
+ *
+ *   useEffect(() => {
+ *     fetcher.load();
+ *   }, [fetcher.load]);
+ *
+ *   const handleSave = async (title: string, content: string) => {
+ *     await submitter.submitJson({ title, content }, { method: "PUT" });
+ *     // Reload after save
+ *     fetcher.load();
+ *   };
+ *
+ *   if (!fetcher.data) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <form onSubmit={(e) => {
+ *       e.preventDefault();
+ *       const form = new FormData(e.currentTarget);
+ *       handleSave(form.get("title") as string, form.get("content") as string);
+ *     }}>
+ *       <input name="title" defaultValue={fetcher.data.post.title} />
+ *       <textarea name="content" defaultValue={fetcher.data.post.content} />
+ *       <button disabled={submitter.state !== "idle"}>
+ *         {submitter.state === "submitting" ? "Saving..." : "Save"}
+ *       </button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+
 import { useCallback, useMemo } from "react";
 import { href, useFetcher } from "react-router";
 import type { HrefArgs } from "./types/HrefArgs";
 import type { RouteWithLoaderModule } from "./types/RouteWithLoaderModule";
 
+/**
+ * Creates a type-safe fetcher for loading data from dynamic routes.
+ *
+ * This hook provides full TypeScript inference for:
+ * - Route parameters (from the route path)
+ * - Loader response type (from the route's loader export)
+ *
+ * @template TInfo - The route module type (use `typeof import("./route-file")`)
+ *
+ * @param path - The route path (must match the route's `route` export)
+ * @param args - Route parameters (if the route has dynamic segments like `:id`)
+ *
+ * @returns An extended fetcher object with:
+ * - `load` - Function to load data, optionally with query parameters
+ * - `data` - Response data from the loader (typed)
+ * - `state` - Fetcher state ("idle" | "loading" | "submitting")
+ * - All other useFetcher properties (except `submit`)
+ *
+ * @example
+ * ### Basic usage
+ *
+ * ```typescript
+ * // In your route file (app/routes/api.products.$productId.ts):
+ * export const route: RoutePath<"/api/products/:productId"> = "/api/products/:productId";
+ * export const loader = async ({ params }: LoaderFunctionArgs) => {
+ *   return { product: await getProduct(params.productId) };
+ * };
+ *
+ * // In your component:
+ * const fetcher = useDynamicFetcher<typeof import("./api.products.$productId")>(
+ *   "/api/products/:productId",
+ *   { productId: "abc123" }
+ * );
+ *
+ * useEffect(() => {
+ *   fetcher.load();
+ * }, [fetcher.load]);
+ *
+ * // fetcher.data is typed as { product: Product } | undefined
+ * ```
+ *
+ * @example
+ * ### With query parameters
+ *
+ * ```typescript
+ * const fetcher = useDynamicFetcher<typeof import("./api.search")>("/api/search");
+ *
+ * // Load with query params: /api/search?q=hello&limit=10
+ * fetcher.load({ q: "hello", limit: "10" });
+ * ```
+ */
 export const useDynamicFetcher = <TInfo extends RouteWithLoaderModule>(
 	path: TInfo["route"],
 	...args: TInfo["route"] extends "undefined"
 		? HrefArgs<"/">
 		: HrefArgs<TInfo["route"]>
 ): Omit<ReturnType<typeof useFetcher<TInfo["loader"]>>, "load" | "submit"> & {
+	/**
+	 * Load data from the route's loader.
+	 *
+	 * @param queryParams - Optional query parameters to append to the URL
+	 * @returns A promise that resolves when the load is complete
+	 *
+	 * @example
+	 * ```typescript
+	 * // Load without query params
+	 * fetcher.load();
+	 *
+	 * // Load with query params
+	 * fetcher.load({ page: "2", sort: "name" });
+	 * ```
+	 */
 	load: (queryParams?: Record<string, string>) => Promise<void>;
 } => {
 	const url = useMemo(() => {
-		// biome-ignore lint/suspicious/noExplicitAny: Typechecks complain about this so we need to cast to any
-		return (href as any)(path, ...args);
+		// biome-ignore lint/suspicious/noExplicitAny: Intentional
+		return href(path, ...(args as any));
 	}, [path, args]);
 
 	const fetcher = useFetcher<TInfo["loader"]>({

package/src/useDynamicSubmitter.tsx

@@ -1,3 +1,115 @@
+/**
+ * @fileoverview Type-safe dynamic form submission hook for React Router 7
+ *
+ * This module provides a hook that creates a type-safe fetcher for submitting forms
+ * to dynamic routes with full TypeScript inference for the form schema and route params.
+ *
+ * @example
+ * ### Route Setup (`app/routes/admin.posts.$id.tsx`)
+ *
+ * First, set up your route with the required exports:
+ *
+ * ```typescript
+ * import { z } from "zod";
+ * import { formAction, type RoutePath } from "@firtoz/router-toolkit";
+ * import { success, fail } from "@firtoz/maybe-error";
+ *
+ * // Export the route path for type inference
+ * export const route: RoutePath<"/admin/posts/:id"> = "/admin/posts/:id";
+ *
+ * // Define the form schema
+ * export const formSchema = z.object({
+ *   title: z.string().min(1, "Title is required"),
+ *   content: z.string().min(10, "Content must be at least 10 characters"),
+ *   published: z.boolean().optional().default(false),
+ * });
+ *
+ * // Create the action using formAction
+ * export const action = formAction({
+ *   schema: formSchema,
+ *   handler: async ({ request, params }, formData) => {
+ *     const postId = params.id;
+ *     const updated = await db.posts.update({
+ *       where: { id: postId },
+ *       data: formData,
+ *     });
+ *     return success(updated);
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ### Using the hook in a component
+ *
+ * ```tsx
+ * import { useDynamicSubmitter } from "@firtoz/router-toolkit";
+ *
+ * function EditPostForm({ postId }: { postId: string }) {
+ *   // Type-safe submitter with full inference
+ *   const submitter = useDynamicSubmitter<typeof import("./admin.posts.$id")>(
+ *     "/admin/posts/:id",
+ *     { id: postId }
+ *   );
+ *
+ *   // submitter.data is the typed response from the action
+ *   // submitter.state is "idle" | "loading" | "submitting"
+ *
+ *   // Option 1: Submit as JSON (recommended for programmatic submissions)
+ *   const handleSubmitJson = async () => {
+ *     await submitter.submitJson(
+ *       { title: "My Post", content: "Post content here", published: true },
+ *       { method: "POST" }
+ *     );
+ *   };
+ *
+ *   // Option 2: Submit with FormData or SubmitTarget
+ *   const handleSubmit = async (formData: FormData) => {
+ *     await submitter.submit(formData, { method: "POST" });
+ *   };
+ *
+ *   // Option 3: Use the Form component
+ *   return (
+ *     <submitter.Form method="POST">
+ *       <input name="title" />
+ *       <textarea name="content" />
+ *       <button type="submit">Save</button>
+ *     </submitter.Form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ### Handling responses
+ *
+ * ```tsx
+ * function LoginForm() {
+ *   const submitter = useDynamicSubmitter<typeof import("./auth.login")>("/auth/login");
+ *
+ *   useEffect(() => {
+ *     if (submitter.data?.success) {
+ *       // Handle success
+ *       console.log("Logged in as:", submitter.data.value.user.email);
+ *     } else if (submitter.data && !submitter.data.success) {
+ *       // Handle error
+ *       if (submitter.data.error.type === "validation") {
+ *         console.log("Validation errors:", submitter.data.error.error);
+ *       }
+ *     }
+ *   }, [submitter.data]);
+ *
+ *   return (
+ *     <submitter.Form method="POST">
+ *       <input name="email" type="email" />
+ *       <input name="password" type="password" />
+ *       <button disabled={submitter.state !== "idle"}>
+ *         {submitter.state === "submitting" ? "Logging in..." : "Login"}
+ *       </button>
+ *     </submitter.Form>
+ *   );
+ * }
+ * ```
+ */
+
 // biome-ignore lint/style/useImportType: We need to import React here.
 import React, { useCallback, useMemo } from "react";
 import {
@@ -12,12 +124,35 @@ import type { Func } from "./types/Func";
 import type { HrefArgs } from "./types/HrefArgs";
 import type { RegisterPages } from "./types/RegisterPages";
 
+/**
+ * Represents a route module with the required exports for useDynamicSubmitter.
+ *
+ * A valid route module must export:
+ * - `route`: The route path (e.g., "/admin/posts/:id")
+ * - `action`: The form action handler created with `formAction`
+ * - `formSchema`: The Zod schema for form validation
+ */
 type RouteModule = {
 	route: keyof RegisterPages;
 	action: Func;
 	formSchema: z.ZodType;
 };
 
+/**
+ * Function type for submitting form data with a SubmitTarget.
+ *
+ * Accepts the form schema data combined with SubmitTarget (FormData, HTMLFormElement, etc.)
+ * Use this when you have a FormData object or form element reference.
+ *
+ * @example
+ * ```typescript
+ * // With FormData
+ * submitter.submit(formData, { method: "POST" });
+ *
+ * // With form element reference
+ * submitter.submit(formRef.current, { method: "POST" });
+ * ```
+ */
 type SubmitFunc<TModule extends RouteModule> = (
 	target: z.infer<TModule["formSchema"]> & SubmitTarget,
 	options: Omit<SubmitOptions, "action" | "method" | "encType"> & {
@@ -25,6 +160,42 @@ type SubmitFunc<TModule extends RouteModule> = (
 	},
 ) => Promise<void>;
 
+/**
+ * Function type for submitting form data as JSON.
+ *
+ * Accepts only the inferred form schema type (plain object).
+ * Automatically serializes the data as JSON. This is the recommended
+ * approach for programmatic form submissions.
+ *
+ * @example
+ * ```typescript
+ * // Submit a plain object - fully type-safe
+ * await submitter.submitJson(
+ *   { email: "user@example.com", password: "secret123", rememberMe: true },
+ *   { method: "POST" }
+ * );
+ * ```
+ */
+type SubmitJsonFunc<TModule extends RouteModule> = (
+	data: z.infer<TModule["formSchema"]>,
+	options: Omit<SubmitOptions, "action" | "method" | "encType"> & {
+		method: Exclude<SubmitOptions["method"], "GET">;
+	},
+) => Promise<void>;
+
+/**
+ * Form component type with pre-bound action URL.
+ *
+ * Renders a form element that automatically submits to the correct route.
+ *
+ * @example
+ * ```typescript
+ * <submitter.Form method="POST">
+ *   <input name="title" />
+ *   <button type="submit">Submit</button>
+ * </submitter.Form>
+ * ```
+ */
 type SubmitForm = (
 	props: Omit<
 		FetcherFormProps & React.RefAttributes<HTMLFormElement>,
@@ -34,6 +205,59 @@ type SubmitForm = (
 	},
 ) => React.ReactElement;
 
+/**
+ * Creates a type-safe fetcher for submitting forms to dynamic routes.
+ *
+ * This hook provides full TypeScript inference for:
+ * - Route parameters (from the route path)
+ * - Form data schema (from the route's formSchema export)
+ * - Action response type (from the route's action export)
+ *
+ * @template TInfo - The route module type (use `typeof import("./route-file")`)
+ *
+ * @param path - The route path (must match the route's `route` export)
+ * @param args - Route parameters (if the route has dynamic segments like `:id`)
+ *
+ * @returns An extended fetcher object with:
+ * - `submit` - Submit with FormData/SubmitTarget (includes schema type)
+ * - `submitJson` - Submit a plain object as JSON (schema type only)
+ * - `Form` - Pre-bound form component
+ * - `data` - Response data from the action (typed)
+ * - `state` - Fetcher state ("idle" | "loading" | "submitting")
+ * - All other useFetcher properties
+ *
+ * @example
+ * ### Basic usage with route parameters
+ *
+ * ```typescript
+ * // In your route file (app/routes/users.$userId.settings.tsx):
+ * export const route: RoutePath<"/users/:userId/settings"> = "/users/:userId/settings";
+ * export const formSchema = z.object({
+ *   displayName: z.string().min(2),
+ *   email: z.string().email(),
+ *   notifications: z.boolean().default(true),
+ * });
+ * export const action = formAction({ schema: formSchema, handler: ... });
+ *
+ * // In your component:
+ * const submitter = useDynamicSubmitter<typeof import("./users.$userId.settings")>(
+ *   "/users/:userId/settings",
+ *   { userId: "123" }
+ * );
+ *
+ * // Submit using submitJson (type-safe, no FormData needed)
+ * await submitter.submitJson({
+ *   displayName: "John Doe",
+ *   email: "john@example.com",
+ *   notifications: true,
+ * }, { method: "POST" });
+ *
+ * // Check the response
+ * if (submitter.data?.success) {
+ *   console.log("Settings updated!");
+ * }
+ * ```
+ */
 export const useDynamicSubmitter = <TInfo extends RouteModule>(
 	path: TInfo["route"],
 	...args: TInfo["route"] extends "undefined"
@@ -43,12 +267,16 @@ export const useDynamicSubmitter = <TInfo extends RouteModule>(
 	ReturnType<typeof useFetcher<TInfo["action"]>>,
 	"load" | "submit" | "Form"
 > & {
+	/** Submit with FormData or SubmitTarget (schema type & SubmitTarget) */
 	submit: SubmitFunc<TInfo>;
+	/** Submit a plain object as JSON (schema type only, recommended for programmatic use) */
+	submitJson: SubmitJsonFunc<TInfo>;
+	/** Pre-bound Form component with action URL already set */
 	Form: SubmitForm;
 } => {
 	const url = useMemo(() => {
-		// biome-ignore lint/suspicious/noExplicitAny: Typechecks complain about this so we need to cast to any
-		return (href as any)(path, ...args);
+		// biome-ignore lint/suspicious/noExplicitAny: Intentional
+		return href(path, ...(args as any));
 	}, [path, args]);
 
 	const fetcher = useFetcher<TInfo["action"]>({
@@ -57,7 +285,6 @@ export const useDynamicSubmitter = <TInfo extends RouteModule>(
 
 	const submit: SubmitFunc<TInfo> = useCallback(
 		(target, options) => {
-			// console.log("Submitting form to", url, target, options);
 			return fetcher.submit(target, {
 				...options,
 				action: url,
@@ -67,6 +294,17 @@ export const useDynamicSubmitter = <TInfo extends RouteModule>(
 		[fetcher.submit, url],
 	);
 
+	const submitJson: SubmitJsonFunc<TInfo> = useCallback(
+		(data, options) => {
+			return fetcher.submit(data as SubmitTarget, {
+				...options,
+				action: url,
+				encType: "application/json",
+			});
+		},
+		[fetcher.submit, url],
+	);
+
 	const OriginalForm = fetcher.Form;
 
 	const Form: SubmitForm = useCallback(
@@ -79,6 +317,7 @@ export const useDynamicSubmitter = <TInfo extends RouteModule>(
 	return {
 		...fetcher,
 		submit,
+		submitJson,
 		Form,
 	};
 };