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

package/lib/typescript/utils/utils.d.ts

@@ -6,9 +6,8 @@ export type ReactionData = {
     Icon: React.ComponentType<IconProps>;
     type: string;
     /**
-     * Whether the reaction should appear inside of the reaction picker in the
-     * context menu or not. If `true`, it will consequently not appear in the
-     * extra reactions bottom sheet.
+     * Whether the reaction appears in the context menu's reaction picker. When `true`, it does not
+     * appear in the extra reactions bottom sheet.
      */
     isMain?: boolean;
 };
@@ -35,87 +34,98 @@ export declare const MessageStatusTypes: {
 export type Progress = ValueOf<typeof ProgressIndicatorTypes>;
 export declare const getIndicatorTypeForFileState: (fileState: AttachmentLoadingState, pendingUploadsEnabled: boolean) => Progress | undefined;
 /**
- * Utility to check if the message is a Blocked message.
- * @param message
- * @returns boolean
+ * Whether the message was blocked by moderation.
+ *
+ * @param message The message to check.
+ * @returns Whether the message is blocked.
  */
 export declare const isBlockedMessage: (message: LocalMessage) => boolean;
 /**
- *  Utility to check if the message is a Bounced message.
- * @param message
- * @returns boolean
+ * Whether the message was bounced by moderation.
+ *
+ * @param message The message to check.
+ * @returns Whether the message is bounced.
  */
 export declare const isBouncedMessage: (message: LocalMessage) => boolean;
 /**
- * Utility to check if the message is a edited message.
- * @param message
- * @returns boolean
+ * Whether the message text has been edited.
+ *
+ * @param message The message to check.
+ * @returns Whether the message is edited.
  */
 export declare const isEditedMessage: (message: LocalMessage) => boolean;
 export declare const makeImageCompatibleUrl: (url?: string) => string | undefined;
 export declare const getUrlWithoutParams: (url?: string) => string | undefined;
 /**
- * Whether this URL points at a file on the device rather than something fetchable.
+ * Whether the URL points at a file on the device rather than something fetchable over HTTP(S).
+ * An undefined URL is not local.
  *
- * Anchored on the scheme rather than searching for `http` anywhere in the string: a
- * `content://`/`ph://` URI is free to contain that substring, and an attachment mid-upload is
- * rendered from exactly such a URI. Undefined is "not local" — there is no local file to read.
+ * Matches on the scheme, not on `http` anywhere in the string, because a `content://` or `ph://`
+ * URI may contain that substring.
  */
 export declare const isLocalUrl: (url?: string) => boolean;
 export declare const generateRandomId: (a?: string) => string;
+/** Whether the text contains only emojis, ignoring whitespace. */
 export declare const hasOnlyEmojis: (text: string) => boolean;
 /**
- * Stringifies a message object
- * @param {LocalMessage} message - the message object to be stringified
- * @returns {string} The stringified message
+ * Stringifies the fields of a message that affect how it renders, to compare messages cheaply.
+ *
+ * @param params.message The message to stringify.
+ * @param params.includeReactions Whether to include the reactions. Defaults to true.
+ * @returns The stringified message.
  */
 export declare const stringifyMessage: ({ message, includeReactions, }: {
     message: MessageResponse | LocalMessage;
     includeReactions?: boolean;
 }) => string;
 /**
- * Utility to get the file name from the path using regex.
- * `[^/]+` matches one or more characters that are not a slash (/), ensuring we capture the filename part.
- * `\.` matches the period before the file extension.
- * `[^/]+$` matches one or more characters that are not a slash (/) until the end of the string, capturing the file extension.
- * @param path string
- * @returns string
+ * Returns the file name, including its extension, from the last segment of a path.
+ *
+ * @param path The file path or URI.
+ * @returns The file name, or an empty string when the last segment has no extension.
  */
 export declare const getFileNameFromPath: (path: string) => string;
 /**
- * Utility to get the duration label from the duration in seconds.
- * @param duration number
- * @returns string
+ * Formats a duration as `m:ss`, or `HH:mm:ss` from one hour.
+ *
+ * @param duration The duration in milliseconds.
+ * @returns The duration label, `00:00` for a zero or missing duration.
  */
 export declare const getDurationLabelFromDuration: (duration: number) => string;
 export declare const formatMsToMinSec: (ms: number) => string;
 /**
- * Utility to escape special characters in a string.
- * @param text
- * @returns string
+ * Escapes the characters that have a special meaning in a regular expression.
+ *
+ * @param text The text to escape.
+ * @returns The escaped text.
  */
 export declare function escapeRegExp(text: string): string;
 /**
- * The purpose of this function is to compare two messages and determine if they are equal.
- * It checks various properties of the messages, such as status, type, text, pinned state, updated_at timestamp, i18n data, and reply count.
- * If all these properties match, it returns true, indicating that the messages are considered equal.
- * If any of the properties differ, it returns false, indicating that the messages are not equal.
- * Useful for the `areEqual` logic in the React.memo of the Message component/sub-components.
+ * Whether two messages are equal for rendering purposes, for use in `React.memo` comparators.
+ * Compares `status`, `type`, `text`, `pinned`, `i18n` (by reference), `reply_count`, `updated_at`
+ * and `deleted_at`. Two missing messages are equal.
+ *
+ * @param prevMessage The previous message.
+ * @param nextMessage The next message.
+ * @returns Whether the messages are equal.
  */
 export declare const checkMessageEquality: (prevMessage?: LocalMessage | MessageResponse | null, nextMessage?: LocalMessage | MessageResponse | null) => boolean;
 /**
- * The purpose of this function is to compare two quoted messages and determine if they are equal.
- * It checks various properties of the messages, such as status, type, text, updated_at timestamp, and deleted_at.
- * If all these properties match, it returns true, indicating that the messages are considered equal.
- * If any of the properties differ, it returns false, indicating that the messages are not equal.
- * Useful for the `areEqual` logic in the React.memo of the Message component/sub-components.
+ * Whether two quoted messages are equal for rendering purposes, for use in `React.memo`
+ * comparators. Compares `type`, `text`, `updated_at` and `deleted_at`. Two missing messages are
+ * equal.
+ *
+ * @param prevQuotedMessage The previous quoted message.
+ * @param nextQuotedMessage The next quoted message.
+ * @returns Whether the quoted messages are equal.
  */
 export declare const checkQuotedMessageEquality: (prevQuotedMessage?: LocalMessage | MessageResponse | null, nextQuotedMessage?: LocalMessage | MessageResponse | null) => boolean;
 /**
- * Utility to get initials from name.
- * @param name string
- * @param numberOfInitials number - optional, default is 2
- * @returns string
+ * Returns the uppercase first letters of the first words of a name.
+ *
+ * @param name The full name.
+ * @param numberOfInitials How many initials to return. Defaults to 2.
+ * @returns The initials, or an empty string for a blank name.
  */
 export declare const getInitialsFromName: (name: string, numberOfInitials?: number) => string;
 export declare const hashStringToNumber: (str: string) => number;

package/lib/typescript/utils/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/utils/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,KAAK,EAAE,sBAAsB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEzF,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEzC,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,SAAS;;;;;;EAMpB,CAAC;AAEH,eAAO,MAAM,sBAAsB,EAAE;IACnC,WAAW,EAAE,aAAa,CAAC;IAC3B,QAAQ,EAAE,UAAU,CAAC;IACrB,aAAa,EAAE,eAAe,CAAC;IAC/B,OAAO,EAAE,SAAS,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAOf,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;CAK9B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAG9D,eAAO,MAAM,4BAA4B,GACvC,WAAW,sBAAsB,EACjC,uBAAuB,OAAO,KAC7B,QAAQ,GAAG,SAcb,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,YAAY,YAErD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,YAAY,YACgB,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,YAAY,YAA4C,CAAC;AAElG,eAAO,MAAM,sBAAsB,GAAI,MAAM,MAAM,uBACkB,CAAC;AAEtE,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,uBAW/C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,YAA+C,CAAC;AAEvF,eAAO,MAAM,gBAAgB,GAAI,UAAM,KAAG,MAIqC,CAAC;AAKhF,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,YAazC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,gCAG9B;IACD,OAAO,EAAE,eAAe,GAAG,YAAY,CAAC;IACxC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,KAAG,MA8BH,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,WAI/C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,GAAI,UAAU,MAAM,WAgB5D,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,WAc1C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,UAExC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,cAAc,YAAY,GAAG,eAAe,GAAG,IAAI,EACnD,cAAc,YAAY,GAAG,eAAe,GAAG,IAAI,KAClD,OAwBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GACrC,oBAAoB,YAAY,GAAG,eAAe,GAAG,IAAI,EACzD,oBAAoB,YAAY,GAAG,eAAe,GAAG,IAAI,KACxD,OAgBF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,EAAE,mBAAkB,MAAU,WAU7E,CAAC;AAGF,eAAO,MAAM,kBAAkB,GAAI,KAAK,MAAM,WAS7C,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,OAAO,MAAM,GAAG,MAAM,uBAa5D,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/utils/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,KAAK,EAAE,sBAAsB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEzF,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEzC,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,SAAS;;;;;;EAMpB,CAAC;AAEH,eAAO,MAAM,sBAAsB,EAAE;IACnC,WAAW,EAAE,aAAa,CAAC;IAC3B,QAAQ,EAAE,UAAU,CAAC;IACrB,aAAa,EAAE,eAAe,CAAC;IAC/B,OAAO,EAAE,SAAS,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAOf,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;CAK9B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAG9D,eAAO,MAAM,4BAA4B,GACvC,WAAW,sBAAsB,EACjC,uBAAuB,OAAO,KAC7B,QAAQ,GAAG,SAcb,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,YAAY,YAErD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,YAAY,YACgB,CAAC;AAEvE;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,YAAY,YAA4C,CAAC;AAElG,eAAO,MAAM,sBAAsB,GAAI,MAAM,MAAM,uBACkB,CAAC;AAEtE,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,uBAW/C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,YAA+C,CAAC;AAEvF,eAAO,MAAM,gBAAgB,GAAI,UAAM,KAAG,MAIqC,CAAC;AAEhF,kEAAkE;AAClE,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,YAUzC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,gCAG9B;IACD,OAAO,EAAE,eAAe,GAAG,YAAY,CAAC;IACxC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,KAAG,MA8BH,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,WAI/C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,GAAI,UAAU,MAAM,WAgB5D,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,WAc1C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,UAExC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAC/B,cAAc,YAAY,GAAG,eAAe,GAAG,IAAI,EACnD,cAAc,YAAY,GAAG,eAAe,GAAG,IAAI,KAClD,OAuBF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GACrC,oBAAoB,YAAY,GAAG,eAAe,GAAG,IAAI,EACzD,oBAAoB,YAAY,GAAG,eAAe,GAAG,IAAI,KACxD,OAgBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,EAAE,mBAAkB,MAAU,WAU7E,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,KAAK,MAAM,WAS7C,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,OAAO,MAAM,GAAG,MAAM,uBAa5D,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stream-chat-react-native-core",
   "description": "The official React Native and Expo components for Stream Chat, a service for building chat applications",
-  "version": "10.0.0-rc.1",
+  "version": "10.0.0-rc.2",
   "author": {
     "company": "Stream.io Inc",
     "name": "Stream.io Inc"
@@ -85,7 +85,7 @@
     "react-native-markdown-package": "1.8.2",
     "react-native-url-polyfill": "^2.0.0",
     "react-syntax-highlighter": "^16.1.0",
-    "stream-chat": "^10.0.0-rc.22",
+    "stream-chat": "^10.0.0-rc.25",
     "use-sync-external-store": "^1.7.0",
     "zod": "^4.1.12"
   },
@@ -158,7 +158,7 @@
     "react": "19.3.0",
     "react-native": "0.88.0",
     "react-native-builder-bob": "0.40.11",
-    "react-native-gesture-handler": "^3.3.0",
+    "react-native-gesture-handler": "^3.4.0",
     "react-native-reanimated": "^4.7.1",
     "react-native-safe-area-context": "^5.10.1",
     "react-native-svg": "15.15.5",

package/src/__tests__/offline-support/offline-feature.tsx

@@ -83,7 +83,7 @@ import { BetterSqlite } from '../../test-utils/BetterSqlite';
 const ChannelPreviewComponent = ({ channel }: { channel: ChannelLLC }) => (
   <View accessibilityLabel='list-item' testID={channel.cid}>
     <Text>{channel.data?.custom?.name}</Text>
-    <Text>{channel.messagePaginator?.headItems?.[0]?.text}</Text>
+    <Text>{channel.messagePaginator?.anchoredHeadItems?.[0]?.text}</Text>
   </View>
 );
 
@@ -386,6 +386,14 @@ export const Generic = () => {
     });
 
     it('should store filter-sort query and cids on ChannelList in channelQueries table', async () => {
+      // A server returns the list in `sort` order, here by each channel's latest message, ascending.
+      // The generated messages have random times, so give them ordered ones: the reconnect below
+      // re-queries the list and sorts what it gets back, which would reorder an unsorted mock.
+      channels.forEach((channel, channelIndex) =>
+        channel.messages.forEach((message, messageIndex) => {
+          message.created_at = dateToNs(new Date(Date.UTC(2026, 0, 1, channelIndex, messageIndex)));
+        }),
+      );
       useMockedApis(chatClient, [queryChannelsApi(channels)]);
       await renderComponent();
 
@@ -796,7 +804,8 @@ export const Generic = () => {
         expect(matchingRows.length).toBe(1);
         expect(matchingRows[0].hidden).toBeTruthy();
         expect(matchingMessagesRows.length).toBe(
-          chatClient.channelManager.get(hiddenChannel.cid)?.messagePaginator.headItems.length,
+          chatClient.channelManager.get(hiddenChannel.cid)?.messagePaginator.anchoredHeadItems
+            .length,
         );
       });
     });
@@ -831,7 +840,8 @@ export const Generic = () => {
         expect(matchingRows.length).toBe(1);
         expect(matchingRows[0].hidden).toBeTruthy();
         expect(matchingMessagesRows.length).toBe(
-          chatClient.channelManager.get(hiddenChannel.cid)?.messagePaginator.headItems.length,
+          chatClient.channelManager.get(hiddenChannel.cid)?.messagePaginator.anchoredHeadItems
+            .length,
         );
       });
 
@@ -858,7 +868,8 @@ export const Generic = () => {
         expect(matchingRows.length).toBe(1);
         expect(matchingRows[0].hidden).toBeFalsy();
         expect(matchingMessagesRows.length).toBe(
-          chatClient.channelManager.get(hiddenChannel.cid)?.messagePaginator.headItems.length,
+          chatClient.channelManager.get(hiddenChannel.cid)?.messagePaginator.anchoredHeadItems
+            .length,
         );
       });
     });

package/src/__tests__/offline-support/optimistic-update.tsx

@@ -208,7 +208,7 @@ export const OptimisticUpdates = () => {
       jest.clearAllMocks();
 
       chatClient = await getTestClientWithUser({ id: 'dan' });
-      const channelResponse = createChannel();
+      channelResponse = createChannel();
       useMockedApis(chatClient, [getOrCreateChannelApi(channelResponse)]);
       channel = chatClient.channel('messaging', channelResponse.id);
       await channel.watch();
@@ -237,6 +237,7 @@ export const OptimisticUpdates = () => {
     });
 
     let channel: ChannelLLC;
+    let channelResponse: ReturnType<typeof createChannel>;
     // This component is used for performing effects in a component that consumes ChannelContext,
     // i.e. making use of the callbacks & values provided by the Channel component.
     // the effect is called every time channelContext changes
@@ -380,7 +381,7 @@ export const OptimisticUpdates = () => {
       // is intentionally NOT queued. Force the offline case. See the delete-message variant for detail.
       it('pending task should exist if sendReaction request fails', async () => {
         const reaction = generateReaction();
-        const targetMessage = channel.messagePaginator.headItems[0];
+        const targetMessage = channel.messagePaginator.anchoredHeadItems[0];
 
         render(
           <Chat client={chatClient} enableOfflineSupport>
@@ -415,7 +416,7 @@ export const OptimisticUpdates = () => {
 
       it('pending task should be cleared if sendReaction request is successful', async () => {
         const reaction = generateReaction();
-        const targetMessage = channel.messagePaginator.headItems[0];
+        const targetMessage = channel.messagePaginator.anchoredHeadItems[0];
 
         render(
           <Chat client={chatClient} enableOfflineSupport>
@@ -516,7 +517,7 @@ export const OptimisticUpdates = () => {
       // is intentionally NOT queued. Force the offline case. See the delete-message variant for detail.
       it('pending task should exist if deleteReaction request fails', async () => {
         const reaction = generateReaction();
-        const targetMessage = channel.messagePaginator.headItems[0];
+        const targetMessage = channel.messagePaginator.anchoredHeadItems[0];
 
         render(
           <Chat client={chatClient} enableOfflineSupport>
@@ -549,7 +550,7 @@ export const OptimisticUpdates = () => {
 
       it('pending task should be cleared if deleteReaction request is successful', async () => {
         const reaction = generateReaction();
-        const targetMessage = channel.messagePaginator.headItems[0];
+        const targetMessage = channel.messagePaginator.anchoredHeadItems[0];
 
         render(
           <Chat client={chatClient} enableOfflineSupport>
@@ -576,7 +577,7 @@ export const OptimisticUpdates = () => {
 
     describe('edit message', () => {
       it('should keep the optimistic edit in state and DB if the LLC queues the edit', async () => {
-        const message = channel.messagePaginator.headItems[0];
+        const message = channel.messagePaginator.anchoredHeadItems[0];
         const editedText = 'edited while offline';
 
         // Registered declaratively — the `<Channel doUpdateMessageRequest>` prop is gone. The LLC
@@ -666,7 +667,7 @@ export const OptimisticUpdates = () => {
       });
 
       it('should keep the optimistic edit if the request fails', async () => {
-        const message = channel.messagePaginator.headItems[0];
+        const message = channel.messagePaginator.anchoredHeadItems[0];
         const editedText = 'should stay optimistic';
 
         // Registered declaratively — the `<Channel doUpdateMessageRequest>` prop is gone. The LLC
@@ -738,7 +739,7 @@ export const OptimisticUpdates = () => {
         // failed message carries no message_text_updated_at. generateMessage always sets one, so strip
         // it here; the test then verifies the optimistic edit path does not add one back.
         const { message_text_updated_at: _stripped, ...headItem } = channel.messagePaginator
-          .headItems[0] as LocalMessage & { message_text_updated_at?: Date };
+          .anchoredHeadItems[0] as LocalMessage & { message_text_updated_at?: Date };
         const message = headItem as LocalMessage;
         const optimisticStateSpy = jest.fn();
 
@@ -795,7 +796,7 @@ export const OptimisticUpdates = () => {
       });
 
       it('should keep the optimistic edit for attachment updates without auto-queueing', async () => {
-        const message = channel.messagePaginator.headItems[0];
+        const message = channel.messagePaginator.anchoredHeadItems[0];
         const editedText = 'edited attachment message';
         const localUri = 'file://edited-attachment.png';
         const editedAttachments = [
@@ -899,7 +900,7 @@ export const OptimisticUpdates = () => {
     // failing until the default optimistic offline update/delete lands — the red is the signal.
     describe('default offline update/delete (no custom handler)', () => {
       it('should optimistically apply + persist an offline edit without a custom doUpdateMessageRequest', async () => {
-        const message = channel.messagePaginator.headItems[0];
+        const message = channel.messagePaginator.anchoredHeadItems[0];
         const editedText = 'edited offline via default path';
 
         render(
@@ -953,7 +954,7 @@ export const OptimisticUpdates = () => {
       });
 
       it('should optimistically apply + persist an offline delete without a custom doDeleteMessageRequest', async () => {
-        const message = channel.messagePaginator.headItems[0];
+        const message = channel.messagePaginator.anchoredHeadItems[0];
 
         render(
           <Chat client={chatClient} enableOfflineSupport>
@@ -1121,7 +1122,7 @@ export const OptimisticUpdates = () => {
 
     describe('optimistic edit without offline support', () => {
       it('keeps the optimistic edit AND surfaces the failure when there is no offline DB', async () => {
-        const message = channel.messagePaginator.headItems[0];
+        const message = channel.messagePaginator.anchoredHeadItems[0];
         const editedText = 'edited with no offline support';
 
         chatClient.config.set({
@@ -1180,7 +1181,7 @@ export const OptimisticUpdates = () => {
       jest.setTimeout(20_000);
 
       it('pending task should be executed after connection is recovered', async () => {
-        const message = channel.messagePaginator.headItems[0];
+        const message = channel.messagePaginator.anchoredHeadItems[0];
         const reaction = generateReaction();
 
         render(
@@ -1291,7 +1292,7 @@ export const OptimisticUpdates = () => {
       it('should not re-add a failed local message after reconnect when its pending send task was resolved', async () => {
         const localMessage = generateMessage({
           // The channel paginator only ingests messages whose cid matches (matchesFilter), so the
-          // optimistic message must carry the channel cid to appear in the paginator/headItems.
+          // optimistic message must carry the channel cid to appear in the paginator/anchoredHeadItems.
           cid: channel.cid,
           status: MessageStatusTypes.SENDING,
           text: 'offline resend',
@@ -1344,14 +1345,21 @@ export const OptimisticUpdates = () => {
         });
 
         expect(
-          channel.messagePaginator.headItems.some((message) => message.id === localMessage.id),
+          channel.messagePaginator.anchoredHeadItems.some(
+            (message) => message.id === localMessage.id,
+          ),
         ).toBe(true);
 
-        jest
-          .spyOn(channel, 'watch')
-          .mockResolvedValue({} as Awaited<ReturnType<typeof channel.watch>>);
+        // The reconnect reloads the active channel, and by then the server has the sent message. A
+        // page without it would remove the message as deleted while offline.
+        useMockedApis(chatClient, [
+          getOrCreateChannelApi({
+            ...channelResponse,
+            messages: [...channelResponse.messages, serverMessage],
+          }),
+        ]);
         // Without this the reconnect below nukes the offline DB. `client.sync` is a POST, so it
-        // resolves with the `getOrCreateChannelApi` payload mocked in `beforeEach`, whose `events` is
+        // resolves with the `getOrCreateChannelApi` payload mocked above, whose `events` is
         // undefined; `OfflineDBSyncManager.sync` then throws reading `result.events.length` and its
         // catch block calls `resetDB()` — taking the persisted failed message with it. Nothing to do
         // with what these tests assert, so give sync an empty, well-formed reply.
@@ -1380,7 +1388,7 @@ export const OptimisticUpdates = () => {
         });
 
         await waitFor(() => {
-          const matchingMessages = channel.messagePaginator.headItems.filter(
+          const matchingMessages = channel.messagePaginator.anchoredHeadItems.filter(
             (message) => message.text === localMessage.text,
           );
 
@@ -1399,7 +1407,7 @@ export const OptimisticUpdates = () => {
       it('should re-add a failed local message after reconnect when fresh state still does not contain it', async () => {
         const localMessage = generateMessage({
           // The channel paginator only ingests messages whose cid matches (matchesFilter), so the
-          // optimistic message must carry the channel cid to appear in the paginator/headItems.
+          // optimistic message must carry the channel cid to appear in the paginator/anchoredHeadItems.
           cid: channel.cid,
           status: MessageStatusTypes.SENDING,
           text: 'offline resend unresolved',
@@ -1476,7 +1484,7 @@ export const OptimisticUpdates = () => {
         });
 
         await waitFor(() => {
-          const matchingMessages = channel.messagePaginator.headItems.filter(
+          const matchingMessages = channel.messagePaginator.anchoredHeadItems.filter(
             (message) => message.id === localMessage.id,
           );
 

package/src/a11y/a11yUtils.ts

@@ -1,15 +1,22 @@
 /**
- * Compose a single accessibility label from multiple parts.
- * Empty/null/undefined parts are filtered out, the remainder joined with a comma+space
- * so screen readers add a brief pause between segments.
+ * Joins the non-empty `parts` into one accessibility label, separated by commas so screen readers
+ * pause between segments.
+ *
+ * @param parts Label segments; empty strings and non-strings are dropped.
+ * @returns The joined label, or an empty string when no part remains.
  */
 export const composeAccessibilityLabel = (
   ...parts: Array<string | null | undefined | false>
 ): string => parts.filter((p): p is string => typeof p === 'string' && p.length > 0).join(', ');
 
 /**
- * Build the value object passed to `accessibilityValue` for progress/seek surfaces.
- * Mirrors the React SDK's `progressBarA11y.ts` shape.
+ * Builds the `accessibilityValue` object for progress and seek surfaces.
+ *
+ * @param params.max Upper bound of the range.
+ * @param params.min Lower bound of the range. Defaults to 0.
+ * @param params.now Current value, clamped to `[min, max]`.
+ * @param params.text Optional spoken description, omitted from the result when empty.
+ * @returns The `accessibilityValue` object.
  */
 export const formatAccessibilityValue = ({
   max,
@@ -31,11 +38,14 @@ export const formatAccessibilityValue = ({
   return value;
 };
 
-/**
- * Merge two `accessibilityActions` arrays, deduplicating by `name` (later wins).
- */
 type A11yAction = Readonly<{ name: string; label?: string }>;
 
+/**
+ * Merges `accessibilityActions` lists, deduplicating by `name` (the later list wins).
+ *
+ * @param actionLists Lists of actions; `undefined` entries are skipped.
+ * @returns The merged actions, in first-seen order of their `name`.
+ */
 export const mergeAccessibilityActions = (
   ...actionLists: Array<ReadonlyArray<A11yAction> | undefined>
 ): A11yAction[] => {

package/src/a11y/hooks/useA11yLabel.ts

@@ -5,20 +5,22 @@ import { TranslationContext } from '../../contexts/translationContext/Translatio
 import { asDynamicKey } from '../../i18n/utils';
 
 /**
- * Returns the translated `a11y/...` label when the AccessibilityContext is enabled,
- * or `undefined` when disabled. Components pass the result straight to
- * `accessibilityLabel` so the i18n lookup is skipped on hot list paths in the
- * default disabled-state.
+ * Returns the translated accessibility label for `key`, or `undefined` when accessibility is
+ * disabled, so the i18n lookup is skipped on hot list paths.
  *
  * Example:
  *   const labelParams = useMemo(() => ({ name }), [name]);
- *   const label = useA11yLabel('a11y/Avatar of {{name}}', labelParams);
+ *   const label = useA11yLabel('avatar.accessibilityLabel', labelParams);
  *   <Image accessibilityLabel={label} />
+ *
+ * @param key Translation key, such as `avatar.accessibilityLabel`.
+ * @param params Interpolation values for the translation.
+ * @returns The label to pass to `accessibilityLabel`.
  */
 export const useA11yLabel = (key: string, params?: Record<string, unknown>): string | undefined => {
   const { enabled } = useAccessibilityContext();
   const { t } = useContext(TranslationContext);
   if (!enabled || !key) return undefined;
-  // `key` is a caller-supplied string, so this is the deliberate runtime-key escape hatch.
+  // `key` is a caller-supplied string, so it bypasses the typed translation keys.
   return t(asDynamicKey(key), params);
 };

package/src/a11y/hooks/useAccessibilityActivateAction.ts

@@ -19,10 +19,13 @@ const accessibilityActivateActions: NonNullable<ViewProps['accessibilityActions'
 ];
 
 /**
- * Adds the standard screen-reader `activate` action for labeled pressables when
- * SDK accessibility is enabled. Some Android pressable implementations don't
- * reliably map TalkBack double-tap to `onPress`, so this bridges the generated
- * accessibility action back to the existing press handler.
+ * Returns the screen-reader `activate` accessibility action for a pressable, wired to `onPress`.
+ * Some Android pressables do not map the TalkBack double-tap to `onPress`.
+ *
+ * @param params.onPress Press handler invoked on `activate`.
+ * @param params.shouldHandleActivate Opts the pressable in. Defaults to false.
+ * @returns The action props to spread on the pressable, or `undefined` when accessibility is
+ * disabled, the opt-in is off or there is no `onPress`.
  */
 export const useAccessibilityActivateAction = <TPressEvent>({
   onPress,

package/src/a11y/hooks/useAccessibilityServiceEnabled.ts

@@ -4,22 +4,13 @@ import { AccessibilityInfo, AppState, Platform } from 'react-native';
 import { useAccessibilityContext } from '../../contexts/accessibilityContext/AccessibilityContext';
 
 /**
- * Subscribes to Android accessibility service availability and returns the live state.
+ * Tracks whether any Android accessibility service is running (TalkBack, Switch Access, Voice
+ * Access and so on, not only screen readers).
  *
- * `AccessibilityInfo.isAccessibilityServiceEnabled` reports whether ANY a11y service is
- * running - TalkBack, Switch Access, Voice Access, Select to Speak, etc.  not just
- * screen readers. The signal is Android only; iOS doesn't expose it (and doesn't need to,
- * since the SDK's iOS overlay trap uses `accessibilityViewIsModal`).
+ * React Native emits no change event for this signal, so the state is refreshed on
+ * `screenReaderChanged` and when the app returns to the foreground.
  *
- * React Native does not emit a dedicated change event for this signal, so the hook
- * re-polls when the app returns to the foreground - which is the realistic path for a
- * user toggling Accessibility settings and coming back to the app. The most common
- * single service change (TalkBack on/off) is also covered by the `screenReaderChanged`
- * listener.
- *
- * Returns false on non-Android platforms without subscribing.
- * Returns false when the `AccessibilityContext` is disabled so consumers don't pay the
- * listener cost when the SDK's a11y is opted out.
+ * @returns Whether a service is running. Always false on iOS and when accessibility is disabled.
  */
 export const useAccessibilityServiceEnabled = (): boolean => {
   const { enabled } = useAccessibilityContext();
@@ -39,7 +30,7 @@ export const useAccessibilityServiceEnabled = (): boolean => {
           if (!cancelled) setIsEnabled(value);
         })
         .catch(() => {
-          // Older RN versions / certain environments may not implement this; fall back to false.
+          // The API may be unavailable in older RN versions; stay false.
         });
     };
 

package/src/a11y/hooks/useAnnounceOnShow.ts

@@ -9,17 +9,14 @@ type Options = {
 };
 
 /**
- * Announces `message` once each time `visible` flips from false to true.
- * Resets when `visible` flips back to false, so the next show re-announces —
- * unlike `useAnnounceOnStateChange`, which announces on string change and
- * dedupes consecutive identical strings.
+ * Announces `message` each time `visible` flips from false to true, for transient surfaces such as
+ * modals and bottom sheets. Hiding the surface re-arms the announcement. Does nothing while
+ * `message` is `undefined`.
  *
- * Use this for transient surfaces that appear and disappear repeatedly within
- * a session (modals, autocomplete pickers, bottom sheets) where the user
- * benefits from hearing the affordance on every reappearance.
- *
- * When `message` is undefined (typically because `useA11yLabel` returned
- * undefined — a11y disabled or key missing), the hook is a no-op.
+ * @param visible Whether the surface is shown.
+ * @param message Text to announce.
+ * @param params.delayMs Delay before announcing. Defaults to 500.
+ * @param params.priority Announcement priority. Defaults to `polite`.
  */
 export const useAnnounceOnShow = (
   visible: boolean,

package/src/a11y/hooks/useAnnounceOnStateChange.ts

@@ -11,11 +11,12 @@ type UseAnnounceOnStateChangeOptions = {
 };
 
 /**
- * Announces `message` whenever it changes (and is non-empty), with a debounce
- * to avoid spamming the screen reader on rapid transitions.
+ * Announces `message` whenever it changes to a new non-empty value, debounced so rapid transitions
+ * do not flood the screen reader. Repeating the last announced message is skipped.
  *
- * Used by `AITypingIndicatorView` ("Thinking…" → "Generating…" → idle) and
- * the `Indicators` family (loading → loaded → error).
+ * @param message Text to announce.
+ * @param options.debounceMs Debounce before announcing. Defaults to 250.
+ * @param options.priority Announcement priority. Defaults to `polite`.
  */
 export const useAnnounceOnStateChange = (
   message: string | null | undefined,

package/src/a11y/hooks/useReducedMotionPreference.ts

@@ -4,8 +4,9 @@ import { AccessibilityInfo } from 'react-native';
 import { useAccessibilityContext } from '../../contexts/accessibilityContext/AccessibilityContext';
 
 /**
- * Subscribes to AccessibilityInfo reduce-motion changes and returns the live state.
- * Returns false when the AccessibilityContext is disabled.
+ * Tracks the OS reduce-motion setting.
+ *
+ * @returns Whether reduce motion is on. Always false when accessibility is disabled.
  */
 export const useReducedMotionPreference = (): boolean => {
   const { enabled } = useAccessibilityContext();
@@ -23,7 +24,7 @@ export const useReducedMotionPreference = (): boolean => {
         if (!cancelled) setReduceMotion(value);
       })
       .catch(() => {
-        // Older RN or platforms without the API.
+        // The API may be unavailable on some platforms; stay false.
       });
 
     const subscription = AccessibilityInfo.addEventListener('reduceMotionChanged', setReduceMotion);