@antadesign/anta 0.3.11 → 0.3.13

package/README.md

@@ -1,16 +1,16 @@
 # @antadesign/anta
 
-<a href="https://antithesis.com" target="_blank" rel="noopener noreferrer">Antithesis</a> design system, **Anta**, has three layers: global CSS tokens, framework-agnostic web components that work with plain HTML, and JSX wrappers for React and Preact.
+<a href="https://antithesis.com" target="_blank" rel="noopener noreferrer">Antithesis</a> design system, **Anta**, has three layers: global CSS tokens with swappable themes, framework-agnostic web components that work in plain HTML, and JSX wrappers for React and Preact.
 
-The Antithesis SaaS has an unusual architecture: most of its UI code runs inside a Worker thread, driven by a custom reactive engine that powers Antithesis notebooks. To keep state in sync between the Worker and the UI thread, Anta's web components must be **fully declarative** — they never mutate their own attributes (any internal state changes happen inside Shadow DOM, invisible to the outer document). A self-mutating attribute would break the Worker↔UI sync.
-
-This constraint shapes the architecture: the web components carry the core styling and the occasional browser-API call (e.g. `getBoundingClientRect()`) without imposing a framework. Majority of web components are stateless. The React/Preact wrappers exist for dynamic state and conditional rendering.
+One constraint shapes the architecture. Antithesis runs most of its UI in a Worker thread, driven by a custom reactive engine, and a component that mutates its own attributes would desync the Worker from the UI thread. So Anta's web components are **fully declarative**: they never touch their own attributes, and internal state lives in Shadow DOM, invisible to the outer document. The components carry the styling without imposing a framework, and most are stateless; the JSX wrappers exist for dynamic state and conditional rendering.
 
 ## Installation
 
-`@antadesign/anta` is an NPM package, so you can `npm install @antadesign/anta` or do that with `pnpm` / `bun`.
+```sh
+npm install @antadesign/anta   # or pnpm / bun
+```
 
-Use the latest version from npm, but **always pin an exact version** — `"@antadesign/anta": "0.2.0"` in your `package.json` — rather than a floating tag like `"latest"` or `"dev"`, which can change between installs.
+Pin an exact version in your `package.json` (`"@antadesign/anta": "0.3.12"`) rather than a floating tag like `"latest"`, which can change between installs.
 
 ### Usage
 
@@ -25,24 +25,23 @@ import { Progress } from '@antadesign/anta'
 
 ### What you import (and why)
 
-Anta exposes four independent imports. Tokens + elements + the JSX layer are the minimum to render a styled component; the reset is recommended but skippable.
+Five imports, listed in the order you'd add them. Tokens + elements + the JSX layer render a styled component; the reset is recommended; the theme is opt-in.
 
 | Import | Provides | Skip if… |
 |---|---|---|
-| `@antadesign/anta/tokens.css` | The CSS custom properties — `--bg-1…5`, `--text-1…5`, `--border-1…5`, the `.dark`-ancestor toggling, the base `font-size: 15px`. Also declares the `@layer base, anta, components, utilities;` cascade order. | You're applying your own design tokens at the same variable names. |
-| `@antadesign/anta/reset.css` | Modern small reset (box-sizing, margin reset, replaced-element block, form-control font inheritance, text-wrap defaults) plus Anta's typography opinions for `h1-h6`, `strong`, `ul / ol / menu`, `a` / link states. Lives in `@layer anta`. | You already have a reset and don't want Anta's typography defaults. |
-| `@antadesign/anta/elements` | Side-effect import that registers `<a-progress>`, `<a-text>`, `<a-icon>` as custom elements *and* attaches their per-element CSS (also in `@layer anta`). | You're rendering Anta only on the server (no DOM) and never hydrating. |
-| `@antadesign/anta` | The JSX wrappers (`Progress`, `Text`, `Icon`) — typed React/Preact components that emit `<a-*>` tags. | You're writing the `<a-*>` elements by hand and don't need a JSX layer. |
+| `@antadesign/anta/tokens.css` | The CSS custom properties: six tone seeds (`--anta-seed-neutral`, `--anta-seed-brand`, …), the role scales derived from them (`--bg-1…5`, `--text-1…5`, `--border-1…5`), the `.dark` ancestor toggle, and the base `font-size: 15px`. Also declares the `@layer base, anta, components, utilities` order. Override a seed to reskin its whole tone. | You're supplying your own values for the same variables. |
+| `@antadesign/anta/reset.css` | Small modern reset (box-sizing, margins, form-control font inheritance) plus Anta's typography for headings, lists, and links. Lives in `@layer anta`. | You already have a reset and don't want Anta's typography defaults. |
+| `@antadesign/anta/elements` | Side-effect import: registers every `<a-*>` element and attaches its CSS (also `@layer anta`). Per-element entries register just one — see [Registering elements](#registering-elements). | You render only on the server, or you import per-element entries instead. |
+| `@antadesign/anta` | The JSX wrappers (`Progress`, `Text`, `Icon`, …): typed React/Preact components that emit `<a-*>` tags. | You write the `<a-*>` elements by hand. |
+| `@antadesign/anta/theme-anta.css` *(optional)* | Anta's hand-tuned reference palette. The default palette is seed-derived; import this last for the exact hand-tuned values. | The seed-derived default, or your own palette, is what you want. |
 
-The chain matters: the per-element CSS that ships with `/elements` references variables like `var(--text-1)` and `var(--bg-2)`. Those variables are *only defined* by `tokens.css`. Skip the tokens import and the components render with whatever the surrounding cascade provides — usually nothing styled at all.
-
-`@antadesign/anta/elements` registers **all** elements — convenient, but it includes every element's code (and deps). To keep your bundle lean, import only the elements you use from their per-element entry points instead: `import '@antadesign/anta/elements/a-tooltip'` registers just `<a-tooltip>` **and loads just its CSS**. Unused elements — and any dependencies they pull in — then never enter your bundle. See [Registering elements](#registering-elements).
+The order matters at the top: the element CSS reads `var(--text-1)`, `var(--bg-2)`, and friends, and only `tokens.css` defines them. Skip the tokens import and components render unstyled.
 
 ### Cascade layers
 
-Anta's reset and element CSS live in `@layer anta`. `tokens.css` pre-declares an order of `@layer base, anta, components, utilities;`, which keeps Anta's defaults above any preflight resets (Tailwind's `@layer base`, Normalize, etc.) while letting your own `@layer components` rules and utility-class frameworks like Tailwind (`@layer utilities`) override Anta when you ask them to.
+Anta's reset and element CSS live in `@layer anta`. `tokens.css` pre-declares `@layer base, anta, components, utilities;`: Anta's defaults sit above preflight resets (Tailwind's `@layer base`, Normalize) and below your `@layer components` rules and utility frameworks.
 
-If you need a different order, declare it in your *own* CSS file that loads **before** `tokens.css`. The first mention of each layer name fixes its position:
+For a different order, declare it in your own CSS loaded **before** `tokens.css` — the first mention of each layer name fixes its position:
 
 ```css
 /* your global.css, loaded before anta */
@@ -51,37 +50,33 @@ If you need a different order, declare it in your *own* CSS file that loads **be
 
 CSS custom properties (the `:root { --… }` declarations in `tokens.css`) stay unlayered so they take effect everywhere unconditionally.
 
-> **Gotcha: unlayered hard resets defeat Anta's element rules.**
->
-> A snippet like this in your global CSS — common copy-paste from older reset guides — silently overrides every element rule Anta ships:
+> **Gotcha: an unlayered hard reset defeats Anta's element rules.**
 >
 > ```css
 > *, *::before, *::after { box-sizing: border-box; }
 > * { margin: 0; }
 > ```
 >
-> Unlayered styles **always** beat layered ones in the cascade, regardless of specificity. So `* { margin: 0 }` outranks Anta's `caption { margin-bottom: 0.25em }`, `p { margin: 0 0 1em }`, `ul / ol` padding, and any other per-element default Anta provides — even though those use stronger selectors.
->
-> If you're importing `@antadesign/anta/reset.css`, Anta already does the same universal `box-sizing` and margin reset, *inside* `@layer anta`. The element-level rules sitting on top are intentionally polite defaults — sensible out of the box, trivially overridable when you want something else (any rule in `@layer components` / `@layer utilities`, or any unlayered rule of your own that targets specific elements, wins automatically). **Delete the duplicate hard reset from your global CSS** so those defaults can apply. If you want to keep your own reset, wrap it in `@layer base { … }` so it sits below `anta` in the declared order and Anta's rules still win element-by-element.
+> Unlayered styles beat layered ones regardless of specificity, so this common copy-paste outranks every per-element default Anta ships (`p` margins, list padding, and the rest). `reset.css` already does the same universal reset inside `@layer anta` — delete the duplicate from your global CSS, or wrap your own reset in `@layer base { … }` so Anta's element rules still win.
 
 ## Registering elements
 
-The JSX wrappers (React components) as `Progress` render custom DOM elements as `<a-progress>`. The custom elements themselves must be registered with the browser **before** they appear in the DOM, and registration only works where `HTMLElement` exists — i.e. the UI thread of a real browser. **Node.js (SSR) and Worker threads don't have `HTMLElement`**, so the import is harmless in those environments: it does nothing — registration is skipped silently and the class uses a stand-in base instead of crashing — though it might extend your worker's bundle size a bit.
+The JSX wrappers render `<a-*>` tags, and the classes behind those tags must be registered **before** they appear in the DOM. Registration needs `HTMLElement`, which exists only in the UI thread of a real browser; in Node.js (SSR) and Worker threads the import is a silent no-op that costs nothing but bundle size.
 
 ```ts
 import '@antadesign/anta/elements'  // auto-registers all elements
 ```
 
-**Register only what you use.** `/elements` is the all-in-one convenience import. To trim your bundle, import the specific element entry points instead — each registers just that element and loads just its CSS:
+**Register only what you use.** `/elements` registers everything; per-element entry points register one element and load just its CSS, keeping unused elements (and their dependencies) out of your bundle:
 
 ```ts
 import '@antadesign/anta/elements/a-tooltip'  // only <a-tooltip> + its CSS
 import '@antadesign/anta/elements/a-button'   // only <a-button> + its CSS
 ```
 
-Both styles are side-effect imports (the act of importing registers the element), and both are idempotent and SSR-safe. The granular form keeps unused elements — and any dependencies they pull in — out of your bundle.
+Both forms are side-effect imports, idempotent, and SSR-safe.
 
-The cleanest pattern is a **static, synchronous import at your app's entry file** — outside any component, outside any hook:
+The cleanest pattern is a static import at your app's entry file, outside any component or hook:
 
 ```ts
 // src/main.tsx (or wherever your root render lives)
@@ -91,19 +86,18 @@ import App from './App'
 createRoot(document.getElementById('root')!).render(<App />)
 ```
 
-Bundlers resolve this at module-init time, so by the time any component renders an `<a-progress>`, the custom element class is already registered — there's no flash of un-upgraded elements.
+Bundlers resolve this at module-init time, so the element classes are registered before anything renders: no flash of un-upgraded elements.
 
 > **Why not `useEffect(() => import('@antadesign/anta/elements'), [])`?**
->
-> `useEffect` fires after paint, and the dynamic `import()` itself is asynchronous. In practice the browser paints unregistered custom elements (which collapse to nothing) for a few hundred milliseconds before the upgrade catches up. `useLayoutEffect` doesn't help either: the async import still resolves after paint, and `useLayoutEffect` warns during SSR hydration. A static import at the entry file avoids all of this.
+> `useEffect` fires after paint and the dynamic import resolves later still, so the browser paints unregistered elements (which collapse to nothing) until the upgrade catches up. `useLayoutEffect` doesn't help: the import is still async, and it warns during SSR hydration.
 
-Where to put the static import depends on the runtime:
+Where the static import goes depends on the runtime:
 
-**Plain HTML / static sites** — put it in a `<script type="module">` tag in the document head. That's client-side by default.
+**Plain HTML / static sites** — a `<script type="module">` tag in the document head.
 
-**SSR frameworks (Astro, Next.js)** — register from a script that the framework only ships to the client. In Astro: `<script>import '@antadesign/anta/elements'</script>` (Astro `<script>` tags are client-side by default). In Next.js: a top-level `import` in a Client Component file (the one with `'use client'` at the top) — that file is only bundled into the client chunk, so the import never reaches Node.
+**SSR frameworks (Astro, Next.js)** — a script the framework ships only to the client. In Astro: `<script>import '@antadesign/anta/elements'</script>` (Astro `<script>` tags are client-side by default). In Next.js: a top-level import in a `'use client'` file, which only enters the client chunk.
 
-**React / Preact apps where the UI runs in a Worker thread (the Antithesis setup)** — register the elements in your UI-thread bootstrap code, the script that owns the real DOM. The Worker won't have `HTMLElement`, so the import must not run there.
+**UI in a Worker thread (the Antithesis setup)** — the UI-thread bootstrap, the script that owns the real DOM. The Worker has no `HTMLElement`, so the import must not run there.
 
 ## Framework setup
 
@@ -137,7 +131,7 @@ If you only use the JSX wrappers (`<Button>`, `<Progress>`, …) you need no set
 
 Every `a-*` tag type-checks, all standard HTML tags keep working, and importing anything from `@antadesign/stickers` adds the sticker tags automatically.
 
-**Option B** — if you can't change `jsxImportSource` (a shared tsconfig, Emotion's `@emotion/react` source, an older `@types/react` without the `React.JSX` namespace), merge anta's tag map into your JSX namespace yourself. Anta exports it as a standalone interface, `AntaIntrinsicElements` — and `@antadesign/stickers` exports the matching `StickerIntrinsicElements` — so it's a single `extends` in any `.d.ts` covered by your tsconfig:
+**Option B** — if you can't change `jsxImportSource` (a shared tsconfig, Emotion's `@emotion/react` source), merge anta's tag map into your JSX namespace yourself: anta exports it as `AntaIntrinsicElements` (and `@antadesign/stickers` as `StickerIntrinsicElements`), one `extends` in any `.d.ts` your tsconfig covers:
 
 ```ts
 import type { AntaIntrinsicElements } from '@antadesign/anta'
@@ -166,8 +160,9 @@ Either way the tags stay fully typed — unknown `a-*` tags and wrong prop types
 
 ### Raw web components (no JSX)
 
+The elements work in plain HTML; registering them also loads their CSS. The bare specifier needs a bundler or an import map to resolve.
+
 ```html
-<link rel="stylesheet" href="@antadesign/anta/elements/a-progress.css">
 <script type="module">
   import '@antadesign/anta/elements'
 </script>
@@ -187,7 +182,7 @@ Add the `dark` class to any ancestor element:
 
 ## Fonts
 
-Anta is designed with a customized version of <a href="https://typetype.org/fonts/tt-interphases-pro" target="_blank" rel="noopener noreferrer">TT Interphases Pro</a> in mind, but it doesn't ship any font binaries. Components reference families through the `--sans-serif` and `--monospace` CSS variables and fall back to native system stacks when no font is registered. The base size is `font-size: 15px` on `:root` (so `1rem = 15px`), intentionally diverging from the browser default of 16px to match Antithesis's information-dense layouts — both the variables and the base size live in `tokens.css`.
+Anta is designed for a customized <a href="https://typetype.org/fonts/tt-interphases-pro" target="_blank" rel="noopener noreferrer">TT Interphases Pro</a> but ships no font binaries. Components reference families through the `--sans-serif` and `--monospace` variables and fall back to system stacks. The base size is `font-size: 15px` on `:root` (so `1rem = 15px`), a deliberate step down from the browser's 16px for Antithesis's information-dense layouts. Both live in `tokens.css`.
 
 To use the Antithesis fonts, register your own `@font-face` declarations and override the variables:
 

package/dist/anta_helpers.js

@@ -86,6 +86,11 @@ class SelectableChildElement extends HTMLElementBase {
   ariaProp = "ariaChecked";
   internals = this.attachInternals?.();
   connectedCallback() {
+    if (Object.prototype.hasOwnProperty.call(this, "selected")) {
+      const v = this.selected;
+      delete this.selected;
+      this.selected = v;
+    }
     if (this.hasAttribute("selected")) this.applyState(true);
   }
   attributeChangedCallback(name) {

package/dist/components/Button.d.ts

@@ -55,13 +55,24 @@ export type ContentMode = {
     iconTrailing?: IconShape;
 };
 /** Submit axis — anchors (href) don't carry form-submission props; buttons
- *  don't carry anchor props. A link (`href`) also can't be a copy control, so the
- *  copy props live only on the non-link branch (via `CopyMode`) and are `never`
- *  on the link branch — a `<ButtonCopy href=…>` or `<Button href=… copy=…>` is a
- *  type error, not a silently-ignored attribute. */
+ *  don't carry anchor props. (Copy is no longer a Button concern — `ButtonCopy`
+ *  composes a `<a-copy>` child; see `copy-props.ts`.)
+ *
+ *  `href` is **optional** so a conditional URL just works: `href={maybeUrl}`
+ *  (`string | undefined`) type-checks, and a falsy href degrades to a plain
+ *  button — a definite string renders `<a role="button">`, an absent / `undefined`
+ *  href renders `<a-button>`, mirroring the `href != null` runtime check. Keeping
+ *  it required forced a two-render (`href ? … : …`) or a conditional spread, and
+ *  made TypeScript blame the wrong prop: with `href: string | undefined` matching
+ *  neither branch, the intersection fell through to `PriorityMode` and reported a
+ *  spurious "`priority` is missing". The anchor props (`href` / `target` / `rel` /
+ *  `download` / `ping`) still can't combine with the button props (`type` /
+ *  `form`). */
 export type SubmitMode = {
-    /** Renders as `<a role="button">` instead of `<a-button>`. */
-    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. */
+    href?: string;
     /** Anchor target. */
     target?: string;
     /** Anchor rel. */
@@ -72,13 +83,7 @@ export type SubmitMode = {
     ping?: string;
     type?: never;
     form?: never;
-    copy?: never;
-    copyNode?: never;
-    copyUrl?: never;
-    copyWithUrl?: never;
-    onCopyRequest?: never;
-    onCopied?: never;
-} | ({
+} | {
     href?: never;
     target?: never;
     rel?: never;
@@ -88,7 +93,7 @@ export type SubmitMode = {
     type?: 'button' | 'submit' | 'reset';
     /** Form id when the button isn't a descendant of its form. */
     form?: string;
-} & CopyMode);
+};
 /** Priority axis — `underline` only on `tertiary` / `quaternary`,
  *  `paddingless` only on `quaternary`. */
 export type PriorityMode = {
@@ -109,55 +114,6 @@ export type PriorityMode = {
     /** Drops outer padding to zero. */
     paddingless?: boolean;
 };
-/** Copy axis — turns the button into a copy control that writes to the clipboard
- *  on click and flashes a success / failure state (see `<a-button>`'s copy
- *  behavior). **Exactly one** of `copy`, `copyNode`, or `copyUrl` may be set;
- *  the union makes the others `never` in each mode. For the batteries-included
- *  preset, use `ButtonCopy`. */
-export type CopyMode = {
-    copy?: never;
-    copyNode?: never;
-    copyUrl?: never;
-    copyWithUrl?: never;
-    onCopied?: never;
-    onCopyRequest?: never;
-} | {
-    /** Text copied to the clipboard on click. */
-    copy: string;
-    /** Prefix the copied text with `// URL: <current page URL>`. */
-    copyWithUrl?: boolean;
-    /** Compute the copy content lazily. Fires on **pointerdown**; update `copy`
-     *  (a state change) here and the click copies the latest value. The
-     *  pointerdown→click gap lets the update land even when this handler runs
-     *  off the UI thread (a worker-rendered app) — only the serializable `copy`
-     *  string crosses, via the normal re-render. */
-    onCopyRequest?: () => void;
-    copyNode?: never;
-    copyUrl?: never;
-    /** Fires after the copy attempt with whether it succeeded. */
-    onCopied?: (ok: boolean) => void;
-} | {
-    /** Copy a DOM node as rich text instead of a string. `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?: never;
-    copyUrl?: never;
-    copyWithUrl?: never;
-    onCopyRequest?: never;
-    /** Fires after the copy attempt with whether it succeeded. */
-    onCopied?: (ok: boolean) => void;
-} | {
-    /** Copy the current page URL (`location.href`). */
-    copyUrl: true;
-    copy?: never;
-    copyNode?: never;
-    copyWithUrl?: never;
-    onCopyRequest?: never;
-    /** Fires after the copy attempt with whether it succeeded. */
-    onCopied?: (ok: boolean) => void;
-};
 export type ButtonProps = BaseButtonProps & PriorityMode & ContentMode & SubmitMode & BaseProps;
 /**
  * Action button.
@@ -179,4 +135,4 @@ export type ButtonProps = BaseButtonProps & PriorityMode & ContentMode & SubmitM
  * <Button href="/docs" target="_blank" label="Read the docs" />
  * ```
  */
-export declare const Button: ({ priority, tone, underline, icon, iconTrailing, paddingless, label, size, loading, disabled, selected, round, href, type, form, copy, copyNode, copyUrl, copyWithUrl, onCopied, onCopyRequest, className, style, children, ...rest }: ButtonProps) => any;
+export declare const Button: ({ priority, tone, underline, icon, iconTrailing, paddingless, label, size, loading, disabled, selected, round, href, target, rel, download, ping, type, form, className, style, children, ...rest }: ButtonProps) => any;

package/dist/components/Button.js

@@ -1,5 +1,5 @@
 import { Fragment, jsx, jsxs } from "@antadesign/anta/jsx-runtime";
-import { toneStyle, roundStyle, roundAttr, wrapLabel, nativeStateChange } from "../anta_helpers";
+import { toneStyle, roundStyle, roundAttr, wrapLabel } from "../anta_helpers";
 const Button = ({
   priority,
   tone,
@@ -14,24 +14,20 @@ const Button = ({
   selected,
   round,
   href,
+  target,
+  rel,
+  download,
+  ping,
   type,
   form,
-  copy,
-  copyNode,
-  copyUrl,
-  copyWithUrl,
-  onCopied,
-  onCopyRequest,
   className,
   style,
   children,
   ...rest
 }) => {
-  const isCopy = copy != null || copyNode != null || copyUrl === true;
   const toneAttr = tone || void 0;
   const computedStyle = roundStyle(round, "--button-round", toneStyle(toneAttr, "--button-tone-source", style));
-  const leadingIcon = icon ?? (isCopy ? "copy" : void 0);
-  const isIconOnly = leadingIcon != null && label == null && children == null && iconTrailing == null;
+  const isIconOnly = icon != null && label == null && children == null && iconTrailing == null;
   const sharedAttrs = {
     // `<a-button>` is a custom element with no implicit ARIA role, so AT would
     // announce it as a generic clickable — and `aria-pressed` below is only
@@ -61,27 +57,15 @@ const Button = ({
     "aria-disabled": disabled || loading ? "true" : void 0,
     "aria-busy": loading ? "true" : void 0,
     "aria-pressed": selected ? "true" : void 0,
-    // Icon-only buttons get an accessible name: "Copy" for a copy control (its
-    // glyph carries no text), else the icon shape. Consumer's own `aria-label`
-    // (via ...rest) wins by spread order.
-    "aria-label": isIconOnly ? isCopy ? "Copy" : icon : void 0,
-    // Copy behavior — the element reads these and performs the write itself.
-    copy: copy != null ? copy : void 0,
-    "copy-node": copyNode === true ? "" : typeof copyNode === "string" ? copyNode : void 0,
-    "copy-url": copyUrl ? "" : void 0,
-    "copy-with-url": copyWithUrl ? "" : void 0,
-    // Marks the control so `copy-node` serialization strips it from the copied
-    // node (a copy button inside the copied region shouldn't paste itself).
-    "data-copy-node-button": copyNode != null && copyNode !== false ? "" : void 0,
-    oncopydone: onCopied ? (e) => onCopied(nativeStateChange(e).detail?.ok ?? false) : void 0,
-    // Fired on pointerdown for a lazy copy — the consumer updates `copy` here
-    // (a state change) and the click copies the latest value. No payload crosses.
-    oncopyrequest: onCopyRequest ? () => onCopyRequest() : void 0,
+    // Icon-only buttons get an accessible name from the icon shape. Consumer's
+    // own `aria-label` (via ...rest) wins by spread order — that's the channel
+    // ButtonCopy uses to name an icon-only copy button "Copy".
+    "aria-label": isIconOnly ? icon : void 0,
     class: className,
     style: computedStyle
   };
   const inner = /* @__PURE__ */ jsxs(Fragment, { children: [
-    leadingIcon && /* @__PURE__ */ jsx("a-icon", { shape: leadingIcon, "aria-hidden": "true" }),
+    icon && /* @__PURE__ */ jsx("a-icon", { shape: icon, "aria-hidden": "true" }),
     label != null && /* @__PURE__ */ jsx("a-button-label", { children: label }),
     wrapLabel(children, "a-button-label"),
     iconTrailing && /* @__PURE__ */ jsx("a-icon", { shape: iconTrailing, "aria-hidden": "true" })
@@ -92,6 +76,10 @@ const Button = ({
       {
         href,
         "data-anta": "",
+        target,
+        rel,
+        download,
+        ping,
         ...sharedAttrs,
         ...rest,
         children: inner

package/dist/components/ButtonCopy.d.ts

@@ -1,38 +1,56 @@
 import { type ButtonProps } from './Button';
-/** `ButtonProps` narrowed so a copy target is required — a copy button must copy
- *  something. Intersecting with the target union drops the "no copy prop" member
- *  of `CopyMode` (its `copy?: never` makes each combination `never`). */
-export type ButtonCopyProps = ButtonProps & ({
-    copy: string;
-} | {
-    copyNode: boolean | string;
-} | {
-    copyUrl: true;
-});
+import { type CopyTarget } from './copy-props';
+/** A copy button is a plain action control, so `ButtonCopy` keeps the `Button`
+ *  axes that fit — tone / size / priority styling, `disabled` / `loading`, a
+ *  leading `icon` + `label` — and pins the ones that don't to `never`: `selected`
+ *  (it isn't a toggle), the whole submit/link axis (`href` / `target` / `rel` /
+ *  `download` / `ping` / `type` / `form` — a copy button neither navigates nor
+ *  submits), and the public `iconTrailing` (the glyph's side is `iconPlacement`'s
+ *  job). Plus a required copy target and the placement knob. (Pinning to `never`
+ *  keeps the intersection expanding fully in the docs props table, which `Omit`
+ *  wouldn't.) */
+export type ButtonCopyProps = ButtonProps & {
+    selected?: never;
+    href?: never;
+    target?: never;
+    rel?: never;
+    download?: never;
+    ping?: never;
+    type?: never;
+    form?: never;
+    iconTrailing?: never;
+} & CopyTarget & {
+    /** Where the copy glyph sits relative to the label — or `'none'` to omit it,
+     *  in which case the feedback is a ghost of the label floating up (`toast`)
+     *  plus a brief success / failure tone flash.
+     *  @defaultValue 'leading' */
+    iconPlacement?: 'leading' | 'trailing' | 'none';
+};
 /**
  * Copy button — a `Button` preset for copy-to-clipboard. Set `copy` for a literal
  * string, `copyNode` to copy a DOM region, or `copyUrl` to copy the current page
  * URL. For content computed on demand, keep `copy` reactive and refresh it in
- * `onCopyRequest` (fired on pointerdown). The `<a-button>` element performs the
- * write and reports the result; this wrapper flips the leading icon to a check
- * (success) or ✕ (failure) and retones to `success` / `critical` for ~2s — a JSX
- * re-render, no element state (see `useCopyFeedback`).
+ * `onCopyRequest` (fired on pointerdown / keydown).
  *
- * With a `label` it's a labeled button; without one it's an icon-only copy button.
- * Everything else is a normal `Button` prop — `tone`, `priority`, `size`, `icon`
- * (the resting glyph), `onCopied`.
+ * It composes a plain `<Button>` with a slotted `<a-copy>` child that performs
+ * the write — the button itself carries no copy behavior. This wrapper flips the
+ * copy glyph to a check (success) or ✕ (failure) and retones to `success` /
+ * `critical` for ~2s (a re-render, no element state — see `useCopyFeedback`).
+ * `iconPlacement` puts that glyph leading (default), trailing, or `'none'`; with
+ * `'none'` the `<a-copy>` floats a ghost of the label upward instead.
+ *
+ * With a `label` it's a labeled button; without one it's an icon-only copy button
+ * (named "Copy" for assistive tech). Everything else is a normal `Button` prop —
+ * `tone`, `priority`, `size`, `icon` (the resting glyph), `onCopied`.
  *
  * @example
  * ```tsx
  * <ButtonCopy copy="npm i @antadesign/anta" label="Copy install" />
- * <ButtonCopy copy="https://anta.design" />          // icon-only
+ * <ButtonCopy copy="https://anta.design" />                     // icon-only
+ * <ButtonCopy copy={code} label="Copy" iconPlacement="trailing" />
+ * <ButtonCopy copy={code} label="Copy snippet" iconPlacement="none" />  // ghost feedback
  * <ButtonCopy copyNode=".snippet" label="Copy block" priority="tertiary" />
- * <ButtonCopy copyUrl label="Copy link" />           // copies location.href
- * <ButtonCopy copy={code} copyWithUrl label="Copy snippet" />  // code + source URL
- *
- * // Lazy: compute on pointerdown, copied on the click that follows.
- * const [report, setReport] = useState('')
- * <ButtonCopy copy={report} onCopyRequest={() => setReport(buildReport())} label="Copy report" />
+ * <ButtonCopy copyUrl label="Copy link" />                      // copies location.href
  * ```
  */
-export declare const ButtonCopy: ({ icon, tone, onCopied, ...rest }: ButtonCopyProps) => any;
+export declare const ButtonCopy: ({ icon, iconPlacement, tone, onCopied, onCopyRequest, copy, copyNode, copyUrl, copyWithUrl, label, children, "aria-label": ariaLabel, ...rest }: ButtonCopyProps) => any;

package/dist/components/ButtonCopy.js

@@ -1,9 +1,51 @@
-import { jsx } from "@antadesign/anta/jsx-runtime";
+import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
 import { Button } from "./Button";
 import { useCopyFeedback } from "../anta_helpers";
-const ButtonCopy = ({ icon, tone, onCopied, ...rest }) => {
-  const { shownIcon, shownTone, handleCopied } = useCopyFeedback(icon, tone, onCopied);
-  return /* @__PURE__ */ jsx(Button, { icon: shownIcon, tone: shownTone, onCopied: handleCopied, ...rest });
+import { copyElementProps, isNodeCopy } from "./copy-props";
+const ButtonCopy = ({
+  icon,
+  iconPlacement = "leading",
+  tone,
+  onCopied,
+  onCopyRequest,
+  copy,
+  copyNode,
+  copyUrl,
+  copyWithUrl,
+  label,
+  children,
+  "aria-label": ariaLabel,
+  ...rest
+}) => {
+  const restingIcon = iconPlacement === "none" ? void 0 : icon ?? "copy";
+  const { shownIcon, shownTone, handleCopied } = useCopyFeedback(restingIcon, tone, onCopied);
+  const iconSlot = iconPlacement === "trailing" ? { iconTrailing: shownIcon } : iconPlacement === "none" ? {} : { icon: shownIcon };
+  const hasText = label != null || children != null;
+  const copyAttrs = copyElementProps({
+    copy,
+    copyNode,
+    copyUrl,
+    copyWithUrl,
+    onCopyRequest,
+    onCopied: handleCopied,
+    // Ghost feedback only makes sense when there's no glyph to swap.
+    toast: iconPlacement === "none"
+  });
+  return /* @__PURE__ */ jsxs(
+    Button,
+    {
+      ...iconSlot,
+      label,
+      tone: shownTone,
+      "aria-label": ariaLabel ?? (hasText ? void 0 : "Copy"),
+      "data-copy-node-button": isNodeCopy({ copyNode }) ? "" : void 0,
+      ...rest,
+      children: [
+        children,
+        /* @__PURE__ */ jsx("a-copy", { ...copyAttrs })
+      ]
+    }
+  );
 };
 export {
   ButtonCopy

package/dist/components/Expander.js

@@ -44,7 +44,7 @@ const Expander = ({
       ...rest,
       children: [
         titleNode,
-        actions != null && /* @__PURE__ */ jsx("span", { slot: "actions", style: { display: "contents" }, children: actions }),
+        actions != null && /* @__PURE__ */ jsx("span", { slot: "actions", children: actions }),
         /* @__PURE__ */ jsx("a-expander-details", { children })
       ]
     }

package/dist/components/InputDate.d.ts

@@ -1,5 +1,6 @@
 import type { BaseProps } from '../general_types';
 import type { IconShape } from '../elements/a-icon.shapes';
+import { type MenuProps } from './Menu';
 /** Snapshot passed as the 2nd argument to `onValueChange` — the new ISO value
  *  (`''` when cleared) plus the field name (mirrors `Input` / `Calendar`). */
 export interface InputDateChangeAttrs {
@@ -43,6 +44,13 @@ export interface InputDateProps extends Omit<BaseProps, 'children'> {
     status?: 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'critical';
     /** Round the field corners — `true` for fully round, or a number / CSS length. */
     round?: boolean | number | string;
+    /** Preferred placement of the calendar menu relative to the field. Same values as
+     *  `Menu`; it auto-flips and clamps when space runs out.
+     *  @defaultValue bottom-start */
+    placement?: MenuProps['placement'];
+    /** Gap in pixels between the field and the calendar menu.
+     *  @defaultValue 4 */
+    offset?: number;
     /** Show a clear button once the field has a value. */
     clearable?: boolean;
     /** Leading icon at the start of the field — the calendar affordance. Pass
@@ -87,4 +95,4 @@ export interface InputDateProps extends Omit<BaseProps, 'children'> {
  * <InputDate label="Starts" time defaultValue="2026-06-15T09:00" onValueChange={(v) => save(v)} />
  * ```
  */
-export declare const InputDate: ({ value, defaultValue, min, max, locale, name, size, disabled, label, hint, placeholder, status, round, clearable, icon, time, hour12, onValueChange, className, style, ...rest }: InputDateProps) => any;
+export declare const InputDate: ({ value, defaultValue, min, max, locale, name, size, disabled, label, hint, placeholder, status, round, placement, offset, clearable, icon, time, hour12, onValueChange, className, style, ...rest }: InputDateProps) => any;

package/dist/components/InputDate.js

@@ -33,6 +33,8 @@ const InputDate = ({
   placeholder,
   status,
   round,
+  placement,
+  offset,
   clearable,
   icon,
   time,
@@ -154,7 +156,8 @@ const InputDate = ({
       Menu,
       {
         open,
-        placement: "bottom-start",
+        placement: placement ?? "bottom-start",
+        offset,
         autoWidth: true,
         className: styles.calendarMenu,
         onStateChange: (_e, { next }) => setOpen(next),

package/dist/components/Menu.d.ts

@@ -1,11 +1,12 @@
 import type { BaseProps } from '../general_types';
 export interface MenuProps extends BaseProps {
-    /** Preferred placement relative to the trigger. The cross-axis suffix
-     *  (`-start` / `-end`) aligns the left / right edges; no suffix (`bottom` /
-     *  `top`) centers the menu on the trigger. The menu auto-flips vertically and
-     *  clamps horizontally when there isn't room.
+    /** Preferred placement relative to the trigger. `bottom` / `top` place the menu
+     *  below / above; `right` / `left` place it beside (like a submenu flyout). The
+     *  cross-axis suffix (`-start` / `-end`) aligns the near / far edges, and no suffix
+     *  centers on the trigger. The menu flips to the opposite side when the preferred
+     *  one lacks room, and clamps to the viewport.
      *  @defaultValue bottom-start */
-    placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' | 'bottom' | 'top';
+    placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' | 'bottom' | 'top' | 'right-start' | 'right-end' | 'left-start' | 'left-end' | 'right' | 'left';
     /** Open on right-click (the `contextmenu` event) of the trigger region
      *  instead of a left click, positioned at the pointer. */
     context?: boolean;