@cdx-ui/primitives 0.0.1-beta.140 → 0.0.1-beta.141

package/src/month-picker/MonthPickerRoot.tsx

@@ -0,0 +1,183 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentRef,
+  type ReactNode,
+} from 'react';
+import { View, type ViewProps } from 'react-native';
+import type { DateComponentLabels, MonthId } from '@cdx-ui/formatters';
+import { resolveDateComponentLabels } from '@cdx-ui/formatters';
+import { mergeRefs, useControllableState } from '@cdx-ui/utils';
+import { DateFieldRoot } from '../date-field/DateFieldRoot';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import type { PickerSurfaceType } from '../date-picker/context';
+import { MonthPickerContext } from './context';
+
+export interface MonthPickerRootProps extends Omit<ViewProps, 'children'> {
+  asChild?: boolean;
+  children?: ReactNode;
+  className?: string;
+  value?: MonthId;
+  defaultValue?: MonthId;
+  /** Called with the new `MonthId`, or `undefined` when the selection is cleared. */
+  onValueChange?: (value: MonthId | undefined) => void;
+  /** Controlled open state. Use `defaultOpen` for the uncontrolled variant. */
+  isOpen?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  isDisabled?: boolean;
+  isReadOnly?: boolean;
+  isInvalid?: boolean;
+  isRequired?: boolean;
+  /** Earliest selectable month, applied to the embedded calendar. Build with `monthId(...)`. */
+  minValue?: MonthId;
+  /** Latest selectable month, applied to the embedded calendar. Build with `monthId(...)`. */
+  maxValue?: MonthId;
+  name?: string;
+  locale?: string;
+  labels?: Partial<DateComponentLabels>;
+}
+
+export const MonthPickerRoot = forwardRef<ComponentRef<typeof View>, MonthPickerRootProps>(
+  (
+    {
+      asChild,
+      children,
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      isOpen: openProp,
+      defaultOpen = false,
+      onOpenChange,
+      isDisabled: disabled = false,
+      isReadOnly,
+      isInvalid,
+      isRequired,
+      minValue,
+      maxValue,
+      locale = 'en-US',
+      labels: labelsProp,
+      ...props
+    },
+    ref,
+  ) => {
+    const labels = useMemo(() => resolveDateComponentLabels(labelsProp), [labelsProp]);
+    const [value, setValue] = useControllableState<MonthId | undefined>({
+      prop: valueProp,
+      defaultProp: defaultValue,
+      onChange: onValueChange,
+    });
+
+    const [open, setOpenState] = useControllableState<boolean>({
+      prop: openProp,
+      defaultProp: defaultOpen,
+      onChange: onOpenChange,
+    });
+
+    const [draftValue, setDraftValue] = useState<MonthId | undefined>(value);
+
+    const surfacesRef = useRef<Set<PickerSurfaceType>>(new Set());
+    const anchorRef = useRef<ComponentRef<typeof View>>(null);
+    const triggerRef = useRef<ComponentRef<typeof View>>(null);
+
+    const setOpen = useCallback(
+      (next: boolean) => {
+        if (disabled && next) {
+          return;
+        }
+        if (next) {
+          setDraftValue(value);
+        }
+        setOpenState(next);
+      },
+      [disabled, setOpenState, value],
+    );
+
+    const registerSurface = useCallback((type: PickerSurfaceType) => {
+      if (surfacesRef.current.has(type)) {
+        return;
+      }
+      surfacesRef.current.add(type);
+      if (surfacesRef.current.size > 1) {
+        console.warn(
+          '[Forge UI] MonthPicker: multiple presentation surfaces detected. Use only one of Popover, Dialog, or BottomSheet.',
+        );
+      }
+    }, []);
+
+    useEffect(() => {
+      setDraftValue(value);
+    }, [value]);
+
+    useEffect(() => {
+      if (!open) {
+        surfacesRef.current.clear();
+      }
+    }, [open]);
+
+    const contextValue = useMemo(
+      () => ({
+        value,
+        onValueChange: setValue,
+        draftValue,
+        setDraftValue,
+        open: open ?? false,
+        setOpen,
+        disabled,
+        minValue,
+        maxValue,
+        locale,
+        labels,
+        registerSurface,
+        anchorRef,
+        triggerRef,
+      }),
+      [
+        value,
+        setValue,
+        draftValue,
+        open,
+        setOpen,
+        disabled,
+        minValue,
+        maxValue,
+        locale,
+        labels,
+        registerSurface,
+      ],
+    );
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <MonthPickerContext.Provider value={contextValue}>
+        <Comp
+          ref={mergeRefs(ref, anchorRef)}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ disabled, open }))}
+        >
+          <DateFieldRoot
+            value={value}
+            onValueChange={(next) => setValue(next as MonthId | undefined)}
+            mode="month"
+            locale={locale}
+            labels={labelsProp}
+            isDisabled={disabled}
+            isReadOnly={isReadOnly}
+            isInvalid={isInvalid}
+            isRequired={isRequired}
+          >
+            {children}
+          </DateFieldRoot>
+        </Comp>
+      </MonthPickerContext.Provider>
+    );
+  },
+);
+
+MonthPickerRoot.displayName = 'MonthPickerRoot';

package/src/month-picker/context.tsx

@@ -0,0 +1,31 @@
+import { createContext, useContext, type RefObject } from 'react';
+import type { View } from 'react-native';
+import type { DateComponentLabels, MonthId } from '@cdx-ui/formatters';
+import type { PickerSurfaceType } from '../date-picker/context';
+
+export interface MonthPickerContextValue {
+  value?: MonthId;
+  onValueChange?: (value: MonthId | undefined) => void;
+  draftValue?: MonthId;
+  setDraftValue: (value: MonthId | undefined) => void;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  disabled: boolean;
+  minValue?: MonthId;
+  maxValue?: MonthId;
+  locale: string;
+  labels: DateComponentLabels;
+  registerSurface: (type: PickerSurfaceType) => void;
+  anchorRef: RefObject<View | null>;
+  triggerRef: RefObject<View | null>;
+}
+
+export const MonthPickerContext = createContext<MonthPickerContextValue | null>(null);
+
+export function useMonthPickerContext(): MonthPickerContextValue {
+  const ctx = useContext(MonthPickerContext);
+  if (!ctx) {
+    throw new Error('MonthPicker compound components must be used within MonthPickerRoot');
+  }
+  return ctx;
+}

package/src/month-picker/index.ts

@@ -0,0 +1,3 @@
+export { MonthPickerRoot } from './MonthPickerRoot';
+export type { MonthPickerRootProps } from './MonthPickerRoot';
+export { MonthPickerContext, useMonthPickerContext, type MonthPickerContextValue } from './context';

package/src/overlay/useAnchorPosition.ts

@@ -78,21 +78,35 @@ export function useAnchorPosition(
 
     let cancelled = false;
 
-    if (Platform.OS === 'web') {
-      measureAnchor();
-    } else {
-      const anchor = anchorRef.current;
-      if (!anchor) {
-        return;
+    const runMeasure = () => {
+      if (!cancelled) {
+        measureAnchor();
       }
+    };
+
+    runMeasure();
 
-      anchor.measureInWindow((x: number, y: number, width: number, height: number) => {
-        if (!cancelled) {
-          setLayoutIfChanged(setLayout, { x, y, width, height });
-        }
-      });
+    if (Platform.OS === 'web') {
+      const frame = requestAnimationFrame(runMeasure);
+      return () => {
+        cancelled = true;
+        cancelAnimationFrame(frame);
+      };
     }
 
+    const anchor = anchorRef.current;
+    if (!anchor) {
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    anchor.measureInWindow((x: number, y: number, width: number, height: number) => {
+      if (!cancelled) {
+        setLayoutIfChanged(setLayout, { x, y, width, height });
+      }
+    });
+
     return () => {
       cancelled = true;
     };

package/src/overlay/useDismissOverlay.web.ts

@@ -1,6 +1,14 @@
 import type { RefObject } from 'react';
 import { useEffect, useRef } from 'react';
 
+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
  * focus moves to an element outside the overlay via keyboard.
@@ -24,11 +32,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;
         }
       }

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;
 
@@ -71,7 +74,7 @@ export function useOverlayPosition(anchorLayout: AnchorLayout | null): OverlayPo
       const maxHeight = Math.max(0, spaceBelow);
       return {
         style: {
-          top: anchorBottom,
+          top: anchorBottom + POPOVER_GAP,
           left: anchorLayout.x,
           width: anchorLayout.width,
           maxHeight,
@@ -84,7 +87,7 @@ export function useOverlayPosition(anchorLayout: AnchorLayout | null): OverlayPo
     const maxHeight = Math.max(0, spaceAbove);
     return {
       style: {
-        bottom: viewportHeight - anchorLayout.y,
+        bottom: viewportHeight - anchorLayout.y + POPOVER_GAP,
         left: anchorLayout.x,
         width: anchorLayout.width,
         maxHeight,

package/src/portal/portal.tsx

@@ -1,6 +1,7 @@
 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';
 
@@ -17,12 +18,67 @@ const store: PortalStore = {
   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 emitHostStack() {
+  for (const cb of hostStackStore.listeners) cb();
+}
+
+function getHostStackSnapshot() {
+  return hostStackStore.stacks;
+}
+
+function subscribeHostStack(cb: () => void) {
+  hostStackStore.listeners.add(cb);
+  return () => {
+    hostStackStore.listeners.delete(cb);
+  };
+}
+
+function pushPortalHost(name: string, id: symbol) {
+  const stacks = new Map(hostStackStore.stacks);
+  const stack = [...(stacks.get(name) ?? [])];
+  stack.push(id);
+  stacks.set(name, stack);
+  hostStackStore.stacks = stacks;
+
+  if (__DEV__ && !hasWarnedMultiplePortalHosts && stack.length > 1) {
+    hasWarnedMultiplePortalHosts = 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).',
+    );
+  }
+
+  emitHostStack();
+}
+
+function popPortalHost(name: string, id: symbol) {
+  const stacks = new Map(hostStackStore.stacks);
+  const stack = (stacks.get(name) ?? []).filter((entry) => entry !== id);
+  stacks.set(name, stack);
+  hostStackStore.stacks = stacks;
+  emitHostStack();
+}
+
+function isActivePortalHost(name: string, id: symbol) {
+  const stack = hostStackStore.stacks.get(name) ?? [];
+  return stack.length > 0 && stack[0] === id;
+}
+
 function getSnapshot() {
   return store.map;
 }
@@ -55,10 +111,31 @@ function removePortal(hostName: string, name: string) {
 // --------------------------------------------------
 
 export function PortalHost({ name = DEFAULT_PORTAL_HOST }: { name?: string }) {
+  const hostId = React.useRef(Symbol()).current;
+
+  useEffect(() => {
+    pushPortalHost(name, hostId);
+    return () => {
+      popPortalHost(name, hostId);
+    };
+  }, [name, hostId]);
+
+  useSyncExternalStore(subscribeHostStack, getHostStackSnapshot, getHostStackSnapshot);
+
   const map = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
   const portalMap = map.get(name) ?? new Map<string, React.ReactNode>();
-  if (portalMap.size === 0) return null;
-  return <>{Array.from(portalMap.values())}</>;
+
+  if (!isActivePortalHost(name, hostId) || portalMap.size === 0) {
+    return null;
+  }
+
+  const content = <>{Array.from(portalMap.values())}</>;
+
+  if (Platform.OS === 'web' && createPortalFn && typeof document !== 'undefined') {
+    return createPortalFn(content, document.body);
+  }
+
+  return content;
 }
 
 // --------------------------------------------------

package/src/range-calendar/RangeCalendarRoot.tsx

@@ -0,0 +1,213 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentRef,
+  type ReactNode,
+} from 'react';
+import { View, type ViewProps } from 'react-native';
+import {
+  normalizeDateRange,
+  resolveDateComponentLabels,
+  todayMonthId,
+  toMonthId,
+  type DateComponentLabels,
+  type DateId,
+  type MonthId,
+} from '@cdx-ui/formatters';
+import { useControllableState } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { accessibleLabelAttributes, resolveAccessibleLabel } from '../utils/accessibleLabel';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import type { CalendarView } from '../calendar/context';
+import { RangeCalendarContext, type RangeCalendarFocus } from './context';
+
+export interface RangeCalendarRootProps extends Omit<ViewProps, 'children'> {
+  asChild?: boolean;
+  children?: ReactNode;
+  className?: string;
+  startValue?: DateId;
+  endValue?: DateId;
+  defaultStartValue?: DateId;
+  defaultEndValue?: DateId;
+  onRangeChange?: (range: { startId?: DateId; endId?: DateId }) => void;
+  monthId?: MonthId;
+  defaultMonthId?: MonthId;
+  onMonthIdChange?: (monthId: MonthId) => void;
+  focusedField?: RangeCalendarFocus;
+  defaultFocusedField?: RangeCalendarFocus;
+  onFocusedFieldChange?: (field: RangeCalendarFocus) => void;
+  /** Earliest selectable date. Build with `dateId(...)` from `@cdx-ui/formatters`. */
+  minValue?: DateId;
+  /** Latest selectable date. Build with `dateId(...)` from `@cdx-ui/formatters`. */
+  maxValue?: DateId;
+  disabled?: boolean;
+  locale?: string;
+  labels?: Partial<DateComponentLabels>;
+  /** Accessible name for the range-calendar region. */
+  accessibilityLabel?: string;
+}
+
+export const RangeCalendarRoot = forwardRef<ComponentRef<typeof View>, RangeCalendarRootProps>(
+  (props, ref) => {
+    const {
+      asChild,
+      children,
+      startValue: startProp,
+      endValue: endProp,
+      defaultStartValue,
+      defaultEndValue,
+      onRangeChange,
+      monthId: monthIdProp,
+      defaultMonthId,
+      onMonthIdChange,
+      focusedField: focusedProp,
+      defaultFocusedField = 'start',
+      onFocusedFieldChange,
+      minValue,
+      maxValue,
+      disabled = false,
+      locale = 'en-US',
+      labels: labelsProp,
+      accessibilityLabel: accessibilityLabelProp,
+      'aria-label': ariaLabelProp,
+      ...rest
+    } = props;
+
+    const labels = useMemo(() => resolveDateComponentLabels(labelsProp), [labelsProp]);
+    const accessibilityLabel = resolveAccessibleLabel({
+      accessibilityLabel: accessibilityLabelProp,
+      'aria-label': ariaLabelProp,
+    });
+
+    const isRangeControlled = 'startValue' in props || 'endValue' in props;
+    const [uncontrolledStart, setUncontrolledStart] = useState<DateId | undefined>(
+      defaultStartValue,
+    );
+    const [uncontrolledEnd, setUncontrolledEnd] = useState<DateId | undefined>(defaultEndValue);
+
+    const startId = isRangeControlled ? startProp : uncontrolledStart;
+    const endId = isRangeControlled ? endProp : uncontrolledEnd;
+
+    const [monthId, setMonthId] = useControllableState<MonthId>({
+      prop: monthIdProp,
+      defaultProp:
+        defaultMonthId ??
+        (startId ? toMonthId(startId) : endId ? toMonthId(endId) : todayMonthId()),
+      onChange: onMonthIdChange,
+    });
+
+    const prevRangeRef = useRef({ startId, endId });
+    useEffect(() => {
+      if (monthIdProp !== undefined) {
+        prevRangeRef.current = { startId, endId };
+        return;
+      }
+      if (prevRangeRef.current.startId === startId && prevRangeRef.current.endId === endId) {
+        return;
+      }
+      prevRangeRef.current = { startId, endId };
+      const anchor = startId ?? endId;
+      if (anchor !== undefined) {
+        setMonthId(toMonthId(anchor));
+      }
+    }, [endId, monthIdProp, setMonthId, startId]);
+
+    const [focusedField, setFocusedField] = useControllableState<RangeCalendarFocus>({
+      prop: focusedProp,
+      defaultProp: defaultFocusedField,
+      onChange: onFocusedFieldChange,
+    });
+
+    const [view, setViewState] = useState<CalendarView>('month');
+
+    const setView = useCallback((next: CalendarView) => {
+      setViewState(next);
+    }, []);
+
+    const onDayPress = useCallback(
+      (dateId: DateId) => {
+        if (disabled) {
+          return;
+        }
+
+        let next: { startId: DateId; endId?: DateId };
+
+        // Empty or complete range → start a new selection at this day.
+        if (!startId || endId) {
+          next = { startId: dateId, endId: undefined };
+          setFocusedField('end');
+        } else {
+          // Incomplete range (start only) → set end and normalize order.
+          next = normalizeDateRange({ startId, endId: dateId });
+          setFocusedField('start');
+        }
+
+        if (!isRangeControlled) {
+          setUncontrolledStart(next.startId);
+          setUncontrolledEnd(next.endId);
+        }
+        onRangeChange?.(next);
+      },
+      [disabled, endId, isRangeControlled, onRangeChange, setFocusedField, startId],
+    );
+
+    const contextValue = useMemo(
+      () => ({
+        startId,
+        endId,
+        onRangeChange,
+        monthId: monthId ?? todayMonthId(),
+        onMonthIdChange: setMonthId,
+        focusedField: focusedField ?? 'start',
+        onFocusedFieldChange: setFocusedField,
+        minValue,
+        maxValue,
+        disabled,
+        locale,
+        labels,
+        onDayPress,
+        view,
+        setView,
+      }),
+      [
+        startId,
+        endId,
+        onRangeChange,
+        monthId,
+        setMonthId,
+        focusedField,
+        setFocusedField,
+        minValue,
+        maxValue,
+        disabled,
+        locale,
+        labels,
+        onDayPress,
+        view,
+        setView,
+      ],
+    );
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <RangeCalendarContext.Provider value={contextValue}>
+        <Comp
+          ref={ref}
+          accessibilityRole="none"
+          {...rest}
+          {...mergeDataAttributes(rest, dataAttributes({ disabled }))}
+          {...accessibleLabelAttributes(accessibilityLabel)}
+        >
+          {children}
+        </Comp>
+      </RangeCalendarContext.Provider>
+    );
+  },
+);
+
+RangeCalendarRoot.displayName = 'RangeCalendarRoot';

package/src/range-calendar/context.tsx

@@ -0,0 +1,33 @@
+import { createContext, useContext } from 'react';
+import type { DateComponentLabels, DateId, MonthId } from '@cdx-ui/formatters';
+import type { CalendarView } from '../calendar/context';
+
+export type RangeCalendarFocus = 'start' | 'end';
+
+export interface RangeCalendarContextValue {
+  startId?: DateId;
+  endId?: DateId;
+  onRangeChange?: (range: { startId?: DateId; endId?: DateId }) => void;
+  monthId: MonthId;
+  onMonthIdChange: (monthId: MonthId) => void;
+  focusedField: RangeCalendarFocus;
+  onFocusedFieldChange: (field: RangeCalendarFocus) => void;
+  minValue?: DateId;
+  maxValue?: DateId;
+  disabled: boolean;
+  locale: string;
+  labels: DateComponentLabels;
+  onDayPress: (dateId: DateId) => void;
+  view: CalendarView;
+  setView: (view: CalendarView) => void;
+}
+
+export const RangeCalendarContext = createContext<RangeCalendarContextValue | null>(null);
+
+export function useRangeCalendarContext(): RangeCalendarContextValue {
+  const ctx = useContext(RangeCalendarContext);
+  if (!ctx) {
+    throw new Error('RangeCalendar compound components must be used within RangeCalendarRoot');
+  }
+  return ctx;
+}

package/src/range-calendar/index.ts

@@ -0,0 +1,4 @@
+export { RangeCalendarRoot } from './RangeCalendarRoot';
+export type { RangeCalendarRootProps } from './RangeCalendarRoot';
+export { useRangeCalendarContext } from './context';
+export type { RangeCalendarFocus } from './context';

package/src/select/SelectRoot.tsx

@@ -28,7 +28,7 @@ export const SelectRoot = forwardRef<ComponentRef<typeof View>, SelectRootProps>
       value: valueProp,
       defaultValue,
       onValueChange,
-      open: openProp,
+      isOpen: openProp,
       defaultOpen = false,
       onOpenChange,
       disabled = false,