@cdx-ui/primitives 0.0.1-beta.98 → 0.1.0

package/src/overlay/OverlayContainer.tsx

@@ -10,6 +10,7 @@ import {
 } from 'react-native';
 import Animated, { type EntryOrExitLayoutType } from 'react-native-reanimated';
 import { createPortalFn } from '../utils/createPortal';
+import { MODAL_OVERLAY_Z_INDEX } from './constants';
 
 export interface OverlayContainerProps {
   onDismiss: () => void;
@@ -23,7 +24,7 @@ export interface OverlayContainerProps {
  * Cross-platform overlay container.
  *
  * - Web: renders children into a `createPortal` at `document.body` with
- *   `position: fixed` and `zIndex: 50`. Uses a plain `View` rather than
+ *   `position: fixed` and `MODAL_OVERLAY_Z_INDEX`. Uses a plain `View` rather than
  *   Reanimated's `Animated.View` because Reanimated's layout animations
  *   (`entering`/`exiting`) rely on `require()` calls that break silently
  *   in Vite production bundles, leaving elements stuck at opacity 0.
@@ -43,7 +44,9 @@ export function OverlayContainer({
 }: Readonly<OverlayContainerProps>) {
   if (Platform.OS === 'web' && createPortalFn) {
     return createPortalFn(
-      <View style={[{ position: 'fixed' as any, zIndex: 50 }, style]}>{children}</View>,
+      <View style={[{ position: 'fixed' as any, zIndex: MODAL_OVERLAY_Z_INDEX }, style]}>
+        {children}
+      </View>,
       document.body,
     );
   }
@@ -56,10 +59,12 @@ export function OverlayContainer({
         accessible={false}
         importantForAccessibility="no-hide-descendants"
       />
+      {/* Stable bounds prevent iOS Fabric from duplicating descendant shadow layers at the origin. */}
       <Animated.View
         entering={entering}
         exiting={exiting}
-        style={[{ position: 'absolute' }, style]}
+        pointerEvents="box-none"
+        style={[StyleSheet.absoluteFill, style]}
       >
         {children}
       </Animated.View>

package/src/overlay/OverlayStack.tsx

@@ -0,0 +1,202 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
+
+export type OverlayStackLayer = 'nonmodal' | 'modal' | 'notification';
+export type OverlayStackCapability = 'escape' | 'outside' | 'back';
+
+export interface OverlayStackMetadata {
+  /**
+   * Semantic layer used by hosts for visual and accessibility policy.
+   * Dismissal ownership follows activation order so a child opened from a modal
+   * handles Escape or outside interaction before its parent.
+   * @default 'nonmodal'
+   */
+  layer?: OverlayStackLayer;
+  /**
+   * Optional logical overlay identifier.
+   */
+  id?: string;
+  /**
+   * Optional parent overlay identifier for nested overlay diagnostics.
+   */
+  parentId?: string;
+  /**
+   * Optional group identifier for registrations owned by one logical overlay.
+   */
+  groupId?: string;
+}
+
+export interface OverlayStackRegistrationOptions extends OverlayStackMetadata {
+  active: boolean;
+  capabilities?: readonly OverlayStackCapability[];
+}
+
+export interface OverlayStackRegistrationResult {
+  id: string;
+  isTopmost: (capability: OverlayStackCapability) => boolean;
+}
+
+interface OverlayStackEntry {
+  token: symbol;
+  id: string;
+  layer: OverlayStackLayer;
+  parentId?: string;
+  groupId?: string;
+  capabilities: ReadonlySet<OverlayStackCapability>;
+  activationOrder: number;
+}
+
+interface OverlayStackRegistry {
+  register: (token: symbol, entry: Omit<OverlayStackEntry, 'token' | 'activationOrder'>) => void;
+  unregister: (token: symbol) => void;
+  isTopmost: (token: symbol, capability: OverlayStackCapability) => boolean;
+  subscribe: (listener: () => void) => () => void;
+  getSnapshot: () => number;
+}
+
+function createOverlayStackRegistry(): OverlayStackRegistry {
+  const entries = new Map<symbol, OverlayStackEntry>();
+  const listeners = new Set<() => void>();
+  let activationOrder = 0;
+  let version = 0;
+
+  const emit = () => {
+    version += 1;
+    for (const listener of listeners) listener();
+  };
+
+  return {
+    register(token, entry) {
+      activationOrder += 1;
+      entries.set(token, { ...entry, token, activationOrder });
+      emit();
+    },
+    unregister(token) {
+      if (entries.delete(token)) emit();
+    },
+    isTopmost(token, capability) {
+      const current = entries.get(token);
+      if (!current?.capabilities.has(capability)) return false;
+
+      let topmost = current;
+      for (const candidate of entries.values()) {
+        if (!candidate.capabilities.has(capability)) continue;
+
+        if (candidate.activationOrder > topmost.activationOrder) {
+          topmost = candidate;
+        }
+      }
+
+      return topmost.token === token;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot() {
+      return version;
+    },
+  };
+}
+
+const OverlayStackContext = createContext<OverlayStackRegistry | null>(null);
+const subscribeNoop = () => {
+  return () => undefined;
+};
+const getZeroSnapshot = () => 0;
+
+/**
+ * Scopes overlay ordering and dismissal coordination to a provider subtree.
+ * Hooks retain their standalone behavior when no provider is present.
+ */
+export function OverlayStackProvider({ children }: Readonly<{ children: React.ReactNode }>) {
+  const [registry] = React.useState(createOverlayStackRegistry);
+
+  return <OverlayStackContext.Provider value={registry}>{children}</OverlayStackContext.Provider>;
+}
+
+/**
+ * Registers one active overlay and reports whether it is topmost for a specific
+ * dismissal capability. Capabilities are resolved independently so a
+ * notification without dismissal capabilities never blocks a modal.
+ */
+export function useOverlayStackRegistration({
+  active,
+  capabilities = [],
+  layer = 'nonmodal',
+  id,
+  parentId,
+  groupId,
+}: OverlayStackRegistrationOptions): OverlayStackRegistrationResult {
+  const registry = useContext(OverlayStackContext);
+  const token = useRef(Symbol('forge-ui-overlay')).current;
+  const generatedId = `forge-ui-overlay-${useId()}`;
+  const resolvedId = id ?? generatedId;
+  const handlesEscape = capabilities.includes('escape');
+  const handlesOutside = capabilities.includes('outside');
+  const handlesBack = capabilities.includes('back');
+
+  useEffect(() => {
+    if (!registry || !active) return;
+
+    const resolvedCapabilities = new Set<OverlayStackCapability>();
+    if (handlesEscape) resolvedCapabilities.add('escape');
+    if (handlesOutside) resolvedCapabilities.add('outside');
+    if (handlesBack) resolvedCapabilities.add('back');
+
+    registry.register(token, {
+      id: resolvedId,
+      layer,
+      parentId,
+      groupId,
+      capabilities: resolvedCapabilities,
+    });
+
+    return () => {
+      registry.unregister(token);
+    };
+  }, [
+    active,
+    groupId,
+    handlesBack,
+    handlesEscape,
+    handlesOutside,
+    layer,
+    parentId,
+    registry,
+    resolvedId,
+    token,
+  ]);
+
+  useSyncExternalStore(
+    registry?.subscribe ?? subscribeNoop,
+    registry?.getSnapshot ?? getZeroSnapshot,
+    getZeroSnapshot,
+  );
+
+  const isTopmost = useCallback(
+    (capability: OverlayStackCapability) => {
+      if (!active) return false;
+
+      const handlesCapability =
+        (capability === 'escape' && handlesEscape) ||
+        (capability === 'outside' && handlesOutside) ||
+        (capability === 'back' && handlesBack);
+      if (!handlesCapability) return false;
+
+      return !registry || registry.isTopmost(token, capability);
+    },
+    [active, handlesBack, handlesEscape, handlesOutside, registry, token],
+  );
+
+  return { id: resolvedId, isTopmost };
+}

package/src/overlay/constants.ts

@@ -0,0 +1,11 @@
+/**
+ * Modal overlay z-index — above @gorhom/bottom-sheet internal layers (footer uses 9999)
+ * so Dialog / AlertDialog stack on top when opened from a bottom sheet.
+ */
+export const MODAL_OVERLAY_Z_INDEX = 10000;
+
+/**
+ * Notification overlay z-index — above modal surfaces while remaining
+ * nonmodal and pointer-transparent outside the notification content.
+ */
+export const NOTIFICATION_OVERLAY_Z_INDEX = 11000;

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';