docs(emojis): document StreamEmojiPicker composition + add a composed-grid example

- AI.md: add a composition section (`StreamEmojiPicker.Root` + slots +
  `useEmojiPickerContext`), the "SDK owns data + selection; you own presentation +
  behavior" rule, and a paged-grid example.
- vite example: add a "Stream (composed)" engine option that assembles the picker from
  `StreamEmojiPicker.Root` + the built-in nav/search/preview/skin-tone with a custom
  `PagedGrid`, demonstrating built-in-Nav + custom-Grid interop through shared state.

Author: oliverlaz

AI.md

@@ -285,6 +285,60 @@ import 'stream-chat-react/css/emoji-picker.css';
   picker — keep using the deprecated `EmojiPicker` if you still need them. Try it live in
   the "Emoji Picker" settings tab of `examples/vite/`.
 
+- **Custom layouts (composition).** For a non-standard arrangement, or to replace a part,
+  compose the picker from its slots instead of rearranging props. Rendered directly,
+  `StreamEmojiPicker` is the preset; `StreamEmojiPicker.Root` + the slots let you assemble
+  it yourself:
+
+  ```tsx
+  import { StreamEmojiPicker, useEmojiPickerContext } from 'stream-chat-react/emojis';
+
+  <StreamEmojiPicker.Root onEmojiSelect={insert}>
+    <StreamEmojiPicker.Nav />
+    <StreamEmojiPicker.Search />
+    <StreamEmojiPicker.Grid />
+    <StreamEmojiPicker.SkinTone />
+  </StreamEmojiPicker.Root>;
+  ```
+
+  The rule: **the SDK owns the data + the selection; you own presentation + behavior.**
+  `Root` exposes everything through `useEmojiPickerContext()` — read-only data
+  (`categories`, `searchResults`, `status`, `skinTones`, `resolveNative`) and report-back
+  setters (`selectEmoji`, `setQuery`, `setSkinTone`, `setActiveCategory` /
+  `requestScrollToCategory`). A custom slot is just a component that calls the hook; when
+  you replace a slot, that slot's mechanics (scrolling, scroll-spy, roving keyboard, ARIA,
+  virtualization, hover-preview) become yours, but it keeps talking to the others through
+  the shared state. Example — a paged grid driven by the built-in `Nav`:
+
+  ```tsx
+  function PagedGrid() {
+    const {
+      categories,
+      activeCategoryId,
+      searchResults,
+      isSearching,
+      selectEmoji,
+      resolveNative,
+    } = useEmojiPickerContext();
+    const emojis = isSearching
+      ? (searchResults ?? [])
+      : ((categories.find((c) => c.id === activeCategoryId) ?? categories[0])?.emojis ??
+        []);
+    return (
+      <div>
+        {emojis.map((e) => (
+          <button key={e.id} onClick={() => selectEmoji(e)}>
+            {resolveNative(e)}
+          </button>
+        ))}
+      </div>
+    );
+  }
+  ```
+
+  `Root` always keeps the container-level a11y (dialog role, Escape-to-close,
+  focus-return) and the loading/error states, regardless of how you recompose the inside.
+
 - To let users **react with any emoji** (the reaction selector's `+` button), fill
   `reactionOptions.extended` with the full emoji set. It also gates display — a reaction
   whose type isn't in `quick`/`extended` is not rendered. Load it lazily from the emojis

examples/vite/src/AppSettings/state.ts

@@ -13,7 +13,7 @@ export type ChatViewSettingsState = {
 
 export type EmojiPickerSettingsState = {
   autoFocus: boolean;
-  engine: 'emoji-mart' | 'stream';
+  engine: 'emoji-mart' | 'stream' | 'stream-composed';
 };
 
 // Mirrors the SDK's EmojiPicker defaults; the settings tab resets to this.

examples/vite/src/AppSettings/tabs/EmojiPicker/EmojiPickerTab.tsx

@@ -1,7 +1,12 @@
 import EmojiMartPickerImport from '@emoji-mart/react';
 import { type ComponentType, useState } from 'react';
 import { Button } from 'stream-chat-react';
-import { EmojiPickerPanel, type EmojiSelection } from 'stream-chat-react/emojis';
+import {
+  EmojiPickerPanel,
+  type EmojiSelection,
+  StreamEmojiPicker,
+  useEmojiPickerContext,
+} from 'stream-chat-react/emojis';
 import {
   appSettingsStore,
   DEFAULT_EMOJI_PICKER_SETTINGS,
@@ -62,17 +67,62 @@ function Field<T extends string | number | boolean>({
   );
 }
 
+/**
+ * A custom "paged" grid slot — renders only the active category (a layout the default
+ * scrolling grid can't do), driven entirely by context: it reads `activeCategoryId`
+ * (which the built-in Nav sets) and reports selection via `selectEmoji`. Demonstrates
+ * that a replacement slot only needs the SDK's data + report-back APIs.
+ */
+const PagedGrid = () => {
+  const {
+    activeCategoryId,
+    categories,
+    isSearching,
+    resolveNative,
+    searchResults,
+    selectEmoji,
+  } = useEmojiPickerContext();
+  const emojis = isSearching
+    ? (searchResults ?? [])
+    : ((categories.find((category) => category.id === activeCategoryId) ?? categories[0])
+        ?.emojis ?? []);
+
+  return (
+    <div className='str-chat__emoji-picker__body'>
+      <div className='str-chat__emoji-picker__grid'>
+        <div className='str-chat__emoji-picker__category-emojis'>
+          {emojis.map((emoji) => (
+            <button
+              className='str-chat__emoji-picker__emoji'
+              key={emoji.id}
+              onClick={() => selectEmoji(emoji)}
+              type='button'
+            >
+              {resolveNative(emoji)}
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+};
+
 /**
  * Always-open picker wired to the current settings, so tweaks show instantly without
  * opening the composer. Skin tone and frequently-used are local to the preview —
- * selecting an emoji here feeds the "frequently used" row.
+ * selecting an emoji here feeds the "frequently used" row. The `stream-composed` engine
+ * shows the same picker assembled from `StreamEmojiPicker.Root` + slots, swapping in the
+ * custom `PagedGrid` while keeping the built-in nav/search/preview/skin-tone.
  */
 const EmojiPickerPreview = ({ options }: { options: EmojiPickerSettingsState }) => {
   const { mode } = useAppSettingsSelector((state) => state.theme);
   const { autoFocus, engine } = options;
   const [skinTone, setSkinTone] = useState(0);
   const [frequentlyUsedIds, setFrequentlyUsedIds] = useState<string[]>([]);
 
+  const recordUse = (emoji: EmojiSelection) =>
+    setFrequentlyUsedIds((ids) => [emoji.id, ...ids.filter((id) => id !== emoji.id)]);
+
   // The deprecated emoji-mart picker renders inline too and honors the same option
   // names, so the shared controls drive both engines.
   if (engine === 'emoji-mart') {
@@ -86,13 +136,30 @@ const EmojiPickerPreview = ({ options }: { options: EmojiPickerSettingsState })
     );
   }
 
+  if (engine === 'stream-composed') {
+    return (
+      <StreamEmojiPicker.Root
+        frequentlyUsedIds={frequentlyUsedIds}
+        onEmojiSelect={recordUse}
+        onSkinToneChange={setSkinTone}
+        skinToneIndex={skinTone}
+      >
+        <StreamEmojiPicker.Nav />
+        <StreamEmojiPicker.Search autoFocus={autoFocus} />
+        <PagedGrid />
+        <div className='str-chat__emoji-picker__footer'>
+          <StreamEmojiPicker.Preview />
+          <StreamEmojiPicker.SkinTone />
+        </div>
+      </StreamEmojiPicker.Root>
+    );
+  }
+
   return (
     <EmojiPickerPanel
       autoFocus={autoFocus}
       frequentlyUsedIds={frequentlyUsedIds}
-      onEmojiSelect={(emoji: EmojiSelection) =>
-        setFrequentlyUsedIds((ids) => [emoji.id, ...ids.filter((id) => id !== emoji.id)])
-      }
+      onEmojiSelect={recordUse}
       onSkinToneChange={setSkinTone}
       skinToneIndex={skinTone}
     />
@@ -139,6 +206,7 @@ export const EmojiPickerTab = ({ close }: EmojiPickerTabProps) => {
               onSelect={(engine) => update({ engine })}
               options={[
                 { label: 'Stream (native)', value: 'stream' },
+                { label: 'Stream (composed)', value: 'stream-composed' },
                 { label: 'emoji-mart (deprecated)', value: 'emoji-mart' },
               ]}
               value={emojiPicker.engine}