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

package/src/date-time-picker/DateTimePickerRoot.tsx

@@ -0,0 +1,210 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentRef,
+  type ReactNode,
+} from 'react';
+import { View, type ViewProps } from 'react-native';
+import {
+  clampDateTimeId,
+  isLocaleHour12,
+  nowDateTimeId,
+  resolveDateComponentLabels,
+  type DateComponentLabels,
+  type DateTimeGranularity,
+  type DateTimeId,
+} from '@cdx-ui/formatters';
+import { mergeRefs, useControllableState } from '@cdx-ui/utils';
+import { DateTimeFieldRoot } from '../date-time-field/DateTimeFieldRoot';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import type { PickerSurfaceType } from '../date-picker/context';
+import { DateTimePickerContext } from './context';
+
+export interface DateTimePickerRootProps extends Omit<ViewProps, 'children'> {
+  asChild?: boolean;
+  children?: ReactNode;
+  className?: string;
+  value?: DateTimeId;
+  defaultValue?: DateTimeId;
+  /** Called with the new `DateTimeId`, or `undefined` when the selection is cleared. */
+  onValueChange?: (value: DateTimeId | 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 date-time, applied to the scroll list. Build with `dateTimeId(...)`. */
+  minValue?: DateTimeId;
+  /** Latest selectable date-time, applied to the scroll list. Build with `dateTimeId(...)`. */
+  maxValue?: DateTimeId;
+  name?: string;
+  locale?: string;
+  labels?: Partial<DateComponentLabels>;
+  /** Which field segments and list columns to show, from coarsest (`day`) to finest (`second`). */
+  granularity?: DateTimeGranularity;
+  /**
+   * Force a 12-hour clock (AM/PM column) or a 24-hour clock. Defaults to the
+   * locale's convention when omitted.
+   */
+  hour12?: boolean;
+}
+
+export const DateTimePickerRoot = forwardRef<ComponentRef<typeof View>, DateTimePickerRootProps>(
+  (
+    {
+      asChild,
+      children,
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      isOpen: openProp,
+      defaultOpen = false,
+      onOpenChange,
+      isDisabled: disabled = false,
+      isReadOnly,
+      isInvalid,
+      isRequired,
+      minValue,
+      maxValue,
+      locale = 'en-US',
+      labels: labelsProp,
+      granularity = 'minute',
+      hour12: hour12Prop,
+      ...props
+    },
+    ref,
+  ) => {
+    const hour12 = hour12Prop ?? isLocaleHour12(locale);
+    const labels = useMemo(() => resolveDateComponentLabels(labelsProp), [labelsProp]);
+    const [value, setValue] = useControllableState<DateTimeId | undefined>({
+      prop: valueProp,
+      defaultProp: defaultValue,
+      onChange: onValueChange,
+    });
+
+    const [open, setOpenState] = useControllableState<boolean>({
+      prop: openProp,
+      defaultProp: defaultOpen,
+      onChange: onOpenChange,
+    });
+
+    const [draftValue, setDraftValue] = useState<DateTimeId | 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) {
+          const base = value ?? nowDateTimeId({ granularity });
+          setDraftValue(clampDateTimeId(base, { min: minValue, max: maxValue }));
+        } else if (value === undefined) {
+          setDraftValue(undefined);
+        }
+        setOpenState(next);
+      },
+      [disabled, granularity, maxValue, minValue, 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] DateTimePicker: multiple presentation surfaces detected. Use only one of Popover, Dialog, or BottomSheet.',
+        );
+      }
+    }, []);
+
+    useEffect(() => {
+      if (value !== undefined) {
+        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,
+        registerSurface,
+        anchorRef,
+        triggerRef,
+        granularity,
+        locale,
+        labels,
+        hour12,
+      }),
+      [
+        value,
+        setValue,
+        draftValue,
+        open,
+        setOpen,
+        disabled,
+        minValue,
+        maxValue,
+        registerSurface,
+        granularity,
+        locale,
+        labels,
+        hour12,
+      ],
+    );
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <DateTimePickerContext.Provider value={contextValue}>
+        <Comp
+          ref={mergeRefs(ref, anchorRef)}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ disabled, open }))}
+        >
+          <DateTimeFieldRoot
+            value={value}
+            onValueChange={setValue}
+            granularity={granularity}
+            locale={locale}
+            hour12={hour12}
+            labels={labels}
+            isDisabled={disabled}
+            isReadOnly={isReadOnly}
+            isInvalid={isInvalid}
+            isRequired={isRequired}
+          >
+            {children}
+          </DateTimeFieldRoot>
+        </Comp>
+      </DateTimePickerContext.Provider>
+    );
+  },
+);
+
+DateTimePickerRoot.displayName = 'DateTimePickerRoot';

