@antadesign/anta 0.3.28 → 0.3.30

package/docs/components/panel.md

@@ -0,0 +1,189 @@
+# Panel
+
+`Panel` is a container that can maximize to the browser viewport without moving
+or remounting its children. It fills its parent's width and height and uses
+`overflow: scroll` by default.
+
+Give the parent a defined height for Panel to fill vertically. With an
+auto-height parent, percentage height follows normal CSS sizing and the Panel
+can grow with its content. A parent's `min-height` alone does not generally
+establish a height for `height: 100%` to fill.
+
+> **Warning:** For now, Panel is a nonvisual utility container only. Supply your
+> own appearance and controls. Built-in chrome, resizing, and folding are not
+> available yet.
+
+## Usage
+
+### Declarative
+
+Panel manages its own state. Use `data-custom-event="paneltoggle"` on
+an Anta button to toggle maximization without a click handler.
+
+```tsx title="Declarative Panel"
+import { Box, Button, Input, Panel } from '@antadesign/anta'
+
+function Workspace() {
+  return (
+    <Panel style={{ background: 'var(--bg-3)' }}>
+      <Box
+        display="flex"
+        gap={16}
+        padding={16}
+      >
+        <Input aria-label="Workspace note" placeholder="Write a note" />
+        <Button data-custom-event="paneltoggle">
+          Maximize / restore
+        </Button>
+      </Box>
+    </Panel>
+  )
+}
+```
+
+### Controlled
+
+Pass `maximized` to manage state in your application. The button updates it
+through `onClick`; `onStateChange` accepts requests from declarative controls
+inside the panel.
+
+```tsx title="Controlled Panel"
+import { useState } from 'react'
+import { Box, Button, Input, Panel } from '@antadesign/anta'
+
+function Workspace() {
+  const [maximized, setMaximized] = useState(false)
+
+  return (
+    <Panel
+      style={{ background: 'var(--bg-3)' }}
+      maximized={maximized}
+      onStateChange={(_event, { next }) => setMaximized(next)}
+    >
+      <Box
+        display="flex"
+        gap={16}
+        padding={16}
+      >
+        <Input aria-label="Workspace note" placeholder="Write a note" />
+        <Button onClick={() => setMaximized(value => !value)}>
+          {maximized ? 'Restore panel' : 'Maximize panel'}
+        </Button>
+      </Box>
+    </Panel>
+  )
+}
+```
+
+## How does this work?
+
+Maximizing applies `popover="manual"` to the internal content slot and calls
+`showPopover()` to fill the viewport. Children keep their DOM ancestry, theme,
+and event bubbling. A placeholder preserves the panel's normal layout size.
+Restoring calls `hidePopover()` and returns the same content to normal layout.
+
+```html title="Internal content while maximized"
+<!-- Managed by Panel inside its shadow root. -->
+<slot part="content" popover="manual" tabindex="-1"></slot>
+```
+
+While maximized, Panel traps focus inside its content. Tab and Shift+Tab cycle
+through its controls. Restoring releases the trap and returns focus to the
+previous external control, when available.
+
+Provide a keyboard-accessible **Restore** control: Escape and outside clicks
+do not restore the panel. Panel adds no dialog role, background inertness, or
+scroll lock. Use [Dialog](./dialog.md) for modal interactions.
+
+Panel fills the browser viewport, without invoking the Fullscreen API.
+Browsers without Popover API support keep it in normal layout.
+
+## Component props
+
+For uncontrolled state, omit `maximized` and optionally set `defaultMaximized`.
+Call `event.preventDefault()` synchronously in `onStateChange` to cancel an
+uncontrolled transition. In controlled mode, reject a request by leaving
+`maximized` unchanged.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `defaultMaximized?` | boolean | — | Initial viewport maximization for an uncontrolled panel, read once on connect. |
+| `maximized?` | boolean | — | Fill the browser viewport and contain keyboard focus within the panel. When supplied, the application owns the state. |
+| `onStateChange?` | (event, detail) => void | — | Requested maximization change. Update `maximized` to accept a controlled request, or prevent the event to veto an uncontrolled request. |
+
+## Web component
+
+Import `@antadesign/anta/elements` to register the elements in this example.
+The button toggles the nearest panel without JavaScript handlers.
+
+```html title="Declarative web component"
+<a-panel style="background: var(--bg-3)">
+  <a-box display="flex" padding="16px" gap="16px" style="--box-padding: 16px; --box-gap: 16px">
+    <a-input aria-label="Workspace note" placeholder="Write a note"></a-input>
+    <a-button role="button" tabindex="0" data-custom-event="paneltoggle">
+      Maximize / restore
+    </a-button>
+  </a-box>
+</a-panel>
+```
+
+Use `state="normal"` or `state="maximized"` for controlled state, or `default-state="maximized"`
+for an initially maximized, uncontrolled panel.
+
+`requestMaximize()` and `requestRestore()` emit a cancelable, non-bubbling
+`statechange` with `{ next, prev }` using those state strings.
+Anta buttons can send `panelmaximizerequest`, `panelrestorerequest`, or
+`paneltoggle` through `data-custom-event` to the nearest Panel.
+
+## Styling
+
+Panel defaults to `display: block`, `width: 100%`, `height: 100%`,
+`box-sizing: border-box`, and `overflow: scroll`. Padding and borders stay inside
+its assigned size. It does not set `flex-grow`.
+
+Override these through ordinary CSS. Use `height: auto` for content-driven
+height or `overflow: auto` for scrollbars only when content overflows.
+With `overflow: scroll`, scrollbar visibility and reserved space follow the
+browser and operating system's scrollbar settings.
+
+Set the background on Panel. Its maximized surface inherits that background,
+so inner content can keep its natural height. Style light-DOM children, such as
+[Box](./box.md) or [Capture](./capture.md), for content layout shared between both states.
+Use `:state(maximized)` for viewport styling and `::part(content)` for the
+maximized scrolling surface. In normal mode, the content slot uses `display: contents`.
+The maximized surface also uses `overflow: scroll`; override
+`::part(content)` to change its overflow separately from the normal Panel.
+
+Enter a note, then select **Maximize panel** and **Restore panel**. The input
+keeps its value. The `panel-demo` classes supply this example's appearance;
+replace them with your own selectors.
+
+```html title="A persistent workspace panel"
+<a-panel class="panel-demo">
+  <a-box class="panel-demo-content">
+    <a-box class="panel-demo-toolbar" display="flex">
+      <a-text weight="medium">Workspace preview</a-text>
+      <a-button role="button" tabindex="0" data-custom-event="paneltoggle">
+        <span class="panel-demo-maximize">Maximize panel</span>
+        <span class="panel-demo-restore">Restore panel</span>
+      </a-button>
+    </a-box>
+    <a-capture>
+      <a-input placeholder="Write a note before maximizing" aria-label="Workspace note"></a-input>
+      <a-text>Panel keeps this Box and Capture in their original DOM location.</a-text>
+    </a-capture>
+  </a-box>
+</a-panel>
+```
+
+```css title="Preview layout and appearance"
+.panel-demo { border: 1px solid var(--border-4); border-radius: 8px; background: var(--bg-3); }
+.panel-demo-content { display: flex; flex-direction: column; gap: 20px; padding: 20px; }
+.panel-demo-toolbar { justify-content: space-between; align-items: center; gap: 12px; flex-wrap: wrap; }
+.panel-demo-content a-capture { display: grid; gap: 16px; }
+.panel-demo-content a-input { width: 100%; }
+.panel-demo-restore { display: none; }
+.panel-demo:state(maximized) .panel-demo-content { padding: max(20px, env(safe-area-inset-top)) max(20px, env(safe-area-inset-right)) max(20px, env(safe-area-inset-bottom)) max(20px, env(safe-area-inset-left)); }
+.panel-demo:state(maximized) .panel-demo-maximize { display: none; }
+.panel-demo:state(maximized) .panel-demo-restore { display: inline; }
+```

package/docs/components/radio.md

@@ -165,7 +165,9 @@ Under the hood the split is deliberate. The `<a-radio-group>` web component
 **never mutates the DOM** — it coordinates entirely off-DOM: selection is set as a
 property on each `<a-radio>` (which reflects it into `:state(selected)` +
 `aria-checked` via its own `ElementInternals`), the form value goes through
-`ElementInternals`, and focus is tracked with `aria-activedescendant`. The
+`ElementInternals`, and focus is tracked with `aria-activedescendant`. Each
+option's light-DOM label and hint also become its accessible name and description
+through direct element references, without generated IDs. The
 **roving `tabindex`** — which option Tab lands on — is the one piece rendered
 declaratively, by the `RadioGroup` wrapper, from the current value. That's why
 selection is owned by the element but the wrapper holds the value: it needs it to
@@ -270,7 +272,7 @@ element — `Input`, and the composed `Select` — skip it and expose only
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size applied to every option (an option's own `size` wins). |
 | `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | 'neutral' | Validation/feedback tone for the group `hint` — recolors it (same tone set as `Input`'s `status`). Use `critical` for an error message, etc.; omit for the neutral default. |
 | `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Mark tone applied to every option (an option's own `tone` wins), or any literal CSS color for a one-off custom tone. In the default `all` scope it colors the selected-ring fill + dot and the unselected ring border. Named tones track light/dark mode. Set `toneScope="selected"` to tone only the selected option and leave the rest neutral. The option text stays neutral — recolor it in plain CSS via the `--text-N-{tone}` tokens. |
-| `toneScope?` | ToneScope | 'all' | Apply `tone` to every state, or only to the selected option so unselected rings stay neutral. An option's own `toneScope` wins. |
+| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every state, or only to the selected option so unselected rings stay neutral. An option's own `toneScope` wins. |
 | `value?` | string | — | Controlled selected value. The group follows this prop and reports a requested change through `onStateChange`. Leave it undefined for uncontrolled use. |
 
 ## Web Component

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; }
 ```