跳转至

搜索状态词汇表系统规范

{
  "scope": "global",
  "triggers": {
    "public-api": [
      "FR1",
      "FR2",
      "FR3",
      "FR4",
      "FR5",
      "FR6",
      "FR7",
      "DEC-1",
      "DEC-2",
      "DEC-3",
      "DEC-4"
    ],
    "accessibility": ["AR1", "AR2"],
    "compatibility": ["FR7"]
  }
}

契约一览

领域 契约
公共契约 一个词汇表,而不是一种结构。"查询未匹配任何内容"是 emptySearchText,接受 ReactNode,存在于每个拥有该状态的组件上;"这里根本没有内容"保持为 emptyText,两者永不合并(FR1、FR2、DEC-1)。需要查询的能力在自身的 prop 名称中明确体现,其处理函数是它唯一的开关(FR5、DEC-3)。没有配置对象(DEC-2)。
行为 不变。由谁解析查询,取决于谁拥有选项,且不会在每个组件上重复说明:持有自身选项集的组件会过滤这些选项,并暴露一个布尔值来显示输入框;呈现的选项本身就是查询结果的组件需要一个必填的 searchSource(FR4、DEC-2)。
最终用户影响 用户在任何地方都会遇到同样的死胡同,也可以获得同样的出路:将 emptySearchResultsText 扩展为 ReactNode,使产品可以在 Tokenizer 的空结果中放入链接或创建行,就像在 Selector 中已经能做的那样。配置不完整的创建行不再静默渲染为空(FR5)。调用方提供什么内容,就会播报什么内容(FR3、AR1)。
构建者影响 只需学习一次重命名:emptySearchResultsText 变为 emptySearchText。没有 prop 移动,没有对象字面量,没有重构。所有已发布的 prop 在整个周期内继续正常工作。
兼容性/就绪状态 并非新增式变更,但改动很小:三个组件上的一个 prop 被重命名,其类型从 string 扩展为 ReactNode。没有必填 prop 发生移动。替换优先的周期及其成本见 Migration and compatibility;FR7 是唯一约束它的需求。权威级别:draft。三个 owner 问题仍未解决;其中任何一个都不会改变 FR1 或 FR2。
审查检查 拒绝为这些 prop 已表达的某个状态另取第二个名称;拒绝用布尔值门控处理函数;拒绝在兄弟 prop 缺失时渲染为无效的能力;拒绝无法到达辅助技术的空状态值(AR1);拒绝仅以 placeholder 命名的查询输入(AR2)。
治理规则 准入及每个输入只承担一项职责遵循 spec:AST-002 的 FR1、FR4、FR15、FR16 和 spec:AST-002/DEC-1、DEC-6;共享命名语法和已发布 API 生命周期遵循 architecture:public-component-api 的 INV1、INV2、INV3、INV9;废弃与清理遵循 spec:AST-017 的 FR28–FR31;查询输入周边的字段外观遵循 family:input-fields,此处不变。

此表是审查投影;下文正文具有权威性。

意图

键入以收窄列表是用户会做的一件事,而 Astryx 用七种方式来表达它。一个在 Selector 上用过 hasSearch 的构建者,在 Tokenizer 上找不到 hasSearch;一个在 Typeahead 上设置过 emptySearchResultsText 的构建者,会在 CommandPalette 上遇到 emptySearchText,且类型不同。对使用产品的用户来说,没有任何东西被破坏;但每一个新的搜索相关能力都会以另一个扁平 prop 的形式落到某个组件上,带着自己的名字,而下一个组件会复制它恰好读过的那个邻居。

这份记录只负责一个答案:为键入查询所产生的各种状态提供一套共享词汇表,且不进行重构。 它固定了"查询未匹配任何内容"的名称和类型,让该状态与"这里根本没有内容"保持区分,并说明了没有查询就无法工作的能力如何声明这一依赖。

早期的草案曾提议将这些 props 收集到一个以对象为值的 search prop 中。这一提案在 DEC-2 中被否决:它本会让七个组件付出九次弃用的代价,其中四次涉及必填 prop,而解决的只是整洁性问题,而不是一个使用 Astryx 产品的人会遇到的问题。

触发原因是 #6829,它提议在 MultiSelector 上增加 hasCreate + onCreate——这是一个已带有三个相关 prop 的组件上出现的第六个和第七个搜索相邻 prop,而这些名称 Tokenizer 已经以不同契约在使用了。该 pull request 被本裁决阻塞,它最终采用的形态将成为后续每个组件复制的形态。

所有权边界

拥有

  • 每个类型化查询所产生的可观察状态的名称与类型,并在所有具有该状态的组件间共享。
  • “查询未匹配任何内容”与“这里根本没有内容”是不同名称下的不同状态,任何一方都不会吞并另一方。
  • 一个没有查询就无法运作的能力如何声明该依赖,以及由什么来门控。
  • 新提出的搜索相关 prop 是加入这一词汇表,还是为它已表述的内容引入第二个名称。
  • 该安排在空结果消息和查询输入名称上必须维持的可访问性下限。

为何现有记录无法承接它

  • spec:AST-002 是 current 且已获批;一条记录只携带一个 authority 值,因此向其中添加未批准的声明会把它们呈现为已批准(architecture:knowledge-contracts INV1、INV14)。它还拥有另一个不同的事实——公共 API 是否获准存在——而且其 FR17 和 DEC-7 都用自己的话说明 组件 prop 与事件命名保持分离。关于组件 prop 形态和名称的规则,在结构上位于 AST-002 所声明内容的范围之外。本记录位于 AST-002 FR1 和 FR4 的下游:准入仍然决定搜索能力是否存在,而本记录只决定它被书写在何处。
  • architecture:public-component-api 是 current 且已获批,并存在同样的权威性问题。它持有共享的命名语法(INV2),并通过 deciding_specs 链接其人工裁决——spec:AST-002/DEC-1、spec:AST-005/DEC-1、spec:AST-012/DEC-1。新的跨组件裁决应放在它所链接的某个 spec 中,而不是放在它内部;其自身的 INV18 边界将调用方可观察到的行为保留在产品契约中。
  • family:input-fields 是 current 且拥有其成员共享的字段外观——标签、状态、尺寸、主题。本记录所约束的两个组件 BaseTypeahead 和 CommandPalette 并非其成员,也不是输入字段;CommandPalette 是一个对话框。它们不是同一个同级家族,因此该词汇表由这里拥有,而非由那个契约拥有。
  • contributing:api-conventions 和 wiki 的 Prop Naming 一节记录了布尔值、回调、枚举、方向以及 HTML 冲突的约定。它们没有涉及同一个状态在跨组件中保持同一个名称;而指南并不是权威记录。一旦本记录成为 current,两者都需要作出修订。
  • 六个组件记录将各自私下持有同一决策的一份副本,这是 architecture:knowledge-contracts INV2 所禁止的。component:MultiSelector 已经在以 FR10 / DEC-3 起草这样一份副本。

非目标

  • 匹配质量。 模糊匹配、排序、高亮、分词和变音符号折叠不在此处裁定。FR4 只固定组件自行过滤这一模式的下限。
  • 任何特定组件是否应获得搜索或创建行。 这是 spec:AST-002 的准入决定,逐案处理。
  • PowerSearch。 它的查询是结构化 field/operator/value 表达式,不是用于收窄列表的类型化字符串。它的 maxSearchResults 和逐字段的 searchSource 被引作扩散的证据,但不受本记录约束(OQ4)。
  • CommandPalette 上的 emptyBootstrapText。 “尚无查询,且默认集合为空”与“查询未匹配任何内容”是不同可观察状态;它仍是顶层 prop。
  • ChatComposerInput 上的触发菜单配置。 其每个 per-trigger 对象都带有 emptySearchResultsText,因此 FR1 覆盖到它们;但这个嵌套重命名是否随本记录的周期一并处理,属于 OQ4。
  • 内部过滤实现。 满足本契约的等价内部实现仍然有效。内部模块、文件、函数名、算法、数据结构、存储布局、清单、日志、锁、事务协议以及 CI 作业/工作流拓扑都属于架构或实现范畴,除非调用方或互操作系统刻意依赖该确切机制作为公共协议。

证据:当前 core 中所有搜索形态的 prop

在本记录的基础提交上读取 packages/core/src。此表是 FR1–FR5 的证据;它不是迁移计划。

组件 查询输入因何存在 谁解析查询 占位符 “未匹配任何内容” 调用方可观察到的查询 创建入口 其他搜索形态的 props
Selector hasSearch?: boolean — 默认 false 组件自身,基于自己的 options searchPlaceholder?: string — 'Search…' emptySearchText?: ReactNode — 'No results found' 否 — searchQuery 是内部 useState — emptyText?: ReactNode('No options',一个不同的状态)
MultiSelector hasSearch?: boolean — 默认 false 组件自身,针对其自己的 options searchPlaceholder?: string — 'Search…' emptySearchText?: ReactNode — 'No results found' 否 — searchQuery 是内部的 useState hasCreate + onCreate 拟新增于 #6829 emptyText?: ReactNode('No options')
Tokenizer searchSource: SearchSource<T> — 必填 调用方的数据源 placeholder?: string — 输入即控件 emptySearchResultsText?: string — 'No results found' onChangeQuery?: (query: string) => void hasCreate?: boolean — 组件负责生成 token minQueryLength?: number(1)、debounceMs?: number(150)
Typeahead searchSource: SearchSource<T> — 必填 调用方的数据源 placeholder?: string emptySearchResultsText?: string onChangeQuery?: (query: string) => void — minQueryLength?: number、debounceMs?: number
BaseTypeahead searchSource: SearchSource<T> — 必填 调用方的数据源 placeholder?: string emptySearchResultsText?: string onChangeQuery?: (query: string) => void __queryEntries — 带下划线前缀,@internal minQueryLength?: number、debounceMs?: number
CommandPalette searchSource: SearchSource<T> — 必填 调用方的数据源 CommandPaletteInput.placeholder — 'Search…' emptySearchText?: ReactNode — 'No results' 通过 input 插槽的 value / onValueChange — emptyBootstrapText?: ReactNode('Type to search')
ChatComposerInput triggers[] 中每个条目对应一个 searchSource 调用方的数据源,按触发词区分 —(composer 自身的 placeholder) triggers[].emptySearchResultsText?: string — — triggers[].loadingText、triggers[].menuLabel、debounceMs
PowerSearch 结构化筛选表达式,而非键入式查询 调用方按字段提供的 searchSource?(值选择器) 内部(@astryx.powersearch.placeholder) — — — maxSearchResults?: number

上述表格呈现出四个漂移轴,每个都是某个人独自做出的决定:

  1. “无匹配结果”的两种命名:Selector、MultiSelector 和 CommandPalette 使用 emptySearchText;Typeahead、BaseTypeahead、Tokenizer 以及每个 ChatComposerTrigger 使用 emptySearchResultsText。
  2. 同一消息的两种类型:第一组使用 ReactNode,第二组使用 string。能够向某个组件传入元素的构建者,却无法向相邻组件传入同样的元素。
  3. 它的三种默认值:'No results found'、'No results',以及——因为 Selector 和 MultiSelector 还带有顶层 emptyText——相邻状态的 'No options'。
  4. 前缀只出现在搜索可选之处。Selector 和 MultiSelector 之所以写 searchPlaceholder,是因为它们还有一个触发器占位符;Typeahead 和 Tokenizer 之所以写 placeholder,是因为查询输入本身就是控件。两者在局部都是正确的,而这恰恰就是为什么没有任何组件能靠自身修复这个问题。

在核心包之外,packages/lab 也复制了这一漂移:TransferList 采用了 hasSearch + searchPlaceholder + searchLabel,ChatEmojiPicker 则采用 searchLabel。Lab 并非稳定的公共承诺,因此本记录不对其加以约束;它只是表明这种模式会通过复制而扩散的证据。

关于既有先例的两个说法,予以更正

  • searchConfig 不是组件属性,也不是此形态的先例。它是 Table/plugins/filtering/useTableFiltering.tsx 中的一个参数和插件配置字段,持有 PowerSearchConfig——即筛选构建器的结构化字段/运算符/值配置。它配置的是另一个概念。
  • 该仓库中此形态的真正先例是 ChatComposerTrigger。ChatComposerInput 的 triggers[] 中每个条目都是一个对象,承载着 searchSource、renderItem、onSelect、emptySearchResultsText、loadingText 和 menuLabel——一次触发词的查询的全部配置集中在一个值中,且键名大多去掉了外层名称已提供的前缀。它行之有效、已经发布,也从来没有人要求将其扁平化。

公共 API 与概念

概念 闭合取值或状态 含义 默认值 负责人 稳定性
emptySearchText ReactNode 组件在查询未匹配到任何内容时显示的内容。在所有地方都使用同一个名称和同一种类型(FR1) 按组件而定 spec:AST-056 提议中
显示输入框 一个布尔值,或必填的 searchSource 组件如果持有自己的选项集合,就暴露一个布尔值;如果其选项本身就是查询结果,则接受一个数据源 按组件而定 该组件本身 已发布
仅查询才有的能力 一个名称表明需要查询的 handler handler 的存在即为开关;旁边不再设有布尔值(FR5) 缺省 spec:AST-056 提议中
"完全没有选项" 组件自身的顶层 emptyText 与"查询未匹配到任何内容"是两种不同的可观察状态;本记录不改变这一点 该组件本地化的默认值 该组件本身 稳定
获取调优 minQueryLength、debounceMs、加载文本 不由本记录规定位置;它们属于负责获取的一方,OQ5 询问它们是否应移入组件内部 按组件而定 该组件本身 稳定

需求

行为契约

ID 不变式 依据 验证状态
FR1 在所有带类型化查询的组件中,一个可观察状态只能有一个 prop 名称和一种类型。"查询未匹配到任何内容"即 emptySearchText,接受 ReactNode。emptySearchResultsText 解析为该状态,其 string 类型被放宽,因此调用方可以传入元素。任何组件不得以其他名称或类型来命名或定义此状态。 DEC-1;architecture:public-component-api INV2 提议中;main 上尚无证据
FR2 "查询未匹配到任何内容"与"组件根本未获得任何选项"是两种不同的状态,必须能以不同名称分别表达:emptySearchText 和 emptyText。Selector 和 MultiSelector 已经同时声明了二者,因此任何一个名称都不能吞并另一个;只提供其中一种状态的组件,仍必须使用与其所表达状态相匹配的名称。 DEC-1;spec:AST-002 FR16 提议中;已发布行为,未作规定
FR3 调用方为空白状态提供的任何内容,都必须传达给操作该组件的人,无论是视觉方式还是非视觉方式。宣布此状态的组件必须宣布它渲染了什么。在渲染调用方元素的同时宣布内置默认值,是一种缺陷,而非回退方案。 AR1;architecture:interaction-modality 提议中;main 上存在缺陷(见 AR1)
FR4 由谁解析查询,取决于谁拥有选项集合,且不在每个组件中重复说明。持有自身选项集合的组件自行解析查询,至少对每个选项的显示标签进行不区分大小写的匹配,并暴露一个布尔值来开启查询输入。所展示选项本身就是查询结果的组件,则接受必填的 searchSource。两种组件都会达到相同的可观察状态:收窄后的列表、空结果,以及 emptyText。 DEC-2;spec:AST-002 FR16 提议中;已发布行为,未作规定
FR5 没有类型化查询就无法运作的能力,必须只有一个开关,并且必须通过组件的主变更回调(primary change callback)上报,附带一个描述变更类型的描述符,而不是通过它自己的 handler prop。调用方绝不能能够表达出一种"既不渲染也不上报"的配置——hasCreate && hasSearch && onCreate != null 在任一条件缺失时就会允许这种情况。在没有查询输入的组件上启用该能力,必须在开发模式下发出警告,而不是静默失败。 DEC-3;spec:AST-002 FR15(绝不静默渲染损坏状态) 提议中;main 上尚无证据
FR6 一项新的搜索相关能力只有通过 spec:AST-002 针对本记录被接纳,否则根本不被接纳。一个名称中包含 search 的新顶层 prop MUST 用本记录所固定的词汇来命名其管辖的状态或能力,并且 MUST NOT 为这些 props 已表达的某个状态引入第二个名称。 DEC-4;spec:AST-002 FR1、FR5、DEC-1 已提议;main 上尚无证据
FR7 本记录重命名的每个 prop 都是已发布且存在受影响使用方的公开表面,因此它 MUST 遵循 spec:AST-017 FR28–FR31:替代品先发布,旧用法在重叠期内保持等价,移除则发生在声明的 minor 版本中,并附上指明替代品的 [breaking] Changeset。在两者并存期间,同时传入两者的组件 MUST 解析到新 prop,并且 MUST 触发一条开发警告。 architecture:public-component-api INV9;spec:AST-017 FR1、FR3、FR28–FR31 已提议;周期尚未开始

无障碍契约

  • AR1 — 空结果消息按原样传达给辅助技术。 无论 emptySearchText 在屏幕上渲染什么,MUST 都必须是面板变空时屏幕阅读器接收的内容。但当前并非如此:Selector 和 MultiSelector 会播报 typeof emptySearchText === 'string' ? emptySearchText : t('@astryx.selector.emptySearchResults'),因此当调用方传入一个元素——ReactNode 类型正是这样邀请的——辅助技术会静默播报默认字符串,而不是调用方自己的消息。接受 ReactNode(FR1)使组件有义务从中推导出可播报的字符串,或者文档化并要求提供单独的可播报形式;它不能播报屏幕上的人没有阅读的内容。
  • AR2 — 查询输入框有一个可访问名称,且该名称不是其占位文本。 占位文本就是占位文本,MUST NOT 作为输入框唯一可访问名称。组件提供名称:在 Selector 和 MultiSelector 中是本地化的 “Search options”,在 CommandPaletteInput 中是本地化的 “Search commands”。

