etudes 6.2.0 → 6.2.2

package/README.md

@@ -1,3 +1,3 @@
-# Études [![npm](https://img.shields.io/npm/v/etudes.svg)](https://www.npmjs.com/package/etudes) [![CI](https://github.com/andrewscwei/etudes/workflows/CI/badge.svg)](https://github.com/andrewscwei/etudes/actions?query=workflow%3ACI) [![CD](https://github.com/andrewscwei/etudes/workflows/CD/badge.svg)](https://github.com/andrewscwei/etudes/actions?query=workflow%3ACD)
+# Études [![npm](https://img.shields.io/npm/v/etudes.svg)](https://www.npmjs.com/package/etudes) [![CD](https://github.com/andrewscwei/etudes/workflows/CD/badge.svg)](https://github.com/andrewscwei/etudes/actions?query=workflow%3ACD)
 
 A study of headless React components.

package/components/Carousel.js

@@ -6,42 +6,15 @@ import { useTimeout } from '../hooks/useTimeout.js';
 import { Each } from '../operators/Each.js';
 import { asStyleDict, styles } from '../utils/index.js';
 export const Carousel = forwardRef(({ autoAdvanceInterval = 0, index = 0, isDragEnabled = true, items = [], orientation = 'horizontal', tracksItemExposure = false, onAutoAdvancePause, onAutoAdvanceResume, onIndexChange, ItemComponent, ...props }, ref) => {
-    const getItemExposures = () => {
-        const viewportElement = viewportRef.current;
-        if (!viewportElement)
-            return undefined;
-        const exposures = [];
-        for (let i = 0; i < viewportElement.children.length; i++) {
-            exposures.push(getItemExposureAt(i));
-        }
-        return exposures;
-    };
-    const getItemExposureAt = (idx) => {
-        const viewportElement = viewportRef.current;
-        const child = viewportElement?.children[idx];
-        if (!child)
-            return 0;
-        const intersection = Rect.intersecting(child, viewportElement);
-        if (!intersection)
-            return 0;
-        switch (orientation) {
-            case 'horizontal':
-                return Math.max(0, Math.min(1, Math.round((intersection.width / viewportElement.clientWidth + Number.EPSILON) * 1000) / 1000));
-            case 'vertical':
-                return Math.max(0, Math.min(1, Math.round((intersection.height / viewportElement.clientHeight + Number.EPSILON) * 1000) / 1000));
-            default:
-                throw new Error(`Unsupported orientation '${orientation}'`);
-        }
-    };
-    const handleIndexChange = (newValue) => {
-        onIndexChange?.(newValue);
-    };
+    const handleIndexChange = (newValue) => onIndexChange?.(newValue);
     const handlePointerDown = (event) => {
         pointerDownPositionRef.current = Point.make(event.clientX, event.clientY);
         setIsPointerDown(true);
     };
     const handlePointerUp = (event) => {
         pointerUpPositionRef.current = Point.make(event.clientX, event.clientY);
+        if (!isPointerDown)
+            return;
         setIsPointerDown(false);
     };
     const handleClick = (event) => {
@@ -57,66 +30,50 @@ export const Carousel = forwardRef(({ autoAdvanceInterval = 0, index = 0, isDrag
         pointerDownPositionRef.current = undefined;
         pointerUpPositionRef.current = undefined;
     };
-    const autoScrollToCurrentIndex = () => {
-        const viewportElement = viewportRef.current;
-        if (!viewportElement)
-            return;
-        const top = orientation === 'horizontal' ? 0 : viewportElement.clientHeight * index;
-        const left = orientation === 'horizontal' ? viewportElement.clientWidth * index : 0;
-        viewportElement.scrollTo({ top, left, behavior: 'smooth' });
-        clearTimeout(autoScrollTimeoutRef.current);
-        autoScrollTimeoutRef.current = setTimeout(() => {
-            clearTimeout(autoScrollTimeoutRef.current);
-            autoScrollTimeoutRef.current = undefined;
-        }, autoScrollTimeoutMs);
-    };
+    const normalizeScrollPosition = () => scrollToIndex(viewportRef, index, orientation);
     const prevIndexRef = useRef();
     const viewportRef = useRef(null);
     const pointerDownPositionRef = useRef();
     const pointerUpPositionRef = useRef();
-    const [exposures, setExposures] = useState(getItemExposures());
-    const autoScrollTimeoutRef = useRef();
-    const autoScrollTimeoutMs = 1000;
+    const [exposures, setExposures] = useState(getItemExposures(viewportRef, orientation));
     const [isPointerDown, setIsPointerDown] = useState(false);
+    const fixedStyles = getFixedStyles({ scrollSnapEnabled: !isPointerDown, orientation });
+    const shouldAutoAdvance = autoAdvanceInterval > 0;
     useEffect(() => {
-        const viewportElement = viewportRef.current;
-        if (!viewportElement)
+        const viewport = viewportRef.current;
+        if (!viewport)
             return;
-        const scrollHandler = () => {
+        const isInitialRender = prevIndexRef.current === undefined;
+        const isIndexModifiedFromManualScrolling = prevIndexRef.current === index;
+        const scrollHandler = (e) => {
             if (tracksItemExposure) {
-                setExposures(getItemExposures());
+                setExposures(getItemExposures(viewportRef, orientation));
             }
-            if (autoScrollTimeoutRef.current !== undefined)
-                return;
             const newIndex = orientation === 'horizontal'
-                ? Math.round(viewportElement.scrollLeft / viewportElement.clientWidth)
-                : Math.round(viewportElement.scrollTop / viewportElement.clientHeight);
+                ? Math.round(viewport.scrollLeft / viewport.clientWidth)
+                : Math.round(viewport.scrollTop / viewport.clientHeight);
             const clampedIndex = Math.max(0, Math.min(items.length - 1, newIndex));
             if (clampedIndex === index)
                 return;
-            // Set previous index ref here to avoid the side-effect of handling index
-            // changes from prop/state.
+            // Set previous index before emitting index change event to differentiate
+            // between index change from scroll vs from prop.
             prevIndexRef.current = clampedIndex;
             handleIndexChange(clampedIndex);
         };
-        viewportElement.addEventListener('scroll', scrollHandler);
+        viewport.addEventListener('scroll', scrollHandler);
+        if (!isIndexModifiedFromManualScrolling) {
+            prevIndexRef.current = index;
+            if (!isInitialRender) {
+                handleIndexChange(index);
+                normalizeScrollPosition();
+            }
+        }
         return () => {
-            viewportElement.removeEventListener('scroll', scrollHandler);
+            viewport.removeEventListener('scroll', scrollHandler);
         };
-    }, [index, orientation]);
+    }, [index, orientation, tracksItemExposure]);
     useEffect(() => {
-        const isInitialRender = prevIndexRef.current === undefined;
-        const isIndexModifiedFromManualScrolling = prevIndexRef.current === index;
-        if (isIndexModifiedFromManualScrolling)
-            return;
-        prevIndexRef.current = index;
-        if (isInitialRender)
-            return;
-        handleIndexChange(index);
-        autoScrollToCurrentIndex();
-    }, [index, orientation]);
-    useEffect(() => {
-        if (autoAdvanceInterval <= 0)
+        if (!shouldAutoAdvance)
             return;
         if (isPointerDown) {
             onAutoAdvancePause?.();
@@ -124,64 +81,104 @@ export const Carousel = forwardRef(({ autoAdvanceInterval = 0, index = 0, isDrag
         else {
             onAutoAdvanceResume?.();
         }
-    }, [isPointerDown]);
+    }, [isPointerDown, shouldAutoAdvance]);
     useDragEffect(viewportRef, {
         isEnabled: isDragEnabled && items.length > 1,
-        onDragMove: (displacement) => {
+        onDragMove: ({ x, y }) => {
             switch (orientation) {
                 case 'horizontal':
                     requestAnimationFrame(() => {
                         if (!viewportRef.current)
                             return;
-                        viewportRef.current.scrollLeft += displacement.x * 1.5;
+                        viewportRef.current.scrollLeft += x * 1.5;
                     });
                     break;
                 case 'vertical':
                     requestAnimationFrame(() => {
                         if (!viewportRef.current)
                             return;
-                        viewportRef.current.scrollTop += displacement.y * 1.5;
+                        viewportRef.current.scrollTop += y * 1.5;
                     });
                     break;
                 default:
                     throw Error(`Unsupported orientation '${orientation}'`);
             }
         },
-    }, [orientation, isDragEnabled]);
-    useTimeout(() => handleIndexChange((index + items.length + 1) % items.length), (isPointerDown || autoAdvanceInterval <= 0) ? -1 : autoAdvanceInterval, [isPointerDown, index, items.length]);
-    const fixedStyles = getFixedStyles({ isPointerDown, orientation });
-    return (_jsx("div", { ...props, ref: ref, role: 'region', onClick: event => handleClick(event), onPointerDown: event => handlePointerDown(event), onPointerLeave: event => handlePointerUp(event), onPointerUp: event => handlePointerUp(event), children: _jsx("div", { ref: viewportRef, style: styles(fixedStyles.viewport), children: _jsx(Each, { in: items, children: ({ style: itemStyle, ...itemProps }, idx) => (_jsx("div", { style: styles(fixedStyles.itemContainer), children: _jsx(ItemComponent, { "aria-hidden": idx !== index, exposure: tracksItemExposure ? exposures?.[idx] : undefined, style: styles(itemStyle, fixedStyles.item), ...itemProps }) })) }) }) }));
+    }, [isDragEnabled, items.length, orientation]);
+    useTimeout((isPointerDown || !shouldAutoAdvance) ? -1 : autoAdvanceInterval, {
+        onTimeout: () => {
+            const nextIndex = (index + items.length + 1) % items.length;
+            handleIndexChange(nextIndex);
+        },
+    }, [autoAdvanceInterval, isPointerDown, index, items.length, shouldAutoAdvance, handleIndexChange]);
+    return (_jsx("div", { ...props, ref: ref, role: 'region', onClick: event => handleClick(event), onPointerCancel: event => handlePointerUp(event), onPointerDown: event => handlePointerDown(event), onPointerLeave: event => handlePointerUp(event), onPointerUp: event => handlePointerUp(event), children: _jsx("div", { ref: viewportRef, style: styles(fixedStyles.viewport), children: _jsx(Each, { in: items, children: ({ style: itemStyle, ...itemProps }, idx) => (_jsx("div", { style: styles(fixedStyles.itemContainer), children: _jsx(ItemComponent, { "aria-hidden": idx !== index, exposure: tracksItemExposure ? exposures?.[idx] : undefined, style: styles(itemStyle, fixedStyles.item), ...itemProps }) })) }) }) }));
 });
-function getFixedStyles({ isPointerDown = false, orientation = 'horizontal' }) {
+function scrollToIndex(ref, index, orientation) {
+    const viewport = ref.current;
+    if (!viewport)
+        return;
+    const top = orientation === 'horizontal' ? 0 : viewport.clientHeight * index;
+    const left = orientation === 'horizontal' ? viewport.clientWidth * index : 0;
+    if (viewport.scrollTop === top && viewport.scrollLeft === left)
+        return;
+    viewport.scrollTo({ top, left, behavior: 'smooth' });
+}
+function getItemExposures(ref, orientation) {
+    const viewport = ref.current;
+    if (!viewport)
+        return undefined;
+    const exposures = [];
+    for (let i = 0; i < viewport.children.length; i++) {
+        exposures.push(getItemExposureAt(i, ref, orientation));
+    }
+    return exposures;
+}
+function getItemExposureAt(idx, ref, orientation) {
+    const viewport = ref.current;
+    const child = viewport?.children[idx];
+    if (!child)
+        return 0;
+    const intersection = Rect.intersecting(child, viewport);
+    if (!intersection)
+        return 0;
+    switch (orientation) {
+        case 'horizontal':
+            return Math.max(0, Math.min(1, Math.round((intersection.width / viewport.clientWidth + Number.EPSILON) * 1000) / 1000));
+        case 'vertical':
+            return Math.max(0, Math.min(1, Math.round((intersection.height / viewport.clientHeight + Number.EPSILON) * 1000) / 1000));
+        default:
+            throw new Error(`Unsupported orientation '${orientation}'`);
+    }
+}
+function getFixedStyles({ scrollSnapEnabled = false, orientation = 'horizontal' }) {
     return asStyleDict({
         viewport: {
             alignItems: 'center',
             display: 'flex',
             height: '100%',
-            userSelect: isPointerDown ? 'none' : 'auto',
+            userSelect: scrollSnapEnabled ? 'auto' : 'none',
             justifyContent: 'flex-start',
-            scrollBehavior: isPointerDown ? 'auto' : 'smooth',
-            scrollSnapStop: isPointerDown ? 'unset' : 'always',
+            scrollBehavior: scrollSnapEnabled ? 'smooth' : 'auto',
+            scrollSnapStop: scrollSnapEnabled ? 'always' : 'unset',
             WebkitOverflowScrolling: 'touch',
             width: '100%',
             ...orientation === 'horizontal' ? {
                 flexDirection: 'row',
                 overflowX: 'scroll',
                 overflowY: 'hidden',
-                scrollSnapType: isPointerDown ? 'none' : 'x mandatory',
+                scrollSnapType: scrollSnapEnabled ? 'x mandatory' : 'none',
             } : {
                 flexDirection: 'column',
                 overflowX: 'hidden',
                 overflowY: 'scroll',
-                scrollSnapType: isPointerDown ? 'none' : 'y mandatory',
+                scrollSnapType: scrollSnapEnabled ? 'y mandatory' : 'none',
             },
         },
         itemContainer: {
             height: '100%',
             overflow: 'hidden',
-            scrollSnapAlign: 'start',
+            scrollSnapAlign: 'center',
             width: '100%',
-            scrollBehavior: 'smooth',
             flex: '0 0 auto',
         },
         item: {

package/components/Dropdown.js

@@ -53,7 +53,7 @@ export const Dropdown = forwardRef(({ children, className, style, collapsesOnSel
     const numItems = items.length;
     const numVisibleItems = maxVisibleItems < 0 ? numItems : Math.min(numItems, maxVisibleItems);
     const menuLength = itemLength * numVisibleItems + itemPadding * (numVisibleItems - 1);
-    const fixedStyles = getFixedStyles({ isCollapsed, isInverted, maxVisibleItems, menuLength, numItems, orientation });
+    const fixedStyles = getFixedStyles({ isCollapsed, collectionPadding, isInverted, maxVisibleItems, menuLength, numItems, orientation });
     const components = asComponentDict(children, {
         collapseIcon: DropdownCollapseIcon,
         expandIcon: DropdownExpandIcon,

package/hooks/useTimeout.d.ts

@@ -1,10 +1,12 @@
-import { type DependencyList } from 'react';
-/**
- * Hoook for invoking a method after a set timeout.
- *
- * @param handler The method to invoke.
- * @param timeout Time (in milliseconds) for the timeout. If the value is
- *                `undefined` or less than 0, the timeout is disabled.
- * @param deps Dependencies that trigger this effect.
- */
-export declare function useTimeout(handler: () => void, timeout?: number, deps?: DependencyList): void;
+import { type DependencyList, type RefObject } from 'react';
+type Options = {
+    autoStart?: boolean;
+    onTimeout?: () => void;
+};
+type ReturnValue = {
+    start: () => void;
+    stop: () => void;
+    ref: RefObject<NodeJS.Timeout | undefined>;
+};
+export declare function useTimeout(timeout?: number, { autoStart, onTimeout }?: Options, deps?: DependencyList): ReturnValue;
+export {};

package/hooks/useTimeout.js

@@ -1,21 +1,29 @@
-import { useEffect, useRef } from 'react';
-/**
- * Hoook for invoking a method after a set timeout.
- *
- * @param handler The method to invoke.
- * @param timeout Time (in milliseconds) for the timeout. If the value is
- *                `undefined` or less than 0, the timeout is disabled.
- * @param deps Dependencies that trigger this effect.
- */
-export function useTimeout(handler, timeout, deps = []) {
+import { useCallback, useEffect, useRef } from 'react';
+export function useTimeout(timeout = 0, { autoStart = true, onTimeout } = {}, deps = []) {
+    const timeoutRef = useRef();
     const handlerRef = useRef();
+    const start = useCallback(() => {
+        stop();
+        if (timeout < 0)
+            return;
+        timeoutRef.current = setTimeout(() => {
+            stop();
+            handlerRef.current?.();
+        }, timeout);
+    }, [timeout]);
+    const stop = useCallback(() => {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = undefined;
+    }, []);
     useEffect(() => {
-        handlerRef.current = handler;
-    }, [handler]);
+        handlerRef.current = onTimeout;
+    }, [onTimeout]);
     useEffect(() => {
-        if (timeout === undefined || timeout < 0)
+        if (timeout < 0)
             return;
-        const timer = window.setTimeout(() => handlerRef.current?.(), timeout);
-        return () => clearTimeout(timer);
+        if (autoStart)
+            start();
+        return () => stop();
     }, [timeout, ...deps]);
+    return { start, stop, ref: timeoutRef };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "etudes",
-  "version": "6.2.0",
+  "version": "6.2.2",
   "description": "A study of headless React components",
   "type": "module",
   "scripts": {