Divider 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | orientation、label、主题可扩展的 variant、isFullBleed、BaseProps<HTMLDivElement> 以及根 ref。 |
| 行为 | 无标签时,分隔符渲染一条线条;存在可渲染标签时,渲染两条围绕标签的线条;全出血消耗继承的逻辑容器内边距。 |
| 终端用户影响 | 人们可以在水平、垂直、带标签、全出血、窄幅和 RTL 组合中感知到命名分隔符。 |
| 构建者影响 | 无;该记录描述已发布行为。数字零是有效标签;布尔值和空字符串会留下一条连续的无名线条。 |
| 兼容性/就绪状态 | 已发布行为记录为当前状态;无 API、默认值或输出变更。两个实现差距列于「当前状态影响」下。 |
| 评审检查 | 拒绝数字标签缺失、物理边缘出血、根输入被丢弃、或目标或轴与渲染分隔符不一致的情况。 |
| 治理规则 | architecture:public-component-api/INV1,INV5–INV9;architecture:component-theming-surface/INV3–INV7,INV14;architecture:container-padding/INV1,INV3,INV7–INV10;通过 spec:AST-020/FR1 引用 WCAG 2.2 SC 1.3.1 与 4.1.2。 |
此表是评审投影;以下正文具有权威性。
意图¶
Divider 在调用方所有的内容区域之间提供程序化且可视的分隔。它拥有方向、线宽、可选标签的放置与命名、逻辑全出血几何,以及聚合的 divider 主题目标。周围区域的含义由调用方拥有。
消费者语法与示例属于 Divider.doc.mjs。
兼容性与迁移¶
- 已发布默认值保持不变:是——水平、subtle(细微)、无标签且非全出血。
- 兼容性类别:记录已发布行为;无公共 prop、默认值、DOM 或样式输出变更。React 会渲染的 ReactNode 值(包括数字零)保留在标签包装器内;被跳过的标量标签会留下一条连续的无名线条。
- 受控/非受控行为:不适用。
- 迁移决策:无。
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 主题添加的变体缺少线条绘制(FR3)。
DividerVariantMap允许主题添加的值,但未匹配的值会使内部线条未绘制,因此线条可能消失。architecture:component-theming-surfaceINV14 要求可扩展的视觉轴具有安全的、不依赖主题的基线;OQ2 持有修复方向。 - 调用方的
role和aria-orientation被替换(FR6)。 Divider 在调用方 props 之后设置role="separator"和aria-orientation,因此调用方的显式值永远不会到达根元素,而architecture:public-component-apiINV5 允许调用方的显式输入到达该元素。
所有权边界¶
拥有
- 一个语义分隔根元素及其公共 ref、DOM、数据、ARIA、类、样式、事件和
xstyle组合。 - 水平和垂直的线条几何。
- 可选标签放置及分隔符命名关联。
- 内置的 subtle(细微)和 strong(粗重)线宽。
- 反射的自定义变体状态,包括「当前状态影响」中记录的缺失线条绘制回退。
- 对继承容器内边距的逻辑全出血消耗。
- 聚合的
divider目标,带反射的方向和变体轴。
不拥有 / 非目标
- 周围内容区域的含义或标题结构——由产品调用点拥有。
- 容器内边距的发布——由
architecture:container-padding拥有。 - 为 Rule 或 Label 提供单独的公共目标——不存在;OQ1 持有该问题。
- 由主题编写的自定义变体绘制,以及应拥有它的公共部分——OQ2 持有该问题。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 方向(Orientation) | horizontal; vertical |
选择分隔符轴、线条几何和 aria-orientation。 |
每个分隔符 | horizontal |
组件 | 稳定 | 封闭联合;被类型系统拒绝 |
| 标签 | 可渲染的 ReactNode;省略/跳过的标量 | 在两个线条之间插入一个标签,并为分隔符命名,除非显式的 ARIA 命名优先。 | 所有方向和变体 | 省略 | 调用方/组件 | 稳定 | null、布尔值和空字符串不渲染标签;数字零仍然可见 |
| 变体 | subtle;strong;主题添加的视觉值 |
选择线条绘制方式,并在目标上反映所请求的值。 | 所有方向和标签状态 | subtle |
组件/主题 | 稳定的内置项;主题可扩展的轴 | 未匹配的自定义值会使线条保持未绘制状态(FR3) |
| 全出血 | false;true | 在分隔轴线上消耗继承的逻辑容器内边距。 | 所有方向 | false | 组件/容器协议 | 稳定 | 缺失的变量解析为零 |
| 根表面 | ref;DOM/数据/ARIA;class/style/xstyle/事件 | 扩展语义分隔符的根节点。 | 每个分隔符 | 省略 | 公共组件 API | 稳定 | 接受的输入会组合;目前调用方的 role 或 aria-orientation 会被替换(FR6 差距) |
行为和布局约定¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 分隔符在没有可渲染标签时渲染一条线条,在存在标签时渲染两条线条并将标签置于两者之间。数字零是可渲染的标签;null、布尔值和空字符串不渲染标签。水平分隔符是全宽 flex 行,垂直分隔符是全高行内 flex 列;标签在分隔轴线上使用次要文本样式的辅助字体,并带有 --spacing-3 内边距。 |
已发布的 ReactNode API;当前源代码、文档和测试 |
| FR2 | 默认情况下,根节点暴露 role="separator" 和所选的 aria-orientation;调用方显式提供的 role 或 aria-orientation 优先,并按原样使用,即使与 orientation 相矛盾也是如此(FR6)。除非调用方提供了 aria-label 或 aria-labelledby,否则可渲染的标签会通过 aria-labelledby 为其命名。 |
WCAG 2.2 SC 1.3.1 和 4.1.2;当前源代码和测试 |
| FR3 | subtle 使用 --color-border 绘制线条,strong 使用 --color-border-emphasized 绘制,线宽为 --border-width。导出的映射接受主题添加的值,根节点会反映这些值,并且可扩展的视觉轴线具有安全且与主题无关的基线(architecture:component-theming-surface INV14)。实现差距:未匹配的值会使内部线条保持未绘制状态(当前状态影响)。 |
architecture:component-theming-surface/INV4,INV6,INV14;当前源代码 |
| FR4 | 全出血会消耗水平分隔符继承的逻辑内联内边距和垂直分隔符的逻辑块内边距,使盒子向外扩展相同的量;缺失的内边距解析为零。 | architecture:container-padding/INV1,INV3,INV7–INV10;当前源代码 |
| FR5 | 根节点携带 divider 目标,并反映 orientation 和所请求的 variant。线条和标签不携带公共目标。反射的 data-orientation 和 data-variant 是组件拥有的主题状态,并会替换调用方的值。 |
architecture:component-theming-surface/INV3–INV6;当前源代码和文档 |
| FR6 | ref、DOM、数据、ARIA、class、style、事件和 xstyle 输入会到达或组合在分隔符根节点上,并且调用方显式的 role 或 aria-orientation 也会到达那里(architecture:public-component-api INV5)。实现差距:组件在调用方属性之后设置 role 和 aria-orientation,因此调用方的值会被替换(当前状态影响)。 |
architecture:public-component-api/INV5–INV8;当前源代码和测试 |
允许的变化¶
- AV1 — 标签内容。 任何由调用方拥有且 React 可渲染的 ReactNode 都可以填充标签包装器。
- AV2 — 主题绘制。 活动主题可以重新样式化聚合目标及其变体轴。OQ2 拥有未解决的内部规则绘制和回退边界。
- AV3 — 容器几何。 通栏遵循继承的逐边内边距,包括不对称和零值。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 未标记水平 | 一条细微或强烈的内联规则;水平分隔符语义 | 容器宽度与主题绘制 |
| 已标记水平 | 两条规则环绕一个可见的、提供名称的标签 | 任何可渲染的标签内容 |
| 数字零标签 | 标签包装器内有一个可见的 0;分隔符名称为 0 |
任意方向或变体 |
| 垂直已标记/未标记 | 块轴规则与垂直分隔符语义 | 容器高度与标签内容 |
| 无匹配的主题新增变体 | 请求的变体得以反映;内部规则没有组件自有的绘制(FR3 缺口) | 自定义变体名称 |
| 通栏 | 逻辑轴内边距被消耗,且不作物理方向假设 | 统一、不对称、零或缺失的内边距 |
| RTL | 水平几何仍保持逻辑性;通栏独立消耗行内起点/终点 | 周围内容与标签语言 |
转换与优先级顺序¶
- ORD1 — 标签存在性。 应用共享的可渲染值谓词;当标签保留时,在两条规则之间渲染并引用一个包装器。
- ORD2 — 可访问名称。 显式
aria-labelledby优先,然后是显式aria-label,再然后是渲染出的标签包装器;未标记的分隔符保持无名称。 - ORD3 — 变体绘制。 在根目标上反映请求的值。内置值选择细微或强烈的内部规则绘制;未匹配的自定义值不选择任何内部规则绘制(FR3)。
性能与资源¶
- PR1 — 无外部生命周期。 Divider 不安装监听器、观察器、计时器、请求、状态机或 Effect。
可访问性契约¶
- AR1 — 编程式分隔符。 默认情况下,根元素暴露分隔符角色和精确的视觉方向;调用方显式提供的
role或aria-orientation优先(FR6),而目前组件的值会替换它(FR6 缺口)。 - AR2 — 标签关系。 渲染出的标签为分隔符命名,除非调用方提供了显式的可访问名称关系。
- AR3 — 装饰性规则片段。 内部规则元素不添加单独的角色、名称、焦点目标或交互。
设计关系¶
| 结构或状态 | 设计要求 | 表示权 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Divider group | 将规则片段和可选标签排列在同一个逻辑轴上。 | 当前来源;容器几何来自当前架构 | 辅助 | FR1, FR4 |
| Rule | 绘制一条可见的细微或强烈的分隔线;主题新增的值缺少已确定的回退方案。 | 当前来源;自定义回退是 FR3 缺口 | 辅助 | FR3 |
| Label | 使用辅助文本令牌在两条规则之间呈现可选内容。 | 当前来源;无单独目标(OQ1) | 突出 | FR1–FR2 |
没有记录任何组件本地的设计决策。
主题化结构¶
{
"Divider group": {"target": "divider"},
"Rule": {
"none": {
"reason": "unsettled: No current public target reaches this part"
}
},
"Label": {
"none": {
"reason": "unsettled: No current public target reaches this part"
}
}
}
这两个 none 处置方式记录了没有公共目标可达 Rule 或 Label;OQ1 持有它们是否应获得一个目标的开放问题。
家族与系统关系¶
architecture:container-padding拥有继承的内部内边距协议;Divider 仅通过isFullBleed消费它。architecture:component-theming-surface为目标、反映的轴和结构资格设定规则,并规定开放的视觉轴必须具有确定性的回退。Divider 的自定义值路径不满足该要求(FR3);OQ2 持有修复方向。architecture:public-component-api拥有根组合、ref 行为以及已发布的 ReactNode 标签表面的兼容性。- 当前没有 Divider 家族或设计记录。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, FR2, AR1, AR2 | Divider.test.tsx 方向、标签、命名和数值零测试 |
带标签和未带标签、数值零、显式名称、两种方向 | 在包装器外部渲染零值、未命名的带标签分隔符,或角色、方向或名称漂移会导致失败。缺口:只有未带标签的水平默认状态在稳定视觉基线(core-divider--default)中;垂直布局以及标签的类型和内边距没有自动化检查。 |
audit:Divider/a11y |
| AR3 | 源码审查 | 带标签和未带标签 | 缺口:如果分割线片段获得角色、名称或 Tab 停靠点,没有自动化检查会失败。 | audit:Divider/a11y |
| FR3, FR5 | Divider.test.tsx 变体和目标测试;themingTargets.test.ts;稳定视觉基线 core-divider--default |
弱化、强化、两种方向;默认 | 丢失的类或 orientation/variant 反射会导致失败;更改的默认规则绘制会以变更形式返回以供审查。缺口:强化绘制和未匹配的主题新增路径没有自动化检查。 |
audit:Divider/theming |
| FR4 | @astryx/no-physical-properties lint 规则;Divider.stories.tsx 全出血夹具 |
水平和垂直、LTR 和 RTL、无内嵌 | Divider 样式中物理的 left/right 属性会导致 lint 失败。缺口:Divider.test.tsx 全出血测试仅检查元素是否渲染,因此当全出血未应用、应用于错误轴或带有非零回退值时,没有自动化检查会失败,且没有浏览器从右到左检查覆盖全出血。 |
audit:Divider/layout |
| FR6 | Divider.test.tsx ref 和透传测试 |
Ref、额外属性 | 丢失的 ref 或调用方属性会导致失败。缺口:ref 测试接受任何元素,因此包装器上的 ref 会通过;没有测试覆盖样式输入合并或调用方的 role 或 aria-orientation。 |
audit:Divider/behavior |
| PR1 | 源码审查 | 每个状态 | 缺口:如果 Divider 添加监听器、观察器、定时器或副作用,没有自动化检查会失败。 | audit:Divider/behavior |
| AR1, AR2 | 无障碍树证据(spec:AST-009 FR3) |
带标签和未带标签的分隔符 | 缺口:没有无障碍树检查能证明分隔符的角色、方向或名称;单元测试仅查询 DOM。 | audit:Divider/a11y |
决策日志¶
未记录任何内容。该记录描述的是已发布的行为。
未决问题¶
- OQ1 — Rule 或 Label 是否应获得稳定的公开主题目标?(
human-api) 目前没有公开目标能触及它们;这种缺失并不能决定答案。 - OQ2 — 开放的
variant轴是否应关闭,或者哪个绘制部分拥有其确定性的自定义值回退?(human-api)根目标可以承载主题绘制,而内部分割线承载内置绘制。应用弱化的内部回退可以覆盖现有的根背景;保持当前路径可能会使分割线消失。选项:关闭该轴、转移目标所有权,或通过经过审查的公开属性传递绘制。
内容边界¶
本文件不重复使用者属性表/示例、当前审计结果、实现步骤或组件族/系统规则。它链接到这些内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx