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

package/src/components/Attachment/utils/buildGallery/buildThumbnailGrid.ts

@@ -6,132 +6,18 @@ import type { GallerySizeAndThumbnailGrid, GallerySizeConfig, ThumbnailGrid } fr
 import { ChatConfigContextValue } from '../../../../contexts/chatConfigContext/ChatConfigContext';
 
 /**
- * Builds a grid of thumbnail images from image attachments.
- * This function take a object parameter with following properties:
- *
- * @params
- *
- * - {number[][]} grid - Grid pattern of the gallery. Each numeric value in the array represents the flex value of corresponding image in grid.
- * - {Attachment[]} images - Array of image attachments.
- * - {GallerySizeConfig} sizeConfig - Theme config for the gallery.
- * - {boolean} invertedDirections - Whether to invert the direction of the grid. By default grid is rendered with column as primary direction and row as secondary direction.
- *
- * @usage
- *
- * ```
- * const { thumbnailGrid, invertedDirection } = buildThumbnailGrid({
- *  grid: [[1], [1]],
- *  images: [image1, image2],
- *  sizeConfig: {
- *    gridHeight: 200,
- *    gridWidth: 200,
- *    maxHeight: 200,
- *    maxWidth: 200,
- *    minHeight: 200,
- *    minWidth: 200,
- *  },
- * })
- *
- * Rendering logic on UI:
- *
- * ```
- * <View style={{ flexDirection: invertedDirection ? 'row' : 'column }}>
- * {
- *  thumbnailGrid.forEach(rows => {
- *    return (
- *      <View style={{ flexDirection: invertedDirection ? 'column' : 'row' }}>
- *       {
- *        rows.forEach(thumbnail => (
- *          <Image
- *            source={{ uri: thumbnail.url }}
- *            resizeMode={thumbnail.resizeMode}
- *            width={thumbnail.width}
- *            height={thumbnail.height}
- *          />
- *       ))}
- *      </View>
- *    )});
- * }
- * </View>
- * ```
- *
- * Lets look at different examples of grid and invertedDirections param:
- *
- * EXAMPLE 1:
- *
- * ```
- * {
- *  grid: [[2, 1], [2, 1]]
- *  invertedDirections: false
- * }
- * ```
- *
- * Resulting thumbnail grid on rendered UI:
- *
- *  __________________
- * |            |     |
- * |            |     |
- * |------------------|
- * |            |     |
- * |            |     |
- *  ------------------
- *
- * EXAMPLE 2:
- *
- * ```
- * {
- *  grid: [[2, 1], [2, 1]]
- *  invertedDirections: true
- * }
- * ```
- * Resulting thumbnail grid on rendered UI:
- *  __________________
- * |         |        |
- * |         |        |
- * |         |        |
- * |         |        |
- * |------------------|
- * |         |        |
- * |         |        |
- *  ------------------
- *
- * EXAMPLE 3:
- *
- * ```
- * {
- *  grid: [[2, 1]]
- *  invertedDirections: false
- * }
- * ```
- * Resulting thumbnail grid on rendered UI:
- *  __________________
- * |                  |
- * |                  |
- * |                  |
- * |                  |
- * |------------------|
- * |                  |
- * |                  |
- *  ------------------
- *
- * EXAMPLE 4:
- *
- * ```
- * {
- *  grid: [[2, 1]]
- *  invertedDirections: true
- * }
- * ```
- * Resulting thumbnail grid on rendered UI:
- *  __________________
- * |            |     |
- * |            |     |
- * |            |     |
- * |            |     |
- * |            |     |
- *  ------------------
- *
- * @return {GallerySizeAndThumbnailGrid}
+ * Builds the thumbnail grid for image attachments, sized to `gridWidth` x `gridHeight`.
+ *
+ * Each inner array of `grid` is a column of thumbnails stacked top to bottom, sized by flex weight:
+ * `[[2, 1]]` is one column whose first thumbnail is twice as tall as the second. With
+ * `invertedDirections` each inner array is a row, laid out left to right instead.
+ *
+ * @param params.grid Flex weight of every thumbnail, per column (per row when inverted).
+ * @param params.images Image attachments, consumed in grid order.
+ * @param params.invertedDirections Swaps the roles of columns and rows. Defaults to false.
+ * @param params.resizableCDNHosts CDN hosts whose image URLs can be resized.
+ * @param params.sizeConfig Overall gallery size; only `gridHeight` and `gridWidth` are read here.
+ * @returns The grid size, its thumbnails and the `invertedDirections` it was built with.
  */
 export function buildThumbnailGrid({
   grid,

package/src/components/Attachment/utils/buildGallery/types.ts

@@ -4,7 +4,7 @@ export type Thumbnail = {
   resizeMode: ImageResizeMode;
   url: string;
   id?: string;
-  /** Same as attachment `localId` for correlating with `client.uploadManager` */
+  /** The attachment `localId`, which keys its upload in `client.uploadManager`. */
   localId?: string;
   thumb_url?: string;
   type?: string;

package/src/components/Attachment/utils/getAspectRatio.ts

@@ -3,10 +3,11 @@ import type { Attachment } from 'stream-chat';
 import { FileTypes } from '../../../types/types';
 
 /**
- * Returns the aspect ratio of an image attachment.
+ * Returns the aspect ratio (width / height) of an image attachment or video thumbnail.
  *
- * @param image Image attachment.
- * @returns {number}
+ * @param attachment Image attachment or video thumbnail.
+ * @returns The aspect ratio, or 1 when the original size is unknown.
+ * @throws When the attachment is not an image or a video.
  */
 export function getAspectRatio(attachment: Attachment) {
   if (!(attachment.type === FileTypes.Image || attachment.type === FileTypes.Video)) {

package/src/components/Attachment/utils/getGiphyMimeType.ts

@@ -1,7 +1,8 @@
 /**
+ * Infers the MIME type of a Giphy asset from its URL.
  *
- * @param giphyUrl The giphy attachment url
- * @returns mimeType for the giphy attachment
+ * @param giphyUrl The Giphy attachment URL.
+ * @returns `video/mp4` or `image/webp` for those extensions, `image/gif` otherwise.
  */
 export function getGiphyMimeType(giphyUrl: string): string {
   if (giphyUrl.includes('.mp4')) {

package/src/components/Attachment/utils/openUrlSafely.ts

@@ -1,8 +1,8 @@
 import { Linking } from 'react-native';
 
 export const openUrlSafely = async (url?: string) => {
-  // An attachment whose upload hasn't settled yet has no remote URL. Without this guard the
-  // scheme fallback below would turn it into `http://undefined`, which `canOpenURL` accepts.
+  // An attachment still uploading has no remote URL, and the scheme fallback below would turn
+  // it into `http://undefined`.
   if (!url) {
     return;
   }

package/src/components/AttachmentPicker/AttachmentPicker.tsx

@@ -101,10 +101,7 @@ export const AttachmentPicker = () => {
     windowHeight - topInset - attachmentPickerBottomSheetHeight - bottomInset,
   );
 
-  /**
-   * Snap points changing cause a rerender of the position,
-   * this is an issue if you are calling close on the bottom sheet.
-   */
+  // A new snap points array re-renders the sheet position, which breaks closing the sheet.
   const snapPoints = useMemo(() => [initialSnapPoint], [initialSnapPoint]);
 
   const onAttachmentPickerSelectionBarLayout = useStableCallback((e: LayoutChangeEvent) => {
@@ -124,10 +121,7 @@ export const AttachmentPicker = () => {
 
   const animatedIndex = useSharedValue(currentIndex);
 
-  // This is required to prevent the attachment picker from getting out of sync
-  // with the rest of the state. While there are more prudent fixes, this is about
-  // as much as we can do now without refactoring the entire state layer for the
-  // picker. When we do that, this can be removed completely.
+  // Keeps the picker store in sync with the sheet index (-1 closed, 0 open).
   const reactToIndex = useStableCallback((index: number) => {
     if (index === -1) {
       attachmentPickerStore.setSelectedPicker(undefined);

package/src/components/AttachmentPicker/components/AttachmentMediaPicker/AttachmentMediaPicker.tsx

@@ -83,8 +83,6 @@ export const AttachmentMediaPicker = (props: AttachmentPickerContentProps) => {
         });
 
         endCursorRef.current = results.endCursor;
-        // skip updating if the sheet closed in the meantime, to avoid
-        // confusing the bottom sheet internals
         setPhotos((prevPhotos) => {
           if (endCursor) {
             return [...prevPhotos, ...results.assets];
@@ -116,13 +114,11 @@ export const AttachmentMediaPicker = (props: AttachmentPickerContentProps) => {
     if (!NativeHandlers.oniOS14GalleryLibrarySelectionChange) {
       return;
     }
-    // ios 14 library selection change event is fired when user reselects the images that are permitted to be
-    // readable by the app
+    // iOS 14 fires this when the user changes which photos the app is permitted to read.
     const { unsubscribe } = NativeHandlers.oniOS14GalleryLibrarySelectionChange(() => {
-      // we reset the cursor and has next page to true to facilitate fetching of the first page of photos again
+      // Restart pagination from the first page.
       hasNextPageRef.current = true;
       endCursorRef.current = undefined;
-      // fetch the first page of photos again
       getMorePhotos();
     });
     return unsubscribe;
@@ -144,8 +140,7 @@ export const AttachmentMediaPicker = (props: AttachmentPickerContentProps) => {
       !loadingPhotosRef.current
     ) {
       getMorePhotos();
-      // we do this only once on open for avoiding to request permissions in rationale dialog again and again on
-      // Android
+      // Once per open, so Android does not show the permission rationale dialog repeatedly.
       attemptedToLoadPhotosOnOpenRef.current = true;
     }
   }, [getMorePhotos]);

package/src/components/AttachmentPicker/components/AttachmentMediaPicker/AttachmentPickerItem.tsx

@@ -32,8 +32,8 @@ type AttachmentPickerItemType = {
 };
 
 /**
- * Where this cell's asset sits among the composer's attachments, or -1. Selected per cell, so an
- * upload progressing re-renders no cell and a selection change only the cells whose index moved.
+ * Index of this cell's asset among the composer's attachments, or -1. Selected per cell, so upload
+ * progress re-renders no cell and a selection change only the cells whose index moved.
  */
 const useSelectedIndex = (isAsset: (attachment: LocalAttachment) => boolean) => {
   const { attachmentManager } = useMessageComposer();
@@ -220,12 +220,8 @@ export const renderAttachmentPickerItem = ({ item }: { item: PhotoContentItemTyp
   if (isIosLimited(item)) {
     return <AttachmentIosLimited />;
   }
-  /**
-   * Expo Media Library - Result of asset type
-   * Native Android - Gives mime type(Eg: image/jpeg, video/mp4, etc.)
-   * Native iOS - Gives `image` or `video`
-   * Expo Android/iOS - Gives `photo` or `video`
-   **/
+  // `type` is a MIME type on native Android (such as `video/mp4`), `image` or `video` on native
+  // iOS, and `photo` or `video` with Expo.
   const isVideoType = item.type?.includes('video');
 
   if (isVideoType) {

package/src/components/AttachmentPicker/components/AttachmentTypePickerButton.tsx

@@ -173,7 +173,7 @@ export const PollPickerButton = () => {
     openPollCreationDialog?.({ sendMessage });
   });
 
-  return !thread && hasCreatePoll && ownCapabilities.sendPoll ? ( // do not allow poll creation in threads
+  return !thread && hasCreatePoll && ownCapabilities.sendPoll ? ( // No polls in threads.
     <AttachmentTypePickerButton
       accessibilityLabelKey='attachmentPicker.typeButton.poll.accessibilityLabel'
       testID='create-poll-touchable'

package/src/components/AutoCompleteInput/AutoCompleteInput.tsx

@@ -62,10 +62,7 @@ type AutoCompleteInputPropsWithContext = TextInputProps &
   Pick<ChannelContextValue, 'channel'> &
   Pick<MessageInputContextValue, 'setInputBoxRef'> &
   Pick<TranslationContextValue, 't'> & {
-    /**
-     * This is currently passed in from MessageComposer to avoid rerenders
-     * that would happen if we put this in the MessageInputContext
-     */
+    /** Passed in by `MessageComposer` rather than read from context, to avoid extra re-renders. */
     cooldownRemainingSeconds?: number;
     TextInputComponent?: TextInputOverrideComponent;
   };
@@ -97,9 +94,8 @@ const commandPlaceHolders: Record<string, string> = {
 const AutoCompleteInputWithContext = (props: AutoCompleteInputPropsWithContext) => {
   const styles = useStyles();
   const {
-    // Destructured purely to keep it out of `...rest`, which is spread onto the TextInput below. It is
-    // no longer read here — the message length limit now comes from resolved composer configuration —
-    // but leaking a whole Channel into native props would be a large, pointless serialization.
+    // Unused: destructured only to keep the channel out of `...rest`, which is spread onto the
+    // TextInput, so it is not serialized into native props.
     channel: _channel,
     cooldownRemainingSeconds,
     setInputBoxRef,
@@ -117,11 +113,8 @@ const AutoCompleteInputWithContext = (props: AutoCompleteInputPropsWithContext)
     configStateSelector,
   );
 
-  // RN's onChangeText doesn't carry cursor info, and iOS / Android fire
-  // onChangeText vs onSelectionChange in different orders. Rather than derive
-  // the caret from a text-length delta (fragile — gets clobbered by re-renders
-  // and varies across platforms), we hold the latest values reported by native
-  // and call into the LLC once both have settled.
+  // `onChangeText` carries no cursor info and iOS and Android fire it and `onSelectionChange` in
+  // different orders, so the latest text and selection are held in refs and forwarded together.
   const latestTextRef = useRef('');
   const latestSelectionRef = useRef<{ end: number; start: number }>({
     end: 0,
@@ -137,8 +130,7 @@ const AutoCompleteInputWithContext = (props: AutoCompleteInputPropsWithContext)
     });
   }, [textComposer]);
 
-  // Defer to the next task so onChangeText and onSelectionChange both land
-  // before we forward to the LLC, regardless of platform ordering.
+  // Deferred a task so both `onChangeText` and `onSelectionChange` land first, whatever the order.
   const scheduleChange = useCallback(() => {
     if (flushHandleRef.current !== null) return;
     flushHandleRef.current = setTimeout(flushChange, 0);
@@ -153,9 +145,8 @@ const AutoCompleteInputWithContext = (props: AutoCompleteInputPropsWithContext)
     };
   }, []);
 
-  // The composer's resolved limit, not the raw `max_message_length` server flag. The LLC treats the
-  // channel type's value as an *upper bound* on `text.maxLengthOnSend`, so this is the tighter of the
-  // server's cap and anything registered through `client.config`, and it is reactive.
+  // The composer's resolved limit rather than the raw `max_message_length` channel flag: the flag
+  // is an upper bound on `text.maxLengthOnSend`, which also reflects `client.config`.
   const maxMessageLength = maxLengthOnSend;
 
   const numberOfLines = useMemo(() => {
@@ -164,10 +155,9 @@ const AutoCompleteInputWithContext = (props: AutoCompleteInputPropsWithContext)
 
   useEffect(() => {
     setLocalText(text);
-    // Only resync the refs when the text change came from outside (clear after
-    // send, draft restore, programmatic setText). For changes we triggered
-    // ourselves, latestTextRef is already up to date and overwriting the
-    // selection would clobber what onSelectionChange just told us.
+    // Resync the refs only for changes from outside (clear after send, draft restore, `setText`).
+    // Our own changes already updated `latestTextRef`, and resetting the selection would discard
+    // what `onSelectionChange` just reported.
     if (text !== latestTextRef.current) {
       latestTextRef.current = text;
       latestSelectionRef.current = { end: text.length, start: text.length };
@@ -178,13 +168,9 @@ const AutoCompleteInputWithContext = (props: AutoCompleteInputPropsWithContext)
 
   const clearState = useCallback(() => {
     setLocalText('');
-    // iOS UITextView caches its intrinsicContentSize while focused, so a
-    // controlled `value` change to '' after a multiline send doesn't shrink
-    // the input back to single line height and UIKit keeps rendering at the
-    // previously cached focused size until blur. Not particularly sure which
-    // RN version regressed this, but 0.85.3 for sure has the bug. Forcebly
-    // setting its native prop forces UITextView to reconcile its content size
-    // and update accordingly.
+    // iOS `UITextView` caches its intrinsic content size while focused, so clearing `value` after a
+    // multiline send keeps the tall size until blur (seen on RN 0.85.3). Setting the native prop
+    // forces it to recompute.
     if (Platform.OS === 'ios') {
       nativeInputRef.current?.setNativeProps({ text: '' });
     }
@@ -347,11 +333,11 @@ const useStyles = () => {
         color: semantics.inputTextDefault,
         flex: 1,
         fontSize: 16,
-        includeFontPadding: false, // for android vertical text centering
+        includeFontPadding: false, // Android vertical text centering
         lineHeight: 20,
         paddingLeft: 16,
         paddingVertical: 12,
-        textAlignVertical: 'center', // for android vertical text centering
+        textAlignVertical: 'center', // Android vertical text centering
         alignSelf: 'center',
       },
     });

package/src/components/AutoCompleteInput/AutoCompleteSuggestionItem.tsx

@@ -24,10 +24,8 @@ export type AutoCompleteSuggestionItemProps = {
 };
 
 /**
- * Default `@`-trigger row dispatcher. Routes a `MentionSuggestion` to the
- * per type component. Each per type component is its own export and can be
- * composed by integrators who override this dispatcher via
- * `ComponentsContext.MentionSuggestionItem`.
+ * Default `@`-trigger row dispatcher that renders a `MentionSuggestion` with the component for its
+ * mention type. Replaceable through `ComponentsContext.MentionSuggestionItem`.
  */
 export const MentionSuggestionItem = (item: MentionSuggestion) => {
   switch (item.mentionType) {
@@ -116,9 +114,8 @@ const SuggestionItem = ({
   item: TextComposerSuggestion;
   triggerType?: string;
 }) => {
-  // Resolve via context so integrators can swap the mention dispatcher alone
-  // (e.g. to render a custom @channel row) without re-implementing the
-  // emoji/command branches of AutoCompleteSuggestionItem.
+  // Read from context so the mention row can be replaced without touching the emoji and command
+  // rows.
   const { MentionSuggestionItem } = useComponentsContext();
   switch (triggerType) {
     case 'mention':

package/src/components/AutoCompleteInput/AutoCompleteSuggestionList.tsx

@@ -77,9 +77,7 @@ export const AutoCompleteSuggestionList = () => {
 
   const loadMore = useStableCallback(() => suggestions?.searchSource.search());
 
-  // Polite announcement when the suggestion list appears. Different label per
-  // trigger type so the user knows whether they're looking at mentions,
-  // commands, or emoji without having to swipe in to find out.
+  // Polite announcement when the list appears, with a label per trigger type.
   const announceLabelKey =
     triggerType === 'command'
       ? 'autoCompleteInput.suggestions.commandsAvailable.accessibilityLabel'

package/src/components/AutoCompleteInput/mentionItems/EnhancedMentionContent.tsx

@@ -11,8 +11,7 @@ export type EnhancedMentionContentProps = {
 };
 
 /**
- * Title + optional subtitle pair used by every non-user mention row
- * (channel / here / role / user_group). Override styling via
+ * Title and optional subtitle of a non-user mention row. Styled through
  * `theme.messageComposer.suggestions.mention.enhancedMention{Container,Title,Subtitle}`.
  */
 export const EnhancedMentionContent = ({

package/src/components/AutoCompleteInput/mentionItems/EnhancedMentionIcon.tsx

@@ -6,26 +6,16 @@ import type { IconProps } from '../../../icons/utils/base';
 import { primitives } from '../../../theme';
 
 export type EnhancedMentionIconProps = {
-  /**
-   * Any icon component from `package/src/icons` (or a custom one matching the
-   * same `IconProps` shape). The wrapper standardizes size + color and wraps
-   * the icon in a circular chip — per-type mention items don't have to know
-   * about any of that.
-   */
+  /** Icon component, rendered at half the chip size inside a circular chip. */
   Icon: React.ComponentType<IconProps>;
-  /**
-   * Icon size in px. Defaults to 16. The surrounding chip scales with this.
-   */
+  /** Chip diameter in px. Defaults to 32. */
   size?: IconProps['size'];
-  /**
-   * Stroke / fill color. Defaults to `semantics.textSecondary`.
-   */
+  /** Icon fill color. Defaults to `semantics.textPrimary`. */
   color?: IconProps['pathFill'];
 };
 
 /**
- * Universal wrapper for non-user mention-row icons. Renders the supplied
- * `Icon` inside a circular chip. Override chip styling via
+ * Circular chip around the icon of a non-user mention row. Styled through
  * `theme.messageComposer.suggestions.mention.enhancedMentionIcon`.
  */
 export const EnhancedMentionIcon = ({ color, Icon, size = 32 }: EnhancedMentionIconProps) => {

package/src/components/AutoCompleteInput/mentionItems/MentionBroadcastItem.tsx

@@ -13,9 +13,7 @@ export type MentionBroadcastItemProps = {
   entity: ChannelMentionSuggestion | HereMentionSuggestion;
 };
 
-// @channel and @here are literal SDK command keywords (matching mentioned_channel
-// and mentioned_here on the wire). The title is not localized; only the
-// description below it is.
+// `@channel` and `@here` are literal keywords, so only the description is localized.
 const TITLE = { channel: '@channel', here: '@here' } as const;
 const SUBTITLE_KEY = {
   channel: 'autoCompleteInput.mention.channel.description',

package/src/components/AutoCompleteInput/mentionItems/MentionItem.tsx

@@ -5,19 +5,14 @@ import { useTheme } from '../../../contexts/themeContext/ThemeContext';
 import { primitives } from '../../../theme';
 
 export type MentionItemProps = PropsWithChildren<{
-  /**
-   * Leading visual rendered to the left of the row. UserAvatar for user
-   * mentions, an `EnhancedMentionIcon` for the rest.
-   */
+  /** Visual rendered before the content: a user avatar or an `EnhancedMentionIcon`. */
   leading?: ReactNode;
   testID?: string;
 }>;
 
 /**
- * Layout primitive for every mention-suggestion row: `[leading | content]`.
- * The per-type content (tokenized user name, or `EnhancedMentionContent` for
- * channel/here/role/user_group) is passed as children. Container and column
- * styles come from `theme.messageComposer.suggestions.mention`.
+ * Layout of a mention-suggestion row: the `leading` visual followed by the children as content.
+ * Styled through `theme.messageComposer.suggestions.mention`.
  */
 export const MentionItem = ({ children, leading, testID }: MentionItemProps) => {
   const {

package/src/components/AutoCompleteInput/mentionItems/TokenizedSuggestionParts.tsx

@@ -5,15 +5,11 @@ import type { TokenizationPayload } from 'stream-chat';
 
 export type TokenizedSuggestionPartsProps = {
   /**
-   * Token + parts payload produced by the stream-chat-js text composer search
-   * source. When the consumer matches against a display name the source splits
-   * the name into substrings around the matched token; we render each part and
-   * bold whichever part case-insensitively equals the token.
+   * Display name split into parts around the matched token. Parts equal to the token, ignoring
+   * case, are rendered with `matchStyle`.
    */
   tokenizedDisplayName?: TokenizationPayload['tokenizedDisplayName'];
-  /**
-   * Fallback string rendered when the tokenized payload is absent (or empty).
-   */
+  /** Rendered when `tokenizedDisplayName` is absent or has no parts. */
   fallback?: string;
   style?: StyleProp<TextStyle>;
   matchStyle?: StyleProp<TextStyle>;

package/src/components/Channel/Channel.tsx

@@ -24,9 +24,8 @@ export { reactionData } from './ChannelShell';
 
 export type MarkReadFunctionOptions = {
   /**
-   * Signal, whether the message paginator's unread snapshot should be updated.
-   * By default, the local state update is prevented when the Channel component is mounted.
-   * This is in order to keep the UI indicating the original unread state, when the user opens a channel.
+   * Whether the paginator's unread snapshot is reset to the latest message. Defaults to true.
+   * Marking read on mount passes false so the channel keeps showing its original unread state.
    */
   updateChannelUnreadState?: boolean;
 };
@@ -35,23 +34,14 @@ export type ChannelPropsWithContext = Pick<ChannelContextValue, 'channel'> &
   Pick<ChatContextValue, 'client'> &
   Pick<TranslationContextValue, 't'> &
   ChannelConfigProps & {
-    /**
-     * When true, messageList will be scrolled at first unread message, when opened.
-     */
+    /** Scrolls the message list to the first unread message on open. Defaults to false. */
     initialScrollToFirstUnreadMessage?: boolean;
-    /**
-     * Boolean flag to enable/disable marking the channel as read on mount
-     */
+    /** Marks the channel as read on mount. Defaults to true. */
     markReadOnMount?: boolean;
     /**
-     * A boolean signifying whether the Channel component should run channel.watch()
-     * whenever it mounts up a new channel. If set to `false`, it is the integrator's
-     * responsibility to run channel.watch() if they wish to receive WebSocket events
-     * for that channel.
-     *
-     * Can be particularly useful whenever we are viewing channels in a read-only mode
-     * or perhaps want them in an ephemeral state (i.e not created until the first message
-     * is sent).
+     * Whether to call `channel.watch()` when a channel mounts. Defaults to true. When false, call
+     * it yourself to receive WebSocket events, such as for a read-only or ephemeral channel that is
+     * not created until its first message.
      */
     initializeOnMount?: boolean;
   };
@@ -89,8 +79,8 @@ const ChannelWithContext = (props: PropsWithChildren<ChannelPropsWithContext>) =
   });
 
   if (!channel || blockingError) {
-    // Retry re-runs the query that failed. A new failure lands in the paginator's `lastQueryError`,
-    // which is the `error` this indicator renders off — so the warn is all the handling needed.
+    // A failed retry lands in the paginator's `lastQueryError`, which the indicator renders, so
+    // the warning is all the handling needed.
     const retry = () =>
       channel?.messagePaginator
         ?.jumpToTheLatestMessage()
@@ -124,17 +114,15 @@ export type ChannelProps = Partial<Omit<ChannelPropsWithContext, 'channel'>> &
   Pick<ChannelPropsWithContext, 'channel'> & {
     /**
      * The notification host this channel's notifications are routed to. Defaults to the channel's
-     * own host, derived from its cid.
+     * own host, derived from its `cid`.
      */
     notificationHostId?: string;
   };
 
 /**
- *
- * The wrapper component for a chat channel. Channel needs to be placed inside a Chat component
- * to receive the StreamChat client instance. MessageList and MessageComposer must be children of
- * the Channel component to receive the ChannelContext. A thread is rendered by `<Thread>`, next to
- * the channel rather than inside it.
+ * Wrapper component for a chat channel. It must be inside `<Chat>`, and `MessageList` and
+ * `MessageInput` must be its children to receive the channel context. A thread is rendered by
+ * `<Thread>` next to the channel, not inside it.
  *
  * @example ./Channel.md
  */