Edux overlays

Original headless overlay behaviour shared by Edux component packages. React and React DOM are peer dependencies; the foundation does not depend on another UI, positioning, focus-management or scroll-lock library.

This package is under local implementation and has not been published. Component adapters and compatibility evidence are being developed on the original-overlays branch. Public component styling remains in the existing Edux packages.

The core state helper treats undefined as uncontrolled state. Controlled updates request a change from the host and do not change the displayed value unless the host accepts. State callbacks are interaction-driven and never run from a React state updater or initial render.

Slot composes onto one element without adding DOM. Child attributes take precedence, class names are joined, and styles merge with the child's declarations last. Both native event handlers run child first; internal primitive behaviour uses composeEventHandlers to respect the event's defaultPrevented state. Native object/callback refs and React 19 callback cleanup are preserved.

Observing an anchor from the shared position tracker

usePosition accepts two optional subscriptions. onAnchorRectChange(rect) runs when the numeric rectangle changes; onAnchorMeasure(rect) runs on every measurement, including unchanged geometry. Both receive the same immutable Readonly<RectLike> | null value in viewport CSS pixels (x, y, width, height). Equal rectangles reuse their snapshot identity. A transformed positioner may use different local coordinates; these callbacks always report the original viewport rectangle.

const position = usePosition({
  open,
  anchorRef,
  contentRef,
  positionerRef,
  updatePositionStrategy: "always",
  positioning: !docked && !instructionHost,
  onAnchorMeasure: (rect) => {
    // Derive application-owned padding, corners and highlight state here.
    // Return previous state when those derived values are unchanged.
    updateHighlight(rect);
  },
});

The position tracker owns the observer/event/frame queue. "always" uses that same queue to follow transforms and animation; an event never adds a second frame tracker. The callback reads the latest function without restarting observers. Changing callback identity does not replay an unchanged snapshot. A per-measurement callback can sample styles when geometry is unchanged; compare derived state before setting it, and keep virtual getBoundingClientRect getters free of state updates. Callback-induced renders use the next shared frame instead of measuring again synchronously.

A missing, disconnected, invalid, cross-document or CSS-hidden anchor reports null. CSS-hidden means display:none on the element/ancestor, or computed visibility:hidden/collapse on the element. Valid offscreen and zero-sized virtual anchors remain valid. aria-hidden, inert, opacity and application target eligibility belong to the consumer. Callback visibility does not change existing floating visibility/placement rules. An initially closed hook reports null once; closing reports null if the previous snapshot was available. Closed hooks perform no measurements or observer/frame work. Unmount cancels work without calling the callbacks. Unavailable-anchor measurements may keep reporting null through onAnchorMeasure while the hook is open.

Set positioning:false for a docked card or an external instruction host. The hook keeps tracking/reporting the real anchor, skips floating content, arrow and positioner measurements, returns an empty positionerStyle, and reports isPositioned:false. It works without mounted floating content. Supply a contextElement for a virtual anchor when no floating content establishes the owner document. Measurement-only mode without either subscription allocates no tracker. Keep ref objects stable while their element is unchanged. When replacing the anchor, supply a new anchorRef object so its observer lifecycle follows the new element (continuous mode also reads the current element on every frame). For per-frame style-only changes, use updatePositionStrategy:"always".