@lumiose/ui 0.0.0-stage → 0.1.0

package/docs/separator.md

@@ -0,0 +1,116 @@
+# Separator
+
+> A native `<hr>` between groups of content, after Base UI's Separator: announced as a separator, horizontal by default, or vertical between the items of a row with `aria-orientation="vertical"`. No script.
+
+```ts
+import { Separator } from "@lumiose/ui"; // or "@lumiose/ui/separator"
+import "@lumiose/ui/separator.css"; // a vertical separator's margins and height in a row
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Separator />
+```
+
+| Part        | Renders                                                                              |
+| ----------- | ------------------------------------------------------------------------------------ |
+| `Separator` | `<hr data-orientation="…">`, with `aria-orientation="vertical"` when it is vertical. |
+
+An `<hr>` is a separator for assistive technology with no role to add. It is flow content: it
+cannot go inside a `<p>`, a `<span>` or a `<button>`, where the browser would move it out of the
+element.
+
+## API
+
+### Separator
+
+| Prop          | Type                         | Default        |                                                                           |
+| ------------- | ---------------------------- | -------------- | ------------------------------------------------------------------------- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Which way it runs: `"vertical"` between the items of a row (a toolbar's). |
+
+Every other native prop passes through: `class`, `style`, `id`, `aria-*`, `data-*`.
+
+**Differences from Base UI's Separator.** It is always an `<hr>`, not a `<div role="separator">`:
+no `render`. A horizontal one leaves out `aria-orientation="horizontal"`, an `<hr>`'s default.
+
+## Example
+
+Links in a row, split into groups, styled by the default theme:
+
+```tsx check
+import { Separator } from "@lumiose/ui";
+
+export function FooterLinks() {
+  return (
+    <nav aria-label="Footer" style={{ display: "flex", gap: "0.75rem", "align-items": "center" }}>
+      <a href="#docs">Docs</a>
+      <a href="#blog">Blog</a>
+      <Separator orientation="vertical" class="lu-separator" />
+      <a href="#privacy">Privacy</a>
+      <a href="#terms">Terms</a>
+    </nav>
+  );
+}
+```
+
+Between sections of a page or a card, a horizontal one:
+
+```tsx check
+import { Separator } from "@lumiose/ui";
+
+export function AccountCard() {
+  return (
+    <section aria-label="Account">
+      <p>Signed in as ada@example.com</p>
+      <Separator class="lu-separator" />
+      <p>Plan: Free</p>
+    </section>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-separator` on it: a 1px line in `--lu-border`, with a margin
+above and below when horizontal, and as tall as its row when vertical.
+
+**With your own CSS**, style it through `class` and `[data-orientation]`. Reset the borders an
+`<hr>` has by default, and draw the line with a background:
+
+```css
+.separator {
+  border: 0;
+  background: #e4e4e7;
+}
+.separator[data-orientation="horizontal"] {
+  block-size: 1px;
+  margin: 1rem 0;
+}
+.separator[data-orientation="vertical"] {
+  inline-size: 1px;
+}
+```
+
+`@lumiose/ui/separator.css`, in the `lu.core` layer, gives a vertical separator no margins (an
+`<hr>`'s automatic ones would push the row's items apart) and the full height of its row, even one
+that centres its items (`align-self: stretch`).
+
+## Keyboard and focus
+
+A separator takes no focus and has no keys: it only structures the content around it.
+
+## Without JavaScript, and the client script
+
+A native `<hr>` with attributes: it needs no script, on the server or in an island.
+
+## Browser support
+
+Native `<hr>` and `aria-orientation`: every browser.
+
+## Related
+
+- [Menu](menu.md): `Menu.Separator` between a menu's items.
+- [Select](select.md): separators between a select's options.
+- [UI components](README.md): the approach, styling and the other components.

package/docs/slider.md

@@ -0,0 +1,184 @@
+# Slider
+
+> A value picked within a range by dragging or with the keys, or a range with two thumbs, after Base UI's Slider. Each thumb is a native `<input type="range">`, so it drags, takes the arrow keys, Home and End, follows the text direction and submits with its form, in server HTML and without JavaScript. `<lu-slider>` adds Page Up and Page Down, keeps a range's thumbs in order, moves the nearest thumb on a press on the track and keeps the value text current. `bind:value` keeps a signal in sync.
+
+```ts
+import { Slider } from "@lumiose/ui"; // or "@lumiose/ui/slider"
+import "@lumiose/ui/slider.css"; // or "@lumiose/ui/styles.css" for every component
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Slider.Root>
+  <Slider.Label />
+  <Slider.Value />
+  <Slider.Control>
+    <Slider.Track>
+      <Slider.Indicator />
+    </Slider.Track>
+    <Slider.Thumb />
+  </Slider.Control>
+</Slider.Root>
+```
+
+| Part        | Renders                                                                                                                           |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `Root`      | `<lu-slider data-orientation data-thumb-alignment>` with `--lu-slider-start` and `--lu-slider-end`                                |
+| `Label`     | `<label for>` the first thumb; thumbs without an `aria-label` are labelled by it                                                  |
+| `Value`     | `<output for>` the thumbs, with the formatted values (`20 – 80`)                                                                  |
+| `Control`   | `<div>`: the track and the thumbs stacked in one place; presses on it move a thumb. A range's is a `role="group"` the Label names |
+| `Track`     | `<div>`: the rail                                                                                                                 |
+| `Indicator` | `<div>`: the selected part, from `--lu-slider-start` to `--lu-slider-end`                                                         |
+| `Thumb`     | `<input type="range" min max step value name>`, one per value, in order                                                           |
+
+## API
+
+### Slider.Root
+
+| Prop                     | Type                             | Default        |                                                                                                                                                                 |
+| ------------------------ | -------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`                  | `number \| number[]`             |                | Moves the thumbs when it changes (an array: one value per thumb). Pair it with `onValueChange`.                                                                 |
+| `defaultValue`           | `number \| number[]`             | `min`          | The value at first; a form reset goes back to it.                                                                                                               |
+| `onValueChange`          | `(value) => void`                |                | Called with the new value as a thumb moves.                                                                                                                     |
+| `onValueCommitted`       | `(value) => void`                |                | Called when a move ends: a release, a key press.                                                                                                                |
+| `bind:value`             | `Signal<number \| number[]>`     |                | Stands in for `value` and `onValueChange`.                                                                                                                      |
+| `min`                    | `number`                         | `0`            | The smallest value.                                                                                                                                             |
+| `max`                    | `number`                         | `100`          | The largest value.                                                                                                                                              |
+| `step`                   | `number`                         | `1`            | The step of the arrow keys; values snap to it.                                                                                                                  |
+| `largeStep`              | `number`                         | `10`           | The step of Page Up, Page Down and Shift with an arrow key.                                                                                                     |
+| `minStepsBetweenValues`  | `number`                         | `0`            | With several thumbs: how many steps apart they stay.                                                                                                            |
+| `thumbCollisionBehavior` | `"push"` \| `"swap"` \| `"none"` | `"push"`       | With several thumbs: a thumb moved into another pushes it along, swaps places with it (a drag), or stops at it.                                                 |
+| `thumbAlignment`         | `"edge"` \| `"center"`           | `"edge"`       | The thumbs stop inside the control at its ends, or with their centre on its ends (overhanging it).                                                              |
+| `orientation`            | `"horizontal"` \| `"vertical"`   | `"horizontal"` | Vertical sliders run bottom to top.                                                                                                                             |
+| `disabled`               | `boolean`                        | `false`        | Disables every thumb.                                                                                                                                           |
+| `name`                   | `string`                         |                | The thumbs submit their values under it, one entry each.                                                                                                        |
+| `form`                   | `string`                         |                | The id of a form the thumbs belong to, when they are outside it.                                                                                                |
+| `format`                 | `Intl.NumberFormatOptions`       | plain numbers  | How the values are written; with it, each thumb's `aria-valuetext` is its formatted value. Options or a `locale` the browser refuses fall back to its defaults. |
+| `locale`                 | `string`                         | the browser's  | The locale of the formatted values (the server's in server HTML).                                                                                               |
+
+The value's type follows `value`, `defaultValue` or `bind:value`: a number for one thumb, a
+`number[]` for a range. Every other prop passes through to `<lu-slider>`: `id`, `class`, `style`.
+
+### The other parts
+
+`Label` takes `<label>` props, its `id` among them, which the `Control` and the thumbs point at. `Value` takes `<output>` props, and its `children` may be a function
+`(formattedValues, values) => JSX.Element` (then it has no `for`, and you render its text). `Control`,
+`Track` and `Indicator` take `<div>` props. `Thumb` takes `<input>` props except the range's own
+(`aria-label`, `aria-valuetext`, `disabled`, `class`). A thumb keeps its own `id`, which the
+`Label` and the `Value` before it point at (in a Field, the first thumb's is the field's control;
+see [Ids](README.md#ids)). Give each thumb of a range an
+`aria-label` with the label's text in it ("Minimum price" under "Price"), so speech users can say
+what they see (WCAG 2.5.3); the Label names the range's group (`Control`), so screen readers
+announce "Price, group" before the thumbs. Inside a Field, the first thumb takes the field's id,
+name, description and error.
+
+- **`thumbCollisionBehavior="swap"`.** A thumb dragged past another (with the pointer, or a press
+  on the track) trades places with it: the values stay in order, the other thumb takes the
+  dragged value and focus, and the drag goes on with it. A native drag keeps its own thumb, so
+  that thumb stays put and hands its value on. The keys stop at the other thumb, as with
+  `"none"`, and `minStepsBetweenValues` applies to keys only.
+- **Blocked moves.** A move that changes no value, such as a thumb pushed against its neighbour
+  with `"none"`, fires no `input` or `change`, so `onValueChange` and `onValueCommitted` do not
+  run.
+- **`thumbAlignment` and `--lu-slider-thumb-size`.** A native thumb stays inside its input. With
+  the thumbs' size in `--lu-slider-thumb-size` (the default theme sets it), slider.css runs the
+  track between the thumbs' centres at the ends, so the Indicator ends at a thumb's centre
+  whatever the value (`"edge"`); with `"center"` the inputs outgrow the control by half a thumb
+  at each end, so the thumbs' centres reach its ends and the track spans it. Without the
+  variable, the Indicator can end up to half a thumb from its centre.
+
+**Differences from Base UI's Slider.** Thumbs are the range inputs themselves, so there is no hidden
+input, no `inputRef` and no `getAriaLabel` (use `aria-label` on each Thumb). `thumbAlignment`
+defaults to `"edge"` (Base UI's to `"center"`), and has no `"edge-client-only"`: the server HTML
+is already right. `format` is `Intl.NumberFormatOptions` and `locale` a string, both written to
+the element for its script.
+
+## Example
+
+A price range, in an island:
+
+```tsx check
+import { Slider } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function PriceRange() {
+  const price = signal([20, 80]);
+  return (
+    <Slider.Root
+      name="price"
+      bind:value={price}
+      minStepsBetweenValues={5}
+      format={{ style: "currency", currency: "EUR", maximumFractionDigits: 0 }}
+      class="lu-slider"
+    >
+      <Slider.Label>Price</Slider.Label>
+      <Slider.Value />
+      <Slider.Control>
+        <Slider.Track>
+          <Slider.Indicator />
+        </Slider.Track>
+        <Slider.Thumb aria-label="Minimum price" />
+        <Slider.Thumb aria-label="Maximum price" />
+      </Slider.Control>
+    </Slider.Root>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-slider` on `Root`: the label and the value on a row above a 24px
+tall control, an 8px track edged in `--lu-input` (3:1), the selected part in the primary colour,
+and 24px round thumbs (`--lu-slider-thumb-size`) with a focus ring around the thumb. Vertical
+sliders are 10rem tall. A center-aligned control is inset by half a thumb, so its thumbs overhang
+it inside the slider's box.
+
+**With your own CSS**, style the parts through `class`, the thumbs' pseudo-elements
+(`::-webkit-slider-thumb`, `::-moz-range-thumb`), `[data-orientation="vertical"]`, `:disabled`,
+`:focus-visible`, and the Indicator through `--lu-slider-start` and `--lu-slider-end`. Over a Track,
+the thumbs' own tracks are transparent (`appearance: none`). Set `--lu-slider-thumb-size` to your
+thumbs' size on the Root, so the track lines up with their centres.
+
+`@lumiose/ui/slider.css` (0.4 kB brotli) stacks the track and thumbs, spans the thumbs over the
+control and the Indicator over the selected part, lines the track up with the thumbs' centres
+(`--lu-slider-thumb-size`, `data-thumb-alignment`), writes vertical thumbs bottom to top and lets
+only the thumbs of a range take the pointer.
+
+## Keyboard and focus
+
+| Key                     | Does                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------- |
+| Tab                     | Moves between the thumbs, then on: one tab stop per thumb.                                     |
+| Arrow Right / Arrow Up  | One step up (Arrow Left goes up right to left).                                                |
+| Arrow Left / Arrow Down | One step down (Arrow Right goes down right to left).                                           |
+| Page Up / Page Down     | `largeStep` up or down.                                                                        |
+| Shift + an arrow        | `largeStep` in that direction.                                                                 |
+| Home / End              | The minimum or the maximum; in a range, at most the neighbouring thumb, which they never push. |
+
+Every drag has these keys as its alternative (WCAG 2.5.7). A press on a range's track moves the
+nearest thumb there and focuses it; a press on a single slider's track moves its thumb.
+
+## Without JavaScript, and the element's script
+
+The thumbs are native range inputs: dragging, the arrows, Home, End, right to left, vertical,
+submission, `disabled` and reset work with no script, and the server HTML has the Indicator's
+custom properties and the value text. `<lu-slider>`'s script (2.0 kB brotli) adds Page Up and Page
+Down, runs the arrow keys the same in every browser (WebKit's native range does not mirror them
+right to left), stops Home and End at a range's neighbouring thumb, keeps a range's thumbs in order and apart (or swaps them), moves the nearest thumb
+on a press on its track, and keeps the Indicator, `aria-valuetext` and the Value text current (also
+after a form reset).
+Without it, a range's thumbs can cross, and the Value text and the Indicator stay where the server
+put them.
+
+## Browser support
+
+Native range inputs: every browser. Vertical sliders use `writing-mode: vertical-lr` on the thumbs
+(Chrome 124, Safari 17.4, Firefox 120 and later).
+
+## Related
+
+- [Field](field.md): a label, description and error for a slider.
+- [Meter](meter.md): show a value in a range, without picking it.
+- [Input](input.md): `type="number"` for an exact value.

package/docs/switch.md

@@ -0,0 +1,98 @@
+# Switch
+
+> On or off, for a setting: a native `<input type="checkbox" role="switch">`, after Base UI's Switch. Space and a label click toggle it, the form submits its value when on, `required` and reset work, in server HTML and without JavaScript, and assistive technology announces a switch. `bind:checked` keeps a signal in sync.
+
+```ts
+import { Switch } from "@lumiose/ui"; // or "@lumiose/ui/switch"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<label>
+  <Switch.Root /> Label
+</label>
+```
+
+| Part   | Renders                                                                |
+| ------ | ---------------------------------------------------------------------- |
+| `Root` | `<input type="checkbox" role="switch">`; `aria-readonly` if read-only. |
+
+## API
+
+### Switch.Root
+
+| Prop              | Type                         | Default |                                                                                     |
+| ----------------- | ---------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `checked`         | `boolean`                    |         | Turns it on or off when it changes. Pair it with `onCheckedChange`.                 |
+| `defaultChecked`  | `boolean`                    | `false` | Whether it starts on; a form reset goes back to it.                                 |
+| `onCheckedChange` | `(checked: boolean) => void` |         | Called after the user turns it on or off.                                           |
+| `bind:checked`    | `Signal<boolean>`            |         | Stands in for `checked` and `onCheckedChange`.                                      |
+| `value`           | `string`                     | `"on"`  | What it submits when on.                                                            |
+| `readOnly`        | `boolean`                    | `false` | It cannot be toggled, but stays focusable and is submitted.                         |
+| `uncheckedValue`  | `string`                     |         | What it submits when off (by the script); by default an off switch submits nothing. |
+
+Every other native prop passes through: `name`, `required`, `disabled`, `form`, `id`, `class`,
+`aria-*`. Inside a Field it takes the field's wiring.
+
+**Differences from Base UI's Switch.** The switch is the native input, so there is no
+`Switch.Thumb`: draw the track and thumb with `appearance: none` and `::before`. No `nativeButton` or
+`inputRef`; `uncheckedValue` needs the client script (without it an off switch submits nothing). `<input switch>` exists only in
+Safari, so `role="switch"` stays on a checkbox everywhere.
+
+## Example
+
+In an island, bound to a signal:
+
+```tsx check
+import { Switch } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function AirplaneMode() {
+  const on = signal(false);
+  return (
+    <p>
+      <label>
+        <Switch.Root name="airplane" bind:checked={on} class="lu-switch" /> Airplane mode
+      </label>{" "}
+      {on() ? "Radios off." : ""}
+    </p>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-switch` on `Root`: a 40 by 24px track (`--lu-input` when off,
+the primary colour when on) and a white thumb on the side that tells on from off, a focus ring.
+
+**With your own CSS**, style the input and its state: `:checked`, `:disabled`, `:focus-visible`,
+`[aria-readonly="true"]`, `[aria-invalid="true"]`.
+
+Switch ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+| Key   | Does                                     |
+| ----- | ---------------------------------------- |
+| Space | Turns it on or off (not when read-only). |
+| Tab   | Moves on: one tab stop.                  |
+
+Enter does not toggle it. A click on its label does.
+
+## Without JavaScript, and the client script
+
+A native checkbox with the switch role: toggling, submission, `required`, reset and `disabled`
+work with no script. The shared checkbox script (1.0 kB brotli,
+[Checkbox](checkbox.md#without-javascript-and-the-client-script)) adds read-only and
+`uncheckedValue`.
+
+## Browser support
+
+`role="switch"` on a checkbox: every supported browser and screen reader.
+
+## Related
+
+- [Checkbox](checkbox.md): a choice to confirm, submitted with a form.
+- [Field](field.md): a description and errors for a switch.

package/docs/tabs.md

@@ -0,0 +1,254 @@
+# Tabs
+
+> A tab list and the panel of the selected tab, after the WAI-ARIA tabs pattern: the server HTML holds the whole state (roles, `aria-selected`, the roving tab stop, the hidden panels), and `<lu-tabs>`, a 1.2 kB light-DOM element, adds the arrow keys and the selection. Manual or automatic activation, horizontal or vertical, right-to-left aware, with an optional indicator that slides to the selected tab; `bind:value` (or `value` and `onValueChange`) keeps a signal in sync.
+
+```ts
+import { Tabs } from "@lumiose/ui"; // or "@lumiose/ui/tabs"
+import "@lumiose/ui/tabs.css"; // makes <lu-tabs> a block and places the indicator
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Tabs.Root>
+  <Tabs.List>
+    <Tabs.Tab />
+    <Tabs.Indicator />
+  </Tabs.List>
+  <Tabs.Panel />
+</Tabs.Root>
+```
+
+| Part        | Renders                                                                                                                   |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `Root`      | `<lu-tabs>`, the element that handles the keys and the selection.                                                         |
+| `List`      | `<div role="tablist">`, with `aria-orientation="vertical"` when vertical. Name it with `aria-label` or `aria-labelledby`. |
+| `Tab`       | `<button type="button" role="tab" value="…" aria-selected="…" aria-controls="…" tabindex="…">`.                           |
+| `Indicator` | `<span aria-hidden="true" data-indicator>`, over the selected tab's box and behind its text. Optional.                    |
+| `Panel`     | `<div role="tabpanel" tabindex="0" aria-labelledby="…">`, `hidden` unless its tab is selected.                            |
+
+A `Tab` and a `Panel` with the same `value` belong together. Every panel stays in the page, hidden
+when its tab is not selected, so the browser can switch them before any script loads. Panels go
+inside their `Tabs.Root`: `<lu-tabs>` shows and hides only its own panels, whatever ids its tabs
+name.
+
+## API
+
+### Tabs.Root
+
+| Prop            | Type                         | Default               |                                                  |
+| --------------- | ---------------------------- | --------------------- | ------------------------------------------------ |
+| `value`         | `string`                     |                       | Selects the tab with this value when it changes. |
+| `defaultValue`  | `string`                     | the first enabled tab | The tab selected at first, without `value`.      |
+| `onValueChange` | `(value: string) => void`    |                       | Called after the user selects another tab.       |
+| `bind:value`    | `Signal<string>`             |                       | Stands in for `value` and `onValueChange`.       |
+| `orientation`   | `"horizontal" \| "vertical"` | `"horizontal"`        | Which arrow keys move between the tabs.          |
+
+`Root` also takes the props of an element (`class`, `style`, `data-*`, events) and passes them to
+`<lu-tabs>`.
+
+### Tabs.List
+
+| Prop              | Type      | Default |                                                                                            |
+| ----------------- | --------- | ------- | ------------------------------------------------------------------------------------------ |
+| `activateOnFocus` | `boolean` | `false` | Selects a tab as soon as it receives focus (automatic activation), as Zag does by default. |
+| `loopFocus`       | `boolean` | `true`  | The arrow keys go from the last tab to the first and back.                                 |
+
+The element reads them from the list's attributes: `data-activate-on-focus` and
+`data-loop-focus="false"`.
+
+### Tabs.Tab and Tabs.Panel
+
+| Prop       | On    | Type      |                                                               |
+| ---------- | ----- | --------- | ------------------------------------------------------------- |
+| `value`    | both  | `string`  | Pairs a tab with its panel. Required.                         |
+| `disabled` | `Tab` | `boolean` | The tab takes focus but cannot be selected (`aria-disabled`). |
+
+Each takes the props of the element it renders. A `Tab`'s `id` names it, and its `Panel` points at
+it; a `Panel` keeps its own `id`, which its tab points at (see [Ids](README.md#ids)). `role`,
+`value`, `aria-selected`, `aria-controls`, `aria-labelledby`, `tabindex` on tabs and `hidden` stay
+the parts' own.
+
+- **Disabled tabs.** A selected tab that becomes disabled gives its selection to the first enabled
+  tab. With every tab disabled, none is selected and the first tab is the tab stop. There is one
+  tab stop: in the server HTML, the tab `value` or `defaultValue` names (a disabled one keeps it
+  until the script selects another), else the first enabled tab; once the script runs, the
+  selected tab.
+- **The element.** `<lu-tabs>`' `value` property reads and sets the selection, and it fires
+  `valuechange` (not bubbling) when the user changes it, so `bind:value` works on the element too.
+
+### Tabs.Indicator
+
+Takes the props of a `<span>`, without children. Put it inside `Tabs.List`, after the tabs. It is
+`hidden` while no tab can be selected.
+
+- **Placed before any script.** CSS anchor positioning puts it over the selected tab from the
+  server HTML on (the selected tab carries the anchor `Root` names in `--lu-tabs-anchor`), so it
+  is in place at the first paint and nothing shifts when the script loads (doc-9 §8).
+- **Then measured.** Once `<lu-tabs>`' script runs, it writes the selected tab's box, from the
+  list's padding edge, on the Root as `--lu-tabs-indicator-left`, `--lu-tabs-indicator-top`,
+  `--lu-tabs-indicator-width` and `--lu-tabs-indicator-height`, and keeps them current as the
+  selection changes (a click, the keys, an island), as the list or a tab resizes, and as a `dir`
+  attribute changes in the page. The indicator reads them over its anchor, so a `transition` can
+  slide it from tab to tab, and they place it in browsers without anchor positioning.
+- **Behind the text.** The list isolates its stacking (`isolation: isolate`) and the indicator
+  sits at `z-index: -1`, so a highlight never covers a tab's text.
+
+**Differences from Base UI's Tabs.Indicator.** The variables are on the Root, with these names,
+instead of Base UI's `--active-tab-*` on the indicator, and there is no `renderBeforeHydration`:
+anchor positioning places it from the server HTML. No `data-activation-direction`.
+
+## Example
+
+```tsx check
+import { Tabs } from "@lumiose/ui";
+
+export function AccountSettings() {
+  return (
+    <Tabs.Root class="lu-tabs" defaultValue="account">
+      <Tabs.List aria-label="Account settings">
+        <Tabs.Tab value="account">Account</Tabs.Tab>
+        <Tabs.Tab value="password">Password</Tabs.Tab>
+        <Tabs.Tab value="billing" disabled>
+          Billing
+        </Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="account">Your name and email.</Tabs.Panel>
+      <Tabs.Panel value="password">Change your password.</Tabs.Panel>
+      <Tabs.Panel value="billing">Invoices and payment methods.</Tabs.Panel>
+    </Tabs.Root>
+  );
+}
+```
+
+In an island, bound to a signal: `bind:value={tab}` is short for `value={tab()}` plus
+`onValueChange={(next) => tab.set(next)}`.
+
+```tsx check
+import { Tabs } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function Project() {
+  const tab = signal("overview");
+  return (
+    <>
+      <Tabs.Root class="lu-tabs" bind:value={tab}>
+        <Tabs.List aria-label="Project" activateOnFocus>
+          <Tabs.Tab value="overview">Overview</Tabs.Tab>
+          <Tabs.Tab value="settings">Settings</Tabs.Tab>
+        </Tabs.List>
+        <Tabs.Panel value="overview">The project at a glance.</Tabs.Panel>
+        <Tabs.Panel value="settings">Name and members.</Tabs.Panel>
+      </Tabs.Root>
+      <button type="button" onClick={() => tab.set("settings")}>
+        Open the settings
+      </button>
+    </>
+  );
+}
+```
+
+With an indicator that slides to the selected tab:
+
+```tsx check
+import { Tabs } from "@lumiose/ui";
+
+export function Release() {
+  return (
+    <Tabs.Root class="lu-tabs" defaultValue="notes">
+      <Tabs.List aria-label="Release">
+        <Tabs.Tab value="notes">Notes</Tabs.Tab>
+        <Tabs.Tab value="changelog">Full changelog</Tabs.Tab>
+        <Tabs.Indicator />
+      </Tabs.List>
+      <Tabs.Panel value="notes">The highlights.</Tabs.Panel>
+      <Tabs.Panel value="changelog">Every change.</Tabs.Panel>
+    </Tabs.Root>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-tabs` on `Root`: tabs in a row (or a column when vertical)
+over a rule, the selected one underlined (beside it when vertical) in the foreground colour,
+disabled ones faded, and focus rings on tabs and panels. The list wraps on narrow screens. With a
+`Tabs.Indicator`, the indicator draws that bar and slides to the next tab in 0.2s (at once where
+motion is reduced).
+
+**With your own CSS**, style the parts through `class` and their state: `[role="tab"]`,
+`[aria-selected="true"]`, `[aria-disabled="true"]`, `[role="tablist"][aria-orientation="vertical"]`
+and `[role="tabpanel"]`. Mark the selected tab with more than a colour (WCAG 1.4.1), such as a bar
+or a weight, at 3:1 against its background (WCAG 1.4.11).
+
+```css
+.tabs [role="tab"] {
+  padding: 0.5rem 1rem;
+  border: 0;
+  background: none;
+  color: #52525b;
+}
+.tabs [role="tab"][aria-selected="true"] {
+  color: #09090b;
+  box-shadow: inset 0 -2px currentColor;
+}
+```
+
+A highlight behind the selected tab, with `Tabs.Indicator`:
+
+```css
+.tabs [data-indicator] {
+  border-radius: 6px;
+  background: #f4f4f5;
+  transition:
+    left 0.2s,
+    width 0.2s;
+}
+```
+
+`@lumiose/ui/tabs.css` (0.3 kB brotli), in the `lu.core` layer, makes `<lu-tabs>` a block and
+places the indicator: over the selected tab, behind the tabs' text, from `--lu-tabs-anchor` and the
+script's `--lu-tabs-indicator-*` variables.
+
+## Keyboard and focus
+
+The [WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/):
+
+| Key                   | Does                                                                                               |
+| --------------------- | -------------------------------------------------------------------------------------------------- |
+| Tab                   | Into the list, onto the selected tab; out of it, onto the panel.                                   |
+| ArrowRight, ArrowLeft | The next or previous tab (horizontal). Swapped in right-to-left. Loops unless `loopFocus={false}`. |
+| ArrowDown, ArrowUp    | The next or previous tab (vertical).                                                               |
+| Home, End             | The first or last tab.                                                                             |
+| Enter, Space          | Selects the focused tab (manual activation).                                                       |
+
+- **Manual activation** (the default, as in Base UI): the arrows move focus and Enter, Space or a
+  click selects. With `activateOnFocus`, moving focus selects too. Either way only the panels
+  change: nothing navigates or submits.
+- **Only the main button** selects: a right-click does not. Disabled tabs take focus but are
+  never selected.
+- The arrow keys do nothing while an input method is composing, or with Alt, Ctrl or Meta held.
+
+## Without JavaScript, and the element's script
+
+The server HTML is complete: the selected tab, its panel and the tab stop are right before any
+script loads, and the panels of the other tabs are `hidden`. Selecting another tab needs
+`<lu-tabs>`' script, a 1.2 kB (brotli) module that a page rendering `Tabs` loads once, without
+the Lumiose runtime; islands bundle it. A `Tabs.Indicator` is placed by CSS alone until then; the
+script makes it follow a new selection. `value`, `onValueChange` and `bind:value` need the
+component to run in an island.
+
+## Browser support
+
+- **Custom elements** (`<lu-tabs>`) and everything the element uses: every current browser.
+- The default theme's vertical tabs follow the direction with logical properties
+  (`border-inline-end`): every current browser.
+- **CSS anchor positioning** places `Tabs.Indicator` before the script runs: Chrome and Edge 125,
+  Firefox 147, Safari 26. Elsewhere it appears once the script has measured the selected tab.
+
+## Related
+
+- [UI components](README.md): the approach, styling, the default theme and the other components.
+- [Web components](https://itsjavi.com/lumiose/docs/guides/web-components/): custom elements, their properties and
+  `bind:` on them.