@antadesign/anta 0.3.28 → 0.3.30

package/docs/components/breadcrumbs.md

@@ -4,6 +4,9 @@ Hierarchy navigation assembled from Anta Buttons. Breadcrumb entries can be
 links, actions, or copy controls. Set `maxItems` to fold one middle range into a
 More menu without measuring the available width.
 
+Breadcrumbs do not scroll horizontally by default. Use `maxItems` to limit
+visible entries, or enable scrolling with the [scrolling recipe](#horizontal-scrolling).
+
 ## Items
 
 Pass ordered `BreadcrumbItem` objects through `items`. Each item is a link,
@@ -212,3 +215,33 @@ with your own selector.
   color: var(--text-2);
 }
 ```
+
+### Horizontal scrolling
+
+Set `overflow-x: auto` on the trail to scroll when its contents exceed the
+available width. `maxItems` limits the item count; long labels can still overflow.
+
+Horizontal scrolling also makes vertical overflow compute to `auto`, which
+clips the default button focus ring above and below the row. Set
+`outline-offset: -1px` on the trail's focused controls to draw the ring inside
+their bounds. The selector below covers breadcrumb links, action and copy
+buttons, and the More control.
+
+`scrolling-breadcrumbs` is an example class; replace it with your own selector.
+Use Tab to move through the controls and see the focus ring.
+
+```tsx
+<Box style={{ width: 280, maxWidth: '100%' }}>
+  <Breadcrumbs className="scrolling-breadcrumbs" maxItems={3} items={[
+    { label: 'Anta', href: '/' },
+    { label: 'Documentation', href: '/box/' },
+    { label: 'Layout components', href: '/panel/' },
+    { label: 'Breadcrumbs', current: true },
+  ]} />
+</Box>
+```
+
+```css
+.scrolling-breadcrumbs { overflow-x: auto; }
+.scrolling-breadcrumbs > :focus-visible { outline-offset: -1px; }
+```

package/docs/components/button.md

@@ -166,8 +166,8 @@ name "trash". Pass your own `aria-label` to override.
 ### Children
 
 ```tsx
-<Button tone="brand" label="Save" icon="check">
-  <span style={{ opacity: 0.7 }}>⌘S</span>
+<Button tone="brand" label="Save" icon="check" aria-keyshortcuts="Meta+s">
+  <kbd aria-hidden="true" style={{ font: 'inherit', fontVariationSettings: 'inherit', opacity: 0.7 }}>⌘S</kbd>
 </Button>
 ```
 

package/docs/components/capture.md

@@ -214,9 +214,9 @@ native text selection or touch gestures.
 | `onWheelInput?` | (event, detail) => void | — | Accepted wheel input, with a serialized original event, Capture-relative geometry, focus state, and activation reason. Cancellation is already complete. |
 | `pan?` | boolean \| CapturePan | — | Emit custom pan motion. `true` enables touch panning on both axes without momentum. Options select devices, axes, bounds directions, and optional inertia. Captures the pointer internally; `pointerCapture` is not required. Sets CSS touch-action through attributes before the gesture starts. |
 | `pointerCapture?` | boolean \| CapturePointerCapture | — | Emit raw data for a primary pointer until release or cancellation. An options object filters devices/buttons and configures activation. Nested interactive controls are excluded unless explicitly included. A listener alone enables nothing. |
-| `wheelActivation?` | CaptureWheelActivation | settled | Pointer or focus condition required before wheel input can be captured. Focus applies only to input targeted within this Capture. |
+| `wheelActivation?` | 'hover' \| 'settled' \| 'focus' \| 'settled-or-focus' | settled | Pointer or focus condition required before wheel input can be captured. Focus applies only to input targeted within this Capture. |
 | `wheelCapture?` | CaptureInputDirections | — | Capture wheel input in the enabled directions and emit `onWheelInput`. `true` accepts all directions. Omit or pass `false` to leave wheel input alone. Nested native wheel controls and Anta menus are excluded. All-false direction bounds preserve pointer settling while declining input. A listener alone never enables capture. |
-| `wheelModifier?` | CaptureInputModifier | none | Required modifier for wheel capture. `none` preserves browser Ctrl/pinch zoom. |
+| `wheelModifier?` | 'none' \| 'any' \| 'alt' \| 'ctrl' \| 'meta' \| 'shift' | none | Required modifier for wheel capture. `none` preserves browser Ctrl/pinch zoom. |
 | `wheelSettle?` | CaptureWheelSettle | { delay: 150, tolerance: 5, resetOnMove: false } | Dwell delay, movement tolerance, and whether movement resets eligibility. |
 
 ### CaptureWheelSettle
@@ -233,7 +233,7 @@ native text selection or touch gestures.
 |------|------|---------|-------------|
 | `buttons?` | readonly number[] | [0] | Accepted initiating buttons, using PointerEvent.button values. |
 | `includeInteractive?` | boolean | false | Allow capture to start on nested native or ARIA controls, links, or editable regions. |
-| `modifier?` | CaptureInputModifier | any | Modifier required to start a capture session. |
+| `modifier?` | 'none' \| 'any' \| 'alt' \| 'ctrl' \| 'meta' \| 'shift' | any | Modifier required to start a capture session. |
 | `pointerTypes?` | readonly CapturePointerType[] | ['mouse', 'pen', 'touch'] | Accepted pointer devices. One primary pointer is tracked per Capture. |
 | `threshold?` | number | 0 | Movement required before activation, in viewport CSS pixels. |
 
@@ -258,7 +258,7 @@ native text selection or touch gestures.
 
 | Field | Type | Default | Description |
 |------|------|---------|-------------|
-| `activationReason` | CaptureWheelActivationReason | — |  |
+| `activationReason` | 'immediate' \| 'settled' \| 'focus' | — |  |
 | `boxHeight` | number | — |  |
 | `boxWidth` | number | — | Dimensions of the same viewport bounding rectangle, in CSS pixels. |
 | `focusWithin` | boolean | — |  |
@@ -271,7 +271,7 @@ native text selection or touch gestures.
 
 | Field | Type | Default | Description |
 |------|------|---------|-------------|
-| `activationReason` | CapturePointerActivationReason | — |  |
+| `activationReason` | 'pointer-down' \| 'drag-threshold' | — |  |
 | `boxHeight` | number | — |  |
 | `boxWidth` | number | — | Dimensions of the same viewport bounding rectangle, in CSS pixels. |
 | `deltaX` | number | — | Movement since the previous delivered sample, in viewport CSS pixels. |
@@ -285,13 +285,13 @@ native text selection or touch gestures.
 | `phase` | 'start' \| 'move' \| 'end' \| 'cancel' | — |  |
 | `pointerEvent` | SerializedPointerEvent \| null | — | Null when cancellation comes from lifecycle or configuration changes. |
 | `start` | CapturePointerStart | — |  |
-| `cancelReason?` | CaptureInputCancelReason | — |  |
+| `cancelReason?` | 'pointer-cancel' \| 'lost-capture' \| 'disabled' \| 'disconnected' \| 'blur' \| 'interrupted' | — |  |
 
 ### CapturePanInput
 
 | Field | Type | Default | Description |
 |------|------|---------|-------------|
-| `activationReason` | CapturePointerActivationReason | — |  |
+| `activationReason` | 'pointer-down' \| 'drag-threshold' | — |  |
 | `boxHeight` | number | — |  |
 | `boxWidth` | number | — | Dimensions of the same viewport bounding rectangle, in CSS pixels. |
 | `deltaX` | number | — | Incremental scroll motion in viewport CSS pixels. |
@@ -305,7 +305,7 @@ native text selection or touch gestures.
 | `start` | CapturePointerStart | — |  |
 | `velocityX` | number | — | Scroll velocity in viewport CSS pixels/ms. |
 | `velocityY` | number | — |  |
-| `cancelReason?` | CaptureInputCancelReason | — |  |
+| `cancelReason?` | 'pointer-cancel' \| 'lost-capture' \| 'disabled' \| 'disconnected' \| 'blur' \| 'interrupted' | — |  |
 
 ## Web component
 

package/docs/components/checkbox.md

@@ -163,7 +163,11 @@ function ParentChild() {
 
 ## Accessibility
 
-The wrapper sets `role="checkbox"` and `aria-checked` (`"true"` / `"false"` / `"mixed"`), and derives the accessible name from `label` or `children`. For a label-less checkbox, pass `aria-label`.
+The wrapper sets `role="checkbox"`, and the element keeps `aria-checked`
+(`"true"` / `"false"` / `"mixed"`) in sync. Its light-DOM label supplies the
+accessible name and its hint supplies the accessible description through
+`ElementInternals`; no generated IDs are needed. For a label-less checkbox, pass
+`aria-label`.
 
 Space toggles the checkbox. Follows the [WAI-ARIA checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).
 
@@ -174,7 +178,7 @@ Space toggles the checkbox. Follows the [WAI-ARIA checkbox pattern](https://www.
 | `checked?` | CheckboxValue | — | Controlled checked state. When provided the checkbox is controlled — it renders exactly this and never self-applies; `onStateChange` is a *request* the consumer accepts by updating this prop. Use `defaultChecked` for an uncontrolled checkbox. `'indeterminate'` shows the minus glyph and takes visual precedence; clicking it requests `true`. |
 | `defaultChecked?` | CheckboxValue | false | Initial checked state for an uncontrolled checkbox. Read once; later changes are ignored and the element updates its state after interaction. |
 | `disabled?` | boolean | — | Disable the checkbox (no interaction, dropped from the tab order). |
-| `hint?` | ReactNode | — | Secondary text rendered under the label — explanatory copy, like Input's hint. Not part of the accessible name. |
+| `hint?` | ReactNode | — | Secondary text rendered under the label and exposed as the checkbox's accessible description. Not part of the accessible name. |
 | `label?` | string | — | Visible label — the *value* of the checkbox (clicked along with the box). Convenience for the common single-string case; for richer content (markup, a link, an info icon) use `children`. When both are supplied, `label` renders first. Required unless `children` or `aria-label` is provided (a `role="checkbox"` takes its name from the author, not the markup). |
 | `name?` | string | — | Form field name. Inside a `<form>` the checkbox submits under this name, contributing `value` when checked — like a native checkbox. |
 | `onChange?` | (event) => void | — | Fired *after* the checked state changes — a native `change` event (the post-apply counterpart to `onStateChange`). Not cancelable. For a controlled checkbox this fires once you've updated `checked`. |
@@ -183,14 +187,15 @@ Space toggles the checkbox. Follows the [WAI-ARIA checkbox pattern](https://www.
 | `round?` | boolean \| number \| string | — | Round the checkbox mark to a circle (`border-radius: 999px` on the box). Pass a `number` (px) or a CSS length string for a rounded-square mark instead. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant. small=14px, medium=16px, large=18px box. |
 | `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the **mark**. In the default `all` scope this colors the checked-box fill and 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 color keeps its hue + chroma and pins lightness to the fill curve. Set `toneScope="selected"` to tone only the checked mark and leave the empty box neutral. The label + hint stay neutral — recolor them in plain CSS via the theme-aware `--text-N-{tone}` tokens. |
-| `toneScope?` | ToneScope | 'all' | Apply `tone` to every state, or only while checked so the empty box stays neutral. `selected` is useful when a tinted resting border would read as a validation state. |
+| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every state, or only while checked so the empty box stays neutral. `selected` is useful when a tinted resting border would read as a validation state. |
 | `value?` | string | "on" | Value submitted with the form when checked — like a native checkbox. |
 
 ## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
-The focusable host carries the state. Label and hint are light-DOM children.
+The focusable host carries the state. Label and hint are light-DOM children that
+the element exposes as its accessible name and description.
 
 ```html
 <a-checkbox role="checkbox" tabindex="0" name="updates" default-state="checked">

package/docs/components/input-autocomplete.md

@@ -23,6 +23,12 @@ the first suggestion (then ↑/↓ move through them), and
 Enter on a highlighted row picks it. Esc or an outside click
 closes the list; clicking the field to place the caret keeps it open.
 
+The focused field is associated directly with the suggestion popup and its
+active option through ARIA element reflection. These relationships do not
+require generated popup or option IDs, so separate application roots cannot
+collide. Explicit ARIA relationships authored on a raw Anta Input take
+precedence.
+
 ## Filtering
 
 `filter` decides how suggestions match the text:

package/docs/components/input-date.md

@@ -212,9 +212,15 @@ the standard constraint-validation pipeline.
 
 ## Accessibility
 
+The focused Input field is associated directly with its Calendar dialog through
+ARIA element reflection. The relationship does not require a generated popup ID,
+so separate application roots can render InputDate instances without ID
+collisions. An explicitly authored relationship on a raw Anta Input takes
+precedence.
+
 The calendar is a labelled **group** of day buttons, a flat grid rather than a
-nested `grid`/`row`/`gridcell` tree. The group is named by the visible month
-(`aria-labelledby`). Each day is a `<button>` whose `aria-label` is its full date
+nested `grid`/`row`/`gridcell` tree. The visible month names the group directly.
+Each day is a `<button>` whose `aria-label` is its full date
 including weekday ("Sunday, June 28, 2026"), with `aria-pressed` on the selected day
 and `aria-current="date"` on today. The decorative weekday headers are `aria-hidden`,
 since each day already names its weekday. A roving `tabindex` keeps a single tab

package/docs/components/input.md

@@ -9,9 +9,9 @@ for styling through `::part(input)`.
 ## Size
 
 ```tsx
-<Input size="small"  label="Small"  placeholder="24px tall" />
-<Input size="medium" label="Medium" placeholder="28px tall" /> {/* default */}
-<Input size="large"  label="Large"  placeholder="32px tall" />
+<Input size="small"  label="Small"  placeholder="24px tall" autoComplete="off" />
+<Input size="medium" label="Medium" placeholder="28px tall" autoComplete="off" /> {/* default */}
+<Input size="large"  label="Large"  placeholder="32px tall" autoComplete="off" />
 ```
 
 Three sizes (`medium` is the default). The field **height**, the **type scale**
@@ -27,8 +27,8 @@ Anta's text scale, so a field lines up with same-size `Text` / `Button`.
 ## Label and hint
 
 ```tsx
-<Input label="Display name" defaultValue="Ada Lovelace" />
-<Input label="API key" hint="Find this in Settings → Developers." placeholder="sk-…" />
+<Input label="Display name" defaultValue="Ada Lovelace" autoComplete="name" />
+<Input label="API key" hint="Find this in Settings → Developers." placeholder="sk-…" autoComplete="off" />
 ```
 
 `label` sits above the field; `hint` is neutral helper text below it
@@ -40,12 +40,18 @@ mirrors the label text into `aria-label`, since a native `<label for>` can't
 cross the shadow boundary. The `hint` (or error) is mirrored the same way into
 `aria-description`, so a screen reader announces the message too.
 
+Standard `role` and `aria-*` attributes on `<Input>` or raw `<a-input>` are
+applied to the native input, textarea, or button inside its shadow root. This
+keeps the focused native control as the single accessible control. If you query
+the DOM directly, read those semantics from `a-input.control` rather than from
+the custom-element host.
+
 ## Tooltip
 
 ```tsx
 {/* Drop a <Tooltip> in as a child — it attaches to the field and shows on hover,
     exactly like a tooltip on any other element. */}
-<Input label="API key" placeholder="sk-…">
+<Input label="API key" placeholder="sk-…" autoComplete="off">
   <Tooltip>Find this in Settings → Developers.</Tooltip>
 </Input>
 ```
@@ -60,12 +66,12 @@ content.)
 
 ```tsx
 {/* No status = neutral helper text */}
-<Input label="Display name" defaultValue="Ada Lovelace" hint="This is your public name." />
-<Input label="Workspace" defaultValue="acme" status="info" hint="Lowercase letters and dashes only." />
-<Input label="Username" defaultValue="ada" status="success" hint="Username is available." />
-<Input label="Password" type="password" defaultValue="hunter2" status="warning" hint="Weak — add more characters." />
-<Input label="Email" defaultValue="not-an-email" status="critical" hint="Enter a valid email address." />
-<Input label="Plan" defaultValue="Pro" status="brand" hint="You're on the Pro plan." />
+<Input label="Display name" defaultValue="Ada Lovelace" hint="This is your public name." autoComplete="name" />
+<Input label="Workspace" defaultValue="acme" status="info" hint="Lowercase letters and dashes only." autoComplete="off" />
+<Input label="Username" defaultValue="ada" status="success" hint="Username is available." autoComplete="username" />
+<Input label="Password" type="password" defaultValue="hunter2" status="warning" hint="Weak — add more characters." autoComplete="new-password" />
+<Input label="Email" type="email" defaultValue="not-an-email" status="critical" hint="Enter a valid email address." autoComplete="email" />
+<Input label="Plan" defaultValue="Pro" status="brand" hint="You're on the Pro plan." autoComplete="off" />
 ```
 
 `status` tints the border and the `hint`, and prefixes a glyph — `critical`,
@@ -92,15 +98,16 @@ with `statusIcon={false}`.
 ```tsx
 {/* clearable — the clear button shows once there's a value */}
 {/* dimActions — adornments rest quiet, brighten when the field is hovered/focused */}
-<Input label="Search" placeholder="Search…" clearable dimActions defaultValue="design tokens" />
+<Input label="Search" placeholder="Search…" clearable dimActions defaultValue="design tokens" autoComplete="off" />
 
 {/* type="search" is a shorthand for the leading search icon + clearable below */}
-<Input label="Search" type="search" placeholder="Search…" />
+<Input label="Search" type="search" placeholder="Search…" autoComplete="off" />
 
 {/* leading / trailing take any node — see the live playground above */}
-<Input label="Search" leading={<Icon shape="search" />} clearable dimActions />
+<Input label="Search" leading={<Icon shape="search" />} clearable dimActions autoComplete="off" />
 <Input
   label="Date"
+  autoComplete="off"
   leading={<Icon shape="calendar" />}
   trailing={<Button priority="quaternary" size="small" icon="eye" aria-label="Pick" />}
   dimActions
@@ -149,6 +156,7 @@ const [reveal, setReveal] = useState(false)
 
 <Input
   label="Password"
+  autoComplete="current-password"
   type={reveal ? 'text' : 'password'}
   defaultValue="hunter2"
   dimActions
@@ -176,10 +184,10 @@ Firefox. So Anta keeps the native field.
 
 ```tsx
 {/* Grows with content, capped at 6 rows, then scrolls */}
-<Input multiline maxRows={6} label="Bio (autogrows)" placeholder="Tell us…" />
+<Input multiline maxRows={6} label="Bio (autogrows)" placeholder="Tell us…" autoComplete="off" />
 
 {/* Constant height of 3 rows */}
-<Input multiline rows={3} label="Notes (fixed 3 rows)" placeholder="…" />
+<Input multiline rows={3} label="Notes (fixed 3 rows)" placeholder="…" autoComplete="off" />
 ```
 
 `multiline` renders a `<textarea>` under the same API. With **no `rows`** it
@@ -195,11 +203,11 @@ browser.
 
 ```tsx
 // Uncontrolled: the element updates its value after input.
-<Input label="Name" defaultValue="Ada" onChange={(e) => log(e.target.value)} />
+<Input label="Name" defaultValue="Ada" autoComplete="name" onChange={(e) => log(e.target.value)} />
 
 // Controlled: application state supplies the value.
 const [v, setV] = useState('')
-<Input label="Name" value={v} onInput={(e) => setV(e.target.value)} />
+<Input label="Name" value={v} autoComplete="name" onInput={(e) => setV(e.target.value)} />
 ```
 
 Like a native input: pass `defaultValue` for **uncontrolled**, or `value` +
@@ -240,7 +248,7 @@ value-based, also has only `onValueChange`.)
 
 ```tsx
 <form onSubmit={handle}>
-  <Input name="email" label="Email" type="email" required clearable />
+  <Input name="email" label="Email" type="email" autoComplete="email" required clearable />
   <Button tone="brand" type="submit" label="Sign up" />
   <Button priority="tertiary" type="reset" label="Reset" />
 </form>
@@ -254,12 +262,12 @@ restores the field to its `defaultValue` via `formResetCallback`.
 ## Types and validation
 
 ```tsx
-<Input type="text"     label="Text" />
-<Input type="email"    label="Email" />
-<Input type="password" label="Password" />
-<Input type="tel"      label="Tel" />
-<Input type="url"      label="URL" />
-<Input type="number"   label="Number" min={0} max={100} />
+<Input type="text"     label="Text"     autoComplete="off" />
+<Input type="email"    label="Email"    autoComplete="email" />
+<Input type="password" label="Password" autoComplete="current-password" />
+<Input type="tel"      label="Tel"      autoComplete="tel" />
+<Input type="url"      label="URL"      autoComplete="url" />
+<Input type="number"   label="Number"   autoComplete="off" min={0} max={100} />
 ```
 
 `type` accepts `text` (default), `email`, `password`, `tel`, `url`, and
@@ -267,6 +275,12 @@ restores the field to its `defaultValue` via `formResetCallback`.
 constraint validation. (`search` is omitted on purpose — see above.)
 `number` also takes `min` / `max` / `step`.
 
+Set `autoComplete` to describe the field's purpose. `email`, `tel`, and `url`
+derive their matching token from `type`. Other purposes need an explicit token,
+such as `name`, `username`, `current-password`, `new-password`, or
+`one-time-code`. Use `autoComplete="off"` for examples and application fields
+that do not represent autofill data.
+
 For a **controlled** numeric field — one whose `value` you hold in state — prefer
 `type="text"` with `inputMode="decimal"` (or `"numeric"`) over `type="number"`. A
 number input runs value sanitization, so a mid-typing `"1."` or `"1.0"` reports an
@@ -296,10 +310,10 @@ function onSubmit(e) {
 }
 
 <form noValidate onSubmit={onSubmit}>
-  <Input name="email" type="email" required hint={errors.email}
+  <Input name="email" type="email" autoComplete="email" required hint={errors.email}
          status={errors.email ? 'critical' : undefined}
          onInput={() => setErrors(p => ({ ...p, email: undefined }))} />
-  <Input name="age" type="number" min="18" max="120" hint={errors.age}
+  <Input name="age" type="number" autoComplete="off" min="18" max="120" hint={errors.age}
          status={errors.age ? 'critical' : undefined}
          onInput={() => setErrors(p => ({ ...p, age: undefined }))} />
   <Button type="submit" label="Submit" />
@@ -345,7 +359,7 @@ Re-template the host to two columns and drop each part into one. The hint stays
 under the field by landing in the same column.
 
 ```tsx
