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

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/radio/RadioGroup.tsx

@@ -1,12 +1,13 @@
-import { forwardRef } from 'react';
-import { View, type ViewProps } from 'react-native';
-import { useFormControlContext } from '@cdx-ui/utils';
+import { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
+import { Platform, View, type ViewProps } from 'react-native';
+import { composeEventHandlers, useFormControl } from '@cdx-ui/utils';
 import { useRadioGroup } from '@react-native-aria/radio';
 import { useRadioGroupState } from '@react-stately/radio';
 import { Slot } from '../slot';
 import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
 import { RadioGroupContext } from './context';
-import type { IRadioGroupProps } from './types';
+import type { IRadioGroupProps, RegisteredRadio } from './types';
+import { useRadioGroupNavigation } from './useRadioGroupNavigation';
 
 export interface RadioGroupRootProps extends IRadioGroupProps {
   asChild?: boolean;
@@ -16,30 +17,86 @@ export interface RadioGroupRootProps extends IRadioGroupProps {
 
 export const RadioGroup = forwardRef<View, RadioGroupRootProps>(
   ({ asChild, children, className, style, ...props }, ref) => {
-    const formControlContext = useFormControlContext();
+    const formControlProps = useFormControl({
+      isDisabled: props.isDisabled,
+      isRequired: props.isRequired,
+      isInvalid: props.isInvalid,
+      isReadOnly: props.isReadOnly,
+    });
 
-    const combinedProps = {
-      ...formControlContext,
-      ...props,
-    };
+    const isDisabled = props.isDisabled ?? Boolean(formControlProps.disabled);
+    const isInvalid = props.isInvalid ?? Boolean(formControlProps['aria-invalid']);
+    const isRequired = props.isRequired ?? Boolean(formControlProps.required);
+    const isReadOnly = props.isReadOnly ?? Boolean(formControlProps.readOnly);
+    const name = props.name ?? formControlProps.name;
+    const ariaLabel = props['aria-label'];
+    const ariaLabelledBy = props['aria-labelledby'] ?? formControlProps['aria-labelledby'];
+    const ariaDescribedBy = formControlProps['aria-describedby'];
 
     const radioGroupState = useRadioGroupState({
-      ...combinedProps,
-      validationState: combinedProps.isInvalid ? 'invalid' : 'valid',
+      name,
+      value: props.value,
+      defaultValue: props.defaultValue,
+      onChange: props.onChange,
+      isDisabled,
+      isInvalid,
+      isRequired,
+      isReadOnly,
+      validationState: isInvalid ? 'invalid' : 'valid',
     });
 
     const { radioGroupProps } = useRadioGroup(
       {
-        ...combinedProps,
-        'aria-label': combinedProps['aria-label'],
+        'aria-label': ariaLabel,
+        'aria-labelledby': ariaLabelledBy,
+        isDisabled,
       },
       radioGroupState,
     );
 
-    const isDisabled = combinedProps.isDisabled ?? false;
-    const isInvalid = combinedProps.isInvalid ?? false;
-    const isRequired = combinedProps.isRequired ?? false;
-    const isReadOnly = combinedProps.isReadOnly ?? false;
+    const [focusedValue, setFocusedValue] = useState<string | undefined>(undefined);
+    // Identity of getRadios depends on this so roving tabIndex recomputes after register/unregister.
+    const [registrationEpoch, setRegistrationEpoch] = useState(0);
+    const radiosRef = useRef<Map<string, RegisteredRadio>>(new Map());
+
+    useEffect(() => {
+      setFocusedValue((prev) =>
+        prev !== undefined && prev !== radioGroupState.selectedValue ? undefined : prev,
+      );
+    }, [radioGroupState.selectedValue]);
+
+    const registerRadio = useCallback((value: string, entry: RegisteredRadio) => {
+      radiosRef.current.set(value, entry);
+      setRegistrationEpoch((epoch) => epoch + 1);
+    }, []);
+
+    const unregisterRadio = useCallback((value: string) => {
+      radiosRef.current.delete(value);
+      setRegistrationEpoch((epoch) => epoch + 1);
+    }, []);
+
+    const getRadios = useCallback(
+      () => Array.from(radiosRef.current.entries()),
+      [registrationEpoch],
+    );
+
+    const { handleKeyDown } = useRadioGroupNavigation({
+      getRadios,
+      focusedValue,
+      setFocusedValue,
+      selectedValue: radioGroupState.selectedValue,
+      selectValue: (value: string) => radioGroupState.setSelectedValue(value),
+    });
+
+    const webProps =
+      Platform.OS === 'web'
+        ? {
+            onKeyDown: composeEventHandlers(
+              (props as { onKeyDown?: (e: KeyboardEvent) => void }).onKeyDown,
+              handleKeyDown,
+            ),
+          }
+        : {};
 
     const Comp = asChild ? Slot : View;
 
@@ -55,18 +112,25 @@ export const RadioGroup = forwardRef<View, RadioGroupRootProps>(
             selectValue: (value: string) => radioGroupState.setSelectedValue(value),
           },
           radioGroupState,
-          name: combinedProps.name,
+          name,
+          focusedValue,
+          setFocusedValue,
+          registerRadio,
+          unregisterRadio,
+          getRadios,
         }}
       >
         <Comp
           {...radioGroupProps}
-          aria-label={combinedProps['aria-label']}
-          aria-labelledby={combinedProps['aria-labelledby']}
+          aria-label={ariaLabel}
+          aria-labelledby={ariaLabelledBy}
+          aria-describedby={ariaDescribedBy}
           aria-required={isRequired || undefined}
           aria-readonly={isReadOnly || undefined}
           className={className}
           style={style}
           ref={ref}
+          {...webProps}
           {...mergeDataAttributes(
             props,
             dataAttributes({