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

package/src/hooks/messagePreview/useMessageDeliveryStatus.ts

@@ -5,7 +5,7 @@ import {
   LocalMessage,
   MessageReceiptsSnapshot,
   MessageResponse,
-  UserResponse,
+  MsgRef,
 } from 'stream-chat';
 
 import { useChatContext } from '../../contexts/chatContext/ChatContext';
@@ -20,22 +20,29 @@ export enum MessageDeliveryStatus {
 
 type MessageDeliveryStatusProps = {
   channel: Channel;
-  // Only `created_at`/`id`/`user` are read here (never the LocalMessage-only `status`), so a
-  // plain `MessageResponse` is accepted too — lets callers pass the channel's last message
-  // without asserting it is a `LocalMessage`.
+  // Only `created_at`, `id` and `user` are read, so a plain `MessageResponse` is accepted too.
   lastMessage: LocalMessage | MessageResponse;
   isReadEventsEnabled: boolean;
 };
 
-const hasOtherUser = (users: UserResponse[] | undefined, currentUserId: string | undefined) =>
-  !!users && (users.length > 1 || (users.length === 1 && users[0].id !== currentUserId));
+/** Whether a cursor has reached a message created at `createdAt`, even from a later message. */
+const hasCursorReached = (createdAt: number | undefined, cursor: MsgRef | null) =>
+  !!cursor && typeof createdAt === 'number' && Number.isFinite(createdAt)
+    ? createdAt <= cursor.timestamp
+    : false;
 
 /**
- * Delivery/read status of the last own message, sourced reactively from the channel's
- * `messageReceiptsTracker.snapshotStore` (`readersByMessageId` / `deliveredByMessageId`) — the same
- * store the in-list read/delivered receipt hooks use. Replaces the previous manual
- * `channel.on('message.new'/'message.delivered'/'message.read')` + `useState` machinery so there is
- * a single reactive source of truth for receipts.
+ * Delivery and read status of the last message when it is the current user's, derived from the
+ * channel's `messageReceiptsTracker.snapshotStore`, the same store the in-list receipt hooks use.
+ *
+ * It compares the message against `lastReadRefByOthers` and `lastDeliveredRefByOthers`, the furthest
+ * points anyone else has reached, so a message stays read once another member reads past it.
+ *
+ * @param params.channel The channel the message belongs to.
+ * @param params.lastMessage The channel's last message.
+ * @param params.isReadEventsEnabled When false, the status is `NOT_SENT_BY_CURRENT_USER`. Defaults
+ * to true.
+ * @returns An object with the `status`, `undefined` when the message is not the current user's.
  */
 export const useMessageDeliveryStatus = ({
   channel,
@@ -43,15 +50,15 @@ export const useMessageDeliveryStatus = ({
   isReadEventsEnabled = true,
 }: MessageDeliveryStatusProps) => {
   const { client } = useChatContext();
-  const messageId = lastMessage?.id ?? '';
   const currentUserId = client.user?.id;
+  const createdAt = lastMessage?.created_at;
 
   const selector = useCallback(
     (snapshot: MessageReceiptsSnapshot) => ({
-      isDelivered: hasOtherUser(snapshot.deliveredByMessageId[messageId], currentUserId),
-      isRead: hasOtherUser(snapshot.readersByMessageId[messageId], currentUserId),
+      isDelivered: hasCursorReached(createdAt, snapshot.lastDeliveredRefByOthers),
+      isRead: hasCursorReached(createdAt, snapshot.lastReadRefByOthers),
     }),
-    [currentUserId, messageId],
+    [createdAt],
   );
 
   const { isDelivered, isRead } = useStateStore(

package/src/hooks/messagePreview/useMessagePreviewText.tsx

@@ -48,10 +48,8 @@ export const useMessagePreviewText = ({
   }
 
   if (message?.shared_location) {
-    // Draft messages type `shared_location` loosely, hence the cast. The RESPONSE shape, not the
-    // request one: the value here came off a message, so `end_at` is the wire number rather than
-    // the `Date` an outgoing request would carry. `end_at` is optional because a static location
-    // has no expiry — only a live one does.
+    // Draft messages type `shared_location` loosely, hence the cast to the response shape, where
+    // `end_at` is a number. It is optional: only a live location expires.
     const { end_at: endAt } = message.shared_location as SharedLocationResponseData;
     if (endAt != null && endAt > nowNs()) {
       return t('messagePreview.liveLocation.label', 'Live Location');

package/src/hooks/useAfterKeyboardOpenCallback.ts

@@ -6,18 +6,18 @@ import { useStableCallback } from './useStableCallback';
 import { useMessageInputContext } from '../contexts/messageInputContext/MessageInputContext';
 
 /**
- * A utility hook that returns a stable callback which focuses the message input
- * and invokes the callback once the keyboard is open.
+ * Returns a stable callback that focuses the message input and runs `callback` once the keyboard is
+ * open.
  *
- * @param callback - callback we want to run once the keyboard is ready
- * @returns A stable callback that will wait for the keyboard to be open before executing.
+ * @param callback Runs once the keyboard is open.
+ * @returns A stable callback that waits for the keyboard before running `callback`.
  */
 export const useAfterKeyboardOpenCallback = <T extends unknown[]>(
   callback: (...args: T) => void,
 ) => {
   const { inputBoxRef } = useMessageInputContext();
   const keyboardSubscriptionRef = useRef<EventSubscription | undefined>(undefined);
-  // This callback runs from a keyboard event listener, so it must stay fresh across rerenders.
+  // Runs from a keyboard event listener, so it must read the latest callback across re-renders.
   const stableCallback = useStableCallback(callback);
 
   /** Clears the pending keyboard listener, if any. */

package/src/hooks/useAppStateListener.ts

@@ -2,24 +2,23 @@ import { useEffect, useRef } from 'react';
 import { AppState, AppStateStatus } from 'react-native';
 
 export const useAppStateListener = (onForeground?: () => void, onBackground?: () => void) => {
-  // React Native 0.87 widened `AppState.currentState` to `string | null | undefined` (it was
-  // `AppStateStatus` up to 0.86). Normalise once here so the comparisons below stay total on
-  // every supported version.
+  // `AppState.currentState` is `string | null | undefined` from React Native 0.87 and
+  // `AppStateStatus` before. Normalized so the comparison holds on every supported version.
   const isBackgroundedRef = useRef(
     ((AppState.currentState as AppStateStatus | null | undefined) ?? 'unknown') === 'background',
   );
   const onForegroundRef = useRef(onForeground);
   const onBackgroundRef = useRef(onBackground);
 
-  // setting refs to avoid passing the functions as dependencies to useEffect
+  // Refs keep the handlers out of the effect's dependencies.
   onForegroundRef.current = onForeground;
   onBackgroundRef.current = onBackground;
 
   useEffect(() => {
     const handleAppStateChange = (nextAppState: AppStateStatus) => {
-      // Only `background` is backgrounded. `inactive` is visible-but-unfocused, and from iOS 27 an
-      // app in Split View stays `inactive` the whole time it is side by side. Transitions pass
-      // through `inactive` in both directions, so ignoring it still observes both.
+      // Only `background` counts as backgrounded. `inactive` is visible-but-unfocused, and from
+      // iOS 27 an app in Split View stays `inactive` the whole time it is side by side. Transitions
+      // pass through `inactive` in both directions, so ignoring it still observes both.
       if (nextAppState === 'background') {
         if (!isBackgroundedRef.current) {
           isBackgroundedRef.current = true;
@@ -36,8 +35,7 @@ export const useAppStateListener = (onForeground?: () => void, onBackground?: ()
     const subscription = AppState.addEventListener('change', handleAppStateChange);
 
     return () => {
-      // Following if-else logic is to support RN >= 0.65 and RN < 0.65 versions.
-      // https://github.com/react-native-community/releases/blob/master/CHANGELOG.md#:~:text=EventEmitter%23removeSubscription%20is%20now%20deprecated.%20(cb6cbd12f8%20by%20%40yungsters)
+      // React Native < 0.65 has no `subscription.remove`; fall back to `removeEventListener`.
       if (subscription?.remove) {
         subscription.remove();
       } else {

package/src/hooks/useAttachmentPickerBottomSheet.ts

@@ -4,11 +4,10 @@ import BottomSheet from '@gorhom/bottom-sheet';
 import { BottomSheetMethods } from '@gorhom/bottom-sheet/lib/typescript/types';
 
 /**
- * This hook is used to manage the state of the attachment picker bottom sheet.
- * It provides functions to open and close the bottom sheet, as well as a reference to the bottom sheet itself.
- * The bottom sheet is used to display the attachment picker UI.
- * The `openPicker` function opens the bottom sheet, and the `closePicker` function closes it.
- * The `bottomSheetRef` is a reference to the bottom sheet component, which allows for programmatic control of the bottom sheet.
+ * Manages the attachment picker bottom sheet: a ref to the sheet plus `openPicker` and
+ * `closePicker`, which open or close the sheet behind the ref they are given.
+ *
+ * @returns The `bottomSheetRef`, `openPicker` and `closePicker`.
  */
 export const useAttachmentPickerBottomSheet = () => {
   const bottomSheetRef = useRef<BottomSheet>(null);
@@ -17,7 +16,9 @@ export const useAttachmentPickerBottomSheet = () => {
     if (ref.current?.snapToIndex) {
       ref.current.snapToIndex(0);
     } else {
-      console.warn('bottom and top insets must be set for the image picker to work correctly');
+      console.warn(
+        'The attachment picker cannot open: its bottom sheet ref has no snapToIndex. Make sure the attachment picker is mounted.',
+      );
     }
   }, []);
 

package/src/hooks/useAudioPlayer.ts

@@ -8,16 +8,9 @@ import { AudioPlayerErrorCode, AudioPlayerOptions } from '../state-store/audio-p
 
 export type UseAudioPlayerProps = {
   /**
-   * Identifier of the entity that requested the audio playback, e.g. message ID.
-   * Asset to specific audio player is a many-to-many relationship
-   * - one URL can be associated with multiple UI elements,
-   * - one UI element can display multiple audio sources.
-   * Therefore, the AudioPlayer ID is a combination of request:src.
-   *
-   * The requester string can take into consideration whether there are multiple instances of
-   * the same URL requested by the same requester (message has multiple attachments with the same asset URL).
-   * In reality the fact that one message has multiple attachments with the same asset URL
-   * could be considered a bad practice or a bug.
+   * Identifier of the entity that requested the playback, such as a message ID. It scopes the
+   * audio player ID (`requester:src:id`), as one URL can back several UI elements and one UI
+   * element can show several sources.
    */
   requester?: string;
 } & Partial<AudioPlayerOptions>;

package/src/hooks/useCanAddMembersToChannel.ts

@@ -4,6 +4,9 @@ import { useChannelOwnCapabilities } from './useChannelOwnCapabilities';
 
 /**
  * Whether the current user can add members to the channel.
+ *
+ * @param channel The channel to check.
+ * @returns True when the user has the `update-channel-members` capability.
  */
 export const useCanAddMembersToChannel = (channel?: Channel) =>
   useChannelOwnCapabilities(channel)?.includes('update-channel-members') ?? false;

package/src/hooks/useCanEditChannel.ts

@@ -3,7 +3,10 @@ import type { Channel } from 'stream-chat';
 import { useChannelOwnCapabilities } from './useChannelOwnCapabilities';
 
 /**
- * Whether the current user can update (edit) the channel.
+ * Whether the current user can update the channel.
+ *
+ * @param channel The channel to check.
+ * @returns True when the user has the `update-channel` capability.
  */
 export const useCanEditChannel = (channel?: Channel) =>
   useChannelOwnCapabilities(channel)?.includes('update-channel') ?? false;

package/src/hooks/useChannel.ts

@@ -4,12 +4,11 @@ import { useChannelContext } from '../contexts/channelContext/ChannelContext';
 import { useThreadContext } from '../contexts/threadContext/ThreadContext';
 
 /**
- * Resolves the active `Channel` instance: the thread's channel when rendered inside a
- * thread, otherwise the `ChannelContext` channel.
+ * Resolves the active channel: the thread's channel inside a `<Thread>`, otherwise the
+ * `ChannelContext` channel. Prefer it over `useChannelContext()` in code shared between the main
+ * list and a thread.
  *
- * Thread-aware analogue of stream-chat-react's `useChannel()`. Prefer this over reading
- * `channel` from `useChannelContext()` directly in message/thread interaction code, so the
- * same code path targets the correct channel in both the main list and a thread.
+ * @returns The active channel.
  */
 export const useChannel = (): Channel => {
   const { channel } = useChannelContext();

package/src/hooks/useChannelImage.ts

@@ -7,9 +7,13 @@ const selector = (state: { data: Channel['data'] }) => ({
 });
 
 /**
- * Returns the channel's image, sourced reactively from `channel.state` (updates on `channel.updated`).
+ * Returns the channel's image, read reactively from `channel.state` (updates on `channel.updated`).
+ *
+ * @param channel The channel to read from.
+ * @returns The channel image.
  */
 export function useChannelImage(channel: Channel): string | undefined;
+/** Same as above, for a channel that may be undefined. */
 export function useChannelImage(channel?: Channel): string | undefined;
 export function useChannelImage(channel?: Channel) {
   return useStateStore(channel?.state, selector)?.image;

package/src/hooks/useChannelMemberCount.ts

@@ -7,10 +7,14 @@ const selector = (state: { memberCount: number }) => ({
 });
 
 /**
- * Returns the channel's member count, sourced reactively from `channel.state` (updates on
+ * Returns the channel's member count, read reactively from `channel.state` (updates on
  * `channel.updated`).
+ *
+ * @param channel The channel to read from.
+ * @returns The member count.
  */
 export function useChannelMemberCount(channel: Channel): number;
+/** Same as above, for a channel that may be undefined. */
 export function useChannelMemberCount(channel?: Channel): number | undefined;
 export function useChannelMemberCount(channel?: Channel) {
   return useStateStore(channel?.state, selector)?.memberCount;

package/src/hooks/useChannelMembershipState.ts

@@ -7,10 +7,14 @@ const selector = (state: { membership: ChannelMemberResponse }) => ({
 });
 
 /**
- * Returns the current user's membership for the channel, sourced reactively from `channel.state`
+ * Returns the current user's membership for the channel, read reactively from `channel.state`
  * (updates on `member.added`/`member.updated`).
+ *
+ * @param channel The channel to read from.
+ * @returns The current user's membership.
  */
 export function useChannelMembershipState(channel: Channel): ChannelMemberResponse;
+/** Same as above, for a channel that may be undefined. */
 export function useChannelMembershipState(channel?: Channel): ChannelMemberResponse | undefined;
 export function useChannelMembershipState(channel?: Channel) {
   return useStateStore(channel?.state, selector)?.membership;

package/src/hooks/useChannelName.ts

@@ -7,9 +7,13 @@ const selector = (state: { data: Channel['data'] }) => ({
 });
 
 /**
- * Returns the channel's name, sourced reactively from `channel.state` (updates on `channel.updated`).
+ * Returns the channel's name, read reactively from `channel.state` (updates on `channel.updated`).
+ *
+ * @param channel The channel to read from.
+ * @returns The channel name.
  */
 export function useChannelName(channel: Channel): string | undefined;
+/** Same as above, for a channel that may be undefined. */
 export function useChannelName(channel?: Channel): string | undefined;
 export function useChannelName(channel?: Channel) {
   return useStateStore(channel?.state, selector)?.name;

package/src/hooks/useChannelOwnCapabilities.ts

@@ -7,8 +7,10 @@ const selector = (state: { ownCapabilities: string[] }) => ({
 });
 
 /**
- * Returns the current user's capabilities for the channel, sourced reactively from
- * `channel.state`.
+ * Returns the current user's capabilities for the channel, read reactively from `channel.state`.
+ *
+ * @param channel The channel to read from.
+ * @returns The own capabilities.
  */
 export function useChannelOwnCapabilities(channel?: Channel): string[] | undefined {
   return useStateStore(channel?.state, selector)?.ownCapabilities;

package/src/hooks/useClientNotifications.ts

@@ -9,9 +9,9 @@ const selector = (state: NotificationManagerState) => ({
 });
 
 /**
- * This hook is used to get the notifications from the client.
- * @returns {Object} - An object containing the notifications.
- * @returns {Notification[]} notifications - The notifications.
+ * Returns the notifications held by the client's notification manager.
+ *
+ * @returns An object with the `notifications`.
  */
 export const useClientNotifications = () => {
   const { client } = useChatContext();

package/src/hooks/useHorizontalInsets.ts

@@ -5,24 +5,18 @@ import { useSafeAreaInsets } from 'react-native-safe-area-context';
 /**
  * Horizontal safe area padding for a surface that spans the full window width.
  *
- * **Only for surfaces an integrator cannot wrap.** Everything the SDK renders in-tree is left
- * alone: the integrator wraps their screen in a `SafeAreaView` and the whole subtree - including
- * absolutely positioned children, which track their containing block's border box - narrows with
- * it. Applying this to an in-tree surface double-pads it for every integrator who already wraps.
+ * Only for surfaces an integrator cannot wrap, such as React Native's `Modal`, which renders in a
+ * separate native window. In-tree surfaces already narrow with the integrator's `SafeAreaView`, so
+ * this would double-pad them; a bottom sheet or overlay qualifies only if it mounts outside that
+ * tree. Prefer a `SafeAreaView` where one fits (see `ImageGalleryHeader`): it compares the window
+ * inset with its own frame, whereas this hook reads the window-global `useSafeAreaInsets` and has
+ * no such protection when nested.
  *
- * In practice that leaves React Native's own `Modal`, which renders in a separate native window.
- * A bottom sheet or an overlay is *not* automatically out of reach - check where it actually
- * mounts. Prefer a `SafeAreaView` (see `ImageGalleryHeader`/`Footer`) wherever one fits: it
- * compares the window inset against its own measured frame, so a nested instance contributes
- * nothing once an ancestor has narrowed the subtree. This hook reads `useSafeAreaInsets`, which is
- * window-global and has no such protection.
+ * `left` and `right` stay separate because from iOS 27 the system can stack its controls down a
+ * single edge (measured 0 and 84 on iPhone Duo). A side whose inset is 0 is omitted, as a
+ * `paddingLeft: 0` longhand would override a `padding` shorthand set elsewhere.
  *
- * `left` and `right` are never collapsed into one value: from iOS 27 the system stacks its controls
- * down a single edge, so the two differ (measured 0 and 84 on iPhone Duo).
- *
- * A side whose inset is 0 is omitted rather than emitted as `paddingLeft: 0`, because a longhand
- * overrides a `padding` shorthand for that side - emitting a zero would silently drop padding the
- * component or a consumer's theme had already set.
+ * @returns A style with `paddingLeft` and `paddingRight` for the non-zero insets.
  */
 export const useHorizontalInsets = (): ViewStyle => {
   const { left, right } = useSafeAreaInsets();

package/src/hooks/useIsChannelMember.ts

@@ -5,7 +5,11 @@ import type { Channel } from 'stream-chat';
 import { useChannelMembersState } from '../components/ChannelList/hooks/useChannelMembersState';
 
 /**
- * Determines whether the user with the given id is already a member of the channel.
+ * Whether the user with the given ID is a member of the channel.
+ *
+ * @param channel The channel to check.
+ * @param userId The ID of the user. Without it the result is false.
+ * @returns True when the user is a member.
  */
 export const useIsChannelMember = (channel: Channel, userId?: string) => {
   const members = useChannelMembersState(channel);

package/src/hooks/useIsDirectChat.ts

@@ -9,7 +9,7 @@ const pickId = (member: ChannelMemberResponse) => ({ id: member.user?.id });
 
 export const useIsDirectChat = (channel?: Channel) => {
   const { client } = useChatContext();
-  const ownUserId = client.userID;
+  const ownUserId = client.userId;
   const members = useChannelMembersState(channel, pickId);
 
   const otherMembers = useMemo(

package/src/hooks/useIsMountedRef.ts

@@ -1,8 +1,7 @@
 import { useEffect, useRef } from 'react';
 
 /**
- * Returns mount status of component. This hook can be used for purpose of avoiding any
- * setState calls (within async operation) after component gets unmounted.
+ * Returns a ref that turns false once the component unmounts, to skip state updates in async work.
  *
  * @example
  * ```
@@ -10,19 +9,16 @@ import { useEffect, useRef } from 'react';
  * const [dummyValue, setDummyValue] = useState(false);
  *
  * useEffect(() => {
- *  someAsyncOperation().then(() => {
- *    if (isMounted.current) setDummyValue(true);
- *  })
- * })
+ *   someAsyncOperation().then(() => {
+ *     if (isMounted.current) setDummyValue(true);
+ *   });
+ * }, []);
  * ```
  *
- * @returns isMounted {Object} Mount status ref for the component.
+ * @returns A ref whose `current` is true until the component unmounts.
  */
 export const useIsMountedRef = () => {
-  // Initial value has been set to true, since this hook exist only for sole purpose of
-  // avoiding any setState calls (within async operation) after component gets unmounted.
-  // Basically we don't need to know about state change from component being initialized -> mounted.
-  // We only need a state change from initialized or mounted state -> unmounted state.
+  // Starts true: only the transition to unmounted matters, not the one from initialized to mounted.
   const isMounted = useRef(true);
 
   useEffect(

package/src/hooks/useIsSvg.ts

@@ -1,10 +1,11 @@
 import { useMemo } from 'react';
 
 /**
- * Returns true if `uri` points to an SVG (either by `.svg` extension or by
- * `image/svg+xml` data-URI prefix). Exported as a pure function for non-React
- * callers; React components should prefer `useIsSvg` so the check is memoized
- * per URI.
+ * Whether `uri` points to an SVG, by `.svg` extension (ignoring query and fragment) or by
+ * `image/svg+xml` data URI. The non-hook form of `useIsSvg`.
+ *
+ * @param uri The URI to check.
+ * @returns True when the URI is an SVG.
  */
 export const isSvgUri = (uri: string | null | undefined): boolean => {
   if (typeof uri !== 'string' || uri.length === 0) {
@@ -19,10 +20,10 @@ export const isSvgUri = (uri: string | null | undefined): boolean => {
 };
 
 /**
- * Memoized variant of `isSvgUri`. Re-runs the string check only when `uri`
- * actually changes — useful in hot render paths like the gallery where the
- * surrounding component re-renders frequently (animated styles, swipe state)
- * but the URI is stable.
+ * Memoized `isSvgUri`, re-evaluated only when `uri` changes.
+ *
+ * @param uri The URI to check.
+ * @returns True when the URI is an SVG.
  */
 export const useIsSvg = (uri: string | null | undefined): boolean =>
   useMemo(() => isSvgUri(uri), [uri]);

package/src/hooks/useIsTargetedMessage.ts

@@ -6,14 +6,14 @@ import { useStateStore } from './useStateStore';
 type MessageFocusSignalState = { signal: { messageId?: string } | null };
 
 /**
- * Whether this message is the one the list is currently focused on — the target of a
- * `jumpToMessage` / `jumpToTheFirstUnreadMessage`, for the lifetime of the signal's TTL.
+ * Whether the message is the target of the active paginator's `messageFocusSignal` (set by
+ * `jumpToMessage` and `jumpToTheFirstUnreadMessage`, for the signal's TTL).
  *
- * Read per row, off the active paginator's `messageFocusSignal`, rather than from a
- * `highlightedMessageId` on the channel context. Both cost one subscription per row in practice
- * (every row already consumes that context), but a context value that changes on every jump
- * re-renders every row; a boolean scoped to one id re-renders only the row losing the highlight
- * and the row gaining it.
+ * Each row selects its own boolean, so a jump re-renders only the row losing the highlight and the
+ * row gaining it, not every row as a shared context value would.
+ *
+ * @param messageId The ID of the message.
+ * @returns True when the message is the focus target.
  */
 export const useIsTargetedMessage = (messageId: string) => {
   const paginator = useMessagePaginator();

package/src/hooks/useKeyboardVisibility.ts

@@ -2,8 +2,9 @@ import { useEffect, useState } from 'react';
 import { Keyboard, Platform } from 'react-native';
 
 /**
- * A custom hook that provides a boolean value indicating whether the keyboard is visible.
- * @returns A boolean value indicating whether the keyboard is visible.
+ * Tracks whether the keyboard is visible.
+ *
+ * @returns True while the keyboard is visible.
  */
 export const useKeyboardVisibility = () => {
   const [isKeyboardVisible, setIsKeyboardVisible] = useState(false);

package/src/hooks/useLazyRef.ts

@@ -1,8 +1,10 @@
 import { type RefObject, useRef } from 'react';
 
 /**
- * Creates a stable ref whose initial value is computed only once.
- * Use this when the initial ref value is expensive or allocates an object.
+ * Creates a stable ref whose initial value is computed once, for values that are costly to build.
+ *
+ * @param getInitialValue Computes the initial value on the first render. Must not return `null`.
+ * @returns The ref holding the value.
  */
 export const useLazyRef = <T>(getInitialValue: () => T) => {
   const ref = useRef<T | null>(null);

package/src/hooks/useLoadingImage.tsx

@@ -52,13 +52,13 @@ export const useLoadingImage = () => {
   );
   const isNetworkOnline = useNetworkConnectionState()?.isOnline;
 
-  // storing the value of isLoadingImageError in a ref to avoid passing as a dep to useEffect
+  // A ref keeps `isLoadingImageError` out of the effect's dependencies.
   const hasImageLoadedErroredRef = useRef(isLoadingImageError);
   hasImageLoadedErroredRef.current = isLoadingImageError;
 
   useEffect(() => {
     if (isNetworkOnline && hasImageLoadedErroredRef.current) {
-      // if there was an error previously, reload the image automatically when user comes back online
+      // Retry a failed image automatically when the network comes back.
       onReloadImageRef.current();
     }
   }, [isNetworkOnline]);

package/src/hooks/useMessagePaginator.ts

@@ -2,8 +2,10 @@ import { useChannelContext } from '../contexts/channelContext/ChannelContext';
 import { useThreadContext } from '../contexts/threadContext/ThreadContext';
 
 /**
- * The message paginator this subtree is rendering: the thread's reply list inside a `<Thread>`, the
- * channel's main list otherwise.
+ * The message paginator this subtree renders: the thread's inside a `<Thread>`, otherwise the
+ * channel's.
+ *
+ * @returns The active message paginator.
  */
 export const useMessagePaginator = () => {
   const { channel } = useChannelContext();

package/src/hooks/usePendingAttachmentUpload.ts

@@ -7,11 +7,11 @@ import { useStateStore } from './useStateStore';
 import { useChatContext } from '../contexts/chatContext/ChatContext';
 
 export type PendingAttachmentUpload = {
-  /** True when `client.uploadManager` has an in-flight upload for this attachment local id. */
+  /** Whether `client.uploadManager` has an in-flight upload for this attachment local ID. */
   isUploading: boolean;
   /**
-   * Upload percent **0–100** from `client.uploadManager` (same scale as `attachmentManager`
-   * `onProgress` / `localMetadata.uploadProgress`). `undefined` when not computable or not uploading.
+   * Upload progress from `client.uploadManager` as a percentage from 0 to 100, the same scale as
+   * `localMetadata.uploadProgress`. `undefined` when not uploading or not computable.
    */
   uploadProgress: number | undefined;
 };
@@ -32,7 +32,11 @@ const COMPLETION_READY_PROGRESS = 90;
 const now = () => Date.now();
 
 /**
- * Subscribes to `client.uploadManager` for the pending attachment identified by `localId`.
+ * Subscribes to `client.uploadManager` for the pending attachment identified by `localId`. An
+ * upload that finished after reaching 90% keeps reporting `isUploading` at 100% for 350 ms.
+ *
+ * @param localId The local ID of the attachment. Without it the upload is reported as idle.
+ * @returns The upload state of the attachment.
  */
 export function usePendingAttachmentUpload(localId: string | undefined): PendingAttachmentUpload {
   const { client } = useChatContext();