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

package/src/dialog/DialogTrigger.tsx

@@ -0,0 +1,26 @@
+import { forwardRef, type ComponentRef } from 'react';
+import { Pressable, type PressableProps } from 'react-native';
+import { composeEventHandlers } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { useDialog } from './context';
+import type { IDialogTriggerProps } from './types';
+
+export interface DialogTriggerProps extends IDialogTriggerProps {}
+
+export const DialogTrigger = forwardRef<ComponentRef<typeof Pressable>, DialogTriggerProps>(
+  ({ asChild = false, children, onPress, ...props }, ref) => {
+    const { onOpenChange } = useDialog();
+
+    const handlePress = composeEventHandlers(onPress, () => onOpenChange(true));
+
+    const Comp = asChild ? Slot : Pressable;
+
+    return (
+      <Comp ref={ref} {...(props as PressableProps)} onPress={handlePress}>
+        {children}
+      </Comp>
+    );
+  },
+);
+
+DialogTrigger.displayName = 'DialogTrigger';

package/src/dialog/index.tsx

@@ -1,93 +1,18 @@
-import type React from 'react';
-import { createDialogRoot } from './createDialogRoot';
-import { createDialogTrigger } from './createDialogTrigger';
-import { createDialogContent } from './createDialogContent';
-import { createDialogHeader } from './createDialogHeader';
-import { createDialogTitle } from './createDialogTitle';
-import { createDialogDescription } from './createDialogDescription';
-import { createDialogBody } from './createDialogBody';
-import { createDialogFooter } from './createDialogFooter';
-import { createDialogClose } from './createDialogClose';
-import { DialogProvider, useDialog } from './context';
-import type { IDialogComponentType } from './types';
-
-export { DialogProvider, useDialog };
+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,
-  IDialogContentProps,
+  IDialogPortalProps,
   IDialogOverlayProps,
-  IDialogHeaderProps,
-  IDialogTitleProps,
-  IDialogDescriptionProps,
-  IDialogBodyProps,
-  IDialogFooterProps,
+  IDialogContentProps,
+  IDialogPopupProps,
   IDialogCloseProps,
 } from './types';
-
-export function createDialog<
-  RootProps,
-  TriggerProps,
-  ContentProps,
-  OverlayProps,
-  HeaderProps,
-  TitleProps,
-  DescriptionProps,
-  BodyProps,
-  FooterProps,
-  CloseProps,
->(BaseComponents: {
-  Root: React.ComponentType<RootProps>;
-  Trigger: React.ComponentType<TriggerProps>;
-  Content: React.ComponentType<ContentProps>;
-  Overlay: React.ComponentType<OverlayProps>;
-  Header: React.ComponentType<HeaderProps>;
-  Title: React.ComponentType<TitleProps>;
-  Description: React.ComponentType<DescriptionProps>;
-  Body: React.ComponentType<BodyProps>;
-  Footer: React.ComponentType<FooterProps>;
-  Close: React.ComponentType<CloseProps>;
-}) {
-  const Root = createDialogRoot(BaseComponents.Root);
-  const Trigger = createDialogTrigger(BaseComponents.Trigger);
-  const Content = createDialogContent(BaseComponents.Content, BaseComponents.Overlay);
-  const Header = createDialogHeader(BaseComponents.Header);
-  const Title = createDialogTitle(BaseComponents.Title);
-  const Description = createDialogDescription(BaseComponents.Description);
-  const Body = createDialogBody(BaseComponents.Body);
-  const Footer = createDialogFooter(BaseComponents.Footer);
-  const Close = createDialogClose(BaseComponents.Close);
-
-  Root.displayName = 'DialogPrimitive.Root';
-  Trigger.displayName = 'DialogPrimitive.Trigger';
-  Content.displayName = 'DialogPrimitive.Content';
-  Header.displayName = 'DialogPrimitive.Header';
-  Title.displayName = 'DialogPrimitive.Title';
-  Description.displayName = 'DialogPrimitive.Description';
-  Body.displayName = 'DialogPrimitive.Body';
-  Footer.displayName = 'DialogPrimitive.Footer';
-  Close.displayName = 'DialogPrimitive.Close';
-
-  return Object.assign(Root, {
-    Root,
-    Trigger,
-    Content,
-    Header,
-    Title,
-    Description,
-    Body,
-    Footer,
-    Close,
-  }) as IDialogComponentType<
-    RootProps,
-    TriggerProps,
-    ContentProps,
-    HeaderProps,
-    TitleProps,
-    DescriptionProps,
-    BodyProps,
-    FooterProps,
-    CloseProps
-  >;
-}

package/src/dialog/types.ts

@@ -1,5 +1,5 @@
-import type { PropsWithoutRef, RefAttributes } from 'react';
-import type { PressableProps, TextProps, ViewProps } from 'react-native';
+import type React from 'react';
+import type { PressableProps, ViewProps } from 'react-native';
 
 export interface IDialogContextType {
   readonly open: boolean;
@@ -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,65 +25,54 @@ export interface IDialogTriggerProps extends PressableProps {
   readonly asChild?: boolean;
 }
 
-export interface IDialogContentProps extends ViewProps {
+export interface IDialogPortalProps {
   readonly forceMount?: boolean;
+  readonly hostName?: string;
+  readonly children: React.ReactNode;
 }
 
-export interface IDialogOverlayProps extends PressableProps {}
-
-export interface IDialogHeaderProps extends ViewProps {}
-
-export interface IDialogTitleProps extends TextProps {}
-
-export interface IDialogDescriptionProps extends TextProps {}
+export interface IDialogOverlayProps extends PressableProps {
+  readonly asChild?: boolean;
+  readonly forceMount?: boolean;
+}
 
-export interface IDialogBodyProps extends ViewProps {}
+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 IDialogFooterProps extends ViewProps {}
+export interface IDialogPopupProps extends ViewProps {
+  readonly forceMount?: boolean;
+  /**
+   * Whether the popup 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 popup when keyboard avoidance
+   * is active. Forwarded to the underlying keyboard-avoiding layer on native.
+   * 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 {
   readonly asChild?: boolean;
   readonly accessibilityLabel?: string;
 }
-
-export type IDialogComponentType<
-  RootProps,
-  TriggerProps,
-  ContentProps,
-  HeaderProps,
-  TitleProps,
-  DescriptionProps,
-  BodyProps,
-  FooterProps,
-  CloseProps,
-  ContentRef = unknown,
-  TriggerRef = unknown,
-  CloseRef = unknown,
-> = React.ForwardRefExoticComponent<
-  PropsWithoutRef<RootProps & IDialogRootProps> & RefAttributes<unknown>
-> & {
-  Trigger: React.ForwardRefExoticComponent<
-    PropsWithoutRef<TriggerProps & IDialogTriggerProps> & RefAttributes<TriggerRef>
-  >;
-  Content: React.ForwardRefExoticComponent<
-    PropsWithoutRef<ContentProps & IDialogContentProps> & RefAttributes<ContentRef>
-  >;
-  Header: React.ForwardRefExoticComponent<
-    PropsWithoutRef<HeaderProps & IDialogHeaderProps> & RefAttributes<unknown>
-  >;
-  Title: React.ForwardRefExoticComponent<
-    PropsWithoutRef<TitleProps & IDialogTitleProps> & RefAttributes<unknown>
-  >;
-  Description: React.ForwardRefExoticComponent<
-    PropsWithoutRef<DescriptionProps & IDialogDescriptionProps> & RefAttributes<unknown>
-  >;
-  Body: React.ForwardRefExoticComponent<
-    PropsWithoutRef<BodyProps & IDialogBodyProps> & RefAttributes<unknown>
-  >;
-  Footer: React.ForwardRefExoticComponent<
-    PropsWithoutRef<FooterProps & IDialogFooterProps> & RefAttributes<unknown>
-  >;
-  Close: React.ForwardRefExoticComponent<
-    PropsWithoutRef<CloseProps & IDialogCloseProps> & RefAttributes<CloseRef>
-  >;
-};

package/src/field/FieldLabel.tsx

@@ -0,0 +1,43 @@
+import { forwardRef, type ComponentRef } from 'react';
+import { Text } from 'react-native';
+import { composeEventHandlers, useFormControlContext } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import type { IFieldLabelProps } from './types';
+
+export interface FieldLabelProps extends IFieldLabelProps {
+  asChild?: boolean;
+  className?: string;
+}
+
+/**
+ * Native: `Text` label row — tap focuses the field input via form context
+ * (parity with `<label htmlFor>` on web).
+ */
+export const FieldLabel = forwardRef<ComponentRef<typeof Text>, FieldLabelProps>(
+  ({ asChild, children, htmlFor: _omitHtmlFor, requiredIndicator, onPress, ...props }, ref) => {
+    void _omitHtmlFor;
+
+    const { labelId, isInvalid, isRequired, isDisabled, focusInput } = useFormControlContext();
+    const Comp = asChild ? Slot : Text;
+
+    return (
+      <Comp
+        ref={ref}
+        id={labelId}
+        {...props}
+        disabled={Boolean(isDisabled)}
+        onPress={composeEventHandlers(onPress, () => focusInput?.())}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({ invalid: isInvalid, required: isRequired }),
+        )}
+      >
+        {children}
+        {isRequired ? requiredIndicator : null}
+      </Comp>
+    );
+  },
+);
+
+FieldLabel.displayName = 'FieldLabel';

package/src/field/FieldLabel.web.tsx

@@ -0,0 +1,71 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import { useFormControlContext } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import {
+  domDataAttributes,
+  mergeDomDataAttributes,
+  type DomDataAttributeValue,
+} from '../utils/domDataAttributes';
+
+export interface FieldLabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+  /**
+   * Element rendered after the label text when the field is required. The primitive
+   * owns this composition so the styled layer never needs to read `FormControlContext`.
+   */
+  requiredIndicator?: ReactNode;
+  /**
+   * Forwarded RNW `dataSet` from the styled layer (e.g. `data-slot`). Translated to
+   * flat `data-*` attributes for the underlying `<label>` DOM element.
+   */
+  dataSet?: Record<string, DomDataAttributeValue>;
+}
+
+/**
+ * Real `<label>` so clicking the label focuses the associated control
+ * (`htmlFor` → input `id`). The htmlFor default matches `useFormControl`:
+ * `props.id ?? \`${field.id}-input\``.
+ */
+export const FieldLabel = forwardRef<HTMLLabelElement, FieldLabelProps>(
+  ({ asChild, children, htmlFor: htmlForProp, requiredIndicator, dataSet, ...rest }, ref) => {
+    const { id: fieldId, labelId, isInvalid, isRequired } = useFormControlContext();
+
+    const htmlFor = htmlForProp ?? (fieldId ? `${fieldId}-input` : undefined);
+
+    const mergedDataAttrs = mergeDomDataAttributes(
+      domDataAttributes(dataSet ?? {}),
+      domDataAttributes({ invalid: isInvalid, required: isRequired }),
+    );
+
+    const labelContent = (
+      <>
+        {children}
+        {isRequired ? requiredIndicator : null}
+      </>
+    );
+
+    if (asChild) {
+      return (
+        <Slot
+          ref={ref}
+          id={labelId}
+          htmlFor={htmlFor}
+          {...(rest as Record<string, unknown>)}
+          {...mergedDataAttrs}
+        >
+          {labelContent}
+        </Slot>
+      );
+    }
+
+    return (
+      <label ref={ref} id={labelId} htmlFor={htmlFor} {...rest} {...mergedDataAttrs}>
+        {labelContent}
+      </label>
+    );
+  },
+);
+
+FieldLabel.displayName = 'FieldLabel';

package/src/field/FieldRoot.tsx

@@ -0,0 +1,39 @@
+import { forwardRef, type ComponentRef } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { FormControlContext, useFormControlRoot } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import type { IFieldRootProps } from './types';
+
+export interface FieldRootProps extends IFieldRootProps {
+  asChild?: boolean;
+  className?: string;
+}
+
+export const FieldRoot = forwardRef<ComponentRef<typeof View>, FieldRootProps>(
+  ({ asChild, children, ...props }, ref) => {
+    const { htmlProps, ...context } = useFormControlRoot(props);
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <FormControlContext.Provider value={context}>
+        <Comp
+          ref={ref}
+          {...(htmlProps as ViewProps)}
+          {...mergeDataAttributes(
+            htmlProps,
+            dataAttributes({
+              disabled: context.isDisabled,
+              invalid: context.isInvalid,
+              required: context.isRequired,
+            }),
+          )}
+        >
+          {children}
+        </Comp>
+      </FormControlContext.Provider>
+    );
+  },
+);
+
+FieldRoot.displayName = 'FieldRoot';

package/src/field/index.tsx

@@ -1,68 +1,3 @@
-import type React from 'react';
-import { createFieldError } from './createFieldError';
-import { createFieldErrorIcon } from './createFieldErrorIcon';
-import { createFieldErrorText } from './createFieldErrorText';
-import { createFieldRoot } from './createFieldRoot';
-import { createFieldHelper } from './createFieldHelper';
-import { createFieldHelperText } from './createFieldHelperText';
-import { createFieldLabel } from './createFieldLabel';
-import type { IFieldComponentType } from './types';
-
-export type {
-  IFieldRootProps,
-  IFieldLabelProps,
-  IFieldHelperProps,
-  IFieldHelperTextProps,
-  IFieldErrorProps,
-  IFieldErrorTextProps,
-  IFieldErrorIconProps,
-  IFieldComponentType,
-} from './types';
-
-export function createField<Root, Label, Helper, HelperText, Error, ErrorText, ErrorIcon>({
-  Root,
-  Label,
-  Helper,
-  HelperText,
-  Error,
-  ErrorText,
-  ErrorIcon,
-}: {
-  Root: React.ComponentType<Root>;
-  Label: React.ComponentType<Label>;
-  Helper: React.ComponentType<Helper>;
-  HelperText: React.ComponentType<HelperText>;
-  Error: React.ComponentType<Error>;
-  ErrorText: React.ComponentType<ErrorText>;
-  ErrorIcon: React.ComponentType<ErrorIcon>;
-}) {
-  const FieldRoot = createFieldRoot(Root);
-  FieldRoot.displayName = 'FieldPrimitive';
-
-  const FieldLabel = createFieldLabel(Label);
-  FieldLabel.displayName = 'FieldPrimitive.Label';
-
-  const FieldHelper = createFieldHelper(Helper);
-  FieldHelper.displayName = 'FieldPrimitive.Helper';
-
-  const FieldHelperText = createFieldHelperText(HelperText);
-  FieldHelperText.displayName = 'FieldPrimitive.HelperText';
-
-  const FieldError = createFieldError(Error);
-  FieldError.displayName = 'FieldPrimitive.Error';
-
-  const FieldErrorText = createFieldErrorText(ErrorText);
-  FieldErrorText.displayName = 'FieldPrimitive.ErrorText';
-
-  const FieldErrorIcon = createFieldErrorIcon(ErrorIcon);
-  FieldErrorIcon.displayName = 'FieldPrimitive.ErrorIcon';
-
-  return Object.assign(FieldRoot, {
-    Label: FieldLabel,
-    Helper: FieldHelper,
-    HelperText: FieldHelperText,
-    Error: FieldError,
-    ErrorText: FieldErrorText,
-    ErrorIcon: FieldErrorIcon,
-  }) as IFieldComponentType<Root, Label, Helper, HelperText, Error, ErrorText, ErrorIcon>;
-}
+export type { IFieldRootProps, IFieldLabelProps } from './types';
+export { FieldRoot, type FieldRootProps } from './FieldRoot';
+export { FieldLabel, type FieldLabelProps } from './FieldLabel';

