@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/context-menu.md

@@ -0,0 +1,74 @@
+## What it is
+
+A **Menu** opened by right-click, long-press, or the keyboard's own request (Shift+F10, the Menu key), anchored at the point it was asked for rather than at a button. Wrap the region the commands are about — a row, a card, a canvas — and hand it the same `MenuEntry[]` tree **Menu**, **Menubar** and **CommandPalette** take: one command object, four surfaces.
+
+Use it when the commands belong to a thing the reader can point at and there is no room, or no wish, for a visible button. If there is a button, use **Menu**. If the commands are global, use **CommandPalette**. If a right-click should do one thing rather than offer several, it should not be a menu at all.
+
+## The contract
+
+```
+@items                                       — the MenuNode tree, identical to Menu's
+@open? @defaultOpen? @onOpenChange?          — the overlay contract
+@onSelect?(node)                             — fires after any item activates, alongside the node's own onSelect
+@label? (default 'Context menu')             — the root panel's accessible name
+@focusable? (default true)                   — the region takes a tab stop
+@longPressDelay? (seconds, default 0.5)      — touch
+@hoverDelay? (ms, default 110)               — submenu hover intent
+@safeDelay? (ms, default 300)                — how long the safe triangle defers a sibling
+@platform? ('apple' | 'other')               — force the shortcut spelling
+<:default as |open|>                         — the right-clickable region
+```
+
+**Nothing about `@items` is context-menu specific.** Commands, toggles with true/false/mixed, radio groups, sections, submenus, separators, `kbd` shortcuts, the `needsInput` ellipsis convention, `isDefault`, `destructive`, and dynamic Alt overlays all come from `menu.gts` — the taxonomy, the row transform, the panel markup, its whole stylesheet, the safe triangle, the roving tabindex and the type-ahead. A command object written for Menu renders here unchanged, which is the property that stops the four menu surfaces drifting apart.
+
+**The region is the trigger, and it takes a tab stop by default.** Browsers fire `contextmenu` for Shift+F10 and the Menu key only on an element that can hold focus, so a menu on a bare `<div>` is pointer-only whatever it listens for. `@focusable={{false}}` opts out when the region already contains its own focusable rows and the menu should hang off those instead.
+
+**It is anchored to a point.** The invocation point is materialised as a zero-size fixed span and measured by the same `anchorTo` every other Pretui overlay uses, so it flips and shifts near a viewport edge for free. A keyboard invocation has no pointer, so it anchors on the region's own box — its start edge, a little way down — never at the viewport origin.
+
+**Long-press is one-shot.** Any movement, lift or cancel clears the handle and nothing re-arms it. The default is the platform long-press threshold on both mobile OSes.
+
+**The wrapper is `display: contents`**, so the component does not disturb the layout it wraps. The region itself is a block, and the default block is yielded `open` so it can show a selected treatment while the menu is up.
+
+## Prior art
+
+**shadcn / Radix ContextMenu** mirrors DropdownMenu part for part — `Item`, `CheckboxItem`, `RadioItem`, `Sub`, `Separator`, `Shortcut`, `destructive` — anchored on a virtual reference at the pointer, with a 700ms long-press. **Base UI ContextMenu** is the same shape. **MUI** uses `Menu` with `anchorReference='anchorPosition'`. Agents will emit an `onContextMenu` handler with `preventDefault` and a `ContextMenuTrigger` wrapping the region.
+
+Where this is better: **the keyboard path exists.** A right-click menu that can only be opened by right-clicking is a set of commands that do not exist for anyone using a keyboard. The region is reachable, Shift+F10 and the Menu key are handled explicitly (browsers disagree about the coordinates they report for them, and a menu pinned to the top-left corner is the usual symptom), a keyboard invocation focuses the first item as the APG asks, and dismissal puts focus back on the thing the menu was about rather than dropping it on the body. It is also **not a second menu engine**: Radix and Base UI ship a ContextMenu that duplicates DropdownMenu, and the two drift; this file contains only the anchoring, the gestures and the focus return.
+
+Where it is thinner: no per-item components — the tree is data, so there is no `ContextMenuItem` to wrap a custom row in; no `modal` arg; and no way to keep the browser's own menu on an `<input>` inside the region, because `preventDefault` is applied to every `contextmenu` the region receives. Put text fields outside the region, or accept that their native cut/paste menu is replaced.
+
+## Accessibility
+
+Governing pattern: APG **Menu and Menubar**, with the menu surface itself supplied by `MenuPanel` (see **Menu** for the roles inside it).
+
+What this component does, and the tests assert:
+
+- **The region is in the tab order** (`tabindex='0'` through the roving-tabindex modifier) unless `@focusable={{false}}`, which takes it out of the tab order.
+- **A right-click opens the menu displayed, focus untouched**, exactly as a platform menu does; the first Down or Home then moves focus onto the first item (Up or End onto the last) from wherever focus was. **Shift+F10 opens it with focus on the first item.** The two invocations are deliberately different, and both are asserted.
+- **Arrow keys walk the rows, Home and End jump, Right opens a submenu onto its first item, Left closes it back to the parent, Enter activates.** Type-ahead comes from the shared buffer.
+- **Escape closes one level at a time**, and the last one returns focus to the region. Activating an item closes everything and returns focus the same way.
+- **A disabled row is present and skipped**, not removed.
+- **Outside pointer and a right-click elsewhere close it**; a right-click inside the region while open re-anchors rather than stacking.
+- **The root panel is named** by `@label`; each submenu panel is named by its parent row.
+
+The caller's part: keep the region a thing, not the page. The tab stop and the accessible name are for a reader who lands on it and presses Shift+F10, so the region should be recognisable as the object of the commands. If the region already has focusable rows, turn `@focusable` off and let the menu hang off those. And put the destructive command last, behind a separator, with `destructive: true`; the flag is what makes it visually distinct, not its position.
+
+## Theming
+
+The region reads `--radius-surface` for its focus outline shape and `--ring` for the outline itself. Everything else — panel surface, border, shadow, rows, shortcut faces, the destructive tone, check and submenu indicators — is `MenuPanel`'s and follows **Menu**'s theming exactly. Nothing here has a knob of its own; a theme that retunes Menu retunes this with it, which is the point of sharing the engine.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                                         | Give them                                                 |
+| --------------------------------------------------- | --------------------------------------------------------- |
+| `ContextMenuTrigger`                                | the `<:default>` block — the region                       |
+| `ContextMenuContent` / `Item` / `Sub` / `Separator` | the `@items` tree                                         |
+| `CheckboxItem` / `RadioItem`                        | `kind: 'toggle'` / `kind: 'radio'` nodes                  |
+| `ContextMenuShortcut`                               | `kbd: 'Mod+O'` on the node; `@platform` fixes the face    |
+| Radix `onSelect` on an item                         | the node's `onSelect`, plus `@onSelect` for the component |
+| `onContextMenu` + `preventDefault`                  | done for you — do not add another                         |
+| MUI `anchorReference='anchorPosition'`              | built in; the point comes from the gesture                |
+| a button that opens a menu                          | **Menu**                                                  |
+| commands across the whole app                       | **CommandPalette**                                        |

package/bundled-realms/pretui/components/context-menu.usage.gts

@@ -0,0 +1,244 @@
+// Pretui — ContextMenu usage page.
+//
+// The stage is a board of lots, because a context menu only makes sense
+// against something you can point at. The same `MenuEntry[]` shape `Menu`,
+// `Menubar` and `CommandPalette` take is used verbatim — that is the claim the
+// page is making, so it should be demonstrated rather than restated.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { ContextMenu } from './context-menu';
+import type { MenuEntry, ShortcutPlatform } from '../internal/menu';
+
+const PLATFORM_OPTIONS = ['apple', 'other'];
+
+class ContextMenuUsage extends GlimmerComponent {
+  @tracked platform = 'apple';
+  @tracked focusable = true;
+  @tracked pinned = false;
+  @tracked grade = 'cupping';
+  @tracked log = '—';
+
+  setPlatform = (value: string) => (this.platform = value);
+  setFocusable = (value: boolean) => (this.focusable = value);
+
+  get platformValue() {
+    return this.platform as ShortcutPlatform;
+  }
+
+  private ran = (what: string) => () => (this.log = what);
+
+  setPinned = (next: boolean) => {
+    this.pinned = next;
+    this.log = next ? 'Pinned to desk' : 'Unpinned';
+  };
+  sortByCupping = () => {
+    this.grade = 'cupping';
+    this.log = 'Sort: cupping score';
+  };
+  sortByArrival = () => {
+    this.grade = 'arrival';
+    this.log = 'Sort: arrival date';
+  };
+
+  get items(): MenuEntry[] {
+    return [
+      {
+        label: 'Open lot',
+        kbd: 'Mod+O',
+        isDefault: true,
+        onSelect: this.ran('Open lot'),
+      },
+      {
+        label: 'Rename',
+        needsInput: true,
+        onSelect: this.ran('Rename'),
+      },
+      '---',
+      {
+        kind: 'toggle',
+        label: 'Pin to desk',
+        checked: this.pinned,
+        onChange: this.setPinned,
+      },
+      {
+        kind: 'section',
+        label: 'Sort board by',
+        items: [
+          {
+            kind: 'radio',
+            group: 'grade',
+            label: 'Cupping score',
+            checked: this.grade === 'cupping',
+            onSelect: this.sortByCupping,
+          },
+          {
+            kind: 'radio',
+            group: 'grade',
+            label: 'Arrival date',
+            checked: this.grade === 'arrival',
+            onSelect: this.sortByArrival,
+          },
+        ],
+      },
+      {
+        kind: 'submenu',
+        label: 'Share',
+        items: [
+          { label: 'Copy link', kbd: 'Mod+Shift+C', onSelect: this.ran('Copy link') },
+          { label: 'Email the desk', needsInput: true, onSelect: this.ran('Email the desk') },
+        ],
+      },
+      '---',
+      {
+        label: 'Withdraw lot',
+        destructive: true,
+        onSelect: this.ran('Withdraw lot'),
+      },
+    ];
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='ContextMenu'
+      @description='Right-click, on the shared menu engine rather than a second one. The MenuNode taxonomy, the row transform, the panel markup and its whole stylesheet, the shortcut faces, the safe triangle, the roving tabindex and the type-ahead all come from menu.gts — a command object written for Menu renders here unchanged. What is genuinely different is the anchoring and the keyboard: the menu hangs off a zero-size fixed box at the invocation point, measured by the same anchorTo primitive every other Pretui overlay uses, so it flips and shifts near a viewport edge for free. The region takes a tab stop by default, which is what makes Shift+F10 and the Menu key reach it at all, and dismissal returns focus to the region rather than dropping it on the body.'
+    >
+      <:example>
+        <ContextMenu
+          @items={{this.items}}
+          @platform={{this.platformValue}}
+          @focusable={{this.focusable}}
+          @label='Lot actions'
+        >
+          <:default as |isOpen|>
+            <div class='cm-board' data-open={{if isOpen 'true'}}>
+              <span class='cm-board-title'>Arrivals board</span>
+              <ul class='cm-board-list'>
+                <li>Ethiopia Guji · 87.5</li>
+                <li>Colombia Huila · 86.0</li>
+                <li>Kenya Nyeri · 88.25</li>
+              </ul>
+              <span class='cm-board-hint'>right-click, long-press, or focus and
+                press Shift+F10</span>
+            </div>
+          </:default>
+        </ContextMenu>
+        <p class='cm-log'>last action: <strong>{{this.log}}</strong></p>
+        <p class='cm-hint'>Tab to the board and press
+          <em>Shift+F10</em>
+          (or the Menu key): the menu opens against the board rather than at the
+          top-left corner, and the first item already has focus, which is what
+          the APG asks for on a keyboard invocation. A right-click opens it
+          merely displayed, focus untouched, exactly as a platform menu does.
+          Escape closes one level at a time and the last one puts focus back on
+          the board.</p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @description='The same MenuNode tree Menu takes: commands, toggles with true/false/mixed, radio groups, sections, submenus, separators, dynamic Alt overlays, the ellipsis convention and the destructive flag. Nothing about this arg is context-menu specific, which is the point.'
+          @value={{this.items}}
+        />
+        <Args.Bool
+          @name='focusable'
+          @description='The region takes a tab stop. This is what makes the platform keys reachable — a browser fires contextmenu for Shift+F10 and the Menu key only on an element that can hold focus, so a menu on a bare div is pointer-only no matter what it listens for. Turn it off when the region already contains its own focusable rows and the menu should hang off those instead.'
+          @value={{this.focusable}}
+          @defaultValue={{true}}
+          @onInput={{this.setFocusable}}
+        />
+        <Args.String
+          @name='platform'
+          @description='Forces the shortcut spelling instead of detecting it. One kbd token renders both faces, so the platform mapping never lands in a caller string.'
+          @value={{this.platform}}
+          @options={{PLATFORM_OPTIONS}}
+          @defaultValue='(detected)'
+          @onInput={{this.setPlatform}}
+        />
+        <Args.Base
+          @name='open / onOpenChange / defaultOpen / onSelect'
+          @description='The overlay contract plus the menu one. A controlled ContextMenu is how a host that owns its own selection model opens the menu itself — the point it opens at is still the components own, taken from the gesture.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='longPressDelay'
+          @description='Seconds of press before a touch opens the menu (0.5, the platform long-press threshold on both mobile OSes; Radix uses 0.7). One-shot: any movement, lift or cancel clears the handle and nothing re-arms it.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='hoverDelay / safeDelay'
+          @description='Submenu hover intent and how long the Amazon safe triangle keeps deferring a sibling row the pointer crosses on its diagonal. Both are the same owned, one-shot timers Menu uses, and the keyboard path never depends on either.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='default'
+          @description='The right-clickable region, yielded the open state so it can show its own selected treatment while the menu is up. The wrapper is display:contents, so it does not disturb the layout it wraps.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .cm-board {
+        display: grid;
+        gap: var(--space-3, 8px);
+        max-width: 320px;
+        padding: var(--space-5, 15px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: 0 0 0 1px var(--border);
+        transition: box-shadow var(--pretui-dur-snap, 140ms) var(--pretui-ease-snap, ease);
+      }
+      .cm-board[data-open] {
+        box-shadow: 0 0 0 1px var(--ring);
+      }
+      .cm-board-title {
+        font-weight: 600;
+        font-size: var(--text-ui-md, 12.5px);
+      }
+      .cm-board-list {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        display: grid;
+        gap: 3px;
+        font-size: var(--text-ui-md, 12.5px);
+        font-variant-numeric: tabular-nums;
+        color: var(--muted-foreground);
+      }
+      .cm-board-hint {
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--ink-3, var(--boxel-400));
+      }
+      .cm-log {
+        margin: var(--space-4, 11px) 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .cm-log strong {
+        color: var(--foreground);
+        font-weight: 600;
+      }
+      .cm-hint {
+        margin: var(--space-3, 8px) 0 0;
+        max-width: 62ch;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.6;
+        color: var(--muted-foreground);
+      }
+      .cm-hint em {
+        font-style: normal;
+        font-weight: 600;
+        color: var(--foreground);
+      }
+      @media (prefers-reduced-motion: reduce) {
+        .cm-board {
+          transition: none;
+        }
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_CONTEXT_MENU: Record<string, unknown> = {
+  ContextMenu: ContextMenuUsage,
+};

package/bundled-realms/pretui/components/copy-button.gts

@@ -0,0 +1,237 @@
+// Pretui — CopyButton: an IconButton that copies text to the clipboard.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { registerDestructor } from '@ember/destroyable';
+import type Owner from '@ember/owner';
+import { on } from '@ember/modifier';
+import CheckIcon from '@cardstack/boxel-icons/check';
+import CopyIcon from '@cardstack/boxel-icons/copy';
+import XIcon from '@cardstack/boxel-icons/x';
+import { IconButton, ICON_SIZE } from './icon-button';
+import { VisuallyHidden } from './visually-hidden';
+import { firstDefined } from '../pretui-primitives';
+import type { IconButtonSignature } from './icon-button';
+import type { PretuiSizeArg } from '../pretui-primitives';
+
+// Fresh small. boxel-ui's copy-button rides Tooltip (ember-velcro
+// wormhole — wart list forbids); this one is an IconButton that copies
+// @text to the clipboard and swaps its glyph while the result holds.
+// The result holds for 2 s, the duration every clipboard component settles
+// on, whatever the input: a timer is the one reset.
+
+type CopyState = 'idle' | 'copied' | 'failed';
+
+const STATUS_TEXT: Record<CopyState, string> = {
+  idle: '',
+  copied: 'Copied',
+  failed: 'Copy failed',
+};
+
+export const RESET_MS = 2000;
+
+export interface CopyButtonSignature {
+  Args: {
+    text?: string | null | undefined;
+    /** alias — the clipboard payload is this control's value, and `@value`
+     * is what Chakra/Ant/Mantine's Clipboard all call it */
+    value?: string | null | undefined;
+    /** alias of @text, boxel-ui's spelling */
+    textToCopy?: string | null | undefined;
+    /** accessible name — 'Copy to clipboard' by default */
+    label?: string;
+    /** alias of @label, boxel-ui's spelling */
+    ariaLabel?: string;
+    tone?: IconButtonSignature['Args']['tone'];
+    appearance?: IconButtonSignature['Args']['appearance'];
+    /** deprecated sugar over @tone + @appearance */
+    variant?: IconButtonSignature['Args']['variant'];
+    size?: PretuiSizeArg;
+    disabled?: boolean;
+  };
+  Element: HTMLButtonElement;
+}
+
+export class CopyButton extends Component<CopyButtonSignature> {
+  @tracked state: CopyState = 'idle';
+  // Announced separately from the glyph: a repeat copy empties the region
+  // while the glyph keeps showing the last result, so the result is announced
+  // again without a visible flicker.
+  @tracked announced: CopyState = 'idle';
+
+  constructor(owner: Owner, args: CopyButtonSignature['Args']) {
+    super(owner, args);
+    registerDestructor(this, () => this.clearResetTimer());
+  }
+
+  // Fixed through the result, so voice control keeps matching it; the status
+  // region announces the result instead. An empty name is no name.
+  get label() {
+    return (
+      firstDefined(this.args.label, this.args.ariaLabel) || 'Copy to clipboard'
+    );
+  }
+  get text() {
+    return firstDefined(this.args.text, this.args.value, this.args.textToCopy);
+  }
+  get copied() {
+    return this.state === 'copied';
+  }
+  get failed() {
+    return this.state === 'failed';
+  }
+  get dataState() {
+    return this.state === 'idle' ? undefined : this.state;
+  }
+  get statusText() {
+    return STATUS_TEXT[this.announced];
+  }
+  get glyph(): 'copy' | 'check' | 'cross' {
+    return this.copied ? 'check' : this.failed ? 'cross' : 'copy';
+  }
+  // Which copy is in flight; a result from an earlier click is dropped, so a
+  // slow failure never overwrites a newer success.
+  private attempt = 0;
+  private resetTimer: ReturnType<typeof setTimeout> | undefined;
+  private clearResetTimer() {
+    if (this.resetTimer !== undefined) {
+      clearTimeout(this.resetTimer);
+      this.resetTimer = undefined;
+    }
+  }
+  private settle(result: CopyState) {
+    this.state = result;
+    this.announced = result;
+    this.clearResetTimer();
+    this.resetTimer = setTimeout(() => this.reset(), RESET_MS);
+  }
+  copy = (_e: Event) => {
+    let text = this.text;
+    if (text == null) {
+      return;
+    }
+    // a repeat copy clears the region first, so the result is announced
+    // again, and disarms the last result's reset so the glyph holds until
+    // this one settles
+    let attempt = ++this.attempt;
+    this.clearResetTimer();
+    this.announced = 'idle';
+    // absent outside a secure context, and writeText can throw synchronously
+    let write: Promise<void>;
+    try {
+      write = navigator.clipboard.writeText(text);
+    } catch (error) {
+      write = Promise.reject(error);
+    }
+    write.then(
+      () => {
+        if (attempt === this.attempt) {
+          this.settle('copied');
+        }
+      },
+      (error: unknown) => {
+        if (attempt === this.attempt) {
+          this.settle('failed');
+        }
+        console.error(error instanceof Error ? error.message : error);
+      },
+    );
+  };
+  reset = () => {
+    this.clearResetTimer();
+    this.state = 'idle';
+    this.announced = 'idle';
+  };
+  <template>
+    <IconButton
+      @label={{this.label}}
+      @tone={{@tone}}
+      @appearance={{@appearance}}
+      @variant={{@variant}}
+      @size={{@size}}
+      @disabled={{@disabled}}
+      data-state={{this.dataState}}
+      {{on 'click' this.copy}}
+      data-test-pretui-copy-button
+      ...attributes
+    >
+      {{! all three glyphs stay in the DOM and cross-fade, so the result
+          both enters and leaves smoothly; the copy glyph sets the size }}
+      <span
+        class='pretui-copy-glyphs'
+        data-glyph={{this.glyph}}
+        data-test-pretui-copy-button-glyph
+      >
+        <CopyIcon
+          class='pretui-copy-glyph pretui-copy-idle'
+          width={{ICON_SIZE}}
+          height={{ICON_SIZE}}
+        />
+        <CheckIcon
+          class='pretui-copy-glyph pretui-copy-check'
+          width={{ICON_SIZE}}
+          height={{ICON_SIZE}}
+        />
+        <XIcon
+          class='pretui-copy-glyph pretui-copy-failed'
+          width={{ICON_SIZE}}
+          height={{ICON_SIZE}}
+        />
+      </span>
+    </IconButton>
+    {{! outside the button, whose children are presentational; always rendered
+        so assistive tech is already watching it when the text arrives }}
+    <VisuallyHidden
+      role='status'
+      data-test-pretui-copy-button-status
+    >{{this.statusText}}</VisuallyHidden>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-copy-glyphs {
+          position: relative;
+          display: inline-flex;
+        }
+        .pretui-copy-glyph {
+          scale: 0.25;
+          opacity: 0;
+          filter: blur(4px);
+        }
+        .pretui-copy-check,
+        .pretui-copy-failed {
+          position: absolute;
+          inset: 0;
+        }
+        .pretui-copy-glyphs[data-glyph='copy'] .pretui-copy-idle,
+        .pretui-copy-glyphs[data-glyph='check'] .pretui-copy-check,
+        .pretui-copy-glyphs[data-glyph='cross'] .pretui-copy-failed {
+          scale: 1;
+          opacity: 1;
+          filter: blur(0);
+        }
+        @media (prefers-reduced-motion: no-preference) {
+          .pretui-copy-glyph {
+            transition-property: scale, opacity, filter;
+            transition-duration: 300ms;
+            transition-timing-function: cubic-bezier(0.2, 0, 0, 1);
+          }
+        }
+        .pretui-copy-check {
+          color: var(--success-ink);
+        }
+        .pretui-copy-failed {
+          color: var(--destructive-ink);
+        }
+        /* an -ink tone loses contrast on a fill (the cross on a filled hover
+           surface measures under 3:1), so there the glyph keeps the fill's
+           own text color and its shape carries the result */
+        [data-appearance='accent'] .pretui-copy-check,
+        [data-appearance='accent'] .pretui-copy-failed,
+        [data-appearance='filled'] .pretui-copy-check,
+        [data-appearance='filled'] .pretui-copy-failed,
+        [data-appearance='filled-outlined'] .pretui-copy-check,
+        [data-appearance='filled-outlined'] .pretui-copy-failed {
+          color: inherit;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/copy-button.md

@@ -0,0 +1,71 @@
+## What it is
+
+An **IconButton** that copies a string to the clipboard, swaps its glyph to a check (or a cross when the copy fails), and announces the result to screen readers. Use it next to any value a user will want to paste elsewhere — an id, a URL, an API key, a **Token**. If the thing to copy is a whole block of code, put one of these in its corner rather than making the block clickable. If the action is "share" rather than "copy", that is a **Menu** or a **Popover**.
+
+## The contract
+
+```
+@text: string | null | undefined   (required; aliases @value, and @textToCopy as boxel-ui spells it)
+@label?   (default 'Copy to clipboard'; alias @ariaLabel as boxel-ui spells it)
+@tone?, @appearance?   (IconButton's; default 'neutral' / 'outlined')
+@variant?   (deprecated sugar over @tone + @appearance)
+@size?: 'xs' | 's' | 'm' | 'l' | 'xl'   (default 'm'; the glyph scales with it)
+@disabled?
+Element: HTMLButtonElement
+```
+
+**`@text` accepts null and undefined and no-ops on them.** That is deliberate: the value being copied usually comes from a field that may not be set, and the alternative — a button that copies the string "undefined" — is worse than one that does nothing.
+
+**The result holds for 2 seconds, whatever the input.** Two seconds is where the field has settled (Web Awesome 1 s, Chakra 1.5 s, Mantine, shadcn and GitHub's clipboard-copy 2 s, Ant 3 s). A timer is the one reset, so mouse, keyboard and touch all see the same thing, and a keyboard user, whose focus stays on the button, is not left with a stale check.
+
+**`@label` is the accessible name, and it does not change with the result.** It flows into IconButton's `@label`, so it is applied as both `aria-label` and `title`. The result is written into a `role="status"` region, a **VisuallyHidden**, instead: 'Copied', or 'Copy failed'.
+
+**A failed copy is shown, not just logged.** `navigator.clipboard.writeText` rejects in insecure contexts, without permission, and when the document is not focused. The button then shows a cross in `--destructive-ink`, sets `data-state="failed"`, announces 'Copy failed', and logs the error to the console.
+
+**The status region renders after the button, as a sibling.** A button's children are presentational, so a live region inside it would not be announced. The region is absolutely positioned and 1px, so it takes no space in flex, grid or inline layout, but a caller's `:last-child` selector will match it rather than the button. ButtonGroup matches its children by class, so a CopyButton at either end of a group still gets the group's outer corners.
+
+## Prior art
+
+**Web Awesome `wa-copy-button`** is the fullest: `value`, `from` (copy from another element's property or attribute by id), `copy-label` / `success-label` / `error-label`, `feedback-duration` (default 1000ms), `tooltip-placement`, and separate `copy-icon` / `success-icon` / `error-icon` slots — plus a real error state when the clipboard API rejects. **shadcn** has no copy button; it is a docs recipe with `useState` and a `setTimeout`.
+
+**boxel-ui's own copy-button rides Tooltip via ember-velcro's wormhole**, which is on this kit's wart list — the portal escapes the theme island — so this is a fresh implementation rather than a wrap.
+
+### Differences from boxel-ui CopyButton
+
+- **No styled tooltip**, so `@tooltipText`, `@placement` and `@offset` are not accepted. The native `title` tooltip shows `@label`, and the glyph swap shows the result.
+- **The result holds for 2 seconds** on every input, with no pointer or focus reset (above).
+- **The accessible name stays fixed.** boxel-ui swaps `aria-label` to 'Copied', which a screen reader does not announce; here the status region announces it.
+- **`@width` / `@height` are not accepted.** The glyph follows `@size`.
+- **The root element is the button**, not a Tooltip wrapper, so `...attributes` land on the button.
+
+Where Pretui differs and is arguably ahead: **the result is announced and the name stays fixed** (below), and a repeat copy is announced again. The 2-second hold itself is the field's standard, not a difference.
+
+Where it is behind, plainly:
+
+- **No `from` equivalent** — you must have the string, not a reference to an element.
+- **The status text is fixed** ('Copied', 'Copy failed'); there is no `copy-label` / `success-label` / `error-label` equivalent.
+
+## Accessibility
+
+No APG pattern; a native `<button>`. Space and Enter both activate.
+
+What is right:
+
+- **The result is announced.** A polite `role="status"` region, rendered from the start so assistive tech is already watching it, receives 'Copied' or 'Copy failed'.
+- **The accessible name is stable**, so a voice-control command such as "click copy to clipboard" keeps working after a copy. The glyphs sit inside IconButton's `aria-hidden` face, so the SVGs contribute nothing.
+- **The reset is a timer, not a focus change**, so a keyboard user who keeps focus on the button sees the check clear like everyone else. The reset empties the region, which announces nothing.
+
+Gaps and cautions:
+
+- **A repeat copy is announced again**: each click empties the region before the clipboard write, and the result lands after it; the glyph keeps the last result meanwhile, so nothing flickers. A result that arrives after the pointer or focus has already left is dropped, so nothing is shown or announced for a button the user is no longer on.
+- **`title` is inherited from IconButton** and duplicates the `aria-label`, with the usual double-announcement risk.
+- **The check is `--success-ink` and the cross `--destructive-ink`**, the hue tokens meant for ink on a neutral surface. On a fill (`accent`, `filled`, `filled-outlined`) they lose contrast, the cross on a filled hover surface measures under 3:1, so there the glyph keeps the fill's own text color. The shape change (clipboard → check or cross) carries the result without color, which satisfies **WCAG 1.4.1**.
+- Target size is IconButton's 28×28, clearing WCAG 2.5.8's minimum narrowly.
+
+## Theming
+
+`--success-ink` (the check) and `--destructive-ink` (the cross) plus **IconButton**'s and **Button**'s full token set for the button itself — `--pretui-tone`/`--pretui-tone-on` per tone, `--radius`, `--hover`, `--border`, `--control-h`.
+
+The three glyphs stay in the DOM and cross-fade (scale, opacity and blur over 300 ms) when the state changes, so the result both enters and leaves smoothly; under `prefers-reduced-motion: reduce` the swap is instant. `data-state="copied"` or `data-state="failed"` is reflected on the button, so a stylesheet can dress the confirmed state beyond the glyph swap — a tinted background, for example — without touching the component. That is the intended extension point, and it is worth using: a glyph-only-by-default confirmation on a 28px button is easy to miss.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.