chore!(utils): useScrollListener no longer accepts an element or options

Author: mlaursen

packages/documentation/src/components/Demos/AppBar/AnimatingAppBar.tsx

@@ -4,7 +4,6 @@ import { Avatar } from "@react-md/avatar";
 import avatarVariables from "@react-md/avatar/dist/scssVariables";
 import { List, ListItem } from "@react-md/list";
 import { MenuSVGIcon, MoreVertSVGIcon } from "@react-md/material-icons";
-import { useScrollListener } from "@react-md/utils";
 
 import people from "constants/people";
 import AppBarTitle from "components/AppBarTitle";
@@ -33,27 +32,6 @@ const SCROLL_MULTIPLIER = 0.314;
 
 export default function AnimatingAppBar(): ReactElement {
   const [height, setHeight] = useState(`${HEIGHT}px`);
-
-  const [ref, setRef] = useState<HTMLDivElement | null>(null);
-  useScrollListener({
-    element: ref,
-    onScroll: () => {
-      if (!ref) {
-        return;
-      }
-
-      const { scrollTop } = ref;
-      const remaining = Math.min(
-        Math.max(HEIGHT - scrollTop * SCROLL_MULTIPLIER, 0),
-        HEIGHT
-      );
-      const nextHeight = `${remaining}px`;
-      if (height !== nextHeight) {
-        setHeight(nextHeight);
-      }
-    },
-  });
-
   const style: CSSProperties = {
     "--offset": height,
   };
@@ -74,7 +52,20 @@ export default function AnimatingAppBar(): ReactElement {
           <MoreVertSVGIcon />
         </AppBarAction>
       </AppBar>
-      <div className={styles.content} ref={setRef}>
+      <div
+        className={styles.content}
+        onScroll={(event) => {
+          const { scrollTop } = event.currentTarget;
+          const remaining = Math.min(
+            Math.max(HEIGHT - scrollTop * SCROLL_MULTIPLIER, 0),
+            HEIGHT
+          );
+          const nextHeight = `${remaining}px`;
+          if (height !== nextHeight) {
+            setHeight(nextHeight);
+          }
+        }}
+      >
         <List>
           {transformedPeople.map(({ id, name, avatar, color }, i) => (
             <ListItem

packages/utils/src/events/ScrollListener.tsx

@@ -1,6 +1,9 @@
-import { useScrollListener, Options } from "./useScrollListener";
+import {
+  useScrollListener,
+  ScrollListenerHookOptions,
+} from "./useScrollListener";
 
-export type ScrollListenerProps = Omit<Options<HTMLElement>, "enabled">;
+export type ScrollListenerProps = Omit<ScrollListenerHookOptions, "enabled">;
 
 /**
  * This is a simple component wrapper for the `useScrollListener` hook.

packages/utils/src/events/useScrollListener.ts

@@ -2,62 +2,51 @@ import { useEffect } from "react";
 
 import { useRefCache } from "../useRefCache";
 import { delegateEvent } from "./delegateEvent";
-import { isSupported } from "./passiveEvents";
 
-export interface Options<E extends HTMLElement = HTMLElement> {
+/**
+ * @remarks \@since 5.0.0
+ */
+export interface ScrollListenerHookOptions extends AddEventListenerOptions {
   /**
-   * A function that is called whenever the scroll event is triggered.
+   * The event handler that will be fired when the page scrolls or if any child
+   * element scrolls when the {@link capture} option is `true`.
    */
   onScroll: EventListener;
 
-  /**
-   * Any event listener options to use when attaching the event.
-   */
-  options?: AddEventListenerOptions | boolean;
-
-  /**
-   * Boolean if the scroll listener should be enabled. You can swap this boolean
-   * to `true` or `false` to add/remove the event listeners. The event listeners
-   * will *always* be removed when the parent component is unmounted though.
-   */
+  /** @defaultValue `true` */
   enabled?: boolean;
-
-  /**
-   * The element that should gain the focus event. When this is omitted, it will
-   * default to the entire `window`.
-   */
-  element?: E | null;
 }
 
 /**
- * This hook will create a performant scroll listener by enabling passive events
- * if it's supported by the browser and delegating the event as needed.
+ *
+ * @remarks \@since 5.0.0 Moved the `AddEventListenerOptions` to no longer be
+ * part of an `options` object.
  */
-export function useScrollListener<E extends HTMLElement = HTMLElement>({
+export function useScrollListener({
+  once,
+  passive = true,
+  signal,
+  capture,
   enabled = true,
   onScroll,
-  element,
-  options = isSupported ? { passive: true } : false,
-}: Options<E>): void {
-  const callback = useRefCache(onScroll);
-
+}: ScrollListenerHookOptions): void {
+  const scrollHandlerRef = useRefCache(onScroll);
   useEffect(() => {
     if (!enabled) {
       return;
     }
 
-    const eventHandler = delegateEvent(
-      "scroll",
-      element || window,
-      true,
-      options
-    );
-    const handler = (event: Event): void => callback.current(event);
-    eventHandler.add(handler);
+    const eventHandler = delegateEvent("scroll", window, true, {
+      once,
+      passive,
+      signal,
+      capture,
+    });
+    const scrollHandler = scrollHandlerRef.current;
+    eventHandler.add(scrollHandler);
+
     return () => {
-      eventHandler.remove(handler);
+      eventHandler.remove(scrollHandler);
     };
-    // disabled since useRefCache
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [enabled, element, options]);
+  }, [capture, enabled, once, passive, scrollHandlerRef, signal]);
 }