跳转至

图标解析与组件插槽

{
  "scope": "global",
  "triggers": {
    "component-slots": [
      "INV1",
      "INV2",
      "INV3",
      "INV6",
      "INV7",
      "INV10",
      "INV11",
      "INV12"
    ]
  }
}

本记录定义了共享图标与组件自有图标角色如何相互配合。它是已批准的目标架构。现有的扩展键将继续有效,直到另行做出的兼容性决策改变它们。

目的

主题作者应当能够更改某个组件角色所使用的图标,而无需更改同一共享图标的每一处使用。

系统需要两个相互独立的选择:

  1. 组件角色使用哪个共享图标名称;以及
  2. 活动主题为该共享图标名称使用哪份图稿。

将这两个选择分开,可避免把每一个组件细节都变成一个新的全局图标名称。

当前基线

当前 main 拥有一个共享的 IconName 注册表,并且也支持带命名空间的扩展键。某些组件自有的图稿直接使用这些扩展键。本记录不会使这些已发布行为失效,也不要求对其进行迁移。

目标模型为未来的组件角色增加了一条规则:新的语义组件插槽使用 componentIcons。每个 Core 插槽都记录在其所属组件的契约中,或记录在引入该插槽的系统规范中(chat-send-button-send 对应 spec:AST-032 FR2)。Selector 的选中选项标记由 check 指示器绘制,因此它不是组件图标插槽。已发布的扩展键仍然受支持,直到另行做出的兼容性决策改变它们。本记录不决定任何现有组件的最终结果。

系统模型

共享图标解析

IconName 是共享语义图标名称的封闭集合,例如 check、close 和 chevronDown。现有的扩展键与该集合共存。

通用解析器按以下顺序选择图稿:

  1. 活动主题的 icons[name] 条目;
  2. 进程级的 registerIcons() 条目;以及
  3. defaultIcons 中的匹配条目。

条目可以是 React 节点,也可以是接收 {size, variant} 的纯同步函数。

如果一个静态条目是 nullish,则会继续向下查找下一个来源。一旦选定了函数条目,其结果在本次解析中就是最终的:nullish 结果不会渲染任何字形,也绝不会继续回退,因此图稿永远不会混合两个来源。component:Icon 提供解析后的尺寸,以及活动主题列出的变体;若没有可列出的变体,则提供 undefined。主题提供的条目(包括继承得到的条目)仅当定义它的主题也列出该变体时,才会收到变体。

本记录不改变通用解析器接受的共享键或扩展键。活动主题的选择方式由主题应用逻辑负责。icons 的规范化和继承方式由主题编写逻辑负责。Icon 组件契约负责其公共源模式、渲染、尺寸、颜色和无障碍性。

类型化的组件自有插槽

组件图标插槽表示某个组件内部的一个稳定用途。它不是用来命名图稿的。

公共的 @astryxdesign/core/Icon 子路径拥有一个可扩充的映射:

// Public @astryxdesign/core/Icon module
export interface ComponentIconSlotMap {}

export type ComponentIconSlotName = keyof ComponentIconSlotMap & string;

export type ComponentIconRequest = Readonly<{
  icon?: IconName | null;
  variant?: IconVariant;
  size?: 'xsm' | 'sm' | 'md' | 'lg';
}>;

export type ComponentIconValue<State> =
  | IconName
  | null
  | ComponentIconRequest
  | ((state: Readonly<State>) => ComponentIconRequest | null | undefined);

export type ComponentIconMap = {
  [Slot in ComponentIconSlotName]?: ComponentIconSlotMap[Slot] extends true
    ? IconName | null | ComponentIconRequest
    : ComponentIconValue<ComponentIconSlotMap[Slot]>;
};

对于无状态插槽,或对于列出该插槽 readonly 状态字段的对象类型,插槽的映射值为 true。上面的类型形状是概念性的;公共名称和精确的映射类型属于实现。

接口必须声明在消费者要扩充的公共模块中。如果接口只在实现文件中声明并从公共子路径重新导出,则不会扩展消费者使用的类型。运行时解析器代码会从该映射的公共所有者处导入映射。

外部组件包通过扩充同一个公共 @astryxdesign/core/Icon 模块来添加它们的插槽:

declare module '@astryxdesign/core/Icon' {
  interface ComponentIconSlotMap {
    'example-panel-dismiss': true;
    'example-nav-item-leading': {selected: boolean; disabled: boolean};
  }
}

Core 插槽以同样的方式在公共模块中声明。插槽使用 <component-kebab>-<semantic-role> 命名。该角色描述图标存在的原因,而不是其当前的形状或方向。

defineTheme({componentIcons}) 将组件插槽映射为共享的 IconName、null、静态的部分请求;对于有状态插槽,则映射为接收插槽状态的纯同步函数并返回部分请求。它与 defineTheme({icons}) 相互独立:

defineTheme({
  name: 'brand',
  iconVariants: ['outline', 'filled'],
  componentIcons: {
    'example-panel-dismiss': 'close',
    'example-nav-item-leading': ({selected}) => ({
      variant: selected ? 'filled' : 'outline',
    }),
  },
  icons: {
    close: <BrandCloseIcon />,
  },
});

插槽映射说明组件角色使用哪个共享含义、变体和尺寸。图标映射说明哪个图稿绘制该共享含义。

组件插槽优先级

组件按以下顺序解析带图标的角色:

  1. 组件暴露了消费者提供的实例 prop 时,使用该 prop;
  2. 最近的活动主题的 componentIcons[slot] 条目;以及
  3. 组件声明的回退 IconName | null。

undefined 表示“使用下一个回退”。null 表示“不渲染图标”。映射到的 IconName 会继续进入共享图标解析流程。

请求按字段逐个应用。请求中的 icon 替换回退名称;icon: null 或 null 结果表示不渲染图标。缺少 icon 时保留回退名称,缺少 variant 时保留组件原本会请求的变体(或无变体),缺少 size 时保留组件的尺寸。undefined 结果不改变任何内容。请求中的 variant 和 size 应用于最终渲染的名称。未知的 icon、主题未列出的变体,或不支持的 size 都被视为缺失,并产生一条仅限开发环境的警告。

共享解析器模块一致地应用以下顺序:

  • 一个函数将插槽、其状态及其回退解析为共享的 IconName | null、变体和大小的请求;
  • 另一个函数通过共享图标解析将该请求解析为实际图形;
  • 客户端 hook 则从当前激活的主题中解析相同的插槽、状态和回退。

组件,包括那些扩展 ComponentIconSlotMap 的包,将其插槽状态传递给这些解析器,而不是直接读取 componentIcons。解析器是主题插槽函数的唯一调用方。解析器不拥有组件的插槽名称、状态含义、回退或渲染规则。

指示器保持独立

组件通过指示器绘制的有状态控件标记,例如选中勾选标记、单选按钮或复选框的方框,不属于组件图标插槽。指示器接收其所属组件族的状态,主题通过 defineTheme({indicators}) 按名称替换它。一个视觉元素绝不会同时既是指示器又是 componentIcons 插槽。

本文档规定了激活主题的 componentIcons 映射的含义。主题编写架构拥有 DefineThemeInput、规范化和 extends。主题编译负责在构建输出中保留规范化后的映射。

已知偏差

  • NumberInput 步进器图标。 当前的 NumberInput 通过通用扩展键而不是 componentIcons 解析其步进器。这一已发布的行为仍受支持,并且不构成新组件插槽的先例。
  • 所有者: 一旦该组件契约存在,即为 component:NumberInput。
  • 退出条件: 一项单独评审过的迁移在保留已发布调用者和主题覆盖的同时使用组件插槽模型,或者遵循明确批准的破坏性变更路径。

本文档不选择迁移设计或时间线。

边界与不变量

  • INV1 — 共享名称与组件角色相互分离。 IconName 拥有共享的语义含义。ComponentIconSlotName 拥有组件特定的用途。
  • INV2 — 插槽是类型化的,并由所有者声明。 每个 Core 插槽都列在 ComponentIconSlotMap 中。外部包扩展该映射,而不是添加无主的 Core 字符串。
  • INV3 — 插槽映射到共享含义。 componentIcons 的值可以是 IconName、null、针对 icon、variant 和 size 的静态部分请求,或者对于有状态插槽,可以是一个以插槽声明状态为输入、返回此类请求的纯同步函数。它绝不是具体的图形作品。
  • INV4 — Null 会抑制插槽。 componentIcons[slot] = null 表示有意不渲染任何图标。缺失的映射将使用组件回退。
  • INV5 — 每个插槽都声明一个回退。 拥有该插槽的组件声明一个 IconName | null;主题无需重复默认值。
  • INV6 — 解析顺序是稳定的。 实例内容优先于主题插槽映射。插槽映射先选择共享名称,然后共享注册表再选择具体图形。
  • INV7 — 组件插槽不会扩大共享名称集合。 添加插槽不会扩大 IconName。
  • INV8 — 组件行为仍由组件保持。 状态含义、变换、放置、颜色、无障碍性和控件几何形状仍归渲染该插槽的组件所有。主题插槽请求可以选择该插槽的 Icon 大小和变体;组件自身的大小和变体作为回退。插槽大小绝不会改变控件的高度、触摸目标或外部尺寸。
  • INV9 — 主题生命周期保持单一所有者。 本文档定义 componentIcons 条目表示什么。主题编写拥有其规范化和继承;主题应用拥有激活主题的选择。
  • INV10 — 现有键共存。 已发布的插槽和扩展键保持支持,直到单独的兼容性决策改变它们。新的 Core 插槽使用 ComponentIconSlotMap 和 componentIcons。
  • INV11 — 选定的函数答复该请求。 一旦选定了函数条目或插槽函数,其结果即为该次解析的最终结果。公共主题读取永远不会调用或返回插槽函数。
  • INV12 — 指示器与插槽不重叠。 由指示器绘制的视觉元素通过 indicators 替换;它不会同时也是 componentIcons 插槽。

