@antadesign/anta 0.3.19 → 0.3.20

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

package/docs/components/input-time.md

@@ -20,14 +20,14 @@ or uncontrolled (`defaultValue`), and submits under `name` via the native form A
 
 Focus a section and edit it with the keyboard: ↑/↓ to step (it
 wraps), PageUp/PageDown for a larger jump on minutes,
-or just type the digits. Home/End, selection, deletion, and
+or enter the digits. Home/End, selection, deletion, and
 paste behave as they do in a native text input. Typing
 `9` then `3` `0` lands `09:30` and moves across the sections on its own; an
 out-of-range digit (a `6` in the minutes) commits and advances immediately.
 Backspace on an empty section selects the previous one. The whole thing
 reads as one field while preserving native caret behavior. In a
 12-hour field, typing a 24-hour hour converts it and flips AM/PM — `18` becomes
-`6 PM` — so pasting a 24-hour time just works.
+`6 PM`, so pasted 24-hour times work.
 
 ```tsx
 <InputTime label="Start time" defaultValue="09:30" onValueChange={(_, { value }) => save(value)} />
@@ -69,7 +69,7 @@ range is clamped to the nearest bound as you step or leave the field, and flags
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `children?` | ReactNode | — | Extra content rendered under the field, above the hint (a no-box child like
- a `<Tooltip>` takes no space and just anchors to the field). |
+ 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. |
@@ -101,12 +101,12 @@ range is clamped to the nearest bound as you step or leave the field, and flags
  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 colour — any literal CSS colour tints the resting + hover
+| `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`. |
 
-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 supply the field label and leading icon.
 
@@ -165,9 +165,9 @@ tighter `1em` line:
 `}</style>
 ```
 
-For a one-off accent, `tone` takes **any literal CSS colour** (e.g. `#7c3aed`) and
+For a one-off accent, `tone` takes **any literal CSS color** (e.g. `#7c3aed`) and
 tints the resting + hover border — the focus ring stays the global ring. It's a
-colour, not a named tone; the named feedback tones live on `status`.
+color, not a named tone; the named feedback tones live on `status`.
 
 ```tsx
 <InputTime label="Accent" tone="#7c3aed" defaultValue="09:30" />

package/docs/components/input.md

@@ -24,7 +24,7 @@ Anta's text scale, so a field lines up with same-size `Text` / `Button`.
 | `medium` | 28px | 15 / 20 | 16px |
 | `large` | 32px | 17 / 22 | 18px |
 
-## Label & hint
+## Label and hint
 
 ```tsx
 <Input label="Display name" defaultValue="Ada Lovelace" />
@@ -75,8 +75,8 @@ recolors it.
 
 It reuses the tone palette but isn't `tone`: **`status` is a validation *state*** (it
 also carries the glyph and, for `critical`, validity), whereas `tone` — elsewhere in
-Anta — is decorative colour. On `Input` the named tones live on `status`; `tone` is
-reserved for a one-off custom border colour.
+Anta — is decorative color. On `Input` the named tones live on `status`; `tone` is
+reserved for a one-off custom border color.
 
 Only `status="critical"` carries validity — it sets `aria-invalid`, flips the
 `:state(invalid)` hook, and reports invalid to a surrounding `<form>` through
@@ -87,7 +87,7 @@ Each status has a default glyph (`critical` → `warning-diamond`, `warning` →
 `circle-small-solid`). Override it with **`statusIcon`** (any shape), or drop it
 with `statusIcon={false}`.
 
-## Leading, trailing & clear
+## Leading, trailing, and clear
 
 ```tsx
 {/* clearable — the clear button shows once there's a value */}
@@ -191,13 +191,13 @@ Autogrow uses CSS `field-sizing` where supported (Chromium, Safari ≥ 26.2) and
 built-in JS resize everywhere else (Firefox, older Safari), so it grows in every
 browser.
 
-## Controlled & uncontrolled
+## Controlled and uncontrolled
 
 ```tsx
-// Uncontrolled — the element owns the value
+// Uncontrolled: the element updates its value after input.
 <Input label="Name" defaultValue="Ada" onChange={(e) => log(e.target.value)} />
 
-// Controlled — you own the value
+// Controlled: application state supplies the value.
 const [v, setV] = useState('')
 <Input label="Name" value={v} onInput={(e) => setV(e.target.value)} />
 ```
@@ -251,7 +251,7 @@ Because `<a-input>` is form-associated, it submits with the surrounding
 needed. `required` participates in native validity, and `<Button type="reset">`
 restores the field to its `defaultValue` via `formResetCallback`.
 
-## Types & validation
+## Types and validation
 
 ```tsx
 <Input type="text"     label="Text" />
@@ -263,7 +263,7 @@ restores the field to its `defaultValue` via `formResetCallback`.
 ```
 
 `type` accepts `text` (default), `email`, `password`, `tel`, `url`, and
-`number` — each gets the right mobile keyboard, autofill behaviour, and native
+`number` — each gets the right mobile keyboard, autofill behavior, and native
 constraint validation. (`search` is omitted on purpose — see above.)
 `number` also takes `min` / `max` / `step`.
 
@@ -433,7 +433,7 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
  `username`, `current-password`, `new-password`, `one-time-code`, or `off`. |
 | `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 just anchors to the field — consistent with how tooltips attach
+ 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
@@ -508,7 +508,7 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
  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 colour — any literal CSS colour tints the resting + hover
+| `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
@@ -523,7 +523,7 @@ this; use `truncate` when an editable field should keep the same treatment. |
  clear/search affordances never appear — Anta owns that chrome. |
 | `value?` | string | — | Controlled value. Pair with `onChange` / `onInput`. |
 
-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 label, hint, and controls around the native field.
 
@@ -563,7 +563,7 @@ their `size` attribute, so Anta does not reuse it. `round` and a custom-color
 ```
 
 Reach for the props first: **`status`** sets a validation tone (border + message),
-**`tone`** a custom accent colour for the border (any CSS colour), **`size`** the
+**`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).
 
 ```tsx
@@ -587,7 +587,7 @@ The border is drawn as an **inset `box-shadow`**, not a real `border`, so its wi
 (`0.5px` → `1px` when a `status` is set) and placement never change the box size —
 the field height stays locked to the matching Button. Drop the leading `inset` to
 draw the border as an outset ring instead. You can also re-point an `--input-*`
-colour token on one instance (`style={{ '--input-border': 'var(--border-1)' }}`)
+color token on one instance (`style={{ '--input-border': 'var(--border-1)' }}`)
 or a wrapping selector; the resolver lives in `@layer anta`, so any un-layered rule
 of yours wins.