@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/BottomSheet/BottomSheet.tsx

@@ -0,0 +1,476 @@
+//
+// GPU-accelerated BottomSheet using translate3d transforms for better mobile performance
+//
+// This component uses static height and translate3d transforms instead of height animations
+// for improved performance on mobile devices. Key improvements:
+// - GPU acceleration through translate3d
+// - Static height calculation (no height animations)
+// - Reduced layout thrashing
+// - Optimized for mobile performance
+
+import { cn } from '@evolve.ui/theme-system';
+import { animated } from '@react-spring/web';
+import { useDrag } from '@use-gesture/react';
+import {
+    FC,
+    forwardRef,
+    HTMLProps,
+    RefObject,
+    useCallback,
+    useEffect,
+    useImperativeHandle,
+    useMemo,
+    useRef,
+    useState,
+} from 'react';
+
+import type { SpringSetOptions } from './hooks/useSpring';
+import type { defaultSnapProps, Props, RefHandles, ResizeSource, SnapPointProps } from './types';
+
+import { nodeEnv } from '../utils/nodeEnv';
+import { BottomSheetBackdrop, BottomSheetOverlay } from './components';
+import {
+    useAriaHider,
+    useBottomSheetServices,
+    useDragHandler,
+    useFocusTrap,
+    useLayoutEffect,
+    useOptimizedScrollState,
+    useReady,
+    useReducedMotion,
+    useScrollLock,
+    useSnapPoints,
+    useSpring,
+    useSpringInterpolationsTranslate3d,
+} from './hooks';
+import { type BottomSheetActions, useBottomSheetStateMachine } from './state/useBottomSheetStateMachine';
+
+// react-spring 9.7.5's animated.div drops `children` from its props under TS 6 — alias
+// it to a plain div component type (runtime identical), same adaptation as ContentPager.
+type AnimatedDivProps = Omit<HTMLProps<HTMLDivElement>, 'style'> & { style?: object };
+const AnimatedDiv = animated.div as unknown as FC<AnimatedDivProps>;
+
+/**
+ * BottomSheet - GPU-accelerated version using translate3d transforms
+ *
+ * Key features:
+ * - Uses translate3d for positioning instead of height + translateY
+ * - Static height calculation for better performance
+ * - Optimized for mobile device GPU acceleration
+ * - Reduced layout thrashing during animations
+ * - Viewport height limiting with 64px buffer to prevent sheet from exceeding screen bounds
+ * - Hard cap at actual viewport height for all maxHeight props and snap points
+ */
+export const BottomSheet = forwardRef<
+    RefHandles,
+    {
+        initialState: 'OPEN' | 'CLOSED';
+        lastSnapRef: RefObject<number | null>;
+        /**
+         * Preload the sheet measurements and setup when closed for faster opening.
+         * Useful when you know a sheet will be opened soon.
+         */
+        preload?: boolean;
+    } & Props
+>(function BottomSheetInternal(
+    {
+        children,
+        className,
+        defaultSnap: getDefaultSnap = _defaultSnap,
+        disableScroll = false,
+        footer,
+        header,
+        initialFocusRef,
+        initialState,
+        lastSnapRef,
+        maxHeight: controlledMaxHeight,
+        minHeight: controlledMinHeight = 300,
+        onCloseEnd,
+        onDismiss,
+        onSpringCancel,
+        onSpringEnd,
+        onSpringStart,
+        open: _open,
+        preload = false,
+        scrollLocking = true,
+        snapPoints: getSnapPoints = _snapPoints,
+        style,
+        ...props
+    },
+    forwardRef
+) {
+    // Before any animations can start we need to measure a few things
+    const { ready, registerReady } = useReady();
+
+    // Controls the drag handler, used by spring operations that happen outside the render loop in React
+    const canDragRef = useRef(false);
+
+    // Callback refs to avoid breaking the sheet when callbacks change
+    const onCloseEndRef = useRef(onCloseEnd);
+    const onSpringStartRef = useRef(onSpringStart);
+    const onSpringCancelRef = useRef(onSpringCancel);
+    const onSpringEndRef = useRef(onSpringEnd);
+    useEffect(() => {
+        onCloseEndRef.current = onCloseEnd;
+        onSpringStartRef.current = onSpringStart;
+        onSpringCancelRef.current = onSpringCancel;
+        onSpringEndRef.current = onSpringEnd;
+    }, [onCloseEnd, onSpringCancel, onSpringStart, onSpringEnd]);
+
+    // The animation engine
+    const [spring, api] = useSpring();
+
+    // Use Tailwind transitions for fade animation like Drawer/Modal components
+    const [showContent, setShowContent] = useState(_open);
+
+    const containerRef = useRef<HTMLDivElement>(null);
+    const scrollRef = useRef<HTMLDivElement>(null);
+    const contentRef = useRef<HTMLDivElement>(null);
+    const headerRef = useRef<HTMLDivElement>(null);
+    const footerRef = useRef<HTMLDivElement>(null);
+    const overlayRef = useRef<HTMLDivElement | null>(null);
+
+    // Keeps track of the current height, or the height transitioning to
+    const heightRef = useRef(0);
+    const resizeSourceRef = useRef<ResizeSource>('window');
+    const preventScrollingRef = useRef(false);
+
+    // Use optimized scroll state hook for better performance
+    const { isScrollable, isScrolledToBottom } = useOptimizedScrollState(scrollRef, ready);
+
+    const prefersReducedMotion = useReducedMotion();
+
+    // Plugins
+    const scrollLockRef = useScrollLock({
+        enabled: ready && scrollLocking,
+        reserveScrollBarGap: true,
+        targetRef: scrollRef as RefObject<Element>,
+    });
+    const ariaHiderRef = useAriaHider({
+        enabled: ready,
+        targetRef: containerRef as RefObject<Element>,
+    });
+
+    const focusTrapRef = useFocusTrap({
+        enabled: ready && initialFocusRef !== false,
+        fallbackRef: overlayRef as RefObject<HTMLElement>,
+        initialFocusRef: initialFocusRef || undefined,
+        targetRef: containerRef as RefObject<HTMLElement>,
+    });
+
+    const { findSnap, maxHeight, maxSnap, minSnap } = useSnapPoints({
+        contentRef: contentRef as RefObject<Element>,
+        controlledMaxHeight,
+        controlledMinHeight,
+        footerEnabled: Boolean(footer),
+        footerRef: footerRef as RefObject<Element>,
+        getSnapPoints: getSnapPoints as (props: SnapPointProps) => number[],
+        headerEnabled: Boolean(header),
+        headerRef: headerRef as RefObject<Element>,
+        heightRef,
+        lastSnapRef: lastSnapRef as RefObject<number>,
+        ready,
+        registerReady,
+        resizeSourceRef,
+    });
+
+    // Setup refs for full control over when side effects execute
+    const maxHeightRef = useRef(maxHeight);
+    const minSnapRef = useRef(minSnap);
+    const maxSnapRef = useRef(maxSnap);
+    const findSnapRef = useRef(findSnap);
+    const defaultSnapRef = useRef(0);
+
+    // Sync refs with current state
+    useLayoutEffect(() => {
+        maxHeightRef.current = maxHeight;
+        maxSnapRef.current = maxSnap;
+        minSnapRef.current = minSnap;
+        findSnapRef.current = findSnap;
+        defaultSnapRef.current = findSnap(getDefaultSnap);
+    }, [findSnap, getDefaultSnap, maxHeight, maxSnap, minSnap]);
+
+    // Mobile-optimized spring animation with translate3d focus
+    const asyncSet = useCallback(
+        ({ onRest, ...opts }: SpringSetOptions) => {
+            return new Promise<void>((resolve) =>
+                api.start({
+                    ...opts,
+                    onRest: (result: unknown) => {
+                        resolve();
+                        onRest?.(result);
+                    },
+                })
+            );
+        },
+        [api]
+    );
+    // Define services for the state machine using the custom hook
+    const services = useBottomSheetServices({
+        ariaHiderRef,
+        asyncSet,
+        canDragRef,
+        defaultSnapRef,
+        findSnapRef,
+        focusTrapRef,
+        heightRef,
+        lastSnapRef,
+        maxHeightRef,
+        maxSnapRef,
+        minSnapRef,
+        onSpringCancelRef,
+        onSpringEndRef,
+        onSpringStartRef,
+        prefersReducedMotion,
+        resizeSourceRef,
+        scrollLockRef,
+    });
+
+    // Define actions for the state machine
+    const actions = useCallback(
+        (): BottomSheetActions => ({
+            onCloseCancel: () => onSpringCancelRef.current?.({ type: 'CLOSE' }),
+            onCloseEnd: () => {
+                onSpringEndRef.current?.({ type: 'CLOSE' });
+                onCloseEndRef.current?.();
+            },
+            onOpenCancel: () => onSpringCancelRef.current?.({ type: 'OPEN' }),
+            onOpenEnd: () => onSpringEndRef.current?.({ type: 'OPEN' }),
+            onResizeCancel: () =>
+                onSpringCancelRef.current?.({
+                    source: resizeSourceRef.current,
+                    type: 'RESIZE',
+                }),
+            onResizeEnd: () =>
+                onSpringEndRef.current?.({
+                    source: resizeSourceRef.current,
+                    type: 'RESIZE',
+                }),
+            onSnapCancel: (context) =>
+                onSpringCancelRef.current?.({
+                    source: context.snapSource || 'custom',
+                    type: 'SNAP',
+                }),
+            onSnapEnd: (context) =>
+                onSpringEndRef.current?.({
+                    source: context.snapSource || 'custom',
+                    type: 'SNAP',
+                }),
+        }),
+        []
+    );
+
+    // Memoize the initial context to prevent infinite loops
+    const initialContext = useMemo(() => ({ initialState }), [initialState]);
+
+    // Use the Jotai-based state machine
+    const { current, reset, send } = useBottomSheetStateMachine(services(), actions(), initialContext);
+
+    useEffect(() => {
+        if (_open) {
+            send('OPEN');
+        } else {
+            // IMPORTANT: Blur any focused element within the sheet BEFORE deactivating aria-hider
+            // This prevents the warning: "Blocked aria-hidden on an element because its descendant retained focus"
+            // This happens when user clicks a button (e.g., Cancel) which triggers close while button has focus
+            const activeElement = document.activeElement;
+            if (activeElement instanceof HTMLElement && containerRef.current?.contains(activeElement)) {
+                activeElement.blur();
+            }
+            send('CLOSE');
+        }
+    }, [_open, send, current.value]);
+
+    // Control content visibility for Tailwind fade animation
+    useEffect(() => {
+        if (_open) {
+            setShowContent(true);
+        } else {
+            const timeoutId = setTimeout(() => setShowContent(false), 50);
+            return () => clearTimeout(timeoutId);
+        }
+        return undefined;
+    }, [_open]);
+
+    useLayoutEffect(() => {
+        // Adjust the height whenever the snap points are changed due to resize events
+        if (maxHeight || maxSnap || minSnap) {
+            send('RESIZE');
+        }
+    }, [maxHeight, maxSnap, minSnap, send]);
+
+    useEffect(
+        () => () => {
+            // Cleanup effects on unmount
+            try {
+                scrollLockRef.current.deactivate();
+            } catch (e) {
+                if (nodeEnv !== 'production') {
+                    // eslint-disable-next-line no-console
+                    console.error('❌ ScrollLock deactivation error:', e);
+                }
+            }
+
+            try {
+                focusTrapRef.current.deactivate();
+            } catch (e) {
+                if (nodeEnv !== 'production') {
+                    // eslint-disable-next-line no-console
+                    console.error('❌ FocusTrap deactivation error:', e);
+                }
+            }
+
+            try {
+                ariaHiderRef.current.deactivate();
+            } catch (e) {
+                if (nodeEnv !== 'production') {
+                    // eslint-disable-next-line no-console
+                    console.error('❌ AriaHider deactivation error:', e);
+                }
+            }
+
+            try {
+                api.stop();
+            } catch (e) {
+                if (nodeEnv !== 'production') {
+                    // eslint-disable-next-line no-console
+                    console.error('❌ Spring API stop error:', e);
+                }
+            }
+
+            // Reset state machine to ensure clean state on remount
+            try {
+                reset('CLOSED');
+            } catch (e) {
+                if (nodeEnv !== 'production') {
+                    // eslint-disable-next-line no-console
+                    console.error('❌ State machine reset error:', e);
+                }
+            }
+        },
+        [api, ariaHiderRef, focusTrapRef, reset, scrollLockRef]
+    );
+
+    useImperativeHandle(
+        forwardRef,
+        () => ({
+            get height() {
+                return heightRef.current;
+            },
+            snapTo: (numberOrCallback, { source = 'custom', velocity = 1 } = {}) => {
+                // Pass the payload flat: `send` wraps it into the SNAP event itself.
+                // (Upstream nested it under `payload`, double-wrapping the event so the
+                // reducer read undefined values — surfaced when `send` gained real types.)
+                send('SNAP', {
+                    source,
+                    velocity,
+                    y: findSnapRef.current(numberOrCallback, velocity),
+                });
+            },
+        }),
+        [send]
+    );
+
+    // Use the custom drag handler hook
+    const { handleDrag } = useDragHandler({
+        api,
+        canDragRef,
+        maxHeightRef,
+        maxSnapRef,
+        minSnapRef,
+        onDismiss,
+        preventScrollingRef,
+        send,
+        spring,
+    });
+
+    // Memoize drag configuration to prevent recreation
+    const dragConfig = useMemo(
+        () => ({
+            filterTaps: true,
+            rubberband: true,
+            threshold: 5,
+        }),
+        []
+    );
+
+    const bind = useDrag(handleDrag, dragConfig);
+
+    if (nodeEnv === 'development') {
+        if (Number.isNaN(maxSnapRef.current)) {
+            throw new TypeError('maxSnapRef is NaN!!');
+        }
+        if (Number.isNaN(minSnapRef.current)) {
+            throw new TypeError('minSnapRef is NaN!!');
+        }
+    }
+
+    // Use translate3d interpolations for GPU acceleration
+    const interpolations = useSpringInterpolationsTranslate3d({ spring });
+
+    return (
+        <AnimatedDiv
+            {...props}
+            className={cn(
+                // Base positioning and layout
+                'fixed bottom-0 left-0 right-0 z-[10001]',
+                // Touch and interaction optimizations
+                'touch-none select-none',
+                // Transition - faster transition when preloaded
+                preload ? 'transition-opacity duration-150' : 'transition-opacity duration-300',
+                {
+                    'opacity-0': !showContent,
+                    'opacity-100': showContent,
+                },
+                className
+            )}
+            ref={containerRef}
+            style={{
+                // Use translate3d interpolations
+                ...interpolations,
+                ...style,
+                ...(preload && !_open && { pointerEvents: 'none', visibility: 'hidden' }),
+            }}
+        >
+            <BottomSheetBackdrop
+                bind={bind}
+                blocking
+            />
+            {/* Anti-gap filler */}
+            <div
+                className={cn(
+                    'fixed bottom-0 left-0 right-0',
+                    'h-px bg-background-primary',
+                    'origin-bottom',
+                    'scale-y-[var(--rsbs-antigap-scale-y,0)]',
+                    'pointer-events-none',
+                    'will-change-transform'
+                )}
+            />
+            <BottomSheetOverlay
+                bind={bind}
+                contentRef={contentRef}
+                disableScroll={disableScroll}
+                footer={footer}
+                footerRef={footerRef}
+                header={header}
+                headerRef={headerRef}
+                isScrollable={isScrollable}
+                isScrolledToBottom={isScrolledToBottom}
+                onDismiss={onDismiss}
+                overlayRef={overlayRef}
+                scrollRef={scrollRef}
+            >
+                {children}
+            </BottomSheetOverlay>
+        </AnimatedDiv>
+    );
+});
+
+// Default prop values that are callbacks, and it's nice to save some memory and reuse their instances since they're pure
+function _defaultSnap({ lastSnap, snapPoints }: defaultSnapProps) {
+    return lastSnap ?? Math.min(...snapPoints);
+}
+function _snapPoints({ minHeight }: SnapPointProps) {
+    return minHeight;
+}

package/src/BottomSheet/components/BottomSheetBackdrop/BottomSheetBackdrop.tsx

@@ -0,0 +1,47 @@
+import { cn } from '@evolve.ui/theme-system';
+import React from 'react';
+
+import type { DragBind } from '../../types';
+
+/**
+ * Props for the BottomSheetBackdrop component
+ */
+type Props = {
+    /** Drag bind function for backdrop interactions */
+    bind: DragBind;
+    /** Whether the backdrop should be rendered */
+    blocking: boolean;
+};
+
+/**
+ * BottomSheetBackdrop handles the backdrop overlay that appears behind the sheet
+ */
+export const BottomSheetBackdrop = ({ bind, blocking }: Props) => {
+    if (!blocking) {
+        return null;
+    }
+
+    return (
+        <div
+            className={cn(
+                // Positioning - cover entire viewport
+                'fixed inset-0',
+                // Extend beyond safe areas for mobile
+                '-bottom-[60px] -top-[60px]',
+                // Background
+                'bg-background-overlay',
+                // Interaction
+                'cursor-pointer',
+                // Touch optimizations
+                'touch-none select-none',
+                // Opacity (always visible, parent controls overall opacity)
+                'opacity-100'
+            )}
+            // This component needs to be placed outside bottom-sheet, as bottom-sheet uses transform and thus creates a new context
+            // that clips this element to the container, not allowing it to cover the full page.
+            data-testid="rsbs-backdrop"
+            key="backdrop"
+            {...bind({ closeOnTap: true })}
+        />
+    );
+};

