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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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 };