跳转至

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