@antadesign/anta 0.3.22 → 0.3.24

package/docs/components/breadcrumbs.md

@@ -0,0 +1,177 @@
+# Breadcrumbs
+
+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.
+
+## 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.
+
+```tsx
+<Breadcrumbs
+  aria-label="Project location"
+  items={[
+    { label: 'Home', href: '/', icon: 'home' },
+    { label: 'Projects', href: '/projects', icon: 'folder-open', tone: 'brand' },
+    { label: 'Refresh', icon: 'refresh', onClick: reload },
+  ]}
+/>
+```
+
+An item with `current` receives `aria-current="page"`. The current item may
+remain a link when revisiting the page is useful, or it can be an action such as
+copying the current path.
+
+## Priority, size, underline, and padding
+
+Breadcrumbs use either `tertiary` or `quaternary` Button priority. `size` drives
+every visible crumb and the More control: small is 24px, medium is 28px, and
+large is 32px. `underline` and `underlineOnHover` forward to each visible Button.
+With `priority="quaternary"` (the default), `paddingless` removes their horizontal
+padding without changing their height, and uses a `0.75ch` gap around separators.
+
+```tsx
+<Breadcrumbs priority="tertiary" size="small" items={items} />
+<Breadcrumbs priority="quaternary" underline="solid" underlineOnHover items={items} />
+<Breadcrumbs paddingless items={items} />
+<Breadcrumbs priority="tertiary" size="large" items={items} />
+```
+
+The default is medium quaternary. `tertiary` adds a hover fill. `quaternary`
+keeps the trail text-only, which suits dense page headers. An underline is
+permanent unless `underlineOnHover` is set. `paddingless` is only available with
+quaternary priority.
+
+## Separators
+
+Pass any of `→`, `/`, `•`, or `▸` for a text separator. Pass an
+Anta icon shape for an icon separator. Separators are decorative and hidden from
+assistive technology.
+
+```tsx
+<Breadcrumbs separator="→" items={items} />
+<Breadcrumbs separator="/" items={items} />
+<Breadcrumbs separator="•" items={items} />
+<Breadcrumbs separator="▸" items={items} />
+<Breadcrumbs separator="chevron-right" items={items} />
+```
+
+`chevron-right` is the default. The icon form accepts any registered `IconShape`,
+including icons added by an application through Anta's icon generator. Icon
+separators use no flex gap; text separators keep the configured gap.
+
+## Folding into More
+
+`maxItems` limits the number of original breadcrumb entries that remain visible;
+the More control does not count. When folding, `itemsBeforeCollapse` controls
+where More appears. Its default is `0`, so More comes first and the most recent
+items remain visible. The final original item is always kept visible.
+
+```tsx
+// More / Projects / Anta / Button.tsx
+<Breadcrumbs maxItems={3} items={items} />
+
+// Home / Workspace / More / src / Button.tsx
+<Breadcrumbs maxItems={4} itemsBeforeCollapse={2} items={items} />
+```
+
+The More trigger is an icon-only Button followed by an Anta `Menu`; it supports
+pointer, keyboard, and outside-dismiss interaction through the existing menu
+primitive. Folded links retain their native link behavior, while folded actions
+become menu selections.
+
+## Copying the current item
+
+An item with `copy`, `copyNode`, or `copyUrl` uses `ButtonCopy` while visible and
+`MenuItemCopy` if it is folded. Copy entries cannot combine with `href`. Mark a
+copying final item `current` when it represents the current page.
+
+```tsx
+<Breadcrumbs
+  items={[
+    { label: 'Home', href: '/' },
+    {
+      label: 'Button.tsx',
+      current: true,
+      copy: 'src/components/Button.tsx',
+      iconPlacement: 'trailing',
+      copiedLabel: 'Path copied',
+    },
+  ]}
+/>
+```
+
+Use `copyUrl` to copy `location.href`, `copyNode` to copy a marked rendered
+region, or `copy` for a known string. `onCopyRequest` refreshes a reactive string
+before copying, and `onCopied` receives the result.
+
+### 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. |
+| `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. |
+| `separator?` | BreadcrumbSeparator | 'chevron-right' | Separator between visible entries. |
+| `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Button size applied to every visible item and the More control. |
+| `underline?` | 'solid' \| 'dashed' \| 'dotted' | — | Underline style applied to every visible breadcrumb control. |
+| `underlineOnHover?` | boolean | — | Hide the underline at rest and reveal it on hover. |
+
+`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
+structure yourself. Keep an overflow Menu immediately after its More Button.
+
+```ts
+import '@antadesign/anta/components/Breadcrumbs.css'
+import '@antadesign/anta/elements'
+```
+
+```html
+<a-breadcrumbs role="navigation" aria-label="Project location" data-paddingless>
+  <a href="/" data-anta role="button" priority="quaternary" paddingless>
+    <a-button-label>Home</a-button-label>
+  </a>
+  <a-breadcrumb-separator aria-hidden="true">•</a-breadcrumb-separator>
+
+  <a-button role="button" tabindex="0" priority="quaternary" paddingless
+    aria-label="Show more breadcrumbs" aria-haspopup="menu">
+    <a-icon shape="more" aria-hidden="true"></a-icon>
+  </a-button>
+  <a-menu autowidth>
+    <a href="/workspace" data-anta-menu-item role="menuitem"><a-menu-item-label>Workspace</a-menu-item-label></a>
+    <a href="/workspace/projects" data-anta-menu-item role="menuitem"><a-menu-item-label>Projects</a-menu-item-label></a>
+  </a-menu>
+
+  <a-breadcrumb-separator aria-hidden="true">•</a-breadcrumb-separator>
+  <a href="/workspace/projects/anta" data-anta role="button" priority="quaternary"
+    paddingless aria-current="page"><a-button-label>Anta</a-button-label></a>
+</a-breadcrumbs>
+```
+
+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.
+
+```tsx
+<Breadcrumbs className="project-breadcrumbs" separator="chevron-right" items={items} />
+```
+
+```css
+.project-breadcrumbs a-breadcrumb-separator {
+  color: var(--text-2);
+}
+```

package/docs/components/button.md

@@ -5,7 +5,7 @@ component (or `<a role="button">` when `href` is set). Tone, priority,
 size, and state are all plain attributes, so the styling is identical
 whether you use the wrapper or author the element by hand.
 
-## Priorities
+## Priority
 
 A button's priority helps control how much attention it draws:
 
@@ -21,7 +21,7 @@ A button's priority helps control how much attention it draws:
 - `tertiary` — Background-less at rest, fills on hover.
 - `quaternary` — Text only, no background.
 
-## Tones
+## Tone
 
 Six named tones — `neutral` (default), `brand`, `critical`, `info`,
 `success`, `warning`. Omitting `tone` — or passing an empty string —
@@ -66,7 +66,7 @@ too, so there's no state change; to keep distinct states, set the per-state
 variables instead — `--button-bg-{priority}-hover`,
 `--button-bg-{priority}-active`, and the `--button-fg-*` equivalents.
 
-## Sizes
+## Size
 
 ```tsx
 <Button tone="brand" size="small"  label="Small" />
