ChatLayout 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | children、composer、emptyState、scrollButton、scrollRef、density,外加布局根节点上的 BaseProps<HTMLDivElement> 和 ref。 |
| 行为 | 根节点为 flex 列;消息区域可增长且永不收缩;当根节点滚动时 dock 为 sticky,当 scrollRef 指定外部滚动容器时为 fixed。 |
| 最终用户影响 | 聊天记录在始终可达的 composer 下方滚动,自动跟随流式输出,并在读者离开底部时提供滚动到底部的操作提示。 |
| 构建者影响 | 无。 |
| 兼容性/就绪状态 | 记录已发布行为;无公共变更。两个 owner 问题仍未解决。 |
| 审查检查 | 拒绝任何声称未发布行为、承诺本组件不提供的默认值、或在没有 owner 决策的情况下解决 OQ1 或 OQ2 的行。 |
| 治理规则 | architecture:public-component-api/INV1, INV5–INV6, INV8;architecture:component-style-authoring/INV1–INV3, INV5;architecture:theme-tokens/INV3;spec:AST-025/FR12(未采纳)。 |
此表为审查投影;以下正文为准。
意图¶
ChatLayout 是聊天界面的结构外壳。它只负责一件事:将可滚动的聊天记录放在停靠的 composer 上方,使短对话不会溢出,长对话可以滚动,并且 composer 始终停留在实际滚动元素的底部边缘。滚动机制位于 useChatStreamScroll 和 useChatNewMessages 中;本组件将它们连接到自己所拥有的 DOM,并通过 ChatLayoutContext 发布生成的 refs。
消费者用法、属性语法和示例属于 ChatLayout.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;无公共变更
- 受控/非受控行为:不适用;该组件不持有任何可控值。
- 迁移决策:无。
所有权边界¶
拥有
- 布局根节点:flex 列、相对定位、
container-type: inline-size,以及带有density轴的chat-layout主题目标。 - 哪个元素滚动:根节点本身,或
scrollRef指定的元素。 - dock 定位——自滚动模式下为
sticky,外部滚动模式下为fixed——以及绘制在它背后的毛玻璃层。 - 密度几何:dock 内边距、消息列最大宽度和内联内边距,以及模糊层的高度和遮罩。
- 空状态替换及其居中框。
- 默认的滚动到底部操作提示及其收到的可见性信号。
- 通过
ChatLayoutContext发布scrollContainerRef和contentRef。
不拥有 / 非目标
- 滚动测量、弹簧动画、锁定行为或新消息检测——由
useChatStreamScroll和useChatNewMessages拥有。 - 在跟随期间关闭浏览器的滚动锚定——由
useChatStreamScroll拥有,它只通过 Core 的滚动锚定所有者模块(privateAttributes/scrollAnchoring.stylex.ts)写入该规则,该模块是该规则的唯一所有者(architecture:public-component-apiINV23)。 - 消息呈现、分组或发送者语义——由
component:ChatMessageList和component:ChatMessage拥有。 - composer 的行为、尺寸或状态——由
component:ChatComposer拥有。 - 滚动到底部控件自身的呈现——由
component:ChatLayoutScrollButton拥有。 - 页面外壳、导航和地标分配——由调用方负责。
spec:AST-025定义的共享有效轴滚动能力。本组件先于它存在,且尚未采纳;见 OQ1。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|
children |
任意 ReactNode |
放置在消息区域中的聊天记录内容。 | 必填 | 调用方 | 稳定 | 不适用 — 必填 |
composer |
任意 ReactNode |
放置在 dock 内部的内容。 | 必填 | 调用方 | 稳定 | 不适用 — 必填 |
emptyState |
ReactNode;省略 |
当 children 为空时,居中渲染以替代 children。 |
省略 | 调用方 | 稳定 | 省略时原样渲染 children |
scrollButton |
undefined;null;任意 ReactNode |
undefined 选择已接线的默认项,null 不渲染任何内容,节点则替换默认项。 |
undefined |
组件/调用方 | 稳定 | 任意节点按给定内容渲染 |
scrollRef |
RefObject<HTMLElement \| null>;省略 |
指定滚动元素;省略时使根元素滚动。 | 省略 | 调用方 | 稳定 | current 为 null 时滚动保持不激活 |
density |
compact;balanced;spacious |
选择停靠栏内边距、消息列宽度和模糊层尺寸。 | balanced |
组件 | 稳定 | 封闭联合;被类型系统拒绝 |
| 根表面 | ref;DOM/data/ARIA props;className/style/xstyle |
扩展布局根元素。 | 省略 | 公共组件 API | 稳定 | 不适用 |
density 是一个封闭联合。它是 chat-layout 目标的一个已记录的 visualProps 轴,并且不可通过主题扩展:没有任何不可用的自定义值具有安全的、与主题无关的基线,因此它在 architecture:component-theming-surface/INV14 下保持封闭。
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | 根元素 MUST 是一个 flex 列,因此文档流中粘性停靠栏的高度计入根元素的高度,而不是叠加在根元素之上。 | 当前源码和测试 |
| FR2 | 消息区域 MUST 扩展到剩余空间,并且 MUST NOT 收缩到低于其内容高度,因此短对话记录恰好填满根元素,长对话记录则使其溢出。 | 当前源码和测试 |
| FR3 | 在没有 scrollRef 时,根元素 MUST 作为滚动容器,停靠栏 MUST 为 position: sticky。 |
当前源码和测试 |
| FR4 | 在提供 scrollRef 时,根元素 MUST NOT 成为滚动容器,停靠栏 MUST 为 position: fixed。消息区域的末尾内边距 MUST 容纳停靠栏的高度,以便在滚动结束时最新消息位于停靠栏上方。 |
当前源码和测试 |
| FR5 | emptyState MUST 在 children 为 null、undefined、false 或空数组时恰好替换 children,并且 MUST NOT 替换任何其他子内容。 |
当前源码和测试 |
| FR6 | scrollButton MUST 区分三种情况:省略时选择内置默认值,null 时不渲染任何内容,传入节点时替换默认值。 |
当前源码和测试 |
| FR7 | density MUST 以 chat-layout 目标的 data-density 形式反映在根元素上,并且 MUST 同时选择停靠栏、消息区域、停靠栏内部和模糊层的几何尺寸。 |
当前源码、测试和文档 |
| FR8 | 布局 MUST 通过 ChatLayoutContext 发布其滚动容器和消息内容 refs,以便消息列表可以注册被观察的内容框。 |
当前源码 |
| FR9 | 被接受的 ref、DOM/data/ARIA props、className、style 和 xstyle MUST 到达布局根元素并在其上组合。 |
architecture:public-component-api/INV5–INV6, INV8 |
允许的变化¶
- AV1 — 滚动所有权。 调用方在根元素所有和外部所有的滚动之间进行选择;停靠栏的定位策略跟随该选择。
- AV2 — 滚动提示(affordance)。 调用方可以保留内置默认值、移除它,或用任意节点替换。
- AV3 — 对话记录内容。 消息区域允许任何内容;
ChatMessageList是一种约定,而非要求。 - AV4 — 密度几何。 解析后的间距和宽度遵循当前主题的间距刻度;只有三个档位之间的关系是固定的。
代表性状态¶
| 状态 | 必需不变式 | 允许的变化 |
|---|---|---|
| 自身滚动,短对话记录 | 根元素在不溢出的情况下填满;停靠栏在块末尾保持粘性 | 空状态可以占据消息区域 |
| 自滚动、内容溢出的对话记录 | 根元素滚动;消息区域保持内容高度 | 滚动提示变为可见 |
外部 scrollRef |
根元素不滚动;dock 固定到视口的 block 末端;最新消息停留在其上方、滚动末端 | 指定的元素可以是 document 元素 |
子元素为空且带有 emptyState |
居中的空状态替代对话记录 | 任何节点都可以作为空状态 |
scrollButton={null} |
不渲染任何滚动提示 | 自动滚动行为保持不变 |
性能与资源¶
- PR1 — 组件中不进行布局测量。 密度通过 prop 传入。ChatLayout
MUST NOT 为 CSS 容器/弹性模型已经解决的呈现需求,自行添加
ResizeObserver、 媒体查询或动画帧(architecture:component-style-authoring/INV2)。固定 dock 脱离文档流,因此 flex 布局无法预留其高度。该高度通过 PR2 的池化 observer 到达消息区域。其首次调用不携带尺寸,因此挂载时会读取一次 dock 的高度。 - PR2 — 仅共享观察。 内容尺寸观察通过
useChatNewMessages使用的池化observeResize工具到达浏览器,绝不使用实例级 observer。
可访问性契约¶
- AR1 — 已接入的默认滚动提示在视觉隐藏时 MUST NOT 成为可聚焦元素。 隐藏的 pill
不绘制任何内容,因此焦点落在其上时不会有可见指示(WCAG 2.2 SC 2.4.7, Level AA)。
opacity和pointer-events不会将元素从顺序焦点导航中移除。 - AR2 — 滚动提示在可见时 MUST 保持键盘可达且可操作,其可访问名称由目录提供, 并在新消息到达时替换为新消息标签。
- AR3 — 所有用户可见和面向 AT 的字符串 MUST 来自目录:
@astryx.chatLayout.newMessages和@astryx.chatLayoutScrollButton.scrollToBottom。 - AR4 — 布局 MUST NOT 为调用者的区域分配 landmark 角色或可访问名称。 区域语义仍由调用者拥有。
- 自滚动根元素自身不携带
tabIndex、角色或可访问名称;进入滚动内容的键盘路径来自children提供的任何内容。应由哪一层拥有该保证尚未解决;见 OQ1。
设计关系¶
- dock 使用
backdrop-filter模糊和 block-start 遮罩绘制,使对话记录在 composer 后面淡出, 而不是以硬边缘结束。模糊高度和遮罩距离随density分档变化。 - 滚动提示是一个 pill,其高度跟踪
--size-element-md,即决定它所包裹的mdButton 尺寸的同一个 token,因此在重新调整元素刻度的主题下,pill 的overflow: hidden无法裁剪该 Button(architecture:theme-tokens/INV3)。 - 间距、圆角、阴影、时长和缓动全部从可移植的语义 token 解析。没有语义角色的组件局部几何形状—— 消息列和 dock 内部上限、模糊高度以及空状态最小高度——仍是命名的组件设计决策。
- 该组件不声明任何可移植 token,也不声明任何公开的自定义属性。
主题可及性¶
ChatLayout 的五个 anatomy 部件的处置。该记录不携带 anatomy-theming:v1 块;
该块在迁移期间是可选的,另见 OQ2。
| Anatomy 部件 | 处置 |
|---|---|
| 消息区域 | none — 可及性缺口:内部元素没有 themeProps 调用。chat-layout 位于滚动根元素上,因此主题无法触及对话记录列自身的 padding 或宽度上限。 |
| 毛玻璃 dock | none — 未定:dock、其内部列和模糊层绘制标志性表面,且没有目标;见 OQ2。 |
| 滚动到底部按钮 | delegatesTo chat-layout-scroll-button 目标,其在当前清单中的规范所有者是 component:Chat。 |
| Composer | delegatesTo chat-composer 目标,其在当前清单中的规范所有者是 component:Chat。 |
| 空状态 | none — 有意的:空状态框只居中调用者内容,这属于布局管道。 |
chat-layout 目标本身声明在 Chat 家族文档(Chat.doc.mjs)上,而不是
ChatLayout.doc.mjs 上。
家族与系统关系¶
- 不存在
family:chat记录。Chat 组件共享Chat.doc.mjs家族文档及其主题目标清单, 这不是知识记录家族契约。 component:ChatLayoutScrollButton拥有滚动提示的呈现、标签和焦点行为。ChatLayout 仅拥有其何时可见这一决定。component:ChatMessageList使用ChatLayoutContext.contentRef。spec:AST-025拥有共享的有效轴滚动能力。ChatLayout 目前并未采用它:它在自滚动模式下 无条件声明overflow-y: auto,而非解析有效轴,并且它没有为视口本身分配键盘访问权限。 FR12 接受现有的可聚焦后代作为键盘路径;未解决的所有权问题见 OQ1。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, FR2 | ChatLayout.test.tsx 自滚动布局契约 |
自滚动、短会话记录和长会话记录 | 恢复消息区域上的 min-height: 100% 会重新引入 dock 的高度,并导致根元素溢出 |
audit:ChatLayout/§4 |
| FR3, FR4 | ChatLayout.test.tsx 中 dock 的定位以及固定 dock 所需的空间 |
无 scrollRef;外部 scrollRef;持续增长的 composer |
将 sticky 与 fixed 互换会使 dock 脱离实际发生滚动的元素;去掉该空间会让最新消息被固定 dock 遮挡 | audit:ChatLayout/§4 |
| FR5 | ChatLayout.test.tsx 空状态用例;useChatNewMessages.test.tsx 条件列表用例 |
空数组;有内容的 children | 将有内容的 children 当作空会隐藏会话记录 | audit:ChatLayout/§4 |
| FR6 | ChatLayout.test.tsx 滚动按钮用例 |
自定义节点 | 用默认节点代替提供的节点渲染会导致失败 | audit:ChatLayout/§4 |
| FR7 | ChatLayout.test.tsx 密度用例;themingTargets.test.ts |
紧凑;均衡;宽松 | 移除被反射的属性会使主题化轴无法被选择 | audit:ChatLayout/§2 |
| FR8 | ChatLayout.test.tsx “首次填充滚动定位”用例;useChatNewMessages.test.tsx 条件列表用例 |
首次填充;流式增长 | 丢失已发布的 refs 会使自动滚动无法观察内容增长 | audit:ChatLayout/§7 |
| AR1, AR2 | ChatLayoutScrollButton.test.tsx 和 ChatLayout.test.tsx 的 Tab 顺序用例;在真实 Chromium 中的 ChatLayoutScrollButton.a11y.chromium.spec.ts |
静止时隐藏;可见;激活后重新隐藏 | 恢复为仅使用 opacity 隐藏会把不可见的控件重新放回 Tab 顺序中 |
audit:ChatLayout/§1 |
从源码阅读得出,暂无聚焦测试:
- FR3、FR4:根元素是否为滚动容器。
- FR5:
null和undefinedchildren 是否选择空状态。 - FR6:
null不渲染任何内容,省略scrollButton时选择已接线的默认按钮,而默认按钮不会在提供了自定义节点时一同渲染。 - FR8:对外发布的滚动容器。
- FR7:每种密度下的 dock、message-area、dock-inner 和模糊层的几何尺寸。
- FR9:根元素上的
ref、DOM props、className、style和xstyle。 - AR2:新消息标签是否取代目录名称。
- AR3:目录字符串;AR4:调用方区域上没有 landmark 或名称。
- PR1–PR2:组件自身不进行布局测量,并使用池化观察器。
决策日志¶
未记录任何组件本地决策。
开放问题¶
- OQ1 — 哪一层拥有通往已滚动内容的键盘路径,ChatLayout 是否应保证这一点?(
human-api)在自滚动模式下,根元素就是滚动容器,并且自身不携带tabIndex、role 或可访问名称。文档中的子组件component:ChatMessageList带有role="log"和tabIndex={0},spec:AST-025/FR12接受这样一个已有的可聚焦后代,而不是命名视口。children的类型是ReactNode,因此对于未提供可聚焦后代的组合是否也受覆盖,以及应由哪一层拥有这一保证,仍然悬而未决。本记录陈述了该安排,并断言无缺陷。 - OQ2 — 磨砂 dock 是否应可主题化?(
human-api)dock、其内部列以及模糊层构成了组件标志性的外观,而当前没有任何主题目标能够触及它们。
内容边界¶
本文件不重复 ChatLayout.doc.mjs 的属性表或示例、审计的评分与证据,也不重复由各自组件和 hooks 所拥有的滚动、消息和 composer 契约。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx