Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docsite): use chat subcomponent usage summaries (#2893)

Cindy Zhang8ec5090e04d3
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index efc57893a1..f1079f45ed 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -406,8 +406,10 @@ async function generateComponentRegistry() {
// .doc.mjs file. Inherits family fields (group, category, keywords,
// theming, playground, importPath) from the directory's primary doc
// unless the sub-component doc overrides them; owns its name,
- // description, props, and usage. Produces a registry
- // entry identical to the legacy inline `components[]` expansion.
+ // description, props, and usage. When no usage block is authored,
+ // use the sub-component description as the usage summary instead of
+ // inheriting parent prose. Produces a registry entry identical to the
+ // legacy inline `components[]` expansion.
const parentMeta = dirPrimaryMeta || {};
const subName = (doc.name || '').replace(/^XDS/, '');
if (subName) {
@@ -439,9 +441,9 @@ async function generateComponentRegistry() {
: [],
usage: doc.usage
? sanitizeForJson(doc.usage)
- : isHookEntry && doc.description
+ : doc.description
? {description: doc.description}
- : parentMeta.usage ?? null,
+ : null,
theming: isHookEntry
? null
: doc.theming
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 3993002c02..92880f5073 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -235,6 +235,22 @@ describe('componentRegistry', () => {
expect(dialogHeader!.description.toLowerCase()).toContain('header');
});
+ it('extracted sub-components do not inherit parent usage prose', () => {
+ const core = components['@xds/core'];
+ const chatComposer = core.find(c => c.name === 'ChatComposer');
+ expect(chatComposer).toBeDefined();
+ expect(chatComposer!.parentDoc).toBe('Chat');
+ expect(chatComposer!.usage?.description).toContain(
+ 'Layout shell for a chat composer',
+ );
+ expect(chatComposer!.usage?.description).not.toContain(
+ 'XDSChatMessageList',
+ );
+ expect(chatComposer!.usage?.description).not.toContain(
+ 'scrollable container for chat messages',
+ );
+ });
+
it('sub-components can override inherited playground defaults', () => {
const core = components['@xds/core'];
const avatarGroupOverflow = core.find(
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index aa94c23f2f..ef725121ff 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -57,7 +57,7 @@ export const docs = {
{name: 'XDSChatLayoutScrollButton'},
],
usage: {
- description: 'XDSChatMessageList is the scrollable container for chat messages. It renders children in a flex column with role="log" for accessibility, provides density context to child messages, and supports infinite scroll for loading older messages. Use it inside XDSChatLayout for full-page chat with auto-scroll and composer docking, or standalone for embedded message panels.',
+ description: 'XDSChat is a family of composable primitives for building AI and human chat experiences. Combine XDSChatLayout, XDSChatMessageList, XDSChatMessage, bubbles, system messages, tool calls, tokenized text, and XDSChatComposer to assemble complete conversations without reimplementing sender-aware layout, density, scrolling, or composer behavior.',
bestPractices: [
{ guidance: true, description: 'Compose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.' },
{ guidance: true, description: 'Set the density prop to control spacing globally: compact for sidebars, balanced for most views, spacious for long-form reading. Individual messages can override.' },
@@ -91,7 +91,7 @@ export const docs = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
usage: {
- description: 'XDSChatMessageList 是聊天消息的可滚动容器。它以 flex 列的形式渲染子元素,使用 role="log" 确保无障碍性,通过上下文向子消息提供密度设置,并支持无限滚动以加载更早的消息。在 XDSChatLayout 内使用它可获得全页聊天体验(自动滚动和编辑器停靠),也可独立用于嵌入式消息面板。',
+ description: 'XDSChat 是一组用于构建 AI 和人工聊天体验的可组合基础组件。组合 XDSChatLayout、XDSChatMessageList、XDSChatMessage、气泡、系统消息、工具调用、标记文本和 XDSChatComposer,可构建完整对话,而无需重新实现发送者感知布局、密度、滚动或编写器行为。',
bestPractices: [
{ guidance: true, description: '使用 MessageList > Message > Bubble 组合来获得一致的发送者感知样式和密度。' },
{ guidance: true, description: '设置 density 属性来全局控制间距:compact 用于侧边栏,balanced 用于大多数视图,spacious 用于长篇阅读。' },
@@ -121,7 +121,7 @@ export const docsZh = {
export const docsDense = {
description: 'AI chat components. Layout (MessageList>Message>Bubble+SystemMessage) + Composer (shell w/ slots, ContentEditable input w/ trigger menus, tokens, msg history, attachments)',
usage: {
- description: 'XDSChatMessageList: scrollable msg container w/ role="log", density context, infinite scroll. Use inside XDSChatLayout for full-page chat or standalone for embedded panels.',
+ description: 'Chat family: layout + message list + sender messages + bubbles + system messages + tool calls + tokenized text + composer for complete conversation UIs.',
bestPractices: [
{ guidance: true, description: 'MessageList > Message > Bubble for sender-aware styling.' },
{ guidance: true, description: 'Density prop controls global spacing: compact for sidebars, balanced default, spacious for reading.' },
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
index f5a85b306c..2e309b8998 100644
--- a/packages/core/src/docs-types.ts
+++ b/packages/core/src/docs-types.ts
@@ -561,9 +561,9 @@ export interface SubComponentDoc extends Omit<BaseDoc, 'usage'> {
description: string;
/** All public props for this sub-component. */
props: PropDoc[];
- /** Usage is optional for sub-components — when omitted, the registry entry
- * carries the sub-component's own props/description with no usage prose
- * (it is NOT inherited from the parent, which was the #2602 bug). */
+ /** Usage is optional for sub-components — when omitted, generated surfaces
+ * should use the sub-component's own description as the concise usage
+ * summary (not inherited from the parent, which was the #2602 bug). */
usage?: UsageDoc;
}