stream-chat-react-native-core 10.0.0-rc.1 → 10.0.0-rc.3

package/src/components/Message/MessageItemView/MessageWrapper.tsx

@@ -53,33 +53,30 @@ export const MessageWrapper = React.memo(function MessageWrapper(props: MessageW
     noGroupByUser,
   });
 
-  // Wire timestamps throughout, directly comparable. `new Date(ns)` yielded NaN, so the unread
-  // separator never rendered.
+  // `created_at` is a numeric wire timestamp, directly comparable (`new Date(ns)` yields NaN).
   const createdAtTimestamp = message.created_at;
   const messageId = message.id;
   const nextMessageId = nextMessage?.id;
-  const nextMessageIsOwn = nextMessage?.user?.id === client.userID;
+  const nextMessageIsOwn = nextMessage?.user?.id === client.userId;
   const nextMessageCreatedAt = nextMessage?.created_at ?? undefined;
+  const isThreadList = !!messagePaginator.parentMessageId;
 
-  // The unread separator belongs above the first UNREAD message from another user — i.e. on the row
-  // whose newer neighbour is that first unread. We locate it per-message inside the selector so
-  // `useStateStore`'s per-key comparison keeps the flag referentially stable (`false === false`) for
-  // every non-boundary row: a mark-read changes the channel-wide unread fields but only re-renders
-  // the one or two boundary rows whose flag actually flips, not the whole list.
+  // The unread separator goes on the row above the first unread message from another user. It is
+  // located per message inside the selector, so the flag stays `false` for every other row and a
+  // mark-read only re-renders the boundary rows whose flag flips, not the whole list.
   const showUnreadSeparatorSelector = useCallback(
     (snapshot: UnreadSnapshotState) => {
       let showUnreadSeparator: boolean;
-      if (snapshot.firstUnreadMessageId) {
-        // Frozen boundary (channel open / mark-unread): anchor directly to the known first-unread id.
+      if (isThreadList) {
+        showUnreadSeparator = false;
+      } else if (snapshot.firstUnreadMessageId) {
+        // Frozen boundary (channel open or mark-unread): anchor to the known first unread ID.
         showUnreadSeparator = nextMessageId === snapshot.firstUnreadMessageId;
       } else if (snapshot.unreadCount) {
-        // Live boundary: the separator sits above the FIRST unread-from-another message — i.e. on
-        // the last genuinely-read row (created at/before the read boundary) whose newer neighbour is
-        // that first unread. Gating on "this row is read" (rather than "this row isn't itself an
-        // unread-from-another") keeps it to a SINGLE separator even when our own messages are
-        // interleaved among the unreads: an own message sent after the boundary is not "read" by
-        // this test, so `own → unread-from-another` transitions further down never start a second
-        // separator. Chronological ordering guarantees exactly one read→unread transition.
+        // Live boundary: the separator goes on the last read row (created at or before
+        // `lastReadAt`) whose newer neighbor is the first unread from another user. Requiring this
+        // row to be read keeps it to one separator when own messages are interleaved among the
+        // unreads, as an own message sent after the boundary is not read.
         const lastReadAt = snapshot.lastReadAt ?? 0;
         const nextIsUnreadFromOther =
           !!nextMessageId &&
@@ -89,7 +86,7 @@ export const MessageWrapper = React.memo(function MessageWrapper(props: MessageW
         const thisIsRead =
           typeof createdAtTimestamp === 'number' && createdAtTimestamp <= lastReadAt;
         // Own messages sent elsewhere after the boundary leave no read row above the first unread,
-        // so the rule above never fires. Anchor on the last read message in those cases.
+        // so the rule above never fires. Anchor on the last read message then.
         const isLastReadBeforeOwnUnread =
           thisIsRead &&
           messageId === snapshot.lastReadMessageId &&
@@ -104,12 +101,19 @@ export const MessageWrapper = React.memo(function MessageWrapper(props: MessageW
       return {
         showUnreadSeparator,
         // Only the boundary row needs the unread count (for its inline indicator). Gating it on
-        // `showUnreadSeparator` keeps this `undefined` for every other row, so the channel-wide
-        // count changing on each mark-read doesn't re-render the whole list.
+        // `showUnreadSeparator` keeps it `undefined` elsewhere, so a changing channel-wide count
+        // does not re-render the whole list.
         unreadCount: showUnreadSeparator ? snapshot.unreadCount : undefined,
       };
     },
-    [createdAtTimestamp, messageId, nextMessageCreatedAt, nextMessageId, nextMessageIsOwn],
+    [
+      createdAtTimestamp,
+      isThreadList,
+      messageId,
+      nextMessageCreatedAt,
+      nextMessageId,
+      nextMessageIsOwn,
+    ],
   );
   const { showUnreadSeparator, unreadCount } = useStateStore(
     messagePaginator.unreadStateSnapshot,
@@ -125,7 +129,7 @@ export const MessageWrapper = React.memo(function MessageWrapper(props: MessageW
 
   const showUnreadUnderlay = !!shouldShowUnreadUnderlay && showUnreadSeparator;
 
-  const wrapMessageInTheme = client.userID === message.user?.id && !!myMessageTheme;
+  const wrapMessageInTheme = client.userId === message.user?.id && !!myMessageTheme;
   const renderDateSeperator = dateSeparatorDate ? (
     <View style={styles.dateSeparatorContainer}>
       <InlineDateSeparator date={dateSeparatorDate} />

package/src/components/Message/MessageItemView/ReactionList/ReactionListBottom.tsx

@@ -129,7 +129,7 @@ export const ReactionListBottom = (props: ReactionListBottomProps) => {
         columnWrapperStyle={styles.columnWrapper}
         data={reactionListBottomItemData}
         keyExtractor={(item) => item.reaction.type}
-        ItemSeparatorComponent={ItemSeparatorComponent} // This is for the gap between the rows of reactions
+        ItemSeparatorComponent={ItemSeparatorComponent} // Gap between the rows of reactions
         renderItem={renderItem}
         showsHorizontalScrollIndicator={false}
         showsVerticalScrollIndicator={false}

package/src/components/Message/MessageItemView/ReactionList/ReactionListTop.tsx

@@ -32,9 +32,7 @@ export type ReactionListTopProps = Partial<
   showCount?: boolean;
 };
 
-/**
- * ReactionListTop - A high level component which implements all the logic required for a message reaction list
- */
+/** Displays the reaction list of a message. */
 export const ReactionListTop = (props: ReactionListTopProps) => {
   const {
     alignment: propAlignment,

package/src/components/Message/MessageItemView/__tests__/MessageStatus.test.tsx

@@ -184,4 +184,25 @@ describe('MessageStatus', () => {
       });
     });
   });
+
+  it.each([
+    [false, false, 'sending', 'message-status-sending'],
+    [true, true, 'received', 'message-status-read'],
+    [false, false, 'received', 'message-status-sent'],
+    [true, false, 'received', 'message-status-delivered'],
+  ] as [boolean, boolean, string, string][])(
+    'exposes a status testID when delivered is %s, read is %s and status is %s',
+    async (delivered, read, status, testID) => {
+      const message = generateMessage({ user: generateUser() });
+      const { getByTestId } = renderMessageStatus({
+        delivered,
+        message: { ...message, status },
+        read,
+      });
+      // The icon row is hidden from screen readers in favour of the hidden text label.
+      await waitFor(() => {
+        expect(getByTestId(testID, { includeHiddenElements: true })).toBeTruthy();
+      });
+    },
+  );
 });

package/src/components/Message/MessageItemView/utils/generateMarkdownText.test.ts

@@ -19,6 +19,15 @@ describe('generateMarkdownText', () => {
     ],
     ['Hi @getstream.io getstream.io', 'Hi @getstream.io [getstream.io](http://getstream.io)'],
     ['Hi <Stream>', 'Hi \\<Stream>'],
+    [
+      'getstream.io and https://example.com',
+      '[getstream.io](http://getstream.io) and [https://example.com](https://example.com)',
+    ],
+    ['  see getstream.io  ', 'see [getstream.io](http://getstream.io)'],
+    [
+      'getstream.io and getstream.io/chat',
+      '[getstream.io](http://getstream.io) and [getstream.io/chat](http://getstream.io/chat)',
+    ],
   ])('Returns the generated markdown text for %p and %p', (text, expected) => {
     const result = generateMarkdownText(text);
     expect(result).toBe(expected);

package/src/components/Message/MessageItemView/utils/generateMarkdownText.ts

@@ -11,33 +11,44 @@ export const generateMarkdownText = (text?: string) => {
 
   const normalizedText = text.replace(/\uFFFC/g, ' ');
 
-  // Trim the extra spaces from the text.
   let resultText = normalizedText.trim();
 
-  // List of all the links present in the text.
-  const linkInfos = parseLinksFromText(resultText);
-
-  for (const linkInfo of linkInfos) {
-    const displayLink = truncate(linkInfo.raw, {
+  const links = parseLinksFromText(resultText).map((linkInfo) => ({
+    ...linkInfo,
+    displayLink: truncate(linkInfo.raw, {
       length: 200,
       omission: '...',
-    });
-    // Convert raw links/emails in the text to respective markdown syntax.
-    // Eg: Hi @getstream.io -> Hi @[getstream.io](getstream.io).
-    const normalRegEx = new RegExp(escapeRegExp(linkInfo.raw), 'g');
-    const markdown = `[${displayLink}](${linkInfo.url})`;
-    resultText = normalizedText.replace(normalRegEx, markdown);
-
-    // After previous step, in some cases, the mentioned user after `@` might have a link/email so we convert it back to normal raw text.
-    // Eg: Hi, @[test.user@gmail.com](mailto:test.user@gmail.com) to @test.user@gmail.com.
+    }),
+  }));
+
+  if (links.length > 0) {
+    // Convert raw links and emails to markdown links in one pass, longest first, so a link that
+    // contains another one (`getstream.io/chat` and `getstream.io`) is converted only once.
+    // Eg: `getstream.io` -> `[getstream.io](http://getstream.io)`.
+    const markdownByRaw = new Map(
+      links.map(({ displayLink, raw, url }) => [raw, `[${displayLink}](${url})`]),
+    );
+    const linksRegEx = new RegExp(
+      [...markdownByRaw.keys()]
+        .sort((a, b) => b.length - a.length)
+        .map(escapeRegExp)
+        .join('|'),
+      'g',
+    );
+    resultText = resultText.replace(linksRegEx, (raw) => markdownByRaw.get(raw) ?? raw);
+  }
+
+  for (const { displayLink, url } of links) {
+    // A mention whose name looks like a link or email is converted back to raw text.
+    // Eg: `@[test.user@gmail.com](mailto:test.user@gmail.com)` -> `@test.user@gmail.com`.
     const mentionsRegex = new RegExp(
-      `@\\[${escapeRegExp(displayLink)}\\]\\(${escapeRegExp(linkInfo.url)}\\)`,
+      `@\\[${escapeRegExp(displayLink)}\\]\\(${escapeRegExp(url)}\\)`,
       'g',
     );
     resultText = resultText.replace(mentionsRegex, `@${displayLink}`);
   }
 
-  // Escape the " and ' characters, except in code blocks where we deem this allowed.
+  // Escape `<`, `"` and `'` outside of code spans and code blocks.
   resultText = resultText.replace(/(```[\s\S]*?```|`.*?`)|[<"']/g, (match, code) => {
     if (code) {
       return code;
@@ -45,7 +56,7 @@ export const generateMarkdownText = (text?: string) => {
     return `\\${match}`;
   });
 
-  // Remove whitespaces that come directly after newlines except in code blocks where we deem this allowed.
+  // Remove 2 or more spaces right after a newline, except in code spans and code blocks.
   resultText = resultText.replace(/(```[\s\S]*?```|`.*?`)|\n[ ]{2,}/g, (_, code) => {
     if (code) {
       return code;
@@ -53,8 +64,8 @@ export const generateMarkdownText = (text?: string) => {
     return '\n';
   });
 
-  // Always replace \n``` with \n\n``` to force the markdown state machine to treat it as a separate block. Otherwise, code blocks inside of list
-  // items for example were broken. We clean up the code block closing state within the rendering itself.
+  // A blank line before a code fence makes the markdown parser treat it as a separate block, which
+  // keeps code blocks inside list items intact. The closing state is cleaned up in the rendering.
   resultText = resultText.replace(/\n```/g, '\n\n```');
 
   return resultText;

package/src/components/Message/MessageItemView/utils/parseLinks.ts

@@ -5,15 +5,10 @@ interface LinkInfo {
   url: string;
 }
 
-/**
- * This is done to remove all markdown formatted links.
- * eg: [google.com](https://www.google.com), [Google](https://www.google.com), [https://www.google.com](https://www.google.com)
- * */
+/** Strips markdown links such as `[Google](https://www.google.com)`, so they are not linkified again. */
 const removeMarkdownLinksFromText = (input: string) => input.replace(/\[.*\]\(.*\)/g, '');
 
-/**
- * This is done to avoid parsing usernames with dot as well as an email address in it.
- */
+/** Strips `@user.name@domain.tld` mentions, so a username with a dot is not parsed as a link. */
 const removeUserNamesWithEmailFromText = (input: string) =>
   input.replace(/@(\w+(\.\w+)?)(@\w+\.\w+)/g, '');
 
@@ -31,7 +26,7 @@ export const parseLinksFromText = (input?: string): LinkInfo[] => {
 
   const result: LinkInfo[] = [...links, ...emails].map(({ href, value }) => {
     let hrefWithProtocol = href;
-    // Matching these: https://reactnative.dev/docs/0.73/linking?syntax=ios#built-in-url-schemes
+    // Values that already carry a scheme (`mailto:`, `tel:`, `sms:` or `scheme://`) are kept as is.
     const pattern = new RegExp(/^(mailto:|tel:|sms:|\S+:\/\/)/);
     if (!pattern.test(hrefWithProtocol)) {
       hrefWithProtocol = 'http://' + hrefWithProtocol;

package/src/components/Message/MessageItemView/utils/renderText.tsx

@@ -101,13 +101,10 @@ const defaultMarkdownStyles: MarkdownStyle = {
     fontSize: primitives.typographyFontSizeMd,
     lineHeight: primitives.typographyLineHeightNormal,
   },
-  // Heading sizes are derived from the body font size (`typographyFontSizeMd`) so they
-  // scale with the integrator's typography settings. lineHeight = fontSize × 1.25 to
-  // give headings room to breathe. Both fields are required here: without lineHeight,
-  // the inherited `lineHeight: typographyLineHeightNormal` (20) from `styles.text` (set
-  // in renderText below) leaks into the heading's inner Text via the markdown library's
-  // text rule (`{...styles.text, ...state.style}`) and squishes larger heading fontSizes
-  // into a 20px line box.
+  // Heading sizes derive from the body font size (`typographyFontSizeMd`) and scale with it, with
+  // lineHeight = fontSize × 1.25. lineHeight is required: otherwise `styles.text`'s
+  // `typographyLineHeightNormal` leaks into the heading's inner Text through the markdown
+  // library's text rule (`{...styles.text, ...state.style}`) and squishes larger headings.
   heading1: {
     fontSize: primitives.typographyFontSizeMd * 2,
     lineHeight: primitives.typographyFontSizeMd * 2 * 1.25,
@@ -342,8 +339,8 @@ export const renderText = (params: RenderTextParams) => {
   let previousLink: string | undefined;
   const linkReact: ReactNodeOutput = (node, output, { ...state }) => {
     let url: string;
-    // Some long URLs with `&` separated parameters are trimmed and the url only until first param is taken.
-    // This is done because of internal link been taken from the original URL in react-native-markdown-package. So, we check for `withinLink` and take the previous full URL.
+    // Inside a link (`withinLink`), react-native-markdown-package passes a URL cut at its first `&`
+    // parameter, so the previous full URL is reused.
     if (state?.withinLink && previousLink) {
       url = previousLink;
     } else {
@@ -388,8 +385,7 @@ export const renderText = (params: RenderTextParams) => {
 
   const paragraphTextReact: ReactNodeOutput = (node, output, { ...state }) => {
     if (messageTextNumberOfLines !== undefined) {
-      // If we want to truncate the message text, lets only truncate the first paragraph
-      // and simply not render rest of the paragraphs.
+      // Truncation applies to the first paragraph only; the other paragraphs are not rendered.
       if (state.key === '0' || state.key === 0) {
         return (
           <Text key={state.key} numberOfLines={messageTextNumberOfLines} style={styles.paragraph}>
@@ -408,8 +404,8 @@ export const renderText = (params: RenderTextParams) => {
     );
   };
 
-  // Collect every mention type the server sent us into a single typed list so
-  // the markdown rule, the lookup, and the press payload all see the same shape.
+  // Every mention type of the message as one typed list, shared by the markdown rule, the lookup
+  // and the press payload.
   const {
     mentioned_channel,
     mentioned_group_ids,
@@ -447,10 +443,8 @@ export const renderText = (params: RenderTextParams) => {
     ),
   ];
 
-  // Lookup keyed by the rendered mention text (sans `@`), lowercased so we
-  // resolve case-insensitively. First-write-wins: if a user shares a name with
-  // a role/group, the user entity is preferred — same precedence the React SDK
-  // applies via insertion order in its plugin.
+  // Keyed by the lowercased mention text without the `@`, for case-insensitive lookup. The first
+  // entity wins, so a user is preferred over a role or group with the same name.
   const mentionLookup = new Map<string, MentionEntity>();
   for (const entity of mentionEntities) {
     const key = (entity.name ?? entity.id).toLowerCase();
@@ -566,13 +560,13 @@ export const renderText = (params: RenderTextParams) => {
       react: blockQuoteReact,
     },
     codeBlock: { react: codeBlockReact },
-    // do not render images, we will scrape them out of the message and show on attachment card component
+    // Images are not rendered inline; the attachment card shows them.
     image: { match: () => null },
     link: { react: linkReact },
     list: { react: listReact },
-    // Truncate long text content in the message overlay
+    // Truncates the text when `messageTextNumberOfLines` is set, such as in the message overlay.
     paragraph: messageTextNumberOfLines ? { react: paragraphTextReact } : {},
-    // we have no react rendering support for reflinks
+    // Reference links are not rendered.
     reflink: { match: () => null },
     sublist: { react: listReact },
     ...(mentionTokens
@@ -613,11 +607,8 @@ export interface ListOutputProps {
 }
 
 /**
- * For lists and sublists, the default behavior of the markdown library we use is
- * to always renumber any list, so all ordered lists start from 1.
- *
- * This custom rule overrides this behavior both for top level lists and sublists,
- * in order to start the numbering from the number of the first list item provided.
+ * Renders lists and sublists. Ordered lists start at the number of their first item, where the
+ * markdown library renumbers every list from 1.
  */
 export const ListOutput = ({ node, output, state, styles }: ListOutputProps) => {
   let isSublist = state.withinList;

package/src/components/Message/MessageOverlayWrapper.tsx

@@ -12,13 +12,11 @@ import type { ViewRef } from '../../types/react-native-compat';
 
 export type MessageOverlayWrapperProps = PropsWithChildren<{
   /**
-   * Stable identifier for this overlay target. Must match `messageOverlayTargetId`
-   * when this subtree should be teleported into the overlay.
+   * Identifier of this overlay target. The subtree is teleported into the overlay when it equals
+   * `messageOverlayTargetId`.
    */
   targetId: string;
-  /**
-   * Optional test id attached to the wrapped target container.
-   */
+  /** Test ID of the wrapped target container. */
   testID?: string;
 }>;
 

package/src/components/Message/hooks/__tests__/useCreateMessageActionHandlers.test.tsx

@@ -22,7 +22,7 @@ const createClient = (mutedUsers: UserMuteResponse[] = []) =>
     on: jest.fn(() => ({ unsubscribe: jest.fn() })),
     pinMessage: jest.fn(),
     unpinMessage: jest.fn(),
-    userID: 'current-user-id',
+    userId: 'current-user-id',
   }) as unknown as StreamChat & {
     moderation: { mute: jest.Mock; unmute: jest.Mock };
     notifications: { add: jest.Mock; remove: jest.Mock; startTimeout: jest.Mock };
@@ -89,7 +89,7 @@ describe('useCreateMessageActionHandlers notifications', () => {
       await result.current.handleTogglePinMessage();
     });
 
-    expect(client.pinMessage).toHaveBeenCalledWith(message, null);
+    expect(client.pinMessage).toHaveBeenCalledWith(message);
     expect(client.notifications.add).toHaveBeenCalledWith({
       message: 'Message pinned',
       options: {

package/src/components/Message/hooks/__tests__/useUserMuteActive.test.tsx

@@ -13,7 +13,7 @@ const muteOf = (targetId: string) =>
 const createClient = () =>
   ({
     mutedUsersStore: new StateStore<{ mutedUsers: UserMuteResponse[] }>({ mutedUsers: [] }),
-    userID: 'current-user-id',
+    userId: 'current-user-id',
   }) as unknown as StreamChat;
 
 describe('useUserMuteActive', () => {

package/src/components/Message/hooks/useCreateMessageActionHandlers.ts

@@ -75,6 +75,17 @@ export type CreateMessageActionHandlersParams = Pick<
 /**
  * Builds the handlers behind the message actions. Holds no subscriptions: anything the handlers
  * branch on (mute, ban and block state, the translated text) is read when the handler runs.
+ *
+ * @param params.channel The channel of the message.
+ * @param params.client The chat client.
+ * @param params.deleteMessage Deletes a message.
+ * @param params.deleteReaction Removes a reaction from a message.
+ * @param params.message The message the handlers act on.
+ * @param params.retrySendMessage Retries sending a failed message.
+ * @param params.sendReaction Adds a reaction to a message.
+ * @param params.setEditingState Puts the composer into editing state.
+ * @param params.setQuotedMessage Sets the message the composer quotes.
+ * @returns The handlers of the message actions.
  */
 export const useCreateMessageActionHandlers = ({
   channel,
@@ -186,7 +197,7 @@ export const useCreateMessageActionHandlers = ({
 
     const isMuted = isUserMuted(
       client.mutedUsersStore.getLatestValue().mutedUsers,
-      client.userID,
+      client.userId,
       message.user.id,
     );
 
@@ -245,7 +256,7 @@ export const useCreateMessageActionHandlers = ({
     const isPinned = !!message.pinned;
     try {
       if (!isPinned) {
-        await client.pinMessage(message, null);
+        await client.pinMessage(message);
         addNotification({
           message: t('message.pinned.text', 'Message pinned'),
           options: { severity: 'success', type: 'api:message:pin:success' },
@@ -296,7 +307,7 @@ export const useCreateMessageActionHandlers = ({
         {
           onPress: async () => {
             try {
-              await client.moderation.flagMessage(message.id);
+              await client.moderation.flagMessage({ message_id: message.id });
               addNotification({
                 message: t('message.flagged.text', 'Message has been successfully flagged'),
                 options: { severity: 'success', type: 'api:message:flag:success' },
@@ -358,18 +369,18 @@ export const useCreateMessageActionHandlers = ({
     const messageId = message.id;
     const own_reactions = message.own_reactions ?? [];
     const userExistingReaction = own_reactions.find((reaction) => {
-      // own user should only ever contain the current user id
-      // just in case we check to prevent bugs with message updates from breaking reactions
-      if (reaction.user && client.userID === reaction.user.id && reaction.type === reactionType) {
+      // `own_reactions` should only hold the current user's reactions; checked anyway so a bad
+      // message update cannot break toggling.
+      if (reaction.user && client.userId === reaction.user.id && reaction.type === reactionType) {
         return true;
-      } else if (reaction.user && client.userID !== reaction.user.id) {
+      } else if (reaction.user && client.userId !== reaction.user.id) {
         console.warn(
           'message.own_reactions contained reactions from a different user, this indicates a bug',
         );
       }
       return false;
     });
-    // Change reaction in local state, make API call in background, revert to old message if fails
+    // The operation applies the change locally at once, sends the request and rolls back on error.
     try {
       if (channel && messageId) {
         if (userExistingReaction) {

package/src/components/Message/hooks/useCreateMessageContext.ts

@@ -67,10 +67,8 @@ export const useCreateMessageContext = ({
     ? stringifyMessage({ includeReactions: false, message: message.quoted_message })
     : '';
 
-  // Resolved here (not at each consumer) so the boolean lives on MessageContext
-  // and downstream components (MessageContent, MessageTextContainer) read it
-  // directly. The predicate's identity is stable in the default case; an
-  // integrator override is expected to be stable too (documented on the config).
+  // Resolved here so downstream components read the boolean from MessageContext. The predicate
+  // is expected to be stable, including an integrator override.
   const { hasInteractiveAccessibilityContent: hasInteractiveAccessibilityContentPredicate } =
     useAccessibilityContext();
   const hasInteractiveAccessibilityContent = hasInteractiveAccessibilityContentPredicate(message);

package/src/components/Message/hooks/useIsMessageDeliveredToOthers.ts

@@ -6,14 +6,15 @@ import { useChannelContext } from '../../../contexts/channelContext/ChannelConte
 import { useStateStore } from '../../../hooks/useStateStore';
 
 /**
- * Whether the given message has been delivered to at least one *other* member, sourced reactively
- * from the channel's `messageReceiptsTracker.snapshotStore`.
+ * Whether the message has been delivered to at least one other member, read from the channel's
+ * `messageReceiptsTracker.snapshotStore`.
  *
- * As {@link useIsMessageReadByOthers}, for delivery: compares against the single furthest point
- * anyone else has reached (`lastDeliveredRefByOthers`) rather than asking who is parked on this
- * message, so the answer is monotonic across the list.
+ * Like {@link useIsMessageReadByOthers}, it compares the message against the furthest point anyone
+ * else has reached (`lastDeliveredRefByOthers`), so the answer is monotonic across the list.
+ * Use `useMessageDeliveredData` to get who received the message.
  *
- * Use this for a delivery indicator; `useMessageDeliveredData` answers who has actually received it.
+ * @param params.message The message to check.
+ * @returns Whether another member has received the message.
  */
 export const useIsMessageDeliveredToOthers = ({ message }: { message?: LocalMessage }) => {
   const { channel } = useChannelContext();

package/src/components/Message/hooks/useIsMessageReadByOthers.ts

@@ -6,17 +6,16 @@ import { useChannelContext } from '../../../contexts/channelContext/ChannelConte
 import { useStateStore } from '../../../hooks/useStateStore';
 
 /**
- * Whether at least one *other* member has read the given message, sourced reactively from the
- * channel's `messageReceiptsTracker.snapshotStore`.
+ * Whether at least one other member has read the message, read from the channel's
+ * `messageReceiptsTracker.snapshotStore`.
  *
- * Compares against `lastReadRefByOthers` — the single furthest point anyone else has reached —
- * rather than asking who is parked on this message. Read cursors only move forward, so one
- * comparison answers every message, and an older message can never report less than a newer one.
- * The per-message maps cannot express that: they mark only the message each cursor happens to land
- * on, so every message before it looks unread.
+ * It compares the message against `lastReadRefByOthers`, the furthest point anyone else has read.
+ * Read cursors only move forward, so an older message never reports less than a newer one, which
+ * the per-message maps cannot guarantee as they mark only the message each cursor lands on.
+ * Use `useMessageReadData` to get the users who read the message.
  *
- * Use this for a read indicator. `useMessageReadData` answers a different question — the users who
- * have read the message — and is what a message-info screen wants.
+ * @param params.message The message to check.
+ * @returns Whether another member has read the message.
  */
 export const useIsMessageReadByOthers = ({ message }: { message?: LocalMessage }) => {
   const { channel } = useChannelContext();

package/src/components/Message/hooks/useMessageActionHandlers.ts

@@ -7,7 +7,9 @@ export {
 
 /**
  * The handlers behind the message actions (copy, delete, edit, pin, mute, ...) for the message this
- * component renders. Call it inside a message, e.g. in a custom message component or a custom
+ * component renders. Call it inside a message, such as a custom message component or a custom
  * `MessageActionList`. Every caller shares the message's one set of handlers.
+ *
+ * @returns The action handlers of the message.
  */
 export const useMessageActionHandlers = () => useMessageContext().messageActionHandlers;

package/src/components/Message/hooks/useMessageActions.tsx

@@ -19,9 +19,11 @@ import type { MessageActionType } from '../../MessageMenu/MessageActionListItem'
 
 /**
  * The default message actions (copy, edit, reply, pin, mute, delete, ...) for the message this
- * component renders, ready to pass to a `MessageActionList`. Call it inside a message, e.g. in a
- * custom message component or a custom `MessageActionList`. The SDK itself calls it only when a
- * message's action menu opens.
+ * component renders, keyed by action name. Call it inside a message, such as a custom message
+ * component or a custom `MessageActionList`. The SDK itself calls it only when a message's action
+ * menu opens.
+ *
+ * @returns The message actions, keyed by action name.
  */
 export const useMessageActions = () => {
   const { client } = useChatContext();