@antadesign/anta 0.3.19 → 0.3.20

package/docs/components/menu.md

@@ -1,6 +1,6 @@
 # Menu
 
-A dropdown or context menu that anchors to any target and just works. Place
+A dropdown or context menu that anchors to a target. Place
 `<Menu>` immediately after the trigger — a button, an icon, a whole region —
 and it opens on click, positions itself with room-aware flipping, and dismisses
 on outside-click, `Escape`, or scroll. Rows are dedicated **`MenuItem`s** (not
@@ -12,7 +12,7 @@ Open state is uncontrolled by default — pass **`onStateChange`** (event-first:
 observe it, or pass **`open`** to control it, applying `detail.next` to `open`
 from your `onStateChange` handler (submenus stay uncontrolled). `statechange` is
 **cancelable** and fires before the menu moves, so uncontrolled you can keep it
-open with `event.preventDefault()`. You can also grab a `ref` and call
+open with `event.preventDefault()`. You can also keep a `ref` and call
 `.open()` / `.close()` / `.toggle()`.
 
 ## Dropdown from a button
@@ -92,7 +92,7 @@ instead of its full border box. Anta's `Input` does this — it reports its fiel
 box — so a `Menu` placed after an `<Input>` (as in `Select`) lines up with the
 field, not the whole component (whose box also spans the label and hint).
 
-## Right-click & at-cursor
+## Open at the pointer
 
 Pass `context` to open on right-click (the `contextmenu` event) of the region
 the menu follows, positioned at the pointer — ideal for content surfaces like a
@@ -203,7 +203,7 @@ empty-state message (what `Select`'s `renderEmpty` uses).
 </Menu>
 ```
 
-## Pinned header & footer
+## Pinned header and footer
 
 `a-menu-header` and `a-menu-footer` name fixed regions around the scrolling
 items. Put `a-select-header` or `a-select-footer` in the same slots when a
@@ -225,7 +225,7 @@ footer stays the menu's divider.
 </Menu>
 ```
 
-## Custom content & the close contract
+## Custom content and the close behavior
 
 The close decision is read straight from the DOM on click — never from whether a
 handler called `preventDefault` — so it's safe in runtimes where event handlers
@@ -241,7 +241,7 @@ run off the UI thread. Walking out from the click, the nearest marker wins:
   menu without being a `MenuItem`.
 
 For programmatic open/close from app state, drive the `open` prop (the `state`
-attribute, `"open"` / `"closed"`) and react via `onStateChange`, or grab a `ref`
+attribute, `"open"` / `"closed"`) and react via `onStateChange`, or keep a `ref`
 and call `.open()` / `.close()` / `.toggle()`.
 
 ```tsx
@@ -313,7 +313,7 @@ a checkable menu.
 <MenuItem selectionIndicator="checkbox" label="Show archived" selected data-menu-open />
 ```
 
-## Badges, counters & hints
+## Badges, counters, and hints
 
 Drop a `<Tag>` (or any element) as a **child** of a `MenuItem` for a trailing
 counter or badge. Children render after the label but before the `kbd` hint and
@@ -356,6 +356,8 @@ 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. |
 | `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
@@ -363,11 +365,73 @@ navigating links.
  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. |
+| `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 | — | A trailing keyboard-shortcut hint, e.g. `"⌘E"`. |
+| `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 | — | Compute the copy content lazily. Fires on pointerdown / keydown; update
  `copy` (a state change) here and the activation copies the latest value.
  The gap lets the update land even off the UI thread — only the
  serializable `copy` string crosses. |
+| `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. |
 
 ## Keyboard
 
@@ -401,7 +465,7 @@ 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`.)
 
-Use this when you are not using the React or Preact wrapper and a native HTML control does not fit: construct the equivalent Anta web component from the elements below.
+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
 uncontrolled menu. Its light-DOM `<a-menu-item>` rows need their own `tabindex`

package/docs/components/progress.md

@@ -106,7 +106,7 @@ radius.
 | `round?` | boolean \| number \| string | — | Fully-round track (`border-radius: 999px`); the fill is clipped to it. Pass a
  `number` (px) or a CSS length string for a custom radius. |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. Scales the track and the default label row together. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Colour variant, or any literal CSS colour for a one-off custom tone (the
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color variant, or any literal CSS color for a one-off custom tone (the
  surface / indicator / text are derived from it in oklch). Named tones track
  light/dark automatically. |
 | `value?` | number \| false | — | Current progress value. Omit this prop, or pass `false`, to show
@@ -171,7 +171,7 @@ a-progress.fancy::part(indicator) {
 }
 a-progress.fancy::part(indicator)::after { background: none; }   /* hard right edge */
 
-/* the percentage / label / hint are light-DOM children — recolour for the bar */
+/* the percentage / label / hint are light-DOM children — recolor for the bar */
 a-progress.fancy a-progress-number,
 a-progress.fancy a-progress-text { color: #fff; }
 a-progress.fancy a-progress-hint { color: var(--text-2); }

package/docs/components/radio.md

@@ -5,7 +5,7 @@ A single-select control. `RadioGroup` is the whole component — you pass it an
 navigation, and the form value. There's no separate `Radio` component: options
 are data, not markup.
 
-## Options, label & hint
+## Options, label, and hint
 
 ```tsx
 <RadioGroup
@@ -42,12 +42,12 @@ The group's own `label` and `hint` form a header **above** the options: the
 ```
 
 Six named tones — `neutral` (default), `brand`, `info`, `success`, `warning`,
-`critical`. `tone` colours the **mark** in every state — the selected-ring fill + dot
+`critical`. `tone` colors the **mark** in every state — the selected-ring fill + dot
 and (for a tinted tone) the unselected ring border (a light shade of the fill that
 darkens on hover and active; `neutral` keeps a grey ring). The label and hint stay
-neutral — colour them in plain CSS with the `--text-N-{tone}` tokens. Set `tone` on
-the `RadioGroup` to colour every option, or on a single option to override just that
-one. Any literal CSS colour works too, for a one-off custom tone.
+neutral — color them in plain CSS with the `--text-N-{tone}` tokens. Set `tone` on
+the `RadioGroup` to color every option, or on a single option to override just that
+one. Any literal CSS color works too, for a one-off custom tone.
 
 ## Selected-only tone
 
@@ -67,7 +67,7 @@ neutral grey. Reach for it instead of `tone` when a resting tinted border would
 as a validation error. Same tone set; set it on the group, or on a single option to
 override one.
 
-To colour the **label and hint**, there's no prop — add a `color` rule on the
+To color the **label and hint**, there's no prop — add a `color` rule on the
 option's `a-radio-label` / `a-radio-hint` with a `--text-N-{tone}` value.
 
 ## Size
@@ -89,7 +89,7 @@ Three sizes scale the control circle **and** the label + hint type together:
 `large` (18px / 17px). Set it on the `RadioGroup`, or on a single option to
 override one.
 
-## Orientation & layout
+## Orientation and layout
 
 ```tsx
 <RadioGroup
@@ -145,11 +145,11 @@ navigation and dropped from the tab order.
 />
 ```
 
-`status` recolours the group `hint` for feedback — the same tone set as
+`status` recolors the group `hint` for feedback — the same tone set as
 [`Input`](./input.md): `critical`, `warning`, `success`, `info`, `brand`
 (omit for neutral). It styles the message only; drive it from your own validation.
 
-## Keyboard & accessibility
+## Keyboard and accessibility
 
 The group is one Tab stop: `Tab` moves into the selected option (or the first
 enabled one), the arrow keys (`↑`/`↓`/`←`/`→`) move the selection between enabled
@@ -250,8 +250,7 @@ element — `Input`, and the composed `Select` — skip it and expose only
 |------|------|---------|-------------|
 | `options` | RadioOption[] | — | The options. The wrapper renders one `<a-radio>` per entry and computes its
  `selected` / roving `tabindex` / `role` declaratively. |
-| `defaultValue?` | string | — | Initial selected value for the uncontrolled case (the wrapper then owns the
- selection in local state). |
+| `defaultValue?` | string | — | Initial selected value for uncontrolled use. |
 | `disabled?` | boolean | — | Disable the whole group. |
 | `hint?` | string | — | Plain-text description for the group, rendered directly under `label` (above
  the options) — typically instructional copy. Per-option helper text goes on
@@ -272,27 +271,27 @@ element — `Input`, and the composed `Select` — skip it and expose only
  (uncontrolled), or in controlled mode answer by updating `value` (reject by
  doing nothing). `'reset'` (form reset) and `'restore'` (bfcache / autofill) are
  not cancelable — filter on `reason` if you only track user picks. |
-| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value, name }` snapshot as the 2nd argument —
- the ergonomic "just give me the new value" callback (mirrors `Input`). |
+| `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value, name }` snapshot as the second argument,
+ matching `Input`. |
 | `orientation?` | 'vertical' \| 'horizontal' | 'vertical' | Layout + arrow-key axis. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size applied to every option (an option's own `size` wins). |
-| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | 'neutral' | Validation/feedback tone for the group `hint` — recolours it (same tone set
+| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | 'neutral' | Validation/feedback tone for the group `hint` — recolors it (same tone set
  as `Input`'s `status`). Use `critical` for an error message, etc.; omit for
  the neutral default. |
 | `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Mark tone applied to every option (an option's own `tone` wins), or any literal
- CSS color for a one-off custom tone. Colours the selected-ring fill + dot *and*
+ CSS color for a one-off custom tone. Colors the selected-ring fill + dot *and*
  the unselected ring border. Named tones track light/dark mode. Use `toneSelected`
  instead to tone only the selected option and leave the rest neutral. The option
- text stays neutral — recolour it in plain CSS via the `--text-N-{tone}` tokens. |
-| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Like `tone`, but coloured onto the **selected option only** — every unselected
+ text stays neutral — recolor it in plain CSS via the `--text-N-{tone}` tokens. |
+| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Like `tone`, but colored onto the **selected option only** — every unselected
  ring stays neutral grey. Applied to every option (an option's own `toneSelected`
  wins). Prefer this over `tone` when a resting tinted border would read as a
  validation state. |
-| `value?` | string | — | Controlled selected value. When provided, the consumer owns selection: the
- group follows this prop and a pick only *requests* a change via
- `onStateChange` (reject by not updating). Leave undefined for uncontrolled. |
+| `value?` | string | — | Controlled selected value. The group follows this prop and reports a
+ requested change through `onStateChange`. Leave it undefined for
+ uncontrolled use. |
 
-Use this when you are not using the React or Preact wrapper and a native HTML control does not fit: construct the equivalent Anta web component from the elements below.
+Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 The group owns selection and the single tab stop. Put options in `<a-radio-list>`.
 
@@ -323,8 +322,8 @@ treatments.
 </div>
 ```
 
-Reach for the props first: **`tone`** colours the mark in every state,
-**`toneSelected`** only the selected option (any CSS colour for a custom tone, set on
+Reach for the props first: **`tone`** colors the mark in every state,
+**`toneSelected`** only the selected option (any CSS color for a custom tone, set on
 the group or a single option — derives the full curve in oklch), **`size`** the
 dimensions + type. To tint the label + hint, add a `color` rule on the option's
 `a-radio-label` / `a-radio-hint` with the `--text-N-{tone}` values — there's no
@@ -343,7 +342,7 @@ masked — same heart as the checkbox):
 
 ```css
 /* Outlined — an unfilled selected ring: keep the ring background and paint the
-   border + dot in the tone colour (light-dark() tunes both themes at once). */
+   border + dot in the tone color (light-dark() tunes both themes at once). */
 a-radio-group.outlined a-radio:state(selected)::before {
   background: var(--radio-bg);
   border-color: light-dark(#5f4bc3, #7460d7);
@@ -357,7 +356,7 @@ a-radio-group.square a-radio:state(selected)::before { background: light-dark(#0
 a-radio-group.square a-radio:state(selected)::after { background: light-dark(#fff, #000); }   /* contrasting dot */
 
 /* Heart — a bigger ring with a heart mark (the dot ::after, masked) on a pink fill.
-   Same heart SVG as the checkbox; mask-size: contain centres it in the bigger ring. */
+   Same heart SVG as the checkbox; mask-size: contain centers it in the bigger ring. */
 a-radio-group.heart a-radio::before { inline-size: 22px; block-size: 22px; }   /* bigger ring */
 a-radio-group.heart a-radio::after {
   inline-size: 13px; block-size: 13px; border-radius: 0;