feat: add customizable reactions sorting (#2289)

### 🎯 Goal

Currently the order of reactions in the `ReactionsList` depends of the
order of keys in the `reaction_counts` object returned by the backend.
This leads to unstable reaction order, which can change on page reloads,
or when the list of reactions changes.

We want to provide a way to customize this behavior, and to have a
stable order of reactions by default.

### 🛠 Implementation details

Added a new `MessageContext` property: `sortReactions`. It accepts two
reaction objects, and should return a positive/negative/zero numeric
value, similar to the `Array.prototype.sort` method.

The `sortReactions` prop can be passed both to `MessageList` and
`VirtualizedMessageList`, as well as to the `Message` component
directly. It will then be available via the `MessageContext`.

Author: myandrienko

docusaurus/docs/React/components/contexts/message-context.mdx

@@ -377,6 +377,14 @@ When true, show the reactions list component.
 | ------- |
 | boolean |
 
+### sortReactions
+
+Comparator function to sort reactions. Should have the same signature as an array's `sort` method.
+
+| Type                                                     | Default            |
+| -------------------------------------------------------- | ------------------ |
+| (this: ReactionSummary, that: ReactionSummary) => number | alphabetical order |
+
 ### threadList
 
 If true, indicates that the current `MessageList` component is part of a `Thread`.

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

@@ -73,6 +73,7 @@ The default `remark` plugins used by SDK are:
 1. [`remark-gfm`](https://github.com/remarkjs/remark-gfm) - a third party plugin to add GitHub-like markdown support
 
 The default `rehype` plugins (both specific to this SDK) are:
+
 1. plugin to render user mentions
 2. plugin to render emojis
 
@@ -166,56 +167,54 @@ If you would like to extend the array of plugins used to parse the markdown, you
 It is important to understand what constitutes a rehype or remark plugin. A good start is to learn about the library called [`react-remark`](https://github.com/remarkjs/react-remark) which is used under the hood in our `renderText()` function.
 :::
 
-
 ```tsx
 import { renderText, RenderTextPluginConfigurator } from 'stream-chat-react';
-import {customRehypePlugin} from './rehypePlugins';
-import {customRemarkPlugin} from './remarkPlugins';
+import { customRehypePlugin } from './rehypePlugins';
+import { customRemarkPlugin } from './remarkPlugins';
 
 const getRehypePlugins: RenderTextPluginConfigurator = (plugins) => {
-    return [customRehypePlugin, ...plugins];
-}
+  return [customRehypePlugin, ...plugins];
+};
 const getRemarkPlugins: RenderTextPluginConfigurator = (plugins) => {
-    return [customRemarkPlugin, ...plugins];
-}
+  return [customRemarkPlugin, ...plugins];
+};
 
 const customRenderText = (text, mentionedUsers) =>
   renderText(text, mentionedUsers, {
     getRehypePlugins,
-    getRemarkPlugins
+    getRemarkPlugins,
   });
 
-const CustomMessageList = () => (
-  <MessageList renderText={customRenderText}/>
-);
+const CustomMessageList = () => <MessageList renderText={customRenderText} />;
 ```
 
 It is also possible to define your custom set of allowed tag names for the elements rendered from the parsed markdown. To perform the tree transformations, you will need to use libraries like [`unist-builder`](https://github.com/syntax-tree/unist-builder) to build the trees and [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit-parents) or [`hast-util-find-and-replace`](https://github.com/syntax-tree/hast-util-find-and-replace) to traverse the tree:
 
 ```tsx
 import { findAndReplace } from 'hast-util-find-and-replace';
 import { u } from 'unist-builder';
-import { defaultAllowedTagNames, renderText, RenderTextPluginConfigurator } from 'stream-chat-react';
+import {
+  defaultAllowedTagNames,
+  renderText,
+  RenderTextPluginConfigurator,
+} from 'stream-chat-react';
 
 // wraps every letter b in <xxx></xxx> tags
 const customTagName = 'xxx';
 const replace = (match) => u('element', { tagName: customTagName }, [u('text', match)]);
 const customRehypePlugin = () => (tree) => findAndReplace(tree, /b/, replace);
 
 const getRehypePlugins: RenderTextPluginConfigurator = (plugins) => {
-    return [customRehypePlugin, ...plugins];
-}
-
+  return [customRehypePlugin, ...plugins];
+};
 
 const customRenderText = (text, mentionedUsers) =>
   renderText(text, mentionedUsers, {
     allowedTagNames: [...defaultAllowedTagNames, customTagName],
     getRehypePlugins,
   });
 
-const CustomMessageList = () => (
-  <MessageList renderText={customRenderText}/>
-);
+const CustomMessageList = () => <MessageList renderText={customRenderText} />;
 ```
 
 #### Custom message list rendering
@@ -233,9 +232,7 @@ const customRenderMessages: MessageRenderer<StreamChatGenerics> = (options) => {
   return elements;
 };
 
-const CustomMessageList = () => (
-  <MessageList renderMessages={customRenderMessages}/>
-);
+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.
@@ -621,9 +618,17 @@ The floating notification informing about unread messages will be shown when the
 is shown only when viewing unread messages.
 
 | Type    | Default |
-|---------|---------|
+| ------- | ------- |
 | boolean | false   |
 
+### sortReactions
+
+Comparator function to sort reactions. Should have the same signature as the `sort` method for a string array.
+
+| Type                                                     | Default            |
+| -------------------------------------------------------- | ------------------ |
+| (this: ReactionSummary, that: ReactionSummary) => number | alphabetical order |
+
 ### threadList
 
 If true, indicates that the current `MessageList` component is part of a `Thread`.

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

@@ -252,7 +252,7 @@ The floating notification informing about unread messages will be shown when the
 is shown only when viewing unread messages.
 
 | Type    | Default |
-|---------|---------|
+| ------- | ------- |
 | boolean | false   |
 
 ### stickToBottomScrollBehavior
@@ -264,6 +264,14 @@ The scroll-to behavior when new messages appear. Use `'smooth'` for regular chat
 | ------------------ | -------- |
 | 'smooth' \| 'auto' | 'smooth' |
 
+### sortReactions
+
+Comparator function to sort reactions. Should have the same signature as an array's `sort` method.
+
+| Type                                                     | Default            |
+| -------------------------------------------------------- | ------------------ |
+| (this: ReactionSummary, that: ReactionSummary) => number | alphabetical order |
+
 ### threadList
 
 If true, indicates that the current `VirtualizedMessageList` component is part of a `Thread`.

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

@@ -363,6 +363,14 @@ Custom action handler to retry sending a message after a failed request.
 | -------- | -------------------------------------------------------------------------------------------------------- |
 | function | [ChannelActionContextValue['retrySendMessage']](../contexts/channel-action-context.mdx#retrysendmessage) |
 
+### sortReactions
+
+Comparator function to sort reactions. Should have the same signature as the `sort` method for a string array.
+
+| Type                                                     | Default            |
+| -------------------------------------------------------- | ------------------ |
+| (this: ReactionSummary, that: ReactionSummary) => number | alphabetical order |
+
 ### threadList
 
 If true, indicates that the current `MessageList` component is part of a `Thread`.

docusaurus/docs/React/components/message-components/reactions.mdx

@@ -119,6 +119,31 @@ const CustomReactionsList = (props) => {
 </Chat>;
 ```
 
+## Sorting reactions
+
+By default, reactions are sorted alphabetically by type. You can change this behavior by passing a `sortReactions` prop to the `MessageList` (or `VirtualizedMessageList`).
+
+In this example, we sort the reactions in the descending order by the number of users:
+
+```jsx
+function sortByReactionCount(a, b) {
+  return b.reactionCount - a.reactionCount;
+}
+
+<Chat client={client}>
+  <Channel
+    channel={channel}
+    ReactionSelector={CustomReactionSelector}
+    ReactionsList={CustomReactionsList}
+  >
+    <MessageList sortReactions={sortByReactionCount} />
+    <MessageInput />
+  </Channel>
+</Chat>;
+```
+
+For better performance, keep this function memoized with `useCallback`, or declare it in either global or module scope.
+
 ## ReactionSelector Props
 
 ### additionalEmojiProps (removed in `11.0.0`)
@@ -276,6 +301,14 @@ If true, adds a CSS class that reverses the horizontal positioning of the select
 | ------- | ------- |
 | boolean | false   |
 
+### sortReactions
+
+Comparator function to sort reactions. Should have the same signature as an array's `sort` method. This prop overrides the function stored in `MessageContext`.
+
+| Type                                                     | Default            |
+| -------------------------------------------------------- | ------------------ |
+| (this: ReactionSummary, that: ReactionSummary) => number | alphabetical order |
+
 ## SimpleReactionsList Props
 
 ### additionalEmojiProps (removed in `11.0.0`)

src/components/Message/Message.tsx

@@ -50,7 +50,8 @@ type MessageContextPropsToPick =
   | 'onMentionsHoverMessage'
   | 'onReactionListClick'
   | 'reactionSelectorRef'
-  | 'showDetailedReactions';
+  | 'showDetailedReactions'
+  | 'sortReactions';
 
 type MessageWithContextProps<
   StreamChatGenerics extends DefaultStreamChatGenerics = DefaultStreamChatGenerics
@@ -207,6 +208,7 @@ export const Message = <
     openThread: propOpenThread,
     pinPermissions,
     retrySendMessage: propRetrySendMessage,
+    sortReactions,
   } = props;
 
   const { addNotification } = useChannelActionContext<StreamChatGenerics>('Message');
@@ -308,6 +310,7 @@ export const Message = <
       readBy={props.readBy}
       renderText={props.renderText}
       showDetailedReactions={showDetailedReactions}
+      sortReactions={sortReactions}
       threadList={props.threadList}
       unsafeHTML={props.unsafeHTML}
       userRoles={userRoles}

src/components/Message/types.ts

@@ -6,6 +6,7 @@ import type { MessageActionsArray } from './utils';
 
 import type { GroupStyle } from '../MessageList/utils';
 import type { MessageInputProps } from '../MessageInput/MessageInput';
+import type { ReactionsComparator } from '../Reactions/types';
 
 import type { ChannelActionContextValue } from '../../context/ChannelActionContext';
 import type { StreamMessage } from '../../context/ChannelStateContext';
@@ -97,6 +98,8 @@ export type MessageProps<
   ) => JSX.Element | null;
   /** Custom retry send message handler to override default in [ChannelActionContext](https://getstream.io/chat/docs/sdk/react/contexts/channel_action_context/) */
   retrySendMessage?: ChannelActionContextValue<StreamChatGenerics>['retrySendMessage'];
+  /** Comparator function to sort reactions, defaults to alphabetical order */
+  sortReactions?: ReactionsComparator;
   /** Whether the Message is in a Thread */
   threadList?: boolean;
   /** render HTML instead of markdown. Posting HTML is only allowed server-side */

src/components/MessageList/MessageList.tsx

@@ -291,6 +291,7 @@ type PropsDrilledToMessage =
   | 'pinPermissions' // @deprecated in favor of `channelCapabilities` - TODO: remove in next major release
   | 'renderText'
   | 'retrySendMessage'
+  | 'sortReactions'
   | 'unsafeHTML';
 
 export type MessageListProps<

src/components/MessageList/VirtualizedMessageList.tsx

@@ -64,6 +64,7 @@ type VirtualizedMessageListPropsForContext =
   | 'Message'
   | 'messageActions'
   | 'shouldGroupByUser'
+  | 'sortReactions'
   | 'threadList';
 
 /**
@@ -194,6 +195,7 @@ const VirtualizedMessageListWithContext = <
     separateGiphyPreview = false,
     shouldGroupByUser = false,
     showUnreadNotificationAlways,
+    sortReactions,
     stickToBottomScrollBehavior = 'smooth',
     suppressAutoscroll,
     threadList,
@@ -443,6 +445,7 @@ const VirtualizedMessageListWithContext = <
               ownMessagesReadByOthers,
               processedMessages,
               shouldGroupByUser,
+              sortReactions,
               threadList,
               unreadMessageCount: channelUnreadUiState?.unread_messages,
               UnreadMessagesSeparator,
@@ -487,7 +490,8 @@ const VirtualizedMessageListWithContext = <
 type PropsDrilledToMessage =
   | 'additionalMessageInputProps'
   | 'customMessageActions'
-  | 'messageActions';
+  | 'messageActions'
+  | 'sortReactions';
 
 export type VirtualizedMessageListProps<
   StreamChatGenerics extends DefaultStreamChatGenerics = DefaultStreamChatGenerics

src/components/MessageList/VirtualizedMessageListComponents.tsx

@@ -137,6 +137,7 @@ export const messageRenderer = <
     ownMessagesReadByOthers,
     processedMessages: messageList,
     shouldGroupByUser,
+    sortReactions,
     unreadMessageCount = 0,
     UnreadMessagesSeparator,
     virtuosoRef,
@@ -189,6 +190,7 @@ export const messageRenderer = <
         Message={MessageUIComponent}
         messageActions={messageActions}
         readBy={ownMessagesReadByOthers[message.id] || []}
+        sortReactions={sortReactions}
       />
       {showUnreadSeparator && (
         <div className='str-chat__unread-messages-separator-wrapper'>

src/components/Reactions/ReactionsList.tsx

@@ -8,6 +8,7 @@ import { useProcessReactions } from './hooks/useProcessReactions';
 import type { ReactEventHandler } from '../Message/types';
 import type { DefaultStreamChatGenerics } from '../../types/types';
 import type { ReactionOptions } from './reactionOptions';
+import type { ReactionsComparator } from './types';
 import { ReactionsListModal } from './ReactionsListModal';
 import { MessageContextValue, useTranslationContext } from '../../context';
 import { MAX_MESSAGE_REACTIONS_TO_FETCH } from '../Message/hooks';
@@ -27,6 +28,8 @@ export type ReactionsListProps<
   reactions?: ReactionResponse<StreamChatGenerics>[];
   /** Display the reactions in the list in reverse order, defaults to false */
   reverse?: boolean;
+  /** Comparator function to sort reactions, defaults to alphabetical order */
+  sortReactions?: ReactionsComparator;
 };
 
 const UnMemoizedReactionsList = <

src/components/Reactions/__tests__/ReactionsList.test.js

@@ -134,4 +134,49 @@ describe('ReactionsList', () => {
       ),
     ).not.toBeInTheDocument();
   });
+
+  it('should order reactions alphabetically by default', () => {
+    const { getByTestId } = renderComponent({
+      reaction_counts: {
+        haha: 2,
+        like: 8,
+        love: 5,
+      },
+    });
+
+    expect(
+      getByTestId('reactions-list-button-haha').compareDocumentPosition(
+        getByTestId('reactions-list-button-like'),
+      ),
+    ).toStrictEqual(Node.DOCUMENT_POSITION_FOLLOWING);
+
+    expect(
+      getByTestId('reactions-list-button-like').compareDocumentPosition(
+        getByTestId('reactions-list-button-love'),
+      ),
+    ).toStrictEqual(Node.DOCUMENT_POSITION_FOLLOWING);
+  });
+
+  it('should use custom comparator if provided', () => {
+    const { getByTestId } = renderComponent({
+      reaction_counts: {
+        haha: 2,
+        like: 8,
+        love: 5,
+      },
+      sortReactions: (a, b) => b.reactionCount - a.reactionCount,
+    });
+
+    expect(
+      getByTestId('reactions-list-button-like').compareDocumentPosition(
+        getByTestId('reactions-list-button-love'),
+      ),
+    ).toStrictEqual(Node.DOCUMENT_POSITION_FOLLOWING);
+
+    expect(
+      getByTestId('reactions-list-button-love').compareDocumentPosition(
+        getByTestId('reactions-list-button-haha'),
+      ),
+    ).toStrictEqual(Node.DOCUMENT_POSITION_FOLLOWING);
+  });
 });