@cdx-ui/primitives 0.0.1-beta.159 → 0.0.1-beta.160

package/src/overlay/index.ts

@@ -1,12 +1,40 @@
-export { MODAL_OVERLAY_Z_INDEX } from './constants';
+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/useAnchoredOverlay.ts

@@ -0,0 +1,153 @@
+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(() => {
+    const floating = floatingRef.current;
+    if (!floating) return;
+
+    if (Platform.OS === 'web' && typeof floating.getBoundingClientRect === 'function') {
+      const rect = floating.getBoundingClientRect();
+      setLayoutIfChanged(setFloatingLayout, { width: rect.width, height: rect.height });
+      return;
+    }
+
+    if (typeof floating.measure === 'function') {
+      floating.measure((_x: number, _y: number, width: number, height: number) => {
+        setLayoutIfChanged(setFloatingLayout, { width, 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,6 @@
 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;
@@ -19,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) {
@@ -44,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();
       }
     };
@@ -55,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

@@ -49,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
@@ -57,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;
@@ -70,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: {
+          ...horizontalStyle,
           top: anchorBottom + POPOVER_GAP,
-          left: anchorLayout.x,
-          width: anchorLayout.width,
           maxHeight,
         },
         maxHeight,
@@ -87,13 +107,20 @@ export function useOverlayPosition(anchorLayout: AnchorLayout | null): OverlayPo
     const maxHeight = Math.max(0, spaceAbove);
     return {
       style: {
+        ...horizontalStyle,
         bottom: viewportHeight - anchorLayout.y + POPOVER_GAP,
-        left: anchorLayout.x,
-        width: anchorLayout.width,
         maxHeight,
       },
       maxHeight,
       placement: 'top' as const,
     };
-  }, [anchorLayout, viewportHeight, insetTop, insetBottom]);
+  }, [
+    anchorLayout,
+    viewportWidth,
+    viewportHeight,
+    insetTop,
+    insetBottom,
+    insetRight,
+    matchAnchorWidth,
+  ]);
 }

package/src/portal/portal.tsx

@@ -8,54 +8,55 @@ const DEFAULT_PORTAL_HOST = 'FORGE_UI_DEFAULT_HOST_NAME';
 type PortalMap = Map<string, React.ReactNode>;
 type PortalHostMap = Map<string, PortalMap>;
 
-interface PortalStore {
+interface PortalRegistry {
   map: PortalHostMap;
-  listeners: Set<() => void>;
+  hostStacks: Map<string, symbol[]>;
+  portalListeners: Set<() => void>;
+  hostListeners: Set<() => void>;
+  hasWarnedMultipleHosts: boolean;
 }
 
-const store: PortalStore = {
-  map: new Map<string, PortalMap>().set(DEFAULT_PORTAL_HOST, new Map<string, React.ReactNode>()),
-  listeners: new Set(),
-};
-
-/** Tracks mounted PortalHost instances per host name — only the first mount renders portals. */
-const hostStackStore = {
-  stacks: new Map<string, symbol[]>(),
-  listeners: new Set<() => void>(),
-};
-
-let hasWarnedMultiplePortalHosts = false;
-
-// --------------------------------------------------
-
-function emit() {
-  for (const cb of store.listeners) cb();
+function createPortalRegistry(): PortalRegistry {
+  return {
+    map: new Map<string, PortalMap>().set(DEFAULT_PORTAL_HOST, new Map()),
+    hostStacks: new Map(),
+    portalListeners: new Set(),
+    hostListeners: new Set(),
+    hasWarnedMultipleHosts: false,
+  };
 }
 
-function emitHostStack() {
-  for (const cb of hostStackStore.listeners) cb();
+/**
+ * Standalone Portal and PortalHost instances continue to share this fallback.
+ * PortalProvider creates an isolated registry for each provider subtree.
+ */
+const fallbackPortalRegistry = createPortalRegistry();
+const PortalRegistryContext = React.createContext<PortalRegistry | null>(null);
+
+function emitPortals(registry: PortalRegistry) {
+  for (const cb of registry.portalListeners) cb();
 }
 
-function getHostStackSnapshot() {
-  return hostStackStore.stacks;
+function emitHosts(registry: PortalRegistry) {
+  for (const cb of registry.hostListeners) cb();
 }
 
-function subscribeHostStack(cb: () => void) {
-  hostStackStore.listeners.add(cb);
+function subscribeHosts(registry: PortalRegistry, cb: () => void) {
+  registry.hostListeners.add(cb);
   return () => {
-    hostStackStore.listeners.delete(cb);
+    registry.hostListeners.delete(cb);
   };
 }
 
-function pushPortalHost(name: string, id: symbol) {
-  const stacks = new Map(hostStackStore.stacks);
+function pushPortalHost(registry: PortalRegistry, name: string, id: symbol) {
+  const stacks = new Map(registry.hostStacks);
   const stack = [...(stacks.get(name) ?? [])];
   stack.push(id);
   stacks.set(name, stack);
-  hostStackStore.stacks = stacks;
+  registry.hostStacks = stacks;
 
-  if (__DEV__ && !hasWarnedMultiplePortalHosts && stack.length > 1) {
-    hasWarnedMultiplePortalHosts = true;
+  if (__DEV__ && !registry.hasWarnedMultipleHosts && stack.length > 1) {
+    registry.hasWarnedMultipleHosts = true;
     console.warn(
       '[Forge UI] Multiple PortalHost instances detected for the same host name. ' +
         'Only the first mounted PortalHost renders portal content. ' +
@@ -63,73 +64,107 @@ function pushPortalHost(name: string, id: symbol) {
     );
   }
 
-  emitHostStack();
+  emitHosts(registry);
 }
 
-function popPortalHost(name: string, id: symbol) {
-  const stacks = new Map(hostStackStore.stacks);
+function popPortalHost(registry: PortalRegistry, name: string, id: symbol) {
+  const stacks = new Map(registry.hostStacks);
   const stack = (stacks.get(name) ?? []).filter((entry) => entry !== id);
-  stacks.set(name, stack);
-  hostStackStore.stacks = stacks;
-  emitHostStack();
+  if (stack.length === 0) {
+    stacks.delete(name);
+  } else {
+    stacks.set(name, stack);
+  }
+  registry.hostStacks = stacks;
+  emitHosts(registry);
 }
 
-function isActivePortalHost(name: string, id: symbol) {
-  const stack = hostStackStore.stacks.get(name) ?? [];
+function isActivePortalHost(registry: PortalRegistry, name: string, id: symbol) {
+  const stack = registry.hostStacks.get(name) ?? [];
   return stack.length > 0 && stack[0] === id;
 }
 
-function getSnapshot() {
-  return store.map;
-}
-
-function subscribe(cb: () => void) {
-  store.listeners.add(cb);
+function subscribePortals(registry: PortalRegistry, cb: () => void) {
+  registry.portalListeners.add(cb);
   return () => {
-    store.listeners.delete(cb);
+    registry.portalListeners.delete(cb);
   };
 }
 
-function updatePortal(hostName: string, name: string, children: React.ReactNode) {
-  const next = new Map(store.map);
-  const portal = next.get(hostName) ?? new Map<string, React.ReactNode>();
+function updatePortal(
+  registry: PortalRegistry,
+  hostName: string,
+  name: string,
+  children: React.ReactNode,
+) {
+  const next = new Map(registry.map);
+  const portal = new Map(next.get(hostName) ?? []);
   portal.set(name, children);
   next.set(hostName, portal);
-  store.map = next;
-  emit();
+  registry.map = next;
+  emitPortals(registry);
 }
 
-function removePortal(hostName: string, name: string) {
-  const next = new Map(store.map);
-  const portal = next.get(hostName) ?? new Map<string, React.ReactNode>();
+function removePortal(registry: PortalRegistry, hostName: string, name: string) {
+  const next = new Map(registry.map);
+  const portal = new Map(next.get(hostName) ?? []);
   portal.delete(name);
-  next.set(hostName, portal);
-  store.map = next;
-  emit();
+  if (portal.size === 0 && hostName !== DEFAULT_PORTAL_HOST) {
+    next.delete(hostName);
+  } else {
+    next.set(hostName, portal);
+  }
+  registry.map = next;
+  emitPortals(registry);
+}
+
+// --------------------------------------------------
+
+export function PortalProvider({ children }: Readonly<{ children: React.ReactNode }>) {
+  const [registry] = React.useState(createPortalRegistry);
+
+  return (
+    <PortalRegistryContext.Provider value={registry}>{children}</PortalRegistryContext.Provider>
+  );
 }
 
 // --------------------------------------------------
 
 export function PortalHost({ name = DEFAULT_PORTAL_HOST }: { name?: string }) {
+  const registry = React.useContext(PortalRegistryContext) ?? fallbackPortalRegistry;
   const hostId = React.useRef(Symbol()).current;
 
   useEffect(() => {
-    pushPortalHost(name, hostId);
+    pushPortalHost(registry, name, hostId);
     return () => {
-      popPortalHost(name, hostId);
+      popPortalHost(registry, name, hostId);
     };
-  }, [name, hostId]);
-
-  useSyncExternalStore(subscribeHostStack, getHostStackSnapshot, getHostStackSnapshot);
-
-  const map = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  }, [registry, name, hostId]);
+
+  useSyncExternalStore(
+    (cb) => subscribeHosts(registry, cb),
+    () => registry.hostStacks,
+    () => registry.hostStacks,
+  );
+
+  const map = useSyncExternalStore(
+    (cb) => subscribePortals(registry, cb),
+    () => registry.map,
+    () => registry.map,
+  );
   const portalMap = map.get(name) ?? new Map<string, React.ReactNode>();
 
-  if (!isActivePortalHost(name, hostId) || portalMap.size === 0) {
+  if (!isActivePortalHost(registry, name, hostId) || portalMap.size === 0) {
     return null;
   }
 
-  const content = <>{Array.from(portalMap.values())}</>;
+  const content = (
+    <>
+      {Array.from(portalMap.entries()).map(([portalName, children]) => (
+        <React.Fragment key={portalName}>{children}</React.Fragment>
+      ))}
+    </>
+  );
 
   if (Platform.OS === 'web' && createPortalFn && typeof document !== 'undefined') {
     return createPortalFn(content, document.body);
@@ -149,12 +184,17 @@ export function Portal({
   hostName?: string;
   children: React.ReactNode;
 }) {
+  const registry = React.useContext(PortalRegistryContext) ?? fallbackPortalRegistry;
+
+  useEffect(() => {
+    updatePortal(registry, hostName, name, children);
+  }, [registry, hostName, name, children]);
+
   useEffect(() => {
-    updatePortal(hostName, name, children);
     return () => {
-      removePortal(hostName, name);
+      removePortal(registry, hostName, name);
     };
-  }, [hostName, name, children]);
+  }, [registry, hostName, name]);
 
   return null;
 }