An open source design system that's fully customizable and agent ready
TypeScript
Improve ChatDictationButton docs page and block examples (#1857)
Kenton Quatman5da81712a282
diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.doc.mjs b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.doc.mjsindex e84f5b4846..733e2b5344 100644--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.doc.mjs+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.doc.mjs@@ -1,9 +1,9 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'ChatDictation — In Composer',- description: 'Interactive dictation button placed in the sendActions slot of a chat composer.',+ name: 'ChatDictationButton — In Composer',+ description: 'Dictation button placed in the sendActions slot of a chat composer. Shows the recommended integration point for voice input alongside the send button.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Chat', 'ChatDictation', 'ChatComposer', 'ChatComposerInput'],+ aspectRatio: 16 / 9,+ componentsUsed: ['ChatDictation', 'ChatComposer', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.tsx b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.tsxindex 0576d95356..44cf81bbdd 100644--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.tsx+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.tsx@@ -1,28 +1,44 @@'use client';-import {useRef} from 'react';import {XDSChatDictationButton,XDSChatComposer,- XDSChatComposerInput,- useXDSChatDictation,} from '@xds/core/Chat';-import type {XDSChatComposerInputHandle} from '@xds/core/Chat';+import type {UseSpeechRecognitionReturn} from '@xds/core/Chat';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';-export default function ChatDictationDictationInComposer() {- const inputRef = useRef<XDSChatComposerInputHandle>(null);+const noop = () => {};- const dictation = useXDSChatDictation({- inputRef,- hasSounds: true,- });+const idleDictation: UseSpeechRecognitionReturn = {+ volume: 0,+ rawBands: [0, 0, 0, 0, 0],+ bands: [0, 0, 0, 0, 0],+ isSupported: true,+ isListening: false,+ isSpeaking: false,+ interimTranscript: '',+ start: noop,+ stop: noop,+ abort: noop,+ toggle: noop,+};+export default function ChatDictationDictationInComposer() {return (- <XDSChatComposer- onSubmit={() => {}}- placeholder="Type or tap the mic to dictate..."- input={<XDSChatComposerInput ref={inputRef} />}- sendActions={<XDSChatDictationButton dictation={dictation} />}- />+ <XDSStack+ direction="vertical"+ gap={3}+ style={{width: '100%', maxWidth: 450}}+ >+ <XDSText type="supporting" color="secondary">+ Dictation button in the sendActions slot+ </XDSText>+ <XDSChatComposer+ onSubmit={() => {}}+ placeholder="Type or tap the mic to dictate..."+ sendActions={<XDSChatDictationButton dictation={idleDictation} />}+ />+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.doc.mjs b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.doc.mjsindex d8f4355c0e..61d7d6ec1c 100644--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.doc.mjs+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.doc.mjs@@ -1,9 +1,9 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'ChatDictation — States',- description: 'Dictation button in idle, listening, and speaking states side by side.',+ name: 'ChatDictationButton — States',+ description: 'Dictation button in idle, listening, and speaking states side by side. Shows the three visual phases of a voice input interaction.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Chat', 'ChatDictation'],+ aspectRatio: 16 / 9,+ componentsUsed: ['ChatDictation', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.tsx b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.tsxindex 6354913801..dd545c51da 100644--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.tsx+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.tsx@@ -2,12 +2,12 @@import {XDSChatDictationButton} from '@xds/core/Chat';import type {UseSpeechRecognitionReturn} from '@xds/core/Chat';-import {XDSHStack, XDSVStack} from '@xds/core/Layout';+import {XDSStack} from '@xds/core/Layout';import {XDSText} from '@xds/core/Text';const noop = () => {};-const base: UseSpeechRecognitionReturn = {+const idle: UseSpeechRecognitionReturn = {volume: 0,rawBands: [0, 0, 0, 0, 0],bands: [0, 0, 0, 0, 0],@@ -21,41 +21,60 @@ const base: UseSpeechRecognitionReturn = {toggle: noop,};-const idle: UseSpeechRecognitionReturn = {...base};-const listening: UseSpeechRecognitionReturn = {- ...base,volume: 0.05,rawBands: [0.08, 0.06, 0.04, 0.02, 0.01],bands: [0.08, 0.06, 0.04, 0.02, 0.01],+ isSupported: true,isListening: true,+ isSpeaking: false,+ interimTranscript: '',+ start: noop,+ stop: noop,+ abort: noop,+ toggle: noop,};const speaking: UseSpeechRecognitionReturn = {- ...base,volume: 0.12,rawBands: [0.15, 0.12, 0.08, 0.05, 0.02],bands: [0.15, 0.12, 0.08, 0.05, 0.02],+ isSupported: true,isListening: true,isSpeaking: true,interimTranscript: 'hello world',+ start: noop,+ stop: noop,+ abort: noop,+ toggle: noop,};export default function ChatDictationDictationStates() {return (- <XDSHStack gap={6} vAlign="center">- <XDSVStack gap={2} hAlign="center">- <XDSChatDictationButton dictation={idle} />- <XDSText type="supporting" color="secondary">Idle</XDSText>- </XDSVStack>- <XDSVStack gap={2} hAlign="center">- <XDSChatDictationButton dictation={listening} />- <XDSText type="supporting" color="secondary">Listening</XDSText>- </XDSVStack>- <XDSVStack gap={2} hAlign="center">- <XDSChatDictationButton dictation={speaking} />- <XDSText type="supporting" color="secondary">Speaking</XDSText>- </XDSVStack>- </XDSHStack>+ <XDSStack direction="vertical" gap={4}>+ <XDSText type="supporting" color="secondary">+ Three states of a dictation interaction+ </XDSText>+ <XDSStack direction="horizontal" gap={6} hAlign="center">+ <XDSStack direction="vertical" gap={1} hAlign="center">+ <XDSChatDictationButton dictation={idle} />+ <XDSText type="supporting" color="secondary">+ Idle+ </XDSText>+ </XDSStack>+ <XDSStack direction="vertical" gap={1} hAlign="center">+ <XDSChatDictationButton dictation={listening} />+ <XDSText type="supporting" color="secondary">+ Listening+ </XDSText>+ </XDSStack>+ <XDSStack direction="vertical" gap={1} hAlign="center">+ <XDSChatDictationButton dictation={speaking} />+ <XDSText type="supporting" color="secondary">+ Speaking+ </XDSText>+ </XDSStack>+ </XDSStack>+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.doc.mjsdeleted file mode 100644index b9cad52377..0000000000--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'ChatDictation',- description: 'Interactive dictation in a composer — connected to the SpeechRecognition API via useXDSChatDictation.',- isReady: true,- isShowcase: true,- aspectRatio: 4 / 3,- componentsUsed: ['Chat', 'ChatDictation', 'ChatComposer', 'ChatComposerInput'],-};diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.tsx b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.tsxdeleted file mode 100644index a3ca57f1af..0000000000--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.tsx+++ /dev/null@@ -1,30 +0,0 @@-'use client';--import {useRef} from 'react';-import {- XDSChatDictationButton,- XDSChatComposer,- XDSChatComposerInput,- useXDSChatDictation,-} from '@xds/core/Chat';-import type {XDSChatComposerInputHandle} from '@xds/core/Chat';--export default function ChatDictationShowcase() {- const inputRef = useRef<XDSChatComposerInputHandle>(null);-- const dictation = useXDSChatDictation({- inputRef,- hasSounds: true,- onResult: (text) => {- console.log('Dictation result:', text);- },- });-- return (- <XDSChatComposer- onSubmit={(v) => console.log('Submit:', v)}- input={<XDSChatComposerInput ref={inputRef} />}- sendActions={<XDSChatDictationButton dictation={dictation} />}- />- );-}diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationSizes.doc.mjs b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationSizes.doc.mjsnew file mode 100644index 0000000000..b79364366b--- /dev/null+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationSizes.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'ChatDictationButton — Sizes',+ description: 'Small and medium dictation buttons side by side. Use small in compact composer densities and medium for standard layouts.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['ChatDictation', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationSizes.tsx b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationSizes.tsxnew file mode 100644index 0000000000..cdfba13fc3--- /dev/null+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationSizes.tsx@@ -0,0 +1,61 @@+'use client';++import {XDSChatDictationButton} from '@xds/core/Chat';+import type {UseSpeechRecognitionReturn} from '@xds/core/Chat';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++const noop = () => {};++const idleDictation: UseSpeechRecognitionReturn = {+ volume: 0,+ rawBands: [0, 0, 0, 0, 0],+ bands: [0, 0, 0, 0, 0],+ isSupported: true,+ isListening: false,+ isSpeaking: false,+ interimTranscript: '',+ start: noop,+ stop: noop,+ abort: noop,+ toggle: noop,+};++const listeningDictation: UseSpeechRecognitionReturn = {+ volume: 0.05,+ rawBands: [0.08, 0.06, 0.04, 0.02, 0.01],+ bands: [0.08, 0.06, 0.04, 0.02, 0.01],+ isSupported: true,+ isListening: true,+ isSpeaking: false,+ interimTranscript: '',+ start: noop,+ stop: noop,+ abort: noop,+ toggle: noop,+};++export default function ChatDictationSizes() {+ return (+ <XDSStack direction="vertical" gap={4}>+ <XDSStack direction="vertical" gap={1}>+ <XDSText type="supporting" color="secondary">+ Small+ </XDSText>+ <XDSStack direction="horizontal" gap={4} vAlign="center">+ <XDSChatDictationButton dictation={idleDictation} size="sm" />+ <XDSChatDictationButton dictation={listeningDictation} size="sm" />+ </XDSStack>+ </XDSStack>+ <XDSStack direction="vertical" gap={1}>+ <XDSText type="supporting" color="secondary">+ Medium+ </XDSText>+ <XDSStack direction="horizontal" gap={4} vAlign="center">+ <XDSChatDictationButton dictation={idleDictation} size="md" />+ <XDSChatDictationButton dictation={listeningDictation} size="md" />+ </XDSStack>+ </XDSStack>+ </XDSStack>+ );+}diff --git a/packages/core/src/Chat/ChatDictationButton.doc.mjs b/packages/core/src/Chat/ChatDictationButton.doc.mjsnew file mode 100644index 0000000000..a4942121bc--- /dev/null+++ b/packages/core/src/Chat/ChatDictationButton.doc.mjs@@ -0,0 +1,106 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'ChatDictationButton',+ group: 'Chat',+ hidden: true,++ keywords: ['dictation', 'microphone', 'voice', 'speech', 'recording', 'stt', 'speech-to-text', 'voice-input', 'mic'],++ usage: {+ description:+ 'ChatDictationButton is a toggle button that starts and stops voice dictation inside a chat composer. It pairs with useXDSChatDictation to show a microphone icon when idle and animated frequency bars when listening. Place it in the sendActions slot of XDSChatComposer.',+ bestPractices: [+ {guidance: true, description: 'Place the dictation button in the sendActions slot of XDSChatComposer so it sits next to the send button where users expect voice input controls.'},+ {guidance: true, description: 'Pass an inputRef to useXDSChatDictation so interim transcripts appear as ghost text in the composer input while the user speaks.'},+ {guidance: true, description: "Enable hasSounds on useXDSChatDictation to give users audio feedback when dictation starts and stops \u2014 especially helpful when the button's visual change is subtle."},+ {guidance: false, description: "Don't use the dictation button outside a chat composer context \u2014 it's designed for the composer's send-action layout, not as a standalone recording control."},+ {guidance: false, description: "Don't forget to handle the unsupported case \u2014 the button hides itself by default when the browser lacks SpeechRecognition, but you should still design the composer to work without it."},+ ],+ anatomy: [+ {name: 'Microphone icon', required: true, description: 'Shown in the idle state. Indicates that tapping will start voice input.'},+ {name: 'Frequency bars', required: false, description: 'Animated equalizer bars that replace the icon during listening. React to real microphone volume.'},+ {name: 'Ghost button', required: true, description: 'The underlying XDSButton with ghost variant and isIconOnly, providing the hit target and focus ring.'},+ ],+ },++ props: [+ {+ name: 'dictation',+ type: 'UseSpeechRecognitionReturn',+ description:+ 'The return value from useXDSChatDictation or useSpeechRecognition. Controls all button state \u2014 listening, volume, bands, and toggle.',+ required: true,+ },+ {+ name: 'size',+ type: "'sm' | 'md'",+ description: 'Button size. Matches XDSChatComposer density.',+ default: "'md'",+ },+ {+ name: 'isHiddenWhenUnsupported',+ type: 'boolean',+ description:+ 'When true, renders nothing if the browser does not support SpeechRecognition.',+ default: 'true',+ },+ {+ name: 'label',+ type: 'string',+ description:+ 'Accessible label override. Defaults to "Start dictation" or "Stop dictation" based on state.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description: 'Additional StyleX styles applied to the wrapper.',+ },+ ],++};++/** @type {import('../docs-types').TranslationDoc} */+export const docsZh = {+ usage: {+ description:+ 'ChatDictationButton is a toggle button that starts and stops voice dictation inside a chat composer. It pairs with useXDSChatDictation to show a microphone icon when idle and animated frequency bars when listening. Place it in the sendActions slot of XDSChatComposer.',+ bestPractices: [+ {guidance: true, description: 'Place the dictation button in the sendActions slot of XDSChatComposer so it sits next to the send button where users expect voice input controls.'},+ {guidance: true, description: 'Pass an inputRef to useXDSChatDictation so interim transcripts appear as ghost text in the composer input while the user speaks.'},+ {guidance: true, description: "Enable hasSounds on useXDSChatDictation to give users audio feedback when dictation starts and stops \u2014 especially helpful when the button's visual change is subtle."},+ {guidance: false, description: "Don't use the dictation button outside a chat composer context \u2014 it's designed for the composer's send-action layout, not as a standalone recording control."},+ {guidance: false, description: "Don't forget to handle the unsupported case \u2014 the button hides itself by default when the browser lacks SpeechRecognition, but you should still design the composer to work without it."},+ ],+ },+ propDescriptions: {+ dictation: 'The return value from useXDSChatDictation or useSpeechRecognition. Controls all button state.',+ size: 'Button size.',+ isHiddenWhenUnsupported: 'When true, renders nothing if SpeechRecognition is unsupported.',+ label: 'Accessible label override.',+ xstyle: 'Additional StyleX styles.',+ },+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsDense = {+ description: 'mic toggle btn for voice input in chat composer; idle=mic icon, listening=freq bars; pairs w/ useXDSChatDictation',+ usage: {+ description:+ 'Toggle button for voice dictation in chat composer. Pairs with useXDSChatDictation. Shows mic icon when idle, animated frequency bars when listening. Goes in sendActions slot.',+ bestPractices: [+ {guidance: true, description: 'Place in sendActions slot of XDSChatComposer next to send button.'},+ {guidance: true, description: 'Pass inputRef to useXDSChatDictation for interim ghost text in input.'},+ {guidance: true, description: 'Enable hasSounds for audio feedback on start/stop.'},+ {guidance: false, description: "Don't use outside chat composer context \u2014 designed for composer send-action layout only."},+ {guidance: false, description: "Don't forget unsupported case \u2014 button auto-hides but composer should work without it."},+ ],+ },+ propDescriptions: {+ dictation: 'return from useXDSChatDictation/useSpeechRecognition; controls state',+ size: 'btn size',+ isHiddenWhenUnsupported: 'hide when SpeechRecognition unsupported',+ label: 'a11y label override',+ xstyle: 'extra StyleX styles',+ },+};