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

package/docs/hooks/async-options.md

@@ -0,0 +1,366 @@
+# Async Options
+
+Load search results, cancel stale requests, and fetch the next page.
+
+`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.
+
+```tsx title="async.tsx"
+"use client"
+
+import { useAsyncOptions } from "@ui-sdk/react/async-options"
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxItemIndicator,
+  ComboboxLabel,
+  ComboboxList,
+  ComboboxStatus,
+  ComboboxTrigger,
+} from "@ui-sdk/react/combobox"
+import { CheckIcon, ChevronDownIcon } from "lucide-react"
+
+const movieTitles = [
+  "The Shawshank Redemption",
+  "The Godfather",
+  "The Dark Knight",
+  "Pulp Fiction",
+  "Schindler's List",
+  "The Lord of the Rings",
+  "Fight Club",
+  "Forrest Gump",
+  "Inception",
+  "The Matrix",
+  "Goodfellas",
+  "Interstellar",
+  "Parasite",
+  "Spirited Away",
+  "Whiplash",
+  "The Prestige",
+  "The Departed",
+  "Gladiator",
+  "Alien",
+  "Casablanca",
+  "Amélie",
+  "Arrival",
+]
+
+function searchMovies(query: string, { signal }: { signal: AbortSignal }) {
+  return new Promise<{ value: string; label: string }[]>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const needle = query.trim().toLowerCase()
+      resolve(
+        movieTitles
+          .filter((title) => title.toLowerCase().includes(needle))
+          .map((title) => ({
+            value: title.toLowerCase().replace(/\W+/g, "-"),
+            label: title,
+          }))
+      )
+    }, 500)
+    signal.addEventListener("abort", () => {
+      clearTimeout(timer)
+      reject(signal.reason)
+    })
+  })
+}
+
+function Example() {
+  const movies = useAsyncOptions(searchMovies, {
+    debounce: 300,
+    query: "the",
+    immediate: true,
+  })
+
+  return (
+    <Combobox
+      items={movies.items}
+      defaultQuery="the"
+      filter={false}
+      status={movies.status}
+      onQueryChange={(query) => movies.setQuery(query)}
+    >
+      <div data-slot="stack">
+        <ComboboxLabel>Movie</ComboboxLabel>
+        <div data-slot="row">
+          <ComboboxInput placeholder="Search movies…" />
+          <ComboboxTrigger aria-label="Show movies">
+            <ChevronDownIcon aria-hidden="true" />
+          </ComboboxTrigger>
+        </div>
+      </div>
+      <ComboboxContent>
+        <ComboboxStatus>
+          {(state) =>
+            state.status === "error"
+              ? "Couldn't load movies."
+              : state.loading
+                ? "Searching…"
+                : `${state.count} ${state.count === 1 ? "movie" : "movies"}`
+          }
+        </ComboboxStatus>
+        <ComboboxEmpty>
+          {(state) =>
+            state.empty && !state.loading
+              ? `No movies match “${state.query}”.`
+              : null
+          }
+        </ComboboxEmpty>
+        <ComboboxList>
+          {(state) =>
+            (
+              state.items as {
+                value: string
+                label: string
+                disabled?: boolean
+              }[]
+            ).map((item) => (
+              <ComboboxItem
+                key={item.value}
+                value={item.value}
+                label={item.label}
+                disabled={item.disabled}
+              >
+                {item.label}
+                <ComboboxItemIndicator>
+                  <CheckIcon aria-hidden="true" />
+                </ComboboxItemIndicator>
+              </ComboboxItem>
+            ))
+          }
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  )
+}
+
+export { Example }
+```
+
+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 hook. This example expects `/api/movies` to return an array of movie titles:
+
+```tsx
+"use client"
+
+import { useAsyncOptions } from "@ui-sdk/react/async-options"
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxInput,
+} from "@ui-sdk/react/combobox"
+
+function MovieSearch() {
+  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()
+  })
+
+  return (
+    <Combobox
+      items={movies.items}
+      filter={false}
+      status={movies.status}
+      onQueryChange={movies.setQuery}
+    >
+      <ComboboxInput aria-label="Movie" placeholder="Search movies…" />
+      <ComboboxContent />
+    </Combobox>
+  )
+}
+
+export { MovieSearch }
+```
+
+Pass `signal` to `fetch` so a newer search can cancel the request. The hook also cancels on unmount.
+
+`filter={false}` leaves matching and result order to the server. `status` tells the component when it's busy. 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 hook's second argument sets its starting behavior:
+
+| Option      | What It Does                                     | Default |
+| ----------- | ------------------------------------------------ | ------- |
+| `debounce`  | How long typing must pause, in milliseconds.     | `200`   |
+| `query`     | The starting search text.                        | `""`    |
+| `immediate` | Loads that text as soon as the component mounts. | `false` |
+
+For example, add `{ immediate: true, debounce: 300 }` after the loader to fetch initial choices and wait a little longer between searches. 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 `defaultQuery`.
+
+## Load More
+
+For paged results, the loader also receives `page`, starting at `0`. Return `{ items, hasMore }`:
+
+```tsx
+"use client"
+
+import { useAsyncOptions } from "@ui-sdk/react/async-options"
+
+function useMoviePages() {
+  return useAsyncOptions<string>(async (query, { signal, page }) => {
+    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 { useMoviePages }
+```
+
+Call `useMoviePages()` inside your component, then pass `onLoadMore={movies.loadMore}` to Combobox alongside the props above. It asks for another page when scrolling or keyboard navigation reaches the last item. The hook appends the new items.
+
+```tsx title="infinite.tsx"
+"use client"
+
+import { useAsyncOptions } from "@ui-sdk/react/async-options"
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxItemIndicator,
+  ComboboxLabel,
+  ComboboxList,
+  ComboboxStatus,
+  ComboboxTrigger,
+} from "@ui-sdk/react/combobox"
+import { CheckIcon, ChevronDownIcon } from "lucide-react"
+
+const movieTitles = [
+  "The Shawshank Redemption",
+  "The Godfather",
+  "The Dark Knight",
+  "Pulp Fiction",
+  "Schindler's List",
+  "The Lord of the Rings",
+  "Fight Club",
+  "Forrest Gump",
+  "Inception",
+  "The Matrix",
+  "Goodfellas",
+  "Interstellar",
+  "Parasite",
+  "Spirited Away",
+  "Whiplash",
+  "The Prestige",
+  "The Departed",
+  "Gladiator",
+  "Alien",
+  "Casablanca",
+  "Amélie",
+  "Arrival",
+]
+
+function searchMoviePages(
+  query: string,
+  { signal, page }: { signal: AbortSignal; page: number }
+) {
+  return new Promise<{
+    items: { value: string; label: string }[]
+    hasMore: boolean
+  }>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const needle = query.trim().toLowerCase()
+      const found = movieTitles
+        .filter((title) => title.toLowerCase().includes(needle))
+        .map((title) => ({
+          value: title.toLowerCase().replace(/\W+/g, "-"),
+          label: title,
+        }))
+      resolve({
+        items: found.slice(page * 5, page * 5 + 5),
+        hasMore: found.length > page * 5 + 5,
+      })
+    }, 500)
+    signal.addEventListener("abort", () => {
+      clearTimeout(timer)
+      reject(signal.reason)
+    })
+  })
+}
+
+function Example() {
+  const movies = useAsyncOptions(searchMoviePages, { immediate: true })
+
+  return (
+    <Combobox
+      items={movies.items}
+      filter={false}
+      status={movies.status}
+      onQueryChange={(query) => movies.setQuery(query)}
+      onLoadMore={movies.loadMore}
+    >
+      <div data-slot="stack">
+        <ComboboxLabel>Movie</ComboboxLabel>
+        <div data-slot="row">
+          <ComboboxInput placeholder="Search movies…" />
+          <ComboboxTrigger aria-label="Show movies">
+            <ChevronDownIcon aria-hidden="true" />
+          </ComboboxTrigger>
+        </div>
+      </div>
+      <ComboboxContent>
+        <ComboboxEmpty>
+          {(state) =>
+            state.empty && !state.loading ? "No movies found." : null
+          }
+        </ComboboxEmpty>
+        <ComboboxList>
+          {(state) =>
+            (
+              state.items as {
+                value: string
+                label: string
+                disabled?: boolean
+              }[]
+            ).map((item) => (
+              <ComboboxItem key={item.value} value={item.value} label={item.label} disabled={item.disabled}>
+                {item.label}
+                <ComboboxItemIndicator>
+                  <CheckIcon aria-hidden="true" />
+                </ComboboxItemIndicator>
+              </ComboboxItem>
+            ))
+          }
+        </ComboboxList>
+        <ComboboxStatus>
+          {(state) =>
+            state.loading
+              ? "Loading more…"
+              : movies.hasMore
+                ? `${state.count} loaded`
+                : `All ${state.count}`
+          }
+        </ComboboxStatus>
+      </ComboboxContent>
+    </Combobox>
+  )
+}
+
+export { Example }
+```
+
+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"` while a request is pending, `"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`. `movies.hasMore` tells you whether another page is available.

