@antadesign/anta 0.3.25 → 0.3.27

package/docs/components/menu.md

@@ -366,6 +366,8 @@ chevron stay centered on the row, so it composes with a trailing counter.
 </Menu>
 ```
 
+## MenuItemCopy
+
 `MenuItemCopy` is a row that copies to the clipboard when chosen: `copy` for a
 string, `copyNode` for a DOM region, or `copyUrl` for the current URL. It composes
 a `<MenuItem>` with a slotted `<a-copy>` element that performs the write, and
@@ -390,89 +392,32 @@ navigating links.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children?` | ReactNode | — | Item content. With `label` set, children are extra content — most
- notably the nested `<Menu>` for a submenu parent. |
+| `children?` | ReactNode | — | Item content. With `label` set, children are extra content — most notably the nested `<Menu>` for a submenu parent. |
 | `copiedLabel?` | string | Copied | Text in the successful no-icon confirmation. |
 | `copy?` | string | — | Text copied to the clipboard on activation. |
-| `copyNode?` | boolean \| string | — | Copy a DOM node as rich text (`text/html`) + plain text. `true` copies
- the nearest ancestor marked `data-copy-source`; a string is a CSS
- selector for an ancestor region (`closest`). The copy control is stripped
- from the copied output. |
+| `copyNode?` | boolean \| string | — | Copy a DOM node as rich text (`text/html`) + plain text. `true` copies the nearest ancestor marked `data-copy-source`; a string is a CSS selector for an ancestor region (`closest`). The copy control is stripped from the copied output. |
 | `copyUrl?` | true | — | Copy the current page URL (`location.href`). |
 | `copyWithUrl?` | boolean | — | Prefix the copied text with `// URL: <current page URL>`. |
-| `disabled?` | boolean | — | Disable the item: greyed out, not focusable for activation, no close. A
- disabled link also drops its `href`, so it can't navigate. |
-| `hint?` | ReactNode | — | Secondary text under the label — explanatory copy, like `RadioGroup`'s
- option `hint`. Requires `label` (it stacks in a column beneath it). Muted
- (`--text-3`) and tracks the row's `tone`. A string, or any node. |
+| `disabled?` | boolean | — | Disable the item: greyed out, not focusable for activation, no close. A disabled link also drops its `href`, so it can't navigate. |
+| `hint?` | ReactNode | — | Secondary text under the label — explanatory copy, like `RadioGroup`'s option `hint`. Requires `label` (it stacks in a column beneath it). Muted (`--text-3`) and tracks the row's `tone`. A string, or any node. |
 | `icon?` | IconShape | — | Leading icon shape. |
-| `iconPlacement?` | 'leading' \| 'trailing' \| 'none' | 'leading' | Where the copy glyph sits relative to the label — or `'none'` to omit it.
- Without a glyph, a successful copy shows a confirmation label near the
- pointer and leaves the row unchanged. |
-| `iconTrailing?` | IconShape | — | A trailing icon. On a `submenu` item this **overrides** the default
- chevron (omit it to keep the chevron); on a normal item it's the trailing
- glyph (omit for none). |
-| `indeterminate?` | boolean | — | Only meaningful with `selectionIndicator="checkbox"`: render the box in the
- mixed state (`aria-checked="mixed"`) — e.g. a "Select all" row when some but
- not all of its options are selected. |
-| `indicator?` | React.ReactNode | — | Replace the built-in selection-indicator *visual* with your own node,
- rendered at the **leading** edge (where the checkbox / radio sit). Pair with
- `selectionIndicator` to keep the semantics — the row stays the control and
- carries `role` + `aria-checked`; only the drawn mark changes. Suppresses the
- built-in checkbox / radio and the trailing `check` glyph. The node is made
- passive (aria-hidden, no pointer events) so the row receives the click. |
-| `kbd?` | string | — | Trailing shortcut hint, e.g. `"⌘E"`. Anta translates it to
- `aria-keyshortcuts` and hides the visual glyphs from assistive technology.
- Use `+` within a chord and spaces between shortcuts (`"⌘K ⌘S"` becomes
- `"Meta+K Meta+S"`). Pass `aria-keyshortcuts` to override the translation.
- This does not bind the shortcut. |
-| `label?` | ReactNode | — | The item's text. Usually a string, but any node is accepted — e.g. a filtered
- `Select` bolds the matched substring. Omit and pass `children` for richer
- content. |
+| `iconPlacement?` | 'leading' \| 'trailing' \| 'none' | 'leading' | Where the copy glyph sits relative to the label — or `'none'` to omit it. Without a glyph, a successful copy shows a confirmation label near the pointer and leaves the row unchanged. |
+| `iconTrailing?` | IconShape | — | A trailing icon. On a `submenu` item this **overrides** the default chevron (omit it to keep the chevron); on a normal item it's the trailing glyph (omit for none). |
+| `indeterminate?` | boolean | — | Only meaningful with `selectionIndicator="checkbox"`: render the box in the mixed state (`aria-checked="mixed"`) — e.g. a "Select all" row when some but not all of its options are selected. |
+| `indicator?` | React.ReactNode | — | Replace the built-in selection-indicator *visual* with your own node, rendered at the **leading** edge (where the checkbox / radio sit). Pair with `selectionIndicator` to keep the semantics — the row stays the control and carries `role` + `aria-checked`; only the drawn mark changes. Suppresses the built-in checkbox / radio and the trailing `check` glyph. The node is made passive (aria-hidden, no pointer events) so the row receives the click. |
+| `kbd?` | string | — | Trailing shortcut hint, e.g. `"⌘E"`. Anta translates it to `aria-keyshortcuts` and hides the visual glyphs from assistive technology. Use `+` within a chord and spaces between shortcuts (`"⌘K ⌘S"` becomes `"Meta+K Meta+S"`). Pass `aria-keyshortcuts` to override the translation. This does not bind the shortcut. |
+| `label?` | ReactNode | — | The item's text. Usually a string, but any node is accepted — e.g. a filtered `Select` bolds the matched substring. Omit and pass `children` for richer content. |
 | `onCopied?` | (ok) => void | — | Fires after the copy attempt with whether it succeeded. |
-| `onCopyRequest?` | () => void | — | Refresh a dynamic `copy` value before activation. Set the new string in
- application state so the next render updates `copy`. Return values are
- ignored. Fires on pointerdown and Enter/Space keydown. |
-| `onMouseDown?` | (event) => void | — | Raw `mousedown` on the row. Mainly to `preventDefault()` so the row doesn't
- take focus on a mouse press — e.g. a combobox option keeping focus in its
- input field while the click still selects. |
-| `onSelect?` | (event, detail) => void | — | Activation handler — fires when *this* item is chosen (click / Enter /
- Space), unless it's `disabled`. It does **not** fire for a submenu parent
- (clicking that opens the flyout, which isn't a selection) nor for a
- selection bubbling up from a nested submenu. On a link item it fires
- alongside the navigation. Receives the event plus a `{ value, label }`
- detail. |
-| `role?` | string | — | ARIA role override. Defaults to the role implied by `selectionIndicator`
- (`menuitem` / `menuitemcheckbox` / `menuitemradio`); set it to reparent the
- row under a different container role — e.g. `option` inside a `listbox`. |
-| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is
- a persistent background tint, the same resting fill a pressed row shows —
- also the way to flag the current page on a link item. On a checkable row
- (`selectionIndicator` set) it instead drives the leading `checkbox` / `radio`
- indicator and the row's `aria-checked`. |
-| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' | — | Turn the row into a checkable item, driven by `selected` (the row stays the
- control and carries `aria-checked`):
- - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>`
-   (before `icon`); the tint is dropped (the box carries state).
- - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped.
- - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected
-   row *and* the background tint (the canonical single-select look).
- Omit for a plain row (the default). |
-| `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and
- `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the
- `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal
- CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose
- hue + chroma are kept while the lightness is pinned to match the brand text.
- `critical` is the destructive action; `neutral` (the default) is the standard
- gray. |
-| `toneSelected?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Like `tone`, but applied only while the row is `selected` — an unselected row
- stays neutral. The whole selected row (label, icon, tint, and the `checkbox` /
- `radio` indicator) takes the tone. Same value set as `tone`; on a selected row
- `toneSelected` wins over `tone` when both are set. |
-| `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail
- so a shared handler can tell which row was chosen without a per-item
- closure. |
+| `onCopyRequest?` | () => void | — | Refresh a dynamic `copy` value before activation. Set the new string in application state so the next render updates `copy`. Return values are ignored. Fires on pointerdown and Enter/Space keydown. |
+| `onMouseDown?` | (event) => void | — | Raw `mousedown` on the row. Mainly to `preventDefault()` so the row doesn't take focus on a mouse press — e.g. a combobox option keeping focus in its input field while the click still selects. |
+| `onSelect?` | (event, detail) => void | — | Activation handler — fires when *this* item is chosen (click / Enter / Space), unless it's `disabled`. It does **not** fire for a submenu parent (clicking that opens the flyout, which isn't a selection) nor for a selection bubbling up from a nested submenu. On a link item it fires alongside the navigation. Receives the event plus a `{ value, label }` detail. |
+| `role?` | string | — | ARIA role override. Defaults to the role implied by `selectionIndicator` (`menuitem` / `menuitemcheckbox` / `menuitemradio`); set it to reparent the row under a different container role — e.g. `option` inside a `listbox`. |
+| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is a persistent background tint, the same resting fill a pressed row shows — also the way to flag the current page on a link item. On a checkable row (`selectionIndicator` set) it instead drives the leading `checkbox` / `radio` indicator and the row's `aria-checked`. |
+| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' | — | Turn the row into a checkable item, driven by `selected` (the row stays the control and carries `aria-checked`): - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>` (before `icon`); the tint is dropped (the box carries state). - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped. - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected row *and* the background tint (the canonical single-select look). Omit for a plain row (the default). |
+| `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose hue + chroma are kept while the lightness is pinned to match the brand text. `critical` is the destructive action; `neutral` (the default) is the standard gray. |
+| `toneSelected?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Like `tone`, but applied only while the row is `selected` — an unselected row stays neutral. The whole selected row (label, icon, tint, and the `checkbox` / `radio` indicator) takes the tone. Same value set as `tone`; on a selected row `toneSelected` wins over `tone` when both are set. |
+| `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail so a shared handler can tell which row was chosen without a per-item closure. |
 
 ## Keyboard
 
@@ -506,6 +451,55 @@ call `event.preventDefault()` to keep the menu as-is (e.g. block a dismiss).
 Controlled, the menu never self-moves — apply `detail.next` to `open` to accept,
 or do nothing to reject. (Submenus are always uncontrolled, regardless of `open`.)
 
+## Menu props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `autoWidth?` | boolean | — | Size the menu to its content instead of flooring its width to the trigger. A root menu is never narrower than its trigger by default; set this for a content menu under a wide trigger (e.g. a calendar below a full-width field) so it wraps its content and left-aligns under the trigger. |
+| `children?` | ReactNode | — | The menu's contents: `MenuItem`, `MenuSeparator`, `MenuGroup`, or any custom element. |
+| `context?` | boolean | — | Open on right-click (the `contextmenu` event) of the trigger region instead of a left click, positioned at the pointer. |
+| `coord?` | boolean | — | Open at the pointer coordinates rather than aligned to the trigger box. Pairs naturally with `context`; on its own it positions a left-click menu at the cursor. |
+| `inset?` | number \| string | 4 | Inner inset for the scroll body and named header/footer content. A number is pixels; a CSS length string is used as written. |
+| `nohover?` | boolean | — | Submenu-only (a `<Menu>` nested inside a `MenuItem`); ignored on a root menu. Submenus open on hover by default (with intent timing) as well as on click — set `nohover` to make this submenu click-only. Hover-intent is mouse-only regardless: on touch (and pen) a submenu always opens on tap and stays open until dismissed. |
+| `offset?` | number | 4 | Gap in pixels between the trigger and the menu. |
+| `onactivedescendant?` | (e) => void | — | Combobox-mode cursor report (raw element event). Fires when the active option changes as arrow keys move the cursor while focus stays in a `[data-menu-search]` filter field; `detail.id` is the active option's `id` (`null` when none). The reactive layer that renders the field reflects this onto its `aria-activedescendant` — the element can't write that light-DOM attribute itself. Passed straight through to the element. |
+| `onStateChange?` | (event, detail) => void | — | Fired before the open state changes — on open, and on every dismiss (Esc, outside-click, scroll, selecting an item). `event` is the cancelable `statechange`; `detail.next`/`detail.prev` are the requested/previous open state (booleans). It's the declarative way to observe a menu, and the handler you pair with `open` to drive a controlled menu (apply `detail.next` to `open`). Uncontrolled, `event.preventDefault()` vetoes the transition (e.g. keep the menu open). |
+| `open?` | boolean | — | Controlled open state. Omit for the default **uncontrolled** menu (it opens/closes itself via its triggers). Pass a boolean to **control** it: the menu's visibility follows `open`, and user dismiss (Esc, outside-click, select) fires `onStateChange` *without* self-closing — you update `open` in response. Submenus are always uncontrolled regardless of this. See STATEFUL-COMPONENTS.md. |
+| `placement?` | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' \| 'bottom' \| 'top' \| 'right-start' \| 'right-end' \| 'left-start' \| 'left-end' \| 'right' \| 'left' | bottom-start | Preferred placement relative to the trigger. `bottom` / `top` place the menu below / above; `right` / `left` place it beside (like a submenu flyout). The cross-axis suffix (`-start` / `-end`) aligns the near / far edges, and no suffix centers on the trigger. The menu flips to the opposite side when the preferred one lacks room, and clamps to the viewport. |
+| `role?` | string | menu | ARIA role of the menu surface. |
+| `round?` | boolean \| number \| string | — | Round the menu: the container softens to a 20px radius and its items go fully round. A `number` (px) or CSS length string tunes the container radius only — items stay full pills. |
+| `stopPropagation?` | boolean \| string \| string[] | — | Contain events so they don't bubble out of the menu to ancestor handlers (e.g. a clickable row the menu sits in). Selecting an item is always contained; this extends it to whole event types. `true` contains `click`; pass an event name or list (`"click pointerdown"`) to contain those. |
+
+## MenuItem props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children?` | ReactNode | — | Item content. With `label` set, children are extra content — most notably the nested `<Menu>` for a submenu parent. |
+| `disabled?` | boolean | — | Disable the item: greyed out, not focusable for activation, no close. A disabled link also drops its `href`, so it can't navigate. |
+| `download?` | string \| boolean | — | Download the resource instead of navigating: `true` / `''` uses the resource's default filename, a string overrides it. |
+| `hint?` | ReactNode | — | Secondary text under the label — explanatory copy, like `RadioGroup`'s option `hint`. Requires `label` (it stacks in a column beneath it). Muted (`--text-3`) and tracks the row's `tone`. A string, or any node. |
+| `href?` | string | — | Renders the item as `<a role="menuitem" data-anta-menu-item href>`. |
+| `icon?` | IconShape | — | Leading icon shape. |
+| `iconTrailing?` | IconShape | — | A trailing icon. On a `submenu` item this **overrides** the default chevron (omit it to keep the chevron); on a normal item it's the trailing glyph (omit for none). |
+| `indeterminate?` | boolean | — | Only meaningful with `selectionIndicator="checkbox"`: render the box in the mixed state (`aria-checked="mixed"`) — e.g. a "Select all" row when some but not all of its options are selected. |
+| `indicator?` | React.ReactNode | — | Replace the built-in selection-indicator *visual* with your own node, rendered at the **leading** edge (where the checkbox / radio sit). Pair with `selectionIndicator` to keep the semantics — the row stays the control and carries `role` + `aria-checked`; only the drawn mark changes. Suppresses the built-in checkbox / radio and the trailing `check` glyph. The node is made passive (aria-hidden, no pointer events) so the row receives the click. |
+| `kbd?` | string | — | Trailing shortcut hint, e.g. `"⌘E"`. Anta translates it to `aria-keyshortcuts` and hides the visual glyphs from assistive technology. Use `+` within a chord and spaces between shortcuts (`"⌘K ⌘S"` becomes `"Meta+K Meta+S"`). Pass `aria-keyshortcuts` to override the translation. This does not bind the shortcut. |
+| `label?` | ReactNode | — | The item's text. Usually a string, but any node is accepted — e.g. a filtered `Select` bolds the matched substring. Omit and pass `children` for richer content. |
+| `onMouseDown?` | (event) => void | — | Raw `mousedown` on the row. Mainly to `preventDefault()` so the row doesn't take focus on a mouse press — e.g. a combobox option keeping focus in its input field while the click still selects. |
+| `onSelect?` | (event, detail) => void | — | Activation handler — fires when *this* item is chosen (click / Enter / Space), unless it's `disabled`. It does **not** fire for a submenu parent (clicking that opens the flyout, which isn't a selection) nor for a selection bubbling up from a nested submenu. On a link item it fires alongside the navigation. Receives the event plus a `{ value, label }` detail. |
+| `ping?` | string | — | Space-separated URLs the browser pings on navigation. |
+| `rel?` | string | — | Anchor rel. |
+| `role?` | string | — | ARIA role override. Defaults to the role implied by `selectionIndicator` (`menuitem` / `menuitemcheckbox` / `menuitemradio`); set it to reparent the row under a different container role — e.g. `option` inside a `listbox`. |
+| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is a persistent background tint, the same resting fill a pressed row shows — also the way to flag the current page on a link item. On a checkable row (`selectionIndicator` set) it instead drives the leading `checkbox` / `radio` indicator and the row's `aria-checked`. |
+| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' | — | Turn the row into a checkable item, driven by `selected` (the row stays the control and carries `aria-checked`): - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>` (before `icon`); the tint is dropped (the box carries state). - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped. - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected row *and* the background tint (the canonical single-select look). Omit for a plain row (the default). |
+| `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
+| `target?` | string | — | Anchor target, e.g. `'_blank'`. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose hue + chroma are kept while the lightness is pinned to match the brand text. `critical` is the destructive action; `neutral` (the default) is the standard gray. |
+| `toneSelected?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Like `tone`, but applied only while the row is `selected` — an unselected row stays neutral. The whole selected row (label, icon, tint, and the `checkbox` / `radio` indicator) takes the tone. Same value set as `tone`; on a selected row `toneSelected` wins over `tone` when both are set. |
+| `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail so a shared handler can tell which row was chosen without a per-item closure. |
+
+## Web Component
+
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 Put a focusable trigger immediately before `<a-menu>` and omit `state` for an
@@ -522,6 +516,8 @@ values.
 </a-menu>
 ```
 
+## Styling
+
 The popover surface lives in shadow DOM and is exposed as a **part** — style its
 chrome (background, frost, border, radius, shadow, padding, min-width) with
 `::part(menu)`. Menu items are light DOM, so style them (and their

package/docs/components/progress.md

@@ -92,25 +92,19 @@ works for one at the bottom.
 `round` makes the track fully round. Pass a number or CSS length for a custom
 radius.
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `hint?` | string | — | Right-aligned hint text (e.g. "3 of 7"). Like `label`, it's not rendered
- when custom `children` are provided but still feeds the accessible name. |
-| `label?` | string | — | Text label displayed after the percentage, or on its own for
- indeterminate progress. When you provide custom `children` (which replace
- the default label row), `label` is no longer rendered — but it still
- supplies the progressbar's accessible name. |
+| `hint?` | string | — | Right-aligned hint text (e.g. "3 of 7"). Like `label`, it's not rendered when custom `children` are provided but still feeds the accessible name. |
+| `label?` | string | — | Text label displayed after the percentage, or on its own for indeterminate progress. When you provide custom `children` (which replace the default label row), `label` is no longer rendered — but it still supplies the progressbar's accessible name. |
 | `max?` | number | 100 | Upper bound of the range. |
-| `round?` | boolean \| number \| string | — | Fully-round track (`border-radius: 999px`); the fill is clipped to it. Pass a
- `number` (px) or a CSS length string for a custom radius. |
+| `round?` | boolean \| number \| string | — | Fully-round track (`border-radius: 999px`); the fill is clipped to it. Pass a `number` (px) or a CSS length string for a custom radius. |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. Scales the track and the default label row together. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color variant, or any literal CSS color for a one-off custom tone (the
- surface / indicator / text are derived from it in oklch). Named tones track
- light/dark automatically. |
-| `value?` | number \| false | — | Current progress value. Omit this prop, or pass `false`, to show
-indeterminate progress. Negative values are clamped to 0. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color variant, or any literal CSS color for a one-off custom tone (the surface / indicator / text are derived from it in oklch). Named tones track light/dark automatically. |
+| `value?` | number \| false | — | Current progress value. Omit this prop, or pass `false`, to show indeterminate progress. Negative values are clamped to 0. |
+
+## Web Component
 
 ```html
 <a-progress style="width: 100%" value="42" max="100" tone="info" role="progressbar"
@@ -158,6 +152,8 @@ is absent, while using Anta's track, fill, tone, and size treatments. Native
 progress does not render Anta's label or hint structure; give it an accessible
 name instead.
 
+## Styling
+
 ```css
 /* a fancy bar: rounded track (all sides), a multi-stop gradient fill with a glow,
    and a crisp hard right edge (the default soft right-edge fade is cleared). */

package/docs/components/radio.md

@@ -250,50 +250,29 @@ element — `Input`, and the composed `Select` — skip it and expose only
 <RadioGroup onValueChange={(_e, { value }) => save(value)} options={…} />
 ```
 
+## RadioGroup props
+
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `options` | RadioOption[] | — | The options. The wrapper renders one `<a-radio>` per entry and computes its
- `selected` / roving `tabindex` / `role` declaratively. |
+| `options` | RadioOption[] | — | The options. The wrapper renders one `<a-radio>` per entry and computes its `selected` / roving `tabindex` / `role` declaratively. |
 | `defaultValue?` | string | — | Initial selected value for uncontrolled use. |
 | `disabled?` | boolean | — | Disable the whole group. |
-| `hint?` | string | — | Plain-text description for the group, rendered directly under `label` (above
- the options) — typically instructional copy. Per-option helper text goes on
- the option's own `hint` instead. |
+| `hint?` | string | — | Plain-text description for the group, rendered directly under `label` (above the options) — typically instructional copy. Per-option helper text goes on the option's own `hint` instead. |
 | `label?` | string | — | Plain-text label for the whole group, rendered above the options. |
-| `name?` | string | — | Form field name — the group submits one `name=value` (it's the
- form-associated element). |
+| `name?` | string | — | Form field name — the group submits one `name=value` (it's the form-associated element). |
 | `onBlur?` | (event) => void | — | Fired when focus leaves the group entirely — wired to `focusout`. |
-| `onChange?` | (event) => void | — | Fired *after* the selection changes — a native `change` event (the post-apply
- counterpart to `onStateChange`). Not cancelable; for a controlled group it
- fires once you've updated `value`. |
-| `onFocus?` | (event) => void | — | Fired when focus enters the group (any option) — wired to `focusin`, since
- focus lands on an individual option, not the group element itself. |
-| `onStateChange?` | (event, detail) => void | — | Fired whenever selection changes — event-first. `detail` is
- `{ next, prev, reason }`: `next`/`prev` are values (`null` = nothing selected);
- `reason` is `'user'` \| `'reset'` \| `'restore'`. A `'user'` pick fires *before*
- applying and is **cancelable** — `event.preventDefault()` vetoes it
- (uncontrolled), or in controlled mode answer by updating `value` (reject by
- doing nothing). `'reset'` (form reset) and `'restore'` (bfcache / autofill) are
- not cancelable — filter on `reason` if you only track user picks. |
-| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value, name }` snapshot as the second argument,
- matching `Input`. |
+| `onChange?` | (event) => void | — | Fired *after* the selection changes — a native `change` event (the post-apply counterpart to `onStateChange`). Not cancelable; for a controlled group it fires once you've updated `value`. |
+| `onFocus?` | (event) => void | — | Fired when focus enters the group (any option) — wired to `focusin`, since focus lands on an individual option, not the group element itself. |
+| `onStateChange?` | (event, detail) => void | — | Fired whenever selection changes — event-first. `detail` is `{ next, prev, reason }`: `next`/`prev` are values (`null` = nothing selected); `reason` is `'user'` \| `'reset'` \| `'restore'`. A `'user'` pick fires *before* applying and is **cancelable** — `event.preventDefault()` vetoes it (uncontrolled), or in controlled mode answer by updating `value` (reject by doing nothing). `'reset'` (form reset) and `'restore'` (bfcache / autofill) are not cancelable — filter on `reason` if you only track user picks. |
+| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value, name }` snapshot as the second argument, matching `Input`. |
 | `orientation?` | 'vertical' \| 'horizontal' | 'vertical' | Layout + arrow-key axis. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size applied to every option (an option's own `size` wins). |
-| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | 'neutral' | Validation/feedback tone for the group `hint` — recolors it (same tone set
- as `Input`'s `status`). Use `critical` for an error message, etc.; omit for
- the neutral default. |
-| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Mark tone applied to every option (an option's own `tone` wins), or any literal
- CSS color for a one-off custom tone. Colors the selected-ring fill + dot *and*
- the unselected ring border. Named tones track light/dark mode. Use `toneSelected`
- instead to tone only the selected option and leave the rest neutral. The option
- text stays neutral — recolor it in plain CSS via the `--text-N-{tone}` tokens. |
-| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Like `tone`, but colored onto the **selected option only** — every unselected
- ring stays neutral grey. Applied to every option (an option's own `toneSelected`
- wins). Prefer this over `tone` when a resting tinted border would read as a
- validation state. |
-| `value?` | string | — | Controlled selected value. The group follows this prop and reports a
- requested change through `onStateChange`. Leave it undefined for
- uncontrolled use. |
+| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | 'neutral' | Validation/feedback tone for the group `hint` — recolors it (same tone set as `Input`'s `status`). Use `critical` for an error message, etc.; omit for the neutral default. |
+| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Mark tone applied to every option (an option's own `tone` wins), or any literal CSS color for a one-off custom tone. Colors the selected-ring fill + dot *and* the unselected ring border. Named tones track light/dark mode. Use `toneSelected` instead to tone only the selected option and leave the rest neutral. The option text stays neutral — recolor it in plain CSS via the `--text-N-{tone}` tokens. |
+| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Like `tone`, but colored onto the **selected option only** — every unselected ring stays neutral grey. Applied to every option (an option's own `toneSelected` wins). Prefer this over `tone` when a resting tinted border would read as a validation state. |
+| `value?` | string | — | Controlled selected value. The group follows this prop and reports a requested change through `onStateChange`. Leave it undefined for uncontrolled use. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -326,6 +305,8 @@ treatments.
 </div>
 ```
 
+## Styling
+
 Reach for the props first: **`tone`** colors the mark in every state,
 **`toneSelected`** only the selected option (any CSS color for a custom tone, set on
 the group or a single option — derives the full curve in oklch), **`size`** the

package/docs/components/select-faceted.md

@@ -358,7 +358,7 @@ const recency: SelectFacetCustom<Recency> = {
 // concrete date (or take the day as-is) and filter your rows with it
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -370,33 +370,15 @@ const recency: SelectFacetCustom<Recency> = {
 | `icon?` | IconShape | filter | Default trigger's leading icon. |
 | `label?` | string | Filter | Default trigger's button label. |
 | `offset?` | number | 4 | Gap in pixels between the trigger and the filter menu. |
-| `onValueChange?` | (value, attrs) => void | — | Fires after any facet changes. `value` is the whole new record (a facet key →
- that facet's value; a cleared facet is absent). `attrs` says what changed:
- `{ facet, kind, value }` for a single facet edit, or `{ all: true }` for the
- "Clear all" row — narrow on `'all' in attrs` before reading `facet`. |
-| `placement?` | 'left' \| 'right' \| 'bottom' \| 'top' \| 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'left-start' \| 'left-end' | bottom-start | Preferred placement of the root filter menu relative to its trigger. The
- menu auto-flips vertically and clamps horizontally when needed. |
+| `onValueChange?` | (value, attrs) => void | — | Fires after any facet changes. `value` is the whole new record (a facet key → that facet's value; a cleared facet is absent). `attrs` says what changed: `{ facet, kind, value }` for a single facet edit, or `{ all: true }` for the "Clear all" row — narrow on `'all' in attrs` before reading `facet`. |
+| `placement?` | 'left' \| 'right' \| 'bottom' \| 'top' \| 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'left-start' \| 'left-end' | bottom-start | Preferred placement of the root filter menu relative to its trigger. The menu auto-flips vertically and clamps horizontally when needed. |
 | `priority?` | 'primary' \| 'secondary' | secondary | Default trigger's button priority. |
-| `renderTrigger?` | (state) => ReactNode | — | Replaces the default `Button` with a trigger returned from this function.
- Receives a `SelectFacetedTriggerState`. Return exactly one focusable element:
- the menu is positioned relative to that element and opens when it is clicked.
- Add `aria-haspopup="menu"` and `aria-expanded={state.open}` to the returned
- element, on a role that supports them (an Anta `Button` already carries
- `role="button"`; otherwise add `role="combobox"`). `className`, `style`, and
- other trigger props apply only to the default Button, so add styling and
- attributes to the returned element. |
-| `searchable?` | boolean | — | Adds a search field at the top of the root menu. It searches the options of
- every `single` and `multiple` facet in one list. For example, "alice" can
- appear under application-defined Assignee and Owner facets. `text` and
- `custom` facets remain available when the search is empty. Each facet uses
- its `filter` function when supplied, or the built-in substring match. |
+| `renderTrigger?` | (state) => ReactNode | — | Replaces the default `Button` with a trigger returned from this function. Receives a `SelectFacetedTriggerState`. Return exactly one focusable element: the menu is positioned relative to that element and opens when it is clicked. Add `aria-haspopup="menu"` and `aria-expanded={state.open}` to the returned element, on a role that supports them (an Anta `Button` already carries `role="button"`; otherwise add `role="combobox"`). `className`, `style`, and other trigger props apply only to the default Button, so add styling and attributes to the returned element. |
+| `searchable?` | boolean | — | Adds a search field at the top of the root menu. It searches the options of every `single` and `multiple` facet in one list. For example, "alice" can appear under application-defined Assignee and Owner facets. `text` and `custom` facets remain available when the search is empty. Each facet uses its `filter` function when supplied, or the built-in substring match. |
 | `searchPlaceholder?` | string | Filter… | Placeholder for the global search field. |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Default trigger's button size. |
-| `toneSelected?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | — | Tone applied to a selected option row in the facet flyouts (label, selected
- tint, and the check / checkbox indicator). A named tone or a custom CSS
- color, matching `Select`'s `toneSelected`. Defaults to a neutral selection. |
-| `value?` | SelectFacetedValue | — | Controlled value record, keyed by facet. When provided, update it through
- `onValueChange`. Leave it undefined for uncontrolled use. |
+| `toneSelected?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | — | Tone applied to a selected option row in the facet flyouts (label, selected tint, and the check / checkbox indicator). A named tone or a custom CSS color, matching `Select`'s `toneSelected`. Defaults to a neutral selection. |
+| `value?` | SelectFacetedValue | — | Controlled value record, keyed by facet. When provided, update it through `onValueChange`. Leave it undefined for uncontrolled use. |
 
 ### The `SelectFacet` type
 

package/docs/components/select.md

@@ -623,117 +623,40 @@ sections is one pick (dev builds warn).
 groups (their label becomes the heading) and drops empty ones, so results read as one
 scannable list instead of hiding matches behind flyouts.
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `options` | SelectItem[] | — | The options to choose from — bare strings, `SelectOption` objects, `SelectGroup`s
- (inline titled sections), or `SelectSubmenu`s (flyout branches). Groups and
- submenus nest and mix with plain options. Selection stays global (one `value`,
- leaf options only); a filter query flattens the tree into grouped results.
-
- `Select` infers its value type `V` from these options: `{ value: 365 }` makes
- `onValueChange` report `number`. A mix of value types widens `V` to the union.
-
- Each leaf `value` is the option's identity and must be **unique across the whole
- tree** (selection is value-keyed, so a value repeated in two sections is one logical
- pick: both rows toggle together, the trigger resolves to the last). Values that
- stringify alike (`365` and `"365"`) also collide as row keys; dev builds
- `console.warn` on either. |
-| `clearable?` | boolean | — | Add a "Clear" row pinned in the menu **footer** that empties the selection
- (single → none, multiple → `[]`). Shown only while something is selected, so
- it never scrolls away in a long or filtered list. |
+| `options` | SelectItem[] | — | The options to choose from — bare strings, `SelectOption` objects, `SelectGroup`s (inline titled sections), or `SelectSubmenu`s (flyout branches). Groups and submenus nest and mix with plain options. Selection stays global (one `value`, leaf options only); a filter query flattens the tree into grouped results. `Select` infers its value type `V` from these options: `{ value: 365 }` makes `onValueChange` report `number`. A mix of value types widens `V` to the union. Each leaf `value` is the option's identity and must be **unique across the whole tree** (selection is value-keyed, so a value repeated in two sections is one logical pick: both rows toggle together, the trigger resolves to the last). Values that stringify alike (`365` and `"365"`) also collide as row keys; dev builds `console.warn` on either. |
+| `clearable?` | boolean | — | Add a "Clear" row pinned in the menu **footer** that empties the selection (single → none, multiple → `[]`). Shown only while something is selected, so it never scrolls away in a long or filtered list. |
 | `clearLabel?` | string | Clear | Label for the `clearable` footer row. |
 | `defaultValue?` | V \| V[] | — | Initial selected option value for uncontrolled use. |
 | `disabled?` | boolean | — | Disable the whole select. |
-| `filter?` | boolean \| (option, query) => boolean | — | Add a search field at the top of the menu that filters the options as you
- type. `true` uses the built-in matcher — a case-insensitive substring of the
- option's **value / label / hint**. Pass a **function** `(option, query) =>
- boolean` for custom matching (called per option; return `true` to keep it). |
+| `filter?` | boolean \| (option, query) => boolean | — | Add a search field at the top of the menu that filters the options as you type. `true` uses the built-in matcher — a case-insensitive substring of the option's **value / label / hint**. Pass a **function** `(option, query) => boolean` for custom matching (called per option; return `true` to keep it). |
 | `hint?` | string | — | Helper text under the field (Input's `hint`). |
-| `icon?` | IconShape | — | Leading icon shown at the left of the field (the default trigger's `Input`
- `leading` slot). With a custom `renderTrigger`, it's passed through as
- `state.icon` instead — the consumer places it. |
-| `indicator?` | 'none' \| 'check' \| 'radio' | none | The per-row mark for **single**-select: `'none'` (a tint-only highlight),
- `'check'` (a trailing checkmark on the selected row, keeping the tint — the
- canonical Select look), or `'radio'` (a leading radio on every row).
- Multi-select always uses checkboxes. |
+| `icon?` | IconShape | — | Leading icon shown at the left of the field (the default trigger's `Input` `leading` slot). With a custom `renderTrigger`, it's passed through as `state.icon` instead — the consumer places it. |
+| `indicator?` | 'none' \| 'check' \| 'radio' | none | The per-row mark for **single**-select: `'none'` (a tint-only highlight), `'check'` (a trailing checkmark on the selected row, keeping the tint — the canonical Select look), or `'radio'` (a leading radio on every row). Multi-select always uses checkboxes. |
 | `label?` | string | — | Field label, above the trigger (Input's `label`). |
-| `leading?` | ReactNode | — | Content for the default trigger's `leading` slot, such as a key prefix
- before the value. It replaces the icon derived from `icon`. Include an
- `<Icon>` in this content when both are needed. Ignored by `renderTrigger`. |
+| `leading?` | ReactNode | — | Content for the default trigger's `leading` slot, such as a key prefix before the value. It replaces the icon derived from `icon`. Include an `<Icon>` in this content when both are needed. Ignored by `renderTrigger`. |
 | `offset?` | number | 4 | Gap in pixels between the trigger and the options menu. |
-| `onValueChange?` | (value, attrs) => void | — | Fires after the selection changes, with the new value and a
- `{ value, option }` snapshot. Select has no discrete element state, so
- there is no cancelable `onStateChange` (see the Input event-model note). |
+| `onValueChange?` | (value, attrs) => void | — | Fires after the selection changes, with the new value and a `{ value, option }` snapshot. Select has no discrete element state, so there is no cancelable `onStateChange` (see the Input event-model note). |
 | `placeholder?` | string | — | Text shown when nothing is selected. |
-| `placement?` | 'left' \| 'right' \| 'bottom' \| 'top' \| 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'left-start' \| 'left-end' | bottom-start | Preferred placement of the options menu relative to the trigger. The menu
- auto-flips vertically and clamps horizontally when needed. |
-| `renderEmpty?` | (state) => ReactNode | — | Render content in the menu body when the (filtered) option list is empty —
- a "no results" message, a loading indicator (gated on your own external
- loading state), or a "create from the query" row. Receives an `EmptyState`
- (`query`, trimmed). There is no built-in empty message: when omitted, an empty
- list renders nothing. Whatever you return goes where the option rows would —
- a plain node is inert; return a `MenuItem` (e.g. a "Create" row) to make it
- focusable and selectable. |
-| `renderIndicator?` | (state) => ReactNode | — | Replace each row's selection **mark** with your own node, drawn at the
- leading edge. The row stays the control (`role` + `aria-checked` from
- `indicator` / `selection`); only the drawn mark changes, so pair it with an
- `indicator` (`'check'` / `'radio'`) or `selection="multiple"` for the
- semantics. Composes with `renderOption`. |
-| `renderOption?` | (option, state) => ReactNode | — | Replaces the built-in `label`, `hint`, and `icon` layout for each option row.
- Select still supplies the row container, click handling, ARIA attributes, and
- selection indicator. Read extra option fields through `SelectOption`'s index
- signature. `state` contains `value`, `selected`, and `disabled`. Filtering
- still matches the option's `value`, `label`, and `hint`, but Select cannot
- highlight matches within the returned content. |
-| `renderSummary?` | (selected) => string \| undefined | — | `multiple` only: build the trigger's selection summary text yourself,
- replacing the built-in "`All` / one label / `N selected`" logic. Receives
- the resolved selected options (`selected.length` is the count) and runs only
- while something is selected — an empty selection still shows the
- `placeholder`. Return a **string**: it flows into the default trigger's
- read-only field, so a long summary ellipsizes at the field's width just
- like a long value (`Engineering, Design, … `). Return `undefined` to fall
- back to the default for that case (e.g. customize only the count, keeping
- the single-label case built-in). For rich content (chips, multiple nodes)
- use `renderTrigger`, which replaces the whole field. |
-| `renderTrigger?` | (state) => ReactNode | — | Replaces the default field with a trigger returned from this function.
- Receives `open`, `value`, `selected`, `disabled`, and `icon`. Return exactly
- one focusable element, such as an Anta `Button`. The menu is positioned
- relative to that element and opens when it is clicked. Do not return a
- fragment, multiple siblings, or a non-focusable wrapper. Add
- `aria-haspopup="menu"` and `aria-expanded={state.open}` to the element, on a
- role that supports them (an Anta `Button` already carries `role="button"`;
- otherwise add `role="combobox"`).
- Field props (`label`, `hint`, `size`, `status`, `placeholder`, and `round`) and
- `className` / `style` apply only to the default field. Add styling and
- attributes to the returned element instead. |
+| `placement?` | 'left' \| 'right' \| 'bottom' \| 'top' \| 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' \| 'right-start' \| 'right-end' \| 'left-start' \| 'left-end' | bottom-start | Preferred placement of the options menu relative to the trigger. The menu auto-flips vertically and clamps horizontally when needed. |
+| `renderEmpty?` | (state) => ReactNode | — | Render content in the menu body when the (filtered) option list is empty — a "no results" message, a loading indicator (gated on your own external loading state), or a "create from the query" row. Receives an `EmptyState` (`query`, trimmed). There is no built-in empty message: when omitted, an empty list renders nothing. Whatever you return goes where the option rows would — a plain node is inert; return a `MenuItem` (e.g. a "Create" row) to make it focusable and selectable. |
+| `renderIndicator?` | (state) => ReactNode | — | Replace each row's selection **mark** with your own node, drawn at the leading edge. The row stays the control (`role` + `aria-checked` from `indicator` / `selection`); only the drawn mark changes, so pair it with an `indicator` (`'check'` / `'radio'`) or `selection="multiple"` for the semantics. Composes with `renderOption`. |
+| `renderOption?` | (option, state) => ReactNode | — | Replaces the built-in `label`, `hint`, and `icon` layout for each option row. Select still supplies the row container, click handling, ARIA attributes, and selection indicator. Read extra option fields through `SelectOption`'s index signature. `state` contains `value`, `selected`, and `disabled`. Filtering still matches the option's `value`, `label`, and `hint`, but Select cannot highlight matches within the returned content. |
+| `renderSummary?` | (selected) => string \| undefined | — | `multiple` only: build the trigger's selection summary text yourself, replacing the built-in "`All` / one label / `N selected`" logic. Receives the resolved selected options (`selected.length` is the count) and runs only while something is selected — an empty selection still shows the `placeholder`. Return a **string**: it flows into the default trigger's read-only field, so a long summary ellipsizes at the field's width just like a long value (`Engineering, Design, … `). Return `undefined` to fall back to the default for that case (e.g. customize only the count, keeping the single-label case built-in). For rich content (chips, multiple nodes) use `renderTrigger`, which replaces the whole field. |
+| `renderTrigger?` | (state) => ReactNode | — | Replaces the default field with a trigger returned from this function. Receives `open`, `value`, `selected`, `disabled`, and `icon`. Return exactly one focusable element, such as an Anta `Button`. The menu is positioned relative to that element and opens when it is clicked. Do not return a fragment, multiple siblings, or a non-focusable wrapper. Add `aria-haspopup="menu"` and `aria-expanded={state.open}` to the element, on a role that supports them (an Anta `Button` already carries `role="button"`; otherwise add `role="combobox"`). Field props (`label`, `hint`, `size`, `status`, `placeholder`, and `round`) and `className` / `style` apply only to the default field. Add styling and attributes to the returned element instead. |
 | `round?` | boolean \| number \| string | — | Round the field corners — `true` for fully round, or a number / CSS length. |
-| `selectAll?` | boolean | true | `multiple` only: shows a "Select all" row that toggles every enabled option,
- or only the visible options when a filter query is active. Its checkbox is
- mixed when some options are selected. It is on by default. Set it to `false`
- to remove the row and the Alt/Option-click shortcut that selects only one row. |
+| `selectAll?` | boolean | true | `multiple` only: shows a "Select all" row that toggles every enabled option, or only the visible options when a filter query is active. Its checkbox is mixed when some options are selected. It is on by default. Set it to `false` to remove the row and the Alt/Option-click shortcut that selects only one row. |
 | `selectAllLabel?` | string | Select all | Label for the `selectAll` row. |
-| `selection?` | 'single' \| 'multiple' | single | Selection mode. `'single'` (the default) keeps `value` a single value and
- closes the menu on pick. Switch to `'multiple'` for checkboxes + an
- array value. |
+| `selection?` | 'single' \| 'multiple' | single | Selection mode. `'single'` (the default) keeps `value` a single value and closes the menu on pick. Switch to `'multiple'` for checkboxes + an array value. |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Field size. |
 | `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | neutral | Validation/feedback tone for the field (Input's `status`). |
-| `statusIcon?` | (string & {}) \| false \| IconShape | — | Glyph shown before the `hint` when `status` is set (Input's `statusIcon`).
- Each status has a default; pass a shape to override, or `false` to drop it. |
-| `toneSelected?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | — | Tone applied to the **selected** row(s) — the whole row takes this tone
- (label, icon, indicator, and the background tint), like passing `tone` to just
- the chosen option. A named tone or a custom CSS color. Most visible with the
- tint-based marks (`indicator` `'none'` / `'check'`); with `'radio'` /
- `'checkbox'` it tones the label + indicator (those modes have no row tint). |
-| `value?` | V \| V[] | — | Controlled value: the selected option's `value`. Update it through
- `onValueChange`. Leave it undefined for uncontrolled use. |
-| `verbose?` | boolean | — | `multiple` only: spell the picks out in the count summary — `3 selected:
- A, B, C` (labels comma-joined) in place of the bare `3 selected`. Applies
- to the multi-count case only: `All` stays `All`, a single pick stays its
- own label, and an empty selection stays the `placeholder`. The list flows
- into the read-only field, so it ellipsizes at the field's width when long
- (`3 selected: Engineering, Des… `). `renderSummary` overrides this. |
+| `statusIcon?` | (string & {}) \| false \| IconShape | — | Glyph shown before the `hint` when `status` is set (Input's `statusIcon`). Each status has a default; pass a shape to override, or `false` to drop it. |
+| `toneSelected?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | — | Tone applied to the **selected** row(s) — the whole row takes this tone (label, icon, indicator, and the background tint), like passing `tone` to just the chosen option. A named tone or a custom CSS color. Most visible with the tint-based marks (`indicator` `'none'` / `'check'`); with `'radio'` / `'checkbox'` it tones the label + indicator (those modes have no row tint). |
+| `value?` | V \| V[] | — | Controlled value: the selected option's `value`. Update it through `onValueChange`. Leave it undefined for uncontrolled use. |
+| `verbose?` | boolean | — | `multiple` only: spell the picks out in the count summary — `3 selected: A, B, C` (labels comma-joined) in place of the bare `3 selected`. Applies to the multi-count case only: `All` stays `All`, a single pick stays its own label, and an empty selection stays the `placeholder`. The list flows into the read-only field, so it ellipsizes at the field's width when long (`3 selected: Engineering, Des… `). `renderSummary` overrides this. |
 
 ### The `SelectItem` type
 
@@ -829,6 +752,8 @@ inline `SelectGroup`, and a flyout `SelectSubmenu` (whose items are themselves
 />
 ```
 
+## Web Component
+
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 `Select` has no host element. Compose a read-only `<a-input>` trigger with an
@@ -896,6 +821,8 @@ corners.
 </select>
 ```
 
+## Styling
+
 Select is an [Input](./input.md) plus a [Menu](./menu.md), so it
 inherits both surfaces' hooks. Reach for props first, then plain CSS or `::part` for
 the rest. Don't override an element's internal `--*` output tokens.