@void/react 0.21.9 → 0.23.0

package/README.md

@@ -39,7 +39,7 @@ Main runtime APIs live at `@void/react`:
 - `useParams()`
 - `useNavigation()`
 - `useShared()`
-- `useForm()`
+- `Form` and `useForm()`
 - `useIslandForm()`
 - `action()`
 
@@ -110,7 +110,7 @@ export interface Props {
 inside the form for button pending state.
 
 ```tsx
-import { useForm } from '@void/react';
+import { Form, useForm } from '@void/react';
 import { useFormStatus } from 'react-dom';
 
 function SubmitButton() {
@@ -122,16 +122,15 @@ export default function CreateUser() {
   const form = useForm('/users', { name: '', email: '' });
 
   return (
-    <form action={form.post}>
+    <Form form={form}>
       <input
         name="name"
         value={form.data.name}
         onChange={(e) => form.setData('name', e.target.value)}
       />
       {form.errors.name && <span>{form.errors.name}</span>}
-      {form.error && <p>{form.error.message}</p>}
       <SubmitButton />
-    </form>
+    </Form>
   );
 }
 ```
@@ -217,6 +216,12 @@ import { defineHandler } from 'void';
 export const loader = defineHandler(() => ({ title: 'Home' }));
 ```
 
+## Form
+
+Use `Form` with `useForm()` to display action and validation errors automatically. It preserves controlled input after a failed submission and announces errors accessibly. Structured usage-limit responses display the application's message and an optional retry time. Submissions are blocked while pending and before that deadline; inputs remain editable and requests are never retried automatically.
+
+`method` selects `post` (the default), `put`, `patch`, or `delete`. Use `renderError` to customize action-error presentation (a snippet in Svelte). Native forms remain available when you manage error presentation yourself.
+
 ## Tests
 
 - `test/unit/link.test.ts`

package/dist/action-4EvQppia.mjs

@@ -0,0 +1,7 @@
+import { createActionClient } from "void/pages-client";
+//#region src/runtime/action.ts
+const client = createActionClient();
+const action = client.action;
+const setActionRouter = client.setActionRouter;
+//#endregion
+export { setActionRouter as n, action as t };

package/dist/{index-Cx2A1XEu.d.mts → index-D5M3zrVB.d.mts}

@@ -1,7 +1,15 @@
-import { AnchorHTMLAttributes, ButtonHTMLAttributes, Context, JSX } from "react";
-import { ActionResult, NavigationState, VoidActionError, VoidRouter } from "void/pages-client";
+import { AnchorHTMLAttributes, ButtonHTMLAttributes, Context, FormHTMLAttributes, JSX, ReactElement, ReactNode } from "react";
+import { ActionClient, FormMethod, FormModel, NavigationState, VoidActionError, VoidRouter } from "void/pages-client";
 import { CloudContextVariables, InferProps } from "void";
-import { ActionFormOptions, ActionUrl, ResolveActionBody, ResolveActionParams } from "void/routes";
+import { ActionFormOptions, ActionUrl, ResolveActionBody } from "void/routes";
+//#region src/runtime/form.d.ts
+type FormProps = Omit<FormHTMLAttributes<HTMLFormElement>, "action" | "onSubmit" | "method" | "onError"> & {
+  form: FormModel<[FormData]>;
+  method?: FormMethod;
+  renderError?: (error: VoidActionError) => ReactNode;
+};
+declare function Form({ form, method, renderError, children, ...props }: FormProps): ReactElement;
+//#endregion
 //#region src/runtime/link.d.ts
 type PrefetchStrategy = "hover" | "click" | "mount" | "visible";
 type LinkMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -79,20 +87,8 @@ type IslandFormReturn<T extends Record<string, unknown>> = Readonly<{
 declare function useIslandForm<T extends Record<string, unknown>>(defaults: T): IslandFormReturn<T>;
 //#endregion
 //#region src/runtime/action.d.ts
-type ActionMethod = "POST" | "PUT" | "PATCH" | "DELETE";
-type HasParams<U extends string> = [ResolveActionParams<U>] extends [never] ? false : true;
-type ActionOptions<U extends string> = {
-  data?: ResolveActionBody<U>;
-  method?: ActionMethod;
-} & (HasParams<U> extends true ? {
-  params: ResolveActionParams<U>;
-} : {
-  params?: never;
-});
-/** Called during app initialization to store the router instance */
-declare function setActionRouter(router: VoidRouter): void;
-/** Programmatic one-shot page action call with Inertia page update */
-declare function action<U extends ActionUrl & string>(url: U, ...args: HasParams<U> extends true ? [options: ActionOptions<U>] : [options?: ActionOptions<U>]): Promise<ActionResult>;
+declare const action: ActionClient["action"];
+declare const setActionRouter: ActionClient["setActionRouter"];
 //#endregion
 //#region src/runtime/context.d.ts
 declare const SharedContext: Context<Record<string, unknown> | null>;
@@ -104,4 +100,4 @@ declare const NavigationContext: Context<NavigationState>;
 //#region src/runtime/index.d.ts
 type Deferred<T> = Promise<T>;
 //#endregion
-export { ParamsContext as a, action as c, useNavigation as d, useForm as f, Link as g, useRouter as h, NavigationContext as i, setActionRouter as l, useParams as m, InferProps as n, RouterContext as o, useShared as p, ErrorsContext as r, SharedContext as s, Deferred as t, useIslandForm as u };
+export { Form as _, ParamsContext as a, action as c, useNavigation as d, useForm as f, Link as g, useRouter as h, NavigationContext as i, setActionRouter as l, useParams as m, InferProps as n, RouterContext as o, useShared as p, ErrorsContext as r, SharedContext as s, Deferred as t, useIslandForm as u };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { a as ParamsContext, c as action, d as useNavigation, f as useForm, g as Link, h as useRouter, i as NavigationContext, l as setActionRouter, m as useParams, n as InferProps, o as RouterContext, p as useShared, r as ErrorsContext, s as SharedContext, t as Deferred, u as useIslandForm } from "./index-Cx2A1XEu.mjs";
-export { Deferred, ErrorsContext, type InferProps, Link, NavigationContext, ParamsContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useParams, useRouter, useShared };
+import { _ as Form, a as ParamsContext, c as action, d as useNavigation, f as useForm, g as Link, h as useRouter, i as NavigationContext, l as setActionRouter, m as useParams, n as InferProps, o as RouterContext, p as useShared, r as ErrorsContext, s as SharedContext, t as Deferred, u as useIslandForm } from "./index-D5M3zrVB.mjs";
+export { Deferred, ErrorsContext, Form, type InferProps, Link, NavigationContext, ParamsContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useParams, useRouter, useShared };

package/dist/index.mjs

@@ -1,4 +1,4 @@
+import { a as useParams, c as Form, i as useShared, n as useNavigation, o as useRouter, r as useForm, s as Link, t as useIslandForm } from "./runtime-D_Wv52MZ.mjs";
 import { a as SharedContext, i as RouterContext, n as NavigationContext, r as ParamsContext, t as ErrorsContext } from "./context-B0GL7p5m.mjs";
-import { a as useParams, i as useShared, n as useNavigation, o as useRouter, r as useForm, s as Link, t as useIslandForm } from "./runtime-W1oiBA4P.mjs";
-import { n as setActionRouter, t as action } from "./action-Bq1iSG6m.mjs";
-export { ErrorsContext, Link, NavigationContext, ParamsContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useParams, useRouter, useShared };
+import { n as setActionRouter, t as action } from "./action-4EvQppia.mjs";
+export { ErrorsContext, Form, Link, NavigationContext, ParamsContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useParams, useRouter, useShared };

package/dist/runtime/index.d.mts

@@ -1,2 +1,2 @@
-import { a as ParamsContext, c as action, d as useNavigation, f as useForm, g as Link, h as useRouter, i as NavigationContext, l as setActionRouter, m as useParams, n as InferProps, o as RouterContext, p as useShared, r as ErrorsContext, s as SharedContext, t as Deferred, u as useIslandForm } from "../index-Cx2A1XEu.mjs";
-export { Deferred, ErrorsContext, type InferProps, Link, NavigationContext, ParamsContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useParams, useRouter, useShared };
+import { _ as Form, a as ParamsContext, c as action, d as useNavigation, f as useForm, g as Link, h as useRouter, i as NavigationContext, l as setActionRouter, m as useParams, n as InferProps, o as RouterContext, p as useShared, r as ErrorsContext, s as SharedContext, t as Deferred, u as useIslandForm } from "../index-D5M3zrVB.mjs";
+export { Deferred, ErrorsContext, Form, type InferProps, Link, NavigationContext, ParamsContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useParams, useRouter, useShared };

package/dist/runtime/index.mjs

@@ -1,4 +1,4 @@
+import { a as useParams, c as Form, i as useShared, n as useNavigation, o as useRouter, r as useForm, s as Link, t as useIslandForm } from "../runtime-D_Wv52MZ.mjs";
 import { a as SharedContext, i as RouterContext, n as NavigationContext, r as ParamsContext, t as ErrorsContext } from "../context-B0GL7p5m.mjs";
-import { a as useParams, i as useShared, n as useNavigation, o as useRouter, r as useForm, s as Link, t as useIslandForm } from "../runtime-W1oiBA4P.mjs";
-import { n as setActionRouter, t as action } from "../action-Bq1iSG6m.mjs";
-export { ErrorsContext, Link, NavigationContext, ParamsContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useParams, useRouter, useShared };
+import { n as setActionRouter, t as action } from "../action-4EvQppia.mjs";
+export { ErrorsContext, Form, Link, NavigationContext, ParamsContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useParams, useRouter, useShared };

package/dist/runtime/pages-client.mjs

@@ -1,5 +1,5 @@
 import { a as SharedContext, i as RouterContext, n as NavigationContext, r as ParamsContext, t as ErrorsContext } from "../context-B0GL7p5m.mjs";
-import { n as setActionRouter } from "../action-Bq1iSG6m.mjs";
+import { n as setActionRouter } from "../action-4EvQppia.mjs";
 import { n as DEFERRED_SHELL_END_ID } from "../deferred-shell-DOuP2YAo.mjs";
 import React, { Suspense, startTransition, use, useCallback, useEffect, useInsertionEffect, useLayoutEffect, useMemo, useReducer, useTransition } from "react";
 import { createPageNavigationEngine, createRouterFacade, idleNavigationState, isAbortError, isCallSiteActionError } from "void/pages-client";

package/dist/{runtime-W1oiBA4P.mjs → runtime-D_Wv52MZ.mjs}

@@ -1,8 +1,30 @@
 import { a as SharedContext, i as RouterContext, n as NavigationContext, r as ParamsContext } from "./context-B0GL7p5m.mjs";
-import "./action-Bq1iSG6m.mjs";
+import "./action-4EvQppia.mjs";
 import { useActionState, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
-import { VoidActionError, categorizeActionError, isAbortError, isEqualFormValue, ssrProxy, submitAction } from "void/pages-client";
-import { jsx } from "react/jsx-runtime";
+import { VoidActionError, categorizeActionError, formErrorMessage, formRetryMessage, formSubmissionBlocked, isAbortError, isEqualFormValue, scheduleFormRetry, ssrProxy, submitAction } from "void/pages-client";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/runtime/form.tsx
+function Form({ form, method = "post", renderError, children, ...props }) {
+	const [now, setNow] = useState(Date.now);
+	useEffect(() => scheduleFormRetry(form.error, () => setNow(Date.now())), [form.error]);
+	const message = formErrorMessage(form);
+	const retry = formRetryMessage(form.error);
+	const blocked = formSubmissionBlocked(form, now);
+	return /* @__PURE__ */ jsxs("form", {
+		...props,
+		action: form[method],
+		"aria-busy": form.pending,
+		onSubmit: (event) => {
+			if (blocked) event.preventDefault();
+		},
+		children: [message && /* @__PURE__ */ jsxs("div", {
+			role: "alert",
+			"data-void-form-error": true,
+			children: [form.error && renderError ? renderError(form.error) : message, retry && /* @__PURE__ */ jsx("p", { children: retry })]
+		}), children]
+	});
+}
+//#endregion
 //#region src/runtime/link.tsx
 function appendQueryValue(params, key, value) {
 	if (value === null || value === void 0) return false;
@@ -497,4 +519,4 @@ function useIslandForm(defaults) {
 	};
 }
 //#endregion
-export { useParams as a, useShared as i, useNavigation as n, useRouter as o, useForm as r, Link as s, useIslandForm as t };
+export { useParams as a, Form as c, useShared as i, useNavigation as n, useRouter as o, useForm as r, Link as s, useIslandForm as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@void/react",
-  "version": "0.21.9",
+  "version": "0.23.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/voidzero-dev/void.git",
@@ -35,21 +35,21 @@
     "@vitejs/plugin-react": "^6.1.1"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.3",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "pathslash": "^0.1.0",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.1",
-    "vite-plus": "0.3.1",
-    "void": "0.21.9"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
+    "vite-plus": "1.0.0",
+    "void": "0.23.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "vite": "^8.0.0",
-    "void": "0.21.9"
+    "void": "0.23.0"
   },
   "scripts": {
     "build": "vp pack",

package/dist/action-Bq1iSG6m.mjs

@@ -1,29 +0,0 @@
-import { submitAction } from "void/pages-client";
-//#region src/runtime/action.ts
-let _router = null;
-/** Called during app initialization to store the router instance */
-function setActionRouter(router) {
-	_router = router;
-}
-/** Programmatic one-shot page action call with Inertia page update */
-async function action(url, ...args) {
-	if (!_router) throw new Error("action(): called before router initialization.");
-	const options = args[0];
-	const data = options?.data;
-	const method = options?.method || "POST";
-	let resolvedUrl = url;
-	let actionQuery = "";
-	const qIdx = resolvedUrl.indexOf("?");
-	if (qIdx !== -1) {
-		actionQuery = resolvedUrl.slice(qIdx);
-		resolvedUrl = resolvedUrl.slice(0, qIdx);
-	}
-	if (options?.params) for (const [key, value] of Object.entries(options.params)) resolvedUrl = resolvedUrl.replace(`:${key}`, encodeURIComponent(value));
-	resolvedUrl = resolvedUrl + actionQuery;
-	return submitAction(_router, resolvedUrl, {
-		method,
-		data
-	});
-}
-//#endregion
-export { setActionRouter as n, action as t };