[x-chat] Add ChatBox layout slots with context-based slot distribution

docs/data/chat/behavior/error-handling/error-handling.md

@@ -3,7 +3,7 @@ productId: x-chat
 title: Error Handling
 packageName: '@mui/x-chat'
 githubLabel: 'scope: chat'
-components: ChatBox, MessageError
+components: ChatBox, ChatMessageError, MessageError
 ---
 
 # Chat - Error Handling

docs/data/chat/customization/slots-and-composition/slots-and-composition.md

@@ -63,37 +63,43 @@ Use `slotProps` to pass additional props to either the default or a custom slot
 
 ### Conversation slots
 
-| Slot name                   | Default component               | Element    | Description                         |
-| :-------------------------- | :------------------------------ | :--------- | :---------------------------------- |
-| `conversationList`          | `ChatConversationList`          | `<div>`    | Conversation list                   |
-| `conversationHeader`        | `ChatConversationHeader`        | `<header>` | Header bar above the message list   |
-| `conversationTitle`         | `ChatConversationTitle`         | `<div>`    | Conversation name                   |
-| `conversationSubtitle`      | `ChatConversationSubtitle`      | `<div>`    | Secondary line (participants, etc.) |
-| `conversationHeaderActions` | `ChatConversationHeaderActions` | `<div>`    | Action buttons in the header        |
+| Slot name                   | Default component               | Element    | Description                          |
+| :-------------------------- | :------------------------------ | :--------- | :----------------------------------- |
+| `conversationRoot`          | `ChatConversation`              | `<div>`    | Thread shell (wrapper-only)          |
+| `conversationList`          | `ChatConversationList`          | `<div>`    | Conversation list                    |
+| `conversationHeader`        | `ChatConversationHeader`        | `<header>` | Header bar above the message list    |
+| `conversationHeaderInfo`    | `ChatConversationHeaderInfo`    | `<div>`    | Title + subtitle group in the header |
+| `conversationTitle`         | `ChatConversationTitle`         | `<div>`    | Conversation name                    |
+| `conversationSubtitle`      | `ChatConversationSubtitle`      | `<div>`    | Secondary line (participants, etc.)  |
+| `conversationHeaderActions` | `ChatConversationHeaderActions` | `<div>`    | Action buttons in the header         |
 
 ### Message list slots
 
-| Slot name        | Default component    | Element | Description                   |
-| :--------------- | :------------------- | :------ | :---------------------------- |
-| `messageList`    | `ChatMessageList`    | `<div>` | Scrollable message container  |
-| `messageRoot`    | `ChatMessage`        | `<div>` | Individual message row        |
-| `messageAvatar`  | `ChatMessageAvatar`  | `<div>` | Author avatar                 |
-| `messageContent` | `ChatMessageContent` | `<div>` | Message bubble                |
-| `messageMeta`    | `ChatMessageMeta`    | `<div>` | Timestamp and delivery status |
-| `messageActions` | `ChatMessageActions` | `<div>` | Hover action menu             |
-| `messageGroup`   | `ChatMessageGroup`   | `<div>` | Same-author message group     |
-| `dateDivider`    | `ChatDateDivider`    | `<div>` | Date separator between groups |
+| Slot name           | Default component       | Element  | Description                           |
+| :------------------ | :---------------------- | :------- | :------------------------------------ |
+| `messageList`       | `ChatMessageList`       | `<div>`  | Scrollable message container          |
+| `messageGroup`      | `ChatMessageGroup`      | `<div>`  | Same-author message group             |
+| `messageRoot`       | `ChatMessage`           | `<div>`  | Individual message row (wrapper-only) |
+| `messageAvatar`     | `ChatMessageAvatar`     | `<div>`  | Author avatar                         |
+| `messageContent`    | `ChatMessageContent`    | `<div>`  | Message bubble                        |
+| `messageMeta`       | `ChatMessageMeta`       | `<div>`  | Timestamp (compact variant)           |
+| `messageInlineMeta` | `ChatMessageInlineMeta` | `<span>` | Inline timestamp inside the bubble    |
+| `messageError`      | `ChatMessageError`      | `<div>`  | Error card under a failed message     |
+| `messageActions`    | `ChatMessageActions`    | `<div>`  | Hover action menu                     |
+| `messageAuthorName` | —                       | `<div>`  | Author name label above the group     |
+| `dateDivider`       | `ChatDateDivider`       | `<div>`  | Date separator between groups         |
 
 ### Composer slots
 
-| Slot name              | Default component          | Element      | Description             |
-| :--------------------- | :------------------------- | :----------- | :---------------------- |
-| `composerRoot`         | `ChatComposer`             | `<form>`     | Composer container      |
-| `composerInput`        | `ChatComposerTextArea`     | `<textarea>` | Auto-resizing text area |
-| `composerSendButton`   | `ChatComposerSendButton`   | `<button>`   | Submit button           |
-| `composerAttachButton` | `ChatComposerAttachButton` | `<button>`   | File attach trigger     |
-| `composerToolbar`      | `ChatComposerToolbar`      | `<div>`      | Button row              |
-| `composerHelperText`   | `ChatComposerHelperText`   | `<div>`      | Disclaimer or hint      |
+| Slot name                | Default component            | Element      | Description                       |
+| :----------------------- | :--------------------------- | :----------- | :-------------------------------- |
+| `composerRoot`           | `ChatComposer`               | `<form>`     | Composer container (wrapper-only) |
+| `composerInput`          | `ChatComposerTextArea`       | `<textarea>` | Auto-resizing text area           |
+| `composerSendButton`     | `ChatComposerSendButton`     | `<button>`   | Submit button                     |
+| `composerAttachButton`   | `ChatComposerAttachButton`   | `<button>`   | File attach trigger               |
+| `composerAttachmentList` | `ChatComposerAttachmentList` | `<div>`      | Pending-attachment preview row    |
+| `composerToolbar`        | `ChatComposerToolbar`        | `<div>`      | Button row                        |
+| `composerHelperText`     | `ChatComposerHelperText`     | `<div>`      | Disclaimer or hint                |
 
 ### Indicator slots
 
@@ -104,8 +110,13 @@ Use `slotProps` to pass additional props to either the default or a custom slot
 | `scrollToBottom`  | `ChatScrollToBottomAffordance` | `<button>` | Floating scroll-to-bottom button       |
 | `suggestions`     | `ChatSuggestions`              | `<div>`    | Prompt suggestion chips                |
 
-:::info
-The `typingIndicator`, `unreadMarker`, and `messageActions` slots are defined in the type interface but are not currently consumed by `ChatBox`'s internal composition. To customize these, use the standalone components directly in a custom layout with `ChatProvider`.
+:::warning
+**Two things to know about the slot names:**
+
+- **Standalone components use short keys.** The flat, prefixed names above (for example, `messageAvatar`, `composerSendButton`) apply to `ChatBox`. When you render a leaf component directly, it uses its own short keys — `<ChatMessage slots={{ avatar: MyAvatar }} />`, not `messageAvatar`.
+- **`*Root` slots are wrapper-only.** `conversationRoot`, `messageRoot`, and `composerRoot` swap the styled root element while the default children still render inside. To replace a region entirely, compose it yourself with the headless hooks.
+
+The `typingIndicator` and `unreadMarker` slots are surfaced for standalone composition but are not rendered by `ChatBox`'s default layout. To use them, render the standalone components in a custom layout with `ChatProvider`.
 :::
 
 ## Hiding a slot
@@ -143,33 +154,42 @@ To conditionally show a custom component, keep the feature flag enabled and hand
 
 ## `slotProps` reference
 
-| Key                    | Type                                         | Description             |
-| :--------------------- | :------------------------------------------- | :---------------------- |
-| `root`                 | `SlotComponentProps<'div'>`                  | Outermost div           |
-| `layout`               | `SlotComponentProps<'div'>`                  | Layout div              |
-| `conversationsPane`    | `SlotComponentProps<'div'>`                  | Conversations pane div  |
-| `threadPane`           | `SlotComponentProps<'div'>`                  | Thread pane div         |
-| `conversationList`     | `Partial<ChatConversationListProps>`         | Conversation list       |
-| `conversationHeader`   | `Partial<ChatConversationHeaderProps>`       | Thread header           |
-| `conversationTitle`    | `Partial<ChatConversationTitleProps>`        | Thread title            |
-| `conversationSubtitle` | `Partial<ChatConversationSubtitleProps>`     | Thread subtitle         |
-| `messageList`          | `Partial<ChatMessageListProps>`              | Message list            |
-| `messageRoot`          | `Partial<ChatMessageProps>`                  | Each message container  |
-| `messageAvatar`        | `Partial<ChatMessageAvatarProps>`            | Message avatar          |
-| `messageContent`       | `Partial<ChatMessageContentProps>`           | Message content/bubble  |
-| `messageMeta`          | `Partial<ChatMessageMetaProps>`              | Message timestamp       |
-| `messageActions`       | `Partial<ChatMessageActionsProps>`           | Message action menu     |
-| `messageGroup`         | `Partial<ChatMessageGroupProps>`             | Message group container |
-| `dateDivider`          | `Partial<ChatDateDividerProps>`              | Date separator          |
-| `composerRoot`         | `Partial<ChatComposerProps>`                 | Composer form root      |
-| `composerInput`        | `Partial<ChatComposerTextAreaProps>`         | Composer textarea       |
-| `composerSendButton`   | `Partial<ChatComposerSendButtonProps>`       | Send button             |
-| `composerAttachButton` | `Partial<ChatComposerAttachButtonProps>`     | Attach button           |
-| `composerToolbar`      | `Partial<ChatComposerToolbarProps>`          | Toolbar container       |
-| `composerHelperText`   | `Partial<ChatComposerHelperTextProps>`       | Helper text below input |
-| `typingIndicator`      | `Partial<ChatTypingIndicatorProps>`          | Typing indicator        |
-| `unreadMarker`         | `Partial<ChatUnreadMarkerProps>`             | Unread marker           |
-| `scrollToBottom`       | `Partial<ChatScrollToBottomAffordanceProps>` | Scroll to bottom button |
+| Key                         | Type                                          | Description                    |
+| :-------------------------- | :-------------------------------------------- | :----------------------------- |
+| `root`                      | `SlotComponentProps<'div'>`                   | Outermost div                  |
+| `layout`                    | `SlotComponentProps<'div'>`                   | Layout div                     |
+| `conversationsPane`         | `SlotComponentProps<'div'>`                   | Conversations pane div         |
+| `threadPane`                | `SlotComponentProps<'div'>`                   | Thread pane div                |
+| `conversationRoot`          | `Partial<ChatConversationProps>`              | Thread shell (wrapper-only)    |
+| `conversationList`          | `Partial<ChatConversationListProps>`          | Conversation list              |
+| `conversationHeader`        | `Partial<ChatConversationHeaderProps>`        | Thread header                  |
+| `conversationHeaderInfo`    | `Partial<ChatConversationHeaderInfoProps>`    | Title + subtitle group         |
+| `conversationTitle`         | `Partial<ChatConversationTitleProps>`         | Thread title                   |
+| `conversationSubtitle`      | `Partial<ChatConversationSubtitleProps>`      | Thread subtitle                |
+| `conversationHeaderActions` | `Partial<ChatConversationHeaderActionsProps>` | Header action area             |
+| `messageList`               | `Partial<ChatMessageListProps>`               | Message list                   |
+| `messageGroup`              | `Partial<ChatMessageGroupProps>`              | Message group container        |
+| `messageRoot`               | `Partial<ChatMessageProps>`                   | Each message container         |
+| `messageAvatar`             | `Partial<ChatMessageAvatarProps>`             | Message avatar                 |
+| `messageContent`            | `Partial<ChatMessageContentProps>`            | Message content/bubble         |
+| `messageMeta`               | `Partial<ChatMessageMetaProps>`               | Message timestamp (compact)    |
+| `messageInlineMeta`         | `Record<string, unknown>`                     | Inline timestamp in the bubble |
+| `messageError`              | `Partial<ChatMessageErrorProps>`              | Error card                     |
+| `messageActions`            | `Partial<ChatMessageActionsProps>`            | Message action menu            |
+| `messageAuthorName`         | `Record<string, unknown>`                     | Author name label              |
+| `dateDivider`               | `Partial<ChatDateDividerProps>`               | Date separator                 |
+| `composerRoot`              | `Partial<ChatComposerProps>`                  | Composer form root             |
+| `composerInput`             | `Partial<ChatComposerTextAreaProps>`          | Composer textarea              |
+| `composerSendButton`        | `Partial<ChatComposerSendButtonProps>`        | Send button                    |
+| `composerAttachButton`      | `Partial<ChatComposerAttachButtonProps>`      | Attach button                  |
+| `composerAttachmentList`    | `Partial<ChatComposerAttachmentListProps>`    | Attachment preview row         |
+| `composerToolbar`           | `Partial<ChatComposerToolbarProps>`           | Toolbar container              |
+| `composerHelperText`        | `Partial<ChatComposerHelperTextProps>`        | Helper text below input        |
+| `typingIndicator`           | `Partial<ChatTypingIndicatorProps>`           | Typing indicator               |
+| `unreadMarker`              | `Partial<ChatUnreadMarkerProps>`              | Unread marker                  |
+| `scrollToBottom`            | `Partial<ChatScrollToBottomAffordanceProps>`  | Scroll to bottom button        |
+| `suggestions`               | `Partial<ChatSuggestionsProps>`               | Prompt suggestions             |
+| `emptyState`                | `SlotComponentProps<'div'>`                   | Custom empty state             |
 
 ## CSS classes
 

docs/data/chat/display/message-actions/BasicMessageActions.js

@@ -36,7 +36,9 @@ export default function BasicMessageActions() {
       initialActiveConversationId={minimalConversation.id}
       initialConversations={[minimalConversation]}
       initialMessages={minimalMessages}
-      slots={{ messageActions: MyMessageActions }}
+      slots={{
+        messageActions: MyMessageActions,
+      }}
       sx={{
         height: 500,
         border: '1px solid',

docs/data/chat/display/message-actions/BasicMessageActions.tsx

@@ -36,7 +36,9 @@ export default function BasicMessageActions() {
       initialActiveConversationId={minimalConversation.id}
       initialConversations={[minimalConversation]}
       initialMessages={minimalMessages}
-      slots={{ messageActions: MyMessageActions }}
+      slots={{
+        messageActions: MyMessageActions,
+      }}
       sx={{
         height: 500,
         border: '1px solid',

docs/data/chat/display/message-actions/BasicMessageActions.tsx.preview

@@ -3,7 +3,9 @@
   initialActiveConversationId={minimalConversation.id}
   initialConversations={[minimalConversation]}
   initialMessages={minimalMessages}
-  slots={{ messageActions: MyMessageActions }}
+  slots={{
+    messageActions: MyMessageActions,
+  }}
   sx={{
     height: 500,
     border: '1px solid',

docs/data/chat/display/message-actions/RoleBasedMessageActions.js

@@ -44,7 +44,9 @@ export default function RoleBasedMessageActions() {
       initialActiveConversationId={minimalConversation.id}
       initialConversations={[minimalConversation]}
       initialMessages={minimalMessages}
-      slots={{ messageActions: RoleBasedActions }}
+      slots={{
+        messageActions: RoleBasedActions,
+      }}
       sx={{
         height: 500,
         border: '1px solid',

docs/data/chat/display/message-actions/RoleBasedMessageActions.tsx

@@ -44,7 +44,9 @@ export default function RoleBasedMessageActions() {
       initialActiveConversationId={minimalConversation.id}
       initialConversations={[minimalConversation]}
       initialMessages={minimalMessages}
-      slots={{ messageActions: RoleBasedActions }}
+      slots={{
+        messageActions: RoleBasedActions,
+      }}
       sx={{
         height: 500,
         border: '1px solid',

docs/data/chat/display/message-actions/RoleBasedMessageActions.tsx.preview

@@ -3,7 +3,9 @@
   initialActiveConversationId={minimalConversation.id}
   initialConversations={[minimalConversation]}
   initialMessages={minimalMessages}
-  slots={{ messageActions: RoleBasedActions }}
+  slots={{
+    messageActions: RoleBasedActions,
+  }}
   sx={{
     height: 500,
     border: '1px solid',

docs/data/chat/material/composer/ComposerCustomPlaceholder.js

@@ -17,7 +17,7 @@ export default function ComposerCustomPlaceholder() {
       initialConversations={[minimalConversation]}
       initialMessages={minimalMessages}
       slotProps={{
-        composerInput: { placeholder: 'Ask me anything…' },
+        composerInput: { placeholder: 'Ask me anything...' },
       }}
       sx={{
         height: 400,

docs/data/chat/material/composer/ComposerCustomPlaceholder.tsx

@@ -17,7 +17,7 @@ export default function ComposerCustomPlaceholder() {
       initialConversations={[minimalConversation]}
       initialMessages={minimalMessages}
       slotProps={{
-        composerInput: { placeholder: 'Ask me anything…' },
+        composerInput: { placeholder: 'Ask me anything...' },
       }}
       sx={{
         height: 400,

docs/data/chat/material/composer/ComposerCustomPlaceholder.tsx.preview

@@ -4,7 +4,7 @@
   initialConversations={[minimalConversation]}
   initialMessages={minimalMessages}
   slotProps={{
-    composerInput: { placeholder: 'Ask me anything…' },
+    composerInput: { placeholder: 'Ask me anything...' },
   }}
   sx={{
     height: 400,

docs/data/chat/material/conversation-list/CompactRow.js

@@ -88,6 +88,7 @@ export default function CompactRow() {
       activeConversationId={activeConversationId}
       conversations={conversations}
       messages={messages}
+      features={{ conversationList: true }}
       onActiveConversationChange={(nextId) => {
         if (nextId) {
           setActiveConversationId(nextId);

docs/data/chat/material/conversation-list/CompactRow.tsx

@@ -95,6 +95,7 @@ export default function CompactRow() {
       activeConversationId={activeConversationId}
       conversations={conversations}
       messages={messages}
+      features={{ conversationList: true }}
       onActiveConversationChange={(nextId) => {
         if (nextId) {
           setActiveConversationId(nextId);

docs/data/chat/material/conversation-list/FullCustomRow.js

@@ -147,6 +147,7 @@ export default function FullCustomRow() {
       activeConversationId={activeConversationId}
       conversations={conversations}
       messages={messages}
+      features={{ conversationList: true }}
       onActiveConversationChange={(nextId) => {
         if (nextId) {
           setActiveConversationId(nextId);

docs/data/chat/material/conversation-list/FullCustomRow.tsx

@@ -155,6 +155,7 @@ export default function FullCustomRow() {
       activeConversationId={activeConversationId}
       conversations={conversations}
       messages={messages}
+      features={{ conversationList: true }}
       onActiveConversationChange={(nextId) => {
         if (nextId) {
           setActiveConversationId(nextId);

docs/data/chat/material/conversation-list/RichItemContent.js

@@ -89,6 +89,7 @@ export default function RichItemContent() {
       activeConversationId={activeConversationId}
       conversations={conversations}
       messages={messages}
+      features={{ conversationList: true }}
       onActiveConversationChange={(nextId) => {
         if (nextId) {
           setActiveConversationId(nextId);

docs/data/chat/material/conversation-list/RichItemContent.tsx

@@ -97,6 +97,7 @@ export default function RichItemContent() {
       activeConversationId={activeConversationId}
       conversations={conversations}
       messages={messages}
+      features={{ conversationList: true }}
       onActiveConversationChange={(nextId) => {
         if (nextId) {
           setActiveConversationId(nextId);

docs/data/chat/material/conversation-list/ThemedAvatar.js

@@ -67,6 +67,7 @@ export default function ThemedAvatar() {
       activeConversationId={activeConversationId}
       conversations={conversations}
       messages={messages}
+      features={{ conversationList: true }}
       onActiveConversationChange={(nextId) => {
         if (nextId) {
           setActiveConversationId(nextId);