@cdx-ui/primitives 0.0.1-beta.17 → 0.0.1-beta.171

package/src/overlay/getAnchoredOverlayPosition.ts

@@ -0,0 +1,334 @@
+import type { ViewStyle } from 'react-native';
+import type { AnchorLayout } from './useAnchorPosition';
+import type { EdgeInsets } from './useOverlayPosition';
+
+export const OVERLAY_PLACEMENTS = [
+  'auto',
+  'auto-start',
+  'auto-end',
+  'top',
+  'top-start',
+  'top-end',
+  'right',
+  'right-start',
+  'right-end',
+  'bottom',
+  'bottom-start',
+  'bottom-end',
+  'left',
+  'left-start',
+  'left-end',
+] as const;
+
+export type OverlayPlacement = (typeof OVERLAY_PLACEMENTS)[number];
+export type OverlaySide = 'top' | 'right' | 'bottom' | 'left';
+export type OverlayAlign = 'start' | 'center' | 'end';
+export type OverlayCollisionBehavior = 'none' | 'flip' | 'flip-shift';
+export type OverlayWidthPolicy = 'content' | 'anchor';
+
+export interface FloatingLayout {
+  width: number;
+  height: number;
+}
+
+export interface ResolvedOverlayPlacement {
+  side: OverlaySide;
+  align: OverlayAlign;
+}
+
+export interface AnchoredOverlayPositionOptions {
+  placement?: OverlayPlacement;
+  offset?: number;
+  crossOffset?: number;
+  collisionBehavior?: OverlayCollisionBehavior;
+  collisionPadding?: number | Partial<EdgeInsets>;
+  insets?: Partial<EdgeInsets>;
+  width?: OverlayWidthPolicy;
+  isRTL?: boolean;
+  arrowBoundaryOffset?: number;
+}
+
+export interface AnchoredOverlayPosition {
+  style: ViewStyle;
+  resolvedPlacement: ResolvedOverlayPlacement;
+  placement: Exclude<OverlayPlacement, 'auto' | 'auto-start' | 'auto-end'>;
+  availableWidth: number;
+  availableHeight: number;
+  arrow: { x?: number; y?: number };
+  transformOrigin: string;
+}
+
+interface Boundary {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+const DEFAULT_COLLISION_PADDING = 8;
+const DEFAULT_OFFSET = 4;
+
+function toInsets(value: number | Partial<EdgeInsets> | undefined): EdgeInsets {
+  if (typeof value === 'number') {
+    return { top: value, right: value, bottom: value, left: value };
+  }
+
+  return {
+    top: value?.top ?? DEFAULT_COLLISION_PADDING,
+    right: value?.right ?? DEFAULT_COLLISION_PADDING,
+    bottom: value?.bottom ?? DEFAULT_COLLISION_PADDING,
+    left: value?.left ?? DEFAULT_COLLISION_PADDING,
+  };
+}
+
+function parsePlacement(
+  placement: OverlayPlacement,
+): ResolvedOverlayPlacement | { side: 'auto'; align: OverlayAlign } {
+  const [side, align = 'center'] = placement.split('-') as [
+    OverlaySide | 'auto',
+    OverlayAlign | undefined,
+  ];
+  return { side, align };
+}
+
+function stringifyPlacement({
+  side,
+  align,
+}: ResolvedOverlayPlacement): AnchoredOverlayPosition['placement'] {
+  return (align === 'center' ? side : `${side}-${align}`) as AnchoredOverlayPosition['placement'];
+}
+
+function oppositeSide(side: OverlaySide): OverlaySide {
+  switch (side) {
+    case 'top':
+      return 'bottom';
+    case 'right':
+      return 'left';
+    case 'bottom':
+      return 'top';
+    case 'left':
+      return 'right';
+  }
+}
+
+function availableMainAxis(
+  side: OverlaySide,
+  anchor: AnchorLayout,
+  boundary: Boundary,
+  offset: number,
+): number {
+  switch (side) {
+    case 'top':
+      return anchor.y - offset - boundary.top;
+    case 'right':
+      return boundary.right - (anchor.x + anchor.width + offset);
+    case 'bottom':
+      return boundary.bottom - (anchor.y + anchor.height + offset);
+    case 'left':
+      return anchor.x - offset - boundary.left;
+  }
+}
+
+function mainAxisSize(side: OverlaySide, floating: FloatingLayout): number {
+  return side === 'top' || side === 'bottom' ? floating.height : floating.width;
+}
+
+function resolveAutoSide(
+  anchor: AnchorLayout,
+  floating: FloatingLayout,
+  boundary: Boundary,
+  offset: number,
+): OverlaySide {
+  const sides: OverlaySide[] = ['bottom', 'top', 'right', 'left'];
+  return sides.reduce((best, side) => {
+    const available = availableMainAxis(side, anchor, boundary, offset);
+    const bestAvailable = availableMainAxis(best, anchor, boundary, offset);
+    const fits = available >= mainAxisSize(side, floating);
+    const bestFits = bestAvailable >= mainAxisSize(best, floating);
+
+    if (fits !== bestFits) {
+      return fits ? side : best;
+    }
+
+    return available > bestAvailable ? side : best;
+  });
+}
+
+function alignCoordinate(
+  anchorStart: number,
+  anchorSize: number,
+  floatingSize: number,
+  align: OverlayAlign,
+  reverseLogicalAlignment: boolean,
+): number {
+  const resolvedAlign =
+    reverseLogicalAlignment && align !== 'center' ? (align === 'start' ? 'end' : 'start') : align;
+
+  if (resolvedAlign === 'start') {
+    return anchorStart;
+  }
+
+  if (resolvedAlign === 'end') {
+    return anchorStart + anchorSize - floatingSize;
+  }
+
+  return anchorStart + (anchorSize - floatingSize) / 2;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  if (max < min) return min;
+  return Math.min(Math.max(value, min), max);
+}
+
+function getTransformOrigin(
+  side: OverlaySide,
+  arrow: AnchoredOverlayPosition['arrow'],
+  floating: FloatingLayout,
+): string {
+  const x = arrow.x ?? floating.width / 2;
+  const y = arrow.y ?? floating.height / 2;
+
+  switch (side) {
+    case 'top':
+      return `${String(x)}px 100%`;
+    case 'right':
+      return `0% ${String(y)}px`;
+    case 'bottom':
+      return `${String(x)}px 0%`;
+    case 'left':
+      return `100% ${String(y)}px`;
+  }
+}
+
+export function getAnchoredOverlayPosition(
+  anchor: AnchorLayout,
+  floatingLayout: FloatingLayout,
+  viewport: { width: number; height: number },
+  options: AnchoredOverlayPositionOptions = {},
+): AnchoredOverlayPosition {
+  const placement = options.placement ?? 'bottom-start';
+  const offset = options.offset ?? DEFAULT_OFFSET;
+  const crossOffset = options.crossOffset ?? 0;
+  const collisionBehavior = options.collisionBehavior ?? 'flip-shift';
+  const collisionPadding = toInsets(options.collisionPadding);
+  const insets: EdgeInsets = {
+    top: options.insets?.top ?? 0,
+    right: options.insets?.right ?? 0,
+    bottom: options.insets?.bottom ?? 0,
+    left: options.insets?.left ?? 0,
+  };
+  const boundary: Boundary = {
+    top: insets.top + collisionPadding.top,
+    right: viewport.width - insets.right - collisionPadding.right,
+    bottom: viewport.height - insets.bottom - collisionPadding.bottom,
+    left: insets.left + collisionPadding.left,
+  };
+  const parsed = parsePlacement(placement);
+  const measuredFloating: FloatingLayout = {
+    width: options.width === 'anchor' ? anchor.width : floatingLayout.width,
+    height: floatingLayout.height,
+  };
+
+  let side =
+    parsed.side === 'auto'
+      ? resolveAutoSide(anchor, measuredFloating, boundary, offset)
+      : parsed.side;
+  const align = parsed.align;
+
+  if (parsed.side !== 'auto' && collisionBehavior !== 'none') {
+    const opposite = oppositeSide(side);
+    const available = availableMainAxis(side, anchor, boundary, offset);
+    const oppositeAvailable = availableMainAxis(opposite, anchor, boundary, offset);
+    const required = mainAxisSize(side, measuredFloating);
+
+    if (available < required && oppositeAvailable > available) {
+      side = opposite;
+    }
+  }
+
+  const availableWidth =
+    side === 'left' || side === 'right'
+      ? Math.max(0, availableMainAxis(side, anchor, boundary, offset))
+      : Math.max(0, boundary.right - boundary.left);
+  const availableHeight =
+    side === 'top' || side === 'bottom'
+      ? Math.max(0, availableMainAxis(side, anchor, boundary, offset))
+      : Math.max(0, boundary.bottom - boundary.top);
+  const positionedFloating: FloatingLayout = {
+    width: Math.min(measuredFloating.width, availableWidth),
+    height: Math.min(measuredFloating.height, availableHeight),
+  };
+
+  let left: number;
+  let top: number;
+
+  if (side === 'top' || side === 'bottom') {
+    left =
+      alignCoordinate(
+        anchor.x,
+        anchor.width,
+        positionedFloating.width,
+        align,
+        options.isRTL ?? false,
+      ) + crossOffset;
+    top =
+      side === 'top'
+        ? anchor.y - offset - positionedFloating.height
+        : anchor.y + anchor.height + offset;
+  } else {
+    left =
+      side === 'left'
+        ? anchor.x - offset - positionedFloating.width
+        : anchor.x + anchor.width + offset;
+    top =
+      alignCoordinate(anchor.y, anchor.height, positionedFloating.height, align, false) +
+      crossOffset;
+  }
+
+  if (collisionBehavior === 'flip-shift') {
+    if (side === 'top' || side === 'bottom') {
+      left = clamp(left, boundary.left, boundary.right - positionedFloating.width);
+    } else {
+      top = clamp(top, boundary.top, boundary.bottom - positionedFloating.height);
+    }
+  }
+
+  const arrowBoundaryOffset = options.arrowBoundaryOffset ?? 8;
+  const anchorCenterX = anchor.x + anchor.width / 2;
+  const anchorCenterY = anchor.y + anchor.height / 2;
+  const arrow =
+    side === 'top' || side === 'bottom'
+      ? {
+          x: clamp(
+            anchorCenterX - left,
+            arrowBoundaryOffset,
+            positionedFloating.width - arrowBoundaryOffset,
+          ),
+        }
+      : {
+          y: clamp(
+            anchorCenterY - top,
+            arrowBoundaryOffset,
+            positionedFloating.height - arrowBoundaryOffset,
+          ),
+        };
+  const resolvedPlacement = { side, align };
+
+  return {
+    style: {
+      left,
+      top,
+      width: options.width === 'anchor' ? anchor.width : undefined,
+      minWidth: positionedFloating.width,
+      minHeight: positionedFloating.height,
+      maxWidth: availableWidth,
+      maxHeight: availableHeight,
+    },
+    resolvedPlacement,
+    placement: stringifyPlacement(resolvedPlacement),
+    availableWidth,
+    availableHeight,
+    arrow,
+    transformOrigin: getTransformOrigin(side, arrow, positionedFloating),
+  };
+}

package/src/overlay/index.ts

@@ -1,11 +1,40 @@
+export { MODAL_OVERLAY_Z_INDEX, NOTIFICATION_OVERLAY_Z_INDEX } from './constants';
 export { OverlayContainer } from './OverlayContainer';
 export type { OverlayContainerProps } from './OverlayContainer';
+export {
+  OverlayStackProvider,
+  useOverlayStackRegistration,
+  type OverlayStackCapability,
+  type OverlayStackLayer,
+  type OverlayStackMetadata,
+  type OverlayStackRegistrationOptions,
+  type OverlayStackRegistrationResult,
+} from './OverlayStack';
 export { useAnchorPosition, type AnchorLayout } from './useAnchorPosition';
 export { useDismissOverlay } from './useDismissOverlay';
 export { useEscapeKey } from './useEscapeKey';
+export {
+  getAnchoredOverlayPosition,
+  OVERLAY_PLACEMENTS,
+  type AnchoredOverlayPosition,
+  type AnchoredOverlayPositionOptions,
+  type FloatingLayout,
+  type OverlayAlign,
+  type OverlayCollisionBehavior,
+  type OverlayPlacement,
+  type OverlaySide,
+  type OverlayWidthPolicy,
+  type ResolvedOverlayPlacement,
+} from './getAnchoredOverlayPosition';
+export {
+  useAnchoredOverlay,
+  type UseAnchoredOverlayOptions,
+  type UseAnchoredOverlayResult,
+} from './useAnchoredOverlay';
 export {
   useOverlayPosition,
   type OverlayPosition,
+  type UseOverlayPositionOptions,
   OverlayInsetsProvider,
   type EdgeInsets,
 } from './useOverlayPosition';

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,14 +1,20 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-
 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,
+  });
+}