@byndyusoft-ui/use-intersection-observer 0.0.1

package/.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+.turbo

package/README.md

@@ -0,0 +1,119 @@
+# `@byndyusoft-ui/use-intersection-observer`
+---
+> A React hook that provides a simple and flexible way to use the Intersection Observer API, allowing you to track the visibility of DOM elements and react to their intersection with a specified root element or the viewport.
+
+### Installation
+
+```
+npm i @byndyusoft-ui/use-intersection-observer
+```
+
+### Usage `useIntersectionObserver` hook
+```js
+// Use object destructuring, so you don't need to remember the exact order
+const { isIntersecting, entry } = useIntersectionObserver(ref, options);
+
+// Or array destructuring, making it easy to customize the field names
+const [isIntersecting, entry] = useIntersectionObserver(ref, options);
+```
+
+#### Default
+
+```jsx
+import React, { useRef } from "react";
+import {useIntersectionObserver} from "@byndyusoft-ui/use-intersection-observer";
+
+const Component = () => {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const { isIntersecting, entry } = useIntersectionObserver(ref);
+
+  return (
+    <div class="scroll-container">
+      <div ref={ref}>
+        {`isIntersecting: ${isIntersecting}`}
+      </div>
+    </div>
+  );
+};
+```
+
+### Usage of `useIntersectionObserver` for Unmounted or Lazy-Loaded Components
+
+
+
+```jsx
+import React, { useState } from "react";
+import { useIntersectionObserver } from "@byndyusoft-ui/use-intersection-observer";
+
+const Component = () => {
+  const [ref, setRef] = useState<HTMLDivElement | null>(null);
+  const [isVisible, setIsVisible] = useState<boolean>(false);
+  
+  const { isIntersecting, entry } = useIntersectionObserver({ current: ref });
+
+  return (
+    <div class="scroll-container">
+      <button onClick={() => setIsVisible(p => !p)}>Toggle visible</button>
+      {isVisible && (
+          <div ref={setRef}>
+            {`isIntersecting: ${isIntersecting}`}
+          </div>
+      )}
+    </div>
+  );
+};
+```
+
+> The example below demonstrates a non-standard approach to using `useIntersectionObserver` with components that can be
+> unmounted or lazy-loaded. This method involves using `useState` to manage the reference to the target element, 
+> which ensures that the intersection observer works correctly even when the target element is dynamically mounted or unmounted.
+
+
+### Usage `useIntersectionObserver` with options
+
+```jsx
+import React from "react";
+import { useIntersectionObserver } from "@byndyusoft-ui/use-intersection-observer";
+
+const Component = () => {
+  const tergetRef = useRef<HTMLDivElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  const { isIntersecting, entry } = useIntersectionObserver(tergetRef, {
+    root: scrollContainerRef.current,
+    rootMargin: "10px",
+    threshold: 0.5,
+    triggerOnce: false,
+    skip: false,
+    isIntersectingInitial: false,
+    isIntersectingFallback: false,
+    trackVisibility: false, // experimental
+    delay: 1500, // experimental
+    onChange: (isIntersecting, entry) => console.log(isIntersecting, entry),
+  });
+
+  return (
+    <div ref={containerRef} class="scroll-container">
+      <div ref={tergetRef}>
+        {`isIntersecting: ${isIntersecting}`}
+      </div>
+    </div>
+  );
+};
+```
+### Options
+
+Provide these as the options argument in the `useIntersectionObserver ` hook.
+
+| Name                               | Type                              | Default     | Description                                                                                                                                                                                                                                                                                             |
+|------------------------------------|-----------------------------------| ----------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **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%"`.                                      |
+| **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**                       | `(isIntersecting, entry) => void` | `undefined` | Call this function whenever the `isIntersecting` state changes. It will receive the `isIntersecting` boolean, alongside the current `IntersectionObserverEntry`.                                                                                                                                |
+| **trackVisibility** (experimental) | `boolean`                         | `false`     | A boolean indicating whether this Intersection Observer will track visibility changes on the target.                                                                                                                                                                                                    |
+| **delay** (experimental)           | `number`                          | `undefined` | A number indicating the minimum delay in milliseconds between notifications from this observer for a given target. This must be set to at least `100` if `trackVisibility` is `true`.                                                                                                                   |
+| **skip**                           | `boolean`                         | `false`     | Skip creating the IntersectionObserver. You can use this to enable and disable the observer as needed. If `skip` is set while `isIntersecting`, the current state will still be kept.                                                                                                                   |
+| **triggerOnce**                    | `boolean`                         | `false`     | Only trigger the observer once.                                                                                                                                                                                                                                                                         |
+| **isIntersectingInitial**          | `boolean`                         | `false`     | Set the initial value of the `isIntersecting` boolean. This can be used if you expect the element to be in the viewport to start with, and you want to trigger something when it leaves.                                                                                                                |
+| **isIntersectingFallback**         | `boolean`                         | `undefined` | If the `IntersectionObserver` API isn't available in the client, the default behavior is to throw an Error. You can set a specific fallback behavior, and the `isIntersecting` value will be set to this instead of failing. To set a global default, you can set it with the `defaultFallbackInView()` |

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import useIntersectionObserver from './useIntersectionObserver';
+export type { IUseIntersectionObserverOptions, IUseIntersectionObserverReturn } from './useIntersectionObserver.types';
+export { useIntersectionObserver };
+export default useIntersectionObserver;

package/dist/index.js

@@ -0,0 +1,3 @@
+import useIntersectionObserver from './useIntersectionObserver';
+export { useIntersectionObserver };
+export default useIntersectionObserver;

package/dist/useIntersectionObserver.d.ts

@@ -0,0 +1,3 @@
+import { MutableRefObject } from 'react';
+import type { IUseIntersectionObserverReturn, IUseIntersectionObserverOptions } from './useIntersectionObserver.types';
+export default function useIntersectionObserver(ref: MutableRefObject<Element | null>, { threshold, delay, trackVisibility, rootMargin, root, triggerOnce, skip, isIntersectingInitial, isIntersectingFallback, onChange }?: IUseIntersectionObserverOptions): IUseIntersectionObserverReturn;

package/dist/useIntersectionObserver.js

@@ -0,0 +1,61 @@
+import { useEffect, useRef, useState } from 'react';
+import { observe } from './utilities/useIntersectionObserver.utilities';
+export default function useIntersectionObserver(ref, { threshold, delay, trackVisibility, rootMargin, root, triggerOnce, skip, isIntersectingInitial, isIntersectingFallback, onChange } = {}) {
+    const [isIntersecting, setIsIntersecting] = useState(Boolean(isIntersectingInitial));
+    const [entry, setEntry] = useState(undefined);
+    const callback = useRef();
+    const previousEntryTarget = useRef();
+    callback.current = onChange;
+    useEffect(() => {
+        if (skip || !ref?.current)
+            return;
+        let unobserve;
+        unobserve = observe({
+            element: ref.current,
+            options: {
+                root,
+                rootMargin,
+                threshold,
+                // @ts-expect-error experimental v2 api
+                trackVisibility,
+                delay
+            },
+            callback: (isIntersectingValue, entryValue) => {
+                setIsIntersecting(isIntersectingValue);
+                setEntry(entryValue);
+                if (callback.current)
+                    callback.current(isIntersectingValue, entryValue);
+                if (entryValue.isIntersecting && triggerOnce && unobserve) {
+                    unobserve();
+                    unobserve = undefined;
+                }
+            },
+            isIntersectingFallback
+        });
+        return () => {
+            unobserve?.();
+        };
+    }, [
+        Array.isArray(threshold) ? threshold.toString() : threshold,
+        ref?.current,
+        root,
+        rootMargin,
+        triggerOnce,
+        skip,
+        trackVisibility,
+        isIntersectingFallback,
+        delay
+    ]);
+    const entryTarget = entry?.target;
+    if (!ref?.current && entryTarget && !triggerOnce && !skip && previousEntryTarget.current !== entryTarget) {
+        previousEntryTarget.current = entryTarget;
+        setIsIntersecting(Boolean(isIntersectingInitial));
+        setEntry(undefined);
+    }
+    const tupleReturn = [isIntersecting, entry];
+    const objectReturn = {
+        isIntersecting,
+        entry
+    };
+    return Object.assign(tupleReturn, objectReturn);
+}

