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

package/src/components/Accessibility/hooks/useIncomingMessageAnnouncements.ts

@@ -39,15 +39,16 @@ export type UseIncomingMessageAnnouncementsParams = {
 };
 
 /**
- * Mirrors stream-chat-react's `useIncomingMessageAnnouncements`:
- *  - 1 message → "New message from {{user}}"
- *  - >1 messages within throttle window → "{{count}} new messages"
- *  - Throttled to one announcement per second
- *  - Bounded `announcedMessageIds` set so a long-running session does not leak.
+ * Announces new messages from other users to screen readers: "New message from {{user}}" for one,
+ * "{{count}} new messages" for several within the one second throttle window.
  *
- * Subscribes to `channel.on('message.new')`. When AccessibilityContext.enabled
- * is false OR `announceNewMessages` is false, the hook is a no-op (no
- * subscription is opened, no listener cost is paid).
+ * Does nothing, and opens no subscription, unless accessibility and `announceNewMessages` are
+ * enabled. Announced message IDs are tracked to skip duplicates and cleared past 500 entries.
+ *
+ * @param params.activeThreadId The open thread, if any. Only its replies are announced; without
+ * it only non-reply messages are.
+ * @param params.channel The channel whose `message.new` events are observed.
+ * @param params.ownUserId The current user's ID. Their own messages are not announced.
  */
 export const useIncomingMessageAnnouncements = ({
   activeThreadId,

package/src/components/Accessibility/useAccessibilityAnnouncer.ts

@@ -17,11 +17,10 @@ export const AccessibilityAnnouncerContext = createContext<
 >(undefined);
 
 /**
- * Returns the imperative announcer. When called outside the AccessibilityProvider's
- * announcer context (which happens any time the SDK's a11y is disabled), this
- * returns a no-op.
+ * Returns the function that announces a message to the screen reader. Outside the announcer
+ * context, as when SDK accessibility is disabled, it is a no-op.
  *
- * Mirrors the React SDK's `useAriaLiveAnnouncer` so cross-SDK code reads the same.
+ * @returns The `announce` function.
  */
 export const useAccessibilityAnnouncer = (): AccessibilityAnnounce => {
   const contextValue = useContext(AccessibilityAnnouncerContext);

package/src/components/Attachment/Attachment.tsx

@@ -43,13 +43,9 @@ export type AttachmentPropsWithContext = Pick<
   'isAttachmentEqual' | 'myMessageTheme' | 'urlPreviewType'
 > &
   Pick<MessageContextValue, 'message'> & {
-    /**
-     * The attachment to render
-     */
+    /** The attachment to render. */
     attachment: AttachmentType;
-    /**
-     * The index of the attachment in the message
-     */
+    /** The index of the attachment in the message. */
     index?: number;
   };
 
@@ -81,7 +77,7 @@ const AttachmentWithContext = (props: AttachmentPropsWithContext) => {
     return <Gallery images={[attachment]} />;
   }
 
-  // The `!attachment.og_scrape_url` is added for cases, where the url preview is not an image but a video.
+  // URL previews (`og_scrape_url`) whose media is a video are excluded.
   if (isVideoAttachment(attachment) && !attachment.og_scrape_url) {
     return isVideoPlayerAvailable() ? (
       <Gallery videos={[attachment]} />
@@ -151,9 +147,7 @@ const MemoizedAttachment = React.memo(
 
 export type AttachmentProps = Partial<AttachmentPropsWithContext>;
 
-/**
- * Attachment - The message attachment
- */
+/** Renders a single message attachment according to its type. */
 export const Attachment = (props: AttachmentProps) => {
   const { attachment } = props;
 

package/src/components/Attachment/AttachmentFileUploadProgressIndicator.tsx

@@ -36,9 +36,7 @@ const formatMegabytesOneDecimal = (bytes: number) => {
   return `${(bytes / (1000 * 1000)).toFixed(1)} MB`;
 };
 
-/**
- * Circular progress plus `uploaded / total` for file and audio attachments during upload.
- */
+/** Circular progress plus `uploaded / total` for file and audio attachments during upload. */
 export const AttachmentFileUploadProgressIndicatorUI = ({
   containerStyle,
   localId,

package/src/components/Attachment/AttachmentUploadIndicator.tsx

@@ -19,7 +19,8 @@ export type AttachmentUploadIndicatorProps = {
 };
 
 /**
- * Upload state for attachment previews: determinate ring when progress is known, otherwise `ActivityIndicator`.
+ * Upload state for attachment previews: a determinate ring when progress is known, otherwise an
+ * `ActivityIndicator`.
  */
 export const AttachmentUploadIndicatorUI = ({
   containerStyle,

package/src/components/Attachment/Audio/AudioAttachment.tsx

@@ -61,14 +61,10 @@ export type AudioAttachmentProps = {
   message?: LocalMessage;
   hideProgressBar?: boolean;
   showTitle?: boolean;
-  /**
-   * If true, the speed settings button will be shown.
-   */
+  /** Shows the speed settings button. Defaults to false. */
   showSpeedSettings?: boolean;
   testID?: string;
-  /**
-   * If true, the audio attachment is in preview mode in the message input.
-   */
+  /** Whether the attachment is shown as a preview in the message input. Defaults to false. */
   isPreview?: boolean;
   containerStyle?: StyleProp<ViewStyle>;
   indicator?: React.ReactNode;
@@ -89,10 +85,7 @@ const audioPlayerSelector = (state: AudioPlayerState) => ({
   progress: state.progress,
 });
 
-/**
- * AudioAttachment
- * UI Component to preview the audio files
- */
+/** Previews and plays audio and voice recording attachments. */
 export const AudioAttachment = (props: AudioAttachmentProps) => {
   const soundRef = React.useRef<SoundReturnType | null>(null);
   const styles = useStyles();
@@ -125,14 +118,14 @@ export const AudioAttachment = (props: AudioAttachmentProps) => {
     audioPlayerSelector,
   );
 
-  // Initialize the player for native cli apps
+  // Initializes the player for native CLI apps.
   useEffect(() => {
     if (soundRef.current) {
       audioPlayer.initPlayer({ playerRef: soundRef.current });
     }
   }, [audioPlayer]);
 
-  // When a audio attachment in preview is removed, we need to remove the player from the pool
+  // A removed preview releases its player from the pool.
   useEffect(
     () => () => {
       if (isPreview) {
@@ -142,22 +135,22 @@ export const AudioAttachment = (props: AudioAttachmentProps) => {
     [audioPlayer, isPreview],
   );
 
-  /** This is for Native CLI Apps */
+  /** Player callback for native CLI apps. */
   const handleLoad = (payload: VideoPayloadData) => {
-    // Voice recordings already carry the canonical duration in the attachment payload.
+    // Voice recordings carry the canonical duration in the attachment payload.
     if (isVoiceRecording) {
       return;
     }
     audioPlayer.duration = payload.duration * ONE_SECOND_IN_MILLISECONDS;
   };
 
-  /** This is for Native CLI Apps */
+  /** Player callback for native CLI apps. */
   const handleProgress = (data: VideoProgressData) => {
     const { currentTime } = data;
     audioPlayer.position = currentTime * ONE_SECOND_IN_MILLISECONDS;
   };
 
-  /** This is for Native CLI Apps */
+  /** Player callback for native CLI apps. */
   const onSeek = (seekResponse: VideoSeekResponse) => {
     audioPlayer.position = seekResponse.currentTime * ONE_SECOND_IN_MILLISECONDS;
   };

package/src/components/Attachment/Audio/PlayPauseButton.tsx

@@ -7,17 +7,11 @@ import { primitives } from '../../../theme';
 import { buttonSizes } from '../../ui/Button/constants';
 
 export type PlayPauseButtonProps = PressableProps & {
-  /**
-   * If true, the button will be playing.
-   */
+  /** Whether the button shows the playing state. */
   isPlaying: boolean;
-  /**
-   * The function to be called when the button is pressed.
-   */
+  /** Called when the button is pressed. */
   onPress: () => void;
-  /**
-   * The style of the container.
-   */
+  /** Style of the container. */
   containerStyle?: StyleProp<ViewStyle>;
 };
 

package/src/components/Attachment/CircularProgressIndicator.tsx

@@ -16,9 +16,9 @@ const SPIN_DURATION_MS = 900;
 const PROGRESS_ANIMATION_DURATION_MS = 1200;
 
 export type CircularProgressIndicatorProps = {
-  /** Upload percent **0–100**. */
   backgroundColor: ColorValue;
   filledColor: ColorValue;
+  /** Upload progress as a percentage from 0 to 100. */
   progress: number;
   unfilledColor: ColorValue;
   size?: number;
@@ -27,9 +27,7 @@ export type CircularProgressIndicatorProps = {
   testID?: string;
 };
 
-/**
- * Circular upload progress ring (determinate) or rotating arc (indeterminate).
- */
+/** Circular upload progress ring (determinate) or rotating arc (indeterminate). */
 export const CircularProgressIndicator = ({
   backgroundColor,
   filledColor,

package/src/components/Attachment/FileAttachment.tsx

@@ -29,7 +29,7 @@ export type FileAttachmentPropsWithContext = Pick<
   'onLongPress' | 'onPress' | 'onPressIn' | 'preventPress'
 > &
   Pick<MessagesContextValue, 'additionalPressableProps'> & {
-    /** The attachment to render */
+    /** The attachment to render. */
     attachment: Attachment;
     attachmentIconSize?: FileIconProps['size'];
     // TODO: Think we really need a way to style the file preview using props if we have theme.

package/src/components/Attachment/FileIcon.tsx

@@ -164,8 +164,7 @@ const audioFileTypes = [
   'audio/vorbis-config',
 ];
 
-// Partially based on:
-// https://stackoverflow.com/a/4212908/2570866
+// Partially based on https://stackoverflow.com/a/4212908/2570866
 
 const docMimeTypes = [
   // Microsoft Word
@@ -181,8 +180,7 @@ const docMimeTypes = [
   'application/vnd.oasis.opendocument.text-template',
   // .fodt
   'application/vnd.oasis.opendocument.text-flat-xml',
-  // .uot
-  // NOTE: firefox doesn't know mimetype so maybe ignore
+  // .uot has no entry: Firefox does not know its MIME type.
 
   // Microsoft Word
   // .docx
@@ -193,14 +191,6 @@ const docMimeTypes = [
   'application/vnd.ms-word.document.macroEnabled.12',
   // .dotm (no test)
   'application/vnd.ms-word.template.macroEnabled.12',
-
-  // LibreOffice/OpenOffice Writer
-  // .odt
-  'application/vnd.oasis.opendocument.text',
-  // .ott
-  'application/vnd.oasis.opendocument.text-template',
-  // .fodt
-  'application/vnd.oasis.opendocument.text-flat-xml',
 ];
 
 const excelMimeTypes = [
@@ -227,23 +217,22 @@ const excelMimeTypes = [
   // .xlam (no test)
   'application/vnd.ms-excel.addin.macroEnabled.12',
   // .xlsb (no test)
-  'application/vnd.ms-excel.addin.macroEnabled.12',
+  'application/vnd.ms-excel.sheet.binary.macroEnabled.12',
 ];
 
 const powerpointMimeTypes = [
-  // Microsoft Word
+  // Microsoft PowerPoint
   // .ppt .pot .pps .ppa (no test for .ppa)
   'application/vnd.ms-powerpoint',
 
-  // LibreOffice/OpenOffice Writer
+  // LibreOffice/OpenOffice Impress
   // .odp
   'application/vnd.oasis.opendocument.presentation',
   // .otp
   'application/vnd.oasis.opendocument.presentation-template',
   // .fodp
   'application/vnd.oasis.opendocument.presentation-flat-xml',
-  // .uop
-  // NOTE: firefox doesn't know mimetype so maybe ignore
+  // .uop has no entry: Firefox does not know its MIME type.
 
   // .pptx
   'application/vnd.openxmlformats-officedocument.presentationml.presentation',
@@ -262,7 +251,7 @@ const powerpointMimeTypes = [
 ];
 
 const zipFileTypes = [
-  // .gzip
+  // .gzip .tar.gz
   'application/gzip',
   // .zip
   'application/zip',
@@ -271,8 +260,6 @@ const zipFileTypes = [
   'application/x-archive',
   // .tar
   'application/x-tar',
-  // .tar.gz
-  'application/gzip',
   // .tar.Z
   'application/x-compress',
   // .tar.bz2
@@ -327,7 +314,6 @@ const videoFileTypes = [
   'video/wmv',
   'video/yuv',
   'video/quicktime',
-  'video/webm',
   'video/x-flv',
 ];
 

package/src/components/Attachment/FilePreview.tsx

@@ -10,7 +10,7 @@ import { primitives } from '../../theme';
 import { getDurationLabelFromDuration, getFileSizeDisplayText } from '../../utils/utils';
 
 export type FilePreviewProps = {
-  /** The attachment to render */
+  /** The attachment to render. */
   attachment: Attachment;
   attachmentIconSize?: FileIconProps['size'];
   // TODO: Think we really need a way to style the file preview using props if we have theme.
@@ -44,8 +44,7 @@ export const FilePreview = (props: FilePreviewProps) => {
     },
   } = useTheme();
 
-  // `duration` is only populated for audio / voice-recording attachments, where it lives under
-  // `custom` (untyped on the base `Attachment`, hence the narrow field read).
+  // `duration` only exists on audio and voice recording attachments, under the untyped `custom`.
   const duration = (attachment.custom as { duration?: number } | undefined)?.duration;
 
   return (

package/src/components/Attachment/Gallery.tsx

@@ -262,11 +262,11 @@ const GalleryThumbnail = ({
     setOverlay('gallery');
   };
   const defaultOnPress = () => {
-    // If the url is defined then only try to open the file.
+    // Only opens when the thumbnail has a URL.
     if (thumbnail.url) {
       if (thumbnail.type === FileTypes.Video && !isVideoPlayerAvailable()) {
-        // This condition is kinda unreachable, since we render videos as file attachment if the video
-        // library is not installed. But doesn't hurt to have extra safeguard, in case of some customizations.
+        // Normally unreachable, since videos render as file attachments without a video library;
+        // kept as a safeguard for customizations.
         openUrlSafely(thumbnail.url);
       } else {
         openImageViewer();
@@ -425,9 +425,7 @@ const areEqual = (prevProps: GalleryPropsWithContext, nextProps: GalleryPropsWit
 };
 const MemoizedGallery = React.memo(GalleryWithContext, areEqual) as typeof GalleryWithContext;
 export type GalleryProps = Partial<GalleryPropsWithContext>;
-/**
- * UI component for card in attachments.
- */
+/** Renders image and video attachments as a grid of thumbnails. */
 export const Gallery = (props: GalleryProps) => {
   const {
     alignment: propAlignment,

package/src/components/Attachment/GalleryImage.tsx

@@ -29,8 +29,8 @@ export const GalleryImageWithContext = (props: GalleryImageWithContextProps) =>
     ...rest
   } = props;
 
-  // Caching image components such as FastImage will not work with local images.
-  // This for the case of local uris, we use the default Image component.
+  // Caching image components such as FastImage do not work with local images, so local URIs use
+  // the default `Image`.
   if (!isLocalUrl(uri)) {
     return (
       <ImageComponent

package/src/components/Attachment/Giphy/Giphy.tsx

@@ -185,9 +185,7 @@ export type GiphyProps = Partial<GiphyPropsWithContext> & {
   attachment: Attachment;
 };
 
-/**
- * UI component for card in attachments.
- */
+/** Renders a Giphy attachment. */
 export const Giphy = (props: GiphyProps) => {
   const { handleAction, isMyMessage, onLongPress, onPress, onPressIn, preventPress } =
     useMessageContext();

package/src/components/Attachment/Giphy/GiphyImage.tsx

@@ -19,9 +19,7 @@ export type GiphyImagePropsWithContext = Pick<MessagesContextValue, 'giphyVersio
   ImageComponent?: React.ComponentType<ImageProps>;
 } & {
   attachment: Attachment;
-  /**
-   * Whether to render the preview image or the full image
-   */
+  /** Whether to render the preview image or the full image. Defaults to false. */
   preview?: boolean;
 };
 
@@ -156,9 +154,7 @@ export type GiphyImageProps = Partial<GiphyImagePropsWithContext> & {
   attachment: Attachment;
 };
 
-/**
- * UI component for card in attachments.
- */
+/** Renders a Giphy image, either the preview or the full image. */
 export const GiphyImage = (props: GiphyImageProps) => {
   const { ImageComponent } = useComponentsContext();
   const { giphyVersion } = useMessagesContext();

package/src/components/Attachment/ImageLoadingFailedIndicator.tsx

@@ -7,10 +7,7 @@ import { useStableCallback } from '../../hooks';
 import { RetryBadge } from '../ui/Badge/RetryBadge';
 
 export type ImageLoadingFailedIndicatorProps = ViewProps & {
-  /**
-   * Callback to reload the image
-   * @returns Callback to reload the image
-   */
+  /** Called to reload the image. */
   onReloadImage: () => void;
 };
 

package/src/components/Attachment/MediaUploadProgressOverlay.tsx

@@ -11,9 +11,7 @@ export type MediaUploadProgressOverlayProps = {
   testID?: string;
 };
 
-/**
- * Full-cover upload overlay for image and video thumbnails.
- */
+/** Full-cover upload overlay for image and video thumbnails. */
 export const MediaUploadProgressOverlay = ({
   progress,
   size = 18,

package/src/components/Attachment/UnsupportedAttachment.tsx

@@ -15,7 +15,7 @@ import { useTranslationContext } from '../../contexts/translationContext/Transla
 import { primitives } from '../../theme';
 
 export type UnsupportedAttachmentProps = Partial<Pick<MessageContextValue, 'isMyMessage'>> & {
-  /** The attachment to render */
+  /** The attachment to render. */
   attachment: Attachment;
   attachmentIconSize?: FileIconProps['size'];
 };

package/src/components/Attachment/UrlPreview/URLPreview.tsx

@@ -205,9 +205,7 @@ export type URLPreviewProps = Partial<URLPreviewPropsWithContext> & {
   attachment: Attachment;
 };
 
-/**
- * UI component for card in attachments.
- */
+/** Renders a URL preview card for a scraped link attachment. */
 export const URLPreview = (props: URLPreviewProps) => {
   const { ImageComponent } = useComponentsContext();
   const { message, onLongPress, onPress, onPressIn, preventPress } = useMessageContext();
@@ -215,7 +213,7 @@ export const URLPreview = (props: URLPreviewProps) => {
 
   return (
     <MemoizedURLPreview
-      key={`${message?.id}${message?.updated_at}`} // press listeners must change on message update, updating key ensures this
+      key={`${message?.id}${message?.updated_at}`} // remounts on update to refresh press listeners
       {...{
         additionalPressableProps,
         channelId: message.cid,

package/src/components/Attachment/UrlPreview/URLPreviewCompact.tsx

@@ -203,9 +203,7 @@ export type URLPreviewCompactProps = Partial<URLPreviewCompactPropsWithContext>
   attachment: Attachment;
 };
 
-/**
- * UI component for card in attachments.
- */
+/** Renders a compact URL preview for a scraped link attachment. */
 export const URLPreviewCompact = (props: URLPreviewCompactProps) => {
   const { ImageComponent } = useComponentsContext();
   const { message, onLongPress, onPress, onPressIn, preventPress } = useMessageContext();
@@ -213,7 +211,7 @@ export const URLPreviewCompact = (props: URLPreviewCompactProps) => {
 
   return (
     <MemoizedURLPreviewCompact
-      key={`${message?.id}${message?.updated_at}`} // press listeners must change on message update, updating key ensures this
+      key={`${message?.id}${message?.updated_at}`} // remounts on update to refresh press listeners
       {...{
         additionalPressableProps,
         channelId: message.cid,

package/src/components/Attachment/VideoThumbnail.tsx

@@ -21,9 +21,7 @@ const styles = StyleSheet.create({
 
 export type VideoThumbnailProps = {
   imageStyle?: StyleProp<ImageStyle>;
-  /**
-   * When set, upload state is read from `client.uploadManager` for this pending attachment id.
-   */
+  /** ID of a pending attachment whose upload state is read from `client.uploadManager`. */
   localId?: string;
   style?: StyleProp<ViewStyle>;
   thumb_url?: string;

package/src/components/Attachment/__tests__/FileIcon.test.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import { Text } from 'react-native';
+
+import { render, screen } from '@testing-library/react-native';
+
+import { WithComponents } from '../../../contexts/componentsContext/ComponentsContext';
+import { ThemeProvider } from '../../../contexts/themeContext/ThemeContext';
+import { defaultTheme } from '../../../contexts/themeContext/utils/theme';
+import { FileIcon } from '../FileIcon';
+
+const renderFileIcon = (mimeType: string) =>
+  render(
+    <WithComponents
+      overrides={{
+        icons: {
+          DOC: () => <Text>doc</Text>,
+          OtherFileIcon: () => <Text>other</Text>,
+          SpreadSheet: () => <Text>spreadsheet</Text>,
+        },
+      }}
+    >
+      <ThemeProvider theme={defaultTheme}>
+        <FileIcon mimeType={mimeType} />
+      </ThemeProvider>
+    </WithComponents>,
+  );
+
+describe('FileIcon', () => {
+  it.each([
+    ['application/vnd.ms-excel.addin.macroEnabled.12'],
+    ['application/vnd.ms-excel.sheet.binary.macroEnabled.12'],
+  ])('shows the spreadsheet icon for %s', (mimeType) => {
+    renderFileIcon(mimeType);
+    expect(screen.getByText('spreadsheet')).toBeTruthy();
+  });
+
+  it('shows the document icon for an OpenDocument text', () => {
+    renderFileIcon('application/vnd.oasis.opendocument.text');
+    expect(screen.getByText('doc')).toBeTruthy();
+  });
+
+  it('falls back to the generic icon for an unknown type', () => {
+    renderFileIcon('application/x-unknown');
+    expect(screen.getByText('other')).toBeTruthy();
+  });
+});

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

@@ -14,20 +14,14 @@ import {
 } from '../../../../contexts/chatConfigContext/ChatConfigContext';
 
 /**
- * Builds and returns a gallery of optimized images to be rendered on UI.
- * This function take a object parameter with following properties:
+ * Builds the gallery layout for image attachments, with a dedicated layout for one, two and three
+ * images. Four or more use a 2x2 grid of the first four.
  *
- * @param {Attachment[]} images - Array of image attachments
- * @param {GallerySizeConfig} sizeConfig - Theme config for the gallery
- *
- * The returned object contains following properties:
- *
- * - height {number[]} - Height of the gallery
- * - width {number[]} - Width of the gallery
- * - thumbnailGrid {number[][]} - Grid of thumbnail images
- * - invertedDirections {boolean} - Whether to invert the direction of the grid. By default grid is rendered with column as primary direction and row as secondary direction.
- *
- * @return {GallerySizeAndThumbnailGrid}
+ * @param params.images Image attachments to lay out.
+ * @param params.resizableCDNHosts CDN hosts whose image URLs can be resized. Defaults to the chat
+ * config default.
+ * @param params.sizeConfig Size limits of the gallery.
+ * @returns The gallery size, its thumbnails and the `invertedDirections` it was built with.
  */
 export function buildGallery({
   images,
@@ -61,15 +55,7 @@ export function buildGallery({
     });
   }
 
-  /**
-   * -----------
-   * |    |    |
-   * |    |    |
-   * -----------
-   * |    |    |
-   * |    |    |
-   * -----------
-   */
+  // Four or more images: a 2x2 grid of the first four.
   return buildThumbnailGrid({
     grid: [
       [1, 1],

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

@@ -8,14 +8,6 @@ import { ChatConfigContextValue } from '../../../../contexts/chatConfigContext/C
 
 import { getAspectRatio } from '../getAspectRatio';
 
-/**
- * Bound a number to a range.
- * @param number The number to bound.
- * @param min The minimum value.
- * @param max The maximum value.
- *
- * @returns The bounded number.
- */
 function clamp(number: number, min: number, max: number) {
   return Math.min(Math.max(number, min), max);
 }