@antadesign/anta 0.3.27 → 0.3.29

package/docs/components/box.md

@@ -5,32 +5,34 @@ events. For custom wheel, pointer, and touch handling, use [Capture](./capture.m
 
 ## Display
 
-Use `display`, `gap`, and `round` for layout and corners. Numeric lengths use
-pixels; strings accept CSS lengths. A bare `round` fully rounds the corners.
+Use `display`, `gap`, `padding`, `margin`, and `round` for layout and corners. Numeric lengths use
+pixels; strings accept CSS lengths. `padding` and `margin` also accept CSS
+shorthand, such as `padding="8px 16px"` or `margin="0 auto"`. Omission adds no
+spacing styles. A bare `round` fully rounds the corners.
 
 ```tsx
-<Box round={8}><span /></Box>
-<Box display="flex" round={8} gap={6}><span /></Box>
-<Box display="grid" round={8} gap="0.5rem" style={{ gridTemplateColumns: '1fr 1fr' }}><span /></Box>
+<Box round={8} padding={10}><span /></Box>
+<Box display="flex" round={8} gap={6} padding={10}><span /></Box>
+<Box display="grid" round={8} gap="0.5rem" padding="8px 16px" style={{ gridTemplateColumns: '1fr 1fr' }}><span /></Box>
 ```
 
 ## Overflow
 
 Box reports overflow, clipping, and scrollability as measurements and CSS
-states. Use `observe="size"` to keep CSS states current. `fade` and
-`onMeasureChange` also enable measurement; without these, Box adds no size
-observers.
+states. Use `observe="overflow"` to keep overflow, clipping, and scrollability
+states current as content changes. `observe="edges"` also tracks which
+edges hide content while scrolling. `fade` enables both automatically.
 
 `.edge` is a demo class name. Use your own selector.
 
 ```tsx
-<Box observe="size" round={8} className="edge" style={{ width: 150 }}>Content that fits.</Box>
+<Box observe="overflow" round={8} className="edge" style={{ width: 150 }}>Content that fits.</Box>
 
-<Box observe="size" round={8} className="edge" style={{ width: 150, overflow: 'hidden', whiteSpace: 'nowrap' }}>
+<Box observe="overflow" round={8} className="edge" style={{ width: 150, overflow: 'hidden', whiteSpace: 'nowrap' }}>
   A label too long for this box.
 </Box>
 
-<Box observe="size" round={8} className="edge" style={{ width: 150, height: 56, overflowY: 'auto' }}>
+<Box observe="overflow" round={8} className="edge" style={{ width: 150, height: 56, overflowY: 'auto' }}>
   One. Two. Three. Four. Five. Six. Seven. Eight. Nine. Ten.
 </Box>
 ```
@@ -65,7 +67,7 @@ const TAGS = ['frontend', 'design-system', 'a11y', 'performance']
 The mask clips to the padding box. It preserves the Box border, shadows, and
 focus ring when no edge is hidden.
 
-To style hidden edges without `fade`, use `observe="size"` and the
+To style hidden edges without `fade`, use `observe="edges"` and the
 `hidden-start-x`, `hidden-end-x`, `hidden-start-y`, or `hidden-end-y` CSS states.
 
 ### Tooltip on clipped content
@@ -88,11 +90,63 @@ const TAGS = ['frontend', 'design-system', 'a11y', 'performance']
 
 ## Measurements
 
-`onMeasureChange` reports one frame after observation starts and when the Box or
-its content changes. `changed` contains changed fields; `current` is the full
-snapshot. Reporting pauses off screen and resumes when Box returns.
-
-Resize or scroll the Box to update its measurements.
+By default, `onMeasureChange` reports one frame after observation starts, then when
+the border-box `width` or `height` changes. `changed` contains all fields changed
+since the last event; `current` is the full snapshot. Reporting pauses off screen
+and resumes with a fresh snapshot when Box returns.
+
+`observe` accepts one of the eight selections below, or a typed array combining
+them. `observe={['size', 'edges']}` and `observe={['edges', 'size']}` select the
+same triggers. Repeated selections have no effect. Changing the selected
+measurement fields requests a fresh snapshot. TypeScript checks each value;
+use an array to combine selections in JSX.
+
+The selections below progress from resize and context signals to continuous
+scroll tracking. Intensity describes typical observation work and event frequency,
+not a fixed performance rating. Content churn and the work in your handler also
+affect the cost.
+
+| Selection | Event triggers | Frontend work and intensity |
+| --- | --- | --- |
+| `width` | Border-box `width`. | Low during ordinary use: observes the host; no content or scroll observers. Can report each frame during resizing. |
+| `height` | Border-box `height`. | Same work as `width`, with height as the event trigger. |
+| `size` | Either border-box `width` or `height`. | Same observers as a single dimension; observes the element itself. |
+| `context` | Theme, resolved font, insets, background, focus, and browser/device context through `onContextChange`. | Usually infrequent: shared theme/media listeners and local style/focus reads; no scroll listener. |
+| `overflow` | `clientWidth`, `clientHeight`, `scrollWidth`, `scrollHeight`, `overflowX/Y`, `clippedX/Y`, and `scrollableX/Y`. | Content-dependent: adds content mutations and child resizes; no scroll listener. Does not report individual child dimensions. |
+| `edges` | `hiddenStartX`, `hiddenEndX`, `hiddenStartY`, and `hiddenEndY`. | Measures content/layout changes and scrolling, at most once per frame. Emits only when an edge flag changes, so moving through the middle stays silent. |
+| `scroll` | `scrollLeft` or `scrollTop`. | High during scrolling: measures content/layout and scroll changes and can emit every frame. |
+| `all` | Every measurement field and rendering context. | Enables all observers and can emit every frame. |
+
+Selections are independent. `scroll` selects offset triggers; it does not include
+`size`, `overflow`, `edges`, or `context`. Every measurement event still
+contains fresh values for every measurement field, including client/content
+dimensions and hidden edges. Combine triggers when you also need events caused
+by those other changes. With `observe="size"`, content-only changes cause no
+event; the next size event includes the current content measurements.
+
+For a scroll-edge indicator, use `edges`: it reads during scrolling but
+avoids a callback for each offset change. `scroll` and `all` can cause the most
+frequent application updates, especially when the handler sets state or sends
+each snapshot to a worker. Prefer `fade` when CSS alone needs the edge state.
+
+When no measurement is selected, `onMeasureChange` adds `size`;
+`onContextChange` adds `context`.
+Passing both handlers observes size and context without enabling scroll events.
+Without handlers or `fade`, omitting `observe` keeps Box idle.
+
+Set `throttle` to a minimum interval in milliseconds. The first report has no
+added delay; subsequent reports include a trailing update with the latest values.
+Omit it or pass `0` for frame-based reporting. Negative or non-finite values use
+`0`. The interval applies to `onMeasureChange`; context events are not throttled.
+Throttling limits event delivery; it does not reduce observer reads.
+`edges`, `scroll`, and `fade` continue measuring during scrolling so their
+CSS states remain current.
+
+`Tooltip truncatedOnly` reads Box's clipping on demand. It works without
+`observe` or `onMeasureChange` and does not enable continuous observation.
+
+This readout observes `['size', 'overflow', 'edges', 'scroll']` with `throttle={100}`.
+Resize or scroll the Box to update it.
 
 ```tsx title="measurechange"
 const [measurement, setMeasurement] = useState<BoxMeasurement | null>(null)
@@ -100,6 +154,8 @@ const [measurement, setMeasurement] = useState<BoxMeasurement | null>(null)
 <Box
   round={8}
   className="measure-probe-box"
+  observe={['size', 'overflow', 'edges', 'scroll']}
+  throttle={100}
   onMeasureChange={(_, { current }) => setMeasurement(current)}
 >
   <Text size="small" priority="tertiary">Resize or scroll this Box.</Text>
@@ -224,14 +280,17 @@ const canvasRef = useRef<HTMLCanvasElement>(null)
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `display?` | BoxDisplay | block | Layout model for the host. All other layout, sizing, mask, and shadow properties stay ordinary `className` / `style` CSS on the Box itself. |
+| `display?` | 'block' \| 'inline-block' \| 'flex' \| 'inline-flex' \| 'grid' \| 'inline-grid' | block | Layout model for the host. Sizing, alignment, mask, and shadow properties stay ordinary `className` / `style` CSS on the Box itself. |
 | `fade?` | boolean | — | Fades out every edge that currently hides clipped content, and drops the fade from an edge once the reader scrolls to it. |
 | `fadeSize?` | number \| string | 24 | Depth of the `fade` gradient. A `number` is pixels; a string is any CSS length. |
 | `gap?` | number \| string | — | Gap between children, matching the CSS `gap` property. A `number` is pixels; a string is any CSS length or two-value gap (`'1rem'`, `'8px 16px'`). Applies while the Box is a flex or grid container. |
-| `observe?` | 'size' \| 'context' \| 'all' | — | What the Box watches, when a handler is not what turns it on. `'size'` keeps the overflow CSS states (`:state(clipped-x)`, `:state(scrollable-y)`, …) current — reach for it when your own CSS is the only reader. `'context'` and `'all'` are there for symmetry; passing `onMeasureChange` or `onContextChange` already turns the matching half on. |
+| `margin?` | number \| string | — | Outer spacing, matching CSS `margin`. Numbers are pixels; strings accept CSS shorthand, `auto`, negative lengths, and custom properties. Omission adds no style. |
+| `observe?` | 'width' \| 'height' \| 'size' \| 'context' \| 'overflow' \| 'edges' \| 'scroll' \| 'all' \| readonly BoxObservation[] | — | One selection or an array of selections, in any order. `'size'` watches width and height; `'context'` watches rendering context; `'overflow'` watches content dimensions and clipping. `'edges'` reports which edges hide content; `'scroll'` reports offsets, potentially every frame; `'all'` selects everything. Selections are independent: use `['size', 'edges']` to combine them. A measurement handler implies `'size'` when no measurement is selected; a context handler adds `'context'`. Size skips content and scroll observers; overflow adds content observation; hidden edges and scroll add scroll reads. Without handlers or `fade`, omission stays idle. |
 | `onContextChange?` | (event, detail) => void | — | Fired after Box's browser and local rendering context changes. `detail` contains the changed fields and a full current snapshot. |
-| `onMeasureChange?` | (event, detail) => void | — | Fired after Box geometry or its content-overflow state changes. `detail` contains the changed fields and a full current snapshot. |
+| `onMeasureChange?` | (event, detail) => void | — | Fired when a selected measurement field changes. `detail` contains all fields changed since the last event and a full current snapshot. |
+| `padding?` | number \| string | — | Inner spacing, matching CSS `padding`. Numbers are pixels; strings accept CSS shorthand, percentages, and custom properties. Omission adds no style. |
 | `round?` | boolean \| number \| string | — | Fully-round corners (`border-radius: 999px`, clamped to the box). Pass a `number` (px) or a CSS length string (`'1rem'`) for a custom radius. Omit for square corners. |
+| `throttle?` | number | 0 | Minimum interval between measurement events, in milliseconds. The first report has no added delay; a trailing report delivers the latest values. Active observers and CSS clipping states are not throttled. |
 
 ### BoxMeasurement
 
@@ -261,21 +320,21 @@ const canvasRef = useRef<HTMLCanvasElement>(null)
 | Field | Type | Default | Description |
 |------|------|---------|-------------|
 | `backgroundColor` | string | — | Resolved `background-color`. Needed when the box's content is drawn somewhere else — an offscreen canvas, a worker, an export — where the box's own background is not behind it. |
-| `browser` | BoxBrowser | — | Browser family. |
+| `browser` | 'chrome' \| 'edge' \| 'firefox' \| 'opera' \| 'safari' \| 'unknown' | — | Browser family. |
 | `browserVersion` | number | — | Browser major version, or `0` when unknown. Minor and patch digits are frozen by every engine, so only the major number is reported. |
 | `devicePixelRatio` | number | — | `window.devicePixelRatio`: CSS pixels per device pixel. `1` on a standard display, `2` on most Retina screens, and a fraction under OS or browser zoom. Live — it re-reports on zoom and when the window moves to a monitor with a different density. |
 | `focusWithin` | boolean | — | Whether focus is on the box or any of its descendants, read from the native `:focus-within`. For CSS, use that pseudo-class directly; this field is for logic that cannot query the DOM. |
 | `font` | BoxFont | — | Resolved text style, ready to hand to a canvas 2D context. |
-| `globalMode` | BoxMode | — | Mode on `<html>`, independent of an enclosing local scope. |
+| `globalMode` | 'light' \| 'dark' | — | Mode on `<html>`, independent of an enclosing local scope. |
 | `hover` | boolean | — | Whether ordinary hover interaction is available. |
 | `inset` | BoxInset | — | Padding and border widths, for placing content inside the border box. |
 | `mobile` | boolean | — | Whether the browser reports a mobile device. |
-| `mode` | BoxMode | — | Closest scoped Anta mode. A local `.light` can override a dark document. |
-| `os` | BoxOS | — | Operating-system family. |
+| `mode` | 'light' \| 'dark' | — | Closest scoped Anta mode. A local `.light` can override a dark document. |
+| `os` | 'android' \| 'ios' \| 'linux' \| 'macos' \| 'windows' \| 'unknown' | — | Operating-system family. |
 | `osVersion` | number | — | Operating-system major version, or `0` when the browser withholds it. Browsers freeze this: every engine reports macOS as `10.15.7` and Windows 11 as `10.0`, so only Android and iOS carry a real number. Treat it as a hint, never as a gate. |
-| `pointer` | BoxPointer | — | Most precise available primary pointer. |
+| `pointer` | 'fine' \| 'coarse' \| 'none' | — | Most precise available primary pointer. |
 | `reducedMotion` | boolean | — | Whether the reader asks for reduced motion. |
-| `systemAppearance` | BoxMode | — | Browser / operating-system color preference, independent of Anta classes. |
+| `systemAppearance` | 'light' \| 'dark' | — | Browser / operating-system color preference, independent of Anta classes. |
 
 ### BoxFont
 
@@ -318,8 +377,11 @@ const canvasRef = useRef<HTMLCanvasElement>(null)
 ## Web component
 
 Use `<a-box>` without JSX. Events are non-bubbling `CustomEvent`s with the same
-`detail`. Set `observe="size"`, `"context"`, or `"all"` explicitly; adding a
-listener does not enable observation. A bare `observe` means `"all"`.
+`detail`. Set `observe` explicitly; adding a listener does not enable
+observation. Combine the eight selections with spaces, such as
+`observe="size edges"` or `observe="size scroll"`, in any order. Repeated tokens
+have no effect; unknown tokens are ignored. A bare `observe` means `"all"`.
+`throttle="100"` limits measurement events to a 100 ms interval.
 
 ```html title="a-box"
 <a-box display="grid" gap="8px" round="12px" observe="all"
@@ -335,20 +397,22 @@ Import `@antadesign/anta/elements/a-box` to register the element. Listen for
 
 ## Styling
 
-Your `className` and `style` override `display`, `gap`, and `round` through the
+Your `className` and `style` override `display`, `gap`, `padding`, `margin`, and
+`round` through the
 `anta.components` CSS layer.
 
-Without typed CSS `attr()` support, raw `gap`, `round`, and `fade-size` length
-attributes need matching custom properties. The JSX wrapper sets these for you:
+Without typed CSS `attr()` support, raw `gap`, `padding`, `margin`, `round`,
+and `fade-size` attributes need matching custom properties. The JSX wrapper
+sets these for you. Raw HTML lengths need units, such as `padding="16px"`:
 
 ```html
-<a-box display="flex" gap round fade class="raw-box"
-       style="--box-gap: 8px; --box-round: 12px; --box-fade-size: 32px">
+<a-box display="flex" gap padding margin round fade class="raw-box"
+       style="--box-gap: 8px; --box-padding: 12px; --box-margin: 0 auto; --box-round: 12px; --box-fade-size: 32px">
   <span>Layout</span><span>Context</span><span>Measurements</span>
 </a-box>
 ```
 
 ```css
-.raw-box { width: 190px; overflow: auto; padding: 12px; border: 1px solid var(--border-4); }
+.raw-box { width: 190px; overflow: auto; border: 1px solid var(--border-4); }
 .raw-box span { flex: 0 0 auto; }
 ```

package/docs/components/breadcrumbs.md

@@ -4,14 +4,46 @@ 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 data through `items`. An `href` renders a native link with the
-Button appearance; omit it for an action button. Each item accepts `label`,
-`icon`, `iconTrailing`, `tone`, `disabled`, `onClick`, `className`, `style`,
-`id`, `title`, and `data-*` / `aria-*` attributes. `size`, priority, and
-underline treatment belong to the whole trail so every visible control retains
-the same height.
+Pass ordered `BreadcrumbItem` objects through `items`. Each item is a link,
+action, or copy control. `size`, `priority`, and underline treatment belong to
+the whole trail.
+
+### BreadcrumbItem reference
+
+| Property | Possible values | Description |
+| --- | --- | --- |
+| `label` | `React.ReactNode` | Required content, such as text, an image, or JSX. Also used as the label when the item folds into More. |
+| `icon` | `IconShape` | Leading Anta icon shape. |
+| `iconTrailing` | `IconShape` | Trailing Anta icon shape. Available on link and action items. |
+| `tone` | `'neutral'`, `'brand'`, `'info'`, `'success'`, `'warning'`, `'critical'`, or a CSS color string | Item color. Defaults to neutral. |
+| `disabled` | `boolean` | Disables the item. |
+| `current` | `boolean` | Sets `aria-current="page"`. Does not change the tone. |
+| `onClick` | `(event: any) => void` | Activation handler. Folded items call it on menu selection. |
+| `href` | `string` | Destination URL for a link item. |
+| `target` | `string` | Link target, such as `'_blank'`. Requires `href`. |
+| `copy` | `string` | Literal text to copy. |
+| `copyNode` | `boolean` or `string` | `true` copies the nearest ancestor marked `data-copy-source`; a CSS selector chooses an ancestor region. `false` disables the node target. |
+| `copyUrl` | `true` | Copies the current page URL. |
+| `copyWithUrl` | `boolean` | Prefixes literal `copy` text with the current page URL. |
+| `onCopyRequest` | `() => void` | Refreshes a literal `copy` value before activation. Update application state; return values are ignored. |
+| `onCopied` | `(ok: boolean) => void` | Reports whether a copy attempt succeeded. Available on copy items. |
+| `iconPlacement` | `'leading'`, `'trailing'`, or `'none'` | Copy glyph placement. Defaults to `'leading'`. |
+| `copiedLabel` | `string` | Confirmation text for a copy item with no icon. Defaults to `'Copied'`. |
+| `className` | `string` | CSS class on the item control. |
+| `style` | `React.CSSProperties` | Inline styles on the item control. |
+| `id` | `string` | HTML ID on the item control. |
+| `title` | `string` | Native browser tooltip text. |
+| `data-*`, `aria-*` | Attribute-specific values | Attributes forwarded to the item control. |
+
+Use `href` for a link, omit navigation and copy props for an action, or choose
+exactly one of `copy`, `copyNode`, and `copyUrl` for a copy item. Copy items
+cannot use `href`, `target`, or `iconTrailing`. `copyWithUrl` and
+`onCopyRequest` apply only to literal `copy` text.
 
 ```tsx
 <Breadcrumbs
@@ -167,12 +199,49 @@ Use `priority`, `size`, and `separator` before adding CSS. A `className` on
 their individual Buttons. The composed structure uses light-DOM tags, so plain
 CSS can style a separator directly.
 
+To tighten the space between items, give the trail a class and set
+`a-breadcrumb-separator` to `width: 8px` within that class. This changes the
+separator's layout width while keeping the icon size unchanged. The website
+header uses this approach. `project-breadcrumbs` is a demo class; replace it
+with your own selector.
+
 ```tsx
 <Breadcrumbs className="project-breadcrumbs" separator="chevron-right" items={items} />
 ```
 
 ```css
 .project-breadcrumbs a-breadcrumb-separator {
+  width: 8px;
   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

@@ -20,20 +20,20 @@ neutral. Six named tones (`neutral` default), or pass any CSS color for a custom
 
 ## Selected-only tone
 
-`toneSelected` tones the **checked mark only** — the empty box stays neutral grey
-until it's checked. Reach for it instead of `tone` when a resting tinted border would
-read as a validation error. Same value set as `tone`.
+`toneScope="selected"` applies the checkbox's `tone` to the **checked mark only** —
+the empty box stays neutral grey until it's checked. Use it when a resting tinted
+border would read as a validation error.
 
 ```tsx
-<Checkbox toneSelected="brand">Off stays neutral</Checkbox>
-<Checkbox defaultChecked toneSelected="critical">Checked mark tinted</Checkbox>
+<Checkbox tone="brand" toneScope="selected">Off stays neutral</Checkbox>
+<Checkbox defaultChecked tone="critical" toneScope="selected">Checked mark tinted</Checkbox>
 ```
 
 ## Coloring the text
 
 There's no text-tone prop. To tint the **label**, set `color` on the checkbox with a
 theme-aware `--text-N-{tone}` token (the label inherits it); for the **hint**, add a
-`color` rule on the `a-checkbox-hint` child. Pair either with `tone` / `toneSelected`
+`color` rule on the `a-checkbox-hint` child. Pair either with `tone`
 to tint the whole control.
 
 ```css
@@ -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`. |
@@ -182,15 +186,16 @@ Space toggles the checkbox. Follows the [WAI-ARIA checkbox pattern](https://www.
 | `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ checked, indeterminate, name, value }` snapshot as the second argument, matching `Input`'s `onValueChange`. |
 | `round?` | boolean \| number \| string | — | Round the checkbox mark to a circle (`border-radius: 999px` on the box). Pass a `number` (px) or a CSS length string for a rounded-square mark instead. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant. small=14px, medium=16px, large=18px box. |
-| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | 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 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 — recolor them in plain CSS via the theme-aware `--text-N-{tone}` tokens. |
-| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Like `tone`, but 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. |
+| `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?` | '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">
@@ -205,22 +210,22 @@ For a standard HTML form, add `data-anta` to a native checkbox. It keeps the
 browser's label behavior, checked and indeterminate states, and form submission
 while using Anta's control surface.
 
-`size`, `tone`, `tone-selected`, and `round` use the matching Checkbox visual
+`size`, `tone`, `tone-scope`, and `round` use the matching Checkbox visual
 treatments.
 
 ```html
 <div style="display: grid; gap: 8px">
   <label><input data-anta type="checkbox" name="updates" size="small" tone="brand"> Product updates</label>
-  <label><input data-anta type="checkbox" name="security" tone-selected="success" checked> Security notices</label>
+  <label><input data-anta type="checkbox" name="security" tone="success" tone-scope="selected" checked> Security notices</label>
   <label><input data-anta type="checkbox" name="billing" size="large" round tone="warning" checked> Billing alerts</label>
 </div>
 ```
 
 ## Styling
 
-Reach for the props first: **`tone`** colors the mark in every state,
-**`toneSelected`** only the checked mark (any CSS color for a custom tone — it
-derives the full rest/hover/active curve in oklch), **`size`** the dimensions + type.
+Reach for the props first: **`tone`** chooses the mark color and **`toneScope`**
+chooses whether it applies in `all` states or only while `selected` (any CSS color
+derives the full rest/hover/active curve in oklch); **`size`** controls dimensions + type.
 To tint the label + hint, add a `color` rule (on the host for the label, on
 `a-checkbox-hint` for the hint) with the `--text-N-{tone}` tokens — there's no
 text-tone prop. The focus ring is the global

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