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

package/src/menu/useMenuTrigger.ts

@@ -0,0 +1,161 @@
+import { useCallback, useMemo, useRef, type ForwardedRef, type RefCallback } from 'react';
+import { type GestureResponderEvent, type PressableProps } from 'react-native';
+import { composeEventHandlers, mergeRefs } from '@cdx-ui/utils';
+import { useFocus } from '@react-native-aria/focus';
+import { useHover } from '@react-native-aria/interactions';
+import type { InteractionState } from '../types';
+import { useMenuOverlayContext } from './overlayContext';
+
+export interface UseMenuTriggerOptions {
+  asChild?: boolean;
+  onPress?: PressableProps['onPress'];
+  onHoverIn?: PressableProps['onHoverIn'];
+  onHoverOut?: PressableProps['onHoverOut'];
+  onFocus?: (...args: unknown[]) => unknown;
+  onBlur?: (...args: unknown[]) => unknown;
+  onKeyDown?: (e: KeyboardEvent) => void;
+}
+
+export interface MenuTriggerAriaProps {
+  role: 'button';
+  id: string;
+  'aria-haspopup': 'menu';
+  'aria-expanded': boolean;
+  'aria-controls': string;
+  disabled: boolean;
+}
+
+export interface UseMenuTriggerReturn {
+  ariaProps: MenuTriggerAriaProps;
+  interactionState: Pick<InteractionState, 'hover' | 'focus' | 'disabled'>;
+  mergedRef: RefCallback<unknown>;
+  handlers: {
+    onPress: (e: GestureResponderEvent) => void;
+    onHoverIn: NonNullable<PressableProps['onHoverIn']>;
+    onHoverOut: NonNullable<PressableProps['onHoverOut']>;
+    onFocus: (...args: unknown[]) => unknown;
+    onBlur: (...args: unknown[]) => unknown;
+    onKeyDown: (e: KeyboardEvent) => void;
+  };
+}
+
+export function useMenuTrigger(
+  forwardedRef: ForwardedRef<unknown>,
+  options: UseMenuTriggerOptions,
+): UseMenuTriggerReturn {
+  const {
+    onPress: consumerOnPress,
+    onHoverIn: consumerOnHoverIn,
+    onHoverOut: consumerOnHoverOut,
+    onFocus: consumerOnFocus,
+    onBlur: consumerOnBlur,
+    onKeyDown: consumerOnKeyDown,
+  } = options;
+
+  const { open, setOpen, closeMenu, disabled, triggerRef, triggerId, menuId, focusOnOpenRef } =
+    useMenuOverlayContext();
+  const pendingKeyboardOpenRef = useRef<'first' | 'last' | null>(null);
+
+  const { isFocused, focusProps } = useFocus();
+  const { isHovered, hoverProps } = useHover();
+  const clearPendingKeyboardOpen = useCallback(() => {
+    pendingKeyboardOpenRef.current = null;
+  }, []);
+
+  const handlePress = useCallback(
+    (_e: GestureResponderEvent) => {
+      if (disabled) {
+        return;
+      }
+
+      if (open) {
+        pendingKeyboardOpenRef.current = null;
+        closeMenu('trigger');
+        return;
+      }
+
+      focusOnOpenRef.current = pendingKeyboardOpenRef.current ?? 'menu';
+      pendingKeyboardOpenRef.current = null;
+      setOpen(true);
+    },
+    [closeMenu, disabled, focusOnOpenRef, open, setOpen],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      if (disabled) {
+        return;
+      }
+
+      switch (e.key) {
+        case 'Enter':
+        case ' ': {
+          e.preventDefault();
+          pendingKeyboardOpenRef.current = 'first';
+          break;
+        }
+        case 'ArrowDown': {
+          e.preventDefault();
+          pendingKeyboardOpenRef.current = null;
+          focusOnOpenRef.current = 'first';
+          setOpen(true);
+          break;
+        }
+        case 'ArrowUp': {
+          e.preventDefault();
+          pendingKeyboardOpenRef.current = null;
+          focusOnOpenRef.current = 'last';
+          setOpen(true);
+          break;
+        }
+      }
+    },
+    [disabled, focusOnOpenRef, setOpen],
+  );
+
+  const interactionState = useMemo(
+    () => ({
+      hover: !!isHovered,
+      focus: !!isFocused,
+      disabled: !!disabled,
+    }),
+    [isHovered, isFocused, disabled],
+  );
+
+  const mergedRef = mergeRefs(forwardedRef, triggerRef);
+
+  const ariaProps: MenuTriggerAriaProps = {
+    role: 'button',
+    id: triggerId,
+    'aria-haspopup': 'menu',
+    'aria-expanded': open,
+    'aria-controls': menuId,
+    disabled,
+  };
+
+  const handlers = {
+    onPress: composeEventHandlers(
+      consumerOnPress,
+      handlePress,
+    ) as UseMenuTriggerReturn['handlers']['onPress'],
+    onHoverIn: composeEventHandlers(
+      consumerOnHoverIn,
+      hoverProps.onHoverIn,
+    ) as UseMenuTriggerReturn['handlers']['onHoverIn'],
+    onHoverOut: composeEventHandlers(
+      consumerOnHoverOut,
+      hoverProps.onHoverOut,
+    ) as UseMenuTriggerReturn['handlers']['onHoverOut'],
+    onFocus: composeEventHandlers(consumerOnFocus, focusProps.onFocus),
+    onBlur: composeEventHandlers(
+      composeEventHandlers(consumerOnBlur, focusProps.onBlur),
+      clearPendingKeyboardOpen,
+    ),
+    onKeyDown: composeEventHandlers(
+      consumerOnKeyDown,
+      handleKeyDown,
+    ) as UseMenuTriggerReturn['handlers']['onKeyDown'],
+  };
+
+  return { ariaProps, interactionState, mergedRef, handlers };
+}

package/src/overlay/OverlayContainer.tsx

@@ -59,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

@@ -3,3 +3,9 @@
  * 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,326 @@
+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;
+    }
+  }
+
+  let left: number;
+  let top: number;
+
+  if (side === 'top' || side === 'bottom') {
+    left =
+      alignCoordinate(
+        anchor.x,
+        anchor.width,
+        measuredFloating.width,
+        align,
+        options.isRTL ?? false,
+      ) + crossOffset;
+    top =
+      side === 'top'
+        ? anchor.y - offset - measuredFloating.height
+        : anchor.y + anchor.height + offset;
+  } else {
+    left =
+      side === 'left'
+        ? anchor.x - offset - measuredFloating.width
+        : anchor.x + anchor.width + offset;
+    top =
+      alignCoordinate(anchor.y, anchor.height, measuredFloating.height, align, false) + crossOffset;
+  }
+
+  if (collisionBehavior === 'flip-shift') {
+    if (side === 'top' || side === 'bottom') {
+      left = clamp(left, boundary.left, boundary.right - measuredFloating.width);
+    } else {
+      top = clamp(top, boundary.top, boundary.bottom - measuredFloating.height);
+    }
+  }
+
+  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 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,
+            measuredFloating.width - arrowBoundaryOffset,
+          ),
+        }
+      : {
+          y: clamp(
+            anchorCenterY - top,
+            arrowBoundaryOffset,
+            measuredFloating.height - arrowBoundaryOffset,
+          ),
+        };
+  const resolvedPlacement = { side, align };
+
+  return {
+    style: {
+      left,
+      top,
+      width: options.width === 'anchor' ? anchor.width : undefined,
+      maxWidth: availableWidth,
+      maxHeight: availableHeight,
+    },
+    resolvedPlacement,
+    placement: stringifyPlacement(resolvedPlacement),
+    availableWidth,
+    availableHeight,
+    arrow,
+    transformOrigin: getTransformOrigin(side, arrow, measuredFloating),
+  };
+}