ChatComposerDrawer 组件契约¶
契约速览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 新增一个可选的 collapsedSummary?: ReactNode 插槽,名称取自规范结构部件 Collapsed summary,用于由调用方组合的视觉内容。 |
| 行为 | count 仍用于启用披露。省略 collapsedSummary 时,保持中性 Badge 计数加已解析标签;提供该插槽时,会替换这一完整视觉摘要,但不会改变折叠行为或命名。 |
| 最终用户影响 | 默认情况下,用户仍保有既有的 Badge 层级。需要更低调或以不同方式组合折叠行的产品,可以提供一个本地化的视觉摘要,同时不削弱披露语义。 |
| 构建者影响 | 现有调用点无需更改。选择该插槽的构建者负责其视觉内容和本地化,而 label 仍用于标识受控内容,以提供组件自身的无障碍名称。 |
| 兼容性/就绪度 | 新增且保持默认不变。本记录为当前权威依据;该插槽及其对应的实现、消费者文档、测试和渲染证据尚未发布。 |
| 审查检查 | 应拒绝:纯文本默认实现、第二个摘要 API、会改变命名或折叠状态的自定义内容、视觉摘要内可达的交互式后代,或对无插槽与无计数路径的任何回归。 |
| 治理规则 | component:ChatComposerDrawer/FR1–FR10, AR1–AR4, DEC-1–DEC-2;architecture:public-component-api/INV3–INV4, INV9, INV13;spec:AST-002/DEC-1, DEC-2。 |
此表是审查投影;下文正文具有权威性。
意图¶
ChatComposerDrawer 在 ChatComposer 输入框上方组合补充内容。当存在 count 时,构建者可以让用户折叠该内容,同时保留一个紧凑摘要供使用。
两个在其他方面完全相同的抽屉,在折叠状态下可能需要不同的视觉层级。产品构建者知道是既有的 count Badge 还是更低调、针对产品定制的摘要更适合该上下文,而 ChatComposerDrawer 无法从 count、内容、布局、语言区域或折叠状态中推导出这一区别。因此,该组件暴露一个视觉组合接缝,同时保留其现有默认行为,并拥有全部披露行为。
兼容性与迁移¶
- 已发布默认行为得到保留:是。省略
collapsedSummary时,保持中性 count Badge,其后跟随已解析标签。 - 兼容性类别:新增式可选组合插槽,无默认行为变更。
- 受控/非受控行为:不变。
- 迁移决策:无。现有调用点无需任何编辑。
消费者迁移说明应放入消费者文档和发布说明。
所有权边界¶
拥有
- 抽屉表面、可选披露状态、披露关联,以及折叠后代的可用性。
- 受控与非受控折叠请求。
- 保留 Badge 的默认摘要,以及一个由调用方组合的折叠摘要的纯展示边界。
- 披露控件的本地化无障碍名称,不受视觉摘要内容影响。
不拥有 / 非目标
- 调用方提供的抽屉子内容或自定义摘要内容的含义、样式或本地化。
- 自定义摘要内部的交互行为;摘要仅为视觉内容,绝不创建另一个焦点或激活目标。
- ChatComposer 输入、提交、状态和操作行为。
- 呈现枚举、Badge 开关、渲染回调、摘要专用主题目标,或第二个无障碍名称属性。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 抽屉内容 | 任意 React 节点 | 组合在聊天输入框上方的补充内容。 | 始终 | 无 | component:ChatComposerDrawer |
稳定 | 缺少内容会被必需类型拒绝。 |
| 折叠支持 | 不可用、已展开、已折叠 | count 存在(包括为 0)时,启用一个披露控件并提供其摘要计数。 |
省略 count 时不可用 |
不可用 | component:ChatComposerDrawer |
稳定 | 没有 count 时,折叠输入不会产生可见效果。 |
| 折叠控制 | 非受控、受控 | 由内部状态或 isCollapsed 决定当前披露状态。 |
当折叠支持可用时 | 非受控 | component:ChatComposerDrawer |
稳定 | 受控状态优先于初始默认值。 |
| collapsed summary | 默认、调用方组合 | 折叠披露所展示的视觉内容。 | 当折叠支持可用时 | 中性 Badge 加上 label | 调用方选择;组件接缝 | 已接受,未发布 | 省略时使用默认值;没有 count 时不暴露任何摘要。 |
| collapse request | 下一状态 | 激活请求相反的有效折叠状态。 | 当折叠支持可用时 | 无 | component:ChatComposerDrawer |
稳定 | 没有披露控件时不发出任何请求。 |
collapsedSummary 是规范 Collapsed summary 解剖部件的 camelCase 公共 API 投影。它是完整的自定义视觉摘要,而不是默认内容之前或之后的附加内容。该组件不会解析、克隆、装饰或向该节点提供数据。构建者已经拥有他们作为 count 和 label 传入的值;当自定义摘要构成句子或格式化数字时,其调用点拥有完整的本地化消息。
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 当存在 count 时,包括其为 0 时,组件 MUST 公开一个带有 aria-expanded 和可解析的 aria-controls 关系的命名披露控件。 |
已发布 API 和实现;WAI-ARIA 披露语义 |
| FR2 | 指针激活、Enter 和 Space MUST 恰好请求一次相反的有效折叠状态。 | 已发布实现和公共回调契约 |
| FR3 | 在受控模式下,isCollapsed MUST 保持权威;在非受控模式下,激活 MUST 在下次渲染前更新内部状态。 |
已发布实现和消费者文档 |
| FR4 | 折叠抽屉的内容可以保持挂载以进行网格过渡,但其后代 MUST 不参与键盘和辅助技术导航。 | WAI-ARIA 披露语义;WCAG 2.4.3 和 2.4.7 |
| FR5 | 通过共享的焦点指示器机制,披露控件上的键盘焦点 MUST 保持清晰可感知。 | architecture:interaction-modality/INV1–INV4 |
| FR6 | 省略 count 时,MUST 直接渲染抽屉内容,MUST NOT 创建披露控件,且 MUST NOT 暴露 collapsedSummary。在此状态下,现有的折叠输入继续不产生可见效果。 |
已发布的 no-count 行为和兼容性 |
| FR7 | 根节点 MUST 继续转发其 ref、BaseProps 属性和样式接缝,而不将它们移动到内部子节点。 | 已发布公共表面和 architecture:public-component-api/INV5–INV6, INV8–INV9 |
| FR8 | collapsedSummary MUST 保持为规范 Collapsed summary 解剖部件的 camelCase 公共名称。省略时,折叠披露 MUST 保留现有的中性 Badge,其中包含 count,后接解析后的 label;提供时,该节点 MUST 恰好一次替换该完整解剖部件。 |
经批准的解剖对齐调用方组合边界和已发布默认值 |
| FR9 | 自定义摘要 MUST 仅影响视觉内容。它 MUST NOT 改变折叠是否可用、有效折叠状态、切换控件激活、回调值、受控区域或组件拥有的无障碍名称。 | 受限插槽契约与 spec:AST-002/DEC-2 |
| FR10 | 摘要子树 MUST 保持仅呈现:disclosure 是唯一的焦点和激活目标;摘要后代 MUST 不出现在 Tab 顺序和无障碍树中;自定义内容 MUST NOT 添加另一个操作。 | WAI-ARIA disclosure 语义与组件拥有的无障碍边界 |
允许的变体¶
- AV1 — Drawer 子内容组合。 构建者选择 drawer 内容及其自身语义。
- AV2 — 自定义摘要组合。 构建者可以组合任何符合仅呈现边界的内容,包括本地化文本或现有的 Astryx 显示组件。
- AV3 — 摘要生命周期。 组件可以在视觉展开期间保持默认或自定义摘要的挂载,以保留动画。调用方 MUST NOT 依赖挂载或卸载时机。
- AV4 — 自定义摘要样式。 调用方组合的内容保留其所使用组件的样式和主题接缝。ChatComposerDrawer 不会添加摘要特定的目标。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变体 |
|---|---|---|
count 省略 |
内容可见;不暴露任何 disclosure 或摘要。 | 子内容与根样式。 |
| 默认摘要,已折叠 | 一个 disclosure 显示中性计数的 Badge 以及解析后的 label。 | 计数值与本地化标签。 |
| 自定义摘要,已折叠 | 一个 disclosure 显示调用方节点,而非两个默认摘要部分。 | 仅呈现的自定义内容与样式。 |
| 自定义摘要,已展开 | disclosure 保留其状态和名称;自定义摘要可保持挂载,但在视觉上和语义上隐藏。 | 内部交叉淡化与挂载时机。 |
| 受控已展开或已折叠 | 渲染状态遵循 isCollapsed;激活时报告请求的下一个状态。 |
父级时机及其是否接受请求。 |
转换与优先级顺序¶
- ORD1 — 折叠可用性。
count存在 → disclosure 启用;count省略 → 无 disclosure 或已折叠摘要。 - ORD2 — 有效状态。 定义了
isCollapsed时 → 使用该值;否则使用由defaultIsCollapsed初始化的内部状态。 - ORD3 — 视觉摘要。 调用方提供的
collapsedSummary→ 否则是count的中性 Badge 后跟解析后的label。 - ORD4 — 无障碍名称。 从 prop 或区域设置目录解析
label→ 对有效状态使用目录中的展开或折叠操作消息。视觉摘要内容永远不会进入或覆盖此管道。
性能与资源¶
- PR1 — 仅本地状态。 摘要接缝 MUST NOT 需要 Effect、观察器、监听器、计时器或外部资源。
无障碍契约¶
- AR1 — Disclosure 关系。 该切换控件暴露一个本地化名称、展开状态,以及一个可解析的受控内容 ID。
- AR2 — 命名保持组件所有。
label在展开/折叠目录消息中标识受控的 drawer 内容。默认或自定义视觉摘要文本 MUST NOT 替换、重复或拼接到该无障碍名称中。 - AR3 — 隐藏内容不可用。 视觉上折叠的 drawer 后代在展开之前不可用。
- AR4 — 自定义摘要保持仅呈现。 自定义内容不能在 disclosure 内添加第二个焦点停留点、激活目标、角色或公告。
设计关系¶
目前没有任何设计规范约束这种组件局部的表示。
| 结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 根表面 | 现有已发布表面不因该决定而改变。 | 已发布行为 | 支持 | FR7 |
| 展开/收起开关 | 一个可操作且具名控件拥有折叠交互。 | 组件所有 | 辅助 | FR1–FR5, AR1 |
| 折叠摘要 | Badge 层级保持默认;调用方可选择一个视觉组合插槽。 | 组件默认或调用方选择的组合 | 辅助 | FR8–FR10, AR2–AR4 |
| 内容区域 | 折叠后的后代内容保持对键盘和辅助技术不可用。 | 组件所有 | 辅助 | FR4, FR6, AR3 |
现有的 chat-composer-drawer 目标仍保留在已绘制的根元素上。保留 Badge 的默认实现将计数绘制委托给 Badge。调用方组合的摘要内容保留其所提供组件的主题所有权。此决定不会新增 ChatComposerDrawer 摘要目标,也不会将任意插槽内部内容纳入 ChatComposerDrawer 的主题 API。
家族与系统关系¶
architecture:public-component-api负责新增插槽的可达性、命名语法和兼容性;本组件拥有其局部含义和默认值。architecture:interaction-modality负责共享的焦点可见性机制;本组件拥有该展开控件并作为其语义焦点所有者。architecture:component-theming-surface负责目标和结构映射规则;自定义摘要不会创建新目标,也不会转移调用方内容的所有权。architecture:knowledge-contracts将当前权限限制为本记录中的明确声明。spec:AST-002/DEC-1允许该插槽存在,因为其他方面完全相同的抽屉可能需要调用方拥有的、组件无法推导的视觉层级。DEC-2要求该接缝保留可靠且无障碍安全的结果。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1–FR3, FR6, ORD1–2 | 聚焦 ChatComposerDrawer 状态和键盘测试 | 无计数;零计数;受控;不受控;指针;Enter;Space | 存在性/真值变化改变折叠可用性、状态权威发生变化,或回调报告错误的下一状态。 | audit:ChatComposerDrawer/behavior |
| FR8–FR9, ORD3 | 聚焦默认/自定义摘要测试和消费者文档投影检查 | 默认;自定义节点;展开;折叠;无计数 | 默认 Badge 消失、默认与自定义内容同时渲染、自定义内容改变行为,或无计数情况将其暴露。 | audit:ChatComposerDrawer/api |
| FR4, FR10, AR2–AR4 | 聚焦惰性状态和自定义后代测试,以及 exact-head 无障碍 CI | 默认文本;自定义文本;可聚焦的自定义后代;折叠/展开 | 隐藏的抽屉内容或自定义摘要变为可聚焦、可被播报,或成为第二个动作;视觉文本替换目录名称。 | audit:ChatComposerDrawer/accessibility |
| FR5, AR1 | KeyboardFocus Storybook 测试脚本和 exact-head 视觉/无障碍门禁 |
代表性浅色和深色主题下的键盘焦点 | 焦点缺少共享的可见指示器,或披露关系/名称被破坏。 | audit:ChatComposerDrawer/accessibility |
| FR7 | 聚焦 DOM/类型测试和包检查 | ref、BaseProps、xstyle、className、style | 根所有权或样式接缝移动或消失。 | audit:ChatComposerDrawer/api |
| AV4 和主题边界 | 默认和自定义摘要的源代码/运行时主题检查 | 默认 Badge;调用方组合的 Astryx 内容 | 出现新的摘要目标、Badge 失去其目标,或调用方拥有的内容被重新定位为 ChatComposerDrawer 的结构。 | audit:ChatComposerDrawer/theming |
决策日志¶
DEC-1 — 一个视觉插槽保留 Badge 默认¶
引用: component:ChatComposerDrawer/DEC-1
决策人: cixzhang,2026-09-21
ChatComposerDrawer 允许一个可选的 collapsedSummary 节点作为完整视觉摘要。产品构建者自行决定某个折叠行是否需要既有的 Badge 层级,还是更简洁的局部组合;组件无法推导这种视觉层级。省略该插槽会保留现有的中性 Badge 加标签,因此现有构建者不会获得新的选项或迁移要求。
已拒绝的方案:用 {count} {label} 句子替换默认,为 Badge 添加布尔值或有限的呈现枚举,为调用方已拥有的值添加渲染回调,或暴露并行的摘要接缝。这些形态要么破坏已发布的默认值,要么将呈现机制编码化,要么招致区域设置不安全的字符串拼接,要么增加超出调用方自有区分所需的 API。
DEC-2 — 视觉组合不拥有披露语义¶
参考: component:ChatComposerDrawer/DEC-2
决策者: cixzhang,2026-09-21
自定义摘要仅用于展示。现有的 label 和语言环境目录继续为展开/折叠操作命名;count 继续启用披露;组件将摘要后代排除在焦点、激活和辅助技术导航之外。该接缝无法替代这些义务。
已拒绝:从任意摘要内容派生可访问名称,或让自定义摘要在披露内部引入另一个操作。这两种做法都会使正确的语义依赖于组件无法验证的调用方标记。
未决问题¶
此契约部分没有未决问题。
内容边界¶
本文件拥有 ChatComposerDrawer 的折叠摘要组合边界、保留 Badge 的默认行为、折叠门控与状态行为、可访问命名、兼容性以及所需证据。它不会重复完整的消费者 prop 参考、实现步骤、当前审计分数或无关组件缺口。当前权威性仅适用于上述明确需求,并不认证 ChatComposerDrawer 的每一种行为。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx