@lumiose/ui 0.0.0-stage → 0.1.0

package/docs/progress.md

@@ -0,0 +1,115 @@
+# Progress
+
+> A task's progress, after Base UI's Progress: a native `<progress>` (the progress bar for assistive technology, with its value and `aria-valuetext`), labelled, with the value as text (a percentage by default, or your `Intl.NumberFormat` options). With no value it is indeterminate. No script.
+
+```ts
+import { Progress } from "@lumiose/ui"; // or "@lumiose/ui/progress"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Progress.Root value={30}>
+  <Progress.Label />
+  <Progress.Value />
+  <Progress.Track />
+</Progress.Root>
+```
+
+| Part    | Renders                                                                        |
+| ------- | ------------------------------------------------------------------------------ |
+| `Root`  | `<div>` with `--lu-value` (`0%` to `100%`; unset while indeterminate)          |
+| `Label` | `<label for>` the track                                                        |
+| `Value` | `<span>` with the formatted value (empty while indeterminate)                  |
+| `Track` | `<progress value max aria-valuetext>`: the bar; no `value` while indeterminate |
+
+## API
+
+### Progress.Root
+
+| Prop               | Type                                                | Default             |                                                                                     |
+| ------------------ | --------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------- |
+| `value`            | `number \| null`                                    |                     | The progress, from `min` to `max`; `null` while unknown (indeterminate). Required.  |
+| `min`              | `number`                                            | `0`                 | The start.                                                                          |
+| `max`              | `number`                                            | `100`               | The end: done.                                                                      |
+| `format`           | `Intl.NumberFormatOptions`                          | a percentage        | How the value is written. With it, the value itself is formatted, not a percentage. |
+| `locale`           | `Intl.LocalesArgument`                              | the browser's       | The locale of the formatted value (the server's in server HTML).                    |
+| `getAriaValueText` | `(formattedValue: string, value: number) => string` | the formatted value | The text assistive technology reads.                                                |
+
+Every other prop passes through to the `<div>`: `id`, `class`, `style`.
+
+### Progress.Label, Progress.Track and Progress.Value
+
+`Label` takes `<label>` props, its `id` among them; the `Track` keeps its own `id`, which the
+`Label` before it points at (see [Ids](README.md#ids)). `Track` takes `<progress>` props (`aria-label` when there is no
+`Label`). `Value` takes `<span>` props, and its `children` may be a function
+`(formattedValue, value) => JSX.Element` that writes the value your way.
+
+**Differences from Base UI's Progress.** The `<progress>` element is the track and the indicator:
+there is no `Progress.Indicator` (style the element's value pseudo-elements, or use `--lu-value`).
+Root has no `role`; the `<progress>` has it.
+
+## Example
+
+An upload, in an island:
+
+```tsx check
+import { Progress } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function UploadProgress() {
+  const done = signal<number | null>(null);
+  return (
+    <p>
+      <button
+        type="button"
+        class="lu-button"
+        onClick={() => done.set(Math.min(100, (done() ?? 0) + 20))}
+      >
+        Upload a part
+      </button>
+      <Progress.Root value={done()} class="lu-progress">
+        <Progress.Label>Uploading</Progress.Label>
+        <Progress.Value />
+        <Progress.Track />
+      </Progress.Root>
+    </p>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-progress` on `Root`: the label and the value on a row above a
+10px bar, its edge in `--lu-input` (3:1 against the page, so the whole range shows) and its value in
+the primary colour (a lighter blue in dark mode). Indeterminate, a segment slides along it; it
+stands still where motion is reduced.
+
+**With your own CSS**, style the bar with `appearance: none` and its pseudo-elements:
+`::-webkit-progress-bar`, `::-webkit-progress-value`, `::-moz-progress-bar`, and
+`progress:indeterminate`. Or draw your own bar from `--lu-value` on `Root`.
+
+Progress ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+A progress bar is not interactive: it takes no focus and no keys.
+
+## Without JavaScript
+
+Fully: the server renders the `<progress>` with its value, the label and the text. It changes when
+the component renders again (in an island, from a signal).
+
+Right to left, the native bar fills from the right, and the default theme's indeterminate
+segment slides leftward.
+
+## Browser support
+
+Native `<progress>`: every browser. Its pseudo-elements differ between engines, hence the two sets
+above.
+
+## Related
+
+- [Meter](meter.md): a measurement within a range, not a task's progress.
+- [Toast](toast.md): tell the user when the task is done.

package/docs/radio-group.md

@@ -0,0 +1,127 @@
+# Radio
+
+> A group of radios with one value, after Base UI's RadioGroup and Radio: native radios in a `<fieldset role="radiogroup">`. The browser gives the group one tab stop, arrow keys that move and select (skipping disabled radios), `required`, submission and reset, in server HTML and without JavaScript; a legend names the group. `bind:value` keeps a signal in sync.
+
+```ts
+import { Radio, RadioGroup, Fieldset } from "@lumiose/ui"; // or "@lumiose/ui/radio-group"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<RadioGroup>
+  <Fieldset.Legend />
+  <Radio.Root />
+</RadioGroup>
+```
+
+| Part         | Renders                                                                                  |
+| ------------ | ---------------------------------------------------------------------------------------- |
+| `RadioGroup` | `<fieldset role="radiogroup">`; a `Fieldset.Legend` first inside names it.               |
+| `Radio.Root` | `<input type="radio">` with the group's `name`, checked when its `value` is the group's. |
+
+Put each radio in a `<label>` (or name it with `aria-label`).
+
+## API
+
+### RadioGroup
+
+| Prop            | Type                      | Default         |                                                                                 |
+| --------------- | ------------------------- | --------------- | ------------------------------------------------------------------------------- |
+| `value`         | `string`                  |                 | Checks the radio with this value when it changes. Pair it with `onValueChange`. |
+| `defaultValue`  | `string`                  |                 | The radio checked at first; none when left out.                                 |
+| `onValueChange` | `(value: string) => void` |                 | Called with the value of the radio the user checks.                             |
+| `bind:value`    | `Signal<string>`          |                 | Stands in for `value` and `onValueChange`.                                      |
+| `name`          | `string`                  | a generated one | The name the radios share and submit under (a Field's `name` inside a Field).   |
+| `required`      | `boolean`                 | `false`         | A radio must be checked to submit the form (`aria-required` on the group).      |
+| `readOnly`      | `boolean`                 | `false`         | The radios cannot be checked, but stay focusable and are submitted.             |
+| `disabled`      | `boolean`                 | `false`         | Disables every radio (a disabled fieldset).                                     |
+
+Every other `<fieldset>` prop passes through. Inside a Field, the group takes the field's
+`aria-describedby` and `aria-invalid`, and its radios the field's name.
+
+### Radio.Root
+
+| Prop       | Type      | Default |                                                         |
+| ---------- | --------- | ------- | ------------------------------------------------------- |
+| `value`    | `string`  |         | Required: the value the group takes when it is checked. |
+| `disabled` | `boolean` | `false` | It cannot be checked; the arrow keys skip it.           |
+
+Every other native prop passes through (`id`, `class`, `aria-*`).
+
+**Differences from Base UI's RadioGroup and Radio.** The radios are native inputs in a fieldset, so
+there is no `Radio.Indicator` (style `:checked` with `appearance: none`) and no `nativeButton` or
+`inputRef`.
+
+## Example
+
+In an island, bound to a signal:
+
+```tsx check
+import { Fieldset, Radio, RadioGroup } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function ShippingChoice() {
+  const speed = signal("standard");
+  return (
+    <div>
+      <RadioGroup name="shipping" bind:value={speed} class="lu-fieldset">
+        <Fieldset.Legend>Shipping</Fieldset.Legend>
+        <label>
+          <Radio.Root value="standard" class="lu-radio" /> Standard
+        </label>
+        <label>
+          <Radio.Root value="express" class="lu-radio" /> Express
+        </label>
+        <label>
+          <Radio.Root value="drone" disabled class="lu-radio" /> Drone (soon)
+        </label>
+      </RadioGroup>
+      <p>Arrives {speed() === "express" ? "tomorrow" : "in three days"}.</p>
+    </div>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-fieldset` on the group and `lu-radio` on each radio: an 18px
+circle in a 24px target, a thick primary ring when checked (a shape, not only a colour), a focus
+ring.
+
+**With your own CSS**, style the inputs and their state: `:checked`, `:disabled`,
+`:focus-visible`; the group: `[role="radiogroup"]`, `[aria-invalid="true"]`.
+
+Radio Group ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+| Key                     | Does                                                                              |
+| ----------------------- | --------------------------------------------------------------------------------- |
+| Tab                     | Into the group, on the checked radio (or the first, from either side); out of it. |
+| Arrow Down, Arrow Right | Checks the next enabled radio, around at the end.                                 |
+| Arrow Up, Arrow Left    | Checks the previous enabled radio, around at the start.                           |
+| Space                   | Checks the focused radio.                                                         |
+
+Enter does not check a radio. Read-only radios move focus but do not change. Right to left, Arrow
+Left checks the next radio and Arrow Right the previous one.
+
+## Without JavaScript, and the client script
+
+Native radios: the roving tab stop, the arrow keys, `required`, submission and reset 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 runs the
+arrow keys itself so that every browser follows the table above: without it, WebKit's native
+radios stop at the ends and keep Left and Right as they are right to left.
+
+## Browser support
+
+Native radios and `role="radiogroup"` on a fieldset: every supported browser.
+
+## Related
+
+- [Checkbox Group](checkbox-group.md): several values.
+- [Select](select.md): one value from a longer list.
+- [Field](field.md): a description and errors for the group.
+- [Fieldset](fieldset.md): the legend.

package/docs/scroll-area.md

@@ -0,0 +1,147 @@
+# Scroll Area
+
+> A scrolling region with custom scrollbars laid over native scrolling, after Base UI's ScrollArea. The viewport scrolls natively (the wheel, touch, the keyboard, find-in-page), is focusable while it overflows, and traps nothing; without JavaScript its native scrollbars show. `<lu-scroll-area>`'s 1.6 kB script hides them and draws its own, which show on hover, while scrolling and while focused, take a thumb drag and a track press, and expose the overflow as data attributes and CSS variables.
+
+```ts
+import { ScrollArea } from "@lumiose/ui"; // or "@lumiose/ui/scroll-area"
+import "@lumiose/ui/scroll-area.css"; // or "@lumiose/ui/styles.css" for every component
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<ScrollArea.Root>
+  <ScrollArea.Viewport>
+    <ScrollArea.Content />
+  </ScrollArea.Viewport>
+  <ScrollArea.Scrollbar>
+    <ScrollArea.Thumb />
+  </ScrollArea.Scrollbar>
+  <ScrollArea.Scrollbar orientation="horizontal">
+    <ScrollArea.Thumb />
+  </ScrollArea.Scrollbar>
+  <ScrollArea.Corner />
+</ScrollArea.Root>
+```
+
+| Part        | Renders                                                                                             |
+| ----------- | --------------------------------------------------------------------------------------------------- |
+| `Root`      | `<lu-scroll-area>`: give it a size (a height or a max height); the viewport fills it                |
+| `Viewport`  | `<div tabindex="0" data-viewport>`: scrolls natively; `tabindex="-1"` while nothing overflows       |
+| `Content`   | `<div>`, at least as wide as what it holds                                                          |
+| `Scrollbar` | `<div aria-hidden="true" data-scrollbar data-orientation>` over an edge; hidden while its axis fits |
+| `Thumb`     | `<div data-thumb>`, sized and moved by the script                                                   |
+| `Corner`    | `<div data-corner hidden>`, where the scrollbars meet, shown while both axes overflow               |
+
+## API
+
+### ScrollArea.Root
+
+| Prop                    | Type     | Default |                                                                                       |
+| ----------------------- | -------- | ------- | ------------------------------------------------------------------------------------- |
+| `overflowEdgeThreshold` | `number` | `0`     | How many px of content past an edge before `data-overflow-*-start` or `-end` applies. |
+
+### ScrollArea.Scrollbar
+
+| Prop          | Type                         | Default      |                                                             |
+| ------------- | ---------------------------- | ------------ | ----------------------------------------------------------- |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | The edge and axis: the inline end, or the bottom.           |
+| `keepMounted` | `boolean`                    | `false`      | Keeps the scrollbar shown while its axis does not overflow. |
+
+### The other parts
+
+Each part passes the props of its element through. Give the `Viewport` an `aria-label`, and
+`role="region"` when it holds a section people should find: it is a tab stop while it overflows
+(and in server HTML before the script, which cannot know whether it will). The scrollbars are
+`aria-hidden` pointer conveniences, since the viewport itself scrolls from the keyboard.
+
+**Data attributes and CSS variables.** On Root and Viewport: `data-has-overflow-x`,
+`data-has-overflow-y`, `data-overflow-x-start`, `-x-end`, `-y-start`, `-y-end`, `data-scrolling`
+(Root). On the Viewport: `--lu-scroll-area-overflow-x-start` (and `-x-end`, `-y-start`, `-y-end`),
+the px of content past each edge, for fades. On the Scrollbars: `data-orientation`,
+`data-hovering`, `data-scrolling`, and `--lu-scroll-area-thumb-height` (or `-width`). On Root:
+`--lu-scroll-area-corner-width` and `-height`.
+
+**What CSS can do alone.** `scrollbar-color`, `scrollbar-width` and `scrollbar-gutter` recolour
+and thin the native scrollbar in every current browser, with no script; they cannot shape it, lay
+it over the content, or show it only on hover. Style the native scrollbar that way for pages
+without JavaScript; the custom scrollbars take over once the script runs.
+
+**Differences from Base UI's ScrollArea.** The custom properties are `--lu-scroll-area-*` (Base
+UI's `--scroll-area-*`); the viewport is focusable while it overflows; no `render`.
+
+## Example
+
+```tsx check
+import { ScrollArea } from "@lumiose/ui";
+
+const RELEASES = ["1.4.0", "1.3.2", "1.3.1", "1.3.0", "1.2.0", "1.1.0", "1.0.0"];
+
+export function ReleaseList() {
+  return (
+    <ScrollArea.Root class="lu-scroll-area" style={{ "block-size": "8rem" }}>
+      <ScrollArea.Viewport role="region" aria-label="Releases">
+        <ScrollArea.Content>
+          <ul>
+            {RELEASES.map((release) => (
+              <li>{release}</li>
+            ))}
+          </ul>
+        </ScrollArea.Content>
+      </ScrollArea.Viewport>
+      <ScrollArea.Scrollbar>
+        <ScrollArea.Thumb />
+      </ScrollArea.Scrollbar>
+    </ScrollArea.Root>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-scroll-area` on `Root`: a bordered box, padded content, 10px
+scrollbars whose rounded thumbs (`--lu-muted-foreground`, 3:1) show while the pointer is over the
+area, while it scrolls and while it has focus, and an inward focus ring on the viewport. Each
+thumb takes presses over 24 by 24 px at least (WCAG 2.5.8), reaching 16px into the content; the
+track stays 10px, which the wheel, the keyboard and the thumb stand in for.
+
+**With your own CSS**, style the parts through `class`, `[data-scrollbar]`, `[data-thumb]`,
+`[data-orientation]`, `[data-hovering]`, `[data-scrolling]` and the overflow attributes and
+custom properties above; a fade at an edge reads `--lu-scroll-area-overflow-y-end`.
+
+`@lumiose/ui/scroll-area.css` (0.3 kB brotli) fills the root with the viewport, hides the native
+scrollbar once the script runs (`:defined`) and the custom ones until then, places the scrollbars
+over the edges leaving room for the corner, and sizes the thumbs from the custom properties.
+
+## Keyboard and focus
+
+| Key                         | Does                                                    |
+| --------------------------- | ------------------------------------------------------- |
+| Tab                         | Onto the viewport while it overflows, then on: no trap. |
+| Arrow keys                  | Scroll a line.                                          |
+| Page Up / Page Down / Space | Scroll a page.                                          |
+| Home / End                  | The top or the bottom.                                  |
+
+The keys are the browser's own scrolling of the focused viewport. A focusable child (a link) takes
+focus first, and the viewport scrolls it into view.
+
+## Without JavaScript, and the element's script
+
+The viewport scrolls with its native scrollbars, from the keyboard too. It keeps its
+`tabindex="0"` then, so an area that does not overflow is a tab stop with nothing to scroll: one
+reason to name it. `<lu-scroll-area>`'s script
+(1.6 kB brotli) hides them and runs the custom ones: thumbs sized and moved on every scroll and
+resize (a ResizeObserver follows content that grows), dragging and track presses, the wheel over
+a scrollbar (which scrolls the viewport, and the page once the viewport is at its end), hover and
+scrolling states, the overflow attributes and variables, the corner, right to left.
+
+## Browser support
+
+`scrollbar-width: none` and `::-webkit-scrollbar`, ResizeObserver and pointer capture: every
+supported browser.
+
+## Related
+
+- [Dialog](dialog.md): a modal whose long content scrolls in a Scroll Area.
+- [Combobox](combobox.md) and [Select](select.md): lists that scroll on their own.

package/docs/select.md

@@ -0,0 +1,236 @@
+# Select
+
+> A native `<select>` for picking one value from a list: it works with no JavaScript, submits with its form and keeps the platform's keyboard, typeahead and mobile pickers. Where the browser has customizable select (`appearance: base-select`, Chrome 135, Safari 26), `Select.Trigger` and `Select.Value` shape the button, the picker is styleable and options may hold more than text; elsewhere it is the classic select. No script; `bind:value` keeps a signal in sync in islands.
+
+```ts
+import { Select } from "@lumiose/ui"; // or "@lumiose/ui/select"
+import "@lumiose/ui/select.css"; // makes a select with a Trigger a customizable select
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Select.Root>
+  <Select.Trigger>
+    <Select.Value />
+  </Select.Trigger>
+  <Select.Item />
+  <Select.Separator />
+  <Select.Group>
+    <Select.Item />
+  </Select.Group>
+</Select.Root>
+```
+
+| Part        | Renders                                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------------------------- |
+| `Root`      | `<select>`, the control (`role="combobox"`), with the props it is given.                                |
+| `Trigger`   | `<button type="button">`, customizable select's button. Optional; it must be the first child of `Root`. |
+| `Value`     | `<selectedcontent>`, where the browser copies the selected option's content. Inside the `Trigger`.      |
+| `Item`      | `<option value="…">`.                                                                                   |
+| `Group`     | `<optgroup label="…">` of options.                                                                      |
+| `Separator` | `<hr>` between options or groups.                                                                       |
+
+The picker, the popup of options, is the select's own `::picker(select)`: there is no part for it.
+Browsers without customizable select drop the `Trigger` and show their own control and picker, with
+the options' text.
+
+## API
+
+### Select.Root
+
+| Prop            | Type                      | Default          |                                                                                   |
+| --------------- | ------------------------- | ---------------- | --------------------------------------------------------------------------------- |
+| `value`         | `string`                  |                  | Selects the option with this value when it changes. Pair it with `onValueChange`. |
+| `defaultValue`  | `string`                  | the first option | The option selected at first, when `value` is left out.                           |
+| `onValueChange` | `(value: string) => void` |                  | Called after the user selects another option, with its value.                     |
+| `bind:value`    | `Signal<string>`          |                  | Stands in for `value` and `onValueChange`.                                        |
+| `name`          | `string`                  |                  | The name the value is submitted under.                                            |
+| `required`      | `boolean`                 | `false`          | The form needs a value: an option whose value is `""` counts as none.             |
+| `disabled`      | `boolean`                 | `false`          | The select cannot be used.                                                        |
+
+Every other `<select>` prop passes through: `id`, `autocomplete`, `form`, `class`, `aria-*`, event
+handlers. Name it with a `<label for>` pointing at its `id`, or `aria-label`, or put it in a
+[Field](field.md) with a `Field.Label`: it takes the field's id, name and ARIA references.
+
+### Select.Item
+
+| Prop       | Type      | Default |                                                                                                                       |
+| ---------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
+| `value`    | `string`  |         | Required: the value the select takes, and submits, when selected.                                                     |
+| `disabled` | `boolean` | `false` | The option cannot be selected; the arrow keys skip it.                                                                |
+| `label`    | `string`  |         | The option's text for typeahead and the classic select, when its content starts with an icon or holds more than text. |
+
+### Select.Group
+
+| Prop    | Type     | Default |                                                    |
+| ------- | -------- | ------- | -------------------------------------------------- |
+| `label` | `string` |         | Required: the group's name, shown above its items. |
+
+### The other parts
+
+`Trigger`, `Value` and `Separator` take the props of the element they render (`class`, `style`,
+`aria-*`, `data-*`) and pass them through.
+
+**Differences from Base UI's Select.** Select is the native control, chosen over the listbox
+pattern because it works without JavaScript, carries forms, autofill, validation and the mobile
+pickers, and ships no script. So it has no `open`, `onOpenChange` or `modal` (the platform fires no
+event when the picker opens; style `:open` instead), no `Label` (use `<label for>`), no `multiple`
+(use [Combobox](combobox.md) with `multiple`), no `alignItemWithTrigger` (the picker opens below the
+control and flips), no `Portal`, `Positioner`, `Popup`, `List`, `Icon`, `ItemText`,
+`ItemIndicator`, `GroupLabel`, `Arrow` or scroll arrows (the picker, `::picker-icon` and
+`option::checkmark` are the platform's), and Enter does not open it (Space and the arrows do, as on
+any select).
+
+## Example
+
+A select in a server-rendered page, with no island, styled by the default theme:
+
+```tsx check
+import { Select } from "@lumiose/ui";
+
+export function PlanField() {
+  return (
+    <form method="post">
+      <label for="plan">Plan</label>
+      <Select.Root id="plan" name="plan" defaultValue="pro" class="lu-select">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Item value="free">Free</Select.Item>
+        <Select.Item value="pro">Pro</Select.Item>
+        <Select.Separator />
+        <Select.Group label="Teams">
+          <Select.Item value="team">Team</Select.Item>
+          <Select.Item value="enterprise" disabled>
+            Enterprise
+          </Select.Item>
+        </Select.Group>
+      </Select.Root>
+      <button class="lu-button">Save</button>
+    </form>
+  );
+}
+```
+
+In an island, bound to a signal. `bind:value={theme}` is short for `value={theme()}` plus
+`onValueChange={(next) => theme.set(next)}`.
+
+```tsx check
+import { Select } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function ThemePicker() {
+  const theme = signal("system");
+  return (
+    <Select.Root aria-label="Theme" bind:value={theme} class="lu-select">
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Item value="light">Light</Select.Item>
+      <Select.Item value="dark">Dark</Select.Item>
+      <Select.Item value="system">System</Select.Item>
+    </Select.Root>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-select` on `Root`. It makes the select a customizable select
+and styles the control, the picker, the options (hover and keyboard focus, disabled), the groups and
+the separators; in browsers without customizable select it styles the closed control. Its colours
+come from the theme's `--lu-` properties ([UI components](README.md#the-default-theme)).
+
+**With your own CSS**, opt in to customizable select and style the select's parts and states:
+
+- the control: the `select` itself, `:open` while its picker is open, `:focus-visible`,
+  `:disabled`, `:invalid` and `:user-invalid`, and `::picker-icon`;
+- the picker: `::picker(select)`, placed with anchor positioning (`position-area`,
+  `position-try-fallbacks` work on it);
+- options: `option`, `option:checked`, `option:hover`, `option:focus-visible`, `option:disabled`,
+  and `option::checkmark`;
+- `optgroup`, `hr`, and inside the `Trigger`, `selectedcontent`.
+
+A starting point:
+
+```css
+.select,
+.select::picker(select) {
+  appearance: base-select;
+}
+.select {
+  padding: 0.5rem 0.75rem;
+  border: 1px solid #85858e;
+  border-radius: 0.5rem;
+}
+.select::picker(select) {
+  padding: 0.25rem;
+  border: 1px solid #e4e4e7;
+  border-radius: 0.5rem;
+}
+.select option:focus-visible {
+  background: #f4f4f5;
+  outline: 2px solid #2563eb;
+  outline-offset: -2px;
+}
+```
+
+`@lumiose/ui/select.css` holds what Select needs to work, in the `lu.core` layer: a select whose
+first child is a `Trigger` gets `appearance: base-select` (and so does its picker), since only a
+customizable select renders the trigger, `Value` and options with more than text. Where
+customizable select is missing, it hides the `Trigger` (Firefox keeps it in the select, a nameless
+button for assistive technology otherwise). A select with no `Trigger` keeps the browser's look
+until your CSS or the theme opts in.
+
+## Keyboard and focus
+
+The platform's: the select is one tab stop with `role="combobox"`, and the browser runs the
+keyboard. In Chromium's customizable select:
+
+| Key                         | Does                                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Space, Arrow Down, Arrow Up | On the control: opens the picker, with focus on the selected option.                                    |
+| Alt+Arrow Down, F4          | On the control: opens the picker.                                                                       |
+| Arrow Down, Arrow Up        | In the picker: the next or previous option; disabled options are skipped.                               |
+| Home, End                   | In the picker: the first or last option.                                                                |
+| A character                 | In the picker: typeahead, the next option whose text starts with it.                                    |
+| Enter, Space                | In the picker: selects the focused option and closes the picker.                                        |
+| Escape                      | Closes the picker without selecting, focus back on the control; closed, it goes on, so a dialog closes. |
+| Tab                         | In the picker: closes it, focus back on the control; from there Tab moves on.                           |
+
+A click on a `<label for>` focuses the select without opening it. A click on the control opens the
+picker; a click on an option selects it; a click outside closes the picker. Other browsers keep
+their own select keyboard and pickers, which differ by platform.
+
+## Without JavaScript
+
+Select needs none: it is a native control, in server HTML and with JavaScript off, on every
+browser. It submits under its `name`, is validated (`required`), resets with its form, takes the
+browser's autofill and is disabled by a disabled `<fieldset>`. `value`, `onValueChange` and
+`bind:value` need the component to run in the browser, in an island; there `value` sets the
+control's value when it changes, and its `change` event calls `onValueChange`.
+
+## Browser support
+
+- **Customizable select** (`appearance: base-select`, `::picker(select)`, `<selectedcontent>`, a
+  `<button>` and rich content inside `<select>`): Chrome and Edge 135, Safari 26 (the end-to-end
+  tests run it in Chromium and WebKit 26.6). Firefox has none yet: it shows its classic select,
+  styled by the theme when closed, with the options' text (or their `label`).
+- Firefox 155 keeps the `Trigger` and the tags inside options in the DOM (`select.css` hides the
+  `Trigger`). Older browsers without customizable select drop them from server HTML, so an
+  island's select falls back to rendering on the client there
+  ([LUM4006](https://itsjavi.com/lumiose/docs/errors/LUM4006/)).
+- **Typeahead** matches an option's text, or its `label`: give options that start with an icon a
+  `label`.
+- **`:open`** comes with customizable select.
+
+## Related
+
+- [Combobox](combobox.md): when the list is long enough to filter, for several values, or for
+  async options.
+- [Menu](menu.md): commands rather than a value.
+- [UI components](README.md): the approach, styling, the default theme and the other components.
+- [Islands](https://itsjavi.com/lumiose/docs/concepts/islands/): running a component in the
+  browser, for `bind:value`.