package/src/BottomSheet/components/BottomSheetContentArea/BottomSheetContentArea.tsx

@@ -0,0 +1,92 @@
+import { cn } from '@evolve.ui/theme-system';
+import { memo, ReactNode, RefObject, useEffect, useLayoutEffect, useState } from 'react';
+
+/**
+ * Props for the BottomSheetContentArea component
+ */
+type Props = {
+    /** The main content to display */
+    children: ReactNode;
+    /** Reference to the content container */
+    contentRef: RefObject<HTMLDivElement | null>;
+    /** Whether to disable the BottomSheet's own scrolling (useful when children handle their own scrolling) */
+    disableScroll?: boolean;
+    /** Reference to the scroll container */
+    scrollRef: RefObject<HTMLDivElement | null>;
+};
+
+/**
+ * BottomSheetContentArea handles the scrollable content area of the sheet
+ * Memoized to prevent unnecessary re-renders when parent state changes
+ */
+export const BottomSheetContentArea = memo<Props>(({ children, contentRef, disableScroll = false, scrollRef }) => {
+    // Delay disableScroll to allow initial measurement
+    const [isDisableScrollActive, setIsDisableScrollActive] = useState(false);
+
+    useEffect(() => {
+        if (disableScroll) {
+            // Delay enabling disableScroll until after opening animation completes
+            const timer = setTimeout(() => {
+                setIsDisableScrollActive(true);
+            }, 200); // Match typical BottomSheet opening animation duration
+
+            return () => clearTimeout(timer);
+        }
+        setIsDisableScrollActive(false);
+        return undefined;
+    }, [disableScroll]);
+
+    useLayoutEffect(() => {
+        if (!scrollRef.current) {
+            return;
+        }
+
+        // Reset scroll position immediately
+        scrollRef.current.scrollTop = 0;
+
+        // Sometimes you need a short delay if layout/paint hasn't happened yet
+        const timer = setTimeout(() => {
+            if (scrollRef.current) {
+                scrollRef.current.scrollTop = 0;
+            }
+        }, 50);
+
+        return () => clearTimeout(timer);
+    }, [scrollRef]);
+
+    return (
+        <div
+            className={cn(
+                // Layout - flexible scrollable area
+                'min-h-0 flex-shrink flex-grow',
+                // When disableScroll is active (after delay), make this a flex container for children to handle their own scrolling
+                {
+                    'flex flex-col overflow-hidden': isDisableScrollActive,
+                    'overflow-auto overscroll-contain': !isDisableScrollActive,
+                },
+                // Focus
+                'focus:outline-none'
+            )}
+            data-testid="rsbs-scroll"
+            key="scroll"
+            ref={scrollRef}
+        >
+            <div
+                className={cn(
+                    // Content container
+                    {
+                        'flex min-h-0 flex-grow flex-col': isDisableScrollActive, // Allow children to handle their own scrolling
+                        'overflow-hidden': !isDisableScrollActive, // Ensures margin collapse works correctly for height measurements
+                    }
+                )}
+                data-testid="rsbs-content"
+                ref={contentRef}
+            >
+                {children}
+            </div>
+        </div>
+    );
+});
+
+// Add display name for better debugging
+BottomSheetContentArea.displayName = 'BottomSheetContentArea';