跳转至

调用方渲染的浮层触发器系统规范

{
  "scope": "global",
  "triggers": {
    "public-api": ["FR1", "FR2", "FR3", "FR7", "FR8", "DEC-1", "DEC-4"],
    "accessibility": ["AR1", "AR2", "AR3", "AR4"],
    "styling": ["FR4", "FR5", "FR6", "DEC-2", "DEC-3"]
  }
}

契约概览

Area Contract
公共契约 每种组件都采用同一种形态:一个 render prop,让调用方提供打开其浮层的控件。组件以单个 props 对象调用调用方的函数,并直接渲染其返回的内容,不做额外包裹。该 props 对象的类型已导出。该 prop 名为 renderTrigger(DEC-5)。现有已发布的 prop 不发生任何变更。
行为 调用方拥有元素本身;组件拥有其交回的行为。将给定 props 展开到元素上就是全部集成工作。若同时提供了内置控件与 render prop,则以调用方的控件为准,并触发一条开发警告。悬停与按下样式仍由调用方的 CSS 负责;打开状态通过 aria-expanded 传递给 CSS。
终端用户影响 操作图标按钮、chip、头像或列表行(用于打开菜单或选择器)的用户,将获得系统提供的键盘打开方式、按压模型、焦点返回和 disclosure 语义,而不是手写副本所保留的那些内容。对于保留内置控件的调用方,一切不变。
构建者影响 提供控件的构建者只需渲染一个元素,并将一个对象展开到该元素上;无需 ref 管道,也无需重新推导 ARIA。调用方新增的责任:控件自身的悬停、按下和焦点绘制,以及以 aria-expanded 为键的打开状态样式。若控件无法获得焦点,则需要使用组件文档中记录的替代路径(AR4)。
兼容性与就绪状态 增量式:render prop 默认不存在,所有当前内置控件的路径均保持不变。权威性:current;cixzhang 于 2026-10-02 批准了本条记录。仍有一个 owner 问题未决(OQ3),它不会改变 FR1–FR8 或 AR1–AR4。关于焦点环以及浮层相对于调用方控件位置的真实浏览器证据尚未记录。
审查检查 应拒绝以下情况:调用方提供的控件被渲染在组件拥有的 <button>、链接或 tabindex 宿主内部;调用方的控件被包裹在一个无盒模型元素中,组件随后基于该元素进行锚定或绘制焦点;交回的 props 中缺少 disclosure ARIA;组件将悬停或按下样式写到它并未渲染的元素上;两个控件同时渲染,或其中一个被静默丢弃。
治理规则 准入及每个输入单一职责遵循 spec:AST-002 FR4、FR15、FR16 和 spec:AST-002/DEC-1;共享命名与透传语法遵循 architecture:public-component-api INV2、INV3、INV5;将浮层锚定到触发器遵循 architecture:layer-runtime;关闭顺序遵循 family:overlay-dismissal,此处不作更改。

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

意图

菜单或选择器往往需要从设计系统并不拥有的控件打开:工具栏中的图标按钮、头像、chip,或列表行内本身是链接的字形。Astryx 组件会绘制自己的控件,因此处于这种位置的构建者只能手写浮层——锚定、关闭、焦点返回、键盘打开、ARIA——而每一份手写副本都会逐渐偏离。产品的使用者于是会遇到不同的键盘路径,以及手写副本所保留下来的任意可访问性。

本条记录对该情形给出一个跨组件的统一答案:调用方渲染控件,组件交回让控件正常工作的 props。 它规定了形态、交回的 props 必须携带的内容、样式边界的划分,以及该安排必须保持的可访问性。

四份组件草案记录各自正在为这同一事实撰写自己的决定。一个事实只有一个所有者(architecture:knowledge-contracts INV2),因此决定归于此文,那些记录引用它即可。

所有权边界

拥有

  • 组件在调用方提供打开组件浮层的控件时所采用的形态:是一个 render prop,而不是内容插槽,也不是包装器。
  • 交还的 props 对象必须携带什么,以及展开它即已足够。
  • 调用方元素与组件之间的样式边界落在何处,以及打开状态如何到达调用方的 CSS。
  • 该安排的可访问性契约:披露(disclosure)状态、一个交互元素、焦点返回,以及完整的键盘路径。
  • 当组件同时提供内置控件和此 prop 时的裁定办法。

为什么现有记录无法承载它

  • architecture:public-component-api 处于 current 状态并已批准。一条记录只携带一个 authority 值,因此将这些未批准的声明添加到其中,会让它们表现为已批准(architecture:knowledge-contracts INV1、INV5)。该记录还持有共享的 API 语法,并将其人工裁定作为 deciding_specs 链接(spec:AST-002/DEC-1、spec:AST-005/DEC-1、spec:AST-012/DEC-1);新的跨组件裁定应放入它所链接的 spec,而不是其内部。它自身的 INV18/DEC-7 边界将可观察的、调用方可感知的行为保留在产品契约中。
  • spec:AST-002 处于 current 状态,存在同样的 authority 问题,并且拥有另一个事实:公共 API 是否被准入,以及操作和函数的命名。本记录位于 AST-002 FR4 的下游——它说明一旦准入通过,调用方提供的控件使用哪条组合缝(composition seam)。
  • family:overlay-dismissal 拥有的是浮层如何关闭,而不是如何打开或由谁渲染控件。此处的采纳者也不是同一个同级家族:它们横跨菜单、上下文菜单和选择器。
  • 正在推进中的四个组件记录会各自持有这份决策的私有副本,而这正是 INV2 所禁止的。

非目标

  • 一个触发区域,它包裹任意的调用方内容,并对上下文手势(如 ContextMenu 的右键点击区域)作出响应。这是不同的事实:没有提供控件,没有交还 props,浮层锚定到指针而不是矩形区域。OQ3 要求所有者确认该边界。
  • 非交互式触发内容,渲染在组件自有的控件内部,例如 Collapsible 的 trigger: ReactNode 位于其自有 <button> 中。这种形态对内容仍然有效且保持不变;FR3 仅禁止将其用于调用方提供的控件。
  • 系统级的 render<X> 前缀规则本身(DEC-6):本记录遵循它;spec:AST-002 和 API Conventions 页面拥有它。
  • Hook 形态的触发 API(FR8)。
  • 锚定、关闭顺序、按压模型、焦点陷阱和浮层解剖结构。它们的所有者以链接形式给出,这里不重述。
  • 满足本契约的等价内部实现仍然有效。内部模块、文件、函数名、算法、数据结构、存储布局、清单(manifests)、日志(journals)、锁、事务协议,以及 CI 作业/工作流拓扑,除非调用方或互操作系统有意将该确切机制作为公共协议来依赖,否则都属于架构或实现范畴。

公共 API 与概念

概念 封闭值或状态 含义 默认值 所有者 稳定性
调用方渲染模式 prop 缺失、prop 存在 缺失:组件渲染自己的控件和外围界面(chrome)。存在:调用方的控件替换它们。 缺失 spec:AST-055 提议中
render prop (props: <Name>TriggerProps) => ReactNode 调用方的函数;组件调用它,并直接渲染返回值,不做包裹。 — spec:AST-055 提议中
交还的 props 一个对象,展开(spread)到一个元素上 Ref/锚点、id、打开和切换处理器,以及 AR1 的披露 ARIA;参见 FR2。 — spec:AST-055 提议中
CSS 中的打开状态 aria-expanded="true" / "false" 唯一由系统提供的信号,调用方据此为打开状态添加样式;组件不会在调用方的元素上写入任何绘制(paint)。 false spec:AST-055 提议中
悬停与按下时的绘制 调用方自己的 CSS 组件不提供,因为组件不渲染该元素。 无 调用方 提议中
两个控件均已提供 调用方的控件渲染 调用方的控件优先;触发一条开发警告;组件自己的控件及其外围界面不渲染。 调用方的控件 spec:AST-055 提议中
Hook 触发 props triggerProps, getTriggerProps Hook 的返回值,是一个单独的约定,不受本记录影响。 — 所属的 hook 记录 稳定

