Hook: useScrollTop (#8254)

* feat: New useScrollTop hook

* feat: useScrollTop docs added

Author: tugcekucukoglu

apps/showcase/demo/usescrolltop/basic-demo.tsx

@@ -0,0 +1,18 @@
+import { useScrollTop } from '@primereact/hooks';
+import { Button } from 'primereact/button';
+
+export default function BasicDemo() {
+    const { scrollToTop, visible } = useScrollTop();
+
+    return (
+        <div className="card flex flex-col items-center">
+            <p>Scroll down the page to display the ScrollTop component.</p>
+            <i className="pi pi-angle-down animate-fadeout animate-duration-1000 animate-infinite text-[2rem] mb-[30rem]"></i>
+            {visible && (
+                <Button onClick={scrollToTop} iconOnly rounded className="fixed [inset-block-end:20px] [inset-inline-end:20px]">
+                    <i className="pi pi-chevron-up" />
+                </Button>
+            )}
+        </div>
+    );
+}

apps/showcase/demo/usescrolltop/element-demo.tsx

@@ -0,0 +1,31 @@
+import { useScrollTop } from '@primereact/hooks';
+import { Button } from 'primereact/button';
+import * as React from 'react';
+
+export default function ElementDemo() {
+    const [target, setTarget] = React.useState<HTMLDivElement | null>(null);
+
+    const { scrollToTop, visible } = useScrollTop({
+        target,
+        threshold: 100
+    });
+
+    return (
+        <div className="card flex justify-center">
+            <div ref={setTarget} className="overflow-scroll" style={{ width: '250px', height: '200px', scrollbarWidth: 'thin' }}>
+                <p>
+                    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Vitae et leo duis ut diam. Ultricies mi quis hendrerit dolor magna eget est lorem. Amet consectetur
+                    adipiscing elit ut. Nam libero justo laoreet sit amet. Pharetra massa massa ultricies mi quis hendrerit dolor magna. Est ultricies integer quis auctor elit sed vulputate. Consequat ac felis donec et. Tellus orci ac auctor augue
+                    mauris. Semper feugiat nibh sed pulvinar proin gravida hendrerit lectus a. Tincidunt arcu non sodales neque sodales. Metus aliquam eleifend mi in nulla posuere sollicitudin aliquam ultrices. Sodales ut etiam sit amet nisl purus.
+                    Cursus sit amet dictum sit amet. Tristique senectus et netus et malesuada fames ac turpis egestas. Et tortor consequat id porta nibh venenatis cras sed. Diam maecenas ultricies mi eget mauris. Eget egestas purus viverra accumsan
+                    in nisl nisi. Suscipit adipiscing bibendum est ultricies integer. Mattis aliquam faucibus purus in massa tempor nec.
+                </p>
+                {visible && (
+                    <Button onClick={scrollToTop} iconOnly rounded className="sticky flex ms-auto [inset-block-end:20px] [inset-inline-end:20px]">
+                        <i className="pi pi-arrow-up" />
+                    </Button>
+                )}
+            </div>
+        </div>
+    );
+}

apps/showcase/docs/hooks/usescrolltop/features.mdx

@@ -0,0 +1,29 @@
+---
+title: useScrollTop
+description: useScrollTop is a hook that provides a way to scroll to the top of a container.
+component: usescrolltop
+---
+
+## Usage
+
+```tsx
+import { useScrollTop } from '@primereact/hooks';
+```
+
+```tsx
+const scrollTop = useScrollTop();
+```
+
+## Examples
+
+### Basic
+
+useScrollTop listens window scroll by default.
+
+<DocDemoViewer name="usescrolltop:basic-demo" />
+
+Setting the _target_ option binds useScrollTop to this element that has scrolling content.
+
+### Element
+
+<DocDemoViewer name="usescrolltop:element-demo" />

packages/hooks/src/index.ts

@@ -8,6 +8,7 @@ export * from './use-match-media';
 export * from './use-mount-effect';
 export * from './use-previous';
 export * from './use-props';
+export * from './use-scrolltop';
 export * from './use-unmount-effect';
 export * from './use-update-effect';
 export * from './use-view-transition';

packages/hooks/src/use-scrolltop/index.test.ts

@@ -0,0 +1,102 @@
+import { getWindowScrollTop } from '@primeuix/utils';
+import * as React from 'react';
+
+/**
+ * The options for the `useScrollTop` hook.
+ */
+export interface UseScrollTopOptions {
+    /**
+     * Reference to the target element.
+     * @default window
+     */
+    target?: Window | Element | null;
+    /**
+     * Defines the threshold value of the vertical scroll position of the target to toggle the visibility.
+     * @default 400
+     */
+    threshold?: number;
+    /**
+     * Defines the scrolling behaviour, 'smooth' adds an animation and 'auto' scrolls with a jump.
+     * @default smooth
+     */
+    behavior?: ScrollBehavior;
+}
+
+/**
+ * The exposes for the `useScrollTop` hook.
+ */
+export interface UseScrollTopExposes {
+    /**
+     * Current visible state as a boolean.
+     * @default false
+     */
+    visible: boolean;
+    /**
+     * Scrolls the target element to the top.
+     */
+    scrollToTop: () => void;
+}
+
+/**
+ * useScrollTop hook is used to enter input in a certain format such as numeric, date, currency, email and phone.
+ *
+ * @param {UseScrollTopOptions} options - The options for the scroll top behavior.
+ * @returns {UseScrollTopExposes} - The exposed methods for the scroll top behavior.
+ *
+ * @example
+ * ```tsx
+ * const { scrollToTop, visible } = useScrollTop({
+ *    target: elementRef.current,
+ *    threshold: 400,
+ *    behavior: 'smooth'
+ * });
+ *
+ * return (
+ *    <div ref={elementRef}>
+ *        {visible && (
+ *            <Button onClick={scrollToTop}>
+ *                 <i className="pi pi-arrow-up" />
+ *            </Button>
+ *         )}
+ *    </div>
+ * );
+ */
+export function useScrollTop(options?: UseScrollTopOptions): UseScrollTopExposes {
+    const { target = typeof window !== 'undefined' ? window : null, threshold = 400, behavior = 'smooth' } = options || {};
+    const [visible, setVisible] = React.useState(false);
+
+    const scrollToTop = () => {
+        target?.scroll({
+            top: 0,
+            behavior: behavior
+        });
+    };
+
+    React.useEffect(() => {
+        if (!target) return;
+
+        const checkVisibility = (scrollY: number) => {
+            if (scrollY > threshold) setVisible(true);
+            else setVisible(false);
+        };
+
+        const onScroll = () => {
+            const scrollY = target === window ? getWindowScrollTop() : (target as Element).scrollTop;
+
+            checkVisibility(scrollY);
+        };
+
+        target.addEventListener('scroll', onScroll);
+
+        return () => {
+            target.removeEventListener('scroll', onScroll);
+        };
+    }, [target, threshold]);
+
+    return {
+        //state
+        visible,
+        //methods
+        scrollToTop
+    };
+}