@void/solid 0.22.0 → 0.23.0

package/README.md

@@ -37,7 +37,7 @@ Main runtime APIs live at `@void/solid`:
 - `useParams()`
 - `useNavigation()`
 - `useShared()`
-- `useForm()`
+- `Form` and `useForm()`
 - `useIslandForm()`
 - `action()`
 
@@ -113,6 +113,12 @@ Export `ssr = false` from a page's `.server.ts` file to skip server-rendered
 component HTML for that route while still running its loader on the first
 request.
 
+## 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/integration/solid-pages-playground.test.ts`

package/dist/runtime/index.d.mts

@@ -1,8 +1,16 @@
 import { ErrorsContext, NavigationContext, ParamsContext, RouterContext, SharedContext } from "./context.mjs";
 import { JSX } from "solid-js";
-import { ActionResult, NavigationState, VisitOptions, VoidActionError, VoidRouter } from "void/pages-client";
+import { ActionClient, FormMethod, FormModel, NavigationState, VisitOptions, VoidActionError, VoidRouter } from "void/pages-client";
 import { CloudContextVariables, DeferredState as Deferred, 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<JSX.FormHTMLAttributes<HTMLFormElement>, "action" | "onSubmit" | "method" | "onError"> & {
+  form: FormModel;
+  method?: FormMethod;
+  renderError?: (error: VoidActionError) => JSX.Element;
+};
+export declare function Form(props: FormProps): JSX.Element;
+//#endregion
 //#region src/runtime/link.d.ts
 type PrefetchStrategy = "hover" | "click" | "mount" | "visible";
 type LinkMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -85,19 +93,7 @@ type IslandFormReturn<T extends Record<string, unknown>> = Readonly<{
 export 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 */
-export declare function setActionRouter(router: VoidRouter): void;
-/** Programmatic one-shot page action call with Inertia page update */
-export declare function action<U extends ActionUrl & string>(url: U, ...args: HasParams<U> extends true ? [options: ActionOptions<U>] : [options?: ActionOptions<U>]): Promise<ActionResult>;
+export declare const action: ActionClient["action"];
+export declare const setActionRouter: ActionClient["setActionRouter"];
 //#endregion
 export { type Deferred, ErrorsContext, type InferProps, type LinkProps, NavigationContext, ParamsContext, RouterContext, SharedContext };

package/dist/runtime/index.mjs

@@ -1,7 +1,32 @@
 import { ErrorsContext, NavigationContext, ParamsContext, RouterContext, SharedContext } from "./context.mjs";
-import { createMemo, createSignal, onCleanup, onMount, splitProps, useContext } from "solid-js";
-import { VoidActionError, categorizeActionError, idleNavigationState, isAbortError, isEqualFormValue, ssrProxy, submitAction } from "void/pages-client";
+import { createEffect, createMemo, createSignal, onCleanup, onMount, splitProps, useContext } from "solid-js";
+import { VoidActionError, categorizeActionError, createActionClient, formErrorMessage, formRetryMessage, formSubmissionBlocked, idleNavigationState, isAbortError, isEqualFormValue, scheduleFormRetry, ssrProxy, submitAction } from "void/pages-client";
 import { createStore, reconcile } from "solid-js/store";
+//#region src/runtime/form.tsx
+function Form(props) {
+	const [local, rest] = splitProps(props, [
+		"form",
+		"method",
+		"renderError",
+		"children"
+	]);
+	const [now, setNow] = createSignal(Date.now());
+	createEffect(() => {
+		const cancel = scheduleFormRetry(local.form.error, () => setNow(Date.now()));
+		onCleanup(cancel);
+	});
+	return <form {...rest} aria-busy={local.form.pending} onSubmit={async (event) => {
+		event.preventDefault();
+		if (!formSubmissionBlocked(local.form, now())) await local.form[local.method ?? "post"]();
+	}}>
+      {formErrorMessage(local.form) && <div role="alert" data-void-form-error>
+          {local.form.error && local.renderError ? local.renderError(local.form.error) : formErrorMessage(local.form)}
+          {formRetryMessage(local.form.error) && <p>{formRetryMessage(local.form.error)}</p>}
+        </div>}
+      {local.children}
+    </form>;
+}
+//#endregion
 //#region src/runtime/link.tsx
 function appendQueryValue(params, key, value) {
 	if (value === null || value === void 0) return false;
@@ -498,30 +523,8 @@ function useIslandForm(defaults) {
 }
 //#endregion
 //#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
-	});
-}
+const client = createActionClient();
+const action = client.action;
+const setActionRouter = client.setActionRouter;
 //#endregion
