@antadesign/anta 0.3.26 → 0.3.28

package/docs/components/breadcrumbs.md

@@ -6,12 +6,41 @@ More menu without measuring the available width.
 
 ## 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
@@ -111,16 +140,13 @@ Use `copyUrl` to copy `location.href`, `copyNode` to copy a marked rendered
 region, or `copy` for a known string. For dynamic text, pass a controlled `copy`
 string and set it from `onCopyRequest`. `onCopied` receives the result.
 
-### Props
+## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `items` | BreadcrumbItem[] | — | Ordered breadcrumb entries. |
-| `itemsBeforeCollapse?` | number | 0 | Number of original items kept before the More control when `maxItems`
- collapses the trail. The rest of the visible-item budget is kept from the
- end, so `0` puts More first. |
-| `maxItems?` | number | — | Maximum number of original breadcrumb items left visible. The More
- control does not count. Omit to keep every item visible. |
+| `itemsBeforeCollapse?` | number | 0 | Number of original items kept before the More control when `maxItems` collapses the trail. The rest of the visible-item budget is kept from the end, so `0` puts More first. |
+| `maxItems?` | number | — | Maximum number of original breadcrumb items left visible. The More control does not count. Omit to keep every item visible. |
 | `moreLabel?` | string | 'Show more breadcrumbs' | Accessible name for the More control. |
 | `paddingless?` | boolean | — | Remove horizontal padding from every visible breadcrumb control. |
 | `priority?` | 'quaternary' \| 'tertiary' | quaternary | Button priority applied to every visible item and the More control. |
@@ -129,6 +155,8 @@ string and set it from `onCopyRequest`. `onCopied` receives the result.
 | `underline?` | 'solid' \| 'dashed' \| 'dotted' | — | Underline style applied to every visible breadcrumb control. |
 | `underlineOnHover?` | boolean | — | Hide the underline at rest and reveal it on hover. |
 
+## Web Component
+
 `Breadcrumbs` deliberately adds no custom-element behavior: it assembles Anta
 Buttons, an optional Menu, and two light-DOM layout tags. When you are not using
 JSX, import the Breadcrumbs stylesheet and the primitives, then compose the same
@@ -161,17 +189,26 @@ import '@antadesign/anta/elements'
 </a-breadcrumbs>
 ```
 
+## Styling
+
 Use `priority`, `size`, and `separator` before adding CSS. A `className` on
 `Breadcrumbs` lands on the navigation wrapper; item `className` values land 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);
 }
 ```

package/docs/components/button.md

@@ -217,6 +217,8 @@ underline stylistically, it supports three styles — `solid`, `dashed`,
 - **`selected`** — toggled-on / pressed visual; shares the active
   state's look. Useful for filter chips and icon toggles.
 
+## ButtonCopy
+
 `ButtonCopy` is a copy button — a `Button` preset for copy-to-clipboard. It
 composes a plain `<Button>` with a slotted `<a-copy>` element that writes to the
 clipboard when the button is activated. A button with a copy glyph changes the
@@ -329,57 +331,32 @@ current URL (`copyUrl`).
 |------|------|---------|-------------|
 | `copiedLabel?` | string | Copied | Text in the successful no-icon confirmation. |
 | `copy?` | string | — | Text copied to the clipboard on activation. |
-| `copyNode?` | boolean \| string | — | Copy a DOM node as rich text (`text/html`) + plain text. `true` copies
- the nearest ancestor marked `data-copy-source`; a string is a CSS
- selector for an ancestor region (`closest`). The copy control is stripped
- from the copied output. |
+| `copyNode?` | boolean \| string | — | Copy a DOM node as rich text (`text/html`) + plain text. `true` copies the nearest ancestor marked `data-copy-source`; a string is a CSS selector for an ancestor region (`closest`). The copy control is stripped from the copied output. |
 | `copyUrl?` | true | — | Copy the current page URL (`location.href`). |
 | `copyWithUrl?` | boolean | — | Prefix the copied text with `// URL: <current page URL>`. |
 | `disabled?` | boolean | — | Disable the button. |
 | `download?` | string \| boolean | — | Anchor download attribute. Empty string / `true` triggers a download with the resource's default name; a string overrides the filename. |
 | `form?` | string | — | Form id when the button isn't a descendant of its form. |
-| `href?` | string | — | URL to link to. A definite string renders `<a role="button">`; omit it
- (or pass `undefined`) to render `<a-button>`, so `href={maybeUrl}`
- degrades to a plain button when the URL is absent. |
-| `icon?` | IconShape | — | Leading icon shape. When set alone (no `label`, no `iconTrailing`, no
- `children`), the button renders as a square icon-only control and
- the wrapper auto-supplies `aria-label={icon}` (override by passing
- your own `aria-label`). |
-| `iconPlacement?` | 'leading' \| 'trailing' \| 'none' | 'leading' | Where the copy glyph sits relative to the label — or `'none'` to omit it.
- Without a glyph, a successful copy shows a small confirmation label near
- the pointer and leaves the button unchanged. |
+| `href?` | string | — | URL to link to. A definite string renders `<a role="button">`; omit it (or pass `undefined`) to render `<a-button>`, so `href={maybeUrl}` degrades to a plain button when the URL is absent. |
+| `icon?` | IconShape | — | Leading icon shape. When set alone (no `label`, no `iconTrailing`, no `children`), the button renders as a square icon-only control and the wrapper auto-supplies `aria-label={icon}` (override by passing your own `aria-label`). |
+| `iconPlacement?` | 'leading' \| 'trailing' \| 'none' | 'leading' | Where the copy glyph sits relative to the label — or `'none'` to omit it. Without a glyph, a successful copy shows a small confirmation label near the pointer and leaves the button unchanged. |
 | `iconTrailing?` | IconShape | — | Trailing icon shape. Renders after `children`, last in the slot order. |
 | `label?` | string | — | Label text. Renders between the leading icon and `children`. |
-| `loading?` | boolean | — | Show a rotating loading indicator. Blocks clicks and keyboard
- activation, and removes the button from the tab order while active. |
+| `loading?` | boolean | — | Show a rotating loading indicator. Blocks clicks and keyboard activation, and removes the button from the tab order while active. |
 | `onClick?` | (e) => void | — | Click handler. |
 | `onCopied?` | (ok) => void | — | Fires after the copy attempt with whether it succeeded. |
-| `onCopyRequest?` | () => void | — | Refresh a dynamic `copy` value before activation. Set the new string in
- application state so the next render updates `copy`. Return values are
- ignored. Fires on pointerdown and Enter/Space keydown. |
+| `onCopyRequest?` | () => void | — | Refresh a dynamic `copy` value before activation. Set the new string in application state so the next render updates `copy`. Return values are ignored. Fires on pointerdown and Enter/Space keydown. |
 | `paddingless?` | boolean | — | Drops outer padding to zero. |
 | `ping?` | string | — | Space-separated URLs the browser pings on navigation. |
 | `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | secondary | Visual emphasis. |
 | `rel?` | string | — | Anchor rel. |
-| `role?` | string | button | ARIA role override (e.g. `'gridcell'` when a button is a cell in a grid).
- Forwarded to the underlying element. |
-| `round?` | boolean \| number \| string | — | Fully-round corners — a pill for text buttons, a circle for icon-only ones
- (`border-radius: 999px`, clamped to the element's height). Pass a `number`
- (px) or a CSS length string (`'1rem'`) for a custom radius instead. |
+| `role?` | string | button | ARIA role override (e.g. `'gridcell'` when a button is a cell in a grid). Forwarded to the underlying element. |
+| `round?` | boolean \| number \| string | — | Fully-round corners — a pill for text buttons, a circle for icon-only ones (`border-radius: 999px`, clamped to the element's height). Pass a `number` (px) or a CSS length string (`'1rem'`) for a custom radius instead. |
 | `selected?` | boolean | — | Toggled-on / pressed state, e.g. for filter chips. |
-| `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. small=24px, medium=28px, large=32px. Omit the
- attribute or pass `'medium'` for the default — both render
- identically and emit no DOM attribute. |
-| `tabIndex?` | number | 0 | Tab order. The button is keyboard-focusable by default (`0`) and
- becomes `-1` automatically while `disabled` or `loading` — `<a-button>`
- and `<a role="button">` aren't focusable without an explicit tabindex,
- and a loading button must stay out of the tab order so Enter/Space can't
- fire it mid-flight. |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. small=24px, medium=28px, large=32px. Omit the attribute or pass `'medium'` for the default — both render identically and emit no DOM attribute. |
+| `tabIndex?` | number | 0 | Tab order. The button is keyboard-focusable by default (`0`) and becomes `-1` automatically while `disabled` or `loading` — `<a-button>` and `<a role="button">` aren't focusable without an explicit tabindex, and a loading button must stay out of the tab order so Enter/Space can't fire it mid-flight. |
 | `target?` | string | — | Anchor target. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`)
- for a one-off custom tone. Primary uses the color as-is; secondary,
- tertiary, and quaternary take its hue and pin lightness/chroma to the
- brand curve so any input stays legible. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone. Primary uses the color as-is; secondary, tertiary, and quaternary take its hue and pin lightness/chroma to the brand curve so any input stays legible. |
 | `type?` | 'button' \| 'submit' \| 'reset' | — | Form submission type. |
 | `underline?` | 'solid' \| 'dashed' \| 'dotted' | — | Underline style. |
 | `underlineOnHover?` | boolean | — | Hide the underline at rest and reveal it on hover. |
@@ -405,6 +382,8 @@ split or conditional spread:
 <Button href={reportUrl} disabled={!reportUrl} iconTrailing="external-link" label="View report" />
 ```
 