平台支持

  • 支持的功能/引擎底线:所有受支持的渲染器和所有受支持的浏览器。这里没有任何功能依赖能力检查(capability check)。
  • 不支持的行为:无。无法满足 FR3 必需/可选规则的组件不会部分采纳该 prop;在规则为其确定之前,它保持现有 API。
  • 浏览器证据:DOM live-region 断言证明了渲染内容的来源,但不能证明辅助技术播报的内容或时机。任何改变播报内容或时机的采纳方,都应在 DOM 和可访问性树层面证明其路由、文本和触发次数;在 spec:AST-009 下建议以真实辅助技术观察作为后续验证。

迁移与兼容性

这不是新增式变更,且成本集中在一处。

已发布并存在受影响使用方的部分。 七个核心组件上的九个公开 prop:Selector 和 MultiSelector 上的 hasSearch、searchPlaceholder、emptySearchText;Tokenizer、Typeahead 和 BaseTypeahead 上的 searchSource、emptySearchResultsText;CommandPalette 上的 searchSource、emptySearchText;三个 typeahead 上的 onChangeQuery;Tokenizer 上的 hasCreate;每个 ChatComposerTrigger 上的 emptySearchResultsText。根据 spec:AST-017 FR1 和 FR3,以及 architecture:public-component-api INV9,移除或重新类型化其中任何一个都是破坏性变更。

必需项无需变动。 早期草案曾打算把 Tokenizer、Typeahead、BaseTypeahead 和 CommandPalette 上必需的 searchSource 折叠进一个对象,从而使这四个组件的每个现有调用点都在类型检查时失败。DEC-2 否决了该方案,因此整个迁移现在只是在四个 API 表面上重命名一个可选 prop,并放宽其类型。

本记录的建议:采用先发替代品的弃用周期。 不是无限期共存,也不是直接替换。

  • 一个 patch 在每个重命名组件上随附 emptySearchText,同时旧 prop 继续工作;该 patch 带有命名其替代品的 @deprecated,并且行为与之前完全一致(spec:AST-017 FR28、FR29)。在重叠期内,组件同时读取两者,新 prop 优先;发生冲突时,开发环境只发出一条警告(FR7)。
  • 移除发生在一个后续声明的 minor 版本中,并附带一个指明替代品的 [breaking] Changeset(spec:AST-017 FR31)。本记录不设定时间表;FR30 禁止将发布节奏解读为时间表。
  • 对于传入 string 的调用方,除了名称之外无需任何修改:类型只会放宽,因此所有现有值仍然有效。

每个选项的实际成本。

  • 带周期地弃用(推荐)。 在重叠期内,一个 prop 会变成两个:在 Tokenizer、Typeahead、BaseTypeahead 和 ChatComposerTrigger 上,emptySearchResultsText 与 emptySearchText 同时出现在类型中、同时出现在 .doc.mjs 中、同时出现在消费者文档中。四个 DEP-* 记录和四个 CLN-* ID。这个重命名可以通过 codemod 机械完成,包括调用方展开 props 的情况,因为值的含义不变,类型只是变宽了。随后一个 minor 版本会破坏这四个 API 表面上未迁移的调用点。
  • 无限期共存。 永远不会破坏任何东西。这种分歧会保留在类型签名中:使用方仍会在某个组件上遇到 emptySearchResultsText,在另一个组件上遇到 emptySearchText,而该标准只约束在其之后构建的组件。这回答了“以后我们在其他组件上添加它时能匹配这个模式”,但让今天的不一致继续存在。
  • 直接替换。 一个不设重叠期的 minor 重命名。否决理由:此处的弃用成本很低,也没有任何用户问题可以证明打破调用点是合理的——而弃用周期本可以平稳承载这些调用点。

Tokenizer.hasCreate 无需迁移。 早先的解读将其视为冲突,因为 Tokenizer 的 hasCreate 是一个没有回调的布尔值,而 #6829 为 MultiSelector 提出了一个处理器。OQ5 以另一种方式解决了这一问题:Tokenizer 自行铸造 token,并通过 onChange(items, {item, type: 'create'}) 上报,这正是 DEC-3 描述的形状,因此 Tokenizer 已经符合规范,且不需要任何改动。当 #6829 回归时,MultiSelector 将向其收敛。

当前状态影响

  • 当本记录成为 current 时,architecture:public-component-api 会在其 deciding_specs 中获得 spec:AST-056,并在其 Deciding specs 列表中获得一行。该记录的不变量没有任何变化:FR1–FR7 位于其 INV2、INV3 和 INV9 文法之内,而不是对其进行修订。
  • contributing:api-conventions 和 wiki 的 Prop Naming 部分将新增状态命名规则:一个可观察状态在所有拥有它的组件上只有一个 prop 名称和一种类型,并且新 prop 不得为已有状态引入第二个名称。目前这两处都没有这方面的规则。
  • component:Selector、component:MultiSelector、component:Tokenizer、component:Typeahead、component:BaseTypeahead 和 component:CommandPalette 将引用本记录,而不是各自保存一份私有副本。component:MultiSelector 处于 authority: draft 状态,并且正在起草的正是这样一份副本;该主张被撤回,转而采用本记录中的 FR5 和 FR6。
  • #6829 被此裁决阻塞。它的 hasCreate + onCreate 组合被 FR5 否决;FR5 承认与单独使用 hasCreate 相同的用户需求,并通过组件现有的 onChange 以及一个指明创建的描述符来上报——这正是 Tokenizer 已经提供的形状——因此该能力不能被半配置,同一个词也不能承担两份契约。
  • family:input-fields、spec:AST-002 和 spec:AST-017 只读不改:字段外观(field chrome)、准入(admission)和弃用生命周期保持其原有归属。
  • 本记录自身的合并不会带来任何已发布的公开 API 变更。每个组件保留所有 prop 和所有默认值,直到采纳变更落地。
  • 当本记录处于 draft 时,其 review-applicability:v1 块不路由任何内容:全局路由只加载 current 声明(architecture:knowledge-contracts INV20)。它将在获批后生效。

验证

契约 验证 代表性状态 变更或失败预期
FR1, FR2 每个采用者的 prop 表面测试套件,加上仓库的导出表面和 .doc.mjs prop 检查 每个采用者声明的 props;从包入口点导入的导出对象类型 一个名称包含 search 的顶层 prop、重复前缀的 key,或未导出的对象类型,均失败。
FR3 每个采用者的渲染测试套件 search 缺失;search={{}};在需要 search 的组件上省略 search 在 prop 缺失时仍渲染查询输入、残留查询状态,或必填/可选声明与组件是否持有选项相矛盾,均失败。
FR4 在两种模式下运行每个采用者的测试套件 无 source,组件持有选项;提供了 source;在每种模式下查询均无匹配 两种模式之间的可观察状态出现分歧,或组件对 source 返回的结果进行重新过滤,均失败。
FR5, AR1 每个采用者的测试套件及其 live-region 断言 一个字符串 emptyText;一个元素 emptyText;相邻的“完全没有选项”状态 名称或类型不同的 key,或播报没有携带元素渲染出的内容,均失败。这正是 AR1 今天在 main 上指出的差距。
FR6, FR7 类型级检查加上每个采用者的测试套件 在存在 search 时给出 onCreate;在缺少 search 时给出 onCreate 没有 search 即可触达的创建入口、用布尔值门控处理器,或静默失效的配置,均失败。
FR8 按采用者划分的套件 输入;清空;程序化变更 如果某个回调抑制了组件自身的解析,或者某个组件需要该回调却缺失,则失败。
FR9 每个采用者上的重叠套件,外加声明层级的 Changeset 检查 仅有旧 prop;仅有 key;两者都给出;两者都不给 若旧用法改变行为、旧 prop 静默胜出、缺少 DEP-*/CLN-* 对,或某项移除未出现在冻结的 minor 清单中,则失败。
FR10, AR2 对照本记录的公共 API 审查;每个采用者的可访问名称断言 一个提议的新搜索能力;每个采用者的查询输入,有名称的和无名称的 若允许新增顶级 search* prop,或查询输入的唯一名称是占位符,则失败。

已知的验证缺口:上述套件均不存在于 main 上,也没有组件实现 search。本记录为 draft,不约束审查,也不指定任何实现。AR1 另外记录的是当前已发布行为中的一个缺陷,而非一项通过的契约。

决策日志

以下每项决定均由 cixzhang 于 2026-10-02 在本记录的 pull request 上裁定。

DEC-1 — 为“查询未匹配任何内容”统一名称和类型

Reference: spec:AST-056/DEC-1 Decider: cixzhang, 2026-10-02

统一使用 emptySearchText,并接受 ReactNode,处处如此。

