@lumiose/ui 0.0.0-stage → 0.1.0

package/docs/theming.md

@@ -0,0 +1,132 @@
+# Theming
+
+> `@lumiose/ui` is unstyled: its stylesheets hold only what the components need to work. The optional default theme gives them a look, light and dark, through `--lu-` custom properties you can change; or style the parts with your own CSS.
+
+## Cascade layers
+
+The components' stylesheets hold only what a component needs to work (display, positioning and
+anchoring, the top layer, the CSS variables a component sets), in the `lu.core` cascade layer. The
+default theme sits in `lu.theme`, above it:
+
+```ts
+import "@lumiose/ui/styles.css"; // what every component needs (or "@lumiose/ui/dialog.css", …)
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+Both stylesheets declare the layers `lu.core, lu.theme`, in that order. CSS outside layers always
+wins over layered CSS, so your own stylesheets override the package's without specificity games.
+If your app orders its own layers, put `lu` first: `@layer lu, reset, components;`.
+
+## The default theme
+
+`@lumiose/ui/themes/default.css` is a ready look for demos, prototypes and getting started: neutral
+surfaces, a blue primary, light and dark. It styles a few classes, which you put on the parts
+through their `class` prop:
+
+| Class                | On                                             | Variants                                                                                    |
+| -------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `lu-button`          | `Button`, any `<button>` part                  | `data-variant="primary"`, `data-variant="destructive"`                                      |
+| `lu-dialog`          | `Dialog.Popup`                                 | Styles the backdrop, the title, the description and a `<footer>` inside                     |
+| `lu-popover`         | `Popover.Popup`                                | Styles the title, the description and a `<footer>` inside                                   |
+| `lu-tooltip`         | `Tooltip.Popup`                                |                                                                                             |
+| `lu-tabs`            | `Tabs.Root`                                    | Styles the list, the tabs (the selected one underlined) and the panels                      |
+| `lu-menu`            | every `Menu.Popup`                             | Styles the items, their checkbox and radio marks, separators and labels                     |
+| `lu-combobox`        | `Combobox.Root`, `Autocomplete.Root`           | Lays out the field (label, chips, input, buttons) and styles the popup                      |
+| `lu-select`          | `Select.Root`                                  | Makes it a customizable select and styles the control and the picker                        |
+| `lu-field`           | `Field.Root`                                   | Stacks the label, control, description and errors; errors in red                            |
+| `lu-input`           | `Input`, `Field.Control`                       | A text field with a focus ring and a red border when invalid                                |
+| `lu-fieldset`        | `Fieldset.Root`, `CheckboxGroup`, `RadioGroup` | The legend and the items in a column                                                        |
+| `lu-checkbox`        | `Checkbox.Root`                                | An 18px box in a 24px target, a ✓ or a dash                                                 |
+| `lu-radio`           | `Radio.Root`                                   | An 18px circle in a 24px target, a thick ring when checked                                  |
+| `lu-switch`          | `Switch.Root`                                  | A track and a thumb on the side that tells on from off                                      |
+| `lu-collapsible`     | `Collapsible.Root`                             | Styles the trigger (a chevron) and animates the panel's height                              |
+| `lu-accordion`       | `Accordion.Root`                               | Items between borders; styles the triggers and animates the panels                          |
+| `lu-toast-viewport`  | `Toast.Viewport`                               | A column at the window's bottom end                                                         |
+| `lu-toast`           | every `Toast.Root`                             | Styles the title, description and close button; `data-type="error"`                         |
+| `lu-toggle`          | `Toggle`                                       | Pressed: a filled surface and a bar along the bottom                                        |
+| `lu-toggle-group`    | `ToggleGroup`                                  | The toggles in a row, or a column when vertical                                             |
+| `lu-progress`        | `Progress.Root`                                | The label and value above a bar; a sliding segment when indeterminate                       |
+| `lu-meter`           | `Meter.Root`                                   | The label and value above a bar                                                             |
+| `lu-slider`          | `Slider.Root`                                  | The label and value above the track, the indicator and 24px thumbs                          |
+| `lu-number-field`    | `NumberField.Root`                             | The label above one bordered group: the input between its buttons                           |
+| `lu-otp-field`       | `OTPField.Root`                                | A box per character, the caret's box ringed while focused                                   |
+| `lu-preview-card`    | `PreviewCard.Popup`                            | A surface like a popover's, with a fade                                                     |
+| `lu-toolbar`         | `Toolbar.Root`                                 | A bordered row (or column), separators across it, links as tall as buttons                  |
+| `lu-scroll-area`     | `ScrollArea.Root`                              | A bordered box; 10px scrollbars shown on hover, scroll or focus                             |
+| `lu-drawer`          | `Drawer.Popup`                                 | A surface against its edge (a handle on a bottom sheet), title, description, footer; slides |
+| `lu-separator`       | `Separator`                                    | A 1px line in `--lu-border`, horizontal or vertical                                         |
+| `lu-avatar`          | `Avatar.Root`                                  | A 40px circle on a muted surface, the image covering it, the initials centred               |
+| `lu-menubar`         | `Menubar`                                      | A bordered bar of the triggers, the open one filled; `lu-menu` on each popup                |
+| `lu-navigation-menu` | `NavigationMenu.Root`                          | The list in a row, the current page underlined, contents as surfaces that slide in          |
+
+Its colours and radius are custom properties with shadcn/ui's names and a `--lu-` prefix, so a
+shadcn palette carries over:
+
+| Property                                          | Used for                            |
+| ------------------------------------------------- | ----------------------------------- |
+| `--lu-background`, `--lu-foreground`              | Page-level surfaces and text        |
+| `--lu-card`, `--lu-card-foreground`               | Cards                               |
+| `--lu-popover`, `--lu-popover-foreground`         | Dialogs, popovers, menus            |
+| `--lu-primary`, `--lu-primary-foreground`         | Primary actions                     |
+| `--lu-secondary`, `--lu-secondary-foreground`     | Secondary actions                   |
+| `--lu-muted`, `--lu-muted-foreground`             | Subdued surfaces and text           |
+| `--lu-accent`, `--lu-accent-foreground`           | Hover and highlighted items         |
+| `--lu-destructive`, `--lu-destructive-foreground` | Destructive actions                 |
+| `--lu-border`, `--lu-input`, `--lu-ring`          | Borders, field borders, focus rings |
+| `--lu-radius`                                     | Corner radius                       |
+
+The theme sets `color-scheme: light dark` on `:root` and every colour with `light-dark()`, so it
+follows the system. Set `color-scheme: light` (or `dark`) on `:root` or on any element, in CSS,
+inline or from a script, to force one, in development and in production builds alike (Lumiose's
+CSS target keeps `light-dark()` as written; an older `build.cssTarget` would lower it to colours
+that follow the system only). Redefine a property outside layers to change it:
+
+```css
+:root {
+  --lu-primary: #7c3aed;
+  --lu-radius: 0.375rem;
+}
+```
+
+The theme meets WCAG 2.2 AA in light and dark: each `-foreground` colour reaches 4.5:1 on its
+surface, and `--lu-input` (the borders of fields and controls) and `--lu-ring` (the focus ring)
+reach 3:1 on the surfaces they sit on. `--lu-border` is for decoration, such as a dialog's edge:
+it is too light to outline a control. Keep those ratios when you change the colours.
+
+In forced colours (Windows' contrast themes), the browser drops shadows and gradients and paints
+backgrounds in its own palette, which would erase the state a colour shows. The theme draws those
+states again in system colours (`Highlight`, `HighlightText`, `ButtonText`, `Canvas`): a switch's
+thumb and its on state, a pressed toggle, the selected tab's bar, progress and meter values, a
+slider's range, the scroll thumb and the highlighted menu item. A pressed toggle's focus ring,
+outside its `Highlight` fill, is `CanvasText`, the colour every contrast theme pairs with the page
+(Firefox would draw it in the toggle's `HighlightText`). Do the same for the states your own CSS
+draws with a colour, in a `@media (forced-colors: active)` block.
+
+## Your own CSS
+
+Style the parts through:
+
+- **Class props.** Every part takes `class` (and `style`), like the element it renders.
+- **State.** Components expose state the way the platform does, so selectors read it directly:
+  `dialog[open]`, `:modal`, `::backdrop`, `:popover-open`, `[aria-expanded]`, `[aria-checked]`,
+  `[aria-selected]`. Where the platform has no such state, they set Base UI's state attributes:
+  `data-highlighted` on the active option of a list, `data-side` and `data-align` on a placed
+  popup, `data-orientation`, `data-starting-style` and `data-ending-style` while a popup animates,
+  `data-swiping`, `data-indeterminate` and others. Each component's page lists its own.
+- **Custom properties.** The values components measure or place, such as a panel's height, a
+  toast's index in its stack or a popup's offset, are custom properties with the `--lu-` prefix.
+  Base UI names them without a prefix, so its `--collapsible-panel-height` is
+  `--lu-collapsible-panel-height` here and its `--scroll-area-thumb-height` is
+  `--lu-scroll-area-thumb-height`.
+
+Other `data-*` attributes on the rendered HTML, such as the markers scripts use to find a part or
+the settings the server HTML passes to a script, are internal and may change between versions.
+Style those parts through their class props.
+
+Each component's page has an example stylesheet to start from.
+
+## Related
+
+- [UI components](README.md): the approach and the components.
+- [Installation](installation.md): adding the package and importing its stylesheets.
+- [Styles](https://itsjavi.com/lumiose/docs/concepts/styles/): scoped CSS and global stylesheets in Lumiose.

package/docs/toast.md

@@ -0,0 +1,311 @@
+# Toast
+
+> Short notices in a region of their own, after Base UI's toast: server HTML renders them (a form action's result), and islands add, update and close them through a toast manager. `<lu-toast-viewport>`, a 2.6 kB light-DOM element, puts them in the top layer, times them (pausing on hover and focus), limits how many show, closes them on a swipe, Escape or their close button, focuses the region on F6, and makes screen readers announce them.
+
+```ts
+import { Toast } from "@lumiose/ui"; // or "@lumiose/ui/toast"
+import "@lumiose/ui/toast.css"; // the viewport's box, the limit, swipes on touch screens
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Toast.Provider>
+  <Toast.Viewport>
+    <Toast.Root>
+      <Toast.Content>
+        <Toast.Title />
+        <Toast.Description />
+      </Toast.Content>
+      <Toast.Action />
+      <Toast.Close />
+    </Toast.Root>
+  </Toast.Viewport>
+</Toast.Provider>
+```
+
+| Part          | Renders                                                                                                          |
+| ------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `Provider`    | No element. Holds the toasts' defaults (`timeout`, `limit`) and a manager for `Toast.useToastManager()`.         |
+| `Viewport`    | `<lu-toast-viewport role="region" aria-label="Notifications (F6)" tabindex="-1">`, the toasts' region.           |
+| `Root`        | `<div role="status" aria-atomic="true">`, a toast: `role="alert"` for a high-priority one.                       |
+| `Content`     | `<div>`, around the text.                                                                                        |
+| `Title`       | `<h2>`: its children, or else the toast's `title`; nothing without either.                                       |
+| `Description` | `<p>`: its children, or else the toast's `description`; nothing without either.                                  |
+| `Action`      | `<button type="button">` with the toast's `actionProps`; nothing without them or children.                       |
+| `Close`       | `<button type="button" command="--close-toast" commandfor="…">`: a custom invoker command that closes the toast. |
+
+Each toast is a live region of its own, `role="status"` (announced when the reader is idle) or
+`role="alert"` (announced at once), as in Zag; Base UI's are non-modal dialogs. The viewport is
+a named region that F6 reaches.
+
+## API
+
+### Toast.createToastManager
+
+`Toast.createToastManager()` returns a manager. Create one in a module and import it where toasts
+are added and where they are shown: islands of a page share a module, so they share its manager.
+
+| Method                      | Does                                                                                                                                |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `toasts()`                  | The open toasts, newest first, read reactively: map them to `Toast.Root`s.                                                          |
+| `add(options)`              | Adds a toast and returns its id. With the `id` of an open toast, it updates that one in place.                                      |
+| `update(id, options)`       | Changes an open toast in place: the same object, its fields read reactively, so its parts update without a new element.             |
+| `close(id?)`                | Closes a toast, or every toast: it gets `transitionStatus: "ending"` and `data-ending-style`, then leaves after its exit animation. |
+| `promise(promise, options)` | Shows a loading toast while `promise` runs (it stays), then turns it into a success or an error toast; returns `promise`.           |
+
+The options of `add` and `update`:
+
+| Option        | Type                              | Default |                                                                                                                                                                                                                                                                                                    |
+| ------------- | --------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`          | `string`                          | made up | An id of your own, to update or close the toast later.                                                                                                                                                                                                                                             |
+| `title`       | `string`                          |         | Shown by `Toast.Title`.                                                                                                                                                                                                                                                                            |
+| `description` | `string`                          |         | Shown by `Toast.Description`.                                                                                                                                                                                                                                                                      |
+| `type`        | `string`                          |         | A type of your own (`"success"`, `"error"`, `"loading"`): the toast's `data-type`, for styling.                                                                                                                                                                                                    |
+| `timeout`     | `number`                          | `5000`  | Milliseconds before it closes on its own; `0` keeps it until closed. The provider's `timeout` sets the default.                                                                                                                                                                                    |
+| `priority`    | `"low" \| "high"`                 | `"low"` | `"high"` announces it at once (`role="alert"`), for errors that need attention.                                                                                                                                                                                                                    |
+| `actionProps` | `JSX.IntrinsicElements["button"]` |         | The props of its `Toast.Action`: `children` for the label, `onClick`, `class`, `disabled` and `aria-*`. Other keys are dropped, so options passed as they arrived (a notification payload) cannot set the button's `type`, `formaction` or `style`. Write any other prop on `Toast.Action` itself. |
+| `onClose`     | `() => void`                      |         | Called when it starts closing.                                                                                                                                                                                                                                                                     |
+| `onRemove`    | `() => void`                      |         | Called once it is removed, after its exit animation.                                                                                                                                                                                                                                               |
+
+`promise`'s options are `loading`, `success` and `error`: options, a title, or (for `success` and
+`error`) a function of the result. The loading toast has `type: "loading"` and `timeout: 0`; the
+others `type: "success"` or `"error"` and the default timeout.
+
+### Toast.Provider
+
+| Prop           | Type           | Default   |                                                                                                                                      |
+| -------------- | -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `toastManager` | `ToastManager` | a new one | The manager its toasts come from, for `Toast.useToastManager()`.                                                                     |
+| `timeout`      | `number`       | `5000`    | Milliseconds before a toast closes on its own; `0` keeps toasts open.                                                                |
+| `limit`        | `number`       | `3`       | How many toasts show at once; older ones wait, hidden and paused, until a newer one closes. The toast that holds focus always shows. |
+
+`Toast.useToastManager()` returns the closest provider's manager.
+
+### Toast.Root
+
+| Prop             | Type                                      | Default             |                                                                  |
+| ---------------- | ----------------------------------------- | ------------------- | ---------------------------------------------------------------- |
+| `toast`          | `ToastObject \| ToastOptions`             |                     | The toast: one from a manager, or a plain object in server HTML. |
+| `swipeDirection` | `("up" \| "down" \| "left" \| "right")[]` | `["down", "right"]` | The directions a swipe closes it in; `[]` turns swiping off.     |
+
+### The other parts
+
+Each part takes the props of the element it renders (`class`, `style`, `aria-*`, `data-*`, event
+handlers, `ref`) and passes them through. Your props override the defaults (`role`, `aria-label`,
+`type`). A `Root`'s `id` names the toast's element, and its `Close` points at it (see
+[Ids](README.md#ids)); `command` and `commandfor` stay the parts' own, since they connect them.
+
+- **`Viewport`**: rename the region with `aria-label`; keep the hotkey in it.
+- **`Root`**: the script fires a cancelable `close` event on it when a toast should close (a close
+  button, Escape, a swipe, its timer); a managed toast handles it through its manager.
+- **`Close`**: name it, with text or `aria-label`.
+
+## Example
+
+In an island, a button and the toasts it adds, styled by the default theme:
+
+```tsx check
+import { Toast } from "@lumiose/ui";
+
+export function SaveButton() {
+  const toasts = Toast.createToastManager();
+  return (
+    <Toast.Provider toastManager={toasts}>
+      <button
+        type="button"
+        class="lu-button"
+        onClick={() => toasts.add({ title: "Saved", description: "Your changes are live." })}
+      >
+        Save
+      </button>
+      <Toast.Viewport class="lu-toast-viewport">
+        {toasts.toasts().map((toast) => (
+          <Toast.Root class="lu-toast" toast={toast}>
+            <Toast.Title />
+            <Toast.Description />
+            <Toast.Close aria-label="Close">×</Toast.Close>
+          </Toast.Root>
+        ))}
+      </Toast.Viewport>
+    </Toast.Provider>
+  );
+}
+```
+
+A promise toast, and an error that stays (`timeout: 0`) with an action:
+
+```tsx check
+import { Toast } from "@lumiose/ui";
+
+export function UploadButton() {
+  const toasts = Toast.createToastManager();
+  const upload = () =>
+    toasts
+      .promise(new Promise((resolve) => setTimeout(resolve, 1000)), {
+        loading: "Uploading…",
+        success: "Uploaded",
+        error: "Upload failed",
+      })
+      .catch(() => undefined);
+  const fail = () =>
+    toasts.add({
+      title: "Payment failed",
+      description: "Check your card and try again.",
+      type: "error",
+      priority: "high",
+      timeout: 0,
+      actionProps: { children: "Retry", class: "lu-button", onClick: upload },
+    });
+  return (
+    <Toast.Provider toastManager={toasts}>
+      <button type="button" class="lu-button" onClick={upload}>
+        Upload
+      </button>
+      <button type="button" class="lu-button" data-variant="destructive" onClick={fail}>
+        Pay
+      </button>
+      <Toast.Viewport class="lu-toast-viewport">
+        {toasts.toasts().map((toast) => (
+          <Toast.Root class="lu-toast" toast={toast}>
+            <Toast.Title />
+            <Toast.Description />
+            <Toast.Action />
+            <Toast.Close aria-label="Close">×</Toast.Close>
+          </Toast.Root>
+        ))}
+      </Toast.Viewport>
+    </Toast.Provider>
+  );
+}
+```
+
+A form action's result in server HTML, with no island: the page renders the toast, and the
+script times and closes it.
+
+```tsx check
+import { Toast } from "@lumiose/ui";
+
+export function SaveResult(props: { saved: boolean }) {
+  return (
+    <Toast.Viewport class="lu-toast-viewport">
+      {props.saved && (
+        <Toast.Root class="lu-toast" toast={{ title: "Project saved" }}>
+          <Toast.Title />
+          <Toast.Close aria-label="Close">×</Toast.Close>
+        </Toast.Root>
+      )}
+    </Toast.Viewport>
+  );
+}
+```
+
+To add toasts from several islands, create the manager in a module and import it in each: one
+island renders the viewport from it, the others call `toasts.add()`.
+
+```ts
+// src/toasts.ts
+import { Toast } from "@lumiose/ui";
+
+export const toasts = Toast.createToastManager();
+```
+
+## Styling
+
+**With the default theme**, put `lu-toast-viewport` on `Viewport` and `lu-toast` on each `Root`: a
+column at the window's bottom end, popover surfaces with the title, description and a 28px close
+button, a slide in, a fade out, and a swipe that leaves in its direction. `data-type="error"`
+adds a red edge.
+
+**With your own CSS**, style the parts through `class` and the script's state:
+
+- `[data-type]`, from the toast's `type`;
+- `[data-starting-style]` on a new toast's first frame, and `[data-ending-style]` while it closes
+  (the script, or the manager, waits for its animations before removing it);
+- `[data-swiping]`, `[data-swipe-direction]` (`up`, `down`, `left`, `right`) and the
+  `--lu-toast-swipe-movement-x` and `--lu-toast-swipe-movement-y` variables, in pixels, while a swipe
+  runs; `[data-swipe-direction]` stays while a swiped toast leaves;
+- `--lu-toast-index` on each shown toast (0 for the first child), and `[data-limited]` on the ones
+  past the limit;
+- `[data-expanded]` on the viewport while the pointer or keyboard focus is in it.
+
+```css
+.toast {
+  translate: var(--lu-toast-swipe-movement-x, 0) var(--lu-toast-swipe-movement-y, 0);
+  transition:
+    opacity 200ms,
+    translate 200ms;
+}
+.toast:is([data-starting-style], [data-ending-style]) {
+  opacity: 0;
+}
+.toast[data-swiping] {
+  transition: none;
+}
+```
+
+`@lumiose/ui/toast.css`, in the `lu.core` layer, makes the viewport a box fixed to the window's
+bottom end, without a popover's default border, padding or centring; hides the toasts past the
+limit whatever display your CSS gives them; sets `touch-action` on swipeable toasts, so a swipe
+does not scroll the page along its axes, while pinch-zoom still works (where `touch-action` knows
+it: not in Safari); and gives the page `scroll-padding-block-end` the height of the shown toasts
+(`--lu-toast-stack-block-size`, which the script keeps on the root), so a control that takes focus
+is scrolled clear of them (WCAG 2.4.11).
+
+A modal dialog makes everything outside it inert, so while one is open the region moves into it,
+and back when it closes or leaves the page.
+
+## Keyboard and focus
+
+| Key       | Does                                                                 |
+| --------- | -------------------------------------------------------------------- |
+| F6        | Focuses the toasts' region, when a toast shows.                      |
+| Tab       | Moves through the toasts' buttons.                                   |
+| Escape    | In a toast: closes it. On the region: returns focus to where it was. |
+| Shift+Tab | On the region: returns focus to where it was.                        |
+
+- **When the focused toast closes**, focus moves to the next toast's first button, or back to
+  where it was before it entered the region (F6, Tab or a click).
+- **Timers pause** while the pointer is over the region, while keyboard focus is in it, while the
+  window is in the background and while the page is hidden; they resume with the time that was
+  left. A press that focuses a toast pauses it only while the pointer stays, as in Base UI.
+- **A swipe** closes the toast past 40px, unless it is pulled back 10px or more from its farthest
+  point before the release.
+- **Swipes** have a single-pointer alternative, the close button, and a keyboard one, Escape
+  (WCAG 2.5.1 and 2.5.7). A swipe never starts on a button, link or field.
+- **Time limits** (WCAG 2.2.1): a toast that times out must hold nothing the reader needs to act
+  on. Give a toast with an action, or with something to read twice, `timeout: 0`.
+- **Over a modal dialog**: a modal dialog makes everything outside it inert, so while one is open
+  the region moves into it, and back when it closes. Toasts stay usable and announced.
+- **Persistent**: a press in a toast does not close an open menu, popover or combobox.
+
+## Without JavaScript, and the element's script
+
+What is server-rendered and what needs the client:
+
+| Server HTML                                                                   | The element's script (2.6 kB, loaded once per page)                                                      |
+| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| The region and the toasts a page renders, with their text, roles and buttons. | The top layer (a manual popover), so toasts sit above dialogs and survive other popovers' light dismiss. |
+| Toasts show at the window's bottom end (`toast.css`).                         | Timers, pausing, the limit, closing (button, Escape, swipe), F6, focus when a toast goes.                |
+|                                                                               | The announcement mutation, and following modal dialogs.                                                  |
+
+Without JavaScript a server-rendered toast stays on the page until the next one, and its close
+button does nothing. The manager needs an island.
+
+**Announcements.** Each toast is a live region, so screen readers read it without moving focus
+(WCAG 4.1.3). Safari's VoiceOver misses the text of a region inserted with it, so 250ms after a
+toast appears the script adds an invisible word joiner to it, a change VoiceOver reads, as Base UI
+does. A toast in the page's HTML is announced the same way once the script runs.
+
+## Browser support
+
+- **Popover**: every current browser. Without it, toasts stay out of the top layer.
+- **Invoker commands** (`Toast.Close`): Chrome 135, Firefox 144, Safari 26.2; elsewhere the
+  script handles the close button's click.
+
+## Related
+
+- [UI components](README.md): the approach, styling and the other components.
+- [Dialog](dialog.md): a modal popup, which the toasts' region follows.
+- [Data and actions](https://itsjavi.com/lumiose/docs/concepts/data-and-actions/): a form action's result, for a server-rendered toast.

package/docs/toggle-group.md

@@ -0,0 +1,119 @@
+# Toggle Group
+
+> A set of [Toggles](toggle.md) with one value, after Base UI's ToggleGroup: text alignment (one pressed at a time) or text style (several). `<lu-toggle-group role="group">` presses its toggles and gives the group one tab stop that the arrow keys, Home and End move, following the orientation and the direction, on server pages and in islands. `bind:value` keeps a signal in sync.
+
+```ts
+import { Toggle, ToggleGroup } from "@lumiose/ui"; // or "@lumiose/ui/toggle-group"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<ToggleGroup aria-label="Alignment">
+  <Toggle value="left">Left</Toggle>
+  <Toggle value="center">Center</Toggle>
+</ToggleGroup>
+```
+
+| Part          | Renders                                                                |
+| ------------- | ---------------------------------------------------------------------- |
+| `ToggleGroup` | `<lu-toggle-group role="group" data-orientation>`; `multiple` if set   |
+| `Toggle`      | `<button aria-pressed value>`; the group's tab stop has `tabindex="0"` |
+
+## API
+
+### ToggleGroup
+
+| Prop            | Type                           | Default        |                                                                            |
+| --------------- | ------------------------------ | -------------- | -------------------------------------------------------------------------- |
+| `value`         | `string[]`                     |                | Presses these toggles when it changes. Pair it with `onValueChange`.       |
+| `defaultValue`  | `string[]`                     | `[]`           | The toggles pressed at first.                                              |
+| `onValueChange` | `(value: string[]) => void`    |                | Called after the user presses or releases a toggle.                        |
+| `bind:value`    | `Signal<string[]>`             |                | Stands in for `value` and `onValueChange`.                                 |
+| `multiple`      | `boolean`                      | `false`        | Several toggles can be pressed; otherwise pressing one releases the other. |
+| `orientation`   | `"horizontal"` \| `"vertical"` | `"horizontal"` | Which arrow keys move focus.                                               |
+| `loopFocus`     | `boolean`                      | `true`         | The arrow keys go from the last toggle to the first, and back.             |
+| `disabled`      | `boolean`                      | `false`        | Disables every toggle.                                                     |
+
+Every other prop passes through to `<lu-toggle-group>`: `aria-label`, `aria-labelledby`, `id`,
+`class`. Name the group with one of the first two.
+
+Each toggle's `value` is its identity in the group; its `onPressedChange` still fires. A
+`pressedchange` event (`detail.pressed`) bubbles from a toggle before it changes, and
+`event.preventDefault()` cancels the change.
+
+**Differences from Base UI's ToggleGroup.** No `render`. Focus follows `tabindex` on the toggles
+(roving), as Base UI does; disabled toggles are natively `disabled`, so focus skips them.
+
+## Example
+
+```tsx check
+import { Toggle, ToggleGroup } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function TextAlignment() {
+  const align = signal<string[]>(["left"]);
+  return (
+    <p>
+      <ToggleGroup aria-label="Text alignment" bind:value={align} class="lu-toggle-group">
+        <Toggle value="left" class="lu-toggle">
+          Left
+        </Toggle>
+        <Toggle value="center" class="lu-toggle">
+          Center
+        </Toggle>
+        <Toggle value="right" class="lu-toggle">
+          Right
+        </Toggle>
+      </ToggleGroup>{" "}
+      Aligned: {align()[0] ?? "none"}.
+    </p>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-toggle-group` on the group and `lu-toggle` on each toggle: the
+toggles in a row with a small gap, in a column when `data-orientation="vertical"`.
+
+**With your own CSS**, style the group by `[data-orientation]` and `[multiple]`, and the toggles by
+`[aria-pressed="true"]`, `:focus-visible` and `:disabled`.
+
+Toggle Group ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+| Key                      | Does                                                                                                           |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| Tab                      | Enters the group on the last focused toggle (at first, the first pressed or the first enabled), and leaves it. |
+| Arrow Right / Arrow Left | Horizontal: the next or previous toggle (swapped right to left), looping.                                      |
+| Arrow Down / Arrow Up    | Vertical: the next or previous toggle, looping.                                                                |
+| Home / End               | The first or last enabled toggle.                                                                              |
+| Enter / Space            | Presses or releases the focused toggle.                                                                        |
+
+Arrows move focus without pressing, and skip disabled toggles. With `loopFocus={false}` they stop at
+the ends.
+
+Inside a [Toolbar](toolbar.md), the group still presses its toggles, but the toolbar's arrow keys
+and single tab stop take over: the toggles are toolbar items.
+
+## Without JavaScript, and the element's script
+
+The server HTML has each toggle's `aria-pressed` and the tab stop. `<lu-toggle-group>`'s script
+(0.9 kB brotli) presses the toggles and moves focus, on server pages and in islands; when the tab
+stop's toggle goes or is disabled, or a disabled group is enabled, the first pressed (else enabled)
+toggle takes the tab stop. With no script
+at all the toggles show their state but do not change. For values a form submits, use a
+[Checkbox Group](checkbox-group.md) or a [Radio](radio-group.md) group.
+
+## Browser support
+
+Custom elements and `aria-pressed`: every supported browser.
+
+## Related
+
+- [Toggle](toggle.md): one toggle, on its own or in a group.
+- [Radio](radio-group.md): one choice submitted with a form.
+- [Tabs](tabs.md): toggles that switch panels.