@firtoz/router-toolkit 8.0.1 → 9.0.1

package/dist/useDynamicSubmitter.d.ts

@@ -1,5 +1,6 @@
-import React from 'react';
+import * as react_router from 'react-router';
 import { useFetcher, SubmitTarget, SubmitOptions, FetcherFormProps } from 'react-router';
+import React from 'react';
 import { z } from 'zod';
 import { HrefArgs } from './types/HrefArgs.js';
 import { RouteWithActionModule } from './types/RouteWithActionModule.js';
@@ -7,119 +8,277 @@ import './types/RegisterPages.js';
 import './types/Func.js';
 
 /**
- * @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)
- *   // Defaults to POST if no options provided
- *   const handleSubmitJson = async () => {
- *     await submitter.submitJson({
- *       title: "My Post",
- *       content: "Post content here",
- *       published: true,
- *     });
- *   };
- *
- *   // Option 2: Submit with FormData or SubmitTarget
- *   const handleSubmit = async (formData: FormData) => {
- *     await submitter.submit(formData, { method: "POST" });
- *   };
- *
- *   // Option 3: Use the Form component (defaults to POST)
- *   return (
- *     <submitter.Form>
- *       <input name="title" />
- *       <textarea name="content" />
- *       <button type="submit">Save</button>
- *     </submitter.Form>
- *   );
- * }
- * ```
+ * An augmentable interface users can modify in their app-code to opt into
+ * future-flag-specific types
+ */
+interface Future {
+}
+type MiddlewareEnabled = Future extends {
+    v8_middleware: infer T extends boolean;
+} ? T : false;
+/**
+ * A context instance used as the key for the `get`/`set` methods of a
+ * {@link RouterContextProvider}. Accepts an optional default
+ * value to be returned if no value has been set.
+ */
+interface RouterContext<T = unknown> {
+    defaultValue?: T;
+}
+/**
+ * Provides methods for writing/reading values in application context in a
+ * type-safe way. Primarily for usage with [middleware](../../how-to/middleware).
  *
  * @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>
- *       <input name="email" type="email" />
- *       <input name="password" type="password" />
- *       <button disabled={submitter.state !== "idle"}>
- *         {submitter.state === "submitting" ? "Logging in..." : "Login"}
- *       </button>
- *     </submitter.Form>
- *   );
- * }
- * ```
+ * import {
+ *   createContext,
+ *   RouterContextProvider
+ * } from "react-router";
+ *
+ * const userContext = createContext<User | null>(null);
+ * const contextProvider = new RouterContextProvider();
+ * contextProvider.set(userContext, getUser());
+ * //                               ^ Type-safe
+ * const user = contextProvider.get(userContext);
+ * //    ^ User
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ */
+declare class RouterContextProvider {
+    #private;
+    /**
+     * Create a new `RouterContextProvider` instance
+     * @param init An optional initial context map to populate the provider with
+     */
+    constructor(init?: Map<RouterContext, unknown>);
+    /**
+     * Access a value from the context. If no value has been set for the context,
+     * it will return the context's `defaultValue` if provided, or throw an error
+     * if no `defaultValue` was set.
+     * @param context The context to get the value for
+     * @returns The value for the context, or the context's `defaultValue` if no
+     * value was set
+     */
+    get<T>(context: RouterContext<T>): T;
+    /**
+     * Set a value for the context. If the context already has a value set, this
+     * will overwrite it.
+     *
+     * @param context The context to set the value for
+     * @param value The value to set for the context
+     * @returns {void}
+     */
+    set<C extends RouterContext>(context: C, value: C extends RouterContext<infer T> ? T : never): void;
+}
+type DefaultContext = MiddlewareEnabled extends true ? Readonly<RouterContextProvider> : any;
+/**
+ * @private
+ * Arguments passed to route loader/action functions.  Same for now but we keep
+ * this as a private implementation detail in case they diverge in the future.
+ */
+interface DataFunctionArgs<Context> {
+    /** A {@link https://developer.mozilla.org/en-US/docs/Web/API/Request Fetch Request instance} which you can use to read headers (like cookies, and {@link https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams URLSearchParams} from the request. */
+    request: Request;
+    /**
+     * A URL instance representing the application location being navigated to or fetched.
+     * Without `future.unstable_passThroughRequests` enabled, this matches `request.url`.
+     * With `future.unstable_passThroughRequests` enabled, this is a normalized
+     * URL with React-Router-specific implementation details removed (`.data`
+     * suffixes, `index`/`_routes` search params).
+     * The URL includes the origin from the request for convenience.
+     */
+    unstable_url: URL;
+    /**
+     * Matched un-interpolated route pattern for the current path (i.e., /blog/:slug).
+     * Mostly useful as a identifier to aggregate on for logging/tracing/etc.
+     */
+    unstable_pattern: string;
+    /**
+     * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the current route.
+     * @example
+     * // app/routes.ts
+     * route("teams/:teamId", "./team.tsx"),
+     *
+     * // app/team.tsx
+     * export function loader({
+     *   params,
+     * }: Route.LoaderArgs) {
+     *   params.teamId;
+     *   //        ^ string
+     * }
+     */
+    params: Params;
+    /**
+     * This is the context passed in to your server adapter's getLoadContext() function.
+     * It's a way to bridge the gap between the adapter's request/response API with your React Router app.
+     * It is only applicable if you are using a custom server adapter.
+     */
+    context: Context;
+}
+/**
+ * Arguments passed to loader functions
  */
+interface LoaderFunctionArgs<Context = DefaultContext> extends DataFunctionArgs<Context> {
+}
+/**
+ * Arguments passed to action functions
+ */
+interface ActionFunctionArgs<Context = DefaultContext> extends DataFunctionArgs<Context> {
+}
+/**
+ * The parameters that were parsed from the URL path.
+ */
+type Params<Key extends string = string> = {
+    readonly [key in Key]: string | undefined;
+};
+declare class DataWithResponseInit<D> {
+    type: string;
+    data: D;
+    init: ResponseInit | null;
+    constructor(data: D, init?: ResponseInit);
+}
 
+type Serializable = undefined | null | boolean | string | symbol | number | Array<Serializable> | {
+    [key: PropertyKey]: Serializable;
+} | bigint | Date | URL | RegExp | Error | Map<Serializable, Serializable> | Set<Serializable> | Promise<Serializable>;
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type Func = (...args: any[]) => unknown;
+
+/**
+ * A brand that can be applied to a type to indicate that it will serialize
+ * to a specific type when transported to the client from a loader.
+ * Only use this if you have additional serialization/deserialization logic
+ * in your application.
+ */
+type unstable_SerializesTo<T> = {
+    unstable__ReactRouter_SerializesTo: [T];
+};
+
+type Serialize<T> = T extends unstable_SerializesTo<infer To> ? To : T extends Serializable ? T : T extends (...args: any[]) => unknown ? undefined : T extends Promise<infer U> ? Promise<Serialize<U>> : T extends Map<infer K, infer V> ? Map<Serialize<K>, Serialize<V>> : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<Serialize<K>, Serialize<V>> : T extends Set<infer U> ? Set<Serialize<U>> : T extends ReadonlySet<infer U> ? ReadonlySet<Serialize<U>> : T extends [] ? [] : T extends readonly [infer F, ...infer R] ? [Serialize<F>, ...Serialize<R>] : T extends Array<infer U> ? Array<Serialize<U>> : T extends readonly unknown[] ? readonly Serialize<T[number]>[] : T extends Record<any, any> ? {
+    [K in keyof T]: Serialize<T[K]>;
+} : undefined;
+type VoidToUndefined<T> = Equal<T, void> extends true ? undefined : T;
+type DataFrom<T> = IsAny<T> extends true ? undefined : T extends Func ? VoidToUndefined<Awaited<ReturnType<T>>> : undefined;
+type ClientData<T> = T extends Response ? never : T extends DataWithResponseInit<infer U> ? U : T;
+type ServerData<T> = T extends Response ? never : T extends DataWithResponseInit<infer U> ? Serialize<U> : Serialize<T>;
+type ServerDataFrom<T> = ServerData<DataFrom<T>>;
+type ClientDataFrom<T> = ClientData<DataFrom<T>>;
+type ClientDataFunctionArgs<Params> = {
+    /**
+     * A {@link https://developer.mozilla.org/en-US/docs/Web/API/Request Fetch Request instance} which you can use to read the URL, the method, the "content-type" header, and the request body from the request.
+     *
+     * @note Because client data functions are called before a network request is made, the Request object does not include the headers which the browser automatically adds. React Router infers the "content-type" header from the enc-type of the form that performed the submission.
+     **/
+    request: Request;
+    /**
+     * A URL instance representing the application location being navigated to or fetched.
+     * Without `future.unstable_passThroughRequests` enabled, this matches `request.url`.
+     * With `future.unstable_passThroughRequests` enabled, this is a normalized
+     * URL with React-Router-specific implementation details removed (`.data`
+     * pathnames, `index`/`_routes` search params).
+     * The URL includes the origin from the request for convenience.
+     */
+    unstable_url: URL;
+    /**
+     * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the current route.
+     * @example
+     * // app/routes.ts
+     * route("teams/:teamId", "./team.tsx"),
+     *
+     * // app/team.tsx
+     * export function clientLoader({
+     *   params,
+     * }: Route.ClientLoaderArgs) {
+     *   params.teamId;
+     *   //        ^ string
+     * }
+     **/
+    params: Params;
+    /**
+     * Matched un-interpolated route pattern for the current path (i.e., /blog/:slug).
+     * Mostly useful as a identifier to aggregate on for logging/tracing/etc.
+     */
+    unstable_pattern: string;
+    /**
+     * When `future.v8_middleware` is not enabled, this is undefined.
+     *
+     * When `future.v8_middleware` is enabled, this is an instance of
+     * `RouterContextProvider` and can be used to access context values
+     * from your route middlewares.  You may pass in initial context values in your
+     * `<HydratedRouter getContext>` prop
+     */
+    context: Readonly<RouterContextProvider>;
+};
+type SerializeFrom<T> = T extends (...args: infer Args) => unknown ? Args extends [
+    ClientLoaderFunctionArgs | ClientActionFunctionArgs | ClientDataFunctionArgs<unknown>
+] ? ClientDataFrom<T> : ServerDataFrom<T> : T;
+/**
+ * Arguments passed to a route `clientAction` function
+ */
+type ClientActionFunctionArgs = ActionFunctionArgs & {
+    serverAction: <T = unknown>() => Promise<SerializeFrom<T>>;
+};
+/**
+ * Arguments passed to a route `clientLoader` function
+ */
+type ClientLoaderFunctionArgs = LoaderFunctionArgs & {
+    serverLoader: <T = unknown>() => Promise<SerializeFrom<T>>;
+};
+
+/**
+ * Thrown when a new `submit` or `submitJson` runs before a prior returned promise has settled.
+ * The new submission proceeds; catch this error if overlapping calls are expected.
+ */
+declare class SubmitterSupersededError extends Error {
+    readonly name = "SubmitterSupersededError";
+    constructor(message?: string);
+}
+/**
+ * Thrown when the component that owns the submitter unmounts before a `submit` /
+ * `submitJson` promise has settled.
+ */
+declare class SubmitterUnmountedError extends Error {
+    readonly name = "SubmitterUnmountedError";
+    constructor(message?: string);
+}
+/**
+ * Action payload type on the fetcher (same shape React Router puts on `fetcher.data` after the action runs).
+ * Includes `undefined` while idle or in flight—use {@link SubmitterSettledData} for the value after
+ * `await submitter.submit` / `await submitter.submitJson`.
+ */
+type DynamicSubmitterData<TInfo extends RouteWithActionModule> = ReturnType<typeof useFetcher<TInfo["action"]>>["data"];
+/**
+ * Payload type after a successful `await submitter.submit` / `await submitter.submitJson`.
+ * Omits `undefined` from {@link DynamicSubmitterData}: the promise only resolves when `fetcher.data`
+ * is defined (otherwise it rejects). Inner success values may still be void / optional `result` for
+ * `MaybeError<undefined>` from `formAction` + `success()`.
+ */
+type SubmitterSettledData<TInfo extends RouteWithActionModule> = NonNullable<DynamicSubmitterData<TInfo>>;
+/**
+ * Options for {@link useDynamicSubmitter}.
+ */
+type UseDynamicSubmitterOptions = {
+    /**
+     * Appended to the default fetcher key so multiple submitters can target the same resolved URL
+     * without sharing React Router fetcher state. Omit to use the default key for that URL.
+     */
+    keySuffix?: string;
+};
+/**
+ * React Router `useFetcher` key used by {@link useDynamicSubmitter} for a resolved href.
+ * Pass the same string as {@link UseDynamicSubmitterResult.fetcherKey} (or call with the same
+ * `resolvedHref` and `keySuffix` as the submitter) so a parallel `useFetcher({ key })` observes
+ * the same submission lifecycle.
+ *
+ * When `keySuffix` is set, it is encoded and joined with a fixed delimiter so arbitrary strings
+ * are safe in the key.
+ */
+declare function dynamicSubmitterFetcherKey(resolvedHref: string, keySuffix?: string): string;
+type UseDynamicSubmitterRest<R extends RouteWithActionModule["route"]> = HrefArgs<R> extends readonly [] ? [options?: UseDynamicSubmitterOptions] : [...hrefArgs: HrefArgs<R>, options?: UseDynamicSubmitterOptions];
 /**
  * Function type for submitting form data with a SubmitTarget.
  *
@@ -137,7 +296,7 @@ import './types/Func.js';
  */
 type SubmitFunc<TModule extends RouteWithActionModule> = (target: z.infer<TModule["formSchema"]> & SubmitTarget, options: Omit<SubmitOptions, "action" | "method" | "encType"> & {
     method: Exclude<SubmitOptions["method"], "GET">;
-}) => Promise<void>;
+}) => Promise<SubmitterSettledData<TModule>>;
 /**
  * Options for submitJson function.
  * Method defaults to "POST" if not specified.
@@ -167,7 +326,7 @@ type SubmitJsonOptions = Omit<SubmitOptions, "action" | "method" | "encType"> &
  * await submitter.submitJson(data, { method: "PUT" });
  * ```
  */
-type SubmitJsonFunc<TModule extends RouteWithActionModule> = (data: z.infer<TModule["formSchema"]>, options?: SubmitJsonOptions) => Promise<void>;
+type SubmitJsonFunc<TModule extends RouteWithActionModule> = (data: z.infer<TModule["formSchema"]>, options?: SubmitJsonOptions) => Promise<SubmitterSettledData<TModule>>;
 /**
  * Form component type with pre-bound action URL.
  *
@@ -191,6 +350,18 @@ type SubmitJsonFunc<TModule extends RouteWithActionModule> = (data: z.infer<TMod
 type SubmitForm = (props: Omit<FetcherFormProps & React.RefAttributes<HTMLFormElement>, "action" | "method"> & {
     method?: Exclude<SubmitOptions["method"], "GET">;
 }) => React.ReactElement;
+/**
+ * Stable object returned by {@link useDynamicSubmitter}: `submit`, `submitJson`, `Form`, and
+ * `fetcherKey`. The reference is memoized and does not change when the internal fetcher’s
+ * `state` / `data` update.
+ */
+type UseDynamicSubmitterResult<TInfo extends RouteWithActionModule> = {
+    submit: SubmitFunc<TInfo>;
+    submitJson: SubmitJsonFunc<TInfo>;
+    Form: SubmitForm;
+    /** Pass to {@link useDynamicSubmitterFetcher} or `useFetcher({ key })` for reactive `state` / `data`. */
+    fetcherKey: string;
+};
 /**
  * Creates a type-safe fetcher for submitting forms to dynamic routes.
  *
@@ -202,15 +373,13 @@ type SubmitForm = (props: Omit<FetcherFormProps & React.RefAttributes<HTMLFormEl
  * @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`)
+ * @param rest - Route parameters (if any), then optional {@link UseDynamicSubmitterOptions}. For
+ * static routes, you may pass only options as the second argument (e.g. `{ keySuffix: "a" }`).
+ * Options are recognized only when the object contains exclusively the `keySuffix` key (do not use
+ * a route param object whose only field is named `keySuffix` unless it is meant as options).
  *
- * @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
+ * @returns Stable `{ submit, submitJson, Form, fetcherKey }`. Await the promises for action results;
+ * use {@link useDynamicSubmitterFetcher} or local state for reactive loading/data.
  *
  * @example
  * ### Basic usage with route parameters
@@ -231,26 +400,24 @@ type SubmitForm = (props: Omit<FetcherFormProps & React.RefAttributes<HTMLFormEl
  *   { userId: "123" }
  * );
  *
- * // Submit using submitJson (type-safe, no FormData needed, defaults to POST)
- * await submitter.submitJson({
+ * const data = await submitter.submitJson({
  *   displayName: "John Doe",
  *   email: "john@example.com",
  *   notifications: true,
  * });
  *
- * // Check the response
- * if (submitter.data?.success) {
+ * if (data.success) {
  *   console.log("Settings updated!");
  * }
  * ```
  */
