An open source design system that's fully customizable and agent ready
TypeScript
feat(ChatComposerInput): multi-word trigger queries via hasMultiWordQuery (#6128)
Geervan55e2f3ec6399
diff --git a/.changeset/chat-trigger-allow-spaces.md b/.changeset/chat-trigger-allow-spaces.mdnew file mode 100644index 0000000000..794fe2e83a--- /dev/null+++ b/.changeset/chat-trigger-allow-spaces.md@@ -0,0 +1,11 @@+---+'@astryxdesign/core': patch+---++[feat] Chat: mention people and topics by multi-word names with opt-in `hasMultiWordQuery` on `ChatComposerTrigger`++Set `hasMultiWordQuery: true` on a trigger whose suggestions contain spaces, and typing `@Jordan Le` keeps narrowing the menu instead of closing it at the first space. The query runs until a line break or about 64 characters, typed text is never changed unless a row is picked, and an unmatched multi-word phrase hides the menu unless the trigger sets `emptySearchText`. Triggers that don't opt in still end their query at a space.++For every trigger: while results for the current query are still loading, Enter sends the message as typed and never picks a row from an earlier query. Results that arrive after a send or after the editor clears are dropped, so the menu never reopens over an empty composer. Escape and the arrow keys pass through while the menu is hidden, and IME keystrokes never pick a row.++@Geervandiff --git a/apps/storybook/stories/ChatComposerInput.stories.tsx b/apps/storybook/stories/ChatComposerInput.stories.tsxindex ca6c72df50..79746ceb00 100644--- a/apps/storybook/stories/ChatComposerInput.stories.tsx+++ b/apps/storybook/stories/ChatComposerInput.stories.tsx@@ -44,6 +44,17 @@ const USERS: SearchableItem<{role: string}>[] = [{id: 'jordan', label: 'Jordan Lee', auxiliaryData: {role: 'Product'}},{id: 'taylor', label: 'Taylor Kim', auxiliaryData: {role: 'Design'}},{id: 'morgan', label: 'Morgan Chen', auxiliaryData: {role: 'Infrastructure'}},+ {+ id: 'maria',+ label: 'María José García de la Fuente',+ auxiliaryData: {role: 'Research'},+ },+ {+ id: 'rdj',+ label: 'Robert Downey Jr.',+ auxiliaryData: {role: 'Guest Speaker'},+ },+ {id: 'q4_review', label: 'Design Review: Q4', auxiliaryData: {role: 'Topic'}},];const COMMANDS: SearchableItem<{description: string}>[] = [@@ -372,6 +383,7 @@ export const MentionTrigger: Story = {const mentionTrigger: ChatComposerTrigger = {character: '@',searchSource: userSource,+ hasMultiWordQuery: true,renderItem: item => (<TypeaheadItemitem={item}@@ -497,6 +509,7 @@ export const MultipleTriggers: Story = {const mentionTrigger: ChatComposerTrigger = {character: '@',searchSource: userSource,+ hasMultiWordQuery: true,onSelect: item => ({value: `@${item.id}`,label: item.label,diff --git a/packages/core/src/Chat/ChatComposerInput.doc.mjs b/packages/core/src/Chat/ChatComposerInput.doc.mjsindex ffe96e13f9..5668085cee 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. Per-trigger emptySearchText (ReactNode) is the message when the query matched nothing.',+ 'Trigger definitions for typeahead menus. Each trigger specifies a character (@ or /), a search source, and an onSelect handler that returns the token to insert. Set hasMultiWordQuery: true when suggestions contain spaces (people, topics): the query then runs to a line break or about 64 characters instead of ending at the first space. Per-trigger emptySearchText (ReactNode) is the message when the query matched nothing.',},{name: 'debounceMs',diff --git a/packages/core/src/Chat/ChatComposerInput.spec.md b/packages/core/src/Chat/ChatComposerInput.spec.mdindex 3bbcd566e4..f4605009f4 100644--- a/packages/core/src/Chat/ChatComposerInput.spec.md+++ b/packages/core/src/Chat/ChatComposerInput.spec.md@@ -39,7 +39,7 @@ system_specs: [spec:AST-002, spec:AST-029]| Behavior | Every edit path keeps the serialized draft observable. Files pasted or dropped reach `onFiles`; consumer `onPaste` receives first refusal over plain text before optional paste-as-token conversion. || End-user impact | Dictated or otherwise programmatically inserted text is sendable and never hidden behind the empty placeholder; dropped files reach the product attachment flow. || Builder impact | Existing props, callback signatures, prop defaults, exports, and token serialization are unchanged. Builders relying on the documented `onPaste` and `onFiles` paths receive those callbacks except where FR5 and FR6 record implementation gaps; `hasMultiWordQuery` is the one added optional trigger field. Every trigger receives the trigger-key corrections listed under Compatibility and migration (FR10, FR13, FR15, FR16). |-| Compatibility/readiness | Patch-compatible. One additive optional trigger field (DEC-1) plus trigger-key corrections that apply to every trigger (FR10, FR13, FR15, FR16); no visual decision. Implementation gaps are recorded inline on FR1, FR5, FR6, FR10–FR13, FR15, FR16, and PR2. |+| Compatibility/readiness | Patch-compatible. One additive optional trigger field (DEC-1) plus trigger-key corrections that apply to every trigger (FR10, FR13, FR15, FR16); no visual decision. Implementation gaps are recorded inline on FR1, FR5, FR6, FR10, and PR2. || Review checks | Reject an edit path that mutates the DOM without updating the serialized draft, a file drop that can navigate away or bypass `onFiles`, a text paste that bypasses consumer interception, changed submit/token semantics, a trigger query that alters typed text, a key that picks a row from an earlier trigger query, or a menu that reopens after a send. || Governing rules | `architecture:public-component-api/INV1`; `architecture:interaction-modality/INV1–INV4`; `architecture:knowledge-contracts/INV11, INV16`; `spec:AST-002`; `spec:AST-029`; rubric B15. |@@ -96,24 +96,24 @@ imperative editing handle.## Behavioral and layout contract-| ID | Invariant | Basis |-| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |-| FR1 | Every user or imperative edit that changes serialized content MUST update empty state and emit the effective value through the active `onChange` channel. Implementation gap: `handleRef.insertToken` inserts the token without emitting the value through `onChange` or updating empty state, so the placeholder stays visible. | Shipped `onChange` contract, imperative handle, and ChatDictation callsite. |-| FR2 | Enter without Shift MUST submit one trimmed non-empty draft and clear it unless the event is composing, the trigger menu consumes it, or a consumer prevents default. | Shipped implementation and consumer docs. |-| FR3 | Shift+Enter and mid-text history arrows MUST retain native multiline editing behavior. | Shipped implementation and focused tests. |-| FR4 | `value` supplied directly on ChatComposerInput MUST win over ChatComposer context, while an emitted echo MUST NOT rebuild the DOM or move the caret. | Shipped controlled precedence and regression tests. |-| FR5 | Plain-text paste precedence MUST be consumer `onPaste` → configured/default paste-as-token → plain insertion. Implementation gap: a paste whose selection starts inside a token inserts the text after that token without calling `onPaste`. | Public callback meaning and objective callback composition. |-| FR6 | File paste and file drop MUST prevent native insertion/navigation and deliver the same ordered `File[]` to `onFiles`; disabled editors MUST NOT emit file callbacks. Implementation gap: a file paste whose selection starts inside a token never reaches `onFiles`. | Shipped public `onFiles` contract and consumer docs. |-| FR7 | Trigger-menu keyboard handling MUST run before consumer and built-in editor handling; IME composition MUST never submit. | Shipped interaction contract and tests. |-| FR8 | History recall MUST operate only at the draft boundaries and MUST restore the pending draft after stepping past the newest item. | Shipped behavior and tests. |-| FR9 | The root MUST keep forwarding its ref, BaseProps attributes, and styling seams; the imperative handle remains separate in `handleRef`. | Released public API and `architecture:public-component-api`. |-| FR10 | A trigger activates when its character starts the text or follows a space, a tab, or a line break, and its query runs from after that character to the caret. Inside an active multi-word query, FR11 limits which characters activate. A no-break space, such as the one after an inserted token, is not a boundary. A single-token query ends at a space, a tab, or a line break. Implementation gap: a tab is not yet a boundary: a tab before the trigger character does not activate it, and a tab inside a single-token query does not end it. Implementation gap: a trigger character that begins a text node activates whatever precedes it, such as an `@` typed directly after an inserted token and before its trailing no-break space. | Shipped trigger detection; DEC-1. |-| FR11 | A trigger with `hasMultiWordQuery: true` keeps its query through spaces and punctuation. The query ends only at a line break, past an implementation-owned length bound of at least 64 characters, or where the same trigger's character after a space, a tab, or a line break starts a new query; no word count, punctuation list, or termination callback applies. Inside an active multi-word query, another trigger's character does not activate under FR10, so the query continues through it. Implementation gap: no trigger accepts `hasMultiWordQuery` yet; every query ends at a space or a line break. | DEC-1. |-| FR12 | Ending a trigger query MUST leave the typed text unchanged. Only an explicit pick of a current row replaces the range from the trigger character to the caret. Implementation gap: Enter or Tab while a newer search is pending can replace the trigger text with a row from an earlier query (FR13). | DEC-1. |-| FR13 | While a newer search for the active query is pending, Enter without Shift submits the draft as typed and MUST NOT pick a row; no key picks a row returned for an earlier query. Results for a superseded query, or arriving after a pick, dismissal, submission, or the query ending, are discarded, so the menu never reopens over a sent or cleared draft. This applies to every trigger. Implementation gap: Enter or Tab while a newer search is pending picks the earlier query's highlighted row, and Enter does not send the draft; a superseded query's results are not discarded; and a send does not close the menu, so a result arriving after it shows rows over the cleared draft. | DEC-1; reference chat composer behavior. |-| FR14 | When a multi-word query settles with no matches, the menu is hidden unless the trigger supplies `emptySearchText`. A single-token query with no matches shows the empty message. | DEC-1. |-| FR15 | Keys pressed during IME composition MUST NOT pick a row or move the highlighted row. Implementation gap: the trigger menu handles keys before checking composition, so keys pressed during IME composition can move the highlighted row and pick it. | DEC-1; FR7. |-| FR16 | Escape on a visible menu dismisses it, and the menu stays hidden while the same query keeps growing from the same trigger. Implementation gap: after Escape, the menu reopens on the next keystroke of the same query. | DEC-1. |+| ID | Invariant | Basis |+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |+| FR1 | Every user or imperative edit that changes serialized content MUST update empty state and emit the effective value through the active `onChange` channel. Implementation gap: `handleRef.insertToken` inserts the token without emitting the value through `onChange` or updating empty state, so the placeholder stays visible. | Shipped `onChange` contract, imperative handle, and ChatDictation callsite. |+| FR2 | Enter without Shift MUST submit one trimmed non-empty draft and clear it unless the event is composing, the trigger menu consumes it, or a consumer prevents default. | Shipped implementation and consumer docs. |+| FR3 | Shift+Enter and mid-text history arrows MUST retain native multiline editing behavior. | Shipped implementation and focused tests. |+| FR4 | `value` supplied directly on ChatComposerInput MUST win over ChatComposer context, while an emitted echo MUST NOT rebuild the DOM or move the caret. | Shipped controlled precedence and regression tests. |+| FR5 | Plain-text paste precedence MUST be consumer `onPaste` → configured/default paste-as-token → plain insertion. Implementation gap: a paste whose selection starts inside a token inserts the text after that token without calling `onPaste`. | Public callback meaning and objective callback composition. |+| FR6 | File paste and file drop MUST prevent native insertion/navigation and deliver the same ordered `File[]` to `onFiles`; disabled editors MUST NOT emit file callbacks. Implementation gap: a file paste whose selection starts inside a token never reaches `onFiles`. | Shipped public `onFiles` contract and consumer docs. |+| FR7 | Trigger-menu keyboard handling MUST run before consumer and built-in editor handling; IME composition MUST never submit. | Shipped interaction contract and tests. |+| FR8 | History recall MUST operate only at the draft boundaries and MUST restore the pending draft after stepping past the newest item. | Shipped behavior and tests. |+| FR9 | The root MUST keep forwarding its ref, BaseProps attributes, and styling seams; the imperative handle remains separate in `handleRef`. | Released public API and `architecture:public-component-api`. |+| FR10 | A trigger activates when its character starts the text or follows a space, a tab, or a line break, and its query runs from after that character to the caret. Inside an active multi-word query, FR11 limits which characters activate. A no-break space, such as the one after an inserted token, is not a boundary. A single-token query ends at a space, a tab, or a line break. Implementation gap: a trigger character that begins a text node activates whatever precedes it, such as an `@` typed directly after an inserted token and before its trailing no-break space. | Shipped trigger detection; DEC-1. |+| FR11 | A trigger with `hasMultiWordQuery: true` keeps its query through spaces and punctuation. The query ends only at a line break, past an implementation-owned length bound of at least 64 characters, or where the same trigger's character after a space, a tab, or a line break starts a new query; no word count, punctuation list, or termination callback applies. Inside an active multi-word query, another trigger's character does not activate under FR10, so the query continues through it. | DEC-1. |+| FR12 | Ending a trigger query MUST leave the typed text unchanged. Only an explicit pick of a current row replaces the range from the trigger character to the caret. | DEC-1. |+| FR13 | While a newer search for the active query is pending, Enter without Shift submits the draft as typed and MUST NOT pick a row; no key picks a row returned for an earlier query. Results for a superseded query, or arriving after a pick, dismissal, submission, or the query ending, are discarded, so the menu never reopens over a sent or cleared draft. This applies to every trigger. | DEC-1; reference chat composer behavior. |+| FR14 | When a multi-word query settles with no matches, the menu is hidden unless the trigger supplies `emptySearchText`. A single-token query with no matches shows the empty message. | DEC-1. |+| FR15 | Keys pressed during IME composition MUST NOT pick a row or move the highlighted row. | DEC-1; FR7. |+| FR16 | Escape on a visible menu dismisses it, and the menu stays hidden while the same query keeps growing from the same trigger. | DEC-1. |### Allowed variation@@ -129,7 +129,7 @@ imperative editing handle.| typed or imperatively inserted text | Placeholder is absent and the same serialized value is observable to ChatComposer and callbacks (FR1 records an implementation gap). | Draft content. || controlled update | External value is reflected without corrupting a live caret or treating a stale echo as authoritative. | Parent update timing. || trigger menu open | Combobox semantics and active option wiring are exposed; menu interaction owns its keys. | Search source and item rendering. |-| trigger search pending | Enter submits the draft as typed; no earlier query's row can be picked (FR13 records an implementation gap). | Loading copy and source latency. |+| trigger search pending | Enter submits the draft as typed; no earlier query's row can be picked. | Loading copy and source latency. || trigger menu hidden | The editor reports a collapsed combobox and the menu consumes no keys. | Why the menu is hidden. || file paste or drop | Native insertion/navigation is prevented and files reach `onFiles` once (FR6 records an implementation gap). | File types and product handling. || disabled | Editing and file callbacks are unavailable and disabled state is exposed. | Product reason and surrounding status. |@@ -152,7 +152,7 @@ imperative editing handle.- **AR1 — Editing semantics.** Without triggers, the surface is a named multiline textbox; with triggers, it exposes the adopted combobox semantics without invalid multiline ARIA.- **AR2 — Disabled state.** Disabled editing is exposed with `aria-disabled` and cannot accept content or file callbacks.-- **AR3 — Keyboard ownership.** IME, trigger-menu keys, consumer cancellation, Enter submission, and boundary-only history do not steal one another's keys (FR15 records an implementation gap).+- **AR3 — Keyboard ownership.** IME, trigger-menu keys, consumer cancellation, Enter submission, and boundary-only history do not steal one another's keys.- **AR4 — Focus visibility.** When composed in ChatComposer, the semantic editor focus owner drives the shell's shared keyboard focus indicator.- **AR5 — Collapsed suggestions.** While the menu is hidden, the editor reports `aria-expanded="false"`, exposes no active descendant, and arrow keys, Enter, and Escape reach the editor and its surroundings.diff --git a/packages/core/src/Chat/ChatComposerInput.test.tsx b/packages/core/src/Chat/ChatComposerInput.test.tsxindex 5f1005a934..52429847cc 100644--- a/packages/core/src/Chat/ChatComposerInput.test.tsx+++ b/packages/core/src/Chat/ChatComposerInput.test.tsx@@ -11,7 +11,7 @@ import type {ChatComposerInputHandle,} from './ChatComposerInput';import {createStaticSource} from '../Typeahead/createStaticSource';-import type {SearchableItem} from '../Typeahead/types';+import type {SearchableItem, SearchSource} from '../Typeahead/types';// =============================================================================// Helpers@@ -1370,6 +1370,203 @@ describe('ChatComposerInput', () => {});});+ describe('trigger query (component:ChatComposerInput FR13, AR5)', () => {+ function typeAtEnd(editable: HTMLElement, text: string) {+ editable.textContent = text;+ const node = editable.firstChild!;+ const range = document.createRange();+ range.setStart(node, text.length);+ range.collapse(true);+ const sel = window.getSelection()!;+ sel.removeAllRanges();+ sel.addRange(range);+ fireEvent.input(editable);+ }++ it('Enter while a newer trigger search is pending sends the typed text, picks no row, and no menu reopens after the send', async () => {+ const onSubmit = vi.fn();+ let resolveSlow: (items: SearchableItem[]) => void = () => {};+ const source: SearchSource = {+ bootstrap: async () => [],+ async search(query: string) {+ if (query === 'ci') {+ return new Promise(resolve => {+ resolveSlow = resolve;+ });+ }+ return Promise.resolve(+ USERS.filter(u => u.label.toLowerCase().includes(query)),+ );+ },+ };+ render(+ <ChatComposerInput+ triggers={[createMentionTrigger({searchSource: source})]}+ debounceMs={0}+ onSubmit={onSubmit}+ />,+ );+ const editable = screen.getByRole('combobox');+ editable.focus();++ typeAtEnd(editable, '@c');+ await waitFor(() => {+ expect(editable.getAttribute('aria-activedescendant')).toBeTruthy();+ });++ // A newer search is pending: Enter sends the draft exactly as typed.+ typeAtEnd(editable, '@ci');+ fireEvent.keyDown(editable, {key: 'Enter'});+ expect(onSubmit).toHaveBeenCalledWith('@ci');+ expect(editable.querySelector('[data-astryx-token]')).toBeNull();+ expect(editable.textContent).toBe('');++ // The late result for the sent query must not reopen the menu.+ await act(async () => {+ resolveSlow([{id: 'cindy', label: 'Cindy Zhang'}]);+ });+ expect(editable).toHaveAttribute('aria-expanded', 'false');+ expect(screen.queryByRole('listbox')).not.toBeInTheDocument();+ expect(screen.queryByRole('option')).not.toBeInTheDocument();+ });++ it('forgets an Escape-dismissed mention when the message is sent, so the next message can mention', async () => {+ const onSubmit = vi.fn();+ render(+ <ChatComposerInput+ triggers={[createMentionTrigger()]}+ onSubmit={onSubmit}+ />,+ );+ const editable = screen.getByRole('combobox');+ editable.focus();++ typeAtEnd(editable, '@');+ await waitFor(() => {+ expect(editable).toHaveAttribute('aria-expanded', 'true');+ });+ fireEvent.keyDown(editable, {key: 'Escape'});+ await waitFor(() => {+ expect(editable).toHaveAttribute('aria-expanded', 'false');+ });++ fireEvent.keyDown(editable, {key: 'Enter'});+ expect(onSubmit).toHaveBeenCalledWith('@');++ typeAtEnd(editable, '@ci');+ await waitFor(() => {+ expect(editable).toHaveAttribute('aria-expanded', 'true');+ });+ expect(editable.getAttribute('aria-activedescendant')).toBeTruthy();+ });++ it('forgets an Escape-dismissed trigger when the send button sends the draft', async () => {+ const onSubmit = vi.fn();+ render(+ <ChatComposer+ onSubmit={onSubmit}+ input={<ChatComposerInput triggers={[createCommandTrigger()]} />}+ />,+ );+ const editable = screen.getByRole('combobox');+ editable.focus();++ typeAtEnd(editable, '/');+ await waitFor(() => {+ expect(editable).toHaveAttribute('aria-expanded', 'true');+ });+ fireEvent.keyDown(editable, {key: 'Escape'});+ await waitFor(() => {+ expect(editable).toHaveAttribute('aria-expanded', 'false');+ });++ fireEvent.click(screen.getByRole('button', {name: /send/i}));+ expect(onSubmit).toHaveBeenCalledWith('/');+ await waitFor(() => {+ expect(editable.textContent).toBe('');+ });++ typeAtEnd(editable, '/s');+ await waitFor(() => {+ expect(editable).toHaveAttribute('aria-expanded', 'true');+ });+ });++ it('drops a late trigger result after the send button sends the draft', async () => {+ const onSubmit = vi.fn();+ let resolveSlow: (items: SearchableItem[]) => void = () => {};+ const source: SearchSource = {+ bootstrap: async () => [],+ async search(query: string) {+ if (query === 'ci') {+ return new Promise(resolve => {+ resolveSlow = resolve;+ });+ }+ return Promise.resolve(+ USERS.filter(u => u.label.toLowerCase().includes(query)),+ );+ },+ };+ render(+ <ChatComposer+ onSubmit={onSubmit}+ input={+ <ChatComposerInput+ triggers={[createMentionTrigger({searchSource: source})]}+ debounceMs={0}+ />+ }+ />,+ );+ const editable = screen.getByRole('combobox');+ editable.focus();++ typeAtEnd(editable, '@c');+ await waitFor(() => {+ expect(editable.getAttribute('aria-activedescendant')).toBeTruthy();+ });+ typeAtEnd(editable, '@ci');++ fireEvent.click(screen.getByRole('button', {name: /send/i}));+ expect(onSubmit).toHaveBeenCalledWith('@ci');+ await waitFor(() => {+ expect(editable.textContent).toBe('');+ });++ await act(async () => {+ resolveSlow([{id: 'cindy', label: 'Cindy Zhang'}]);+ });+ expect(editable).toHaveAttribute('aria-expanded', 'false');+ expect(screen.queryByRole('option')).not.toBeInTheDocument();+ });++ it('lets Escape reach the consumer while an unmatched multi-word query hides the menu', async () => {+ const onKeyDown = vi.fn();+ render(+ <ChatComposerInput+ triggers={[createMentionTrigger({hasMultiWordQuery: true})]}+ onKeyDown={onKeyDown}+ />,+ );+ const editable = screen.getByRole('combobox');+ editable.focus();++ typeAtEnd(editable, '@team please');+ await waitFor(() => {+ expect(editable).toHaveAttribute('aria-expanded', 'false');+ });++ // Nothing cancels the key: the closed menu holds no Escape handling,+ // so a surrounding dialog or drawer still receives it.+ const notCancelled = fireEvent.keyDown(editable, {key: 'Escape'});+ expect(notCancelled).toBe(true);+ expect(onKeyDown).toHaveBeenCalledWith(+ expect.objectContaining({key: 'Escape'}),+ );+ });+ });+describe('trigger menu cursor anchor', () => {// The trigger menu anchors its popover to the cursor position, not the// entire input element. In real browsers this creates a fixed-positiondiff --git a/packages/core/src/Chat/ChatComposerInput.tsx b/packages/core/src/Chat/ChatComposerInput.tsxindex 1add3ced55..754f1abfa1 100644--- a/packages/core/src/Chat/ChatComposerInput.tsx+++ b/packages/core/src/Chat/ChatComposerInput.tsx@@ -170,6 +170,15 @@ export type ChatComposerTrigger = {loadingText?: string;/** Accessible label for the menu. @default 'Suggestions' */menuLabel?: string;+ /**+ * Whether the query continues past spaces, for suggestions whose names have+ * spaces (e.g. "@María José García", "@Design Review: Q4"). The query then+ * runs until a line break or about 64 characters, and when nothing matches+ * the menu hides unless `emptySearchText` is set. When false, the query ends+ * at the first space.+ * @default false+ */+ hasMultiWordQuery?: boolean;};export interface ChatComposerInputProps extends Omit<@@ -685,6 +694,10 @@ export function ChatComposerInput(props: ChatComposerInputProps) {currentDraftRef.current = '';}+ // Submitting ends any trigger query, including one dismissed with+ // Escape: no menu stays open, and no dismissal carries into the next+ // message.+ triggerMenu.reset();onSubmit?.(text);editableRef.current.textContent = '';setIsEmpty(true);diff --git a/packages/core/src/Chat/useTriggerMenu.test.tsx b/packages/core/src/Chat/useTriggerMenu.test.tsxnew file mode 100644index 0000000000..215823c147--- /dev/null+++ b/packages/core/src/Chat/useTriggerMenu.test.tsx@@ -0,0 +1,994 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file useTriggerMenu.test.tsx+ * @input Uses vitest, @testing-library/react, useTriggerMenu hook+ * @output Unit tests for trigger detection, multi-word queries, IME guard, pending-search Enter, stale and late results, and Escape dismissal+ * @position Testing; validates useTriggerMenu.tsx implementation+ *+ * SYNC: When useTriggerMenu.tsx changes, update tests to match new behavior+ */++import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';+import {renderHook, act} from '@testing-library/react';+import {useTriggerMenu} from './useTriggerMenu';+import type {ChatComposerTrigger} from './ChatComposerInput';+import {createStaticSource} from '../Typeahead/createStaticSource';+import type {SearchableItem, SearchSource} from '../Typeahead/types';++const USERS: SearchableItem[] = [+ {id: 'cindy', label: 'Cindy Zhang'},+ {id: 'alex', label: 'Alex Johnson'},+ {id: 'sam', label: 'Sam Rivera'},+ {id: 'obrien', label: "O'Brien"},+ {id: 'jeanluc', label: "Jean-Luc's Task"},+ {id: 'maria', label: 'María José García de la Fuente'},+ {id: 'rdj', label: 'Robert Downey Jr.'},+ {id: 'q4_review', label: 'Design Review: Q4'},+];++const COMMANDS: SearchableItem[] = [+ {id: 'summarize', label: 'summarize'},+ {id: 'translate', label: 'translate'},+ {id: 'search', label: 'search'},+];++function createMentionTrigger(+ overrides?: Partial<ChatComposerTrigger>,+): ChatComposerTrigger {+ return {+ character: '@',+ searchSource: createStaticSource(USERS),+ onSelect: item => ({+ value: `@${item.id}`,+ label: `@${item.label}`,+ variant: 'blue' as const,+ }),+ hasMultiWordQuery: true,+ ...overrides,+ };+}++function createCommandTrigger(+ overrides?: Partial<ChatComposerTrigger>,+): ChatComposerTrigger {+ return {+ character: '/',+ searchSource: createStaticSource(COMMANDS),+ onSelect: item => `/${item.label} `,+ hasMultiWordQuery: false,+ ...overrides,+ };+}++describe('useTriggerMenu', () => {+ let editable: HTMLDivElement;++ beforeEach(() => {+ editable = document.createElement('div');+ editable.contentEditable = 'true';+ document.body.appendChild(editable);+ });++ afterEach(() => {+ editable.remove();+ const selection = window.getSelection();+ selection?.removeAllRanges();+ });++ // Typing in a real editor grows the same text node; reuse it so state tied to+ // the node (an Escape dismissal) behaves as it does in a browser. Assigning+ // `editable.textContent` directly models an external rewrite instead.+ function setCursor(text: string, cursorOffset?: number) {+ const existing = editable.firstChild;+ if (+ existing?.nodeType === Node.TEXT_NODE &&+ editable.childNodes.length === 1 &&+ text !== ''+ ) {+ (existing as Text).data = text;+ } else {+ editable.textContent = text;+ }+ const textNode = editable.firstChild;+ const offset = cursorOffset ?? text.length;++ const selection = window.getSelection();+ if (!selection) {+ return;+ }+ selection.removeAllRanges();++ if (textNode) {+ const range = document.createRange();+ range.setStart(textNode, offset);+ range.collapse(true);+ selection.addRange(range);+ }+ }++ function renderTriggerHook(triggers?: ChatComposerTrigger[]) {+ return renderHook(() =>+ useTriggerMenu({+ triggers: triggers ?? [createMentionTrigger(), createCommandTrigger()],+ editableRef: {current: editable},+ onInsertToken: vi.fn(),+ onInsertText: vi.fn(),+ onEmitChange: vi.fn(),+ debounceMs: 0,+ }),+ );+ }++ // 1. Single-token / behavior unchanged+ it('1. single-token / command behavior is unchanged and terminates on space', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('/summarize');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('summarize');+ expect(result.current.state.activeTrigger?.character).toBe('/');++ // Space immediately terminates single-token trigger+ await act(async () => {+ setCursor('/summarize ');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(false);++ // Further typing after space remains inactive+ await act(async () => {+ setCursor('/summarize now');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(false);+ });++ // 2. hasMultiWordQuery: true allows multi-word names with spaces, punctuation, etc.+ it('2. allows multi-word queries without word count or punctuation cutoffs', async () => {+ const {result} = renderTriggerHook();++ // Multi-word name: "María José García de la Fuente" (6 words)+ await act(async () => {+ setCursor('@María José García de la Fuente');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('María José García de la Fuente');+ expect(result.current.state.items.some(u => u.id === 'maria')).toBe(true);++ // Name with dot: "Robert Downey Jr."+ await act(async () => {+ setCursor('@Robert Downey Jr.');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('Robert Downey Jr.');+ expect(result.current.state.items.some(u => u.id === 'rdj')).toBe(true);++ // Phrase with colon: "Design Review: Q4"+ await act(async () => {+ setCursor('@Design Review: Q4');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('Design Review: Q4');+ expect(result.current.state.items.some(u => u.id === 'q4_review')).toBe(+ true,+ );+ });++ // 3. Trailing-space browse-all (@ )+ it('3. supports trailing-space browse-all query', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('@ ');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe(' ');++ await act(async () => {+ setCursor('@Project ');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('Project ');+ });++ // 4. Bounded length (64 chars)+ it('4. bounds active multi-word query length to 64 characters', async () => {+ const {result} = renderTriggerHook();+ const query64 = 'a'.repeat(64);+ const query65 = 'a'.repeat(65);++ await act(async () => {+ setCursor(`@${query64}`);+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe(query64);++ await act(async () => {+ setCursor(`@${query65}`);+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(false);+ });++ // 5. Apostrophe/hyphen preserved+ it("5. preserves apostrophes and hyphens without terminating (O'Brien, Jean-Luc's Task)", async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor("@O'Brien");+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe("O'Brien");++ await act(async () => {+ setCursor("@Jean-Luc's Task");+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe("Jean-Luc's Task");+ });++ // 6. Double space does not close+ it('6. tolerates double spaces without closing', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('@Project Alpha');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('Project Alpha');+ });++ // 7. Cursor repositioned into an earlier mention binds correctly+ it('7. binds correctly to earlier mention when cursor is repositioned', async () => {+ const {result} = renderTriggerHook();+ const fullText = 'Hello @First and @Second Name';++ // Reposition cursor right after "@First and" (offset 16)+ await act(async () => {+ setCursor(fullText, 16);+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('First and');++ // Reposition cursor at end of fullText+ await act(async () => {+ setCursor(fullText, fullText.length);+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('Second Name');+ });++ // 8. Word-boundary gate holds+ it('8. preserves word-boundary gate ([email protected], foo/bar do not activate)', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('[email protected]');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(false);++ await act(async () => {+ setCursor('foo/bar');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(false);+ });++ // 9. Newline hard-terminates even with hasMultiWordQuery: true+ it('9. terminates on newline even with hasMultiWordQuery: true', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('@Project\nAlpha');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(false);++ await act(async () => {+ setCursor('@\n');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(false);+ });++ // 10. Punctuation trigger characters (e.g. ':' emoji trigger) activate correctly+ it('10. allows triggers configured with punctuation characters (e.g. ":")', async () => {+ const emojiTrigger: ChatComposerTrigger = {+ character: ':',+ searchSource: createStaticSource([+ {id: 'smile', label: 'smile'},+ {id: 'wave', label: 'wave'},+ ]),+ onSelect: item => `:${item.label}:`,+ hasMultiWordQuery: false,+ };+ const {result} = renderTriggerHook([emojiTrigger, createMentionTrigger()]);++ await act(async () => {+ setCursor(':smile');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.activeTrigger?.character).toBe(':');+ expect(result.current.state.query).toBe('smile');+ });++ // 11. Non-opt-in triggers retain punctuation in queries (e.g. /v1.2, @john.doe)+ it('11. allows punctuation in queries for triggers that do not opt into hasMultiWordQuery', async () => {+ const singleTokenMention: ChatComposerTrigger = {+ character: '@',+ searchSource: createStaticSource([{id: 'john.doe', label: 'john.doe'}]),+ onSelect: item => `@${item.label}`,+ hasMultiWordQuery: false,+ };+ const {result} = renderTriggerHook([+ singleTokenMention,+ createCommandTrigger(),+ ]);++ // Command query with dot: /v1.2+ await act(async () => {+ setCursor('/v1.2');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('v1.2');++ // Single-token mention query with dot: @john.doe+ await act(async () => {+ setCursor('@john.doe');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('john.doe');+ });++ // 12. No matches: hides menu when hasMultiWordQuery matches nothing without emptySearchText+ it('12. hides menu when multi-word query matches nothing and no emptySearchText is set', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('@NonExistentUser12345');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.items).toEqual([]);+ // renderMenu returns null when hasMultiWordQuery matches nothing and emptySearchText is not set+ expect(result.current.renderMenu()).toBeNull();+ expect(result.current.ariaProps['aria-expanded']).toBe(false);+ });++ // 13. Callers with emptySearchText still display empty panel+ it('13. shows empty panel when caller provides emptySearchText', async () => {+ const customEmptyTrigger = createMentionTrigger({+ emptySearchText: 'No matching team members',+ });+ const {result} = renderTriggerHook([customEmptyTrigger]);++ await act(async () => {+ setCursor('@NonExistentUser');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.renderMenu()).not.toBeNull();+ expect(result.current.ariaProps['aria-expanded']).toBe(true);+ });++ // 13b. `emptySearchText: null` is "not given", so the menu still hides.+ it('13b. hides the menu for an unmatched multi-word query when emptySearchText is null', async () => {+ const {result} = renderTriggerHook([+ createMentionTrigger({emptySearchText: null}),+ ]);++ await act(async () => {+ setCursor('@NonExistentUser');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.renderMenu()).toBeNull();+ expect(result.current.ariaProps['aria-expanded']).toBe(false);+ });++ // 14. Enter with no matching row does not consume event+ it('14. does not consume Enter when there is no matching row', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('@NonExistentUser');+ result.current.handleInput();+ await Promise.resolve();+ });++ const enterEvent = {+ key: 'Enter',+ preventDefault: vi.fn(),+ nativeEvent: {} as KeyboardEvent,+ } as unknown as React.KeyboardEvent;++ let consumed = false;+ act(() => {+ consumed = result.current.handleKeyDown(enterEvent);+ });++ expect(consumed).toBe(false);+ expect(enterEvent.preventDefault).not.toHaveBeenCalled();+ });++ // 15. Guard IME composition: Enter during IME does not select+ it('15. guards IME composition so Enter during candidate selection does not pick a row', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('@Cindy');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.items.length).toBeGreaterThan(0);++ const imeEnterEvent = {+ key: 'Enter',+ preventDefault: vi.fn(),+ nativeEvent: {isComposing: true} as unknown as KeyboardEvent,+ } as unknown as React.KeyboardEvent;++ let consumed = false;+ act(() => {+ consumed = result.current.handleKeyDown(imeEnterEvent);+ });++ expect(consumed).toBe(false);+ expect(imeEnterEvent.preventDefault).not.toHaveBeenCalled();+ });++ // 16. Guard stale results: older query search cannot overwrite newer results or be pickable+ it('16. guards against stale search results from in-flight queries', async () => {+ let resolveFirstSearch: (items: SearchableItem[]) => void = () => {};+ let resolveSecondSearch: (items: SearchableItem[]) => void = () => {};++ const asyncSource: SearchSource = {+ async search(query: string) {+ if (query === 'C') {+ return new Promise(resolve => {+ resolveFirstSearch = resolve;+ });+ }+ if (query === 'Ci') {+ return new Promise(resolve => {+ resolveSecondSearch = resolve;+ });+ }+ return [];+ },+ bootstrap: async () => [],+ };++ const asyncTrigger: ChatComposerTrigger = {+ character: '@',+ searchSource: asyncSource,+ onSelect: item => `@${item.id}`,+ hasMultiWordQuery: true,+ };++ const {result} = renderTriggerHook([asyncTrigger]);++ // Type @C (search 1 starts)+ await act(async () => {+ setCursor('@C');+ result.current.handleInput();+ });+ expect(result.current.state.isLoading).toBe(true);+ expect(result.current.state.items).toEqual([]);++ // Type @Ci (search 2 starts)+ await act(async () => {+ setCursor('@Ci');+ result.current.handleInput();+ });++ // Older search 1 completes later with stale data+ await act(async () => {+ resolveFirstSearch([{id: 'stale', label: 'Stale Item'}]);+ await Promise.resolve();+ });++ // Stale result should be ignored+ expect(result.current.state.items).toEqual([]);++ // Newer search 2 completes+ await act(async () => {+ resolveSecondSearch([{id: 'cindy', label: 'Cindy Zhang'}]);+ await Promise.resolve();+ });++ expect(result.current.state.items).toEqual([+ {id: 'cindy', label: 'Cindy Zhang'},+ ]);+ });++ // 17. Escape keeps menu hidden while same query keeps growing+ it('17. keeps menu hidden after Escape while that same query keeps growing', async () => {+ const {result} = renderTriggerHook();++ // Type @Cindy -> active+ await act(async () => {+ setCursor('@Cindy');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);++ // Press Escape -> dismissed+ const escapeEvent = {+ key: 'Escape',+ preventDefault: vi.fn(),+ nativeEvent: {} as KeyboardEvent,+ } as unknown as React.KeyboardEvent;++ act(() => {+ result.current.handleKeyDown(escapeEvent);+ });+ expect(result.current.state.isActive).toBe(false);++ // User continues typing in the same query "@Cindy " -> stays hidden+ await act(async () => {+ setCursor('@Cindy ');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(false);++ // User continues typing in the same query "@Cindy Zhang" -> stays hidden+ await act(async () => {+ setCursor('@Cindy Zhang');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(false);++ // User backspaces past the Escape point to "@Cin" -> reactivates+ await act(async () => {+ setCursor('@Cin');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.query).toBe('Cin');+ });++ // 18. Enter while newer search is pending does not pick previous query's item+ it('18. does not pick a row on Enter while a newer search is pending (isLoading)', async () => {+ let resolveFirstSearch: (items: SearchableItem[]) => void = () => {};+ let resolveSecondSearch: (items: SearchableItem[]) => void = () => {};++ const asyncSource: SearchSource = {+ async search(query: string) {+ if (query === 'C') {+ return new Promise(resolve => {+ resolveFirstSearch = resolve;+ });+ }+ if (query === 'Ci') {+ return new Promise(resolve => {+ resolveSecondSearch = resolve;+ });+ }+ return [];+ },+ bootstrap: async () => [],+ };++ const asyncTrigger: ChatComposerTrigger = {+ character: '@',+ searchSource: asyncSource,+ onSelect: vi.fn(item => `@${item.id}`),+ hasMultiWordQuery: true,+ };++ const {result} = renderTriggerHook([asyncTrigger]);++ // Type @C (search 1 starts)+ await act(async () => {+ setCursor('@C');+ result.current.handleInput();+ });++ // Resolve search 1 -> rows populated+ await act(async () => {+ resolveFirstSearch([{id: 'cindy', label: 'Cindy Zhang'}]);+ await Promise.resolve();+ });+ expect(result.current.state.items.length).toBe(1);+ expect(result.current.state.isLoading).toBe(false);++ // Type @Ci (search 2 starts, isLoading becomes true, older items preserved in state)+ await act(async () => {+ setCursor('@Ci');+ result.current.handleInput();+ });+ expect(result.current.state.isLoading).toBe(true);++ // Press Enter while newer search is still loading+ const enterEvent = {+ key: 'Enter',+ preventDefault: vi.fn(),+ nativeEvent: {} as KeyboardEvent,+ } as unknown as React.KeyboardEvent;++ let consumed = false;+ act(() => {+ consumed = result.current.handleKeyDown(enterEvent);+ });++ // Enter picks no row from the earlier query and passes through, so the+ // composer sends the message as typed (component:ChatComposerInput FR13).+ expect(consumed).toBe(false);+ expect(enterEvent.preventDefault).not.toHaveBeenCalled();+ expect(asyncTrigger.onSelect).not.toHaveBeenCalled();++ // Now resolve search 2+ await act(async () => {+ resolveSecondSearch([{id: 'cindy_new', label: 'Cindy New'}]);+ await Promise.resolve();+ });+ expect(result.current.state.isLoading).toBe(false);+ });++ // 19. Arrows are not swallowed when multi-word no-matches menu is hidden+ it('19. does not swallow ArrowDown or ArrowUp when multi-word query has no matches and menu is hidden', async () => {+ const {result} = renderTriggerHook();++ // Type query with no matches -> menu is hidden (renderMenu is null, isMenuVisible is false)+ await act(async () => {+ setCursor('@UnknownNameThatDoesNotMatch');+ result.current.handleInput();+ await Promise.resolve();+ });++ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.items.length).toBe(0);+ expect(result.current.renderMenu()).toBeNull();++ const arrowDownEvent = {+ key: 'ArrowDown',+ preventDefault: vi.fn(),+ nativeEvent: {} as KeyboardEvent,+ } as unknown as React.KeyboardEvent;++ let consumedDown = false;+ act(() => {+ consumedDown = result.current.handleKeyDown(arrowDownEvent);+ });++ expect(consumedDown).toBe(false);+ expect(arrowDownEvent.preventDefault).not.toHaveBeenCalled();++ const arrowUpEvent = {+ key: 'ArrowUp',+ preventDefault: vi.fn(),+ nativeEvent: {} as KeyboardEvent,+ } as unknown as React.KeyboardEvent;++ let consumedUp = false;+ act(() => {+ consumedUp = result.current.handleKeyDown(arrowUpEvent);+ });++ expect(consumedUp).toBe(false);+ expect(arrowUpEvent.preventDefault).not.toHaveBeenCalled();+ });++ // 20. Stale search resolving after Escape does not populate items or reopen menu+ it('20. ignores async search results that resolve after Escape dismisses the menu', async () => {+ let resolveSearch: (items: SearchableItem[]) => void = () => {};++ const asyncSource: SearchSource = {+ async search(query: string) {+ if (query === 'C') {+ return new Promise(resolve => {+ resolveSearch = resolve;+ });+ }+ return [];+ },+ bootstrap: async () => [],+ };++ const asyncTrigger: ChatComposerTrigger = {+ character: '@',+ searchSource: asyncSource,+ onSelect: item => `@${item.id}`,+ hasMultiWordQuery: true,+ };++ const {result} = renderTriggerHook([asyncTrigger]);++ // Type @C -> search starts+ await act(async () => {+ setCursor('@C');+ result.current.handleInput();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.state.isLoading).toBe(true);++ // Press Escape -> reset called, state inactive+ const escapeEvent = {+ key: 'Escape',+ preventDefault: vi.fn(),+ nativeEvent: {} as KeyboardEvent,+ } as unknown as React.KeyboardEvent;++ act(() => {+ result.current.handleKeyDown(escapeEvent);+ });+ expect(result.current.state.isActive).toBe(false);++ // Later, the pending search resolves+ await act(async () => {+ resolveSearch([{id: 'cindy', label: 'Cindy Zhang'}]);+ await Promise.resolve();+ });++ // Results must be dropped and state must remain clean and empty+ expect(result.current.state.isActive).toBe(false);+ expect(result.current.state.items).toEqual([]);+ expect(result.current.state.isLoading).toBe(false);+ });++ function keyEvent(key: string, extra?: Partial<React.KeyboardEvent>) {+ return {+ key,+ shiftKey: false,+ preventDefault: vi.fn(),+ nativeEvent: {} as KeyboardEvent,+ ...extra,+ } as unknown as React.KeyboardEvent;+ }++ function deferredSource() {+ const pending = new Map<string, (items: SearchableItem[]) => void>();+ const source: SearchSource = {+ async search(query: string) {+ return new Promise<SearchableItem[]>(resolve => {+ pending.set(query, resolve);+ });+ },+ bootstrap: async () => [],+ };+ return {+ source,+ resolve: (q: string, items: SearchableItem[]) => pending.get(q)?.(items),+ };+ }++ // 21. Pending-search Enter applies to triggers that never opted in.+ it('21. Enter passes through and picks no row while a single-token trigger search is pending', async () => {+ const {source, resolve} = deferredSource();+ const onSelect = vi.fn((item: SearchableItem) => `/${item.id} `);+ const trigger = createCommandTrigger({searchSource: source, onSelect});+ const {result} = renderTriggerHook([trigger]);++ await act(async () => {+ setCursor('/s');+ result.current.handleInput();+ });+ await act(async () => {+ resolve('s', [{id: 'summarize', label: 'summarize'}]);+ await Promise.resolve();+ });+ await act(async () => {+ setCursor('/su');+ result.current.handleInput();+ });+ expect(result.current.state.isLoading).toBe(true);++ const enter = keyEvent('Enter');+ let consumed = false;+ act(() => {+ consumed = result.current.handleKeyDown(enter);+ });+ expect(consumed).toBe(false);+ expect(enter.preventDefault).not.toHaveBeenCalled();+ expect(onSelect).not.toHaveBeenCalled();++ // Tab has nothing current to pick either.+ const tab = keyEvent('Tab');+ act(() => {+ consumed = result.current.handleKeyDown(tab);+ });+ expect(consumed).toBe(false);+ expect(onSelect).not.toHaveBeenCalled();++ // Arrows stay with the menu but cannot build a selection on stale rows.+ const down = keyEvent('ArrowDown');+ act(() => {+ consumed = result.current.handleKeyDown(down);+ });+ expect(consumed).toBe(true);+ expect(result.current.state.highlightedIndex).toBe(0);++ // Shift+Enter keeps its editor meaning (a line break ends the query).+ const shiftEnter = keyEvent('Enter', {shiftKey: true});+ act(() => {+ consumed = result.current.handleKeyDown(shiftEnter);+ });+ expect(consumed).toBe(false);+ });++ // 22. A hidden menu does not swallow Escape.+ it('22. does not consume Escape while an unmatched multi-word query hides the menu', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('@team please review');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(true);+ expect(result.current.renderMenu()).toBeNull();++ const escape = keyEvent('Escape');+ let consumed = true;+ act(() => {+ consumed = result.current.handleKeyDown(escape);+ });+ expect(consumed).toBe(false);+ expect(escape.preventDefault).not.toHaveBeenCalled();+ });++ // 23. A result arriving after its query ended does not reopen the menu.+ it('23. discards a result that arrives after the editor no longer holds the query', async () => {+ const {source, resolve} = deferredSource();+ const {result} = renderTriggerHook([+ createMentionTrigger({searchSource: source}),+ ]);++ await act(async () => {+ setCursor('@jor');+ result.current.handleInput();+ });+ expect(result.current.state.isActive).toBe(true);++ // The composer clears the editor on submit without an input event.+ act(() => {+ editable.textContent = '';+ });+ await act(async () => {+ resolve('jor', [{id: 'jordan', label: 'Jordan Lee'}]);+ await Promise.resolve();+ });++ expect(result.current.state.isActive).toBe(false);+ expect(result.current.state.items).toEqual([]);+ expect(result.current.renderMenu()).toBeNull();+ });++ // 24. FR11: another trigger's character inside a multi-word query is text.+ it('24. continues a multi-word query through another trigger character', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('@jordan /s');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.activeTrigger?.character).toBe('@');+ expect(result.current.state.query).toBe('jordan /s');+ });++ // 25. FR11: the same trigger's character after a boundary starts a new query.+ it('25. restarts a multi-word query at the same trigger character after a space', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('@jordan @sa');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.activeTrigger?.character).toBe('@');+ expect(result.current.state.query).toBe('sa');+ });++ // 26. FR10: with no open multi-word query, another trigger after a space activates.+ it('26. activates a single-token trigger after a closed query', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('hello /su');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.activeTrigger?.character).toBe('/');+ expect(result.current.state.query).toBe('su');+ });++ // 26b. FR10: a tab is a boundary before a trigger and ends a single-token query.+ it('26b. treats a tab as a trigger boundary and as the end of a single-token query', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('hi\t/su');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.activeTrigger?.character).toBe('/');+ expect(result.current.state.query).toBe('su');++ await act(async () => {+ setCursor('/su\tx');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.isActive).toBe(false);+ });++ // 27. A visible empty menu keeps the arrows.+ it('27. keeps ArrowDown and ArrowUp while a visible menu shows its empty message', async () => {+ const {result} = renderTriggerHook();++ await act(async () => {+ setCursor('/zzz');+ result.current.handleInput();+ await Promise.resolve();+ });+ expect(result.current.state.items).toEqual([]);+ expect(result.current.renderMenu()).not.toBeNull();++ for (const key of ['ArrowDown', 'ArrowUp']) {+ const event = keyEvent(key);+ let consumed = false;+ act(() => {+ consumed = result.current.handleKeyDown(event);+ });+ expect(consumed).toBe(true);+ expect(event.preventDefault).toHaveBeenCalled();+ }++ // Enter has nothing to pick, so it keeps its editor meaning.+ let consumedEnter = true;+ act(() => {+ consumedEnter = result.current.handleKeyDown(keyEvent('Enter'));+ });+ expect(consumedEnter).toBe(false);+ });+});diff --git a/packages/core/src/Chat/useTriggerMenu.tsx b/packages/core/src/Chat/useTriggerMenu.tsxindex 00ca6bd65d..923bd75300 100644--- a/packages/core/src/Chat/useTriggerMenu.tsx+++ b/packages/core/src/Chat/useTriggerMenu.tsx@@ -10,7 +10,9 @@** Detects trigger characters (@ / etc.) typed inside a contentEditable,* opens a popover at the cursor position with filtered items, handles- * keyboard navigation, and inserts tokens or text on selection.+ * keyboard navigation, and inserts tokens or text on selection. Triggers+ * opt into multi-word queries with hasMultiWordQuery; results apply only+ * while their query is current (component:ChatComposerInput FR10–FR16).** Reuses SearchSource from Typeahead for async/sync search with* cancel() support and debounce.@@ -38,7 +40,7 @@ import {typeScaleVars,typographyVars,} from '../theme/tokens.stylex';-import {mergeProps, groupItems} from '../utils';+import {mergeProps, groupItems, isImeKeyEvent} from '../utils';import type {SearchableItem} from '../Typeahead/types';import {themeProps} from '../utils/themeProps';import {useTranslator} from '../i18n';@@ -55,6 +57,11 @@ export interface TriggerMenuState {items: SearchableItem[];highlightedIndex: number;isLoading: boolean;+ /**+ * The last settled results were an unmatched multi-word query, so the menu+ * is closed. It stays closed while a newer search for the same query runs.+ */+ isHidden: boolean;}export interface UseTriggerMenuOptions {@@ -74,7 +81,7 @@ export interface UseTriggerMenuReturn {state: TriggerMenuState;/** Call on every input event to check for trigger activation */handleInput: () => void;- /** Call on keydown \u2014 returns true if the event was consumed */+ /** Call on keydown — returns true if the event was consumed */handleKeyDown: (e: React.KeyboardEvent) => boolean;/** Render the trigger menu popover */renderMenu: () => ReactNode;@@ -169,6 +176,18 @@ const styles = stylex.create({// Helpers// =============================================================================+/** The text node holding a collapsed caret inside `editable`, if any. */+function getCaretTextNode(editable: HTMLDivElement): Node | null {+ const selection = window.getSelection();+ if (!selection || selection.rangeCount === 0) {+ return null;+ }+ const node = selection.getRangeAt(0).startContainer;+ return node.nodeType === Node.TEXT_NODE && editable.contains(node)+ ? node+ : null;+}+function getTextBeforeCursor(editable: HTMLDivElement): string | null {const selection = window.getSelection();if (!selection || selection.rangeCount === 0) {@@ -191,6 +210,38 @@ function getTextBeforeCursor(editable: HTMLDivElement): string | null {return null;}+const MAX_MULTI_WORD_QUERY_LENGTH = 64;++/**+ * An unmatched multi-word query hides the menu instead of covering prose with+ * an empty panel, unless the trigger supplies its own empty message.+ */+function isUnmatchedMultiWordQuery(+ trigger: ChatComposerTrigger | null,+ items: SearchableItem[],+ isLoading: boolean,+): boolean {+ return (+ trigger?.hasMultiWordQuery === true &&+ // `null` means "not given", exactly as `undefined` does.+ trigger.emptySearchText == null &&+ items.length === 0 &&+ !isLoading+ );+}++function isTriggerBoundary(char: string | null): boolean {+ return char === null || char === ' ' || char === '\t' || char === '\n';+}++/**+ * Finds the trigger query the caret is in (component:ChatComposerInput FR10,+ * FR11). A trigger character activates at the start of the text or after a+ * space, tab, or line break. A single-token query ends at whitespace. A+ * multi-word query ends at a line break, past the length bound, or where the+ * same trigger's character starts a new query; another trigger's character+ * inside it is ordinary text.+ */function findActiveTrigger(textBeforeCursor: string,triggers: ChatComposerTrigger[],@@ -199,25 +250,50 @@ function findActiveTrigger(query: string;triggerStart: number;} | null {- for (let i = textBeforeCursor.length - 1; i >= 0; i--) {+ let active: {trigger: ChatComposerTrigger; triggerStart: number} | null =+ null;++ for (let i = 0; i < textBeforeCursor.length; i++) {const char = textBeforeCursor[i];- if (char === ' ' || char === '\n') {- return null;+ if (char === '\n') {+ active = null;+ continue;}-- for (const trigger of triggers) {- if (char === trigger.character) {- const prevChar = i > 0 ? textBeforeCursor[i - 1] : null;- if (prevChar === null || prevChar === ' ' || prevChar === '\n') {- const query = textBeforeCursor.slice(i + 1);- return {trigger, query, triggerStart: i};- }+ if (active && !active.trigger.hasMultiWordQuery) {+ if (char === ' ' || char === '\t') {+ active = null;}+ continue;+ }+ if (active && i - active.triggerStart > MAX_MULTI_WORD_QUERY_LENGTH) {+ active = null;+ }++ if (!isTriggerBoundary(i > 0 ? textBeforeCursor[i - 1] : null)) {+ continue;+ }+ const trigger = triggers.find(t => t.character === char);+ if (!trigger) {+ continue;}+ if (active && trigger.character !== active.trigger.character) {+ continue;+ }+ active = {trigger, triggerStart: i};}- return null;+ if (!active) {+ return null;+ }+ const query = textBeforeCursor.slice(active.triggerStart + 1);+ if (+ active.trigger.hasMultiWordQuery &&+ query.length > MAX_MULTI_WORD_QUERY_LENGTH+ ) {+ return null;+ }+ return {trigger: active.trigger, query, triggerStart: active.triggerStart};}function deleteTriggerText(@@ -274,11 +350,25 @@ export function useTriggerMenu(items: [],highlightedIndex: 0,isLoading: false,+ isHidden: false,});const triggerStartRef = useRef<number>(-1);const searchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);+ const searchRequestIdRef = useRef<number>(0);+ const dismissedRef = useRef<{+ character: string;+ triggerStart: number;+ dismissedQuery: string;+ // The text the Escape dismissed. Replacing the draft from outside typing+ // (a send button, a cleared value) replaces this node, which ends the+ // dismissal without any extra bookkeeping.+ textNode: Node | null;+ } | null>(null);const anchorSpanRef = useRef<HTMLSpanElement | null>(null);+ // True while the popover is closed only because the query is unmatched; the+ // trigger query itself is still active.+ const isMenuSuppressedRef = useRef(false);const removeAnchorSpan = useCallback(() => {if (anchorSpanRef.current) {@@ -289,6 +379,10 @@ export function useTriggerMenu(const popover = usePopover({onHide: useCallback(() => {+ if (isMenuSuppressedRef.current) {+ return;+ }+ searchRequestIdRef.current++;removeAnchorSpan();setState(prev => ({...prev,@@ -298,6 +392,7 @@ export function useTriggerMenu(items: [],highlightedIndex: 0,isLoading: false,+ isHidden: false,}));}, [removeAnchorSpan]),hasLightDismiss: true,@@ -307,6 +402,7 @@ export function useTriggerMenu(// the contenteditable composer, so a modal dialog wrapper is incorrect.role: 'none',});+ const {show: showPopover, hide: hidePopover} = popover;// Cleanup on unmountuseEffect(() => {@@ -323,14 +419,29 @@ export function useTriggerMenu(clearTimeout(searchTimeoutRef.current);searchTimeoutRef.current = null;}+ searchRequestIdRef.current++;// Cancel any in-flight search on the active trigger's searchSourceconst trigger = state.activeTrigger;if (trigger?.searchSource) {trigger.searchSource.cancel?.();}removeAnchorSpan();+ isMenuSuppressedRef.current = false;+ // Ending the query also forgets an Escape on it; a send or clear must not+ // leave the next message's mention at the same offset suppressed.+ dismissedRef.current = null;popover.hide();triggerStartRef.current = -1;+ setState(prev => ({+ ...prev,+ isActive: false,+ activeTrigger: null,+ query: '',+ items: [],+ highlightedIndex: 0,+ isLoading: false,+ isHidden: false,+ }));}, [popover, state.activeTrigger, removeAnchorSpan]);// Anchor the popover to the cursor position (not the entire input).@@ -395,28 +506,69 @@ export function useTriggerMenu(searchTimeoutRef.current = null;}+ const requestId = ++searchRequestIdRef.current;+ // A result applies only while its request is the latest one and the+ // caret is still inside the same trigger query. Submitting or clearing+ // the editor ends the query without an input event, so check the DOM.+ const isCurrent = () => {+ if (requestId !== searchRequestIdRef.current) {+ return false;+ }+ const editable = editableRef.current;+ const textBefore = editable ? getTextBeforeCursor(editable) : null;+ const found =+ textBefore === null || !triggers+ ? null+ : findActiveTrigger(textBefore, triggers);+ if (+ found?.trigger.character !== trigger.character ||+ found.triggerStart !== triggerStartRef.current+ ) {+ reset();+ return false;+ }+ return true;+ };++ const applyResults = (items: SearchableItem[]) => {+ const isHidden = isUnmatchedMultiWordQuery(trigger, items, false);+ setState(prev => ({+ ...prev,+ items,+ highlightedIndex: items.length > 0 ? 0 : -1,+ isLoading: false,+ isHidden,+ }));+ // A hidden menu closes its popover, which also releases the popover's+ // Escape and light-dismiss handling; matches reopen it at the caret.+ if (isHidden && !isMenuSuppressedRef.current) {+ isMenuSuppressedRef.current = true;+ hidePopover();+ } else if (!isHidden && isMenuSuppressedRef.current) {+ isMenuSuppressedRef.current = false;+ setAnchor();+ showPopover();+ }+ };+const doSearch = () => {if (trigger.searchSource) {- // Use SearchSource \u2014 cancel previous, then search+ // Use SearchSource — cancel previous, then searchtrigger.searchSource.cancel?.();setState(prev => ({...prev, isLoading: true}));const result = trigger.searchSource.search(query);Promise.resolve(result).then(items => {- setState(prev => ({- ...prev,- items,- highlightedIndex: items.length > 0 ? 0 : -1,- isLoading: false,- }));+ if (!isCurrent()) {+ return;+ }+ applyResults(items);},() => {- setState(prev => ({- ...prev,- items: [],- highlightedIndex: -1,- isLoading: false,- }));+ if (!isCurrent()) {+ return;+ }+ applyResults([]);},);}@@ -435,7 +587,15 @@ export function useTriggerMenu(}}},- [debounceMs],+ [+ debounceMs,+ editableRef,+ triggers,+ reset,+ setAnchor,+ hidePopover,+ showPopover,+ ],);const selectItem = useCallback(@@ -490,6 +650,7 @@ export function useTriggerMenu(const textBefore = getTextBeforeCursor(editable);if (textBefore === null) {+ dismissedRef.current = null;if (state.isActive) {reset();}@@ -498,6 +659,7 @@ export function useTriggerMenu(const found = findActiveTrigger(textBefore, triggers);if (!found) {+ dismissedRef.current = null;if (state.isActive) {reset();}@@ -506,20 +668,44 @@ export function useTriggerMenu(const {trigger, query, triggerStart} = found;- if (!state.isActive || state.activeTrigger !== trigger) {+ // After Escape, keep the menu hidden while that same query keeps growing+ const dismissed = dismissedRef.current;+ if (+ dismissed &&+ dismissed.character === trigger.character &&+ dismissed.triggerStart === triggerStart &&+ dismissed.textNode !== null &&+ dismissed.textNode.isConnected &&+ dismissed.textNode === getCaretTextNode(editable)+ ) {+ if (query.startsWith(dismissed.dismissedQuery)) {+ return;+ }+ dismissedRef.current = null;+ } else {+ dismissedRef.current = null;+ }++ if (+ !state.isActive ||+ state.activeTrigger?.character !== trigger.character ||+ triggerStartRef.current !== triggerStart+ ) {triggerStartRef.current = triggerStart;+ isMenuSuppressedRef.current = false;setState(prev => ({...prev,isActive: true,activeTrigger: trigger,query,highlightedIndex: 0,+ isHidden: false,}));setAnchor();searchItems(trigger, query);popover.show();} else if (state.query !== query) {- setState(prev => ({...prev, query}));+ setState(prev => ({...prev, query, activeTrigger: trigger}));searchItems(trigger, query);}}, [@@ -534,9 +720,49 @@ export function useTriggerMenu(popover,]);+ const isMenuVisible = state.isActive && !state.isHidden;+const handleKeyDown = useCallback((e: React.KeyboardEvent): boolean => {- if (!state.isActive || !popover.isOpen) {+ // Never intercept IME composition keystrokes (e.g. Enter committing candidates)+ if (isImeKeyEvent(e.nativeEvent)) {+ return false;+ }++ // A hidden menu consumes nothing: arrows move the caret, Enter submits,+ // and Escape reaches the surrounding surface.+ if (!isMenuVisible) {+ return false;+ }++ if (e.key === 'Escape') {+ e.preventDefault();+ const editable = editableRef.current;+ const dismissed = state.activeTrigger+ ? {+ character: state.activeTrigger.character,+ triggerStart: triggerStartRef.current,+ dismissedQuery: state.query,+ textNode: editable ? getCaretTextNode(editable) : null,+ }+ : null;+ reset();+ // Remembered after reset, which clears it: the menu stays hidden while+ // this same query keeps growing.+ dismissedRef.current = dismissed;+ return true;+ }++ // A visible menu keeps the arrows even when it has nothing to pick (rows+ // still loading, or the empty message), so they never recall history+ // under an open panel. Enter and Tab pick only a settled row; otherwise+ // they keep their editor meaning, so Enter sends the message as typed.+ const hasPickableRows = !state.isLoading && state.items.length > 0;+ if (!hasPickableRows && (e.key === 'ArrowDown' || e.key === 'ArrowUp')) {+ e.preventDefault();+ return true;+ }+ if (!hasPickableRows) {return false;}@@ -575,20 +801,18 @@ export function useTriggerMenu(}return false;}- case 'Escape': {- e.preventDefault();- reset();- return true;- }default:return false;}},[- state.isActive,+ isMenuVisible,+ editableRef,+ state.activeTrigger,+ state.query,+ state.isLoading,state.highlightedIndex,state.items,- popover.isOpen,selectItem,reset,],@@ -621,7 +845,7 @@ export function useTriggerMenu(const hasTriggers = (triggers?.length ?? 0) > 0;const ariaProps: UseTriggerMenuReturn['ariaProps'] = !hasTriggers? {role: 'textbox', 'aria-multiline': 'true'}- : state.isActive && popover.isOpen+ : isMenuVisible? {role: 'combobox','aria-expanded': true as const,@@ -639,9 +863,17 @@ export function useTriggerMenu(};const renderMenu = useCallback((): ReactNode => {- const trigger = state.activeTrigger;- const emptyText = trigger?.emptySearchText ?? 'No results';- const loadingText = trigger?.loadingText ?? 'Searching\u2026';+ const activeTrigger = state.activeTrigger;+ if (!activeTrigger) {+ return null;+ }++ if (state.isHidden) {+ return null;+ }++ const emptyText = activeTrigger.emptySearchText ?? 'No results';+ const loadingText = activeTrigger.loadingText ?? 'Searching\u2026';let listContent: ReactNode;if (state.isLoading) {@@ -674,8 +906,8 @@ export function useTriggerMenu(styles.item,idx === state.highlightedIndex && styles.itemHighlighted,)}>- {trigger?.renderItem ? (- trigger.renderItem(item)+ {activeTrigger.renderItem ? (+ activeTrigger.renderItem(item)) : (<span {...stylex.props(styles.itemLabel)}>{item.label}</span>)}@@ -704,7 +936,7 @@ export function useTriggerMenu(id={listboxId}role="listbox"aria-label={- trigger?.menuLabel ?? t('@astryx.chatTriggerMenu.suggestions')+ activeTrigger.menuLabel ?? t('@astryx.chatTriggerMenu.suggestions')}{...mergeProps(themeProps('trigger-menu'),