package/dist/useIntersectionObserver.types.d.ts

@@ -0,0 +1,40 @@
+export type TObserverInstanceCallback = (isIntersecting: boolean, entry: IntersectionObserverEntry) => void;
+export interface IObserveOptions {
+    element: Element;
+    callback: TObserverInstanceCallback;
+    options: IntersectionObserverInit;
+    isIntersectingFallback?: boolean;
+}
+export interface IObserverItem {
+    id: string;
+    observer: IntersectionObserver;
+    elements: Map<Element, Array<TObserverInstanceCallback>>;
+}
+export interface IUseIntersectionObserverOptions extends IntersectionObserverInit {
+    /** 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;
+    /** 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 isIntersecting callback once */
+    triggerOnce?: boolean;
+    /** Skip assigning the observer to the `ref` */
+    skip?: boolean;
+    /** Set the initial value of the `isIntersecting` boolean. This can be used if you expect the element to be in the viewport to start with, and you want to trigger something when it leaves. */
+    isIntersectingInitial?: boolean;
+    /** Fallback to this isIntersecting state if the IntersectionObserver is unsupported, and a polyfill wasn't loaded */
+    isIntersectingFallback?: boolean;
+    /** IntersectionObserver v2 - Track the actual visibility of the element */
+    trackVisibility?: boolean;
+    /** IntersectionObserver v2 - Set a minimum delay between notifications */
+    delay?: number;
+    /** Call this function whenever the in view state changes */
+    onChange?: (isIntersecting: boolean, entry: IntersectionObserverEntry) => void;
+}
+export type IUseIntersectionObserverTuple = [boolean, IntersectionObserverEntry | undefined];
+export type IUseIntersectionObserverObject = {
+    isIntersecting: boolean;
+    entry?: IntersectionObserverEntry;
+};
+export type IUseIntersectionObserverReturn = IUseIntersectionObserverTuple & IUseIntersectionObserverObject;

package/dist/useIntersectionObserver.types.js

@@ -0,0 +1 @@
+export {};

package/dist/utilities/useIntersectionObserver.utilities.d.ts

@@ -0,0 +1,12 @@
+import type { IObserveOptions, IObserverItem } from '../useIntersectionObserver.types';
+/**
+ * Generate a unique ID for the root element
+ */
+export declare function getRootId(root: IntersectionObserverInit['root']): string | undefined;
+/**
+ * Convert the options to a string Id, based on the values.
+ * Ensures we can reuse the same observer when observing elements with the same options.
+ */
+export declare function optionsToId(options: IntersectionObserverInit): string;
+export declare function createObserver(options: IntersectionObserverInit): IObserverItem;
+export declare function observe({ element, callback, options, isIntersectingFallback }: IObserveOptions): () => void;

package/dist/utilities/useIntersectionObserver.utilities.js

@@ -0,0 +1,93 @@
+const observerMap = new Map();
+const rootIdsWeakMap = new WeakMap();
+let rootId = 0;
+/**
+ * Generate a unique ID for the root element
+ */
+export function getRootId(root) {
+    if (!root)
+        return '0';
+    if (rootIdsWeakMap.has(root))
+        return rootIdsWeakMap.get(root);
+    rootId += 1;
+    rootIdsWeakMap.set(root, rootId.toString());
+    return rootIdsWeakMap.get(root);
+}
+/**
+ * Convert the options to a string Id, based on the values.
+ * Ensures we can reuse the same observer when observing elements with the same options.
+ */
+export function optionsToId(options) {
+    return Object.keys(options)
+        .sort()
+        .filter(key => options[key] !== undefined)
+        .map(key => {
+        const value = key === 'root' ? getRootId(options.root) : options[key];
+        return `${key}_${value}`;
+    })
+        .toString();
+}
+export function createObserver(options) {
+    const id = optionsToId(options);
+    let instance = observerMap.get(id);
+    if (instance)
+        return instance;
+    const elements = new Map();
+    let thresholds = [];
+    const observer = new IntersectionObserver(entries => {
+        entries.forEach(entry => {
+            const isIntersecting = entry.isIntersecting && thresholds.some(threshold => entry.intersectionRatio >= threshold);
+            // @ts-expect-error support IntersectionObserver v2
+            if (options.trackVisibility && typeof entry.isVisible === 'undefined') {
+                // The browser doesn't support Intersection Observer v2, falling back to v1 behavior.
+                // @ts-expect-error
+                entry.isVisible = isIntersecting;
+            }
+            elements.get(entry.target)?.forEach(callback => {
+                callback(isIntersecting, entry);
+            });
+        });
+    }, options);
+    thresholds =
+        observer.thresholds || (Array.isArray(options.threshold) ? options.threshold : [options.threshold || 0]);
+    instance = {
+        id,
+        observer,
+        elements
+    };
+    observerMap.set(id, instance);
+    return instance;
+}
+export function observe({ element, callback, options = {}, isIntersectingFallback }) {
+    if (typeof window.IntersectionObserver === 'undefined' && isIntersectingFallback !== undefined) {
+        const bounds = element.getBoundingClientRect();
+        callback(isIntersectingFallback, {
+            isIntersecting: isIntersectingFallback,
+            target: element,
+            intersectionRatio: typeof options.threshold === 'number' ? options.threshold : 0,
+            time: 0,
+            boundingClientRect: bounds,
+            intersectionRect: bounds,
+            rootBounds: bounds
+        });
+        return () => { };
+    }
+    const { id, observer, elements } = createObserver(options);
+    const callbacks = elements.get(element) || [];
+    if (!elements.has(element)) {
+        elements.set(element, callbacks);
+    }
+    callbacks.push(callback);
+    observer.observe(element);
+    return function unobserve() {
+        callbacks.splice(callbacks.indexOf(callback), 1);
+        if (callbacks.length === 0) {
+            elements.delete(element);
+            observer.unobserve(element);
+        }
+        if (elements.size === 0) {
+            observer.disconnect();
+            observerMap.delete(id);
+        }
+    };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@byndyusoft-ui/use-intersection-observer",
+  "version": "0.0.1",
+  "description": "Byndyusoft UI React Hook",
+  "keywords": [
+    "byndyusoft",
+    "byndyusoft-ui",
+    "react",
+    "hook",
+    "intersection-observer"
+  ],
+  "author": "Gleb Fomin <gleb.fom28@gmail.com>",
+  "homepage": "https://github.com/Byndyusoft/ui/tree/master/hooks/use-intersection-observer#readme",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Byndyusoft/ui.git"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "clean": "rimraf dist && rimraf .turbo && rimraf node_modules && rimraf package-lock.json",
+    "lint": "eslint src --config ../../eslint.config.js",
+    "test": "jest --config ../../jest.config.js --roots hooks/use-intersection-observer/src"
+  },
+  "bugs": {
+    "url": "https://github.com/Byndyusoft/ui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["src/**/*.stories.*", "src/**/__stories__", "src/**/*.docs.*", "src/**/*.tests.*", "src/**/__tests__"]
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationDir": "dist",
+    "outDir": "dist",
+    "module": "ESNext"
+  },
+  "include": ["../../types.d.ts", "src"]
+}