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

package/src/types/types.ts

@@ -42,13 +42,11 @@ export type UploadAttachmentPreviewProps<A extends LocalUploadAttachment> = {
 };
 
 /**
- * This SDK adds nothing of its own to an attachment's custom data.
+ * The SDK adds nothing of its own to an attachment's custom data.
  *
  * An attachment whose upload has not resolved keeps `localMetadata` (`id`, `file`, `previewUri`)
- * from `stream-chat`'s own composition, which is what the message list joins to the live
- * `uploadManager` record and what the send path needs to upload or retry. The SDK used to smuggle
- * that through `custom.localId` / `custom.originalFile` instead, squatting in data that belongs to
- * the integrator. `mime_type` and `file_size` come from `stream-chat` itself.
+ * from `stream-chat`. The message list joins it to the live `uploadManager` record, and the send
+ * path uses it to upload or retry.
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface DefaultAttachmentData {}
@@ -99,7 +97,6 @@ export type UnknownType = Record<string, unknown>;
 
 export type ValueOf<T> = T[keyof T];
 
-// ASYNC AUDIO EXPO:
 export enum AndroidOutputFormat {
   DEFAULT = 0,
   THREE_GPP = 1,
@@ -169,53 +166,39 @@ export enum IOSAudioQuality {
 }
 
 export type RecordingOptionsAndroid = {
-  /**
-   * The desired audio encoder. See the [`AndroidAudioEncoder`](#androidaudioencoder) enum for all valid values.
-   */
+  /** The desired audio encoder. See the `AndroidAudioEncoder` enum for valid values. */
   audioEncoder: AndroidAudioEncoder | number;
   /**
-   * The desired file extension. Example valid values are `.3gp` and `.m4a`.
-   * For more information, see the [Android docs](https://developer.android.com/guide/topics/media/media-formats)
-   * for supported output formats.
+   * The desired file extension, such as `.3gp` or `.m4a`. See the
+   * [Android docs](https://developer.android.com/guide/topics/media/media-formats) for supported
+   * output formats.
    */
   extension: string;
-  /**
-   * The desired file format. See the [`AndroidOutputFormat`](#androidoutputformat) enum for all valid values.
-   */
+  /** The desired file format. See the `AndroidOutputFormat` enum for valid values. */
   outputFormat: AndroidOutputFormat | number;
   /**
-   * The desired bit rate.
-   *
-   * Note that `prepareToRecordAsync()` may perform additional checks on the parameter to make sure whether the specified
-   * bit rate is applicable, and sometimes the passed bitRate will be clipped internally to ensure the audio recording
-   * can proceed smoothly based on the capabilities of the platform.
+   * The desired bit rate. `prepareToRecordAsync()` may clip it to what the platform supports.
    *
    * @example `128000`
    */
   bitRate?: number;
   /**
-   * The desired maximum file size in bytes, after which the recording will stop (but `stopAndUnloadAsync()` must still
-   * be called after this point).
+   * The maximum file size in bytes, after which the recording stops. `stopAndUnloadAsync()` must
+   * still be called.
    *
    * @example `65536`
    */
   maxFileSize?: number;
   /**
-   * The desired number of channels.
-   *
-   * Note that `prepareToRecordAsync()` may perform additional checks on the parameter to make sure whether the specified
-   * number of audio channels are applicable.
+   * The desired number of channels. `prepareToRecordAsync()` may check that the platform supports
+   * it.
    *
    * @example `1`, `2`
    */
   numberOfChannels?: number;
   /**
-   * The desired sample rate.
-   *
-   * Note that the sampling rate depends on the format for the audio recording, as well as the capabilities of the platform.
-   * For instance, the sampling rate supported by AAC audio coding standard ranges from 8 to 96 kHz,
-   * the sampling rate supported by AMRNB is 8kHz, and the sampling rate supported by AMRWB is 16kHz.
-   * Please consult with the related audio coding standard for the supported audio sampling rate.
+   * The desired sample rate. The supported rates depend on the output format and the platform: AAC
+   * supports 8 to 96 kHz, AMR-NB 8 kHz and AMR-WB 16 kHz.
    *
    * @example 44100
    */
@@ -223,9 +206,7 @@ export type RecordingOptionsAndroid = {
 };
 
 export type RecordingOptionsIOS = {
-  /**
-   * The desired audio quality. See the [`IOSAudioQuality`](#iosaudioquality) enum for all valid values.
-   */
+  /** The desired audio quality. See the `IOSAudioQuality` enum for valid values. */
   audioQuality: IOSAudioQuality | number;
   /**
    * The desired bit rate.
@@ -257,9 +238,7 @@ export type RecordingOptionsIOS = {
    * @example `16`
    */
   bitDepthHint?: number;
-  /**
-   * The desired bit rate strategy. See the next section for an enumeration of all valid values of `bitRateStrategy`.
-   */
+  /** The desired bit rate strategy. */
   bitRateStrategy?: number;
   /**
    * The desired PCM bit depth.
@@ -267,17 +246,11 @@ export type RecordingOptionsIOS = {
    * @example `16`
    */
   linearPCMBitDepth?: number;
-  /**
-   * A boolean describing if the PCM data should be formatted in big endian.
-   */
+  /** Whether the PCM data is formatted in big endian. */
   linearPCMIsBigEndian?: boolean;
-  /**
-   * A boolean describing if the PCM data should be encoded in floating point or integral values.
-   */
+  /** Whether the PCM data is encoded as floating point (true) or integral (false) values. */
   linearPCMIsFloat?: boolean;
-  /**
-   * The desired file format. See the [`IOSOutputFormat`](#iosoutputformat) enum for all valid values.
-   */
+  /** The desired file format. See the `IOSOutputFormat` enum for valid values. */
   outputFormat?: string | IOSOutputFormat | number;
 };
 
@@ -288,66 +261,53 @@ export type RecordingOptionsWeb = {
 };
 
 export type ExpoRecordingOptions = {
-  /**
-   * Recording options for the Android platform.
-   */
+  /** Recording options for Android. */
   android: RecordingOptionsAndroid;
-  /**
-   * Recording options for the iOS platform.
-   */
+  /** Recording options for iOS. */
   ios: RecordingOptionsIOS;
-  /**
-   * Recording options for the Web platform.
-   */
+  /** Recording options for the web. */
   web: RecordingOptionsWeb;
-  /**
-   * A boolean that determines whether audio level information will be part of the status object under the "metering" key.
-   */
+  /** Whether audio level information is included in the status object under the `metering` key. */
   isMeteringEnabled?: boolean;
   /**
-   * A boolean that hints to keep the audio active after `prepareToRecordAsync` completes.
-   * Setting this value can improve the speed at which the recording starts. Only set this value to `true` when you call `startAsync`
-   * immediately after `prepareToRecordAsync`. This value is automatically set when using `Audio.recording.createAsync()`.
+   * Keeps the audio active after `prepareToRecordAsync` completes, which can speed up the start of
+   * the recording. Set it to `true` only when `startAsync` is called immediately afterwards. Set
+   * automatically by `Audio.recording.createAsync()`.
    */
   keepAudioActiveHint?: boolean;
 };
 
 export type AudioMode = {
   /**
-   * A boolean selecting if recording is enabled on iOS.
-   * > When this flag is set to `true`, playback may be routed to the phone earpiece instead of to the speaker. Set it back to `false` after stopping recording to reenable playback through the speaker.
+   * Whether recording is enabled on iOS. While `true`, playback may be routed to the earpiece
+   * instead of the speaker; set it back to `false` after recording to restore speaker playback.
    * @default false
    */
   allowsRecordingIOS: boolean;
-  /**
-   * An enum selecting how your experience's audio should interact with the audio from other apps on Android.
-   */
+  /** How the app's audio interacts with audio from other apps on Android. */
   interruptionModeAndroid: InterruptionModeAndroid;
-  /**
-   * An enum selecting how your experience's audio should interact with the audio from other apps on iOS.
-   */
+  /** How the app's audio interacts with audio from other apps on iOS. */
   interruptionModeIOS: InterruptionModeIOS;
   /**
-   * A boolean selecting if your experience's audio should play in silent mode on iOS.
+   * Whether the app's audio plays in silent mode on iOS.
    * @default false
    */
   playsInSilentModeIOS: boolean;
   /**
-   * A boolean selecting if the audio is routed to earpiece on Android.
+   * Whether the audio is routed to the earpiece on Android.
    * @default false
    */
   playThroughEarpieceAndroid: boolean;
   /**
-   * A boolean selecting if your experience's audio should automatically be lowered in volume ("duck") if audio from another
-   * app interrupts your experience. If `false`, audio from other apps will pause your audio.
+   * Whether the app's audio is lowered in volume ("ducked") when another app plays audio. When
+   * `false`, audio from other apps pauses the app's audio.
    * @default true
    */
   shouldDuckAndroid: boolean;
   /**
-   * A boolean selecting if the audio session (playback or recording) should stay active even when the app goes into background.
-   * > This is not available in Expo Go for iOS, it will only work in standalone apps.
-   * > To enable it for standalone apps, [follow the instructions below](#playing-or-recording-audio-in-background)
-   * > to add `UIBackgroundModes` to your app configuration.
+   * Whether the audio session (playback or recording) stays active while the app is in the
+   * background. Not available in Expo Go for iOS; standalone apps also need `UIBackgroundModes` in
+   * the app configuration.
    * @default false
    */
   staysActiveInBackground: boolean;
@@ -355,28 +315,18 @@ export type AudioMode = {
 
 // @needsAudit
 export enum InterruptionModeIOS {
-  /**
-   * **This is the default option.** If this option is set, your experience's audio is mixed with audio playing in background apps.
-   */
+  /** The app's audio mixes with audio playing in background apps. This is the default. */
   MixWithOthers = 0,
-  /**
-   * If this option is set, your experience's audio interrupts audio from other apps.
-   */
+  /** The app's audio interrupts audio from other apps. */
   DoNotMix = 1,
-  /**
-   * If this option is set, your experience's audio lowers the volume ("ducks") of audio from other apps while your audio plays.
-   */
+  /** The app's audio lowers the volume ("ducks") of other apps' audio while it plays. */
   DuckOthers = 2,
 }
 
 export enum InterruptionModeAndroid {
-  /**
-   * If this option is set, your experience's audio interrupts audio from other apps.
-   */
+  /** The app's audio interrupts audio from other apps. */
   DoNotMix = 1,
-  /**
-   * **This is the default option.** If this option is set, your experience's audio lowers the volume ("ducks") of audio from other apps while your audio plays.
-   */
+  /** The app's audio ducks other apps' audio while it plays. This is the default. */
   DuckOthers = 2,
 }
 
@@ -385,8 +335,6 @@ export type ExpoAudioRecordingConfiguration = {
   options?: Partial<ExpoRecordingOptions>;
 };
 
-// ASYNC AUDIO RN CLI
-
 export enum AudioSourceAndroidType {
   DEFAULT = 0,
   MIC,
@@ -522,9 +470,7 @@ export interface AudioSet {
 
 export type RNCLIRecordingOptions = {
   audioSet?: AudioSet;
-  /**
-   * A boolean that determines whether audio level information will be part of the status object under the "metering" key.
-   */
+  /** Whether audio level information is included in the status object under the `metering` key. */
   isMeteringEnabled?: boolean;
 };
 
@@ -546,8 +492,8 @@ export type EmojiSearchIndex = {
 };
 
 /**
- * Override the file upload request used to upload the channel image.
- * By default the SDK uploads to Stream's CDN via `client.uploadImage`.
+ * Overrides the request that uploads the channel image. Defaults to `client.uploadImage`, which
+ * uploads to Stream's CDN.
  * @param file File object to upload
  */
 export type GlobalFileUploadRequest = (file: File) => Promise<MinimumUploadRequestResult>;

package/src/utils/__tests__/getTrimmedAttachmentTitle.test.ts

@@ -0,0 +1,19 @@
+import { getTrimmedAttachmentTitle } from '../getTrimmedAttachmentTitle';
+
+describe('getTrimmedAttachmentTitle', () => {
+  it('returns an empty string without a title', () => {
+    expect(getTrimmedAttachmentTitle()).toBe('');
+  });
+
+  it('keeps a title that fits', () => {
+    expect(getTrimmedAttachmentTitle('short.pdf')).toBe('short.pdf');
+  });
+
+  it('keeps the head and tail of a long title with the default length', () => {
+    expect(getTrimmedAttachmentTitle('This is a very long title')).toBe('This is a...ong title');
+  });
+
+  it('keeps exactly maxLength characters for an odd maxLength', () => {
+    expect(getTrimmedAttachmentTitle('abcdefghijklmnopqrst', 7)).toBe('abc...qrst');
+  });
+});

package/src/utils/attachmentUrls.ts

@@ -6,14 +6,12 @@ const localFileUri = (attachment: Attachment | LocalAttachment) =>
     : undefined;
 
 /**
- * The URL to play a video from — `asset_url` / `image_url`, or the local file it has yet to be
+ * The URL to play a video from: `asset_url`, `image_url`, or the local file it is yet to be
  * uploaded from.
  *
- * Only videos need this. For them `setupVideoAttachmentPreviewMiddleware` replaces
- * `localMetadata.previewUri` with the thumbnail the picker extracted, so `stream-chat`'s
- * `getAttachmentPreviewUrl` would play the thumbnail. For every other type the LLC's
- * `toLocalUploadAttachment` sets `previewUri` to the picked file's own `uri`, so use
- * `getAttachmentPreviewUrl` there.
+ * Videos only; use `getAttachmentPreviewUrl` for other types. The
+ * `setupVideoAttachmentPreviewMiddleware` sets `localMetadata.previewUri` to the video's
+ * `thumb_url`, so `getAttachmentPreviewUrl` would return the thumbnail, not the video.
  */
 export const getPlayableVideoUrl = (attachment: Attachment | LocalAttachment) =>
   attachment.asset_url ?? attachment.image_url ?? localFileUri(attachment);

package/src/utils/compressImage.ts

@@ -2,19 +2,16 @@ import { NativeHandlers } from '../native';
 import type { File } from '../types/types';
 
 /**
- * Function to compress and Image and return the compressed Image URI
- * @param image
- * @param compressImageQuality
- * @returns string
+ * Compresses an image and returns the URI of the compressed image.
+ *
+ * @param image The image to compress.
+ * @param compressImageQuality Compression quality. Compression is skipped when it is not a number
+ * or is 1.
+ * @returns The compressed image URI, or the original URI when compression is skipped.
  */
 export const compressedImageURI = async (image: File, compressImageQuality?: number) => {
   const uri = image.uri || '';
-  /**
-   * We skip compression if:
-   * - the file is from the camera as that should already be compressed
-   * - the file has no height/width value to maintain for compression
-   * - the compressImageQuality number is not present or is 1 (meaning no compression)
-   */
+  // Compression is skipped without a height or width, and when the quality is not a number or is 1.
   const compressedUri = await (!image.height ||
   !image.width ||
   typeof compressImageQuality !== 'number' ||

package/src/utils/getResizedImageUrl.ts

@@ -13,16 +13,16 @@ export type GetResizedImageUrlParams = Pick<ChatConfigContextValue, 'resizableCD
 };
 
 /**
- * Any file or image upload done through stream's chat SDK or components get uploaded
- * to CloudFront CDN. Following function returns a url of resized image (to given width and height).
- * It can be used to avoid rendering heavy images on UI, for the sake of performance.
+ * Returns the URL of an image resized to the given size, to avoid rendering oversized images.
+ * URLs outside `resizableCDNHosts`, without the `oh` and `ow` query parameters, or when neither
+ * `height` nor `width` is given are returned unchanged.
  *
- * This function accepts an object with following properties:
- * - height: height of the resized image.
- * - url: url of the image.
- * - width: width of the resized image.
- *
- * @returns {string} Url of the image with given height and width.
+ * @param params.url The image URL.
+ * @param params.height Target height in layout units, converted to pixels.
+ * @param params.width Target width in layout units, converted to pixels.
+ * @param params.resize The resize mode. Defaults to 'clip'.
+ * @param params.resizableCDNHosts CDN hosts whose image URLs can be resized.
+ * @returns The resized image URL.
  */
 export function getResizedImageUrl({
   height,
@@ -37,9 +37,7 @@ export function getResizedImageUrl({
     const originalHeight = parsedUrl.searchParams.get('oh');
     const originalWidth = parsedUrl.searchParams.get('ow');
 
-    // If url is not within Stream's cloudfront CDN or any other configured resizableCDNHosts (which offers fast image resizing), then return the url as it is.
-    // Check for oh and ow parameters in the url, is just to differentiate between old and new CDN.
-    // In case of old CDN we don't want to do any kind of resizing.
+    // `oh` and `ow` only appear on the new CDN, which resizes; the old CDN must not be resized.
 
     const isResizableUrl =
       resizableCDNHosts?.some((rCDNh) => url.includes(rCDNh)) && originalHeight && originalWidth;
@@ -60,8 +58,7 @@ export function getResizedImageUrl({
 
     return parsedUrl.toString();
   } catch (error) {
-    // There is some issue with the url.
-    // Simply return the original url, there is no need to break the app for this.
+    // An unparsable URL is returned as is rather than breaking the render.
     console.warn(error);
 
     return url;

package/src/utils/getTrimmedAttachmentTitle.ts

@@ -1,5 +1,6 @@
-// Add dots in between the title if it is too long and then append the remaining last characters.
-// Eg: "This is a very long title" => "This is a very long ti...le"
+// Shortens a title longer than `maxLength` (default 18) to `maxLength` characters, its head and tail
+// joined by an ellipsis: "This is a very long title" => "This is a...ong title". An odd
+// `maxLength` gives the tail the extra character.
 export const getTrimmedAttachmentTitle = (title?: string, maxLength?: number) => {
   const maxLengthValue = maxLength || 18;
   if (!title) return '';
@@ -10,8 +11,10 @@ export const getTrimmedAttachmentTitle = (title?: string, maxLength?: number) =>
     return title;
   }
 
-  const start = title.slice(0, maxLengthValue / 2);
-  const end = title.slice(title.length - maxLengthValue / 2);
+  const headLength = Math.floor(maxLengthValue / 2);
+  const tailLength = maxLengthValue - headLength;
+  const start = title.slice(0, headLength);
+  const end = title.slice(title.length - tailLength);
 
   return `${start}${ellipsis}${end}`;
 };

package/src/utils/getUrlOfImageAttachment.ts

@@ -5,9 +5,11 @@ import { getPlayableVideoUrl } from './attachmentUrls';
 import { FileTypes } from '../types/types';
 
 /**
- * Extract url of image from image attachment.
- * @param image Image attachment
- * @returns {string}
+ * Returns the URL to display for an image attachment.
+ *
+ * @param image The image attachment.
+ * @param giphyVersion The Giphy rendition used for Giphy attachments. Defaults to 'fixed_height'.
+ * @returns The image URL.
  */
 export function getUrlOfImageAttachment(
   image: Attachment,
@@ -17,7 +19,7 @@ export function getUrlOfImageAttachment(
     return image.giphy?.[giphyVersion]?.url || image.thumb_url;
   }
 
-  // Videos open in the player, so resolve the playable file rather than the thumbnail
+  // Videos open in the player, so resolve the playable file rather than the thumbnail.
   if (image.type === FileTypes.Video) {
     return getPlayableVideoUrl(image);
   }

package/src/utils/i18n/Streami18n.ts

@@ -4,8 +4,8 @@ import {
   isDayjsLike,
   Streami18n as CoreStreami18n,
 } from '@stream-io/i18n';
-// The names of the languages the API can auto-translate a message into. Chat API metadata, so it
-// stays in `stream-chat` rather than moving to the generic i18n package.
+// `languageNameDefaults` (the names of the languages the API can auto-translate into) is Chat API
+// metadata, so it comes from `stream-chat` rather than the generic i18n package.
 import type {
   CalendarFormats,
   Streami18nOptions as CoreStreami18nOptions,
@@ -18,17 +18,14 @@ import { runtimeDefaults } from '../../i18n/runtimeDefaults';
 import type { TranslationCatalog } from '../../i18n/types';
 
 /**
- * The English calendar wording the SDK ships, for the dayjs calendar plugin.
+ * The English calendar wording the SDK ships for the dayjs calendar plugin, layered under any
+ * calendar an integrator supplies.
  *
- * Bundled data, the same way `runtimeDefaults` is, and layered the same way: underneath anything an
- * integrator supplies. `timestamp.*` keys formatted with `timestampFormatter(calendar: true)` and no
- * `calendarFormats` argument of their own read this off the active dayjs locale, and nothing else
- * supplies it — no locale file defines `calendar`, and dayjs already has `en` registered, so core's
- * locale fallback never gets a chance to fill it in. Without it the plugin's own defaults apply and a
- * date separator reads "Today at 3:04 PM" where every previous version read "Today".
+ * `timestamp.*` keys formatted with `timestampFormatter(calendar: true)` and no `calendarFormats`
+ * argument read it off the active dayjs locale. No locale file defines `calendar` and dayjs already
+ * has `en` registered, so without it the plugin defaults apply ("Today at 3:04 PM", not "Today").
  *
- * Exported so a new language can be built from it (`{ ...englishCalendarFormats, sameDay: '[heute]' }`)
- * rather than transcribed.
+ * Exported so a new language can extend it: `{ ...englishCalendarFormats, sameDay: '[heute]' }`.
  */
 export const englishCalendarFormats: CalendarFormats = {
   lastDay: '[Yesterday]',
@@ -43,16 +40,11 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null;
 
 /**
- * The calendar slots already registered on dayjs's `en` locale.
+ * The calendar slots already registered on dayjs's `en` locale, so that the
+ * {@link englishCalendarFormats} defaults do not overwrite them. Core's constructor and the app
+ * (`Dayjs.updateLocale('en', { calendar })`) can both register them first.
  *
- * Read back rather than assumed empty, because {@link englishCalendarFormats} is a default and must not
- * overwrite a choice already made. Two things get there before this runs: core applies
- * `dayjsLocaleConfigForLanguage` inside its own constructor, and an app is free to call
- * `Dayjs.updateLocale('en', { calendar })` itself — which the v10 migration guide suggests for anyone
- * bringing their own `DateTimeParser`.
- *
- * Filtered to the six known slots with string values: whatever is in the registry came from outside and
- * is typed `unknown`, and a stray key would be spread straight into a config dayjs then formats with.
+ * Only known slots with string values are returned, because the registry is untyped external data.
  */
 const registeredEnglishCalendar = (parser: DateTimeParserModule): Partial<CalendarFormats> => {
   const registry = 'Ls' in parser ? parser.Ls : undefined;
@@ -68,23 +60,18 @@ const registeredEnglishCalendar = (parser: DateTimeParserModule): Partial<Calend
   return Object.fromEntries(slots);
 };
 
-/**
- * Options for {@link Streami18n}.
- *
- * `runtimeDefaults` is accepted and *merged* over the SDK's own, so supplying it adds to rather than
- * replaces what the SDK ships.
- */
+/** Options for {@link Streami18n}. `runtimeDefaults` is merged over the SDK's own. */
 export type Streami18nOptions = CoreStreami18nOptions<TranslationCatalog>;
 
 /**
- * Wrapper around [i18next](https://www.i18next.com/) for this SDK's translations. Pass an instance to
- * `<Chat i18nInstance={…}>` to control language and copy.
+ * Wrapper around [i18next](https://www.i18next.com/) for this SDK's translations. Pass an instance
+ * to `<Chat i18nInstance={…}>` to control language and copy.
  *
- * The implementation lives in `@stream-io/i18n`, shared with the React SDK, so both behave identically
- * and a fix reaches both at once. What is added here is this SDK's own bundled translation data — core
- * cannot import it, because the key catalog is generated from *this* package's `t()` call sites.
+ * The implementation lives in `@stream-io/i18n`, shared with the React SDK. This class adds the
+ * SDK's bundled translation data, which core cannot import because the key catalog is generated
+ * from this package's `t()` call sites.
  *
- * ## Overriding some of the English copy
+ * Overriding some of the English copy:
  *
  * ```ts
  * const i18n = new Streami18n({
@@ -92,7 +79,7 @@ export type Streami18nOptions = CoreStreami18nOptions<TranslationCatalog>;
  * });
  * ```
  *
- * ## Registering a language
+ * Registering a language:
  *
  * ```ts
  * import 'dayjs/locale/de';
@@ -103,20 +90,18 @@ export type Streami18nOptions = CoreStreami18nOptions<TranslationCatalog>;
  * });
  * ```
  *
- * A partial dictionary is safe: keys you do not supply render their English copy, never a raw dotted
- * path. Note no dayjs locale file defines `calendar` — that field belongs to the calendar plugin — so a
- * new language needs both the locale import and a `calendar` config, or relative dates render English
- * scaffolding around translated day names.
+ * Keys missing from a partial dictionary render their English copy, never a raw dotted path. No
+ * dayjs locale file defines `calendar`, so a new language needs both the locale import and a
+ * `calendar` config, or relative dates mix English with translated day names.
  *
- * Reactivity goes through `i18n.state`, a `StateStore`. `setLanguage()` returns nothing — the new `t` is
- * published to that store, which `<Chat>` subscribes to.
+ * `setLanguage()` resolves with no value: the new `t` is published to `i18n.state`, a `StateStore`
+ * that `<Chat>` subscribes to.
  */
 export class Streami18n extends CoreStreami18n<TranslationCatalog, BundledTranslationKey> {
   constructor(options: Streami18nOptions = {}) {
     super({
       ...options,
-      // Core owns the `language.*` names, since it owns the `TranslationLanguage` union they describe.
-      // Merged under this SDK's data, and the caller's over both, so an individual name stays overridable.
+      // The `language.*` names come from `stream-chat`. Precedence: those, SDK data, the caller.
       runtimeDefaults: {
         ...languageNameDefaults,
         ...runtimeDefaults,
@@ -124,13 +109,12 @@ export class Streami18n extends CoreStreami18n<TranslationCatalog, BundledTransl
       },
     });
 
-    // Scoped to `en`, and only to the slots nothing has claimed. A translated app is untouched: dayjs
-    // reads `calendar` off the active locale and never falls back to another one, so this is reachable
-    // only when English is what was asked for — `language: 'en'`, `disableDateTimeTranslations`, or an
-    // active language whose dayjs locale was never imported, which core warns about separately.
+    // Fills only unclaimed `en` slots. dayjs reads `calendar` off the active locale with no
+    // fallback, so this matters only when English is active (`language: 'en'`,
+    // `disableDateTimeTranslations`, or a language whose dayjs locale was never imported).
     //
-    // On the parser module rather than our own dayjs copy, an integrator-supplied `DateTimeParser` has
-    // its own locale registry, and writing to ours would leave the one that formats the dates without it.
+    // Written to the parser module, not our own dayjs copy: a custom `DateTimeParser` has its own
+    // locale registry, and that is the one that formats the dates.
     if (isDayjsLike(this.DateTimeParser)) {
       addOrUpdateDayjsLocale(
         DEFAULT_LANGUAGE,

package/src/utils/installNativeMultipartAdapter.ts

@@ -260,9 +260,8 @@ const nativeMultipartAxiosAdapter = async (
 const createNativeMultipartAdapter =
   (client: StreamChat): AxiosAdapter =>
   (config) => {
-    // Built from the config the adapter receives, so it reflects everything that ran after routing:
-    // request interceptors registered before this one (axios runs them after it) and
-    // `transformRequest`.
+    // Built from the config the adapter receives, so it includes the changes made by request
+    // interceptors registered before this one (axios runs them after it) and `transformRequest`.
     const nativeMultipartRequest = createNativeMultipartRequest(
       client,
       config as NativeMultipartAxiosRequestConfig,
@@ -280,13 +279,14 @@ const createNativeMultipartAdapter =
   };
 
 /**
- * Routes file uploads through the native uploader by setting `adapter` on those requests only.
+ * Routes multipart file uploads through the native uploader by setting `adapter` on those requests
+ * only. Does nothing when native multipart upload is unavailable or the client is already set up.
  *
- * The client's default adapter is deliberately left alone. Replacing it would mean resolving the
- * fallback (`['xhr', 'http', 'fetch']`) with `axios.getAdapter`, i.e. importing axios here — and
- * wherever that import resolves to a different copy than `stream-chat`'s, every request would fail
- * with that copy's `AxiosError`, which `stream-chat` does not recognise. Untouched, every other
- * request is resolved by `stream-chat`'s own axios.
+ * The client's default adapter is left alone: replacing it would require importing axios here to
+ * resolve the fallback, and a copy different from `stream-chat`'s would fail every request with an
+ * `AxiosError` that `stream-chat` does not recognize.
+ *
+ * @param client The client to install the adapter on.
  */
 export const installNativeMultipartAdapter = (client: StreamChat) => {
   if (!isNativeMultipartUploadAvailable()) {

package/src/utils/isRNVersionGreaterThanOrEqualTo.ts

@@ -1,11 +1,13 @@
 import { Platform } from 'react-native';
 
 /**
- * Returns `true` when the running React Native version is greater than or equal to `version`
- * (a `'major.minor.patch'` string, e.g. `'0.86.0'`), comparing major, then minor, then patch.
+ * Whether the running React Native version is greater than or equal to `version`.
  *
- * Falls back to `false` when the version is unavailable (e.g. react-native-web) — callers should
- * treat that as "assume an older React Native".
+ * Returns `false` when the version is unavailable (such as react-native-web), so callers treat it
+ * as an older React Native.
+ *
+ * @param version A `'major.minor.patch'` string, such as `'0.86.0'`.
+ * @returns Whether the running version is at least `version`.
  */
 export const isRNVersionGreaterThanOrEqualTo = (version: string): boolean => {
   const runtime = Platform.constants?.reactNativeVersion;