@lovett/ui 0.0.10 → 0.0.11

package/src/lib/anchor.ts

@@ -0,0 +1,427 @@
+/**
+ * Anchored positioning — the ONE measure / flip / clamp routine behind every
+ * floating surface in @lovett/ui.
+ *
+ * Four primitives (DropdownMenu, FilterDropdown, FolderTreePicker,
+ * TagChipInput) each hand-rolled the same `useLayoutEffect` +
+ * `getBoundingClientRect` + clamp + resize/scroll-listener block, with four
+ * slightly different gaps: no flip at a viewport edge; no clamp; measuring in
+ * a passive effect so the first paint was wrong; `top`/`bottom` only. This
+ * module is the single implementation. DropdownMenu is rebuilt on it in the
+ * same change; the other three keep their local copies for now (follow-up).
+ *
+ * Promoted per ADR-0030 Decision G (meta-ads-audit-dashboard task manager)
+ * with the workspace app as the first consumer — DropdownMenu and Popover
+ * position through this hook, so every menu in the app is on it. Select /
+ * Combobox / Tooltip / ContextMenu build on it next.
+ *
+ * No Floating UI, no Popper (CLAUDE.md §1 allowed deps). Three pieces:
+ *   • `computeAnchoredPosition` — pure math, unit-tested without a DOM.
+ *   • `useAnchoredPosition` — measures, positions, tracks resize / scroll /
+ *     size changes. Anchor is an element (`anchorRef`) OR a virtual rect
+ *     (`anchorRect`) — ContextMenu passes the right-click point as
+ *     `{ left: e.clientX, top: e.clientY, width: 0, height: 0 }`.
+ *   • `useOutsideClick` — pointerdown outside a set of targets, aware of
+ *     layers stacked above (a nested Select's listbox is not "outside").
+ *
+ * Two-phase render, unchanged from the DropdownMenu it replaces: the first
+ * paint measures the content parked at (-99999, -99999) with
+ * `visibility: hidden`, the layout effect computes the real coordinates, and
+ * the second paint reveals it. Components gate their entry animation on
+ * `positioned` so `.ds-enter-pop` never plays from the parked location.
+ *
+ * Token discipline: the hook emits geometry only (`position: fixed` +
+ * `left` / `top` in px). Surface colour, radius, shadow, padding and the
+ * motion class stay with the component.
+ *
+ * Usage:
+ *
+ *   const { ref, style, placement, positioned } =
+ *     useAnchoredPosition<HTMLDivElement>({
+ *       anchorRef: triggerRef,
+ *       side: 'bottom',
+ *       align: 'start',
+ *       offset: 6,
+ *       enabled: open,
+ *     })
+ *   return createPortal(
+ *     <div
+ *       ref={ref}
+ *       style={style}
+ *       data-side={placement?.side}
+ *       className={cn(positioned && 'ds-enter-pop')}
+ *     >
+ *       …
+ *     </div>,
+ *     document.body,
+ *   )
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type RefObject,
+} from 'react'
+import type { LayerHandle } from './layer-stack'
+
+export type AnchorSide = 'top' | 'bottom' | 'left' | 'right'
+export type AnchorAlign = 'start' | 'center' | 'end'
+
+/** Viewport-relative rect. `DOMRect` satisfies it; so does a point. */
+export interface AnchorRect {
+  readonly left: number
+  readonly top: number
+  readonly width: number
+  readonly height: number
+}
+
+export interface AnchorSize {
+  readonly width: number
+  readonly height: number
+}
+
+/** The side and alignment actually used after flipping. */
+export interface AnchorPlacement {
+  readonly side: AnchorSide
+  readonly align: AnchorAlign
+}
+
+export interface AnchoredPositionOptions {
+  /** Preferred side of the anchor. Default `bottom`. */
+  side?: AnchorSide
+  /** Alignment along the anchor's cross axis. Default `start`. */
+  align?: AnchorAlign
+  /** Gap between anchor and floating element along `side`, px. Default 6. */
+  offset?: number
+  /** Shift along the alignment axis, px. Default 0. */
+  alignOffset?: number
+  /**
+   * Flip to the opposite side when the preferred side cannot fit and the
+   * opposite side fits — or simply has more room. Default true.
+   */
+  flip?: boolean
+  /** Keep the floating element inside the viewport, `gutter` px in. Default true. */
+  clampToViewport?: boolean
+  /** Viewport inset used by both flip and clamp, px. Default 8. */
+  gutter?: number
+}
+
+export interface AnchoredPosition {
+  readonly left: number
+  readonly top: number
+  readonly placement: AnchorPlacement
+}
+
+const OPPOSITE: Record<AnchorSide, AnchorSide> = {
+  top: 'bottom',
+  bottom: 'top',
+  left: 'right',
+  right: 'left',
+}
+
+function isVertical(side: AnchorSide): boolean {
+  return side === 'top' || side === 'bottom'
+}
+
+function clampNumber(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(value, max))
+}
+
+/**
+ * Pure placement math. Given the anchor rect, the floating element's size
+ * and the viewport size, returns fixed-position coordinates plus the
+ * placement actually used. No DOM — this is what the tests pin.
+ */
+export function computeAnchoredPosition(
+  anchor: AnchorRect,
+  floating: AnchorSize,
+  viewport: AnchorSize,
+  options: AnchoredPositionOptions = {},
+): AnchoredPosition {
+  const {
+    side: preferred = 'bottom',
+    align = 'start',
+    offset = 6,
+    alignOffset = 0,
+    flip = true,
+    clampToViewport = true,
+    gutter = 8,
+  } = options
+
+  const anchorRight = anchor.left + anchor.width
+  const anchorBottom = anchor.top + anchor.height
+
+  // Room on each side of the anchor, inside the gutter.
+  const room: Record<AnchorSide, number> = {
+    top: anchor.top - gutter,
+    bottom: viewport.height - anchorBottom - gutter,
+    left: anchor.left - gutter,
+    right: viewport.width - anchorRight - gutter,
+  }
+  const needed = (side: AnchorSide): number =>
+    (isVertical(side) ? floating.height : floating.width) + offset
+
+  let side = preferred
+  if (flip && room[preferred] < needed(preferred)) {
+    const opposite = OPPOSITE[preferred]
+    if (room[opposite] >= needed(opposite) || room[opposite] > room[preferred]) {
+      side = opposite
+    }
+  }
+
+  let left: number
+  let top: number
+
+  if (isVertical(side)) {
+    top =
+      side === 'bottom'
+        ? anchorBottom + offset
+        : anchor.top - floating.height - offset
+    switch (align) {
+      case 'start':
+        left = anchor.left + alignOffset
+        break
+      case 'center':
+        left = anchor.left + anchor.width / 2 - floating.width / 2 + alignOffset
+        break
+      case 'end':
+        left = anchorRight - floating.width - alignOffset
+        break
+    }
+  } else {
+    left =
+      side === 'right'
+        ? anchorRight + offset
+        : anchor.left - floating.width - offset
+    switch (align) {
+      case 'start':
+        top = anchor.top + alignOffset
+        break
+      case 'center':
+        top = anchor.top + anchor.height / 2 - floating.height / 2 + alignOffset
+        break
+      case 'end':
+        top = anchorBottom - floating.height - alignOffset
+        break
+    }
+  }
+
+  if (clampToViewport) {
+    // `max` first: when the element is wider than the viewport the upper
+    // bound is below the gutter, and the gutter wins.
+    left = clampNumber(left, gutter, viewport.width - floating.width - gutter)
+    top = clampNumber(top, gutter, viewport.height - floating.height - gutter)
+  }
+
+  return {
+    left: Math.round(left),
+    top: Math.round(top),
+    placement: { side, align },
+  }
+}
+
+export interface UseAnchoredPositionOptions extends AnchoredPositionOptions {
+  /** Element to anchor to. Ignored while `anchorRect` is non-null. */
+  anchorRef?: RefObject<Element | null>
+  /** Virtual anchor (a right-click point, a text caret). Wins over `anchorRef`. */
+  anchorRect?: AnchorRect | null
+  /** Measure and track while true. Default true. */
+  enabled?: boolean
+}
+
+export interface UseAnchoredPositionResult<T extends HTMLElement> {
+  /** Attach to the floating element. */
+  ref: (node: T | null) => void
+  /** The same node as a ref object — for `contains()` checks. */
+  floatingRef: RefObject<T | null>
+  /** `position: fixed` + coordinates; hidden and parked off-screen until measured. */
+  style: CSSProperties
+  /** Side / align actually used, or null until measured. */
+  placement: AnchorPlacement | null
+  /** True once real coordinates are applied. Gate entry motion on this. */
+  positioned: boolean
+  /** Re-measure now (after content you know changed size, for example). */
+  update: () => void
+}
+
+const PARKED_STYLE: CSSProperties = {
+  position: 'fixed',
+  // Parked far off-screen, not at (0, 0): if a renderer paints the
+  // unpositioned frame despite `visibility: hidden`, nothing flashes at the
+  // viewport's top-left corner.
+  left: -99999,
+  top: -99999,
+  visibility: 'hidden',
+  opacity: 0,
+  pointerEvents: 'none',
+}
+
+function viewportSize(): AnchorSize {
+  // `clientWidth` excludes a vertical scrollbar, which `innerWidth` includes;
+  // an end-aligned menu would otherwise sit under the scrollbar. jsdom
+  // reports 0 for clientWidth, hence the fallback.
+  const root = document.documentElement
+  return {
+    width: root.clientWidth || window.innerWidth,
+    height: root.clientHeight || window.innerHeight,
+  }
+}
+
+function samePosition(a: AnchoredPosition | null, b: AnchoredPosition): boolean {
+  return (
+    a !== null &&
+    a.left === b.left &&
+    a.top === b.top &&
+    a.placement.side === b.placement.side &&
+    a.placement.align === b.placement.align
+  )
+}
+
+export function useAnchoredPosition<T extends HTMLElement = HTMLElement>(
+  options: UseAnchoredPositionOptions,
+): UseAnchoredPositionResult<T> {
+  const {
+    anchorRef,
+    anchorRect = null,
+    enabled = true,
+    side = 'bottom',
+    align = 'start',
+    offset = 6,
+    alignOffset = 0,
+    flip = true,
+    clampToViewport = true,
+    gutter = 8,
+  } = options
+
+  // The floating node lives in state as well as a ref so the measuring
+  // effect re-runs when the element mounts — a RefObject alone cannot
+  // signal that.
+  const floatingRef = useRef<T | null>(null)
+  const [floating, setFloating] = useState<T | null>(null)
+  const ref = useCallback((node: T | null) => {
+    floatingRef.current = node
+    setFloating(node)
+  }, [])
+
+  const [position, setPosition] = useState<AnchoredPosition | null>(null)
+
+  // Latest virtual rect, read at measure time. Keyed by value (not object
+  // identity) so a caller passing a fresh literal each render does not
+  // re-subscribe the listeners.
+  const anchorRectRef = useRef<AnchorRect | null>(anchorRect)
+  useLayoutEffect(() => {
+    anchorRectRef.current = anchorRect
+  })
+  const rectKey = anchorRect
+    ? `${anchorRect.left}|${anchorRect.top}|${anchorRect.width}|${anchorRect.height}`
+    : ''
+
+  const measure = useCallback(() => {
+    const node = floatingRef.current
+    if (!node) return
+    const rect =
+      anchorRectRef.current ?? anchorRef?.current?.getBoundingClientRect() ?? null
+    if (!rect) return
+    // offsetWidth/Height are layout sizes, untouched by the entry animation's
+    // transform. getBoundingClientRect() would read a 0.95-scaled box mid-
+    // `.ds-enter-pop` and shift an end-aligned menu by 5% of its width.
+    const next = computeAnchoredPosition(
+      rect,
+      { width: node.offsetWidth, height: node.offsetHeight },
+      viewportSize(),
+      { side, align, offset, alignOffset, flip, clampToViewport, gutter },
+    )
+    setPosition((prev) => (samePosition(prev, next) ? prev : next))
+  }, [anchorRef, side, align, offset, alignOffset, flip, clampToViewport, gutter])
+
+  useLayoutEffect(() => {
+    if (!enabled || !floating) {
+      setPosition((prev) => (prev === null ? prev : null))
+      return
+    }
+    measure()
+    window.addEventListener('resize', measure)
+    // Capture phase: scrolls inside nested containers do not bubble, and a
+    // menu anchored inside one must follow its trigger.
+    window.addEventListener('scroll', measure, true)
+    let observer: ResizeObserver | null = null
+    if (typeof ResizeObserver !== 'undefined') {
+      observer = new ResizeObserver(() => measure())
+      observer.observe(floating)
+      const anchorEl = anchorRef?.current
+      if (anchorEl) observer.observe(anchorEl)
+    }
+    return () => {
+      window.removeEventListener('resize', measure)
+      window.removeEventListener('scroll', measure, true)
+      observer?.disconnect()
+    }
+  }, [enabled, floating, measure, anchorRef, rectKey])
+
+  const positioned = position !== null
+  const style: CSSProperties = positioned
+    ? { position: 'fixed', left: position.left, top: position.top }
+    : PARKED_STYLE
+
+  return {
+    ref,
+    floatingRef,
+    style,
+    placement: position?.placement ?? null,
+    positioned,
+    update: measure,
+  }
+}
+
+export type OutsideClickTarget = RefObject<Element | null> | Element | null | undefined
+
+export interface UseOutsideClickOptions {
+  /** Default true. */
+  enabled?: boolean
+  /**
+   * This surface's dismiss layer. When given, a pointerdown inside any layer
+   * stacked ABOVE it (a Select opened from inside a Popover) is treated as
+   * inside, not outside.
+   */
+  layer?: LayerHandle
+}
+
+/**
+ * Calls `onOutside` on a `pointerdown` whose target is inside none of
+ * `targets`. Handler and targets are read through refs, so inline arrays
+ * and arrows do not re-subscribe the listener.
+ */
+export function useOutsideClick(
+  targets: ReadonlyArray<OutsideClickTarget>,
+  onOutside: (event: PointerEvent) => void,
+  options: UseOutsideClickOptions = {},
+): void {
+  const { enabled = true, layer } = options
+
+  const targetsRef = useRef(targets)
+  const handlerRef = useRef(onOutside)
+  useEffect(() => {
+    targetsRef.current = targets
+    handlerRef.current = onOutside
+  })
+
+  useEffect(() => {
+    if (!enabled) return
+    const onPointerDown = (event: PointerEvent) => {
+      const target = event.target
+      if (!(target instanceof Node)) return
+      for (const candidate of targetsRef.current) {
+        const el = candidate instanceof Node ? candidate : candidate?.current
+        if (el?.contains(target)) return
+      }
+      if (layer?.containsInLayerAbove(target)) return
+      handlerRef.current(event)
+    }
+    document.addEventListener('pointerdown', onPointerDown)
+    return () => document.removeEventListener('pointerdown', onPointerDown)
+  }, [enabled, layer])
+}

package/src/lib/focus.ts

@@ -0,0 +1,32 @@
+/**
+ * Tabbable-element query shared by the focus-managing surfaces (Modal's
+ * trap, Popover's focus-on-open). Extracted from modal.tsx.
+ *
+ * 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.
+ */
+
+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(',')
+
+export function tabbablesWithin(root: HTMLElement): HTMLElement[] {
+  return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+    (el) =>
+      el.tabIndex >= 0 &&
+      !el.hasAttribute('inert') &&
+      el.getAttribute('aria-hidden') !== 'true' &&
+      !el.closest('[hidden]'),
+  )
+}

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