ChartTooltip 组件契约¶
契约概览¶
| 区域 | 契约 |
|---|---|
| 公共契约 | 无 API 形状或默认值更改。本草案记录了已交付的分组内容、指示器、圆点、自定义渲染和定位表面。 |
| 行为 | 最近的指针 x 选择一个数据项;卡片、启用的 SVG 指示器和符合条件的圆点会同步更新。当前一个和后一个选择都能产生内容时,可见的 Layer 保持打开。卡片保持在最近的图表 HTML 作用域内,并使用 Layer 固定模式。 |
| 终端用户影响 | 指针用户继续获得图表的嵌套 Theme/MediaTheme 处理;受支持的浏览器还能在裁剪区域或模态顶层 UI 之上保留细节,而精简的降级方案保持普通可见性。 |
| 构建者影响 | 无。Chart tooltip、tooltip 配置对象以及直接组合 ChartTooltip 的方式继续使用相同的 props 和默认值。 |
| 兼容性/就绪状态 | Canary 兼容的行为修复。本观察性草案不具备权威性;定位含义、焦点关联和未来的主题化目标仍是未决的所有者选择。 |
| 审查检查项 | 拒绝 document-body 宿主、过早的自定义内容打开、API/默认值更改、指针清理丢失、自定义渲染重复调用、无效 SVG 坐标,或任何声称未决问题已解决的说法。 |
| 治理规则 | spec:AST-027/FR7–FR8、architecture:layer-runtime/INV1–INV3、architecture:theme-application/INV1–INV3、spec:AST-013/FR7–FR10、architecture:component-test-sufficiency/INV1–INV11 以及 spec:AST-029/DEC-4。 |
此表为审查概览;以下正文才是权威内容。
意图¶
ChartTooltip 为最接近指针的图表数据项渲染补充的分组值。它负责指针选中的卡片、其视口定位、可选的十字准线或带状高亮,以及符合条件的悬停圆点。Chart 负责数据、比例尺、绘图几何、指针分发、无障碍命名,以及其受支持的等效数据视图。
兼容性与迁移¶
- 已发布的默认值保持不变:在 canary 层面为是;该包尚无稳定版本。
- 兼容性类别:无公共 API 或默认值更改;卡片从带有页面级 z-index 的固定 body 门户迁移到共享的固定 Layer 运行时。
- 受控/非受控行为:不适用;Chart 的指针流拥有活动索引。
- 迁移决策:无;
spec:AST-027/FR7–FR8已要求进行 Layer 迁移。
消费者迁移说明应放在消费者文档与发布说明中。
所有权边界¶
拥有
- 从最近的图表指针事件中选择 tooltip 内容。
- 为悬停的数据项派生有序的可见系列行。
- 渲染默认卡片或调用方提供的卡片内容。
- 将 Layer 托管在最近的图表 HTML 容器之下,使嵌套的 Theme 与 MediaTheme 作用域保持继承。
- 通过 Layer 固定模式定位卡片坐标并执行视口钳制;自定义渲染器负责其内容尺寸。
- 渲染当前的十字准线或条形带指示器以及符合条件的悬停圆点。
- 在组件卸载时取消订阅 Chart 的指针流。
不拥有 / 非目标
- Chart 数据、比例尺、绘图几何或指针事件生成——由
component:Chart拥有。 - 产品特定的值格式化、系列标签和颜色——由产品调用点和系列定义拥有。
- 图表的无障碍名称、隐藏数据表、摘要或其他等效的非指针数据视图——由
component:Chart和产品调用点拥有。 - 新的可聚焦数据点模型或 tooltip 触发关系;这些需要根据
spec:AST-002和spec:AST-003由所有者作出决定。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 系列来源 | 调用方数组或省略 | 提供行标签、值、颜色、标记类型和悬停圆点资格。 | 每个 ChartTooltip | 空数组 | 产品调用点 | 实验性 | 工具系列和未解析系列会被过滤;缺失和非有限的行值会被保留。 |
| 卡片内容 | 默认主体;自定义 React 节点;自定义 null |
显示分组详情,或仅抑制卡片本身。 | 悬停数据项 | 默认分组内容 | component:ChartTooltip |
实验性 | 自定义 null 永不打开 Layer,并保留已启用的 SVG 指示器和数据点。 |
| 悬停指示器 | 启用或禁用;条形带或垂直十字准线 | 在绘图区内标记活动 x 位置。 | 有效悬停数据项 | 启用 | component:ChartTooltip |
实验性 | 无效或非有限的图表坐标会抑制该标记。 |
| 悬停数据点 | 启用或禁用;每个符合条件的已解析非条形序列一个 | 在活动索引处标记每个符合条件的序列点。 | 有效且有限的已解析点 | 启用 | component:ChartTooltip |
实验性 | 缺失和非有限的已解析点会被跳过。 |
| 卡片放置 | auto、right、left、top |
根据悬停的 x 坐标和当前的垂直参考线选择水平放置位置。 | 可见卡片 | auto |
component:ChartTooltip |
实验性 | 未知值会被 TypeScript 拒绝。 |
| Layer 宿主 | 最近的图表 HTML 容器 | 在 SVG 之外保持合法 HTML 的同时,保留最近的 Theme 和 MediaTheme CSS 作用域。 | 浏览器渲染 | 最近的图表容器 | architecture:layer-runtime;architecture:theme-application |
已定型 | 文档 body 宿主会丢失嵌套 CSS 作用域。 |
| Layer 可见性 | 关闭;浏览器 top-layer 打开;降级回退可见 | 受支持时使用原生 top-layer 堆叠;否则保持普通卡片可见性。 | 浏览器渲染 | 关闭 | architecture:layer-runtime |
已定型 | 降级回退不声称具有 top-layer 堆叠能力。 |
行为与布局契约¶
草案需求会标明其依据,以免所观察到的代码被误认为有意设计。current 契约不包含未解决的行。
| ID | 候选不变量 | 依据 | 草案审查状态 |
|---|---|---|---|
| FR1 | Chart 的 tooltip 简写 MUST 注入图表序列;当前直接组合要求调用方在需要行和数据点时传入同一个序列数组。 |
实现、类型、文档和聚焦测试 | 待验证 |
| FR2 | 最近的指针事件 MUST 选择一个数据索引;从有内容到有内容的变化 MUST 替换内容而不关闭已打开的 Layer。离开图表、选择陈旧索引或选择被自定义 null 抑制的内容时,MUST 保持 Layer 关闭或隐藏已打开的卡片,且后续的有内容索引 MUST 能再次显示它。 |
spec:AST-013/FR8–FR10;architecture:component-test-sufficiency/INV4–INV5;实现以及聚焦/浏览器测试 |
待验证 |
| FR3 | 默认卡片 MUST 显示 x 值,并且每个可见的已解析序列要么显示一个裸值,要么显示一个带标签的行。自定义渲染器 MUST 在每次渲染时接收 x 值和有序行,并且 MAY 返回 null 而不打开 Layer。 |
实现和聚焦测试 | 待验证 |
| FR4 | 启用的指示器 MUST 在带刻度尺上为条形系列渲染带状高亮,否则渲染垂直十字线。启用的点 MUST 排除条形以及非有限或缺失的已解析点。 | 实现与定向测试 | 待验证 |
| FR5 | auto 目前从右侧开始,在内联溢出时翻转到左侧;显式的 right、left 和 top 使用悬停的 x 坐标,而每种模式目前都以绘图顶部作为垂直原点并钳制生成的坐标。自定义渲染内容保持其调用方拥有的尺寸。 |
实现与部分定向测试 | 人工决策 |
| FR6 | 宿主 MUST 保持在最近的图表 HTML 容器之下,以保留 Theme 和 MediaTheme 作用域,并且 MUST 使用 useLayer({mode: 'fixed'});受支持的浏览器获得原生顶层提升,而没有 Popover API 的浏览器则使用 Layer 的降低可见性回退。文档主体宿主或数值 z-index 不能替代。 |
architecture:theme-application/INV1–INV3;spec:AST-027/FR7–FR8;architecture:layer-runtime/INV1–INV3;spec:AST-013/FR7–FR8 |
已定 |
| FR7 | 组件 MUST 按每个活动回调身份订阅一次,并且 MUST 在卸载时释放该订阅。 | 实现与定向测试 | 待验证 |
| FR8 | 服务端渲染 MUST 省略仅浏览器层,且不读取 portal 目标;SVG 指示器保持由渲染派生。 | spec:AST-013/FR9–FR10;实现与定向服务端渲染测试 |
待验证 |
允许的变体¶
- AV1 — 系列内容。 调用方可通过现有公共输入选择标签、颜色、顺序、值以及自定义渲染的卡片内容。
- AV2 — 图表几何。 图表可更改绘图尺寸和刻度输出;ChartTooltip 跟随提供的指针坐标并钳制其卡片坐标。自定义渲染器拥有其内容尺寸。
- AV3 — 补充表面。 当图表的非指针呈现已经提供足够细节时,产品可省略 tooltip。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 展示内容过渡 | 卡片内容和位置在同一个 Layer 宿主持续打开期间更新。 | 所选值和最终坐标会变化。 |
| 初始 / 指针离开 | 卡片已关闭,且不暴露任何过期的卡片内容。 | SVG 指示器不存在。 |
| 过期索引 | Layer 不会为当前数据中不存在的指针索引打开。 | 先前有效的内容可能已经关闭。 |
| 单一系列 | 卡片显示 x 值和一个值。 | 调用方的标签、颜色和值可变。 |
| 多个系列 | 卡片保留派生的可见系列顺序,并为每行添加标签。 | 行的数量和类型可变。 |
| 自定义内容 | 渲染器接收当前 x 值和行。 | 可返回任何非交互式 React 内容。 |
自定义 null |
启用的绘图指示器存在时,Layer 永不打开。 | 指示器和点选项保持可独立配置。 |
| 带刻度上的条形 | 带状高亮替代十字线;条形不接收悬停点。 | 带几何形状遵循刻度。 |
| 线、面积或点 | 十字准线和符合条件的有限悬停点跟随所选索引。 | 系列绘制和解析的坐标可变。 |
| 嵌套主题 / MediaTheme | 图层宿主保持为最近活动作用域的 DOM 后代。 | 主题名称和媒体模式可变。 |
| 裁剪或模态组合 | 图层宿主是位于裁剪和顶层对等元素之上的打开的原生 popover。 | 周围的裁剪和模态几何形状可变。 |
| Popover 降级回退 | 宿主初始隐藏,在有效悬停时打开,并在没有虚假可见状态的情况下再次隐藏。 | 原生顶层增强不可用。 |
| 服务端渲染 | 不发出任何 portal 或浏览器图层。 | 渲染的 SVG 片段在没有指针状态时可能为空。 |
转换与优先级顺序¶
- ORD1 — 指针选择。 接收 Chart 指针事件 → 解析最近的数据索引 → 派生数据项和行 → 解析自定义或默认卡片内容 → 当后续选择也产生内容时保持图层打开,否则在内容缺失时保持图层关闭,在内容存在时显示它 → 测量最终卡片几何形状并约束其坐标。
- ORD2 — 指示器选择。 检查
hoverIndicator→ 当任何条形使用带区比例尺时优先采用条形带表示 → 否则解析十字准线的 x → 抑制非有限输出。 - ORD3 — 点选择。 检查
showHoverDots→ 保留符合条件的非条形系列 → 找到当前已解析的点 → 抑制缺失或非有限的点。
性能与资源¶
- PR1 — 指针渲染边界。 指针在单个已解析数据索引内移动时,如果计算出的卡片位置未改变,则不应强制 React 提交。
- PR2 — 订阅所有权。 ChartTooltip 恰好拥有一个当前指针订阅,并且 MUST 在订阅身份发生变化或组件卸载时释放它。
- PR3 — 渲染回调。 自定义卡片渲染器 MUST NOT 仅为了决定可见性而在同一次 React 渲染中被调用两次。
无障碍契约¶
- AR1 — 补充信息。 仅 Tooltip 内容不会替代 Chart 的可访问名称、受支持的隐藏数据表、摘要或另一个完整数据视图。
- AR2 — 当前语义。 卡片当前公开
role="tooltip",并且保持不可交互。本草案不断言仅指针触发路径满足 WAI-ARIA tooltip 模式。 - AR3 — 关联缺口。 键盘暴露和
aria-describedby所有者仍未解决,因为 Chart 没有可聚焦的数据点触发器。未经所有者批准,审计 MUST NOT 虚构该交互或 API。
设计关系¶
| 结构或状态 | 设计要求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 图层宿主 | 保持在最近的图表 HTML 作用域之下;在可用时使用原生顶层堆叠,并在降级回退中保持普通可见性。 | architecture:theme-application/INV1–INV3; spec:AST-027/FR7–FR8; spec:AST-013/FR7–FR8 |
浮层 | FR6 |
| Tooltip 卡片 | 呈现分组补充细节,且不接收指针交互。 | 未定;当前未链接任何设计记录 | 辅助 | FR3, AR1–AR3 |
| 系列行 | 将一个可见标签和值与其装饰性系列色板关联。 | 观察到的实现 | 辅助 | FR3 |
| 悬停指示器 | 标记活动 x 区域,而不改变图表的数据或可访问名称。 | 未定;当前未链接任何设计记录 | 辅助 | FR4 |
| 悬停点 | 在所选索引处回显符合条件的系列点。 | 未定;当前未链接任何设计记录 | 辅助 | FR4 |
主题结构¶
{
"Layer host": {
"none": {
"reason": "unsettled: the host paints the card with semantic tokens but no current contract decides whether ChartTooltip needs a public target."
}
},
"Tooltip card": {
"none": {
"reason": "intentional: the semantic role-only child adds no component-owned paint; the Layer host owns the card chrome."
}
},
"Series row": {
"none": {
"reason": "intentional: shared Layout, Text, and ChartSwatch components own the rendered row surfaces."
}
},
"Hover indicator": {
"none": {
"reason": "unsettled: semantic tokens paint the current SVG mark but no current contract selects public theme reachability."
}
},
"Hover dot": {
"none": {
"reason": "unsettled: series-owned paint and current fixed geometry have no approved public theme target."
}
}
}
组件家族与系统关系¶
- 目前没有任何组件家族或设计记录对 ChartTooltip 进行约束。
architecture:layer-runtime与spec:AST-027/FR7–FR8要求在受支持处使用固定的 Layer 组合和浏览器 top-layer 提升。architecture:theme-application/INV1–INV3要求宿主保持在最近的 Theme 和 MediaTheme CSS 作用域内,而不是 portal 到 document body。architecture:component-test-sufficiency负责合理的公共状态划分和可观察断言。architecture:component-theming-surface负责 anatomy 到主题目标(anatomy-to-target)的配置;本草案记录当前缺失这一配置的现状,而不决定未来的可主题化能力。architecture:knowledge-contracts将消费者语法保留在ChartTooltip.doc.mjs中,将观察到的行为保留在本草案组件记录中。spec:AST-013/FR7–FR10负责精简的 Popover 回退、服务端渲染边界和真实浏览器证据要求。spec:AST-002负责任何未来的公共 API 或兼容性决策。spec:AST-003负责任何未来的被动覆盖层(passive-overlay)协调模型。spec:AST-029/DEC-4负责先红后绿(red-before-green)行为修复;更广泛的 Night Watch 契约负责此观察性回填、有限证据清单、客观修复和 fail-closed 就绪报告。
验证映射¶
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR3–FR4 | ChartTooltip.test.tsx;Tooltip Storybook fixture |
single、multi、custom、null、stale 索引、bar、line、缺失值 | stale/custom-null 状态会打开 Layer、公共选项会改变输出,或缺失/非有限点会泄漏无效 SVG。 | audit:ChartTooltip/behavior |
| FR2 | 当前内容(present-content)连续性专项测试;modal Storybook play 断言 | initial open、present→present、leave→reopen、open→stale→valid、content→custom-null→content | 当前内容变化会关闭/重新打开 Layer、保留旧内容,或在关闭状态后阻止后续当前内容显示。 | audit:ChartTooltip/behavior |
| FR5 | placement 专项测试;源码审查 | right;其他模式仍为空白 | 定位在缺少负责人裁定或每个公共值的证据时发生变化。 | audit:ChartTooltip/api-behavior |
| FR6 | 红/绿(red/green)Layer 宿主、嵌套主题和精简回退测试;modal Storybook play 断言 | nested Theme/MediaTheme、closed、fallback open/closed、native modal hover | document-body 宿主丢失本地主题作用域、原生 top-layer 状态缺失,或回退可见性为 false。 | audit:ChartTooltip/layering |
| FR7 | 生命周期专项测试 | mount and unmount | 卸载后仍有 pointer 监听器残留。 | audit:ChartTooltip/code-health |
| FR8 | renderToString 专项测试 |
server render | 服务端求值读取 document,或输出仅浏览器端(browser-only)卡片。 |
audit:ChartTooltip/runtime |
| AR1–AR3 | Chart 无障碍测试;聚焦 axe 扫描;负责人审查待定 | small-data 替代方案和悬停卡片 | Tooltip 内容成为唯一数据路径,或草案语义被视为策略。 | audit:ChartTooltip/accessibility |
决策日志¶
无。本草案记录观察到的行为,以及当前共享权威规范已要求的 Layer 与主题局部性(theme-locality)修正;它不批准新的 ChartTooltip 策略。
未决问题¶
- OQ1 — Placement 含义。
top、left、right和auto是否应相对于悬停点在两个轴向上的位置,还是公共描述应指明当前绘图区顶部(plot-top)的垂直原点?(human-api) - OQ2 — 键盘与 tooltip 关联。 Chart 是否应暴露可聚焦的数据点触发器(trigger)和
aria-describedby关系,还是此表面应采用不同语义,同时数据表继续作为键盘/辅助技术(AT)路径?(human-api) - OQ3 — 主题化可达性。 Layer 宿主或任何 SVG 指示器是否应成为稳定的公共主题目标?(
human-api)
内容边界¶
本文件不重复消费者 prop 表/示例、当前审计结果、实施步骤或共享系统规则。它会链接到这些内容的负责人。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx