@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/BottomSheet/hooks/useDragHandler.tsx

@@ -0,0 +1,282 @@
+import { rubberbandIfOutOfBounds } from '@use-gesture/react';
+import { RefObject, useCallback, useEffect, useRef } from 'react';
+
+import type { BottomSheetEvent, SnapPayload } from '../state/atoms';
+import type { Spring, SpringAPI } from './useSpring';
+
+/**
+ * The subset of use-gesture's drag state the handler reads.
+ * Structurally compatible with `FullGestureState<'drag'>`, so the handler can be
+ * passed straight to `useDrag` without widening any parameter to `any`.
+ */
+export type DragState = {
+    args?: { closeOnTap?: boolean }[];
+    cancel: () => void;
+    direction?: [number, number];
+    down?: boolean;
+    first?: boolean;
+    last?: boolean;
+    memo?: number;
+    movement?: [number, number];
+    tap?: boolean;
+    velocity?: [number, number];
+};
+
+/**
+ * Props for the drag handler hook
+ */
+type UseDragHandlerProps = {
+    /** Spring API object for controlling animations */
+    api: SpringAPI;
+    /** Reference to track if dragging is allowed */
+    canDragRef: RefObject<boolean>;
+    /** Reference to the current max height value */
+    maxHeightRef: RefObject<number>;
+    /** Reference to the current max snap value */
+    maxSnapRef: RefObject<number>;
+    /** Reference to the current min snap value */
+    minSnapRef: RefObject<number>;
+    /** Dismiss handler function */
+    onDismiss?: () => void;
+    /** Reference to track if scrolling should be prevented */
+    preventScrollingRef: RefObject<boolean>;
+    /** Function to send events to the state machine */
+    send: (event: BottomSheetEvent['type'], payload?: SnapPayload) => void;
+    /** Spring object with current values */
+    spring: Spring;
+};
+
+/**
+ * Custom hook to handle drag interactions for the bottom sheet
+ */
+export const useDragHandler = ({
+    api,
+    canDragRef,
+    maxHeightRef,
+    maxSnapRef,
+    minSnapRef,
+    onDismiss,
+    preventScrollingRef,
+    send,
+    spring,
+}: UseDragHandlerProps) => {
+    // Create stable refs for the functions to avoid recreating the drag handler
+    const sendRef = useRef(send);
+    const apiRef = useRef(api);
+    const onDismissRef = useRef(onDismiss);
+    const springRef = useRef(spring);
+
+    // Performance optimization: Throttle drag updates using RAF
+    const rafRef = useRef<number>(0);
+    const lastUpdateRef = useRef<number>(0);
+
+    // DEBUGGING: Track active timers and RAF calls
+    const activeTimersRef = useRef<Set<ReturnType<typeof setTimeout>>>(new Set());
+    const activeRAFsRef = useRef<Set<number>>(new Set());
+
+    // Cleanup function to clear all pending timers and RAF calls
+    const cleanupPendingCalls = useCallback(() => {
+        // Clear all pending RAF calls
+        activeRAFsRef.current.forEach((id) => {
+            cancelAnimationFrame(id);
+        });
+        activeRAFsRef.current.clear();
+
+        // Clear all pending timers
+        activeTimersRef.current.forEach((id) => {
+            clearTimeout(id);
+        });
+        activeTimersRef.current.clear();
+
+        // Clear the main RAF ref
+        if (rafRef.current) {
+            cancelAnimationFrame(rafRef.current);
+            rafRef.current = 0;
+        }
+    }, []);
+
+    // Cleanup on unmount - force cleanup of all pending operations
+    useEffect(() => {
+        return () => {
+            cleanupPendingCalls();
+        };
+    }, [cleanupPendingCalls]);
+
+    // Update refs when functions change
+    sendRef.current = send;
+    apiRef.current = api;
+    onDismissRef.current = onDismiss;
+    springRef.current = spring;
+
+    const handleDrag = useCallback(
+        (state: DragState) => {
+            // Clean up any pending timers/RAF at the start of each drag operation
+            if (state?.first) {
+                cleanupPendingCalls();
+            }
+
+            // Optimize: Avoid destructuring and use direct property access to reduce object creation
+            const args = state?.args || [];
+            const cancel = state?.cancel;
+            const direction = state?.direction?.[1] || 0; // Only need Y direction
+            const down = state?.down;
+            const first = state?.first;
+            const last = state?.last;
+            const memo = state?.memo ?? (springRef.current.y.get() as number);
+            const movement = state?.movement || [0, 0];
+            const tap = state?.tap;
+            const velocity = state?.velocity || [0, 0];
+
+            // Extract closeOnTap from args if available, default to false
+            const closeOnTap = args[0]?.closeOnTap || false;
+            const _my = movement[1];
+            const velocityY = velocity[1]; // Extract y-component of velocity
+            const my = _my * -1;
+
+            // Cancel the drag operation if the canDrag state changed
+            if (!canDragRef.current) {
+                cancel();
+                return memo;
+            }
+
+            if (onDismissRef.current && closeOnTap && tap) {
+                cancel();
+                // Runs onDismiss in a timeout to avoid tap events on the backdrop from triggering click events on elements underneath
+                const timerId = setTimeout(() => {
+                    activeTimersRef.current.delete(timerId);
+                    onDismissRef.current?.();
+                }, 0);
+                activeTimersRef.current.add(timerId);
+                return memo;
+            }
+
+            // Filter out taps
+            if (tap) {
+                return memo;
+            }
+
+            // Note: Content dragging has been removed - only header/handle area can drag the sheet
+
+            const rawY = memo + my;
+            // More natural velocity prediction with proper deceleration
+            // Use a smaller multiplier and consider the velocity direction more carefully
+            const velocityFactor = Math.min(Math.abs(velocityY), 2); // Cap velocity influence
+            const predictedDistance = my * velocityFactor * 0.3; // Much gentler prediction
+            // Allow going below minSnap for close detection, but clamp for normal snapping
+            const unclamped = rawY + predictedDistance;
+            const predictedY = onDismissRef.current
+                ? Math.min(maxSnapRef.current, unclamped) // Allow below minSnap if dismissible
+                : Math.max(minSnapRef.current, Math.min(maxSnapRef.current, unclamped)); // Normal clamping
+
+            if (!down && onDismissRef.current && direction > 0 && rawY + predictedDistance < minSnapRef.current / 2) {
+                cancel();
+                onDismissRef.current();
+                return memo;
+            }
+
+            const newY = down
+                ? // Handle rubberband when min and max snap points are equal (single snap point)
+                  !onDismissRef.current && minSnapRef.current === maxSnapRef.current
+                    ? // For single snap point, create symmetric rubberband effect
+                      rubberbandIfOutOfBounds(
+                          rawY,
+                          minSnapRef.current * 0.5, // Allow some downward stretch
+                          minSnapRef.current * 1.5, // Allow some upward stretch
+                          0.55
+                      )
+                    : rubberbandIfOutOfBounds(
+                          rawY,
+                          onDismissRef.current ? 0 : minSnapRef.current,
+                          maxSnapRef.current,
+                          0.55
+                      )
+                : predictedY;
+
+            // Since content dragging is disabled, we don't need to prevent scrolling
+            preventScrollingRef.current = false;
+
+            if (first) {
+                sendRef.current('DRAG');
+            }
+
+            if (last) {
+                // Add small delay to prevent rapid state changes
+                const timerId1 = setTimeout(() => {
+                    activeTimersRef.current.delete(timerId1);
+                    // Check if should close instead of snap
+                    // Use unclamped position for close detection
+                    const closePosition = rawY + my * velocityFactor * 0.3;
+                    const shouldClose =
+                        onDismissRef.current &&
+                        // Close if dragged significantly below minSnap
+                        (closePosition < minSnapRef.current * 0.75 ||
+                            // Close if moving downward with significant velocity
+                            (velocityY < -0.5 && closePosition < minSnapRef.current));
+
+                    if (shouldClose) {
+                        // Call onDismiss directly like the backdrop click does
+                        // This triggers the same close animation as clicking the backdrop
+                        cancel();
+                        const timerId2 = setTimeout(() => {
+                            activeTimersRef.current.delete(timerId2);
+                            onDismissRef.current?.();
+                        }, 0);
+                        activeTimersRef.current.add(timerId2);
+                    } else {
+                        sendRef.current('SNAP', {
+                            source: 'dragging',
+                            velocity: Math.abs(velocityY) > 0.01 ? Math.abs(velocityY) : 0.5,
+                            y: newY,
+                        });
+                    }
+                }, 0);
+                activeTimersRef.current.add(timerId1);
+
+                return memo;
+            }
+
+            // Performance optimization: Throttle spring updates to ~60fps during dragging
+            const now = performance.now();
+            if (now - lastUpdateRef.current < 16) {
+                // ~60fps throttling
+                // Cancel any pending RAF and schedule new one
+                if (rafRef.current) {
+                    activeRAFsRef.current.delete(rafRef.current);
+                    cancelAnimationFrame(rafRef.current);
+                }
+
+                rafRef.current = requestAnimationFrame(() => {
+                    activeRAFsRef.current.delete(rafRef.current);
+                    apiRef.current.start({
+                        config: { velocity: velocityY },
+                        immediate: true,
+                        maxHeight: maxHeightRef.current,
+                        maxSnap: maxSnapRef.current,
+                        minSnap: minSnapRef.current,
+                        y: newY,
+                    });
+                    lastUpdateRef.current = performance.now();
+                    rafRef.current = 0;
+                });
+                activeRAFsRef.current.add(rafRef.current);
+            } else {
+                // Update immediately if enough time has passed
+                apiRef.current.start({
+                    config: { velocity: velocityY },
+                    immediate: true,
+                    maxHeight: maxHeightRef.current,
+                    maxSnap: maxSnapRef.current,
+                    minSnap: minSnapRef.current,
+                    y: newY,
+                });
+                lastUpdateRef.current = now;
+            }
+
+            return memo;
+        },
+        [canDragRef, preventScrollingRef, minSnapRef, maxSnapRef, maxHeightRef, cleanupPendingCalls]
+        // Removed spring.y from deps since we access it via spring.y.get() inside the callback
+    );
+
+    return { handleDrag };
+};

