@antadesign/anta 0.3.10 → 0.3.12

package/dist/components/Button.d.ts

@@ -55,7 +55,8 @@ export type ContentMode = {
     iconTrailing?: IconShape;
 };
 /** Submit axis — anchors (href) don't carry form-submission props; buttons
- *  don't carry anchor props. */
+ *  don't carry anchor props. (Copy is no longer a Button concern — `ButtonCopy`
+ *  composes a `<a-copy>` child; see `copy-props.ts`.) */
 export type SubmitMode = {
     /** Renders as `<a role="button">` instead of `<a-button>`. */
     href: string;
@@ -100,50 +101,7 @@ 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 `copyLazy` 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;
-    copyLazy?: never;
-    onCopied?: never;
-    onCopyRequest?: never;
-} | {
-    /** Text copied to the clipboard on click. */
-    copy: string;
-    copyNode?: never;
-    copyLazy?: never;
-    onCopyRequest?: 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;
-    copyLazy?: never;
-    onCopyRequest?: never;
-    /** Fires after the copy attempt with whether it succeeded. */
-    onCopied?: (ok: boolean) => void;
-} | {
-    /** Lazy copy: the content isn't computed or held in the DOM until the
-     *  click. The click fires `onCopyRequest(provide)`; call `provide(text)`
-     *  with the value — synchronously, or after an `await` (the browser's
-     *  transient-activation window still covers the write). */
-    copyLazy: true;
-    copy?: never;
-    copyNode?: never;
-    /** Supplies the lazily-computed content on click: call `provide(text)`. */
-    onCopyRequest: (provide: (text: string) => void) => void;
-    /** Fires after the copy attempt with whether it succeeded. */
-    onCopied?: (ok: boolean) => void;
-};
-export type ButtonProps = BaseButtonProps & PriorityMode & ContentMode & SubmitMode & CopyMode & BaseProps;
+export type ButtonProps = BaseButtonProps & PriorityMode & ContentMode & SubmitMode & BaseProps;
 /**
  * Action button.
  *
@@ -164,4 +122,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, copyLazy, 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, 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,
@@ -16,21 +16,14 @@ const Button = ({
   href,
   type,
   form,
-  copy,
-  copyNode,
-  copyLazy,
-  onCopied,
-  onCopyRequest,
   className,
   style,
   children,
   ...rest
 }) => {
-  const isCopy = copy != null || copyNode != null || copyLazy === 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
@@ -60,26 +53,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-lazy": copyLazy ? "" : 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,
-    // The element hands `provide` on the request event; forward it so the
-    // consumer supplies the lazily-computed content.
-    oncopyrequest: onCopyRequest ? (e) => onCopyRequest(nativeStateChange(e).detail.provide) : 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" })

package/dist/components/ButtonCopy.d.ts

@@ -1,32 +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;
-} | {
-    copyLazy: 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 `copyLazy` + `onCopyRequest` to
- * compute the content on click. 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`).
+ * 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 / 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 copyLazy label="Copy report" onCopyRequest={(p) => p(buildReport())} />
+ * <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/MenuItem.d.ts

@@ -1,6 +1,5 @@
 import type { BaseProps } from '../general_types';
 import type { IconShape } from '../elements/a-icon.shapes';
-import type { CopyMode } from './Button';
 /** Props shared by every menu item, link or not. */
 export interface MenuItemCommonProps extends BaseProps {
     /** Leading icon shape. */
@@ -84,11 +83,6 @@ export type MenuItemLinkMode = {
     selectionIndicator?: never;
     indeterminate?: never;
     indicator?: never;
-    copy?: never;
-    copyNode?: never;
-    copyLazy?: never;
-    onCopied?: never;
-    onCopyRequest?: never;
 };
 export type MenuItemActionMode = {
     href?: never;
@@ -120,7 +114,7 @@ export type MenuItemActionMode = {
      *  passive (aria-hidden, no pointer events) so the row owns the click. */
     indicator?: React.ReactNode;
 };
-export type MenuItemProps = MenuItemCommonProps & (MenuItemLinkMode | (MenuItemActionMode & CopyMode));
+export type MenuItemProps = MenuItemCommonProps & (MenuItemLinkMode | MenuItemActionMode);
 /**
  * MenuItem — a single selectable row inside a `Menu`. Composes a leading
  * `icon`, a `label` (or `children`), an optional trailing `kbd` hint, and an
@@ -141,4 +135,4 @@ export type MenuItemProps = MenuItemCommonProps & (MenuItemLinkMode | (MenuItemA
  * </MenuItem>
  * ```
  */
-export declare const MenuItem: ({ icon, label, hint, kbd, iconTrailing, disabled, selected, selectionIndicator, indeterminate, indicator, tone, toneSelected, submenu, value, onSelect, href, target, rel, download, ping, copy, copyNode, copyLazy, onCopied, onCopyRequest, role: roleOverride, className, style, children, ...rest }: MenuItemProps) => any;
+export declare const MenuItem: ({ icon, label, hint, kbd, iconTrailing, disabled, selected, selectionIndicator, indeterminate, indicator, tone, toneSelected, submenu, value, onSelect, href, target, rel, download, ping, role: roleOverride, className, style, children, ...rest }: MenuItemProps) => any;

package/dist/components/MenuItem.js

@@ -1,5 +1,5 @@
 import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
-import { toneStyle, nativeStateChange } from "../anta_helpers";
+import { toneStyle } from "../anta_helpers";
 const MenuItem = ({
   icon,
   label,
@@ -21,19 +21,13 @@ const MenuItem = ({
   rel,
   download,
   ping,
-  copy,
-  copyNode,
-  copyLazy,
-  onCopied,
-  onCopyRequest,
   role: roleOverride,
   className,
   style,
   children,
   ...rest
 }) => {
-  const isCopy = copy != null || copyNode != null || copyLazy === true;
-  const leadingIcon = icon ?? (isCopy ? "copy" : void 0);
+  const leadingIcon = icon;
   const checkable = selectionIndicator === "checkbox" || selectionIndicator === "radio" || selectionIndicator === "check";
   const role = selectionIndicator === "checkbox" ? "menuitemcheckbox" : selectionIndicator === "radio" || selectionIndicator === "check" ? "menuitemradio" : "menuitem";
   const ariaChecked = !checkable ? void 0 : selectionIndicator === "checkbox" && indeterminate ? "mixed" : selected ? "true" : "false";
@@ -83,12 +77,6 @@ const MenuItem = ({
       "aria-haspopup": submenu ? "menu" : void 0,
       "aria-disabled": disabled ? "true" : void 0,
       onmenuselect: onSelect ? (e) => onSelect(e, { value, label }) : void 0,
-      copy: copy != null ? copy : void 0,
-      "copy-node": copyNode === true ? "" : typeof copyNode === "string" ? copyNode : void 0,
-      "copy-lazy": copyLazy ? "" : void 0,
-      "data-copy-node-button": copyNode != null && copyNode !== false ? "" : void 0,
-      oncopydone: onCopied ? (e) => onCopied(nativeStateChange(e).detail?.ok ?? false) : void 0,
-      oncopyrequest: onCopyRequest ? (e) => onCopyRequest(nativeStateChange(e).detail.provide) : void 0,
       class: className,
       ...rest,
       children: [

package/dist/components/MenuItemCopy.d.ts

@@ -1,33 +1,37 @@
 import { type MenuItemCommonProps, type MenuItemActionMode } from './MenuItem';
-import type { CopyMode } from './Button';
-/** The action-mode menu-item props plus a required copy target (a copying row
- *  must copy something). The target intersection drops `CopyMode`'s "no copy
- *  prop" member. */
-export type MenuItemCopyProps = MenuItemCommonProps & MenuItemActionMode & CopyMode & ({
-    copy: string;
-} | {
-    copyNode: boolean | string;
-} | {
-    copyLazy: true;
-});
+import { type CopyTarget } from './copy-props';
+/** Action-mode menu-item props plus a required copy target (a copying row must
+ *  copy something). The action-mode props that don't fit a copy row are pinned to
+ *  `never`: `submenu` (a copy row has no flyout) and the selection-indicator axis
+ *  (`selectionIndicator` / `indeterminate` / `indicator` — a copy row isn't a
+ *  checkable option). Pinning (not `Omit`) keeps the intersection expanding fully
+ *  in the docs props table. */
+export type MenuItemCopyProps = MenuItemCommonProps & MenuItemActionMode & {
+    submenu?: never;
+    selectionIndicator?: never;
+    indeterminate?: never;
+    indicator?: never;
+} & CopyTarget;
 /**
  * Copying menu item — a `MenuItem` preset for copy-to-clipboard rows inside a
  * `Menu`. Set `copy` for a literal string, `copyNode` to copy a DOM region, or
- * `copyLazy` + `onCopyRequest` to compute the content on select. The
- * `<a-menu-item>` element performs the write when the row is chosen; this wrapper
+ * `copyUrl` to copy the current page URL. For content computed on demand, keep
+ * `copy` reactive and refresh it in `onCopyRequest` (fired on pointerdown / keydown).
+ *
+ * It composes a plain `<MenuItem>` with a slotted `<a-copy>` child that performs
+ * the write when the row is chosen — the item itself carries no copy behavior.
+ * The row is kept open (`data-menu-open`) so the feedback shows: this wrapper
  * flips the leading icon to a check / ✕ and retones for ~2s (see `useCopyFeedback`).
  *
- * The menu closes on select by default, so the feedback shows only when the row
- * is kept open (`data-menu-open`). Defaults `label` to "Copy" and the leading
- * `icon` to `copy`; override either. Other props pass through — `tone`, `kbd`,
- * `onCopied`.
+ * Defaults `label` to "Copy" and the leading `icon` to `copy`; override either.
+ * Other props pass through — `tone`, `kbd`, `onCopied`.
  *
  * @example
  * ```tsx
  * <Menu>
  *   <MenuItemCopy copy={shareUrl} label="Copy link" kbd="⌘C" />
- *   <MenuItemCopy copyNode=".invoice" label="Copy invoice" data-menu-open />
+ *   <MenuItemCopy copyNode=".invoice" label="Copy invoice" />
  * </Menu>
  * ```
  */
-export declare const MenuItemCopy: ({ label, icon, tone, onCopied, ...rest }: MenuItemCopyProps) => any;
+export declare const MenuItemCopy: ({ label, icon, tone, onCopied, onCopyRequest, copy, copyNode, copyUrl, copyWithUrl, children, ...rest }: MenuItemCopyProps) => any;

package/dist/components/MenuItemCopy.js

@@ -1,9 +1,44 @@
-import { jsx } from "@antadesign/anta/jsx-runtime";
+import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
 import { MenuItem } from "./MenuItem";
 import { useCopyFeedback } from "../anta_helpers";
-const MenuItemCopy = ({ label = "Copy", icon = "copy", tone, onCopied, ...rest }) => {
+import { copyElementProps, isNodeCopy } from "./copy-props";
+const MenuItemCopy = ({
+  label = "Copy",
+  icon = "copy",
+  tone,
+  onCopied,
+  onCopyRequest,
+  copy,
+  copyNode,
+  copyUrl,
+  copyWithUrl,
+  children,
+  ...rest
+}) => {
   const { shownIcon, shownTone, handleCopied } = useCopyFeedback(icon, tone, onCopied);
-  return /* @__PURE__ */ jsx(MenuItem, { label, icon: shownIcon, tone: shownTone, onCopied: handleCopied, ...rest });
+  const copyAttrs = copyElementProps({
+    copy,
+    copyNode,
+    copyUrl,
+    copyWithUrl,
+    onCopyRequest,
+    onCopied: handleCopied
+  });
+  return /* @__PURE__ */ jsxs(
+    MenuItem,
+    {
+      label,
+      icon: shownIcon,
+      tone: shownTone,
+      "data-menu-open": "",
+      "data-copy-node-button": isNodeCopy({ copyNode }) ? "" : void 0,
+      ...rest,
+      children: [
+        children,
+        /* @__PURE__ */ jsx("a-copy", { ...copyAttrs })
+      ]
+    }
+  );
 };
 export {
   MenuItemCopy

package/dist/components/Select.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';
 /** One option in a `<Select>`. Pass a bare string as shorthand for
  *  `{ value: s, label: s }`. Carries an index signature so you can attach
  *  arbitrary fields (a `ranAt` date, a `status`, …) and read them back in
@@ -131,6 +132,13 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
      *  logical pick (both rows toggle together; the trigger resolves to the last). Dev
      *  builds `console.warn` on a duplicate. */
     options: SelectItem[];
+    /** Preferred placement of the options menu relative to the trigger. The menu
+     *  auto-flips vertically and clamps horizontally when needed.
+     *  @defaultValue bottom-start */
+    placement?: MenuProps['placement'];
+    /** Gap in pixels between the trigger and the options menu.
+     *  @defaultValue 4 */
+    offset?: number;
     /** The per-row mark for **single**-select: `'none'` (a tint-only highlight),
      *  `'check'` (a trailing checkmark on the selected row, keeping the tint — the
      *  canonical Select look), or `'radio'` (a leading radio on every row).

package/dist/components/Select.js

@@ -37,6 +37,8 @@ function optionsWithSelection(options, values) {
 const Select = (props) => {
   const {
     options,
+    placement,
+    offset,
     selection,
     indicator,
     value,
@@ -274,6 +276,8 @@ const Select = (props) => {
     /* @__PURE__ */ jsxs(
       Menu,
       {
+        placement,
+        offset,
         onStateChange: (_e, { next }) => {
           setOpen(next);
           if (!next) {

package/dist/components/SelectFaceted.d.ts

@@ -1,6 +1,7 @@
 import type { BaseProps } from '../general_types';
 import type { IconShape } from '../elements/a-icon.shapes';
 import type { SelectItem, SelectOption } from './Select';
+import { type MenuProps } from './Menu';
 interface FacetBase {
     /** The facet's namespace — the key its value is stored under in the value
      *  record, and what `onValueChange`'s `attrs.facet` reports. Unique across
@@ -108,6 +109,13 @@ export interface SelectFacetedTriggerState {
 export interface SelectFacetedProps extends Omit<BaseProps, 'children'> {
     /** The facets (dimensions) to filter across, each with its own editor kind. */
     facets: SelectFacet[];
+    /** Preferred placement of the root filter menu relative to its trigger. The
+     *  menu auto-flips vertically and clamps horizontally when needed.
+     *  @defaultValue bottom-start */
+    placement?: MenuProps['placement'];
+    /** Gap in pixels between the trigger and the filter menu.
+     *  @defaultValue 4 */
+    offset?: number;
     /** Controlled value — the facet-keyed record. When provided, the consumer
      *  owns state: a pick only *requests* a change via `onValueChange` (reject by
      *  not updating). Leave undefined for uncontrolled. */

package/dist/components/SelectFaceted.js

@@ -27,6 +27,8 @@ const defaultMatch = (o, query) => matchesQuery(o, matchQueryRegex(query));
 const SelectFaceted = (props) => {
   const {
     facets,
+    placement,
+    offset,
     value,
     defaultValue,
     onValueChange,
@@ -284,6 +286,8 @@ const SelectFaceted = (props) => {
     /* @__PURE__ */ jsxs(
       Menu,
       {
+        placement,
+        offset,
         open,
         onStateChange: (_e, { next }) => {
           setOpen(next);

package/dist/components/copy-props.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The copy target for a copy preset (`ButtonCopy` / `MenuItemCopy`) — exactly
+ * one of a literal string, a DOM region, or the page URL. The write itself is
+ * performed by the slotted `<a-copy>` element; these props map to its attributes
+ * via `copyElementProps`. `copyWithUrl` / `onCopyRequest` are only meaningful for
+ * the string target, so the union pins them `never` elsewhere.
+ */
+export type CopyTarget = {
+    /** Text copied to the clipboard on activation. */
+    copy: string;
+    /** Prefix the copied text with `// URL: <current page URL>`. */
+    copyWithUrl?: boolean;
+    /** Compute the copy content lazily. Fires on pointerdown / keydown; update
+     *  `copy` (a state change) here and the activation copies the latest value.
+     *  The gap lets the update land even off the UI thread — only the
+     *  serializable `copy` string crosses. */
+    onCopyRequest?: () => void;
+    /** Fires after the copy attempt with whether it succeeded. */
+    onCopied?: (ok: boolean) => void;
+    copyNode?: never;
+    copyUrl?: never;
+} | {
+    /** 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;
+    /** Fires after the copy attempt with whether it succeeded. */
+    onCopied?: (ok: boolean) => void;
+    copy?: never;
+    copyUrl?: never;
+    copyWithUrl?: never;
+    onCopyRequest?: never;
+} | {
+    /** Copy the current page URL (`location.href`). */
+    copyUrl: true;
+    /** Fires after the copy attempt with whether it succeeded. */
+    onCopied?: (ok: boolean) => void;
+    copy?: never;
+    copyNode?: never;
+    copyWithUrl?: never;
+    onCopyRequest?: never;
+};
+/** Everything `copyElementProps` reads: the target plus the resolved `onCopied`
+ *  (the preset passes its feedback-wrapped handler) and the `toast` opt-in. */
+type CopyElementInput = {
+    copy?: string;
+    copyNode?: boolean | string;
+    copyUrl?: true;
+    copyWithUrl?: boolean;
+    onCopyRequest?: () => void;
+    onCopied?: (ok: boolean) => void;
+    toast?: boolean;
+};
+/** Project the copy-target props onto `<a-copy>` attributes + event handlers.
+ *  Shared by `ButtonCopy` / `MenuItemCopy` so the mapping (and the cross-renderer
+ *  `copydone` detail unwrap) lives in one place. */
+export declare function copyElementProps(p: CopyElementInput): {
+    readonly copy: string | undefined;
+    readonly 'copy-node': string | undefined;
+    readonly 'copy-url': "" | undefined;
+    readonly 'copy-with-url': "" | undefined;
+    readonly toast: "" | undefined;
+    readonly oncopydone: ((e: any) => void) | undefined;
+    readonly oncopyrequest: (() => void) | undefined;
+};
+/** True when these props copy a DOM node — the host control must then be marked
+ *  `data-copy-node-button` so the serializer strips it from the copied region. */
+export declare function isNodeCopy(p: {
+    copyNode?: boolean | string;
+}): boolean;
+export {};

package/dist/components/copy-props.js

@@ -0,0 +1,20 @@
+import { nativeStateChange } from "../anta_helpers";
+function copyElementProps(p) {
+  const { copy, copyNode, copyUrl, copyWithUrl, onCopyRequest, onCopied, toast } = p;
+  return {
+    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,
+    toast: toast ? "" : void 0,
+    oncopydone: onCopied ? (e) => onCopied(nativeStateChange(e).detail?.ok ?? false) : void 0,
+    oncopyrequest: onCopyRequest ? () => onCopyRequest() : void 0
+  };
+}
+function isNodeCopy(p) {
+  return p.copyNode != null && p.copyNode !== false;
+}
+export {
+  copyElementProps,
+  isNodeCopy
+};