+### Routing libraries
+
 Anta's CSS targets `a-button, a[role="button"][data-anta]` — an anchor (`<a>`)
 with `role="button"`, the `data-anta` opt-in marker, and the right attributes
 gets the styling. That means anta doesn't need an `as` / `asChild` /
@@ -453,6 +432,8 @@ Usage:
 This approach would work for Next.js `<Link>`, TanStack Router, or any
 other routing library.
 
+## Special events
+
 Beyond a plain click, a `Button` can drive a native form or emit your own
 event:
 
@@ -483,7 +464,35 @@ without taking ownership of `onClick`.
 <Button tone="brand" label="Save" data-custom-event="save-clicked" />
 ```
 
-### Props
+## Component props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `disabled?` | boolean | — | Disable the button. |
+| `download?` | string \| boolean | — | Anchor download attribute. Empty string / `true` triggers a download with the resource's default name; a string overrides the filename. |
+| `form?` | string | — | Form id when the button isn't a descendant of its form. |
+| `href?` | string | — | URL to link to. A definite string renders `<a role="button">`; omit it (or pass `undefined`) to render `<a-button>`, so `href={maybeUrl}` degrades to a plain button when the URL is absent. |
+| `icon?` | IconShape | — | Leading icon shape. When set alone (no `label`, no `iconTrailing`, no `children`), the button renders as a square icon-only control and the wrapper auto-supplies `aria-label={icon}` (override by passing your own `aria-label`). |
+| `iconTrailing?` | IconShape | — | Trailing icon shape. Renders after `children`, last in the slot order. |
+| `label?` | string | — | Label text. Renders between the leading icon and `children`. |
+| `loading?` | boolean | — | Show a rotating loading indicator. Blocks clicks and keyboard activation, and removes the button from the tab order while active. |
+| `onClick?` | (e) => void | — | Click handler. |
+| `paddingless?` | boolean | — | Drops outer padding to zero. |
+| `ping?` | string | — | Space-separated URLs the browser pings on navigation. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | secondary | Visual emphasis. |
+| `rel?` | string | — | Anchor rel. |
+| `role?` | string | button | ARIA role override (e.g. `'gridcell'` when a button is a cell in a grid). Forwarded to the underlying element. |
+| `round?` | boolean \| number \| string | — | Fully-round corners — a pill for text buttons, a circle for icon-only ones (`border-radius: 999px`, clamped to the element's height). Pass a `number` (px) or a CSS length string (`'1rem'`) for a custom radius instead. |
+| `selected?` | boolean | — | Toggled-on / pressed state, e.g. for filter chips. |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. small=24px, medium=28px, large=32px. Omit the attribute or pass `'medium'` for the default — both render identically and emit no DOM attribute. |
+| `tabIndex?` | number | 0 | Tab order. The button is keyboard-focusable by default (`0`) and becomes `-1` automatically while `disabled` or `loading` — `<a-button>` and `<a role="button">` aren't focusable without an explicit tabindex, and a loading button must stay out of the tab order so Enter/Space can't fire it mid-flight. |
+| `target?` | string | — | Anchor target. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone. Primary uses the color as-is; secondary, tertiary, and quaternary take its hue and pin lightness/chroma to the brand curve so any input stays legible. |
+| `type?` | 'button' \| 'submit' \| 'reset' | — | Form submission type. |
+| `underline?` | 'solid' \| 'dashed' \| 'dotted' | — | Underline style. |
+| `underlineOnHover?` | boolean | — | Hide the underline at rest and reveal it on hover. |
+
+## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
@@ -520,6 +529,8 @@ wrapper sets them for you). A native `<button>` also carries its own default
 <button data-anta tone="critical" priority="tertiary">Delete</button>
 ```
 