-<Input className="label-side" label="Display name" hint="Shown on your profile" />
+<Input className="label-side" label="Display name" hint="Shown on your profile" autoComplete="name" />
 
 {/* .label-side is just for the demo — use your own selector */}
 <style>{`
@@ -369,9 +383,9 @@ left-edge lines up. Each hint still tucks under its own field.
 
 ```tsx
 <div className="aligned-form">
-  <Input label="Email" type="email" hint="We'll never share it." />
-  <Input label="Confirm password" type="password" />
-  <Input label="PIN" />
+  <Input label="Email" type="email" autoComplete="email" hint="We'll never share it." />
+  <Input label="Confirm password" type="password" autoComplete="new-password" />
+  <Input label="PIN" autoComplete="one-time-code" />
 </div>
 
 <style>{`
@@ -391,7 +405,7 @@ unit. Two columns (field, then hint); the label spans the top, and the hint
 centers against the field.
 
 ```tsx
-<Input className="hint-right" label="Username" hint="3–20 characters" placeholder="ada" />
+<Input className="hint-right" label="Username" hint="3–20 characters" placeholder="ada" autoComplete="username" />
 
 <style>{`
   a-input.hint-right {
@@ -412,10 +426,10 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 
 ```tsx
 <div className="wrap-fields">
-  <Input label="First name" />
-  <Input label="Last name" />
-  <Input label="Email" type="email" />
-  <Input label="Phone" type="tel" />
+  <Input label="First name" autoComplete="given-name" />
+  <Input label="Last name" autoComplete="family-name" />
+  <Input label="Email" type="email" autoComplete="email" />
+  <Input label="Phone" type="tel" autoComplete="tel" />
 </div>
 
 <style>{`
@@ -430,6 +444,7 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 |------|------|---------|-------------|
 | `autoComplete?` | 'off' \| 'on' \| 'name' \| 'username' \| 'email' \| 'current-password' \| 'new-password' \| 'one-time-code' \| 'tel' \| 'url' \| (string & {}) | — | Native autocomplete token. Overrides the value derived from `type` (`email` / `tel` / `url`) — set it for the cases `type` can't express, e.g. `username`, `current-password`, `new-password`, `one-time-code`, or `off`. |
 | `autoFocus?` | boolean | — | Focus this field when its containing `Dialog` opens. |
+| `button?` | boolean | — | Render the field surface with a native button as its focus target. This is available for Input-styled popup triggers; the value becomes the button text and the placeholder is shown while it is empty. |
 | `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 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 value. |
 | `defaultValue?` | string | — | Initial value for the uncontrolled case. |
@@ -457,7 +472,7 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 | `placeholder?` | string | — | Placeholder shown when empty. |
 | `readOnly?` | boolean | — | Make the field read-only. |
 | `required?` | boolean | — | Mark the field required (drives native validity). |
-| `role?` | string | — | ARIA `role` for the field — e.g. `combobox` when the input drives a suggestion `listbox` (see `InputAutocomplete`). Left unset by default. |
+| `role?` | string | — | ARIA `role` for the field — e.g. `combobox` when the input drives a suggestion `listbox` (see `InputAutocomplete`). The custom element delegates it, together with standard `aria-*` props, to the focused native shadow control. Left unset by default. |
 | `round?` | boolean \| number \| string | — | Fully-round the field (`border-radius: 999px`). Pass a `number` (px) or a CSS length string for a custom radius. The `clearable` × button always rounds to a circle to match (it isn't sized by a custom field value). |
 | `rows?` | number | — | Fixed visible row count — a constant-height `<textarea>` (implies `multiline`). |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. small=24px, medium=28px, large=32px tall; the type scale and icon track the size (small 13/16 + 14px icon · medium 15/20 + 16px · large 17/22 + 18px). |
@@ -478,7 +493,7 @@ Use the web component directly when you are not using React or Preact and a nati
 Slots hold the label, hint, and controls around the native field.
 
 ```html
-<a-input name="email" placeholder="you@example.com">
+<a-input name="email" type="email" autocomplete="email" placeholder="you@example.com">
   <span slot="label">Email</span>
   <span slot="hint">We only use it for account notices.</span>
 </a-input>
@@ -524,7 +539,7 @@ Reach for the props first: **`status`** sets a validation tone (border + message
 dimensions. The focus ring is the global [`--focus-ring`](../colors.md#focus-ring).
 
 ```tsx
-<Input tone="#e0457b" label="Custom accent" />
+<Input tone="#e0457b" label="Custom accent" autoComplete="off" />
 ```
 
 For everything else, `<a-input>` is shadow-DOM — style its **parts** with plain
@@ -563,5 +578,49 @@ a-input.fancy::part(field) {
   padding-inline: 20px;                      /* roomier */
 }
 a-input.fancy::part(input) { color: light-dark(#ffffff, #1a1a1a); }
+a-input.fancy::part(input)::placeholder {
+  color: light-dark(#b8b8b8, #666666);
+  opacity: 1;
+}
 a-input.fancy:focus-within::part(field) { background: light-dark(#161616, #ffffff); }
 ```
+
+### Placeholder contrast
+
+If the label, marking, context, or hint leaves the field's purpose unclear,
+a stronger placeholder can help. Keep an accessible name and put essential
+instructions in a persistent label or hint.
+
+Antune uses `--text-4` for placeholders. These ratios compare the default neutral
+Input backgrounds with the example's literal color:
+
+| Style | Placeholder | Background | Contrast |
+| --- | --- | --- | --- |
+| Antune light theme | `#7a737c` | `#ffffff` | 4.59:1 |
+| Antune dark theme | `#7c737c` | `#000000` | 4.60:1 |
+| Example | `#767676` | `#ffffff` | 4.54:1 |
+
+`#767676` is the lightest opaque 8-bit neutral gray that passes 4.5:1 on white.
+W3C recommends [sufficient placeholder contrast](https://www.w3.org/WAI/tutorials/forms/instructions/#styling).
+Redundant placeholders remain debated in the
+[meeting discussion](https://www.w3.org/2025/04/16-matf-minutes.html) and
+[open W3C issue](https://github.com/w3c/wcag/issues/4343); there is no agreed exemption.
+
+This demo uses `#767676` on white in every state and theme.
+Replace `.placeholder-contrast` with your own class.
+
+```tsx
+<Input className="placeholder-contrast" label="Email" type="email" autoComplete="email" placeholder="you@example.com" />
+```
+
+```css
+a-input.placeholder-contrast::part(field) { background: #ffffff; }
+a-input.placeholder-contrast::part(input) { color: #161616; }
+a-input.placeholder-contrast::part(input)::placeholder {
+  color: #767676;
+  opacity: 1;
+}
+```
+
+Check contrast separately if you use a different background.
+Native inputs and textareas use `::placeholder` without `::part(input)`.

package/docs/components/menu.md

@@ -415,7 +415,7 @@ navigating links.
 | `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' | — | Turn the row into a checkable item, driven by `selected` (the row stays the control and carries `aria-checked`): - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>` (before `icon`); the tint is dropped (the box carries state). - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped. - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected row *and* the background tint (the canonical single-select look). Omit for a plain row (the default). |
 | `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
 | `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose hue + chroma are kept while the lightness is pinned to match the brand text. `critical` is the destructive action; `neutral` (the default) is the standard gray. |
-| `toneScope?` | ToneScope | 'all' | Apply `tone` to every row state, or only while the row is selected. In `selected` scope, an unselected row and its checkbox/radio indicator stay neutral. |
+| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every row state, or only while the row is selected. In `selected` scope, an unselected row and its checkbox/radio indicator stay neutral. |
 | `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail so a shared handler can tell which row was chosen without a per-item closure. |
 
 ## Keyboard
@@ -461,7 +461,7 @@ or do nothing to reject. (Submenus are always uncontrolled, regardless of `open`
 | `inset?` | number \| string | 4 | Inner inset for the scroll body and named header/footer content. A number is pixels; a CSS length string is used as written. |
 | `nohover?` | boolean | — | Submenu-only (a `<Menu>` nested inside a `MenuItem`); ignored on a root menu. Submenus open on hover by default (with intent timing) as well as on click — set `nohover` to make this submenu click-only. Hover-intent is mouse-only regardless: on touch (and pen) a submenu always opens on tap and stays open until dismissed. |
 | `offset?` | number | 4 | Gap in pixels between the trigger and the menu. |
-| `onactivedescendant?` | (e) => void | — | 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 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) => void | — | 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 an authored option `id`, or `null`. Built-in Anta Inputs receive the active option through a direct ARIA element relationship; this remains available to custom fields and observers. Passed straight through to the element. |
 | `onStateChange?` | (event, detail) => void | — | Fired before the open state changes — on open, and on every dismiss (Esc, outside-click, scroll, selecting an item). `event` is the cancelable `statechange`; `detail.next`/`detail.prev` are the requested/previous open state (booleans). It's the declarative way to observe a menu, and the handler you pair with `open` to drive a controlled menu (apply `detail.next` to `open`). Uncontrolled, `event.preventDefault()` vetoes the transition (e.g. keep the menu open). |
 | `open?` | boolean | — | Controlled open state. Omit for the default **uncontrolled** menu (it opens/closes itself via its triggers). Pass a boolean to **control** it: the menu's visibility follows `open`, and user dismiss (Esc, outside-click, select) fires `onStateChange` *without* self-closing — you update `open` in response. Submenus are always uncontrolled regardless of this. See STATEFUL-COMPONENTS.md. |
 | `placement?` | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' \| 'bottom' \| 'top' \| 'right-start' \| 'right-end' \| 'left-start' \| 'left-end' \| 'right' \| 'left' | bottom-start | Preferred placement relative to the trigger. `bottom` / `top` place the menu below / above; `right` / `left` place it beside (like a submenu flyout). The cross-axis suffix (`-start` / `-end`) aligns the near / far edges, and no suffix centers on the trigger. The menu flips to the opposite side when the preferred one lacks room, and clamps to the viewport. |
@@ -494,7 +494,7 @@ or do nothing to reject. (Submenus are always uncontrolled, regardless of `open`
 | `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
 | `target?` | string | — | Anchor target, e.g. `'_blank'`. |
 | `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose hue + chroma are kept while the lightness is pinned to match the brand text. `critical` is the destructive action; `neutral` (the default) is the standard gray. |
-| `toneScope?` | ToneScope | 'all' | Apply `tone` to every row state, or only while the row is selected. In `selected` scope, an unselected row and its checkbox/radio indicator stay neutral. |
+| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every row state, or only while the row is selected. In `selected` scope, an unselected row and its checkbox/radio indicator stay neutral. |
 | `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail so a shared handler can tell which row was chosen without a per-item closure. |
 
 ## Web Component