@antadesign/anta 0.3.25 → 0.3.27

package/docs/components/box.md

@@ -0,0 +1,354 @@
+# Box
+
+`Box` is a DOM container with layout props, overflow states, and browser context
+events. For custom wheel, pointer, and touch handling, use [Capture](./capture.md).
+
+## 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.
+
+```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>
+```
+
+## 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.
+
+`.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="size" 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' }}>
+  One. Two. Three. Four. Five. Six. Seven. Eight. Nine. Ten.
+</Box>
+```
+
+```css
+.edge:state(clipped-x) { border-color: var(--border-3-warning); }
+.edge:state(scrollable-y) { border-color: var(--border-3-info); }
+```
+
+### Fading a clipped edge
+
+`fade` masks edges with hidden content and removes the mask as scrolling reveals
+them. `fadeSize` sets its depth. It measures on connection, even off screen.
+
+```tsx
+const TAGS = ['frontend', 'design-system', 'a11y', 'performance']
+
+<Box fade fadeSize={32} round display="flex" gap={6} className="fade-demo" style={{ width: 190, overflowX: 'auto' }}>
+  {TAGS.map((t) => <Tag key={t} size="small" label={t} />)}
+</Box>
+
+<Box fade fadeSize={32} round={8} className="fade-demo" style={{ width: 190, height: 56, overflowY: 'auto' }}>
+  One. Two. Three. Four. Five. Six. Seven. Eight. Nine. Ten. Eleven. Twelve.
+</Box>
+```
+
+```css
+.fade-demo { flex-wrap: nowrap; padding: 10px; border: 1px solid var(--border-4); }
+.fade-demo a-tag { flex: 0 0 auto; }
+```
+
+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
+`hidden-start-x`, `hidden-end-x`, `hidden-start-y`, or `hidden-end-y` CSS states.
+
+### Tooltip on clipped content
+
+`Tooltip truncatedOnly` shows when Box clips content on either axis, including
+wrapped children.
+
+```tsx
+const TAGS = ['frontend', 'design-system', 'a11y', 'performance']
+
+<Box display="flex" round={8} gap={6} className="tag-box" style={{ height: 34 }}>
+  {TAGS.map((t) => <Tag key={t} size="small" label={t} />)}
+  <Tooltip truncatedOnly>{TAGS.join(' · ')}</Tooltip>
+</Box>
+```
+
+```css
+.tag-box { flex-wrap: wrap; padding: 6px; overflow: hidden; }
+```
+
+## 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.
+
+```tsx title="measurechange"
+const [measurement, setMeasurement] = useState<BoxMeasurement | null>(null)
+
+<Box
+  round={8}
+  className="measure-probe-box"
+  onMeasureChange={(_, { current }) => setMeasurement(current)}
+>
+  <Text size="small" priority="tertiary">Resize or scroll this Box.</Text>
+  <div className="measure-probe-wide">wide content, so both axes overflow</div>
+  <div className="measure-probe-wide">and a second line, so the vertical axis does too</div>
+  <div className="measure-probe-wide">and a third</div>
+</Box>
+
+<div className="measure-probe-readout">
+  {Object.entries(measurement ?? {}).map(([field, value]) => (
+    <Tag key={field} size="small" label={field} value={String(value)} />
+  ))}
+</div>
+```
+
+```css
+.measure-probe-box {
+  resize: both;
+  overflow: auto;
+  inline-size: 320px;
+  block-size: 132px;
+  min-inline-size: 120px;
+  min-block-size: 64px;
+  padding: 10px;
+  border: 1px solid var(--border-4);
+}
+.measure-probe-wide { inline-size: 520px; padding-block: 6px; }
+.measure-probe-readout { display: flex; flex-wrap: wrap; gap: 6px; }
+```
+
+See the [measurement fields](#boxmeasurement). Overflow fields map to kebab-case
+CSS states, such as `clippedX` → `:state(clipped-x)`.
+
+## Context
+
+`onContextChange` reports theme, focus, and browser context as
+`{ changed, current }`. See the [context fields](#boxcontext). For CSS, use
+`:focus-within`, mode classes, and media queries instead.
+
+Switch themes, resize, or zoom to update the preview. The `.light` Box keeps its
+local `mode`; `globalMode` follows the document. Browser and OS versions may be
+frozen, so use `pointer`, `hover`, or feature tests to choose behavior.
+
+```tsx title="contextchange"
+import { useState } from 'react'
+import { Box, Tag, Text, type BoxContext } from '@antadesign/anta'
+
+function ScopedContext() {
+  const [context, setContext] = useState<BoxContext | null>(null)
+
+  return (
+    <div className="light">
+      <Box display="flex" round={8} gap={6} className="context-probe-box"
+           onContextChange={(_, { current }) => setContext(current)}>
+        <Text size="small" priority="tertiary">inside a .light scope</Text>
+        <Tag size="small" tone="brand" label="mode" value={context?.mode ?? '…'} />
+        <Tag size="small" label="globalMode" value={context?.globalMode ?? '…'} />
+      </Box>
+    </div>
+  )
+}
+```
+
+```css
+.context-probe-box {
+  flex-wrap: wrap;
+  align-items: center;
+  padding: 10px;
+  border: 1px solid var(--border-4);
+  background: var(--bg-1);
+  color: var(--text-1);
+}
+```
+
+<a id="canvas"></a>
+
+### Canvas-related styles
+
+Use `context.font` and `devicePixelRatio` to match canvas text to the DOM.
+The first line is DOM text; the second is drawn on canvas. Switch themes or
+zoom to update both. `context.inset` also reports border and padding when you
+need to align drawing coordinates with the Box's content edge.
+
+Set `ctx.font` before spacing and direction. Box assembles `font.shorthand`
+because `getComputedStyle(element).font` can be empty. Stretch and variant caps
+remain separate fields; percentage stretch is invalid in the shorthand.
+
+```tsx title="canvas"
+const canvasRef = useRef<HTMLCanvasElement>(null)
+
+<Box className="canvas-probe"
+  onContextChange={(_, { current }) => {
+    const canvas = canvasRef.current
+    const ctx = canvas?.getContext('2d')
+    if (!canvas || !ctx) return
+
+    const { font, devicePixelRatio: dpr } = current
+    canvas.width = canvas.clientWidth * dpr
+    canvas.height = canvas.clientHeight * dpr
+    ctx.scale(dpr, dpr)
+
+    ctx.font = font.shorthand
+    ctx.letterSpacing = font.letterSpacing
+    ctx.wordSpacing = font.wordSpacing
+    ctx.direction = font.direction === 'rtl' ? 'rtl' : 'ltr'
+    ctx.fillStyle = font.color
+
+    ctx.fillText('Matches the DOM', 0, font.lineHeight ?? font.size)
+  }}
+>
+  <span>Matches the DOM</span>
+  <canvas ref={canvasRef} aria-label="Canvas text using the Box font and color" />
+</Box>
+```
+
+```css
+.canvas-probe { width: 100%; font-size: 20px; line-height: 32px; color: var(--text-1); }
+.canvas-probe canvas { display: block; width: 100%; height: 48px; }
+```
+
+## Component props
+
+| 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. |
+| `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. |
+| `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. |
+| `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. |
+
+### BoxMeasurement
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| `clientHeight` | number | — |  |
+| `clientWidth` | number | — | Padding-box dimensions, matching the browser's `clientWidth` / `clientHeight`. |
+| `clippedX` | boolean | — | The exceeded content is visually clipped on this axis. |
+| `clippedY` | boolean | — |  |
+| `height` | number | — |  |
+| `hiddenEndX` | boolean | — |  |
+| `hiddenEndY` | boolean | — |  |
+| `hiddenStartX` | boolean | — | Clipped content sits past this specific edge, in logical writing-mode terms. A clipped box that has not been scrolled hides content past its end edge only; scroll it to the end and the hidden content moves to the start. These drive the `fade` mask. |
+| `hiddenStartY` | boolean | — |  |
+| `overflowX` | boolean | — | Content exceeds the padding box on this axis, regardless of CSS overflow. |
+| `overflowY` | boolean | — |  |
+| `scrollableX` | boolean | — | The exceeded content can be scrolled by the reader on this axis. |
+| `scrollableY` | boolean | — |  |
+| `scrollHeight` | number | — |  |
+| `scrollLeft` | number | — | Current scroll offset, matching `scrollLeft` / `scrollTop`. |
+| `scrollTop` | number | — |  |
+| `scrollWidth` | number | — | Full scrollable-content dimensions, matching `scrollWidth` / `scrollHeight`. |
+| `width` | number | — | Border-box width and height in CSS pixels. |
+
+### BoxContext
+
+| 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. |
+| `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. |
+| `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. |
+| `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. |
+| `reducedMotion` | boolean | — | Whether the reader asks for reduced motion. |
+| `systemAppearance` | BoxMode | — | Browser / operating-system color preference, independent of Anta classes. |
+
+### BoxFont
+
+`context.font`, the resolved text style.
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | string | — | Resolved text color. Canvas: `ctx.fillStyle`. |
+| `direction` | string | — | Canvas: `ctx.direction`. |
+| `family` | string | — | Resolved family list, quoted as the engine reports it. |
+| `featureSettings` | string | — | Canvas 2D consumes neither of these. They are here for text you measure or draw some other way. |
+| `kerning` | string | — | Canvas: `ctx.fontKerning`. |
+| `letterSpacing` | string | — | A length, never `normal` - `normal` is reported as `0px`, which is what `ctx.letterSpacing` accepts. |
+| `lineHeight` | number \| null | — | Line height in CSS pixels, or `null` when it computes to `normal`. Canvas ignores line height in `ctx.font`; this is for laying text out yourself. |
+| `shorthand` | string | — | CSS `font` shorthand, assembled here because every engine returns an empty string for the computed shorthand. `stretch` and `variantCaps` are left out of it deliberately: a percentage `font-stretch` makes every engine reject the whole string and fall back to `10px sans-serif`. Apply those through `ctx.fontStretch` / `ctx.fontVariantCaps` after setting `ctx.font`. |
+| `size` | number | — | Font size in CSS pixels. |
+| `stretch` | string | — | Computed `font-stretch`, a percentage such as `88%`. Canvas: `ctx.fontStretch`. |
+| `style` | string | — | `normal`, `italic`, or an `oblique <angle>`. |
+| `textRendering` | string | — | Canvas: `ctx.textRendering`, which WebKit does not implement. |
+| `variantCaps` | string | — | Canvas: `ctx.fontVariantCaps`. |
+| `variationSettings` | string | — |  |
+| `weight` | number | — | Numeric weight, 1-1000. |
+| `wordSpacing` | string | — | Same normalization as `letterSpacing`. Canvas: `ctx.wordSpacing`. |
+
+### BoxInset
+
+`context.inset`, the distance from the border edge to the content edge.
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| `borderBottom` | number | — |  |
+| `borderLeft` | number | — |  |
+| `borderRight` | number | — |  |
+| `borderTop` | number | — |  |
+| `paddingBottom` | number | — |  |
+| `paddingLeft` | number | — |  |
+| `paddingRight` | number | — |  |
+| `paddingTop` | number | — |  |
+
+## 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"`.
+
+```html title="a-box"
+<a-box display="grid" gap="8px" round="12px" observe="all"
+       style="--box-gap: 8px; --box-round: 12px; padding: 12px; border: 1px solid var(--border-4)">
+  <span>Summary content</span>
+  <span>Observation enabled</span>
+</a-box>
+```
+
+Import `@antadesign/anta/elements/a-box` to register the element. Listen for
+`measurechange` and `contextchange` with `addEventListener`.
+`box.measurement`, `box.context`, and `box.isTruncated` read values synchronously.
+
+## Styling
+
+Your `className` and `style` override `display`, `gap`, 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:
+
+```html
+<a-box display="flex" gap round fade class="raw-box"
+       style="--box-gap: 8px; --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 span { flex: 0 0 auto; }
+```

package/docs/components/breadcrumbs.md

@@ -111,16 +111,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 +126,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,6 +160,8 @@ 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

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