CommentPin 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | @astryxdesign/lab 导出一个 CommentPin 按钮、其 props 及其参与者数据类型。 |
| 行为 | 一个标记为单个线程渲染第一个参与者。代表多个线程的标记会将其不同的参与者渲染为一个 AvatarGroup,最多三个圆圈(两个 Avatar 加一个超过三个时的省略号溢出),并显示线程总数。只要任何一个被代表的线程有未读内容,一个强调色状态点会跟随总数,或在单个标记上跟随参与者。已解决的标记除非被选中,否则不渲染任何内容。三种尺寸遵循元素尺寸比例,且每边内边距相等。 |
| 对最终用户的影响 | 注释锚点标识的是人,而不是序列中的位置。分组锚点保持一组有界的参与者身份,同时显示他们打开的线程数量;未读活动保持为可见的小点;已解决的讨论会从内容中消失。 |
| 对构建者的影响 | 调用方按顺序提供每个不同的参与者、线程总数和未读线程数、无障碍操作标签、激活行为、可选尺寸,以及受控的 selected/dimmed/resolved/disabled 状态。 |
| 兼容性/就绪状态 | 增补性实验性 Lab API。其 API 和视觉处理在产品和视觉证据确定之前保持草稿状态。 |
| 评审检查 | 拒绝序号性身份、pin 自有的聚类或坐标、居中锚定放置、可交互的后代头像、超过三个参与者圆圈、计数旁边的数字溢出、不等内边距、总数旁边或代替总数的未读数字、未选中但仍渲染的已解决标记、生成的应用程序文案、隐藏的线程计数语义、禁用同级选择的变暗,或掩盖参与者身份的选中/已解决绘制。 |
| 治理规则 | architecture:public-component-api、architecture:component-theming-surface、architecture:interaction-modality、architecture:component-test-sufficiency 和 spec:AST-002。 |
此表是评审投影;下文正文是权威依据。
意图¶
CommentPin 是用于打开一个锚定批注线程或调用方定义的线程组的紧凑交互界面。它可在锚点处保留人类身份提示,同时仍可在内容上方或内容边距中使用。
兼容性与迁移¶
- 已发布默认值保留:
not yet released - 兼容性类别:增补性实验性 Lab API
- 受控/非受控行为:selected、dimmed、resolved 和 disabled 状态以及未读计数由调用方控制;该组件不拥有任何选中或已读状态
- 迁移决策:无;调用方在 Lab 契约被接受后替换定制的批注 pin 视觉
消费者迁移说明应放在消费者文档和发布说明中。
所有权边界¶
拥有
- 一个按钮表面、其单个/分组视觉变换、三种尺寸,以及选中、变暗、已解决、禁用、悬停、按下和聚焦可见的呈现样式。
- 通过
Avatar渲染有序参与者数据,或对于组通过AvatarGroup和不可交互的AvatarGroupOverflow渲染,且不使后代可交互。 - 当总数大于一时显示所代表的总线程数,然后只要未读数大于零就显示一个强调色的
StatusDot。 - 对于未选中的已解决标记不渲染任何内容。
- 稳定的
comment-pin主题目标和状态反射。
不拥有 / 非目标
- 线程数据、未读跟踪、授权、加载、传输、选中状态或由激活打开的面板 —— 由产品调用点拥有。
- 聚类、参与者排序、锚点标识、坐标、碰撞处理、图像变换、边距布局或连接线 —— 由产品调用点拥有。
- 头像的加载/回退、形状和身份绘制 —— 委托给
component:Avatar;溢出指示器绘制 —— 委托给component:AvatarGroup。 - 标注的序数编号。线程数是对分组标记的一种数量描述,绝不是标记的身份。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| participants | 非空有序参与者元组 | 线程或组中的每个不同身份,领头者排在首位;组最多显示三个圆 | 每个 pin | 必需的非空元组 | 产品提供;组件渲染 | 实验性 Lab | TypeScript 拒绝空元组;未类型化的空输入回退为装饰性的匿名 Avatar,并在开发环境中警告 |
| size | sm, md, lg |
在元素尺寸刻度上的 pin 高度(28、32、36px),参与者圆为 22、24 和 28px | 每个 pin;独立轴,不纳入 architecture:component-size-cascade |
sm |
产品 | 实验性 Lab | 未知的运行时值解析为 sm |
| represented thread total | 正整数 | 由标记打开的线程数;大于 1 的值选择分组呈现 | 每个标记 | 1 |
产品 | 实验性 Lab | 非有限值、小数或小于 1 的值解析为 1,并在开发环境中警告 |
| unread thread total | 不大于总数量的非负整数 | 有未读活动的所代表线程数;大于 0 时,强调圆点跟随总数显示 | 每个标记 | 0 |
产品 | 实验性 Lab | 非有限值、小数或负值被忽略;超过总数的值被上限截断;两种情况都会在开发环境中警告 |
| selected state | selected、not selected | 此 pin 是否为当前活动标注目标 | 启用和禁用 | not selected | 产品 | 实验性 Lab | 封闭布尔值 |
| dimmed state | dimmed、not dimmed | 是否另一个 pin 被选中;降低醒目度但不禁用激活 | 未选中的 pin | not dimmed | 产品 | 实验性 Lab | 封闭布尔值;当两者均为 true 时,选中绘制优先 |
| resolved state | resolved、unresolved | 所代表的线程集是否已解决;未选中的已解决标记不渲染任何内容 | 每个标记 | unresolved | 产品 | 实验性 Lab | 封闭布尔值 |
| disabled state | disabled、enabled | 标记是否可以激活 | 每个标记 | enabled | 产品 | 实验性 Lab | 封闭布尔值 |
| accessible action name | 非空的调用方编写的字符串 | 为操作命名并提供标记的工具提示,不生成应用专属文案 | 每个标记 | 必需 | 产品 | 实验性 Lab | TypeScript 要求字符串;空白内容仍为调用方错误 |
| DOM extension | 受支持的按钮 BaseProps、样式和 ref |
定位标记并连接产品拥有的交互,而无需向组件提供坐标 | 每个标记 | 无额外输入 | architecture:public-component-api |
实验性 Lab | 不受支持的原生 props 仍然不可用 |
行为与布局契约¶
草稿需求会标明其依据,以免观察到的代码被误认为有意决策。current 契约不包含未解决的行。
| ID | 候选不变量 | 依据 | 草稿审查状态 |
|---|---|---|---|
| FR1 | CommentPin MUST 渲染一个按钮,且 MUST NOT 接受、派生或修改锚点坐标、分组归属、线程选择或碰撞布局。 | 产品职责边界 | 产品方向;待负责人批准 |
| FR2 | 当仅表示一个线程时,标记 MUST 仅渲染第一个参与者的 Avatar,且 MUST NOT 使用序号作为身份标识。 | 产品方向 | 产品方向;待负责人批准 |
| FR3 | 当表示多个线程时,标记 MUST 将其不同参与者渲染为一个至多三个圆圈的 AvatarGroup——当不同参与者为三个或更少时渲染全部参与者,否则先渲染前两个,后跟一个显示省略号且不带数字的非交互式 AvatarGroupOverflow 圆圈——随后渲染精确的所表示线程总数,除非 FR10 适用。 | 产品方向 | 产品方向;待负责人批准 |
| FR4 | 参与者 Avatar 和溢出圆圈 MUST 使用其核心组件的回退与绘制,MUST 抑制工具提示和交互,并且 MUST 保持为标记按钮的装饰性后代。 | Avatar 组合与有效交互树 | 候选实现 |
| FR5 | isSelected、isDimmed、isResolved 和 isDisabled MUST 保持为独立且由调用方控制的状态。选中呈现 MUST 在图钉外部以透明边框之上的 box-shadow 环绘制一个实心 2px 强调色轮廓,且不得有强调色填充或布局偏移;MUST 保持静止状态的中等 elevation 和 Avatar 可读性;MUST 与位于更外部的共享焦点轮廓保持区分;MUST 保留可见的 forced-colors 回退;并且 MUST 优先于变暗效果。变暗呈现 MUST 降低未选中图钉的突出度,但不能禁用激活;未选中的已解决标记 MUST 不渲染任何内容,选中的已解决标记 MUST 采用选中呈现样式。 |
迁移用例与视觉方向 | 候选实现;渲染后的视觉审查待定 |
| FR6 | 标记根节点 MUST 组合 xstyle、className 和 style,转发中性的按钮 DOM/事件属性及其 ref,并保持组件自有的 type、label、选中语义、禁用状态、target 和反射状态的权威性。 |
公共组件 API 架构 | 候选实现 |
| FR7 | 悬停绘制 MUST 受悬停能力保护,触摸按压反馈 MUST 使用共享按压模型,键盘焦点 MUST 使用共享的 focus-visible 处理。 | 交互模态架构 | 候选实现 |
| FR8 | 根节点 MUST 在每种视觉状态下(LTR 和 RTL 中)都保持对话气泡轮廓:一个固定的 2px 逻辑 bottom-start 角,以及逻辑 start-start、start-end 和 end-end 的完全圆角,半径为图钉高度的一半。该 2px 角 MUST NOT 跟随主题圆角覆盖设置,且任何角都不得大到使浏览器按 CSS 圆角重叠规则缩放圆角以适应,否则会抹掉该 2px 角。 | 产品视觉方向与逻辑布局要求 | 候选实现;渲染后的视觉审查待定 |
| FR9 | 根节点的变换原点(transform origin)和文档化的绝对定位约定 MUST 使用逻辑 bottom-start 角。宿主通过将图钉向上平移其完整高度,将锚点映射到该角,且 MUST NOT 将图钉居中于该点之上。 | 产品放置方向 | 候选实现;渲染后的放置审查待定 |
| FR10 | 当 unreadCount 计算结果大于零时,标记 MUST 在会话总数之后显示强调色 StatusDot,或在单个标记中的参与者之后显示;且 MUST NOT 显示未读数字;该圆点 MUST 保持可见的 forced-colors 处理,并且 MUST 保持装饰性。 |
产品方向 | 产品方向;渲染后的视觉审查待定 |
| FR11 | size MUST 将根高度和最小宽度设置为 --size-element-sm、--size-element-md 或 --size-element-lg,并绘制 22、24 或 28px 的参与者圆圈,且反映出的尺寸 MUST 匹配。每一侧的内边距 MUST 相等,并且等于在该高度中使一个参与者圆圈居中的内缩距离;分组标记 MUST 将其第一个 AvatarGroup 环放置在起始内边距内,以便参与者圆圈从起始边缘保持该内缩距离。尾部的总数或未读点 MUST 添加 --spacing-1 的末尾内边距,以免两者挤占边缘。 |
产品视觉方向 | 产品方向;渲染视觉审查待定 |
允许的变化¶
- AV1 — 参与者身份。 名称和图片来源可变;Avatar 负责图片加载、后备首字母和匿名后备。
- AV2 — 产品放置。 调用方通过布局组合和受支持的样式输入将根元素定位在内容上方或内容边距中。绝对锚点坐标映射到逻辑上的底部起始角,而不是图钉的中心。
- AV3 — 线程分组。 调用方可以使用任何聚类策略和参与者排序,而标记的视觉转换保持不变。
- AV4 — 主题输出。 主题可以重新绘制被允许的根目标及其反映出的状态,而不改变行为或后代 Avatar 的所有权。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变化 |
|---|---|---|
| 单个 | 第一个参与者 Avatar;无可见计数;未读时其后带有强调色圆点 | 身份、已选中/变暗/已解决/已禁用状态、放置位置 |
| 分组,单一身份 | 一个 Avatar 加上线程总数 | 计数和状态 |
| 分组,两到三个 | 每个不同的参与者 Avatar 加上线程总数 | 排序的身份、计数和状态 |
| 分组,超过三个 | 前两个不同的 Avatar、一个省略号溢出圆和线程总数 | 排序的身份和状态 |
| 未读 | 总计数后的强调色圆点,或单个标记上参与者之后的强调色圆点 | 其他状态 |
| 尺寸 | 28、32 或 36px 高,带有 22、24 或 28px 圆,并且每侧具有相同的内缩距离 | 所有其他状态 |
| 已选中 | 活动的强调色处理保留 Avatar 和计数的可读性,并优先于变暗 | 主题绘制 |
| Dimmed | 降低不透明度用于标识未选中的同级元素,同时不禁用激活功能 | 也可同时应用 disabled |
| Resolved | 未选中时不渲染任何内容;选中时,采用选中样式 | 也可同时应用 disabled |
| Disabled | aria-disabled 按钮不会激活,但保留其 Tab 停靠点,因此键盘和屏幕阅读器用户可以到达它并听到其不可用;在强制颜色下,未选中的禁用 pin 会呈现 GrayText 颜色和边框 | 选中的表示保持可见,保留其 Highlight 样式 |
转换与优先级顺序¶
- ORD1 — 计数归一化。 验证
threadCount;无效值解析为 1,大于 1 的值选择分组呈现。 接下来验证unreadCount;无效值被忽略,超过解析后总数的值被截断为该总数。 - ORD2 — 参与者。 保留调用方顺序并移除重复 ID。单个标记取第一位参与者;分组标记在剩余不超过三位不同参与者时全部显示,否则显示前两位并附加一个省略号溢出圆圈。
- ORD3 — 计数显示。 分组标记显示总数;解析后的未读计数大于零时,在其后添加一个强调圆点,或在单个标记的参与者后添加。
- ORD4 — 绘制。 未选中的已解析标记不渲染任何内容。否则按顺序组合:基础表面、变暗样式、选中样式,然后是禁用样式。选中身份保持完全突出,且禁用交互始终优先。
性能与资源¶
- PR1 — 有限的结构。 渲染工作量被限制为最多三个参与者圆圈(头像加溢出指示器)、一个计数元素和一个未读圆点,无论所表示的线程数或提供的参与者数量是多少。
- PR2 — 共享交互资源。 触摸反馈使用共享的文档级按压控制器,不添加任何标记本地的监听器、观察器、定时器或状态。
当前测量值属于审计记录;本小节只包含持久约束及其验证目标。
无障碍契约¶
- AR1 — 操作。 根元素是一个原生
button type="button",由必需的label命名;isDisabled暴露aria-disabled="true"并阻止所有激活路径,同时 pin 保留其 Tab 停靠点(spec:AST-085)。 - AR2 — 选择。
isSelected通过aria-pressed、pin 外侧的一条实心 2px 强调轮廓以及强制颜色 Highlight 样式来暴露;轮廓紧贴 pin,而共享的 focus-visible 轮廓位于更外侧,因此两种状态保持可区分。 当选中的 pin 再次被激活时,宿主清除该选择。 - AR3 — 装饰性后代。 参与者头像、溢出圆圈、可见的线程总数和未读圆点对辅助技术隐藏,因为调用方编写的按钮标签拥有完整的操作名称。
- AR4 — 工具提示。 操作标签在指针悬停和键盘聚焦时以视觉方式呈现;激活仍然是主要的触摸行为。
- AR5 — 状态命名。 当 resolved、grouped 或 unread 上下文改变操作含义时,调用方在
label中包含这些上下文;组件不会生成应用特定或区域设置敏感的文案。 - AR6 — 变暗的同级元素。
isDimmed仅改变呈现方式。它 MUST NOT 设置 disabled 或 aria-disabled,因为未选中的 pin 仍然是切换选择的可访问目标。
设计关系¶
| 结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 标记表面 | 紧凑的浮动表面将该操作与底层内容区分开来 | 候选实现,待视觉审查 | 突出锚点 | FR1, FR5, FR7 |
| 代表性头像 | 人类身份仍然是主要的识别线索;分组上限为三个圆圈 | 人工选定的产品方向 | 主要内容 | FR2–FR4 |
| 溢出指示器 | 省略号圆圈以无数字形式概括前两位之外的参与者,因此它永远不会与线程数竞争 | 人工选定的产品方向 | 辅助内容 | FR3, FR4, AR3 |
| 数量(Group count) | 数量传达总量,而不成为序数标识 | 人工选择的产品方向 | 辅助内容 | FR3, AR3 |
| 未读圆点(Unread dot) | 总数之后的强调圆点标记未读活动,不显示第二个数字 | 人工选择的产品方向 | 辅助状态信号 | FR10, AR3 |
| 选中/变暗/已解决状态 | 选中态在引脚外侧绘制一条 2px 实线强调轮廓、无填充,与更外侧的焦点轮廓相区分;未选中的同级项变暗但不禁用;已解决态消失,除非被选中 | 人工选择的产品方向 | 辅助状态信号 | FR5, AR2, AR6 |
| 气泡角(Speech-bubble corner) | 逻辑上的底首(bottom-start)角固定为 2px,并在 RTL 中镜像;其余三个逻辑角保持完全圆角 | 人工选择的产品方向 | 轮廓线索 | FR8 |
| 放置原点(Placement origin) | 绝对宿主坐标映射到逻辑底首(bottom-start),绝不映射到中心 | 人工选择的产品方向 | 空间锚点 | FR9 |
| 尺寸(Sizes) | 在元素尺寸标度上有三种高度;参与者圆形、溢出和计数在每一边缘保持一个内边距 | 人工选择的产品方向 | 密度 | FR11 |
设计决策¶
| ID | 决策 | 意图或原因 | 适用范围 | 允许的变体 |
|---|---|---|---|---|
| DD1 | 参与者头像(Participant Avatars),而非序数,用于标识评论图钉。 | 随着注释量增长,序数标识会变得难以浏览和管理。 | 单个和分组标记 | 身份数据和头像回退可以变化 |
| DD2 | 分组标记最多显示三个参与者圆形——两个头像加上一个省略号溢出圆(当超过三人参与时)——并单独显示会话总数。 | 身份与数量回答不同的问题;为头像堆叠(facepile)设置上限可使分组图钉在参与人数增长时保持紧凑、易扫描;省略号确保总数是图钉上唯一的数字。 | 分组标记 | 调用方选择参与者顺序和分组策略;主题选择省略号字形 |
| DD3 | 选中态绘制为图钉外侧一条 2px 实线强调轮廓,以透明边框之上的 box-shadow 环实现;它保留图钉的中等高度(elevation),且不增加强调填充;共享的焦点轮廓位于更外侧。 | 一条 2px 轮廓呈现为选中态而非输入边框;不引起布局位移;保留头像区域;并与键盘焦点保持区别。 | 选中态以及选中加聚焦状态 | 主题强调色和高程令牌可以变化;轮廓宽度、位置和间隔不变。 |
| DD4 | 逻辑 bottom-start 角是一个固定的 2px 逻辑长属性;另外三个逻辑角为图钉高度的一半。 | 主题可能会放大 --radius-inner,因此使用字面量能让气泡尖角保持恰好 2px。半高角无需 9999px 全圆角 token 即可完全变圆,因为全圆角 token 会让浏览器缩放全部四个角以适应,从而抹掉那个小角。显式逻辑长属性可避免简写属性的级联冲突,并在 RTL 中天然镜像。 |
每个图钉及各种视觉状态 | 三个圆角遵循元素尺寸 token;2px 锚点角不变 |
| DD5 | 绝对锚点坐标映射到图钉的逻辑 bottom-start 角,而非其中心。 | 当主体向 block-start 和 inline-end 方向扩展时,气泡角保持附着在被标注的点上。 | 定位在内容之上或页边距中的图钉 | 宿主坐标和变换可以变化;锚点角不变 |
| DD6 | 当某个图钉被选中时,同级图钉使用受控变暗效果并保持可用。 | 活动目标获得视觉焦点,同时不妨碍查看者直接切换到另一个图钉。 | 具有一个活动目标的图钉组 | 宿主决定哪些同级图钉属于聚焦集合;选中的总是优先于变暗 |
| DD7 | 未读讨论串在讨论串总数之后添加一个强调色 StatusDot,或在单个标记的参与者之后添加;不显示未读数字。 |
圆点让未读活动在每个图钉上保持可见,同时不会出现与总数竞争的第二组数字。 | 单个和分组标记 | 主题强调色可以变化;圆点在总数之后的位置不变 |
| DD8 | 尺寸 sm、md 和 lg 在元素尺寸 token 上分别对应 28、32 和 36px 的高度,参与者圆环为 22、24 和 28px,每侧内边距相等;分组标记的第一个环位于起始内边距,尾部的总数或圆点增加 --spacing-1 的结束内边距。 |
宿主将图钉与其所标注内容的密度相匹配;每条边上的统一内缩量使身份标识和计数保持居中,并让单个和分组图钉具有相同的边缘节奏。 | 每个图钉 | 主题可以更改元素尺寸 token;圆环直径和统一内缩量不变 |
| DD9 | 除非被选中,否则已解决的标记不渲染任何内容。 | 已解决的讨论从内容中移除;选中的标记会保留,以便读者打开的、或从图钉弹窗中解决的讨论串保持其锚点,直到宿主清除该选择。 | 已解决的标记 | 宿主决定哪些讨论串已解决、哪一个被选中 |
主题结构¶
{
"Marker surface": {"target": "comment-pin"},
"Representative avatars": {
"delegatesTo": {"owner": "component:Avatar", "target": "avatar"}
},
"Overflow indicator": {
"delegatesTo": {
"owner": "component:AvatarGroup",
"target": "avatar-group-overflow"
}
},
"Group count": {"inherits": "comment-pin"},
"Unread dot": {
"delegatesTo": {"owner": "component:StatusDot", "target": "status-dot"}
}
}
族系与系统关系¶
architecture:public-component-api负责 DOM 可达性、prop 语义、样式组合、处理函数转发以及 React 19 refs。architecture:component-theming-surface负责单一根绘制目标、状态反射以及委托的 Avatar 所有权。architecture:interaction-modality负责悬停能力、触摸按压和 focus-visible 行为。architecture:component-test-sufficiency负责代表性状态和变异敏感回归证据。architecture:theme-tokens负责基线绘制所使用的语义化颜色、圆角、间距、字体排印、动效和阴影词汇。spec:AST-002负责公共 Lab 表面的准入和无效输入行为。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1–FR4, FR10, FR11, PR1, AR1, AR3 | CommentPin.test.tsx 以及 Storybook 尺寸矩阵 |
单个、三个以内的分组、分组溢出、未读单个与分组、无效未读、重复身份、空参与者、每种尺寸 | 多余的结构、超过三个圆圈、数字溢出、未读数字或未读圆点缺失、序号身份、计数丢失、圆圈或反射值与尺寸不一致,或交互/头像语义未通过聚焦断言 | audit:CommentPin/behavior |
| FR5, FR8, FR9, AR2, AR5, AR6 | 聚焦测试以及 Storybook 状态矩阵、位置示例和文档站展示 | 选中、选中+聚焦、变暗、强制颜色、已解析隐藏和已解析选中、禁用、LTR/RTL 轮廓与位置 | 缺少状态反射、禁用态变暗兄弟节点、合并的选中/聚焦提示,或居中/非镜像位置未通过语义/源码断言或渲染审查 | audit:CommentPin/states |
| FR6 | 聚焦的透传、ref、稳定目标和状态反射测试 | 自定义 DOM/样式输入以及每种状态 | 丢失输入/ref 或覆盖组件自身语义将无法通过聚焦断言 | audit:CommentPin/api-theming |
| FR7, PR2, AR4 | 聚焦、悬停能力源码检查、工具提示测试、构建扫描 | 指针、键盘、触摸模型 | 无防护的悬停、缺少焦点处理,或本地按压机制未通过源码/测试/构建检查 | audit:CommentPin/interaction |
| 文档与界面 | 组件文档、块元数据、根导出、Storybook 和知识检查 | 公开示例与组件发现 | 缺失或过时的可发现性、语法、边界或关系会导致仓库检查失败 | audit:CommentPin/docs |
决策日志¶
无。该记录仍处于草稿状态;其候选需求和本地设计意图等待组件负责人与视觉审查。
未决问题¶
- OQ1 — 选中的状态处理方式能否在代表性图像和所有主题中保持足够的对比度,同时在图像内容和页面边距上仍然清晰可辨? (
human-design)
内容边界¶
本文件不重复消费者 prop 表格/示例、当前审计结果、实现步骤、产品分组算法、坐标系或家族/系统规则。它链接到这些内容的负责人。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx