跳转至

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