oihana-next-ui 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oihana-next-ui",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "private": false,
   "description": "Oihana Next.js UI component library — reusable components, hooks and utilities built with React 19, Next.js, Tailwind CSS and DaisyUI",
   "author": {

package/src/@configs/navigation.js

@@ -23,6 +23,7 @@ import { IoMdGrid               as GridIcon           } from "react-icons/io";
 import { FaPager                as HeaderIcon         } from "react-icons/fa6";
 import { SlPicture              as ImageIcon          } from "react-icons/sl";
 import { RiInputField           as InputIcon          } from "react-icons/ri" ;
+import { TbInfinity             as InfiniteScrollIcon } from "react-icons/tb";
 import { LuLayoutDashboard      as LayoutIcon         } from "react-icons/lu";
 import { CiBoxList              as ListIcon           } from "react-icons/ci";
 import { RiProgress7Line        as LoadingIcon        } from "react-icons/ri";
@@ -73,12 +74,13 @@ const navigation =
                 Icon : LayoutIcon ,
                 items :
                 [
-                    { id : 'flex'     , type : LINK  , Icon : FlexIcon     , path  : '/lab/flex'     } ,
-                    { id : 'grid'     , type : LINK  , Icon : GridIcon     , path  : '/lab/grid'     } ,
-                    { id : 'masonry'  , type : LINK  , Icon : MasonryIcon  , path  : '/lab/masonry'  } ,
-                    { id : 'layout'   , type : LINK  , Icon : LayoutIcon   , path  : '/lab/layout'   } ,
-                    { id : 'collapse' , type : LINK  , Icon : CollapseIcon , path  : '/lab/collapse' } ,
-                    { id : 'patterns' , type : LINK  , Icon : PatternsIcon , path  : '/lab/patterns' } ,
+                    { id : 'flex'           , type : LINK  , Icon : FlexIcon           , path  : '/lab/flex'           } ,
+                    { id : 'grid'           , type : LINK  , Icon : GridIcon           , path  : '/lab/grid'           } ,
+                    { id : 'masonry'        , type : LINK  , Icon : MasonryIcon        , path  : '/lab/masonry'        } ,
+                    { id : 'infiniteScroll' , type : LINK  , Icon : InfiniteScrollIcon , path  : '/lab/infiniteScroll' } ,
+                    { id : 'layout'         , type : LINK  , Icon : LayoutIcon         , path  : '/lab/layout'         } ,
+                    { id : 'collapse'       , type : LINK  , Icon : CollapseIcon       , path  : '/lab/collapse'       } ,
+                    { id : 'patterns'       , type : LINK  , Icon : PatternsIcon       , path  : '/lab/patterns'       } ,
                 ]
             } ,
             {

package/src/@locale/navigation.js

@@ -25,6 +25,7 @@ const navigation =
                 grid           : 'Grid' ,
                 layout         : 'Layout' ,
                 masonry        : 'Masonry' ,
+                infiniteScroll : 'Scroll infini' ,
                 table          : 'Table' ,
             feedback     : 'Feedback' ,
                 loading        : 'Loading' ,
@@ -73,6 +74,7 @@ const navigation =
                 grid           : 'Grid' ,
                 layout         : 'Layout' ,
                 masonry        : 'Masonry' ,
+                infiniteScroll : 'Infinite Scroll' ,
                 table          : 'Table' ,
             feedback     : 'Feedback' ,
                 loading        : 'Loading' ,

package/src/app/lab/@tabs/infiniteScroll/page.js

@@ -0,0 +1,26 @@
+'use client' ;
+
+import Page               from '@/display/Page' ;
+import Container          from '@/display/Container' ;
+import InfiniteScrollDemo from '@/demo/layouts/InfiniteScrollDemo' ;
+
+/**
+ * InfiniteScroll showcase page.
+ */
+const InfiniteScrollPage = () =>
+(
+    <Page className="gap-8" full>
+        {/* Header */}
+        <Container className="text-center" maxWidth="max-w-4xl">
+            <h1 className="text-4xl font-bold bg-linear-to-r from-secondary to-primary inline-block text-transparent bg-clip-text">
+                Infinite Scroll
+            </h1>
+        </Container>
+
+        <Container maxWidth="max-w-3xl">
+            <InfiniteScrollDemo />
+        </Container>
+    </Page>
+) ;
+
+export default InfiniteScrollPage ;

package/src/components/layouts/InfiniteScroll.jsx

@@ -0,0 +1,172 @@
+'use client' ;
+
+import { useRef } from 'react' ;
+
+import Loading from '@/components/Loading' ;
+
+import useInfiniteScroll from '@/hooks/useInfiniteScroll' ;
+
+import cn from '@/themes/helpers/cn' ;
+
+/**
+ * Default root element type for the InfiniteScroll container.
+ * @type {string}
+ */
+export const DEFAULT_ELEMENT = 'div' ;
+
+/**
+ * Class applied to the container when `scrollable` is enabled.
+ * @type {string}
+ */
+export const SCROLLABLE_CLASS = 'overflow-y-auto' ;
+
+/**
+ * Class applied to the (visually empty) sentinel element.
+ * @type {string}
+ */
+export const SENTINEL_CLASS = 'h-px w-full' ;
+
+/**
+ * Class applied to the default loading indicator wrapper.
+ * @type {string}
+ */
+export const LOADER_WRAPPER_CLASS = 'flex justify-center py-4' ;
+
+/**
+ * Class applied to the container in `reverse` mode (chat-like). Lays children
+ * out bottom-to-top so the scroll stays anchored at the bottom : prepending
+ * older items does not shift the visible content.
+ * @type {string}
+ */
+export const REVERSE_CLASS = 'flex flex-col-reverse' ;
+
+/**
+ * InfiniteScroll — renders its children, then watches a sentinel element to
+ * load more content when the user scrolls near the edge of the list.
+ *
+ * Headless by design : it does not render the list itself, it wraps whatever
+ * you pass as `children` and manages the sentinel plus the loading / end
+ * indicators. Loading is paused while `loading` is true and stops once
+ * `hasMore` becomes false.
+ *
+ * @module components/layouts/InfiniteScroll
+ *
+ * @param {Object} props
+ * @param {React.ElementType} [props.as='div']           - HTML element or component to render as the container.
+ * @param {React.ReactNode}   [props.children]           - The already-loaded content.
+ * @param {string}            [props.className]          - Additional class names for the container.
+ * @param {React.ReactNode}   [props.endMessage=null]    - Shown when `hasMore` is false.
+ * @param {boolean}           [props.hasMore=true]       - Whether more items can be loaded.
+ * @param {React.ReactNode}   [props.loader]             - Custom loading indicator (defaults to `<Loading />`).
+ * @param {boolean}           [props.loading=false]      - Loading-in-flight state.
+ * @param {Function}          [props.onLoadMore]         - Called when the sentinel is reached. Should be stable (`useCallback`).
+ * @param {boolean}           [props.reverse=false]      - Reverse / chat mode : lays children out bottom-to-top (`flex flex-col-reverse`) and loads older items when scrolling up. Children must be ordered newest-first.
+ * @param {string}            [props.rootMargin]         - Pre-load distance before the sentinel is reached.
+ * @param {boolean}           [props.scrollable=false]   - When true, the container is the scroll viewport and the observer root.
+ * @param {number}            [props.threshold]          - Visibility threshold (0-1).
+ *
+ * @example
+ * ```jsx
+ * // Forward infinite scroll over a List
+ * <InfiniteScroll
+ *     hasMore={ hasMore }
+ *     loading={ loading }
+ *     onLoadMore={ loadNextPage }
+ *     endMessage={ <p className="text-center opacity-60 py-4">No more items</p> }
+ * >
+ *     <List>
+ *         { items.map( item => <ListRow key={ item.id } title={ item.title } /> ) }
+ *     </List>
+ * </InfiniteScroll>
+ *
+ * // Scrollable container with a fixed height (internal scroll viewport)
+ * <InfiniteScroll
+ *     scrollable
+ *     className="max-h-96"
+ *     hasMore={ hasMore }
+ *     loading={ loading }
+ *     onLoadMore={ loadNextPage }
+ * >
+ *     { rows }
+ * </InfiniteScroll>
+ *
+ * // Reverse / chat mode (older messages load when scrolling up).
+ * // `flex flex-col-reverse` is applied automatically ; pass messages newest-first.
+ * <InfiniteScroll
+ *     reverse
+ *     scrollable
+ *     className="max-h-96"
+ *     hasMore={ hasMore }
+ *     loading={ loading }
+ *     onLoadMore={ loadOlderMessages }
+ * >
+ *     { messagesNewestFirst.map( m => <ChatBubble key={ m.id } { ...m } /> ) }
+ * </InfiniteScroll>
+ * ```
+ */
+const InfiniteScroll =
+({
+    as ,
+    children ,
+    className ,
+    endMessage = null ,
+    hasMore    = true ,
+    loader ,
+    loading    = false ,
+    onLoadMore ,
+    reverse    = false ,
+    rootMargin ,
+    scrollable = false ,
+    threshold ,
+}) =>
+{
+    const Component = as ?? DEFAULT_ELEMENT ;
+
+    /** @type {React.RefObject<HTMLElement>} - Container used as observer root when scrollable. */
+    const rootRef = useRef( null ) ;
+
+    const { ref : sentinelRef } = useInfiniteScroll
+    ({
+        hasMore ,
+        loading ,
+        onLoadMore ,
+        root : scrollable ? rootRef : null ,
+        rootMargin ,
+        threshold ,
+    }) ;
+
+    // --------- Building blocks
+
+    const sentinel = hasMore
+        ? <div ref={ sentinelRef } aria-hidden="true" className={ SENTINEL_CLASS } />
+        : null ;
+
+    const indicator = loading
+        ? ( loader ?? <div className={ LOADER_WRAPPER_CLASS }><Loading /></div> )
+        : null ;
+
+    const footer = !hasMore ? endMessage : null ;
+
+    // --------- Render container
+    //
+    // DOM order is always [ children , indicator , sentinel , footer ].
+    // In `reverse` mode the container is laid out bottom-to-top (flex-col-reverse),
+    // so the sentinel / indicator / footer naturally end up at the visual top and
+    // the scroll stays anchored at the bottom.
+
+    return (
+        <Component
+            className = { cn( scrollable && SCROLLABLE_CLASS , reverse && REVERSE_CLASS , className ) }
+            ref       = { rootRef }
+        >
+            { children }
+            { indicator }
+            { sentinel }
+            { footer }
+        </Component>
+    ) ;
+} ;
+
+InfiniteScroll.displayName = 'InfiniteScroll' ;
+
+export default InfiniteScroll ;

package/src/demo/layouts/InfiniteScrollDemo.jsx

@@ -0,0 +1,343 @@
+'use client' ;
+
+import { useCallback , useEffect , useState } from 'react' ;
+
+import InfiniteScroll from '@/components/layouts/InfiniteScroll' ;
+import List           from '@/components/lists/List' ;
+import ListRow        from '@/components/lists/ListRow' ;
+
+/**
+ * Number of items appended on each load.
+ * @type {number}
+ */
+const PAGE_SIZE = 15 ;
+
+/**
+ * Total number of items available in the simulated dataset.
+ * @type {number}
+ */
+const TOTAL_ITEMS = 75 ;
+
+/**
+ * Simulated network latency, in milliseconds.
+ * @type {number}
+ */
+const LATENCY = 700 ;
+
+/**
+ * Simulates a paginated API call returning a slice of items.
+ *
+ * @param {number} page - Zero-based page index to fetch.
+ * @returns {Promise<{ items: Array<{ id: number, title: string, subtitle: string }>, hasMore: boolean }>}
+ */
+const fetchPage = ( page ) => new Promise( resolve =>
+{
+    setTimeout( () =>
+    {
+        const start = page * PAGE_SIZE ;
+        const end   = Math.min( start + PAGE_SIZE , TOTAL_ITEMS ) ;
+
+        const items = [] ;
+
+        for ( let i = start ; i < end ; i++ )
+        {
+            items.push
+            ({
+                id       : i + 1 ,
+                title    : `Item #${ i + 1 }` ,
+                subtitle : `Loaded on page ${ page + 1 }` ,
+            }) ;
+        }
+
+        resolve({ items , hasMore : end < TOTAL_ITEMS }) ;
+    }
+    , LATENCY ) ;
+}) ;
+
+// ============================================================================
+//  Reverse / chat demo
+// ============================================================================
+
+/**
+ * Number of messages loaded on each "load older" request.
+ * @type {number}
+ */
+const CHAT_PAGE_SIZE = 8 ;
+
+/**
+ * Side of the conversation a speaker sits on.
+ */
+const START = 'start' ;
+const END   = 'end' ;
+
+/**
+ * Avatars used by the two speakers.
+ */
+const KENOBI_AVATAR = 'https://img.daisyui.com/images/profile/demo/kenobee@192.webp' ;
+const ANAKIN_AVATAR = 'https://img.daisyui.com/images/profile/demo/anakeen@192.webp' ;
+
+/**
+ * Bubble color (DaisyUI) used for the "current user" (Anakin).
+ * @type {string}
+ */
+const OWN_BUBBLE_COLOR = 'chat-bubble-primary' ;
+
+/**
+ * The conversation, ordered oldest → newest. Each line alternates between
+ * Obi-Wan (chat-start) and Anakin (chat-end).
+ */
+const SCRIPT =
+[
+    [ 'obiwan' , 'It was said that you would destroy the Sith, not join them.' ] ,
+    [ 'anakin' , "Don't lecture me, Obi-Wan." ] ,
+    [ 'obiwan' , 'It was you who would bring balance to the Force…' ] ,
+    [ 'anakin' , 'I should have known the Jedi were plotting to take over.' ] ,
+    [ 'obiwan' , '…not leave it in Darkness.' ] ,
+    [ 'anakin' , "If you're not with me, then you're my enemy." ] ,
+    [ 'obiwan' , 'Only a Sith deals in absolutes.' ] ,
+    [ 'anakin' , 'You will try.' ] ,
+    [ 'obiwan' , 'You were the Chosen One!' ] ,
+    [ 'anakin' , 'I hate you!' ] ,
+    [ 'obiwan' , 'You were my brother, Anakin.' ] ,
+    [ 'obiwan' , 'I loved you.' ] ,
+    [ 'anakin' , 'What kind of nonsense is this?' ] ,
+    [ 'anakin' , 'Put me on the Council and not make me a Master!?' ] ,
+    [ 'obiwan' , 'Anakin, calm down.' ] ,
+    [ 'anakin' , "That's never been done in the history of the Jedi." ] ,
+    [ 'anakin' , "It's insulting!" ] ,
+    [ 'obiwan' , 'You have been given a great honor.' ] ,
+    [ 'obiwan' , 'To be on the Council at your age…' ] ,
+    [ 'obiwan' , "It's never happened before." ] ,
+    [ 'anakin' , 'The Council wants me to spy on the Chancellor?' ] ,
+    [ 'obiwan' , 'The Council is asking you.' ] ,
+    [ 'anakin' , 'This is treason.' ] ,
+    [ 'obiwan' , 'Be mindful of your thoughts, Anakin.' ] ,
+    [ 'anakin' , 'I have brought peace, freedom, justice…' ] ,
+    [ 'obiwan' , 'Your new empire?!' ] ,
+    [ 'anakin' , "Don't make me kill you." ] ,
+    [ 'obiwan' , 'I will do what I must.' ] ,
+] ;
+
+/**
+ * Builds the full conversation as message objects, oldest → newest.
+ *
+ * @returns {Array<{ id: number, side: string, author: string, avatar: string, color: string, text: string, time: string }>}
+ */
+const buildConversation = () => SCRIPT.map( ( [ speaker , text ] , index ) =>
+{
+    const isObiwan = speaker === 'obiwan' ;
+
+    const hours   = 12 + Math.floor( index / 60 ) ;
+    const minutes = index % 60 ;
+
+    return {
+        id     : index + 1 ,
+        side   : isObiwan ? START : END ,
+        author : isObiwan ? 'Obi-Wan Kenobi' : 'Anakin' ,
+        avatar : isObiwan ? KENOBI_AVATAR : ANAKIN_AVATAR ,
+        color  : isObiwan ? '' : OWN_BUBBLE_COLOR ,
+        text   ,
+        time   : `${ hours }:${ String( minutes ).padStart( 2 , '0' ) }` ,
+    } ;
+} ) ;
+
+/**
+ * Full conversation, computed once.
+ */
+const CONVERSATION = buildConversation() ;
+
+/**
+ * A single chat message, rendered with DaisyUI chat bubble classes.
+ *
+ * @param {Object} props
+ * @param {string} props.author - Author name shown in the header.
+ * @param {string} props.avatar - Author image URL.
+ * @param {string} props.color  - DaisyUI chat-bubble color class.
+ * @param {string} props.side   - 'start' or 'end'.
+ * @param {string} props.text   - Message body.
+ * @param {string} props.time   - Timestamp shown in the header.
+ */
+const ChatMessage =
+({
+    author ,
+    avatar ,
+    color ,
+    side ,
+    text ,
+    time ,
+}) =>
+(
+    <div className={ `chat ${ side === END ? 'chat-end' : 'chat-start' }` }>
+        <div className="chat-image avatar">
+            <div className="w-10 rounded-full">
+                <img alt={ author } src={ avatar } />
+            </div>
+        </div>
+        <div className="chat-header text-xs">
+            { author }
+            <time className="opacity-50 ml-1">{ time }</time>
+        </div>
+        <div className={ `chat-bubble ${ color }` }>{ text }</div>
+    </div>
+) ;
+
+/**
+ * Chat panel : a reverse infinite scroll that loads older messages when the
+ * user scrolls up. Messages are kept oldest → newest in state and rendered
+ * newest-first, as required by `<InfiniteScroll reverse>`.
+ */
+const ChatPanel = () =>
+{
+    const [ loaded  , setLoaded  ] = useState( [] ) ;
+    const [ loading , setLoading ] = useState( false ) ;
+    const [ hasMore , setHasMore ] = useState( true ) ;
+
+    // --------- Prepend the previous (older) page of messages
+
+    const loadOlder = useCallback( async () =>
+    {
+        if ( loading || !hasMore )
+        {
+            return ;
+        }
+
+        setLoading( true ) ;
+
+        await new Promise( resolve => setTimeout( resolve , LATENCY ) ) ;
+
+        const remaining = CONVERSATION.length - loaded.length ;
+        const start     = Math.max( 0 , remaining - CHAT_PAGE_SIZE ) ;
+        const older     = CONVERSATION.slice( start , remaining ) ;
+
+        setLoaded( prev => [ ...older , ...prev ] ) ;
+        setHasMore( start > 0 ) ;
+        setLoading( false ) ;
+    }
+    , [ hasMore , loaded.length , loading ] ) ;
+
+    // --------- Initial load (most recent page)
+
+    useEffect( () =>
+    {
+        loadOlder() ;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    } , [] ) ;
+
+    return (
+        <InfiniteScroll
+            className  = "max-h-96 p-4 gap-1 rounded-box border border-base-300 bg-base-100"
+            endMessage = {
+                <p className="text-center text-xs opacity-60 py-2">
+                    — Beginning of the conversation —
+                </p>
+            }
+            hasMore    = { hasMore }
+            loading    = { loading }
+            onLoadMore = { loadOlder }
+            reverse
+            scrollable
+        >
+            { [ ...loaded ].reverse().map( message => (
+                <ChatMessage key={ message.id } { ...message } />
+            ) ) }
+        </InfiniteScroll>
+    ) ;
+} ;
+
+/**
+ * InfiniteScroll showcase : a forward scrollable list and a reverse chat panel,
+ * both lazily loading paginated content.
+ */
+const InfiniteScrollDemo = () =>
+{
+    const [ items   , setItems   ] = useState( [] ) ;
+    const [ page    , setPage    ] = useState( 0 ) ;
+    const [ loading , setLoading ] = useState( false ) ;
+    const [ hasMore , setHasMore ] = useState( true ) ;
+
+    // --------- Append the next page, guarding against concurrent loads
+
+    const loadMore = useCallback( async () =>
+    {
+        if ( loading || !hasMore )
+        {
+            return ;
+        }
+
+        setLoading( true ) ;
+
+        const { items : newItems , hasMore : more } = await fetchPage( page ) ;
+
+        setItems( prev => [ ...prev , ...newItems ] ) ;
+        setHasMore( more ) ;
+        setPage( prev => prev + 1 ) ;
+        setLoading( false ) ;
+    }
+    , [ hasMore , loading , page ] ) ;
+
+    // --------- Initial load
+
+    useEffect( () =>
+    {
+        loadMore() ;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    } , [] ) ;
+
+    return (
+        <div className="flex flex-col gap-8">
+
+            {/* Forward scroll */}
+            <div className="card bg-base-200 shadow-xl">
+                <div className="card-body">
+
+                    <h2 className="card-title text-2xl mb-2">Scrollable container</h2>
+                    <p className="text-sm opacity-70 mb-4">
+                        { items.length } / { TOTAL_ITEMS } items loaded — scroll down to load more.
+                    </p>
+
+                    <InfiniteScroll
+                        className  = "max-h-96 py-2 rounded-box border border-base-300 bg-base-100"
+                        endMessage = {
+                            <p className="text-center text-sm opacity-60 py-4">
+                                — End of the list —
+                            </p>
+                        }
+                        hasMore    = { hasMore }
+                        loading    = { loading }
+                        onLoadMore = { loadMore }
+                        scrollable
+                    >
+                        <List>
+                            { items.map( item => (
+                                <ListRow
+                                    key      = { item.id }
+                                    title    = { item.title }
+                                    subtitle = { item.subtitle }
+                                />
+                            ) ) }
+                        </List>
+                    </InfiniteScroll>
+
+                </div>
+            </div>
+
+            {/* Reverse / chat */}
+            <div className="card bg-base-200 shadow-xl">
+                <div className="card-body">
+
+                    <h2 className="card-title text-2xl mb-2">Reverse mode — chat</h2>
+                    <p className="text-sm opacity-70 mb-4">
+                        Scroll up to load older messages. New messages stay pinned at the
+                        bottom and the scroll position never jumps.
+                    </p>
+
+                    <ChatPanel />
+
+                </div>
+            </div>
+
+        </div>
+    ) ;
+} ;
+
+export default InfiniteScrollDemo ;

package/src/helpers/react/resolveRefElement.js

@@ -0,0 +1,26 @@
+/**
+ * Resolves a DOM element from either a React ref object or a raw element.
+ *
+ * Useful when an API (IntersectionObserver, ResizeObserver, …) expects a DOM
+ * element but the caller may provide either a ref or the element directly.
+ *
+ * @param {React.RefObject<Element>|Element|null} [target] - Ref object, element or null.
+ * @returns {Element|null} The resolved DOM element, or null.
+ *
+ * @example
+ * ```js
+ * resolveRefElement( myRef ) ;     // → myRef.current
+ * resolveRefElement( domNode ) ;   // → domNode
+ * resolveRefElement( null ) ;      // → null
+ * ```
+ */
+const resolveRefElement = ( target ) =>
+{
+    if ( target && typeof target === 'object' && 'current' in target )
+    {
+        return target.current ;
+    }
+    return target ?? null ;
+} ;
+
+export default resolveRefElement ;

package/src/hooks/useInfiniteScroll.js

@@ -0,0 +1,100 @@
+'use client' ;
+
+import { useEffect , useRef } from 'react' ;
+
+import resolveRefElement from '@/helpers/react/resolveRefElement' ;
+
+/**
+ * Default distance, before the sentinel is reached, at which loading is triggered.
+ * @type {string}
+ */
+export const DEFAULT_ROOT_MARGIN = '200px' ;
+
+/**
+ * Default visibility threshold passed to the IntersectionObserver.
+ * @type {number}
+ */
+export const DEFAULT_THRESHOLD = 0 ;
+
+/**
+ * Hook that invokes a callback when a sentinel element scrolls into view.
+ *
+ * Building block for infinite scrolling / "load more on scroll". Attach the
+ * returned `ref` to a sentinel element placed at the edge of your list ; when
+ * that sentinel enters the viewport (or the scrollable `root`), `onLoadMore`
+ * is called. Observation is paused while `loading` is true and stops once
+ * `hasMore` becomes false.
+ *
+ * Note : `onLoadMore` should be stable (wrap it in `useCallback`), otherwise
+ * the observer is recreated on every render.
+ *
+ * @param {Object} [options]
+ * @param {boolean}  [options.hasMore=true]                  - Whether more items can be loaded.
+ * @param {boolean}  [options.loading=false]                 - Pauses observation while a load is in flight.
+ * @param {Function} [options.onLoadMore]                    - Called when the sentinel becomes visible.
+ * @param {React.RefObject<Element>|Element|null} [options.root=null] - Scrollable container used as observer root ; defaults to the viewport.
+ * @param {string}   [options.rootMargin=DEFAULT_ROOT_MARGIN]- Pre-load distance before the sentinel is reached.
+ * @param {number}   [options.threshold=DEFAULT_THRESHOLD]   - Visibility threshold (0-1).
+ *
+ * @returns {{ ref: React.RefObject<HTMLElement> }} Ref to attach to the sentinel element.
+ *
+ * @example
+ * ```js
+ * const onLoadMore = useCallback( () => loadNextPage() , [ loadNextPage ] ) ;
+ * const { ref } = useInfiniteScroll({ hasMore , loading , onLoadMore }) ;
+ *
+ * <ul>
+ *     { items.map( item => <li key={ item.id }>{ item.label }</li> ) }
+ *     <li ref={ ref } aria-hidden="true" />
+ * </ul>
+ * ```
+ */
+const useInfiniteScroll =
+({
+    hasMore    = true ,
+    loading    = false ,
+    onLoadMore ,
+    root       = null ,
+    rootMargin = DEFAULT_ROOT_MARGIN ,
+    threshold  = DEFAULT_THRESHOLD ,
+}
+= {}) =>
+{
+    /** @type {React.RefObject<HTMLElement>} */
+    const ref = useRef( null ) ;
+
+    useEffect( () =>
+    {
+        const element = ref.current ;
+
+        if ( !element || !hasMore || loading )
+        {
+            return ;
+        }
+
+        const observer = new IntersectionObserver
+        (
+            ( [ entry ] ) =>
+            {
+                if ( entry.isIntersecting )
+                {
+                    onLoadMore?.() ;
+                }
+            } ,
+            {
+                root       : resolveRefElement( root ) ,
+                rootMargin ,
+                threshold  ,
+            }
+        ) ;
+
+        observer.observe( element ) ;
+
+        return () => observer.disconnect() ;
+    }
+    , [ hasMore , loading , onLoadMore , root , rootMargin , threshold ] ) ;
+
+    return { ref } ;
+} ;
+
+export default useInfiniteScroll ;

package/src/version.js

@@ -1,3 +1,3 @@
-const version = "0.2.1" ;
+const version = "0.2.2" ;
 
 export default version ;