跳转至

组件尺寸级联架构

{
  "scope": "global",
  "triggers": {
    "layout": ["INV1", "INV2", "INV3", "INV4", "INV5", "INV9"]
  }
}

目的

用户应在组件拥有的组内遇到一致的控件尺寸,而不需要每个子元素重复传入相同的 prop。显式的子元素选择仍应胜出,而位于已声明级联之外的组件必须保持其自身的尺寸契约。

本记录拥有 Astryx 标准元素尺寸级联的共享运行时优先级和范围。组件与家族契约决定参与、几何形状以及有意的覆盖行为。

系统模型

标准级联有三个角色:

  1. 一个参与型消费者(participating consumer) 接受标准的 sm | md | lg 元素尺寸轴,并通过共享的尺寸上下文解析它。
  2. 一个提供方所有者(provider owner) 为文档记录的合格后代建立默认尺寸。
  3. 一个组件默认值(component default) 在没有显式值或继承值适用时提供回退。

消费者按以下顺序解析出一个有效尺寸:

  1. 显式组件 prop;
  2. 最近的活跃提供方值;以及
  3. 消费者文档记录的组件默认值。

有效尺寸随后流经消费者自身的几何形状、渲染状态和主题契约。本架构不决定这些组件特定的映射。

边界与不变量

  • INV1 — 标准轴是共享的。 参与型组件使用规范的标准化元素尺寸词汇 sm | md | lg。具有真正不同语义轴的组件保持在此级联之外,并记录其自身的值。
  • INV2 — 参与是显式的。 组件仅在其当前组件或家族契约采用该级联时才继承尺寸。仅仅暴露一个名为 size 的 prop 并不会使其加入。
  • INV3 — 显式意图胜出。 参与型消费者的显式尺寸 prop MUST 覆盖所有继承的提供方值。
  • INV4 — 最近的提供方胜出。 在没有显式 prop 的情况下,参与型消费者 MUST 使用最近的活跃提供方的值。嵌套的提供方作用域不会相互泄漏。
  • INV5 — 局部默认值是最终的。 在没有显式 prop 或活跃提供方值的情况下,消费者 MUST 使用其文档记录的组件默认值。共享辅助函数的通用默认值不会静默改写组件已发布的默认值。
  • INV6 — null 重置继承的作用域。 提供方的值为 null 时,会抑制该作用域内后代的外部继承值,从而使每个消费者使用其自身的回退值,除非有另一个更近的提供方适用。
  • INV7 — 提供方所有权是声明的。 一个组或容器仅向其当前契约所指定的合格后代集合提供值。该所有者决定是先继承外部尺寸、解析显式组 prop,还是有意开启一个新作用域。
  • INV8 — 传播不会抹除子元素所有权。 提供方提供的是默认值,而非强制值。兄弟后代独立解析,且一个子元素的显式覆盖 MUST NOT 改变另一个子元素或提供方。
  • INV9 — 公开、渲染和视觉尺寸一致。 解析后,参与型组件的公开值、渲染状态、几何形状以及面向主题的尺寸元数据 MUST 在其自身契约下描述同一个有效尺寸。
  • INV10 — 导出的传输并不等于组件准入。 SizeContext、useSize 和 SizeProvider 是公开导出,也是当前传输机制。它们的公开兼容性属于 architecture:public-component-api。它们的存在或使用本身并不授权一个新的公开尺寸轴,也不会使组件加入标准级联。

允许的变体

  • 提供方所有者可以在其当前契约允许的情况下,为后代建立一个固定尺寸,而不为其自身布局消费该级联。
  • 家族可以约束哪些后代继承,或有意压平嵌套成员以保持连通的几何结构。
  • 组件可以仅在此标准级联之外使用另一个封闭的尺寸词汇;通用辅助函数类型化是实现能力,而非共享语义。
  • 主题可以改变已解析值的令牌或几何结构,而不改变优先级或提供方所有权。

变更耦合

当以下变更发生时,触发聚焦审查:

  • 在组件中添加或移除 useSize 或 SizeProvider;
  • 改变参与型组件的显式、继承或回退优先级;
  • 改变提供方的合格后代,或其是否继承外部作用域;
  • 向共享的 ElementSize 类型添加非标准值;或
  • 使渲染/主题尺寸与已解析的公开值不同。

审查会检查提供方以及具有显式、继承、局部默认、嵌套和 null 重置状态的具有代表性的子元素。

所属代码

  • packages/core/src/SizeContext/SizeContext.ts 拥有共享解析和传输。
  • packages/core/src/ButtonGroup/、packages/core/src/InputGroup/、packages/core/src/Toolbar/ 和 packages/core/src/SideNav/ 拥有当前的提供方位置、继承或固定的提供方值,以及后代作用域。
  • 参与型组件和家族契约拥有准入、组件默认值、合格后代、几何形状以及有意的覆盖行为。
  • architecture:public-component-api 拥有 SizeContext、useSize 和 SizeProvider 的导出可达性和兼容性。
  • architecture:component-theming-surface 与组件样式所有者拥有解析后面向主题的尺寸元数据和视觉含义。

决策规范

无。新尺寸概念的公开准入仍遵循 spec:AST-002;本记录仅管辖已采用的标准级联。

提升证据缺口

此仅具权威性的草稿未添加测试。在提升为 current 之前,聚焦证据必须直接覆盖:

  • 嵌套的 null 提供方将外部值重置为消费者的局部默认值;
  • ButtonGroup 和 InputGroup 的继承、显式组和显式子元素优先级;以及
  • Toolbar 在无关的外部提供方之下有意开启固定作用域。

现有 SideNav 测试已经覆盖其固定的 sm footer/action 子作用域和显式子级覆盖。这些缺口属于验证工作,而非新语义。

验证

不变量 证据 失败信号
INV1–INV2 ElementSize 以及当前的组件/系列采用记录 非参与者意外继承,或参与者创造了并行的标准值
INV3–INV6 SizeContext.test.tsx 中的显式/provider/默认、嵌套 provider、null 重置、同级和重渲染 fixture 继承的大小覆盖了显式意图,外层作用域越过更近的 provider,或本地回退丢失
INV7–INV8 针对 ButtonGroup、InputGroup、Toolbar 和 SideNav 的 provider 所有者测试,以及共享的同级 fixture provider 到达不合格的后代、静默改变作用域,或一个子级改变另一个子级
INV9 已变更参与者的所属组件/系列几何、渲染状态和主题化证据;此处为代表性列举,并非详尽无遗 解析后的大小与实际绘制或暴露的有效大小不一致
INV10 包导出清单以及 architecture:public-component-api 审查 导出的 transport 被视为私有,或 transport 的使用被视为组件准入

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