@lovett/ui 0.0.10 → 0.0.11

package/src/dropdown-menu.tsx

@@ -8,45 +8,75 @@
  * BUILD_FRESH per ADR-025 DEVIATION-3: source ships on
  * `@base-ui/react/menu`, which is NOT in CLAUDE.md §1 allowed deps.
  * The compound-component surface (Root / Trigger / Content / Item /
- * CheckboxItem / Separator / Label / Group) carries over; the
- * implementation is a lightweight React Context + Portal + outside-
- * click + Escape handler.
+ * CheckboxItem / Separator / Label / Group) carries over.
  *
- * Trigger styling per ADR-026 D4 (DQ-4 LIFT): the default trigger
- * inherits the secondary Button visual (rounded-xl, `--bg-card` fill,
- * 1px `--border`). Consumers can pass `asChild`-equivalent custom
- * trigger content; the wrapper applies the button-style classes
- * unless `unstyled` is set.
+ * Rebuilt on the shared anchored-positioning kit per ADR-0030 Decision G
+ * (meta-ads-audit-dashboard task manager; the workspace app's 137 call
+ * sites are the other consumer). Same public API, same DOM roles and
+ * `data-slot`s; what changed underneath:
+ *   • Positioning is `useAnchoredPosition` (lib/anchor.ts) — the menu now
+ *     FLIPS to the other side when it cannot fit, instead of being clamped
+ *     over its own trigger; `side` accepts `left` / `right` too.
+ *   • Escape goes through the shared dismiss-layer stack (lib/layer-stack.ts)
+ *     that Modal uses: a menu opened inside a Modal now closes on its own,
+ *     leaving the Modal open. Before, both closed on one keypress.
+ *   • Outside-click is `useOutsideClick`, layer-aware — a Select or Popover
+ *     opened from a menu item is not "outside".
+ *   • Trigger, Content, Item and CheckboxItem forward refs.
+ *
+ * Trigger styling per ADR-026 D4 (DQ-4 LIFT): the default trigger inherits
+ * the secondary Button visual (rounded-xl, `--bg-card` fill, 1px
+ * `--border`). Consumers can pass custom trigger content; the wrapper
+ * applies the button-style classes unless `unstyled` is set.
+ *
+ * Focus stays on the trigger when the menu opens (menus do not steal
+ * focus here; items are reached with Tab). Escape closes and refocuses the
+ * trigger. Roving arrow-key focus is a follow-up.
+ *
+ * Token discipline: surface chrome is `POPOVER_SURFACE_STYLE` (shared with
+ * Popover — internal `--popover` tokens are allowed inside packages/ui);
+ * item hover / focus use public `--surface-overlay`; motion is
+ * `.ds-enter-pop`, gated on `positioned` so it never plays from the parked
+ * off-screen frame.
  *
  * Workspace ADR: ADR-025 (port) + ADR-026 D4 (trigger spec)
- * Ported 2026-05-18
+ * Ported 2026-05-18 · Rebuilt on lib/anchor 2026-09-05
  */
 
 import {
   createContext,
+  forwardRef,
   useCallback,
   useContext,
-  useEffect,
   useId,
-  useLayoutEffect,
   useMemo,
   useRef,
   useState,
   type ButtonHTMLAttributes,
   type HTMLAttributes,
   type ReactNode,
+  type RefObject,
 } from 'react'
 import { createPortal } from 'react-dom'
 import { Check } from 'lucide-react'
 import { cn } from './lib/utils'
+import { composeRefs } from './lib/refs'
+import { useLayer } from './lib/layer-stack'
+import {
+  useAnchoredPosition,
+  useOutsideClick,
+  type AnchorAlign,
+  type AnchorSide,
+} from './lib/anchor'
+import { POPOVER_SURFACE_STYLE } from './popover'
 
-type Align = 'start' | 'center' | 'end'
-type Side = 'top' | 'bottom'
+type Align = AnchorAlign
+type Side = AnchorSide
 
 interface DropdownMenuContextValue {
   open: boolean
   setOpen: (next: boolean) => void
-  triggerRef: React.RefObject<HTMLButtonElement | null>
+  triggerRef: RefObject<HTMLButtonElement | null>
   contentId: string
 }
 
@@ -119,23 +149,28 @@ export interface DropdownMenuTriggerProps
  * secondary Button visual (rounded-xl + `--bg-card` fill + 1px
  * `--border`). Set `unstyled` to wrap your own button shape.
  */
-export function DropdownMenuTrigger({
-  unstyled,
-  className,
-  onClick,
-  children,
-  ...rest
-}: DropdownMenuTriggerProps) {
+export const DropdownMenuTrigger = forwardRef<
+  HTMLButtonElement,
+  DropdownMenuTriggerProps
+>(function DropdownMenuTrigger(
+  { unstyled, className, onClick, children, ...rest },
+  forwardedRef,
+) {
   const { open, setOpen, triggerRef, contentId } =
     useDropdownMenuCtx('DropdownMenuTrigger')
+  const ref = useMemo(
+    () => composeRefs<HTMLButtonElement>(forwardedRef, triggerRef),
+    [forwardedRef, triggerRef],
+  )
 
   return (
     <button
-      ref={triggerRef}
+      ref={ref}
       type="button"
       aria-haspopup="menu"
       aria-expanded={open}
       aria-controls={open ? contentId : undefined}
+      data-state={open ? 'open' : 'closed'}
       className={cn(
         !unstyled && 'btn btn-secondary',
         className,
@@ -149,7 +184,7 @@ export function DropdownMenuTrigger({
       {children}
     </button>
   )
-}
+})
 
 export interface DropdownMenuContentProps
   extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
@@ -158,142 +193,98 @@ export interface DropdownMenuContentProps
   align?: Align
   /** Pixel offset along the alignment axis. Default 0. */
   alignOffset?: number
-  /** Place above (`top`) or below (`bottom`) the trigger. Default `bottom`. */
+  /**
+   * Preferred side of the trigger. Default `bottom`. Flips to the opposite
+   * side when it cannot fit (before the 2026-09-05 rebuild it was clamped
+   * over its own trigger instead; only that no-room case differs).
+   */
   side?: Side
   /** Pixel offset along the side axis. Default 6. */
   sideOffset?: number
 }
 
-export function DropdownMenuContent({
-  children,
-  align = 'start',
-  alignOffset = 0,
-  side = 'bottom',
-  sideOffset = 6,
-  className,
-  style,
-  ...rest
-}: DropdownMenuContentProps) {
+export const DropdownMenuContent = forwardRef<
+  HTMLDivElement,
+  DropdownMenuContentProps
+>(function DropdownMenuContent(
+  {
+    children,
+    align = 'start',
+    alignOffset = 0,
+    side = 'bottom',
+    sideOffset = 6,
+    className,
+    style,
+    ...rest
+  },
+  forwardedRef,
+) {
   const { open, setOpen, triggerRef, contentId } =
     useDropdownMenuCtx('DropdownMenuContent')
   const contentRef = useRef<HTMLDivElement | null>(null)
-  const [position, setPosition] = useState<{ left: number; top: number } | null>(
-    null,
-  )
-
-  // Position relative to the trigger viewport rect. We measure on
-  // open + on layout changes (scroll / resize) so the panel tracks.
-  useLayoutEffect(() => {
-    if (!open) {
-      setPosition(null)
-      return
-    }
-    const measure = () => {
-      const triggerEl = triggerRef.current
-      const contentEl = contentRef.current
-      if (!triggerEl || !contentEl) return
-      const triggerRect = triggerEl.getBoundingClientRect()
-      const contentRect = contentEl.getBoundingClientRect()
-
-      let left = triggerRect.left + alignOffset
-      if (align === 'end') left = triggerRect.right - contentRect.width - alignOffset
-      else if (align === 'center')
-        left =
-          triggerRect.left +
-          triggerRect.width / 2 -
-          contentRect.width / 2 +
-          alignOffset
-
-      let top =
-        side === 'bottom'
-          ? triggerRect.bottom + sideOffset
-          : triggerRect.top - contentRect.height - sideOffset
 
-      // Keep on-screen — clamp to viewport with an 8px gutter.
-      const gutter = 8
-      const maxLeft = window.innerWidth - contentRect.width - gutter
-      const maxTop = window.innerHeight - contentRect.height - gutter
-      left = Math.max(gutter, Math.min(left, maxLeft))
-      top = Math.max(gutter, Math.min(top, maxTop))
-
-      setPosition({ left, top })
-    }
+  const {
+    ref: positionRef,
+    style: positionStyle,
+    placement,
+    positioned,
+  } = useAnchoredPosition<HTMLDivElement>({
+    anchorRef: triggerRef,
+    side,
+    align,
+    offset: sideOffset,
+    alignOffset,
+    enabled: open,
+  })
+
+  // Topmost-wins Escape, shared with Modal and Popover.
+  const layer = useLayer({
+    enabled: open,
+    kind: 'popover',
+    elementRef: contentRef,
+    onEscape: () => {
+      setOpen(false)
+      triggerRef.current?.focus()
+    },
+  })
 
-    measure()
-    window.addEventListener('resize', measure)
-    window.addEventListener('scroll', measure, true)
-    return () => {
-      window.removeEventListener('resize', measure)
-      window.removeEventListener('scroll', measure, true)
-    }
-  }, [open, align, alignOffset, side, sideOffset, triggerRef])
+  useOutsideClick([triggerRef, contentRef], () => setOpen(false), {
+    enabled: open,
+    layer,
+  })
 
-  // Outside-click + Escape dismissal.
-  useEffect(() => {
-    if (!open) return
-    const onPointerDown = (event: PointerEvent) => {
-      const target = event.target as Node | null
-      if (!target) return
-      if (contentRef.current?.contains(target)) return
-      if (triggerRef.current?.contains(target)) return
-      setOpen(false)
-    }
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        event.stopPropagation()
-        setOpen(false)
-        triggerRef.current?.focus()
-      }
-    }
-    document.addEventListener('pointerdown', onPointerDown)
-    document.addEventListener('keydown', onKeyDown)
-    return () => {
-      document.removeEventListener('pointerdown', onPointerDown)
-      document.removeEventListener('keydown', onKeyDown)
-    }
-  }, [open, setOpen, triggerRef])
+  const ref = useMemo(
+    () => composeRefs<HTMLDivElement>(forwardedRef, contentRef, positionRef),
+    [forwardedRef, positionRef],
+  )
 
   if (!open || typeof document === 'undefined') return null
 
-  // Two-phase render: first paint measures the content invisibly at
-  // (0,0) with opacity:0, useLayoutEffect computes the real position,
-  // and the second paint applies the correct coords + entrance animation.
-  // The animation classes are gated behind `isPositioned` so the
-  // entrance never fires from the unpositioned location — that's what
-  // caused the "flash at top of viewport then jump under the trigger"
-  // glitch.
-  const isPositioned = position !== null
-
+  // Two-phase render (see lib/anchor.ts): the hook parks the first paint
+  // off-screen and hidden, measures, then applies real coordinates. The
+  // entrance animation is gated on `positioned` so it never fires from the
+  // parked location — that was the "flash at top of viewport then jump
+  // under the trigger" glitch.
   return createPortal(
     <div
-      ref={contentRef}
+      ref={ref}
       id={contentId}
       role="menu"
       data-slot="dropdown-menu-content"
       data-state="open"
-      data-positioned={isPositioned ? 'true' : 'false'}
+      data-side={placement?.side}
+      data-align={placement?.align}
+      data-positioned={positioned ? 'true' : 'false'}
       className={cn(
         'fixed z-[100] min-w-48 max-w-[min(28rem,calc(100vw-16px))]',
         'p-1.5 overflow-y-auto',
         'rounded-[var(--radius-lg)]',
-        isPositioned && 'ds-enter-pop',
+        positioned && 'ds-enter-pop',
         className,
       )}
       style={{
-        // Anchor the unpositioned phase WAY off-screen as a defense
-        // against any browser/renderer that doesn't fully respect
-        // visibility:hidden during a same-frame double-render. If the
-        // first paint slips through, it's at (-99999, -99999), not at
-        // viewport (0, 0) where a left-edge flash would be visible.
-        left: position?.left ?? -99999,
-        top: position?.top ?? -99999,
-        opacity: isPositioned ? undefined : 0,
-        pointerEvents: isPositioned ? undefined : 'none',
-        visibility: isPositioned ? 'visible' : 'hidden',
-        background: 'rgb(var(--popover))',
-        color: 'rgb(var(--popover-foreground))',
-        border: '1px solid rgb(var(--border))',
-        boxShadow: 'var(--shadow-lg, 0 10px 32px rgba(0,0,0,0.18))',
+        ...positionStyle,
+        ...POPOVER_SURFACE_STYLE,
         ...style,
       }}
       {...rest}
@@ -302,7 +293,7 @@ export function DropdownMenuContent({
     </div>,
     document.body,
   )
-}
+})
 
 export interface DropdownMenuItemProps
   extends ButtonHTMLAttributes<HTMLButtonElement> {
@@ -312,17 +303,17 @@ export interface DropdownMenuItemProps
   inset?: boolean
 }
 
-export function DropdownMenuItem({
-  variant = 'default',
-  inset,
-  className,
-  onClick,
-  children,
-  ...rest
-}: DropdownMenuItemProps) {
+export const DropdownMenuItem = forwardRef<
+  HTMLButtonElement,
+  DropdownMenuItemProps
+>(function DropdownMenuItem(
+  { variant = 'default', inset, className, onClick, children, ...rest },
+  forwardedRef,
+) {
   const { setOpen } = useDropdownMenuCtx('DropdownMenuItem')
   return (
     <button
+      ref={forwardedRef}
       role="menuitem"
       type="button"
       data-slot="dropdown-menu-item"
@@ -348,7 +339,7 @@ export function DropdownMenuItem({
       {children}
     </button>
   )
-}
+})
 
 export interface DropdownMenuCheckboxItemProps
   extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onChange'> {
@@ -356,17 +347,16 @@ export interface DropdownMenuCheckboxItemProps
   onCheckedChange?: (checked: boolean) => void
 }
 
-export function DropdownMenuCheckboxItem({
-  checked,
-  onCheckedChange,
-  className,
-  children,
-  onClick,
-  disabled,
-  ...rest
-}: DropdownMenuCheckboxItemProps) {
+export const DropdownMenuCheckboxItem = forwardRef<
+  HTMLButtonElement,
+  DropdownMenuCheckboxItemProps
+>(function DropdownMenuCheckboxItem(
+  { checked, onCheckedChange, className, children, onClick, disabled, ...rest },
+  forwardedRef,
+) {
   return (
     <button
+      ref={forwardedRef}
       role="menuitemcheckbox"
       type="button"
       data-slot="dropdown-menu-checkbox-item"
@@ -399,7 +389,7 @@ export function DropdownMenuCheckboxItem({
       ) : null}
     </button>
   )
-}
+})
 
 export function DropdownMenuSeparator({
   className,

package/src/index.ts

@@ -172,6 +172,112 @@ export {
   type EditingCell,
 } from './data-grid'
 
+// Anchored-positioning kit + dismiss-layer stack — promoted per ADR-0030
+// Decision G (meta-ads-audit-dashboard task manager: its pickers, sheets
+// and palette need one positioning routine and one Escape order). The
+// workspace app is the other consumer: DropdownMenu (137 call sites),
+// Modal (51 files) and Popover are rebuilt on these in the same change.
+// `useAnchoredPosition` measures / flips / clamps against an element ref
+// OR a virtual rect (ContextMenu's right-click point); `useOutsideClick`
+// is layer-aware; `useLayer` / `useEscapeKey` are the topmost-wins stack
+// extracted from Modal's `openPanels`. Select / Combobox / Tooltip /
+// ContextMenu build on them next; FilterDropdown / FolderTreePicker /
+// TagChipInput still carry local copies of the positioning block
+// (follow-up).
+export {
+  useAnchoredPosition,
+  computeAnchoredPosition,
+  useOutsideClick,
+  type AnchorSide,
+  type AnchorAlign,
+  type AnchorRect,
+  type AnchorSize,
+  type AnchorPlacement,
+  type AnchoredPosition,
+  type AnchoredPositionOptions,
+  type UseAnchoredPositionOptions,
+  type UseAnchoredPositionResult,
+  type OutsideClickTarget,
+  type UseOutsideClickOptions,
+} from './lib/anchor'
+export {
+  useLayer,
+  useEscapeKey,
+  type LayerKind,
+  type LayerHandle,
+  type UseLayerOptions,
+  type UseEscapeKeyOptions,
+} from './lib/layer-stack'
+
+// Popover — anchored, non-modal surface: portal to body, `.ds-enter-pop`
+// once positioned, focus into the content on open and back to the trigger
+// on close, Escape closes the topmost layer only, outside-click closes.
+// Compound: Popover + Popover.Trigger (`asChild` to wrap a <Button> or a
+// cell) + Popover.Content (`role="dialog"` or `"none"`). Promoted per
+// ADR-0030 Decision G; the workspace app's three hand-rolled popovers
+// (sidebar user menu, group-settings colour / icon pickers, calculator
+// AssumptionsPopover) are the migration targets. DropdownMenu shares its
+// surface chrome (`POPOVER_SURFACE_STYLE`) and stack, but stays a sibling
+// because a menu does not move focus into itself on open.
+export {
+  Popover,
+  POPOVER_SURFACE_STYLE,
+  type PopoverProps,
+  type PopoverTriggerProps,
+  type PopoverContentProps,
+} from './popover'
+
+// Select — single-value picker: an `.input-shell` trigger (sm / md, sits
+// flush beside <Input>) that opens a real listbox (APG select-only
+// combobox: role=combobox trigger, aria-activedescendant, role=listbox /
+// option, arrow / Home / End / Enter / Space / type-ahead, disabled
+// options, optional icon + description). Promoted per ADR-0030 Decision G
+// — the meta-ads-audit-dashboard task manager's status / priority / role
+// pickers; its Users page hand-rolled a native <select> with a comment
+// saying the package ships none. The workspace app is the second consumer
+// (26 native <select>s, products/product-form.tsx says the same). Built on
+// useAnchoredPosition + the layer stack; shares the popover surface chrome.
+// `ListboxOption` / `LISTBOX_CLASS` are the row + popup chrome Combobox
+// reuses, exported for the same reason POPOVER_SURFACE_STYLE is.
+export {
+  Select,
+  ListboxOption,
+  LISTBOX_CLASS,
+  type SelectProps,
+  type SelectOption,
+  type SelectSize,
+  type ListboxOptionProps,
+} from './select'
+
+// Combobox — text input + filtered listbox (APG editable combobox with list
+// autocomplete), single or multi-select with chips, optional grouped options
+// with headings, a per-option live `count` slot and a `renderOption` slot.
+// Async-friendly: `shouldFilter={false}` + `loading` + `onInputValueChange`;
+// it never fetches. Promoted per ADR-0030 Decision G — the task manager's
+// row / card / context-menu / palette pickers are "popover + search + live
+// counts". Second consumer is the workspace app
+// (sem-spec/location-autocomplete.tsx hand-rolls the role; TagChipInput
+// carries the chip model this generalises).
+export {
+  Combobox,
+  type ComboboxProps,
+  type ComboboxSingleProps,
+  type ComboboxMultipleProps,
+  type ComboboxOption,
+  type ComboboxGroup,
+  type ComboboxOptionState,
+  type ComboboxSize,
+} from './combobox'
+
+// Tooltip — hover (300 ms) / focus (immediate) triggered role=tooltip with
+// aria-describedby wiring, Escape-dismissable through the layer stack, never
+// focusable, pointer-events none, token-only inline surface like Kbd.
+// Promoted per ADR-0030 Decision G (task manager: truncated cells, icon-only
+// row actions, timestamps). Second consumer is the workspace app, which
+// hand-rolls two today (tools/_shared/calc/info-tip.tsx,
+// components/ui/sidebar/rail-tooltip.tsx).
+export { Tooltip, type TooltipProps, type TooltipTriggerProps } from './tooltip'
+
 // DropdownButton — Button-styled trigger + rich popover menu. Composed
 // over <DropdownMenu> primitives. First consumer: Keywords dashboard's
 // "New Keyword Plan" CTA (Set/Group picker). Reusable across other