跳转至

CommandPaletteList 组件契约

契约速览

领域 契约
公共契约 CommandPaletteList 带有 label、children、ref、xstyle、className、style 以及根 DOM props:CommandPalette 渲染的命名结果 listbox,或独立的结果列表。
行为 根是一个 listbox,名称来自调用方的 aria-label,否则来自 label,再否则使用翻译后的默认值(当前调用方的 aria-label 是 FR2 缺口);在 CommandPalette 内部,只有存在可选结果时它才是一个 listbox,并携带查询字段所控制的上下文列表 ID。
最终用户影响 屏幕阅读器用户可从查询字段到达命名结果列表;溢出的结果在列表内部滚动,而不是让命令面板变大。
构建方影响 构建方显式的 aria-label 本意是为列表命名;但目前组件的名称会替换它(FR2 缺口)。
兼容性/就绪状态 记录已发布行为;无公开变更。存在两个实现缺口,列在“当前状态影响”下;一个所有者问题仍然开放。
评审检查 拒绝第二个列表 ID 所有者、可被调用方替换的 listbox 角色、无法到达根的调用方 aria-label、原生或样式输入被丢弃,或将列表目标移出滚动根节点的情况。
治理规则 architecture:public-component-api/INV5,INV6,INV8;architecture:component-theming-surface;WAI-ARIA 1.2 listbox。

本表是评审视图;下文正文为权威内容。

意图

CommandPaletteList 是命令面板的可滚动结果容器。在 CommandPalette 内部,它是查询字段所控制的 listbox。独立使用时,它在调用方提供的选项内容周围呈现一个命名的结果 listbox。

兼容性与迁移

  • 已发布默认值保留:yes
  • 兼容性类别:记录已发布行为;无公开变更
  • 受控/非受控行为:不适用;列表不持有状态
  • 迁移决策:无

使用方的迁移说明属于使用方文档和发布说明。

当前状态影响

  • 独立列表没有键盘模型。 独立列表公开一个没有所属键盘模型的选项 listbox,因此键盘用户无法在其选项中移动;WAI-ARIA 1.2 将 listbox 的键盘交互交给其所有者(AR3、OQ1)。
  • 列表会替换调用方的名称(FR2)。 使用方 props 在组件的可访问名称之前展开,因此构建方显式的 aria-label 永远不能为列表命名,而 architecture:public-component-api INV5 允许这样做。

所有权边界

拥有

  • listbox 根节点及其可访问名称:来自调用方的 aria-label,否则来自 label,再否则使用翻译后的默认值(FR2);在 CommandPalette 内部,当不存在可选结果时,二者一并移除。
  • 将 CommandPalette 上下文列表 ID 应用到根节点。
  • 根节点上的原生透传、ref 和样式输入组合。
  • 溢出子元素的块轴滚动,以及间距刻度 padding 和间隙。

不拥有 / 非目标

  • 列表 ID 生成、查询字段聚焦、活动后代、方向键导航、悬停高亮、Enter 选择、搜索,以及结果与空状态之间的选择 — 由 component:CommandPalette 所有。
  • 聚合 List 结构条目及其 command-palette-list 目标映射 — 由 component:CommandPalette 所有。
  • 选项语义、状态和激活;分组语义和标题 — 由 CommandPaletteItem 和 CommandPaletteGroup 所有。
  • 独立复合键盘模型;其方向仍为 OQ1。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
可访问名称 调用方 aria-label;调用方 label;翻译后的默认值 为结果 listbox 宣布的名称。 所有使用场景 @astryx.commandPalette.list.label(英文为 "Commands") component:CommandPaletteList 稳定 空的 label 会使 listbox 没有名称;调用方应提供真实名称。
列表标识 上下文列表 id;调用方 id CommandPalette 查询字段所引用的 DOM id。 CommandPalette 内部;独立使用 CommandPalette 内部使用上下文 id;独立使用时使用调用方 id component:CommandPalette 稳定 在 CommandPalette 内部,调用方 id 会被上下文 id 替换。

行为与布局契约

ID 不变式 依据
FR1 原生 props 和 ref 传递到 listbox 根节点,消费方的 className 和 style 与列表目标和基础样式合并。在 CommandPalette 内部,根节点 id 为上下文列表 id;独立使用时保留调用方的 id。 当前源代码和测试
FR2 独立使用时,以及在 CommandPalette 内部且至少存在一个可选结果时,根节点暴露 role=listbox,调用方的 role 不会替换它:在 CommandPalette 内部是因为复合语义由组件拥有并替换透传,正如 component:CommandPaletteInput AR3 所记录;独立使用时则依据本记录自身的规则,由调用方显式提供的 aria-label 命名,否则由 label 命名,否则使用翻译后的默认值(architecture:public-component-api INV5)。实现缺口:组件的名称会替换调用方的 aria-label(当前状态影响)。否则适用 AR4。 当前源代码和测试
FR3 在 CommandPalette 内部,查询字段的 aria-controls 引用 listbox id。 当前源代码和测试
FR4 根节点将子元素按单列布局,使用间距尺度的内边距和间隔,在 flex 父容器中增长,将高度上限设为父容器高度,并让溢出的子元素在自身内部滚动。 当前源代码

允许的变化

  • AV1 — 子元素。 条目、分组和空状态的数量、顺序和内容可以变化,而不会改变根节点,除非 AR4 另有说明。
  • AV2 — 布局。 消费方的 xstyle、class 和 style 可以调整根节点,而不会替换其 role、id 或目标。

代表性状态

状态 必需的不变式 允许的变化
独立结果 listbox 由调用方的 aria-label 命名,否则由 label 命名,否则使用翻译后的默认值(FR2 中关于 aria-label 的缺口)。 条目数量和分组。
CommandPalette 内部 根节点 id 等于查询字段的 aria-controls 值。 结果数量和分组。
溢出结果 结果在列表内部滚动,而不是超出容器继续增长。 容器和条目高度。
空结果面板 在 CommandPalette 内部且没有可选择结果时,根元素没有 role 或名称。 空消息或等待中的消息。

转换与优先级顺序

  • ORD1 — 根属性。 先使用消费者的原生 props,然后是组件自有的 id 和 listbox role;除非调用者提供自己的 aria-label,否则可访问名称会生效(FR2;目前它会替换调用者的 aria-label)。
  • ORD2 — 样式。 先是列表目标,然后是带有 xstyle 的基础样式,接着是消费者的 class,最后是消费者的 style。

性能与资源

  • PR1 — 渲染之外不执行额外工作。 列表不添加 state、effect、listener 或 observer;它仅在渲染期间读取 translation 和 CommandPalette context。

可访问性契约

  • AR1 — 名称。 listbox 将调用者显式提供的 aria-label,否则使用 label,再否则使用翻译后的默认值,作为其可访问名称(FR2 缺口)。
  • AR2 — 关系。 在 CommandPalette 内部,查询字段通过其 id 控制 listbox;CommandPalette 在其 combobox 模型下拥有焦点和键盘导航。
  • AR3 — 独立缺口。 独立列表暴露一个包含选项但没有所属键盘模型的 listbox(当前状态影响;OQ1)。
  • AR4 — 空内容。 在 CommandPalette 内部,当不存在可选择结果时,根元素没有 role 也没有可访问名称,因此屏幕阅读器会将空消息或等待中的消息作为纯文本内容,并且不会遇到空的弹出框;WAI-ARIA 1.2 要求 listbox 拥有选项。独立列表仍然是 listbox,其选项由调用者提供。

设计关系

结构或状态 设计需求 呈现权威 层级角色 组件契约
List 在一个可滚动列中呈现结果选项,并使用间距尺度的 padding 和 gap。 当前源码与公开文档 支持性 FR1、FR4

族系与系统关系

  • component:CommandPalette 负责 list-id 生成、键盘导航、悬停高亮、聚合结构以及 command-palette-list 目标映射;该组件应用 id 并绘制 List。
  • architecture:public-component-api 负责原生透传、样式组合和 refs。
  • architecture:component-theming-surface 负责目标限定和聚合 List 结构映射。
  • architecture:component-test-sufficiency 负责下方验证映射背后的证据规则。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1 CommandPaletteList.test.tsx 带有 ref、class 和 style 的独立根元素 断开 ref,或丢弃消费者的 class 或列表目标,会导致聚焦的 DOM 断言失败。 audit:CommandPaletteList/api
FR2、AR1、AR4 CommandPaletteList.test.tsx 默认 label 和调用者提供的 label;有结果和无结果的 CommandPalette 移除 role 或名称,或在空的 CommandPalette 表面上保留它们,会导致 role 和名称断言失败。缺口:没有测试覆盖调用者提供的 role 或 aria-label。 audit:CommandPaletteList/a11y
FR3、AR2 CommandPaletteList.test.tsx、CommandPalette.test.tsx 内联 CommandPalette 丢弃 context id 会破坏查询字段关系断言。 audit:CommandPaletteList/a11y
FR4 themingTargets.test.ts;已验证 RTL 不适用 独立列表 丢失目标会导致目标清单失败。 audit:CommandPaletteList/theming
AR3 源码审查 独立列表 缺口:不存在可测试的独立键盘模型(OQ1)。 audit:CommandPaletteList/accessibility
PR1 源码审查 所有状态 缺口:如果列表添加 state、effect、listener 或 observer,没有自动化检查会失败。 audit:CommandPaletteList/behavior

从源码中读取,目前尚无聚焦测试:

  • FR4:单列布局、间距、高度上限和内部滚动。
  • PR1:没有 state、Effect、listener 或 observer。

决策日志

未记录任何组件本地决策。

开放问题

  • OQ1 — CommandPaletteList 应暴露哪种独立键盘契约? (human-api) 独立列表暴露一个包含选项的 listbox,但不拥有键盘模型。需要决定:是由公共复合属主提供该模型,还是独立组合承担不同角色,抑或独立使用仍保持仅指针的呈现。

内容边界

本文件不重复消费方 prop 表格/示例、实现步骤或家族/系统规则。它链接到各自的属主。

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