本文档不拥有以下内容:

  • DefineThemeInput、主题规范化或 extends;这些属于主题编写架构;
  • 激活主题的选择;这属于主题应用架构;
  • Icon 的公共源模式、渲染、视觉结构、大小、颜色或无障碍名称 API;这些属于 Icon 组件契约;
  • 通过公共组件 props 传入的由使用者编写的图标内容;
  • 针对图标绘制或状态的 CSS 主题目标;
  • 有状态指示器渲染器的替换;或
  • 组件所选字形的视觉设计。

组件本地文档

架构文档拥有共享规则。组件所有者会在本地为每个插槽编写文档。

组件中的 .doc.mjs 主题条目记录以下内容:

  • 插槽名称;
  • 其回退 IconName | null;
  • 对于有状态插槽,其状态字段;以及
  • 对该角色以及 null 是否可能隐藏它的简短说明。

组件规范记录主题作者必须理解的行为,例如依赖于状态的渲染、放置、无障碍所有权和兼容性要求。它不会复制通用的解析算法。

消费者的图标 props 仍作为组件 API 记录在文档中。除非组件还承诺提供独立的稳定主题级角色,否则它们不会被列为 componentIcons 插槽。

变更耦合

  • 添加一个 Core 插槽,需要更新公共 @astryxdesign/core/Icon 模块中的 ComponentIconSlotMap、其拥有组件的源码、本地文档、解析器测试和组件测试。
  • 添加一个包拥有的插槽,会从该包扩充公共 @astryxdesign/core/Icon 模块,并添加相同的所有者本地文档和测试。
  • 更改插槽的回退或优先级属于兼容性变更,因为主题可能省略该插槽并依赖旧结果。
  • 添加、重命名、移除或重新解释已发布的插槽状态字段属于兼容性变更,因为主题解析器会读取它。
  • 重命名、移除或重新解释已发布的插槽或扩展键需要明确的兼容性计划,并且在无法保留现有行为时需要允许的破坏性变更路径。
  • 更改 componentIcons 的编写结构、规范化或继承时,需要更新主题编写文档及其测试。更改构建输出时,需要更新主题编译文档和一致性测试。
  • 更改激活主题的选择时,需要更新主题应用文档及其测试。
  • 更改 Icon 的公共源模式或渲染时,需要更新 Icon 组件契约及其测试。
  • 将组件特定的键直接添加到通用 Icon API 需要架构评审;这不是添加组件插槽的默认方式。

代码所有权

  • 公共的 @astryxdesign/core/Icon 子路径负责 ComponentIconSlotMap 以及消费者可增强的公共槽位类型。
  • packages/core/src/Icon/globalIconRegistry.tsx 负责共享图标解析和组件槽位解析,包括对主题槽位函数的唯一调用。
  • packages/core/src/Icon/useIcon.ts 负责共享名称和组件槽位的活动主题客户端解析。
  • Icon 组件及其组件契约负责公共源模式、渲染、尺寸、颜色和无障碍性。组件在将结果传递给 Icon 之前解析其语义槽位。
  • architecture:theme-authoring-contract 负责 DefineThemeInput、规范化主题数据和 extends,包括集成独立的 componentIcons 映射。
  • architecture:theme-application 负责活动主题的选择和查找。
  • architecture:theme-compilation 负责在构建输出中保留规范化主题数据。
  • 每个组件负责其槽位含义、回退、状态相关渲染、无障碍性以及消费者覆盖行为。
  • CLI 和 docsite 工具暴露所有者声明的槽位元数据,而不凭空发明新的槽位语义。

规格决策

本记录整合了现有的共享注册表行为和已批准的带类型组件槽位模型。spec:AST-087 的决策 2、4、5、6 和 10 添加了函数条目、静态槽位请求和状态解析器槽位请求、指示器边界、最终函数结果,以及仅由槽位解析调用的槽位函数。

验证

不变量 证据 失败信号
INV1, INV3, INV6 注册表解析器测试和一个渲染后的组件夹具 组件槽位直接解析具体图形,或跳过了共享图标解析
INV2, INV5 类型测试加上组件 .doc.mjs 元数据检查 Core 槽位是未类型化字符串,或没有所有者/回退
INV4 使用 componentIcons[slot] = null 的解析器和组件测试 null 映射会穿透并仍然渲染图标
INV7 共享名称类型和注册表快照测试 添加组件槽位会扩大 IconName
INV8 具有状态和槽位尺寸的代表性组件所有者测试 主题必须知道组件渲染细节,否则槽位尺寸会移动控件几何
INV9 主题编写、应用和编译的所有者测试 本记录引入了第二条规范化路径或活动主题路径
INV10 已发布键兼容性夹具和新槽位负向测试 某个已发布键在没有单独兼容性决策的情况下停止工作
INV11 针对函数条目、槽位函数和读取的解析器测试 空值(nullish)函数结果会穿透到另一个来源,或者一次读取返回一个函数
INV12 槽位和指示器清单检查 同一个视觉元素既可作为指示器访问,也可作为 componentIcons 槽位访问
文档 组件元数据和生成的 CLI/docsite 夹具 可主题化的槽位无法连同其所有者、回退和用途被发现

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