-declare const useDynamicSubmitter: <TInfo extends RouteWithActionModule>(path: TInfo["route"], ...args: TInfo["route"] extends "undefined" ? HrefArgs<"/"> : HrefArgs<TInfo["route"]>) => Omit<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, defaults to POST) */
-    submitJson: SubmitJsonFunc<TInfo>;
-    /** Pre-bound Form component with action URL already set (defaults to POST) */
-    Form: SubmitForm;
-};
+declare function useDynamicSubmitter<TInfo extends RouteWithActionModule>(path: TInfo["route"], ...rest: UseDynamicSubmitterRest<TInfo["route"]>): UseDynamicSubmitterResult<TInfo>;
+/**
+ * React Router `useFetcher` bound to the same key as {@link useDynamicSubmitter}, so `state` /
+ * `data` reflect the same submissions as `submitter.submit` / `submitter.Form`.
+ *
+ * Call at component top level next to `useDynamicSubmitter`.
+ */
+declare function useDynamicSubmitterFetcher<TInfo extends RouteWithActionModule>(submitter: UseDynamicSubmitterResult<TInfo>): react_router.FetcherWithComponents<SerializeFrom<TInfo["action"]>>;
 
-export { useDynamicSubmitter };
+export { type DynamicSubmitterData, type SubmitterSettledData, SubmitterSupersededError, SubmitterUnmountedError, type UseDynamicSubmitterOptions, type UseDynamicSubmitterResult, dynamicSubmitterFetcherKey, useDynamicSubmitter, useDynamicSubmitterFetcher };

package/dist/useDynamicSubmitter.js

@@ -1,3 +1,3 @@
-export { useDynamicSubmitter } from './chunk-JJN6GBJL.js';
+export { SubmitterSupersededError, SubmitterUnmountedError, dynamicSubmitterFetcherKey, useDynamicSubmitter, useDynamicSubmitterFetcher } from './chunk-XMGRKSHM.js';
 //# sourceMappingURL=useDynamicSubmitter.js.map
 //# sourceMappingURL=useDynamicSubmitter.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/router-toolkit",
-	"version": "8.0.1",
+	"version": "9.0.1",
 	"description": "Type-safe React Router 7 framework mode helpers with enhanced fetching, form submission, and state management",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -64,9 +64,8 @@
 		"url": "https://github.com/firtoz/fullstack-toolkit/issues"
 	},
 	"peerDependencies": {
-		"@firtoz/maybe-error": "^1.6.0",
 		"react": "^19.2.5",
-		"react-router": "^7.14.1",
+		"react-router": "^7.14.2",
 		"zod": "^4.3.6"
 	},
 	"engines": {
@@ -76,13 +75,14 @@
 		"access": "public"
 	},
 	"dependencies": {
+		"@firtoz/maybe-error": "^1.6.1",
 		"zod-form-data": "^3.0.1"
 	},
 	"devDependencies": {
 		"@testing-library/react": "^16.3.1",
 		"@types/jsdom": "^28.0.1",
 		"@types/react": "^19.2.14",
-		"bun-types": "^1.3.12",
+		"bun-types": "^1.3.13",
 		"jsdom": "^29.0.2"
 	}
 }

package/src/formAction.ts

@@ -52,13 +52,26 @@
  * @example
  * ### Using with useDynamicSubmitter
  *
- * The route above can be used with `useDynamicSubmitter` for type-safe form submissions:
+ * The route above can be used with `useDynamicSubmitter` for type-safe form submissions.
+ * The hook exposes {@link UseDynamicSubmitterResult.fetcherKey} (built with
+ * {@link dynamicSubmitterFetcherKey}) so a parallel `useFetcher` stays aligned; prefer
+ * {@link useDynamicSubmitterFetcher} instead of hand-rolling the key.
+ *
+ * The **optional** {@link useDynamicSubmitterFetcher} below is only for declarative UI that reads
+ * `fetcher.state` / `fetcher.data` in render (same submission as `submitter`). For promise-first
+ * flows, omit it and use `await submitter.submitJson(...)` plus local `useState` for pending.
+ * Use {@link UseDynamicSubmitterOptions.keySuffix} when two submitters target the same URL and
+ * must not share fetcher state.
  *
  * ```tsx
- * import { useDynamicSubmitter } from "@firtoz/router-toolkit";
+ * import {
+ *   useDynamicSubmitter,
+ *   useDynamicSubmitterFetcher,
+ * } from "@firtoz/router-toolkit";
  *
  * function LoginForm() {
  *   const submitter = useDynamicSubmitter<typeof import("./auth.login")>("/auth/login");
+ *   const fetcher = useDynamicSubmitterFetcher(submitter);
  *
  *   // Option 1: Submit as JSON (defaults to POST)
  *   const handleLoginJson = async () => {
@@ -69,7 +82,7 @@
  *     });
  *   };
  *
- *   // Option 2: Use the Form component (defaults to POST)
+ *   // Option 2: Form + useDynamicSubmitterFetcher for reactive state/data
  *   return (
  *     <submitter.Form>
  *       <input name="email" type="email" placeholder="Email" />
@@ -77,16 +90,16 @@
  *       <label>
  *         <input name="rememberMe" type="checkbox" /> Remember me
  *       </label>
- *       <button disabled={submitter.state !== "idle"}>
- *         {submitter.state === "submitting" ? "Logging in..." : "Login"}
+ *       <button type="submit" disabled={fetcher.state === "submitting"}>
+ *         {fetcher.state === "submitting" ? "Logging in..." : "Login"}
  *       </button>
  *
- *       {submitter.data && !submitter.data.success && (
+ *       {fetcher.data && !fetcher.data.success && (
  *         <div className="error">
- *           {submitter.data.error.type === "validation"
+ *           {fetcher.data.error.type === "validation"
  *             ? "Please check your inputs"
- *             : submitter.data.error.type === "handler"
- *               ? submitter.data.error.error // "Invalid email or password"
+ *             : fetcher.data.error.type === "handler"
+ *               ? fetcher.data.error.error
  *               : "An unexpected error occurred"}
  *         </div>
  *       )}
@@ -139,21 +152,21 @@
  *
  * ```tsx
  * import { useDynamicFetcher, useDynamicSubmitter } from "@firtoz/router-toolkit";
- * import { useEffect } from "react";
+ * import { useEffect, useState } 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 }
  *   );
  *
+ *   const [saving, setSaving] = useState(false);
+ *
  *   useEffect(() => {
  *     fetcher.load();
  *   }, [fetcher.load]);
@@ -165,15 +178,28 @@
  *   const post = fetcher.data?.post;
  *
  *   return (
- *     <submitter.Form method="PUT">
+ *     <submitter.Form
+ *       method="PUT"
+ *       onSubmit={async (e) => {
+ *         e.preventDefault();
+ *         setSaving(true);
+ *         try {
+ *           const fd = new FormData(e.currentTarget);
+ *           await submitter.submit(fd, { method: "PUT" });
+ *           fetcher.load();
+ *         } finally {
+ *           setSaving(false);
+ *         }
+ *       }}
+ *     >
  *       <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 type="submit" disabled={saving}>
+ *         {saving ? "Saving..." : "Save"}
  *       </button>
  *     </submitter.Form>
  *   );

package/src/types/index.ts

@@ -1,4 +1,3 @@
-export * from "@firtoz/maybe-error";
 export * from "./Func";
 export * from "./HrefArgs";
 export * from "./RegisterPages";