@astryxdesign/core 0.7.7 → 0.7.8-canary.30b1896

package/src/Tokenizer/Tokenizer.tsx

@@ -8,8 +8,8 @@
  *   useAdaptivePresentation, and TokenizerBottomSheet (lazy)
  * @output Exports Tokenizer multi-select typeahead component
  * @position Composed component; forwards DOM ref and exposes focus control via
- *   handleRef. The experimental `presentation` option swaps the inline
- *   combobox for a trigger that opens TokenizerBottomSheet.
+ *   handleRef. The `presentation` prop swaps the inline combobox for a
+ *   trigger that opens TokenizerBottomSheet.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Tokenizer/index.ts
@@ -51,9 +51,13 @@ import {useMergedRefs} from '../hooks/useMergedRefs';
 import {TokenizerClearAllMessageContext} from './TokenizerClearAllMessageContext';
 import {TokenizerItemRemovableContext} from './TokenizerItemRemovableContext';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
-import {useAdaptivePresentation} from '../hooks/useAdaptivePresentation';
+import {
+  type AdaptivePresentation,
+  useAdaptivePresentation,
+} from '../hooks/useAdaptivePresentation';
 import {useIsHydrating} from '../hooks/useIsHydrating';
 import {VisuallyHidden} from '../VisuallyHidden';
+import {useDevWarning} from '../hooks/useDevWarning';
 import {warnOnce} from '../utils/devWarning';
 import type {SizeValue} from '../utils/types';
 import {BaseTypeahead} from '../Typeahead/BaseTypeahead';
@@ -296,62 +300,74 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   onFocus?: (e: React.FocusEvent) => void;
   /** Fires when focus leaves the tokenizer entirely. */
   onBlur?: (e: React.FocusEvent) => void;
-  /** Ref forwarded to the combobox input. */
+  /**
+   * How the field presents its choices.
+   * - `'popover'`: the inline combobox with its anchored suggestion menu, on
+   *   every device.
+   * - `'bottom-sheet'`: a trigger showing the selected tokens that opens one
+   *   tall modal sheet: a search row on top, full-width checkbox rows that
+   *   keep their place while the sheet is open, a create row with
+   *   `hasCreate`, and a footer pinned in every state with a confirmed Clear
+   *   all and Save. The sheet edits a draft: `onChange` fires once, when Save
+   *   commits it, and a swipe, scrim or Escape close of a changed draft asks
+   *   before discarding. Suited to compact touch screens, where the inline
+   *   combobox competes with the software keyboard.
+   * - `'adaptive'`: the bottom sheet on compact coarse-pointer screens,
+   *   otherwise the popover — the same resolution Selector uses. The server
+   *   render and the hydrating render are the popover.
+   *
+   * In the sheet presentation the trigger is the control: `ref`, `id`,
+   * `aria-*`, and `data-*` reach it. `renderItem`, `renderToken`,
+   * `endContent`, `hasClear`, `hasEntriesOnFocus`, `menuWidth`,
+   * `tokenOverflowBehavior`, and `hasAutoFocus` have no surface to act on
+   * and warn once in development. Pass `'popover'` to keep the inline field
+   * and those props on every device.
+   * @default 'adaptive'
+   */
+  presentation?: TokenizerPresentation;
+  /**
+   * Ref forwarded to the control: the combobox input in the popover
+   * presentation, the trigger button in the sheet presentation. This type
+   * keeps its released input element; the component itself also accepts a
+   * `Ref<HTMLInputElement | HTMLButtonElement>`, the type to use where the
+   * sheet can present.
+   */
   ref?: React.Ref<HTMLInputElement>;
   /** Imperative handle ref for focus/blur control. */
   handleRef?: React.Ref<TokenizerHandle>;
   /**
    * Experimental options, outside the stable compatibility promise: anything
-   * in this object may change or be removed in a patch release. Omit it for
-   * the stable behavior.
+   * in this object may change or be removed in a patch release.
    * @experimental
    */
   experimental?: {
     /**
-     * How the field presents its choices.
-     * - `'popover'`: the inline combobox with its anchored suggestion menu —
-     *   the stable behavior.
-     * - `'bottom-sheet'`: a trigger showing the selected tokens that opens one
-     *   tall modal sheet: a search row on top, full-width checkbox rows that
-     *   keep their place while the sheet is open, a create row with
-     *   `hasCreate`, and a footer pinned in every state with a confirmed Clear
-     *   all and Save. The sheet edits a draft: `onChange` fires once, when Save
-     *   commits it, and a swipe, scrim or Escape close of a changed draft asks
-     *   before discarding. Suited to compact touch screens, where the inline
-     *   combobox competes with the software keyboard.
-     * - `'adaptive'`: the bottom sheet on compact coarse-pointer screens,
-     *   otherwise the popover — the same resolution Selector uses.
-     *
-     * In the sheet presentation the trigger is the control: `ref`, `id`,
-     * `aria-*`, and `data-*` reach it. `renderItem`, `renderToken`,
-     * `endContent`, `hasClear`, `hasEntriesOnFocus`, `menuWidth`,
-     * `tokenOverflowBehavior`, and `hasAutoFocus` have no surface to act on
-     * and warn once in development.
+     * The earlier spelling of `presentation`, with the same values. The
+     * top-level `presentation` wins when both are set.
      * @experimental
-     * @default 'popover'
+     * @deprecated Use the stable `presentation` prop.
      */
-    presentation?: 'popover' | 'bottom-sheet' | 'adaptive';
+    presentation?: TokenizerPresentation;
   };
 }
 
+/** How Tokenizer presents its choices; see `TokenizerProps.presentation`. */
+export type TokenizerPresentation = AdaptivePresentation;
+
 /**
- * The props the experimental opt-in admits. `experimental` is present, and
- * `ref` also accepts the sheet presentation's trigger button, the control it
- * stands for there. Only the overload below reaches this type. `TokenizerProps`
- * stays the component's declared props type: it is an interface, so
- * `interface X extends TokenizerProps<T>`, `Omit<TokenizerProps<T>, …>` and
- * `ComponentProps<typeof Tokenizer>` keep their released shapes.
+ * The props the component accepts: `TokenizerProps`, whose `ref` keeps its
+ * released input type, with a `ref` that also accepts the sheet
+ * presentation's trigger button. `TokenizerProps` stays the declared props
+ * type, so `interface X extends TokenizerProps<T>`, `Omit<TokenizerProps<T>,
+ * …>` and `ComponentProps<typeof Tokenizer>` keep their released shapes.
  */
-type TokenizerExperimentalProps<T extends SearchableItem> = Omit<
+type TokenizerAcceptedProps<T extends SearchableItem> = Omit<
   TokenizerProps<T>,
-  'ref' | 'experimental'
+  'ref'
 > & {
-  /** @experimental */
-  experimental: NonNullable<TokenizerProps<T>['experimental']>;
   /**
    * Ref forwarded to the control: the combobox input in the popover
    * presentation, the trigger button in the sheet presentation.
-   * @experimental
    */
   ref?: React.Ref<HTMLInputElement | HTMLButtonElement>;
 };
