Skip to content

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.md
new file mode 100644
index 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`
+
+@cixzhang
diff --git a/apps/storybook/stories/BaseTypeahead.stories.tsx b/apps/storybook/stories/BaseTypeahead.stories.tsx
index 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 = {
<Demo
source={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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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 convenience
export 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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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;
+}