ChartSwatch 组件契约¶
契约速览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 无 API 形态或默认值更改。本草案记录当前由调用方拥有的颜色、方形/线形形状,以及导出的系列类型映射工具函数。 |
| 行为 | 省略 variant 时渲染方形;显式传入 line 时渲染短笔画;swatchVariantForType 将 bar 映射为方形,将所有其他或省略的类型映射为线形。 |
| 终端用户影响 | 图表读者在可见系列标签旁看到相同的装饰性标记形状颜色键;本次审计不改变任何渲染行为。 |
| 构建者影响 | 现有调用点保持有效,并为随组件发布的 props、默认值、组合和可访问性边界补充消费者文档。 |
| 兼容性/就绪状态 | 该包仍仅限 canary。本观察性草案不具备权威性;公共工具函数名称及未来的主题化可达性仍是未解决的所有者决策。 |
| 审查检查 | 拒绝更改后的默认值或类型映射、丢失的装饰语义、将几何漂移表述为策略的做法,或声称仅凭颜色即可始终识别系列的主张。 |
| 治理规则 | spec:AST-029/FR3–FR7、architecture:component-test-sufficiency/INV1–INV11、architecture:component-theming-surface/INV1–INV11 以及 spec:AST-002/FR17。 |
此表是审查投影;以下正文具有权威性。
意图¶
ChartSwatch 绘制一个紧凑的装饰性颜色键,在视觉上将系列标签与图表标记连接起来。它拥有方形和线形形状,以及当前从系列类型到这些形状的映射。图例、工具提示、图表或产品调用点拥有可见的系列名称及其周边关系。
兼容性与迁移¶
- 已发布默认值保留情况:在 canary 层面为是;该包尚无稳定版本。
- 兼容性类别:无公共 API、默认值或渲染行为更改。
- 受控/非受控行为:不适用。
- 迁移决策:无;本草案不授权对公共工具函数进行重命名或移除。
消费者迁移说明应归入消费者文档和发布说明。
所有权边界¶
拥有
- 将调用方拥有的一种颜色绘制为紧凑的方形或线形。
- 保持色块对辅助技术为装饰性。
- 将
bar系列类型映射为方形,将所有其他或省略的类型映射为线形。
不拥有 / 非目标
- 选择、验证或调整图表调色板——由图表和产品调用点拥有。
- 命名系列或提供可访问的图表替代方案——由周围的图例、工具提示、Chart 或产品调用点拥有。
- 确立仅凭颜色即可在绘制出的图表及其周边界面中区分系列的能力。
- 交互、选择、过滤、可见性或工具提示行为。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 系列颜色 | 调用方拥有的 CSS 颜色字符串 | 为装饰性标记着色。 | 每个 ChartSwatch | 必填 | 产品调用点 | 实验性 | 无效的 CSS 颜色语法可能使色块无填充色。 |
| 色块形状 | square、line |
在视觉上呼应柱状或非柱状图表标记。 | 每个 ChartSwatch | square |
component:ChartSwatch |
实验性 | 由导出的 TypeScript 联合类型封闭。 |
| 系列类型映射 | bar;所有其他字符串;省略 |
将系列类型转换为组件支持的两种形状。 | 导出的工具函数 | line | component:ChartSwatch |
实验性 | 未知类型和省略的类型使用 line 形状。 |
| 辅助技术参与 | 装饰性,对辅助技术隐藏 | 将含义交由周围的可见文本承载。 | 每个 ChartSwatch | 内置 | component:ChartSwatch |
实验性 | 不可配置。 |
行为与布局契约¶
草稿需求标明其依据,以免将观察到的代码误认为有意决策。
| ID | 候选不变量 | 依据 | 草案审查状态 |
|---|---|---|---|
| FR1 | ChartSwatch 在省略 variant 时 MUST 渲染一个装饰元素,并 MUST 使用 square。 |
实现、针对性测试和浏览器传感器 | 待验证 |
| FR2 | Square 目前 MUST 渲染为 8×8 的标记,圆角为 2,内联边距为 1;line 目前 MUST 渲染为 10×3 的标记,圆角为 1.5。 | 实现和已确认的浏览器矩阵 | 待验证 |
| FR3 | 渲染的绘制 MUST 遵循调用方提供的 color,不自行选择或调整调色板。 |
实现、针对性测试和浏览器传感器 | 验证 |
| FR4 | 色块 MUST 对辅助技术保持隐藏;周围内容 MUST 提供可见且可访问的系列含义。 | 实现、针对性测试、针对性的 axe 和浏览器 | 验证 |
| FR5 | swatchVariantForType 仅在 bar 时 MUST 返回 square,对于所有其他字符串和 undefined MUST 返回 line。 |
实现和针对性测试 | 验证 |
| FR6 | 浅色、深色、窄视口和粗指针媒体 MUST NOT 改变组件自有的形状契约,也不得引入水平视口溢出。 | 已收讫的浏览器矩阵 | 验证 |
允许的变化¶
- AV1 — 系列绘制。 任何有效的调用方自有 CSS 颜色都可以绘制任一形状。
- AV2 — 周围布局。 图例、工具提示或自定义调用点可以将色块放置在任意位置,只要保留其与可见系列标签的关联。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 省略 / 方形 | 方形几何和装饰性语义保持不变。 | 调用方颜色和周围位置可以变化。 |
| 线形 | 线形几何和装饰性语义保持不变。 | 调用方颜色和周围位置可以变化。 |
bar 映射 |
工具函数返回 square。 |
源系列定义可以携带其他字段。 |
| 非 bar / 省略映射 | 工具函数返回 line。 |
未知的和未来的非 bar 类型字符串使用回退值。 |
| 浅色 / 深色 | 形状和提供的绘制保持不变。 | 周围表面遵循其当前激活的主题。 |
| 窄视口 / 粗指针 | 不添加组件自有的溢出或交互。 | 周围布局可以换行或重新定位色块。 |
转换与优先级顺序¶
- ORD1 — 渲染。 省略时应用默认变体 → 选择方形或线形几何 → 使用调用方颜色绘制 → 将结果元素对辅助技术隐藏。
- ORD2 — 系列映射。 将系列类型与
bar比较 → 对精确匹配返回 square → 否则返回 line。
性能与资源¶
- PR1 — 无持久资源。 渲染、重新渲染和卸载 ChartSwatch MUST NOT 创建或保留监听器、观察器、计时器、请求、订阅或其他持久浏览器资源,并且 MUST 不需要使用者进行清理。
无障碍契约¶
- AR1 — 装饰性标记。 ChartSwatch 对辅助技术保持隐藏,因为其周围可见的系列标签提供了含义。
- AR2 — 有意义的上下文。 独立的调用点将色块与可见文本配对;色块不能替代 Chart 的可访问名称、等效数据视图或摘要。
- AR3 — 系列区分。 关于同形状系列是否需要额外关联线索的证据,必须覆盖组合后的图表及其标签,而不是孤立的装饰性色块。
设计关系¶
| 结构或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 系列色块 | 呼应图表标记,同时保持对辅助技术(AT)的装饰性。 | 未定;当前没有关联的设计记录 | 支撑 | FR1–FR6, AR1–AR3 |
| 方形形状 | 表示当前的 bar 系列映射。 | 观察到的实现 | 支撑 | FR1–FR2, FR5 |
| 线形形状 | 表示当前的非 bar 和回退系列映射。 | 观察到的实现 | 支撑 | FR2, FR5 |
主题化结构¶
{
"Series swatch": {
"none": {
"reason": "unsettled: caller-owned color and fixed component geometry currently paint the swatch without a public theme target; this draft does not decide future reachability."
}
}
}
ChartSwatch 是可见的绘制者,但不暴露当前的公共主题目标。主题是否应获得一个稳定目标,仍是所有者的决定。
家族与系统关系¶
- 当前没有家族或设计记录管辖 ChartSwatch。
architecture:component-test-sufficiency负责合理的公共状态划分、可观察断言和审计证据质量。architecture:component-theming-surface负责结构到目标的处置;本草案记录当前的缺失,而不决定未来的可主题化性。architecture:knowledge-contracts将消费者语法保存在ChartSwatch.doc.mjs中,并将观察到的行为保存在本草案组件记录中。spec:AST-002/FR17负责未解决的公共工具函数命名问题。spec:AST-029负责本次观察性回填、关闭的证据收讫、安全修复和 fail-closed 资格报告。
验证映射表¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1–FR3 | ChartSwatch.test.tsx;已验证的浏览器矩阵 |
省略、方形、线条、六种颜色、浅色、深色 | 默认、几何形状或调用方绘制的更改没有可见证据。 | audit:ChartSwatch/behavior-design |
| FR4 | 聚焦的 DOM 断言;聚焦的 axe 检查;浏览器传感器 | 方形、线条、浅色、深色 | 色块进入无障碍树,或周围含义被赋予该标记。 | audit:ChartSwatch/accessibility |
| FR5 | ChartSwatch.test.tsx |
条形、线条、圆点、面积、未知、省略 | 条形失去方形,或其他类型获得方形。 | audit:ChartSwatch/public-utility-behavior |
| FR6 | 已验证的 Storybook 浏览器矩阵 | 1280 px、320 px、粗指针、浅色、深色 | 形状改变、出现溢出,或组件获得依赖媒体的行为。 | audit:ChartSwatch/responsive-rendered-design |
| AR1–AR3 | 聚焦的 axe 检查;ChartLegend 和 ChartTooltip 组合审查 | 独立使用和组合使用 | 装饰性语义丢失,或使用孤立证据来决定图表关联。 | audit:ChartSwatch/accessibility-composition |
决策日志¶
无。本草案仅记录观察到的行为和证据缺口。
开放问题¶
- OQ1 — 公共工具名称。 系列类型映射是否应保持公开?如果是,什么以动词开头的名称和兼容路径能够满足
spec:AST-002/FR17?(human-api) - OQ2 — 色块主题可达性。 ChartSwatch 是否应暴露公共主题目标,还是其绘制和几何形状应保持由调用方/组件所有?(
human-api) - OQ3 — 组合系列关联。 包含多个形状相同系列的组合图表是否需要额外的关联提示,以及该提示由哪一层负责?(
human-design)
内容边界¶
本文件不重复使用方属性表/示例、当前审计结果、实施步骤或共享系统规则。它链接到相应内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx