refactor: introduce WithComponents context provider (#3542)

## 🎯 Goal

Replace the prop-drilling of 120+ component overrides with a single
`WithComponents` context provider. This eliminates massive boilerplate
across `Channel`, `ChannelList`, and all consumer components.

**Before:**
```tsx
<Channel Message={MyMessage} SendButton={MySendButton} Reply={MyReply} channel={channel}>
```

**After:**
```tsx
<WithComponents overrides={{ Message: MyMessage, SendButton: MySendButton, Reply: MyReply }}>
  <Channel channel={channel}>
</WithComponents>
```

## 🛠 Implementation details

### Design principle

**All components are read from `useComponentsContext()`. All other
contexts only provide data + APIs — never components.**

### New `ComponentsContext`
- `WithComponents` provider — nestable, inner overrides win. Uses
`overrides` prop (aligned with `stream-chat-react`)
- `useComponentsContext()` hook — returns all components with defaults
filled in
- `ComponentOverrides` type — auto-derived from `DEFAULT_COMPONENTS` map
(`Partial<typeof DEFAULT_COMPONENTS>`)
- `defaultComponents.ts` — single source of truth for all ~120 default
component mappings (lazy-loaded to avoid circular deps)
- Adding a new overridable component only requires editing
`defaultComponents.ts` — the type is derived automatically

### What changed
- **Stripped component keys** from `MessagesContextValue`,
`InputMessageInputContextValue`, `ChannelContextValue`,
`ChannelsContextValue`, `AttachmentPickerContextValue`,
`ThreadsContextValue`, `ImageGalleryContextValue` — these now only carry
data + APIs
- **Simplified `useCreate*Context` hooks** — no longer receive or
forward component params
- **Simplified `Channel.tsx`** — removed ~90 component imports, prop
defaults, and forwarding lines
- **Simplified `ChannelList.tsx`** — removed ~19 component props
- **Updated ~80 consumer files** — switched from old context hooks to
`useComponentsContext()` for component reads
- **Removed component override props** from ALL individual components
(Chat, Thread, ThreadList, Poll, ChannelPreview, ImageGallery, etc.)
- **No component accepts component overrides as props anymore** —
everything goes through `WithComponents`
- **`ComponentsContext.tsx` reduced from ~350 lines to ~55 lines** —
type is derived from defaults, no manual type maintenance
- **Updated all 3 example apps** (SampleApp, ExpoMessaging,
TypeScriptMessaging) to use `WithComponents`

### Net result
- **90+ files changed**, net **-2500+ lines** removed
- Each component override name went from being listed 4 times to 0 in
the forwarding pipeline
- One place to override components: `<WithComponents overrides={{ ...
}}>`
- One place to read components: `useComponentsContext()`
- One place to add new overridable components: `defaultComponents.ts`

## BREAKING CHANGE

- **Component override props removed from all SDK components** —
`<Channel Message={X}>`, `<ChannelList Preview={X}>`, `<Thread
MessageComposer={X}>`, etc. no longer accept component overrides as
props. Use `<WithComponents overrides={{ Message: X }}>` instead.
- **Component keys removed from context value types** —
`MessagesContextValue`, `InputMessageInputContextValue`,
`ChannelContextValue`, `ChannelsContextValue`,
`AttachmentPickerContextValue`, `ThreadsContextValue`,
`ImageGalleryContextValue` no longer include component-type keys. Use
`useComponentsContext()` to read component overrides.
- **`List` prop removed from `ChannelList`** — use custom
`EmptyStateIndicator` override or wrap `ChannelListView` directly.
- **`LoadingIndicator` prop removed from `Chat`** — use `<WithComponents
overrides={{ ChatLoadingIndicator: X }}>`.

## 🎨 UI Changes

No visual changes — this is a pure structural refactor.

## 🧪 Testing

- `yarn build` — 0 type errors
- `yarn lint` — passes clean (0 warnings, 0 errors)
- `yarn test:unit` — 91/92 suites pass; 1 pre-existing timeout failure
in `offline-support` that also fails on `develop`
- New test: `defaultComponents.test.ts` verifies all default component
mappings are defined and optional keys are explicitly listed
- Updated test files to use `<WithComponents overrides={...}>` wrapper
instead of removed component override props

## ☑️ Checklist

- [x] I have signed the [Stream
CLA](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform)
(required)
- [x] PR targets the `develop` branch
- [ ] Documentation is updated
- [x] New code is tested in main example apps, including all possible
scenarios
  - [x] SampleApp iOS and Android
  - [x] Expo iOS and Android

---------

Co-authored-by: Ivan Sekovanikj <ivan.sekovanikj@getstream.io>

Author: oliverlaz

examples/ExpoMessaging/app/channel/[cid]/index.tsx

@@ -6,6 +6,7 @@ import {
   useChatContext,
   ThreadContextValue,
   MessageList,
+  WithComponents,
 } from 'stream-chat-expo';
 import { Stack, useLocalSearchParams, useRouter } from 'expo-router';
 import { AuthProgressLoader } from '../../../components/AuthProgressLoader';
@@ -70,22 +71,23 @@ export default function ChannelScreen() {
       <Stack.Screen
         options={{ title: 'Channel Screen', contentStyle: { backgroundColor: 'white' } }}
       />
-      <Channel
-        audioRecordingEnabled={true}
-        channel={channel}
-        onPressMessage={onPressMessage}
-        keyboardVerticalOffset={headerHeight}
-        MessageLocation={MessageLocation}
-        thread={thread}
-      >
-        <MessageList
-          onThreadSelect={(thread: ThreadContextValue['thread']) => {
-            setThread(thread);
-            router.push(`/channel/${channel.cid}/thread/${thread?.cid ?? ''}`);
-          }}
-        />
-        <MessageComposer InputButtons={InputButtons} />
-      </Channel>
+      <WithComponents overrides={{ MessageLocation, InputButtons }}>
+        <Channel
+          audioRecordingEnabled={true}
+          channel={channel}
+          onPressMessage={onPressMessage}
+          keyboardVerticalOffset={headerHeight}
+          thread={thread}
+        >
+          <MessageList
+            onThreadSelect={(thread: ThreadContextValue['thread']) => {
+              setThread(thread);
+              router.push(`/channel/${channel.cid}/thread/${thread?.cid ?? ''}`);
+            }}
+          />
+          <MessageComposer />
+        </Channel>
+      </WithComponents>
     </View>
   );
 }

examples/ExpoMessaging/components/InputButtons.tsx

@@ -1,10 +1,11 @@
 import React, { useState } from 'react';
 import { Pressable, StyleSheet } from 'react-native';
-import { Channel, InputButtons as DefaultInputButtons } from 'stream-chat-expo';
+import type { ComponentOverrides } from 'stream-chat-expo';
+import { InputButtons as DefaultInputButtons } from 'stream-chat-expo';
 import { ShareLocationIcon } from '../icons/ShareLocationIcon';
 import { LiveLocationCreateModal } from './LocationSharing/CreateLocationModal';
 
-const InputButtons: NonNullable<React.ComponentProps<typeof Channel>['InputButtons']> = (props) => {
+const InputButtons: NonNullable<ComponentOverrides['InputButtons']> = (props) => {
   const [modalVisible, setModalVisible] = useState(false);
 
   const onRequestClose = () => {

examples/SampleApp/src/screens/ChannelListScreen.tsx

@@ -10,12 +10,7 @@ import {
   View,
 } from 'react-native';
 import { useNavigation, useScrollToTop } from '@react-navigation/native';
-import {
-  ChannelList,
-  useTheme,
-  useStableCallback,
-  ChannelActionItem,
-} from 'stream-chat-react-native';
+import { ChannelList, useTheme, useStableCallback, ChannelActionItem, WithComponents } from 'stream-chat-react-native';
 import { Channel } from 'stream-chat';
 import { ChannelPreview } from '../components/ChannelPreview';
 import { ChatScreenHeader } from '../components/ChatScreenHeader';
@@ -254,18 +249,23 @@ export const ChannelListScreen: React.FC = () => {
         )}
         <View style={{ flex: searchQuery ? 0 : 1 }}>
           <View style={[styles.channelListContainer, { opacity: searchQuery ? 0 : 1 }]}>
-            <ChannelList
-              additionalFlatListProps={additionalFlatListProps}
-              filters={filters}
-              HeaderNetworkDownIndicator={HeaderNetworkDownIndicator}
-              maxUnreadCount={99}
-              onSelect={onSelect}
-              options={options}
-              Preview={ChannelPreview}
-              setFlatListRef={setScrollRef}
-              getChannelActionItems={getChannelActionItems}
-              sort={sort}
-            />
+            <WithComponents
+              overrides={{
+                HeaderNetworkDownIndicator,
+                Preview: ChannelPreview,
+              }}
+            >
+              <ChannelList
+                additionalFlatListProps={additionalFlatListProps}
+                filters={filters}
+                maxUnreadCount={99}
+                onSelect={onSelect}
+                options={options}
+                setFlatListRef={setScrollRef}
+                getChannelActionItems={getChannelActionItems}
+                sort={sort}
+              />
+            </WithComponents>
           </View>
         </View>
       </View>

examples/SampleApp/src/screens/ChannelScreen.tsx

@@ -17,6 +17,7 @@ import {
   MessageActionsParams,
   ChannelAvatar,
   PortalWhileClosingView,
+  WithComponents,
 } from 'stream-chat-react-native';
 import { Pressable, StyleSheet, View } from 'react-native';
 import type { NativeStackNavigationProp } from '@react-navigation/native-stack';
@@ -265,19 +266,23 @@ export const ChannelScreen: React.FC<ChannelScreenProps> = ({ navigation, route
 
   return (
     <View style={[styles.flex, { backgroundColor: 'transparent' }]}>
+      <WithComponents
+        overrides={{
+          // AttachmentPickerSelectionBar: CustomAttachmentPickerSelectionBar,
+          AttachmentPickerContent: CustomAttachmentPickerContent,
+          MessageLocation,
+          NetworkDownIndicator: () => null,
+        }}
+      >
       <Channel
         audioRecordingEnabled={true}
-        // AttachmentPickerSelectionBar={CustomAttachmentPickerSelectionBar}
-        AttachmentPickerContent={CustomAttachmentPickerContent}
         channel={channel}
         messageInputFloating={messageInputFloating}
         onPressMessage={onPressMessage}
         initialScrollToFirstUnreadMessage
         keyboardVerticalOffset={0}
         messageActions={messageActions}
-        MessageLocation={MessageLocation}
         messageId={messageId}
-        NetworkDownIndicator={() => null}
         onAlsoSentToChannelHeaderPress={onAlsoSentToChannelHeaderPress}
         thread={selectedThread}
         maximumMessageLimit={messageListPruning}
@@ -306,6 +311,7 @@ export const ChannelScreen: React.FC<ChannelScreenProps> = ({ navigation, route
           />
         )}
       </Channel>
+      </WithComponents>
     </View>
   );
 };

examples/SampleApp/src/screens/NewDirectMessagingScreen.tsx

@@ -8,6 +8,7 @@ import {
   MessageList,
   UserAdd,
   useTheme,
+  WithComponents,
 } from 'stream-chat-react-native';
 
 import { User } from '../icons/User';
@@ -338,32 +339,37 @@ export const NewDirectMessagingScreen: React.FC<NewDirectMessagingScreenProps> =
         },
       ]}
     >
-      <Channel
-        additionalTextInputProps={{
-          onFocus: () => {
-            setFocusOnMessageInput(true);
-            setFocusOnSearchInput(false);
-            if (messageInputRef.current) {
-              messageInputRef.current.focus();
-            }
-          },
+      <WithComponents
+        overrides={{
+          EmptyStateIndicator: EmptyMessagesIndicator,
+          SendButton: NewDirectMessagingSendButton,
         }}
-        audioRecordingEnabled={true}
-        channel={currentChannel.current}
-        EmptyStateIndicator={EmptyMessagesIndicator}
-        enforceUniqueReaction
-        keyboardVerticalOffset={0}
-        onChangeText={setMessageInputText}
-        overrideOwnCapabilities={{ sendMessage: true }}
-        SendButton={NewDirectMessagingSendButton}
-        setInputRef={(ref) => (messageInputRef.current = ref)}
       >
-        {renderUserSearch({ inSafeArea: true })}
-        {results && results.length >= 0 && !focusOnSearchInput && focusOnMessageInput && (
-          <MessageList />
-        )}
-        <MessageComposer />
-      </Channel>
+        <Channel
+          additionalTextInputProps={{
+            onFocus: () => {
+              setFocusOnMessageInput(true);
+              setFocusOnSearchInput(false);
+              if (messageInputRef.current) {
+                messageInputRef.current.focus();
+              }
+            },
+          }}
+          audioRecordingEnabled={true}
+          channel={currentChannel.current}
+          enforceUniqueReaction
+          keyboardVerticalOffset={0}
+          onChangeText={setMessageInputText}
+          overrideOwnCapabilities={{ sendMessage: true }}
+          setInputRef={(ref) => (messageInputRef.current = ref)}
+        >
+          {renderUserSearch({ inSafeArea: true })}
+          {results && results.length >= 0 && !focusOnSearchInput && focusOnMessageInput && (
+            <MessageList />
+          )}
+          <MessageComposer />
+        </Channel>
+      </WithComponents>
     </SafeAreaView>
   );
 };

examples/SampleApp/src/screens/SharedGroupsScreen.tsx

@@ -3,8 +3,6 @@ import { StyleSheet, Text, TouchableOpacity, View } from 'react-native';
 import { NavigationProp, RouteProp, useNavigation } from '@react-navigation/native';
 import {
   ChannelList,
-  ChannelListView,
-  ChannelListViewProps,
   ChannelPreviewViewProps,
   getChannelPreviewDisplayAvatar,
   GroupAvatar,
@@ -13,6 +11,7 @@ import {
   useTheme,
   Avatar,
   getInitialsFromName,
+  WithComponents,
 } from 'stream-chat-react-native';
 
 import { ScreenHeader } from '../components/ScreenHeader';
@@ -145,18 +144,19 @@ const EmptyListComponent = () => {
   );
 };
 
-type ListComponentProps = ChannelListViewProps;
-
-// If the length of channels is 1, which means we only got 1:1-distinct channel,
-// And we don't want to show 1:1-distinct channel in this list.
-const ListComponent: React.FC<ListComponentProps> = (props) => {
+// Custom empty state that also shows when there's only the 1:1 direct channel
+const SharedGroupsEmptyState = () => {
   const { channels, loadingChannels, refreshing } = useChannelsContext();
 
-  if (channels && channels.length <= 1 && !loadingChannels && !refreshing) {
+  if (loadingChannels || refreshing) {
+    return null;
+  }
+
+  if (!channels || channels.length <= 1) {
     return <EmptyListComponent />;
   }
 
-  return <ChannelListView {...props} />;
+  return null;
 };
 
 type SharedGroupsScreenRouteProp = RouteProp<StackNavigatorParamList, 'SharedGroupsScreen'>;
@@ -179,19 +179,24 @@ export const SharedGroupsScreen: React.FC<SharedGroupsScreenProps> = ({
   return (
     <View style={styles.container}>
       <ScreenHeader titleText='Shared Groups' />
-      <ChannelList
-        filters={{
-          $and: [{ members: { $in: [chatClient?.user?.id] } }, { members: { $in: [user.id] } }],
+      <WithComponents
+        overrides={{
+          EmptyStateIndicator: SharedGroupsEmptyState,
+          Preview: CustomPreview,
         }}
-        List={ListComponent}
-        options={{
-          watch: false,
-        }}
-        Preview={CustomPreview}
-        sort={{
-          last_updated: -1,
-        }}
-      />
+      >
+        <ChannelList
+          filters={{
+            $and: [{ members: { $in: [chatClient?.user?.id] } }, { members: { $in: [user.id] } }],
+          }}
+          options={{
+            watch: false,
+          }}
+          sort={{
+            last_updated: -1,
+          }}
+        />
+      </WithComponents>
     </View>
   );
 };

examples/SampleApp/src/screens/ThreadScreen.tsx

@@ -12,6 +12,7 @@ import {
   useTranslationContext,
   useTypingString,
   PortalWhileClosingView,
+  WithComponents,
 } from 'stream-chat-react-native';
 import { useStateStore } from 'stream-chat-react-native';
 
@@ -148,15 +149,19 @@ export const ThreadScreen: React.FC<ThreadScreenProps> = ({
 
   return (
     <View style={[styles.container, { backgroundColor: white }]}>
+      <WithComponents
+        overrides={{
+          // AttachmentPickerSelectionBar: CustomAttachmentPickerSelectionBar,
+          MessageLocation,
+        }}
+      >
       <Channel
         audioRecordingEnabled={true}
-        // AttachmentPickerSelectionBar={CustomAttachmentPickerSelectionBar}
         channel={channel}
         enforceUniqueReaction
         keyboardVerticalOffset={0}
         messageActions={messageActions}
         messageInputFloating={messageInputFloating}
-        MessageLocation={MessageLocation}
         onPressMessage={onPressMessage}
         thread={thread}
         threadList
@@ -174,6 +179,7 @@ export const ThreadScreen: React.FC<ThreadScreenProps> = ({
           shouldUseFlashList={messageListImplementation === 'flashlist'}
         />
       </Channel>
+      </WithComponents>
     </View>
   );
 };