; } export default definePage(MovieView, { Wrapper: MovieWrapper }); ``` ## 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 // movies.server.ts import { defineLoader } from 'hono-preact'; export const serverLoaders = { default: defineLoader(async () => ({ movies: await getMovies() })), }; ``` ```tsx // reviews.tsx: a different page whose action should also refresh the movie list import { useAction } from 'hono-preact'; import { serverLoaders as moviesLoaders } from './movies.server.js'; import { serverActions } from './reviews.server.js'; const moviesLoader = moviesLoaders.default; const { mutate } = useAction(serverActions.addReview, { invalidate: [moviesLoader], // clears moviesLoader's cache on success }); ``` `invalidate` accepts an array of loader refs, so a single action can refresh multiple targets: `invalidate: [moviesLoader, ratingsLoader]`. Use `'auto'` instead of an array to invalidate the current page's loader only. ## How it works A page is a file pair: - `movies.server.ts`: the server loaders collected in a `serverLoaders` container. Never reaches the browser bundle. - `movies.tsx`: a pure component that consumes each loader's data via `.View()` (or `loader.useData()` inside a `loader.Boundary`) and is exported through `definePage(Component)`. `definePage(Component)` returns a routable component that self-wraps in `` with any page-level bindings. The route table in `routes.ts` declares which view and which `.server.ts` live at each URL via the `view` and `server` fields; the framework wires the rest. **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 is fired. 3. **Client-side navigation:** the Vite plugin replaces the `serverLoaders` import with a Proxy stub. 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: `loader.useData()` and the `.View()` render argument are typed `Serialize`, 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. The same `Serialize` applies to action results (`useAction().data`, `

`, `useActionResult()`). ## Timeouts Loaders get a deadline. By default every call has 30 seconds to finish; the deadline starts when the handler receives the request. Pass `timeoutMs` on `defineLoader` to override: ```ts export const slowReport = defineLoader( async () => { /* ... */ }, { timeoutMs: 60_000 } ); ``` Pass `timeoutMs: false` to opt out entirely (useful for long-running streams): ```ts export const longLivedStream = defineLoader( async function* () { /* yields indefinitely */ }, { timeoutMs: false } ); ``` When a deadline fires, the loader'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 framework default timeout is 30s. Override it per loader with `defineLoader({ timeoutMs })` (a number of milliseconds, or `false` to disable the timeout for that loader). ### Delaying the loading fallback On a fast connection a loader's `fallback` can flash on screen for a few milliseconds before the data lands, which reads as a flicker. The framework waits `fallbackDelay` milliseconds (default `100`) before mounting the fallback on a client navigation; if the response arrives first, the fallback never paints. Set it per loader: ```ts import { defineLoader } from 'hono-preact'; export const movie = defineLoader( async ({ location }) => fetchMovie(location.pathParams.id), { fallbackDelay: 200 } ); ``` Pass `fallbackDelay: 0` to show the fallback immediately. The delay applies in the browser only; server-rendered output is unchanged. Both `loader.Boundary` and `loader.View` inherit it. ## The server/client boundary 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. Any imported `serverActions` becomes a Proxy of action stubs. `serverLoaderValidationPlugin` fails the build if a `.server.*` file has unrecognised named exports. ## Options Pass a second argument to `defineLoader` to configure a loader: | Option | Type | Default | Description | | --------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------- | | `params` | `string[] \| '*'` | `[]` | Search params that change the cache key; `'*'` means any. | | `cache` | `LoaderCache` | auto | A shared cache; see Caching navigation results. | | `timeoutMs` | `number \| false` | `30000` | Per-loader deadline; `false` disables it. | | `fallbackDelay` | `number` | `100` | Delay (ms) before the loading fallback mounts on a client nav; `0` shows it immediately. | | `use` | `LoaderUse` | none | Per-loader middleware and stream observers. | Most options have a dedicated section above; this table is the at-a-glance summary. ## See also - [Loading States](/docs/loading-states): the loading and error UI for a loader's data. - [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. --- > Source: https://framework.sbesh.com/docs/loading-states # Loading States Show a loading UI during client-side navigation by passing a `fallback` to `loader.View()`, so users see a skeleton or spinner instead of a blank page while their data loads. ## 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 }) => (

{m.title}

), { fallback:

Loading…

} ); export default definePage(MoviesView); ``` ```ts // src/routes.ts { path: '/movies', view: () => import('./pages/movies.js'), server: () => import('./pages/movies.server.js'), } ``` `fallback` is rendered by the Suspense boundary `.View()` installs around the loader fetch. It only appears on client-side navigation; SSR and first-load hydration read from preloaded data and render immediately. ## When fallback shows | Navigation | Fallback shown? | | ---------------------------- | ---------------------------------------------- | | SSR (first load) | No. Data is preloaded into the HTML. | | Hydration | No. Client reads from `data-loader` attribute. | | Client-side nav (cache miss) | Yes, until the loader resolves. | | Client-side nav (cache hit) | No. Cached data renders immediately. | ## Using a skeleton Any Preact element works as a fallback, including a layout-matching skeleton: ```tsx const MoviesSkeleton = () => (

))}

); const MoviesView = moviesLoader.View( ({ data }) => (

{m.title}

), { fallback: } ); ``` ## Error fallback If the loader rejects, the boundary renders `errorFallback` instead of unwinding the page tree. Pass it alongside `fallback` in the same `.View()` options. The fallback may be an element or a function that receives the error and a `reset()` callback: ```tsx const MoviesView = moviesLoader.View( ({ data }) => (

{m.title}

), { fallback:

Loading…

, errorFallback: (err, reset) => (

Couldn't load movies: {err.message}

), } ); ``` Calling `reset()` clears the boundary so the next render attempt re-enters the loader. For runtime invalidation of cached data from elsewhere on the page, use [`useReload`](/docs/reloading) or [cross-page invalidation](/docs/loaders#cross-page-invalidation). ## `.View()` options reference Both options are passed as the second argument to `loader.View(render, opts)`: | Option | Type | Description | | --------------- | ---------------------------------------------------------- | ----------------------------------------------------------------- | | `fallback` | `ComponentChildren` | Shown while the loader is pending. | | `errorFallback` | `ComponentChildren \| ((err, reset) => ComponentChildren)` | Shown when the loader errors; the function form receives `reset`. | ## Page-level fallbacks `definePage` accepts a page-level `errorFallback` that catches errors from the rest of the page tree (e.g. a render-time throw outside any loader boundary): ```tsx export default definePage(MoviesView, { errorFallback: (err) =>

Something went wrong: {err.message}

, }); ``` Loader-specific loading and error UI lives on `.View()` / `.Boundary`. The page-level `errorFallback` is the outer safety net. ## See also - [Server Loaders](/docs/loaders): where `.View()` comes from. - [Streaming](/docs/streaming): fallback behavior 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(); }; return ( <>

{m.title}

); }); export default definePage(MoviesView); ``` **`src/routes.ts`** wires the URL to the view and its server module: ```ts { path: '/movies', view: () => import('./pages/movies.js'), server: () => import('./pages/movies.server.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: the current content stays visible while the new data fetches. There is no Suspense fallback shown during reload. Use `reloading` to reflect the in-progress state in your UI. ## 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 the loader is fetching, `false` otherwise. | ## See also - [Server Loaders](/docs/loaders): `loader.invalidate()` in context. - [Server Actions](/docs/actions): `useAction` invalidate option. - [Loading States](/docs/loading-states): the fallback shown 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` | 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. The consumer API (`loader.useData()`, `useAction`) is the same as for static loaders; only the author shape changes. ## 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 { 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` 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 Use `.View()` to create a component that re-renders on each new chunk. The render function receives the latest `data` value plus `error` and `reload`: ```tsx // src/pages/dashboard.tsx import { definePage } from 'hono-preact'; import { serverLoaders } from './dashboard.server.js'; const dataLoader = serverLoaders.default; const DashboardView = dataLoader.View( ({ data, error, reload }) => ( <> {error &&

