void 0.21.9 → 0.23.0

package/skills/void/docs/guide/pages-routing/actions-and-forms.md

@@ -34,10 +34,10 @@ export const action = defineHandler.withValidator({
 When a page needs multiple mutations, such as updating and deleting a user on the same page, export `actions` (plural) instead of `action`:
 
 ```ts
-// pages/users/edit.server.ts
+// pages/users/[id].server.ts
 import { defineHandler } from 'void';
 import { db, eq } from 'void/db';
-import { users } from '@schema';
+import { users, updateUserSchema } from '@schema';
 
 export const actions = {
   update: defineHandler.withValidator({
@@ -46,19 +46,18 @@ export const actions = {
     await db
       .update(users)
       .set(body)
-      .where(eq(users.id, c.req.param('id')));
+      .where(eq(users.id, Number(c.req.param('id'))));
   }),
 
   delete: defineHandler(async (c) => {
-    const { id } = await c.req.json<{ id: string }>();
-    await db.delete(users).where(eq(users.id, id));
+    await db.delete(users).where(eq(users.id, Number(c.req.param('id'))));
   }),
 };
 ```
 
-Named actions are dispatched via a `?actionName` suffix on the URL (e.g. `/users/edit?update`). The client primitives `useForm` and `action()` handle this automatically.
+Named actions are dispatched via a `?actionName` suffix on the URL (e.g. `/users/42?update`). The client primitives `useForm` and `action()` handle this automatically.
 
-`export const action` (singular) still works for pages that only need one mutation. Named actions are opt-in. Exporting both `action` and `actions` from the same file is an error.
+Use `action` or `actions` in a file, not both.
 
 You can also define an `actions.default` key for the action that runs when no name is specified (i.e. a bare POST to the page URL):
 
@@ -73,39 +72,25 @@ export const actions = {
 };
 ```
 
-## `useForm`
+## Form
 
-`useForm` handles form submissions, loading state, and validation errors. It is **fully typed end to end**. The URL autocompletes to pages that have an action, `form.data` matches the action validator schema, and `form.errors` keys are constrained to the body field names.
+Pair `Form` with `useForm` for automatic error presentation. It preserves controlled input on failure, announces validation and action errors, and displays the message from structured quota responses. Known retry deadlines prevent premature resubmission without locking the fields. It never retries a submission automatically.
 
-First, define the action in your server handler:
+Import `Form` from your adapter. Pass `form` and, optionally, `method="put"`, `"patch"`, or `"delete"`; the default is `"post"`. Use `renderError` for a custom action-error renderer (a snippet in Svelte).
 
-```ts
-// pages/users/create.server.ts
-import { defineHandler } from 'void';
-import { db } from 'void/db';
-import { users } from '@schema';
-import * as v from 'valibot';
+On the server, use `limit.response({ message: 'AI is temporarily unavailable. Your draft is still editable.' })` in an AI or Sandbox operation's required `limited` handler. It supplies the status and structured metadata consumed by `Form`.
 
-const createUserSchema = v.object({
-  name: v.pipe(v.string(), v.minLength(1)),
-  email: v.pipe(v.string(), v.email()),
-});
+## `useForm`
 
-export const action = defineHandler.withValidator({
-  body: createUserSchema,
-})(async (c, { body }) => {
-  await db.insert(users).values(body);
-  return c.redirect('/users');
-});
-```
+`useForm` handles submissions, loading state, and validation errors. URLs, form values, and error fields are typed from your action.
 
-Then, use `useForm` in the page component to submit to this action:
+Submit to the `/users` action defined above:
 
 ::: code-group
 
 ```tsx [React]
-// pages/users/create.tsx
-import { useForm } from '@void/react';
+// pages/users/index.tsx
+import { Form, useForm } from '@void/react';
 import { useFormStatus } from 'react-dom';
 
 function SubmitButton() {
@@ -114,11 +99,10 @@ function SubmitButton() {
 }
 
 export default function CreateUser() {
-  // "/users/create" autocompletes; { name, email } is typed from the action's validator
-  const form = useForm('/users/create', { name: '', email: '' });
+  const form = useForm('/users', { name: '', email: '' });
 
   return (
-    <form action={form.post}>
+    <Form form={form}>
       <input
         name="name"
         value={form.data.name}
@@ -133,25 +117,22 @@ export default function CreateUser() {
       />
       {form.errors.email && <span>{form.errors.email}</span>}
 
-      {form.error && <p>{form.error.message}</p>}
-
       <SubmitButton />
-    </form>
+    </Form>
   );
 }
 ```
 
 ```vue [Vue]
-<!-- pages/users/create.vue -->
+<!-- pages/users/index.vue -->
 <script setup lang="ts">
-import { useForm } from '@void/vue';
+import { Form, useForm } from '@void/vue';
 
-// "/users/create" autocompletes; { name, email } is typed from the action's validator
-const form = useForm('/users/create', { name: '', email: '' });
+const form = useForm('/users', { name: '', email: '' });
 </script>
 
 <template>
-  <form @submit.prevent="form.post()">
+  <Form :form="form">
     <input v-model="form.data.name" />
     <span v-if="form.errors.name">{{ form.errors.name }}</span>
 
@@ -159,20 +140,19 @@ const form = useForm('/users/create', { name: '', email: '' });
     <span v-if="form.errors.email">{{ form.errors.email }}</span>
 
     <button :disabled="form.pending">Create</button>
-  </form>
+  </Form>
 </template>
 ```
 
 ```svelte [Svelte]
-<!-- pages/users/create.svelte -->
+<!-- pages/users/index.svelte -->
 <script>
-  import { useForm } from "@void/svelte";
+  import { Form, useForm } from "@void/svelte";
 
-  // "/users/create" autocompletes; { name, email } is typed from the action's validator
-  const form = useForm("/users/create", { name: "", email: "" });
+  const form = useForm("/users", { name: "", email: "" });
 </script>
 
-<form onsubmit={(e) => { e.preventDefault(); return form.post(); }}>
+<Form {form}>
   <input bind:value={form.data.name} />
   {#if form.errors.name}<span>{form.errors.name}</span>{/if}
 
@@ -180,24 +160,18 @@ const form = useForm('/users/create', { name: '', email: '' });
   {#if form.errors.email}<span>{form.errors.email}</span>{/if}
 
   <button disabled={form.pending}>Create</button>
-</form>
+</Form>
 ```
 
 ```tsx [Solid]
-// pages/users/create.tsx
-import { useForm } from '@void/solid';
+// pages/users/index.tsx
+import { Form, useForm } from '@void/solid';
 
 export default function CreateUser() {
-  // "/users/create" autocompletes; { name, email } is typed from the action's validator
-  const form = useForm('/users/create', { name: '', email: '' });
+  const form = useForm('/users', { name: '', email: '' });
 
   return (
-    <form
-      onSubmit={(e) => {
-        e.preventDefault();
-        return form.post();
-      }}
-    >
+    <Form form={form}>
       <input value={form.data.name} onInput={(e) => form.setData('name', e.target.value)} />
       {form.errors.name && <span>{form.errors.name}</span>}
 
@@ -205,7 +179,7 @@ export default function CreateUser() {
       {form.errors.email && <span>{form.errors.email}</span>}
 
       <button disabled={form.pending}>Create</button>
-    </form>
+    </Form>
   );
 }
 ```
@@ -218,40 +192,28 @@ The types are inferred from your action's `withValidator()` schema in the compan
 
 `useForm` returns a reactive object with:
 
-| Property / Method                | Purpose                                                                                       |
-| -------------------------------- | --------------------------------------------------------------------------------------------- |
-| Property / Method                | Purpose                                                                                       |
-| -------------------------------- | --------------------------------------------------------------------------------------------- |
-| `data` / `setData`               | Current form values, typed to match the action's body schema.                                 |
-| `errors`                         | Field-level validation errors, keys typed to body field names.                                |
-| `error`                          | Non-validation call-site action error, or `null`.                                             |
-| `post`, `put`, `patch`, `delete` | Submit the form with that method. In React these are native form action callbacks.            |
-| `pending`                        | `true` while the submission is in flight.                                                     |
-| `hasChanges`                     | `true` if form data differs from initial values.                                              |
-| `wasSuccessful`                  | `true` after a successful submission. Stays `true` until the next submission.                 |
-| `recentlySuccessful`             | `true` for 2 seconds after a successful submission. Useful for flash messages.                |
-| `reset(...fields)`               | Reset form data to initial values. Field names autocomplete.                                  |
-| `clearErrors(...fields)`         | Clear validation errors. Field names autocomplete.                                            |
-| `clearError()`                   | Clear the non-validation call-site error.                                                     |
-
-In React, prefer the native Action form:
-
-```tsx
-<form action={form.post}>{/* controlled inputs update form.data */}</form>
-```
-
-Use `form.put`, `form.patch`, or `form.delete` as the form action for alternate HTTP methods. Use the `action()` helper when you need an awaitable imperative mutation.
-
-In Vue, Svelte, and Solid, the same helpers return `Promise<void>` so
-boundary-class failures can propagate through framework async error handling or
-explicit `catch` handlers.
+| Property / Method                | Purpose                                                                            |
+| -------------------------------- | ---------------------------------------------------------------------------------- |
+| `data` / `setData`               | Current form values, typed to match the action's body schema.                      |
+| `errors`                         | Field-level validation errors, keys typed to body field names.                     |
+| `error`                          | Action error, or `null`.                                                           |
+| `post`, `put`, `patch`, `delete` | Submit the form with that method. In React these are native form action callbacks. |
+| `pending`                        | `true` while the submission is in flight.                                          |
+| `hasChanges`                     | `true` if form data differs from initial values.                                   |
+| `wasSuccessful`                  | `true` after a successful submission. Stays `true` until the next submission.      |
+| `recentlySuccessful`             | `true` for 2 seconds after a successful submission. Useful for flash messages.     |
+| `reset(...fields)`               | Reset form data to initial values. Field names autocomplete.                       |
+| `clearErrors(...fields)`         | Clear validation errors. Field names autocomplete.                                 |
+| `clearError()`                   | Clear `error`.                                                                     |
+
+For a native React form, use `form.post`, `form.put`, `form.patch`, or `form.delete` as a native form action. For an awaitable mutation, use `action()`. In Vue, Svelte, and Solid, form submissions return `Promise<void>`; catch thrown errors or use your framework's error handling.
 
 For dynamic routes, pass `params` in the options:
 
 ```ts
 // pages/users/[id].server.ts has an action
 const form = useForm('/users/:id', { name: '' }, { params: { id: '42' } });
-<form action={form.put}>{/* submits to /users/42 */}</form>
+<Form form={form} method="put">{/* submits to /users/42 */}</Form>
 ```
 
 ### Named Actions with `useForm`
@@ -260,24 +222,20 @@ When a page exports named actions, append `?actionName` to the URL:
 
 ```ts
 const form = useForm('/users/:id?update', { name: '' }, { params: { id } });
-<form action={form.put}>{/* submits to /users/42?update */}</form>
+<Form form={form} method="put">{/* submits to /users/42?update */}</Form>
 ```
 
 Each named action has its own validator schema, which supplies types for its URL, body, and error keys. See [Type Safety](../type-safety#action-%E2%86%92-useform) for an example.
 
 ## `action()` Helper
 
-For one-shot mutations that do not need form state such as dirty tracking, reset, or field-level errors, use `action()` instead of `useForm`. It sends a request to a page action and triggers an Inertia page update, just like `useForm`, but without the reactive form object:
+Use `action()` for a button or other mutation that does not need form state. It updates the page after a successful request:
 
 ```ts
-import { useForm, action } from '@void/react'; // or "@void/vue", "@void/svelte", "@void/solid"
-
-// Form with state + Inertia page update
-const form = useForm('/?create-user', { name: '', email: '' });
+import { action } from '@void/react'; // or "@void/vue", "@void/svelte", "@void/solid"
 
-// Programmatic call + Inertia page update (no form state)
-const result = await action('/?delete-user', {
-  data: { id: 42 },
+const result = await action('/users/:id?delete', {
+  params: { id: '42' },
   method: 'DELETE',
 });
 if (!result.ok) {
@@ -285,17 +243,17 @@ if (!result.ok) {
 }
 ```
 
-Call `action()` from a button or another event handler when you don't need form state. It defaults to `POST`; pass `{ data, method, params }` to set the body, route parameters, or a `PUT`, `PATCH`, or `DELETE` method.
+`action()` defaults to `POST`. Pass `data`, `params`, and `method` to set the body, route parameters, or HTTP method.
 
 A successful call returns `{ ok: true, pageData }`. Expected errors, such as validation failures or conflicts, return `{ ok: false, error }`.
 
 ## Validation Errors
 
-When an action throws a `ValidationError`, or validation fails through `withValidator`, the errors are automatically available on `form.errors`. You do not need to wire that up manually.
+`withValidator()` and `ValidationError` populate `form.errors` automatically.
 
 Expected errors such as `400`, `404`, `409`, `422`, and `429` stay with the form or action call. `useForm` stores them in `form.errors` or `form.error`; `action()` returns `{ ok: false, error }`.
 
-Authentication errors (`401`, `403`), server errors (`500`, `502`), and unknown network or protocol failures are thrown. Handle them with your framework's error boundary or error handling.
+Authentication errors (`401`, `403`), server errors (`500`, `502`), and unexpected failures are thrown. Handle them with your framework's error boundary or error handling.
 
 Actions can throw `ValidationError` for custom validation logic:
 
@@ -311,26 +269,28 @@ export const action = defineHandler(async (c) => {
 });
 ```
 
-Or use `withValidator()` for automatic schema-based validation. Errors are returned in the same format.
+## Authentication and origin checks
+
+Browser submissions must come from the same origin as the page, including its scheme, hostname, and port. Void rejects cross-origin page actions with `403 Forbidden`. Server clients can call actions without browser origin headers; actions still need authentication and authorization for protected data.
 
 ## File Uploads
 
-`useForm` automatically detects `File`, `Blob`, and `FileList` values in form data and sends the request as `multipart/form-data` instead of JSON. No extra configuration is needed. Set a file on the form data and submit.
+Set a `File`, `Blob`, or `FileList` in form data and submit. `useForm` sends it as `multipart/form-data`:
 
 ::: code-group
 
 ```tsx [React]
-import { useForm } from '@void/react';
+import { Form, useForm } from '@void/react';
 
 export default function Upload() {
   const form = useForm('/photos', { title: '', photo: null as File | null });
 
   return (
-    <form action={form.post}>
+    <Form form={form}>
       <input value={form.data.title} onChange={(e) => form.setData('title', e.target.value)} />
       <input type="file" onChange={(e) => form.setData('photo', e.target.files?.[0] ?? null)} />
       <button disabled={form.pending}>Upload</button>
-    </form>
+    </Form>
   );
 }
 ```
@@ -338,7 +298,7 @@ export default function Upload() {
 ```vue [Vue]
 <script setup lang="ts">
 import { ref } from 'vue';
-import { useForm } from '@void/vue';
+import { Form, useForm } from '@void/vue';
 
 const form = useForm('/photos', { title: '', photo: null as File | null });
 const fileInput = ref<HTMLInputElement>();
@@ -349,45 +309,40 @@ function onFileChange() {
 </script>
 
 <template>
-  <form @submit.prevent="form.post()">
+  <Form :form="form">
     <input v-model="form.data.title" />
     <input type="file" ref="fileInput" @change="onFileChange" />
     <button :disabled="form.pending">Upload</button>
-  </form>
+  </Form>
 </template>
 ```
 
 ```svelte [Svelte]
 <script>
-  import { useForm } from "@void/svelte";
+  import { Form, useForm } from "@void/svelte";
 
   const form = useForm("/photos", { title: "", photo: null });
 </script>
 
-<form onsubmit={(e) => { e.preventDefault(); return form.post(); }}>
+<Form {form}>
   <input bind:value={form.data.title} />
   <input type="file" onchange={(e) => { form.data.photo = e.target.files?.[0] ?? null; }} />
   <button disabled={form.pending}>Upload</button>
-</form>
+</Form>
 ```
 
 ```tsx [Solid]
-import { useForm } from '@void/solid';
+import { Form, useForm } from '@void/solid';
 
 export default function Upload() {
   const form = useForm('/photos', { title: '', photo: null as File | null });
 
   return (
-    <form
-      onSubmit={(e) => {
-        e.preventDefault();
-        return form.post();
-      }}
-    >
+    <Form form={form}>
       <input value={form.data.title} onInput={(e) => form.setData('title', e.target.value)} />
       <input type="file" onChange={(e) => form.setData('photo', e.target.files?.[0] ?? null)} />
       <button disabled={form.pending}>Upload</button>
-    </form>
+    </Form>
   );
 }
 ```
@@ -414,10 +369,8 @@ export const action = defineHandler(async (c) => {
 
 ## Choosing a Primitive
 
-| Primitive  | Inertia page update | Form state                 | Framework-specific |
-| ---------- | ------------------- | -------------------------- | ------------------ |
-| `useForm`  | Yes                 | Yes (errors, dirty, reset) | Yes                |
-| `action()` | Yes                 | No                         | Yes                |
-| `fetch()`  | No (raw response)   | No                         | No                 |
-
-Use `useForm` when you have a form with inputs. Use `action()` for programmatic mutations (delete buttons, toggles), optionally passing `{ method }` for non-POST actions. Use `fetch()` when you need the raw response and don't want Inertia page updates.
+| Primitive        | Page update | Form state                 | Framework-specific |
+| ---------------- | ----------- | -------------------------- | ------------------ |
+| `useForm`        | Yes         | Yes (errors, dirty, reset) | Yes                |
+| `action()`       | Yes         | No                         | Yes                |
+| Native `fetch()` | No          | No                         | No                 |

package/skills/void/docs/guide/pages-routing/head.md

@@ -4,9 +4,9 @@ outline: deep
 
 # Head Management
 
-Pages mode manages `<head>` tags (title, meta, links, scripts, HTML/body attributes) across three layers with clear precedence: **page > middleware > config**.
+Set page titles and metadata with `head()`, middleware, or site-wide defaults. Page values take precedence over middleware and config.
 
-## Page `head()` Export
+## Page titles and metadata
 
 Export a `head()` function from your `.server.ts` file. It receives the Hono context and the resolved loader props, and returns a `HeadDescriptor`:
 
@@ -37,7 +37,7 @@ export const head = defineHead<Props>((c, props) => {
 
 `head()` runs server-side only, after the loader resolves.
 
-## Config Defaults
+## Site defaults
 
 Set site-wide head defaults in `void.config.ts`:
 
@@ -56,9 +56,9 @@ Set site-wide head defaults in `void.config.ts`:
 
 `titleTemplate` wraps the page title. `%s` is replaced with whatever `head()` returns as `title`. A page returning `{ title: "About" }` with the template above produces `<title>About | My Site</title>`.
 
-## Middleware Defaults
+## Middleware defaults
 
-Middleware can inject head defaults that apply to every page. This is useful for things like a theme script that must run before first paint:
+Set `headDefaults` in middleware to apply defaults to every page. For example, a theme script can run before first paint:
 
 ```ts
 // middleware/01.head.ts
@@ -77,7 +77,7 @@ export default defineMiddleware(async (c, next) => {
 });
 ```
 
-## Merge Precedence
+## Precedence
 
 When multiple layers provide head data, they merge with this precedence:
 
@@ -90,7 +90,7 @@ When multiple layers provide head data, they merge with this precedence:
 | `htmlAttrs` | Shallow merge, page wins conflicts.                                                                                  |
 | `bodyAttrs` | Shallow merge, page wins conflicts.                                                                                  |
 
-## HeadDescriptor Shape
+## HeadDescriptor
 
 ```ts
 interface HeadDescriptor {
@@ -108,7 +108,7 @@ interface HeadDescriptor {
 }
 ```
 
-## Markdown Auto-Head
+## Markdown pages
 
 Markdown pages (`.md` files) automatically generate head tags from frontmatter. You do not need a `.server.ts` file:
 
@@ -123,8 +123,8 @@ Your content here...
 
 This produces `<title>Getting Started</title>` and `<meta name="description" content="Learn how to use Void">`, with `titleTemplate` applied if configured.
 
-## Client-Side Updates
+## Client-side updates
 
-On SPA navigation, head tags update automatically. The framework tracks managed tags with a `data-void-head` attribute and preserves matching tags across navigations, so unchanged stylesheet and preload links are not torn down and re-added. Tags that are no longer present are removed, and new tags are inserted.
+Titles, meta tags, and links update automatically on client-side navigation.
 
 `script`, `htmlAttrs`, and `bodyAttrs` are SSR-only. They are not re-applied on client-side navigation.

package/skills/void/docs/guide/pages-routing/islands.md

@@ -55,13 +55,7 @@ Islands mode builds on top of [Pages Routing](./overview). You need a working Pa
 
 ## When to Use Islands
 
-Islands mode is a good fit when:
-
-- **Most of your page is static content:** blog posts, marketing pages, or documentation
-- **Only a few components need interactivity:** a counter, a form, or a live widget
-- **Performance is critical:** you want near-zero JavaScript for static content
-
-If your entire page is interactive (dashboards, apps with lots of client state), stick with regular [Pages Routing](./overview).
+Use islands for blogs, marketing pages, or documentation with a few interactive components. For dashboards and apps with shared client state, use regular [Pages Routing](./overview).
 
 ## Creating an Island Page
 
@@ -69,12 +63,9 @@ Name your page file with the `.island` suffix:
 
 <FileTree :items="islandItems" adapter-tabs default-expanded />
 
-The `.island` suffix tells Void to:
+Island pages render as HTML and hydrate only the components you mark as islands. Navigation uses full page loads.
 
-1. **Server-render the full page** as static HTML (no `data-page` attribute, no Void Router)
-2. **Only hydrate** the components you explicitly mark as islands
-3. **Skip the Inertia protocol:** navigation between island pages uses full page loads
-4. **Auto-prerender:** island pages with no `loader` and no dynamic params are automatically [prerendered](/guide/edge/prerendering) at deploy time. Opt out with `export const prerender = false` in the companion `.server.ts` file.
+Pages without a loader or dynamic parameters are automatically [prerendered](/guide/edge/prerendering). Opt out with `export const prerender = false` in the companion `.server.ts` file.
 
 ## Marking Components as Islands
 
@@ -353,30 +344,9 @@ export default function PostForm() {
 
 :::
 
-`useIslandForm` returns the same shape as `useForm`:
-
-| Property                  | Type                      | Description                                |
-| ------------------------- | ------------------------- | ------------------------------------------ |
-| `data`                    | `T`                       | Reactive form state                        |
-| `setData(field, value)`   | Function                  | Update a field                             |
-| `errors`                  | `Record<string, string>`  | Validation errors from 422 responses       |
-| `error`                   | `VoidActionError \| null` | Non-validation call-site action error      |
-| `pending`                 | `boolean`                 | Submission in progress                     |
-| `hasChanges`              | `boolean`                 | Form has unsaved changes                   |
-| `wasSuccessful`           | `boolean`                 | Last submission succeeded                  |
-| `recentlySuccessful`      | `boolean`                 | Success within last 2 seconds              |
-| `reset(...fields?)`       | Function                  | Reset to defaults (all or specific fields) |
-| `clearErrors(...fields?)` | Function                  | Clear errors (all or specific fields)      |
-| `clearError()`            | Function                  | Clear the non-validation call-site error   |
-| `post(url)`               | Function                  | Submit via POST                            |
-| `put(url)`                | Function                  | Submit via PUT                             |
-| `patch(url)`              | Function                  | Submit via PATCH                           |
-| `delete(url)`             | Function                  | Submit via DELETE                          |
-
-The submit helpers return `Promise<void>` so callers and framework event
-handlers can observe boundary-class failures. On success (200), the page reloads.
-On validation error (422), `errors` is populated from the response
-`{ errors: { field: "message" } }`. On redirect, the browser follows it.
+`useIslandForm` provides the same state and methods as [`useForm`](./actions-and-forms#useform). Use `post`, `put`, `patch`, or `delete` with the action URL to submit.
+
+Successful submissions reload the page; redirects navigate to their destination. A `422` response populates `errors` from `{ errors: { field: "message" } }`. Submit helpers return `Promise<void>`.
 
 ## Navigation