void 0.1.6 → 0.7.0

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

@@ -0,0 +1,362 @@
+---
+outline: deep
+---
+
+<script setup>
+function layoutBasicItems(ext) {
+  return [
+    {
+      name: "pages/",
+      children: [
+        { name: `layout${ext}`, description: "Root layout (nav, footer)" },
+        { name: `index${ext}` },
+        {
+          name: "users/",
+          children: [
+            { name: `layout${ext}`, description: "Nested layout for /users/*" },
+            { name: `index${ext}` },
+            { name: `[id]${ext}` },
+          ],
+        },
+      ],
+    },
+  ]
+}
+
+function namedLayoutItems(ext) {
+  return [
+    {
+      name: "pages/",
+      children: [
+        {
+          name: "_layouts/",
+          children: [
+            { name: `landing${ext}`, description: 'named "landing"' },
+            { name: `post${ext}`, description: 'named "post"' },
+          ],
+        },
+        { name: `layout${ext}`, description: "default root layout" },
+        { name: `index${ext}` },
+        {
+          name: "blog/",
+          children: [
+            { name: "hello.md", description: "layout: post" },
+            { name: "archive.md", description: "layout: landing" },
+          ],
+        },
+        { name: `pricing${ext}`, description: "layout: !landing (exclusive)" },
+      ],
+    },
+  ]
+}
+
+function blogLayoutItems(ext) {
+  return [
+    {
+      name: "pages/",
+      children: [
+        {
+          name: "_layouts/",
+          children: [
+            { name: `post${ext}`, description: "sidebar, date, author" },
+          ],
+        },
+        { name: `layout${ext}`, description: "nav + footer" },
+        {
+          name: "blog/",
+          children: [
+            { name: `layout${ext}`, description: "blog sidebar" },
+            { name: "hello.md", description: "layout: post → chain: [root, _layouts/post]" },
+            { name: `archive${ext}`, description: "(no layout) → chain: [root, blog/layout]" },
+          ],
+        },
+      ],
+    },
+  ]
+}
+
+</script>
+
+# Layouts & Shared Data
+
+## Layouts
+
+Place a layout file in any `pages/` directory to wrap all pages in that subtree:
+
+<FileTree :items="layoutBasicItems" adapter-tabs default-expanded />
+
+::: code-group
+
+```tsx [React]
+// pages/layout.tsx
+import { useShared, Link } from '@void/react';
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  const { auth } = useShared();
+  return (
+    <>
+      <nav>
+        <Link href="/">Home</Link>
+        <Link href="/users">Users</Link>
+        {auth?.user && <span>{auth.user.name}</span>}
+      </nav>
+      <main>{children}</main>
+    </>
+  );
+}
+```
+
+```vue [Vue]
+<!-- pages/layout.vue -->
+<script setup lang="ts">
+import { useShared, Link } from '@void/vue';
+const { auth } = useShared();
+</script>
+
+<template>
+  <nav>
+    <Link href="/">Home</Link>
+    <Link href="/users">Users</Link>
+    <span v-if="auth?.user">{{ auth.user.name }}</span>
+  </nav>
+  <main>
+    <slot />
+  </main>
+</template>
+```
+
+```svelte [Svelte]
+<!-- pages/layout.svelte -->
+<script>
+  import { useShared, Link } from "@void/svelte";
+  let { children } = $props();
+  const { auth } = useShared();
+</script>
+
+<nav>
+  <Link href="/">Home</Link>
+  <Link href="/users">Users</Link>
+  {#if auth?.user}<span>{auth.user.name}</span>{/if}
+</nav>
+<main>
+  {@render children()}
+</main>
+```
+
+```tsx [Solid]
+// pages/layout.tsx
+import { useShared, Link } from '@void/solid';
+import type { JSX } from 'solid-js';
+
+export default function Layout(props: { children: JSX.Element }) {
+  const shared = useShared<{ auth: { user: { name: string } | null } }>();
+  return (
+    <>
+      <nav>
+        <Link href="/">Home</Link>
+        <Link href="/users">Users</Link>
+        {shared.auth?.user && <span>{shared.auth.user.name}</span>}
+      </nav>
+      <main>{props.children}</main>
+    </>
+  );
+}
+```
+
+:::
+
+When a page renders, the layout wraps it. The page component is injected as the layout's children in React, Solid, and Svelte, or as a slot in Vue:
+
+<img src="./layout-nesting.svg" alt="Layout nesting diagram: pages/layout wraps pages/users/layout wraps pages/users/[id] page component" style="max-width: 520px; width: 100%;" />
+
+Layouts nest automatically and persist across navigations within their subtree, so component state is preserved.
+
+## Named Layouts
+
+Named layouts let individual pages opt into a different layout without changing the URL structure. Define them in `_layouts/` directories within `pages/`:
+
+<FileTree :items="namedLayoutItems" adapter-tabs default-expanded />
+
+### Selecting a named layout
+
+Export a `layout` constant from any page:
+
+::: code-group
+
+```tsx [React]
+export const layout = 'landing';
+
+export default function Page() {
+  return <div>This page uses the landing layout</div>;
+}
+```
+
+```vue [Vue]
+<script>
+export const layout = 'landing';
+</script>
+
+<template>
+  <div>This page uses the landing layout</div>
+</template>
+```
+
+```svelte [Svelte]
+<script context="module">
+export const layout = "landing";
+</script>
+
+<div>This page uses the landing layout</div>
+```
+
+```tsx [Solid]
+export const layout = 'landing';
+
+export default function Page() {
+  return <div>This page uses the landing layout</div>;
+}
+```
+
+:::
+
+For markdown pages, use frontmatter:
+
+```md
+---
+layout: post
+---
+
+# My Blog Post
+```
+
+### Layout modes
+
+| Value        | Behavior                                                                       |
+| ------------ | ------------------------------------------------------------------------------ |
+| `"landing"`  | Replace the innermost layout in the chain. Outer ancestor layouts still apply. |
+| `"!landing"` | Replace the **entire** chain. Only the named layout wraps the page.            |
+| `false`      | No layout wrapping at all. Page renders standalone.                            |
+
+"Innermost" means the deepest layout in the resolved chain. If the chain is `[root, docs/layout]`, the named layout replaces `docs/layout`. If the chain is only `[root]`, it replaces root.
+
+### Resolution order
+
+When a page specifies `layout: "post"`, the scanner walks up the directory tree to find `_layouts/post`:
+
+```
+pages/guide/intro.md  (layout: post)
+
+1. pages/guide/_layouts/post.vue  → not found
+2. pages/_layouts/post.vue        → found ✓
+```
+
+Closest ancestor wins, same as default layout chain. If no matching named layout is found in any ancestor, the build fails with a clear error.
+
+### Examples
+
+**Blog with shared nav but post-specific layout:**
+
+<FileTree :items="blogLayoutItems" adapter-tabs default-expanded />
+
+`layout: post` on `blog/hello.md` replaces the innermost default layout (`blog/layout`) with `_layouts/post`. The root layout still wraps.
+
+**Fullscreen page with no layout:**
+
+::: code-group
+
+```tsx [React]
+export const layout = false;
+
+export default function Landing() {
+  return (
+    <div className="hero fullscreen">
+      <h1>Welcome</h1>
+    </div>
+  );
+}
+```
+
+```vue [Vue]
+<script>
+export const layout = false;
+</script>
+
+<template>
+  <div class="hero fullscreen"><h1>Welcome</h1></div>
+</template>
+```
+
+:::
+
+**Exclusive layout (skip all ancestors):**
+
+```md
+---
+layout: '!landing'
+---
+
+# Standalone Landing Page
+```
+
+Only `_layouts/landing` wraps this page, and the root layout is skipped entirely.
+
+## Shared Data
+
+Middleware can inject data available on every page via `c.set("shared", {...})`. Augment `CloudContextVariables` to type the shared data, and `useShared()` will infer the type automatically:
+
+```ts
+// middleware/01.auth.ts
+import { defineMiddleware } from 'void';
+
+declare module 'void' {
+  interface CloudContextVariables {
+    shared: { auth: { user: { name: string } | null } };
+  }
+}
+
+export default defineMiddleware(async (c, next) => {
+  const user = await getSessionUser(c);
+  c.set('shared', { auth: { user } });
+  await next();
+});
+```
+
+Access it on the client with `useShared()`. The return type is inferred from your augmentation:
+
+::: code-group
+
+```tsx [React]
+import { useShared } from '@void/react';
+
+export default function Page() {
+  const { auth } = useShared(); // { auth: { user: { name: string } | null } }
+  return <p>Hello, {auth?.user?.name}</p>;
+}
+```
+
+```vue [Vue]
+<script setup lang="ts">
+import { useShared } from '@void/vue';
+const { auth } = useShared(); // { auth: { user: { name: string } | null } }
+</script>
+```
+
+```svelte [Svelte]
+<script>
+  import { useShared } from "@void/svelte";
+  const { auth } = useShared(); // { auth: { user: { name: string } | null } }
+</script>
+```
+
+```tsx [Solid]
+import { useShared } from '@void/solid';
+
+export default function Page() {
+  const shared = useShared(); // { auth: { user: { name: string } | null } }
+  return <p>Hello, {shared.auth?.user?.name}</p>;
+}
+```
+
+:::
+
+Shared data is separate from page props. Props come from the loader, while `useShared()` returns global data from middleware. See [Type Safety](../type-safety.md#context-variables) for more on augmenting `CloudContextVariables`.

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

@@ -0,0 +1,267 @@
+---
+outline: deep
+---
+
+# Loaders & Props
+
+Every page can have a companion `.server.ts` file that exports a `loader`. Server handlers use the same `defineHandler` API as [server routes](../server-routing.md), so you get the same typed `c.env` bindings and Hono context methods.
+
+## Defining a Loader
+
+`loader` runs on GET requests and returns an object that becomes the page's props:
+
+```ts
+// pages/users/index.server.ts
+import { defineHandler } from 'void';
+import type { InferProps } from 'void';
+import { db } from 'void/db';
+import { users } from '@schema';
+
+export type Props = InferProps<typeof loader>; // [!code highlight]
+
+export const loader = defineHandler(async (c) => {
+  return { users: await db.select().from(users) };
+});
+```
+
+`InferProps` extracts the return type from a `defineHandler` call, so you don't need to maintain a separate interface. You can also write the interface explicitly if you prefer:
+
+```ts
+export interface Props {
+  users: Array<{ id: number; name: string; email: string }>;
+}
+
+export const loader = defineHandler<Props>(async (c) => {
+  return { users: await db.select().from(users) };
+});
+```
+
+## Using the Data in Page Components
+
+The component receives loader data as props. Export the props type from your `.server.ts` file to keep the contract in one place:
+
+::: code-group
+
+```tsx [React]
+// pages/users/index.tsx
+import type { Props } from './index.server';
+
+export default function UsersPage({ users }: Props) {
+  return (
+    <ul>
+      {users.map((u) => (
+        <li key={u.id}>{u.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+```vue [Vue]
+<!-- pages/users/index.vue -->
+<script setup lang="ts">
+import type { Props } from './index.server';
+defineProps<Props>();
+</script>
+
+<template>
+  <h1>Users</h1>
+  <ul>
+    <li v-for="u in users" :key="u.id">{{ u.name }}</li>
+  </ul>
+</template>
+```
+
+```svelte [Svelte]
+<!-- pages/users/index.svelte -->
+<script lang="ts">
+  import type { Props } from "./index.server";
+
+  let { users }: Props = $props();
+</script>
+
+<h1>Users</h1>
+<ul>
+  {#each users as u (u.id)}
+    <li>{u.name}</li>
+  {/each}
+</ul>
+```
+
+```tsx [Solid]
+// pages/users/index.tsx
+import type { Props } from './index.server';
+import { For } from 'solid-js';
+
+export default function UsersPage(props: Props) {
+  return (
+    <>
+      <h1>Users</h1>
+      <ul>
+        <For each={props.users}>{(u) => <li>{u.name}</li>}</For>
+      </ul>
+    </>
+  );
+}
+```
+
+:::
+
+## Deferred Props
+
+Loaders sometimes need to fetch slower data such as analytics, external API responses, or AI inference. `defer()` lets you return a placeholder immediately so the page renders quickly, then streams the real data when it resolves:
+
+```ts
+// pages/dashboard.server.ts
+import { defineHandler, defer } from 'void';
+import type { InferProps } from 'void';
+import { db } from 'void/db';
+import { projects } from '@schema';
+
+export type Props = InferProps<typeof loader>;
+
+export const loader = defineHandler(async (c) => {
+  const allProjects = await db.select().from(projects); // fast, returns immediately
+  return {
+    projects: allProjects,
+    usage: defer(async () => {
+      return await fetchUsageMetrics(); // slow, streams when ready
+    }),
+  };
+});
+```
+
+The page renders immediately with `projects` available. The `usage` prop is a framework-native deferred resource: React consumes it with Suspense and `use()`, while the other adapters expose a `{ loading, value, error }` state object.
+
+### Handling Deferred State
+
+In React, `Deferred<T>` is consumed as a promise. Put the deferred read under a `<Suspense>` boundary and call `use()` where the value is needed:
+
+::: code-group
+
+```tsx [React]
+import { Suspense, use } from '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({ projects, usage }: Props) {
+  return (
+    <div>
+      <h1>Projects ({projects.length})</h1>
+      <Suspense fallback={<p>Loading usage...</p>}>
+        <Usage usage={usage} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+:::
+
+Rejected deferred props throw from `use()`. Put a normal React error boundary
+around the Suspense boundary when the page should render a custom failure state.
+For explicit React prop annotations, import `Deferred` from `@void/react`; the
+adapter export is typed as `Promise<T>`.
+
+In Vue, Svelte, and Solid, `Deferred<T>` behaves as a [discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions) with three states:
+
+```ts
+type Deferred<T> =
+  | { loading: true; value: null; error: null } // pending
+  | { loading: false; value: T; error: null } // resolved
+  | { loading: false; value: null; error: Error }; // rejected
+```
+
+Check `loading` first, then `error`. TypeScript narrows `value` to `T` in the resolved branch:
+
+::: code-group
+
+```vue [Vue]
+<script setup lang="ts">
+import type { Props } from './dashboard.server';
+defineProps<Props>();
+</script>
+
+<template>
+  <div>
+    <h1>Projects ({{ projects.length }})</h1>
+    <p v-if="usage.loading">Loading usage...</p>
+    <p v-else-if="usage.error">Failed: {{ usage.error.message }}</p>
+    <p v-else>{{ usage.value.requests }} requests</p>
+  </div>
+</template>
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import type { Props } from "./dashboard.server";
+  let { projects, usage }: Props = $props();
+</script>
+
+<div>
+  <h1>Projects ({projects.length})</h1>
+  {#if usage.loading}
+    <p>Loading usage...</p>
+  {:else if usage.error}
+    <p>Failed: {usage.error.message}</p>
+  {:else}
+    <p>{usage.value.requests} requests</p>
+  {/if}
+</div>
+```
+
+```tsx [Solid]
+import type { Props } from './dashboard.server';
+
+export default function Dashboard(props: Props) {
+  return (
+    <div>
+      <h1>Projects ({props.projects.length})</h1>
+      {props.usage.loading ? (
+        <p>Loading usage...</p>
+      ) : props.usage.error ? (
+        <p>Failed: {props.usage.error.message}</p>
+      ) : (
+        <p>{props.usage.value.requests} requests</p>
+      )}
+    </div>
+  );
+}
+```
+
+:::
+
+### How Streaming Works
+
+On the initial page load (SSR), React uses React 19 streaming SSR and renders the nearest Suspense fallback for deferred props; the other adapters render their loading state. As each deferred function resolves, the server streams an inline `<script>` tag that delivers the data, so no extra HTTP request is needed. On SPA navigation, deferred data streams via NDJSON over the same response.
+
+### Deferred Props After Mutations
+
+::: info
+When a mutation runs, the loader runs again to provide fresh props, but deferred props cannot stream over a mutation response. The client preserves the last resolved value for each deferred prop, so the UI keeps showing the previous data until the next full page load or SPA navigation.
+:::
+
+### Grouped Deferred Props
+
+When multiple props depend on the same slow operation, use a named group to resolve them together with a single function call:
+
+```ts
+export const loader = defineHandler<Props>(async (c) => {
+  const analyticsResolver = async () => {
+    const data = await fetchAnalytics(); // one slow call
+    return { metrics: data.metrics, chart: data.chart };
+  };
+
+  return {
+    projects: await db.select().from(projects),
+    metrics: defer('analytics', analyticsResolver),
+    chart: defer('analytics', analyticsResolver),
+  };
+});
+```
+
+Both `metrics` and `chart` resolve from a single invocation of the analytics resolver. The component receives them as separate `Deferred<T>` props.