Overlays

Anchored popovers, viewport clamping, z-index management. Lives in packages/sdk/src/chrome/overlays/.

Key files

• AnchoredPopover.tsx — single primitive for every anchored popover/dropdown in the editor chrome
• useAnchoredPopover.ts — Floating UI hook (placement, flip, shift, click-outside, ESC)
• useClampToViewport.ts — keeps a fixed-position element on screen as the viewport changes
• overlayZIndex.ts — OVERLAY_Z_ANCHORED / dialog / toast z-index constants
• VIEWPORT_ANCHORING.md — internal design doc for the anchoring strategy
• index.ts — public exports

AnchoredPopover

Wraps useAnchoredPopover (Floating UI) + portal + z-index + fade animation + delayed unmount for the exit fade.

Two anchor modes:

• Element ref: anchor={someRef} or anchor={someElement}
• DOMRect (for atom-driven dialogs where the trigger is unmounted by the time the popover opens): anchorRect={rect}

Use it for: selects, color pickers, variable pickers, searchable menus, spacing/sizing dropdowns.

NOT for: FloatingPanel-style draggable windows (use FloatingPanel instead).

Key props

• placement, mainAxisOffset, crossAxisOffset, flipOptions, shiftPadding, boundary, rootBoundary
• maxHeightCeiling — caps max-height to available viewport space
• matchAnchorWidth: { min, max } — clamp width to anchor's width
• immediate — skip fade-out delay
• portalTarget — defaults to .pagehub-sdk-root then document.body
• ignoreOutsideClicks — refs that don't count as "outside" for dismissal
• controlled mode — caller owns visibility (skip built-in click-outside + ESC)

Composition examples

• SearchableMenuPopover wraps AnchoredPopover + Headless UI Combobox.
• VariablePopover uses anchorRect for atom-driven mounting.

Z-index tiers

From overlayZIndex.ts:

• OVERLAY_Z_ANCHORED — popovers and dropdowns
• Dialog/modal tier above
• Toast tier highest

Related

• primitives, editor-popover-pattern.md
• dialogs — atom-driven dialogs that compose AnchoredPopover with anchorRect