@usefy/use-infinite-scroll 0.20.0

package/README.md

@@ -0,0 +1,144 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png" alt="usefy logo" width="120" />
+</p>
+
+<h1 align="center">@usefy/use-infinite-scroll</h1>
+
+<p align="center">
+  <strong>Sentinel-driven infinite loading built on IntersectionObserver — attach one ref, load more automatically</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefy/use-infinite-scroll"><img src="https://img.shields.io/npm/v/@usefy/use-infinite-scroll.svg?style=flat-square&color=007acc" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@usefy/use-infinite-scroll"><img src="https://img.shields.io/npm/dm/@usefy/use-infinite-scroll.svg?style=flat-square&color=007acc" alt="npm downloads" /></a>
+  <a href="https://bundlephobia.com/package/@usefy/use-infinite-scroll"><img src="https://img.shields.io/bundlephobia/minzip/@usefy/use-infinite-scroll?style=flat-square&color=007acc" alt="bundle size" /></a>
+  <a href="https://github.com/mirunamu00/usefy/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@usefy/use-infinite-scroll.svg?style=flat-square&color=007acc" alt="license" /></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api">API</a> •
+  <a href="#testing">Testing</a> •
+  <a href="#license">License</a>
+</p>
+
+<p align="center">
+  <a href="https://mirunamu00.github.io/usefy/?path=/docs/hooks-useinfinitescroll--docs" target="_blank" rel="noopener noreferrer">
+    <strong>📚 View Storybook Demo</strong>
+  </a>
+</p>
+
+---
+
+## Overview
+
+`useInfiniteScroll` is part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem — a collection of production-ready, TypeScript-first, SSR-safe React hooks. It turns "load the next page when the user reaches the bottom" into a one-liner: render a small **sentinel** element at the end of your list, attach the returned ref, and your `loadMore` callback fires whenever that sentinel scrolls into view — once per intersection, never while a load is already in flight.
+
+Built on top of [`@usefy/use-intersection-observer`](https://www.npmjs.com/package/@usefy/use-intersection-observer), so it inherits its SSR-safe and StrictMode-safe behavior — no scroll listeners, no offset math.
+
+## Features
+
+- **One ref, that's it** — `const ref = useInfiniteScroll(loadMore, { hasMore, loading })`; attach `ref` to a sentinel
+- **Fires once per intersection** — it does not re-fire while the sentinel stays in view (the sentinel must leave and re-enter)
+- **Respects `hasMore` / `loading` / `enabled`** — stops observing entirely once exhausted or disabled
+- **No double-fire on async loads** — honours the `loading` flag *and* an internal in-flight guard: if `loadMore` returns a promise, it won't fire again until it settles
+- **Latest-callback pattern** — changing `loadMore` (or the flags) never re-subscribes the observer
+- **Prefetch support** — `rootMargin` fires `loadMore` before the sentinel is on screen; custom `root`, `threshold` supported
+- **SSR-safe & StrictMode-safe** — returns an inert no-op ref on the server; no observer leaks
+- **TypeScript-first** — full type inference and exported types
+- **Tiny & tree-shakeable** — one small dependency, published as its own package
+
+## Installation
+
+```bash
+# npm
+npm install @usefy/use-infinite-scroll
+
+# yarn
+yarn add @usefy/use-infinite-scroll
+
+# pnpm
+pnpm add @usefy/use-infinite-scroll
+```
+
+Requires React 18 or 19 (`peerDependencies: "react": "^18.0.0 || ^19.0.0"`).
+
+## Quick Start
+
+```tsx
+import { useState } from "react";
+import { useInfiniteScroll } from "@usefy/use-infinite-scroll";
+
+function Feed() {
+  const [items, setItems] = useState<Item[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [hasMore, setHasMore] = useState(true);
+
+  const loadMore = async () => {
+    setLoading(true);
+    const { data, done } = await fetchNextPage(items.length);
+    setItems((prev) => [...prev, ...data]);
+    setHasMore(!done);
+    setLoading(false);
+  };
+
+  const sentinelRef = useInfiniteScroll(loadMore, { hasMore, loading });
+
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>{item.title}</li>
+      ))}
+      {/* Render the sentinel only while there is more to load. */}
+      {hasMore && <li ref={sentinelRef} aria-hidden />}
+    </ul>
+  );
+}
+```
+
+## API
+
+```ts
+const sentinelRef = useInfiniteScroll(loadMore, options?);
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `loadMore` | `() => void \| Promise<void>` | Called to load the next page when the sentinel enters view. May be sync or async — when it returns a promise, the hook treats the load as in-flight and won't fire again until it settles. Changing this reference never re-subscribes the observer. |
+| `options` | `UseInfiniteScrollOptions` | Optional configuration (see below). |
+
+### Options — `UseInfiniteScrollOptions`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `hasMore` | `boolean` | `true` | Whether there is more to load. When `false`, the sentinel is **no longer observed** and `loadMore` never fires. Set it `false` after the last page. |
+| `loading` | `boolean` | `false` | Whether a load is in progress. When `true`, an intersection will not trigger `loadMore`. Wire this to your own loading state. |
+| `enabled` | `boolean` | `true` | Master switch. When `false`, the sentinel is not observed and `loadMore` never fires, regardless of `hasMore`/`loading`. |
+| `rootMargin` | `string` | `"0px"` | CSS margin around the root. A positive value like `"300px"` fires `loadMore` *before* the sentinel is on screen (prefetch). |
+| `threshold` | `number \| number[]` | `0` | Intersection ratio(s) that trigger a load. `0` fires as soon as a single pixel is visible. |
+| `root` | `Element \| Document \| null` | `null` | The scroll container used as the observer root. `null` uses the browser viewport; pass a scrollable element to run infinite scroll inside a fixed-height panel. |
+
+### Returns — `UseInfiniteScrollRef`
+
+A **callback ref** — `(node: Element | null) => void` — to attach to your sentinel element. It has a stable identity across renders, so it is safe to pass directly to a `ref` prop.
+
+### Behavior notes
+
+- **Once per intersection.** `loadMore` fires when the sentinel *enters* view; it does not re-fire while the sentinel stays visible. If a load doesn't fill the viewport and the sentinel is still visible, the user scrolls (or the sentinel re-enters) to trigger the next page — this matches native infinite-scroll UX and avoids runaway loops.
+- **No double-fire.** Two guards prevent overlapping loads: the `loading` prop you control, and an internal in-flight guard for the async case (a second intersection while the returned promise is pending is ignored). The hook does **not** surface `loadMore` errors — handle them inside `loadMore` (e.g. `try/catch` and reset your `loading` state).
+- **Stops observing when exhausted.** Once `hasMore` is `false` (or `enabled` is `false`), the underlying observer disconnects — no wasted work.
+- **SSR / StrictMode.** On the server (or where `IntersectionObserver` is unavailable) the returned ref is an inert no-op and nothing fires. Under StrictMode's double-mount the observer is set up and torn down cleanly.
+- **Memoize `threshold` / `root`.** Changing `loadMore` and the `hasMore` / `loading` / `enabled` flags never re-subscribes the observer, but `threshold` and `root` are observer configuration — passing a fresh inline array (`threshold={[0, 0.5]}`) or element every render re-subscribes it. Hoist them to a constant or `useMemo`/ref if they are non-primitive.
+
+## Testing
+
+📊 <a href="https://mirunamu00.github.io/usefy/coverage/use-infinite-scroll/src/index.html" target="_blank" rel="noopener noreferrer"><strong>View Detailed Coverage Report</strong></a> (GitHub Pages) — **19 tests**, 100% statement coverage.
+
+## License
+
+MIT © [mirunamu](https://github.com/mirunamu00)
+
+This package is part of the [usefy](https://github.com/mirunamu00/usefy) monorepo.

package/dist/index.d.mts

@@ -0,0 +1,137 @@
+/**
+ * The function invoked to load the next page of data.
+ *
+ * It may be synchronous (`void`) or asynchronous (`Promise<void>`). When it
+ * returns a promise, `useInfiniteScroll` tracks it as in-flight and will not
+ * fire again until it settles, even if the sentinel re-enters view in the
+ * meantime — an internal guard on top of the `loading` flag.
+ */
+type LoadMoreFn = () => void | Promise<void>;
+/**
+ * Options for configuring the {@link useInfiniteScroll} hook.
+ */
+interface UseInfiniteScrollOptions {
+    /**
+     * Whether there is more data to load. When `false`, the sentinel is no longer
+     * observed and `loadMore` will never fire — set it `false` once the last page
+     * has been reached.
+     * @default true
+     */
+    hasMore?: boolean;
+    /**
+     * Whether a load is currently in progress. When `true`, an intersection will
+     * not trigger `loadMore`, preventing overlapping requests. Wire this to your
+     * own loading state.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Master enable/disable switch. When `false`, the sentinel is not observed
+     * and `loadMore` never fires, regardless of `hasMore`/`loading`.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Margin around the root, in CSS margin syntax, used to grow (or shrink) the
+     * area that triggers a load. A positive margin like `"200px"` fires
+     * `loadMore` *before* the sentinel is actually on screen, prefetching the
+     * next page for a seamless scroll.
+     * @default "0px"
+     */
+    rootMargin?: string;
+    /**
+     * The intersection ratio(s) at which a load is triggered. `0` fires as soon
+     * as a single pixel of the sentinel is visible.
+     * @default 0
+     */
+    threshold?: number | number[];
+    /**
+     * The scroll container used as the observer root. `null` (default) uses the
+     * browser viewport. Pass a scrollable element (e.g. `containerRef.current`)
+     * to run infinite scroll inside a fixed-height panel.
+     * @default null
+     */
+    root?: Element | Document | null;
+}
+/**
+ * The value returned by {@link useInfiniteScroll}: a callback ref to attach to
+ * the sentinel element (typically an empty `<div>` at the end of the list).
+ *
+ * @example
+ * ```tsx
+ * const sentinelRef = useInfiniteScroll(loadMore, { hasMore, loading });
+ * return <div ref={sentinelRef} />;
+ * ```
+ */
+type UseInfiniteScrollRef = (node: Element | null) => void;
+
+/**
+ * Sentinel-driven infinite scrolling built on the Intersection Observer API.
+ *
+ * Attach the returned callback ref to a small sentinel element rendered at the
+ * end of your list. Whenever that sentinel scrolls into view — and there is
+ * more to load, nothing is currently loading, and the hook is enabled — your
+ * `loadMore` callback fires exactly **once** per intersection.
+ *
+ * Built on top of {@link useIntersectionObserver}, so it inherits its SSR-safe
+ * (returns an inert no-op ref on the server) and StrictMode-safe behavior.
+ *
+ * Key guarantees:
+ * - **Fires once per intersection.** It does not re-fire while the sentinel
+ *   stays in view; the sentinel must leave and re-enter to trigger again.
+ * - **Latest-callback pattern.** Changing `loadMore` (or the `hasMore` /
+ *   `loading` / `enabled` flags) never re-subscribes the observer.
+ * - **No double-fire while loading.** Respects the `loading` flag *and* an
+ *   internal in-flight guard: if `loadMore` returns a promise, the hook will
+ *   not fire again until it settles.
+ * - **Stops observing when exhausted.** Once `hasMore` is `false` (or `enabled`
+ *   is `false`), the observer disconnects entirely.
+ *
+ * @param loadMore - Called to load the next page. May be sync or async.
+ * @param options - Configuration (`hasMore`, `loading`, `enabled`, `rootMargin`,
+ *   `threshold`, `root`).
+ * @returns A callback ref to attach to the sentinel element.
+ *
+ * @example
+ * ```tsx
+ * function Feed() {
+ *   const [items, setItems] = useState<Item[]>([]);
+ *   const [loading, setLoading] = useState(false);
+ *   const [hasMore, setHasMore] = useState(true);
+ *
+ *   const loadMore = async () => {
+ *     setLoading(true);
+ *     const { data, done } = await fetchNextPage(items.length);
+ *     setItems((prev) => [...prev, ...data]);
+ *     setHasMore(!done);
+ *     setLoading(false);
+ *   };
+ *
+ *   const sentinelRef = useInfiniteScroll(loadMore, { hasMore, loading });
+ *
+ *   return (
+ *     <ul>
+ *       {items.map((item) => (
+ *         <li key={item.id}>{item.title}</li>
+ *       ))}
+ *       {hasMore && <li ref={sentinelRef} aria-hidden />}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Prefetch 300px early, inside a fixed-height scroll container.
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const sentinelRef = useInfiniteScroll(loadMore, {
+ *   hasMore,
+ *   loading,
+ *   root: containerRef.current,
+ *   rootMargin: "300px",
+ * });
+ * ```
+ */
+declare function useInfiniteScroll(loadMore: LoadMoreFn, options?: UseInfiniteScrollOptions): UseInfiniteScrollRef;
+
+export { type LoadMoreFn, type UseInfiniteScrollOptions, type UseInfiniteScrollRef, useInfiniteScroll };

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The function invoked to load the next page of data.
+ *
+ * It may be synchronous (`void`) or asynchronous (`Promise<void>`). When it
+ * returns a promise, `useInfiniteScroll` tracks it as in-flight and will not
+ * fire again until it settles, even if the sentinel re-enters view in the
+ * meantime — an internal guard on top of the `loading` flag.
+ */
+type LoadMoreFn = () => void | Promise<void>;
+/**
+ * Options for configuring the {@link useInfiniteScroll} hook.
+ */
+interface UseInfiniteScrollOptions {
+    /**
+     * Whether there is more data to load. When `false`, the sentinel is no longer
+     * observed and `loadMore` will never fire — set it `false` once the last page
+     * has been reached.
+     * @default true
+     */
+    hasMore?: boolean;
+    /**
+     * Whether a load is currently in progress. When `true`, an intersection will
+     * not trigger `loadMore`, preventing overlapping requests. Wire this to your
+     * own loading state.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Master enable/disable switch. When `false`, the sentinel is not observed
+     * and `loadMore` never fires, regardless of `hasMore`/`loading`.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Margin around the root, in CSS margin syntax, used to grow (or shrink) the
+     * area that triggers a load. A positive margin like `"200px"` fires
+     * `loadMore` *before* the sentinel is actually on screen, prefetching the
+     * next page for a seamless scroll.
+     * @default "0px"
+     */
+    rootMargin?: string;
+    /**
+     * The intersection ratio(s) at which a load is triggered. `0` fires as soon
+     * as a single pixel of the sentinel is visible.
+     * @default 0
+     */
+    threshold?: number | number[];
+    /**
+     * The scroll container used as the observer root. `null` (default) uses the
+     * browser viewport. Pass a scrollable element (e.g. `containerRef.current`)
+     * to run infinite scroll inside a fixed-height panel.
+     * @default null
+     */
+    root?: Element | Document | null;
+}
+/**
+ * The value returned by {@link useInfiniteScroll}: a callback ref to attach to
+ * the sentinel element (typically an empty `<div>` at the end of the list).
+ *
+ * @example
+ * ```tsx
+ * const sentinelRef = useInfiniteScroll(loadMore, { hasMore, loading });
+ * return <div ref={sentinelRef} />;
+ * ```
+ */
+type UseInfiniteScrollRef = (node: Element | null) => void;
+
+/**
+ * Sentinel-driven infinite scrolling built on the Intersection Observer API.
+ *
+ * Attach the returned callback ref to a small sentinel element rendered at the
+ * end of your list. Whenever that sentinel scrolls into view — and there is
+ * more to load, nothing is currently loading, and the hook is enabled — your
+ * `loadMore` callback fires exactly **once** per intersection.
+ *
+ * Built on top of {@link useIntersectionObserver}, so it inherits its SSR-safe
+ * (returns an inert no-op ref on the server) and StrictMode-safe behavior.
+ *
+ * Key guarantees:
+ * - **Fires once per intersection.** It does not re-fire while the sentinel
+ *   stays in view; the sentinel must leave and re-enter to trigger again.
+ * - **Latest-callback pattern.** Changing `loadMore` (or the `hasMore` /
+ *   `loading` / `enabled` flags) never re-subscribes the observer.
+ * - **No double-fire while loading.** Respects the `loading` flag *and* an
+ *   internal in-flight guard: if `loadMore` returns a promise, the hook will
+ *   not fire again until it settles.
+ * - **Stops observing when exhausted.** Once `hasMore` is `false` (or `enabled`
+ *   is `false`), the observer disconnects entirely.
+ *
+ * @param loadMore - Called to load the next page. May be sync or async.
+ * @param options - Configuration (`hasMore`, `loading`, `enabled`, `rootMargin`,
+ *   `threshold`, `root`).
+ * @returns A callback ref to attach to the sentinel element.
+ *
+ * @example
+ * ```tsx
+ * function Feed() {
+ *   const [items, setItems] = useState<Item[]>([]);
+ *   const [loading, setLoading] = useState(false);
+ *   const [hasMore, setHasMore] = useState(true);
+ *
+ *   const loadMore = async () => {
+ *     setLoading(true);
+ *     const { data, done } = await fetchNextPage(items.length);
+ *     setItems((prev) => [...prev, ...data]);
+ *     setHasMore(!done);
+ *     setLoading(false);
+ *   };
+ *
+ *   const sentinelRef = useInfiniteScroll(loadMore, { hasMore, loading });
+ *
+ *   return (
+ *     <ul>
+ *       {items.map((item) => (
+ *         <li key={item.id}>{item.title}</li>
+ *       ))}
+ *       {hasMore && <li ref={sentinelRef} aria-hidden />}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Prefetch 300px early, inside a fixed-height scroll container.
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const sentinelRef = useInfiniteScroll(loadMore, {
+ *   hasMore,
+ *   loading,
+ *   root: containerRef.current,
+ *   rootMargin: "300px",
+ * });
+ * ```
+ */
+declare function useInfiniteScroll(loadMore: LoadMoreFn, options?: UseInfiniteScrollOptions): UseInfiniteScrollRef;
+
+export { type LoadMoreFn, type UseInfiniteScrollOptions, type UseInfiniteScrollRef, useInfiniteScroll };

package/dist/index.js

@@ -0,0 +1,94 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useInfiniteScroll: () => useInfiniteScroll
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useInfiniteScroll.ts
+var import_react = require("react");
+var import_use_intersection_observer = require("@usefy/use-intersection-observer");
+function useInfiniteScroll(loadMore, options = {}) {
+  const {
+    hasMore = true,
+    loading = false,
+    enabled = true,
+    rootMargin = "0px",
+    threshold = 0,
+    root = null
+  } = options;
+  const loadMoreRef = (0, import_react.useRef)(loadMore);
+  loadMoreRef.current = loadMore;
+  const stateRef = (0, import_react.useRef)({ hasMore, loading, enabled });
+  stateRef.current = { hasMore, loading, enabled };
+  const inFlightRef = (0, import_react.useRef)(false);
+  const prevInViewRef = (0, import_react.useRef)(false);
+  const fireLoadMore = (0, import_react.useCallback)(() => {
+    const state = stateRef.current;
+    if (!state.enabled || !state.hasMore || state.loading || inFlightRef.current) {
+      return;
+    }
+    inFlightRef.current = true;
+    let result;
+    try {
+      result = loadMoreRef.current();
+    } catch (error) {
+      inFlightRef.current = false;
+      throw error;
+    }
+    if (result && typeof result.then === "function") {
+      const release = () => {
+        inFlightRef.current = false;
+      };
+      Promise.resolve(result).then(release, release);
+    } else {
+      inFlightRef.current = false;
+    }
+  }, []);
+  const handleChange = (0, import_react.useCallback)(
+    (_entry, inView) => {
+      if (inView && !prevInViewRef.current) {
+        fireLoadMore();
+      }
+      prevInViewRef.current = inView;
+    },
+    [fireLoadMore]
+  );
+  const { ref } = (0, import_use_intersection_observer.useIntersectionObserver)({
+    root,
+    rootMargin,
+    threshold,
+    // Disconnect the observer entirely when there is nothing more to load or the
+    // hook is disabled — there is no point observing a sentinel we will never
+    // act on. `loading` is intentionally *not* folded in here: we keep observing
+    // while a load is in flight (the fire guard handles it) so we don't lose the
+    // sentinel's position mid-request.
+    enabled: enabled && hasMore,
+    onChange: handleChange
+  });
+  return ref;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useInfiniteScroll
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useInfiniteScroll.ts"],"sourcesContent":["export { useInfiniteScroll } from \"./useInfiniteScroll\";\nexport type {\n  LoadMoreFn,\n  UseInfiniteScrollOptions,\n  UseInfiniteScrollRef,\n} from \"./types\";\n","import { useCallback, useRef } from \"react\";\nimport {\n  useIntersectionObserver,\n  type OnChangeCallback,\n} from \"@usefy/use-intersection-observer\";\nimport type {\n  LoadMoreFn,\n  UseInfiniteScrollOptions,\n  UseInfiniteScrollRef,\n} from \"./types\";\n\n/**\n * Sentinel-driven infinite scrolling built on the Intersection Observer API.\n *\n * Attach the returned callback ref to a small sentinel element rendered at the\n * end of your list. Whenever that sentinel scrolls into view — and there is\n * more to load, nothing is currently loading, and the hook is enabled — your\n * `loadMore` callback fires exactly **once** per intersection.\n *\n * Built on top of {@link useIntersectionObserver}, so it inherits its SSR-safe\n * (returns an inert no-op ref on the server) and StrictMode-safe behavior.\n *\n * Key guarantees:\n * - **Fires once per intersection.** It does not re-fire while the sentinel\n *   stays in view; the sentinel must leave and re-enter to trigger again.\n * - **Latest-callback pattern.** Changing `loadMore` (or the `hasMore` /\n *   `loading` / `enabled` flags) never re-subscribes the observer.\n * - **No double-fire while loading.** Respects the `loading` flag *and* an\n *   internal in-flight guard: if `loadMore` returns a promise, the hook will\n *   not fire again until it settles.\n * - **Stops observing when exhausted.** Once `hasMore` is `false` (or `enabled`\n *   is `false`), the observer disconnects entirely.\n *\n * @param loadMore - Called to load the next page. May be sync or async.\n * @param options - Configuration (`hasMore`, `loading`, `enabled`, `rootMargin`,\n *   `threshold`, `root`).\n * @returns A callback ref to attach to the sentinel element.\n *\n * @example\n * ```tsx\n * function Feed() {\n *   const [items, setItems] = useState<Item[]>([]);\n *   const [loading, setLoading] = useState(false);\n *   const [hasMore, setHasMore] = useState(true);\n *\n *   const loadMore = async () => {\n *     setLoading(true);\n *     const { data, done } = await fetchNextPage(items.length);\n *     setItems((prev) => [...prev, ...data]);\n *     setHasMore(!done);\n *     setLoading(false);\n *   };\n *\n *   const sentinelRef = useInfiniteScroll(loadMore, { hasMore, loading });\n *\n *   return (\n *     <ul>\n *       {items.map((item) => (\n *         <li key={item.id}>{item.title}</li>\n *       ))}\n *       {hasMore && <li ref={sentinelRef} aria-hidden />}\n *     </ul>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Prefetch 300px early, inside a fixed-height scroll container.\n * const containerRef = useRef<HTMLDivElement>(null);\n * const sentinelRef = useInfiniteScroll(loadMore, {\n *   hasMore,\n *   loading,\n *   root: containerRef.current,\n *   rootMargin: \"300px\",\n * });\n * ```\n */\nexport function useInfiniteScroll(\n  loadMore: LoadMoreFn,\n  options: UseInfiniteScrollOptions = {}\n): UseInfiniteScrollRef {\n  const {\n    hasMore = true,\n    loading = false,\n    enabled = true,\n    rootMargin = \"0px\",\n    threshold = 0,\n    root = null,\n  } = options;\n\n  // Latest-callback pattern: mirror the callback and flags into refs so that a\n  // changing `loadMore` (or flags) never re-subscribes the observer.\n  const loadMoreRef = useRef<LoadMoreFn>(loadMore);\n  loadMoreRef.current = loadMore;\n\n  const stateRef = useRef({ hasMore, loading, enabled });\n  stateRef.current = { hasMore, loading, enabled };\n\n  // Internal in-flight guard for the async case, independent of the `loading`\n  // prop: prevents a second fire while a returned promise is still pending.\n  const inFlightRef = useRef(false);\n\n  // Tracks the sentinel's previous visibility so we fire on the `false -> true`\n  // transition only. Without this, a multi-threshold observer (e.g.\n  // `threshold: [0, 0.5, 1]`) emits several `inView === true` callbacks as the\n  // sentinel scrolls in; a synchronous `loadMore` (one that never sets\n  // `loading`) would otherwise fire once per crossing.\n  const prevInViewRef = useRef(false);\n\n  const fireLoadMore = useCallback(() => {\n    const state = stateRef.current;\n    if (!state.enabled || !state.hasMore || state.loading || inFlightRef.current) {\n      return;\n    }\n\n    inFlightRef.current = true;\n\n    let result: void | Promise<void>;\n    try {\n      result = loadMoreRef.current();\n    } catch (error) {\n      // Synchronous throw: release the guard so a later intersection can retry,\n      // then rethrow (mirrors the caller invoking loadMore directly).\n      inFlightRef.current = false;\n      throw error;\n    }\n\n    if (result && typeof (result as Promise<void>).then === \"function\") {\n      const release = () => {\n        inFlightRef.current = false;\n      };\n      // Handle both settle paths so the guard is always released and a rejected\n      // promise does not surface as an unhandled rejection. The hook does not\n      // itself surface loadMore errors — handle them inside loadMore.\n      Promise.resolve(result).then(release, release);\n    } else {\n      inFlightRef.current = false;\n    }\n  }, []);\n\n  const handleChange = useCallback<OnChangeCallback>(\n    (_entry, inView) => {\n      // Fire only on the transition into view, so a multi-threshold observer\n      // that emits several `inView === true` callbacks per entry triggers a\n      // single load.\n      if (inView && !prevInViewRef.current) {\n        fireLoadMore();\n      }\n      prevInViewRef.current = inView;\n    },\n    [fireLoadMore]\n  );\n\n  const { ref } = useIntersectionObserver({\n    root,\n    rootMargin,\n    threshold,\n    // Disconnect the observer entirely when there is nothing more to load or the\n    // hook is disabled — there is no point observing a sentinel we will never\n    // act on. `loading` is intentionally *not* folded in here: we keep observing\n    // while a load is in flight (the fire guard handles it) so we don't lose the\n    // sentinel's position mid-request.\n    enabled: enabled && hasMore,\n    onChange: handleChange,\n  });\n\n  return ref;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAAoC;AACpC,uCAGO;AA0EA,SAAS,kBACd,UACA,UAAoC,CAAC,GACf;AACtB,QAAM;AAAA,IACJ,UAAU;AAAA,IACV,UAAU;AAAA,IACV,UAAU;AAAA,IACV,aAAa;AAAA,IACb,YAAY;AAAA,IACZ,OAAO;AAAA,EACT,IAAI;AAIJ,QAAM,kBAAc,qBAAmB,QAAQ;AAC/C,cAAY,UAAU;AAEtB,QAAM,eAAW,qBAAO,EAAE,SAAS,SAAS,QAAQ,CAAC;AACrD,WAAS,UAAU,EAAE,SAAS,SAAS,QAAQ;AAI/C,QAAM,kBAAc,qBAAO,KAAK;AAOhC,QAAM,oBAAgB,qBAAO,KAAK;AAElC,QAAM,mBAAe,0BAAY,MAAM;AACrC,UAAM,QAAQ,SAAS;AACvB,QAAI,CAAC,MAAM,WAAW,CAAC,MAAM,WAAW,MAAM,WAAW,YAAY,SAAS;AAC5E;AAAA,IACF;AAEA,gBAAY,UAAU;AAEtB,QAAI;AACJ,QAAI;AACF,eAAS,YAAY,QAAQ;AAAA,IAC/B,SAAS,OAAO;AAGd,kBAAY,UAAU;AACtB,YAAM;AAAA,IACR;AAEA,QAAI,UAAU,OAAQ,OAAyB,SAAS,YAAY;AAClE,YAAM,UAAU,MAAM;AACpB,oBAAY,UAAU;AAAA,MACxB;AAIA,cAAQ,QAAQ,MAAM,EAAE,KAAK,SAAS,OAAO;AAAA,IAC/C,OAAO;AACL,kBAAY,UAAU;AAAA,IACxB;AAAA,EACF,GAAG,CAAC,CAAC;AAEL,QAAM,mBAAe;AAAA,IACnB,CAAC,QAAQ,WAAW;AAIlB,UAAI,UAAU,CAAC,cAAc,SAAS;AACpC,qBAAa;AAAA,MACf;AACA,oBAAc,UAAU;AAAA,IAC1B;AAAA,IACA,CAAC,YAAY;AAAA,EACf;AAEA,QAAM,EAAE,IAAI,QAAI,0DAAwB;AAAA,IACtC;AAAA,IACA;AAAA,IACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAMA,SAAS,WAAW;AAAA,IACpB,UAAU;AAAA,EACZ,CAAC;AAED,SAAO;AACT;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,69 @@
+// src/useInfiniteScroll.ts
+import { useCallback, useRef } from "react";
+import {
+  useIntersectionObserver
+} from "@usefy/use-intersection-observer";
+function useInfiniteScroll(loadMore, options = {}) {
+  const {
+    hasMore = true,
+    loading = false,
+    enabled = true,
+    rootMargin = "0px",
+    threshold = 0,
+    root = null
+  } = options;
+  const loadMoreRef = useRef(loadMore);
+  loadMoreRef.current = loadMore;
+  const stateRef = useRef({ hasMore, loading, enabled });
+  stateRef.current = { hasMore, loading, enabled };
+  const inFlightRef = useRef(false);
+  const prevInViewRef = useRef(false);
+  const fireLoadMore = useCallback(() => {
+    const state = stateRef.current;
+    if (!state.enabled || !state.hasMore || state.loading || inFlightRef.current) {
+      return;
+    }
+    inFlightRef.current = true;
+    let result;
+    try {
+      result = loadMoreRef.current();
+    } catch (error) {
+      inFlightRef.current = false;
+      throw error;
+    }
+    if (result && typeof result.then === "function") {
+      const release = () => {
+        inFlightRef.current = false;
+      };
+      Promise.resolve(result).then(release, release);
+    } else {
+      inFlightRef.current = false;
+    }
+  }, []);
+  const handleChange = useCallback(
+    (_entry, inView) => {
+      if (inView && !prevInViewRef.current) {
+        fireLoadMore();
+      }
+      prevInViewRef.current = inView;
+    },
+    [fireLoadMore]
+  );
+  const { ref } = useIntersectionObserver({
+    root,
+    rootMargin,
+    threshold,
+    // Disconnect the observer entirely when there is nothing more to load or the
+    // hook is disabled — there is no point observing a sentinel we will never
+    // act on. `loading` is intentionally *not* folded in here: we keep observing
+    // while a load is in flight (the fire guard handles it) so we don't lose the
+    // sentinel's position mid-request.
+    enabled: enabled && hasMore,
+    onChange: handleChange
+  });
+  return ref;
+}
+export {
+  useInfiniteScroll
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useInfiniteScroll.ts"],"sourcesContent":["import { useCallback, useRef } from \"react\";\nimport {\n  useIntersectionObserver,\n  type OnChangeCallback,\n} from \"@usefy/use-intersection-observer\";\nimport type {\n  LoadMoreFn,\n  UseInfiniteScrollOptions,\n  UseInfiniteScrollRef,\n} from \"./types\";\n\n/**\n * Sentinel-driven infinite scrolling built on the Intersection Observer API.\n *\n * Attach the returned callback ref to a small sentinel element rendered at the\n * end of your list. Whenever that sentinel scrolls into view — and there is\n * more to load, nothing is currently loading, and the hook is enabled — your\n * `loadMore` callback fires exactly **once** per intersection.\n *\n * Built on top of {@link useIntersectionObserver}, so it inherits its SSR-safe\n * (returns an inert no-op ref on the server) and StrictMode-safe behavior.\n *\n * Key guarantees:\n * - **Fires once per intersection.** It does not re-fire while the sentinel\n *   stays in view; the sentinel must leave and re-enter to trigger again.\n * - **Latest-callback pattern.** Changing `loadMore` (or the `hasMore` /\n *   `loading` / `enabled` flags) never re-subscribes the observer.\n * - **No double-fire while loading.** Respects the `loading` flag *and* an\n *   internal in-flight guard: if `loadMore` returns a promise, the hook will\n *   not fire again until it settles.\n * - **Stops observing when exhausted.** Once `hasMore` is `false` (or `enabled`\n *   is `false`), the observer disconnects entirely.\n *\n * @param loadMore - Called to load the next page. May be sync or async.\n * @param options - Configuration (`hasMore`, `loading`, `enabled`, `rootMargin`,\n *   `threshold`, `root`).\n * @returns A callback ref to attach to the sentinel element.\n *\n * @example\n * ```tsx\n * function Feed() {\n *   const [items, setItems] = useState<Item[]>([]);\n *   const [loading, setLoading] = useState(false);\n *   const [hasMore, setHasMore] = useState(true);\n *\n *   const loadMore = async () => {\n *     setLoading(true);\n *     const { data, done } = await fetchNextPage(items.length);\n *     setItems((prev) => [...prev, ...data]);\n *     setHasMore(!done);\n *     setLoading(false);\n *   };\n *\n *   const sentinelRef = useInfiniteScroll(loadMore, { hasMore, loading });\n *\n *   return (\n *     <ul>\n *       {items.map((item) => (\n *         <li key={item.id}>{item.title}</li>\n *       ))}\n *       {hasMore && <li ref={sentinelRef} aria-hidden />}\n *     </ul>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Prefetch 300px early, inside a fixed-height scroll container.\n * const containerRef = useRef<HTMLDivElement>(null);\n * const sentinelRef = useInfiniteScroll(loadMore, {\n *   hasMore,\n *   loading,\n *   root: containerRef.current,\n *   rootMargin: \"300px\",\n * });\n * ```\n */\nexport function useInfiniteScroll(\n  loadMore: LoadMoreFn,\n  options: UseInfiniteScrollOptions = {}\n): UseInfiniteScrollRef {\n  const {\n    hasMore = true,\n    loading = false,\n    enabled = true,\n    rootMargin = \"0px\",\n    threshold = 0,\n    root = null,\n  } = options;\n\n  // Latest-callback pattern: mirror the callback and flags into refs so that a\n  // changing `loadMore` (or flags) never re-subscribes the observer.\n  const loadMoreRef = useRef<LoadMoreFn>(loadMore);\n  loadMoreRef.current = loadMore;\n\n  const stateRef = useRef({ hasMore, loading, enabled });\n  stateRef.current = { hasMore, loading, enabled };\n\n  // Internal in-flight guard for the async case, independent of the `loading`\n  // prop: prevents a second fire while a returned promise is still pending.\n  const inFlightRef = useRef(false);\n\n  // Tracks the sentinel's previous visibility so we fire on the `false -> true`\n  // transition only. Without this, a multi-threshold observer (e.g.\n  // `threshold: [0, 0.5, 1]`) emits several `inView === true` callbacks as the\n  // sentinel scrolls in; a synchronous `loadMore` (one that never sets\n  // `loading`) would otherwise fire once per crossing.\n  const prevInViewRef = useRef(false);\n\n  const fireLoadMore = useCallback(() => {\n    const state = stateRef.current;\n    if (!state.enabled || !state.hasMore || state.loading || inFlightRef.current) {\n      return;\n    }\n\n    inFlightRef.current = true;\n\n    let result: void | Promise<void>;\n    try {\n      result = loadMoreRef.current();\n    } catch (error) {\n      // Synchronous throw: release the guard so a later intersection can retry,\n      // then rethrow (mirrors the caller invoking loadMore directly).\n      inFlightRef.current = false;\n      throw error;\n    }\n\n    if (result && typeof (result as Promise<void>).then === \"function\") {\n      const release = () => {\n        inFlightRef.current = false;\n      };\n      // Handle both settle paths so the guard is always released and a rejected\n      // promise does not surface as an unhandled rejection. The hook does not\n      // itself surface loadMore errors — handle them inside loadMore.\n      Promise.resolve(result).then(release, release);\n    } else {\n      inFlightRef.current = false;\n    }\n  }, []);\n\n  const handleChange = useCallback<OnChangeCallback>(\n    (_entry, inView) => {\n      // Fire only on the transition into view, so a multi-threshold observer\n      // that emits several `inView === true` callbacks per entry triggers a\n      // single load.\n      if (inView && !prevInViewRef.current) {\n        fireLoadMore();\n      }\n      prevInViewRef.current = inView;\n    },\n    [fireLoadMore]\n  );\n\n  const { ref } = useIntersectionObserver({\n    root,\n    rootMargin,\n    threshold,\n    // Disconnect the observer entirely when there is nothing more to load or the\n    // hook is disabled — there is no point observing a sentinel we will never\n    // act on. `loading` is intentionally *not* folded in here: we keep observing\n    // while a load is in flight (the fire guard handles it) so we don't lose the\n    // sentinel's position mid-request.\n    enabled: enabled && hasMore,\n    onChange: handleChange,\n  });\n\n  return ref;\n}\n"],"mappings":";AAAA,SAAS,aAAa,cAAc;AACpC;AAAA,EACE;AAAA,OAEK;AA0EA,SAAS,kBACd,UACA,UAAoC,CAAC,GACf;AACtB,QAAM;AAAA,IACJ,UAAU;AAAA,IACV,UAAU;AAAA,IACV,UAAU;AAAA,IACV,aAAa;AAAA,IACb,YAAY;AAAA,IACZ,OAAO;AAAA,EACT,IAAI;AAIJ,QAAM,cAAc,OAAmB,QAAQ;AAC/C,cAAY,UAAU;AAEtB,QAAM,WAAW,OAAO,EAAE,SAAS,SAAS,QAAQ,CAAC;AACrD,WAAS,UAAU,EAAE,SAAS,SAAS,QAAQ;AAI/C,QAAM,cAAc,OAAO,KAAK;AAOhC,QAAM,gBAAgB,OAAO,KAAK;AAElC,QAAM,eAAe,YAAY,MAAM;AACrC,UAAM,QAAQ,SAAS;AACvB,QAAI,CAAC,MAAM,WAAW,CAAC,MAAM,WAAW,MAAM,WAAW,YAAY,SAAS;AAC5E;AAAA,IACF;AAEA,gBAAY,UAAU;AAEtB,QAAI;AACJ,QAAI;AACF,eAAS,YAAY,QAAQ;AAAA,IAC/B,SAAS,OAAO;AAGd,kBAAY,UAAU;AACtB,YAAM;AAAA,IACR;AAEA,QAAI,UAAU,OAAQ,OAAyB,SAAS,YAAY;AAClE,YAAM,UAAU,MAAM;AACpB,oBAAY,UAAU;AAAA,MACxB;AAIA,cAAQ,QAAQ,MAAM,EAAE,KAAK,SAAS,OAAO;AAAA,IAC/C,OAAO;AACL,kBAAY,UAAU;AAAA,IACxB;AAAA,EACF,GAAG,CAAC,CAAC;AAEL,QAAM,eAAe;AAAA,IACnB,CAAC,QAAQ,WAAW;AAIlB,UAAI,UAAU,CAAC,cAAc,SAAS;AACpC,qBAAa;AAAA,MACf;AACA,oBAAc,UAAU;AAAA,IAC1B;AAAA,IACA,CAAC,YAAY;AAAA,EACf;AAEA,QAAM,EAAE,IAAI,IAAI,wBAAwB;AAAA,IACtC;AAAA,IACA;AAAA,IACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAMA,SAAS,WAAW;AAAA,IACpB,UAAU;AAAA,EACZ,CAAC;AAED,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@usefy/use-infinite-scroll",
+  "version": "0.20.0",
+  "description": "A React hook for sentinel-driven infinite scrolling built on IntersectionObserver",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@usefy/use-intersection-observer": "0.20.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mirunamu00/usefy.git",
+    "directory": "packages/hooks/use-infinite-scroll"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "infinite-scroll",
+    "infinite-loading",
+    "intersection-observer",
+    "sentinel",
+    "load-more",
+    "pagination",
+    "lazy-loading",
+    "useInfiniteScroll"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}