跳转至

ChatMessageBubble 组件契约

契约速览

领域 契约
公共契约 必需 children;可选 variant、name、metadata、group 和 width;根 div 透传、样式和 ref。
行为 该气泡从 Chat 消息上下文推导出发送者和密度,绘制 filled 或 ghost 内容,对发送者一侧的逻辑角进行成组处理,并将可渲染的标量 name/metadata 内容保持在对齐包装器内。
终端用户影响 对话内容呈现为发送者感知的气泡;数字零与其气泡保持对齐;不绘制任何内容的插槽值不会留下空白间隙。
构建者影响 无。
兼容性/就绪状态 记录已发布行为;无公共变更。无实现缺口;仍有三个负责人问题保持开放。
评审检查 拒绝:根透传/ref 被丢弃、缺少目标 metadata、物理成组圆角逻辑、显式宽度仍保留默认上限、标量 0 位于其包装器之外、空的标量包装器,或声称已解决未决组合边界。
约束规则 architecture:public-component-api/INV1, INV5, INV6, INV8–INV9;architecture:component-theming-surface/INV4, INV6–INV8;architecture:component-test-sufficiency/INV1–INV7, INV10–INV11;WCAG 2.2 SC 1.4.10。

此表是评审概览;下方正文具有权威性。

意图

ChatMessageBubble 是 ChatMessage 内部可选且感知发送者的绘制内容表面。它为对话内容提供了原始消息内容所不具备的气泡边界、文本内边距、成组圆角处理和对齐的 name/metadata 位置。

兼容性与迁移

  • 已发布默认值保留:yes
  • 兼容性类别:记录已发布行为;无公共变更
  • 受控/非受控行为:不适用;组件不持有状态
  • 迁移决策:无

消费者迁移说明应放在消费者文档和发布说明中。

所有权边界

拥有

  • 气泡根的填充、文本颜色、排版、圆角、内边距、换行和宽度上限。
  • 将消息发送者和密度上下文映射到气泡绘制和几何形状。
  • 使用逻辑角在发送者一侧进行的成组圆角几何处理。
  • 可选 name 和 metadata 内容周围的对齐包装器。
  • 根 DOM 透传、消费者样式组合和根 ref。

不拥有 / 非目标

  • 消息语义、发送者布局、头像位置或消息级别的 name 和 metadata——由 ChatMessage 或共享的 Chat 组合表面负责。
  • 时间戳、投递状态和页脚语义——由 ChatMessageMetadata 负责。
  • 调用方提供的 React 节点的含义、可访问性、生命周期或最终渲染输出。
  • 列表滚动、对话记录语义、composer 行为或系统通知——由各自的 Chat 组件负责。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
children 任意 ReactNode 在气泡根内部渲染的内容 始终 必需 调用方 稳定 不适用——必需
variant filled、ghost 选择填充的发送者感知边界或透明的对齐内容 始终 filled 组件 稳定 封闭联合;会被类型系统拒绝
name 省略;任意 ReactNode 气泡上方对齐包装器中的可选内容 始终 省略 调用方/组件包装器 稳定 不渲染的标量会被省略;可见标量(包括 0)会参与对齐;参见 FR7 和 OQ1
metadata 省略;任意 ReactNode 对齐包装器中气泡下方的可选内容 始终 省略 调用方/组件包装器 稳定 不渲染的标量省略;可见标量(包括 0)对齐;见 FR7 和 OQ1
group 省略、first、middle、last 收紧连续气泡的发送方侧边角 filled、ghost 省略 组件 稳定 省略则保持完整圆角;其他值被类型拒绝
width 省略;任意 SizeValue 用显式宽度替换默认宽度上限 filled、ghost 省略 调用方 稳定 数字变为 CSS 像素;字符串原样传递
消息上下文 发送方 user、assistant、system;密度 compact、balanced、spacious;缺失 选择所反映的发送方/密度及相应的绘制和几何 当嵌套或独立时 assistant 和 balanced 聊天上下文 / 本投影 观察性 缺失上下文时使用组件回退
根 div BaseProps<HTMLDivElement> 和 ref 扩展并引用承载 children、绘制、target 和气泡几何的元素 始终 无 architecture:public-component-api 稳定 组件目标数据和使用方样式组合
chat-message-bubble 目标 发送方、变体和密度以 data-* 反映;确切的保证属性集未在文档中单独声明 气泡绘制根的公开选择器 始终 每个气泡一个 target architecture:component-theming-surface 稳定 未声明的通用属性保持尽力而为

使用方语法和 prop 默认值保留在 ChatMessageBubble.doc.mjs 中。

行为与布局契约

ID 不变量 依据
FR1 组件 MUST 始终为 children 渲染一个根 div,即使调用方提供不渲染的子内容也是如此。 当前源码和测试
FR2 根 MUST 反映解析后的发送方。user 选择用户绘制路径;assistant、system 和缺失上下文使用非用户绘制路径;缺失上下文反映 assistant。 当前源码和测试
FR3 根 MUST 反映解析后的密度。compact 使用紧凑圆角和内边距;balanced 是回退;spacious 使用更宽的块向和行向内边距。 当前源码和测试
FR4 filled MUST 绘制感知发送方的气泡样式;ghost MUST 在保留行向对齐的同时移除填充和块向内边距。 当前源码和测试
FR5 first、middle 和 last MUST 分别收紧逻辑发送方侧的尾端角、两端角和首端角。用户使用 inline-end;每个非用户发送方使用 inline-start。 当前源码和测试
FR6 省略 width MUST 保持 max(80%, 280px)。显式数字或字符串 MUST 设置宽度并将默认上限替换为 none。 当前源码和测试
FR7 对于 null、undefined、布尔值和空字符串,name 和 metadata MUST 省略其对应的包装器。可见的标量值(包括数字零)MUST 保留在其对应的包装器内。非标量 React 节点保持不透明。 当前源码和测试
FR8 根 ref、中性 DOM/data/ARIA 属性、class、style 和 xstyle MUST 到达或合并到绘制根上,且不丢失组件目标或自有样式。 architecture:public-component-api/INV5, INV6, INV8
FR9 恰好一个 chat-message-bubble 目标 MUST 位于绘制根上,并反映发送者、变体和密度。 architecture:component-theming-surface/INV4, INV6–INV8;公开的 Chat 文档

公共类型还接受数组、Fragment、元素、一次性可迭代对象、lazy 内容和 Promise。FR7 不会遍历、克隆、消费、等待或物化这些值:它们各自仍然是调用方拥有的不透明内容。是否应规范化任何复合或异步类别,属于 OQ1。

允许的变化

  • AV1 — 主题令牌。 已解析的颜色、圆角、间距和排版可随主题变化,同时保持语义令牌角色不变。
  • AV2 — 调用方内容。 子节点、name 和 metadata 的节点结构与语义仍归调用方所有。
  • AV3 — 绝对几何。 令牌解析的 padding 和 radius 可以变化;逻辑发送者侧分组和宽度优先级不变。

代表性状态

状态 必需的不变式 允许的变化
独立 助手发送者与均衡密度回退;一个绘制目标 调用方内容
助手/系统,填充 非用户绘制;inline-start 分组圆角 令牌解析的绘制
用户,填充 用户绘制;inline-end 分组圆角 令牌解析的绘制
任意发送者,幽灵 透明表面;保留 inline inset;移除 block inset 主题化文本和 padding
紧凑/均衡/宽松 反映密度以及对应的 padding/radius 路径 已解析的令牌刻度
组首/组中/组尾 LTR 和 RTL 中逻辑发送者侧的圆角顺序 令牌解析的 radii
数值槽 0 可见的零保留在对应的包装器内 无
不渲染的标量槽 null、undefined、布尔值和空字符串不产生对应的包装器 无
不透明的 name/metadata 非标量输入产生包装器,无需遍历或物化 最终由调用方拥有的 React 输出
宽度省略/显式 保留默认上限 / 显式宽度替换上限 有效的 CSS 长度
窄/长文本 文本在 320 CSS px 处换行且无水平溢出 换行及由此产生的高度

转换与优先级顺序

  • ORD1 — 上下文到绘制。 从最近的消息上下文或本地回退解析发送者/密度,选择绘制与几何,然后通过共享的 mergeProps 契约合并组件主题 props、StyleX 输出和消费者样式输入。
  • ORD2 — 宽度。 省略时应用默认最大宽度;显式时,在消费者样式组合之前设置宽度并替换该上限。
  • ORD3 — 分组。 先解析发送者侧,再解析组位置,然后使用逻辑圆角属性,使 CSS 方向镜像物理边缘。

性能与资源

  • PR1 — 纯渲染推导。 组件不拥有 state、Effect、事件监听器、观察器、定时器或动画帧。每次输出都在渲染期间由 props 和 context 推导。
  • PR2 — 不检查调用方内容。 组件不会遍历、克隆、消费、等待或物化调用方提供的 React 节点。是保留该边界还是规范化选定输入,属于 OQ1。

无障碍契约

  • AR1 — 显示表面。 ChatMessageBubble 本身不添加任何 widget 角色、Tab 焦点位置、键盘行为、焦点管理、公告或可访问名称。语义属于外层 ChatMessage 和调用方内容。
  • AR2 — 内容保留。 调用方的 DOM 和 ARIA 透传在 FR8 下到达气泡根;组件目标元数据 MUST NOT 覆盖中性的调用方 ARIA。
  • AR3 — 回流。 在 320 CSS-px 父宽度下,长内容和文档所述的满宽情形 MUST 换行且不产生水平页面溢出(WCAG 2.2 SC 1.4.10)。
  • AR4 — 颜色。 气泡文本仍是有意义的内容,并且需要在浅色和深色模式下与最终渲染的气泡/背景达到 WCAG 2.2 AA 文本对比度。组件使用语义令牌对。

设计关系

解剖或状态 设计需求 表示权威 层级角色 组件契约
气泡内容 感知发送者的填充边界或对齐的幽灵表面 未定 主要 FR2–FR4
分组圆角 在发送者一侧将连续的气泡在视觉上连接起来 未定 辅助 FR5
名称 将辅助内容与气泡文本内边距对齐 未定 辅助 FR7
元数据 将辅助内容与气泡文本内边距对齐 未定 辅助 FR7

没有 authority: current 设计记录拥有 ChatMessageBubble 的本地表征 (OQ3)。这些行描述的是已发布的外观;它们并不授权重新设计。

组件族与系统关系

  • 共享的 Chat 使用方文档拥有跨 message、bubble、metadata、list、layout 和 composer 组件的组合指南。
  • architecture:public-component-api 拥有导出、透传、样式输入和 ref 行为。
  • architecture:component-theming-surface 拥有绘制目标和反射轴。它并不独立要求此封闭变体轴变得可扩展;那将需要组件级的公共 API 决策。
  • architecture:component-test-sufficiency 拥有基于风险的证据清单。
  • spec:AST-029 拥有本记录验证映射所遵循的审计证据清单。

验证映射

契约 验证 代表性状态 变更或失败预期 审计部分
FR1–FR3 ChatMessageBubble.test.tsx 的 children、sender、fallback 和紧凑密度测试 独立;用户和助手;紧凑 缺失根节点、fallback 或反射轴将导致失败。 audit:ChatMessageBubble/behavior
FR4, FR9 ChatMessageBubble.test.tsx 变体和幽灵测试;themingTargets.test.ts filled;ghost 去掉反射、完全移除幽灵内边距,或丢失目标将导致失败。 audit:ChatMessageBubble/theming
FR5 ChatMessageBubble.a11y.chromium.spec.ts 可见状态和 RTL 分组圆角测试 用户和助手 × 第一个、中间、最后一个;LTR 和 RTL 物理角逻辑或错误的发送者一侧会导致角断言失败。 audit:ChatMessageBubble/rtl
FR6 ChatMessageBubble.test.tsx 宽度测试 省略;字符串;数字 保留上限或更改数字像素将导致失败。 audit:ChatMessageBubble/behavior
FR7 ChatMessageBubble.test.tsx 插槽测试;Chromium 可见状态测试的数值对齐 zero;true;false;空字符串;nullish 真值检查会丢失零的对齐或恢复空包装器。 audit:ChatMessageBubble/behavior
FR8, AR2 ChatMessageBubble.test.tsx “将 ref 和中性 DOM props 转发到气泡根节点”以及 data-testid 测试 ref;DOM、data 和 ARIA props 丢失转发将导致失败。 audit:ChatMessageBubble/public-api
AR3 ChatMessageBubble.a11y.chromium.spec.ts “将长内容保持在 320px fixture 内” 320 CSS px 水平溢出将导致失败。 audit:ChatMessageBubble/accessibility
AR4 ChatMessageBubble.a11y.chromium.spec.ts 可见状态测试的对比度断言 亮色和暗色 气泡文本低于 4.5:1 将导致失败。 audit:ChatMessageBubble/accessibility

从源码读取,尚无专门测试:

  • FR1:当 children 为 null 时渲染一个根节点。
  • FR2:system 发送者走非用户绘制路径。
  • FR3:独立的 balanced fallback、紧凑半径和 spacious 内边距。
  • FR4:filled 绘制发送者填充;ghost 移除填充和块轴内边距,并且其内联对齐与每种密度匹配。
  • FR8:className、style 和 xstyle 的组合。
  • AR1:组件自身没有 role、tab stop 或 name。
  • PR1–PR2:没有 state 或 Effect,也不检查调用方内容。

决策日志

未记录任何组件本地决策。

待解决问题

  • OQ1 — ChatMessageBubble 应该将每个非标量 ReactNode 的 name/metadata 值都视为调用方拥有的不透明内容,还是将选定的数组、Fragments、一次性可迭代对象、lazy 值或 promises 规范化为稳定的、可安全重渲染的空/非空契约? (human-api)
  • OQ2 — 对齐的 name 和 metadata 包装器是否应变为可独立主题化、继承当前属主,还是保持故意不可达? (human-api)
  • OQ3 — 如果有的话,哪个当前设计属主应该将 filled/ghost 用法和分组圆角表征定为持久决定? (human-design)

内容边界

本文件不重复使用者 prop 表/示例、实现步骤或共享架构规则。这些内容保留在 ChatMessageBubble.doc.mjs 及其权威归属方中。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx