@antadesign/anta 0.3.23 → 0.3.24

package/docs/comparison.md

@@ -8,11 +8,16 @@ Most systems are React-only and use CSS-in-JS, Sass, StyleX, or Tailwind.
 Anta ships web components with plain CSS in one `@layer`, without a style
 runtime. Consumer CSS overrides its defaults normally.
 
+Browser years show the oldest published fixed floor. `~` marks the earliest
+year shared by a browser feature the current system ships, rather than a
+published support promise. Hover a value for the policy and the feature behind
+that estimate.
+
 Fixed-package sizes are measured from the version named on each card. Each npm
 artifact was downloaded, bundled as a full ESM import with esbuild, minified,
-and gzipped. React and React DOM are external. When a library ships base CSS,
-the total adds its separately gzipped CSS bundle. The line below each figure
-states what it counts.
+and gzipped, then rounded up to the nearest 10 KiB. React and React DOM are
+external. When a library ships base CSS, the total adds its separately gzipped
+CSS bundle. The line below each figure states what it counts.
 
 Tree-shaking, peer dependencies, icons, styles, and copied source still make
 the numbers different shapes. Polaris is a dated CDN snapshot, not a

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

@@ -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/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/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

@@ -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/menu.md

@@ -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/index.md

@@ -25,6 +25,7 @@ Anta is designed for a clean DOM. Prefer the props and attributes exposed by eac
 - [Progress](./components/progress.md)
 
 - [Button](./components/button.md)
+- [Breadcrumbs](./components/breadcrumbs.md)
 - [Checkbox](./components/checkbox.md)
 - [Radio](./components/radio.md)
 - [Switch](./components/switch.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antadesign/anta",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",