package/src/BottomSheet/hooks/useFocusTrap.tsx

@@ -0,0 +1,113 @@
+import { RefObject, useDebugValue, useEffect, useRef } from 'react';
+
+/**
+ * Lightweight focus trap implementation without external dependencies
+ * Provides basic focus management for modal/sheet components
+ */
+export const useFocusTrap = ({
+    enabled,
+    fallbackRef,
+    initialFocusRef,
+    targetRef,
+}: {
+    enabled: boolean;
+    fallbackRef: RefObject<HTMLElement>;
+    initialFocusRef?: RefObject<HTMLElement>;
+    targetRef: RefObject<HTMLElement>;
+}) => {
+    // eslint-disable-next-line func-call-spacing
+    const ref = useRef<{ activate: () => void; deactivate: () => void }>({
+        activate: () => {
+            throw new TypeError('Tried to activate focus trap too early');
+        },
+        deactivate: () => {},
+    });
+    const previousActiveElement = useRef<Element | null>(null);
+
+    useDebugValue(enabled ? 'Enabled' : 'Disabled');
+
+    useEffect(() => {
+        if (!enabled) {
+            ref.current.deactivate();
+            ref.current = { activate: () => {}, deactivate: () => {} };
+            return;
+        }
+
+        const target = targetRef.current;
+        let active = false;
+
+        const getFocusableElements = (container: HTMLElement): HTMLElement[] => {
+            const focusableSelectors = [
+                'button:not([disabled])',
+                'input:not([disabled])',
+                'textarea:not([disabled])',
+                'select:not([disabled])',
+                'a[href]',
+                '[tabindex]:not([tabindex="-1"])',
+            ].join(', ');
+
+            return Array.from(container.querySelectorAll(focusableSelectors)) as HTMLElement[];
+        };
+
+        const handleKeyDown = (e: KeyboardEvent) => {
+            // eslint-disable-next-line @typescript-eslint/prefer-optional-chain, @typescript-eslint/no-unnecessary-condition
+            if (!active || !target || e.key !== 'Tab') {
+                return;
+            }
+
+            const focusableElements = getFocusableElements(target);
+            if (focusableElements.length === 0) {
+                return;
+            }
+
+            const firstElement = focusableElements[0];
+            const lastElement = focusableElements[focusableElements.length - 1];
+
+            if (e.shiftKey) {
+                if (document.activeElement === firstElement) {
+                    e.preventDefault();
+                    lastElement.focus();
+                }
+            } else if (document.activeElement === lastElement) {
+                e.preventDefault();
+                firstElement.focus();
+            }
+        };
+
+        ref.current = {
+            activate: () => {
+                // eslint-disable-next-line @typescript-eslint/prefer-optional-chain, @typescript-eslint/no-unnecessary-condition
+                if (active || !target) {
+                    return;
+                }
+                active = true;
+
+                // Store the previously focused element
+                previousActiveElement.current = document.activeElement;
+
+                // Add event listener for tab trapping
+                document.addEventListener('keydown', handleKeyDown);
+            },
+            deactivate: () => {
+                if (!active) {
+                    return;
+                }
+                active = false;
+
+                // Remove event listener
+                document.removeEventListener('keydown', handleKeyDown);
+
+                // Restore focus to previously focused element
+                if (
+                    previousActiveElement.current &&
+                    typeof (previousActiveElement.current as HTMLElement).focus === 'function'
+                ) {
+                    (previousActiveElement.current as HTMLElement).focus();
+                }
+                previousActiveElement.current = null;
+            },
+        };
+    }, [enabled, fallbackRef, initialFocusRef, targetRef]);
+
+    return ref;
+};

