An open source design system that's fully customizable and agent ready
TypeScript
feat(Tokenizer, Typeahead, BaseTypeahead, ChatComposerInput): emptySearchText (#6906)
Cindy Zhang8ffb134d7716
diff --git a/.changeset/empty-search-text-one-name.md b/.changeset/empty-search-text-one-name.mdnew file mode 100644index 0000000000..b288b1fee3--- /dev/null+++ b/.changeset/empty-search-text-one-name.md@@ -0,0 +1,18 @@+---+'@astryxdesign/core': patch+---++[feat] The message a component shows when a query matched nothing is now `emptySearchText` everywhere, and it takes a `ReactNode`.++`Selector`, `MultiSelector`, and `CommandPalette` already called it `emptySearchText` and already accepted a node. `Tokenizer`, `Typeahead`, `BaseTypeahead`, and each `ChatComposerInput` trigger called it `emptySearchResultsText` and accepted only a string — so the same product could offer a "no results, create one" row in one component and not in its neighbour, and a builder who learned one had to discover the other.++Nothing breaks. The type only widens, so every existing value stays valid, and `emptySearchResultsText` keeps working exactly as released. Set both and `emptySearchText` wins, with a development warning. Migration is the name alone.++Deprecation lifecycle (`spec:AST-017` FR28, FR31) — removal only in a later minor whose frozen manifest carries both ids of a pair:++- deprecation `DEP-0001` / cleanup `CLN-0001` — `Tokenizer.emptySearchResultsText`+- deprecation `DEP-0002` / cleanup `CLN-0002` — `Typeahead.emptySearchResultsText`+- deprecation `DEP-0003` / cleanup `CLN-0003` — `BaseTypeahead.emptySearchResultsText`+- deprecation `DEP-0004` / cleanup `CLN-0004` — `ChatComposerTrigger.emptySearchResultsText`++@cixzhangdiff --git a/apps/storybook/stories/BaseTypeahead.stories.tsx b/apps/storybook/stories/BaseTypeahead.stories.tsxindex 39ffcb0a1b..32448ee8a7 100644--- a/apps/storybook/stories/BaseTypeahead.stories.tsx+++ b/apps/storybook/stories/BaseTypeahead.stories.tsx@@ -199,7 +199,7 @@ export const EmptyResults: Story = {<Demosource={emptySource}debounceMs={0}- emptySearchResultsText="No matching frameworks"+ emptySearchText="No matching frameworks"/>),play: async ({canvasElement}) => {diff --git a/apps/storybook/stories/ChatComposerInput.stories.tsx b/apps/storybook/stories/ChatComposerInput.stories.tsxindex 268b770272..24734cc449 100644--- a/apps/storybook/stories/ChatComposerInput.stories.tsx+++ b/apps/storybook/stories/ChatComposerInput.stories.tsx@@ -463,7 +463,7 @@ export const AsyncSearch: Story = {variant: 'blue' as const,}),loadingText: 'Searching users…',- emptySearchResultsText: 'No users found',+ emptySearchText: 'No users found',};return (diff --git a/packages/core/src/Chat/ChatComposerInput.doc.mjs b/packages/core/src/Chat/ChatComposerInput.doc.mjsindex 229dfc770f..3c1eb48945 100644--- a/packages/core/src/Chat/ChatComposerInput.doc.mjs+++ b/packages/core/src/Chat/ChatComposerInput.doc.mjs@@ -98,7 +98,7 @@ export const docs = {name: 'triggers',type: 'ChatComposerTrigger[]',description:- 'Trigger definitions for typeahead menus. Each trigger specifies a character (@ or /), a search source, and an onSelect handler that returns the token to insert.',+ 'Trigger definitions for typeahead menus. Each trigger specifies a character (@ or /), a search source, and an onSelect handler that returns the token to insert. Per-trigger emptySearchText (ReactNode) is the message when the query matched nothing; the older emptySearchResultsText (string) is deprecated and still works.',},{name: 'debounceMs',@@ -174,7 +174,7 @@ export const docsZh = {placeholder: '输入为空时显示的占位文本。',maxRows: '滚动前的最大可见行数。紧凑布局中使用较小值。',triggers:- '菜单的触发定义。每个触发器指定字符(@ 或 /)、搜索源和返回要插入标记的 onSelect 处理器。',+ '菜单的触发定义。每个触发器指定字符(@ 或 /)、搜索源和返回要插入标记的 onSelect 处理器。每个触发器的 emptySearchText(ReactNode)用于查询无匹配结果时的提示;旧的 emptySearchResultsText(string)已弃用,但仍可使用。',debounceMs: '异步搜索源的去抖动延迟,避免过多网络请求。',hasHistory: '启用 ArrowUp/Down 回溯之前提交的消息。',label: '屏幕阅读器播报的无障碍标签。',@@ -205,7 +205,7 @@ export const docsDense = {placeholder: 'placeholder when empty',maxRows: 'max visible rows before scroll; lower for compact layouts',triggers:- 'typeahead trigger defs; character(@/)+searchSource+onSelect returning token',+ 'typeahead trigger defs; character(@/)+searchSource+onSelect returning token; emptySearchText (ReactNode) for no matches, emptySearchResultsText deprecated',debounceMs: 'debounce for async search to avoid excess requests',hasHistory: 'ArrowUp/Down to recall previous submissions',label: 'a11y label for screen readers',diff --git a/packages/core/src/Chat/ChatComposerInput.test.tsx b/packages/core/src/Chat/ChatComposerInput.test.tsxindex daff81bcbe..531e7607cb 100644--- a/packages/core/src/Chat/ChatComposerInput.test.tsx+++ b/packages/core/src/Chat/ChatComposerInput.test.tsx@@ -1143,6 +1143,98 @@ describe('ChatComposerInput', () => {const {container} = render(<ChatComposerInput triggers={[trigger]} />);expect(container).toBeTruthy();});++ // A trigger's `emptySearchResultsText` was renamed to `emptySearchText`+ // and widened from `string` to `ReactNode` (`spec:AST-056` FR1). The+ // released key keeps working through the overlap (`spec:AST-017` FR28).+ it('renders an element emptySearchText when the query matched nothing', async () => {+ const user = userEvent.setup();+ const trigger = createMentionTrigger({+ emptySearchText: (+ <span>+ Nobody by that name. <a href="/invite">Invite them</a>+ </span>+ ),+ });+ render(<ChatComposerInput triggers={[trigger]} />);++ await user.click(screen.getByRole('combobox'));+ await user.keyboard('@zzzzz');++ await waitFor(() => {+ expect(screen.getByText('Invite them')).toBeInTheDocument();+ });+ });++ it('keeps the deprecated key working, and says it is deprecated', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const user = userEvent.setup();+ const trigger = createMentionTrigger({+ emptySearchResultsText: 'Nobody found',+ });+ render(<ChatComposerInput triggers={[trigger]} />);++ await user.click(screen.getByRole('combobox'));+ await user.keyboard('@zzzzz');++ await waitFor(() => {+ expect(screen.getByText('Nobody found')).toBeInTheDocument();+ });+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining(+ 'ChatComposerInput: A trigger sets `emptySearchResultsText`, which is deprecated',+ ),+ );+ warn.mockRestore();+ });++ it('treats an explicit null key as not given, falling through to the old one', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const user = userEvent.setup();+ const trigger = createMentionTrigger({+ emptySearchResultsText: 'Nobody found',+ emptySearchText: null,+ });+ render(<ChatComposerInput triggers={[trigger]} />);++ await user.click(screen.getByRole('combobox'));+ await user.keyboard('@zzzzz');++ // The same meaning the typeahead family gives `null`: not given, so+ // the released key still supplies the message and no warning claims a+ // winner the menu did not pick.+ await waitFor(() => {+ expect(screen.getByText('Nobody found')).toBeInTheDocument();+ });+ expect(warn).not.toHaveBeenCalledWith(+ expect.stringContaining('sets both'),+ );+ warn.mockRestore();+ });++ it('lets the new key win when a trigger sets both, and warns', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const user = userEvent.setup();+ const trigger = createMentionTrigger({+ emptySearchResultsText: 'Old copy',+ emptySearchText: 'New copy',+ });+ render(<ChatComposerInput triggers={[trigger]} />);++ await user.click(screen.getByRole('combobox'));+ await user.keyboard('@zzzzz');++ await waitFor(() => {+ expect(screen.getByText('New copy')).toBeInTheDocument();+ });+ expect(screen.queryByText('Old copy')).not.toBeInTheDocument();+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining(+ 'ChatComposerInput: A trigger sets both `emptySearchResultsText` and `emptySearchText`',+ ),+ );+ warn.mockRestore();+ });});describe('accessibility', () => {diff --git a/packages/core/src/Chat/ChatComposerInput.tsx b/packages/core/src/Chat/ChatComposerInput.tsxindex fb0c25b355..b25baa8bcd 100644--- a/packages/core/src/Chat/ChatComposerInput.tsx+++ b/packages/core/src/Chat/ChatComposerInput.tsx@@ -69,6 +69,7 @@ import {Badge, type BadgeProps} from '../Badge';import {useChatComposerContext} from './ChatContext';import {themeProps} from '../utils/themeProps';import {useTranslator} from '../i18n';+import {useDevWarning} from '../hooks/useDevWarning';// =============================================================================// Types@@ -157,7 +158,25 @@ export type ChatComposerTrigger = {* Used when loading a previous message for editing.*/deserialize?: (value: string) => ChatComposerToken | null;- /** Text shown when no results found. @default 'No results' */+ /**+ * Content shown when the query matched nothing (`spec:AST-056` FR1).+ * Takes a `ReactNode`, so a dead end can carry a link or a create row.+ *+ * `null` means "not given", exactly as `undefined` does, so it falls+ * through to the default. Pass an empty string to render nothing.+ * @default 'No results'+ */+ emptySearchText?: ReactNode;+ /**+ * Text shown when no results found.+ * @default 'No results'+ * @deprecated `DEP-0004`. Renamed to `emptySearchText`, which takes a+ * `ReactNode` rather than a `string` — every existing value stays valid+ * (`spec:AST-056` FR1, FR7). Still works exactly as released;+ * `emptySearchText` wins when both are set. Removal is `CLN-0004`, in a+ * later minor whose frozen manifest carries both ids (`spec:AST-017`+ * FR31).+ */emptySearchResultsText?: string;/** Text shown during async search. @default 'Searching\u2026' */loadingText?: string;@@ -585,6 +604,30 @@ export function ChatComposerInput(props: ChatComposerInputProps) {insertTextRef.current = insertText;// --- Trigger menu ---+ // Each trigger's empty-result message was renamed (`spec:AST-056` FR1); the+ // released key keeps working through the overlap and development says which+ // one was read (`spec:AST-017` FR28).+ // `!= null` matches the `??` the menu resolves with, so an explicit `null`+ // counts as "not given" on both names and the warnings cannot claim a+ // winner the render did not pick.+ const triggersWithDeprecatedEmptyText =+ triggers?.filter(trigger => trigger.emptySearchResultsText != null) ?? [];+ const triggersWithBothEmptyTexts = triggersWithDeprecatedEmptyText.filter(+ trigger => trigger.emptySearchText != null,+ );+ useDevWarning(+ 'ChatComposerInput',+ 'A trigger sets `emptySearchResultsText`, which is deprecated; use ' ++ '`emptySearchText` instead. It still works exactly as released.',+ triggersWithDeprecatedEmptyText.length > triggersWithBothEmptyTexts.length,+ );+ useDevWarning(+ 'ChatComposerInput',+ 'A trigger sets both `emptySearchResultsText` and `emptySearchText`; ' ++ '`emptySearchText` wins. `emptySearchResultsText` is deprecated — ' ++ 'drop it.',+ triggersWithBothEmptyTexts.length > 0,+ );const triggerMenu = useTriggerMenu({triggers,editableRef,diff --git a/packages/core/src/Chat/useTriggerMenu.tsx b/packages/core/src/Chat/useTriggerMenu.tsxindex 02ca531687..30a91de6f6 100644--- a/packages/core/src/Chat/useTriggerMenu.tsx+++ b/packages/core/src/Chat/useTriggerMenu.tsx@@ -640,7 +640,10 @@ export function useTriggerMenu(const renderMenu = useCallback((): ReactNode => {const trigger = state.activeTrigger;- const emptyText = trigger?.emptySearchResultsText ?? 'No results';+ const emptyText =+ trigger?.emptySearchText ??+ trigger?.emptySearchResultsText ??+ 'No results';const loadingText = trigger?.loadingText ?? 'Searching\u2026';let listContent: ReactNode;diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjsindex 9695ccd1bb..d9efadd6ed 100644--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs@@ -6,7 +6,17 @@ export const docs = {name: 'Tokenizer',displayName: 'Tokenizer',category: 'Form Controls',- keywords: ["tokenizer","multiselect","multi-select","chips","tags","combobox","autocomplete","taginput","chipinput"],+ keywords: [+ 'tokenizer',+ 'multiselect',+ 'multi-select',+ 'chips',+ 'tags',+ 'combobox',+ 'autocomplete',+ 'taginput',+ 'chipinput',+ ],playground: {// `value` is a required array of custom items the preview cannot// auto-generate; without a default the properties tab shows the@@ -146,24 +156,35 @@ export const docs = {{name: 'maxMenuItems',type: 'number',- description: 'Maximum number of search results to display. The hasCreate entry is offered on top of them, so a menu can show one more than this.',+ description:+ 'Maximum number of search results to display. The hasCreate entry is offered on top of them, so a menu can show one more than this.',default: '10',},{name: 'menuWidth',type: 'number',- description: 'Fixed dropdown width in pixels. The menu never shrinks below its anchor width.',+ description:+ 'Fixed dropdown width in pixels. The menu never shrinks below its anchor width.',},{name: 'minQueryLength',type: 'number',- description: 'Minimum query length before the search source is queried. Below it no search runs, and the menu stays closed — unless hasCreate is set, in which case the "Create ..." entry is still offered, being derived from the typed text rather than fetched for it.',+ description:+ 'Minimum query length before the search source is queried. Below it no search runs, and the menu stays closed — unless hasCreate is set, in which case the "Create ..." entry is still offered, being derived from the typed text rather than fetched for it.',default: '1',},+ {+ name: 'emptySearchText',+ type: 'ReactNode',+ description:+ 'Content shown when the query matched nothing. Takes a ReactNode, so the dead end can carry a link or a create row. Announced in a polite live region as the text it renders, read from the DOM; aria-hidden parts stay out of both, and content that renders no text announces nothing. null counts as not given, like undefined, and falls through to the default; pass an empty string to render nothing.',+ default: "'No results found'",+ },{name: 'emptySearchResultsText',type: 'string',- description: 'Text shown when search returns no results.',+ description:+ 'Deprecated: renamed to emptySearchText, which takes a ReactNode rather than a string, so every existing value stays valid. Still works exactly as released; emptySearchText wins when both are set.',default: "'No results found'",},{@@ -229,7 +250,8 @@ export const docs = {{name: 'tokenOverflowBehavior',type: "'none' | 'unfocusedInline' | 'unfocusedLayer'",- description: 'Controls how tokens overflow when the container is too narrow.',+ description:+ 'Controls how tokens overflow when the container is too narrow.',default: "'none'",},{@@ -251,30 +273,101 @@ export const docs = {],theming: {targets: [- {className: 'astryx-tokenizer', visualProps: ['size', 'status'], states: ['disabled']},+ {+ className: 'astryx-tokenizer',+ visualProps: ['size', 'status'],+ states: ['disabled'],+ },],},usage: {description:'Tokenizer is a multi-select input that lets users search, select, and manage multiple items displayed as removable chips. Use it when users need to build a set of selections from a searchable data source, like adding team members, applying tags, or choosing filters.',bestPractices: [- {guidance: true, description: 'Write a placeholder that tells users what they can search for, such as "Search people..." or "Add tags...", so the input is not a blank mystery.'},- {guidance: true, description: 'Set maxEntries when the number of selections should be bounded, like limiting a review to 5 approvers.'},- {guidance: true, description: 'Use hasCreate for free-form tagging where users need to enter values that do not exist in the search source.'},- {guidance: true, description: 'Show validation status with the status prop so users know immediately when a selection is missing or invalid.'},- {guidance: false, description: 'Don\'t use Tokenizer for single-item selection; use Typeahead instead. Tokenizer is for building sets of two or more items.'},- {guidance: false, description: 'Avoid applying custom colors to individual tokens inside a Tokenizer; use the default token style for visual consistency across the set.'},- {guidance: false, description: 'Don\'t hide the label; every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.'},- {guidance: false, description: 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},+ {+ guidance: true,+ description:+ 'Write a placeholder that tells users what they can search for, such as "Search people..." or "Add tags...", so the input is not a blank mystery.',+ },+ {+ guidance: true,+ description:+ 'Set maxEntries when the number of selections should be bounded, like limiting a review to 5 approvers.',+ },+ {+ guidance: true,+ description:+ 'Use hasCreate for free-form tagging where users need to enter values that do not exist in the search source.',+ },+ {+ guidance: true,+ description:+ 'Show validation status with the status prop so users know immediately when a selection is missing or invalid.',+ },+ {+ guidance: false,+ description:+ "Don't use Tokenizer for single-item selection; use Typeahead instead. Tokenizer is for building sets of two or more items.",+ },+ {+ guidance: false,+ description:+ 'Avoid applying custom colors to individual tokens inside a Tokenizer; use the default token style for visual consistency across the set.',+ },+ {+ guidance: false,+ description:+ "Don't hide the label; every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.",+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- {name: 'Label', required: true, description: 'The visible text above the input describing what the user is selecting. Also used as the accessible name.'},- {name: 'Token chips', required: false, description: 'Removable chips representing each selected item. Each chip shows a label and a remove button.'},- {name: 'Search input', required: true, description: 'The text input where users type to search the data source. Hides when maxEntries is reached.'},- {name: 'Dropdown menu', required: false, description: 'The search results list that appears below the input as the user types.'},- {name: 'Spinner', required: false, description: 'Loading indicator shown at the end of the field while a search is in flight.'},- {name: 'End content', required: false, description: 'A trailing slot after the input for action buttons, counts, or other controls.'},- {name: 'Clear button', required: false, description: 'A button that removes all selected tokens at once. Shown when hasClear is true and tokens are present.'},+ {+ name: 'Label',+ required: true,+ description:+ 'The visible text above the input describing what the user is selecting. Also used as the accessible name.',+ },+ {+ name: 'Token chips',+ required: false,+ description:+ 'Removable chips representing each selected item. Each chip shows a label and a remove button.',+ },+ {+ name: 'Search input',+ required: true,+ description:+ 'The text input where users type to search the data source. Hides when maxEntries is reached.',+ },+ {+ name: 'Dropdown menu',+ required: false,+ description:+ 'The search results list that appears below the input as the user types.',+ },+ {+ name: 'Spinner',+ required: false,+ description:+ 'Loading indicator shown at the end of the field while a search is in flight.',+ },+ {+ name: 'End content',+ required: false,+ description:+ 'A trailing slot after the input for action buttons, counts, or other controls.',+ },+ {+ name: 'Clear button',+ required: false,+ description:+ 'A button that removes all selected tokens at once. Shown when hasClear is true and tokens are present.',+ },],},};@@ -287,7 +380,8 @@ export const docsZh = {{name: 'label',type: 'string',- description: '\u8f93\u5165\u6846\u7684\u65e0\u969c\u788d\u6807\u7b7e\u3002',+ description:+ '\u8f93\u5165\u6846\u7684\u65e0\u969c\u788d\u6807\u7b7e\u3002',required: true,},{@@ -300,7 +394,8 @@ export const docsZh = {{name: 'value',type: 'T[]',- description: '\u5f53\u524d\u5df2\u9009\u9879\u76ee\u7684\u6570\u7ec4\u3002',+ description:+ '\u5f53\u524d\u5df2\u9009\u9879\u76ee\u7684\u6570\u7ec4\u3002',required: true,},{@@ -325,7 +420,8 @@ export const docsZh = {{name: 'hasClear',type: 'boolean',- description: '\u663e\u793a\u5168\u90e8\u6e05\u9664\u6309\u94ae\uff0c\u7528\u4e8e\u6279\u91cf\u79fb\u9664\u6240\u6709\u6807\u8bb0\u3002',+ description:+ '\u663e\u793a\u5168\u90e8\u6e05\u9664\u6309\u94ae\uff0c\u7528\u4e8e\u6279\u91cf\u79fb\u9664\u6240\u6709\u6807\u8bb0\u3002',default: 'false',},{@@ -343,13 +439,15 @@ export const docsZh = {{name: 'isDisabled',type: 'boolean',- description: '\u7981\u7528\u8f93\u5165\u6846\u548c\u6240\u6709\u6807\u8bb0\u4ea4\u4e92\u3002',+ description:+ '\u7981\u7528\u8f93\u5165\u6846\u548c\u6240\u6709\u6807\u8bb0\u4ea4\u4e92\u3002',default: 'false',},{name: 'htmlName',type: 'string',- description: '用于表单提交的 HTML name 属性。为每个已选项目的 id 渲染一个隐藏输入。',+ description:+ '用于表单提交的 HTML name 属性。为每个已选项目的 id 渲染一个隐藏输入。',},{name: 'disabledMessage',@@ -373,13 +471,15 @@ export const docsZh = {{name: 'isLabelHidden',type: 'boolean',- description: '\u89c6\u89c9\u9690\u85cf\u6807\u7b7e\uff0c\u540c\u65f6\u4fdd\u6301\u5176\u53ef\u8bbf\u95ee\u6027\u3002',+ description:+ '\u89c6\u89c9\u9690\u85cf\u6807\u7b7e\uff0c\u540c\u65f6\u4fdd\u6301\u5176\u53ef\u8bbf\u95ee\u6027\u3002',default: 'false',},{name: 'description',type: 'string',- description: '\u663e\u793a\u5728\u6807\u7b7e\u4e0b\u65b9\u7684\u8f85\u52a9\u6587\u672c\u3002',+ description:+ '\u663e\u793a\u5728\u6807\u7b7e\u4e0b\u65b9\u7684\u8f85\u52a9\u6587\u672c\u3002',},{name: 'isRequired',@@ -390,24 +490,28 @@ export const docsZh = {{name: 'isOptional',type: 'boolean',- description: '\u5728\u6807\u7b7e\u4e0a\u663e\u793a\u53ef\u9009\u6307\u793a\u5668\u3002',+ description:+ '\u5728\u6807\u7b7e\u4e0a\u663e\u793a\u53ef\u9009\u6307\u793a\u5668\u3002',default: 'false',},{name: 'labelTooltip',type: 'string',- description: '\u6807\u7b7e\u4e0a\u663e\u793a\u7684\u5de5\u5177\u63d0\u793a\u6587\u672c\u3002',+ description:+ '\u6807\u7b7e\u4e0a\u663e\u793a\u7684\u5de5\u5177\u63d0\u793a\u6587\u672c\u3002',},{name: 'hasEntriesOnFocus',type: 'boolean',- description: '\u805a\u7126\u65f6\u5728\u8f93\u5165\u524d\u663e\u793a\u5f15\u5bfc\u7ed3\u679c\u3002',+ description:+ '\u805a\u7126\u65f6\u5728\u8f93\u5165\u524d\u663e\u793a\u5f15\u5bfc\u7ed3\u679c\u3002',default: 'false',},{name: 'maxMenuItems',type: 'number',- description: '下拉列表显示的最大搜索结果数。“创建 ...”条目会在此之外额外提供,因此菜单可能比该数量多显示一项。',+ description:+ '下拉列表显示的最大搜索结果数。“创建 ...”条目会在此之外额外提供,因此菜单可能比该数量多显示一项。',default: '10',},{@@ -418,25 +522,36 @@ export const docsZh = {{name: 'minQueryLength',type: 'number',- description: '查询搜索源前的最小查询长度。低于该长度不会发起搜索,菜单保持关闭;但设置 hasCreate 时仍会提供“创建 ...”条目——该条目由输入的文本推导而来,并非通过搜索获取。',+ description:+ '查询搜索源前的最小查询长度。低于该长度不会发起搜索,菜单保持关闭;但设置 hasCreate 时仍会提供“创建 ...”条目——该条目由输入的文本推导而来,并非通过搜索获取。',default: '1',},+ {+ name: 'emptySearchText',+ type: 'ReactNode',+ description:+ '查询无匹配结果时显示的内容。接受 ReactNode,因此可在无结果处放置链接或创建入口。会从 DOM 读取其渲染出的文本在礼貌性实时区域中播报;aria-hidden 的部分两处都不包含,不渲染任何文本的内容则不会播报。null 与 undefined 同样视为未提供,将回退到默认值;若要不渲染任何内容,请传入空字符串。',+ default: "'No results found'",+ },{name: 'emptySearchResultsText',type: 'string',- description: '\u641c\u7d22\u65e0\u7ed3\u679c\u65f6\u663e\u793a\u7684\u6587\u672c\u3002',+ description:+ '已弃用:改名为 emptySearchText,其类型由 string 放宽为 ReactNode,原有取值全部仍然有效。仍按已发布行为工作;两者同时设置时以 emptySearchText 为准。',default: "'No results found'",},{name: 'hasAutoFocus',type: 'boolean',- description: '\u6302\u8f7d\u65f6\u81ea\u52a8\u805a\u7126\u8f93\u5165\u6846\u3002',+ description:+ '\u6302\u8f7d\u65f6\u81ea\u52a8\u805a\u7126\u8f93\u5165\u6846\u3002',default: 'false',},{name: 'size',type: "'sm' | 'md' | 'lg'",- description: '\u8f93\u5165\u6846\u548c\u6807\u8bb0\u7684\u5c3a\u5bf8\u3002',+ description:+ '\u8f93\u5165\u6846\u548c\u6807\u8bb0\u7684\u5c3a\u5bf8\u3002',default: "'md'",},{@@ -449,7 +564,8 @@ export const docsZh = {{name: 'onChangeQuery',type: '(query: string) => void',- description: '\u641c\u7d22\u67e5\u8be2\u6587\u672c\u53d8\u66f4\u65f6\u89e6\u53d1\u7684\u56de\u8c03\u3002',+ description:+ '\u641c\u7d22\u67e5\u8be2\u6587\u672c\u53d8\u66f4\u65f6\u89e6\u53d1\u7684\u56de\u8c03\u3002',},{name: 'startIcon',@@ -477,83 +593,197 @@ export const docsZh = {],theming: {targets: [- {className: 'astryx-tokenizer', visualProps: ['size', 'status'], states: ['disabled']},+ {+ className: 'astryx-tokenizer',+ visualProps: ['size', 'status'],+ states: ['disabled'],+ },],},usage: {description:'Tokenizer is a multi-select input that lets users search, select, and manage multiple items displayed as removable chips. Use it when users need to build a set of selections from a searchable data source, like adding team members, applying tags, or choosing filters.',bestPractices: [- {guidance: true, description: 'Write a placeholder that tells users what they can search for, such as "Search people..." or "Add tags...", so the input is not a blank mystery.'},- {guidance: true, description: 'Set maxEntries when the number of selections should be bounded, like limiting a review to 5 approvers.'},- {guidance: true, description: 'Use hasCreate for free-form tagging where users need to enter values that do not exist in the search source.'},- {guidance: true, description: 'Show validation status with the status prop so users know immediately when a selection is missing or invalid.'},- {guidance: false, description: 'Don\'t use Tokenizer for single-item selection; use Typeahead instead. Tokenizer is for building sets of two or more items.'},- {guidance: false, description: 'Avoid applying custom colors to individual tokens inside a Tokenizer; use the default token style for visual consistency across the set.'},- {guidance: false, description: 'Don\'t hide the label; every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.'},- {guidance: false, description: 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},+ {+ guidance: true,+ description:+ 'Write a placeholder that tells users what they can search for, such as "Search people..." or "Add tags...", so the input is not a blank mystery.',+ },+ {+ guidance: true,+ description:+ 'Set maxEntries when the number of selections should be bounded, like limiting a review to 5 approvers.',+ },+ {+ guidance: true,+ description:+ 'Use hasCreate for free-form tagging where users need to enter values that do not exist in the search source.',+ },+ {+ guidance: true,+ description:+ 'Show validation status with the status prop so users know immediately when a selection is missing or invalid.',+ },+ {+ guidance: false,+ description:+ "Don't use Tokenizer for single-item selection; use Typeahead instead. Tokenizer is for building sets of two or more items.",+ },+ {+ guidance: false,+ description:+ 'Avoid applying custom colors to individual tokens inside a Tokenizer; use the default token style for visual consistency across the set.',+ },+ {+ guidance: false,+ description:+ "Don't hide the label; every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.",+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- {name: 'Label', required: true, description: 'The visible text above the input describing what the user is selecting. Also used as the accessible name.'},- {name: 'Token chips', required: false, description: 'Removable chips representing each selected item. Each chip shows a label and a remove button.'},- {name: 'Search input', required: true, description: 'The text input where users type to search the data source. Hides when maxEntries is reached.'},- {name: 'Dropdown menu', required: false, description: 'The search results list that appears below the input as the user types.'},- {name: 'Spinner', required: false, description: 'Loading indicator shown at the end of the field while a search is in flight.'},- {name: 'End content', required: false, description: 'A trailing slot after the input for action buttons, counts, or other controls.'},- {name: 'Clear button', required: false, description: 'A button that removes all selected tokens at once. Shown when hasClear is true and tokens are present.'},+ {+ name: 'Label',+ required: true,+ description:+ 'The visible text above the input describing what the user is selecting. Also used as the accessible name.',+ },+ {+ name: 'Token chips',+ required: false,+ description:+ 'Removable chips representing each selected item. Each chip shows a label and a remove button.',+ },+ {+ name: 'Search input',+ required: true,+ description:+ 'The text input where users type to search the data source. Hides when maxEntries is reached.',+ },+ {+ name: 'Dropdown menu',+ required: false,+ description:+ 'The search results list that appears below the input as the user types.',+ },+ {+ name: 'Spinner',+ required: false,+ description:+ 'Loading indicator shown at the end of the field while a search is in flight.',+ },+ {+ name: 'End content',+ required: false,+ description:+ 'A trailing slot after the input for action buttons, counts, or other controls.',+ },+ {+ name: 'Clear button',+ required: false,+ description:+ 'A button that removes all selected tokens at once. Shown when hasClear is true and tokens are present.',+ },],},};/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */export const docsDense = {- description: 'Multi-select typeahead w/ token chips for selected items. Composes BaseTypeahead for search+Token for chips.',+ description:+ 'Multi-select typeahead w/ token chips for selected items. Composes BaseTypeahead for search+Token for chips.',usage: {description:'Multi-select input for searching and selecting multiple items as removable chips. Use for team members, tags, filters, or any set built from a searchable source.',bestPractices: [- {guidance: true, description: 'Placeholder that communicates what to search, such as "Search people..." rather than blank.'},- {guidance: true, description: 'maxEntries when selections are bounded (e.g. 5 approvers max).'},- {guidance: true, description: 'hasCreate for free-form tagging with values not in the source.'},- {guidance: true, description: 'status prop for immediate validation feedback.'},- {guidance: false, description: 'Don\'t use for single-item selection; use Typeahead instead.'},- {guidance: false, description: 'Avoid custom token colors; default style for consistency.'},- {guidance: false, description: 'Don\'t hide the label unless context makes purpose obvious.'},- {guidance: false, description: 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},+ {+ guidance: true,+ description:+ 'Placeholder that communicates what to search, such as "Search people..." rather than blank.',+ },+ {+ guidance: true,+ description:+ 'maxEntries when selections are bounded (e.g. 5 approvers max).',+ },+ {+ guidance: true,+ description:+ 'hasCreate for free-form tagging with values not in the source.',+ },+ {+ guidance: true,+ description: 'status prop for immediate validation feedback.',+ },+ {+ guidance: false,+ description:+ "Don't use for single-item selection; use Typeahead instead.",+ },+ {+ guidance: false,+ description:+ 'Avoid custom token colors; default style for consistency.',+ },+ {+ guidance: false,+ description:+ "Don't hide the label unless context makes purpose obvious.",+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},propDescriptions: {label: 'Accessible label for input.',- searchSource: 'Data source w/ search+bootstrap methods for populating dropdown.',+ searchSource:+ 'Data source w/ search+bootstrap methods for populating dropdown.',value: 'Array of currently selected items.',- onChange: "Fired on selection change. Change arg includes affected item+type ('add'|'create'|'remove'|'reorder').",- hasCreate: 'Enable free-text token creation. Shows "Create" dropdown option for unmatched typed text.',+ onChange:+ "Fired on selection change. Change arg includes affected item+type ('add'|'create'|'remove'|'reorder').",+ hasCreate:+ 'Enable free-text token creation. Shows "Create" dropdown option for unmatched typed text.',placeholder: 'Input placeholder. Only shown when no tokens selected.',maxEntries: 'Max selections allowed. Input hidden at limit.',hasClear: 'Clear-all button for bulk removal.',- renderToken: 'Custom token render. Default renders Token w/ label+onRemove.',+ renderToken:+ 'Custom token render. Default renders Token w/ label+onRemove.',renderItem: 'Custom dropdown item render. Default renders TypeaheadItem.',isDisabled: 'Disables input+all token interactions.',htmlName: 'HTML name attr; one hidden input per selected item id.',status: 'Validation status w/ type+message for error/warning/success.',- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',+ statusVariant:+ 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',isLabelHidden: 'Visually hides label; keeps a11y.',description: 'Helper text below label.',isRequired: 'Marks field required.',isOptional: 'Shows optional indicator on label.',labelTooltip: 'Tooltip on label.',hasEntriesOnFocus: 'Show bootstrap results on focus before typing.',- maxMenuItems: 'Max search results shown; the hasCreate entry sits on top of them.',+ maxMenuItems:+ 'Max search results shown; the hasCreate entry sits on top of them.',menuWidth: 'Fixed dropdown width in pixels.',- minQueryLength: 'Min query length before searching. Menu stays closed below it, except the hasCreate entry.',- emptySearchResultsText: 'Text when search returns no results.',+ minQueryLength:+ 'Min query length before searching. Menu stays closed below it, except the hasCreate entry.',+ emptySearchText: 'Content when the query matched nothing. ReactNode.',+ emptySearchResultsText:+ 'deprecated, use emptySearchText (ReactNode). still works as released; emptySearchText wins if both set.',hasAutoFocus: 'Auto-focus input on mount.',size: 'Input+token size.',debounceMs: 'Search debounce delay ms. 0 for sync sources.',onChangeQuery: 'Fired on search query text change.',- startIcon: 'Icon at input start, before tokens. Icon name, SVG component, or ReactNode.',+ startIcon:+ 'Icon at input start, before tokens. Icon name, SVG component, or ReactNode.',endContent: 'Content at input row end. For buttons, counts, controls.',handleRef: 'Imperative handle for focus() and blur() control.',- xstyle: 'StyleX layout styles (margins, positioning). Must be stylex.create() value.',+ xstyle:+ 'StyleX layout styles (margins, positioning). Must be stylex.create() value.',},};diff --git a/packages/core/src/Tokenizer/Tokenizer.test.tsx b/packages/core/src/Tokenizer/Tokenizer.test.tsxindex d5cb0cc52b..d05c00a5e9 100644--- a/packages/core/src/Tokenizer/Tokenizer.test.tsx+++ b/packages/core/src/Tokenizer/Tokenizer.test.tsx@@ -1736,3 +1736,187 @@ describe('Tokenizer end-lane reserve', () => {});});});++// `emptySearchResultsText` was renamed to `emptySearchText` and widened from+// `string` to `ReactNode` (`spec:AST-056` FR1). It is a released prop with a+// victim, so the replacement ships first and the old name keeps working+// through the overlap (`spec:AST-017` FR28, FR29).+describe('Tokenizer emptySearchText', () => {+ async function searchForNothing() {+ const input = screen.getByRole('combobox');+ fireEvent.change(input, {target: {value: 'zzzzz'}});+ }++ it('renders an element, which the old string type could not express', async () => {+ render(+ <Tokenizer+ label="People"+ searchSource={userSource}+ value={[]}+ onChange={() => {}}+ debounceMs={0}+ emptySearchText={+ <span>+ Nobody by that name. <a href="/invite">Invite them</a>+ </span>+ }+ />,+ );+ await searchForNothing();++ await waitFor(() => {+ expect(screen.getByText('Invite them')).toBeInTheDocument();+ });+ });++ it('announces what it rendered, not the catalog default', async () => {+ render(+ <Tokenizer+ label="People"+ searchSource={userSource}+ value={[]}+ onChange={() => {}}+ debounceMs={0}+ emptySearchText={+ <span>+ Nobody by that name. <a href="/invite">Invite them</a>+ </span>+ }+ />,+ );+ await searchForNothing();++ await waitFor(() => {+ expect(+ document.querySelector('[data-astryx-live-region="polite"]'),+ ).toHaveTextContent('Nobody by that name. Invite them');+ });+ });++ it('leaves an aria-hidden decoration out of the announcement', async () => {+ render(+ <Tokenizer+ label="People"+ searchSource={userSource}+ value={[]}+ onChange={() => {}}+ debounceMs={0}+ emptySearchText={+ <span>+ Nobody by that name<span aria-hidden="true"> →</span>+ </span>+ }+ />,+ );+ await searchForNothing();++ // The arrow is hidden from the accessibility tree on screen, so reading+ // it into the live region would announce something the sighted user is+ // not being shown either.+ await waitFor(() => {+ expect(+ document.querySelector('[data-astryx-live-region="polite"]'),+ ).toHaveTextContent('Nobody by that name');+ });+ expect(+ document.querySelector('[data-astryx-live-region="polite"]')?.textContent,+ ).not.toContain('→');+ });++ it('treats an explicit null as not given, falling through to the old name', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ render(+ <Tokenizer+ label="People"+ searchSource={userSource}+ value={[]}+ onChange={() => {}}+ debounceMs={0}+ emptySearchResultsText="Nobody found"+ emptySearchText={null}+ />,+ );+ await searchForNothing();++ // `null` is what this prop's own `??` default already treats as absent,+ // so the released name still supplies the message and the warning says+ // only that it is deprecated.+ await waitFor(() => {+ expect(screen.getByText('Nobody found')).toBeInTheDocument();+ });+ expect(warn).not.toHaveBeenCalledWith(+ expect.stringContaining('are both set'),+ );+ warn.mockRestore();+ });++ it('falls through to the default when null is the only value given', async () => {+ render(+ <Tokenizer+ label="People"+ searchSource={userSource}+ value={[]}+ onChange={() => {}}+ debounceMs={0}+ emptySearchText={null}+ />,+ );+ await searchForNothing();++ await waitFor(() => {+ expect(screen.getByText('No results found')).toBeInTheDocument();+ });+ });++ it('keeps the deprecated name working, and says it is deprecated', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ render(+ <Tokenizer+ label="People"+ searchSource={userSource}+ value={[]}+ onChange={() => {}}+ debounceMs={0}+ emptySearchResultsText="Nobody found"+ />,+ );+ await searchForNothing();++ await waitFor(() => {+ expect(screen.getByText('Nobody found')).toBeInTheDocument();+ });+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining(+ 'Tokenizer: `emptySearchResultsText` is deprecated; use `emptySearchText`',+ ),+ );+ warn.mockRestore();+ });++ it('lets the new name win when both are set, and warns', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ render(+ <Tokenizer+ label="People"+ searchSource={userSource}+ value={[]}+ onChange={() => {}}+ debounceMs={0}+ emptySearchResultsText="Old copy"+ emptySearchText="New copy"+ />,+ );+ await searchForNothing();++ await waitFor(() => {+ expect(screen.getByText('New copy')).toBeInTheDocument();+ });+ expect(screen.queryByText('Old copy')).not.toBeInTheDocument();+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining(+ 'Tokenizer: `emptySearchResultsText` and `emptySearchText` are both set',+ ),+ );+ warn.mockRestore();+ });+});diff --git a/packages/core/src/Tokenizer/Tokenizer.tsx b/packages/core/src/Tokenizer/Tokenizer.tsxindex f2d6c767e1..48cafb449a 100644--- a/packages/core/src/Tokenizer/Tokenizer.tsx+++ b/packages/core/src/Tokenizer/Tokenizer.tsx@@ -63,6 +63,7 @@ import type {SearchableItem, SearchSource} from '../Typeahead/types';import {mergeProps} from '../utils';import {themeProps} from '../utils/themeProps';import {useTranslator} from '../i18n';+import {useRenamedProp} from '../hooks/useRenamedProp';// Re-export status types for convenienceexport type {@@ -177,7 +178,32 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<* @default 1*/minQueryLength?: number;- /** Text shown when no results found. @default 'No results found' */+ /**+ * Content shown when the query matched nothing (`spec:AST-056` FR1).+ * Takes a `ReactNode`, so a dead end can carry a link or a create row.+ *+ * The message is announced in a polite live region as the text it renders,+ * read from the DOM, so an element is announced as written and anything+ * marked `aria-hidden` is left out of both. Content that renders no text+ * announces nothing, matching the screen.+ *+ * `null` means "not given", exactly as `undefined` does, so it falls+ * through to the default. Pass an empty string to render nothing.+ *+ * @default 'No results found'+ */+ emptySearchText?: ReactNode;++ /**+ * Text shown when no results found.+ * @default 'No results found'+ * @deprecated `DEP-0001`. Renamed to `emptySearchText`, which takes a+ * `ReactNode` rather than a `string` — every existing value stays valid+ * (`spec:AST-056` FR1, FR7). Still works exactly as released;+ * `emptySearchText` wins when both are set. Removal is `CLN-0001`, in a+ * later minor whose frozen manifest carries both ids (`spec:AST-017`+ * FR31).+ */emptySearchResultsText?: string;/** Whether the input is disabled. @default false */isDisabled?: boolean;@@ -539,6 +565,7 @@ export function Tokenizer<T extends SearchableItem>({menuWidth,minQueryLength,emptySearchResultsText,+ emptySearchText: emptySearchTextFromProps,isDisabled = false,htmlName,disabledMessage,@@ -581,6 +608,16 @@ export function Tokenizer<T extends SearchableItem>({isEnabled: showsDisabledMessage,});+ // The replacement wins, the released name keeps working, and development+ // says which one was read (`spec:AST-056` FR7, `spec:AST-017` FR28).+ const emptySearchText = useRenamedProp<ReactNode>({+ component: 'Tokenizer',+ deprecated: 'emptySearchResultsText',+ deprecatedValue: emptySearchResultsText,+ replacement: 'emptySearchText',+ value: emptySearchTextFromProps,+ });+useImperativeHandle(handleRef, () => ({focus() {inputRef.current?.focus();@@ -959,7 +996,7 @@ export function Tokenizer<T extends SearchableItem>({maxMenuItems={maxMenuItems}menuWidth={menuWidth}minQueryLength={minQueryLength}- emptySearchResultsText={emptySearchResultsText}+ emptySearchText={emptySearchText}isDisabled={isDisabled}isFocusableDisabled={showsDisabledMessage}hasAutoFocus={hasAutoFocus}diff --git a/packages/core/src/Typeahead/BaseTypeahead.doc.mjs b/packages/core/src/Typeahead/BaseTypeahead.doc.mjsindex f05df6b3bc..c31773a600 100644--- a/packages/core/src/Typeahead/BaseTypeahead.doc.mjs+++ b/packages/core/src/Typeahead/BaseTypeahead.doc.mjs@@ -158,10 +158,18 @@ export const docs = {'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',default: '1',},+ {+ name: 'emptySearchText',+ type: 'ReactNode',+ description:+ 'Content shown when the query matched nothing. Takes a ReactNode, so the dead end can carry a link or a create row. Announced in a polite live region as the text it renders, read from the DOM; aria-hidden parts stay out of both, and content that renders no text announces nothing. null counts as not given, like undefined, and falls through to the default; pass an empty string to render nothing.',+ default: "'No results found'",+ },{name: 'emptySearchResultsText',type: 'string',- description: 'Text shown when search returns no results.',+ description:+ 'Deprecated: renamed to emptySearchText, which takes a ReactNode rather than a string, so every existing value stays valid. Still works exactly as released; emptySearchText wins when both are set.',default: "'No results found'",},{@@ -316,10 +324,18 @@ export const docsZh = {'查询搜索源前的最小查询长度。低于该长度不会发起搜索,菜单保持关闭。',default: '1',},+ {+ name: 'emptySearchText',+ type: 'ReactNode',+ description:+ '查询无匹配结果时显示的内容。接受 ReactNode,因此可在无结果处放置链接或创建入口。会从 DOM 读取其渲染出的文本在礼貌性实时区域中播报;aria-hidden 的部分两处都不包含,不渲染任何文本的内容则不会播报。null 与 undefined 同样视为未提供,将回退到默认值;若要不渲染任何内容,请传入空字符串。',+ default: "'No results found'",+ },{name: 'emptySearchResultsText',type: 'string',- description: '搜索无结果时显示的文本。',+ description:+ '已弃用:改名为 emptySearchText,其类型由 string 放宽为 ReactNode,原有取值全部仍然有效。仍按已发布行为工作;两者同时设置时以 emptySearchText 为准。',default: "'No results found'",},{@@ -462,7 +478,9 @@ export const docsDense = {menuWidth: 'Requested px width before viewport clamping.',minQueryLength:'Min query length before searching. Menu stays closed below it.',- emptySearchResultsText: 'Text when no results.',+ emptySearchText: 'Content when the query matched nothing. ReactNode.',+ emptySearchResultsText:+ 'deprecated, use emptySearchText (ReactNode). still works as released; emptySearchText wins if both set.',isDisabled: 'Whether input disabled.',isFocusableDisabled:'Keeps disabled input focusable and blocks text entry; an already-open highlight can still be selected with Enter.',diff --git a/packages/core/src/Typeahead/BaseTypeahead.tsx b/packages/core/src/Typeahead/BaseTypeahead.tsxindex cfee187768..26f2fdaeb2 100644--- a/packages/core/src/Typeahead/BaseTypeahead.tsx+++ b/packages/core/src/Typeahead/BaseTypeahead.tsx@@ -31,6 +31,8 @@ import {useBusyIndicatorLane} from './busyIndicatorLane';import type {StyleXStyles} from '@stylexjs/stylex';import {usePopover} from '../Popover/usePopover';import {useAnnounce} from '../hooks/useAnnounce';+import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';+import {useRenamedProp} from '../hooks/useRenamedProp';import {useHighlightedOptionScroll} from '../hooks/useHighlightedOptionScroll';import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';import {isImeKeyEvent} from '../utils/ime';@@ -121,9 +123,31 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<*/minQueryLength?: number;+ /**+ * Content shown when the query matched nothing (`spec:AST-056` FR1).+ * Takes a `ReactNode`, so a dead end can carry a link or a create row.+ *+ * The message is announced in a polite live region as the text it renders,+ * read from the DOM, so an element is announced as written and anything+ * marked `aria-hidden` is left out of both. Content that renders no text+ * announces nothing, matching the screen.+ *+ * `null` means "not given", exactly as `undefined` does, so it falls+ * through to the default. Pass an empty string to render nothing.+ *+ * @default 'No results found'+ */+ emptySearchText?: ReactNode;+/*** Text shown when no results found.* @default 'No results found'+ * @deprecated `DEP-0003`. Renamed to `emptySearchText`, which takes a+ * `ReactNode` rather than a `string` — every existing value stays valid+ * (`spec:AST-056` FR1, FR7). Still works exactly as released;+ * `emptySearchText` wins when both are set. Removal is `CLN-0003`, in a+ * later minor whose frozen manifest carries both ids (`spec:AST-017`+ * FR31).*/emptySearchResultsText?: string;@@ -438,7 +462,8 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({maxMenuItems = 10,menuWidth,minQueryLength = 1,- emptySearchResultsText: emptySearchResultsTextFromProps,+ emptySearchResultsText: deprecatedEmptySearchResultsText,+ emptySearchText: emptySearchTextFromProps,isDisabled = false,isFocusableDisabled = false,hasAutoFocus = false,@@ -470,9 +495,21 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({const t = useTranslator();const placeholder =placeholderFromProps ?? t('@astryx.typeahead.searchPlaceholder');- const emptySearchResultsText =- emptySearchResultsTextFromProps ??- t('@astryx.typeahead.emptySearchResults');+ const emptySearchText =+ useRenamedProp<ReactNode>({+ component: 'BaseTypeahead',+ deprecated: 'emptySearchResultsText',+ deprecatedValue: deprecatedEmptySearchResultsText,+ replacement: 'emptySearchText',+ value: emptySearchTextFromProps,+ }) ?? t('@astryx.typeahead.emptySearchResults');+ // The empty-state row carries the message visually, and the live region has+ // to speak the same words. `emptySearchText` takes a ReactNode, so they are+ // read off the rendered row after it renders rather than guessed from the+ // prop — announcing a default over a caller's element tells the+ // screen-reader user something the sighted user is not reading+ // (`spec:AST-056` AR1).+ const emptyStateRef = useRef<HTMLDivElement>(null);const generatedId = useId();// Keep the released input-specific aliases authoritative when a caller uses// them, but do not let an omitted alias erase the equivalent native BaseProp.@@ -496,6 +533,16 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({const [isLoading, setIsLoading] = useState(false);const [hasSearched, setHasSearched] = useState(false);+ // Only the WORDS move here, not the timing. An empty query still reports+ // nothing — a focus-opened menu that bootstrapped to nothing is not a+ // search that failed — and a search still in flight reports nothing, which+ // matters because the row is in the DOM before the spinner clears.+ useAnnounceRenderedText(+ emptyStateRef,+ results.length === 0 && hasSearched && query.length > 0 && !isLoading,+ query,+ );+// Report the busy state to a wrapper that has taken the indicator over.//// Through a ref, and at the call site rather than from an effect: an effect@@ -634,13 +681,11 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({}// Announce the outcome only for an active query (not the initial// focus-open), so screen-reader users hear result counts / no-results.- if (searchQuery.length > 0) {- announce(- shown.length === 0- ? emptySearchResultsText- : t('@astryx.typeahead.resultCount', {count: shown.length}),- );+ if (searchQuery.length > 0 && shown.length > 0) {+ announce(t('@astryx.typeahead.resultCount', {count: shown.length}));}+ // An empty result is announced from the rendered row instead, so the+ // region speaks whatever the caller put there.} catch {if (searchGenRef.current !== gen) {return;@@ -658,7 +703,6 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({maxMenuItems,showLayer,announce,- emptySearchResultsText,__queryEntries,setLoading,t,@@ -1087,13 +1131,14 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({)}>{results.length === 0 && hasSearched ? (<div+ ref={emptyStateRef}role="option"aria-disabled="true"{...mergeProps(themeProps('typeahead-empty-state'),stylex.props(styles.emptyState),)}>- {emptySearchResultsText}+ {emptySearchText}</div>) : ((() => {diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjsindex 90012795e8..2488fe6dfa 100644--- a/packages/core/src/Typeahead/Typeahead.doc.mjs+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs@@ -223,10 +223,18 @@ export const docs = {type: 'string',description: 'Tooltip text shown on the label.',},+ {+ name: 'emptySearchText',+ type: 'ReactNode',+ description:+ 'Content shown when the query matched nothing. Takes a ReactNode, so the dead end can carry a link or a create row. Announced in a polite live region as the text it renders, read from the DOM; aria-hidden parts stay out of both, and content that renders no text announces nothing. null counts as not given, like undefined, and falls through to the default; pass an empty string to render nothing.',+ default: "'No results found'",+ },{name: 'emptySearchResultsText',type: 'string',- description: 'Text shown when search returns no results.',+ description:+ 'Deprecated: renamed to emptySearchText, which takes a ReactNode rather than a string, so every existing value stays valid. Still works exactly as released; emptySearchText wins when both are set.',default: "'No results found'",},{diff --git a/packages/core/src/Typeahead/Typeahead.test.tsx b/packages/core/src/Typeahead/Typeahead.test.tsxindex a8976cfc3b..fd3c70d1bc 100644--- a/packages/core/src/Typeahead/Typeahead.test.tsx+++ b/packages/core/src/Typeahead/Typeahead.test.tsx@@ -2041,3 +2041,139 @@ describe('the value is bounded by the content lane', () => {expect(style.marginInlineEnd).toBe('auto');});});++// `emptySearchResultsText` was renamed to `emptySearchText` and widened from+// `string` to `ReactNode` (`spec:AST-056` FR1). It is a released prop with a+// victim, so the replacement ships first and the old name keeps working+// through the overlap (`spec:AST-017` FR28, FR29).+describe('emptySearchText rename', () => {+ function searchForNothing() {+ fireEvent.change(screen.getByRole('combobox'), {+ target: {value: 'zzzzz'},+ });+ }++ describe('Typeahead', () => {+ it('renders an element, which the old string type could not express', async () => {+ render(+ <Typeahead+ label="Fruit"+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ debounceMs={0}+ emptySearchText={+ <span>+ Nothing ripe. <a href="/add">Add a fruit</a>+ </span>+ }+ />,+ );+ searchForNothing();++ await waitFor(() => {+ expect(screen.getByText('Add a fruit')).toBeInTheDocument();+ });+ });++ it('keeps the deprecated name working, and says it is deprecated', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ render(+ <Typeahead+ label="Fruit"+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ debounceMs={0}+ emptySearchResultsText="Nothing ripe"+ />,+ );+ searchForNothing();++ await waitFor(() => {+ expect(screen.getByText('Nothing ripe')).toBeInTheDocument();+ });+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining(+ 'Typeahead: `emptySearchResultsText` is deprecated; use `emptySearchText`',+ ),+ );+ warn.mockRestore();+ });++ it('lets the new name win when both are set, and warns', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ render(+ <Typeahead+ label="Fruit"+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ debounceMs={0}+ emptySearchResultsText="Old copy"+ emptySearchText="New copy"+ />,+ );+ searchForNothing();++ await waitFor(() => {+ expect(screen.getByText('New copy')).toBeInTheDocument();+ });+ expect(screen.queryByText('Old copy')).not.toBeInTheDocument();+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining(+ 'Typeahead: `emptySearchResultsText` and `emptySearchText` are both set',+ ),+ );+ warn.mockRestore();+ });+ });++ describe('BaseTypeahead', () => {+ it('announces the text of an element, not the catalog default', async () => {+ render(+ <BaseTypeahead+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ debounceMs={0}+ emptySearchText={+ <span>+ Nothing ripe. <a href="/add">Add a fruit</a>+ </span>+ }+ />,+ );+ searchForNothing();++ // Widening to ReactNode without this would hand the live region an+ // object: the AR1 defect, spread to a fourth component.+ await waitFor(() => {+ expect(+ document.querySelector('[data-astryx-live-region="polite"]'),+ ).toHaveTextContent('Nothing ripe. Add a fruit');+ });+ });++ it('announces the deprecated name unchanged', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ render(+ <BaseTypeahead+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ debounceMs={0}+ emptySearchResultsText="Nothing ripe"+ />,+ );+ searchForNothing();++ await waitFor(() => {+ expect(+ document.querySelector('[data-astryx-live-region="polite"]'),+ ).toHaveTextContent('Nothing ripe');+ });+ warn.mockRestore();+ });+ });+});diff --git a/packages/core/src/Typeahead/Typeahead.tsx b/packages/core/src/Typeahead/Typeahead.tsxindex f1ce0cf5c0..6104f95c5d 100644--- a/packages/core/src/Typeahead/Typeahead.tsx+++ b/packages/core/src/Typeahead/Typeahead.tsx@@ -61,6 +61,7 @@ import {themeProps} from '../utils/themeProps';import {useTranslator} from '../i18n';import {useMergedRefs} from '../hooks/useMergedRefs';+import {useRenamedProp} from '../hooks/useRenamedProp';export type {InputStatus as TypeaheadStatus,InputStatusType as TypeaheadStatusType,@@ -126,7 +127,32 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<* @default 1*/minQueryLength?: number;- /** Text shown when no results found. @default 'No results found' */+ /**+ * Content shown when the query matched nothing (`spec:AST-056` FR1).+ * Takes a `ReactNode`, so a dead end can carry a link or a create row.+ *+ * The message is announced in a polite live region as the text it renders,+ * read from the DOM, so an element is announced as written and anything+ * marked `aria-hidden` is left out of both. Content that renders no text+ * announces nothing, matching the screen.+ *+ * `null` means "not given", exactly as `undefined` does, so it falls+ * through to the default. Pass an empty string to render nothing.+ *+ * @default 'No results found'+ */+ emptySearchText?: ReactNode;++ /**+ * Text shown when no results found.+ * @default 'No results found'+ * @deprecated `DEP-0002`. Renamed to `emptySearchText`, which takes a+ * `ReactNode` rather than a `string` — every existing value stays valid+ * (`spec:AST-056` FR1, FR7). Still works exactly as released;+ * `emptySearchText` wins when both are set. Removal is `CLN-0002`, in a+ * later minor whose frozen manifest carries both ids (`spec:AST-017`+ * FR31).+ */emptySearchResultsText?: string;/** Whether the input is disabled. @default false */isDisabled?: boolean;@@ -356,6 +382,7 @@ export function Typeahead<T extends SearchableItem>({maxMenuItems,minQueryLength,emptySearchResultsText,+ emptySearchText: emptySearchTextFromProps,isDisabled = false,disabledMessage,hasClear = true,@@ -378,6 +405,16 @@ export function Typeahead<T extends SearchableItem>({const statusMessageId = useId();const inputGroup = useInputGroup();+ // The replacement wins, the released name keeps working, and development+ // says which one was read (`spec:AST-056` FR7, `spec:AST-017` FR28).+ const emptySearchText = useRenamedProp<ReactNode>({+ component: 'Typeahead',+ deprecated: 'emptySearchResultsText',+ deprecatedValue: emptySearchResultsText,+ replacement: 'emptySearchText',+ value: emptySearchTextFromProps,+ });+const wrapperRef = useRef<HTMLDivElement>(null);const inputRef = useRef<HTMLInputElement>(null);const tokenRef = useRef<HTMLElement>(null);@@ -587,7 +624,7 @@ export function Typeahead<T extends SearchableItem>({hasEntriesOnFocus={hasEntriesOnFocus}maxMenuItems={maxMenuItems}minQueryLength={minQueryLength}- emptySearchResultsText={emptySearchResultsText}+ emptySearchText={emptySearchText}isDisabled={isDisabled}hasAutoFocus={hasAutoFocus}isFocusableDisabled={showsDisabledMessage}diff --git a/packages/core/src/hooks/useRenamedProp.test.tsx b/packages/core/src/hooks/useRenamedProp.test.tsxnew file mode 100644index 0000000000..23bf22928d--- /dev/null+++ b/packages/core/src/hooks/useRenamedProp.test.tsx@@ -0,0 +1,95 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it, vi, afterEach} from 'vitest';+import {render} from '@testing-library/react';+import {useRenamedProp} from './useRenamedProp';++function Probe({+ deprecatedValue,+ value,+}: {+ deprecatedValue?: string;+ value?: string;+}) {+ const resolved = useRenamedProp<string>({+ component: 'Probe',+ deprecated: 'oldName',+ deprecatedValue,+ replacement: 'newName',+ value,+ });+ return <span data-testid="resolved">{resolved ?? '(none)'}</span>;+}++afterEach(() => {+ vi.restoreAllMocks();+});++describe('useRenamedProp', () => {+ it('returns undefined when neither name is given, leaving the default to the caller', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const {getByTestId} = render(<Probe />);+ expect(getByTestId('resolved').textContent).toBe('(none)');+ expect(warn).not.toHaveBeenCalled();+ });++ it('returns the replacement with no warning', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const {getByTestId} = render(<Probe value="new" />);+ expect(getByTestId('resolved').textContent).toBe('new');+ expect(warn).not.toHaveBeenCalled();+ });++ it('keeps the released name working, and says it is deprecated', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const {getByTestId} = render(<Probe deprecatedValue="old" />);+ expect(getByTestId('resolved').textContent).toBe('old');+ expect(warn).toHaveBeenCalledWith(+ 'Probe: `oldName` is deprecated; use `newName` instead. ' ++ '`oldName` still works exactly as released.',+ );+ });++ it('lets the replacement win when both are set, and says so once', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const {getByTestId} = render(<Probe deprecatedValue="old" value="new" />);+ expect(getByTestId('resolved').textContent).toBe('new');+ expect(warn).toHaveBeenCalledExactlyOnceWith(+ 'Probe: `oldName` and `newName` are both set; `newName` wins. ' ++ '`oldName` is deprecated — drop it.',+ );+ });++ it('treats an explicit null replacement as not given', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ // `null` is what the adopting components' own `??` already treats as+ // absent, so it must fall through to the deprecated value rather than+ // winning — and the warning must not claim a winner the render did not+ // pick.+ const {getByTestId} = render(+ <Probe deprecatedValue="old" value={null as unknown as string} />,+ );+ expect(getByTestId('resolved').textContent).toBe('old');+ expect(warn).toHaveBeenCalledExactlyOnceWith(+ expect.stringContaining('`oldName` is deprecated'),+ );+ });++ it('falls through to the caller default when null is the only value', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const {getByTestId} = render(<Probe value={null as unknown as string} />);+ expect(getByTestId('resolved').textContent).toBe('(none)');+ expect(warn).not.toHaveBeenCalled();+ });++ it('distinguishes an explicit falsy replacement from an absent one', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ // An empty string is a deliberate "render nothing here", not an omission,+ // so it must beat the deprecated value rather than fall through to it.+ const {getByTestId} = render(<Probe deprecatedValue="old" value="" />);+ expect(getByTestId('resolved').textContent).toBe('');+ expect(warn).toHaveBeenCalledExactlyOnceWith(+ expect.stringContaining('are both set'),+ );+ });+});diff --git a/packages/core/src/hooks/useRenamedProp.ts b/packages/core/src/hooks/useRenamedProp.tsnew file mode 100644index 0000000000..25bdcb2e82--- /dev/null+++ b/packages/core/src/hooks/useRenamedProp.ts@@ -0,0 +1,95 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file useRenamedProp.ts+ * @input The component name, the old and new prop names, and both values+ * @output The value to use, with development warnings for the overlap+ * @position Core deprecation utility; the replacement-first half of a prop+ * rename+ *+ * A released prop is a public promise, so a rename ships the replacement+ * first and keeps the old name working through the overlap (`spec:AST-017`+ * FR28–FR29, `architecture:public-component-api` INV9). This centralizes the+ * two things every such overlap owes: the new name wins when both are set,+ * and development says so rather than letting a caller wonder which one the+ * component read.+ *+ * Production behavior is unchanged either way — a warning is a builder+ * guardrail, never shipped noise (`spec:AST-017` FR29).+ *+ * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —+ * that barrel is re-exported wholesale from the package entry point, so+ * adding it there would ship a new public hook without `spec:AST-002`+ * admission. Import it by path from inside the package.+ */++import {useDevWarning} from './useDevWarning';++export interface RenamedPropOptions<T> {+ /** Component name, for the development warnings. */+ component: string;+ /** The deprecated prop's name. */+ deprecated: string;+ /** The deprecated prop's value, as the caller passed it. */+ deprecatedValue: T | undefined;+ /** The replacement prop's name. */+ replacement: string;+ /** The replacement prop's value, as the caller passed it. */+ value: T | undefined;+}++/**+ * Resolve a renamed prop: the replacement wins, the old name still works,+ * and development warns on use of the old name and again when both are set.+ *+ * `null` and `undefined` both count as "not given", matching the `??` the+ * adopting components already apply to their own defaults — so an explicit+ * `null` replacement falls through to the deprecated value if there is one,+ * and otherwise to the component's default, without a both-are-set warning+ * for a value that was never really set. An empty string is different: it is+ * a deliberate "render nothing" and wins like any other value.+ *+ * Returns `undefined` when neither is given, so the caller still applies its+ * own default.+ *+ * @example+ * ```+ * const emptySearchText = useRenamedProp({+ * component: 'Tokenizer',+ * deprecated: 'emptySearchResultsText',+ * deprecatedValue: emptySearchResultsText,+ * replacement: 'emptySearchText',+ * value: emptySearchTextFromProps,+ * });+ * ```+ */+export function useRenamedProp<T>({+ component,+ deprecated,+ deprecatedValue,+ replacement,+ value,+}: RenamedPropOptions<T>): T | undefined {+ // `!= null` catches undefined too: one notion of "not given", shared by+ // both names, so the warnings and the resolved value cannot disagree.+ const hasDeprecated = deprecatedValue != null;+ const hasValue = value != null;+ const hasBoth = hasDeprecated && hasValue;++ useDevWarning(+ component,+ `\`${deprecated}\` is deprecated; use \`${replacement}\` instead. ` ++ `\`${deprecated}\` still works exactly as released.`,+ hasDeprecated && !hasBoth,+ );+ useDevWarning(+ component,+ `\`${deprecated}\` and \`${replacement}\` are both set; ` ++ `\`${replacement}\` wins. \`${deprecated}\` is deprecated — drop it.`,+ hasBoth,+ );++ return hasValue ? value : deprecatedValue;+}