ChartAxis 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 无 API 形状或默认值更改。截断和自动水平密度现在按照客观的 Unicode 文本分段标准统计完整的字素簇。 |
| 行为 | 所选物理绘图边缘决定比例尺、位置、标签方向和默认边缘线;显式格式化和密度输入可细化标签。 |
| 最终用户影响 | 图表阅读者会获得完整的刻度标签字符,同样短的 Unicode 标签不再比 ASCII 标签更激进地抽稀。 |
| 构建方影响 | 无。现有调用点保持有效,并为当前界面获得直接 CLI 文档。 |
| 兼容性/就绪状态 | canary API 和默认值均被保留。此记录是草稿观察证据;渲染和可访问性树证据仍不完整。 |
| 审查检查 | 若出现以下情况则拒绝:公共形状/默认值被更改、坐标轴使用了错误的 Chart 比例尺、物理边缘放置损坏、字素标签被拆分、或线/刻度优先级被隐藏。 |
| 约束规则 | spec:AST-029/FR3–FR7、architecture:component-test-sufficiency/INV1–INV9,以及 Unicode 文本分段。 |
此表为评审概览;下方正文具有权威性。
意图¶
ChartAxis 在 Chart 内部渲染带标签的笛卡尔 x 或 y 比例尺输出。它负责物理边缘放置、刻度选择和格式化、可选刻度标记以及可选坐标轴边缘线,而 Chart 负责比例尺域和绘图几何。
兼容性与迁移¶
- 已发布默认值保留:是;该包仅限 canary,尚无稳定版本。
- 兼容性类别:无公共 API 或默认值更改;Unicode 截断和自动抽稀仅有意更改包含多码元字素的标签,而具有代表性的 ASCII 行为得以保留。
- 受控/非受控行为:不适用。
- 迁移决策:无;本草案不授权公共 API 变更。
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 为一条物理绘图边缘选择 Chart 提供的 x 或 y 比例尺。
- 生成、格式化、抽稀、截断、定位和隐藏刻度标签。
- 渲染其可选的边缘线和可选向外刻度标记。
- 为刻度位置和可见性变化应用可选的过渡样式。
不拥有 / 非目标
- 数据、域、比例尺构建或绘图尺寸 — 由
component:Chart拥有。 - 网格线 — 由
component:ChartGrid拥有。 - 产品特定的单位、区域设置选择或通过
tickFormat提供的标签措辞 — 由产品调用点拥有。 - 独立图表数据替代方案 — 由
component:Chart及其周围的产品内容拥有。
公共概念¶
| 概念 | 闭合值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 物理边缘 | top、right、bottom、left |
选择绘图边缘、比例尺轴、变换和向外标签侧。 | 每个坐标轴必需。 | 无 | component:ChartAxis |
实验性 | 未知值会被 TypeScript 拒绝。 |
| 刻度目标 | 有限数值 | 向 d3 请求近似的连续比例尺刻度数量。 | 连续比例尺;同时配置自动格式化器。 | 5 |
component:ChartAxis |
实验性 | 负值/非有限值回退到 5;小数向下取整;值上限为 1000。 |
| 标签上限 | 数字或缺失 | 当生成的标签集合超出请求的上限时,均匀跳过标签。 | 所有比例尺。 | 根据可用空间自动设置 | component:ChartAxis |
实验性 | 超出预期正整数数量范围之外的值未作规定。 |
| 标签格式化器 | (value: unknown) => string 或缺失 |
替换 band 字符串或 d3 连续比例尺格式化器。 | 每个刻度。 | 适合比例尺的内置格式化器 | component:ChartAxis |
实验性 | 消费者格式化器抛出的异常会向上传播。 |
| 标签截断 | 正字符数或缺失 | 保留那么多用户感知的字符,然后追加省略号。 | 每个已格式化标签。 | 缺失 | component:ChartAxis |
实验性 | 零/省略时禁用截断;其他无效值未作规定。 |
| 边缘线 | 显示或隐藏 | 沿所选坐标轴边缘渲染一条线。 | 每个边缘;刻度标记强制启用。 | 仅对 bottom 显示 |
component:ChartAxis |
实验性 | 不适用。 |
| 刻度线 | 显示或隐藏 | 在每个可见刻度标签旁渲染一条向外垂直的标记。 | 每条边。 | 隐藏 | component:ChartAxis |
实验性 | 不适用。 |
| 刻度过渡 | 动画或即时 | 在比例尺变化期间对刻度变换和透明度进行动画处理。 | 生成的刻度。 | 动画 | component:ChartAxis |
实验性 | 不适用。 |
行为与布局契约¶
草稿需求会标明其依据,以免观察到的代码被误认为是有意设计。
| ID | 候选不变式 | 依据 | 草稿评审状态 |
|---|---|---|---|
| FR1 | 顶部或底部坐标轴 MUST 使用 Chart 的 x 比例尺;左侧或右侧坐标轴在存在分类 y 比例尺时 MUST 使用它,否则使用线性 y 比例尺。 | 实现、类型和聚焦测试 | 待验证 |
| FR2 | 连续刻度生成 MUST 在 d3 刻度生成及其默认格式化器中使用同一个经过清理的计数;带状比例尺 MUST 在抽稀之前使用其完整定义域。 | 实现 | 待验证 |
| FR3 | 提供的 tickFormat MUST 优先生效;否则连续比例尺使用 d3 格式化,带状值使用 String。 |
实现和聚焦测试 | 待验证 |
| FR4 | 显式 maxTicks MUST 优先于由尺寸推导出的上限。 |
实现和聚焦测试 | 待验证 |
| FR5 | 截断 MUST 保留完整的 Unicode 字素簇,同时保持文档所述的“内容计数加省略号”输出。 | 聚焦的红/绿测试和 Unicode Standard Annex #29 | 已确定 |
| FR6 | 自动水平密度 MUST 以用户感知的字符数而非 UTF-16 存储单元来估算格式化标签的长度。 | 聚焦的红/绿等价测试和 Unicode 分段 | 已确定 |
| FR7 | 底部 MUST 默认显示边缘线,其他边缘 MUST 默认隐藏它。showTicks MUST 强制启用边缘线,并为每个保留的刻度渲染一个标记。 |
实现、JSDoc、聚焦测试和 Storybook | 待验证 |
| FR8 | 底部和右侧坐标轴 MUST 平移到对应的绘图边缘。顶部和左侧保持在绘图原点。标签和刻度线从该物理边缘向外延伸。 | 实现和聚焦测试 | 待验证 |
| FR9 | 在正负混合的线性 y 定义域上,底部边缘线 MUST 与 y=0 对齐;分类 y 将其留在绘图边缘。 | 实现 | 待验证 |
| FR10 | 当 animated 为 true 时,刻度移动和可见性可以过渡;为 false 时 MUST 立即生效。更新期间,超出范围的刻度保持挂载状态且透明度为零。 |
实现和流式示例;动效意图尚未确定 | 人工决策 |
允许的变化¶
- AV1 — 刻度数。 d3 可以选择更接近的连续刻度数,而不是请求的数量。
- AV2 — 标签集合。 自动和显式的密度限制可以省略等距标签,同时保持其比例尺顺序。
- AV3 — 提供的文本。 产品调用点可以通过
tickFormat使用自己的单位和区域设置来格式化值。
代表性状态¶
| 状态 | 必需的不变式 | 允许的变化 |
|---|---|---|
| 底部分类轴 | 带状标签居中;默认显示边缘线。 | 自动密度可以省略标签。 |
| 顶部分类轴 | 带状标签在顶部边缘外侧渲染。 | 除非被请求,否则边缘线保持隐藏。 |
| 左侧连续轴 | d3 标签在左侧边缘外侧渲染。 | d3 选择合适的刻度值。 |
| 右侧连续轴 | 坐标轴平移到右侧边缘,标签在其外侧渲染。 | d3 选择合适的刻度值。 |
| 垂直分类型 | 行标签使用 yBandScale 并与条带中心对齐。 |
自动密度可能省略标签。 |
| 显式格式化 | 每个保留的标签都使用所提供的格式化器。 | 消费者自行决定措辞和单位。 |
| 截断的标签 | 完整的字素簇位于附加的省略号之前。 | 调用方选择内容字符限制。 |
| 显示刻度线 | 每个保留的标签都有一个向外的标记和一条边缘线。 | 边缘线可见性输入被并入此状态。 |
| 混合符号线性 y 数据 | 底部线条表示 y=0,而不是绘图边界。 | 精确像素位置依据所提供的域。 |
| 流式/变化的域 | 刻度位置和可见性更新;动画遵循 animated。 |
刻度标识依据原始值。 |
转换与优先级顺序¶
- ORD1 — 比例尺。 解析物理方向 → 选择 Chart 比例尺 → 生成并格式化每个刻度一次 → 推导出字素感知的密度上限 → 均匀过滤标签。
- ORD2 — 标签。 应用所提供的格式化器或比例尺默认值 → 截断时保留完整的字素簇 → 渲染结果。
- ORD3 — 边缘线。 解析位置默认值 → 应用
showAxisLine→ 当showTicks为真时强制显示线条。
性能与资源¶
- PR1 — 有界连续刻度。 清理机制将 d3 请求限制在 1000,因此消费者值无法分配无界刻度数组。
- PR2 — 派生刻度状态。 刻度生成和格式化保持渲染派生且已记忆化;每个生成的标签只格式化一次,并在密度和渲染之间共享;ChartAxis 不拥有任何监听器、观察器、定时器或持久资源。
无障碍契约¶
- AR1 — 可见文本完整性。 截断的刻度标签 MUST 在 Unicode 字素簇边界下保留完整的用户感知字符。
- AR2 — Chart 级替代内容。 ChartAxis 在 Chart 的命名图像内渲染。Chart 拥有无障碍图表名称和支持的小数据表;轴标签和指针内容不会取代该替代内容。
- AR3 — 嵌套轴语义缺口。 该实现当前输出一个带位置标签的
role="group"。该组是否应在 Chart 的role="img"之下被独立暴露和定位,仍未得到验证,需要所有者评审。
设计关系¶
| 解剖结构或状态 | 设计需求 | 表征权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 轴边缘线 | 在存在时确立物理绘图边缘的基准。 | 未定;未链接任何当前设计记录 | 支撑 | FR7, FR9 |
| 刻度线 | 将保留的标签与比例尺上的位置关联。 | 未定;未链接任何当前设计记录 | 支撑 | FR7 |
| 刻度标签 | 在绘图四周保留可读的值/类别文本。 | Unicode 字素边界确定文本完整性 | 支撑 | FR3, FR5, FR6, AR1 |
| 刻度过渡 | 在比例尺变化期间显示连续性。 | 未定;design:motion 仍处于草稿状态 |
支撑 | FR10 |
主题化解剖¶
{
"Axis edge line": {
"none": {
"reason": "unsettled: ChartAxis consumes semantic color tokens but no current component or family contract decides whether the line is a public theme target."
}
},
"Tick marks": {
"none": {
"reason": "unsettled: ChartAxis consumes semantic color tokens but no current component or family contract decides whether tick marks are a public theme target."
}
},
"Tick labels": {
"none": {
"reason": "unsettled: ChartAxis consumes semantic color tokens but no current component or family contract decides whether labels are a public theme target."
}
}
}
族与系统关系¶
- 当前没有族或设计记录管辖 ChartAxis。
architecture:component-test-sufficiency负责合理的公共状态划分、可观察的断言,以及先失败后成功的审计修复。architecture:component-theming-surface负责解剖结构到目标的映射安排;仅消费 token 本身并不会使 ChartAxis 被纳入公共组件主题化。spec:AST-002负责公共 API 准入,并禁止审计将新的公共选择偷偷带入修复中。spec:AST-029负责本次观察性回填、封闭证据接收、安全修复和 fail-closed 资格报告。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1, FR8 | ChartAxis.test.tsx;ChartAxis.stories.tsx |
上、右、下、左;带状和线性 | 边缘使用了错误的比例尺、变换或向外的标签侧。 | audit:ChartAxis/behavior-layout |
| FR2, FR3 | ChartAxis.test.tsx |
默认计数;band、linear 和自定义格式化 | 生成与格式化不一致,或提供的格式化器被忽略。 | audit:ChartAxis/behavior |
| FR4 | ChartAxis.test.tsx |
自动上限和显式 maxTicks |
显式上限不再优先于基于尺寸的抽稀。 | audit:ChartAxis/behavior |
| FR5, FR6, AR1 | 红-绿字素回归测试;密度测试;浏览器故事 | ASCII、emoji、旗帜和 ZWJ 标签;被截断的宽/窄绘图区 | 可见标签拆分字素,或感知宽度相等的标签保留了不同的刻度。 | audit:ChartAxis/i18n-testing |
| FR7 | ChartAxis.test.tsx;Axes & Grids Storybook fixture |
默认状态;请求线条;请求刻度 | 刻度标记丢失其边缘线,或线条默认值发生改变。 | audit:ChartAxis/behavior |
| FR9 | 源码审查;浏览器证据仍待确认 | 仅正值、仅负值、混合符号、y-band | 混合符号的零线移动到边缘,或分类轴穿过绘图区。 | audit:ChartAxis/behavior-design |
| FR10 | 流式故事;exact-head 浏览器证据仍待确认 | 动画、即时、进入/离开的刻度 | 禁用动画后仍保留过渡效果,或移动中的标签跳转到陈旧几何位置。 | audit:ChartAxis/design-testing |
| AR2, AR3 | 图表无障碍测试;axe 包;无障碍树审查 | 标题/副标题、小数据表、嵌套轴组 | 图表失去其替代文本,或未经审查的嵌套语义声明被当作事实。 | audit:ChartAxis/accessibility |
决策日志¶
无。本草案记录了观察到的行为和一处客观的 Unicode 修正;它不批准新的 ChartAxis 策略。
开放问题¶
- OQ1 — 轴语义。 ChartAxis 应继续作为 Chart 单个命名图像中的纯视觉内容,还是将每个轴暴露为独立本地化的无障碍组?(
human-api)
内容边界¶
本文件不重复使用方的 prop 表格/示例、当前审计结果、实施步骤或共享系统规则;它链接到各自的归属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx