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:独立的
balancedfallback、紧凑半径和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