需求

行为契约

ID 不变式 依据 验证状态
FR1 允许调用方提供用于打开其浮层的控件的组件,MUST 将该控件作为名为 renderTrigger 的渲染属性(render prop)接收(DEC-5):一个由组件以单个 props 对象调用的函数,函数返回的元素组件应按原样渲染。组件 MUST NOT 将该返回元素包装在自己拥有的元素中,也 MUST NOT 要求特定标签或特定的 Astryx 组件。 DEC-1;spec:AST-002 FR4 已接受;jsdom 证据待补
FR2 将返回的 props 展开到一个元素上 MUST 是全部集成工作。该对象 MUST 携带浮层定位所依据的 ref 或锚点、AR1 所需的 id、在该组件支持的输入路径上从该控件打开、切换和关闭浮层的所有处理函数,以及 AR1 的披露属性。该对象的类型 MUST 从组件的公共入口点导出。 DEC-1;architecture:public-component-api INV1、INV5 已接受;jsdom 证据待补
FR3 调用方提供的控件 MUST NOT 作为 ReactNode 插槽被组件渲染到其自身的交互元素内部。调用方通常会传入交互式组件,而这种形态会形成一个交互元素嵌套在另一个交互元素内部的情况(AR2)。在组件自有的控件内部渲染的内容插槽,对非交互内容仍然有效,且保持不变。 DEC-1;AR2 已接受;jsdom 证据待补
FR4 调用方的控件 MUST 拥有一个盒子(box)。组件 MUST NOT 将其渲染在自身没有盒子的包装器(display: contents)内,也 MUST NOT 在触发器的焦点指示器绘制或偏移、或根据触发器的矩形定位浮层时依赖此类包装器:因为既没有可锚定的矩形,也没有可绘制的盒子。FR1 消除了对任何包装器的需求。 DEC-2;architecture:layer-runtime anchor contract 已接受;需真实浏览器证据
FR5 悬停、按下以及所有其他在调用方控件上的指针绘制效果,MUST 归属于调用方自己的 CSS。组件 MUST NOT 将绘制写入其不渲染的元素。组件 MUST 将浮层的打开状态以 aria-expanded 形式发布到返回的 props 上,以便调用方根据渲染出的属性来设置打开状态的样式,而无需为此新增额外的公共 API。 DEC-3;spec:AST-002 FR1、FR2 已接受;jsdom 证据待补
FR6 该属性的消费者文档 MUST 展示如何从调用方控件上的 aria-expanded 设置打开状态的样式,并且 MUST 说明:以 :active 为键的按下外观不能作为替代,因为 :active 在手指触摸下的表现不同,而且按压绘制遵循的是 spec:AST-094 FR11 的模式。 DEC-3;当前没有核心组件基于 aria-expanded 设置样式,因此调用方没有可参考的示例 已接受;文档证据待补
FR7 当组件同时提供内置控件和此属性时,MUST 恰好渲染一个控件。调用方的控件 MUST 在组件支持的每种呈现形式中都以相同方式胜出,并且 MUST 发出开发警告;组件自身用于被替换控件的 chrome MUST NOT 渲染。静默忽略传入的属性,或同时渲染两者,都是不可接受的。 spec:AST-002 FR15(绝不静默渲染损坏状态);architecture:public-component-api INV3 已接受;jsdom 证据待补
FR8 返回触发器 props 的 hook——useLightbox、usePopover、useMenuHover 和 useHoverCard 上的 triggerProps 与 getTriggerProps——遵循 hook 约定,并且不因本记录而改变。这些返回值名称并不是组件属性名称或形态的先例。本记录不要求 hook 增加 render prop,也不要求组件将其触发器 props 重新发布为 hook 返回值。 DEC-4 已由 DEC-4 解决;无代码变更

