Skip to content

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

TypeScript

docs(ChatComposerDrawer): improve usage docs and block examples (#1862)

Kenton Quatmanb9c7328f4d69
diff --git a/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.doc.mjs b/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.doc.mjs
index 85f0bd028a..361531551d 100644
--- a/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.doc.mjs
+++ b/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.doc.mjs
@@ -2,8 +2,8 @@
export const doc = {
type: 'block',
name: 'Chat — Composer Drawer',
- description: 'Composer with removable file tokens and a collapsible drawer. Use a context progress bar to show how much of the context window is used, and the collapse toggle when many files are attached.',
+ description: 'Composer with removable file tokens, header actions, and a collapsible drawer. Use the collapse toggle when many files are attached, and header actions for attach and mention buttons.',
isReady: true,
aspectRatio: 16 / 9,
- componentsUsed: ['Chat', 'Token', 'ProgressBar', 'Layout', 'Text'],
+ componentsUsed: ['Chat', 'Token', 'Button', 'Icon', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.tsx b/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.tsx
index ff891bc273..291f39280c 100644
--- a/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.tsx
+++ b/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.tsx
@@ -2,9 +2,7 @@
import {XDSChatComposer, XDSChatComposerDrawer} from '@xds/core/Chat';
import {XDSToken} from '@xds/core/Token';
-import {XDSProgressBar} from '@xds/core/ProgressBar';
import {XDSStack} from '@xds/core/Layout';
-import {XDSText} from '@xds/core/Text';
import {XDSButton} from '@xds/core/Button';
import {XDSIcon} from '@xds/core/Icon';
import {PaperClipIcon, AtSymbolIcon} from '@heroicons/react/24/outline';
diff --git a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerAttachments.doc.mjs b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerAttachments.doc.mjs
new file mode 100644
index 0000000000..ed9f272c33
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerAttachments.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatComposerDrawer — Attachments',
+ description: 'Drawer with removable file tokens. Omit count to keep the drawer always expanded — use when the number of attachments is small and predictable.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'Token', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerAttachments.tsx b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerAttachments.tsx
new file mode 100644
index 0000000000..a9a82279a9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerAttachments.tsx
@@ -0,0 +1,21 @@
+'use client';
+
+import {XDSChatComposer, XDSChatComposerDrawer} from '@xds/core/Chat';
+import {XDSToken} from '@xds/core/Token';
+import {XDSStack} from '@xds/core/Layout';
+
+export default function ChatComposerDrawerAttachments() {
+ return (
+ <XDSStack direction="vertical" gap={4} width={480}>
+ <XDSChatComposer
+ onSubmit={() => {}}
+ drawer={
+ <XDSChatComposerDrawer>
+ <XDSToken label="quarterly-report.pdf" onRemove={() => {}} />
+ <XDSToken label="budget-forecast.xlsx" onRemove={() => {}} />
+ </XDSChatComposerDrawer>
+ }
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerCollapsible.doc.mjs b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerCollapsible.doc.mjs
new file mode 100644
index 0000000000..6b5aacbc12
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerCollapsible.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatComposerDrawer — Collapsible',
+ description: 'Drawer with many items and a collapse toggle. Pass count to enable the toggle — collapsed state shows a badge with the total count and a label.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'Token', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerCollapsible.tsx b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerCollapsible.tsx
new file mode 100644
index 0000000000..6c887f9425
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerCollapsible.tsx
@@ -0,0 +1,25 @@
+'use client';
+
+import {XDSChatComposer, XDSChatComposerDrawer} from '@xds/core/Chat';
+import {XDSToken} from '@xds/core/Token';
+import {XDSStack} from '@xds/core/Layout';
+
+export default function ChatComposerDrawerCollapsible() {
+ return (
+ <XDSStack direction="vertical" gap={4} width={480}>
+ <XDSChatComposer
+ onSubmit={() => {}}
+ drawer={
+ <XDSChatComposerDrawer count={6} label="Files">
+ <XDSToken label="design-spec.pdf" onRemove={() => {}} />
+ <XDSToken label="api-schema.json" onRemove={() => {}} />
+ <XDSToken label="screenshot.png" onRemove={() => {}} />
+ <XDSToken label="meeting-notes.md" onRemove={() => {}} />
+ <XDSToken label="test-results.csv" onRemove={() => {}} />
+ <XDSToken label="deploy-log.txt" onRemove={() => {}} />
+ </XDSChatComposerDrawer>
+ }
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.doc.mjs
index 971e739696..ef825eca4e 100644
--- a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.doc.mjs
@@ -2,9 +2,9 @@
export const doc = {
type: 'block',
name: 'ChatComposerDrawer',
- description: 'Composer drawer area with file tokens and collapsible overflow.',
+ description: 'Composer drawer with file tokens, a collapsible toggle, and header actions. Use as a starting point for any chat composer with attachments.',
isReady: true,
isShowcase: true,
aspectRatio: 16 / 9,
- componentsUsed: ['Chat', 'ChatComposerDrawer', 'Token'],
+ componentsUsed: ['Chat', 'Token', 'Icon', 'Button', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.tsx b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.tsx
index bb1ba8e17b..8b30f4dc2a 100644
--- a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.tsx
+++ b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.tsx
@@ -1,24 +1,45 @@
'use client';
-import {
- XDSChatComposer,
- XDSChatComposerDrawer,
-} from '@xds/core/Chat';
+import {XDSChatComposer, XDSChatComposerDrawer} from '@xds/core/Chat';
import {XDSToken} from '@xds/core/Token';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSStack} from '@xds/core/Layout';
+import {PaperClipIcon} from '@heroicons/react/24/outline';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars, borderVars, radiusVars} from '@xds/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+ drawerBorder: {
+ border: `${borderVars['--border-width']} solid ${colorVars['--color-border']}`,
+ borderRadius: radiusVars['--radius-page'],
+ },
+});
export default function ChatComposerDrawerShowcase() {
return (
- <XDSChatComposer
- onSubmit={() => {}}
- drawer={
- <XDSChatComposerDrawer count={5}>
- <XDSToken label="design-spec.pdf" onRemove={() => {}} />
- <XDSToken label="api-schema.json" onRemove={() => {}} />
- <XDSToken label="screenshot.png" onRemove={() => {}} />
- <XDSToken label="meeting-notes.md" onRemove={() => {}} />
- <XDSToken label="test-results.csv" onRemove={() => {}} />
- </XDSChatComposerDrawer>
- }
- />
+ <XDSStack direction="vertical" gap={4} width={480}>
+ <XDSChatComposer
+ onSubmit={() => {}}
+ drawer={
+ <XDSChatComposerDrawer count={4} label="Attachments" xstyle={styles.drawerBorder}>
+ <XDSToken label="design-spec.pdf" onRemove={() => {}} />
+ <XDSToken label="api-schema.json" onRemove={() => {}} />
+ <XDSToken label="screenshot.png" onRemove={() => {}} />
+ <XDSToken label="meeting-notes.md" onRemove={() => {}} />
+ </XDSChatComposerDrawer>
+ }
+ headerActions={
+ <XDSButton
+ label="Attach"
+ variant="ghost"
+ size="sm"
+ icon={<XDSIcon icon={PaperClipIcon} size="sm" />}
+ isIconOnly
+ onClick={() => {}}
+ />
+ }
+ />
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerWithProgress.doc.mjs b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerWithProgress.doc.mjs
new file mode 100644
index 0000000000..9db632fbf8
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerWithProgress.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatComposerDrawer — With Progress',
+ description: 'Drawer paired with a context progress bar in the header. Show context window usage when attachments consume part of the available token budget.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'Token', 'ProgressBar', 'Icon', 'Button', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerWithProgress.tsx b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerWithProgress.tsx
new file mode 100644
index 0000000000..95aa28765b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerWithProgress.tsx
@@ -0,0 +1,51 @@
+'use client';
+
+import {XDSChatComposer, XDSChatComposerDrawer} from '@xds/core/Chat';
+import {XDSToken} from '@xds/core/Token';
+import {XDSProgressBar} from '@xds/core/ProgressBar';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {PaperClipIcon, AtSymbolIcon} from '@heroicons/react/24/outline';
+
+export default function ChatComposerDrawerWithProgress() {
+ return (
+ <XDSStack direction="vertical" gap={4} width={480}>
+ <XDSChatComposer
+ onSubmit={() => {}}
+ drawer={
+ <XDSChatComposerDrawer count={3} label="Attachments">
+ <XDSToken label="design-spec.pdf" onRemove={() => {}} />
+ <XDSToken label="api-schema.json" onRemove={() => {}} />
+ <XDSToken label="screenshot.png" onRemove={() => {}} />
+ </XDSChatComposerDrawer>
+ }
+ headerActions={
+ <>
+ <XDSButton
+ label="Mention"
+ variant="ghost"
+ size="sm"
+ icon={<XDSIcon icon={AtSymbolIcon} size="sm" />}
+ isIconOnly
+ onClick={() => {}}
+ />
+ <XDSButton
+ label="Attach"
+ variant="ghost"
+ size="sm"
+ icon={<XDSIcon icon={PaperClipIcon} size="sm" />}
+ isIconOnly
+ onClick={() => {}}
+ />
+ </>
+ }
+ headerContext={
+ <XDSStack direction="horizontal" gap={2} vAlign="center">
+ <XDSProgressBar value={42} label="Context usage" isLabelHidden hasValueLabel />
+ </XDSStack>
+ }
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index 11d476a7fa..935385d289 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -126,10 +126,14 @@ export const docs = {
},
{
name: 'XDSChatComposerDrawer',
- description: 'Collapsible drawer panel for the composer. Use for attachments, context chips, or any supplementary content above the input.',
+ description: 'Collapsible drawer panel that sits above the chat input inside XDSChatComposer. Pass it to the composer\'s `drawer` slot to show attachments, context chips, or any supplementary content. When `count` is provided the drawer gains a collapse toggle — collapsed state shows a badge and label, expanded state shows all children.',
props: [
- {name: 'children', type: 'ReactNode', description: 'Attachment items to render.', required: true},
- {name: 'count', type: 'number', description: 'Total attachment count. When provided and exceeds visible children, shows a collapse/expand toggle.'},
+ {name: 'children', type: 'ReactNode', description: 'Content to render inside the drawer — tokens, chips, previews, or any React elements.', required: true},
+ {name: 'count', type: 'number', description: 'Total item count shown in the collapsed badge. When provided, the drawer gains a collapse/expand toggle.'},
+ {name: 'label', type: 'string', description: 'Label shown next to the count in collapsed state.', default: "'Items'"},
+ {name: 'isCollapsed', type: 'boolean', description: 'Controlled collapsed state. Use with `onCollapsedChange` for external control.'},
+ {name: 'defaultIsCollapsed', type: 'boolean', description: 'Initial collapsed state for uncontrolled usage.', default: 'false'},
+ {name: 'onCollapsedChange', type: '(isCollapsed: boolean) => void', description: 'Callback fired when the user toggles the drawer.'},
],
},
{
@@ -195,6 +199,10 @@ export const docs = {
{ guidance: false, description: 'Don\'t nest XDSChatMessage inside another XDSChatMessage — each message is a standalone article element with its own sender context.' },
{ guidance: false, description: 'Don\'t mix filled and ghost bubble variants within the same sender\'s messages — pick one style per side and use it consistently.' },
+ { guidance: true, description: 'Provide a `count` on XDSChatComposerDrawer that matches the number of children, and set a descriptive `label` like "Attachments" instead of the default "Items".' },
+ { guidance: true, description: 'Use XDSToken with `onRemove` inside XDSChatComposerDrawer so users can remove attachments individually.' },
+ { guidance: false, description: 'Don\'t omit `count` on XDSChatComposerDrawer when there are many items — without it the drawer can\'t collapse and may push the input out of view.' },
+ { guidance: false, description: 'Don\'t render XDSChatComposerDrawer outside of XDSChatComposer\'s `drawer` slot — it relies on the composer for border radius and spacing context.' },
],
anatomy: [
{ name: 'Avatar', required: false, description: 'A sender avatar rendered beside the message. Typically XDSAvatar with size="small". Hidden for system messages.' },
@@ -254,6 +262,10 @@ export const docsZh = {
{ guidance: false, description: 'Don\'t nest XDSChatMessage inside another XDSChatMessage — each message is a standalone article element with its own sender context.' },
{ guidance: false, description: 'Don\'t mix filled and ghost bubble variants within the same sender\'s messages — pick one style per side and use it consistently.' },
+ { guidance: true, description: 'Provide a `count` on XDSChatComposerDrawer that matches the number of children, and set a descriptive `label` like "Attachments" instead of the default "Items".' },
+ { guidance: true, description: 'Use XDSToken with `onRemove` inside XDSChatComposerDrawer so users can remove attachments individually.' },
+ { guidance: false, description: 'Don\'t omit `count` on XDSChatComposerDrawer when there are many items — without it the drawer can\'t collapse and may push the input out of view.' },
+ { guidance: false, description: 'Don\'t render XDSChatComposerDrawer outside of XDSChatComposer\'s `drawer` slot — it relies on the composer for border radius and spacing context.' },
],
},
components: [
@@ -345,8 +357,8 @@ export const docsZh = {
},
{
name: 'XDSChatComposerDrawer',
- description: '编写器的可折叠抽屉面板。用于附件、上下文标签或输入上方的任何补充内容。',
- propDescriptions: {children: '要渲染的附件项目。', count: '附件总数。超过可见子元素时显示折叠/展开切换。'},
+ description: '位于聊天输入上方的可折叠抽屉面板。传入 XDSChatComposer 的 `drawer` 插槽,用于显示附件、上下文标签或预览内容。提供 `count` 时启用折叠切换。',
+ propDescriptions: {children: '抽屉内渲染的内容——标记、标签、预览或任何 React 元素。', count: '折叠徽章中显示的总数。提供时,抽屉获得折叠/展开切换。', label: '折叠状态下显示在数量旁边的标签。', isCollapsed: '受控折叠状态。与 onCollapsedChange 一起使用。', defaultIsCollapsed: '非受控模式的初始折叠状态。', onCollapsedChange: '用户切换抽屉时触发的回调。'},
},
{
name: 'XDSChatSendButton',
@@ -429,6 +441,10 @@ export const docsDense = {
{ guidance: false, description: 'Nesting XDSChatMessage inside another — each is a standalone article.' },
{ guidance: false, description: 'Mix filled and ghost variants in same sender\'s messages — pick one style per side.' },
+ { guidance: true, description: 'Match `count` to children on XDSChatComposerDrawer; set a descriptive `label` like "Attachments".' },
+ { guidance: true, description: 'Use XDSToken with `onRemove` inside XDSChatComposerDrawer for individually removable attachments.' },
+ { guidance: false, description: 'Don\'t omit `count` on XDSChatComposerDrawer when there are many items — drawer can\'t collapse without it.' },
+ { guidance: false, description: 'Don\'t render XDSChatComposerDrawer outside of XDSChatComposer\'s `drawer` slot.' },
],
},
components: [
@@ -527,10 +543,14 @@ export const docsDense = {
},
{
name: 'XDSChatComposerDrawer',
- description: 'collapsible drawer panel for composer; use for attachments, context chips, or supplementary content',
+ description: 'collapsible drawer above chat input; pass to composer `drawer` slot for attachments, context chips, previews. `count` enables collapse toggle',
propDescriptions: {
- children: 'attachment items to render',
- count: 'total count; shows collapse/expand when exceeds visible',
+ children: 'drawer content — tokens, chips, previews, any React elements',
+ count: 'total count for collapsed badge; enables collapse/expand toggle',
+ label: 'collapsed label next to count badge',
+ isCollapsed: 'controlled collapsed state',
+ defaultIsCollapsed: 'initial collapsed state (uncontrolled)',
+ onCollapsedChange: 'callback on collapse toggle',
},
},
{