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

package/docs/components/avatar.md

@@ -0,0 +1,252 @@
+# Avatar
+
+Show an image with a fallback while it loads or if it fails.
+
+Use an Avatar for a person or a team, like in a comment, a member list or an account menu. It shows initials or an icon until the image loads, and keeps showing them if the image fails.
+
+```tsx title="basic.tsx"
+import { Avatar, AvatarFallback, AvatarImage } from "@ui-sdk/react/avatar"
+
+const person = {
+  name: "shadcn",
+  src: "https://github.com/shadcn.png",
+}
+
+export function Example() {
+  return (
+    <div data-slot="row">
+      <Avatar>
+        <AvatarImage src={person.src} alt={person.name} />
+        <AvatarFallback>
+          <span aria-hidden="true">CN</span>
+          <span data-slot="visually-hidden">shadcn</span>
+        </AvatarFallback>
+      </Avatar>
+    </div>
+  )
+}
+```
+
+The image replaces the initials once it loads. A screen reader can read the person's name in either state.
+
+## Installation
+
+```bash
+npm install @ui-sdk/react @ui-sdk/core
+```
+
+## Composition
+
+Use the following composition to build an `Avatar`:
+
+```text
+Avatar
+├── AvatarImage
+└── AvatarFallback
+```
+
+- `Avatar` shares the image's loading state with its parts.
+- `AvatarImage` renders the image.
+- `AvatarFallback` shows when no image is loaded.
+
+The image is a real `img`, including in server markup. The browser can start fetching it before hydration. The fallback stays visible until the image loads; if loading fails, the fallback remains.
+
+## Usage
+
+Import the parts and put them together:
+
+```tsx
+<Avatar>
+  <AvatarImage src="/ada.png" alt="Ada Lovelace" />
+  <AvatarFallback>AL</AvatarFallback>
+</Avatar>
+```
+
+## Build Your Own
+
+`@ui-sdk/react/avatar` comes with a ready-made Avatar. If you'd like to build your own, with your own names, start from the `avatar` primitive in `@ui-sdk/core`:
+
+```ts title="user-photo.ts"
+"use client"
+
+import { avatar } from "@ui-sdk/core/avatar"
+import { createParts } from "@ui-sdk/react/primitive"
+
+const {
+  Root: UserPhoto,
+  Image: UserPhotoImage,
+  Fallback: UserPhotoInitials,
+} = createParts(avatar, { root: "span", image: "img", fallback: "span" })
+
+export { UserPhoto, UserPhotoImage, UserPhotoInitials }
+```
+
+```tsx
+<UserPhoto>
+  <UserPhotoImage src="https://github.com/shadcn.png" alt="shadcn" />
+  <UserPhotoInitials>CN</UserPhotoInitials>
+</UserPhoto>
+```
+
+These are the same parts the ready-made Avatar is made of, with your names. See [Rendering](../rendering.md) and [Custom Rendering](#custom-rendering) for more.
+
+## Fallback Delay
+
+<span id="behavior-and-options" />
+
+Set `delay` on the fallback to wait before showing it. This avoids flashing initials when an image loads quickly. Without a delay, the fallback appears immediately, including on the server.
+
+```tsx
+<Avatar>
+  <AvatarImage src="https://github.com/shadcn.png" alt="shadcn" />
+  <AvatarFallback delay={600}>CN</AvatarFallback>
+</Avatar>
+```
+
+## Image Attributes
+
+Pass image attributes such as `srcSet`, `crossOrigin`, and `referrerPolicy` to the image. They work on the same `img` the browser loads. For avatars farther down a page, use `loading="lazy"`.
+
+```tsx
+<Avatar>
+  <AvatarImage
+    src="https://github.com/shadcn.png"
+    srcSet="https://github.com/shadcn.png?size=80 1x, https://github.com/shadcn.png?size=160 2x"
+    alt="shadcn"
+    crossOrigin="anonymous"
+    referrerPolicy="no-referrer"
+    loading="lazy"
+  />
+  <AvatarFallback>CN</AvatarFallback>
+</Avatar>
+```
+
+<span id="render-functions" />
+
+## Interactive Avatar
+
+Use a button when clicking an avatar performs an action. Give it an accessible name that stays available while the image loads.
+
+```tsx
+<Avatar
+  render={<button type="button" aria-label="shadcn" />}
+  onClick={openProfile}
+>
+  <AvatarImage src="https://github.com/shadcn.png" alt="" />
+  <AvatarFallback aria-hidden>CN</AvatarFallback>
+</Avatar>
+```
+
+[Parts and Composition](../parts-and-composition.md) explains how to change the root element in this framework.
+
+## Loading Status
+
+`onLoadingStatusChange` receives the new status and change details. The possible statuses are `loading`, `loaded`, `error`, and `idle`.
+
+```tsx
+<Avatar
+  onLoadingStatusChange={(status, details) => {
+    if (status === "error") reportBrokenImage(details.reason)
+  }}
+>
+  <AvatarImage src={user.image} alt={user.name} />
+  <AvatarFallback>{user.initials}</AvatarFallback>
+</Avatar>
+```
+
+When you replace a loaded image, the browser keeps it visible while the next source loads. A failed replacement shows the fallback. The change details explain why the status changed; see [Reasons](#reasons).
+
+## Custom Rendering
+
+Use [Parts and Composition](../parts-and-composition.md) to replace an element or read its state. Every part receives the loading status, so the fallback can say something different when the image fails:
+
+```tsx
+<Avatar>
+  <AvatarImage src={user.image} alt={user.name} />
+  <AvatarFallback>
+    {(state) => (state.loadingStatus === "error" ? "?" : user.initials)}
+  </AvatarFallback>
+</Avatar>
+```
+
+## Styling
+
+Set the root's size and let the image and fallback fill it. The image manages its own hidden styles until it loads; keep those styles intact when changing its element.
+
+Each part has a `data-slot`, such as `avatar-fallback`, and shows the loading status through the attributes listed under [Data Attributes](#data-attributes).
+
+## Data Attributes
+
+### Avatar
+`[data-slot="avatar"]`
+
+- `data-loading-status` (`idle`, `loading`, `loaded`, `error`): Where the image is: no image yet, loading, loaded, or failed.
+
+### AvatarImage
+`[data-slot="avatar-image"]`
+
+- `data-loading-status` (`idle`, `loading`, `loaded`, `error`): Where the image is: no image yet, loading, loaded, or failed.
+
+### AvatarFallback
+`[data-slot="avatar-fallback"]`
+
+- `data-loading-status` (`idle`, `loading`, `loaded`, `error`): Where the image is: no image yet, loading, loaded, or failed.
+
+## API Reference
+
+Props and callbacks are the same as below, as React props.
+
+### Avatar
+
+- `onLoadingStatusChange?` (`((status: AvatarLoadingStatus, details: ChangeDetails<AvatarLoadingStatusChangeReason>) => void)`): Runs when the image's loading status changes: `"loading"` when it gets a source, `"loaded"`, `"error"`, and `"idle"` when it leaves the page. `details.reason` says why, and `details.event` is the image's `load` or `error` event, or undefined when the status was known at once, like for a cached image.
+- `debug?` (`boolean`): Logs every state change with its reason to the console, in development builds.
+
+### AvatarImage
+
+The image. Renders a real `img`, so the browser can fetch it before hydration, and accepts its attributes, such as `srcSet`, `crossOrigin` and `referrerPolicy`.
+
+### AvatarFallback
+
+- `delay?` (`number`): How long to wait, in milliseconds, before showing the fallback, so a fast image appears without the fallback flashing first. Without one, the fallback shows at once, server markup included.
+
+### State
+
+What render functions, state-based class names and slots receive. Every part gets the same state.
+
+- `loadingStatus` (`AvatarLoadingStatus`): Where the image is: `"idle"`, `"loading"`, `"loaded"` or `"error"`.
+
+### Reasons
+
+`details.reason` says why the status changed.
+
+- `image-load` (`Event | undefined`): An image loaded. No event when it was already in the browser's cache.
+- `image-error` (`Event | undefined`): An image failed to load, or has no source. No event when that was known at once.
+- `src-change` (`none`): An image got a new source, or left the page, so its status starts over.
+
+### Events
+
+Callbacks get the new status first, then the details.
+
+| Prop                    | On       | Receives                                                                            |
+| ----------------------- | -------- | ----------------------------------------------------------------------------------- |
+| `onLoadingStatusChange` | `Avatar` | `(status, details)`: the image's status, the [reason](#reasons) and `details.event` |
+
+## Accessibility
+
+Give the image meaningful `alt` text. Include the person's name in the fallback too, using visually hidden text if you only want to show initials.
+
+When a visible name beside the avatar already identifies the person, use an empty `alt` and hide decorative fallback content from screen readers.
+
+- An image that loads replaces the fallback.
+- An image that fails keeps the fallback.
+- An avatar without an image shows its fallback.
+- A fallback with a delay waits before showing.
+- The image's loading status is reported.
+- Removing the image brings the fallback back.
+- A new source shows its image once it loads.
+- The image is fetched with its own referrer policy.
+- A cached image doesn't flash the fallback when the avatar mounts again.
+- A new source keeps showing the previous image until it loads.
+- The image is fetched once, even when it can't be cached.
+
+Runs in React, Vue and web components.

package/docs/components/button.md

@@ -0,0 +1,444 @@
+# Button
+
+Run an action, show that it's working, and keep it reachable when disabled.
+
+Button renders a native `button` and adds what it doesn't do on its own: it stays pending while an async action runs, so a form can't submit twice, announces slow actions to screen readers, can stay focusable while disabled, and keeps the same behavior when it renders a link. For a plain click handler, a native `button` is enough.
+
+```tsx title="basic.tsx"
+import { Button } from "@ui-sdk/react/button"
+import { useLog } from "./log"
+
+function Example() {
+  const log = useLog()
+
+  return <Button onClick={() => log("Pressed")}>Button</Button>
+}
+
+export { Example }
+```
+
+Click Button, or focus it and press Enter or Space. The console logs each press.
+
+## Installation
+
+```bash
+npm install @ui-sdk/react @ui-sdk/core
+```
+
+## Usage
+
+Use `onClick` to run an action. Button renders a native `<button>` with `type="button"` by default.
+
+```tsx
+import { Button } from "@ui-sdk/react/button"
+
+;<Button onClick={() => save()}>Save</Button>
+```
+
+## Pending
+
+Return a Promise from `onClick` to keep the button pending until it settles. The button keeps focus and ignores further presses while it waits.
+
+```tsx
+<Button
+  onClick={() => new Promise((resolve) => setTimeout(resolve, 1500))}
+  pendingAnnouncement="Saving"
+>
+  Save
+</Button>
+```
+
+After one second, it announces "Loading" to screen readers. Set `pendingAnnouncement` to change that message, as above, or use an empty string to silence it.
+
+```tsx title="pending.tsx"
+"use client"
+
+import { Button } from "@ui-sdk/react/button"
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+function Example() {
+  return (
+    <Button onClick={() => wait(1500)} pendingAnnouncement="Saving">
+      Save
+    </Button>
+  )
+}
+
+export { Example }
+```
+
+Press Save, then press it again while it saves. Nothing happens until the first action finishes.
+
+## Pending Content
+
+To change what the button shows while it waits, mark content with `data-show="idle"` or `data-show="pending"` and hide it in the other state with one CSS rule each, or use Tailwind's `in-data-pending` variant:
+
+```css
+[data-slot="button"]:not([data-pending]) [data-show="pending"],
+[data-slot="button"][data-pending] [data-show="idle"] {
+  display: none;
+}
+```
+
+```tsx title="pending-content.tsx"
+"use client"
+
+import { Button } from "@ui-sdk/react/button"
+import { ArrowDownToLineIcon, LoaderCircleIcon } from "lucide-react"
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+function Example() {
+  return (
+    <Button onClick={() => wait(1500)} pendingAnnouncement="Saving">
+      <ArrowDownToLineIcon data-show="idle" aria-hidden="true" />
+      <LoaderCircleIcon data-show="pending" data-slot="spinner" aria-hidden="true" />
+      Save
+    </Button>
+  )
+}
+
+export { Example }
+```
+
+Press Save. Its arrow turns into a spinner while it saves.
+
+Keep the label and change only the visual, as above. If the text has to change too, swap it the same way, without an `aria-label`. [Pending Buttons](#pending-buttons) explains why:
+
+```tsx
+<Button onClick={save}>
+  <span data-show="idle">Save</span>
+  <span data-show="pending">Saving…</span>
+</Button>
+```
+
+## Handling Errors
+
+If the handler throws or its Promise rejects, `state.error` holds the error. Use it to show a message or a retry label. The next press clears the error and runs the handler again.
+
+The demo uses a [render function](../parts-and-composition.md#read-the-state) to show the error beside the button.
+
+```tsx title="render.tsx"
+"use client"
+
+import { Button } from "@ui-sdk/react/button"
+import { useLog } from "./log"
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+function Example() {
+  const log = useLog()
+
+  return (
+    <div data-slot="stack">
+      <Button
+        onClick={async () => {
+          await wait(1000)
+          log("Couldn't save. Check your connection and try again.")
+          throw new Error("Couldn't save")
+        }}
+        render={(props, state) => (
+          <button {...props}>
+            {state.pending
+              ? "Saving…"
+              : state.error
+                ? "Try Again"
+                : "Save Changes"}
+          </button>
+        )}
+      />
+    </div>
+  )
+}
+
+export { Example }
+```
+
+Choose Save Changes. Saving always fails here: the console shows the error and the label changes to Try Again.
+
+## Changes After an Await
+
+`onClick` receives the event and `{ source }`, which says how the button was pressed. If the handler changes another ui-sdk component after an `await`, wrap that change in `withSource` to keep the original source. Otherwise, the later change is reported as `"programmatic"`.
+
+Here `save()` is your request and `status` is an Input's [controller](../controllers.md):
+
+```tsx
+"use client"
+
+import { Button } from "@ui-sdk/react/button"
+import { withSource } from "@ui-sdk/react/observe"
+
+function SaveButton() {
+  return (
+    <Button
+      onClick={async (event, { source }) => {
+        await save()
+        withSource(source, () => status.setValue("Saved"))
+      }}
+    >
+      Save
+    </Button>
+  )
+}
+
+export { SaveButton }
+```
+
+[Observe](../core.md#keep-the-source-after-an-await) explains source tracking. Preserving `"agent"` lets [`undoSource("agent")`](../agents.md#undo-the-agents-changes) include that later change.
+
+## Disabled
+
+Set `disabled` to prevent presses and remove the button from the tab order. A disabled `<fieldset>` around the button disables it too.
+
+```tsx
+<Button disabled>Disabled</Button>
+```
+
+```tsx title="disabled.tsx"
+import { Button } from "@ui-sdk/react/button"
+
+function Example() {
+  return <Button disabled>Disabled</Button>
+}
+
+export { Example }
+```
+
+Try clicking the button. It does nothing, and Tab skips it.
+
+## Focusable When Disabled
+
+Add `focusableWhenDisabled` when people should still be able to focus a disabled button. It uses `aria-disabled` instead of the native `disabled` attribute. Presses still do nothing.
+
+Use `aria-describedby` to explain why the action is unavailable:
+
+```tsx
+<Button disabled focusableWhenDisabled aria-describedby="publish-hint">
+  Publish
+</Button>
+<p id="publish-hint">Add a title to publish.</p>
+```
+
+```tsx title="focusable-when-disabled.tsx"
+"use client"
+
+import * as React from "react"
+import { Button } from "@ui-sdk/react/button"
+import { Field, FieldLabel } from "@ui-sdk/react/field"
+import { Input } from "@ui-sdk/react/input"
+import { useLog } from "./log"
+
+function Example() {
+  const log = useLog()
+  const [title, setTitle] = React.useState("")
+  const hint = React.useId()
+  const ready = title.trim() !== ""
+
+  return (
+    <div data-slot="stack">
+      <Field>
+        <FieldLabel>Title</FieldLabel>
+        <Input value={title} onValueChange={(value) => setTitle(value)} />
+      </Field>
+      <div data-slot="row">
+        <Button
+          disabled={!ready}
+          focusableWhenDisabled
+          aria-describedby={hint}
+          onClick={() => log(`Published “${title}”`)}
+        >
+          Publish
+        </Button>
+        <p id={hint} data-slot="hint">
+          {ready ? "Ready to publish." : "Add a title to publish."}
+        </p>
+      </div>
+    </div>
+  )
+}
+
+export { Example }
+```
+
+Focus Title, then press Tab to reach Publish while it is disabled. Enter a title to enable it, then choose Publish. The console logs what was published.
+
+## Links
+
+Pass an `<a>` to `render` to make a link. It keeps its `href` and link semantics, including opening in a new tab. A disabled link cannot navigate and leaves the tab order.
+
+```tsx
+<Button render={<a href="/docs/react" />}>Get started</Button>
+```
+
+```tsx title="link.tsx"
+import { Button } from "@ui-sdk/react/button"
+
+function Example() {
+  return (
+    <div data-slot="row">
+      <Button render={<a href="#installation" />}>Get Started</Button>
+      <Button disabled render={<a href="#changelog" />}>
+        Changelog
+      </Button>
+    </div>
+  )
+}
+
+export { Example }
+```
+
+Choose Get Started to jump to Installation on this page. Changelog is disabled and does not navigate.
+
+For your own components, see [Parts and Composition](../parts-and-composition.md).
+
+## Forms
+
+Set `type="submit"` to submit a form or `type="reset"` to restore its default values. The default, `type="button"`, does neither.
+
+```tsx
+<Button type="submit">Subscribe</Button>
+<Button type="reset">Reset</Button>
+```
+
+```tsx title="form.tsx"
+"use client"
+
+import { Field, FieldLabel } from "@ui-sdk/react/field"
+import { Input } from "@ui-sdk/react/input"
+import { Button } from "@ui-sdk/react/button"
+import { useLog } from "./log"
+
+function Example() {
+  const log = useLog()
+
+  return (
+    <form
+      data-slot="stack"
+      onSubmit={(event) => {
+        event.preventDefault()
+        const email = String(new FormData(event.currentTarget).get("email"))
+        log(`Subscribed ${email}`)
+      }}
+    >
+      <Field>
+        <FieldLabel>Email</FieldLabel>
+        <Input name="email" type="email" defaultValue="ada@example.com" />
+      </Field>
+      <div data-slot="row">
+        <Button type="submit">Subscribe</Button>
+        <Button type="reset">Reset</Button>
+      </div>
+    </form>
+  )
+}
+
+export { Example }
+```
+
+Edit the email and choose Subscribe, or press Enter in the field. The console logs each submission, and Reset restores the original email.
+
+Button tracks the Promise returned by its own `onClick`, not one from the form’s submit handler. For an async submit handler, keep your own pending flag and set `disabled` on the button while it runs, with [`focusableWhenDisabled`](#focusable-when-disabled) so the button keeps focus while it waits.
+
+## Styling
+
+Use `data-pending` to show a spinner or waiting cursor, and `data-disabled` to style an unavailable action. The button's `data-slot` is `button`, and its attributes are listed under [Data Attributes](#data-attributes).
+
+[Styling and Animation](../styling-and-animation.md) covers the styling patterns shared by all components.
+
+## Data Attributes
+
+### Button
+`[data-slot="button"]`
+
+- `data-pending`: Present while the Promise its press handler returned is running.
+- `data-disabled`: Present when disabled.
+
+## API Reference
+
+Button accepts native button props and the options below. `render`, `children`, `className` and `style` can read the button's state; see [Parts and Composition](../parts-and-composition.md).
+
+### Button
+
+- `disabled?` (`boolean`): Stops presses. The button is natively disabled, so it leaves the tab order and its form doesn't submit through it, unless `focusableWhenDisabled` is set.
+- `focusableWhenDisabled?` (`boolean`): Keeps a disabled button in the tab order with `aria-disabled` instead of the native attribute, so it can hold focus while it becomes disabled and host a tooltip that says why. Presses still do nothing.
+- `type?` (`"button" | "reset" | "submit"`): What a native button does in a form: `"submit"` submits it and `"reset"` resets it. Ignored when the button renders as something else.
+- `pendingAnnouncement?` (`string`): What screen readers hear once the button has been pending for a second, so a slow action doesn't pass in silence. Set it in the page's language. An empty string says nothing.
+- `debug?` (`boolean`): Logs every state change with its reason to the console, in development builds.
+
+### State
+
+- `disabled` (`boolean`): Whether it's disabled, by the `disabled` option or a disabled fieldset around it. A running press shows in `pending` instead.
+- `pending` (`boolean`): Whether the Promise the last press returned is still running. Presses do nothing meanwhile.
+- `error` (`unknown`): Why the last press failed: what its handler threw, or its Promise rejected with. Cleared by the next press.
+
+### Events
+
+| Prop      | Receives                                                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `onClick` | React's click event and `{ source }`, how the button was pressed. Return a Promise to keep the button pending until it settles. |
+
+## Accessibility
+
+Give the button a clear text label. If it contains only an icon, add an `aria-label`. Native buttons respond to Enter and Space; links respond to Enter.
+
+### Pending Buttons
+
+While its action runs, the button tells assistive technology it's busy, so you don't need to add anything:
+
+- It sets `aria-busy="true"` and `aria-disabled="true"`, and ignores presses until the action settles. It keeps focus the whole time.
+- After a second, it announces `pendingAnnouncement` ("Loading" by default) through a polite live region. Quick actions stay silent. This is a status message: people hear it without focus moving.
+
+To show progress, keep the label and change only the visual, like a spinner. Changing the text renames the button while it has focus: screen readers don't reliably announce a new name on the focused element, so the change mostly helps sighted users, and the button's width shifts as the text changes length. The announcement already tells everyone it's working.
+
+```tsx title="Do"
+<Button onClick={save} pendingAnnouncement="Saving">
+  <ArrowDownToLineIcon data-show="idle" aria-hidden="true" />
+  <LoaderCircleIcon data-show="pending" aria-hidden="true" />
+  Save
+</Button>
+```
+
+```tsx title="Don't"
+<Button onClick={save} aria-label="Save">
+  {saving ? "Saving…" : "Save"}
+  <span aria-live="polite">{saving ? "Saving" : ""}</span>
+</Button>
+```
+
+The second button tracks `saving` itself, shows text its accessible name doesn't contain, and announces the same state twice. If the text has to change anyway, swap it with `data-show` and leave out `aria-label`, so the button's name always contains the text on screen. See [Pending Content](#pending-content) for the markup.
+
+References:
+
+- [WCAG 2.5.3 Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html)
+- [WCAG 4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html)
+- [WAI-ARIA `aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy) and [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled)
+
+### Tested Behavior
+
+The following behaviors are covered by automated tests:
+
+- Clicking a button runs its handler.
+- Space presses a focused button.
+- Enter presses a focused button.
+- A submit button submits its form.
+- A reset button resets its form.
+- A disabled button can't be focused or pressed.
+- A button rendered as a link stays a link.
+
+**Focusable when disabled**
+
+- It stays focusable and says it's disabled.
+- Tab reaches it.
+- Clicking it runs nothing and submits nothing.
+- Space on it runs nothing and submits nothing.
+- Enter on it runs nothing and submits nothing.
+
+**Pending**
+
+- A returned Promise makes it busy, and it keeps focus until the Promise settles.
+- While pending, it says it's unavailable with aria-disabled and keeps focus.
+- Still pending after a second, it tells screen readers it's loading.
+- A rejected Promise ends the pending state.
+
+Runs in React, Vue and web components.