Merge pull request #53 from SMAKSS/feature/migrate-to-ts

feat: change the project folder hierarchy

Author: SMAKSS

Readme.md

@@ -2,64 +2,73 @@
 
 ![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)
 
-Detect scroll direction in your React applications effortlessly using `@smakss/react-scroll-direction`, a custom React Hook with an adjustable threshold.
+`@smakss/react-scroll-direction` is a versatile, lightweight React hook that detects scroll direction in your application with ease. You can fine-tune its sensitivity using an adjustable threshold, catering to your application's unique needs.
 
-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.
+This package originated from a [popular StackOverflow response](https://stackoverflow.com/a/62497293/11908502) and has been developed further into a ready-to-implement solution for managing scroll direction detection in your React applications.
 
 ## Demo
 
-Click the button below to view a demo on CodeSandbox:
+Experience `@smakss/react-scroll-direction` in action 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)
 
 ## Installation
 
-Install the package using npm or yarn:
+Install `@smakss/react-scroll-direction` via npm or yarn:
 
 ```bash
 npm install @smakss/react-scroll-direction
 # or
 yarn add @smakss/react-scroll-direction
 ```
 
-To include it in your project, use:
+Then, import it into your project:
 
 CommonJS:
 
 ```js
-const { useDetectScroll } = require("@smakss/react-scroll-direction");
+const useDetectScroll = require("@smakss/react-scroll-direction");
 ```
 
 ES Module:
 
 ```js
-import { useDetectScroll } from "@smakss/react-scroll-direction";
+import useDetectScroll from "@smakss/react-scroll-direction";
+```
+
+For TypeScript projects, import the hook and its types:
+
+```ts
+import useDetectScroll, {
+  Axis,
+  Direction,
+} from "@smakss/react-scroll-direction";
 ```
 
 ## Usage
 
-The `useDetectScroll` custom hook accepts an options object with the following properties:
+The `useDetectScroll` hook takes an options object that can include the following properties:
 
-- `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"`).
+- `thr`: Threshold for scroll direction change detection (default: `0`, accepts only positive values).
+- `axis`: Defines the scroll axis (`"y"` or `"x"`, default: `"y"`).
+- `scrollUp`: Value returned when scrolling up (y-axis) or left (x-axis) (default: `"up"` for y-axis, `"left"` for x-axis).
+- `scrollDown`: Value returned when scrolling down (y-axis) or right (x-axis) (default: `"down"` for y-axis, `"right"` for x-axis).
+- `still`: Value returned when there's no scrolling activity (default: `"still"`).
 
 ## Examples
 
-Detecting scroll up/down:
+To detect upward or downward scroll:
 
 ```js
 const scrollDir = useDetectScroll({});
 
-// Outputs: "up", "down", or "still"
+// Returns: "up", "down", or "still"
 ```
 
-Detecting scroll left/right:
+To detect left or right scroll:
 
 ```js
 const scrollDir = useDetectScroll({ axis: "x" });
 
-// Outputs: "left", "right", or "still"
+// Returns: "left", "right", or "still"
 ```

package.json

@@ -57,5 +57,5 @@
     "lint:fix": "eslint src/**/*.ts --fix"
   },
   "type": "module",
-  "version": "2.0.0"
+  "version": "2.1.0"
 }

src/hooks/index.ts

@@ -1 +1,105 @@
-export * from "./hooks";
+import { useState, useEffect, useCallback } from "react";
+
+/** Enumeration for axis values */
+export enum Axis {
+  X = "x",
+  Y = "y",
+}
+
+/** Enumeration for direction values */
+export enum Direction {
+  Up = "up",
+  Down = "down",
+  Left = "left",
+  Right = "right",
+  Still = "still",
+}
+
+/** Type declaration for scroll properties */
+type ScrollProps = {
+  thr?: number;
+  axis?: Axis;
+  scrollUp?: Direction;
+  scrollDown?: Direction;
+  still?: Direction;
+};
+
+/**
+ * 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 '@smakss/react-scroll-direction';
+ *
+ * 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,
+    scrollUp = axis === Axis.Y ? Direction.Up : Direction.Left,
+    scrollDown = axis === Axis.Y ? Direction.Down : Direction.Right,
+    still = Direction.Still,
+  } = props;
+
+  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;
+
+    if (Math.abs(scroll - lastScroll) >= threshold) {
+      setScrollDir(scroll > lastScroll ? scrollDown : scrollUp);
+      lastScroll = Math.max(0, scroll);
+    }
+    ticking = false;
+  }, [axis, threshold, scrollDown, scrollUp]);
+
+  useEffect(() => {
+    /** Function to handle onScroll event */
+    const onScroll = () => {
+      if (!ticking) {
+        window.requestAnimationFrame(updateScrollDir);
+        ticking = true;
+      }
+    };
+
+    window.addEventListener("scroll", onScroll);
+
+    return () => window.removeEventListener("scroll", onScroll);
+  }, [updateScrollDir]);
+
+  return scrollDir;
+}
+
+export default useDetectScroll;