@cdx-ui/components 0.0.1-beta.18 → 0.0.1-beta.181

package/src/animation/hooks/usePopupDialogContentAnimation.ts

@@ -0,0 +1,265 @@
+import { useEffect, useMemo } from 'react';
+import { Keyboard, Platform, useWindowDimensions } from 'react-native';
+import { Gesture } from 'react-native-gesture-handler';
+import {
+  Easing,
+  Extrapolation,
+  interpolate,
+  Keyframe,
+  useAnimatedStyle,
+  useDerivedValue,
+  useSharedValue,
+  withSpring,
+  type EntryOrExitLayoutType,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { scheduleOnRN } from 'react-native-worklets';
+import { useAnimationSettings } from '../../providers/animation-settings';
+import type { PopupDialogContentAnimation } from '../types';
+import { getAnimationState, getIsAnimationDisabledValue } from '../utils';
+
+const IS_WEB = Platform.OS === 'web';
+
+export interface UsePopupDialogContentAnimationOptions {
+  isOpen: boolean;
+  progress: SharedValue<number>;
+  isDragging: SharedValue<boolean>;
+  isGestureReleaseAnimationRunning: SharedValue<boolean>;
+  onOpenChange: (open: boolean) => void;
+  animation?: PopupDialogContentAnimation;
+  /** @default true */
+  isSwipeable?: boolean;
+}
+
+const DEFAULT_ENTERING_ANIMATION: EntryOrExitLayoutType = new Keyframe({
+  0: {
+    transform: [{ scale: 0.96 }],
+    opacity: 0,
+  },
+  100: {
+    transform: [{ scale: 1 }],
+    opacity: 1,
+    easing: Easing.out(Easing.ease),
+  },
+}).duration(200);
+
+const DEFAULT_EXITING_ANIMATION: EntryOrExitLayoutType = new Keyframe({
+  0: {
+    transform: [{ scale: 1 }],
+    opacity: 1,
+  },
+  100: {
+    transform: [{ scale: 0.96 }],
+    opacity: 0,
+    easing: Easing.in(Easing.ease),
+  },
+}).duration(150);
+
+/**
+ * Animation hook for popup dialog content (panel).
+ * Handles enter/exit Keyframes, swipe-to-dismiss gesture, and drag-driven
+ * translateY + scale via a shared `progress` value.
+ *
+ * On web, entering/exiting are undefined (CSS transitions drive the visuals)
+ * and the gesture is disabled.
+ */
+export function usePopupDialogContentAnimation({
+  isOpen,
+  progress,
+  isDragging,
+  isGestureReleaseAnimationRunning,
+  onOpenChange,
+  animation,
+  isSwipeable = true,
+}: UsePopupDialogContentAnimationOptions) {
+  const { height: screenHeight } = useWindowDimensions();
+
+  const animationSettingsContext = useAnimationSettings();
+  const isAllAnimationsDisabled = animationSettingsContext?.isAllAnimationsDisabled;
+
+  const { animationConfig, isAnimationDisabled } = getAnimationState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  const enteringValue = animationConfig?.entering ?? DEFAULT_ENTERING_ANIMATION;
+  const exitingValue = animationConfig?.exiting ?? DEFAULT_EXITING_ANIMATION;
+
+  const contentY = useSharedValue(0);
+  const contentHeight = useSharedValue(0);
+  const progressAnchor = useSharedValue(1);
+  const contentTranslateYAnchor = useSharedValue(0);
+  const contentScaleAnchor = useSharedValue(1);
+  const gestureTranslationY = useSharedValue(0);
+
+  useEffect(() => {
+    if (isOpen) {
+      progress.set(1);
+    }
+  }, [isOpen, progress]);
+
+  const dismissKeyboard = () => {
+    Keyboard.dismiss();
+  };
+
+  // Explicit deps for Vite/web without the Reanimated Babel plugin.
+  const contentTranslateY = useDerivedValue(() => {
+    const maxDragDistance = screenHeight - contentY.get();
+
+    if (progress.get() >= 1) {
+      return interpolate(progress.get(), [1, 2], [0, maxDragDistance], Extrapolation.CLAMP);
+    }
+
+    const absoluteGestureTranslationY = Math.abs(gestureTranslationY.get());
+
+    return interpolate(
+      absoluteGestureTranslationY,
+      [0, screenHeight],
+      [0, -50],
+      Extrapolation.CLAMP,
+    );
+  }, [progress, screenHeight, contentY, gestureTranslationY]);
+
+  const contentScale = useDerivedValue(() => {
+    return interpolate(progress.get(), [1, 2], [1, 0.95], Extrapolation.CLAMP);
+  }, [progress]);
+
+  const panGesture = useMemo(
+    () =>
+      Gesture.Pan()
+        .enabled(isSwipeable && isOpen && !isAnimationDisabledValue && !IS_WEB)
+        .onStart(() => isDragging.set(true))
+        .onUpdate((event) => {
+          if (!isDragging.get()) return;
+
+          const maxDragDistance = screenHeight - contentY.get();
+
+          gestureTranslationY.set(event.translationY);
+
+          if (event.translationY > 0) {
+            const progressValue = 1 + event.translationY / maxDragDistance;
+            progress.set(Math.max(1, Math.min(progressValue, 2)));
+          } else if (event.translationY < 0) {
+            const progressValue = 1 - Math.abs(event.translationY) / contentY.get();
+            progress.set(Math.max(0, Math.min(progressValue, 1)));
+          }
+        })
+        .onFinalize(() => {
+          progressAnchor.set(progress.get());
+          contentTranslateYAnchor.set(contentTranslateY.get());
+          contentScaleAnchor.set(contentScale.get());
+
+          if (progress.get() > 1.1) {
+            isGestureReleaseAnimationRunning.set(true);
+            scheduleOnRN(dismissKeyboard);
+            progress.set(
+              withSpring(
+                2,
+                {
+                  mass: 4,
+                  damping: 120,
+                  stiffness: 900,
+                  overshootClamping: false,
+                },
+                () => {
+                  isGestureReleaseAnimationRunning.set(false);
+                },
+              ),
+            );
+            isDragging.set(false);
+            setTimeout(() => {
+              progress.set(2);
+              scheduleOnRN(onOpenChange, false);
+            }, 300);
+            setTimeout(() => {
+              progress.set(0);
+            }, 350);
+          } else {
+            isGestureReleaseAnimationRunning.set(true);
+            progress.set(
+              withSpring(1, {}, () => {
+                isGestureReleaseAnimationRunning.set(false);
+              }),
+            );
+            isDragging.set(false);
+          }
+        }),
+    [
+      contentScale,
+      contentScaleAnchor,
+      contentTranslateY,
+      contentTranslateYAnchor,
+      contentY,
+      isOpen,
+      isDragging,
+      isGestureReleaseAnimationRunning,
+      isSwipeable,
+      onOpenChange,
+      progress,
+      progressAnchor,
+      screenHeight,
+      isAnimationDisabledValue,
+      gestureTranslationY,
+    ],
+  );
+
+  const rDragContainerStyle = useAnimatedStyle(() => {
+    if (isGestureReleaseAnimationRunning.get()) {
+      return {
+        opacity: interpolate(progress.get(), [1, progressAnchor.get(), 1.5, 1.75], [1, 1, 1, 0]),
+        transform: [
+          {
+            translateY: interpolate(
+              progress.get(),
+              [progressAnchor.get(), 1, progressAnchor.get(), progressAnchor.get() + 0.1, 2],
+              [
+                contentTranslateYAnchor.get(),
+                0,
+                contentTranslateYAnchor.get(),
+                contentTranslateYAnchor.get() + 50,
+                contentTranslateYAnchor.get() - 150,
+              ],
+            ),
+          },
+          {
+            scale: interpolate(
+              progress.get(),
+              [progressAnchor.get(), 1, progressAnchor.get(), 2],
+              [contentScaleAnchor.get(), 1, contentScaleAnchor.get(), 0.75],
+            ),
+          },
+        ],
+      };
+    }
+
+    return {
+      transform: [
+        {
+          translateY: contentTranslateY.get(),
+        },
+        {
+          scale: contentScale.get(),
+        },
+      ],
+    };
+  }, [
+    isGestureReleaseAnimationRunning,
+    progress,
+    progressAnchor,
+    contentTranslateYAnchor,
+    contentScaleAnchor,
+    contentTranslateY,
+    contentScale,
+  ]);
+
+  return {
+    contentY,
+    contentHeight,
+    panGesture,
+    rDragContainerStyle,
+    entering: isAnimationDisabledValue || IS_WEB ? undefined : enteringValue,
+    exiting: isAnimationDisabledValue || IS_WEB ? undefined : exitingValue,
+  };
+}

package/src/animation/hooks/usePopupOverlayAnimation.ts

@@ -0,0 +1,91 @@
+import { Platform } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+import { FadeIn, FadeOut, interpolate, useAnimatedStyle } from 'react-native-reanimated';
+import { useAnimationSettings } from '../../providers/animation-settings';
+import type { PopupOverlayAnimation } from '../types';
+import {
+  getAnimationState,
+  getAnimationValueProperty,
+  getIsAnimationDisabledValue,
+} from '../utils';
+
+const IS_WEB = Platform.OS === 'web';
+
+export interface UsePopupOverlayAnimationOptions {
+  /** Animation progress shared value (0=idle, 1=open, 2=close) */
+  progress?: SharedValue<number>;
+  /** Dragging state shared value */
+  isDragging?: SharedValue<boolean>;
+  /** Gesture release animation running state (for components with swipe gestures) */
+  isGestureReleaseAnimationRunning?: SharedValue<boolean>;
+  /** Animation configuration for overlay */
+  animation?: PopupOverlayAnimation;
+}
+
+/**
+ * Animation hook for popup overlay (backdrop) components.
+ * Shared by Dialog, Select, BottomSheet, Popover, etc.
+ *
+ * Returns progress-based opacity style and entering/exiting layout animations.
+ * On web, entering/exiting are undefined (CSS transitions drive the visuals).
+ */
+export function usePopupOverlayAnimation(options: UsePopupOverlayAnimationOptions) {
+  const { progress, isDragging, isGestureReleaseAnimationRunning, animation } = options;
+
+  const animationSettingsContext = useAnimationSettings();
+  const isAllAnimationsDisabled = animationSettingsContext?.isAllAnimationsDisabled;
+
+  const { animationConfig, isAnimationDisabled } = getAnimationState(animation);
+
+  const isAnimationDisabledValue = getIsAnimationDisabledValue({
+    isAnimationDisabled,
+    isAllAnimationsDisabled,
+  });
+
+  const opacityValue = getAnimationValueProperty({
+    animationValue: animationConfig?.opacity,
+    property: 'value',
+    defaultValue: [0, 1, 0] as [number, number, number],
+  });
+
+  // Explicit deps for Vite/web without the Reanimated Babel plugin.
+  const rContainerStyle = useAnimatedStyle(() => {
+    if (progress?.get() === undefined) {
+      return {};
+    }
+
+    if (isAnimationDisabledValue) {
+      return {
+        opacity: progress.get() > 0 ? 1 : 0,
+      };
+    }
+
+    if ((isDragging?.get() || isGestureReleaseAnimationRunning?.get()) && progress.get() <= 1) {
+      return {
+        opacity: 1,
+      };
+    }
+
+    return {
+      opacity: interpolate(progress.get(), [0, 1, 2], opacityValue),
+    };
+  }, [
+    progress,
+    isDragging,
+    isGestureReleaseAnimationRunning,
+    isAnimationDisabledValue,
+    opacityValue,
+  ]);
+
+  const enteringValue =
+    animationConfig?.entering ?? (isAnimationDisabledValue ? undefined : FadeIn.duration(200));
+
+  const exitingValue =
+    animationConfig?.exiting ?? (isAnimationDisabledValue ? undefined : FadeOut.duration(150));
+
+  return {
+    rContainerStyle,
+    entering: isAnimationDisabledValue || IS_WEB ? undefined : enteringValue,
+    exiting: isAnimationDisabledValue || IS_WEB ? undefined : exitingValue,
+  };
+}

package/src/animation/hooks/usePopupRootAnimation.ts

@@ -0,0 +1,27 @@
+import { useSharedValue } from 'react-native-reanimated';
+import type { AnimationRootDisableAll } from '../types';
+import { useCombinedAnimationDisabledState } from './useCombinedAnimationDisabledState';
+
+export interface UsePopupRootAnimationOptions {
+  animation?: AnimationRootDisableAll;
+}
+
+/**
+ * Root animation hook for popup-like components (Dialog, Select, BottomSheet, Popover, etc.)
+ * Manages component state transitions and animation coordination via a shared
+ * `progress` value: 0 = idle/closed, 1 = fully open, 2 = dismissed.
+ */
+export function usePopupRootAnimation(options: UsePopupRootAnimationOptions) {
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(options.animation);
+
+  const progress = useSharedValue(0);
+  const isDragging = useSharedValue(false);
+  const isGestureReleaseAnimationRunning = useSharedValue(false);
+
+  return {
+    isAllAnimationsDisabled,
+    progress,
+    isDragging,
+    isGestureReleaseAnimationRunning,
+  };
+}

package/src/animation/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './hooks';
+export * from './utils';

package/src/animation/types.ts

@@ -0,0 +1,128 @@
+import type {
+  BaseAnimationBuilder,
+  EntryOrExitLayoutType,
+  LayoutAnimationFunction,
+  WithSpringConfig,
+  WithTimingConfig,
+} from 'react-native-reanimated';
+
+/**
+ * Universal animation prop type
+ * - `true` or `undefined`: Use default animations
+ * - `false` or `"disabled"`: Disable all animations
+ * - `object`: Custom animation configuration
+ *   - Can include `state?: 'disabled' | boolean | undefined` to disable animations while customizing properties
+ */
+export type Animation<TConfig extends Record<string, any> = Record<string, any>> =
+  | boolean
+  | 'disabled'
+  | (TConfig & { state?: 'disabled' | boolean });
+
+export type AnimationDisabled = 'disabled' | false;
+
+/**
+ * Root-level animation prop type with cascading control
+ * - `true` or `undefined`: Use default animations
+ * - `false` or `"disabled"`: Disable only root animations (children can still animate)
+ * - `"disable-all"`: Disable all animations including children (cascades down)
+ * - `object`: Custom animation configuration
+ *   - Can include `state?: 'disabled' | 'disable-all' | boolean` to disable animations while customizing properties
+ */
+export type AnimationRoot<TConfig extends Record<string, any> = Record<string, any>> =
+  | boolean
+  | 'disabled'
+  | 'disable-all'
+  | (TConfig & { state?: 'disabled' | 'disable-all' | boolean });
+
+export type AnimationRootDisableAll = Extract<AnimationRoot, 'disable-all'>;
+
+/**
+ * Animation value that can be a custom config
+ * Used for granular animation control within a component
+ */
+export type AnimationValue<TConfig extends Record<string, any> = Record<string, any>> = TConfig;
+
+export type LayoutTransition =
+  | BaseAnimationBuilder
+  | LayoutAnimationFunction
+  | typeof BaseAnimationBuilder
+  | undefined;
+
+/**
+ * Spring animation configuration
+ */
+export interface SpringAnimationConfig {
+  type: 'spring';
+  config?: WithSpringConfig;
+}
+
+/**
+ * Timing animation configuration
+ */
+export interface TimingAnimationConfig {
+  type: 'timing';
+  config?: WithTimingConfig;
+}
+
+/**
+ * Animation configuration for popup overlay components (Dialog, Select, BottomSheet, Popover, etc.)
+ * Supports both progress-based opacity animation and entering/exiting animations
+ */
+export type PopupOverlayAnimation = Animation<{
+  /**
+   * Opacity animation configuration (progress-based)
+   * Takes effect for bottom-sheet/dialog presentation
+   * @default [0, 1, 0] - opacity values for [idle, open, close] states
+   */
+  opacity?: AnimationValue<{
+    /**
+     * Opacity values [idle, open, close]
+     * @default [0, 1, 0]
+     */
+    value?: [number, number, number];
+  }>;
+  /**
+   * Takes effect for popover presentation
+   * @default FadeIn with duration 200ms
+   */
+  entering?: EntryOrExitLayoutType;
+  /**
+   * Takes effect for popover presentation
+   * @default FadeOut with duration 150ms
+   */
+  exiting?: EntryOrExitLayoutType;
+}>;
+
+/**
+ * Animation configuration for popup dialog content components (Dialog, Select dialog presentation)
+ * Supports opacity and scale animations
+ */
+export type PopupDialogContentAnimation = Animation<{
+  /**
+   * Custom Keyframe animation for entering transition
+   * @default Keyframe with scale, and opacity (200ms)
+   */
+  entering?: EntryOrExitLayoutType;
+  /**
+   * Custom Keyframe animation for exiting transition
+   * @default Keyframe mirroring entering animation (150ms)
+   */
+  exiting?: EntryOrExitLayoutType;
+}>;
+
+/**
+ * Animation configuration for popup popover content components (Popover, Select popover presentation)
+ * Supports custom Keyframe animations for entering and exiting transitions
+ */
+export type PopupPopoverContentAnimation = Animation<{
+  /**
+   * Custom Keyframe animation for entering transition
+   * @default Keyframe with translateY/translateX, scale, and opacity (200ms)
+   */
+  entering?: EntryOrExitLayoutType;
+  /**
+   * Custom Keyframe animation for exiting transition
+   * @default Keyframe mirroring entering animation (150ms)
+   */
+  exiting?: EntryOrExitLayoutType;
+}>;