@void/react 0.0.0

package/README.md

@@ -0,0 +1,216 @@
+# @void/react
+
+React adapter for Void Pages mode.
+
+## Setup
+
+`@void/react` requires React 19.
+
+```ts
+import { defineConfig } from 'vite';
+import { voidPlugin } from 'void';
+import { voidReact } from '@void/react/plugin';
+
+export default defineConfig({
+  plugins: [voidPlugin(), voidReact()],
+});
+```
+
+## 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()`
+- `useNavigation()`
+- `useShared()`
+- `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.
+
+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 { 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 action={form.post}>
+      <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.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.
+
+### `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' }));
+```
+
+## Tests
+
+- `test/unit/use-form.test.ts`
+- `test/unit/link.test.ts`
+- `test/integration/react-pages-client.test.ts`
+
+Cross-package SSR/protocol coverage for React pages mode also lives in `framework/packages/void/test/integration/*`.

package/dist/action-BFWtavbf.mjs

@@ -0,0 +1,29 @@
+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 };

package/dist/context-BCeFV8Jy.mjs

@@ -0,0 +1,9 @@
+import { createContext } from "react";
+import { idleNavigationState } from "void/pages-client";
+//#region src/runtime/context.ts
+const SharedContext = createContext(null);
+const ErrorsContext = createContext(null);
+const RouterContext = createContext(null);
+const NavigationContext = createContext(idleNavigationState());
+//#endregion
+export { SharedContext as i, NavigationContext as n, RouterContext as r, ErrorsContext as t };

package/dist/index-6hxGVqsE.d.mts

@@ -0,0 +1,125 @@
+import { AnchorHTMLAttributes, ButtonHTMLAttributes, Context, JSX } from "react";
+import { ActionResult, NavigationState, VoidActionError, VoidRouter } from "void/pages-client";
+import { CloudContextVariables, InferProps } from "void";
+import { ActionFormOptions, ActionUrl, ResolveActionBody, ResolveActionParams } from "void/routes";
+
+//#region src/runtime/link.d.ts
+type PrefetchStrategy = "hover" | "click" | "mount" | "visible";
+type LinkMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+type CommonProps = {
+  href: string;
+  method?: LinkMethod | Lowercase<LinkMethod>;
+  data?: Record<string, unknown>;
+  preserveScroll?: boolean;
+  preserveState?: boolean;
+  replace?: boolean;
+  reloadDocument?: boolean;
+  viewTransition?: boolean;
+  prefetch?: boolean | PrefetchStrategy | Array<PrefetchStrategy>;
+  cacheFor?: number | string | [string, string];
+  onNavigate?: (event: {
+    preventDefault(): void;
+  }) => void;
+};
+type LinkProps = CommonProps & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, keyof CommonProps> & Omit<ButtonHTMLAttributes<HTMLButtonElement>, keyof CommonProps>;
+declare function Link({
+  href,
+  method,
+  data,
+  preserveScroll,
+  preserveState,
+  replace,
+  reloadDocument,
+  viewTransition,
+  prefetch: prefetchProp,
+  cacheFor,
+  onNavigate,
+  children,
+  style,
+  onClick: onClickProp,
+  onMouseEnter: onMouseEnterProp,
+  onMouseLeave: onMouseLeaveProp,
+  onFocus: onFocusProp,
+  onMouseDown: onMouseDownProp,
+  onTouchStart: onTouchStartProp,
+  ...rest
+}: LinkProps): JSX.Element;
+//#endregion
+//#region src/runtime/use-router.d.ts
+declare function useRouter(): VoidRouter;
+//#endregion
+//#region src/runtime/use-shared.d.ts
+declare function useShared<T = CloudContextVariables["shared"]>(): T;
+//#endregion
+//#region src/runtime/use-form.d.ts
+declare function useForm<U extends ActionUrl & string>(url: U, defaults: ResolveActionBody<U>, options?: ActionFormOptions<U>): {
+  data: ResolveActionBody<U>;
+  setData: <K extends keyof ResolveActionBody<U> & string>(field: K, value: ResolveActionBody<U>[K]) => void;
+  errors: Partial<Record<keyof ResolveActionBody<U> & string, string>>;
+  error: VoidActionError | null;
+  pending: boolean;
+  hasChanges: boolean;
+  wasSuccessful: boolean;
+  recentlySuccessful: boolean;
+  post(formData: FormData): void;
+  put(formData: FormData): void;
+  patch(formData: FormData): void;
+  delete(formData: FormData): void;
+  reset(...fields: Array<keyof ResolveActionBody<U> & string>): void;
+  clearErrors(...fields: Array<keyof ResolveActionBody<U> & string>): void;
+  clearError(): void;
+};
+//#endregion
+//#region src/runtime/use-navigation.d.ts
+declare function useNavigation(): NavigationState;
+//#endregion
+//#region src/runtime/use-island-form.d.ts
+interface IslandFormReturn<T extends Record<string, unknown>> {
+  data: T;
+  setData: <K extends keyof T & string>(field: K, value: T[K]) => void;
+  errors: Record<string, string>;
+  error: VoidActionError | null;
+  pending: boolean;
+  hasChanges: boolean;
+  wasSuccessful: boolean;
+  recentlySuccessful: boolean;
+  reset: (...fields: Array<keyof T & string>) => void;
+  clearErrors: (...fields: Array<string>) => void;
+  clearError: () => void;
+  post: (url: string) => Promise<void>;
+  put: (url: string) => Promise<void>;
+  patch: (url: string) => Promise<void>;
+  delete: (url: string) => Promise<void>;
+}
+/**
+* Form hook for island pages. Uses fetch + page reload instead of the
+* Void Router (which is not available in island mode).
+*/
+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>;
+//#endregion
+//#region src/runtime/context.d.ts
+declare const SharedContext: Context<Record<string, unknown> | null>;
+declare const ErrorsContext: Context<Record<string, string> | null>;
+declare const RouterContext: Context<VoidRouter | null>;
+declare const NavigationContext: Context<NavigationState>;
+//#endregion
+//#region src/runtime/index.d.ts
+type Deferred<T> = Promise<T>;
+//#endregion
+export { RouterContext as a, setActionRouter as c, useForm as d, useShared as f, NavigationContext as i, useIslandForm as l, Link as m, InferProps as n, SharedContext as o, useRouter as p, ErrorsContext as r, action as s, Deferred as t, useNavigation as u };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { a as RouterContext, c as setActionRouter, d as useForm, f as useShared, i as NavigationContext, l as useIslandForm, m as Link, n as InferProps, o as SharedContext, p as useRouter, r as ErrorsContext, s as action, t as Deferred, u as useNavigation } from "./index-6hxGVqsE.mjs";
+export { Deferred, ErrorsContext, InferProps, Link, NavigationContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useRouter, useShared };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { i as SharedContext, n as NavigationContext, r as RouterContext, t as ErrorsContext } from "./context-BCeFV8Jy.mjs";
+import { a as useRouter, i as useShared, n as useNavigation, o as Link, r as useForm, t as useIslandForm } from "./runtime-C24S_Dlg.mjs";
+import { n as setActionRouter, t as action } from "./action-BFWtavbf.mjs";
+export { ErrorsContext, Link, NavigationContext, RouterContext, SharedContext, action, setActionRouter, useForm, useIslandForm, useNavigation, useRouter, useShared };

package/dist/plugin.d.mts

@@ -0,0 +1,16 @@
+import react from "@vitejs/plugin-react";
+import { Plugin } from "vite";
+
+//#region src/plugin.d.ts
+interface PrefetchConfig {
+  hoverDelay?: number;
+  cacheFor?: number | string | [string, string];
+}
+interface VoidReactOptions {
+  react?: Parameters<typeof react>[0];
+  viewTransitions?: boolean;
+  prefetch?: PrefetchConfig;
+}
+declare function voidReact(options?: VoidReactOptions): Array<Plugin>;
+//#endregion
+export { VoidReactOptions, voidReact };