-export { ErrorsContext, Link, NavigationContext, ParamsContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useParams, useRouter, useShared };
+export { ErrorsContext, Form, Link, NavigationContext, ParamsContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useParams, useRouter, useShared };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@void/solid",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/voidzero-dev/void.git",
@@ -33,12 +33,12 @@
     "solid-js": "^1.9.15",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
     "vite-plus": "1.0.0",
-    "void": "0.22.0"
+    "void": "0.23.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0",
     "vite": "^8.0.0",
-    "void": "0.22.0"
+    "void": "0.23.0"
   },
   "scripts": {
     "build": "vp pack",

package/src/runtime/action.ts

@@ -1,50 +1,6 @@
-import { submitAction, type ActionResult, type VoidRouter } from 'void/pages-client';
-import type { ActionUrl, ResolveActionBody, ResolveActionParams } from 'void/routes';
+import { createActionClient, type ActionClient } from 'void/pages-client';
 
-type ActionMethod = 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+const client = createActionClient();
 
-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 });
-
-let _router: VoidRouter | null = null;
-
-/** Called during app initialization to store the router instance */
-export function setActionRouter(router: VoidRouter): void {
-  _router = router;
-}
-
-/** Programmatic one-shot page action call with Inertia page update */
-export async function action<U extends ActionUrl & string>(
-  url: U,
-  ...args: HasParams<U> extends true ? [options: ActionOptions<U>] : [options?: ActionOptions<U>]
-): Promise<ActionResult> {
-  if (!_router) {
-    throw new Error('action(): called before router initialization.');
-  }
-
-  const options = args[0] as ActionOptions<U> | undefined;
-  const data = options?.data;
-  const method = options?.method || 'POST';
-
-  let resolvedUrl: string = 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 as string));
-    }
-  }
-
-  resolvedUrl = resolvedUrl + actionQuery;
-  return submitAction(_router, resolvedUrl, { method, data });
-}
+export const action: ActionClient['action'] = client.action;
+export const setActionRouter: ActionClient['setActionRouter'] = client.setActionRouter;

package/src/runtime/form.tsx

@@ -0,0 +1,49 @@
+import { createEffect, createSignal, onCleanup, splitProps, type JSX } from 'solid-js';
+import {
+  formErrorMessage,
+  formRetryMessage,
+  formSubmissionBlocked,
+  scheduleFormRetry,
+  type FormModel,
+  type FormMethod,
+  type VoidActionError,
+} from 'void/pages-client';
+
+export type FormProps = Omit<
+  JSX.FormHTMLAttributes<HTMLFormElement>,
+  'action' | 'onSubmit' | 'method' | 'onError'
+> & {
+  form: FormModel;
+  method?: FormMethod;
+  renderError?: (error: VoidActionError) => JSX.Element;
+};
+export function Form(props: FormProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['form', 'method', 'renderError', 'children']);
+  const [now, setNow] = createSignal(Date.now());
+  createEffect(() => {
+    const cancel = scheduleFormRetry(local.form.error, () => setNow(Date.now()));
+    onCleanup(cancel);
+  });
+  return (
+    <form
+      {...rest}
+      aria-busy={local.form.pending}
+      onSubmit={async (event) => {
+        event.preventDefault();
+        if (!formSubmissionBlocked(local.form, now())) {
+          await local.form[local.method ?? 'post']();
+        }
+      }}
+    >
+      {formErrorMessage(local.form) && (
+        <div role="alert" data-void-form-error>
+          {local.form.error && local.renderError
+            ? local.renderError(local.form.error)
+            : formErrorMessage(local.form)}
+          {formRetryMessage(local.form.error) && <p>{formRetryMessage(local.form.error)}</p>}
+        </div>
+      )}
+      {local.children}
+    </form>
+  );
+}

package/src/runtime/index.ts

@@ -1,3 +1,4 @@
+export { Form } from './form.tsx';
 export { Link, type LinkProps } from './link.tsx';
 export { useRouter } from './use-router.ts';
 export { useParams } from './use-params.ts';