fix: unify paginator interface (#1803)

* feat: add deprecation warning logger utility function

* feat: unify paginator interface

* feat: add React SDK scoped classes to ChannelListMessenger elements

* feat: add popper tooltip to SimpleReactionList items (#1801)

* fix: log deprecation warnings only on mount

* refactor: do not use LoadingIndicator prop in InfiniteScroll

* style: do not state the exact version for removal of deprecated props

* docs: describe how to use InfiniteScroll with ChannelList

Co-authored-by: Petyo Ivanov <[email protected]>
Co-authored-by: Anton Arnautov <[email protected]>

Author: 3 people

docusaurus/docs/React/custom-code-examples/channel-list-infinite-scroll.mdx

@@ -0,0 +1,72 @@
+---
+id: channel-list-infinite-scroll
+sidebar_position: 24
+title: Channel List Infinite Scroll
+keywords: [channel list, infinite scroll]
+---
+
+import GHComponentLink from '../_docusaurus-components/GHComponentLink';
+
+This example demonstrates how to implement infinite scroll with existing SDK components. By default, the SDK's `ChannelList` component uses `LoadMorePaginator` to load more channels into the list. More channels are loaded every time the `LoadMoreButton` is clicked. The infinite scroll instead loads more channels based on the channel list container's scroll position. The request to load more channels is automatically triggered, once the scroller approaches the bottom scroll threshold of the container.
+
+## How to plug in the infinite scroll
+
+The SDK provides own [`InfiniteScroll`](https://github.com/GetStream/stream-chat-react/blob/master/src/components/InfiniteScrollPaginator/InfiniteScroll.tsx) component. This component implements the [`PaginatorProps`](https://github.com/GetStream/stream-chat-react/blob/master/src/types/types.ts) interface. As this interface is implemented by the [`LoadMorePaginator`](https://github.com/GetStream/stream-chat-react/blob/master/src/components/LoadMore/LoadMorePaginator.ts) too, we can just pass the `InfiniteScroll` into the `ChannelList` prop `Paginator`.
+
+```tsx
+import {
+  ChannelList,
+  InfiniteScroll,
+} from 'stream-chat-react';
+
+<ChannelList filters={filters} sort={sort} options={options}
+             Paginator={InfiniteScroll}
+             showChannelSearch
+/>
+```
+
+If you would like to adjust the configuration parameters like `threshold`, `reverse` (`PaginatorProps`) or `useCapture`, etc. (`InfiniteScrollProps`), you can create a wrapper component where these props can be set:
+
+```tsx
+import {
+  ChannelList,
+  InfiniteScroll,
+  InfiniteScrollProps
+} from 'stream-chat-react';
+
+
+const Paginator = (props: InfiniteScrollProps) => <InfiniteScroll {...props} threshold={50} />;
+
+...
+<ChannelList filters={filters} sort={sort} options={options}
+             Paginator={Paginator}
+             showChannelSearch
+/>
+```
+
+Especially the `threshold` prop may need to be set as the default is 250px. That may be too soon to load more channels.
+
+## What to take into consideration
+
+For the infinite scroll to work, the element containing the `ChannelPreview` list has to be forced to display the scroll bar with the initial channel list load. This is achieved by:
+
+**1. adjusting the initial number of loaded channels**
+
+Set a reasonable number of channels to be initially loaded. If loading 10 channels leads to them being visible without having to scroll, then increase the number to e.g. 15:
+
+```tsx
+import type { ChannelOptions } from 'stream-chat';
+const options: ChannelOptions = { state: true, presence: true, limit: 15 };
+```
+
+**2. adjusting the container height**
+
+You can change the container height so that not all channels are visible at once. You should target the container with class `.str-chat__channel-list-messenger-react__main`
+
+```css
+.str-chat__channel-list-messenger-react__main {
+    max-height: 50%;
+}
+```
+
+

src/components/ChannelList/ChannelList.tsx

@@ -317,7 +317,8 @@ const UnMemoizedChannelList = <
   const className = clsx(
     customClasses?.chat ?? 'str-chat',
     theme,
-    customClasses?.channelList ?? 'str-chat-channel-list str-chat__channel-list',
+    customClasses?.channelList ??
+      'str-chat-channel-list str-chat__channel-list str-chat__channel-list-react',
     {
       'str-chat--windows-flags': useImageFlagEmojisOnWindows && navigator.userAgent.match(/Win/),
       'str-chat-channel-list--open': navOpen,
@@ -350,8 +351,8 @@ const UnMemoizedChannelList = <
             ) : (
               <Paginator
                 hasNextPage={hasNextPage}
+                isLoading={channelsQueryState.queryInProgress === 'load-more'}
                 loadNextPage={loadNextPage}
-                refreshing={channelsQueryState.queryInProgress === 'load-more'}
               >
                 {renderChannels
                   ? renderChannels(loadedChannels, renderChannel)

src/components/ChannelList/ChannelListMessenger.tsx

@@ -49,10 +49,10 @@ export const ChannelListMessenger = <
   }
 
   return (
-    <div className='str-chat__channel-list-messenger'>
+    <div className='str-chat__channel-list-messenger str-chat__channel-list-messenger-react'>
       <div
         aria-label='Channel list'
-        className='str-chat__channel-list-messenger__main'
+        className='str-chat__channel-list-messenger__main str-chat__channel-list-messenger-react__main'
         role='listbox'
       >
         {children}

src/components/ChannelList/__tests__/__snapshots__/ChannelListMessenger.test.js.snap

@@ -2,11 +2,11 @@
 
 exports[`ChannelListMessenger by default, children should be rendered 1`] = `
 <div
-  className="str-chat__channel-list-messenger"
+  className="str-chat__channel-list-messenger str-chat__channel-list-messenger-react"
 >
   <div
     aria-label="Channel list"
-    className="str-chat__channel-list-messenger__main"
+    className="str-chat__channel-list-messenger__main str-chat__channel-list-messenger-react__main"
     role="listbox"
   >
     <div>

src/components/InfiniteScrollPaginator/InfiniteScroll.tsx

@@ -1,4 +1,6 @@
 import React, { PropsWithChildren, useCallback, useEffect, useRef } from 'react';
+import type { PaginatorProps } from '../../types/types';
+import { deprecationAndReplacementWarning } from '../../utils/deprecationWarning';
 
 /**
  * Prevents Chrome hangups
@@ -10,43 +12,66 @@ const mousewheelListener = (event: Event) => {
   }
 };
 
-export type InfiniteScrollProps = {
+export type InfiniteScrollProps = PaginatorProps & {
   className?: string;
   element?: React.ElementType;
+  /**
+   * @desc Flag signalling whether more pages with older items can be loaded
+   * @deprecated Use hasPreviousPage prop instead. Planned for removal: https://github.com/GetStream/stream-chat-react/issues/1804
+   */
   hasMore?: boolean;
+  /**
+   * @desc Flag signalling whether more pages with newer items can be loaded
+   * @deprecated Use hasNextPage prop instead. Planned for removal: https://github.com/GetStream/stream-chat-react/issues/1804
+   */
   hasMoreNewer?: boolean;
-  /** Element to be rendered at the top of the thread message list. By default Message and ThreadStart components */
+  /** Element to be rendered at the top of the thread message list. By default, Message and ThreadStart components */
   head?: React.ReactNode;
   initialLoad?: boolean;
   isLoading?: boolean;
   listenToScroll?: (offset: number, reverseOffset: number, threshold: number) => void;
   loader?: React.ReactNode;
-  loading?: React.ReactNode;
+  /**
+   * @desc Function that loads previous page with older items
+   * @deprecated Use loadPreviousPage prop instead. Planned for removal: https://github.com/GetStream/stream-chat-react/issues/1804
+   */
   loadMore?: () => void;
+  /**
+   * @desc Function that loads next page with newer items
+   * @deprecated Use loadNextPage prop instead. Planned for removal: https://github.com/GetStream/stream-chat-react/issues/1804
+   */
   loadMoreNewer?: () => void;
   pageStart?: number;
-  threshold?: number;
   useCapture?: boolean;
 };
 
 export const InfiniteScroll = (props: PropsWithChildren<InfiniteScrollProps>) => {
   const {
     children,
     element = 'div',
-    hasMore = false,
-    hasMoreNewer = false,
+    hasMore,
+    hasMoreNewer,
+    hasNextPage,
+    hasPreviousPage,
     head,
     initialLoad = true,
-    isLoading = false,
+    isLoading,
     listenToScroll,
     loader,
     loadMore,
     loadMoreNewer,
+    loadNextPage,
+    loadPreviousPage,
     threshold = 250,
     useCapture = false,
     ...elementProps
   } = props;
 
+  const loadNextPageFn = loadNextPage || loadMoreNewer;
+  const loadPreviousPageFn = loadPreviousPage || loadMore;
+  const hasNextPageFlag = hasNextPage || hasMoreNewer;
+  const hasPreviousPageFlag = hasPreviousPage || hasMore;
+
   const scrollComponent = useRef<HTMLElement>();
 
   const scrollListener = useCallback(() => {
@@ -66,14 +91,37 @@ export const InfiniteScroll = (props: PropsWithChildren<InfiniteScrollProps>) =>
       listenToScroll(offset, reverseOffset, threshold);
     }
 
-    if (reverseOffset < Number(threshold) && typeof loadMore === 'function' && hasMore) {
-      loadMore();
+    if (
+      reverseOffset < Number(threshold) &&
+      typeof loadPreviousPageFn === 'function' &&
+      hasPreviousPageFlag
+    ) {
+      loadPreviousPageFn();
     }
 
-    if (offset < Number(threshold) && typeof loadMoreNewer === 'function' && hasMoreNewer) {
-      loadMoreNewer();
+    if (offset < Number(threshold) && typeof loadNextPageFn === 'function' && hasNextPageFlag) {
+      loadNextPageFn();
     }
-  }, [hasMore, hasMoreNewer, threshold, listenToScroll, loadMore, loadMoreNewer]);
+  }, [
+    hasPreviousPageFlag,
+    hasNextPageFlag,
+    threshold,
+    listenToScroll,
+    loadPreviousPageFn,
+    loadNextPageFn,
+  ]);
+
+  useEffect(() => {
+    deprecationAndReplacementWarning(
+      [
+        [{ hasMoreNewer }, { hasNextPage }],
+        [{ loadMoreNewer }, { loadNextPage }],
+        [{ hasMore }, { hasPreviousPage }],
+        [{ loadMore }, { loadPreviousPage }],
+      ],
+      'InfiniteScroll',
+    );
+  }, []);
 
   useEffect(() => {
     const scrollElement = scrollComponent.current?.parentNode;

src/components/InfiniteScrollPaginator/__tests__/InfiniteScroll.test.js

@@ -1,11 +1,11 @@
 import React from 'react';
-import { render } from '@testing-library/react';
+import { fireEvent, render } from '@testing-library/react';
 import '@testing-library/jest-dom';
 import renderer from 'react-test-renderer';
 
 import { InfiniteScroll } from '../';
 
-const loadMore = jest.fn().mockImplementation(() => Promise.resolve());
+const loadPreviousPage = jest.fn().mockImplementation(() => Promise.resolve());
 
 // Note: testing actual infinite scroll behavior is very tricky / pointless because Jest does not
 // really implement offsetHeight / offsetTop / offsetParent etc. This means we'd have to mock basically everything,
@@ -24,7 +24,7 @@ describe('InfiniteScroll', () => {
   const renderComponent = (props) => {
     const renderResult = render(
       <div data-testid='scroll-parent'>
-        <InfiniteScroll loadMore={loadMore} {...props} />
+        <InfiniteScroll loadPreviousPage={loadPreviousPage} {...props} />
       </div>,
     );
     const scrollParent = renderResult.getByTestId('scroll-parent');
@@ -35,7 +35,7 @@ describe('InfiniteScroll', () => {
     'should bind scroll, mousewheel and resize events to the right target with useCapture as %s',
     (useCapture) => {
       renderComponent({
-        hasMore: true,
+        hasPreviousPage: true,
         useCapture,
       });
 
@@ -53,7 +53,7 @@ describe('InfiniteScroll', () => {
     'should unbind scroll, mousewheel and resize events from the right target with useCapture as %s',
     (useCapture) => {
       const { unmount } = renderComponent({
-        hasMore: true,
+        hasPreviousPage: true,
         useCapture,
       });
 
@@ -77,11 +77,48 @@ describe('InfiniteScroll', () => {
     },
   );
 
+  it.each([
+    ['hasMoreNewer', 'loadMoreNewer', 'hasNextPage', 'loadNextPage'],
+    ['hasMore', 'loadMore', 'hasPreviousPage', 'loadPreviousPage'],
+  ])(
+    'deprecates %s and %s in favor of %s and %s',
+    (deprecatedFlag, deprecatedLoader, newFlag, newLoader) => {
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => null);
+      const oldLoaderSpy = jest.fn();
+      const newLoaderSpy = jest.fn();
+
+      const { scrollParent } = renderComponent({
+        [deprecatedFlag]: false,
+        [deprecatedLoader]: oldLoaderSpy,
+        [newFlag]: true,
+        [newLoader]: newLoaderSpy,
+        threshold: Infinity,
+      });
+
+      Object.defineProperty(HTMLElement.prototype, 'offsetParent', {
+        get() {
+          return this.parentNode;
+        },
+      });
+      fireEvent.scroll(scrollParent);
+
+      consoleWarnSpy.mockRestore();
+
+      expect(oldLoaderSpy).not.toHaveBeenCalled();
+      // eslint-disable-next-line jest/prefer-called-with
+      expect(newLoaderSpy).toHaveBeenCalled();
+    },
+  );
+
   describe('Rendering loader', () => {
     const getRenderResult = () =>
       renderer
         .create(
-          <InfiniteScroll isLoading loader={<div key='loader'>loader</div>} loadMore={loadMore}>
+          <InfiniteScroll
+            isLoading
+            loader={<div key='loader'>loader</div>}
+            loadPreviousPage={loadPreviousPage}
+          >
             Content
           </InfiniteScroll>,
         )

src/components/LoadMore/LoadMoreButton.tsx

@@ -1,26 +1,41 @@
-import React, { PropsWithChildren } from 'react';
+import React, { PropsWithChildren, useEffect } from 'react';
 import { LoadingIndicator } from '../Loading';
+import { deprecationAndReplacementWarning } from '../../utils/deprecationWarning';
 
 export type LoadMoreButtonProps = {
   /** onClick handler load more button. Pagination logic should be executed in this handler. */
   onClick: React.MouseEventHandler<HTMLButtonElement>;
-  /** If true, LoadingIndicator is displayed instead of button */
+  /** indicates whether a loading request is in progress */
+  isLoading?: boolean;
+  /**
+   * @desc If true, LoadingIndicator is displayed instead of button
+   * @deprecated Use loading prop instead of refreshing. Planned for removal: https://github.com/GetStream/stream-chat-react/issues/1804
+   */
   refreshing?: boolean;
 };
 
-const UnMemoizedLoadMoreButton = (props: PropsWithChildren<LoadMoreButtonProps>) => {
-  const { children = 'Load more', onClick, refreshing } = props;
+const UnMemoizedLoadMoreButton = ({
+  children = 'Load more',
+  isLoading,
+  onClick,
+  refreshing,
+}: PropsWithChildren<LoadMoreButtonProps>) => {
+  const loading = typeof isLoading !== 'undefined' ? isLoading : refreshing;
+
+  useEffect(() => {
+    deprecationAndReplacementWarning([[{ refreshing }, { isLoading }]], 'LoadMoreButton');
+  }, []);
 
   return (
     <div className='str-chat__load-more-button'>
       <button
         aria-label='Load More Channels'
         className='str-chat__load-more-button__button str-chat__cta-button'
         data-testid='load-more-button'
-        disabled={refreshing}
+        disabled={loading}
         onClick={onClick}
       >
-        {refreshing ? <LoadingIndicator /> : children}
+        {loading ? <LoadingIndicator /> : children}
       </button>
     </div>
   );