@ui-sdk/vue 0.0.0-stage → 0.1.0-beta.1

package/docs/llms.txt

@@ -0,0 +1,1502 @@
+# ui-sdk for Vue
+
+> @ui-sdk/vue renders ui-sdk's framework-free TypeScript core in Vue. How an interface behaves lives in the core; @ui-sdk/vue turns each primitive into parts. No styles, no dependencies, no providers, no portals.
+
+This file is the context an agent needs to build with @ui-sdk/vue: how Vue renders a primitive and the conventions every part shares, then every component with a link to its page. Read the pages of the components you use. It's generated from the docs, for this release.
+
+- [Core](./core.md): build a component, compose behaviors, and explore the foundations, from defining a primitive to working with state, the browser and text.
+- [Agents](./agents.md): letting an agent operate a page, and WebMCP.
+
+## Introduction
+
+These docs cover ui-sdk in Vue. Using another framework? See React, Svelte, Solid or Web Components. To build your own components from behaviors, see [Core](./core.md).
+
+`@ui-sdk/vue` gives you components such as Select, Dialog, and Tabs, built on ui-sdk's behaviors. They handle interactions, focus, and ARIA attributes. You choose their markup and styles.
+
+Import the parts you need, put them together in your app, and style them with your own CSS.
+
+### Quick Start
+
+Copy this prompt into your agent:
+
+```text prompt
+Set up ui-sdk in this Vue project. It needs Vue 3.5 or newer.
+
+1. Install @ui-sdk/vue and @ui-sdk/core with the project's package manager.
+2. Add a note to AGENTS.md, creating it if needed: before using ui-sdk, follow the ui-sdk skill if it's installed, and read node_modules/@ui-sdk/vue/docs/llms.txt. To build a new component, also search node_modules/@ui-sdk/vue/docs/core.md by heading, and read rendering.md next to it.
+3. If you support skills, run: npx skills add vercel-labs/ui --skill ui-sdk
+```
+
+It installs ui-sdk and points your `AGENTS.md` at the docs that ship with the packages.
+
+### Set It Up Yourself
+
+- [Installation](./installation.md): Install the packages in your Vue app.
+- [First Component](./first-component.md): Add and style your first component.
+
+### Explore the Components
+
+The [Using Components guides](./parts-and-composition.md) cover patterns the components share, such as composing parts, handling state, and styling.
+
+## Installation
+
+Start with an app using Vue 3.5 or newer.
+
+### Install the Packages
+
+```bash
+npm install @ui-sdk/vue @ui-sdk/core
+```
+
+`@ui-sdk/vue` provides the Vue components. `@ui-sdk/core` provides their behavior and is a peer dependency. Install both so the components and any helpers you use share one copy of the core.
+
+### Import a Component
+
+Import each component from its own entry:
+
+```ts
+import { Button } from "@ui-sdk/vue/button"
+import { Toggle } from "@ui-sdk/vue/toggle"
+```
+
+A Dialog has separate parts for its trigger, content, and title. Import those parts from the same entry:
+
+```ts
+import {
+  Dialog,
+  DialogContent,
+  DialogTitle,
+  DialogTrigger,
+} from "@ui-sdk/vue/dialog"
+```
+
+Each [component page](./README.md) lists the parts you can use.
+
+### Use with Nuxt
+
+Install the same two packages in a Nuxt app, then add `@ui-sdk/vue` to its modules:
+
+```ts title="nuxt.config.ts"
+export default defineNuxtConfig({
+  modules: ["@ui-sdk/vue"],
+})
+```
+
+Nuxt finds the module at `@ui-sdk/vue/nuxt`. It registers each part of every entry as an auto-imported component, like `<DialogTrigger>`, and auto-imports their other exports, like `createDialogController`, in `<script>`. Each one is still imported from its own entry, so a page bundles only what it uses. When a name clashes, your own component or `utils/` export wins. `confirm` is left out because it would replace the browser's `confirm()` in your code, so import it from `@ui-sdk/vue/alert-dialog`.
+
+The module adds no plugin and no styles. Components render on the server and hydrate in the browser without one, so importing them from their entries, as above, works in Nuxt too.
+
+Pass `prefix` to use ui-sdk's components beside your own of the same name:
+
+```ts title="nuxt.config.ts"
+export default defineNuxtConfig({
+  modules: ["@ui-sdk/vue"],
+  uiSdk: { prefix: "U" },
+})
+```
+
+With that prefix, `<DialogTrigger>` becomes `<UDialogTrigger>`. Other exports keep their names.
+
+### Add Your Styles
+
+Components are unstyled, so you style them with your app's CSS or with Tailwind CSS. [Styling and Animation](./styling-and-animation.md) covers both.
+
+You can render your first component without setting up a provider, importing a UI SDK stylesheet, or adding a portal root. [Server Rendering](./server-rendering.md) covers rendering the initial HTML and adding interactions during hydration, in Nuxt or your own server. If your Nuxt app sends a Content Security Policy, [Content Security Policy](./styling-and-animation.md#content-security-policy) covers nuxt-security.
+
+### Right to Left
+
+Set `dir="rtl"` on the page or a container. Arrow keys and popup placement follow that direction without a provider. Use logical CSS properties, such as `padding-inline-start`, for your styles.
+
+Continue with [First Component](./first-component.md) to add a working toggle to your app.
+
+## First Component
+
+Let's add a Bookmark toggle. Press it once to turn it on, then again to turn it off.
+
+If you haven't installed the packages yet, start with [Installation](./installation.md).
+
+### Create the Component
+
+Create `bookmark-button.vue` next to your app component and render a `Toggle`:
+
+```vue title="bookmark-button.vue"
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle>Bookmark</Toggle>
+</template>
+```
+
+`Toggle` renders a button. It keeps track of its pressed state, handles Enter and Space, and sets `aria-pressed` for screen readers.
+
+### Use It in Your App
+
+In your app component (`App.vue` here), import and render `BookmarkButton`:
+
+```vue title="App.vue"
+<script setup lang="ts">
+import BookmarkButton from "./bookmark-button.vue"
+</script>
+
+<template>
+  <BookmarkButton />
+</template>
+```
+
+Open your app. You should see a button labeled Bookmark. Next, add styles so you can tell when it is pressed.
+
+### Add Styles
+
+When the toggle is pressed, it has a `data-pressed` attribute. Use that attribute to change its appearance.
+
+With Tailwind CSS configured in your app, add utility classes to `class`. The `data-pressed:` variant applies while the toggle is pressed:
+
+```vue title="bookmark-button.vue"
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle
+    class="inline-flex h-8 items-center rounded-md border border-neutral-300 px-3 text-sm font-medium hover:bg-neutral-100 focus-visible:outline-2 focus-visible:outline-offset-2 data-pressed:bg-neutral-900 data-pressed:text-white"
+  >
+    Bookmark
+  </Toggle>
+</template>
+```
+
+Try the styled toggle:
+
+```vue title="first-component.vue"
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle data-variant="outline"> Bookmark </Toggle>
+</template>
+```
+
+Click Bookmark to turn it on or off. A filled background means it is on. You can also focus the button with Tab and press Enter or Space.
+
+Keep the label the same in both states. `aria-pressed` tells a screen reader whether the toggle is on.
+
+### Keep Going
+
+- [Toggle](./components/toggle.md) covers disabled states, controlled state, and groups of toggles.
+- [Components](./README.md) lists the other components you can add with the same install.
+- [Parts and Composition](./parts-and-composition.md) shows how to put a component with several parts together.
+- [State and Events](./state-and-events.md) shows how to read changes and control state from your app.
+- [Styling and Animation](./styling-and-animation.md) covers state attributes, CSS variables, and transitions.
+
+## Parts and Composition
+
+A component can have several parts. A Popover has a root to hold its state, a trigger to open it, and content to show.
+
+### Put Parts Together
+
+Import the parts you need and nest them as shown in the component's Composition:
+
+```vue
+<script setup lang="ts">
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+</script>
+
+<template>
+  <Popover>
+    <PopoverTrigger>Details</PopoverTrigger>
+    <PopoverContent>
+      <PopoverTitle>Project Details</PopoverTitle>
+      <p>Last updated today.</p>
+      <PopoverClose>Done</PopoverClose>
+    </PopoverContent>
+  </Popover>
+</template>
+```
+
+`Popover` shares state without adding an element. Other roots, such as `Tabs`, do render an element. Parts find their root through the framework's context, so you can put your own components between them.
+
+### Choose the Element
+
+Render a menu item as a link:
+
+```vue
+<script setup lang="ts">
+import { Menu, MenuContent, MenuItem, MenuTrigger } from "@ui-sdk/vue/menu"
+</script>
+
+<template>
+  <Menu>
+    <MenuTrigger>Account</MenuTrigger>
+    <MenuContent>
+      <MenuItem href="/settings">
+        <template #render="{ props }">
+          <a v-bind="props">Settings</a>
+        </template>
+      </MenuItem>
+    </MenuContent>
+  </Menu>
+</template>
+```
+
+The `#render` slot receives the part's `props` and `state`. Bind the props with `v-bind="props"` to keep the part's behavior connected. It also receives `children`, the part's own content, like a slider thumb's range input: render it inside your element with `<component :is="children" />`. A component works too: the part binds to its root element, so give the component one element at its root.
+
+Your event handler runs first. Calling `event.preventDefault()` skips the built-in handler. Keep the supplied roles, IDs, and ARIA state when rendering your own element. A name or typing hint you pass replaces the part's own: `aria-label`, `aria-labelledby`, `aria-description`, `title`, `autocomplete`, `autocapitalize`, `autocorrect`, `inputmode` and `spellcheck`. Roles, `tabindex`, references like `aria-controls` and `aria-describedby`, state attributes and `data-slot` stay the part's, since its behavior reads them.
+
+### Read the State
+
+The part can pass its state to its content:
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle v-slot="{ state }" aria-label="Mute">{{
+    state.pressed ? "Mute on" : "Mute off"
+  }}</Toggle>
+</template>
+```
+
+Keep the accessible name stable when the content changes. Here, `aria-label="Mute"` names the toggle and `aria-pressed` reports its state.
+
+### Name the Control
+
+Use the component's label or title part, such as `FieldLabel` or `DialogTitle`. Give controls without visible text an `aria-label`.
+
+[Custom Parts](./custom-parts.md) covers writing a part with logic of its own.
+
+## State and Events
+
+Components manage their own state unless you pass a controlled value. A change callback lets you respond in either case.
+
+### Set the Starting Value
+
+Use a default prop to choose the starting state. Here, Bold starts pressed and changes when you click it:
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle default-pressed>Bold</Toggle>
+</template>
+```
+
+The prop depends on the component: `default-pressed`, `default-checked`, `default-open`, or `default-value`.
+
+### Control the Value
+
+Use `v-model` when the parent needs the current value:
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+import { ref } from "vue"
+
+const pressed = ref(false)
+</script>
+
+<template>
+  <Toggle v-model="pressed">Bold</Toggle>
+  <output>{{ pressed ? "On" : "Off" }}</output>
+</template>
+```
+
+`v-model` keeps the toggle’s `pressed` value in your ref. `v-model:pressed` works here too. Clicking Bold changes both the button and the output.
+
+The main value depends on the component: `checked` for Checkbox, `open` for Popover, and `value` for Select. Name another binding when you need it, such as `v-model:open` on Select or `v-model:query` on Combobox.
+
+If you pass `:pressed` without `v-model`, update that value yourself in `@pressed-change`. A value the parent never updates stays fixed.
+
+To keep a value in the URL, update your ref through `v-model` or the event, then call `router.push`. A value that changes only when the navigation finishes leaves the component showing the old one until then, and logs a warning in development.
+
+### Respond to a Change
+
+Events such as `@pressed-change` receive the requested value and `details`. They run before `v-model` updates.
+
+| Detail     | What It Tells You                                                                                |
+| ---------- | ------------------------------------------------------------------------------------------------ |
+| `reason`   | What requested the change, such as `press` or `outside-press`. Each component lists its reasons. |
+| `event`    | The DOM event, when there is one.                                                                |
+| `source`   | `keyboard`, `mouse`, `touch`, `pen`, `virtual`, `programmatic`, or `agent`.                      |
+| `cancel()` | Stops the requested change.                                                                      |
+
+For example, keep a popover open when someone clicks outside it:
+
+```vue
+<script setup lang="ts">
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+
+function keepOpen(
+  open: boolean,
+  details: { reason: string; cancel: () => void }
+) {
+  if (!open && details.reason === "outside-press") {
+    details.cancel()
+  }
+}
+</script>
+
+<template>
+  <Popover @open-change="keepOpen">
+    <PopoverTrigger>Details</PopoverTrigger>
+    <PopoverContent>
+      <PopoverTitle>Project Details</PopoverTitle>
+      <p>Last updated today.</p>
+      <PopoverClose>Done</PopoverClose>
+    </PopoverContent>
+  </Popover>
+</template>
+```
+
+The Done button still closes it. Cancellation also works when you control the value. Add `debug` to a root to log changes while you work.
+
+### Empty and Multiple Values
+
+Select, Tabs, and Radio Group report `null` when nothing is selected. A multiple Select or Combobox uses an array. Accordion and Toggle Group always use arrays.
+
+To change a component from outside its parts, use a [Controller](./controllers.md).
+
+## Styling and Animation
+
+Parts render without styles. The component demos use plain CSS, and the same state attributes and CSS variables work with Tailwind CSS or any other stylesheet.
+
+### Style a Part
+
+Every part has a `data-slot` attribute. State adds attributes such as `data-pressed` and `data-disabled`:
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle
+    class="rounded-md border border-neutral-300 px-2.5 py-1.5 text-sm data-pressed:bg-neutral-100 data-disabled:opacity-50"
+    >Bold</Toggle
+  >
+</template>
+```
+
+Vue's `class` and `style` bindings accept strings, arrays, and objects. They aren't functions of the part's state. Use data attributes, or read `state` in a `#render` slot.
+
+Most state attributes are present or absent. Others have values, such as `data-side="top"`. Each component's Styling section lists its attributes and CSS variables. Use those rather than generated IDs.
+
+### CSS Modules
+
+Import a CSS Module and pass its class to the part. State selectors work the same way:
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+import styles from "./toggle.module.css"
+</script>
+
+<template>
+  <Toggle :class="styles.toggle">Bold</Toggle>
+</template>
+```
+
+```css title="toggle.module.css"
+.toggle {
+  cursor: default;
+  border: 1px solid var(--input, #e5e5e5);
+  border-radius: 1.125rem;
+  background: transparent;
+  padding: 0.375rem 0.625rem;
+  color: inherit;
+  font: inherit;
+  font-size: 0.875rem;
+}
+
+.toggle[data-pressed] {
+  background: var(--muted, #f5f5f5);
+}
+
+.toggle[data-disabled] {
+  opacity: 0.5;
+}
+
+.toggle:focus-visible {
+  outline: 2px solid var(--ring, #a3a3a3);
+  outline-offset: 2px;
+}
+```
+
+### Animate Opening and Closing
+
+Popup content gets `data-starting-style` before it enters and `data-ending-style` while it exits. It stays mounted until the exit transition or animation finishes:
+
+```vue
+<script setup lang="ts">
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+</script>
+
+<template>
+  <Popover>
+    <PopoverTrigger>Details</PopoverTrigger>
+    <PopoverContent
+      class="origin-(--transform-origin) transition-[opacity,scale] duration-150 data-starting-style:scale-96 data-starting-style:opacity-0 data-ending-style:scale-96 data-ending-style:opacity-0 motion-reduce:transition-none"
+    >
+      <PopoverTitle>Project Details</PopoverTitle>
+      <p>Last updated today.</p>
+      <PopoverClose>Done</PopoverClose>
+    </PopoverContent>
+  </Popover>
+</template>
+```
+
+Put exit styles on `data-ending-style`. `data-closed` describes the state but doesn't keep the element around for an exit.
+
+Popups provide `--anchor-width` and `--available-height` for sizing. [Popups](./popups.md) covers mounting and placement.
+
+### The ui-sdk Layer
+
+A few behaviors need a little CSS, like keeping a closed popup hidden or dimming the page behind a sheet, so ui-sdk adds it to the page in a cascade layer named `ui-sdk`. Declare that layer at the top of your global stylesheet, the one `main.ts` or `nuxt.config.ts` loads, so your own styles win over it wherever the page puts them. With Tailwind, put it above `@import "tailwindcss"`:
+
+```css
+@layer ui-sdk;
+```
+
+A component's `<style>` block loads with the component, too late to come first, so keep the line in the global stylesheet.
+
+ui-sdk adds this CSS once a component mounts, so HTML rendered on the server doesn't have it until the page hydrates. Closed content kept in the page, like a tooltip's, carries `hidden`, and a class that sets `display` shows it until then. Tailwind's base styles already hide `hidden` elements. With other CSS, add the same rule to your global stylesheet:
+
+```css
+@layer ui-sdk {
+  :where([data-slot][hidden]:not([hidden="until-found"])) {
+    display: none !important;
+  }
+}
+```
+
+It leaves `hidden="until-found"` alone, so find in page can still open a closed panel.
+
+### Content Security Policy
+
+A Content Security Policy without `'unsafe-inline'` in `style-src` blocks the CSS ui-sdk adds. Give ui-sdk your policy's nonce with a meta tag in the page's `<head>`:
+
+```html
+<meta property="csp-nonce" nonce="your-nonce" />
+```
+
+With Vite, set `html.cspNonce` in your Vite config to a placeholder, and Vite writes this tag for you. Your server replaces the placeholder with a new nonce on each request.
+
+In Nuxt, the nuxt-security module writes the tag only in development. For production, add a Nitro plugin, like `server/plugins/csp-nonce.ts`, that writes it into every page with the module's nonce:
+
+```ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook("render:html", (html, { event }) => {
+    html.head.push(
+      `<meta property="csp-nonce" nonce="${event.context.security.nonce}">`
+    )
+  })
+})
+```
+
+Pages rendered on the server also carry a few `style` attributes, like the one that hides a select's native input, so the policy needs `style-src-attr 'unsafe-inline'` too.
+
+If your policy has no nonce for styles, add the tag without the `nonce` attribute. ui-sdk then adds its CSS as constructed style sheets, which no policy blocks. In Nuxt, `useHead` leaves out a meta tag without `content`, so give it one. ui-sdk doesn't read it: `useHead({ meta: [{ property: "csp-nonce", content: "none" }] })`. If your code replaces `document.adoptedStyleSheets`, ui-sdk adds its sheets back the next time a component mounts.
+
+## Controllers
+
+A controller connects code to a mounted component. Use one when the button or action that changes it lives somewhere else.
+
+### Connect a Controller
+
+Create it once in your component and pass it to the root:
+
+```vue
+<script setup lang="ts">
+import { createToggleController, Toggle } from "@ui-sdk/vue/toggle"
+
+const toggle = createToggleController()
+</script>
+
+<template>
+  <button @click="() => toggle.toggle()">Toggle Bold</button>
+  <Toggle :controller="toggle">Bold</Toggle>
+</template>
+```
+
+Controller methods run the same change callbacks as user input. Controlled values and cancellation follow [State and Events](./state-and-events.md).
+
+Each component lists its methods, such as `open()`, `close()`, `setValue()`, or `focus()`.
+
+A read like `toggle.isPressed()` answers when you call it, so call it from an event handler or async code. It returns `undefined` until the component mounts, and the template doesn't update when the state changes. To render the state, keep it in a ref with `v-model:pressed`.
+
+### Share a Popup
+
+External triggers can use the same controller. A `payload` tells the content which item was opened:
+
+```vue
+<script setup lang="ts">
+import {
+  createPopoverController,
+  Popover,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+
+const editor = createPopoverController<string>()
+</script>
+
+<template>
+  <PopoverTrigger :controller="editor" payload="Notes"
+    >Edit Notes</PopoverTrigger
+  >
+  <PopoverTrigger :controller="editor" payload="Tasks"
+    >Edit Tasks</PopoverTrigger
+  >
+  <Popover :controller="editor">
+    <PopoverContent v-slot="{ state }"
+      ><PopoverTitle>Edit {{ state.payload }}</PopoverTitle></PopoverContent
+    >
+  </Popover>
+</template>
+```
+
+### Wait for a Popup to Close
+
+A popup controller's `open()` returns a promise. It settles when the popup closes, with its reason and return value:
+
+```ts
+const result = await editor.open({ payload: "Notes" })
+console.log(result.reason, result.returnValue)
+```
+
+For confirmations, [Alert Dialog](./components/alert-dialog.md) provides `createConfirm()`, which gives you a function you can await.
+
+## Popups
+
+Popovers, menus, selects, and dialogs use the browser's top layer. They render in place, above the page, so you don't need a portal or Positioner part. Their events bubble through the elements around them like any other child's, so a click handler or a link wrapped around a popup also gets the clicks inside it. Keep popups outside clickable cards and links.
+
+### Place the Content
+
+Set placement on the content part:
+
+```vue
+<script setup lang="ts">
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+</script>
+
+<template>
+  <Popover>
+    <PopoverTrigger>Details</PopoverTrigger>
+    <PopoverContent side="bottom" align="start" :side-offset="8">
+      <PopoverTitle>Project Details</PopoverTitle>
+      <p>Last updated today.</p>
+      <PopoverClose>Done</PopoverClose>
+    </PopoverContent>
+  </Popover>
+</template>
+```
+
+The popup flips or shifts when there isn't enough room.
+
+| Prop                | What It Does                                                                                         |
+| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| `side`              | Chooses `top`, `bottom`, `left`, `right`, `start`, or `end`. Start and end follow reading direction. |
+| `align`             | Aligns the popup to the start, center, or end of that side.                                          |
+| `side-offset`       | Sets the gap from the anchor, in pixels.                                                             |
+| `align-offset`      | Shifts it along its side.                                                                            |
+| `collision-padding` | Leaves space from the window's edges.                                                                |
+
+An `anchor` positions the popup against another element. The component's page lists the anchors it accepts.
+
+### Control Dismissal
+
+Set `dismissible` to false to stop Escape, outside presses, focus leaving, Back, and sheet swipes from closing it. The trigger, Close part, and controller can still close it:
+
+```vue
+<script setup lang="ts">
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/vue/popover"
+</script>
+
+<template>
+  <Popover :dismissible="false">
+    <PopoverTrigger>Details</PopoverTrigger>
+    <PopoverContent>
+      <PopoverTitle>Project Details</PopoverTitle>
+      <p>Last updated today.</p>
+      <PopoverClose>Done</PopoverClose>
+    </PopoverContent>
+  </Popover>
+</template>
+```
+
+Use `@dismiss-attempt` to hear each refused dismissal. [State and Events](./state-and-events.md) shows how to cancel just one reason.
+
+### Modals and Sheets
+
+`modal` set to true makes the rest of the page inert and locks scrolling. Each component documents its default.
+
+Menu, Select, Combobox, Autocomplete, Popover, and Dialog support `presentation="auto"` to become a sheet on small touch screens. Use `presentation="sheet"` to always show a sheet.
+
+### Focus
+
+Dialogs, alert dialogs, drawers, and popovers move focus into their content when they open. Where it lands depends on how they opened:
+
+| Opened With                                  | Focus Goes To                                                |
+| -------------------------------------------- | ------------------------------------------------------------ |
+| Keyboard, screen reader, mouse, pen, or code | The element `initial-focus` picks.                           |
+| Touch                                        | The content itself, so no on-screen keyboard appears.        |
+| Hover                                        | Nowhere. Focus stays where it is.                            |
+| Rendered open                                | Nowhere, except in a dialog, which takes focus as it mounts. |
+
+`initial-focus` defaults to `"auto"`: the first focusable element, or the content when it has none. A dialog tries an element with `autofocus` first, and an alert dialog tries its first Close part. Pass `"content"` to focus the content itself, `"none"` to leave focus alone, or a CSS selector, an element, or a function that returns one.
+
+`modal` decides whether Tab can leave. With `true` or `"trap-focus"`, Tab and Shift+Tab wrap inside the content. With `false`, Tab moves from the trigger into a popover and on to the page after it, and focus leaving closes the popover. A non-modal dialog stays open.
+
+When a popup closes while focus is inside it, focus returns to the trigger. If the trigger is gone or can't take focus, focus goes to the element focused before the popup opened, then where the popup it was opened from would return focus, then to the nearest focusable element after where the trigger was. A popup a controller opened returns to the element focused before it first. Set `final-focus` to `"none"` to leave focus alone, or to a selector, an element, or a function to send it somewhere else. Closing because focus moved away never moves it back, and neither does pressing something focusable outside a non-modal popup.
+
+Menus, selects, and comboboxes handle focus within their own lists, and tooltips never move it. Each component's page covers its own.
+
+### Mounting and Containers
+
+Closed content unmounts after its exit animation. `keep-mounted` leaves it in the page, hidden. `@open-change-complete` runs when opening or closing finishes, including animations.
+
+Use `container` to render into another element, a shadow root, or an element in an iframe. Focus, Escape, and scroll locking then work in the document and shadow root the content renders in. Keep a dialog containing a form outside any surrounding form, or move its content with `container`, to avoid nested forms.
+
+In a page `<KeepAlive>` caches, an open popup leaves with the page, from its `container` too, and comes back open when the page does, with focus in it if it's modal.
+
+[Styling and Animation](./styling-and-animation.md) covers transitions. For toasts and confirms, mount `OverlayHost` once near your app's root; [Toast](./components/toast.md) and [Alert Dialog](./components/alert-dialog.md) show the setup.
+
+## Lists and Menus
+
+Select, Combobox, Autocomplete, Listbox, and Trigger Menu accept items as data. Use this when your choices already come from an array. You can also compose their item parts yourself.
+
+### Start with Strings
+
+```vue
+<script setup lang="ts">
+import {
+  Select,
+  SelectContent,
+  SelectTrigger,
+  SelectValue,
+} from "@ui-sdk/vue/select"
+</script>
+
+<template>
+  <Select :items="['Apple', 'Banana', 'Pear']">
+    <SelectTrigger aria-label="Fruit"
+      ><SelectValue placeholder="Choose a fruit"
+    /></SelectTrigger>
+    <SelectContent />
+  </Select>
+</template>
+```
+
+Each string is both the value and its label. Use objects when those need to differ:
+
+```ts
+const items = [
+  { value: "apple", label: "Apple" },
+  { value: "banana", label: "Banana", disabled: true },
+]
+```
+
+Items can have `keywords` for searching. Group them with `{ type: "group", label, items }`, or separate them with `{ type: "separator" }`.
+
+For object values, provide `item-to-value` for the submitted string and `item-to-label` for the displayed text. [Select](./components/select.md) and [Combobox](./components/combobox.md) show complete examples.
+
+### Style the Items
+
+Items as data render bare parts, each with just its label. To style them, render the parts yourself from your array, with your classes right on them. Type the array with `ListData`, so a mistake in it shows up where you write it:
+
+```vue
+<script setup lang="ts">
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  type ListData,
+} from "@ui-sdk/vue/select"
+
+const fruits = [
+  { value: "apple", label: "Apple" },
+  { value: "banana", label: "Banana" },
+] satisfies ListData
+</script>
+
+<template>
+  <Select :items="fruits">
+    <SelectTrigger aria-label="Fruit" class="…"
+      ><SelectValue placeholder="Choose a fruit"
+    /></SelectTrigger>
+    <SelectContent class="…">
+      <SelectItem
+        v-for="fruit in fruits"
+        :key="fruit.value"
+        :value="fruit.value"
+        class="…"
+      >
+        {{ fruit.label }}
+      </SelectItem>
+    </SelectContent>
+  </Select>
+</template>
+```
+
+A list that searches still filters the items you render, and hides the ones that don't match. When the items come from state, like results from a server, the list part's slot gives you the ones to show. Write `<SelectList v-slot="{ state }">` and render `state.items`.
+
+### Search and Load Items
+
+Searchable components accept a `filter` to change how typing narrows their items. [Async Options](./utilities/async-options.md) handles server results, debouncing, and stale requests.
+
+Data lists can virtualize large collections. You don't need to render every item yourself.
+
+### Describe a Menu
+
+A `MenuData` array describes actions, separators, groups, and submenus. A plain string is an action whose value and label are the string:
+
+```vue
+<script setup lang="ts">
+import { Menu, MenuTrigger, type MenuData } from "@ui-sdk/vue/menu"
+
+const actions: MenuData = [
+  { value: "open", label: "Open", shortcut: "mod+o" },
+  { type: "separator" },
+  {
+    type: "submenu",
+    label: "Share",
+    items: [{ value: "email", label: "Email" }],
+  },
+]
+</script>
+
+<template>
+  <Menu :items="actions" @action="(value: string) => console.log(value)">
+    <MenuTrigger>File</MenuTrigger>
+  </Menu>
+</template>
+```
+
+A data menu renders bare parts too. To style it, place a `MenuContent` of your own and render the items in it, as [Menu](./components/menu.md#menus-as-data) shows. That page also covers checkbox items, radio groups, and nested menus.
+
+### Keys and Shortcuts
+
+`loop` controls whether arrow keys wrap around a list. Components that support `orientation` use it to choose the navigation axis.
+
+A trigger's `shortcut="mod+k"` opens it from elsewhere on the page. A data menu runs item shortcuts while closed; a manually rendered MenuItem's shortcut only displays the keys. [Shortcuts](./utilities/shortcuts.md) covers registering your own.
+
+## Forms
+
+Give a control a `name` to include its value in a form. This works for Select and Combobox as well as inputs and checkboxes.
+
+### Submit a Value
+
+```vue
+<script setup lang="ts">
+import { Checkbox } from "@ui-sdk/vue/checkbox"
+</script>
+
+<template>
+  <form action="/preferences" method="post">
+    <label
+      ><Checkbox name="updates" value="yes" default-checked /> Email me
+      updates</label
+    >
+    <button type="submit">Save</button>
+    <button type="reset">Reset</button>
+  </form>
+</template>
+```
+
+The checkbox submits `updates=yes` when checked. Reset restores its default value.
+
+### Reset a Controlled Value
+
+A reset also goes through `@checked-change` and `v-model`. Keep the binding in place so your ref follows the reset:
+
+```vue
+<script setup lang="ts">
+import { Checkbox, type CheckedState } from "@ui-sdk/vue/checkbox"
+import { ref } from "vue"
+
+const checked = ref<CheckedState>(true)
+const reason = ref("No change yet")
+</script>
+
+<template>
+  <form>
+    <label>
+      <Checkbox
+        v-model:checked="checked"
+        name="updates"
+        default-checked
+        @checked-change="(_next, details) => (reason = details.reason)"
+      />
+      Email me updates
+    </label>
+    <button type="reset">Reset</button>
+    <output>{{ reason }}</output>
+  </form>
+</template>
+```
+
+Uncheck the box, then press Reset. `default-checked` supplies the reset value. The event receives `true` with reason `"reset"`, and `v-model` updates `checked`. The event runs when reset requests a different value; it does not run if the checkbox is already at its default.
+
+### Label and Validate a Field
+
+`Field` connects a control to its label, description, and error message:
+
+```vue
+<script setup lang="ts">
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@ui-sdk/vue/field"
+import { Input } from "@ui-sdk/vue/input"
+</script>
+
+<template>
+  <Field name="email">
+    <FieldLabel>Email</FieldLabel>
+    <Input type="email" required />
+    <FieldDescription>We'll only use it for receipts.</FieldDescription>
+    <FieldError />
+  </Field>
+</template>
+```
+
+You can use a Textarea, Checkbox, Switch, Radio Group, or Select in place of the Input. [Field](./components/field.md) shows how they connect.
+
+On controls that support them, `required`, `disabled`, `read-only`, and `form` follow native conventions. Disabled fields are left out of submission; read-only fields remain focusable and submitted.
+
+### Handle a Submission
+
+On a normal submit, the browser checks constraints such as `required` and `type="email"` before running your handler.
+
+Your server may still reject a valid-looking value. Pass `invalid` to the field and show the server’s message. When the user edits the field, clear the message and return `invalid` to `undefined` so the field uses native validation again. This example expects a `/api/preferences` endpoint:
+
+```vue
+<script setup lang="ts">
+import { Field, FieldError, FieldLabel } from "@ui-sdk/vue/field"
+import { Input } from "@ui-sdk/vue/input"
+import { ref } from "vue"
+
+const error = ref("")
+
+async function save(event: SubmitEvent) {
+  const body = new FormData(event.currentTarget as HTMLFormElement)
+  const response = await fetch("/api/preferences", { method: "POST", body })
+  error.value = response.ok ? "" : "That email is already taken."
+}
+</script>
+
+<template>
+  <form @submit.prevent="save">
+    <Field name="email" :invalid="error ? true : undefined">
+      <FieldLabel>Email</FieldLabel>
+      <Input type="email" required @value-change="error = ''" />
+      <FieldError v-slot="{ state }">{{ error || state.message }}</FieldError>
+    </Field>
+    <button type="submit">Save</button>
+  </form>
+</template>
+```
+
+Without a handler, the form submits through its `action` URL.
+
+## Server Rendering
+
+ui-sdk parts render HTML with Vue's server renderer. Their initial attributes include ARIA state and the group's tab stop. In Nuxt, pages and components render this way with no plugin or module.
+
+### Render the Initial State
+
+```vue
+<script setup lang="ts">
+import { Toggle } from "@ui-sdk/vue/toggle"
+</script>
+
+<template>
+  <Toggle default-pressed>Bold</Toggle>
+</template>
+```
+
+The server sends a button with `aria-pressed="true"`. It can toggle after hydration. Native HTML behavior, such as submitting a form, can work before hydration.
+
+### Read Browser Values After Mount
+
+The server does not know the browser’s language. Start with the same placeholder on the server and client, then read the language after mount:
+
+```vue
+<script setup lang="ts">
+import { onMounted, ref } from "vue"
+
+const language = ref("")
+onMounted(() => {
+  language.value = navigator.language
+})
+</script>
+
+<template>
+  <p>{{ language || "Loading language…" }}</p>
+</template>
+```
+
+Both initial renders show “Loading language…”. Once mounted, the paragraph shows the browser’s language. Read other browser-only values in the same place, or in an event handler.
+
+### Saved Preferences and Storage
+
+Preferences like a color scheme or an emoji skin tone are saved in the browser, so the server can't render them. [Preferences](./core.md#preferences) covers the preferences themselves; this is how they fit server rendering.
+
+#### Show Them Before Hydration
+
+Render `Preferences` around your app. On the server it renders one inline script as its first child, which puts every saved value on its `data-*` attribute as the page loads, before Vue hydrates, so CSS that selects those attributes is right from the first paint:
+
+```vue title="app.vue"
+<script setup lang="ts">
+import { Preferences } from "@ui-sdk/vue/preferences"
+import Page from "./page.vue"
+import { colorScheme, skinTone } from "./preferences"
+
+const preferences = [colorScheme, skinTone]
+</script>
+
+<template>
+  <Preferences :preferences="preferences">
+    <Page />
+  </Preferences>
+</template>
+```
+
+Its element marks its attributes with `data-allow-mismatch="attribute"`, since the script changes them before hydration. A preference made with `global: true` goes on `<html>` instead. Pass `nonce` if your Content Security Policy only allows inline scripts with one.
+
+Content that reads a preference through `usePreference` renders the default on the server and the saved value once mounted. Style by the attribute instead wherever the first paint has to be right, as [Style by Preferences](./core.md#style-by-preferences) shows.
+
+#### Read a Cookie on the Server
+
+A preference kept in a cookie can render on the server too, content included. Read the request's `Cookie` header on the server, however your server or framework gives you the request, and pass it to your app as a prop, like `createSSRApp(App, { cookie })`. `setup` runs once per request, so create the preference there and share it with `provide`:
+
+```vue title="app.vue"
+<script setup lang="ts">
+import { createCookieStorage, createPreference } from "@ui-sdk/core"
+import { Preferences } from "@ui-sdk/vue/preferences"
+import { provide } from "vue"
+import Page from "./page.vue"
+
+const props = defineProps<{ cookie: string | null }>()
+const skinTone = createPreference({
+  values: ["default", "light", "medium", "dark"],
+  defaultValue: "default",
+  attribute: "data-skin-tone",
+  storage: createCookieStorage("skin-tone", { cookie: props.cookie }),
+})
+provide("skin-tone", skinTone)
+</script>
+
+<template>
+  <Preferences :preferences="[skinTone]">
+    <Page />
+  </Preferences>
+</template>
+```
+
+The server reads the value from `cookie`, and the browser from `document.cookie`, so both render it and hydration matches.
+
+Nuxt creates the app for you, so read the header with `useRequestHeader` in `app.vue` instead of taking a prop:
+
+```vue title="app.vue"
+<script setup lang="ts">
+import { createCookieStorage, createPreference } from "@ui-sdk/core"
+import { Preferences } from "@ui-sdk/vue/preferences"
+
+const skinTone = createPreference({
+  values: ["default", "light", "medium", "dark"],
+  defaultValue: "default",
+  attribute: "data-skin-tone",
+  storage: createCookieStorage("skin-tone", {
+    cookie: useRequestHeader("cookie"),
+  }),
+})
+provide("skin-tone", skinTone)
+</script>
+
+<template>
+  <Preferences :preferences="[skinTone]">
+    <NuxtPage />
+  </Preferences>
+</template>
+```
+
+`useRequestHeader` returns the whole `Cookie` header on the server and undefined in the browser, where the storage reads `document.cookie` instead. `useCookie` doesn't fit here, since it reads one cookie by name and the storage takes the header.
+
+#### Render the Storage Script Yourself
+
+`Preferences` is the usual way. For one component that keeps its own value, like a toolbar's density, a storage's `script` returns the same kind of inline script for a single element. Render it right after the element, since it writes to the element right before it. Vue templates leave `<script>` tags out, so render it from a render function:
+
+```ts title="toolbar.ts"
+import { createLocalStorage } from "@ui-sdk/core"
+import { defineComponent, h, onMounted, shallowRef } from "vue"
+
+const density = createLocalStorage("density")
+const script = density.script({
+  attribute: "data-density",
+  values: ["comfortable", "compact"],
+})
+
+const Toolbar = defineComponent((_props, { slots }) => {
+  const value = shallowRef("comfortable")
+  // The script is in the server's HTML until then.
+  const mounted = shallowRef(false)
+  onMounted(() => {
+    value.value = density.get() === "compact" ? "compact" : "comfortable"
+    mounted.value = true
+  })
+  return () => [
+    h(
+      "div",
+      { "data-density": value.value, "data-allow-mismatch": "attribute" },
+      slots.default?.()
+    ),
+    mounted.value || !script ? null : h("script", { innerHTML: script }),
+  ]
+})
+
+export { Toolbar }
+```
+
+- **Only from the server.** The browser never runs a script Vue inserts, so drop it once mounted.
+- **The element differs until hydration.** The script changes its attribute before Vue hydrates, so mark it with `data-allow-mismatch="attribute"`. Once mounted, render the saved value from state, as above.
+- **Shared by ID.** Every script with the same storage kind and ID reads the storage once, however many elements render it, and the scripts are identical, so compression shrinks the repeats.
+- **Only safe values.** Any script on your site can write the saved value, so `script` only sets attributes that start with `data-`, and only to one of `values`.
+- **Not for cookies.** A cookie storage's `script` returns undefined, since the server reads the cookie and renders the value itself.
+
+To run before the page's content at all, render `preferencesScript([...])` from `@ui-sdk/core` in `<head>` yourself, wherever your server writes it. Only global preferences make sense there, since the others go on the script's parent element.
+
+### Keep IDs and Values Consistent
+
+Use the same initial component values on the server and client. For example, do not render an open dialog on the server and a closed one for the first client render.
+
+Parts generate IDs for relationships such as a Dialog trigger’s `aria-controls` and a Field label’s `for`. You usually do not need to supply them.
+
+Pass an explicit `id` when something outside the component needs to refer to a part. On the server, render order matters: if a Field label renders before a control with your ID, the label initially uses the generated ID. Hydration updates the reference to yours. The same applies to Dialog triggers, titles, and descriptions.
+
+Use classes or data attributes for styling, rather than generated IDs.
+
+Popups render in place, so your server layout doesn't need a portal root. [Popups](./popups.md) covers containers; [Forms](./forms.md) covers submission and validation.
+
+## Rendering Primitives
+
+This page renders the rating from [Compose Behaviors](./core.md#compose-behaviors). Start with that guide's [complete `rating.ts`](./core.md#complete-primitive): it already handles selection, arrow keys, and focus. Here we'll connect its `root` and `star` slots to Vue.
+
+### Create the Parts
+
+`createParts` maps slots to elements. Save this beside `rating.ts`:
+
+```ts title="rating-parts.ts"
+import { createParts } from "@ui-sdk/vue/primitive"
+import { rating } from "./rating"
+
+const { Root: RatingRoot, Star: RatingStar } = createParts(rating, {
+  root: "div",
+  star: "button",
+})
+
+export { RatingRoot, RatingStar }
+```
+
+`Root` creates the instance and shares it with the parts inside. Each mapped slot becomes a component. Slot names become Pascal case: `star` becomes `Star`, and `tab-icon` would become `TabIcon`.
+
+If you leave out the `root` tag, `Root` still shares the instance but renders only its children.
+
+### Render the Rating
+
+The root accepts the primitive's options and the element's props. Each star receives its slot value and a name a screen reader can announce:
+
+```vue
+<script setup lang="ts">
+import { RatingRoot, RatingStar } from "./rating-parts"
+</script>
+
+<template>
+  <RatingRoot :default-value="4" aria-label="Rating" class="flex gap-1">
+    <RatingStar
+      v-for="star in 5"
+      :key="star"
+      :value="String(star)"
+      :aria-label="`${star} ${star === 1 ? 'star' : 'stars'}`"
+      class="opacity-40 data-filled:opacity-100"
+      >★</RatingStar
+    >
+  </RatingRoot>
+</template>
+```
+
+The primitive supplies `data-filled`; these classes make the filled stars easier to see. [Styling and Animation](./styling-and-animation.md) covers other ways to style parts.
+
+Generated parts also support the same default and `#render` slots as the components in the catalog. Use [Parts and Composition](./parts-and-composition.md) when you want to change their markup.
+
+### Add Logic to a Part
+
+Keep `createParts` when mapping slots to elements is enough. [Custom Parts](./custom-parts.md) uses the same rating to show how `usePrimitive` and `usePart` let you write your own root or child part.
+
+## Custom Parts
+
+The parts from [Rendering Primitives](./rendering.md) are enough until one needs its own logic. You can replace just that part and keep the same `rating.ts` definition from [Compose Behaviors](./core.md#complete-primitive).
+
+### Write a Root Part
+
+Here's a replacement for the generated `RatingRoot`. `usePrimitive` creates its instance, and `usePart` connects the `root` slot:
+
+```ts title="rating-root.ts"
+import { usePart, usePrimitive, type PartSlots } from "@ui-sdk/vue/primitive"
+import { defineComponent, type HTMLAttributes } from "vue"
+import { rating } from "./rating"
+
+const RatingRoot = defineComponent(
+  (
+    props: { value?: number; defaultValue?: number } & HTMLAttributes,
+    { emit }
+  ) => {
+    const handle = usePrimitive(rating, () => ({
+      value: props.value,
+      defaultValue: props.defaultValue,
+      onValueChange(value, details) {
+        emit("value-change", value, details)
+        if (!details.canceled) {
+          emit("update:value", value)
+        }
+      },
+    }))
+    return usePart(handle, "root", undefined, undefined, "div")
+  },
+  {
+    inheritAttrs: false,
+    props: ["value", "defaultValue"],
+    emits: ["value-change", "update:value"],
+    slots: Object as PartSlots<typeof rating, "root">,
+  }
+)
+
+export { RatingRoot }
+```
+
+Call both helpers in `setup`. The options getter keeps values current; `usePrimitive` also shares the instance with child parts. `usePart` returns a render function that forwards attrs and slots. `inheritAttrs: false` avoids applying attrs twice.
+
+`HTMLAttributes` makes native attrs available to TypeScript callers; only `value` and `defaultValue` are declared component props, so the other attrs still reach `usePart`.
+
+This root supports `v-model:value` by emitting `update:value` after the change callback has had a chance to cancel. `PartSlots` types the default and `#render` slots. The adapter manages the instance's lifetime.
+
+### Connect a Child Part
+
+Pass the primitive itself to `usePart` to find the instance shared by the root above it. This `RatingStar` works inside the manual root above or the generated `RatingRoot`:
+
+```ts title="rating-star.ts"
+import { usePart, type PartSlots } from "@ui-sdk/vue/primitive"
+import { defineComponent, type ButtonHTMLAttributes } from "vue"
+import { rating } from "./rating"
+
+const RatingStar = defineComponent(
+  (props: { value: string } & Omit<ButtonHTMLAttributes, "value">) => {
+    return usePart(
+      rating,
+      "star",
+      () => ({ value: props.value }),
+      undefined,
+      "button"
+    )
+  },
+  {
+    inheritAttrs: false,
+    props: ["value"],
+    slots: Object as PartSlots<typeof rating, "star">,
+  }
+)
+
+export { RatingStar }
+```
+
+Use it in place of the generated star in [Render the Rating](./rendering.md#render-the-rating). `ButtonHTMLAttributes` types its native attrs. The `value` getter identifies the star; the remaining props go to its button. Keep it inside `RatingRoot` and give it an `aria-label`.
+
+### Merge Props
+
+`usePart` merges the component's attrs with the slot's. Slot attributes win, classes and styles combine, and your listeners run first. An `id`, or a name or typing hint you pass, like `aria-label` or `autocomplete`, replaces the slot's. Call `preventDefault()` in a listener to skip the built-in handler.
+
+The last argument can be a tag, or an object with `tag`, `children`, and `extend`. Use `extend` for extra props after the slot's props, such as attributes supplied by a Field. Keep the slot's roles, IDs, and ARIA state intact.
+
+### Compose a Popup
+
+A custom component can also use an existing Popover or Dialog. [Compose Ours](./core.md#compose-ours) shows that connection with an emoji picker.
+
+## Components
+
+Each page has the component's composition, examples, styling hooks and every prop.
+
+- [Accordion](./components/accordion.md): Show and hide sections of content from their headings. Import from `@ui-sdk/vue/accordion`.
+- [Alert Dialog](./components/alert-dialog.md): Ask someone to confirm an action before you continue. Import from `@ui-sdk/vue/alert-dialog`.
+- [Autocomplete](./components/autocomplete.md): Suggest text while someone types, without limiting what they can enter. Import from `@ui-sdk/vue/autocomplete`.
+- [Avatar](./components/avatar.md): Show an image with a fallback while it loads or if it fails. Import from `@ui-sdk/vue/avatar`.
+- [Button](./components/button.md): Run an action, show that it's working, and keep it reachable when disabled. Import from `@ui-sdk/vue/button`.
+- [Calendar](./components/calendar.md): Choose one date, several dates, or a range from a month grid. Import from `@ui-sdk/vue/calendar`.
+- [Carousel](./components/carousel.md): Page through slides with native scrolling, keyboard controls, and optional rotation. Import from `@ui-sdk/vue/carousel`.
+- [Checkbox](./components/checkbox.md): Choose one or more options, individually or as a group. Import from `@ui-sdk/vue/checkbox`.
+- [Collapsible](./components/collapsible.md): Show and hide a panel, preserve its contents, and animate its height. Import from `@ui-sdk/vue/collapsible`.
+- [Color Picker](./components/color-picker.md): Choose a color by dragging across an area and along sliders, typing any CSS color, or picking a preset. Import from `@ui-sdk/vue/color-picker`.
+- [Combobox](./components/combobox.md): Search a list of options and choose one or several values. Import from `@ui-sdk/vue/combobox`.
+- [Command](./components/command.md): Search commands, run actions, and open pages of more choices. Import from `@ui-sdk/vue/command`.
+- [Date Input](./components/date-input.md): Type a date one part at a time, in the order your user's language writes it. Import from `@ui-sdk/vue/date-input`.
+- [Date Picker](./components/date-picker.md): Type a date or choose one from a calendar, with support for ranges and forms. Import from `@ui-sdk/vue/date-picker`.
+- [Dialog](./components/dialog.md): Open a focused task over the page. Import from `@ui-sdk/vue/dialog`.
+- [Drawer](./components/drawer.md): A sheet you can open, drag, and resize from an edge of the screen. Import from `@ui-sdk/vue/drawer`.
+- [Field](./components/field.md): Connect a form control to its label, description, and validation errors. Import from `@ui-sdk/vue/field`.
+- [File Input](./components/file-input.md): Choose, drop, or paste files, validate them, and submit them with a form. Import from `@ui-sdk/vue/file-input`.
+- [Hover Card](./components/hover-card.md): Preview a link on hover or keyboard focus while keeping its normal navigation. Import from `@ui-sdk/vue/hover-card`.
+- [Image Cropper](./components/image-cropper.md): Choose the part of an image to keep by moving and resizing a selection, or by panning and zooming the image under it. Import from `@ui-sdk/vue/image-cropper`.
+- [Input](./components/input.md): Enter text, add a clear button, and connect the value to your form or state. Import from `@ui-sdk/vue/input`.
+- [Label](./components/label.md): Name any control with a label, and let a press on the label reach it. Import from `@ui-sdk/vue/label`.
+- [Listbox](./components/listbox.md): Choose one or several options from an always-visible list. Import from `@ui-sdk/vue/listbox`.
+- [Menu](./components/menu.md): Choose actions and settings from a button or a context menu. Import from `@ui-sdk/vue/menu`.
+- [Menubar](./components/menubar.md): Move between an application’s menus with one tab stop. Import from `@ui-sdk/vue/menubar`.
+- [Meter](./components/meter.md): Show a measurement within a known range, such as storage used or an account quota. Import from `@ui-sdk/vue/meter`.
+- [Navigation Menu](./components/navigation-menu.md): Groups site links into panels that open from a row of triggers. Import from `@ui-sdk/vue/navigation-menu`.
+- [Number Input](./components/number-input.md): Enter numbers, step through values, and format them for a locale. Import from `@ui-sdk/vue/number-input`.
+- [OTP Input](./components/otp-input.md): Enter a one-time code with support for pasting, autofill, and native form validation. Import from `@ui-sdk/vue/otp-input`.
+- [Pagination](./components/pagination.md): Navigate pages with buttons, links, or your router. Import from `@ui-sdk/vue/pagination`.
+- [Password Input](./components/password-input.md): Enter a password, show or hide it, and use it in a native form. Import from `@ui-sdk/vue/password-input`.
+- [Popover](./components/popover.md): Edit or explore something beside its trigger. Import from `@ui-sdk/vue/popover`.
+- [Preferences](./components/preferences.md): Apply user preferences to data attributes so your styles can follow them. Import from `@ui-sdk/vue/preferences`.
+- [Progress](./components/progress.md): Show a task’s progress, or an indeterminate state while its progress is unknown. Import from `@ui-sdk/vue/progress`.
+- [Radio](./components/radio.md): Choose one option, move the selection with arrow keys, and submit it with a form. Import from `@ui-sdk/vue/radio`.
+- [Rating](./components/rating.md): Pick a score from a row of stars, whole or half, with a preview as the pointer moves over them. Import from `@ui-sdk/vue/rating`.
+- [Resizable](./components/resizable.md): Resize, collapse, and save panel layouts with pointer and keyboard controls. Import from `@ui-sdk/vue/resizable`.
+- [Scroll Area](./components/scroll-area.md): Add styled scrollbars, edge indicators, and follow-to-end behavior to native scrolling. Import from `@ui-sdk/vue/scroll-area`.
+- [Segmented Control](./components/segmented-control.md): Pick one of a few options from a row of buttons, with an indicator that slides to the choice. Import from `@ui-sdk/vue/segmented-control`.
+- [Select](./components/select.md): Choose one value or several from a popup list. Import from `@ui-sdk/vue/select`.
+- [Separator](./components/separator.md): Divide groups of content with a horizontal or vertical line. Import from `@ui-sdk/vue/separator`.
+- [Slider](./components/slider.md): Adjust a number or a range with draggable thumbs and keyboard controls. Import from `@ui-sdk/vue/slider`.
+- [Switch](./components/switch.md): Turn a setting on or off. Import from `@ui-sdk/vue/switch`.
+- [Tabs](./components/tabs.md): Switch between related panels with one tab selected at a time. Import from `@ui-sdk/vue/tabs`.
+- [Textarea](./components/textarea.md): Enter multiple lines of text, grow the field as you type, and connect it to a form. Import from `@ui-sdk/vue/textarea`.
+- [Time Input](./components/time-input.md): Type a time one part at a time, on the clock your user's language uses.
+- [Timeline](./components/timeline.md): Show dated events in order, like an activity feed, a changelog or an order's progress, with arrow keys between them. Import from `@ui-sdk/vue/timeline`.
+- [Toast](./components/toast.md): Show notifications with actions, timed dismissal, and screen reader announcements. Import from `@ui-sdk/vue/toast`.
+- [Toggle](./components/toggle.md): Keep a button pressed, or group toggles with a shared value and arrow-key navigation. Import from `@ui-sdk/vue/toggle`.
+- [Token Input](./components/token-input.md): Mix editable text with tokens for files, people, tags, and other references. Import from `@ui-sdk/vue/token-input`.
+- [Toolbar](./components/toolbar.md): Give buttons, toggles, menus and fields one tab stop with arrow-key navigation. Import from `@ui-sdk/vue/toolbar`.
+- [Tooltip](./components/tooltip.md): Name a control or add a short hint on hover and keyboard focus. Import from `@ui-sdk/vue/tooltip`.
+- [Tree](./components/tree.md): Browse a hierarchy of files, pages, or choices with expandable branches. Import from `@ui-sdk/vue/tree`.
+- [Trigger Menu](./components/trigger-menu.md): "Opens suggestions at the caret when you type a trigger such as @, /, or #." Import from `@ui-sdk/vue/trigger-menu`.
+- [Waterfall](./components/waterfall.md): Show a trace or a page's requests as bars on a shared time axis, with spans that expand to show what they started. Import from `@ui-sdk/vue/waterfall`.
+
+## Utilities
+
+### Async Options
+
+`useAsyncOptions` loads items as someone types. It waits for typing to pause, cancels requests that are replaced, and keeps the previous results visible while loading.
+
+Change the movie search and wait for the results. Use the arrow keys to choose a movie, then press Enter.
+
+#### Load Results
+
+Pass a loader to the helper. This example expects `/api/movies` to return an array of movie titles:
+
+```vue
+<script setup lang="ts">
+import { useAsyncOptions } from "@ui-sdk/vue/async-options"
+import { Combobox, ComboboxContent, ComboboxInput } from "@ui-sdk/vue/combobox"
+
+const movies = useAsyncOptions<string>(async (query, { signal }) => {
+  const response = await fetch(`/api/movies?q=${encodeURIComponent(query)}`, {
+    signal,
+  })
+  if (!response.ok) throw new Error("Couldn't load movies")
+  return response.json()
+})
+const { state } = movies
+</script>
+
+<template>
+  <Combobox
+    :items="state.items"
+    :filter="false"
+    :status="state.status"
+    @query-change="movies.setQuery"
+  >
+    <ComboboxInput aria-label="Movie" placeholder="Search movies…" />
+    <ComboboxContent />
+  </Combobox>
+</template>
+```
+
+`state` is a ref, unwrapped in the template. In script, read `state.value.items` or `state.value.status`.
+
+Pass `signal` to `fetch` so a newer search can cancel the request. The helper cancels on unmount. `filter` set to false leaves matching and ordering to the server.
+
+Use `ComboboxStatus` and `ComboboxEmpty` to show loading, error, and empty messages, as in the demo. The same pattern works with [Select](./components/select.md#async-search), [Autocomplete](./components/autocomplete.md#async-suggestions), and [Command](./components/command.md#async-results).
+
+#### Choose When to Load
+
+The second argument sets the starting behavior:
+
+| Option      | What It Does                                            | Default |
+| ----------- | ------------------------------------------------------- | ------- |
+| `debounce`  | Milliseconds typing must pause before a request starts. | `200`   |
+| `query`     | The starting search text.                               | `""`    |
+| `immediate` | Loads that text as soon as the component mounts.        | `false` |
+
+For initial choices, add `{ immediate: true, debounce: 300 }` after the loader. Until that first load starts, `status` is already `"loading"`, so the list never flashes an empty state. If you set `query`, use the same starting text for the component's `default-query`.
+
+#### Load More
+
+For paged results, the loader receives `page`, starting at `0`. Return `{ items, hasMore }`:
+
+```ts
+import type { AsyncOptionsContext } from "@ui-sdk/vue/async-options"
+
+async function loadMoviePages(
+  query: string,
+  { signal, page }: AsyncOptionsContext
+) {
+  const response = await fetch(
+    `/api/movies?q=${encodeURIComponent(query)}&page=${page}`,
+    { signal }
+  )
+  if (!response.ok) throw new Error("Couldn't load movies")
+  const data: { titles: string[]; next: number | null } = await response.json()
+  return { items: data.titles, hasMore: data.next !== null }
+}
+
+export { loadMoviePages }
+```
+
+Pass `loadMoviePages` to `useAsyncOptions` in place of the inline loader above.
+
+Connect `@load-more="movies.loadMore"` on Combobox. It asks for another page when scrolling or keyboard navigation reaches the last item. The helper appends the new items.
+
+Open the movie list and scroll down, or use Arrow Down to reach the last result. The next page is added to the list.
+
+#### Retry a Search
+
+`status` is `"loading"` during a request, `"error"` after a failure, and `"idle"` otherwise. `error` holds the failure, and the previous items stay available.
+
+Call `movies.reload()` from a retry button to load the current query again, starting at page `0`. `state.value.hasMore` tells you whether another page is available.
+
+### Shortcuts
+
+`useShortcut` registers a shortcut while your component is mounted. For a component that already accepts `shortcut`, such as a dialog trigger, use that prop directly.
+
+Press N to create a note. Press Command+S on Mac or Control+S elsewhere to save. The buttons run the same actions.
+
+#### Register a Shortcut
+
+Keys are joined with `+`. `mod` means Command on Apple platforms and Control elsewhere. This example also displays the keys using `useShortcutHint`:
+
+```vue
+<script setup lang="ts">
+import { useShortcut, useShortcutHint } from "@ui-sdk/vue/shortcuts"
+import { ref } from "vue"
+
+const count = ref(0)
+const addNote = () => count.value++
+useShortcut("mod+enter", addNote, { description: "New note" })
+const { text, ariaKeyshortcuts } = useShortcutHint("mod+enter")
+</script>
+
+<template>
+  <button @click="addNote" :aria-keyshortcuts="ariaKeyshortcuts">
+    New note ({{ count }}) <kbd aria-hidden="true">{{ text }}</kbd>
+  </button>
+</template>
+```
+
+Call the helper in setup. It unregisters when the component goes away. Keys and options can be getters; return `null` for keys to leave the shortcut unregistered.
+
+#### Show the Keys
+
+`useShortcutHint` supplies display text and `aria-keyshortcuts`. It keeps the server and first client render consistent, then updates for the user's platform after mount.
+
+Its fields are computed refs. The example destructures them so the template unwraps them automatically.
+
+Outside rendering, use `formatShortcut` for display text or `ariaKeyshortcuts` for the ARIA value, from the same entry.
+
+#### While Someone Is Typing
+
+Shortcuts with Command, Control, or Option can run in text fields. Plain letters and other keys stay available for typing. Set `allowInInput: true` when a shortcut should work there too, such as Escape to clear a search.
+
+#### Limit a Shortcut to an Area
+
+Use a named `scope` for an editor or another area. Turn it on while that area has focus:
+
+```vue
+<script setup lang="ts">
+import { shortcuts, useShortcut } from "@ui-sdk/vue/shortcuts"
+import { onScopeDispose, ref } from "vue"
+
+const text = ref("")
+useShortcut(
+  "escape",
+  () => {
+    text.value = ""
+  },
+  { scope: "note", allowInInput: true }
+)
+onScopeDispose(() => shortcuts.setScope("note", false))
+</script>
+
+<template>
+  <textarea
+    aria-label="Note"
+    v-model="text"
+    @focus="shortcuts.setScope('note', true)"
+    @blur="shortcuts.setScope('note', false)"
+  />
+</template>
+```
+
+Scope names are shared, so choose one for each area you want to enable together. A `when` function can add another condition, checked each time the keys are pressed.
+
+Focus the note and type some text. Press Command+Enter on Mac or Control+Enter elsewhere to save, or Escape to clear it. Move focus outside the note to turn off its shortcuts.
+
+#### Inside a Popup
+
+Page shortcuts pause while a modal is open. Pass `layer`, an element inside the popup or a getter that returns one, to make a shortcut belong to that popup. It runs only while that popup is open.
+
+When shortcuts share the same keys, the topmost open layer wins, then the most recently registered shortcut.
+
+#### List Available Shortcuts
+
+Call `shortcuts.list()` when a help screen opens. It returns the shortcuts that can run now, including their `keys`, formatted `hint`, and `description`. Add descriptions when registering shortcuts so the help screen can explain each action.