跳转至

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