An open source design system that's fully customizable and agent ready
TypeScript
docs: improve ChatSendButton usage docs and block examples (#1864)
Kenton Quatman941889a4911e
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.doc.mjs b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.doc.mjsnew file mode 100644index 0000000000..3d2a91dd23--- /dev/null+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'ChatSendButton — Custom Icon',+ description: 'Send buttons with custom icons via sendIcon and stopIcon props. Use to match the personality of the chat experience — a paper airplane for messaging, sparkles for AI generation, or a check mark for confirmation flows.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Chat', 'ChatSendButton', 'Icon', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.tsx b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.tsxnew file mode 100644index 0000000000..1258da0927--- /dev/null+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.tsx@@ -0,0 +1,44 @@+'use client';++import {XDSChatSendButton} from '@xds/core/Chat';+import {XDSIcon} from '@xds/core/Icon';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';+import {+ CheckIcon,+ PaperAirplaneIcon,+ SparklesIcon,+} from '@heroicons/react/24/solid';+import {XCircleIcon} from '@heroicons/react/24/outline';++export default function ChatSendButtonCustomIcon() {+ return (+ <XDSStack direction="vertical" gap={4}>+ <XDSText type="supporting" color="secondary">+ Custom icons for send and stop states+ </XDSText>+ <XDSStack direction="horizontal" gap={4} vAlign="center">+ <XDSChatSendButton+ isDisabled={false}+ onSend={() => {}}+ sendIcon={<XDSIcon icon={PaperAirplaneIcon} size="sm" />}+ />+ <XDSChatSendButton+ isDisabled={false}+ onSend={() => {}}+ sendIcon={<XDSIcon icon={CheckIcon} size="sm" />}+ />+ <XDSChatSendButton+ isDisabled={false}+ onSend={() => {}}+ sendIcon={<XDSIcon icon={SparklesIcon} size="sm" />}+ />+ <XDSChatSendButton+ isStreaming+ onStop={() => {}}+ stopIcon={<XDSIcon icon={XCircleIcon} size="sm" />}+ />+ </XDSStack>+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.doc.mjs b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.doc.mjsnew file mode 100644index 0000000000..02962b980c--- /dev/null+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'ChatSendButton — In Composer',+ description: 'Send button inside XDSChatComposer, where it reads state from context automatically. No wiring needed — the button enables when the input has content.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Chat', 'ChatComposer', 'ChatSendButton', 'Layout'],+};diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.tsx b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.tsxnew file mode 100644index 0000000000..659eb24a42--- /dev/null+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.tsx@@ -0,0 +1,23 @@+'use client';++import * as stylex from '@stylexjs/stylex';+import {XDSChatComposer} from '@xds/core/Chat';+import {XDSStack} from '@xds/core/Layout';++const styles = stylex.create({+ root: {+ maxWidth: 450,+ },+});++export default function ChatSendButtonInComposer() {+ return (+ <XDSStack direction="vertical" width="100%" xstyle={styles.root}>+ <XDSChatComposer+ onSubmit={() => {}}+ value="Hello, how can you help?"+ onChange={() => {}}+ />+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjsindex 6213bf49a6..abe925267d 100644--- a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjs+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjs@@ -2,9 +2,9 @@export const doc = {type: 'block',name: 'ChatSendButton',- description: 'Send button in default, active, streaming, custom icon, small size, and standalone states.',+ description: 'Ready, custom icon, and streaming states of the send button.',isReady: true,isShowcase: true,aspectRatio: 16 / 9,- componentsUsed: ['Chat', 'ChatSendButton', 'Icon', 'Layout', 'Text'],+ componentsUsed: ['Chat', 'ChatSendButton', 'Icon', 'Layout'],};diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsx b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsxindex 3c7463afc3..8a91836dc8 100644--- a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsx+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsx@@ -1,103 +1,20 @@'use client';-import {XDSChatComposer, XDSChatSendButton} from '@xds/core/Chat';+import {XDSChatSendButton} from '@xds/core/Chat';import {XDSIcon} from '@xds/core/Icon';import {XDSStack} from '@xds/core/Layout';-import {XDSText} from '@xds/core/Text';+import {SparklesIcon} from '@heroicons/react/24/solid';export default function ChatSendButtonShowcase() {return (- <XDSStack direction="vertical" gap={4}>- <XDSStack direction="vertical" gap={1}>- <XDSText type="supporting" color="secondary">- Default (empty input — disabled)- </XDSText>- <XDSChatComposer onSubmit={() => {}} />- </XDSStack>-- <XDSStack direction="vertical" gap={1}>- <XDSText type="supporting" color="secondary">- With content (enabled)- </XDSText>- <XDSChatComposer- onSubmit={() => {}}- value="Ready to send"- onChange={() => {}}- />- </XDSStack>-- <XDSStack direction="vertical" gap={1}>- <XDSText type="supporting" color="secondary">- Streaming (shows stop button)- </XDSText>- <XDSChatComposer- onSubmit={() => {}}- onStop={() => {}}- isStreaming- />- </XDSStack>-- <XDSStack direction="vertical" gap={1}>- <XDSText type="supporting" color="secondary">- Custom send icon- </XDSText>- <XDSChatComposer- onSubmit={() => {}}- value="Custom icon"- onChange={() => {}}- sendButton={- <XDSChatSendButton- sendIcon={<XDSIcon icon="check" size="sm" />}- onSend={() => {}}- isDisabled={false}- />- }- />- </XDSStack>-- <XDSStack direction="vertical" gap={1}>- <XDSText type="supporting" color="secondary">- Small size- </XDSText>- <XDSChatComposer- onSubmit={() => {}}- value="Small send button"- onChange={() => {}}- density="compact"- sendButton={- <XDSChatSendButton- size="sm"- onSend={() => {}}- isDisabled={false}- />- }- />- </XDSStack>-- <XDSStack direction="vertical" gap={1}>- <XDSText type="supporting" color="secondary">- Standalone (outside composer context)- </XDSText>- <XDSStack direction="horizontal" gap={2} vAlign="center">- <XDSChatSendButton- isDisabled={true}- onSend={() => {}}- />- <XDSChatSendButton- isDisabled={false}- onSend={() => {}}- />- <XDSChatSendButton- isStreaming={true}- onStop={() => {}}- />- <XDSChatSendButton- size="sm"- isDisabled={false}- onSend={() => {}}- />- </XDSStack>- </XDSStack>+ <XDSStack direction="horizontal" gap={3} vAlign="center">+ <XDSChatSendButton isDisabled={false} onSend={() => {}} />+ <XDSChatSendButton+ isDisabled={false}+ onSend={() => {}}+ sendIcon={<XDSIcon icon={SparklesIcon} size="sm" />}+ />+ <XDSChatSendButton isStreaming onStop={() => {}} /></XDSStack>);}diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.doc.mjs b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.doc.mjsnew file mode 100644index 0000000000..bf0b082eb9--- /dev/null+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'ChatSendButton — States',+ description: 'Disabled, ready, and streaming states at both sizes. The button automatically toggles between send (primary) and stop (secondary) based on streaming state.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Chat', 'ChatSendButton', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.tsx b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.tsxnew file mode 100644index 0000000000..4e11893333--- /dev/null+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.tsx@@ -0,0 +1,20 @@+'use client';++import {XDSChatSendButton} from '@xds/core/Chat';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++export default function ChatSendButtonStates() {+ return (+ <XDSStack direction="vertical" gap={2}>+ <XDSText type="supporting" color="secondary">+ Disabled → Ready → Streaming+ </XDSText>+ <XDSStack direction="horizontal" gap={3} vAlign="center">+ <XDSChatSendButton isDisabled onSend={() => {}} />+ <XDSChatSendButton isDisabled={false} onSend={() => {}} />+ <XDSChatSendButton isStreaming onStop={() => {}} />+ </XDSStack>+ </XDSStack>+ );+}diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjsindex 181cf551e4..314a1fe802 100644--- a/packages/core/src/Chat/Chat.doc.mjs+++ b/packages/core/src/Chat/Chat.doc.mjs@@ -138,7 +138,7 @@ export const docs = {},{name: 'XDSChatSendButton',- description: 'Circular send/stop toggle button for the composer. Reads state from XDSChatComposerContext by default so it works automatically inside XDSChatComposer. All context values can be overridden via props for standalone usage.',+ description: 'Circular send/stop toggle button for the chat composer. Place it inside XDSChatComposer where it reads context automatically — no wiring needed. When streaming starts, the button switches from a primary send icon to a secondary stop icon. Override any context value via props for standalone or custom usage.',props: [{name: 'isStreaming', type: 'boolean', description: 'Whether the assistant is currently streaming. Defaults to context value.'},{name: 'isDisabled', type: 'boolean', description: 'Whether the send button is disabled. Defaults to !canSend from context.'},@@ -212,6 +212,9 @@ export const docs = {{ guidance: false, description: 'Don\'t apply a fixed height directly on XDSChatLayout — wrap it in a sized container and let the layout fill with flex: 1.' },{ guidance: true, description: 'Show a label on XDSChatLayoutScrollButton (e.g. "New messages") when unread content arrives below the fold so the user knows there is something to see.' },{ guidance: false, description: 'Don\'t rebuild the scroll-to-bottom button from scratch — use XDSChatLayoutScrollButton or pass a custom element to XDSChatLayout\'s scrollButton prop.' },+ { guidance: true, description: 'Let XDSChatSendButton read state from XDSChatComposerContext by default — it handles disabled, send, and stop states automatically. Only override via props when using the button standalone or replacing the default icon.' },+ { guidance: false, description: 'Don\'t manually wire isDisabled on XDSChatSendButton inside a composer — the context already tracks whether the input has content. Override only for custom validation logic.' },+ { guidance: false, description: 'Don\'t use XDSChatSendButton for non-chat submit actions — use XDSButton instead. The send button is purpose-built for the chat composer flow.' },],anatomy: [{ name: 'Message area', required: true, description: 'Scrollable region for messages. Renders children (typically XDSChatMessageList) in a flex column that pushes content to the bottom when the list is short.' },@@ -289,6 +292,9 @@ export const docsZh = {{ guidance: false, description: 'Don\'t apply a fixed height directly on XDSChatLayout — wrap it in a sized container and let the layout fill with flex: 1.' },{ guidance: true, description: 'Show a label on XDSChatLayoutScrollButton (e.g. "New messages") when unread content arrives below the fold so the user knows there is something to see.' },{ guidance: false, description: 'Don\'t rebuild the scroll-to-bottom button from scratch — use XDSChatLayoutScrollButton or pass a custom element to XDSChatLayout\'s scrollButton prop.' },+ { guidance: true, description: 'Let XDSChatSendButton read state from XDSChatComposerContext by default — it handles disabled, send, and stop states automatically. Only override via props when using the button standalone or replacing the default icon.' },+ { guidance: false, description: 'Don\'t manually wire isDisabled on XDSChatSendButton inside a composer — the context already tracks whether the input has content. Override only for custom validation logic.' },+ { guidance: false, description: 'Don\'t use XDSChatSendButton for non-chat submit actions — use XDSButton instead. The send button is purpose-built for the chat composer flow.' },],anatomy: [{ name: 'Message area', required: true, description: 'Scrollable region for messages. Renders children (typically XDSChatMessageList) in a flex column that pushes content to the bottom when the list is short.' },@@ -484,6 +490,9 @@ export const docsDense = {{ guidance: false, description: 'Fixed height on XDSChatLayout directly — wrap in a sized container, let flex: 1 fill.' },{ guidance: true, description: 'Show a label on XDSChatLayoutScrollButton when unread content arrives below the fold.' },{ guidance: false, description: 'Don\'t rebuild the scroll-to-bottom button — use XDSChatLayoutScrollButton or pass a custom element to scrollButton.' },+ { guidance: true, description: 'Let ChatSendButton read context by default. Override only for standalone use or custom icons.' },+ { guidance: false, description: 'Don\'t manually wire isDisabled on ChatSendButton inside a composer — context already tracks it.' },+ { guidance: false, description: 'Don\'t use ChatSendButton for non-chat actions — use XDSButton instead.' },],},components: [