@lovett/ui 0.0.9 → 0.0.11

package/src/lib/layer-stack.ts

@@ -0,0 +1,188 @@
+/**
+ * Dismiss-layer stack — the ONE "topmost layer wins" registry shared by
+ * Modal, DropdownMenu and Popover (and, next, ContextMenu / Select /
+ * Combobox / Tooltip / CommandPalette).
+ *
+ * Extracted from modal.tsx's module-level `openPanels` array so every
+ * dismissable surface participates in the same order. Before this, a
+ * DropdownMenu opened from inside a Modal answered Escape at the same time
+ * the Modal did — two document listeners, one keypress, both closed. Now a
+ * single document `keydown` listener dispatches Escape to the top of the
+ * stack ONLY, then stops propagation so window-level handlers (the chat
+ * conversation drawer's Escape, lens hotkey maps) do not treat a consumed
+ * Escape as theirs — which is what DropdownMenu's own listener already did.
+ *
+ * Promoted per ADR-0030 Decision G (meta-ads-audit-dashboard task manager:
+ * every picker, sheet and palette needs one dismiss order). First consumer
+ * is the workspace app: Modal (51 files), DropdownMenu (137 call sites) and
+ * Popover all register here.
+ *
+ * Two kinds. A `modal` layer also owns a focus trap, and that trap must not
+ * switch off because a `popover` opened above it — so Modal asks
+ * `isTopOfKind()` for Tab handling while Escape always goes to `isTop()`.
+ * Order is push order, which under React is effect order: a surface that
+ * mounts or opens later sits above one that opened earlier.
+ *
+ * Usage (a dismissable surface):
+ *
+ *   const layer = useLayer({
+ *     enabled: open,
+ *     kind: 'popover',
+ *     elementRef: contentRef,
+ *     onEscape: () => setOpen(false),
+ *   })
+ *   useOutsideClick([triggerRef, contentRef], () => setOpen(false), {
+ *     enabled: open,
+ *     layer, // clicks inside a layer stacked ABOVE this one are not "outside"
+ *   })
+ *
+ * `useEscapeKey(handler, { enabled })` is the one-liner for anything that
+ * only needs Escape.
+ */
+
+import { useEffect, useMemo, useRef, type RefObject } from 'react'
+
+export type LayerKind = 'modal' | 'popover'
+
+export interface LayerHandle {
+  /** True while no layer of ANY kind sits above this one. */
+  isTop(): boolean
+  /** True while no layer of the SAME kind sits above this one. */
+  isTopOfKind(): boolean
+  /**
+   * True when `node` is inside the element of a layer stacked above this
+   * one — a nested Select's listbox, a Combobox inside a Popover. Outside-
+   * click handlers treat those as inside.
+   */
+  containsInLayerAbove(node: Node): boolean
+}
+
+interface LayerRecord {
+  readonly kind: LayerKind
+  readonly element: () => HTMLElement | null
+  readonly onEscape: (event: KeyboardEvent) => void
+}
+
+const stack: LayerRecord[] = []
+let listening = false
+
+function onDocumentKeyDown(event: KeyboardEvent): void {
+  if (event.key !== 'Escape') return
+  const top = stack[stack.length - 1]
+  if (!top) return
+  // Consumed here. Window-level listeners (hotkey maps, drawers) must not
+  // see an Escape that closed a layer — same contract DropdownMenu's own
+  // listener had before the stack existed.
+  event.stopPropagation()
+  top.onEscape(event)
+}
+
+function pushLayer(record: LayerRecord): () => void {
+  stack.push(record)
+  if (!listening) {
+    document.addEventListener('keydown', onDocumentKeyDown)
+    listening = true
+  }
+  return () => {
+    const at = stack.lastIndexOf(record)
+    if (at !== -1) stack.splice(at, 1)
+    if (stack.length === 0 && listening) {
+      document.removeEventListener('keydown', onDocumentKeyDown)
+      listening = false
+    }
+  }
+}
+
+export interface UseLayerOptions {
+  /** Register while true; pop when it turns false or the owner unmounts. */
+  enabled: boolean
+  kind: LayerKind
+  /**
+   * The surface's root element. Read lazily, so a ref that is filled in
+   * after the layer registers (portal content) still resolves.
+   */
+  elementRef?: RefObject<HTMLElement | null>
+  /** Called when this layer is topmost and Escape is pressed. */
+  onEscape: (event: KeyboardEvent) => void
+}
+
+/**
+ * Register a dismiss layer for as long as `enabled` holds. `onEscape` is
+ * read through a ref, so an inline arrow does not re-register the layer
+ * (and does not reorder it) on every render.
+ */
+export function useLayer(options: UseLayerOptions): LayerHandle {
+  const { enabled, kind, elementRef, onEscape } = options
+
+  const onEscapeRef = useRef(onEscape)
+  useEffect(() => {
+    onEscapeRef.current = onEscape
+  })
+
+  const recordRef = useRef<LayerRecord | null>(null)
+
+  useEffect(() => {
+    if (!enabled) return
+    const record: LayerRecord = {
+      kind,
+      element: () => elementRef?.current ?? null,
+      onEscape: (event) => onEscapeRef.current(event),
+    }
+    recordRef.current = record
+    const pop = pushLayer(record)
+    return () => {
+      pop()
+      if (recordRef.current === record) recordRef.current = null
+    }
+  }, [enabled, kind, elementRef])
+
+  return useMemo<LayerHandle>(
+    () => ({
+      isTop: () => {
+        const record = recordRef.current
+        return record !== null && stack[stack.length - 1] === record
+      },
+      isTopOfKind: () => {
+        const record = recordRef.current
+        if (!record) return false
+        for (let i = stack.length - 1; i >= 0; i--) {
+          const layer = stack[i]
+          if (layer === record) return true
+          if (layer?.kind === record.kind) return false
+        }
+        return false
+      },
+      containsInLayerAbove: (node) => {
+        const record = recordRef.current
+        if (!record) return false
+        const at = stack.indexOf(record)
+        if (at === -1) return false
+        for (let i = at + 1; i < stack.length; i++) {
+          if (stack[i]?.element()?.contains(node)) return true
+        }
+        return false
+      },
+    }),
+    [],
+  )
+}
+
+export interface UseEscapeKeyOptions {
+  /** Default true. */
+  enabled?: boolean
+  /** Default `popover`. */
+  kind?: LayerKind
+}
+
+/**
+ * Escape-only participant in the layer stack. Fires `onEscape` only while
+ * this is the topmost layer; a layer that opens later takes over until it
+ * closes.
+ */
+export function useEscapeKey(
+  onEscape: (event: KeyboardEvent) => void,
+  options: UseEscapeKeyOptions = {},
+): LayerHandle {
+  const { enabled = true, kind = 'popover' } = options
+  return useLayer({ enabled, kind, onEscape })
+}

package/src/lib/refs.ts

@@ -0,0 +1,31 @@
+/**
+ * Ref plumbing for primitives that must hand one DOM node to several
+ * owners — the caller's forwarded ref, the component's own ref, and a
+ * positioning hook's callback ref.
+ *
+ * `assignRef` writes a node into any React ref shape. `composeRefs` returns
+ * ONE callback ref that fans out to all of them; memoize the result
+ * (`useMemo` on the inputs) so React does not detach/re-attach on every
+ * render.
+ */
+
+import type { Ref, RefCallback } from 'react'
+
+export function assignRef<T>(ref: Ref<T> | undefined, node: T | null): void {
+  if (!ref) return
+  if (typeof ref === 'function') {
+    // React 19 callback refs may return a cleanup; we call with `null` on
+    // detach instead, which every consumer of this package already handles.
+    ref(node)
+    return
+  }
+  ref.current = node
+}
+
+export function composeRefs<T>(
+  ...refs: ReadonlyArray<Ref<T> | undefined>
+): RefCallback<T> {
+  return (node) => {
+    for (const ref of refs) assignRef(ref, node)
+  }
+}

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

@@ -2,12 +2,16 @@ import {
   Children,
   isValidElement,
   useEffect,
+  useId,
+  useRef,
   type HTMLAttributes,
   type ReactElement,
   type ReactNode,
 } 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
@@ -36,6 +40,42 @@ import { cn } from './lib/utils'
  *            <Button>Confirm</Button>
  *          </Modal.Footer>
  *        </Modal>
+ *
+ * Accessibility. The panel is a `role="dialog" aria-modal="true"` region
+ * named by its own `<h2>` (`aria-labelledby`), or by the `ariaLabel` prop
+ * when a caller renders a titleless modal. Opening moves focus to the
+ * panel — so a screen reader announces the dialog's name — and closing
+ * RESTORES focus to whatever was focused before it opened. Tab and
+ * Shift+Tab wrap inside the panel; Escape closes.
+ *
+ * Callers that want a specific control focused on open mark it
+ * `data-autofocus`; anything else and the panel itself takes focus.
+ *
+ * WHY A FOCUS TRAP AND NOT `inert` ON THE APP ROOT. Modal renders INLINE
+ * in the React tree — it is a descendant of `#root`, not a portal — so
+ * `inert` on the app root would make the modal itself inert. Portaling it
+ * to `document.body` to unlock that would move all 59 consuming files off
+ * 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`, `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.
+ */
+
+/**
+ * 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.
  */
 
 interface ModalProps {
@@ -43,18 +83,106 @@ interface ModalProps {
   onClose: () => void
   title: string
   children: ReactNode
-  className?: string
+  className?: string | undefined
+  /**
+   * Accessible name for a modal rendered with an empty `title`. Ignored
+   * when `title` is non-empty — the `<h2>` names the dialog then.
+   */
+  ariaLabel?: string | undefined
 }
 
-function Modal({ isOpen, onClose, title, children, className }: ModalProps) {
+function Modal({ isOpen, onClose, title, children, className, ariaLabel }: ModalProps) {
+  const panelRef = useRef<HTMLDivElement | null>(null)
+  const titleId = useId()
+
+  // Focus: move in on open, restore on close. Keyed on `isOpen` ALONE —
+  // adding `onClose` here would re-run it on every render for the many
+  // callers that pass an inline arrow, snatching focus back to the panel
+  // mid-keystroke.
   useEffect(() => {
     if (!isOpen) return
-    const handleEscape = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') onClose()
+    const panel = panelRef.current
+    if (!panel) return
+
+    const previous =
+      document.activeElement instanceof HTMLElement &&
+      document.activeElement !== document.body
+        ? document.activeElement
+        : null
+
+    const initial = panel.querySelector<HTMLElement>('[data-autofocus]')
+    ;(initial ?? panel).focus()
+
+    return () => {
+      // 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.
+      if (previous && previous.isConnected) previous.focus()
     }
-    document.addEventListener('keydown', handleEscape)
-    return () => document.removeEventListener('keydown', handleEscape)
-  }, [isOpen, onClose])
+  }, [isOpen])
+
+  // 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 (e.key !== 'Tab') return
+      if (!layer.isTopOfKind()) return
+
+      const active = document.activeElement
+      // Focus is outside the panel — almost always a body-level portal
+      // (DropdownMenu / TagChipInput / FolderTreePicker) opened FROM the
+      // modal. Wrapping it back in would break that menu's own keyboard
+      // handling, so leave the event alone.
+      if (!(active instanceof HTMLElement) || !panel.contains(active)) return
+
+      const tabbables = tabbablesWithin(panel)
+      const first = tabbables[0]
+      const last = tabbables[tabbables.length - 1]
+      if (!first || !last) {
+        // Nothing to land on — keep focus on the panel rather than let
+        // Tab walk out into the page behind the backdrop.
+        e.preventDefault()
+        panel.focus()
+        return
+      }
+
+      // The panel holds focus itself right after open. Forward Tab can
+      // fall through to `first` naturally; Shift+Tab would leave the
+      // dialog, so it wraps to `last`.
+      if (active === panel) {
+        if (e.shiftKey) {
+          e.preventDefault()
+          last.focus()
+        }
+        return
+      }
+      if (e.shiftKey && active === first) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown)
+    return () => document.removeEventListener('keydown', handleKeyDown)
+  }, [isOpen, layer])
 
   if (!isOpen) return null
 
@@ -69,8 +197,17 @@ function Modal({ isOpen, onClose, title, children, className }: ModalProps) {
       {/* Outer card — uses .ds-card-surface so the modal gets the
          same chrome as cards (border + multi-layer shadow + inner
          highlight in light mode). overflow-hidden clips children to
-         the rounded corners; the tray inside handles its own scroll. */}
+         the rounded corners; the tray inside handles its own scroll.
+
+         tabIndex={-1} makes the panel programmatically focusable so it
+         can receive focus on open without joining the tab ring. */}
       <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={title ? titleId : undefined}
+        aria-label={title ? undefined : ariaLabel}
+        tabIndex={-1}
         data-framed="true"
         className={cn(
           'ds-card-surface relative w-full max-w-2xl flex flex-col max-h-[90vh] overflow-hidden',
@@ -89,7 +226,10 @@ function Modal({ isOpen, onClose, title, children, className }: ModalProps) {
            than the text, the BUTTON set the row height and the title
            floated in slack it never asked for. */}
         <div className="flex items-center justify-between gap-3 shrink-0 px-4 py-3">
-          <h2 className="text-[15px] font-bold tracking-[-0.01em] text-[rgb(var(--foreground))]">
+          <h2
+            id={titleId}
+            className="text-[15px] font-bold tracking-[-0.01em] text-[rgb(var(--foreground))]"
+          >
             {title}
           </h2>
           <button

package/src/page-shell.tsx

@@ -10,6 +10,7 @@ import {
 } from 'react'
 import { createPortal } from 'react-dom'
 import { Link } from 'react-router-dom'
+import { House } from 'lucide-react'
 import { cn } from './lib/utils'
 
 export type Crumb = {
@@ -60,7 +61,24 @@ interface PageShellProps {
 // per mount, never per render).
 // ---------------------------------------------------------------------------
 
+/**
+ * The app's home destination, rendered as the first breadcrumb.
+ *
+ * PER-APP AND OPT-IN, which is the whole reason it lives on the provider
+ * instead of being hardcoded in `Breadcrumbs`. `PageShell` is shared: the
+ * workspace and `apps/approvals` both render it, and approvals has no
+ * `/clients` route — a hardcoded home would have shipped it a dead link on
+ * every page. An app that wants a home crumb says where home is; an app that
+ * does not gets no icon and nothing breaks.
+ */
+export interface HomeCrumb {
+  to: string
+  /** Accessible name for the icon-only link, e.g. "Clients". */
+  label: string
+}
+
 interface PageHeaderSlotValue {
+  home: HomeCrumb | null
   hostEl: HTMLElement | null
   centerEl: HTMLElement | null
   scrollEl: HTMLElement | null
@@ -71,7 +89,14 @@ interface PageHeaderSlotValue {
 
 const PageHeaderSlotContext = createContext<PageHeaderSlotValue | null>(null)
 
-export function PageHeaderSlotProvider({ children }: { children: ReactNode }) {
+export function PageHeaderSlotProvider({
+  children,
+  home = null,
+}: {
+  children: ReactNode
+  /** Where the leading home crumb points. Omit to render no home crumb. */
+  home?: HomeCrumb | null
+}) {
   const [hostEl, setHostEl] = useState<HTMLElement | null>(null)
   const [centerEl, setCenterEl] = useState<HTMLElement | null>(null)
   const [scrollEl, setScrollEl] = useState<HTMLElement | null>(null)
@@ -84,6 +109,7 @@ export function PageHeaderSlotProvider({ children }: { children: ReactNode }) {
   return (
     <PageHeaderSlotContext.Provider
       value={{
+        home,
         hostEl,
         centerEl,
         scrollEl,
@@ -375,6 +401,50 @@ export function PageHeaderHost({
   )
 }
 
+/**
+ * The app's home destination, or null when the app has not declared one.
+ *
+ * Exported because not every breadcrumb in the app goes through `PageShell` —
+ * the Generate lens renders its own trail beside an editable project title —
+ * and those forks should read the same destination rather than each hardcoding
+ * a path that then drifts.
+ */
+export function useBreadcrumbHome(): HomeCrumb | null {
+  return useContext(PageHeaderSlotContext)?.home ?? null
+}
+
+/**
+ * The leading home crumb: an icon, not a word.
+ *
+ * WHY AN ICON REPLACES THE FIRST CRUMB RATHER THAN SITTING BESIDE IT. Thirty-one
+ * lens trails already began `Clients / …` pointing at `/clients`, which is
+ * exactly where home goes — so rendering both would put the same destination on
+ * screen twice in a row, once as a picture and once as a word. The icon takes
+ * that crumb's place when they agree and prepends when they do not (the tools
+ * trails start at `/tools`), so "first position" holds either way.
+ *
+ * It carries an `aria-label` and a `title`: an icon-only link has no accessible
+ * name otherwise, and the tooltip is what tells a first-time user that the house
+ * means the client list rather than some other notion of home.
+ */
+export function HomeCrumbLink({ home }: { home: HomeCrumb }) {
+  return (
+    <Link
+      to={home.to}
+      aria-label={home.label}
+      title={home.label}
+      className="shrink-0 flex items-center transition-colors hover:text-[rgb(var(--foreground))]"
+      style={{ color: 'inherit' }}
+    >
+      {/* 15px beside 13px crumb text, at the 1.9 stroke the theme toggle in
+          this same header band uses — the app's chrome runs heavier than
+          Lucide's default, and matching the neighbour matters more than the
+          generic rule. */}
+      <House className="h-[15px] w-[15px]" strokeWidth={1.9} aria-hidden="true" />
+    </Link>
+  )
+}
+
 function Breadcrumbs({
   parents,
   current,
@@ -382,12 +452,31 @@ function Breadcrumbs({
   parents: Crumb[]
   current: Crumb | undefined
 }) {
+  const home = useBreadcrumbHome()
+  // When the first crumb already IS home, the icon stands in for it rather
+  // than duplicating it. Compared by destination, not by label, because the
+  // label varies ("Clients", a brand name) while the route does not.
+  const visibleParents =
+    home && parents[0]?.to === home.to ? parents.slice(1) : parents
+
   return (
     <nav
       className="flex items-center gap-1.5 text-[13px] min-w-0"
       style={{ color: 'rgb(var(--text-tertiary))' }}
     >
-      {parents.map((c, i) => (
+      {home && (
+        <>
+          <HomeCrumbLink home={home} />
+          {/* Separator only when something follows it. A page with no crumbs
+              at all would otherwise render a dangling "home /". */}
+          {(visibleParents.length > 0 || current) && (
+            <span className="shrink-0" style={{ color: 'rgb(var(--text-muted))' }}>
+              /
+            </span>
+          )}
+        </>
+      )}
+      {visibleParents.map((c, i) => (
         <span key={i} className="flex items-center gap-1.5 min-w-0">
           {c.to ? (
             <Link