公共组件 API¶
{
"scope": "global",
"triggers": {
"public-api": [
"INV1",
"INV2",
"INV3",
"INV4",
"INV5",
"INV6",
"INV7",
"INV8",
"INV9",
"INV12",
"INV16",
"INV24",
"INV25"
]
}
}
本记录定义了稳定 Astryx 组件的共享公共 API 契约。
目的¶
使用者应当无需了解 Astryx 组件的内部实现,就能预测它如何被导入、控制、扩展和组合。新 API 应表达调用方拥有的意图,并保留既有行为。
系统模型¶
可安装的包即公共契约。它包括:
- 导出的组件和 hooks;
- 导出的 props 和稳定的支持类型;
- 已发布的组件子路径;
- 已文档化的默认值;以及
- 使用者可以观察到的行为。
使用者的 .doc.mjs 文件说明该契约。它们不会创建导出代码所没有的 props 或策略。
一旦本记录变为 current,每份 current 组件契约都会在其 architecture 链接中列出 architecture:public-component-api。草稿组件契约只有在本文档变为 current 之后才添加该链接,因此候选关系不会过早产生权威。
组件契约和组件族契约拥有更窄范围的行为。主题记录拥有主题目标、公共主题属性、tokens 和生成的样式。贡献指南拥有用于提出和测试 API 的流程。
边界与不变量¶
- INV1 — 公共导出是可访问的。 稳定的组件、hook、prop 类型以及其他承诺的公共类型可从其已发布的包入口或组件子路径获得。
- INV2 — 名称承载相同的含义。 组件、hooks、布尔值、回调、Actions、方向、refs 以及原生 HTML 透传都遵循共享的命名语法。组件特定的词汇保持在局部。决定组件如何响应输入的 prop 被命名为
<thing>Behavior,并接受一个封闭的行为名称联合;当其值能够命名行为时,它的名称不包含输入类词语(press、touch、tap、hover、mouse、click)。公共 prop 使用系统已有的词汇来命名系统原语:它不会为系统已命名的概念引入新术语(DEC-1)。元素与其锚点之间的间隙是offset,如useLayer的offset;定位元素从容器或视口边缘保持的距离是inset,如 LayerProvider 和 ToastViewport 的inset。深度是elevation,它从Elevation取值,如 Card、Button 和 Banner 那样。lift表示按压下的运动,例如 Switch 的 thumb lift、Slider 的springs.sliderLift和 ContextMenu 的springs.contextMenuLift,因此它不表示布局距离。hook 接受的元素 ref 按元素的职责命名,如containerRef、scrollRef、menuRef、triggerRef和inputRef;当元素没有更窄的职责时命名为ref。 - INV3 — 一个 prop 控制一个独立概念。 prop 不会静默抑制无关的 prop。父组件不会重复子组合组件已拥有的状态。一种交互行为就是一个 prop,绝不用并行的 touch、mouse 或 focus props:当行为因设备而异时,该 prop 在显式固定值之外提供一个按设备解析的自适应值;当它只有一种设备解析时命名为
'adaptive',当它有多种时命名为'adaptive-<target>',如presentation那样(spec:AST-043/DEC-1、component:DropdownMenuSubMenu);新的行为 prop 默认采用已发布行为,当已发布行为已因设备而异时该默认值就是自适应值;既有 prop 的默认值只能在 INV16 和 INV9 下变更。is…或has…布尔值只命名没有第三种状态的真开关;presentation命名出现哪个表面,并在 INV16 下命名打开表面的输入模式。 - INV4 — 新 props 表达调用方拥有的意图。 新公共 props 遵循
spec:AST-002/DEC-1。当组件能够从状态、内容、布局、上下文或平台行为推导出正确结果时,它将该决策保留在内部。 - INV5 — 已接受的调用方 props 会被保留。 对于拥有 DOM 的组件,受支持的 DOM、data、ARIA、style、class 和事件输入会到达拥有该契约的元素。组件拥有的可访问性和行为不能被意外覆盖。
- INV6 — 样式输入会组合。
xstyle、className和style按文档化的顺序组合,而不是相互替换。组件族记录可以为其成员声明根样式输入的例外,在决策中说明替换的部件输入及其原因;family:input-fields的 FR10 就是一例。 - INV7 — 事件处理程序有意识地组合。 调用方处理程序和内置行为使用共享的取消契约。调用方只能在公共 API 承诺取消的地方取消内置行为。将处理程序移动到另一个元素的组件会保持它为该处理程序发布的顺序和取消能力,并将其文档化(
family:input-fieldsDEC-8)。 - INV8 — Refs 遵循 React 19。 公共 DOM 组件接受
ref作为 prop,并将其连接到契约所承诺的元素。 - INV9 — 已发布的 API 须审慎变更。 已发布的 prop、类型、导出、默认值或可观察行为,在未按照
spec:AST-017要求完成生命周期、证据和迁移前,不会被移除、重命名、改变类型、弃用或进行不兼容修正。 - INV10 — 共享子契约应被链接,而非复制。 输入 Actions、层行为、主题化和组件族特定规则保留在其所属记录中。
- INV11 — 公共主题接缝须通过 API 准入。 只有当调用方拥有的意图无法由目标保证的 CSS 属性集表达时,才会接纳公共语义 CSS 自定义属性。其主题记录拥有确切用途、稳定默认值/回退、作用域、文档、证据和兼容性契约;仅凭内部样式缺口并不能证明公共 API 的合理性。
- INV12 — 可达性优先于内部标签。 从受支持的包路径可到达的类型、上下文成员、hook 返回值、工具函数签名、默认值或操作,即使其源码注释、文件名或当前用途称其为内部,也属于公共。要保护隐私,必须移除导出或将能力移到未导出的边界之后。Core 的
./internal/*子路径是唯一例外:它们可达,但保留给 Core 和 Lab,未文档化,与 Core 同步版本,通过 lint 限制在这两个包内,并且仅可被 swizzled 副本导入以获取一个其身份即其路径的已导出 StyleX 模块(spec:AST-110FR1),且不在兼容性承诺之内(spec:AST-017FR21)。 - INV13 — 公共变更需路由到其权威所有者。 每次公共 API 更新和每次公共行为变更都遵循
architecture:knowledge-contracts定义的结果和处置方式。测试、Changeset 或生成的 manifest 都是证据;任何一项都不能为缺失或矛盾的契约定案。 - INV14 — 共享断点名称保持单一含义。 接受主题宽度点的组件使用活动 Theme 中的
sm/md/lg/xl/2xl。below边界是排他的,因此相等属于更宽的一侧。 - INV15 — 部件的样式输入以一组形式出现。 除根元素外的元素样式以
<part>Xstyle、<part>ClassName和<part>Style一起接受,到达该元素并按 INV6 描述的方式组合。遵循spec:AST-071/DEC-1,没有任何公共 prop 会为不能同时接受类名和内联样式的元素接受 StyleX 样式。 - INV16 — 调用方的呈现选择优先于触控默认值。 在粗指针下呈现不同表面(例如用 sheet 代替 popover)或改变打开表面跟随输入的方式(例如打开列表中的触控跟踪)的稳定组件,采用一个
presentationprop;它的某个值(如presentation="popover")会在所有设备上保持组件在细指针下使用的表面和输入模式。触控行为在服务于触控用户时是组件的默认行为,而调用方的显式选择始终优先于该默认值。此类每种内部触控模式都可被调用方通过公共 prop 或值访问;任何模式都不会被硬编码到调用方无法触及。触控样式(如按压绘制或文本大小下限)以及其自身记录定义的仅触控行为(如行滑动或 tooltip 的触控触发器)遵循那些记录。模式内部的阈值和调优值保持内部(spec:AST-002FR3)。INV4 让组件推导默认值;INV16 让调用方能够覆盖它。当触控默认值改变已发布组件的行为时,该presentation值就是spec:AST-017FR3 所指的恢复 prop(spec:AST-017/DEC-23)。一个例外会覆盖显式选择:在gregory或iso8601以外的日历下,DateInput或DateTimeInput上的presentation="native"会解析为针对指针的 Astryx 表面,因为没有原生日期选择器会显示应用程序的日历(spec:AST-111FR15、DEC-7)。 - INV17 — 紧凑只有一个共享定义。 按屏幕尺寸选择呈现方式的组件使用主题的紧凑定义:宽度低于有效
md点或高度低于 500,并且每个平台上的数值相同(spec:AST-012FR9)。它自己不保留紧凑数值,正如 INV14 不保留并行的断点表。调用方选择的布局宽度(例如 AppShell 的mobileNav.breakpoint)改为遵循 INV14。 - INV18 — 沿解剖结构组合。 避免深入组件解剖结构的 props(例如选取子组件的特定 prop 或 label)。应改为构建组合。组合必须遵循组件的解剖结构;绝不暴露组合或渲染解剖结构中未描述的插槽的方式;并且插槽必须有组件。配置对象是可以的:描述操作或选项的纯数据(例如传给
createSwipe的{label, icon, onActivate}条目)不是插槽。"插槽必须有组件"适用于渲染内容插槽,即接受任意节点的位置;这样的插槽必须是组件解剖结构中命名的部件,调用方用组件填充它。这扩展了 INV3 的规则:父组件不重复已组合子组件的状态;插槽的样式遵循 INV15 和architecture:component-theming-surface。参见 Slots and composition。 - INV19 — 资源成本要与功能相权衡。 在资源负载与功能特性和跨平台考量之间取得平衡。如果某个功能有较大的资源成本,考虑将行为以插件方式接入,如
Item的滑动操作通过swipe={createSwipe(…)}接入(spec:AST-057DEC-8)。为功能提供命名 props 也是可以的(如collapsible)。 - INV20 — 使用变体,而非视觉布尔值。 避免只切换视觉表现的布尔标志;优先使用变体。这将对视觉选择应用 INV2 的命名和 INV4 的调用方拥有意图;参见 Open visual vocabularies and closed axes。
- INV21 — 每项任务一个 API。 不得有与既有 API 共用同一任务的新 API,除非既有 API 正在被弃用并让位于它。INV3 保持一个 prop 对应一个概念,INV16 保持一个
presentationprop 用于表面选择;INV21 在 props、组件、hooks 和 factories 之间应用同样的规则。一个完全委托给公共 factory 的 hook,且没有
自身的行为,而完全基于公共工厂构建的组件与该工厂是同一个 API,而非第二个 API(spec:AST-107 FR6、FR8)。弃用遵循 INV9。组件通过单个插槽 prop 取得其值的 hook 与该组件是同一个 API,而非第二个 API,如 const value = useX(…); <Component x={value} />(负责人决策,2026-11-04)。
- INV21a — 已发布的 API 仅因用户价值而变更。 对已发布的公开 API 进行破坏性或弃用性变更需要用户价值;仅凭符合系统规则并不足以作为理由。新 API 遵循当前规则;已发布的 API 在真正需求出现之前不受新规则约束(负责人决策,2026-11-04)。每个组件 API 的变更仍需各自的负责人批准。
- INV22 — 交互工具函数具有非 React 等价实现。 交互工具函数具有与其 hooks 高度对应的非 React 等价实现(
create…),包括相同的选项名称与含义、事件和返回值概念。一个其结果仅能由 Astryx 组件或 StyleX 使用的 hook(插槽 hook,其输出供给某个 Astryx 组件 prop,或useAnimatedLayout、useEntryAnimation、useContainerReveal、useTouchTrigger、useTableRowExpansion、useTableColumnResize)默认没有等价实现;负责人可以添加一个(负责人决策,2026-11-04)。根据负责人决策(2026-11-04),useMenuPress没有非 React 等价实现;当调用方需要时,可以添加一个。 - INV23 — 每个私有数据属性都有一个所有者模块。 除非本不变量将其命名为公开属性,否则
data-astryx-*属性都是私有的。每个私有属性在写入它的包中都有一个内部所有者模块,即packages/<package>/src/privateAttributes/<name>.stylex.ts,该模块持有其名称和值,并在其自己的stylex.create调用中以字面量形式将每个选择器写入一次;StyleX 仅在选择器被写入的位置解析该选择器。所有者仅导出读取该属性的现成样式、设置该属性的 props 或写入器,以及其包所需的运行时读取器,例如closest或matches辅助函数或 getter;它从不导出原始名称或选择器。纯 TS 所有者packages/core/src/privateAttributes/<name>.ts可以将其名称和选择器文本导出给其.stylex.ts同级文件以及packages/core/src/theme/中的主题引擎;没有其他文件导入它,而.stylex.ts所有者仍然从不导出它们。当存在纯 TS 所有者时,其.stylex.ts同级文件不是所有者:它仅将属性的选择器作为其自身stylex.create调用的字面量写入,因为 StyleX 仅在选择器被写入的位置解析选择器,并且它从不导出这些选择器或设置该属性。该包中的所有其他文件展开这些导出,并且从不写入该属性或其选择器;任何包都不得通过内部路径导入另一个包的所有者模块。如果所有者模块的属性标记的是其包不渲染的元素,则该模块可以在注入的规则中写入其选择器一次,而不是通过stylex.create;Core 可以仅通过内部入口将该模块的写入器重新导出给 Lab,而属性名称和选择器对所有者保持私有。StyleX 一次按整个属性合并样式,因此所有者样式携带其设置的每个属性的所有条件,包括其静止状态和指针状态,调用方不会在同一元素上再次设置这些属性。在所有者模块和测试文件之外,手写的data-astryx-字符串、模板或 JSX 属性名,或命名私有属性的dataAttr()调用,都会违反@astryx/no-raw-private-attributelint 规则;先于该规则存在的代码位于其基线中,该基线只会缩小。测试可以命名私有属性,因为它们断言组件渲染出的 DOM。私有属性不出现在任何公开导出、.doc.mjs或 Changeset 中,不承担任何兼容性承诺,并且可以在任何版本中变更。data-astryx-*命名空间之外的数据属性也是公开的,并且仅在当前记录命名它时才添加(DEC-2)。公开的data-astryx-*属性包括:data-astryx-theme,即主题作用域(spec:AST-066FR6);data-astryx-media,即主题编译产出的媒体表面作用域;data-astryx-aspect-ratio-override(component:AspectRatioFR3);data-astryx-token和data-astryx-token-value(component:ChatComposerTokenElementFR1);data-astryx-menu-press,即菜单根标记(module:DropdownMenu/useMenuPress);data-astryx-pressable,即按压标记(component:SegmentedControlItemFR7);以及data-astryx-edge-comp,以EDGE_COMP_ATTR(INV12)导出。它们仅在 INV9 下变更。拥有它们的代码在其自身的代码位置写入它们,包括 Theme、MediaTheme、reset.css、generateThemeRules.ts、CLI 主题构建、AspectRatio、Chat composer、按压与菜单按压 hooks、以及边缘补偿样式,lint 规则允许这些名称。 - INV24 — 每个拉取请求都携带生成的公开 API 差异报告。 任何包都不得提交生成的 API 报告。对于更改已发布包源码或构建的拉取请求,CI 在合并基线和确切 HEAD 上运行同一个表面生成器,依据每个已发布包按入口点构建的声明和样式表,并将两者之间的 API 变更以未提交的形式写入,作为 CI 的 API 变更产物。差异报告列出新增、变更和移除的导出、组件 props 及其类型、hooks 及其签名、辅助类型、公开 CSS 自定义属性和主题目标、INV23 命名的公开
data-astryx-*属性以及公开事件,每行都带有其签名。标记为 internal 的可达成员会出现(INV12);Core 的./internal/*子路径和未发布的包(包括 Lab)不会出现。位于规范性实验边界内的成员会以 experimental 标记出现(spec:AST-017FR21)。合并门禁仅对更改已发布包源码或构建的拉取请求读取该产物,当产物缺失或生成器出错时,门禁按失败关闭处理。对于任何其他拉取请求,门禁不读取产物,其审查备注显示“New public API: none”。审查机器人对每个拉取请求的审查以差异报告开始其摘要备注,每行附有使用示例,或显示“New public API: none”;公开 API 审查读取该差异报告。差异报告的行是证据,不决定验收与否(INV13)。 - INV25 — 未声明的公开 API 交由人工处理。 公开 API 审查将拉取请求 API 差异报告(INV24)中每个新增或变更的行与当前记录进行比较。由合并基线时有效的记录,或同一拉取请求中的记录变更所决定的行,无需进一步步骤。没有当前记录决定的行,包括标记为 internal 的可达成员,将把该行列入列表提交人工审查,交由该记录的所有者,如
architecture:knowledge-contracts变更耦合第 6 步所述。被移除或重命名的行遵循 INV9。
本记录适用于稳定的公共包;INV23 同样适用于 Lab 源码。Lab 组件在晋级之前不属于稳定的公共承诺。
变更耦合¶
- 新增或修改导出的 prop、支撑类型、context 成员、hook 返回值、操作签名、默认值、包入口、ref 目标,或有意的可观察契约,都会触发公共 API 审查。即使顶层导出不变,可达的支撑契约也可能发生变化。
- 每次审查都比较从 merge-base 到 head,以及从当前 main 到合成合并(synthetic merge)的声明与可达导出。拉取请求的 API delta(INV24)将这些证据编入清单,并把每一行映射到其规范的组件、系列、架构或系统负责人;它并不决定是否接受。
- 更改已发布包公共表面的拉取请求,需在其 API delta(INV24)中展示该变更,且不提交生成的报告。
- 在生成的表面清单确定确切的 API 与行为差异及其规范负责人后,将其路由到
architecture:knowledge-contracts之下。本记录不重新定义审查结果或 PR 处置。 - 当消费者用法或有文档记载的承诺发生变化,或现有文档可能因此失真时,消费者文档才需要变更。修复实现缺陷本身并不要求变更消费者文档。
- 新增 prop 必须包含
spec:AST-002/DEC-1的准入论证;不能仅仅因为它解决了一个调用点就被接受。 - 公共 API 审查会拒绝用新术语命名既有系统概念的公共 prop(INV2、DEC-1);该 prop 应采用系统对这个概念的既有用词。
- 为稳定组件新增触控呈现或开放表面的触控输入模式时,需检查 INV16:
presentation值保留精细指针表面与模式,并且每个此类触控模式都可被调用方触达。 - 新增公共语义 CSS 自定义属性时,需包含同样的准入论证,并说明为什么目标元素保证的 CSS 属性集无法表达调用方拥有的需求。其详细契约与证据保留在所属的主题/组件记录中。
- 发布的破坏性变更需包含发布流程所要求的兼容性决策和迁移证据。
- 暴露具名主题宽度点的组件,应使用
spec:AST-012中的固定词汇和上界排他行为;它不得维护并行的硬编码断点表。按屏幕尺寸选择呈现方式的组件应使用 compact 定义(INV17)。 - 对系列所属 API 的变更应更新系列契约,而不是把其规则复制到本记录或每个组件中。
- 接受或推导导航目标的组件遵循
family:navigation-destinations。新增 sink 或携带目标的组件时,应更新该系列,而不是创建组件本地的 URL 规则。
所属代码¶
- 公共包 manifest 与组件 barrel 拥有可达导出。
- 组件 prop/类型定义与运行时行为拥有实际 API。
BaseProps为拥有 DOM 的组件定义共享的 DOM/样式表面。.doc.mjs文件拥有面向消费者的 prop 描述、默认值和示例。- Astryx ESLint 规则与 API/文档测试检查共享契约。
决策规范¶
spec:AST-002/DEC-1— 新的公共 prop 要求调用方拥有组件无法推导的信息。spec:AST-005/DEC-1— 每个 Astryx 拥有的导航出口都遵循同一个目标安全决策。spec:AST-012/DEC-1与spec:AST-012/DEC-2— 组件复用固定主题宽度名称,以及from包含、below排他的边界含义。spec:AST-071/DEC-1— 每个样式输入都能从每种样式系统工作,因此一个部件的样式输入以集合形式出现。spec:AST-107/DEC-2与spec:AST-107/DEC-3— 一个基于公共工厂的 hook,以及一个完全基于该工厂的组件,与工厂本身属于同一个 API(INV21)。spec:AST-017/DEC-23— 触控呈现或开放表面的触控模式是一种调用方总能覆盖的默认行为,通过一个presentationprop 实现,该 prop 同时恢复先前的表面与模式。spec:AST-012/DEC-6— compact 只有一个定义,在所有平台上一致。
Transition Action 的顺序安排与待处理行为归属于它们的组件或系列契约。本记录一旦成为当前版本,就会链接到该负责人;它不复制组件矩阵。
DEC-1 — 公共 prop 使用系统既有词汇¶
决策者: cixzhang, 2026-11-03
命名系统原语的公共 prop 应使用系统已有的用词,这样熟悉一个组件的构建者在看下一个组件时,能以同样方式理解同一概念。锚点旁的间隙是 offset,定位元素相对边缘向内保持的距离是 inset,深度是 elevation,而 lift 保持为按压时运动的名称。新组件(如搜索字段)的 API 应从系统中既有模式出发,不为系统已命名的概念引入新术语。
已否决:为共享概念使用组件本地名称。
DEC-2 — 私有 data-astryx-* 命名空间之外的数据属性属于公共表面¶
参考: architecture:public-component-api/DEC-2
决策者: cixzhang, 2026-11-09
负责人曾说:“新的数据属性是对外的,除非有明确的规范绕过此规则,否则不应用于仅限内部的问题”,以及“我们对数据属性如此谨慎的主要原因是,我们会为它们生成主题”。主题编译会把选择器写到数据属性上(这些 data-astryx-* 作用域以及镜像 prop 的属性,如 data-size 和 data-variant),因此组件渲染出的数据属性可能会被主题读取或作为目标,从而成为公共表面。因此,组件只有在当前记录明确命名并说明理由时,才可新增数据属性;仅限内部关注点应使用 INV23 下的私有 data-astryx-* 属性,或者完全不使用属性。
对于每实例的动态样式,首选是 StyleX 动态样式(使用函数的 stylex.create):它在该实例上内联设置一个生成的自定义属性(--x-<property>,或者是伪元素或条件之下的哈希名称)。根据此规则,该属性是私有的:没有主题值、记录或文档指名它,并且它可能在任何发布版本中改变。负责人谈到 Avatar 的首字母时说:“我们应该让智能体把它作为这类动态样式的首选。”
已拒绝:为内部关注点添加 data 属性,而没有一条指名它的记录。
DEC-6 — 拉取请求携带 API 差异,而非提交的报告¶
决策者: cixzhang, 2026-11-09
负责人说:“好吧,让我们删掉这个庞大的文件。我们不需要它,我们应该用 codebunny 以智能体方式为每个 PR 生成 API 差异。”每个包中提交的报告体积庞大,在每个包中重复呈现接口面,并且会过时;为每个拉取请求生成的差异会在评审发生之处标记变更。CI 对合并基线与精确 head 的接口面比较是合并门禁所读取的机器源;当某个变更已发布包的拉取请求缺少该产物时,它会失败关闭;对于任何其他拉取请求,它不读取任何内容。评审机器人在其摘要说明开头的差异是人工视图(INV24)。
已拒绝:为每个包保留一份已提交的生成式 API 报告。
验证¶
| 不变量 | 证据 | 失败信号 |
|---|---|---|
| INV1, INV8 | 导出、公共子路径、prop 和 ref 检查 | 承诺的组件/类型无法被导入,或其 ref 无法到达约定元素 |
| INV2 | 命名与逻辑方向的 lint/测试 | 等价概念使用冲突的名称,或物理方向泄漏到公共 API |
| INV2, DEC-1 | 对照系统词汇表的公共 API 评审 | 公共 prop 用新术语命名系统已命名的概念,例如距离、深度或按压动效,或使用 lift 表示布局距离 |
| INV3, INV4 | 历史 API 评审基准与 spec:AST-002 证据 |
某个 prop 组合了不相关的轴,或暴露了可推导的实现选择;新的交互行为 prop 不是 <thing>Behavior 封闭联合,或携带了一个其值本可命名该行为的输入词,或将单一行为拆分到按输入划分的多个 prop 中,或作为新 prop 默认值不是已交付行为 |
| INV5, INV6, INV7 | BaseProps/透传 lint 和代表性运行时测试 | 使用者的 ARIA/data/style/事件被丢弃、破坏组件语义,或无法组合 |
| INV9 | 已发布接口面、Changeset、迁移和公共类型检查 | 已发布的 API 在没有明确兼容性证据的情况下发生变化 |
| INV11 | 公共 API 准入审查,以及自有的主题/组件测试 | 某个公共语义自定义属性暴露了可推导的或不受支持的实现细节 |
| INV12, INV13 | 生成的声明/导出/行为清单,以及规范所有者映射 | 在 ./internal/* 之外存在可触达的支撑类型或行为却被称作内部,或机械性证据被视为允许接受它的依据 |
| INV14 | AppShell.test.tsx |
组件硬编码了分歧点,或将相等性视为次要 |
| INV15 | 对生成的声明清单进行公共 API 审查 | 某个部件或 StyleX 类型化的样式属性在发布时,未在同一元素上提供 className 和内联样式的对应项 |
| INV16 | 触控呈现形式的公共 API 审查,以及粗指针和细指针的运行时测试 | 一个稳定组件在粗指针下呈现不同表面,或切换已打开表面的输入模式,且没有可保持其细指针表面和模式的 presentation 值;调用者无法触达此类触控模式;默认值覆盖调用者的显式选择(spec:AST-111 的 FR15 日历例外除外) |
| INV17 | 紧凑边界处的解析器测试,加上公共 API 审查 | 组件用自己的数值按屏幕尺寸选择呈现形式,或在宽度 768 或高度 500 处与主题的紧凑定义不一致 |
| INV18 | 对照组件解剖表进行公共 API 审查 | 某 prop 选择或配置子组件的 prop 或标签;组合渲染了解剖结构未描述的插槽;或渲染出的内容插槽不是解剖结构中命名的部件 |
| INV19 | 对高成本特性进行公共 API 审查,并附上打包体积和运行时成本说明 | 资源成本很高的特性让每个调用者都为其买单,却没有插件化路径或命名特性 prop |
| INV20 | 对新布尔属性的 Public-API 审查 | 一个布尔属性,其唯一效果是在存在适用变体时进行视觉切换 |
| INV21 | 对照现有属性、组件、hook 和工厂进行的 Public-API 审查 | 新 API 与某个现有 API 职责重叠,而现有 API 并未为了支持新 API 而被弃用;一个 hook 被提供给某组件的 slot 属性,却被计作第二个 API |
| INV21a | 对已发布 API 的每次破坏性变更或弃用变更进行 Public-API 审查 | 对已发布的公共 API 进行的破坏性变更或弃用变更,仅以符合系统规则为理由 |
| INV22 | 对每个公共交互工具 hook 与其 create… 等价物进行 Public-API 审查 |
存在没有 create… 等价物的交互工具 hook(除其结果只能由 Astryx 组件或 StyleX 使用的 hook,以及 useMenuPress(由所有者决定)之外),或某个等价物的选项名称和含义、事件或返回概念与对应 hook 不同 |
| INV23 | @astryx/no-raw-private-attribute lint 及其基线(测试文件除外),另加对公共列表的 Public-API 审查 |
在所属模块、测试或公共列表之外写出的 data-astryx-* 名称或选择器;dataAttr() 调用命名了私有属性;所属模块导出了其原始名称或选择器;某个包导入了另一个包的所属模块;调用方设置了其展开的所属样式也会设置的属性;在公共导出、.doc.mjs 或 Changeset 中出现私有属性;新增了基线条目;在没有 INV9 证据的情况下更改了公共数据属性 |
| INV24 | 生成器测试、CI 的 merge-base 到 head 表面比较,以及 review bot 的按 PR 的 API delta | 承诺的导出、属性、hook、类型、自定义属性、主题目标、公共属性或事件在 delta 中缺失;可触及的 internal-tagged 成员缺失;出现了 ./internal/* 或 Lab 成员;当比较产物缺失或生成器出错时,merge gate 仍通过了会更改已发布包的拉取请求;review bot 的摘要备注不是以 delta 或“New public API: none”开头;某个 delta 行决定了验收结果 |
| INV25 | 根据拉取请求的 API delta 进行 Public-API 审查路由 | 未被任何当前记录判定的行未进入人工审查;被当前记录判定的行却被留待人工处理;一个未声明的行单独引发了变更请求 |
| Consumer-doc projection | docPropReferences.test.ts 和 docPropLiterals.test.ts |
文档命名了不存在的属性,或遗漏了公共字面量选项 |
已知验证缺口:
- INV23 缺口:目前尚无任何检查覆盖
data-astryx-*之外的数据属性;该 lint 及其验证行仅能看到data-astryx-*名称,而该命名空间之外的现有属性(如 ToastViewport 的data-toast-id)没有任何清单。 - INV2、INV3:在行为属性规则之前就已发布的属性保留其名称,直到某个 minor 版本在 INV9 下重命名它们。此列表仅为部分清单;已知偏差包括 Tooltip 和 HoverCard 的
focusTrigger、touchTrigger和hasHoverIndication,Text 和 Heading 的hasTruncateTooltip(最后两个具有两种以上状态);Dialog 和 AlertDialog 的isInline;CheckboxListItem 的isChecked;useTableTreeData的isAllExpanded;hook 形式如usePopover的hasLightDismiss;Tooltip、HoverCard 和 Popover 的isEnabled;Overlay 的showOn;Thumbnail 的showRemoveOn;Popover 的hasLightDismiss、hasEscapeDismiss和isModal;Dialog、Drawer 和 BottomSheet 的purpose;Banner 的isDismissable;Drawer、BottomSheet 和 BottomSheetSwitcher 的hasScrim;CommandPalette 的isInline;Carousel 的hasLoop和useListFocus的wrap;NumberInput 的isWheelEnabled;Outline 的hasScrollOnClick;useTableRowExpansion和useTableTreeData的hasRowClickExpansion;useTableSortable的isMultiSortEnabled和allowUnsortedState;Banner、SideNav、SideNavItem 和useResizable的collapsible以及 CodeBlock 的isCollapsible;Calendar 的mode和 FileInput 的isMultiple;FileInput 的mode;Tokenizer 和 PowerSearch 的tokenOverflowBehavior;OverflowList 的behavior。 - INV2:某个已发布属性使用系统用于另一概念的词来命名某一概念时,会保留其名称,直到某个 minor 版本在 INV9 下重命名它。Outline 的
offset是其滚动根顶部下方的距离(component:OutlineFR4),而不是与锚点之间的间隙。 - INV3:Carousel 的
hasSnap接受boolean | SnapPaging。省略或false表示不吸附,true表示原生滚动吸附,而来自useSnapPaging的值表示吸附分页。它已知偏离三条规则:is…或has…布尔值只能表示真正的开/关,不能有第三种状态(INV3);决定组件如何响应输入的属性应为<thing>Behavior封闭联合(INV2);以及随设备而不同的行为应提供按设备区分的值(INV3),其中分页值在手指和触控板滑动时进行翻页,而在鼠标滚轮下保持原生吸附。它为了构建者保留了一个吸附属性(component:Carousel/DEC-2),且未被重命名。 - INV22:已知缺口包括
useLongPress、usePressFeedback、useClickableContainer、useInputContainer、useOverlay、useCombobox、useMultiCombobox、useResizable、useTooltip、useHoverCard和useChatStreamScroll:它们各自附加了手势、按压、拖拽或运动行为,且尚无create…工厂;目前还没有完整清单。每个 hook 通过添加其工厂来合规;已发布的 hook 签名仅在出现真实需求时才改变(INV21a)。 - 在已知违规仍然存在期间,透传 lint 仅发出警告。
- 当前的源码到文档完整性匹配器仍在查找旧的带前缀属性接口,因此它尚不能证明完整的属性覆盖。
- INV24:差异覆盖了声明、CSS 自定义属性、主题目标和公共属性;上下文成员行为、未声明的默认值、CLI schema,以及分支和合成合并的可观察行为仍需要显式审查。
- INV24 缺口:审查方案的 API 差异还没有 fixture 测试,且没有任何仓库测试覆盖合并门禁对比较产物的 fail-closed 读取。
- INV18:已发布但 anatomy 尚未命名的内容插槽包括 PowerSearch 的
startIcon和endContent、SideNav 的topContent、footer和footerIcons、Tokenizer 的startIcon、DropdownMenu 的header和footer,以及 picker 选项的action;目前还没有完整清单。每个插槽通过命名该部分来合规,无需 API 变更。 - INV18:配置子组件标签或目标的已发布属性,例如 TopNavMegaMenuFeaturedCard 的
linkLabel和linkHref以及 TopNavHeading 的logoLabel,只能通过 INV9 下的替换来合规。 - INV23:
@astryx/no-raw-private-attribute规则以先于它的站点作为基线运行,且目前尚不存在所有者模块;公共 API 审查覆盖了该规则无法看到的内容:Changesets、组件的.doc.mjs文件(lint 无法触及它们),以及通过+从命名空间拼接的名称,或在模板中通过dataAttrNamespace或NAMESPACE以外的任何方式(成员访问、别名导入、classPrefix)访问的名称,以及通过element.dataset读取或写入的名称。data-astryx-press选择器被复制到了 14 个 Core 文件中。其他仍在各自站点写入的私有属性包括data-astryx-popover-fallback-close和 DropdownMenu 的data-astryx-submenu-regions(Popover 和 DropdownMenuSubMenu 也在运行时读取它们);data-astryx-table-pinned和data-astryx-cell-gliding(各自出现在两个文件中);data-astryx-scrolling(只读不写);DropdownMenu 的data-astryx-submenu-host;Chat 编辑器的data-astryx-dictation-interim;以及 RichText 的data-astryx-richtext-code-syntax。目前还没有完整清单。每个属性通过移入其自身包中的所有者模块来合规,并在其包在代码中读取该属性时,由该模块提供运行时读取器。Lab 的 Schedule 读取 Core 的data-astryx-popover-fallback-close,并通过 Core 的公共 API 或 Lab 拥有的属性来合规。
此处明确列出了这些缺口,而非将部分检查视为完整证明。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx