@antadesign/anta 0.3.19 → 0.3.21

package/docs/components/button.md

@@ -471,7 +471,7 @@ without taking ownership of `onClick`.
 
 ### Props
 
-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.
 
 Set `role="button"` and `tabindex="0"` when authoring `<a-button>` directly.
 
@@ -506,7 +506,7 @@ wrapper sets them for you). A native `<button>` also carries its own default
 <button data-anta tone="critical" priority="tertiary">Delete</button>
 ```
 
-Reach for the props first: **`tone`** sets the colour (any CSS colour for a custom
+Reach for the props first: **`tone`** sets the color (any CSS color for a custom
 tone — it derives the whole tone × priority × state curve in oklch), **`priority`**
 the emphasis, **`size`** the dimensions. The focus ring is the global
 [`--focus-ring`](../colors.md#focus-ring).
@@ -520,7 +520,7 @@ CSS (an un-layered rule beats `@layer anta` without `!important`). Set
 `background-color` / `color` **per state**, plus full type control (size,
 line-height, letter-spacing, `font-feature-settings`), padding, radius, even a
 frosted `backdrop-filter` — no need to touch a single token. **`light-dark()`** works
-too (Anta sets `color-scheme` from its theme toggle), so colours adapt to dark mode
+too (Anta sets `color-scheme` from its theme toggle), so colors adapt to dark mode
 with no `.dark` selector. The classes below are just for the demos:
 
 ```css
