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

package/src/contexts/themeContext/utils/theme.ts

@@ -25,7 +25,6 @@ export const Colors = {
   bg_user: '#F7F7F8',
   black: '#000000',
   blue_alice: '#E9F2FF',
-  // border: '#00000014', // 14 = 8% opacity; top: x=0, y=-1; bottom: x=0, y=1
   code_block: '#DDDDDD',
   disabled: '#B4BBBA',
   grey: '#7A7A7A',
@@ -1210,7 +1209,7 @@ export type Theme = {
     thumb: ViewStyle;
     waveform: ViewStyle;
   };
-  semantics: typeof lightSemantics; // themed semantics have the same type
+  semantics: typeof lightSemantics;
 };
 
 export const defaultTheme: Theme = {
@@ -1874,7 +1873,7 @@ export const defaultTheme: Theme = {
       container: {},
       spacer: {
         height: BASE_AVATAR_SIZE,
-        width: BASE_AVATAR_SIZE, // same as BASE_AVATAR_SIZE
+        width: BASE_AVATAR_SIZE,
       },
     },
     card: {

package/src/contexts/threadContext/ThreadContext.tsx

@@ -9,16 +9,11 @@ export type AlsoSentToChannelHeaderPressPayload = {
 
 export type ThreadContextValue = {
   allowThreadMessagesInChannel: boolean;
-  /**
-   * The thread this subtree renders. Set by `<Thread>`; `undefined` everywhere else.
-   */
+  /** The thread this subtree renders. Set by `<Thread>`, `undefined` elsewhere. */
   thread?: Thread;
 };
 
-/**
- * What `useThreadContext()` returns outside a `<Thread>`. Only `<Thread>` provides this context, so
- * its absence is how a component knows it is not rendering a thread.
- */
+/** What `useThreadContext()` returns outside a `<Thread>`, the only provider of this context. */
 const NO_THREAD_CONTEXT_VALUE: ThreadContextValue = {
   allowThreadMessagesInChannel: false,
   thread: undefined,
@@ -34,7 +29,7 @@ export const ThreadProvider = ({
 }>) => <ThreadContext.Provider value={value}>{children}</ThreadContext.Provider>;
 
 /**
- * The thread the calling component renders, if any. Unlike the other context hooks this one does not
- * throw outside its provider: outside a `<Thread>` it returns `{ thread: undefined }`.
+ * The thread the calling component renders, if any. Unlike the other context hooks it does not
+ * throw outside its provider: it returns `{ thread: undefined }`.
  */
 export const useThreadContext = () => useContext(ThreadContext);

package/src/contexts/translationContext/TranslationContext.tsx

@@ -9,13 +9,9 @@ export const DEFAULT_USER_LANGUAGE = 'en';
 
 export type TranslationContextValue = TranslatorFunctions & {
   /**
-   * The language the SDK's own copy renders in.
-   *
-   * Plain `string`, not `stream-chat`'s `TranslationLanguage`. That union enumerates the languages
-   * the *message auto-translation* endpoint supports, which is a different question from which
-   * languages this SDK's UI can be translated into — any language an integrator registers a
-   * dictionary for is valid here. It also does not contain `pt-BR`, which this SDK itself shipped
-   * a locale for.
+   * The language the SDK's own copy renders in. A plain `string` rather than `stream-chat`'s
+   * `TranslationLanguage` (the message auto-translation languages): any language with a registered
+   * dictionary is valid.
    */
   userLanguage: string;
 };

package/src/contexts/translationContext/types.ts

@@ -1,23 +1,14 @@
 import type { StreamTFunction } from '../../i18n/types';
 
-/**
- * The date/time parser types come from `@stream-io/i18n`, shared with the React SDK.
- *
- * They used to be declared here, and `TDateTimeParserOutput` referenced `Moment` from
- * `moment-timezone` — a *devDependency*, so the type leaked into the published `.d.ts` and failed to
- * resolve for any consumer who had not separately installed it. Core's structural `DateTimeLike`
- * covers a Dayjs or a Moment without depending on either.
- */
+/** The date/time parser types come from `@stream-io/i18n`, shared with the React SDK. */
 export type { TDateTimeParser, TDateTimeParserInput, TDateTimeParserOutput } from '@stream-io/i18n';
 
 export type TranslatorFunctions = {
   /**
-   * The SDK's translation function.
-   *
-   * Typed as {@link StreamTFunction} rather than i18next's `TFunction`, so a key is checked against
-   * the generated catalog and prose call sites are required to pass their English copy inline. The
-   * typing is deliberately local: installing it through i18next's `CustomTypeOptions` would be
-   * global and would force an integrator's own unrelated `t()` calls to satisfy our key union.
+   * The SDK's translation function. Typed as {@link StreamTFunction} so keys are checked against
+   * the generated catalog and prose call sites pass their English copy inline. The typing is local,
+   * not installed through i18next's `CustomTypeOptions`, which would constrain an app's own `t()`
+   * calls.
    */
   t: StreamTFunction;
   tDateTimeParser: import('@stream-io/i18n').TDateTimeParser;

package/src/hooks/__tests__/useAttachmentPickerBottomSheet.test.ts

@@ -0,0 +1,27 @@
+import { renderHook } from '@testing-library/react-native';
+
+import { useAttachmentPickerBottomSheet } from '../useAttachmentPickerBottomSheet';
+
+describe('useAttachmentPickerBottomSheet', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('opens the sheet at its first snap point', () => {
+    const snapToIndex = jest.fn();
+    const { result } = renderHook(() => useAttachmentPickerBottomSheet());
+
+    result.current.openPicker({ current: { snapToIndex } as never });
+
+    expect(snapToIndex).toHaveBeenCalledWith(0);
+  });
+
+  it('warns that the sheet cannot open when the ref has no snapToIndex', () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    const { result } = renderHook(() => useAttachmentPickerBottomSheet());
+
+    result.current.openPicker({ current: null });
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('snapToIndex'));
+  });
+});

package/src/hooks/__tests__/useRAFCoalescedValue.test.tsx

@@ -0,0 +1,80 @@
+import { act, renderHook } from '@testing-library/react-native';
+
+import { useRAFCoalescedValue } from '../useRAFCoalescedValue';
+
+describe('useRAFCoalescedValue', () => {
+  let frames: FrameRequestCallback[];
+
+  beforeEach(() => {
+    frames = [];
+    jest.spyOn(global, 'requestAnimationFrame').mockImplementation((callback) => {
+      frames.push(callback);
+      return frames.length;
+    });
+    jest.spyOn(global, 'cancelAnimationFrame').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  const flushFrame = () =>
+    act(() => {
+      frames.splice(0).forEach((callback) => callback(0));
+    });
+
+  it('publishes the latest value once per frame', () => {
+    const { rerender, result } = renderHook(
+      ({ value }: { value: string }) => useRAFCoalescedValue(value, true),
+      { initialProps: { value: 'a' } },
+    );
+
+    rerender({ value: 'b' });
+    rerender({ value: 'c' });
+    expect(result.current).toBe('a');
+    expect(frames).toHaveLength(1);
+
+    flushFrame();
+    expect(result.current).toBe('c');
+  });
+
+  it('returns the value as is while disabled', () => {
+    const { rerender, result } = renderHook(
+      ({ value }: { value: string }) => useRAFCoalescedValue(value, false),
+      { initialProps: { value: 'a' } },
+    );
+
+    rerender({ value: 'b' });
+    expect(result.current).toBe('b');
+    expect(frames).toHaveLength(0);
+  });
+
+  it('shows the last published value when re-enabled with it', () => {
+    const { rerender, result } = renderHook(
+      ({ isEnabled, value }: { isEnabled: boolean; value: string }) =>
+        useRAFCoalescedValue(value, isEnabled),
+      { initialProps: { isEnabled: true, value: 'a' } },
+    );
+
+    rerender({ isEnabled: true, value: 'b' });
+    flushFrame();
+    rerender({ isEnabled: false, value: 'c' });
+    rerender({ isEnabled: true, value: 'b' });
+
+    expect(result.current).toBe('b');
+  });
+
+  it('publishes a value that changed while disabled once re-enabled', () => {
+    const { rerender, result } = renderHook(
+      ({ isEnabled, value }: { isEnabled: boolean; value: string }) =>
+        useRAFCoalescedValue(value, isEnabled),
+      { initialProps: { isEnabled: true, value: 'a' } },
+    );
+
+    rerender({ isEnabled: false, value: 'b' });
+    rerender({ isEnabled: true, value: 'b' });
+    flushFrame();
+
+    expect(result.current).toBe('b');
+  });
+});

package/src/hooks/actions/__tests__/useChannelActions.test.tsx

@@ -273,7 +273,7 @@ describe('useChannelActions', () => {
       await result.current.addMembers(['u-1', 'u-2']);
     });
 
-    expect(channel.addMembers).toHaveBeenCalledWith(['u-1', 'u-2']);
+    expect(channel.addMembers).toHaveBeenCalledWith({ members: ['u-1', 'u-2'] });
     expect(client.notifications.add).toHaveBeenCalledWith({
       message: '{{count}} members added',
       options: {
@@ -326,7 +326,7 @@ describe('useChannelActions', () => {
       await result.current.addMembers(['u-1'], { onSuccess });
     });
 
-    expect(channel.addMembers).toHaveBeenCalledWith(['u-1']);
+    expect(channel.addMembers).toHaveBeenCalledWith({ members: ['u-1'] });
     expect(onSuccess).toHaveBeenCalledTimes(1);
   });
 
@@ -357,7 +357,7 @@ describe('useChannelActions', () => {
       await result.current.removeMembers(['u-1', 'u-2']);
     });
 
-    expect(channel.removeMembers).toHaveBeenCalledWith(['u-1', 'u-2']);
+    expect(channel.removeMembers).toHaveBeenCalledWith({ members: ['u-1', 'u-2'] });
     expect(client.notifications.add).toHaveBeenCalledWith({
       message: '{{count}} members removed',
       options: {

package/src/hooks/actions/useChannelActionItems.tsx

@@ -22,10 +22,8 @@ import { useChannelMembershipState } from '../useChannelMembershipState';
 import { useIsDirectChat } from '../useIsDirectChat';
 import { useStateStore } from '../useStateStore';
 
-// Lazily resolved to avoid a static import cycle with defaultComponents.ts
-// (defaultComponents → ChannelDetails*/ChannelPreview* → this file). Statically
-// importing defaultIcons corrupts module-init order; require it at call time
-// instead. Same pattern as ComponentsContext's getDefaults().
+// Required lazily: a static import of defaultComponents.ts would form a cycle
+// (defaultComponents -> ChannelDetails*/ChannelPreview* -> this file) and corrupt init order.
 let cachedDefaultIcons: IconsMap | undefined;
 const getDefaultIcons = (): IconsMap => {
   if (!cachedDefaultIcons) {
@@ -40,37 +38,22 @@ export type ChannelActionItem = ActionItem<
   'mute' | 'muteUser' | 'block' | 'leave' | 'deleteChannel' | 'pin' | string
 > & {
   /**
-   * Per item routing **within a channel preview interaction** (swipe row vs
-   * the sheet that opens from it). Only meaningful when the items are consumed
-   * from `<ChannelSwipableWrapper>`:
-   *
-   * - `'swipe'`: shown only in the swipe-row chips.
-   * - `'sheet'`: shown only in the swipe-triggered options sheet.
-   * - `'both'`: shown in both swipe row and sheet.
-   *
-   * The standalone Channel Details screen does **not** filter by `placement` -
-   * use {@link ChannelActionSurface} (`surface`) instead to vary items between
-   * the channel list and the Channel Details screen.
+   * Where the item shows in a channel preview: `'swipe'` (swipe-row chips only), `'sheet'` (the
+   * options sheet opened from the swipe row only) or `'both'`. Only `<ChannelSwipableWrapper>`
+   * reads it; the Channel Details screen does not, so use `surface` to vary items there.
    */
   placement: 'both' | 'sheet' | 'swipe';
 };
 
 /**
- * Identifies which top level UI surface is requesting channel action items.
- * Passed verbatim into {@link ChannelActionItemsParams} so the default builder
- * and any integrator supplied `getChannelActionItems` can branch on it - i.e.
- * to drop or relabel an item on a specific surface or to provide an entirely
- * different builder per surface.
+ * The UI surface requesting channel action items, passed through to `getChannelActionItems` so it
+ * can drop or relabel items per surface.
  *
- * - `'list'`: anything driven by a ChannelList interaction, the swipe row
- *   chips on a channel preview and the bottom sheet that opens from them.
- *   Subrouting between the swipe row and the sheet is handled by the per item
- *   {@link ChannelActionItem.placement} field.
- * - `'details'`: items for the standalone Channel Details screen.
+ * - `'list'`: ChannelList interactions, the swipe row of a channel preview and its options sheet
+ *   (routed between the two by {@link ChannelActionItem.placement}).
+ * - `'details'`: the standalone Channel Details screen.
  *
- * `surface` operates at the call site level (which UI is asking). It is
- * optional and when omitted, the default builder applies no surface specific
- * filtering and returns every item it would otherwise produce.
+ * When omitted, the default builder applies no surface filtering.
  */
 export type ChannelActionSurface = 'list' | 'details';
 

package/src/hooks/actions/useChannelActions.ts

@@ -174,7 +174,7 @@ export const useChannelActions = (channel: Channel) => {
     }
     if (ownUserId) {
       try {
-        await channel.removeMembers([ownUserId]);
+        await channel.removeMembers({ members: [ownUserId] });
         addNotification({
           message: t('channel.left.text', 'Left channel'),
           options: { severity: 'success', type: 'api:channel:leave:success' },
@@ -202,7 +202,7 @@ export const useChannelActions = (channel: Channel) => {
         return;
       }
       try {
-        await channel.removeMembers(memberIds);
+        await channel.removeMembers({ members: memberIds });
         addNotification({
           message: t('channel.membersRemoved.text', {
             count: memberIds.length,
@@ -234,7 +234,7 @@ export const useChannelActions = (channel: Channel) => {
         return;
       }
       try {
-        await channel.addMembers(memberIds);
+        await channel.addMembers({ members: memberIds });
         addNotification({
           message: t('channel.membersAdded.text', {
             count: memberIds.length,

package/src/hooks/actions/useChannelMemberActionItems.tsx

@@ -16,10 +16,8 @@ import { IconProps } from '../../icons';
 import { useChannelOwnCapabilities } from '../useChannelOwnCapabilities';
 import { useStateStore } from '../useStateStore';
 
-// Lazily resolved to avoid a static import cycle with defaultComponents.ts
-// (defaultComponents → ChannelDetails*/ChannelPreview* → this file). Statically
-// importing defaultIcons corrupts module-init order; require it at call time
-// instead. Same pattern as ComponentsContext's getDefaults().
+// Required lazily: a static import of defaultComponents.ts would form a cycle
+// (defaultComponents -> ChannelDetails*/ChannelPreview* -> this file) and corrupt init order.
 let cachedDefaultIcons: IconsMap | undefined;
 const getDefaultIcons = (): IconsMap => {
   if (!cachedDefaultIcons) {
@@ -81,8 +79,7 @@ export const buildDefaultChannelMemberActionItems: BuildDefaultChannelMemberActi
 
   const actionItems: ChannelMemberActionItem[] = [];
 
-  // Muting or blocking yourself is meaningless, so these actions are only
-  // added for other members.
+  // Muting or blocking yourself is meaningless, so these actions are only for other members.
   if (!isCurrentUser) {
     actionItems.push(
       {

package/src/hooks/messagePreview/useGroupedAttachments.ts

@@ -17,15 +17,15 @@ type GroupedAttachments = {
   images: Attachment[];
   videos: Attachment[];
   files: Attachment[];
-  // Narrowed by `isVoiceRecordingAttachment` below so consumers can read `.custom.duration`
-  // without re-asserting the subtype.
+  // Narrowed by `isVoiceRecordingAttachment` so consumers can read `.custom.duration`.
   voiceRecordings: VoiceRecordingAttachment[];
 };
 
 /**
- * Hook to group attachments by type.
- * @param {Attachment[]} attachments
- * @returns {GroupedAttachments}
+ * Groups attachments by type. Attachments matching no group are dropped.
+ *
+ * @param attachments The attachments to group.
+ * @returns The attachments per type.
  */
 export const useGroupedAttachments = (attachments?: Attachment[]) => {
   return useMemo<GroupedAttachments>(() => {

package/src/hooks/messagePreview/useMessageDeliveryStatus.ts

@@ -20,9 +20,7 @@ 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;
 };
@@ -31,11 +29,14 @@ const hasOtherUser = (users: UserResponse[] | undefined, currentUserId: string |
   !!users && (users.length > 1 || (users.length === 1 && users[0].id !== currentUserId));
 
 /**
- * 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.
+ *
+ * @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,

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;