跳转至

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