Indicator 组件契约¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 无变更。@astryxdesign/core/Indicator 导出三个内置指示器(CheckboxIndicator、CheckIndicator、RadioIndicator)、共享的指示器 props 与类型、默认注册表以及按名称解析。 |
| 行为 | 宿主按名称(check、checkbox、radio)绘制装饰性控件视觉。主题中针对该名称的 indicators 条目会在每个按名称解析指示器的宿主中替换它;否则渲染内置指示器。每个指示器都对辅助技术隐藏。 |
| 最终用户影响 | 用户会在按名称解析指示器的组件中看到所选选项、复选框或单选按钮的一致标记,屏幕阅读器用户听到的是宿主控件的语义,而绝不会是重复内容。 |
| 构建者影响 | 无。 |
| 兼容性/就绪状态 | 记录已发布的行为;无 API、默认值或 DOM 变更。三个宿主直接渲染内置指示器,而非按名称解析;列于「当前状态影响」之下。 |
| 审查检查 | 拒绝向辅助技术暴露的指示器、被按名称解析的宿主忽略的主题覆盖、抑制内置标记的 falsy children,或指示器上的 role 或 Tab 停靠点。 |
| 治理规则 | architecture:component-theming-surface;architecture:public-component-api INV5;architecture:theme-authoring-contract。 |
此表为审查参考;下文正文具有权威性。
意图¶
Indicator 是共享的、可替换的装饰性控件视觉集合:所选选项上的标记、复选框绘制的方框以及单选按钮绘制的圆圈。它拥有指示器名称、按名称的主题替换、共享的装饰性 prop 契约,以及 RadioIndicator。消费者用法位于 Indicator.doc.mjs 中。
兼容性与迁移¶
- 已发布的默认行为保留:
yes;在没有主题覆盖的情况下,check、checkbox和radio解析为内置指示器 - 兼容性类别:记录已发布的行为;无公共 prop、默认值、导出或 DOM 变更
- 受控/非受控行为:不适用;宿主提供
state - 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 核心指示器名称以及将它们映射到内置指示器的默认注册表。
- 按名称的主题替换以及共享的指示器 prop 契约。
- RadioIndicator,作为
Indicator.doc.mjs的内联组件记录,具有radio-indicator和radio-indicator-dot目标。 - 宿主放置在元素上的
indicatorScope标记,该元素的悬停驱动指示器的悬停色调。
不拥有 / 非目标
- CheckboxIndicator — 由
component:CheckboxIndicator拥有。 - CheckIndicator — 由
component:CheckIndicator拥有。 - 宿主控件的角色、名称、状态、焦点、键盘和激活 — 由每个宿主拥有(CheckboxInput、RadioList、Selector、菜单行)。
- 作为 API 的
useIndicator和getIndicator— 没有自己模块记录的公共 hook 和函数;除 FR2 所描述的解析外,不受契约约束。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 指示器名称 | check、checkbox、radio,以及增强名称 |
宿主绘制哪种视觉。 | 始终。 | — | component:Indicator |
稳定 | 没有主题提供的增强名称解析为空。 |
| 状态 | unchecked、checked 和 indeterminate(复选框) |
宿主的选中状态。 | 按指示器系列。 | 必需 | component:Indicator |
稳定 | TypeScript 拒绝该系列之外的值。 |
| 尺寸 | sm、md |
指示器框尺寸。 | 始终。 | md |
component:Indicator |
稳定 | TypeScript 拒绝其他值。 |
| 替换内容 | 可渲染的 children |
替代内置状态标记绘制的内容。 | 始终。 | 无 | component:Indicator |
稳定 | Nullish、boolean 和空字符串 children 保留内置标记。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 默认注册表精确地将 check 映射到 CheckIndicator,checkbox 映射到 CheckboxIndicator,radio 映射到 RadioIndicator。 |
当前测试 |
| FR2 | 宿主按名称从最近的主题中解析指示器:该名称在主题的 indicators 条目中的值优先,否则使用内置指示器。一次覆盖会到达每个解析该名称的宿主。Tokenizer 底部弹层直接渲染 CheckboxIndicator 和 RadioIndicator,因此主题的 checkbox 或 radio 条目无法到达它。增强名称仅在主题提供时才解析。 |
architecture:theme-authoring-contract;当前测试 |
| FR3 | 每个内置指示器的根元素在调用方的 props 之后设置 aria-hidden="true",因此调用方无法将其暴露;公共 props 类型拒绝 role 和 tabIndex。指示器接收 state、size、isDisabled 和 children,并且不接收任何会赋予它们语义的内容。 |
architecture:public-component-api INV5;当前测试 |
| FR4 | 可渲染的 children 会替换指示器内部的内置状态标记;nullish、布尔值和空字符串 children 保留它,而 0 算作内容。 |
当前测试 |
| FR5 | RadioIndicator 渲染一个圆形的 span 元素(20 或 24 CSS 像素),其边框和填充随状态而变化:未选中时在表面(surface)上显示强调边框,选中时显示强调色填充,内部有一个 on-accent 圆点(8 或 10 CSS 像素)。禁用会将不透明度减半并弱化边框(以及未选中时的填充)。在支持悬停的指针下,悬停宿主的 indicatorScope 会使其着色。在强制颜色模式下,圆点保持可见。在减少动态效果(reduced motion)下,过渡是瞬时的。圆形和圆点以 50% 半径绘制,绝不用 --radius-full 胶囊(pill)token:圆形标记一个单选按钮,因此将胶囊做成方形的主题仍保留圆形的单选按钮,而想要方形单选按钮的主题则需要覆盖此组件。 |
当前源码和测试 |
| FR6 | RadioIndicator 的根元素带有 astryx-radio-indicator,并包含 data-size、data-checked 和 data-disabled;圆点带有 astryx-radio-indicator-dot,并包含 data-size。不会发出别名目标。调用方 props、ref、className、style 和 xstyle 都会到达根元素。 |
architecture:component-theming-surface;当前测试 |
允许的变化¶
- AV1 — 替换。 主题可以将任何已命名的指示器替换为符合 FR3 的组件。
- AV2 — 主题绘制。 主题可以在不替换内置指示器的情况下,通过其目标重新设置内置指示器的样式。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 无主题覆盖 | 内置指示器按名称渲染。 | — |
| 主题覆盖 | 每个解析该名称的宿主都会绘制覆盖组件。 | 覆盖设计。 |
| 单选已选中 | 强调色圆形容器带圆点;data-checked。 |
尺寸。 |
| Falsy 子元素 | 内置标记仍会渲染。 | — |
转换与优先级顺序¶
- ORD1 — 解析。 最近主题的
indicators[name],然后是内置指示器,对于未提供的增强名称则什么也不渲染。 - ORD2 — 属性。 先是调用方 props,然后是指示器自身的
aria-hidden。
性能与资源¶
- PR1 — 纯渲染。 指示器不拥有任何状态、副作用、监听器或观察器。
无障碍契约¶
- AR1 — 装饰性。 指示器对辅助技术隐藏;宿主拥有全部语义(FR3)。
- AR2 — 强制颜色。 在强制颜色模式下,单选圆点保持可见。
设计关系¶
| 结构或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 单选圆形容器 | 未选中时强调边框;选中时强调色填充。 | 当前来源 | 支持性 | FR5, FR6 |
| 单选圆点 | 选中时在强调色上显示圆点。 | 当前来源 | 支持性 | FR5, FR6 |
没有任何设计记录约束 Indicator。复选框和勾选视觉由它们各自的记录所有。
族与系统关系¶
architecture:theme-authoring-contract负责定义主题如何提供indicators。component:CheckboxIndicator和component:CheckIndicator负责另外两个内置指示器。- CheckboxInput、RadioListItem、Selector 和菜单选择行承载指示器。
验证映射¶
| 契约 | 验证 | 代表性状态 | 突变或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1、FR2 | indicatorRegistry.test.tsx;Indicator.test.tsx useIndicator 测试套件 |
无主题;主题覆盖;增强名称 | 默认值错误、覆盖被忽略或解析出未提供的名称,均判定为失败。 | audit:Indicator/behavior |
| FR3 | Indicator.test.tsx decorative-contract 测试套件 |
每个内置组件处于选中状态;调用方设置 aria-hidden={false};role 和 tabIndex 作为字面量 prop |
调用方可暴露的指示器、丢失的普通 prop,或接受的字面量 role 或 tabIndex,均判定为失败。证据缺口:没有测试检查未选中状态下的 aria-hidden。 |
audit:Indicator/accessibility |
| FR4 | Indicator.test.tsx falsy-children 测试套件 |
null、false、''、0、真实子元素 |
抑制任何内置组件标记的假值子元素(false、null、undefined 或 '')判定为失败,且 CheckIndicator 将 0 视为空值也判定为失败。证据缺口:没有测试将 0 渲染为 CheckboxIndicator 或 RadioIndicator 的子元素。 |
audit:Indicator/behavior |
| FR5、FR6、AR2 | Indicator.test.tsx radio-dot、disabled 和 target-name 用例;RadioIndicator.circle.source-build.test.mjs |
选中和未选中;禁用;规范目标 | 未选中时出现圆点、选中时无圆点、缺少已选中的 data-checked 或已禁用的 data-disabled,或别名目标,均判定为失败。证据缺口:没有测试断言单选按钮的尺寸、状态颜色(强调边框、强调填充、强调色上的圆点)、减少动态效果下的即时过渡、禁用状态的透明度和边框、悬停色调、强制颜色模式下的圆点(RadioList 的强制颜色用例在任一匹配规则下均通过)、根元素和圆点上的 radio data-size、ref,或调用方在根元素上的 className、style 和 xstyle。 |
audit:Indicator/theming |
| ORD1、ORD2、PR1 | 由 FR2 和 FR3 行覆盖。证据缺口:没有测试断言不存在状态、效果或监听器。 | — | — | audit:Indicator/behavior |
当前状态影响¶
- 直接指示器导入(FR2)。 Tokenizer 底部面板直接渲染 CheckboxIndicator 和 RadioIndicator,因此主题的
checkbox或radio覆盖无法作用于它。
决策日志¶
无组件级决策。
开放问题¶
无。
内容边界¶
本文件不重复消费者 prop 表格/示例、当前审计结果、实现步骤或组件族/系统规则。它链接到这些内容的所属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx