@antadesign/anta 0.3.26 → 0.3.28

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

@@ -57,7 +57,8 @@ one. Any literal CSS color works too, for a one-off custom tone.
 
 ```tsx
 <RadioGroup
-  toneSelected="brand"
+  tone="brand"
+  toneScope="selected"
   defaultValue="a"
   options={[
     { value: 'a', label: 'Option A' },
@@ -66,10 +67,10 @@ one. Any literal CSS color works too, for a one-off custom tone.
 />
 ```
 
-`toneSelected` tones the **selected option only** — every unselected ring stays
-neutral grey. Reach for it instead of `tone` when a resting tinted border would read
-as a validation error. Same tone set; set it on the group, or on a single option to
-override one.
+`toneScope="selected"` applies the group's `tone` to the **selected option only** —
+every unselected ring stays neutral grey. Use it when a resting tinted border would
+read as a validation error. Set the scope on the group, or on a single option to
+override the group.
 
 To color the **label and hint**, there's no prop — add a `color` rule on the
 option's `a-radio-label` / `a-radio-hint` with a `--text-N-{tone}` value.
@@ -250,50 +251,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. In the default `all` scope it colors the selected-ring fill + dot and the unselected ring border. Named tones track light/dark mode. Set `toneScope="selected"` 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. |
+| `toneScope?` | ToneScope | 'all' | Apply `tone` to every state, or only to the selected option so unselected rings stay neutral. An option's own `toneScope` wins. |
+| `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.
 
@@ -315,20 +295,22 @@ For a standard HTML form, add `data-anta` to each native radio. Radios that shar
 a `name` retain the browser's selection, keyboard behavior, labels, and form
 submission while using Anta's control surface.
 
-`size`, `tone`, and `tone-selected` use the matching RadioGroup option
+`size`, `tone`, and `tone-scope` use the matching RadioGroup option
 treatments.
 
 ```html
 <div style="display: grid; gap: 8px">
   <label><input data-anta type="radio" name="plan" value="starter" size="small" tone="brand"> Starter</label>
-  <label><input data-anta type="radio" name="plan" value="pro" tone-selected="success" checked> Pro</label>
+  <label><input data-anta type="radio" name="plan" value="pro" tone="success" tone-scope="selected" checked> Pro</label>
   <label><input data-anta type="radio" name="plan" value="enterprise" size="large" tone="warning"> Enterprise</label>
 </div>
 ```
 
-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
+## Styling
+
+Reach for the props first: **`tone`** chooses the mark color and **`toneScope`**
+chooses whether it applies in all states or only to the selected option (any CSS
+color can be set on the group or one option and derives the full curve in oklch), **`size`** the
 dimensions + type. To tint the label + hint, add a `color` rule on the option's
 `a-radio-label` / `a-radio-hint` with the `--text-N-{tone}` values — there's no
 text-tone prop. The focus ring is the global [`--focus-ring`](../colors.md#focus-ring).

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,16 @@ 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. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | — | Default option-row tone in facet flyouts. An option's own `tone` wins. |
+| `toneScope?` | ToneScope | 'all' | Apply the default row tone in every state, or only to selected rows. An option's own `toneScope` wins. |
+| `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

@@ -40,8 +40,8 @@ skipped by the keyboard.
 <Select options={OPTIONS} value={one} onValueChange={setOne} />                    // tint only (default)
 
 // Tone the selected row: named tone or custom color (the indicator adopts it)
-<Select indicator="check" toneSelected="brand" options={OPTIONS} value={one} onValueChange={setOne} />
-<Select indicator="radio" toneSelected="#c026d3" options={OPTIONS} value={one} onValueChange={setOne} />
+<Select indicator="check" tone="brand" toneScope="selected" options={OPTIONS} value={one} onValueChange={setOne} />
+<Select indicator="radio" tone="#c026d3" toneScope="selected" options={OPTIONS} value={one} onValueChange={setOne} />
 
 // Multiple: checkboxes, count summary, Select-all row (default); value is an array
 <Select
@@ -78,9 +78,9 @@ Each checkable row is the control itself (`role="menuitemcheckbox"` /
 `menuitemradio`, `aria-checked`); the checkbox / radio / check is a passive indicator
 the row drives.
 
-**`toneSelected`** tones the selected row(s): the whole row takes the tone, including
-label, icon, indicator, and tint. Pass a named tone or any CSS color (a custom color
-keeps its hue, with lightness pinned to the brand text). It reads strongest with
+Use **`tone`** with **`toneScope="selected"`** to tone only selected rows: the whole
+row takes the tone, including label, icon, indicator, and tint. Pass a named tone or
+any CSS color (a custom color keeps its hue, with lightness pinned to the brand text). It reads strongest with
 `indicator` `none` / `check`, which show the row tint; `radio` / `checkbox` have no
 row tint, so it tones the label and indicator only.
 
@@ -623,117 +623,41 @@ 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. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | — | Default option-row tone. An option's own `tone` wins. A named tone or a custom CSS color. Most visible with tint-based marks (`indicator` `'none'` / `'check'`); with `'radio'` / `'checkbox'` it also tones the indicator. |
+| `toneScope?` | ToneScope | 'all' | Apply the default row tone in every state, or only to selected rows. An option's own `toneScope` wins. |
+| `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 +753,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,12 +822,14 @@ 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.
 
-**Selection color** routes through the props: a per-option `tone`, or `toneSelected`
-for the chosen row(s). Both take a named tone or any CSS color (a custom color keeps
+**Selection color** routes through `tone`: set it per option or on the Select as a
+default, then use `toneScope="selected"` for chosen rows only. It takes a named tone or any CSS color (a custom color keeps
 its hue, with lightness pinned to the brand text).
 
 **The field** is styled through Input's props (`size`, `status`, `round`) and its
@@ -910,7 +838,7 @@ popover** takes Menu's `::part(menu)`.
 
 ```tsx
 // Tone the selection; give the trigger a width.
-<Select toneSelected="brand" style={{ width: '220px' }} options={OPTIONS} />
+<Select tone="brand" toneScope="selected" style={{ width: '220px' }} options={OPTIONS} />
 ```
 
 **Borderless trigger.** The field's border is an inset `box-shadow`, so you can drop

package/docs/components/slider.md

@@ -13,6 +13,9 @@ decreases it. The thumb does not move to the point where the rail was pressed.
 Set `trackClick="jump"` to move the thumb to the pressed position before
 dragging, as a native range input does.
 
+Releasing the pointer or losing pointer capture ends the drag. Moving back over
+the slider without pressing leaves its value unchanged.
+
 Arrow keys change by `step`. Home and End set the minimum and maximum. PageUp and PageDown move by one tenth of the range.
 
 ```tsx
@@ -59,43 +62,35 @@ Arrow keys change by `step`. Home and End set the minimum and maximum. PageUp an
 />
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `defaultValue?` | number | 0 | Initial uncontrolled value. |
 | `disabled?` | boolean | — | Disables pointer and keyboard interaction. |
-| `label?` | ReactNode | — | Visible field label, shown above the rail. A string supplies the slider's
-accessible name; give a rich label an explicit `aria-label`. |
-| `markers?` | SliderMarker[] | — | Compact text labels positioned below the rail. They do not add dots or
-ticks to the rail. |
+| `label?` | ReactNode | — | Visible field label, shown above the rail. A string supplies the slider's accessible name; give a rich label an explicit `aria-label`. |
+| `markers?` | SliderMarker[] | — | Compact text labels positioned below the rail. They do not add dots or ticks to the rail. |
 | `max?` | number | 100 | Highest permitted value. |
 | `min?` | number | 0 | Lowest permitted value. |
 | `name?` | string | — | Form field name. The current numeric value submits under this name. |
 | `onValueChange?` | (event, attrs) => void | — | Fires on every keyboard or pointer value change. |
 | `onValueCommit?` | (event, attrs) => void | — | Fires after a drag ends and after each keyboard value change. |
-| `round?` | boolean \| number \| string | — | Fully round the rail and thumb. Pass a number (px) or CSS length string
-for a shared custom radius. |
+| `round?` | boolean \| number \| string | — | Fully round the rail and thumb. Pass a number (px) or CSS length string for a shared custom radius. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant. small=24px, medium=28px, large=32px tall. |
 | `step?` | number | 1 | Smallest keyboard and drag increment. |
