@lumiose/ui 0.0.0-stage → 0.1.1

package/docs/meter.md

@@ -0,0 +1,103 @@
+# Meter
+
+> A measurement within a known range (storage used, a password's strength, a rating), after Base UI's Meter: a native `<meter>` (with its value, range and `aria-valuetext`), labelled, with the value as text (a percentage of the range by default, or your `Intl.NumberFormat` options). No script.
+
+```ts
+import { Meter } from "@lumiose/ui"; // or "@lumiose/ui/meter"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Meter.Root value={72}>
+  <Meter.Label />
+  <Meter.Value />
+  <Meter.Track />
+</Meter.Root>
+```
+
+| Part    | Renders                                         |
+| ------- | ----------------------------------------------- |
+| `Root`  | `<div>` with `--lu-value` (`0%` to `100%`)      |
+| `Label` | `<label for>` the track                         |
+| `Value` | `<span>` with the formatted value               |
+| `Track` | `<meter value min max aria-valuetext>`: the bar |
+
+## API
+
+### Meter.Root
+
+| Prop               | Type                                                | Default             |                                                                                     |
+| ------------------ | --------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------- |
+| `value`            | `number`                                            |                     | The measurement, from `min` to `max`. Required.                                     |
+| `min`              | `number`                                            | `0`                 | The bottom of the range.                                                            |
+| `max`              | `number`                                            | `100`               | The top of the range.                                                               |
+| `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`.
+
+### Meter.Label, Meter.Track and Meter.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 `<meter>` props, among them the native `low`, `high`
+and `optimum`, which tell browsers which band a value is in (`aria-label` when there is no
+`Label`). `Value` takes `<span>` props, and its `children` may be a function
+`(formattedValue, value) => JSX.Element`.
+
+**Differences from Base UI's Meter.** The `<meter>` element is the track and the indicator: there is
+no `Meter.Indicator`. Root has no `role`; the `<meter>` has it (`meter`).
+
+## Example
+
+```tsx check
+import { Meter } from "@lumiose/ui";
+
+export function StorageMeter() {
+  return (
+    <Meter.Root
+      value={7.2}
+      max={10}
+      getAriaValueText={(_, gb) => `${gb} of 10 GB`}
+      class="lu-meter"
+    >
+      <Meter.Label>Storage used</Meter.Label>
+      <Meter.Value>{(_, gb) => `${gb} GB of 10`}</Meter.Value>
+      <Meter.Track low={6} high={9} optimum={0} />
+    </Meter.Root>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-meter` on `Root`: the label and the value on a row above a 10px
+bar, its edge in `--lu-input` (3:1, so the whole range shows) and its value in the primary colour
+(a lighter blue in dark mode), whatever band it is in.
+
+**With your own CSS**, style the bar with `appearance: none` and its pseudo-elements:
+`::-webkit-meter-bar`, `::-webkit-meter-optimum-value`, `::-webkit-meter-suboptimum-value`,
+`::-webkit-meter-even-less-good-value`, `::-moz-meter-bar` (and `:-moz-meter-optimum` and the
+others). Or draw your own bar from `--lu-value` on `Root`.
+
+Meter ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+A meter is not interactive: it takes no focus and no keys.
+
+## Without JavaScript
+
+Fully: the server renders the `<meter>` with its value, range, label and text.
+
+## Browser support
+
+Native `<meter>`: every browser. Its pseudo-elements differ between engines, hence the two sets
+above. `role="meter"` reaches screen readers in recent versions; older ones read a progress bar.
+
+## Related
+
+- [Progress](progress.md): a task's progress, which can be indeterminate.
+- [Slider](slider.md): a value the user picks within a range.

package/docs/navigation-menu.md

@@ -0,0 +1,257 @@
+# Navigation Menu
+
+> A site's navigation whose items open panels of links, after Base UI's NavigationMenu and the WAI-ARIA disclosure navigation pattern: a `<nav>` landmark around a list, each trigger opening its content through `popovertarget` (a native popover placed under it by CSS anchor positioning), so the links work and the panels open on a click, one at a time, in server HTML with no JavaScript. A 3.5 kB script adds hover intent, the arrow keys, closing when focus leaves and the direction a panel comes in from. `bind:value` (or `value` and `onValueChange`) keeps the open item in a signal.
+
+```ts
+import { NavigationMenu } from "@lumiose/ui"; // or "@lumiose/ui/navigation-menu"
+import "@lumiose/ui/navigation-menu.css"; // places each content next to its trigger
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<NavigationMenu.Root>
+  <NavigationMenu.List>
+    <NavigationMenu.Item>
+      <NavigationMenu.Trigger>
+        <NavigationMenu.Icon />
+      </NavigationMenu.Trigger>
+      <NavigationMenu.Content>
+        <NavigationMenu.Link />
+      </NavigationMenu.Content>
+    </NavigationMenu.Item>
+    <NavigationMenu.Item>
+      <NavigationMenu.Link />
+    </NavigationMenu.Item>
+  </NavigationMenu.List>
+</NavigationMenu.Root>
+```
+
+| Part      | Renders                                                                                                    |
+| --------- | ---------------------------------------------------------------------------------------------------------- |
+| `Root`    | `<nav data-orientation="…">` inside `<lu-navigation-menu>`, an element with no box; a `<div>` when nested. |
+| `List`    | `<ul>` of the items.                                                                                       |
+| `Item`    | `<li data-value="…">`: a trigger with its content, or a link.                                              |
+| `Trigger` | `<button type="button" popovertarget="…">`; `aria-expanded` follows its content where the script runs.     |
+| `Icon`    | `<span aria-hidden="true">` inside the trigger, such as a chevron.                                         |
+| `Content` | `<div popover="auto" data-side="…" data-align="…">` of links, anchored to its trigger.                     |
+| `Link`    | `<a>`; `aria-current="page"` and `data-active` when `active`.                                              |
+
+Give `Root` an `aria-label` ("Main") when the page has more than one `<nav>`. A `Root` inside a
+`Content` is a nested menu: a `<div>`, inside its parent's landmark. Focus, the pointer or a click
+in it keep its parent's content open.
+
+## API
+
+### NavigationMenu.Root
+
+| Prop            | Type                              | Default        |                                                                                                                     |
+| --------------- | --------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `value`         | `string \| null`                  |                | The `value` of the item whose content is open, or `null`; opens or closes them when it changes, in the browser.     |
+| `defaultValue`  | `string \| null`                  | `null`         | The item open at first, in the browser, when `value` is left out.                                                   |
+| `onValueChange` | `(value: string \| null) => void` |                | Called after a content opens (its item's `value`) or the open one closes (`null`), whatever did it.                 |
+| `bind:value`    | `Signal<string \| null>`          |                | Stands in for `value` and `onValueChange`.                                                                          |
+| `delay`         | `number`                          | `50`           | How long the pointer rests on a trigger before its content opens, in milliseconds.                                  |
+| `closeDelay`    | `number`                          | `50`           | How long after the pointer leaves an item its content closes, in milliseconds (300 while it heads for the content). |
+| `orientation`   | `"horizontal" \| "vertical"`      | `"horizontal"` | Which way the items run: vertical moves with Arrow Up and Down and places contents at the inline end.               |
+
+Server HTML always starts closed: a popover only opens from its trigger or script.
+
+### NavigationMenu.Item
+
+| Prop    | Type     | Default        |                                         |
+| ------- | -------- | -------------- | --------------------------------------- |
+| `value` | `string` | a generated id | The value `Root`'s `value` names it by. |
+
+### NavigationMenu.Content
+
+| Prop          | Type                                                                       | Default                                   |                                                 |
+| ------------- | -------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- |
+| `side`        | `"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"` | `"bottom"` (`"inline-end"` when vertical) | The trigger's side it goes on; it flips to fit. |
+| `align`       | `"start" \| "center" \| "end"`                                             | `"center"` (`"start"` when vertical)      | How it aligns with the trigger along that side. |
+| `sideOffset`  | `number`                                                                   |                                           | The gap to the trigger, in CSS pixels.          |
+| `alignOffset` | `number`                                                                   |                                           | A shift along the side, in CSS pixels.          |
+
+### NavigationMenu.Link
+
+| Prop           | Type      | Default |                                                                               |
+| -------------- | --------- | ------- | ----------------------------------------------------------------------------- |
+| `active`       | `boolean` | `false` | The link to the current page: `aria-current="page"`.                          |
+| `closeOnClick` | `boolean` | `false` | Whether following it closes the open content (every level, in a nested menu). |
+
+### The other parts
+
+Each part takes the props of the element it renders (`class`, `style`, `aria-*`, `data-*`, event
+handlers) and passes them through: `href` and `target` on a `Link`, `disabled` and `id` on a
+`Trigger`. A `Content` keeps its own `id`, which its trigger points at (see [Ids](README.md#ids)).
+
+**Differences from Base UI's NavigationMenu.** Each `Content` is its own popover in the top layer,
+anchored to its trigger: there is no shared `Viewport`, `Popup`, `Positioner`, `Portal`,
+`Backdrop` or `Arrow`, and so no `--popup-width` and `--popup-height` to animate one box between
+contents. `data-activation-direction` lets a content slide in from where the previous one was. No
+`actionsRef`, `onOpenChangeComplete`, `keepMounted` or `render`.
+
+## Example
+
+A site's main navigation in a server-rendered page, with no island, styled by the default theme:
+
+```tsx check
+import { NavigationMenu } from "@lumiose/ui";
+
+export function MainNavigation() {
+  return (
+    <NavigationMenu.Root aria-label="Main" class="lu-navigation-menu">
+      <NavigationMenu.List>
+        <NavigationMenu.Item>
+          <NavigationMenu.Trigger>
+            Products <NavigationMenu.Icon>▾</NavigationMenu.Icon>
+          </NavigationMenu.Trigger>
+          <NavigationMenu.Content>
+            <ul>
+              <li>
+                <NavigationMenu.Link href="#analytics">Analytics</NavigationMenu.Link>
+              </li>
+              <li>
+                <NavigationMenu.Link href="#automation">Automation</NavigationMenu.Link>
+              </li>
+            </ul>
+          </NavigationMenu.Content>
+        </NavigationMenu.Item>
+        <NavigationMenu.Item>
+          <NavigationMenu.Trigger>
+            Learn <NavigationMenu.Icon>▾</NavigationMenu.Icon>
+          </NavigationMenu.Trigger>
+          <NavigationMenu.Content>
+            <ul>
+              <li>
+                <NavigationMenu.Link href="#guides">Guides</NavigationMenu.Link>
+              </li>
+              <li>
+                <NavigationMenu.Link href="#blog">Blog</NavigationMenu.Link>
+              </li>
+            </ul>
+          </NavigationMenu.Content>
+        </NavigationMenu.Item>
+        <NavigationMenu.Item>
+          <NavigationMenu.Link href="#pricing" active>
+            Pricing
+          </NavigationMenu.Link>
+        </NavigationMenu.Item>
+      </NavigationMenu.List>
+    </NavigationMenu.Root>
+  );
+}
+```
+
+In an island, the open item in a signal:
+
+```tsx check
+import { NavigationMenu } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function SiteNavigation() {
+  const open = signal<string | null>(null);
+  return (
+    <>
+      <NavigationMenu.Root aria-label="Site" bind:value={open} class="lu-navigation-menu">
+        <NavigationMenu.List>
+          <NavigationMenu.Item value="docs">
+            <NavigationMenu.Trigger>Docs</NavigationMenu.Trigger>
+            <NavigationMenu.Content>
+              <NavigationMenu.Link href="#start">Getting started</NavigationMenu.Link>
+            </NavigationMenu.Content>
+          </NavigationMenu.Item>
+          <NavigationMenu.Item value="community">
+            <NavigationMenu.Trigger>Community</NavigationMenu.Trigger>
+            <NavigationMenu.Content>
+              <NavigationMenu.Link href="#forum">Forum</NavigationMenu.Link>
+            </NavigationMenu.Content>
+          </NavigationMenu.Item>
+        </NavigationMenu.List>
+      </NavigationMenu.Root>
+      <p>Open: {open() ?? "none"}</p>
+    </>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-navigation-menu` on `Root`: the list in a row (a column when
+vertical), the triggers and links as 36px targets, the current page underlined, an open trigger
+filled with its icon turned, and each content a surface of links that fades and slides in.
+
+**With your own CSS**, style the parts through `class`, the triggers' `[aria-expanded="true"]`,
+links' `[aria-current="page"]`, and the contents' `:popover-open`, `[data-side]` and
+`[data-activation-direction]` (`left`, `right`, `up` or `down`: where the content's trigger is from
+the trigger of the content that was open before; absent when none was):
+
+```css
+.panel {
+  transition:
+    opacity 150ms,
+    translate 150ms,
+    overlay 150ms allow-discrete,
+    display 150ms allow-discrete;
+}
+.panel:not(:popover-open) {
+  opacity: 0;
+}
+@starting-style {
+  .panel[data-activation-direction="right"]:popover-open {
+    translate: 1rem 0;
+  }
+}
+```
+
+`@lumiose/ui/navigation-menu.css`, in the `lu.core` layer, holds the shared placement rules that put
+each content next to its trigger, with the same flips as Popover and Menu, and gives
+`<lu-navigation-menu>` no box.
+
+## Keyboard and focus
+
+| Key                     | Does                                                                                                        |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Tab, Shift+Tab          | Every trigger and link is a tab stop; from an open trigger, Tab goes into its content.                      |
+| Enter, Space            | On a trigger: opens or closes its content.                                                                  |
+| Arrow Right, Arrow Left | Between the top-level triggers and links (Down and Up when vertical; swapped right to left).                |
+| Home, End               | The first or last top-level trigger or link.                                                                |
+| Arrow Down              | On a trigger: opens its content on its first link (Arrow Right when vertical). In a content: the next link. |
+| Arrow Up                | In a content: the previous link.                                                                            |
+| Escape                  | Closes the open content and returns to its trigger.                                                         |
+
+- **The pointer**: resting on a trigger opens its content after `delay`, at once while another one
+  is open; leaving the item closes it after `closeDelay`, unless a click kept it open. On the way
+  from a trigger to its open content, another trigger the pointer crosses waits 300ms before it
+  takes over, so a diagonal path into a wide panel keeps it. A click toggles a content; a click
+  outside closes it, but not a right-click or a press in a toast.
+- **Focus** leaving an open item for elsewhere on the page closes its content. It is a navigation
+  landmark, not a menu: links keep their roles and the browser's link behaviour.
+
+## Without JavaScript, and the client script
+
+The `<nav>`, its links and the triggers are HTML: each trigger opens its content with
+`popovertarget`, one at a time (an auto popover closes the others), and Escape or a click outside
+closes it. `value`, `onValueChange` and `bind:value` need the component to run in an island.
+
+A page that renders a `NavigationMenu` loads a 3.5 kB (brotli) script (its dismissal module is
+Menu's and Popover's too), without the Lumiose runtime; islands bundle it. `<lu-navigation-menu>`
+takes over the trigger's click (so a click keeps a content opened by hover open), opens contents on
+hover, adds the arrow keys, closes a content when focus leaves its item, dismisses contents as Menu
+and Popover do (a press of the main button outside, an Escape, another layer opening), keeps
+`aria-expanded` and `data-activation-direction` current, and places the contents where CSS anchor
+positioning is missing.
+
+## Browser support
+
+- **Popovers and `popovertarget`**: every current browser.
+- **CSS anchor positioning**: Chrome and Edge 125, Firefox 147, Safari 26. Elsewhere the script
+  places the contents next to their triggers.
+- **Exit animations** that keep a content in the top layer (`overlay`) are Chromium-only.
+
+## Related
+
+- [Menubar](menubar.md): a bar of application menus, with the menu roles.
+- [Popover](popover.md): one popup anchored to its trigger.
+- [UI components](README.md): the approach, styling and the other components.

package/docs/number-field.md

@@ -0,0 +1,181 @@
+# Number Field
+
+> A number input with buttons to step it, after Base UI's NumberField and the APG spinbutton. Without `format` it is a native `<input type="number">`, which steps, validates and submits without JavaScript; with `format` (`Intl.NumberFormat` options: a currency, a percentage, grouping) it shows the formatted number, reads what is typed back in the same locale, and a hidden input submits the number. `<lu-number-field>`'s 2.6 kB script adds Page Up and Page Down, Home and End, press-and-hold buttons, a scrub area, the wheel when asked, and commit-time clamping. `bind:value` keeps a signal in sync.
+
+```ts
+import { NumberField } from "@lumiose/ui"; // or "@lumiose/ui/number-field"
+import "@lumiose/ui/number-field.css"; // or "@lumiose/ui/styles.css" for every component
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<NumberField.Root>
+  <NumberField.ScrubArea />
+  <NumberField.Group>
+    <NumberField.Decrement />
+    <NumberField.Input />
+    <NumberField.Increment />
+  </NumberField.Group>
+</NumberField.Root>
+```
+
+| Part        | Renders                                                                                                                           |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `Root`      | `<lu-number-field>` with the range and format as attributes, and an `<input type="hidden">` that submits the number with `format` |
+| `ScrubArea` | `<span data-scrub>`: dragging across it steps the number (usually around the label)                                               |
+| `Group`     | `<div>` around the input and the buttons                                                                                          |
+| `Input`     | `<input type="number" inputmode min max step>`, or with `format` `<input type="text" role="spinbutton" aria-value…>`              |
+| `Increment` | `<button type="button" tabindex="-1" aria-label="Increase" aria-controls="…">`, disabled at `max`                                 |
+| `Decrement` | `<button type="button" tabindex="-1" aria-label="Decrease" aria-controls="…">`, disabled at `min`                                 |
+
+Name the field with a [Field](field.md) (`Field.Label`), a `<label for>` the Root's `id`, or an
+`aria-label` on the `Input`.
+
+## API
+
+### NumberField.Root
+
+| Prop                               | Type                              | Default       |                                                                                                                                                                         |
+| ---------------------------------- | --------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`                            | `number \| null`                  |               | Shows this number (`null`: empty) when it changes. Pair it with `onValueChange`.                                                                                        |
+| `defaultValue`                     | `number \| null`                  | `null`        | The number at first; a form reset goes back to it.                                                                                                                      |
+| `onValueChange`                    | `(value: number \| null) => void` |               | Called as the number changes: typing, a key, a button, the wheel, a drag.                                                                                               |
+| `onValueCommitted`                 | `(value: number \| null) => void` |               | Called when a change is done: the input left, a key pressed, a button or a drag released.                                                                               |
+| `bind:value`                       | `Signal<number \| null>`          |               | Stands in for `value` and `onValueChange`.                                                                                                                              |
+| `min`, `max`                       | `number`                          |               | The range. A typed number outside it becomes its end when committed.                                                                                                    |
+| `step`                             | `number`                          | `1`           | The step of the arrow keys, the buttons, the wheel and a drag.                                                                                                          |
+| `largeStep`                        | `number`                          | `10`          | The step of Page Up, Page Down, and Shift with an arrow key or a button.                                                                                                |
+| `smallStep`                        | `number`                          | `0.1`         | The step of Alt with an arrow key or a button.                                                                                                                          |
+| `snapOnStep`                       | `boolean`                         | `false`       | A step lands on the next multiple of its size (from `min`, or 0): 1.3 steps up to 2, not 2.3.                                                                           |
+| `format`                           | `Intl.NumberFormatOptions`        |               | How the number is shown; with it, the input is a text field and a hidden input submits the number. Options or a `locale` the browser refuses fall back to its defaults. |
+| `locale`                           | `string`                          | the browser's | The locale of the formatted number (the server's in server HTML).                                                                                                       |
+| `allowWheelScrub`                  | `boolean`                         | `false`       | The wheel steps the number while the input has focus and the pointer is over it.                                                                                        |
+| `allowOutOfRange`                  | `boolean`                         | `false`       | Typed numbers outside the range stay as typed, for the browser's validation to report.                                                                                  |
+| `name`, `form`                     | `string`                          |               | The name the number is submitted under, and the id of its form when it is outside it.                                                                                   |
+| `id`                               | `string`                          | generated     | The input's id, for a `<label for>`.                                                                                                                                    |
+| `required`, `disabled`, `readOnly` | `boolean`                         | `false`       | As on a native input; read-only and disabled fields' buttons are disabled.                                                                                              |
+
+### NumberField.ScrubArea
+
+| Prop               | Type                         | Default        |                                                              |
+| ------------------ | ---------------------------- | -------------- | ------------------------------------------------------------ |
+| `direction`        | `"horizontal" \| "vertical"` | `"horizontal"` | The drag that changes the number: right goes up, or up does. |
+| `pixelSensitivity` | `number`                     | `2`            | How many pixels of drag make one step.                       |
+
+### The other parts
+
+`Group` takes `<div>` props. `Input` takes `<input>` props except the range's own (`type`, `value`,
+`min`, `max`, `step`, `name`, `required`, `readonly`, `id`: the Root's). `Increment` and
+`Decrement` take `<button>` props; give them an `aria-label` in the page's language. Inside a
+[Field](field.md), the input takes the field's id, name, description and error.
+
+**Native or formatted.** A native number input cannot show grouping, a currency or a percentage,
+and reads a typed number in the browser's own way, so a formatted field is a text field with the
+spinbutton role, and the number it submits sits in a hidden input. The native input is the default
+because it needs no JavaScript: typing, the arrow keys, `min`, `max` and `step` validation and the
+form value are the browser's.
+
+With `snapOnStep`, each kind of step snaps to its own size: Shift steps 37 up to 40, Alt steps
+1.37 up to 1.4. A native field (no `format`) validates the value against `step` without
+JavaScript; the script sets its `step` to `any`, so the values Alt's small step, Home, End and
+clamping give always submit.
+
+The keyboard: `inputmode="decimal"` when `min` is 0 or more, `"text"` otherwise, since iOS's
+decimal keyboard has no minus sign. Digits of other scripts (full-width `１`, Arabic-Indic `٤`) are
+read as numbers.
+
+**Differences from Base UI's NumberField.** No `ScrubAreaCursor`: Base UI draws a cursor because
+its scrub area locks the pointer (which hides the real one); this scrub area keeps the real cursor
+(a resize cursor), so a drag stops at the screen's edge. No `inputRef`, no `render`. `locale` is a
+string, written to the element for its script.
+
+## Example
+
+```tsx check
+import { NumberField } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function PriceField() {
+  const price = signal<number | null>(19.9);
+  return (
+    <NumberField.Root
+      id="price"
+      name="price"
+      bind:value={price}
+      min={0}
+      step={0.5}
+      format={{ style: "currency", currency: "EUR" }}
+      class="lu-number-field"
+    >
+      <NumberField.ScrubArea>
+        <label for="price">Price</label>
+      </NumberField.ScrubArea>
+      <NumberField.Group>
+        <NumberField.Decrement aria-label="Lower the price">−</NumberField.Decrement>
+        <NumberField.Input />
+        <NumberField.Increment aria-label="Raise the price">+</NumberField.Increment>
+      </NumberField.Group>
+    </NumberField.Root>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-number-field` on `Root`: the label above one bordered group,
+the input centred between two 36px buttons that dim at the ends of the range, and a focus ring
+around the whole group.
+
+**With your own CSS**, style the parts through `class`, the input's `:focus-visible`, the buttons'
+`:disabled` and `[data-action="increment"]` / `[data-action="decrement"]`, the scrub area's
+`[data-scrub]`, and `lu-number-field[data-scrubbing]` while a drag is on.
+
+`@lumiose/ui/number-field.css` (0.2 kB brotli) hides the native spinners once the script runs
+(`:defined`) and hides the buttons until then, keeps held buttons from selecting text, and gives a
+scrub area its resize cursor and `touch-action: none`.
+
+## Keyboard and focus
+
+| Key                     | Does                                                                      |
+| ----------------------- | ------------------------------------------------------------------------- |
+| Arrow Up / Arrow Down   | One step up or down.                                                      |
+| Shift + Arrow Up / Down | `largeStep` up or down.                                                   |
+| Alt + Arrow Up / Down   | `smallStep` up or down.                                                   |
+| Page Up / Page Down     | `largeStep` up or down.                                                   |
+| Home / End              | `min` or `max`, when set.                                                 |
+| Enter                   | Commits the typed number (clamped, formatted); a form submits.            |
+| Tab                     | Moves on: one tab stop, the input (the buttons are not in the tab order). |
+
+Right to left, dragging the scrub area toward the left steps up, as a slider runs. A press on a
+button steps once (by `largeStep` with Shift, `smallStep` with Alt) and, with a mouse, puts focus
+in the input, so the arrow keys go on stepping (a touch leaves focus where it is, so no virtual
+keyboard opens); holding it steps again every 60 ms after 400 ms. A click from a keyboard or a screen reader on a button steps once. Every drag (the
+scrub area) has the arrow keys as its alternative (WCAG 2.5.7). The wheel steps the number only
+with `allowWheelScrub`, while the input has focus and the pointer is over it; otherwise the wheel
+scrolls the page, as over any field (Chromium's own stepping of a focused number input is turned
+off). Ctrl with the wheel zooms the page, and a sideways swipe never steps. Text that is no number
+(Firefox lets letters into a number input) goes on commit, and the last number comes back.
+
+## Without JavaScript, and the element's script
+
+Without `format`, the native number input works and submits with no script; the buttons, which
+need it, stay hidden and the native spinners show. With `format`, the text input submits its text
+as typed until the script moves the name to the hidden input, so a form that must work without
+JavaScript should leave `format` out.
+
+`<lu-number-field>`'s script (2.6 kB brotli) adds the large step, Home and End, the buttons, the
+scrub area and the wheel, clamps and formats on commit, keeps the hidden input, `aria-valuenow`
+and `aria-valuetext` current, and follows a form reset.
+
+## Browser support
+
+Native number inputs and `Intl.NumberFormat` (with `formatToParts`): every supported browser.
+Scrubbing uses pointer capture, without pointer lock.
+
+## Related
+
+- [Field](field.md): a label, a description and errors for a number field.
+- [Slider](slider.md): a number picked by dragging along a range.
+- [Input](input.md): any other text.