这就是已经波及实际用户的分歧。在同一产品中搜索 Selector 和 Tokenizer 的人会遇到同一个死胡同,而如今这两个组件甚至对这个状态叫什么都没有共识,更不用说调用者可以往那里传什么。Selector、MultiSelector 和 CommandPalette 使用 emptySearchText 并接受 ReactNode;Tokenizer、Typeahead、BaseTypeahead 和 ChatComposerInput 使用 emptySearchResultsText 并接受 string——因此同一产品无法在两个组件中都提供相同的“无结果,试试 X”提示行,而熟悉了一个组件的构建者还得再去摸索另一个。

名称最终落在 emptySearchText 而非更短的名称上,原因至关重要:Selector 和 MultiSelector 已经同时声明了 emptyText 和 emptySearchText,用于两种截然不同的提示——“这里什么都没有”和“没有匹配你输入的内容”。缩短搜索状态的名称会与一个已发布且含义不同的 prop 冲突,而这恰恰发生在搜索面最广的两个组件上。因此是三个组件向多数拼法改名,而不是七个组件迁就少数拼法。

类型则定为 ReactNode,而不是 string。死胡同恰恰是产品希望放链接、插图或新建操作提示的地方;收窄四个已经支持它的组件,等于为了赢得一致性而移除一项已发布能力。放宽另外三个组件,才能让产品在所有地方呈现相同的死胡同提示,而这正是统一名称的全部意义。

DEC-2 — 不使用 search 配置对象

Reference: spec:AST-056/DEC-2 Decider: cixzhang, 2026-10-02

本记录的早期草稿曾提议把所有搜索相关 prop 收集到一个对象值的 search prop 中,以 placeholder、emptyText、onChange 和 onCreate 作为键。该方案被否决。

这个对象解决的是整洁问题,而不是 Astryx 产品用户实际遇到的事情。传三个扁平 prop 并不难,而且下面的调查显示,仓库中并没有一个已经确立的约定可以援引:core 中每个 *Config 对象配置的都是一个 hook,唯一作为对象值的组件 prop 是 collapsible 和 button。

相比之下,代价是实实在在的。九个已发布的 prop 将进入弃用周期,其中四个带有 必填 的 searchSource,会在清理次要版本中破坏四个组件的每一个调用点。ComplexSelector 将接受一个只有一个有意义键的 search 对象,因为它自己管理自己的内容。而自动补全会变得更糟,而不是更好:在组件的标签列表内输入会立即列出扁平 prop,而 search={{ 则需要先被了解。

这种分歧真正需要的是共享的词汇表,而 DEC-1 和 FR6 在不重构任何东西的情况下就提供了这一点。

DEC-3 — 仅查询时存在的能力通过布尔值启用,并通过现有变更回调上报

Reference: spec:AST-056/DEC-3 Decider: cixzhang, 2026-10-02

一种仅在存在查询时才存在的能力——从未匹配任何内容的文本中创建一个值——通过一个布尔值启用,并通过组件的主要变更回调上报,附带一个描述符说明这是哪种变更。

Tokenizer 已经在这样做:hasCreate 打开该行,onChange(items, change) 在 'add'、'remove' 和 'reorder' 之外报告 {item, type: 'create'}。调用者通过它已经用于监听所有其他变更的同一通道得知创建事件,而且不会出现半配置状态,因为只有一个开关。

这种规则排除的形态是布尔值和处理函数相互门控,也就是 hasCreate && hasSearch && onCreate != null 所产生的:三种半设置状态,每一种都既不渲染任何内容,也不报告任何内容,更不发出任何警告。构建者设置了布尔值,却看不到创建行,且无从得知原因。

其 value 并不携带所创建对象的组件——MultiSelector 将 options 与 value: string[] 分开存放——会把下一个 value 和创建事件一起报告,因此调用方可以在一次更新中同时添加该选项并接受该 value。这一义务属于调用方,并且必须在能力落地之处予以说明;它并不构成同一能力采用另一种形态的理由。

布尔值无法阻止的唯一情形,是在查询输入被关闭的组件上启用创建功能。这种情况会在开发环境中发出警告(FR5),而不是静默地什么都不渲染。

DEC-4 — 词汇表是固定的;新能力加入其中

参考: spec:AST-056/DEC-4 决策者: cixzhang、2026-10-02

下面调研中的每个 prop 在当时都是合理的局部决策。偏差来自它们各自独立产生:同一个状态有两个名字,同一个名字有两种类型,实验室里有 searchLabel,某个组件上有 maxSearchResults。

因此,标准是词汇表而非结构。新的搜索相关 prop 用本记录固定的词语来命名其状态,并且不会为已有 prop 已表达的内容引入第二个名字。这一点可以在评审中检查,而无需任何人重构组件。

开放问题

  • OQ1 — 已解答。两个概念,按谁拥有选项来区分。(human-api)

cixzhang、2026-10-02:持有自身选项的组件接受 search 对象;选项来自调用方的组件保留 searchSource。共享的匹配规则和 createStaticSource 表明两者可以统一,但统一会使 source 成为四个组件上原本可选对象中的必填成员,并且会把一个已发布的必填 prop 迁移到调用方而毫无收益。FR1 和 FR4 记录了这一区分,DEC-1 承载了推理过程。

  • OQ2 — 已解答。用一个周期来弃用。(human-api)

cixzhang、2026-10-02:emptySearchResultsText 被标记为 @deprecated,指向 emptySearchText;两者在重叠期内都可用,移除将在后续 minor 版本中依据 spec:AST-017 FR28–FR31 进行。代价是三个组件上多出一个成对 prop,这正是 FR7 已经描述的——远低于被否决的对象形态原本会带来的九对。即使调用方展开 props,重命名也可以通过 codemod 完成,因为值的含义不变,类型只是放宽了。

  • OQ3 — 已解答。否。(human-api)

cixzhang、2026-10-02:本记录不会让 Selector 或 MultiSelector 上的查询观察变为公开能力。searchQuery 在两者上仍为内部状态。需要对查询采取行动的调用方会获得一个说明其用途的能力——即下面的创建——而不是一个原始查询流,再让他们围绕组件自身行为重新实现一遍。

  • OQ4 — 已解答。三个采用者;其余仅受 FR1 约束。(human-api)

cixzhang、2026-10-02:Selector、MultiSelector 和 ComplexSelector 原本会放置 search 对象,因此它们是本记录最直接针对的组件;随着该对象被否决(DEC-2),这一区别基本消解。Tokenizer、Typeahead、BaseTypeahead、CommandPalette 和 ChatComposerInput 保留 searchSource,并受 FR1(“查询未匹配任何内容”只有一个名字、一个类型)和 FR6(不为这些 props 已表达的状态另立名字)约束。PowerSearch 仍被引用且被排除:结构化的字段/运算符/值表达式不是对列表的类型化查询。

  • OQ5 — 已解答。一种能力:一个布尔值加一个变更描述符。(human-api)

cixzhang、2026-10-02:创建操作通过布尔值启用,并通过组件现有的变更回调上报,携带一个说明该变更为创建操作的描述符。没有单独的 handler prop,也没有 create 配置对象。

Tokenizer 已经如此工作:onChange(items, change),其中 change 是 {item, type: 'create'},与 'add'、'remove'、'reorder' 并列。MultiSelector 也可以用同样的方式上报——下一个 value 连同命名所创建查询的描述符——这样调用方可以在一次更新中添加选项并接受 value,并在它已经监听的、用于所有其他选择变更的通道上获知创建事件。

这取代了此处早前的一个答案,那个答案将两者视为需要不同形态的不同能力,理由是 MultiSelector 将 options 与 value: string[] 分开,因而无法像 Tokenizer 铸造 token 那样铸造选项。这一差异是真实的,但并不强制要求单独的 handler:将 value 和创建事件一起上报正是描述符的用途。因此,hasCreate 在两个组件中都表示同一件事,这是 FR1 的规则应用于动词而非状态。

契约还欠两件事,需在能力落地之处而非此处解决:描述符作为公共类型的形态,以及调用方添加所创建选项的义务——Tokenizer 没有这一义务,因为其 value 本身就携带对象;而 MultiSelector 的调用方若接受 value 却不添加选项,就会握有一个匹配不到任何内容的 id。

minQueryLength、debounceMs 和触发菜单的 loadingText 保持原处。它们描述的是获取行为,而获取只存在于调用方拥有选项的场景中;本记录不会重新组织已发布的 props。

内容边界

本记录不会重复任何组件的结构剖析、prop 表、主题目标或使用方示例;不会重复 spec:AST-002 中的准入论证;不会重复 spec:AST-017 中的弃用、清理和发布清单机制;不会重复 architecture:public-component-api 中的共享命名语法;不会重复 family:input-fields 中的字段外观;也不会重复各组件自身记录所拥有的匹配、防抖和取消行为。它会链接到这些内容的规范所有者。

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