-| `thumbFill?` | boolean | false | Fill the thumb with its resolved border color. This follows `thumbTone`
-and interactive states. |
-| `thumbSize?` | number \| string | 16 | Diameter of the thumb. Numbers use pixels; strings are CSS lengths. Keep
-it at least as large as `trackSize`. |
-| `thumbTone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the thumb stroke. Pass a named tone or a literal CSS color for a
-one-off custom tone. Omit it to keep the thumb neutral. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the filled rail. Pass a named tone or a literal CSS color for a
-one-off custom tone. The unfilled rail stays neutral. |
-| `trackClick?` | 'drag-only' \| 'jump' | 'drag-only' | Controls what happens when the rail is pressed. `drag-only` starts dragging
-from the current value. `jump` first moves to the pressed position. |
-| `trackSize?` | number \| string | 2 | Thickness of both rail segments. Numbers use pixels; strings are CSS
-lengths. Keep it no larger than the thumb diameter. |
+| `thumbFill?` | boolean | false | Fill the thumb with its resolved border color. This follows `thumbTone` and interactive states. |
+| `thumbSize?` | number \| string | 16 | Diameter of the thumb. Numbers use pixels; strings are CSS lengths. Keep it at least as large as `trackSize`. |
+| `thumbTone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the thumb stroke. Pass a named tone or a literal CSS color for a one-off custom tone. Omit it to keep the thumb neutral. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the filled rail. Pass a named tone or a literal CSS color for a one-off custom tone. The unfilled rail stays neutral. |
+| `trackClick?` | 'drag-only' \| 'jump' | 'drag-only' | Controls what happens when the rail is pressed. `drag-only` starts dragging from the current value. `jump` first moves to the pressed position. |
+| `trackSize?` | number \| string | 2 | Thickness of both rail segments. Numbers use pixels; strings are CSS lengths. Keep it no larger than the thumb diameter. |
 | `value?` | number | — | Controlled value. Update it from `onValueChange`. |
-| `valueDisplay?` | 'end' \| 'inline' \| 'thumb' \| 'none' | 'end' | Where the live value appears. `end` puts it at the right edge of the label
-row. `inline` renders `Label: value`. `thumb` keeps it above the thumb. |
+| `valueDisplay?` | 'end' \| 'inline' \| 'thumb' \| 'none' | 'end' | Where the live value appears. `end` puts it at the right edge of the label row. `inline` renders `Label: value`. `thumb` keeps it above the thumb. |
 | `valuePrefix?` | string | — | Text inserted before the live numeric value, such as `$`. |
 | `valueSuffix?` | string | — | Text inserted after the live numeric value, such as `%` or `°C`. |
 
+## Web Component
+
 Use `<a-slider>` when you are not using React or Preact. Add its `role` and accessible name yourself, then register it from `@antadesign/anta/elements`.
 
 ```html

package/docs/components/steps.md

@@ -225,6 +225,8 @@ the next step.
 </Steps>
 ```
 
+## Keyboard and accessibility
+
 Pass `label` to name the tablist. Arrow keys follow the orientation; `Home` and
 `End` move to the edges; `Enter` and `Space` activate a focused step. Disabled
 steps are skipped.
@@ -242,17 +244,43 @@ Events match [`Tabs`](./tabs.md#events).
 | `onChange(event)` | After selection | No | Native `change` event |
 | `onValueChange(event, { value })` | After selection | No | Selected value |
 
+## Steps props
+
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `options` | StepOption[] | — | Ordered process phases. |
-| `priority?` | StepPriority | 'secondary' | Visual emphasis. Primary uses a solid selected marker and a stronger
-completed connector; secondary is the outlined default; tertiary is compact
-and borderless. |
-| `renderMarker?` | (option, state) => ReactNode | — | Builds a custom marker from a step and its current state. A returned node
-replaces `marker` and the built-in state marker; return `undefined` to use
-those fallbacks, or `null` for an empty ring. |
-| `tone?` | StepTone \| '' | 'neutral' | Tone applied to every step without its own `tone`. Error steps stay
-critical and disabled steps stay neutral. |
+| `children?` | ReactNode | — | Optional `<TabPanel value="…">` panels, one per tab value. Each is a self-managing `<a-tabpanel>` that shows itself when its `value` is the active tab. Omit them to use `Tabs` as a bare selectable strip. To place panels in a different layout region, or to unmount an inactive panel, drive selection with a controlled `value` and render the content yourself (see the docs). |
+| `defaultValue?` | string | — | Initial active value for the uncontrolled case. After first render `Tabs` owns selection itself. |
+| `disabled?` | boolean | — | Disable the whole strip. |
+| `fill?` | boolean | false | Makes horizontal tabs share the available inline space equally. |
+| `label?` | string | — | Accessible name for the tablist (`aria-label`). |
+| `onBlur?` | (event) => void | — | Focus left the strip entirely — wired to `focusout`. |
+| `onChange?` | (event) => void | — | Fired *after* the active tab changes — a native `change` event. |
+| `onFocus?` | (event) => void | — | Focus entered the strip (any tab) — wired to `focusin` (focus lands on a tab, not the tablist). |
+| `onStateChange?` | (event, detail) => void | — | Fired whenever the active tab changes — event-first. `detail` is `{ next, prev }` (values; `null` = none). Cancelable: `event.preventDefault()` vetoes it (uncontrolled), or in controlled mode answer by updating `value`. |
+| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value }` snapshot as the 2nd argument. |
+| `orientation?` | 'horizontal' \| 'vertical' | 'horizontal' | Layout + arrow-key axis. Horizontal ellipsizes labels when tabs overflow (scroll is opt-in via CSS); vertical stacks them. |
+| `priority?` | StepPriority | 'secondary' | Visual emphasis. Primary uses a solid selected marker and a stronger completed connector; secondary is the outlined default; tertiary is compact and borderless. |
+| `renderMarker?` | (option, state) => ReactNode | — | Builds a custom marker from a step and its current state. A returned node replaces `marker` and the built-in state marker; return `undefined` to use those fallbacks, or `null` for an empty ring. |
+| `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size — small 24px · medium 28px · large 32px tall, matching Button's scale (the tab's label leading runs a touch tighter, offset by 1px more block padding per side). |
+| `tone?` | StepTone \| '' | 'neutral' | Tone applied to every step without its own `tone`. Error steps stay critical and disabled steps stay neutral. |
+| `value?` | string | — | Controlled active value — the tab `value` to mark selected (and, when a `<TabPanel value="…">` shares it, the panel to reveal). When set, you own selection: the strip renders exactly what this says, and a user pick only *requests* a change via `onStateChange` — apply it by updating this prop. Leave undefined (and use `defaultValue`) for uncontrolled. |
+
+## Step option props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | ReactNode | — | Visible phase label. It ellipsizes in a constrained step; its full content is available in a tooltip only when clipped. |
+| `state` | StepState | — | Application-owned process state. Selection and availability are separate; `error` keeps a critical icon and outline, and selection adds the fill. |
+| `value` | string | — | Stable phase identity. Values must be unique within the sequence. |
+| `className?` | string | — | CSS class on the option's rendered row. |
+| `disabled?` | boolean | — | Disables this phase. A custom `marker` or `renderMarker` result is kept; otherwise it uses the incomplete marker. |
+| `hint?` | ReactNode | — | Secondary text shown below the label. It ellipsizes in a constrained step; its full content is available in a tooltip only when clipped. |
+| `marker?` | StepMarker | — | Replaces the marker derived from `state`. A number is shown directly; an Anta icon shape is rendered as an `<Icon>`. |
+| `style?` | CSSProperties | — | Inline styles on the option's rendered row. |
+| `tone?` | StepTone \| '' | inherits Steps `tone | Tone for this phase. It colors the label, hint, marker, and completed connector. Overrides the Steps `tone`; error steps stay critical and disabled steps stay neutral. |
+
+## Web Component
 
 For framework-free use, compose the same light DOM that `Steps` emits.
 `a-steps` and its `a-step-*` children are structural elements styled by the
@@ -288,6 +316,8 @@ import '@antadesign/anta/components/Steps.css'
 </div>
 ```
 
+## Styling
+
 Use `priority`, `size`, and `orientation` first. Set `tone` on each option. Each
 option also accepts `className`, `style`, and `data-*` attributes. Markers are
 light DOM; connectors are pseudo-elements.