@@ -537,14 +537,14 @@ a-button.checkout {
 }
 a-button.checkout:hover  { background: linear-gradient(140deg, light-dark(#3a3a42, #fff), light-dark(#161618, #cacace)); }
 a-button.checkout:active { background: linear-gradient(140deg, light-dark(#000, #ececf0), light-dark(#1a1a1c, #fff)); }
-a-button.checkout a-button-label {            /* customised label */
+a-button.checkout a-button-label {            /* customized label */
   text-transform: uppercase;
   letter-spacing: 0.14em;
   font-weight: 600;
 }
 
 /* Second — liquid glass: frost + translucent tint + a diagonal specular sheen,
-   a top/bottom bevel, and a soft lift. Sits on a colourful backdrop so it reads. */
+   a top/bottom bevel, and a soft lift. Sits on a colorful backdrop so it reads. */
 a-button.glass {
   color: #fff;
   background-color: rgba(255, 255, 255, 0.12);
@@ -600,4 +600,4 @@ beyond the button so it can rotate behind the label without exposing an edge.
 
 Don't reach for the resolved `--button-fg` / `--button-bg`: they're recomputed per
 state, so setting one only catches a single state — restyle per state as above, or
-use `tone` for a full custom-colour curve.
+use `tone` for a full custom-color curve.

package/docs/components/card.md

@@ -116,10 +116,9 @@ round (`999px`, clamped to the box). Omit it for the default (`--card-radius`, 8
 
 ## Header controls
 
-There's no dedicated actions slot. For a control at the top-right of the header — a
-"more" button, a tag — pass a laid-out node as the `header` and put the title and
-the control in it yourself (a flex row). You own the layout, so the title and
-control sit exactly where you place them.
+There is no dedicated actions slot. To place a control in the top-right of the
+header, pass a layout node as `header`. For example, use a flex row containing
+the title and a "more" button. That layout determines where both items appear.
 
 ```tsx
 <Card
@@ -179,7 +178,7 @@ out of it — its text is non-selectable and the whole surface navigates.
   href="/docs/ci"
   header={<><Icon shape="book-open" /> CI integration guide</>}
 >
-  Wire Antithesis into your pipeline in a few minutes.
+  Connect your CI pipeline in a few minutes.
 </Card>
 ```
 
@@ -254,7 +253,7 @@ it also blocks navigation until the load resolves.
  color keeps its hue while lightness/chroma are pinned. `'neutral'` (the
  default) is the same as omitting it. |
 
-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.
 
 Slots hold media, header, and footer content. Unslotted content is the card body.
 

package/docs/components/checkbox.md

@@ -6,7 +6,7 @@ The `Checkbox` wrapper renders an `<a-checkbox>` element that manages its own st
 
 ## Tone
 
-`tone` colours the **mark** — the checked-box fill and, for a tinted tone, the
+`tone` colors the **mark** — the checked-box fill and, for a tinted tone, the
 unselected box border (a light shade of the fill that darkens on hover and active,
 like the neutral border; `neutral` keeps a grey border). The label and hint stay
 neutral. Six named tones (`neutral` default), or pass any CSS color for a custom tone.
@@ -29,7 +29,7 @@ read as a validation error. Same value set as `tone`.
 <Checkbox defaultChecked toneSelected="critical">Checked mark tinted</Checkbox>
 ```
 
-## Colouring the text
+## 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
@@ -38,7 +38,7 @@ to tint the whole control.
 
 ```css
 /* Mark via the prop, text via a plain color rule — the label inherits the host
-   colour, the hint is targeted directly. The class is just for the demo — swap
+   color, the hint is targeted directly. The class is just for the demo — swap
    your own selector. */
 a-checkbox.toned-text { color: var(--text-1-critical); }
 a-checkbox.toned-text a-checkbox-hint { color: var(--text-3-critical); }
@@ -56,7 +56,7 @@ Three sizes scale the box **and** the label + hint type together: `small`
 <Checkbox defaultChecked size="large">Large</Checkbox>
 ```
 
-## Label & hint
+## Label and hint
 
 Pass the label as `children` or the `label` prop. Add a `hint` for a secondary line beneath. For a label-less checkbox (e.g. a table "select all"), pass `aria-label`.
 
@@ -177,7 +177,7 @@ Space toggles the checkbox. Follows the [WAI-ARIA checkbox pattern](https://www.
  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 ignored (the element then owns the state). |
+ 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. |
@@ -196,25 +196,24 @@ Space toggles the checkbox. Follows the [WAI-ARIA checkbox pattern](https://www.
  `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 2nd argument — the ergonomic "just give me the new value" callback
- (mirrors `Input`'s `onValueChange`). |
+ 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' | Colour of the **mark** in every state — the checked-box fill *and* the
+| `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 colour keeps its hue + chroma and pins lightness to the
+ 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 — recolour them in plain
+ 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 coloured onto the **checked mark only** — the empty box stays
+| `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. |
 | `value?` | string | "on" | Value submitted with the form when checked — like a native checkbox. |
 
-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 focusable host carries the state. Label and hint are light-DOM children.
 
@@ -242,8 +241,8 @@ treatments.
 </div>
 ```
 
-Reach for the props first: **`tone`** colours the mark in every state,
-**`toneSelected`** only the checked mark (any CSS colour for a custom tone — it
+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.
 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
@@ -251,7 +250,7 @@ text-tone prop. The focus ring is the global
 [`--focus-ring`](../colors.md#focus-ring).
 
 ```tsx
-<Checkbox tone="#e0457b" defaultChecked>Custom colour</Checkbox>
+<Checkbox tone="#e0457b" defaultChecked>Custom color</Checkbox>
 ```
 
 For anything else, `<a-checkbox>` is light-DOM — the **box is `::before`**, the
@@ -262,7 +261,7 @@ without `!important`). The classes below are just for the demos:
 
 ```css
 /* Outlined — an unfilled box: the checked box keeps its background and paints the
-   border + checkmark in the tone colour (light-dark() tunes both themes at once). */
+   border + checkmark in the tone color (light-dark() tunes both themes at once). */
 a-checkbox.outlined:state(checked)::before {
   background: var(--checkbox-bg);
   border-color: light-dark(#5f4bc3, #7460d7);
@@ -272,7 +271,7 @@ a-checkbox.outlined:state(checked)::after {
 }
 
 /* Customized — bold label, bigger circular box, bigger checkmark.
-   Colours use light-dark() so they're tuned for both themes at once. */
+   Colors use light-dark() so they're tuned for both themes at once. */
 a-checkbox.customized { font-weight: 700; }
 a-checkbox.customized::before,
 a-checkbox.customized::after { inline-size: 24px; block-size: 24px; margin-block-start: -2px; }
@@ -284,7 +283,7 @@ a-checkbox.customized:state(checked)::before {
 }
 
 /* Beautified — a full white heart mark swapped in via --checkbox-mask-check
-   (centred by the default mask-position), sized down a touch, on a pink fill */
+   (centered by the default mask-position), sized down a touch, on a pink fill */
 a-checkbox.beautified {
   --checkbox-mask-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54z'/%3E%3C/svg%3E");
 }

package/docs/components/dialog.md

@@ -210,7 +210,7 @@ returns to whatever opened the dialog, from the native `<dialog>`.
 | `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` just removes the ✕, it doesn't make the dialog un-closable. |
+ 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. |
@@ -245,7 +245,7 @@ returns to whatever opened the dialog, from the native `<dialog>`.
  corners at `--dialog-radius`. Omit for the position default: `center` is
  rounded, drawers and `fullscreen` are square. |
 
-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.
 
 Slots hold the header, footer, and close control. Add `tabindex="0"` to every
 raw `<a-button>`.

package/docs/components/expander.md

@@ -94,7 +94,7 @@ it's a no-op there. Use it where the expander sits in a content column
 with room to its left (a prose measure); in a full-width / edge-to-edge
 container the chevron would overhang the edge.
 
-## Title & level
+## Title and level
 
 `title` takes a string or any node. For a string, `level` (1–6) applies
 the matching heading **type scale** — the same scale as `<Title>` —
@@ -114,14 +114,14 @@ horizontally.
 
 When you need real heading **semantics** — so the title lands in a
 page's table of contents (and assistive tech announces it as a heading) —
-pass a `<Title>` (or your own `<h2>`–`<h6>`) as the `title` instead of a
-string. The node owns its own type scale, so set the level on it, not on
-`<Expander>`; a slotted heading keeps its block-rhythm margins, so zero
-them in the header:
+pass a `<Title>` (or an application `<h2>`–`<h6>`) as the `title` instead of a
+string. The heading's `level` sets its type scale, so set it on the heading,
+not on `<Expander>`. A slotted heading keeps its block margins, so reset them
+in the header:
 
 ```tsx
-{/* A node title owns its own scale + heading semantics: set the level on
-   the <Title>, not on <Expander>. (The preview uses element composition
+{/* A Title supplies its type scale and heading semantics. Set the level on
+   the Title, not on Expander. (The preview uses element composition
    because these docs render statically; the title-prop form is identical.) */}
 <Expander title={<Title level={2}>Title level 2 example</Title>}>…</Expander>
 <Expander title={<Title level={4}>Title level 4 example</Title>}>…</Expander>
@@ -214,12 +214,11 @@ state stays as-is — disabling an open expander keeps it open. Header
 
 ## Open state
 
-Leave it uncontrolled and pass `defaultOpen` for the initial state — the
-element owns open/close from there. To drive it yourself, pass `open`
-and handle `onStateChange` (controlled): the expander then only follows
-the prop, and clicking the summary just *requests* a change — apply
-`detail.next` to your state to accept, or ignore it to reject. If you pass
-`open`, you own it.
+For uncontrolled use, pass `defaultOpen` for the initial state. The element
+then updates its open state after interaction. For controlled use, pass `open`
+and handle `onStateChange`. The expander follows the `open` prop and reports a
+requested change. Update application state with `detail.next` to accept it, or
+leave the state unchanged to reject it.
 
 `onStateChange` is event-first: `(event, { next, prev })`, where `next`/`prev`
 are booleans (the requested / previous open state). `statechange` fires
@@ -243,16 +242,15 @@ const [open, setOpen] = useState(false)
 
 ## Controlled vs Uncontrolled
 
-Open state follows Anta's shared **state contract**. Leave it *uncontrolled* and
-the expander owns open/close; pass the controlled prop and *you* own it. The two
-layers speak different idioms — the `<Expander>` wrapper takes booleans, the
-`<a-expander>` element takes a `state` string enum — and the wrapper maps between
-them:
+Open state follows Anta's shared **state contract**. In uncontrolled use, the
+element updates open state. In controlled use, the application supplies it. The
+`<Expander>` wrapper uses booleans; the `<a-expander>` element uses a `state`
+string. The wrapper maps between them:
 
 | | `<Expander>` (JSX) | `<a-expander>` (element) |
 |---|---|---|
-| **Uncontrolled** — element owns it | `defaultOpen` | `default-state="open" \| "closed"` |
-| **Controlled** — you own it | `open` + `onStateChange` | `state="open" \| "closed"` + `statechange` |
+| **Uncontrolled** | `defaultOpen` | `default-state="open" \| "closed"` |
+| **Controlled** | `open` + `onStateChange` | `state="open" \| "closed"` + `statechange` |
 | **Change event** | `onStateChange(event, { next, prev })` — `next` / `prev` are **booleans** | `statechange`, a `CustomEvent<{ next, prev }>` — `'open'` / `'closed'` |
 
 `statechange` is **cancelable** and fires *before* the element applies the
@@ -330,10 +328,9 @@ function Accordion() {
  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:
- the expander only follows this prop, and clicking the summary just
- requests a change via `onStateChange` (so a toggle can be rejected by
- not updating). Leave undefined for uncontrolled. |
+| `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
@@ -352,7 +349,7 @@ function Accordion() {
  its hue while lightness/chroma are pinned. `'neutral'` (the default) is
  the same as omitting it. |
 
-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.
 
 Slots hold the title and actions. The details element contains the collapsible body.
 
@@ -369,7 +366,7 @@ Slots hold the title and actions. The details element contains the collapsible b
 ### Native HTML details
 
 For a simple disclosure, add `data-anta` to native `<details>`. It keeps the
-browser's opening, keyboard, and accessibility behaviour while taking on the
+browser's opening, keyboard, and accessibility behavior while taking on the
 neutral tertiary Expander treatment. Add `priority="secondary"` or `"primary"`
 for a filled surface. `round`, `tone`, tertiary `outdent`, and `level="1"`–`"6"`
 use the matching Expander visual treatments. `level` changes visual type only;
@@ -382,9 +379,9 @@ use a heading inside the summary when you need heading semantics.
 </details>
 ```
 
-Reach for the props first: **`tone`** sets the colour (any CSS colour for a custom
+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 colour a
+heading. Two knobs are worth keeping: **`--expander-tone-source`** (the color a
 custom `tone` derives from — set it to drive the palette from your own variable) and
 **`--expander-gutter`** (the shared left inset that re-insets header + body + chevron
 in lockstep; `outdent` sets it to `0`).
@@ -435,12 +432,12 @@ a-expander.hover-tint::part(summary):active { background: var(--bg-2); }
 ```
 
 **Highlight the title on hover.** The title inherits its `color` from `::part(summary)`,
-so recolour the part on hover and the title (and the `currentColor` chevron) follow — a
+so recolor the part on hover and the title (and the `currentColor` chevron) follow — a
 custom title node that sets its own `color` opts out. Here we also drop the tertiary
 hover underline on the light-DOM `a-expander-summary`:
 
 ```css
-a-expander.title-highlight::part(summary):hover { color: #e5484d; }       /* title colour on hover */
+a-expander.title-highlight::part(summary):hover { color: #e5484d; }       /* title color on hover */
 a-expander.title-highlight a-expander-summary { text-decoration: none; }  /* drop the hover underline */
 ```
 

package/docs/components/icon.md

@@ -31,7 +31,7 @@ accessible loading status.
  noise alongside neighbouring text. |
 | `size?` | number | 16 | Width and height in pixels. |
 
-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.
 
 Set the accessible name on the raw element. Use `--icon-size` for a portable custom
 size.

package/docs/components/input-autocomplete.md

@@ -1,14 +1,14 @@
 # InputAutocomplete
 
-`InputAutocomplete` — a text field whose value is a free string, with a suggestion list that assists
-without constraining. Type anything: a value that isn't in the list stays as you
-typed it, and picking a suggestion fills the field. For a value that must be one of
-the options, use [Select](./select.md) with `filter`.
+`InputAutocomplete` is a text field with a suggestion list. Its value remains a
+free-form string: text that is not in the list stays in the field, and selecting
+a suggestion fills the field. Use [Select](./select.md) with `filter` when the
+value must be one of the options.
 
-It's a **composed component**, an [Input](./input.md) stitched to a [Menu](./menu.md) of
-suggestions. The field text arrives through **`onValueChange`**; `onSelect` fires
-only when a suggestion is chosen. Controlled via `value`, uncontrolled via
-`defaultValue`.
+InputAutocomplete uses an [Input](./input.md) for the field and a [Menu](./menu.md)
+for suggestions. **`onValueChange`** reports field text. `onSelect` runs only
+after someone chooses a suggestion. Use `value` to control it, or `defaultValue`
+for uncontrolled use.
 
 ## Free text is the point
 
@@ -29,7 +29,7 @@ closes the list; clicking the field to place the caret keeps it open.
 
 - **`true`** (default): built-in case-insensitive substring match on each option's
   `value` / `label` / `hint`.
-- **a function** `(option, query) => boolean`: your own matcher, called per option.
+- **a function** `(option, query) => boolean`: a custom matcher, called for each option.
 - **`false`**: show `suggestions` as-is, doing no local filtering. Use this when you
   fetch or filter results yourself (async / remote) and feed the current set through
   `suggestions`.
@@ -44,12 +44,12 @@ Suggestions are bare strings or `SelectOption`s, the same option shape
 | `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 the uncontrolled case (the wrapper then owns it). |
+| `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` does custom matching; `false` shows `suggestions` verbatim so you
- can filter them yourself (async / remote). |
+ 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. |
@@ -61,7 +61,7 @@ Suggestions are bare strings or `SelectOption`s, the same option shape
 | `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 colour — a named tone or any CSS colour. |
+| `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. |
@@ -76,9 +76,8 @@ For browser-native suggestions, pair a native input with a `<datalist>`. It
 keeps free-form entry and lets the browser filter and fill matching options,
 while `data-anta` supplies the field appearance.
 
-The suggestions popup is owned by the browser, so use `InputAutocomplete` when
-you need custom option content, popup styling, or consistent interaction across
-browsers.
+The browser renders the suggestions popup. Use `InputAutocomplete` for custom
+option content, popup styling, or consistent behavior across browsers.
 
 ```html
 <input data-anta type="text" list="people" placeholder="Search people">

package/docs/components/input-date.md

@@ -94,17 +94,19 @@ field converts it (18 → 6 PM).
 The sections below document `Calendar`, the month grid `InputDate` opens. Reach for
 it directly when you want the grid inline, without a field.
 
-`Calendar` is **composed from Anta components in light DOM**, with nothing hidden in
-a shadow root. The days and prev/next chevrons are `<Button>`s (a selected day is a
-`tertiary` Button in its selected state, toned `brand`), inside a form-associated `<a-calendar>`
-grid. Date math runs on the [Temporal API](https://tc39.es/proposal-temporal/docs/),
-bundled via `temporal-polyfill`. For a raw grid, import `buildMonth` from
-`@antadesign/anta`: it returns localized weekday headers and every day record you
-need to render — ISO value, accessible label, and selected, disabled, today, and
-outside-month state. It does not coordinate navigation, roving focus, selection, or
-re-renders for you. The value is an ISO `YYYY-MM-DD` string, never a `Date`. It works
-controlled (`value` + `onStateChange`) or uncontrolled (`defaultValue`), and
-participates in forms under `name`.
+`Calendar` uses Anta components in light DOM; it has no hidden shadow-root UI.
+The day cells and previous/next chevrons are `<Button>`s inside a
+form-associated `<a-calendar>` grid. Date calculations use the
+[Temporal API](https://tc39.es/proposal-temporal/docs/) through
+`temporal-polyfill`.
+
+For a raw grid, import `buildMonth` from `@antadesign/anta`. It returns
+localized weekday headers and day records with ISO values, accessible labels,
+and selected, disabled, today, and outside-month state. It does not manage
+navigation, roving focus, selection, or rendering. The value is an ISO
+`YYYY-MM-DD` string, never a `Date`. Use `value` with `onStateChange` to
+control it, or `defaultValue` for uncontrolled use. It participates in forms
+under `name`.
 
 **Not SSR-safe.** `Calendar` (and `InputDate`, which embeds it) reads the current
 date (`Temporal.Now`) and locale (`navigator.language`) at render, so a server
@@ -241,60 +243,53 @@ stop, and an `aria-live` region announces the month when it changes.
 
 ## Customization
 
-The family stacks in layers: `InputDate` composes `Input` + `Menu` + `Calendar`,
-and `Calendar` itself splits into the `<a-calendar>` element (the day grid) and a
-JSX wrapper (the navigation chrome). Knowing which layer owns what tells you where to
-reach when you extend it, and lets a non-React consumer rebuild the chrome from stock
-elements.
-
-### Components composition
-
-`InputDate` has no `a-inputdate` element; the wrapper is the coordinator, the role
-`Select` plays over `Input` + `Menu`. It renders an editable `<Input>` trigger and a
-`<Menu>` holding a `<Calendar>` (with `time`, the hour/minute row and AM/PM `Tabs`
-sit under the grid), and owns the draft text, the lenient parse on commit, and the
-ISO value. The menu anchors to the field and opens on click (via the `Menu`'s own
-anchor-click trigger, like `Select`) — a mouse open leaves focus in the field so you
-can keep typing, while ↓ opens it and moves focus into the grid. That
-focus move is declarative: `InputDate` bumps `Calendar`'s `focusSignal`, which
-renders a `data-focus` attribute the `<a-calendar>` element reads to focus the active
-day — the wrapper never touches the DOM. Nesting a stateful component in a menu has
-one wrinkle: the `Calendar` (and `Tabs`) dispatch their own
-`statechange`, so the `Menu` acts only on its own `open` / `closed`, and a bubbled
-pick isn't mistaken for a dismiss.
-
-The `<a-calendar>` element owns the grid and nothing else. It wires the day
-`<button>`s you render into it (click and keyboard: arrows, Home/End,
-PageUp/PageDown), holds the submitted value via `ElementInternals`,
-and dispatches the events: `statechange` / `change` on a pick, and `navigate` when a
-key pages past the rendered month. It's framework-agnostic and works on its own, with
-no notion of a "current month" and no sight of `min` / `max`.
-
-Everything above the grid is the JSX wrapper, rendered as **siblings outside**
-`<a-calendar>` from ordinary components: the prev/next arrows are `<Button>`s, and the
-month/year picker is a `<Button>` opening a `<Menu>` of year `MenuItem`s, each a
-submenu of months. The wrapper holds the displayed-month cursor in state, derives the
-day cells and the arrows' `disabled` state from `min` / `max`, and turns a click on an
-arrow, a pick in the menu, or a `navigate` event into a new cursor, then re-renders
-the grid. So range enforcement (disabled days, capped arrows, a disabled picker for a
-single-month range) lives entirely in the wrapper; the element only refuses to
-activate a day you've rendered `disabled`.
-
-That seam is why the element has no `min` / `max` and the switcher is a sibling: the
-grid stays a small, portable authority, and the chrome (Anta `Button`s and a `Menu`)
-is composition you can replace or rebuild. **Without React**, render the grid from the
-exported engine (`buildMonth`) and drive it with the same glue the wrapper packages:
+`InputDate` uses Input, Menu, and Calendar. Calendar uses an `<a-calendar>`
+element for the day grid and a JSX wrapper for navigation. The sections below
+describe which layer provides each behavior and how to recreate the interface
+without React.
+
+### Build it from elements
+
+`InputDate` has no `a-inputdate` element. Its wrapper renders an editable
+`<Input>` and a `<Menu>` containing a `<Calendar>`. When `time` is set, the
+hour/minute fields and AM/PM `Tabs` appear below the grid. The wrapper manages
+draft text, parsing on commit, and the ISO value.
+
+Clicking the field opens the menu while keeping focus in the field. Pressing
+↓ opens the menu and moves focus to the grid. The wrapper passes a
+`focusSignal` to Calendar, which renders `data-focus`; `<a-calendar>` then
+focuses the active day. Calendar and Tabs emit their own `statechange` events,
+but Menu responds only to changes in its own open state.
+
+The `<a-calendar>` element provides grid behavior. It connects the supplied day
+`<button>`s to click and keyboard navigation, including arrows, Home,
+End, PageUp, and PageDown. It stores the form
+value through `ElementInternals` and emits `statechange` / `change` on selection
+and `navigate` when keyboard navigation leaves the displayed month. It is
+framework-agnostic and does not track a current month, `min`, or `max`.
+
+The JSX wrapper renders the controls above the grid as siblings of
+`<a-calendar>`. The previous/next arrows are `<Button>`s. The month/year picker
+is a `<Button>` that opens a `<Menu>` of year `MenuItem`s, each with a month
+submenu. The wrapper stores the displayed-month cursor in state and derives day
+cells and the arrows' `disabled` states from `min` and `max`. A click on an
+arrow, a menu selection, or a `navigate` event updates the cursor and re-renders
+the grid. The wrapper enforces the range. The element only ignores a day that
+was rendered with `disabled`.
+
+The element has no `min` or `max` because the wrapper provides the surrounding
+controls. Without React, render the grid with `buildMonth` and add the
+navigation behavior shown below:
 
 ```html
-<!-- `.calendar` is your own wrapper; the switcher is plain Buttons + a Menu. -->
+<!-- `.calendar` scopes this example. Use an application selector instead. -->
 <div class="calendar" style="display: inline-flex; flex-direction: column; gap: 6px">
   <div style="display: flex; align-items: center">
     <a-button priority="tertiary" data-prev aria-label="Previous month"><a-icon shape="chevron-left"></a-icon></a-button>
     <a-button priority="tertiary" data-heading style="flex: 1; justify-content: center" aria-haspopup="menu"></a-button>
     <a-button priority="tertiary" data-next aria-label="Next month"><a-icon shape="chevron-right"></a-icon></a-button>
   </div>
-  <!-- The element wires whatever day cells you render; it owns selection,
-       keyboard, the form value, and the events. -->
+  <!-- The element provides selection, keyboard behavior, form value, and events. -->
   <a-calendar role="group" name="date"></a-calendar>
 </div>
 <script type="module">
@@ -367,7 +362,7 @@ field treatments.
 ```
 
 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 colours,
+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
 themselves; they sit inside the `<a-calendar>` grid, and the switcher header sits in
 the `.anta-calendar` shell. An un-layered consumer rule beats `@layer anta` without
@@ -384,7 +379,7 @@ the `.anta-calendar` shell. An un-layered consumer rule beats `@layer anta` with
 Each day is a `<a-button data-part="day-cell" data-date="YYYY-MM-DD">`, so a
 specific date is addressable by its `data-date`: tint it, or hang an event marker
 off a `::after` (give the cell `position: relative` first). Below, three days carry a
-brand dot and one is flagged in the critical colour.
+brand dot and one is flagged in the critical color.
 
 ```css
 /* Day cells are `<a-button data-part="day-cell" data-date="YYYY-MM-DD">`. Give them a