@antadesign/anta 0.3.28 → 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,12 +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. |
 | `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. |
+| `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
@@ -391,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.
@@ -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.
 
@@ -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,19 +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. |
+| `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?` | ToneScope | 'all' | Apply the default row tone in every state, or only to selected rows. An option's own `toneScope` 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?` | 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
 
@@ -757,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>
@@ -776,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
@@ -786,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>
 ```
@@ -824,17 +836,18 @@ 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 `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.
@@ -844,16 +857,15 @@ popover** takes Menu's `::part(menu)`.
 **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,7 +19,7 @@ The `Switch` wrapper renders a form-associated `<a-switch>` element. It works un
 
 ## Selected-only tone
 
-`toneScope="selected"` applies the switch's `tone` to 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.
+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 tone="brand" toneScope="selected" label="Off stays neutral" />
@@ -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 `toneScope="selected"` to color only the checked track. |
-| `toneScope?` | ToneScope | 'all' | Apply `tone` to every state, or only while checked so the unchecked track and thumb stay neutral. |
+| `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">

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

package/docs/components/tooltip.md

@@ -67,9 +67,11 @@ The underlying `<a-tooltip>` works in plain HTML too, as a child of any element:
 
 ### Adjacent and nested tooltips
 
-Only one tooltip shows at a time. Moving between **adjacent** anchors hands off
-cleanly — the outgoing bubble cross-fades out as the next fades in (no blink).
-With `follow` tooltips (used below to show it), the outgoing bubble also keeps
+Only one tooltip shows at a time. Moving between **adjacent** anchors with
+`follow` tooltips hands off cleanly — the outgoing bubble cross-fades out as the
+next fades in (no blink). If either tooltip does not have `follow`, the next
+tooltip waits for its configured delay. With `follow` tooltips (used below to
+show it), the outgoing bubble also keeps
 trailing the cursor and fades by distance from its anchor (transparent by ~100px
 away), so a near hop reads as a smooth cross-fade and a far one is already gone.
 With **nested** anchors, the inner (descendant) tooltip wins while you're over
@@ -125,7 +127,7 @@ shows.
 | `delay?` | number | 300 | Show delay in milliseconds after hover / focus. Never use `0` — use ~`50` for a near-instant tooltip (0 has caused issues in practice). |
 | `follow?` | boolean | — | Follow the cursor instead of pinning under the anchor. The bubble is pinned (anchored beneath the target) by default; pass `follow` for the cursor-tracking behavior, which fades by distance as the cursor leaves. |
 | `interactive?` | boolean | — | Make the bubble hoverable and clickable — enables pointer events and keeps it open while the cursor is over it, so its content (links, buttons) can be interacted with. Always pinned (an interactive bubble can't follow the cursor, even with `follow`). |
-| `placement?` | 'top' \| 'bottom' | bottom | Which side of the anchor the bubble prefers. Auto-flips to the other side when there isn't room. |
+| `placement?` | 'top' \| 'bottom' \| 'left' | bottom | Which side of the anchor the bubble prefers. Auto-flips to the other side when there isn't room. |
 | `round?` | boolean \| number \| string | — | Round the bubble to a 20px radius (matching a round menu). Pass a `number` (px) or a CSS length string for a custom radius. |
 | `truncatedOnly?` | boolean | — | Only show when the target is actually truncated (its text overflows and is ellipsized); a label that fits gets no tooltip. The check is a UI-thread layout read, re-measured on each show. By default it measures every Anta ellipsizing label part inside the anchor, then the anchor itself — override with `truncatedSelector`. |
 | `truncatedSelector?` | string | — | CSS selector (resolved within the anchor) for the element or elements whose overflow decides whether a `truncatedOnly` tooltip shows. |

package/docs/index.md

@@ -50,6 +50,7 @@ Anta is designed for a clean DOM. Prefer the props and attributes exposed by eac
 
 - [Box](./components/box.md)
 - [Capture](./components/capture.md)
+- [Panel](./components/panel.md)
 
 ## Packages
 

package/docs/install-config.md

@@ -61,8 +61,9 @@ seed-derived default palette or provide your own theme.
 
 ### Cascade layers
 
-Anta's reset and element CSS use child layers inside `@layer anta`. `tokens.css`
-orders them above preflight resets and below your component and utility layers:
+Anta's reset and element CSS use child layers inside `@layer anta`. Every Anta
+stylesheet reserves the same order, so granular stylesheets remain safe when a
+bundler loads them before `tokens.css`:
 
 ```css
 @layer base, anta, components, utilities;
@@ -72,8 +73,8 @@ orders them above preflight resets and below your component and utility layers:
 `anta.theme` lets the optional reference palette replace component formulas. The
 outer `anta` layer keeps its public cascade position.
 
-To change that order, declare it in CSS loaded **before** `tokens.css`. The
-first declaration fixes a layer's position:
+To change that order, declare it in CSS loaded **before any Anta stylesheet**.
+The first declaration fixes a layer's position:
 
 ```css
 /* your global.css, loaded before anta */