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.mjsindex 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.tsxindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.tsxindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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',},},{