跳转至

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-api INV23)。
  • 消息呈现、分组或发送者语义——由 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,即决定它所包裹的 md Button 尺寸的同一个 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 和 undefined children 是否选择空状态。
  • 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