fix!: remove dead v15 surface and restore v14 behaviors found by the API audit

AGENTS.md

@@ -125,7 +125,7 @@ Each is a `StateStore`. Components read them with `useStateStore(store, selector
 
 `Channel` takes a single `channel` prop (`src/components/Channel/Channel.tsx`). It activates the channel on mount, deactivates it on unmount, seeds the paginator's unread snapshot, and re-queries on `user.deleted` — nothing else. It does not query the channel for you: initialize it first (`channel.ensureWatched()` sends one watch for overlapping calls, and none for a channel already watched). There is no `Window` component in v15; compose layout yourself or through `ChatView` slots.
 
-Read the bound channel with `useChannel()` (`src/context/useChannel.ts`, thread's channel first, then the `Channel` subtree's) and the active message list with `useMessagePaginator()` (`src/hooks/useMessagePaginator.ts`, thread first, then channel). `useMessagePaginator()` is internal and not exported from the package; integrator-facing docs and examples read `(thread ?? channel).messagePaginator` via `useThreadContext()` / `useChannel()`.
+Read the bound channel with `useChannel()` (`src/context/useChannel.ts`, thread's channel first, then the `Channel` subtree's) and the active message list with `useMessagePaginator()` (`src/hooks/useMessagePaginator.ts`, thread first, then channel). `useMessagePaginator()` is also exported from the package root, so integrator-facing docs and examples can use it too.
 
 ### Context layers (`src/context/`)
 

src/components/Attachment/ModalGallery.tsx

@@ -71,9 +71,10 @@ export const ModalGallery = ({
       items.map((item) => ({
         ...item,
         createdAt: item.createdAt ?? convertTimestampToDate(message?.created_at),
+        message: item.message ?? message,
         user: item.user ?? message?.user ?? undefined,
       })),
-    [items, message?.created_at, message?.user],
+    [items, message],
   );
   const usesDefaultBaseImage = BaseImage === DefaultBaseImage;
 

src/components/Channel/hooks/useChannelContainerClasses.ts

@@ -8,17 +8,13 @@ export const useImageFlagEmojisOnWindowsClass = () => {
     : '';
 };
 
-export const getChatContainerClass = (customClass?: string) =>
-  customClass ?? 'str-chat__container';
-
 export const useChannelContainerClasses = ({
   customClasses,
 }: Pick<ChatContextValue, 'customClasses'>) => {
   const windowsEmojiClass = useImageFlagEmojisOnWindowsClass();
   return {
     channelClass: customClasses?.channel ?? 'str-chat__channel',
     chatClass: customClasses?.chat ?? 'str-chat',
-    chatContainerClass: getChatContainerClass(customClasses?.chatContainer),
     windowsEmojiClass,
   };
 };

src/components/ChannelList/ChannelList.tsx

@@ -9,6 +9,7 @@ import { LoadingChannels, LoadingIndicator } from '../Loading';
 import { useChatContext } from '../../context/ChatContext';
 import { useComponentContext } from '../../context/ComponentContext';
 import { useTranslationContext } from '../../context/TranslationContext';
+import { ThemeScope } from '../../context/ThemeScopeContext';
 import { useChannelListKeyboardNavigation } from './hooks/useChannelListKeyboardNavigation';
 import { useStateStore } from '../../store';
 
@@ -82,24 +83,28 @@ export const ChannelList = ({
     });
   }, [client, lastQueryError]);
 
+  // Rendered on its own (no `ChannelNavigation` or `ChatView` above it), the list brings the theme
+  // scope with it.
   return (
-    <InfiniteScrollWithComponents<Channel>
-      aria-label={t('channelList.channelList.ariaLabel', 'Channel list')}
-      contentProps={{ role: 'presentation' }}
-      EmptyListIndicator={EmptyListIndicator}
-      EndReachedIndicator={EndReachedIndicator}
-      FirstPageLoadingIndicator={FirstPageLoadingIndicator}
-      ListItem={ListItem as ComponentType<{ item: Channel }>}
-      LoadingNextPageIndicator={LoadingNextPageIndicator}
-      loadNextDebounceMs={loadMoreDebounceMs}
-      loadNextOnScrollToBottom={paginator.next}
-      onClickCapture={onClickCapture}
-      onKeyDown={onKeyDown}
-      paginator={paginator}
-      ref={listboxRef}
-      role='listbox'
-      threshold={loadMoreThresholdPx}
-    />
+    <ThemeScope>
+      <InfiniteScrollWithComponents<Channel>
+        aria-label={t('channelList.channelList.ariaLabel', 'Channel list')}
+        contentProps={{ role: 'presentation' }}
+        EmptyListIndicator={EmptyListIndicator}
+        EndReachedIndicator={EndReachedIndicator}
+        FirstPageLoadingIndicator={FirstPageLoadingIndicator}
+        ListItem={ListItem as ComponentType<{ item: Channel }>}
+        LoadingNextPageIndicator={LoadingNextPageIndicator}
+        loadNextDebounceMs={loadMoreDebounceMs}
+        loadNextOnScrollToBottom={paginator.toTail}
+        onClickCapture={onClickCapture}
+        onKeyDown={onKeyDown}
+        paginator={paginator}
+        ref={listboxRef}
+        role='listbox'
+        threshold={loadMoreThresholdPx}
+      />
+    </ThemeScope>
   );
 };
 

src/components/ChannelList/ChannelNavigation.tsx

@@ -1,3 +1,4 @@
+import clsx from 'clsx';
 import React from 'react';
 import type { SearchControllerState } from 'stream-chat';
 
@@ -6,6 +7,12 @@ import { ChannelLists } from './ChannelLists';
 import { NotificationList as DefaultNotificationList } from '../Notifications';
 import { Search as DefaultSearch } from '../Search';
 import { useChatContext, useComponentContext } from '../../context';
+import {
+  ThemeScopeProvider,
+  useIsInThemeScope,
+  useThemeScopeClassName,
+} from '../../context/ThemeScopeContext';
+import { useImageFlagEmojisOnWindowsClass } from '../Channel/hooks/useChannelContainerClasses';
 import { useStateStore } from '../../store';
 
 const searchControllerStateSelector = (state: SearchControllerState) => ({
@@ -18,25 +25,41 @@ const searchControllerStateSelector = (state: SearchControllerState) => ({
  * always; results while active), then the paginator-driven `ChannelLists` only while
  * search is inactive. Mapped to the channel-navigation slot; `Search` is customizable
  * via the `ComponentContext` `Search` slot.
+ *
+ * Outside `ChatView` its root carries the `str-chat <theme>` scope itself, so the design tokens
+ * apply; inside one it inherits `ChatView`'s instead of resetting them with a nested scope.
+ * `customClasses.chat` / `customClasses.channelList` replace the `str-chat` /
+ * `str-chat__channel-list` classes.
  */
 export const ChannelNavigation = () => {
   const {
     ChannelListHeader = DefaultChannelListHeader,
     NotificationList = DefaultNotificationList,
     Search = DefaultSearch,
   } = useComponentContext();
-  const { searchController } = useChatContext();
+  const { customClasses, searchController } = useChatContext();
+  const isInThemeScope = useIsInThemeScope();
+  const themeScopeClassName = useThemeScopeClassName();
+  const windowsEmojiClass = useImageFlagEmojisOnWindowsClass();
   const { isActive } = useStateStore(
     searchController.state,
     searchControllerStateSelector,
   );
 
   return (
-    <div className='str-chat__channel-list'>
-      <ChannelListHeader />
-      <Search />
-      {!isActive && <ChannelLists />}
-      <NotificationList panel='channel-list' />
+    <div
+      className={clsx(
+        !isInThemeScope && themeScopeClassName,
+        customClasses?.channelList ?? 'str-chat__channel-list',
+        windowsEmojiClass,
+      )}
+    >
+      <ThemeScopeProvider>
+        <ChannelListHeader />
+        <Search />
+        {!isActive && <ChannelLists />}
+        <NotificationList panel='channel-list' />
+      </ThemeScopeProvider>
     </div>
   );
 };

src/components/ChannelList/__tests__/ChannelList.test.tsx

@@ -6,6 +6,7 @@ import { ChannelPaginator } from 'stream-chat';
 
 import { Chat } from '../../Chat';
 import { ChannelList } from '../ChannelList';
+import { ThemeScopeProvider } from '../../../context/ThemeScopeContext';
 import { getTestClientWithUser } from '../../../mock-builders';
 
 const setupClient = async () => {
@@ -28,6 +29,34 @@ const renderList = (client: StreamChat, paginator: ChannelPaginator) => {
 describe('ChannelList', () => {
   afterEach(cleanup);
 
+  it('brings a layout-neutral theme scope when rendered on its own', async () => {
+    const { client } = await setupClient();
+    const paginator = new ChannelPaginator({ client, id: 'channels:a' });
+    paginator.setItems({ isLastPage: true, valueOrFactory: [] });
+
+    const { container } = renderList(client, paginator);
+
+    const scope = container.firstElementChild;
+    expect(scope).toHaveClass('str-chat', 'messaging', 'light', 'str-chat__theme-scope');
+  });
+
+  it('adds no theme scope inside an existing one', async () => {
+    const { client } = await setupClient();
+    const paginator = new ChannelPaginator({ client, id: 'channels:a' });
+    paginator.setItems({ isLastPage: true, valueOrFactory: [] });
+    client.channelManager.insertPaginator({ paginator });
+
+    const { container } = render(
+      <Chat client={client}>
+        <ThemeScopeProvider>
+          <ChannelList paginator={paginator} />
+        </ThemeScopeProvider>
+      </Chat>,
+    );
+
+    expect(container.querySelector('.str-chat')).not.toBeInTheDocument();
+  });
+
   it('queries the first page of a list that has never been queried', async () => {
     const { client, queryChannels } = await setupClient();
     const paginator = new ChannelPaginator({ client, id: 'channels:a' });

src/components/ChannelList/__tests__/ChannelNavigation.test.tsx

@@ -0,0 +1,87 @@
+import React from 'react';
+import { cleanup, render } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { StreamChat } from 'stream-chat';
+
+import { Chat } from '../../Chat';
+import type { ChatProps } from '../../Chat';
+import { ChannelNavigation } from '../ChannelNavigation';
+import { ThemeScopeProvider } from '../../../context/ThemeScopeContext';
+import { getTestClientWithUser } from '../../../mock-builders';
+import { axe } from '../../../../axe-helper';
+
+const setupClient = async () => {
+  const client = await getTestClientWithUser({ id: 'user_x' });
+  // no paginator is registered, so nothing should query
+  vi.spyOn(client, 'queryChannelsAndHydrate').mockRejectedValue(
+    new Error('unexpected channel query'),
+  );
+  return client;
+};
+
+const renderNavigation = (
+  client: StreamChat,
+  chatProps: Partial<Omit<ChatProps, 'client'>> = {},
+) =>
+  render(
+    <Chat client={client} {...chatProps}>
+      <ChannelNavigation />
+    </Chat>,
+  );
+
+describe('ChannelNavigation', () => {
+  afterEach(cleanup);
+
+  it('carries the str-chat theme scope on its root outside ChatView', async () => {
+    const client = await setupClient();
+
+    const { container } = renderNavigation(client, { theme: 'str-chat__theme-dark' });
+
+    const root = container.firstElementChild;
+    expect(root).toHaveClass(
+      'str-chat',
+      'str-chat__theme-dark',
+      'str-chat__channel-list',
+    );
+  });
+
+  it('applies customClasses.chat and customClasses.channelList to its root', async () => {
+    const client = await setupClient();
+
+    const { container } = renderNavigation(client, {
+      customClasses: { channelList: 'custom-channel-list', chat: 'custom-chat' },
+    });
+
+    const root = container.firstElementChild;
+    expect(root).toHaveClass('custom-chat', 'custom-channel-list');
+    expect(root).not.toHaveClass('str-chat');
+    expect(root).not.toHaveClass('str-chat__channel-list');
+  });
+
+  it('inherits an enclosing theme scope (e.g. ChatView) instead of nesting one', async () => {
+    // `.str-chat` declares the whole token set: a nested one would reset tokens an app overrides
+    // on the ChatView root, and pick up app CSS written for `.str-chat` roots.
+    const client = await setupClient();
+
+    const { container } = render(
+      <Chat client={client} customClasses={{ channelList: 'custom-channel-list' }}>
+        <ThemeScopeProvider>
+          <ChannelNavigation />
+        </ThemeScopeProvider>
+      </Chat>,
+    );
+
+    const root = container.firstElementChild;
+    expect(root).toHaveClass('custom-channel-list');
+    expect(root).not.toHaveClass('str-chat');
+    expect(container.querySelector('.str-chat')).not.toBeInTheDocument();
+  });
+
+  it('has no axe violations', async () => {
+    const client = await setupClient();
+
+    const { container } = renderNavigation(client);
+
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

src/components/ChannelList/styling/ChannelList.scss

@@ -45,20 +45,6 @@
   color: var(--str-chat__text-primary);
   border-inline-end: 1px solid var(--str-chat__border-core-default);
 
-  .str-chat__channel-list-inner {
-    flex: 1;
-    min-height: 0;
-    overflow: hidden;
-    padding-bottom: calc(var(--str-chat__space-8) + var(--str-chat__space-2));
-
-    .str-chat__channel-list-inner__main {
-      height: 100%;
-      overflow-y: auto;
-      scrollbar-gutter: stable both-edges;
-      scrollbar-width: thin;
-    }
-  }
-
   .str-chat__load-more-button {
     display: flex;
     justify-content: center;

src/components/ChannelListItem/ChannelListItem.tsx

@@ -45,7 +45,7 @@ export type ChannelListItemUIProps = ChannelListItemProps & {
 };
 
 export type ChannelListItemProps = {
-  /** Comes from either the `channelRenderFilterFn` or `usePaginatedChannels` call from [ChannelList](https://github.com/GetStream/stream-chat-react/blob/master/src/components/ChannelList/ChannelList.tsx) */
+  /** The channel to preview: one of the items of the `ChannelPaginator` that [ChannelList](https://github.com/GetStream/stream-chat-react/blob/master/src/components/ChannelList/ChannelList.tsx) renders, or any channel when used on its own (e.g. in search results) */
   channel: Channel;
   /** If the component's channel is the active (selected) Channel */
   active?: boolean;

src/components/Gallery/GalleryContext.tsx

@@ -1,5 +1,5 @@
 import { createContext, useContext } from 'react';
-import type { UserResponse } from 'stream-chat';
+import type { LocalMessage, UserResponse } from 'stream-chat';
 
 import { requireContext } from '../../context/requireContext';
 import { toBaseImageDescriptors } from '../BaseImage';
@@ -11,6 +11,11 @@ export type GalleryItem = Omit<BaseImageProps, 'src'> & {
   createdAt?: string | Date;
   dimensions?: Dimensions;
   imageUrl?: string;
+  /**
+   * The message the media was shared in. Lets the gallery header render a `MessageTimestamp`
+   * override from `ComponentContext` for it.
+   */
+  message?: LocalMessage;
   /** User who shared the media; drives the gallery header title. */
   user?: UserResponse;
   videoThumbnailUrl?: string;

src/components/Gallery/GalleryHeader.tsx

@@ -6,6 +6,7 @@ import { Button } from '../Button';
 import {
   ModalContext,
   useChatContext,
+  useComponentContext,
   useComponentContextIcons,
   useTranslationContext,
 } from '../../context';
@@ -50,10 +51,11 @@ const GalleryTimestamp = ({ createdAt }: Pick<GalleryItem, 'createdAt'>) => {
 
 export const GalleryHeader = ({ currentItem }: GalleryHeaderProps) => {
   const { IconArrowDownCircle, IconXmark } = useComponentContextIcons();
+  const { MessageTimestamp } = useComponentContext();
   const { t } = useTranslationContext();
   const { client } = useChatContext();
   const modalContext = useContext(ModalContext);
-  const { createdAt, user } = currentItem;
+  const { createdAt, message, user } = currentItem;
 
   const headerTitle =
     (!!user?.id && user.id === client.userID && t('common.you.label', 'You')) ||
@@ -77,7 +79,14 @@ export const GalleryHeader = ({ currentItem }: GalleryHeaderProps) => {
       <div aria-hidden='true' className='str-chat__gallery__header-spacer' />
       <div className='str-chat__gallery__header-meta'>
         <div className='str-chat__gallery__title'>{headerTitle}</div>
-        <GalleryTimestamp createdAt={createdAt} />
+        {MessageTimestamp && message ? (
+          <MessageTimestamp
+            customClass='str-chat__gallery__timestamp'
+            message={message}
+          />
+        ) : (
+          <GalleryTimestamp createdAt={createdAt} />
+        )}
       </div>
       <div className='str-chat__gallery__header-actions'>
         {downloadUrl ? (