+## Styling
+
 Reach for the props first: **`tone`** sets the color (any CSS color for a custom
 tone — it derives the whole tone × priority × state curve in oklch), **`priority`**
 the emphasis, **`size`** the dimensions. The focus ring is the global

package/docs/components/capture.md

@@ -0,0 +1,345 @@
+# Capture
+
+`Capture` is a light-DOM input surface for custom tables, plots, and drag
+interactions. Wheel capture, pointer capture, and panning are all disabled by default.
+
+## Usage
+
+Each capability is opt-in; handlers alone enable nothing. Choose by interaction:
+
+| Interaction | Capability | Your component handles |
+| --- | --- | --- |
+| Mouse wheel or trackpad scrolling | `wheelCapture` | Scroll offsets or zoom |
+| Touchscreen drag to scroll | `pan` | Scroll offsets from pan deltas |
+| Drag to select, resize, or draw | `pointerCapture` | Raw pointer samples |
+
+Disabled Capture surfaces add no input state or listeners.
+
+Capture cancels accepted native input on the browser thread, then sends plain data
+to your handler. Your component performs the action. Forward the serializable
+`detail` across worker boundaries. Handler return values cannot change cancellation.
+
+For a 2D table, combine `wheelCapture` and `pan` for scrolling with
+`pointerCapture={{ pointerTypes: ['mouse', 'pen'] }}` for selection. Each
+handler updates the corresponding scroll or selection state.
+
+## Wheel ownership
+
+Set `wheelCapture` to `true` for all directions, or update allowed directions
+from your component's bounds. Declined input reaches the enclosing editor or
+scroll container. The dominant axis decides ownership; both deltas are delivered.
+All-false bounds preserve settling while declining input. Passing `false` or
+removing `wheelCapture` disables capture and clears settling.
+
+Enable **Capture wheel**, then scroll over the rows. The controls let you try
+different activation and settling rules.
+
+```tsx title="Custom table wheel"
+const [offset, setOffset] = useState(0)
+const maxOffset = 28 * 32 - 192
+
+// These settings come from the preview controls.
+<div onKeyDown={event => {
+  if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+  event.preventDefault()
+  const delta = event.key === 'ArrowDown' ? 32 : -32
+  setOffset(value => Math.max(0, Math.min(maxOffset, value + delta)))
+}}>
+  <Capture
+    wheelCapture={enabled && { up: offset > 0, down: offset < maxOffset }}
+    wheelActivation={activation}
+    wheelSettle={{ delay, tolerance: 5, resetOnMove }}
+    tabIndex={0}
+    aria-label="Wheel capture surface"
+    style={{ height: 192, overflow: 'hidden' }}
+    onWheelInput={(_, { wheelEvent, boxHeight }) => {
+      const unit = wheelEvent.deltaMode === 1 ? 32 : wheelEvent.deltaMode === 2 ? boxHeight : 1
+      setOffset(value => Math.max(0, Math.min(maxOffset, value + wheelEvent.deltaY * unit)))
+    }}
+  >
+    <div style={{ transform: `translateY(${-offset}px)` }}>
+      {Array.from({ length: 28 }, (_, index) => (
+        <div key={index} style={{ height: 32 }}>Sample {index + 1}</div>
+      ))}
+    </div>
+  </Capture>
+</div>
+```
+
+The default `"settled"` activation waits for the pointer to rest inside Capture
+(150ms, 5px tolerance). It stays active until the pointer leaves.
+`wheelSettle.resetOnMove` requires settling again after movement beyond tolerance.
+Scrolling a Capture under a stationary pointer does not activate it.
+
+Use `"hover"` for immediate activation, `"focus"` for `:focus-within`, or
+`"settled-or-focus"` for either condition. Wheel input must still target Capture.
+Capture never takes focus automatically; provide `tabIndex` or a focusable child.
+
+Modified input stays native by default, including Ctrl/pinch zoom. Use
+`wheelModifier="ctrl"` to capture Ctrl-wheel, or `"any"` for all modifiers.
+Named modifiers allow other keys too.
+
+The innermost eligible Capture handles wheel input on its host. Canceled and
+non-cancelable events are ignored; Capture cannot undo an ancestor's capture-phase
+handler. Capture skips nested `textarea`, `select`, numeric/range inputs, and
+Anta menus. Mark other native scroll panes with `data-capture-ignore`.
+
+`detail.wheelEvent` preserves native event data, signs, and `deltaMode` units
+(0: pixels, 1: lines, 2: pages). Capture does not infer OS scrolling preferences.
+`localX` and `localY` are CSS pixels from Capture's viewport rectangle's top-left,
+without undoing transforms. Native `offsetX` and `offsetY` refer to the original
+target, which may be a child.
+
+## Pointer sessions
+
+`pointerCapture` sends raw data for one primary mouse, pen, or touch pointer,
+including movement outside Capture. Your component interprets the gesture.
+Use `threshold` to delay capture until dragging starts. Drag an area in the
+preview, or select **Select sample area** with the keyboard.
+
+```tsx title="Mouse or pen selection"
+type Selection = { x: number; y: number; width: number; height: number }
+const [selection, setSelection] = useState<Selection | null>(null)
+
+<Button label="Select sample area" onClick={() => setSelection({ x: 24, y: 24, width: 100, height: 64 })} />
+<Button label="Clear selection" onClick={() => setSelection(null)} />
+<Capture
+  className="pointer-probe-surface"
+  aria-label="Pointer selection surface"
+  pointerCapture={{ pointerTypes: ['mouse', 'pen'], threshold: 3 }}
+  onPointerInput={(_, detail) => {
+    if (detail.phase === 'cancel') return
+    const x = Math.max(0, Math.min(detail.boxWidth, detail.localX))
+    const y = Math.max(0, Math.min(detail.boxHeight, detail.localY))
+    setSelection({
+      x: Math.min(detail.start.localX, x), y: Math.min(detail.start.localY, y),
+      width: Math.abs(x - detail.start.localX), height: Math.abs(y - detail.start.localY),
+    })
+  }}
+>
+  <Text size="small" priority="tertiary">Drag to select an area.</Text>
+  {selection && <div className="pointer-probe-selection"
+    style={{ left: selection.x, top: selection.y, width: selection.width, height: selection.height }} />}
+</Capture>
+```
+
+```css
+.pointer-probe-surface { position: relative; height: 160px; overflow: hidden; border: 1px solid var(--border-4); border-radius: 8px; background: var(--bg-canvas); }
+.pointer-probe-surface a-text { display: block; padding: 12px; }
+.pointer-probe-selection { position: absolute; pointer-events: none; border: 1px solid var(--border-3-brand); background: color-mix(in oklch, var(--text-1-brand) 12%, transparent); }
+```
+
+`onPointerInput` reports `start`, `move`, `end`, and `cancel`. `deltaX/Y` are
+incremental movement; `movementX/Y` are totals from the press, positive right/down.
+
+Presses below threshold emit nothing. Captured gestures suppress the following
+pointer-generated click. Cancellation reports `cancelReason` on pointer
+cancellation, lost capture, disabling, removal, or window blur/hiding.
+Lifecycle cancellation sets `pointerEvent: null`.
+Capture cancels native behavior without stopping pointer-event propagation.
+
+Pointer and pan capture skip nested native/ARIA controls, links, and editable content.
+`pointerCapture.includeInteractive` includes them. Use `data-capture-ignore`
+to exclude a subtree from all capture, including wheel. It does not remove
+ancestor `touch-action` restrictions.
+
+## Touch panning and inertia
+
+`pan` converts touchscreen dragging into scroll deltas without inertia. It
+captures the pointer internally; it does not require `pointerCapture`. Set
+`pan.pointerTypes` to enable mouse or pen panning. If your component already
+interprets touch gestures, use `pointerCapture` for touch and omit `pan`.
+
+Enabling both for the same pointer type emits both streams. Assign separate
+pointer types when each gesture should have one handler.
+
+Try touch panning, or enable **Pan with mouse**. **Inertia** continues motion
+after release; turn it off to stop when the pointer lifts.
+
+```tsx title="Custom touch scrolling"
+const [offset, setOffset] = useState(0)
+const maxOffset = 18 * 32 - 160
+const move = (delta: number) => setOffset(value => Math.max(0, Math.min(maxOffset, value + delta)))
+
+// mouse and inertia come from the preview checkboxes.
+<div onKeyDown={event => {
+  if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+  event.preventDefault()
+  move(event.key === 'ArrowDown' ? 32 : -32)
+}}>
+  <Capture
+    className="pan-probe-surface"
+    tabIndex={0}
+    aria-label="Pan capture surface"
+    pan={{
+      axis: 'y',
+      pointerTypes: mouse ? ['touch', 'mouse'] : ['touch'],
+      directions: { up: offset > 0, down: offset < maxOffset },
+      inertia,
+    }}
+    onPanInput={(_, { deltaY }) => move(deltaY)}
+  >
+    <div style={{ transform: `translateY(${-offset}px)` }}>
+      {Array.from({ length: 18 }, (_, index) => (
+        <div className="pan-probe-row" key={index}>Sample {index + 1}</div>
+      ))}
+    </div>
+  </Capture>
+</div>
+```
+
+```css
+.pan-probe-surface { height: 160px; overflow: hidden; border: 1px solid var(--border-4); border-radius: 8px; background: var(--bg-canvas); }
+.pan-probe-row { height: 32px; box-sizing: border-box; padding: 6px 12px; border-bottom: 1px solid var(--border-5); }
+```
+
+Pan deltas oppose finger movement. Apply deltas from every phase, including
+`release`. Inertia samples have `pointerEvent: null`. Motion stops on new input,
+disabled directions, or cancellation.
+
+Capture sets CSS `touch-action` before contact. Single-axis pan leaves the other
+axis and pinch zoom to the browser. Both-axis pan or touch pointer capture owns
+the whole gesture; mouse-only capture leaves touch unchanged. Unlike wheel,
+an active touch gesture cannot return to native scrolling at a bound. Update
+directions to stop custom motion and control the next gesture.
+Empty pointer-type or button lists disable that capability without restricting
+native text selection or touch gestures.
+
+## Component props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onPanInput?` | (event, detail) => void | — | Custom pan motion and its lifecycle. Inertial samples have no native pointer event. |
+| `onPointerInput?` | (event, detail) => void | — | Start, movement, end, and cancellation of an opted-in pointer session. |
+| `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. |
+| `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. |
+| `wheelSettle?` | CaptureWheelSettle | { delay: 150, tolerance: 5, resetOnMove: false } | Dwell delay, movement tolerance, and whether movement resets eligibility. |
+
+### CaptureWheelSettle
+
+| Option | Type | Default | Description |
+|------|------|---------|-------------|
+| `delay?` | number | 150 | Pointer dwell time in milliseconds. |
+| `resetOnMove?` | boolean | false | Restart dwell after movement beyond tolerance, including after activation. |
+| `tolerance?` | number | 5 | Maximum movement from the dwell anchor on either axis, in CSS pixels. |
+
+### CapturePointerCapture
+
+| Option | Type | Default | Description |
+|------|------|---------|-------------|
+| `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. |
+| `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. |
+
+### CapturePan
+
+| Option | Type | Default | Description |
+|------|------|---------|-------------|
+| `axis?` | 'x' \| 'y' \| 'both' | both | Axes handled by custom panning. CSS touch-action leaves the other axis to the browser. |
+| `directions?` | CaptureInputDirections | true | Allowed scroll directions. Updating these can stop motion at application bounds. |
+| `inertia?` | boolean \| CapturePanInertia | false | Continue panning after release with browser-side velocity decay. |
+| `pointerTypes?` | readonly CapturePointerType[] | ['touch'] | Accepted pointer devices. |
+| `threshold?` | number | 3 | Movement required before activation, in viewport CSS pixels. |
+
+### CapturePanInertia
+
+| Option | Type | Default | Description |
+|------|------|---------|-------------|
+| `minVelocity?` | number | 0.02 | Stop when speed on both axes falls below this value, in CSS pixels/ms. |
+| `timeConstant?` | number | 325 | Exponential velocity decay time constant in milliseconds. |
+
+### CaptureWheelInput
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| `activationReason` | CaptureWheelActivationReason | — |  |
+| `boxHeight` | number | — |  |
+| `boxWidth` | number | — | Dimensions of the same viewport bounding rectangle, in CSS pixels. |
+| `focusWithin` | boolean | — |  |
+| `inside` | boolean | — | Whether the pointer is inside that rectangle. Capture can continue outside it. |
+| `localX` | number | — | Pointer position relative to the viewport bounding rectangle's top-left, in CSS pixels. |
+| `localY` | number | — |  |
+| `wheelEvent` | SerializedWheelEvent | — |  |
+
+### CapturePointerInput
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| `activationReason` | CapturePointerActivationReason | — |  |
+| `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. |
+| `deltaY` | number | — |  |
+| `focusWithin` | boolean | — |  |
+| `inside` | boolean | — | Whether the pointer is inside that rectangle. Capture can continue outside it. |
+| `localX` | number | — | Pointer position relative to the viewport bounding rectangle's top-left, in CSS pixels. |
+| `localY` | number | — |  |
+| `movementX` | number | — | Total movement from the initial press, in viewport CSS pixels. |
+| `movementY` | number | — |  |
+| `phase` | 'start' \| 'move' \| 'end' \| 'cancel' | — |  |
+| `pointerEvent` | SerializedPointerEvent \| null | — | Null when cancellation comes from lifecycle or configuration changes. |
+| `start` | CapturePointerStart | — |  |
+| `cancelReason?` | CaptureInputCancelReason | — |  |
+
+### CapturePanInput
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| `activationReason` | CapturePointerActivationReason | — |  |
+| `boxHeight` | number | — |  |
+| `boxWidth` | number | — | Dimensions of the same viewport bounding rectangle, in CSS pixels. |
+| `deltaX` | number | — | Incremental scroll motion in viewport CSS pixels. |
+| `deltaY` | number | — |  |
+| `focusWithin` | boolean | — |  |
+| `inside` | boolean | — | Whether the pointer is inside that rectangle. Capture can continue outside it. |
+| `localX` | number | — | Pointer position relative to the viewport bounding rectangle's top-left, in CSS pixels. |
+| `localY` | number | — |  |
+| `phase` | 'start' \| 'move' \| 'release' \| 'inertia' \| 'end' \| 'cancel' | — |  |
+| `pointerEvent` | SerializedPointerEvent \| null | — | Null during momentum or cancellation without a pointer event. |
+| `start` | CapturePointerStart | — |  |
+| `velocityX` | number | — | Scroll velocity in viewport CSS pixels/ms. |
+| `velocityY` | number | — |  |
+| `cancelReason?` | CaptureInputCancelReason | — |  |
+
+## Web component
+
+Use `<a-capture>` without JSX. Events are non-bubbling `CustomEvent`s
+with the same `detail`. Adding listeners enables no capabilities.
+
+Import `@antadesign/anta/elements/a-capture` to register the element. A bare
+Capture leaves wheel and touch scrolling native:
+
+```html title="a-capture"
+<a-capture class="native-capture">
+  <p>Native scrolling stays enabled.</p>
+  <p>No wheel, pointer, or pan input is captured.</p>
+  <p>Scroll to the end of this content.</p>
+  <p>The browser owns this scroll position.</p>
+</a-capture>
+```
+
+```css
+.native-capture { width: 100%; height: 120px; overflow: auto; padding: 12px; border: 1px solid var(--border-4); border-radius: 8px; }
+.native-capture p { margin: 0; padding-block: 12px; }
+```
+
+Configure capture with attributes such as `wheel-capture="up down"` or `pan="y"`.
+Bare capability attributes match passing `true` in JSX. Remove an attribute to
+disable it. Listen for `wheelinput`, `pointerinput`, and `paninput` with
+`addEventListener`; each event exposes the same `detail` as the JSX handler.
+
+## Styling
+
+Capture renders a block container with no shadow root. Use `className` or
+`style` for layout, size, and appearance. Keep a CSS box on the host so its
+bounds define the input surface and local coordinates.
+
+Use [Box](./box.md) around Capture when you also need measurements, context events,
+or edge fades. Box measures its own bounds; Capture reports coordinates relative
+to its own bounds.