@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

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,15 +19,17 @@
  * - /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";
+import { useCommittedChoices } from "./committedChoicesKey.js";
 import { usePopover } from "../Popover/usePopover.js";
 import { useAnnounce } from "../hooks/useAnnounce.js";
 import { useAnnounceRenderedText } from "../hooks/useAnnounceRenderedText.js";
 import { useHighlightedOptionScroll } from "../hooks/useHighlightedOptionScroll.js";
 import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
+import { isFocusInsideOwnedLayer, isPressInsideOwnedLayer, useOutsidePress } from "../Layer/outsidePress.js";
 import { isImeKeyEvent } from "../utils/ime.js";
 import { TypeaheadItem } from "./TypeaheadItem.js";
 import { Icon } from "../Icon/index.js";
@@ -34,16 +39,22 @@ import { borderVars, colorVars, spacingVars, radiusVars, typographyVars, fontWei
 import { characterCount, composeEventHandlers, getKey, groupItems, mergeProps } from "../utils/index.js";
 import { warnOnce } from "../utils/devWarning.js";
 import { themeProps } from "../utils/themeProps.js";
-import { useTranslator } from "../i18n/index.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { useBusyAnnouncement } from "../hooks/useBusyAnnouncement.js";
 import "../Layer/layerViewportInset.stylex.js";
 import { layerViewportInset } from "../Layer/layerViewportInset.stylex.js";
 import { clampInlineSize } from "../Layer/clampInlineSize.js";
+import { registerEnglishFallback, useComponentTranslator } from "../i18n/useComponentTranslator.js";
+import english from "../i18n/generated-english/Typeahead/BaseTypeahead.generated.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+registerEnglishFallback(english);
 // =============================================================================
 // Types
 // =============================================================================
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const _temp = {
+  kskxy: "x1jols5v",
+  "$$css": true
+};
 // =============================================================================
 // Styles
 // =============================================================================
@@ -69,6 +80,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 +159,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
@@ -212,7 +257,7 @@ export const BaseTypeahead = function BaseTypeahead({
   ref,
   ...rest
 }) {
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const placeholder = placeholderFromProps ?? t('@astryx.typeahead.searchPlaceholder');
   const emptySearchText = emptySearchTextFromProps ?? t('@astryx.typeahead.emptySearchResults');
   // The empty-state row carries the message visually, and the live region has
@@ -249,6 +294,76 @@ 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]);
+  // Committed values (Tokenizer's tokens) leave the shown rows in the same
+  // render that commits them, before any reload answers, so a list never
+  // offers a token (component:Tokenizer FR13). The highlight stays on its item
+  // when that item remains. The previous key is remembered in state, like
+  // `sourceOfState` below.
+  const committedChoices = useCommittedChoices();
+  const committedChoicesKey = committedChoices?.key;
+  const isAtCommitLimit = committedChoices?.isAtLimit === true;
+  const [committedKeyOfState, setCommittedKeyOfState] = useState(committedChoicesKey);
+  if (committedKeyOfState !== committedChoicesKey) {
+    setCommittedKeyOfState(committedChoicesKey);
+    const committedIds = committedChoices?.ids;
+    const kept = committedIds == null ? results : results.filter(item => !committedIds.has(item.id));
+    if (kept.length !== results.length) {
+      const highlightedId = displayedResults[highlightedIndex]?.id;
+      const keptOrder = displayOrder(kept, queryEntryCount);
+      const keptIndex = highlightedId == null ? -1 : keptOrder.findIndex(item => item.id === highlightedId);
+      setResults(kept);
+      setHighlightedIndex(keptIndex >= 0 ? keptIndex : keptOrder.length > 0 ? 0 : -1);
+    }
+  }
+  // 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
@@ -299,10 +414,9 @@ export const BaseTypeahead = function BaseTypeahead({
     onLoadingChangeRef.current?.(next);
   }, []);
 
-  // Track active pointer to defer popover.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).
+  // Track active pointer to defer popover.show() past click events, so a
+  // list that opens during a press starts its outside-press watch after that
+  // press ends and never judges it.
   const pointerActiveRef = useRef(false);
 
   // Whether the input was ALREADY the active element the moment the current
@@ -359,6 +473,17 @@ export const BaseTypeahead = function BaseTypeahead({
     }
     loadingRef.current = false;
   }
+  // A field that becomes disabled stops showing a search as busy in the same
+  // render, and the dropped query shows no outcome, so no empty state; the
+  // layout effect below drops the work itself.
+  const [disabledOfState, setDisabledOfState] = useState(isDisabled);
+  if (disabledOfState !== isDisabled) {
+    setDisabledOfState(isDisabled);
+    if (isDisabled && isLoading) {
+      setIsLoading(false);
+      setHasSearched(false);
+    }
+  }
 
   // When the search source is replaced, any in-flight load from the previous
   // source is abandoned (generation bumped above). Notify the wrapper's busy lane
@@ -374,19 +499,50 @@ export const BaseTypeahead = function BaseTypeahead({
     }
   }, [searchSource]);
 
-  // Layer for dropdown
+  // True from the moment the list is asked to open until it closes, including
+  // a show deferred past the active click, so committed values that change in
+  // the same event that opened the list still reload it.
+  const isShowingRef = useRef(false);
+
+  // Layer for dropdown. The list is a manual popover (see usePopover below):
+  // while it is open, a press on the combobox itself (its input or its
+  // buttons) or in the list is inside, and a press anywhere else closes it
+  // (component:BaseTypeahead FR12). The watch starts when the list shows and
+  // stops when it hides or the field unmounts (useOutsidePress owns that).
+  // An outside press hides the
+  // popover element directly, which useLayer reconciles like the browser's
+  // own light dismiss.
+  const outsidePress = useOutsidePress();
   const handleLayerShow = useCallback(() => {
+    isShowingRef.current = true;
     onOpenChange?.(true);
-  }, [onOpenChange]);
+    const anchorEl = anchorRef?.current ?? fallbackAnchorRef.current;
+    if (anchorEl == null) {
+      outsidePress.stop();
+      return;
+    }
+    // The list's own element sits inside the popover element.
+    const findLayer = () => dropdownRef.current?.closest('[popover]') ?? null;
+    outsidePress.start(anchorEl, path => isPressInsideOwnedLayer(path, anchorRef?.current ?? fallbackAnchorRef.current ?? anchorEl, findLayer()?.id ?? ''), () => findLayer()?.hidePopover());
+  }, [onOpenChange, anchorRef, outsidePress]);
   const handleLayerHide = useCallback(() => {
+    isShowingRef.current = false;
+    outsidePress.stop();
     onOpenChange?.(false);
     setHighlightedIndex(-1);
+    closedGenRef.current = searchGenRef.current;
+    setHeldHeight(null);
     searchSource.cancel?.();
-  }, [onOpenChange, searchSource]);
+  }, [onOpenChange, searchSource, outsidePress]);
   const popover = usePopover({
     onShow: handleLayerShow,
     onHide: handleLayerHide,
-    hasLightDismiss: true,
+    // A manual popover: the browser's light dismiss counts a press in the
+    // input as outside (a text input cannot be an invoker), so it would close
+    // the list on every press in the field. handleLayerShow watches for a
+    // press outside instead (architecture:layer-runtime); Escape stays on the
+    // shared layer stack.
+    hasLightDismiss: false,
     hasCloseButton: false,
     hasAutoFocus: false,
     // The popup's own role="listbox" is the exposed semantics; the input keeps
@@ -394,19 +550,36 @@ export const BaseTypeahead = function BaseTypeahead({
     role: 'none'
   });
 
-  // 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.
+  // Show the layer, deferring past the active click if a pointer is down
+  // (see pointerActiveRef).
   // 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;
+    if (!isDisabled) {
+      return;
+    }
+    // Search work scheduled or in flight when the field became disabled is
+    // dropped: a later answer lists, announces and spins nothing
+    // (spec:AST-085 FR2). Bumping the generation fails its checks.
+    searchGenRef.current++;
+    if (searchTimeoutRef.current) {
+      clearTimeout(searchTimeoutRef.current);
+      searchTimeoutRef.current = null;
+    }
+    prevSearchSourceRef.current.cancel?.();
+    // The busy state itself cleared in the render that disabled the field.
+    if (loadingRef.current) {
+      loadingRef.current = false;
+      onLoadingChangeRef.current?.(false);
+    }
   }, [isDisabled]);
   const showLayer = useCallback(() => {
     if (isDisabledRef.current) {
       return;
     }
+    isShowingRef.current = true;
     if (pointerActiveRef.current) {
       document.addEventListener('click', () => requestAnimationFrame(() => {
         if (!isDisabledRef.current) {
@@ -431,7 +604,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
@@ -441,46 +619,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;
@@ -491,12 +756,19 @@ 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();
+    } else if (committedChoices != null) {
+      // A Tokenizer list left with no eligible choice (its focus entries
+      // all committed, or the request failed) closes rather than staying
+      // open and empty (component:Tokenizer FR15). A plain Typeahead
+      // provides no committed choices and keeps its current behavior.
+      popover.hide();
     }
-  }, [highlightedIndex, maxMenuItems, results.length, showLayer]);
+  }, [highlightedIndex, maxMenuItems, results.length, showLayer, replaceResults, popover, committedChoices]);
 
   // Perform bootstrap
   const performBootstrap = useCallback(async () => {
@@ -505,8 +777,9 @@ export const BaseTypeahead = function BaseTypeahead({
     try {
       bootstrapResult = searchSource.bootstrap();
     } catch {
+      // A failed request offers nothing: an open list closes (FR15).
+      applyBootstrapResults([], gen);
       if (searchGenRef.current === gen) {
-        setResults([]);
         setLoading(false);
       }
       return;
@@ -520,9 +793,7 @@ export const BaseTypeahead = function BaseTypeahead({
     try {
       applyBootstrapResults(await bootstrapResult, gen);
     } catch {
-      if (searchGenRef.current === gen) {
-        setResults([]);
-      }
+      applyBootstrapResults([], gen);
     } finally {
       if (searchGenRef.current === gen) {
         setLoading(false);
@@ -530,6 +801,73 @@ export const BaseTypeahead = function BaseTypeahead({
     }
   }, [searchSource, applyBootstrapResults, setLoading]);
 
+  // A list shown before the caller's committed values changed is no longer
+  // current (component:Tokenizer FR13, spec:AST-092 FR4). While the list is
+  // open, it reloads the same query, its typed text or the focus list, from
+  // the source those values now filter. A closed list stays closed; opening it
+  // loads that source.
+  // Decided from the state at the moment the committed values change, with
+  // no remembered outcome (the state table in the pull request):
+  // - at the limit: close, whatever the query (FR15);
+  // - a closed list with no search waiting: stays closed, and opening it
+  //   loads the current source;
+  // - typed text: search it again, also replacing a search still waiting
+  //   for its debounce; an empty answer shows the empty-search message;
+  // - a focus list the commit emptied (no row left, no load waiting): close
+  //   (FR15); with rows left, or a load waiting: load the focus list again;
+  //   an empty or failed answer closes (FR15);
+  // - a focus list with focus entries off: close.
+  const reloadForCommittedChoices = useCallback(() => {
+    // A search waiting for its debounce would use the source from before the
+    // commit, so the reload replaces it.
+    const hadPendingSearch = searchTimeoutRef.current != null;
+    if (searchTimeoutRef.current != null) {
+      clearTimeout(searchTimeoutRef.current);
+      searchTimeoutRef.current = null;
+    }
+    if (isDisabled || !isMountedRef.current) {
+      return;
+    }
+    if (isAtCommitLimit) {
+      popover.hide();
+      return;
+    }
+    if (!isShowingRef.current && !hadPendingSearch) {
+      return;
+    }
+    if (query.length > 0) {
+      if (!isBelowMinQueryLength(query, minQueryLength)) {
+        void performSearch(query);
+      }
+      return;
+    }
+    if (!hasEntriesOnFocus || results.length === 0 && !hadPendingSearch) {
+      popover.hide();
+      return;
+    }
+    void performBootstrap();
+  }, [isDisabled, isAtCommitLimit, query, minQueryLength, hasEntriesOnFocus, results.length, performSearch, performBootstrap, popover]);
+  // The latest reload, read when the key changes, as an effect event.
+  const reloadForCommittedChoicesRef = useRef(reloadForCommittedChoices);
+  useIsomorphicLayoutEffect(() => {
+    reloadForCommittedChoicesRef.current = reloadForCommittedChoices;
+  });
+  const reloadedKeyRef = useRef(committedChoicesKey);
+  useIsomorphicLayoutEffect(() => {
+    if (reloadedKeyRef.current === committedChoicesKey) {
+      return;
+    }
+    reloadedKeyRef.current = committedChoicesKey;
+    // The reload is a source request, started after the commit like one a
+    // keystroke starts. Queued from a layout effect, it runs before paint, so
+    // a list the commit emptied closes without showing empty.
+    queueMicrotask(() => {
+      if (reloadedKeyRef.current === committedChoicesKey) {
+        reloadForCommittedChoicesRef.current();
+      }
+    });
+  }, [committedChoicesKey]);
+
   // Handle query change
   const handleQueryChange = useCallback(newQuery => {
     setQuery(newQuery);
@@ -549,7 +887,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
@@ -576,9 +915,12 @@ export const BaseTypeahead = function BaseTypeahead({
     if (debounceMs <= 0) {
       triggerSearch();
     } else {
-      searchTimeoutRef.current = setTimeout(triggerSearch, debounceMs);
+      searchTimeoutRef.current = setTimeout(() => {
+        searchTimeoutRef.current = null;
+        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 => {
@@ -601,7 +943,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
@@ -609,7 +952,7 @@ export const BaseTypeahead = function BaseTypeahead({
     setLoading(false);
     popover.hide();
     inputRef.current?.focus();
-  }, [isDisabled, 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
@@ -655,23 +998,19 @@ export const BaseTypeahead = function BaseTypeahead({
 
   // Handle blur — close the dropdown when focus leaves the input for an
   // element that is neither inside the field wrapper (anchor) nor inside the
-  // dropdown popover. The native popover="auto" light-dismiss only fires on
-  // outside pointer clicks and Escape; it does not close when focus moves away
-  // via the keyboard (Tab) or programmatically, which would otherwise leave an
-  // orphaned open menu. Clicking a result moves focus onto the option (it is
+  // dropdown popover. The outside-press watch only answers pointer presses
+  // and Escape stays on the layer stack; neither closes the list when focus
+  // moves away via the keyboard (Tab) or programmatically, which would
+  // otherwise leave an orphaned open menu. Clicking a result moves focus onto the option (it is
   // tabIndex={-1}, so it lives inside the popover) and selection re-focuses the
   // input, so this only closes on a genuine focus-out of the whole field.
   const handleBlur = useCallback(e => {
     if (!popover.isOpen) {
       return;
     }
-    const next = e.relatedTarget;
-    if (next) {
-      const anchorEl = anchorRef?.current ?? fallbackAnchorRef.current;
-      const popoverEl = document.getElementById(popover.id);
-      if (anchorEl?.contains(next) || popoverEl?.contains(next)) {
-        return;
-      }
+    const anchorEl = anchorRef?.current ?? fallbackAnchorRef.current;
+    if (isFocusInsideOwnedLayer(e.relatedTarget, anchorEl, popover.id)) {
+      return;
     }
     popover.hide();
   }, [popover, anchorRef]);
@@ -751,7 +1090,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':
@@ -783,25 +1122,47 @@ export const BaseTypeahead = function BaseTypeahead({
         }
         break;
     }
-  }, [isDisabled, popover, results, highlightedIndex, handleSelect, hasEntriesOnFocus, query, minQueryLength, performBootstrap, performSearch, 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);
       }
@@ -867,12 +1228,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",
@@ -916,7 +1276,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);
@@ -935,6 +1296,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',