package/src/date-time-picker/context.tsx

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

package/src/date-time-picker/index.ts

@@ -0,0 +1,7 @@
+export { DateTimePickerRoot } from './DateTimePickerRoot';
+export type { DateTimePickerRootProps } from './DateTimePickerRoot';
+export {
+  DateTimePickerContext,
+  useDateTimePickerContext,
+  type DateTimePickerContextValue,
+} from './context';

package/src/dialog/DialogContent.tsx

@@ -0,0 +1,90 @@
+import { forwardRef, useCallback, useEffect, type ComponentRef } from 'react';
+import { BackHandler, Platform, View, type ViewProps } from 'react-native';
+import { FocusScope } from '@react-native-aria/focus';
+import { Slot } from '../slot';
+import { useEscapeKey, useOverlayStackRegistration } from '../overlay';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { useDialog } from './context';
+import type { IDialogContentProps } from './types';
+
+export interface DialogContentProps extends IDialogContentProps {}
+
+/**
+ * Dialog content panel primitive. Provides:
+ * - ARIA role, aria-modal, aria-labelledby/describedby
+ * - FocusScope (focus trap + restore + auto-focus)
+ * - Escape key dismissal (web)
+ * - Android hardware back button dismissal (native)
+ * - data-state attribute for CSS transition targeting
+ *
+ * Unstyled — the styled layer applies centering, background, border-radius, etc.
+ */
+export const DialogContent = forwardRef<ComponentRef<typeof View>, DialogContentProps>(
+  ({ asChild = false, forceMount = false, children, ...props }, ref) => {
+    const { open, onOpenChange, closeOnEscKey, nativeID, role } = useDialog();
+
+    const handleClose = useCallback(() => {
+      onOpenChange(false);
+    }, [onOpenChange]);
+
+    useEscapeKey(open && closeOnEscKey, handleClose, {
+      id: nativeID,
+      groupId: nativeID,
+      layer: 'modal',
+    });
+    const { isTopmost } = useOverlayStackRegistration({
+      active: open && Platform.OS !== 'web',
+      capabilities: ['back'],
+      id: nativeID,
+      groupId: nativeID,
+      layer: 'modal',
+    });
+
+    useEffect(() => {
+      // BackHandler is native-only; react-native-web warns on every subscription.
+      if (!open || Platform.OS === 'web') return;
+
+      const backHandler = BackHandler.addEventListener('hardwareBackPress', () => {
+        if (!isTopmost('back')) return false;
+        handleClose();
+        return true;
+      });
+
+      return () => {
+        backHandler.remove();
+      };
+    }, [handleClose, isTopmost, open]);
+
+    if (!forceMount && !open) {
+      return null;
+    }
+
+    const Comp = asChild ? Slot : View;
+
+    const ariaProps = {
+      role,
+      'aria-modal': true,
+      'aria-labelledby': `${nativeID}-title`,
+      'aria-describedby': `${nativeID}-description`,
+    };
+
+    return (
+      <FocusScope contain={open} restoreFocus autoFocus={open}>
+        <Comp
+          ref={ref}
+          nativeID={nativeID}
+          {...ariaProps}
+          {...(props as ViewProps)}
+          {...mergeDataAttributes(
+            props,
+            forceMount ? undefined : dataAttributes({ state: open ? 'open' : 'closed' }),
+          )}
+        >
+          {children}
+        </Comp>
+      </FocusScope>
+    );
+  },
+);
+
+DialogContent.displayName = 'DialogContent';

package/src/dialog/DialogOverlay.tsx

