@antadesign/anta 0.3.26 → 0.3.28

package/docs/components/input-date.md

@@ -52,42 +52,30 @@ field converts it (18 → 6 PM).
 <InputDate size="large" label="Large" time defaultValue="2026-06-15T09:00" />
 ```
 
+## InputDate props
+
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `clearable?` | boolean | — | Show a clear button once the field has a value. |
 | `defaultValue?` | string | — | Initial value for the uncontrolled case. |
 | `disabled?` | boolean | — | Disable the field and the calendar. |
-| `hint?` | ReactNode | — | Helper text under the field. Replaced by a format hint while the entry is
- unrecognized. |
-| `hour12?` | boolean | — | Force the time cycle when `time` is on: `true` for 12-hour (AM/PM), `false`
- for 24-hour. Omit to follow the locale (`en-US` → 12-hour, most others → 24). |
-| `icon?` | false \| IconShape | calendar-days | Leading icon at the start of the field — the calendar affordance. Pass
- another shape to change it, or `false` to drop it. |
+| `hint?` | ReactNode | — | Helper text under the field. Replaced by a format hint while the entry is unrecognized. |
+| `hour12?` | boolean | — | Force the time cycle when `time` is on: `true` for 12-hour (AM/PM), `false` for 24-hour. Omit to follow the locale (`en-US` → 12-hour, most others → 24). |
+| `icon?` | false \| IconShape | calendar-days | Leading icon at the start of the field — the calendar affordance. Pass another shape to change it, or `false` to drop it. |
 | `label?` | ReactNode | — | Field label, above the control. |
-| `locale?` | string | navigator.language | BCP-47 locale driving the display format, the placeholder mask, parsing order,
- and the calendar. |
+| `locale?` | string | navigator.language | BCP-47 locale driving the display format, the placeholder mask, parsing order, and the calendar. |
 | `max?` | string | — | Latest selectable date (ISO). |
-| `min?` | string | — | Earliest selectable date (ISO). Earlier days disable, and a typed date before
- it stays uncommitted. |
+| `min?` | string | — | Earliest selectable date (ISO). Earlier days disable, and a typed date before it stays uncommitted. |
 | `name?` | string | — | Form field name — the ISO value submits under this key. |
 | `offset?` | number | 4 | Gap in pixels between the field and the calendar menu. |
-| `onValueChange?` | (value, attrs) => void | — | Fired after the value resolves (a recognized entry, a calendar pick, a time
- change, or a clear), with the new ISO value (`''` when cleared) and a
- `{ value, name }` snapshot. An unrecognized entry does not fire it. |
+| `onValueChange?` | (value, attrs) => void | — | Fired after the value resolves (a recognized entry, a calendar pick, a time change, or a clear), with the new ISO value (`''` when cleared) and a `{ value, name }` snapshot. An unrecognized entry does not fire it. |
 | `placeholder?` | string | the locale's format mask (e.g. `MM/DD/YYYY`, `MM/DD/YYYY HH:MM` with `time`) | Placeholder shown when empty. |
-| `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 calendar menu relative to the field. Same values as
- `Menu`; it auto-flips and clamps when space runs out. |
+| `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 calendar menu relative to the field. Same values as `Menu`; it auto-flips and clamps when space runs out. |
 | `round?` | boolean \| number \| string | — | Round the field corners — `true` for fully round, or a number / CSS length. |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Field size. Also sizes the calendar and the time row. |
 | `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | neutral | Validation/feedback tone. An unrecognized entry forces `critical` until fixed. |
-| `time?` | boolean | — | Include a time. The value becomes ISO `YYYY-MM-DDTHH:mm`, the field parses a
- trailing time after a space (`06/15/2026 14:30`, `… 2:30pm`), and the menu
- shows a time row (hours : minutes, an AM/PM toggle in 12-hour locales, then a
- Done button) under the calendar. Picking a day keeps the menu open so you can
- set the time. |
-| `value?` | string | — | Controlled value — ISO `YYYY-MM-DD` (or `YYYY-MM-DDTHH:mm` with `time`), `''`
- for empty. Pair with `onValueChange`; the field and calendar follow it and a
- pick only *requests* a change. |
+| `time?` | boolean | — | Include a time. The value becomes ISO `YYYY-MM-DDTHH:mm`, the field parses a trailing time after a space (`06/15/2026 14:30`, `… 2:30pm`), and the menu shows a time row (hours : minutes, an AM/PM toggle in 12-hour locales, then a Done button) under the calendar. Picking a day keeps the menu open so you can set the time. |
+| `value?` | string | — | Controlled value — ISO `YYYY-MM-DD` (or `YYYY-MM-DDTHH:mm` with `time`), `''` for empty. Pair with `onValueChange`; the field and calendar follow it and a pick only *requests* a change. |
 
 ## Calendar
 
@@ -336,6 +324,26 @@ Tracking the cursor, painting the grid from `buildMonth`, and re-rendering on
 `navigate` is what the React `Calendar` packages, plus the year/month jump menu,
 which uses the same `Menu` composition shown on the [Menu](./menu.md) page.
 
