import { useCallback, useEffect, useMemo, useRef, useState } from 'react'; import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent, RefObject, } from 'react'; export type UseInertialHorizontalScrollOptions = { axis?: 'x' | 'y'; scrollStepRatio?: number; dragThreshold?: number; friction?: number; minVelocity?: number; }; export type UseInertialHorizontalScrollResult = { scrollRef: RefObject; isDragging: boolean; canScrollBack: boolean; canScrollForward: boolean; scrollBack: () => void; scrollForward: () => void; scrollProps: { onPointerDown: (evt: ReactPointerEvent) => void; onPointerMove: (evt: ReactPointerEvent) => void; onPointerUp: (evt: ReactPointerEvent) => void; onPointerCancel: (evt: ReactPointerEvent) => void; onLostPointerCapture: (evt: ReactPointerEvent) => void; onDragStartCapture: (evt: React.DragEvent) => void; onClickCapture: (evt: ReactMouseEvent) => void; }; }; const TEXT_SELECTION_TARGET_SELECTOR = '[data-allow-text-selection="true"], input, textarea, [contenteditable="true"]'; type ScrollState = { activePointerId: number | null; startPrimary: number; startScrollPrimary: number; lastPrimary: number; lastTime: number; velocity: number; dragging: boolean; moved: boolean; suppressClick: boolean; animationFrameId: number | null; }; type PointerLikeEvent = { pointerId: number; clientX: number; clientY: number; timeStamp: number; preventDefault?: () => void; }; const DEFAULT_OPTIONS: Required = { axis: 'x', scrollStepRatio: 1.3, dragThreshold: 3, friction: 0.95, minVelocity: 0.02, }; /** * Shared hook for drag-scrolling horizontal overflow areas with inertial momentum. */ export function useInertialHorizontalScroll( options: UseInertialHorizontalScrollOptions = {}, ): UseInertialHorizontalScrollResult { const resolvedOptions = useMemo(() => ({ ...DEFAULT_OPTIONS, ...options }), [options]); const scrollRef = useRef(null); const stateRef = useRef({ activePointerId: null, startPrimary: 0, startScrollPrimary: 0, lastPrimary: 0, lastTime: 0, velocity: 0, dragging: false, moved: false, suppressClick: false, animationFrameId: null, }); const [isDragging, setIsDragging] = useState(false); const [canScrollBack, setCanScrollBack] = useState(false); const [canScrollForward, setCanScrollForward] = useState(false); const updateScrollState = useCallback(() => { const scroll = scrollRef.current; if (!scroll) return; const isHorizontal = resolvedOptions.axis === 'x'; const scrollPrimary = isHorizontal ? scroll.scrollLeft : scroll.scrollTop; const scrollSize = isHorizontal ? scroll.scrollWidth : scroll.scrollHeight; const clientSize = isHorizontal ? scroll.clientWidth : scroll.clientHeight; const maxScrollPrimary = Math.max(scrollSize - clientSize, 0); setCanScrollBack(scrollPrimary > 1); setCanScrollForward(scrollPrimary < maxScrollPrimary - 1); }, [resolvedOptions.axis]); useEffect(() => { updateScrollState(); const scroll = scrollRef.current; if (!scroll) return undefined; const handleScroll = () => { updateScrollState(); }; const handleResize = () => { updateScrollState(); }; scroll.addEventListener('scroll', handleScroll, { passive: true }); window.addEventListener('resize', handleResize, { passive: true }); return () => { scroll.removeEventListener('scroll', handleScroll); window.removeEventListener('resize', handleResize); }; }, [updateScrollState]); useEffect( () => () => { const { animationFrameId } = stateRef.current; if (animationFrameId !== null) { cancelAnimationFrame(animationFrameId); } }, [], ); const scrollByStep = useCallback( (direction: 1 | -1) => { const scroll = scrollRef.current; if (!scroll) return; const isHorizontal = resolvedOptions.axis === 'x'; const currentPrimary = isHorizontal ? scroll.scrollLeft : scroll.scrollTop; const offsetSize = isHorizontal ? scroll.offsetWidth : scroll.offsetHeight; scroll.scrollTo({ ...(isHorizontal ? { left: currentPrimary + (offsetSize / resolvedOptions.scrollStepRatio) * direction } : { top: currentPrimary + (offsetSize / resolvedOptions.scrollStepRatio) * direction }), behavior: 'smooth', }); }, [resolvedOptions.axis, resolvedOptions.scrollStepRatio], ); const stopInertia = useCallback(() => { const state = stateRef.current; if (state.animationFrameId !== null) { cancelAnimationFrame(state.animationFrameId); state.animationFrameId = null; } }, []); const startInertia = useCallback(() => { const state = stateRef.current; const scroll = scrollRef.current; if (!scroll) return; const isHorizontal = resolvedOptions.axis === 'x'; const step = (timestamp: number, previousTimestamp: number) => { const currentState = stateRef.current; const currentScroll = scrollRef.current; if (!currentScroll) return; const deltaMs = Math.max(timestamp - previousTimestamp, 1); const deltaScroll = currentState.velocity * deltaMs; if (Math.abs(currentState.velocity) < resolvedOptions.minVelocity) { currentState.animationFrameId = null; updateScrollState(); return; } const before = isHorizontal ? currentScroll.scrollLeft : currentScroll.scrollTop; if (isHorizontal) { currentScroll.scrollLeft = before - deltaScroll; } else { currentScroll.scrollTop = before - deltaScroll; } updateScrollState(); const after = isHorizontal ? currentScroll.scrollLeft : currentScroll.scrollTop; if (after === before) { currentState.animationFrameId = null; return; } currentState.velocity *= resolvedOptions.friction ** (deltaMs / 16.6667); currentState.animationFrameId = requestAnimationFrame((nextTimestamp) => step(nextTimestamp, timestamp), ); }; stopInertia(); state.animationFrameId = requestAnimationFrame((timestamp) => step(timestamp, timestamp)); }, [ resolvedOptions.axis, resolvedOptions.friction, resolvedOptions.minVelocity, stopInertia, updateScrollState, ]); const endDrag = useCallback( (pointerId: number | null) => { const state = stateRef.current; if (!state.dragging) return; const scroll = scrollRef.current; if (scroll && pointerId !== null && scroll.hasPointerCapture(pointerId)) { scroll.releasePointerCapture(pointerId); } if (state.moved) { state.suppressClick = true; startInertia(); } state.dragging = false; state.activePointerId = null; state.moved = false; state.velocity = 0; setIsDragging(false); }, [startInertia], ); const processPointerMove = useCallback( (evt: PointerLikeEvent) => { const state = stateRef.current; if (!state.dragging || state.activePointerId !== evt.pointerId) { return; } const scroll = scrollRef.current; if (!scroll) return; const isHorizontal = resolvedOptions.axis === 'x'; const currentPrimary = isHorizontal ? evt.clientX : evt.clientY; const deltaPrimary = currentPrimary - state.startPrimary; const now = evt.timeStamp; const deltaTime = Math.max(now - state.lastTime, 1); const hasExceededThreshold = Math.abs(deltaPrimary) >= resolvedOptions.dragThreshold; if (hasExceededThreshold) { state.moved = true; } if (!state.moved) { state.lastPrimary = currentPrimary; state.lastTime = now; return; } evt.preventDefault?.(); if (isHorizontal) { scroll.scrollLeft = state.startScrollPrimary - deltaPrimary; } else { scroll.scrollTop = state.startScrollPrimary - deltaPrimary; } const rawVelocity = (currentPrimary - state.lastPrimary) / deltaTime; state.velocity = Math.max(Math.min(rawVelocity, 2), -2); state.lastPrimary = currentPrimary; state.lastTime = now; }, [resolvedOptions.axis, resolvedOptions.dragThreshold], ); const handlePointerDown = useCallback( (evt: React.PointerEvent) => { if (evt.button !== 0) return; if (!evt.isPrimary) return; const state = stateRef.current; if (state.dragging && state.activePointerId === evt.pointerId) return; const { target } = evt; if (target instanceof Element && target.closest(TEXT_SELECTION_TARGET_SELECTOR)) { return; } const scroll = scrollRef.current; if (!scroll) return; const isHorizontal = resolvedOptions.axis === 'x'; stopInertia(); state.activePointerId = evt.pointerId; state.startPrimary = isHorizontal ? evt.clientX : evt.clientY; state.startScrollPrimary = isHorizontal ? scroll.scrollLeft : scroll.scrollTop; state.lastPrimary = isHorizontal ? evt.clientX : evt.clientY; state.lastTime = evt.timeStamp; state.velocity = 0; state.dragging = true; state.moved = false; state.suppressClick = false; try { scroll.setPointerCapture(evt.pointerId); } catch { // Ignore capture failures when browser has already ended pointer interaction. } setIsDragging(true); }, [resolvedOptions.axis, stopInertia], ); const handlePointerMove = useCallback( (evt: React.PointerEvent) => { processPointerMove(evt); }, [processPointerMove], ); const handlePointerUp = useCallback( (evt: React.PointerEvent) => { const state = stateRef.current; if (state.activePointerId !== evt.pointerId) return; endDrag(evt.pointerId); }, [endDrag], ); const handlePointerCancel = useCallback( (evt: React.PointerEvent) => { const state = stateRef.current; if (state.activePointerId !== evt.pointerId) return; endDrag(evt.pointerId); }, [endDrag], ); const handleLostPointerCapture = useCallback( (evt: React.PointerEvent) => { const state = stateRef.current; if (state.activePointerId !== evt.pointerId) return; endDrag(evt.pointerId); }, [endDrag], ); useEffect(() => { const handleWindowPointerMove = (evt: PointerEvent) => { processPointerMove(evt); }; const handleWindowPointerUpOrCancel = (evt: PointerEvent) => { const state = stateRef.current; if (state.activePointerId !== evt.pointerId) return; endDrag(evt.pointerId); }; window.addEventListener('pointermove', handleWindowPointerMove, true); window.addEventListener('pointerup', handleWindowPointerUpOrCancel, true); window.addEventListener('pointercancel', handleWindowPointerUpOrCancel, true); return () => { window.removeEventListener('pointermove', handleWindowPointerMove, true); window.removeEventListener('pointerup', handleWindowPointerUpOrCancel, true); window.removeEventListener('pointercancel', handleWindowPointerUpOrCancel, true); }; }, [endDrag, processPointerMove]); useEffect(() => { const handleGlobalDragTermination = () => { const state = stateRef.current; if (!state.dragging) return; endDrag(state.activePointerId); }; const handleVisibilityChange = () => { if (document.visibilityState !== 'visible') { handleGlobalDragTermination(); } }; window.addEventListener('mouseup', handleGlobalDragTermination, true); window.addEventListener('pointerup', handleGlobalDragTermination, true); window.addEventListener('blur', handleGlobalDragTermination, true); document.addEventListener('visibilitychange', handleVisibilityChange, true); return () => { window.removeEventListener('mouseup', handleGlobalDragTermination, true); window.removeEventListener('pointerup', handleGlobalDragTermination, true); window.removeEventListener('blur', handleGlobalDragTermination, true); document.removeEventListener('visibilitychange', handleVisibilityChange, true); }; }, [endDrag]); const handleClickCapture = useCallback((evt: React.MouseEvent) => { const state = stateRef.current; if (!state.suppressClick) return; state.suppressClick = false; evt.preventDefault(); evt.stopPropagation(); }, []); const handleDragStartCapture = useCallback((evt: React.DragEvent) => { evt.preventDefault(); }, []); return { scrollRef, isDragging, canScrollBack, canScrollForward, scrollBack: () => scrollByStep(-1), scrollForward: () => scrollByStep(1), scrollProps: { onPointerDown: handlePointerDown, onPointerMove: handlePointerMove, onPointerUp: handlePointerUp, onPointerCancel: handlePointerCancel, onLostPointerCapture: handleLostPointerCapture, onDragStartCapture: handleDragStartCapture, onClickCapture: handleClickCapture, }, }; }