@@ -190,11 +190,13 @@ dropped (a valid `0` still renders).
 <Button tone="brand" priority="tertiary" underline="solid"  label="Solid" />
 <Button tone="brand" priority="tertiary" underline="dashed" label="Dashed" />
 <Button tone="brand" priority="tertiary" underline="dotted" label="Dotted" />
+<Button tone="brand" priority="quaternary" underline="solid" underlineOnHover label="Hover only" />
 ```
 
 When the button has a [link mode](#link-mode), or you simply want an
 underline stylistically, it supports three styles — `solid`, `dashed`,
-`dotted` (only valid on `priority="tertiary"` / `"quaternary"`).
+`dotted` (only valid on `priority="tertiary"` / `"quaternary"`). Set
+`underlineOnHover` to keep that underline hidden until pointer hover.
 
 ## States
 
@@ -369,6 +371,7 @@ because the write happens on the click.
  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. |
 
 ## Link mode
 

package/docs/components/card.md

@@ -62,7 +62,7 @@ when toned (stepping to `border-3` on hover).
 <Card priority="tertiary" header="Tertiary">…</Card>
 ```
 
-## Tones
+## Tone
 
 A semantic `tone` tints the surface, border, and text. The set matches the rest of
 Anta: `neutral` (the default) plus `brand`, `info`, `success`, `warning`, and

package/docs/components/dialog.md

@@ -193,13 +193,13 @@ destructive button, and it works the same with or without a close button or
 focusable content. A screen reader announces the dialog by its `header` text
 (mirrored to the dialog's accessible name), and the ✕ is the last tab stop.
 
-To focus a specific control on open instead (a search field, say), put
-`autofocus` on it; the dialog honors that and skips the default. On close, focus
-returns to whatever opened the dialog, from the native `<dialog>`.
+To focus a specific control on open instead (a search field, say), pass
+`autoFocus`; the dialog focuses it before returning from the opening interaction.
+On close, focus returns to whatever opened the dialog, from the native `<dialog>`.
 
 ```tsx
 <Dialog header="Rename" footer={…}>
-  <Input label="Name" autofocus />   {/* focus the field on open */}
+  <Input label="Name" autoFocus />
 </Dialog>
 ```
 

package/docs/components/expander.md

@@ -36,7 +36,7 @@ to see the corners hold their radius as the body appears.
 <Expander round title="Details" priority="primary">…</Expander>
 ```
 
-## Tones
+## Tone
 
 Pick a semantic `tone` to tint the header text and — on the filled
 priorities (`secondary` / `primary`) — the surface too. The set matches

package/docs/components/input-time.md

@@ -68,6 +68,7 @@ range is clamped to the nearest bound as you step or leave the field, and flags
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `autoFocus?` | boolean | — | Focus this field when its containing `Dialog` opens. |
 | `children?` | ReactNode | — | Extra content rendered under the field, above the hint (a no-box child like
  a `<Tooltip>` takes no space and anchors to the field). |
 | `clearable?` | boolean | — | Show a clear button once the field has a value. |

package/docs/components/input.md

@@ -6,7 +6,7 @@ self-contained (you never pass a control in) yet fully native underneath:
 focus, IME, autofill, and form submission all work, and the control is reachable
 for styling through `::part(input)`.
 
-## Sizes
+## Size
 
 ```tsx
 <Input size="small"  label="Small"  placeholder="24px tall" />
@@ -431,6 +431,7 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 | `autoComplete?` | 'off' \| 'on' \| 'name' \| 'username' \| 'email' \| 'current-password' \| 'new-password' \| 'one-time-code' \| 'tel' \| 'url' \| (string & {}) | — | Native autocomplete token. Overrides the value derived from `type`
  (`email` / `tel` / `url`) — set it for the cases `type` can't express, e.g.
  `username`, `current-password`, `new-password`, `one-time-code`, or `off`. |
+| `autoFocus?` | boolean | — | Focus this field when its containing `Dialog` opens. |
 | `children?` | ReactNode | — | Extra content rendered directly under the field, above the hint/error (it
  pushes the message down). A no-box child like an Anta `<Tooltip>` takes no
  space and anchors to the field — consistent with how tooltips attach

package/docs/components/loader.md

@@ -61,6 +61,7 @@ decorative so nearby status text remains the single announcement. |
 | `max?` | number | 100 | Upper bound of the range. |
 | `size?` | number | 16 | Width and height in pixels. |
 | `speed?` | number | 0.75 | Seconds per rotation. Pass a positive number. |
+| `tone?` | LoaderTone | — | Color tone for the loader. Omit it to use the standard text-3 color. |
 | `value?` | number \| false | — | Current progress value. Omit this prop, or pass `false`, for an
 indeterminate rotating gradient. |
 

package/docs/components/menu.md

@@ -39,7 +39,7 @@ const onSelect = (e, { value }) => act(value)
 </Menu>
 ```
 
-## Tones
+## Tone
 
 `tone` colors an item's label, icon, and hover/selected tint (and its
 `selectionIndicator`) with a semantic palette — `brand`, `info`, `success`,
@@ -370,7 +370,8 @@ chevron stay centered on the row, so it composes with a trailing counter.
 literal string, `copyNode` for a DOM region. It composes a `<MenuItem>` with a
 slotted `<a-copy>` element that performs the write, and keeps the menu open on
 select so the check / retone feedback shows. `onCopied(ok)` fires after each
-attempt.
+attempt. `iconPlacement="trailing"` moves the feedback glyph to the end of the
+row; `"none"` shows a cursor-near confirmation instead.
 
 Copy sits alongside normal items, so a "Share" menu can mix a copy-link row with
 navigating links.
@@ -391,6 +392,7 @@ navigating links.
 |------|------|---------|-------------|
 | `children?` | ReactNode | — | Item content. With `label` set, children are extra content — most
  notably the nested `<Menu>` for a submenu parent. |
+| `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
@@ -404,6 +406,9 @@ navigating links.
  option `hint`. Requires `label` (it stacks in a column beneath it). Muted
  (`--text-3`) and tracks the row's `tone`. A string, or any node. |
 | `icon?` | IconShape | — | Leading icon shape. |
+| `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 confirmation label near the
+ pointer and leaves the row unchanged. |
 | `iconTrailing?` | IconShape | — | A trailing icon. On a `submenu` item this **overrides** the default
  chevron (omit it to keep the chevron); on a normal item it's the trailing
  glyph (omit for none). |

package/docs/components/radio.md

@@ -31,7 +31,7 @@ Each option can also set `className`, `style`, and `data-*`.
 `RadioGroup` forwards them to that option's `<a-radio>` so you can add
 per-option presentation and application metadata.
 
-## Tones
+## Tone
 
 ```tsx
 {/* Usually one tone for the whole group: */}

package/docs/components/slider.md

@@ -80,7 +80,7 @@ for a shared custom radius. |
 | `step?` | number | 1 | Smallest keyboard and drag increment. |
 | `thumbFill?` | boolean | false | Fill the thumb with its resolved border color. This follows `thumbTone`
 and interactive states. |
-| `thumbSize?` | number \| string | 18 | Diameter of the thumb. Numbers use pixels; strings are CSS lengths. Keep
+| `thumbSize?` | number \| string | 16 | Diameter of the thumb. Numbers use pixels; strings are CSS lengths. Keep
 it at least as large as `trackSize`. |
 | `thumbTone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the thumb stroke. Pass a named tone or a literal CSS color for a
 one-off custom tone. Omit it to keep the thumb neutral. |