An open source design system that's fully customizable and agent ready
TypeScript
xds typeahead (#662)
Andrey Goderb92383e50c49
diff --git a/apps/storybook/stories/Tokenizer.stories.tsx b/apps/storybook/stories/Tokenizer.stories.tsxindex 8104f9e296..97ad9089ce 100644--- a/apps/storybook/stories/Tokenizer.stories.tsx+++ b/apps/storybook/stories/Tokenizer.stories.tsx@@ -189,6 +189,26 @@ export const WithStartIconAndTokens: Story = {name: 'With Start Icon and Tokens',};+export const WithEntriesOnFocus: Story = {+ render: args => {+ const [value, setValue] = useState<XDSSearchableItem[]>([]);+ return (+ <XDSTokenizer+ {...args}+ searchSource={userSource}+ value={value}+ onChange={items => setValue(items)}+ hasEntriesOnFocus+ />+ );+ },+ args: {+ label: 'Team Members',+ placeholder: 'Click to see suggestions...',+ },+ name: 'With Entries On Focus',+};+export const WithEndContent: Story = {render: args => {const [value, setValue] = useState<XDSSearchableItem[]>([diff --git a/packages/core/src/DateInput/XDSDateInput.tsx b/packages/core/src/DateInput/XDSDateInput.tsxindex b4c0dc0d12..a04876ce5f 100644--- a/packages/core/src/DateInput/XDSDateInput.tsx+++ b/packages/core/src/DateInput/XDSDateInput.tsx@@ -327,14 +327,16 @@ export function XDSDateInput({}, [pendingInput]);// Use XDSPopover for popover rendering, positioning, and focus trapping+ const handlePopoverHide = useCallback(() => {+ // Return focus to input when popover closes+ inputRef.current?.focus();+ }, []);+const popover = useXDSPopover({xstyle: styles.popover,dialogLabel: 'Choose date',closeButtonLabel: 'Close calendar',- onHide: () => {- // Return focus to input when popover closes- inputRef.current?.focus();- },+ onHide: handlePopoverHide,});// Handle opening the popover from button click (focus calendar)diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsxindex cbb8391f09..8d54759b31 100644--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx@@ -333,25 +333,29 @@ export function XDSDropdownMenu({const selectableItems = useMemo(() => getSelectableItems(items), [items]);// Layer for dropdown positioning+ const handleLayerHide = useCallback(() => {+ if (isControlled) {+ onOpenChange?.(false);+ } else {+ setInternalIsOpen(false);+ }+ setHighlightedIndex(-1);+ buttonRef.current?.focus();+ }, [isControlled, onOpenChange]);++ const handleLayerShow = useCallback(() => {+ if (isControlled) {+ onOpenChange?.(true);+ } else {+ setInternalIsOpen(true);+ }+ }, [isControlled, onOpenChange]);+const layer = useXDSLayer({mode: 'context',lightDismiss: true,- onHide: () => {- if (isControlled) {- onOpenChange?.(false);- } else {- setInternalIsOpen(false);- }- setHighlightedIndex(-1);- buttonRef.current?.focus();- },- onShow: () => {- if (isControlled) {- onOpenChange?.(true);- } else {- setInternalIsOpen(true);- }- },+ onHide: handleLayerHide,+ onShow: handleLayerShow,});// Sync layer with controlled statediff --git a/packages/core/src/HoverCard/XDSHoverCard.tsx b/packages/core/src/HoverCard/XDSHoverCard.tsxindex 433ad08fc4..99752c015d 100644--- a/packages/core/src/HoverCard/XDSHoverCard.tsx+++ b/packages/core/src/HoverCard/XDSHoverCard.tsx@@ -13,6 +13,7 @@'use client';import React, {+ useCallback,useLayoutEffect,useRef,type ReactElement,@@ -165,6 +166,14 @@ export function XDSHoverCard({const showHoverIndication =hasHoverIndication === true || (hasHoverIndication === 'auto' && textOnly);+ const handleShow = useCallback(() => {+ onOpenChange?.(true);+ }, [onOpenChange]);++ const handleHide = useCallback(() => {+ onOpenChange?.(false);+ }, [onOpenChange]);+// Use the hook for all hover card behaviorconst hoverCard = useXDSHoverCard({placement,@@ -173,8 +182,8 @@ export function XDSHoverCard({hideDelay,focusTrigger,isEnabled,- onShow: onOpenChange ? () => onOpenChange(true) : undefined,- onHide: onOpenChange ? () => onOpenChange(false) : undefined,+ onShow: handleShow,+ onHide: handleHide,});// For element children with display:contents, attach ref to first childdiff --git a/packages/core/src/HoverCard/useXDSHoverCard.tsx b/packages/core/src/HoverCard/useXDSHoverCard.tsxindex 7a559ab2e3..f4c5886248 100644--- a/packages/core/src/HoverCard/useXDSHoverCard.tsx+++ b/packages/core/src/HoverCard/useXDSHoverCard.tsx@@ -130,12 +130,14 @@ export interface XDSHoverCardOptions {isEnabled?: boolean;/**- * Callback fired when hover card is shown+ * Callback fired when hover card is shown.+ * Wrap in useCallback for stable identity.*/onShow?: () => void;/**- * Callback fired when hover card is hidden+ * Callback fired when hover card is hidden.+ * Wrap in useCallback for stable identity.*/onHide?: () => void;}diff --git a/packages/core/src/Layer/useXDSLayer.tsx b/packages/core/src/Layer/useXDSLayer.tsxindex 7ab06d89ac..f9adf10a29 100644--- a/packages/core/src/Layer/useXDSLayer.tsx+++ b/packages/core/src/Layer/useXDSLayer.tsx@@ -88,12 +88,14 @@ export interface FixedRenderProps {*/interface BaseLayerOptions {/**- * Callback fired when layer is shown+ * Callback fired when layer is shown.+ * Wrap in useCallback for stable identity.*/onShow?: () => void;/**- * Callback fired when layer is hidden+ * Callback fired when layer is hidden.+ * Wrap in useCallback for stable identity.*/onHide?: () => void;@@ -313,6 +315,17 @@ export function useXDSLayer([onShow, onHide],);+ // Ref callback for popover element — sets up toggle listener+ const popoverRefCallback = useCallback(+ (el: HTMLElement | null) => {+ popoverRef.current = el;+ if (el) {+ el.addEventListener('toggle', handleToggle);+ }+ },+ [handleToggle],+ );+// Render function for context modeconst renderContext = useCallback((children: ReactNode, props?: ContextRenderProps) => {@@ -327,12 +340,7 @@ export function useXDSLayer(return (<div- ref={el => {- popoverRef.current = el;- if (el) {- el.addEventListener('toggle', handleToggle);- }- }}+ ref={popoverRefCallback}id={id}popover={lightDismiss ? 'auto' : 'manual'}{...stylex.props(styles.base, xstyle)}@@ -341,7 +349,7 @@ export function useXDSLayer(</div>);},- [anchorId, handleToggle, id, lightDismiss],+ [anchorId, id, lightDismiss, popoverRefCallback],);// Render function for fixed mode@@ -357,12 +365,7 @@ export function useXDSLayer(return (<div- ref={el => {- popoverRef.current = el;- if (el) {- el.addEventListener('toggle', handleToggle);- }- }}+ ref={popoverRefCallback}id={id}popover={lightDismiss ? 'auto' : 'manual'}{...stylex.props(styles.base, styles.fixed)}@@ -371,7 +374,7 @@ export function useXDSLayer(</div>);},- [handleToggle, id, lightDismiss],+ [popoverRefCallback, id, lightDismiss],);if (mode === 'context') {diff --git a/packages/core/src/MoreMenu/XDSMoreMenu.tsx b/packages/core/src/MoreMenu/XDSMoreMenu.tsxindex c31d8a73fe..9859a559fd 100644--- a/packages/core/src/MoreMenu/XDSMoreMenu.tsx+++ b/packages/core/src/MoreMenu/XDSMoreMenu.tsx@@ -256,13 +256,15 @@ export function XDSMoreMenu({const selectableItems = useMemo(() => getSelectableItems(items), [items]);+ const handleLayerHide = useCallback(() => {+ setHighlightedIndex(-1);+ buttonRef.current?.focus();+ }, []);+const layer = useXDSLayer({mode: 'context',lightDismiss: true,- onHide: () => {- setHighlightedIndex(-1);- buttonRef.current?.focus();- },+ onHide: handleLayerHide,});const handleButtonClick = useCallback(() => {diff --git a/packages/core/src/Popover/XDSPopover.tsx b/packages/core/src/Popover/XDSPopover.tsxindex 923bf4c2f5..830694f9b0 100644--- a/packages/core/src/Popover/XDSPopover.tsx+++ b/packages/core/src/Popover/XDSPopover.tsx@@ -276,14 +276,20 @@ export function XDSPopover({// the trigger click from immediately re-opening it.const lastHideTimeRef = useRef(0);+ const handlePopoverShow = useCallback(() => {+ onOpenChange?.(true);+ }, [onOpenChange]);++ const handlePopoverHide = useCallback(() => {+ lastHideTimeRef.current = Date.now();+ onOpenChange?.(false);+ }, [onOpenChange]);+const popover = useXDSPopover({dialogLabel: label,hasLightDismiss: true,- onShow: () => onOpenChange?.(true),- onHide: () => {- lastHideTimeRef.current = Date.now();- onOpenChange?.(false);- },+ onShow: handlePopoverShow,+ onHide: handlePopoverHide,});// Shared handler for click events on the trigger button.diff --git a/packages/core/src/Popover/useXDSPopover.tsx b/packages/core/src/Popover/useXDSPopover.tsxindex 3e97206288..06ec5093eb 100644--- a/packages/core/src/Popover/useXDSPopover.tsx+++ b/packages/core/src/Popover/useXDSPopover.tsx@@ -87,13 +87,15 @@ const styles = stylex.create({*/export interface UseXDSPopoverOptions {/**- * Callback fired when popover is shown+ * Callback fired when popover is shown.+ * Wrap in useCallback for stable identity.*/onShow?: () => void;/*** Callback fired when popover is hidden.* Use this to return focus to the trigger element.+ * Wrap in useCallback for stable identity.*/onHide?: () => void;diff --git a/packages/core/src/PowerSearch/PowerSearchEditPopover.tsx b/packages/core/src/PowerSearch/PowerSearchEditPopover.tsxindex f5d23658a6..58c27df4ea 100644--- a/packages/core/src/PowerSearch/PowerSearchEditPopover.tsx+++ b/packages/core/src/PowerSearch/PowerSearchEditPopover.tsx@@ -692,15 +692,18 @@ export function PowerSearchEditPopover({const isSaveDisabled = !partialFilter.operator || !partialFilter.value;- // Handle Enter key anywhere in the popover to trigger save+ // Handle Enter to save, Escape to cancelconst handleKeyDown = useCallback((e: React.KeyboardEvent) => {if (e.key === 'Enter' && !isSaveDisabled) {e.preventDefault();handleSave();+ } else if (e.key === 'Escape' && !e.defaultPrevented) {+ e.preventDefault();+ onCancel();}},- [isSaveDisabled, handleSave],+ [isSaveDisabled, handleSave, onCancel],);const operatorValue: OperatorValue | undefined = currentOperator?.value;@@ -723,7 +726,7 @@ export function PowerSearchEditPopover({// Nested filter editingif (isNestedType) {return (- <div {...stylex.props(styles.container)}>+ <div {...stylex.props(styles.container)} onKeyDown={handleKeyDown}><div {...stylex.props(styles.content)}><XDSVStack gap={2}><XDSHStack gap={2}>diff --git a/packages/core/src/PowerSearch/XDSPowerSearch.tsx b/packages/core/src/PowerSearch/XDSPowerSearch.tsxindex 99834bf01f..531871b25b 100644--- a/packages/core/src/PowerSearch/XDSPowerSearch.tsx+++ b/packages/core/src/PowerSearch/XDSPowerSearch.tsx@@ -473,12 +473,14 @@ export function XDSPowerSearch({});// Layer for positioning the edit popover anchored to the tokenizer+ const handleLayerHide = useCallback(() => {+ setPopoverStateRaw({type: 'idle'});+ }, []);+const layer = useXDSLayer({mode: 'context',lightDismiss: true,- onHide() {- setPopoverStateRaw({type: 'idle'});- },+ onHide: handleLayerHide,});// Wrapper that manages layer visibility and tokenizer focus alongside statediff --git a/packages/core/src/Selector/XDSSelector.tsx b/packages/core/src/Selector/XDSSelector.tsxindex beb8bb76fc..60fe29dabf 100644--- a/packages/core/src/Selector/XDSSelector.tsx+++ b/packages/core/src/Selector/XDSSelector.tsx@@ -438,12 +438,14 @@ export function XDSSelector<T extends XDSSelectorOptionType>({const listboxRef = useRef<HTMLDivElement>(null);// Layer for dropdown positioning+ const handleLayerHide = useCallback(() => {+ triggerRef.current?.focus();+ }, []);+const layer = useXDSLayer({mode: 'context',lightDismiss: true,- onHide: () => {- triggerRef.current?.focus();- },+ onHide: handleLayerHide,});// Calculate offset to position selected item over triggerdiff --git a/packages/core/src/Selector/hooks.ts b/packages/core/src/Selector/hooks.tsindex f944b58866..595213466f 100644--- a/packages/core/src/Selector/hooks.ts+++ b/packages/core/src/Selector/hooks.ts@@ -233,8 +233,10 @@ export function useCombobox({break;case 'Escape':- e.preventDefault();- closeAndReset();+ if (isOpen) {+ e.preventDefault();+ closeAndReset();+ }break;case 'Home':diff --git a/packages/core/src/Tooltip/XDSTooltip.tsx b/packages/core/src/Tooltip/XDSTooltip.tsxindex 58a4add74a..1c38e09866 100644--- a/packages/core/src/Tooltip/XDSTooltip.tsx+++ b/packages/core/src/Tooltip/XDSTooltip.tsx@@ -12,6 +12,7 @@'use client';import React, {+ useCallback,useLayoutEffect,useRef,type ReactElement,@@ -175,6 +176,14 @@ export function XDSTooltip({const showHoverIndication =hasHoverIndication === true || (hasHoverIndication === 'auto' && textOnly);+ const handleShow = useCallback(() => {+ onOpenChange?.(true);+ }, [onOpenChange]);++ const handleHide = useCallback(() => {+ onOpenChange?.(false);+ }, [onOpenChange]);+// Use the hook for all tooltip behaviorconst tooltip = useXDSTooltip({placement,@@ -183,8 +192,8 @@ export function XDSTooltip({hideDelay,focusTrigger,isEnabled,- onShow: onOpenChange ? () => onOpenChange(true) : undefined,- onHide: onOpenChange ? () => onOpenChange(false) : undefined,+ onShow: handleShow,+ onHide: handleHide,});// Sibling mode: attach to external anchorRefdiff --git a/packages/core/src/Tooltip/useXDSTooltip.tsx b/packages/core/src/Tooltip/useXDSTooltip.tsxindex 0c62cc37c7..0d2b646f54 100644--- a/packages/core/src/Tooltip/useXDSTooltip.tsx+++ b/packages/core/src/Tooltip/useXDSTooltip.tsx@@ -138,12 +138,14 @@ export interface XDSTooltipOptions {isEnabled?: boolean;/**- * Callback fired when tooltip is shown+ * Callback fired when tooltip is shown.+ * Wrap in useCallback for stable identity.*/onShow?: () => void;/**- * Callback fired when tooltip is hidden+ * Callback fired when tooltip is hidden.+ * Wrap in useCallback for stable identity.*/onHide?: () => void;}diff --git a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsxindex 26f2e3f3bf..c1a94d76c1 100644--- a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx+++ b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx@@ -329,11 +329,19 @@ function DefaultMegaMenu({const triggerButtonRef = useRef<HTMLButtonElement | null>(null);const clickLockedRef = useRef(false);+ const handlePopoverShow = useCallback(() => {+ onOpenChange?.(true);+ }, [onOpenChange]);++ const handlePopoverHide = useCallback(() => {+ onOpenChange?.(false);+ }, [onOpenChange]);+const popover = useXDSPopover({dialogLabel: label,xstyle: styles.panelAnimation,- onShow: () => onOpenChange?.(true),- onHide: () => onOpenChange?.(false),+ onShow: handlePopoverShow,+ onHide: handlePopoverHide,});// Set the CSS anchor to the parent <nav> element (the XDSTopNav).diff --git a/packages/core/src/Typeahead/XDSBaseTypeahead.tsx b/packages/core/src/Typeahead/XDSBaseTypeahead.tsxindex 527302a2be..358c829391 100644--- a/packages/core/src/Typeahead/XDSBaseTypeahead.tsx+++ b/packages/core/src/Typeahead/XDSBaseTypeahead.tsx@@ -284,33 +284,58 @@ export const XDSBaseTypeahead = function XDSBaseTypeahead<const [isLoading, setIsLoading] = useState(false);const [hasSearched, setHasSearched] = useState(false);+ // Track active pointer to defer layer.show() past click events.+ // With popover="auto", showing the popover between pointerdown and+ // pointerup/click causes the browser's light-dismiss to immediately+ // close it (the click is seen as "outside" the newly-opened popover).+ const pointerActiveRef = useRef(false);+// Debounce refconst searchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);// Layer for dropdown+ const handleLayerShow = useCallback(() => {+ onOpenChange?.(true);+ }, [onOpenChange]);++ const handleLayerHide = useCallback(() => {+ onOpenChange?.(false);+ setHighlightedIndex(-1);+ searchSource.cancel?.();+ }, [onOpenChange, searchSource]);+const layer = useXDSLayer({mode: 'context',lightDismiss: true,- onShow: () => onOpenChange?.(true),- onHide: () => {- onOpenChange?.(false);- setHighlightedIndex(-1);- searchSource.cancel?.();- },+ onShow: handleLayerShow,+ onHide: handleLayerHide,});+ // Show the layer, deferring past the active click if a pointer is down.+ // Without this, popover="auto" light-dismiss immediately closes the+ // dropdown when it opens between pointerdown and pointerup/click.+ const showLayer = useCallback(() => {+ if (pointerActiveRef.current) {+ document.addEventListener(+ 'click',+ () => requestAnimationFrame(() => layer.show()),+ {once: true},+ );+ } else {+ layer.show();+ }+ }, [layer]);+// Merge refs: forward ref + internal ref + fallback anchor refconst setInputRef = useCallback((el: HTMLInputElement | null) => {- (inputRef as React.MutableRefObject<HTMLInputElement | null>).current =+ (inputRef as React.RefObject<HTMLInputElement | null>).current = el;+ (fallbackAnchorRef as React.RefObject<HTMLInputElement | null>).current =el;- (- fallbackAnchorRef as React.MutableRefObject<HTMLInputElement | null>- ).current = el;if (typeof ref === 'function') {ref(el);} else if (ref) {- (ref as React.MutableRefObject<HTMLInputElement | null>).current = el;+ (ref as React.RefObject<HTMLInputElement | null>).current = el;}},[ref],@@ -338,7 +363,7 @@ export const XDSBaseTypeahead = function XDSBaseTypeahead<setResults(searchResults.slice(0, maxMenuItems));setHighlightedIndex(searchResults.length > 0 ? 0 : -1);if (searchResults.length > 0 || searchQuery.length > 0) {- layer.show();+ showLayer();}} catch {setResults([]);@@ -347,7 +372,7 @@ export const XDSBaseTypeahead = function XDSBaseTypeahead<setIsLoading(false);}},- [searchSource, maxMenuItems, layer],+ [searchSource, maxMenuItems, showLayer],);// Perform bootstrap@@ -358,14 +383,14 @@ export const XDSBaseTypeahead = function XDSBaseTypeahead<setResults(bootstrapResults.slice(0, maxMenuItems));setHighlightedIndex(bootstrapResults.length > 0 ? 0 : -1);if (bootstrapResults.length > 0) {- layer.show();+ showLayer();}} catch {setResults([]);} finally {setIsLoading(false);}- }, [searchSource, maxMenuItems, layer]);+ }, [searchSource, maxMenuItems, showLayer]);// Handle query changeconst handleQueryChange = useCallback(@@ -434,8 +459,8 @@ export const XDSBaseTypeahead = function XDSBaseTypeahead<if (isDisabled) return;if (hasEntriesOnFocus && results.length === 0 && query.length === 0) {performBootstrap();- } else if (query.length > 0 && results.length > 0) {- layer.show();+ } else if (results.length > 0 && (query.length > 0 || hasEntriesOnFocus)) {+ showLayer();}}, [isDisabled,@@ -443,7 +468,7 @@ export const XDSBaseTypeahead = function XDSBaseTypeahead<results.length,query.length,performBootstrap,- layer,+ showLayer,]);// Keyboard navigation@@ -548,6 +573,16 @@ export const XDSBaseTypeahead = function XDSBaseTypeahead<aria-describedby={ariaDescribedBy}value={query}onChange={handleInputChange}+ onPointerDown={() => {+ pointerActiveRef.current = true;+ document.addEventListener(+ 'click',+ () => {+ pointerActiveRef.current = false;+ },+ {once: true},+ );+ }}onFocus={handleFocus}onKeyDown={handleKeyDown}placeholder={placeholder}diff --git a/packages/core/src/Typeahead/XDSTypeahead.test.tsx b/packages/core/src/Typeahead/XDSTypeahead.test.tsxindex eddd916190..8e72e94d83 100644--- a/packages/core/src/Typeahead/XDSTypeahead.test.tsx+++ b/packages/core/src/Typeahead/XDSTypeahead.test.tsx@@ -238,6 +238,78 @@ describe('XDSTypeahead', () => {});});+describe('XDSBaseTypeahead hasEntriesOnFocus', () => {+ it('shows bootstrap results on mouse click', async () => {+ render(+ <XDSBaseTypeahead+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ hasEntriesOnFocus+ debounceMs={0}+ />,+ );+ const input = screen.getByRole('combobox');++ // Simulate full mouse click sequence (pointerdown → focus → pointerup → click)+ fireEvent.pointerDown(input);+ fireEvent.focus(input);+ fireEvent.pointerUp(input);+ fireEvent.click(input);++ await waitFor(() => {+ expect(input).toHaveAttribute('aria-expanded', 'true');+ });+ });++ it('shows bootstrap results on keyboard focus', async () => {+ render(+ <XDSBaseTypeahead+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ hasEntriesOnFocus+ debounceMs={0}+ />,+ );+ const input = screen.getByRole('combobox');++ // Keyboard focus — no pointer events+ fireEvent.focus(input);++ await waitFor(() => {+ expect(input).toHaveAttribute('aria-expanded', 'true');+ });+ });++ it('re-shows results on refocus when results already exist', async () => {+ render(+ <XDSBaseTypeahead+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ hasEntriesOnFocus+ debounceMs={0}+ />,+ );+ const input = screen.getByRole('combobox');++ // Initial focus to load bootstrap results+ fireEvent.focus(input);+ await waitFor(() => {+ expect(input).toHaveAttribute('aria-expanded', 'true');+ });++ // Blur to close, then refocus+ fireEvent.blur(input);+ fireEvent.focus(input);++ await waitFor(() => {+ expect(input).toHaveAttribute('aria-expanded', 'true');+ });+ });+});+describe('XDSTypeahead edit mode', () => {it('enters edit mode on token container click', () => {const onChange = vi.fn();