@antadesign/anta 0.3.19 → 0.3.20

package/README.md

@@ -1,6 +1,6 @@
 # @antadesign/anta
 
-**Anta** is [Antithesis](https://antithesis.com)'s design system. It provides
+**Anta** is an opinionated design system. It provides
 design tokens, declarative web components, and typed JSX wrappers. Use the same
 components in React, Preact via compat, plain HTML, and custom JSX runtimes via
 `configure()`.

package/dist/anta_helpers.d.ts

@@ -65,10 +65,10 @@ export declare function parseOpenState(v: string | null): 'open' | 'closed';
  *  (e.g. skipping `[disabled]` triggers) lands for every element at once. */
 export declare function installDismissTrigger(host: HTMLElement, attr: string, onDismiss: () => void): void;
 /** The six named tones every toned component shares. Anything else is a literal
- *  CSS colour the element resolves through its `--{component}-tone-source` var. */
+ *  CSS color the element resolves through its `--{component}-tone-source` var. */
 export declare const NAMED_TONES: Set<string>;
 /**
- * Inline-style helper for a custom (non-named) tone: hands the literal colour to
+ * Inline-style helper for a custom (non-named) tone: hands the literal color to
  * the element via `varName` (e.g. `--radio-tone-source`) so the element's CSS
  * derives the fill/text/border curve in oklch. Named tones return `base` unchanged.
  */

package/dist/components/Banner.d.ts

@@ -12,7 +12,7 @@ export interface BannerProps extends BaseProps {
     children?: React.ReactNode;
     /** Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for
      *  a one-off custom tone. Named tones re-point the surface, text, and border
-     *  colour (used if you opt into a border); a custom color keeps its hue while
+     *  color (used if you opt into a border); a custom color keeps its hue while
      *  lightness/chroma are pinned. `'neutral'` (the default) is the same as omitting it.
      *  @defaultValue 'neutral' */
     tone?: "neutral" | "brand" | "info" | "success" | "warning" | "critical" | (string & {});
@@ -22,7 +22,7 @@ export interface BannerProps extends BaseProps {
     round?: boolean | number | string;
     /** Whether the trailing ✕ dismiss button is present. `false` removes it — drive
      *  dismissal yourself (a controlled `dismissed`, or your own control) instead.
-     *  It doesn't make the banner un-dismissible, it just drops the built-in ✕.
+     *  It removes the built-in ✕ without making the banner un-dismissible.
      *  @defaultValue true */
     closable?: boolean;
     /** ARIA role for the strip host. `'status'` (a polite live region, so the notice
@@ -39,7 +39,7 @@ export interface BannerProps extends BaseProps {
     /** Initial dismissed state for the uncontrolled case (read once on mount). */
     defaultDismissed?: boolean;
     /** Fired when the user dismisses the banner (clicks ✕). Uncontrolled, the banner
-     *  hides itself and this just notifies. Controlled, it's how you accept the
+     *  hides itself and this notifies. Controlled, use it to accept the
      *  request — set `dismissed` to `true` (or ignore to reject); pair it with
      *  `dismissed`, or the banner can't be closed. */
     onDismiss?: () => void;

package/dist/components/Button.d.ts

@@ -58,7 +58,7 @@ export type ContentMode = {
  *  don't carry anchor props. (Copy is no longer a Button concern — `ButtonCopy`
  *  composes a `<a-copy>` child; see `copy-props.ts`.)
  *
- *  `href` is **optional** so a conditional URL just works: `href={maybeUrl}`
+ *  `href` is **optional**, so you can pass a conditional URL: `href={maybeUrl}`
  *  (`string | undefined`) type-checks, and a falsy href degrades to a plain
  *  button — a definite string renders `<a role="button">`, an absent / `undefined`
  *  href renders `<a-button>`, mirroring the `href != null` runtime check. Keeping

package/dist/components/Calendar.d.ts

@@ -14,8 +14,8 @@ export interface CalendarChangeAttrs {
 }
 /** Public props for `<Calendar>` — the single-date month grid. */
 export interface CalendarProps extends Omit<BaseProps, "children" | "onChange"> {
-    /** Controlled selected date — ISO `YYYY-MM-DD`. When provided, the consumer owns
-     *  selection: the grid follows this prop and a pick only *requests* a change via
+    /** 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. */
     value?: string;
     /** Initial selected date for the uncontrolled case (ISO `YYYY-MM-DD`). */
@@ -53,23 +53,22 @@ export interface CalendarProps extends Omit<BaseProps, "children" | "onChange">
     /** Fired *after* the selection changes (post-apply). Not cancelable; for a
      *  controlled calendar it fires once you've updated `value`. */
     onChange?: (event: Event) => void;
-    /** Like `onChange`, but with a `{ value, name }` snapshot — the ergonomic
-     *  "just give me the new date" callback (mirrors `Input`). */
+    /** Like `onChange`, but with a `{ value, name }` snapshot as the second argument,
+     *  matching `Input`. */
     onValueChange?: (event: Event, attrs: CalendarChangeAttrs) => void;
 }
 /**
- * `<Calendar>` — a single-date month grid you pick a day from, **composed from
- * Anta components in light DOM** (nothing is hidden in a shadow root): days and
- * the prev/next chevrons are `<Button>`s, so they inherit the design system's
- * states for free — a selected day is literally a `tertiary` Button in its
- * `selected` state, toned `brand` so the active date reads in the brand color.
+ * `<Calendar>` is a single-date month grid. It uses Anta components in light DOM.
+ * Days and the previous/next chevrons are `<Button>`s, so they use the design
+ * system's button states. A selected day is a `tertiary` Button in its `selected`
+ * state, using the `brand` tone so the active date uses the brand color.
  * All date math runs on the Temporal engine
  * (`@antadesign/anta` exports `buildMonth` & friends), and the value is an ISO
  * `YYYY-MM-DD` string.
  *
- * The grid lives in a form-associated `<a-calendar>` element (which owns the
- * submitted value + reset/restore); the wrapper owns view-month, selection,
- * keyboard, and roving `tabindex` — the `RadioGroup` model. The month switcher
+ * The grid lives in a form-associated `<a-calendar>` element, which manages the
+ * submitted value, reset, and restore. The wrapper manages view month, selection,
+ * keyboard, and roving `tabindex`. The month switcher
  * is a sibling rendered *outside* the grid, so it can be extended (month/year
  * pickers) independently.
  *

package/dist/components/Card.d.ts

@@ -93,7 +93,7 @@ export interface CardProps extends BaseProps {
  * @example Link card
  * ```tsx
  * <Card href="/docs/ci" header="CI integration guide">
- *   Wire Antithesis into your pipeline in a few minutes.
+ *   Connect your CI pipeline in a few minutes.
  * </Card>
  * ```
  */

package/dist/components/Card.js

@@ -75,7 +75,7 @@ const Card = ({
         /* @__PURE__ */ jsx(Text, { slot: "header", size: "small", priority: "tertiary", tone: toneAttr, children: subtitle }),
         typeof children === "string" || typeof children === "number" ? (
           // A string / number body becomes a <Text> at secondary priority (text-2,
-          // the body colour) — stated explicitly rather than leaning on the default —
+          // the body color) — stated explicitly rather than leaning on the default —
           // following the card's tone and size. Anything else is a node the caller
           // owns, passed through untouched.
           /* @__PURE__ */ jsx(Text, { priority: "secondary", tone: toneAttr, size, children })

package/dist/components/Checkbox.d.ts

@@ -37,7 +37,7 @@ export interface CheckboxProps extends BaseProps {
      *  visual precedence; clicking it requests `true`. */
     checked?: CheckboxValue;
     /** 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.
      *  @defaultValue false */
     defaultChecked?: CheckboxValue;
     /** Disable the checkbox (no interaction, dropped from the tab order). */
@@ -51,16 +51,16 @@ export interface CheckboxProps extends BaseProps {
     /** Value submitted with the form when checked — like a native checkbox.
      *  @defaultValue "on" */
     value?: string;
-    /** Colour of the **mark** in every state — the checked-box fill *and* the
+    /** 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.
      *  @defaultValue 'neutral' */
     tone?: 'brand' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | (string & {});
-    /** Like `tone`, but coloured onto the **checked mark only** — the empty box stays
+    /** 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.
@@ -82,13 +82,12 @@ export interface CheckboxProps extends BaseProps {
      *  checkbox this fires once you've updated `checked`. */
     onChange?: (event: Event) => 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`. */
     onValueChange?: (event: Event, attrs: CheckboxChangeAttrs) => void;
 }
 /**
- * Checkbox. Renders an `<a-checkbox>` web component that owns the visual
- * state; controlled via `checked` + `onStateChange`, or uncontrolled via
+ * Checkbox. Renders an `<a-checkbox>` web component that provides visual
+ * state; use `checked` with `onStateChange` for controlled use, or
  * `defaultChecked`. Label is `label` (or `children`); `hint` adds secondary
  * text under the label. Requires `@antadesign/anta/elements`.
  *

package/dist/components/Dialog.d.ts

@@ -18,7 +18,7 @@ export interface DialogProps extends Omit<BaseProps, "title"> {
     position?: "center" | "left" | "right" | "top" | "bottom" | "fullscreen";
     /** 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.
      *  @defaultValue true */
     closable?: boolean;
     /** Turn off light-dismiss: a backdrop click and Esc no longer close the dialog.

package/dist/components/Expander.d.ts

@@ -44,10 +44,9 @@ export interface ExpanderProps extends Omit<BaseProps, "title"> {
      *  `number` (px) or CSS length string for a *fixed* radius that overrides the
      *  measurement (and skips it) in both states. */
     round?: boolean | number | string;
-    /** 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. */
+    /** Controlled open state. When provided, the consumer owns open/close. Selecting
+     *  the summary requests a change through `onStateChange`; omit `open` for
+     *  uncontrolled use. */
     open?: boolean;
     /** Initial open state for the uncontrolled case. */
     defaultOpen?: boolean;
@@ -64,12 +63,12 @@ export interface ExpanderProps extends Omit<BaseProps, "title"> {
 /**
  * `<Expander>` — a collapsible disclosure section.
  *
- * A pure, stateless pass-through to `<a-expander>`: the element owns all
+ * A pure, stateless pass-through to `<a-expander>`: the element handles all
  * interaction (toggle, keyboard, ARIA, animation), so the wrapper holds
  * no state and grabs no ref — it only maps props to attributes (safe
  * wherever the host DOM is reconciled, incl. off the UI thread).
  *
- * Uncontrolled (`defaultOpen`): the element owns its open state. The wrapper
+ * Uncontrolled (`defaultOpen`): the element updates its open state. The wrapper
  * emits `default-state="open"` — never `state` — so the DOM carries no stale
  * controlled attribute. Controlled (`open` + `onStateChange`): the wrapper
  * emits `state="open" | "closed"`; the element treats the attribute as the

package/dist/components/Input.d.ts

@@ -19,7 +19,7 @@ export interface InputChangeAttrs {
 export interface InputProps extends BaseProps, DOMEventHandlers {
     /** 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. */
     children?: React.ReactNode;
@@ -41,7 +41,7 @@ export interface InputProps extends BaseProps, DOMEventHandlers {
      *  success → `circle-check`, info → `info`, brand → `circle-small-solid`); pass a
      *  shape to override, or `false` to drop it. `neutral` has no default glyph. */
     statusIcon?: IconShape | (string & {}) | false;
-    /** Custom accent colour — any literal CSS colour tints the resting + hover
+    /** 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. */
     tone?: string;

package/dist/components/Input.js

@@ -126,7 +126,7 @@ const Input = ({
         label != null && (isStringish(label) ? /* @__PURE__ */ jsx("span", { slot: "label", children: label }) : /* @__PURE__ */ jsx("span", { slot: "label", style: { display: "contents" }, children: label })),
         resolvedLeading != null && /* @__PURE__ */ jsx("span", { slot: "leading", style: { display: "contents" }, children: resolvedLeading }),
         resolvedClearable && // A real <a-button> (light DOM → fully styled, keyboard-focusable) in
-        // the element's `clear` slot — the element owns its visibility (shown
+        // the element's `clear` slot — the element controls its visibility (shown
         // only when filled + editable). It fires the bubbling `clearrequest`
         // event via a-button's global listener, so clearing works even without
         // framework hydration; the element turns that into clearclick→clear().

package/dist/components/InputAutocomplete.d.ts

@@ -8,7 +8,7 @@ export interface InputAutocompleteProps extends Omit<BaseProps, 'children'> {
     /** Controlled value: the field's text, a **free** string not constrained to a
      *  suggestion. Leave undefined for uncontrolled. */
     value?: string;
-    /** Initial value for the uncontrolled case (the wrapper then owns it). */
+    /** Initial value for uncontrolled use. */
     defaultValue?: string;
     /** Fires as the text changes (typing, picking a suggestion, or clearing) with
      *  the new field text. */
@@ -17,8 +17,8 @@ export interface InputAutocompleteProps extends Omit<BaseProps, 'children'> {
     onSelect?: (option: SelectOption) => void;
     /** 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.
      *  @defaultValue true */
     filter?: boolean | ((option: SelectOption, query: string) => boolean);
     /** Placeholder text. */
@@ -30,7 +30,7 @@ export interface InputAutocompleteProps extends Omit<BaseProps, 'children'> {
     status?: 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'critical';
     /** Status icon override, or `false` to drop it. */
     statusIcon?: IconShape | (string & {}) | false;
-    /** Custom accent colour — a named tone or any CSS colour. */
+    /** Custom accent color — a named tone or any CSS color. */
     tone?: string;
     /** Show a clear button while the field has text. */
     clearable?: boolean;
@@ -48,10 +48,10 @@ export interface InputAutocompleteProps extends Omit<BaseProps, 'children'> {
     trailing?: React.ReactNode;
 }
 /**
- * `<InputAutocomplete>` — a text field whose value is a free string, with a
- * suggestion dropdown that assists without constraining. Typing something not in
- * the list is valid and stays the value; picking a suggestion just fills the
- * field. For a value that MUST be one of the options, use `Select` with `filter`.
+ * `<InputAutocomplete>` is a text field with a suggestion dropdown. Its value is
+ * a free-form string. Text not in the list remains valid, and choosing a
+ * suggestion fills the field. Use `Select` with `filter` when the value must be
+ * one of the options.
  *
  * Controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
  * Requires `@antadesign/anta/elements` (client-side only).

package/dist/components/InputTime.d.ts

@@ -16,7 +16,7 @@ export interface InputTimeChangeAttrs {
 }
 export interface InputTimeProps extends BaseProps, DOMEventHandlers {
     /** 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). */
     children?: React.ReactNode;
     /** Field label, shown above the control and used as the segment group's
      *  accessible name. */
@@ -29,7 +29,7 @@ export interface InputTimeProps extends BaseProps, DOMEventHandlers {
     /** Glyph before the `hint` when `status` is set (per-status default; pass a
      *  shape to override, or `false` to drop it). */
     statusIcon?: IconShape | (string & {}) | false;
-    /** Custom accent colour — any literal CSS colour tints the resting + hover
+    /** Custom accent color — any literal CSS color tints the resting + hover
      *  border (focus ring stays `--focus-ring`); `status` overrides for validation. */
     tone?: string;
     /** Size variant. small=24px, medium=28px, large=32px tall.
@@ -87,7 +87,7 @@ export interface InputTimeProps extends BaseProps, DOMEventHandlers {
  * behave as one control: each is a native text input — ↑/↓ steps with wrap,
  * ←/→ crosses segments at caret boundaries, typing digits auto-advances, and
  * AM/PM accepts its locale text or `a`/`p`. Renders an `<a-input-time>` web
- * component that owns the segments, navigation, and form value (via
+ * component that manages the segments, navigation, and form value (via
  * `ElementInternals`).
  *
  * The clock and layout follow the locale (`en-US` → 12-hour, most others 24),

package/dist/components/InputTime.js

@@ -79,7 +79,7 @@ const InputTime = ({
       children: [
         label != null && (isStringish(label) ? /* @__PURE__ */ jsx("span", { slot: "label", children: label }) : /* @__PURE__ */ jsx("span", { slot: "label", style: { display: "contents" }, children: label })),
         icon !== false && /* @__PURE__ */ jsx("span", { slot: "leading", style: { display: "contents" }, children: /* @__PURE__ */ jsx(Icon, { shape: icon ?? "clock" }) }),
-        clearable && // Real <a-button> in the element's `clear` slot; the element owns its
+        clearable && // Real <a-button> in the element's `clear` slot; the element controls its
         // visibility (shown only when filled). It fires `clearrequest`, which the
         // element turns into clear(). CONTRACT: `data-custom-event` MUST match
         // CLEAR_TRIGGER in src/elements/a-input-time.ts (string duplicated, not

package/dist/components/Menu.d.ts

@@ -57,7 +57,7 @@ export interface MenuProps extends BaseProps {
     /** 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 owns the field reflects this
+     *  (`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. */
     onactivedescendant?: (e: CustomEvent<{
@@ -78,7 +78,7 @@ export interface MenuProps extends BaseProps {
  *
  * Open state is uncontrolled by default — listen for `onStateChange`
  * (`detail: { next, prev }`) to observe it, or pass `open` to control it. You
- * can also grab a `ref` and call `.open()` / `.close()` / `.toggle()`.
+ * can also keep a `ref` and call `.open()` / `.close()` / `.toggle()`.
  * Selecting a `MenuItem` closes the menu;
  * arbitrary injected content does not. Add `data-menu-open` to any item /
  * container to keep it open, or `data-menu-close` to a custom element to let it

package/dist/components/MenuItem.d.ts

@@ -111,7 +111,7 @@ export type MenuItemActionMode = {
      *  `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 owns the click. */
+     *  passive (aria-hidden, no pointer events) so the row receives the click. */
     indicator?: React.ReactNode;
 };
 export type MenuItemProps = MenuItemCommonProps & (MenuItemLinkMode | MenuItemActionMode);

package/dist/components/MenuItem.js

@@ -81,7 +81,7 @@ const MenuItem = ({
       ...rest,
       children: [
         indicator != null ? (
-          // `min-height: 1lh` makes the wrapper one text line tall and centres the node
+          // `min-height: 1lh` makes the wrapper one text line tall and centers the node
           // in it, so a small indicator aligns with the label's first line in a hinted
           // (top-aligned) row instead of riding at the top.
           /* @__PURE__ */ jsx(

package/dist/components/Progress.d.ts

@@ -6,7 +6,7 @@ export interface ProgressProps extends BaseProps {
     /** Upper bound of the range.
      *  @defaultValue 100 */
     max?: number;
-    /** Colour variant, or any literal CSS colour for a one-off custom tone (the
+    /** 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.
      *  @defaultValue 'neutral' */

package/dist/components/RadioGroup.d.ts

@@ -37,12 +37,11 @@ export interface RadioGroupProps extends Omit<BaseProps, "children" | "onChange"
     /** The options. The wrapper renders one `<a-radio>` per entry and computes its
      *  `selected` / roving `tabindex` / `role` declaratively. */
     options: RadioOption[];
-    /** 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. */
+    /** Controlled selected value. The group follows this prop and reports a
+     *  requested change through `onStateChange`. Leave it undefined for
+     *  uncontrolled use. */
     value?: string;
-    /** Initial selected value for the uncontrolled case (the wrapper then owns the
-     *  selection in local state). */
+    /** Initial selected value for uncontrolled use. */
     defaultValue?: string;
     /** Fired whenever selection changes — event-first. `detail` is
      *  `{ next, prev, reason }`: `next`/`prev` are values (`null` = nothing selected);
@@ -56,8 +55,8 @@ export interface RadioGroupProps extends Omit<BaseProps, "children" | "onChange"
      *  counterpart to `onStateChange`). Not cancelable; for a controlled group it
      *  fires once you've updated `value`. */
     onChange?: (event: Event) => void;
-    /** Like `onChange`, but with a `{ value, name }` snapshot as the 2nd argument —
-     *  the ergonomic "just give me the new value" callback (mirrors `Input`). */
+    /** Like `onChange`, but with a `{ value, name }` snapshot as the second argument,
+     *  matching `Input`. */
     onValueChange?: (event: Event, attrs: RadioChangeAttrs) => void;
     /** Fired when focus enters the group (any option) — wired to `focusin`, since
      *  focus lands on an individual option, not the group element itself. */
@@ -73,19 +72,19 @@ export interface RadioGroupProps extends Omit<BaseProps, "children" | "onChange"
      *  the options) — typically instructional copy. Per-option helper text goes on
      *  the option's own `hint` instead. */
     hint?: string;
-    /** Validation/feedback tone for the group `hint` — recolours it (same tone set
+    /** 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.
      *  @defaultValue 'neutral' */
     status?: "neutral" | "brand" | "info" | "success" | "warning" | "critical";
     /** 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.
+     *  text stays neutral — recolor it in plain CSS via the `--text-N-{tone}` tokens.
      *  @defaultValue 'neutral' */
     tone?: "brand" | "neutral" | "info" | "success" | "warning" | "critical" | (string & {});
-    /** Like `tone`, but coloured onto the **selected option only** — every unselected
+    /** 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.
@@ -104,8 +103,8 @@ export interface RadioGroupProps extends Omit<BaseProps, "children" | "onChange"
  * `<RadioGroup>` — a single-select radio control, rendered from `options`.
  *
  * This wrapper is convenience over the web components: it renders an `<a-radio>`
- * per option and, crucially, owns the two **declarative** DOM concerns the
- * elements deliberately don't touch — the roving **`tabindex`** (so keyboard Tab
+ * per option and manages the two **declarative** DOM concerns the elements
+ * deliberately do not touch: the roving **`tabindex`** (so keyboard Tab
  * lands on the right option) and each radio's **`role`**. Selection itself lives
  * in `<a-radio-group>` off-DOM (it sets each radio's `selected` property), so the
  * elements never mutate the DOM; this wrapper just reflects the current value into

package/dist/components/Select.d.ts

@@ -35,7 +35,7 @@ export interface SelectOption<V extends OptionValue = string> {
      *  hint for the Alt/Option-click "select only this" accelerator; set `tooltip`
      *  to override that, or `''` to suppress it. */
     tooltip?: React.ReactNode;
-    /** Your own data — attach anything and read it in `renderOption`. */
+    /** Additional application data. Read it in `renderOption`. */
     [key: string]: unknown;
 }
 /** A titled group of options rendered **inline** under a heading (like `MenuGroup`).
@@ -164,10 +164,9 @@ export interface SelectCommonProps<V extends OptionValue = string> extends Omit<
      *  `leading` slot). With a custom `renderTrigger`, it's passed through as
      *  `state.icon` instead — the consumer places it. */
     icon?: IconShape;
-    /** Arbitrary content for the default trigger's leading slot (piped straight to
-     *  `Input`'s `leading`) — e.g. a key prefix before the value. Overrides the
-     *  `icon`-derived glyph when both are set; include your own `<Icon>` if you want
-     *  one alongside. Ignored with a custom `renderTrigger`. */
+    /** Content for the default trigger's `leading` slot, such as a key prefix
+     *  before the value. It replaces the icon derived from `icon`. Include an
+     *  `<Icon>` in this content when both are needed. Ignored by `renderTrigger`. */
     leading?: React.ReactNode;
     /** Field label, above the trigger (Input's `label`). */
     label?: string;
@@ -197,11 +196,10 @@ export interface SelectCommonProps<V extends OptionValue = string> extends Omit<
      *  option's **value / label / hint**. Pass a **function** `(option, query) =>
      *  boolean` for custom matching (called per option; return `true` to keep it). */
     filter?: boolean | ((option: SelectOption<V>, query: string) => boolean);
-    /** `multiple` only: a "Select all" row at the top that toggles every enabled
-     *  option (the currently-visible ones when a `filter` query is active); its box
-     *  shows the mixed state when only some are selected. On by default in
-     *  `multiple` mode — set `false` to drop the row (and with it the Alt/⌥-click
-     *  isolate accelerator it gates).
+    /** `multiple` only: shows a "Select all" row that toggles every enabled option,
+     *  or only the visible options when a filter query is active. Its checkbox is
+     *  mixed when some options are selected. It is on by default. Set it to `false`
+     *  to remove the row and the Alt/Option-click shortcut that selects only one row.
      *  @defaultValue true */
     selectAll?: boolean;
     /** Label for the `selectAll` row.
@@ -214,13 +212,12 @@ export interface SelectCommonProps<V extends OptionValue = string> extends Omit<
     /** Label for the `clearable` footer row.
      *  @defaultValue Clear */
     clearLabel?: string;
-    /** Render the **content** of each option row yourself, replacing the built-in
-     *  `label`/`hint`/`icon` layout. Select still supplies the row box, click, ARIA,
-     *  and the selection indicator — you return only what goes *inside*. Read extra
-     *  fields off the option (see `SelectOption`'s index signature) plus an
-     *  `OptionState` (`value`/`selected`/`disabled`). Filtering still works (it
-     *  matches the option's `value`/`label`/`hint`), but match-highlighting is
-     *  skipped — your content owns its own display. */
+    /** Replaces the built-in `label`, `hint`, and `icon` layout for each option row.
+     *  Select still supplies the row container, click handling, ARIA attributes, and
+     *  selection indicator. Read extra option fields through `SelectOption`'s index
+     *  signature. `state` contains `value`, `selected`, and `disabled`. Filtering
+     *  still matches the option's `value`, `label`, and `hint`, but Select cannot
+     *  highlight matches within the returned content. */
     renderOption?: (option: SelectOption<V>, state: OptionState<V>) => React.ReactNode;
     /** Replace each row's selection **mark** with your own node, drawn at the
      *  leading edge. The row stays the control (`role` + `aria-checked` from
@@ -246,16 +243,15 @@ export interface SelectCommonProps<V extends OptionValue = string> extends Omit<
      *  the single-label case built-in). For rich content (chips, multiple nodes)
      *  use `renderTrigger`, which replaces the whole field. */
     renderSummary?: (selected: SelectOption<V>[]) => string | undefined;
-    /** Render your own trigger in place of the default field. Receives a
-     *  `TriggerState` (`open` / `value` / `selected` / `disabled` / `icon`) to drive
-     *  its look. **Return exactly one focusable element** (an Anta `Button`, say) —
-     *  the menu anchors to it (its own previous DOM sibling) and opens it on click,
-     *  so a fragment, multiple siblings, or a non-focusable wrapper will misanchor
-     *  (the menu warns in the console if the trigger has no focusable element). Give
-     *  the element `aria-haspopup="menu"` plus `aria-expanded={state.open}`. The custom
-     *  trigger owns its own styling: the field props (`label`, `hint`, `size`, `status`,
-     *  `placeholder`, `round`) and `className` / `style` apply to the *default* trigger
-     *  only — put your own on the element you return. */
+    /** Replaces the default field with a trigger returned from this function.
+     *  Receives `open`, `value`, `selected`, `disabled`, and `icon`. Return exactly
+     *  one focusable element, such as an Anta `Button`. The menu is positioned
+     *  relative to that element and opens when it is clicked. Do not return a
+     *  fragment, multiple siblings, or a non-focusable wrapper. Add
+     *  `aria-haspopup="menu"` and `aria-expanded={state.open}` to the element.
+     *  Field props (`label`, `hint`, `size`, `status`, `placeholder`, and `round`) and
+     *  `className` / `style` apply only to the default field. Add styling and
+     *  attributes to the returned element instead. */
     renderTrigger?: (state: TriggerState<V>) => React.ReactNode;
     /** Render content in the menu body when the (filtered) option list is empty —
      *  a "no results" message, a loading indicator (gated on your own external
@@ -276,13 +272,10 @@ export type SelectProps<V extends OptionValue = string> = SelectCommonProps<V> &
      *  array value.
      *  @defaultValue single */
     selection?: 'single';
-    /** Controlled value — the `value` of the selected option. When provided, the
-     *  consumer owns selection: the field follows this prop and a pick only
-     *  *requests* a change via `onValueChange` (reject by not updating). Leave
-     *  undefined for uncontrolled. */
+    /** Controlled value: the selected option's `value`. Update it through
+     *  `onValueChange`. Leave it undefined for uncontrolled use. */
     value?: V;
-    /** Initial value (an option's `value`) for the uncontrolled case — the
-     *  wrapper then owns it. */
+    /** Initial selected option value for uncontrolled use. */
     defaultValue?: V;
     /** Fires after the selection changes, with the new value and a
      *  `{ value, option }` snapshot. Select has no discrete element state, so
@@ -352,17 +345,17 @@ export type SelectedItem<V extends OptionValue = string> = SelectedOption<V> | S
  */
 export declare function optionsWithSelection<V extends OptionValue = string>(options: SelectItem<V>[], values: V | V[] | undefined): SelectedItem<V>[];
 /**
- * `<Select>` — a single- or multi-select dropdown, composed from `<Input>` (a
- * read-only trigger) and `<Menu>` (the options). `selection` sets behaviour:
+ * `<Select>` lets people choose one or more options from a dropdown. It uses an
+ * `<Input>` as its read-only trigger and a `<Menu>` for its options. `selection` sets behavior:
  * `'single'` (default; `value` is a string, menu closes on pick) or `'multiple'`
  * (checkboxes, `value` is a string array, menu stays open while toggling, the
  * field shows an "N selected" count). For single-select, `indicator` picks the
  * per-row mark: `'none'` (tint only, default), `'check'` (trailing checkmark), or
  * `'radio'` (leading radio).
  *
- * Controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`). There
- * is no `a-select` element — this wrapper is the coordinator; for a non-React
- * equivalent, hand-compose the same pieces (see the docs).
+ * Use `value` with `onValueChange` to control the selection, or use
+ * `defaultValue` for uncontrolled use. There is no `a-select` element. See the
+ * docs for the equivalent markup without React or Preact.
  *
  * Requires `@antadesign/anta/elements` (client-side only).
  *

package/dist/components/Select.js

@@ -269,7 +269,7 @@ const Select = (props) => {
         "aria-haspopup": "menu",
         "aria-expanded": open ? "true" : "false",
         trailing: (
-          // The named tag owns the select-specific rotation while the icon remains
+          // The named tag applies the Select-specific rotation while the icon remains
           // a normal currentColor glyph.
           /* @__PURE__ */ jsx("a-select-chevron", { open: open ? "" : void 0, style: statusColor ? { color: statusColor } : void 0, children: /* @__PURE__ */ jsx(Icon, { shape: "chevron-down" }) })
         ),