@lovett/ui 0.0.9 → 0.0.11

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,
+})

package/src/segmented-pill.tsx

@@ -9,12 +9,20 @@
  *   │ └──────────────┘                                              │
  *   ╰──────────────────────────────────────────────────────────────╯
  *
- *   • Whole strip sits in a subtle `--surface-overlay-soft` rounded
- *     container so the inactive segments read as text rather than
- *     borderless buttons.
- *   • The active segment is wrapped in a 1px accent border with an
- *     `--accent-subtle` fill — reads as an "outlined pill" sitting
- *     inside the strip.
+ *   • The track is an OPAQUE recessed well (`--surface-frame`) so the
+ *     inactive segments read as text rather than borderless buttons.
+ *   • The active segment steps UP off the track: an opaque
+ *     `--surface-card` fill sandwiched between the track and a 1px
+ *     accent border, plus `--shadow-sm`. It reads as a raised pill,
+ *     not a tinted one.
+ *
+ *   Both were translucent until 2026-08-30 (`--surface-overlay-soft`
+ *   track, `--accent-subtle` pill). Stacked, they composited to a 245
+ *   pill inside a 247 track in light mode — the active segment was
+ *   DARKER than the thing it sits in, so the raised element read as
+ *   recessed and the control looked washed out. Opaque surfaces cannot
+ *   invert like that, because their relationship does not depend on
+ *   whatever happens to be behind them.
  *   • Each segment is a button with an optional leading icon.
  *
  * Generic — accepts a typed `items` array. First consumer: Keywords
@@ -79,7 +87,14 @@ export function SegmentedPill<Id extends string = string>({
         className,
       )}
       style={{
-        background: 'rgb(var(--surface-overlay-soft))',
+        // OPAQUE. This was --surface-overlay-soft, a translucent tint, with a
+        // translucent --accent-subtle pill on top of it — two alpha layers
+        // stacked. In light that composited to a 245 pill inside a 247 strip:
+        // the ACTIVE segment rendered DARKER than the track it sits in, so the
+        // raised element read as recessed and the whole control looked washed
+        // out. --surface-frame is the recessed-well token and is darker than
+        // --surface-card in BOTH themes, so the direction holds either way.
+        background: 'rgb(var(--surface-frame))',
         border: '1px solid rgb(var(--border))',
         borderRadius: 'var(--radius-full)',
       }}
@@ -110,9 +125,17 @@ export function SegmentedPill<Id extends string = string>({
               borderRadius: 'var(--radius-full)',
               ...(isActive
                 ? {
-                    background: 'rgb(var(--accent-subtle))',
+                    // The active segment STEPS UP off the track: an opaque
+                    // surface sandwiched between the accent border and the
+                    // strip, plus a small shadow. --surface-card is +8 on the
+                    // frame in light and +6 in dark, so it reads raised in both.
+                    background: 'rgb(var(--surface-card))',
                     border: '1px solid rgb(var(--accent))',
-                    color: 'rgb(var(--accent))',
+                    // --accent-ink, not --accent: the brand red is 5.64:1 on a
+                    // light card but 3.05:1 on a dark one, i.e. an accent LABEL
+                    // fails AA in dark. --accent-ink is the theme-tuned form.
+                    color: 'rgb(var(--accent-ink))',
+                    boxShadow: 'var(--shadow-sm)',
                   }
                 : {
                     background: 'transparent',
@@ -126,7 +149,7 @@ export function SegmentedPill<Id extends string = string>({
                 className="inline-flex shrink-0"
                 style={{
                   color: isActive
-                    ? 'rgb(var(--accent))'
+                    ? 'rgb(var(--accent-ink))'
                     : 'rgb(var(--text-muted))',
                 }}
                 aria-hidden="true"