CheckboxIndicator 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | CheckboxIndicator 从 @astryxdesign/core/Indicator 导出;state 为必需项,size 默认为 md,isDisabled 默认为 false,children 可替换内置标记。 |
| 行为 | 始终渲染装饰性复选框外观。除非浅层 isRenderable() 谓词将 children 视为替换内容,否则选中和不确定状态会绘制对应的标记。 |
| 终端用户影响 | 用户会收到一个可见的复选框状态提示,而所属控件保留所有语义、焦点、键盘和激活行为。 |
| 构建者影响 | 构建者可重新设置标准目标的样式或替换指定的指示器,而无需接管所属控件的语义。 |
| 兼容性/就绪状态 | 记录已发布行为;无 API、默认值或 DOM 变更。仅输出标准的 checkbox-indicator 目标。 |
| 审查检查 | 拒绝丢失 aria-hidden、缺失状态标记、丢弃透传/ref/样式、更改替换优先级,或在根上出现第二个目标别名。 |
| 治理规则 | architecture:public-component-api/INV1,INV5,INV6,INV8,INV9;architecture:component-theming-surface/INV3–INV8,INV12;architecture:component-test-sufficiency/INV1–INV7,INV10–INV11。 |
此表是审查投影;下文正文具有权威性。
意图¶
渲染可替换的装饰性视觉元素,用于传达复选框所有者的未选中、选中或不确定状态,而不接管复选框的语义或交互。
兼容性与迁移¶
- 已发布默认值保留:是
- 兼容性类别:记录已发布行为;无公共 prop、默认值、导出或 DOM 变更
- 受控/非受控行为:不适用;
state由所有者提供 - 迁移决策:无
使用者的迁移说明应放在使用者文档和发布说明中。
所有权边界¶
拥有
- 装饰性复选框外观、状态标记、禁用外观、尺寸、替换内容优先级以及组件主题化目标。
- 根 DOM ref 以及受支持的中性 DOM 和样式透传。
不拥有 / 非目标
- 复选框角色、无障碍名称、焦点、键盘、激活、表单参与或忙碌语义——由组合控件拥有。
- 行放置和逻辑边缘布局——由宿主组件拥有。
- 使用者提供的替换内容的行为或可访问性。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
state |
unchecked、checked、indeterminate |
选择内置的视觉状态。 | 所有渲染路径。 | 必需 | component:CheckboxIndicator |
稳定 | 由公共类型拒绝 |
size |
sm、md |
选择 20px 或 24px 的视觉框及匹配的标记几何。 | 所有状态。 | md |
component:CheckboxIndicator |
稳定 | 由公共类型拒绝 |
| 禁用外观 | 启用、禁用 | 镜像所属控件的禁用表现,而不产生语义。 | 所有状态。 | 启用 | component:CheckboxIndicator |
稳定 | 仅接受布尔值 |
| 替换内容 | 浅层可渲染或为空 | 当 isRenderable(children) 返回 true 时,替换两个内置标记。即使后代未渲染任何内容,React 元素和容器也会走此分支。 |
所有状态。 | 内置标记路径 | component:CheckboxIndicator |
稳定;空容器策略开放(OQ1) | 不支持的取值遵循 React 渲染行为 |
行为与布局契约¶
| ID | 不变式 | 依据 |
| FR1 | 组件 MUST 在每种状态下渲染一个装饰性的 span 外壳,并且在调用方透传之后设置自身的 aria-hidden="true"。 | 已发布的源码;architecture:public-component-api/INV5 |
| FR2 | unchecked MUST 不显示任何内置标记,checked MUST 显示对勾,indeterminate MUST 显示短横线。 | 已发布的源码、文档、测试和 stories |
| FR3 | 替换使用浅层 isRenderable(children) 优先级:nullish 值、布尔值和空字符串保留状态标记;React 元素和容器会替换它,即使其后代不渲染任何内容(OQ1)。 | 已发布的源码和回归测试 |
| FR4 | 根元素 MUST 保留受支持的 DOM props、ref、className、style 和 xstyle,同时保持组件自有的可访问性优先级。 | architecture:public-component-api/INV5,INV6,INV8 |
| FR5 | 根目标 MUST 是 checkbox-indicator,即该元素上唯一的目标;不得发出别名目标。 | architecture:component-theming-surface/INV4,INV6;当前测试 |
| FR6 | 尺寸、选中或不确定(data-checked)以及禁用状态 MUST 反映在根目标上;对勾和短横线 MUST 保留其专用的 checkbox-indicator-check 和 checkbox-indicator-dash 绘制目标。 | 已发布的源码;architecture:component-theming-surface/INV4,INV6 |
| FR7 | 状态转换 MUST 遵循减少动态效果(reduced motion)设置,并且选中/不确定标记在强制颜色(forced-colors)模式下 MUST 保持可感知。 | 已发布的源码和 WCAG 2.2 1.4.11 |
允许的变化¶
- AV1 — 主题绘制。 令牌和规范组件目标可以更改颜色、边框、圆角、不透明度及其他允许的视觉属性,而无需改变状态或语义所有权。
- AV2 — 替换组件。 当替换组件保留此公开 prop 和装饰性所有权契约时,主题可以替换指定的复选框指示器。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| unchecked | 外壳保持可见,且不显示任何内置标记。 | 主题拥有的绘制与形状。 |
| checked | 外壳和对勾保持可见。 | 主题拥有的绘制与形状。 |
| indeterminate | 外壳和短横线保持可见。 | 主题拥有的绘制与形状。 |
| disabled | 所请求的状态在弱化处理下保持清晰可读,且没有宿主驱动的悬停响应。 | 主题拥有的非活动处理方式。 |
| replacement content | 可浅层渲染的内容会替换同一外壳内的两个内置标记。 | 调用方拥有的装饰性内容。 |
转换与优先级顺序¶
- ORD1 — 渲染优先级。 调用方透传 → 组件自有的
aria-hidden→ 合并的主题/样式输入 → 浅层替换内容决策 → 内置状态标记。
性能与资源¶
- PR1 — 纯渲染。 组件不拥有任何状态、Effect、监听器、观察器、计时器或外部资源。
可访问性契约¶
- AR1 — 装饰性所有权。 根元素保持
aria-hidden;组合而成的控件拥有角色、名称、状态、焦点、键盘、激活和表单语义。 - AR2 — 强制颜色。 当作者颜色被强制覆盖时,选中和不确定标记仍可区分。
- AR3 — 替换边界。 替换内容在隐藏的根元素内是装饰性的,并且 MUST NOT 成为所属控件状态的唯一语义表达。
设计关系¶
| 结构或状态 | 设计需求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Chrome | 语义主题令牌和规范绘制目标 | 由当前主题架构规定 | 辅助控件视觉 | FR1, FR5–FR7 |
| Checkmark | 可见的选中状态标记 | 已发布实现中的观察结果 | 辅助状态提示 | FR2, FR6–FR7 |
| 不确定标记 | 可见的部分状态标记 | 从已发布实现中观察到的表现 | 辅助性状态提示 | FR2、FR6–FR7 |
共享的 Indicator.doc.mjs 将 CheckboxIndicator、CheckIndicator 和 RadioIndicator 的解剖结构与目标合并列出,因此本条记录不包含解剖结构-主题映射。
组件族与系统关系¶
architecture:component-theming-surface负责目标放置与状态反映。component:Indicator负责注册表名称checkbox与主题替换。architecture:public-component-api负责导出、透传、样式组合、ref 和兼容性要求。architecture:component-test-sufficiency负责每条关键承诺及不同风险分区所需证据。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1、AR1 | Indicator.test.tsx 装饰性契约用例 |
选中状态;调用方 aria-hidden={false} |
可被调用方暴露的已选中指示器将导致失败。证据缺口:没有测试检查未选中或不确定状态下的 aria-hidden,也没有测试验证替换内容并非唯一的状态表达方式(AR3)。 |
audit:CheckboxIndicator/accessibility |
| FR2、FR3 | Indicator.test.tsx 默认指示器、替换和假值子元素用例 |
选中状态且带假值与真实子元素;选中状态且带替换子元素 | 被移除的勾选标记元素、抑制它的假值子元素、或不替换它的真实子元素,都会导致失败。证据缺口:没有测试检查短横线元素;而且由于两个标记在每个状态下都会渲染,并通过 display 切换显隐,没有测试断言每个状态下可见的是哪个标记。 | audit:CheckboxIndicator/behavior |
| FR4 | Indicator.test.tsx 装饰性契约「仍然转发普通属性」用例 |
普通 DOM 属性 | 丢失 data-testid、id 或 dir 将导致失败。证据缺口:没有测试断言根元素上的 ref、className、style 或 xstyle。 |
audit:CheckboxIndicator/api |
| FR5、FR6 | Indicator.test.tsx 复选框目标与规范目标用例;themingTargets.test.ts |
sm 下的不确定状态;规范目标 |
缺失或被别名化的 checkbox-indicator 目标,或缺失 data-checked="indeterminate" 或 data-size,将导致失败。证据缺口:没有测试断言选中状态下的 data-checked、复选框的 data-disabled(禁用状态用例渲染的是 RadioIndicator)、或 checkbox-indicator-check 与 checkbox-indicator-dash 目标。 |
audit:CheckboxIndicator/theming |
| FR7、AR2 | CheckboxInput.test.tsx 强制颜色用例(「编译强制颜色填充,使不确定标记在 Windows 高对比度下依然可见」、「编译强制颜色,使勾选标记在 Windows 高对比度下依然可见」) |
强制颜色下的选中与不确定状态 | 证据缺口:强制颜色用例只要匹配任意注入的规则即可通过,因此移除勾选标记和短横线元素的 CanvasText 规则后测试仍然通过;没有测试断言减少动效(reduced-motion)过渡。 |
audit:CheckboxIndicator/visual |
| ORD1、PR1 | 由 FR1–FR4 行覆盖。证据缺口:没有测试断言不存在状态、副作用或监听器。 | — | — | audit:CheckboxIndicator/behavior |
决策日志¶
无组件本地决策。
开放问题¶
- OQ1 — 空的 React 容器在
children中是否应继续抑制内置状态标记? (human-api) FR3 记录表明当前确实如此。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx