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

package/docs/custom-parts.md

@@ -0,0 +1,89 @@
+# Custom Parts
+
+Write a part with its own Vue logic and connect it to a primitive.
+
+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.

package/docs/first-component.md

@@ -0,0 +1,83 @@
+# First Component
+
+Add a component to your app and style its state.
+
+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.

package/docs/forms.md

@@ -0,0 +1,122 @@
+# Forms
+
+Submit component values, label controls, and show validation errors.
+
+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.

package/docs/installation.md

@@ -0,0 +1,72 @@
+# Installation
+
+Install UI SDK in your Vue app.
+
+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.

package/docs/introduction.md

@@ -0,0 +1,32 @@
+# Introduction
+
+Use unstyled Vue components with keyboard, focus, and screen reader support built in.
+
+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.

package/docs/lists-and-menus.md

@@ -0,0 +1,122 @@
+# Lists and Menus
+
+Supply options as data, load them from a server, and define menu actions.
+
+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.