@antadesign/anta 0.3.25 → 0.3.27

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.

package/docs/components/text.md

@@ -97,34 +97,19 @@ more" and "Show less". `collapsible` takes effect only with `expandable`.
 <Text truncate={3} expandable collapsible>{longSentence}</Text>
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `collapsible?` | boolean | — | Let the reader collapse back after expanding: the chevron becomes a
- "Show more" / "Show less" toggle that stays visible while expanded.
- Only takes effect together with `expandable`. |
-| `expandable?` | boolean | — | Show a fade hint and chevron over the truncated text and let the user
- expand it by clicking the chevron region or pressing Enter while the
- chevron has keyboard focus. Only takes effect together with `truncate`.
- On its own, expanding is **one-way** — the control is removed once
- expanded; add `collapsible` for a two-way toggle. |
+| `collapsible?` | boolean | — | Let the reader collapse back after expanding: the chevron becomes a "Show more" / "Show less" toggle that stays visible while expanded. Only takes effect together with `expandable`. |
+| `expandable?` | boolean | — | Show a fade hint and chevron over the truncated text and let the user expand it by clicking the chevron region or pressing Enter while the chevron has keyboard focus. Only takes effect together with `truncate`. On its own, expanding is **one-way** — the control is removed once expanded; add `collapsible` for a two-way toggle. |
 | `inline?` | boolean | — | Render as inline-block instead of the default block element. |
-| `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | secondary | Visual priority. Maps to text-1..text-4 (`primary` = text-1, the
- strongest). The default is `secondary` (text-2) — body text reads a
- step softer than the strongest foreground; pass `primary` for emphasis. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | secondary | Visual priority. Maps to text-1..text-4 (`primary` = text-1, the strongest). The default is `secondary` (text-2) — body text reads a step softer than the strongest foreground; pass `primary` for emphasis. |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Type scale. `small` = 13/16, `medium` = 15/20, `large` = 17/24. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a
- named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS
- color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is
- kept while lightness/chroma are pinned per priority in oklch. |
-| `truncate?` | boolean \| number | — | Truncate with a trailing ellipsis. `true` (or `1`) clamps to a
- single line; any integer ≥ 2 clamps to that many lines; `0` or a
- negative value means no truncation. A clipped, non-expandable JSX
- `Text` shows its text content in a tooltip by default. Nest a
- `<Tooltip>` to provide your own tooltip instead. Uses the
- `-webkit-line-clamp` technique, supported in all major browsers
- (Firefox 68+, Chrome, Safari, Edge). |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is kept while lightness/chroma are pinned per priority in oklch. |
+| `truncate?` | boolean \| number | — | Truncate with a trailing ellipsis. `true` (or `1`) clamps to a single line; any integer ≥ 2 clamps to that many lines; `0` or a negative value means no truncation. A clipped, non-expandable JSX `Text` shows its text content in a tooltip by default. Nest a `<Tooltip>` to provide your own tooltip instead. Uses the `-webkit-line-clamp` technique, supported in all major browsers (Firefox 68+, Chrome, Safari, Edge). |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -136,6 +121,8 @@ Use `<a-text>` directly for a block that carries the text priority and tone.
 </a-text>
 ```
 