Live updates paused: {error.message}

}

Count: {data.count}, load: {data.load}

), { fallback:

} ); export default definePage(DashboardView); ``` `loader.useData()` always returns the latest yielded value. `loader.useError()` returns the current error or `null`. 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 unblock another. ```ts // src/pages/movie.server.ts import { defineLoader } from 'hono-preact'; export const serverLoaders = { summary: defineLoader(async ({ location }) => getMovie(location.pathParams.id) ), cast: defineLoader(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; const Summary = summary.View(({ data }) => , { fallback: , }); const Cast = cast.View(({ data }) => , { fallback: , }); function MovieDetail() { return (

); } export default definePage(MovieDetail); ``` `

` and `` each own their Suspense boundary. `

` can paint immediately while `` is still streaming. Each `.View()` component gets a separate streaming-SSR registry key so the server can flush chunks for both concurrently. ## What happens on first paint 1. The server runs each `serverLoader` function and renders the page with first chunks for all loaders. The response stays open. 2. As subsequent chunks arrive, the server flushes `` tags inline into the ongoing HTML response, keyed per loader. 3. The browser receives and executes those tags as they arrive. On hydration, the client picks up from the latest pushed value for each loader and continues listening. The first-load experience is full SSR with progressive enhancement: the user sees real data immediately, and it keeps updating without a separate fetch or WebSocket. ## Errors **Before the first chunk:** the error propagates through the normal Suspense and error boundary path. If you provide `errorFallback` in `.View()`, it renders instead of the content. Otherwise the error boundary above catches it. **After the first chunk:** the stream is already open and the page is rendered. `error` in the `.View()` render function surfaces the error; `data` keeps returning the last good value. The page stays mounted with stale data visible. ```tsx const StatsView = dataLoader.View(({ data, error }) => ( <> {error &&

Live updates paused: {error.message}

}

Visitors: {data.visitors}

)); ``` ## 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 ``. 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 ; // 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. - [Loading States](/docs/loading-states): fallbacks while a stream fills. --- > 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 { defineLoader, type LoaderCtx } from 'hono-preact'; import { subscribeActivity, recentActivityEvents, type ActivityEvent, } from './activity-stream.js'; async function* activityStream( ctx: LoaderCtx ): AsyncGenerator { // Yield recent events first so the feed is not empty on connect. for (const e of recentActivityEvents(5)) yield e; const queue: ActivityEvent[] = []; let wake!: () => void; let wakeP = new Promise((r) => (wake = r)); const unsub = subscribeActivity((e) => { queue.push(e); wake(); }); ctx.signal.addEventListener('abort', () => { unsub(); wake(); }); while (!ctx.signal.aborted) { while (queue.length) yield queue.shift()!; await wakeP; wakeP = new Promise((r) => (wake = r)); } } export const serverLoaders = { default: defineLoader(shellLoader), activity: defineLoader(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 (

{events.length === 0 ? (

Listening for activity...

) : (

{e.actor}: {e.taskTitle}

)}

); } // The accumulating `.View` form (selected by `initial` + `reduce`) renders // through the loader's Suspense boundary, so the bar hydrates cleanly inside the // layout. `fallback` shows on SSR and until the first chunk; then `render` // receives the folded `data` and the connection `status`. const ActivityBar = activityLoader.View( ({ data, status }) => , { initial: [], reduce: (acc, e) => [e, ...acc].slice(0, MAX), fallback:

Connecting to activity...

, } ); export default function ProjectsShell({ children, }: { children: ComponentChildren; }) { return (

{children}

); } ``` 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`), so using the wrong form is a compile error. - `loader.View(render, { initial, reduce, fallback })` is the accumulating form of the standard consumption convention. It folds every chunk into accumulated state and renders through the loader's Suspense boundary, so a live widget hydrates cleanly inside a lazy layout: `fallback` renders during SSR and until the first chunk arrives, then `render` receives the accumulated `data` plus a `status`. ## On Cloudflare `publish()` and `route.liveLoader` have the same API 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. ## 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()` (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 The `status` field reports `'error'` / `'closed'` for failures and clean ends that happen _after_ the first chunk arrives. On the **initial** connect, a stream that fails, times out, or closes with zero chunks _before_ its first chunk is delivered through the loader's error boundary instead: the `errorFallback` renders (or the error propagates to the nearest boundary), and the render function's `status` is not updated. Live loaders normally yield immediately on connect (e.g. a backfill of recent events), so this only affects empty or pre-first-chunk-failing streams. A failed `reload()` behaves differently and more conveniently: because the component is already mounted, a reconnect that fails (at any point, including before its first chunk) surfaces as `status === 'error'` in the render function, not through the error boundary. That is exactly what makes the reconnect-on-error pattern above work in place. ## 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`. `data` becomes the folded accumulator and the render args carry a `status`. ```ts loader.View( render: (args: { data: Acc; status: StreamStatus; error: Error | null; reload: () => void; }) => ComponentChildren, opts: { initial: Acc; reduce: (acc: Acc, chunk: Serialize) => Acc; fallback?: ComponentChildren; errorFallback?: ComponentChildren; } ): FunctionComponent ``` `chunk` is `Serialize`: 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 rendered on SSR and before the first chunk arrives. | | `reduce` | `(acc: Acc, chunk: Serialize) => Acc` | Folds each incoming chunk (the JSON wire shape) into the accumulated value. Called for every chunk in order. | | `fallback` | `ComponentChildren` | Rendered on SSR and while the stream is connecting (before the first chunk). | The `render` function receives: | Field | Type | Description | | -------- | --------------- | ------------------------------------------------------------------------------------------------- | | `data` | `Acc` | Current accumulated value. Starts as `initial`, updated after each chunk. | | `status` | `StreamStatus` | Connection state: `'connecting'`, `'open'`, `'closed'`, or `'error'`. | | `error` | `Error \| null` | Set when `status === 'error'`. | | `reload` | `() => void` | Resubscribe: aborts the current stream, resets `data` to `initial`, reconnects, and folds afresh. | `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.liveLoader({ topic, load })` subscribes any connected client to that topic and pushes a fresh data snapshot on every publish. ## 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')(). No payload; the subscriber // calls load() for the fresh value. Published with no message argument. export const counterChannel = defineChannel('counter')(); ``` **`counter.server.ts`** (server module for the `/counter` route): ```ts import { serverRoute } from 'hono-preact'; import { counterChannel } from './counter-channel.js'; import { getCount } from './counter-db.js'; const route = serverRoute('/counter'); export const serverLoaders = { count: route.liveLoader({ // 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. const CountDisplay = countLoader.View( ({ data, status }) => (

Count: {data}

Status: {status}

), { initial: 0, reduce: (_acc, chunk) => chunk, fallback:

Connecting...

, } ); export default function CounterPage() { return (

); } ``` **`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` that ties publish and subscribe together at the type level. 2. **Subscribe** from a `serverLoaders` entry using `route.liveLoader({ topic, load })`. The loader runs `load` once on connect and again on every publish to `topic`. 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` function in `liveLoader` receives the same `ctx` as `load`, so it can read `ctx.location.pathParams` to key the subscription to the route: ```ts const route = serverRoute('/board/:boardId'); export const serverLoaders = { tasks: route.liveLoader({ 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)()` 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). | Returns a `Channel` with one method: | Method | Signature | Description | | ---------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `channel.key(params?)` | `(...args) => Topic` | Builds a branded `Topic`. 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

