@lumiose/ui 0.0.0-stage → 0.1.1

package/docs/accordion.md

@@ -0,0 +1,208 @@
+# Accordion
+
+> A stack of items whose triggers show and hide their panels, after the WAI-ARIA accordion pattern: each item is a native `<details>`, one open at a time through the browser's exclusive group (`name`) or several, so it works in server HTML with no JavaScript and find-in-page opens the item it lands in. `<lu-accordion>`, a 1 kB light-DOM element, adds the arrow keys and Base UI's animation hooks. `bind:value` (or `value` and `onValueChange`) keeps a signal in sync.
+
+```ts
+import { Accordion } from "@lumiose/ui"; // or "@lumiose/ui/accordion"
+import "@lumiose/ui/accordion.css"; // the root is a block; disabled triggers ignore the pointer
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Accordion.Root>
+  <Accordion.Item>
+    <Accordion.Header>
+      <Accordion.Trigger />
+    </Accordion.Header>
+    <Accordion.Panel />
+  </Accordion.Item>
+</Accordion.Root>
+```
+
+| Part      | Renders                                                                                                            |
+| --------- | ------------------------------------------------------------------------------------------------------------------ |
+| `Root`    | `<lu-accordion>`, around the items.                                                                                |
+| `Item`    | `<details name="…">`, right inside `Root`, `open` while its panel shows; no `name` when several may be open.       |
+| `Header`  | `<h3>` around the trigger's label: inside the `<summary>`, where HTML allows a heading.                            |
+| `Trigger` | `<summary aria-controls="…">`, the first child of `Item`: it opens and closes the panel.                           |
+| `Panel`   | `<div role="region" aria-labelledby="…">`, labelled by its trigger; the browser hides it while the item is closed. |
+
+HTML puts a heading inside a `<summary>`, not a `<summary>` inside a heading, so `Header` renders
+its `<h3>` inside the trigger's `<summary>`: the trigger names the heading, and the browser
+exposes the `<summary>` as a button with its expanded state. Set `aria-level` on `Header` for
+another heading level.
+
+## API
+
+### Accordion.Root
+
+| Prop            | Type                         | Default      |                                                                                                                   |
+| --------------- | ---------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `value`         | `string[]`                   |              | The values of the open items: opens and closes them when it changes. Server HTML starts as it says.               |
+| `defaultValue`  | `string[]`                   | `[]`         | The items open at first, when there is no `value`.                                                                |
+| `onValueChange` | `(value: string[]) => void`  |              | Called after an item opens or closes, with the values of the open items.                                          |
+| `bind:value`    | `Signal<string[]>`           |              | Stands in for `value` and `onValueChange`.                                                                        |
+| `multiple`      | `boolean`                    | `false`      | Several items may be open at once. By default opening one closes the other, and only the first value starts open. |
+| `disabled`      | `boolean`                    | `false`      | Every item is disabled.                                                                                           |
+| `orientation`   | `"vertical" \| "horizontal"` | `"vertical"` | The direction the arrow keys follow: Up and Down, or Left and Right.                                              |
+| `loopFocus`     | `boolean`                    | `true`       | The arrow keys go from the last trigger to the first and back.                                                    |
+
+Without `value`, `onValueChange` or `bind:value` the items keep their own state.
+
+### Accordion.Item
+
+| Prop           | Type                      | Default          |                                                                  |
+| -------------- | ------------------------- | ---------------- | ---------------------------------------------------------------- |
+| `value`        | `string`                  | an id of its own | Identifies the item in the root's `value`.                       |
+| `disabled`     | `boolean`                 | `false`          | Its trigger takes no focus and does not toggle the panel.        |
+| `onOpenChange` | `(open: boolean) => void` |                  | Called after the item opens or closes; not when it renders open. |
+
+### The other parts
+
+Each part takes the props of the element it renders (`class`, `style`, `aria-*`, `data-*`, event
+handlers, `ref`) and passes them through. A `Trigger`'s `id` names it, and its `Panel` points at
+it; a `Panel` keeps its own `id`, which its trigger points at (see [Ids](README.md#ids)). `name`,
+`aria-controls` and `aria-labelledby` stay the parts' own, since they connect the parts.
+
+- **`Trigger`**: a disabled trigger gets `aria-disabled="true"` and `tabindex="-1"`.
+- **`Panel`**: the client script sets `--lu-accordion-panel-height` and `--lu-accordion-panel-width` on
+  it while it opens and closes, and `data-starting-style` and `data-ending-style`
+  ([Styling](#styling)).
+
+## Example
+
+A FAQ in a server-rendered page, with no island, styled by the default theme:
+
+```tsx check
+import { Accordion } from "@lumiose/ui";
+
+export function ShippingFaq() {
+  return (
+    <Accordion.Root class="lu-accordion" defaultValue={["shipping"]}>
+      <Accordion.Item value="shipping">
+        <Accordion.Header>
+          <Accordion.Trigger>When will my order ship?</Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel>Within two working days.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="returns">
+        <Accordion.Header>
+          <Accordion.Trigger>Can I return it?</Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel>Yes, within 30 days, for free.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="gifts" disabled>
+        <Accordion.Header>
+          <Accordion.Trigger>Gift cards</Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel>Coming soon.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}
+```
+
+In an island, several items open, bound to a signal: `bind:value={open}` is short for
+`value={open()}` plus `onValueChange={(next) => open.set(next)}`.
+
+```tsx check
+import { Accordion } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function SettingsSections() {
+  const open = signal(["profile"]);
+  return (
+    <>
+      <Accordion.Root class="lu-accordion" multiple bind:value={open}>
+        <Accordion.Item value="profile">
+          <Accordion.Header>
+            <Accordion.Trigger>Profile</Accordion.Trigger>
+          </Accordion.Header>
+          <Accordion.Panel>Your name and photo.</Accordion.Panel>
+        </Accordion.Item>
+        <Accordion.Item value="security">
+          <Accordion.Header>
+            <Accordion.Trigger>Security</Accordion.Trigger>
+          </Accordion.Header>
+          <Accordion.Panel>Password and recovery keys.</Accordion.Panel>
+        </Accordion.Item>
+      </Accordion.Root>
+      <p>Open: {open().join(", ") || "none"}</p>
+    </>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-accordion` on `Root`: items between borders, triggers as rows
+with a chevron that turns while the item is open, and panels whose height animates.
+
+**With your own CSS**, style the parts through `class`, `[open]` on the items and
+`[aria-disabled]` on the triggers. The client script gives each panel what Base UI's does, for an
+open and close animation: `--lu-accordion-panel-height` (the content's height in pixels while it
+moves, `auto` once open), `data-starting-style` for the frame an opening starts from and
+`data-ending-style` while it closes. The browser hides a panel as soon as its item closes, so keep
+it visible while it closes with a transition on `::details-content`:
+
+```css
+.accordion > details > .panel {
+  overflow: hidden;
+  block-size: var(--lu-accordion-panel-height, auto);
+  transition: block-size 200ms ease-out;
+}
+.accordion > details > .panel:is([data-starting-style], [data-ending-style]) {
+  block-size: 0;
+}
+.accordion > details::details-content {
+  transition: content-visibility 200ms allow-discrete;
+}
+```
+
+Opening an item closes the open one, and both animate. `@lumiose/ui/accordion.css`, in the
+`lu.core` layer, makes `<lu-accordion>` a block, keeps a trigger's heading on the line of the
+`<summary>`'s marker (`display: inline`), and makes a disabled trigger ignore the pointer.
+
+## Keyboard and focus
+
+The [WAI-ARIA accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/), with its
+optional keys, as in Base UI:
+
+| Key            | Does                                                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Enter, Space   | On a trigger: opens or closes its item.                                                                                   |
+| Tab, Shift+Tab | Move through the triggers and the open panels' content.                                                                   |
+| Down, Up       | Move focus to the next or the previous trigger; Right and Left when `orientation="horizontal"`, swapped in right-to-left. |
+| Home, End      | Move focus to the first or the last trigger.                                                                              |
+
+- **Disabled triggers** are out of the tab order, and the arrow keys skip them.
+- **Looping**: from the last trigger, Down goes to the first, unless `loopFocus={false}`.
+
+## Without JavaScript, and the element's script
+
+Opening and closing, one open item at a time (the `name` group), find-in-page and links into a
+closed item are HTML features: an accordion in a server-rendered page works before any script
+loads, and with none. Disabled triggers ignore the pointer through CSS. `value`, `onValueChange`
+and `bind:value` need the component to run in an island.
+
+A page that renders an `Accordion` loads a 1 kB (brotli) module once, without the Lumiose runtime;
+islands bundle it. It defines `<lu-accordion>`, which adds the arrow keys, Home and End, and sets
+the panels' animation hooks (shared with [Collapsible](collapsible.md)); a disabled trigger does
+not toggle, also from the keyboard.
+
+## Browser support
+
+- **`<details name>`** (one open item at a time): Chrome 120, Firefox 130, Safari 17.2. Older
+  browsers let several items open.
+- **Find-in-page and links into a closed item** open it: Chrome 97, Firefox 139. Safari has not
+  shipped it yet (WebKit bug 304174): there, find-in-page skips a closed item.
+- **`::details-content`**, which the closing transition needs: Chrome 131, Firefox 143, Safari
+  18.4. Elsewhere a panel disappears at once when its item closes.
+
+## Related
+
+- [Collapsible](collapsible.md): one panel and its trigger.
+- [Tabs](tabs.md): one panel at a time, from a tab list.
+- [UI components](README.md): the approach, styling and the other components.

package/docs/autocomplete.md

@@ -0,0 +1,161 @@
+# Autocomplete
+
+> A text input with suggestions, for text that may be anything (a search, a tag, an address): the WAI-ARIA combobox pattern with list autocomplete, after Base UI's Autocomplete. Unlike a [Combobox](combobox.md), the text is the value: the input has the name and submits what is typed, and choosing a suggestion only fills it in. It runs on the Combobox's element (`<lu-combobox free>`, 5.0 kB) and parts, on server-rendered pages and in islands; `bind:value` keeps a signal in sync. Filtering, inline completion, groups, an empty state and a status.
+
+```ts
+import { Autocomplete } from "@lumiose/ui"; // or "@lumiose/ui/autocomplete"
+import "@lumiose/ui/autocomplete.css"; // Combobox's CSS: places the popup, hides filtered options
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Autocomplete.Root>
+  <Autocomplete.Label />
+  <Autocomplete.Input />
+  <Autocomplete.Clear />
+  <Autocomplete.Trigger />
+  <Autocomplete.Popup>
+    <Autocomplete.List>
+      <Autocomplete.Item />
+      <Autocomplete.Group>
+        <Autocomplete.GroupLabel />
+        <Autocomplete.Item />
+      </Autocomplete.Group>
+    </Autocomplete.List>
+    <Autocomplete.Empty />
+    <Autocomplete.Status />
+  </Autocomplete.Popup>
+</Autocomplete.Root>
+```
+
+| Part                  | Renders                                                                             |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| `Root`                | `<lu-combobox free>`: the element, with no box; `inline` with inline completion     |
+| `Label`               | `<label for>` the input                                                             |
+| `Input`               | `<input role="combobox" aria-autocomplete name value>`: the form control            |
+| `Clear`, `Trigger`    | `<button tabindex="-1">`: empty the text, or open and close the suggestions         |
+| `Popup`, `List`       | `<div popover>` around the `<div role="listbox">`, or the listbox as the popup      |
+| `Item`                | `<div role="option" data-value>`: a suggestion; its `value` is the text it fills in |
+| `Group`, `GroupLabel` | `<div role="group">` named by its `<div role="presentation">`                       |
+| `Empty`, `Status`     | `<div role="status">`: shown when nothing matches, or a message you update          |
+
+The parts are [Combobox](combobox.md)'s, under this Root: their props and styling hooks are the
+same.
+
+## API
+
+### Autocomplete.Root
+
+| Prop                                | Type                                     | Default      |                                                                                                         |
+| ----------------------------------- | ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
+| `value`                             | `string`                                 |              | Puts this text in the input when it changes. Pair it with `onValueChange`.                              |
+| `defaultValue`                      | `string`                                 |              | The text at first; a form reset goes back to it.                                                        |
+| `onValueChange`                     | `(value: string) => void`                |              | Called as the text changes: typing, choosing a suggestion, clearing.                                    |
+| `bind:value`                        | `Signal<string>`                         |              | Stands in for `value` and `onValueChange`.                                                              |
+| `open`, `onOpenChange`, `bind:open` | `boolean`, `(open: boolean) => void`     |              | Open or close the suggestions, and hear about it, as in Combobox.                                       |
+| `mode`                              | `"list" \| "both" \| "inline" \| "none"` | `"list"`     | How the suggestions complete the text (below).                                                          |
+| `filter`                            | `"contains" \| "startsWith"`             | `"contains"` | How `"list"` and `"both"` filter the suggestions, ignoring case and accents.                            |
+| `openOnInputClick`                  | `boolean`                                | `false`      | A click on the input opens the suggestions; otherwise typing and Arrow Down do.                         |
+| `autoHighlight`                     | `boolean`                                | `false`      | The first suggestion is highlighted as you type, so Enter fills it in.                                  |
+| `keepHighlight`                     | `boolean`                                | `false`      | A suggestion the pointer highlighted stays highlighted when it leaves the list.                         |
+| `submitOnItemClick`                 | `boolean`                                | `false`      | Choosing a suggestion (a click, or Enter on it) fills it in and submits the form, as a search box does. |
+| `limit`                             | `number`                                 | no limit     | Shows at most this many suggestions; a narrower text shows the others.                                  |
+| `name`                              | `string`                                 |              | The name the text is submitted under (the input's).                                                     |
+| `required`, `disabled`              | `boolean`                                | `false`      | As on a native input.                                                                                   |
+
+The modes follow Base UI's:
+
+- **`"list"`**: typing filters the suggestions; the input keeps what is typed while the arrows move
+  through them.
+- **`"both"`**: filtered, and the arrows show the highlighted suggestion in the input, its
+  completed part selected; Escape takes it back, Tab or a click elsewhere keeps it.
+- **`"inline"`**: the arrows show the highlighted suggestion in the input, unfiltered.
+- **`"none"`**: neither: the page filters the suggestions itself (results from a server).
+
+### The other parts
+
+As in [Combobox](combobox.md#the-other-parts). An `Item`'s `value` is the text it fills in (and its
+`label`, when the shown text differs, what typing matches). Inside a [Field](field.md), the input
+takes the field's id, name, description and error, and the field shows its validation.
+
+**Differences from Base UI's Autocomplete.** The suggestions are markup, not an `items` array, and
+filtering compares their text (`mode="none"` hands it to you, as Base UI's `filter={null}`).
+`limit` hides the matches past it, as filtering does, so it applies to the server's suggestions
+too. No `Portal`, `Positioner`,
+`Backdrop`, `Arrow`, `Value`, `Icon`, `Row`, `Collection` or `Separator`.
+
+## Example
+
+A search with suggestions, in an island:
+
+```tsx check
+import { Autocomplete } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+const TOPICS = ["accessibility", "animation", "forms", "islands", "routing", "signals"];
+
+export function TopicSearch() {
+  const query = signal("");
+  return (
+    <>
+      <Autocomplete.Root name="q" bind:value={query} class="lu-combobox">
+        <Autocomplete.Label>Search the docs</Autocomplete.Label>
+        <Autocomplete.Input placeholder="Any topic" />
+        <Autocomplete.Popup>
+          <Autocomplete.List>
+            {TOPICS.map((topic) => (
+              <Autocomplete.Item value={topic}>{topic}</Autocomplete.Item>
+            ))}
+          </Autocomplete.List>
+          <Autocomplete.Empty>No suggestions: press Enter to search.</Autocomplete.Empty>
+        </Autocomplete.Popup>
+      </Autocomplete.Root>
+      <p>{query() ? `Searching for “${query()}”` : "Type to search."}</p>
+    </>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-combobox` on `Root`, as for a Combobox: the label, the input
+with its buttons, and the popup with the highlighted suggestion marked.
+
+**With your own CSS**, style the parts through `class` and their state: `[aria-expanded]` on the
+input, `:popover-open` on the popup, `[data-highlighted]` and `[aria-disabled]` on the
+suggestions, `[hidden]` on filtered ones.
+
+`@lumiose/ui/autocomplete.css` is Combobox's stylesheet: it places the popup next to the input and
+keeps filtered suggestions hidden.
+
+## Keyboard and focus
+
+| Key                   | Does                                                                                                                                                                       |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Typing                | Filters the suggestions (with `"list"` and `"both"`) and opens them; an empty input closes them.                                                                           |
+| Arrow Down / Arrow Up | Opens the suggestions, then moves the highlight (with `"both"` and `"inline"`, into the input).                                                                            |
+| Enter                 | Fills in the highlighted suggestion (the first, with `autoHighlight`); with none, submits.                                                                                 |
+| Escape                | Open: closes the suggestions and keeps the typed text (taking back an inline completion). Closed: clears the text, as Base UI's; closed and empty, it goes on to the page. |
+| Tab                   | Closes the suggestions and moves on, keeping the text.                                                                                                                     |
+
+Focus stays in the input: the highlight moves through `aria-activedescendant`.
+
+## Without JavaScript, and the element's script
+
+The input is a native text field with the name: typing, `required`, submission and reset work with
+no script; the suggestions need it. `<lu-combobox>`'s script (5.0 kB brotli, shared with Combobox)
+filters and opens them, moves the highlight, fills in a choice (firing `input` and `change` on the
+input) and runs inline completion.
+
+## Browser support
+
+As [Combobox](combobox.md#browser-support): popover, and CSS anchor positioning where available
+(the script places the popup elsewhere).
+
+## Related
+
+- [Combobox](combobox.md): a value picked from the options, when the text must match one.
+- [Field](field.md): a label, a description and errors for an autocomplete.
+- [Input](input.md): a text field without suggestions.

package/docs/avatar.md

@@ -0,0 +1,198 @@
+# Avatar
+
+> A person's picture with a fallback, such as their initials, after Base UI's Avatar: the image loads in the server HTML and shows once it has loaded, the fallback shows until then, after an optional delay, and when the image fails. Both sit in one cell, so neither moves the other. A 0.5 kB script follows the image's loading status; without JavaScript an avatar with an image shows the image alone.
+
+```ts
+import { Avatar } from "@lumiose/ui"; // or "@lumiose/ui/avatar"
+import "@lumiose/ui/avatar.css"; // stacks the image over the fallback; hides each in turn
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Avatar.Root>
+  <Avatar.Image />
+  <Avatar.Fallback />
+</Avatar.Root>
+```
+
+| Part       | Renders                                                                                        |
+| ---------- | ---------------------------------------------------------------------------------------------- |
+| `Root`     | `<lu-avatar>`, an inline grid with one cell, `data-loaded` once the image has loaded.          |
+| `Image`    | `<img data-loading>`: `data-loading` while it loads, `data-error` when it failed, both hidden. |
+| `Fallback` | `<span data-fallback>`, hidden once the image has loaded.                                      |
+
+The image is the root's `<img>` child; anything else inside, such as a status badge, is yours to
+place.
+
+## API
+
+### Avatar.Image
+
+| Prop                    | Type                                                 | Default |                                                                                                                                           |
+| ----------------------- | ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `onLoadingStatusChange` | `(status: "loading" \| "loaded" \| "error") => void` |         | Called when the loading status changes; `"error"` also when there is no `src`. An island hears the status the image had when it hydrated. |
+
+Every native `<img>` prop passes through: `src`, `srcset`, `sizes`, `alt`, `width`, `height`,
+`loading`, `decoding`, `fetchpriority`. A new `src` or `srcset` starts over at `"loading"`.
+
+### Avatar.Fallback
+
+| Prop    | Type     | Default |                                                                                                           |
+| ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| `delay` | `number` | `0`     | How long to wait before showing the fallback, in milliseconds: an image that loads sooner never shows it. |
+
+### The other parts
+
+`Root` and `Fallback` take the props of the element they render (`class`, `style`, `aria-*`,
+`data-*`, event handlers) and pass them through. The root element has a `status` property
+(`"loading"`, `"loaded"`, `"error"`, or `undefined` without an image), and the image dispatches
+`loadingstatuschange` (`event.detail.status`) for `on:loadingstatuschange`.
+
+**Differences from Base UI's Avatar.** The image is always in the page, as with Base UI's
+`keepMounted`: it starts loading with the server HTML, supports `loading="lazy"`, and shows without
+JavaScript. A missing `src` is `"error"`, not `"idle"`. No `render`.
+
+## Example
+
+Two people in a server-rendered page, with no island: an image that loads, and one that fails and
+leaves the initials. The default theme draws the circles.
+
+```tsx check
+import { Avatar } from "@lumiose/ui";
+
+// A portrait drawn inline, so the example runs anywhere.
+const portrait = `data:image/svg+xml,${encodeURIComponent(
+  `<svg xmlns="http://www.w3.org/2000/svg" width="80" height="80" viewBox="0 0 80 80">
+    <rect width="80" height="80" fill="#c7d2fe"/>
+    <circle cx="40" cy="31" r="14" fill="#4338ca"/>
+    <path d="M12 80a28 28 0 0 1 56 0z" fill="#4338ca"/>
+  </svg>`,
+)}`;
+
+export function Reviewers() {
+  return (
+    <ul aria-label="Reviewers" style={{ display: "flex", gap: "0.5rem", "list-style": "none" }}>
+      <li>
+        <Avatar.Root class="lu-avatar">
+          <Avatar.Image src={portrait} alt="Ada Lovelace" />
+          <Avatar.Fallback role="img" aria-label="Ada Lovelace" delay={600}>
+            AL
+          </Avatar.Fallback>
+        </Avatar.Root>
+      </li>
+      <li>
+        <Avatar.Root class="lu-avatar">
+          <Avatar.Image src="/avatars/missing.jpg" alt="Grace Hopper" />
+          <Avatar.Fallback role="img" aria-label="Grace Hopper">
+            GH
+          </Avatar.Fallback>
+        </Avatar.Root>
+      </li>
+    </ul>
+  );
+}
+```
+
+In an island, the loading status in a signal, as the picture breaks and comes back:
+
+```tsx check
+import { Avatar, type AvatarLoadingStatus } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+const portrait = `data:image/svg+xml,${encodeURIComponent(
+  `<svg xmlns="http://www.w3.org/2000/svg" width="80" height="80" viewBox="0 0 80 80">
+    <rect width="80" height="80" fill="#fde68a"/>
+    <circle cx="40" cy="31" r="14" fill="#b45309"/>
+    <path d="M12 80a28 28 0 0 1 56 0z" fill="#b45309"/>
+  </svg>`,
+)}`;
+
+export function ProfilePicture() {
+  const broken = signal(false);
+  const status = signal<AvatarLoadingStatus>("loading");
+  return (
+    <>
+      <Avatar.Root class="lu-avatar">
+        <Avatar.Image
+          src={broken() ? "/avatars/missing.jpg" : portrait}
+          alt=""
+          onLoadingStatusChange={(next) => status.set(next)}
+        />
+        <Avatar.Fallback aria-hidden="true">AL</Avatar.Fallback>
+      </Avatar.Root>
+      <p>Ada Lovelace (picture: {status()})</p>
+      <button type="button" class="lu-button" onClick={() => broken.set(!broken())}>
+        {broken() ? "Fix the picture" : "Break the picture"}
+      </button>
+    </>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-avatar` on `Root`: a 40px circle on a muted surface, the image
+covering it, the fallback's initials centred.
+
+**With your own CSS**, give the root a size, so the image loading or failing never changes the
+layout, and style the parts through `class`, `[data-loaded]`, `[data-loading]`, `[data-error]` and
+`[data-fallback]`:
+
+```css
+.avatar {
+  place-items: center;
+  inline-size: 3rem;
+  block-size: 3rem;
+  overflow: hidden;
+  border-radius: 50%;
+  background: #f4f4f5;
+}
+.avatar > img {
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+}
+```
+
+`@lumiose/ui/avatar.css`, in the `lu.core` layer, puts the parts in one grid cell, the image above
+the fallback, and hides them in turn with `visibility` (so a `loading="lazy"` image still loads):
+the image while it loads, where scripting is enabled, and when it failed; the fallback once the
+image has loaded. The fallback's `delay` is a zero-length `lu-avatar-delay` animation: an animation
+of your own on the fallback replaces it, so list both (`animation: lu-avatar-delay 0s
+var(--lu-avatar-delay, 0s) backwards, my-fade 200ms`).
+
+## Keyboard and focus
+
+An avatar takes no focus and has no keys. Name it once:
+
+- **Next to the person's name**, it repeats it: `alt=""` on the image and `aria-hidden="true"` on
+  the fallback.
+- **Alone**, name both parts, since only one shows at a time: the image's `alt`, and on the
+  fallback `role="img"` with an `aria-label`, so the initials are not read letter by letter.
+
+## Without JavaScript, and the client script
+
+The image and the fallback are in the server HTML. Without JavaScript nothing tells a failed image
+from a loaded one, so an avatar with an image shows the image alone (the browser's broken-image box
+when it fails) and hides its fallback, from sight and from assistive technology, which would name
+the avatar twice; an avatar without an image shows its fallback.
+`onLoadingStatusChange` needs the component to run in an island.
+
+A page that renders an `Avatar` loads a 0.5 kB (brotli) script, without the Lumiose runtime;
+islands bundle it. `<lu-avatar>` reads the image's state when it connects (a cached image shows
+at once), then follows its `load` and `error` events and changes to its `src` and `srcset`. An
+image that is complete without a size (an SVG without intrinsic dimensions, or a broken image) is
+told apart with `decode()`.
+
+## Browser support
+
+- **The `scripting` media query**, which keeps a loading image hidden only where scripts run:
+  Chrome and Edge 120, Firefox 113, Safari 17. Elsewhere a loading image shows as it arrives.
+- **CSS grid and `visibility`**: every browser.
+
+## Related
+
+- [UI components](README.md): the approach, styling and the other components.
+- [Theming](theming.md): the default theme's classes and custom properties.

package/docs/button.md

@@ -0,0 +1,98 @@
+# Button
+
+> A native `<button>`, after Base UI's Button. It is `type="button"` unless you say otherwise, so it submits a form only when asked to. Disabled it leaves the tab order; with `focusableWhenDisabled` it stays focusable as `aria-disabled="true"` (a loading state keeps focus where it was) and a tiny script cancels its clicks.
+
+```ts
+import { Button } from "@lumiose/ui"; // or "@lumiose/ui/button"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Button>Save</Button>
+```
+
+| Part     | Renders                                                                       |
+| -------- | ----------------------------------------------------------------------------- |
+| `Button` | `<button type="button">`; `aria-disabled="true"` with `focusableWhenDisabled` |
+
+## API
+
+### Button
+
+| Prop                    | Type      | Default    |                                                                                                                     |
+| ----------------------- | --------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
+| `type`                  | `string`  | `"button"` | `"submit"` or `"reset"` to act on its form.                                                                         |
+| `disabled`              | `boolean` | `false`    | Natively disabled: out of the tab order, its clicks ignored.                                                        |
+| `focusableWhenDisabled` | `boolean` | `false`    | With `disabled`: it stays focusable as `aria-disabled="true"`, and its clicks, presses, Enter and Space do nothing. |
+
+Every other native prop passes through: `name`, `value`, `form`, `command`, `commandfor`,
+`popovertarget`, `id`, `class`, `aria-*`, `onClick`.
+
+**Differences from Base UI's Button.** It is always a `<button>`: no `nativeButton` or `render`. For
+a link that looks like a button, style an `<a>` with the same class.
+
+## Example
+
+A save button that keeps focus while it saves, in an island:
+
+```tsx check
+import { Button } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function SavingButton() {
+  const saving = signal(false);
+  return (
+    <Button
+      class="lu-button"
+      data-variant="primary"
+      disabled={saving()}
+      focusableWhenDisabled
+      onClick={() => {
+        saving.set(true);
+        setTimeout(() => saving.set(false), 1500);
+      }}
+    >
+      {saving() ? "Saving…" : "Save"}
+    </Button>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-button` on it (`data-variant="primary"` or
+`data-variant="destructive"` for the others): a 36px tall button with a focus ring, faded when
+`:disabled` or `[aria-disabled="true"]`.
+
+**With your own CSS**, style the button and its states: `:hover`, `:focus-visible`, `:disabled`,
+`[aria-disabled="true"]`.
+
+Button ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+| Key           | Does                                                                          |
+| ------------- | ----------------------------------------------------------------------------- |
+| Enter / Space | Presses it, unless it is disabled.                                            |
+| Tab           | Moves on. A disabled button is skipped, unless it is focusable when disabled. |
+
+## Without JavaScript, and the client script
+
+A native button: it works, submits and resets with no script. The client script (0.2 kB brotli)
+only cancels the clicks, Enter and Space of an `aria-disabled` button (one without a `role` of its
+own), and keeps its presses (`pointerdown`, `mousedown`) and Enter and Space keys from its
+handlers and its ancestors' bubbling ones, as Base UI does; listeners that capture still see them,
+and the other keys (Tab, a toolbar's arrows) go on. Without it such a button still acts, so a
+server page that disables a button until something happens should use `disabled` alone.
+
+## Browser support
+
+Native `<button>`: every browser.
+
+## Related
+
+- [Toggle](toggle.md): a button that stays pressed.
+- [Form](form.md): a form whose submit button is a Button.
+- [Dialog](dialog.md): a Button with `command="show-modal"` opens a dialog without JavaScript.