Skip to content

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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
deleted file mode 100644
index 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.tsx
deleted file mode 100644
index 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.mjs
new file mode 100644
index 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.tsx
new file mode 100644
index 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.mjs
new file mode 100644
index 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',
+ },
+};