> Source: https://framework.sbesh.com/docs

# hono-preact docs

A small, opinionated full-stack framework. Hono on the edge, Preact in the
browser, manifest driven routes, typed RPC, streaming everywhere.

## Get started

- [Quick start](/docs/quick-start): five-minute walkthrough from `pnpm install` to a deployed page.
- [Project structure](/docs/structure): what each file in a hono-preact project does.

## Routing and layouts

- [Routes](/docs/routes): `defineRoutes()` and the route table.
- [Pages](/docs/pages): view components and `definePage()`.
- [Layouts](/docs/layouts): nested layouts that survive navigation.
- [Vite config](/docs/vite-config): the `honoPreact()` Vite plugin and its options.
- [Active links](/docs/active-links): marking the current route in navigation.
- [View transitions](/docs/view-transitions): animated route changes with the View Transition API.

## Data

- [Loaders](/docs/loaders): server-rendered data with `defineLoader()`.
- [Actions](/docs/actions): mutations via `<Form>` and typed RPC.
- [Optimistic UI](/docs/optimistic-ui): `useOptimistic()` and friends.
- [Loading states](/docs/loading-states): switching on the `LoaderState` status to show skeletons and spinners.
- [Streaming](/docs/streaming): generator loaders, streaming forms, SSE.

## Auth and access

- [Middleware](/docs/middleware): the unified `use` primitive for auth gates, redirects, request-scoped setup, and stream observers.
- [CSRF protection](/docs/csrf): built-in CSRF token validation for forms and mutations.
- [Composing Hono middleware](/docs/hono-middleware): wiring Hono-native middleware and custom routes alongside the framework.

## Operations

- [Prefetch](/docs/prefetch): preloading routes on hover or focus.
- [Link prefetch](/docs/link-prefetch): browser-level speculation rules for near-instant navigation.
- [Reloading](/docs/reloading): invalidating loaders after mutations.
- [`renderPage`](/docs/render-page): the SSR entry point.
- [Deployment](/docs/deployment): shipping to Cloudflare Workers or Node.js.
- [WebSockets](/docs/websockets): full-duplex connections via Hono's WebSocket helper.

## For LLMs and AI tools

These docs are available as plain text for LLMs and AI coding assistants: <a href="/llms.txt" target="_blank" rel="noreferrer noopener"><code>/llms.txt</code></a> is a curated index of every page, and <a href="/llms-full.txt" target="_blank" rel="noreferrer noopener"><code>/llms-full.txt</code></a> is the entire documentation concatenated into one file.

---

Looking for a working app to read? The whole **[demo](/demo)** is built with the framework.


---

> Source: https://framework.sbesh.com/docs/quick-start

# Quick Start

Build a movies list with a server loader and a form action. One example covers the full route-table + view + server pattern.

## Prerequisites

Scaffold a new app. Run it with no arguments to use the interactive wizard, or
pass a directory:

```bash
pnpm create hono-preact my-app
cd my-app
```

The wizard asks for the adapter (Cloudflare Workers or Node), whether to add
`hono-preact-ui` components, and whether to install dependencies and init git.
To script it, pass flags instead (`--adapter node`, `--ui`, `--yes`); with npm,
put them after `--`. See [Build & Deploy](./deployment) for the deployment side.

## Configure Vite

`honoPreact()` requires an `adapter` option; without one it throws a clear "adapter required" error at startup. A minimal `vite.config.ts` looks like:

```ts
import { honoPreact } from 'hono-preact/vite';
import { cloudflareAdapter } from 'hono-preact/adapter-cloudflare';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [honoPreact({ adapter: cloudflareAdapter() })],
});
```

The framework also ships a `nodeAdapter()` from `hono-preact/adapter-node` for non-Cloudflare deployments; see [Build & Deploy](./deployment) for the full picture. See [Vite Config](/docs/vite-config) for all `honoPreact()` options.

Now start the dev server:

```bash
pnpm dev
```

Open `http://localhost:5173`. The dev server runs both the Hono server and the Vite HMR client. The generated `server.tsx` is a one-line call to the framework's `createServerEntry`, which builds the `/__loaders` RPC, the page-action POST handler, the realtime socket upgrade, and the catch-all SSR handler on a single Hono app; `routes.ts` declares every URL in the app and which view (and optional `.server.ts` module) lives at each path.

## 1. Create a view

Create `src/pages/movies.tsx` as a pure component with a default export:

```tsx
import type { FunctionComponent } from 'preact';

const Movies: FunctionComponent = () => {
  return (
    <main>
      <h1>Movies</h1>
    </main>
  );
};

Movies.displayName = 'Movies';

export default Movies;
```

Add it to the `routeTree` array in `src/routes.ts` (the scaffolded file
declares the tree `as const` and registers it, so `useParams` and
`buildPath` stay typed as the table grows):

```ts
const routeTree = [
  // ... existing routes
  { path: '/movies', view: () => import('./pages/movies.js') },
] as const;
```

Open `http://localhost:5173/movies`. You should see "Movies".

> The `view` field is a deferred dynamic import. The framework wraps it with preact-iso's `lazy` for code-splitting. No manual `<Route>` JSX is needed; the framework-generated client entry (`virtual:hono-preact/client`) registers everything from the manifest.

## 2. Add a server loader

Create `src/pages/movies.server.ts`. Loaders are exported in a `serverLoaders` container so the view never needs to import `defineLoader` itself:

```ts
import { defineLoader } from 'hono-preact';

export type Movie = { id: string; title: string };

const store: Movie[] = [
  { id: '1', title: 'The Godfather' },
  { id: '2', title: 'Chinatown' },
];

const getMovies = () => store;

export const serverLoaders = {
  default: defineLoader(async () => ({
    movies: getMovies(),
  })),
};
```

Update `src/pages/movies.tsx` to consume the loader data via `.View()`, and pass the resulting component to `definePage`:

```tsx
import { definePage } from 'hono-preact';
import { serverLoaders } from './movies.server.js';

const dataLoader = serverLoaders.default;

const MoviesView = dataLoader.View(({ data }) => {
  if (!data) return <p>Loading...</p>;
  return (
    <main>
      <h1>Movies</h1>
      <ul>
        {data.movies.map((m) => (
          <li key={m.id}>{m.title}</li>
        ))}
      </ul>
    </main>
  );
});

MoviesView.displayName = 'Movies';

export default definePage(MoviesView);
```

Register the route in `src/routes.ts`; the colocated `movies.server.ts` is wired in with it:

```ts
{
  path: '/movies',
  view: () => import('./pages/movies.js'),
}
```

Reload `http://localhost:5173/movies`. The list renders server-side on first load, with the data preloaded into the HTML. On client-side navigation away and back, the framework calls the loader over RPC. Same function, no manual wiring.

`defineLoader(fn)` returns a typed `LoaderRef<T>`. The Vite `moduleKeyPlugin` rewrites the call at build time to inject `{ __moduleKey, __loaderName }` so the key drives RPC routing (`/__loaders`), the `__id` Symbol identity, and HMR. `.View(render)` returns a Preact component pre-wrapped in the loader's error boundary, data context, and reload context. The render function receives a `LoaderState` discriminated union on every render; switch on `status` (`loading | success | revalidating | error`) to render each state, and read `reload` from `useReload()`. `loader.useData()` inside the render function is argument-free and returns the same `LoaderState`.

## 3. Add a server action

Add `serverActions` to `src/pages/movies.server.ts`:

```ts
import { defineAction, defineLoader } from 'hono-preact';

export type Movie = { id: string; title: string };

const store: Movie[] = [
  { id: '1', title: 'The Godfather' },
  { id: '2', title: 'Chinatown' },
];

const getMovies = () => store;
const addMovieToStore = (title: string) =>
  store.push({ id: String(store.length + 1), title });

export const serverLoaders = {
  default: defineLoader(async () => ({
    movies: getMovies(),
  })),
};

export const serverActions = {
  addMovie: defineAction<{ title: string }, { ok: boolean }>(
    async (_ctx, { title }) => {
      addMovieToStore(title);
      return { ok: true };
    }
  ),
};
```

Update `src/pages/movies.tsx` to add the form. Import `serverActions` alongside `serverLoaders`:

```tsx
import type { FunctionComponent } from 'preact';
import { definePage, Form } from 'hono-preact';
import { serverLoaders, serverActions } from './movies.server.js';

const dataLoader = serverLoaders.default;

const AddMovieForm: FunctionComponent = () => (
  <Form action={serverActions.addMovie}>
    <input name="title" placeholder="Movie title" required />
    <button type="submit">Add</button>
  </Form>
);

const MoviesView = dataLoader.View(({ data }) => {
  if (!data) return <p>Loading...</p>;
  return (
    <main>
      <h1>Movies</h1>
      <AddMovieForm />
      <ul>
        {data.movies.map((m) => (
          <li key={m.id}>{m.title}</li>
        ))}
      </ul>
    </main>
  );
});

MoviesView.displayName = 'Movies';

export default definePage(MoviesView);
```

The route entry in `routes.ts` doesn't change; actions ride along with the same `server` import. Submit a title in the form. The action runs on the server and the list updates. To automatically re-fetch the loader after the action, pass `invalidate: 'auto'` via `useAction` (see [Server Actions](/docs/actions) for the programmatic form).

## What's next

- [The Route Table](/docs/routes): the full `defineRoutes` reference.
- [Layouts & Nested Routes](/docs/layouts): share chrome across URLs without remounting.
- [Server Loaders](/docs/loaders): caching, cross-page invalidation, path params.
- [Server Actions](/docs/actions): `useAction`, optimistic updates, file uploads, streaming.
- [Middleware](/docs/middleware): protect pages with the unified `use` array.
- [Loading States](/docs/loading-states): switch on the `LoaderState` status to show a spinner or skeleton while the loader fetches.
- [Build & Deploy](/docs/deployment): production build and deployment.


---

> Source: https://framework.sbesh.com/docs/routes

# The Route Table

Declare every URL in your app in one place: `src/routes.ts`. A code-defined route table makes URL redesign a one-edit refactor and keeps URL structure independent of file layout, with no filesystem-based routing to work around.

## Why one file

A code-defined route table makes URL design a one-edit refactor (rename a path, move a leaf), keeps URL structure independent of file layout (organize files by domain, not by URL), and gives agents and devtools a single source of truth they can grep. The trade you make is a manual entry per route.

## A complete example

```ts
// src/routes.ts
import { defineRoutes } from 'hono-preact';

export default defineRoutes([
  { path: '/', view: () => import('./pages/home.js') },
  { path: '/demo/login', view: () => import('./pages/demo-login.js') },
  {
    path: '/demo/projects',
    layout: () => import('./pages/projects-layout.js'),
    children: [
      { path: '', view: () => import('./pages/projects-list.js') },
      {
        path: ':projectId/issues/:issueId',
        view: () => import('./pages/issue.js'),
      },
    ],
  },
  {
    path: '/demo/projects/:projectId',
    view: () => import('./pages/project.js'),
  },
  { path: '*', view: () => import('./pages/not-found.js') },
]);
```

That table covers four URL behaviours:

| Path                                            | Behaviour                                                                                                        |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `/`, `/demo/login`, `/demo/projects/:projectId` | Plain leaves. The `view` resolves to the page component; a colocated `.server.ts` sibling is auto-discovered.    |
| `/demo/projects`                                | An empty-path child of a layout group. Renders `<ProjectsLayout>` wrapping the list view.                        |
| `/demo/projects/:projectId/issues/:issueId`     | A nested child of the same layout group. The same `ProjectsLayout` instance stays mounted across the navigation. |
| `*`                                             | Catch-all. Matches anything not matched above.                                                                   |

## Route entry fields

| Field      | Type                                                     | Required                    | What it is                                                                                                                                                                                                                                                                                                         |
| ---------- | -------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `path`     | `string`                                                 | always                      | URL pattern. Top-level paths start with `/`. Child paths must NOT start with `/` (they're relative to the parent). The wildcard `*` matches anything not matched by siblings.                                                                                                                                      |
| `view`     | `() => Promise<{ default: ComponentType }>`              | for leaves                  | The page component, behind a dynamic import. The framework wraps it with preact-iso's `lazy` for code-splitting.                                                                                                                                                                                                   |
| `layout`   | `() => Promise<{ default: ComponentType<LayoutProps> }>` | for layout groups           | A wrapper component that receives `children`. See [Layouts & Nested Routes](/docs/layouts).                                                                                                                                                                                                                        |
| `server`   | `() => Promise<unknown>` \| `false`                      | optional, advanced          | **Advanced.** The sibling `.server.ts` module behind a dynamic import (carries `serverLoaders` / `serverActions`). Usually omitted: the colocated sibling is auto-discovered. Set this only to point at a non-sibling module, or to `false` to opt out. See [Colocated server modules](#colocated-server-modules). |
| `use`      | `Middleware[]`                                           | optional                    | An array of page-layer middleware run for this node and all its descendants. See [Middleware](/docs/middleware#the-three-layers).                                                                                                                                                                                  |
| `children` | `RouteDef[]`                                             | for layouts and path groups | Nested routes.                                                                                                                                                                                                                                                                                                     |

## The three valid shapes

| Shape            | Fields                                                     | Meaning                                                                                             |
| ---------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Leaf**         | `path`, `view`, optional `server`                          | A page. Cannot have `children`.                                                                     |
| **Layout group** | `path`, `layout`, `children` (required), optional `server` | A wrapper that renders matched descendants. May declare its own `server` for layout-scoped loaders. |
| **Path group**   | `path`, `children` (no `view`, no `layout`)                | Pure URL prefix sharing. Useful for `/admin/*` without shared chrome.                               |

`defineRoutes` validates the tree at runtime and throws with the offending URL if the shape is wrong: `view` + `layout`, `view` + `children`, `layout` without `children`, child path starting with `/`, or a route declaring none of `view`/`layout`/`children`.

## Colocated server modules

A route's server module (its `serverLoaders`, `serverActions`, rooms, and sockets) lives in a `.server.ts` file named after the route's `view`/`layout` file: `login.tsx` pairs with `login.server.ts`, `projects-shell.tsx` with `projects-shell.server.ts`. The build finds that sibling and wires it to the route:

```ts
// login.tsx + login.server.ts sit side by side.
{ path: 'login', view: () => import('./pages/login.js') }
```

Middleware inheritance, the loader/action RPC map, and the boot-time route-binding check apply just as they do for an explicit `server:` thunk. In `vite dev`, each wired module is logged once.

### Advanced: the explicit `server` field

Writing `server:` by hand is an advanced override for the cases discovery does not cover:

- **Non-sibling module:** `server: () => import('./somewhere-else.server.js')` points the route at a specific module and wins over the sibling.
- **`server: false`:** keeps a `.server.ts` sibling from being wired (e.g. a scratch file).

Discovery reads the inline `() => import()` on the route, so it covers hand-written route tables. A route whose `view` is a hoisted const thunk, or one generated at runtime (e.g. `contentRoutes(import.meta.glob(...))`), takes an explicit `server:` if it needs one. If a `.server.*` file is imported by nothing (not a route, and not the [`src/server` registry](#the-srcserver-registry) below), the production build warns about it, so a misplaced module is not a silent runtime 404.

## The `src/server` registry

Server modules that are not tied to a single page can live in `src/server/` instead of next to a view. Every `.server.*` file under it, at any folder depth, is globbed into the server build, so its units register without a `server:` route field. This is the place to organize route-less server code by domain (`src/server/billing/`, `src/server/audit/`).

**Route-less** units are addressed by module key: a bare `defineLoader` (over the loaders RPC) or `defineAction` (via the handler's moduleKey fallback), plus rooms and sockets. Both are route-independent: their RPC runs only the app-level `use` and the unit's own unit-level `use`, never a route node's page-layer `use`, so gate a route-less unit with a unit-level `use` (or bind it with `serverRoute(r)`). A page reaches them by importing their `serverLoaders` / `serverActions` exactly as it would a route-attached module.

```
src/server/audit/log.server.ts   ->  export const serverLoaders = { recent: defineLoader(...) }
```

**Route-bound** units work here too: bind one to a real route with `serverRoute('/path')` and it inherits that route's page-layer `use` (auth) chain, wherever the file lives. This lets you keep a gated route's server logic under `src/server/` organized by domain rather than beside its view.

```ts
// src/server/audit/project-activity.server.ts
const route = serverRoute('/demo/projects/:projectId'); // inherits its requireSession gate
export const serverLoaders = {
  activity: route.loader(async () => ({ events: [] })),
};
```

The bound pattern must be a real route in your table; a `serverRoute('/typo')` that matches no route fails loudly at startup rather than running under no gates. Any node with child routes (a layout, or a grouping node that declares only `use` and `children`) is bindable as a subtree: `serverRoute('/demo/projects/*')` resolves the chain every descendant inherits. Under a tree-form registration (`tree: typeof routeTree`, see [Typed route params](/docs/layouts#typed-route-params)) the subtree spelling is typed for every children-bearing node, grouping nodes included; a paths-only registration types subtree patterns heuristically from the path union, requiring a registered strict descendant. A layout's exact path is also bindable when the layout has an index child or a server module of its own; that spelling is the page scope, the pattern's deepest composed chain. A subtree pattern on a childless route fails loudly at startup. The folder is configurable via the Vite plugin's `serverDir` option (default `src/server`).

## Mounting

You do not write `iso.tsx` or `server.tsx`. The framework generates both as virtual modules from your `routes.ts` and `Layout.tsx`. The client entry hydrates `<Routes>` inside `<LocationProvider>`; the server entry calls `createServerEntry`, which builds the loaders RPC, the page-action POST handler, the realtime socket upgrade, your optional `api.ts`, and the SSR catch-all on one Hono app and exports it as the worker's default. See [Project Structure](/docs/structure) for the file layout the plugin assumes.

If you need to customize the client or server entry (rare), pass a path override via the Vite plugin's `clientEntry` / `entry` options and follow the patterns in the generated virtual modules. A custom client entry must call `bootClient()` before hydrating; see [Custom client entry path](/docs/vite-config#custom-client-entry-path).

## Inline imports stay inline

Every `view` and `layout` (and any explicit `server`) is `() => import('./path')`. The arrow shape is required for code-splitting: bundlers create a separate chunk per `import()` call site. A helper that takes a string (`view: lazy('./pages/home')`) would either lose splitting or require a transform plugin. The five characters of `() => ` per route is the trade for zero magic and full bundler support.

## Sharing references for non-layout routes

When two leaves point at the same component (e.g. mounting one page at multiple paths), hoist the import thunk to a const so the framework's `lazy()` memoization sees the same identity and produces one shared component reference:

```ts
const sharedView = () => import('./pages/shared.js');

defineRoutes([
  // ...
  { path: '/a', view: sharedView },
  { path: '/b', view: sharedView },
]);
```

For layout groups, identity sharing is automatic: a layout group is registered at both `/path` and `/path/*` with the same component reference, so intra-group navigation does not remount the layout. See [Layouts & Nested Routes](/docs/layouts) for the full pattern.

## What `defineRoutes` returns

```ts
type RoutesManifest = {
  tree: ReadonlyArray<RouteDef>; // the original input, for introspection
  flat: ReadonlyArray<FlatRoute>; // the registered routes
  serverImports: ReadonlyArray<
    // every `server` thunk in the tree
    () => Promise<unknown>
  >;
  serverRoutes: ReadonlyArray<ServerRoute>; // server-bound nodes (loaders/actions/rooms/sockets)
  routeUse: ReadonlyArray<{
    path: string;
    use: ReadonlyArray<Middleware | StreamObserver>;
  }>; // composed page-layer `use` chain, one per matchable route pattern
};
```

`tree` is the original input retained for devtools and dev-time introspection. `flat` is what `<Routes>` registers with preact-iso. `serverImports` is what the generated server entry (through `createServerEntry`) adapts into the loader and action handler map. `serverRoutes` and `routeUse` are the introspection surfaces the page-action resolver and the page-layer `use` resolver read to apply a route node's `use` to its actions and route-bound loaders by exact pattern.

## Page-layer middleware on a route node

A route entry can carry a `use` field to attach page-layer middleware to that node and all its descendants. The guard applies to the node's own view render (SSR and client navigation), to every action RPC, and to every route-bound loader RPC (`serverRoute(r).loader`) under that subtree. A bare `defineLoader` is the exception: its RPC is route-independent, so it inherits the guard on the SSR render but not on a direct `POST /__loaders` hit. Bind such a loader to its route (or give it a unit-level `use`) to gate it. See [Middleware](/docs/middleware) for the full model.

```ts
import { defineRoutes } from 'hono-preact';
import { requireSession } from './auth/session.js';

export default defineRoutes([
  { path: '/login', view: () => import('./pages/login.js') }, // ungated
  {
    path: '/dashboard',
    use: [requireSession], // gates everything below
    children: [
      { path: '', view: () => import('./pages/dashboard.js') },
      { path: 'settings', view: () => import('./pages/settings.js') },
    ],
  },
]);
```

`use` takes an array of middleware. When multiple ancestors each carry `use`, they compose outer-to-inner in tree order (outermost ancestor first). A sibling that is not a descendant of the guarded node is not affected.

For the full chain model and middleware authoring, see [Middleware](/docs/middleware).

## See also

- [Layouts & Nested Routes](/docs/layouts): the `layout` field, `LayoutProps`, identity preservation, the inner-router lowering.
- [Adding Pages](/docs/pages): the page-authoring side: views, server bindings, definePage.
- [Server Loaders](/docs/loaders): what the `server` import contains.
- [Middleware](/docs/middleware): the full middleware chain and `use` authoring.
- [Project Structure](/docs/structure): where each piece lives in the demo app.


---

> Source: https://framework.sbesh.com/docs/layouts

# Layouts & Nested Routes

A layout is a wrapper component that stays mounted across navigations between sibling routes. Use a layout when several URLs share chrome: a sidebar, a header, a tab bar, a sub-navigation. The framework preserves the layout's identity across intra-group navigation so its state survives.

## Declaring a layout

In `routes.ts`, a layout group is a route entry with `layout` and `children`:

```ts
import { defineRoutes } from 'hono-preact';

export default defineRoutes([
  {
    path: '/movies',
    layout: () => import('./pages/movies-layout.js'),
    children: [
      {
        path: '',
        view: () => import('./pages/movies-list.js'),
        server: () => import('./pages/movies-list.server.js'),
      },
      {
        path: ':id',
        view: () => import('./pages/movie.js'),
        server: () => import('./pages/movie.server.js'),
      },
    ],
  },
]);
```

URLs:

- `/movies` matches the parent + the empty-path child. Renders `<MoviesLayout><MoviesList /></MoviesLayout>`.
- `/movies/123` matches the parent + the `:id` child. Renders `<MoviesLayout><Movie /></MoviesLayout>` with `pathParams.id === '123'`.

Navigating from `/movies` to `/movies/123` does NOT remount `MoviesLayout`. State held in the layout (an open menu, scroll position, a focused element) survives.

## The layout component

A layout is a Preact component whose props match `LayoutProps` from `hono-preact`:

```tsx
// src/pages/movies-layout.tsx
import type { LayoutProps } from 'hono-preact';

export default function MoviesLayout({ children }: LayoutProps) {
  return (
    <section class="p-1">
      <header class="flex gap-2">
        <a href="/" class="bg-amber-200">
          home
        </a>
        <a href="/demo/projects" class="bg-emerald-200">
          projects
        </a>
      </header>
      <div class="mt-2">{children}</div>
    </section>
  );
}
```

`children` is the matched descendant tree. The framework injects it.

## Typed route params

`pathParams` is `Record<string, string>` by default, so reading `route.pathParams.id` is unchecked. Register your route tree once and `useParams` returns params typed from the route's own pattern, with the route id validated against your real routes.

Register in `routes.ts`, next to `defineRoutes`. Give the tree its own `as const` binding and register against `typeof routeTree`:

```ts
import { defineRoutes } from 'hono-preact';

const routeTree = [
  {
    path: '/movies',
    layout: () => import('./pages/movies-layout.js'),
    children: [{ path: ':id', view: () => import('./pages/movie.js') }],
  },
] as const;

export default defineRoutes(routeTree);

declare module 'hono-preact' {
  interface RegisteredRoutes {
    tree: typeof routeTree;
  }
}
```

Then name the route you are on; the params are inferred from its pattern:

```tsx
import { useParams } from 'hono-preact';

export default function Movie() {
  // id is typed `string`; an unknown or misspelled route id is a type error.
  const { id } = useParams('/movies/:id');
  return <h1>{id}</h1>;
}
```

Register against `typeof routeTree` (the tree array), not `typeof routes` (the manifest `defineRoutes` returns). The manifest form creates a type cycle. Before you register, `useParams` still works: it accepts any string and projects that pattern's params.

The tree form types the whole binding surface from the tree structure: the path union (what `RoutePaths<typeof routeTree>` extracts) plus a subtree pattern (`<path>/*`, what `RouteSubtrees<typeof routeTree>` extracts) for every node with children, so `serverRoute`'s subtree scope compiles for grouping nodes and index-only layouts alike. A `paths: RoutePaths<typeof routeTree>` registration is also supported; with only a path union to work from, it types subtree patterns heuristically, requiring a registered strict descendant.

## URL composition rules

| Rule                                                     | Why                                                                         |
| -------------------------------------------------------- | --------------------------------------------------------------------------- |
| Top-level paths start with `/`                           | `/movies`, `/admin`, etc. Standard.                                         |
| Child paths must NOT start with `/`                      | A child path is appended to its parent (`/movies` + `:id` → `/movies/:id`). |
| Empty child path (`''`) matches the parent's URL exactly | The "index" child of a layout group.                                        |
| Routes match in source order                             | First match wins, including catchalls like `*`.                             |
| `*` matches anything not matched by siblings             | Works at any nesting level.                                                 |
| Trailing slashes normalised                              | `/movies/` and `/movies` are the same route.                                |

## Loaders per layout, per leaf

A layout MAY declare its own `server` module. Its loaders are scoped to the layout's matched location, not the deepest active child route, and do not re-fire when navigating between children under the same layout. See [Layout-level loaders](/docs/loaders#layout-level-loaders) for the full pattern.

```ts
{
  path: '/movies',
  layout: () => import('./pages/movies-layout.js'),
  server: () => import('./pages/movies-layout.server.js'),  // ok: layout-scoped loaders
  children: [...],
}
```

If you want chrome plus a leaf loader at the same URL, structure it as a layout with an empty-path child carrying the leaf data:

```ts
{
  path: '/movies',
  layout: () => import('./pages/movies-layout.js'),
  children: [
    {
      path: '',
      view: () => import('./pages/movies-list.js'),
      server: () => import('./pages/movies-list.server.js'),  // loader for /movies
    },
    // ... other children
  ],
}
```

The list view consumes its loader data via `loader.useData()`; the layout never sees it. If a child needs data the layout ALSO needs to display, lift the data into the layout's render via context or pass it through as a prop in the empty-path child.

## Path-grouping (no layout)

If you want to share a URL prefix without a wrapper, omit `layout` and `view`:

```ts
{
  path: '/admin',
  children: [
    { path: 'users', view: () => import('./pages/admin-users.js') },
    { path: 'posts', view: () => import('./pages/admin-posts.js') },
  ],
}
```

Both `/admin/users` and `/admin/posts` are independent routes; they share only the URL prefix. No shared chrome means no shared mount, so navigating between them remounts each view.

## Nested layouts

Layouts can contain layouts. Each layer of nesting adds another wrapper around the matched leaf:

```ts
{
  path: '/dashboard',
  layout: () => import('./pages/dashboard-layout.js'),
  children: [
    { path: '', view: () => import('./pages/dashboard-home.js') },
    {
      path: 'reports',
      layout: () => import('./pages/reports-layout.js'),
      children: [
        { path: '', view: () => import('./pages/reports-index.js') },
        { path: ':id', view: () => import('./pages/report.js') },
      ],
    },
  ],
}
```

Renders for `/dashboard/reports/42`:

```
<DashboardLayout>
  <ReportsLayout>
    <Report />
  </ReportsLayout>
</DashboardLayout>
```

Navigating `/dashboard/reports → /dashboard/reports/42` remounts only `<Report />`. Both layouts stay mounted. Navigating `/dashboard/reports/42 → /dashboard` remounts everything below `<DashboardLayout>` (because `<ReportsLayout>` is no longer matched).

## How the framework preserves identity

preact-iso's `<Router>` decides whether a navigation is "the same component re-rendered" or "a different component mounted" by comparing component references between the matched outgoing and incoming routes. If the references are the same, the component re-renders in place; if different, it unmounts and a new one mounts.

For a layout group, the framework registers ONE shared component at the outer router under both `/path` and `/path/*`. That shared component renders `<Layout><Router>{...children}</Router></Layout>`. The inner `<Router>` matches the rest of the URL against the layout's children. Outer navigation between `/movies` and `/movies/123` finds the SAME outer component, so the layout re-renders in place; the inner Router resolves the new child and swaps its content.

Nesting works recursively: a layout-group child of a layout group registers as a single component within its parent's inner Router, and so on.

## What's out of scope

| Feature                                    | Workaround                                                                                                                                      |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Pathless layout routes (no URL segment)    | Repeat the wrapper as a regular component imported by each view that needs it.                                                                  |
| `useParentLoaderData` / loader composition | Layout loaders and leaf loaders both run, but they do not see each other's data. Read from a context provided by the layout, or pass via props. |
| Path-prefix middleware                     | Use Hono `.use()` in your `api.ts` for path-prefix middleware.                                                                                  |

Layout-level loaders DO run in parallel with leaf loaders (see [Layout-level loaders](/docs/loaders#layout-level-loaders)); what's out of scope is letting a leaf loader read its parent layout loader's data through framework plumbing.

## Sharing chrome without a layout

If you want chrome shared across unrelated URLs (not a contiguous URL prefix), don't declare a layout group. Instead, write the chrome as a regular component and import it directly into each view:

```tsx
// src/components/MarketingChrome.tsx
export function MarketingChrome({ children }: { children: ComponentChildren }) {
  return (
    <div class="marketing-bg">
      <nav>...</nav>
      {children}
    </div>
  );
}

// src/pages/about.tsx
import { MarketingChrome } from '../components/MarketingChrome.js';
export default function About() {
  return (
    <MarketingChrome>
      <h1>About</h1>
    </MarketingChrome>
  );
}
```

This pattern remounts the chrome on each navigation, so it's only appropriate when the chrome has no state that needs to survive nav. For shared chrome with state, prefer a layout group with an empty-path index child.

## See also

- [The Route Table](/docs/routes): the `defineRoutes` factory and the manifest.
- [Adding Pages](/docs/pages): view authoring.
- [Server Loaders](/docs/loaders): what `server` imports provide.


---

> Source: https://framework.sbesh.com/docs/pages

# Adding Pages

Add a page by creating a view component and registering it in the route table. The framework handles code-splitting and server wiring automatically; the route table is the single source of truth for every URL in the app.

## Standard pages

A view component is a default-exported Preact component. The page itself imports only what it consumes. The route table maps a URL to the view (and optionally its server module); `definePage` wraps the component with a `Wrapper` or `errorFallback` when needed, and page-layer middleware attaches as `use` on the route node in `routes.ts`.

### Step 1: Create `src/pages/about.tsx`

```tsx
import type { FunctionComponent } from 'preact';

const About: FunctionComponent = () => {
  return <section>About this app.</section>;
};

About.displayName = 'About';

export default About;
```

The page is a default-exported component. No `<Page>` wrapper, no `RouteHook` plumbing; those concerns belong to `definePage` (only when the page needs a `Wrapper` or an `errorFallback`).

### Step 2: Add to `src/routes.ts`

```ts
import { defineRoutes } from 'hono-preact';

export default defineRoutes([
  // ... other routes
  { path: '/about', view: () => import('./pages/about.js') },
]);
```

`view` is a deferred dynamic import. The framework wraps it with preact-iso's `lazy` for code-splitting.

For pages that need data, import `serverLoaders` from the sibling `.server.ts` and use `.View()` to create the component:

```tsx
// src/pages/about.tsx
import { definePage } from 'hono-preact';
import { serverLoaders } from './about.server.js';

const AboutView = serverLoaders.default.View(({ data }) =>
  data ? <section>{/* render data */}</section> : <p>Loading...</p>
);

export default definePage(AboutView);
```

```ts
// src/routes.ts
{
  path: '/about',
  view: () => import('./pages/about.js'),
}
```

`about.server.ts` sits next to `about.tsx`, so its `serverLoaders` and `serverActions` are wired into the generated `server.tsx` (`createServerEntry`) automatically. See [Colocated server modules](/docs/routes#colocated-server-modules).

### Step 3: Link to it

From anywhere in the app:

```tsx
<a href="/about">About</a>
```

preact-iso intercepts clicks on same-origin `<a>` tags and handles them as client-side navigations.

## Pages with shared chrome

When several routes share a header, sidebar, or other wrapper, declare a layout group instead of repeating the chrome in every view. See [Layouts & Nested Routes](/docs/layouts) for the full pattern.

```ts
{
  path: '/movies',
  layout: () => import('./pages/movies-layout.js'),
  children: [
    // `movies-list.server.ts` / `movie.server.ts` siblings are auto-discovered.
    { path: '',    view: () => import('./pages/movies-list.js') },
    { path: ':id', view: () => import('./pages/movie.js') },
  ],
}
```

## MDX content pages

MDX is supported via the `@mdx-js/rollup` Vite plugin (configured in `vite.config.ts`). To mount a whole folder of MDX as routes, pass `import.meta.glob` to `contentRoutes`, which turns each file into a framework route node. Spread those nodes under a layout group so the pages share chrome:

```ts
import { defineRoutes, contentRoutes } from 'hono-preact';
import { MdxArticle } from './components/MdxArticle.js';

export default defineRoutes([
  // ...
  {
    path: '/docs',
    layout: () => import('./components/DocsLayout.js'),
    children: [
      ...contentRoutes(import.meta.glob('./pages/docs/**/*.mdx'), {
        wrapper: MdxArticle,
      }),
      { path: '*', view: () => import('./components/DocsNotFound.js') },
    ],
  },
]);
```

`import.meta.glob` must be written inline with a literal pattern (a Vite requirement); `contentRoutes` receives the resulting module map. Each MDX file becomes its own route: server-rendered, navigable, and code-split. The `*` child renders a docs-styled "not found" inside the layout for unmatched `/docs/...` URLs.

### The wrapper

`contentRoutes` wraps every page in a single-element root, here `MdxArticle` (an `<article class="mdx-content">`). The wrapper is required: MDX compiles to a multiple-sibling Fragment root, which does not hydrate stably on its own; the single wrapping element is what makes hydration correct. It is also the natural home for prose styling. The default wrapper, if you pass none, is a bare `<div>`.

### `contentRoutes(modules, options?)`

| Param             | Type                                     | Description                                                                                                                       |
| ----------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `modules`         | `Record<string, () => Promise<unknown>>` | The map from `import.meta.glob`. Keys are file paths; each value is a lazy importer whose `default` export is the page component. |
| `options.wrapper` | `ComponentType<{ children }>`            | Single-root wrapper around each page. Defaults to a bare `<div>`.                                                                 |
| `options.slug`    | `(key: string) => string`                | Map a glob key to its route `path`, overriding the default rule.                                                                  |
| `options.base`    | `string`                                 | Prefix stripped from each key before slug derivation. Defaults to the longest common directory of all keys.                       |

The default slug rule strips the common directory prefix and the file extension and collapses a trailing `index` to the empty path: `index.mdx` serves the directory root (`/docs`), `quick-start.mdx` serves `/docs/quick-start`, and `components/dialog.mdx` serves `/docs/components/dialog`.

**To add a new MDX page**, drop a file into `src/pages/docs/<slug>.mdx`; `contentRoutes` picks it up via the glob, with no `routes.ts` edit. (See `.claude/skills/add-docs-page.md` for the project-local skill.)

## View transitions

Route changes trigger a view transition automatically in browsers that support `document.startViewTransition`. See [View Transitions](/docs/view-transitions) for the full toolkit (named elements, lifecycle hooks, direction-driven types, and persistent elements).

## See also

- [The Route Table](/docs/routes): full reference for `defineRoutes`.
- [Layouts & Nested Routes](/docs/layouts): when and how to share chrome across URLs.
- [Server Loaders](/docs/loaders): what goes in the `.server.ts` file.
- [Middleware](/docs/middleware): the `use` field on a route node in `routes.ts` for auth gates and per-page middleware.
- [Active Links](/docs/active-links): linking between pages with active-state highlighting.


---

> Source: https://framework.sbesh.com/docs/head

# Head Management

Pages declare their document title, meta tags, link tags, and the `<html lang>` attribute with head hooks imported from `hono-preact`. During SSR the framework collects every hook call made in the rendered tree and injects the tags into the document head, so titles and social metadata are present in the initial HTML; on the client the same hooks keep the head in sync as the user navigates.

## Example

Set a title and description from any page component:

```tsx
// src/pages/movie.tsx
import { useTitle, useMeta } from 'hono-preact';

export default function Movie({ movie }: { movie: { title: string } }) {
  useTitle(movie.title);
  useMeta({ name: 'description', content: `Details for ${movie.title}` });
  return <h1>{movie.title}</h1>;
}
```

Set a site-wide title template once in a layout, and page titles slot into it:

```tsx
// src/pages/layout.tsx
import { useTitleTemplate, useLang } from 'hono-preact';

export default function Layout({ children }) {
  useTitleTemplate('%s | My App');
  useLang('en');
  return <>{children}</>;
}
```

Add a link tag (a canonical URL, a preload, an icon):

```tsx
import { useLink } from 'hono-preact';

useLink({ rel: 'canonical', href: 'https://example.com/movies' });
```

## How it works

- **SSR injection.** `renderPage` collects every head hook call during prerender and post-processes the tags into your layout's `</head>`. Your `Layout` must render a real `<head>` element (the `<Head>` component from `hono-preact` provides one); with no `<head>` in the output there is nowhere to inject and the tags are dropped.
- **Fallback title.** When no page sets a title, the `<Head defaultTitle="...">` prop (or `renderPage`'s `defaultTitle` option) supplies one.
- **Client navigation.** The hooks run on the client too: navigating to a page that calls `useTitle` updates `document.title` without a reload, and unmounting restores the previous value.
- **Deepest call wins.** When a layout and a page both set the same field, the innermost (most recently rendered) hook call takes effect, so page-level titles override layout defaults.

## API reference

| Hook               | Signature                                     | Description                                                                                                                                |
| ------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `useTitle`         | `(title: string, template?: boolean) => void` | Sets `document.title`. Pass `template: true` to treat the string as a title template.                                                      |
| `useTitleTemplate` | `(template: string) => void`                  | Declares a title template; `%s` is replaced by the current `useTitle` value.                                                               |
| `useMeta`          | `(options: MetaOptions) => void`              | Renders a `<meta>` tag. `MetaOptions` carries `name`, `property` (Open Graph), `httpEquiv`, `charset`, and `content`.                      |
| `useLink`          | `(options: LinkOptions) => void`              | Renders a `<link>` tag. `LinkOptions` carries `rel` (required), `href`, `as`, `media`, `sizes`, `crossorigin`, `type`, and `hreflang`.     |
| `useLang`          | `(language: string) => void`                  | Sets the `lang` attribute on `<html>`.                                                                                                     |
| `useScript`        | `(options: ScriptOptions) => void`            | Renders a `<script>` tag. `ScriptOptions` carries `src`, `id`, `text`, `type`, `async`, `defer`, `module`, `crossorigin`, and `integrity`. |

The option types (`MetaOptions`, `LinkOptions`, `ScriptOptions`) are exported from `hono-preact`.

See also: [renderPage](/docs/render-page) for how collected tags are injected server-side.


---

> Source: https://framework.sbesh.com/docs/active-links

# Active Links

Highlighting the current page in navigation needs one question answered: does the current URL match a given route? `useRouteActive`, `useRouteMatch`, and `<NavLink>` answer it against the same route grammar your route table uses, so `/posts/:id` matches any post and hands you the `id`.

## `useRouteActive`

Returns `true` when the current path matches the route.

```tsx
import { useRouteActive } from 'hono-preact';

function Tab() {
  const active = useRouteActive('/docs');
  return (
    <a href="/docs" aria-current={active ? 'page' : undefined}>
      Docs
    </a>
  );
}
```

By default the match is **exact**. Pass `{ exact: false }` to also match descendant paths, e.g. highlight a section for every page beneath it:

```tsx
// active on /docs/components AND /docs/components/dialog
const inSection = useRouteActive('/docs/components', { exact: false });
```

One caveat: because every path is a descendant of `/`, a non-exact match on the root (`useRouteActive('/', { exact: false })`) is active everywhere. Keep a "Home" link `exact` (the default).

## `useRouteMatch`

Same matching, but returns the captured params (or `null`). Use it when you want to both test _and_ read the dynamic segments.

```tsx
import { useRouteMatch } from 'hono-preact';

function Crumb() {
  const params = useRouteMatch('/posts/:id');
  // on /posts/42 -> { id: '42' }, elsewhere -> null
  return params ? <span>Post {params.id}</span> : null;
}
```

The route accepts the full pattern grammar: `:param`, `*`, `+`, `:param?`.

## `buildPath`

Build a typed URL from a route pattern and its params. TypeScript enforces that the pattern is registered and that the params object matches the pattern's dynamic segments. Param values must be strings; convert numbers or other types before passing them.

```tsx
import { buildPath } from 'hono-preact';

// /posts/42
const href = buildPath('/posts/:id', { id: '42' });

// /dashboard  (no params needed; second argument is omitted)
const dashHref = buildPath('/dashboard');
```

`buildPath` is the safe alternative to template literals: a wrong key or a missing param is a compile error, not a silent bug.

## `<NavLink>`

A `<a>` that applies an active or inactive class for you (and sets `aria-current="page"` when active).

```tsx
import { NavLink } from 'hono-preact';

<NavLink
  href="/docs"
  activeClass="text-accent font-semibold"
  inactiveClass="text-muted"
>
  Docs
</NavLink>;
```

Any `class` you pass is always applied; `activeClass` / `inactiveClass` are merged on top per state. Other anchor props (`target`, `rel`, `data-*`) pass straight through.

Pass your own `aria-current` to override the computed value, including `aria-current={undefined}` to opt out entirely (the link still gets its active class, just no `aria-current` attribute). Active state is path-only: it cannot see the query string, so if a set of links differ only by their query (e.g. `?tab=`), manage `aria-current` yourself.

Use `exact={false}` for section links, and `match` when the link target differs from the pattern you want to highlight on:

```tsx
// links to /posts, but stays active on /posts/123
<NavLink href="/posts" match="/posts/:id" activeClass="text-accent">
  Posts
</NavLink>
```

## Navigating programmatically

`useNavigate()` returns a `navigate(path, options?)` function for navigating from
an event handler (a logout button, a post-action redirect). A soft navigate runs
the same client middleware, loaders, and view transitions as a `<NavLink>` click.

```tsx
import { useNavigate } from 'hono-preact';

function LogoutButton() {
  const navigate = useNavigate();
  return (
    <button onClick={() => navigate('/login', { replace: true })}>
      Log out
    </button>
  );
}
```

A fragment target is a same-document anchor navigation: `navigate('#usage')`
writes the hash to the URL and scrolls to the matching element, like a native
anchor click. No route change happens, so nothing animates and the `transition`
option has no effect.

| Option       | Type      | Default | Description                                                             |
| ------------ | --------- | ------- | ----------------------------------------------------------------------- |
| `replace`    | `boolean` | `false` | Replace the current history entry instead of pushing a new one.         |
| `reload`     | `boolean` | `false` | Do a full-page navigation (clean slate) instead of a client navigation. |
| `transition` | `boolean` | `true`  | Set `false` to navigate without a view transition.                      |

## API reference

`<NavLink>` forwards any other `<a>` attribute (e.g. `target`, `rel`, `data-*`) to the underlying anchor and sets `aria-current="page"` while the link is active. A caller-supplied `aria-current` always wins, and `aria-current={undefined}` suppresses the computed value. Because active detection is path-only, links that differ only by query string need their `aria-current` managed explicitly.

| Prop            | Type      | Default  | Description                                                     |
| --------------- | --------- | -------- | --------------------------------------------------------------- |
| `href`          | `string`  | required | Destination path.                                               |
| `match`         | `string`  | `href`   | Pattern tested for the active state.                            |
| `exact`         | `boolean` | `true`   | Match the full path; set `false` for prefix (section) matching. |
| `class`         | `string`  | none     | Always applied.                                                 |
| `activeClass`   | `string`  | none     | Merged in when the link is active.                              |
| `inactiveClass` | `string`  | none     | Merged in when the link is not active.                          |
| `transition`    | `boolean` | `true`   | Set `false` to navigate without a view transition.              |

## See also

- [The Route Table](/docs/routes): the path grammar `match` tests against.
- [Link Prefetch](/docs/link-prefetch): prefetching the page a link points to.


---

> Source: https://framework.sbesh.com/docs/loaders

# Server Loaders

Pages need data. Loaders run on the server: a direct function call during SSR, and an automatic RPC call during client-side navigation, so you never write the branch manually.

A loader is either route-bound (declared via `serverRoute(r).loader`) or route-independent (declared via `defineLoader`). Route-bound loaders receive a typed `location` with the route's path and search params. Route-independent loaders receive a lighter context without location, suitable for shared or reusable fetching logic.

## Route-bound loaders

Bind a server module to its route with `serverRoute(r)`. Calling `.loader(fn)` on the result types `ctx.location.pathParams` from the route pattern automatically:

```ts
// src/pages/movie.server.ts
import { serverRoute } from 'hono-preact';
import { getMovie } from '@/server/movies.js';

const route = serverRoute('/movies/:id');

export const serverLoaders = {
  default: route.loader(async ({ location }) => {
    // location.pathParams.id is typed `string` from the `/movies/:id` pattern
    return getMovie(location.pathParams.id);
  }),
};
```

Then consume the data in the page component via `.View()`:

```tsx
// src/pages/movie.tsx
import { definePage } from 'hono-preact';
import { serverLoaders } from './movie.server.js';

const MovieView = serverLoaders.default.View(({ data }) =>
  data ? (
    <article>
      <h1>{data.title}</h1>
    </article>
  ) : (
    <p>Loading...</p>
  )
);

export default definePage(MovieView);
```

**`src/routes.ts`** wires the URL to the view; the colocated `movie.server.ts` is picked up with it:

```ts
import { defineRoutes } from 'hono-preact';

export default defineRoutes([
  {
    path: '/movies/:id',
    view: () => import('./pages/movie.js'),
  },
]);
```

### Validating params and search params

Pass `paramsSchema` or `searchSchema` (any [Standard Schema](https://standardschema.dev) library) to validate and coerce the input before the loader runs. When validation fails, `paramsSchema` causes a 404; `searchSchema` causes a 400 and the loader's error boundary catches it:

```ts
import { serverRoute } from 'hono-preact';
import { z } from 'zod';

const route = serverRoute('/movies/:id');

export const serverLoaders = {
  default: route.loader(
    async ({ location }) => {
      return getMovie(location.pathParams.id, location.searchParams.quality);
    },
    {
      searchSchema: z.object({ quality: z.enum(['hd', 'sd']).default('hd') }),
    }
  ),
};
```

## Route-independent loaders

`defineLoader(fn)` defines a loader not tied to any specific route. The context carries `c` (the Hono Context), `signal`, and `call`; there is no `location`. Use this for shared utilities, loaders reused across multiple routes, or data that does not depend on the current URL:

```ts
// src/pages/movies.server.ts
import { defineLoader } from 'hono-preact';
import { getMovies } from '@/server/movies.js';

export const serverLoaders = {
  default: defineLoader(async ({ c, signal }) => {
    const token = getCookie(c, 'session');
    const movies = await getMovies({ token, signal });
    return { movies };
  }),
};
```

When path or search params are needed, use `serverRoute(r).loader()` instead.

A route-independent loader is not route-gated. Its RPC endpoint (`POST /__loaders`) runs only the app-level `use` plus the loader's own unit-level `use`; it does not inherit a route node's page-layer `use`, even when the loader module is colocated under a guarded route. To gate a loader by a route's middleware chain, bind it with `serverRoute(r).loader` (the page-layer `use` then resolves from that exact route pattern) or attach a unit-level `use` to the loader itself. See [Middleware](/docs/middleware) for the three layers. In dev, the server warns once per loader when a route-independent loader serves a request whose matched route declares `use`, so an ungated RPC under a guarded subtree is visible in the console.

## Streaming loaders

A loader whose function body is an `async function*` is a streaming loader. The framework infers this from the function shape at build time. Streaming loaders are SSR-pumped by default: the server starts writing the response immediately, flushing each yielded chunk as an inline `<script>` tag:

```ts
// src/pages/dashboard.server.ts
import { defineLoader } from 'hono-preact';

export const serverLoaders = {
  metrics: defineLoader(async function* ({ signal }) {
    while (!signal.aborted) {
      yield await currentMetrics();
      await delay(1000);
    }
  }),
};
```

A streaming loader exposes the accumulating `.View(render, { initial, reduce })` form. See [Streaming](/docs/streaming) for the full consumption reference.

### The `{ live }` flag

By default, a streaming loader runs during SSR and pumps chunks into the HTML. Pass `{ live: true }` to skip SSR entirely, making the loader a client-only subscription. This is appropriate for unbounded generators that must not hang the document response:

```ts
import { defineLoader } from 'hono-preact';

export const serverLoaders = {
  activity: defineLoader(
    async function* ({ signal }) {
      for await (const event of subscribeToActivity(signal)) {
        yield event;
      }
    },
    { live: true }
  ),
};
```

### liveStream

`liveStream({ topic, load })` is a generator helper that re-runs a loader on every publish to a channel topic. It yields `load(ctx)` on initial connect, then re-yields each time `publish()` fires on `topic(ctx)`. Because `liveStream` produces an inherently unbounded subscription, it is always live: no `{ live: true }` flag is required. Compose it with either `defineLoader` or `route.loader`:

```ts
import { serverRoute, liveStream } from 'hono-preact';
import { tasksChannel, getTasks } from '@/server/tasks.js';

const route = serverRoute('/projects/:id');

export const serverLoaders = {
  tasks: route.loader(
    liveStream({
      topic: ({ location }) => tasksChannel.key(location.pathParams.id),
      load: ({ location }) => getTasks(location.pathParams.id),
    })
  ),
};
```

See [Realtime Channels](/docs/realtime) for channel setup.

## Streaming lifecycle

| Loader type                     | `live` | Behavior                                                   |
| ------------------------------- | ------ | ---------------------------------------------------------- |
| Finite (`Promise<T>`)           | n/a    | SSR-awaited; arrives in the initial HTML as a static value |
| Streaming (`AsyncGenerator<T>`) | false  | SSR-pumped; chunks flush inline into the HTML (default)    |
| Streaming (`AsyncGenerator<T>`) | true   | Skipped on SSR; starts as a client-only subscription       |

Both route-bound and route-independent loaders support the streaming and live forms.

## Consuming loaders

### `.View(render)`: single-value loaders

`.View(render)` creates a component pre-wrapped in the loader's error boundary, data context, and reload context. The render function receives a `LoaderState<Serialize<T>>` discriminated union; switch on `status`:

```tsx
import { definePage } from 'hono-preact';
import { serverLoaders } from './movies.server.js';

const MoviesView = serverLoaders.default.View(({ data, status }) => {
  // `data` is absent on the cold `loading` arm; a truthy check is
  // enough to guard it before reading sub-fields.
  if (!data) return <p>Loading...</p>;
  if (status === 'error') return <p>Failed to load.</p>;
  return (
    <ul>
      {data.movies.map((m) => (
        <li key={m.id}>{m.title}</li>
      ))}
    </ul>
  );
});

export default definePage(MoviesView);
```

The `loading` arm carries no data. `success`, `revalidating`, and `error` each carry `data` narrowed to `Serialize<T>`. The `revalidating` status is the stale-while-revalidate state during a reload; the `error` arm keeps the last good value. Call `useReload()` for the imperative `reload()`.

**Prop passthrough** (using the generic `P`):

```tsx
const MovieCard = serverLoaders.default.View<{ highlight: boolean }>(
  ({ data, highlight }) => {
    if (!data) return <MovieSkeleton />;
    return (
      <article class={highlight ? 'highlight' : undefined}>
        <h2>{data.title}</h2>
      </article>
    );
  }
);

// Use site:
<MovieCard highlight={true} />;
```

**Error handling inside the render function:**

When the loader rejects after already succeeding once, the status is `error` and the last good `data` is still available. Read `reload` from `useReload()` to let the user retry:

```tsx
import { useReload } from 'hono-preact';

const StatsView = statsLoader.View(({ status, data }) => {
  const { reload } = useReload();
  if (!data) return <StatsSkeleton />;
  if (status === 'error') return <button onClick={reload}>Retry</button>;
  return <p>Count: {data.count}</p>;
});
```

This `error` arm handles a reload that fails after the first load succeeded. A cold first-load failure routes to the error boundary and `errorFallback` instead. See [Loading States](/docs/loading-states) for the distinction.

During SSR, a cold first-load failure with a local `errorFallback` (including a loader that throws `deny(status, message)`) renders that `errorFallback` into the full document at the failure's status, and hydrates without refetching. A loader that fails without a local `errorFallback` responds with the status and a plain-text body.

### `.View(render, { initial, reduce })`: streaming loaders

Streaming loaders use the accumulating form. Each chunk is folded into accumulated state and the render function receives a `StreamState<Acc>` discriminated union:

```tsx
const ActivityBar = serverLoaders.activity.View<ActivityEvent[]>(
  (s) => {
    if (s.status === 'connecting') return <p>Connecting...</p>;
    if (s.status === 'error') return <p>Stream disconnected.</p>;
    return (
      <ul>
        {s.data.map((e) => (
          <li key={e.id}>{e.actor}</li>
        ))}
      </ul>
    );
  },
  {
    initial: [],
    reduce: (acc, event) => [event, ...acc].slice(0, 50),
  }
);
```

See [Streaming](/docs/streaming) and [Live Loaders](/docs/live-loaders) for the full streaming consumption reference.

### `loader.useData()` and `loader.Boundary`

`loader.useData()` returns the same `LoaderState` for descendants that need it without prop-drilling. Call it inside a `.View()` render function or inside an explicit `loader.Boundary`:

```tsx
function HeaderWithSummary() {
  const { data } = serverLoaders.summary.useData();
  if (!data) return <Skeleton />;
  return <h1>{data.title}</h1>;
}

function Header() {
  return (
    <serverLoaders.summary.Boundary>
      <HeaderWithSummary />
    </serverLoaders.summary.Boundary>
  );
}
```

`loader.useData()` is not available on streaming loaders (they have no single value). Calling it on a streaming loader throws with a clear error message; use the accumulating `.View` form instead.

## The serverLoaders container

Loaders are exported in a named `serverLoaders` container from a `.server.*` file. Whether a module has one loader or many, the shape is always the same:

```ts
// src/pages/movies.server.ts
import { defineLoader } from 'hono-preact';

export const serverLoaders = {
  default: defineLoader(async ({ c }) => {
    const movies = await getMovies(c.env.MY_KV);
    return { movies };
  }),
};
```

A single-loader page conventionally uses the key `default`. Multi-loader pages give each loader a descriptive name. The plugin treats all entries the same way.

## Multiple loaders per route

Declare each data source as its own loader in `serverLoaders`. Each one gets its own independent error boundary, cache key, and streaming section, so a slow source never blocks the rest of the page:

```ts
// src/pages/movie.server.ts
import { serverRoute, defineLoader } from 'hono-preact';

const route = serverRoute('/movies/:id');

export const serverLoaders = {
  summary: route.loader(async ({ location }) =>
    getMovie(location.pathParams.id)
  ),

  cast: route.loader(async function* ({ location, signal }) {
    for await (const member of streamCast(location.pathParams.id, signal)) {
      yield member;
    }
  }),

  similar: defineLoader(async ({ c }) => getFeaturedMovies(c.env.MY_KV)),
};
```

```tsx
// src/pages/movie.tsx
import { definePage, useReload } from 'hono-preact';
import { serverLoaders } from './movie.server.js';

const { summary, cast, similar } = serverLoaders;

const Summary = summary.View(({ status, data }) => {
  const { reload } = useReload();
  if (!data) return <SummarySkeleton />;
  if (status === 'error') return <ErrorBox onRetry={reload} />;
  return <SummaryCard data={data} />;
});

const Cast = cast.View(
  (s) => (s.status === 'open' ? <CastList items={s.data} /> : <CastSkeleton />),
  { initial: [], reduce: (acc, m) => [...acc, m] }
);

const Similar = similar.View(({ data }) =>
  data ? <SimilarCarousel items={data} /> : null
);

function MovieDetail() {
  return (
    <article>
      <Summary />
      <Cast />
      <Similar />
    </article>
  );
}

export default definePage(MovieDetail);
```

Each `.View` component loads independently. `<Summary />` can show content while `<Cast />` is still streaming.

## Layout-level loaders

A loader in `layout.server.*` is scoped to the layout's matched location. It does not re-fire when navigating between child routes:

```ts
// src/pages/movies/layout.server.ts
import { serverRoute } from 'hono-preact';

// Subtree scope: the gates every /movies child inherits.
const route = serverRoute('/movies/*');

export const serverLoaders = {
  activity: route.loader(
    async function* ({ signal }) {
      for await (const event of subscribeToActivity(signal)) {
        yield event;
      }
    },
    { live: true }
  ),
};
```

```tsx
// src/pages/movies/layout.tsx
import { serverLoaders } from './layout.server.js';

const Feed = serverLoaders.activity.View(
  (s) => (s.status === 'open' ? <ActivitySidebar events={s.data} /> : null),
  { initial: [], reduce: (acc, e) => [e, ...acc].slice(0, 50) }
);

export default function MoviesLayout({
  children,
}: {
  children: ComponentChildren;
}) {
  return (
    <div class="movies-layout">
      <main>{children}</main>
      <aside>
        <Feed />
      </aside>
    </div>
  );
}
```

Navigating between child routes does not unmount the layout, so the streaming subscription continues across those navigations.

### Binding a layout's loaders

A layout server module has two bindable spellings, and they name different scopes:

- `serverRoute('/movies')` is the **page scope**: the deepest composed chain for that pattern string. A layout and its empty-path index child share the string, and guard resolution uses the deepest node's chain, so this spelling runs the layout's inherited and own `use` plus the index child's own `use` when the index child declares one. Bind it when the module's units belong to the index page.
- `serverRoute('/movies/*')` is the **subtree scope**: the layout node's own composed chain (ancestors outer-first, then the node's own `use`), exactly the gates every descendant of `/movies` inherits. The index child's additions are not included. Bind it when the module carries shell data that serves every child route, which is the usual case for a layout module.

Both spellings resolve the `use` chain from the declared pattern on every loader RPC, never from the request URL. The subtree pattern names the tree node at `/movies` and resolves its chain statically at startup; it is not a per-request deepest-match. A subtree pattern on a childless route fails loudly at startup.

Inside the layout, a bound loader resolves its `location` to the layout's own matched path with the wildcard remainder stripped, so `ctx.location.pathParams` carries exactly the bound pattern's prefix params under either spelling.

In dev, binding the exact path while the index child's own `use` widens the chain logs a one-time hint naming both spellings.

## The loader context

A route-bound loader (`serverRoute(r).loader(fn)`) receives:

| Field      | Type                   | Description                                                                                                                                               |
| ---------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `c`        | `Context`              | The request's Hono Context. Use for cookies, headers, `Bindings`, the request URL, etc.                                                                   |
| `location` | `RouteHook`            | The matched route's navigation info: typed `pathParams`, `searchParams`, path, and metadata. The same shape as `useLocation()` accessed from a component. |
| `signal`   | `AbortSignal`          | Aborts when the user navigates away mid-load. Forward to `fetch` and cancellable work.                                                                    |
| `call`     | `ServerCaller['call']` | Invoke another loader or action server-side without an HTTP round-trip.                                                                                   |

A route-independent loader (`defineLoader(fn)`) receives the same fields except `location`.

`location.pathParams` and `location.searchParams` are plain objects, so read them any way you like: `pathParams.id`, `'id' in pathParams`, `Object.keys(pathParams)`, and the rest all work. You never have to worry about a param name clashing with a built-in like `constructor` or `toString`, because a route can't declare one in the first place: `serverRoute('/plugin/:constructor')` throws at definition. The same holds for a socket's `data` params and a room's `onJoin` params; see [WebSockets](/docs/websockets) and [Rooms](/docs/rooms).

Pass the signal to upstream `fetch` calls and subscriptions so they clean up promptly:

```ts
defineLoader(async ({ c, signal }) => {
  const token = getCookie(c, 'session');
  const res = await fetch('/api/data', { signal });
  return res.json();
});
```

By convention, loaders read; actions write. Setting cookies or headers from a loader is allowed but discouraged. On the SSR path, `setCookie(ctx.c, …)` from a non-streaming loader survives to the response. A streaming loader can set cookies only before its first `yield`; anything written after is dropped because the response headers are already committed.

## Search-param dependencies (`params`)

By default, a loader's cache key includes only the path and path params. Declare search-param dependencies per loader with the `params` option:

```ts
const route = serverRoute('/movies/:id');

export const serverLoaders = {
  // path-only cache key (default); never refetches on search-param changes
  summary: route.loader(async ({ location }) =>
    getMovie(location.pathParams.id)
  ),

  // refetches when ?genre changes, but not on other params
  similar: route.loader(
    async ({ location }) =>
      fetchSimilar(location.pathParams.id, location.searchParams.genre),
    { params: ['genre'] }
  ),

  // refetches on any search-param change; for search/filter pages
  results: route.loader(
    async ({ location }) => searchMovies(location.searchParams),
    { params: '*' }
  ),
};
```

The RPC request always sends the full location to the server; `params` only narrows the client-side cache key.

## Cross-page invalidation

When a mutation on one page should refresh data on another, import the other page's loader ref and pass it to `useAction({ invalidate: [...] })`. Invalidation is by reference, not by name:

```ts
import { useAction } from 'hono-preact';
import { serverLoaders as moviesLoaders } from './movies.server.js';
import { serverActions } from './reviews.server.js';

const { mutate } = useAction(serverActions.addReview, {
  invalidate: [moviesLoaders.default],
});
```

Pass `'auto'` to invalidate the current page's loader only. Use `loader.invalidate()` to clear the cache imperatively.

## Caching navigation results

Every loader gets its own cache automatically. Repeated navigations to the same route (with the same cache key) hit the cache and skip the RPC call. To clear the cache:

```ts
serverLoaders.default.invalidate();
```

### Sharing a cache between loaders

If two loaders need to share storage, construct a `LoaderCache` explicitly and pass it via the `cache` option:

```ts
import { createCache, defineLoader } from 'hono-preact';

const moviesCache = createCache<{ movies: MovieList }>();

export const serverLoaders = {
  default: defineLoader(serverLoader, { cache: moviesCache }),
};
```

### Cache registry scope

The loader-cache registry is keyed off `Symbol.for('@hono-preact/iso/loaderCaches')`, shared across every consumer of `@hono-preact/iso` in the same JavaScript realm. On Cloudflare Workers each request runs in a short-lived isolate, so this is effectively per-process. On a long-lived Node server hosting multiple tenants from one realm, the registry is shared. Cache contents are per-request via AsyncLocalStorage, so there is no cross-tenant data leak.

## Timeouts

`timeoutMs` sets a per-loader deadline on the loader RPC path, the request the client issues when it navigates. It defaults to 30 seconds. Override it per loader:

```ts
export const serverLoaders = {
  slowReport: defineLoader(
    async () => {
      /* ... */
    },
    { timeoutMs: 60_000 }
  ),
  liveStream: defineLoader(
    async function* () {
      /* yields indefinitely */
    },
    { timeoutMs: false }
  ),
};
```

Pass `timeoutMs: false` to opt out entirely. When the deadline fires, the loader's `ctx.signal` aborts, the server responds with 504, and the client receives a `TimeoutError`.

`timeoutMs` governs the loader RPC path (client navigation) only. It is not enforced during the initial SSR render: there the loader runs inline as the page prerenders, with no `timeoutMs` deadline applied.

## Page bindings with `definePage`

Per-page bindings (`Wrapper`, `errorFallback`) live with the page component. `definePage` captures them:

```tsx
import { definePage } from 'hono-preact';

export default definePage(Component, { Wrapper });
```

Loader consumption (`.View()`) lives inside the page's JSX tree, not on `definePage`.

## Registering the loader endpoint

You do not wire `loadersHandler` directly. The framework's Vite plugin generates the server entry, which mounts `loadersHandler` on `POST /__loaders`, a page POST handler for actions, your optional `api.ts`, and the SSR catch-all on one Hono app. If you ever need a custom server entry, see [`renderPage`](/docs/render-page) for the manual wiring contract.

## How it works

A page is a file pair: a `.server.ts` module that collects loaders in `serverLoaders`, and a `.tsx` component that consumes data through `.View()` or `useData()`.

**At runtime:**

1. **SSR:** each loader in `serverLoaders` runs directly during `prerender`. Its return value is JSON-serialized and embedded in the page's HTML.
2. **Hydration (first load):** the client reads that embedded data. No fetch fires.
3. **Client-side navigation:** the Vite plugin replaces `.server.*` imports with Proxy stubs. Accessing `serverLoaders.name` returns a `LoaderRef` whose RPC stub POSTs `{ module, loader, location }` to `POST /__loaders`. The server runs the real function and returns JSON.

Because every value crosses this boundary as JSON, the client receives the _serialized_ shape of a loader's return, not the server-side type. The data hooks reflect that honestly: the value carried by `loader.useData()` and the `.View()` render argument is `Serialize<T>`, the JSON round-trip of the loader's return `T`. A `Date` field is therefore typed (and arrives) as a `string`; values JSON cannot carry (functions, `bigint`, symbols) are dropped, or surface as `never` so a non-serializable return is a compile error.

Two Vite plugins enforce that `.server.*` code never reaches the browser. `serverOnlyPlugin` rewrites `*.server.*` imports in the client bundle: the `serverLoaders` named export becomes a Proxy whose `get(_, name)` returns a fresh `LoaderRef` stub for that name. `serverLoaderValidationPlugin` fails the build if a `.server.*` file has unrecognised named exports.

## Options

Pass a second argument to `defineLoader` or `route.loader` to configure a loader:

| Option         | Type               | Default | Description                                                                 |
| -------------- | ------------------ | ------- | --------------------------------------------------------------------------- |
| `params`       | `string[] \| '*'`  | `[]`    | Search params that change the cache key; `'*'` means any. Route-bound only. |
| `cache`        | `LoaderCache<T>`   | auto    | Shared cache; see Caching navigation results.                               |
| `timeoutMs`    | `number \| false`  | `30000` | Per-loader deadline in milliseconds; `false` disables it.                   |
| `live`         | `boolean`          | `false` | Skip SSR; start as a client-only subscription (streaming loaders only).     |
| `use`          | `LoaderUse`        | none    | Per-loader middleware and stream observers.                                 |
| `paramsSchema` | `StandardSchemaV1` | none    | Route-bound only: validates and coerces `pathParams`. Fails with 404.       |
| `searchSchema` | `StandardSchemaV1` | none    | Route-bound only: validates and coerces `searchParams`. Fails with 400.     |

Most options have a dedicated section above; this table is the at-a-glance summary.

## Inference types

`InferLoaderData<L>` extracts a loader ref's data type without re-importing the loader definition. It resolves to the authored server-side type, not the serialized wire shape.

```ts
import type { InferLoaderData, Serialize } from 'hono-preact';
import type { serverLoaders } from './movies.server.js';

// The loader's return type as declared (server-side, pre-serialization)
type Data = InferLoaderData<typeof serverLoaders.default>;
// { movies: MovieList } (a Date field stays Date here)

// The wire shape (JSON round-trip): Date degrades to string, etc.
type WireData = Serialize<InferLoaderData<typeof serverLoaders.default>>;
```

`InferLoaderData<L>` is useful for code that only runs server-side (such as fixtures, adapters, and `createCaller` test helpers) where the pre-serialized type is the right type to work with. The client-facing hooks (`.View()`, `loader.useData()`) always carry `Serialize<T>`, because data crosses the server/client boundary as JSON.

### API reference

| Helper               | Resolves to                                     |
| -------------------- | ----------------------------------------------- |
| `InferLoaderData<L>` | The loader's data type (`T`), pre-serialization |

## See also

- [Middleware](/docs/middleware): the app, page, and unit `use` layers, and how each one gates a loader.
- [Loading States](/docs/loading-states): the loading and error UI for loader data.
- [Streaming](/docs/streaming): streaming loaders and their consumption API.
- [Live Loaders](/docs/live-loaders): persistent live loaders on layouts, `{ live: true }`, and `StreamStatus`.
- [Reloading Data](/docs/reloading): invalidating and re-running loaders.
- [Prefetching](/docs/prefetch): warming a loader before navigation.
- [Server Actions](/docs/actions): mutations that can invalidate loaders.
- [Realtime Channels](/docs/realtime): channels and `publish()` used with `liveStream`.


---

> Source: https://framework.sbesh.com/docs/loading-states

# Loading States

Show a loading UI during client-side navigation by switching on the `LoaderState` the `loader.View()` render function receives. It is a discriminated union with four `status` variants: `loading` (no data yet), `success`, `revalidating` (a background refresh with the prior data still present), and `error`. Match on `status` and render your own affordance for each; the framework supplies the state, not the UI. For a simple loading-or-content split you can skip the `status` check and read `data` directly (it is `undefined` only while `loading`); reach for `status` when you need to tell `revalidating` or `error` apart.

## Basic usage

```tsx
// src/pages/movies.tsx
import { definePage } from 'hono-preact';
import { serverLoaders } from './movies.server.js';

const moviesLoader = serverLoaders.default;

const MoviesView = moviesLoader.View(({ data }) => {
  // `data` is present in every arm but the cold `loading` one, so a truthy
  // check doubles as the loading guard and narrows `data` to the value type.
  if (!data) return <p>Loading...</p>;
  return (
    <ul>
      {data.movies.results.map((m) => (
        <li key={m.id}>{m.title}</li>
      ))}
    </ul>
  );
});

export default definePage(MoviesView);
```

```ts
// src/routes.ts
{
  path: '/movies',
  view: () => import('./pages/movies.js'),
}
```

The `loading` status appears only on a client-side navigation with no cached value; SSR and first-load hydration render with data already present, so the initial paint is `success`, never `loading`.

## When each status appears

| Navigation                      | `status` on entry                                         |
| ------------------------------- | --------------------------------------------------------- |
| SSR (first load)                | `success`. Data is preloaded into the HTML.               |
| Hydration                       | `success`. Client reads from the `data-loader` attribute. |
| Client-side nav (cache miss)    | `loading`, until the loader resolves (then `success`).    |
| Client-side nav (cache hit)     | `success`. Cached data renders immediately.               |
| Reload (stale-while-revalidate) | `revalidating`. `data` retains the previous value.        |

## Using a skeleton

Return a skeleton component while the cold load is in flight (`data` still absent):

```tsx
const MoviesSkeleton = () => (
  <ul>
    {Array.from({ length: 5 }).map((_, i) => (
      <li key={i} class="h-6 w-48 animate-pulse bg-gray-200 rounded" />
    ))}
  </ul>
);

const MoviesView = moviesLoader.View(({ data }) =>
  data ? (
    <ul>
      {data.movies.results.map((m) => (
        <li key={m.id}>{m.title}</li>
      ))}
    </ul>
  ) : (
    <MoviesSkeleton />
  )
);
```

## Stale-while-revalidate

During a reload the status is `revalidating`: a refresh is in flight, but `data` still holds the previous value. Render the cold-load placeholder only for `loading`, and show a subtle indicator for `revalidating` so the current content stays visible:

```tsx
const MoviesView = moviesLoader.View(({ status, data }) => {
  if (!data) return <MoviesSkeleton />;
  return (
    <div>
      {status === 'revalidating' && (
        <span class="text-sm text-muted">Refreshing...</span>
      )}
      <ul>
        {data.movies.results.map((m) => (
          <li key={m.id}>{m.title}</li>
        ))}
      </ul>
    </div>
  );
});
```

## Error handling inside the render function

When the loader rejects, the status is `error`. That arm also carries the last good `data` (so prior content can stay visible), and `reload` from `useReload()` lets the user retry:

```tsx
import { useReload } from 'hono-preact';

const MoviesView = moviesLoader.View((s) => {
  const { reload } = useReload();
  if (s.status === 'loading') return <p>Loading...</p>;
  if (s.status === 'error')
    return (
      <div role="alert">
        <p>Couldn't load movies: {s.error.message}</p>
        <button onClick={reload}>Retry</button>
      </div>
    );
  return (
    <ul>
      {s.data.movies.results.map((m) => (
        <li key={m.id}>{m.title}</li>
      ))}
    </ul>
  );
});
```

A cold error (the very first load fails, with no prior data) is caught by the loader's error boundary and the page-level `errorFallback` before the render function runs, so the `error` arm always carries a `data` value.

`s.error.message` is `Loader failed` in production; the loader's real thrown message and name reach the client only in dev.

## The `LoaderState` union

The render function receives a `LoaderState<T>` discriminated union. Match on `status`:

| `status`         | Fields                               | When                                                                                      |
| ---------------- | ------------------------------------ | ----------------------------------------------------------------------------------------- |
| `'loading'`      | `data?: never`                       | Cold load before the first response. No data yet.                                         |
| `'success'`      | `data: Serialize<T>`                 | The loader resolved; `data` is the value.                                                 |
| `'revalidating'` | `data: Serialize<T>`                 | A background refresh is in flight; `data` is the previous value (stale-while-revalidate). |
| `'error'`        | `error: Error`, `data: Serialize<T>` | The loader rejected; `data` is the last good value.                                       |

In the `success`, `revalidating`, and `error` arms `data` is narrowed to `Serialize<T>`, so there is no `undefined` to guard. Because the `loading` arm declares `data?: never`, `data` is readable on the un-narrowed union as `Serialize<T> | undefined` (`undefined` only while `loading`), so a render that reads `data` directly does not need to narrow on `status` first. The render function also receives any props declared by the generic `P` (see [prop passthrough in loaders](/docs/loaders)). The imperative `reload()` callback is read from `useReload()`, not passed as a render arg (see [Reloading](/docs/reloading)).

## Page-level error fallback

`definePage` accepts a page-level `errorFallback` that catches errors from the rest of the page tree (for example, a render-time throw outside any loader boundary):

```tsx
export default definePage(MoviesView, {
  errorFallback: (err) => <p>Something went wrong: {err.message}</p>,
});
```

Loader-specific loading and error UI lives inside the `.View()` render function. The page-level `errorFallback` is the outer safety net.

## See also

- [Server Loaders](/docs/loaders): where `.View()` comes from.
- [Streaming](/docs/streaming): state-based loading for streaming loaders.
- [Middleware](/docs/middleware): the `use` binding.
- [Project Structure](/docs/structure): the full `definePage` bindings list (including `Wrapper`).


---

> Source: https://framework.sbesh.com/docs/reloading

# Reloading Data

Sometimes you need to re-run the loader imperatively, for example after a user adds a record to a table. The `useReload` hook lets you do this from within a page component.

## Basic usage

Snippets on this page assume `type MovieList = { results: { id: number; title: string }[] }`.

**`src/pages/movies.server.ts`** holds the loader (the cache is auto-attached):

```ts
import { defineLoader } from 'hono-preact';

export const serverLoaders = {
  default: defineLoader(async () => ({
    movies: await getMovies(),
  })),
};
```

**`src/pages/movies.tsx`** uses `.View()` to create the component. `useReload` is called inside the render function, which runs inside the loader's boundary:

```tsx
import { definePage, useReload } from 'hono-preact';
import { serverLoaders } from './movies.server.js';

const dataLoader = serverLoaders.default;

const MoviesView = dataLoader.View(({ data }) => {
  const { reload, reloading } = useReload();

  const handleAdd = async () => {
    await addMovie({ title: 'New Movie' });
    reload();
  };

  if (!data) return <p>Loading...</p>;

  return (
    <>
      <button onClick={handleAdd} disabled={reloading}>
        {reloading ? 'Adding...' : 'Add Movie'}
      </button>
      <ul>
        {data.movies.results.map((m) => (
          <li key={m.id}>{m.title}</li>
        ))}
      </ul>
    </>
  );
});

export default definePage(MoviesView);
```

**`src/routes.ts`** wires the URL to the view; the colocated `movies.server.ts` is auto-discovered with it:

```ts
{
  path: '/movies',
  view: () => import('./pages/movies.js'),
}
```

`useReload` must be called inside a component rendered within a loader boundary (inside `.View()` or inside a `loader.Boundary`). Calling it outside throws an error.

## Background refresh

Reload is a background refresh. While `reloading` is `true`, the loader's previous value is retained so the current content stays visible; `reloading` reflects an explicit reload or revalidation only, never the cold initial load. Inside a `.View()` render function the same in-flight refresh surfaces as the `revalidating` status, whose arm still carries `data`. Use `reloading` (from `useReload`) or the `revalidating` status (from the `.View()` render arg) to reflect the in-progress state in your UI. `reloading` is `true` only while revalidating a value that already exists; a reload or retry of a loader that has not produced a value yet (a failed first load, or a live reconnect after a cold pre-first-chunk error) is itself a cold load, so branch on `status === 'loading'` for that case, not `reloading`.

## Three knobs, three behaviors

The framework has three ways to invalidate or re-run a loader. They look similar at the call site but mean different things at runtime:

| Knob                                      | Triggers fetch now? | Clears cache?                      | Affects what?                                                                                                                                                                                                       |
| ----------------------------------------- | ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useReload().reload()`                    | **Yes**             | Yes (writes fresh data on success) | The active page's loader (the one whose boundary you're inside).                                                                                                                                                    |
| `loader.invalidate()`                     | No                  | Yes (drops the entry)              | A specific loader's cache only. Next navigation that mounts the loader will refetch on cache miss.                                                                                                                  |
| `useAction({ invalidate: 'auto' })`       | **Yes**             | Yes                                | After the action succeeds, re-runs the active page's loader (the one wrapping the `useAction` call). Equivalent to calling `useReload().reload()` inside `onSuccess`.                                               |
| `useAction({ invalidate: [refA, refB] })` | Sometimes           | Yes                                | After the action succeeds, calls `.invalidate()` on each ref. If any ref is the active page's loader, ALSO re-runs that loader; sibling-page loaders just have their cache cleared and refetch on their next mount. |

The mental model: **`invalidate`** is "mark stale, refetch lazily". **`reload`** is "fetch right now". `useAction`'s `'auto'` mode is sugar over the reload path; its array mode is sugar over `loader.invalidate()` calls plus an opportunistic reload if the active loader is in the list.

A common surprise: `invalidate: 'auto'` is NOT a no-op even when the loader has no observable changes; it triggers a real network request through `/__loaders`. Use `invalidate: false` (the default) if you don't want a refetch after the action.

## API

```ts
const { reload, reloading } = useReload();
```

| Value       | Type         | Description                                                                                                                                                                                                                   |
| ----------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reload`    | `() => void` | Re-runs the `serverLoader`. If called while a fetch (initial load or a previous reload) is still in flight, the call is queued and runs once the in-flight fetch settles; concurrent calls coalesce into a single queued run. |
| `reloading` | `boolean`    | `true` while an explicit reload or revalidation is in flight; `false` during the cold initial load and when idle.                                                                                                             |

## See also

- [Server Loaders](/docs/loaders): `loader.invalidate()` in context.
- [Server Actions](/docs/actions): `useAction` invalidate option.
- [Loading States](/docs/loading-states): switching on the `LoaderState` union during a refetch.


---

> Source: https://framework.sbesh.com/docs/prefetch

# Prefetching Data

`prefetch` runs a loader and fills its cache ahead of navigation, so the destination route renders immediately when the user arrives. Use it when you can predict the user's next move (hover on a link, scroll into view, idle after page load) and the loader is non-trivial.

## Basic usage

```ts
import { prefetch } from 'hono-preact';
import { serverLoaders } from './pages/movie.server.js';

const movieLoader = serverLoaders.default;

// On link hover, kick off a fetch for /movies/42 so the route is ready when clicked.
function onMovieLinkHover(id: number) {
  prefetch(movieLoader, { url: `/movies/${id}`, route: '/movies/:id' });
}
```

The result is written into the loader's cache (when one is configured) and the next navigation reads from cache instead of refetching.

## Common patterns

**Hover prefetch** is the typical case: bind to `onMouseEnter` on a link and call `prefetch` with the destination URL.

**Idle prefetch** is useful for the next-most-likely route. Call `prefetch` from a `requestIdleCallback` after the current page settles.

**Programmatic prefetch** works anywhere: a router transition listener, a search-as-you-type debounce, an intersection observer for cards scrolling into view.

`prefetch` checks the loader's cache first and returns immediately when the destination is already warm. A hover handler firing repeatedly (mouse over → off → back over the same link), an intersection observer re-entering visibility, or duplicate idle-callback scheduling will not issue redundant network requests. The cache key combines path with whatever `searchParams` the loader's `params` option declares, so two prefetches for `/movies/41` and `/movies/42` each hit the network exactly once.

## Why pass `url` and `route`?

Loaders receive a `RouteHook` location (`{ path, searchParams, pathParams }`). When your loader reads `location.pathParams.id` or `location.searchParams.q`, prefetching with no location would crash or return the wrong data. Pass the URL the user is about to navigate to, plus the route pattern, and `prefetch` derives a complete `RouteHook` for you:

- `url` populates `path` (trailing slash stripped, root preserved) and `searchParams`.
- `route` is the matching route pattern (e.g. `/movies/:id`); when present, `pathParams` is derived by matching `url` against it.

If you don't read any of those fields, omit both arguments and `prefetch(loader)` still works.

## Options

| Option     | Type             | Description                                                                                |
| ---------- | ---------------- | ------------------------------------------------------------------------------------------ |
| `url`      | `string`         | Target URL or path. Drives `path` and `searchParams`.                                      |
| `route`    | `string`         | Route pattern (e.g. `/movies/:id`). Combined with `url` to derive `pathParams`.            |
| `location` | `RouteHook`      | Escape hatch: pass a fully-formed `RouteHook` directly. Overrides `url`/`route`.           |
| `cache`    | `LoaderCache<T>` | Override the cache the result is written to. Defaults to the cache attached to the loader. |

## See also

- [Server Loaders](/docs/loaders): the loader cache prefetch fills.
- [Link Prefetch](/docs/link-prefetch): the declarative `data-prefetch` attribute.
- [Loading States](/docs/loading-states): what prefetching lets you skip.


---

> Source: https://framework.sbesh.com/docs/streaming

# Streaming Loaders & Actions

Reach for streaming when the data changes while the user is looking at it: dashboards, log tails, chat token streams, progressive search results. If your data is stable for the lifetime of a request, a plain async function is simpler and should be your first choice.

Streaming loaders and actions are async generators that yield values over time. A streaming loader is consumed with the accumulating `loader.View(render, { initial, reduce })` form, which folds each chunk into a value and hands the render function a `StreamState` to switch on; a streaming action is consumed with `useAction`'s `onChunk` callback.

## Streaming loaders

### Author shape

A streaming loader is an `async function*` that yields `T` and receives a `LoaderCtx`:

```ts
// src/pages/dashboard.server.ts
import { defineLoader, type LoaderCtx } from 'hono-preact';

export type Snapshot = { count: number; load: number };

export const serverLoaders = {
  default: defineLoader(async function* (
    ctx: LoaderCtx
  ): AsyncGenerator<Snapshot> {
    while (!ctx.signal.aborted) {
      yield await currentSnapshot();
      await new Promise((r) => setTimeout(r, 1000));
    }
  }),
};
```

`ctx.signal` is an `AbortSignal` that fires when the client disconnects or the component unmounts. Thread it into upstream `fetch` calls and subscriptions so they clean up promptly. Returning from the generator (rather than looping) also ends the stream cleanly.

For byte-level piping (e.g. forwarding a server-sent event feed without parsing), you can return a `ReadableStream<Uint8Array>` instead of an `AsyncGenerator`. The framework pipes it straight to the response. This is an escape hatch; for typed structured data, use an async generator.

### Consumer shape

A streaming loader (its fn is an `async function*`) has the type `LoaderRef<T, true>`, so it is consumed with the accumulating `loader.View(render, { initial, reduce })` form only. `reduce` folds each yielded chunk into an accumulated value seeded by `initial`; the render function receives a `StreamState<Acc>` discriminated union you switch on (`connecting | open | closed | error`). The single-value `.View(render)` form and `loader.useData()` are not available on a streaming loader (it has no single value), so the wrong form is a compile error. `reload` is read via `useReload()`.

For a dashboard that shows the **latest** snapshot, the accumulator is just that snapshot (`reduce` replaces it each chunk):

```tsx
// src/pages/dashboard.tsx
import { definePage } from 'hono-preact';
import { serverLoaders, type Snapshot } from './dashboard.server.js';

const dataLoader = serverLoaders.default;

const DashboardView = dataLoader.View<Snapshot | null>(
  (s) => {
    if (s.status === 'connecting') return <p>Connecting...</p>;
    return (
      <>
        {s.status === 'error' && <p>Live updates paused: {s.error.message}</p>}
        {s.data && (
          <p>
            Count: {s.data.count}, load: {s.data.load}
          </p>
        )}
      </>
    );
  },
  { initial: null, reduce: (_acc, snap) => snap }
);

export default definePage(DashboardView);
```

To keep a growing log or progressive result list instead, accumulate into an array: `{ initial: [], reduce: (acc, chunk) => [...acc, chunk] }`. Components re-render on each new chunk automatically.

See `/demo/projects/:projectId/issues/:issueId` for a running example of multi-loader streaming: the issue detail page declares multiple loaders in `serverLoaders`, each with its own `.View()` component streaming independently.

## Multi-loader streaming

When a page declares multiple loaders in `serverLoaders`, each `.View()` component streams independently. They share no boundary; one loader finishing does not affect another's `loading` state.

```ts
// src/pages/movie.server.ts
import { serverRoute } from 'hono-preact';

const route = serverRoute('/movie/:id');

export const serverLoaders = {
  summary: route.loader(async ({ location }) =>
    getMovie(location.pathParams.id)
  ),

  cast: route.loader(async function* ({ location }) {
    for await (const member of streamCast(location.pathParams.id)) yield member;
  }),
};
```

```tsx
// src/pages/movie.tsx
import { definePage } from 'hono-preact';
import { serverLoaders } from './movie.server.js';

const { summary, cast } = serverLoaders;

// `summary` is a plain async loader (single value): the single-value `.View`.
const Summary = summary.View(({ data }) =>
  data ? <SummaryCard data={data} /> : <SummarySkeleton />
);

// `cast` is a streaming generator: the accumulating `.View`, folding members
// into a list and switching on the StreamState `status`.
const Cast = cast.View<CastMember[]>(
  (s) =>
    s.status === 'connecting' ? (
      <CastSkeleton />
    ) : (
      <CastList items={s.data ?? []} />
    ),
  { initial: [], reduce: (acc, member) => [...acc, member] }
);

function MovieDetail() {
  return (
    <article>
      <Summary />
      <Cast />
    </article>
  );
}

export default definePage(MovieDetail);
```

`<Summary />` and `<Cast />` each track their own state. `<Summary />` can paint as soon as its value resolves while `<Cast />` is still streaming members into its list.

## What happens on first paint

A streaming loader does not bake chunk data into the SSR HTML; it reconnects on the client.

1. The server renders the page with each streaming loader in its `connecting` state: the render function runs with the `initial` accumulator and `status === 'connecting'`, and the loader's element carries no baked value (`data-loader="null"`).
2. On hydration the client adopts that server-rendered node and opens the loader's stream (an SSE request). It then folds each arriving chunk through `reduce`, moving `status` from `connecting` to `open` and re-rendering as the accumulator fills.
3. When the stream ends cleanly `status` becomes `closed`; if it drops, `status` becomes `error` (carrying the last accumulator, if any).

The first paint shows the `connecting` affordance (the `initial` value), then the live data streams in. A plain async loader, by contrast, is fully server-rendered with its value baked in. For long-lived layout-scoped subscriptions, see [Live Loaders](/docs/live-loaders).

## Errors

A stream lifecycle event is data, not an exception: a stream failure travels through the render function's `status` field, never the loader's error boundary or `errorFallback`.

**Before the first chunk:** a stream that fails on the initial connect surfaces as `status === 'error'` with no accumulated value (`data` absent), exactly like a mid-stream drop. Guard `data` rather than handing your render an empty accumulator.

**After a chunk:** the `error` arm surfaces the error while still carrying the last good `data`, so the view stays mounted with the last accumulator visible.

```tsx
const StatsView = dataLoader.View<Snapshot | null>(
  (s) => {
    if (s.status === 'connecting') return <StatsSkeleton />;
    return (
      <>
        {s.status === 'error' && <p>Live updates paused: {s.error.message}</p>}
        {s.data && <p>Count: {s.data.count}</p>}
      </>
    );
  },
  { initial: null, reduce: (_acc, snap) => snap }
);
```

A mid-stream throw reaches the client as a terminal error event on the wire. In production its message is masked as `Stream failed`, mirroring the non-streaming `Loader failed` and `Action failed` masking; in dev the real message and error name pass through. An expected, user-facing terminal state should be yielded as data the consumer understands rather than thrown.

## Abort and cleanup

The framework aborts `ctx.signal` when the client disconnects (server side) or when the component that owns the loader unmounts (client side). Pass the signal to any upstream resource that supports cancellation:

```ts
const serverLoaders = {
  feed: defineLoader(async function* (ctx) {
    const res = await fetch('https://api.example.com/feed', {
      signal: ctx.signal,
    });
    for await (const chunk of parseStream(res.body!)) {
      yield chunk;
    }
  }),
};
```

Polling loops should check `ctx.signal.aborted` at the top of each iteration (as in the example above) rather than listening for the abort event, so cleanup happens at a natural yield point.

## Streaming actions

An action can be a streaming generator that yields progress chunks and returns a final result. The type parameters on `defineAction` follow the generator's shapes automatically.

### Author shape

```ts
// src/pages/watched.server.ts
import { defineAction } from 'hono-preact';

export const serverActions = {
  bulkImport: defineAction(async function* (ctx, payload: { count: number }) {
    for (let i = 0; i < payload.count; i++) {
      if (ctx.signal.aborted) return { imported: i };
      await processItem(i);
      yield { count: i + 1, total: payload.count };
      await new Promise((r) => setTimeout(r, 150));
    }
    return { imported: payload.count };
  }),
};
```

Yielded values are the chunk type (`TChunk`). The return value is the final result (`TResult`). TypeScript infers both from the generator body.

### Consumer shape

```tsx
const [progress, setProgress] = useState<{
  count: number;
  total: number;
} | null>(null);

const { mutate, data, pending } = useAction(serverActions.bulkImport, {
  onChunk: (p) => setProgress(p),
  onSuccess: (r) => console.log(`imported ${r.imported}`),
});
```

`onChunk` receives each typed chunk. `onSuccess` receives the typed final result (the generator's return value). `data` holds the final result after the stream closes.

For error handling, pass `onError`:

```tsx
const { mutate } = useAction(serverActions.bulkImport, {
  onChunk: (p) => setProgress(p),
  onSuccess: (r) => setProgress(null),
  onError: (err) => console.error('import failed', err),
});
```

Chunks and the final result are delivered in order. If the generator throws, the stream closes and `onError` is called; `onSuccess` does not fire.

## Form limitations for streaming actions

Streaming actions cannot be used with `<Form action={stub}>`. The type signature of `FormProps['action']` constrains the stub to non-streaming actions (`TChunk = never`), so passing a streaming action stub is a TypeScript error at compile time.

If a streaming action receives a raw POST without `Accept: text/event-stream` (for example, a no-JS form submission), the server responds with HTTP 405. Streaming actions are only invocable via `useAction(stub)` with the `onChunk` callback.

```tsx
// This is a type error: streaming actions are not accepted by <Form>
<Form action={serverActions.bulkImport} />; // TS error

// Correct: call streaming actions programmatically
const { mutate } = useAction(serverActions.bulkImport, {
  onChunk: (p) => setProgress(p.count),
});
```

## Debugging

Streaming loaders and actions use a server-sent event (SSE) wire format. You can inspect the framing directly with curl:

```bash
# Streaming loader endpoint
curl -N 'http://localhost:5173/demo/projects/inf/tasks/t-1'

# Streaming action: must include Accept: text/event-stream (replace module key and action name)
curl -N -X POST http://localhost:5173/movies \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{"module":"pages/movies.server","action":"bulkImport","payload":{"count":5}}'
```

Each chunk arrives as a `data:` line followed by a blank line (standard SSE framing). The final result for actions arrives as a `result:` line. Parsing is handled automatically by the framework on the client.

## See also

- [Server Loaders](/docs/loaders): non-streaming loaders.
- [Server Actions](/docs/actions): streaming actions.
- [Live Loaders](/docs/live-loaders): long-lived, layout-scoped streaming subscriptions (same accumulating `.View` form).
- [Loading States](/docs/loading-states): switching on the loader-state and stream-state unions.


---

> Source: https://framework.sbesh.com/docs/live-loaders

# Live Loaders & Persistent UI

A live loader is a streaming loader that connects once and survives intra-scope navigation. It is the mechanism for building UI that persists visually across route changes: a notification bar, a sidebar feed, a presence indicator, or any widget that should keep running while the user navigates within a section of the app.

## Example: activity bar

The demo at `/demo/projects` uses a live activity loader on the `projects-shell` layout to show a real-time event feed across all project pages.

**Server module** (`projects-shell.server.ts`):

```ts
import { serverRoute, eventStream, type LoaderCtx } from 'hono-preact';
import {
  activityChannel,
  recentActivityEvents,
  type ActivityEvent,
} from './activity-stream.js';

// Backfill recent history, then stream every event published on the activity
// channel (server actions publish real events with
// `publish(activityChannel.key(), e)`).
async function* activityStream({
  signal,
}: LoaderCtx): AsyncGenerator<ActivityEvent, void, unknown> {
  for (const e of recentActivityEvents(5)) yield e;
  for await (const e of eventStream(activityChannel.key(), signal)) {
    yield e;
  }
}

// The projects route node declares `use: requireSession`; the subtree
// binding resolves that gate for the shell's loader RPCs from this
// declared pattern.
const route = serverRoute('/demo/projects/*');

export const serverLoaders = {
  default: route.loader(shellLoader),
  activity: route.loader(activityStream, { live: true }),
};
```

**Layout component** (`projects-shell.tsx`):

```tsx
import type { StreamStatus } from 'hono-preact';
import { serverLoaders } from './projects-shell.server.js';
import type { ActivityEvent } from './activity-stream.js';

const activityLoader = serverLoaders.activity;
const MAX = 50;

function Feed({
  events,
  status,
}: {
  events: ActivityEvent[];
  status: StreamStatus;
}) {
  const connected = status === 'open';
  return (
    <div role="log" aria-label="Recent activity">
      <span aria-hidden class={connected ? 'dot dot--live' : 'dot dot--idle'} />
      {events.length === 0 ? (
        <p>Listening for activity...</p>
      ) : (
        <ul>
          {events.map((e) => (
            <li key={e.id}>
              {e.actor}: {e.taskTitle}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

// The accumulating `.View` form (selected by `initial` + `reduce`) tracks its
// connection status as state, so the bar hydrates cleanly inside the layout.
// Branch on `status` for each affordance: `connecting` (pre-first-chunk) and a
// cold `error` (the connect failed before any chunk) carry no data, so guard
// them before reading `s.data`.
const ActivityBar = activityLoader.View<ActivityEvent[]>(
  (s) => {
    if (s.status === 'open' || s.status === 'closed')
      return <Feed events={s.data} status={s.status} />;
    if (s.status === 'error') return <p>Activity stream disconnected.</p>;
    return <p>Connecting to activity...</p>;
  },
  {
    initial: [],
    reduce: (acc, e) => [e, ...acc].slice(0, MAX),
  }
);

export default function ProjectsShell({
  children,
}: {
  children: ComponentChildren;
}) {
  return (
    <div class="projects-shell">
      <main>{children}</main>
      <ActivityBar />
    </div>
  );
}
```

Navigating between `/demo/projects/alpha` and `/demo/projects/beta` does not remount `ProjectsShell`, so `ActivityBar` keeps its accumulated events and the stream stays open.

## How it works

Persistent UI is expressed as a child of a layout. A layout stays mounted across navigations between its child routes, so anything rendered inside the layout survives those navigations too. Attach a `live` loader to the layout's server module to connect a long-lived stream to that layout, and consume the stream with `loader.View(render, { initial, reduce })` inside a layout component. The stream connects once when the layout mounts and reconnects only when the user leaves the layout's scope entirely.

Two pieces of the same loader API drive this pattern:

- `defineLoader(fn, { live: true })` marks a loader as live. A live loader is never invoked during SSR (an infinite generator cannot hang the document response), and its timeout defaults to `false` (no 30-second cap) unless `timeoutMs` is set explicitly. A live loader is consumed with the accumulating `loader.View(render, { initial, reduce })` form. The single-value `.View(render)` form, `.useData()`, and `.Boundary` are not available on a live loader (it has no single value): the form is fixed by the loader's type (`defineLoader({ live: true })` returns a `LoaderRef<T, true>`), so using the wrong form is a compile error.
- `loader.View(render, { initial, reduce })` is the accumulating form of the standard consumption convention. It folds every chunk into accumulated state, and the render function receives a `StreamState<Acc>` discriminated union to match on `status`. `status === 'connecting'` on SSR and before the first chunk arrives (this arm carries no data); after the first chunk `status` is `'open'`, with the accumulator on `data`. Switch on `status` inside the render function to show a connecting affordance.

## On Cloudflare

`publish()`, `route.loader(liveStream({ topic, load }))`, and `eventStream(topic, signal)` share the same cross-isolate fan-out on Cloudflare Workers.
Cross-isolate fan-out (a `publish()` in one request waking a live loader
streaming in another isolate) is backed by the same `HONO_PREACT_REALTIME`
Durable Object that powers rooms, so no extra setup is needed once that binding
is in your `wrangler.jsonc` (see the rooms docs, "Cloudflare setup").

One thing to keep in mind: `publish()` syncs the **event**, not your state. It
fans a "something changed, re-run" wake out to every connected live loader; each
loader then re-runs its `load(ctx)` and reads the current value. So your `load`
must read from a **shared source of truth** that every isolate can see: a
database, KV, D1, or Durable Object storage. A module-level `let count = 0` works
on Node (one process shares it) but is **per-isolate on Workers**, so two tabs
would drift apart even though the wake reached both. Read shared state in `load`,
and `publish()` after you write it.
`eventStream` is the exception to the "event, not state" rule: it delivers the published payload itself (as its JSON wire shape), so a feed of self-contained events needs no shared read on the subscriber side.

## Scoping the persistence

Choose the layout based on the scope you want:

| Scope           | Route table entry                                 | What persists         |
| --------------- | ------------------------------------------------- | --------------------- |
| App-wide        | Root route with `layout` and `path: '*'` children | Across the whole app  |
| Section         | Prefix route group (e.g. `path: '/projects'`)     | Within `/projects/**` |
| Single sub-tree | Any nested layout group                           | Within that sub-tree  |

The stream is tied to the layout's lifecycle. It connects when the layout mounts and is aborted (via `ctx.signal`) when the layout unmounts, which happens when the user navigates outside the layout's scope.

## Known behavior

### Scope-exit blip

When the user navigates out of the layout's scope, the layout unmounts and the stream closes. If the user navigates back in, the layout remounts and the stream reconnects from scratch, starting with `initial` again. This is the expected lifecycle: there is no cross-mount cache for live loaders.

### No automatic reconnect on drop

A live loader opens the stream once and does not auto-reconnect. If the connection drops mid-session (a network blip, a server restart, an idle proxy timeout), `status` becomes `'error'` or `'closed'` and stays there until the layout unmounts and remounts (scope exit and re-entry). To recover in place, branch on `status` and call `reload()` from `useReload()` (for example, a "Reconnect" button shown when `status === 'error'`); `reload()` resets `data` to `initial` and re-opens the stream.

### Failure or close before the first chunk

A stream lifecycle event is **data, not an exception**: failures and clean ends always travel through the render function's `status` field, at every point in the stream's life. A failure on the **initial** connect (the stream fails or times out before its first chunk arrives) surfaces as `status === 'error'`, exactly like a mid-stream drop; because no chunk has arrived, that cold-connect error carries no accumulated value, so its `data` is `undefined`. Branch on it (show an error UI rather than handing your render an empty accumulator), the way the `'error'` row in the table below describes. A stream that ends cleanly before its first chunk simply stays on the `connecting` affordance: there is no accumulator to show.

Because the cold-connect error surfaces in-view, the reconnect-on-error pattern above works on the very first connect too: a "Reconnect" button shown when `status === 'error'` calls `reload()` to re-open the stream. A failed `reload()` behaves identically, so the in-place recovery pattern is uniform across the first connect and every later reconnect.

`errorFallback` does **not** catch a stream connect failure. It only catches a **render-time throw** from the render subtree (and, during SSR, a throw raised while the document renders). Stream lifecycle errors never reach it.

## API reference

### `defineLoader(fn, { live })`

| Option | Type      | Default | Description                                                                                                                                          |
| ------ | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `live` | `boolean` | `false` | Marks this loader as a long-lived client subscription. Skipped on SSR; timeout defaults to `false`. Consume via the accumulating `loader.View` form. |

All other `defineLoader` options (`params`, `cache`, `timeoutMs`, `use`) work the same for live loaders. See [Server Loaders](/docs/loaders) for the full option table.

### `loader.View(render, { initial, reduce })` (accumulating form)

Passing `initial` and `reduce` selects the accumulating form of `.View`. The render function receives a `StreamState<Acc>` discriminated union; switch on `status` (`connecting | open | closed | error`). The `connecting` arm carries no data; the other arms carry the folded accumulator as `data`.

```ts
loader.View<Acc>(
  render: (args: StreamState<Acc>) => ComponentChildren,
  opts: {
    initial: Acc;
    reduce: (acc: Acc, chunk: Serialize<T>) => Acc;
    errorFallback?:
      | ComponentChildren
      | ((err: Error, reset: () => void) => ComponentChildren);
  }
): FunctionComponent
```

`chunk` is `Serialize<T>`: the JSON round-trip of the server-side chunk, the same wire shape `useData()` and the single-value `.View` surface (a `Date` field arrives as a string).

| Option          | Type                                                       | Description                                                                                                                                                                                                                                                                    |
| --------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `initial`       | `Acc`                                                      | Seed value; also the value passed to the render function on SSR and before the first chunk arrives.                                                                                                                                                                            |
| `reduce`        | `(acc: Acc, chunk: Serialize<T>) => Acc`                   | Folds each incoming chunk (the JSON wire shape) into the accumulated value. Called for every chunk in order.                                                                                                                                                                   |
| `errorFallback` | `ComponentChildren` or `(err, reset) => ComponentChildren` | Rendered if the render subtree throws (or, during SSR, a throw while the document renders). It does **not** catch stream connect failures: a cold-connect error surfaces in-view as `status === 'error'` instead. The function form receives the error and a `reset` to retry. |

The render function receives a `StreamState<Acc>` discriminated union. Match on `status`:

| `status`       | Fields                       | When                                                                                                                                              |
| -------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `'connecting'` | `data?: never`               | SSR and before the first chunk arrives. No data yet.                                                                                              |
| `'open'`       | `data: Acc`                  | The stream is live; `data` is the folded accumulator, updated after each chunk.                                                                   |
| `'closed'`     | `data: Acc`                  | The stream ended cleanly after at least one chunk; `data` is the last accumulator.                                                                |
| `'error'`      | `error: Error`, `data?: Acc` | The stream errored (on the initial connect, or after a chunk). `data` is the last accumulator if a chunk had arrived, otherwise absent: guard it. |

The `connecting` arm declares `data?: never`, so `data` is readable on the un-narrowed union as `Acc | undefined` (`undefined` while `connecting`, or on a pre-chunk `error`) without narrowing on `status` first. The imperative `reload()` (resubscribe: abort the current stream, reset `data` to `initial`, reconnect, and fold afresh) is read from `useReload()`, not passed as a render arg.

`StreamStatus` values:

| Value          | Meaning                                                       |
| -------------- | ------------------------------------------------------------- |
| `'connecting'` | SSR or pre-hydration; the first chunk has not arrived yet.    |
| `'open'`       | At least one chunk has arrived; the stream is active.         |
| `'closed'`     | The generator returned normally; no more chunks are expected. |
| `'error'`      | The stream errored. `error` holds the cause.                  |

### Type exports

```ts
import type { StreamStatus } from 'hono-preact';
```

## See also

- [Server Loaders](/docs/loaders): non-live loaders and the full `defineLoader` option table.
- [Layouts & Nested Routes](/docs/layouts): how layout scoping and lifecycle work.
- [Streaming](/docs/streaming): finite streaming loaders consumed with the single-value `.View()` form.


---

> Source: https://framework.sbesh.com/docs/realtime

# Realtime Channels

Realtime channels let you push live data from the server to the client without polling. A `Channel` is a typed address; `publish(topic, message)` fires from a server action after a mutation; `route.loader(liveStream({ topic, load }))` subscribes any connected client to that topic and pushes a fresh data snapshot on every publish. When the event itself is the data, `eventStream(topic, signal)` yields each published payload directly to a streaming loader.

## Example: live shared counter

A single-instance signal channel (no route params, no payload) that signals all live loaders to refetch the current count.

**`counter-channel.ts`** (shared between server and action):

```ts
import { defineChannel } from 'hono-preact';

// A signal channel: defineChannel('name')<void>(). No payload; the subscriber
// calls load() for the fresh value. Published with no message argument.
export const counterChannel = defineChannel('counter')<void>();
```

**`counter.server.ts`** (server module for the `/counter` route):

```ts
import { serverRoute, liveStream } from 'hono-preact';
import { counterChannel } from './counter-channel.js';
import { getCount } from './counter-db.js';

const route = serverRoute('/counter');

export const serverLoaders = {
  count: route.loader(
    liveStream({
      // topic(ctx) returns the Topic this loader subscribes to.
      topic: (_ctx) => counterChannel.key(),
      // load(ctx) is called on connect and on every publish to the topic.
      load: async (_ctx) => getCount(),
    })
  ),
};
```

**`counter.tsx`** (page component):

```tsx
import type { StreamStatus } from 'hono-preact';
import { serverLoaders } from './counter.server.js';

const countLoader = serverLoaders.count;

// The accumulating .View form folds every pushed chunk into `data`.
// `initial` seeds the value before the first chunk arrives;
// `reduce` folds each chunk. For a simple replace-on-every-push pattern,
// reduce just returns the latest chunk.
// Branch on `status`: `connecting` (pre-first-chunk) and a cold `error` (the
// connect failed before any chunk) carry no data, so guard them first.
const CountDisplay = countLoader.View<number>(
  (s) => {
    if (s.status === 'error') return <p>Disconnected.</p>;
    if (s.status === 'connecting') return <p>Connecting...</p>;
    return (
      <div>
        <p>Count: {s.data}</p>
        <p>Status: {s.status}</p>
      </div>
    );
  },
  {
    initial: 0,
    reduce: (_acc, chunk) => chunk,
  }
);

export default function CounterPage() {
  return (
    <main>
      <CountDisplay />
    </main>
  );
}
```

**`counter.action.ts`** (server action that mutates and publishes):

```ts
import { defineAction } from 'hono-preact';
import { publish } from 'hono-preact';
import { counterChannel } from './counter-channel.js';
import { incrementCount } from './counter-db.js';

export const increment = defineAction(async () => {
  await incrementCount();
  // Signal channel: no message argument.
  publish(counterChannel.key());
});
```

Every client with the counter page open receives the new count within milliseconds of the action completing, without polling.

## How it works

Three pieces cooperate to wire up a live shared counter (or any data that changes on server events):

1. **Define a channel** with `defineChannel`. The name uses the same `/:param` grammar as route paths; `channel.key(params)` builds a branded `Topic<Payload>` that ties publish and subscribe together at the type level.
2. **Subscribe** from a `serverLoaders` entry by composing `liveStream({ topic, load })` into `route.loader(...)`. The loader runs `load` once on connect and again on every publish to `topic`. `liveStream` is inherently live, so no `{ live: true }` flag is needed. The framework streams the results to the client over SSE so you consume them with the accumulating `loader.View(render, { initial, reduce })` form.
3. **Publish** from a server action by calling `publish(channel.key(params), message)`. Every connected live loader subscribed to that topic re-runs `load` and pushes the new value.

## Parameterized channels

When the same data shape is segmented per resource, include the resource id in the channel name:

```ts
import { defineChannel, type Channel, type Topic } from 'hono-preact';

// Type is Channel<'board/:boardId', { taskId: string; to: string }>
export const boardChannel = defineChannel('board/:boardId')<{
  taskId: string;
  to: string;
}>();

// In a server action: boardChannel.key({ boardId }) is a Topic<{ taskId, to }>
import { publish } from 'hono-preact';
publish(boardChannel.key({ boardId: 'b1' }), { taskId: 't7', to: 'done' });
```

The `topic` and `load` functions in `liveStream` receive the same `ctx`, so both can read `ctx.location.pathParams` to key the subscription to the route:

```ts
import { serverRoute, liveStream } from 'hono-preact';

const route = serverRoute('/board/:boardId');

export const serverLoaders = {
  tasks: route.loader(
    liveStream({
      topic: (ctx) =>
        boardChannel.key({ boardId: ctx.location.pathParams.boardId }),
      load: async (ctx) => getTasks(ctx.location.pathParams.boardId),
    })
  ),
};
```

## Cross-connection fan-out

Live loaders are server-to-client over SSE. Publishing to a topic fans out to every live loader subscribed to that topic. On Node, the in-process bus reaches all connections on the same instance. On Cloudflare Workers, each request runs in an isolated Worker instance, so fan-out is backed by a Durable Object: a subscribe holds a Worker-to-DO socket and `publish()` POSTs to the topic's DO, which fans the event out to every subscriber across isolates. This uses the same `HONO_PREACT_REALTIME` Durable Object binding rooms use; see [Cloudflare setup](/docs/rooms#cloudflare-setup) for the binding. Note `publish()` syncs the event, not your state: subscribers re-run their `load()` to read the current shared state.

## API reference

### `defineChannel(name)<Payload>()`

Defines a typed channel. The name uses the `/:param` grammar. The `Payload` type parameter sets the message type. A `void` payload (the default) is a signal channel that publishes with no message.

```ts
const c = defineChannel('board/:boardId')<{ taskId: string }>();
```

|           | Type       | Description                                                          |
| --------- | ---------- | -------------------------------------------------------------------- |
| `name`    | `string`   | Channel address, e.g. `'board/:boardId'`. Params use `:name` syntax. |
| `Payload` | type param | Message type. Defaults to `void` (signal channel, no message).       |

Each `:` in `name` starts a param whose own name must be one or more of `[A-Za-z0-9_]`, optionally followed by a single `?`, `*`, or `+` modifier (e.g. `:id`, `:id?`, `:rest*`, `:rest+`). `defineChannel` throws immediately, at definition time, if any segment carries a `:` outside that grammar, including a `:` that appears mid-segment rather than at its start (e.g. `'board:boardId'`).

Returns a `Channel<Name, Payload>` with one method:

| Method                 | Signature                     | Description                                                                                                                                         |
| ---------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channel.key(params?)` | `(...args) => Topic<Payload>` | Builds a branded `Topic<Payload>`. For a param-less name the argument is omitted; for a name with params the argument is `{ [paramName]: string }`. |

### `publish(topic, message?)`

Publishes to a typed topic from a server action or server agent. Every live loader subscribed to `topic` re-runs its `load` and pushes the result to connected clients.

```ts
import { publish } from 'hono-preact';

publish(boardChannel.key({ boardId }), { taskId, to }); // payload channel
publish(counterChannel.key()); // signal channel
```

| Argument  | Type       | Description                                                          |
| --------- | ---------- | -------------------------------------------------------------------- |
| `topic`   | `Topic<P>` | The topic to publish to. Built with `channel.key(params)`.           |
| `message` | `P`        | Required for payload channels; omitted for `void` (signal) channels. |

### `liveStream({ topic, load })`

A generator helper for channel-driven live loaders. Yields `load(ctx)` once on connect, then re-runs and pushes the result on every publish to `topic(ctx)`. Because `liveStream` produces an inherently unbounded subscription, liveness is implied: compose it directly as `route.loader(liveStream({ topic, load }))` or `defineLoader(liveStream({ topic, load }))` without any `{ live: true }` flag.

| Option  | Type                                 | Description                                                                          |
| ------- | ------------------------------------ | ------------------------------------------------------------------------------------ |
| `topic` | `(ctx: LoaderCtx) => Topic<unknown>` | Returns the topic this loader subscribes to. Called with the same context as `load`. |
| `load`  | `(ctx: LoaderCtx) => Promise<T>`     | Produces the data snapshot. Called on connect and on every publish.                  |

The composed loader returns a `LoaderRef<T, true>`. Consume it with the accumulating form `ref.View(render, { initial, reduce })`. The `StreamStatus` and `.View` option table are described on the [Live Loaders](/docs/live-loaders) page.

### `eventStream(topic, signal)`

Subscribe to a topic as an async generator of its published payloads. Where `liveStream` re-runs a `load` snapshot on every publish (and discards the message), `eventStream` delivers each published payload itself, in order: the right shape for feeds and tickers where the event is the data.

```ts
import { defineChannel, defineLoader, eventStream } from 'hono-preact';

const activityChannel = defineChannel('activity')<ActivityEvent>();

export const serverLoaders = {
  activity: defineLoader(
    async function* ({ signal }) {
      for await (const e of eventStream(activityChannel.key(), signal)) {
        yield e;
      }
    },
    { live: true }
  ),
};
```

| Argument | Type             | Description                                                                            |
| -------- | ---------------- | -------------------------------------------------------------------------------------- |
| `topic`  | `Topic<Payload>` | The channel topic to subscribe to. Build it with `channel.key(...)`.                   |
| `signal` | `AbortSignal`    | Ends the stream and removes the subscription when aborted. Pass the loader's `signal`. |

Returns `AsyncGenerator<Serialize<Payload>, void, unknown>`. Payloads arrive in publish order and buffer while the consumer is busy. The yield type is the JSON wire shape (`Serialize<Payload>`): on Cloudflare a payload crosses isolates as JSON, so a `Date` arrives as its ISO string. If the underlying subscription drops, the generator throws, terminating the stream rather than going silently stale.

### Type exports

```ts
import type { Channel, Topic } from 'hono-preact';
import type { StreamStatus } from 'hono-preact';
```

## See also

- [Live Loaders](/docs/live-loaders): the persistent-layout streaming pattern, `.View` accumulating form, and `StreamStatus` reference.
- [Server Loaders](/docs/loaders): non-live loaders and the full `defineLoader` option table.
- [Server Actions](/docs/actions): where `publish` is typically called.


---

> Source: https://framework.sbesh.com/docs/actions

# Server Actions

Pages often need to mutate data: adding a record, toggling a flag, deleting a row. Server actions let you define those mutations as typed functions in your `.server.ts` file and call them from a form or a hook. No manual `fetch` wiring, no API route plumbing.

For long-running operations that emit progress or results incrementally, see [Streaming](/docs/streaming).

## Defining actions

**`src/pages/movies.server.ts`** (assumes `type MovieList = { results: { id: number; title: string }[] }`):

```ts
import { getMovies } from '@/server/movies.js';
import { defineAction } from 'hono-preact';

const serverLoader = async () => {
  const movies = await getMovies();
  return { movies };
};

export default serverLoader;

export const serverActions = {
  addMovie: defineAction<{ title: string }, { ok: boolean }>(
    async (_ctx, payload) => {
      await db.insert({ title: payload.title });
      return { ok: true };
    }
  ),
};
```

`defineAction` is a no-op at runtime; it just returns the function unchanged. Its only job is to brand the function with phantom types so `useAction` and `<Form>` can infer the payload and result types without codegen.

### Typing the payload

`defineAction` and `serverRoute(r).action` accept the payload type three ways; the explicit generics above are only one of them:

- **Explicit generics** — `defineAction<Payload, Result>(fn)`, as shown above.
- **Annotated parameters** — annotate the handler's payload argument and return type and drop the generics; the ref's types are inferred from the function:

  ```ts
  addMovie: defineAction(
    async (_ctx, payload: { title: string }): Promise<{ ok: boolean }> => {
      await db.insert({ title: payload.title });
      return { ok: true };
    }
  );
  ```

- **A validation schema** — pass a [Standard Schema](/docs/validation) as `input`; the payload type is the schema's validated output, inferred with no generics, and enforced at runtime before the handler runs:

  ```ts
  addMovie: defineAction(async (_ctx, payload) => db.insert(payload), {
    input: NewMovieSchema, // payload is InferOutput<typeof NewMovieSchema>
  });
  ```

With none of these, `payload` is typed `unknown` (never `any`), so the type system makes you narrow it before use rather than letting an untyped value through.

Only the schema form validates at runtime. The two type-only forms (explicit generics, annotated parameters) assert a shape the wire does not enforce: the client payload reaches the handler as-is. In dev, the server warns once per action when an action without an `input` schema receives a payload other than `undefined`, `null`, or an empty object.

### `defineAction` options

Pass a second argument to `defineAction(fn, opts)` to configure per-action behavior:

| Option      | Type              | Default | Description                                 |
| ----------- | ----------------- | ------- | ------------------------------------------- |
| `use`       | `ActionUse`       | none    | Per-action middleware and stream observers. |
| `timeoutMs` | `number \| false` | `30000` | Per-action deadline; `false` disables it.   |

The first argument is `ctx: ActionCtx`, which has two fields: `signal` (an `AbortSignal` tied to the HTTP request) and `c` (the request's Hono `Context`). Use `ctx.c` to read cookies (`getCookie`), set response headers, or reach Hono `Bindings` via `ctx.c.env`.

### Route-bound actions

Like loaders, an action can be bound to its route with `serverRoute(r)`. Calling `.action(fn)` is otherwise identical to `defineAction`: the action body's `ctx` still carries no typed `location` and reads its data from the payload, while the route's guard chain gates the request with a route-authoritative `location` matched against this route's pattern (see [Middleware](/docs/middleware)). It accepts the same options (`use`, `timeoutMs`, `input`) and types the payload the same three ways too (see [Typing the payload](#typing-the-payload)); the example below infers it from an `input` schema, so no `<Payload, Result>` generics are needed:

```ts
import { serverRoute } from 'hono-preact';
import { RateSchema } from './movie-schema.js';

const route = serverRoute('/movies/:id');

export const serverActions = {
  rate: route.action(
    async (_ctx, payload) => {
      // payload is InferOutput<typeof RateSchema>: { movieId: string; stars: number }
      await db.rate(payload.movieId, payload.stars);
      return { ok: true };
    },
    { input: RateSchema }
  ),
};
```

Binding the route makes the action resolve its page-level `use` chain from that exact route pattern. A bare `defineAction` is route-independent (like a bare `defineLoader`): its POST RPC runs only the app-level `use` and the action's own unit-level `use`, never a route node's page-layer `use`. So reach for `route.action` whenever an action lives under an authenticated layout, so the route-level gate (a `requireSession` on the parent route node, say) is applied by the action's own declared pattern. Otherwise put the gate on the action itself with a unit-level `use`. The same `route` binder typically already defines the page's loaders, so its loaders and actions read as one route-bound unit.

Bind an action to the route its module is registered on. Route-binding pins the `use` chain to the **declaring** route's gates, so the framework enforces that a route-bound action (or loader) names the route it is actually mounted on: a mismatch fails the request closed with a startup error rather than silently resolving the wrong route's gates. Using the same `route` binder for a module's loaders and actions keeps this correct by construction.

## Registering the handler

You do not register the action handler directly. The framework's Vite plugin generates the server entry, which mounts a page POST handler alongside the loader RPC and SSR catch-all, and exports it as the worker's default. The handler routes by `mod.__moduleKey` (the path-derived key injected into each `.server.*` file by `moduleKeyPlugin`).

If you ever need a custom server entry, see [`renderPage`](/docs/render-page) for the manual wiring contract.

## Calling from a form: `<Form action={stub}>`

`<Form action={stub}>` is the primary way to invoke an action. Pass the action stub directly to the `action` prop. On the client, `<Form>` intercepts the submit event, serializes the form fields, and fires a JSON POST to the page URL. Without JS, the form falls back to a native POST to the same URL and the page re-renders with the action result available via `useActionResult()`.

```tsx
import { definePage, Form } from 'hono-preact';
import { serverLoaders, serverActions } from './movies.server.js';

const dataLoader = serverLoaders.default;

const AddMovieForm = () => (
  <Form action={serverActions.addMovie}>
    <input name="title" placeholder="Title" />
    <button type="submit">Add Movie</button>
  </Form>
);

const MoviesView = dataLoader.View(({ data }) => {
  if (!data) return <p>Loading...</p>;
  return (
    <main>
      <AddMovieForm />
      <ul>
        {data.movies.results.map((m) => (
          <li key={m.id}>{m.title}</li>
        ))}
      </ul>
    </main>
  );
});

export default definePage(MoviesView);
```

`<Form>` accepts any HTML `<form>` attribute (except `onSubmit`, which it owns), plus `action` (required). The wrapping `<fieldset>` is disabled while the submission is in flight.

### FormData serialization

FormData values are collected into a plain object before being passed to the action. Single-value fields arrive as scalars (string for text inputs, `File` for file inputs). **Repeated field names** (checkboxes sharing a name, multi-select, `<input type="file" multiple>`) arrive as **arrays** in the order they appeared in the form. Declare the array fields in your `defineAction` payload type:

```ts
defineAction<{ title: string; tags: string[]; photos: File[] }, ...>
```

String values are passed as strings; coerce them in the action body if you need numbers or booleans. File inputs are handled automatically; see [File uploads](#file-uploads).

### Form lifecycle

`<Form>` accepts optional callbacks that fire after a submission resolves, plus
declarative cache invalidation and form reset:

| Prop         | Type                             | Notes                                                                                                                                             |
| ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onSuccess`  | `(data, { reset }) => void`      | Fires on a successful action. `reset()` clears the form; `reset(names)` clears specific fields.                                                   |
| `onError`    | `(err: Error) => void`           | Fires on an error, timeout, or unknown outcome. A `deny` is not an error; read it via `useActionResult`.                                          |
| `invalidate` | `'auto' \| false \| LoaderRef[]` | Same semantics as `useAction`'s `invalidate`: `'auto'` re-runs the active loader; an array clears each (and re-runs the active loader if listed). |
| `reset`      | `boolean`                        | Reset the form to its defaults after a successful submit.                                                                                         |

```tsx
<Form
  action={serverActions.createIssue}
  reset
  invalidate="auto"
  onSuccess={() => setShowForm(false)}
>
  <input name="title" />
  <button type="submit">Create</button>
</Form>
```

`reset` calls the form's native reset (restoring uncontrolled fields to their
defaults and firing a `reset` event). Controlled custom fields can subscribe to
that event to reset themselves.

## Progressive enhancement (PE): forms without JS

`<Form action={stub}>` works without JavaScript. On a no-JS page load the form submits as a standard HTML POST to the page URL. The server runs the action, then re-renders the page. Inside the rendered page, `useActionResult(stub?)` returns the outcome of that action call so you can show validation errors or a success message without requiring JavaScript.

```tsx
import { Form, useActionResult } from 'hono-preact';
import { serverActions } from './movies.server.js';

const AddMovieForm = () => {
  const result = useActionResult(serverActions.addMovie);

  return (
    <Form action={serverActions.addMovie}>
      {result?.kind === 'deny' && <p role="alert">{result.message}</p>}
      {result?.kind === 'deny' && result.data?.fieldErrors?.title && (
        <p>{result.data.fieldErrors.title}</p>
      )}
      <input
        name="title"
        placeholder="Title"
        defaultValue={result?.submittedPayload?.title ?? ''}
      />
      <button type="submit">Add Movie</button>
    </Form>
  );
};
```

`useActionResult(stub?)` returns the result of the most recent action invocation that targeted the current page render. The `submittedPayload` field lets you re-populate form inputs via `defaultValue` so users don't lose what they typed on a deny.

Pass no argument (or pass `undefined`) to receive the result of any action that posted to this page. Pass a specific stub to filter to that action only.

### Returning structured deny data

Use `deny()` with the `data` option to pass field-level error information back to the form:

```ts
import { defineAction, deny } from 'hono-preact';

export const serverActions = {
  addMovie: defineAction<{ title: string }, { ok: boolean }>(
    async (_ctx, payload) => {
      if (!payload.title.trim()) {
        throw deny(422, 'Validation failed', {
          data: { fieldErrors: { title: 'Title is required' } },
        });
      }
      await db.insert({ title: payload.title });
      return { ok: true };
    }
  ),
};
```

`deny(status, message, opts?)` accepts an optional third argument: `opts.data` is any value serializable to JSON. It is available as `result.data` in `useActionResult()` after a deny.

## Deny codes

`deny()` accepts a named code string instead of a numeric status. Codes map to standard HTTP statuses by default, but the numeric `status` is always authoritative when both are given:

```ts
import { deny } from 'hono-preact';

// Code only: status inferred from the code (404)
throw deny('NOT_FOUND');

// Code with a message
throw deny('FORBIDDEN', 'Members only');

// Code with structured data; status inferred from the code (409)
throw deny({ code: 'CONFLICT', data: { field: 'title' } });

// Explicit status overrides the code's default
throw deny({ status: 403, code: 'UNAUTHORIZED' });

// Numeric status form still works exactly as before (no code attached)
throw deny(404, 'Not found');
```

### Code to status defaults

The `DENY_CODE_STATUS` constant maps each code to its default HTTP status. Import it when you need to look up the status for a given code at runtime:

```ts
import { DENY_CODE_STATUS } from 'hono-preact';

const status = DENY_CODE_STATUS['NOT_FOUND']; // 404
```

| Code                | Default status |
| ------------------- | -------------- |
| `BAD_REQUEST`       | 400            |
| `UNAUTHORIZED`      | 401            |
| `FORBIDDEN`         | 403            |
| `NOT_FOUND`         | 404            |
| `CONFLICT`          | 409            |
| `UNPROCESSABLE`     | 422            |
| `TOO_MANY_REQUESTS` | 429            |
| `INTERNAL`          | 500            |

### Reading the code client-side

`useActionResult()` exposes `result.code` when the action called `deny()` with a code. Switch on it instead of comparing message strings:

```tsx
import { useActionResult } from 'hono-preact';
import { serverActions } from './movies.server.js';

const ActionFeedback = () => {
  const result = useActionResult(serverActions.addMovie);
  if (result?.kind !== 'deny') return null;

  switch (result.code) {
    case 'NOT_FOUND':
      return <p>Movie not found.</p>;
    case 'FORBIDDEN':
      return <p>You do not have permission.</p>;
    case 'CONFLICT':
      return <p>A movie with that title already exists.</p>;
    default:
      return <p>{result.message}</p>;
  }
};
```

`result.code` is `DenyCode | undefined`. It is `undefined` when the action used the numeric form `deny(status, message)`.

Deny codes are on the action path only. Loader denies surface as an `Error` without a structured code, so `result.code` is not available from loader error boundaries.

## Error handling

An action that throws anything other than a framework outcome (`deny`, `redirect`, a timeout) responds 500 with the uniform error envelope. In production the envelope's `message` is always `Action failed`: a thrown error's text can carry PII or internal detail, so it never reaches the client. In dev the real message passes through so the failure is readable in the network tab, and the server console prints a hint naming the action.

Because of the production mask, a plain thrown `Error` is the wrong way to reject bad input or denied access on purpose. Throw `deny(status, message)` instead; a deny's status, message, and `data` reach the client in every mode:

```ts
import { defineAction, deny } from 'hono-preact';

export const serverActions = {
  publish: defineAction(
    async (ctx, payload) => {
      const user = await currentUser(ctx.c);
      if (!user) throw deny(401, 'Sign in to publish.');
      // ...
    },
    { input: PublishSchema }
  ),
};
```

The same policy applies to route-bound chain resolution: when a route-bound action cannot resolve its page-use chain, the 500 message carries the resolver's detail only in dev.

## Calling programmatically: `useAction(stub)`

`useAction` manages pending state, error handling, and optional cache invalidation after the action completes. Use it for programmatic mutations: button `onClick` handlers, conditional logic before submitting, or any case where you need to await the result.

```tsx
import { useAction } from 'hono-preact';
import { serverLoaders, serverActions } from './movies.server.js';

const moviesLoader = serverLoaders.default;

const Movies = () => {
  const { data } = moviesLoader.useData();
  const { mutate, pending, error } = useAction(serverActions.addMovie, {
    invalidate: 'auto',
    onSuccess: (result) => console.log('added', result),
  });

  if (!data) return <p>Loading...</p>;

  return (
    <>
      <button onClick={() => mutate({ title: 'Dune' })} disabled={pending}>
        {pending ? 'Adding...' : 'Add Movie'}
      </button>
      {error && <p>{error.message}</p>}
    </>
  );
};
```

`useAction` posts to the page URL with `Accept: application/json, text/event-stream;q=0.9` and returns a discriminated result. The dual header lets json-returning actions negotiate a plain JSON response while still accepting a streaming one: when the action streams, the response arrives as `text/event-stream` and is delivered chunk by chunk to `onChunk` instead. The action body runs identically whether called from `<Form>` or `useAction`. `useAction` also accepts an opt-in `schema` option for client-side pre-validation; see [Validation](/docs/validation#pre-validating-an-imperative-action).

### Options

| Option       | Type                                      | Description                                                                                                                                                                                                                                                       |
| ------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalidate` | `'auto' \| false \| LoaderRef<unknown>[]` | `'auto'` re-runs the current page's `serverLoader` (via the `/__loaders` RPC in the browser). An array of [`LoaderRef`](/docs/loaders)s invalidates each loader's cache; pass loaders imported from other pages to refresh data across the app. Default: `false`. |
| `onMutate`   | `(payload) => unknown`                    | Called before the request fires on a dispatched mutation. Return value is passed to `onError` as `snapshot` for optimistic rollback. A client `schema` rejection short-circuits before dispatch, so it does not fire (see the note below the tables).             |
| `onSuccess`  | `(data) => void`                          | Called with the action's return value on success.                                                                                                                                                                                                                 |
| `onError`    | `(err, snapshot) => void`                 | Called with the error and the `onMutate` snapshot when a dispatched mutation fails: a server `deny`, error, or timeout. A client `schema` rejection does not fire it (see the note below the tables).                                                             |
| `onChunk`    | `(chunk: string) => void`                 | Called for each chunk when the action returns a streaming response. See [Streaming responses](#streaming-responses).                                                                                                                                              |

### Return value

| Value     | Type                                                                                                       | Description                                                                                                                                                                                                                                                                                               |
| --------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mutate`  | `(payload) => Promise<{ ok: true; data: Serialize<TResult> \| undefined } \| { ok: false; error: Error }>` | Fires the action. Resolves with a discriminated union so awaiting callers can chain on the result without leaking unhandled rejections. The same `error` is also written to the `error` state field for non-awaiting render-time use. Stable reference, safe to pass to `useEffect` or memoized children. |
| `pending` | `boolean`                                                                                                  | `true` while the request is in flight.                                                                                                                                                                                                                                                                    |
| `error`   | `Error \| null`                                                                                            | The last error, or `null` if none.                                                                                                                                                                                                                                                                        |
| `data`    | `Serialize<TResult> \| null`                                                                               | The last successful result, or `null`. Not set for streaming responses.                                                                                                                                                                                                                                   |

#### Chaining on success

```tsx
const { mutate } = useAction(addMovie);

async function submit(payload) {
  const result = await mutate(payload);
  if (result.ok) {
    navigate(`/movies/${result.data.id}`);
  } else {
    showToast(result.error.message);
  }
}
```

Non-awaiting callers (the common case: `onClick={() => mutate(payload)}`) still get the existing `error` state and `onError` callback for failure handling; no unhandled rejection is produced.

`onMutate` and `onError` bracket a dispatched request. A server `deny`, error, or timeout rejects the in-flight mutation, so `onError` fires (with the `onMutate` snapshot for rollback). A client-side `schema` rejection is different: it short-circuits **before** any request, so neither `onMutate` nor `onError` fires. The failure is still surfaced every other way, as the returned `{ ok: false, error }`, the hook's `error` state, and a `deny(422)` on `useActionResult` (decode the issues with `getValidationIssues`), so it renders identically to a server-caught validation failure. See [Validation](/docs/validation#pre-validating-an-imperative-action).

## Cancellation

`mutate` and `<Form>` submit both manage their in-flight request lifetime automatically.

**Unmount aborts the request.** If a component that called `mutate` unmounts while the request is in flight, the fetch is aborted. The abort is quiet: no error state is written, no `onError` fires. This prevents "setState after unmount" warnings without any cleanup code in the component.

`<Form>` submit works the same way: unmounting the form while a submit is in flight aborts the underlying fetch.

**Opt-in caller signal.** Pass `{ signal }` as the second argument to `mutate` to wire in your own `AbortSignal`. Either source (the caller signal or the unmount signal) aborts the request when triggered:

```tsx
const abortController = new AbortController();
const { mutate } = useAction(serverActions.addMovie);

// Start the mutation with a caller-owned signal
mutate({ title: 'Dune' }, { signal: abortController.signal });

// Cancel from anywhere in the component
abortController.abort();
```

**Concurrent mutations are not auto-aborted.** Calling `mutate` again while a previous call is in flight does not cancel the earlier request. Each call owns its own `AbortController`. This is deliberate: when a row of table cells each has an independent save button, aborting the first save on the second click would lose work. A component that wants abort-previous behavior brings its own signal:

```tsx
const controllerRef = useRef<AbortController | null>(null);
const { mutate } = useAction(serverActions.saveRow);

const handleSave = (payload) => {
  controllerRef.current?.abort();
  const controller = new AbortController();
  controllerRef.current = controller;
  mutate(payload, { signal: controller.signal });
};
```

**No-JS form posts cannot be cancelled.** The cancellation above applies to the JS-enhanced path only. When JavaScript is unavailable, `<Form>` submits a native HTML POST and there is no mechanism to abort it in flight.

**Write-loss on navigation.** When a component that owns a `mutate` call or a `<Form>` submit unmounts mid-flight (for example, the user navigates away), the request is aborted and the write may not reach the server. If a mutation must always complete regardless of navigation, drive it outside the cancelling component, or do not depend on it finishing after the component unmounts.

## Pending state outside the form

`useFormStatus(stub?)` reports whether a submission is currently in flight. It is JS-only (SSR always returns `{ pending: false }`). Use it for indicators outside the form's `<fieldset>`, such as a global spinner or a disabled navigation item.

```tsx
import { useFormStatus } from 'hono-preact';
import { serverActions } from './movies.server.js';

const SaveIndicator = () => {
  const { pending } = useFormStatus(serverActions.addMovie);
  return pending ? <p>Saving...</p> : null;
};
```

Pass no argument to track any in-flight form submission on the page. Pass a specific stub to track only that action.

## Optimistic updates

Use `onMutate` to update local state before the request fires, and `onError` to roll it back:

```tsx
const { data } = moviesLoader.useData();
const initialMovies = data ? data.movies.results : [];
const [items, setItems] = useState(initialMovies);

const { mutate } = useAction(serverActions.addMovie, {
  onMutate: (payload) => {
    const prev = items;
    setItems((cur) => [...cur, { id: 'temp', title: payload.title }]);
    return prev; // snapshot returned to onError
  },
  onError: (_err, snapshot) => {
    setItems(snapshot as typeof items); // restore on failure
  },
});
```

See [Optimistic UI](/docs/optimistic-ui) for the higher-level `useOptimisticAction` hook, which also integrates directly with `<Form action={result}>`.

## Cross-page cache invalidation

When a mutation on one page should refresh data on another, import the other page's loader and pass it to `invalidate`. Invalidation is by reference; there are no cache names:

```tsx
// movies.tsx: an action that should also refresh the ratings sidebar
import { useAction } from 'hono-preact';
import { serverLoaders as ratingsLoaders } from './ratings.server.js';
import { serverActions } from './movies.server.js';

const ratingsLoader = ratingsLoaders.default;

const { mutate } = useAction(serverActions.addMovie, {
  invalidate: [ratingsLoader], // clears ratingsLoader's cache on success
});
```

`invalidate` accepts an array of `LoaderRef`s, so a single action can refresh multiple loaders in one shot: `invalidate: [moviesLoader, ratingsLoader]`.

Use `'auto'` (instead of an array) to invalidate the current page's own loader after the action succeeds.

## Method form: `stub.useAction(opts)`

`useAction(stub, opts)` and `stub.useAction(opts)` are equivalent. Both ship; pick whichever reads better in context.

```tsx
import { useAction } from 'hono-preact';
import { serverLoaders, serverActions } from './movies.server.js';

const moviesLoader = serverLoaders.default;

// Method form:
const { mutate, pending } = serverActions.addMovie.useAction({
  invalidate: [moviesLoader],
});

// Equivalent function form:
const { mutate, pending } = useAction(serverActions.addMovie, {
  invalidate: [moviesLoader],
});
```

The method form reads more naturally when the action is the focus of the call site; the function form reads better when grouped with other hooks at the top of a component.

## File uploads

`useAction` automatically switches to `multipart/form-data` when the payload contains `File` objects. Since `<Form>` serializes file inputs as `File` instances in the payload, file uploads work transparently when you pair it with `useAction`.

**With `<Form>`:** add a file input; the framework detects the `File` value in the payload and sends FormData:

```tsx
const UploadPosterForm = ({ movieId, setPosterUrl }) => (
  <Form action={serverActions.uploadPoster}>
    <input type="hidden" name="movieId" value={movieId} />
    <input type="file" name="poster" accept="image/*" />
    <button type="submit">Upload Poster</button>
  </Form>
);
```

**With `useAction`:** include a `File` in the payload object:

```tsx
const { mutate } = useAction(serverActions.uploadPoster);

const handleChange = (e: Event) => {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (file) mutate({ movieId: movie.id, poster: file });
};
```

The action receives the `File` object directly:

```ts
export const serverActions = {
  uploadPoster: defineAction<
    { movieId: string; poster: File },
    { url: string }
  >(async (_ctx, { movieId, poster }) => {
    const url = await uploadToStorage(movieId, poster);
    return { url };
  }),
};
```

Non-`File` values in a FormData payload are serialized as strings (numbers and booleans via `JSON.stringify`). Repeated field names (multi-checkbox groups, multi-select, `<input type="file" multiple>`) are forwarded as arrays; type your action's payload accordingly (`tags: string[]`, `photos: File[]`, etc.) instead of expecting a single value.

## Streaming responses

An action can be a streaming generator for long-running operations. Streaming actions must be invoked via `useAction`; they cannot be used with `<Form action={stub}>` (a type error). See [Streaming: limitations](/docs/streaming#form-limitations) for details.

```ts
// movies.server.ts
export const serverActions = {
  bulkImport: defineAction(async function* (_ctx, payload: { url: string }) {
    const source = await fetch(payload.url);
    let count = 0;
    for await (const item of parseNDJSON(source.body!)) {
      await saveMovie(item);
      count++;
      yield { count };
    }
    return { imported: count };
  }),
};
```

```tsx
// movies.tsx
const [progress, setProgress] = useState(0);

const { mutate, pending } = useAction(serverActions.bulkImport, {
  onChunk: (p) => setProgress(p.count),
  onSuccess: (r) => console.log(`imported ${r.imported}`),
});
```

Each `onChunk` call receives a typed chunk. `onSuccess` receives the typed final result. `data` holds the final result after the stream closes.

## Gating actions with middleware

Actions accept the same `use` array as loaders and pages. Use it for authentication, authorization, rate limiting, or any other gate that should fire before the action body runs:

```ts
// movies.server.ts
import { defineAction, defineServerMiddleware, deny } from 'hono-preact';

const requireAuth = defineServerMiddleware<'action'>(async (ctx, next) => {
  const token = ctx.c.req.header('Authorization');
  if (!token) throw deny(401, 'Authentication required');
  await next();
});

export const serverActions = {
  addMovie: defineAction<{ title: string }, { ok: boolean }>(
    async (_ctx, payload) => {
      /* ... */
    },
    { use: [requireAuth] }
  ),
};
```

For route-wide gating (every render, plus every route-bound loader and action, under a route), declare `use` on the route node in `src/routes.ts`. A route node's `use` covers route-bound units only: a bare `defineAction` or `defineLoader` is route-independent, so its RPC is not gated by the route node (see [Middleware](/docs/middleware) for why). To bind an action to that route node's gate by exact pattern, define it with [`route.action`](#route-bound-actions); otherwise gate the bare action with its own unit-level `use`.

## Inference types

The inference helpers extract an action ref's type parameters without re-importing the action definition. They resolve to the authored server-side type, not the serialized wire shape.

```ts
import type {
  InferActionPayload,
  InferActionResult,
  InferActionChunk,
  Serialize,
} from 'hono-preact';
import type { serverActions } from './movies.server.js';

type AddMovie = typeof serverActions.addMovie;

// The payload type declared in defineAction
type Payload = InferActionPayload<AddMovie>;
// { title: string }

// The result type declared in defineAction (server-side, pre-serialization)
type Result = InferActionResult<AddMovie>;
// { ok: boolean }

// The wire shape (JSON round-trip); compose with Serialize for the client-visible type
type WireResult = Serialize<InferActionResult<AddMovie>>;

// The streaming chunk type; never for non-streaming actions
type Chunk = InferActionChunk<AddMovie>;
```

`Serialize<InferActionResult<typeof action>>` is the correct type for the client-visible result. `InferActionResult` gives you the server-side type; `Serialize<T>` applies the JSON round-trip transformation (matching the type that `useAction().data` and `<Form onSuccess>` carry).

### API reference

| Helper                  | Resolves to                                                               |
| ----------------------- | ------------------------------------------------------------------------- |
| `InferActionPayload<A>` | The action's payload type (`TPayload`)                                    |
| `InferActionResult<A>`  | The action's result type (`TResult`, server-side)                         |
| `InferActionChunk<A>`   | The streaming chunk type (`TChunk`), or `never` for non-streaming actions |

## How it works

Define a `serverActions` map in your `.server.ts` file alongside the loader. Each action is wrapped with `defineAction` to carry its payload and result types.

Actions are invoked via POST to the owning page's URL. On the client, the Vite plugin replaces the `serverActions` import with a Proxy: each property access returns an `ActionRef` object that encodes the module and action name. Neither the function body nor its imports ever reach the browser bundle.

## Timeouts

Actions get a deadline. By default every call has 30 seconds to finish; the
deadline starts when the handler receives the request. Pass `timeoutMs` on
`defineAction` to override:

```ts
export const slowExport = defineAction<{ id: string }, { ok: boolean }>(
  async (_ctx, { id }) => {
    /* ... */
  },
  { timeoutMs: 60_000 }
);
```

Pass `timeoutMs: false` to opt out entirely (useful for streaming actions):

```ts
export const longRunningStream = defineAction(
  async function* (_ctx, payload: { url: string }) {
    /* returns a stream that may run for minutes */
  },
  { timeoutMs: false }
);
```

When a deadline fires, the action's `ctx.signal` aborts with reason
`DOMException('TimeoutError')`. The server responds with status 504 and a
`{ __outcome: 'timeout', timeoutMs }` envelope. On the client, the failure
surfaces as a `TimeoutError` instance (with `kind: 'timeout'` and the original
`timeoutMs` as class properties).

## The server/client boundary

`serverOnlyPlugin` rewrites `serverActions` imports in the client bundle with a Proxy: each property access returns an `ActionRef` with the module and action name. `serverLoaderValidationPlugin` enforces that `.server.*` files only export `serverLoaders`, `serverActions`, `serverRooms`, or `serverSockets`. See [Overview: The server/client boundary](/docs#the-serverclient-boundary) for the full explanation.

## Security: SameSite cookies on form posts

Form posts go to the page URL on the same origin. The framework relies on
`SameSite=Lax` (Hono's cookie default) for CSRF protection. Cross-origin POSTs
without a credential do not carry the session cookie; cross-origin POSTs from a
malicious site cannot read the response.

If you need a stricter posture, mount Hono's CSRF middleware app-wide via
`appConfig.use` or scope it to specific paths in your `src/api.ts`. See [CSRF Protection](/docs/csrf) for the
full recipe.


---

> Source: https://framework.sbesh.com/docs/validation

# Validation

The framework integrates with the [Standard Schema](https://standardschema.dev) spec so you can validate action payloads, form fields, and loader params using any compliant library: Zod, Valibot, ArkType, or any other implementation. The framework depends only on the types-only `@standard-schema/spec` package and never on a specific validator.

## Covered surfaces

Validation covers four payload surfaces:

- **Action payloads** via `defineAction(fn, { input })`: server-enforced; the handler receives the schema's output type.
- **Form fields** via `<Form schema>`: opt-in client pre-validation before the POST fires.
- **Loader search params** via `serverRoute(path).loader(fn, { searchSchema })`: validates and coerces `ctx.location.searchParams`.
- **Loader route params** via `serverRoute(path).loader(fn, { paramsSchema })`: validates and coerces `ctx.location.pathParams`.

**The server is always authoritative.** Client-side validation (the `<Form schema>` prop) is an opt-in enhancement that only works when the schema is importable by the browser. Both paths surface through the same field-error rendering API.

**The framework does not coerce.** Standard Schema validates `Input -> Output` and the framework passes the raw payload as `Input`. Coercing FormData strings (e.g. `z.coerce.number()`) is the schema author's job.

## Action validation

Pass `input` to `defineAction` to attach a schema. On the server, the framework runs the schema before calling your handler; if validation fails the handler never runs and the action returns a `deny(422)` with the issues embedded in `deny.data`. On success the handler receives the schema's output type (coercion is visible).

```ts
// tasks.server.ts
import { defineAction } from 'hono-preact';
import { z } from 'zod';

const NewTask = z.object({
  title: z.string().min(1, 'Title is required'),
  priority: z.enum(['urgent', 'high', 'medium', 'low']),
});

export const serverActions = {
  createTask: defineAction(
    async (_ctx, payload) => {
      // payload: { title: string; priority: 'urgent' | 'high' | 'medium' | 'low' }
      const task = await db.tasks.create(payload);
      return { id: task.id };
    },
    { input: NewTask }
  ),
};
```

The handler's `payload` type is inferred from the schema's output. No explicit type annotation is needed.

### Reading issues client-side

`getValidationIssues(result)` pulls issues from a `useActionResult()` result when the result is a schema-validation failure. It returns `ValidationIssue[]` or `null` for non-validation denies.

```tsx
import { Form, useActionResult, getValidationIssues } from 'hono-preact';
import { serverActions } from './tasks.server.js';

const CreateForm = () => {
  const result = useActionResult(serverActions.createTask);
  const issues = getValidationIssues(result);

  return (
    <Form action={serverActions.createTask}>
      {issues && (
        <ul role="alert">
          {issues.map((issue, i) => (
            <li key={i}>{issue.message}</li>
          ))}
        </ul>
      )}
      <input name="title" placeholder="Title" />
      <button type="submit">Create</button>
    </Form>
  );
};
```

## Form client pre-validation

Pass `schema` to `<Form>` to enable client-side pre-validation. When schema validation fails on submit, the POST is blocked and the field errors are stored in form-local state. Once a field has shown an error, it re-validates on input so the error clears as the user fixes it.

Because `.server.*` files are stripped to typed proxies on the client, a schema passed to `<Form schema>` **must live in a shared (non-`.server`) module**. A schema used only server-side can be a local `const` inside the `.server.*` file.

```ts
// tasks.schema.ts  (shared module, not *.server.*)
import { z } from 'zod';

export const NewTaskSchema = z.object({
  title: z.string().min(1, 'Title is required'),
  priority: z.enum(['urgent', 'high', 'medium', 'low']),
});
```

```ts
// tasks.server.ts
import { defineAction } from 'hono-preact';
import { NewTaskSchema } from './tasks.schema.js';

export const serverActions = {
  createTask: defineAction(
    async (_ctx, payload) => {
      const task = await db.tasks.create(payload);
      return { id: task.id };
    },
    { input: NewTaskSchema }
  ),
};
```

```tsx
// tasks.tsx
import { Form, FieldError, useFieldErrorProps } from 'hono-preact';
import { serverActions } from './tasks.server.js';
import { NewTaskSchema } from './tasks.schema.js';

const TitleField = () => (
  <label>
    Title
    <input
      name="title"
      placeholder="Short summary"
      {...useFieldErrorProps('title')}
    />
    <FieldError name="title" />
  </label>
);

const CreateTaskForm = () => (
  <Form action={serverActions.createTask} schema={NewTaskSchema}>
    <TitleField />
    <button type="submit">Create</button>
  </Form>
);
```

Spreading `useFieldErrorProps('title')` onto the input associates it with its `<FieldError>` for assistive technology: when the field has an error the hook returns `aria-invalid` and an `aria-describedby` pointing at the error element's id (and nothing when the field is valid). Wire it on every field so screen-reader users hear the error tied to the control, not just an isolated alert.

The `schema` prop is typed as `StandardSchemaV1<unknown, TPayload>` where `TPayload` is the action's inferred payload type. Passing a schema that produces the wrong shape is a compile error, so the action and form cannot drift.

### Rendering field errors

**`<FieldError name>`** renders the first error message for a field, or nothing. It is a thin convenience wrapper around `useFieldErrors()`.

```tsx
<FieldError name="title" />
<FieldError name="title" class="text-red-500 text-sm" />

{/* Form-level errors (issues with no field path) */}
<FieldError name="" />
```

**`useFieldErrors()`** returns the full `FieldErrorsMap` (a `Record<string, string[]>`) for custom rendering. It reads from form context and is only useful inside a `<Form>`.

```tsx
import { useFieldErrors } from 'hono-preact';

const TitleField = () => {
  const errors = useFieldErrors();
  const titleErrors = errors['title'] ?? [];

  return (
    <label>
      Title
      <input name="title" />
      {titleErrors.length > 0 && (
        <ul>
          {titleErrors.map((msg, i) => (
            <li key={i}>{msg}</li>
          ))}
        </ul>
      )}
    </label>
  );
};
```

**`useFieldErrorProps(name)`** returns the ARIA props to spread onto a field control (`<input>`/`<select>`/...) so it is programmatically associated with its `<FieldError>`. When the field has an error it returns `{ 'aria-invalid': true, 'aria-describedby': <error id> }`; when valid it returns `{}`, so the attributes are absent rather than stale. The id it references is the one `<FieldError>` renders, scoped per `<Form>` so two forms on a page do not collide.

Both `useFieldErrors()` and `<FieldError>` unify client pre-validation issues and server-returned `deny(422)` issues into the same field-error surface, so client-skipped and server-caught errors render identically. Client pre-validation errors clear as you type once a field has been shown an error; server-returned field errors (from a `deny(422)` response) clear on the next submit rather than on input.

### Pre-validating an imperative action

`useAction` takes the same opt-in `schema` as `<Form>`, so an action called from a click handler or other imperative code gets the same client-side gate.

```tsx
import { useAction, useActionResult, getValidationIssues } from 'hono-preact';
import { serverActions } from './tasks.server.js';
import { NewTaskSchema } from './tasks.schema.js';

const CreateTaskButton = () => {
  const { mutate, pending } = useAction(serverActions.createTask, {
    schema: NewTaskSchema,
  });
  const issues = getValidationIssues(useActionResult(serverActions.createTask));

  return (
    <>
      <button
        onClick={() => mutate({ title: '', priority: 'medium' })}
        disabled={pending}
      >
        Create
      </button>
      {issues && (
        <ul role="alert">
          {issues.map((issue, i) => (
            <li key={i}>{issue.message}</li>
          ))}
        </ul>
      )}
    </>
  );
};
```

An invalid payload is rejected locally, no request goes out, and `mutate` surfaces the same `deny(422)` a server validation failure produces, so `getValidationIssues` decodes both the same way. If the schema's `validate` throws, the request proceeds and the server validates instead. The server always re-validates and coerces; the client gate never changes what is sent. Because a client-caught rejection short-circuits before any request, the mutation lifecycle never starts, so `onMutate`/`onError` do not fire for it; the path-independent way to surface issues either way is `getValidationIssues(useActionResult(stub))`, which reads the same whether the client or the server rejected.

## Loader validation

Pass `searchSchema` or `paramsSchema` to `serverRoute(path).loader(fn, opts)` to validate and coerce URL params. Validation schemas apply to route-bound loaders because they validate the URL's search and path params, which only route-bound loaders have.

- **`searchSchema` failure** is a 400 (bad query string).
- **`paramsSchema` failure** is a 404 (the URL does not name a valid resource).

Validation runs on both entry paths, but they fail differently because they happen at different layers. On a **direct page load (SSR)** an invalid param is a bad URL: the response is a plain `400`/`404` (the status above), and no client error boundary renders. On a **client navigation (loader RPC fetch)** the failure reaches the loader's error boundary, where you can render a custom fallback and read the field issues (below). Use `.default(...)` for optional search params you want to render rather than error on.

### Reading loader validation issues

On the client-navigation path the failure reaches the error boundary as a `LoaderValidationError` carrying the same normalized field issues an action's `deny(422)` does. Read them with `getValidationIssues(error)`, the same reader the action path uses, so field-level errors render identically across actions and loaders:

```tsx
import { LoaderValidationError, getValidationIssues } from 'hono-preact';

function LoaderErrorFallback({ error }: { error: unknown }) {
  const issues = getValidationIssues(error);
  if (error instanceof LoaderValidationError && issues) {
    return (
      <ul>
        {issues.map((issue, i) => (
          <li key={i}>
            {issue.path.join('.')}: {issue.message}
          </li>
        ))}
      </ul>
    );
  }
  return <p>Something went wrong.</p>;
}
```

`getValidationIssues` returns `null` for any non-validation failure (an app-level `deny`, a thrown error), so the same reader works for action results and loader errors alike.

This fallback renders on client navigation. A direct/refreshed load of the same invalid URL returns a bare `400`/`404` instead (a bad URL is a status, not a field-error screen), so do not rely on it for first-paint rendering.

```ts
import { serverRoute } from 'hono-preact';
import { z } from 'zod';

// Validate and coerce search params.
const route = serverRoute('/tasks');

export const serverLoaders = {
  list: route.loader(
    (ctx) => {
      // ctx.location.searchParams: { page: number }
      return getTasksPage(ctx.location.searchParams.page);
    },
    {
      searchSchema: z.object({ page: z.coerce.number().min(1).default(1) }),
      params: ['page'],
    }
  ),
};
```

```ts
import { serverRoute } from 'hono-preact';
import { z } from 'zod';

// Validate and coerce route params.
const route = serverRoute('/tasks/:id');

export const serverLoaders = {
  default: route.loader(
    (ctx) => {
      // ctx.location.pathParams: { id: number }
      return getTask(ctx.location.pathParams.id);
    },
    { paramsSchema: z.object({ id: z.coerce.number().int() }) }
  ),
};
```

The loader's `ctx.location.searchParams` and `ctx.location.pathParams` types narrow to the schema's output when a schema is present.

**Note:** `useParams()` on the client always returns raw string params from the route match. The coerced types are a loader-side concern only.

**Cache keys and search params:** `searchSchema` does not automatically add params to the client-side cache key. When the loader's data depends on a search param, declare that param in `params` (as shown above for `page`). Without it, navigating `?page=1` to `?page=2` returns the cached page-1 result.

## Validation timing and what middleware sees

Understanding when validation runs clarifies what each layer of the stack receives.

**Handlers receive coerced output.** A declared `input` (on `defineAction`) or `searchSchema`/`paramsSchema` (on `serverRoute(path).loader`) is validated and coerced before the handler runs. The handler receives the schema's output type, so coercions (like `z.coerce.number()`) are already applied by the time your code sees the value.

**Middleware and observers see the raw payload.** Auth guards, page-use middleware, and stream observers all run earlier in the request pipeline, before the validation step. They receive the raw, pre-validation payload or params, not the coerced values. If a middleware needs a typed value (for example, a numeric id), it should coerce that field itself. This ordering is intentional: auth gates reject unauthenticated requests before any validation work happens, so a malformed payload never reaches guarded logic.

**Action schemas should be coercion-tolerant.** `<Form>` and any multipart or file POST send fields as strings because FormData is string-only. A `useAction` call that includes a `File` also sends a multipart body. A `useAction` call with no files sends typed JSON. Schemas used with actions that may receive either format should use coercing rules (e.g. `z.coerce.number()`, or valibot's `v.pipe(v.unknown(), v.transform(Number))`) so the same logical payload validates whether it arrives as a typed value or as a string.

A future option to configure validation position in the middleware chain is tracked as a potential addition.

## API reference

### `defineAction(fn, { input })`

| Option  | Type               | Description                                                                                                                                          |
| ------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input` | `StandardSchemaV1` | Schema applied to the action payload before the handler runs. Failure produces `deny(422)` with issues under a reserved key; the handler never runs. |

### `serverRoute(id).loader(fn, { searchSchema, paramsSchema })`

| Option         | Type               | Description                                                                                                                                                        |
| -------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `searchSchema` | `StandardSchemaV1` | Validates and coerces `ctx.location.searchParams`. Failure is a 400: a bare status on direct load, a `LoaderValidationError` carrying issues on client navigation. |
| `paramsSchema` | `StandardSchemaV1` | Validates and coerces `ctx.location.pathParams`. Failure is a 404: a bare status on direct load, a `LoaderValidationError` carrying issues on client navigation.   |

### `<Form schema>`

| Prop     | Type                                  | Description                                                                                                                                        |
| -------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema` | `StandardSchemaV1<unknown, TPayload>` | Schema for client-side pre-validation. Must live in a shared (non-`.server`) module. Typed to the action's payload; mismatches are compile errors. |

### `useAction(stub, { schema })`

| Option   | Type                                  | Description                                                                                                                                                     |
| -------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema` | `StandardSchemaV1<unknown, TPayload>` | Same opt-in client-side pre-validation as `<Form schema>`, for imperative `mutate` calls. Fails open: a throwing schema lets the request through to the server. |

### `getValidationIssues(result)`

```ts
function getValidationIssues(result: ActionResult): ValidationIssue[] | null;
```

Extracts validation issues from `useActionResult()`. Returns `null` when the result is not a schema-validation failure. A validation failure is a `deny` whose `data` carries the framework-reserved validation key; this distinguishes it from an app-level `deny`.

### `useFieldErrors()`

```ts
function useFieldErrors(): FieldErrorsMap;
// type FieldErrorsMap = Record<string, string[]>
```

Returns the enclosing `<Form>`'s merged field errors, keyed by field name. The path segments from each issue are joined with `.` (`['address', 'zip']` becomes `"address.zip"`). Issues with no path map to `""` (form-level errors). Returns `{}` outside a `<Form>`.

### `<FieldError name>`

| Prop     | Type                  | Description                                                                 |
| -------- | --------------------- | --------------------------------------------------------------------------- |
| `name`   | `string`              | The field key to render. Pass `""` for form-level errors.                   |
| `class`  | `string`              | Optional CSS class, merged onto a custom `render` element.                  |
| `render` | `RenderElementRender` | Customize the rendered element (a tag name, a VNode, or a render function). |

Renders the first error message for `name` inside a `<span data-field-error={name} role="alert">`, or nothing when there are no errors. The `render` prop follows the framework render-element convention, pass a tag name (`render="p"`), a VNode to merge the framework props into (`render={<MyError />}`), or a function `(props) => VNode`; `data-field-error` and `role="alert"` are always applied. Use `useFieldErrors()` directly for fully custom rendering.

### Types

| Name               | Description                                                           |
| ------------------ | --------------------------------------------------------------------- |
| `StandardSchemaV1` | The Standard Schema interface. Any compliant validator implements it. |
| `ValidationIssue`  | A single normalized validation problem: `{ path, message }`.          |
| `FieldErrorsMap`   | `Record<string, string[]>`: field name to error messages.             |

To infer the input or output type of a schema, use `StandardSchemaV1.InferInput<S>` and `StandardSchemaV1.InferOutput<S>` from the `@standard-schema/spec` package, or the equivalent helpers your schema library provides (e.g. `z.infer<typeof MySchema>` for Zod, `v.InferOutput<typeof MySchema>` for Valibot).

## Related

- [Server Actions](/docs/actions): defining and calling actions
- [Server Loaders](/docs/loaders): typed data fetching with `defineLoader`


---

> Source: https://framework.sbesh.com/docs/optimistic-ui

# Optimistic UI Updates

`useOptimistic` and `useOptimisticAction` let you show the result of a mutation in the UI before the server confirms it, then automatically reconcile when the server responds. They compose with the existing `useAction` hook with no changes to your loaders or actions.

## Why two hooks?

- **`useOptimistic`** is a primitive: it maintains a queue of pending changes layered over a base value. You hold the queue handles and decide when to settle (success) or revert (error) each entry. Use it directly when you need full control or when one piece of optimistic state is fed by multiple actions.
- **`useOptimisticAction`** is a wrapper around `useAction` + `useOptimistic` for the common single-action case. It owns the queue lifecycle for you.

Start with `useOptimisticAction`. Drop down to the primitive if you outgrow it.

## `useOptimisticAction`

```tsx
import { useOptimisticAction, Form } from 'hono-preact';
import { serverActions } from './movies.server.js';

const Movies = ({ loaderData }) => {
  const addMovie = useOptimisticAction(serverActions.create, {
    base: loaderData.movies,
    apply: (current, payload) => [...current, payload],
    invalidate: 'auto',
    onSuccess: (data) => console.log('created', data),
    onError: (err) => console.error(err),
  });

  return (
    <>
      <ul>
        {addMovie.value.map((m) => (
          <li key={m.id}>{m.title}</li>
        ))}
      </ul>
      <Form action={addMovie}>
        <input name="title" placeholder="Title" />
        <button type="submit">Add</button>
      </Form>
    </>
  );
};
```

`value` is the projection: `base` with all in-flight payloads applied via `apply`. While the mutation is in flight, `addMovie.value` includes the optimistic entry; after the server responds and the loader refetches (`invalidate: 'auto'`), `addMovie.value` reflects real server data with no visual gap.

The returned object is stub-compatible: pass it to `<Form action={addMovie}>` for declarative form submission, or call `addMovie.mutate(payload)` for programmatic invocation. Both paths participate in the optimistic queue. Access `addMovie.pending`, `addMovie.error`, and `addMovie.data` to read the mutation status and result.

### Options

| Option       | Type                             | Description                                                                                       |
| ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------- |
| `base`       | `TBase`                          | The base value (typically loader data) the projection layers over                                 |
| `apply`      | `(current, payload) => TBase`    | Reducer that produces the next projection                                                         |
| `invalidate` | `'auto' \| LoaderRef<unknown>[]` | Refetch trigger after mutation succeeds. `false` is intentionally not allowed (see below).        |
| `onSuccess`  | `(data) => void`                 | Called after a successful mutation. Snapshot is internal; not exposed here.                       |
| `onError`    | `(err) => void`                  | Called after a failed mutation. The optimistic entry is reverted automatically before this fires. |

Other `useAction` options (`onChunk`) pass through.

### Why no `invalidate: false`?

The optimistic entry settles into `'ready'` state on success and waits for the base to update before evicting. Without an invalidation that refetches, the base never changes, the entry lingers, and the UI gets stuck. Use `useOptimistic` directly if you have a use case where base updates by another path.

## `useOptimistic` (primitive)

```tsx
import { useOptimistic, useAction } from 'hono-preact';

const Movies = ({ loaderData }) => {
  const [movies, addOptimistic] = useOptimistic(
    loaderData.movies,
    (current, payload) => [...current, payload]
  );

  const { mutate } = useAction(serverActions.create, {
    invalidate: 'auto',
    onMutate: (payload) => addOptimistic(payload),
    onSuccess: (_data, handle) => handle.settle(),
    onError: (_err, handle) => handle.revert(),
  });

  return (
    <ul>
      {movies.map((m) => (
        <li key={m.id}>{m.title}</li>
      ))}
    </ul>
  );
};
```

`addOptimistic(payload)` appends a queue entry and returns an `OptimisticHandle`:

```ts
type OptimisticHandle = {
  settle: () => void; // success: linger until base ref changes
  revert: () => void; // error: remove immediately
};
```

The handle becomes the snapshot in `useAction`'s `onMutate`/`onSuccess`/`onError` chain.

## Concurrent mutations

Both APIs handle concurrent mutations correctly. If a user fires two mutations and the first completes before the second, the second's optimistic entry survives the first's settle-and-refetch:

```
queue=[A:active, B:active]
  → A succeeds, A.settle()
queue=[A:ready, B:active]
  → loader refetches, base updates (A confirmed)
  → A:ready evicted (base ref changed), B:active stays
queue=[B:active]
  → UI shows server-confirmed A + optimistic B
```

No special configuration needed.

## Composing with `<Form>`

`useOptimisticAction` returns a stub-compatible value that you can pass directly to `<Form action={...}>`. The result carries the action's type brand, so the form knows how to invoke it and TypeScript enforces the payload shape.

```tsx
const NotesForm = ({ defaultNotes }) => {
  const notesAction = useOptimisticAction(serverActions.setNotes, {
    base: defaultNotes,
    apply: (_current, payload) => payload.notes,
    invalidate: 'auto',
  });

  return (
    <>
      <p>Current: {notesAction.value}</p>
      <Form action={notesAction}>
        <textarea name="notes" defaultValue={notesAction.value} />
        <button>Save</button>
      </Form>
    </>
  );
};
```

The returned object exposes `notesAction.mutate(payload)` and `notesAction.pending` directly, so you can call it from an `onClick` handler or await it in an async function without holding a separate `useAction` ref.

## `<OptimisticOverlay>`

`<OptimisticOverlay>` projects a list of pending actions onto the loader data that descendant components see via `loader.useData()`. Use it when a child component reads loader data and you want it to render against an optimistic projection without rewriting the child to take a prop.

```tsx
import { OptimisticOverlay } from 'hono-preact/internal';
import { serverLoaders } from './movies.server.js';

const moviesLoader = serverLoaders.default;

const MovieList = () => {
  const { data } = moviesLoader.useData();
  if (!data) return <p>Loading...</p>;
  return (
    <ul>
      {data.map((m) => (
        <li key={m.id}>{m.title}</li>
      ))}
    </ul>
  );
};

const MoviesPage = ({ pendingAdds }) => (
  <OptimisticOverlay
    loader={moviesLoader}
    reducer={(base, action) => [...base, action]}
    pending={pendingAdds}
  >
    <MovieList />
  </OptimisticOverlay>
);
```

`OptimisticOverlay` lives in the `hono-preact/internal` subpath, which has no semver guarantee. Use it when you need projection through `loader.useData()`; prefer `useOptimistic` or `useOptimisticAction` for local optimistic state.

`<OptimisticOverlay>` must be inside a route or `<Page>` configured with the same `loader` it references; otherwise it throws.

| Prop      | Type                        | Description                                                                          |
| --------- | --------------------------- | ------------------------------------------------------------------------------------ |
| `loader`  | `LoaderRef<T>`              | The loader whose data is being projected. Must match the surrounding route's loader. |
| `reducer` | `(base: T, action: A) => T` | Folds each pending action into the base value.                                       |
| `pending` | `A[]`                       | Pending actions to project. Defaults to `[]`.                                        |

Prefer `useOptimistic` or `useOptimisticAction` when the optimistic state is local to the component that owns the mutation. Reach for `<OptimisticOverlay>` when the optimistic projection needs to flow through `loader.useData()` for descendants you don't want to thread props through.

## View Transitions

`useOptimistic` and `useOptimisticAction` accept `{ transition: true }` to
wrap settle and revert state changes in
[`document.startViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition).
See [View Transitions](/docs/view-transitions) for the full toolkit of named elements, lifecycle hooks, and direction-driven types.
The initial optimistic update is never wrapped so it paints in the same
frame. When `startViewTransition` is not available (older browsers or SSR),
the option is a no-op.

```ts
const [count, addOptimistic] = useOptimistic(serverCount, reducer, {
  transition: true,
});
```

Style transitions with `::view-transition-old(*)` and `::view-transition-new(*)`
CSS pseudo-elements, or attach `view-transition-name` to specific elements
for element-level animations.


---

> Source: https://framework.sbesh.com/docs/server-caller

# Server Caller

Loaders and actions can call each other server-side without an HTTP round-trip using `ctx.call`. The called procedure runs in the same request scope, its input is validated, and the result carries the authored type with no JSON serialization. For testing outside a live request, `createCaller(c)` binds the same mechanism to any Hono `Context` you provide.

## Calling from inside a handler

Every loader and action receives a `call` method on its context object. Pass another loader ref as the first argument to invoke it directly:

```ts
// src/pages/movie.server.ts
import { serverRoute } from 'hono-preact';
import { serverLoaders as reviewLoaders } from './reviews.server.js';

const reviewsLoader = reviewLoaders.default;
const route = serverRoute('/movies/:id');

export const serverLoaders = {
  default: route.loader(async (ctx) => {
    const movie = await fetchMovie(ctx.location.pathParams.id);
    const reviewsResult = await ctx.call(reviewsLoader, {
      location: { pathParams: ctx.location.pathParams },
    });
    if (!reviewsResult.ok) throw reviewsResult.outcome;
    return { movie, reviews: reviewsResult.value };
  }),
};
```

`ctx.call` returns a `CallResult<T>` discriminated union. Narrow on `ok` before reading `value`. A `deny` or `redirect` from the inner procedure surfaces as `{ ok: false, outcome }` rather than throwing into the outer handler, so the caller decides whether to propagate or handle it:

```ts
const result = await ctx.call(anotherLoader, { location });
if (result.ok) {
  // result.value: T (the authored type, not Serialize<T>)
  return { combined: result.value };
} else {
  // propagate any deny or redirect from the inner loader
  throw result.outcome;
}
```

Actions also receive `ctx.call`. Use it to delegate to a shared action from within another action:

```ts
// src/pages/orders.server.ts
import { defineAction } from 'hono-preact';
import { serverActions as notifyActions } from './notifications.server.js';

export const serverActions = {
  createOrder: defineAction(async (ctx, payload: { items: string[] }) => {
    const order = await db.orders.create(payload);
    const notifyResult = await ctx.call(notifyActions.sendConfirmation, {
      orderId: order.id,
    });
    if (!notifyResult.ok) throw notifyResult.outcome;
    return { orderId: order.id };
  }),
};
```

## Testing with `createCaller(c)`

Outside a running request (in unit or integration tests), use `createCaller` to build a caller bound to a Hono `Context`:

```ts
import type { Context } from 'hono';
import { createCaller } from 'hono-preact';
import { serverLoaders } from './movie.server.js';

it('returns the movie', async () => {
  // The framework does not mint a synthetic Context; capture a real one from a
  // one-off middleware wrapped around a test request.
  let c!: Context;
  app.use('*', async (ctx, next) => {
    c = ctx;
    await next();
  });
  await app.request(new Request('https://app.test/movies/42'));
  const caller = createCaller(c);

  const result = await caller.call(serverLoaders.default, {
    location: { pathParams: { id: '42' } },
  });

  expect(result.ok).toBe(true);
  if (result.ok) {
    expect(result.value.movie.id).toBe(42);
  }
});
```

`createCaller(c)` reuses an already-open request scope if one exists, and otherwise opens a fresh scope bound to `c`. In a test there is normally no active scope, so it runs standalone; inside a live handler `ctx.call` goes through the same mechanism and reuses the request's active scope automatically.

## Streaming loaders and actions

Streaming refs are first-class through the same `call` surface. Calling a streaming loader runs its middleware and schema coercion up front, then resolves to the loader's async generator; iterate it to run the loader body. Pass `signal` to end the stream from the caller's side:

```ts
import { createCaller } from 'hono-preact';
import { serverLoaders } from './projects-shell.server.js';

it('streams activity events', async () => {
  const ctrl = new AbortController();
  const r = await createCaller(c).call(serverLoaders.activity, {
    signal: ctrl.signal,
  });
  expect(r.ok).toBe(true);
  if (r.ok) {
    const events = [];
    for await (const e of r.value) {
      events.push(e);
      if (events.length === 3) break;
    }
    ctrl.abort();
  }
});
```

A middleware `deny` or `redirect` still surfaces as `{ ok: false, outcome }` before the generator is produced. An error thrown mid-stream propagates from the generator itself (a rejected `next()`), matching the HTTP path where the SSE stream terminates.

A streaming action resolves to `AsyncGenerator<TChunk, TResult>`: iterate for chunks; the final `next()`'s `value` (when `done` is `true`) is the action's return value.

## How it works

- **Runs the procedure's own `use` middleware.** The called procedure's per-unit `use` array is applied: auth guards, rate limits, and any observers declared on `defineLoader` or `defineAction`. The app-level chain and the page (route) middleware are not run for the call: the app chain already fired for the outer request, and the callee's own route-level middleware is bypassed entirely. So a guard placed only on a route node does not protect a procedure reached through `ctx.call` from a different route. Put any guard that must protect a procedure regardless of how it is entered on that procedure's own `defineLoader` / `defineAction({ use })`, not only on its route.
- **Reuses the live request scope.** Inside a live handler, `ctx.call` inherits the outer request's async-local storage context, so the Hono `Context`, session state, and middleware side-effects are shared. `createCaller(c)` used outside a handler opens a fresh scope per call.
- **Returns the authored type, not the wire shape.** No JSON round-trip occurs. The return type of `ctx.call(loader)` is `T` (the loader's declared return), not `Serialize<T>`. A `Date` field stays a `Date`.
- **Does not share the loader result cache.** The loader result cache is populated on the SSR page-render path. `ctx.call` invokes the loader function directly, so the result is always freshly computed. Two calls to the same loader produce two executions.
- **Validates inputs.** If the called loader has a `searchSchema` or `paramsSchema`, or the called action has an `input` schema, the caller validates the supplied location or payload before invoking the function. A validation failure surfaces as `{ ok: false, outcome }`, not a raw throw.
- **Unexpected errors reject the promise.** `ctx.call` resolves a `redirect`, `deny`, or validation failure to `{ ok: false, outcome }`, but an unexpected thrown error (a bug or exception inside the callee) propagates as a rejected promise. Wrap the call in `try/catch` if you need to contain those.
- **Does not apply the callee's `timeoutMs`.** A loader's or action's `timeoutMs` is a deadline the HTTP handler enforces at the request entrypoint; `ctx.call` runs the procedure in-process under the _outer_ request's `signal`, so the callee's own `timeoutMs` is not applied here. If an in-process call needs its own deadline, race the returned promise against one yourself.

## Limitations

- **No synthetic context minting.** `createCaller(c)` accepts a `Context` you supply. Obtain one from `app.request(new Request(...))` or your test helper. The framework does not mint a synthetic context.

## API reference

### `ctx.call(loader, opts?)`

| Argument        | Type                                          | Description                                                                                                             |
| --------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `loader`        | `LoaderRef<T, false>` \| `LoaderRef<T, true>` | The loader to call. A single-value loader resolves to its value; a streaming loader resolves to its async generator.    |
| `opts.location` | `CallLoaderLocation` (optional)               | Path, path params, and search params for the loader's location. Defaults to the current request path with empty params. |
| `opts.signal`   | `AbortSignal` (optional, streaming loaders)   | Composed with the request's signal and threaded to the loader as `ctx.signal`; aborting it ends the stream.             |

Returns `Promise<CallResult<T>>` for a single-value loader, `Promise<CallResult<AsyncGenerator<T, void, unknown>>>` for a streaming loader.

### `ctx.call(action, payload)`

| Argument  | Type                                   | Description                                                                                                           |
| --------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `action`  | `ActionRef<TPayload, TResult, TChunk>` | The action to call. A single-value action resolves to its result; a streaming action resolves to its async generator. |
| `payload` | `TPayload`                             | The action payload. Validated against the action's `input` schema when one is present.                                |

Returns `Promise<CallResult<TResult>>` for a single-value action, `Promise<CallResult<AsyncGenerator<TChunk, TResult, unknown>>>` for a streaming action (an async generator handler with a chunk type).

### `createCaller(c)`

```ts
import { createCaller } from 'hono-preact';

const caller = createCaller(c: Context): ServerCaller;
```

Returns a `ServerCaller` with a `call` method that accepts the same arguments as `ctx.call`. Each call reuses the active request scope if one is already open, otherwise it opens a fresh scope bound to `c`. Use in tests and any context outside a live request handler.

### `CallResult<T>`

```ts
type CallResult<T> = { ok: true; value: T } | { ok: false; outcome: Outcome };
```

Narrow on `ok` to access `value` or inspect `outcome`. The `outcome` type is `Outcome` (one of `redirect | deny | timeout | render`). Re-throw it to propagate to the outer handler, or inspect `outcome.__outcome` to handle specific cases.

### `CallLoaderLocation`

```ts
type CallLoaderLocation = {
  path?: string;
  pathParams?: Record<string, string>;
  searchParams?: Record<string, string>;
};
```

Optional location shape for `ctx.call(loader, { location })`. All fields are optional; omitted fields default to the current request path and empty params.

## See also

- [Server Loaders](/docs/loaders): defining loaders and composing multiple loaders per route.
- [Server Actions](/docs/actions): defining and calling actions.
- [Middleware](/docs/middleware): the per-unit and app-level middleware model.


---

> Source: https://framework.sbesh.com/docs/view-transitions

# View Transitions

The framework wraps every same-document route change in `document.startViewTransition` automatically. You don't opt in. A route change is a path or query change; hash-only URL changes (in-page anchors) never animate. Style the default root transition with `::view-transition-old(root)` and `::view-transition-new(root)`, and respect `prefers-reduced-motion`.

On top of that, three primitives let you scale view transitions across many elements, hook into the navigation lifecycle, and target CSS by direction.

## Named elements

Use `<ViewTransitionName>` to give an element a stable identity that participates in the transition. The component is polymorphic (Base UI `renderElement` style): pass a `render` prop to control which element actually mounts.

```tsx
import { ViewTransitionName } from 'hono-preact';

// list page
{
  posts.map((post) => (
    <ViewTransitionName
      key={post.id}
      name={`post-${post.id}`}
      groupClass="post-card"
      render={<article class="card" />}
    >
      <h2>{post.title}</h2>
    </ViewTransitionName>
  ));
}

// detail page
<ViewTransitionName name={`post-${post.id}`} render={<header />}>
  <h1>{post.title}</h1>
</ViewTransitionName>;
```

The matching `name` between list and detail tells the browser to animate the elements as a continuous group.

### Props

| Prop         | Type                                    | Default  | Description                                                        |
| ------------ | --------------------------------------- | -------- | ------------------------------------------------------------------ |
| `name`       | `string \| null \| undefined`           | required | The `view-transition-name` to apply; `null`/`undefined` clears it. |
| `groupClass` | `string \| string[]`                    | none     | Adds a `view-transition-class` for grouping.                       |
| `render`     | `VNode \| string \| ((props) => VNode)` | `<div>`  | The element to render: a tag string, an element, or a function.    |
| `children`   | `ComponentChildren`                     | none     | Content.                                                           |

For hand-written components, the `useViewTransitionName` hook returns a ref callback:

```tsx
import { useViewTransitionName } from 'hono-preact';

function PostCard({ post }: { post: Post }) {
  const vt = useViewTransitionName(`post-${post.id}`);
  return <article ref={vt}>{post.title}</article>;
}
```

`<ViewTransitionGroup class="post-card">` (or `useViewTransitionClass`) sets `view-transition-class` so you can target many elements at once via `::view-transition-group(*.post-card)` in CSS. The class only takes effect on elements that also carry a `view-transition-name`: a class with no named elements captures nothing. Pair it with a per-element name: `<ViewTransitionName name={postName} groupClass="post-card">` sets both on one wrapper.

## Lifecycle hooks

`useViewTransitionLifecycle` exposes four phases the framework controls:

```tsx
import { useViewTransitionLifecycle } from 'hono-preact';

useViewTransitionLifecycle({
  onBeforeTransition: (event) => {
    // Before the View Transition starts.
    // event.types.push('my-type') to add a type, event.skip() to bypass.
  },
  onBeforeSwap: (event) => {
    // After the framework has begun the transition. Last chance to mutate
    // the DOM before the new-frame snapshot is captured.
  },
  onAfterSwap: (event) => {
    // The new DOM is settled and the browser is ready to animate.
  },
  onAfterTransition: (event) => {
    // After transition.finished resolves (or rejects).
    // event.reason is 'skipped' | 'unsupported' | 'aborted' if the transition
    // didn't run.
  },
});
```

Each callback receives a `ViewTransitionEvent`:

| Member                         | Type                                                      | Description                                |
| ------------------------------ | --------------------------------------------------------- | ------------------------------------------ |
| `to`                           | `string`                                                  | Destination path.                          |
| `from`                         | `string \| undefined`                                     | Source path; `undefined` on initial load.  |
| `direction`                    | `'initial' \| 'push' \| 'replace' \| 'back' \| 'forward'` | Navigation direction.                      |
| `types`                        | `string[]`                                                | Mutable list of transition type names.     |
| `skip()`                       | `() => void`                                              | Skip this transition.                      |
| `set(key, value)` / `get(key)` | method                                                    | Per-event scratch shared across callbacks. |

The four callbacks (`onBeforeTransition`, `onBeforeSwap`, `onAfterSwap`, `onAfterTransition`) each have the signature `(event) => void | Promise<void>`.

A hash-only URL change is not a route change (see [Opting out](#opting-out-of-the-transition) below), so it never runs a transition and none of these four callbacks fire for it, including `afterSwap`. Effects that react to a URL fragment, scrolling to a heading, for example, should key on location (`useLocation().url` from `preact-iso`) rather than on a lifecycle callback, since a same-path fragment link is exactly the case where the lifecycle stays silent.

## Direction-driven CSS via types

The framework adds three types to every transition:

- `nav-initial` on the first navigation after hydrate, otherwise one of `nav-push`, `nav-replace`, `nav-back`, `nav-forward`.
- `nav-same-origin`.

Target them with `:active-view-transition-type(...)`:

```css
:active-view-transition-type(nav-back) ::view-transition-old(root) {
  animation: slide-right-out 0.3s ease;
}
:active-view-transition-type(nav-back) ::view-transition-new(root) {
  animation: slide-right-in 0.3s ease;
}
```

Add your own types with `useViewTransitionTypes`:

```tsx
import { useViewTransitionTypes } from 'hono-preact';

useViewTransitionTypes((nav) =>
  nav.from?.startsWith('/posts/') && nav.to === '/posts' ? ['back-to-list'] : []
);
```

For a rule that should apply regardless of what is mounted, for example a calm
transition whenever a navigation enters or leaves a whole section, use the
always-on `subscribeViewTransitionTypes`. A hook in a section layout only sees
navigations within the section: it is not subscribed yet when you navigate in, and
is torn down before you navigate out. A single subscriber registered at client
startup sees every navigation's `from` and `to`.

```ts
import { subscribeViewTransitionTypes } from 'hono-preact';

subscribeViewTransitionTypes((nav) => {
  const inDocs = (p?: string) => p === '/docs' || p?.startsWith('/docs/');
  return inDocs(nav.to) || inDocs(nav.from) ? ['docs'] : [];
});
```

It returns an unsubscribe and is a no-op on the server, so it is safe to register
as a module side effect.

## Opting out of the transition

The transition is on by default for every route change (a path or query
change). A hash-only URL change is not a route change: writing `#section` to
the URL, whether via `navigate('#section')`, a plain anchor click, or a raw
`history.pushState`, never animates and needs no opt-out. Three opt-outs
update the URL without animating (the render still commits):

- `navigate(href, { transition: false })` from `useNavigate`, for programmatic
  navigations (reflecting a tab, filter, or sort into the query string).
- `<NavLink href="..." transition={false}>`: the declarative form of the same.
- `skipNextNavTransition(target?)`: a one-shot escape hatch for code that
  drives a navigation outside `useNavigate` and `<NavLink>`. Call it
  immediately before the navigation. Pass the destination URL to key the skip
  to it: the skip applies only when the next navigation commits at that path
  and query, and expires without applying when the next navigation goes
  anywhere else. With no argument the skip applies to the next navigation
  whatever its destination.

  ```ts
  import { skipNextNavTransition } from 'hono-preact';

  skipNextNavTransition('/inbox?folder=archive');
  history.pushState(null, '', '/inbox?folder=archive'); // URL updates, no transition
  ```

Each opt-out applies to the next navigation only.

## See also

- [Optimistic UI](/docs/optimistic-ui): the `transition` option on `useOptimistic` and `useOptimisticAction` wraps mutations in a view transition.
- [Loading States](/docs/loading-states): coordinating loading indicators with transitions.


---

> Source: https://framework.sbesh.com/docs/middleware

# Middleware

Middleware is how you add auth gates, tracing, timing, and request logging to loaders, actions, and page renders without repeating that logic in each handler. Declare a `use` array on your app config, a route node, or an individual loader or action; the framework runs them in order and partitions server- vs client-bound members automatically.

## The three layers

Each layer attaches its `use` array through a different surface:

| Layer | Where you declare it                                           | What it wraps                                                                                                                                                                        |
| ----- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| App   | `defineApp({ use })` default-exported from `src/app-config.ts` | Every page render, every loader, every action.                                                                                                                                       |
| Page  | `use` on a route node in `src/routes.ts`                       | The matched node and its descendants: renders, plus route-bound loaders and actions (`serverRoute(r)`). A bare `defineLoader` / `defineAction` RPC is route-independent (see below). |
| Unit  | `defineLoader(fn, { use })` / `defineAction(fn, { use })`      | Just that one loader or action call.                                                                                                                                                 |

```ts
// apps/site/src/app-config.ts (optional file)
import { defineApp, defineServerMiddleware } from 'hono-preact';

const requestId = defineServerMiddleware(async (ctx, next) => {
  ctx.c.header('X-Request-Id', crypto.randomUUID());
  await next();
});

export default defineApp({ use: [requestId] });
```

```ts
// src/routes.ts
import { defineRoutes } from 'hono-preact';
import { requireSession } from './auth/session.js';

export default defineRoutes([
  { path: '/login', view: () => import('./pages/login.js') }, // public
  {
    path: '/admin',
    layout: () => import('./pages/admin/layout.js'),
    use: requireSession, // one declaration
    children: [
      {
        path: '',
        view: () => import('./pages/admin/index.js'),
        server: () => import('./pages/admin/index.server.js'),
      },
      {
        path: 'users',
        view: () => import('./pages/admin/users.js'),
        server: () => import('./pages/admin/users.server.js'),
      },
    ],
  },
]);
```

```ts
// src/pages/admin/index.server.ts
import { serverRoute } from 'hono-preact';
import { auditLog } from '../../audit.js';

const admin = serverRoute('/admin');

// requireSession is declared once on the /admin route node (routes.ts).
// Binding these units to that route makes their RPC paths inherit it, so no
// guard is repeated here.
export const serverLoaders = {
  default: admin.loader(async () => listAdminRows()),
};

export const serverActions = {
  promote: admin.action(async (ctx, payload) => promoteUser(payload.id), {
    use: [auditLog],
  }),
};
```

### Chain order

Outer-to-inner the chain is `appConfig.use → node use (ancestors outer-first) → unit-level use`. The dispatcher runs each `before` body in order, then `next()` enters the next ring, then each `after` body unwinds in reverse:

```
root:before
  page:before
    unit:before
      inner (loader / action body)
    unit:after
  page:after
root:after
```

A `throw` in any ring propagates up through the surrounding `after` blocks (so a `try { await next() } finally { ... }` middleware still runs its cleanup on failure).

### Nested routes compose down the tree

A `use` on a route node inherits down the tree: it applies to the node's own view (if any) and every descendant. It covers the render path for the whole subtree and the RPC path of any **route-bound** loader or action (`serverRoute(r).loader` / `serverRoute(r).action`). You declare the guard once on the ancestor; leaves under it are gated without repeating anything. A sibling route that is not a descendant of the guarded node stays ungated.

Bare units are the exception, and loaders and actions behave the same way. A route-independent `defineLoader` or `defineAction` runs its SSR render inside the route chain, but its client-driven RPC (`POST /__loaders` for a loader, the action POST for an action) runs only the app-level `use` and the unit's own unit-level `use`, never the route node's page-layer `use`. So a bare unit colocated under a guarded route is gated on first paint but not on a direct RPC hit. A bare unit is route-independent by design: the client chooses where to POST, so the route it posts from is not a security boundary. Bind it with `serverRoute(r).loader` / `serverRoute(r).action` (as in the example above), or give it a unit-level `use`, to gate it everywhere.

A layout's own server module binds either scope of its node. `serverRoute('/admin/*')` is the subtree scope: the chain every descendant inherits (the layout's inherited and own `use`), the usual spelling for shell data. `serverRoute('/admin')` is the page scope: the deepest composed chain for the pattern string, which adds the index child's own `use` when the index child declares one (see [Binding a layout's loaders](/docs/loaders#binding-a-layouts-loaders)).

A grouping node that declares `use` and `children` but no `view` or `layout` has no page pattern of its own, but its subtree does: a server module shared across the subtree binds `serverRoute('/x/*')` and runs the composed chain the node passes to every descendant. Under a tree-form registration (`tree: typeof routeTree`, see [Typed route params](/docs/layouts#typed-route-params)) the `'/x/*'` spelling is typed like every other children-bearing node's subtree; a paths-only registration types subtree patterns heuristically from the path union, which cannot see a grouping node.

```ts
// src/routes.ts
import { defineRoutes } from 'hono-preact';
import { adminGate } from './auth/admin.js';
import { auditLog } from './audit.js';

export default defineRoutes([
  {
    path: '/admin',
    use: [adminGate], // guards everything below
    children: [
      {
        path: 'users/:id',
        view: () => import('./admin/users.js'),
        server: () => import('./admin/users.server.js'), // no redundant guard needed
      },
    ],
  },
  { path: '/public', view: () => import('./pages/public.js') }, // not a descendant: ungated
]);
```

A page request (SSR GET) to `/admin/users/42` runs:

```
root:before                     // appConfig.use
  admin:before                  // /admin node use: adminGate
    audit:before                // /admin/users/:id loader unit use: auditLog
      unit:before               // defineLoader({ use })
        inner
      unit:after
    audit:after
  admin:after
root:after
```

When multiple ancestors each carry `use`, they compose outer-to-inner in tree order (outermost ancestor first, then each child toward the matched leaf, then the leaf's own `use`).

## Server vs client middleware

`defineServerMiddleware` runs on the server side: during SSR, during the page-tsx pre-render, and during loader/action RPC calls. It receives the Hono `Context`, so cookies, headers, and signed-cookie helpers work as you'd expect.

The context's shape follows the scope: page and loader scope carry a `location`
(path and search params), and route-bound action scope does too. A per-resource
gate declared on a route node that reads `ctx.location.pathParams` therefore
applies to renders, loaders, and route-bound actions (`serverRoute(r).action`)
alike. Two cases carry no location: a bare `defineAction` (route-independent, so
bind it with `serverRoute(r)` or give it a unit-level `use` to gate it), and the
in-process `call()` path (server-to-server, which runs no route-node middleware).

`defineClientMiddleware` runs only on the browser side, when the user navigates intra-app. It receives a minimal context with `scope: 'page'` and `location`; there's no Hono context because there's no server request.

During a client navigation between routes that have page-layer middleware (`use`), the previous route stays visible while the next route's middleware chain resolves. The navigation commits and the new route mounts only after the chain completes, so the user never sees a blank interval between routes. This matches the behavior for plain lazy routes, where the router holds the outgoing content visible until the incoming route is ready. For apps that mount the page-middleware host directly (via `hono-preact/internal`), a `Router` ancestor is required as the suspense boundary; the `Routes` component in the generated client entry provides this automatically.

Both factories produce a brand object with a `runs` tag. The framework's Vite plugin strips the wrong-env body at build time: a `defineServerMiddleware(...)` call in the client bundle is rewritten to a no-op brand object, and vice versa. Server-only modules pulled in by a server middleware body tree-shake out of the client bundle automatically.

```ts
import {
  defineServerMiddleware,
  defineClientMiddleware,
  redirect,
} from 'hono-preact';
import { currentUser } from './session.js';

// Server check (SSR + RPC): validates the signed cookie via Hono helpers.
const requireSessionServer = defineServerMiddleware(async (ctx, next) => {
  const user = await currentUser(ctx.c);
  if (!user) throw redirect('/login');
  await next();
});

// Client check (intra-app navigation): reads a localStorage hint set by
// the login view. On full reload the server middleware reconciles drift.
const requireSessionClient = defineClientMiddleware(async (_ctx, next) => {
  if (typeof window === 'undefined') {
    await next();
    return;
  }
  if (!window.localStorage.getItem('app:authed')) {
    throw redirect('/login');
  }
  await next();
});

export const requireSession = [requireSessionServer, requireSessionClient];
```

## Outcomes

A middleware short-circuits by throwing one of three outcomes:

| Outcome                 | Where it makes sense | Result                                                                                                         |
| ----------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------- |
| `redirect(to)`          | any scope            | HTTP redirect on SSR; `route(to)` on the client; `{ __outcome: 'redirect', to }` envelope on loader/action RPC |
| `deny(status, message)` | any scope            | HTTP response at `status` with `message`; on RPC paths the client surfaces `message` as the thrown `Error`     |
| `render(Component)`     | page scope only      | Renders `<Component />` in place of the matched page                                                           |

```ts
import { redirect, deny, render } from 'hono-preact/page';

const adminOnly = defineServerMiddleware<'page'>(async (ctx, next) => {
  const user = await currentUser(ctx.c);
  if (!user) throw redirect('/login');
  if (!user.isAdmin) throw render(NotAuthorizedPage);
  await next();
});

const rateLimit = defineServerMiddleware<'action'>(async (ctx, next) => {
  if (await isRateLimited(ctx.c)) throw deny(429, 'Slow down');
  await next();
});
```

`render` is page-scope only and lives at the `hono-preact/page` subpath, so loader/action code can't accidentally import it and trigger a `render outcome is page-scope only` 500 at runtime.

## Stream observers

Streaming loaders and actions accept `defineStreamObserver` entries in the same `use` array. Observers are passive: they see lifecycle events but never short-circuit. The dispatcher fires `onStart` before the first chunk, `onChunk` for each chunk in order, `onEnd` once the stream completes, `onError` if it throws, and `onAbort` if the request signal aborts.

Failure isolation: if one observer's callback throws, the framework logs it and continues firing the remaining observers and the stream itself. Observers cannot break the stream.

### Callbacks

| Callback  | Signature                           | Description                            |
| --------- | ----------------------------------- | -------------------------------------- |
| `onStart` | `(ctx) => void`                     | The stream opened.                     |
| `onChunk` | `(ctx, chunk, index) => void`       | Each chunk, with its zero-based index. |
| `onEnd`   | `(ctx, { chunks, result }) => void` | The stream completed.                  |
| `onError` | `(ctx, err, { chunks }) => void`    | The stream threw.                      |
| `onAbort` | `(ctx, { chunks }) => void`         | The client navigated away or aborted.  |

```ts
import { defineStreamObserver, defineLoader } from 'hono-preact';

const trace = defineStreamObserver({
  onStart: (ctx) => console.log('stream:start', ctx.loader),
  onChunk: (_ctx, chunk, i) => console.log(`chunk[${i}]`, chunk),
  onEnd: (_ctx, { chunks, result }) =>
    console.log('stream:end', { chunks, result }),
  onError: (_ctx, err, { chunks }) =>
    console.error('stream:error', err, { chunks }),
  onAbort: (_ctx, { chunks }) => console.log('aborted', { chunks }),
});

export const serverLoaders = {
  default: defineLoader(
    async function* () {
      for (const row of cursorRows()) yield row;
    },
    { use: [trace] }
  ),
};
```

## The `use` array

`use` is a flat array. The dispatcher walks it once and partitions into middleware (server + client) and stream observers, then runs each group with the right strategy. You can mix everything in one list:

```ts
use: [requireSessionServer, requireSessionClient, rateLimit, trace];
```

Ordering matters for middleware: outer-to-inner is `appConfig.use` first, then node `use` (ancestors outer-first), then per-unit `use`, in the order each array lists them. Observers have no relative ordering: they all fire on every chunk in registration order, and one observer's slowness doesn't gate the others.

## Worked examples

### Auth gate with server + client legs

```ts
// auth/session.ts
import {
  defineServerMiddleware,
  defineClientMiddleware,
  redirect,
} from 'hono-preact';
import { currentUser } from './session.js';

const server = defineServerMiddleware(async (ctx, next) => {
  if (!(await currentUser(ctx.c))) throw redirect('/login');
  await next();
});

const client = defineClientMiddleware(async (_ctx, next) => {
  if (
    typeof window !== 'undefined' &&
    !window.localStorage.getItem('app:authed')
  ) {
    throw redirect('/login');
  }
  await next();
});

export const requireSession = [server, client];
```

### Timing middleware that logs duration

```ts
import { defineServerMiddleware } from 'hono-preact';

export const timing = defineServerMiddleware(async (ctx, next) => {
  const t0 = performance.now();
  try {
    await next();
  } finally {
    const ms = (performance.now() - t0).toFixed(1);
    console.log(`[${ctx.scope}] ${ctx.c.req.path} ${ms}ms`);
  }
});
```

### Tracing middleware around a span

```ts
import { defineServerMiddleware } from 'hono-preact';
import { tracer } from './otel.js';

export const traced = defineServerMiddleware(async (ctx, next) => {
  await tracer.startActiveSpan(`hp:${ctx.scope}`, async (span) => {
    try {
      await next();
    } catch (err) {
      span.recordException(err);
      throw err;
    } finally {
      span.end();
    }
  });
});
```

### Per-chunk audit observer

```ts
import { defineStreamObserver } from 'hono-preact';

export const auditChunks = defineStreamObserver({
  onChunk: (ctx, chunk, i) => {
    auditLog.push({
      module: ctx.module,
      loader: ctx.loader,
      index: i,
      bytes: JSON.stringify(chunk).length,
    });
  },
});
```

### Page render replacement

```ts
// hono-preact/page is the page-scope-only subpath where `render` lives.
import { defineServerMiddleware, redirect } from 'hono-preact';
import { render } from 'hono-preact/page';
import { LoginModal } from './LoginModal.js';
import { currentUser } from './session.js';

export const showLoginModal = defineServerMiddleware<'page'>(
  async (ctx, next) => {
    if (!(await currentUser(ctx.c))) {
      // Render an alternative component in place of the matched page.
      // The page tree is replaced; the user keeps the current URL.
      throw render(LoginModal);
    }
    await next();
  }
);
```


---

> Source: https://framework.sbesh.com/docs/csrf

# CSRF Protection

This page is a recipe for CSRF protection. You need it when your app uses cookie
authentication and accepts `multipart/form-data` actions; the JSON path is
already protected by browser CORS preflight. The recipe is a single server-side
Origin check in `api.ts`, with no client changes required.

## When you need it

If your app:

- authenticates users via a cookie (signed session, JWT in `Set-Cookie`, etc.), and
- uses `SameSite=Lax` or `SameSite=None` on that cookie, and
- accepts file uploads or any other `multipart/form-data` action

then a malicious page on another origin can submit a top-level `<form action="https://yoursite/your-page" enctype="multipart/form-data">` to your page URL with the victim's cookie attached, and your action runs as the victim. That's CSRF.

The JSON path (which `useAction` uses for any payload that does not contain a `File`) is already protected by browsers: `Content-Type: application/json` is not a "safelisted" request header, so browsers force a CORS preflight that a cross-origin attacker page cannot satisfy without your server's explicit allow. (This is a browser-enforced property, not a server-enforced one, but every current browser enforces it.) The multipart path is the gap, because `multipart/form-data` is safelisted and can be sent cross-origin from a plain `<form>` without preflight.

You do not need this recipe if any of:

- Your auth cookie is `SameSite=Strict`
- Your app does not use cookie auth at all (bearer tokens in `Authorization`)
- Your page URLs are not publicly accessible
- You never accept multipart payloads (convert files to base64 in JSON, or upload via a separate direct route)

## The recipe: server-side Origin check

Add a Hono middleware that rejects cross-origin POSTs. Modern browsers always send `Origin` on cross-origin POSTs, and an attacker page on another origin cannot forge it.

This runs entirely on the server. No client changes, no `fetch` wrapper, and it covers both `useAction` requests and native form posts.

```ts
// src/api.ts
import { Hono } from 'hono';

const ALLOWED_ORIGIN = 'https://yoursite.example';

const app = new Hono();

app.use('*', async (c, next) => {
  if (c.req.method !== 'POST') return next();
  const origin = c.req.header('Origin');
  if (origin !== ALLOWED_ORIGIN) {
    return c.json({ error: 'Cross-origin POST rejected' }, 403);
  }
  return next();
});

export default app;
```

This works because the framework mounts your `api.ts` app **ahead of** its own handlers and the page renderer. Middleware you register in `api.ts` therefore runs before the framework's loader RPC and page action handlers: `app.use('*', …)` is effectively app-wide. Middleware via `app.use(…)` is always safe: it calls `next()` and composes ahead of the framework handlers rather than replacing them. What you must not do is register a catch-all _route_ (`app.get('*', …)`, `app.all('/*', …)`, or `app.on(…)` with `'*'` as the path) in `api.ts`: those shadow the framework's handlers, so the build rejects them.

### Configure the allowed origin

Hard-code the production origin or read it from an environment variable. **Do not derive it from the request** (e.g. `new URL(c.req.url).origin`); behind a CDN or reverse proxy, the request URL the worker sees may use a different scheme or host than the browser sent, and the comparison will silently mis-match or, worse, silently allow.

On Cloudflare Workers, configure `ALLOWED_ORIGIN` as an environment variable in `wrangler.toml` and read it from `c.env`.

If you need to allow multiple origins (e.g. a staging and production host), check against a small allowlist of exact strings. Do not pattern-match.

### Verifying it

1. From your own site, submit an action; it should succeed.
2. From a browser tab on a different origin (e.g. `http://localhost:8080` running `python3 -m http.server`), POST a `<form enctype="multipart/form-data" action="https://yoursite.example/your-page">` with the victim's cookies attached. You should get a 403.

## What this does NOT protect against

- **Subdomain takeovers.** If `a.example.com` is compromised and your cookie is `Domain=example.com`, the attacker is same-origin to you. Use `__Host-` cookies (no `Domain` attribute) to scope auth to a single host.
- **Stored XSS.** If an attacker can inject script into your origin, none of this matters; they are you. Set Content Security Policy headers.
- **Logged-out cross-origin reads.** This recipe is about mutations. GETs to your loaders are public surface; do not put authorization-only data behind GET-with-cookie unless you also know `SameSite=Strict` is honored.

For deployment-level controls (CSP, HSTS, frame-ancestors, etc.) see your runtime's documentation. Cloudflare Workers, for example, lets you set response headers from your worker code or via the dashboard.


---

> Source: https://framework.sbesh.com/docs/cli

# CLI

One command gets you from nothing to a running hono-preact app:
`create-hono-preact` scaffolds the project, installs dependencies, and
initializes a git repo. It also has an `add-agents` subcommand for dropping
framework guidance into a project you set up manually.

## Create a new app

```bash
npm create hono-preact
```

Run with no arguments and the wizard walks you through it: project directory,
adapter (Cloudflare Workers or a Node server), whether to add `hono-preact-ui`
components, and whether to install dependencies and initialize git. Because the
common path takes no flags, there is nothing for npm to mis-parse.

The CLI requires Node `^22.18.0 || >=24.11.0` (the range hono-preact itself
supports) and exits with a clear message on an older Node before anything is
scaffolded. `--help`, `--version`, and `add-agents` work on any Node.

You can pass a directory and skip prompts with flags for scripting or CI:

```bash
# pnpm/yarn/bun forward flags directly:
pnpm create hono-preact my-app --adapter node --ui --yes
# npm needs a `--` separator before tool flags:
npm create hono-preact my-app -- --adapter node --ui --yes
```

### Options

| Flag                           | Description                                              |
| ------------------------------ | -------------------------------------------------------- |
| `--adapter <cloudflare\|node>` | Choose the deployment target (prompted otherwise).       |
| `--ui`, `--no-ui`              | Include or exclude `hono-preact-ui` components.          |
| `--no-install`                 | Skip the dependency install step.                        |
| `--no-git`                     | Skip `git init`.                                         |
| `-y`, `--yes`                  | Accept defaults for anything not specified (no prompts). |
| `--skip-hints`                 | Suppress the "Next steps" note.                          |
| `--version`, `-v`              | Print the CLI version.                                   |
| `--help`, `-h`                 | Print usage.                                             |

> In a non-interactive shell (CI, piped input), the CLI never prompts: it uses
> your flags plus defaults (adapter `cloudflare`, UI off, install on, git on),
> and a missing directory is an error. With `npm`, put tool flags after `--`.

## Add agent guidance to an existing app

If you added hono-preact to a project you did not scaffold (for example with
`pnpm add hono-preact`), drop in the guidance an AI coding agent reads:

```bash
npx create-hono-preact add-agents
```

It writes `AGENTS.md` (framework conventions for any AI coding agent), a one-line `CLAUDE.md` pointer, an `agents/skills/` directory of step-by-step recipes (add a page, a loader, an action, a guard), and `agents/llms-full.txt` (the full documentation bundled for offline reference). Existing files are left untouched unless you pass `--force`.

| Flag      | Default | Description                                                                                 |
| --------- | ------- | ------------------------------------------------------------------------------------------- |
| `--force` | off     | Overwrite existing files (AGENTS.md, CLAUDE.md, agents/skills/\*.md, agents/llms-full.txt). |

See [Quick Start](./quick-start) for the full walkthrough.


---

> Source: https://framework.sbesh.com/docs/vite-config

# Vite Configuration

The `hono-preact/vite` subpath exports a `honoPreact()` plugin that configures Vite for the framework's two-pass build and dev server. Your `vite.config.ts` only needs to wire in the plugins that are specific to your application.

## Minimal setup

```ts
import { honoPreact } from 'hono-preact/vite';
import { cloudflareAdapter } from 'hono-preact/adapter-cloudflare';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [honoPreact({ adapter: cloudflareAdapter() })],
});
```

`adapter` is required; `honoPreact()` throws a clear error if it is omitted. The plugin auto-includes `@preact/preset-vite` internally, so you don't import it yourself. The framework ships two adapters today: `cloudflareAdapter()` for Cloudflare Workers, imported from `hono-preact/adapter-cloudflare`, and `nodeAdapter()` for Node.js (via `@hono/node-server`), imported from `hono-preact/adapter-node`. Each adapter supplies its own Vite plugins and entry wrapper, so the framework core stays target-agnostic.

## honoPreact(options)

| Option        | Type                                                         | Default                        | Description                                                                                                                                |
| ------------- | ------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `adapter`     | `HonoPreactAdapter`                                          | required                       | Deployment target, e.g. `cloudflareAdapter()` or `nodeAdapter()`.                                                                          |
| `layout`      | `string`                                                     | `'src/Layout.tsx'`             | Root layout component path.                                                                                                                |
| `routes`      | `string`                                                     | `'src/routes.ts'`              | Route table path.                                                                                                                          |
| `api`         | `string`                                                     | `'src/api.ts'`                 | Optional custom routes; loaded only if the file exists.                                                                                    |
| `appConfig`   | `string`                                                     | `'src/app-config.ts'`          | Optional app config; loaded only if the file exists.                                                                                       |
| `serverDir`   | `string`                                                     | `'src/server'`                 | Registry folder for route-less server modules; globbed if it exists. See [The `src/server` registry](/docs/routes#the-srcserver-registry). |
| `clientEntry` | `string`                                                     | `'virtual:hono-preact/client'` | Client entry module id.                                                                                                                    |
| `css`         | `{ global?: string; autoSplit?: boolean; minSize?: number }` | `undefined`                    | Framework-owned global stylesheet delivery and build-time auto-split tuning. See [Styling](/docs/styling) for the full pipeline.           |

## What the plugin handles

`honoPreact()` configures everything the framework requires:

| Concern              | What it sets                                                                                                                                                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Preact deduplication | `resolve.dedupe` for `preact`, `preact/hooks`, `preact-iso`                                                                                                                                                                    |
| Build target         | `build.target: 'esnext'`, `build.assetsDir: 'static'`                                                                                                                                                                          |
| Client build output  | `static/client.js` entry, hashed chunk and asset filenames in the `client` environment                                                                                                                                         |
| Deployment target    | Delegated to the configured adapter (Cloudflare Workers, Node.js, etc.), which supplies its own Vite plugins and entry wrapper                                                                                                 |
| Server-only imports  | `serverOnlyPlugin` stubs static `*.server.*` imports and dynamic `() => import('./*.server.*')` calls in the client bundle (see [Project Structure](/docs/structure) for the `.server.*` file convention)                      |
| Loader validation    | `serverLoaderValidationPlugin` enforces `.server.*` export conventions                                                                                                                                                         |
| Module identity      | `moduleKeyPlugin` injects a path-derived `__moduleKey` into each `.server.*` file for RPC routing                                                                                                                              |
| Guard strip          | `guardStripPlugin` rewrites opposite-environment middleware bodies to no-ops so server-only code tree-shakes out of the client bundle                                                                                          |
| Browser shim         | `clientShimPlugin` prepends a `globalThis.process ??= ...` shim to the client entry so libraries reading `process.env.NODE_ENV` at module-eval time do not throw                                                               |
| CSS pipeline         | `build.cssMinify: 'lightningcss'` and Baseline browser targets (`css.lightningcss.targets`), unless you set `cssMinify` or `css.lightningcss` yourself, in which case your config wins outright. See [Styling](/docs/styling). |

## Peer dependencies

Peer deps depend on the adapter you pick. Install the ones that match your deployment target.

```bash
npm install -D @cloudflare/vite-plugin wrangler
```

```bash
npm install @hono/node-server
```

Add `@hono/node-ws` to the Node.js install if you want WebSocket support.

## Adding MDX

MDX is a user-space choice and not included in the plugin. Add it alongside `honoPreact()`:

```ts
import { honoPreact } from 'hono-preact/vite';
import { cloudflareAdapter } from 'hono-preact/adapter-cloudflare';
import mdx from '@mdx-js/rollup';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    honoPreact({ adapter: cloudflareAdapter() }),
    Object.assign(mdx({ jsxImportSource: 'preact' }), { enforce: 'pre' }),
  ],
});
```

The `enforce: 'pre'` placement ensures MDX files are transformed to JSX before other plugins see them.

## Path aliases

`honoPreact()` does not add path aliases; those belong in your config. A common setup:

```ts
import { resolve } from 'node:path';

export default defineConfig({
  resolve: {
    alias: [{ find: '@', replacement: resolve(__dirname, './src') }],
  },
  plugins: [honoPreact({ adapter: cloudflareAdapter() })],
});
```

## Custom client entry path

The plugin defaults to the framework-generated virtual module `virtual:hono-preact/client`, which hydrates `<Routes>` under `<LocationProvider>` for you. Override it only when you need a hand-written entry:

```ts
honoPreact({
  adapter: cloudflareAdapter(),
  clientEntry: 'src/main.tsx',
});
```

`clientEntry` is the single source of truth for both the rollup `input` and the `clientShimPlugin` transform target, so you only set it in one place.

A custom entry takes over the virtual entry's responsibilities. Before hydrating, call `bootClient()` (exported from `hono-preact`). It installs the client runtime services the framework relies on: the history shim (back/forward direction tracking), the navigation transition scheduler (view transitions on route changes), and the stream registry (live-loader streams). Skipping the call silently disables all three, so the dev server warns when the configured `clientEntry` module never references `bootClient`.

```tsx
// src/main.tsx
import { hydrate } from 'preact';
import { LocationProvider } from 'preact-iso';
import { Routes, bootClient } from 'hono-preact';
import routes from './routes.js';

bootClient();

hydrate(
  <LocationProvider>
    <Routes routes={routes} />
  </LocationProvider>,
  document.getElementById('app')
);
```


---

> Source: https://framework.sbesh.com/docs/structure

# Project Structure

A hono-preact app is organized around a few key files: a route table, a layout shell, and paired view and server modules. This page maps the directory layout and explains the role of each entry point.

```
hono-preact/                    # monorepo root
├── apps/
│   └── site/                    # the deployed application
│       ├── src/
│       │   ├── api.ts          # Optional: custom Hono routes mounted before SSR
│       │   ├── Layout.tsx      # HTML shell with <Head>, <ClientScript />
│       │   ├── routes.ts       # The route table (defineRoutes manifest)
│       │   ├── pages/          # View components, paired .server.ts files, MDX content
│       │   ├── components/     # Shared UI components (incl. MdxArticle for MDX)
│       │   └── styles/         # Global CSS
│       ├── vite.config.ts      # Two build configs: client bundle + Worker bundle
│       └── wrangler.jsonc      # Cloudflare Workers deployment config
└── packages/
    ├── iso/                    # hono-preact: routing primitives + isomorphic data
    ├── server/                 # hono-preact/server: render + handler wiring
    └── vite/                   # hono-preact/vite: framework Vite plugins
```

## Key files

### `apps/site/src/routes.ts`

The single source of truth for URL routing. Exports a `defineRoutes(...)` manifest naming every page in the app, paired with an optional `server` import for any route that needs a loader or actions. See [The Route Table](/docs/routes).

```ts
import { defineRoutes } from 'hono-preact';

export default defineRoutes([
  { path: '/', view: () => import('./pages/home.js') },
  { path: '/movies', layout: () => import('./pages/movies-layout.js'), children: [...] },
  { path: '/demo/projects/:projectId', view: () => import('./pages/project.js') },
  { path: '*', view: () => import('./pages/not-found.js') },
]);
```

### Client and server entries (generated)

The framework owns both entries as virtual modules. The browser entry (`virtual:hono-preact/client`) hydrates the app and the server entry (`virtual:hono-preact/server`) wires the Hono app from your `routes.ts` and `Layout.tsx`, including the loader RPC handler, the page action handler, the WebSocket upgrade endpoint, and the catch-all SSR handler. `<Routes>`, `LocationProvider`, and `onRouteChange` are all wrapped inside the generated entries; no `iso.tsx` or `client.tsx` lives in user code. To add custom REST routes, author an optional `src/api.ts` that exports a Hono app (or a function returning one); the generated entry mounts it before the SSR catch-all. Creating or deleting `src/api.ts` while the dev server is running restarts it automatically, so the change takes effect without a manual restart.

### `apps/site/src/Layout.tsx`

Renders the HTML shell. Uses `<Head>` and `<ClientScript />` from `hono-preact` to declare the document title/meta and inject the client bundle script tag. Default-exports a component the framework's generated server entry renders for the catch-all route; the framework emits the `<!doctype html>` prefix and post-processes hoofd-collected head tags into the user's `</head>`. View Transitions fire automatically on every client-side route change in browsers that support `document.startViewTransition`; style them via `::view-transition-old(root)` / `::view-transition-new(root)` CSS.

### `apps/site/src/pages/`

View components and their paired server modules. Files in this folder are referenced by entries in `routes.ts`; nothing is auto-discovered. Naming and folder structure are the user's choice (the demo uses kebab-case `movies-list.tsx` + `movies-list.server.ts` siblings).

`layout.server.ts` is also valid alongside any `layout.tsx`. A loader declared there is auto-scoped to the layout's matched location, not the deepest active child route. The auto-scoping is structural: the framework infers scope from which route entry owns the `.server.*` file, with no opt-in flag required.

MDX content (`pages/docs/**/*.mdx`) is mounted by `contentRoutes(import.meta.glob('./pages/docs/**/*.mdx'))` in `routes.ts`, which turns each file into a route node under the `/docs` layout group.

### `hono-preact` (workspace package)

Isomorphic primitives shared between server and client (`packages/iso/`):

- **Routing**: `defineRoutes`, `Routes`, `RouteDef`, `LayoutProps`, `ViewProps`, `RoutesManifest`, `FlatRoute`, `ServerRoute`. The route-table primitive and runtime mounter.
- **Page bindings**: `definePage(Component, { errorFallback, Wrapper })` factory plus `<Page>`, `WrapperProps`. Used by views that need a Wrapper. Page-layer middleware is declared via `use` on the route node in `routes.ts`; entries are built with `defineServerMiddleware`, `defineClientMiddleware`, and `defineStreamObserver`. Loader consumption (`.View()`) lives inside the page's JSX tree; loading UI is rendered by switching on the `LoaderState` status inside `.View()`.
- **Loaders**: `defineLoader`, `LoaderRef`, `useReload`. (`LoaderRef` carries `useData()`, `useError()`, `invalidate()`, `cache`, `.View()`, and `.Boundary`.)
- **Actions**: `defineAction`, `useAction`, `useOptimistic`, `useOptimisticAction`, `<Form>`.
- **Caching**: `createCache` (advanced: shared caches across loaders).
- **Middleware**: `defineServerMiddleware`, `defineClientMiddleware`, `defineStreamObserver`, `defineApp`, plus the outcome constructors `redirect`, `deny` (and `render` at the `hono-preact/page` subpath) and predicates `isOutcome` / `isRedirect` / `isDeny` / `isRender`. See [Middleware](/docs/middleware).
- **Utilities**: `prefetch`, `isBrowser`, `Route`/`Router`/`lazy` (re-exports of preact-iso for advanced use).

### App-level config (optional)

```ts
// apps/site/src/app-config.ts
import { defineApp, defineServerMiddleware } from 'hono-preact';

const withRequestId = defineServerMiddleware(async (ctx, next) => {
  ctx.c.header('X-Request-Id', crypto.randomUUID());
  await next();
});

export default defineApp({ use: [withRequestId] });
```

The framework's generated server entry imports the default export from `src/app-config.ts` (configurable via the `appConfig` option to `honoPreact()`). If the file doesn't exist, the framework treats it as `defineApp({})`. Creating or deleting `src/app-config.ts` while the dev server is running restarts it automatically, so the change takes effect without a manual restart. The `appConfig.use` array is the outermost layer of the middleware chain: it wraps every loader, action, and page render. See [Middleware: The three layers](/docs/middleware#the-three-layers).

### `hono-preact/server` (workspace package)

Server-only utilities (`packages/server/`):

- **`renderPage`**: SSR entry that prerenders to HTML, injects head tags via hoofd, and turns middleware-thrown redirect / deny / render outcomes into the appropriate HTTP response.
- **`HonoContext`** / **`useHonoContext`**: access the Hono `Context` from Preact components during SSR.

### `hono-preact/vite` (workspace package)

Vite plugins for the framework (`packages/vite/`). The primary export is `honoPreact()`, which bundles all framework Vite configuration into a single plugin. See [Vite Configuration](/docs/vite-config) for usage.

- **`honoPreact()`** configures resolve deduplication, SSR bundling, client/server build outputs, and the client-shim auto-injection. Deployment target plugins (the worker or dev-server toolchain) come from the required `adapter` option, currently `cloudflareAdapter()` from `hono-preact/adapter-cloudflare` or `nodeAdapter()` from `hono-preact/adapter-node`.
- **`serverOnlyPlugin`** rewrites `*.server.*` imports during the client bundle build, replacing static imports with no-op stubs and dynamic `import('./*.server.*')` calls with `Promise.resolve({})` so server code never reaches the browser.
- **`serverLoaderValidationPlugin`** fails the build if a `.server.*` file has named exports other than `serverLoaders`, `serverActions`, `serverRooms`, or `serverSockets`.
- **`moduleKeyPlugin`** rewrites each `.server.*` file at build time with a `__moduleKey` derived from the file path, which the loader/action handlers use to dispatch RPC requests.
- **`clientShimPlugin`** prepends a `globalThis.process ??= { env: { NODE_ENV } }` shim to the client entry so libraries that read `process.env.NODE_ENV` at module-eval time in the browser do not throw.


---

> Source: https://framework.sbesh.com/docs/styling

# Styling

Write CSS the way you'd write it for any app: design tokens, Tailwind, `@font-face`, component rules, all in one stylesheet. Hand the framework that stylesheet and it takes care of delivery: every route gets a `<link>` for the styles it actually uses, with nothing to hand-split and nothing to wire up yourself.

## One global stylesheet

Point `css.global` at your stylesheet in `vite.config.ts`:

```ts
// vite.config.ts
import { honoPreact } from 'hono-preact/vite';
import { cloudflareAdapter } from 'hono-preact/adapter-cloudflare';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    honoPreact({
      adapter: cloudflareAdapter(),
      css: { global: 'src/styles/root.css' },
    }),
  ],
});
```

The framework injects it for you, in dev and in production: no manual `?url` import, no `<link>` in your Layout. Bring one stylesheet, and every page gets it.

At build time the framework goes further: it looks at which rules in that stylesheet only ever apply to one route's chunk of JavaScript, and splits those rules out into a sheet delivered just for that route, render-blocking in the SSR head, exactly like a route sheet you split by hand. What's left behind, the residual, ships as the global sheet every route still loads. Scoped rules load after the global sheet, so they win any equal-specificity tie against it, the same cascade order a hand-split sheet would give you. You don't request this or opt into it per route; it's automatic, and it never removes a rule from your app, only moves where it's delivered from.

| Option      | Type      | Default  | Description                                                                                                                                  |
| ----------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `global`    | `string`  | required | Project-relative path to your global stylesheet, e.g. `'src/styles/root.css'`.                                                               |
| `autoSplit` | `boolean` | `true`   | Split route-exclusive rules into per-route sheets. Set `false` to deliver the stylesheet unsplit.                                            |
| `minSize`   | `number`  | `1024`   | Minimum size in bytes for a route's split-out rules. Below this, they stay in the global sheet rather than costing a route an extra request. |

`css.global` must point at a file that exists; the framework throws a clear build error if it doesn't, telling you the path it checked.

Head order is fixed: whatever your Layout or route renders into `<head>` itself (title, meta, any `<link>` you write by hand) comes first, then the global stylesheet, then route sheets. One consequence is worth knowing up front: because the global stylesheet lands later in the head than anything you hand-write there, it wins an equal-specificity tie against a stylesheet you link yourself. If you need to override a rule from the global stylesheet, the override belongs inside the global stylesheet itself (it's one file, so a later rule there wins the normal cascade way) or in a hand-split route sheet, which loads after it for the same reason.

## How splitting decides what's exclusive

A rule is scoped to a route only when every class it depends on shows up in exactly one route's built JavaScript, nowhere else. That's a strict bar on purpose: the framework would rather ship a rule as global than guess wrong and scope it to the wrong route.

Two kinds of classes never clear that bar, and both fail safe by staying global:

- **Classes built at runtime**, like `` `item-${status}` ``, don't appear anywhere as a literal string, so the framework can't see them.
- **Classes that only appear in data**, like a CSS class name stored in a CMS field or a database row, aren't in any route's JavaScript at all.

Either one alone is harmless: the rule just stays global, same as it always would have without splitting. The one case that can bite is a _double_ failure: a route builds a class name at runtime, **and** that same class name happens to appear as a literal string in exactly one other route's code. Now the framework sees a single, unambiguous owner, and it isn't the route that actually needed the rule at runtime. If you hit this, the fix is to either hand-split that rule into a route sheet yourself (below), or turn off auto-split for the stylesheet with `autoSplit: false`.

## Hand-split route sheets

Auto-split covers rules the framework can prove are exclusive to one route. For anything else, or when you'd rather be explicit, import a stylesheet from a route module for its side effect and it ships only on that route:

```tsx
// src/pages/home.tsx
import '@/styles/home.css';

export default function Home() {
  return <section class="hero">...</section>;
}
```

The same pattern on a layout module scopes the sheet to every route under that layout:

```tsx
// src/components/DocsLayout.tsx
import '@/styles/docs.css';
import type { LayoutProps } from 'hono-preact';

export default function DocsLayout({ children }: LayoutProps) {
  return <div class="docs-shell">{children}</div>;
}
```

No `?url` suffix and no manual `<link>`: a bare side-effect `import` is the whole contract. The framework follows each route's build-time import graph to find the CSS it pulls in, injects a `<link rel="stylesheet">` for it after the global sheet (so it wins the same equal-specificity ties auto-split rules do), and carries it along on client-side navigation as part of the route's JS chunk.

Hand-split sheets and auto-split compose freely: nothing about importing `home.css` from `home.tsx` changes because `root.css` is also being split. Route sheets are always render-blocking, present for first paint with no flash of unstyled content, for the same reason the injected link is a real stylesheet link and not a hint.

## Keep centering in one `transform`

All framework CSS, whether it's your global stylesheet, an auto-split route sheet, or a hand-split one, goes through Lightning CSS as the production minifier, targeting the browsers Baseline Widely Available covers. One gotcha is worth knowing about ahead of time: when a rule declares a standalone `translate` / `scale` / `rotate` property alongside a `transform` property, the minifier keeps only `transform` and drops the standalone one. A rule that centers with `translate: -50% -50%` and animates with `transform: scale(...)` loses its centering in the production build, while `vite dev` (which doesn't run the minifier) still looks correct. Fold every component into a single `transform` so there's nothing for the minifier to drop.

```css
/* Correct: translate and scale live in one transform, nothing is dropped */
.dialog {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%) scale(0.98);
}
```

```css
/* Wrong: the minifier drops the standalone translate (a transform is
   present in the same rule), so only scale survives and centering is lost */
.dialog {
  position: fixed;
  top: 50%;
  left: 50%;
  translate: -50% -50%;
  transform: scale(0.98);
}
```

The framework fills in two independent defaults, and configuring one in `vite.config.ts` leaves the other alone. `build.cssMinify` chooses the minifier (the framework defaults it to `lightningcss`), and `css.lightningcss` supplies the Baseline targets. So setting `cssMinify: 'lightningcss'` explicitly is a no-op that keeps the Baseline targets, and setting your own `css.lightningcss` keeps Lightning CSS as the minifier while your options win wholesale over the targets. Setting `cssMinify: 'esbuild'` swaps the minifier out of the Lightning CSS pipeline entirely, so the Baseline targets no longer apply to it.

Either way, that carve-out doesn't extend to auto-split output: once `css.global` and `autoSplit` are on, every residual and route sheet the splitter emits is re-serialized through Lightning CSS with `minify: true` directly (not via Vite's `cssMinify` setting), so a custom `cssMinify` never opts split output out of minification.

## Preload critical fonts

List your above-the-fold fonts on `AppConfig.fonts` as `?url` imports, and the framework preloads them for you: a `<link rel="preload" as="font" type="font/woff2" crossorigin>` in the SSR head, plus a matching `Link` response header so a CDN or edge runtime can promote it to a 103 Early Hints response. Both flatten the font fetch into the same round trip as the HTML instead of waiting for the CSS that references it.

```ts
// src/app-config.ts
import { defineApp } from 'hono-preact';
import regular from '@/styles/fonts/brand-regular.woff2?url';
import semibold from '@/styles/fonts/brand-semibold.woff2?url';

export default defineApp({
  fonts: [regular, semibold],
});
```

`crossorigin` is mandatory on every font preload tag the framework emits: fonts always fetch in CORS mode, even when they're same-origin, so a preload without `crossorigin` doesn't match the font request the browser actually makes and the font downloads twice.

List only the weights your first paint needs; a body weight and a heading weight typically cover it. Preloading every weight in your type scale spends early bandwidth on fonts the current page never renders, competing with the resources that are actually on the critical path.

Font-display is a separate, per-stylesheet concern: `AppConfig.fonts` only controls when the browser starts fetching a font, not how it swaps in once loaded. Set `font-display` in your own `@font-face` rules as you normally would.


---

> Source: https://framework.sbesh.com/docs/hono-middleware

# Composing Hono Middleware

A `hono-preact` server is a Hono app. You can use any `hono/*` or `@hono/*` middleware package by mounting it inside your project's `api.ts`. This page covers the mount point, the rules around framework-reserved paths, and short recipes for the middleware packages most users reach for first.

If you're looking for the in-app middleware that wraps page renders, loaders, and actions (auth gates, request-scoped context, tracing across server and client), see [Middleware](/docs/middleware). That layer runs inside the RPC pipeline; this page is about the HTTP layer above it.

## api.ts: your Hono mount point

Create `src/api.ts` and default-export a Hono app:

```ts
// src/api.ts
import { Hono } from 'hono';

const app = new Hono();

export default app;
```

The framework mounts your app at the root, ahead of its reserved paths and the SSR catch-all:

```
api.ts (your Hono app)   <- composes first
  POST /__loaders        <- framework loader RPC
  POST <page-url>        <- framework action handler (per page)
  GET /__sockets         <- framework realtime socket upgrade
  GET *                  <- framework SSR
```

That ordering is the whole story. A `.use('*', ...)` in `api.ts` runs on every request the framework will see, including the SSR page render and the loader RPC endpoint. A `.get('/healthz', ...)` works the same way it does in any Hono app.

## Reserved paths

The framework owns three URL surfaces you must not override:

| Path              | Purpose                             |
| ----------------- | ----------------------------------- |
| `POST /__loaders` | Server loader RPC                   |
| `GET /__sockets`  | Realtime socket upgrade (WebSocket) |
| `GET *`           | SSR page renderer                   |

Page URLs also accept `POST` for action submission; do not register a conflicting `POST` route for any page path in `api.ts`.

`.use(...)` on those paths in `api.ts` is fine and is exactly how you compose middleware around them. What you cannot do is register a _route_ on those paths or a wildcard that swallows them. The build rejects these cases:

```ts
// All of these fail the build
app.get('*', handler);
app.all('/*', handler);
app.on(['GET'], '/*', handler);
app.post('/__loaders', handler);
```

If you need broad scope, use `app.use('*', middleware)` (which calls `next()` and composes) instead of `app.get('*', handler)` (which terminates the request).

## Recipes

### CORS

```ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';

const app = new Hono();

app.use(
  '*',
  cors({
    origin: ['https://your-app.example'],
    credentials: true,
  })
);

export default app;
```

Scope to your custom API routes if your SSR pages are same-origin only.

### CSRF protection

For cookie-authenticated `multipart/form-data` actions, see the dedicated [CSRF Protection](/docs/csrf) page. It explains when you need it, why the JSON path is already protected by browser CORS preflight, and how to write an Origin check that covers the multipart gap.

### Security headers

Apply a baseline of HTTP security headers to every response, including SSR pages:

```ts
import { secureHeaders } from 'hono/secure-headers';

app.use(
  '*',
  secureHeaders({
    contentSecurityPolicy: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'"],
      // tighten per your app
    },
  })
);
```

### Request logging

```ts
import { logger } from 'hono/logger';

app.use('*', logger());
```

Logs each request the framework handles, including loader and action RPC calls.

### Server-Timing

Emit `Server-Timing` headers so the browser's network panel can render a latency breakdown:

```ts
import { timing, setMetric } from 'hono/timing';

app.use('*', timing());
```

`setMetric(c, name, ms)` works anywhere you hold the Hono `Context`. Loaders and actions both see the same `c`, so a `defineServerMiddleware` can record timings that span the HTTP and RPC layers.

### Sentry

```ts
import { sentry } from '@hono/sentry';

app.use('*', sentry({ dsn: process.env.SENTRY_DSN }));
```

On Cloudflare Workers, read the DSN from `c.env` rather than `process.env`. See the `@hono/sentry` package docs for per-runtime setup.

### OpenTelemetry

```ts
import { otel } from '@hono/otel';

app.use('*', otel());
```

`@hono/otel` requires that an OpenTelemetry SDK is initialized before the Hono app loads. For Node, configure the SDK in your startup script; for Cloudflare, follow the Workers-specific tracing guide.

## API routes alongside middleware

`api.ts` is also where you write custom HTTP endpoints that are not framework loaders or actions:

```ts
app.get('/healthz', (c) => c.text('ok'));
app.post('/webhooks/stripe', stripeWebhookHandler);
```

Specific, non-wildcard patterns compose freely with the framework's reserved paths. For a larger surface, organize routes into sub-apps and mount them: `app.route('/api', subApp)`.


---

> Source: https://framework.sbesh.com/docs/websockets

# WebSockets

hono-preact ships two WebSocket layers. The typed socket primitive (`defineSocket` + `useSocket`) gives you a declarative, type-safe duplex channel wired automatically to the framework's shared connection. The raw `upgradeWebSocket` export, imported from `hono-preact`, lets you register any hand-authored WS route in `api.ts`, following Hono's own `upgradeWebSocket` pattern. It works on both adapters: on Node it rides the framework's shared connection, and on Cloudflare it upgrades in the worker via a per-route `WebSocketPair`.

For the rules around the `api.ts` mount point and framework-reserved paths, see [Composing Hono Middleware](/docs/hono-middleware).

## Choosing between sockets and live loaders

| Need                                      | Reach for                           |
| ----------------------------------------- | ----------------------------------- |
| Client sends messages to the server       | `defineSocket` + `useSocket`        |
| Server pushes data on mutations (pub/sub) | [Realtime Channels](/docs/realtime) |
| Server streams data to a layout widget    | [Live Loaders](/docs/live-loaders)  |

A socket is the right tool when the browser needs to send upstream, or when you want a persistent full-duplex channel. Server-to-client-only scenarios (a notification feed, a dashboard widget) are better served by SSE-backed live loaders, which require no upgrade plumbing.

On Node, a single HTTP connection is shared across the framework and all sockets. On Cloudflare a typed socket runs end to end: the worker guards the upgrade at the edge and forwards it to a per-connection Durable Object that runs the handler under the Hibernation API, so the same `defineSocket` works on both runtimes. Cross-connection fan-out (broadcasting to every connected client) is a separate concern: use [Rooms](/docs/rooms), which coordinate many connections through one Durable Object per topic.

## Typed sockets with `defineSocket`

The typed socket primitive integrates with the framework's route table and build pipeline. The build strips the server implementation on the client side, replacing it with a lightweight descriptor, so the types flow without shipping handler code to the browser.

### Server module

Place the socket definition in a `.server.ts` module, inside a `serverSockets` export:

```ts
// src/chat.server.ts
import { defineSocket } from 'hono-preact';
import { requireSession } from './auth/session.js';

export const serverSockets = {
  chat: defineSocket<
    { text: string }, // messages the client sends
    { text: string; from: string }, // messages the server sends
    { name: string } // socket.data shape, seeded by the `data` factory below
  >({
    // Optional guard middleware. A failing guard closes the socket with 4403.
    use: [requireSession],

    // Edge factory: runs at the upgrade with the live Context; its result seeds
    // socket.data. Read cookies, headers, and middleware values here.
    data: (c) => ({ name: c.get('user').name }),

    open(socket) {
      // Return a teardown fn to run on close (Node only; see the note below).
      return () => {
        console.log(`${socket.data.name} disconnected`);
      };
    },

    message(socket, msg) {
      // Echo the message back to the same connection.
      socket.send({ text: msg.text, from: socket.data.name });
    },

    close(socket, ev) {
      console.log('closed', ev.code, ev.reason);
    },
  }),
};
```

`open` runs once per connection after the upgrade. It receives only the `socket`; read request-derived values (cookies, headers, middleware state) in the `data` factory, which runs at the upgrade with the full Hono `Context` and seeds `socket.data`. Returning a function from `open` registers a teardown that runs when the connection closes on Node; on Cloudflare the connection is hibernatable, so use `close` for cleanup that must run on both runtimes.

`socket.data` is seeded by the `data` factory at connect time and is read-only (`Readonly<Data>`). Declare its shape with the third type parameter: `defineSocket<Incoming, Outgoing, Data>()`. It is `undefined` by default (no `data` factory). On Cloudflare each event sees the connect-time value (the Durable Object hibernates between events). For Node-only mutable per-connection state, capture a closure variable inside `open()` instead.

### Client component

Import the `serverSockets` map from the `.server` module and call `.useSocket` on the entry:

```tsx
// src/chat.tsx
import { serverSockets } from './chat.server.js';

export default function Chat() {
  const { send, status, lastMessage } = serverSockets.chat.useSocket({
    lastMessage: true,
    onMessage(msg) {
      console.log('received', msg.text);
    },
  });

  return (
    <div>
      <p>Status: {status}</p>
      {lastMessage && (
        <p>
          {lastMessage.from}: {lastMessage.text}
        </p>
      )}
      <button onClick={() => send({ text: 'hello' })}>Send</button>
    </div>
  );
}
```

The free `useSocket(ref, opts)` export also works and is equivalent; the method form is the idiomatic choice when the ref is a `serverSockets` entry.

`useSocket` manages the WebSocket lifecycle: it connects on mount, reconnects with exponential backoff on unexpected drops, and closes cleanly on unmount. `send` queues messages if the socket is not yet open, flushing them once the connection is established (up to 128 queued messages); beyond that cap, further sends while not open are dropped, with a dev-mode console warning rather than a silent loss. Toggling `enabled` to `false` on an open socket tears the connection down and `status` becomes `'closed'`.

`status` is reactive and drives UI affordances:

| Value            | Meaning                                   |
| ---------------- | ----------------------------------------- |
| `'connecting'`   | First connect attempt in progress         |
| `'open'`         | Connection is established                 |
| `'reconnecting'` | Connection dropped; backoff timer running |
| `'closing'`      | `close()` called; handshake in progress   |
| `'closed'`       | Connection closed and will not reconnect  |

### Guard model

A socket's guard chain is composed in order: app-level `use` from `defineApp({ use })`, then the owning route's page-layer `use`, then the socket's own `use` array. A socket colocated with a route (its `.server.ts` sibling) inherits that route's `use` chain automatically, the same as a colocated loader or action.

`serverRoute(r).socket(handler)` binds a socket to a route explicitly instead of relying on colocation:

```ts
// src/server/chat/room-chat.server.ts
import { serverRoute } from 'hono-preact';

const route = serverRoute('/chat');

export const serverSockets = {
  chat: route.socket<{ text: string }, { text: string; from: string }>({
    // Inherits `/chat`'s page-layer `use` chain, wherever this file lives.
    message(socket, msg) {
      socket.send({ text: msg.text, from: 'someone' });
    },
  }),
};
```

The declared pattern is stamped on the def and validated at boot: a pattern that does not match the module's mount, names an unknown route, or targets a childless wildcard fails the boot rather than running the socket under an empty gate chain. A declared binding takes precedence over the module-mount derivation, so it also lets a route-bound socket live under the [`src/server` registry](/docs/routes#the-srcserver-registry) organized by domain rather than beside its view. A bare `defineSocket` with no `serverRoute` binding, defined in a `src/server` registry module rather than colocated with a route, is route-independent: it only ever runs the app-level `use` and its own `use`. Add socket-specific authorization in the socket's own `use` array for concerns that only apply to the socket.

Binding to a route with `:param`s opens a typed param wire too. `useSocket` requires a `params` option shaped from the route pattern, and the same validated values reach the edge `data` factory as its second argument:

```ts
// src/server/boards/board-chat.server.ts
import { serverRoute } from 'hono-preact';

const route = serverRoute('/board/:id');

export const serverSockets = {
  boardChat: route.socket<
    { text: string },
    { text: string },
    { boardId: string }
  >({
    // Route params are validated at the upgrade and passed to the factory.
    data: (_c, { id }) => ({ boardId: id }),
    message(socket, msg) {
      socket.send({ text: msg.text });
    },
  }),
};
```

```tsx
// on the /board/:id page
import { useParams } from 'hono-preact';
import { serverSockets } from './server/boards/board-chat.server.js';

const { id } = useParams('/board/:id');
const { send } = serverSockets.boardChat.useSocket({ params: { id } });
```

Use `deny()`, not `redirect()`, to reject a realtime upgrade. A WebSocket handshake cannot follow an HTTP redirect, so a guard that throws `redirect()` on the socket path is treated as a deny (close `4403`) and logs a warning. If you share a guard between an HTTP route and its socket, branch on the request so the HTTP path redirects and the socket path denies.

An explicit `serverRoute(r).socket` binding on a param-bearing route authorizes on the route's params: `useSocket(ref, { params })` becomes required and typed from the route pattern. The client sends those params on the upgrade; the server validates them before the guard chain runs, denying the connection (close `4403`) when a required param is missing. The validated params are readable by the guard as `ctx.location.pathParams`, and are the same values passed to the `data` factory's second argument, so an authorization check or the seed for `socket.data` can key off them directly.

A **colocated** socket, a `.server.ts` sibling of a route with no `serverRoute` binding, has no param wire. `ctx.location.pathParams` stays empty, and the connection is never denied for a missing param, even next to a route with `:param`s. It never fails the boot for this either. When its mount route declares a param a guard could read and at least one guard tier is live (app-level `use`, the route's page-layer `use`, or the socket's own `use`), a console advisory names the socket and the params a guard would read as `undefined`. That advisory prints in production too, not just in dev: it is your only signal that the mismatch is live. Reach for an explicit `serverRoute(r).socket` binding whenever a socket needs to authorize on a route param. Rooms resolve their params differently, from the channel key rather than this `params` option; see [Rooms](/docs/rooms).

A route param outside the supported `:name` class (one or more of `[A-Za-z0-9_]`, with an optional `?`/`*`/`+`), like a hyphenated `/board/:board-id`, gets special treatment. Its value never reaches `ctx.location.pathParams` for a realtime connection, even though preact-iso's runtime matcher binds it fine over plain HTTP, so the params **wire** can't see it. The colocated-socket **advisory** still can: it reasons over every param a guard could actually read off the route (preact-iso's own matcher, not this framework's narrower `:param` grammar), so a hyphenated segment still fires the advisory rather than staying silent. A colocated socket on such a route is not rejected; it just never sees that param, the same as any other route param a colocated socket doesn't wire up. An **explicitly bound** `serverRoute(r).socket` fails the boot outright, whether or not a guard is live: `serverRoute('/board/:board-id').socket(...)` throws at startup rather than run with an empty params object, so every `/__loaders` request, action POST, and `/__sockets` upgrade returns a 500 until you rename the segment to use only letters, digits, and underscores.

The params a socket sees, both the `data` factory's second argument and the guard's `ctx.location.pathParams`, are plain objects: read them any way you like. You never have to worry about a param name clashing with a built-in like `constructor` or `toString`, because a route can't declare one in the first place: `serverRoute('/plugin/:constructor')` throws at definition.

### Cloudflare setup

On Cloudflare Workers, `defineSocket` runs inside a per-connection Durable Object, so it needs the `HONO_PREACT_REALTIME` Durable Object binding and migration in `wrangler.jsonc` (the same binding rooms and live-loader pub/sub use). See [Rooms → Cloudflare setup](/docs/rooms#cloudflare-setup) for the binding and migration. (This applies to `defineSocket`. The raw `upgradeWebSocket` path below is separate and needs no Durable Object binding: it upgrades in the worker via a `WebSocketPair`.)

### Reconnect behavior

`useSocket` reconnects automatically after unexpected drops. The default policy skips reconnect for close code `1000` (normal closure) and all `4000-4999` codes (application-defined). Code `4403` is issued by the framework when a socket's `use` guard rejects the upgrade, signaling that reconnecting would hit the same rejection.

Override the policy with `shouldReconnect`:

```ts
serverSockets.chat.useSocket({
  shouldReconnect: (ev) => ev.code !== 1000 && ev.code !== 4403,
  reconnect: {
    maxRetries: 10,
    minDelay: 500,
    maxDelay: 60_000,
    growth: 2,
  },
});
```

Disable the socket entirely with `enabled: false`; the hook will not connect until `enabled` becomes `true`.

### Close codes

| Code        | Meaning                                             |
| ----------- | --------------------------------------------------- |
| `1000`      | Normal closure; no reconnect by default             |
| `4000-4999` | Application-defined; no reconnect by default        |
| `4403`      | Guard rejected the upgrade; no reconnect by default |

## Raw WebSocket routes with `upgradeWebSocket`

For routes that do not fit the typed socket pattern, `upgradeWebSocket` from `hono-preact` lets you register any WS route in `api.ts` using the same Hono handler API:

```ts
// src/api.ts
import { Hono } from 'hono';
import { upgradeWebSocket } from 'hono-preact';

const app = new Hono();

app.get(
  '/ws',
  upgradeWebSocket(() => ({
    onMessage(event, ws) {
      ws.send(`echo: ${event.data}`);
    },
    onClose() {
      // cleanup
    },
  }))
);

export default app;
```

Both adapters install a WebSocket upgrader, so the same `upgradeWebSocket` route works on Node and Cloudflare with identical `onOpen` → `onMessage` → `onClose` semantics. The two runtimes differ only in how the connection is minted: Node shares the framework's single connection (the one that powers `serverSockets`), while Cloudflare mints a fresh `WebSocketPair` per route and needs no Durable Object binding.

### Node.js

On Node the framework's adapter wires the WebSocket upgrade internally (the same connection that powers `serverSockets`), so you do not install `@hono/node-ws`, call `createNodeWebSocket`, or export `injectWebSocket`. Your `api.ts` only needs `upgradeWebSocket` from `hono-preact`:

```ts
// src/api.ts
import { Hono } from 'hono';
import { upgradeWebSocket } from 'hono-preact';

const app = new Hono();

app.get(
  '/ws',
  upgradeWebSocket(() => ({
    onMessage(event, ws) {
      ws.send(`echo: ${event.data}`);
    },
  }))
);

export default app;
```

A working end-to-end example lives at `apps/example-node/` in the repo.

### Cloudflare Workers

The same `api.ts` route runs on Cloudflare with no adapter-specific code. The adapter upgrades each raw route in the worker via a `WebSocketPair`, so it needs no Durable Object binding (unlike `defineSocket`, which does). `onOpen` fires on Cloudflare just as it does on Node:

```ts
// src/api.ts
import { Hono } from 'hono';
import { upgradeWebSocket } from 'hono-preact';

const app = new Hono();

app.get(
  '/ws',
  upgradeWebSocket(() => ({
    onOpen(_e, ws) {
      ws.send('ready');
    },
    onMessage(event, ws) {
      ws.send(`echo: ${event.data}`);
    },
  }))
);

export default app;
```

Each raw route is its own `WebSocketPair` connection; for cross-connection fan-out use rooms, and for the typed duplex primitive use `defineSocket` (which runs in the Durable Object).

## Avoiding reserved paths

Register WebSocket routes on any non-colliding path. The build rejects catch-all and reserved-path route registrations in `api.ts`. See [Composing Hono Middleware](/docs/hono-middleware) for the full rules.

## API reference

### `defineSocket<Incoming, Outgoing, Data>(handler)`

| Parameter  | Type       | Description                                         |
| ---------- | ---------- | --------------------------------------------------- |
| `Incoming` | type param | Message type the client sends (JSON-serializable).  |
| `Outgoing` | type param | Message type the server sends (JSON-serializable).  |
| `Data`     | type param | Per-connection data bag type. Default: `undefined`. |

`handler` fields:

| Field     | Type                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `use`     | `ReadonlyArray<Middleware>`                             | Guard chain run before the upgrade. A failing guard closes with code 4403.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `data`    | `(c: Context, params: Params) => Data \| Promise<Data>` | Optional. Edge factory run once at the upgrade with the live Context and the route's validated params (`{}` for a bare `defineSocket`, or the route's params for a `serverRoute(r).socket` binding); its result seeds `socket.data`. May be async. The only place a socket handler sees a Context (on Cloudflare the handler runs inside a Durable Object). On Cloudflare the `data()` result rides a request header to the Durable Object (6KB limit); the Node dev server warns when the factory result exceeds this budget. |
| `open`    | `(socket) => void \| (() => void) \| Promise<...>`      | Runs once per connection. Returning a function registers a teardown (Node only; on Cloudflare use `close`). Receives only the socket; its `data` is the `data` factory result.                                                                                                                                                                                                                                                                                                                                                 |
| `message` | `(socket, msg: Incoming) => void \| Promise<void>`      | Called for every incoming message.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `close`   | `(socket, { code, reason }) => void`                    | Called when the connection closes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `error`   | `(socket, err) => void`                                 | Called on a socket error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

`socket` fields:

| Field                   | Type                      | Description                                                                                                                                                      |
| ----------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `send(msg)`             | `(msg: Outgoing) => void` | Send a message to the client. JSON-encoded by the framework.                                                                                                     |
| `close(code?, reason?)` | method                    | Close the connection.                                                                                                                                            |
| `data`                  | `Readonly<Data>`          | Per-connection data seeded by the `data` factory at connect time. Read-only; for Node-only mutable per-connection state, capture a closure variable in `open()`. |
| `raw`                   | `unknown`                 | Escape hatch to the underlying runtime socket.                                                                                                                   |

### `ref.useSocket(opts)` / `useSocket(ref, opts)`

`opts` is optional for a bare or param-less socket, and required for a
`serverRoute(r).socket` binding with route params (to supply `params`; see
below).

| Option                 | Type                                 | Default                                                                        | Description                                                                                                                                                     |
| ---------------------- | ------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `params`               | route params                         | required for a param-bearing `serverRoute(r).socket` binding, absent otherwise | The bound route's params, typed from the route pattern. Sent on the upgrade and validated server-side; a missing required param denies the connection (`4403`). |
| `onMessage`            | `(msg: Serialize<Outgoing>) => void` |                                                                                | Called for every incoming message. Does not trigger a re-render.                                                                                                |
| `onOpen`               | `() => void`                         |                                                                                | Called when the connection opens.                                                                                                                               |
| `onClose`              | `(e: CloseEvent) => void`            |                                                                                | Called when the connection closes.                                                                                                                              |
| `shouldReconnect`      | `(e: CloseEvent) => boolean`         | See below                                                                      | Returns `true` to reconnect.                                                                                                                                    |
| `reconnect.maxRetries` | `number`                             | `5`                                                                            | Maximum reconnect attempts.                                                                                                                                     |
| `reconnect.minDelay`   | `number`                             | `250`                                                                          | Minimum delay in ms before first retry.                                                                                                                         |
| `reconnect.maxDelay`   | `number`                             | `30000`                                                                        | Backoff cap in ms.                                                                                                                                              |
| `reconnect.growth`     | `number`                             | `2`                                                                            | Exponential growth factor.                                                                                                                                      |
| `enabled`              | `boolean`                            | `true`                                                                         | When `false`, the socket does not connect.                                                                                                                      |
| `lastMessage`          | `boolean`                            | `false`                                                                        | When `true`, the latest message is stored in reactive state and returned as `lastMessage`.                                                                      |

Default `shouldReconnect`: `false` for codes `1000` and `4000-4999`, `true` otherwise.

Returns:

| Field         | Type                               | Description                                               |
| ------------- | ---------------------------------- | --------------------------------------------------------- |
| `send`        | `(msg: Incoming) => void`          | Send a message. Queued if not yet open.                   |
| `status`      | `SocketStatus`                     | Reactive connection status.                               |
| `close`       | `(code?, reason?) => void`         | Close the connection. Suppresses reconnect.               |
| `closeInfo`   | `SocketCloseInfo \| undefined`     | Code, reason, and wasClean from the last close event.     |
| `lastMessage` | `Serialize<Outgoing> \| undefined` | Last received message, when `opts.lastMessage` is `true`. |

### `upgradeWebSocket(createEvents)`

Wraps Hono's `upgradeWebSocket` pattern. Works on both adapters: Node shares the framework connection, Cloudflare upgrades via a per-route `WebSocketPair` (no Durable Object). `onOpen` fires on both.

| Parameter      | Type                                            | Description                                     |
| -------------- | ----------------------------------------------- | ----------------------------------------------- |
| `createEvents` | `(c: Context) => WSEvents \| Promise<WSEvents>` | Factory that returns the Hono WSEvents handler. |

Returns a `MiddlewareHandler` for use in `app.get('/path', upgradeWebSocket(...))`.

### Type exports

```ts
import type {
  SocketRef,
  SocketHandler,
  ServerSocket,
  SocketStatus,
  SocketCloseInfo,
  ReconnectOptions,
  UseSocketOptions,
  UseSocketResult,
  UseSocketArgs,
} from 'hono-preact';
```

`UseSocketArgs<R>` is the type of `useSocket`'s options rest tuple (`[opts?: UseSocketOptions<R>]` for a param-less binding, `[opts: UseSocketOptions<R>]` for a param-bearing one): useful for typing a generic wrapper that forwards its own rest args to `useSocket` without re-deriving the required-vs-optional rule itself.

## See also

- [Realtime Channels](/docs/realtime): server-to-client pub/sub over SSE with `defineChannel` + `publish`.
- [Live Loaders](/docs/live-loaders): persistent streaming loaders for layout-scoped widgets.
- [Composing Hono Middleware](/docs/hono-middleware): `api.ts` mount rules and reserved paths.


---

> Source: https://framework.sbesh.com/docs/rooms

# Rooms & Presence

Rooms give you multi-connection fan-out over WebSockets with a built-in presence roster. A room is a `Channel`-keyed group: every connection that joins the same channel key sees each other's messages (via server-mediated broadcast) and each other's presence state. The roster (`members`) is reactive on the client and updates whenever anyone joins, leaves, or changes their presence.

Rooms are the right tool when you need multiple clients to talk to each other and you want to track who is connected. For server-to-client-only data streams, use [Realtime Channels](/docs/realtime) or [Live Loaders](/docs/live-loaders). For a private duplex channel to one client, use [WebSockets](/docs/websockets).

## Overview

Three pieces cooperate:

1. **Define a channel** with `defineChannel`. The channel name pattern (e.g. `room/:roomId`) sets the room key and types the params that flow into the server handler.
2. **Define a room** with `defineRoom(channel, handler)` inside a `serverRooms` export in a `.server` module. The handler receives a `RoomConnection` that can send to one client, broadcast to others, and update presence.
3. **Join from the client** with `serverRooms.<name>.useRoom({ key })` or the free `useRoom(ref, opts)` form. The hook returns a reactive `members` roster, a `send` function, and `setPresence` for updating this client's state.

Rooms ride the same `/__sockets` WebSocket transport as typed sockets and inherit the same guard composition: app `use`, then route-node `use`, then the room's own `use`. Fan-out is server-mediated: the client `send`s a message and the room's `onMessage` decides whether to call `conn.broadcast`.

## Example: live cursor board

### Channel definition

Define the channel in a shared file (not a `.server` module) so both server and client can import it:

```ts
// src/cursors-channel.ts
import { defineChannel } from 'hono-preact';

export type CursorMsg = { x: number; y: number };

// The channel name carries the room-key param.
// The payload type is the message type the room exchanges.
export const cursorsChannel = defineChannel('board/:boardId')<CursorMsg>();
```

### Server module

Place the room definition in a `.server.ts` module inside a `serverRooms` export. The build strips the server body on the client side and replaces it with a lightweight descriptor:

```ts
// src/board.server.ts
import { defineRoom } from 'hono-preact';
import { cursorsChannel, type CursorMsg } from './cursors-channel.js';

export type CursorState = { x: number; y: number; name: string };

export const serverRooms = {
  cursors: defineRoom(cursorsChannel, {
    // data runs at the edge with the live Hono Context. Its serializable result
    // seeds conn.data, available in onJoin and onMessage. Use it to capture
    // request-derived values (the authenticated user, a header) that are not
    // available inside a Durable Object on Cloudflare.
    data: (c) => ({ name: c.get('user')?.name ?? 'Guest' }),

    // Seed the joining member's initial presence state.
    presence: () => ({ x: 0, y: 0, name: 'Anonymous' }),

    onJoin(conn, { params }) {
      // params is typed: { boardId: string }
      // conn.data.name was captured at the edge by the data factory above.
      conn.setPresence({ x: 0, y: 0, name: conn.data.name });
    },

    onMessage(conn, msg) {
      // The client sent a cursor position. Broadcast to every other member.
      conn.broadcast(msg);
    },

    onLeave(conn) {
      // No explicit cleanup needed; the presence roster removes this member
      // automatically when the connection closes.
    },
  }),
};
```

### Client component

Import `serverRooms` from the `.server` module and call `.useRoom` with the channel key params:

```tsx
// src/board.tsx
import { serverRooms } from './board.server.js';
import type { CursorState } from './board.server.js';

export default function Board() {
  const { send, setPresence, members, self, status } =
    serverRooms.cursors.useRoom({
      key: { boardId: 'main' },
      // Seed this client's initial presence.
      presence: { x: 0, y: 0, name: 'Me' },
      onMessage(msg, from) {
        // Incoming cursor position from another member.
        // `msg` is typed as CursorMsg; `from` is the sender's member id.
        console.log(from, 'moved to', msg);
      },
    });

  function handleMouseMove(e: MouseEvent) {
    const pos = { x: e.clientX, y: e.clientY };
    // Update this client's presence in the roster.
    setPresence({ ...pos, name: self?.state?.name ?? 'Me' });
    // Notify others of the new position.
    send(pos);
  }

  return (
    <div
      onMouseMove={handleMouseMove}
      style="position:relative;width:100%;height:400px"
    >
      <p>Status: {status}</p>
      {members.map((m) => (
        <div
          key={m.id}
          style={`position:absolute;left:${m.state?.x}px;top:${m.state?.y}px`}
        >
          {m.state?.name}
        </div>
      ))}
    </div>
  );
}
```

`members` is reactive and updates on every join, leave, or presence change. `self` is this client's own roster entry, derived from the roster (it is `undefined` until the first server snapshot arrives). Incoming messages from other members go to `onMessage`; they do not trigger a re-render.

## Broadcast vs send

The server `conn` has two delivery methods:

- `conn.send(msg)` sends to this one client only.
- `conn.broadcast(msg)` fans out to every other member of the room. The sender is excluded by default; pass `{ self: true }` to also deliver to the sender.

The client has only `send`. There is no client-side `broadcast` because fan-out is server-mediated: the client calls `send` and the room's `onMessage` decides whether to call `conn.broadcast`. This keeps authorization centralized on the server.

## Guard inheritance

The guard chain for a room is: app `use` (from `defineApp({ use })`) then the owning route's page-layer `use` then the room's own `use`. A room colocated with a route (its `.server.ts` sibling) inherits that route's `use` chain automatically, the same as a colocated loader or action:

```ts
export const serverRooms = {
  cursors: defineRoom(cursorsChannel, {
    // The room's own guard, composed after the inherited app and route-node use.
    use: [requireBoardAccess],
    // ...
  }),
};
```

`serverRoute(r).room(channel, handler)` binds a room to a route explicitly instead of relying on colocation:

```ts
// src/server/boards/cursors.server.ts
import { serverRoute } from 'hono-preact';
import { cursorsChannel } from '../../cursors-channel.js';

const route = serverRoute('/board/:boardId');

export const serverRooms = {
  cursors: route.room(cursorsChannel, {
    // Inherits `/board/:boardId`'s page-layer `use` chain, wherever this file lives.
    onJoin(conn, { params }) {
      // params is typed from the CHANNEL pattern (board/:boardId), not the route.
      // The route's own `:boardId` is required to be a channel param of the same
      // name too, so the guard chain's `ctx.location.pathParams.boardId` and this
      // `params.boardId` always denote the same resource.
    },
  }),
};
```

The declared pattern is stamped on the def and validated at boot: a pattern that does not match the module's mount, names an unknown route, or targets a childless wildcard fails the boot rather than running the room under an empty gate chain. A declared binding takes precedence over the module-mount derivation, so it also lets a route-bound room live under the [`src/server` registry](/docs/routes#the-srcserver-registry) organized by domain rather than beside its view. A bare `defineRoom` with no `serverRoute` binding, defined in a `src/server` registry module rather than colocated with a route, is route-independent: it only ever runs the app-level `use` and its own `use`.

A room's route and its channel must be **congruent**: every `:param` the route pattern declares (including an optional `:id?` or rest `:rest*`/`:rest+` slot) must also be a param the channel pattern declares, and every `:param` the route _requires_ must be a _required_ param of the channel too (an optional or rest channel slot can be absent at runtime, so it cannot stand in for a required route param). The channel may be finer-grained and carry extra params of its own, but never coarser. `/board/:boardId` bound to a `board/:boardId` channel is congruent; `/board/:id` bound to that same channel is not, because `id` names no channel key. This applies whether the route param is required or optional/rest: preact-iso's runtime matcher binds an optional or rest param over HTTP just as readily as a required one, so a guard can read it either way.

Whether a mismatch fails the boot depends on how the room reaches its route:

- An **explicitly bound** room (`serverRoute(r).room`, or the equivalent `serverRoute(r).socket`) **fails the boot closed** on a mismatch, but only when a guard could actually read the mismatched param, that is, when at least one of the three tiers is non-empty: app-level `use` from `defineApp`, the route-node `use` chain, or the room's own `use`. With all three empty, no guard can read the param, so the boot proceeds and prints a console advisory naming the mismatch instead. Either way the mismatch is never silent.
- A **colocated** room (no `serverRoute` binding) **never fails the boot** for a mismatch. Its route is its module's mount, and it carries no param wire, so its guard chain reads the missing param as `undefined`. It prints the same console advisory instead, whether a guard reads that param today or you add one later. That advisory (like the socket one below) prints in production too, not just in dev: it is your only signal that the mismatch is live.

When congruence holds (names line up correctly), a separate dev-only advisory names each correspondence (which route param is satisfied by which channel key), so the pairing is never silent even when the names happen to match. A room's guard chain reads its params from the resolved **channel** key, not the route, so a route param the channel doesn't carry reads as `undefined`.

The requirement applies to a colocated room the same as an explicitly bound one: a colocated room's effective route is the module's mount, so its params are checked against that mount even with no declared `__routeId`. A bare `defineRoom` with no route binding and no colocation is route-independent and is not checked.

A route param outside the supported `:name` class (one or more of `[A-Za-z0-9_]`, with an optional `?`/`*`/`+`), like a hyphenated `/board/:board-id`, gets special treatment. Its value never reaches `pathParams` for a realtime connection, even though preact-iso's runtime matcher binds it fine over plain HTTP, so room param **resolution** can't see it. The congruence **check** above still can: it reasons over every param a guard could actually read off the route, using preact-iso's own matcher rather than this framework's narrower `:param` grammar, so a hyphenated segment is caught the same as a conforming one.

What happens next depends on how the room reaches that route. A **colocated** room is never rejected (per the bound/colocated split above); it prints the same console advisory instead. An **explicitly bound** room (`serverRoute(r).room`, or an equivalent `serverRoute(r).socket`) fails the boot outright, whether or not a guard is live: `serverRoute('/board/:board-id').room(...)` throws at startup rather than run with an empty params object, so every `/__loaders` request, action POST, and `/__sockets` upgrade returns a 500 until you rename the segment to use only letters, digits, and underscores.

A guard that denies the upgrade closes the connection with code `4403`. Use `deny()` rather than `redirect()` in a room guard: a WebSocket handshake cannot follow an HTTP redirect, so a `redirect()` is treated as a deny (close `4403`) and logs a warning.

The room-key params are resolved server-side before the guard chain runs, so a route-node or room `use` guard can read them via `ctx.location.pathParams` (for example `ctx.location.pathParams.roomId`) to make resource-scoped authorization decisions. This holds whether the route-node `use` is colocation-derived or explicitly bound: binding selects the `use` chain, not the room-key param wire, which always comes from the channel. The congruence check above is what guarantees that wire actually carries every param the route's own guards expect.

The params a room sees, both `onJoin`'s `ctx.params` and the guard's `ctx.location.pathParams`, are plain objects: read them any way you like. You never have to worry about a key name clashing with a built-in like `constructor` or `toString`, because a channel can't declare one in the first place: `defineChannel('board/:constructor')` throws at definition.

## Presence reconnect behavior

On reconnect, the room re-joins and the server sends a fresh presence snapshot. Any presence state the client passed in `opts.presence` is re-sent on open. There is a brief membership gap between disconnect and rejoin; missed messages during a disconnect are not replayed.

## Runtime scope

On Node, rooms fan out within a single process. Each Cloudflare Worker request is isolated, so in-process fan-out only reaches connections on the same instance. Rooms on Cloudflare run inside a Durable Object where all connections for a channel key share one instance, giving true cross-connection fan-out.

## Cloudflare setup

Rooms on Cloudflare run inside a Durable Object. The framework provides and re-exports the `HonoPreactRealtimeDO` class from the generated worker entry; you only need to declare the binding and migration in `wrangler.jsonc`. Apps scaffolded with the Cloudflare template get this pre-wired.

Add these two fields to `wrangler.jsonc`:

```jsonc
"durable_objects": {
  "bindings": [{ "name": "HONO_PREACT_REALTIME", "class_name": "HonoPreactRealtimeDO" }]
},
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["HonoPreactRealtimeDO"] }]
```

By default the binding name is `HONO_PREACT_REALTIME` and the class name is `HonoPreactRealtimeDO`: the generated entry reads `c.env.HONO_PREACT_REALTIME` and re-exports `HonoPreactRealtimeDO`. To use different names, pass them to the adapter in `vite.config.ts` and keep `wrangler.jsonc` in sync:

```ts
import { cloudflareAdapter } from 'hono-preact/adapter-cloudflare';

honoPreact({
  adapter: cloudflareAdapter({
    realtimeBinding: 'MY_REALTIME',
    realtimeClass: 'MyRealtimeDO',
  }),
});
```

`realtimeBinding` must match the binding `name`; `realtimeClass` must match both the binding `class_name` and the `new_sqlite_classes` migration tag. `realtimeClass` must be a valid JavaScript identifier (it is emitted as a `class` declaration in the generated entry).

A few behaviors differ between Node and Cloudflare:

- **Plain sockets (`defineSocket`/`useSocket`) run in a Durable Object.** On Cloudflare, the worker guards the upgrade at the edge and forwards it to a per-connection Durable Object running under the Hibernation API; on Node they run in-process. See [WebSockets](/docs/websockets) for setup details.
- **`onJoin` teardown functions run only on Node.** A function returned from `onJoin` is called on connection close in the Node runtime. On Cloudflare a Durable Object can hibernate between messages, so the teardown cannot be preserved. Use `onLeave` for cleanup that must run on both runtimes.
- **`conn.data` is read-only edge metadata.** `conn.data` is typed `Readonly<Data>` and seeded by the `data()` factory at upgrade time. For state that evolves and must broadcast, use `setPresence`. For Node-only mutable per-connection state, capture a closure variable in `onJoin()` instead.

## API reference

### `defineRoom(channel, handler)`

Defines a typed broadcasting room bound to a `Channel`. Place it in a `serverRooms` export in a `.server` module.

| Parameter | Type                     | Description                                                                      |
| --------- | ------------------------ | -------------------------------------------------------------------------------- |
| `channel` | `Channel<Name, Payload>` | The channel that keys this room. The name pattern types `onJoin`'s `ctx.params`. |
| `handler` | `RoomHandler`            | The server-side lifecycle object (see below).                                    |

Returns a `RoomRef` that the client hook reads. On the client side the `.server` import is replaced by a lightweight descriptor.

#### Handler fields

| Field       | Type                                                         | Description                                                                                                                                                                                                                                                                                                                                                                         |
| ----------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `use`       | `ReadonlyArray<Middleware>`                                  | Guard chain run before the upgrade. A failing guard closes with code `4403`.                                                                                                                                                                                                                                                                                                        |
| `presence`  | `() => State`                                                | Seeds the joining member's initial presence state.                                                                                                                                                                                                                                                                                                                                  |
| `data`      | `(c: Context) => Data \| Promise<Data>`                      | Optional. Runs at the edge (the worker) with the live Hono Context. May be async. Its serializable result seeds `conn.data`, available in `onJoin` and `onMessage`. Without a `data` factory, `conn.data` is `undefined`. On Cloudflare the result rides a request header to the Durable Object (6KB limit); the Node dev server warns when the factory result exceeds this budget. |
| `onJoin`    | `(conn, { params }) => void \| (() => void) \| Promise<...>` | Runs once per connection after the upgrade. `params` is typed from the channel name; request-derived data lives on `conn.data`. Returning a function registers it as a teardown called on leave.                                                                                                                                                                                    |
| `onMessage` | `(conn, msg) => void \| Promise<void>`                       | Called for every incoming message from this connection.                                                                                                                                                                                                                                                                                                                             |
| `onLeave`   | `(conn) => void`                                             | Called when the connection closes.                                                                                                                                                                                                                                                                                                                                                  |
| `onError`   | `(conn, err) => void`                                        | Called on a socket error.                                                                                                                                                                                                                                                                                                                                                           |

#### `RoomConnection` fields (the `conn` handle)

| Field                   | Type             | Description                                                                                                                                                                                    |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | `string`         | This connection's stable member id.                                                                                                                                                            |
| `send(msg)`             | method           | Send a message to this one client.                                                                                                                                                             |
| `broadcast(msg, opts?)` | method           | Fan out to every other member. Pass `{ self: true }` to also include the sender.                                                                                                               |
| `setPresence(state)`    | method           | Publish this connection's presence state to the roster.                                                                                                                                        |
| `data`                  | `Readonly<Data>` | Per-connection metadata seeded by the `data()` factory. Read-only; use `setPresence` for evolving state. For Node-only mutable per-connection state, capture a closure variable in `onJoin()`. |
| `close(code?, reason?)` | method           | Close this connection.                                                                                                                                                                         |

### `ref.useRoom(opts)` / `useRoom(ref, opts)`

`opts` is optional for a param-less channel, and required for a channel with
params (to supply `key`; see below).

| Option                 | Type                          | Default                        | Description                                                                                    |
| ---------------------- | ----------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `key`                  | channel params                | required if channel has params | The room-key params (e.g. `{ roomId: 'demo' }`). The server interpolates the topic from these. |
| `presence`             | `State`                       |                                | Initial presence state, sent on open and re-sent on every reconnect.                           |
| `onMessage`            | `(msg, from: string) => void` |                                | Called for each incoming message. Does not trigger a re-render.                                |
| `onOpen`               | `() => void`                  |                                | Called when the connection opens.                                                              |
| `onClose`              | `(e: CloseEvent) => void`     |                                | Called when the connection closes.                                                             |
| `shouldReconnect`      | `(e: CloseEvent) => boolean`  | See below                      | Returns `true` to reconnect.                                                                   |
| `reconnect.maxRetries` | `number`                      | `5`                            | Maximum reconnect attempts.                                                                    |
| `reconnect.minDelay`   | `number`                      | `250`                          | Minimum delay in ms before first retry.                                                        |
| `reconnect.maxDelay`   | `number`                      | `30000`                        | Backoff cap in ms.                                                                             |
| `reconnect.growth`     | `number`                      | `2`                            | Exponential growth factor.                                                                     |
| `enabled`              | `boolean`                     | `true`                         | When `false`, the room does not connect.                                                       |

Default `shouldReconnect`: `false` for codes `1000` and `4000-4999`, `true` otherwise.

Returns:

| Field         | Type                                   | Description                                                                                       |
| ------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `send`        | `(msg) => void`                        | Send a message to the server. Queued if not yet open.                                             |
| `setPresence` | `(state) => void`                      | Publish this client's presence state to the roster.                                               |
| `members`     | `ReadonlyArray<PresenceMember<State>>` | The presence roster, reactive.                                                                    |
| `self`        | `PresenceMember<State> \| undefined`   | This client's own roster entry. `undefined` until the first snapshot arrives.                     |
| `status`      | `SocketStatus`                         | Reactive connection status (`'connecting'`, `'open'`, `'reconnecting'`, `'closing'`, `'closed'`). |
| `close`       | `(code?, reason?) => void`             | Close the connection. Suppresses reconnect.                                                       |
| `closeInfo`   | `SocketCloseInfo \| undefined`         | Code, reason, and wasClean from the last close event.                                             |

### Type exports

```ts
import type {
  RoomRef,
  RoomHandler,
  RoomConnection,
  UseRoomOptions,
  UseRoomResult,
  PresenceMember,
  UseRoomArgs,
} from 'hono-preact';
```

`UseRoomArgs<R>` is the type of `useRoom`'s options rest tuple (`[opts?: UseRoomOptions<R>]` for a param-less binding, `[opts: UseRoomOptions<R>]` for a param-bearing one): useful for typing a generic wrapper that forwards its own rest args to `useRoom` without re-deriving the required-vs-optional rule itself.

## See also

- [WebSockets](/docs/websockets): the typed socket primitive (`defineSocket` + `useSocket`) for private duplex channels.
- [Realtime Channels](/docs/realtime): server-to-client pub/sub over SSE with `defineChannel` + `publish`.
- [Live Loaders](/docs/live-loaders): persistent streaming loaders for layout-scoped widgets.


---

> Source: https://framework.sbesh.com/docs/render-page

# renderPage

Use `renderPage` in your server's catch-all handler to SSR your app. It prerenders the Preact tree to HTML, injects collected head tags, and returns a complete HTTP response, replacing the boilerplate for dispatcher setup, head tag injection, and HTML assembly that would otherwise live in every app's catch-all handler.

## Usage

```ts
import { renderPage } from 'hono-preact/server';

app.get('*', (c) => renderPage(c, <Layout context={c} />));
```

That single line replaces the boilerplate for dispatcher setup, prerendering, head tag injection, and HTML assembly that would otherwise live in every app's catch-all handler.

## API

```ts
renderPage(
  c: Context,
  node: VNode,
  options?: { defaultTitle?: string; appConfig?: AppConfig }
): Promise<Response>
```

| Param                  | Description                                                                                                                                                                                                                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `c`                    | The Hono `Context` from your route handler                                                                                                                                                                                                                                                                                                        |
| `node`                 | The root Preact element to render, typically your `<Layout>`                                                                                                                                                                                                                                                                                      |
| `options.defaultTitle` | Fallback `<title>` when no page sets one via hoofd. Defaults to `''`. Express defaults via `<Head defaultTitle="...">` in your `Layout` for the common case; the option is here for custom server entries that call `renderPage` directly.                                                                                                        |
| `options.appConfig`    | The default-exported result of `defineApp()`. Surfaces app-level config to the render: [middleware](/docs/middleware) composition via `use`, plus opt-in features like [`speculation`](/docs/link-prefetch). The framework's generated server entry threads this for you; custom server entries must pass it explicitly to enable those features. |

## Head tags

Head tags (`<title>`, `<meta>`, `<link>`) are collected during prerender via hoofd. Pages set them with the `useTitle`, `useMeta`, and `useLink` hooks (see [Head Management](/docs/head)):

```tsx
import { useTitle } from 'hono-preact';

export default function MoviesPage() {
  useTitle('Movies');
  return <main>…</main>;
}
```

`renderPage` injects the collected tags into the `<head>` of the rendered HTML before returning the response.

## Redirect outcomes

If a [middleware](/docs/middleware) throws `redirect('/path')` during SSR, `renderPage` catches the outcome and turns it into an HTTP redirect via `c.redirect()`, so you don't need to handle it in the route handler. Deny outcomes thrown during SSR map to an HTTP response at the deny's status; render outcomes substitute an alternative component into the prerender tree.

## Custom server routes

Most apps never write the server entry. The framework's Vite plugin generates it, mounting `loadersHandler` on `POST /__loaders`, the page POST action handler, your optional `src/api.ts`, and the `renderPage` SSR catch-all on one Hono app exported as the worker's default.

For your own server-side routes, author `src/api.ts`; the generated entry mounts it alongside the framework routes, so you get custom endpoints without owning the entry:

```ts
// src/api.ts
import { Hono } from 'hono';

const api = new Hono().get('/api/movies', async (c) => {
  return c.json(await getMovies());
});

export default api;
```

`renderPage` is public (see [Usage](#usage) above), so a custom catch-all can call it directly when you need bespoke layout injection or a `defaultTitle`. The loader and page-action handlers are not a public hand-wiring surface, though. The framework's generated entry delegates the full wiring to an internal `createServerEntry` factory behind `hono-preact/server/internal/runtime`, a private, version-coupled contract the codegen emits. That factory builds the route-use resolver carrying your page-level `use` guards (including auth gates) and threads it into both handlers, so a page guard can never be silently dropped on the loader or action path. Because the factory is internal, hand-assembling a full entry depends on a door that can change in any non-major release: pin your framework version if you reach for it. Short of an alternate runtime, prefer `api.ts` plus the generated entry.


---

> Source: https://framework.sbesh.com/docs/link-prefetch

# Link Prefetch

Link prefetch makes navigation feel instant by fetching destinations before the user clicks. Enable it once with `speculation: true` in your app config; the framework emits a Speculation Rules tag that tells supporting browsers to prefetch same-origin links on hover. The feature is off by default.

## Enabling

Set `speculation: true` on your `defineApp` config:

```ts
import { defineApp } from 'hono-preact';

export default defineApp({
  speculation: true,
});
```

Once enabled, every server-rendered page emits the speculation rules tag. No per-route configuration.

The tag lands inside the existing `<head>` element. If your `Layout` renders an HTML document with no `<head>`, the framework has nowhere to inject the tag and no tag is emitted; the same constraint applies to hoofd's `<title>`, `<meta>`, and `<link>` injection.

## What gets prefetched

The emitted rule applies to every same-origin `<a href>` link rendered in the page. Cross-origin links are skipped automatically.

The browser decides when to prefetch based on the `moderate` eagerness setting: pointer hover or touchstart usually triggers it, click-time is too late. The prefetched response counts as a normal `GET` against your server.

## Opting individual links out

Some links should never be prefetched: ones that mutate server state via a `GET` (logout, sign-out, unsubscribe), generate signed URLs that count against a quota, or otherwise have side effects on fetch. Mark them with the `data-no-prefetch` attribute:

```tsx
<a href="/logout" data-no-prefetch>
  Sign out
</a>
```

The browser excludes any link matching `[data-no-prefetch]` from the rule. Plain HTML attribute; works on any `<a>` element.

## Auditing before enabling

The framework cannot tell which of your `GET` routes are safe to prefetch. Before flipping `speculation: true` on, review your app for routes where a `GET` does any of:

- Records a write (analytics ping, view-counter increment, audit log).
- Burns a one-shot token (signed-URL with single-use semantics).
- Triggers a side effect (sends an email, decrements a quota, expires a session).

Add `data-no-prefetch` to the links that lead to those routes, or refactor them to `POST` so prefetch never fires. The framework's mutation pattern is `POST`-only by design; route-level GETs are expected to be idempotent.

## Strict-CSP apps

The emitted script is a normal `<script>` element and is subject to your `Content-Security-Policy`. Apps with strict CSPs that don't allow inline scripts will see the speculation script blocked by the browser. The framework does not currently plumb a CSP nonce. If your app needs Speculation Rules under strict CSP, file an issue describing the use case.

## Prefetch on intent

`usePrefetch(href, loaders)` returns a callback that prefetches a link's loader
data, resolving the target route's params from the route table for you (no
copied route pattern). Bind it to whatever events express intent, hover and
focus, touch, an `IntersectionObserver`, a long-press:

```tsx
import { usePrefetch } from 'hono-preact';
import { serverLoaders } from '../pages/issue.server.js';

function IssueLink({ href }: { href: string }) {
  const prefetchIssue = usePrefetch(href, serverLoaders.issue);
  return (
    <a href={href} onMouseEnter={prefetchIssue} onFocus={prefetchIssue}>
      Open issue
    </a>
  );
}
```

Pass one loader or an array. A warm cache makes repeat fires free, so binding to
several events is fine.

## See also

- [Middleware](/docs/middleware): `defineApp` accepts other options beyond `speculation`, including `use` for middleware composition.
- [renderPage](/docs/render-page): how the `appConfig` (including `speculation`) is threaded into the server render.


---

> Source: https://framework.sbesh.com/docs/deployment

# Build & Deploy

hono-preact ships a build pipeline for each target runtime. Pick the Cloudflare
adapter to run your app as a Worker with bindings and SSR in `workerd`; pick
the Node adapter to deploy as a standard Node server. This page covers the dev,
build, and deploy commands for both.

## Adapters

The framework targets whichever adapter you choose. Two adapters ship today:
`cloudflareAdapter()` from `hono-preact/adapter-cloudflare` and `nodeAdapter()`
from `hono-preact/adapter-node`. You select one in [`vite.config.ts`](/docs/vite-config) by passing
it to the framework plugin: `honoPreact({ adapter: ... })`. An adapter is
required.

Dev, build, and deploy all behave per-adapter. The rest of this page covers
both flows.

## Cloudflare Workers

This section assumes a `cloudflareAdapter()` in `vite.config.ts`:

```ts
import { cloudflareAdapter } from 'hono-preact/adapter-cloudflare';
// ...
plugins: [honoPreact({ adapter: cloudflareAdapter() })],
```

### Development

```bash
npm run dev
```

Starts the Vite dev server. The Cloudflare adapter runs your worker inside
`workerd` (the real Cloudflare Workers runtime) via `@cloudflare/vite-plugin`,
so development mirrors production: Cloudflare bindings, the SSR runtime, and
WebSocket upgrades all behave the same as a deployed Worker. Hot module
replacement works for both client components and server code.

### Production build

```bash
npm run build
```

A single `vite build`. Vite's Environment API builds the browser bundle and the
Worker bundle together; there is no separate client pass. The `serverOnlyPlugin`
still replaces every `*.server.*` import with a no-op stub so server code never
enters the browser bundle.

Output is split into two directories so worker source can never be served as a
static asset:

```
dist/
  client/                      # static assets, served from Cloudflare's CDN
    static/client.js            #   client entry
    static/<name>-<hash>.js     #   lazy route chunks
    static/<name>-<hash>.css
  hono_preact/                 # the Worker bundle
    index.js                    #   bundled Worker
    wrangler.json               #   generated deploy config
```

The Worker directory name is derived from the `name` field in `wrangler.jsonc`
(hyphens become underscores), so `hono-preact` produces `dist/hono_preact/`.

### Local preview

```bash
npm run preview
```

Runs `vite preview`, which serves the production build through `workerd` again.

### Configuring `wrangler.jsonc`

`wrangler.jsonc` is the source of truth `@cloudflare/vite-plugin` reads:

```jsonc
{
  "name": "your-app-name", // also names the dist/<name>/ worker directory
  "main": "node_modules/.vite/hono-preact/server-entry.tsx",
  "compatibility_date": "2026-02-22",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": "./dist/client",
    "binding": "ASSETS",
  },
}
```

`main` points at the server entry the framework generates into the Vite cache
directory; the framework writes that file before the build starts. `assets`
points at the client build output; `assets.binding` exposes those files to the
Worker as `env.ASSETS`, which the framework reads at render time to emit
`modulepreload` hints for the client entry's boot chunks. No `run_worker_first` list is needed: the
client assets and the Worker bundle land in separate directories, so the Worker
source is never exposed through the asset store. The build also writes a
`.assetsignore` into `dist/client/` that excludes the generated config from the
asset upload.

### Deploy

```bash
npm run deploy
```

This runs `wrangler deploy` against the generated config in the Worker output
directory (`dist/hono_preact/wrangler.json`), which references the built Worker
and the `dist/client/` assets. Run `npm run build` first so the output exists.

## Node.js

### Setup

Register the Node adapter in `vite.config.ts`:

```ts
import { honoPreact } from 'hono-preact/vite';
import { nodeAdapter } from 'hono-preact/adapter-node';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [honoPreact({ adapter: nodeAdapter() })],
});
```

`@hono/node-server` is a peer dependency, so install it alongside the
framework: `npm install @hono/node-server`. `@hono/node-ws` is an optional peer
if you need WebSocket upgrades.

### Development

```bash
npm run dev
```

Starts the Vite dev server. The Node adapter handles SSR through Vite's SSR
module runner, so HMR works for both client and server code.

### Production build and start

`vite build` emits a server entry at `dist/server/server-entry.js` and the
client bundle under `dist/client/`. Start production with:

```bash
node dist/server/server-entry.js
```

The server listens on `PORT` (default 3000).

### Deploying

Deploy the same way you would any Node server: a container image (Docker),
a system service (systemd), or a PaaS that runs Node processes. Static assets
must be served from `dist/client/`; the Node adapter serves them in-process
when you run the bundled server, so a single `node` process handles both
assets and SSR.

## See also

- [Vite Config](/docs/vite-config): full `honoPreact()` options reference and peer-dependency setup.
- [Composing Hono Middleware](/docs/hono-middleware): adding custom Hono routes and middleware alongside the framework (via `src/api.ts`).


---

> Source: https://framework.sbesh.com/docs/components

# Components

hono-preact ships a set of headless, accessible UI primitives that lean on the
platform: the native `<dialog>` element and top layer, a battle-tested positioning
library, and a thin ARIA, keyboard, and collection layer on top. The popup
components (Popover, Tooltip, Menu, Select, Combobox) promote their surfaces into
the top layer with the Popover API and require it; Dialog builds on the native
`<dialog>` element. Positioning is computed in JavaScript, so CSS anchor
positioning is not used.

## What's here

The reference is grouped as the library grows:

- **Overlays:** [Dialog](/docs/components/dialog), [Popover](/docs/components/popover), [Tooltip](/docs/components/tooltip), [Menu](/docs/components/menu), [Context Menu](/docs/components/context-menu), [Select](/docs/components/select), [Combobox](/docs/components/combobox), [Toast](/docs/components/toast).
- **Foundations:** the shared primitives the components build on: the render-prop
  and ref helpers ([renderElement](/docs/components/render-element),
  [mergeRefs](/docs/components/merge-refs)), controlled state
  ([useControllableState](/docs/components/use-controllable-state)), and the
  overlay building blocks for positioning, dismissal, and focus return
  ([usePosition](/docs/components/use-position),
  [useDismiss](/docs/components/use-dismiss),
  [useFocusReturn](/docs/components/use-focus-return)).


---

> Source: https://framework.sbesh.com/docs/components/dialog

# Dialog

An accessible modal dialog built on the native `<dialog>` element. The browser
supplies the focus trap, background `inert`, top layer, and Escape-to-close;
`hono-preact-ui` adds the ARIA wiring, open-state, and `render`-prop
composition. It ships unstyled: style it through the `data-state` contract.

## Demo

<Example code={dialogCode}>

</Example>

## Styling

Every part exposes `data-state="open" | "closed"`. The popup is a native
`<dialog>`, so its backdrop is the `::backdrop` pseudo-element and its entry
animates with `@starting-style` (degrading to no animation where unsupported).
The demo above uses the styles below; copy a starting point in either flavor:

```css
/* Center the modal and give it a card surface. position + transform restore
   centering even when a reset (e.g. Tailwind preflight) clears the UA margin
   that normally centers a modal <dialog>. Keep centering in `transform`, not the
   standalone `translate` property: a rule that sets both can have its `translate`
   dropped by a CSS minifier, silently un-centering the dialog in a production
   build. */
dialog[data-state='open'] {
  position: fixed;
  top: 50%;
  left: 50%;
  width: min(28rem, calc(100vw - 2rem));
  max-height: calc(100dvh - 2rem);
  overflow: auto;
  padding: 1.5rem;
  border: 1px solid #e4e4e7;
  border-radius: 14px;
  background: #fff;
  color: #18181b;
  box-shadow:
    0 10px 15px -3px rgb(0 0 0 / 0.2),
    0 4px 6px -4px rgb(0 0 0 / 0.2);
  opacity: 1;
  transform: translate(-50%, -50%);
  transition:
    opacity 160ms ease,
    transform 160ms ease;
}

@starting-style {
  dialog[data-state='open'] {
    opacity: 0;
    transform: translate(-50%, calc(-50% + 8px)) scale(0.98);
  }
}

dialog::backdrop {
  background: rgb(0 0 0 / 0.5);
  backdrop-filter: blur(2px);
  opacity: 1;
  transition: opacity 160ms ease;
}

@starting-style {
  dialog[open]::backdrop {
    opacity: 0;
  }
}

@media (prefers-color-scheme: dark) {
  dialog[data-state='open'] {
    border-color: #27272a;
    background: #18181b;
    color: #fafafa;
  }
}

dialog[data-state='closed'] {
  animation: dialog-out 160ms ease-in forwards;
}
@keyframes dialog-out {
  to {
    opacity: 0;
    transform: translate(-50%, calc(-50% + 8px)) scale(0.98);
  }
}

dialog[data-state='closed']::backdrop {
  animation: dialog-backdrop-out 160ms ease-in forwards;
}
@keyframes dialog-backdrop-out {
  to {
    opacity: 0;
  }
}

@media (prefers-reduced-motion: reduce) {
  dialog[data-state='open'],
  dialog[data-state='closed'],
  dialog::backdrop,
  dialog[data-state='closed']::backdrop {
    transition: none;
    animation: none;
  }
}
```

```tsx
<Dialog.Popup
  class="fixed top-1/2 left-1/2 [transform:translate(-50%,-50%)]
         w-[min(28rem,calc(100vw-2rem))] max-h-[calc(100dvh-2rem)] overflow-auto
         rounded-2xl border border-zinc-200 bg-white p-6 text-zinc-900 shadow-xl
         opacity-100 transition-[opacity,transform] duration-[160ms] ease-out
         starting:opacity-0 starting:[transform:translate(-50%,calc(-50%_+_8px))_scale(0.98)]
         data-[state=closed]:opacity-0 data-[state=closed]:[transform:translate(-50%,calc(-50%_+_8px))_scale(0.98)]
         motion-reduce:transition-none
         backdrop:bg-black/50 backdrop:backdrop-blur-sm
         dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-100"
>
  {/* Dialog.Title, Dialog.Description, Dialog.Close */}
</Dialog.Popup>
```

## API reference

Every part accepts a `render` prop for composition (see
[renderElement](/docs/components/render-element)) and forwards unknown props to the
element it renders. `Dialog.Trigger`, `Dialog.Popup`, and `Dialog.Close` also
expose `data-state="open" | "closed"` and pass `{ open }` to a render function.

### Dialog.Root

Provides state and id wiring to the parts. Renders only its children.

| Prop           | Type                      | Default | Description                                       |
| -------------- | ------------------------- | ------- | ------------------------------------------------- |
| `open`         | `boolean`                 | -       | Controlled open state. Pair with `onOpenChange`.  |
| `defaultOpen`  | `boolean`                 | `false` | Initial open state when uncontrolled.             |
| `onOpenChange` | `(open: boolean) => void` | -       | Called when the dialog requests an open or close. |
| `children`     | `ComponentChildren`       | -       | The trigger and popup.                            |

### Dialog.Trigger

Opens the dialog on click. Default element `<button type="button">`.

| Prop       | Type                                    | Default | Description                                                                |
| ---------- | --------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `render`   | `RenderProp<{ open: boolean }>`         | -       | Compose or replace the element.                                            |
| `children` | `ComponentChildren`                     | -       | Trigger label.                                                             |
| `...props` | `JSX.HTMLAttributes<HTMLButtonElement>` | -       | Forwarded to the element; a passed `onClick` runs before the dialog opens. |

Sets `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, `id`, and `data-state`.

### Dialog.Popup

The native `<dialog>`. Renders closed on the server and calls `showModal()` on
the client when opened.

| Prop                   | Type                                    | Default | Description                                                 |
| ---------------------- | --------------------------------------- | ------- | ----------------------------------------------------------- |
| `render`               | `RenderProp<{ open: boolean }>`         | -       | Compose or replace the element.                             |
| `aria-label`           | `string`                                | -       | Accessible name when there is no `Dialog.Title`.            |
| `closeOnBackdropClick` | `boolean`                               | `true`  | Close when the backdrop (the dialog's own area) is clicked. |
| `children`             | `ComponentChildren`                     | -       | Title, description, body, and close controls.               |
| `...props`             | `JSX.HTMLAttributes<HTMLDialogElement>` | -       | Forwarded to the element.                                   |

Sets `id`, `data-state`, `aria-labelledby` (the Title) or `aria-label`, and
`aria-describedby` (only when a `Dialog.Description` is present). `role="dialog"`
and `aria-modal="true"` come implicitly from `showModal()`.

### Dialog.Title

The dialog's accessible name, wired to the popup's `aria-labelledby`. Default
element `<h2>`.

| Prop       | Type                                     | Default | Description                     |
| ---------- | ---------------------------------------- | ------- | ------------------------------- |
| `render`   | `RenderProp`                             | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                      | -       | Title text.                     |
| `...props` | `JSX.HTMLAttributes<HTMLHeadingElement>` | -       | Forwarded to the element.       |

### Dialog.Description

Optional supporting text, wired to the popup's `aria-describedby` while it is
rendered. Default element `<p>`.

| Prop       | Type                                       | Default | Description                     |
| ---------- | ------------------------------------------ | ------- | ------------------------------- |
| `render`   | `RenderProp`                               | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                        | -       | Description text.               |
| `...props` | `JSX.HTMLAttributes<HTMLParagraphElement>` | -       | Forwarded to the element.       |

### Dialog.Close

Closes the dialog on click. Default element `<button type="button">`.

| Prop       | Type                                    | Default | Description                                                                 |
| ---------- | --------------------------------------- | ------- | --------------------------------------------------------------------------- |
| `render`   | `RenderProp<{ open: boolean }>`         | -       | Compose or replace the element.                                             |
| `children` | `ComponentChildren`                     | -       | Button label.                                                               |
| `...props` | `JSX.HTMLAttributes<HTMLButtonElement>` | -       | Forwarded to the element; a passed `onClick` runs before the dialog closes. |

### Primitives

`hono-preact-ui` also exports the building blocks the parts use, for composing
your own components. Each has its own page with examples:
[renderElement](/docs/components/render-element),
[useControllableState](/docs/components/use-controllable-state), and
[mergeRefs](/docs/components/merge-refs).

## Accessibility

A dialog must have an accessible name: render a `Dialog.Title` (wired through
`aria-labelledby`) or pass `aria-label` to `Dialog.Popup`. A `Dialog.Description`
is wired through `aria-describedby` when present.

Because the popup is a native modal `<dialog>`, the platform handles the rest:

- Focus moves into the dialog when it opens and is trapped until it closes.
- Background content is `inert`: not focusable and hidden from the accessibility tree.
- Escape closes the dialog and focus returns to the trigger.
- The dialog renders in the top layer, above all other content, with the
  `::backdrop` covering the page.
- Screen readers announce the dialog's name, and its description when present.


---

> Source: https://framework.sbesh.com/docs/components/popover

# Popover

A non-modal, anchored overlay for interactive content: menus of actions, small
forms, or detail panels. Positioning runs on Floating UI; the overlay renders
in place and promotes to the browser top layer using the Popover API.
It ships unstyled: style it through the `data-state`, `data-side`,
and `data-align` contract.

## Demo

<Example code={popoverCode}>

</Example>

## Styling

Parts expose `data-state="open" | "closed"`; the Positioner and Arrow also
expose `data-side` and `data-align`. The Positioner is the fixed-positioned
wrapper, so size, z-index, and entry animation go on the Popup inside it. The
demo above uses the styles below; copy a starting point in either flavor:

```css
.docs-popover-positioner {
  z-index: 50;
}
.docs-popover {
  box-sizing: border-box;
  width: max(16rem, 12rem);
  padding: 1rem;
  border: 1px solid #e4e4e7;
  border-radius: 0.625rem;
  background: #fff;
  color: #18181b;
  box-shadow:
    0 10px 15px -3px rgb(0 0 0 / 0.25),
    0 4px 6px -4px rgb(0 0 0 / 0.25);
  opacity: 1;
  transform: translateY(0);
  transition:
    opacity 120ms ease,
    transform 120ms ease;
}
/* Compact popup typography so the title/description do not inherit page heading
   and paragraph margins. */
.docs-popover h2 {
  font-size: 0.95rem;
  font-weight: 600;
  margin: 0 0 0.25rem;
}
.docs-popover p {
  margin: 0 0 0.75rem;
  font-size: 0.875rem;
  color: #71717a;
}
@starting-style {
  .docs-popover[data-state='open'] {
    opacity: 0;
    transform: translateY(-4px);
  }
}
.docs-popover[data-state='closed'] {
  animation: docs-popover-out 120ms ease-in forwards;
}
@keyframes docs-popover-out {
  to {
    opacity: 0;
    transform: translateY(-4px);
  }
}
/* The arrow is a rotated square; the component sets position:absolute and the
   cross-axis offset, the per-side rules place it on the edge facing the anchor.
   The Positioner already clears the UA top-layer styles, so nothing else is
   needed for the shadow to show. */
.docs-popover__arrow {
  width: 9px;
  height: 9px;
  rotate: 45deg;
  background: #fff;
  border: 1px solid #e4e4e7;
}
.docs-popover__arrow[data-side='bottom'] {
  top: -5px;
  border-right: 0;
  border-bottom: 0;
}
.docs-popover__arrow[data-side='top'] {
  bottom: -5px;
  border-left: 0;
  border-top: 0;
}
.docs-popover__arrow[data-side='right'] {
  left: -5px;
  border-top: 0;
  border-right: 0;
}
.docs-popover__arrow[data-side='left'] {
  right: -5px;
  border-bottom: 0;
  border-left: 0;
}
@media (prefers-color-scheme: dark) {
  .docs-popover {
    border-color: #27272a;
    background: #18181b;
    color: #fafafa;
  }
  .docs-popover p {
    color: #a1a1aa;
  }
  .docs-popover__arrow {
    background: #18181b;
    border-color: #27272a;
  }
}
@media (prefers-reduced-motion: reduce) {
  .docs-popover {
    transition: none;
  }
  .docs-popover[data-state='closed'] {
    animation: none;
  }
}
```

```tsx
<Popover.Positioner className="z-50">
  <Popover.Popup className="w-64 rounded-[0.625rem] border border-zinc-200 bg-white p-4 text-zinc-900 shadow-xl opacity-100 translate-y-0 transition-[opacity,translate] duration-[120ms] ease-out starting:opacity-0 starting:-translate-y-1 data-[state=closed]:opacity-0 data-[state=closed]:-translate-y-1 motion-reduce:transition-none dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-100">
    <Popover.Title className="text-sm font-semibold">Settings</Popover.Title>
    <Popover.Description className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
      Adjust your preferences.
    </Popover.Description>
  </Popover.Popup>
</Popover.Positioner>
```

## API reference

Every part accepts a `render` prop for composition (see
[renderElement](/docs/components/render-element)) and forwards unknown props to the
element it renders. The Trigger, Positioner, Popup, Arrow, and Close also
expose `data-state="open" | "closed"` and pass state to a render function.

### Popover.Root

Provides open state, ids, refs, and placement config to the parts. Renders only
its children.

| Prop           | Type                               | Default    | Description                                        |
| -------------- | ---------------------------------- | ---------- | -------------------------------------------------- |
| `open`         | `boolean`                          | -          | Controlled open state. Pair with `onOpenChange`.   |
| `defaultOpen`  | `boolean`                          | `false`    | Initial open state when uncontrolled.              |
| `onOpenChange` | `(open: boolean) => void`          | -          | Called when the popover requests an open or close. |
| `side`         | `'top'\|'right'\|'bottom'\|'left'` | `'bottom'` | Preferred side of the anchor to place the popup.   |
| `align`        | `'start'\|'center'\|'end'`         | `'center'` | Alignment along that side.                         |
| `offset`       | `number`                           | `8`        | Gap in pixels between the anchor and the popup.    |
| `children`     | `ComponentChildren`                | -          | The trigger, optional anchor, and positioner.      |

### Popover.Trigger

Toggles the popover on click and anchors it (unless a `Popover.Anchor` is
present). Default element `<button type="button">`.

| Prop       | Type                                    | Default | Description                                                                   |
| ---------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `render`   | `RenderProp<{ open: boolean }>`         | -       | Compose or replace the element.                                               |
| `children` | `ComponentChildren`                     | -       | Trigger label.                                                                |
| `...props` | `JSX.HTMLAttributes<HTMLButtonElement>` | -       | Forwarded to the element; a passed `onClick` runs before the popover toggles. |

Sets `aria-haspopup="dialog"`, `aria-expanded`, `id`, `data-state`, and
`aria-controls` (only while open, since the popup is mounted on open).

### Popover.Anchor

Optional. Positions the popover relative to this element instead of the trigger,
for example to anchor a popover to a region while a separate button opens it.
Default element `<span>`.

| Prop       | Type                                  | Default | Description                     |
| ---------- | ------------------------------------- | ------- | ------------------------------- |
| `render`   | `RenderProp`                          | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                   | -       | The anchored content.           |
| `...props` | `JSX.HTMLAttributes<HTMLSpanElement>` | -       | Forwarded to the element.       |

### Popover.Positioner

The fixed-positioned wrapper that Floating UI drives. Renders nothing until the
popover is open (mount on open). Default element `<div>`.

| Prop       | Type                                       | Default | Description                                              |
| ---------- | ------------------------------------------ | ------- | -------------------------------------------------------- |
| `render`   | `RenderProp<{ side: Side; align: Align }>` | -       | Compose or replace the element.                          |
| `children` | `ComponentChildren`                        | -       | The popup (and optional arrow).                          |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`       | -       | Forwarded to the element. Style positioning via `class`. |

Sets `position: fixed` and the resolved `data-side` / `data-align`. The element
is promoted to the top layer via the Popover API, so it escapes ancestor clipping.

### Popover.Popup

The surface and focus target. Default element `<div>` with `role="dialog"`.

| Prop         | Type                                 | Default | Description                                       |
| ------------ | ------------------------------------ | ------- | ------------------------------------------------- |
| `render`     | `RenderProp<{ open: boolean }>`      | -       | Compose or replace the element.                   |
| `aria-label` | `string`                             | -       | Accessible name when there is no `Popover.Title`. |
| `children`   | `ComponentChildren`                  | -       | Arrow, title, description, body, and controls.    |
| `...props`   | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.                         |

Sets `role="dialog"`, `id`, `tabindex="-1"`, `data-state`, `aria-labelledby`
(the Title) or `aria-label`, and `aria-describedby` (only when a
`Popover.Description` is present). Registers the Escape / outside-press dismissal
and the focus move-in / return.

### Popover.Arrow

Optional pointer positioned from the Floating UI arrow data. Default element
`<div>`. Place it on the correct edge with CSS keyed on `data-side`.

| Prop       | Type                                 | Default | Description                     |
| ---------- | ------------------------------------ | ------- | ------------------------------- |
| `render`   | `RenderProp<{ side: Side }>`         | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                  | -       | Optional arrow content.         |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.       |

Sets `data-side` and `position: absolute` with the computed offset.

### Popover.Title

The popover's accessible name, wired to the popup's `aria-labelledby`. Default
element `<h2>`.

| Prop       | Type                                     | Default | Description                     |
| ---------- | ---------------------------------------- | ------- | ------------------------------- |
| `render`   | `RenderProp`                             | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                      | -       | Title text.                     |
| `...props` | `JSX.HTMLAttributes<HTMLHeadingElement>` | -       | Forwarded to the element.       |

### Popover.Description

Optional supporting text, wired to the popup's `aria-describedby` while it is
rendered. Default element `<p>`.

| Prop       | Type                                       | Default | Description                     |
| ---------- | ------------------------------------------ | ------- | ------------------------------- |
| `render`   | `RenderProp`                               | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                        | -       | Description text.               |
| `...props` | `JSX.HTMLAttributes<HTMLParagraphElement>` | -       | Forwarded to the element.       |

### Popover.Close

Closes the popover on click. Default element `<button type="button">`.

| Prop       | Type                                    | Default | Description                                                                  |
| ---------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `render`   | `RenderProp<{ open: boolean }>`         | -       | Compose or replace the element.                                              |
| `children` | `ComponentChildren`                     | -       | Button label.                                                                |
| `...props` | `JSX.HTMLAttributes<HTMLButtonElement>` | -       | Forwarded to the element; a passed `onClick` runs before the popover closes. |

### Primitives

`hono-preact-ui` exports the building blocks the parts use, for composing your
own components. Several have their own page with examples:
[usePosition](/docs/components/use-position),
[useDismiss](/docs/components/use-dismiss),
[useFocusReturn](/docs/components/use-focus-return),
[renderElement](/docs/components/render-element),
[useControllableState](/docs/components/use-controllable-state), and
[mergeRefs](/docs/components/merge-refs).

## Accessibility

The popover is a non-modal disclosure: the trigger carries `aria-haspopup`,
`aria-expanded`, and (while open) `aria-controls`. Give the popup an accessible
name with a `Popover.Title` (wired through `aria-labelledby`) or by passing
`aria-label` to `Popover.Popup`; a `Popover.Description` is wired through
`aria-describedby` when present.

- Focus moves into the popup when it opens (the first focusable element, or the
  popup itself) and returns to the trigger when it closes.
- Focus is **not** trapped: the popover is non-modal, so tabbing past the last
  control moves into the rest of the page, and the page stays interactive.
- Escape closes the popover; an outside pointer press closes it; nested overlays
  close innermost-first.
- The popup renders in the top layer via the Popover API, so an ancestor
  `transform`, `filter`, `contain`, or `will-change` does not clip it.


---

> Source: https://framework.sbesh.com/docs/components/tooltip

# Tooltip

A small label that appears on hover or keyboard focus. It follows WCAG 1.4.13:
the tooltip is hoverable (you can move the pointer onto it), dismissible with
Escape, and persistent (it stays until you leave or press Escape). Tooltips are
not shown for touch input, which cannot hover; do not put essential information
only in a tooltip. It ships unstyled: style it through the `data-state`,
`data-side`, and `data-align` contract.

## Demo

<Example code={tooltipCode}>

</Example>

The trigger opens after a short delay on hover and immediately on focus. Set
`openDelay` and `closeDelay` on `Tooltip.Root` to tune the timing.

Once open, the tooltip stays open while the pointer rests on the trigger, the
popup, or the safe corridor across the gap between them; it closes `closeDelay`
after the pointer leaves that region, and a move back inside cancels the close.
See [useSafeArea](/docs/components/use-safe-area).

## Styling

Parts expose `data-state="open" | "closed"`; the Positioner and Arrow also
expose `data-side` and `data-align`. Size, z-index, and entry animation go on the
Popup inside the Positioner. The demo above uses the styles below; copy a
starting point in either flavor:

```css
.docs-tooltip-positioner {
  z-index: 50;
}
.docs-tooltip {
  padding: 0.375rem 0.625rem;
  border-radius: 0.375rem;
  background: #18181b;
  color: #fafafa;
  font-size: 0.8125rem;
  box-shadow: 0 6px 18px rgb(0 0 0 / 0.18);
  opacity: 1;
  transition: opacity 100ms ease;
}
@starting-style {
  .docs-tooltip[data-state='open'] {
    opacity: 0;
  }
}
.docs-tooltip[data-state='closed'] {
  animation: docs-tooltip-out 100ms ease-in forwards;
}
@keyframes docs-tooltip-out {
  to {
    opacity: 0;
  }
}
/* A solid rotated square, same color as the chip, straddling the edge facing
   the anchor. */
.docs-tooltip__arrow {
  width: 8px;
  height: 8px;
  rotate: 45deg;
  background: #18181b;
}
.docs-tooltip__arrow[data-side='bottom'] {
  top: -4px;
}
.docs-tooltip__arrow[data-side='top'] {
  bottom: -4px;
}
.docs-tooltip__arrow[data-side='right'] {
  left: -4px;
}
.docs-tooltip__arrow[data-side='left'] {
  right: -4px;
}
@media (prefers-color-scheme: dark) {
  .docs-tooltip {
    background: #27272a;
    color: #fafafa;
  }
  .docs-tooltip__arrow {
    background: #27272a;
  }
}
@media (prefers-reduced-motion: reduce) {
  .docs-tooltip {
    transition: none;
  }
}
```

```tsx
<Tooltip.Positioner className="z-50">
  <Tooltip.Popup className="rounded-md bg-zinc-900 px-2.5 py-1.5 text-[13px] text-zinc-50 shadow-lg opacity-100 transition-opacity duration-100 ease-out starting:opacity-0 data-[state=closed]:opacity-0 motion-reduce:transition-none">
    Saved to your library
  </Tooltip.Popup>
</Tooltip.Positioner>
```

## API reference

Every part accepts a `render` prop for composition (see
[renderElement](/docs/components/render-element)) and forwards unknown props to the
element it renders. The Trigger, Positioner, Popup, and Arrow also expose
`data-state="open" | "closed"` and pass state to a render function.

### Tooltip.Root

Provides open state, ids, refs, timing, and placement config to the parts.
Renders only its children.

| Prop           | Type                               | Default    | Description                                                                              |
| -------------- | ---------------------------------- | ---------- | ---------------------------------------------------------------------------------------- |
| `open`         | `boolean`                          | -          | Controlled open state. Pair with `onOpenChange`.                                         |
| `defaultOpen`  | `boolean`                          | `false`    | Initial open state when uncontrolled.                                                    |
| `onOpenChange` | `(open: boolean) => void`          | -          | Called when the tooltip requests an open or close.                                       |
| `openDelay`    | `number`                           | `600`      | Open delay in ms after the pointer enters the trigger.                                   |
| `closeDelay`   | `number`                           | `300`      | Grace in ms before closing once the pointer leaves the trigger, popup, or safe corridor. |
| `side`         | `'top'\|'right'\|'bottom'\|'left'` | `'top'`    | Preferred side of the anchor to place the popup.                                         |
| `align`        | `'start'\|'center'\|'end'`         | `'center'` | Alignment along that side.                                                               |
| `offset`       | `number`                           | `8`        | Gap in pixels between the anchor and the popup.                                          |
| `children`     | `ComponentChildren`                | -          | The trigger and positioner.                                                              |

### Tooltip.Trigger

The element the tooltip describes. Binds hover and focus, wires
`aria-describedby`, and anchors positioning. Default element
`<button type="button">`; use `render` to attach it to your own control.

| Prop       | Type                                    | Default | Description                                           |
| ---------- | --------------------------------------- | ------- | ----------------------------------------------------- |
| `render`   | `RenderProp<{ open: boolean }>`         | -       | Compose or replace the element.                       |
| `children` | `ComponentChildren`                     | -       | Trigger content.                                      |
| `...props` | `JSX.HTMLAttributes<HTMLButtonElement>` | -       | Forwarded; passed pointer / focus handlers run first. |

Sets `data-state` and `aria-describedby` (the popup id, only while open). Opens
after `openDelay` on a mouse `pointerenter`, immediately on `focus`; once open, it
closes `closeDelay` after the pointer leaves the trigger, popup, and safe
corridor, immediately on `blur`, or on Escape. A touch pointer does not open it.

### Tooltip.Positioner

The fixed-positioned wrapper that Floating UI drives. Renders nothing until the
tooltip is open (mount on open). Default element `<div>`.

| Prop       | Type                                       | Default | Description                                              |
| ---------- | ------------------------------------------ | ------- | -------------------------------------------------------- |
| `render`   | `RenderProp<{ side: Side; align: Align }>` | -       | Compose or replace the element.                          |
| `children` | `ComponentChildren`                        | -       | The popup (and optional arrow).                          |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`       | -       | Forwarded to the element. Style positioning via `class`. |

Sets `position: fixed` and the resolved `data-side` / `data-align`. The element
is promoted to the top layer via the Popover API, so it escapes ancestor clipping.

### Tooltip.Popup

The tooltip surface. Default element `<div>` with `role="tooltip"`.

| Prop       | Type                                 | Default | Description                           |
| ---------- | ------------------------------------ | ------- | ------------------------------------- |
| `render`   | `RenderProp<{ open: boolean }>`      | -       | Compose or replace the element.       |
| `children` | `ComponentChildren`                  | -       | Tooltip content (and optional arrow). |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.             |

Sets `role="tooltip"`, `id`, and `data-state`. Hoverable: moving the pointer
onto the popup cancels the close so the content stays readable.

### Tooltip.Arrow

Optional pointer positioned from the Floating UI arrow data. Default element
`<div>`. Place it on the correct edge with CSS keyed on `data-side`.

| Prop       | Type                                 | Default | Description                     |
| ---------- | ------------------------------------ | ------- | ------------------------------- |
| `render`   | `RenderProp<{ side: Side }>`         | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                  | -       | Optional arrow content.         |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.       |

Sets `data-side` and `position: absolute` with the computed offset.

### Primitives

`hono-preact-ui` exports the building blocks the parts use, for composing your
own components. Several have their own page with examples:
[usePosition](/docs/components/use-position),
[useDismiss](/docs/components/use-dismiss),
[renderElement](/docs/components/render-element),
[useControllableState](/docs/components/use-controllable-state),
[mergeRefs](/docs/components/merge-refs), and
[useSafeArea](/docs/components/use-safe-area).

## Accessibility

The tooltip is wired to its trigger through `aria-describedby` while open, so a
screen reader announces the content when the trigger receives focus. The popup
has `role="tooltip"`.

- Both hover and keyboard focus open the tooltip, so it is reachable without a
  pointer.
- It is **hoverable**: moving the pointer from the trigger onto the popup keeps
  it open (WCAG 1.4.13), so content that needs to be read or selected does not
  vanish.
- It is **dismissible** with Escape and **persistent**: while the pointer rests on
  the trigger, the popup, or the safe corridor between them it never auto-hides on
  a timer; it closes once focus or the pointer leaves.
- Touch input cannot hover, so the tooltip is suppressed there. Do not place
  information that is only available through a tooltip; keep it supplementary.


---

> Source: https://framework.sbesh.com/docs/components/menu

# Menu

A button-triggered dropdown of commands: a list of actions, toggles, and
single-select choices that opens from a trigger and closes when you pick
something or dismiss it. Positioning runs on Floating UI; the popup renders in
place and promotes to the browser top layer using the Popover API.
It ships unstyled: style it through the `data-state`, `data-highlighted`,
`data-disabled`, `data-side`, and `data-align` contract.

The popup uses the `role="menu"` pattern, which is for application and command
menus (a list of actions to perform), not for site navigation. For a set of
links between pages, use a plain list of anchors so each link is a real `<a>`
in the tab order; reserve Menu for commands.

## Demo

<Example code={menuCode}>

</Example>

## Usage

`Menu.Item` activates and closes the menu on click or Enter; call
`event.preventDefault()` in its `onSelect` to keep the menu open after a choice.
`Menu.CheckboxItem` and `Menu.RadioItem` carry their own checked state (each
takes a controlled `checked`/`value` pair or an uncontrolled `defaultChecked`/
`defaultValue`). A `Menu.SubmenuRoot` nests another menu off a trigger row.

## Styling

Parts expose `data-state` (`open`/`closed` on the popup and submenu trigger).
Checkbox and radio items expose `data-checked` (present when checked). Items expose
`data-highlighted` while active and `data-disabled` when disabled; the
Positioner and Arrow expose `data-side` and `data-align`. The Positioner is the
fixed-positioned wrapper, so size, z-index, and the entry animation go on the
Popup inside it. The demo above uses the styles below; copy a starting point in
either flavor:

```css
.docs-menu-positioner {
  z-index: 50;
}
.docs-menu {
  box-sizing: border-box;
  min-width: 12rem;
  padding: 0.25rem;
  border: 1px solid #e4e4e7;
  border-radius: 0.625rem;
  background: #fff;
  color: #18181b;
  box-shadow:
    0 10px 15px -3px rgb(0 0 0 / 0.25),
    0 4px 6px -4px rgb(0 0 0 / 0.25);
  outline: none;
  opacity: 1;
  transform: translateY(0);
  transition:
    opacity 120ms ease,
    transform 120ms ease;
}
@starting-style {
  .docs-menu[data-state='open'] {
    opacity: 0;
    transform: translateY(-4px);
  }
}
.docs-menu[data-state='closed'] {
  opacity: 0;
  transform: translateY(-4px);
}
/* Items are roving-tabindex rows; the active row is highlighted via the
   data-attribute the component sets on hover and arrow navigation. */
.docs-menu__item {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  font-size: 0.875rem;
  padding: 0.4rem 0.6rem;
  border-radius: 0.375rem;
  cursor: pointer;
  outline: none;
}
.docs-menu__item[data-highlighted] {
  background: #18181b;
  color: #fafafa;
}
.docs-menu__item[data-disabled] {
  color: #a1a1aa;
  pointer-events: none;
}
.docs-menu__separator {
  height: 1px;
  margin: 0.25rem 0.3rem;
  background: #e4e4e7;
}
.docs-menu__label {
  padding: 0.25rem 0.6rem;
  font-size: 0.75rem;
  font-weight: 600;
  text-transform: uppercase;
  letter-spacing: 0.04em;
  color: #71717a;
}
@media (prefers-color-scheme: dark) {
  .docs-menu {
    border-color: #27272a;
    background: #18181b;
    color: #fafafa;
  }
  .docs-menu__item[data-highlighted] {
    background: #fafafa;
    color: #18181b;
  }
  .docs-menu__separator {
    background: #27272a;
  }
}
@media (prefers-reduced-motion: reduce) {
  .docs-menu {
    transition: none;
  }
}
```

```tsx
<Menu.Positioner className="z-50">
  <Menu.Popup className="min-w-48 rounded-[0.625rem] border border-zinc-200 bg-white p-1 text-zinc-900 shadow-xl outline-none opacity-100 translate-y-0 transition-[opacity,translate] duration-[120ms] ease-out starting:opacity-0 starting:-translate-y-1 data-[state=closed]:opacity-0 data-[state=closed]:-translate-y-1 motion-reduce:transition-none dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-100">
    <Menu.Item className="flex items-center gap-2 rounded-md px-2.5 py-1.5 text-sm outline-none cursor-pointer data-[highlighted]:bg-zinc-900 data-[highlighted]:text-zinc-50 data-[disabled]:pointer-events-none data-[disabled]:text-zinc-400 dark:data-[highlighted]:bg-zinc-50 dark:data-[highlighted]:text-zinc-900">
      New file
    </Menu.Item>
    <Menu.Separator className="my-1 mx-1.5 h-px bg-zinc-200 dark:bg-zinc-800" />
    <Menu.GroupLabel className="px-2.5 py-1 text-xs font-semibold uppercase tracking-wide text-zinc-500">
      Density
    </Menu.GroupLabel>
  </Menu.Popup>
</Menu.Positioner>
```

## Keyboard

| Keys                          | When                 | Action                                                                 |
| ----------------------------- | -------------------- | ---------------------------------------------------------------------- |
| `Enter` / `Space` / `↓` / `↑` | Trigger, closed      | Open the menu. `↓` focuses the first item, `↑` the last.               |
| `↓` / `↑`                     | Menu open            | Move to the next / previous item, wrapping at the ends.                |
| `Home` / `End`                | Menu open            | Move to the first / last item.                                         |
| _printable characters_        | Menu open            | Typeahead: focus the next item whose label starts with the typed text. |
| `Enter` / `Space`             | On an item           | Activate the highlighted item.                                         |
| `Escape`                      | Menu open            | Close the menu and return focus to the trigger.                        |
| `Tab`                         | Menu open            | Close the menu, then move focus to the next element.                   |
| `→`                           | On a submenu trigger | Open the submenu and focus its first item.                             |
| `←`                           | In a submenu         | Close the submenu and return focus to its trigger.                     |
| `Escape`                      | In a submenu         | Close the innermost open menu first.                                   |

Set `loop={false}` on `Menu.Root` to stop arrow navigation from wrapping, and
`typeahead={false}` to disable type-to-focus.

## Data attributes

| Attribute          | On                                            | Values                                            |
| ------------------ | --------------------------------------------- | ------------------------------------------------- |
| `data-state`       | Trigger, Popup, SubmenuTrigger                | `open` \| `closed`                                |
| `data-checked`     | CheckboxItem, RadioItem                       | present when checked                              |
| `data-highlighted` | Item, CheckboxItem, RadioItem, SubmenuTrigger | present while the item is the active row          |
| `data-disabled`    | Item, CheckboxItem, RadioItem                 | present when the item is disabled                 |
| `data-side`        | Positioner, Arrow                             | `top` \| `right` \| `bottom` \| `left` (resolved) |
| `data-align`       | Positioner                                    | `start` \| `center` \| `end` (resolved)           |

## API reference

Every part accepts a `render` prop for composition (see
[renderElement](/docs/components/render-element)) and forwards unknown props to the
element it renders. Items pass their `{ disabled, highlighted }` (plus `checked`
on checkbox / radio items) state to a render function.

### Menu.Root

Provides open state, ids, refs, navigation config, and placement to the parts.
Renders only its children.

| Prop           | Type                               | Default    | Description                                       |
| -------------- | ---------------------------------- | ---------- | ------------------------------------------------- |
| `open`         | `boolean`                          | -          | Controlled open state. Pair with `onOpenChange`.  |
| `defaultOpen`  | `boolean`                          | `false`    | Initial open state when uncontrolled.             |
| `onOpenChange` | `(open: boolean) => void`          | -          | Called when the menu requests an open or close.   |
| `side`         | `'top'\|'right'\|'bottom'\|'left'` | `'bottom'` | Preferred side of the trigger to place the popup. |
| `align`        | `'start'\|'center'\|'end'`         | `'start'`  | Alignment along that side.                        |
| `offset`       | `number`                           | `8`        | Gap in pixels between the trigger and the popup.  |
| `loop`         | `boolean`                          | `true`     | Wrap arrow navigation at the first / last item.   |
| `typeahead`    | `boolean`                          | `true`     | Focus items by typing their leading characters.   |
| `children`     | `ComponentChildren`                | -          | The trigger and positioner.                       |

### Menu.Trigger

Toggles the menu on click and anchors it. Default element
`<button type="button">`.

| Prop       | Type                                    | Default | Description                                                                |
| ---------- | --------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `render`   | `RenderProp<{ open: boolean }>`         | -       | Compose or replace the element.                                            |
| `children` | `ComponentChildren`                     | -       | Trigger label.                                                             |
| `...props` | `JSX.HTMLAttributes<HTMLButtonElement>` | -       | Forwarded to the element; a passed `onClick` runs before the menu toggles. |

Sets `aria-haspopup="menu"`, `aria-expanded`, `id`, `data-state`, and
`aria-controls` (only while open, since the popup is mounted on open).

### Menu.Positioner

The fixed-positioned wrapper that Floating UI drives. Renders nothing until the
menu is open (mount on open). Default element `<div>`.

| Prop       | Type                                       | Default | Description                                              |
| ---------- | ------------------------------------------ | ------- | -------------------------------------------------------- |
| `render`   | `RenderProp<{ side: Side; align: Align }>` | -       | Compose or replace the element.                          |
| `children` | `ComponentChildren`                        | -       | The popup (and optional arrow).                          |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`       | -       | Forwarded to the element. Style positioning via `class`. |

Sets `position: fixed` and the resolved `data-side` / `data-align`. The element
is promoted to the top layer via the Popover API, so it escapes ancestor clipping.

### Menu.Popup

The menu surface and navigation root. Default element `<div>` with
`role="menu"`.

| Prop         | Type                                 | Default | Description                                       |
| ------------ | ------------------------------------ | ------- | ------------------------------------------------- |
| `render`     | `RenderProp<{ open: boolean }>`      | -       | Compose or replace the element.                   |
| `aria-label` | `string`                             | -       | Accessible name. Defaults to the trigger's label. |
| `children`   | `ComponentChildren`                  | -       | Items, separators, groups, and submenus.          |
| `...props`   | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.                         |

Sets `role="menu"`, `id`, `tabindex="-1"`, `aria-orientation="vertical"`,
`data-state`, and `aria-labelledby` (the trigger) or `aria-label`. Owns the
keyboard navigation, typeahead, Escape / outside-press dismissal, and focus
move-in / return.

### Menu.Item

A command row. Default element `<div>` with `role="menuitem"`.

| Prop       | Type                                                      | Default | Description                                                                |
| ---------- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `render`   | `RenderProp<{ disabled: boolean; highlighted: boolean }>` | -       | Compose or replace the element.                                            |
| `disabled` | `boolean`                                                 | `false` | Skip the item in navigation and ignore activation.                         |
| `onSelect` | `(event: Event) => void`                                  | -       | Called on activation. Call `event.preventDefault()` to keep the menu open. |
| `children` | `ComponentChildren`                                       | -       | Item content.                                                              |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`                      | -       | Forwarded to the element.                                                  |

### Menu.CheckboxItem

A toggle row that holds its own checked state. Default element `<div>` with
`role="menuitemcheckbox"`.

| Prop              | Type                                                                        | Default | Description                                                   |
| ----------------- | --------------------------------------------------------------------------- | ------- | ------------------------------------------------------------- |
| `render`          | `RenderProp<{ checked: boolean; disabled: boolean; highlighted: boolean }>` | -       | Compose or replace the element.                               |
| `checked`         | `boolean`                                                                   | -       | Controlled checked state. Pair with `onCheckedChange`.        |
| `defaultChecked`  | `boolean`                                                                   | `false` | Initial checked state when uncontrolled.                      |
| `onCheckedChange` | `(checked: boolean) => void`                                                | -       | Called when the checked state changes.                        |
| `disabled`        | `boolean`                                                                   | `false` | Skip the item and ignore activation.                          |
| `onSelect`        | `(event: Event) => void`                                                    | -       | Called on activation; `preventDefault()` keeps the menu open. |
| `children`        | `ComponentChildren`                                                         | -       | Item content (render your own check indicator).               |
| `...props`        | `JSX.HTMLAttributes<HTMLDivElement>`                                        | -       | Forwarded to the element.                                     |

Sets `aria-checked` and `data-checked` (present when checked).

### Menu.RadioGroup

Single-select context for the radio items inside it. Generic over the value
type (`Menu.RadioGroup<V extends string>`); `V` is inferred from `value` /
`defaultValue` and defaults to `string`. Default element `<div>` with
`role="group"`.

| Prop            | Type                                 | Default | Description                                           |
| --------------- | ------------------------------------ | ------- | ----------------------------------------------------- |
| `render`        | `RenderProp`                         | -       | Compose or replace the element.                       |
| `value`         | `V`                                  | -       | Controlled selected value. Pair with `onValueChange`. |
| `defaultValue`  | `V`                                  | -       | Initial selected value when uncontrolled.             |
| `onValueChange` | `(value: V) => void`                 | -       | Called when the selection changes.                    |
| `children`      | `ComponentChildren`                  | -       | The radio items.                                      |
| `...props`      | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.                             |

### Menu.RadioItem

A choice within a `Menu.RadioGroup`. Default element `<div>` with
`role="menuitemradio"`.

| Prop       | Type                                                                        | Default  | Description                                                   |
| ---------- | --------------------------------------------------------------------------- | -------- | ------------------------------------------------------------- |
| `value`    | `string`                                                                    | required | Identifies the item within its group.                         |
| `render`   | `RenderProp<{ checked: boolean; disabled: boolean; highlighted: boolean }>` | -        | Compose or replace the element.                               |
| `disabled` | `boolean`                                                                   | `false`  | Skip the item and ignore activation.                          |
| `onSelect` | `(event: Event) => void`                                                    | -        | Called on activation; `preventDefault()` keeps the menu open. |
| `children` | `ComponentChildren`                                                         | -        | Item content (render your own selected indicator).            |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`                                        | -        | Forwarded to the element.                                     |

Sets `aria-checked` and `data-checked` (present when checked).

### Menu.Separator

A horizontal divider between groups of items. Default element `<div>` with
`role="separator"`.

| Prop       | Type                                 | Default | Description               |
| ---------- | ------------------------------------ | ------- | ------------------------- |
| `render`   | `RenderProp`                         | -       | Compose or replace it.    |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element. |

### Menu.Group

Wraps related items and labels them with a `Menu.GroupLabel`. Default element
`<div>` with `role="group"`.

| Prop       | Type                                 | Default | Description                        |
| ---------- | ------------------------------------ | ------- | ---------------------------------- |
| `render`   | `RenderProp`                         | -       | Compose or replace it.             |
| `children` | `ComponentChildren`                  | -       | A `Menu.GroupLabel` and the items. |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.          |

Wires its label to `aria-labelledby`.

### Menu.GroupLabel

The accessible name for a `Menu.Group`. Presentational, not focusable. Default
element `<div>`.

| Prop       | Type                                 | Default | Description               |
| ---------- | ------------------------------------ | ------- | ------------------------- |
| `render`   | `RenderProp`                         | -       | Compose or replace it.    |
| `children` | `ComponentChildren`                  | -       | Label text.               |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element. |

### Menu.Arrow

Optional pointer positioned from the Floating UI arrow data. Default element
`<div>`. Place it on the correct edge with CSS keyed on `data-side`.

| Prop       | Type                                 | Default | Description                     |
| ---------- | ------------------------------------ | ------- | ------------------------------- |
| `render`   | `RenderProp<{ side: Side }>`         | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                  | -       | Optional arrow content.         |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.       |

Sets `data-side` and `position: absolute` with the computed offset.

### Menu.SubmenuRoot

Provides a nested menu's open state and placement off a trigger row. Must be
placed inside a `Menu.Popup`. Renders only its children.

| Prop           | Type                               | Default   | Description                                                |
| -------------- | ---------------------------------- | --------- | ---------------------------------------------------------- |
| `open`         | `boolean`                          | -         | Controlled open state. Pair with `onOpenChange`.           |
| `defaultOpen`  | `boolean`                          | `false`   | Initial open state when uncontrolled.                      |
| `onOpenChange` | `(open: boolean) => void`          | -         | Called when the submenu requests an open or close.         |
| `side`         | `'top'\|'right'\|'bottom'\|'left'` | `'right'` | Preferred side of the trigger to place the submenu.        |
| `align`        | `'start'\|'center'\|'end'`         | `'start'` | Alignment along that side.                                 |
| `offset`       | `number`                           | `0`       | Gap in pixels between the trigger and the submenu.         |
| `openDelay`    | `number`                           | `100`     | Hover open delay in ms.                                    |
| `closeDelay`   | `number`                           | `300`     | Safe-corridor grace in ms before closing on pointer leave. |
| `children`     | `ComponentChildren`                | -         | The submenu trigger and positioner.                        |

### Menu.SubmenuTrigger

The row that opens the submenu. It is itself a `menuitem` in the parent menu.
Default element `<div>` with `role="menuitem"`.

| Prop       | Type                                                  | Default | Description                         |
| ---------- | ----------------------------------------------------- | ------- | ----------------------------------- |
| `render`   | `RenderProp<{ open: boolean; highlighted: boolean }>` | -       | Compose or replace the element.     |
| `disabled` | `boolean`                                             | `false` | Skip the row and ignore activation. |
| `children` | `ComponentChildren`                                   | -       | Row content.                        |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`                  | -       | Forwarded to the element.           |

Sets `aria-haspopup="menu"`, `aria-expanded`, and (while open) `aria-controls`.
Opens on hover (after `openDelay`), `→`, `Enter`, `Space`, or click; the safe
corridor keeps it open while the pointer travels toward the submenu.

### Menu.SubmenuPositioner

The submenu's fixed-positioned wrapper. Same surface as `Menu.Positioner`,
bound to the submenu. Default element `<div>`.

| Prop       | Type                                       | Default | Description                                              |
| ---------- | ------------------------------------------ | ------- | -------------------------------------------------------- |
| `render`   | `RenderProp<{ side: Side; align: Align }>` | -       | Compose or replace the element.                          |
| `children` | `ComponentChildren`                        | -       | The submenu popup.                                       |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`       | -       | Forwarded to the element. Style positioning via `class`. |

### Menu.SubmenuPopup

The submenu surface. Same surface as `Menu.Popup`, with `←` wired to close the
submenu and return focus to its trigger. Default element `<div>` with
`role="menu"`.

| Prop         | Type                                 | Default | Description                                       |
| ------------ | ------------------------------------ | ------- | ------------------------------------------------- |
| `render`     | `RenderProp<{ open: boolean }>`      | -       | Compose or replace the element.                   |
| `aria-label` | `string`                             | -       | Accessible name. Defaults to the submenu trigger. |
| `children`   | `ComponentChildren`                  | -       | The nested items.                                 |
| `...props`   | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.                         |

### Primitives

`hono-preact-ui` exports the building blocks the parts use, for composing your
own components. Several have their own page with examples:
[usePosition](/docs/components/use-position),
[useDismiss](/docs/components/use-dismiss),
[useFocusReturn](/docs/components/use-focus-return),
[useSafeArea](/docs/components/use-safe-area),
[renderElement](/docs/components/render-element),
[useControllableState](/docs/components/use-controllable-state), and
[mergeRefs](/docs/components/merge-refs).

## Accessibility

The menu follows the ARIA menu-button pattern. The trigger carries
`aria-haspopup="menu"`, `aria-expanded`, and (while open) `aria-controls`; the
popup is a `role="menu"` with `aria-orientation="vertical"`, named by the
trigger or an explicit `aria-label`. Items are `menuitem`, `menuitemcheckbox`,
and `menuitemradio`.

- Both Enter / Space and the arrow keys open the menu from the trigger, so it is
  reachable without a pointer.
- Focus moves into the menu when it opens (the first or last item) and returns to
  the trigger when it closes. The items use a roving tabindex, so only the active
  item is in the tab order.
- Escape closes the menu, an outside pointer press closes it, and nested submenus
  close innermost-first.
- Use the `role="menu"` pattern only for commands. For navigation between pages,
  render a list of links instead, so each destination is a real `<a>`.


---

> Source: https://framework.sbesh.com/docs/components/context-menu

# Context Menu

A menu opened by a right-click (the `contextmenu` event) on a region rather than
by a button. The trigger is the area you right-click; the menu opens at the
pointer instead of anchored to an element, suppressing the browser's native
context menu in that region. Everything below the trigger is the same machinery
as the [Menu](/docs/components/menu) component: items, separators, checkbox and
radio items, groups, and submenus all behave identically. It ships unstyled:
style it through the `data-state`, `data-highlighted`, `data-disabled`,
`data-side`, and `data-align` contract.

## Demo

<Example code={contextMenuCode}>

</Example>

## Usage

`ContextMenu.Trigger` wraps the right-clickable region; it captures the pointer
position and opens the menu there. The other parts (`Positioner`, `Popup`,
`Item`, `Separator`, `CheckboxItem`, `RadioGroup`, `RadioItem`, `Group`,
`GroupLabel`, `Arrow`, and the `Submenu*` parts) are the same components the Menu
component uses, re-exported under the `ContextMenu` namespace so an example never
mixes the two. They are documented in the API reference below, and the keyboard
map and navigation behave exactly as in [Menu](/docs/components/menu).

### Touch

There is no long-press fallback on touch in this version. The menu opens on the
`contextmenu` event, which is reliable for mouse and trackpad but not raised by
a touch long-press on every browser. Where right-click reach matters on touch,
pair the right-click region with a visible button that toggles the same menu
(for example a `Menu` with the same items), so the actions stay reachable
without a pointer that can right-click.

## Styling

Parts expose `data-state` (`open`/`closed` on the trigger region and popup).
Checkbox and radio items expose `data-checked` (present when checked). Items expose
`data-highlighted` while active and `data-disabled` when disabled; the
Positioner and Arrow expose `data-side` and `data-align`. The popup is styled
exactly like a `Menu.Popup`; the demo above uses the styles below:

```css
.docs-context-zone {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 7rem;
  padding: 1.5rem;
  border: 1px dashed #e4e4e7;
  border-radius: 0.625rem;
  background: #fafafa;
  color: #71717a;
  user-select: none;
}
.docs-context-zone[data-state='open'] {
  border-color: #18181b;
  color: #18181b;
}
.docs-menu-positioner {
  z-index: 50;
}
.docs-menu {
  box-sizing: border-box;
  min-width: 12rem;
  padding: 0.25rem;
  border: 1px solid #e4e4e7;
  border-radius: 0.625rem;
  background: #fff;
  color: #18181b;
  box-shadow:
    0 10px 15px -3px rgb(0 0 0 / 0.25),
    0 4px 6px -4px rgb(0 0 0 / 0.25);
  outline: none;
  opacity: 1;
  transform: translateY(0);
  transition:
    opacity 120ms ease,
    transform 120ms ease;
}
@starting-style {
  .docs-menu[data-state='open'] {
    opacity: 0;
    transform: translateY(-4px);
  }
}
.docs-menu[data-state='closed'] {
  opacity: 0;
  transform: translateY(-4px);
}
.docs-menu__item {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  font-size: 0.875rem;
  padding: 0.4rem 0.6rem;
  border-radius: 0.375rem;
  cursor: pointer;
  outline: none;
}
.docs-menu__item[data-highlighted] {
  background: #18181b;
  color: #fafafa;
}
.docs-menu__item[data-disabled] {
  color: #a1a1aa;
  pointer-events: none;
}
.docs-menu__separator {
  height: 1px;
  margin: 0.25rem 0.3rem;
  background: #e4e4e7;
}
@media (prefers-color-scheme: dark) {
  .docs-context-zone {
    border-color: #27272a;
    background: #18181b;
  }
  .docs-context-zone[data-state='open'] {
    border-color: #fafafa;
    color: #fafafa;
  }
  .docs-menu {
    border-color: #27272a;
    background: #18181b;
    color: #fafafa;
  }
  .docs-menu__item[data-highlighted] {
    background: #fafafa;
    color: #18181b;
  }
  .docs-menu__separator {
    background: #27272a;
  }
}
@media (prefers-reduced-motion: reduce) {
  .docs-menu {
    transition: none;
  }
}
```

```tsx
<ContextMenu.Trigger className="flex min-h-28 items-center justify-center rounded-[0.625rem] border border-dashed border-zinc-200 bg-zinc-50 p-6 text-zinc-500 select-none data-[state=open]:border-zinc-900 data-[state=open]:text-zinc-900 dark:border-zinc-800 dark:bg-zinc-900 dark:data-[state=open]:border-zinc-50 dark:data-[state=open]:text-zinc-50">
  Right-click here
</ContextMenu.Trigger>
<ContextMenu.Positioner className="z-50">
  <ContextMenu.Popup className="min-w-48 rounded-[0.625rem] border border-zinc-200 bg-white p-1 text-zinc-900 shadow-xl outline-none opacity-100 translate-y-0 transition-[opacity,translate] duration-[120ms] ease-out starting:opacity-0 starting:-translate-y-1 data-[state=closed]:opacity-0 data-[state=closed]:-translate-y-1 motion-reduce:transition-none dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-100">
    <ContextMenu.Item className="flex items-center gap-2 rounded-md px-2.5 py-1.5 text-sm outline-none cursor-pointer data-[highlighted]:bg-zinc-900 data-[highlighted]:text-zinc-50 data-[disabled]:pointer-events-none data-[disabled]:text-zinc-400 dark:data-[highlighted]:bg-zinc-50 dark:data-[highlighted]:text-zinc-900">
      Copy
    </ContextMenu.Item>
  </ContextMenu.Popup>
</ContextMenu.Positioner>
```

## API reference

`ContextMenu.Root` and `ContextMenu.Trigger` are unique to this component; the
rest are the same components as their `Menu.*` counterparts, re-exported under
the `ContextMenu` namespace and documented below. Every part accepts a `render`
prop for composition (see [renderElement](/docs/components/render-element)) and forwards
unknown props to the element it renders. Items pass their
`{ disabled, highlighted }` state (plus `checked` on checkbox and radio items)
to a render function.

### ContextMenu.Root

Provides open state, ids, refs, navigation config, and placement to the parts.
Opens at the captured pointer position via a virtual anchor. Renders only its
children.

| Prop           | Type                               | Default    | Description                                       |
| -------------- | ---------------------------------- | ---------- | ------------------------------------------------- |
| `open`         | `boolean`                          | -          | Controlled open state. Pair with `onOpenChange`.  |
| `defaultOpen`  | `boolean`                          | `false`    | Initial open state when uncontrolled.             |
| `onOpenChange` | `(open: boolean) => void`          | -          | Called when the menu requests an open or close.   |
| `side`         | `'top'\|'right'\|'bottom'\|'left'` | `'bottom'` | Preferred side of the pointer to place the popup. |
| `align`        | `'start'\|'center'\|'end'`         | `'start'`  | Alignment along that side.                        |
| `offset`       | `number`                           | `0`        | Gap in pixels between the pointer and the popup.  |
| `loop`         | `boolean`                          | `true`     | Wrap arrow navigation at the first / last item.   |
| `typeahead`    | `boolean`                          | `true`     | Focus items by typing their leading characters.   |
| `children`     | `ComponentChildren`                | -          | The trigger and positioner.                       |

### ContextMenu.Trigger

The right-clickable region. On `contextmenu` it suppresses the native menu and
opens the popup at the pointer. Default element `<div>`.

| Prop       | Type                                 | Default | Description                                                                    |
| ---------- | ------------------------------------ | ------- | ------------------------------------------------------------------------------ |
| `render`   | `RenderProp`                         | -       | Compose or replace the element.                                                |
| `children` | `ComponentChildren`                  | -       | The right-clickable content.                                                   |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element; a passed `onContextMenu` runs before the menu opens. |

Sets `data-state="open" | "closed"`. Unlike `Menu.Trigger` it is not a button
and carries no `aria-haspopup`: the menu is reached by right-click, not by
activating the region.

### ContextMenu.Positioner

The fixed-positioned wrapper that Floating UI drives. Renders nothing until the
menu is open (mount on open). Default element `<div>`.

| Prop       | Type                                       | Default | Description                                              |
| ---------- | ------------------------------------------ | ------- | -------------------------------------------------------- |
| `render`   | `RenderProp<{ side: Side; align: Align }>` | -       | Compose or replace the element.                          |
| `children` | `ComponentChildren`                        | -       | The popup (and optional arrow).                          |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`       | -       | Forwarded to the element. Style positioning via `class`. |

Sets `position: fixed` and the resolved `data-side` / `data-align`. The element
is promoted to the top layer via the Popover API, so it escapes ancestor clipping.

### ContextMenu.Popup

The menu surface and navigation root. Default element `<div>` with
`role="menu"`.

| Prop         | Type                                 | Default | Description                                                            |
| ------------ | ------------------------------------ | ------- | ---------------------------------------------------------------------- |
| `render`     | `RenderProp<{ open: boolean }>`      | -       | Compose or replace the element.                                        |
| `aria-label` | `string`                             | -       | Accessible name. Set one, since there is no named trigger to label it. |
| `children`   | `ComponentChildren`                  | -       | Items, separators, groups, and submenus.                               |
| `...props`   | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.                                              |

Sets `role="menu"`, `id`, `tabindex="-1"`, `aria-orientation="vertical"`, and
`data-state`. Owns the keyboard navigation, typeahead, Escape / outside-press
dismissal, and focus move-in / return.

### ContextMenu.Item

A command row. Default element `<div>` with `role="menuitem"`.

| Prop       | Type                                                      | Default | Description                                                                |
| ---------- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `render`   | `RenderProp<{ disabled: boolean; highlighted: boolean }>` | -       | Compose or replace the element.                                            |
| `disabled` | `boolean`                                                 | `false` | Skip the item in navigation and ignore activation.                         |
| `onSelect` | `(event: Event) => void`                                  | -       | Called on activation. Call `event.preventDefault()` to keep the menu open. |
| `children` | `ComponentChildren`                                       | -       | Item content.                                                              |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`                      | -       | Forwarded to the element.                                                  |

### ContextMenu.CheckboxItem

A toggle row that holds its own checked state. Default element `<div>` with
`role="menuitemcheckbox"`.

| Prop              | Type                                                                        | Default | Description                                                   |
| ----------------- | --------------------------------------------------------------------------- | ------- | ------------------------------------------------------------- |
| `render`          | `RenderProp<{ checked: boolean; disabled: boolean; highlighted: boolean }>` | -       | Compose or replace the element.                               |
| `checked`         | `boolean`                                                                   | -       | Controlled checked state. Pair with `onCheckedChange`.        |
| `defaultChecked`  | `boolean`                                                                   | `false` | Initial checked state when uncontrolled.                      |
| `onCheckedChange` | `(checked: boolean) => void`                                                | -       | Called when the checked state changes.                        |
| `disabled`        | `boolean`                                                                   | `false` | Skip the item and ignore activation.                          |
| `onSelect`        | `(event: Event) => void`                                                    | -       | Called on activation; `preventDefault()` keeps the menu open. |
| `children`        | `ComponentChildren`                                                         | -       | Item content (render your own check indicator).               |
| `...props`        | `JSX.HTMLAttributes<HTMLDivElement>`                                        | -       | Forwarded to the element.                                     |

Sets `aria-checked` and `data-checked` (present when checked).

### ContextMenu.RadioGroup

Single-select context for the radio items inside it. Generic over the value
type (`ContextMenu.RadioGroup<V extends string>`); `V` is inferred from
`value` / `defaultValue` and defaults to `string`. Default element `<div>`
with `role="group"`.

| Prop            | Type                                 | Default | Description                                           |
| --------------- | ------------------------------------ | ------- | ----------------------------------------------------- |
| `render`        | `RenderProp`                         | -       | Compose or replace the element.                       |
| `value`         | `V`                                  | -       | Controlled selected value. Pair with `onValueChange`. |
| `defaultValue`  | `V`                                  | -       | Initial selected value when uncontrolled.             |
| `onValueChange` | `(value: V) => void`                 | -       | Called when the selection changes.                    |
| `children`      | `ComponentChildren`                  | -       | The radio items.                                      |
| `...props`      | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.                             |

### ContextMenu.RadioItem

A choice within a `ContextMenu.RadioGroup`. Default element `<div>` with
`role="menuitemradio"`.

| Prop       | Type                                                                        | Default  | Description                                                   |
| ---------- | --------------------------------------------------------------------------- | -------- | ------------------------------------------------------------- |
| `value`    | `string`                                                                    | required | Identifies the item within its group.                         |
| `render`   | `RenderProp<{ checked: boolean; disabled: boolean; highlighted: boolean }>` | -        | Compose or replace the element.                               |
| `disabled` | `boolean`                                                                   | `false`  | Skip the item and ignore activation.                          |
| `onSelect` | `(event: Event) => void`                                                    | -        | Called on activation; `preventDefault()` keeps the menu open. |
| `children` | `ComponentChildren`                                                         | -        | Item content (render your own selected indicator).            |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`                                        | -        | Forwarded to the element.                                     |

Sets `aria-checked` and `data-checked` (present when checked).

### ContextMenu.Separator

A horizontal divider between groups of items. Default element `<div>` with
`role="separator"`.

| Prop       | Type                                 | Default | Description               |
| ---------- | ------------------------------------ | ------- | ------------------------- |
| `render`   | `RenderProp`                         | -       | Compose or replace it.    |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element. |

### ContextMenu.Group

Wraps related items and labels them with a `ContextMenu.GroupLabel`. Default
element `<div>` with `role="group"`.

| Prop       | Type                                 | Default | Description                               |
| ---------- | ------------------------------------ | ------- | ----------------------------------------- |
| `render`   | `RenderProp`                         | -       | Compose or replace it.                    |
| `children` | `ComponentChildren`                  | -       | A `ContextMenu.GroupLabel` and the items. |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.                 |

Wires its label to `aria-labelledby`.

### ContextMenu.GroupLabel

The accessible name for a `ContextMenu.Group`. Presentational, not focusable.
Default element `<div>`.

| Prop       | Type                                 | Default | Description               |
| ---------- | ------------------------------------ | ------- | ------------------------- |
| `render`   | `RenderProp`                         | -       | Compose or replace it.    |
| `children` | `ComponentChildren`                  | -       | Label text.               |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element. |

### ContextMenu.Arrow

Optional pointer positioned from the Floating UI arrow data. Default element
`<div>`. Place it on the correct edge with CSS keyed on `data-side`.

| Prop       | Type                                 | Default | Description                     |
| ---------- | ------------------------------------ | ------- | ------------------------------- |
| `render`   | `RenderProp<{ side: Side }>`         | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                  | -       | Optional arrow content.         |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.       |

Sets `data-side` and `position: absolute` with the computed offset.

### ContextMenu.SubmenuRoot

Provides a nested menu's open state and placement off a trigger row. Must be
placed inside a `ContextMenu.Popup`. Renders only its children.

| Prop           | Type                               | Default   | Description                                                |
| -------------- | ---------------------------------- | --------- | ---------------------------------------------------------- |
| `open`         | `boolean`                          | -         | Controlled open state. Pair with `onOpenChange`.           |
| `defaultOpen`  | `boolean`                          | `false`   | Initial open state when uncontrolled.                      |
| `onOpenChange` | `(open: boolean) => void`          | -         | Called when the submenu requests an open or close.         |
| `side`         | `'top'\|'right'\|'bottom'\|'left'` | `'right'` | Preferred side of the trigger to place the submenu.        |
| `align`        | `'start'\|'center'\|'end'`         | `'start'` | Alignment along that side.                                 |
| `offset`       | `number`                           | `0`       | Gap in pixels between the trigger and the submenu.         |
| `openDelay`    | `number`                           | `100`     | Hover open delay in ms.                                    |
| `closeDelay`   | `number`                           | `300`     | Safe-corridor grace in ms before closing on pointer leave. |
| `children`     | `ComponentChildren`                | -         | The submenu trigger and positioner.                        |

### ContextMenu.SubmenuTrigger

The row that opens the submenu. It is itself a `menuitem` in the parent menu.
Default element `<div>` with `role="menuitem"`.

| Prop       | Type                                                  | Default | Description                         |
| ---------- | ----------------------------------------------------- | ------- | ----------------------------------- |
| `render`   | `RenderProp<{ open: boolean; highlighted: boolean }>` | -       | Compose or replace the element.     |
| `disabled` | `boolean`                                             | `false` | Skip the row and ignore activation. |
| `children` | `ComponentChildren`                                   | -       | Row content.                        |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`                  | -       | Forwarded to the element.           |

Sets `aria-haspopup="menu"`, `aria-expanded`, and (while open) `aria-controls`.
Opens on hover (after `openDelay`), `→`, `Enter`, `Space`, or click; the safe
corridor keeps it open while the pointer travels toward the submenu.

### ContextMenu.SubmenuPositioner

The submenu's fixed-positioned wrapper. Same surface as `ContextMenu.Positioner`,
bound to the submenu. Default element `<div>`.

| Prop       | Type                                       | Default | Description                                              |
| ---------- | ------------------------------------------ | ------- | -------------------------------------------------------- |
| `render`   | `RenderProp<{ side: Side; align: Align }>` | -       | Compose or replace the element.                          |
| `children` | `ComponentChildren`                        | -       | The submenu popup.                                       |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`       | -       | Forwarded to the element. Style positioning via `class`. |

### ContextMenu.SubmenuPopup

The submenu surface. Same surface as `ContextMenu.Popup`, with `←` wired to close
the submenu and return focus to its trigger. Default element `<div>` with
`role="menu"`.

| Prop         | Type                                 | Default | Description                                       |
| ------------ | ------------------------------------ | ------- | ------------------------------------------------- |
| `render`     | `RenderProp<{ open: boolean }>`      | -       | Compose or replace the element.                   |
| `aria-label` | `string`                             | -       | Accessible name. Defaults to the submenu trigger. |
| `children`   | `ComponentChildren`                  | -       | The nested items.                                 |
| `...props`   | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.                         |

### Primitives

`hono-preact-ui` exports the building blocks the parts use, for composing your
own components. Several have their own page with examples:
[usePosition](/docs/components/use-position),
[useDismiss](/docs/components/use-dismiss),
[useFocusReturn](/docs/components/use-focus-return),
[useSafeArea](/docs/components/use-safe-area),
[renderElement](/docs/components/render-element),
[useControllableState](/docs/components/use-controllable-state), and
[mergeRefs](/docs/components/merge-refs).

## Accessibility

The menu itself is the same `role="menu"` surface as Menu, with the same
keyboard navigation, focus management, and dismissal; see
[Menu accessibility](/docs/components/menu#accessibility) for the full contract.

- Once open, the menu is operated entirely by keyboard: arrow keys move, Enter /
  Space activate, Escape closes, and focus returns to the page on close.
- The right-click opening gesture is not keyboard-reachable on its own. Where a
  context menu is the only path to an action, also expose those actions through a
  button-triggered control so they are reachable without a right-click.
- Touch input does not reliably raise the `contextmenu` event and there is no
  long-press fallback here, so do not put actions that are only available through
  the context menu; keep a visible alternative.


---

> Source: https://framework.sbesh.com/docs/components/select

# Select

A custom listbox select: a button that opens a popup of options and writes the
chosen value back. It supports single and multiple selection, carries a generic
value type so an option's `value` is your own data rather than a string, and
submits in a real form through a `name`. Positioning runs on Floating UI; the
popup renders in place and promotes to the browser top layer using the Popover
API. It ships unstyled: style it through the `data-state`,
`data-highlighted`, `data-selected`, `data-disabled`, `data-placeholder`,
`data-side`, and `data-align` contract.

`Select.Value` shows the selected option's label by reading the registered
options client-side, so on the server (before hydration) it falls back to the
placeholder. For a label that is correct in server-rendered HTML, pass
`Select.Value` a render prop (or a children function) and resolve the label from
your own data, which runs on the server too.

## Demo

A single select closes when you pick an option; the trigger shows the chosen
label.

<Example code={selectCode}>

</Example>

A multiple select toggles each option and stays open; the trigger joins the
selected labels.

<Example code={selectMultiCode}>

</Example>

## Usage

The value contract follows `multiple`. A single select (the default) deals in
`Value | null`: `onValueChange` receives the picked value, or `null` when the
selection is cleared (for example by a form reset with no `defaultValue`). Set
`multiple` on `Select.Root` for multi-selection: picking an option toggles it
and keeps the popup open, and the value is a `Value[]`. Pass a `value` /
`onValueChange` pair to control the selection (`null` in single mode and `[]`
in multiple mode mean controlled-and-empty), or `defaultValue` to leave it
uncontrolled. When `name` is set, the value submits as a hidden field (one
field per selected value in multiple mode), present before hydration; an empty
selection submits no field, like an unchecked checkbox.

Two typing notes. `multiple` must be a literal (`true`, or omitted) for
TypeScript to pin the mode; a `boolean` variable widens the handler to the
union of both modes. And `null` alone cannot infer `Value`, so when the initial
controlled value is `null` and `Value` is not `string`, pass the generic
explicitly (`<Select.Root<User> value={null}>`).

The value type is generic. By default an option's `value` is a string, but you
can pass objects: give `Select.Root` an `isValueEqual` comparator so the
component can match selected values by identity, and a `serializeValue` so the
hidden form field has a string to submit.

```tsx
<Select.Root<User>
  isValueEqual={(a, b) => a.id === b.id}
  serializeValue={(u) => u.id}
  name="assignee"
>
  <Select.Trigger>
    <Select.Value placeholder="Assign to">
      {({ selectedLabels }) => selectedLabels.join(', ') || 'Assign to'}
    </Select.Value>
  </Select.Trigger>
  {/* ... */}
</Select.Root>
```

### Form reset

Inside a `<form>`, the component resets to its `defaultValue` when the form is
reset (a reset button, or `Form`'s `reset`), the same way a native field resets
to its default. A reset whose event is `preventDefault`ed is ignored.

## Styling

Parts expose `data-state` (`open` / `closed` on the trigger and popup). Options expose `data-highlighted` while active, `data-selected` when
selected, and `data-disabled` when disabled; `Select.Value` exposes
`data-placeholder` while empty; the Positioner and Arrow expose `data-side` and
`data-align`. The Positioner is the fixed-positioned wrapper, so size, z-index,
and the entry animation go on the Popup inside it. The demo above uses the
styles below; copy a starting point in either flavor:

```css
.docs-select-trigger {
  display: inline-flex;
  align-items: center;
  justify-content: space-between;
  gap: 0.5rem;
  min-width: 14rem;
  font-size: 0.875rem;
  padding: 0.5rem 0.75rem;
  border: 1px solid #e4e4e7;
  border-radius: 0.5rem;
  background: #fff;
  color: #18181b;
  cursor: pointer;
}
.docs-select-trigger:hover,
.docs-select-trigger[data-state='open'] {
  border-color: #18181b;
}
.docs-select__value[data-placeholder] {
  color: #71717a;
}
.docs-select-positioner {
  z-index: 50;
}
.docs-select {
  box-sizing: border-box;
  min-width: 14rem;
  max-height: 16rem;
  overflow-y: auto;
  padding: 0.25rem;
  border: 1px solid #e4e4e7;
  border-radius: 0.625rem;
  background: #fff;
  color: #18181b;
  box-shadow:
    0 10px 15px -3px rgb(0 0 0 / 0.25),
    0 4px 6px -4px rgb(0 0 0 / 0.25);
  outline: none;
  opacity: 1;
  transform: translateY(0);
  transition:
    opacity 120ms ease,
    transform 120ms ease;
}
@starting-style {
  .docs-select[data-state='open'] {
    opacity: 0;
    transform: translateY(-4px);
  }
}
.docs-select[data-state='closed'] {
  opacity: 0;
  transform: translateY(-4px);
}
/* Options: the active descendant is data-highlighted (set by hover and arrow
   keys); the selected option is data-selected. Both can be true at once. */
.docs-select__option {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  font-size: 0.875rem;
  padding: 0.4rem 0.6rem;
  border-radius: 0.375rem;
  cursor: pointer;
  outline: none;
}
.docs-select__option[data-selected]::after {
  content: '✓';
  margin-left: auto;
}
.docs-select__option[data-highlighted] {
  background: #18181b;
  color: #fafafa;
}
.docs-select__option[data-disabled] {
  color: #a1a1aa;
  pointer-events: none;
}
.docs-select__label {
  padding: 0.25rem 0.6rem;
  font-size: 0.75rem;
  font-weight: 600;
  text-transform: uppercase;
  letter-spacing: 0.04em;
  color: #71717a;
}
@media (prefers-color-scheme: dark) {
  .docs-select-trigger,
  .docs-select {
    border-color: #27272a;
    background: #18181b;
    color: #fafafa;
  }
  .docs-select-trigger:hover,
  .docs-select-trigger[data-state='open'] {
    border-color: #fafafa;
  }
  .docs-select__option[data-highlighted] {
    background: #fafafa;
    color: #18181b;
  }
}
@media (prefers-reduced-motion: reduce) {
  .docs-select {
    transition: none;
  }
}
```

```tsx
<Select.Trigger className="flex min-w-56 items-center justify-between gap-2 rounded-lg border border-zinc-200 bg-white px-3 py-2 text-sm text-zinc-900 cursor-pointer hover:border-zinc-900 data-[state=open]:border-zinc-900 dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-100 dark:hover:border-zinc-50 dark:data-[state=open]:border-zinc-50">
  <Select.Value
    className="data-[placeholder]:text-zinc-500"
    placeholder="Pick a fruit"
  />
</Select.Trigger>
<Select.Positioner className="z-50">
  <Select.Popup className="min-w-56 max-h-64 overflow-y-auto rounded-[0.625rem] border border-zinc-200 bg-white p-1 text-zinc-900 shadow-xl outline-none opacity-100 translate-y-0 transition-[opacity,translate] duration-[120ms] ease-out starting:opacity-0 starting:-translate-y-1 data-[state=closed]:opacity-0 data-[state=closed]:-translate-y-1 motion-reduce:transition-none dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-100">
    <Select.Option className="flex items-center gap-2 rounded-md px-2.5 py-1.5 text-sm outline-none cursor-pointer data-[selected]:after:content-['✓'] data-[selected]:after:ml-auto data-[highlighted]:bg-zinc-900 data-[highlighted]:text-zinc-50 data-[disabled]:pointer-events-none data-[disabled]:text-zinc-400 dark:data-[highlighted]:bg-zinc-50 dark:data-[highlighted]:text-zinc-900">
      Apple
    </Select.Option>
    <Select.OptionGroupLabel className="px-2.5 py-1 text-xs font-semibold uppercase tracking-wide text-zinc-500">
      Citrus
    </Select.OptionGroupLabel>
  </Select.Popup>
</Select.Positioner>
```

## Keyboard

| Keys                   | When                    | Action                                                                      |
| ---------------------- | ----------------------- | --------------------------------------------------------------------------- |
| `Enter` / `Space`      | Trigger, closed         | Open the listbox.                                                           |
| `↓` / `↑`              | Trigger, closed         | Open the listbox.                                                           |
| `Alt` + `↓`            | Trigger, closed         | Open the listbox.                                                           |
| `↓` / `↑`              | Listbox open            | Move the active option to the next / previous, wrapping at the ends.        |
| `Home` / `End`         | Listbox open            | Move the active option to the first / last.                                 |
| _printable characters_ | Listbox open            | Typeahead: activate the next option whose label starts with the typed text. |
| `Enter` / `Space`      | Listbox open (single)   | Select the active option and close.                                         |
| `Enter` / `Space`      | Listbox open (multiple) | Toggle the active option and stay open.                                     |
| `Escape`               | Listbox open            | Close without changing the selection; focus stays on the trigger.           |
| `Tab`                  | Listbox open            | Close, then move focus to the next element.                                 |

Focus stays on the trigger the whole time; navigation moves the active option
via `aria-activedescendant` rather than moving DOM focus. Disabled options are
skipped by arrow keys and typeahead. Set `loop={false}` on `Select.Root` to stop
arrow navigation from wrapping, and `typeahead={false}` to disable
type-to-activate.

## Data attributes

| Attribute          | On                | Values                                            |
| ------------------ | ----------------- | ------------------------------------------------- |
| `data-state`       | Trigger, Popup    | `open` \| `closed`                                |
| `data-highlighted` | Option            | present while the option is the active descendant |
| `data-selected`    | Option            | present when the option is selected               |
| `data-disabled`    | Option            | present when the option is disabled               |
| `data-placeholder` | Value             | present while no option is selected               |
| `data-side`        | Positioner, Arrow | `top` \| `right` \| `bottom` \| `left` (resolved) |
| `data-align`       | Positioner        | `start` \| `center` \| `end` (resolved)           |

The selected option also carries `aria-selected="true"`, so you can style the
selection with either the data attribute or the ARIA state.

## API reference

Every part accepts a `render` prop for composition (see
[renderElement](/docs/components/render-element)) and forwards unknown props to the
element it renders. `Select.Option` passes its
`{ selected, disabled, highlighted }` state to a render function; `Select.Value`
passes `{ selectedLabels }`.

### Select.Root

Provides selection and open state, ids, refs, navigation config, and placement
to the parts. Generic over the value type (`Select.Root<Value>`); defaults to
`string`. Renders its children plus the hidden form field(s) when `name` is set.

| Prop             | Type                                                                         | Default     | Description                                                                                                                         |
| ---------------- | ---------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `value`          | `Value \| null` single, `readonly Value[]` multiple                          | -           | Controlled selection. Pair with `onValueChange`. `null` (single) or `[]` (multiple) is controlled-and-empty; omit for uncontrolled. |
| `defaultValue`   | `Value \| null` single, `readonly Value[]` multiple                          | -           | Initial selection when uncontrolled.                                                                                                |
| `onValueChange`  | `(value: Value \| null) => void` single, `(value: Value[]) => void` multiple | -           | Called when the selection changes, including when it is cleared.                                                                    |
| `multiple`       | `true \| false`                                                              | `false`     | Discriminates the value shape: omitted or `false` is scalar, `true` is array. Use a literal so TypeScript pins the mode.            |
| `open`           | `boolean`                                                                    | -           | Controlled open state. Pair with `onOpenChange`.                                                                                    |
| `defaultOpen`    | `boolean`                                                                    | `false`     | Initial open state when uncontrolled.                                                                                               |
| `onOpenChange`   | `(open: boolean) => void`                                                    | -           | Called when the listbox requests an open or close.                                                                                  |
| `name`           | `string`                                                                     | -           | Submit the value as a hidden field (one per value in multiple mode).                                                                |
| `disabled`       | `boolean`                                                                    | `false`     | Disable the trigger and skip the hidden field.                                                                                      |
| `required`       | `boolean`                                                                    | `false`     | Mark the trigger `aria-required`.                                                                                                   |
| `isValueEqual`   | `(a: Value, b: Value) => boolean`                                            | `Object.is` | Compare values for selection matching (use for object values).                                                                      |
| `serializeValue` | `(value: Value) => string`                                                   | `String`    | Stringify a value for the hidden form field.                                                                                        |
| `side`           | `'top'\|'right'\|'bottom'\|'left'`                                           | `'bottom'`  | Preferred side of the trigger to place the popup.                                                                                   |
| `align`          | `'start'\|'center'\|'end'`                                                   | `'start'`   | Alignment along that side.                                                                                                          |
| `offset`         | `number`                                                                     | `8`         | Gap in pixels between the trigger and the popup.                                                                                    |
| `loop`           | `boolean`                                                                    | `true`      | Wrap arrow navigation at the first / last option.                                                                                   |
| `typeahead`      | `boolean`                                                                    | `true`      | Activate options by typing their leading characters.                                                                                |
| `children`       | `ComponentChildren`                                                          | -           | The trigger and positioner.                                                                                                         |

### Select.Trigger

Toggles the listbox on click and anchors it. Owns the keyboard navigation and
typeahead while open (focus stays on it). Default element
`<button type="button">` with `role="combobox"`.

| Prop       | Type                                    | Default | Description                                                                   |
| ---------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `render`   | `RenderProp<{ open: boolean }>`         | -       | Compose or replace the element.                                               |
| `children` | `ComponentChildren`                     | -       | Usually a `Select.Value` and an indicator.                                    |
| `...props` | `JSX.HTMLAttributes<HTMLButtonElement>` | -       | Forwarded to the element; a passed `onClick` runs before the listbox toggles. |

Sets `role="combobox"`, `aria-haspopup="listbox"`, `aria-expanded`,
`aria-controls`, `aria-activedescendant` (while open), `aria-required` (when
required), `id`, and `data-state`.

### Select.Value

Shows the selected option's label, or the placeholder while empty. Reads the
registered option labels client-side, so server-rendered HTML shows the
placeholder unless you supply a children / render function. Default element
`<span>`.

| Prop          | Type                                                         | Default | Description                                                    |
| ------------- | ------------------------------------------------------------ | ------- | -------------------------------------------------------------- |
| `placeholder` | `string`                                                     | `''`    | Text shown while nothing is selected.                          |
| `render`      | `RenderProp<{ selectedLabels: string[] }>`                   | -       | Compose or replace the element.                                |
| `children`    | `(state: { selectedLabels: string[] }) => ComponentChildren` | -       | Render the display from the selected labels (server-accurate). |
| `...props`    | `JSX.HTMLAttributes<HTMLSpanElement>`                        | -       | Forwarded to the element.                                      |

Sets `data-placeholder` while no option is selected.

### Select.Positioner

The fixed-positioned wrapper that Floating UI drives. Always mounted (so options
register their labels) and `hidden` while closed. Default element `<div>`.

| Prop       | Type                                       | Default | Description                                              |
| ---------- | ------------------------------------------ | ------- | -------------------------------------------------------- |
| `render`   | `RenderProp<{ side: Side; align: Align }>` | -       | Compose or replace the element.                          |
| `children` | `ComponentChildren`                        | -       | The popup (and optional arrow).                          |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`       | -       | Forwarded to the element. Style positioning via `class`. |

Sets `position: fixed`, the resolved `data-side` / `data-align`, and `hidden`
while closed. The element is promoted to the top layer via the Popover API, so it
escapes ancestor clipping.

### Select.Popup

The listbox surface. Default element `<div>` with `role="listbox"`.

| Prop         | Type                                 | Default | Description                                       |
| ------------ | ------------------------------------ | ------- | ------------------------------------------------- |
| `render`     | `RenderProp<{ open: boolean }>`      | -       | Compose or replace the element.                   |
| `aria-label` | `string`                             | -       | Accessible name. Defaults to the trigger's label. |
| `children`   | `ComponentChildren`                  | -       | Options and option groups.                        |
| `...props`   | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.                         |

Sets `role="listbox"`, `id`, `aria-multiselectable` (in multiple mode),
`data-state`, and `aria-labelledby` (the trigger) or `aria-label`. Owns
Escape / outside-press dismissal.

### Select.Option

A selectable row. Default element `<div>` with `role="option"`.

| Prop       | Type                                                                         | Default  | Description                                         |
| ---------- | ---------------------------------------------------------------------------- | -------- | --------------------------------------------------- |
| `value`    | `Value`                                                                      | required | The value this option selects.                      |
| `render`   | `RenderProp<{ selected: boolean; disabled: boolean; highlighted: boolean }>` | -        | Compose or replace the element.                     |
| `disabled` | `boolean`                                                                    | `false`  | Skip the option in navigation and ignore selection. |
| `children` | `ComponentChildren`                                                          | -        | Option content; a string child is its label.        |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`                                         | -        | Forwarded to the element.                           |

Sets `role="option"`, `aria-selected`, `aria-disabled` (when disabled), and
`data-selected` / `data-highlighted` / `data-disabled`.

### Select.OptionGroup

Wraps related options and labels them with a `Select.OptionGroupLabel`. Default
element `<div>` with `role="group"`.

| Prop       | Type                                 | Default | Description                              |
| ---------- | ------------------------------------ | ------- | ---------------------------------------- |
| `render`   | `RenderProp`                         | -       | Compose or replace it.                   |
| `children` | `ComponentChildren`                  | -       | A `Select.OptionGroupLabel` and options. |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.                |

Wires its label to `aria-labelledby`.

### Select.OptionGroupLabel

The accessible name for a `Select.OptionGroup`. Presentational, not selectable.
Default element `<div>`.

| Prop       | Type                                 | Default | Description               |
| ---------- | ------------------------------------ | ------- | ------------------------- |
| `render`   | `RenderProp`                         | -       | Compose or replace it.    |
| `children` | `ComponentChildren`                  | -       | Label text.               |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element. |

### Select.Arrow

Optional pointer positioned from the Floating UI arrow data. Default element
`<div>`. Place it on the correct edge with CSS keyed on `data-side`.

| Prop       | Type                                 | Default | Description                     |
| ---------- | ------------------------------------ | ------- | ------------------------------- |
| `render`   | `RenderProp<{ side: Side }>`         | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                  | -       | Optional arrow content.         |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded to the element.       |

Sets `data-side` and `position: absolute` with the computed offset.

### Primitives

`hono-preact-ui` exports the building blocks the parts use, for composing your
own components. Several have their own page with examples:
[useListNavigation](/docs/components/use-list-navigation),
[usePosition](/docs/components/use-position),
[useDismiss](/docs/components/use-dismiss),
[renderElement](/docs/components/render-element),
[useControllableState](/docs/components/use-controllable-state), and
[mergeRefs](/docs/components/merge-refs).

## Accessibility

The select follows the ARIA combobox-with-listbox pattern. The trigger is a
`role="combobox"` carrying `aria-haspopup="listbox"`, `aria-expanded`,
`aria-controls`, and `aria-activedescendant`; the popup is a `role="listbox"`
(`aria-multiselectable` in multiple mode), named by the trigger or an explicit
`aria-label`. Options are `role="option"` with `aria-selected`.

- Both Enter / Space and the arrow keys open the listbox from the trigger, so it
  is reachable without a pointer.
- Focus stays on the trigger while the listbox is open; the active option is
  tracked with `aria-activedescendant` rather than moving DOM focus, and the
  active option is scrolled into view.
- On open, the active descendant starts on the selected option (or the first
  option when nothing is selected).
- Escape closes without changing the selection, an outside pointer press closes
  it, and Tab closes then moves on. Disabled options are skipped by navigation,
  typeahead, and selection.
- Set a `name` so the value submits in a real form; the hidden field is a real
  input present before hydration.


---

> Source: https://framework.sbesh.com/docs/components/combobox

# Combobox

An editable text input combined with a popup listbox. The user types a query,
the consumer filters and renders matching options, and the component handles
navigation, ARIA wiring, and selection commit. It ships unstyled: style it
through the `data-state`, `data-highlighted`, `data-selected`, `data-disabled`,
`data-side`, `data-align`, and `data-empty` contract.

Use a Combobox when the user needs to search or filter before picking. Use
[Select](/docs/components/select) when the list is short and always fully
visible without filtering.

**The consumer owns filtering.** The component never filters its children.
Read `inputValue` (the typed query) and render only the matching
`<Combobox.Option>` elements. A `matchSubstring` helper is exported for the
common in-memory case.

**`inputValue` is always the typed query.** In `autocomplete="both"` mode the
DOM input may show a longer inline completion, but the public `inputValue`
(and `onInputChange`) is always the prefix the user typed, so consumer
filtering is identical across all three autocomplete modes.

## Demo

The minimal form is a single `Combobox.Input`. Focus it (or click it) to open,
type to filter; the consumer renders the matching options while the component
handles navigation and selection. A single select commits and closes on pick.

<Example code={comboboxCode}>

</Example>

Multiple selection shows the two optional parts: `Combobox.Anchor` wraps the
chips and input into one bordered field (the popup aligns to it and clicks in it
are dismiss-safe), and `Combobox.Trigger` is the chevron toggle. Picking keeps
the popup open; `Combobox.Value` renders the chips; Backspace on an empty input
removes the last one.

<Example code={comboboxMultiCode}>

</Example>

Creatable: when nothing matches, a "Create …" option appears and adds the new
value through `onCreate`.

<Example code={comboboxCreatableCode}>

</Example>

With `autocomplete="both"`, the input inline-completes to the first match; Enter
or Tab accepts it, Backspace dismisses it and keeps typing.

<Example code={comboboxInlineCode}>

</Example>

## Usage

The only required part is `Combobox.Input` (it carries `role="combobox"`); it
opens on focus by default and anchors the popup to itself. Everything else is an
opt-in. The combobox is uncontrolled by default; pass `value` / `onValueChange`,
`open` / `onOpenChange`, or `inputValue` / `onInputChange` to control any piece.

**Field wrapper + trigger (optional).** For a bordered field that holds chips or
adornments, wrap the input in `Combobox.Anchor`: the popup then aligns to the
whole field and clicks anywhere in it are dismiss-safe. Add `Combobox.Trigger`
for an explicit chevron toggle button (focus already opens the popup, so this is
only needed when you want a dedicated open/close control):

```tsx
<Combobox.Anchor>
  <Combobox.Input aria-label="Fruit" />
  <Combobox.Trigger aria-label="Open">▾</Combobox.Trigger>
</Combobox.Anchor>
```

**Multiple selection.** Set `multiple`; the value becomes an array and the popup
stays open on pick. Wrap the field in `Combobox.Anchor` and render the selected
chips with `Combobox.Value`, which exposes `{ selectedItems, remove }`. It
renders a `<span>` and accepts standard HTML attributes (like `class`) and a
`render` prop for full control:

```tsx
<Combobox.Value class="chip-list">
  {({ selectedItems, remove }) =>
    selectedItems.map((it) => (
      <button key={String(it.value)} onClick={() => remove(it.value)}>
        {it.label} ×
      </button>
    ))
  }
</Combobox.Value>
```

**Creatable.** When the query matches nothing, render an option marked `create`.
Selecting it calls `onCreate(inputValue)` instead of `onValueChange`; your
handler persists the new option and selects it:

```tsx
{
  showCreate && (
    <Combobox.Option value={query} create>
      Create “{query}”
    </Combobox.Option>
  );
}
```

**Inline autocomplete.** Set `autocomplete="both"` to complete the input to the
first match (Enter or Tab accepts; Backspace dismisses). `autocomplete="none"`
turns off auto-highlight for a static, non-filtering suggestion list.

**Async options.** Fetch and filter in an effect and render the results;
override `Combobox.Status` with a render prop to announce loading instead of the
result count.

### Form reset

Inside a `<form>`, the component resets to its `defaultValue` when the form is
reset (a reset button, or `Form`'s `reset`), the same way a native field resets
to its default. The input text returns to `defaultInputValue`. A reset whose
event is `preventDefault`ed is ignored.

## Styling

Style through the data-attribute contract: `data-state` (`open` / `closed`) on
the Input, Trigger, and Popup; `data-highlighted` / `data-selected` /
`data-disabled` on Options; `data-empty` on the Popup when no options are
registered; `data-side` / `data-align` on the Positioner and Arrow. The
Positioner is the fixed-positioned wrapper, so size, z-index, and the entry
animation go on the Popup inside it. The demos above use the styles below; copy
a starting point in either flavor:

```css
.docs-cb-input {
  box-sizing: border-box;
  min-width: 16rem;
  padding: 0.5rem 0.75rem;
  font-size: 0.875rem;
  border: 1px solid #e4e4e7;
  border-radius: 0.5rem;
  background: #fff;
  color: #18181b;
  outline: none;
}
.docs-cb-input:focus {
  border-color: #18181b;
}
/* Optional Combobox.Anchor field wrapper (chips / adornments): the wrapper takes
   the border and the input inside goes borderless. */
.docs-cb-field {
  display: inline-flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 0.25rem;
  min-width: 16rem;
  padding: 0.375rem 0.5rem;
  border: 1px solid #e4e4e7;
  border-radius: 0.5rem;
  background: #fff;
  cursor: text;
}
.docs-cb-field:focus-within {
  border-color: #18181b;
}
.docs-cb-field .docs-cb-input {
  flex: 1;
  min-width: 5rem;
  padding: 0.125rem 0.25rem;
  border: none;
}
.docs-cb-trigger {
  padding: 0 0.5rem;
  border: none;
  background: transparent;
  color: #71717a;
  cursor: pointer;
}
.docs-cb-positioner {
  z-index: 50;
}
.docs-cb {
  box-sizing: border-box;
  min-width: 16rem;
  max-height: 16rem;
  overflow-y: auto;
  padding: 0.25rem;
  border: 1px solid #e4e4e7;
  border-radius: 0.625rem;
  background: #fff;
  color: #18181b;
  box-shadow:
    0 10px 15px -3px rgb(0 0 0 / 0.25),
    0 4px 6px -4px rgb(0 0 0 / 0.25);
  outline: none;
  opacity: 1;
  transform: translateY(0);
  transition:
    opacity 120ms ease,
    transform 120ms ease;
}
@starting-style {
  .docs-cb[data-state='open'] {
    opacity: 0;
    transform: translateY(-4px);
  }
}
.docs-cb[data-state='closed'] {
  opacity: 0;
  transform: translateY(-4px);
}
.docs-cb__option {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.4rem 0.6rem;
  font-size: 0.875rem;
  border-radius: 0.375rem;
  cursor: pointer;
  outline: none;
}
.docs-cb__option[data-selected]::after {
  content: '✓';
  margin-left: auto;
}
.docs-cb__option[data-highlighted] {
  background: #18181b;
  color: #fafafa;
}
.docs-cb__option[data-disabled] {
  color: #a1a1aa;
  pointer-events: none;
}
.docs-cb__empty {
  padding: 0.5rem 0.6rem;
  font-size: 0.875rem;
  color: #71717a;
}
@media (prefers-color-scheme: dark) {
  .docs-cb-field,
  .docs-cb {
    border-color: #27272a;
    background: #18181b;
    color: #fafafa;
  }
  .docs-cb-field:focus-within {
    border-color: #fafafa;
  }
  .docs-cb__option[data-highlighted] {
    background: #fafafa;
    color: #18181b;
  }
}
@media (prefers-reduced-motion: reduce) {
  .docs-cb {
    transition: none;
  }
}
```

```tsx
{
  /* Minimal: the Input is the field box. */
}
<Combobox.Input className="min-w-64 rounded-lg border border-zinc-200 bg-white px-3 py-2 text-sm text-zinc-900 outline-none placeholder:text-zinc-400 focus:border-zinc-900 dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-100 dark:focus:border-zinc-50" />;

{
  /* For chips or a chevron, wrap in Combobox.Anchor (the border moves to the
    wrapper and the input goes borderless):
<Combobox.Anchor className="inline-flex min-w-64 flex-wrap items-center gap-1 rounded-lg border border-zinc-200 bg-white px-2 py-1.5 focus-within:border-zinc-900 dark:border-zinc-800 dark:bg-zinc-900">
  <Combobox.Input className="min-w-20 flex-1 border-0 bg-transparent px-1 text-sm outline-none" />
  <Combobox.Trigger className="px-2 text-zinc-400" />
</Combobox.Anchor> */
}

<Combobox.Positioner className="z-50">
  <Combobox.Popup className="min-w-64 max-h-64 overflow-y-auto rounded-[0.625rem] border border-zinc-200 bg-white p-1 text-zinc-900 shadow-xl outline-none opacity-100 translate-y-0 transition-[opacity,translate] duration-[120ms] ease-out starting:opacity-0 starting:-translate-y-1 data-[state=closed]:opacity-0 data-[state=closed]:-translate-y-1 motion-reduce:transition-none dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-100">
    <Combobox.Option className="flex cursor-pointer items-center gap-2 rounded-md px-2.5 py-1.5 text-sm outline-none data-[highlighted]:bg-zinc-900 data-[highlighted]:text-zinc-50 data-[selected]:after:content-['✓'] data-[selected]:after:ml-auto data-[disabled]:pointer-events-none data-[disabled]:text-zinc-400 dark:data-[highlighted]:bg-zinc-50 dark:data-[highlighted]:text-zinc-900">
      Apple
    </Combobox.Option>
    <Combobox.Empty className="px-2.5 py-2 text-sm text-zinc-500">
      No results
    </Combobox.Empty>
  </Combobox.Popup>
</Combobox.Positioner>;
```

## Keyboard

| Key                  | When                    | Action                                                                       |
| -------------------- | ----------------------- | ---------------------------------------------------------------------------- |
| Printable characters | Input focused           | Update query, open the popup, auto-highlight the first match (list/both).    |
| `↓` / `↑`            | Input focused, closed   | Open the popup.                                                              |
| `↓` / `↑`            | Popup open              | Move the active option to the next / previous, wrapping at the ends.         |
| `Alt` + `↑`          | Popup open              | Close the popup.                                                             |
| `Home` / `End`       | Input focused           | Move the text caret (native; the popup is not navigated).                    |
| `Enter`              | Popup open, active set  | Commit the active option and close (single) or toggle and stay open (multi). |
| `Tab`                | Popup open, `both` mode | Accept the inline completion (commit the active option).                     |
| `Tab`                | Popup open, other modes | Revert the input to the committed value, close, then move focus.             |
| `Escape`             | Popup open              | Close and revert the display to the typed query (does not reset the value).  |
| `Escape`             | Input focused, closed   | Reset the input to the selected value's label (or empty in multiple mode).   |
| `Backspace`          | Empty input, multi      | Remove the last selected token.                                              |

Focus stays in the input the whole time. The active option is tracked with
`aria-activedescendant`; it does not receive DOM focus. Arrow navigation wraps
by default; pass `loop={false}` on `Combobox.Root` to disable.

## Data attributes

| Attribute          | On                    | Values                                            |
| ------------------ | --------------------- | ------------------------------------------------- |
| `data-state`       | Input, Trigger, Popup | `open` \| `closed`                                |
| `data-highlighted` | Option                | Present while the option is the active descendant |
| `data-selected`    | Option                | Present when the option is selected               |
| `data-disabled`    | Option                | Present when the option is disabled               |
| `data-side`        | Positioner, Arrow     | `top` \| `right` \| `bottom` \| `left` (resolved) |
| `data-align`       | Positioner            | `start` \| `center` \| `end` (resolved)           |
| `data-empty`       | Popup                 | Present when no options are registered            |

## API reference

Every part accepts a `render` prop for composition (see
[renderElement](/docs/components/render-element)) and forwards unknown props to the
element it renders. `Combobox.Option` passes `{ selected, disabled, highlighted
}` to a render function; `Combobox.Status` passes `{ count, open }`;
`Combobox.Value` exposes `{ selectedItems, remove }` via a children function or
a `render` prop.

### Combobox.Root

Provides value, open state, input value, autocomplete mode, refs, and
positioning to the parts. Generic over the value type (`Combobox.Root<Value>`);
defaults to `string`. Renders children and the hidden form field(s) when `name`
is set.

| Prop                | Type                                                                         | Default     | Description                                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`             | `Value \| null` single, `readonly Value[]` multiple                          | -           | Controlled selection. Pair with `onValueChange`. `null` (single) or `[]` (multiple) is controlled-and-empty; omit for uncontrolled.                |
| `defaultValue`      | `Value \| null` single, `readonly Value[]` multiple                          | -           | Initial selection when uncontrolled.                                                                                                               |
| `onValueChange`     | `(value: Value \| null) => void` single, `(value: Value[]) => void` multiple | -           | Called when the selection changes, including clears (not called for `create` options).                                                             |
| `multiple`          | `true \| false`                                                              | `false`     | Discriminates the value shape: omitted or `false` is scalar, `true` is array; popup stays open on pick. Use a literal so TypeScript pins the mode. |
| `open`              | `boolean`                                                                    | -           | Controlled open state. Pair with `onOpenChange`.                                                                                                   |
| `defaultOpen`       | `boolean`                                                                    | `false`     | Initial open state when uncontrolled.                                                                                                              |
| `onOpenChange`      | `(open: boolean) => void`                                                    | -           | Called when the popup requests an open or close.                                                                                                   |
| `inputValue`        | `string`                                                                     | -           | Controlled typed query. Pair with `onInputChange`.                                                                                                 |
| `defaultInputValue` | `string`                                                                     | `''`        | Initial query when uncontrolled.                                                                                                                   |
| `onInputChange`     | `(value: string) => void`                                                    | -           | Called when the user edits the input (always the typed query, not completion).                                                                     |
| `autocomplete`      | `'none' \| 'list' \| 'both'`                                                 | `'list'`    | Sets `aria-autocomplete` and governs auto-highlight and inline completion.                                                                         |
| `onCreate`          | `(inputValue: string) => void`                                               | -           | Called when a `create` option is selected; if absent, `create` falls back to normal selection.                                                     |
| `itemToString`      | `(value: Value) => string`                                                   | -           | Resolve a label for a value whose option is not currently rendered (SSR, filter).                                                                  |
| `name`              | `string`                                                                     | -           | Submit the value as a hidden field (one per value in multiple mode).                                                                               |
| `disabled`          | `boolean`                                                                    | `false`     | Disable the input and skip the hidden field.                                                                                                       |
| `required`          | `boolean`                                                                    | `false`     | Mark the input `aria-required`.                                                                                                                    |
| `isValueEqual`      | `(a: Value, b: Value) => boolean`                                            | `Object.is` | Compare values for selection matching (use for object values).                                                                                     |
| `serializeValue`    | `(value: Value) => string`                                                   | `String`    | Stringify a value for the hidden form field.                                                                                                       |
| `side`              | `'top'\|'right'\|'bottom'\|'left'`                                           | `'bottom'`  | Preferred side of the input to place the popup.                                                                                                    |
| `align`             | `'start'\|'center'\|'end'`                                                   | `'start'`   | Alignment along that side.                                                                                                                         |
| `offset`            | `number`                                                                     | `8`         | Gap in pixels between the input and the popup.                                                                                                     |
| `loop`              | `boolean`                                                                    | `true`      | Wrap arrow navigation at the first / last option.                                                                                                  |
| `openOnFocus`       | `boolean`                                                                    | `true`      | Open the popup when the input gains focus (or is clicked while closed). Set `false` to opt out.                                                    |
| `children`          | `ComponentChildren`                                                          | -           | The input, trigger, positioner, and status parts.                                                                                                  |

### Combobox.Input

The editable text input. Owns keyboard navigation, filtering side effects,
inline completion (in `both` mode), and IME composition handling. Default
element `<input type="text">` with `role="combobox"`.

| Prop       | Type                                   | Default | Description                                                    |
| ---------- | -------------------------------------- | ------- | -------------------------------------------------------------- |
| `render`   | `RenderProp<{ open: boolean }>`        | -       | Compose or replace the element.                                |
| `...props` | `JSX.HTMLAttributes<HTMLInputElement>` | -       | Forwarded; `value` and `onInput` are managed by the component. |

Sets `role="combobox"`, `aria-autocomplete`, `aria-expanded`, `aria-controls`,
`aria-activedescendant` (while open), `aria-required` (when required), `id`,
`disabled`, and `data-state`.

### Combobox.Trigger

An optional chevron button that toggles the popup. Removes itself from the tab
order (`tabIndex=-1`) so focus stays in the input. Default element
`<button type="button">`.

| Prop       | Type                                    | Default | Description                                           |
| ---------- | --------------------------------------- | ------- | ----------------------------------------------------- |
| `render`   | `RenderProp<{ open: boolean }>`         | -       | Compose or replace the element.                       |
| `children` | `ComponentChildren`                     | -       | Chevron icon or label.                                |
| `...props` | `JSX.HTMLAttributes<HTMLButtonElement>` | -       | Forwarded; a passed `onClick` runs before the toggle. |

Sets `aria-controls`, `aria-expanded`, `aria-label` (defaults to `"Open"`),
`disabled`, and `data-state`.

### Combobox.Clear

An optional button that resets the selection and the input, then focuses the
input. The cleared selection reaches `onValueChange` as `null` in single mode
and `[]` in multiple mode, so a controlled parent observes the clear. Default
element `<button type="button">`.

| Prop       | Type                                    | Default | Description                                          |
| ---------- | --------------------------------------- | ------- | ---------------------------------------------------- |
| `render`   | `RenderProp`                            | -       | Compose or replace the element.                      |
| `children` | `ComponentChildren`                     | -       | Button content.                                      |
| `...props` | `JSX.HTMLAttributes<HTMLButtonElement>` | -       | Forwarded; a passed `onClick` runs before the clear. |

Sets `aria-label` (defaults to `"Clear"`) and `disabled`.

### Combobox.Anchor

Optional wrapper that becomes the popup's positioning anchor. Wrap the Input
(plus any chips, Trigger, or Clear) in it so the popup aligns to the whole field
instead of the bare input. It is also a dismiss-safe region: pressing its padding
or a chip will not close the popup. When omitted, the popup anchors to the Input.
Default element `<div>`.

| Prop       | Type                              | Default | Description                     |
| ---------- | --------------------------------- | ------- | ------------------------------- |
| `render`   | `RenderProp`                      | -       | Compose or replace the element. |
| `children` | `ComponentChildren`               | -       | The input and adornments.       |
| `...props` | `JSX.HTMLAttributes<HTMLElement>` | -       | Forwarded.                      |

### Combobox.Positioner

The fixed-positioned wrapper that Floating UI drives. Always mounted so options
register their labels even while closed. Default element `<div>`.

| Prop       | Type                                       | Default | Description                               |
| ---------- | ------------------------------------------ | ------- | ----------------------------------------- |
| `render`   | `RenderProp<{ side: Side; align: Align }>` | -       | Compose or replace the element.           |
| `children` | `ComponentChildren`                        | -       | The popup (and optional arrow).           |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`       | -       | Forwarded. Style positioning via `class`. |

Sets `position: fixed`, resolved `data-side` / `data-align`, and `hidden`
while closed. Promotes to the browser top layer via the Popover API.

### Combobox.Popup

The listbox surface. Default element `<div>` with `role="listbox"`.

| Prop         | Type                                 | Default | Description                                     |
| ------------ | ------------------------------------ | ------- | ----------------------------------------------- |
| `render`     | `RenderProp<{ open: boolean }>`      | -       | Compose or replace the element.                 |
| `aria-label` | `string`                             | -       | Accessible name. Defaults to the input's label. |
| `children`   | `ComponentChildren`                  | -       | Options, groups, and Empty.                     |
| `...props`   | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded.                                      |

Sets `role="listbox"`, `id`, `aria-multiselectable` (in multiple mode),
`data-state`, `data-empty` (when no options are registered), and
`aria-labelledby` (the input) or `aria-label`. Owns outside-press dismissal.

### Combobox.Empty

Renders only when the popup is open and no options are registered. Use for
"No results" messages. Default element `<div>`.

| Prop       | Type                                 | Default | Description            |
| ---------- | ------------------------------------ | ------- | ---------------------- |
| `render`   | `RenderProp`                         | -       | Compose or replace it. |
| `children` | `ComponentChildren`                  | -       | Message content.       |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded.             |

### Combobox.Option

A selectable row in the popup. Default element `<div>` with `role="option"`.

| Prop       | Type                                                                         | Default  | Description                                                    |
| ---------- | ---------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- |
| `value`    | `Value`                                                                      | required | The value this option selects.                                 |
| `create`   | `boolean`                                                                    | `false`  | Route selection to `onCreate` instead of committing the value. |
| `render`   | `RenderProp<{ selected: boolean; disabled: boolean; highlighted: boolean }>` | -        | Compose or replace the element.                                |
| `disabled` | `boolean`                                                                    | `false`  | Skip in navigation and ignore selection.                       |
| `children` | `ComponentChildren`                                                          | -        | Option content; a string child is used as the option's label.  |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`                                         | -        | Forwarded.                                                     |

Sets `role="option"`, `aria-selected`, `aria-disabled` (when disabled), and
`data-selected` / `data-highlighted` / `data-disabled`.

### Combobox.OptionGroup

Wraps related options and labels them with a `Combobox.OptionGroupLabel`.
Default element `<div>` with `role="group"`.

| Prop       | Type                                 | Default | Description                                |
| ---------- | ------------------------------------ | ------- | ------------------------------------------ |
| `render`   | `RenderProp`                         | -       | Compose or replace it.                     |
| `children` | `ComponentChildren`                  | -       | A `Combobox.OptionGroupLabel` and options. |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded.                                 |

Wires its label to `aria-labelledby`.

### Combobox.OptionGroupLabel

The accessible name for a `Combobox.OptionGroup`. Presentational, not
selectable. Default element `<div>`.

| Prop       | Type                                 | Default | Description            |
| ---------- | ------------------------------------ | ------- | ---------------------- |
| `render`   | `RenderProp`                         | -       | Compose or replace it. |
| `children` | `ComponentChildren`                  | -       | Label text.            |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded.             |

### Combobox.Arrow

Optional pointer positioned by Floating UI arrow data. Default element
`<div>`. Place it on the correct edge with CSS keyed on `data-side`.

| Prop       | Type                                 | Default | Description                     |
| ---------- | ------------------------------------ | ------- | ------------------------------- |
| `render`   | `RenderProp<{ side: Side }>`         | -       | Compose or replace the element. |
| `children` | `ComponentChildren`                  | -       | Optional arrow content.         |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>` | -       | Forwarded.                      |

Sets `data-side` and `position: absolute` with the computed offset.

### Combobox.Status

A visually-hidden `aria-live="polite"` region that announces the result count
to screen readers. Default content: `"{N} results available"` when open and
options exist; `"No results"` when open and empty; cleared when closed. Default
element `<div>`.

| Prop       | Type                                           | Default | Description                                                              |
| ---------- | ---------------------------------------------- | ------- | ------------------------------------------------------------------------ |
| `render`   | `RenderProp<{ count: number; open: boolean }>` | -       | Override the content. Receives the current option count and open state.  |
| `...props` | `JSX.HTMLAttributes<HTMLDivElement>`           | -       | Forwarded (excluding `children`); merged with the visually-hidden style. |

Sets `role="status"`, `aria-live="polite"`, `aria-atomic="true"`, and
visually-hidden styles.

### Combobox.Value

Renders selected items. Required in multiple mode to render chips; optional in
single mode. Renders a `<span>` wrapper and accepts standard HTML attributes
(like `class` for styling the chip container). Generic over the root's value
type (`Combobox.Value<Value>`).

| Prop       | Type                                                      | Default | Description                                                                                   |
| ---------- | --------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `children` | `(state: ComboboxValueState<Value>) => ComponentChildren` | -       | Render function receiving the selected items. Optional when `render` is provided.             |
| `render`   | `(props, state: ComboboxValueState<Value>) => VNode`      | -       | Replace the default `<span>` entirely; receives forwarded props and state.                    |
| `...props` | `JSX.HTMLAttributes<HTMLSpanElement>`                     | -       | Forwarded to the `<span>` wrapper (excluding `children`); e.g. `class` for chip-list styling. |

`ComboboxValueState<Value>` has:

| Field           | Type                     | Description                                                      |
| --------------- | ------------------------ | ---------------------------------------------------------------- |
| `selectedItems` | `OptionEntry<Value>[]`   | Selected items in value order, each with `{ id, value, label }`. |
| `remove`        | `(value: Value) => void` | Toggle an item off (de-select it).                               |

### Primitives

`hono-preact-ui` exports the building blocks the parts use, for composing
your own components. Several have their own page with examples:
[useListNavigation](/docs/components/use-list-navigation),
[usePosition](/docs/components/use-position),
[useDismiss](/docs/components/use-dismiss),
[renderElement](/docs/components/render-element),
[useControllableState](/docs/components/use-controllable-state), and
[mergeRefs](/docs/components/merge-refs).

The `matchSubstring` helper is also exported from `hono-preact-ui` for the
common in-memory filter case:
`matchSubstring(label: string, query: string): boolean`.

## Accessibility

The Combobox follows the WAI-ARIA combobox with listbox pattern. The input is
`role="combobox"` carrying `aria-haspopup="listbox"`, `aria-expanded`,
`aria-controls`, `aria-autocomplete`, and `aria-activedescendant` (while
open). The popup is `role="listbox"` (`aria-multiselectable` in multiple mode),
named by the input or an explicit `aria-label`. Options are `role="option"`
with `aria-selected`.

- Focus stays in the input at all times. The active option is tracked with
  `aria-activedescendant` and scrolled into view rather than receiving DOM
  focus.
- Focusing the input opens the popup (`openOnFocus`, default `true`) and selects
  its text, so the first keystroke starts a fresh search.
- The input mirrors the committed value when you are not editing: dismissing
  without a fresh pick (clicking away or Tab) reverts the text to the selected
  value's label, so it never shows a dangling, unselected query.
- Arrow keys open the popup from a closed input; Alt+ArrowUp closes it.
- Escape closes but keeps the typed query so you can keep editing; a second
  Escape reverts the input to the selected value's label.
- Home and End move the text caret (native behavior); they do not navigate the
  list, per the APG pattern.
- `Combobox.Status` announces the result count politely after each filter so
  screen readers report how many options are available without interrupting
  ongoing speech.
- Set a `name` so the committed value submits in a real form; the hidden field
  is present before hydration.


---

> Source: https://framework.sbesh.com/docs/components/toast

# Toast

Imperative, accessible toast notifications. Fire one from anywhere with
`toast(...)`; render them through the headless `Toast.*` parts. Ships unstyled:
style everything through the `data-*` and CSS-variable contract.

## Demo

<Example code={toastCode}>

</Example>

## Usage

```tsx
import { toast, Toaster, Toast, type ToastRecord } from 'hono-preact-ui';

function renderToast(t: ToastRecord) {
  return (
    <Toast.Root toast={t}>
      <Toast.Title />
      <Toast.Description />
      <Toast.Action />
      <Toast.Close aria-label="Dismiss">x</Toast.Close>
    </Toast.Root>
  );
}

export function App() {
  return (
    <>
      <button onClick={() => toast.success('Saved')}>Save</button>
      <Toaster position="bottom-right">{renderToast}</Toaster>
    </>
  );
}
```

Fire toasts imperatively:

```ts
toast('Event saved');
toast.success('Profile updated', { description: 'Your changes are live.' });
toast.error('Upload failed');
toast.promise(save(), {
  loading: 'Saving...',
  success: 'Saved!',
  error: 'Failed',
});
const id = toast.loading('Working...');
toast.dismiss(id);
```

## Styling

Toast is headless: the recipe below is the full set of styles that drives the
demo above, and you own all of it. `Toaster` renders a `popover` region (target
it with `[popover]`); each `Toast.Root` carries `data-state`, `data-type`,
`data-position`, `data-expanded`, `data-front`, `data-swiping`, and the
`--toast-index` / `--toasts-before` / `--toast-offset` / `--toast-height` /
`--toast-swipe-amount` variables. The stack is built from one composed
`transform`: the front toast (`--toast-index` 0) sits on top via `z-index`,
older toasts offset up by `--toast-offset` and scale down by depth, and the
collapsed pile expands to full size on hover/focus (`data-expanded`). The
`::after` bridges the gap between expanded toasts so the pointer never leaves
the stack (no hover-collapse jitter), and a dismiss slides out to the side,
continuing a swipe rather than snapping back. Guard every transition behind
`prefers-reduced-motion`.

```css
/* Region: pinned to a corner; toasts are absolutely stacked inside it.
   Pass class="toaster" to <Toaster> for this hook. */
.toaster {
  position: fixed;
  inset: auto 1rem 1rem auto;
  width: min(22rem, calc(100vw - 2rem));
  margin: 0;
  padding: 0;
  border: 0;
  background: transparent;
  overflow: visible;
}
.toaster ol {
  margin: 0;
  padding: 0;
  list-style: none;
}

/* Each toast: front on top, one transform for swipe + stacking offset + depth
   scale. Add your own padding / border / background / radius / shadow. */
.toast {
  position: absolute;
  right: 0;
  bottom: 0;
  z-index: calc(1000 - var(--toast-index, 0));
  box-sizing: border-box;
  width: 100%;
  transform-origin: bottom center;
  transform: translateX(var(--toast-swipe-amount, 0px))
    translateY(calc(-1 * var(--toast-offset, 0px))) scale(var(--toast-scale, 1));
  touch-action: pan-y;
}
/* Bridge the gap to the toast above so moving between expanded toasts never
   leaves the region (prevents hover-collapse jitter). */
.toast::after {
  content: '';
  position: absolute;
  inset: auto 0 100% 0;
  height: 16px;
}
/* Collapsed pile: front three opaque and peeking; deeper toasts hide beneath. */
.toast:not([data-expanded='true']) {
  --toast-scale: calc(1 - 0.05 * min(var(--toasts-before, 0), 2));
  opacity: calc(1 - max(0, var(--toasts-before, 0) - 2));
}
/* Expanded on hover/focus: full size and opacity, real heights. */
.toast[data-expanded='true'] {
  --toast-scale: 1;
  opacity: 1;
}
@media (prefers-reduced-motion: no-preference) {
  .toast {
    transition:
      transform 0.4s,
      opacity 0.4s;
  }
}
/* Enter from below + fade (transition origin on insert). */
@starting-style {
  .toast {
    opacity: 0;
    transform: translateY(100%) scale(0.9);
  }
}
/* Track the pointer 1:1 while dragging. */
.toast[data-swiping='true'] {
  transition: none;
}
/* Exit: slide out and fade. A swipe-dismiss keeps its offset, so this continues
   the gesture outward instead of snapping back to center. */
.toast[data-state='closed'] {
  opacity: 0;
  transform: translateX(110%) translateY(calc(-1 * var(--toast-offset, 0px)));
}
```

```tsx
// Base Tailwind v4. The starting:/after:/data-[]/motion-safe: variants map 1:1
// to the CSS tab, so the two are feature-equivalent.

<Toaster
  class="fixed inset-[auto_1rem_1rem_auto] m-0 w-[min(22rem,calc(100vw-2rem))]
    overflow-visible border-0 bg-transparent p-0 [&>ol]:m-0 [&>ol]:list-none [&>ol]:p-0"
  position="bottom-right"
>
  {(t) => (
    <Toast.Root
      toast={t}
      class="absolute right-0 bottom-0 box-border w-full origin-bottom touch-pan-y
    z-[calc(1000-var(--toast-index,0))]
    [transform:translateX(var(--toast-swipe-amount,0px))_translateY(calc(-1*var(--toast-offset,0px)))_scale(var(--toast-scale,1))]
    after:content-[''] after:absolute after:inset-x-0 after:bottom-full after:h-4
    not-data-[expanded=true]:[--toast-scale:calc(1-0.05*min(var(--toasts-before,0),2))]
    not-data-[expanded=true]:[opacity:calc(1-max(0,var(--toasts-before,0)-2))]
    data-[expanded=true]:[--toast-scale:1] data-[expanded=true]:opacity-100
    motion-safe:transition-[transform,opacity] motion-safe:duration-[400ms]
    starting:opacity-0 starting:[transform:translateY(100%)_scale(0.9)]
    data-[swiping=true]:transition-none
    data-[state=closed]:opacity-0
    data-[state=closed]:[transform:translateX(110%)_translateY(calc(-1*var(--toast-offset,0px)))]"
    />
  )}
</Toaster>
```

## API reference

### `toast`

| Call                                                               | Returns | Description                                     |
| ------------------------------------------------------------------ | ------- | ----------------------------------------------- |
| `toast(message, opts?)`                                            | `id`    | Default toast.                                  |
| `toast.success / error / info / warning / loading(message, opts?)` | `id`    | Typed variants; `error` announces assertively.  |
| `toast.custom((id) => VNode, opts?)`                               | `id`    | Render an arbitrary body.                       |
| `toast.promise(promise, { loading, success, error })`              | `id`    | One toast tracks a promise.                     |
| `toast.dismiss(id?)`                                               | `void`  | Dismiss one toast, or all when `id` is omitted. |

`opts`: `id`, `description`, `duration` (ms; `Infinity` = sticky; default 4000),
`important`, `action: { label, onClick }`, `onDismiss`, `onAutoClose`.

### `Toaster`

| Prop            | Type                        | Default             | Description                                  |
| --------------- | --------------------------- | ------------------- | -------------------------------------------- |
| `position`      | `ToastPosition`             | `'bottom-right'`    | Corner; sets entry direction and swipe axis. |
| `label`         | `string`                    | `'Notifications'`   | Accessible name of the region.               |
| `expand`        | `boolean`                   | `false`             | Always-expanded stack vs collapse-to-pile.   |
| `visibleToasts` | `number`                    | `3`                 | Toasts shown before older ones fade under.   |
| `gap`           | `number`                    | `14`                | Px gap between expanded toasts.              |
| `hotkey`        | `string[]`                  | `['altKey','KeyT']` | Chord that focuses the region.               |
| `children`      | `(t: ToastRecord) => VNode` | required            | Render prop for each toast.                  |

### `Toast.Root`

| Prop     | Type          | Default   | Description                      |
| -------- | ------------- | --------- | -------------------------------- |
| `toast`  | `ToastRecord` | required  | The record from the render prop. |
| `render` | `RenderProp`  | undefined | Replace the rendered element.    |

`Toast.Title`, `Toast.Description`, `Toast.Action`, and `Toast.Close` each accept
the standard `render` prop and read the active toast from context; `Description`
and `Action` render nothing when the record has no description / action.

## Accessibility

`<Toaster>` mounts a separate, always-present visually-hidden announcer: polite
(`role=status`) for normal toasts and assertive (`role=alert`) for `error` or
`important` toasts. The visible list is a labeled `region` landmark of `<ol>`
items and is intentionally not itself a live region (so reflow never
re-announces). Press the `hotkey` (default Alt+T) to move focus into the region.
Hovering or focusing the region pauses auto-dismiss and expands the stack.
Motion is driven entirely by your CSS, so guarding transitions behind
`prefers-reduced-motion` yields an accessible, reduced-motion-correct result.
For a toast to be spoken by a screen reader, its `title` and `description` must
be plain strings; a VNode body renders visually but is not included in the
spoken announcement.

Because toasts fire imperatively from anywhere, a headless primitive cannot know
where focus should return when a focused toast is dismissed (auto-dismiss, swipe,
or its close button). Restoring focus is therefore the consumer's
responsibility; the `usePresence` status / `onExitComplete` seam on `Toast.Root`
is the hook for it. Toast does not move focus to a sibling toast on dismiss,
which would steal focus to another unrequested notification.

> Toast requires the browser Popover API to place its region in the top layer.
> This is a deliberate, documented exception to the library's
> progressive-enhancement baseline; all current browser versions support it.


---

> Source: https://framework.sbesh.com/docs/components/render-element

# renderElement

`renderElement` is the composition engine behind every component's `render` prop. It
takes the framework-controlled props (ARIA attributes, refs, event handlers) and
applies them to whatever element you want to render: the default tag, a tag you
name, an element you pass, or a function you supply. It is how a part can lend
its behavior and accessibility wiring to a different element without losing
either.

## Demo

<Example code={renderElementCode}>

</Example>

## Example

Build a component that owns its behavior but lets the caller swap the element:

```tsx
import { renderElement, type RenderProp } from 'hono-preact-ui';
import type { ComponentChildren, JSX, VNode } from 'preact';

type ButtonProps = {
  render?: RenderProp<{ pressed: boolean }>;
  pressed?: boolean;
  children?: ComponentChildren;
} & Omit<JSX.HTMLAttributes<HTMLButtonElement>, 'children'>;

export function Button({
  render,
  pressed = false,
  children,
  ...rest
}: ButtonProps): VNode {
  return renderElement<{ pressed: boolean }>({
    render,
    defaultTag: 'button',
    props: {
      ...rest,
      type: 'button',
      'data-pressed': pressed ? '' : undefined,
    },
    state: { pressed },
    children,
  });
}
```

## Signature

```tsx
import { renderElement, type RenderProp } from 'hono-preact-ui';

function renderElement<State>(opts: {
  render?: RenderProp<State>; // the consumer's override (optional)
  defaultTag: string; // element to use when no render is given
  props: Record<string, unknown>; // framework-controlled props (ref, aria-*, handlers)
  state?: State; // passed to the function form of render
  children?: ComponentChildren;
}): VNode;

type RenderProp<State> =
  | VNode // an element to clone
  | string // a tag name
  | ((props, state: State) => VNode) // full control
  | undefined; // use defaultTag
```

When merging, `class`/`className` are joined and `ref` is merged (so the
consumer's ref and the framework's ref both fire); every other framework prop
overrides.

### Options

| Option       | Type                      | Description                                         |
| ------------ | ------------------------- | --------------------------------------------------- |
| `render`     | `RenderProp<State>`       | The consumer's override. Omit to use `defaultTag`.  |
| `defaultTag` | `string`                  | The element to render when no `render` is given.    |
| `props`      | `Record<string, unknown>` | Framework-controlled props merged onto the element. |
| `state`      | `State`                   | Passed as the second argument to the function form. |
| `children`   | `ComponentChildren`       | Children for the rendered element.                  |

Returns a `VNode`.

## The three forms

A consumer can drive `render` three ways:

```tsx
// 1. Default element: a <button> with the framework props.
<Button>Save</Button>

// 2. An element to clone: render as a link, props are merged onto it.
<Button render={<a href="/save" />}>Save</Button>

// 3. A function: full control, with the component's state.
<Button render={(props, state) => (
  <a {...props}>{state.pressed ? 'Saved' : 'Save'}</a>
)} />
```

`renderElement` ships in `hono-preact-ui` and powers every [Dialog](/docs/components/dialog), [Popover](/docs/components/popover), and [Tooltip](/docs/components/tooltip) part, so anything
you build with it composes the same way the built-in components do.


---

> Source: https://framework.sbesh.com/docs/components/use-controllable-state

# useControllableState

`useControllableState` lets a single component support both controlled and
uncontrolled use from one hook. When the caller passes a value, the component is
controlled and the value is the single source of truth; when they pass only a
default, the component manages its own state. Either way, the setter is stable
across renders, so you can list it in effect dependencies without re-subscribing.

## Demo

<Example code={useControllableStateCode}>

</Example>

## Example

A toggle that works controlled or uncontrolled, mirroring how [`Dialog.Root`](/docs/components/dialog)
handles `open` / `defaultOpen` / `onOpenChange`:

```tsx
import { useControllableState } from 'hono-preact-ui';

type ToggleProps = {
  pressed?: boolean; // controlled
  defaultPressed?: boolean; // uncontrolled
  onPressedChange?: (pressed: boolean) => void;
};

export function Toggle({
  pressed,
  defaultPressed,
  onPressedChange,
}: ToggleProps) {
  const [on, setOn] = useControllableState<boolean>({
    value: pressed,
    defaultValue: defaultPressed ?? false,
    onChange: onPressedChange,
  });

  return (
    <button type="button" aria-pressed={on} onClick={() => setOn(!on)}>
      {on ? 'On' : 'Off'}
    </button>
  );
}
```

```tsx
// Uncontrolled: the component owns the state.
<Toggle defaultPressed onPressedChange={(p) => console.log(p)} />;

// Controlled: you own the state, the component reflects it.
const [pressed, setPressed] = useState(false);
<Toggle pressed={pressed} onPressedChange={setPressed} />;
```

The mode is assumed fixed for the component's lifetime, switching controlled and
uncontrolled does not re-seed internal state, which matches typical usage.

## Signature

```tsx
import { useControllableState } from 'hono-preact-ui';

function useControllableState<T>(opts: {
  value?: T; // controlled; when defined, the component is controlled
  defaultValue: T; // uncontrolled initial value
  onChange?: (value: T) => void;
}): [T, (next: T) => void];
```

When `value` is defined the hook is controlled: it reads `value` and never
updates internal state, so the parent must apply the change. When `value` is
absent it is uncontrolled, seeded from `defaultValue`. The setter always calls
`onChange`.

### Options

| Option         | Type                 | Description                                             |
| -------------- | -------------------- | ------------------------------------------------------- |
| `value`        | `T`                  | Controlled value. When defined, the hook is controlled. |
| `defaultValue` | `T`                  | Initial value when uncontrolled.                        |
| `onChange`     | `(value: T) => void` | Called with the next value on every change.             |

Returns `[value, setValue]`: the current value and a stable setter.


---

> Source: https://framework.sbesh.com/docs/components/merge-refs

# mergeRefs

`mergeRefs` combines several refs into one callback ref. It is the small piece
that lets a component keep its own internal ref to a node while still handing
that node to a ref the caller passed in. Function refs are invoked with the
node, object refs have their `.current` assigned, and `null`/`undefined` are
skipped.

## Demo

<Example code={mergeRefsCode}>

</Example>

## Example

A field that needs its own ref to the input (to measure or focus it) while also
forwarding a ref to the caller:

```tsx
import { mergeRefs } from 'hono-preact-ui';
import { useRef } from 'preact/hooks';
import type { Ref } from 'preact';

export function Field({ inputRef }: { inputRef?: Ref<HTMLInputElement> }) {
  const internalRef = useRef<HTMLInputElement>(null);

  const focus = () => internalRef.current?.focus();

  // Both refs receive the same node.
  return (
    <div>
      <input ref={mergeRefs(internalRef, inputRef)} />
      <button type="button" onClick={focus}>
        Focus
      </button>
    </div>
  );
}
```

This is the same helper [`renderElement`](/docs/components/render-element) uses internally to merge a consumer's `ref`
with the framework's own, so passing a `ref` through the `render` prop always
keeps both wired up.

## Signature

```tsx
import { mergeRefs } from 'hono-preact-ui';

function mergeRefs<T>(
  ...refs: (Ref<T> | null | undefined)[]
): (node: T | null) => void;
```

It returns a single callback ref. Pass that to an element's `ref`, and every ref
you merged receives the node.

### Parameters

| Parameter | Type                              | Description                                                                                        |
| --------- | --------------------------------- | -------------------------------------------------------------------------------------------------- |
| `...refs` | `(Ref<T> \| null \| undefined)[]` | The refs to combine. Function refs are called, object refs are assigned, nullish refs are skipped. |

Returns a callback ref, `(node: T \| null) => void`, that forwards the node to
every ref passed in.


---

> Source: https://framework.sbesh.com/docs/components/use-list-navigation

# useListNavigation

`useListNavigation` is the keyboard navigation binding the [Menu](/docs/components/menu)
and [Select](/docs/components/select) components use. Given a container of items,
it handles ArrowUp / ArrowDown, Home / End, and typeahead, tracking which item is
active and moving the active state through the list (wrapping at the ends, skipping
disabled items).

It supports two modes. In `roving` mode it moves DOM focus to the active item (a
roving tabindex list, as in a menu). In `activedescendant` mode focus stays on a
container element and you render `aria-activedescendant` pointing at the active
item, scrolling it into view rather than focusing it (as in a listbox where the
trigger keeps focus).

## Demo

<Example code={useListNavigationCode}>

</Example>

## Example

A listbox where the trigger keeps focus and the active option is tracked with
`aria-activedescendant`:

```tsx
import { useListNavigation } from 'hono-preact-ui';
import { useRef, useState } from 'preact/hooks';

function Listbox({ open }: { open: boolean }) {
  const listRef = useRef<HTMLDivElement>(null);
  const [activeId, setActiveId] = useState<string | null>(null);
  const nav = useListNavigation({
    enabled: open,
    containerRef: listRef,
    itemSelector: '[role="option"]:not([aria-disabled="true"])',
    activeId,
    setActiveId,
    mode: 'activedescendant',
  });
  return (
    <button
      role="combobox"
      aria-expanded={open}
      aria-activedescendant={open ? (activeId ?? undefined) : undefined}
      onKeyDown={nav.onKeyDown}
    >
      <div ref={listRef} role="listbox">
        {/* role="option" rows */}
      </div>
    </button>
  );
}
```

## Signature

```ts
import { useListNavigation } from 'hono-preact-ui';

function useListNavigation(opts: UseListNavigationOptions): ListNavigation;

interface UseListNavigationOptions {
  enabled: boolean;
  containerRef: RefObject<HTMLElement>;
  itemSelector: string;
  activeId: string | null;
  setActiveId: (id: string | null) => void;
  mode: 'roving' | 'activedescendant';
  loop?: boolean; // default true
  typeahead?: boolean; // default true
  homeEnd?: boolean; // default true
  scopeSelector?: string;
}

interface ListNavigation {
  onKeyDown: (event: KeyboardEvent) => void;
  getItems: () => HTMLElement[];
  setActiveItem: (index: number) => void;
}
```

## Options

| Option          | Type                             | Default | Notes                                                                                                   |
| --------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `enabled`       | `boolean`                        | none    | Handle keys only while active (typically the open state).                                               |
| `containerRef`  | `RefObject<HTMLElement>`         | none    | The element holding the items.                                                                          |
| `itemSelector`  | `string`                         | none    | CSS selector matching the navigable items (exclude disabled items here).                                |
| `activeId`      | `string \| null`                 | none    | The id of the active item; drives `aria-activedescendant`.                                              |
| `setActiveId`   | `(id: string \| null) => void`   | none    | Called to change the active item.                                                                       |
| `mode`          | `'roving' \| 'activedescendant'` | none    | `roving` moves DOM focus; `activedescendant` keeps focus and scrolls into view.                         |
| `loop`          | `boolean`                        | `true`  | Wrap arrow navigation at the first / last item.                                                         |
| `typeahead`     | `boolean`                        | `true`  | Activate items by typing their leading characters.                                                      |
| `homeEnd`       | `boolean`                        | `true`  | Handle Home/End (default true); pass false to leave them as native caret movement (Combobox uses this). |
| `scopeSelector` | `string`                         | none    | Exclude items nested in a closer same-role container (a submenu).                                       |

## Returns

| Field           | Type                             | Description                                                                          |
| --------------- | -------------------------------- | ------------------------------------------------------------------------------------ |
| `onKeyDown`     | `(event: KeyboardEvent) => void` | Handle navigation keys; calls `preventDefault` on keys it consumes.                  |
| `getItems`      | `() => HTMLElement[]`            | The current enabled items, queried live from the DOM in order.                       |
| `setActiveItem` | `(index: number) => void`        | Activate the item at `index`: sets the active id and focuses or scrolls it per mode. |

`onKeyDown` calls `event.preventDefault()` on the keys it handles, so a caller
that adds its own keys (Enter to select, Escape to close) can early-return on
`event.defaultPrevented` after delegating.

## Companion exports

`hono-preact-ui` also exports `useTypeahead`, the type-to-select hook
`useListNavigation` uses internally, for composing your own navigation:

| Export                                           | Type                                                       | Description                                                                                             |
| ------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [`useTypeahead`](/docs/components/use-typeahead) | `(opts?: UseTypeaheadOptions) => (char: string) => string` | A hook returning a callback that accumulates printable chars into a query, resetting after an idle gap. |


---

> Source: https://framework.sbesh.com/docs/components/use-typeahead

# useTypeahead

`useTypeahead` is the type-to-select hook [useListNavigation](/docs/components/use-list-navigation) uses internally, exported for composing your own keyboard navigation. It returns an `onChar(char)` callback that accumulates printable characters into a query string and returns the current query; the buffer resets after a short idle gap. The caller matches the returned query against its item labels and moves the active item.

## Demo

<Example code={useTypeaheadCode}>

</Example>

## Example

```tsx
import { useTypeahead } from 'hono-preact-ui';
import { useState } from 'preact/hooks';

const ITEMS = ['Argon', 'Boron', 'Calcium', 'Carbon'];

function Typeahead() {
  const onChar = useTypeahead();
  const [active, setActive] = useState(0);

  return (
    <ul
      tabIndex={0}
      role="listbox"
      onKeyDown={(e) => {
        if (e.key.length !== 1) return; // printable characters only
        const query = onChar(e.key);
        const idx = ITEMS.findIndex((it) =>
          it.toLowerCase().startsWith(query.toLowerCase())
        );
        if (idx >= 0) setActive(idx);
      }}
    >
      {ITEMS.map((it, i) => (
        <li key={it} role="option" aria-selected={i === active}>
          {it}
        </li>
      ))}
    </ul>
  );
}
```

See also: [useListNavigation](/docs/components/use-list-navigation), which folds typeahead together with arrow-key and Home/End navigation.

## Signature

```ts
import { useTypeahead } from 'hono-preact-ui';

function useTypeahead(opts?: UseTypeaheadOptions): (char: string) => string;

interface UseTypeaheadOptions {
  idleMs?: number; // reset the buffer after this idle gap, default 500
}
```

Call the returned function with each printable character (for example from a `keydown` handler, skipping non-printable keys); it appends the character to the buffer, schedules a reset after `idleMs` of no input, and returns the current query.

## Options

| Option   | Type     | Default | Notes                                            |
| -------- | -------- | ------- | ------------------------------------------------ |
| `idleMs` | `number` | `500`   | Reset the accumulated query after this idle gap. |

Returns `(char: string) => string`: a stable callback that accumulates `char` into the query and returns it.


---

> Source: https://framework.sbesh.com/docs/components/use-listbox-selection

# useListboxSelection

`useListboxSelection` is the selection core shared by Select and Combobox. It
owns single- and multi-select value tracking, an option registry that resolves
display labels in DOM order (so a closed control can show the selected label
without rendering its list), and hidden form-field serialization. Reach for it
when building a custom listbox-style control that needs the same selection
semantics as the built-in components.

See also: [useListNavigation](/docs/components/use-list-navigation), [Select](/docs/components/select), [Combobox](/docs/components/combobox).

## Demo

<Example code={useListboxSelectionCode}>

</Example>

## Signature

```ts
import { useListboxSelection } from 'hono-preact-ui';

function useListboxSelection<Value = string>(
  opts: UseListboxSelectionOptions<Value>
): ListboxSelection;
```

## Options

| Option           | Type                              | Notes                                                                               |
| ---------------- | --------------------------------- | ----------------------------------------------------------------------------------- |
| `values`         | `readonly Value[]`                | The selected values; `[]` when nothing is selected.                                 |
| `setValues`      | `(next: Value[]) => void`         | Called with the next selection array (a one-element array on a single-select pick). |
| `multiple`       | `boolean`                         | Whether multiple options can be selected.                                           |
| `setOpen`        | `(open: boolean) => void`         | Called to close the control after a single-select choice.                           |
| `isValueEqual`   | `(a: Value, b: Value) => boolean` | Optional. Custom equality; defaults to `Object.is`.                                 |
| `serializeValue` | `(value: Value) => string`        | Optional. Serializes a value for the hidden form field.                             |
| `itemToString`   | `(value: Value) => string`        | Optional. Resolves a display label when no option is registered for a value.        |
| `name`           | `string`                          | Optional. Hidden form-field name; enables native form submission.                   |
| `disabled`       | `boolean`                         | Optional. Disables selection.                                                       |

## Result

| Member           | Type                                | Notes                                                              |
| ---------------- | ----------------------------------- | ------------------------------------------------------------------ |
| `isSelected`     | `(optionValue: unknown) => boolean` | Whether a value is currently selected.                             |
| `toggle`         | `(optionValue: unknown) => void`    | Select or deselect a value (closes the control in single-select).  |
| `registerOption` | `(id, value, label) => () => void`  | Register an option in the label registry; returns a cleanup fn.    |
| `selectedLabels` | `() => string[]`                    | Selected labels in registry (DOM) order.                           |
| `selectedItems`  | `() => OptionEntry[]`               | Selected options in value order, labels resolved via the registry. |
| `labelFor`       | `(value: unknown) => string`        | Resolve a single value's display label.                            |
| `optionCount`    | `number`                            | Number of currently-registered options.                            |
| `hiddenFields`   | `ComponentChild[] \| null`          | Hidden `<input>`s for native form submission, or `null`.           |

## normalizeSelectionProps

`normalizeSelectionProps` is the pure helper that maps [Select](/docs/components/select)'s and [Combobox](/docs/components/combobox)'s public
`value` / `defaultValue` / `onValueChange` props (discriminated on `multiple`,
see [Select](/docs/components/select)'s Usage section) onto the array-shaped
`values` / `setValues` that `useListboxSelection` consumes. Reach for it when
building a custom control that wants the same single/multiple discriminated
prop contract as the built-in components, feeding the result into your own
`useListboxSelection` call.

```ts
import { normalizeSelectionProps } from 'hono-preact-ui';
import type { SelectionProps, NormalizedSelection } from 'hono-preact-ui';

function normalizeSelectionProps<Value>(
  p: SelectionProps<Value>
): NormalizedSelection<Value>;
```

`NormalizedSelection<Value>` always represents selection as an array:
`values`/`defaultValues` are `readonly Value[]` (`undefined` values means
uncontrolled), and `onValuesChange` wraps the caller's `onValueChange` so a
single-mode caller still gets `Value | null` (`[] -> null`) while a
multiple-mode caller gets the `Value[]` it passed in. Memoize the result
per render: a single-mode `value` wraps into a fresh array each call, which
would otherwise churn downstream callback identities.


---

> Source: https://framework.sbesh.com/docs/components/use-position

# usePosition

Hook to keep a floating element anchored to a reference element, with preferred
side and alignment, automatic repositioning on scroll and resize, and optional
arrow offset data. It wraps [Floating UI](https://floating-ui.com) and is the
positioning layer [Popover](/docs/components/popover) and
[Tooltip](/docs/components/tooltip) use internally; reach for it when building
your own custom floating components.

## Demo

<Example code={usePositionCode}>

</Example>

## Signature

```ts
import { usePosition } from 'hono-preact-ui';

function usePosition(opts: UsePositionOptions): PositionState;

interface UsePositionOptions {
  open: boolean;
  anchorRef: RefObject<HTMLElement>;
  floatingRef: RefObject<HTMLElement>;
  arrowRef?: RefObject<HTMLElement>;
  getAnchorRect?: ClientRectGetter; // position against a point/virtual element
  side?: 'top' | 'right' | 'bottom' | 'left'; // default 'bottom'
  align?: 'start' | 'center' | 'end'; // default 'center'
  offset?: number; // gap in px, default 8
}

interface PositionState {
  side: 'top' | 'right' | 'bottom' | 'left';
  align: 'start' | 'center' | 'end';
  arrowX: number | null;
  arrowY: number | null;
}
```

## Options

| Option          | Type                                     | Default    | Notes                                                                                         |
| --------------- | ---------------------------------------- | ---------- | --------------------------------------------------------------------------------------------- |
| `open`          | `boolean`                                | none       | Positioning runs only while open.                                                             |
| `anchorRef`     | `RefObject`                              | none       | The reference element.                                                                        |
| `floatingRef`   | `RefObject`                              | none       | The element being positioned.                                                                 |
| `arrowRef`      | `RefObject`                              | optional   | Enables arrow positioning.                                                                    |
| `getAnchorRect` | `ClientRectGetter`                       | optional   | Position against a point or virtual element instead of `anchorRef` (e.g. a pointer position). |
| `side`          | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Preferred side.                                                                               |
| `align`         | `'start' \| 'center' \| 'end'`           | `'center'` | Alignment along the side.                                                                     |
| `offset`        | `number`                                 | `8`        | Gap in pixels.                                                                                |

## Returns

| Field    | Type                                     | Description                             |
| -------- | ---------------------------------------- | --------------------------------------- |
| `side`   | `'top' \| 'right' \| 'bottom' \| 'left'` | Resolved side after collision handling. |
| `align`  | `'start' \| 'center' \| 'end'`           | Resolved alignment.                     |
| `arrowX` | `number \| null`                         | Arrow x offset in px, or null.          |
| `arrowY` | `number \| null`                         | Arrow y offset in px, or null.          |

## Helpers

Two pure helpers convert between the hook's `(side, align)` model and a Floating
UI `Placement` string. Both are exported from `hono-preact-ui` for building your
own positioning logic on top of the same mapping the components use.

```ts
import { placementFor, sideAlignFromPlacement } from 'hono-preact-ui';

// (side, align) -> Placement: 'center' is the bare side; 'start'/'end' add the suffix.
function placementFor(
  side: 'top' | 'right' | 'bottom' | 'left',
  align: 'start' | 'center' | 'end'
): Placement; // e.g. ('bottom', 'start') -> 'bottom-start'

// Placement -> (side, align): the inverse, for rendering data-side / data-align.
function sideAlignFromPlacement(placement: Placement): {
  side: 'top' | 'right' | 'bottom' | 'left';
  align: 'start' | 'center' | 'end';
};
```

`Placement` is the Floating UI placement union (e.g. `'bottom'`, `'bottom-start'`, `'left-end'`).


---

> Source: https://framework.sbesh.com/docs/components/use-positioner

# usePositioner

`usePositioner` is the complete anchored-overlay positioning hook the library's
own Popover, Tooltip, Menu, Select, and Combobox parts are built on. It composes
`usePosition` (floating placement), `usePresence` (the open/close lifecycle),
top-layer promotion, and the user-agent `[popover]` style neutralization into a
single hook, so a custom anchored overlay does not have to rediscover the
platform quirks the library already handles.

See also: [usePosition](/docs/components/use-position), [usePresence](/docs/components/use-presence), [useDismiss](/docs/components/use-dismiss).

## Demo

<Example code={usePositionerCode}>

</Example>

## Example

```tsx
import { usePositioner } from 'hono-preact-ui';
import { useRef } from 'preact/hooks';

function Anchored({ open }: { open: boolean }) {
  const anchorRef = useRef<HTMLButtonElement>(null);
  const floatingRef = useRef<HTMLElement>(null);

  const { isPresent, positionerProps, state } = usePositioner({
    open,
    anchorRef,
    floatingRef,
    side: 'bottom',
    align: 'center',
    offset: 8,
    mount: 'unmount',
  });

  return (
    <>
      <button ref={anchorRef}>anchor</button>
      {isPresent && (
        <div {...positionerProps} data-side={state.side}>
          overlay contents
        </div>
      )}
    </>
  );
}
```

## Signature

```ts
import { usePositioner } from 'hono-preact-ui';

function usePositioner(opts: UsePositionerOptions): UsePositionerResult;
```

## Options

| Option          | Type                     | Notes                                                                                                                              |
| --------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `open`          | `boolean`                | The overlay's open state; drives the presence lifecycle.                                                                           |
| `anchorRef`     | `RefObject<HTMLElement>` | The element the overlay is positioned against.                                                                                     |
| `floatingRef`   | `RefObject<HTMLElement>` | The positioned overlay element.                                                                                                    |
| `side`          | `Side`                   | Preferred side: `top`, `right`, `bottom`, or `left`.                                                                               |
| `align`         | `Align`                  | Alignment along the side: `start`, `center`, or `end`.                                                                             |
| `offset`        | `number`                 | Gap in pixels between anchor and overlay.                                                                                          |
| `getAnchorRect` | `ClientRectGetter`       | Optional. Position against a point or virtual element instead of `anchorRef` (e.g. a pointer position).                            |
| `mount`         | `'unmount' \| 'hidden'`  | `'unmount'`: branch on `isPresent` and return `null` while closed. `'hidden'`: keep the element mounted and `hidden` while closed. |

`usePositioner` returns `{ isPresent, positionerProps, state, position, arrowRef }`:
spread `positionerProps` onto your positioner element (it already carries the
merged ref including `floatingRef`, Popover-API promotion, the UA `[popover]`
style resets, and `data-side` / `data-align`), branch on `isPresent` when `mount`
is `'unmount'`, and read `state.side` / `state.align` for side-aware styling. For
a custom arrow, attach the returned `arrowRef` to your arrow element and read
`position.arrowX` / `position.arrowY` for its offset (this is what the built-in
`Arrow` part does).


---

> Source: https://framework.sbesh.com/docs/components/use-dismiss

# useDismiss

`useDismiss` registers an open overlay with a shared dismissal stack. Pressing
Escape or pressing outside the overlay dismisses the topmost registered layer,
so nested overlays close one at a time, innermost first.

See also: [useFocusReturn](/docs/components/use-focus-return), [usePosition](/docs/components/use-position), [useSafeArea](/docs/components/use-safe-area).

## Demo

<Example code={useDismissCode}>

</Example>

## Example

```tsx
import { useDismiss } from 'hono-preact-ui';
import { useRef } from 'preact/hooks';

function Panel({ open, onClose }: { open: boolean; onClose: () => void }) {
  const ref = useRef<HTMLDivElement>(null);
  useDismiss({
    enabled: open,
    refs: [ref],
    onDismiss: onClose,
  });
  return open ? <div ref={ref}>panel</div> : null;
}
```

## Signature

```ts
import { useDismiss } from 'hono-preact-ui';

function useDismiss(opts: UseDismissOptions): void;

interface UseDismissOptions {
  enabled: boolean; // typically the open state
  refs: RefObject<HTMLElement>[]; // elements treated as inside (no outside-press)
  escape?: boolean; // default true
  outsidePress?: boolean; // default true
  id?: string; // dismiss-tree node id (nested menus); omit for a single-node layer
  parentId?: string | null; // parent node id for submenu coordination
  onDismiss: (reason: 'escape' | 'outside-press') => void;
}
```

## Options

| Option         | Type               | Default  | Notes                                                                                    |
| -------------- | ------------------ | -------- | ---------------------------------------------------------------------------------------- |
| `enabled`      | `boolean`          | none     | Register only while open.                                                                |
| `refs`         | `RefObject[]`      | none     | Elements treated as inside (no outside-press).                                           |
| `escape`       | `boolean`          | `true`   | Dismiss on Escape.                                                                       |
| `outsidePress` | `boolean`          | `true`   | Dismiss on an outside pointer press.                                                     |
| `id`           | `string`           | optional | Dismiss-tree node id for nested menus; omit for a single-node layer (Popover / Tooltip). |
| `parentId`     | `string \| null`   | optional | Parent node's id for submenu coordination; omit at the tree root.                        |
| `onDismiss`    | `(reason) => void` | none     | Called with `'escape'` or `'outside-press'`.                                             |

The listeners are document-level and capture-phase, attached once and shared
across every registered layer, so adding overlays does not multiply listeners.


---

> Source: https://framework.sbesh.com/docs/components/use-focus-return

# useFocusReturn

`useFocusReturn` is the focus management [Popover](/docs/components/popover) uses. When an overlay opens it
moves focus into the popup; when it closes it returns focus to wherever it was
before. It is not a focus trap: tab order flows out of the popup into the rest
of the page, which is what a non-modal overlay wants.

## Demo

<Example code={useFocusReturnCode}>

</Example>

## Example

```tsx
import { useFocusReturn } from 'hono-preact-ui';
import { useRef } from 'preact/hooks';

function Panel({ open }: { open: boolean }) {
  const popupRef = useRef<HTMLDivElement>(null);
  useFocusReturn({ open, popupRef });
  return open ? (
    <div ref={popupRef}>
      <button>First</button>
      <button>Second</button>
    </div>
  ) : null;
}
```

## Signature

```ts
import { useFocusReturn } from 'hono-preact-ui';

function useFocusReturn(opts: UseFocusReturnOptions): void;

interface UseFocusReturnOptions {
  open: boolean;
  popupRef: RefObject<HTMLElement>;
  initialFocusRef?: RefObject<HTMLElement>; // defaults to first focusable, then popup
}
```

## Options

| Option            | Type        | Default  | Notes                                                            |
| ----------------- | ----------- | -------- | ---------------------------------------------------------------- |
| `open`            | `boolean`   | none     | Focus moves in when this becomes true and returns when it falls. |
| `popupRef`        | `RefObject` | none     | The popup; focus moves into it on open.                          |
| `initialFocusRef` | `RefObject` | optional | Element to focus first, instead of the first focusable.          |

On open it focuses `initialFocusRef`, else the first focusable element in the
popup, else the popup itself. On close it returns focus to the element that was
focused when the overlay opened (usually the trigger). It does not trap focus,
so pair it with a dismissal mechanism such as [useDismiss](/docs/components/use-dismiss).


---

> Source: https://framework.sbesh.com/docs/components/use-safe-area

# useSafeArea

`useSafeArea` keeps a hover-opened floating element open while the pointer travels
the empty gap toward it. When the pointer leaves the trigger it would normally
fire `pointerleave` and close the element before the pointer arrives. This hook
watches `pointermove` and treats the trigger, the floating element, and a safe
corridor between them, a quad spanning the trigger's edge to the floating
element's near edge, as one safe region: while the pointer rests anywhere inside
it the element stays open, including when it dwells in the gap. Once the pointer
leaves that region the element closes after a short grace period, which a move
back inside cancels.

See also: [usePosition](/docs/components/use-position), [useDismiss](/docs/components/use-dismiss), [Tooltip](/docs/components/tooltip).

## Demo

<Example code={useSafeAreaCode}>

</Example>

## Example

```tsx
import { useSafeArea } from 'hono-preact-ui';
import { useRef } from 'preact/hooks';

function HoverCard({ open, onClose }: { open: boolean; onClose: () => void }) {
  const anchorRef = useRef<HTMLButtonElement>(null);
  const floatingRef = useRef<HTMLDivElement>(null);

  useSafeArea({ enabled: open, anchorRef, floatingRef, onClose });

  return (
    <>
      <button ref={anchorRef}>Profile</button>
      {open && <div ref={floatingRef}>card content</div>}
    </>
  );
}
```

## How it works

The safe corridor is a quad joining the trigger's near edge to the floating
element's near edge, spanning the gap between them. While the element is open, a
`pointermove` that stays inside the corridor, even on a diagonal that does not aim
straight at the element, keeps it open, and so does pausing there. A move that
leaves the corridor without reaching the floating element starts the grace timer
and then closes the element; returning to the corridor or either element before
the grace lapses cancels the close. The point-in-polygon test runs against the
live rects of both elements on every move, so the corridor follows them through
scroll, resize, and a flipped placement.

## Signature

```ts
import { useSafeArea } from 'hono-preact-ui';

function useSafeArea(opts: UseSafeAreaOptions): void;

interface UseSafeAreaOptions {
  enabled: boolean; // typically the open state of a hover-driven element
  anchorRef: RefObject<HTMLElement>; // the trigger the corridor starts from
  floatingRef: RefObject<HTMLElement>; // the floating element it points at
  onClose: () => void; // pointer left the safe region and the grace lapsed
  graceMs?: number; // close grace after leaving the safe region, default 300
}
```

## Options

| Option        | Type                     | Default | Notes                                                                                                 |
| ------------- | ------------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `enabled`     | `boolean`                | none    | Watch the pointer only while the element is open.                                                     |
| `anchorRef`   | `RefObject<HTMLElement>` | none    | The trigger the corridor starts from.                                                                 |
| `floatingRef` | `RefObject<HTMLElement>` | none    | The floating element the corridor points at.                                                          |
| `onClose`     | `() => void`             | none    | Called after the pointer leaves the safe region and the grace period lapses.                          |
| `graceMs`     | `number`                 | `300`   | Grace period after the pointer leaves the safe region before `onClose` fires; re-entering cancels it. |

It injects no DOM: it listens to `pointermove` while enabled and runs a
point-in-polygon test against the live rects of the two elements, so nothing
under the corridor is blocked from interaction. The corridor follows the elements
through scroll, resize, and a flipped placement. A pointer session begins only
once the pointer has been over the trigger or the floating element, so an element
opened by keyboard focus is not closed by unrelated mouse movement (the consumer
closes it on blur or Escape instead). If the pointer leaves the document while a
session is active, the same grace timer starts, so the element does not hang open
when the cursor exits the window. Touch pointers are ignored.


---

> Source: https://framework.sbesh.com/docs/components/use-presence

# usePresence

`usePresence` keeps an element mounted while it animates out, then unmounts it.
It is the primitive every overlay in this library uses to run a closing
animation: on close it holds the element in the DOM, lets a `[data-state="closed"]`
CSS **transition or keyframe animation** run, and unmounts only once it finishes.
Animation is opt-in: with no closing rule the element unmounts immediately,
exactly as before.

## Demo

<Example code={usePresenceCode}>

</Example>

## Example

```tsx
import { usePresence } from 'hono-preact-ui';
import { useState } from 'preact/hooks';

function Panel() {
  const [open, setOpen] = useState(false);
  const presence = usePresence(open);
  return (
    <div>
      <button onClick={() => setOpen((o) => !o)}>Toggle</button>
      {presence.isPresent ? (
        <div
          ref={presence.ref}
          data-state={presence.status === 'open' ? 'open' : 'closed'}
        >
          Content
        </div>
      ) : null}
    </div>
  );
}
```

```css
[data-state='open'] {
  animation: panel-in 160ms ease-out;
}
[data-state='closed'] {
  animation: panel-out 160ms ease-in forwards;
}
@keyframes panel-in {
  from {
    opacity: 0;
    transform: translateY(-6px);
  }
}
@keyframes panel-out {
  to {
    opacity: 0;
    transform: translateY(-6px);
  }
}
@media (prefers-reduced-motion: reduce) {
  [data-state='open'],
  [data-state='closed'] {
    animation: none;
  }
}
```

## Signature

```ts
import { usePresence } from 'hono-preact-ui';

function usePresence(
  present: boolean,
  options?: UsePresenceOptions
): UsePresenceResult;

interface UsePresenceOptions {
  onExitComplete?: () => void; // fires when the exit resolves, before unmount
  timeoutCap?: number; // ms cap on the exit wait (default 3000)
}

interface UsePresenceResult {
  isPresent: boolean; // render the element while true (open or animating out)
  status: 'open' | 'closing' | 'closed'; // map to data-state (closing -> "closed")
  ref: (node: Element | null) => void; // attach to the animated element
}
```

## Options

`present` is the first positional argument (the desired visibility; flip it to
false to start the exit animation). The optional second argument is the options
object:

| Option           | Type         | Default | Notes                                                                 |
| ---------------- | ------------ | ------- | --------------------------------------------------------------------- |
| `onExitComplete` | `() => void` | none    | Runs when the exit resolves, immediately before `isPresent` is false. |
| `timeoutCap`     | `number`     | `3000`  | Safety cap (ms) so a stuck animation can never block teardown.        |

Gate rendering on `isPresent` and attach `ref` to the element that carries the
exit animation (or an ancestor of it, but never a sibling) merged with your
own ref via [mergeRefs](/docs/components/merge-refs). Drive `data-state` from
`status` (both `closing` and `closed` map to `"closed"`, so one
`[data-state="closed"]` rule styles the exit), or equivalently from your own
open flag; the library's own components do the latter. It reads
`Element.getAnimations({ subtree: true })` after a forced reflow, waits for every
exit animation to finish (with a `timeoutCap` safety net), and short-circuits
under `prefers-reduced-motion`. There is no exit on first mount or during SSR.

## Transition or keyframes

The exit can be a keyframe `animation` (above) or a plain CSS `transition`,
`usePresence` waits for either. A transition is often simpler: put the resting
values and a `transition` on the element, drive entry with `@starting-style`,
and the exit values on `[data-state="closed"]`.

```css
[data-state] {
  opacity: 1;
  transform: translateY(0);
  transition:
    opacity 160ms ease,
    transform 160ms ease;
}
@starting-style {
  [data-state='open'] {
    opacity: 0;
    transform: translateY(-6px);
  }
}
[data-state='closed'] {
  opacity: 0;
  transform: translateY(-6px);
}
@media (prefers-reduced-motion: reduce) {
  [data-state] {
    transition: none;
  }
}
```

Under the hood, `usePresence` reads `Element.getAnimations({ subtree: true })`,
which reports both transitions and keyframe animations, and if nothing is
running on the first read it waits for a `transitionrun`/`animationstart` to
bubble up before deciding there is no exit. That `subtree`/event handling is why
the animated element can be a child of the one you attach `ref` to, and why a
child whose `data-state` flips a render-tick later still animates.

**Exit animations must be finite.** An `animation-iteration-count: infinite`
exit is ignored (it would never resolve, blocking teardown), so the element
finalizes as if there were no exit, use a finite count with `forwards`. Entry
animations may loop freely; only the closing animation is awaited.