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

package/src/ai-components/markdown/utils/generate-markdown-text.ts

@@ -7,15 +7,10 @@ export function escapeRegExp(text: string) {
   return text.replace(/[-[\]{}()*+?.,/\\^$|#]/g, '\\$&');
 }
 
-/**
- * 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)
- * */
+/** Removes markdown links such as `[Google](https://www.google.com)` from `input`. */
 const removeMarkdownLinksFromText = (input: string) => input.replace(/\[.*\]\(.*\)/g, '');
 
-/**
- * This is done to avoid parsing usernames with dot as well as an email address in it.
- */
+/** Removes `@name@domain.tld` mentions so a username with an email is not parsed as a link. */
 const removeUserNamesWithEmailFromText = (input: string) =>
   input.replace(/@(\w+(\.\w+)?)(@\w+\.\w+)/g, '');
 
@@ -33,7 +28,8 @@ 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
+    // Hrefs without a built-in scheme get `http://`:
+    // https://reactnative.dev/docs/0.73/linking?syntax=ios#built-in-url-schemes
     const pattern = new RegExp(/^(mailto:|tel:|sms:|\S+:\/\/)/);
     if (!pattern.test(hrefWithProtocol)) {
       hrefWithProtocol = 'http://' + hrefWithProtocol;
@@ -53,10 +49,8 @@ export const generateMarkdownText = (text?: string) => {
     return null;
   }
 
-  // Trim the extra spaces from the text.
   let resultText = text;
 
-  // List of all the links present in the text.
   const linkInfos = parseLinksFromText(resultText);
 
   for (const linkInfo of linkInfos) {
@@ -64,14 +58,13 @@ export const generateMarkdownText = (text?: string) => {
       length: 200,
       omission: '...',
     });
-    // Convert raw links/emails in the text to respective markdown syntax.
-    // Eg: Hi @getstream.io -> Hi @[getstream.io](getstream.io).
+    // Wrap each raw link or email in markdown link syntax.
     const normalRegEx = new RegExp(escapeRegExp(linkInfo.raw), 'g');
     const markdown = `[${displayLink}](${linkInfo.url})`;
     resultText = resultText.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.
+    // Undo it for a link right after `@`, so a mention stays plain text:
+    // `@[test.user@gmail.com](mailto:test.user@gmail.com)` becomes `@test.user@gmail.com`.
     const mentionsRegex = new RegExp(
       `@\\[${escapeRegExp(displayLink)}\\]\\(${escapeRegExp(linkInfo.url)}\\)`,
       'g',
@@ -79,33 +72,27 @@ export const generateMarkdownText = (text?: string) => {
     resultText = resultText.replace(mentionsRegex, `@${displayLink}`);
   }
 
-  // Remove whitespaces that come directly after newlines except in code blocks where we deem this allowed.
-  // A line starts a (possibly quoted) list item if, after indentation, it has
-  //   - unordered bullet: -, *, +
-  //   - or ordered marker: 1. 2. 10.
-  // and at least one space after the marker.
+  // Collapses indentation after a newline, except in code and before a list item (a `-`, `*`, `+`
+  // or `1.` marker followed by a space, at any nesting depth, optionally quoted with `>`).
   const LIST_START_RE = /^[ \t]*(?:> ?)*?(?:[*+-]|\d+\.)(?: |\t)(?:\[(?: |x|X)\] )?/;
 
   resultText = resultText.replace(
     // 1) fenced code blocks (``` <some code here> ```)
     // 2) inline code (`…`)
-    // 3) newline + 2 + spaces/tabs
+    // 3) newline followed by 2 or more spaces/tabs
     /(```[\s\S]*?```|`[^`]*?`)|\n([ \t]{2,})/g,
     (match, code, spaces, offset, full) => {
-      // Preserve code spans / fences exactly as they are
+      // Code spans and fences are returned untouched.
       if (code) return code;
 
-      // Peek what follows this newline + the indent on the same line
       const after = full.slice(offset + match.length);
 
-      // If that line begins with a list item (any nesting depth, optional > quotes),
-      // keep the indentation; otherwise collapse to a single newline.
       return LIST_START_RE.test(after) ? `\n${spaces}` : '\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 each fence makes the parser treat it as a separate block, which code blocks
+  // inside list items need. The renderer cleans up the closing state of the code block.
   resultText = resultText.replace(/\n```/g, '\n\n```\n');
 
   const codeBlockCounts = (resultText.match(/```/g) || []).length;

package/src/ai-components/message-composer/SpeechToTextButton.tsx

@@ -20,10 +20,7 @@ type SpeechToTextButtonProps = {
   options?: DictationStartOptions;
 };
 
-/**
- * Renders nothing when the native dictation module is not part of the build (see
- * `isDictationAvailable`), so that pressing the button can never reach a missing module.
- */
+/** Renders nothing when the native dictation module is not part of the build. */
 export const SpeechToTextButton = (props: SpeechToTextButtonProps) => {
   if (!isDictationAvailable()) {
     warnIfDictationUnavailable();

package/src/ai-components/native/AIDictation.ts

@@ -23,9 +23,11 @@ const getEventEmitter = () => {
 const noop = () => {};
 
 /**
- * Whether the native dictation module is part of this build. It is always compiled in on Android,
- * while on iOS it is opt-in: add `$StreamChatEnableDictation = true` to your
- * `Podfile` (or use the `stream-chat-expo` config plugin) and run `pod install`.
+ * Whether the native dictation module is part of this build. It is always compiled in on Android;
+ * on iOS add `$StreamChatEnableDictation = true` to the `Podfile` (or use the `stream-chat-expo`
+ * config plugin) and run `pod install`.
+ *
+ * @returns True when the native module is present.
  */
 export const isDictationAvailable = () => NativeAIDictation != null;
 
@@ -42,7 +44,6 @@ export const warnIfDictationUnavailable = () => {
   );
 };
 
-// Low-level API
 export const AIDictation = {
   start(options?: DictationStartOptions) {
     NativeAIDictation?.start(options);

package/src/ai-components/native-specs/NativeAIDictation.ts

@@ -4,13 +4,13 @@ import { TurboModuleRegistry } from 'react-native';
 /**
  * Codegen spec of the native dictation module.
  *
- * This file is duplicated (byte for byte) in `package/native-package/src/native/NativeAIDictation.ts`
- * and `package/expo-package/src/native/NativeAIDictation.ts`, which are the copies codegen reads.
- * `yarn validate-entry-isolation` fails if they drift apart.
+ * Duplicated byte for byte in `package/native-package/src/native/NativeAIDictation.ts` and
+ * `package/expo-package/src/native/NativeAIDictation.ts`, the copies codegen reads;
+ * `yarn validate-entry-isolation` fails when they drift apart.
  *
- * Events are delivered through `addListener`/`removeListeners` and a `NativeEventEmitter` (see
- * `../native/AIDictation.ts`) rather than codegen `EventEmitter` properties, since the latter are
- * not understood by the codegen of every React Native version the SDK supports (>= 0.76).
+ * Events go through `addListener`/`removeListeners` and a `NativeEventEmitter` (see
+ * `../native/AIDictation.ts`), because codegen `EventEmitter` properties are not understood by
+ * every React Native version the SDK supports.
  */
 
 export type DictationStartOptions = {
@@ -42,7 +42,6 @@ export interface Spec extends TurboModule {
   removeListeners(count: number): void;
 }
 
-// `get` rather than `getEnforcing`: the module is only compiled in when dictation is enabled
-// (always on Android, opt-in on iOS), and importing the AI entry point
-// must not throw when it is absent.
+// `get` returns null when absent: the module is only compiled in when dictation is enabled (always
+// on Android, opt-in on iOS), and importing the AI entry point must not throw without it.
 export default TurboModuleRegistry.get<Spec>('AIDictation');

package/src/ai-components/services/clipboard-service/expo.ts

@@ -3,7 +3,7 @@ let Clipboard: { setString: (string: string) => void } | undefined;
 try {
   Clipboard = require('expo-clipboard');
 } catch (_) {
-  // do nothing
+  // `expo-clipboard` is not installed.
 }
 
 export const setClipboardString = Clipboard

package/src/ai-components/services/clipboard-service/rncli.ts

@@ -3,7 +3,7 @@ let Clipboard: { setString: (string: string) => void } | undefined;
 try {
   Clipboard = require('@react-native-clipboard/clipboard').default;
 } catch (_) {
-  // do nothing
+  // `@react-native-clipboard/clipboard` is not installed.
 }
 
 export const setClipboardString = Clipboard

package/src/ai-components/services/media-picker-service/expo.ts

@@ -13,7 +13,7 @@ let internalService = undefined;
 try {
   internalService = require('expo-image-picker');
 } catch (_error) {
-  /* do nothing */
+  // `expo-image-picker` is not installed.
 }
 
 type Size = {
@@ -91,7 +91,7 @@ class ExpoMediaPickerService extends AbstractMediaPickerService {
         if (!result || !result.assets || !result.assets.length || result.canceled) {
           return { cancelled: true };
         }
-        // since we only support single photo upload for now we will only be focusing on 0'th element.
+        // Only a single photo is supported, so only the first asset is read.
         const photo = result.assets[0];
         if (!photo) {
           return { cancelled: true };

package/src/ai-components/services/media-picker-service/optional-modules.d.ts

@@ -1,6 +1,6 @@
-// The image picker libraries are optional peer dependencies (`react-native-image-picker` for React
-// Native CLI apps, `expo-image-picker` for Expo apps) and are not installed in this package. Only
-// the asset shapes the media picker services read are declared here.
+// Optional peer dependencies that are not installed in this package: `react-native-image-picker`
+// (React Native CLI) and `expo-image-picker` (Expo). Only the asset shapes the media picker
+// services read are declared.
 
 declare module 'react-native-image-picker' {
   export type Asset = {

package/src/ai-components/services/media-picker-service/rncli.ts

@@ -12,7 +12,7 @@ let internalService = undefined;
 try {
   internalService = require('react-native-image-picker');
 } catch (_error) {
-  /* do nothing */
+  // `react-native-image-picker` is not installed.
 }
 
 class RNCLIMediaPickerService extends AbstractMediaPickerService {
@@ -96,7 +96,6 @@ class RNCLIMediaPickerService extends AbstractMediaPickerService {
             size.height = height;
             size.width = width;
           } catch (e) {
-            // do nothing
             console.warn('Error while getting image size of picture captured from camera ', e);
           }
         } else {
@@ -122,10 +121,11 @@ class RNCLIMediaPickerService extends AbstractMediaPickerService {
       }
     } catch (e: unknown) {
       if (e instanceof Error) {
-        // on iOS: if it was in inactive state, then the user had just denied the permissions
+        // On iOS the permission dialog makes the app inactive, so an inactive state means the user
+        // just denied it; settings are offered only when the app is active.
         if (Platform.OS === 'ios' && AppState.currentState === 'active') {
           const cameraPermissionDeniedMsg = 'User did not grant camera permission.';
-          // Open settings when the user did not allow camera permissions
+          // Offer to open settings when camera permission was denied.
           if (e.message === cameraPermissionDeniedMsg) {
             return { askToOpenSettings: true, cancelled: true };
           }

package/src/ai-components/store/index.ts

@@ -1,11 +1,8 @@
-// bottom sheet
 export * from './bottom-sheet/store';
 export * from './bottom-sheet/useBottomSheetState';
 
-// message composer
 export * from './composer/store';
 export * from './composer/useComposerHasText';
 export * from './composer/useComposerText';
 
-// dictation
 export * from './dictation/store';

package/src/ai-components/syntax-highlighting/index.ts

@@ -1,7 +1,6 @@
 /**
- * This sub-library is a port/took inspiration from https://github.com/conorhastings/react-native-syntax-highlighter.
- * We create our own since we don't want the version of https://github.com/react-syntax-highlighter/react-syntax-highlighter
- * to be pinned to version 6 but rather use whatever we see fit.
+ * Adapted from https://github.com/conorhastings/react-native-syntax-highlighter.
+ * Maintained here so the `react-syntax-highlighter` dependency can be upgraded independently.
  */
 
 export * from './SyntaxHighlighter';

package/src/ai-components/syntax-highlighting/types.ts

@@ -17,10 +17,9 @@ export type NativeSyntaxHighlighterProps = SyntaxHighlighterProps & ExtraSyntaxH
 
 export type CSSP = React.CSSProperties;
 
-/** Options for unit conversion */
 export type ConvertOpts = {
-  /** base for `em` (defaults to 16) */
+  /** Base for `em` units. Defaults to 16. */
   baseFontSize?: number;
-  /** root base for `rem` (defaults to baseFontSize) */
+  /** Base for `rem` units. Defaults to `baseFontSize`. */
   rootFontSize?: number;
 };

package/src/ai-components/syntax-highlighting/utils/converter.ts

@@ -4,10 +4,10 @@ import type { ConvertOpts, CSSP } from '../types';
 
 const EM_DEFAULT = 16;
 
-// React Native's strict TypeScript API declares style properties as readonly.
+// Style properties are readonly in React Native's strict TypeScript API.
 type MutableTextStyle = { -readonly [K in keyof TextStyle]: TextStyle[K] };
 
-/** Parse CSS lengths like 14, "14", "14px", "1.25em", "0.875rem" */
+/** Parses a CSS length such as 14, "14px", "1.25em" or "0.875rem" into a number. */
 const len = (v: unknown, { baseFontSize, rootFontSize }: ConvertOpts): number | undefined => {
   if (v == null) return undefined;
   if (typeof v === 'number') return v;
@@ -27,43 +27,35 @@ const len = (v: unknown, { baseFontSize, rootFontSize }: ConvertOpts): number |
     const root = rootFontSize ?? baseFontSize ?? EM_DEFAULT;
     return Number.isFinite(n) ? n * root : undefined;
   }
-  // plain number-like string
   const n = Number(s);
   return Number.isFinite(n) ? n : undefined;
 };
 
-/** Font shorthand: e.g. "italic small-caps 700 14px/20px Menlo, monospace" */
+/** Parses a CSS `font` shorthand such as "italic small-caps 700 14px/20px Menlo, monospace". */
 const parseFontShorthand = (v: string, opts: ConvertOpts) => {
   const out: MutableTextStyle = {};
   const parts = v.split(/\s+/);
-  // Very light parser: pick out style, weight, size[/lineHeight], and family
-  // Strategy:
-  // - style: "normal|italic"
-  // - weight: "normal|bold|100..900"
-  // - when we hit a token like "14px" or "14px/20px" → size & optional lineHeight
-  // - everything after size token is font family (may contain commas/spaces)
+  // Reads in order: style, small-caps, weight, size[/lineHeight], then the family (everything after
+  // the size token, which may contain commas and spaces).
   let i = 0;
 
-  // style
   if (parts[i] === 'italic' || parts[i] === 'normal') {
     if (parts[i] !== 'normal') out.fontStyle = 'italic';
     i++;
   }
 
-  // (skip small-caps if present; RN uses fontVariant which is separate)
+  // RN models `small-caps` as `fontVariant`.
   if (parts[i] === 'small-caps') {
     out.fontVariant = ['small-caps'];
     i++;
   }
 
-  // weight
   if (/^(normal|bold|[1-9]00)$/.test(parts[i] ?? '')) {
     const token = parts[i]!;
     out.fontWeight = (token === 'normal' ? undefined : token) as TextStyle['fontWeight'];
     i++;
   }
 
-  // size[/lineHeight]
   const sizeToken = parts[i];
   if (
     sizeToken &&
@@ -79,10 +71,9 @@ const parseFontShorthand = (v: string, opts: ConvertOpts) => {
     i++;
   }
 
-  // family
   const family = parts.slice(i).join(' ').replace(/^,|,$/g, '').trim();
   if (family) {
-    // basic cleanup: take first family; strip quotes
+    // Only the first family is kept, without quotes.
     const first = family
       .split(',')[0]
       ?.trim()
@@ -93,7 +84,13 @@ const parseFontShorthand = (v: string, opts: ConvertOpts) => {
   return out;
 };
 
-/** map CSS (web) to RN TextStyle */
+/**
+ * Converts web CSS properties to an RN `TextStyle`.
+ *
+ * @param css The CSS properties to convert.
+ * @param options Font size bases for `em` and `rem` units.
+ * @returns The equivalent `TextStyle`.
+ */
 export const cssToRNTextStyle = (css: Partial<CSSP>, options: ConvertOpts = {}): TextStyle => {
   const opts: ConvertOpts = {
     baseFontSize: options.baseFontSize ?? EM_DEFAULT,
@@ -102,7 +99,6 @@ export const cssToRNTextStyle = (css: Partial<CSSP>, options: ConvertOpts = {}):
 
   const out: MutableTextStyle = {};
 
-  // Simple 1:1 or unit-converted mappings
   if (css.color) out.color = String(css.color);
 
   if (css.fontFamily) out.fontFamily = String(css.fontFamily);
@@ -130,7 +126,7 @@ export const cssToRNTextStyle = (css: Partial<CSSP>, options: ConvertOpts = {}):
     Object.assign(out, parseFontShorthand(css.font, opts));
   }
 
-  // Simulating the closest we can get to a CSS overflow-like functionality
+  // Maps the CSS overflow values to the closest RN `overflow`.
   const overflowLike = css.overflow ?? css.overflowX ?? css.overflowY;
   if (typeof overflowLike === 'string') {
     out.overflow =

package/src/ai-components/syntax-highlighting/utils/flatten-nodes.ts

@@ -31,7 +31,6 @@ export const flattenNodesToTextAndColorRanges = ({
 
     const { type, tagName, value, properties } = node;
 
-    // leaf node
     if (type === 'text') {
       if (value == null || value === '') return;
       const chunk = String(value);
@@ -45,7 +44,6 @@ export const flattenNodesToTextAndColorRanges = ({
       return;
     }
 
-    // node with children
     if (tagName) {
       const baseStyle =
         properties && properties.className
@@ -56,9 +54,7 @@ export const flattenNodesToTextAndColorRanges = ({
             )
           : { ...startingStyle, color: defaultColor };
 
-      // we take the node's color if present, then its inherited color
-      // if present and finally the block's default color if all else
-      // fails.
+      // Color precedence: the node's own, then the inherited one, then the block's default.
       const effectiveColor =
         (baseStyle as { color?: string | number }).color ?? inheritedColor ?? defaultColor;
 
@@ -70,7 +66,6 @@ export const flattenNodesToTextAndColorRanges = ({
       return;
     }
 
-    // fallback
     if (value != null) {
       const chunk = String(value);
       const start = text.length;
@@ -82,20 +77,17 @@ export const flattenNodesToTextAndColorRanges = ({
     }
   };
 
-  // Recursively flatten nodes
   const nodeArray = Array.isArray(nodes) ? nodes : [nodes];
   for (let i = 0; i < nodeArray.length; i++) {
     walk(nodeArray[i], defaultColor);
   }
 
-  // Merge adjacent ranges with same color and convert them to integers
+  // Merges adjacent ranges of the same color and converts colors to integers.
   rawRanges.sort((a, b) => a.start - b.start);
   const merged: ColorRange[] = [];
   for (let i = 0; i < rawRanges.length; i++) {
     const r = rawRanges[i]!;
-    // in case the color is malformed for some reason, use the defaultColor
-    // as this one should always be non-nullish.
-    const colorInt = processColor(r.color)!; // ?? processColor(defaultColor))!;
+    const colorInt = processColor(r.color)!;
 
     if (!merged.length) {
       merged.push({ start: r.start, end: r.end, color: colorInt });
@@ -131,12 +123,12 @@ export const flattenRowsToTextAndColorRanges = (
     const offset = fullText.length;
     fullText += text;
 
-    // Add newline between rows (no color)
+    // Rows are joined by an uncolored newline.
     if (rowIndex < rows.length - 1) {
       fullText += '\n';
     }
 
-    // Shift ranges by current offset & push
+    // Shift the row ranges by its offset in the full text.
     for (const r of ranges) {
       fullRanges.push({
         start: r.start + offset,

package/src/components/AITypingIndicatorView/hooks/useAIState.ts

@@ -2,16 +2,16 @@ import { AIState, AIStates, Channel } from 'stream-chat';
 
 import { useStateStore } from '../../../hooks/useStateStore';
 
-// Re-export the canonical `AIStates` from the LLC so existing imports keep working
-// (`import { AIStates } from '.../AITypingIndicatorView'`).
+// Re-exports `AIStates` from `stream-chat` so it can be imported from this module.
 export { AIStates };
 
 const selector = (state: { aiState: AIState }) => ({ aiState: state.aiState });
 
 /**
- * A hook that returns the current state of the AI.
- * @param {Channel} channel - The channel for which we want to know the AI state.
- * @returns {{ aiState: AIState }} The current AI state for the given channel.
+ * Returns the AI state of `channel`, or the idle state when there is no channel state.
+ *
+ * @param channel The channel to read the AI state of.
+ * @returns The current AI state.
  */
 export const useAIState = (channel?: Channel): { aiState: AIState } =>
   useStateStore(channel?.state, selector) ?? { aiState: AIStates.Idle };

package/src/components/Accessibility/CompositeAccessibilityProbe.tsx

@@ -5,31 +5,19 @@ import { HiddenA11yText } from './HiddenA11yText';
 
 export type CompositeAccessibilityProbeProps = {
   /**
-   * The accessibility label that VoiceOver / TalkBack should announce for the
-   * wrapped content. When `undefined`, the probe is a no-op and the children
-   * render with no a11y modifications — use this to skip the wrapper when the
-   * SDK's a11y opt-in is off.
+   * Label that VoiceOver and TalkBack announce for the wrapped content. `undefined` renders the
+   * children unchanged.
    */
   label: string | undefined;
 };
 
 /**
- * Wraps decorative visual content with a single, cross platform stable
- * accessibility focus stop carrying the provided `label`.
+ * Gives decorative visual content (avatars, icons, composed graphics) a single screen reader focus
+ * stop that announces `label`, and hides the visual subtree from screen readers.
  *
- * iOS auto collapses descendants when a parent View is `accessible`, but on
- * Android `importantForAccessibility='no-hide-descendants'` on the parent
- * gets defeated by deeply nested descendants that set their own
- * `accessible={true}` (our SDK's `<Avatar>` does this). A zero size accessible
- * `<Text>` sidesteps that - Text is always accessible by default on both
- * platforms and carries the label cleanly, while the visual subtree is
- * marked decorative. More importantly, it's discoverable very very easily
- * by screen readers.
- *
- * Use this anywhere you have non-Text visual content (avatars, icons,
- * composed graphics) that should announce as a single semantic unit with a
- * curated label, rather than letting screen readers walk the visual tree
- * verbosely.
+ * The label lives on a visually hidden `<Text>` sibling because on Android a parent's
+ * `importantForAccessibility='no-hide-descendants'` is defeated by nested descendants that set
+ * `accessible` themselves, such as `<Avatar>`.
  */
 export const CompositeAccessibilityProbe = ({
   children,

package/src/components/Accessibility/HiddenA11yText.tsx

@@ -3,34 +3,24 @@ import { StyleSheet, Text } from 'react-native';
 
 export type HiddenA11yTextProps = {
   /**
-   * The text to inject into the accessibility tree. Rendered as actual Text
-   * content (not as `accessibilityLabel`) so the parent's compose loop on
-   * Android picks it up — Text without its own label isn't
-   * `isAccessibilityFocusable`, so it gets concatenated into the parent's
-   * announcement rather than being skipped as a drill-in target.
-   *
-   * Pass the result of `useA11yLabel(...)` directly: when SDK a11y is
-   * opt-out the value is `undefined` and the component renders nothing.
+   * Text added to the accessibility tree. It is rendered as `Text` content so that the parent's
+   * label composition on Android includes it. `undefined` (such as the result of `useA11yLabel`
+   * while accessibility is disabled) renders nothing.
    */
   label: string | undefined;
 };
 
 /**
- * A visually invisible Text that exists only to contribute extra information
- * to a screen reader's announcement. Use it inside a parent that auto-composes
- * descendant labels (Pressable, or any View with `accessible` + `accessibilityRole`)
- * to splice in supplementary state like "you reacted", "and N more", etc.
- *
- * Not for "this whole element should be one focus stop with a curated label" -
- * use `CompositeAccessibilityProbe` for that.
+ * Visually hidden text that adds information, such as "you reacted", to a screen reader
+ * announcement. Use it inside a parent that composes its descendants' labels (a `Pressable`, or a
+ * `View` with `accessible` and `accessibilityRole`). For one focus stop with a curated label, use
+ * `CompositeAccessibilityProbe`.
  */
 export const HiddenA11yText = ({ label }: HiddenA11yTextProps) => {
   if (!label) return null;
-  // Both content and accessibilityLabel are set to the same string. Content
-  // keeps the Text on the parent's compose loop (label-only would make it
-  // `isAccessibilityFocusable` and potentially skipped on Android — though
-  // the opacity:0 hidden style usually saves it). accessibilityLabel keeps
-  // testing-library `getByLabelText(...)` queries working.
+  // The label is both content and `accessibilityLabel`. Content keeps the Text in the parent's
+  // label composition on Android (a label-only Text is focusable and may be skipped); the label
+  // keeps testing-library `getByLabelText` queries working.
   return (
     <Text accessibilityLabel={label} style={styles.hidden}>
       {label}

package/src/components/Accessibility/NotificationAnnouncer.tsx

@@ -8,21 +8,14 @@ import { useNetworkConnectionState } from '../Chat/hooks/useNetworkConnectionSta
 import { useSettledWSConnectionHealth } from '../Chat/hooks/useWSConnectionState';
 
 /**
- * Mirrors stream-chat-react's `<NotificationAnnouncer />`. RN does not yet have a
- * unified Notification queue, so this component currently announces only
- * connection-state transitions (offline → online and back) gated on
- * `accessibility.announceConnectionState`. Per-channel error announcements can
- * be wired in by a future PR via `useChannelContext().error`.
- *
- * Renders nothing. Mount once inside `<Channel>` (or wherever the active chat
- * surface lives).
+ * Announces connection state transitions (connected, offline, reconnecting) to screen readers when
+ * `accessibility.announceConnectionState` is on. Renders nothing; mount once inside `<Channel>`.
  */
 export const NotificationAnnouncer = () => {
   const { announceConnectionState, enabled } = useAccessibilityContext();
   const isNetworkOnline = useNetworkConnectionState()?.isOnline;
   const isWSOnline = useSettledWSConnectionHealth();
-  // The socket is what 'connected' means to a chat user; the device network only decides which
-  // of the two offline messages is truthful.
+  // Online means the WebSocket is healthy; the network state only picks the offline message.
   const isOnline = !!isWSOnline;
   const announce = useAccessibilityAnnouncer();
   const { t } = useTranslationContext();

package/src/components/Accessibility/OverlayA11yShield.tsx

@@ -21,21 +21,14 @@ const useShouldActivateTrap = (): boolean => {
 };
 
 /**
- * Android only accessibility focus trap for the OverlayProvider's children
- * tree. iOS handles modal focus traps natively via `accessibilityViewIsModal`
- * on each overlay's root, but Android has no equivalent prop - the only
- * JS side mechanism is to mark siblings as `'no-hide-descendants'`.
+ * Android accessibility focus trap for the overlay host's children. iOS traps focus natively with
+ * `accessibilityViewIsModal` on each overlay root; Android can only mark siblings as
+ * `'no-hide-descendants'`.
  *
- * The shield wraps `{children}` in a single View whose `importantForAccessibility`
- * flips to `'no-hide-descendants'` whenever any focus trapping overlay is
- * active (the full screen image/video gallery or the message context menu).
- * When closed, the wrapper is a transparent passthrough.
- *
- * In terms of rerendering, only the wrapper View commits new props on overlay state
- * transitions. The `{children}` element reference is stable across renders,
- * so React reconciliation does not rerender any component below the wrapper.
- *
- * On iOS the wrapper is skipped entirely.
+ * Wraps `{children}` in a View that sets `importantForAccessibility='no-hide-descendants'` while an
+ * overlay (the image or video gallery, or the message context menu) is open and an accessibility
+ * service runs. Only the wrapper re-renders on overlay changes, since the `children` element is
+ * stable. On iOS it renders only the children.
  */
 export function OverlayA11yShield({ children }: PropsWithChildren) {
   const shouldActivateTrap = useShouldActivateTrap();