跳转至

ChatComposer 组件契约

契约概览

领域 契约
公开契约 ChatComposer,支持受控或非受控的草稿(value、onChange)、onSubmit、placeholder、isDisabled、isStopShown、onStop、density、elevation、status、statusPosition、抽屉、标题、输入、页脚和发送插槽,以及 BaseProps;并导出组合上下文。
行为 ChatComposer 协调受控或非受控的草稿,对提交的值进行修剪,通过现有的 value 通道清空,组合调用方的插槽,并保持默认的发送/停止操作与上下文同步。
最终用户影响 屏幕阅读器用户能够识别被禁用的编辑器,指针和触控用户能够停止可中断的响应,自定义编辑器的用户发送的是该编辑器提供的草稿,而不是过时的 Composer 状态。
构建方影响 无。
兼容性/就绪状态 记录已发布的行为;无公开变更。两个实现差距列在“当前状态影响”之下;四个所有者问题仍未解决。FR1、FR5–FR7、FR10 和 PR1–PR2 的部分证据仍待补充(从源码读取;参见验证映射)。
评审检查 应拒绝:忽略上下文提交参数、默认文本框未呈现禁用状态、祖先元素阻止可用的 Stop 操作,或在没有对应所有者的情况下解决未决问题的变更。
约束规则 architecture:interaction-modality/INV4, INV7, INV9;architecture:public-component-api/INV5–INV6, INV9, INV12;architecture:component-theming-surface/INV4, INV6;spec:AST-020/FR1;spec:AST-029/DEC-4。

本表格是评审投影;下方正文具有权威性。

意图

ChatComposer 是聊天界面的消息输入外壳。它协调当前草稿与提交流程,围绕默认或调用方提供的输入布局可选的抽屉、标题、状态、页脚和发送区域内容,并负责仅键盘操作时的编辑器焦点指示。产品方负责消息传输、流式状态、校验策略以及放置在每个插槽中的内容。

兼容性与迁移

  • 已发布的默认值保留:yes
  • 兼容性类别:记录已发布行为;无公开变更
  • 受控/非受控行为:提交成功后,在受控模式下通过 onChange 清空,在其他情况下通过本地状态清空。
  • 迁移决策:无

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

当前状态影响

  • 公开目标不覆盖已绘制的本体。 chat-composer 目标位于外部框架上,因此主题无法选择本体的 elevation 和边框。architecture:component-theming-surface INV4 要求每个可主题化部分的绘制效果位于其目标上(FR7、OQ1)。
  • 样式输入分散在两个元素上。 ref、DOM props 和事件、className 和 style 到达外部框架,而 xstyle 到达已绘制的本体。architecture:public-component-api INV6 要求样式输入在同一个元素上组合(FR10、OQ2)。

所有权边界

拥有

  • 协调受控或非受控的序列化草稿值与输入及提交流程。
  • 提供默认支持 token 的编辑器和发送/停止操作,同时允许替换两者。
  • 布局抽屉、标题、输入、页脚、发送和状态区域。
  • 应用 Composer 的 density、elevation、禁用表现以及仅键盘操作时的编辑器焦点指示。
  • 发布供自定义输入和发送控件使用的组合上下文。

不拥有 / 非目标

  • 发送、重试、取消或持久化消息——由产品调用方拥有。
  • 决定响应何时处于流式状态或是否可中断——由产品调用方拥有。
  • 附件数据、模型选择、语音识别或校验策略——由提供的插槽组件和产品调用方拥有。
  • 产品的无障碍对话记录或实时响应宣告——由围绕的聊天界面拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 负责人 稳定性 无效值行为
草稿所有权 不受控;受控 value + onChange 选择序列化输入草稿的存储位置以及清除操作的报告方式。 每个 ChatComposer 不受控空字符串 component:ChatComposer 稳定 没有更新所有者的受控 value 仍由调用方控制。
提交 输入提交;默认发送;自定义上下文 onSubmit(value) 传递一个经修剪、非空的值,并通过当前通道清除草稿。 已启用且具有非空提供值的 composer 无提交 component:ChatComposer 稳定 空值以及处于禁用状态时的提交将被忽略。
输入构成 默认 ChatComposerInput;自定义 React 节点 提供编辑界面和可选的已注册焦点控制。 每个 ChatComposer ChatComposerInput component:ChatComposer 稳定 没有已注册控件的自定义输入会回退到 textarea 焦点。
编辑可用性 启用;禁用 控制草稿是否可以编辑或提交。 每个 ChatComposer 启用 component:ChatComposer 稳定 禁用状态下的提交将被忽略。
主要操作 发送;停止 发送当前草稿或请求中断。 默认 ChatSendButton 或自定义 sendButton 发送 component:ChatComposer 稳定 显示但没有 onStop 的停止操作仍会渲染,但不会执行任何操作 (OQ4)。
密度 紧凑;平衡;宽敞 选择 composer 的间距。 每个 ChatComposer 平衡 component:ChatComposer 稳定 未知值会被 TypeScript 拒绝。
高度 低;无 选择凸起的主体或带边框的扁平主体。 每个 ChatComposer 低 component:ChatComposer 稳定 未知值会被 TypeScript 拒绝。
状态 无;错误;警告;顶部;底部 在主体之前或之后添加可播报的反馈。 可选状态对象 无;存在时位于底部 component:ChatComposer 稳定 省略消息时仍会渲染该栏,但不播报任何内容。
具名组合插槽 抽屉;头部操作/上下文;输入;底部/发送操作 允许调用方在草稿周围组合配套控件和信息。 可选,独立提供 省略 component:ChatComposer 稳定 省略的插槽组不会生成空的头部;底部保留用于发送操作。
BaseProps 表面 ref;DOM 属性/事件;className/style;xstyle 通过 DOM 标识、行为和样式扩展组件。 每个 ChatComposer 省略 architecture:public-component-api 稳定 在框架和主体之间拆分 (FR10, OQ2)。

行为与布局契约

ID 不变量 依据
FR1 受控模式 MUST 通过 onChange 报告更改;非受控模式 MUST 在本地保留这些更改。每次成功提交 MUST 裁剪并交付该操作所提交的值,然后通过同一值通道清除。 公共类型与文档;architecture:public-component-api/INV3, INV9, INV12;聚焦测试
FR2 默认编辑器 MUST 序列化其当前文本/tokens,在不按 Shift 的情况下提交 Enter,保留 Shift+Enter,在 IME 组合期间延迟提交,并允许调用方的按键处理器阻止默认操作。 实现、文档和聚焦测试
FR3 isDisabled MUST 阻止草稿编辑和提交,并且 MUST 在默认文本框上暴露 aria-disabled="true";移除该 prop MUST 移除该状态。 spec:AST-020/FR1(WCAG 2.2 4.1.2);architecture:interaction-modality/INV5;红/绿聚焦测试
FR4 当 isStopShown 为 true 时,默认主操作 MUST 保持为可用且带名称的 Stop 按钮并调用 onStop;如果编辑同时被禁用,祖先样式 MUST NOT 阻止其指针、触摸或键盘激活。 architecture:interaction-modality/INV4, INV7, INV9;红/绿聚焦测试和浏览器 story 测试
FR5 省略的 header 插槽 MUST 省略标题行;抽屉位于主体之前;输入填充页眉与页脚之间的主体;页脚操作位于发送操作和主操作之前;状态遵循 statusPosition。 实现、props、stories 和 blocks
FR6 compact 减少主体的内边距和间距;balanced 和 spacious 产生相同的主体间距。spacious 是否应当不同仍未决(OQ3)。 实现与已发布的联合类型;当前没有所有者选择不同的 spacious 几何设置
FR7 low 在静止状态应用低阴影层级,在悬停和 focus-within 状态应用中等级别;none 不应用阴影并应用边框。实现缺口:公共目标未触及已绘制的主体(当前状态影响;OQ1)。 实现;architecture:component-theming-surface/INV4, INV6;chat-composer 目标位于框架上(当前状态影响)
FR8 键盘焦点进入已注册/默认编辑器时,MUST 在主体上添加共享焦点指示;指针焦点 MUST NOT 添加该额外环。点击非交互式主体空间 MUST 聚焦已注册控件,然后是 textarea 回退;在打开的 Tooltip 或 HoverCard 表面内的点击不属于主体空间(component:Tooltip FR11、component:HoverCard FR11),architecture:layer-runtime INV17 的条款涵盖了每一层。 实现;architecture:interaction-modality/INV1–INV3, INV9;聚焦测试
FR9 错误状态通过共享通告频道以断言(assertive)方式宣布,警告状态以礼貌(polite)方式宣布,每个场景只宣布一次:即一次状态转换;重新渲染或更新为相同的值不会重复宣布(spec:AST-086 FR6);状态栏本身不带有 live role。两者都将语义图标与颜色配对,并且可以在主体上方或下方渲染。 实现、文档和 stories;spec:AST-020/FR1;spec:AST-086/FR2, FR5, FR6
FR10 ref、DOM 属性和事件、className 以及 style 到达外层框架;xstyle 到达绘制主体。实现差距:样式输入分布在两个元素上(当前状态影响;OQ2)。 实现;architecture:public-component-api/INV5–INV6, INV8
FR11 导出的上下文 MUST 向自定义组合暴露当前值、更改和提交操作、占位符、禁用/停止/发送状态、停止回调,以及可变的输入焦点控制。 公开导出、类型、文档、stories 和针对性测试;architecture:public-component-api/INV12

允许的变体

  • AV1 — 插槽内容。 调用者可省略或替换每个命名插槽,同时保持组合器的 value、提交、焦点和禁用契约。
  • AV2 — 产品工作流。 调用者决定何时显示状态或 Stop,以及他们的回调做什么;ChatComposer 仅拥有本地可供性和分发。
  • AV3 — 编辑器实现。 自定义输入可以是 textarea、contenteditable 编辑器或其他控件,只要它遵循导出的上下文和焦点控制契约即可。

代表性状态

状态 必需不变式 允许的变体
空草稿 默认发送操作处于禁用状态,且提交不会触发。 占位符和可选插槽可以变化。
非空草稿 按 Enter 或 Send 提交一个去除首尾空格后的值,并通过当前所有权通道清除。 序列化的 token 表示和传输行为可以变化。
受控草稿 调用者的 value 保持权威;onChange 接收编辑和清除请求。 调用者可以接受或推迟每次更新。
自定义输入 上下文操作作用于提供的 value,主体点击使用其注册的焦点控制。 DOM/编辑器实现会变化。
禁用编辑 默认文本框暴露禁用状态,并且无法编辑或提交。 辅助内容保持可见。
禁用、可中断的工作 Stop 保持已命名、已启用,并可通过指针、触摸和键盘访问。 产品的取消行为可以变化。
扁平抬升 主体没有阴影,并使用其带边框的呈现方式;键盘焦点指示仍然可用。 主题 token 可以变化。
状态在上方或下方 通告的紧急程度、图标、颜色和所选位置保持同步。 消息内容和状态类型可以变化。
窄视口 组合器保持在其包含的内联尺寸内,并且主要操作仍然可操作。 可用内联尺寸和可选插槽内容可以变化。

转换与优先级顺序

  • ORD1 — 值更新。 接收编辑器值 → 在受控时通过 onChange 发布,或在非受控时更新本地状态 → 派生当前上下文值和发送可用性。
  • ORD2 — 提交。 接收操作提供的值 → 去除首尾空格 → 拒绝空提交或禁用状态下的提交 → 调用公共 onSubmit 一次 → 通过当前值通道请求清除。
  • ORD3 — 主要操作。 解析 isStopShown → 若显示 Stop 则暴露 Stop 并分发 onStop,否则根据当前草稿和禁用状态派生发送可用性 → 提交当前上下文值。
  • ORD4 — 组合顺序。 可选顶部状态 → 抽屉 → 主体头部 → 输入 → 底部操作 → 发送操作 → 主要操作 → 可选底部状态。

性能与资源

  • PR1 — 上下文稳定性。 当导出的上下文的公共成员均未变化时,其值应当保持引用稳定性。
  • PR2 — 焦点协调。 该组件不会为主体点击焦点或焦点指示添加自己的 document 监听器或观察器;它会挂载共享的 interaction-modality 跟踪器,该跟踪器会添加文档级的 pointerdown 和 keydown 监听器(architecture:interaction-modality)。

可访问性契约

  • AR1 — 编辑状态。 默认的 contenteditable 表面充当文本框,当编辑不可用时,必须通过 aria-disabled 暴露禁用状态。
  • AR2 — 原生操作。 默认的发送和停止控件保持为带有可访问名称的原生按钮;禁用发送使用原生禁用行为,而显式的停止仍保持可操作。
  • AR3 — 键盘编辑。 Enter 提交必须保留 Shift+Enter 换行行为、IME 组合输入,以及通过 preventDefault() 实现的调用方取消。
  • AR4 — 焦点指示。 编辑器中的键盘焦点必须产生共享的可见焦点处理;指针焦点不主张键盘模态,内部操作上的焦点仍归该操作所有。
  • AR5 — 状态反馈。 错误反馈通过共享通知通道以断言方式播报,警告反馈以礼貌方式播报(spec:AST-086 FR2、FR5);可见状态栏不承担 live 角色并保持可读性。可见图标和颜色不替代调用方的消息内容。

设计关系

解剖结构或状态 设计要求 表示权威性 层级角色 组件契约
编辑器框架 将主体和可选状态组合成一个合成外壳。 当前源码 container FR5
编辑器主体 提供绘制好的圆角输入/操作表面和高度。 高度已随产品提供;公共主题可达性尚未确定 prominent FR7
抽屉 将附件/上下文内容放置在主体之前。 委派给 component:ChatComposerDrawer supporting FR5
标题 将调用方操作放置在起始位置,将调用方上下文放置在末尾。 当前源码 supporting FR5
输入 拥有或承载编辑表面及其焦点控制。 委派给 component:ChatComposerInput 或调用方自定义输入 prominent FR1–FR3、FR8、FR11
页脚 将调用方操作和主要操作放置在主体最后一行。 当前源码 supporting FR4–FR5
发送或停止操作 呈现当前的主要操作。 委派给 component:ChatSendButton 或调用方自定义发送按钮 prominent FR1、FR4
状态消息 在主体之前或之后添加错误或警告反馈。 共享通道播报和颜色已随产品提供;此处不主张单独的公共主题可达性 supporting FR5、FR9、AR5

公共 chat-composer 目标位于框架上,无法选择主体的高度和边框(当前状态影响)。尚未记录解剖结构-主题映射;迁移期间该块是可选的,因此该映射被推迟。

家族与系统关系

  • 当前没有家族或设计记录管辖 ChatComposer 特定行为。
  • architecture:public-component-api 拥有 BaseProps 元素所有权、回调语义以及导出的组合上下文。
  • architecture:interaction-modality 拥有模态对等性、焦点所有权,以及已启用的停止按钮保持可达的要求。
  • architecture:component-theming-surface 拥有解剖结构到目标的处置方式,并在不决定修复形态的情况下使当前主体可达性不匹配成为阻塞项。
  • architecture:component-test-sufficiency 拥有公共状态分区、否定断言、可观察输出以及精确的浏览器边界。
  • architecture:react-component-runtime 拥有渲染派生状态和浏览器/服务器边界。
  • architecture:knowledge-contracts 将消费者语法保留在 ChatComposer.doc.mjs 中,将系统行为保留在本记录中。
  • spec:AST-020/FR1 承载当前的 WCAG 2.2 可访问性基线。
  • spec:AST-029 拥有本记录验证映射所遵循的审计证据清单。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1、FR11 ChatComposer.test.tsx 输入组合测试 上下文提供的值、自定义输入读取值、变更和禁用 忽略其参数的上下文提交,或自定义输入无法读取的上下文成员,则失败。 audit:ChatComposer/api-behavior
FR2, AR3 ChatComposerInput.test.tsx Enter、Shift+Enter、组合输入中、已取消的 keydown 在组合输入期间发送消息或丢失换行的按键路径将失败。 audit:ChatComposer/input-behavior
FR3, AR1 ChatComposer.test.tsx “在默认文本框上暴露禁用状态,并在启用时清除该状态” 已禁用并重新启用的默认文本框 若文本框错误地丢失或保持禁用状态,则失败。 audit:ChatComposer/accessibility
FR4, AR2 ChatComposer.test.tsx “在编辑被禁用时保持 Stop 操作可被指针操作”;ChatComposer.stories.tsx 中的 DisabledStreamingNarrow story 的 play 函数 禁用编辑但显示 Stop;没有水平溢出的窄视口 若 Stop 操作被祖先阻断,或未调用 onStop,则失败。 audit:ChatComposer/modality
FR7 ChatComposer.test.tsx 中的 elevation 测试 low 默认、none 若不同级别共享同一个 body 类,或默认值不是 low,则失败。 audit:ChatComposer/theming
FR8, AR4 ChatComposer.test.tsx 的焦点指示测试和自定义输入焦点测试;“在 body 中点击打开的 tooltip 不会使输入框获得焦点” 键盘、指针、每种之后的程序化聚焦、内部按钮、body 点击 指针聚焦时出现焦点环、键盘聚焦时缺少焦点环,或 body 点击跳过控件,均失败。 audit:ChatComposer/focus
FR9, AR5 ChatComposer.test.tsx 的状态播报测试 错误、警告、StrictMode 挂载、清除后重复播报、无消息、页面加载 状态栏上出现 live role、播报重复或缺失、或紧急程度错误,均失败。 audit:ChatComposer/accessibility

以下内容来自源码,尚无专注的测试:

  • FR1:受控和非受控草稿存储、修剪、拒绝空提交或禁用提交,以及通过活动通道清除。
  • FR5:slot 顺序、省略的标题行,以及状态在正文上方或下方的放置位置。
  • FR6:密度间距。
  • FR7:每个 elevation 的阴影和边框值。
  • FR10:每个 BaseProps 输入落在哪里。
  • PR1–PR2:上下文稳定性,以及没有组件自身的 document 监听器或观察器。

决策日志

没有记录任何组件本地的决策。

开放问题

  • OQ1 — 正文主题可达性。 是否应添加一个新的稳定正文目标,是否应移动已发布的 chat-composer 目标,还是应通过另一种兼容机制将 elevation 投射到现有根目标上?(human-api)
  • OQ2 — BaseProps 的归属者。 ref、中性 DOM 属性/事件、className、style 和 xstyle 是都应归属外部框架还是绘制后的正文?以及什么兼容性路径能保留现有使用者?(human-api)
  • OQ3 — 宽松密度。 spacious 是应有意识地作为 balanced 的别名,还是应获得由设计选定的不同间距?(human-design)
  • OQ4 — Stop 回调不变量。 当 isStopShown 为 true 且没有 onStop 时,组件是应拒绝该组合、禁用或隐藏 Stop,还是保留当前无操作的动作?(human-api)

内容边界

本文件不重复使用者的属性表/示例、当前审计结果、实现步骤或共享系统规则,而是链接到这些内容的所属方。

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