@cdx-ui/components 0.1.6 → 0.1.7

package/src/components/FullScreenDialog/index.tsx

@@ -0,0 +1,484 @@
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+import {
+  AccessibilityInfo,
+  Platform,
+  useWindowDimensions,
+  View,
+  type ViewProps,
+} from 'react-native';
+import Animated from 'react-native-reanimated';
+import { SafeAreaInsetsContext, type EdgeInsets } from 'react-native-safe-area-context';
+import {
+  DialogContent as DialogContentPrimitive,
+  DialogPortal as DialogPortalPrimitive,
+  DialogRoot as DialogRootPrimitive,
+  DialogTrigger as DialogTriggerPrimitive,
+  MODAL_OVERLAY_Z_INDEX,
+  Slot,
+  dataAttributes,
+  mergeDataAttributes,
+  useDialog,
+  type IDialogContentProps,
+  type IDialogRootProps,
+  type IDialogTriggerProps,
+} from '@cdx-ui/primitives';
+import { cn, mergeRefs } from '@cdx-ui/utils';
+import { useCombinedAnimationDisabledState, type AnimationRootDisableAll } from '../../animation';
+import {
+  AnimationSettingsProvider,
+  useAnimationSettings,
+} from '../../providers/animation-settings';
+import { BottomSheet } from '../BottomSheet';
+import { SheetHeader, type SheetHeaderTitleRef } from '../sheet-header';
+import { WEB_TRANSITION_SAFETY_MS, getFullScreenDialogSurfaceMotion } from './animation';
+import {
+  fullScreenDialogContentVariants,
+  fullScreenDialogHeaderVariants,
+  fullScreenDialogPopupVariants,
+  fullScreenDialogPortalVariants,
+} from './styles';
+
+const IS_WEB = Platform.OS === 'web';
+
+type FullScreenDialogDataState = 'entering' | 'open' | 'closed';
+
+const ZERO_INSETS: EdgeInsets = { top: 0, bottom: 0, left: 0, right: 0 };
+
+function useSafeInsets(): EdgeInsets {
+  return useContext(SafeAreaInsetsContext) ?? ZERO_INSETS;
+}
+
+// The header's last title / back state for the current open session. Lives on the
+// popup so a header that remounts per step still counts as a step change.
+const StepFocusKeyContext = createContext<RefObject<string | undefined> | null>(null);
+
+function focusTitle(node: SheetHeaderTitleRef | null): void {
+  if (!node) return;
+  if (IS_WEB) {
+    (node as unknown as HTMLElement).focus?.();
+  } else {
+    AccessibilityInfo.sendAccessibilityEvent(node, 'focus');
+  }
+}
+
+/**
+ * Moves focus to the header title when `stepKey` changes during an open session.
+ * The first key after open is only recorded, so `FocusScope` auto-focus decides
+ * initial focus. An undefined key (custom header content) never moves focus.
+ */
+function useStepChangeFocus(
+  stepKey: string | undefined,
+  titleRef: RefObject<SheetHeaderTitleRef | null>,
+): void {
+  const lastKeyRef = useContext(StepFocusKeyContext);
+
+  useEffect(() => {
+    if (!lastKeyRef || stepKey === undefined) return;
+    const previousKey = lastKeyRef.current;
+    lastKeyRef.current = stepKey;
+    if (previousKey === undefined || previousKey === stepKey) return;
+
+    if (IS_WEB) {
+      focusTitle(titleRef.current);
+      return;
+    }
+    // Native: wait a frame so the new title is in the accessibility tree.
+    let fired = false;
+    const frame = requestAnimationFrame(() => {
+      fired = true;
+      focusTitle(titleRef.current);
+    });
+    return () => {
+      if (fired) return;
+      cancelAnimationFrame(frame);
+      // Re-arm the pending move for the next run (StrictMode remounts, rapid changes).
+      lastKeyRef.current = previousKey;
+    };
+  }, [lastKeyRef, stepKey, titleRef]);
+}
+
+// =============================================================================
+// STYLED ROOT
+// =============================================================================
+
+export interface FullScreenDialogRootProps
+  extends
+    Omit<ViewProps, 'children' | 'role'>,
+    Omit<
+      IDialogRootProps,
+      | 'closeOnBackdropPress'
+      | 'role'
+      | 'onOpenChange'
+      | 'defaultOpen'
+      | 'closeOnEscKey'
+      | 'children'
+    > {
+  /**
+   * Called with the next open state. Fires `false` for the header close button, Escape, and
+   * Android back while the header has no `onBack`.
+   */
+  onOpenChange?: (open: boolean) => void;
+  /** Initial open state when uncontrolled. @default false */
+  defaultOpen?: boolean;
+  /**
+   * Close when Escape is pressed. Web only. Escape never steps back; Android back is routed
+   * by the header's `onBack` independently of this prop.
+   * @default true
+   */
+  closeOnEscKey?: boolean;
+  /** `FullScreenDialog.Trigger` and `FullScreenDialog.Popup`. */
+  children: ReactNode;
+  /** Classes for the root wrapper around the trigger. */
+  className?: string;
+  /** Pass `'disable-all'` to turn off the popup's enter and exit motion. */
+  animation?: AnimationRootDisableAll;
+}
+
+const FullScreenDialogRoot = forwardRef<View, FullScreenDialogRootProps>(
+  ({ animation, className, children, style, ...props }, ref) => {
+    const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+    const animationSettingsContextValue = useMemo(
+      () => ({ isAllAnimationsDisabled }),
+      [isAllAnimationsDisabled],
+    );
+
+    return (
+      <AnimationSettingsProvider value={animationSettingsContextValue}>
+        <DialogRootPrimitive
+          ref={ref}
+          className={className}
+          style={style}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ slot: 'full-screen-dialog' }))}
+        >
+          {children}
+        </DialogRootPrimitive>
+      </AnimationSettingsProvider>
+    );
+  },
+);
+
+FullScreenDialogRoot.displayName = 'FullScreenDialog';
+
+// =============================================================================
+// STYLED TRIGGER
+// =============================================================================
+
+export interface FullScreenDialogTriggerProps extends Omit<IDialogTriggerProps, 'asChild'> {
+  /** Render the single child as the trigger instead of a `Pressable`. */
+  asChild?: boolean;
+  /** Classes for the trigger. */
+  className?: string;
+  /** Content that opens the dialog when pressed. */
+  children?: ReactNode;
+}
+
+const FullScreenDialogTrigger = forwardRef<View, FullScreenDialogTriggerProps>(
+  ({ className, children, style, ...props }, ref) => (
+    <DialogTriggerPrimitive
+      ref={ref}
+      className={className}
+      style={style}
+      {...props}
+      {...mergeDataAttributes(props, dataAttributes({ slot: 'full-screen-dialog-trigger' }))}
+    >
+      {children}
+    </DialogTriggerPrimitive>
+  ),
+);
+
+FullScreenDialogTrigger.displayName = 'FullScreenDialog.Trigger';
+
+// =============================================================================
+// STYLED POPUP (portal + full-viewport page in the app window)
+// =============================================================================
+
+export interface FullScreenDialogPopupProps extends Omit<
+  IDialogContentProps,
+  'asChild' | 'forceMount' | 'avoidKeyboard' | 'keyboardVerticalOffset'
+> {
+  /** Classes for the page surface, merged after the defaults. */
+  className?: string;
+  /** `FullScreenDialog.Header` and `FullScreenDialog.Content`. Bottom sheets declared here present above the page. */
+  children?: ReactNode;
+}
+
+const FullScreenDialogPopup = forwardRef<View, FullScreenDialogPopupProps>(
+  ({ className, children, style, ...props }, ref) => {
+    const { open } = useDialog();
+    const animationSettings = useAnimationSettings();
+    const { isAllAnimationsDisabled } = animationSettings;
+    const { height: windowHeight } = useWindowDimensions();
+    const surfaceMotion = useMemo(
+      () => getFullScreenDialogSurfaceMotion(windowHeight),
+      [windowHeight],
+    );
+
+    // Web enter/exit lifecycle mirrors `Dialog.Popup`: mount → 'entering' →
+    // (rAF) → 'open' → (close) → 'closed' → (transitionend) → unmount. The exit
+    // flag is derived during render so the popup stays mounted in the same
+    // render that sees `open` go false.
+    const popupRef = useRef<View | null>(null);
+    const prevOpenRef = useRef(open);
+    const [isExiting, setIsExiting] = useState(false);
+    const [webState, setWebState] = useState<FullScreenDialogDataState>(
+      open ? 'entering' : 'closed',
+    );
+
+    if (IS_WEB && prevOpenRef.current && !open && !isExiting) {
+      setIsExiting(true);
+      setWebState('closed');
+    }
+    if (IS_WEB && !prevOpenRef.current && open) {
+      setIsExiting(false);
+      setWebState('entering');
+    }
+    prevOpenRef.current = open;
+
+    const stepFocusKeyRef = useRef<string | undefined>(undefined);
+    useEffect(() => {
+      if (!open) stepFocusKeyRef.current = undefined;
+    }, [open]);
+
+    useEffect(() => {
+      if (!IS_WEB || !open) return;
+      const raf = requestAnimationFrame(() => {
+        setWebState('open');
+      });
+      return () => cancelAnimationFrame(raf);
+    }, [open]);
+
+    useEffect(() => {
+      if (!IS_WEB || !isExiting) return;
+
+      const node = popupRef.current as unknown as HTMLElement | null;
+      let done = false;
+
+      const finish = () => {
+        if (done) return;
+        done = true;
+        setIsExiting(false);
+      };
+
+      const safetyTimer = setTimeout(finish, WEB_TRANSITION_SAFETY_MS);
+
+      if (!node || typeof node.addEventListener !== 'function') {
+        return () => {
+          clearTimeout(safetyTimer);
+        };
+      }
+
+      const handler = (event: Event) => {
+        if (event.target !== node) return;
+        const propertyName = (event as unknown as { propertyName?: string }).propertyName ?? '';
+        if (propertyName === 'opacity' || propertyName === 'transform') {
+          finish();
+        }
+      };
+      node.addEventListener('transitionend', handler);
+
+      return () => {
+        clearTimeout(safetyTimer);
+        node.removeEventListener('transitionend', handler);
+      };
+    }, [isExiting]);
+
+    const shouldMount = IS_WEB ? open || isExiting : open;
+
+    if (!shouldMount) {
+      return null;
+    }
+
+    const isNativeMotion = !IS_WEB && !isAllAnimationsDisabled;
+
+    return (
+      <DialogPortalPrimitive forceMount>
+        <AnimationSettingsProvider value={animationSettings}>
+          {/*
+            No `FullWindowOverlay`: the page lives in the app window so native
+            modals (Menu, Select, picker popover) present above it. Without the
+            overlay window, VoiceOver containment comes from this wrapper, a
+            native sibling of the app tree under the root `PortalHost`.
+          */}
+          <Animated.View
+            className={fullScreenDialogPortalVariants()}
+            style={{ zIndex: MODAL_OVERLAY_Z_INDEX }}
+            entering={isNativeMotion ? surfaceMotion.entering : undefined}
+            exiting={isNativeMotion ? surfaceMotion.exiting : undefined}
+            {...(IS_WEB ? undefined : { accessibilityViewIsModal: true })}
+          >
+            <DialogContentPrimitive
+              ref={mergeRefs(ref, popupRef)}
+              forceMount
+              className={cn(fullScreenDialogPopupVariants(), className)}
+              style={style}
+              {...props}
+              {...mergeDataAttributes(
+                props,
+                dataAttributes({ slot: 'full-screen-dialog-popup' }),
+                IS_WEB ? dataAttributes({ state: webState }) : undefined,
+              )}
+            >
+              <StepFocusKeyContext.Provider value={stepFocusKeyRef}>
+                <BottomSheet.Provider>{children}</BottomSheet.Provider>
+              </StepFocusKeyContext.Provider>
+            </DialogContentPrimitive>
+          </Animated.View>
+        </AnimationSettingsProvider>
+      </DialogPortalPrimitive>
+    );
+  },
+);
+
+FullScreenDialogPopup.displayName = 'FullScreenDialog.Popup';
+
+// =============================================================================
+// STYLED HEADER (shared back / title / close row)
+// =============================================================================
+
+export interface FullScreenDialogHeaderProps {
+  /** Title text. Labels the dialog. Ignored when `children` is set. */
+  title?: string;
+  /** Secondary line under the title. Has no effect without `title`, or when `children` is set. */
+  subtitle?: string;
+  /**
+   * Custom header content. Replaces `title` and `subtitle`. The consumer then owns the
+   * dialog's accessible name and focus on step change: focus doesn't move to the header.
+   */
+  children?: ReactNode;
+  /** Classes for the header region, which includes the top safe-area padding. */
+  className?: string;
+  /** Called by the close button. @default Closes the dialog (`onOpenChange(false)`). */
+  onClose?: () => void;
+  /** Accessible name for the close button. @default Close */
+  closeAccessibilityLabel?: string;
+  /**
+   * Shows the back button when set. Android system back calls it too, instead of
+   * closing the dialog. Escape on web always closes.
+   */
+  onBack?: () => void;
+  /** Accessible name for the back button. @default Go back */
+  backAccessibilityLabel?: string;
+}
+
+const FullScreenDialogHeader = forwardRef<View, FullScreenDialogHeaderProps>(
+  (
+    {
+      title,
+      subtitle,
+      children,
+      className,
+      onClose,
+      closeAccessibilityLabel,
+      onBack,
+      backAccessibilityLabel,
+    },
+    ref,
+  ) => {
+    const { nativeID, onOpenChange, backHandlerRef } = useDialog();
+    const insets = useSafeInsets();
+    const titleRef = useRef<SheetHeaderTitleRef | null>(null);
+
+    const hasTitle = children == null && title !== undefined && title !== '';
+    useStepChangeFocus(hasTitle ? `${onBack ? 'back' : 'root'}:${title}` : undefined, titleRef);
+
+    useEffect(() => {
+      backHandlerRef.current = onBack;
+      return () => {
+        backHandlerRef.current = undefined;
+      };
+    }, [backHandlerRef, onBack]);
+
+    const handleClose = useCallback(() => {
+      onOpenChange(false);
+    }, [onOpenChange]);
+
+    return (
+      <View
+        ref={ref}
+        className={cn(fullScreenDialogHeaderVariants(), className)}
+        style={{ paddingTop: insets.top }}
+        {...dataAttributes({ slot: 'full-screen-dialog-header' })}
+      >
+        <SheetHeader
+          title={title}
+          subtitle={subtitle}
+          titleNativeID={`${nativeID}-title`}
+          titleRef={titleRef}
+          titleFocusable
+          onClose={onClose ?? handleClose}
+          closeAccessibilityLabel={closeAccessibilityLabel}
+          onBack={onBack}
+          backAccessibilityLabel={backAccessibilityLabel}
+        >
+          {children}
+        </SheetHeader>
+      </View>
+    );
+  },
+);
+
+FullScreenDialogHeader.displayName = 'FullScreenDialog.Header';
+
+// =============================================================================
+// STYLED CONTENT
+// =============================================================================
+
+export interface FullScreenDialogContentProps extends ViewProps {
+  /** Render the single child as the content region instead of a `View`. */
+  asChild?: boolean;
+  /** Classes for the content region, merged after the defaults. */
+  className?: string;
+  /** Page body. Usually a `ScrollView`. */
+  children?: ReactNode;
+}
+
+const FullScreenDialogContent = forwardRef<View, FullScreenDialogContentProps>(
+  ({ asChild, className, children, style, ...props }, ref) => {
+    const insets = useSafeInsets();
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(fullScreenDialogContentVariants(), className)}
+        style={[{ paddingBottom: insets.bottom }, style]}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'full-screen-dialog-content' }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+FullScreenDialogContent.displayName = 'FullScreenDialog.Content';
+
+// =============================================================================
+// COMPOUND COMPONENT
+// =============================================================================
+
+type FullScreenDialogCompoundComponent = typeof FullScreenDialogRoot & {
+  Trigger: typeof FullScreenDialogTrigger;
+  Popup: typeof FullScreenDialogPopup;
+  Header: typeof FullScreenDialogHeader;
+  Content: typeof FullScreenDialogContent;
+};
+
+export const FullScreenDialog = Object.assign(FullScreenDialogRoot, {
+  Trigger: FullScreenDialogTrigger,
+  Popup: FullScreenDialogPopup,
+  Header: FullScreenDialogHeader,
+  Content: FullScreenDialogContent,
+}) as FullScreenDialogCompoundComponent;

package/src/components/FullScreenDialog/styles.ts

@@ -0,0 +1,23 @@
+import { cva } from '@cdx-ui/utils';
+
+export const fullScreenDialogPortalVariants = cva([
+  'absolute inset-0',
+  'overflow-hidden',
+  'web:fixed',
+]);
+
+export const fullScreenDialogPopupVariants = cva([
+  'flex-1 flex-col',
+  'bg-surface-primary',
+  'overflow-hidden',
+  'web:transition-transform web:duration-300 web:ease-[cubic-bezier(0.32,0.72,0,1)]',
+  'web:data-[state=entering]:translate-y-full',
+  'web:data-[state=open]:translate-y-0',
+  'web:data-[state=closed]:translate-y-full web:data-[state=closed]:duration-[220ms]',
+  'web:motion-reduce:transition-none web:motion-reduce:duration-0',
+]);
+
+/** Paints the surface behind the status bar inset above the header row. */
+export const fullScreenDialogHeaderVariants = cva(['shrink-0', 'bg-surface-primary']);
+
+export const fullScreenDialogContentVariants = cva(['flex-1 min-h-0']);

package/src/components/IconButton/styles.ts

@@ -2,6 +2,12 @@ import { Platform } from 'react-native';
 import { cva, type VariantProps } from '@cdx-ui/utils';
 import { DISABLED_CURSOR, TRANSITION_COLORS } from '../../styles/constants';
 
+/** Box classes per size. Shared with layout placeholders that must match an `IconButton`'s footprint. */
+export const iconButtonSizeClassNames = {
+  default: 'h-11 w-11 min-w-11 shrink-0 p-2.5',
+  small: 'h-8 w-8 min-w-8 shrink-0 p-1.5',
+} as const;
+
 export const iconButtonRootVariants = cva(
   [
     'flex items-center justify-center',
@@ -24,10 +30,7 @@ export const iconButtonRootVariants = cva(
         action: [],
         danger: [],
       },
-      size: {
-        default: 'h-11 w-11 min-w-11 shrink-0 p-2.5',
-        small: 'h-8 w-8 min-w-8 shrink-0 p-1.5',
-      },
+      size: iconButtonSizeClassNames,
     },
     compoundVariants: [
       // ── solid × color ───────────────────────────────────────────────────

package/src/components/Input/index.tsx

@@ -42,7 +42,7 @@ export interface InputProps extends ViewProps, IInputFieldProps {
    */
   variant?: 'outline';
   /**
-   * Height and padding scale.
+   * Height, padding, and field font size.
    * @default 'default'
    */
   size?: 'default' | 'small';

package/src/components/InsuranceDisclosure/index.tsx

@@ -21,6 +21,7 @@ type InsuranceDisclosureSharedProps = Omit<HStackProps, 'children'> & {
    * Pass `framed` to restore chrome; padding is now `px-3 py-2`.
    */
   framed?: boolean;
+  /** Disclosure copy rendered beside the logo. */
   label?: string;
   className?: string;
 };

package/src/components/Link/index.tsx

@@ -24,6 +24,7 @@ export { LinkProvider, type LinkConfig, type LinkAction } from '@cdx-ui/primitiv
 // =============================================================================
 
 export interface LinkProps extends ILinkProps {
+  /** Renders the consumer's child element in place of the default pressable host. */
   asChild?: boolean;
   className?: string;
   children?: ReactNode;
@@ -52,6 +53,7 @@ LinkRoot.displayName = 'Link';
 // =============================================================================
 
 export interface LinkLabelProps extends TextProps {
+  /** Renders the consumer's child element in place of the default `Text` host. */
   asChild?: boolean;
   className?: string;
   children?: ReactNode;