` | The topic to publish to. Built with `channel.key(params)`. | | `message` | `P` | Required for payload channels; omitted for `void` (signal) channels. | ### `route.liveLoader({ topic, load })` Defines a channel-driven live loader inside a `serverLoaders` object. Yields the result of `load` once on connect, then re-runs and pushes on every publish to `topic`. | Option | Type | Description | | ----------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------- | | `topic` | `(ctx: LoaderCtx) => Topic` | Returns the topic this loader subscribes to. Called with the same context as `load`. | | `load` | `(ctx: LoaderCtx) => Promise` | Produces the data snapshot. Called on connect and on every publish. | | `use` | `ReadonlyArray` | Optional guard/middleware chain run on the subscription (same inheritance as a non-live loader's `use`). | | `cache` | `LoaderCache` | Optional cache shared across `load` calls. | | `timeoutMs` | `number \| false` | Timeout per `load` call. Defaults to `false` (no cap). | Returns a `LoaderRef`. 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. ### Type exports ```ts import type { Channel, Topic, LiveLoaderOptions } 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 `` can infer the payload and result types without codegen. ### `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`. ## 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: `` `` is the primary way to invoke an action. Pass the action stub directly to the `action` prop. On the client, `` 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 = () => ( ); const MoviesView = dataLoader.View(({ data }) => (

