@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/dist/Typeahead/BaseTypeahead.js

@@ -5,7 +5,10 @@
 /**
  * @file BaseTypeahead.tsx
  * @input Uses React, StyleX, usePopover, TypeaheadItem
- * @output Exports BaseTypeahead; empty feedback belongs to the current settled query
+ * @output Exports BaseTypeahead; empty feedback belongs to the current settled query;
+ *   focus bootstraps a replaced search source; a source shows partial lists
+ *   for a query through context.update, and later lists only append
+ *   (spec:AST-092)
  * @position Core implementation; used by Typeahead and Tokenizer
  *
  * Pure combobox engine: input, search, keyboard navigation, dropdown.
@@ -16,7 +19,7 @@
  * - /packages/core/src/Typeahead/index.ts
  * - /packages/cli/assets/templates/blocks/components/Typeahead/ (showcase blocks)
  */
-import React, { useCallback, useEffect, useId, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { useBusyIndicatorLane } from "./busyIndicatorLane.js";
 import { useTrailingKeyDown } from "./trailingKeyDown.js";
@@ -44,6 +47,10 @@ import { clampInlineSize } from "../Layer/clampInlineSize.js";
 // Types
 // =============================================================================
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const _temp = {
+  kskxy: "x1jols5v",
+  "$$css": true
+};
 // =============================================================================
 // Styles
 // =============================================================================
@@ -69,6 +76,16 @@ const styles = {
     kkrTdU: "xt0e3qv",
     $$css: true
   },
+  dropdown: {
+    kB7OPa: "x9f619",
+    kskxy: "xuyqlj2",
+    kORKVm: "x1odjw0f",
+    kmVPX3: "x9epnlk",
+    $$css: true
+  },
+  dropdownHeld: height => [_temp, {
+    "--x-maxHeight": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(`${height}px`)
+  }],
   popover: {
     kB7OPa: "x9f619",
     k7Eaqz: "xviorkc",
@@ -138,6 +155,30 @@ const itemSizeStyles = {
 // Helpers
 // =============================================================================
 
+/** The result popup's maximum height in CSS pixels (`styles.dropdown`). */
+const DROPDOWN_MAX_HEIGHT = 300;
+
+/**
+ * Rows in the order the popup displays them: ungrouped source rows, then each
+ * group, then the trailing entries derived from the typed text (Tokenizer's
+ * create row), which always follow the rows (spec:AST-092 FR1).
+ */
+function displayOrder(list, queryEntryCount = 0) {
+  const end = list.length - queryEntryCount;
+  return [...groupItems(list.slice(0, end), {
+    ungroupedFirst: true
+  }).flatMap(group => group.items), ...list.slice(end)];
+}
+
+/**
+ * Whether `next` starts with `shown`, item by item and in order, by `id`: the
+ * append-only rule a later list for the same query follows, applied to
+ * displayed order (spec:AST-092 FR2).
+ */
+function startsWithRows(next, shown) {
+  return next.length >= shown.length && shown.every((item, index) => next[index].id === item.id);
+}
+
 /**
  * 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
@@ -249,6 +290,55 @@ export const BaseTypeahead = function BaseTypeahead({
     }
   }, [results]);
   const [highlightedIndex, setHighlightedIndex] = useState(-1);
+  // Bumped whenever the rows are replaced rather than appended to, so the
+  // highlighted-row scroll runs for a new list but not when a later list for
+  // the same query appends rows below (spec:AST-092 FR6).
+  const [listKey, setListKey] = useState(0);
+  // How many trailing rows are entries derived from the typed text rather
+  // than source results; they display after every group.
+  const [queryEntryCount, setQueryEntryCount] = useState(0);
+  const replaceResults = useCallback((next, entryCount = 0) => {
+    setResults(next);
+    setQueryEntryCount(entryCount);
+    setListKey(key => key + 1);
+  }, []);
+  // Highlight indexes count rows in displayed order (ungrouped first, then
+  // groups), which is how the popup renders them.
+  const displayedResults = useMemo(() => displayOrder(results, queryEntryCount), [results, queryEntryCount]);
+  // The popup's listbox, measured when a later list arrives so the appended
+  // rows scroll instead of moving the shown rows or flipping the popup to
+  // the other side of the field (spec:AST-092 FR6).
+  const dropdownRef = useRef(null);
+  const [heldHeight, setHeldHeight] = useState(null);
+  // The search generation the popup's close cancelled, so that search's
+  // rejection settles silently (spec:AST-092 FR9).
+  const closedGenRef = useRef(-1);
+  const isMountedRef = useRef(false);
+  const holdPopupInPlace = useCallback(() => {
+    const dropdown = dropdownRef.current;
+    const anchor = anchorRef?.current ?? fallbackAnchorRef.current;
+    if (dropdown == null || anchor == null) {
+      return;
+    }
+    const box = dropdown.getBoundingClientRect();
+    if (box.height <= 0) {
+      return;
+    }
+    if (box.bottom <= anchor.getBoundingClientRect().top + 1) {
+      // Above the field the popup grows upward, so any growth moves the
+      // shown rows: keep the height it has.
+      setHeldHeight(current => current ?? box.height);
+      return;
+    }
+    // Below the field, grow only within the room below, so the layer runtime
+    // never flips the popup above the field.
+    const layer = dropdown.closest('[popover]') ?? dropdown;
+    const layerBox = layer.getBoundingClientRect();
+    const gutter = parseFloat(getComputedStyle(layer).marginBlockEnd) || 0;
+    const viewportHeight = window.visualViewport?.height ?? window.innerHeight;
+    const room = viewportHeight - box.top - Math.max(0, layerBox.bottom - box.bottom) - gutter;
+    setHeldHeight(current => current ?? Math.min(DROPDOWN_MAX_HEIGHT, Math.max(box.height, room)));
+  }, [anchorRef]);
   const [isLoading, setIsLoading] = useState(false);
   const [hasSearched, setHasSearched] = useState(false);
   // `isLoading` starts with the request, after debouncing. Until then the
@@ -381,6 +471,8 @@ export const BaseTypeahead = function BaseTypeahead({
   const handleLayerHide = useCallback(() => {
     onOpenChange?.(false);
     setHighlightedIndex(-1);
+    closedGenRef.current = searchGenRef.current;
+    setHeldHeight(null);
     searchSource.cancel?.();
   }, [onOpenChange, searchSource]);
   const popover = usePopover({
@@ -397,9 +489,22 @@ export const BaseTypeahead = function BaseTypeahead({
   // 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.
+  // Read at show time, so a search or bootstrap that settles after the field
+  // became disabled does not open the list (spec:AST-085 FR2).
+  const isDisabledRef = useRef(isDisabled);
+  useIsomorphicLayoutEffect(() => {
+    isDisabledRef.current = isDisabled;
+  }, [isDisabled]);
   const showLayer = useCallback(() => {
+    if (isDisabledRef.current) {
+      return;
+    }
     if (pointerActiveRef.current) {
-      document.addEventListener('click', () => requestAnimationFrame(() => popover.show()), {
+      document.addEventListener('click', () => requestAnimationFrame(() => {
+        if (!isDisabledRef.current) {
+          popover.show();
+        }
+      }), {
         once: true
       });
     } else {
@@ -418,7 +523,12 @@ export const BaseTypeahead = function BaseTypeahead({
     };
   }, [popover, anchorRef]);
 
-  // Perform search
+  // Perform search. A source may show lists for the query before it settles
+  // through `context.update`, and the value it returns is the final list
+  // (spec:AST-092). The first list shown for a query may replace the rows;
+  // every later one keeps the shown rows first, so nothing moves under the
+  // pointer or the highlight. Merging is the source's work: a later list that
+  // breaks that rule is shown as given, with a development warning.
   const performSearch = useCallback(async searchQuery => {
     searchSource.cancel?.();
     // Claim a new generation so overlapping searches can't race: an
@@ -428,46 +538,133 @@ export const BaseTypeahead = function BaseTypeahead({
     setLastSearchedQuery(searchQuery);
     setLoading(true);
     setHasSearched(true);
+    let isSettled = false;
+    // The capped source rows last shown for this query, and the array handed
+    // to React for them. Null until the query's first non-empty list.
+    let shownRows = null;
+    let shownState = null;
+    let shownEntryCount = 0;
+    const showList = (list, isFinal) => {
+      const fetched = list.slice(0, maxMenuItems);
+      if (shownRows != null && !startsWithRows(displayOrder(fetched), displayOrder(shownRows))) {
+        warnOnce('base-typeahead:append-only', 'BaseTypeahead', 'A later list for the same query moved, removed, or inserted ' + 'above rows already shown. After the first list for a query, ' + 'a search source keeps the shown rows first and in order and ' + 'adds new rows after them (spec:AST-092 FR2).');
+      }
+      // Entries derived from the typed text (Tokenizer's create row) wait
+      // for the query to settle: before then a pending server result may
+      // still show the value they would offer to create.
+      const entries = isFinal ? __queryEntries?.(searchQuery, fetched) ?? [] : [];
+      const shown = [...fetched, ...entries];
+      resultsGenRef.current = gen;
+      const firstRow = shown.length > 0 ? 0 : -1;
+      const previous = shownState;
+      const previousEntryCount = shownEntryCount;
+      if (previous == null) {
+        setHeldHeight(null);
+        replaceResults(shown, entries.length);
+        setHighlightedIndex(firstRow);
+      } else {
+        holdPopupInPlace();
+        const previousOrder = displayOrder(previous, previousEntryCount);
+        const nextOrder = displayOrder(shown, entries.length);
+        if (startsWithRows(nextOrder, previousOrder)) {
+          setResults(shown);
+          setQueryEntryCount(entries.length);
+        } else {
+          replaceResults(shown, entries.length);
+        }
+        // Within one query only this function sets the rows, so the index
+        // the updater receives points into `previous`: the highlighted item
+        // keeps its highlight wherever it now sits (spec:AST-092 FR6).
+        setHighlightedIndex(index => {
+          const id = previousOrder[index]?.id;
+          const kept = id == null ? -1 : nextOrder.findIndex(item => item.id === id);
+          return kept >= 0 ? kept : firstRow;
+        });
+      }
+      if (fetched.length > 0) {
+        shownRows = fetched;
+        shownState = shown;
+        shownEntryCount = entries.length;
+      }
+      return shown;
+    };
+    const announceCount = count => {
+      // Announce the outcome only for an active query (not the initial
+      // focus-open), so screen-reader users hear result counts / no-results.
+      // An empty result is announced from the rendered row instead, so the
+      // region speaks whatever the caller put there.
+      if (isMountedRef.current && searchQuery.length > 0 && count > 0) {
+        announce(t('@astryx.typeahead.resultCount', {
+          count
+        }));
+      }
+    };
+    const context = {
+      update(items) {
+        // An empty list leaves the shown rows in place; a list for a query
+        // that is no longer current, or after it settled, is dropped.
+        if (isSettled || searchGenRef.current !== gen || items.length === 0) {
+          return;
+        }
+        showList(items, false);
+        showLayer();
+      }
+    };
     try {
-      const searchResults = await searchSource.search(searchQuery);
+      const searchResults = await searchSource.search(searchQuery, context);
       if (searchGenRef.current !== gen) {
         return;
       }
-      resultsGenRef.current = gen;
-      const fetched = searchResults.slice(0, maxMenuItems);
-      const shown = [...fetched, ...(__queryEntries?.(searchQuery, fetched) ?? [])];
-      setResults(shown);
-      setHighlightedIndex(shown.length > 0 ? 0 : -1);
+      isSettled = true;
+      const shown = showList(searchResults, true);
       if (searchResults.length > 0 || searchQuery.length > 0) {
         showLayer();
       }
-      // Announce the outcome only for an active query (not the initial
-      // focus-open), so screen-reader users hear result counts / no-results.
       if (searchQuery.length > 0) {
         // This query's outcome is announced now (a count) or from the
         // rendered row (an empty result); a busy start not yet announced
         // would follow it, so it is dropped (spec:AST-086 FR8).
         settleBusyAnnouncement();
       }
-      if (searchQuery.length > 0 && shown.length > 0) {
-        announce(t('@astryx.typeahead.resultCount', {
-          count: shown.length
-        }));
-      }
-      // An empty result is announced from the rendered row instead, so the
-      // region speaks whatever the caller put there.
+      announceCount(shown.length);
     } catch {
       if (searchGenRef.current !== gen) {
         return;
       }
-      setResults([]);
-      setHighlightedIndex(-1);
+      isSettled = true;
+      if (closedGenRef.current === gen) {
+        // The popup closed and cancelled this search, so its rejection is
+        // not a failed answer: announce nothing, and keep only this query's
+        // own rows (spec:AST-092 FR9).
+        if (shownRows != null) {
+          showList(shownRows, true);
+        } else {
+          replaceResults([]);
+          setHighlightedIndex(-1);
+          setHasSearched(false);
+        }
+      } else {
+        // A failure settles this query: its outcome is announced now (the
+        // kept rows' count) or from the rendered empty row, so a busy start
+        // not yet announced is dropped, as on success (spec:AST-086 FR8).
+        if (searchQuery.length > 0) {
+          settleBusyAnnouncement();
+        }
+        if (shownRows != null) {
+          // A failed server answer keeps the last non-empty list the source
+          // showed for this query, which settles it.
+          announceCount(showList(shownRows, true).length);
+        } else {
+          replaceResults([]);
+          setHighlightedIndex(-1);
+        }
+      }
     } finally {
       if (searchGenRef.current === gen) {
         setLoading(false);
       }
     }
-  }, [searchSource, maxMenuItems, showLayer, announce, __queryEntries, setLoading, settleBusyAnnouncement, t]);
+  }, [searchSource, maxMenuItems, showLayer, announce, __queryEntries, setLoading, settleBusyAnnouncement, t, holdPopupInPlace, replaceResults]);
   const applyBootstrapResults = useCallback((bootstrapResults, gen) => {
     if (searchGenRef.current !== gen) {
       return;
@@ -478,12 +675,13 @@ export const BaseTypeahead = function BaseTypeahead({
     if (results.length === 0 && shown.length === 0 && highlightedIndex === -1) {
       return;
     }
-    setResults(shown);
+    setHeldHeight(null);
+    replaceResults(shown);
     setHighlightedIndex(nextHighlightedIndex);
     if (bootstrapResults.length > 0) {
       showLayer();
     }
-  }, [highlightedIndex, maxMenuItems, results.length, showLayer]);
+  }, [highlightedIndex, maxMenuItems, results.length, showLayer, replaceResults]);
 
   // Perform bootstrap
   const performBootstrap = useCallback(async () => {
@@ -493,7 +691,7 @@ export const BaseTypeahead = function BaseTypeahead({
       bootstrapResult = searchSource.bootstrap();
     } catch {
       if (searchGenRef.current === gen) {
-        setResults([]);
+        replaceResults([]);
         setLoading(false);
       }
       return;
@@ -508,14 +706,14 @@ export const BaseTypeahead = function BaseTypeahead({
       applyBootstrapResults(await bootstrapResult, gen);
     } catch {
       if (searchGenRef.current === gen) {
-        setResults([]);
+        replaceResults([]);
       }
     } finally {
       if (searchGenRef.current === gen) {
         setLoading(false);
       }
     }
-  }, [searchSource, applyBootstrapResults, setLoading]);
+  }, [searchSource, applyBootstrapResults, setLoading, replaceResults]);
 
   // Handle query change
   const handleQueryChange = useCallback(newQuery => {
@@ -536,7 +734,8 @@ export const BaseTypeahead = function BaseTypeahead({
       // 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);
+      replaceResults(derived, derived.length);
+      setHeldHeight(null);
       setHighlightedIndex(derived.length > 0 ? 0 : -1);
       setHasSearched(false);
       // Bumping the generation abandons any in-flight search, which means
@@ -565,7 +764,7 @@ export const BaseTypeahead = function BaseTypeahead({
     } else {
       searchTimeoutRef.current = setTimeout(triggerSearch, debounceMs);
     }
-  }, [onChangeQuery, hasEntriesOnFocus, minQueryLength, __queryEntries, showLayer, performSearch, performBootstrap, popover, debounceMs, searchSource, announce, setLoading]);
+  }, [replaceResults, onChangeQuery, hasEntriesOnFocus, minQueryLength, __queryEntries, showLayer, performSearch, performBootstrap, popover, debounceMs, searchSource, announce, setLoading]);
 
   // Handle input change
   const handleInputChange = useCallback(e => {
@@ -574,6 +773,11 @@ export const BaseTypeahead = function BaseTypeahead({
 
   // Handle item selection
   const handleSelect = useCallback(item => {
+    // A disabled field changes nothing, also from a list that was open
+    // before it became disabled (spec:AST-085 FR2).
+    if (isDisabled) {
+      return;
+    }
     // Bump generation to invalidate any in-flight async searches
     searchGenRef.current++;
     if (searchTimeoutRef.current) {
@@ -583,7 +787,8 @@ export const BaseTypeahead = function BaseTypeahead({
     searchSource.cancel?.();
     onChange(item);
     setQuery('');
-    setResults([]);
+    replaceResults([]);
+    setHeldHeight(null);
     setHasSearched(false);
     // Same reason as in handleQueryChange: the invalidated search will not
     // clear this itself. Selecting a stale result while the next search is
@@ -591,7 +796,7 @@ export const BaseTypeahead = function BaseTypeahead({
     setLoading(false);
     popover.hide();
     inputRef.current?.focus();
-  }, [onChange, popover, searchSource, setLoading]);
+  }, [isDisabled, onChange, popover, searchSource, setLoading, replaceResults]);
 
   // Shared by handleFocus and handleClick: bootstrap entries if none are
   // loaded yet, or re-show cached results that haven't been invalidated by
@@ -625,7 +830,7 @@ export const BaseTypeahead = function BaseTypeahead({
   // dropdown never reopens until the user clicks away and back (#6845). See
   // wasAlreadyFocusedRef above for how the two cases are told apart.
   const handleClick = useCallback(() => {
-    if (!wasAlreadyFocusedRef.current || popover.isOpen) {
+    if (isDisabled || !wasAlreadyFocusedRef.current || popover.isOpen) {
       return;
     }
     if (hasEntriesOnFocus && query.length === 0 && resultsGenRef.current !== searchGenRef.current) {
@@ -633,7 +838,7 @@ export const BaseTypeahead = function BaseTypeahead({
       return;
     }
     openIfEligible();
-  }, [popover.isOpen, hasEntriesOnFocus, query.length, performBootstrap, openIfEligible]);
+  }, [isDisabled, popover.isOpen, hasEntriesOnFocus, query.length, performBootstrap, openIfEligible]);
 
   // Handle blur — close the dropdown when focus leaves the input for an
   // element that is neither inside the field wrapper (anchor) nor inside the
@@ -676,17 +881,42 @@ export const BaseTypeahead = function BaseTypeahead({
     if (isImeKeyEvent(e.nativeEvent)) {
       return;
     }
+
+    // A focusable-disabled field opens no list and picks nothing; it only
+    // lets a list that was open before it became disabled close
+    // (spec:AST-085 FR2).
+    if (isDisabled) {
+      // Enter on a list that is still open picks nothing, and must not
+      // submit an enclosing form either, as it would not while enabled.
+      if (popover.isOpen && e.key === 'Enter') {
+        e.preventDefault();
+      }
+      if (popover.isOpen && (e.key === 'Escape' || e.key === 'Tab')) {
+        if (e.key === 'Escape') {
+          e.preventDefault();
+        }
+        popover.hide();
+      }
+      return;
+    }
     if (!popover.isOpen) {
       if (e.key === 'ArrowDown' && (hasEntriesOnFocus || query.length > 0)) {
         e.preventDefault();
-        if (results.length > 0) {
+        // Results held from a replaced search source are not current
+        // (spec:AST-092 FR4): they count as none, so the new source loads.
+        const hasResultsFromCurrentSource = results.length > 0 && resultsGenRef.current >= sourceGenRef.current;
+        const isQueryBelowMinLength = isBelowMinQueryLength(query, minQueryLength);
+        if (hasResultsFromCurrentSource) {
           popover.show();
           setHighlightedIndex(0);
+        } else if (results.length > 0 && query.length > 0 && !isQueryBelowMinLength) {
+          // The typed query runs again against the new source.
+          void performSearch(query);
         } 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)) {
+        !isQueryBelowMinLength) {
           void performBootstrap();
         }
       }
@@ -708,7 +938,7 @@ export const BaseTypeahead = function BaseTypeahead({
       case 'Enter':
         e.preventDefault();
         if (highlightedIndex >= 0 && highlightedIndex < results.length) {
-          handleSelect(results[highlightedIndex]);
+          handleSelect(displayedResults[highlightedIndex]);
         }
         break;
       case 'Escape':
@@ -740,25 +970,47 @@ export const BaseTypeahead = function BaseTypeahead({
         }
         break;
     }
-  }, [popover, results, highlightedIndex, handleSelect, hasEntriesOnFocus, query, minQueryLength, performBootstrap, externalOnKeyDown]);
+  }, [isDisabled, popover, results, displayedResults, highlightedIndex, handleSelect, hasEntriesOnFocus, query, minQueryLength, performBootstrap, performSearch, externalOnKeyDown]);
 
-  // Generate item ID for accessibility
-  const getItemId = useCallback(index => `${listboxId}-option-${index}`, [listboxId]);
+  // Option ids follow the item, not the row, so the active descendant keeps
+  // naming the same option while rows are added after it and a screen reader
+  // does not re-read it (spec:AST-092 FR7). A repeated id in one list falls
+  // back to its row so DOM ids stay unique.
+  const optionIds = useMemo(() => {
+    const seen = new Set();
+    return displayedResults.map((item, index) => {
+      const byItem = `${listboxId}-option-${encodeURIComponent(item.id)}`;
+      const id = seen.has(byItem) ? `${byItem}-${index}` : byItem;
+      seen.add(byItem);
+      return id;
+    });
+  }, [displayedResults, listboxId]);
+  const getItemId = useCallback(index => optionIds[index] ?? `${listboxId}-option-${index}`, [optionIds, listboxId]);
 
   // Keep the highlighted option visible during keyboard navigation; hover
   // highlights never scroll (#6077). Both sides live in useHighlightedOptionScroll.
+  // The scroll follows the highlighted option's id and the list it belongs
+  // to, so rows a later list appends below do not scroll a list the person
+  // has scrolled (spec:AST-092 FR6, FR7).
+  const highlightedOptionId = optionIds[highlightedIndex];
+  const getHighlightedOptionId = useCallback(index => highlightedOptionId ?? `${listboxId}-option-${index}`, [highlightedOptionId, listboxId]);
   const highlightOnHover = useHighlightedOptionScroll({
     isOpen: popover.isOpen,
     highlightedIndex,
     setHighlightedIndex,
-    getOptionId: getItemId,
-    itemCount: results.length
+    getOptionId: getHighlightedOptionId,
+    itemCount: listKey
   });
   const selectedKey = value == null ? null : getKey(value.id, () => results.indexOf(value));
 
-  // Unmount: clear the pending debounce and cancel in-flight work.
+  // Unmount: clear the pending debounce and cancel in-flight work, and stop
+  // announcing for a field that is gone (spec:AST-092 FR4). A flag rather than
+  // a generation bump, so StrictMode's simulated unmount keeps a search or
+  // bootstrap started during mount.
   useEffect(() => {
+    isMountedRef.current = true;
     return () => {
+      isMountedRef.current = false;
       if (searchTimeoutRef.current) {
         clearTimeout(searchTimeoutRef.current);
       }
@@ -805,8 +1057,8 @@ export const BaseTypeahead = function BaseTypeahead({
       placeholder: placeholder
       // When a disabled-reason tooltip is shown the input keeps focusability
       // via aria-disabled + readOnly instead of the native disabled
-      // attribute. Query and text mutation are blocked, but an already-open
-      // highlighted option can still be selected with Enter after transition.
+      // attribute. Query and text mutation, opening and picking are blocked
+      // by the handlers above (spec:AST-085 FR2).
       ,
       disabled: isDisabled && !isFocusableDisabled,
       readOnly: isFocusableDisabled || undefined,
@@ -824,12 +1076,11 @@ export const BaseTypeahead = function BaseTypeahead({
         role: "img"
       })
     }), popover.render(/*#__PURE__*/_jsx("div", {
+      ref: dropdownRef,
       id: listboxId,
       role: "listbox",
       "aria-label": t('@astryx.typeahead.searchResults'),
-      ...mergeProps(themeProps('typeahead-dropdown'), {
-        className: "x9f619 xuyqlj2 x1odjw0f x9epnlk"
-      }),
+      ...mergeProps(themeProps('typeahead-dropdown'), stylex.props(styles.dropdown, heldHeight != null && styles.dropdownHeld(heldHeight))),
       children: results.length === 0 && hasSearched && !isSearchPending ? /*#__PURE__*/_jsx("div", {
         ref: emptyStateRef,
         role: "option",
@@ -873,7 +1124,8 @@ export const BaseTypeahead = function BaseTypeahead({
             })]
           }, itemKey);
         };
-        return groupItems(results, {
+        const sourceEnd = results.length - queryEntryCount;
+        const grouped = groupItems(results.slice(0, sourceEnd), {
           ungroupedFirst: true
         }).map(group => {
           const options = group.items.map(renderOption);
@@ -892,6 +1144,9 @@ export const BaseTypeahead = function BaseTypeahead({
             }), options]
           }, `group-${group.heading}`);
         });
+        // Entries derived from the typed text follow every group
+        // (spec:AST-092 FR1).
+        return [...grouped, ...results.slice(sourceEnd).map(renderOption)];
       })()
     }), {
       placement: 'below',

package/dist/Typeahead/Typeahead.d.ts

@@ -14,11 +14,12 @@
  * - /packages/cli/assets/templates/blocks/components/Typeahead/ (showcase blocks)
  */
 import React, { type ReactNode } from 'react';
-import { type InputStatus, type FieldStatusVariant } from '../Field/index.js';
+import { type InputStatus } from '../Field/index.js';
 import { type IconType } from '../Icon/index.js';
 import { type FieldInputBaseProps } from '../Field/fieldParts.js';
 import type { SizeValue } from '../utils/types.js';
 import type { SearchableItem, SearchSource } from './types.js';
+import type { FieldStatusPlacement } from '../Field/fieldStatusPlacement.js';
 export type { InputStatus as TypeaheadStatus, InputStatusType as TypeaheadStatusType, } from '../Field/index.js';
 export type TypeaheadSize = 'sm' | 'md' | 'lg';
 export interface TypeaheadProps<T extends SearchableItem> extends Omit<FieldInputBaseProps<HTMLInputElement>, 'onChange' | 'onKeyDown'> {
@@ -50,7 +51,7 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<FieldInpu
      * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
      * @default 'attached'
      */
-    statusVariant?: FieldStatusVariant;
+    statusVariant?: FieldStatusPlacement;
     /**
      * Icon to display at the start of the input.
      * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -142,7 +143,7 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<FieldInpu
     /** Callback when dropdown opens/closes. */
     onOpenChange?: (isOpen: boolean) => void;
 }
-export declare function Typeahead<T extends SearchableItem>({ ref, label, isLabelHidden, description, isRequired, isOptional, status, statusVariant, startIcon, labelTooltip, searchSource, value, onChange, renderItem, placeholder, hasEntriesOnFocus, maxMenuItems, minQueryLength, emptySearchText, isDisabled: isDisabledProp, disabledMessage, hasClear, hasAutoFocus, size: sizeProp, debounceMs, onChangeQuery, onOpenChange, onKeyDown, width, containerXstyle, containerClassName, containerStyle, controlXstyle, controlClassName, controlStyle, id: idProp, 'aria-describedby': ariaDescribedByProp, ...restProps }: TypeaheadProps<T>): React.JSX.Element;
+export declare function Typeahead<T extends SearchableItem>({ ref, label, isLabelHidden, description, isRequired, isOptional, status, statusVariant, startIcon, labelTooltip, searchSource, value, onChange, renderItem, placeholder, hasEntriesOnFocus, maxMenuItems, minQueryLength, emptySearchText, isDisabled: isDisabledProp, disabledMessage, hasClear, hasAutoFocus, size: sizeProp, debounceMs, onChangeQuery, onOpenChange, onKeyDown, width, containerXstyle, containerClassName, containerStyle, controlXstyle, controlClassName, controlStyle, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-labelledby': ariaLabelledByProp, ...restProps }: TypeaheadProps<T>): React.JSX.Element;
 export declare namespace Typeahead {
     var displayName: string;
 }

package/dist/Typeahead/Typeahead.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Typeahead.d.ts","sourceRoot":"","sources":["../../src/Typeahead/Typeahead.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"Typeahead.d.ts","sourceRoot":"","sources":["../../src/Typeahead/Typeahead.tsx"],"names":[],"mappings":"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"}