package/src/field/types.tsx

@@ -42,37 +42,3 @@ export interface IFieldLabelProps extends TextProps {
    */
   readonly requiredIndicator?: React.ReactNode;
 }
-
-export interface IFieldHelperProps extends ViewProps {}
-
-export interface IFieldHelperTextProps extends TextProps {}
-
-export interface IFieldErrorProps extends ViewProps {}
-
-export interface IFieldErrorTextProps extends TextProps {}
-
-export interface IFieldErrorIconProps extends ViewProps {}
-
-export type IFieldComponentType<Root, Label, Helper, HelperText, Error, ErrorText, ErrorIcon> =
-  React.ForwardRefExoticComponent<InnerForwardRefExoticComponent<Root> & IFieldRootProps> & {
-    Label: React.ForwardRefExoticComponent<
-      InnerForwardRefExoticComponent<Label> & IFieldLabelProps
-    >;
-    Helper: React.ForwardRefExoticComponent<
-      InnerForwardRefExoticComponent<Helper> & IFieldHelperProps
-    >;
-    HelperText: React.ForwardRefExoticComponent<
-      InnerForwardRefExoticComponent<HelperText> & IFieldHelperTextProps
-    >;
-    Error: React.ForwardRefExoticComponent<
-      InnerForwardRefExoticComponent<Error> & IFieldErrorProps
-    >;
-    ErrorText: React.ForwardRefExoticComponent<
-      InnerForwardRefExoticComponent<ErrorText> & IFieldErrorTextProps
-    >;
-    ErrorIcon: React.ForwardRefExoticComponent<
-      InnerForwardRefExoticComponent<ErrorIcon> & IFieldErrorIconProps
-    >;
-  };
-
-type InnerForwardRefExoticComponent<T> = React.PropsWithoutRef<T> & React.RefAttributes<unknown>;

package/src/form/FormRoot.tsx

@@ -0,0 +1,18 @@
+import { forwardRef } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { Slot } from '../slot';
+import type { IFormRootProps } from './types';
+
+export interface FormRootProps extends ViewProps, IFormRootProps {
+  asChild?: boolean;
+  className?: string;
+}
+
+export const FormRoot = forwardRef<View, FormRootProps>(
+  ({ asChild, onSubmit: _, action: _a, method: _m, ...props }, ref) => {
+    const Comp = asChild ? Slot : View;
+    return <Comp ref={ref} {...props} />;
+  },
+);
+
+FormRoot.displayName = 'FormRoot';

package/src/form/FormRoot.web.tsx

@@ -0,0 +1,17 @@
+import React, { forwardRef } from 'react';
+import { Slot } from '../slot';
+
+export interface FormRootProps extends React.FormHTMLAttributes<HTMLFormElement> {
+  asChild?: boolean;
+  className?: string;
+  children?: React.ReactNode;
+}
+
+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} />;
+});
+
+FormRoot.displayName = 'FormRoot';

package/src/form/index.tsx

@@ -1,12 +1,2 @@
-import type React from 'react';
-import { createFormRoot } from './createFormRoot';
-
-export type { IFormRootProps, IFormComponentType } from './types';
-
-export function createForm<Root>({ Root }: { Root: React.ComponentType<Root> }) {
-  const FormRoot = createFormRoot(Root);
-
-  FormRoot.displayName = 'FormPrimitive';
-
-  return FormRoot;
-}
+export type { IFormRootProps } from './types';
+export { FormRoot, type FormRootProps } from './FormRoot';