{m.title}

)); export default definePage(MoviesView); ``` `

` accepts any HTML `` attribute (except `onSubmit`, which it owns), plus `action` (required). The wrapping `

` 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, ``) 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 `` 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 setShowForm(false)} > ``` `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 ` ); }; ``` `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. ## 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 { movies } = moviesLoader.useData(); const { mutate, pending, error } = useAction(serverActions.addMovie, { invalidate: 'auto', onSuccess: (data) => console.log('added', data), }); return ( <> {error &&

{error.message}

} ); }; ``` `useAction` posts to the page URL with `Accept: application/json` and returns a discriminated result. The action body runs identically whether called from `

` or `useAction`. ### Options | Option | Type | Description | | ------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invalidate` | `'auto' \| false \| LoaderRef[]` | `'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. Return value is passed to `onError` as `snapshot` for optimistic rollback. | | `onSuccess` | `(data) => void` | Called with the action's return value on success. | | `onError` | `(err, snapshot) => void` | Called with the error and the `onMutate` snapshot on failure. | | `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 \| 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 \| 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. ## 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 `

`, 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 ?

Saving...

: 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 { movies } = moviesLoader.useData(); const [items, setItems] = useState(movies.results); 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 ``. ## 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 `` serializes file inputs as `File` instances in the payload, file uploads work transparently when you pair it with `useAction`. **With ``:** add a file input; the framework detects the `File` value in the payload and sends FormData: ```tsx const UploadPosterForm = ({ movieId, setPosterUrl }) => ( ); ``` **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, ``) 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 `

` (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 action plus every loader under a route), declare `use` on the route node in `src/routes.ts`. See [Middleware](/docs/middleware) for the full chain model. ## 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` or `serverActions`. 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 ``: opt-in client pre-validation before the POST fires. - **Loader search params** via `defineLoader(fn, { searchSchema })`: validates and coerces `ctx.location.searchParams`. - **Loader route params** via `defineLoader(fn, { paramsSchema })` (or `serverRoute(id).loader(fn, { paramsSchema })`): validates and coerces `ctx.location.pathParams`. **The server is always authoritative.** Client-side validation (the `` 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 ( {issues && (

{issue.message}

)}

); }; ``` ## Form client pre-validation Pass `schema` to `

` 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 `` **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 = () => ( Title ); const CreateTaskForm = () => ( ); ``` Spreading `useFieldErrorProps('title')` onto the input associates it with its `` 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` 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 **``** renders the first error message for a field, or nothing. It is a thin convenience wrapper around `useFieldErrors()`. ```tsx {/* Form-level errors (issues with no field path) */} ``` **`useFieldErrors()`** returns the full `FieldErrorsMap` (a `Record`) for custom rendering. It reads from form context and is only useful inside a `

`. ```tsx import { useFieldErrors } from 'hono-preact'; const TitleField = () => { const errors = useFieldErrors(); const titleErrors = errors['title'] ?? []; return ( Title {titleErrors.length > 0 && (

{msg}

)} ); }; ``` **`useFieldErrorProps(name)`** returns the ARIA props to spread onto a field control (``/`

); }; ``` `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 `

` 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[]` | 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 (

{m.title}

); }; ``` `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 `` `useOptimisticAction` returns a stub-compatible value that you can pass directly to ``. 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 ( <>

Current: {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 movies = moviesLoader.useData();
  return (
    <ul>
      {movies.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/view-transitions

# View Transitions

The framework wraps every same-document route change in `document.startViewTransition` automatically. You don't opt in. 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 via `::view-transition-group(.post-card)` in CSS.

## 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>`.

## 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.

## 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 all its descendants (render + their loaders/actions). |
| 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',
    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 { defineLoader, defineAction } from 'hono-preact';
import { auditLog } from '../../audit.js';

// requireSession is declared on the route node in routes.ts and
// covers both render and RPC paths for this entire subtree.
export const serverLoaders = {
  default: defineLoader(async () => listAdminRows()),
};

export const serverActions = {
  promote: defineAction(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, covering both the render path and the RPC paths (loaders and actions). 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.

```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 request 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.

`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.

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
pnpm create hono-preact my-app
```

This scaffolds `my-app/`, installs dependencies, and initializes a git repo. Then:

```bash
cd my-app
pnpm dev
```

### Options

| Flag                           | Default       | Description                                                         |
| ------------------------------ | ------------- | ------------------------------------------------------------------- |
| `--adapter=<cloudflare\|node>` | `cloudflare`  | Target runtime. `cloudflare` for Workers, `node` for a Node server. |
| `--no-install`                 | install runs  | Skip the dependency install step.                                   |
| `--no-git`                     | git init runs | Skip initializing a git repository.                                 |
| `--version`, `-v`              |               | Print the CLI version.                                              |
| `--help`, `-h`                 |               | Print usage.                                                        |

## 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.              |
| `clientEntry` | `string`            | `'virtual:hono-preact/client'` | Client entry module id.                                           |

## What the plugin handles

`honoPreact()` configures everything the framework requires:

| Concern              | What it sets                                                                                                                                                                                              |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Preact deduplication | `resolve.dedupe` for `preact`, `preact/compat`, `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                                          |

## 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.

---

> 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'), server: () => import('./pages/project.server.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.

### `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 and fallback bindings live on `serverLoaders.name.View()` inside the page's JSX.
- **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({})`. 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` or `serverActions`.
- **`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/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 lets you register any hand-authored WS route in `api.ts` on the same connection, following the same Hono pattern as before, but now imported from `hono-preact` directly.

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, serverRoute } from 'hono-preact';

const route = serverRoute('/chat');

export const serverSockets = {
  chat: defineSocket<
    { text: string }, // messages the client sends
    { text: string; from: string } // messages the server sends
  >({
    // Optional guard middleware. A failing guard closes the socket with 4403.
    use: [route.use],

// 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. Declare its shape with the third type parameter: `defineSocket<Incoming, Outgoing, Data>()`. It is `undefined` by default (no `data` factory). On Node the handler may mutate it across events (open/message/close share the same object). On Cloudflare each event sees the connect-time value (the Durable Object hibernates between events), so per-connection state that must survive across messages on Cloudflare belongs in external storage.

### 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 any `use` on the enclosing route node (via `serverRoute`), then the socket's own `use` array. Route-node and layout `use` guards are inherited, so a guard that protects a route also covers its sockets and rooms without having to be repeated. Add socket-specific authorization in the socket's own `use` array for concerns that only apply to the socket.

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.

A plain socket does not receive route path params in an inherited route-node guard. The upgrade is served from the framework's flat `/__sockets` endpoint, which is query-string only, so `ctx.location.pathParams` is empty for a socket connection. Param-dependent authorization for a socket must read the connection's query or headers in the socket's own `use` (or in `open`), not rely on a `:param` from the route the socket lives next to. (Rooms differ: a room's guard chain can read the room-key params via `ctx.location.pathParams`, because the room key rides the wire and is resolved server-side before the guard runs. See [Rooms](/docs/rooms).)

### 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 pairs its own Durable Object.)

### 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;
```

`upgradeWebSocket` resolves the correct adapter at request time (Cloudflare Workers or Node), so the same `api.ts` code works across adapters without conditional imports.

### 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

On Cloudflare the Worker runtime handles the upgrade natively. `upgradeWebSocket` from `hono-preact` routes through `hono/cloudflare-workers` under the hood, so no extra peer install is needed. The same handler runs in `vite dev` (because the Cloudflare adapter boots workerd via `@cloudflare/vite-plugin`) and in a deployed Worker.

For long-lived stateful connections, Cloudflare's recommended pattern is to pair with a Durable Object that owns the connection state. From hono-preact's perspective the handler in `api.ts` is unchanged.

## 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) => Data \| Promise<Data>`            | Edge factory run once at the upgrade with the live Context; 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, so keep it small. |
| `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`                  | `Data`                    | Per-connection data seeded by the `data` factory at connect time. On Node, mutable across events. On Cloudflare, the connect-time value only (cross-event mutable state goes to external storage). |
| `raw`                   | `unknown`                 | Escape hatch to the underlying runtime socket.                                                                                                                                                     |

### `ref.useSocket(opts?)` / `useSocket(ref, opts?)`

| Option                 | Type                                 | Default   | Description                                                                                |
| ---------------------- | ------------------------------------ | --------- | ------------------------------------------------------------------------------------------ |
| `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/ws` upgradeWebSocket, resolved at request time so the same handler works across adapters.

| 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,
} from 'hono-preact';
```

## 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);
      },
    });

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 route-node `use` (from `serverRoute`, if the room lives next to a route) then the room's own `use`:

```ts
export const serverRooms = {
  cursors: defineRoom(cursorsChannel, {
    // The room's own guard, composed after the inherited app and route-node use.
    use: [requireBoardAccess],
    // ...
  }),
};
```

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.

## 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).

Two behaviors differ between Node and Cloudflare:

- **Plain sockets (`defineSocket`/`useSocket`) now work on Cloudflare.** The worker guards the upgrade at the edge and forwards it to a per-connection Durable Object running under the Hibernation API. 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 edge-seeded, not mutation-persistent.** Treat `conn.data` as read-only metadata captured by the `data()` factory at upgrade time. An in-place mutation to it in `onJoin` is not guaranteed to survive to later events on every runtime (on Cloudflare each event reads a freshly deserialized attachment). Use `setPresence` for per-connection state that evolves.

## 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>`                      | 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`. Use it to capture request-derived data (authenticated user, headers) at upgrade time. |
| `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`                  | `Data`   | Per-connection metadata seeded by the `data()` factory; treat as read-only (use `setPresence` for evolving state). |
| `close(code?, reason?)` | method   | Close this connection.                                                                                             |

### `ref.useRoom(opts?)` / `useRoom(ref, opts?)`

| 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,
} from 'hono-preact';
```

## 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 hoofd's `useTitle`, `useMeta`, and `useLink` hooks:

```tsx
import { useTitle } from 'hoofd/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",
  },
}
```

`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. 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

```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>

## 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>

## 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>`.

### Popover.Description

Optional supporting text, wired to the popup's `aria-describedby` while it is
rendered. Default element `<p>`.

### 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>

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>`.

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`.

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>

## 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">`.

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>`.

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. Default element `<div>`
with `role="group"`.

| Prop            | Type                                 | Default | Description                                           |
| --------------- | ------------------------------------ | ------- | ----------------------------------------------------- |
| `render`        | `RenderProp`                         | -       | Compose or replace the element.                       |
| `value`         | `string`                             | -       | Controlled selected value. Pair with `onValueChange`. |
| `defaultValue`  | `string`                             | -       | Initial selected value when uncontrolled.             |
| `onValueChange` | `(value: string) => 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`.

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>

## 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>`.

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"`.

### ContextMenu.CheckboxItem

A toggle row that holds its own checked state. Default element `<div>` with
`role="menuitemcheckbox"`.

Sets `aria-checked` and `data-checked` (present when checked).

### ContextMenu.RadioGroup

Single-select context for the radio items inside it. Default element `<div>`
with `role="group"`.

### ContextMenu.RadioItem

A choice within a `ContextMenu.RadioGroup`. Default element `<div>` with
`role="menuitemradio"`.

Sets `aria-checked` and `data-checked` (present when checked).

### ContextMenu.Separator

A horizontal divider between groups of items. Default element `<div>` with
`role="separator"`.

### 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`.

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.

### ContextMenu.SubmenuTrigger

The row that opens the submenu. It is itself a `menuitem` in the parent menu.
Default element `<div>` with `role="menuitem"`.

### 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>

A multiple select toggles each option and stays open; the trigger joins the
selected labels.

</Example>

## Usage

Set `multiple` on `Select.Root` for multi-selection: picking an option toggles
it and keeps the popup open, and the value becomes an array. Pass a `value` /
`onValueChange` pair to control the selection, 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.

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 \| Value[]`                  | -           | Controlled selection. Pair with `onValueChange`. An array in multiple mode. |
| `defaultValue`   | `Value \| Value[]`                  | -           | Initial selection when uncontrolled.                                        |
| `onValueChange`  | `(value: Value \| Value[]) => void` | -           | Called when the selection changes.                                          |
| `multiple`       | `boolean`                           | `false`     | Allow more than one selection; the value becomes an array.                  |
| `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>`.

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`.

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>

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>

Creatable: when nothing matches, a "Create …" option appears and adds the new
value through `onCreate`.

</Example>

With `autocomplete="both"`, the input inline-completes to the first match; Enter
or Tab accepts it, Backspace dismisses it and keeps typing.

</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 \| Value[]`                  | -           | Controlled selection. Pair with `onValueChange`.                                                |
| `defaultValue`      | `Value \| Value[]`                  | -           | Initial selection when uncontrolled.                                                            |
| `onValueChange`     | `(value: Value \| Value[]) => void` | -           | Called when the selection changes (not called for `create` options).                            |
| `multiple`          | `boolean`                           | `false`     | Allow more than one selection; value becomes an array; popup stays open on pick.                |
| `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. 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`.

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>

## 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>

## 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>

## 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>

## 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>

## 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';

## 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>

## 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>

## Signature

```ts
import { useListboxSelection } from 'hono-preact-ui';

function useListboxSelection<Value = string>(
  opts: UseListboxSelectionOptions<Value>
): ListboxSelection;
```

## Options

| Option           | Type                               | Notes                                                                                         |
| ---------------- | ---------------------------------- | --------------------------------------------------------------------------------------------- |
| `value`          | `Value \| Value[] \| undefined`    | The controlled selected value(s).                                                             |
| `setValue`       | `(next: Value \| Value[]) => void` | Called with the next selection: a bare `Value` in single-select, a `Value[]` in multi-select. |
| `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`.           |

---

> 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>

## 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';

// 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>

## 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>

## Example

```tsx
import { useDismiss } from 'hono-preact-ui';
import { useRef } from 'preact/hooks';

## 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>

## Example

```tsx
import { useFocusReturn } from 'hono-preact-ui';
import { useRef } from 'preact/hooks';

## 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>

## 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>

## Example

```tsx
import { usePresence } from 'hono-preact-ui';
import { useState } from 'preact/hooks';

```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.

Movies

Movies

Movies

{id}

About

{data.movie.title}

{data.title}