@cdx-ui/primitives 0.0.1-beta.99 → 0.1.1

package/src/overlay/useAnchorPosition.ts

@@ -16,48 +16,125 @@ function measureWeb(element: any): AnchorLayout {
   return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
 }
 
+function setLayoutIfChanged(
+  setLayout: React.Dispatch<React.SetStateAction<AnchorLayout | null>>,
+  next: AnchorLayout,
+) {
+  setLayout((prev) => {
+    if (
+      prev?.x === next.x &&
+      prev.y === next.y &&
+      prev.width === next.width &&
+      prev.height === next.height
+    ) {
+      return prev;
+    }
+    return next;
+  });
+}
+
+export interface UseAnchorPositionOptions {
+  /** Re-run layout measurement when this value changes (e.g. slider value percent). */
+  remeasureKey?: unknown;
+  /** Poll anchor position each animation frame while open (for anchors that move). */
+  trackWhileOpen?: boolean;
+}
+
 /**
  * Measures an anchor element's position and size, re-measuring on scroll/resize
  * (web) so a positioned overlay can track its anchor across layout changes.
  *
  * Returns `null` until the first measurement completes.
  */
-export function useAnchorPosition(anchorRef: RefObject<any>, open: boolean): AnchorLayout | null {
+export function useAnchorPosition(
+  anchorRef: RefObject<any>,
+  open: boolean,
+  options?: UseAnchorPositionOptions,
+): AnchorLayout | null {
+  const { remeasureKey, trackWhileOpen = false } = options ?? {};
   const [layout, setLayout] = useState<AnchorLayout | null>(null);
 
+  const measureAnchor = () => {
+    const anchor = anchorRef.current;
+    if (!anchor) {
+      return;
+    }
+
+    if (Platform.OS === 'web') {
+      setLayoutIfChanged(setLayout, measureWeb(anchor));
+      return;
+    }
+
+    anchor.measureInWindow((x: number, y: number, width: number, height: number) => {
+      setLayoutIfChanged(setLayout, { x, y, width, height });
+    });
+  };
+
   useIsomorphicLayoutEffect(() => {
     if (!open) {
       setLayout(null);
       return;
     }
 
-    const anchor = anchorRef.current;
-    if (!anchor) return;
-
     let cancelled = false;
+    let retryFrameId = 0;
+    let webFrameId = 0;
+
+    const runMeasure = () => {
+      if (cancelled) {
+        return;
+      }
+
+      const anchor = anchorRef.current;
+      if (!anchor) {
+        retryFrameId = requestAnimationFrame(runMeasure);
+        return;
+      }
+
+      measureAnchor();
+    };
+
+    runMeasure();
 
     if (Platform.OS === 'web') {
-      setLayout(measureWeb(anchor));
-    } else {
-      anchor.measureInWindow((x: number, y: number, width: number, height: number) => {
-        if (!cancelled) {
-          setLayout({ x, y, width, height });
-        }
-      });
+      webFrameId = requestAnimationFrame(runMeasure);
     }
 
     return () => {
       cancelled = true;
+      cancelAnimationFrame(retryFrameId);
+      cancelAnimationFrame(webFrameId);
     };
-  }, [open, anchorRef]);
+  }, [open, anchorRef, remeasureKey]);
 
   useEffect(() => {
-    if (!open || Platform.OS !== 'web') return;
+    if (!open || !trackWhileOpen) {
+      return;
+    }
+
+    let frameId = 0;
+    const tick = () => {
+      measureAnchor();
+      frameId = requestAnimationFrame(tick);
+    };
+    frameId = requestAnimationFrame(tick);
+
+    return () => {
+      cancelAnimationFrame(frameId);
+    };
+  }, [open, anchorRef, remeasureKey, trackWhileOpen]);
+
+  useEffect(() => {
+    if (!open || Platform.OS !== 'web' || trackWhileOpen) {
+      return;
+    }
 
     const anchor = anchorRef.current;
-    if (!anchor) return;
+    if (!anchor) {
+      return;
+    }
 
-    const update = () => setLayout(measureWeb(anchor));
+    const update = () => setLayoutIfChanged(setLayout, measureWeb(anchor));
 
     window.addEventListener('scroll', update, true);
     window.addEventListener('resize', update);
@@ -66,7 +143,7 @@ export function useAnchorPosition(anchorRef: RefObject<any>, open: boolean): Anc
       window.removeEventListener('scroll', update, true);
       window.removeEventListener('resize', update);
     };
-  }, [open, anchorRef]);
+  }, [open, anchorRef, remeasureKey, trackWhileOpen]);
 
   return layout;
 }

package/src/overlay/useAnchoredOverlay.ts

@@ -0,0 +1,150 @@
+import { useCallback, useContext, useEffect, useMemo, useReducer, useRef, useState } from 'react';
+import {
+  I18nManager,
+  Platform,
+  useWindowDimensions,
+  type LayoutChangeEvent,
+  type ViewStyle,
+} from 'react-native';
+import {
+  getAnchoredOverlayPosition,
+  type AnchoredOverlayPosition,
+  type AnchoredOverlayPositionOptions,
+  type FloatingLayout,
+} from './getAnchoredOverlayPosition';
+import { useAnchorPosition, type UseAnchorPositionOptions } from './useAnchorPosition';
+import { OverlayInsetsContext } from './useOverlayPosition';
+
+export interface UseAnchoredOverlayOptions
+  extends AnchoredOverlayPositionOptions, UseAnchorPositionOptions {}
+
+export interface UseAnchoredOverlayResult {
+  floatingRef: React.RefObject<any>;
+  onFloatingLayout: (event: LayoutChangeEvent) => void;
+  style: ViewStyle;
+  position: AnchoredOverlayPosition | null;
+  ready: boolean;
+  update: () => void;
+}
+
+const STAGING_STYLE: ViewStyle = {
+  left: -10000,
+  opacity: 0,
+  pointerEvents: 'none',
+  position: 'absolute',
+  top: -10000,
+};
+
+function setLayoutIfChanged(
+  setLayout: React.Dispatch<React.SetStateAction<FloatingLayout | null>>,
+  next: FloatingLayout,
+) {
+  setLayout((previous) => {
+    if (previous?.width === next.width && previous.height === next.height) {
+      return previous;
+    }
+    return next;
+  });
+}
+
+export function useAnchoredOverlay(
+  anchorRef: React.RefObject<any>,
+  open: boolean,
+  options: UseAnchoredOverlayOptions = {},
+): UseAnchoredOverlayResult {
+  const { remeasureKey: externalRemeasureKey, trackWhileOpen, ...positionOptions } = options;
+  const [revision, update] = useReducer((value: number) => value + 1, 0);
+  const remeasureKey = useMemo(
+    () => ({ externalRemeasureKey, revision }),
+    [externalRemeasureKey, revision],
+  );
+  const anchorLayout = useAnchorPosition(anchorRef, open, {
+    remeasureKey,
+    trackWhileOpen,
+  });
+  const floatingRef = useRef<any>(null);
+  const [floatingLayout, setFloatingLayout] = useState<FloatingLayout | null>(null);
+  const viewport = useWindowDimensions();
+  const insets = useContext(OverlayInsetsContext);
+
+  const measureFloating = useCallback(() => {
+    // Native measure callbacks can resolve after onLayout and replace the rendered size
+    // with stale staging geometry. Native layout changes are already reported by onLayout.
+    if (Platform.OS !== 'web') return;
+
+    const floating = floatingRef.current;
+    if (!floating) return;
+
+    if (typeof floating.getBoundingClientRect === 'function') {
+      const rect = floating.getBoundingClientRect();
+      setLayoutIfChanged(setFloatingLayout, { width: rect.width, height: rect.height });
+    }
+  }, []);
+
+  const onFloatingLayout = useCallback((event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    setLayoutIfChanged(setFloatingLayout, { width, height });
+  }, []);
+
+  const requestUpdate = useCallback(() => {
+    update();
+    measureFloating();
+  }, [measureFloating]);
+
+  useEffect(() => {
+    if (!open) {
+      setFloatingLayout(null);
+      return;
+    }
+
+    measureFloating();
+  }, [measureFloating, open, revision]);
+
+  useEffect(() => {
+    if (!open || Platform.OS !== 'web') return;
+
+    const floating = floatingRef.current as HTMLElement | null;
+    const anchor = anchorRef.current as HTMLElement | null;
+    const resizeObserver =
+      typeof ResizeObserver === 'undefined'
+        ? null
+        : new ResizeObserver(() => {
+            requestUpdate();
+          });
+
+    if (floating) resizeObserver?.observe(floating);
+    if (anchor) resizeObserver?.observe(anchor);
+
+    const visualViewport = window.visualViewport;
+    visualViewport?.addEventListener('resize', requestUpdate);
+    visualViewport?.addEventListener('scroll', requestUpdate);
+
+    return () => {
+      resizeObserver?.disconnect();
+      visualViewport?.removeEventListener('resize', requestUpdate);
+      visualViewport?.removeEventListener('scroll', requestUpdate);
+    };
+  }, [anchorRef, open, requestUpdate]);
+
+  const position = useMemo(() => {
+    if (!anchorLayout || !floatingLayout) return null;
+
+    return getAnchoredOverlayPosition(anchorLayout, floatingLayout, viewport, {
+      ...positionOptions,
+      insets: positionOptions.insets ?? insets,
+      isRTL: positionOptions.isRTL ?? I18nManager.isRTL,
+    });
+  }, [anchorLayout, floatingLayout, viewport, positionOptions, insets]);
+
+  const ready = position !== null;
+  const positionStyle = (Platform.OS === 'web' ? 'fixed' : 'absolute') as ViewStyle['position'];
+
+  return {
+    floatingRef,
+    onFloatingLayout,
+    style: ready ? { position: positionStyle, ...position.style } : STAGING_STYLE,
+    position,
+    ready,
+    update: requestUpdate,
+  };
+}

