Address scrollMargin review feedback

Author: thebuilder

README.md

@@ -206,6 +206,7 @@ Provide these as the options argument in the `useInView` hook or as props on the
 | ---------------------- | ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **root**               | `Element`                 | `document`  | The Intersection Observer interface's read-only root property identifies the Element or Document whose bounds are treated as the bounding box of the viewport for the element which is the observer's target. If the root is `null`, then the bounds of the actual document viewport are used.  |
 | **rootMargin**         | `string`                  | `'0px'`     | Margin around the root. Can have values similar to the CSS margin property, e.g. `"10px 20px 30px 40px"` (top, right, bottom, left). Also supports percentages, to check if an element intersects with the center of the viewport for example `"-50% 0% -50% 0%"`.                              |
+| **scrollMargin**       | `string`                  | `'0px'`     | Margin around nested scroll containers that clip the target, including the root if it is a scroll container.                                       |
 | **threshold**          | `number` or `number[]`    | `0`         | Number between `0` and `1` indicating the percentage that should be visible before triggering. Can also be an array of numbers, to create multiple trigger points.                                                                                                                              |
 | **onChange**           | `(inView, entry) => void` | `undefined` | Call this function whenever the in view state changes. It will receive the `inView` boolean, alongside the current `IntersectionObserverEntry`.                                                                                                                                                 |
 | **trackVisibility** 🧪 | `boolean`                 | `false`     | A boolean indicating whether this Intersection Observer will track visibility changes on the target.                                                                                                                                                                                            |

src/InView.tsx

@@ -88,6 +88,7 @@ export class InView extends React.Component<
     // If a IntersectionObserver option changed, reinit the observer
     if (
       prevProps.rootMargin !== this.props.rootMargin ||
+      prevProps.scrollMargin !== this.props.scrollMargin ||
       prevProps.root !== this.props.root ||
       prevProps.threshold !== this.props.threshold ||
       prevProps.skip !== this.props.skip ||
@@ -109,6 +110,7 @@ export class InView extends React.Component<
       threshold,
       root,
       rootMargin,
+      scrollMargin,
       trackVisibility,
       delay,
       fallbackInView,
@@ -124,7 +126,7 @@ export class InView extends React.Component<
         threshold,
         root,
         rootMargin,
-        // @ts-expect-error
+        scrollMargin,
         trackVisibility,
         delay,
       },

src/__tests__/InView.test.tsx

@@ -124,6 +124,16 @@ test("Should recreate observer when rootMargin change", () => {
   expect(instance.unobserve).toHaveBeenCalled();
 });
 
+test("Should recreate observer when scrollMargin change", () => {
+  const { container, rerender } = render(<InView>Inner</InView>);
+  mockAllIsIntersecting(true);
+  const instance = intersectionMockInstance(container.children[0]);
+  vi.spyOn(instance, "unobserve");
+
+  rerender(<InView scrollMargin="10px">Inner</InView>);
+  expect(instance.unobserve).toHaveBeenCalled();
+});
+
 test("Should unobserve when triggerOnce comes into view", () => {
   const { container } = render(<InView triggerOnce>Inner</InView>);
   mockAllIsIntersecting(false);

src/__tests__/observe.test.ts

@@ -37,7 +37,6 @@ test("should convert options to id", () => {
   expect(
     optionsToId({
       threshold: 0,
-      // @ts-expect-error
       trackVisibility: true,
       delay: 500,
     }),
@@ -49,7 +48,8 @@ test("should convert options to id", () => {
   ).toMatchInlineSnapshot(`"threshold_0"`);
   expect(
     optionsToId({
+      scrollMargin: "10px 20px",
       threshold: [0, 0.5, 1],
     }),
-  ).toMatchInlineSnapshot(`"threshold_0,0.5,1"`);
+  ).toMatchInlineSnapshot(`"scrollMargin_10px 20px,threshold_0,0.5,1"`);
 });

src/__tests__/useInView.test.tsx

@@ -57,6 +57,16 @@ test("should create a hook with array threshold", () => {
   expect(instance.observe).toHaveBeenCalledWith(wrapper);
 });
 
+test("should create a hook with scrollMargin", () => {
+  const { getByTestId } = render(
+    <HookComponent options={{ scrollMargin: "10px" }} />,
+  );
+  const wrapper = getByTestId("wrapper");
+  const instance = intersectionMockInstance(wrapper);
+
+  expect(instance).toHaveProperty("scrollMargin", "10px");
+});
+
 test("should create a lazy hook", () => {
   const { getByTestId } = render(<LazyHookComponent />);
   const wrapper = getByTestId("wrapper");

src/index.tsx

@@ -9,6 +9,15 @@ export { useOnInView } from "./useOnInView";
 
 type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
 
+export type IntersectionObserverInitWithOptions = IntersectionObserverInit & {
+  /** Margin around nested scroll containers that clip the target, including the root if it is a scroll container. */
+  scrollMargin?: string;
+  /** IntersectionObserver v2 - Track the actual visibility of the element */
+  trackVisibility?: boolean;
+  /** IntersectionObserver v2 - Set a minimum delay between notifications */
+  delay?: number;
+};
+
 export type ObserverInstanceCallback = (
   inView: boolean,
   entry: IntersectionObserverEntry,
@@ -26,11 +35,14 @@ interface RenderProps {
   ref: React.RefObject<any> | ((node?: Element | null) => void);
 }
 
-export interface IntersectionOptions extends IntersectionObserverInit {
+export interface IntersectionOptions
+  extends IntersectionObserverInitWithOptions {
   /** The IntersectionObserver interface's read-only `root` property identifies the Element or Document whose bounds are treated as the bounding box of the viewport for the element which is the observer's target. If the `root` is null, then the bounds of the actual document viewport are used.*/
   root?: Element | Document | null;
   /** Margin around the root. Can have values similar to the CSS margin property, e.g. `10px 20px 30px 40px` (top, right, bottom, left). */
   rootMargin?: string;
+  /** Margin around nested scroll containers that clips the target, including the root if it is a scroll container. */
+  scrollMargin?: string;
   /** Number between `0` and `1` indicating the percentage that should be visible before triggering. Can also be an `array` of numbers, to create multiple trigger points. */
   threshold?: number | number[];
   /** Only trigger the inView callback once */

src/observe.ts

@@ -1,4 +1,7 @@
-import type { ObserverInstanceCallback } from "./index";
+import type {
+  IntersectionObserverInitWithOptions,
+  ObserverInstanceCallback,
+} from "./index";
 
 const observerMap = new Map<
   string,
@@ -28,7 +31,7 @@ export function defaultFallbackInView(inView: boolean | undefined) {
  * Generate a unique ID for the root element
  * @param root
  */
-function getRootId(root: IntersectionObserverInit["root"]) {
+function getRootId(root: IntersectionObserverInitWithOptions["root"]) {
   if (!root) return "0";
   if (RootIds.has(root)) return RootIds.get(root);
   rootId += 1;
@@ -41,23 +44,24 @@ function getRootId(root: IntersectionObserverInit["root"]) {
  * Ensures we can reuse the same observer when observing elements with the same options.
  * @param options
  */
-export function optionsToId(options: IntersectionObserverInit) {
+export function optionsToId(options: IntersectionObserverInitWithOptions) {
   return Object.keys(options)
     .sort()
     .filter(
-      (key) => options[key as keyof IntersectionObserverInit] !== undefined,
+      (key) =>
+        options[key as keyof IntersectionObserverInitWithOptions] !== undefined,
     )
     .map((key) => {
       return `${key}_${
         key === "root"
           ? getRootId(options.root)
-          : options[key as keyof IntersectionObserverInit]
+          : options[key as keyof IntersectionObserverInitWithOptions]
       }`;
     })
     .toString();
 }
 
-function createObserver(options: IntersectionObserverInit) {
+function createObserver(options: IntersectionObserverInitWithOptions) {
   // Create a unique ID for this observer instance, based on the root, root margin and threshold.
   const id = optionsToId(options);
   let instance = observerMap.get(id);
@@ -118,7 +122,7 @@ function createObserver(options: IntersectionObserverInit) {
 export function observe(
   element: Element,
   callback: ObserverInstanceCallback,
-  options: IntersectionObserverInit = {},
+  options: IntersectionObserverInitWithOptions = {},
   fallbackInView = unsupportedValue,
 ) {
   if (

src/test-utils.ts

@@ -1,6 +1,10 @@
 import * as React from "react";
 import * as DeprecatedReactTestUtils from "react-dom/test-utils";
 
+type IntersectionObserverWithScrollMargin = IntersectionObserver & {
+  scrollMargin: string;
+};
+
 type Item = {
   callback: IntersectionObserverCallback;
   elements: Set<Element>;
@@ -121,12 +125,13 @@ export function setupIntersectionMocking(mockFn: typeof vi.fn) {
       elements: new Set<Element>(),
       created: Date.now(),
     };
-    const instance: IntersectionObserver = {
+    const instance: IntersectionObserverWithScrollMargin = {
       thresholds: Array.isArray(options.threshold)
         ? options.threshold
         : [options.threshold ?? 0],
       root: options.root ?? null,
       rootMargin: options.rootMargin ?? "",
+      scrollMargin: options.scrollMargin ?? "",
       observe: mockFn((element: Element) => {
         item.elements.add(element);
       }),

src/useInView.tsx

@@ -38,6 +38,7 @@ export function useInView({
   delay,
   trackVisibility,
   rootMargin,
+  scrollMargin,
   root,
   triggerOnce,
   skip,
@@ -93,8 +94,8 @@ export function useInView({
         {
           root,
           rootMargin,
+          scrollMargin,
           threshold,
-          // @ts-expect-error
           trackVisibility,
           delay,
         },
@@ -115,6 +116,7 @@ export function useInView({
       ref,
       root,
       rootMargin,
+      scrollMargin,
       triggerOnce,
       skip,
       trackVisibility,

src/useOnInView.tsx

@@ -49,6 +49,7 @@ export const useOnInView = <TElement extends Element>(
     threshold,
     root,
     rootMargin,
+    scrollMargin,
     trackVisibility,
     delay,
     triggerOnce,
@@ -116,6 +117,7 @@ export const useOnInView = <TElement extends Element>(
           threshold,
           root,
           rootMargin,
+          scrollMargin,
           trackVisibility,
           delay,
         } as IntersectionObserverInit,
@@ -140,6 +142,7 @@ export const useOnInView = <TElement extends Element>(
       Array.isArray(threshold) ? threshold.toString() : threshold,
       root,
       rootMargin,
+      scrollMargin,
       trackVisibility,
       delay,
       triggerOnce,