feat: add generateEscapeScrollUpContext, for disbale auto scroll when user scroll up.

BREAKING CHANGE: 1. remove escapeHook, use context.escapeHook instead. 2. iife usage update: autoScroll.default, autoScroll.generateEscapeScrollUpContext

Author: Yrobot

README.md

@@ -28,12 +28,12 @@ import autoScroll from "@yrobot/auto-scroll";
 autoScroll({ selector: "#scroll-container-id" });
 ```
 
-## script
+## script - iife
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@yrobot/auto-scroll/build/index.iife.js"></script>
 <script>
-  autoScroll({ selector: "#scroll-container-id" });
+  autoScroll.default({ selector: "#scroll-container-id" });
 </script>
 ```
 
@@ -43,3 +43,27 @@ autoScroll({ selector: "#scroll-container-id" });
 
 - [✓] The subtree children list length increase
 - [✓] The direct child element height increase
+
+## Pack Up Useful Utilities Logic
+
+### Stop auto scroll when user scroll up
+
+> es
+
+```ts
+import autoScroll, { generateEscapeScrollUpContext } from "@yrobot/auto-scroll";
+
+autoScroll({
+  selector: "#scroll-container-id",
+  context: generateEscapeScrollUpContext(),
+});
+```
+
+> iife
+
+```ts
+autoScroll.default({
+  selector: "#scroll-container-id",
+  context: autoScroll.generateEscapeScrollUpContext(),
+});
+```

package/index.ts

@@ -25,37 +25,83 @@ const throttle = <R, A extends any[]>(
   ];
 };
 
+type OnUnmount = (elm: Element) => void;
+
+export type Context = {
+  escapeHook?: (elm: Element) => boolean;
+  onMount?: (elm: Element) => void | OnUnmount;
+  onUnmount?: OnUnmount;
+};
+
+/**
+ * Generates the context for escaping auto scroll down when user scroll up.
+ *
+ * @param {Object} config - The configs.
+ * @param {number} [config.threshold=24] - The threshold value for scroll up distance (default: 24).
+ * @param {number} [config.throttleTime=100] - The throttle time for scroll event (default: 100).
+ *
+ * @returns {Context} The generated context object. For autoScroll.param.context
+ */
+export function generateEscapeScrollUpContext({
+  threshold = 24,
+  throttleTime = 100,
+}: { threshold?: number; throttleTime?: number } = {}) {
+  const context: Context = {};
+  let isEscape = false;
+  const [onScroll] = throttle((evt: Event) => {
+    const target = evt.target as Element;
+    const scrollUpDistance =
+      target.scrollHeight - target.scrollTop - target.clientHeight;
+    isEscape = scrollUpDistance > threshold;
+  }, throttleTime);
+  context.onMount = (elm) => {
+    elm.addEventListener("scroll", onScroll);
+  };
+  context.onUnmount = (elm) => {
+    elm.removeEventListener("scroll", onScroll);
+  };
+  context.escapeHook = () => isEscape;
+  return context;
+}
+
 /**
  * @description auto scroll the selector dom to the bottom, when the size of the selector dom has been updated.
- * @author Yrobot <https://yrobot.top>
- * @date 12/01/2024
  *
  * @param {Object} options - The config options for the autoScroll function.
- * @param {string} [options.selector] - The selector for the container element. (example: '#container')
- * @param {EscapeHook} [options.escapeHook] - A function that determines whether scrolling should be escaped.
- * @param {number} [options.throttleTime] - The throttle time in milliseconds.
- * @param {number} [options.offset] - The offset for the scroll position based on the container.scrollHeight.
+ * @param {string} options.selector - The selector for the container element. (example: '#container')
+ * @param {Context} [options.context] - The context for the life cycle hooks of the autoScroll function. [escapeHook,onMount,onUnmount]
+ * @param {number} [options.throttleTime=100] - The throttle time in milliseconds.
+ * @param {number} [options.offset=0] - The offset for the scroll position based on the container.scrollHeight.
  *
  * @return {function} The unObserverCallback function.
+ *
+ * @example autoScroll({ selector: "#scroll-container-id" })
+ * @example autoScroll({ selector: "#scroll-container-id", context: generateEscapeScrollUpContext() })
  */
-function autoScroll({
+export default function autoScroll({
   selector,
-  escapeHook = (elm) => false,
   throttleTime = 100,
+  context,
   offset = 0,
 }: {
   selector: string;
-  escapeHook?: (elm: Element) => boolean;
   throttleTime?: number;
+  context?: Context;
   offset?: number;
 }): unObserverCallback {
   const container = document.querySelector(selector);
 
   if (container === null)
     throw new Error(`Element not found with selector [${selector}]`);
 
+  const returnOnUnmount = context?.onMount?.(container);
+
   const [scrollHook] = throttle(() => {
-    if (escapeHook(container)) return false;
+    if (
+      typeof context?.escapeHook === "function" &&
+      context.escapeHook(container)
+    )
+      return false;
     container.scrollTop = container.scrollHeight + offset;
     return true;
   }, throttleTime);
@@ -81,7 +127,8 @@ function autoScroll({
   return () => {
     resizeObserver.disconnect();
     mutationObserver.disconnect();
+    // unmount
+    returnOnUnmount?.(container);
+    context?.onUnmount?.(container);
   };
 }
-
-export default autoScroll;

website/index.css

@@ -7,13 +7,13 @@ body {
 }
 .panel {
   width: 400px;
-  padding: 24px;
 }
 .list-container {
+  box-sizing: border-box;
   border: 1px solid #000;
   padding: 8px;
   width: 100%;
-  height: 800px;
+  height: 600px;
   overflow: scroll;
   display: flex;
   flex-direction: column;
@@ -40,3 +40,13 @@ body {
   background-color: black;
   color: #fff;
 }
+
+.grid-table {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 64px;
+}
+
+code {
+  white-space: pre-wrap;
+}

website/index.tsx

@@ -1,50 +1,116 @@
-import React, { useEffect, useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 
-import autoScroll from "../package/index.ts";
+import autoScroll, { generateEscapeScrollUpContext } from "../package/index.ts";
 
 import "./index.css";
 
-function App() {
+const useDynamicList = ({ max = 999 }: { max?: number } = {}) => {
   const [list, setList] = useState<number[]>([]);
+  const dataRef = useRef({
+    len: 0,
+    max,
+  });
+  dataRef.current.len = list.length;
+  dataRef.current.max = max;
   useEffect(() => {
     const timeId = setInterval(() => {
-      if (list.length > 999) {
-        setList((list) => list.slice(0, 10));
-      } else {
+      if (dataRef.current.len < dataRef.current.max) {
         setList((list) => [...list, list.length + 1]);
       }
     }, 200);
     return () => {
       clearInterval(timeId);
     };
   }, []);
-  useEffect(() => autoScroll({ selector: "#list-container" }), []);
+  return list;
+};
+
+const codes = {
+  default: `
+import autoScroll from "@yrobot/auto-scroll";
+
+autoScroll({ selector: "#scroll-container-id" });`,
+  escapeScrollUp: `
+import autoScroll, { generateEscapeScrollUpContext } from "@yrobot/auto-scroll";
+
+autoScroll({
+  selector: "#scroll-container-id",
+  context: generateEscapeScrollUpContext(),
+});`,
+};
+
+const DefaultDemo = () => {
+  const list = useDynamicList();
+  useEffect(
+    () =>
+      autoScroll({
+        selector: "#default-list-container",
+      }),
+    []
+  );
   return (
     <div className="panel">
-      <div className="list-container" id="list-container">
-        {/* {list.map((id) => (
+      <h3>Default (auto scroll always)</h3>
+      <div className="list-container" id="default-list-container">
+        {list.map((id) => (
           <div className="item" key={id}>
             {id}
           </div>
-        ))} */}
+        ))}
         {/* <div>
           {list.map((id) => (
             <div className="item" key={id}>
               {id}
             </div>
           ))}
         </div> */}
-        <div
+        {/* <div
           className="item"
           style={{
             height: list.length * 100,
           }}
         >
           Height Update [{list.length * 100}px]
-        </div>
+        </div> */}
         <div className="loading">LOADING...</div>
       </div>
+      <code>{codes.default}</code>
+    </div>
+  );
+};
+
+const EscapeScrollUpDemo = () => {
+  const list = useDynamicList();
+  useEffect(
+    () =>
+      autoScroll({
+        selector: "#escape-scroll-up-list-container",
+        context: generateEscapeScrollUpContext(),
+      }),
+    []
+  );
+  return (
+    <div className="panel">
+      <h3>Stop Auto Scroll When User Scroll Up</h3>
+      <div className="list-container" id="escape-scroll-up-list-container">
+        {list.map((id) => (
+          <div className="item" key={id}>
+            {id}
+          </div>
+        ))}
+        <div className="loading">LOADING...</div>
+      </div>
+      <code>{codes.escapeScrollUp}</code>
+    </div>
+  );
+};
+
+function App() {
+  return (
+    <div className="grid-table">
+      <DefaultDemo />
+      <EscapeScrollUpDemo />
     </div>
   );
 }