package/docs/hooks/shortcuts.md

@@ -0,0 +1,221 @@
+# Shortcuts
+
+Register keyboard shortcuts and show the right keys for the user's platform.
+
+`useShortcut` registers a keyboard shortcut while your component is mounted. Use it for actions outside a particular control. For a component that already accepts `shortcut`, such as a dialog trigger, use that prop directly.
+
+```tsx title="basic.tsx"
+import { useShortcut, useShortcutHint } from "@ui-sdk/react/shortcuts"
+import * as React from "react"
+
+export function Example() {
+  const [status, setStatus] = React.useState("Press N or the keys to save.")
+  const newNote = () => setStatus("Note created")
+  const save = () => setStatus("Saved")
+
+  useShortcut("n", newNote, { description: "New note" })
+  useShortcut("mod+s", save, { description: "Save" })
+  const saveHint = useShortcutHint("mod+s")
+
+  return (
+    <div data-slot="stack">
+      <div data-slot="row">
+        <button type="button" onClick={newNote} aria-keyshortcuts="N">
+          New note
+          <kbd aria-hidden="true" data-slot="kbd">
+            N
+          </kbd>
+        </button>
+        <button
+          type="button"
+          onClick={save}
+          aria-keyshortcuts={saveHint.ariaKeyshortcuts}
+        >
+          Save
+          <kbd aria-hidden="true" data-slot="kbd">
+            {saveHint.text}
+          </kbd>
+        </button>
+      </div>
+      <output data-slot="output">{status}</output>
+    </div>
+  )
+}
+```
+
+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:
+
+```tsx
+"use client"
+
+import { useShortcut } from "@ui-sdk/react/shortcuts"
+import { useState } from "react"
+
+function NewNote() {
+  const [count, setCount] = useState(0)
+  const addNote = () => setCount((count) => count + 1)
+  useShortcut("mod+enter", addNote, { description: "New note" })
+
+  return <button onClick={addNote}>New note ({count})</button>
+}
+
+export { NewNote }
+```
+
+The hook uses your latest handler and unregisters on unmount. You don't need `useCallback`. Pass `null` instead of keys to leave a shortcut unregistered.
+
+## Show the Keys
+
+`useShortcutHint` formats keys for the current platform and supplies `aria-keyshortcuts` for the control:
+
+```tsx
+"use client"
+
+import { useShortcut, useShortcutHint } from "@ui-sdk/react/shortcuts"
+
+function SaveButton({ onSave }: { onSave: () => void }) {
+  useShortcut("mod+s", onSave, { description: "Save" })
+  const hint = useShortcutHint("mod+s")
+
+  return (
+    <button onClick={onSave} aria-keyshortcuts={hint.ariaKeyshortcuts}>
+      Save <kbd aria-hidden="true">{hint.text}</kbd>
+    </button>
+  )
+}
+
+export { SaveButton }
+```
+
+This shows `⌘S` on Apple platforms and `Ctrl+S` elsewhere. The hook keeps the server and first client render consistent, then updates after mount.
+
+Outside rendering, use `formatShortcut` for display text or `ariaKeyshortcuts` for the ARIA value. Both are exported from the same entry. Compare the original keys, not the formatted hint.
+
+## While Someone Is Typing
+
+Shortcuts with Command, Control, or Option can run in a text field. Plain letters and other keys stay available for typing.
+
+Set `allowInInput: true` when the shortcut should work there too, such as Escape to clear a search. `when` checks a condition each time the keys are pressed; it can keep a Save shortcut inactive until there's text.
+
+```tsx title="scope.tsx"
+import { shortcuts, useShortcut } from "@ui-sdk/react/shortcuts"
+import * as React from "react"
+
+export function Example() {
+  const [text, setText] = React.useState("")
+  const [status, setStatus] = React.useState(
+    "Focus the note to turn on its shortcuts."
+  )
+
+  useShortcut(
+    "mod+enter",
+    () => setStatus(`Characters saved: ${text.trim().length}`),
+    {
+      scope: "note",
+      when: () => text.trim() !== "",
+      description: "Save the note",
+    }
+  )
+  useShortcut(
+    "escape",
+    () => {
+      setText("")
+      setStatus("Cleared")
+    },
+    { scope: "note", allowInInput: true, description: "Clear the note" }
+  )
+
+  return (
+    <div data-slot="stack">
+      <textarea
+        aria-label="Note"
+        placeholder="Write a note…"
+        value={text}
+        onChange={(event) => setText(event.target.value)}
+        onFocus={() => shortcuts.setScope("note", true)}
+        onBlur={() => shortcuts.setScope("note", false)}
+      />
+      <output data-slot="output">{status}</output>
+    </div>
+  )
+}
+```
+
+Focus the note and type some text. Press Command+Enter on Mac or Control+Enter elsewhere to save it, or Escape to clear it. Move focus outside the note to turn off its shortcuts.
+
+## Limit a Shortcut to an Area
+
+Use a named `scope` for an editor or another part of the app. Turn it on while that area has focus:
+
+```tsx
+"use client"
+
+import { shortcuts, useShortcut } from "@ui-sdk/react/shortcuts"
+import { useEffect, useState } from "react"
+
+function Note() {
+  const [text, setText] = useState("")
+  useEffect(() => () => shortcuts.setScope("note", false), [])
+  useShortcut("escape", () => setText(""), {
+    scope: "note",
+    allowInInput: true,
+  })
+
+  return (
+    <textarea
+      aria-label="Note"
+      value={text}
+      onChange={(event) => setText(event.target.value)}
+      onFocus={() => shortcuts.setScope("note", true)}
+      onBlur={() => shortcuts.setScope("note", false)}
+    />
+  )
+}
+
+export { Note }
+```
+
+A `when: () => text.length > 0` option can further limit when it runs. Scope names are shared, so choose one for each area you want to enable together.
+
+## Inside a Popup
+
+Page shortcuts pause while a modal is open. Pass `layer` to make a shortcut belong to a popup instead:
+
+```tsx
+"use client"
+
+import { DialogContent } from "@ui-sdk/react/dialog"
+import { useShortcut } from "@ui-sdk/react/shortcuts"
+import { useRef } from "react"
+
+function EditorContent({ onSave }: { onSave: () => void }) {
+  const content = useRef<HTMLDivElement>(null)
+  useShortcut("mod+enter", onSave, { layer: content, description: "Save" })
+
+  return <DialogContent ref={content}>Edit your note here.</DialogContent>
+}
+
+export { EditorContent }
+```
+
+Render this part inside a Dialog. Its shortcut runs only while that dialog is open. `layer` also accepts an element or a function that returns one.
+
+When shortcuts share the same keys, the topmost open layer wins, then the most recently registered shortcut. Development builds warn about duplicate keys in the same place.
+
+## List Available Shortcuts
+
+Call `shortcuts.list()` when a help screen opens. It returns the shortcuts that can run now, with their `keys`, formatted `hint`, and `description`:
+
+```ts
+import { shortcuts } from "@ui-sdk/react/shortcuts"
+
+const labels = shortcuts
+  .list()
+  .map(({ hint, description }) => `${hint} ${description ?? ""}`)
+```
+
+Add descriptions when registering shortcuts so the help screen can explain each action.

