stream-chat-react-native-core 9.4.0-beta.11 → 9.4.0-beta.13

package/src/components/ImageGallery/hooks/useCurrentImageHeight.ts

@@ -0,0 +1,86 @@
+import { useEffect } from 'react';
+import { Image } from 'react-native';
+import { SharedValue, useSharedValue } from 'react-native-reanimated';
+
+import type {
+  ImageGalleryAsset,
+  ImageGalleryStateStore,
+} from '../../../state-store/image-gallery-state-store';
+import { FileTypes } from '../../../types/types';
+
+/**
+ * Owns a SharedValue tracking the visible height of the currently selected
+ * gallery asset and keeps it in lockstep with the gallery store's
+ * currentIndex. Worklet consumers read `.value` on the UI thread.
+ *
+ * The store is subscribed via `subscribeWithSelector` (not `useStateStore`),
+ * so currentIndex changes never go through React state so no rerender is
+ * triggered in the calling component. The callback writes directly into the
+ * SharedValue.
+ *
+ * Sync path uses the attachment's intrinsic `original_height`/`original_width`
+ * when present. Async fallback via `Image.getSize` handles assets that don't
+ * carry dimensions; a token guards against the closure-race where the user
+ * swipes past a slide before its dimensions resolve.
+ */
+export const useCurrentImageHeight = ({
+  assets,
+  fullWindowHeight,
+  fullWindowWidth,
+  imageGalleryStateStore,
+}: {
+  assets: ImageGalleryAsset[];
+  fullWindowHeight: number;
+  fullWindowWidth: number;
+  imageGalleryStateStore: ImageGalleryStateStore;
+}): SharedValue<number> => {
+  const currentImageHeight = useSharedValue(fullWindowHeight);
+
+  useEffect(() => {
+    let latestToken = 0;
+
+    const compute = (index: number) => {
+      const currentToken = ++latestToken;
+      const photo = assets[index];
+
+      if (photo?.original_height && photo?.original_width) {
+        const h = Math.floor(photo.original_height * (fullWindowWidth / photo.original_width));
+        currentImageHeight.value = h > fullWindowHeight ? fullWindowHeight : h;
+        return;
+      }
+
+      if (photo?.uri && photo.type === FileTypes.Image) {
+        Image.getSize(
+          photo.uri,
+          (width, height) => {
+            // Stale result, currentIndex moved on before getSize resolved.
+            if (currentToken !== latestToken) return;
+            if (!width || !height) {
+              currentImageHeight.value = fullWindowHeight;
+              return;
+            }
+            const imageHeight = Math.floor(height * (fullWindowWidth / width));
+            currentImageHeight.value =
+              imageHeight > fullWindowHeight ? fullWindowHeight : imageHeight;
+          },
+          () => {
+            if (currentToken !== latestToken) return;
+            currentImageHeight.value = fullWindowHeight;
+          },
+        );
+        return;
+      }
+
+      currentImageHeight.value = fullWindowHeight;
+    };
+
+    compute(imageGalleryStateStore.state.getLatestValue().currentIndex);
+
+    return imageGalleryStateStore.state.subscribeWithSelector(
+      (state) => ({ currentIndex: state.currentIndex }),
+      ({ currentIndex }) => compute(currentIndex),
+    );
+  }, [assets, fullWindowHeight, fullWindowWidth, currentImageHeight, imageGalleryStateStore]);
+
+  return currentImageHeight;
+};

package/src/components/ImageGallery/hooks/useImageGalleryGestures.tsx

@@ -1,4 +1,4 @@
-import { useRef, useState } from 'react';
+import { useRef } from 'react';
 import { Platform } from 'react-native';
 import { Gesture, GestureType } from 'react-native-gesture-handler';
 import {
@@ -14,9 +14,7 @@ import {
 
 import { useImageGalleryContext } from '../../../contexts/imageGalleryContext/ImageGalleryContext';
 import { useOverlayContext } from '../../../contexts/overlayContext/OverlayContext';
-import { useStateStore } from '../../../hooks';
 import { NativeHandlers } from '../../../native';
-import { ImageGalleryState } from '../../../state-store/image-gallery-state-store';
 
 export enum HasPinched {
   FALSE = 0,
@@ -31,10 +29,6 @@ export enum IsSwiping {
 
 const MARGIN = 32;
 
-const imageGallerySelector = (state: ImageGalleryState) => ({
-  currentIndex: state.currentIndex,
-});
-
 export const useImageGalleryGestures = ({
   currentImageHeight,
   halfScreenHeight,
@@ -49,7 +43,7 @@ export const useImageGalleryGestures = ({
   translateY,
   translationX,
 }: {
-  currentImageHeight: number;
+  currentImageHeight: SharedValue<number>;
   halfScreenHeight: number;
   halfScreenWidth: number;
   headerFooterVisible: SharedValue<number>;
@@ -62,20 +56,8 @@ export const useImageGalleryGestures = ({
   translateY: SharedValue<number>;
   translationX: SharedValue<number>;
 }) => {
-  /**
-   * if a specific image index > 0 has been passed in
-   * while creating the hook, set the value of the index
-   * reference to its value.
-   *
-   * This makes it possible to seelct an image in the list,
-   * and scroll/pan as normal. Prior to this,
-   * it was always assumed that one started at index 0 in the
-   * gallery.
-   * */
   const { imageGalleryStateStore } = useImageGalleryContext();
-  const { currentIndex } = useStateStore(imageGalleryStateStore.state, imageGallerySelector);
-
-  const [index, setIndex] = useState(currentIndex);
+  const currentIndexShared = imageGalleryStateStore.currentIndexShared;
 
   /**
    * Gesture handler refs
@@ -163,13 +145,16 @@ export const useImageGalleryGestures = ({
   };
 
   const moveToNextImage = () => {
-    runOnJS(setIndex)(index + 1);
-    imageGalleryStateStore.currentIndex = index + 1;
+    // Read fresh — both moveToNext/Previous are invoked via runOnJS from a
+    // worklet, so we'd otherwise be using a value captured at hook-creation
+    // time. The setter mirrors into currentIndexShared.
+    const currentIndex = imageGalleryStateStore.state.getLatestValue().currentIndex;
+    imageGalleryStateStore.currentIndex = currentIndex + 1;
   };
 
   const moveToPreviousImage = () => {
-    runOnJS(setIndex)(index - 1);
-    imageGalleryStateStore.currentIndex = index - 1;
+    const currentIndex = imageGalleryStateStore.state.getLatestValue().currentIndex;
+    imageGalleryStateStore.currentIndex = currentIndex - 1;
   };
 
   /**
@@ -221,7 +206,7 @@ export const useImageGalleryGestures = ({
          * true, or false and is reset on releasing the touch
          */
         if (isSwiping.value === IsSwiping.UNDETERMINED) {
-          const maxXYRatio = isAndroid ? 1 : 0.25;
+          const maxXYRatio = 0.25;
           if (
             Math.abs(event.translationX / event.translationY) > maxXYRatio &&
             (Math.abs(-halfScreenWidth * (scale.value - 1) - offsetX.value) < 3 ||
@@ -261,16 +246,17 @@ export const useImageGalleryGestures = ({
          * If swiping down start scaling down the image for swipe
          * away effect
          */
+        const imageHeight = currentImageHeight.value;
         scale.value =
-          currentImageHeight * offsetScale.value < screenHeight && translateY.value > 0
+          imageHeight * offsetScale.value < screenHeight && translateY.value > 0
             ? offsetScale.value * (1 - (1 / 3) * (translateY.value / screenHeight))
-            : currentImageHeight * offsetScale.value > screenHeight &&
-                translateY.value > (currentImageHeight / 2) * offsetScale.value - halfScreenHeight
+            : imageHeight * offsetScale.value > screenHeight &&
+                translateY.value > (imageHeight / 2) * offsetScale.value - halfScreenHeight
               ? offsetScale.value *
                 (1 -
                   (1 / 3) *
                     ((translateY.value -
-                      ((currentImageHeight / 2) * offsetScale.value - halfScreenHeight)) /
+                      ((imageHeight / 2) * offsetScale.value - halfScreenHeight)) /
                       screenHeight))
               : scale.value;
 
@@ -287,6 +273,8 @@ export const useImageGalleryGestures = ({
         const finalXPosition = event.translationX - event.velocityX * 0.3;
         const finalYPosition = event.translationY + event.velocityY * 0.1;
 
+        const currentIndex = currentIndexShared.value;
+
         /**
          * If there is a next photo, the image is lined up to the right
          * edge, the swipe is to the left, and the final position is more
@@ -295,7 +283,7 @@ export const useImageGalleryGestures = ({
          * As we move towards the left to move to next image, the translationX value will be negative on X axis.
          */
         if (
-          index < assetsLength - 1 &&
+          currentIndex < assetsLength - 1 &&
           Math.abs(halfScreenWidth * (scale.value - 1) + offsetX.value) < 3 &&
           translateX.value < 0 &&
           finalXPosition > halfScreenWidth &&
@@ -303,7 +291,7 @@ export const useImageGalleryGestures = ({
         ) {
           cancelAnimation(translationX);
           translationX.value = withTiming(
-            -(screenWidth + MARGIN) * (index + 1),
+            -(screenWidth + MARGIN) * (currentIndex + 1),
             {
               duration: 200,
               easing: Easing.out(Easing.ease),
@@ -322,7 +310,7 @@ export const useImageGalleryGestures = ({
            * As we move towards the right to move to previous image, the translationX value will be positive on X axis.
            */
         } else if (
-          index > 0 &&
+          currentIndex > 0 &&
           Math.abs(-halfScreenWidth * (scale.value - 1) + offsetX.value) < 3 &&
           translateX.value > 0 &&
           finalXPosition < -halfScreenWidth &&
@@ -330,7 +318,7 @@ export const useImageGalleryGestures = ({
         ) {
           cancelAnimation(translationX);
           translationX.value = withTiming(
-            -(screenWidth + MARGIN) * (index - 1),
+            -(screenWidth + MARGIN) * (currentIndex - 1),
             {
               duration: 200,
               easing: Easing.out(Easing.ease),
@@ -376,19 +364,20 @@ export const useImageGalleryGestures = ({
          * otherwise use decay with a clamping at the edges to give the effect
          * the image is sliding along using velocity and friction
          */
+        const imageHeight = currentImageHeight.value;
         translateY.value =
-          currentImageHeight * scale.value < screenHeight
+          imageHeight * scale.value < screenHeight
             ? withTiming(0, { reduceMotion: ReduceMotion.Never })
-            : translateY.value > (currentImageHeight / 2) * scale.value - halfScreenHeight
-              ? withTiming((currentImageHeight / 2) * scale.value - halfScreenHeight, {
+            : translateY.value > (imageHeight / 2) * scale.value - halfScreenHeight
+              ? withTiming((imageHeight / 2) * scale.value - halfScreenHeight, {
                   reduceMotion: ReduceMotion.Never,
                 })
-              : translateY.value < (-currentImageHeight / 2) * scale.value + halfScreenHeight
-                ? withTiming((-currentImageHeight / 2) * scale.value + halfScreenHeight)
+              : translateY.value < (-imageHeight / 2) * scale.value + halfScreenHeight
+                ? withTiming((-imageHeight / 2) * scale.value + halfScreenHeight)
                 : withDecay({
                     clamp: [
-                      (-currentImageHeight / 2) * scale.value + halfScreenHeight,
-                      (currentImageHeight / 2) * scale.value - halfScreenHeight,
+                      (-imageHeight / 2) * scale.value + halfScreenHeight,
+                      (imageHeight / 2) * scale.value - halfScreenHeight,
                     ],
                     deceleration: 0.99,
                     velocity: event.velocityY,
@@ -411,7 +400,7 @@ export const useImageGalleryGestures = ({
          */
         if (
           finalYPosition > halfScreenHeight &&
-          offsetY.value + 8 >= (currentImageHeight / 2) * scale.value - halfScreenHeight &&
+          offsetY.value + 8 >= (imageHeight / 2) * scale.value - halfScreenHeight &&
           isSwiping.value !== IsSwiping.TRUE &&
           translateY.value !== 0 &&
           !(
@@ -448,7 +437,7 @@ export const useImageGalleryGestures = ({
               ? withDecay({
                   velocity: event.velocityY,
                 })
-              : withTiming(halfScreenHeight + (currentImageHeight / 2) * scale.value, {
+              : withTiming(halfScreenHeight + (imageHeight / 2) * scale.value, {
                   duration: 200,
                   easing: Easing.out(Easing.ease),
                 });
@@ -662,13 +651,14 @@ export const useImageGalleryGestures = ({
          * edges of the screen return the photo to line up with the edges,
          * otherwise leave the photo in its current position
          */
+        const imageHeight = currentImageHeight.value;
         translateY.value =
-          currentImageHeight * scale.value < screenHeight
+          imageHeight * scale.value < screenHeight
             ? withTiming(0)
-            : translateY.value > (currentImageHeight / 2) * scale.value - screenHeight / 2
-              ? withTiming((currentImageHeight / 2) * scale.value - screenHeight / 2)
-              : translateY.value < (-currentImageHeight / 2) * scale.value + screenHeight / 2
-                ? withTiming((-currentImageHeight / 2) * scale.value + screenHeight / 2)
+            : translateY.value > (imageHeight / 2) * scale.value - screenHeight / 2
+              ? withTiming((imageHeight / 2) * scale.value - screenHeight / 2)
+              : translateY.value < (-imageHeight / 2) * scale.value + screenHeight / 2
+                ? withTiming((-imageHeight / 2) * scale.value + screenHeight / 2)
                 : translateY.value;
 
         /**
@@ -724,11 +714,12 @@ export const useImageGalleryGestures = ({
             duration: 200,
             easing: Easing.out(Easing.ease),
           });
-          if (currentImageHeight * 2 > screenHeight) {
+          const imageHeight = currentImageHeight.value;
+          if (imageHeight * 2 > screenHeight) {
             const translateYTopBottom =
               event.absoluteY > halfScreenHeight
-                ? -(currentImageHeight * 2 - screenHeight) / 2
-                : (currentImageHeight * 2 - screenHeight) / 2;
+                ? -(imageHeight * 2 - screenHeight) / 2
+                : (imageHeight * 2 - screenHeight) / 2;
             translateY.value = withTiming(translateYTopBottom, {
               duration: 200,
               easing: Easing.out(Easing.ease),

package/src/components/UIComponents/EmptyList.tsx

@@ -0,0 +1,80 @@
+import React from 'react';
+import { I18nManager, StyleSheet, Text, View } from 'react-native';
+
+import { useTheme } from '../../contexts/themeContext/ThemeContext';
+import { IconProps } from '../../icons/utils/base';
+import { primitives } from '../../theme';
+
+export type EmptyListProps = {
+  /**
+   * Icon component to render. Its size and color are set by `EmptyList`.
+   */
+  icon: React.ComponentType<IconProps>;
+  /**
+   * Title text shown below the icon.
+   */
+  title: string;
+  /**
+   * Optional supporting text shown below the title.
+   */
+  subtitle?: string;
+};
+
+/**
+ * @experimental This component is experimental and is subject to change.
+ */
+export const EmptyList = ({ icon: Icon, subtitle, title }: EmptyListProps) => {
+  const {
+    theme: {
+      emptyList: { container, subtitle: subtitleStyle, title: titleStyle },
+      semantics,
+    },
+  } = useTheme();
+
+  return (
+    <View style={[styles.container, container]} testID='empty-list'>
+      <Icon stroke={semantics.textTertiary} size={32} />
+      <View style={styles.content}>
+        <Text style={[styles.title, { color: semantics.textPrimary }, titleStyle]}>{title}</Text>
+        {subtitle ? (
+          <Text style={[styles.subtitle, { color: semantics.textSecondary }, subtitleStyle]}>
+            {subtitle}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+};
+
+EmptyList.displayName = 'EmptyList{emptyList}';
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    gap: primitives.spacingSm,
+    height: '100%',
+    justifyContent: 'center',
+    paddingHorizontal: primitives.spacingMd,
+    paddingVertical: primitives.spacing3xl,
+    width: '100%',
+  },
+  content: {
+    alignItems: 'center',
+    gap: primitives.spacingXs,
+    width: '100%',
+  },
+  subtitle: {
+    fontSize: primitives.typographyFontSizeMd,
+    fontWeight: primitives.typographyFontWeightRegular,
+    lineHeight: primitives.typographyLineHeightNormal,
+    textAlign: 'center',
+    writingDirection: I18nManager.isRTL ? 'rtl' : 'ltr',
+  },
+  title: {
+    fontSize: primitives.typographyFontSizeMd,
+    fontWeight: primitives.typographyFontWeightSemiBold,
+    lineHeight: primitives.typographyLineHeightNormal,
+    textAlign: 'center',
+    writingDirection: I18nManager.isRTL ? 'rtl' : 'ltr',
+  },
+});

package/src/components/UIComponents/__tests__/EmptyList.test.tsx

@@ -0,0 +1,90 @@
+import React from 'react';
+
+import { render, screen } from '@testing-library/react-native';
+
+import { ThemeProvider } from '../../../contexts/themeContext/ThemeContext';
+import { defaultTheme } from '../../../contexts/themeContext/utils/theme';
+import { Pin } from '../../../icons/pin';
+import { EmptyList } from '../EmptyList';
+
+type EmptyListProps = React.ComponentProps<typeof EmptyList>;
+
+const renderComponent = (props: Partial<EmptyListProps> = {}) =>
+  render(
+    <ThemeProvider theme={defaultTheme}>
+      <EmptyList icon={Pin} title='No pinned messages' {...props} />
+    </ThemeProvider>,
+  );
+
+describe('EmptyList', () => {
+  it('renders the empty-list testID', () => {
+    renderComponent();
+    expect(screen.getByTestId('empty-list')).toBeTruthy();
+  });
+
+  it('renders the title text', () => {
+    renderComponent({ title: 'Nothing here' });
+    expect(screen.getByText('Nothing here')).toBeTruthy();
+  });
+
+  it('renders the subtitle when provided', () => {
+    renderComponent({ subtitle: 'Long-press a message to pin it to the chat' });
+    expect(screen.getByText('Long-press a message to pin it to the chat')).toBeTruthy();
+  });
+
+  it('does not render a subtitle when omitted', () => {
+    renderComponent({ subtitle: undefined });
+    expect(screen.queryByText('Long-press a message to pin it to the chat')).toBeNull();
+  });
+
+  it('honors a custom container style override from the theme', () => {
+    const customTheme = {
+      ...defaultTheme,
+      emptyList: {
+        container: { backgroundColor: 'rgb(255, 0, 0)' },
+        subtitle: {},
+        title: {},
+      },
+    };
+
+    render(
+      <ThemeProvider theme={customTheme}>
+        <EmptyList icon={Pin} title='Empty' />
+      </ThemeProvider>,
+    );
+
+    const container = screen.getByTestId('empty-list');
+    const flattened = Array.isArray(container.props.style)
+      ? Object.assign({}, ...container.props.style.flat(Infinity).filter(Boolean))
+      : container.props.style;
+    expect(flattened.backgroundColor).toBe('rgb(255, 0, 0)');
+  });
+
+  it('honors custom title and subtitle style overrides from the theme', () => {
+    const customTheme = {
+      ...defaultTheme,
+      emptyList: {
+        container: {},
+        subtitle: { color: 'rgb(0, 0, 255)' },
+        title: { color: 'rgb(0, 255, 0)' },
+      },
+    };
+
+    render(
+      <ThemeProvider theme={customTheme}>
+        <EmptyList icon={Pin} subtitle='Subtitle' title='Title' />
+      </ThemeProvider>,
+    );
+
+    const flatten = (node: { props: { style: unknown } }) =>
+      Array.isArray(node.props.style)
+        ? Object.assign({}, ...(node.props.style as unknown[]).flat(Infinity).filter(Boolean))
+        : node.props.style;
+
+    const title = screen.getByText('Title') as unknown as { props: { style: unknown } };
+    const subtitle = screen.getByText('Subtitle') as unknown as { props: { style: unknown } };
+
+    expect((flatten(title) as { color?: string }).color).toBe('rgb(0, 255, 0)');
+    expect((flatten(subtitle) as { color?: string }).color).toBe('rgb(0, 0, 255)');
+  });
+});

package/src/components/UIComponents/index.ts

@@ -1,6 +1,7 @@
 export * from './BottomSheetModal';
 export * from './ClippingFadeBottom';
 export * from './StreamBottomSheetModalFlatList';
+export * from './EmptyList';
 export * from './EmptySearchResult';
 export * from './ImageBackground';
 export * from './SearchInput';

package/src/components/ui/Avatar/AvatarGroup.tsx

@@ -28,8 +28,8 @@ export type AvatarGroupProps = {
 // Sizes accounts for the border width as well
 const sizes = {
   '2xl': {
-    width: 64,
-    height: 64,
+    width: 80,
+    height: 80,
   },
   xl: {
     width: 48,
@@ -165,7 +165,7 @@ export type UserAvatarGroupProps = Pick<AvatarGroupProps, 'size'> & {
 };
 
 const userAvatarSize: Record<UserAvatarGroupProps['size'], UserAvatarProps['size']> = {
-  '2xl': 'lg',
+  '2xl': 'xl',
   xl: 'md',
   lg: 'sm',
 };

package/src/components/ui/Avatar/constants.ts

@@ -7,8 +7,8 @@ import { OnlineIndicatorProps } from '../Badge';
 
 const avatarSizes = {
   '2xl': {
-    height: 64,
-    width: 64,
+    height: 80,
+    width: 80,
   },
   xl: {
     height: 48,

package/src/contexts/channelFileAttachmentListContext/ChannelFileAttachmentListContext.tsx

@@ -0,0 +1,67 @@
+import React, { PropsWithChildren, useContext, useState } from 'react';
+
+import { Channel, MessageSearchSource } from 'stream-chat';
+
+import { useChatContext } from '..';
+import { DEFAULT_BASE_CONTEXT_VALUE } from '../utils/defaultBaseContextValue';
+import { isTestEnvironment } from '../utils/isTestEnvironment';
+
+/**
+ * @experimental This API is experimental and is subject to change.
+ */
+export type ChannelFileAttachmentListContextValue = {
+  channel: Channel;
+  searchSource: MessageSearchSource;
+};
+
+export const ChannelFileAttachmentListContext = React.createContext(
+  DEFAULT_BASE_CONTEXT_VALUE as ChannelFileAttachmentListContextValue,
+);
+
+/**
+ * @experimental This API is experimental and is subject to change.
+ */
+export const ChannelFileAttachmentListProvider = ({
+  channel,
+  children,
+}: PropsWithChildren<{ channel: Channel }>) => {
+  const { client } = useChatContext();
+  const [searchSource] = useState(() => {
+    const source = new MessageSearchSource(client, {
+      allowEmptySearchString: true,
+      pageSize: 25,
+      resetOnNewSearchQuery: false,
+    });
+    source.messageSearchChannelFilters = { cid: channel.cid, members: undefined };
+    source.messageSearchFilters = {
+      $or: [{ 'attachments.type': 'file' }, { 'attachments.type': 'audio' }],
+    };
+    // Newest first so the list groups cleanly under month section headers.
+    source.messageSearchSort = { created_at: -1 };
+    source.activate();
+    return source;
+  });
+
+  return (
+    <ChannelFileAttachmentListContext.Provider value={{ channel, searchSource }}>
+      {children}
+    </ChannelFileAttachmentListContext.Provider>
+  );
+};
+
+/**
+ * @experimental This API is experimental and is subject to change.
+ */
+export const useChannelFileAttachmentListContext = () => {
+  const contextValue = useContext(
+    ChannelFileAttachmentListContext,
+  ) as unknown as ChannelFileAttachmentListContextValue;
+
+  if (contextValue === DEFAULT_BASE_CONTEXT_VALUE && !isTestEnvironment()) {
+    throw new Error(
+      'The useChannelFileAttachmentListContext hook was called outside of the ChannelFileAttachmentListContext provider. Render the file attachment list UI inside a ChannelFileAttachmentListProvider.',
+    );
+  }
+
+  return contextValue;
+};

package/src/contexts/channelMediaListContext/ChannelMediaListContext.tsx

@@ -0,0 +1,68 @@
+import React, { PropsWithChildren, useContext, useState } from 'react';
+
+import { Channel, MessageSearchSource } from 'stream-chat';
+
+import { useChatContext } from '..';
+import { DEFAULT_BASE_CONTEXT_VALUE } from '../utils/defaultBaseContextValue';
+import { isTestEnvironment } from '../utils/isTestEnvironment';
+
+/**
+ * @experimental This API is experimental and is subject to change.
+ */
+export type ChannelMediaListContextValue = {
+  channel: Channel;
+  searchSource: MessageSearchSource;
+};
+
+export const ChannelMediaListContext = React.createContext(
+  DEFAULT_BASE_CONTEXT_VALUE as ChannelMediaListContextValue,
+);
+
+/**
+ * @experimental This API is experimental and is subject to change.
+ */
+export const ChannelMediaListProvider = ({
+  channel,
+  children,
+}: PropsWithChildren<{ channel: Channel }>) => {
+  const { client } = useChatContext();
+  const [searchSource] = useState(() => {
+    const source = new MessageSearchSource(client, {
+      allowEmptySearchString: true,
+      pageSize: 25,
+      resetOnNewSearchQuery: false,
+    });
+    source.messageSearchChannelFilters = { cid: channel.cid, members: undefined };
+    source.messageSearchFilters = {
+      'attachments.type': { $in: ['image', 'video'] },
+      type: undefined,
+    };
+    // Newest media first so the grid reads top-to-bottom from most recent.
+    source.messageSearchSort = { created_at: -1 };
+    source.activate();
+    return source;
+  });
+
+  return (
+    <ChannelMediaListContext.Provider value={{ channel, searchSource }}>
+      {children}
+    </ChannelMediaListContext.Provider>
+  );
+};
+
+/**
+ * @experimental This API is experimental and is subject to change.
+ */
+export const useChannelMediaListContext = () => {
+  const contextValue = useContext(
+    ChannelMediaListContext,
+  ) as unknown as ChannelMediaListContextValue;
+
+  if (contextValue === DEFAULT_BASE_CONTEXT_VALUE && !isTestEnvironment()) {
+    throw new Error(
+      'The useChannelMediaListContext hook was called outside of the ChannelMediaListContext provider. Render the media list UI inside a ChannelMediaListProvider.',
+    );
+  }
+
+  return contextValue;
+};