@astryxdesign/core 0.5.0 → 0.5.1-canary.f64186a

package/src/Typeahead/BaseTypeahead.tsx

@@ -97,6 +97,19 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
   /** 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'
@@ -135,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.
@@ -301,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
 // =============================================================================
@@ -333,12 +381,14 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   hasEntriesOnFocus = false,
   maxMenuItems = 10,
   menuWidth,
+  minQueryLength = 1,
   emptySearchResultsText: emptySearchResultsTextFromProps,
   isDisabled = false,
   isFocusableDisabled = false,
   hasAutoFocus = false,
   onChangeQuery,
   onOpenChange,
+  __queryEntries,
   inputId: externalInputId,
   ariaDescribedBy,
   ariaLabelledBy,
@@ -457,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) {
@@ -490,6 +544,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       showLayer,
       announce,
       emptySearchResultsText,
+      __queryEntries,
       t,
     ],
   );
@@ -532,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;
       }
 
@@ -560,6 +636,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
     [
       onChangeQuery,
       hasEntriesOnFocus,
+      minQueryLength,
+      __queryEntries,
+      showLayer,
       performSearch,
       performBootstrap,
       popover,
@@ -591,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();
     },
@@ -674,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();
           }
         }
@@ -740,7 +829,8 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       highlightedIndex,
       handleSelect,
       hasEntriesOnFocus,
-      query.length,
+      query,
+      minQueryLength,
       performBootstrap,
       externalOnKeyDown,
     ],

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}",

package/src/Typeahead/Typeahead.test.tsx

@@ -778,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

@@ -111,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 */
@@ -248,6 +255,7 @@ export function Typeahead<T extends SearchableItem>({
   placeholder,
   hasEntriesOnFocus,
   maxMenuItems,
+  minQueryLength,
   emptySearchResultsText,
   isDisabled = false,
   disabledMessage,
@@ -467,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');
+  });
+});

package/src/Typeahead/TypeaheadItem.tsx

@@ -132,7 +132,11 @@ export function TypeaheadItem<T extends SearchableItem>({
   icon,
   description,
   isDisabled = false,
+  group: _group,
   xstyle,
+  className,
+  style,
+  ...rest
 }: TypeaheadItemProps<T>) {
   // If item has a pre-rendered element, use it
   if (item.element) {
@@ -145,7 +149,10 @@ export function TypeaheadItem<T extends SearchableItem>({
       {...mergeProps(
         themeProps('typeahead-item'),
         stylex.props(styles.container, isDisabled && styles.disabled, xstyle),
-      )}>
+        className,
+        style,
+      )}
+      {...rest}>
       {icon}
       <div {...stylex.props(styles.content)}>
         <span {...stylex.props(styles.label)}>{item.label}</span>

package/src/hooks/useAnnounce.doc.mjs

@@ -0,0 +1,96 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useAnnounce',
+  displayName: 'useAnnounce',
+  keywords: [
+    'announce',
+    'live region',
+    'aria-live',
+    'screen reader',
+    'accessibility',
+    'a11y',
+    'status',
+    'alert',
+    'polite',
+    'assertive',
+    'visually hidden',
+    'wcag',
+  ],
+  params: [],
+  returns: [
+    {
+      name: 'announce',
+      type: '(message: string, politeness?: "polite" | "assertive") => void',
+      description:
+        'Speaks a message through the shared live region. Politeness defaults to "polite"; an empty message clears any lingering status instead of announcing.',
+    },
+  ],
+  usage: {
+    description:
+      'Imperatively announces a message to screen readers through a visually-hidden live region. Use it for state that is only conveyed visually; search result counts, "no results", loading and saved confirmations, validation errors (WCAG 4.1.3 Status Messages). The polite and assertive regions are created empty on first use and stay mounted, which is what makes announcements reliable: most screen readers ignore a live region that is inserted together with its content. Each message is cleared a couple of seconds after it is announced so stale status does not linger in the accessibility tree.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Reach for this instead of hand-rolling an aria-live div; a region rendered with its content usually does not announce at all.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep "polite" for status and result counts; reserve "assertive" for errors and time-sensitive alerts, since it interrupts whatever the screen reader is saying.',
+      },
+      {
+        guidance: true,
+        description:
+          'Announce the outcome, not the interaction; "12 results" rather than "search ran".',
+      },
+      {
+        guidance: false,
+        description:
+          'Announce content that is already visible and correctly labeled in the DOM; that doubles up for screen reader users.',
+      },
+    ],
+  },
+  relatedComponents: ['VisuallyHidden', 'Toast'],
+  relatedHooks: ['useClipboard'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'accessibility',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Imperative screen-reader announcements via a visually-hidden live region. Polite + assertive regions created empty on first use + kept mounted, so announcements are reliable (most AT ignore a live region inserted together w/ its content). Messages auto-clear after ~2s.',
+  returnDescriptions: {
+    announce:
+      'speaks message through shared live region. politeness defaults "polite"; empty message clears lingering status.',
+  },
+  usage: {
+    description:
+      'Announces visual-only state to screen readers: result counts, "no results", loading / saved confirmations, validation errors (WCAG 4.1.3). Regions mounted empty up front, so updates announce; text auto-clears so stale status does not linger in a11y tree.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use instead of hand-rolled aria-live div; region rendered w/ its content usually does not announce.',
+      },
+      {
+        guidance: true,
+        description:
+          '"polite" for status / counts; "assertive" only for errors + time-sensitive alerts (it interrupts).',
+      },
+      {
+        guidance: true,
+        description:
+          'Announce outcome, not interaction; "12 results", not "search ran".',
+      },
+      {
+        guidance: false,
+        description:
+          'Announce content already visible + labeled in DOM; doubles up for AT users.',
+      },
+    ],
+  },
+};