+## Calendar props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label?` | string | — | Accessible name for the grid (defaults to the visible month heading). |
+| `defaultValue?` | string | — | Initial selected date for the uncontrolled case (ISO `YYYY-MM-DD`). |
+| `disabled?` | boolean | — | Disable the whole calendar (not focusable or selectable). |
+| `focusSignal?` | number | — | Move keyboard focus onto the active day. Change this to a new value (e.g. increment a counter) to focus the cursor cell — `InputDate` bumps it when the calendar is opened from the field by keyboard (ArrowDown), so focus lands in the grid. The initial value never focuses; only a change does. |
+| `locale?` | string | navigator.language | BCP-47 locale tag driving first-day-of-week, weekday, and month names. |
+| `max?` | string | — | Latest selectable date (ISO `YYYY-MM-DD`) — later days render disabled. |
+| `min?` | string | — | Earliest selectable date (ISO `YYYY-MM-DD`) — earlier days render disabled. |
+| `name?` | string | — | Form field name — the selected ISO date submits under this key. |
+| `onChange?` | (event) => void | — | Fired *after* the selection changes (post-apply). Not cancelable; for a controlled calendar it fires once you've updated `value`. |
+| `onStateChange?` | (event, detail) => void | — | Fired whenever the selection changes — event-first. `detail` is `{ next, prev, reason }`: `next` / `prev` are ISO date strings (`null` = none); `reason` is `'user'` \| `'reset'` \| `'restore'`. A `'user'` pick fires *before* applying and is **cancelable** — `event.preventDefault()` vetoes it (uncontrolled), or in controlled mode answer by updating `value`. `'reset'` / `'restore'` are not cancelable. |
+| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value, name }` snapshot as the second argument, matching `Input`. |
+| `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size of the whole calendar — scales the day cells, the chevrons, and the weekday / month-heading type together (uses Button's `small` / `medium` / `large` scale). |
+| `value?` | string | — | Controlled selected date — ISO `YYYY-MM-DD`. When provided, the application controls selection: the grid follows this prop and a pick only *requests* a change via `onStateChange`. Leave undefined for uncontrolled. |
+
+## Web Component
+
 `InputDate` has no host element. Rebuilding its text parsing, dropdown calendar,
 localized day grid, month navigation, keyboard navigation, and focus management
 in vanilla JavaScript is significant work, even with Anta's `buildMonth` and
@@ -361,6 +369,8 @@ field treatments.
 <input data-anta type="week" name="sprint-week" value="2026-W25">
 ```
 
+## Styling
+
 The calendar is **light DOM**, so everything is plain CSS, with no shadow parts or
 hidden internals. The days and chevrons are real `<a-button>`s, so their colors,
 hover, focus ring, and selected look come from the Button styles and theme

package/docs/components/input-time.md

@@ -66,47 +66,39 @@ range is clamped to the nearest bound as you step or leave the field, and flags
 <InputTime label="Office hours" size="large" min="09:00" max="17:00" defaultValue="09:30" />
 ```
 
+## InputTime props
+
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `autoFocus?` | boolean | — | Focus this field when its containing `Dialog` opens. |
-| `children?` | ReactNode | — | Extra content rendered under the field, above the hint (a no-box child like
- a `<Tooltip>` takes no space and anchors to the field). |
+| `children?` | ReactNode | — | Extra content rendered under the field, above the hint (a no-box child like a `<Tooltip>` takes no space and anchors to the field). |
 | `clearable?` | boolean | — | Show a clear button once the field has a value. |
 | `defaultValue?` | string | — | Initial value for the uncontrolled case (24-hour `"HH:mm"`). |
 | `dimActions?` | boolean | — | Dim the trailing adornments at rest; they brighten on hover / focus. |
 | `disabled?` | boolean | — | Disable the field. |
 | `hint?` | ReactNode | — | Message below the field. `status` recolors it and prefixes a glyph. |
-| `hour12?` | boolean | — | Force the clock: `true` = 12-hour (AM/PM), `false` = 24-hour. Omit to follow
- the locale. |
-| `icon?` | false \| IconShape | clock | Leading icon at the start of the field — the clock affordance. Pass another
- shape to change it, or `false` to drop it. |
-| `label?` | ReactNode | — | Field label, shown above the control and used as the segment group's
- accessible name. |
-| `locale?` | string | navigator.language | BCP-47 locale driving the clock (12h vs 24h), segment order, separator, and
- the AM/PM text. |
-| `max?` | string | — | Latest allowed time, 24-hour `"HH:mm"`. A complete value above it is clamped
- down (on step / blur) and flagged `rangeOverflow`. |
-| `min?` | string | — | Earliest allowed time, 24-hour `"HH:mm"`. A complete value below it is
- clamped up (on step / blur) and flagged `rangeUnderflow` for form validity. |
+| `hour12?` | boolean | — | Force the clock: `true` = 12-hour (AM/PM), `false` = 24-hour. Omit to follow the locale. |
+| `icon?` | false \| IconShape | clock | Leading icon at the start of the field — the clock affordance. Pass another shape to change it, or `false` to drop it. |
+| `label?` | ReactNode | — | Field label, shown above the control and used as the segment group's accessible name. |
+| `locale?` | string | navigator.language | BCP-47 locale driving the clock (12h vs 24h), segment order, separator, and the AM/PM text. |
+| `max?` | string | — | Latest allowed time, 24-hour `"HH:mm"`. A complete value above it is clamped down (on step / blur) and flagged `rangeOverflow`. |
+| `min?` | string | — | Earliest allowed time, 24-hour `"HH:mm"`. A complete value below it is clamped up (on step / blur) and flagged `rangeUnderflow` for form validity. |
 | `name?` | string | — | Form field name — the 24-hour value submits under this key. |
 | `onBlur?` | (e) => void | — | Fires when the field loses focus. |
 | `onClearInput?` | (e) => void | — | Fires after the built-in clear button has cleared the field. |
 | `onFocus?` | (e) => void | — | Fires when the field gains focus. |
-| `onValueChange?` | (event, attrs) => void | — | Fires on every edit (`input`), with the native event + an `attrs` snapshot
- (`value`, `name`, `empty`, `valid`, `validationMessage`). Also fires on
- `change` (blur) and on clear. |
+| `onValueChange?` | (event, attrs) => void | — | Fires on every edit (`input`), with the native event + an `attrs` snapshot (`value`, `name`, `empty`, `valid`, `validationMessage`). Also fires on `change` (blur) and on clear. |
 | `required?` | boolean | — | Mark the field required (drives native validity). |
 | `round?` | boolean \| number \| string | — | Fully-round the field, or a custom radius (`number` px / CSS length). |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. small=24px, medium=28px, large=32px tall. |
-| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | — | Validation / feedback tone. Only `critical` marks the field invalid; the
- others are advisory. Omit (or `neutral`) for a plain field. |
-| `statusIcon?` | (string & {}) \| false \| IconShape | — | Glyph before the `hint` when `status` is set (per-status default; pass a
- shape to override, or `false` to drop it). |
-| `tone?` | string | — | Custom accent color — any literal CSS color tints the resting + hover
- border (focus ring stays `--focus-ring`); `status` overrides for validation. |
+| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | — | Validation / feedback tone. Only `critical` marks the field invalid; the others are advisory. Omit (or `neutral`) for a plain field. |
+| `statusIcon?` | (string & {}) \| false \| IconShape | — | Glyph before the `hint` when `status` is set (per-status default; pass a shape to override, or `false` to drop it). |
+| `tone?` | string | — | Custom accent color — any literal CSS color tints the resting + hover border (focus ring stays `--focus-ring`); `status` overrides for validation. |
 | `trailing?` | ReactNode | — | Content pinned to the end of the field (after the clear button). |
 | `value?` | string | — | Controlled value — 24-hour `"HH:mm"`. Pair with `onValueChange`. |
 
+## Web Component
+
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 Slots supply the field label and leading icon.

package/docs/components/input.md

@@ -424,106 +424,55 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 `}</style>
 ```
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `autoComplete?` | 'off' \| 'on' \| 'name' \| 'username' \| 'email' \| 'current-password' \| 'new-password' \| 'one-time-code' \| 'tel' \| 'url' \| (string & {}) | — | Native autocomplete token. Overrides the value derived from `type`
- (`email` / `tel` / `url`) — set it for the cases `type` can't express, e.g.
- `username`, `current-password`, `new-password`, `one-time-code`, or `off`. |
+| `autoComplete?` | 'off' \| 'on' \| 'name' \| 'username' \| 'email' \| 'current-password' \| 'new-password' \| 'one-time-code' \| 'tel' \| 'url' \| (string & {}) | — | Native autocomplete token. Overrides the value derived from `type` (`email` / `tel` / `url`) — set it for the cases `type` can't express, e.g. `username`, `current-password`, `new-password`, `one-time-code`, or `off`. |
 | `autoFocus?` | boolean | — | Focus this field when its containing `Dialog` opens. |
-| `children?` | ReactNode | — | Extra content rendered directly under the field, above the hint/error (it
- pushes the message down). A no-box child like an Anta `<Tooltip>` takes no
- space and anchors to the field — consistent with how tooltips attach
- to any other element. Use the named `leading` / `trailing` props for
- in-field content. |
-| `clearable?` | boolean | — | Show a clear button as the first trailing item once the field has a
- value. |
+| `children?` | ReactNode | — | Extra content rendered directly under the field, above the hint/error (it pushes the message down). A no-box child like an Anta `<Tooltip>` takes no space and anchors to the field — consistent with how tooltips attach to any other element. Use the named `leading` / `trailing` props for in-field content. |
+| `clearable?` | boolean | — | Show a clear button as the first trailing item once the field has a value. |
 | `defaultValue?` | string | — | Initial value for the uncontrolled case. |
-| `dimActions?` | boolean | — | Dim the `leading` / `trailing` adornments at rest; they brighten to full
- when the field is hovered or focused (a quiet-until-engaged affordance for
- trailing actions). |
+| `dimActions?` | boolean | — | Dim the `leading` / `trailing` adornments at rest; they brighten to full when the field is hovered or focused (a quiet-until-engaged affordance for trailing actions). |
 | `disabled?` | boolean | — | Disable the field. |
-| `hint?` | ReactNode | — | Message below the field. Neutral helper text by default; `status` recolors
- it and prefixes the matching glyph. |
+| `hint?` | ReactNode | — | Message below the field. Neutral helper text by default; `status` recolors it and prefixes the matching glyph. |
 | `inputMode?` | 'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url' | — | Virtual-keyboard hint. Overrides the value derived from `type`. |
-| `label?` | ReactNode | — | Field label, shown above the control. A string is rendered with the
- label type scale; pass a node for full control. Associated with the
- control as its accessible name (the element mirrors the label text to
- `aria-label`, since `<label for>` can't cross the shadow boundary). |
+| `label?` | ReactNode | — | Field label, shown above the control. A string is rendered with the label type scale; pass a node for full control. Associated with the control as its accessible name (the element mirrors the label text to `aria-label`, since `<label for>` can't cross the shadow boundary). |
 | `leading?` | ReactNode | — | Content pinned to the start of the field (e.g. an icon). |
 | `max?` | number \| string | — |  |
 | `maxLength?` | number | — | Max input length. |
-| `maxRows?` | number | — | Cap the autogrow height (in rows) of a `multiline` field with no `rows`.
- Omit for unbounded growth. |
+| `maxRows?` | number | — | Cap the autogrow height (in rows) of a `multiline` field with no `rows`. Omit for unbounded growth. |
 | `min?` | number \| string | — | Min / max / step — for `type="number"`. |
 | `minLength?` | number | — | Min input length. |
-| `multiline?` | boolean | — | Render a `<textarea>` instead of an `<input>`. Without `rows` it grows
- with its content from one line (capped by `maxRows` if set). Autogrow uses
- CSS `field-sizing` where supported (Chrome/Edge, Safari ≥ 26.2) and falls
- back to a built-in JS resize elsewhere (Firefox, older Safari), so it grows
- in every browser. |
+| `multiline?` | boolean | — | Render a `<textarea>` instead of an `<input>`. Without `rows` it grows with its content from one line (capped by `maxRows` if set). Autogrow uses CSS `field-sizing` where supported (Chrome/Edge, Safari ≥ 26.2) and falls back to a built-in JS resize elsewhere (Firefox, older Safari), so it grows in every browser. |
 | `name?` | string | — | Form field name — submitted with the form via ElementInternals. |
 | `onBlur?` | (e) => void | — | Fires when the field loses focus. |
-| `onChange?` | (e) => void | — | Fires on **commit** (blur / Enter) — the platform `change` semantics, **not**
- React's per-keystroke `onChange`. This is a web component, so `onChange` keeps
- the native meaning; reach for `onInput` (every keystroke) or `onValueChange`
- (both) for live updates. Read `e.target.value`. |
-| `onClearClick?` | (e) => void | — | Fires when the built-in clear button (`clearable`) is clicked, *before*
- the field is cleared. Call `e.preventDefault()` to keep the current value
- — the clear is cancelled and `onClearInput` won't fire. Backed by the
- element's cancelable, bubbling `clearclick` event. |
-| `onClearInput?` | (e) => void | — | Fires after the built-in clear button (`clearable`) has cleared the field
- — so `onInput` / `onChange` fire too — making this useful for reacting
- specifically to a clear. Doesn't fire if `onClearClick` cancelled the
- clear. Backed by the element's bubbling `clearinput` event. |
+| `onChange?` | (e) => void | — | Fires on **commit** (blur / Enter) — the platform `change` semantics, **not** React's per-keystroke `onChange`. This is a web component, so `onChange` keeps the native meaning; reach for `onInput` (every keystroke) or `onValueChange` (both) for live updates. Read `e.target.value`. |
+| `onClearClick?` | (e) => void | — | Fires when the built-in clear button (`clearable`) is clicked, *before* the field is cleared. Call `e.preventDefault()` to keep the current value — the clear is cancelled and `onClearInput` won't fire. Backed by the element's cancelable, bubbling `clearclick` event. |
+| `onClearInput?` | (e) => void | — | Fires after the built-in clear button (`clearable`) has cleared the field — so `onInput` / `onChange` fire too — making this useful for reacting specifically to a clear. Doesn't fire if `onClearClick` cancelled the clear. Backed by the element's bubbling `clearinput` event. |
 | `onFocus?` | (e) => void | — | Fires when the field gains focus. |
 | `onInput?` | (e) => void | — | Fires on every keystroke. Read `e.target.value`. |
-| `onValueChange?` | (event, attrs) => void | — | Unified value-change handler — the easy path for state. Fires on `input`
- *and* `change` (and on clear), with the native `event` plus a convenience
- `attrs` snapshot (`value`, `name`, `empty`, `valid`, `validationMessage`) so
- you can do `setForm(s => ({ ...s, [attrs.name]: attrs.value }))` without
- digging into the event. Use `event.type` to tell a live edit (`input`) from
- a commit (`change`); read `id` / `type` / `className` off `event.target`. |
+| `onValueChange?` | (event, attrs) => void | — | Unified value-change handler — the easy path for state. Fires on `input` *and* `change` (and on clear), with the native `event` plus a convenience `attrs` snapshot (`value`, `name`, `empty`, `valid`, `validationMessage`) so you can do `setForm(s => ({ ...s, [attrs.name]: attrs.value }))` without digging into the event. Use `event.type` to tell a live edit (`input`) from a commit (`change`); read `id` / `type` / `className` off `event.target`. |
 | `pattern?` | string | — | Validation pattern (single-line). |
 | `placeholder?` | string | — | Placeholder shown when empty. |
 | `readOnly?` | boolean | — | Make the field read-only. |
 | `required?` | boolean | — | Mark the field required (drives native validity). |
-| `role?` | string | — | ARIA `role` for the field — e.g. `combobox` when the input drives a
- suggestion `listbox` (see `InputAutocomplete`). Left unset by default. |
-| `round?` | boolean \| number \| string | — | Fully-round the field (`border-radius: 999px`). Pass a `number` (px) or a CSS
- length string for a custom radius. The `clearable` × button always rounds to
- a circle to match (it isn't sized by a custom field value). |
-| `rows?` | number | — | Fixed visible row count — a constant-height `<textarea>` (implies
- `multiline`). |
-| `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. small=24px, medium=28px, large=32px tall; the type scale and
- icon track the size (small 13/16 + 14px icon · medium 15/20 + 16px ·
- large 17/22 + 18px). |
+| `role?` | string | — | ARIA `role` for the field — e.g. `combobox` when the input drives a suggestion `listbox` (see `InputAutocomplete`). Left unset by default. |
+| `round?` | boolean \| number \| string | — | Fully-round the field (`border-radius: 999px`). Pass a `number` (px) or a CSS length string for a custom radius. The `clearable` × button always rounds to a circle to match (it isn't sized by a custom field value). |
+| `rows?` | number | — | Fixed visible row count — a constant-height `<textarea>` (implies `multiline`). |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. small=24px, medium=28px, large=32px tall; the type scale and icon track the size (small 13/16 + 14px icon · medium 15/20 + 16px · large 17/22 + 18px). |
 | `spellCheck?` | boolean | — | Toggle native spell-checking. |
-| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | — | Validation / feedback tone — colors the border + `hint` and prefixes a
- glyph. Only `critical` marks the field invalid (`aria-invalid`, blocks form
- submission, `:state(invalid)`); `success` / `warning` / `info` / `brand`
- are advisory and stay valid. Omit (or `neutral`) for a plain field. |
-| `statusIcon?` | (string & {}) \| false \| IconShape | — | Glyph shown before the `hint` when `status` is set. Each status has a
- default (critical → `warning-diamond`, warning → `warning-triangle`,
- success → `circle-check`, info → `info`, brand → `circle-small-solid`); pass a
- shape to override, or `false` to drop it. `neutral` has no default glyph. |
+| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | — | Validation / feedback tone — colors the border + `hint` and prefixes a glyph. Only `critical` marks the field invalid (`aria-invalid`, blocks form submission, `:state(invalid)`); `success` / `warning` / `info` / `brand` are advisory and stay valid. Omit (or `neutral`) for a plain field. |
+| `statusIcon?` | (string & {}) \| false \| IconShape | — | Glyph shown before the `hint` when `status` is set. Each status has a default (critical → `warning-diamond`, warning → `warning-triangle`, success → `circle-check`, info → `info`, brand → `circle-small-solid`); pass a shape to override, or `false` to drop it. `neutral` has no default glyph. |
 | `step?` | number \| string | — |  |
-| `tone?` | string | — | Custom accent color — any literal CSS color tints the resting + hover
- border (focus ring stays the global `--focus-ring`). For consistency with the
- other controls' custom-tone knob; a `status` still overrides for validation. |
-| `trailing?` | ReactNode | — | Content pinned to the end of the field (e.g. icons, buttons), after the
- clear button when `clearable`. |
-| `truncate?` | boolean | true | Ellipsize an overflowing single-line value. Read-only inputs already do
-this; pass `false` when an editable field should show the full value. |
-| `type?` | 'text' \| 'search' \| 'email' \| 'password' \| 'tel' \| 'url' \| 'number' | text | Single-line input type. Ignored when `multiline`. `search` is a
- **wrapper-only** shorthand: it defaults a leading search icon and a clear
- button (both overridable — pass your own `leading`, or `clearable={false}`)
- and sets `inputmode="search"`, but the DOM input stays `type="text"`. The
- native `search` type never reaches the element, so the browser's own
- clear/search affordances never appear — Anta owns that chrome. |
+| `tone?` | string | — | Custom accent color — any literal CSS color tints the resting + hover border (focus ring stays the global `--focus-ring`). For consistency with the other controls' custom-tone knob; a `status` still overrides for validation. |
+| `trailing?` | ReactNode | — | Content pinned to the end of the field (e.g. icons, buttons), after the clear button when `clearable`. |
+| `truncate?` | boolean | true | Ellipsize an overflowing single-line value. Read-only inputs already do this; pass `false` when an editable field should show the full value. |
+| `type?` | 'text' \| 'search' \| 'email' \| 'password' \| 'tel' \| 'url' \| 'number' | text | Single-line input type. Ignored when `multiline`. `search` is a **wrapper-only** shorthand: it defaults a leading search icon and a clear button (both overridable — pass your own `leading`, or `clearable={false}`) and sets `inputmode="search"`, but the DOM input stays `type="text"`. The native `search` type never reaches the element, so the browser's own clear/search affordances never appear — Anta owns that chrome. |
 | `value?` | string | — | Controlled value. Pair with `onChange` / `onInput`. |
 
+## Web Component
+
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 Slots hold the label, hint, and controls around the native field.
@@ -568,6 +517,8 @@ their `size` attribute, so Anta does not reuse it. `round` and a custom-color
 <input data-anta type="reset" value="Reset">
 ```
 
+## Styling
+
 Reach for the props first: **`status`** sets a validation tone (border + message),
 **`tone`** a custom accent color for the border (any CSS color), **`size`** the
 dimensions. The focus ring is the global [`--focus-ring`](../colors.md#focus-ring).

package/docs/components/loader.md

@@ -52,18 +52,18 @@ label, state, and semantics.
 
 Use `<Loader>` when you need a value, speed, or accessible loading status.
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `label?` | string | — | Accessible name for a standalone loader. Without a label, the loader is
-decorative so nearby status text remains the single announcement. |
+| `label?` | string | — | Accessible name for a standalone loader. Without a label, the loader is decorative so nearby status text remains the single announcement. |
 | `max?` | number | 100 | Upper bound of the range. |
 | `size?` | number | 16 | Width and height in pixels. |
 | `speed?` | number | 0.75 | Seconds per rotation. Pass a positive number. |
 | `tone?` | LoaderTone | — | Color tone for the loader. Omit it to use the standard text-3 color. |
-| `value?` | number \| false | — | Current progress value. Omit this prop, or pass `false`, for an
-indeterminate rotating gradient. |
+| `value?` | number \| false | — | Current progress value. Omit this prop, or pass `false`, for an indeterminate rotating gradient. |
+
+## Web Component
 
 Use a raw `<a-loader>` when you are not using the JSX wrapper. Set its size,
 speed, and determinate percentage with CSS custom properties. `value` selects
@@ -92,6 +92,8 @@ the static ring; `--loader-value` is the percentage it shows.
 When the value is unknown, omit `value` and give a standalone loader an
 accessible name. Mark a loader beside visible status text with `aria-hidden`.
 
+## Styling
+
 The standalone Loader uses the quiet `--text-3` color by default. Set `color`
 directly when it needs a deliberate semantic or one-off color; the `loader`
 icon alias inherits its parent control’s color.

package/docs/components/menu.md

@@ -49,9 +49,8 @@ action. Pass **any CSS color** for a one-off custom tone — its hue and chroma
 kept while the lightness is pinned to match the brand text (resolved through
 `--menu-item-tone-source`).
 
-`toneSelected` applies the tone the same way, but **only while the row is `selected`**
-— an unselected row stays neutral. It's the checkable-menu counterpart to `tone`
-(`Select` uses it to tone the chosen row).
+`toneScope="selected"` applies `tone` **only while the row is `selected`** — an
+unselected row stays neutral. `Select` uses the same pair to tone chosen rows.
 
 ```tsx
 <Menu>
@@ -366,6 +365,8 @@ chevron stay centered on the row, so it composes with a trailing counter.
 </Menu>
 ```
 
+## MenuItemCopy
+
 `MenuItemCopy` is a row that copies to the clipboard when chosen: `copy` for a
 string, `copyNode` for a DOM region, or `copyUrl` for the current URL. It composes
 a `<MenuItem>` with a slotted `<a-copy>` element that performs the write, and
@@ -390,89 +391,32 @@ navigating links.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children?` | ReactNode | — | Item content. With `label` set, children are extra content — most
- notably the nested `<Menu>` for a submenu parent. |
+| `children?` | ReactNode | — | Item content. With `label` set, children are extra content — most notably the nested `<Menu>` for a submenu parent. |
 | `copiedLabel?` | string | Copied | Text in the successful no-icon confirmation. |
 | `copy?` | string | — | Text copied to the clipboard on activation. |
-| `copyNode?` | boolean \| string | — | Copy a DOM node as rich text (`text/html`) + plain text. `true` copies
- the nearest ancestor marked `data-copy-source`; a string is a CSS
- selector for an ancestor region (`closest`). The copy control is stripped
- from the copied output. |
+| `copyNode?` | boolean \| string | — | Copy a DOM node as rich text (`text/html`) + plain text. `true` copies the nearest ancestor marked `data-copy-source`; a string is a CSS selector for an ancestor region (`closest`). The copy control is stripped from the copied output. |
 | `copyUrl?` | true | — | Copy the current page URL (`location.href`). |
 | `copyWithUrl?` | boolean | — | Prefix the copied text with `// URL: <current page URL>`. |
-| `disabled?` | boolean | — | Disable the item: greyed out, not focusable for activation, no close. A
- disabled link also drops its `href`, so it can't navigate. |
-| `hint?` | ReactNode | — | Secondary text under the label — explanatory copy, like `RadioGroup`'s
- option `hint`. Requires `label` (it stacks in a column beneath it). Muted
- (`--text-3`) and tracks the row's `tone`. A string, or any node. |
+| `disabled?` | boolean | — | Disable the item: greyed out, not focusable for activation, no close. A disabled link also drops its `href`, so it can't navigate. |
+| `hint?` | ReactNode | — | Secondary text under the label — explanatory copy, like `RadioGroup`'s option `hint`. Requires `label` (it stacks in a column beneath it). Muted (`--text-3`) and tracks the row's `tone`. A string, or any node. |
 | `icon?` | IconShape | — | Leading icon shape. |
-| `iconPlacement?` | 'leading' \| 'trailing' \| 'none' | 'leading' | Where the copy glyph sits relative to the label — or `'none'` to omit it.
- Without a glyph, a successful copy shows a confirmation label near the
- pointer and leaves the row unchanged. |
-| `iconTrailing?` | IconShape | — | A trailing icon. On a `submenu` item this **overrides** the default
- chevron (omit it to keep the chevron); on a normal item it's the trailing
- glyph (omit for none). |
-| `indeterminate?` | boolean | — | Only meaningful with `selectionIndicator="checkbox"`: render the box in the
- mixed state (`aria-checked="mixed"`) — e.g. a "Select all" row when some but
- not all of its options are selected. |
-| `indicator?` | React.ReactNode | — | Replace the built-in selection-indicator *visual* with your own node,
- rendered at the **leading** edge (where the checkbox / radio sit). Pair with
- `selectionIndicator` to keep the semantics — the row stays the control and
- carries `role` + `aria-checked`; only the drawn mark changes. Suppresses the
- built-in checkbox / radio and the trailing `check` glyph. The node is made
- passive (aria-hidden, no pointer events) so the row receives the click. |
-| `kbd?` | string | — | Trailing shortcut hint, e.g. `"⌘E"`. Anta translates it to
- `aria-keyshortcuts` and hides the visual glyphs from assistive technology.
- Use `+` within a chord and spaces between shortcuts (`"⌘K ⌘S"` becomes
- `"Meta+K Meta+S"`). Pass `aria-keyshortcuts` to override the translation.
- This does not bind the shortcut. |
-| `label?` | ReactNode | — | The item's text. Usually a string, but any node is accepted — e.g. a filtered
- `Select` bolds the matched substring. Omit and pass `children` for richer
- content. |
+| `iconPlacement?` | 'leading' \| 'trailing' \| 'none' | 'leading' | Where the copy glyph sits relative to the label — or `'none'` to omit it. Without a glyph, a successful copy shows a confirmation label near the pointer and leaves the row unchanged. |
+| `iconTrailing?` | IconShape | — | A trailing icon. On a `submenu` item this **overrides** the default chevron (omit it to keep the chevron); on a normal item it's the trailing glyph (omit for none). |
+| `indeterminate?` | boolean | — | Only meaningful with `selectionIndicator="checkbox"`: render the box in the mixed state (`aria-checked="mixed"`) — e.g. a "Select all" row when some but not all of its options are selected. |
+| `indicator?` | React.ReactNode | — | Replace the built-in selection-indicator *visual* with your own node, rendered at the **leading** edge (where the checkbox / radio sit). Pair with `selectionIndicator` to keep the semantics — the row stays the control and carries `role` + `aria-checked`; only the drawn mark changes. Suppresses the built-in checkbox / radio and the trailing `check` glyph. The node is made passive (aria-hidden, no pointer events) so the row receives the click. |
+| `kbd?` | string | — | Trailing shortcut hint, e.g. `"⌘E"`. Anta translates it to `aria-keyshortcuts` and hides the visual glyphs from assistive technology. Use `+` within a chord and spaces between shortcuts (`"⌘K ⌘S"` becomes `"Meta+K Meta+S"`). Pass `aria-keyshortcuts` to override the translation. This does not bind the shortcut. |
+| `label?` | ReactNode | — | The item's text. Usually a string, but any node is accepted — e.g. a filtered `Select` bolds the matched substring. Omit and pass `children` for richer content. |
 | `onCopied?` | (ok) => void | — | Fires after the copy attempt with whether it succeeded. |
-| `onCopyRequest?` | () => void | — | Refresh a dynamic `copy` value before activation. Set the new string in
- application state so the next render updates `copy`. Return values are
- ignored. Fires on pointerdown and Enter/Space keydown. |
-| `onMouseDown?` | (event) => void | — | Raw `mousedown` on the row. Mainly to `preventDefault()` so the row doesn't
- take focus on a mouse press — e.g. a combobox option keeping focus in its
- input field while the click still selects. |
-| `onSelect?` | (event, detail) => void | — | Activation handler — fires when *this* item is chosen (click / Enter /
- Space), unless it's `disabled`. It does **not** fire for a submenu parent
- (clicking that opens the flyout, which isn't a selection) nor for a
- selection bubbling up from a nested submenu. On a link item it fires
- alongside the navigation. Receives the event plus a `{ value, label }`
- detail. |
-| `role?` | string | — | ARIA role override. Defaults to the role implied by `selectionIndicator`
- (`menuitem` / `menuitemcheckbox` / `menuitemradio`); set it to reparent the
- row under a different container role — e.g. `option` inside a `listbox`. |
-| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is
- a persistent background tint, the same resting fill a pressed row shows —
- also the way to flag the current page on a link item. On a checkable row
- (`selectionIndicator` set) it instead drives the leading `checkbox` / `radio`
- indicator and the row's `aria-checked`. |
-| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' | — | Turn the row into a checkable item, driven by `selected` (the row stays the
- control and carries `aria-checked`):
- - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>`
-   (before `icon`); the tint is dropped (the box carries state).
- - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped.
- - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected
-   row *and* the background tint (the canonical single-select look).
- Omit for a plain row (the default). |
-| `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and
- `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the
- `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal
- CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose
- hue + chroma are kept while the lightness is pinned to match the brand text.
- `critical` is the destructive action; `neutral` (the default) is the standard
- gray. |
-| `toneSelected?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Like `tone`, but applied only while the row is `selected` — an unselected row
- stays neutral. The whole selected row (label, icon, tint, and the `checkbox` /
- `radio` indicator) takes the tone. Same value set as `tone`; on a selected row
- `toneSelected` wins over `tone` when both are set. |
-| `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail
- so a shared handler can tell which row was chosen without a per-item
- closure. |
+| `onCopyRequest?` | () => void | — | Refresh a dynamic `copy` value before activation. Set the new string in application state so the next render updates `copy`. Return values are ignored. Fires on pointerdown and Enter/Space keydown. |
+| `onMouseDown?` | (event) => void | — | Raw `mousedown` on the row. Mainly to `preventDefault()` so the row doesn't take focus on a mouse press — e.g. a combobox option keeping focus in its input field while the click still selects. |
+| `onSelect?` | (event, detail) => void | — | Activation handler — fires when *this* item is chosen (click / Enter / Space), unless it's `disabled`. It does **not** fire for a submenu parent (clicking that opens the flyout, which isn't a selection) nor for a selection bubbling up from a nested submenu. On a link item it fires alongside the navigation. Receives the event plus a `{ value, label }` detail. |
+| `role?` | string | — | ARIA role override. Defaults to the role implied by `selectionIndicator` (`menuitem` / `menuitemcheckbox` / `menuitemradio`); set it to reparent the row under a different container role — e.g. `option` inside a `listbox`. |
+| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is a persistent background tint, the same resting fill a pressed row shows — also the way to flag the current page on a link item. On a checkable row (`selectionIndicator` set) it instead drives the leading `checkbox` / `radio` indicator and the row's `aria-checked`. |
+| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' | — | Turn the row into a checkable item, driven by `selected` (the row stays the control and carries `aria-checked`): - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>` (before `icon`); the tint is dropped (the box carries state). - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped. - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected row *and* the background tint (the canonical single-select look). Omit for a plain row (the default). |
+| `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose hue + chroma are kept while the lightness is pinned to match the brand text. `critical` is the destructive action; `neutral` (the default) is the standard gray. |
+| `toneScope?` | ToneScope | 'all' | Apply `tone` to every row state, or only while the row is selected. In `selected` scope, an unselected row and its checkbox/radio indicator stay neutral. |
+| `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail so a shared handler can tell which row was chosen without a per-item closure. |
 
 ## Keyboard
 
@@ -506,6 +450,55 @@ call `event.preventDefault()` to keep the menu as-is (e.g. block a dismiss).
 Controlled, the menu never self-moves — apply `detail.next` to `open` to accept,
 or do nothing to reject. (Submenus are always uncontrolled, regardless of `open`.)
 
+## Menu props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `autoWidth?` | boolean | — | Size the menu to its content instead of flooring its width to the trigger. A root menu is never narrower than its trigger by default; set this for a content menu under a wide trigger (e.g. a calendar below a full-width field) so it wraps its content and left-aligns under the trigger. |
+| `children?` | ReactNode | — | The menu's contents: `MenuItem`, `MenuSeparator`, `MenuGroup`, or any custom element. |
+| `context?` | boolean | — | Open on right-click (the `contextmenu` event) of the trigger region instead of a left click, positioned at the pointer. |
+| `coord?` | boolean | — | Open at the pointer coordinates rather than aligned to the trigger box. Pairs naturally with `context`; on its own it positions a left-click menu at the cursor. |
+| `inset?` | number \| string | 4 | Inner inset for the scroll body and named header/footer content. A number is pixels; a CSS length string is used as written. |
+| `nohover?` | boolean | — | Submenu-only (a `<Menu>` nested inside a `MenuItem`); ignored on a root menu. Submenus open on hover by default (with intent timing) as well as on click — set `nohover` to make this submenu click-only. Hover-intent is mouse-only regardless: on touch (and pen) a submenu always opens on tap and stays open until dismissed. |
+| `offset?` | number | 4 | Gap in pixels between the trigger and the menu. |
+| `onactivedescendant?` | (e) => void | — | Combobox-mode cursor report (raw element event). Fires when the active option changes as arrow keys move the cursor while focus stays in a `[data-menu-search]` filter field; `detail.id` is the active option's `id` (`null` when none). The reactive layer that renders the field reflects this onto its `aria-activedescendant` — the element can't write that light-DOM attribute itself. Passed straight through to the element. |
+| `onStateChange?` | (event, detail) => void | — | Fired before the open state changes — on open, and on every dismiss (Esc, outside-click, scroll, selecting an item). `event` is the cancelable `statechange`; `detail.next`/`detail.prev` are the requested/previous open state (booleans). It's the declarative way to observe a menu, and the handler you pair with `open` to drive a controlled menu (apply `detail.next` to `open`). Uncontrolled, `event.preventDefault()` vetoes the transition (e.g. keep the menu open). |
+| `open?` | boolean | — | Controlled open state. Omit for the default **uncontrolled** menu (it opens/closes itself via its triggers). Pass a boolean to **control** it: the menu's visibility follows `open`, and user dismiss (Esc, outside-click, select) fires `onStateChange` *without* self-closing — you update `open` in response. Submenus are always uncontrolled regardless of this. See STATEFUL-COMPONENTS.md. |
+| `placement?` | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' \| 'bottom' \| 'top' \| 'right-start' \| 'right-end' \| 'left-start' \| 'left-end' \| 'right' \| 'left' | bottom-start | Preferred placement relative to the trigger. `bottom` / `top` place the menu below / above; `right` / `left` place it beside (like a submenu flyout). The cross-axis suffix (`-start` / `-end`) aligns the near / far edges, and no suffix centers on the trigger. The menu flips to the opposite side when the preferred one lacks room, and clamps to the viewport. |
+| `role?` | string | menu | ARIA role of the menu surface. |
+| `round?` | boolean \| number \| string | — | Round the menu: the container softens to a 20px radius and its items go fully round. A `number` (px) or CSS length string tunes the container radius only — items stay full pills. |
+| `stopPropagation?` | boolean \| string \| string[] | — | Contain events so they don't bubble out of the menu to ancestor handlers (e.g. a clickable row the menu sits in). Selecting an item is always contained; this extends it to whole event types. `true` contains `click`; pass an event name or list (`"click pointerdown"`) to contain those. |
+
+## MenuItem props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children?` | ReactNode | — | Item content. With `label` set, children are extra content — most notably the nested `<Menu>` for a submenu parent. |
+| `disabled?` | boolean | — | Disable the item: greyed out, not focusable for activation, no close. A disabled link also drops its `href`, so it can't navigate. |
+| `download?` | string \| boolean | — | Download the resource instead of navigating: `true` / `''` uses the resource's default filename, a string overrides it. |
+| `hint?` | ReactNode | — | Secondary text under the label — explanatory copy, like `RadioGroup`'s option `hint`. Requires `label` (it stacks in a column beneath it). Muted (`--text-3`) and tracks the row's `tone`. A string, or any node. |
+| `href?` | string | — | Renders the item as `<a role="menuitem" data-anta-menu-item href>`. |
+| `icon?` | IconShape | — | Leading icon shape. |
+| `iconTrailing?` | IconShape | — | A trailing icon. On a `submenu` item this **overrides** the default chevron (omit it to keep the chevron); on a normal item it's the trailing glyph (omit for none). |
+| `indeterminate?` | boolean | — | Only meaningful with `selectionIndicator="checkbox"`: render the box in the mixed state (`aria-checked="mixed"`) — e.g. a "Select all" row when some but not all of its options are selected. |
+| `indicator?` | React.ReactNode | — | Replace the built-in selection-indicator *visual* with your own node, rendered at the **leading** edge (where the checkbox / radio sit). Pair with `selectionIndicator` to keep the semantics — the row stays the control and carries `role` + `aria-checked`; only the drawn mark changes. Suppresses the built-in checkbox / radio and the trailing `check` glyph. The node is made passive (aria-hidden, no pointer events) so the row receives the click. |
+| `kbd?` | string | — | Trailing shortcut hint, e.g. `"⌘E"`. Anta translates it to `aria-keyshortcuts` and hides the visual glyphs from assistive technology. Use `+` within a chord and spaces between shortcuts (`"⌘K ⌘S"` becomes `"Meta+K Meta+S"`). Pass `aria-keyshortcuts` to override the translation. This does not bind the shortcut. |
+| `label?` | ReactNode | — | The item's text. Usually a string, but any node is accepted — e.g. a filtered `Select` bolds the matched substring. Omit and pass `children` for richer content. |
+| `onMouseDown?` | (event) => void | — | Raw `mousedown` on the row. Mainly to `preventDefault()` so the row doesn't take focus on a mouse press — e.g. a combobox option keeping focus in its input field while the click still selects. |
+| `onSelect?` | (event, detail) => void | — | Activation handler — fires when *this* item is chosen (click / Enter / Space), unless it's `disabled`. It does **not** fire for a submenu parent (clicking that opens the flyout, which isn't a selection) nor for a selection bubbling up from a nested submenu. On a link item it fires alongside the navigation. Receives the event plus a `{ value, label }` detail. |
+| `ping?` | string | — | Space-separated URLs the browser pings on navigation. |
+| `rel?` | string | — | Anchor rel. |
+| `role?` | string | — | ARIA role override. Defaults to the role implied by `selectionIndicator` (`menuitem` / `menuitemcheckbox` / `menuitemradio`); set it to reparent the row under a different container role — e.g. `option` inside a `listbox`. |
+| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is a persistent background tint, the same resting fill a pressed row shows — also the way to flag the current page on a link item. On a checkable row (`selectionIndicator` set) it instead drives the leading `checkbox` / `radio` indicator and the row's `aria-checked`. |
+| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' | — | Turn the row into a checkable item, driven by `selected` (the row stays the control and carries `aria-checked`): - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>` (before `icon`); the tint is dropped (the box carries state). - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped. - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected row *and* the background tint (the canonical single-select look). Omit for a plain row (the default). |
+| `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
+| `target?` | string | — | Anchor target, e.g. `'_blank'`. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose hue + chroma are kept while the lightness is pinned to match the brand text. `critical` is the destructive action; `neutral` (the default) is the standard gray. |
+| `toneScope?` | ToneScope | 'all' | Apply `tone` to every row state, or only while the row is selected. In `selected` scope, an unselected row and its checkbox/radio indicator stay neutral. |
+| `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail so a shared handler can tell which row was chosen without a per-item closure. |
+
+## Web Component
+
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 Put a focusable trigger immediately before `<a-menu>` and omit `state` for an
@@ -522,6 +515,8 @@ values.
 </a-menu>
 ```
 
+## Styling
+
 The popover surface lives in shadow DOM and is exposed as a **part** — style its
 chrome (background, frost, border, radius, shadow, padding, min-width) with
 `::part(menu)`. Menu items are light DOM, so style them (and their