@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Typeahead/BaseTypeahead.tsx

@@ -41,12 +41,13 @@ import {
   fontWeightVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {getKey, mergeProps, mergeRefs} from '../utils';
+import {getKey, groupItems, mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SearchableItem, SearchSource} from './types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Types
 // =============================================================================
@@ -93,6 +94,22 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
    */
   maxMenuItems?: number;
 
+  /** Fixed dropdown width in pixels. Never shrinks below the anchor width. */
+  menuWidth?: number;
+
+  /**
+   * Minimum query length before the search source is queried. Below it no
+   * search runs and the menu stays closed, so a remote source is not asked
+   * for a result set that cannot be meaningful yet — and the user does not
+   * see "no results" for a query that was never searched.
+   *
+   * Measured with `String.length` (UTF-16 code units), like every other
+   * length check in the library.
+   *
+   * @default 1 — every non-empty query is searched.
+   */
+  minQueryLength?: number;
+
   /**
    * Text shown when no results found.
    * @default 'No results found'
@@ -131,6 +148,28 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
    */
   onOpenChange?: (isOpen: boolean) => void;
 
+  /**
+   * Entries derived from the query text rather than fetched for it — today,
+   * Tokenizer's "Create ...".
+   *
+   * They are appended to whatever the search returned, and they are offered
+   * whatever `minQueryLength` says: that threshold exists to avoid a fetch
+   * that is too broad to be worth making, and these cost no fetch. A field
+   * that can create `QA` should not stop being able to just because a search
+   * for `QA` would match too much.
+   *
+   * Receives the results they will be appended to, so a caller can decline to
+   * offer an entry that duplicates one.
+   *
+   * Underscored and `@internal`: `BaseTypeaheadProps` is re-exported from the
+   * package entry point, so anything named on it ships as public API at the
+   * next cut. This is a wiring detail between Tokenizer and the base — the
+   * same reason `DefinedTheme.__inputTokens` carries its prefix.
+   *
+   * @internal
+   */
+  __queryEntries?: (query: string, results: T[]) => T[];
+
   /**
    * Debounce delay in ms before triggering search after typing.
    * Set to 0 for synchronous/local search sources that don't need debouncing.
@@ -226,6 +265,18 @@ const styles = stylex.create({
   popover: {
     minWidth: 'anchor-size(width)',
   },
+  popoverCustomWidth: (width: number) => ({
+    width: `${width}px`,
+  }),
+  groupHeading: {
+    paddingInline: spacingVars['--spacing-2'],
+    paddingBlockStart: spacingVars['--spacing-2'],
+    paddingBlockEnd: spacingVars['--spacing-1'],
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    color: colorVars['--color-text-secondary'],
+    userSelect: 'none',
+  },
   item: {
     boxSizing: 'border-box',
     display: 'flex',
@@ -285,6 +336,19 @@ const itemSizeStyles = stylex.create({
   },
 });
 
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * A query that has been typed but is still shorter than the caller's
+ * threshold. An empty query is not "below the minimum" — it is the
+ * untouched state, and `hasEntriesOnFocus` owns what happens there.
+ */
+function isBelowMinQueryLength(query: string, minQueryLength: number): boolean {
+  return query.length > 0 && query.length < minQueryLength;
+}
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -316,12 +380,15 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   placeholder: placeholderFromProps,
   hasEntriesOnFocus = false,
   maxMenuItems = 10,
+  menuWidth,
+  minQueryLength = 1,
   emptySearchResultsText: emptySearchResultsTextFromProps,
   isDisabled = false,
   isFocusableDisabled = false,
   hasAutoFocus = false,
   onChangeQuery,
   onOpenChange,
+  __queryEntries,
   inputId: externalInputId,
   ariaDescribedBy,
   ariaLabelledBy,
@@ -440,7 +507,11 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
           return;
         }
         resultsGenRef.current = gen;
-        const shown = searchResults.slice(0, maxMenuItems);
+        const fetched = searchResults.slice(0, maxMenuItems);
+        const shown = [
+          ...fetched,
+          ...(__queryEntries?.(searchQuery, fetched) ?? []),
+        ];
         setResults(shown);
         setHighlightedIndex(shown.length > 0 ? 0 : -1);
         if (searchResults.length > 0 || searchQuery.length > 0) {
@@ -473,6 +544,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       showLayer,
       announce,
       emptySearchResultsText,
+      __queryEntries,
       t,
     ],
   );
@@ -515,14 +587,35 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         clearTimeout(searchTimeoutRef.current);
       }
 
-      if (newQuery.length === 0 && !hasEntriesOnFocus) {
+      // Nothing to search: either the field was emptied, or the query is
+      // still shorter than `minQueryLength`. Both drop stale results and
+      // close the menu — showing the empty state for a query that was never
+      // searched would report "no results" that nobody looked for.
+      if (
+        (newQuery.length === 0 && !hasEntriesOnFocus) ||
+        isBelowMinQueryLength(newQuery, minQueryLength)
+      ) {
         searchGenRef.current++;
         searchSource.cancel?.();
-        setResults([]);
+        // A query too short to search can still carry entries derived from
+        // the text itself. `hasSearched` stays false either way, so the menu
+        // never reports "no results" for a query nobody looked for.
+        const derived = __queryEntries?.(newQuery, []) ?? [];
+        setResults(derived);
+        setHighlightedIndex(derived.length > 0 ? 0 : -1);
         setHasSearched(false);
+        // Bumping the generation abandons any in-flight search, which means
+        // its own `finally` will decline to clear this — so clear it here or
+        // the field spins forever. Backspacing below the threshold on a remote
+        // source is the everyday way to hit that.
+        setIsLoading(false);
         // Clear any lingering result-count / no-results announcement.
         announce('');
-        popover.hide();
+        if (derived.length > 0) {
+          showLayer();
+        } else {
+          popover.hide();
+        }
         return;
       }
 
@@ -543,6 +636,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
     [
       onChangeQuery,
       hasEntriesOnFocus,
+      minQueryLength,
+      __queryEntries,
+      showLayer,
       performSearch,
       performBootstrap,
       popover,
@@ -574,6 +670,10 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       setQuery('');
       setResults([]);
       setHasSearched(false);
+      // Same reason as in handleQueryChange: the invalidated search will not
+      // clear this itself. Selecting a stale result while the next search is
+      // still in flight would otherwise leave the field spinning.
+      setIsLoading(false);
       popover.hide();
       inputRef.current?.focus();
     },
@@ -657,7 +757,13 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
           if (results.length > 0) {
             popover.show();
             setHighlightedIndex(0);
-          } else if (hasEntriesOnFocus) {
+          } else if (
+            hasEntriesOnFocus &&
+            // A below-threshold query was never searched; falling back to the
+            // bootstrap entries here would open a menu of suggestions that
+            // ignore what the user has already typed.
+            !isBelowMinQueryLength(query, minQueryLength)
+          ) {
             void performBootstrap();
           }
         }
@@ -691,6 +797,14 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
           e.preventDefault();
           popover.hide();
           break;
+        case 'Tab':
+          // Dismiss here rather than from the blur this press produces:
+          // hiding a top-layer popover during the focusout makes Chrome
+          // abandon the in-flight focus move and drop focus to <body>, so the
+          // user's Tab appears to do nothing. Selector and MultiSelector
+          // already dismiss on this keydown.
+          popover.hide();
+          break;
         case 'Home':
           if (popover.isOpen) {
             e.preventDefault();
@@ -715,7 +829,8 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       highlightedIndex,
       handleSelect,
       hasEntriesOnFocus,
-      query.length,
+      query,
+      minQueryLength,
       performBootstrap,
       externalOnKeyDown,
     ],
@@ -760,7 +875,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   return (
     <>
       <input
-        ref={mergeRefs(ref, inputRef, fallbackAnchorRef)}
+        ref={useMergedRefs(ref, inputRef, fallbackAnchorRef)}
         id={inputId}
         type="text"
         role="combobox"
@@ -835,44 +950,71 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
               {emptySearchResultsText}
             </div>
           ) : (
-            results.map((item, index) => {
-              const itemKey = getKey(item.id, index);
-              const isSelected = itemKey === selectedKey;
-              return (
-                <div
-                  key={itemKey}
-                  id={getItemId(index)}
-                  role="option"
-                  aria-selected={isSelected}
-                  tabIndex={-1}
-                  onClick={() => handleSelect(item)}
-                  onMouseEnter={() => setHighlightedIndex(index)}
-                  {...stylex.props(
-                    styles.item,
-                    itemSizeStyles[size],
-                    index === highlightedIndex && styles.itemHighlighted,
-                    isSelected && styles.itemSelected,
-                  )}>
-                  <span {...stylex.props(styles.itemContent)}>
-                    {renderItem ? (
-                      renderItem(item)
-                    ) : (
-                      <TypeaheadItem item={item} />
+            (() => {
+              let flatIndex = 0;
+              const renderOption = (item: T) => {
+                const index = flatIndex++;
+                const itemKey = getKey(item.id, index);
+                const isSelected = itemKey === selectedKey;
+                return (
+                  <div
+                    key={itemKey}
+                    id={getItemId(index)}
+                    role="option"
+                    aria-selected={isSelected}
+                    tabIndex={-1}
+                    onClick={() => handleSelect(item)}
+                    onMouseEnter={() => setHighlightedIndex(index)}
+                    {...stylex.props(
+                      styles.item,
+                      itemSizeStyles[size],
+                      index === highlightedIndex && styles.itemHighlighted,
+                      isSelected && styles.itemSelected,
+                    )}>
+                    <span {...stylex.props(styles.itemContent)}>
+                      {renderItem ? (
+                        renderItem(item)
+                      ) : (
+                        <TypeaheadItem item={item} />
+                      )}
+                    </span>
+                    {isSelected && (
+                      <Icon icon="check" size="sm" color="primary" />
                     )}
-                  </span>
-                  {isSelected && (
-                    <Icon icon="check" size="sm" color="primary" />
-                  )}
-                </div>
-              );
-            })
+                  </div>
+                );
+              };
+
+              return groupItems(results, {ungroupedFirst: true}).map(group => {
+                const options = group.items.map(renderOption);
+                if (group.heading == null) {
+                  return options;
+                }
+                return (
+                  <div
+                    key={`group-${group.heading}`}
+                    role="group"
+                    aria-label={group.heading}>
+                    <div
+                      aria-hidden="true"
+                      {...stylex.props(styles.groupHeading)}>
+                      {group.heading}
+                    </div>
+                    {options}
+                  </div>
+                );
+              });
+            })()
           )}
         </div>,
         {
           placement: 'below',
           alignment: 'start',
           offset: spacingVars['--spacing-1'],
-          xstyle: styles.popover,
+          xstyle: [
+            styles.popover,
+            menuWidth != null && styles.popoverCustomWidth(menuWidth),
+          ],
         },
       )}
     </>

package/src/Typeahead/Typeahead.doc.mjs

@@ -83,6 +83,12 @@ export const docs = {
       description: 'Maximum number of dropdown items to display.',
       default: '10',
     },
+    {
+      name: 'minQueryLength',
+      type: 'number',
+      description: 'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',
+      default: '1',
+    },
     {
       name: 'status',
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
@@ -171,6 +177,11 @@ export const docs = {
       description:
         'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
     },
+    {
+      name: 'startIcon',
+      type: 'IconType | ReactNode',
+      description: 'SVG icon component displayed at the start of the input.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',

package/src/Typeahead/Typeahead.test.tsx

@@ -420,6 +420,55 @@ describe('BaseTypeahead focus-out', () => {
     });
   });
 
+  it('closes the list on the Tab keydown, before the blur it produces', async () => {
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    input.focus();
+    fireEvent.change(input, {target: {value: 'App'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    // No blur is fired here on purpose: dismissing from the blur instead lets
+    // the popover close mid-focus-move, which Chrome answers by dropping
+    // focus to <body>.
+    fireEvent.keyDown(input, {key: 'Tab'});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'false');
+    });
+  });
+
+  it('Tab from the input with the list open moves focus to the next control', async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />
+        <button type="button">Next</button>
+      </>,
+    );
+    const input = screen.getByRole('combobox');
+    input.focus();
+    fireEvent.change(input, {target: {value: 'App'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    await user.keyboard('{Tab}');
+    expect(screen.getByRole('button', {name: 'Next'})).toHaveFocus();
+  });
+
   it('keeps the dropdown open when focus moves into the anchor wrapper', async () => {
     const anchor = document.createElement('div');
     document.body.appendChild(anchor);
@@ -729,6 +778,160 @@ describe('BaseTypeahead hasEntriesOnFocus', () => {
   });
 });
 
+describe('BaseTypeahead minQueryLength', () => {
+  it('does not search or open the menu below the threshold', async () => {
+    const search = vi.fn((query: string) =>
+      fruits.filter(f => f.label.toLowerCase().includes(query.toLowerCase())),
+    );
+    render(
+      <BaseTypeahead
+        searchSource={{search, bootstrap: () => []}}
+        value={null}
+        onChange={() => {}}
+        minQueryLength={3}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    fireEvent.change(input, {target: {value: 'Ap'}});
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    expect(search).not.toHaveBeenCalled();
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+
+    // Positive control: the third character crosses the threshold, so the
+    // same harness does see the search and the open menu.
+    fireEvent.change(input, {target: {value: 'App'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+    expect(search).toHaveBeenCalledExactlyOnceWith('App');
+  });
+
+  it('closes the menu again when the query falls back below the threshold', async () => {
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        minQueryLength={3}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    fireEvent.change(input, {target: {value: 'App'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    fireEvent.change(input, {target: {value: 'Ap'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'false');
+    });
+  });
+
+  it('does not fall back to bootstrap entries on ArrowDown below the threshold', async () => {
+    const bootstrap = vi.fn(() => fruits.slice(0, 3));
+    render(
+      <BaseTypeahead
+        searchSource={{search: () => [], bootstrap}}
+        value={null}
+        onChange={() => {}}
+        hasEntriesOnFocus
+        minQueryLength={3}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    fireEvent.focus(input);
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+    bootstrap.mockClear();
+
+    // Typing below the threshold closes the bootstrap menu...
+    fireEvent.change(input, {target: {value: 'Ap'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    // ...and ArrowDown must not re-open it with entries that ignore the
+    // two characters already typed.
+    fireEvent.keyDown(input, {key: 'ArrowDown'});
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(bootstrap).not.toHaveBeenCalled();
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('searches on the first character when minQueryLength is not set', async () => {
+    const search = vi.fn(() => fruits.slice(0, 1));
+    render(
+      <BaseTypeahead
+        searchSource={{search, bootstrap: () => []}}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    fireEvent.change(input, {target: {value: 'A'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+    expect(search).toHaveBeenCalledExactlyOnceWith('A');
+  });
+
+  it('stops reporting "Loading" when the query falls below the threshold mid-search', async () => {
+    // Falling below the threshold abandons the in-flight search by bumping the
+    // search generation, which also makes that search decline to clear the
+    // loading flag on its way out. Backspacing from three characters to two on
+    // a remote source is the everyday way to hit it, and the field would
+    // otherwise report "Loading" to a screen reader until the third character
+    // went back in.
+    let settle: (items: SearchableItem[]) => void = () => {};
+    const search = vi.fn(
+      async () =>
+        new Promise<SearchableItem[]>(resolve => {
+          settle = resolve;
+        }),
+    );
+    render(
+      <BaseTypeahead
+        searchSource={{search, bootstrap: () => []}}
+        value={null}
+        onChange={() => {}}
+        minQueryLength={3}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    fireEvent.change(input, {target: {value: 'App'}});
+    await waitFor(() => {
+      expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+    });
+
+    fireEvent.change(input, {target: {value: 'Ap'}});
+    await act(async () => {
+      settle(fruits.slice(0, 1));
+      await Promise.resolve();
+    });
+
+    expect(
+      screen.queryByRole('status', {name: 'Loading'}),
+    ).not.toBeInTheDocument();
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+  });
+});
+
 describe('BaseTypeahead hasSearched reset', () => {
   it('does not show "No results found" after selecting an item and re-entering', async () => {
     const onChange = vi.fn();

package/src/Typeahead/Typeahead.tsx

@@ -45,13 +45,14 @@ import {VisuallyHidden} from '../VisuallyHidden';
 import {spacingVars, sizeVars} from '../theme/tokens.stylex';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
-import {getInputARIA, isImeKeyEvent, mergeProps, mergeRefs} from '../utils';
+import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import type {SearchableItem, SearchSource} from './types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 export type {
   InputStatus as TypeaheadStatus,
   InputStatusType as TypeaheadStatusType,
@@ -110,6 +111,13 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<
   hasEntriesOnFocus?: boolean;
   /** Max dropdown items. @default 10 */
   maxMenuItems?: number;
+  /**
+   * Minimum query length before the search source is queried. Below it no
+   * search runs and the menu stays closed — useful for remote sources where
+   * one or two characters match too much to be worth fetching.
+   * @default 1
+   */
+  minQueryLength?: number;
   /** Text shown when no results found. @default 'No results found' */
   emptySearchResultsText?: string;
   /** Whether the input is disabled. @default false */
@@ -247,6 +255,7 @@ export function Typeahead<T extends SearchableItem>({
   placeholder,
   hasEntriesOnFocus,
   maxMenuItems,
+  minQueryLength,
   emptySearchResultsText,
   isDisabled = false,
   disabledMessage,
@@ -418,7 +427,7 @@ export function Typeahead<T extends SearchableItem>({
   const typeaheadContent = (
     <>
       <div
-        ref={mergeRefs(
+        ref={useMergedRefs(
           wrapperRef,
           disabledMessageTooltip.ref,
           inputGroup ? ref : undefined,
@@ -466,6 +475,7 @@ export function Typeahead<T extends SearchableItem>({
           placeholder={showToken ? undefined : placeholder}
           hasEntriesOnFocus={hasEntriesOnFocus}
           maxMenuItems={maxMenuItems}
+          minQueryLength={minQueryLength}
           emptySearchResultsText={emptySearchResultsText}
           isDisabled={isDisabled}
           hasAutoFocus={hasAutoFocus}

package/src/Typeahead/TypeaheadItem.test.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TypeaheadItem.test.tsx
+ * @input Uses vitest, @testing-library/react, TypeaheadItem
+ * @output Unit tests for TypeaheadItem
+ * @position Testing; validates TypeaheadItem.tsx implementation
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {TypeaheadItem} from './TypeaheadItem';
+
+describe('TypeaheadItem', () => {
+  it('forwards pass-through props to the item element', () => {
+    render(
+      <TypeaheadItem
+        item={{id: '1', label: 'Alice'}}
+        aria-label="Alice, engineer"
+        id="result-1"
+        data-source="directory"
+        data-testid="item"
+      />,
+    );
+    const item = screen.getByTestId('item');
+    expect(item).toHaveAttribute('aria-label', 'Alice, engineer');
+    expect(item).toHaveAttribute('id', 'result-1');
+    expect(item).toHaveAttribute('data-source', 'directory');
+  });
+
+  it('merges a caller className with its own classes', () => {
+    render(
+      <TypeaheadItem
+        item={{id: '1', label: 'Alice'}}
+        className="caller-class"
+        data-testid="item"
+      />,
+    );
+    const item = screen.getByTestId('item');
+    expect(item.className).toContain('caller-class');
+    expect(item.className).toContain('astryx-typeahead-item');
+  });
+});