@antadesign/anta 0.3.19 → 0.3.21

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

@@ -1,5 +1,14 @@
 import type { IconShape } from "./elements/a-icon.shapes";
+import type { OptionPresentationProps } from "./general_types";
 export declare function hasChildren(children: React.ReactNode): boolean;
+/**
+ * Select the safe presentation attributes from a data-rendered option. Option
+ * objects often carry application data, so wrappers must never spread them onto
+ * their rendered element. Menu rows also own `data-menu-*`: those attributes
+ * control closing and combobox navigation, and letting an option replace them
+ * would desynchronize its selection behavior.
+ */
+export declare function optionPresentationAttrs(option: OptionPresentationProps, menu?: boolean): OptionPresentationProps;
 /**
  * Normalize a wrapper's label content the way `Button` / `Tabs` do: a bare string
  * or number becomes a `<tag>` — the ellipsis-capable label part (`a-button-label`,
@@ -65,10 +74,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/anta_helpers.js

@@ -2,6 +2,14 @@ import { jsx, useState, useMemo } from "./jsx-runtime";
 function hasChildren(children) {
   return Array.isArray(children) ? children.length > 0 : children != null;
 }
+function optionPresentationAttrs(option, menu = false) {
+  const attrs = {};
+  for (const [name, value] of Object.entries(option)) {
+    if (name === "className" || name === "style" || name.startsWith("data-") && (!menu || !name.startsWith("data-menu-") && name !== "data-anta-menu-item"))
+      attrs[name] = value;
+  }
+  return attrs;
+}
 function wrapLabel(kids, tag) {
   if (kids == null) return kids;
   const arr = Array.isArray(kids) ? kids : [kids];
@@ -158,6 +166,7 @@ export {
   isMenuOpen,
   lengthStyle,
   nativeStateChange,
+  optionPresentationAttrs,
   parseOpenState,
   roundAttr,
   roundStyle,

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/InputAutocomplete.js

@@ -1,6 +1,6 @@
 import { Fragment, jsx, jsxs } from "@antadesign/anta/jsx-runtime";
 import { useState, useMemo, useId } from "../jsx-runtime";
-import { nativeStateChange } from "../anta_helpers";
+import { nativeStateChange, optionPresentationAttrs } from "../anta_helpers";
 import { normalizeOpt, matchQueryRegex, matchesQuery, highlight } from "./select-options";
 import { Input } from "./Input";
 import { Menu } from "./Menu";
@@ -69,23 +69,29 @@ const InputAutocomplete = (props) => {
           if (!next) setActiveId(null);
         },
         onactivedescendant: (e) => setActiveId(nativeStateChange(e).detail?.id ?? null),
-        children: visible.map((opt, i) => /* @__PURE__ */ jsx(
-          MenuItem,
-          {
-            id: `${rid}-o${i}`,
-            role: "option",
-            "aria-selected": activeId === `${rid}-o${i}` ? "true" : "false",
-            icon: opt.icon,
-            label: highlight(opt.label ?? opt.value, queryRe),
-            hint: opt.hint ? highlight(opt.hint, queryRe) : opt.hint,
-            tone: opt.tone,
-            disabled: opt.disabled,
-            value: opt.value,
-            onMouseDown: (e) => e.preventDefault(),
-            onSelect: () => pick(opt)
-          },
-          `${rid}-${opt.value}-${i}`
-        ))
+        children: visible.map((opt, i) => {
+          const { className: optionClassName, style: optionStyle, ...optionAttrs } = optionPresentationAttrs(opt, true);
+          return /* @__PURE__ */ jsx(
+            MenuItem,
+            {
+              ...optionAttrs,
+              id: `${rid}-o${i}`,
+              role: "option",
+              "aria-selected": activeId === `${rid}-o${i}` ? "true" : "false",
+              icon: opt.icon,
+              label: highlight(opt.label ?? opt.value, queryRe),
+              hint: opt.hint ? highlight(opt.hint, queryRe) : opt.hint,
+              tone: opt.tone,
+              disabled: opt.disabled,
+              value: opt.value,
+              onMouseDown: (e) => e.preventDefault(),
+              onSelect: () => pick(opt),
+              className: optionClassName,
+              style: optionStyle
+            },
+            `${rid}-${opt.value}-${i}`
+          );
+        })
       }
     )
   ] });

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

@@ -1,4 +1,4 @@
-import type { BaseProps } from "../general_types";
+import type { BaseProps, OptionPresentationProps } from "../general_types";
 /** The element's `statechange` payload. `next`/`prev` are values (`null` = nothing
  *  selected); `reason` distinguishes a user pick from a form reset / bfcache restore. */
 type StateReason = "user" | "reset" | "restore";
@@ -15,7 +15,7 @@ export interface RadioChangeAttrs {
     name?: string;
 }
 /** One option in a `<RadioGroup>`. The wrapper renders an `<a-radio>` per entry. */
-export interface RadioOption {
+export interface RadioOption extends OptionPresentationProps {
     /** This option's identity and the value submitted when it's selected.
      *  Must be unique within the group (a dev-only warning fires on duplicates). */
     value: string;
@@ -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/RadioGroup.js

@@ -1,6 +1,6 @@
 import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
 import { useId, useState } from "../jsx-runtime";
-import { nativeStateChange, toneStyle } from "../anta_helpers";
+import { nativeStateChange, optionPresentationAttrs, toneStyle } from "../anta_helpers";
 const radioAttrsOf = (el) => ({
   value: el?.value ?? null,
   name: el?.getAttribute?.("name") ?? void 0
@@ -79,9 +79,11 @@ const RadioGroup = ({
         hint && /* @__PURE__ */ jsx("a-radio-group-hint", { id: hintId, children: hint }),
         /* @__PURE__ */ jsx("a-radio-list", { children: options.map((o) => {
           const optDisabled = disabled || o.disabled;
+          const { className: optionClassName, style: optionStyle, ...optionAttrs } = optionPresentationAttrs(o);
           return /* @__PURE__ */ jsxs(
             "a-radio",
             {
+              ...optionAttrs,
               role: "radio",
               value: o.value,
               "aria-disabled": optDisabled ? "true" : void 0,
@@ -90,7 +92,8 @@ const RadioGroup = ({
               "tone-selected": o.toneSelected && o.toneSelected !== "neutral" ? o.toneSelected : void 0,
               size: o.size && o.size !== "medium" ? o.size : void 0,
               disabled: o.disabled ? "" : void 0,
-              style: toneStyle(o.toneSelected, "--radio-tone-source", toneStyle(o.tone, "--radio-tone-source")),
+              class: optionClassName,
+              style: toneStyle(o.toneSelected, "--radio-tone-source", toneStyle(o.tone, "--radio-tone-source", optionStyle)),
               children: [
                 /* @__PURE__ */ jsx("a-radio-label", { children: o.label }),
                 o.hint != null && /* @__PURE__ */ jsx("a-radio-hint", { children: o.hint })