package/src/BottomSheet/hooks/useLayoutEffect.tsx

@@ -0,0 +1,4 @@
+import { useEffect, useLayoutEffect as useLayoutEffectSafely } from 'react';
+
+// Ensure the name used in components is useLayoutEffect so the eslint react hooks plugin works
+export const useLayoutEffect = typeof window !== 'undefined' ? useLayoutEffectSafely : useEffect;

package/src/BottomSheet/hooks/useOptimizedResizeObserver.tsx

@@ -0,0 +1,94 @@
+import { ResizeObserver, ResizeObserverEntry } from '@juggle/resize-observer';
+import { ResizeObserverOptions } from '@juggle/resize-observer/lib/ResizeObserverOptions';
+import { RefObject, useCallback, useEffect, useRef } from 'react';
+
+import type { ResizeSource } from '../types';
+
+const observerOptions: ResizeObserverOptions = {
+    box: 'border-box',
+};
+
+/**
+ * Performance-optimized hook that combines multiple resize observers into a single observer
+ * with throttled updates using requestAnimationFrame
+ */
+export const useOptimizedResizeObserver = (
+    targets: Array<{
+        enabled: boolean;
+        label: string;
+        onResize: (size: number) => void;
+        ref: RefObject<Element>;
+    }>,
+    resizeSourceRef: RefObject<ResizeSource>
+) => {
+    const rafRef = useRef<number>(0);
+    const pendingUpdatesRef = useRef<Map<string, number>>(new Map());
+
+    const handleResize = useCallback(
+        (entries: ResizeObserverEntry[]) => {
+            // Cancel any pending RAF to throttle updates
+            if (rafRef.current) {
+                cancelAnimationFrame(rafRef.current);
+            }
+
+            // Collect all size updates
+            entries.forEach((entry) => {
+                const element = entry.target;
+                const size = entry.borderBoxSize[0].blockSize;
+
+                // Find the corresponding target by element reference
+                const target = targets.find((t) => t.ref.current === element);
+                if (target?.enabled) {
+                    pendingUpdatesRef.current.set(target.label, size);
+                }
+            });
+
+            // Process all updates in a single RAF
+            rafRef.current = requestAnimationFrame(() => {
+                const updates = pendingUpdatesRef.current;
+
+                // Apply all size updates
+                targets.forEach((target) => {
+                    if (target.enabled && updates.has(target.label)) {
+                        const size = updates.get(target.label)!;
+                        target.onResize(size);
+                    }
+                });
+
+                // Set resize source after all updates
+                if (updates.size > 0) {
+                    resizeSourceRef.current = 'element';
+                }
+
+                // Clear pending updates
+                updates.clear();
+                rafRef.current = 0;
+            });
+        },
+        [targets, resizeSourceRef]
+    );
+
+    useEffect(() => {
+        const elementsToObserve = targets
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            .filter((target) => target.ref.current && target.enabled)
+            .map((target) => target.ref.current!);
+
+        if (elementsToObserve.length === 0) {
+            return;
+        }
+
+        const resizeObserver = new ResizeObserver(handleResize);
+
+        elementsToObserve.forEach((element) => {
+            resizeObserver.observe(element, observerOptions);
+        });
+
+        return () => {
+            resizeObserver.disconnect();
+            if (rafRef.current) {
+                cancelAnimationFrame(rafRef.current);
+            }
+        };
+    }, [handleResize, targets]);
+};

package/src/BottomSheet/hooks/useOptimizedScrollState.tsx

@@ -0,0 +1,87 @@
+import { RefObject, useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * Custom hook for optimized scroll state management
+ * Reduces re-renders and improves performance for scroll tracking
+ */
+export const useOptimizedScrollState = (scrollRef: RefObject<HTMLDivElement | null>, ready: boolean) => {
+    const [isScrollable, setIsScrollable] = useState(false);
+    const [isScrolledToBottom, setIsScrolledToBottom] = useState(false);
+
+    // Function to check if content is scrollable and if we're at the bottom
+    // Memoized with throttling for better performance
+    const checkScrollState = useCallback(() => {
+        const elem = scrollRef.current;
+        if (!elem) {
+            return;
+        }
+
+        const { clientHeight, scrollHeight, scrollTop } = elem;
+        const scrollable = scrollHeight > clientHeight;
+        const atBottom = Math.abs(scrollHeight - clientHeight - scrollTop) < 1;
+
+        // Only update state if values actually changed to prevent unnecessary re-renders
+        setIsScrollable((prev) => (prev !== scrollable ? scrollable : prev));
+        setIsScrolledToBottom((prev) => (prev !== atBottom ? atBottom : prev));
+    }, [scrollRef]);
+
+    const checkScrollStateRef = useRef(checkScrollState);
+    checkScrollStateRef.current = checkScrollState;
+
+    // Set up scroll listener and initial check with optimized throttling
+    useEffect(() => {
+        const elem = scrollRef.current;
+        if (!elem || !ready) {
+            return;
+        }
+
+        checkScrollState();
+
+        // Use requestAnimationFrame for scroll throttling instead of setTimeout
+        let scrollRaf: number | null = null;
+        let resizeRaf: number | null = null;
+
+        const throttledScrollCheck = () => {
+            if (scrollRaf !== null) {
+                return;
+            }
+            scrollRaf = requestAnimationFrame(() => {
+                checkScrollStateRef.current();
+                scrollRaf = null;
+            });
+        };
+
+        const throttledResizeCheck = () => {
+            if (resizeRaf !== null) {
+                return;
+            }
+            resizeRaf = requestAnimationFrame(() => {
+                checkScrollStateRef.current();
+                resizeRaf = null;
+            });
+        };
+
+        // Use passive listeners for better scroll performance
+        elem.addEventListener('scroll', throttledScrollCheck, { passive: true });
+
+        const resizeObserver = new ResizeObserver(throttledResizeCheck);
+        resizeObserver.observe(elem);
+
+        return () => {
+            elem.removeEventListener('scroll', throttledScrollCheck);
+            if (scrollRaf !== null) {
+                cancelAnimationFrame(scrollRaf);
+            }
+            if (resizeRaf !== null) {
+                cancelAnimationFrame(resizeRaf);
+            }
+            resizeObserver.disconnect();
+        };
+    }, [ready, scrollRef, checkScrollState]);
+
+    return {
+        checkScrollState,
+        isScrollable,
+        isScrolledToBottom,
+    };
+};

package/src/BottomSheet/hooks/useReady.tsx

@@ -0,0 +1,34 @@
+/* eslint-disable no-console */
+// Keeps track of wether everything is good to go or not, in the most efficient way possible
+
+import { useCallback, useEffect, useState } from 'react';
+
+export const useReady = () => {
+    const [ready, setReady] = useState(false);
+    const [readyMap, updateReadyMap] = useState<{ [key: string]: boolean }>({});
+
+    const registerReady = useCallback((key: string) => {
+        // Register the check we're gonna wait for until it's ready
+        updateReadyMap((ready) => ({ ...ready, [key]: false }));
+
+        return () => {
+            // Set it to ready
+            updateReadyMap((ready) => ({ ...ready, [key]: true }));
+        };
+    }, []);
+
+    useEffect(() => {
+        const states = Object.values(readyMap);
+
+        if (states.length === 0) {
+            return;
+        }
+
+        const isReady = states.every(Boolean);
+        if (isReady) {
+            setReady(true);
+        }
+    }, [readyMap]);
+
+    return { ready, registerReady };
+};

package/src/BottomSheet/hooks/useReducedMotion.tsx

@@ -0,0 +1,22 @@
+import { useDebugValue, useEffect, useMemo, useRef } from 'react';
+
+export const useReducedMotion = () => {
+    const mql = useMemo(
+        () => (typeof window !== 'undefined' ? window.matchMedia('(prefers-reduced-motion: reduce)') : null),
+        []
+    );
+    const ref = useRef(mql?.matches);
+
+    useDebugValue(ref.current ? 'reduce' : 'no-preference');
+
+    useEffect(() => {
+        const handler = (event: MediaQueryListEvent) => {
+            ref.current = event.matches;
+        };
+        mql?.addEventListener('change', handler);
+
+        return () => mql?.removeEventListener('change', handler);
+    }, [mql]);
+
+    return ref;
+};