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

package/docs/utilities/async-options.md

@@ -0,0 +1,332 @@
+# Async Options
+
+Load search results, cancel stale requests, and fetch the next page.
+
+`createAsyncOptions` loads items as someone types. It waits for typing to pause, cancels requests that are replaced, and keeps the previous results visible while loading.
+
+```ts title="async.ts"
+import { createAsyncOptions } from "@ui-sdk/core/async-options"
+import "@ui-sdk/web/combobox"
+import { Check, ChevronDown, createElement } from "lucide"
+
+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 mount(root: HTMLElement) {
+  root.innerHTML = `
+    <ui-combobox filter="false" default-query="the">
+      <div data-slot="stack">
+        <ui-combobox-label>Movie</ui-combobox-label>
+        <div data-slot="row">
+          <ui-combobox-input>
+            <input placeholder="Search movies…" />
+          </ui-combobox-input>
+          <ui-combobox-trigger>
+            <button aria-label="Show movies">${createElement(ChevronDown, { "aria-hidden": "true" }).outerHTML}</button>
+          </ui-combobox-trigger>
+        </div>
+      </div>
+      <ui-combobox-content hidden>
+        <ui-combobox-status></ui-combobox-status>
+        <ui-combobox-empty>No movies match “<span>the</span>”.</ui-combobox-empty>
+        <ui-combobox-list></ui-combobox-list>
+      </ui-combobox-content>
+      <template>
+        <ui-combobox-item>
+          <ui-combobox-item-indicator>${createElement(Check, { "aria-hidden": "true" }).outerHTML}</ui-combobox-item-indicator>
+        </ui-combobox-item>
+      </template>
+    </ui-combobox>
+  `
+  const combobox = root.querySelector("ui-combobox")!
+  const status = root.querySelector("ui-combobox-status")!
+  const query = root.querySelector("ui-combobox-empty span")!
+  const movies = createAsyncOptions(searchMovies, {
+    debounce: 300,
+    query: "the",
+    immediate: true,
+  })
+  const update = () => {
+    const { items, status: loading } = movies.getState()
+    combobox.items = items
+    combobox.setAttribute("status", loading)
+    status.textContent =
+      loading === "error"
+        ? "Couldn't load movies."
+        : loading === "loading"
+          ? "Searching…"
+          : `${items.length} ${items.length === 1 ? "movie" : "movies"}`
+  }
+  movies.subscribe(update)
+  update()
+  combobox.addEventListener("querychange", (event) => {
+    query.textContent = event.detail.value
+    movies.setQuery(event.detail.value)
+  })
+}
+
+export { mount }
+```
+
+Change the movie search and wait for the results. Use the arrow keys to choose a movie, then press Enter.
+
+## Load Results
+
+Write the combobox, then connect its query events to a loader. This example expects `/api/movies` to return an array of movie titles:
+
+```html
+<ui-combobox filter="false">
+  <ui-combobox-input
+    ><input aria-label="Movie" placeholder="Search movies…"
+  /></ui-combobox-input>
+  <ui-combobox-content>
+    <ui-combobox-list></ui-combobox-list>
+  </ui-combobox-content>
+</ui-combobox>
+```
+
+```ts
+import "@ui-sdk/web/combobox"
+import { createAsyncOptions } from "@ui-sdk/core/async-options"
+import type { UiComboboxElement } from "@ui-sdk/web"
+
+function connectMovies(combobox: UiComboboxElement) {
+  const movies = createAsyncOptions<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()
+  })
+  function update() {
+    const { items, status } = movies.getState()
+    combobox.items = items
+    combobox.status = status
+  }
+  const unsubscribe = movies.subscribe(update)
+  update()
+  const events = new AbortController()
+  combobox.addEventListener(
+    "querychange",
+    (event) => movies.setQuery(event.detail.value),
+    {
+      signal: events.signal,
+    }
+  )
+  combobox.addEventListener("loadmore", () => movies.loadMore(), {
+    signal: events.signal,
+  })
+
+  return () => {
+    events.abort()
+    unsubscribe()
+    movies.cancel()
+  }
+}
+
+const disconnect = connectMovies(document.querySelector("ui-combobox")!)
+```
+
+Keep `disconnect` and call it when removing this view. It removes listeners, unsubscribes from state, and cancels pending work.
+
+Pass `signal` to `fetch` so a newer search can cancel the request. `filter="false"` leaves matching and result order to the server. Set `items` and `status` as properties, as shown above.
+
+Use the component's status and empty parts 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 helper's second argument sets its 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 before anyone types.                    | `false` |
+
+Add `{ immediate: true, debounce: 300 }` after the loader to load initial choices. If you set `query`, use the same text for the component's `default-query`.
+
+## Load More
+
+For paged results, return `{ items, hasMore }`. The page number starts at `0`:
+
+```ts
+import type { AsyncOptionsContext } from "@ui-sdk/core/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 `createAsyncOptions` in place of the inline loader above.
+
+The `loadmore` listener above asks for another page when scrolling or keyboard navigation reaches the last item. The helper appends the new items.
+
+```ts title="infinite.ts"
+import { createAsyncOptions } from "@ui-sdk/core/async-options"
+import "@ui-sdk/web/combobox"
+import { Check, ChevronDown, createElement } from "lucide"
+
+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 mount(root: HTMLElement) {
+  root.innerHTML = `
+    <ui-combobox filter="false">
+      <div data-slot="stack">
+        <ui-combobox-label>Movie</ui-combobox-label>
+        <div data-slot="row">
+          <ui-combobox-input>
+            <input placeholder="Search movies…" />
+          </ui-combobox-input>
+          <ui-combobox-trigger>
+            <button aria-label="Show movies">${createElement(ChevronDown, { "aria-hidden": "true" }).outerHTML}</button>
+          </ui-combobox-trigger>
+        </div>
+      </div>
+      <ui-combobox-content hidden>
+        <ui-combobox-empty>No movies found.</ui-combobox-empty>
+        <ui-combobox-list></ui-combobox-list>
+        <ui-combobox-status></ui-combobox-status>
+      </ui-combobox-content>
+      <template>
+        <ui-combobox-item>
+          <ui-combobox-item-indicator>${createElement(Check, { "aria-hidden": "true" }).outerHTML}</ui-combobox-item-indicator>
+        </ui-combobox-item>
+      </template>
+    </ui-combobox>
+  `
+  const combobox = root.querySelector("ui-combobox")!
+  const status = root.querySelector("ui-combobox-status")!
+  const movies = createAsyncOptions(searchMoviePages, { immediate: true })
+  const update = () => {
+    const { items, status: loading, hasMore } = movies.getState()
+    combobox.items = items
+    combobox.setAttribute("status", loading)
+    status.textContent =
+      loading === "loading"
+        ? "Loading more…"
+        : hasMore
+          ? `${items.length} loaded`
+          : `All ${items.length}`
+  }
+  movies.subscribe(update)
+  update()
+  combobox.addEventListener("querychange", (event) =>
+    movies.setQuery(event.detail.value)
+  )
+  combobox.addEventListener("loadmore", () => movies.loadMore())
+}
+
+export { mount }
+```
+
+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
+
+`movies.getState()` holds `items`, `status`, `error`, and `hasMore`. Status is `"loading"` during a request, `"error"` after a failure, and `"idle"` otherwise.
+
+Call `movies.reload()` from a retry button to load the current query again, starting at page `0`. Previous results stay available while it loads.

package/docs/utilities/shortcuts.md

@@ -0,0 +1,184 @@
+# Shortcuts
+
+Register keyboard shortcuts and show the right keys for the user's platform.
+
+`registerShortcut` connects keys to an action. For an element that already accepts `shortcut`, such as a dialog trigger, use that attribute directly.
+
+```ts title="basic.ts"
+import { ariaKeyshortcuts, formatShortcut, registerShortcut } from "@ui-sdk/web"
+
+export function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <div data-slot="stack">
+      <div data-slot="row">
+        <button type="button" data-action="new" aria-keyshortcuts="N">New note <kbd aria-hidden="true" data-slot="kbd">N</kbd></button>
+        <button type="button" data-action="save" aria-keyshortcuts="${ariaKeyshortcuts("mod+s")}">Save <kbd aria-hidden="true" data-slot="kbd">${formatShortcut("mod+s")}</kbd></button>
+      </div>
+      <output data-slot="output">Press N or the keys to save.</output>
+    </div>
+  `
+  const output = root.querySelector("output")!
+  const actions = {
+    new: () => (output.textContent = "Note created"),
+    save: () => (output.textContent = "Saved"),
+  }
+  root
+    .querySelector('[data-action="new"]')!
+    .addEventListener("click", actions.new)
+  root
+    .querySelector('[data-action="save"]')!
+    .addEventListener("click", actions.save)
+
+  const offs = [
+    registerShortcut("n", actions.new, { description: "New note" }),
+    registerShortcut("mod+s", actions.save, { description: "Save" }),
+  ]
+  return () => offs.forEach((off) => off())
+}
+```
+
+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:
+
+```html
+<button id="new-note">New note <kbd aria-hidden="true"></kbd></button>
+<p id="count" aria-live="polite">0 notes</p>
+```
+
+```ts
+import { ariaKeyshortcuts, formatShortcut, registerShortcut } from "@ui-sdk/web"
+
+const button = document.querySelector<HTMLButtonElement>("#new-note")!
+const count = document.querySelector("#count")!
+let total = 0
+function addNote() {
+  total++
+  count.textContent = `${total} notes`
+}
+
+const unregister = registerShortcut("mod+enter", addNote, {
+  description: "New note",
+})
+button.addEventListener("click", addNote)
+button.setAttribute("aria-keyshortcuts", ariaKeyshortcuts("mod+enter"))
+button.querySelector("kbd")!.textContent = formatShortcut("mod+enter")
+
+function disconnect() {
+  unregister()
+  button.removeEventListener("click", addNote)
+}
+```
+
+Call `disconnect()` when removing this view. `registerShortcut` returns the function that unregisters it.
+
+## Show the Keys
+
+`formatShortcut` produces display text for the current platform. `ariaKeyshortcuts` produces the matching `aria-keyshortcuts` value. The example hides the visual hint from screen readers because the button already exposes the shortcut.
+
+Format browser-specific hints after the page loads. Compare the original keys, not the formatted display text.
+
+## 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
+
+A named `scope` runs only while it is enabled. This connection turns it on when the textarea has focus and clears it on cleanup:
+
+```html
+<textarea id="note" aria-label="Note"></textarea>
+```
+
+```ts
+import { registerShortcut, shortcuts } from "@ui-sdk/web"
+
+function connectNote(note: HTMLTextAreaElement) {
+  const unregister = registerShortcut(
+    "escape",
+    () => {
+      note.value = ""
+    },
+    {
+      scope: "note",
+      allowInInput: true,
+    }
+  )
+  const events = new AbortController()
+  note.addEventListener("focus", () => shortcuts.setScope("note", true), {
+    signal: events.signal,
+  })
+  note.addEventListener("blur", () => shortcuts.setScope("note", false), {
+    signal: events.signal,
+  })
+  shortcuts.setScope("note", document.activeElement === note)
+
+  return () => {
+    events.abort()
+    shortcuts.setScope("note", false)
+    unregister()
+  }
+}
+
+const disconnect = connectNote(
+  document.querySelector<HTMLTextAreaElement>("#note")!
+)
+```
+
+Call `disconnect()` when removing the note. Scope names are shared, so choose one for each area you want to enable together. A `when` function can add a condition checked on each key press.
+
+```ts title="scope.ts"
+import { registerShortcut, shortcuts } from "@ui-sdk/web"
+
+export function mount(root: HTMLElement) {
+  root.innerHTML = `
+    <div data-slot="stack">
+      <textarea aria-label="Note" placeholder="Write a note…"></textarea>
+      <output data-slot="output">Focus the note to turn on its shortcuts.</output>
+    </div>
+  `
+  const textarea = root.querySelector("textarea")!
+  const output = root.querySelector("output")!
+  textarea.addEventListener("focus", () => shortcuts.setScope("note", true))
+  textarea.addEventListener("blur", () => shortcuts.setScope("note", false))
+
+  const offs = [
+    registerShortcut(
+      "mod+enter",
+      () =>
+        (output.textContent = `Characters saved: ${textarea.value.trim().length}`),
+      {
+        scope: "note",
+        when: () => textarea.value.trim() !== "",
+        description: "Save the note",
+      }
+    ),
+    registerShortcut(
+      "escape",
+      () => {
+        textarea.value = ""
+        output.textContent = "Cleared"
+      },
+      { scope: "note", allowInInput: true, description: "Clear the note" }
+    ),
+  ]
+  return () => {
+    offs.forEach((off) => off())
+    shortcuts.setScope("note", false)
+  }
+}
+```
+
+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 a popup or a function that returns one, to make a shortcut belong to that popup. It runs only while the popup is open, even though its closed content stays in the DOM.
+
+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.