@lovett/ui 0.0.9 → 0.0.11

package/src/index.ts

@@ -28,6 +28,8 @@ export { default as MicrosoftLogo, type MicrosoftLogoProps } from './microsoft-l
 export {
   BrandMeta,
   BrandFacebook,
+  BrandIcon,
+  hasBrandIcon,
   BrandInstagram,
   BrandMessenger,
   BrandLinkedIn,
@@ -45,7 +47,10 @@ export {
   AppScroll,
   PageHeaderHost,
   PageHeaderSlotProvider,
+  HomeCrumbLink,
+  useBreadcrumbHome,
   type Crumb,
+  type HomeCrumb,
 } from './page-shell'
 export { Toaster, toast } from './toast'
 
@@ -167,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

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