@@ -722,11 +738,11 @@ function EndLane({
 }
 
 // Keep this overload first. TypeScript resolves `ComponentProps<typeof
-// Tokenizer>` against the last overload, so that type stays the stable props.
-// A call that passes `experimental` matches this one and may pass the wider
-// `ref`.
+// Tokenizer>` against the last overload, so that type stays the released
+// props. Every call matches this one, so a ref typed for both controls is
+// accepted.
 export function Tokenizer<T extends SearchableItem>(
-  props: TokenizerExperimentalProps<T>,
+  props: TokenizerAcceptedProps<T>,
 ): React.JSX.Element;
 export function Tokenizer<T extends SearchableItem>(
   props: TokenizerProps<T>,
@@ -776,12 +792,13 @@ export function Tokenizer<T extends SearchableItem>({
   ref,
   handleRef,
   onKeyDown,
+  presentation: presentationProp,
   experimental,
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
   'aria-labelledby': ariaLabelledByProp,
   ...restProps
-}: TokenizerProps<T> | TokenizerExperimentalProps<T>): React.JSX.Element {
+}: TokenizerProps<T> | TokenizerAcceptedProps<T>): React.JSX.Element {
   const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const {rest, container} = useFieldInputStyling('Tokenizer', restProps, {
     containerXstyle,
@@ -807,11 +824,16 @@ export function Tokenizer<T extends SearchableItem>({
   const inputRef = useRef<HTMLInputElement>(null);
   const wrapperRef = useRef<HTMLDivElement>(null);
 
-  // Experimental presentation (`component:Tokenizer` DEC-3). `adaptive`
-  // resolves through the policy the selection controls share; an open sheet
-  // keeps its presentation until it closes, so a resolution change mid-task
-  // cannot pull the surface out from under the person.
-  const presentation = experimental?.presentation ?? 'popover';
+  // `adaptive` resolves through the policy the selection controls share. An
+  // open sheet keeps its presentation until it closes. A resolution change
+  // during a task does not replace the open surface.
+  const presentation =
+    presentationProp ?? experimental?.presentation ?? 'adaptive';
+  useDevWarning(
+    'Tokenizer',
+    '`presentation` and `experimental.presentation` are both set; `presentation` wins. Remove `experimental.presentation`.',
+    presentationProp !== undefined && experimental?.presentation !== undefined,
+  );
   const resolvedPresentation = useAdaptivePresentation(presentation);
   const [isSheetOpen, setIsSheetOpen] = useState(false);
   // Latched for the sheet's lifetime: a sheet stays presented after it closes
@@ -931,7 +953,7 @@ export function Tokenizer<T extends SearchableItem>({
         inertSheetProps.length === 1 ? 'has' : 'have'
       } no surface in the bottom-sheet presentation and ${
         inertSheetProps.length === 1 ? 'is' : 'are'
-      } not rendered there.`,
+      } not rendered there. Pass \`presentation="popover"\` to keep the inline field on every device.`,
     );
     // eslint-disable-next-line @eslint-react/exhaustive-deps -- keyed by the joined names
   }, [inertSheetPropsKey]);
@@ -1466,8 +1488,8 @@ export function Tokenizer<T extends SearchableItem>({
               {...rest}
               ref={useMergedRefs(
                 inputRef,
-                // With `experimental`, the ref type admits the trigger too; in
-                // this presentation it receives the input.
+                // The ref type admits the sheet's trigger too; in this
+                // presentation it receives the input.
                 ref as React.Ref<HTMLInputElement> | undefined,
                 handOffFocusRef,
               )}

package/src/Tokenizer/TokenizerBottomSheet.tsx

@@ -8,7 +8,7 @@
  *   EmptyState, AlertDialog, Icon, Spinner, Text, useBusyAnnouncement, and
  *   the i18n translator
  * @output Exports TokenizerBottomSheet — the touch surface of
- *   `Tokenizer experimental.presentation="bottom-sheet"`: one tall modal sheet
+ *   `Tokenizer presentation="bottom-sheet"`: one tall modal sheet
  *   with a search row on top, stable-order checkbox rows, progressive
  *   long-list rendering, an optional create row, and a confirmed Clear all
  * @position Internal presentation surface of Tokenizer. Loaded on demand by

package/src/Tokenizer/index.ts

@@ -16,6 +16,7 @@ export type {
   TokenizerProps,
   TokenizerSize,
   TokenizerOverflowBehavior,
+  TokenizerPresentation,
   TokenizerChange,
   TokenizerHandle,
   TokenizerStatus,

package/src/Tooltip/useTooltip.doc.mjs

@@ -110,6 +110,18 @@ export const docs = {
       description:
         'Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment.',
     },
+    {
+      name: 'show',
+      type: '() => void',
+      description:
+        'Opens the tooltip now and keeps it open until hide(), Escape, a press outside, or focus leaving its trigger. Its text is announced once, and onShow fires. Under a controlled isOpen it only calls onShow. Does nothing while isEnabled is false.',
+    },
+    {
+      name: 'hide',
+      type: '() => void',
+      description:
+        'Closes the tooltip now, and onHide fires. Under a controlled isOpen it only calls onHide.',
+    },
   ],
   usage: {
     description:
@@ -125,6 +137,11 @@ export const docs = {
         description:
           'Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child.',
       },
+      {
+        guidance: true,
+        description:
+          'For a toggle-style trigger, have your own button call show() and hide() on each press. Give it aria-describedby and aria-controls set to describedBy, and aria-expanded (true while show() holds the tooltip, false after hide() or onHide), and keep its own accessible name. For an info icon, use InfoTip instead.',
+      },
       {
         guidance: false,
         description:
@@ -167,6 +184,8 @@ export const docsDense = {
     anchorId: 'CSS anchor name.',
     describedBy: 'ID for aria-describedby.',
     renderTooltip: 'renders anchor-positioned tooltip content.',
+    show: 'opens + holds until hide()/Escape/outside press/focus leave; announces once; onShow. Controlled: onShow only. No-op when disabled.',
+    hide: 'closes; onHide. Controlled: onHide only.',
   },
   usage: {
     description:
@@ -182,6 +201,11 @@ export const docsDense = {
         description:
           'Prefer Tooltip for standard wrapping; use hook when trigger is not simple child.',
       },
+      {
+        guidance: true,
+        description:
+          'Toggle-style trigger: own button calls show()/hide() per press, sets aria-describedby + aria-controls={describedBy}, aria-expanded (true while held), keeps its own name. Info icon: use InfoTip.',
+      },
       {
         guidance: false,
         description:

package/src/Tooltip/useTooltip.tsx

@@ -5,7 +5,8 @@
 /**
  * @file useTooltip.tsx
  * @input Uses useLayer, usePressPin, React hooks
- * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips,
+ * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips
+ *   and imperative show() and hide() for an app-built toggle trigger,
  *   and the module-only useTooltipWithTriggerBehavior that InfoTip's press-to-pin uses
  * @position Layer hook; builds on useLayer for tooltip behavior
  *
@@ -17,9 +18,11 @@ import {
   useCallback,
   useEffect,
   useRef,
+  useState,
   type ReactNode,
   type RefCallback,
 } from 'react';
+import {createTriggerFocusGate} from '../utils/triggerFocus';
 import * as stylex from '@stylexjs/stylex';
 import {
   useLayerInternal,
@@ -216,29 +219,25 @@ export interface TooltipReturn {
     children: ReactNode,
     props?: Omit<ContextRenderProps, 'positioning'>,
   ) => ReactNode;
-}
 
-/**
- * Check if an element is naturally focusable
- */
-function isFocusable(element: HTMLElement): boolean {
-  // Elements with explicit tabindex
-  if (element.hasAttribute('tabindex')) {
-    return element.tabIndex >= 0;
-  }
-
-  // Naturally focusable elements
-  const focusableTags = ['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA'];
-  if (focusableTags.includes(element.tagName)) {
-    return !(element as HTMLButtonElement).disabled;
-  }
-
-  // Elements with contenteditable
-  if (element.isContentEditable) {
-    return true;
-  }
-
-  return false;
+  /**
+   * Opens the tooltip now and keeps it open until `hide()`, Escape, a press
+   * outside, or focus leaving its trigger, as a pinned tooltip does. Its text
+   * is announced once. Reports through `onShow`. Under a controlled `isOpen`,
+   * it calls `onShow` and does not change `isOpen`. Does nothing while
+   * `isEnabled` is false.
+   *
+   * Use `show()` and `hide()` to build a toggle-style trigger: your own button
+   * calls them, sets `aria-describedby` and `aria-controls` to `describedBy`
+   * and `aria-expanded` (true while shown), and keeps its own accessible name.
+   */
+  show: () => void;
+
+  /**
+   * Closes the tooltip now. Reports through `onHide`. Under a controlled
+   * `isOpen`, it calls `onHide` and does not change `isOpen`.
+   */
+  hide: () => void;
 }
 
 /**
@@ -375,6 +374,9 @@ export function useTooltipWithTriggerBehavior(
     isHeldOpen: isPressHeldOpen,
     attach: attachPressPin,
     unpin: unpinPress,
+    hold: holdPress,
+    release: releasePress,
+    isAppHeld,
     isPinShown,
     touch: {
       isTouchPointerRef,
@@ -485,32 +487,13 @@ export function useTooltipWithTriggerBehavior(
     [isTouchPointerRef, layerId, scheduleHide],
   );
 
-  // Under `auto`, whether focus counts is decided when it arrives, not when
-  // the listeners attach: a roving-tabindex member that was `tabindex="-1"`
-  // then can be the tab stop now. A trigger that receives focus is focusable
-  // by definition; focus inside it counts only while the trigger is
-  // focusable too, so a plain wrapper still ignores its children's focus.
-  const isFocusForTrigger = useCallback(
-    (e: Event): boolean => {
-      if (focusTrigger === 'always') {
-        return true;
-      }
-      const triggerEl = e.currentTarget as HTMLElement | null;
-      return (
-        triggerEl != null && (e.target === triggerEl || isFocusable(triggerEl))
-      );
-    },
-    [focusTrigger],
-  );
-
-  // Whether the trigger's current focus counted when it arrived, so its blur
-  // hides the tooltip even if the trigger has since left the tab order.
-  const focusCountedRef = useRef(false);
+  // Under `auto`, whether focus counts is decided when it arrives, and a
+  // focus that counted still hides on blur (utils/triggerFocus.ts).
+  const [focusGate] = useState(createTriggerFocusGate);
 
   const handleFocusIn = useCallback(
     (e: Event) => {
-      focusCountedRef.current = isFocusForTrigger(e);
-      if (!isEnabled || !focusCountedRef.current) {
+      if (!focusGate.focusIn(e, focusTrigger) || !isEnabled) {
         return;
       }
       // A tap focuses the trigger it activates, and `:focus-visible` does not
@@ -531,8 +514,9 @@ export function useTooltipWithTriggerBehavior(
       showLayer();
     },
     [
+      focusGate,
+      focusTrigger,
       isEnabled,
-      isFocusForTrigger,
       isTouchInteraction,
       clearTimeouts,
       showLayer,
@@ -544,13 +528,12 @@ export function useTooltipWithTriggerBehavior(
   // which a held tooltip skips.
   const handleFocusOut = useCallback(
     (e: Event) => {
-      if (!focusCountedRef.current && !isFocusForTrigger(e)) {
+      if (!focusGate.focusOut(e, focusTrigger)) {
         return;
       }
-      focusCountedRef.current = false;
       scheduleHide();
     },
-    [isFocusForTrigger, scheduleHide],
+    [focusGate, focusTrigger, scheduleHide],
   );
 
   // Pressing the trigger hides its own tooltip: once the control is activated
@@ -562,9 +545,10 @@ export function useTooltipWithTriggerBehavior(
   // tooltip at all), so the touch path answers it first.
   const handlePointerDown = useCallback(
     (event: PointerEvent) => {
-      // A press on a toggle trigger pins or closes through its click. It
-      // neither hides the preview here nor waits for a tap verdict.
-      if (isToggleTrigger(triggerRef.current)) {
+      // A toggle trigger's press pins or closes through its click. The app's
+      // hide() closes a held tooltip. Neither path hides here or waits for a
+      // tap verdict.
+      if (isToggleTrigger(triggerRef.current) || isAppHeld()) {
         return;
       }
       if (handleTouchPointerDown(event)) {
@@ -576,7 +560,14 @@ export function useTooltipWithTriggerBehavior(
       clearTimeouts();
       hideLayer();
     },
-    [isToggleTrigger, handleTouchPointerDown, isOpen, clearTimeouts, hideLayer],
+    [
+      isToggleTrigger,
+      isAppHeld,
+      handleTouchPointerDown,
+      isOpen,
+      clearTimeouts,
+      hideLayer,
+    ],
   );
 
   // Interaction ref that handles event listeners only
@@ -609,7 +600,7 @@ export function useTooltipWithTriggerBehavior(
         el.addEventListener('pointerdown', handlePointerDown);
 
         // Focus listeners unless focus never opens the tooltip; `auto` decides
-        // per event (isFocusForTrigger).
+        // per event (utils/triggerFocus.ts).
         if (focusTrigger !== 'never') {
           el.addEventListener('focusin', handleFocusIn);
           el.addEventListener('focusout', handleFocusOut);
@@ -665,9 +656,11 @@ export function useTooltipWithTriggerBehavior(
       showLayer();
     } else {
       clearTimeouts();
+      // A pin or app hold ends when the consumer closes the tooltip.
+      unpinPress();
       hideLayer();
     }
-  }, [isOpen, clearTimeouts, showLayer, hideLayer]);
+  }, [isOpen, clearTimeouts, showLayer, hideLayer, unpinPress]);
 
   // Dismiss on Escape (WCAG 1.4.13 — dismissible) through the shared layer
   // stack. A visible tip is the top-most layer, so it takes the press and
@@ -763,6 +756,16 @@ export function useTooltipWithTriggerBehavior(
     ],
   );
 
+  const show = useCallback(() => {
+    clearTimeouts();
+    holdPress();
+  }, [clearTimeouts, holdPress]);
+
+  const hide = useCallback(() => {
+    clearTimeouts();
+    releasePress();
+  }, [clearTimeouts, releasePress]);
+
   return {
     ref,
     positionRef: layerRef,
@@ -770,5 +773,7 @@ export function useTooltipWithTriggerBehavior(
     anchorId: layerAnchorId,
     describedBy: layerId,
     renderTooltip,
+    show,
+    hide,
   };
 }

package/src/Typeahead/BaseTypeahead.tsx

@@ -24,6 +24,7 @@ import React, {
   useCallback,
   useEffect,
   useId,
+  useInsertionEffect,
   useMemo,
   useRef,
   useState,
@@ -775,15 +776,6 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // source: they can never be re-shown, so focus bootstraps the new source.
   const sourceGenRef = useRef(0);
 
-  // Results still arriving from a replaced source must not land in the new
-  // one's menu.
-  const prevSearchSourceRef = useRef(searchSource);
-  if (prevSearchSourceRef.current !== searchSource) {
-    prevSearchSourceRef.current.cancel?.();
-    prevSearchSourceRef.current = searchSource;
-    sourceGenRef.current = ++searchGenRef.current;
-  }
-
   // The previous source is remembered in state, not a ref, so a render React
   // discards cannot consume the comparison without its state updates.
   const [sourceOfState, setSourceOfState] = useState(searchSource);
@@ -793,7 +785,6 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       setIsLoading(false);
       setHasSearched(false);
     }
-    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
@@ -807,15 +798,34 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
     }
   }
 
-  // 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
-  // in an effect so external store listeners run safely after commit.
-  const isInitialMountRef = useRef(true);
-  useEffect(() => {
-    if (isInitialMountRef.current) {
-      isInitialMountRef.current = false;
+  // Results that arrive from a replaced source must not land in the new
+  // source's menu, so the replacement starts a new generation. That happens
+  // when the replacement commits, not in render. React can render a
+  // replacement and then discard it, for example when a transition suspends
+  // and a newer update replaces it. The source that stays then keeps its read.
+  // An insertion effect runs before every layout effect and ref callback of
+  // its commit. A read that one of them starts against the replacement gets a
+  // later generation, after the replaced source stopped its requests.
+  const prevSearchSourceRef = useRef(searchSource);
+  const isSourceReplacedRef = useRef(false);
+  useInsertionEffect(() => {
+    if (prevSearchSourceRef.current === searchSource) {
+      return;
+    }
+    prevSearchSourceRef.current.cancel?.();
+    prevSearchSourceRef.current = searchSource;
+    sourceGenRef.current = ++searchGenRef.current;
+    // The replacing render cleared the busy state.
+    loadingRef.current = false;
+    isSourceReplacedRef.current = true;
+  }, [searchSource]);
+  // Syncs the wrapper's busy lane. A read of the replacement that already
+  // started keeps the lane busy.
+  useIsomorphicLayoutEffect(() => {
+    if (!isSourceReplacedRef.current) {
       return;
     }
+    isSourceReplacedRef.current = false;
     if (!loadingRef.current) {
       onLoadingChangeRef.current?.(false);
     }

package/src/Typeahead/TypeaheadItem.doc.mjs

@@ -43,7 +43,8 @@ export const docs = {
     {
       name: 'group',
       type: 'string',
-      description: 'Group label for grouping items visually.',
+      description:
+        'This prop has no effect. Set `item.auxiliaryData.group` on search-source items to group results in Typeahead or BaseTypeahead.',
     },
   ],
 };
@@ -79,7 +80,8 @@ export const docsZh = {
     {
       name: 'group',
       type: 'string',
-      description: '用于视觉分组的分组标签。',
+      description:
+        '此属性不影响渲染。要在 Typeahead 或 BaseTypeahead 中分组，请在搜索源返回的结果项上设置 `item.auxiliaryData.group`。',
     },
   ],
 };
@@ -94,6 +96,7 @@ export const docsDense = {
     icon: 'Icon/avatar before label.',
     description: 'Text below label.',
     isDisabled: 'Visually disabled.',
-    group: 'Group label for visual grouping.',
+    group:
+      'No effect. Group results via `item.auxiliaryData.group` in the search source.',
   },
 };

package/src/Typeahead/TypeaheadItem.tsx

@@ -54,7 +54,8 @@ export interface TypeaheadItemProps<
   isDisabled?: boolean;
 
   /**
-   * Group label for grouping items visually.
+   * This prop has no effect. Set `item.auxiliaryData.group` on search-source
+   * items to group results in Typeahead or BaseTypeahead.
    */
   group?: string;
 }