@lovett/ui 0.0.10 → 0.1.0

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