Repository navigation
[chat][docs] Add docs overview gallery and playground - #22488
Merged
Merged
Conversation
Two built-in adapters that ship with @mui/x-chat-headless: a simple echo adapter for examples and an AI SDK adapter that bridges Vercel AI SDK UIMessage streams into ChatMessageChunk events. Wire both through the headless core barrel so they can be imported from '@mui/x-chat-headless' and '@mui/x-chat-headless/core'.
Deploy preview
Bundle size
Check out the code infra dashboard for more information about this PR. |
hasdfa
added
scope: chat
hasdfa
force-pushed
the
x-chat-docs-overview-gallery
branch
4 times, most recently
from
May 18, 2026 10:33
7d92cab to
54abad4
Compare
hasdfa
marked this pull request as ready for review
May 18, 2026 13:14
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f7606d1d4b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
hasdfa
force-pushed
the
x-chat-docs-overview-gallery
branch
from
May 18, 2026 14:37
f7606d1 to
ec631c3
Compare
hasdfa
force-pushed
the
x-chat-docs-overview-gallery
branch
from
May 18, 2026 14:46
ec631c3 to
1ad9d05
Compare
hasdfa
force-pushed
the
x-chat-docs-overview-gallery
branch
from
May 18, 2026 14:53
1ad9d05 to
3defa8e
Compare
When the AI SDK backend omits messageId on its start/finish chunks (the
SDK's own default — bare `{ type: 'start' }`), the adapter synthesized one.
But the counter lived inside convertToChatStream, which is recreated per
sendMessage call, so it reset to 0 every send and always produced the same
first id (`ai-sdk-msg-1`). processStream keys messages by id, so every reply
bound to the same assistant message and appended into a single bubble.
Hoist the counter to adapter scope (shared by sendMessage + regenerate) so
each response gets a unique synthetic id. Correct the test that had codified
the collision.
Addresses test_lint, test_static/test_types, and the docs:build link-check (netlify) on this branch. - backend/adapters: add explicit column alignment (`:---`) to two API tables (remark-lint-mui-table-alignment) - remove ExtraActionsMessageActions.tsx.preview: the demo's JSX exceeds the preview maxLines, so docs:typescript:formatted strips it (drift) - material/composer: drop ChatComposer from frontmatter components (no generated API page exists for the root → broken footer link) - read-receipts: correct two API links to /x/api/chat/... (were /x/react-chat/api/...) - core/adapters: point the Vercel AI SDK link at the ai-sdk-adapter page (integrations/ai-sdk does not exist) - error-handling: fix the useMessageError anchor (#usemessageerror-messageid) Verified: 711-page + 1665-anchor deterministic scan shows zero remaining broken internal links; eslint/prettier/valelint/typescript:ci/proptypes/ docs:api/generate:exports/l10n all clean.
Second CI pass after an authoritative link-crawl of the built export surfaced links the file-existence scan couldn't see (same-page anchors, a directory-without-index, a markdown footnote). test_static: - regenerate docs/public/static/error-codes.json: the docs-correctness guard added two MUI X-prefixed error messages (287/288) that were never extracted docs:build / netlify link-check: - basics/messages: remove the slot jump list — it linked to H4 (####) headings, which the docs don't assign anchor ids, so all five anchors (#avatar/#author-label/#content/#meta/#inline-meta) were dead - sources-and-citations demo: the message text used a markdown footnote ([^1]) with no definition, rendering a broken #1 link; use [1] - add a 301 from /x/react-chat/customization/ to .../customization/ overview/: the ChatBox API page links the overview as the section landing (MUI overview=landing convention) but it is routed at /overview/ Verified by re-crawling the export: the 12 real issues (5 from the prior commit + these 7) are the complete set; remaining crawl 'issues' are a local-server artifact (no _redirects handling for /).
processStream requires a messageId on `start`, which forced every adapter to
synthesize one when the backend omits it (the AI SDK ships bare
`{ type: 'start' }`). Synthesizing it uniquely is a footgun: an adapter that
reused an id across sends made processStream key every reply to the same
assistant message and merge them into one bubble.
Move the uniqueness guarantee into the core: the controller mints a unique
fallback id (createLocalId) per send/regenerate and passes it as
processStream's `messageId`. The `start` handler now keeps that fallback
unless the chunk supplies its own id (`chunk.messageId ?? targetMessageId`,
matching finish/abort), so a backend-supplied id still wins and reconnect
still binds to the resumed id. Regeneration is safe — the prior run is
removed before streaming, so a fresh id targets a new message.
This neutralizes the whole "adapter omitted/duplicated a synthetic id" class
for every adapter, present and future. Adapters keep emitting their own ids
(still correct if consumed standalone); this is the core safety net.
Tests: processStream binds to options.messageId when start omits one, and a
start id still overrides the fallback; sendMessageActions gives each id-less
response across sequential sends its own assistant message.
Animated dots shown while an assistant response is in flight, covering two phases: a trailing row below the last message while waiting for the stream to start, then inside the assistant bubble (below the streamed content) until the response finishes. - New `features.streamingIndicator?: boolean | 'auto'` flag (default 'auto'): auto-detects assistant-backed conversations (assistant member/participant or an assistant message present) so human-to-human chats never show it; `true`/`false` force it on/off. - New `streamingIndicator` slot (+ slotProps) on ChatBox and the standalone ChatMessageList; pass `null` to hide. Disabling the feature nulls the slot for the whole row pipeline. - Material `ChatStreamingIndicator` (visual ported from x-copilot) with utility classes and theme augmentation; headless `StreamingIndicator` primitive and `useStreamingIndicatorVisibility()` hook for custom slots, subscribing to boolean-valued selectors so streamed chunks don't churn re-renders. - `streamingConversationId` recorded on the store via `setStreaming(value, conversationId?)` so the indicator never shows in a different conversation than the in-flight stream. - Dots are aria-hidden; the message list status live region already announces streaming transitions. - Docs: new section + interactive demo on the streaming page, headless indicators page coverage, typing-indicators cross-link callout.
github-actions
Bot
added
the
PR: out-of-date
Contributor
|
This pull request has conflicts, please resolve those before we can evaluate the pull request. |
Add `partProps.tool.defaultExpanded`: a per-tool-name map (boolean | resolver, with a '*' fallback) controlling whether tool cards and their input/output sections are expanded. Resolvers run on every state transition (return false to collapse a card when its tool ends) and can read toolName, state, section, and isMessageStreaming; undefined keeps the built-in default. Open/close state is owned by the new internal useToolDisclosure hook (shared by the card root and sections), with focus-safe auto-collapse. Adds a docs playground, a Default expanded state section (incl. group/prefix matching), and unit tests.
…iew-gallery # Conflicts: # docs/public/static/error-codes.json
github-actions
Bot
removed
the
PR: out-of-date
github-actions
Bot
added
the
PR: out-of-date
Contributor
|
This pull request has conflicts, please resolve those before we can evaluate the pull request. |
…iew-gallery # Conflicts: # docs/public/static/error-codes.json
github-actions
Bot
removed
the
PR: out-of-date
hasdfa
changed the title
This was referenced Jun 15, 2026
mbrookes
pushed a commit
to mbrookes/mui-x
that referenced
this pull request
Jun 27, 2026
Signed-off-by: Vadym Raksha <hello@raksha.bio> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR builds out the Chat docs overview gallery and playground experience, hardens the Material message surfaces in
@mui/x-chat, and follows up with a docs-accuracy pass that ships the runtime APIs the docs describe and adds a CI guard so docs code stays in sync with the package.Docs
docs/src/modules/chat-gallery/*component showcase (message, composer, conversation, layout, and state thumbnails) plus aChatComponentsSectionand anall-componentspage that links every chat surface.docs/src/modules/components/chat-playground/*infrastructure (PlaygroundCard, controls, shared fixtures/providers,parseSx) wiring Props + Classes tabs onto live demos.basics/conversation,display/date-divider,display/unread-marker,customization/{overview,structure,look-and-feel},backend/built-in-adapters/{ai-sdk,echo}, plus refreshed quickstart, basics, behavior, display, and multi-conversation content.@mui/x-chatpackageChatMessageError— new public error-surface component with its own classes (chatMessageErrorClasses,getChatMessageErrorUtilityClass).ChatSlotsContextand a flat slot vocabulary across the Material message/composer/conversation surfaces.ChatBoxlayout modes — newChatBoxLayoutMode/ChatBoxLayoutModeBreakpointstypes and layout slots.markdown-to-jsx(^9.8.1), withstreamingMarkdownRepairto gracefully close partial markdown during streaming.mergeSlotProps,useCopyToClipboard,streamingMarkdownRepair, and aDefaultMessageItemforChatMessageList.theme.alphaused for the error card background (CSS-vars safe).New runtime APIs
A docs review found several pages documenting APIs (or recipes) that didn't actually exist. Rather than weaken the docs, these were implemented in
@mui/x-chat-headlessand surfaced through@mui/x-chat:chat.regenerate(messageId)runtime action (useChat().regenerate) plus a new subscription-freeuseChatActions()hook, an optionaladapter.regeneratetransport hook, aREGENERATE_ERRORcode, andregeneratebridges for the echo and Vercel AI SDK adapters. Message actions gainextraActionswith function-valuedslotProps.messageActions.features.typingSignal(off by default) that edge-triggersadapter.setTyping()on the composer going empty↔non-empty, via newChatFeaturesplumbing throughChatProvider/ChatRoot/ChatBox.onReachBottomon the message list (strict reach semantics mirroringonReachTop), plus JSDoc for the existingonReachTop.isLoadingHistory— exposed across the store, aselectIsLoadingHistoryselector,useChat/useChatStatus, andChatPublicState; true during both initial history fetch andloadMoreHistory.shouldShowDividerpredicate on the date divider for custom grouping (default by-day behavior unchanged), with by-week / every-N-messages recipes in the docs.ConversationList.Itemadded to the headless namespace (was documented but onlyRootwas exported).ChatMessageSkeletonnow respectsprefers-reduced-motion. All additions are covered by new unit + browser tests (882 jsdom / 908 browser passing).Docs correctness
\ |instead of\|), splitting cells and adding phantom columns across 16 pages; repaired mechanically.readstatus, author grouping,renderStreamingMarkdown),data-${string}part types,toolCallIdvsapprovalId, and completed over-claimed sets (the all-components gallery, the streaming chunk-type table, and the selector/hook reference pages now match the real export surface).Tooling
packages/x-chat/src/tests/docsCorrectnessGuard/) that fails CI if any docs code fence or demo.tsximports a symbol that isn't exported from the stated entry point, or if frontmattercomponents:/hooks:reference a missing export. Export surfaces are enumerated via the TypeScript checker; it ships green and prevents this whole class of doc drift from regressing.New dependency
markdown-to-jsx@^9.8.1(added to@mui/x-chat).