CheckIndicator 组件契约¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | CheckIndicator 从 @astryxdesign/core/Indicator 导出;state 为必填,size 默认为 md,isDisabled 默认为 false,且 children 可替换内置标记。 |
| 行为 | 该组件仅在选中状态下绘制装饰性的勾选图形。可浅层渲染的 children 在任一状态下都会替换该图形;未选中且无替换内容时不渲染任何元素。 |
| 最终用户影响 | 用户从所属控件获得一个选择提示,而不会出现重复的无障碍对象,也不会在未选中行旁边出现空占位符。 |
| 构建者影响 | 构建者可以替换名为 check 的指示器,或组合宿主拥有的类与样式,而无需接管所属控件的语义。 |
| 兼容性/就绪度 | 记录已发布行为;没有 API、默认值或 DOM 变更。选中状态的图形路径会丢弃声明的 ref;已列在“当前状态影响”下,修复仍未完成(OQ1)。 |
| 审查检查项 | 拒绝:丢失 aria-hidden;未选中默认状态中的标记;缺少选中标记;丢失受支持的 DOM/样式透传;更改替换优先级;新增组件拥有的主题目标;或在 OQ1 被决定后,选中路径仍丢弃 ref。 |
| 治理规则 | architecture:public-component-api/INV1,INV5,INV6,INV8,INV9;architecture:component-theming-surface/INV3–INV6;architecture:component-test-sufficiency/INV1–INV7,INV10–INV11. |
本表是审查投影;以下正文为权威依据。
意图¶
渲染由宿主使用的可替换、装饰性的勾选标记,用于表示某个选项已被选中,而不承担选择语义、交互或持久控件外观(chrome)的所有权。
兼容性与迁移¶
- 已发布的默认值保留:是
- 兼容性分类:记录已发布行为;没有公共 prop、默认值、导出或 DOM 变更
- 受控/非受控行为:不适用;
state由所有者提供 - 迁移决策:无;公共组件和
check注册名称保持不变
使用方迁移说明应放在使用方文档和发布说明中。
所有权边界¶
拥有
- 选中图形、未选中时的空缺、禁用颜色、尺寸映射、替换内容优先级和装饰性根节点。
- 在每个渲染的根节点上支持中性的 DOM 和样式透传。替换内容的 span 接收声明的 ref;当前选中的 Icon 路径不会。
不拥有 / 非目标
- 选择角色、无障碍名称、状态、焦点、键盘、激活或忙碌语义——由组合控件拥有。
- 持久复选框或单选按钮外观(chrome)——由
component:CheckboxIndicator或component:Indicator拥有。 - 行放置和逻辑边缘布局——由宿主组件拥有。
- 使用方提供的替换内容的行为或无障碍特性。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| state | unchecked, checked |
选择内置勾选图形是不存在还是存在。 | 所有渲染路径。 | 必填 | component:CheckIndicator |
稳定 | 被公共类型拒绝 |
| size | sm, md |
选择共享的指示器尺寸;当前两个值都使用 sm 的 Icon 图形。 |
选中状态和替换内容的根节点。 | md |
component:CheckIndicator |
稳定 | 被公共类型拒绝 |
| 禁用外观 | 启用、禁用 | 镜像所属控件的禁用颜色,而不产生语义。 | 选中状态和替换内容的根节点。 | 启用 | component:CheckIndicator |
稳定 | 仅接受布尔值 |
| replacement content | 浅层可渲染或为空 | 当 isRenderable(children) 返回 true 时,在任一状态下替换内置标记。React 元素和容器即使后代不渲染任何内容也会走此分支。 |
每个状态;替换内容会创建一个 span 根节点。 | 内置标记路径 | component:CheckIndicator |
稳定;空容器策略未决(OQ2) | 不支持的值的处理遵循 React 渲染行为 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 当 state="checked" 且不存在替换内容时,组件 MUST 渲染一个装饰性对勾图形,并且 MUST 在调用方透传之后设置自身的 aria-hidden="true"。 |
随附源码;architecture:public-component-api/INV5 |
| FR2 | 当 state="unchecked" 且不存在替换内容时,默认组件 MUST 不渲染任何元素。 |
随附源码、文档、测试和 stories |
| FR3 | 替换在两个状态下都采用浅层 isRenderable(children) 优先级:nullish 值、布尔值和空字符串保留内置状态行为;React 元素和容器即使后代不渲染任何内容,也会替换内置标记(OQ2)。 |
随附源码和回归测试 |
| FR4 | 每个渲染出的根节点 MUST 保留受支持的 DOM props、className、style 和 xstyle,同时保持组件拥有的无障碍优先权;声明的 ref MUST 到达渲染后的根节点(architecture:public-component-api/INV8)。实现缺口:替换内容的 span 会接收 ref,但选中状态的 Icon 路径会丢弃它(OQ1)。 |
architecture:public-component-api/INV5,INV6,INV8;当前源码 |
| FR5 | 内置的 checked 标记 MUST 保持为 Icon 拥有的绘制器,并与宿主提供的类位于同一元素上;未经批准的契约变更,CheckIndicator MUST NOT 添加包装器或不同的公共目标。 | 随附源码;architecture:component-theming-surface/INV3–INV5 |
| FR6 | 禁用态颜色和替换内容颜色 MUST 继续使用语义化 token,而不是原始颜色值。 | 随附源码;当前 token 与主题架构 |
允许的变化¶
- AV1 — 主题绘制。 Icon 目标和宿主拥有的类可以更改受支持的绘制,而不改变状态或语义所有权。
- AV2 — 替换组件。 当替换组件保留此公共 prop 和装饰性所有权契约时,主题可以替换名为
check的指示器。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 未选中 | 不渲染任何内置元素。 | 替换组件可以绘制。 |
| 选中 | 渲染一个装饰性对勾图形。 | Icon 与宿主拥有的主题绘制。 |
| 禁用 | 选中或替换内容保持所请求的状态,并使用禁用态的语义化颜色。 | 主题拥有的非激活处理方式。 |
| replacement content | 浅层可渲染内容在居中的固定尺寸装饰性根节点中替换内置标记。 | 调用方拥有的装饰性内容。 |
转换与优先级顺序¶
- ORD1 — 渲染优先级。 浅层替换内容判断 → 未选中的缺失或选中的 Icon → 调用方透传 → 组件自有的
aria-hidden→ 合并后的主题/样式输入。
性能与资源¶
- PR1 — 纯渲染。 组件不拥有任何状态、Effect、监听器、观察器、定时器或外部资源。
无障碍契约¶
- AR1 — 装饰性归属。 每个渲染出的根节点保持
aria-hidden;组合控件拥有 role、名称、状态、焦点、键盘、激活和表单语义。 - AR2 — 替换边界。 替换内容在隐藏根节点内是装饰性的,且 MUST NOT 是所属控件选中或忙碌状态的唯一语义表达。
设计关系¶
| 解剖结构或状态 | 设计要求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Chrome | CheckIndicator 有意不拥有任何持久化 chrome。 | 已发布实现中观察到的呈现 | 不适用 | FR2, FR5 |
| 状态标记 | 选中状态渲染共享的装饰性对勾 Icon。 | Icon 所拥有的当前主题架构 | 辅助状态提示 | FR1, FR5–FR6 |
共享的 Indicator.doc.mjs 将 CheckboxIndicator、CheckIndicator 和 RadioIndicator 的解剖结构与目标一同列出,因此本记录不包含 anatomy-theming 映射。CheckIndicator 不拥有任何持久化 chrome,并将其内建选中标记委托给 Icon。
家族与系统关系¶
architecture:component-theming-surface负责目标放置与组合绘制器的归属。architecture:public-component-api负责导出、透传、样式组合、ref 和兼容性要求。architecture:component-test-sufficiency负责每个关键承诺和不同风险分区所需的证据。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, FR2, FR3 | Indicator.test.tsx 中 CheckIndicator 的状态与替换场景;falsy children 场景 |
选中、未选中、空标量、可见子元素、0 |
移除字形、添加未选中的 chrome,或选择错误的 children 分支均会失败。 | audit:CheckIndicator/behavior |
| FR1, AR1 | Indicator.test.tsx 中的装饰性契约场景 |
字形与替换根节点;调用方传入 aria-hidden={false} |
调用方可暴露的根节点会导致失败。证据缺口:没有测试断言替换内容不是状态的唯一表达(AR2)。 | audit:CheckIndicator/accessibility |
| FR4 | Indicator.test.tsx“在两条渲染路径上转发调用方 props 和样式” |
两条渲染路径 | 调用方 DOM prop 若停止到达任一根节点,或 className 若停止到达替换 span,则失败。证据缺口:没有测试断言选中字形路径上的 className、style 或 xstyle,替换 span 上的 style 或 xstyle,或任一路径上的 ref(选中路径的 ref 是 FR4 缺口)。 |
audit:CheckIndicator/api |
| FR5, FR6 | themingTargets.test.ts |
选中的字形 | 渲染出的 class 若未出现在文档记录的 targets 中,则失败。证据缺口:没有测试断言没有包装器将宿主 class 与 Icon 绘制器分隔开,或禁用色与替换色使用语义化 token。 | audit:CheckIndicator/theming |
| ORD1, PR1 | 由 FR1–FR4 行覆盖。证据缺口:没有测试断言不存在状态、Effect 或监听器 | — | — | audit:CheckIndicator/behavior |
当前状态影响¶
- Checked-path ref (FR4). 当 CheckIndicator 绘制其选中的字形(checked glyph)时,声明的 ref 为
null,这与architecture:public-component-apiINV8 相悖;修复方案为 OQ1。
决策日志¶
无组件级决策。
开放问题¶
- OQ1 — CheckIndicator 是否应通过在选中路径中持有一个稳定的 span 根元素来保留其声明的
HTMLSpanElementref,还是应更改公共 ref 合约以匹配 Icon 拥有的 painter? (human-api) 当前的选中路径返回null;任一修正都会改变已发布的 DOM 或 ref 合约。 - OQ2 — 空的 React 容器是否应继续抑制内置状态标记? (
human-api) FR3 记录它们目前正是如此。
内容边界¶
本文件不重复消费者 prop 表/示例、当前审计结果、实现步骤或族/系统规则。它提供指向其归属方的链接。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx