Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

7.5 KB
Raw Blame
import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';

// usePopoverPosition — shared fixed-position placement for portal popovers
// anchored to a trigger element.
//
// Both ThemeSwitcher and CollectionPickerShell (and any future surface that
// portals a menu into <body>) compute the same thing: a viewport-clamped
// { left, top, width } for a fixed-position card that sits above-or-below a
// trigger, re-measured on open and re-flowed (rAF-coalesced) on scroll/resize.
// This hook owns that plumbing so callers only wire two refs and render the
// returned style.
//
// Contract:
//   const { triggerRef, popoverRef, style, reposition } = usePopoverPosition({ open, ... });
//   - triggerRef → the anchor element (button) whose rect the popover follows.
//     Attach this to your trigger. If the trigger lives in a parent and you
//     already hold a ref to it, pass it as `anchorRef` and the hook follows
//     that one instead (the returned `triggerRef` then mirrors it).
//   - popoverRef → the fixed-position portal element being placed.
//   - style → { left, top, width } strings while measured, or `null` before the
//     first measurement (render with `visibility: hidden` until non-null so the
//     popover never flashes at the top-left corner pre-measure).
//   - reposition → force a re-measure (e.g. after the popover's content height
//     changes from filtering/search) without waiting for a scroll/resize event.
//
// `contentDeps` is a dependency array of values whose change alters the
// popover's rendered height (search query, filtered list, load state). The
// hook re-measures synchronously (in useLayoutEffect, before paint) whenever
// any of them change, so a content-height change can't paint one frame at the
// stale position before correcting.
//
// Placement: `position: 'above'` prefers opening above the trigger and flips
// below only when there isn't room above; `'below'` does the inverse. Both
// clamp into the viewport with VIEWPORT_PADDING on every edge.
// Horizontal alignment is 'start', 'center', or 'end' (the compatible default).
// Opt into `constrainHeight` for scrollable help: cap to the chosen side's
// available height, choosing the roomier side when the preferred side is too short.
//
// The reflow listener uses capture-phase scroll so scrolling ANY ancestor
// (not just window) keeps the popover attached to its trigger, and coalesces
// bursts through requestAnimationFrame so a fast scrollwheel can't queue dozens
// of layout reads per frame. The setter short-circuits on an unchanged
// { left, top, width } so a capture-phase scroll that doesn't move the trigger
// doesn't re-render every pixel.

const VIEWPORT_PADDING = 8;

export default function usePopoverPosition({
  open,
  width = 288,
  minWidth = 180,
  gap = 8,
  position = 'above',
  align = 'end',
  constrainHeight = false,
  anchorRef = null,
  contentDeps = [],
} = {}) {
  const ownTriggerRef = useRef(null);
  // Follow a parent-owned anchor when one is supplied; otherwise place this
  // hook's own ref on the trigger.
  const triggerRef = anchorRef ?? ownTriggerRef;
  const popoverRef = useRef(null);
  const [style, setStyle] = useState(null);

  const reposition = useCallback(() => {
    const trigger = triggerRef.current;
    const popover = popoverRef.current;
    if (!trigger || !popover) return;

    const viewportWidth = window.innerWidth;
    const viewportHeight = window.innerHeight;
    const w = Math.min(width, Math.max(minWidth, viewportWidth - VIEWPORT_PADDING * 2));

    // Apply width before measuring height — narrow viewports may wrap content
    // and grow the popover's height. Measuring at the wrong width produces a
    // top value that under-clamps and lets the portal overflow.
    popover.style.width = `${w}px`;

    const triggerRect = trigger.getBoundingClientRect();
    let effectivePosition = position;
    let maxHeight;
    if (constrainHeight) {
      const viewportSpace = Math.max(0, viewportHeight - VIEWPORT_PADDING * 2);
      const aboveSpace = Math.min(viewportSpace, Math.max(0, triggerRect.top - gap - VIEWPORT_PADDING));
      const belowSpace = Math.min(viewportSpace, Math.max(0, viewportHeight - triggerRect.bottom - gap - VIEWPORT_PADDING));
      // Measure natural height at the clamped width before choosing a side.
      popover.style.maxHeight = `${viewportSpace}px`;
      const height = popover.getBoundingClientRect().height;
      const preferredSpace = position === 'above' ? aboveSpace : belowSpace;
      if (height > preferredSpace) effectivePosition = aboveSpace > belowSpace ? 'above' : 'below';
      maxHeight = `${effectivePosition === 'above' ? aboveSpace : belowSpace}px`;
      popover.style.maxHeight = maxHeight;
    }
    const popoverRect = popover.getBoundingClientRect();

    const maxLeft = viewportWidth - w - VIEWPORT_PADDING;
    const alignedLeft = align === 'start'
      ? triggerRect.left
      : align === 'center'
        ? (triggerRect.left + triggerRect.right - w) / 2
        : triggerRect.right - w;
    const left = Math.min(
      Math.max(alignedLeft, VIEWPORT_PADDING),
      Math.max(VIEWPORT_PADDING, maxLeft),
    );

    const aboveTop = triggerRect.top - popoverRect.height - gap;
    const belowTop = triggerRect.bottom + gap;
    const wouldOverflowTop = aboveTop < VIEWPORT_PADDING;
    const wouldOverflowBottom = belowTop + popoverRect.height > viewportHeight - VIEWPORT_PADDING;

    let top = effectivePosition === 'above'
      ? (wouldOverflowTop ? belowTop : aboveTop)
      : (wouldOverflowBottom ? aboveTop : belowTop);

    const maxTop = Math.max(VIEWPORT_PADDING, viewportHeight - popoverRect.height - VIEWPORT_PADDING);
    top = Math.min(Math.max(top, VIEWPORT_PADDING), maxTop);

    setStyle((prev) => {
      const next = { left: `${left}px`, top: `${top}px`, width: `${w}px`, ...(constrainHeight ? { maxHeight } : {}) };
      if (prev && prev.left === next.left && prev.top === next.top && prev.width === next.width && prev.maxHeight === next.maxHeight) {
        return prev;
      }
      return next;
    });
  }, [triggerRef, width, minWidth, gap, position, align, constrainHeight]);

  // Measure synchronously on open (and on any content-height change) so the
  // popover paints in place; clear on close so the next open re-measures (and
  // renders hidden until it does). The content-change re-measure stays in
  // useLayoutEffect — moving it to useEffect would paint one frame at the stale
  // height before correcting when the rendered content grows/shrinks.
  useLayoutEffect(() => {
    if (!open) {
      setStyle(null);
      return;
    }
    reposition();
  }, [open, reposition, ...contentDeps]);

  useEffect(() => {
    if (!open) return undefined;
    let rafId = null;
    const onReflow = (event) => {
      // Scrolling help does not move its anchor. Re-measuring would briefly
      // enlarge the live scroll container and clamp away its bottom scrollTop.
      if (constrainHeight && event.type === 'scroll' && popoverRef.current?.contains(event.target)) return;
      if (rafId !== null) return;
      rafId = requestAnimationFrame(() => {
        rafId = null;
        reposition();
      });
    };
    window.addEventListener('resize', onReflow);
    window.addEventListener('scroll', onReflow, true);
    return () => {
      if (rafId !== null) cancelAnimationFrame(rafId);
      window.removeEventListener('resize', onReflow);
      window.removeEventListener('scroll', onReflow, true);
    };
  }, [open, reposition, constrainHeight]);

  return { triggerRef, popoverRef, style, reposition };
}

export { VIEWPORT_PADDING };