@antadesign/anta 0.3.26 → 0.3.28

package/docs/components/card.md

@@ -206,52 +206,29 @@ it also blocks navigation until the load resolves.
 </Card>
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children?` | ReactNode | — | The card body. A string is wrapped in a `<Text>` at secondary priority,
- following the card's `tone` and `size`; pass your own nodes to take over. |
-| `footer?` | ReactNode | — | Footer content, usually action buttons. Rendered as a **left-aligned** row
- (wraps under pressure) — the opposite of `Dialog`'s right-aligned footer. |
-| `header?` | ReactNode | — | Header content, in the top zone. A string is wrapped in a `<Title>` — a real
- heading in the document outline, tinted to match `tone`, at a level that
- tracks `size` (small → 5, medium → 4, large → 3). Pass your own node
- (`<Title level={2}>`, an `<h2>`) for a different level or styling. Omit for
- no header. |
-| `href?` | string | — | Turn the whole card into a link. The card renders a focusable anchor and its
- accessible name comes from `header` → body → this URL (override with
- `aria-label`). A link card is display content — don't nest interactive
- controls inside it. |
-| `icon?` | (string & {}) \| string \| number \| bigint \| boolean \| ReactElement \| Iterable \| ReactPortal \| Promise \| null | — | Leading visual for the header, laid out to the left of the `header` /
- `subtitle` as one aligned row (so it doesn't sit inline in the title, where it
- mis-aligns). A **string** is an icon shape, rendered as an `<Icon>` inside a
- circular chip (sized per the card via `--card-icon-size`); pass an `<img>`,
- initials (`<Text>`), or any node to use it as-is. Omit for none. |
-| `loading?` | boolean | — | Loading state — dims the card with a skeleton pulse, sets `aria-busy`, and (in
- link mode) blocks navigation. |
-| `media?` | ReactNode | — | Media (image, illustration) rendered full-bleed to the card edge, clipped to
- its corners. Position it with `mediaPosition`. |
+| `children?` | ReactNode | — | The card body. A string is wrapped in a `<Text>` at secondary priority, following the card's `tone` and `size`; pass your own nodes to take over. |
+| `footer?` | ReactNode | — | Footer content, usually action buttons. Rendered as a **left-aligned** row (wraps under pressure) — the opposite of `Dialog`'s right-aligned footer. |
+| `header?` | ReactNode | — | Header content, in the top zone. A string is wrapped in a `<Title>` — a real heading in the document outline, tinted to match `tone`, at a level that tracks `size` (small → 5, medium → 4, large → 3). Pass your own node (`<Title level={2}>`, an `<h2>`) for a different level or styling. Omit for no header. |
+| `href?` | string | — | Turn the whole card into a link. The card renders a focusable anchor and its accessible name comes from `header` → body → this URL (override with `aria-label`). A link card is display content — don't nest interactive controls inside it. |
+| `icon?` | (string & {}) \| string \| number \| bigint \| boolean \| ReactElement \| Iterable \| ReactPortal \| Promise \| null | — | Leading visual for the header, laid out to the left of the `header` / `subtitle` as one aligned row (so it doesn't sit inline in the title, where it mis-aligns). A **string** is an icon shape, rendered as an `<Icon>` inside a circular chip (sized per the card via `--card-icon-size`); pass an `<img>`, initials (`<Text>`), or any node to use it as-is. Omit for none. |
+| `loading?` | boolean | — | Loading state — dims the card with a skeleton pulse, sets `aria-busy`, and (in link mode) blocks navigation. |
+| `media?` | ReactNode | — | Media (image, illustration) rendered full-bleed to the card edge, clipped to its corners. Position it with `mediaPosition`. |
 | `mediaPosition?` | 'top' \| 'bottom' \| 'left' \| 'right' | 'top' | Which edge the `media` bleeds to. |
 | `ping?` | string | — | Space-separated URLs the browser pings on navigation (only with `href`). |
-| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'primary' | Surface emphasis. `primary` (the default) is a clean sheet; `secondary` is a
- subtle fill; `tertiary` is a frosted, semi-transparent panel with a backdrop
- blur. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'primary' | Surface emphasis. `primary` (the default) is a clean sheet; `secondary` is a subtle fill; `tertiary` is a frosted, semi-transparent panel with a backdrop blur. |
 | `rel?` | string | — | Anchor rel (only with `href`). |
-| `round?` | boolean \| number \| string | — | Fully-round corners (`border-radius: 999px`, clamped to the box). Pass a
- `number` (px) or a CSS length string (`'1rem'`) for a custom radius. Omit for
- the default `--card-radius`. |
-| `selected?` | boolean | — | Selected / chosen state — draws an inset ring in the tone color, for
- choice-card / plan-picker patterns. |
+| `round?` | boolean \| number \| string | — | Fully-round corners (`border-radius: 999px`, clamped to the box). Pass a `number` (px) or a CSS length string (`'1rem'`) for a custom radius. Omit for the default `--card-radius`. |
+| `selected?` | boolean | — | Selected / chosen state — draws an inset ring in the tone color, for choice-card / plan-picker patterns. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant — scales the padding. |
-| `subtitle?` | ReactNode | — | A secondary line under the header title, rendered as smaller text
- (`<Text size="small">`) in the heading section. Tinted to match `tone`, like
- the title. Omit for no subtitle. |
+| `subtitle?` | ReactNode | — | A secondary line under the header title, rendered as smaller text (`<Text size="small">`) in the heading section. Tinted to match `tone`, like the title. Omit for no subtitle. |
 | `target?` | string | — | Anchor target (only with `href`). |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for
- a one-off custom tone. Named tones re-point the surface + text; a custom
- color keeps its hue while lightness/chroma are pinned. `'neutral'` (the
- default) is the same as omitting it. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone. Named tones re-point the surface + text; a custom color keeps its hue while lightness/chroma are pinned. `'neutral'` (the default) is the same as omitting it. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -267,6 +244,8 @@ Slots hold media, header, and footer content. Unslotted content is the card body
 </a-card>
 ```
 
