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.mjsindex 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.mjsindex 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.tsxindex 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+ defaultIsExpandedcalls={[{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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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.tsxindex 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+ defaultIsExpandedcalls={[{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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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.tsxindex 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.mjsnew file mode 100644index 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',+ },+};