+## Styling
+
 Color comes from **`priority`** (the neutral text level) and **`tone`** (the tint);
 `size` and the type props set the rest. For a named tone, `Text` consumes the
 global **text role tokens** (`--text-1` … `--text-5`, the `-{tone}` tints,

package/docs/components/title.md

@@ -93,18 +93,15 @@ The four priorities are shown across every named tone at `level={3}`. Omit
 document outline or SEO needs heading elements; the reset applies the same type
 scale.
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `level?` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 2 | Heading level, 1-6. Drives font-size, line-height, and vertical
- rhythm. Also surfaced to assistive tech via `aria-level`
- (h1 is typically reserved for the page title). |
+| `level?` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 2 | Heading level, 1-6. Drives font-size, line-height, and vertical rhythm. Also surfaced to assistive tech via `aria-level` (h1 is typically reserved for the page title). |
 | `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | primary | Visual priority. Maps to text-1..text-4 (`primary` = text-1). |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a
- named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS
- color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is
- kept while lightness/chroma are pinned per priority in oklch. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is kept while lightness/chroma are pinned per priority in oklch. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -116,6 +113,8 @@ Set the heading role and level when writing `<a-title>` directly.
 </a-title>
 ```
 
+## Styling
+
 `priority` selects a neutral text level. Named `tone`s use the matching global
 text tokens. A literal `tone` is stored in `--title-tone-source` and resolved
 into the four priority levels.

package/docs/components/toaster.md

@@ -222,13 +222,14 @@ Toaster.manager.add(() => <Banner tone="critical" message="Connection lost" />,
 })
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `label?` | string | 'Notifications' | Accessible label for the region landmark. |
-| `toaster?` | Toaster | — | The store this region renders. Omit to bind the default store driven by
- `Toaster.manager`; pass a `createToaster()` for an isolated region. |
+| `toaster?` | Toaster | — | The store this region renders. Omit to bind the default store driven by `Toaster.manager`; pass a `createToaster()` for an isolated region. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -266,6 +267,8 @@ remove the toast from the DOM.
 </script>
 ```
 
+## Styling
+
 The region and item are plain custom elements — style them with ordinary CSS
 (`@layer anta`, so an un-layered rule of yours wins without `!important`).
 

package/docs/components/tooltip.md

@@ -117,32 +117,20 @@ arrives later works normally; a bubble whose content is cleared while it's open
 closes itself. Content that's a single icon or image (an element, no text) still
 shows.
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children?` | ReactNode | — | Tooltip content. Renders anything — text, markup, an icon + text.
- Lives in the light DOM, so it's styleable with your own plain CSS. |
-| `delay?` | number | 300 | Show delay in milliseconds after hover / focus. Never use `0` — use
- ~`50` for a near-instant tooltip (0 has caused issues in practice). |
-| `follow?` | boolean | — | Follow the cursor instead of pinning under the anchor. The bubble is
- pinned (anchored beneath the target) by default; pass `follow` for the
- cursor-tracking behavior, which fades by distance as the cursor leaves. |
-| `interactive?` | boolean | — | Make the bubble hoverable and clickable — enables pointer events and
- keeps it open while the cursor is over it, so its content (links,
- buttons) can be interacted with. Always pinned (an interactive bubble
- can't follow the cursor, even with `follow`). |
-| `placement?` | 'top' \| 'bottom' | bottom | Which side of the anchor the bubble prefers. Auto-flips to the other
- side when there isn't room. |
-| `round?` | boolean \| number \| string | — | Round the bubble to a 20px radius (matching a round menu). Pass a `number`
- (px) or a CSS length string for a custom radius. |
-| `truncatedOnly?` | boolean | — | Only show when the target is actually truncated (its text overflows and is
- ellipsized); a label that fits gets no tooltip. The check is a UI-thread
- layout read, re-measured on each show. By default it measures every Anta
- ellipsizing label part inside the anchor, then the anchor itself —
- override with `truncatedSelector`. |
-| `truncatedSelector?` | string | — | CSS selector (resolved within the anchor) for the element or elements
- whose overflow decides whether a `truncatedOnly` tooltip shows. |
+| `children?` | ReactNode | — | Tooltip content. Renders anything — text, markup, an icon + text. Lives in the light DOM, so it's styleable with your own plain CSS. |
+| `delay?` | number | 300 | Show delay in milliseconds after hover / focus. Never use `0` — use ~`50` for a near-instant tooltip (0 has caused issues in practice). |
+| `follow?` | boolean | — | Follow the cursor instead of pinning under the anchor. The bubble is pinned (anchored beneath the target) by default; pass `follow` for the cursor-tracking behavior, which fades by distance as the cursor leaves. |
+| `interactive?` | boolean | — | Make the bubble hoverable and clickable — enables pointer events and keeps it open while the cursor is over it, so its content (links, buttons) can be interacted with. Always pinned (an interactive bubble can't follow the cursor, even with `follow`). |
+| `placement?` | 'top' \| 'bottom' | bottom | Which side of the anchor the bubble prefers. Auto-flips to the other side when there isn't room. |
+| `round?` | boolean \| number \| string | — | Round the bubble to a 20px radius (matching a round menu). Pass a `number` (px) or a CSS length string for a custom radius. |
+| `truncatedOnly?` | boolean | — | Only show when the target is actually truncated (its text overflows and is ellipsized); a label that fits gets no tooltip. The check is a UI-thread layout read, re-measured on each show. By default it measures every Anta ellipsizing label part inside the anchor, then the anchor itself — override with `truncatedSelector`. |
+| `truncatedSelector?` | string | — | CSS selector (resolved within the anchor) for the element or elements whose overflow decides whether a `truncatedOnly` tooltip shows. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -155,6 +143,8 @@ Place `<a-tooltip>` inside the element it describes.
 </a-button>
 ```
 
+## Styling
+
 The bubble lives in shadow DOM and is exposed as a single **part** — style the box
 (background, frost, shadow, radius, padding, a border) with `::part(bubble)`. Its
 *content* is slotted light DOM with a **normalized text baseline** (Anta body