ChatSendButton 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 导出的控件根据 props(优先于 ChatComposer 上下文)选择发送或停止呈现,接受 sm 或 md,支持图标覆盖,并使用受支持的 Button DOM、事件、样式和 ref 输入扩展所渲染的 Button。 |
| 行为 | 发送会因显式或 composer 就绪状态而禁用,停止保持启用;状态特定操作在组合的通用点击处理器之前运行;当前发送图标先从显式覆盖解析,然后才使用共享回退。 |
| 最终用户影响 | 用户会获得一个已翻译且符合状态的发送或停止操作,其可用性遵循 composer 就绪状态。 |
| 构建者影响 | 无。 |
| 兼容性/就绪性 | 记录已发布行为;无公共更改。有一个实现差距,列在“当前状态影响”下。 |
| 审查检查 | 拒绝:丢失发送/停止路由、使用方事件取代状态操作、禁用停止操作、无标签的纯图标输出、丢弃根输入、丢失显式优先发送图标或 arrowUp 回退。 |
| 约束规则 | spec:AST-032 FR2–FR3;architecture:public-component-api INV5–INV8;architecture:interaction-modality;architecture:component-test-sufficiency;spec:AST-020;spec:AST-029。 |
此表是审查投影;以下正文具有权威性。
意图¶
ChatSendButton 是 ChatComposer 使用的紧凑型操作控件。它把 composer 就绪状态和流式状态转化为共享的 Button,同时保留操作、图标、样式和 ref 接缝,供独立组合使用。
兼容性与迁移¶
- 已发布的默认值是否保留:
yes - 兼容性类别:记录已发布行为;无公共更改
- 受控/非受控行为:不适用;显式 props 优先于上下文派生的值
- 迁移决策:无
使用方迁移说明应放在使用方文档和发布说明中。
当前状态影响¶
- 发送图标没有组件插槽阶段。 发送图形从
sendIcon解析,然后使用共享的arrowUp。spec:AST-032FR2–FR3 在该解析中加入了组件图标插槽阶段;ChatSendButton 尚不提供此阶段(FR3)。
所有权边界¶
拥有
- 发送或停止状态的选择。
- 状态特定的已翻译无障碍名称和 Button 变体。
- Composer 上下文对就绪状态和操作的回退。
- 组件接缝处的发送和停止图标选择。
- 状态操作与已接受的通用点击处理器的组合。
chat-send-button主题目标和圆形根节点处理。
不拥有 / 非目标
- ChatComposer 的值编辑、提交生命周期、流式生命周期或放置位置。
- 共享 Button 的激活、焦点、禁用语义、点击区域或基础样式。
- 共享图标图形或主题图标注册。
- 关于
isStopShown是否可以在没有停止操作的情况下出现的公共策略。
公共概念¶
使用方语法保留在 ChatSendButton.doc.mjs 中。此清单界定了可观察的语义表面,且不重复 props 表。
| 概念 | 封闭值或状态 | 含义 | 不同变体/方向/状态下的可用性 | 默认值 | 归属 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 操作状态 | 发送;停止 | 选择名称、Button 变体、图标角色、禁用规则和状态操作。 | 每次渲染时。 | Composer isStopShown,否则为发送。 |
component:ChatSendButton |
稳定 | 布尔 prop 类型之外的值不受支持。 |
| 可用性 | 启用;禁用 | 当内容未就绪时阻止发送激活。停止操作有意忽略此规则。 | 禁用仅适用于发送。 | 显式 isDisabled,否则为 composer canSend 的反值。 |
组件和 ChatComposer 上下文 | 稳定 | 布尔 prop 类型之外的值不受支持。 |
| 操作 | 状态回调;composer 回退;组合的通用点击 | 先运行状态操作,然后运行已接受的使用方点击处理器。 | 发送和停止激活启用时。 | onSend 或提交当前值;onStop 或上下文停止。 |
组件、上下文和调用方 | 稳定 | 如果没有状态回调或匹配的上下文操作,则只有提供的通用点击可以运行。 |
| 发送图标 | 显式内容;共享回退 | 为发送状态选择图标资源。 | 发送状态。 | sendIcon,然后是共享的 arrowUp。 |
组件与调用方 | 稳定 | 不支持的 React 内容遵循共享 Button 的渲染边界。 |
| 停止图标 | 显式内容;共享回退 | 为停止状态选择图标资源。 | 停止状态。 | stopIcon,然后是共享的 stop。 |
组件与调用方 | 稳定 | 不支持的 React 内容遵循共享 Button 的渲染边界。 |
| 尺寸 | sm;md |
选择委托的 Button 尺寸,同时保留圆形处理。 | 两种状态。 | md。 |
component:ChatSendButton |
稳定 | 公共联合类型之外的值会被 TypeScript 拒绝。 |
| 根表面 | ref;受支持的 Button DOM/data/ARIA/events;style/class/xstyle | 扩展并样式化所渲染的 Button,但不替换组件自有的动作逻辑。 | 每次渲染。 | 省略。 | architecture:public-component-api |
稳定 | 不支持的 BaseProps 省略项仍不受支持;组件自有语义在意外冲突中胜出。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 发送状态 MUST 渲染一个以发送文案命名的仅含图标的 primary Button,并且当显式或由上下文推导的就绪状态为 false 时,它 MUST 被禁用。 | 当前实现、文档、测试、spec:AST-020 以及共享 Button 行为 |
| FR2 | 停止状态 MUST 渲染一个以停止文案命名的仅含图标的 secondary Button,无论发送就绪状态如何都保持启用,并调用显式或上下文的停止行为。 | 当前实现、文档和测试 |
| FR3 | 发送图标解析优先使用 sendIcon,否则解析共享的 arrowUp。实现缺口:spec:AST-032 FR2–FR3 所要求的组件图标槽位阶段未提供(当前状态影响)。 |
当前实现、文档、测试以及 spec:AST-032 中当前负责人的要求 |
| FR4 | 停止图标解析优先使用 stopIcon,否则解析共享的 stop 图标。 |
当前实现、文档和测试 |
| FR5 | 显式的 state、disabled、callback、icon 和 size 属性 MUST 优先于其上下文或组件回退。通用的已接受点击处理器 MUST 在所选状态动作之后组合,而不是替换它。 | 当前源码和测试;architecture:public-component-api INV5–INV7 |
| FR6 | 受支持的 Button DOM、data、ARIA、className、style、xstyle 和 ref 输入 MUST 到达或在所渲染的 Button 上组合,同时组件自有的标签、状态和激活行为保持完整。 | 当前实现以及 architecture:public-component-api/INV5-INV8 |
| FR7 | 组件 MUST 在共置的 chat-send-button 目标上通过共享 Button 呈现,并保持其圆形组件处理。 |
当前实现、Chat 消费者文档以及 architecture:component-theming-surface |
允许的变体¶
- AV1 — 上下文或独立组合。 构建者可以依赖 ChatComposer 上下文,或显式提供所有 state、action 和 disabled 值。
- AV2 — 图标资源。 显式的发送与停止内容以及共享回退图标资源可以在图标解析 FR3 和 FR4 状态下有所变化。
- AV3 — 消费者样式。 受支持的样式输入可以扩展 Button,同时组件自有的状态和激活行为保持不变。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| ---------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------- |
| 发送,禁用 | 本地化的主要发送操作不可用,并且不会运行回调。 | 图标来源、尺寸、主题及消费者样式。 |
| 发送,启用 | 本地化的主要发送操作运行显式或上下文提交。 | 图标来源、尺寸、主题及消费者样式。 |
| 停止 | 本地化的次要停止操作保持启用,并运行显式或上下文停止。 | 图标来源、尺寸、主题及消费者样式。 |
| 显式覆盖 | 显式状态、回调、图标、禁用值和尺寸在其回退接缝处优先。 | 上下文仍可提供未指定的值。 |
| 组合通用点击 | 状态操作与被接受的通用点击都会运行,且不会相互替换。 | 任一处理器均可不存在。 |
转换与优先级顺序¶
- ORD1 — 解析状态。 显式
isStopShown优先,其次是组合器上下文,然后是发送状态。 - ORD2 — 解析操作。 显式状态回调优先于其组合器回退。所选状态操作在接受的通用点击处理器之前运行,因为此组件不承诺消费者取消其状态操作。
- ORD3 — 解析可用性。 停止操作保持启用。发送操作优先使用显式
isDisabled,其次使用组合器就绪状态的反向值,再其次是在上下文之外时为禁用。 - ORD4 — 解析图形。 在发送状态下,显式
sendIcon优先,其次是共享的arrowUp;在停止状态下,显式stopIcon优先,其次是共享的stop。spec:AST-032FR2 所要求的组件图标槽阶段尚未提供(FR3)。 - ORD5 — 组合根节点。 应用组件自有的 Button 语义和
chat-send-button目标,同时保留受支持的消费者根节点输入。
性能与资源¶
- PR1 — 仅渲染投影。 该组件不添加任何 Effect、观察器、监听器、计时器、状态镜像或自有的异步生命周期。
无障碍契约¶
- AR1 — 原生操作语义。 委托的 Button MUST 拥有原生按钮激活、键盘行为、焦点指示和禁用语义。
- AR2 — 与状态匹配的名称。 仅图标的控件 MUST 独立于图标图形,暴露当前本地化的发送或停止标签。
- AR3 — 禁用的发送行为。 禁用的发送操作 MUST NOT 调用状态操作或消费者点击处理器。
- AR4 — 输入方式对等。 指针和键盘激活 MUST 走相同的状态操作和组合事件路径。
设计关系¶
| 结构或状态 | 设计需求 | 表现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 操作按钮 | 携带当前发送或停止操作的圆形紧凑 Button。 | 当前源代码和消费者文档;精确调整保留在代码中 | 主要/次要操作 | FR1, FR2, FR7 |
| 发送图形 | 向上发送字形,除非显式内容优先(FR3 的缺口)。 | 当前源代码和文档;spec:AST-032 FR2–FR3 |
操作提示 | FR3 |
| 停止图形 | 共享停止字形,除非显式内容优先。 | 当前源代码和消费者文档 | 操作提示 | FR4 |
此记录不选择新的尺寸、变体、图标图形、颜色角色或视觉突出度。尚未记录任何结构主题映射;该块在迁移期间是可选的,因此该映射被推迟。
Chat 家族消费者文档收录了 chat-send-button。Button 拥有底层绘制和交互状态样式;组件目标与该绘制元素共置。
家族与系统关系¶
- ChatComposer 拥有值、就绪状态、提交、停止生命周期和放置。
- Button 拥有共享的激活、焦点、禁用语义、点击区域和绘制。
architecture:public-component-api拥有 BaseProps 可达性、样式/ref 组合以及有意的组合事件。architecture:icon-resolution-and-component-slots拥有共享槽模型;spec:AST-032FR2–FR3 在发送解析中引入了组件槽阶段,但该阶段未发布(当前状态影响)。architecture:component-theming-surface拥有共置的chat-send-button目标的限定与放置。architecture:interaction-modality与spec:AST-020拥有通过 Button 继承的指针、键盘、焦点和无障碍对等性。architecture:component-test-sufficiency拥有公共接缝的回归覆盖。spec:AST-029拥有此记录的验证映射所遵循的审计证据清单。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, FR2, AR1-AR4 | ChatSendButton.test.tsx、ChatSendButton.a11y.chromium.spec.ts 和 ChatComposer.test.tsx |
启用/禁用发送、有/无处理器的停止、上下文停止、键盘/指针、浅色/深色交互状态 | 标签、禁用、原生激活、状态路由或交互绘制漂移会在聚焦或精确头部浏览器证据中失败。 | audit:ChatSendButton/accessibility |
| FR3 | ChatSendButton.test.tsx |
显式和共享回退发送图标 | 失去显式优先优先级或 arrowUp 回退会导致聚焦测试失败;spec:AST-032 插槽阶段不在此处测试。 |
audit:ChatSendButton/theming |
| FR4 | ChatSendButton.test.tsx |
显式和回退停止图标 | 失去显式优先级或注册表解析失败会导致聚焦断言失败。 | audit:ChatSendButton/behavior |
| FR5, FR6 | ChatSendButton.test.tsx 回调组合、顺序、尺寸、根节点直通、禁用点击和键盘测试 |
发送、停止、sm/md、ref/class/data/ARIA、Enter/Space |
消费者事件取代状态操作、取消重排序、根输入丢失或模态漂移会导致聚焦测试失败。 | audit:ChatSendButton/api |
| FR7 | themingTargets.test.ts 和 ChatSendButton.a11y.chromium.spec.ts |
发送和停止主题 | 目标被移除、移出绘制范围或未记录的目标漂移会导致测试或浏览器证据失败。 | audit:ChatSendButton/theming |
| RTL 关系 | RTL 共享夹具路由,以及针对 ChatSendButton 和 ChatComposer 刷新的已验证不适用(N/A)源码收据 | 发送和停止 | 方向性图形、物理定位或变换会使已签入的收据失效。 | audit:ChatSendButton/i18n-rtl |
| 浏览器矩阵 | ChatSendButton.a11y.chromium.spec.ts 浏览器状态 |
浅色/深色发送和停止的 rest/hover/focus/press、禁用状态的 rest/hover、sm/md、320px 粗指针、D7 对比度对 |
过期构建、诱饵选择器、缺失状态、改变的禁用绘制、缺失的交互像素、对比度失败或几何偏差均会失败关闭(fail closed)。 | audit:ChatSendButton/visual |
| 文档与公开表面 | 消费者文档、导出检查、Storybook 和 check:knowledge |
Props、公共子路径、状态、合约 | 缺失或过期的文档、导出、关系或所需结构无法通过验证。 | audit:ChatSendButton/docs |
从源码读取,尚无聚焦测试:
- FR5:显式 props 优先于 ChatComposer 上下文。
- FR6:
style和xstyle到达根元素。
决策日志¶
未记录任何组件级决策。
未决问题¶
- 交叉引用:无处理器的停止。
component:ChatComposer/OQ4负责处理可见停止操作在缺少显式或上下文onStop时的未决策略。本记录覆盖当前已启用的无操作分支,而不重复该问题。
内容边界¶
本文件不重复消费者示例、审计评分、截图、资格数据或共享的 Button 与图标系统规则,而是链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx