@antadesign/anta 0.3.26 → 0.3.27

package/docs/components/select.md

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

package/docs/components/slider.md

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

package/docs/components/steps.md

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

package/docs/components/switch.md

@@ -123,33 +123,28 @@ The wrapper sets `role="switch"` and keeps `aria-checked` in sync with the curre
 
 Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `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. 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. |
+| `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. |
 | `onChange?` | (event) => void | — | Native post-apply `change` event. |
-| `onStateChange?` | (event, detail) => void | — | Fired before a user toggle applies. Call `event.preventDefault()` to veto an
-uncontrolled change; controlled consumers accept by updating `checked`. |
+| `onStateChange?` | (event, detail) => void | — | Fired before a user toggle applies. Call `event.preventDefault()` to veto an uncontrolled change; controlled consumers accept by updating `checked`. |
 | `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. |
+| `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 & {}) | '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. |
 | `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.
@@ -161,6 +156,8 @@ The focusable host carries the state. Label and hint are light-DOM children.
 </a-switch>
 ```
 
+## 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).
 
 ```tsx

package/docs/components/tabs.md

@@ -166,6 +166,8 @@ its value is active. The panel names its tab as its accessible label
 Panels are **optional**. Without panels, `Tabs` renders the strip. Listen to
 `onStateChange` / `onValueChange` and render the content yourself.
 
+### JSX vs DOM
+
 The strip renders from the `options` array; each `<TabPanel>` renders a
 self-managing `<a-tabpanel>`. `Tabs` **never reads or toggles the panels**: there's
 no child introspection, so it renders the same in static SSR and works with any
@@ -196,6 +198,8 @@ and shows/hides **itself** via its own off-DOM `:state(active)`; nothing writes
 writes the light DOM, only your JSX does, which keeps a worker-thread reactive engine
 in sync.
 
+### Hiding an inactive panel
+
 A `<TabPanel>` stays mounted while inactive (its DOM, form values, and scroll
 survive tab switches); `hideMode` picks how it hides:
 
@@ -265,6 +269,8 @@ 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` /
 `End` jump to the first / last, and `Space` / `Enter` activate the focused tab;
@@ -275,6 +281,8 @@ Pass `label` for the tablist's accessible name. Each `<TabPanel>` names its tab
 its accessible label (`aria-labelledby`), set off-DOM so nothing writes the panel's
 attributes.
 
+## Routing
+
 `Tabs` reports the picked value and leaves navigation to the app, so a strip can
 switch routes as readily as panels. Treat each `value` as a path: control `value`
 from the current location and navigate in `onStateChange` (the pick fires *on click*;
@@ -319,54 +327,56 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 <Tabs defaultValue="a" onValueChange={(_e, { value }) => route(value)}>…</Tabs>
 ```
 
+## Tabs props
+
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children?` | ReactNode | — | Optional `<TabPanel value="…">` panels, one per tab value. Each is a
- self-managing `<a-tabpanel>` that shows itself when its `value` is the active
- tab. Omit them to use `Tabs` as a bare selectable strip. To place panels in a
- different layout region, or to unmount an inactive panel, drive selection with
- a controlled `value` and render the content yourself (see the docs). |
-| `defaultValue?` | string | — | Initial active value for the uncontrolled case. After first render `Tabs`
- owns selection itself. |
+| `children?` | ReactNode | — | Optional `<TabPanel value="…">` panels, one per tab value. Each is a self-managing `<a-tabpanel>` that shows itself when its `value` is the active tab. Omit them to use `Tabs` as a bare selectable strip. To place panels in a different layout region, or to unmount an inactive panel, drive selection with a controlled `value` and render the content yourself (see the docs). |
+| `defaultValue?` | string | — | Initial active value for the uncontrolled case. After first render `Tabs` owns selection itself. |
 | `disabled?` | boolean | — | Disable the whole strip. |
 | `fill?` | boolean | false | Makes horizontal tabs share the available inline space equally. |
 | `label?` | string | — | Accessible name for the tablist (`aria-label`). |
-| `noslide?` | boolean | — | Disable the sliding indicator. By default the selected-tab indicator animates
- between tabs (a single rectangle, via CSS anchor positioning); `noslide` paints it
- per tab so it snaps with no movement. (Browsers without anchor positioning get that
- per-tab paint automatically — `noslide` is the explicit opt-out.) |
+| `noslide?` | boolean | — | Disable the sliding indicator. By default the selected-tab indicator animates between tabs (a single rectangle, via CSS anchor positioning); `noslide` paints it per tab so it snaps with no movement. (Browsers without anchor positioning get that per-tab paint automatically — `noslide` is the explicit opt-out.) |
 | `onBlur?` | (event) => void | — | Focus left the strip entirely — wired to `focusout`. |
 | `onChange?` | (event) => void | — | Fired *after* the active tab changes — a native `change` event. |
-| `onFocus?` | (event) => void | — | Focus entered the strip (any tab) — wired to `focusin` (focus lands on a tab,
- not the tablist). |
-| `onStateChange?` | (event, detail) => void | — | Fired whenever the active tab changes — event-first. `detail` is
- `{ next, prev }` (values; `null` = none). Cancelable: `event.preventDefault()`
- vetoes it (uncontrolled), or in controlled mode answer by updating `value`. |
+| `onFocus?` | (event) => void | — | Focus entered the strip (any tab) — wired to `focusin` (focus lands on a tab, not the tablist). |
+| `onStateChange?` | (event, detail) => void | — | Fired whenever the active tab changes — event-first. `detail` is `{ next, prev }` (values; `null` = none). Cancelable: `event.preventDefault()` vetoes it (uncontrolled), or in controlled mode answer by updating `value`. |
 | `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value }` snapshot as the 2nd argument. |
-| `options?` | TabOption[] | — | The tabs, as a data array (the strip's single source). Each entry is a
- `TabOption` (`value`, `label` or `children`, `icon`, `iconTrailing`, `tone`,
- `disabled`, `round`, `className`, `style`). `className` and `style` land on
- that option's individual `<a-tab>`, not on the strip. |
-| `orientation?` | 'horizontal' \| 'vertical' | 'horizontal' | Layout + arrow-key axis. Horizontal ellipsizes labels when tabs overflow (scroll
- is opt-in via CSS); vertical stacks them. |
-| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'primary' | Visual priority. `primary` is the raised pill on a recessed track (the
- segmented-control look); `secondary` keeps that sizing but drops the track, marking
- the selected tab with a subtle active background fill; `tertiary` is a bottom-underline
- indicator under the selected tab (no track, no rest line). `tone` colors `secondary` +
- `tertiary`; `primary` stays neutral. |
-| `round?` | boolean \| number \| string | — | Fully-round the tabs and the sliding indicator (and the primary track
- well). Applies strip-wide; a single tab's `round` rounds just that tab. A
- `number` (px) or CSS length string sets a custom radius on the top-level
- track well only — the tab pills + indicator stay fully round. |
-| `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?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Tone applied to the selected indicator/label, or any literal CSS color for a
- one-off custom tone (derived in oklch). Named tones track light/dark. |
-| `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. |
+| `options?` | TabOption[] | — | The tabs, as a data array (the strip's single source). Each entry is a `TabOption` (`value`, `label` or `children`, `icon`, `iconTrailing`, `tone`, `disabled`, `round`, `className`, `style`). `className` and `style` land on that option's individual `<a-tab>`, not on the strip. |
+| `orientation?` | 'horizontal' \| 'vertical' | 'horizontal' | Layout + arrow-key axis. Horizontal ellipsizes labels when tabs overflow (scroll is opt-in via CSS); vertical stacks them. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'primary' | Visual priority. `primary` is the raised pill on a recessed track (the segmented-control look); `secondary` keeps that sizing but drops the track, marking the selected tab with a subtle active background fill; `tertiary` is a bottom-underline indicator under the selected tab (no track, no rest line). `tone` colors `secondary` + `tertiary`; `primary` stays neutral. |
+| `round?` | boolean \| number \| string | — | Fully-round the tabs and the sliding indicator (and the primary track well). Applies strip-wide; a single tab's `round` rounds just that tab. A `number` (px) or CSS length string sets a custom radius on the top-level track well only — the tab pills + indicator stay fully round. |
+| `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?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Tone applied to the selected indicator/label, or any literal CSS color for a one-off custom tone (derived in oklch). Named tones track light/dark. |
+| `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. |
+
+## Tab option props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `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). |
+| `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). |
+| `round?` | boolean | — | Fully-round just this tab's box. `<Tabs round>` rounds the whole strip (tabs + sliding indicator) instead. |
+| `style?` | CSSProperties | — | Inline styles on the option's rendered row. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | inherits the strip's `tone | Per-tab tone override, same vocabulary as `<Tabs tone>` — colors this one tab's label + icons (all priorities/modes, named or custom color) and, when it's the active tab, its indicator. For a **custom literal color** the sliding indicator can't adopt it (the shared moving element can't read a descendant's color), so a custom tone colors the label everywhere and the indicator only in `noslide`; the six **named** tones color both in every mode. Overrides the strip's `tone` for this tab. |
+| `tooltip?` | ReactNode | — | Tooltip for this tab — a string or any node — shown **only when one of the tab's ellipsizing label parts is truncated** (tabs ellipsize when the strip overflows), so clipped content reveals its full text on hover while a tab that fits shows nothing. Rendered as a `truncatedOnly` `<Tooltip>` anchored to the tab. For an always-visible tooltip or other custom trigger content, use `children` with your own `<Tooltip>` instead. |
+
+## TabPanel props
+
+| 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.
 
@@ -386,6 +396,8 @@ Add `fill` to make horizontal tabs share the available width equally.
 </div>
 ```
 
+## Styling
+
 Reach for the props first: **`tone`**, **`size`**, **`priority`**. The focus ring is
 the global `--focus-ring` (see [Colors](../colors.md#focus-ring)).
 

package/docs/components/tag.md

@@ -117,33 +117,20 @@ down 1px, since caps read larger than mixed case at the same size.
 <Tag allcaps label="Running" />
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `allcaps?` | boolean | — | Render in all-caps instead of the default normal (mixed) case
- (uppercase tracks wider than the default body-text letter-spacing). |
+| `allcaps?` | boolean | — | Render in all-caps instead of the default normal (mixed) case (uppercase tracks wider than the default body-text letter-spacing). |
 | `icon?` | IconShape | — | Leading icon shape. Sits flush before the label, scaled to the pill. |
 | `iconTrailing?` | IconShape | — | Trailing icon shape. Renders last, after the value. |
-| `label?` | string | — | A short "key" shown before the value. When paired with `value` it
- renders bold (weight 600), same color. On its own (no `value`) it's
- treated as the tag's primary text and keeps the default styling. |
-| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | secondary | Emphasis level. `secondary` (the default) is the subtle alpha-tint
- fill; `primary` is a solid fill with white text; `tertiary` is a
- transparent outline. Omitting it (or passing `'secondary'`) renders
- the default and emits no DOM attribute. |
-| `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. `small` = 16px tall, `medium` = 20px, `large` = 24px
- (matching `Button`). Omit the attribute or pass `'medium'` for the
- default — both render identically and emit no DOM attribute. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`)
- for a one-off custom tone. Each tone renders the secondary tag style:
- `--text-3-{tone}` text over an alpha tint of the tone's hue (fill + a
- slightly stronger hairline border). A custom color is tinted the same
- way, with the text deepened to a readable foreground. `'neutral'` (the
- default) is the gray tag — the same as omitting `tone`. |
-| `value?` | string | — | The tag's primary text — a status, count, version, duration, etc.
- Rendered in the default color and weight, with no divider from the
- label; the color + weight contrast does the separating. |
+| `label?` | string | — | A short "key" shown before the value. When paired with `value` it renders bold (weight 600), same color. On its own (no `value`) it's treated as the tag's primary text and keeps the default styling. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | secondary | Emphasis level. `secondary` (the default) is the subtle alpha-tint fill; `primary` is a solid fill with white text; `tertiary` is a transparent outline. Omitting it (or passing `'secondary'`) renders the default and emits no DOM attribute. |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. `small` = 16px tall, `medium` = 20px, `large` = 24px (matching `Button`). Omit the attribute or pass `'medium'` for the default — both render identically and emit no DOM attribute. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone. Each tone renders the secondary tag style: `--text-3-{tone}` text over an alpha tint of the tone's hue (fill + a slightly stronger hairline border). A custom color is tinted the same way, with the text deepened to a readable foreground. `'neutral'` (the default) is the gray tag — the same as omitting `tone`. |
+| `value?` | string | — | The tag's primary text — a status, count, version, duration, etc. Rendered in the default color and weight, with no divider from the label; the color + weight contrast does the separating. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -157,6 +144,8 @@ Use `a-tag-label` for the key and `a-tag-value` for its value.
 </a-tag>
 ```
 
+## Styling
+
 Reach for the props first: **`tone`** sets the color (any CSS color for a custom
 tone — it derives the fill / border / text in oklch), **`priority`** the fill style,
 **`size`** the dimensions.