@void/react 0.24.0 → 0.26.0

package/README.md

@@ -1,10 +1,16 @@
 # @void/react
 
-React adapter for Void Pages mode.
+Build server-rendered Void pages with React, server loaders, and typed forms. Requires React 19.
 
 ## Setup
 
-`@void/react` requires React 19.
+Install alongside `void`:
+
+```sh
+npm install @void/react
+```
+
+Add the adapter to your Vite config. It includes the framework's Vite plugin:
 
 ```ts
 import { defineConfig } from 'vite';
@@ -16,217 +22,6 @@ export default defineConfig({
 });
 ```
 
-## Plugin
-
-`voidReact(options?)` returns:
-
-- `@vitejs/plugin-react`
-- the React pages plugin
-- the React islands plugin
-
-Options:
-
-- `react?` — forwarded to `@vitejs/plugin-react`
-- `viewTransitions?` — enable View Transitions for SPA navigation
-- `prefetch?` — link prefetch behavior
-
-## Runtime
-
-Main runtime APIs live at `@void/react`:
-
-- `Link`
-- `useRouter()`
-- `useParams()`
-- `useNavigation()`
-- `useShared()`
-- `Form` and `useForm()`
-- `useIslandForm()`
-- `action()`
-
-### Async React Routing
-
-React Pages navigations are scheduled as React transitions. Route data,
-component modules, layouts, and deferred props are prepared as resources, then
-revealed through Suspense so the current screen can stay visible while the next
-page loads.
-
-```tsx
-import { Suspense, use } from 'react';
-import { useNavigation, useRouter } from '@void/react';
-import type { Props } from './dashboard.server';
-
-function Usage({ usage }: Pick<Props, 'usage'>) {
-  const resolved = use(usage);
-  return <p>{resolved.requests} requests</p>;
-}
-
-export default function Dashboard({ usage }: Props) {
-  const router = useRouter();
-  const navigation = useNavigation();
-
-  return (
-    <>
-      <button onClick={() => router.refresh()} disabled={navigation.state !== 'idle'}>
-        Refresh
-      </button>
-      <Suspense fallback={<p>Loading usage...</p>}>
-        <Usage usage={usage} />
-      </Suspense>
-    </>
-  );
-}
-```
-
-Breaking change: React deferred props returned from `defer()` are consumed as
-promises with `use()` under a Suspense boundary. The old
-`prop.loading` / `prop.value` shape remains the runtime shape for the Vue,
-Svelte, and Solid adapters.
-
-SSR uses React 19's streaming renderer. Deferred props render the nearest
-Suspense fallback in the initial shell, then Void streams the resolved values to
-the hydrated client. Put deferred reads behind Suspense, and use a normal React
-error boundary around that Suspense boundary when rejected deferred values need a
-custom error state.
-
-Export `ssr = false` from a page's `.server.ts` file to skip server-rendered
-component HTML for that route. The loader still runs and the browser mounts the
-page with the embedded initial props.
-
-For explicit prop annotations in React pages, import `Deferred` from
-`@void/react`:
-
-```ts
-import type { Deferred } from '@void/react';
-
-export interface Props {
-  usage: Deferred<{ requests: number }>;
-}
-```
-
-### Forms and Actions
-
-`useForm()` is built on React Actions. Prefer native form submission with
-`form.post`, `form.put`, `form.patch`, or `form.delete`; use `useFormStatus()`
-inside the form for button pending state.
-
-```tsx
-import { Form, useForm } from '@void/react';
-import { useFormStatus } from 'react-dom';
-
-function SubmitButton() {
-  const { pending } = useFormStatus();
-  return <button disabled={pending}>Save</button>;
-}
-
-export default function CreateUser() {
-  const form = useForm('/users', { name: '', email: '' });
-
-  return (
-    <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>}
-      <SubmitButton />
-    </Form>
-  );
-}
-```
-
-`form.post`, `form.put`, `form.patch`, and `form.delete` are native React form
-actions. Use `action()` for the awaitable imperative escape hatch; it returns
-`{ ok: true, pageData }` or `{ ok: false, error }` for call-site action errors,
-while boundary-class failures are thrown. `action()` uses `POST` by default and
-accepts `{ data, method, params }`.
-
-### `useRouter`
-
-`useRouter()` returns the Void Router. `visit()`, `refresh()`, and `prefetch()`
-are awaitable; `prefetch()` resolves when the page data has been cached.
-
-### `useParams`
-
-`useParams()` returns dynamic route params for the page currently being rendered.
-Use it instead of parsing `useRouter().path` in dynamic Pages routes.
-
-### `Link`
-
-`Link` is the React Pages navigation component. GET links render an `<a>` and
-client-side navigate when the click is safe to intercept. Mutation links render a
-`<button type="button">` and submit through the Void Router.
-
-```tsx
-import { Link } from '@void/react';
-
-<Link href="/users">Users</Link>
-
-<Link href="/users" data={{ page: 2, tag: ['active', 'new'] }}>
-  Filtered users
-</Link>
-
-<Link href="/users" replace>
-  Replace history entry
-</Link>
-
-<Link href="/logout" reloadDocument>
-  Sign out
-</Link>
-
-<Link
-  href="/settings"
-  onNavigate={(event) => {
-    if (!confirm('Leave this page?')) {
-      event.preventDefault();
-    }
-  }}
->
-  Settings
-</Link>
-```
-
-Props:
-
-- `href` — target URL.
-- `method` — `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Defaults to `GET`.
-- `data` — for GET links, primitive values are merged into the query string and arrays become repeated keys. `null` and `undefined` are omitted. Nested objects throw. For non-GET links, `data` is sent as the request body.
-- `prefetch` — `false`, `true`, `"hover"`, `"click"`, `"mount"`, `"visible"`, or an array of strategies. Prefetch is GET-only and throws for non-GET links.
-- `cacheFor` — cache TTL for prefetched page data.
-- `preserveScroll` — keep the current scroll position after navigation.
-- `preserveState` — apply the page update without writing a new URL or history entry.
-- `replace` — replace the current history entry instead of pushing a new one.
-- `reloadDocument` — use browser document navigation. GET-only and throws for non-GET links.
-- `viewTransition` — override the adapter-level View Transition setting for this navigation.
-- `onNavigate` — cancellable callback for client-side navigations. It does not run for external links, downloads, modified clicks, non-`_self` targets, `reloadDocument`, or missing router context.
-
-## Pages
-
-Pages are `.tsx` files in `pages/` with companion `.server.ts` files:
-
-```tsx
-export default function Home({ title }: { title: string }) {
-  return <h1>{title}</h1>;
-}
-```
-
-```ts
-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`
-- `test/integration/react-pages-client.test.ts`
-
-Cross-package SSR/protocol coverage for React pages mode also lives in `packages/void/test/integration/*`.
+Follow [Pages Routing](https://void.cloud/guide/pages-routing/overview) to add pages, then use [loaders](https://void.cloud/guide/pages-routing/loaders), [forms](https://void.cloud/guide/pages-routing/actions-and-forms), and [layouts](https://void.cloud/guide/pages-routing/layouts).
 
-The [shared client](../../test/pages-client-contract.ts) and [island](../../test/pages-island-contract.ts) contracts run against this adapter in both dev and preview. Shared form equality is tested directly in [Void](../void/test/unit/form-value-equality.test.ts); tests do not copy the hook implementation.
+See the [adapter API reference](https://void.cloud/reference/api/pages) for plugin options and runtime helpers, and [TESTING.md](../../TESTING.md) for repository verification.

package/dist/plugin.mjs

@@ -288,8 +288,13 @@ async function hydrateIsland(el, mod, props) {
   const { hydrateRoot } = await import("react-dom/client");
   const React = await import("react");
   const Component = mod.default || mod;
-  hydrateRoot(el, React.createElement(Component, props));
-  el.setAttribute("data-hydrated", "true");
+  function HydratedIsland() {
+    React.useLayoutEffect(() => {
+      el.setAttribute("data-hydrated", "true");
+    }, []);
+    return React.createElement(Component, props);
+  }
+  hydrateRoot(el, React.createElement(HydratedIsland));
 }
 
 initIslands(islands, hydrateIsland);

package/dist/runtime/pages-client.mjs

@@ -207,7 +207,10 @@ function App({ engine, router, viewTransitions, navigationFallback: NavigationFa
 			layouts: engine.initialLayouts
 		}),
 		abort() {},
-		async commit() {},
+		async commit() {
+			engine.commitInitialRender();
+			document.getElementById("app").setAttribute("data-hydrated", "true");
+		},
 		dispose() {}
 	}), [engine, initialPageData]);
 	const [state, dispatch] = useReducer(appReducer, {
@@ -410,7 +413,6 @@ async function startReactPages(config) {
 	viewTransitionWaiters.clear();
 	pendingVisitSettlers.clear();
 	committedResources.clear();
-	committedResources.add(0);
 	activePendingNavigationId = null;
 	const engine = await createPageNavigationEngine({
 		adapter: {
@@ -447,7 +449,6 @@ async function startReactPages(config) {
 		if (!isSsr) createRoot(appEl).render(app);
 		else hydrateRoot(appEl, app);
 	});
-	appEl.setAttribute("data-hydrated", "true");
 	engine.start();
 	return { router };
 }

package/package.json

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