package/src/hooks/useDevWarning.doc.mjs

@@ -0,0 +1,96 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useDevWarning',
+  displayName: 'useDevWarning',
+  keywords: [
+    'warning',
+    'dev',
+    'development',
+    'console',
+    'guardrail',
+    'misuse',
+    'invariant',
+    'debug',
+    'devWarn',
+  ],
+  params: [
+    {
+      name: 'component',
+      type: 'string',
+      description: 'Component or hook name, used as the message prefix.',
+      required: true,
+    },
+    {
+      name: 'message',
+      type: 'string',
+      description: 'What went wrong and how to fix it.',
+      required: true,
+    },
+    {
+      name: 'condition',
+      type: 'boolean',
+      description: 'Whether to warn.',
+      default: 'true',
+    },
+  ],
+  returns: [],
+  usage: {
+    description:
+      'Fires a dev-only "Component: message" console warning once per mount while the condition holds. It is the render-safe way for a component to flag misuse: warning straight from the render body repeats on every render, and gating it with state adds a re-render, so this uses a ref and an effect instead. For a warning outside a component, use the imperative devWarn utility.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Say what is wrong and what the builder should do instead; the message is the whole value of the warning.',
+      },
+      {
+        guidance: true,
+        description:
+          'Warn about combinations the types cannot express, such as two mutually exclusive props being set together.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use it for anything a user could see or for runtime error handling; it is stripped from production builds.',
+      },
+    ],
+  },
+  relatedComponents: [],
+  relatedHooks: [],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'utility',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Dev-only "Component: message" console warning, once per mount while condition holds. Ref + effect, so it never repeats per render nor causes a re-render. Outside a component, use the imperative devWarn utility.',
+  paramDescriptions: {
+    component: 'component / hook name, used as message prefix.',
+    message: 'what went wrong + how to fix it.',
+    condition: 'whether to warn.',
+  },
+  usage: {
+    description:
+      'Render-safe guardrail warning from inside a component. Stripped from production builds.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Say what is wrong + what to do instead; the message is the value.',
+      },
+      {
+        guidance: true,
+        description:
+          'Warn about combinations types cannot express (mutually exclusive props set together).',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for user-visible problems / runtime error handling; it is dev-only.',
+      },
+    ],
+  },
+};

package/src/hooks/useHotkeys.test.ts

@@ -67,24 +67,6 @@ describe('useHotkeys', () => {
     expect(onPress).toHaveBeenCalledTimes(1);
   });
 
-  it('reads a blank userAgentData.platform as unknown, not as non-Apple', () => {
-    // Builds that rewrite their client-hints identity expose the key with an
-    // empty value; navigator.platform is the only surface left that answers.
-    vi.stubGlobal('navigator', {
-      userAgentData: {platform: ''},
-      platform: 'MacIntel',
-    });
-    const onPress = vi.fn();
-    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
-
-    press('k', {ctrlKey: true});
-    expect(onPress).not.toHaveBeenCalled();
-
-    const event = press('k', {metaKey: true});
-    expect(onPress).toHaveBeenCalledTimes(1);
-    expect(onPress).toHaveBeenCalledWith(event);
-  });
-
   it('does not fire a bare key when modifiers are held', () => {
     stubApplePlatform();
     const onPress = vi.fn();