无障碍契约

  • AR1 —— 调用方的控件承载披露信息。 返回的 props MUST 在调用方的控件上放置 aria-haspopup 以指明浮层的种类、aria-expanded 以承载其打开状态、aria-controls 以指明其元素。当浮层从该控件获取其可访问名称时,props MUST 同时携带浮层 aria-labelledby 所指向的 id;以其他方式为浮层命名(例如通过自身的 label)的组件,会在其自己的记录中另行说明。
  • AR2 —— 一个交互元素,一个焦点环。 调用方的控件 MUST 是用于打开浮层的唯一交互元素。组件 MUST NOT 在其周围添加 <button>、链接或 tabindex 宿主:控件嵌套控件是无效 HTML,并且会破坏键盘操作和屏幕阅读器播报。控件自身的焦点环 MUST 作为可见的焦点指示器,这需要 FR4 所保留的盒子。
  • AR3 —— 焦点返回控件。 通过任何受支持的途径关闭浮层——选择某项、Escape、轻触关闭或命令式句柄——MUST 在该控件仍位于文档中时将焦点返回调用方的控件。
  • AR4 —— 每种受支持的配置都保留完整的键盘路径。 可以接收焦点的调用方控件 MUST 像内置控件一样通过键盘打开和操作浮层。当组件支持无法接收焦点的控件时,它 MUST 提供并记录另一条完整的键盘路径来打开和操作浮层;它 MUST NOT 将仅限指针的配置呈现为受支持配置。

平台支持

  • 受支持的功能/引擎底线:每个受支持的渲染器和每个受支持的浏览器。此处没有任何功能需要能力检查。
  • 不受支持的行为:无法接收焦点的调用方控件按照 AR4 记录的替代路径进行降级,绝不会降级为仅限指针的浮层。
  • 浏览器证据:FR4 和 AR2 属于布局与绘制层面的声明——调用方控件上的焦点环,以及浮层相对于该控件矩形的位置。jsdom 既没有布局也没有绘制,因此这两项需要真实 Chromium 环境中的证据。其余需求可在 jsdom 中证明。

当前状态影响

  • 当本记录变为 current 时,architecture:public-component-api 会在其 deciding_specs 中获得 spec:AST-055,并在其 Deciding specs 列表中增加一行。该记录的任何不变量都不会改变:FR1–FR8 位于其 INV2、INV3 和 INV5 语法之内,而非对其进行修订。
  • contributing:api-conventions 获得针对调用方提供的控件的 render-prop 组合规则,写法为 renderTrigger(DEC-5)。系统级的 render<X> 前缀规则(DEC-6)落在 spec:AST-002 和 API Conventions 页面,而不是这里。
  • component:DropdownMenu、component:ComplexSelector 和 component:MultiSelector 引用本记录,而不是各自记录同一决策的私有副本。它们的消费者文档获得 FR6 所要求的 aria-expanded 样式指南。
  • family:overlay-dismissal、architecture:layer-runtime 和 architecture:interaction-modality 被读取而非更改:关闭顺序、锚定和模态性仍由其所属记录负责。
  • 没有任何已发布的公共 API 变更。每个组件都保留其内置控件和当前默认值。
  • 当本记录处于 draft 状态时,其 review-applicability:v1 块不路由任何内容:全局路由仅加载 current 声明(architecture:knowledge-contracts INV20)。它将在批准后生效。

验证

契约 验证 代表性状态 变异或失败预期
FR1、FR3、AR2 DropdownMenu.test.tsx、ComplexSelector.test.tsx、MultiSelector.test.tsx 中各组件按调用方渲染触发器的测试套件 调用方返回交互组件;调用方返回非按钮元素 组件自有的交互式祖先,或第二个具有打开角色的元素,将导致失败:渲染树必须恰好包含一个。
FR2 同样的测试套件,仅展开该对象且不添加任何其他内容 通过指针打开、通过键盘打开、切换关闭、锚点已解析 调用方必须手动提供的 prop,或缺失的已导出 props 类型,将导致失败。
FR4, AR2 所属组件测试套件旁的真实 Chromium 证据 键盘焦点位于调用方控件上;浮层相对于该控件定位 焦点环没有可绘制的盒子,或浮层失去其锚定矩形,则失败。这在 jsdom 中无法证明。
FR5, FR6 相同的测试套件,外加组件的使用方文档检查 打开和关闭状态;调用方通过 aria-expanded 为打开状态设置样式 组件在调用方元素上写入的悬停或按下样式,或一个在文档中未包含 aria-expanded 路线的 prop,则失败。
FR7 相同的测试套件,提供两种控件,覆盖组件支持的每种呈现形式 指针呈现形式和触摸呈现形式 渲染出两个控件、一个被静默丢弃的 prop,或一个以其他方式解析的呈现形式,则失败。
AR1, AR3 相同的测试套件 关闭、打开、有名称的浮层;通过选择、Escape、点击外部(light dismiss)和关闭手柄关闭 缺失披露属性、浮层没有名称,或关闭后焦点落在 <body> 上,则失败。
AR4 所属组件的键盘测试套件 一个可聚焦的调用方控件;在组件支持此类控件的情况下,一个无法接收焦点的调用方控件 仅能通过指针访问的配置,或未记录的替代路径,则失败。
FR8 对指定 hooks 的源码检查 useLightbox, usePopover, useMenuHover, useHoverCard 为匹配组件 prop 而重命名或重塑 hook 返回值会失败:本记录不改变其中任何一个。

已知验证缺口:上文提到的各组件测试套件和真实 Chromium 证据尚不存在于 main 分支上。此记录为 draft,在它们到位且所有者批准之前,不约束评审。

决策日志

DEC-1 — 调用方提供的浮层控件是一个渲染 prop

Reference: spec:AST-055/DEC-1 Decider: cixzhang, 2026-10-02

调用方渲染控件;组件回传使其工作的 props。将这些 props 展开到一个元素上就是全部集成工作,因此构建者无需编写 ref 管道,也无需重新推导 ARIA;产品使用者可以在图标按钮、chip、头像或列表行上获得系统的键盘打开、焦点返回和披露语义。

已否决:Collapsible 模式上的内容槽位——在组件拥有的 <button> 内部渲染 trigger: ReactNode。调用方通常会传入交互组件;按钮嵌套按钮是无效 HTML,会同时破坏键盘操作和屏幕阅读器播报,因此这种形态根本无法满足此场景。槽位形态仍适用于非交互式触发器内容。

DEC-2 — 触发器拥有自己的盒子

Reference: spec:AST-055/DEC-2 Decider: cixzhang, 2026-10-02

调用方的控件保有自己的盒子,组件在其周围不渲染任何包装器。

已否决:在触发器包装器上使用 display: contents。无盒子的元素让焦点指示器没有可绘制的对象,也让浮层没有可锚定的矩形,因此键盘用户会失去控件本应显示的可见焦点,浮层也会失去其位置。此否决针对的是组件在调用方控件周围渲染的包装器,以及组件以该包装器为锚点或在其上绘制的情况;改为以指针为锚点的触发器区域则是另一种情况(OQ3)。

DEC-3 — 指针绘制保留在调用方;打开状态是 aria-expanded

Reference: spec:AST-055/DEC-3 Decider: cixzhang, 2026-10-02

调用方拥有该元素,因此悬停和按下状态属于调用方自己的 CSS。调用方唯一无法得知的是浮层是否打开,而回传的 props 已经通过 aria-expanded 携带这个信息,因此打开状态通过渲染出的属性到达 CSS,而不是通过新的公共 API。

由于当前没有任何核心组件根据 aria-expanded 设置样式——现有用法都只是发出该属性——这条路在仓库内没有可复制的示例,因此 FR6 要求将其记录在 prop 上。同一文档说明 :active 不能替代:它在手指下表现并不相同,这就是按下样式遵循 spec:AST-094 FR11 的 profiles 而不是 :active 的原因。

DEC-4 — Hook 触发器 props 是另一种约定

Reference: spec:AST-055/DEC-4 Decider: cixzhang, 2026-10-02

useLightbox 返回 triggerProps 和 getTriggerProps;usePopover、useMenuHover 和 useHoverCard 返回 triggerProps。这符合 hooks 的约定——返回一个可供展开的 props 对象是常规形态——因此保持原样不变。

DEC-5 — 该 prop 命名为 renderTrigger

Reference: spec:AST-055/DEC-5 决策者: cixzhang, 2026-10-02

render* 是函数值公开组件 prop 的现有约定,核心中没有任何反例:renderOption、renderValue、renderItem、renderToken、renderContent、renderSelectionLabel、renderLineContent、renderExpanded、renderGroupHeader、renderCell、renderTooltip、renderHoverCard、renderMenu、renderOverlay。裸名词持有函数的情况只出现在调用方传入的配置对象内部,从不作为公开组件 prop。

已否决:裸 trigger。它在调用点读起来不错,但该名称在系统中已经以不同形状公开——Collapsible 的 trigger: ReactNode——因此将其复用为函数会让一个名称拥有两种形状,而 spec:AST-002 FR16 和 architecture:public-component-api INV2 都反对这样做。阅读 renderTrigger 的构建者也仅从名称本身就能知道这里期望一个函数。

DEC-6 — render<X> 是所有 render prop 的前缀

Reference: spec:AST-055/DEC-6 决策者: cixzhang, 2026-10-02

如果一个公开组件 prop 的值是返回渲染输出的函数,则命名为 render<X>。该约定已经近乎普遍;此处将其成文,以便构建者能够预测名称,评审者可以引用它而不必重新论证。

本记录遵循该规则而非拥有该规则:公开 API 的命名规则属于 spec:AST-002 的事实——它已经在 FR11 和 FR17 中拥有操作和函数命名——连同 API Conventions 页面的 Prop Naming 部分,后者目前对布尔值、回调、枚举、方向和 HTML 冲突作出规定,但并未涉及函数值 prop。两者都需要一份携带此规则的修订;在它们携带之前,请引用本决策。

开放问题

  • OQ3 — 包裹任意内容的触发器区域是否属于本记录范围? (human-api)

ContextMenu 不接受控件:它将调用方内容包裹在自身的一个元素中,并在上下文手势触发时打开,锚定到指针而不是包裹元素的矩形,而且它不会在该包裹元素上绘制焦点环。开放的拉取请求 #6839 提议让该包裹元素变为内联或无盒(box-less),以便文中的引用可以拥有上下文菜单。

非目标(Non-goals)将其视为另一个事实,位于 FR1 之外,也不在 DEC-2 的否决范围内,因为 DEC-2 的两个理由——没有可绘制焦点环的对象、没有可锚定的矩形——在该组件不绘制焦点环并锚定到指针时都不适用。请所有者确认该边界,或将触发器区域纳入本记录;若如此,FR1 和 FR4 需要为它们声明例外。

内容边界

本记录不重复任何组件的结构、prop 表、主题化目标或消费者示例;不重复 architecture:layer-runtime 中的浮层定位和 anchor-name 约定;不重复 family:overlay-dismissal 中的关闭与 Escape 顺序;不重复 module:DropdownMenu/useMenuPress 中的按压模型;也不重复 spec:AST-002 中的准入论证。它链接了这些内容的规范所有者。

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