AvatarStatusDot 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 用于 Avatar 的 status 插槽的状态点,包含 variant(默认 success)、可选 label 和可选 icon。 |
| 行为 | 该点根据所属 Avatar 以三档尺寸自我调整大小,将每个内置 variant 与不同的形状配对,并将其 label 报告给 Avatar。 |
| 最终用户影响 | 屏幕阅读器用户会在 avatar 名称中听到状态;有视力的用户除了颜色之外,还能通过形状区分不同状态。 |
| 构建者影响 | 无;该记录描述的是已发布行为。 |
| 兼容性/就绪状态 | 已发布行为记录为当前状态;无 API、默认值或输出变更。一处实现差距列于“当前状态影响”下。 |
| 审查检查 | 拒绝仅靠颜色区分的内置 variant、暴露的图形或图标,或停止传递给所属 Avatar 的 label。 |
| 治理规则 | architecture:component-theming-surface/INV2,INV6,INV14;architecture:public-component-api/INV5,INV6,INV8;WCAG 2.2 1.4.1。 |
此表格是审查投影;以下正文具有权威性。
意图¶
AvatarStatusDot 渲染通过 Avatar 的 status 插槽组合而成的紧凑状态指示器。它负责该点的大小档位、内置的非颜色标记,以及将其 label 报告到所属 Avatar 的可访问名称中。
兼容性与迁移¶
- 已发布的默认值被保留:是
- 兼容性类别:记录已发布行为;无公共 prop、默认值、DOM、目标或样式输出变更
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明应归属于消费者文档和发布说明。
当前状态影响¶
- 无回退的扩展 variant(FR6)。
AvatarStatusDotVariantMap允许主题新增名称,但没有内置规则的新名称会渲染为无填充、墨色或图形的点几何及data-variant。调用方传入带style颜色的icon可以覆盖中档和大档,但小档会丢弃图标,且没有任何东西提供与主题无关的安全基线。architecture:component-theming-surfaceINV14 要求可扩展的视觉轴具有安全的主题无关基线。
所有权边界¶
拥有
- 已绘制的状态点根元素及其
avatar-status-dot目标。 - 内置的填充、环形和减号视觉分支,以及
avatar-status-dot-glyph目标。 - 从 Avatar 已解析的数值尺寸解析大小档位。
- 将其可选状态 label 报告到 Avatar 的可访问名称中。
不拥有 / 非目标
- Avatar 身份、图像回退、形状、状态放置或交互行为——由
component:Avatar拥有。 - 调用方提供的图标内容的含义或图形。
公共概念¶
消费者语法保留在 AvatarStatusDot.doc.mjs 中。
| 概念 | 封闭值或状态 | 含义 | 按 variant/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| Status variant | 内置 success、neutral、error;已发布映射也允许扩展名称 |
选择底板颜色和内置的非颜色标记。 | 所有尺寸档位;LTR 和 RTL。 | success |
component:AvatarStatusDot |
稳定 | 扩展名称会反映为 data-variant,并保持安全的主题无关基线(FR6);目前尚无基线,即 FR6 差距。 |
| Status label | 字符串或缺失 | 命名独立的状态点,并报告到所属 Avatar 名称中。 | 每个 variant 和尺寸。 | 缺失 | 调用方提供含义;组件暴露并报告它 | 稳定 | 空或缺失的 label 不会在该点上发出 role 或可访问名称,也不会报告状态名称。 |
| Custom icon | 可渲染的 React 内容或缺失 | 在尺寸档位允许时替换内置图形。 | 中档和大档;小档隐藏。 | 缺失 | 调用方拥有图形;组件拥有放置和抑制规则 | 稳定 | 布尔值和空字符串会被忽略;渲染无 DOM 的组件仍会抑制内置图形。 |
| DOM extension | 受支持的 BaseProps 输入和 ref | 扩展根元素并合并消费者样式。 | 每个渲染分支。 | 无额外输入。 | architecture:public-component-api |
稳定 | BaseProps 省略项仍不受支持。 |
行为和布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 36px 及以下的 Avatar 尺寸对应一个带 1px 边框、无自定义图标的 10px 圆点;40–72px 对应 20px 圆点、2px 边框和 12px 图标;96px 及以上对应 32px 圆点、4px 边框和 18px 图标。边框使用表面颜色。在相同层(spec:AST-038 FR7, FR8)中,Avatar 之外的圆点采用 36px 档。 |
当前源码、测试和 stories |
| FR2 | success 绘制一个填充的 --color-success 底板,内部无字形;neutral 绘制一个表面底板,并带有次要文本颜色的环;error 绘制一个 --color-error 底板,并在 --color-on-error 上带有一条减号条;success 将 --color-on-success 作为其墨色。字形以 currentColor 按档位以 1、1.5 或 2px 描边;减号条占据内部区域的 75%,带有圆头端点。底板是强状态填充,其墨色是对应的内容角色(architecture:theme-tokens INV11)。 |
当前源码、测试和消费者文档 |
| FR3 | 在中档和大档位,可渲染的 icon 内容会替换内置字形,并居中放置在一个对辅助技术隐藏的包装器中,该包装器的大小与对应档位的图标尺寸一致。在小档位,图标被省略,内置字形保留。布尔值和空字符串不可渲染。 |
当前源码和测试 |
| FR4 | 非空 label 会为圆点添加 role="img" 和 aria-label。圆点会在绘制前、在任意包装器深度下,将同一标签报告给所属 Avatar,并在卸载时撤回该标签。 |
当前源码和 Avatar 集成测试 |
| FR5 | 根元素携带带有 variant 的 avatar-status-dot;环形和减号 SVG 携带带有 shape 的 avatar-status-dot-glyph。受支持的消费者属性和 ref 会传递到根元素;圆点自身的 role、名称和样式在调用方属性之后应用,且 xstyle、className 和 style 按该顺序合并。 |
当前源码、文档和目标测试 |
| FR6 | 已发布的 AvatarStatusDotVariantMap 允许扩充名称,且可扩展的视觉轴具有安全的、与主题无关的基线(architecture:component-theming-surface INV14)。对于不匹配的名称,根元素的几何形状和反射的 data-variant 保留,而内置填充、墨色和字形缺失;在中档和大档位,带有 style 颜色的调用方 icon 提供颜色和标记,在小档位则不渲染图标。实现缺口:没有与主题无关的基线来绘制不匹配的名称(当前状态影响)。 |
当前源码、文档、聚焦测试和 architecture:component-theming-surface/INV14 |
允许的变化¶
- AV1 — 身份与含义。 状态标签和调用方图标图案可以变化。
- AV2 — 主题输出。 目标与反射轴可以通过公开的主题系统变化,而无需转移目标所有权。
- AV3 — 消费者样式。 根节点上受支持的 BaseProps 输入可以变化,而组件自有的尺寸和上报行为保持不变。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变化 |
|---|---|---|
| 内置变体 | 填充、环形和减号分支以及反射的 variant 保持不变。 |
标签、Avatar 内容、尺寸、主题和方向可以变化。 |
| 小尺寸档位 | Dot 和内置形状保持不变;自定义图标被省略。 | 内置变体和标签可以变化。 |
| 中尺寸和大尺寸档位 | 档位尺寸生效;可渲染的自定义图标取代字形。 | 图标图案、变体、标签和主题可以变化。 |
| 带标签 | Dot 暴露其标签并将其上报给 Avatar。 | 调用方编写的标签可以变化。 |
| 无标签 | Dot 没有角色或名称,并且不上报状态标签。 | 视觉变体和图标仍可渲染。 |
| 增强变体 | 根节点几何形状和反射的 data-variant 会渲染;内置填充、墨色和字形不存在(FR6 缺口)。 |
主题可以绘制新增的名称。 |
| RTL | Dot 内容方向中性;Avatar 负责逻辑角位置的摆放。 | 主题、变体、尺寸、标签和图标可以变化。 |
转换与优先级顺序¶
- ORD1 — 解析尺寸。 取所属 Avatar 的解析后尺寸(同一层中位于 Avatar 之外时为 36px),然后选择离散的尺寸档位和尺寸。
- ORD2 — 解析标记。 当档位允许时,可渲染的图标优先;否则在存在内置变体字形时选择该字形。
- ORD3 — 解析根节点。 调用方 props → 角色和名称 → 组件目标和样式 →
xstyle→className→style。
性能与资源¶
- PR1 — 免重渲染的上报。 上报或撤销标签不会导致 Dot 或 Avatar 的额外渲染,也不会遗留任何监听器、观察器或计时器。
无障碍契约¶
- AR1 — 无障碍名称。 非空的
label为独立的 Dot 命名,并被合成到所属 Avatar 的名称中。 - AR2 — 装饰性视觉标记。 内置 SVG 和自定义图标包装器对辅助技术隐藏,因为根节点或 Avatar 名称承载状态。
- AR3 — 内置非颜色线索。 三种内置变体除语义颜色外,还使用填充、环形和减号拓扑(WCAG 2.2 1.4.1)。在中尺寸和大尺寸档位,调用方图标会取代该标记,因此非颜色区分随后取决于调用方是否为每种状态使用不同图标。
设计关系¶
| 解剖结构或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Status-dot 根节点 | Avatar 边缘上紧凑的语义状态标牌。 | 当前源代码和消费者文档;当前没有组件设计记录 | 辅助性指示器 | FR1, FR2, FR5 |
| 内置字形 | 环形或减号为中性/错误状态补充颜色。 | WCAG 2.2 SC 1.4.1 以及当前已交付的表示形式 | 有意义的非文本线索 | FR2, AR3 |
| 自定义图标 | 在空间允许的情况下,调用方图案取代内置标记。 | 调用方拥有图案;当前源代码拥有放置位置 | 条件性有意义线索 | FR3, AR2, AR3 |
家族与系统关系¶
architecture:component-theming-surface负责绘制目标限定、反射轴,以及可扩展视觉轴所需的可靠且与主题无关的回退;FR6 记录与之相关的缺口。architecture:component-style-authoring负责 StyleX 降级,并允许此处使用的组件自有的非字形 SVG 形状。architecture:public-component-api负责已发布的子路径、BaseProps 透传、样式组合、ref 可达性和兼容性边界。architecture:theme-tokens负责语义颜色和圆角词汇。spec:AST-002负责 API 准入,并要求未来的公共行为或默认值变更指明当前权威。
Verification map¶
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1–FR3, AR2, AR3 | AvatarStatusDot.test.tsx 和 AvatarStatusDot.stories.tsx 在浏览器中 |
三种尺寸档位、三种内置状态、自定义图标存在/不存在 | 尺寸档位、标记选择、隐藏图标或内置形状的偏离会使针对性断言或渲染夹具失败。 | audit:AvatarStatusDot/behavior |
| FR4, AR1 | Avatar.test.tsx 状态名称套件和 AvatarStatusDot.test.tsx |
直接/包裹/变化/移除的标签;有标签和无标签的圆点 | 丢失独立或组合的状态名称、提交阶段更新或清理,会使角色/名称断言失败。 | audit:AvatarStatusDot/accessibility |
| FR5 | themingTargets.test.ts 和 extensibleAxes.test.ts |
内置和增强变体、字形环/减号 | 缺少目标元数据或轴接线会导致结构检查失败。缺口:没有测试渲染圆点来检查消费者 props、ref 和样式输入是否到达根节点。 | audit:AvatarStatusDot/theming |
| FR6 | AvatarStatusDot.test.tsx 增强变体测试 |
没有匹配内置规则的新增名称 | 出现未匹配名称的字形会失败。缺口:填充出现以及调用方 icon 路径没有自动化检查。 |
audit:AvatarStatusDot/api |
| RTL relation | AvatarStatusDot.stories.tsx 在浏览器中以两个方向运行 |
所有尺寸档位下的内置状态 | 任何新的方向性字形、物理定位或未匹配的变换都会在渲染夹具中显现。 | audit:AvatarStatusDot/i18n-rtl |
| Record structure | scripts/check-knowledge.mjs |
本记录 | 缺少所需结构或关系会导致仓库验证失败。 | audit:AvatarStatusDot/docs |
| PR1 | Avatar.test.tsx 无额外渲染测试 |
包裹的状态标签 | 额外的渲染或报告循环会导致失败。 | audit:AvatarStatusDot/behavior |
| AR1, AR2 | 可访问性树证据(spec:AST-009 FR3) |
有标签和无标签的独立圆点 | 缺口:没有可访问性树检查证明独立图像角色和名称或隐藏标记;单元测试查询的是 DOM。 | audit:AvatarStatusDot/accessibility |
Decision log¶
无记录。该记录描述的是已发布的行为。
Open questions¶
无。
Content boundary¶
本文件不重复消费者示例、当前审计分数、截图、运行清单、资格数据或共享 API/主题规则。它链接到这些内容的所属方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx