docs: update PLAN.md with current state and reference notes

Author: oliverlaz

package/src/contexts/componentsContext/PLAN.md

@@ -1,180 +1,146 @@
-# Plan: `WithComponents` Context Provider
-
-## Context
-
-The SDK prop-drills 120+ component overrides through `<Channel>` → `useCreate*Context` hooks → context values. Each component name is listed **4 times** (destructured from props → passed to hook → destructured in hook → listed in useMemo). Consumers then read components back out via `useMessagesContext()`, `useMessageInputContext()`, etc.
-
-**Goal**: Replace this entire pipeline with a single `ComponentsContext`. Component overrides are **removed** from all existing contexts. Consumers read components via `useComponentsContext()` instead.
-
-```tsx
-// User API
-<WithComponents value={{ Message: MyMessage, SendButton: MySendButton }}>
-  <Channel channel={channel}>
-    <MessageList />
-    <MessageInput />
-  </Channel>
-</WithComponents>
-```
+# WithComponents — Component Override System
 
 ## Design Principle
 
 **All components are read from `useComponentsContext()`. All other contexts only provide data + APIs — never components.**
 
-No context besides `ComponentsContext` should carry component references. This is the single rule that drives every change in this plan.
+## Current State (Completed)
 
-## Architecture
+### What was done
 
-### Before
+1. **Created `ComponentsContext`** — `WithComponents` provider, `useComponentsContext()` hook, `ComponentOverrides` type
+2. **Created `defaultComponents.ts`** — centralized map of all ~130 default components
+3. **Stripped component keys** from all existing context types: `MessagesContextValue`, `InputMessageInputContextValue`, `ChannelContextValue`, `ChannelsContextValue`, `AttachmentPickerContextValue`, `ThreadsContextValue`, `ImageGalleryContextValue`
+4. **Simplified `useCreate*Context` hooks** — no longer receive or forward component params
+5. **Simplified `Channel.tsx`** — removed ~90 component imports, prop defaults, forwarding lines
+6. **Simplified `ChannelList.tsx`** — removed ~19 component props
+7. **Updated ~80 consumer files** — switched from old context hooks to `useComponentsContext()`
+8. **Removed component override props** from ALL individual components
+9. **Updated all 3 example apps** (SampleApp, ExpoMessaging, TypeScriptMessaging)
+10. **Updated ~45 documentation pages** across docs-content repo
+11. **Merged with develop** and resolved conflicts
 
-```
-Channel props (90+ component overrides with defaults)
-  → useCreateMessagesContext (receives 60+ component params, maps into useMemo)
-  → MessagesContext carries components + runtime data
-  → Consumer: const { Message } = useMessagesContext()
-```
-
-### After
+### Architecture
 
 ```
-DEFAULT_COMPONENTS (static map)
-  → ComponentsContext (defaults; user overrides via WithComponents)
-  → Consumer: const { Message } = useComponentsContext()
-
-Channel props (runtime/config only)
-  → useCreateMessagesContext (runtime data only, no components)
-  → MessagesContext carries ONLY data + APIs
-  → Consumer: const { deleteMessage } = useMessagesContext()
+User: <WithComponents overrides={{ Message: Custom }}>
+  ↓
+ComponentsContext (merges parent + overrides, inner wins)
+  ↓
+useComponentsContext() → { ...DEFAULT_COMPONENTS, ...overrides }
+  ↓
+Consumer: const { Message } = useComponentsContext()
 ```
 
-## Scope
-
-### What changes
-
-1. **Existing context types** (`MessagesContextValue`, `InputMessageInputContextValue`, `ChannelContextValue`, `ChannelsContextValue`, `AttachmentPickerContextValue`) — remove all component-type keys
-2. **`useCreate*Context` hooks** — remove all component params, stop mapping them
-3. **Channel.tsx** — remove ~90 component imports, ~90 destructuring defaults, ~90 forwarding lines
-4. **ChannelList.tsx** — remove ~19 component props and forwarding
-5. **~117 consumer callsites across ~97 files** — switch from `useXContext()` to `useComponentsContext()` for component reads
-
-### What doesn't change
+### Key Files
 
-- Runtime data flow (callbacks like `deleteMessage`, `sendReaction`, state like `targetedMessage`) stays in existing contexts
-- Consumer reads of runtime data (`const { deleteMessage } = useMessagesContext()`) are untouched
-- `WithComponents` nesting semantics (inner wins, like standard React context)
+| File | Purpose |
+|------|---------|
+| `ComponentsContext.tsx` | ~60 lines. `ComponentOverrides` type (derived from `typeof DEFAULT_COMPONENTS`), `WithComponents` provider, `useComponentsContext()` hook |
+| `defaultComponents.ts` | ~300 lines. Single source of truth for all default component mappings. Adding a new component here auto-extends `ComponentOverrides` |
 
-## New Files
+### Type System
 
-| File                                                           | Purpose                                                                             |
-| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `package/src/contexts/componentsContext/ComponentsContext.tsx` | `ComponentOverrides` type, `WithComponents` provider, `useComponentsContext()` hook |
-| `package/src/contexts/componentsContext/defaultComponents.ts`  | All default component imports → `DEFAULT_COMPONENTS` map                            |
-
-Both already drafted in the repo.
-
-## Implementation Steps
-
-### Step 1: Finalize `ComponentsContext.tsx` and `defaultComponents.ts`
-
-Already drafted. Key design:
-
-- `ComponentOverrides`: flat map, all keys optional, explicitly typed per component
-- Context default = `DEFAULT_COMPONENTS` → `useComponentsContext()` always returns resolved values
-- `WithComponents`: merges `{ ...parent, ...value }` (inner wins)
-- `ResolvedComponents` = `Required<ComponentOverrides>` for the return type
-
-Special cases:
-
-- `FlatList` — from `NativeHandlers.FlatList` at runtime. Keep as a runtime prop in MessagesContext, not in ComponentsContext.
-- `StopMessageStreamingButton` — can be `null` (explicitly hide). The type in ComponentOverrides allows `| null`.
+`ComponentOverrides` is derived automatically:
+```ts
+export type ComponentOverrides = Partial<
+  (typeof import('./defaultComponents'))['DEFAULT_COMPONENTS']
+>;
+```
 
-### Step 2: Strip component keys from existing context value types
+No manual type maintenance — add a component to `DEFAULT_COMPONENTS` and the type updates.
 
-**`MessagesContextValue`** (`package/src/contexts/messagesContext/MessagesContext.tsx`):
-Remove ~60 component keys (Attachment, AudioAttachment, DateHeader, Message, MessageContent, Reply, etc.). Keep runtime keys only (deleteMessage, deleteReaction, dismissKeyboardOnMessageTouch, giphyVersion, messageContentOrder, etc.).
+### Circular Dependency Handling
 
-**`InputMessageInputContextValue`** (`package/src/contexts/messageInputContext/MessageInputContext.tsx`):
-Remove ~35 component keys (AttachButton, AudioRecorder, SendButton, Input, InputView, etc.). Keep runtime keys only (asyncMessagesLockDistance, audioRecordingEnabled, editMessage, sendMessage, etc.).
+`defaultComponents.ts` → imports components → components import `useComponentsContext` from `ComponentsContext.tsx`.
 
-**`ChannelContextValue`** (`package/src/contexts/channelContext/ChannelContext.tsx`):
-Remove 4 component keys (EmptyStateIndicator, LoadingIndicator, NetworkDownIndicator, StickyHeader).
+Broken by lazy-loading defaults in the hook:
+```ts
+let cachedDefaults: ComponentOverrides | undefined;
+const getDefaults = () => {
+  if (!cachedDefaults) {
+    cachedDefaults = require('./defaultComponents').DEFAULT_COMPONENTS;
+  }
+  return cachedDefaults;
+};
+```
 
-**`ChannelsContextValue`** (`package/src/contexts/channelsContext/ChannelsContext.tsx`):
-Remove ~19 component keys (Preview, PreviewAvatar, PreviewMessage, Skeleton, FooterLoadingIndicator, etc.).
+### Naming Conventions
 
-**`AttachmentPickerContextValue`** (`package/src/contexts/attachmentPickerContext/AttachmentPickerContext.tsx`):
-Remove 3 component keys (ImageOverlaySelectedComponent, AttachmentPickerSelectionBar, AttachmentPickerContent).
+Some component keys differ from their default component names to avoid collisions:
 
-### Step 3: Simplify `useCreate*Context` hooks
+| Override Key | Default Component | Why renamed |
+|---|---|---|
+| `FileAttachmentIcon` | `FileIcon` | Clarity |
+| `ChannelListLoadingIndicator` | `ChannelListLoadingIndicator` | Split from shared `LoadingIndicator` — renders skeleton UI |
+| `MessageListLoadingIndicator` | `LoadingIndicator` | Split from shared `LoadingIndicator` — renders text |
+| `ChatLoadingIndicator` | `undefined` | Optional, no default |
+| `ThreadMessageComposer` | `MessageComposer` | Avoid collision with `MessageComposer` component name |
+| `ThreadListComponent` | `DefaultThreadListComponent` | Avoid collision with exported `ThreadList` |
+| `StartAudioRecordingButton` | `AudioRecordingButton` | Historical naming |
+| `Preview` | `ChannelPreviewView` | ChannelList preview item |
+| `PreviewAvatar` | `ChannelAvatar` | ChannelList preview avatar |
+| `FooterLoadingIndicator` | `ChannelListFooterLoadingIndicator` | ChannelList footer |
+| `HeaderErrorIndicator` | `ChannelListHeaderErrorIndicator` | ChannelList header |
+| `HeaderNetworkDownIndicator` | `ChannelListHeaderNetworkDownIndicator` | ChannelList header |
 
-Each hook drops all component params and stops mapping them into useMemo:
+### Optional Components (no default)
 
-- **`useCreateMessagesContext`** (`package/src/components/Channel/hooks/useCreateMessagesContext.ts`): ~60 component params removed, keep ~30 runtime params
-- **`useCreateInputMessageInputContext`** (`package/src/components/Channel/hooks/useCreateInputMessageInputContext.ts`): ~35 component params removed, keep ~15 runtime params
-- **`useCreateChannelContext`** (`package/src/components/Channel/hooks/useCreateChannelContext.ts`): 4 component params removed
-- **`useCreateChannelsContext`** (`package/src/components/ChannelList/hooks/useCreateChannelsContext.ts`): ~19 component params removed, keep ~20 runtime params
+These exist in `DEFAULT_COMPONENTS` as `undefined` with `React.ComponentType<any> | undefined` type assertions:
 
-### Step 4: Simplify Channel.tsx
+`AttachmentPickerIOSSelectMorePhotos`, `ChatLoadingIndicator`, `CreatePollContent`, `ImageComponent`, `Input`, `ListHeaderComponent`, `MessageContentBottomView`, `MessageContentLeadingView`, `MessageContentTopView`, `MessageContentTrailingView`, `MessageLocation`, `MessageSpacer`, `MessageText`, `PollContent`
 
-- Remove ~90 default component imports (lines 114-223)
-- Remove component keys from `ChannelPropsWithContext` type
-- Remove component destructuring defaults from `ChannelWithContext`
-- Remove component values from `useCreateMessagesContext()`, `useCreateInputMessageInputContext()`, `useCreateChannelContext()` calls
-- Remove component values from `attachmentPickerContext` useMemo
-- `LoadingErrorIndicator` and `KeyboardCompatibleView` are used directly in Channel's JSX — read from `useComponentsContext()` or keep as Channel-specific props
+### Shared Component Keys (audited)
 
-### Step 5: Simplify ChannelList.tsx
+Some keys were used in multiple contexts before the refactor. Audit results:
 
-- Remove component keys from `ChannelListProps` type
-- Remove default component imports
-- Remove component values from `useCreateChannelsContext()` call
+| Key | Used By | Same Default? | Resolution |
+|-----|---------|---------------|------------|
+| `EmptyStateIndicator` | Channel + ChannelList | Yes (differentiates via `listType` prop) | Single key ✅ |
+| `LoadingErrorIndicator` | Channel + ChannelList | Yes (differentiates via `listType` prop) | Single key ✅ |
+| `LoadingIndicator` | Channel + ChannelList | **No** — Channel used text-based, ChannelList used skeleton | Split into `MessageListLoadingIndicator` + `ChannelListLoadingIndicator` ✅ |
 
-### Step 6: Update ~117 consumer callsites
+### API Alignment with stream-chat-react
 
-Switch component destructuring from old context hooks to `useComponentsContext()`:
+| Aspect | React Native | React Web |
+|--------|-------------|-----------|
+| Provider | `WithComponents` | `WithComponents` |
+| Prop name | `overrides` | `overrides` |
+| Hook | `useComponentsContext()` | `useComponentContext()` |
+| Type | `ComponentOverrides` (auto-derived) | `ComponentContextValue` (hand-written) |
+| Defaults | Lazy-loaded via `require()` | Set at `Channel` level |
+| Merge | `useMemo` | Plain spread (no memo) |
 
-```tsx
-// Before
-const { Message, MessageStatus, MessageTimestamp } = useMessagesContext();
-const { deleteMessage } = useMessagesContext();
+## Known Issues / Future Work
 
-// After
-const { Message, MessageStatus, MessageTimestamp } = useComponentsContext();
-const { deleteMessage } = useMessagesContext();
-```
+### Pre-existing Test Failures (not caused by this work)
 
-**Key files by volume** (largest consumers):
+These test suites fail on `develop` too:
+- `offline-support/index.test.ts` — timeout
+- `ChannelList.test.js` — filter race condition (`channel.countUnread` mock missing)
+- `isAttachmentEqualHandler.test.js`, `MessageContent.test.js`, `MessageTextContainer.test.tsx`, `MessageUserReactions.test.tsx`, `ChannelPreview.test.tsx` — various pre-existing issues
 
-- `components/Message/MessageItemView/MessageItemView.tsx` — 15+ component keys
-- `components/Message/MessageItemView/MessageContent.tsx` — 15+ component keys
-- `components/MessageList/MessageList.tsx` — 10+ component keys
-- `components/MessageList/MessageFlashList.tsx` — 10+ component keys
-- `components/MessageInput/MessageComposer.tsx` — 25+ component keys
-- `components/Attachment/Attachment.tsx` — 10+ component keys
-- `components/ChannelList/ChannelListView.tsx` — multiple component keys
-- `components/ChannelPreview/ChannelPreviewView.tsx` — multiple component keys
+### Linter Interaction
 
-Many other files destructure just 1-2 component keys from context — straightforward replacements.
+`@typescript-eslint/no-unused-vars` (warn, max-warnings 0) aggressively strips unused type keys. When adding new keys to `ComponentOverrides`, the type and its consumer must land in the same edit — otherwise the linter removes the key between saves.
 
-### Step 7: Update exports
+Since `ComponentOverrides` is now auto-derived from `DEFAULT_COMPONENTS`, this is no longer an issue for the type itself. But be aware when adding optional components (`undefined as React.ComponentType<any> | undefined`).
 
-- `package/src/contexts/index.ts` — add `export * from './componentsContext/ComponentsContext'`
-- `package/src/index.ts` — verify `WithComponents`, `ComponentOverrides`, `useComponentsContext` are exported
+### `contexts/index.ts` Barrel Export
 
-### Step 8: Update tests
+The `export * from './componentsContext/ComponentsContext'` line in `contexts/index.ts` was stripped by the linter multiple times during development. If `WithComponents` becomes unexportable from the package, check this barrel file first.
 
-Tests that pass component overrides as Channel/ChannelList props will need to wrap in `<WithComponents>` instead. Mock builders that set up context values with component overrides may also need updating.
+### Documentation
 
-## Edge Cases
+Docs PR: https://github.com/GetStream/docs-content/pull/1169
 
-- **Shared names**: `EmptyStateIndicator`, `LoadingIndicator` exist in both Channel and ChannelList. One key in flat map — users use nesting for different overrides per area.
-- **Mixed destructuring**: Some consumers destructure both components and runtime data from the same `useMessagesContext()` call. These need to be split into two calls.
-- **`FlatList`**: Runtime-resolved from NativeHandlers. Stays in MessagesContext as a runtime value, not in ComponentsContext.
-- **`StopMessageStreamingButton`**: Supports `null` to hide. ComponentOverrides type allows `| null`.
+Updated ~45 pages across:
+- Core teaching pages (custom_components, message-customization, etc.)
+- Component reference pages (channel-list, message-list, message-composer, etc.)
+- Context docs (stripped component keys from 7 context pages)
+- Migration guide (upgrading-from-v8.md — comprehensive WithComponents section)
+- Advanced guides (audio, AI, image-picker, etc.)
 
-## Verification
+### SDK PR
 
-1. `cd package && yarn build` — type-checks and builds
-2. `cd package && yarn test:unit` — tests pass (after updating test fixtures)
-3. `cd package && yarn lint` — no lint errors
-4. Manual: `<WithComponents value={{ Message: Custom }}>` → verify override appears
-5. Verify nesting: inner `WithComponents` wins over outer
+https://github.com/GetStream/stream-chat-react-native/pull/3542