package/docs/installation.md

@@ -0,0 +1,45 @@
+# Installation
+
+Install UI SDK in your React app.
+
+Start with an app using React 19 and React DOM 19 or newer.
+
+## Install the Packages
+
+```bash
+npm install @ui-sdk/react @ui-sdk/core
+```
+
+`@ui-sdk/react` provides the React 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.
+
+If you use TypeScript, you'll also need `@types/react` 19.2.10 or newer.
+
+## Import a Component
+
+Import each component from its own entry:
+
+```tsx
+import { Button } from "@ui-sdk/react/button"
+import { Toggle } from "@ui-sdk/react/toggle"
+```
+
+A Dialog has separate parts for its trigger, content, and title. Import those parts from the same entry:
+
+```tsx
+import {
+  Dialog,
+  DialogContent,
+  DialogTitle,
+  DialogTrigger,
+} from "@ui-sdk/react/dialog"
+```
+
+There is no root import from `@ui-sdk/react`. Each [component page](./README.md) lists the parts you can use.
+
+## 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 or importing a UI SDK stylesheet. If you use Next.js, [Server Rendering](./server-rendering.md) explains when your own components need `"use client"`.
+
+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 React components with keyboard, focus, and screen reader support built in.
+
+These docs cover ui-sdk in React. Using another framework? See Vue, Svelte, Solid or Web Components. To build your own components from behaviors, see [Core](./core.md).
+
+`@ui-sdk/react` 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 React project. It needs React 19 or newer.
+
+1. Install @ui-sdk/react 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/react/docs/llms.txt. To build a new component, also search node_modules/@ui-sdk/react/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 React 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.