搜索状态词汇表系统规范¶
{
"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-contractsINV1、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-contractsINV2 所禁止的。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 |
上述表格呈现出四个漂移轴,每个都是某个人独自做出的决定:
- “无匹配结果”的两种命名:
Selector、MultiSelector和CommandPalette使用emptySearchText;Typeahead、BaseTypeahead、Tokenizer以及每个ChatComposerTrigger使用emptySearchResultsText。 - 同一消息的两种类型:第一组使用
ReactNode,第二组使用string。能够向某个组件传入元素的构建者,却无法向相邻组件传入同样的元素。 - 它的三种默认值:
'No results found'、'No results',以及——因为Selector和MultiSelector还带有顶层emptyText——相邻状态的'No options'。 - 前缀只出现在搜索可选之处。
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-017FR28、FR29)。在重叠期内,组件同时读取两者,新 prop 优先;发生冲突时,开发环境只发出一条警告(FR7)。 - 移除发生在一个后续声明的 minor 版本中,并附带一个指明替代品的
[breaking]Changeset(spec:AST-017FR31)。本记录不设定时间表;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-contractsINV20)。它将在获批后生效。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| 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