feat(API): deprecated scrollToPage

Author: ron0115

README.md

@@ -2,7 +2,7 @@
 
 The `useSmoothScroll` hook finish smooth scroll behaviour in react component by `requestAnimationFrame`.
 
-**Examples are <a target="_blank" href="https://ron0115.best/react-smooth-scroll-hook/?path=/docs/usesmoothscroll--docs#basic" >Here</a>.**(Storybook)
+**Examples are <a target="_blank" href="https://ron0115.best/react-smooth-scroll-hook/?path=/docs/hook-usesmoothscroll--docs" >Here</a>.**(Storybook)
 
 **Live demo is <a target="_blank" href="https://codesandbox.io/s/reverent-cerf-ks4xh?file=/index.tsx" >Here</a>.**(Codesandbox)
 
@@ -20,7 +20,9 @@ The `useSmoothScroll` hook finish smooth scroll behaviour in react component by
 npm install react-smooth-scroll-hook
 ```
 
-## Basic Usage
+## useSmoothScroll
+
+### Basic Usage
 
 ```tsx
 import React, { useRef } from 'react';
@@ -62,27 +64,96 @@ export const Demo = () => {
 };
 ```
 
-## Props
+### Props
 
-- **ref:** `RefObject<HTMLElement>`, container which set as `overflow: scroll`.
+- **ref:** `RefObject<HTMLElement>`, container which set as `overflow: scroll`, if scroll whole document, pass `ref = useRef(document.documentElement)` or `useRef(document.body)`.
 - **speed:** Distance in one frame to move in `requestAnimationFrame` mode, defaults to `100`, if not provide, speed depends on native API `scrollTo`.
 - **direction:** Scroll direction, `x` for horizontal or `y` for vertical.
 - **threshold:** Judge scroll is finished has an error range, .defaults to `1`.
 
-### Returns of Hook
+#### Returns of Hook
 
 - **scrollTo** `(string|number) => void`
 
   - Pass `number`: the distance to scroll, e.g. `scrollTo(400)`
   - Pass `string`: the element seletor you want to scrollTo, meanwhile passing to `document.querySelector`, e.g. `scrollTo('#your-dom-id')`
 
-- **reachTop** `boolean`: Whether it has reached the top of refContainer
+- **reachedTop** `boolean`: Whether it has reached the top of refContainer
 
-- **reachBottom** `boolean`: Whether it has reached the bottom of refContainer
+- **reachedBottom** `boolean`: Whether it has reached the bottom of refContainer
 
 - **scrollToPage** `(number) => void`: Pass page(`number`), which scroll to a distance as multiples of container size(`offsetWidth`/`offsetHeight`)
   .e.g `scrollToPage(1)`,`scrollToPage(-1)`
 
 - **refreshState** `() => void`: Manually refresh the state of `reachTop` and `reachBottom`, possibly useful in some situation.
 
 - **refreshSize** `() => void`: Manually refresh the size of ref container, possibly useful in some situation.
+
+## useScrollWatch
+
+Proviede a `list` of dom like below, and pass the parent container `ref` to hook, it return the scrollbar current state of `scrollTop`, `curIndex`, `curItem`.
+
+```tsx
+export const ScrollConatainerMode = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  const { scrollTop, curIndex, curItem } = useScrollWatch({
+    ref,
+    list: [
+      {
+        href: '#item-0',
+      },
+      {
+        href: '#item-10',
+      },
+      {
+        href: '#item-20',
+      },
+    ],
+  });
+  return (
+    <>
+      <h2>Scroll Container Mode</h2>
+      <div>
+        <p>
+          <strong>scrollTop:</strong> {scrollTop}
+        </p>
+        <p>
+          <strong>curIndex:</strong> {curIndex}
+        </p>
+        <p>
+          <strong>curHref:</strong> {curItem?.href}
+        </p>
+      </div>
+      <div
+        style={{
+          padding: '10px',
+          maxHeight: '200px',
+          overflowY: 'scroll',
+        }}
+        ref={ref}
+      >
+        {Array(100)
+          .fill(null)
+          .map((_item, i) => (
+            <div key={i} id={`item-${i}`}>
+              item-{i}
+            </div>
+          ))}
+      </div>
+    </>
+  );
+};
+```
+
+> Click <a href="https://ron0115.best/react-smooth-scroll-hook/?path=/docs/hook-usescrollwatch--docs" target="_blank">Here</a> to know more and see Demo.
+
+### Props
+
+- **list** `Array({href, offset})`: `href` is elemet selector string, which passing to `querySelector`, such as `#element-id`
+- **ref**: the same as ref of `useSmoothScroll`
+
+### Returns of Hook
+
+- **scrollTop** `number`: current scrollTop of scroll container.
+- **curIndex** `number`: current Index of list
+- **curItem** `{href, offset}`: current Item of list

example/DirectionX.stories.tsx

@@ -4,7 +4,12 @@ import useSmoothScroll from 'react-smooth-scroll-hook';
 export const DirectionX = () => {
   const [speed, setSpeed] = useState(200);
   const ref = useRef<HTMLDivElement>(null);
-  const { scrollTo, reachTop, reachBottom, scrollToPage } = useSmoothScroll({
+  const {
+    scrollTo,
+    reachedTop,
+    reachedBottom,
+    containerSize,
+  } = useSmoothScroll({
     ref,
     direction: 'x',
     speed,
@@ -50,18 +55,21 @@ export const DirectionX = () => {
       <br />
       <strong>
         Scroll to Page:
-        <button disabled={reachBottom} onClick={() => scrollToPage(1)}>
-          scrollToPage(1)
+        <button
+          disabled={reachedBottom}
+          onClick={() => scrollTo(containerSize)}
+        >
+          scrollTo(containerSize)
         </button>
-        <button disabled={reachTop} onClick={() => scrollToPage(-1)}>
-          scrollToPage(-1)
+        <button disabled={reachedTop} onClick={() => scrollTo(-containerSize)}>
+          scrollTo(-containerSize)
         </button>
       </strong>
       <br />
       <br />
-      reachTop: {String(reachTop)}
+      reachedTop: {String(reachedTop)}
       <br />
-      reachBottom: {String(reachBottom)}
+      reachedBottom: {String(reachedBottom)}
       <br />
       <div
         ref={ref}

src/useScrollWatch.ts

@@ -6,16 +6,18 @@ import {
   isWindowScrollParent,
 } from './utils';
 
-type ListType = {
-  href: string;
-  offset?: number;
-}[];
-
 export type useScrollWathType = {
-  /** the container dom RefObject which use `overflow:scroll` */
+  /** the container dom RefObject which use `overflow:scroll`,if scroll whole document, pass `ref = useRef(document.documentElement)` or `useRef(document.body)`. */
   ref: React.RefObject<HTMLElement>;
-  list: ListType;
+  list: {
+    /** dom id of Element */
+    href: string;
+    /** the scroll position judge preset of each Element */
+    offset?: number;
+  }[];
+  /** global offset for every Element of list */
   offset?: number;
+  /** scroll axis, x for horizontal, y for vertical */
   direction?: DirectionType;
 };
 
@@ -74,7 +76,7 @@ export const useScrollWatch = (props: useScrollWathType) => {
 
   useEffect(() => {
     refresh();
-  }, [ref]);
+  }, [ref, refresh]);
 
   const curIndex = getCurIndex(scrollTop, posList);
 
@@ -91,7 +93,7 @@ export const useScrollWatch = (props: useScrollWathType) => {
       observer.disconnect();
       elm && elm.removeEventListener('scroll', refresh);
     };
-  }, [ref]);
+  }, [ref, refresh]);
 
   return {
     curIndex,

src/useSmoothScroll.tsx

@@ -10,12 +10,13 @@ import {
 } from './utils';
 
 export type UseSmoothScrollType = {
-  /** the container dom RefObject which use `overflow:scroll` */
+  /** the container dom RefObject which use `overflow:scroll`, if scroll whole document, pass `ref = useRef(document.documentElement)` or `useRef(document.body)`. */
   ref: React.RefObject<HTMLElement>;
   /** distance per frame, reflects to speed while scrolling */
   speed?: number;
   /** scroll direction, you can use 'x` for vertical, 'y` for horizontal */
   direction?: DirectionType;
+  /** allowable distance beteween nowable state the judgement edge */
   threshold?: number;
 };
 
@@ -56,8 +57,8 @@ export const useSmoothScroll = ({
 }: UseSmoothScrollType) => {
   const attrMap = getAttrMap(direction);
 
-  const [reachTop, setReachTop] = useState(true);
-  const [reachBottom, setReachBottom] = useState(true);
+  const [reachedTop, setReachedTop] = useState(true);
+  const [reachedBottom, setReachedBottom] = useState(true);
   const [size, setSize] = useState(0);
 
   const isTopEdge = () => {
@@ -86,8 +87,8 @@ export const useSmoothScroll = ({
   });
 
   const refreshState = debounce((_evt: Event) => {
-    isTopEdge() ? setReachTop(true) : setReachTop(false);
-    isBottomEdge() ? setReachBottom(true) : setReachBottom(false);
+    isTopEdge() ? setReachedTop(true) : setReachedTop(false);
+    isBottomEdge() ? setReachedBottom(true) : setReachedBottom(false);
   });
 
   const scrollTo = (target?: number | string, offset?: number) => {
@@ -194,18 +195,21 @@ export const useSmoothScroll = ({
       observer.disconnect();
       elm && elm.removeEventListener('scroll', refreshState);
     };
-  }, [ref]);
+  }, [ref, refreshState]);
 
   return {
-    reachTop,
-    reachBottom,
+    reachedTop,
+    reachedBottom,
+    containerSize: size,
     scrollTo,
+    /** @deprecated replace with scrollTo(n * containerSize) */
     scrollToPage: (page: number) => {
       scrollTo(page * size);
     },
+    /** @deprecated */
     refreshState,
+    /** @deprecated */
     refreshSize,
   };
 };
-
 export default useSmoothScroll;

stories/useScrollWath.stories.tsx

@@ -3,7 +3,7 @@ import { useScrollWatch } from '../src/index';
 import './index.css';
 
 export default {
-  title: 'hook/useScrollWatch',
+  title: 'More/useScrollWatch',
   component: useScrollWatch,
 };
 
@@ -19,7 +19,7 @@ export const Docs = () => {
 export { WindowMode, ScrollConatainerMode, DirectionX };
 
 // @ts-ignore
-WindowMode.storyName = 'Body Parent';
+WindowMode.storyName = 'Window Parent Mode';
 // @ts-ignore
 ScrollConatainerMode.storyName = 'ScrollConatainer Mode';
 // @ts-ignore

stories/useSmoothScroll.stories.tsx

@@ -4,7 +4,7 @@ import useSmoothScroll from '../src/index';
 import './index.css';
 
 export default {
-  title: 'hook/useSmoothScroll',
+  title: 'Main/useSmoothScroll',
   component: useSmoothScroll,
 };
 import { Demo } from '../example/Demo.stories';