feat: allow overriding the way MessageList renders messages (#2243)

### 🎯 Goal

Some users want to be able to append custom elements at the start/end of
`MessageList`. For maximum flexibility, we're just giving (optional)
full control over how `MessageList` renders its children.

### 🛠 Implementation details

New optional prop `renderMessages` is added to `MessageList`. It
receives an array of messages to be rendered, all the components from
the channel's component context, and some additional metadata. It
returns an array of React elements.

The default implementation is identical to how `MessageList` currently
renders its children. This default implementation is also exported so
that users can reuse it in their current renderers.

### 🎨 UI Changes

None by default.

Author: myandrienko

docusaurus/docs/React/components/core-components/message-list.mdx

@@ -218,6 +218,34 @@ const CustomMessageList = () => (
 );
 ```
 
+#### Custom message list rendering
+
+You can completely change the way the message list is rendered by providing a custom `renderMessages` function. This function takes all the messages fetched so far (along with some additional data) and returns an array of React elements to render. By overriding the default behavior, you can add custom elements to the message list, change the way messages are grouped, add custom separators between messages, etc.
+
+If you provide a custom `renderMessages` function, it's your responsibility to render each message type correctly. You can use the <GHComponentLink text='default implementation' path='/MessageList/renderMessages.tsx'/> as a reference. Or, if you just want to tweak a few things here and there, you can call `defaultRenderMessages` from your custom `renderMessages` function and build from there.
+
+In this example, we use the default implementation for rendering a message list, and we add a custom element at the bottom of the list:
+
+```tsx
+const customRenderMessages: MessageRenderer<StreamChatGenerics> = (options) => {
+  const elements = defaultRenderMessages(options);
+  elements.push(<li key='caught-up'>You're all caught up!</li>);
+  return elements;
+};
+
+const CustomMessageList = () => (
+  <MessageList renderMessages={customRenderMessages}/>
+);
+```
+
+Make sure that the elements you return have `key`, as they will be rendered as an array. It's also a good idea to wrap each element with `<li>` to keep your markup semantically correct.
+
+:::note
+`MessageList` will re-render every time `renderMessages` function changes. For best performance, make sure that you don't recreate `renderMessages` function on every render: either move it to the global or module scope, or wrap it with `useCallback`.
+:::
+
+Custom message list rendering is only supported in `MessageList` and is currently not supported in `VirtualizedMessageList`.
+
 ## Props
 
 ### additionalMessageInputProps
@@ -504,9 +532,35 @@ The user roles allowed to pin messages in various channel types (deprecated in f
 
 Custom function to render message text content.
 
+| Type     | Default                                                                        |
+| -------- | ------------------------------------------------------------------------------ |
+| function | <GHComponentLink text='renderText' path='/Message/renderText/renderText.tsx'/> |
+
+### renderMessages
+
+Custom function to render message text content.
+
 | Type     | Default                                                                                |
 | -------- | -------------------------------------------------------------------------------------- |
-| function | <GHComponentLink text='renderText' path='/Message/renderText/renderText.tsx'/> |
+| function | <GHComponentLink text='defaultRenderMessages' path='/MessageList/renderMessages.tsx'/> |
+
+#### Parameters
+
+The function receives a single object with the following properties:
+
+| Name                  | Type                                                                                          | Description                                                                                                                                        |
+| --------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| components            | [ComponentContextValue](../contexts/component-context.mdx)                                    | UI components, including possible overrides                                                                                                        |
+| customClasses         | object                                                                                        | Object containing [custom CSS classnames](../../components/core-components/chat.mdx#customclasses) to override the library's default container CSS |
+| lastReceivedMessageId | string                                                                                        | The latest message ID in the current channel                                                                                                       |
+| messageGroupStyles    | string[]                                                                                      | An array of potential styles to apply to a grouped message (ex: top, bottom, single)                                                               |
+| messages              | Array<[ChannelStateContextValue['messages']](../contexts/channel-state-context.mdx#messages)> | The messages to render in the list                                                                                                                 |
+| readData              | object                                                                                        | The read state for for messages submitted by the user themselves                                                                                   |
+| sharedMessageProps    | object                                                                                        | Object containing props that can be directly passed to the `Message` component                                                                     |
+
+#### Return value
+
+The function is expected to return an array of valid React nodes: `Array<ReactNode>`. For best performance, each node should have a `key`.
 
 ### retrySendMessage
 

src/components/Channel/Channel.tsx

@@ -92,6 +92,8 @@ import {
   defaultReactionOptions,
   ReactionOptions,
 } from '../../components/Reactions/reactionOptions';
+import { EventComponent } from '../EventComponent';
+import { DateSeparator } from '../DateSeparator';
 
 type ChannelPropsForwardedToComponentContext<
   StreamChatGenerics extends DefaultStreamChatGenerics = DefaultStreamChatGenerics
@@ -1013,7 +1015,7 @@ const ChannelInner = <
       BaseImage: props.BaseImage,
       CooldownTimer: props.CooldownTimer,
       CustomMessageActionsList: props.CustomMessageActionsList,
-      DateSeparator: props.DateSeparator,
+      DateSeparator: props.DateSeparator || DateSeparator,
       EditMessageInput: props.EditMessageInput,
       EmojiPicker: props.EmojiPicker,
       emojiSearchIndex: props.emojiSearchIndex,
@@ -1031,7 +1033,7 @@ const ChannelInner = <
       MessageOptions: props.MessageOptions,
       MessageRepliesCountButton: props.MessageRepliesCountButton,
       MessageStatus: props.MessageStatus,
-      MessageSystem: props.MessageSystem,
+      MessageSystem: props.MessageSystem || EventComponent,
       MessageTimestamp: props.MessageTimestamp,
       ModalGallery: props.ModalGallery,
       PinIndicator: props.PinIndicator,

src/components/MessageList/MessageList.tsx

@@ -28,6 +28,7 @@ import { TypingIndicator as DefaultTypingIndicator } from '../TypingIndicator';
 import { MessageListMainPanel } from './MessageListMainPanel';
 
 import type { GroupStyle } from './utils';
+import { defaultRenderMessages, MessageRenderer } from './renderMessages';
 
 import type { MessageProps } from '../Message/types';
 
@@ -62,6 +63,7 @@ const MessageListWithContext = <
     unsafeHTML = false,
     headerPosition,
     read,
+    renderMessages = defaultRenderMessages,
     messageLimit = 100,
     loadMore: loadMoreCallback,
     loadMoreNewer: loadMoreNewerCallback,
@@ -142,6 +144,7 @@ const MessageListWithContext = <
     },
     messageGroupStyles,
     read,
+    renderMessages,
     returnAllReadData,
     threadList,
   });
@@ -302,6 +305,8 @@ export type MessageListProps<
   messages?: StreamMessage<StreamChatGenerics>[];
   /** If true, turns off message UI grouping by user */
   noGroupByUser?: boolean;
+  /** Overrides the way MessageList renders messages */
+  renderMessages?: MessageRenderer<StreamChatGenerics>;
   /** If true, `readBy` data supplied to the `Message` components will include all user read states per sent message */
   returnAllReadData?: boolean;
   /**

src/components/MessageList/__tests__/MessageList.test.js

@@ -238,4 +238,59 @@ describe('MessageList', () => {
     const results = await axe(container);
     expect(results).toHaveNoViolations();
   });
+
+  it('should render intro messages', async () => {
+    const intro = generateMessage({ customType: 'message.intro' });
+    const headerText = 'header is rendered';
+    const Header = () => <div>{headerText}</div>;
+
+    await act(() => {
+      renderComponent({
+        channelProps: { channel, HeaderComponent: Header },
+        chatClient,
+        msgListProps: {
+          messages: [intro],
+        },
+      });
+    });
+
+    await waitFor(() => {
+      expect(screen.queryByText(headerText)).toBeInTheDocument();
+    });
+  });
+
+  it('should render system messages', async () => {
+    const system = generateMessage({ text: 'system message is rendered', type: 'system' });
+
+    await act(() => {
+      renderComponent({
+        channelProps: { channel },
+        chatClient,
+        msgListProps: {
+          messages: [system],
+        },
+      });
+    });
+
+    await waitFor(() => {
+      expect(screen.queryByText(system.text)).toBeInTheDocument();
+    });
+  });
+
+  it('should use custom message list renderer if provided', async () => {
+    const customRenderMessages = ({ messages }) =>
+      messages.map((msg) => <li key={msg.id}>prefixed {msg.text}</li>);
+
+    await act(() => {
+      renderComponent({
+        channelProps: { channel },
+        chatClient,
+        msgListProps: { renderMessages: customRenderMessages },
+      });
+    });
+
+    await waitFor(() => {
+      expect(screen.queryByText(`prefixed ${message1.text}`)).toBeInTheDocument();
+    });
+  });
 });

src/components/MessageList/hooks/MessageList/useMessageListElements.tsx

@@ -4,38 +4,23 @@ import React, { useMemo } from 'react';
 import { useLastReadData } from '../useLastReadData';
 import { getLastReceived, GroupStyle } from '../../utils';
 
-import { CUSTOM_MESSAGE_TYPE } from '../../../../constants/messageTypes';
-import { DateSeparator as DefaultDateSeparator } from '../../../DateSeparator/DateSeparator';
-import { EventComponent } from '../../../EventComponent/EventComponent';
-import { Message } from '../../../Message';
-
 import { useChatContext } from '../../../../context/ChatContext';
 import { useComponentContext } from '../../../../context/ComponentContext';
-import { isDate } from '../../../../context/TranslationContext';
 
 import type { UserResponse } from 'stream-chat';
 
-import type { MessageProps } from '../../../Message/types';
-
 import type { StreamMessage } from '../../../../context/ChannelStateContext';
 
 import type { DefaultStreamChatGenerics } from '../../../../types/types';
-
-type MessagePropsToOmit =
-  | 'channel'
-  | 'groupStyles'
-  | 'initialMessage'
-  | 'lastReceivedId'
-  | 'message'
-  | 'readBy'
-  | 'threadList';
+import { MessageRenderer, SharedMessageProps } from '../../renderMessages';
 
 type UseMessageListElementsProps<
   StreamChatGenerics extends DefaultStreamChatGenerics = DefaultStreamChatGenerics
 > = {
   enrichedMessages: StreamMessage<StreamChatGenerics>[];
-  internalMessageProps: Omit<MessageProps<StreamChatGenerics>, MessagePropsToOmit>;
+  internalMessageProps: SharedMessageProps<StreamChatGenerics>;
   messageGroupStyles: Record<string, GroupStyle>;
+  renderMessages: MessageRenderer<StreamChatGenerics>;
   returnAllReadData: boolean;
   threadList: boolean;
   read?: Record<string, { last_read: Date; user: UserResponse<StreamChatGenerics> }>;
@@ -51,16 +36,13 @@ export const useMessageListElements = <
     internalMessageProps,
     messageGroupStyles,
     read,
+    renderMessages,
     returnAllReadData,
     threadList,
   } = props;
 
   const { client, customClasses } = useChatContext<StreamChatGenerics>('useMessageListElements');
-  const {
-    DateSeparator = DefaultDateSeparator,
-    HeaderComponent,
-    MessageSystem = EventComponent,
-  } = useComponentContext<StreamChatGenerics>('useMessageListElements');
+  const components = useComponentContext<StreamChatGenerics>('useMessageListElements');
 
   // get the readData, but only for messages submitted by the user themselves
   const readData = useLastReadData({
@@ -70,71 +52,29 @@ export const useMessageListElements = <
     userID: client.userID,
   });
 
-  const lastReceivedId = useMemo(() => getLastReceived(enrichedMessages), [enrichedMessages]);
+  const lastReceivedMessageId = useMemo(() => getLastReceived(enrichedMessages), [
+    enrichedMessages,
+  ]);
 
   const elements: React.ReactNode[] = useMemo(
     () =>
-      enrichedMessages.map((message) => {
-        if (
-          message.customType === CUSTOM_MESSAGE_TYPE.date &&
-          message.date &&
-          isDate(message.date)
-        ) {
-          return (
-            <li key={`${message.date.toISOString()}-i`}>
-              <DateSeparator
-                date={message.date}
-                formatDate={internalMessageProps.formatDate}
-                unread={message.unread}
-              />
-            </li>
-          );
-        }
-
-        if (message.customType === CUSTOM_MESSAGE_TYPE.intro && HeaderComponent) {
-          return (
-            <li key='intro'>
-              <HeaderComponent />
-            </li>
-          );
-        }
-
-        if (message.type === 'system') {
-          return (
-            <li key={message.id || (message.created_at as string)}>
-              <MessageSystem message={message} />
-            </li>
-          );
-        }
-
-        const groupStyles: GroupStyle = messageGroupStyles[message.id] || '';
-        const messageClass = customClasses?.message || `str-chat__li str-chat__li--${groupStyles}`;
-
-        return (
-          <li
-            className={messageClass}
-            data-message-id={message.id}
-            data-testid={messageClass}
-            key={message.id || (message.created_at as string)}
-          >
-            <Message
-              groupStyles={[groupStyles]} /* TODO: convert to simple string */
-              lastReceivedId={lastReceivedId}
-              message={message}
-              readBy={readData[message.id] || []}
-              threadList={threadList}
-              {...internalMessageProps}
-            />
-          </li>
-        );
+      renderMessages({
+        components,
+        customClasses,
+        lastReceivedMessageId,
+        messageGroupStyles,
+        messages: enrichedMessages,
+        readData,
+        sharedMessageProps: { ...internalMessageProps, threadList },
       }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [
       enrichedMessages,
       internalMessageProps,
-      lastReceivedId,
+      lastReceivedMessageId,
       messageGroupStyles,
       readData,
+      renderMessages,
       threadList,
     ],
   );

src/components/MessageList/index.ts

@@ -6,4 +6,5 @@ export * from './MessageNotification';
 export * from './ScrollToBottomButton';
 export * from './VirtualizedMessageList';
 export * from './hooks';
+export * from './renderMessages';
 export * from './utils';