package/src/overlay/useDismissOverlay.ts

@@ -1,12 +1,20 @@
 import type { RefObject } from 'react';
+import { useOverlayStackRegistration, type OverlayStackMetadata } from './OverlayStack';
 
 /**
  * No-op on native — overlay dismissal is handled by backdrop press
  * or the system back gesture / hardware button via Modal.
  */
 export function useDismissOverlay(
-  _open: boolean,
+  open: boolean,
   _contentRef: RefObject<any>,
   _excludeRefs: RefObject<any>[],
   _onDismiss: () => void,
-) {}
+  options: OverlayStackMetadata = {},
+) {
+  useOverlayStackRegistration({
+    active: open,
+    capabilities: ['outside'],
+    ...options,
+  });
+}

package/src/overlay/useDismissOverlay.web.ts

@@ -1,5 +1,14 @@
 import type { RefObject } from 'react';
 import { useEffect, useRef } from 'react';
+import { useOverlayStackRegistration, type OverlayStackMetadata } from './OverlayStack';
+
+function refContainsNode(ref: RefObject<unknown>, target: Node): boolean {
+  const current = ref.current as { contains?: (node: Node) => boolean } | null;
+  if (!current || typeof current.contains !== 'function') {
+    return false;
+  }
+  return current.contains(target);
+}
 
 /**
  * Dismisses an overlay when the user clicks/presses outside of it or when
@@ -11,12 +20,18 @@ export function useDismissOverlay(
   contentRef: RefObject<any>,
   excludeRefs: RefObject<any>[],
   onDismiss: () => void,
+  options: OverlayStackMetadata = {},
 ) {
   const onDismissRef = useRef(onDismiss);
   onDismissRef.current = onDismiss;
 
   const excludeRefsRef = useRef(excludeRefs);
   excludeRefsRef.current = excludeRefs;
+  const { isTopmost } = useOverlayStackRegistration({
+    active: open,
+    capabilities: ['outside'],
+    ...options,
+  });
 
   useEffect(() => {
     if (!open) {
@@ -24,11 +39,11 @@ export function useDismissOverlay(
     }
 
     const isInsideOverlay = (target: Node) => {
-      if (contentRef.current?.contains?.(target)) {
+      if (refContainsNode(contentRef, target)) {
         return true;
       }
       for (const ref of excludeRefsRef.current) {
-        if (ref.current?.contains?.(target)) {
+        if (refContainsNode(ref, target)) {
           return true;
         }
       }
@@ -36,7 +51,7 @@ export function useDismissOverlay(
     };
 
     const dismissIfOutside = (e: Event) => {
-      if (!isInsideOverlay(e.target as Node)) {
+      if (isTopmost('outside') && !isInsideOverlay(e.target as Node)) {
         onDismissRef.current();
       }
     };
@@ -47,5 +62,5 @@ export function useDismissOverlay(
       document.removeEventListener('pointerdown', dismissIfOutside);
       document.removeEventListener('focusin', dismissIfOutside);
     };
-  }, [open, contentRef]);
+  }, [open, contentRef, isTopmost]);
 }

package/src/overlay/useEscapeKey.ts

@@ -1,5 +1,17 @@
+import { useOverlayStackRegistration, type OverlayStackMetadata } from './OverlayStack';
+
 /**
  * No-op on native — Escape key dismissal is not applicable.
  * Native uses the system back gesture / hardware button via Modal.
  */
-export function useEscapeKey(_open: boolean, _onEscape: () => void) {}
+export function useEscapeKey(
+  open: boolean,
+  _onEscape: () => void,
+  options: OverlayStackMetadata = {},
+) {
+  useOverlayStackRegistration({
+    active: open,
+    capabilities: ['escape'],
+    ...options,
+  });
+}

package/src/overlay/useEscapeKey.web.ts

@@ -1,12 +1,22 @@
 import { useEffect, useRef } from 'react';
+import { useOverlayStackRegistration, type OverlayStackMetadata } from './OverlayStack';
 
 /**
  * Closes an overlay when the user presses the Escape key.
  * Web-only — native platforms use Modal's `onRequestClose` for back/dismiss.
  */
