@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/BottomSheet/index.tsx

@@ -0,0 +1,237 @@
+import { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import type { Props, RefHandles, SpringEvent } from './types';
+
+/* eslint-disable react/jsx-pascal-case */
+import { BottomSheet as _BottomSheet } from './BottomSheet';
+import { useLayoutEffect } from './hooks';
+
+export type { RefHandles as BottomSheetRef, Props as BottomSheetProps } from './types';
+
+/**
+ * BottomSheet component with SSR support and proper animation lifecycle management
+ */
+export const BottomSheet = forwardRef<RefHandles, Props>(function BottomSheet(
+    { onCloseEnd, onDismiss, onSpringEnd, onSpringStart, ...props },
+    ref
+) {
+    // === Component State ===
+    // Mounted state helps with SSR and ensures accessibility (no tabbing/screen reader access when closed)
+    const [mounted, setMounted] = useState(false);
+    const [modalTarget, setModalTarget] = useState<HTMLElement | null>(null);
+
+    // === Animation State ===
+    // Internal state to manage animation lifecycle separate from the open prop
+    const [isAnimating, setIsAnimating] = useState(false);
+    // Track if we're in the middle of an opening animation
+    const [isOpening, setIsOpening] = useState(false);
+    // Internal state to handle initial delay for proper transitions
+    const [shouldShow, setShouldShow] = useState(false);
+
+    // === Refs for State Management ===
+    const timerRef = useRef<ReturnType<typeof requestAnimationFrame>>(0);
+    // The last snap point for remembering user-defined height
+    const lastSnapRef = useRef(0);
+    // Track if we should call onDismiss after close animation completes
+    const shouldCallOnDismiss = useRef(false);
+    // Track last action time to prevent rapid successive calls
+    const lastActionTime = useRef(0);
+    // Track if we're in a force-closed state to ignore all spring events
+    const isForceClosedRef = useRef(false);
+
+    // Initial state determines animation behavior on mount
+    const initialStateRef = useRef<'OPEN' | 'CLOSED'>('CLOSED');
+
+    // Find the modal target element
+    useEffect(() => {
+        const target = document.querySelector('.hui-modal-target');
+
+        if (!target) {
+            throw new Error('Modal target not found, add one in the DOM tree.');
+        }
+
+        setModalTarget(target as HTMLElement);
+    }, []);
+
+    // === Helper Functions ===
+    // Start the close transition (similar to Drawer pattern)
+    const startCloseTransition = useCallback((callOnDismiss: boolean = false) => {
+        setIsAnimating(true);
+        shouldCallOnDismiss.current = callOnDismiss;
+    }, []);
+
+    // Handle internal onDismiss that calls the original onDismiss immediately
+    // Memoized to prevent unnecessary re-renders
+    const handleInternalDismiss = useCallback(() => {
+        const now = Date.now();
+        const DEBOUNCE_MS = 150; // Increased debounce time for stress testing
+
+        // Prevent dismiss during opening animations or rapid successive calls
+        // Allow dismiss during closing animations (drag-to-close scenario)
+        if (isOpening || isAnimating || now - lastActionTime.current < DEBOUNCE_MS) {
+            return;
+        }
+
+        lastActionTime.current = now;
+        isForceClosedRef.current = true;
+
+        onDismiss?.();
+    }, [onDismiss, isOpening, isAnimating]);
+
+    // === Effects ===
+    // Close the sheet when the open prop changes to false
+    useEffect(() => {
+        if (mounted && !props.open && !isAnimating) {
+            startCloseTransition(false);
+        }
+    }, [mounted, props.open, isAnimating, startCloseTransition]);
+
+    // Handle mounting and opening state - supports cases where sheet appears already open
+    useLayoutEffect(() => {
+        if (props.open) {
+            // Prevent rapid re-mounting during stress testing
+            const now = Date.now();
+            if (now - lastActionTime.current < 50) {
+                return undefined; // Skip if too rapid
+            }
+
+            cancelAnimationFrame(timerRef.current);
+            setMounted(true);
+            // Reset all state when opening
+            setIsAnimating(false);
+            setIsOpening(true);
+            shouldCallOnDismiss.current = false;
+            lastActionTime.current = now;
+            isForceClosedRef.current = false;
+
+            // Add initial delay for proper transition
+            // Use requestAnimationFrame to ensure DOM is ready for transition
+            const delayId = requestAnimationFrame(() => {
+                // Double-check we're still supposed to be open
+                if (props.open) {
+                    setShouldShow(true);
+                }
+            });
+
+            // Cleanup function will clear the delay
+            return () => {
+                cancelAnimationFrame(delayId);
+                initialStateRef.current = 'CLOSED';
+                setShouldShow(false);
+            };
+        }
+
+        // Reset shouldShow when not open
+        setShouldShow(false);
+        return undefined;
+    }, [props.open]);
+
+    const handleSpringStart = useCallback(
+        async function handleSpringStart(event: SpringEvent) {
+            // Only process events for open component or CLOSE events
+            if (!props.open && event.type !== 'CLOSE') {
+                return;
+            }
+
+            await onSpringStart?.(event);
+
+            if (event.type === 'OPEN') {
+                // Cancel any pending unmount when opening
+                cancelAnimationFrame(timerRef.current);
+            }
+        },
+        [onSpringStart, props.open]
+    );
+
+    const handleSpringEnd = useCallback(
+        async function handleSpringEnd(event: SpringEvent) {
+            // Only process CLOSE events when force-closed, or any event when open
+            const shouldIgnore = (isForceClosedRef.current || !props.open) && event.type !== 'CLOSE';
+            if (shouldIgnore) {
+                return;
+            }
+
+            await onSpringEnd?.(event);
+
+            if (event.type === 'OPEN') {
+                setIsOpening(false);
+            } else if (event.type === 'CLOSE') {
+                // Reset all animation state and unmount
+                setIsAnimating(false);
+                setIsOpening(false);
+                shouldCallOnDismiss.current = false;
+                timerRef.current = requestAnimationFrame(() => setMounted(false));
+            }
+        },
+        [onSpringEnd, props.open]
+    );
+
+    // Fallback unmounting - ensures component unmounts even if spring callback fails
+    useEffect(() => {
+        if (!props.open && mounted) {
+            const fallbackTimeoutId = setTimeout(() => {
+                // Only unmount if we're still in the closed state after timeout
+                if (!props.open) {
+                    cancelAnimationFrame(timerRef.current);
+                    setMounted(false);
+                    setIsAnimating(false);
+                    shouldCallOnDismiss.current = false;
+                    isForceClosedRef.current = true;
+                }
+            }, 500);
+
+            return () => clearTimeout(fallbackTimeoutId);
+        }
+        return undefined;
+    }, [props.open, mounted]);
+
+    // Cleanup effect - let React handle DOM cleanup naturally
+    useEffect(() => {
+        return () => {
+            // Minimal cleanup - only clear empty modal targets to prevent memory leaks
+            // Let React handle the component unmounting naturally
+            setTimeout(() => {
+                try {
+                    const modalTarget = document.querySelector('.hui-modal-target');
+                    // Only clean if modal target is completely empty and we're sure React is done
+                    if (modalTarget && modalTarget.children.length === 0) {
+                        modalTarget.innerHTML = '';
+                    }
+                } catch {
+                    // Ignore cleanup errors during rapid state changes
+                }
+            }, 200); // Longer delay to avoid race conditions with React
+        };
+    }, []); // Only run on component unmount
+
+    // === Early Return for SSR and Unmounted State ===
+    if (!mounted || !modalTarget) {
+        return null;
+    }
+
+    // === Render ===
+    // Extract onDismiss from props to avoid conflicts with internal handler
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { onDismiss: _, ...bottomSheetProps } = props as Props & { onDismiss?: () => void };
+
+    return createPortal(
+        <div
+            aria-hidden={!props.open}
+            role="presentation"
+        >
+            <_BottomSheet
+                {...bottomSheetProps}
+                initialState={initialStateRef.current}
+                lastSnapRef={lastSnapRef}
+                onCloseEnd={onCloseEnd}
+                onDismiss={handleInternalDismiss}
+                onSpringEnd={handleSpringEnd}
+                onSpringStart={handleSpringStart}
+                open={shouldShow}
+                ref={ref}
+            />
+        </div>,
+        modalTarget
+    );
+});

package/src/BottomSheet/state/atoms.ts

@@ -0,0 +1,147 @@
+import { atom } from 'jotai';
+
+/**
+ * Bottom sheet state types
+ */
+export type BottomSheetState = 'closed' | 'opening' | 'open' | 'closing' | 'dragging' | 'snapping' | 'resizing';
+
+export type BottomSheetEvent =
+    | { type: 'OPEN' }
+    | { type: 'CLOSE' }
+    | { type: 'DRAG' }
+    | { type: 'RESIZE' }
+    | {
+          payload: {
+              source: 'dragging' | 'custom' | string;
+              velocity: number;
+              y: number;
+          };
+          type: 'SNAP';
+      };
+
+/** The payload shape carried by SNAP events. */
+export type SnapPayload = Extract<BottomSheetEvent, { type: 'SNAP' }>['payload'];
+
+export type BottomSheetContext = {
+    initialState: 'OPEN' | 'CLOSED';
+    snapSource?: 'dragging' | 'custom' | string;
+    velocity?: number;
+    y?: number;
+};
+
+/**
+ * Core state atoms
+ */
+export const bottomSheetStateAtom = atom<BottomSheetState>('closed');
+export const bottomSheetContextAtom = atom<BottomSheetContext>({ initialState: 'CLOSED' });
+
+/**
+ * Derived state atoms
+ */
+export const isOpenAtom = atom((get) => {
+    const state = get(bottomSheetStateAtom);
+    return (
+        state === 'open' || state === 'opening' || state === 'dragging' || state === 'snapping' || state === 'resizing'
+    );
+});
+
+export const isClosedAtom = atom((get) => {
+    const state = get(bottomSheetStateAtom);
+    return state === 'closed';
+});
+
+export const isTransitioningAtom = atom((get) => {
+    const state = get(bottomSheetStateAtom);
+    return state === 'opening' || state === 'closing' || state === 'snapping' || state === 'resizing';
+});
+
+export const isDraggingAtom = atom((get) => {
+    const state = get(bottomSheetStateAtom);
+    return state === 'dragging';
+});
+
+/**
+ * Action atoms for state transitions
+ */
+export const sendEventAtom = atom(null, (get, set, event: BottomSheetEvent) => {
+    const currentState = get(bottomSheetStateAtom);
+    const context = get(bottomSheetContextAtom);
+
+    // Add guards to prevent rapid state changes
+    switch (event.type) {
+        case 'OPEN':
+            if (currentState === 'closed' || currentState === 'closing') {
+                set(bottomSheetStateAtom, 'opening');
+            }
+            break;
+
+        case 'CLOSE':
+            if (currentState !== 'closed' && currentState !== 'closing') {
+                set(bottomSheetStateAtom, 'closing');
+            }
+            break;
+
+        case 'DRAG':
+            // Only allow drag if not already in a transitional state
+            if (
+                currentState === 'open' ||
+                (currentState === 'opening' && context.initialState === 'OPEN') ||
+                currentState === 'snapping' ||
+                currentState === 'resizing'
+            ) {
+                set(bottomSheetStateAtom, 'dragging');
+            }
+            break;
+
+        case 'SNAP':
+            // Only allow snap from dragging or stable open state
+            if (currentState === 'dragging' || currentState === 'open') {
+                // Batch the context and state updates to prevent multiple renders
+                const newContext = {
+                    ...context,
+                    snapSource: event.payload.source,
+                    velocity: event.payload.velocity,
+                    y: event.payload.y,
+                };
+
+                set(bottomSheetContextAtom, newContext);
+                set(bottomSheetStateAtom, 'snapping');
+            }
+            break;
+
+        case 'RESIZE':
+            // Only allow resize from stable states
+            if (currentState === 'open') {
+                set(bottomSheetStateAtom, 'resizing');
+            }
+            break;
+
+        default:
+            break;
+    }
+});
+
+/**
+ * Transition completion atoms
+ */
+export const completeTransitionAtom = atom(null, (get, set, targetState: BottomSheetState) => {
+    const currentState = get(bottomSheetStateAtom);
+
+    // Only complete transitions if we're currently in a transitioning state
+    if (get(isTransitioningAtom) || currentState === 'dragging') {
+        set(bottomSheetStateAtom, targetState);
+    }
+});
+
+/**
+ * Reset atom for cleanup
+ */
+export const resetStateAtom = atom(null, (get, set, initialState: 'OPEN' | 'CLOSED' = 'CLOSED') => {
+    set(bottomSheetStateAtom, initialState === 'OPEN' ? 'open' : 'closed');
+    set(bottomSheetContextAtom, {
+        initialState,
+        snapSource: undefined,
+        velocity: undefined,
+        y: undefined,
+    });
+});

package/src/BottomSheet/state/useBottomSheetStateMachine.ts

@@ -0,0 +1,246 @@
+import { useAtom, useAtomValue, useSetAtom } from 'jotai';
+import { useCallback, useEffect, useRef } from 'react';
+
+import {
+    type BottomSheetContext,
+    bottomSheetContextAtom,
+    type BottomSheetEvent,
+    type BottomSheetState,
+    bottomSheetStateAtom,
+    completeTransitionAtom,
+    isClosedAtom,
+    isDraggingAtom,
+    isOpenAtom,
+    isTransitioningAtom,
+    resetStateAtom,
+    sendEventAtom,
+    type SnapPayload,
+} from './atoms';
+
+/**
+ * Services interface matching the XState pattern
+ */
+export interface BottomSheetServices {
+    activate: () => Promise<void>;
+    closeSmoothly: () => Promise<void>;
+    deactivate: () => Promise<void>;
+    onCloseEnd: () => Promise<void>;
+    onCloseStart: () => Promise<void>;
+    onOpenEnd: () => Promise<void>;
+    onOpenStart: () => Promise<void>;
+    onResizeEnd: () => Promise<void>;
+    onResizeStart: () => Promise<void>;
+    onSnapEnd: (context: BottomSheetContext) => Promise<void>;
+    onSnapStart: (context: BottomSheetContext) => Promise<void>;
+    openImmediately: () => Promise<void>;
+    openSmoothly: () => Promise<void>;
+    renderVisuallyHidden: () => Promise<void>;
+    resizeSmoothly: () => Promise<void>;
+    snapSmoothly: (context: BottomSheetContext) => Promise<void>;
+}
+
+/**
+ * Actions interface matching the XState pattern
+ */
+export interface BottomSheetActions {
+    onCloseCancel: () => void;
+    onCloseEnd: () => void;
+    onOpenCancel: () => void;
+    onOpenEnd: () => void;
+    onResizeCancel: () => void;
+    onResizeEnd: () => void;
+    onSnapCancel: (context: BottomSheetContext) => void;
+    onSnapEnd: (context: BottomSheetContext) => void;
+}
+
+/**
+ * Hook that provides bottom sheet state machine functionality using Jotai
+ */
+export const useBottomSheetStateMachine = (
+    services: BottomSheetServices,
+    actions: BottomSheetActions,
+    initialContext: BottomSheetContext
+) => {
+    const [state] = useAtom(bottomSheetStateAtom);
+    const [context, setContext] = useAtom(bottomSheetContextAtom);
+    const sendEvent = useSetAtom(sendEventAtom);
+    const completeTransition = useSetAtom(completeTransitionAtom);
+    const resetState = useSetAtom(resetStateAtom);
+
+    const isOpen = useAtomValue(isOpenAtom);
+    const isClosed = useAtomValue(isClosedAtom);
+    const isTransitioning = useAtomValue(isTransitioningAtom);
+    const isDragging = useAtomValue(isDraggingAtom);
+
+    // Track previous state for transition logic
+    const prevStateRef = useRef<BottomSheetState>(state);
+    const servicesRef = useRef(services);
+    const actionsRef = useRef(actions);
+
+    // Update refs when services/actions change
+    useEffect(() => {
+        servicesRef.current = services;
+        actionsRef.current = actions;
+    }, [services, actions]);
+
+    // Initialize context only once on mount
+    useEffect(() => {
+        setContext(initialContext);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [setContext]); // Only depend on setContext, not initialContext to avoid infinite loops
+
+    // Handle state transitions and side effects
+    useEffect(() => {
+        const currentServices = servicesRef.current;
+        const currentActions = actionsRef.current;
+        const prevState = prevStateRef.current;
+        const currentContext = context; // Capture context at the time of effect
+
+        const handleStateTransition = async () => {
+            try {
+                switch (state) {
+                    case 'opening':
+                        if (prevState === 'closed') {
+                            await currentServices.onOpenStart();
+
+                            if (currentContext.initialState === 'OPEN') {
+                                await currentServices.renderVisuallyHidden();
+                                await currentServices.activate();
+                                await currentServices.openImmediately();
+                            } else {
+                                await currentServices.renderVisuallyHidden();
+                                await currentServices.activate();
+                                await currentServices.openSmoothly();
+                            }
+
+                            await currentServices.onOpenEnd();
+                            completeTransition('open');
+                        } else if (prevState === 'closing') {
+                            // Cancelled close, resume opening
+                            currentActions.onCloseCancel();
+                            await currentServices.onOpenStart();
+                            await currentServices.renderVisuallyHidden();
+                            await currentServices.activate();
+                            await currentServices.openSmoothly();
+                            await currentServices.onOpenEnd();
+                            completeTransition('open');
+                        }
+                        break;
+
+                    case 'closing':
+                        if (prevState !== 'closed') {
+                            if (prevState === 'opening') {
+                                currentActions.onOpenCancel();
+                            } else if (prevState === 'resizing') {
+                                currentActions.onResizeCancel();
+                            } else if (prevState === 'snapping') {
+                                currentActions.onSnapCancel(currentContext);
+                            }
+
+                            await currentServices.onCloseStart();
+                            await currentServices.deactivate();
+                            await currentServices.closeSmoothly();
+                            await currentServices.onCloseEnd();
+                            currentActions.onCloseEnd();
+                            completeTransition('closed');
+                        }
+                        break;
+
+                    case 'resizing':
+                        if (prevState === 'open' || prevState === 'opening') {
+                            await currentServices.onResizeStart();
+                            await currentServices.resizeSmoothly();
+                            await currentServices.onResizeEnd();
+                            completeTransition('open');
+                        }
+                        break;
+
+                    case 'snapping':
+                        // 'dragging' → snap on release; 'open' → the imperative snapTo API.
+                        // (Upstream only serviced the dragging path, so snapTo from a resting
+                        // sheet entered 'snapping' and stalled without ever animating.)
+                        if (prevState === 'dragging' || prevState === 'open') {
+                            await currentServices.onSnapStart(currentContext);
+                            await currentServices.snapSmoothly(currentContext);
+                            await currentServices.onSnapEnd(currentContext);
+                            completeTransition('open');
+                        }
+                        break;
+
+                    case 'dragging':
+                        // Dragging is handled by gesture handlers, no async operations needed
+                        if (prevState === 'opening') {
+                            currentActions.onOpenEnd();
+                        } else if (prevState === 'closing') {
+                            currentActions.onCloseCancel();
+                        } else if (prevState === 'resizing') {
+                            currentActions.onResizeCancel();
+                        } else if (prevState === 'snapping') {
+                            currentActions.onSnapCancel(currentContext);
+                        }
+                        break;
+                    case 'closed':
+                    case 'open':
+                    default:
+                        break;
+                }
+            } catch (error) {
+                // eslint-disable-next-line no-console
+                console.error('Bottom sheet state transition error:', error);
+                // On error, try to recover to a stable state
+                if (state === 'opening' || state === 'closing' || state === 'resizing' || state === 'snapping') {
+                    completeTransition(state === 'closing' ? 'closed' : 'open');
+                }
+            }
+        };
+
+        if (prevState !== state) {
+            handleStateTransition();
+            prevStateRef.current = state;
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [state, completeTransition]); // Removed context from dependencies
+
+    // Send event function with proper typing
+    const send = useCallback(
+        (type: BottomSheetEvent['type'], payload?: SnapPayload) => {
+            if (type === 'SNAP' && payload) {
+                sendEvent({ payload, type: 'SNAP' });
+            } else {
+                sendEvent({ type } as BottomSheetEvent);
+            }
+        },
+        [sendEvent]
+    );
+
+    // Reset function for cleanup
+    const reset = useCallback(
+        (initialState: 'OPEN' | 'CLOSED' = 'CLOSED') => {
+            resetState(initialState);
+            prevStateRef.current = initialState === 'OPEN' ? 'open' : 'closed';
+        },
+        [resetState]
+    );
+
+    return {
+        // Current state
+        current: {
+            context,
+            matches: (stateName: string) => state === stateName,
+            value: state,
+        },
+        isClosed,
+        isDragging,
+
+        // Derived state
+        isOpen,
+        isTransitioning,
+        reset,
+
+        // Actions
+        send,
+
+        // State value for easy access
+        state,
+    };
+};