+## Styling
+
 Reach for the props first: **`tone`** sets the color (any CSS color for a custom
 tone — it derives the surface in oklch), **`priority`** the fill, **`size`** the
 padding. The one custom-color knob worth keeping is **`--card-tone-source`** (the

package/docs/components/checkbox.md

@@ -20,20 +20,20 @@ neutral. Six named tones (`neutral` default), or pass any CSS color for a custom
 
 ## Selected-only tone
 
-`toneSelected` tones the **checked mark only** — the empty box stays neutral grey
-until it's checked. Reach for it instead of `tone` when a resting tinted border would
-read as a validation error. Same value set as `tone`.
+`toneScope="selected"` applies the checkbox's `tone` to the **checked mark only** —
+the empty box stays neutral grey until it's checked. Use it when a resting tinted
+border would read as a validation error.
 
 ```tsx
-<Checkbox toneSelected="brand">Off stays neutral</Checkbox>
-<Checkbox defaultChecked toneSelected="critical">Checked mark tinted</Checkbox>
+<Checkbox tone="brand" toneScope="selected">Off stays neutral</Checkbox>
+<Checkbox defaultChecked tone="critical" toneScope="selected">Checked mark tinted</Checkbox>
 ```
 
 ## Coloring the text
 
 There's no text-tone prop. To tint the **label**, set `color` on the checkbox with a
 theme-aware `--text-N-{tone}` token (the label inherits it); for the **hint**, add a
-`color` rule on the `a-checkbox-hint` child. Pair either with `tone` / `toneSelected`
+`color` rule on the `a-checkbox-hint` child. Pair either with `tone`
 to tint the whole control.
 
 ```css
@@ -167,52 +167,27 @@ The wrapper sets `role="checkbox"` and `aria-checked` (`"true"` / `"false"` / `"
 
 Space toggles the checkbox. Follows the [WAI-ARIA checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `checked?` | CheckboxValue | — | Controlled checked state. When provided the checkbox is controlled — it
- renders exactly this and never self-applies; `onStateChange` is a *request*
- the consumer accepts by updating this prop. Use `defaultChecked` for an
- uncontrolled checkbox. `'indeterminate'` shows the minus glyph and takes
- visual precedence; clicking it requests `true`. |
-| `defaultChecked?` | CheckboxValue | false | Initial checked state for an uncontrolled checkbox. Read once; later
- changes are ignored and the element updates its state after interaction. |
+| `checked?` | CheckboxValue | — | Controlled checked state. When provided the checkbox is controlled — it renders exactly this and never self-applies; `onStateChange` is a *request* the consumer accepts by updating this prop. Use `defaultChecked` for an uncontrolled checkbox. `'indeterminate'` shows the minus glyph and takes visual precedence; clicking it requests `true`. |
+| `defaultChecked?` | CheckboxValue | false | Initial checked state for an uncontrolled checkbox. Read once; later changes are ignored and the element updates its state after interaction. |
 | `disabled?` | boolean | — | Disable the checkbox (no interaction, dropped from the tab order). |
-| `hint?` | ReactNode | — | Secondary text rendered under the label — explanatory copy, like
- Input's hint. Not part of the accessible name. |
-| `label?` | string | — | Visible label — the *value* of the checkbox (clicked along with the box).
- Convenience for the common single-string case; for richer content (markup,
- a link, an info icon) use `children`. When both are supplied, `label`
- renders first. Required unless `children` or `aria-label` is provided
- (a `role="checkbox"` takes its name from the author, not the markup). |
-| `name?` | string | — | Form field name. Inside a `<form>` the checkbox submits under this name,
- contributing `value` when checked — like a native checkbox. |
-| `onChange?` | (event) => void | — | Fired *after* the checked state changes — a native `change` event (the
- post-apply counterpart to `onStateChange`). Not cancelable. For a controlled
- checkbox this fires once you've updated `checked`. |
-| `onStateChange?` | (event, detail) => void | — | Fired on click / Space *before* the element applies any change. Event-first
- so `event.preventDefault()` is the synchronous veto (uncontrolled mode);
- `detail` carries `{ next, prev }`. In controlled mode the element never
- self-applies — answer by updating `checked`, reject by doing nothing. |
-| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ checked, indeterminate, name, value }` snapshot
- as the second argument, matching `Input`'s `onValueChange`. |
-| `round?` | boolean \| number \| string | — | Round the checkbox mark to a circle (`border-radius: 999px` on the box). Pass
- a `number` (px) or a CSS length string for a rounded-square mark instead. |
+| `hint?` | ReactNode | — | Secondary text rendered under the label — explanatory copy, like Input's hint. Not part of the accessible name. |
+| `label?` | string | — | Visible label — the *value* of the checkbox (clicked along with the box). Convenience for the common single-string case; for richer content (markup, a link, an info icon) use `children`. When both are supplied, `label` renders first. Required unless `children` or `aria-label` is provided (a `role="checkbox"` takes its name from the author, not the markup). |
+| `name?` | string | — | Form field name. Inside a `<form>` the checkbox submits under this name, contributing `value` when checked — like a native checkbox. |
+| `onChange?` | (event) => void | — | Fired *after* the checked state changes — a native `change` event (the post-apply counterpart to `onStateChange`). Not cancelable. For a controlled checkbox this fires once you've updated `checked`. |
+| `onStateChange?` | (event, detail) => void | — | Fired on click / Space *before* the element applies any change. Event-first so `event.preventDefault()` is the synchronous veto (uncontrolled mode); `detail` carries `{ next, prev }`. In controlled mode the element never self-applies — answer by updating `checked`, reject by doing nothing. |
+| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ checked, indeterminate, name, value }` snapshot as the second argument, matching `Input`'s `onValueChange`. |
+| `round?` | boolean \| number \| string | — | Round the checkbox mark to a circle (`border-radius: 999px` on the box). Pass a `number` (px) or a CSS length string for a rounded-square mark instead. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant. small=14px, medium=16px, large=18px box. |
-| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the **mark** in every state — the checked-box fill *and* the
- unselected box border. A named tone or any literal CSS color (`'#ff1493'`,
- `'rebeccapurple'`) for a one-off custom tone. Named tones track light/dark mode
- automatically; a custom color keeps its hue + chroma and pins lightness to the
- fill curve. Use `toneSelected` instead to tone only the checked mark and leave
- the empty box neutral. The label + hint stay neutral — recolor them in plain
- CSS via the theme-aware `--text-N-{tone}` tokens. |
-| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Like `tone`, but colored onto the **checked mark only** — the empty box stays
- neutral grey until it's checked. Prefer this over `tone` when a resting tinted
- border would read as a validation state. Same value set as `tone`; if both are
- set, `tone` governs the off-state border and `toneSelected` the checked fill. |
+| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the **mark**. In the default `all` scope this colors the checked-box fill and unselected box border. A named tone or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone. Named tones track light/dark mode automatically; a custom color keeps its hue + chroma and pins lightness to the fill curve. Set `toneScope="selected"` to tone only the checked mark and leave the empty box neutral. The label + hint stay neutral — recolor them in plain CSS via the theme-aware `--text-N-{tone}` tokens. |
+| `toneScope?` | ToneScope | 'all' | Apply `tone` to every state, or only while checked so the empty box stays neutral. `selected` is useful when a tinted resting border would read as a validation state. |
 | `value?` | string | "on" | Value submitted with the form when checked — like a native checkbox. |
 
+## 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.
@@ -230,20 +205,22 @@ For a standard HTML form, add `data-anta` to a native checkbox. It keeps the
 browser's label behavior, checked and indeterminate states, and form submission
 while using Anta's control surface.
 
-`size`, `tone`, `tone-selected`, and `round` use the matching Checkbox visual
+`size`, `tone`, `tone-scope`, and `round` use the matching Checkbox visual
 treatments.
 
 ```html
 <div style="display: grid; gap: 8px">
   <label><input data-anta type="checkbox" name="updates" size="small" tone="brand"> Product updates</label>
-  <label><input data-anta type="checkbox" name="security" tone-selected="success" checked> Security notices</label>
+  <label><input data-anta type="checkbox" name="security" tone="success" tone-scope="selected" checked> Security notices</label>
   <label><input data-anta type="checkbox" name="billing" size="large" round tone="warning" checked> Billing alerts</label>
 </div>
 ```
 
-Reach for the props first: **`tone`** colors the mark in every state,
-**`toneSelected`** only the checked mark (any CSS color for a custom tone — it
-derives the full rest/hover/active curve in oklch), **`size`** the dimensions + type.
+## Styling
+
+Reach for the props first: **`tone`** chooses the mark color and **`toneScope`**
+chooses whether it applies in `all` states or only while `selected` (any CSS color
+derives the full rest/hover/active curve in oklch); **`size`** controls dimensions + type.
 To tint the label + hint, add a `color` rule (on the host for the label, on
 `a-checkbox-hint` for the hint) with the `--text-N-{tone}` tokens — there's no
 text-tone prop. The focus ring is the global

package/docs/components/dialog.md

@@ -203,47 +203,23 @@ On close, focus returns to whatever opened the dialog, from the native `<dialog>
 </Dialog>
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `children?` | ReactNode | — | The dialog body. Scrolls when it overflows the available height. |
-| `closable?` | boolean | true | Whether the top-right ✕ button is present. It's one way to close the dialog,
- alongside Esc, the backdrop, a `data-dialog-close` / footer action, and your
- own code; `false` removes the ✕ without making the dialog unclosable. |
+| `closable?` | boolean | true | Whether the top-right ✕ button is present. It's one way to close the dialog, alongside Esc, the backdrop, a `data-dialog-close` / footer action, and your own code; `false` removes the ✕ without making the dialog unclosable. |
 | `defaultOpen?` | boolean | — | Initial open state for the uncontrolled case (read once on mount). |
-| `footer?` | ReactNode | — | Footer content, usually the action buttons. Rendered in the bottom zone as
- a right-aligned row (wraps under pressure). Omit for none. |
-| `header?` | ReactNode | — | Header content: a title, or any node. Rendered in the top zone. Omit for a
- chromeless dialog with only a body. |
-| `name?` | string | — | Uncontrolled trigger name. Any element with `data-dialog-open="{name}"`
- opens this dialog, `data-dialog-close="{name}"` closes it. A convenience for
- triggers rendered elsewhere; ignored in controlled mode. |
-| `onStateChange?` | (event, detail) => void | — | Fired before the open state changes, on every user open or dismiss.
- `event` is the cancelable `statechange`: call `event.preventDefault()` to
- veto an *uncontrolled* transition. `detail.next` is the requested open
- state, `detail.prev` the current one (booleans). In controlled mode, apply
- `detail.next` to `open` to accept, or do nothing to reject. |
-| `open?` | boolean | — | Controlled open state. When provided, the consumer owns open/close: the
- dialog only follows this prop, and every user dismiss (Esc, backdrop, close
- button) *requests* a change via `onStateChange` (reject by not updating).
- Leave undefined for uncontrolled. |
-| `persistent?` | boolean | — | Turn off light-dismiss: a backdrop click and Esc no longer close the dialog.
- It stays closable through explicit controls (the ✕ when `closable`, a footer
- action, your own code); `persistent` isn't "un-closable", it stops an
- accidental click or stray Esc from dismissing. For an alert / confirm that
- should be answered deliberately. Omit for the default dismissible behavior. |
-| `position?` | 'center' \| 'left' \| 'right' \| 'top' \| 'bottom' \| 'fullscreen' | 'center' | Placement. `center` (the default) is a centered modal; `left` / `right` /
- `top` / `bottom` turn it into an edge drawer (full height for left/right,
- full width for top/bottom); `fullscreen` fills the whole viewport with no
- edge gap or corner radius. |
-| `round?` | boolean \| number \| 'top' \| 'right' \| 'bottom' \| 'left' \| (string & {}) | — | Corner radius. A side keyword — `'top'` / `'right'` / `'bottom'` / `'left'` —
- rounds only that edge's two corners (at `--dialog-radius`), which pairs with
- a drawer's exposed edge (a bottom sheet → `'top'`, a right drawer → `'left'`).
- A `number` (px) or CSS string rounds all corners at that value; the string
- may be a full `border-radius` shorthand (`'12px 12px 0 0'`). `true` rounds all
- corners at `--dialog-radius`. Omit for the position default: `center` is
- rounded, drawers and `fullscreen` are square. |
+| `footer?` | ReactNode | — | Footer content, usually the action buttons. Rendered in the bottom zone as a right-aligned row (wraps under pressure). Omit for none. |
+| `header?` | ReactNode | — | Header content: a title, or any node. Rendered in the top zone. Omit for a chromeless dialog with only a body. |
+| `name?` | string | — | Uncontrolled trigger name. Any element with `data-dialog-open="{name}"` opens this dialog, `data-dialog-close="{name}"` closes it. A convenience for triggers rendered elsewhere; ignored in controlled mode. |
+| `onStateChange?` | (event, detail) => void | — | Fired before the open state changes, on every user open or dismiss. `event` is the cancelable `statechange`: call `event.preventDefault()` to veto an *uncontrolled* transition. `detail.next` is the requested open state, `detail.prev` the current one (booleans). In controlled mode, apply `detail.next` to `open` to accept, or do nothing to reject. |
+| `open?` | boolean | — | Controlled open state. When provided, the consumer owns open/close: the dialog only follows this prop, and every user dismiss (Esc, backdrop, close button) *requests* a change via `onStateChange` (reject by not updating). Leave undefined for uncontrolled. |
+| `persistent?` | boolean | — | Turn off light-dismiss: a backdrop click and Esc no longer close the dialog. It stays closable through explicit controls (the ✕ when `closable`, a footer action, your own code); `persistent` isn't "un-closable", it stops an accidental click or stray Esc from dismissing. For an alert / confirm that should be answered deliberately. Omit for the default dismissible behavior. |
+| `position?` | 'center' \| 'left' \| 'right' \| 'top' \| 'bottom' \| 'fullscreen' | 'center' | Placement. `center` (the default) is a centered modal; `left` / `right` / `top` / `bottom` turn it into an edge drawer (full height for left/right, full width for top/bottom); `fullscreen` fills the whole viewport with no edge gap or corner radius. |
+| `round?` | boolean \| number \| 'top' \| 'right' \| 'bottom' \| 'left' \| (string & {}) | — | Corner radius. A side keyword — `'top'` / `'right'` / `'bottom'` / `'left'` — rounds only that edge's two corners (at `--dialog-radius`), which pairs with a drawer's exposed edge (a bottom sheet → `'top'`, a right drawer → `'left'`). A `number` (px) or CSS string rounds all corners at that value; the string may be a full `border-radius` shorthand (`'12px 12px 0 0'`). `true` rounds all corners at `--dialog-radius`. Omit for the position default: `center` is rounded, drawers and `fullscreen` are square. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -262,6 +238,8 @@ raw `<a-button>`.
 </a-dialog>
 ```
 
+## Styling
+
 Reach for the props first: **`position`** (modal, drawer edge, or fullscreen),
 **`closable`** (the ✕), **`persistent`** (light-dismiss off), **`round`** (corner
 radius). For everything else, style the shadow **parts** in plain CSS.

package/docs/components/expander.md

@@ -304,50 +304,23 @@ function Accordion() {
 .accordion a-expander:not(:first-child):not(:last-child) { border-radius: 0; }
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `title` | ReactNode | — | Summary (header) content. A string is rendered with the `level`
- type scale; pass a node (e.g. a `<Title>`) for full control or real
- heading semantics in the document outline. |
-| `actions?` | ReactNode | — | Header actions (e.g. buttons, tags) rendered at the end of the
- header row, OUTSIDE the toggle trigger — clicking them never
- toggles, they're separately focusable, and screen readers see them
- as separate controls. |
+| `title` | ReactNode | — | Summary (header) content. A string is rendered with the `level` type scale; pass a node (e.g. a `<Title>`) for full control or real heading semantics in the document outline. |
+| `actions?` | ReactNode | — | Header actions (e.g. buttons, tags) rendered at the end of the header row, OUTSIDE the toggle trigger — clicking them never toggles, they're separately focusable, and screen readers see them as separate controls. |
 | `defaultOpen?` | boolean | — | Initial open state for the uncontrolled case. |
-| `disabled?` | boolean | — | Disables the header: not clickable or focusable, hover affordance
- off, text dimmed. The open state freezes as-is — disabling an open
- expander keeps it open. `actions` stay live; disable them
- separately if needed. |
-| `level?` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 5 | Heading type scale applied to a string `title` (mirrors `<Title>`'s
- levels). Visual only — for outline semantics, pass a `<Title>` as
- the title. |
-| `onStateChange?` | (event, detail) => void | — | Fired before the open state changes. `event` is the cancelable
- `statechange` — call `event.preventDefault()` to veto an *uncontrolled*
- toggle (e.g. confirm before closing). `detail.next` is the requested
- open state, `detail.prev` the current one (booleans). In controlled
- mode, apply `detail.next` to `open` to accept, or do nothing to reject. |
-| `open?` | boolean | — | Controlled open state. When provided, the consumer owns open/close. Selecting
- the summary requests a change through `onStateChange`; omit `open` for
- uncontrolled use. |
-| `outdent?` | boolean | — | Outdent the chevron into the left gutter so the title and body sit
- flush with surrounding content (the docs-header layout). Only takes
- effect with `priority="tertiary"` — on the filled priorities the
- container edge has to bound the chevron, so it's a no-op there. |
-| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'secondary' | Surface emphasis. `secondary` (the default) is a subtle fill;
- `primary` is a more pronounced card; `tertiary` is transparent (the
- bare disclosure). |
-| `round?` | boolean \| number \| string | — | Round corners sized to half the folded (header) height: a pill when folded,
- and — when expanded — the same corner radius rather than a bigger stadium.
- The element measures the header, so it tracks custom header content. Pass a
- `number` (px) or CSS length string for a *fixed* radius that overrides the
- measurement (and skips it) in both states. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`)
- for a one-off custom tone. Named tones re-point the text and (on filled
- priorities) the surface to the matching palette; a custom color keeps
- its hue while lightness/chroma are pinned. `'neutral'` (the default) is
- the same as omitting it. |
+| `disabled?` | boolean | — | Disables the header: not clickable or focusable, hover affordance off, text dimmed. The open state freezes as-is — disabling an open expander keeps it open. `actions` stay live; disable them separately if needed. |
+| `level?` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 5 | Heading type scale applied to a string `title` (mirrors `<Title>`'s levels). Visual only — for outline semantics, pass a `<Title>` as the title. |
+| `onStateChange?` | (event, detail) => void | — | Fired before the open state changes. `event` is the cancelable `statechange` — call `event.preventDefault()` to veto an *uncontrolled* toggle (e.g. confirm before closing). `detail.next` is the requested open state, `detail.prev` the current one (booleans). In controlled mode, apply `detail.next` to `open` to accept, or do nothing to reject. |
+| `open?` | boolean | — | Controlled open state. When provided, the consumer owns open/close. Selecting the summary requests a change through `onStateChange`; omit `open` for uncontrolled use. |
+| `outdent?` | boolean | — | Outdent the chevron into the left gutter so the title and body sit flush with surrounding content (the docs-header layout). Only takes effect with `priority="tertiary"` — on the filled priorities the container edge has to bound the chevron, so it's a no-op there. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'secondary' | Surface emphasis. `secondary` (the default) is a subtle fill; `primary` is a more pronounced card; `tertiary` is transparent (the bare disclosure). |
+| `round?` | boolean \| number \| string | — | Round corners sized to half the folded (header) height: a pill when folded, and — when expanded — the same corner radius rather than a bigger stadium. The element measures the header, so it tracks custom header content. Pass a `number` (px) or CSS length string for a *fixed* radius that overrides the measurement (and skips it) in both states. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone. Named tones re-point the text and (on filled priorities) the surface to the matching palette; a custom color keeps its hue while lightness/chroma are pinned. `'neutral'` (the default) is the same as omitting it. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -379,6 +352,8 @@ use a heading inside the summary when you need heading semantics.
 </details>
 ```
 
+## Styling
+
 Reach for the props first: **`tone`** sets the color (any CSS color for a custom
 tone — it derives the surface in oklch), **`priority`** the fill, **`level`** the
 heading. Two knobs are worth keeping: **`--expander-tone-source`** (the color a

package/docs/components/icon.md

@@ -17,20 +17,122 @@ accessible loading status.
 
 ## Built-in shapes
 
-### Props
+| Shape | Search synonyms |
+| --- | --- |
+| `arrow-left-to-line` | dock, snap, align |
+| `arrow-left` | back, previous, prev |
+| `arrow-narrow-down` | download, fall, down |
+| `arrow-narrow-up-down` | sort, swap, transfer, reorder |
+| `arrow-narrow-up` | upload, rise, up |
+| `arrow-right` | forward, next |
+| `arrow-top-right` | external, open, leave |
+| `asterisk` | star, wildcard |
+| `blank` | spacer, empty, placeholder, space, none |
+| `book-open` | read, docs, documentation |
+| `braces` | code, brackets, json |
+| `bug` | defect, issue, error |
+| `calendar-days` |  |
+| `calendar` | date, schedule |
+| `case-sensitive` | aA, capitalize, case |
+| `chat` | message, comment, discuss |
+| `check` | tick, ok, done, confirm, approve |
+| `chevron-down` | arrow, expand, open, down |
+| `chevron-left` | arrow, back, previous |
+| `chevron-right` | arrow, forward, next |
+| `chevron-up` | arrow, collapse, close, up |
+| `chevrons-right` | skip, fast forward |
+| `circle-check` | success, ok, done |
+| `circle-dot` |  |
+| `circle-large` | dot, marker |
+| `circle-small-solid` |  |
+| `circle-user` | avatar, person, account, contact, profile |
+| `circle` | dot, point |
+| `click` | tap, press, touch |
+| `clock` | time |
+| `cloud-upload` | save, sync, upload, send, export |
+| `columns-3-cog` | columns, table, settings, configure, fields, visibility |
+| `copy` | duplicate, clone |
+| `corner-down-right` | branch, indent, return |
+| `cube` | box, package |
+| `dollar-sign` | currency, money, payment |
+| `dots-vertical` | more, kebab, options |
+| `download` | save, import |
+| `edit` | pencil, modify, rename |
+| `external-link` | open, link, share, outbound |
+| `eye-closed` |  |
+| `eye` |  |
+| `file-down` | download, save |
+| `file` | document, page |
+| `filter-x` | clear filter, reset filter, remove filter |
+| `filter` | sort, narrow |
+| `folder-close` | directory |
+| `folder-open` | directory, browse |
+| `folder-tree` | hierarchy, structure, tree |
+| `hat-glasses` | accessibility, vision, disguise, person |
+| `heart-handshake` | credits, thanks, agreement, deal, partnership |
+| `heart` | like, favorite, love, wishlist |
+| `history-tree` | log, past |
+| `history` | log, past |
+| `home` |  |
+| `hourglass` | progress, time, wait, loading, timer |
+| `info` | information, about, i |
+| `link` | url, href, anchor |
+| `list-collapse` | list, collapse, expand, items |
+| `maximize` | fullscreen, expand |
+| `megaphone` | announcement, broadcast |
+| `menu` | hamburger, list, more |
+| `minimize` | collapse, shrink |
+| `minus` | remove, subtract |
+| `moon` |  |
+| `more` | options, extra |
+| `move-horizontal` | resize, swap, horizontal |
+| `not-equal` | neq, different |
+| `play` | start, run, execute |
+| `plus` | add, new, create |
+| `pointer` |  |
+| `presentation` | slides, deck |
+| `refresh-ccw-dot` |  |
+| `refresh` | reload, sync, update |
+| `regex` | pattern, match |
+| `repeat` | loop, retry, rerun |
+| `rotate-ccw` |  |
+| `rss` | feed, subscribe |
+| `runs-history` | log, past |
+| `scroll-text` | log, output, console |
+| `search-check` | found, validated |
+| `search` | find, magnify, lookup |
+| `send` | submit, share, deliver |
+| `settings` |  |
+| `share` |  |
+| `sparkles` | ai, magic, generate |
+| `square-check-big` |  |
+| `square-menu` |  |
+| `sun` |  |
+| `swatch-book` | palette, color, swatch, paint, design |
+| `table-2` | table, grid, data, spreadsheet, rows, columns |
+| `tag` | label, badge, chip |
+| `text-cursor-input` |  |
+| `text-initial` | text, typography, letter, a |
+| `timer` | stopwatch, countdown, time |
+| `toggle-right` | toggle, switch, on, off, boolean |
+| `trash` | delete, remove, bin |
+| `view` | show, display, preview |
+| `warning-diamond` | error, invalid, alert, danger |
+| `warning-triangle` | alert, danger, caution |
+| `webhook` | integration, hook |
+| `workflow` | pipeline, process, flow |
+| `x` | close, cancel, dismiss, remove, no |
+
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `shape` | IconShape | — | Which icon to render. The set of valid shapes comes from Anta's
- built-in icons plus any consumer-generated shapes (via the
- `IconShapes` interface module augmentation). |
-| `label?` | string | — | Accessible name for the icon. When set, the wrapper exposes
- `role="img"` and `aria-label={label}` so screen readers announce
- the icon. When omitted (the default), the icon is treated as
- decorative — `aria-hidden="true"` is applied so it doesn't add
- noise alongside neighbouring text. |
+| `shape` | IconShape | — | Which icon to render. The set of valid shapes comes from Anta's built-in icons plus any consumer-generated shapes (via the `IconShapes` interface module augmentation). |
+| `label?` | string | — | Accessible name for the icon. When set, the wrapper exposes `role="img"` and `aria-label={label}` so screen readers announce the icon. When omitted (the default), the icon is treated as decorative — `aria-hidden="true"` is applied so it doesn't add noise alongside neighbouring text. |
 | `size?` | number | 16 | Width and height in pixels. |
 
+## Web Component
+
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 Set the accessible name on the raw element. Use `--icon-size` for a portable custom

package/docs/components/input-autocomplete.md

@@ -37,34 +37,30 @@ closes the list; clicking the field to place the caret keeps it open.
 Suggestions are bare strings or `SelectOption`s, the same option shape
 [Select](./select.md) uses: `value`, `label`, `hint`, `icon`, `tone`, `disabled`.
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `suggestions` | string \| SelectOption[] | — | The suggestions: bare strings or `SelectOption`s (`value` / `label` / `hint` /
- `icon` / `tone` / `disabled`). A flat list; picking one fills the field. |
+| `suggestions` | string \| SelectOption[] | — | The suggestions: bare strings or `SelectOption`s (`value` / `label` / `hint` / `icon` / `tone` / `disabled`). A flat list; picking one fills the field. |
 | `clearable?` | boolean | — | Show a clear button while the field has text. |
 | `defaultValue?` | string | — | Initial value for uncontrolled use. |
 | `disabled?` | boolean | — | Disable the field. |
-| `filter?` | boolean \| (option, query) => boolean | true | How suggestions match the text. `true` uses the built-in case-insensitive
- substring match on `value` / `label` / `hint`; a function `(option, query) =>
- boolean` uses a custom matcher; `false` shows `suggestions` unchanged for
- application-provided async or remote filtering. |
+| `filter?` | boolean \| (option, query) => boolean | true | How suggestions match the text. `true` uses the built-in case-insensitive substring match on `value` / `label` / `hint`; a function `(option, query) => boolean` uses a custom matcher; `false` shows `suggestions` unchanged for application-provided async or remote filtering. |
 | `hint?` | ReactNode | — | Hint under the field. |
 | `label?` | ReactNode | — | Field label. |
 | `leading?` | ReactNode | — | Leading adornment inside the field. |
 | `name?` | string | — | Form field name. |
 | `onSelect?` | (option) => void | — | Fires only when a suggestion is chosen, with that option. |
-| `onValueChange?` | (value) => void | — | Fires as the text changes (typing, picking a suggestion, or clearing) with
- the new field text. |
+| `onValueChange?` | (value) => void | — | Fires as the text changes (typing, picking a suggestion, or clearing) with the new field text. |
 | `placeholder?` | string | — | Placeholder text. |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Field size. |
 | `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | — | Validation status. |
 | `statusIcon?` | (string & {}) \| false \| IconShape | — | Status icon override, or `false` to drop it. |
 | `tone?` | string | — | Custom accent color — a named tone or any CSS color. |
 | `trailing?` | ReactNode | — | Trailing adornment inside the field. |
-| `value?` | string | — | Controlled value: the field's text, a **free** string not constrained to a
- suggestion. Leave undefined for uncontrolled. |
+| `value?` | string | — | Controlled value: the field's text, a **free** string not constrained to a suggestion. Leave undefined for uncontrolled. |
+
+## Web Component
 
 `InputAutocomplete` combines an input with a Menu. Reproducing its filtering,
 selection, focus, and popup coordination without the React or Preact wrapper is
@@ -90,6 +86,8 @@ option content, popup styling, or consistent behavior across browsers.
 </datalist>
 ```
 
+## Styling
+
 **The field** is styled through Input's props (`size`, `status`, `tone`, `round`,
 `leading` / `trailing`) and its `::part`s; set its width with `style` / `className`
 (forwarded to the field). **The suggestion popover** takes Menu's `::part(menu)`.