feat(a11y): improve keyboard and screen-reader support across composer, lists, search, and dialogs (#3230)

Author: MartinCupela

.cursor/skills/accessibility/SKILL.md

@@ -50,3 +50,12 @@ When importing from 'stream-chat' library, always import by library name (from '
 ## React components
 
 Try to avoid inline `style` attribute and prefer adding styles to `.scss` files.
+
+## How a plugin works in stream-chat-react
+
+A "plugin" is just a separate build entry point that ships as a subpath export (e.g. stream-chat-react/emojis, stream-chat-react/mp3-encoder). Concretely, each plugin is wired in 4 places:
+
+- Source folder — src/plugins/<Name>/ with an index.ts re-exporting its public API (see src/plugins/Emojis/index.ts).
+- Vite entry — a new key in build.lib.entry in vite.config.ts:20.
+- package.json — an exports subpath + a typesVersions entry (package.json:18,44).
+- Styling (optional) — a styling/index.scss added as a separate sass target in the build-styling script (package.json:185), producing its own CSS file like dist/css/emoji-picker.css.

.cursor/skills/dev-patterns/SKILL.md

@@ -5,37 +5,85 @@ import {
   CHANNEL_LIST_TARGET_ID,
   CHANNEL_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID,
   CHANNELS_SELECTOR_BUTTON_TARGET_QUERY,
+  THREAD_LIST_TARGET_ID,
+  THREAD_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID,
 } from '../ChatLayout/Panels.tsx';
 
 export const CHAT_SKIP_NAVIGATION_TARGET_ID = 'app-chat-skip-navigation';
 
+// The list skip-link should land on the FIRST item (a focusable role="option" button with a visible
+// focus ring), not on the listbox container — focusing a container gives no visual focus cue.
+// Returns whether an option was actually focused: an empty/loading list has no `role="option"`, in
+// which case the caller must NOT preventDefault, letting SkipNavigation fall back to focusing the
+// list container (otherwise the link would be a dead end).
+const focusFirstListOption = (listTargetId: string): boolean => {
+  const option = document.querySelector<HTMLElement>(`#${listTargetId} [role="option"]`);
+  option?.focus();
+  return !!option;
+};
+
+const isLinkFor = (target: EventTarget | null, targetId: string) =>
+  target instanceof HTMLAnchorElement && target.getAttribute('href') === `#${targetId}`;
+
+const isActivationKey = (key: string) =>
+  key === 'Enter' || key === ' ' || key === 'Spacebar';
+
 const getSkipNavigationLinkLabel = (targetId: string) => {
-  if (targetId === CHANNEL_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID) {
+  if (
+    targetId === CHANNEL_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID ||
+    targetId === THREAD_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID
+  ) {
     return 'Skip to message composer';
   }
   if (targetId === CHANNEL_LIST_TARGET_ID) {
     return 'Skip to channel list';
   }
+  if (targetId === THREAD_LIST_TARGET_ID) {
+    return 'Skip to thread list';
+  }
 
   return 'Skip to sidebar';
 };
 
 export const ChatSkipNavigation = () => {
-  const [channelsSelectorButtonTargetId, setChannelsSelectorButtonTargetId] = useState<
-    string | null
-  >(null);
+  // Skip targets are tagged imperatively onto SDK-owned DOM and depend on the active view (the
+  // channel list shows in the channels view, the thread list in the threads view) and the layout, so
+  // resolve them from the live DOM and keep them in sync via a MutationObserver. Only links whose
+  // target currently exists are rendered, so there are never dead skip links.
+  const [composerTargetId, setComposerTargetId] = useState<string | null>(null);
+  const [listTargetId, setListTargetId] = useState<string | null>(null);
+  const [selectorButtonTargetId, setSelectorButtonTargetId] = useState<string | null>(
+    null,
+  );
 
   useEffect(() => {
-    const syncChannelsSelectorButtonTargetId = () => {
-      const channelsSelectorButton = document.querySelector<HTMLElement>(
-        CHANNELS_SELECTOR_BUTTON_TARGET_QUERY,
+    const syncTargets = () => {
+      // The channel composer (channels view) and the thread composer (threads view) carry different
+      // ids; whichever is currently mounted is the composer skip target.
+      setComposerTargetId(
+        document.getElementById(CHANNEL_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID)
+          ? CHANNEL_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID
+          : document.getElementById(THREAD_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID)
+            ? THREAD_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID
+            : null,
+      );
+      // Exactly one of the two lists is mounted at a time, depending on the active view.
+      setListTargetId(
+        document.getElementById(THREAD_LIST_TARGET_ID)
+          ? THREAD_LIST_TARGET_ID
+          : document.getElementById(CHANNEL_LIST_TARGET_ID)
+            ? CHANNEL_LIST_TARGET_ID
+            : null,
+      );
+      setSelectorButtonTargetId(
+        document.querySelector<HTMLElement>(CHANNELS_SELECTOR_BUTTON_TARGET_QUERY)?.id ??
+          null,
       );
-      setChannelsSelectorButtonTargetId(channelsSelectorButton?.id ?? null);
     };
 
-    syncChannelsSelectorButtonTargetId();
+    syncTargets();
 
-    const observer = new MutationObserver(syncChannelsSelectorButtonTargetId);
+    const observer = new MutationObserver(syncTargets);
     observer.observe(document.body, {
       attributes: true,
       attributeFilter: ['id'],
@@ -46,22 +94,39 @@ export const ChatSkipNavigation = () => {
     return () => observer.disconnect();
   }, []);
 
-  const targetIds = useMemo(() => {
-    const skipTargets = [
-      CHANNEL_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID,
-      CHANNEL_LIST_TARGET_ID,
-    ];
-
-    if (channelsSelectorButtonTargetId) {
-      skipTargets.push(channelsSelectorButtonTargetId);
-    }
-
-    return skipTargets;
-  }, [channelsSelectorButtonTargetId]);
+  // Ordered by keyboard priority: composer, then the active list, then the sidebar selector.
+  const targetIds = useMemo(
+    () =>
+      [composerTargetId, listTargetId, selectorButtonTargetId].filter(
+        (id): id is string => !!id,
+      ),
+    [composerTargetId, listTargetId, selectorButtonTargetId],
+  );
 
   return (
     <nav aria-label='Chat quick navigation' id={CHAT_SKIP_NAVIGATION_TARGET_ID}>
-      <SkipNavigation getLinkLabel={getSkipNavigationLinkLabel} targetIds={targetIds} />
+      <SkipNavigation
+        getLinkLabel={getSkipNavigationLinkLabel}
+        // Intercept the active list link (SkipNavigation's documented `onClick`/`onKeyDown` +
+        // `preventDefault` escape hatch) to focus the first item instead of the listbox container.
+        // Other links fall through to SkipNavigation's default focus handling.
+        onClick={(event) => {
+          if (!listTargetId || !isLinkFor(event.currentTarget, listTargetId)) return;
+          // Only take over when there is an option to focus; otherwise let SkipNavigation focus the
+          // list container so the link is never a dead end.
+          if (focusFirstListOption(listTargetId)) event.preventDefault();
+        }}
+        onKeyDown={(event) => {
+          if (
+            !listTargetId ||
+            !isLinkFor(event.currentTarget, listTargetId) ||
+            !isActivationKey(event.key)
+          )
+            return;
+          if (focusFirstListOption(listTargetId)) event.preventDefault();
+        }}
+        targetIds={targetIds}
+      />
     </nav>
   );
 };

examples/vite/src/AccessibilityNavigation/ChatSkipNavigation.tsx

@@ -69,6 +69,7 @@ import {
 } from './CustomMessageUi';
 import { ConfigurableMessageActions } from './CustomMessageActions';
 import { SidebarToggle } from './Sidebar/SidebarToggle.tsx';
+import { CommandModeAttachmentSelector } from './CommandModeAttachmentSelector.tsx';
 
 const PUBLIC_VITE_EXAMPLE_API_KEY = 'xzwhhgtazy6h';
 
@@ -97,6 +98,12 @@ if (!apiKey) {
   throw new Error('VITE_STREAM_API_KEY is not defined');
 }
 
+const options: ChannelOptions = {
+  presence: true,
+  state: true,
+  limit: 10,
+};
+
 const sort: ChannelSort = { last_message_at: -1, updated_at: -1 };
 
 // @ts-expect-error ai_generated isn't on LocalMessage's public type yet
@@ -225,18 +232,6 @@ const App = () => {
     () => new URLSearchParams(window.location.search),
     [],
   );
-  const options = useMemo<ChannelOptions>(
-    () => ({
-      // filter_values: {
-      //   user_id: userId,
-      // },
-      // predefined_filter: 'livestreams_channels',
-      presence: true,
-      state: true,
-      limit: 10,
-    }),
-    [],
-  );
   const initialChannelId = useMemo(() => getSelectedChannelIdFromUrl(), []);
   const initialChatView = useMemo(() => getSelectedChatViewFromUrl(), []);
   const initialThreadId = useMemo(
@@ -428,6 +423,7 @@ const App = () => {
         HeaderEndContent: SidebarToggle,
         HeaderStartContent: SidebarToggle,
         MessageActions: ConfigurableMessageActions,
+        AttachmentSelector: CommandModeAttachmentSelector,
         ...messageUiOverrides,
       }}
     >

examples/vite/src/App.tsx

@@ -69,6 +69,7 @@ export const ChannelPreviewOverlay = () => {
         {canJoin && (
           <Button
             appearance='solid'
+            autoFocus
             className='app-channel-preview-overlay__join-button'
             disabled={joining}
             onClick={handleJoin}

examples/vite/src/ChannelPreviewOverlay/ChannelPreviewOverlay.tsx

@@ -9,6 +9,7 @@ import {
   ChannelList,
   ChatView,
   type ChatViewSelectorEntry,
+  MessageComposerUI as DefaultMessageComposerUI,
   MessageComposer,
   MessageList,
   Thread,
@@ -34,10 +35,33 @@ import { ThreadStateSync } from './Sync.tsx';
 
 export const CHANNEL_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID =
   'app-channel-message-composer-textarea';
+export const THREAD_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID =
+  'app-thread-message-composer-textarea';
 export const CHANNEL_LIST_TARGET_ID = 'app-channel-list';
+export const THREAD_LIST_TARGET_ID = 'app-thread-list';
 export const CHANNELS_SELECTOR_BUTTON_TARGET_QUERY =
   '[id^="str-chat__chat-view-"][id$="-tab-channels"]';
 
+// Tag the list's `[role="listbox"]` with a stable id so the skip-navigation links can target it. The
+// listbox unmounts/remounts (search mode, view switches, reloads) and its view may start inactive, so
+// observe `document.body` and re-tag whenever it (re)appears. The selector is globally unambiguous —
+// only one view's sidebar is mounted at a time.
+const useTagSkipNavigationListbox = (listboxSelector: string, targetId: string) => {
+  useEffect(() => {
+    const tagListbox = () => {
+      const listbox = document.querySelector<HTMLElement>(listboxSelector);
+      if (listbox && listbox.id !== targetId) {
+        listbox.id = targetId;
+      }
+    };
+
+    tagListbox();
+    const observer = new MutationObserver(tagListbox);
+    observer.observe(document.body, { childList: true, subtree: true });
+    return () => observer.disconnect();
+  }, [listboxSelector, targetId]);
+};
+
 const ChannelThreadPanel = () => {
   const { thread } = useChannelStateContext('ChannelThreadPanel');
   const isOpen = !!thread;
@@ -92,6 +116,7 @@ const ResponsiveChannelPanels = () => {
               asyncMessagesMultiSendEnabled
               audioRecordingEnabled
               maxRows={10}
+              focus
             />
             <ChannelPreviewOverlay />
           </div>
@@ -127,14 +152,10 @@ export const ChannelsPanels = ({
     closeSidebar();
   }, [channel?.id, closeSidebar]);
 
-  useEffect(() => {
-    const channelListElement = channelsLayoutRef.current?.querySelector<HTMLElement>(
-      '.app-chat-sidebar-overlay > .str-chat__channel-list',
-    );
-    if (!channelListElement) return;
-
-    channelListElement.id = CHANNEL_LIST_TARGET_ID;
-  }, [channel?.id, sidebarOpen]);
+  useTagSkipNavigationListbox(
+    '.app-chat-sidebar-overlay .str-chat__channel-list-inner__main',
+    CHANNEL_LIST_TARGET_ID,
+  );
 
   return (
     <ChatView.Channels>
@@ -173,6 +194,16 @@ export const ChannelsPanels = ({
   );
 };
 
+// Renders the "Back to quick navigation" return link above the thread's composer (the SDK renders
+// the thread composer internally, so we inject via the MessageComposerUI slot) — matching the
+// channel view, where the link sits right above <MessageComposer />.
+const ThreadMessageComposerUI = () => (
+  <>
+    <ReturnToSkipNavigation />
+    <DefaultMessageComposerUI />
+  </>
+);
+
 export const ThreadsPanels = ({
   iconOnly,
   itemSet,
@@ -184,6 +215,11 @@ export const ThreadsPanels = ({
   const { activeThread } = useThreadsViewContext();
   const threadsLayoutRef = useRef<HTMLDivElement | null>(null);
 
+  useTagSkipNavigationListbox(
+    '.app-chat-sidebar-overlay .str-chat__thread-list',
+    THREAD_LIST_TARGET_ID,
+  );
+
   return (
     <ChatView.Threads>
       <ThreadStateSync />
@@ -202,12 +238,21 @@ export const ThreadsPanels = ({
         <div className='app-chat-view__threads-main'>
           <ChatView.ThreadAdapter>
             <WithDragAndDropUpload className='str-chat__dropzone-root--thread'>
-              <WithComponents overrides={{ TypingIndicator }}>
-                <ReturnToSkipNavigation />
+              <WithComponents
+                overrides={{
+                  MessageComposerUI: ThreadMessageComposerUI,
+                  TypingIndicator,
+                }}
+              >
                 <Thread
                   additionalMessageComposerProps={{
+                    additionalTextareaProps: {
+                      id: THREAD_MESSAGE_COMPOSER_TEXTAREA_TARGET_ID,
+                    },
                     audioRecordingEnabled: true,
                     asyncMessagesMultiSendEnabled: true,
+                    // Auto-focus the thread composer on mount, matching the channels-view composer.
+                    focus: true,
                   }}
                   virtualized
                 />

examples/vite/src/ChatLayout/Panels.tsx

@@ -0,0 +1,28 @@
+import type { TextComposerState } from 'stream-chat';
+import {
+  type AttachmentSelectorProps,
+  AttachmentSelector as DefaultAttachmentSelector,
+  useMessageComposerController,
+  useStateStore,
+} from 'stream-chat-react';
+
+const textComposerCommandSelector = ({ command }: TextComposerState) => ({ command });
+
+export const CommandModeAttachmentSelector = (props: AttachmentSelectorProps) => {
+  const messageComposer = useMessageComposerController();
+  const { command } = useStateStore(
+    messageComposer.textComposer.state,
+    textComposerCommandSelector,
+  );
+
+  return (
+    <DefaultAttachmentSelector
+      {...props}
+      // In command mode, keyboard flow should stay in command controls + textarea.
+      // Removing the attachment trigger from tab order avoids an irrelevant stop.
+      // Spread any incoming buttonProps first so ARIA/data props aren't dropped when this override
+      // is wired globally via WithComponents.
+      buttonProps={{ ...props.buttonProps, tabIndex: command ? -1 : undefined }}
+    />
+  );
+};

examples/vite/src/CommandModeAttachmentSelector.tsx

@@ -66,6 +66,7 @@ export const PublicChannelOverlay = () => {
         </div>
         <Button
           appearance='solid'
+          autoFocus
           className='app-public-channel-overlay__join-button'
           disabled={joining}
           onClick={handleJoin}
@@ -78,17 +79,3 @@ export const PublicChannelOverlay = () => {
     </div>
   );
 };
-
-export const PublicChannelComposerBanner = () => {
-  const { canJoin, isMember } = usePublicChannelState();
-
-  if (isMember || canJoin) return null;
-
-  return (
-    <div className='app-public-channel-composer-banner'>
-      <p className='app-public-channel-composer-banner__text'>
-        You can only view this conversation
-      </p>
-    </div>
-  );
-};