跳转至

ChartSwatch 组件契约

契约速览

领域 契约
公共契约 无 API 形态或默认值更改。本草案记录当前由调用方拥有的颜色、方形/线形形状,以及导出的系列类型映射工具函数。
行为 省略 variant 时渲染方形;显式传入 line 时渲染短笔画;swatchVariantForType 将 bar 映射为方形,将所有其他或省略的类型映射为线形。
终端用户影响 图表读者在可见系列标签旁看到相同的装饰性标记形状颜色键;本次审计不改变任何渲染行为。
构建者影响 现有调用点保持有效,并为随组件发布的 props、默认值、组合和可访问性边界补充消费者文档。
兼容性/就绪状态 该包仍仅限 canary。本观察性草案不具备权威性;公共工具函数名称及未来的主题化可达性仍是未解决的所有者决策。
审查检查 拒绝更改后的默认值或类型映射、丢失的装饰语义、将几何漂移表述为策略的做法,或声称仅凭颜色即可始终识别系列的主张。
治理规则 spec:AST-029/FR3–FR7、architecture:component-test-sufficiency/INV1–INV11、architecture:component-theming-surface/INV1–INV11 以及 spec:AST-002/FR17。

此表是审查投影;以下正文具有权威性。

意图

ChartSwatch 绘制一个紧凑的装饰性颜色键,在视觉上将系列标签与图表标记连接起来。它拥有方形和线形形状,以及当前从系列类型到这些形状的映射。图例、工具提示、图表或产品调用点拥有可见的系列名称及其周边关系。

兼容性与迁移

  • 已发布默认值保留情况:在 canary 层面为是;该包尚无稳定版本。
  • 兼容性类别:无公共 API、默认值或渲染行为更改。
  • 受控/非受控行为:不适用。
  • 迁移决策:无;本草案不授权对公共工具函数进行重命名或移除。

消费者迁移说明应归入消费者文档和发布说明。

所有权边界

拥有

  • 将调用方拥有的一种颜色绘制为紧凑的方形或线形。
  • 保持色块对辅助技术为装饰性。
  • 将 bar 系列类型映射为方形,将所有其他或省略的类型映射为线形。

不拥有 / 非目标

  • 选择、验证或调整图表调色板——由图表和产品调用点拥有。
  • 命名系列或提供可访问的图表替代方案——由周围的图例、工具提示、Chart 或产品调用点拥有。
  • 确立仅凭颜色即可在绘制出的图表及其周边界面中区分系列的能力。
  • 交互、选择、过滤、可见性或工具提示行为。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
系列颜色 调用方拥有的 CSS 颜色字符串 为装饰性标记着色。 每个 ChartSwatch 必填 产品调用点 实验性 无效的 CSS 颜色语法可能使色块无填充色。
色块形状 square、line 在视觉上呼应柱状或非柱状图表标记。 每个 ChartSwatch square component:ChartSwatch 实验性 由导出的 TypeScript 联合类型封闭。
系列类型映射 bar;所有其他字符串;省略 将系列类型转换为组件支持的两种形状。 导出的工具函数 line component:ChartSwatch 实验性 未知类型和省略的类型使用 line 形状。
辅助技术参与 装饰性,对辅助技术隐藏 将含义交由周围的可见文本承载。 每个 ChartSwatch 内置 component:ChartSwatch 实验性 不可配置。

行为与布局契约

草稿需求标明其依据,以免将观察到的代码误认为有意决策。

ID 候选不变量 依据 草案审查状态
FR1 ChartSwatch 在省略 variant 时 MUST 渲染一个装饰元素,并 MUST 使用 square。 实现、针对性测试和浏览器传感器 待验证
FR2 Square 目前 MUST 渲染为 8×8 的标记,圆角为 2,内联边距为 1;line 目前 MUST 渲染为 10×3 的标记,圆角为 1.5。 实现和已确认的浏览器矩阵 待验证
FR3 渲染的绘制 MUST 遵循调用方提供的 color,不自行选择或调整调色板。 实现、针对性测试和浏览器传感器 验证
FR4 色块 MUST 对辅助技术保持隐藏;周围内容 MUST 提供可见且可访问的系列含义。 实现、针对性测试、针对性的 axe 和浏览器 验证
FR5 swatchVariantForType 仅在 bar 时 MUST 返回 square,对于所有其他字符串和 undefined MUST 返回 line。 实现和针对性测试 验证
FR6 浅色、深色、窄视口和粗指针媒体 MUST NOT 改变组件自有的形状契约,也不得引入水平视口溢出。 已收讫的浏览器矩阵 验证

允许的变化

  • AV1 — 系列绘制。 任何有效的调用方自有 CSS 颜色都可以绘制任一形状。
  • AV2 — 周围布局。 图例、工具提示或自定义调用点可以将色块放置在任意位置,只要保留其与可见系列标签的关联。

代表性状态

状态 必需不变量 允许的变化
省略 / 方形 方形几何和装饰性语义保持不变。 调用方颜色和周围位置可以变化。
线形 线形几何和装饰性语义保持不变。 调用方颜色和周围位置可以变化。
bar 映射 工具函数返回 square。 源系列定义可以携带其他字段。
非 bar / 省略映射 工具函数返回 line。 未知的和未来的非 bar 类型字符串使用回退值。
浅色 / 深色 形状和提供的绘制保持不变。 周围表面遵循其当前激活的主题。
窄视口 / 粗指针 不添加组件自有的溢出或交互。 周围布局可以换行或重新定位色块。

转换与优先级顺序

  • ORD1 — 渲染。 省略时应用默认变体 → 选择方形或线形几何 → 使用调用方颜色绘制 → 将结果元素对辅助技术隐藏。
  • ORD2 — 系列映射。 将系列类型与 bar 比较 → 对精确匹配返回 square → 否则返回 line。

性能与资源

  • PR1 — 无持久资源。 渲染、重新渲染和卸载 ChartSwatch MUST NOT 创建或保留监听器、观察器、计时器、请求、订阅或其他持久浏览器资源,并且 MUST 不需要使用者进行清理。

无障碍契约

  • AR1 — 装饰性标记。 ChartSwatch 对辅助技术保持隐藏,因为其周围可见的系列标签提供了含义。
  • AR2 — 有意义的上下文。 独立的调用点将色块与可见文本配对;色块不能替代 Chart 的可访问名称、等效数据视图或摘要。
  • AR3 — 系列区分。 关于同形状系列是否需要额外关联线索的证据,必须覆盖组合后的图表及其标签,而不是孤立的装饰性色块。

设计关系

结构或状态 设计需求 表示权威 层级角色 组件契约
系列色块 呼应图表标记,同时保持对辅助技术(AT)的装饰性。 未定;当前没有关联的设计记录 支撑 FR1–FR6, AR1–AR3
方形形状 表示当前的 bar 系列映射。 观察到的实现 支撑 FR1–FR2, FR5
线形形状 表示当前的非 bar 和回退系列映射。 观察到的实现 支撑 FR2, FR5

主题化结构

{
  "Series swatch": {
    "none": {
      "reason": "unsettled: caller-owned color and fixed component geometry currently paint the swatch without a public theme target; this draft does not decide future reachability."
    }
  }
}

ChartSwatch 是可见的绘制者,但不暴露当前的公共主题目标。主题是否应获得一个稳定目标,仍是所有者的决定。

家族与系统关系

  • 当前没有家族或设计记录管辖 ChartSwatch。
  • architecture:component-test-sufficiency 负责合理的公共状态划分、可观察断言和审计证据质量。
  • architecture:component-theming-surface 负责结构到目标的处置;本草案记录当前的缺失,而不决定未来的可主题化性。
  • architecture:knowledge-contracts 将消费者语法保存在 ChartSwatch.doc.mjs 中,并将观察到的行为保存在本草案组件记录中。
  • spec:AST-002/FR17 负责未解决的公共工具函数命名问题。
  • spec:AST-029 负责本次观察性回填、关闭的证据收讫、安全修复和 fail-closed 资格报告。

验证映射表

契约 验证 代表性状态 变更或失败预期 审计章节
FR1–FR3 ChartSwatch.test.tsx;已验证的浏览器矩阵 省略、方形、线条、六种颜色、浅色、深色 默认、几何形状或调用方绘制的更改没有可见证据。 audit:ChartSwatch/behavior-design
FR4 聚焦的 DOM 断言;聚焦的 axe 检查;浏览器传感器 方形、线条、浅色、深色 色块进入无障碍树,或周围含义被赋予该标记。 audit:ChartSwatch/accessibility
FR5 ChartSwatch.test.tsx 条形、线条、圆点、面积、未知、省略 条形失去方形,或其他类型获得方形。 audit:ChartSwatch/public-utility-behavior
FR6 已验证的 Storybook 浏览器矩阵 1280 px、320 px、粗指针、浅色、深色 形状改变、出现溢出,或组件获得依赖媒体的行为。 audit:ChartSwatch/responsive-rendered-design
AR1–AR3 聚焦的 axe 检查;ChartLegend 和 ChartTooltip 组合审查 独立使用和组合使用 装饰性语义丢失,或使用孤立证据来决定图表关联。 audit:ChartSwatch/accessibility-composition

决策日志

无。本草案仅记录观察到的行为和证据缺口。

开放问题

  • OQ1 — 公共工具名称。 系列类型映射是否应保持公开?如果是,什么以动词开头的名称和兼容路径能够满足 spec:AST-002/FR17?(human-api)
  • OQ2 — 色块主题可达性。 ChartSwatch 是否应暴露公共主题目标,还是其绘制和几何形状应保持由调用方/组件所有?(human-api)
  • OQ3 — 组合系列关联。 包含多个形状相同系列的组合图表是否需要额外的关联提示,以及该提示由哪一层负责?(human-design)

内容边界

本文件不重复使用方属性表/示例、当前审计结果、实施步骤或共享系统规则。它链接到相应内容的所有者。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx