Skip to content

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

TypeScript

[Component Audit] ChatToolCalls: restore labels and accessible disclosures (#6680)

Cindy Zhangae45a3d8de28
diff --git a/.changeset/chat-tool-calls-accessibility.md b/.changeset/chat-tool-calls-accessibility.md
new file mode 100644
index 0000000000..942ef93050
--- /dev/null
+++ b/.changeset/chat-tool-calls-accessibility.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] ChatToolCalls now displays custom group labels, keeps collapsed details out of keyboard navigation, adds visible focus treatment, and uses readable secondary text for neutral metadata.
+
+@cixzhang
diff --git a/.github/a11y-baseline.json b/.github/a11y-baseline.json
index f94b05ba20..03f106f402 100644
--- a/.github/a11y-baseline.json
+++ b/.github/a11y-baseline.json
@@ -73,11 +73,6 @@
"impact": "serious",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
},
- {
- "key": "ChatToolCalls::Error With Detail::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
{
"key": "ChatToolCalls::Interactive::color-contrast",
"impact": "serious",
@@ -93,26 +88,6 @@
"impact": "serious",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
},
- {
- "key": "ChatToolCalls::Running::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "ChatToolCalls::Single Call::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "ChatToolCalls::With Errors::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "ChatToolCalls::With Nodes::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
{
"key": "ChatToolCalls::With Stats::color-contrast",
"impact": "serious",
diff --git a/.github/scripts/story-play-guard.js b/.github/scripts/story-play-guard.js
index 195f97943b..6b411e2a7f 100644
--- a/.github/scripts/story-play-guard.js
+++ b/.github/scripts/story-play-guard.js
@@ -45,6 +45,17 @@ const TARGETS = [
'ChartTooltip stays continuously open across content-bearing points in ' +
'nested Theme/MediaTheme scope above a native modal with nonzero geometry',
},
+ {
+ component: 'ChatToolCalls',
+ story: 'core-chattoolcalls--focused-grouped-detail',
+ guards:
+ 'grouped detail focus ring remains visible inside the animated clip boundary',
+ },
+ {
+ component: 'ChatToolCalls',
+ story: 'core-chattoolcalls--narrow',
+ guards: 'long metadata stays within the 320px narrow-container fixture',
+ },
{
component: 'TabList',
story: 'core-tablist--full-bleed-geometry',
diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index 9d57d9ca35..e002cd47d7 100644
--- a/apps/storybook/rtl-audit/verified-not-applicable.json
+++ b/apps/storybook/rtl-audit/verified-not-applicable.json
@@ -281,6 +281,15 @@
"component": "core/ChatMessageMetadata",
"reason": "The metadata row owns no directional glyph, contextual directional separator, physical inline positioning, prev/next control order, horizontal scrolling, dragging, overlay, or arrow-key behavior. Sender-dependent row reversal uses CSS flex direction relative to the surrounding writing direction and is verified separately by matched LTR/RTL Chromium receipts. The RTL audit's D1, D2, D3, D5, and D6 detectors therefore have no applicable target for this component."
},
+ {
+ "component": "core/ChatToolCalls",
+ "reason": "ChatToolCalls uses logical inline spacing and source order. Its only component-owned chevrons rotate on the block axis to disclose vertically stacked content; status and wrench icons are non-directional. It owns no left/right glyph, physical inline positioning, directional reordering, horizontal scrolling or dragging, side-placed overlay, or horizontal keyboard behavior. Caller-supplied target, stats, and result-detail content retain their own direction contract.",
+ "evidence": {
+ "apps/storybook/stories/ChatToolCalls.stories.tsx": "sha256:36088a9a88ca7b3c23f5b0a840eec5e77b12cdaf83ba5f6d371ec6296cf722e5",
+ "packages/core/src/Chat/ChatToolCalls.tsx": "sha256:43baec764e8a7d8f5d28b7ea6507c9e01d6e788436c2c34c904e6737a88e0a2b",
+ "packages/core/src/Chat/index.ts": "sha256:0f4a9d3ee08b4fcd43698ad017460aad109c500d2411913f509506d2a27387bb"
+ }
+ },
{
"component": "core/ChatTokenizedText",
"reason": "ChatTokenizedText projects caller-supplied text and inline token content in source reading order. Its root uses normal inline flow; its token wrapper is an inline flex box with no directional glyph, physical inline positioning, reordering, horizontal scrolling or dragging, side-placed overlay, or horizontal keyboard behavior. Structured token paint delegates to Badge and custom token content remains caller owned. The audit fixture covers plain, structured, custom, repeated, edge, empty-value, and narrow states without adding a component-owned RTL dimension.",
diff --git a/apps/storybook/stories/ChatToolCalls.stories.tsx b/apps/storybook/stories/ChatToolCalls.stories.tsx
index 600dbfddda..39492decd4 100644
--- a/apps/storybook/stories/ChatToolCalls.stories.tsx
+++ b/apps/storybook/stories/ChatToolCalls.stories.tsx
@@ -1,6 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import type {Meta, StoryObj} from '@storybook/react';
+import {expect, userEvent} from 'storybook/test';
import {ChatToolCalls, type ChatToolCallItem} from '@astryxdesign/core/Chat';
import {useState, useCallback} from 'react';
import {CodeBlock} from '@astryxdesign/core/CodeBlock';
@@ -74,6 +75,89 @@ export const MultipleCalls: Story = {
),
};
+/** Custom group label — replaces the translated count while expanded */
+export const CustomLabel: Story = {
+ render: () => (
+ <ChatToolCalls
+ label="Repository updates"
+ defaultIsExpanded
+ calls={[
+ {name: 'read', target: 'package.json', status: 'complete'},
+ {name: 'edit', target: 'package.json', status: 'complete'},
+ ]}
+ />
+ ),
+};
+
+/** Focused grouped detail — proves the inset ring survives the animated clip boundary */
+export const FocusedGroupedDetail: Story = {
+ tags: ['no-visual'],
+ render: () => (
+ <ChatToolCalls
+ defaultIsExpanded
+ calls={[
+ {
+ name: 'read',
+ target: 'package.json',
+ status: 'complete',
+ resultDetail: <CodeBlock code='{"name":"astryx"}' language="json" />,
+ },
+ {name: 'edit', target: 'package.json', status: 'complete'},
+ ]}
+ />
+ ),
+ play: async ({canvasElement}) => {
+ if (document.activeElement instanceof HTMLElement) {
+ document.activeElement.blur();
+ }
+ await userEvent.tab();
+ await userEvent.tab();
+ const focused = canvasElement.querySelector<HTMLElement>(':focus');
+ await expect(focused).not.toBeNull();
+ await expect(focused).toHaveTextContent('read');
+ const style = getComputedStyle(focused as HTMLElement);
+ await expect(Number.parseFloat(style.outlineWidth)).toBeGreaterThanOrEqual(
+ 2,
+ );
+ await expect(Number.parseFloat(style.outlineOffset)).toBeLessThanOrEqual(
+ -2,
+ );
+ },
+};
+
+/** Narrow container — long metadata truncates without horizontal overflow */
+export const Narrow: Story = {
+ tags: ['no-visual'],
+ render: () => (
+ <div
+ data-chat-tool-calls-narrow
+ style={{boxSizing: 'border-box', width: 320, padding: 16}}>
+ <ChatToolCalls
+ calls={[
+ {
+ name: 'long_running_tool_name',
+ target: 'packages/core/src/Chat/ChatToolCalls.tsx',
+ status: 'running',
+ node: 'workspace',
+ },
+ ]}
+ />
+ </div>
+ ),
+ play: async ({canvasElement}) => {
+ const container = canvasElement.querySelector<HTMLElement>(
+ '[data-chat-tool-calls-narrow]',
+ );
+ await expect(container).not.toBeNull();
+ if (container == null) {
+ throw new Error('Expected the narrow ChatToolCalls fixture');
+ }
+ await expect(container.scrollWidth).toBeLessThanOrEqual(
+ container.clientWidth,
+ );
+ },
+};
+
/** With node badges — shows which sandbox ran each tool */
export const WithNodes: Story = {
render: () => (
@@ -431,11 +515,7 @@ Time: 6.1s`;
duration: '6.1s',
node: 'cli:remote-server',
resultDetail: (
- <CodeBlock
- code={testOutput}
- language="bash"
- maxHeight="50vh"
- />
+ <CodeBlock code={testOutput} language="bash" maxHeight="50vh" />
),
},
{
@@ -490,11 +570,7 @@ Time: 6.84s`;
node: 'cli:remote-server',
errorMessage: '4 tests failed',
resultDetail: (
- <CodeBlock
- code={errorOutput}
- language="bash"
- maxHeight="50vh"
- />
+ <CodeBlock code={errorOutput} language="bash" maxHeight="50vh" />
),
},
]}
diff --git a/packages/core/src/Chat/ChatToolCalls.doc.mjs b/packages/core/src/Chat/ChatToolCalls.doc.mjs
index 4037d02d53..58a7c8a194 100644
--- a/packages/core/src/Chat/ChatToolCalls.doc.mjs
+++ b/packages/core/src/Chat/ChatToolCalls.doc.mjs
@@ -16,6 +16,7 @@ export const docs = {
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 a group label when the automatic count does not explain what the calls represent.'},
{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."},
@@ -54,7 +55,7 @@ export const docs = {
name: 'label',
type: 'string',
description:
- 'Custom summary label for groups. Auto-generated from count if omitted.',
+ 'Custom summary label shown for an expanded group. The translated call count is used when omitted.',
},
{
name: 'isExpanded',
@@ -90,6 +91,7 @@ export const docsZh = {
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 a group label when the automatic count does not explain what the calls represent.'},
{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."},
@@ -115,6 +117,7 @@ export const docsDense = {
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 group label when count alone is ambiguous.'},
{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."},
diff --git a/packages/core/src/Chat/ChatToolCalls.spec.md b/packages/core/src/Chat/ChatToolCalls.spec.md
new file mode 100644
index 0000000000..0ce82a2f45
--- /dev/null
+++ b/packages/core/src/Chat/ChatToolCalls.spec.md
@@ -0,0 +1,194 @@
+---
+schema_version: 3
+template_version: 6
+kind: component
+id: component:ChatToolCalls
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility, testing]
+verified_by:
+ [
+ packages/core/src/Chat/ChatToolCalls.test.tsx,
+ apps/storybook/stories/ChatToolCalls.stories.tsx,
+ apps/storybook/rtl-audit/verified-not-applicable.json,
+ packages/core/src/theme/themingTargets.test.ts,
+ ]
+modules: []
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:public-component-api,
+ architecture:component-theming-surface,
+ architecture:component-test-sufficiency,
+ architecture:react-component-runtime,
+ architecture:interaction-modality,
+ architecture:theme-tokens,
+ architecture:knowledge-contracts,
+ ]
+contributing: []
+system_specs: [spec:AST-009, spec:AST-029]
+---
+
+# ChatToolCalls component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | The exported component accepts a required call list, optional group label, controlled or uncontrolled expansion, a change callback, and supported root div props and ref. |
+| Behavior | No calls render nothing; one call renders directly; multiple calls expose a disclosure whose collapsed surface shows the latest call and whose expanded surface shows every call. |
+| End-user impact | Group labels appear as supplied, collapsed detail controls leave keyboard and accessibility navigation, and every disclosure has the shared visible focus treatment. |
+| Builder impact | Existing calls keep their shape and defaults. Builders may rely on the released `label` prop and continue to omit it for the translated count. |
+| Compatibility/readiness | Patch-compatible restoration of documented behavior and objective accessibility requirements. No prop, export, default, theme target, call ordering, or caller-content contract changes. |
+| Review checks | Reject ignored labels, focusable descendants inside a collapsed group, lost keyboard activation, unreadable supporting text, dropped root inputs, or changed call ordering/defaults. |
+| Governing rules | `architecture:public-component-api/INV5–INV6, INV8–INV9`; `architecture:interaction-modality`; `spec:AST-009/FR7`; `spec:AST-029/FR3–FR7`; WCAG 2.2 SC 1.4.3 and 2.4.7. |
+
+This table is a review projection. The draft body records verified shipped or
+remediated behavior and creates no new tool-call protocol or visual policy.
+
+## Intent
+
+ChatToolCalls presents tool or function invocations inside an assistant message,
+including execution status, optional metadata, and inspectable result details.
+
+## Compatibility and migration
+
+- Released default preserved: yes; omitted status means complete and groups start collapsed unless `defaultIsExpanded` is true.
+- Compatibility class: patch-compatible correctness and accessibility repair.
+- Controlled/uncontrolled behavior: `isExpanded` remains authoritative when supplied; otherwise local state starts from `defaultIsExpanded ?? false`.
+- Migration decision: none. No public type, prop, export, default, or theme target changes.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Projection of ordered call data into single-call or grouped presentation.
+- Group and per-call disclosures, including keyboard operation and focus treatment.
+- Status, metadata, duration, statistics, and result-detail placement.
+- The root div, `chat-tool-calls` target, supported BaseProps composition, and ref.
+
+**Does not own / non-goals**
+
+- Tool execution, streaming transport, result parsing, or error recovery.
+- Semantics and interaction inside caller-provided `stats` or `resultDetail` content.
+- Badge, Icon, Spinner, or CodeBlock internals.
+- Product policy for which tool calls may be shown.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |
+| ------------- | ----------------------------------------------------- | ------------------------------------------------------------ | ------------------- | --------- | ----------------------------------- | ------------------------- | ------------------------------------ |
+| Call list | empty; single; multiple | Selects absent, direct-row, or grouped presentation. | Every render | required | `component:ChatToolCalls` | released observed surface | Empty renders nothing. |
+| Status | pending; running; complete; error | Selects the visible and accessible execution state. | Every call | complete | `component:ChatToolCalls` | released observed surface | Type-invalid values reject. |
+| Group label | omitted; supplied string | Names an expanded group; omission uses the translated count. | Multiple calls | omitted | caller and component | released observed surface | Supplied strings render verbatim. |
+| Group state | controlled; uncontrolled collapsed; uncontrolled open | Controls whether grouped rows are exposed. | Multiple calls | collapsed | caller or component | released observed surface | Conflicting control is avoided. |
+| Result detail | omitted; caller React node | Adds an independently operable per-call disclosure. | Any call | omitted | caller and component | released observed surface | Omitted content adds no control. |
+| Root surface | ref; supported DOM/data/ARIA/class/style/xstyle | Extends the root without replacing its owned target. | Non-empty call list | omitted | `architecture:public-component-api` | released observed surface | Unsupported inputs stay unsupported. |
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------ |
+| FR1 | An empty call list MUST render no root; one call MUST render directly; multiple calls MUST render one group disclosure and preserve caller order in its full list. | Released implementation, docs, stories, and tests | verified |
+| FR2 | A supplied `label` MUST replace the translated count on the expanded group surface; omission MUST retain the translated count fallback. | Released public prop and consumer docs; public API INV5, INV9 | remediated and verified |
+| FR3 | A collapsed group MUST keep its descendant call disclosures out of keyboard and accessibility navigation; expansion MUST restore them. | HTML `inert`, disclosure semantics, WCAG operability | remediated and verified |
+| FR4 | Every component-owned disclosure MUST activate with Enter, Space, and pointer input, expose expansion state, and draw the shared keyboard focus ring. | Current interaction-modality architecture and WCAG 2.4.7 | remediated and verified |
+| FR5 | Neutral supporting labels, targets, durations, and custom statistics MUST use the readable secondary foreground; signed addition/deletion counts retain their released semantic colors pending OQ2. | WCAG 2.2 SC 1.4.3 and current token architecture | partial remediation; OQ2 |
+| FR6 | Supported root ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach or compose on the root while the public target remains intact. | `architecture:public-component-api/INV5–INV6, INV8` | verified |
+
+### Allowed variation
+
+- **AV1 — Call content.** Tool names, targets, node names, durations, statistics, error messages, and result details remain caller supplied.
+- **AV2 — Group control.** Callers may control expansion or supply only its initial uncontrolled value.
+- **AV3 — Styling.** Supported root styling inputs may extend the component without replacing its public target.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| -------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Empty | No root is rendered. | Empty array identity may vary. |
+| Single | One row appears without group chrome. | Metadata and result detail may be absent. |
+| Multiple, collapsed | Latest call and count appear; full rows are inert. | Call count and latest status may vary. |
+| Multiple, expanded | Every call appears in source order; supplied label or translated count names the group. | Label text and row metadata may vary. |
+| Detail closed/open | The row exposes its state and conditionally mounts the caller-owned detail. | Any caller React node. |
+| Statuses | All statuses expose translated accessible text; complete and error also retain distinct semantic marks. | Theme may change semantic artwork; pending and running share a spinner pending OQ1. |
+| Narrow / RTL context | Rows truncate without horizontal overflow and follow logical inline direction. | Content length, theme, and direction. |
+
+### Transformation and precedence order
+
+- **ORD1 — Choose presentation.** Empty, single, and grouped branches are selected from list length.
+- **ORD2 — Resolve state.** Controlled expansion wins; otherwise local state starts from the initial default.
+- **ORD3 — Resolve label.** A supplied group label wins; otherwise use the translated count.
+- **ORD4 — Compose rows.** Preserve call order, render status and metadata, then add caller-owned detail disclosure where present.
+- **ORD5 — Compose root.** Apply the component target and styles, then combine supported consumer inputs.
+
+### Performance and resources
+
+- **PR1 — Local state only.** The component owns disclosure state and no Effect, listener, observer, timer, or external resource.
+- **PR2 — Linear projection.** Group rendering traverses the supplied call list once and does not mutate caller data.
+
+## Accessibility contract
+
+- **AR1 — Disclosure operation.** Group and detail disclosures expose `aria-expanded`, operate with pointer, Enter, and Space, and use the shared visible focus ring.
+- **AR2 — Collapsed ownership.** Collapsed group content is inert; hidden detail content is unmounted.
+- **AR3 — Status meaning.** Every status exposes translated visually hidden text. Complete and error also use distinct semantic marks; pending and running currently share the same subtle spinner (OQ1). Error messages are exposed to assistive technology and echoed in the status icon's hover tooltip.
+- **AR4 — Static evidence.** Focus appearance, keyboard behavior, inertness, color contrast, and DOM relationships use unit, axe, and real-browser evidence under `spec:AST-009/FR7`; this audit makes no AT-announcement claim.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------------------------------------------- | --------------------------------- | -------------- | ------------------ |
+| Call row | Compact inline status and metadata remain legible. | Current source and WCAG contrast | supporting | FR5, AR3 |
+| Disclosure | Keyboard focus remains visible without changing layout. | Current interaction architecture | supporting | FR4, AR1 |
+| Status | Translated hidden text preserves accessible meaning; complete and error retain semantic marks. | Current source and objective a11y | supporting | FR5, AR3 |
+
+This observational draft does not choose new spacing, density, iconography,
+proportion, status vocabulary, or motion.
+
+### Theme ownership
+
+The existing `chat-tool-calls` target remains on the root. Badge, Icon, and Spinner
+own their nested targets and paint. This observational draft does not add a public
+theme target or redefine inherited Chat-family anatomy.
+
+## Family and system relationships
+
+- `architecture:public-component-api` owns released exports, accepted inputs, styling composition, and refs.
+- `architecture:component-theming-surface` owns the target and delegated anatomy contract.
+- `architecture:interaction-modality` owns shared keyboard focus treatment.
+- `architecture:component-test-sufficiency` owns bounded, mutation-sensitive evidence.
+- `spec:AST-009` assigns these static semantics, keyboard, focus, and contrast claims to lower evidence layers rather than real AT.
+- `spec:AST-029` owns this observational audit backfill and closed evidence receipt.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ---------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------- |
+| FR1–FR4, AR1–AR2 | `ChatToolCalls.test.tsx` | empty, single, grouped, label, disclosures | Ignored label, wrong state, operable collapsed row, or missing ring fails. | `audit:ChatToolCalls/behavior` |
+| FR5, AR3–AR4 | scoped Chromium axe plus existing-baseline visual comparisons | neutral metadata in light mode; existing visual states in light/dark | Reintroducing disabled-text contrast fails; semantic stats remain baselined under OQ2. | `audit:ChatToolCalls/accessibility` |
+| FR6 | focused root passthrough/ref checks and theming target guard | single root | A supported input, ref, or public target is dropped or replaced. | `audit:ChatToolCalls/public-api` |
+| RTL relation | source-hashed verified-N/A record | all checked-in stories | Component-owned directional behavior invalidates the record. | `audit:ChatToolCalls/i18n-rtl` |
+| Browser matrix | existing visual baselines, scoped a11y, and required real-browser play guards | grouped focus and 320px narrow overflow; existing light/dark states | Missing focus, overflow, visual regressions, or new a11y violations fail. | `audit:ChatToolCalls/rendered` |
+| Docs / surface | docs, declarations, exports, knowledge check, docs typecheck | public props, Chat subpath, draft record | Missing or stale docs, export, target, or knowledge shape fails. | `audit:ChatToolCalls/docs` |
+
+## Decision log
+
+No component-local product decision is created by this observational draft. The
+repairs restore released API behavior and objective accessibility requirements.
+
+## Open questions
+
+- **OQ1 — Pending/running visual distinction.** Pending and running currently render the same subtle spinner and differ only in translated accessible text. Which approved visible treatment should distinguish them without inventing component-local status policy?
+- **OQ2 — Semantic statistics contrast.** The released success/error foreground tokens for signed `+N`/`-N` statistics do not reach 4.5:1 in every shipped light/dark surface. Which system-level semantic text token should replace them while preserving addition/deletion meaning? The five affected axe baselines remain until that owner decision lands.
+
+## Content boundary
+
+This file does not duplicate consumer examples, audit scores, screenshots, tool
+execution policy, or delegated component contracts.
diff --git a/packages/core/src/Chat/ChatToolCalls.test.tsx b/packages/core/src/Chat/ChatToolCalls.test.tsx
index a513bbe700..fdc9864916 100644
--- a/packages/core/src/Chat/ChatToolCalls.test.tsx
+++ b/packages/core/src/Chat/ChatToolCalls.test.tsx
@@ -1,9 +1,12 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+import {createRef} from 'react';
import {describe, it, expect} from 'vitest';
import {render, screen, fireEvent} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
import {Theme} from '../theme/Theme';
import {defineTheme} from '../theme/defineTheme';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {ChatToolCalls} from './ChatToolCalls';
describe('ChatToolCalls', () => {
@@ -12,6 +15,26 @@ describe('ChatToolCalls', () => {
expect(container.firstChild).toBeNull();
});
+ it('forwards the root ref and supported DOM props', () => {
+ const ref = createRef<HTMLDivElement>();
+ render(
+ <ChatToolCalls
+ ref={ref}
+ calls={[{name: 'bash'}]}
+ data-testid="tool-calls"
+ aria-label="Tool activity"
+ className="consumer-class"
+ style={{marginBlockStart: 12}}
+ />,
+ );
+
+ const root = screen.getByTestId('tool-calls');
+ expect(ref.current).toBe(root);
+ expect(root).toHaveAttribute('aria-label', 'Tool activity');
+ expect(root).toHaveClass('astryx-chat-tool-calls', 'consumer-class');
+ expect(root).toHaveStyle({marginBlockStart: '12px'});
+ });
+
it('renders single call inline without group chrome', () => {
render(
<ChatToolCalls
@@ -165,6 +188,66 @@ describe('ChatToolCalls', () => {
expect(btn).toHaveAttribute('aria-expanded', 'true');
});
+ it('renders the public custom group label when expanded', () => {
+ render(
+ <ChatToolCalls
+ label="Repository updates"
+ defaultIsExpanded
+ calls={[{name: 'read'}, {name: 'edit'}]}
+ />,
+ );
+
+ expect(screen.getByText('Repository updates')).toBeInTheDocument();
+ expect(screen.queryByText('2 tool calls')).not.toBeInTheDocument();
+ });
+
+ it('removes collapsed call rows from keyboard and accessibility navigation', () => {
+ render(
+ <ChatToolCalls
+ calls={[
+ {name: 'read', resultDetail: <div>file contents</div>},
+ {name: 'edit', resultDetail: <div>diff contents</div>},
+ ]}
+ />,
+ );
+
+ const header = screen.getAllByRole('button')[0];
+ const content = document.getElementById(
+ header.getAttribute('aria-controls') as string,
+ );
+ expect(content).toHaveAttribute('inert');
+
+ fireEvent.click(header);
+ expect(content).not.toHaveAttribute('inert');
+ });
+
+ it('composes the shared visible focus ring on every disclosure control', () => {
+ render(
+ <ChatToolCalls
+ defaultIsExpanded
+ calls={[
+ {name: 'read', resultDetail: <div>file contents</div>},
+ {name: 'edit'},
+ ]}
+ />,
+ );
+
+ const buttons = screen.getAllByRole('button');
+ const focusRingClasses = stylex
+ .props(focusOutlineStyles.focusVisible)
+ .className!.split(' ');
+ const [focusRingMarker] = focusRingClasses;
+ for (const button of buttons) {
+ expect(button).toHaveClass(focusRingMarker);
+ }
+ // The group header keeps the shared ring unchanged. Grouped detail rows
+ // replace only its offset with an inset value so the animated clip boundary
+ // cannot hide the ring; the focused Storybook story verifies that geometry.
+ for (const className of focusRingClasses) {
+ expect(buttons[0]).toHaveClass(className);
+ }
+ });
+
it('shows target when provided', () => {
render(
<ChatToolCalls
diff --git a/packages/core/src/Chat/ChatToolCalls.tsx b/packages/core/src/Chat/ChatToolCalls.tsx
index 68a424e005..a1d0e8d0ae 100644
--- a/packages/core/src/Chat/ChatToolCalls.tsx
+++ b/packages/core/src/Chat/ChatToolCalls.tsx
@@ -30,6 +30,7 @@ import {
radiusVars,
durationVars,
easeVars,
+ focusVars,
} from '../theme/tokens.stylex';
import {getKey, mergeProps} from '../utils';
import {Badge} from '../Badge';
@@ -37,6 +38,7 @@ import {Icon, type IconName} from '../Icon';
import {Spinner} from '../Spinner';
import {VisuallyHidden} from '../VisuallyHidden';
import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {useTranslator} from '../i18n';
// =============================================================================
@@ -63,14 +65,14 @@ export interface ChatToolCallItem {
/** Additional info rendered after the label. Free-form ReactNode. */
stats?: ReactNode;
/**
- * Error message when status is 'error'. Rendered as visually hidden text in
- * the row (so screen readers and keyboard users perceive it) and echoed in a
- * hover tooltip on the status icon.
+ * Error message when status is 'error'. Exposed as visually hidden text in
+ * the row for assistive technology and echoed in a hover tooltip on the
+ * status icon.
*/
errorMessage?: string;
/** Unique key for React list rendering. Derived from stable metadata if omitted. */
key?: string;
- /** Arbitrary data passed through to renderDetail. Store tool args, result, etc. */
+ /** Arbitrary caller data retained with the call item. */
data?: unknown;
/** Inline detail content shown when the row is expanded (e.g. code diff, command output). */
resultDetail?: ReactNode;
@@ -80,11 +82,11 @@ export interface ChatToolCallsProps extends BaseProps<HTMLDivElement> {
ref?: React.Ref<HTMLDivElement>;
/** Array of tool call data. */
calls: ChatToolCallItem[];
- /** Custom summary label for groups. Auto-generated from count if omitted. */
+ /** Custom summary label shown for an expanded group. */
label?: string;
/** Whether the group is expanded. Uncontrolled by default. */
isExpanded?: boolean;
- /** Default expanded state. @default true for ≤3 calls, false for >3. */
+ /** Default expanded state when uncontrolled. @default false */
defaultIsExpanded?: boolean;
/** Callback when expanded state changes. */
onExpandedChange?: (isExpanded: boolean) => void;
@@ -136,7 +138,7 @@ const styles = stylex.create({
flexShrink: 0,
width: '14px',
height: '14px',
- color: colorVars['--color-text-disabled'],
+ color: colorVars['--color-text-secondary'],
},
// Rides on the chevron <Icon> (via `xstyle`), next to the rotation it
// animates, so one element carries both the transform and the theme target.
@@ -194,6 +196,12 @@ const styles = stylex.create({
minHeight: '24px',
paddingBlock: spacingVars['--spacing-0-5'],
},
+ callRowFocusInset: {
+ outlineOffset: {
+ default: null,
+ ':focus-visible': `calc(-1 * ${focusVars['--focus-outline-width']})`,
+ },
+ },
callRowClickable: {
cursor: {
default: 'pointer',
@@ -240,7 +248,7 @@ const styles = stylex.create({
fontSize: typeScaleVars['--text-supporting-size'],
lineHeight: typeScaleVars['--text-supporting-leading'],
fontFamily: typographyVars['--font-family-body'],
- color: colorVars['--color-text-disabled'],
+ color: colorVars['--color-text-secondary'],
whiteSpace: 'nowrap',
overflow: 'hidden',
textOverflow: 'ellipsis',
@@ -251,7 +259,7 @@ const styles = stylex.create({
fontSize: typeScaleVars['--text-supporting-size'],
lineHeight: typeScaleVars['--text-supporting-leading'],
fontFamily: typographyVars['--font-family-body'],
- color: colorVars['--color-text-disabled'],
+ color: colorVars['--color-text-secondary'],
whiteSpace: 'nowrap',
flexShrink: 0,
},
@@ -265,7 +273,7 @@ const styles = stylex.create({
fontSize: typeScaleVars['--text-supporting-size'],
lineHeight: typeScaleVars['--text-supporting-leading'],
fontFamily: typographyVars['--font-family-body'],
- color: colorVars['--color-text-disabled'],
+ color: colorVars['--color-text-secondary'],
flexShrink: 0,
},
statsAdditions: {
@@ -286,7 +294,7 @@ const styles = stylex.create({
flexShrink: 0,
width: '14px',
height: '14px',
- color: colorVars['--color-text-disabled'],
+ color: colorVars['--color-text-secondary'],
marginInlineStart: 'auto',
},
callDetailContent: {
@@ -300,7 +308,7 @@ const styles = stylex.create({
fontSize: typeScaleVars['--text-supporting-size'],
lineHeight: typeScaleVars['--text-supporting-leading'],
fontFamily: typographyVars['--font-family-body'],
- color: colorVars['--color-text-disabled'],
+ color: colorVars['--color-text-secondary'],
flexShrink: 0,
},
@@ -393,7 +401,13 @@ function getToolCallKey(call: ChatToolCallItem): string {
// Internal: single call row
// =============================================================================
-function CallRow({call}: {call: ChatToolCallItem}) {
+function CallRow({
+ call,
+ hasClippedFocusRing = false,
+}: {
+ call: ChatToolCallItem;
+ hasClippedFocusRing?: boolean;
+}) {
const t = useTranslator();
const status = call.status ?? 'complete';
const hasDetail = call.resultDetail != null;
@@ -426,7 +440,11 @@ function CallRow({call}: {call: ChatToolCallItem}) {
}
: undefined
}
- {...stylex.props(styles.callRow, hasDetail && styles.callRowClickable)}>
+ {...focusOutlineProps.focusVisible(
+ styles.callRow,
+ hasDetail && styles.callRowClickable,
+ hasDetail && hasClippedFocusRing && styles.callRowFocusInset,
+ )}>
<span
title={status === 'error' ? call.errorMessage : undefined}
{...stylex.props(styles.statusIcon, STATUS_STYLES[status])}>
@@ -520,10 +538,8 @@ function CallRow({call}: {call: ChatToolCallItem}) {
* name: tc.toolName,
* status: tc.state,
* duration: tc.duration,
+ * resultDetail: <CodeBlock code={tc.args} language="json" />,
* }))}
- * renderDetail={(call) => (
- * <CodeBlock code={call.args} language="json" />
- * )}
* />
* ```
*/
@@ -531,7 +547,7 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
const t = useTranslator();
const {
calls,
- label: _customLabel,
+ label: customLabel,
isExpanded: controlledExpanded,
defaultIsExpanded,
onExpandedChange,
@@ -609,14 +625,18 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
toggle();
}
}}
- {...stylex.props(styles.callRow, styles.callRowToggle)}>
+ {...focusOutlineProps.focusVisible(
+ styles.callRow,
+ styles.callRowToggle,
+ )}>
{isExpanded ? (
<>
<span {...stylex.props(styles.groupIcon)}>
<Icon icon="wrench" size="sm" color="inherit" />
</span>
<span {...stylex.props(styles.groupLabel)}>
- {t('@astryx.chatToolCalls.groupLabel', {count: calls.length})}
+ {customLabel ??
+ t('@astryx.chatToolCalls.groupLabel', {count: calls.length})}
</span>
</>
) : (
@@ -668,6 +688,7 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
{/* Expanded: all calls with full metadata */}
<div
id={contentId}
+ inert={isExpanded ? undefined : true}
{...stylex.props(
styles.groupContent,
isExpanded && styles.groupContentExpanded,
@@ -675,7 +696,11 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
<div {...stylex.props(styles.groupContentInner)}>
<div {...stylex.props(styles.list)}>
{calls.map(call => (
- <CallRow key={getToolCallKey(call)} call={call} />
+ <CallRow
+ key={getToolCallKey(call)}
+ call={call}
+ hasClippedFocusRing
+ />
))}
</div>
</div>