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

package/bundled-realms/pretui/components/hover-actions.md

@@ -0,0 +1,55 @@
+## What it is
+
+The action cluster that appears on a row, card or cell — edit, duplicate, delete — folded into an overflow when there are too many.
+
+## The contract
+
+```
+@actions?  — the cluster's actions. Omit to supply the <:actions> block instead
+@label (required) — the toolbar's accessible name, and it must say WHICH thing
+           the actions act on
+@maxVisible? — total control budget; anything past it folds into an overflow Menu
+@reveal?   — 'hover' (default) | 'always'
+@space?    — 'overlay' (default) floats the cluster inside the host's own bounds;
+             'reserve' gives it a real grid column so it can never cover content
+@placement? — corner the cluster occupies in overlay mode. Default 'top-end'
+@size?     — size scale for the cluster's buttons. Default 's'
+@onSelect? — fires for every action, inline or overflow, after its own handler
+
+<:default> the host: the row, card or cell the actions belong to
+<:actions> custom cluster contents, replacing @actions
+```
+
+**`@label` must name the thing, not the cluster.** "Actions for Q3 roadmap", not "Actions" — fifty rows of identically-named toolbars is a list a reader cannot navigate. The contract states this because it is the arg most likely to be filled in lazily.
+
+**Coarse pointers get `always` for free.** Hover is not an input on a touchscreen, and a hover-only affordance is simply missing there — so the component does not wait to be told.
+
+**Both modes are layout-stable.** That is the actual requirement: `overlay` satisfies it for free because it is out of flow, and `reserve` satisfies it by giving the cluster a real column. The choice between them is whether covering content is acceptable, not whether the row will jump.
+
+**Overlay is the default because a permanently empty gutter fails the still-frame test** — at rest it is dead space that earns nothing. Choose `reserve` for dense text rows, where an overlay would sit on the words; keep `overlay` for tiles, media and any host with its own padding.
+
+**Roving tabindex applies only to the `@actions` path.** The component cannot know what is inside `<:actions>`, so a block-supplied cluster keeps its members as ordinary tab stops — and once you open that block, the host content must move into an explicit `<:default>`.
+
+## Prior art
+
+The row-hover action cluster in every table and list implementation.
+
+Where Pretui is better: the naming requirement stated in the type, the touch behaviour handled rather than left to a media query at the call site, and the honest note about what the block gives up.
+
+Where it is thinner: no keyboard-only reveal distinct from focus, no per-action disabled state beyond what the action carries, and no drag affordance.
+
+## Accessibility
+
+- **A named toolbar per row is the whole design.** The name is what makes fifty clusters navigable rather than fifty identical ones.
+- **Roving tabindex on the `@actions` path** keeps a long list from becoming hundreds of tab stops — and its absence in the block path is documented rather than silently different.
+- **Hover-revealed controls are focus-revealed too**, or they would be unreachable by keyboard.
+- **Touch gets `always`**, because a hover affordance on a touchscreen does not exist.
+- **`reserve` can never cover content**, which is the mode to choose when the row's own text matters more than density.
+
+## Theming
+
+The cluster takes the kit's control tokens at `@size`, defaulting to the small scale; overlay and reserve differ in layout rather than in treatment.
+
+Keeping both modes on one token set means a product can switch a table from overlay to reserve for density reasons without the buttons changing appearance.
+
+The styles sit in `@layer PretComposite`, above Button's `PretComponent` layer, so what this component sets on Button wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.

package/bundled-realms/pretui/components/hover-actions.usage.gts

@@ -0,0 +1,224 @@
+// Pretui — HoverActions usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import type { PretuiSize } from '../pretui-primitives';
+import { HoverActions } from './hover-actions';
+import type { HoverAction } from './hover-actions';
+import { SIZES } from '../internal/toggle-controls-fixtures';
+
+// ── HoverActions ← listing-hover-card + catalog-image-overlay ────────────
+class HoverActionsUsage extends Component {
+  sizes = SIZES;
+  spaces = ['overlay', 'reserve'];
+  placements = ['top-start', 'top-end', 'bottom-start', 'bottom-end'];
+  reveals = ['hover', 'always'];
+
+  @tracked space = 'overlay';
+  @tracked placement = 'top-end';
+  @tracked reveal = 'hover';
+  @tracked maxVisible = 3;
+  @tracked sizeName = 's';
+  @tracked fired = 'nothing yet';
+
+  setSpace = (v: string) => (this.space = v);
+  setPlacement = (v: string) => (this.placement = v);
+  setReveal = (v: string) => (this.reveal = v);
+  setMaxVisible = (v: number | null) => (this.maxVisible = v ?? 0);
+  setSize = (v: string) => (this.sizeName = v);
+
+  note = (id: string) => {
+    this.fired = id;
+  };
+
+  actions: HoverAction[] = [
+    { id: 'preview', label: 'Preview', icon: 'eye', onSelect: () => this.note('preview') },
+    { id: 'edit', label: 'Edit', icon: 'pencil', onSelect: () => this.note('edit') },
+    { id: 'duplicate', label: 'Duplicate', icon: 'copy', onSelect: () => this.note('duplicate') },
+    { id: 'link', label: 'Copy link', icon: 'link', onSelect: () => this.note('link') },
+    {
+      id: 'remove',
+      label: 'Delete',
+      icon: 'circle-minus',
+      destructive: true,
+      onSelect: () => this.note('remove'),
+    },
+  ];
+
+  get spaceVal() {
+    return this.space as 'overlay' | 'reserve';
+  }
+  get placementVal() {
+    return this.placement as 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+  }
+  get revealVal() {
+    return this.reveal as 'hover' | 'always';
+  }
+  get sizeVal() {
+    return this.sizeName as PretuiSize;
+  }
+  get usage() {
+    let bits = ["@label='Actions for Q3 roadmap'", '@actions={{this.actions}}'];
+    if (this.space !== 'overlay') bits.push(`@space='${this.space}'`);
+    if (this.maxVisible) bits.push(`@maxVisible={{${this.maxVisible}}}`);
+    return `<HoverActions ${bits.join(' ')}>…</HoverActions>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='HoverActions'
+      @description="An action cluster over a row, card or cell. The reason it is not trivial: hover-only actions do not exist on a touchscreen and are a keyboard tax everywhere else. So the reveal is hover OR focus-within in pure CSS, coarse pointers get the cluster pinned on with no JS, the cluster is a toolbar with roving tabindex — one tab stop per host rather than one per button — Escape hands focus back to the host, and anything past the control budget folds into the kit's Menu instead of being dropped by a container query. Sourced from listing-hover-card, whose no-portal absolute-inset approach is kept wholesale, and catalog-image-overlay, which is the cautionary half."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='ha-demo-grid'>
+          <HoverActions
+            class='ha-demo-tile'
+            @label='Actions for Q3 roadmap'
+            @actions={{this.actions}}
+            @space={{this.spaceVal}}
+            @placement={{this.placementVal}}
+            @reveal={{this.revealVal}}
+            @maxVisible={{this.maxVisible}}
+            @size={{this.sizeVal}}
+          >
+            <h4 class='ha-demo-title'>Q3 roadmap</h4>
+            <p class='ha-demo-body'>
+              Twelve initiatives across four teams. Hover or tab in to reach
+              the actions; arrows move between them, Escape returns to the
+              tile.
+            </p>
+          </HoverActions>
+          <HoverActions
+            class='ha-demo-tile'
+            @label='Actions for Pricing experiments'
+            @actions={{this.actions}}
+            @space={{this.spaceVal}}
+            @placement={{this.placementVal}}
+            @reveal={{this.revealVal}}
+            @maxVisible={{this.maxVisible}}
+            @size={{this.sizeVal}}
+          >
+            <h4 class='ha-demo-title'>Pricing experiments</h4>
+            <p class='ha-demo-body'>
+              Every tile names its own toolbar, so a list of fifty does not
+              announce fifty identical ones.
+            </p>
+          </HoverActions>
+        </div>
+        <p class='pretui-demo-readout' data-test-ha-readout>
+          last action = {{this.fired}}
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='actions'
+          @description='The cluster contents: id, a required label, an optional icon-registry name, disabled and destructive flags, and onSelect. The label is required because an icon-only control with no name is not a control — the source used arrow characters as button text, which announce as their Unicode names.'
+          @value={{this.actions}}
+        />
+        <Args.String
+          @name='label'
+          @required={{true}}
+          @defaultValue='Actions for Q3 roadmap'
+          @description='The toolbar name, and it must say which thing the actions act on. Fifty rows of identically-named toolbars is a list nobody can navigate.'
+        />
+        <Args.Number
+          @name='maxVisible'
+          @defaultValue={{0}}
+          @value={{this.maxVisible}}
+          @min={{0}}
+          @max={{5}}
+          @description='Total control budget. Past it, the remainder folds into an overflow Menu — and the menu trigger counts against the budget, which is the arithmetic most implementations get wrong.'
+          @onInput={{this.setMaxVisible}}
+        />
+        <Args.String
+          @name='space'
+          @defaultValue='overlay'
+          @value={{this.space}}
+          @options={{this.spaces}}
+          @description='Overlay floats the cluster inside the host bounds; reserve gives it a real grid column. Both are layout-stable, which is what layout stability actually asks for. Overlay is the default because a permanently empty gutter fails the still-frame test; choose reserve for dense text rows, where an overlay would sit on the words.'
+          @onInput={{this.setSpace}}
+        />
+        <Args.String
+          @name='placement'
+          @defaultValue='top-end'
+          @value={{this.placement}}
+          @options={{this.placements}}
+          @description='Which corner the cluster occupies in overlay mode. Written with logical properties, so RTL is free.'
+          @onInput={{this.setPlacement}}
+        />
+        <Args.String
+          @name='reveal'
+          @defaultValue='hover'
+          @value={{this.reveal}}
+          @options={{this.reveals}}
+          @description='Hover reveals on hover or focus-within; always keeps the cluster on, which is what dense lists want. Coarse pointers get always for free — hover is not an input on a touchscreen.'
+          @onInput={{this.setReveal}}
+        />
+        <Args.String
+          @name='size'
+          @defaultValue='s'
+          @value={{this.sizeName}}
+          @options={{this.sizes}}
+          @description='Scale for the cluster buttons.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Action
+          @name='onSelect'
+          @description='Fires for every action, inline or overflow, after that action own onSelect.'
+        />
+        <Args.Yield
+          @name='actions'
+          @description='Custom cluster contents replacing the actions array. Roving tabindex applies only to the array path — the component cannot know what is inside a block. Opening this block moves the host content into an explicit default block.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-hoveractions-gap'
+          @type='length'
+          @description='Space between cluster members, and between the host and a reserved cluster.'
+        />
+        <Css.Basic
+          @name='pretui-hoveractions-inset'
+          @type='length'
+          @description='Distance from the host edge in overlay mode.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .ha-demo-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr));
+        gap: 12px;
+      }
+      .ha-demo-tile {
+        padding: 14px;
+        border-radius: var(--radius);
+        background: var(--card);
+        box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+      }
+      .ha-demo-title {
+        margin: 0 0 6px;
+        font-size: var(--text-ui-md, 12.5px);
+        font-weight: 600;
+        color: var(--foreground);
+      }
+      .ha-demo-body {
+        margin: 0;
+        font-size: var(--text-ui-xs, 11px);
+        line-height: 1.5;
+        color: var(--muted-foreground);
+      }
+      .pretui-demo-readout {
+        margin: 12px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_HOVER_ACTIONS: Record<string, unknown> = {
+  HoverActions: HoverActionsUsage,
+};

package/bundled-realms/pretui/components/hover-card.gts

@@ -0,0 +1,347 @@
+// Pretui — HoverCard: a rich preview that opens on hover or focus.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { guidFor } from '@ember/object/internals';
+import { modifier } from 'ember-modifier';
+import { Popup } from './popup';
+import type { PopupPlacement } from '../internal/overlay';
+import { OwnedTimers, listenDocument, listenDocumentCapture, ownsTimers } from '../focus';
+import { controlIn } from '../internal/overlay-confirm';
+
+// ─────────────────────────────────────────────────────────────────────────
+// HoverCard
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface HoverCardSignature {
+  Args: {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** default 'bottom-start' */
+    placement?: PopupPlacement;
+    /** gap between trigger and card, px (default 8) */
+    distance?: number;
+    /**
+     * Seconds of hover before the card opens (default 0.5). Seconds, not the
+     * `700` Radix passes — a bare number in a prop is a unit no caller can
+     * check.
+     */
+    openDelay?: number;
+    /** Seconds after the pointer leaves before it closes (default 0.3). The
+     * pair matters more than either value: the close delay is the bridge
+     * across the gap between trigger and card. */
+    closeDelay?: number;
+    /** accessible name for the card (default 'Preview') */
+    label?: string;
+    /** on coarse pointers a tap opens the card, since hover does not exist
+     * there at all (default true) */
+    tapToOpen?: boolean;
+  };
+  Blocks: {
+    trigger: [];
+    default: [close: () => void];
+  };
+  Element: HTMLSpanElement;
+}
+
+/**
+ * The rich link/user preview: a `Popup` with hover intent in front of it.
+ *
+ * ── Accessibility is the whole problem ──────────────────────────────────
+ *
+ * Content that only appears on hover is content a keyboard user, a screen
+ * reader user and every touch device cannot reach. The three fixes, in the
+ * order they matter:
+ *
+ *  1. **Focus opens it, with no delay.** A hover delay exists to stop the card
+ *     firing as the pointer crosses the link; a keyboard user who has
+ *     deliberately tabbed to the trigger has already expressed the intent, so
+ *     making them wait half a second is pure latency.
+ *  2. **The content is not a keyboard trap, and not a dead end either.**
+ *     Radix's HoverCard sets `tabindex='-1'` on every tabbable node inside the
+ *     card — which does prevent a trap, at the price of making the card's own
+ *     links unreachable by the exact users who most needed them reachable.
+ *     Here the card renders in DOM order immediately after the trigger and
+ *     keeps its tab stops, so Tab walks *into* it, Tab out of the last one
+ *     leaves and closes it, and Escape closes it and returns focus to the
+ *     trigger. Nothing is unreachable and nothing is inescapable.
+ *  3. **Touch gets a path at all.** Radix explicitly excludes touch from
+ *     opening, so on a phone the card simply does not exist. `@tapToOpen`
+ *     opens it on a non-mouse pointer without swallowing the trigger's own
+ *     activation, so a link stays a link.
+ *
+ * The trigger's control also carries `aria-expanded` and `aria-controls` — a
+ * relationship neither Radix nor shadcn establishes, so in those kits a
+ * screen-reader user is not told the preview exists even when it is open.
+ *
+ * ── Timers ──────────────────────────────────────────────────────────────
+ *
+ * The two delays are `OwnedTimers` handles: an `ember-modifier` adopts the
+ * set and releases it in its destructor, each handle is one-shot, and opening
+ * cancels the close handle and vice versa, so neither can re-arm. Where the
+ * modifier has not installed, `OwnedTimers` schedules nothing and the card
+ * degrades to opening and closing immediately — a working behaviour, not a
+ * broken one.
+ */
+export class HoverCard extends Component<HoverCardSignature> {
+  private guid = guidFor(this);
+  private timers = new OwnedTimers();
+  private openHandle: ReturnType<typeof setTimeout> | undefined;
+  private closeHandle: ReturnType<typeof setTimeout> | undefined;
+  private triggerControl: HTMLElement | undefined;
+  private hostEl: HTMLElement | undefined;
+  private restoringFocus = false;
+
+  @tracked private internalOpen = this.args.defaultOpen ?? false;
+
+  get isOpen(): boolean {
+    return this.args.open ?? this.internalOpen;
+  }
+  get panelId(): string {
+    return this.guid + '-card';
+  }
+  get panelLabel(): string {
+    return this.args.label ?? 'Preview';
+  }
+  get placement(): PopupPlacement {
+    return this.args.placement ?? 'bottom-start';
+  }
+  private get openMs(): number {
+    return Math.max(0, (this.args.openDelay ?? 0.5) * 1000);
+  }
+  private get closeMs(): number {
+    return Math.max(0, (this.args.closeDelay ?? 0.3) * 1000);
+  }
+
+  private setOpen(next: boolean) {
+    if (this.args.open === undefined) {
+      this.internalOpen = next;
+    }
+    this.args.onOpenChange?.(next);
+  }
+
+  private clearHandles() {
+    this.timers.cancel(this.openHandle);
+    this.timers.cancel(this.closeHandle);
+    this.openHandle = undefined;
+    this.closeHandle = undefined;
+  }
+
+  /** Opens after `openDelay`, or immediately when `immediate` (focus, touch)
+   * or when no modifier has taken timer ownership. */
+  private wantOpen(immediate: boolean) {
+    this.clearHandles();
+    if (this.isOpen) {
+      return;
+    }
+    if (immediate || this.openMs === 0 || !this.timers.active) {
+      this.setOpen(true);
+      return;
+    }
+    this.openHandle = this.timers.after(this.openMs, () => {
+      this.openHandle = undefined;
+      this.setOpen(true);
+    });
+  }
+
+  private wantClose(immediate: boolean) {
+    this.clearHandles();
+    if (!this.isOpen) {
+      return;
+    }
+    if (immediate || this.closeMs === 0 || !this.timers.active) {
+      this.setOpen(false);
+      return;
+    }
+    this.closeHandle = this.timers.after(this.closeMs, () => {
+      this.closeHandle = undefined;
+      this.setOpen(false);
+    });
+  }
+
+  /** Closes and puts focus back on the trigger. Every dismissal path a
+   * keyboard reader can take goes through here. */
+  close = () => {
+    this.clearHandles();
+    this.setOpen(false);
+    this.restoringFocus = true;
+    try {
+      this.triggerControl?.focus();
+    } finally {
+      this.restoringFocus = false;
+    }
+  };
+
+  onPointerEnter = (event: Event) => {
+    let ev = event as PointerEvent;
+    if (ev.pointerType === 'touch' || ev.pointerType === 'pen') {
+      if (this.args.tapToOpen ?? true) {
+        this.wantOpen(true);
+      }
+      return;
+    }
+    this.wantOpen(false);
+  };
+
+  onPointerLeave = (event: Event) => {
+    let ev = event as PointerEvent;
+    if (ev.pointerType === 'touch' || ev.pointerType === 'pen') {
+      return;
+    }
+    this.wantClose(false);
+  };
+
+  onFocusIn = () => {
+    // the focus close() puts back on the trigger is not a request to reopen
+    if (this.restoringFocus) {
+      return;
+    }
+    this.wantOpen(true);
+  };
+
+  onFocusOut = (event: Event) => {
+    let to = (event as FocusEvent).relatedTarget;
+    if (to instanceof Node && this.hostEl?.contains(to)) {
+      return;
+    }
+    this.wantClose(true);
+  };
+
+  onEscape = (event: Event) => {
+    let ev = event as KeyboardEvent;
+    if (ev.key !== 'Escape' || !this.isOpen) {
+      return;
+    }
+    ev.preventDefault();
+    ev.stopPropagation();
+    this.close();
+  };
+
+  /** Touch dismissal: a tap outside closes what a tap opened. */
+  onDocumentPointerDown = (event: Event) => {
+    if (!this.isOpen) {
+      return;
+    }
+    let target = event.target as Node | null;
+    if (target && this.hostEl?.contains(target)) {
+      return;
+    }
+    this.wantClose(true);
+  };
+
+  captureHost = modifier((el: HTMLElement) => {
+    this.hostEl = el;
+    let enter = (event: Event) => this.onPointerEnter(event);
+    let leave = (event: Event) => this.onPointerLeave(event);
+    let focusIn = () => this.onFocusIn();
+    let focusOut = (event: Event) => this.onFocusOut(event);
+    el.addEventListener('pointerenter', enter);
+    el.addEventListener('pointerleave', leave);
+    el.addEventListener('focusin', focusIn);
+    el.addEventListener('focusout', focusOut);
+    return () => {
+      el.removeEventListener('pointerenter', enter);
+      el.removeEventListener('pointerleave', leave);
+      el.removeEventListener('focusin', focusIn);
+      el.removeEventListener('focusout', focusOut);
+      this.hostEl = undefined;
+      this.clearHandles();
+    };
+  });
+
+  captureTrigger = modifier((el: HTMLElement) => {
+    this.triggerControl = controlIn(el);
+  });
+
+  triggerBehavior = modifier(
+    (el: HTMLElement, [isOpen, panelId]: [boolean, string]) => {
+      let control = controlIn(el);
+      control.setAttribute('aria-expanded', isOpen ? 'true' : 'false');
+      // the panel only exists while open, so point at it only then
+      if (isOpen) {
+        control.setAttribute('aria-controls', panelId);
+      } else {
+        control.removeAttribute('aria-controls');
+      }
+      return () => {
+        control.removeAttribute('aria-expanded');
+        control.removeAttribute('aria-controls');
+      };
+    },
+  );
+
+  <template>
+    <span
+      class='pretui-hc'
+      data-test-pretui-hovercard
+      data-state={{if this.isOpen 'open' 'closed'}}
+      {{this.captureHost}}
+      {{ownsTimers this.timers}}
+      ...attributes
+    >
+      <Popup
+        @open={{this.isOpen}}
+        @placement={{this.placement}}
+        @distance={{if @distance @distance 8}}
+      >
+        <:anchor>
+          <span
+            class='pretui-hc-trigger'
+            {{this.captureTrigger}}
+            {{this.triggerBehavior this.isOpen this.panelId}}
+          >{{yield to='trigger'}}</span>
+        </:anchor>
+        <:default>
+          <div
+            class='pretui-hc-panel'
+            id={{this.panelId}}
+            role='dialog'
+            aria-label={{this.panelLabel}}
+            data-test-pretui-hovercard-panel
+            {{listenDocumentCapture 'keydown' this.onEscape}}
+            {{listenDocument 'pointerdown' this.onDocumentPointerDown true}}
+          >
+            {{yield this.close}}
+          </div>
+        </:default>
+      </Popup>
+    </span>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-hc {
+          display: inline-flex;
+        }
+        .pretui-hc-trigger {
+          display: inline-flex;
+        }
+        .pretui-hc-panel {
+          background: var(--popover);
+          color: var(--popover-foreground);
+          border-radius: var(--radius-surface, 10px);
+          box-shadow: var(--pretui-shadow-overlay, 0 0 0 1px var(--border), 0 8px 28px rgb(0 0 0 / 0.16));
+          padding: var(--space-4, 11px);
+          width: var(--pretui-hovercard-width, 260px);
+          max-width: calc(100vw - 16px);
+          font-family: var(--font-sans);
+          font-size: var(--text-ui-md, 12.5px);
+          opacity: 1;
+          transform: none;
+          transition: opacity var(--pretui-dur-enter, 180ms) var(--pretui-ease-enter, cubic-bezier(0.23, 1, 0.32, 1)),
+            transform var(--pretui-dur-enter, 180ms) var(--pretui-ease-enter, cubic-bezier(0.23, 1, 0.32, 1));
+        }
+        @starting-style {
+          .pretui-hc-panel {
+            opacity: 0;
+            transform: translateY(4px) scale(0.98);
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-hc-panel {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}