组件尺寸级联架构¶
目的¶
用户应在组件拥有的组内遇到一致的控件尺寸,而不需要每个子元素重复传入相同的 prop。显式的子元素选择仍应胜出,而位于已声明级联之外的组件必须保持其自身的尺寸契约。
本记录拥有 Astryx 标准元素尺寸级联的共享运行时优先级和范围。组件与家族契约决定参与、几何形状以及有意的覆盖行为。
系统模型¶
标准级联有三个角色:
- 一个参与型消费者(participating consumer) 接受标准的
sm | md | lg元素尺寸轴,并通过共享的尺寸上下文解析它。 - 一个提供方所有者(provider owner) 为文档记录的合格后代建立默认尺寸。
- 一个组件默认值(component default) 在没有显式值或继承值适用时提供回退。
消费者按以下顺序解析出一个有效尺寸:
- 显式组件 prop;
- 最近的活跃提供方值;以及
- 消费者文档记录的组件默认值。
有效尺寸随后流经消费者自身的几何形状、渲染状态和主题契约。本架构不决定这些组件特定的映射。
边界与不变量¶
- 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