[chat][docs] Add docs overview gallery and playground

docs/data/chat/accessibility/accessibility.md

@@ -0,0 +1,85 @@
+---
+productId: x-chat
+title: Accessibility
+packageName: '@mui/x-chat'
+githubLabel: 'scope: chat'
+---
+
+# Chat - Accessibility
+
+<p class="description">Learn how MUI X Chat implements keyboard navigation, landmarks, and screen reader announcements.</p>
+
+## Keyboard navigation
+
+The message list is a single Tab stop: a roving tabindex over the `role="article"` messages keeps only one message in the tab order at a time, so tabbing from the composer to the rest of the application never walks through every message.
+
+{{"demo": "../material/message-list/KeyboardNavigation.js", "defaultCodeOpen": false, "bg": "inline"}}
+
+| Key                                              | Action                                                                                           |
+| :----------------------------------------------- | :----------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Enter or leave the message list (a single stop)                                                  |
+| <kbd>Arrow Up</kbd> / <kbd>Arrow Down</kbd>      | Move focus to the previous / next message                                                        |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | Move focus to the first / latest message                                                         |
+| <kbd>Page Up</kbd> / <kbd>Page Down</kbd>        | Native scrolling (kept unbound so a message taller than the viewport stays readable by keyboard) |
+| <kbd>Enter</kbd>                                 | Drill into the focused message's controls (links, copy buttons, tool output, actions)            |
+| <kbd>Escape</kbd>                                | Return from a message's controls to the message                                                  |
+
+Before the user interacts, the tab stop tracks the newest message.
+The tab stop is remembered per list, so leaving and re-entering the message list returns focus to the same message.
+
+## Drill-in lifecycle
+
+Interactive content inside messages—links in Markdown, code-block copy buttons, tool and reasoning disclosures, source and file links—stays out of the tab order until the user drills into the focused message with <kbd>Enter</kbd>, and leaves it again on <kbd>Escape</kbd>.
+All controls remain mouse-clickable throughout.
+Message actions are additionally hidden (`visibility: hidden`) until the message is hovered or drilled into.
+
+When the user drills back out with <kbd>Escape</kbd>, focus returns to the message that owned the controls. Because the tab stop is remembered per list, re-entering the list later restores focus to the same message.
+
+## Landmarks
+
+The chat surface exposes labeled landmarks so assistive technology can jump between its regions:
+
+- The thread is a `role="region"` labeled by the `threadLandmarkLabel` locale key.
+- The composer is a labeled `form` (the `composerLandmarkLabel` locale key).
+- The conversation list is a `role="navigation"` region labeled by `conversationListLandmarkLabel`.
+- On small screens, the conversation list opens in a `role="dialog"` with `aria-modal="true"`.
+
+## Screen reader announcements
+
+- The scroller element has `role="log"` and `aria-live="polite"`, so newly arriving complete messages are announced.
+- A streaming message carries `aria-busy="true"` while it streams, hinting assistive technology to defer reading it until it completes.
+- A visually hidden `role="status"` region announces streaming transitions—"Assistant is responding" and "Response complete"—exactly once each, never per streamed token.
+- Each message is a `role="article"` labeled "Message from {author}".
+- Date dividers use `role="separator"`.
+
+The announcement strings and labels come from the locale text system, so they localize with the rest of the UI: `messageListLabel` for the list, `responseStreamingStartedAnnouncement` and `responseStreamingCompletedAnnouncement` for the streaming announcer, and `threadLandmarkLabel`, `composerLandmarkLabel`, and `conversationListLandmarkLabel` for the landmarks.
+
+## Reduced motion
+
+The loading skeleton's shimmer animation pauses automatically when the user requests reduced motion (`prefers-reduced-motion: reduce`).
+The skeleton itself is decorative and sets no ARIA, so you wire the loading state up explicitly—see [Loading and empty states](/x/react-chat/display/loading-and-empty-states/) for the `aria-busy` and `role="status"` pattern.
+
+## Opting out and custom controls
+
+Set `enableRovingFocus={false}` on the message list to opt out entirely, for example when rendering fully custom rows that manage focus themselves.
+
+Custom interactive content rendered inside a message can participate in the drill-in model with the `useMessageContentTabIndex()` hook (or `useMessageActionable()` for full control), both available from `@mui/x-chat/headless`:
+
+```tsx
+function CustomControl() {
+  const tabIndex = useMessageContentTabIndex();
+  return (
+    <button type="button" tabIndex={tabIndex}>
+      …
+    </button>
+  );
+}
+```
+
+Outside a roving message list both hooks leave the natural tab order untouched, so the same component works in standalone message compositions.
+
+## See also
+
+- [Message list—Accessibility](/x/react-chat/material/message-list/#accessibility) for the message-list keyboard table and drill-in specifics.
+- [Messages](/x/react-chat/basics/messages/#accessibility) for the summary alongside the message API.
+- [Conversation list—Accessibility notes](/x/react-chat/multi-conversation/conversation-list/#accessibility-notes) for the sidebar's roving listbox.

docs/data/chat/ai-and-agents/reasoning/ReasoningSlotsDemo.js

@@ -0,0 +1,163 @@
+'use client';
+import * as React from 'react';
+import { ChatBox } from '@mui/x-chat';
+
+import AutoAwesomeOutlinedIcon from '@mui/icons-material/AutoAwesomeOutlined';
+
+const CONVERSATION_ID = 'reasoning-slots-demo';
+
+const initialConversations = [{ id: CONVERSATION_ID, title: 'Reasoning slots' }];
+
+const initialMessages = [
+  {
+    id: 'seed',
+    conversationId: CONVERSATION_ID,
+    role: 'assistant',
+    status: 'sent',
+    parts: [
+      {
+        type: 'reasoning',
+        text: 'The user greeted me. A short, friendly reply is enough — no tools needed.',
+        state: 'done',
+      },
+      {
+        type: 'text',
+        text: 'Hi! Send a message to see the restyled reasoning disclosure stream.',
+      },
+    ],
+  },
+];
+
+// Emit one chunk per pull, with a small delay, so the disclosure visibly streams.
+function streamChunks(chunks) {
+  let index = 0;
+  return new ReadableStream({
+    pull(controller) {
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          if (index < chunks.length) {
+            controller.enqueue(chunks[index]);
+            index += 1;
+          } else {
+            controller.close();
+          }
+          resolve();
+        }, 100);
+      });
+    },
+  });
+}
+
+const adapter = {
+  async sendMessage({ message }) {
+    const messageId = `reply-${message.id}`;
+    return streamChunks([
+      { type: 'start', messageId },
+      { type: 'reasoning-start', id: 'r1' },
+      {
+        type: 'reasoning-delta',
+        id: 'r1',
+        delta: 'Let me think about how to answer this. ',
+      },
+      {
+        type: 'reasoning-delta',
+        id: 'r1',
+        delta: 'The question is straightforward, ',
+      },
+      { type: 'reasoning-delta', id: 'r1', delta: 'so a concise reply works best.' },
+      { type: 'reasoning-end', id: 'r1' },
+      { type: 'text-start', id: 't1' },
+      { type: 'text-delta', id: 't1', delta: 'Here is the answer, now that ' },
+      { type: 'text-delta', id: 't1', delta: 'the reasoning above has finished.' },
+      { type: 'text-end', id: 't1' },
+      { type: 'finish', messageId },
+    ]);
+  },
+};
+
+// Custom `root` slot — a tinted disclosure container.
+const CustomRoot = React.forwardRef(function CustomRoot(props, ref) {
+  const { ownerState, style, ...other } = props;
+  return (
+    <details
+      ref={ref}
+      style={{
+        margin: '6px 0',
+        padding: '6px 10px',
+        borderRadius: 8,
+        background: 'rgba(99, 102, 241, 0.08)',
+        ...style,
+      }}
+      {...other}
+    />
+  );
+});
+
+// Custom `summary` slot — uses `ownerState.streaming` for a live affordance.
+const CustomSummary = React.forwardRef(function CustomSummary(props, ref) {
+  const { ownerState, children, style, ...other } = props;
+  const streaming = ownerState?.streaming;
+  return (
+    <summary
+      ref={ref}
+      style={{
+        cursor: 'pointer',
+        display: 'flex',
+        alignItems: 'center',
+        gap: 6,
+        listStyle: 'none',
+        fontSize: 13,
+        fontWeight: 500,
+        color: '#6366f1',
+        ...style,
+      }}
+      {...other}
+    >
+      <AutoAwesomeOutlinedIcon style={{ fontSize: 14 }} />
+      {children}
+      {streaming ? (
+        <span
+          aria-hidden
+          style={{
+            width: 6,
+            height: 6,
+            borderRadius: '50%',
+            background: '#6366f1',
+            animation: 'reasoning-pulse 1s ease-in-out infinite',
+          }}
+        />
+      ) : null}
+      <style>
+        {
+          '@keyframes reasoning-pulse { 0%, 100% { opacity: 0.3; } 50% { opacity: 1; } }'
+        }
+      </style>
+    </summary>
+  );
+});
+
+export default function ReasoningSlotsDemo() {
+  return (
+    <ChatBox
+      adapter={adapter}
+      initialActiveConversationId={CONVERSATION_ID}
+      initialConversations={initialConversations}
+      initialMessages={initialMessages}
+      slotProps={{
+        messageContent: {
+          partProps: {
+            reasoning: {
+              slots: { root: CustomRoot, summary: CustomSummary },
+            },
+          },
+        },
+      }}
+      sx={{
+        height: 480,
+        border: '1px solid',
+        borderColor: 'divider',
+        borderRadius: 1,
+      }}
+    />
+  );
+}