@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/BottomSheet/hooks/useScrollLock.tsx

@@ -0,0 +1,143 @@
+import { RefObject, useDebugValue, useEffect, useRef } from 'react';
+
+/**
+ * Lightweight scroll lock implementation without external dependencies
+ * Handle scroll locking to ensure a good dragging experience on Android and iOS.
+ *
+ * On iOS the following may happen if scroll isn't locked:
+ * - When dragging the sheet the background gets dragged at the same time.
+ * - When dragging the page scroll is also affected, causing the drag to feel buggy and "slow".
+ *
+ * On Android it causes the chrome toolbar to pop down as you drag down, and hide as you drag up.
+ * When it's in between two toolbar states it causes the framerate to drop way below 60fps on
+ * the bottom sheet drag interaction.
+ */
+export const useScrollLock = ({
+    enabled,
+    reserveScrollBarGap,
+    targetRef,
+}: {
+    enabled: boolean;
+    reserveScrollBarGap: boolean;
+    targetRef: RefObject<Element>;
+}) => {
+    // eslint-disable-next-line func-call-spacing
+    const ref = useRef<{ activate: () => void; deactivate: () => void }>({
+        activate: () => {
+            throw new TypeError('Tried to activate scroll lock too early');
+        },
+        deactivate: () => {},
+    });
+    const originalStyles = useRef<{
+        overflow: string;
+        paddingRight: string;
+        position: string;
+    } | null>(null);
+
+    useDebugValue(enabled ? 'Enabled' : 'Disabled');
+
+    useEffect(() => {
+        if (!enabled) {
+            ref.current.deactivate();
+            ref.current = { activate: () => {}, deactivate: () => {} };
+            return;
+        }
+
+        let active = false;
+
+        const getScrollbarWidth = (): number => {
+            const scrollDiv = document.createElement('div');
+            scrollDiv.style.cssText =
+                'width: 100px; height: 100px; overflow: scroll; position: absolute; top: -9999px;';
+            document.body.appendChild(scrollDiv);
+            const scrollbarWidth = scrollDiv.offsetWidth - scrollDiv.clientWidth;
+            document.body.removeChild(scrollDiv);
+            return scrollbarWidth;
+        };
+
+        const preventTouchMove = (e: TouchEvent) => {
+            const target = e.target as Element;
+            // Allow touch move on elements marked as scrollable or within the target ref
+            if (
+                target.closest('[data-body-scroll-lock-ignore]') ||
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition, @typescript-eslint/prefer-optional-chain
+                (targetRef.current && targetRef.current.contains(target))
+            ) {
+                return;
+            }
+            e.preventDefault();
+        };
+
+        ref.current = {
+            activate: () => {
+                if (active) {
+                    return;
+                }
+                active = true;
+
+                const body = document.body;
+                const html = document.documentElement;
+
+                // Store original styles
+                originalStyles.current = {
+                    overflow: body.style.overflow,
+                    paddingRight: body.style.paddingRight,
+                    position: body.style.position,
+                };
+
+                // Calculate scrollbar width if we need to reserve space
+                let scrollbarWidth = 0;
+                if (reserveScrollBarGap && window.innerWidth > html.clientWidth) {
+                    scrollbarWidth = getScrollbarWidth();
+                }
+
+                // Apply scroll lock styles
+                body.style.overflow = 'hidden';
+                if (scrollbarWidth > 0) {
+                    body.style.paddingRight = `${scrollbarWidth}px`;
+                }
+
+                // Prevent touch scrolling on mobile
+                document.addEventListener('touchmove', preventTouchMove, { passive: false });
+
+                // Prevent scroll restoration on iOS
+                if (typeof window !== 'undefined' && 'scrollY' in window) {
+                    const scrollY = window.scrollY;
+                    body.style.position = 'fixed';
+                    body.style.top = `-${scrollY}px`;
+                    body.style.width = '100%';
+                }
+            },
+            deactivate: () => {
+                if (!active) {
+                    return;
+                }
+                active = false;
+
+                const body = document.body;
+
+                // Remove touch move listener
+                document.removeEventListener('touchmove', preventTouchMove);
+
+                // Restore original styles
+                if (originalStyles.current) {
+                    body.style.overflow = originalStyles.current.overflow;
+                    body.style.paddingRight = originalStyles.current.paddingRight;
+
+                    // Restore scroll position on iOS
+                    if (body.style.position === 'fixed') {
+                        const scrollY = parseInt(body.style.top || '0', 10) * -1;
+                        body.style.position = originalStyles.current.position;
+                        body.style.top = '';
+                        body.style.width = '';
+                        window.scrollTo(0, scrollY);
+                    }
+                }
+
+                originalStyles.current = null;
+            },
+        };
+    }, [enabled, targetRef, reserveScrollBarGap]);
+
+    return ref;
+};