-export function useEscapeKey(open: boolean, onEscape: () => void) {
+export function useEscapeKey(
+  open: boolean,
+  onEscape: () => void,
+  options: OverlayStackMetadata = {},
+) {
   const onEscapeRef = useRef(onEscape);
   onEscapeRef.current = onEscape;
+  const { isTopmost } = useOverlayStackRegistration({
+    active: open,
+    capabilities: ['escape'],
+    ...options,
+  });
 
   useEffect(() => {
     if (!open) {
@@ -14,7 +24,7 @@ export function useEscapeKey(open: boolean, onEscape: () => void) {
     }
 
     const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
+      if (e.key === 'Escape' && isTopmost('escape')) {
         onEscapeRef.current();
       }
     };
@@ -23,5 +33,5 @@ export function useEscapeKey(open: boolean, onEscape: () => void) {
     return () => {
       document.removeEventListener('keydown', handleKeyDown);
     };
-  }, [open]);
+  }, [isTopmost, open]);
 }

package/src/overlay/useOverlayPosition.ts

@@ -37,6 +37,9 @@ export const OverlayInsetsProvider = OverlayInsetsContext.Provider;
 /** Minimum gap (px) between the overlay edge and the viewport/safe-area boundary. */
 const SCREEN_EDGE_PADDING = 8;
 
+/** Gap between anchor and popover content. */
+const POPOVER_GAP = 4;
+
 /** Minimum usable space (px) below the anchor before the overlay flips above. */
 const MIN_CONTENT_HEIGHT = 200;
 
@@ -46,6 +49,11 @@ export interface OverlayPosition {
   placement: 'top' | 'bottom';
 }
 
+export interface UseOverlayPositionOptions {
+  /** When true (default), overlay width matches the anchor (e.g. Select). When false, width follows content (e.g. Menu). */
+  matchAnchorWidth?: boolean;
+}
+
 /**
  * Computes viewport-aware overlay positioning relative to an anchor element.
  * Automatically flips placement from bottom to top when insufficient space
@@ -54,9 +62,17 @@ export interface OverlayPosition {
  *
  * Respects safe-area insets provided via `OverlayInsetsProvider`.
  */
-export function useOverlayPosition(anchorLayout: AnchorLayout | null): OverlayPosition | null {
-  const { height: viewportHeight } = useWindowDimensions();
-  const { top: insetTop, bottom: insetBottom } = useContext(OverlayInsetsContext);
+export function useOverlayPosition(
+  anchorLayout: AnchorLayout | null,
+  options?: UseOverlayPositionOptions,
+): OverlayPosition | null {
+  const { width: viewportWidth, height: viewportHeight } = useWindowDimensions();
+  const {
+    top: insetTop,
+    bottom: insetBottom,
+    right: insetRight,
+  } = useContext(OverlayInsetsContext);
+  const matchAnchorWidth = options?.matchAnchorWidth ?? true;
 
   return useMemo(() => {
     if (!anchorLayout) return null;
@@ -67,13 +83,20 @@ export function useOverlayPosition(anchorLayout: AnchorLayout | null): OverlayPo
 
     const preferBelow = spaceBelow >= MIN_CONTENT_HEIGHT || spaceBelow >= spaceAbove;
 
+    const horizontalStyle: ViewStyle = matchAnchorWidth
+      ? { left: anchorLayout.x, width: anchorLayout.width }
+      : {
+          left: anchorLayout.x,
+          alignItems: 'flex-start',
+          maxWidth: Math.max(0, viewportWidth - anchorLayout.x - insetRight - SCREEN_EDGE_PADDING),
+        };
+
     if (preferBelow) {
       const maxHeight = Math.max(0, spaceBelow);
       return {
         style: {
-          top: anchorBottom,
-          left: anchorLayout.x,
-          width: anchorLayout.width,
+          ...horizontalStyle,
+          top: anchorBottom + POPOVER_GAP,
           maxHeight,
         },
         maxHeight,
@@ -84,13 +107,20 @@ export function useOverlayPosition(anchorLayout: AnchorLayout | null): OverlayPo
     const maxHeight = Math.max(0, spaceAbove);
     return {
       style: {
-        bottom: viewportHeight - anchorLayout.y,
-        left: anchorLayout.x,
-        width: anchorLayout.width,
+        ...horizontalStyle,
+        bottom: viewportHeight - anchorLayout.y + POPOVER_GAP,
         maxHeight,
       },
       maxHeight,
       placement: 'top' as const,
     };
-  }, [anchorLayout, viewportHeight, insetTop, insetBottom]);
+  }, [
+    anchorLayout,
+    viewportWidth,
+    viewportHeight,
+    insetTop,
+    insetBottom,
+    insetRight,
+    matchAnchorWidth,
+  ]);
 }