fix: rename ChannelListMessenger to ChannelListUI (#3036)

## Renamed Components

| Old Name | New Name | Notes |
| ---------------------- | --------------- |
-------------------------------------------------------------------------------------------------------
|
| `ChannelListMessenger` | `ChannelListUI` | File renamed
`ChannelListMessenger.tsx` → `ChannelListUI.tsx`; export renamed in
`ChannelList/index.ts` |

## Renamed Types / Interfaces

| Old Name | New Name | Notes |
| --------------------------- | -------------------- |
------------------------------------ |
| `ChannelListMessengerProps` | `ChannelListUIProps` | Props type for
the renamed component |

## Renamed CSS Classes

| Old Name | New Name |
| ---------------------------------------- |
------------------------------------ |
| `str-chat__channel-list-messenger` | `str-chat__channel-list-inner` |
| `str-chat__channel-list-messenger__main` |
`str-chat__channel-list-inner__main` |

## Removed Props

### `ChannelListProps` (on `<ChannelList>`)

| Removed Prop | Type | Migration |
| ----------------------- |
------------------------------------------------- |
-------------------------------------------------------------- |
| `Avatar` | `React.ComponentType<ChannelAvatarProps>` | Use `Avatar`
slot slot in `ComponentContext` instead |
| `List` | `React.ComponentType<ChannelListMessengerProps>` | Use
`ChannelListUI` slot in `ComponentContext` instead |
| `LoadingErrorIndicator` |
`React.ComponentType<LoadingErrorIndicatorProps>` | Use
`LoadingErrorIndicator` slot in `ComponentContext` instead |
| `LoadingIndicator` | `React.ComponentType` | Use `LoadingIndicator`
slot in `ComponentContext` instead |
| `Preview` | `React.ComponentType<ChannelListItemUIProps>` | Use
`ChannelListItemUI` slot in `ComponentContext` instead |

### `ChannelListItemProps` (on `<ChannelListItem>`)

| Removed Prop | Type | Migration |
| ------------ | ----------------------------------------- |
-------------------------------------------------------------- |
| `Avatar` | `React.ComponentType<ChannelAvatarProps>` | Now sourced
from `ComponentContext` inside `ChannelListItemUI` |

### `ChannelListUIProps` (previously `ChannelListMessengerProps`)

| Removed Prop | Type | Migration |
| ----------------------- |
------------------------------------------------- |
---------------------------------------------------------- |
| `LoadingErrorIndicator` |
`React.ComponentType<LoadingErrorIndicatorProps>` | Now sourced from
`ComponentContext` inside `ChannelListUI` |
| `LoadingIndicator` | `React.ComponentType` | Now sourced from
`ComponentContext` inside `ChannelListUI` |

## New `ComponentContext` Slots

| Slot | Type | Description |
| --------------- | ----------------------------------------- |
--------------------------------------------------------------------------------------------
|
| `ChannelListUI` | `React.ComponentType<ChannelListUIProps>` | Custom
UI component for the channel list container (replaces `List` prop on
`<ChannelList>`) |

## Other Breaking Changes

- **Removed CSS class suffix:** The root `<ChannelList>` element no
longer applies the `str-chat__channel-list-react` class. Previously the
default was `str-chat__channel-list str-chat__channel-list-react`, now
it is just `str-chat__channel-list`.


BREAKING CHANGE: The `ChannelListMessenger` component has been renamed
to `ChannelListUI` (props type `ChannelListMessengerProps` ->
`ChannelListUIProps`). The corresponding CSS classes
`str-chat__channel-list-messenger` and
`str-chat__channel-list-messenger__main` have been renamed to
`str-chat__channel-list-inner` and `str-chat__channel-list-inner__main`
respectively. The `Avatar`, `List`, `LoadingErrorIndicator`,
`LoadingIndicator`, and `Preview` props have been removed from the
`ChannelList` component. The `Avatar` prop has also been removed from
`ChannelListItem`, and the `LoadingErrorIndicator` and
`LoadingIndicator` props have been removed from `ChannelListUI`. All of
these component overrides should now be provided through
`ComponentContext` instead of being passed as props directly. A new
`ChannelListUI` slot has been added to `ComponentContext`, replacing the
former `List` prop on `ChannelList`. Additionally, the
`str-chat__channel-list-react` CSS class is no longer applied to the
root `ChannelList` element.

Author: arnautov-anton

examples/vite/src/ChatLayout/Panels.tsx

@@ -63,14 +63,20 @@ export const ChannelsPanels = ({
         })}
         ref={channelsLayoutRef}
       >
-        <ChannelList
-          Avatar={ChannelAvatar}
-          customActiveChannel={initialChannelId}
-          filters={filters}
-          options={options}
-          sort={sort}
-          showChannelSearch
-        />
+        <WithComponents
+          overrides={{
+            // @ts-expect-error TODO: adjust the sizing
+            Avatar: ChannelAvatar,
+          }}
+        >
+          <ChannelList
+            customActiveChannel={initialChannelId}
+            filters={filters}
+            options={options}
+            sort={sort}
+            showChannelSearch
+          />
+        </WithComponents>
         <SidebarResizeHandle layoutRef={channelsLayoutRef} />
         <WithComponents overrides={{ TypingIndicator }}>
           <Channel>

src/components/ChannelList/ChannelList.tsx

@@ -19,16 +19,11 @@ import {
   usePrepareShapeHandlers,
 } from './hooks/useChannelListShape';
 import { useStateStore } from '../../store';
-import type { ChannelListMessengerProps } from './ChannelListMessenger';
-import { ChannelListMessenger } from './ChannelListMessenger';
-import type { ChannelAvatarProps } from '../Avatar';
-import { Avatar as DefaultAvatar } from '../Avatar';
-import type { ChannelListItemUIProps } from '../ChannelListItem/ChannelListItem';
+import { ChannelListUI as DefaultChannelListUI } from './ChannelListUI';
 import { ChannelListItem } from '../ChannelListItem/ChannelListItem';
 import { Search as DefaultSearch } from '../Search';
 import type { EmptyStateIndicatorProps } from '../EmptyStateIndicator';
 import { EmptyStateIndicator as DefaultEmptyStateIndicator } from '../EmptyStateIndicator';
-import { LoadingChannels } from '../Loading/LoadingChannels';
 import type { LoadMorePaginatorProps } from '../LoadMore/LoadMorePaginator';
 import { LoadMorePaginator } from '../LoadMore/LoadMorePaginator';
 import { NotificationList as DefaultNotificationList } from '../Notifications';
@@ -39,11 +34,9 @@ import {
   useChatContext,
   useComponentContext,
 } from '../../context';
-import { NullComponent } from '../UtilityComponents';
 import { moveChannelUpwards } from './utils';
 import type { TranslationContextValue } from '../../context/TranslationContext';
 import type { PaginatorProps } from '../../types/types';
-import type { LoadingErrorIndicatorProps } from '../Loading';
 import { ChannelListHeader } from './ChannelListHeader';
 import { useStableId } from '../UtilityComponents/useStableId';
 
@@ -63,8 +56,6 @@ export type ChannelListProps = {
    * to false, which will prevent channels not in the list from incrementing the list. The default is true.
    */
   allowNewMessagesFromUnfilteredChannels?: boolean;
-  /** UI component to display an avatar, defaults to [Avatar](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Avatar/Avatar.tsx) component and accepts the same props as: [ChannelAvatar](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Avatar/ChannelAvatar.tsx) */
-  Avatar?: React.ComponentType<ChannelAvatarProps>;
   /** Optional function to filter channels prior to loading in the DOM. Do not use any complex or async logic that would delay the loading of the ChannelList. We recommend using a pure function with array methods like filter/sort/reduce. */
   channelRenderFilterFn?: (channels: Array<Channel>) => Array<Channel>;
   // FIXME: how is this even legal (WHY IS IT STRING?!)
@@ -83,12 +74,6 @@ export type ChannelListProps = {
     userLanguage: TranslationContextValue['userLanguage'],
     isMessageAIGenerated?: ChatContextValue['isMessageAIGenerated'],
   ) => ReactNode;
-  /** Custom UI component to display the container for the queried channels, defaults to and accepts same props as: [ChannelListMessenger](https://github.com/GetStream/stream-chat-react/blob/master/src/components/ChannelList/ChannelListMessenger.tsx) */
-  List?: React.ComponentType<ChannelListMessengerProps>;
-  /** Custom UI component to display the loading error indicator, defaults to component that renders null */
-  LoadingErrorIndicator?: React.ComponentType<LoadingErrorIndicatorProps>;
-  /** Custom UI component to display the loading state, defaults to and accepts same props as: [LoadingChannels](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Loading/LoadingChannels.tsx) */
-  LoadingIndicator?: React.ComponentType;
   /** When true, channels won't dynamically sort by most recent message */
   lockChannelOrder?: boolean;
   /** Function to override the default behavior when a user is added to a channel, corresponds to [notification.added\_to\_channel](https://getstream.io/chat/docs/javascript/event_object/?language=javascript) event */
@@ -140,8 +125,6 @@ export type ChannelListProps = {
   options?: ChannelOptions;
   /** Custom UI component to handle channel pagination logic, defaults to and accepts same props as: [LoadMorePaginator](https://github.com/GetStream/stream-chat-react/blob/master/src/components/LoadMore/LoadMorePaginator.tsx) */
   Paginator?: React.ComponentType<PaginatorProps | LoadMorePaginatorProps>;
-  /** Custom UI component to display the channel preview in the list, defaults to and accepts same props as: [ChannelPreviewMessenger](https://github.com/GetStream/stream-chat-react/blob/master/src/components/ChannelPreview/ChannelPreviewMessenger.tsx) */
-  Preview?: React.ComponentType<ChannelListItemUIProps>;
   /**
    * Custom interval during which the recovery channel list queries will be prevented.
    * This is to avoid firing unnecessary queries during internet connection fluctuation.
@@ -169,16 +152,12 @@ export type ChannelListProps = {
 const UnMemoizedChannelList = (props: ChannelListProps) => {
   const {
     allowNewMessagesFromUnfilteredChannels = true,
-    Avatar = DefaultAvatar,
     channelRenderFilterFn,
     customActiveChannel,
     customQueryChannels,
     EmptyStateIndicator = DefaultEmptyStateIndicator,
     filters = {},
     getLatestMessagePreview,
-    List = ChannelListMessenger,
-    LoadingErrorIndicator = NullComponent,
-    LoadingIndicator = LoadingChannels,
     lockChannelOrder = false,
     onAddedToChannel,
     onChannelDeleted,
@@ -191,7 +170,6 @@ const UnMemoizedChannelList = (props: ChannelListProps) => {
     onRemovedFromChannel,
     options,
     Paginator = LoadMorePaginator,
-    Preview,
     recoveryThrottleIntervalMs,
     renderChannels,
     sendChannelsToList = false,
@@ -215,8 +193,12 @@ const UnMemoizedChannelList = (props: ChannelListProps) => {
     theme,
     useImageFlagEmojisOnWindows,
   } = useChatContext('ChannelList');
-  const { NotificationList = DefaultNotificationList, Search = DefaultSearch } =
-    useComponentContext(); // FIXME: use component context to retrieve ChannelListItemUI components too
+  const {
+    ChannelListUI = DefaultChannelListUI,
+    NotificationList = DefaultNotificationList,
+    Search = DefaultSearch,
+  } = useComponentContext();
+
   const channelListRef = useRef<HTMLDivElement | null>(null);
   const [channelUpdateCount, setChannelUpdateCount] = useState(0);
 
@@ -334,12 +316,10 @@ const UnMemoizedChannelList = (props: ChannelListProps) => {
   const renderChannel = (item: Channel) => {
     const previewProps = {
       activeChannel: channel,
-      Avatar,
       channel: item,
       // forces the update of preview component on channel update
       channelUpdateCount,
       getLatestMessagePreview,
-      Preview,
       setActiveChannel,
       watchers,
     };
@@ -351,7 +331,7 @@ const UnMemoizedChannelList = (props: ChannelListProps) => {
   const className = clsx(
     customClasses?.chat ?? 'str-chat',
     theme,
-    customClasses?.channelList ?? `${baseClass} ${baseClass}-react`,
+    customClasses?.channelList ?? `${baseClass}`,
     {
       'str-chat--windows-flags':
         useImageFlagEmojisOnWindows && navigator.userAgent.match(/Win/),
@@ -369,15 +349,13 @@ const UnMemoizedChannelList = (props: ChannelListProps) => {
           <ChannelListHeader />
           {showChannelSearch && <Search />}
           {showChannelList && (
-            <List
+            <ChannelListUI
               error={channelsQueryState.error}
               loadedChannels={sendChannelsToList ? loadedChannels : undefined}
               loading={
                 !!channelsQueryState.queryInProgress &&
                 ['reload', 'uninitialized'].includes(channelsQueryState.queryInProgress)
               }
-              LoadingErrorIndicator={LoadingErrorIndicator}
-              LoadingIndicator={LoadingIndicator}
               setChannels={setChannels}
             >
               {!loadedChannels?.length ? (
@@ -393,7 +371,7 @@ const UnMemoizedChannelList = (props: ChannelListProps) => {
                     : loadedChannels.map((channel) => renderChannel(channel))}
                 </Paginator>
               )}
-            </List>
+            </ChannelListUI>
           )}
           <NotificationList panel='channel-list' />
         </div>

src/components/ChannelList/ChannelListMessenger.tsx

@@ -0,0 +1,44 @@
+import React from 'react';
+import type { PropsWithChildren } from 'react';
+import type { APIErrorResponse, Channel, ErrorFromResponse } from 'stream-chat';
+
+import { LoadingChannels } from '../Loading/LoadingChannels';
+import { NullComponent } from '../UtilityComponents';
+import { useComponentContext, useTranslationContext } from '../../context';
+
+export type ChannelListUIProps = {
+  /** Whether the channel query request returned an errored response */
+  error: ErrorFromResponse<APIErrorResponse> | null;
+  /** The channels currently loaded in the list, only defined if `sendChannelsToList` on `ChannelList` is true */
+  loadedChannels?: Channel[];
+  /** Whether the channels are currently loading */
+  loading?: boolean;
+  /** Local state hook that resets the currently loaded channels */
+  setChannels?: React.Dispatch<React.SetStateAction<Channel[]>>;
+};
+
+/**
+ * A preview list of channels, allowing you to select the channel you want to open
+ */
+export const ChannelListUI = (props: PropsWithChildren<ChannelListUIProps>) => {
+  const { children, error = null, loading = false } = props;
+  const { LoadingErrorIndicator = NullComponent, LoadingIndicator = LoadingChannels } =
+    useComponentContext('ChannelListUI');
+  const { t } = useTranslationContext('ChannelListUI');
+
+  if (error) {
+    return <LoadingErrorIndicator error={error} />;
+  }
+
+  return (
+    <div className='str-chat__channel-list-inner'>
+      <div
+        aria-label={t('aria/Channel list')}
+        className='str-chat__channel-list-inner__main'
+        role='listbox'
+      >
+        {loading ? <LoadingIndicator /> : children}
+      </div>
+    </div>
+  );
+};

src/components/ChannelList/ChannelListUI.tsx

@@ -46,7 +46,7 @@ import {
   useChatContext,
   WithComponents,
 } from '../../../context';
-import { ChannelListMessenger } from '../ChannelListMessenger';
+import { ChannelListUI } from '../ChannelListUI';
 
 expect.extend(toHaveNoViolations);
 
@@ -391,7 +391,7 @@ describe('ChannelList', () => {
 
     const ChannelListMessengerPropsInterceptor = (props) => {
       channelListMessengerLoadingHistory.push(props.loading);
-      return <ChannelListMessenger {...props} />;
+      return <ChannelListUI {...props} />;
     };
 
     await render(

src/components/ChannelList/__tests__/ChannelList.test.js

@@ -2,7 +2,7 @@ import React from 'react';
 import { cleanup, render } from '@testing-library/react';
 import '@testing-library/jest-dom';
 
-import { ChannelListMessenger } from '../ChannelListMessenger';
+import { ChannelListUI } from '../ChannelListUI';
 import { TranslationProvider } from '../../../context';
 import { mockTranslationContext } from '../../../mock-builders';
 
@@ -12,15 +12,15 @@ console.warn = () => null;
 
 const Component = ({ error = false, loading = false }) => (
   <TranslationProvider value={mockTranslationContext}>
-    <ChannelListMessenger
+    <ChannelListUI
       error={error}
       loading={loading}
       LoadingErrorIndicator={() => <div>Loading Error Indicator</div>}
       LoadingIndicator={() => <div>Loading Indicator</div>}
     >
       <div>children 1</div>
       <div>children 2</div>
-    </ChannelListMessenger>
+    </ChannelListUI>
   </TranslationProvider>
 );
 

…t/__tests__/ChannelListMessenger.test.js …nnelList/__tests__/ChannelListUI.test.jssrc/components/ChannelList/__tests__/ChannelListMessenger.test.js renamed to src/components/ChannelList/__tests__/ChannelListUI.test.js src/components/ChannelList/__tests__/ChannelListMessenger.test.js renamed to src/components/ChannelList/__tests__/ChannelListUI.test.js

@@ -1,4 +1,4 @@
 export * from './ChannelList';
-export * from './ChannelListMessenger';
+export * from './ChannelListUI';
 export * from './hooks';
 export * from './utils';

src/components/ChannelList/index.ts

@@ -123,12 +123,12 @@
   @include utils.scrollable-y;
   @include utils.component-layer-overrides('channel-list');
 
-  .str-chat__channel-list-messenger {
+  .str-chat__channel-list-inner {
     height: 100%;
     overflow: hidden;
     padding-bottom: var(--str-chat__spacing-2_5);
 
-    .str-chat__channel-list-messenger__main {
+    .str-chat__channel-list-inner__main {
       height: 100%;
       overflow-y: auto;
 

src/components/ChannelList/styling/ChannelList.scss

@@ -10,7 +10,6 @@ import { getLatestMessagePreview as defaultGetLatestMessagePreview } from './uti
 import { useTranslationContext } from '../../context/TranslationContext';
 import { useMessageDeliveryStatus } from './hooks/useMessageDeliveryStatus';
 import type { MessageDeliveryStatus } from './hooks/useMessageDeliveryStatus';
-import type { ChannelAvatarProps } from '../Avatar/ChannelAvatar';
 import type { GroupChannelDisplayInfo } from './utils';
 import {
   type ChatContextValue,
@@ -47,8 +46,6 @@ export type ChannelListItemProps = {
   active?: boolean;
   /** Current selected channel object */
   activeChannel?: Channel;
-  /** UI component to display an avatar, defaults to [Avatar](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Avatar/Avatar.tsx) component and accepts the same props as: [ChannelAvatar](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Avatar/ChannelAvatar.tsx) */
-  Avatar?: React.ComponentType<ChannelAvatarProps>;
   /** Forces the update of preview component on channel update */
   channelUpdateCount?: number;
   /** Custom class for the channel preview root */

src/components/ChannelListItem/ChannelListItem.tsx

@@ -30,7 +30,10 @@ export function ChannelListItemTimestamp({ lastMessage }: ChannelListItemTimesta
   if (!when) return null;
 
   return (
-    <time className='str-chat__channel-list-item-timestamp' dateTime={normalizedTimestamp}>
+    <time
+      className='str-chat__channel-list-item-timestamp'
+      dateTime={normalizedTimestamp}
+    >
       {when}
     </time>
   );