ChatComposerTokenElement 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | ChatComposerTokenElement 需要一个必填的 token:结构化的,即 value 加上 Badge props,其中只有 label、variant 和 icon 渲染,其余的被接受但忽略;或自定义的 {value, render}、ref、xstyle、className、style 以及中性 span props。 |
| 行为 | 结构化 token 渲染 Badge 内容;自定义 token 渲染调用方内容。两者都保留序列化值标记,并在置于 contenteditable composer 内部时保持不可编辑。 |
| 最终用户影响 | Token 标签和调用方内容保持可见,而不会变成可编辑文本。 |
| 构建者影响 | 无。 |
| 兼容性/就绪状态 | 记录已发布行为;无公共变更。AR1 以及 FR1、FR2 和 FR4 的部分证据仍待补充(从源代码读取;参见验证映射)。 |
| 评审检查 | 拒绝丢失序列化值、变为可编辑、丢弃已接受的 span props 或改变结构化/自定义渲染划分的 token 包装器。 |
| 约束规则 | architecture:public-component-api/INV1, INV5–INV6, INV8–INV9, INV12; architecture:component-test-sufficiency/INV1–INV8, INV10–INV11; spec:AST-029/FR3–FR5, FR7。 |
此表是评审预览;下文正文具有权威性。
设计意图¶
ChatComposerTokenElement 在编辑器插入机制之外渲染一个已定义的 ChatComposerToken。它提供与 ChatComposerInput 使用的相同序列化标记,同时将结构化 Badge 展示或自定义内容留给其现有所有者。
兼容性与迁移¶
- 已发布的默认值保留:
yes - 兼容性类别:记录已发布行为;无公共变更
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 承载
data-astryx-token和 token 序列化值的 span。 - 在 contenteditable 区域内组合时,保持该包装器不可编辑。
- 选择现有的结构化 Badge 或自定义渲染分支。
- 转发包装器 ref 及已接受的中性 span props。
不拥有 / 非目标
- Token 值语法或产品语义。
- Badge 颜色、图标或尺寸。
- 调用方自定义内容中的可访问性语义和交互行为。
- Token 插入、删除、展开或 composer 选择管理。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 默认值 | 所有者 | 稳定性 |
|---|---|---|---|---|---|
| token 形式 | 结构化 Badge 配置;自定义渲染函数 | 在不改变序列化的前提下选择调用方内容。 | 无;必填 | component:ChatComposerTokenElement |
稳定 |
| 序列化值 | 调用方提供的非空或空字符串 | 存储在 data-astryx-token-value 中的值,用于 composer 序列化。 |
无;必填 | 经由本组件传递的调用方值 | 稳定 |
| 包装器表面 | ref;DOM/data/ARIA props;className/style/xstyle | 扩展序列化 span 而不替换所属标记。 | 省略 | architecture:public-component-api |
稳定 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 根元素 MUST 暴露 data-astryx-token 和所提供的精确 token.value,并且 MUST 保持 contentEditable={false}。 |
当前源代码、文档和测试 |
| FR2 | 结构化 token MUST 将 label、variant 和 icon 的渲染委托给 Badge,且不改变 token 值。 | 已发布的实现和公共 token 类型 |
| FR3 | Custom tokens MUST 渲染调用方函数的结果,且不添加组件自有的语义或交互。 | 已发布的实现和公共 Token 类型 |
| FR4 | 已接受的 ref、DOM/data/ARIA、className、style 和 xstyle 输入 MUST 到达根 span 并在其上组合,同时组件自有的序列化属性保持优先级。 | architecture:public-component-api/INV5–INV6, INV8 |
允许的变体¶
- 结构化 Badge 标签、变体和图标仍由调用方提供。
- 自定义渲染内容及其语义仍归调用方所有。
- 该包装器可以在 contenteditable 表面内部或外部使用。
代表性状态¶
| 状态 | 所需不变量 | 允许的变体 |
|---|---|---|
| 结构化 token | 可见的 Badge 内容和精确的序列化值。 | Badge 标签、变体和图标。 |
| 自定义 token | 调用方输出和精确的序列化值。 | 任何调用方所有的 React 节点。 |
| 扩展包装器 | 中性 DOM props 和 ref 到达 span,且不替换自有标记。 | 受支持的 BaseProps 值。 |
可访问性契约¶
- AR1 — 无自有语义。 包装器除已接受的调用方 props 外,不拥有任何交互角色或可访问名称。
- AR2 — 可见内容。 结构化 Badge 文本保持为可见内容;自定义内容语义仍归调用方所有。
- AR3 — 原子化 token。
contentEditable={false}使 token 嵌套在编辑器中时保持原子性的不可编辑状态。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权限 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| token 包装器 | 仅内联对齐 | 当前源 | 支持 | FR1, FR4 |
| 结构化内容 | Badge 呈现 | component:Badge |
支持 | FR2 |
| 自定义内容 | 调用方所有的呈现 | 调用方 | 支持 | FR3 |
包装器不会绘制组件自有的视觉表面,也不会引入公共主题目标。Badge 主题仍归 Badge 所有,自定义内容仍归调用方所有。
系列与系统关系¶
component:ChatComposerInput拥有插入、序列化遍历、删除和选择行为。architecture:public-component-api拥有公共 props 类型、ref 和 BaseProps 组合。architecture:component-test-sufficiency拥有已建立的公共序列化接缝的直接证据。spec:AST-029拥有本记录的验证映射所遵循的审计证据清单。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1–FR3, AR2–AR3 | ChatComposerTokenElement.test.tsx;直接 Storybook 故事 |
结构化和自定义 token | 标记/值消失、包装器变为可编辑、或出现错误的渲染分支。 | audit:ChatComposerTokenElement/behavior |
| FR4 | 聚焦的 ref 和 DOM 透传测试;公共类型检查 | ref、ARIA/data props、样式接缝 | 已接受的输入被丢弃,或自有序列化标记被替换。 | audit:ChatComposerTokenElement/api |
| 渲染状态 | 直接 Storybook 故事 | 受支持主题下的 Badge 和自定义内容 | 不可达的故事未通过故事检查。 | audit:ChatComposerTokenElement/rendered |
从源码读取,尚无聚焦测试:
- AR1:包装器不会自行添加任何角色或可访问名称。
- FR1:当调用方传入
contentEditable时,其保持为false。 - FR2:
variant和icon到达 Badge。 - FR4:
className、style和xstyle在 span 上组合。
决策日志¶
未记录任何组件本地决策。
未决问题¶
无。
内容边界¶
本文件不重复消费者示例、当前审计分数、Badge 策略或 ChatComposerInput 选择机制。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx