Skip to content

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

TypeScript

Improve ChatToolCalls docs page and block examples (#1895)

Kenton Quatman632121dfd6c0
diff --git a/packages/cli/templates/blocks/components/Chat/ChatToolCalls.doc.mjs b/packages/cli/templates/blocks/components/Chat/ChatToolCalls.doc.mjs
index 7e2bb35edf..3cbcafcd52 100644
--- a/packages/cli/templates/blocks/components/Chat/ChatToolCalls.doc.mjs
+++ b/packages/cli/templates/blocks/components/Chat/ChatToolCalls.doc.mjs
@@ -2,8 +2,8 @@
export const doc = {
type: 'block',
name: 'Chat — Tool Calls',
- description: 'Tool call display in single, multiple, error, and running states. Single calls render inline; multiple calls collapse into a summary. Use for showing LLM function invocations with duration, diff stats, and status.',
+ description: 'Tool call display in single, multiple, error, and running states. Single calls render inline; multiple calls collapse into a summary.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['Chat', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsInteractiveToolCalls.doc.mjs b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsInteractiveToolCalls.doc.mjs
index cc75914256..ec1746bae4 100644
--- a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsInteractiveToolCalls.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsInteractiveToolCalls.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'ChatToolCalls — Interactive',
- description:
- 'Tool calls with expandable result details showing diffs and test output in code blocks.',
+ name: 'ChatToolCalls — Expandable',
+ description: 'Tool calls with expandable result details showing diffs and command output in code blocks. Click a row to reveal its result.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['ChatToolCalls', 'CodeBlock'],
};
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsInteractiveToolCalls.tsx b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsInteractiveToolCalls.tsx
index c2a92451b5..f129c1f7ab 100644
--- a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsInteractiveToolCalls.tsx
+++ b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsInteractiveToolCalls.tsx
@@ -3,36 +3,40 @@
import {XDSChatToolCalls} from '@xds/core/Chat';
import {XDSCodeBlock} from '@xds/core/CodeBlock';
-const editDiff = `--- a/packages/core/src/Button/XDSButton.tsx
-+++ b/packages/core/src/Button/XDSButton.tsx
-@@ -55,7 +55,7 @@
-- borderRadius: 'var(--button-radius)',
-+ borderRadius: 'var(--button-radius, var(--radius-element))',
-@@ -93,6 +93,10 @@
-+ focusVisible: {
-+ outline: '2px solid var(--color-ring-focus)',
-+ outlineOffset: '2px',
-+ },`;
+const editDiff = `--- a/src/utils/formatDate.ts
++++ b/src/utils/formatDate.ts
+@@ -8,7 +8,11 @@
+-export function formatDate(date: Date): string {
+- return date.toLocaleDateString();
+-}
++export function formatDate(
++ date: Date,
++ locale = 'en-US',
++ options?: Intl.DateTimeFormatOptions,
++): string {
++ return new Intl.DateTimeFormat(locale, options).format(date);
++}`;
const testOutput = `$ yarn test
- PASS packages/core/src/Button/XDSButton.test.tsx
- PASS packages/core/src/Chat/XDSChatToolCalls.test.tsx
+ PASS src/utils/formatDate.test.ts
+ PASS src/components/DatePicker.test.tsx
-Test Suites: 7 passed, 7 total
-Tests: 67 passed, 67 total
-Time: 6.1s`;
+Test Suites: 2 passed, 2 total
+Tests: 14 passed, 14 total
+Time: 1.8s`;
export default function ChatToolCallsInteractiveToolCalls() {
return (
<XDSChatToolCalls
+ defaultIsExpanded
calls={[
{
name: 'edit',
- target: 'XDSButton.tsx',
+ target: 'src/utils/formatDate.ts',
status: 'complete',
duration: '85ms',
node: 'cli:devvm',
- additions: 12,
+ additions: 6,
deletions: 3,
resultDetail: (
<XDSCodeBlock
@@ -46,7 +50,7 @@ export default function ChatToolCallsInteractiveToolCalls() {
name: 'bash',
target: 'yarn test',
status: 'complete',
- duration: '6.1s',
+ duration: '1.8s',
node: 'cli:devvm',
resultDetail: (
<XDSCodeBlock
@@ -58,9 +62,9 @@ export default function ChatToolCallsInteractiveToolCalls() {
},
{
name: 'web_search',
- target: 'CSS anchor positioning',
+ target: 'Intl.DateTimeFormat locale options',
status: 'complete',
- duration: '1.8s',
+ duration: '1.2s',
},
]}
/>
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsMultipleToolCalls.doc.mjs b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsMultipleToolCalls.doc.mjs
deleted file mode 100644
index b4f860c55e..0000000000
--- a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsMultipleToolCalls.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'ChatToolCalls — Multiple Calls',
- description:
- 'Collapsible group of completed tool calls with duration and diff stats.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ChatToolCalls'],
-};
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsMultipleToolCalls.tsx b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsMultipleToolCalls.tsx
deleted file mode 100644
index 8b06a1c731..0000000000
--- a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsMultipleToolCalls.tsx
+++ /dev/null
@@ -1,32 +0,0 @@
-'use client';
-
-import {XDSChatToolCalls} from '@xds/core/Chat';
-
-export default function ChatToolCallsMultipleToolCalls() {
- return (
- <XDSChatToolCalls
- calls={[
- {
- name: 'bash',
- target: 'git diff --stat',
- status: 'complete',
- duration: '340ms',
- },
- {
- name: 'read',
- target: 'src/Button.tsx',
- status: 'complete',
- duration: '45ms',
- },
- {
- name: 'edit',
- target: 'src/Button.tsx',
- status: 'complete',
- duration: '120ms',
- additions: 12,
- deletions: 3,
- },
- ]}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsShowcase.doc.mjs
index ee06a7afd9..dfbdf01378 100644
--- a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsShowcase.doc.mjs
@@ -3,6 +3,6 @@ export const doc = {
type: 'block',
name: 'ChatToolCalls',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
isShowcase: true,
};
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsShowcase.tsx b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsShowcase.tsx
index 35b5e6b05e..88c68e54d7 100644
--- a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsShowcase.tsx
+++ b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsShowcase.tsx
@@ -5,12 +5,27 @@ import {XDSChatToolCalls} from '@xds/core/Chat';
export default function ChatToolCallsShowcase() {
return (
<XDSChatToolCalls
+ defaultIsExpanded
calls={[
{
name: 'bash',
- target: 'git status',
+ target: 'git diff --stat',
status: 'complete',
- duration: '1.2s',
+ duration: '340ms',
+ },
+ {
+ name: 'read',
+ target: 'src/utils/formatDate.ts',
+ status: 'complete',
+ duration: '45ms',
+ },
+ {
+ name: 'edit',
+ target: 'src/utils/formatDate.ts',
+ status: 'complete',
+ duration: '120ms',
+ additions: 12,
+ deletions: 3,
},
]}
/>
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsStatuses.doc.mjs b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsStatuses.doc.mjs
new file mode 100644
index 0000000000..825a8376d6
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsStatuses.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatToolCalls — Statuses',
+ description: 'All four status states — pending, running, complete, and error — shown together in a single group.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ChatToolCalls'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsStatuses.tsx b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsStatuses.tsx
new file mode 100644
index 0000000000..792ea87e3b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsStatuses.tsx
@@ -0,0 +1,42 @@
+'use client';
+
+import {XDSChatToolCalls} from '@xds/core/Chat';
+
+export default function ChatToolCallsStatuses() {
+ return (
+ <XDSChatToolCalls
+ defaultIsExpanded
+ calls={[
+ {
+ key: 'pending',
+ name: 'bash',
+ target: 'yarn build',
+ status: 'pending',
+ },
+ {
+ key: 'running',
+ name: 'bash',
+ target: 'yarn test',
+ status: 'running',
+ },
+ {
+ key: 'complete',
+ name: 'edit',
+ target: 'src/App.tsx',
+ status: 'complete',
+ duration: '120ms',
+ additions: 8,
+ deletions: 2,
+ },
+ {
+ key: 'error',
+ name: 'bash',
+ target: 'yarn lint',
+ status: 'error',
+ duration: '0.8s',
+ errorMessage: '3 lint errors found',
+ },
+ ]}
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithErrors.doc.mjs b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithErrors.doc.mjs
deleted file mode 100644
index 574a4a2287..0000000000
--- a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithErrors.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'ChatToolCalls — With Errors',
- description:
- 'Tool call group with a failed test run showing error output in a code block detail.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ChatToolCalls', 'CodeBlock'],
-};
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithErrors.tsx b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithErrors.tsx
deleted file mode 100644
index b99e50a593..0000000000
--- a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithErrors.tsx
+++ /dev/null
@@ -1,54 +0,0 @@
-'use client';
-
-import {XDSChatToolCalls} from '@xds/core/Chat';
-import {XDSCodeBlock} from '@xds/core/CodeBlock';
-
-const errorOutput = `$ yarn test
- PASS packages/core/src/Chat/XDSChatReasoning.test.tsx (7 tests)
- FAIL packages/core/src/Chat/XDSChatToolCalls.test.tsx
-
- ● XDSChatToolCalls > renders group header for multiple calls
-
- ReferenceError: hasError is not defined
-
-Test Suites: 1 failed, 6 passed, 7 total
-Tests: 4 failed, 63 passed, 67 total
-Time: 6.84s`;
-
-export default function ChatToolCallsToolCallsWithErrors() {
- return (
- <XDSChatToolCalls
- calls={[
- {
- name: 'bash',
- target: 'yarn build',
- status: 'complete',
- duration: '8s',
- node: 'cli:devvm',
- },
- {
- name: 'read',
- target: 'XDSChatToolCalls.tsx',
- status: 'complete',
- duration: '15ms',
- node: 'cli:devvm',
- },
- {
- name: 'bash',
- target: 'yarn test',
- status: 'error',
- duration: '6.8s',
- node: 'cli:devvm',
- errorMessage: '4 tests failed',
- resultDetail: (
- <XDSCodeBlock
- code={errorOutput}
- language="bash"
- maxHeight="50vh"
- />
- ),
- },
- ]}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithNodes.doc.mjs b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithNodes.doc.mjs
index ccaf64fa7b..d3f92e0b94 100644
--- a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithNodes.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithNodes.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'ChatToolCalls — With Nodes',
- description:
- 'Tool calls with node badges showing which sandbox or environment ran each tool.',
+ name: 'ChatToolCalls — Simple',
+ description: 'A single inline tool call above a collapsible multi-call group with diff stats. Shows both layouts side by side.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ChatToolCalls'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['ChatToolCalls', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithNodes.tsx b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithNodes.tsx
index 246753112a..8730d7ff9e 100644
--- a/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithNodes.tsx
+++ b/packages/cli/templates/blocks/components/ChatToolCalls/ChatToolCallsToolCallsWithNodes.tsx
@@ -1,39 +1,47 @@
'use client';
import {XDSChatToolCalls} from '@xds/core/Chat';
+import {XDSStack} from '@xds/core/Layout';
-export default function ChatToolCallsToolCallsWithNodes() {
+export default function ChatToolCallsSimple() {
return (
- <XDSChatToolCalls
- calls={[
- {
- name: 'bash',
- target: 'yarn test',
- status: 'complete',
- duration: '4.2s',
- node: 'cli:devvm',
- },
- {
- name: 'bash',
- target: 'yarn build',
- status: 'complete',
- duration: '12s',
- node: 'cli:devvm',
- },
- {
- name: 'read',
- target: 'README.md',
- status: 'complete',
- duration: '30ms',
- node: 'workspace',
- },
- {
- name: 'web_search',
- target: 'CSS anchor positioning',
- status: 'complete',
- duration: '1.8s',
- },
- ]}
- />
+ <XDSStack direction="vertical" gap={4}>
+ <XDSChatToolCalls
+ calls={[
+ {
+ name: 'bash',
+ target: 'git status',
+ status: 'complete',
+ duration: '1.2s',
+ },
+ ]}
+ />
+ <XDSChatToolCalls
+ defaultIsExpanded
+ calls={[
+ {
+ name: 'read',
+ target: 'src/components/DataGrid.tsx',
+ status: 'complete',
+ duration: '30ms',
+ },
+ {
+ name: 'edit',
+ target: 'src/components/DataGrid.tsx',
+ status: 'complete',
+ duration: '85ms',
+ additions: 24,
+ deletions: 8,
+ },
+ {
+ name: 'edit',
+ target: 'src/components/DataGrid.test.tsx',
+ status: 'complete',
+ duration: '60ms',
+ additions: 45,
+ },
+ ]}
+ />
+ </XDSStack>
);
}
diff --git a/packages/core/src/Chat/ChatToolCalls.doc.mjs b/packages/core/src/Chat/ChatToolCalls.doc.mjs
new file mode 100644
index 0000000000..83502734c4
--- /dev/null
+++ b/packages/core/src/Chat/ChatToolCalls.doc.mjs
@@ -0,0 +1,113 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatToolCalls',
+ group: 'Chat',
+
+ keywords: ['tool', 'function', 'call', 'invocation', 'llm', 'agent', 'bash', 'edit', 'read', 'search', 'status', 'running', 'error', 'complete', 'diff', 'stats'],
+
+ usage: {
+ description:
+ 'ChatToolCalls displays tool or function call invocations from an LLM response. Pass an array of calls and the component handles the rest — a single call renders inline, while multiple calls collapse into a summary with the latest call visible at the surface. Use it anywhere an AI agent shows what actions it took.',
+ bestPractices: [
+ {guidance: true, description: 'Include a target string on every call so the user can see what the tool acted on — a file path, a shell command, or a search query.'},
+ {guidance: true, description: 'Show a duration on completed calls so users can judge which tools are slow and understand why a response took time.'},
+ {guidance: true, description: 'Provide resultDetail with a code block for calls that produce output — diffs for edits, terminal output for shell commands — so users can inspect results inline.'},
+ {guidance: true, description: 'Set a unique key on each call item when streaming so React can animate additions without re-mounting completed rows.'},
+ {guidance: false, description: "Don't omit the status field — without it the call defaults to complete, which is misleading for calls that are still running or have failed."},
+ {guidance: false, description: "Don't display tool calls outside a chat message context — they are designed to sit inside an assistant message, not as standalone UI."},
+ {guidance: false, description: "Don't use custom wrappers around individual calls — the component handles single vs. grouped layout automatically based on the array length."},
+ ],
+ anatomy: [
+ {name: 'Status icon', required: true, description: 'A colored circle with a check, cross, or spinner indicating whether the call is pending, running, complete, or errored.'},
+ {name: 'Tool name', required: true, description: 'The function or tool name displayed in monospace — bash, edit, read, web_search, etc.'},
+ {name: 'Node badge', required: false, description: 'A neutral pill badge showing which sandbox or environment ran the tool, like cli:devvm or workspace.'},
+ {name: 'Target label', required: false, description: 'The target of the action — a file path, command, or search query — shown after the tool name.'},
+ {name: 'Diff stats', required: false, description: 'Green additions and red deletions counts for edit operations, displayed inline after the target.'},
+ {name: 'Duration', required: false, description: 'Execution time shown on the trailing edge for completed calls.'},
+ {name: 'Group header', required: false, description: 'A wrench icon with a call count, shown when multiple calls are present. Clicking toggles between the summary and the full list.'},
+ ],
+ },
+
+ props: [
+ {
+ name: 'calls',
+ type: 'XDSChatToolCallItem[]',
+ description:
+ 'Array of tool call data. Each item has name, status, target, duration, node, additions, deletions, stats, errorMessage, resultDetail, key, and data.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Custom summary label for groups. Auto-generated from count if omitted.',
+ },
+ {
+ name: 'isExpanded',
+ type: 'boolean',
+ description: 'Controlled expanded state for the group.',
+ },
+ {
+ name: 'defaultIsExpanded',
+ type: 'boolean',
+ description:
+ 'Default expanded state when uncontrolled.',
+ default: 'false',
+ },
+ {
+ name: 'onExpandedChange',
+ type: '(isExpanded: boolean) => void',
+ description: 'Callback fired when the expanded state changes.',
+ },
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsZh = {
+ usage: {
+ description:
+ 'ChatToolCalls displays tool or function call invocations from an LLM response. Pass an array of calls and the component handles the rest — a single call renders inline, while multiple calls collapse into a summary with the latest call visible at the surface. Use it anywhere an AI agent shows what actions it took.',
+ bestPractices: [
+ {guidance: true, description: 'Include a target string on every call so the user can see what the tool acted on — a file path, a shell command, or a search query.'},
+ {guidance: true, description: 'Show a duration on completed calls so users can judge which tools are slow and understand why a response took time.'},
+ {guidance: true, description: 'Provide resultDetail with a code block for calls that produce output — diffs for edits, terminal output for shell commands — so users can inspect results inline.'},
+ {guidance: true, description: 'Set a unique key on each call item when streaming so React can animate additions without re-mounting completed rows.'},
+ {guidance: false, description: "Don't omit the status field — without it the call defaults to complete, which is misleading for calls that are still running or have failed."},
+ {guidance: false, description: "Don't display tool calls outside a chat message context — they are designed to sit inside an assistant message, not as standalone UI."},
+ {guidance: false, description: "Don't use custom wrappers around individual calls — the component handles single vs. grouped layout automatically based on the array length."},
+ ],
+ },
+ propDescriptions: {
+ calls: '工具调用数据数组。每项包含 name、status、target、duration、node、additions、deletions、stats、resultDetail。',
+ label: '组的自定义摘要标签。省略时从数量自动生成。',
+ isExpanded: '受控展开状态。',
+ defaultIsExpanded: '默认展开状态(非受控)。',
+ onExpandedChange: '展开状态变更时的回调。',
+ },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'tool/function call display from LLM response; single=inline, multiple=collapsible summary w/ latest at surface',
+ usage: {
+ description:
+ 'Displays tool or function call invocations from an LLM response. Single call renders inline; multiple calls collapse into a summary. Use inside assistant messages.',
+ bestPractices: [
+ {guidance: true, description: 'Include target on every call — file path, command, or search query.'},
+ {guidance: true, description: 'Show duration on completed calls so users understand timing.'},
+ {guidance: true, description: 'Provide resultDetail with code blocks for calls that produce output.'},
+ {guidance: true, description: 'Set unique key on each call item when streaming for stable animations.'},
+ {guidance: false, description: "Don't omit status — defaults to complete, misleading for running/failed calls."},
+ {guidance: false, description: "Don't display outside chat message context — designed for assistant messages."},
+ {guidance: false, description: "Don't wrap individual calls — component handles single vs. grouped layout automatically."},
+ ],
+ },
+ propDescriptions: {
+ calls: 'tool call data array; name+status+target+duration+node+additions+deletions+resultDetail',
+ label: 'custom summary label; auto from count if omitted',
+ isExpanded: 'controlled expanded state',
+ defaultIsExpanded: 'default expanded state (uncontrolled)',
+ onExpandedChange: 'expanded state change callback',
+ },
+};