@antadesign/anta 0.3.10 → 0.3.12

package/dist/elements/copy-behavior.d.ts

@@ -1,9 +1,10 @@
 /**
- * Shared copy-to-clipboard behavior for `<a-button>` and `<a-menu-item>` — the
- * write half of the productized "copy button" / "copying menu item". The element
- * performs the clipboard write itself (rather than a UI-thread callback) and
- * reports the outcome with a `copydone` event; the JSX wrapper listens and
- * orchestrates the visual feedback (icon + tone swap). Nothing here touches the
+ * Copy-to-clipboard behavior for the `<a-copy>` element — the write half of the
+ * productized "copy button" / "copying menu item". `<a-copy>` (slotted inside a
+ * button or menu row) calls these on the host's activation: it performs the
+ * clipboard write itself (rather than a UI-thread callback) and reports the
+ * outcome with a `copydone` event; the JSX wrapper (`ButtonCopy` / `MenuItemCopy`)
+ * listens and orchestrates the visual feedback (icon + tone swap). Nothing here touches the
  * DOM — no light-DOM mutation, no host attributes, no ElementInternals.
  *
  * Events are dispatched non-bubbling (`bubbles: false`): the wrapper binds on the
@@ -11,23 +12,40 @@
  * nested copy row's `copydone` from flipping an ancestor copy row's feedback
  * (the same point-to-point rule Anta's `statechange` follows).
  *
- * Three modes, chosen by attribute:
+ * Modes, chosen by attribute:
  * - `copy="<text>"` — copy the literal string on activation.
+ * - `copy-url` — copy the current page URL (`location.href`); no `copy` needed.
+ * - `copy-with-url` — prefix the copied `copy` string with `// URL: <href>`.
  * - `copy-node` / `copy-node="<selector>"` — copy a DOM node as rich text
  *   (`text/html`) + plain text. Bare `copy-node` copies the nearest ancestor
  *   marked `[data-copy-source]`; a value is a selector resolved with `closest()`
  *   (an ancestor region). The copy control is stripped from the serialized
  *   output (`[data-copy-node-button]`).
- * - `copy-lazy` — the content isn't known until the click. Activation dispatches
- *   `copyrequest` whose `detail.provide(text)` the consumer calls with the value
- *   (synchronously, or after an `await` — the browser's transient-activation
- *   window still covers the write). Nothing lands in the DOM, and there's no
- *   attribute round-trip to reset. Takes precedence over any `copy` value.
+ *
+ * ## Lazy content (off-UI-thread safe)
+ *
+ * When the content isn't known ahead of time, the element emits a `copyrequest`
+ * event on **pointerdown** (`emitCopyRequest`, fired whenever a `copy` attribute
+ * is present). The consumer answers by setting the `copy` attribute to the
+ * freshly-computed value; the **click** then reads that value and writes it. The
+ * pointerdown→click gap absorbs the round-trip, so this works even when the
+ * consumer's handler runs off the UI thread (e.g. a worker-rendered app): only a
+ * serializable string crosses the boundary via the normal reconcile — no
+ * callback, and the write stays inside the click's transient activation. This is
+ * why there is no `provide`-function handoff and no `copy-lazy` marker.
  *
  * Precedence when several are set (the discriminated-union prop types make this
- * unreachable from the wrappers, but hand-authored markup can): node → lazy →
- * literal `copy`.
+ * unreachable from the wrappers, but hand-authored markup can): node → url →
+ * literal `copy` (with the optional URL prefix).
+ */
+/**
+ * Ask a lazy consumer to refresh the copy content, on pointerdown — dispatch a
+ * non-bubbling, payload-free `copyrequest`. The consumer answers by setting the
+ * `copy` attribute to the freshly-computed value before the click reads it (see
+ * the "Lazy content" note above). Fires only for string-copy controls; node/url
+ * modes resolve themselves at click time and need no request. No-op otherwise.
  */
+export declare function emitCopyRequest(el: HTMLElement): void;
 /**
  * Perform a copy on activation (click / Enter / Space / menu select). Returns
  * `true` if the element is a copy control (so the caller knows the copy path

package/dist/elements/copy-behavior.js

@@ -37,32 +37,34 @@ function run(el, work) {
     el.dispatchEvent(new CustomEvent("copydone", { bubbles: false, detail: { ok } }));
   });
 }
+function currentUrl() {
+  return typeof location !== "undefined" ? location.href : "";
+}
+function resolveText(el) {
+  if (el.hasAttribute("copy-url")) return currentUrl();
+  const base = el.getAttribute("copy") ?? "";
+  if (el.hasAttribute("copy-with-url")) return `// URL: ${currentUrl()}
+${base}`;
+  return base;
+}
+function isTextCopy(el) {
+  return el.hasAttribute("copy") || el.hasAttribute("copy-url");
+}
+function emitCopyRequest(el) {
+  if (!el.hasAttribute("copy")) return;
+  el.dispatchEvent(new CustomEvent("copyrequest", { bubbles: false }));
+}
 function runCopy(el) {
   if (el.hasAttribute("copy-node")) {
     const target = resolveNodeTarget(el);
     run(el, target ? writeNode(target) : Promise.resolve(false));
     return true;
   }
-  if (el.hasAttribute("copy-lazy")) {
-    let done = false;
-    el.dispatchEvent(
-      new CustomEvent("copyrequest", {
-        bubbles: false,
-        detail: {
-          provide(text) {
-            if (done) return;
-            done = true;
-            run(el, writeText(String(text ?? "")));
-          }
-        }
-      })
-    );
-    return true;
-  }
-  if (!el.hasAttribute("copy")) return false;
-  run(el, writeText(el.getAttribute("copy") ?? ""));
+  if (!isTextCopy(el)) return false;
+  run(el, writeText(resolveText(el)));
   return true;
 }
 export {
+  emitCopyRequest,
   runCopy
 };

package/dist/elements/index.d.ts

@@ -17,6 +17,7 @@ export { AProgressElement, register_a_progress } from './a-progress';
 export { ATextElement, register_a_text } from './a-text';
 export { AIconElement, register_a_icon } from './a-icon';
 export { AButtonElement, register_a_button } from './a-button';
+export { ACopyElement, register_a_copy } from './a-copy';
 export { ACheckboxElement, register_a_checkbox } from './a-checkbox';
 export { AExpanderElement, register_a_expander } from './a-expander';
 export { ATooltipElement, register_a_tooltip } from './a-tooltip';

package/dist/elements/index.js

@@ -2,6 +2,7 @@ import { AProgressElement, register_a_progress } from "./a-progress";
 import { ATextElement, register_a_text } from "./a-text";
 import { AIconElement, register_a_icon } from "./a-icon";
 import { AButtonElement, register_a_button } from "./a-button";
+import { ACopyElement, register_a_copy } from "./a-copy";
 import { ACheckboxElement, register_a_checkbox } from "./a-checkbox";
 import { AExpanderElement, register_a_expander } from "./a-expander";
 import { ATooltipElement, register_a_tooltip } from "./a-tooltip";
@@ -26,6 +27,7 @@ export {
   ACalendarElement,
   ACardElement,
   ACheckboxElement,
+  ACopyElement,
   ADialogElement,
   AExpanderElement,
   AIconElement,
@@ -47,6 +49,7 @@ export {
   register_a_calendar,
   register_a_card,
   register_a_checkbox,
+  register_a_copy,
   register_a_dialog,
   register_a_expander,
   register_a_icon,

package/dist/elements/key-activation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared "activate on key release" for Enter / Space, used by `<a-button>` and
+ * `<a-menu-item>` (via one delegated keydown/keyup pair per document).
+ *
+ * Activation fires on **keyup**, not keydown. This matches the native `<button>`
+ * (Space already activates on release), makes activation **cancelable** (move
+ * focus between press and release → no fire), and opens a **keydown→keyup gap**.
+ * A slotted `<a-copy>` uses that gap for its own lazy pre-request (it runs its
+ * own keydown listener); this module just synthesizes the click on release.
+ *
+ * keydown: `preventDefault()` (stop Space scrolling the page and a link's own
+ * native Enter→click) and arm the release. keyup: `activate(el)` only if the
+ * same element is still armed.
+ *
+ * Idempotency is the caller's job (each guards with its own per-document flag);
+ * this just wires one keydown/keyup pair.
+ */
+export interface KeyActivation {
+    /** Keys that activate — `['Enter', ' ']` for buttons/menu items. */
+    keys: readonly string[];
+    /** Resolve the activatable element from the event target (e.g. `closest`). */
+    resolve(target: EventTarget | null): HTMLElement | null;
+    /** Blocked (disabled / loading) — swallow the key without activating. */
+    blocked?(el: HTMLElement): boolean;
+    /** Runs on keyup: the actual activation (a synthesized `click()`). */
+    activate(el: HTMLElement): void;
+}
+export declare function installKeyActivation(doc: Document, config: KeyActivation): void;

package/dist/elements/key-activation.js

@@ -0,0 +1,32 @@
+function installKeyActivation(doc, config) {
+  let armed = null;
+  doc.addEventListener(
+    "keydown",
+    (e) => {
+      if (e.repeat || !config.keys.includes(e.key)) return;
+      const el = config.resolve(e.target);
+      if (!el) return;
+      e.preventDefault();
+      armed = config.blocked?.(el) ? null : el;
+    },
+    true
+  );
+  doc.addEventListener(
+    "keyup",
+    (e) => {
+      if (!config.keys.includes(e.key)) return;
+      const el = config.resolve(e.target);
+      if (!el || el !== armed) {
+        armed = null;
+        return;
+      }
+      armed = null;
+      if (config.blocked?.(el)) return;
+      config.activate(el);
+    },
+    true
+  );
+}
+export {
+  installKeyActivation
+};

package/dist/general_types.d.ts

@@ -727,26 +727,6 @@ export interface AMenuItemAttributes extends BaseAttributes {
      *  a `MouseEvent`, carrying the modifier keys (e.g. `altKey`). All-lowercase so
      *  React/Preact bind it to the CustomEvent. */
     onmenuselect?: (e: MouseEvent) => void;
-    /** Text copied to the clipboard when the row is chosen (a "copying menu item").
-     *  The element performs the write itself on `menuselect`. */
-    copy?: string;
-    /** Copy a DOM node instead of a string (rich `text/html` + plain text). Bare
-     *  `copy-node` copies the nearest ancestor marked `[data-copy-source]`; a value
-     *  is a CSS selector resolved with `closest()`. Presence-based for the boolean
-     *  form. */
-    'copy-node'?: boolean | string;
-    /** Lazy copy: with an empty `copy`, activation dispatches `copyrequest` and the
-     *  write completes once `copy` is set back (within the activation window).
-     *  Presence-based. */
-    'copy-lazy'?: boolean | '';
-    /** Fired after a copy attempt (bubbling `copydone`, `detail: { ok }`).
-     *  All-lowercase so it binds in React *and* Preact. */
-    oncopydone?: (e: CustomEvent<{
-        ok: boolean;
-    }>) => void;
-    /** Fired on a lazy copy activation to request the content (bubbling
-     *  `copyrequest`). Answer by setting the `copy` attribute. All-lowercase. */
-    oncopyrequest?: (e: CustomEvent) => void;
 }
 /**
  * Attributes for the `<a-menu-group>` styled element. For the typed JSX
@@ -790,32 +770,42 @@ export interface AButtonAttributes extends BaseAttributes {
     form?: string;
     /** Custom event name dispatched (bubbling) on click. */
     'data-custom-event'?: string;
-    /** Text copied to the clipboard on activation (the "copy button"). The element
-     *  performs the write itself and flashes a success / failure state. */
+    'aria-disabled'?: 'true' | 'false' | boolean;
+    'aria-busy'?: 'true' | 'false' | boolean;
+}
+/** `<a-copy>` — the copy-to-clipboard behavior, slotted inside an activatable
+ *  control (`<a-button>`, `<a-menu-item>`, native `button`/`[role]`). It owns
+ *  the whole feature; the base controls carry no copy knowledge. `ButtonCopy` /
+ *  `MenuItemCopy` are the presets that drop it in. */
+export interface ACopyAttributes extends BaseAttributes {
+    /** Text copied to the clipboard when the host control is activated. */
     copy?: string;
     /** Copy a DOM node instead of a string (rich `text/html` + plain text). Bare
      *  `copy-node` copies the nearest ancestor marked `[data-copy-source]`; a value
-     *  is a CSS selector resolved with `closest()` (an ancestor region). Presence-
-     *  based for the boolean form. */
+     *  is a CSS selector resolved with `closest()` (an ancestor region). The copy
+     *  control is stripped from the serialized output. Presence-based for the
+     *  boolean form. */
     'copy-node'?: boolean | string;
-    /** Lazy copy: activation dispatches `copyrequest`; the consumer calls
-     *  `detail.provide(text)` with the content, which stays out of the DOM until
-     *  then. Takes precedence over `copy`. Presence-based. */
-    'copy-lazy'?: boolean | '';
+    /** Copy the current page URL (`location.href`) instead of a `copy` string; no
+     *  `copy` needed. Presence-based. */
+    'copy-url'?: boolean | '';
+    /** Prefix the copied `copy` string with `// URL: <href>`. Presence-based. */
+    'copy-with-url'?: boolean | '';
+    /** Float a ghost of the host's content upward as visual feedback on a
+     *  successful copy (rendered in the top layer so the host's overflow can't clip
+     *  it). Presence-based. Opt-in — `ButtonCopy` sets it. */
+    toast?: boolean | '';
     /** Fired after a copy attempt (`copydone`, `detail: { ok }`, non-bubbling so a
-     *  nested copy row can't flip an ancestor's feedback). All-lowercase so it
+     *  nested copy control can't flip an ancestor's feedback). All-lowercase so it
      *  binds in React *and* Preact. */
     oncopydone?: (e: CustomEvent<{
         ok: boolean;
     }>) => void;
-    /** Fired on a lazy copy activation (`copyrequest`, non-bubbling). Supply the
-     *  content by calling `detail.provide(text)` — synchronously or within the
-     *  click's activation window. All-lowercase. */
-    oncopyrequest?: (e: CustomEvent<{
-        provide: (text: string) => void;
-    }>) => void;
-    'aria-disabled'?: 'true' | 'false' | boolean;
-    'aria-busy'?: 'true' | 'false' | boolean;
+    /** Fired on **pointerdown** / keydown for a string-copy control (`copyrequest`,
+     *  non-bubbling). Answer by setting the `copy` attribute to the freshly-computed
+     *  value; the activation then copies it. The gap lets an off-UI-thread handler
+     *  set `copy` in time. All-lowercase. */
+    oncopyrequest?: (e: CustomEvent) => void;
 }
 /**
  * Attributes for the `<a-radio>` custom element — one option in a radio set.

package/dist/index.d.ts

@@ -27,9 +27,10 @@ export type { TagProps } from './components/Tag';
 export { Icon } from './components/Icon';
 export type { IconProps } from './components/Icon';
 export { Button } from './components/Button';
-export type { ButtonProps, BaseButtonProps, ContentMode, SubmitMode, PriorityMode, CopyMode, } from './components/Button';
+export type { ButtonProps, BaseButtonProps, ContentMode, SubmitMode, PriorityMode, } from './components/Button';
 export { ButtonCopy } from './components/ButtonCopy';
 export type { ButtonCopyProps } from './components/ButtonCopy';
+export type { CopyTarget } from './components/copy-props';
 export { ICON_SHAPES, ICON_SYNONYMS } from './elements/a-icon.shapes';
 export { Tooltip } from './components/Tooltip';
 export type { TooltipProps } from './components/Tooltip';

package/dist/jsx-runtime.d.ts

@@ -41,7 +41,7 @@ export declare function useMemo<T>(factory: () => T, deps: unknown[]): T;
 export declare function jsx(type: ComponentType, props: Record<string, unknown> | null, key?: string | number): unknown;
 export declare function jsxs(type: ComponentType, props: Record<string, unknown> | null, key?: string | number): unknown;
 export { _Fragment as Fragment };
-import type { AProgressAttributes, ATextAttributes, ATitleAttributes, ATagAttributes, AExpanderAttributes, AIconAttributes, AButtonAttributes, ACheckboxAttributes, ATooltipAttributes, AInputAttributes, AInputTimeAttributes, ACalendarAttributes, ARadioAttributes, ARadioGroupAttributes, AMenuAttributes, AMenuItemAttributes, AMenuGroupAttributes, ATabsAttributes, ATabAttributes, ATabpanelAttributes, ADialogAttributes, ACardAttributes, BaseAttributes } from './general_types';
+import type { AProgressAttributes, ATextAttributes, ATitleAttributes, ATagAttributes, AExpanderAttributes, AIconAttributes, AButtonAttributes, ACopyAttributes, ACheckboxAttributes, ATooltipAttributes, AInputAttributes, AInputTimeAttributes, ACalendarAttributes, ARadioAttributes, ARadioGroupAttributes, AMenuAttributes, AMenuItemAttributes, AMenuGroupAttributes, ATabsAttributes, ATabAttributes, ATabpanelAttributes, ADialogAttributes, ACardAttributes, BaseAttributes } from './general_types';
 export declare namespace JSX {
     interface IntrinsicElements extends React.JSX.IntrinsicElements, AntaIntrinsicElements {
     }
@@ -65,6 +65,7 @@ export interface AntaIntrinsicElements {
     'a-icon': AIconAttributes;
     'a-button': AButtonAttributes;
     'a-button-label': BaseAttributes;
+    'a-copy': ACopyAttributes;
     'a-checkbox': ACheckboxAttributes;
     'a-checkbox-label': BaseAttributes;
     'a-checkbox-hint': BaseAttributes;

package/package.json

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