package/src/form/types.tsx

@@ -1,16 +1,14 @@
 import type React from 'react';
 
 /**
- * Props for the Form container (`<form>` on web, `<View>` on RN).
- * Does NOT provide field-level context — use `Form.Field` for that.
- *
- * Web-only submit props (`onSubmit`, `action`, `method`) belong in the
- * platform-specific base component (`FormRoot.web.tsx`), not here.
+ * Cross-platform form props accepted on both native and web.
+ * Web-only props (`onSubmit`, `action`, `method`) are accepted on native
+ * for API compatibility but silently ignored.
  */
-export interface IFormRootProps {}
+export interface InterfaceFormRootProps {
+  onSubmit?: (e: React.SyntheticEvent) => void;
+  action?: string | ((formData: FormData) => void | Promise<void>);
+  method?: string;
+}
 
-export type IFormComponentType<Root> = React.ForwardRefExoticComponent<
-  InnerForwardRefExoticComponent<Root> & IFormRootProps
->;
-
-type InnerForwardRefExoticComponent<T> = React.PropsWithoutRef<T> & React.RefAttributes<unknown>;
+export type IFormRootProps = InterfaceFormRootProps;

package/src/full-window-overlay/index.tsx

@@ -0,0 +1,65 @@
+import type { ReactNode } from 'react';
+import { Platform } from 'react-native';
+import { FullWindowOverlay as NativeFullWindowOverlay } from 'react-native-screens';
+
+/**
+ * Props for the FullWindowOverlay component
+ *
+ * @description
+ * FullWindowOverlay renders content in a separate native window on iOS,
+ * which allows overlays (bottom sheets, dialogs, toasts) to appear above
+ * native modals and the keyboard. However, this breaks the React Native
+ * element inspector because it attaches to the main window.
+ *
+ * Set `disableFullWindowOverlay={true}` when you need to use the element
+ * inspector during development. Note: when disabled, overlay content will
+ * not render above native modals. iOS only; has no effect on Android.
+ */
+export interface FullWindowOverlayProps {
+  /**
+   * When true, uses a regular View instead of FullWindowOverlay on iOS.
+   * Enables element inspector but overlay content won't appear above native modals.
+   * @default false
+   */
+  disableFullWindowOverlay: boolean;
+  /**
+   * Controls whether VoiceOver treats the overlay window as a modal container.
+   * When `false`, VoiceOver can still access elements behind the overlay.
+   * When `true`, VoiceOver is restricted to elements inside the overlay.
+   * @default false
+   * @platform ios
+   * @unstable This prop maps directly to the native `accessibilityViewIsModal`
+   * on the container view and may change in a future react-native-screens release.
+   */
+  unstable_accessibilityContainerViewIsModal?: boolean;
+  /**
+   * Content to render inside the overlay
+   */
+  children: ReactNode;
+}
+
+/**
+ * Wrapper for react-native-screens FullWindowOverlay with optional disable prop.
+ *
+ * @description
+ * On iOS, FullWindowOverlay creates a separate native window for overlay content,
+ * which breaks the React Native element inspector. Use `disableFullWindowOverlay`
+ * when debugging to render content in the main window instead.
+ */
+export function FullWindowOverlay({
+  disableFullWindowOverlay,
+  unstable_accessibilityContainerViewIsModal = false,
+  children,
+}: Readonly<FullWindowOverlayProps>) {
+  if (Platform.OS !== 'ios' || disableFullWindowOverlay) {
+    return <>{children}</>;
+  }
+
+  return (
+    <NativeFullWindowOverlay
+      unstable_accessibilityContainerViewIsModal={unstable_accessibilityContainerViewIsModal}
+    >
+      {children}
+    </NativeFullWindowOverlay>
+  );
+}