@os-design/use-auto-scroll 1.0.11 → 1.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@os-design/use-auto-scroll",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "license": "UNLICENSED",
   "repository": "git@gitlab.com:os-team/libs/os-design.git",
   "main": "dist/cjs/index.js",
@@ -14,7 +14,14 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/__tests__",
+    "!**/*.stories.tsx",
+    "!**/*.stories.mdx",
+    "!**/*.example.tsx"
   ],
   "sideEffects": false,
   "scripts": {
@@ -29,10 +36,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@os-design/use-cursor-position": "^1.0.10"
+    "@os-design/use-cursor-position": "^1.0.12"
   },
   "peerDependencies": {
     "react": ">=18"
   },
-  "gitHead": "0e88d3afc41e36cee61222a039ef1aa4d08115b5"
+  "gitHead": "e5d8409760608145d2c738aa5789d0465ae5416f"
 }

package/src/index.ts

@@ -0,0 +1,216 @@
+import useCursorPosition from '@os-design/use-cursor-position';
+import { useCallback, useEffect, useRef } from 'react';
+
+const FPS = 60;
+const FRAME_TIMEOUT = 1000 / FPS;
+
+export interface UseAutoScrollProps {
+  /**
+   * Whether the auto scroll is enabled.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * The distance to the border at which the container starts to scroll automatically (in percent).
+   * @default 20
+   */
+  distPercent?: number;
+  /**
+   * The max auto scroll speed (in px).
+   * @default 100
+   */
+  maxSpeedPx?: number;
+}
+
+const getProps = (props: UseAutoScrollProps): Required<UseAutoScrollProps> => ({
+  enabled: props.enabled !== undefined ? props.enabled : true,
+  distPercent: 20,
+  maxSpeedPx: 100,
+});
+
+const getRect = (el: Element) => {
+  if (el === document.body) {
+    return {
+      x: 0,
+      y: 0,
+      width: window.innerWidth,
+      height: window.innerHeight,
+    };
+  }
+  const rect = el.getBoundingClientRect();
+  return {
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height,
+  };
+};
+
+/**
+ * Detects whether the element is scrollable.
+ */
+const isScrollable = (el: Element) => {
+  const style = getComputedStyle(el);
+  if (
+    el !== document.body &&
+    !/(auto|scroll)/.test(style.overflow + style.overflowY + style.overflowX)
+  ) {
+    return false;
+  }
+  const { width, height } = getRect(el);
+  return el.scrollWidth > width || el.scrollHeight > height;
+};
+
+/**
+ * Returns an array of the scrollable elements located under the specified coordinates. The first one is the topmost.
+ */
+export const getScrollableElements = (x: number, y: number): Element[] => {
+  const elementsFromPoint = document.elementsFromPoint(x, y);
+  const elements: Element[] = [];
+  // eslint-disable-next-line no-restricted-syntax
+  for (const element of elementsFromPoint) {
+    const el = element === document.documentElement ? document.body : element;
+    if (isScrollable(el)) {
+      elements.push(el);
+    }
+    if (el === document.body) break;
+  }
+  return elements;
+};
+
+const getScrollOffset = (el: Element) => {
+  if (el === document.body) {
+    return {
+      scrollLeft: window.scrollX,
+      scrollTop: window.scrollY,
+    };
+  }
+  return {
+    scrollLeft: el.scrollLeft,
+    scrollTop: el.scrollTop,
+  };
+};
+
+const useAutoScroll = (props: UseAutoScrollProps = {}) => {
+  const cursorPosition = useCursorPosition();
+  const cursorPositionRef = useRef(cursorPosition);
+  const propsRef = useRef<Required<UseAutoScrollProps>>(getProps(props));
+  const isScrollingRef = useRef(false);
+  const frameRef = useRef<number>();
+  const timeoutRef = useRef<NodeJS.Timeout>();
+
+  // Update the ref to the cursor position if it changes
+  useEffect(() => {
+    cursorPositionRef.current = cursorPosition;
+  }, [cursorPosition]);
+
+  // Update the props if it changes
+  useEffect(() => {
+    propsRef.current = getProps(props);
+  }, [props]);
+
+  // Cancel the animation frame request and clear the timeout if the component was unmounted
+  useEffect(
+    () => () => {
+      if (frameRef.current) window.cancelAnimationFrame(frameRef.current);
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    },
+    []
+  );
+
+  // Returns the max distance from the border of the specified element at which auto scrolling is enabled (in px)
+  const getMaxDist = useCallback((el: Element, axis: 'x' | 'y') => {
+    const { distPercent } = propsRef.current;
+    const { width, height } = getRect(el);
+    const size = axis === 'x' ? width : height;
+    return Math.round((size * distPercent) / 100);
+  }, []);
+
+  // Returns the distance by which the scroll position should be changed
+  const getScrollStep = useCallback((dist: number, maxDist: number) => {
+    if (dist < 0 || dist > maxDist) return 0;
+    const { maxSpeedPx } = propsRef.current;
+    const divisor = maxDist / Math.log(maxSpeedPx);
+    return Math.round(Math.exp((maxDist - dist) / divisor));
+  }, []);
+
+  // Scrolls the element to the specified position
+  const scrollTo = useCallback((element: Element, options: ScrollToOptions) => {
+    frameRef.current = window.requestAnimationFrame(() => {
+      const el = element === document.body ? window : element;
+      el.scrollTo(options);
+    });
+  }, []);
+
+  const scroll = useCallback(() => {
+    const { enabled } = propsRef.current;
+    const { x, y } = cursorPositionRef.current;
+    const scrollableElements = getScrollableElements(x, y).reverse();
+
+    if (!enabled) {
+      isScrollingRef.current = false;
+      return;
+    }
+
+    isScrollingRef.current = true;
+
+    // eslint-disable-next-line no-restricted-syntax
+    for (const el of scrollableElements) {
+      const rect = getRect(el);
+      const { scrollLeft, scrollTop } = getScrollOffset(el);
+
+      const xMaxDist = getMaxDist(el, 'x');
+      const yMaxDist = getMaxDist(el, 'y');
+
+      const leftDist = x - rect.x;
+      const topDist = y - rect.y;
+      const rightDist = rect.x + rect.width - x;
+      const bottomDist = rect.y + rect.height - y;
+
+      const leftScrollStep = getScrollStep(leftDist, xMaxDist);
+      const topScrollStep = getScrollStep(topDist, yMaxDist);
+      const rightScrollStep = getScrollStep(rightDist, xMaxDist);
+      const bottomScrollStep = getScrollStep(bottomDist, yMaxDist);
+
+      const canScrollLeft = scrollLeft > 0;
+      const canScrollTop = scrollTop > 0;
+      const canScrollRight = el.scrollWidth - scrollLeft > rect.width;
+      const canScrollBottom = el.scrollHeight - scrollTop > rect.height;
+
+      let left = scrollLeft;
+      if (canScrollLeft && leftScrollStep > 0) {
+        left = Math.max(scrollLeft - leftScrollStep, 0);
+      } else if (canScrollRight && rightScrollStep > 0) {
+        left = Math.min(
+          scrollLeft + rightScrollStep,
+          el.scrollWidth - rect.width
+        );
+      }
+
+      let top = scrollTop;
+      if (canScrollTop && topScrollStep > 0) {
+        top = Math.max(scrollTop - topScrollStep, 0);
+      } else if (canScrollBottom && bottomScrollStep > 0) {
+        top = Math.min(
+          scrollTop + bottomScrollStep,
+          el.scrollHeight - rect.height
+        );
+      }
+
+      if (left !== scrollLeft || top !== scrollTop) {
+        scrollTo(el, { left, top });
+        timeoutRef.current = setTimeout(scroll, FRAME_TIMEOUT);
+        return;
+      }
+    }
+
+    isScrollingRef.current = false;
+  }, [getMaxDist, getScrollStep, scrollTo]);
+
+  // Start auto scrolling when the cursor position changes only if it is not already running
+  useEffect(() => {
+    if (!isScrollingRef.current && props.enabled) scroll();
+  }, [scroll, cursorPosition, props.enabled]);
+};
+
+export default useAutoScroll;