ChatToolCalls 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | ChatToolCalls 带有必需的 calls(每个包含 name,可选的 status、target、node、duration、additions、deletions、stats、errorMessage、resultDetail、data 和 key),可选的 label、isExpanded、defaultIsExpanded、onExpandedChange,以及根 div 的 props 和 ref。 |
| 行为 | 无调用时不渲染任何内容;单个调用直接渲染;多个调用时展示一个可展开区域,其折叠表面显示最新调用,展开表面显示所有调用。 |
| 最终用户影响 | 读者可以看到助手运行了哪些工具,以及每个工具是待处理、运行中、已完成还是失败;一组调用会折叠为最新调用,并将隐藏的行排除在键盘和屏幕阅读器导航之外。 |
| 构建方影响 | 无。 |
| 兼容性与就绪状态 | 记录已发布行为;无公共变更。一项实现差距列于“当前状态影响”下;两个所有者问题保持开放。 |
| 审查检查项 | 拒绝被忽略的标签、折叠组内可聚焦的后代元素、丢失的键盘激活、不可读的辅助文本、被丢弃的根输入,或更改的调用顺序/默认值。 |
| 治理规则 | architecture:public-component-api/INV5–INV6, INV8–INV9;architecture:interaction-modality;spec:AST-009/FR7;WCAG 2.2 SC 1.4.3 和 2.4.7。 |
此表是审查预览;以下正文具有权威性。
意图¶
ChatToolCalls 在助手消息中呈现工具或函数调用,包括执行状态、可选元数据和可检查的结果详情。
兼容性与迁移¶
- 已发布的默认行为保持不变:
yes;省略的 status 表示已完成,组默认折叠,除非defaultIsExpanded为 true - 兼容性类别:记录已发布行为;无公共变更
- 受控/非受控行为:提供
isExpanded时它保持权威性;否则本地状态从defaultIsExpanded ?? false开始。 - 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
当前状态影响¶
- 带符号统计信息可能无法满足文本对比度要求。 用于带符号
+N和-N统计信息的成功和错误前景色令牌,在所有已发布的浅色和深色表面上均无法达到 4.5:1;WCAG 2.2 SC 1.4.3 要求文本达到该对比度(FR5, OQ2)。
所有权边界¶
拥有
- 将有序调用数据投影为单调用或分组呈现。
- 组和单次调用的可展开区域,包括键盘操作和焦点处理。
- 状态、元数据、持续时间、统计信息和结果详情的排布。
- 根 div、
chat-tool-calls目标、受支持的 BaseProps 组合以及 ref。
不拥有 / 非目标
- 工具执行、流式传输、结果解析或错误恢复。
- 调用方提供的
stats或resultDetail内容内部的语义和交互。 - Badge、Icon、Spinner 或 CodeBlock 的内部实现。
- 决定哪些工具调用可以展示的产品策略。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 调用列表 | 空;单个;多个 | 选择无呈现、直接行或分组呈现。 | 每次渲染 | 必需 | component:ChatToolCalls |
稳定 | 为空时不渲染任何内容。 |
| 状态 | 待处理;运行中;已完成;错误 | 选择可见且可访问的执行状态。 | 每次调用 | 已完成 | component:ChatToolCalls |
稳定 | 类型无效的值被拒绝。 |
| 组标签 | 省略;提供的字符串 | 为展开的组命名;省略时使用翻译后的计数。 | 多个调用时 | 省略 | 调用方和组件 | 稳定 | 提供的字符串按原样渲染。 |
| 组状态 | 受控;非受控折叠;非受控展开 | 控制分组行是否暴露。 | 多个调用时 | 折叠 | 调用方或组件 | 稳定 | 避免冲突控制。 |
| 结果详情 | 省略;调用方的 React 节点 | 添加一个可独立操作的按调用展开控件。 | 任意调用 | 省略 | 调用方与组件 | 稳定 | 省略的内容不会产生任何控件。 |
| 根表面 | ref;受支持的 DOM/data/ARIA/class/style/xstyle | 扩展根,而不替换其拥有的目标。 | 非空调用列表 | 省略 | architecture:public-component-api |
稳定 | 不支持的输入仍保持不支持。 |
行为和布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 空调用列表 MUST 渲染无根节点;单个调用 MUST 直接渲染;多个调用 MUST 渲染一个分组展开控件,并在其完整列表中保持调用方顺序。 | 当前源代码、测试和文档 |
| FR2 | 提供的 label MUST 替换展开分组表面上的已翻译计数;省略 MUST 保留已翻译计数后备。 |
当前源代码、测试和文档 |
| FR3 | 折叠的分组 MUST 使其后代的调用展开控件不进入键盘和无障碍导航;展开 MUST 恢复它们。 | 当前源代码和测试 |
| FR4 | 每个组件拥有的展开控件 MUST 可通过 Enter、Space 和指针输入激活,暴露展开状态,并绘制共享的键盘焦点环。 | architecture:interaction-modality;WCAG 2.2 SC 2.4.7 |
| FR5 | 中性的支持性标签、目标、持续时间和自定义统计信息 MUST 使用可读的次要前景色;带符号的添加和删除计数使用成功和错误文本颜色。实现差距:这些颜色可能达不到文本对比度要求(当前状态影响;OQ2)。 | WCAG 2.2 SC 1.4.3 和当前 Token 架构 |
| FR6 | 受支持的根 ref、DOM/data/ARIA、className、style 和 xstyle 输入 MUST 到达根上或组合到根上,同时公共目标保持完整。 | architecture:public-component-api/INV5–INV6, INV8 |
允许的变体¶
- AV1 — 调用内容。 工具名称、目标、节点名称、持续时间、统计信息、错误消息和结果详情仍由调用方提供。
- AV2 — 分组控制。 调用方可控制展开,或仅提供其初始非受控值。
- AV3 — 样式。 受支持的根样式输入可扩展组件,而无需替换其公共目标。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 空 | 不渲染任何根。 | 空数组标识可能有所不同。 |
| 单个 | 显示一行,且没有分组装饰。 | 元数据和结果详情可以不存在。 |
| 多个,折叠 | 显示最新调用和计数;完整行处于非活动状态。 | 调用计数和最新状态可能不同。 |
| 多个,展开 | 每个调用按源顺序显示;提供的 label 或已翻译计数为分组命名。 | label 文本和行元数据可能不同。 |
| 详情关闭/打开 | 该行暴露其状态,并有条件地挂载调用方拥有的详情。 | 任意调用方 React 节点。 |
| 状态 | 所有状态都暴露已翻译的无障碍文本;完成和错误还保留不同的语义标记。 | 主题可能更改语义图示;待处理和运行中共享同一个加载指示器(OQ1 未决)。 |
| 窄 / RTL 上下文 | 行在无水平溢出情况下截断,并遵循逻辑内联方向。 | 内容长度、主题和方向。 |
转换与优先级顺序¶
- ORD1 — 选择呈现方式。 根据列表长度选择空、单个和分组的分支。
- ORD2 — 解析状态。 受控展开具有更高优先级;否则本地状态从初始默认值开始。
- ORD3 — 解析标签。 提供的组标签优先;否则使用翻译后的计数。
- ORD4 — 组合行。 保持调用顺序,渲染状态和元数据,然后在存在调用方拥有的详情披露时添加它。
- ORD5 — 组合根节点。 应用组件目标和样式,然后组合受支持的消费者输入。
性能与资源¶
- PR1 — 仅本地状态。 组件拥有披露状态,且没有 Effect、监听器、观察器、计时器或外部资源。
- PR2 — 线性投影。 分组渲染仅遍历提供的调用列表一次,并且不修改调用方数据。
无障碍契约¶
- AR1 — 披露操作。 分组和详情披露暴露
aria-expanded,可通过指针、Enter 和 Space 操作,并使用共享的可见焦点环。 - AR2 — 折叠归属。 折叠的分组内容是惰性的;隐藏的详情内容被卸载。
- AR3 — 状态含义。 每个状态都暴露翻译后的视觉隐藏文本。完成和错误还使用不同的语义标记;待定和运行共享同一个细微的 Spinner(OQ1)。错误消息暴露给辅助技术,并且在调用行中会回显在状态图标的悬停提示中。
- AR4 — 静态证据。 焦点外观、键盘行为、惰性状态和 DOM 关系使用
spec:AST-009/FR7下的单元测试和 Storybook play-function 证据;本记录不作出任何通告声明。
设计关系¶
| 结构或状态 | 设计要求 | 表征来源 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 调用行 | 紧凑的行内状态和元数据保持可读。 | 当前源码和 WCAG 对比度 | 辅助 | FR5, AR3 |
| 披露 | 键盘焦点保持可见且不改变布局。 | 当前交互架构 | 辅助 | FR4, AR1 |
| 状态 | 翻译后的隐藏文本保留可访问含义;完成和错误保留语义标记。 | 当前源码和客观无障碍(a11y) | 辅助 | FR5, AR3 |
未记录任何组件局部的设计决策。
主题所有权¶
现有的 chat-tool-calls 目标保留在根节点上。Badge、Icon 和 Spinner 拥有各自的嵌套目标和绘制。尚未记录结构主题映射;该块在迁移期间是可选的,因此映射被推迟。
家族与系统关系¶
architecture:public-component-api负责已发布的导出、接受的输入、样式组合和 refs。architecture:component-theming-surface负责目标与委托的结构契约。architecture:interaction-modality负责共享的键盘焦点处理。architecture:component-test-sufficiency负责有边界且对变更敏感的验证证据。spec:AST-009将这些静态语义、键盘、焦点和对比度声明归入较低的证据层,而非真实辅助技术(AT)。spec:AST-029负责本记录验证映射所遵循的审计证据清单。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1 | ChatToolCalls.test.tsx 的空、单个、折叠默认、切换以及“includes the latest status in a collapsed group accessible name”测试 |
空;单个;分组 | 渲染出空的根节点、在单个调用上出现分组外壳,或错误的表层则失败。 | audit:ChatToolCalls/behavior |
| FR2 | ChatToolCalls.test.tsx 中的“renders the public custom group label when expanded” |
提供的标签 | 如果提供的标签被忽略则失败。 | audit:ChatToolCalls/behavior |
| FR3, AR2 | ChatToolCalls.test.tsx 中的“removes collapsed call rows from keyboard and accessibility navigation” |
折叠;展开 | 如果折叠行可操作则失败。 | audit:ChatToolCalls/accessibility |
| FR4, AR1 | ChatToolCalls.test.tsx 的 focus-ring、disclosure-semantics 和 aria-controls 测试 |
分组标题;详情行 | 缺少焦点环、展开状态或控件引用则失败。 | audit:ChatToolCalls/accessibility |
| AR3 | ChatToolCalls.test.tsx 的 status-mark、status-name 和 error-message 测试 |
每种状态;带详情和不带详情的错误 | 缺少状态文本、标记或错误文本则失败。 | audit:ChatToolCalls/accessibility |
| FR6 | ChatToolCalls.test.tsx “转发根 ref 和受支持的 DOM props” |
单一根节点 | 若 ref 或 prop 被丢弃,则失败。 | audit:ChatToolCalls/public-api |
| FR4, AR4 | ChatToolCalls.stories.tsx 的 FocusedGroupedDetail 和 Narrow play 函数 |
聚焦的分组详情;320 CSS px | 若聚焦环变细或脱离,或发生水平溢出,则失败。 | audit:ChatToolCalls/accessibility |
| RTL 关系 | apps/storybook/rtl-audit/verified-not-applicable.json |
所有 stories | — | audit:ChatToolCalls/i18n-rtl |
从源码中读取,目前尚无聚焦测试:
- FR1:展开列表中的调用方顺序。
- FR2:省略
label时的已翻译计数回退。 - FR4:Enter 和 Space 激活。
- FR5:辅助文本上的次要前景色。
- FR6:
xstyle组合。 - PR1–PR2:无 Effect 或外部资源,也不修改调用方数据。
决策日志¶
未记录组件局部的决策。
未决问题¶
- OQ1 — 待处理/运行中的视觉区分。 待处理和运行中渲染出相同的细微 spinner,仅在被翻译的无障碍文本上有所区别。应采用哪种已批准的可见处理方式来区分它们,同时避免自创组件局部的状态策略?
- OQ2 — 语义统计对比度。 针对带符号
+N/-N统计数据的已发布 success/error 前景 token,在所有已发布的浅色/深色表面中均未达到 4.5:1。哪个系统级语义文本 token 能够在保留增/删含义的同时取代它们?在负责人敲定该决定之前,五个受影响的 axe 基线保持不变。
内容边界¶
本文件不重复消费者示例、工具执行策略或已委托的组件契约。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx