@cdx-ui/components 0.1.5 → 0.1.7

package/src/components/BottomSheet/index.tsx

@@ -1,5 +1,15 @@
-import React, { forwardRef, useCallback, useContext, useRef, type ReactNode } from 'react';
-import { Dimensions, View, ViewStyle } from 'react-native';
+import React, {
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { BackHandler, Dimensions, Platform, View, ViewStyle } from 'react-native';
 import { SafeAreaInsetsContext, type EdgeInsets } from 'react-native-safe-area-context';
 import { useResolveClassNames } from 'uniwind';
 import {
@@ -14,16 +24,13 @@ import {
   type BottomSheetFooterProps as GorhomBottomSheetFooterProps,
   type BottomSheetModalProps as GorhomBottomSheetModalProps,
 } from '@gorhom/bottom-sheet';
+import { useEscapeKey, useOverlayStackRegistration } from '@cdx-ui/primitives';
 import { cn } from '@cdx-ui/utils';
-import { ArrowBack, Close } from '@cdx-ui/icons';
-import { Heading } from '../Heading';
-import { IconButton } from '../IconButton';
-import { Text } from '../Text';
+import { SheetHeader } from '../sheet-header';
 import {
   bottomSheetBackgroundClassName,
   bottomSheetContentVariants,
   bottomSheetFooterVariants,
-  bottomSheetHeaderVariants,
   bottomSheetModalContainerClassName,
 } from './styles';
 
@@ -37,131 +44,52 @@ function useSafeInsets(): EdgeInsets {
 export type BottomSheetModalRef = React.ComponentRef<typeof BottomSheetModal>;
 
 export interface BottomSheetHeaderProps {
+  /** Title text. 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`. */
   children?: ReactNode;
   className?: string;
+  /** Shows the close button when set. */
   onClose?: () => void;
+  /** Accessible name for the close button. @default Close */
   closeAccessibilityLabel?: string;
+  /** Shows the back button when set. */
   onBack?: () => void;
+  /** Accessible name for the back button. @default Go back */
   backAccessibilityLabel?: string;
 }
 
-function BottomSheetHeaderComponent(
-  {
-    title,
-    subtitle,
-    children,
-    className,
-    onClose,
-    closeAccessibilityLabel,
-    onBack,
-    backAccessibilityLabel = 'Go back',
-  }: BottomSheetHeaderProps,
-  ref: React.Ref<View>,
-) {
-  const hasTitle = title !== undefined && title !== '';
-  const hasContent = hasTitle || !!children || !!onBack;
-  const computedClassName = cn(bottomSheetHeaderVariants({ hasTitle: hasContent }), className);
-  return (
-    <View ref={ref} className={computedClassName}>
-      <BottomSheetBackButton
-        className={cn(!onBack && 'opacity-0')}
-        onPress={onBack}
-        {...(backAccessibilityLabel !== undefined && {
-          accessibilityLabel: backAccessibilityLabel,
-        })}
-      />
-      <View className="flex-1">
-        {children ??
-          (hasTitle ? (
-            <View>
-              <Heading size="sm" className="text-center">
-                {title}
-              </Heading>
-              {subtitle ? (
-                <Text size="sm" className="text-center text-content-secondary">
-                  {subtitle}
-                </Text>
-              ) : null}
-            </View>
-          ) : null)}
-      </View>
-      <BottomSheetCloseButton
-        className={cn(!onClose && 'opacity-0')}
-        onPress={onClose}
-        {...(closeAccessibilityLabel !== undefined && {
-          accessibilityLabel: closeAccessibilityLabel,
-        })}
-      />
-    </View>
-  );
-}
-
-BottomSheetHeaderComponent.displayName = 'BottomSheet.Header';
-
-const BottomSheetHeader = forwardRef<View, BottomSheetHeaderProps>(BottomSheetHeaderComponent);
-BottomSheetHeader.displayName = 'BottomSheet.Header';
-
-// =============================================================================
-// BACKBUTTON
-// =============================================================================
-interface BottomSheetBackButtonProps {
-  onPress?: () => void;
-  className?: string;
-  accessibilityLabel?: string;
-}
-
-function BottomSheetBackButton({
-  onPress,
-  className,
-  accessibilityLabel = 'Go back',
-}: Readonly<BottomSheetBackButtonProps>) {
-  return (
-    <IconButton
-      as={ArrowBack}
-      variant="solid"
-      color="neutral"
-      size="default"
-      onPress={onPress}
-      hitSlop={12}
-      accessibilityLabel={accessibilityLabel}
-      className={className}
-    />
-  );
-}
-
-BottomSheetBackButton.displayName = 'BottomSheet.BackButton';
-
-// =============================================================================
-// CLOSEBUTTON
-// =============================================================================
-interface BottomSheetCloseButtonProps {
-  onPress?: () => void;
-  className?: string;
-  accessibilityLabel?: string;
-}
-
-function BottomSheetCloseButton({
-  onPress,
-  className,
-  accessibilityLabel = 'Close',
-}: Readonly<BottomSheetCloseButtonProps>) {
-  return (
-    <IconButton
-      as={Close}
-      variant="solid"
-      color="neutral"
-      size="default"
-      onPress={onPress}
-      hitSlop={12}
-      accessibilityLabel={accessibilityLabel}
+const BottomSheetHeader = forwardRef<View, BottomSheetHeaderProps>(
+  (
+    {
+      title,
+      subtitle,
+      children,
+      className,
+      onClose,
+      closeAccessibilityLabel,
+      onBack,
+      backAccessibilityLabel,
+    },
+    ref,
+  ) => (
+    <SheetHeader
+      ref={ref}
+      title={title}
+      subtitle={subtitle}
       className={className}
-    />
-  );
-}
-
-BottomSheetCloseButton.displayName = 'BottomSheet.CloseButton';
+      onClose={onClose}
+      closeAccessibilityLabel={closeAccessibilityLabel}
+      onBack={onBack}
+      backAccessibilityLabel={backAccessibilityLabel}
+    >
+      {children}
+    </SheetHeader>
+  ),
+);
+BottomSheetHeader.displayName = 'BottomSheet.Header';
 
 // =============================================================================
 // CONTENT
@@ -170,6 +98,7 @@ BottomSheetCloseButton.displayName = 'BottomSheet.CloseButton';
 export interface BottomSheetContentProps {
   children?: ReactNode;
   className?: string;
+  /** Adds bottom padding equal to the safe-area inset. */
   hasSafeAreaInset?: boolean;
   style?: ViewStyle;
 }
@@ -228,7 +157,10 @@ BottomSheetFooter.displayName = 'BottomSheet.Footer';
 export interface BottomSheetModalProps extends GorhomBottomSheetModalProps {
   /** Show the drag handle indicator. When false, `handleComponent` is set to null. @default true */
   handleVisible?: boolean;
-  /** Footer content rendered via gorhom's BottomSheetFooter for proper animated positioning and safe-area handling. */
+  /**
+   * Footer content rendered via gorhom's BottomSheetFooter for animated positioning and safe-area handling.
+   * Pass it through this prop; a footer placed as a child does not animate with the sheet.
+   */
   footer?: ReactNode;
 }
 
@@ -253,7 +185,7 @@ const CustomBackground = (props: React.ComponentPropsWithoutRef<typeof View>) =>
 const BottomSheetModalStyled = forwardRef<
   React.ComponentRef<typeof BottomSheetModal>,
   BottomSheetModalProps
->(({ handleVisible = true, footer, onDismiss, onChange, ...rest }, ref) => {
+>(({ handleVisible = true, footer, onDismiss, onChange, onAnimate, ...rest }, ref) => {
   const renderFooter = useCallback(
     (props: GorhomBottomSheetFooterProps) => (
       <GorhomBottomSheetFooter {...props}>{footer}</GorhomBottomSheetFooter>
@@ -261,9 +193,67 @@ const BottomSheetModalStyled = forwardRef<
     [footer],
   );
 
+  const modalRef = useRef<BottomSheetModalRef | null>(null);
   const dismissedRef = useRef(false);
+  const sheetMountedRef = useRef(false);
+  const mountPendingRef = useRef(false);
+  const pendingDismissRef = useRef<Parameters<BottomSheetModalRef['dismiss']> | null>(null);
+  const [presented, setPresented] = useState(false);
+
+  // Must stay a callback ref: gorhom hands this ref to its modal provider, which
+  // reads `.current` to minimize and restore stacked sheets. A ref object would
+  // switch that stacking on.
+  const setModalRef = useCallback((instance: BottomSheetModalRef | null) => {
+    modalRef.current = instance;
+  }, []);
+
+  // gorhom mounts the sheet a frame after `present()` and silently drops a
+  // `dismiss()` that arrives before then, never reporting `onDismiss`. Holding
+  // it until the sheet mounts keeps the early Escape/back claim releasable.
+  const dismissSheet = useCallback((...args: Parameters<BottomSheetModalRef['dismiss']>) => {
+    if (mountPendingRef.current) {
+      pendingDismissRef.current = args;
+      return;
+    }
+    modalRef.current?.dismiss(...args);
+  }, []);
+
+  const markSheetMounted = useCallback(() => {
+    sheetMountedRef.current = true;
+    if (!mountPendingRef.current) return;
+    mountPendingRef.current = false;
+    const pendingDismiss = pendingDismissRef.current;
+    pendingDismissRef.current = null;
+    if (pendingDismiss) modalRef.current?.dismiss(...pendingDismiss);
+  }, []);
+
+  // `present()` claims Escape and back immediately; waiting for the first
+  // `onChange` would leave the overlay beneath in charge for the whole open animation.
+  useImperativeHandle(
+    ref,
+    (): BottomSheetModalRef => ({
+      present: (...args) => {
+        dismissedRef.current = false;
+        if (!sheetMountedRef.current) mountPendingRef.current = true;
+        setPresented(true);
+        modalRef.current?.present(...args);
+      },
+      dismiss: dismissSheet,
+      snapToIndex: (...args) => modalRef.current?.snapToIndex(...args),
+      snapToPosition: (...args) => modalRef.current?.snapToPosition(...args),
+      expand: (...args) => modalRef.current?.expand(...args),
+      collapse: (...args) => modalRef.current?.collapse(...args),
+      close: (...args) => modalRef.current?.close(...args),
+      forceClose: (...args) => modalRef.current?.forceClose(...args),
+    }),
+    [dismissSheet],
+  );
 
   const handleDismiss = useCallback(() => {
+    sheetMountedRef.current = false;
+    mountPendingRef.current = false;
+    pendingDismissRef.current = null;
+    setPresented(false);
     if (dismissedRef.current) return;
     dismissedRef.current = true;
     onDismiss?.();
@@ -272,11 +262,51 @@ const BottomSheetModalStyled = forwardRef<
   const handleChange = useCallback(
     (...args: Parameters<NonNullable<BottomSheetModalProps['onChange']>>) => {
       dismissedRef.current = false;
+      setPresented(args[0] >= 0);
+      if (args[0] >= 0) markSheetMounted();
       onChange?.(...args);
     },
-    [onChange],
+    [markSheetMounted, onChange],
   );
 
+  const handleAnimate = useCallback(
+    (...args: Parameters<NonNullable<BottomSheetModalProps['onAnimate']>>) => {
+      if (args[1] >= 0) markSheetMounted();
+      onAnimate?.(...args);
+    },
+    [markSheetMounted, onAnimate],
+  );
+
+  const id = useId();
+  const overlayId = `bottom-sheet-${id}`;
+  useEscapeKey(presented, dismissSheet, {
+    id: overlayId,
+    groupId: overlayId,
+    layer: 'modal',
+  });
+  const { isTopmost } = useOverlayStackRegistration({
+    active: presented && Platform.OS !== 'web',
+    capabilities: ['back'],
+    id: overlayId,
+    groupId: overlayId,
+    layer: 'modal',
+  });
+
+  useEffect(() => {
+    // BackHandler is native-only; react-native-web warns on every subscription.
+    if (!presented || Platform.OS === 'web') return;
+
+    const backHandler = BackHandler.addEventListener('hardwareBackPress', () => {
+      if (!isTopmost('back')) return false;
+      dismissSheet();
+      return true;
+    });
+
+    return () => {
+      backHandler.remove();
+    };
+  }, [dismissSheet, isTopmost, presented]);
+
   const sheetContainerStyle = useResolveClassNames(bottomSheetModalContainerClassName);
   const handleIndicatorStyle = useResolveClassNames(
     'bg-surface-neutral-subtle w-9 h-[5px] rounded-full',
@@ -284,7 +314,7 @@ const BottomSheetModalStyled = forwardRef<
 
   return (
     <BottomSheetModal
-      ref={ref}
+      ref={setModalRef}
       enableDynamicSizing
       maxDynamicContentSize={MAX_DYNAMIC_CONTENT_SIZE}
       style={sheetContainerStyle}
@@ -295,6 +325,7 @@ const BottomSheetModalStyled = forwardRef<
       {...rest}
       onDismiss={handleDismiss}
       onChange={handleChange}
+      onAnimate={handleAnimate}
       {...(footer != null && { footerComponent: renderFooter })}
     />
   );

package/src/components/BottomSheet/styles.ts

@@ -1,4 +1,4 @@
-import { cva, type VariantProps } from '@cdx-ui/utils';
+import { cva } from '@cdx-ui/utils';
 
 /** Keep gorhom's animated container unclipped so web transforms can settle correctly. */
 export const bottomSheetModalContainerClassName = 'rounded-t-4xl';
@@ -6,27 +6,6 @@ export const bottomSheetModalContainerClassName = 'rounded-t-4xl';
 /** Clip the static background for rounded corners without clipping the animated sheet. */
 export const bottomSheetBackgroundClassName = `${bottomSheetModalContainerClassName} overflow-hidden bg-surface-primary`;
 
-export const bottomSheetHeaderVariants = cva(
-  [
-    'flex-row items-center justify-between min-h-11 px-4 pt-3 pb-2.5',
-    'bg-surface-primary',
-    'text-content-primary',
-  ],
-  {
-    variants: {
-      hasTitle: {
-        true: '',
-        false: 'justify-end',
-      },
-    },
-    defaultVariants: {
-      hasTitle: true,
-    },
-  },
-);
-
 export const bottomSheetContentVariants = cva(['bg-surface-primary', 'px-5 pb-5 gap-3']);
 
 export const bottomSheetFooterVariants = cva(['px-5 pb-5 gap-2', 'bg-surface-primary']);
-
-export type BottomSheetHeaderVariants = VariantProps<typeof bottomSheetHeaderVariants>;

package/src/components/Button/index.tsx

@@ -342,7 +342,10 @@ export interface ButtonSpinnerProps extends ActivityIndicatorProps {
   asChild?: boolean;
   /** Additional Uniwind/Tailwind classes for the spinner container. */
   className?: string;
-  /** Uniwind `accent-*` color class override for the spinner. */
+  /**
+   * Uniwind `accent-*` color class override for the spinner.
+   * When omitted, the color is derived from the parent button's `variant` and `color`.
+   */
   colorClassName?: string;
   /**
    * Position hint that emits `data-icon="inline-start"` or `data-icon="inline-end"`.
@@ -350,6 +353,11 @@ export interface ButtonSpinnerProps extends ActivityIndicatorProps {
    * Omit to apply the symmetric baseline gap.
    */
   position?: IconSlotPosition;
+  /**
+   * Screen reader label for the spinner.
+   * @default 'Loading'
+   */
+  accessibilityLabel?: string;
 }
 
 const ButtonSpinner = forwardRef<ActivityIndicator, ButtonSpinnerProps>(

package/src/components/Card/index.tsx

@@ -22,6 +22,11 @@ const SCOPE = 'CARD';
 const useCardStyleContext = () => useStyleContext(SCOPE) as CardVariantProps;
 
 export interface CardProps extends ViewProps, CardVariantProps {
+  /**
+   * When `true`, `Card.Content` drops its padding and `Card.Footer` uses standalone
+   * padding. Both inherit this unless they set their own `fullBleed`.
+   */
+  fullBleed?: CardVariantProps['fullBleed'];
   asChild?: boolean;
   className?: string;
   children?: ReactNode;
@@ -117,6 +122,10 @@ CardHeader.displayName = 'Card.Header';
 // =============================================================================
 
 export interface CardContentProps extends ViewProps, CardContentVariantProps {
+  /**
+   * Removes this region's padding. Inherits the parent `Card`'s `fullBleed` when omitted.
+   */
+  fullBleed?: CardContentVariantProps['fullBleed'];
   asChild?: boolean;
   className?: string;
   children?: ReactNode;
@@ -152,6 +161,11 @@ CardContent.displayName = 'Card.Content';
 // =============================================================================
 
 export interface CardFooterProps extends ViewProps, CardFooterVariantProps {
+  /**
+   * Uses standalone padding instead of flush-top padding. Inherits the parent
+   * `Card`'s `fullBleed` when omitted.
+   */
+  fullBleed?: CardFooterVariantProps['fullBleed'];
   asChild?: boolean;
   className?: string;
   children?: ReactNode;

package/src/components/Chip/index.tsx

@@ -42,7 +42,7 @@ let hasWarnedChipDefaultColor = false;
 
 export interface ChipProps extends IChipProps, Omit<ChipVariantProps, 'variant' | 'color'> {
   /**
-   * Visual style variant.
+   * Filled subtle surface (`subtle`) or transparent with a border (`outline`).
    * @default 'subtle'
    */
   variant?:

package/src/components/CurrencyInput/index.tsx

@@ -40,9 +40,9 @@ export interface CurrencyInputProps
       TextInputProps,
       'accessibilityLabel' | 'accessibilityHint' | 'testID' | 'onFocus' | 'onBlur' | 'returnKeyType'
     > {
-  /** Current numeric value. Renders formatted zero when undefined or null. */
+  /** Current amount in major currency units, not cents. Renders a formatted zero when omitted or null. */
   value?: number;
-  /** Called with the parsed number when the user changes the amount. */
+  /** Called with the parsed amount in major currency units, not cents, when the user edits the field. */
   onChangeValue?: (value: number) => void;
   /** Currency symbol rendered as an inline prefix. Defaults to `"$"`. */
   currencySymbol?: string;

package/src/components/Dialog/index.tsx

@@ -95,6 +95,7 @@ const AnimatedOverlay = Animated.createAnimatedComponent(DialogOverlayPrimitive)
 export interface DialogRootProps
   extends Omit<ViewProps, 'children' | 'role'>, IDialogRootProps, DialogVariantProps {
   className?: string;
+  /** Pass `'disable-all'` to turn off enter/exit and swipe animations for the popup and overlay. */
   animation?: AnimationRootDisableAll;
 }
 
@@ -174,7 +175,16 @@ export interface DialogPopupProps
   extends Omit<IDialogContentProps, 'asChild'>, Pick<DialogVariantProps, 'size'> {
   className?: string;
   children?: ReactNode;
+  /**
+   * On iOS, render in a plain `View` instead of `FullWindowOverlay`. Re-enables
+   * the element inspector, but the popup no longer layers above native modals.
+   * @default false
+   */
   disableFullWindowOverlay?: boolean;
+  /**
+   * Allow swipe-down to dismiss. Native only; no effect on web.
+   * @default true
+   */
   isSwipeable?: boolean;
   /**
    * Stacking order for the portal overlay layer (backdrop + popup panel).

package/src/components/Dialog/styles.ts

@@ -141,6 +141,7 @@ export const dialogCloseIconVariants = cva(['size-5 text-content-tertiary']);
 // ── Exported types ──────────────────────────────────────────
 
 export type DialogVariantProps = VariantProps<typeof dialogPopupVariants> & {
+  /** Removes horizontal padding from `Dialog.Content`. @default false */
   fullBleed?: boolean;
 };
 

package/src/components/Divider/index.tsx

@@ -15,10 +15,15 @@ export interface DividerProps extends ViewProps {
   className?: string;
   /** Renders a vertical divider instead of the default horizontal orientation. */
   vertical?: boolean;
+  /**
+   * When present, splits the divider into line, content, line.
+   * Use `Divider.Label` so the label receives the correct typography and accessibility treatment.
+   */
   children?: ReactNode;
 }
 
 export interface DividerLabelProps extends TextProps {
+  /** Renders the consumer's child element in place of the default `Text` host. */
   asChild?: boolean;
   className?: string;
 }

package/src/components/Form/styles.ts

@@ -1,3 +1,3 @@
 import { cva } from '@cdx-ui/utils';
 
-export const formRootVariants = cva(['flex-col gap-4']);
+export const formRootVariants = cva(['flex flex-col gap-4']);

package/src/components/FullScreenDialog/animation.ts

@@ -0,0 +1,22 @@
+import { Easing, Keyframe } from 'react-native-reanimated';
+
+export const FULL_SCREEN_DIALOG_ENTER_MS = 300;
+export const FULL_SCREEN_DIALOG_EXIT_MS = 220;
+export const WEB_TRANSITION_SAFETY_MS = FULL_SCREEN_DIALOG_ENTER_MS + 100;
+
+const ENTER_EASING = Easing.bezier(0.32, 0.72, 0, 1);
+const EXIT_EASING = Easing.bezier(0.4, 0, 1, 1);
+
+/** Native slide-up surface motion. `offscreen` is the distance below the viewport to start from. */
+export function getFullScreenDialogSurfaceMotion(offscreen: number) {
+  return {
+    entering: new Keyframe({
+      0: { transform: [{ translateY: offscreen }] },
+      100: { transform: [{ translateY: 0 }], easing: ENTER_EASING },
+    }).duration(FULL_SCREEN_DIALOG_ENTER_MS),
+    exiting: new Keyframe({
+      0: { transform: [{ translateY: 0 }] },
+      100: { transform: [{ translateY: offscreen }], easing: EXIT_EASING },
+    }).duration(FULL_SCREEN_DIALOG_EXIT_MS),
+  };
+}