@@ -0,0 +1,51 @@
+import { forwardRef, useCallback, type ComponentRef } from 'react';
+import { Pressable, type PressableProps } from 'react-native';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { useDialog } from './context';
+import type { IDialogOverlayProps } from './types';
+
+export interface DialogOverlayProps extends IDialogOverlayProps {}
+
+/**
+ * Backdrop overlay that dismisses the dialog on press (when closeOnBackdropPress
+ * is enabled). Supports `forceMount` for exit animation coordination.
+ *
+ * Unstyled — the styled layer applies opacity/color via className.
+ */
+export const DialogOverlay = forwardRef<ComponentRef<typeof Pressable>, DialogOverlayProps>(
+  ({ asChild = false, forceMount = false, onPress, ...props }, ref) => {
+    const { open, onOpenChange, closeOnBackdropPress } = useDialog();
+
+    const handlePress = useCallback(
+      (e: any) => {
+        if (closeOnBackdropPress) {
+          onOpenChange(false);
+        }
+        if (typeof onPress === 'function') {
+          onPress(e);
+        }
+      },
+      [closeOnBackdropPress, onOpenChange, onPress],
+    );
+
+    if (!forceMount && !open) {
+      return null;
+    }
+
+    const Comp = asChild ? Slot : Pressable;
+
+    return (
+      <Comp
+        ref={ref}
+        accessible={false}
+        importantForAccessibility="no-hide-descendants"
+        onPress={handlePress}
+        {...(props as PressableProps)}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'dialog-overlay' }))}
+      />
+    );
+  },
+);
+
+DialogOverlay.displayName = 'DialogOverlay';

package/src/dialog/DialogPopup.tsx

@@ -10,7 +10,7 @@ import {
 } from 'react-native';
 import { FocusScope } from '@react-native-aria/focus';
 import { Slot } from '../slot';
-import { useEscapeKey } from '../overlay';
+import { MODAL_OVERLAY_Z_INDEX, useEscapeKey } from '../overlay';
 import { createPortalFn } from '../utils/createPortal';
 import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
 import { useDialog } from './context';
@@ -35,6 +35,7 @@ export const DialogPopup = forwardRef<ComponentRef<typeof View>, DialogPopupProp
       forceMount = false,
       avoidKeyboard = true,
       keyboardVerticalOffset = 0,
+      zIndex = MODAL_OVERLAY_Z_INDEX,
       overlayClassName,
       ...props
     },
@@ -46,7 +47,11 @@ export const DialogPopup = forwardRef<ComponentRef<typeof View>, DialogPopupProp
       onOpenChange(false);
     }, [onOpenChange]);
 
-    useEscapeKey(open && closeOnEscKey, handleClose);
+    useEscapeKey(open && closeOnEscKey, handleClose, {
+      id: nativeID,
+      groupId: nativeID,
+      layer: 'modal',
+    });
 
     if (!(open || forceMount)) {
       return null;
@@ -81,7 +86,7 @@ export const DialogPopup = forwardRef<ComponentRef<typeof View>, DialogPopupProp
             style={{
               position: 'fixed' as any,
               inset: 0 as any,
-              zIndex: 50,
+              zIndex: zIndex,
               display: 'flex' as any,
               alignItems: 'center',
               justifyContent: 'center',

package/src/dialog/DialogPortal.tsx

@@ -0,0 +1,29 @@
+import { Portal } from '../portal';
+import { DialogProvider, useDialog } from './context';
+import type { IDialogPortalProps } from './types';
+
+export interface DialogPortalProps extends IDialogPortalProps {}
+
+/**
+ * Mounts dialog children into the shared PortalHost. Re-provides DialogContext
+ * inside the portal boundary (React context does not cross the portal store).
+ *
+ * When `forceMount` is false (default), the portal is unmounted when the
+ * dialog is closed. Set `forceMount={true}` to keep the portal mounted so
+ * exit animations can play before the styled layer removes it from the tree.
+ */
+export function DialogPortal({ forceMount = false, hostName, children }: DialogPortalProps) {
+  const ctx = useDialog();
+
+  if (!forceMount && !ctx.open) {
+    return null;
+  }
+
+  return (
+    <Portal name={`${ctx.nativeID}-portal`} hostName={hostName}>
+      <DialogProvider value={ctx}>{children}</DialogProvider>
+    </Portal>
+  );
+}
+
+DialogPortal.displayName = 'DialogPortal';

package/src/dialog/DialogRoot.tsx

@@ -13,7 +13,7 @@ export interface DialogRootProps extends Omit<ViewProps, 'children' | 'role'>, I
 export const DialogRoot = forwardRef<ComponentRef<typeof View>, DialogRootProps>(
   (
     {
-      open: openProp,
+      isOpen: openProp,
       onOpenChange,
       defaultOpen = false,
       closeOnBackdropPress = true,

package/src/dialog/index.tsx

@@ -1,12 +1,18 @@
 export { DialogProvider, useDialog } from './context';
 export { DialogRoot, type DialogRootProps } from './DialogRoot';
 export { DialogTrigger, type DialogTriggerProps } from './DialogTrigger';
+export { DialogPortal, type DialogPortalProps } from './DialogPortal';
+export { DialogOverlay, type DialogOverlayProps } from './DialogOverlay';
+export { DialogContent, type DialogContentProps } from './DialogContent';
 export { DialogPopup, type DialogPopupProps } from './DialogPopup';
 export { DialogClose, type DialogCloseProps } from './DialogClose';
 export type {
   IDialogContextType,
   IDialogRootProps,
   IDialogTriggerProps,
+  IDialogPortalProps,
+  IDialogOverlayProps,
+  IDialogContentProps,
   IDialogPopupProps,
   IDialogCloseProps,
 } from './types';

package/src/dialog/types.ts

@@ -11,7 +11,8 @@ export interface IDialogContextType {
 }
 
 export interface IDialogRootProps {
-  readonly open?: boolean;
+  /** Controlled open state. Use `defaultOpen` for the uncontrolled variant. */
+  readonly isOpen?: boolean;
   readonly onOpenChange?: (open: boolean) => void;
   readonly defaultOpen?: boolean;
   readonly closeOnBackdropPress?: boolean;
@@ -24,6 +25,33 @@ export interface IDialogTriggerProps extends PressableProps {
   readonly asChild?: boolean;
 }
 
+export interface IDialogPortalProps {
+  readonly forceMount?: boolean;
+  readonly hostName?: string;
+  readonly children: React.ReactNode;
+}
+
+export interface IDialogOverlayProps extends PressableProps {
+  readonly asChild?: boolean;
+  readonly forceMount?: boolean;
+}
+
+export interface IDialogContentProps extends ViewProps {
+  readonly asChild?: boolean;
+  readonly forceMount?: boolean;
+  /**
+   * Whether the content shifts up to clear the on-screen keyboard (native only).
+   * No-op on web. Defaults to `true`.
+   */
+  readonly avoidKeyboard?: boolean;
+  /**
+   * Distance (in px) between the keyboard and the content when keyboard avoidance
+   * is active. Forwarded to the underlying keyboard-avoiding layer on native.
+   * Defaults to `0`.
+   */
+  readonly keyboardVerticalOffset?: number;
+}
+
 export interface IDialogPopupProps extends ViewProps {
   readonly forceMount?: boolean;
   /**
@@ -37,6 +65,11 @@ export interface IDialogPopupProps extends ViewProps {
    * Defaults to `0`.
    */
   readonly keyboardVerticalOffset?: number;
+  /**
+   * Stacking order for the full-screen portal layer (backdrop + centered popup).
+   * Defaults to `MODAL_OVERLAY_Z_INDEX` (10000).
+   */
+  readonly zIndex?: number;
 }
 
 export interface IDialogCloseProps extends PressableProps {

package/src/form/FormRoot.web.tsx

@@ -1,17 +1,23 @@
 import React, { forwardRef } from 'react';
 import { Slot } from '../slot';
+import { domDataAttributes, type DomDataAttributeValue } from '../utils/domDataAttributes';
 
 export interface FormRootProps extends React.FormHTMLAttributes<HTMLFormElement> {
   asChild?: boolean;
   className?: string;
   children?: React.ReactNode;
+  dataSet?: Record<string, DomDataAttributeValue>;
 }
 
-export const FormRoot = forwardRef<HTMLFormElement, FormRootProps>(({ asChild, ...props }, ref) => {
-  if (asChild) {
-    return <Slot ref={ref} {...(props as Record<string, unknown>)} />;
-  }
-  return <form ref={ref} {...props} />;
-});
+export const FormRoot = forwardRef<HTMLFormElement, FormRootProps>(
+  ({ asChild, dataSet, ...props }, ref) => {
+    const dataAttrs = domDataAttributes(dataSet ?? {});
+
+    if (asChild) {
+      return <Slot ref={ref} {...(props as Record<string, unknown>)} {...dataAttrs} />;
+    }
+    return <form ref={ref} {...props} {...dataAttrs} />;
+  },
+);
 
 FormRoot.displayName = 'FormRoot';

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './avatar';
+export * from './breadcrumbs';
 export * from './button';
 export * from './chip';
 export * from './checkbox';
@@ -8,16 +9,64 @@ export * from './form';
 export * from './full-window-overlay';
 export * from './input';
 export * from './otp-input';
+export * from './date-field';
+export * from './calendar';
+export * from './range-calendar';
+export * from './month-calendar';
+export * from './date-picker';
+export * from './date-range-picker';
+export * from './month-picker';
+export * from './date-time-field';
+export * from './date-time-list';
+export * from './date-time-picker';
 export * from './link';
 export * from './list-item';
-export { type EdgeInsets, OverlayInsetsProvider } from './overlay';
+export * from './menu';
+export {
+  MODAL_OVERLAY_Z_INDEX,
+  NOTIFICATION_OVERLAY_Z_INDEX,
+  OVERLAY_PLACEMENTS,
+  type EdgeInsets,
+  getAnchoredOverlayPosition,
+  OverlayContainer,
+  OverlayInsetsProvider,
+  OverlayStackProvider,
+  useAnchorPosition,
+  useAnchoredOverlay,
+  useDismissOverlay,
+  useEscapeKey,
+  useOverlayStackRegistration,
+  useOverlayPosition,
+  type AnchorLayout,
+  type AnchoredOverlayPosition,
+  type AnchoredOverlayPositionOptions,
+  type FloatingLayout,
+  type OverlayAlign,
+  type OverlayCollisionBehavior,
+  type OverlayPlacement,
+  type OverlayPosition,
+  type OverlaySide,
+  type OverlayStackCapability,
+  type OverlayStackLayer,
+  type OverlayStackMetadata,
+  type OverlayStackRegistrationOptions,
+  type OverlayStackRegistrationResult,
+  type OverlayWidthPolicy,
+  type ResolvedOverlayPlacement,
+  type UseAnchoredOverlayOptions,
+  type UseAnchoredOverlayResult,
+} from './overlay';
 export * from './select';
 export * from './switch';
+export * from './tabs';
 export * from './tile';
 export * from './toast';
+export * from './tooltip';
 export * from './portal';
 export * from './progress-bar';
 export * from './radio';
+export * from './accordion';
+export * from './slider';
 export type { InteractionState } from './types';
 export { FormControlContext, useFormControlContext } from '@cdx-ui/utils';
 export { dataAttributes, mergeDataAttributes } from './utils/dataAttributes';
@@ -26,4 +75,7 @@ export {
   mergeDomDataAttributes,
   type DomDataAttributeValue,
 } from './utils/domDataAttributes';
+export { mapViewPropsToDom, type MapViewPropsToDomOptions } from './utils/mapViewPropsToDom';
+export { assignRef } from './utils/assignRef';
+export { createPortalFn } from './utils/createPortal';
 export { Slot } from './slot';

package/src/input/types.ts

@@ -21,9 +21,15 @@ export interface IInputFieldProps {
   isInvalid?: boolean;
   /** If true, the input will be disabled. */
   isDisabled?: boolean;
-  /** If true, the input will be hovered. */
+  /**
+   * If true, the input will be hovered.
+   * @internal
+   */
   isHovered?: boolean;
-  /** If true, the input will be focused. */
+  /**
+   * If true, the input will be focused.
+   * @internal
+   */
   isFocused?: boolean;
   /** Sets `aria-required="true"` on web when passed in form control. */
   isRequired?: boolean;