@antadesign/anta 0.3.27 → 0.3.29

package/docs/components/select-faceted.md

@@ -14,6 +14,12 @@ application-defined facet keys, not Anta terms. Each facet has one of four
 Use `value` with `onValueChange` to control it, or use `defaultValue` for an
 uncontrolled filter.
 
+Without `searchable`, the trigger opens a menu of facets. With `searchable`, it
+opens a dialog containing the search field and that menu. A filtered option
+facet also opens a dialog containing its search field and options menu. Text and
+custom facets use dialogs for their editable content. An unfiltered option facet
+keeps the menu popup pattern.
+
 Pass `placement` to control where the root facet menu opens relative to its
 trigger. It uses the same values as `Menu` and still flips or clamps when space
 is limited. `offset` sets the gap in pixels between the trigger and the menu:
@@ -22,11 +28,32 @@ is limited. `offset` sets the gap in pixels between the trigger and the menu:
 <SelectFaceted placement="top-end" offset={8} facets={FACETS} />
 ```
 
+Open **Metadata** in the first demo to choose key–value tags such as
+**env production** or **region us-east**. Its `renderOption` callback reads
+custom option fields and renders a `Tag` with `label` and `value`. Search
+for **production** to see the same tag in global results.
+
 ```tsx
 const FACETS = [
   { key: 'assignee', label: 'Assignee', kind: 'multiple', filter: true, options: people },
   { key: 'owner',    label: 'Owner',    kind: 'single',   filter: true, options: people },
   { key: 'status',   label: 'Status',   kind: 'single',   options: [{ value: 'open', label: 'Open' }, /* … */] },
+  {
+    key: 'metadata',
+    label: 'Metadata',
+    kind: 'multiple',
+    icon: 'tag',
+    filter: true,
+    options: [
+      { value: 'env:production', label: 'env: production', dataKey: 'env', dataValue: 'production' },
+      { value: 'env:staging', label: 'env: staging', dataKey: 'env', dataValue: 'staging' },
+      { value: 'region:us-east', label: 'region: us-east', dataKey: 'region', dataValue: 'us-east' },
+      { value: 'team:platform', label: 'team: platform', dataKey: 'team', dataValue: 'platform' },
+    ],
+    renderOption: (option) => (
+      <Tag label={String(option.dataKey)} value={String(option.dataValue)} />
+    ),
+  },
   { key: 'title',    label: 'Title contains', kind: 'text' },
   { key: 'duration', label: 'Min duration', kind: 'custom', summary: (v) => `≥ ${v.min}s`, render: /* … */ },
 ]
@@ -68,6 +95,7 @@ function Demo() {
                   selection={facet.kind}
                   indicator={facet.kind === 'single' ? 'check' : undefined}
                   options={facet.options}
+                  renderOption={facet.renderOption}
                   value={value[facet.key]}
                   onValueChange={(v) => setFacet(facet.key, v)}
                   leading={`${facet.label}:`}
@@ -120,6 +148,27 @@ The trigger opens the facet menu. The example renders one editable
 [Select](./select.md) below it for each active facet. Each Select receives the
 facet label through `leading`, which displays it as a prefix.
 
+### Custom option content
+
+Pass `renderOption(option, state)` on a `single` or `multiple` facet to replace
+each option's label, hint, and icon layout. It runs in both the facet flyout and
+global search results. `state` contains `value`, `selected`, and `disabled`.
+Selection handling, indicators, and option styling remain on the row.
+Return `null` to use the default layout for an option.
+
+The first demo's **Metadata** facet stores the key and value in custom option
+fields. Pass them to Tag's `label` and `value` props:
+
+```tsx
+renderOption: (option) => (
+  <Tag label={String(option.dataKey)} value={String(option.dataValue)} />
+)
+```
+
+Filtering still uses `value`, `label`, and `hint`, or the facet's custom `filter`
+function. Keep searchable text in those fields. Single-facet summaries still
+use the option label, and multiple-facet summaries show the selected count.
+
 ### Value and changes
 
 The value is a record keyed by facet key: `{ [facetKey]: value }`. Its shape
@@ -373,11 +422,12 @@ const recency: SelectFacetCustom<Recency> = {
 | `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. |
+| `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={searchable ? 'dialog' : '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. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | — | Default option-row tone in facet flyouts. An option's own `tone` wins. |
+| `toneScope?` | 'all' \| 'selected' | '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
@@ -390,6 +440,12 @@ properties as [Select](./select.md). They use `kind` in place of Select's
 `selection`. `text` and `custom` do not use Select options. A `single` facet
 returns one option value; a `multiple` facet returns an array of option values.
 
+When `selectAll` is enabled, Alt-clicking an option in a `multiple` facet clears
+the other values and selects that option. Use Option-click on macOS. After a
+700ms hover, a tooltip beside the row describes the shortcut. Moving to another
+row restarts the delay. An option's `tooltip` replaces that hint; set it
+to `''` to hide the hint.
+
 | Field | Type | Description |
 |---|---|---|
 | `key` | `string` | The key for this facet's value in the record. `attrs.facet` returns it. It must be unique in `facets`. |

package/docs/components/select.md

@@ -4,7 +4,7 @@
 field shows the selected value. Click the field to open the menu. The menu
 closes when a user clicks outside it or presses Esc.
 
-Select uses an [Input](./input.md) for its field and a [Menu](./menu.md) for its
+Select uses an [Anta Button](./button.md) for its field and a [Menu](./menu.md) for its
 dropdown. Pass `options` as an array of strings or objects. Use `value` with
 **`onValueChange`** to control the selection, or use `defaultValue` for an
 uncontrolled Select.
@@ -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
@@ -70,7 +70,8 @@ its box goes mixed when only some are on. Pass **`selectAll={false}`** to drop i
 
 In a multi-select, **`Alt`+Click** a row to clear every other selection and
 select that row. On macOS, use Option instead of Alt.
-The standard tooltip describes this shortcut when the pointer is over a row.
+After hovering for 700ms, the standard tooltip describes this shortcut beside
+the row. Moving to another row restarts the delay.
 Set `SelectOption.tooltip` to replace it, or to `''` to hide it. The shortcut
 is available only when `selectAll` is enabled, so `selectAll={false}` removes it.
 
@@ -78,9 +79,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.
 
@@ -105,12 +106,14 @@ option's **value, label, or hint**. It's **whitespace-flexible** (a typed space
 matches any run of whitespace) and **bolds the matched substring** in the results.
 Pass a **function** `(option, query) => boolean` for custom matching (no highlight).
 
-With `filter`, Select behaves as a **combobox**. Opening it focuses the search
-field. ↑ and ↓ move through matching options while focus
-stays in the field. Enter selects the active option, and Esc
-closes the menu. The search field stays visible while the results scroll. A
-"No matches" row appears when nothing matches, and the query resets when the
-menu closes. In `multiple` mode, `selectAll` affects only the visible matches.
+With `filter`, the trigger opens a dialog containing the search field and an
+options menu. This keeps the textbox outside the menu in the accessibility tree.
+Opening the dialog focuses the search field. ↑ and ↓ move
+through matching options while focus stays in that field. Enter
+selects the active option, and Esc closes the dialog. The search field
+stays visible while the results scroll. A "No matches" row appears when nothing
+matches, and the query resets when the dialog closes. In `multiple` mode,
+`selectAll` affects only the visible matches.
 
 ## Value and changes
 
@@ -229,7 +232,7 @@ section marks the leaf everywhere it occurs (selection is value-keyed).
 <Select status="info" statusIcon="sparkles" hint="Custom glyph" options={OPTIONS} defaultValue="stream" />
 ```
 
-The trigger is an [Input](./input.md), so it inherits the field props.
+The trigger is an [Anta Button](./button.md) styled as a field.
 **`size`** (`small` · `medium` · `large`) sets the height and type scale.
 **`status`** paints a validation tone on the border, `hint`, and chevron, and
 prefixes a glyph (`info` / `success` / `warning` / `critical`); **`statusIcon`**
@@ -245,7 +248,7 @@ the glyph and, for `critical`, validity. See the
 ## Customization
 
 Select has no `<a-select>` element. The React and Preact wrapper coordinates an
-Input and a Menu. You can use the wrapper, render custom option content with
+Anta Button and a Menu. You can use the wrapper, render custom option content with
 `renderOption`, replace its selection mark with `renderIndicator`, or build the
 same interaction from the raw elements.
 
@@ -259,22 +262,21 @@ uses the same values as `Menu` and still flips or clamps when space is limited.
 
 ### Build it from elements
 
-The wrapper renders a read-only `<Input>` and a `<Menu>`. It updates the field
+The wrapper renders a `<Button>` immediately followed by a `<Menu>`, with a label
+and hint inside an `<a-select-field>` layout wrapper. It updates the field
 and each option's `selected` state from the value, and reports a pick through
 `onValueChange`. Menu handles positioning, dismissal, and keyboard navigation.
 
 The following example shows the equivalent markup without React or Preact. Place
-the Menu directly after the Input so it can use that Input as its trigger.
+the Menu directly after the Button so it can use that Button as its trigger.
 
 ```html
 <!-- `.select` scopes this example's CSS. Use an application selector instead. -->
 <div class="select" style="width: 240px">
-  <!-- Read-only field trigger; `dim-actions` dims the chevron at rest. The
-       trailing slot supplies the inline inset (--input-trailing-inset); the
-       transition on the chevron matches <Select>. -->
-  <a-input readonly dim-actions value="stream" aria-haspopup="menu">
-    <a-icon slot="trailing" shape="chevron-down" style="transition: transform 150ms ease"></a-icon>
-  </a-input>
+  <a-button role="button" tabindex="0" aria-label="Field" aria-haspopup="menu" aria-expanded="false">
+    <a-button-label>stream</a-button-label>
+    <a-icon shape="chevron-down" aria-hidden="true" style="transition: transform 150ms ease"></a-icon>
+  </a-button>
   <a-menu role="menu">
     <a-menu-item role="menuitemradio" tabindex="0" aria-checked="false" value="output_text"><a-menu-item-label>output_text</a-menu-item-label></a-menu-item>
     <a-menu-item role="menuitemradio" tabindex="0" aria-checked="true" value="stream" selected><a-menu-item-label>stream</a-menu-item-label></a-menu-item>
@@ -284,12 +286,14 @@ the Menu directly after the Input so it can use that Input as its trigger.
 <script type="module">
   import '@antadesign/anta/elements'
   const root = document.querySelector('.select')
-  const field = root.querySelector('a-input')
+  const field = root.querySelector('a-button')
   const menu = root.querySelector('a-menu')
   const chevron = field.querySelector('a-icon')
   // Flip the chevron with the menu's open state (as <Select> does).
   menu.addEventListener('statechange', (e) => {
-    chevron.style.transform = e.detail.next === 'open' ? 'rotate(180deg)' : ''
+    const open = e.detail.next === 'open'
+    field.setAttribute('aria-expanded', String(open))
+    chevron.style.transform = open ? 'rotate(180deg)' : ''
   })
   // On pick: mark the row selected + reflect its label into the field.
   menu.addEventListener('click', (e) => {
@@ -300,12 +304,16 @@ the Menu directly after the Input so it can use that Input as its trigger.
       el.toggleAttribute('selected', selected)
       el.setAttribute('aria-checked', String(selected))
     })
-    field.value = item.querySelector('a-menu-item-label').textContent
+    field.querySelector('a-button-label').textContent = item.querySelector('a-menu-item-label').textContent
   })
 </script>
 ```
 
 The React and Preact `Select` wrapper performs those updates for you.
+Because the Menu directly follows the Anta Button, it associates the focused
+field with the popup through a direct ARIA element reference. No popup ID is
+required. If a custom composition supplies its own `aria-controls`, Anta keeps
+that authored relationship.
 
 ### Custom option rendering
 
@@ -461,7 +469,7 @@ empty selection still shows the `placeholder` — and takes the resolved `select
 options (`selected.length` is the count). Return `undefined` for any case you'd rather
 leave to the default, as above for the single-label case.
 
-Return a **string**: it flows into the same read-only field the default uses, so a
+Return a **string**: it flows into the same Button label the default uses, so a
 long summary **ellipsizes at the field's width** the way a long value does
 (`Engineering, Design, … `). For rich content — chips, several nodes — reach for
 `renderTrigger` below, which replaces the whole field.
@@ -523,7 +531,8 @@ focusable element, such as the Anta `Button` in this example. Select positions
 the menu relative to that element and opens it when it is clicked. A fragment,
 multiple sibling elements, or a non-focusable wrapper prevents Select from finding
 the trigger. It logs a console warning when that happens. Add
-`aria-haspopup="menu"` and `aria-expanded={state.open}` to the element.
+`aria-haspopup={filter ? 'dialog' : 'menu'}` and
+`aria-expanded={state.open}` to the element.
 
 `state` includes `open`, `value`, `selected`, `disabled`, and `icon`. `selected`
 is the resolved option list, so `selected.length` is the multi-select count. The
@@ -633,11 +642,11 @@ scannable list instead of hiding matches behind flyouts.
 | `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). |
-| `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. |
+| `hint?` | string | — | Helper text under the field. |
+| `icon?` | IconShape | — | Leading icon shown at the left of the field. 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`. |
+| `label?` | string | — | Field label, above the trigger. |
+| `leading?` | ReactNode | — | Content before the default trigger's value, 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). |
 | `placeholder?` | string | — | Text shown when nothing is selected. |
@@ -645,18 +654,19 @@ scannable list instead of hiding matches behind flyouts.
 | `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. |
+| `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 Button label, 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={filter ? 'dialog' : 'menu'}` and `aria-expanded={state.open}` to the returned button. An Anta `Button` already carries the correct role. 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. |
 | `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. |
 | `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). |
+| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | neutral | Validation/feedback tone for the field. |
+| `statusIcon?` | (string & {}) \| false \| IconShape | — | Glyph shown before the `hint` when `status` is set. 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?` | 'all' \| 'selected' | '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. |
+| `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 Button label, so it ellipsizes at the field's width when long (`3 selected: Engineering, Des… `). `renderSummary` overrides this. |
 
 ### The `SelectItem` type
 
@@ -756,16 +766,16 @@ inline `SelectGroup`, and a flyout `SelectSubmenu` (whose items are themselves
 
 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
+`Select` uses a layout wrapper. Compose an `<a-button>` trigger with an
 `<a-menu>` of options. The menu owns opening and dismissal; the short controller
 reflects a picked option into the field and selected row.
 
 ```html
 <div data-anta-composition="select" style="display: grid; gap: 4px; width: 280px">
-  <a-input readonly value="stream">
-    <span slot="label">Output</span>
-    <span slot="trailing"><a-icon shape="chevron-down" aria-hidden="true"></a-icon></span>
-  </a-input>
+  <a-button role="button" tabindex="0" aria-label="Output" aria-haspopup="menu" aria-expanded="false">
+    <a-button-label>stream</a-button-label>
+    <a-icon shape="chevron-down" aria-hidden="true"></a-icon>
+  </a-button>
   <a-menu role="menu">
     <a-menu-item role="menuitem" tabindex="0" value="output_text"><a-menu-item-label>output_text</a-menu-item-label></a-menu-item>
     <a-menu-item role="menuitem" tabindex="0" value="stream" selected><a-menu-item-label>stream</a-menu-item-label></a-menu-item>
@@ -775,8 +785,11 @@ reflects a picked option into the field and selected row.
   import '@antadesign/anta/elements'
 
   const root = document.querySelector('[data-anta-composition="select"]')
-  const field = root.querySelector('a-input')
+  const field = root.querySelector('a-button')
   const menu = root.querySelector('a-menu')
+  menu.addEventListener('statechange', (event) => {
+    field.setAttribute('aria-expanded', String(event.detail.next === 'open'))
+  })
 
   menu.addEventListener('click', (event) => {
     const item = event.target instanceof Element ? event.target.closest('a-menu-item') : null
@@ -785,7 +798,7 @@ reflects a picked option into the field and selected row.
       const selected = option === item
       option.toggleAttribute('selected', selected)
     })
-    field.value = item.querySelector('a-menu-item-label').textContent.trim()
+    field.querySelector('a-button-label').textContent = item.querySelector('a-menu-item-label').textContent.trim()
   })
 </script>
 ```
@@ -823,36 +836,36 @@ corners.
 
 ## 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
+Select composes an [Anta Button](./button.md) and a [Menu](./menu.md). 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
-`::part`s; set its width with `style` / `className` (forwarded to the field). **The
-popover** takes Menu's `::part(menu)`.
+**The field** takes `size`, `status`, and `round`. Set its width with `style` /
+`className`, forwarded to the `<a-select-field>` wrapper. Style the trigger through
+`a-select-field > a-button` and its `a-button-label`. The trigger uses
+`:focus-visible` for its focus ring and ellipsizes long values. **The 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
 it *at rest* and let the standard hover / focus shadow return on its own; no need to
 re-declare it. Pair that with hiding the chevron for a field that reads as plain text
-until you reach for it. Hide the chevron by targeting the trailing `a-icon` (its slot
-wrapper is inline-`display:contents`, so hit the icon itself).
+until you reach for it. Hide the chevron by targeting `a-select-chevron`.
 
 ```css
 /* Drop the resting border-shadow; the standard hover / focus shadow still shows. */
-.ghost-select a-input:not(:hover):not(:focus-within)::part(field) {
+.ghost-select a-select-field > a-button:not(:hover):not(:focus-visible) {
   box-shadow: none;
 }
 /* Center the chosen label in the field. */
-.ghost-select a-input::part(input) { text-align: center; }
-/* The chevron's slot wrapper is inline display:contents; hide the icon itself. */
-.ghost-select a-input [slot="trailing"] a-icon { display: none; }
+.ghost-select a-select-field > a-button > a-button-label { text-align: center; }
+/* Hide the chevron. */
+.ghost-select a-select-chevron { display: none; }
 ```

package/docs/components/steps.md

@@ -260,10 +260,10 @@ Events match [`Tabs`](./tabs.md#events).
 | `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. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | '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. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| '' | '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
@@ -271,14 +271,14 @@ Events match [`Tabs`](./tabs.md#events).
 | 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. |
+| `state` | 'incomplete' \| 'loading' \| 'completed' \| 'error' | — | 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. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| '' | 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
 

package/docs/components/switch.md

@@ -6,6 +6,8 @@ The `Switch` wrapper renders a form-associated `<a-switch>` element. It works un
 
 ## Tone
 
+Switch is neutral by default. Pass `tone="brand"` or another tone to color the control.
+
 `tone` colors the whole control: the checked track, plus the unchecked track border and thumb. Six named tones are available, or pass any CSS color for a custom tone. The label and hint stay neutral.
 
 ```tsx
@@ -17,16 +19,16 @@ The `Switch` wrapper renders a form-associated `<a-switch>` element. It works un
 
 ## Selected-only tone
 
-`toneSelected` colors the checked track only. The unchecked track and thumb stay neutral until the switch is on. Use it when a resting tinted control could imply a validation state. It accepts the same values as `tone`.
+To apply a tone only while selected, pass `toneScope="selected"` together with `tone`, such as `tone="brand"`. Only the checked track is tinted; the unchecked track border and thumb stay neutral.
 
 ```tsx
-<Switch toneSelected="brand" label="Off stays neutral" />
-<Switch defaultChecked toneSelected="critical" label="Checked track tinted" />
+<Switch tone="brand" toneScope="selected" label="Off stays neutral" />
+<Switch defaultChecked tone="critical" toneScope="selected" label="Checked track tinted" />
 ```
 
 ## Coloring the text
 
-There is no text-tone prop. To tint the label, set `color` on the switch with a theme-aware `--text-N-{tone}` token; to tint the hint, target `a-switch-hint`. Pair either with `tone` or `toneSelected` to color the whole control.
+There is no text-tone prop. To tint the label, set `color` on the switch with a theme-aware `--text-N-{tone}` token; to tint the hint, target `a-switch-hint`. Pair either with `tone` to color the whole control.
 
 ```css
 /* The class is only for the demo — use your own selector. */
@@ -119,7 +121,10 @@ Use **`onStateChange`** to intercept a toggle or drive a controlled switch. Use
 
 ## Accessibility
 
-The wrapper sets `role="switch"` and keeps `aria-checked` in sync with the current value. It derives the accessible name from `label` or text children. For a label-less switch, pass `aria-label`.
+The wrapper sets `role="switch"`, and the element keeps `aria-checked` in sync
+with the current value. Its light-DOM label supplies the accessible name and its
+hint supplies the accessible description through `ElementInternals`; no generated
+IDs are needed. For a label-less switch, pass `aria-label`.
 
 Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).
 
@@ -130,7 +135,7 @@ Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w
 | `checked?` | boolean | — | Controlled checked value. In controlled mode, update this in `onStateChange`. |
 | `defaultChecked?` | boolean | false | Initial checked value for an uncontrolled switch. |
 | `disabled?` | boolean | — | Disables interaction and removes the switch from the tab order. |
-| `hint?` | ReactNode | — | Secondary text rendered under the label. It does not become part of the accessible name. |
+| `hint?` | ReactNode | — | Secondary text rendered under the label and exposed as the switch's accessible description. It does not become part of the accessible name. |
 | `label?` | string | — | Visible, stable label for the setting. Use `children` for richer label content. |
 | `labelPosition?` | 'start' \| 'end' | 'end' | Put the visible label before or after the control. Grid layout changes only the visual order, preserving DOM/source order for assistive technologies. |
 | `name?` | string | — | Form field name. A checked switch submits `value` under this name. |
@@ -139,15 +144,16 @@ Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w
 | `onValueChange?` | (event, attrs) => void | — | Post-apply callback with the new form-relevant value snapshot. |
 | `round?` | boolean \| number \| string | — | Fully round the thumb and track. Pass a `number` (px) or CSS length string for a custom track radius; the thumb radius is 3px smaller. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant. small=26×16px, medium=30×18px, large=34×20px. |
-| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'brand' | Color of the track and thumb. A tinted tone also colors the unchecked track border and thumb; use `toneSelected` to color only the checked track. |
-| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'brand' | Like `tone`, but applies only while the switch is checked. The unchecked track and thumb stay neutral. If both are set, `tone` colors the unchecked state and `toneSelected` colors the checked track. |
+| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the track and thumb. A tinted tone also colors the unchecked track border and thumb; use `toneScope="selected"` to color only the checked track. |
+| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every state, or only while checked so the unchecked track and thumb stay neutral. |
 | `value?` | string | "on" | Value submitted while checked. |
 
 ## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
-The focusable host carries the state. Label and hint are light-DOM children.
+The focusable host carries the state. Label and hint are light-DOM children that
+the element exposes as its accessible name and description.
 
 ```html
 <a-switch role="switch" tabindex="0" name="updates" default-state="checked">
@@ -158,7 +164,7 @@ The focusable host carries the state. Label and hint are light-DOM children.
 
 ## Styling
 
-Reach for the props first: **`tone`** colors the checked track plus the unchecked chrome, while **`toneSelected`** colors only the checked track. Both accept any CSS color; **`size`** scales the control, label, and hint. The focus ring is the global [`--focus-ring`](../colors.md#focus-ring).
+Reach for the props first: **`tone`** chooses the control color, while **`toneScope`** chooses whether it colors all states or only the checked track. `tone` accepts any CSS color; **`size`** scales the control, label, and hint. The focus ring is the global [`--focus-ring`](../colors.md#focus-ring).
 
 ```tsx
 <Switch tone="#e0457b" defaultChecked label="Custom color" />

package/docs/components/tabs.md

@@ -271,15 +271,17 @@ const [tab, setTab] = useState('overview')
 
 ## Keyboard & accessibility
 
-Every enabled tab is in the tab order; `Tab` / `Shift`+`Tab` step through them.
-The arrow keys also move between enabled tabs (wrapping at the ends), `Home` /
+The selected tab is in the page's tab order. Once focus enters the strip, the
+arrow keys move between enabled tabs (wrapping at the ends), `Home` /
 `End` jump to the first / last, and `Space` / `Enter` activate the focused tab;
 arrow / `Home` / `End` navigation activates as it moves (selection follows focus).
 Disabled tabs are skipped and dropped from the tab order.
 
 Pass `label` for the tablist's accessible name. Each `<TabPanel>` names its tab as
 its accessible label (`aria-labelledby`), set off-DOM so nothing writes the panel's
-attributes.
+attributes. Static panel content remains readable without making the panel a tab
+stop. Set `tabIndex={0}` when you want a text-only panel itself to receive focus;
+when the panel starts with a focusable control, Tab reaches that control directly.
 
 ## Routing
 
@@ -357,7 +359,7 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 | `value` | string | — | This tab's identity — pairs it with the `<TabPanel value="…">` of the same value, and the value reported by `onStateChange` / `onChange`. Unique per strip. |
 | `children?` | ReactNode | — | Tab content when you need more than a string — used if `label` is omitted. |
 | `className?` | string | — | CSS class on the option's rendered row. |
-| `disabled?` | boolean | — | Disable just this tab — skipped by keyboard nav and dropped from the tab order (a disabled-but-selected tab stays reachable, per the ARIA pattern). |
+| `disabled?` | boolean | — | Prevent user activation of this tab. A disabled tab can still indicate the current selection. |
 | `icon?` | IconShape | — | Leading icon shape, rendered before the label. |
 | `iconTrailing?` | IconShape | — | Trailing icon shape, rendered after the label. |
 | `label?` | ReactNode | — | Visible label. The string shorthand for the tab's content; for richer content pass `children` instead (`label` wins when both are set). |
@@ -371,17 +373,18 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `value` | string | — | Pairs this panel with the tab (`options` entry) of the same `value`. |
-| `children?` | ReactNode | — | Panel content — arbitrary React/Preact. |
-| `className?` | string | — | CSS class on the rendered `<a-tabpanel>`. |
 | `hideMode?` | 'display' \| 'visibility' | display | How this panel hides while inactive: `display` (default — removed from layout and the a11y tree) or `visibility` (keeps its layout box, to measure it or avoid reflow). Both stay mounted; to *not render* an inactive panel, render it conditionally off a controlled `value` (see the Tabs docs). |
-| `style?` | CSSProperties | — | Inline style on the rendered `<a-tabpanel>`. |
 
 ## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 Keep the tab strip and panels as siblings under one parent. Panels read the active
-value from `<a-tabs>`.
+value from `<a-tabs>`. Give the selected tab `tabindex="0"` and the others
+`tabindex="-1"`; `<a-tabs>` moves focus and selection with the arrow keys, while
+your change handler updates those attributes for the next visit to the strip. Add
+`tabindex="0"` to a text-only panel only when you want the panel itself in the page
+Tab sequence.
 
 Add `fill` to make horizontal tabs share the available width equally.
 
@@ -396,6 +399,16 @@ Add `fill` to make horizontal tabs share the available width equally.
 </div>
 ```
 
+```js title="Keep the raw DOM tab stop on the selected tab"
+const tabs = document.querySelector('a-tabs')
+
+tabs.addEventListener('change', () => {
+  for (const tab of tabs.querySelectorAll('a-tab')) {
+    tab.tabIndex = tab.getAttribute('value') === tabs.value ? 0 : -1
+  }
+})
+```
+
 ## Styling
 
 Reach for the props first: **`tone`**, **`size`**, **`priority`**. The focus ring is