package/src/BottomSheet/hooks/useSnapPoints.tsx

@@ -0,0 +1,355 @@
+import { ResizeObserver, ResizeObserverEntry } from '@juggle/resize-observer';
+import { ResizeObserverOptions } from '@juggle/resize-observer/lib/ResizeObserverOptions';
+import { RefObject, useCallback, useDebugValue, useEffect, useMemo, useRef, useState } from 'react';
+
+import type { defaultSnapProps, ResizeSource, snapPoints } from '../types';
+
+import { processSnapPoints, roundAndCheckForNaN } from '../utils';
+import { useLayoutEffect } from './useLayoutEffect';
+import { useReady } from './useReady';
+
+export const useSnapPoints = ({
+    contentRef,
+    controlledMaxHeight,
+    controlledMinHeight,
+    footerEnabled,
+    footerRef,
+    getSnapPoints,
+    headerEnabled,
+    headerRef,
+    heightRef,
+    lastSnapRef,
+    ready,
+    registerReady,
+    resizeSourceRef,
+}: {
+    contentRef: RefObject<Element>;
+    controlledMaxHeight?: number;
+    controlledMinHeight?: number;
+    footerEnabled: boolean;
+    footerRef: RefObject<Element>;
+    getSnapPoints: snapPoints;
+    headerEnabled: boolean;
+    headerRef: RefObject<Element>;
+    heightRef: RefObject<number>;
+    lastSnapRef: RefObject<number>;
+    ready: boolean;
+    registerReady: ReturnType<typeof useReady>['registerReady'];
+    resizeSourceRef: RefObject<ResizeSource>;
+}) => {
+    const { footerHeight, headerHeight, maxHeight, minHeight } = useDimensions({
+        contentRef: contentRef,
+        controlledMaxHeight,
+        controlledMinHeight,
+        footerEnabled,
+        footerRef,
+        headerEnabled,
+        headerRef,
+        registerReady,
+        resizeSourceRef,
+    });
+
+    const { maxSnap, minSnap, snapPoints } = processSnapPoints(
+        ready
+            ? getSnapPoints({
+                  footerHeight,
+                  headerHeight,
+                  height: heightRef.current,
+                  maxHeight,
+                  minHeight,
+              })
+            : [0],
+        maxHeight
+    );
+
+    const findSnap = useCallback(
+        (numberOrCallback: number | ((state: defaultSnapProps) => number), velocity?: number) => {
+            let unsafeSearch: number;
+            if (typeof numberOrCallback === 'function') {
+                unsafeSearch = numberOrCallback({
+                    footerHeight,
+                    headerHeight,
+                    height: heightRef.current,
+                    lastSnap: lastSnapRef.current,
+                    maxHeight,
+                    minHeight,
+                    snapPoints,
+                });
+            } else {
+                unsafeSearch = numberOrCallback;
+            }
+            const querySnap = roundAndCheckForNaN(unsafeSearch);
+
+            // If velocity is provided and significant, consider direction for smarter snapping
+            // But be much more conservative to avoid aggressive "pushing" behavior
+            if (velocity && Math.abs(velocity) > 0.3) {
+                // Higher threshold for velocity-based snapping
+                const currentSnap = heightRef.current || 0;
+                const direction = velocity > 0 ? 1 : -1; // positive velocity = upward motion
+
+                // Find snaps in the direction of movement
+                const snapsInDirection = snapPoints.filter((snap) =>
+                    direction > 0 ? snap > currentSnap : snap < currentSnap
+                );
+
+                if (snapsInDirection.length > 0) {
+                    // If moving with significant velocity, prefer the next snap in that direction
+                    const targetSnap = direction > 0 ? Math.min(...snapsInDirection) : Math.max(...snapsInDirection);
+
+                    // But only if the query position is reasonably close to that direction
+                    const distanceToTarget = Math.abs(targetSnap - querySnap);
+                    const distanceToClosest = Math.abs(
+                        snapPoints.reduce(
+                            (prev, curr) => (Math.abs(curr - querySnap) < Math.abs(prev - querySnap) ? curr : prev),
+                            minSnap
+                        ) - querySnap
+                    );
+
+                    // Be much more conservative - only use velocity-based snap if it's very close
+                    // and the velocity is really significant
+                    if (distanceToTarget < distanceToClosest * 1.2 && Math.abs(velocity) > 0.5) {
+                        return targetSnap;
+                    }
+                }
+            }
+
+            // Fallback to closest snap point
+            return snapPoints.reduce(
+                (prev, curr) => (Math.abs(curr - querySnap) < Math.abs(prev - querySnap) ? curr : prev),
+                minSnap
+            );
+        },
+        [snapPoints, minSnap, footerHeight, headerHeight, heightRef, lastSnapRef, maxHeight, minHeight]
+    );
+
+    useDebugValue(`minSnap: ${minSnap}, maxSnap:${maxSnap}`);
+
+    return { findSnap, maxHeight, maxSnap, minSnap };
+};
+
+function useDimensions({
+    contentRef,
+    controlledMaxHeight,
+    controlledMinHeight = 300,
+    footerEnabled,
+    footerRef,
+    headerEnabled,
+    headerRef,
+    registerReady,
+    resizeSourceRef,
+}: {
+    contentRef: RefObject<Element>;
+    controlledMaxHeight?: number;
+    controlledMinHeight?: number;
+    footerEnabled: boolean;
+    footerRef: RefObject<Element>;
+    headerEnabled: boolean;
+    headerRef: RefObject<Element>;
+    registerReady: ReturnType<typeof useReady>['registerReady'];
+    resizeSourceRef: RefObject<ResizeSource>;
+}) {
+    const setReady = useMemo(() => registerReady('contentHeight'), [registerReady]);
+    const maxHeight = useMaxHeight(controlledMaxHeight, registerReady, resizeSourceRef);
+
+    // Note: Future optimization could forward props instead of checking refs for enabled state
+    const headerHeight = useElementSizeObserver(headerRef, {
+        enabled: headerEnabled,
+        label: 'headerHeight',
+        resizeSourceRef,
+    });
+    const contentHeight = useElementSizeObserver(contentRef, {
+        enabled: true,
+        label: 'contentHeight',
+        resizeSourceRef,
+    });
+    const footerHeight = useElementSizeObserver(footerRef, {
+        enabled: footerEnabled,
+        label: 'footerHeight',
+        resizeSourceRef,
+    });
+
+    // Use the larger of calculated minHeight or controlled minHeight
+    // Ensure the calculated minHeight never exceeds maxHeight (which now includes viewport buffer)
+    const calculatedMinHeight =
+        Math.min(maxHeight - headerHeight - footerHeight, contentHeight) + headerHeight + footerHeight;
+    const minHeight = Math.min(Math.max(calculatedMinHeight, controlledMinHeight), maxHeight);
+
+    useDebugValue(`minHeight: ${minHeight}`);
+
+    const ready = contentHeight > 0;
+    useEffect(() => {
+        if (ready) {
+            setReady();
+        }
+    }, [ready, setReady]);
+
+    return {
+        footerHeight,
+        headerHeight,
+        maxHeight,
+        minHeight,
+    };
+}
+
+const observerOptions: ResizeObserverOptions = {
+    // And the user hides or shows the Safari browser toolbar
+    box: 'border-box',
+};
+/**
+ * Hook for determining the size of an element using the Resize Observer API.
+ *
+ * @param ref - A React ref to an element
+ */
+function useElementSizeObserver(
+    ref: RefObject<Element>,
+    {
+        enabled,
+        label,
+        resizeSourceRef,
+    }: {
+        enabled: boolean;
+        label: string;
+        resizeSourceRef: RefObject<ResizeSource>;
+    }
+): number {
+    const [size, setSize] = useState(0);
+    const rafRef = useRef<number>(0);
+    const lastSizeRef = useRef<number>(0);
+
+    useDebugValue(`${label}: ${size}`);
+
+    const handleResize = useCallback(
+        (entries: ResizeObserverEntry[]) => {
+            // Cancel any pending RAF to throttle updates
+            if (rafRef.current) {
+                cancelAnimationFrame(rafRef.current);
+            }
+
+            rafRef.current = requestAnimationFrame(() => {
+                // we only observe one element, so accessing the first entry here is fine
+                const entry = entries[0];
+                const newSize = entry.borderBoxSize[0]?.blockSize || entry.contentRect.height;
+
+                // Only update if size actually changed by a meaningful amount (1px threshold)
+                if (Math.abs(newSize - lastSizeRef.current) >= 1) {
+                    lastSizeRef.current = newSize;
+                    setSize(newSize);
+                    resizeSourceRef.current = 'element';
+                }
+
+                rafRef.current = 0;
+            });
+        },
+        [resizeSourceRef]
+    );
+
+    useLayoutEffect(() => {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!ref.current || !enabled) {
+            return;
+        }
+
+        const element = ref.current;
+        const resizeObserver = new ResizeObserver(handleResize);
+
+        // Get initial size synchronously for faster startup
+        const initialRect = element.getBoundingClientRect();
+        if (initialRect.height > 0 && lastSizeRef.current === 0) {
+            lastSizeRef.current = initialRect.height;
+            setSize(initialRect.height);
+        }
+
+        resizeObserver.observe(element, observerOptions);
+
+        return () => {
+            resizeObserver.disconnect();
+            if (rafRef.current) {
+                cancelAnimationFrame(rafRef.current);
+            }
+        };
+    }, [ref, handleResize, enabled]);
+
+    return enabled ? size : 0;
+}
+
+// Blazingly keep track of the current viewport height without blocking the thread, keeping that sweet 60fps on smartphones
+function useMaxHeight(
+    controlledMaxHeight: number | undefined,
+    registerReady: ReturnType<typeof useReady>['registerReady'],
+    resizeSourceRef: RefObject<ResizeSource>
+) {
+    const setReady = useMemo(() => registerReady('maxHeight'), [registerReady]);
+
+    // Helper function to calculate safe viewport height with buffer
+    const getSafeViewportHeight = useCallback((viewportHeight: number) => {
+        // Apply a buffer to ensure bottom sheet never exceeds viewport height
+        // Use 64px buffer (approximately the height of mobile browser chrome/status bar)
+        const VIEWPORT_BUFFER = 64;
+        return Math.max(viewportHeight - VIEWPORT_BUFFER, 300); // Minimum 300px height
+    }, []);
+
+    const [maxHeight, setMaxHeight] = useState(() => {
+        const viewportHeight = typeof window !== 'undefined' ? window.innerHeight : 0;
+
+        if (controlledMaxHeight) {
+            const controlledHeight = roundAndCheckForNaN(controlledMaxHeight);
+            // Always cap controlled height at actual viewport height
+            return Math.min(controlledHeight, viewportHeight);
+        }
+
+        return getSafeViewportHeight(viewportHeight);
+    });
+
+    const ready = maxHeight > 0;
+    const raf = useRef(0);
+
+    useDebugValue(controlledMaxHeight ? 'controlled' : 'auto');
+
+    useEffect(() => {
+        if (ready) {
+            setReady();
+        }
+    }, [ready, setReady]);
+
+    useLayoutEffect(() => {
+        // Handle controlled max height with viewport capping
+        if (controlledMaxHeight) {
+            const controlledHeight = roundAndCheckForNaN(controlledMaxHeight);
+            // Always cap controlled height at actual viewport height
+            const cappedHeight = Math.min(controlledHeight, window.innerHeight);
+            setMaxHeight(cappedHeight);
+            resizeSourceRef.current = 'maxheightprop';
+
+            return;
+        }
+
+        const handleResize = () => {
+            if (raf.current) {
+                // bail to throttle the amount of resize changes
+                return;
+            }
+
+            // throttle state changes using rAF
+            raf.current = requestAnimationFrame(() => {
+                const safeHeight = getSafeViewportHeight(window.innerHeight);
+                setMaxHeight(safeHeight);
+                resizeSourceRef.current = 'window';
+
+                raf.current = 0;
+            });
+        };
+
+        window.addEventListener('resize', handleResize);
+        const initialSafeHeight = getSafeViewportHeight(window.innerHeight);
+        setMaxHeight(initialSafeHeight);
+        resizeSourceRef.current = 'window';
+        setReady();
+
+        return () => {
+            window.removeEventListener('resize', handleResize);
+            cancelAnimationFrame(raf.current);
+        };
+    }, [controlledMaxHeight, setReady, resizeSourceRef, getSafeViewportHeight]);
+
+    return maxHeight;
+}

package/src/BottomSheet/hooks/useSpring.tsx

@@ -0,0 +1,47 @@
+import { useSpring as useReactSpring } from '@react-spring/web';
+
+// Behold, the engine of it all!
+// Put in this file befause it makes it easier to type and I'm lazy! :D
+
+export const useSpring = () => {
+    const [spring, api] = useReactSpring(() => ({
+        config: {
+            // Increase friction for less oscillation
+            friction: 32,
+            // Prevent spring from overshooting its target, eliminating final bounce
+            overshootClamping: true,
+            // End animation sooner when displacement is below this threshold (increased from 0.01)
+            restDisplacementThreshold: 0.1,
+            // End animation sooner when speed drops below this threshold (increased from 2)
+            restSpeedThreshold: 10,
+            // Increase tension slightly for snappier animations
+            tension: 280,
+        },
+        maxHeight: 0,
+        maxSnap: 0,
+        minSnap: 0,
+        y: 0,
+    }));
+
+    return [spring, api] as const;
+};
+
+export type Spring = ReturnType<typeof useSpring>[0];
+export type SpringAPI = ReturnType<typeof useSpring>[1];
+
+/** The animated values the sheet's spring tracks. */
+type SpringTargetValues = {
+    maxHeight?: number;
+    maxSnap?: number;
+    minSnap?: number;
+    y?: number;
+};
+
+/** The subset of spring props the sheet animates via `api.start` / `asyncSet`. */
+export type SpringSetOptions = SpringTargetValues & {
+    config?: { velocity?: number };
+    from?: SpringTargetValues;
+    immediate?: boolean;
+    onRest?: (result?: unknown) => void;
+    to?: SpringTargetValues;
+};

package/src/BottomSheet/hooks/useSpringInterpolationsTranslate3d.tsx

@@ -0,0 +1,101 @@
+import { to } from '@react-spring/web';
+import { CSSProperties, useMemo } from 'react';
+
+import type { Spring } from './useSpring';
+
+/**
+ * `CSSProperties` widened to admit the sheet's `--rsbs-*` custom properties, whose
+ * values are react-spring interpolations rather than plain strings.
+ */
+type SpringInterpolationStyles = CSSProperties & Record<`--rsbs-${string}`, unknown>;
+
+/**
+ * Experimental translate3d-based interpolations for GPU-accelerated bottom sheet animations.
+ * This approach uses a static height and translates the entire sheet vertically using translate3d,
+ * which leverages GPU acceleration for better performance on mobile devices.
+ */
+export const useSpringInterpolationsTranslate3d = ({ spring }: { spring: Spring }): SpringInterpolationStyles => {
+    // Memoize interpolation functions to prevent recreation on every render
+    const interpolations = useMemo(() => {
+        // Border radius animation - same as original
+        const interpolateBorderRadius = to([spring.y, spring.maxHeight], (y, maxHeight) => {
+            const clamped = Math.max(0, Math.min(16, maxHeight - y));
+            return `${Math.round(clamped)}px`;
+        });
+
+        /**
+         * EXPERIMENTAL: Static height calculation
+         * Instead of animating height, we calculate the maximum height once and keep it static.
+         * This avoids expensive height recalculations during animation.
+         */
+        const interpolateStaticHeight = to([spring.maxSnap], (maxSnap) => {
+            return `${Math.round(maxSnap)}px`;
+        });
+
+        /**
+         * EXPERIMENTAL: translate3d Y positioning
+         * This is the core of the GPU acceleration approach.
+         * We translate the entire bottom sheet vertically using translate3d.
+         *
+         * Logic based on spring system expectations:
+         * - When closed (y = 0): translate3d(0, maxSnap, 0) - hidden below viewport
+         * - When open (y = current snap): translate3d(0, 0, 0) - visible at normal position
+         * - During drag: interpolate between positions based on current y value
+         */
+        const interpolateTranslate3d = to([spring.y, spring.maxSnap], (y, maxSnap) => {
+            // The spring system uses:
+            // y = 0 for closed state (hidden)
+            // y = snap value for open state (visible)
+
+            // Fallback for when maxSnap isn't ready yet
+            const safeMaxSnap = maxSnap || (typeof window !== 'undefined' ? window.innerHeight : 800);
+
+            // When y = 0 (closed): we want translate down by maxSnap (hide sheet)
+            // When y = snap (open): we want translate3d(0, 0, 0) (show sheet)
+
+            if (y === 0) {
+                // Closed state - translate down by full height to hide
+                return `translate3d(0, ${Math.round(safeMaxSnap)}px, 0)`;
+            }
+
+            // Open state - calculate how much to show based on y value
+            // y represents the desired height, so we translate up to show that much
+            const offset = Math.max(0, safeMaxSnap - y);
+            return `translate3d(0, ${Math.round(offset)}px, 0)`;
+        });
+
+        // Anti-gap filler - same as original
+        const interpolateFiller = to([spring.y, spring.maxSnap], (y, maxSnap) => {
+            return Math.max(0, Math.ceil(y - maxSnap));
+        });
+
+        // Content and backdrop opacity - simplified to always 1 for performance
+        const interpolateContentOpacity = to([spring.y], () => 1);
+        const interpolateBackdrop = to([spring.y], () => 1);
+
+        return {
+            interpolateBackdrop,
+            interpolateBorderRadius,
+            interpolateContentOpacity,
+            interpolateFiller,
+            interpolateStaticHeight,
+            interpolateTranslate3d,
+        };
+    }, [spring.y, spring.maxSnap, spring.maxHeight]);
+
+    // Return CSS properties optimized for GPU acceleration
+    return {
+        // Content fade-in effect
+        '--rsbs-content-opacity': interpolations.interpolateContentOpacity,
+        // Backdrop fade-in
+        '--rsbs-backdrop-opacity': interpolations.interpolateBackdrop,
+        // Anti-gap scaling
+        '--rsbs-antigap-scale-y': interpolations.interpolateFiller,
+        // EXPERIMENTAL: Static height instead of animated height
+        '--rsbs-overlay-h-static': interpolations.interpolateStaticHeight,
+        // EXPERIMENTAL: translate3d for GPU acceleration
+        '--rsbs-overlay-translate3d': interpolations.interpolateTranslate3d,
+        // Border radius animation
+        '--rsbs-overlay-rounded': interpolations.interpolateBorderRadius,
+    };
+};