@lovett/ui 0.0.10 → 0.0.11

package/src/metric-card.tsx

@@ -11,9 +11,17 @@
  * Token discipline: all colors via public tokens. Tone variant gives
  * the value text an accent/success/warning/destructive/info color;
  * background is always neutral surface-overlay.
+ *
+ * `copyable` (ADR-145 amendment, 2026-09-04): the card becomes a button
+ * that copies `copyValue` (or the string `value`) and toasts
+ * "Copied <label>". Same hover/focus affordance as ValueChip and the
+ * copyable StatRow. Inert by default so a read-only KPI never advertises
+ * an interaction it doesn't have.
  */
 
 import type { ReactNode } from 'react'
+import { cn } from './lib/utils'
+import { copyText } from './lib/clipboard'
 
 export type MetricCardTone = 'neutral' | 'accent' | 'success' | 'warning' | 'destructive' | 'info'
 
@@ -46,6 +54,11 @@ export interface MetricCardProps {
   labelPosition?: 'top' | 'bottom'
   /** Optional className override for the outer container. */
   className?: string
+  /** Make the whole card a copy-to-clipboard button. */
+  copyable?: boolean
+  /** What a copyable card writes. Defaults to `value` when it is a string;
+   *  REQUIRED when `value` is a node (there is nothing else to copy). */
+  copyValue?: string
 }
 
 export function MetricCard({
@@ -55,6 +68,8 @@ export function MetricCard({
   icon,
   labelPosition = 'bottom',
   className,
+  copyable = false,
+  copyValue,
 }: MetricCardProps) {
   const labelEl =
     labelPosition === 'top' ? (
@@ -89,29 +104,49 @@ export function MetricCard({
     </div>
   )
 
+  const body =
+    labelPosition === 'top' ? (
+      <>
+        {labelEl}
+        {valueEl}
+      </>
+    ) : (
+      <>
+        {valueEl}
+        {labelEl}
+      </>
+    )
+  const surfaceClass = className ?? 'flex flex-col gap-1 px-4 py-3 border'
+  const surfaceStyle = {
+    background: 'rgb(var(--surface-overlay-soft))',
+    borderColor: 'rgb(var(--border))',
+    borderRadius: 'var(--radius-lg)',
+  } as const
+
+  const text = copyValue ?? (typeof value === 'string' ? value : undefined)
+  if (copyable && text !== undefined) {
+    return (
+      <button
+        type="button"
+        onClick={() => void copyText(text, label)}
+        title={`Copy ${label}`}
+        aria-label={`Copy ${label}: ${text}`}
+        className={cn(
+          surfaceClass,
+          'text-left cursor-pointer transition-[border-color,box-shadow]',
+          'hover:border-[rgb(var(--border-strong))] hover:[box-shadow:var(--shadow-sm)]',
+          'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+        )}
+        style={surfaceStyle}
+      >
+        {body}
+      </button>
+    )
+  }
+
   return (
-    <div
-      className={
-        className ??
-        'flex flex-col gap-1 px-4 py-3 border'
-      }
-      style={{
-        background: 'rgb(var(--surface-overlay-soft))',
-        borderColor: 'rgb(var(--border))',
-        borderRadius: 'var(--radius-lg)',
-      }}
-    >
-      {labelPosition === 'top' ? (
-        <>
-          {labelEl}
-          {valueEl}
-        </>
-      ) : (
-        <>
-          {valueEl}
-          {labelEl}
-        </>
-      )}
+    <div className={surfaceClass} style={surfaceStyle}>
+      {body}
     </div>
   )
 }

package/src/modal.tsx

@@ -10,6 +10,8 @@ import {
 } from 'react'
 import { X } from 'lucide-react'
 import { cn } from './lib/utils'
+import { tabbablesWithin } from './lib/focus'
+import { useLayer } from './lib/layer-stack'
 
 /**
  * Modal — a centered floating panel on top of a backdrop. Built on
@@ -56,47 +58,25 @@ import { cn } from './lib/utils'
  * the `.cs-frame`-scoped token layer and out of their current stacking /
  * inheritance context, which is a much larger change than an a11y fix
  * should make. Inerting `document.body`'s other children is also wrong:
- * `DropdownMenu`, `TagChipInput` and `FolderTreePicker` portal their
- * content THERE, so a select inside a modal would go dead. Focus trap it
- * is — the keyboard hole is closed; pointer and AT virtual-cursor access
+ * `DropdownMenu`, `Popover`, `TagChipInput` and `FolderTreePicker` portal
+ * their content THERE, so a select inside a modal would go dead. Focus trap
+ * it is — the keyboard hole is closed; pointer and AT virtual-cursor access
  * to the background remains, which is the documented residual.
+ *
+ * Escape and dismiss order come from the shared layer stack
+ * (`lib/layer-stack.ts`): the topmost open surface — modal, menu or
+ * popover — answers Escape alone.
  */
 
 /**
- * Open panels, outermost first. Only the topmost one answers Escape and
- * owns the tab ring, so nested modals do not both close on one Escape
- * and do not fight over focus.
- */
-const openPanels: HTMLElement[] = []
-
-/**
- * Tabbable candidates. Deliberately attribute-only — no geometry check.
- * `offsetWidth` / `getClientRects()` are always zero in jsdom, so a
- * visibility filter would empty this list under test and silently
- * disable the trap in exactly the environment that verifies it.
+ * Dismiss order lives in the shared layer stack (`lib/layer-stack.ts`),
+ * which this file used to own as a module-level `openPanels` array. Only
+ * the topmost layer answers Escape, so nested modals do not both close on
+ * one keypress — and now a DropdownMenu or Popover opened from inside a
+ * modal closes on its own first, leaving the modal open. The Tab trap asks
+ * for the topmost MODAL (`isTopOfKind`), so a popover above it does not
+ * switch the trap off.
  */
-const FOCUSABLE_SELECTOR = [
-  'a[href]',
-  'area[href]',
-  'button:not([disabled])',
-  'input:not([disabled]):not([type="hidden"])',
-  'select:not([disabled])',
-  'textarea:not([disabled])',
-  'iframe',
-  'summary',
-  '[contenteditable="true"]',
-  '[tabindex]',
-].join(',')
-
-function tabbablesWithin(panel: HTMLElement): HTMLElement[] {
-  return Array.from(panel.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
-    (el) =>
-      el.tabIndex >= 0 &&
-      !el.hasAttribute('inert') &&
-      el.getAttribute('aria-hidden') !== 'true' &&
-      !el.closest('[hidden]'),
-  )
-}
 
 interface ModalProps {
   isOpen: boolean
@@ -130,13 +110,10 @@ function Modal({ isOpen, onClose, title, children, className, ariaLabel }: Modal
         ? document.activeElement
         : null
 
-    openPanels.push(panel)
     const initial = panel.querySelector<HTMLElement>('[data-autofocus]')
     ;(initial ?? panel).focus()
 
     return () => {
-      const at = openPanels.indexOf(panel)
-      if (at !== -1) openPanels.splice(at, 1)
       // Restoring is the half that gets forgotten: without it, closing a
       // modal drops the caret to <body> and the next Tab restarts from
       // the top of the page.
@@ -144,21 +121,27 @@ function Modal({ isOpen, onClose, title, children, className, ariaLabel }: Modal
     }
   }, [isOpen])
 
-  // Escape + tab trap. One document listener; the topmost-panel guard
-  // keeps nested modals from both reacting.
+  // Escape: the shared stack dispatches it to the topmost layer only, and
+  // reads `onClose` through a ref so an inline arrow does not re-register
+  // (or reorder) the layer on every render.
+  const layer = useLayer({
+    enabled: isOpen,
+    kind: 'modal',
+    elementRef: panelRef,
+    onEscape: () => onClose(),
+  })
+
+  // Tab trap. One document listener; the topmost-MODAL guard keeps nested
+  // modals from both reacting, and keeps this trap live while a popover
+  // sits above it.
   useEffect(() => {
     if (!isOpen) return
     const panel = panelRef.current
     if (!panel) return
 
     const handleKeyDown = (e: KeyboardEvent) => {
-      if (openPanels[openPanels.length - 1] !== panel) return
-
-      if (e.key === 'Escape') {
-        onClose()
-        return
-      }
       if (e.key !== 'Tab') return
+      if (!layer.isTopOfKind()) return
 
       const active = document.activeElement
       // Focus is outside the panel — almost always a body-level portal
@@ -199,7 +182,7 @@ function Modal({ isOpen, onClose, title, children, className, ariaLabel }: Modal
 
     document.addEventListener('keydown', handleKeyDown)
     return () => document.removeEventListener('keydown', handleKeyDown)
-  }, [isOpen, onClose])
+  }, [isOpen, layer])
 
   if (!isOpen) return null
 

package/src/popover.tsx

@@ -0,0 +1,407 @@
+/**
+ * Popover — an anchored, non-modal floating surface with focus management.
+ *
+ * Compound: `<Popover>` (state) + `<Popover.Trigger>` + `<Popover.Content>`.
+ * Controlled (`open` + `onOpenChange`) or uncontrolled (`defaultOpen`).
+ * Content portals to `document.body`, positions through
+ * `useAnchoredPosition` (flip + clamp), enters with `.ds-enter-pop` once
+ * positioned, and registers on the shared dismiss-layer stack — so Escape
+ * closes ONLY the topmost surface (a Popover inside a Modal closes before
+ * the Modal does) and an outside pointerdown closes it unless the pointer
+ * landed in a layer stacked above (a Select opened from inside it).
+ *
+ * Focus: opening moves focus into the content — the `[data-autofocus]`
+ * control if one is marked, else the first tabbable, else the content
+ * itself (`tabIndex={-1}`) — once the content is POSITIONED, not on the
+ * first frame: that frame is parked off-screen with `visibility: hidden`,
+ * and no browser will focus into a hidden subtree (the call is a silent
+ * no-op). Closing returns focus to the trigger, EXCEPT
+ * after an outside click, where the user has already put focus where they
+ * want it and yanking it back to the trigger would be wrong.
+ *
+ * Promoted per ADR-0030 Decision G (meta-ads-audit-dashboard task manager:
+ * the row / card / context-menu / palette pickers all sit in a popover with
+ * search + live counts). Second consumer is the workspace app, which has
+ * three hand-rolled popovers today (sidebar user menu, group-settings
+ * colour and icon pickers, CalculatorShell's AssumptionsPopover) — each a
+ * migration target. DropdownMenu stays a sibling on the same hook and stack
+ * rather than a Popover child: a menu does NOT move focus into itself on
+ * open, and 137 call sites depend on that.
+ *
+ * Trigger is an unstyled `<button type="button">` by default — Popover is a
+ * generic surface, the caller chooses the trigger's look. Pass `asChild` to
+ * make the single child element the trigger instead (a `<Button>`, a table
+ * cell, a chip): it receives the ref, the click handler and the ARIA
+ * attributes, and the DOM stays one element. The child must be keyboard-
+ * operable ON ITS OWN: Trigger adds ARIA + click only, no role, tabIndex or
+ * key handler. A native `<button>` / `<a href>` already is; a `<td>` or
+ * `<span>` needs `role="button"`, `tabIndex={0}` and its own Enter / Space
+ * handling, or only mouse users can open the popover.
+ *
+ * Content is `role="dialog"` (non-modal — no `aria-modal`) and needs a name
+ * from the caller (`aria-label` / `aria-labelledby`). Pass `role="none"`
+ * when the content IS the widget (a listbox, a menu) and would otherwise
+ * nest roles.
+ *
+ * Token discipline: the surface reads the INTERNAL `--popover` /
+ * `--popover-foreground` (allowed in packages/ui, ESLint-enforced elsewhere)
+ * plus public `--border`, `--shadow-lg`, `--radius-lg`. Geometry comes from
+ * the hook; motion from `.ds-enter-pop` (`--dur-fast` / `--ease-out`, honours
+ * prefers-reduced-motion in styles.css). No hex, no raw px in classes.
+ *
+ * Usage:
+ *
+ *   <Popover>
+ *     <Popover.Trigger asChild>
+ *       <Button variant="secondary">Assignee</Button>
+ *     </Popover.Trigger>
+ *     <Popover.Content aria-label="Pick an assignee" align="start">
+ *       <input data-autofocus placeholder="Search people…" />
+ *       …
+ *     </Popover.Content>
+ *   </Popover>
+ *
+ *   // Virtual anchor (ContextMenu later): no Trigger, position at a point.
+ *   <Popover open={!!point} onOpenChange={…} anchorRect={point}>
+ *     <Popover.Content role="none">…</Popover.Content>
+ *   </Popover>
+ */
+
+import {
+  cloneElement,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type CSSProperties,
+  type HTMLAttributes,
+  type MouseEvent as ReactMouseEvent,
+  type ReactNode,
+  type Ref,
+  type RefObject,
+} from 'react'
+import { createPortal } from 'react-dom'
+import { cn } from './lib/utils'
+import { composeRefs } from './lib/refs'
+import { tabbablesWithin } from './lib/focus'
+import { useLayer } from './lib/layer-stack'
+import {
+  useAnchoredPosition,
+  useOutsideClick,
+  type AnchorAlign,
+  type AnchorRect,
+  type AnchorSide,
+} from './lib/anchor'
+
+/**
+ * The popover surface chrome, shared with DropdownMenuContent so a menu and
+ * a popover read as the same family. Inline rather than a stylesheet class
+ * because the surface tokens are internal and the primitives already own
+ * them here (Kbd, DropdownMenu follow the same pattern).
+ */
+export const POPOVER_SURFACE_STYLE: CSSProperties = {
+  background: 'rgb(var(--popover))',
+  color: 'rgb(var(--popover-foreground))',
+  border: '1px solid rgb(var(--border))',
+  boxShadow: 'var(--shadow-lg)',
+}
+
+interface PopoverContextValue {
+  open: boolean
+  setOpen: (next: boolean) => void
+  triggerRef: RefObject<HTMLElement | null>
+  contentId: string
+  anchorRect: AnchorRect | null
+  /** Set when the close came from an outside pointerdown; skips focus return. */
+  interactedOutsideRef: RefObject<boolean>
+}
+
+const PopoverCtx = createContext<PopoverContextValue | null>(null)
+
+function usePopoverCtx(consumer: string): PopoverContextValue {
+  const ctx = useContext(PopoverCtx)
+  if (!ctx) {
+    throw new Error(
+      `${consumer} must be rendered inside <Popover>. ` +
+        `Wrap your trigger + content with the Popover root component.`,
+    )
+  }
+  return ctx
+}
+
+export interface PopoverProps {
+  /** Controlled open state. Omit for internal state. */
+  open?: boolean
+  defaultOpen?: boolean
+  /** Fires whenever open transitions. */
+  onOpenChange?: (open: boolean) => void
+  /**
+   * Virtual anchor. When non-null, Content positions against this rect
+   * instead of the Trigger — a right-click point, a caret, a cell.
+   */
+  anchorRect?: AnchorRect | null
+  children: ReactNode
+}
+
+function PopoverRoot({
+  open: controlledOpen,
+  defaultOpen,
+  onOpenChange,
+  anchorRect = null,
+  children,
+}: PopoverProps) {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(Boolean(defaultOpen))
+  const isControlled = controlledOpen !== undefined
+  const open = isControlled ? Boolean(controlledOpen) : uncontrolledOpen
+  const triggerRef = useRef<HTMLElement | null>(null)
+  const interactedOutsideRef = useRef(false)
+  const generatedId = useId()
+  const contentId = `popover-${generatedId.replace(/:/g, '')}`
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!isControlled) setUncontrolledOpen(next)
+      onOpenChange?.(next)
+    },
+    [isControlled, onOpenChange],
+  )
+
+  const value = useMemo<PopoverContextValue>(
+    () => ({ open, setOpen, triggerRef, contentId, anchorRect, interactedOutsideRef }),
+    [open, setOpen, contentId, anchorRect],
+  )
+
+  return <PopoverCtx.Provider value={value}>{children}</PopoverCtx.Provider>
+}
+
+export interface PopoverTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * Render the single child element as the trigger instead of a `<button>`.
+   * The child receives the ref, click handler and ARIA attributes; the DOM
+   * stays one element. It must be focusable and keyboard-operable on its
+   * own (a `<button>`, an `<a href>`, or `role="button"` + `tabIndex={0}` +
+   * Enter / Space handling): Trigger adds no role, tabIndex or key handler.
+   */
+  asChild?: boolean
+}
+
+type TriggerChildProps = HTMLAttributes<HTMLElement> & {
+  ref?: Ref<HTMLElement>
+  'data-state'?: string
+}
+
+const PopoverTrigger = forwardRef<HTMLButtonElement, PopoverTriggerProps>(
+  function PopoverTrigger({ asChild, onClick, children, ...rest }, forwardedRef) {
+    const { open, setOpen, triggerRef, contentId } = usePopoverCtx('Popover.Trigger')
+
+    const ariaProps = {
+      'aria-haspopup': 'dialog',
+      'aria-expanded': open,
+      'aria-controls': open ? contentId : undefined,
+      'data-state': open ? 'open' : 'closed',
+    } as const
+
+    if (asChild) {
+      if (!isValidElement<TriggerChildProps>(children)) {
+        throw new Error('Popover.Trigger with `asChild` expects exactly one element child.')
+      }
+      const child = children
+      const childOnClick = child.props.onClick
+      return cloneElement(child, {
+        ...rest,
+        ...ariaProps,
+        ref: composeRefs<HTMLElement>(child.props.ref, forwardedRef, triggerRef),
+        onClick: (event: ReactMouseEvent<HTMLElement>) => {
+          childOnClick?.(event)
+          onClick?.(event as ReactMouseEvent<HTMLButtonElement>)
+          if (!event.defaultPrevented) setOpen(!open)
+        },
+      })
+    }
+
+    return (
+      <button
+        ref={composeRefs<HTMLElement>(forwardedRef, triggerRef)}
+        type="button"
+        {...ariaProps}
+        onClick={(event) => {
+          onClick?.(event)
+          if (!event.defaultPrevented) setOpen(!open)
+        }}
+        {...rest}
+      >
+        {children}
+      </button>
+    )
+  },
+)
+
+export interface PopoverContentProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'role' | 'children'> {
+  children: ReactNode
+  /** Preferred side of the anchor. Default `bottom`. Flips when it cannot fit. */
+  side?: AnchorSide
+  /** Alignment along the anchor's cross axis. Default `start`. */
+  align?: AnchorAlign
+  /** Gap from the anchor, px. Default 6. */
+  offset?: number
+  /** Shift along the alignment axis, px. Default 0. */
+  alignOffset?: number
+  /** Default true. */
+  flip?: boolean
+  /** Default true. */
+  clampToViewport?: boolean
+  /**
+   * `dialog` (default) — a named, non-modal dialog; give it `aria-label` or
+   * `aria-labelledby`. `none` — no role attribute, for content that is
+   * itself the widget.
+   */
+  role?: 'dialog' | 'none'
+  /** Skip the surface chrome (background / border / shadow / radius / padding). */
+  unstyled?: boolean
+}
+
+const PopoverContent = forwardRef<HTMLDivElement, PopoverContentProps>(
+  function PopoverContent(
+    {
+      children,
+      side = 'bottom',
+      align = 'start',
+      offset = 6,
+      alignOffset = 0,
+      flip = true,
+      clampToViewport = true,
+      role = 'dialog',
+      unstyled,
+      className,
+      style,
+      ...rest
+    },
+    forwardedRef,
+  ) {
+    const { open, setOpen, triggerRef, contentId, anchorRect, interactedOutsideRef } =
+      usePopoverCtx('Popover.Content')
+    const contentRef = useRef<HTMLDivElement | null>(null)
+
+    const {
+      ref: positionRef,
+      style: positionStyle,
+      placement,
+      positioned,
+    } = useAnchoredPosition<HTMLDivElement>({
+      anchorRef: triggerRef,
+      anchorRect,
+      side,
+      align,
+      offset,
+      alignOffset,
+      flip,
+      clampToViewport,
+      enabled: open,
+    })
+
+    const layer = useLayer({
+      enabled: open,
+      kind: 'popover',
+      elementRef: contentRef,
+      onEscape: () => setOpen(false),
+    })
+
+    useOutsideClick(
+      [triggerRef, contentRef],
+      () => {
+        interactedOutsideRef.current = true
+        setOpen(false)
+      },
+      { enabled: open, layer },
+    )
+
+    // Focus in once the content is POSITIONED, back to the trigger on close.
+    // Not on `open`: the first open frame is the parked one (off-screen,
+    // `visibility: hidden`), and Chromium, Firefox and WebKit all refuse to
+    // focus into a visibility:hidden subtree, so a focus() there is a silent
+    // no-op and focus stays on the trigger. `positioned` flips true in the
+    // re-render the measuring layout effect triggers, after the parked frame
+    // has already flushed its passive effects. jsdom does not enforce the
+    // rule, which is why the test records `data-positioned` at focus time.
+    // Keyed on state, not an inline callback, so `onOpenChange` identity
+    // churn never re-runs it mid-interaction.
+    useEffect(() => {
+      if (!open || !positioned) return
+      const node = contentRef.current
+      if (!node) return
+      interactedOutsideRef.current = false
+      // Captured now, not in the cleanup: the trigger does not change while
+      // the popover is open, and a remounted one would be disconnected.
+      const trigger = triggerRef.current
+      const previous =
+        document.activeElement instanceof HTMLElement &&
+        document.activeElement !== document.body
+          ? document.activeElement
+          : null
+      const initial =
+        node.querySelector<HTMLElement>('[data-autofocus]') ??
+        tabbablesWithin(node)[0] ??
+        node
+      initial.focus()
+
+      return () => {
+        if (interactedOutsideRef.current) return
+        // The content is gone by now, so a focus that was inside it has
+        // already fallen to <body>. Anything else means the user moved on.
+        const active = document.activeElement
+        if (active !== null && active !== document.body && !node.contains(active)) return
+        const target = trigger ?? previous
+        if (target?.isConnected) target.focus()
+      }
+    }, [open, positioned, triggerRef, interactedOutsideRef])
+
+    const ref = useMemo(
+      () => composeRefs<HTMLDivElement>(forwardedRef, contentRef, positionRef),
+      [forwardedRef, positionRef],
+    )
+
+    if (!open || typeof document === 'undefined') return null
+
+    return createPortal(
+      <div
+        ref={ref}
+        id={contentId}
+        role={role === 'none' ? undefined : role}
+        tabIndex={-1}
+        data-slot="popover-content"
+        data-state="open"
+        data-side={placement?.side}
+        data-align={placement?.align}
+        data-positioned={positioned ? 'true' : 'false'}
+        className={cn(
+          'fixed z-[100] outline-none',
+          !unstyled && 'rounded-[var(--radius-lg)] p-3',
+          positioned && 'ds-enter-pop',
+          className,
+        )}
+        style={{
+          ...positionStyle,
+          ...(unstyled ? undefined : POPOVER_SURFACE_STYLE),
+          ...style,
+        }}
+        {...rest}
+      >
+        {children}
+      </div>,
+      document.body,
+    )
+  },
+)
+
+export const Popover = Object.assign(PopoverRoot, {
+  Trigger: PopoverTrigger,
+  Content: PopoverContent,
+})