feat(emojis): add StreamEmojiPicker compound components + useEmojiPickerContext

Expose the built-in emoji picker as compound components so integrators can rearrange or
replace parts, while `StreamEmojiPicker` (called directly) stays the unchanged zero-config
preset built on top of them.

- Add `StreamEmojiPicker.Root` (provider + dialog container owning dataset load, filtering,
  search, and container-level a11y — dialog role, Escape-to-close, theme class) and the
  slots `StreamEmojiPicker.Nav` / `.Search` / `.Grid` / `.Preview` / `.SkinTone`.
- Expose `useEmojiPickerContext()` with the public contract: read-only data (`categories`,
  `searchResults`, `status`, `skinTones`, `resolveNative`) and report-back setters
  (`selectEmoji`, `setQuery`, `setSkinTone`, `setActiveCategory`, `requestScrollToCategory`).
  Hover-preview state lives in an internal, non-exported context so it doesn't re-render the
  grid and a custom grid doesn't implicitly drive the default preview.
- Convert each slot from prop-driven to context-driven; `EmojiPickerPanel` becomes the
  default composition. Behavior, a11y, keyboard nav, virtualization, and bundle optionality
  are unchanged — all pre-existing tests stay green.
- `autoFocus` moves to the panel's own props (it's a search behavior), so `Root` no longer
  advertises a prop it ignores.

Author: oliverlaz

src/plugins/Emojis/StreamEmojiPicker.tsx

@@ -9,7 +9,13 @@ import {
 } from '../../components';
 import { usePopoverPosition } from '../../components/Dialog/hooks/usePopoverPosition';
 import { useIsCooldownActive } from '../../components/MessageComposer/hooks/useIsCooldownActive';
-import { EmojiPickerPanel } from './components';
+import { CategoryNav } from './components/CategoryNav';
+import { EmojiGrid } from './components/EmojiGrid';
+import { EmojiPickerPanel } from './components/EmojiPickerPanel';
+import { EmojiPickerRoot } from './components/EmojiPickerRoot';
+import { PreviewPane } from './components/PreviewPane';
+import { SearchInput } from './components/SearchInput';
+import { SkinToneSelector } from './components/SkinToneSelector';
 import { useFrequentlyUsedEmoji } from './hooks/useFrequentlyUsedEmoji';
 import { useSkinTone } from './hooks/useSkinTone';
 
@@ -61,7 +67,7 @@ const classNames: Pick<
   wrapperClassName: 'str-chat__message-textarea-emoji-picker',
 };
 
-export const StreamEmojiPicker = (props: StreamEmojiPickerProps) => {
+const StreamEmojiPickerComponent = (props: StreamEmojiPickerProps) => {
   const { t } = useTranslationContext('EmojiPicker');
   const { textareaRef } = useMessageComposerContext('EmojiPicker');
   const { textComposer } = useMessageComposerController();
@@ -179,3 +185,18 @@ export const StreamEmojiPicker = (props: StreamEmojiPickerProps) => {
     </div>
   );
 };
+
+/**
+ * The built-in emoji picker. Rendered directly, it is the batteries-included preset
+ * (toggle button + popover + the standard panel). For a custom layout, compose the parts
+ * — `StreamEmojiPicker.Root` wrapping any arrangement of `.Nav` / `.Search` / `.Grid` /
+ * `.Preview` / `.SkinTone` (and your own slots via `useEmojiPickerContext`).
+ */
+export const StreamEmojiPicker = Object.assign(StreamEmojiPickerComponent, {
+  Grid: EmojiGrid,
+  Nav: CategoryNav,
+  Preview: PreviewPane,
+  Root: EmojiPickerRoot,
+  Search: SearchInput,
+  SkinTone: SkinToneSelector,
+});

src/plugins/Emojis/__tests__/StreamEmojiPicker.test.tsx

@@ -5,7 +5,7 @@ import { fireEvent, render, screen } from '@testing-library/react';
 // stub. This lets us assert that the owner (EmojiPicker) preserves skin tone and
 // frequently-used across open/close — without depending on the real panel's
 // virtualized grid + async data load, which don't render reliably in jsdom.
-vi.mock('../components', () => ({
+vi.mock('../components/EmojiPickerPanel', () => ({
   EmojiPickerPanel: ({
     frequentlyUsedIds = [],
     onEmojiSelect,

src/plugins/Emojis/__tests__/entry-exports.test.ts

@@ -1,8 +1,23 @@
 import * as emojis from '../index';
+import { StreamEmojiPicker } from '../StreamEmojiPicker';
 
 describe('emojis entry exports', () => {
   it('exports both the deprecated EmojiPicker and the StreamEmojiPicker successor', () => {
     expect(typeof emojis.EmojiPicker).toBe('function');
     expect(typeof emojis.StreamEmojiPicker).toBe('function');
   });
+
+  it('exposes the compound API + context hook', () => {
+    expect(typeof emojis.useEmojiPickerContext).toBe('function');
+    for (const part of [
+      'Grid',
+      'Nav',
+      'Preview',
+      'Root',
+      'Search',
+      'SkinTone',
+    ] as const) {
+      expect(typeof StreamEmojiPicker[part]).toBe('function');
+    }
+  });
 });

src/plugins/Emojis/components/CategoryNav.tsx

@@ -1,28 +1,23 @@
 import { type KeyboardEvent, useRef } from 'react';
 import clsx from 'clsx';
 import { EMOJI_CATEGORY_META } from './categories';
-import type { EmojiPickerCategory } from './EmojiGrid';
-
-export type CategoryNavProps = {
-  categories: EmojiPickerCategory[];
-  onNavigate: (categoryId: string) => void;
-  activeCategoryId?: string;
-};
+import { useEmojiPickerContext } from '../context/EmojiPickerContext';
 
 const NAV_KEYS = ['ArrowRight', 'ArrowLeft', 'Home', 'End'];
 
 /**
  * Top navigation bar with one tab per category (role="tablist"). Clicking a tab
  * scrolls its section into view; Left/Right/Home/End move focus between tabs with a
- * roving tabindex; the active tab reflects the currently visible section.
+ * roving tabindex; the active tab reflects the currently visible section. Reads the
+ * category model + active category from context and reports clicks via
+ * `requestScrollToCategory`. The active tab is suppressed during search.
  */
-export const CategoryNav = ({
-  activeCategoryId,
-  categories,
-  onNavigate,
-}: CategoryNavProps) => {
+export const CategoryNav = () => {
+  const { activeCategoryId, categories, isSearching, requestScrollToCategory } =
+    useEmojiPickerContext('CategoryNav');
   const navRef = useRef<HTMLDivElement>(null);
-  const rovingId = activeCategoryId ?? categories[0]?.id;
+  const active = isSearching ? undefined : activeCategoryId;
+  const rovingId = active ?? categories[0]?.id;
 
   const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
     if (!NAV_KEYS.includes(event.key)) return;
@@ -51,13 +46,12 @@ export const CategoryNav = ({
       {categories.map(({ id, label }) => (
         <button
           aria-label={label}
-          aria-selected={activeCategoryId === id}
+          aria-selected={active === id}
           className={clsx('str-chat__emoji-picker__category-nav-button', {
-            'str-chat__emoji-picker__category-nav-button--active':
-              activeCategoryId === id,
+            'str-chat__emoji-picker__category-nav-button--active': active === id,
           })}
           key={id}
-          onClick={() => onNavigate(id)}
+          onClick={() => requestScrollToCategory(id)}
           role='tab'
           tabIndex={id === rovingId ? 0 : -1}
           type='button'

src/plugins/Emojis/components/EmojiButton.tsx

@@ -1,5 +1,6 @@
 import { memo } from 'react';
 import { useEmojiPickerContext } from '../context/EmojiPickerContext';
+import { useEmojiPickerPreviewContext } from '../context/EmojiPickerPreviewContext';
 import type { EmojiDataEmoji } from '../data';
 
 export type EmojiButtonProps = {
@@ -11,16 +12,15 @@ export type EmojiButtonProps = {
  * skin tone. Memoized because the grid can render ~1800 of these.
  */
 export const EmojiButton = memo(function EmojiButton({ emoji }: EmojiButtonProps) {
-  const { onSelectEmoji, setPreviewedEmoji, skinToneIndex } =
-    useEmojiPickerContext('EmojiButton');
-  const native = emoji.skins[skinToneIndex]?.native ?? emoji.skins[0]?.native ?? '';
+  const { resolveNative, selectEmoji } = useEmojiPickerContext('EmojiButton');
+  const { setPreviewedEmoji } = useEmojiPickerPreviewContext();
 
   return (
     <button
       aria-label={emoji.name}
       className='str-chat__emoji-picker__emoji'
       data-emoji-id={emoji.id}
-      onClick={() => onSelectEmoji(emoji)}
+      onClick={() => selectEmoji(emoji)}
       onFocus={() => setPreviewedEmoji(emoji)}
       onMouseEnter={() => setPreviewedEmoji(emoji)}
       // Native <button> semantics (not role='gridcell'): the category view is
@@ -29,7 +29,7 @@ export const EmojiButton = memo(function EmojiButton({ emoji }: EmojiButtonProps
       tabIndex={-1}
       type='button'
     >
-      {native}
+      {resolveNative(emoji)}
     </button>
   );
 });

src/plugins/Emojis/components/EmojiGrid.tsx

@@ -1,6 +1,9 @@
-import { forwardRef, useImperativeHandle, useRef } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { Virtuoso, type VirtuosoHandle } from 'react-virtuoso';
 import { EmojiButton } from './EmojiButton';
+import { EmptyResults } from './EmptyResults';
+import { useEmojiPickerContext } from '../context/EmojiPickerContext';
+import { useGridKeyboardNav } from '../hooks/useGridKeyboardNav';
 import type { EmojiDataEmoji } from '../data';
 
 export type EmojiPickerCategory = {
@@ -9,15 +12,6 @@ export type EmojiPickerCategory = {
   label: string;
 };
 
-export type EmojiGridHandle = {
-  scrollToCategory: (categoryId: string) => void;
-};
-
-export type EmojiGridProps = {
-  categories: EmojiPickerCategory[];
-  onActiveCategoryChange?: (categoryId: string) => void;
-};
-
 const CategorySection = ({ category }: { category: EmojiPickerCategory }) => (
   <section
     aria-label={category.label}
@@ -36,51 +30,80 @@ const CategorySection = ({ category }: { category: EmojiPickerCategory }) => (
 );
 
 /**
- * The category-grouped emoji grid. Virtualized at the category level with
- * react-virtuoso: only the categories in (and near) the viewport are mounted, which
- * keeps opening the picker fast without giving up section headers, scroll-spy, or
- * per-category scrolling. `scrollToCategory` is exposed imperatively for the nav.
+ * The context-driven body of the picker: while browsing, a category-grouped grid,
+ * virtualized at the category level with react-virtuoso (only categories in/near the
+ * viewport mount); while searching, a flat result list or the empty state. Scrolls to
+ * the category named by `scrollTarget`, reports the visible category via
+ * `setActiveCategory` (scroll-spy), and owns 2D roving keyboard navigation over its
+ * cells. A custom Grid slot forfeits these mechanics but keeps reading the same context.
  */
-export const EmojiGrid = forwardRef<EmojiGridHandle, EmojiGridProps>(function EmojiGrid(
-  { categories, onActiveCategoryChange },
-  ref,
-) {
+export const EmojiGrid = () => {
+  const { categories, isSearching, scrollTarget, searchResults, setActiveCategory } =
+    useEmojiPickerContext('EmojiGrid');
   const virtuosoRef = useRef<VirtuosoHandle>(null);
   const atBottomRef = useRef(false);
+  const bodyRef = useRef<HTMLDivElement>(null);
 
-  useImperativeHandle(
-    ref,
-    () => ({
-      scrollToCategory: (categoryId: string) => {
-        const index = categories.findIndex((category) => category.id === categoryId);
-        if (index >= 0) virtuosoRef.current?.scrollToIndex({ align: 'start', index });
-      },
-    }),
+  const scrollToCategory = useCallback(
+    (categoryId: string) => {
+      const index = categories.findIndex((category) => category.id === categoryId);
+      if (index >= 0) virtuosoRef.current?.scrollToIndex({ align: 'start', index });
+    },
     [categories],
   );
 
+  // Nav clicks (and any consumer) request a scroll via `scrollTarget`; the nonce makes a
+  // repeat request to the same category re-fire.
+  useEffect(() => {
+    if (scrollTarget) scrollToCategory(scrollTarget.categoryId);
+  }, [scrollTarget, scrollToCategory]);
+
+  // Keyboard nav can target a category that virtualization has unmounted; give it the
+  // category order + a way to scroll one into view so focus can traverse the whole set.
+  const { onKeyDown } = useGridKeyboardNav(bodyRef, { categories, scrollToCategory });
+
+  if (isSearching) {
+    return (
+      <div className='str-chat__emoji-picker__body' onKeyDown={onKeyDown} ref={bodyRef}>
+        {searchResults && searchResults.length ? (
+          <div className='str-chat__emoji-picker__grid-container'>
+            <div className='str-chat__emoji-picker__grid'>
+              <div className='str-chat__emoji-picker__category-emojis'>
+                {searchResults.map((emoji) => (
+                  <EmojiButton emoji={emoji} key={emoji.id} />
+                ))}
+              </div>
+            </div>
+          </div>
+        ) : (
+          <EmptyResults />
+        )}
+      </div>
+    );
+  }
+
   return (
-    <Virtuoso
-      atBottomStateChange={(atBottom) => {
-        atBottomRef.current = atBottom;
-        // The last category is often short and never reaches the top of the viewport,
-        // so scroll-spy alone would never mark it active — pin it while at the bottom.
-        if (atBottom) {
+    <div className='str-chat__emoji-picker__body' onKeyDown={onKeyDown} ref={bodyRef}>
+      <Virtuoso
+        atBottomStateChange={(atBottom) => {
+          atBottomRef.current = atBottom;
+          // The last category is often short and never reaches the top of the viewport,
+          // so scroll-spy alone would never mark it active — pin it while at the bottom.
           const last = categories[categories.length - 1];
-          if (last) onActiveCategoryChange?.(last.id);
-        }
-      }}
-      className='str-chat__emoji-picker__grid'
-      data={categories}
-      itemContent={(_index, category) => <CategorySection category={category} />}
-      rangeChanged={({ startIndex }) => {
-        // While pinned at the bottom, atBottomStateChange owns the active category.
-        if (atBottomRef.current) return;
-        const category = categories[startIndex];
-        if (category) onActiveCategoryChange?.(category.id);
-      }}
-      ref={virtuosoRef}
-      style={{ height: '100%' }}
-    />
+          if (atBottom && last) setActiveCategory(last.id);
+        }}
+        className='str-chat__emoji-picker__grid'
+        data={categories}
+        itemContent={(_index, category) => <CategorySection category={category} />}
+        rangeChanged={({ startIndex }) => {
+          // While pinned at the bottom, atBottomStateChange owns the active category.
+          if (atBottomRef.current) return;
+          const category = categories[startIndex];
+          if (category) setActiveCategory(category.id);
+        }}
+        ref={virtuosoRef}
+        style={{ height: '100%' }}
+      />
+    </div>
   );
-});
+};