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

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

package/src/portal/index.ts

@@ -0,0 +1 @@
+export * from './portal';

package/src/portal/portal.tsx

@@ -0,0 +1,233 @@
+import * as React from 'react';
+import { useEffect, useSyncExternalStore } from 'react';
+import { Platform, type View, type ViewStyle } from 'react-native';
+import { createPortalFn } from '../utils/createPortal';
+
+const DEFAULT_PORTAL_HOST = 'FORGE_UI_DEFAULT_HOST_NAME';
+
+type PortalMap = Map<string, React.ReactNode>;
+type PortalHostMap = Map<string, PortalMap>;
+
+interface PortalRegistry {
+  map: PortalHostMap;
+  hostStacks: Map<string, symbol[]>;
+  portalListeners: Set<() => void>;
+  hostListeners: Set<() => void>;
+  hasWarnedMultipleHosts: boolean;
+}
+
+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,
+  };
+}
+
+/**
+ * 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 emitHosts(registry: PortalRegistry) {
+  for (const cb of registry.hostListeners) cb();
+}
+
+function subscribeHosts(registry: PortalRegistry, cb: () => void) {
+  registry.hostListeners.add(cb);
+  return () => {
+    registry.hostListeners.delete(cb);
+  };
+}
+
+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);
+  registry.hostStacks = stacks;
+
+  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. ' +
+        'Mount a single PortalHost near your app root (ForgeDesignProvider does this automatically).',
+    );
+  }
+
+  emitHosts(registry);
+}
+
+function popPortalHost(registry: PortalRegistry, name: string, id: symbol) {
+  const stacks = new Map(registry.hostStacks);
+  const stack = (stacks.get(name) ?? []).filter((entry) => entry !== id);
+  if (stack.length === 0) {
+    stacks.delete(name);
+  } else {
+    stacks.set(name, stack);
+  }
+  registry.hostStacks = stacks;
+  emitHosts(registry);
+}
+
+function isActivePortalHost(registry: PortalRegistry, name: string, id: symbol) {
+  const stack = registry.hostStacks.get(name) ?? [];
+  return stack.length > 0 && stack[0] === id;
+}
+
+function subscribePortals(registry: PortalRegistry, cb: () => void) {
+  registry.portalListeners.add(cb);
+  return () => {
+    registry.portalListeners.delete(cb);
+  };
+}
+
+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);
+  registry.map = next;
+  emitPortals(registry);
+}
+
+function removePortal(registry: PortalRegistry, hostName: string, name: string) {
+  const next = new Map(registry.map);
+  const portal = new Map(next.get(hostName) ?? []);
+  portal.delete(name);
+  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(registry, name, hostId);
+    return () => {
+      popPortalHost(registry, name, hostId);
+    };
+  }, [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(registry, name, hostId) || portalMap.size === 0) {
+    return null;
+  }
+
+  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);
+  }
+
+  return content;
+}
+
+// --------------------------------------------------
+
+export function Portal({
+  name,
+  hostName = DEFAULT_PORTAL_HOST,
+  children,
+}: {
+  name: string;
+  hostName?: string;
+  children: React.ReactNode;
+}) {
+  const registry = React.useContext(PortalRegistryContext) ?? fallbackPortalRegistry;
+
+  useEffect(() => {
+    updatePortal(registry, hostName, name, children);
+  }, [registry, hostName, name, children]);
+
+  useEffect(() => {
+    return () => {
+      removePortal(registry, hostName, name);
+    };
+  }, [registry, hostName, name]);
+
+  return null;
+}
+
+// --------------------------------------------------
+
+const ROOT: ViewStyle = {
+  flex: 1,
+};
+
+/**
+ * @deprecated use `FullWindowOverlay` from `react-native-screens` instead
+ * @example
+import { FullWindowOverlay } from "react-native-screens"
+const WindowOverlay = Platform.OS === "ios" ? FullWindowOverlay : Fragment
+// Wrap the `<PortalHost/>` with `<WindowOverlay/>`
+<WindowOverlay><PortalHost/></WindowOverlay>
+ */
+export function useModalPortalRoot() {
+  const ref = React.useRef<View>(null);
+  const [offset, setSideOffSet] = React.useState(0);
+
+  const onLayout = React.useCallback(() => {
+    if (Platform.OS === 'web') return;
+    ref.current?.measure((_x, _y, _width, _height, _pageX, pageY) => {
+      setSideOffSet(-pageY);
+    });
+  }, []);
+
+  return {
+    ref,
+    offset,
+    onLayout,
+    style: ROOT,
+  };
+}

package/src/progress-bar/ProgressBarIndicator.tsx

@@ -0,0 +1,34 @@
+import { forwardRef, useMemo } from 'react';
+import { View, type ViewProps, type ViewStyle } from 'react-native';
+import { Slot } from '../slot';
+import { dataAttributes } from '../utils/dataAttributes';
+import { useProgressContext } from './context';
+
+type PercentString = `${number}%`;
+
+export interface ProgressBarIndicatorProps extends ViewProps {
+  readonly asChild?: boolean;
+}
+
+export const ProgressBarIndicator = forwardRef<View, ProgressBarIndicatorProps>(
+  ({ asChild, style, ...rest }, ref) => {
+    const { percent, state, max, value } = useProgressContext();
+
+    const filledStyle = useMemo((): ViewStyle => {
+      const pct = `${String(percent)}%` as PercentString;
+      return { width: pct, height: '100%' };
+    }, [percent]);
+
+    const dataAttrs = dataAttributes({
+      state,
+      value: value === null ? undefined : String(value),
+      max: String(max),
+    });
+
+    const Comp = asChild ? Slot : View;
+
+    return <Comp ref={ref} {...rest} {...dataAttrs} style={[filledStyle, style]} />;
+  },
+);
+
+ProgressBarIndicator.displayName = 'ProgressBarIndicator';

package/src/progress-bar/ProgressBarRoot.tsx

@@ -0,0 +1,117 @@
+import { forwardRef, useMemo } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { Slot } from '../slot';
+import { dataAttributes } from '../utils/dataAttributes';
+import { ProgressProvider } from './context';
+import type { InterfaceProgressProps, ProgressDataState } from './types';
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, n));
+}
+
+function resolveState(
+  value: number | null,
+  max: number,
+  clamped: number | null,
+): ProgressDataState {
+  if (value === null) {
+    return 'indeterminate';
+  }
+  if (max <= 0) {
+    return 'complete';
+  }
+  if (clamped !== null && clamped >= max) {
+    return 'complete';
+  }
+  return 'loading';
+}
+
+function defaultGetValueLabel(value: number, max: number): string {
+  if (max <= 0) {
+    return '0%';
+  }
+  return `${String(Math.round((value / max) * 100))}%`;
+}
+
+export const ProgressBarRoot = forwardRef<View, InterfaceProgressProps & { asChild?: boolean }>(
+  (props, ref) => {
+    const {
+      asChild,
+      value: valueProp = 0,
+      max: maxProp = 100,
+      getValueLabel = defaultGetValueLabel,
+      children,
+      accessibilityRole = 'progressbar',
+      accessibilityValue: accessibilityValueProp,
+      role = 'progressbar',
+      ...restProps
+    } = props;
+
+    const max = maxProp > 0 ? maxProp : 0;
+    const isIndeterminate = valueProp === null;
+    const clampedValue =
+      valueProp === null ? null : clamp(Number.isFinite(valueProp) ? valueProp : 0, 0, max);
+
+    const percent = useMemo(() => {
+      if (clampedValue === null || max <= 0) {
+        return 0;
+      }
+      return (clampedValue / max) * 100;
+    }, [clampedValue, max]);
+
+    const state = useMemo(
+      () => resolveState(valueProp, max, clampedValue),
+      [valueProp, max, clampedValue],
+    );
+
+    const contextValue = useMemo(
+      () => ({
+        value: clampedValue,
+        max,
+        percent,
+        state,
+      }),
+      [clampedValue, max, percent, state],
+    );
+
+    const dataAttrs = dataAttributes({
+      state,
+      value: clampedValue === null ? undefined : String(clampedValue),
+      max: String(max),
+    });
+
+    const accessibilityValue = useMemo(() => {
+      if (accessibilityValueProp !== undefined) {
+        return accessibilityValueProp;
+      }
+      if (isIndeterminate || clampedValue === null) {
+        return { min: 0, max, text: 'Indeterminate' };
+      }
+      return {
+        min: 0,
+        max,
+        now: clampedValue,
+        text: getValueLabel(clampedValue, max),
+      };
+    }, [accessibilityValueProp, isIndeterminate, clampedValue, max, getValueLabel]);
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <ProgressProvider value={contextValue}>
+        <Comp
+          ref={ref}
+          {...(restProps as ViewProps)}
+          role={role}
+          accessibilityRole={accessibilityRole}
+          accessibilityValue={accessibilityValue}
+          {...dataAttrs}
+        >
+          {children}
+        </Comp>
+      </ProgressProvider>
+    );
+  },
+);
+
+ProgressBarRoot.displayName = 'ProgressBarRoot';

package/src/progress-bar/index.ts

@@ -0,0 +1,5 @@
+export type { IProgressProps, ProgressDataState } from './types';
+export type { ProgressContextValue } from './context';
+export { useProgressContext } from './context';
+export { ProgressBarRoot } from './ProgressBarRoot';
+export { ProgressBarIndicator, type ProgressBarIndicatorProps } from './ProgressBarIndicator';

package/src/progress-bar/types.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+import type { ViewProps } from 'react-native';
+
+export type ProgressDataState = 'complete' | 'indeterminate' | 'loading';
+
+export interface InterfaceProgressProps extends Omit<ViewProps, 'children'> {
+  /**
+   * Current value in the range [0, max], or `null` for indeterminate progress.
+   * Omit or use a number for determinate progress; default is `0`.
+   */
+  readonly value?: number | null;
+  /**
+   * Maximum value (minimum is always 0).
+   * @default 100
+   */
+  readonly max?: number;
+  /**
+   * Optional label for `accessibilityValue.text` when determinate.
+   */
+  readonly getValueLabel?: (value: number, max: number) => string;
+  readonly children?: ReactNode;
+}
+
+export type IProgressProps = InterfaceProgressProps;