feat: add JSDoc to the app

Also, update the Readme.md file.

Author: SMAKSS

Readme.md

@@ -1,61 +1,65 @@
-# Detect react scroll direction
+# React Scroll Direction Hook
 
 ![npm](https://img.shields.io/npm/v/@smakss/react-scroll-direction) ![Snyk Vulnerabilities for npm package](https://img.shields.io/snyk/vulnerabilities/npm/@smakss/react-scroll-direction) ![NPM](https://img.shields.io/npm/l/@smakss/react-scroll-direction) ![npm](https://img.shields.io/npm/dt/@smakss/react-scroll-direction) ![npm bundle size (scoped)](https://img.shields.io/bundlephobia/min/@smakss/react-scroll-direction)
 
-This is a custom hook for react which is useful to detect scroll direction in React applications in an efficient way with a custom threshold.
+Detect scroll direction in your React applications effortlessly using `@smakss/react-scroll-direction`, a custom React Hook with an adjustable threshold.
 
-This package is created on behalf of a [StackOverflow answer](https://stackoverflow.com/a/62497293/11908502) which draws some attention to itself, so if someone just wants something to work with right away, they can access it easily here.
+This package was inspired by a [popular StackOverflow answer](https://stackoverflow.com/a/62497293/11908502), crafted to be a ready-to-use solution for detecting scroll direction in your React applications.
 
 ## Demo
 
+Click the button below to view a demo on CodeSandbox:
+
 [![View @smakss/search](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/react-scroll-direction-tclwvp?fontsize=14&hidenavigation=1&theme=dark)
 
-## How it works?
+## Installation
 
-To install it you can simply do the following command:
+Install the package using npm or yarn:
 
 ```bash
-npm i @smakss/react-scroll-direction
-or
+npm install @smakss/react-scroll-direction
+# or
 yarn add @smakss/react-scroll-direction
 ```
 
-to include it with common js module you should do this:
+To include it in your project, use:
+
+CommonJS:
 
 ```js
-var { useDetectScroll } = require("@smakss/react-scroll-direction");
+const { useDetectScroll } = require("@smakss/react-scroll-direction");
 ```
 
-and to include it with ECMAscript module you can simply do this one:
+ES Module:
 
 ```js
 import { useDetectScroll } from "@smakss/react-scroll-direction";
 ```
 
-then to use it within your application you can do it just like below:
+## Usage
 
-The useDetectScroll custom hook will accept 3 input parameter:
+The `useDetectScroll` custom hook accepts an options object with the following properties:
 
-- `thr` (`number`): A number to indicate the threshold of firing scroll direction event, which is `0` by default and only accepts a positive numeric value. If it gets a higher value the steps will be longer.
-- `axis` (`string`): Indicate the page scroll axis, whether, in the `y` or `x` axes, it is `y` by default.
-- `scrollUp` (`string`): A string value for the output of the custom hook if the scroll direction is upward. The default value is `up` if the axis is `y` and `left` if the axis is `x`.
-- `scrollDown` (`string`): A string value for the output of the custom hook if the scroll direction is downward. The default value is `down` if the axis is `y` and `right` if the axis is `x`.
-- `still` (`string`): default value for the direction when there is no scrolling happening on the page. The default value is `still`.
+- `thr`: Threshold to trigger scroll direction change (default: `0`, only accepts positive values).
+- `axis`: Scroll axis (`"y"` or `"x"`, default: `"y"`).
+- `scrollUp`: Output value when scrolling up or left (default: `"up"` for y-axis, `"left"` for x-axis).
+- `scrollDown`: Output value when scrolling down or right (default: `"down"` for y-axis, `"right"` for x-axis).
+- `still`: Output value when no scrolling is detected (default: `"still"`).
 
-## Examples of usage
+## Examples
 
-### If the scroll goes upward/downward
+Detecting scroll up/down:
 
 ```js
-const [scrollDir] = useDetectScroll({});
+const scrollDir = useDetectScroll({});
 
-// scrollDir: "up"/"down"
+// Outputs: "up", "down", or "still"
 ```
 
-### If the scroll goes left/right
+Detecting scroll left/right:
 
 ```js
-const [scrollDir] = useDetectScroll({ axis: "x" });
+const scrollDir = useDetectScroll({ axis: "x" });
 
-// scrollDir: "left"/"right"
+// Outputs: "left", "right", or "still"
 ```

package.json

@@ -35,6 +35,7 @@
     "SMAKSS",
     "CommonJS",
     "EcmaScript",
+    "TypeScript",
     "detect scroll in react",
     "react scroll",
     "scroll direction"
@@ -56,5 +57,5 @@
     "lint:fix": "eslint src/**/*.ts --fix"
   },
   "type": "module",
-  "version": "1.1.0-beta"
+  "version": "1.1.0"
 }

src/hooks/useDetectScroll.ts

@@ -1,10 +1,12 @@
 import { useState, useEffect, useCallback } from "react";
 
+/** Enumeration for axis values */
 enum Axis {
   X = "x",
   Y = "y",
 }
 
+/** Enumeration for direction values */
 enum Direction {
   Up = "up",
   Down = "down",
@@ -13,15 +15,51 @@ enum Direction {
   Still = "still",
 }
 
+/** Type declaration for scroll properties */
 type ScrollProps = {
   thr?: number;
   axis?: Axis;
-  scrollUp?: string;
-  scrollDown?: string;
-  still?: string;
+  scrollUp?: Direction;
+  scrollDown?: Direction;
+  still?: Direction;
 };
 
-function useDetectScroll(props: ScrollProps) {
+/**
+ * useDetectScroll hook.
+ *
+ * This hook provides a mechanism to detect the scroll direction.
+ * It will return the scroll direction as a string (up, down, left, right, or still) based on user scrolling.
+ *
+ * @example
+ *
+ * import useDetectScroll, { Axis, Direction } from './useDetectScroll';
+ *
+ * function App() {
+ *   const scrollDirection = useDetectScroll({
+ *     thr: 100,
+ *     axis: Axis.Y,
+ *     scrollUp: Direction.Up,
+ *     scrollDown: Direction.Down,
+ *     still: Direction.Still
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <p>Current scroll direction: {scrollDirection}</p>
+ *     </div>
+ *   );
+ * }
+ *
+ * @param {ScrollProps} props - The properties related to scrolling.
+ * @property {number} props.thr - The threshold value which the scroll difference must exceed to update scroll direction.
+ * @property {Axis} props.axis - The axis along which to detect scroll. Can be 'x' or 'y'.
+ * @property {Direction} props.scrollUp - The direction to set when scrolling up or left. By default, 'up' for y-axis and 'left' for x-axis.
+ * @property {Direction} props.scrollDown - The direction to set when scrolling down or right. By default, 'down' for y-axis and 'right' for x-axis.
+ * @property {Direction} props.still - The direction to set when there is no scrolling. By default, 'still'.
+ *
+ * @returns {Direction} - The current direction of scrolling.
+ */
+function useDetectScroll(props: ScrollProps): Direction {
   const {
     thr = 0,
     axis = Axis.Y,
@@ -30,12 +68,13 @@ function useDetectScroll(props: ScrollProps) {
     still = Direction.Still,
   } = props;
 
-  const [scrollDir, setScrollDir] = useState(still);
+  const [scrollDir, setScrollDir] = useState<Direction>(still);
 
   const threshold = Math.max(0, thr);
   let ticking = false;
   let lastScroll: number = axis === Axis.Y ? window.scrollY : window.scrollX;
 
+  /** Function to update scroll direction */
   const updateScrollDir = useCallback(() => {
     const scroll = axis === Axis.Y ? window.scrollY : window.scrollX;
 
@@ -47,6 +86,7 @@ function useDetectScroll(props: ScrollProps) {
   }, [axis, threshold, scrollDown, scrollUp]);
 
   useEffect(() => {
+    /** Function to handle onScroll event */
     const onScroll = () => {
       if (!ticking) {
         window.requestAnimationFrame(updateScrollDir);
@@ -59,7 +99,7 @@ function useDetectScroll(props: ScrollProps) {
     return () => window.removeEventListener("scroll", onScroll);
   }, [updateScrollDir]);
 
-  return [scrollDir];
+  return scrollDir;
 }
 
 export default useDetectScroll;