ChartGrid组件契约
ChartGrid 组件契约¶
契约速览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 无 API 形状或默认值变更。本草案记录当前水平、垂直及连续比例尺刻度密度表面。 |
| 行为 | 水平指引线跟随连续 y 刻度(零除外);垂直指引线跟随分类 x 波段中心或连续 x 刻度;两个方向均保持独立可选。 |
| 最终用户影响 | 图表读者可看到与父级 Chart 绘图比例尺对齐的指引线;本次审计不改变任何渲染行为。 |
| 构建者影响 | 现有调用点仍然有效,并直接获得 CLI 文档和针对当前密度回退的重点证据。 |
| 兼容性/就绪状态 | 该包仍仅限 canary 版本。本观察性草案非权威,确切的渲染/可访问性证据仍待定。 |
| 审查检查 | 拒绝变更后的公共形状/默认值、在 Chart 上下文之外使用比例尺的指引线、重复绘制的零基线,或不再以波段居中的分类指引线。 |
| 约束规则 | spec:AST-029/FR3–FR7、architecture:component-test-sufficiency/INV1–INV11、architecture:component-theming-surface/INV1–INV6 和 spec:AST-002。 |
此表是评审预览;下文正文具有权威性。
意图¶
ChartGrid 在 Chart 内部渲染被动的笛卡尔指引线。它负责从 Chart 提供的比例尺和绘图尺寸中选择与放置线,而 Chart 拥有坐标系、渲染顺序和图表级替代内容。
兼容性与迁移¶
- 已发布默认值保留:在 canary 表面上为是;该包没有稳定版本。
- 兼容性类别:无公共 API、默认值或渲染行为变更。
- 受控/非受控行为:不适用。
- 迁移决策:无;本草案不授权公共 API 变更。
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 从 Chart 提供的比例尺中选择水平和垂直指引值。
- 将每条指引线定位到当前绘图宽度或高度上。
- 省略配对轴可能强调的水平零基线。
- 在将连续比例尺刻度请求传递给 d3 之前对其进行清理。
不拥有 / 非目标
- 数据、数据域、比例尺构建、绘图尺寸或绘制顺序——由
component:Chart拥有。 - 轴标签、刻度标记或绘图边缘线——由
component:ChartAxis拥有。 - 图表的可访问名称、描述或数据替代内容——由
component:Chart和产品调用点拥有。 - 关于是否需要指引线的产品特定决策。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 水平指引线 | 显示或隐藏 | 在连续 y 刻度处绘制线,零除外。 | 每个 ChartGrid | 显示 | component:ChartGrid |
实验性 | 不适用。 |
| 垂直指引线 | 显示或隐藏 | 在 x 刻度或分类 x 波段中心处绘制线。 | 每个 ChartGrid | 隐藏 | component:ChartGrid |
实验性 | 不适用。 |
| 连续密度 | 有限非负数 | 请求 d3 连续比例尺提供近似的线数。 | 水平指引线和连续 x 指引线 | 5 |
component:ChartGrid |
实验性 | 小数向下取整;超过 1000 的值封顶;负数/非有限值回退为 5。 |
| 分类密度 | 每个分类 x 波段中心一条指引线 | 保持垂直指引线与每个波段对齐。 | 分类 x 搭配垂直指引线 | 所有波段 | component:ChartGrid |
实验性 | tickCount 当前无效果。 |
| Chart 上下文 | 位于父级 Chart 内 |
提供比例尺和当前绘图尺寸。 | 始终 | 无 | component:Chart |
实验性 | 在 Chart 外部渲染会抛出共享上下文错误。 |
行为与布局契约¶
草案需求标明其依据,以免将观察到的代码误认为有意决策。
| ID | 候选不变式 | 依据 | 草案审查状态 |
|---|---|---|---|
| FR1 | ChartGrid MUST 使用父级 Chart 上下文中的当前宽度、高度、x 比例尺和 y 比例尺。 | 实现、包组合和聚焦测试 | 验证 |
| FR2 | horizontal 和 vertical MUST 独立地启用各自的参考线集合;同时启用两者 MUST 渲染两个集合。 |
实现、JSDoc、测试和 Storybook | 验证 |
| FR3 | 水平参考线 MUST 使用连续的 y 刻度、跨越绘图宽度并省略 y=0,以便配对轴不会收到重复线条。 | 实现、JSDoc 和聚焦测试 | 验证 |
| FR4 | 垂直参考线 MUST 对 band x 比例尺使用分类 band 中心,对连续 x 比例尺使用 d3 刻度位置,并跨越绘图高度。 | 实现和聚焦测试 | 验证 |
| FR5 | 连续刻度请求 MUST 是有限、非负且不大于 1000 的整数;零不会产生连续参考线,无效值则使用默认五。 | 实现、防崩溃合理性及测试 | 验证 |
| FR6 | 参考线绘制 MUST 消费语义化主题令牌。网格线是否会成为公开的主题目标仍未决定。 | 实现和当前主题化架构 | 验证 |
允许的变体¶
- AV1 — 连续刻度计数。 d3 可能会选择邻近的一组值,而不是恰好请求的数量。
- AV2 — 分类值。 每个当前 x-band 域值贡献一条居中的垂直参考线。
代表性状态¶
| 状态 | 所需不变量 | 允许的变体 |
|---|---|---|
| 默认 | 仅水平参考线;连续密度默认为五。 | d3 选择确切的 y 刻度集合。 |
| 水平禁用 | 无水平参考线。 | 垂直参考线可保持启用。 |
| 垂直分类 | 每个 x-band 中心有一条垂直参考线。 | Band 宽度和中心遵循 Chart 的 x 比例尺。 |
| 垂直连续 | 每个生成的连续 x 刻度上有一条参考线。 | d3 选择确切的 x 刻度集合。 |
| 两个方向 | 水平参考线集合和垂直参考线集合一起渲染。 | 它们的确切数量可能不同。 |
| 连续刻度计数为零 | 连续参考线集合为空。 | 分类垂直参考线不受影响。 |
| 无效刻度计数 | 连续参考线生成回退到默认请求。 | d3 选择由此产生的确切刻度。 |
| 窄布局 / RTL | 参考线始终与物理数据坐标和绘图边界绑定。 | 绘图宽度和数据域顺序会变化。 |
转换与优先级顺序¶
- ORD1 — 连续密度。 验证有限性和非负性 → 对小数向下取整 → 上限为 1000 → 向 d3 请求刻度。
- ORD2 — 放置。 选择启用的方向 → 选择比例尺路径 → 推导刻度或 band 中心位置 → 跨越当前相对的绘图维度。
性能与资源¶
- PR1 — 派生输出。 参考线数组保持由渲染派生,并根据启用的方向、比例尺、尺寸和清洗后的密度进行记忆化。ChartGrid 不拥有任何监听器、观察器、定时器或持久资源。
- PR2 — 有界的刻度分配。 公开的密度值不能向 d3 请求超过 1000 个连续刻度。
无障碍契约¶
- AR1 — 图表级替代。 ChartGrid 在 Chart 的命名图像内渲染被动的辅助参考线。Chart 拥有可访问的图表名称和支持的数据表替代。
- AR2 — 无仅网格信息。 网格线不替代可见标签、有意义的标记或父级 Chart 替代。
设计关系¶
| 结构或状态 | 设计要求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 网格线 | 支持位置比较,而不单独承载图表含义。 | 未确定;当前未关联设计记录 | 支持性 | FR2–FR6, AR1–AR2 |
主题结构¶
{
"Grid lines": {
"none": {
"reason": "unsettled: ChartGrid consumes a semantic color token, but no current component or family contract decides whether grid lines are a public theme target."
}
}
}
组件族与系统关系¶
- 当前没有组件族或设计记录约束 ChartGrid。
architecture:component-test-sufficiency负责合理的公开状态分区、可观察断言和审计证据质量。architecture:component-theming-surface负责结构到目标的配置;单独的令牌消费不会让 ChartGrid 加入公开的组件主题化。spec:AST-002负责公开 API 准入,并阻止本次审计添加或重新解释公开选择。spec:AST-029负责本次观测性回填、封闭证据接收、安全修复和故障关闭资格报告。
Verification map¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1–FR2 | ChartGrid.test.tsx;ChartGrid.stories.tsx |
默认、关闭水平、开启垂直、两者皆开、两者皆关 | 某个方向不再遵循其输入,或输出脱离父级 Chart 上下文。 | audit:ChartGrid/behavior |
| FR3 | ChartGrid.test.tsx |
正数及正负混合的 y 值域 | 引导线不再跨越绘图区,或 y=0 被绘制两次。 | audit:ChartGrid/behavior-layout |
| FR4 | ChartGrid.test.tsx;ChartGrid.stories.tsx |
分类与连续 x 轴 | 带状引导线偏离其中心,或连续刻度落在错误的坐标上。 | audit:ChartGrid/behavior-layout |
| FR5, PR2 | 针对零值与无效密度的测试及源码审查 | 零值与无效请求;小数分区与上限分区 | 无效输入导致渲染崩溃,或绕过有界回退逻辑。 | audit:ChartGrid/behavior-testing |
| FR6 | 严格 lint;Storybook 主题矩阵仍待完成 | 浅色、深色及受支持的非默认主题 | 原始颜色或组件侧的模式选择取代了语义化令牌的绘制。 | audit:ChartGrid/theming-design |
| AR1–AR2 | Chart 可访问性测试;axe 包检查仍待完成 | 具名 Chart、小数据表格、启用网格 | 网格内容取代所需图表信息,或成为所需图表信息的唯一来源。 | audit:ChartGrid/accessibility |
Decision log¶
无。本草案仅记录已观察到的行为与证据缺口。
Open questions¶
- OQ1 — 分类密度。
tickCount是否应继续保持仅适用于连续比例尺,还是垂直分类引导线应与 ChartAxis 对齐,获得文档化的抽稀契约?(human-api)
Content boundary¶
本文件不重复消费者属性表/示例、现有审计结果、实现步骤或共享系统规则,而是链接到这些内容的所属位置。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx