@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/Tooltip/useTooltip.tsx

@@ -4,9 +4,9 @@
 
 /**
  * @file useTooltip.tsx
- * @input Uses useLayer, usePressPin, React hooks
- * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips,
- *   and the module-only useTooltipWithTriggerBehavior that InfoTip's press-to-pin uses
+ * @input Uses useLayer, useTouchTriggerInternal, React hooks
+ * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips
+ *   and imperative show() and hide() for an app-built toggle trigger
  * @position Layer hook; builds on useLayer for tooltip behavior
  *
  * SYNC: When modified, update:
@@ -17,9 +17,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,
@@ -27,12 +29,14 @@ import {
   type LayerAlignment,
   type LayerPlacement,
 } from '../Layer/useLayer';
-import type {LayerTouchTrigger} from '../Layer/useTouchTrigger';
+import {
+  useTouchTriggerInternal,
+  type LayerTouchTrigger,
+} from '../Layer/useTouchTrigger';
 import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {registerLayerSurface} from '../Layer/layerSurfacePress';
-import {usePressPin, type LayerTriggerBehavior} from '../Layer/usePressPin';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {themeProps} from '../utils/themeProps';
 import {
@@ -216,29 +220,27 @@ 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. If a press on the trigger is down
+   * when you call it, and the press ends off the trigger with no click, the
+   * hold ends. The hover rules then decide.
+   * 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;
 }
 
 /**
@@ -267,42 +269,6 @@ function isFocusable(element: HTMLElement): boolean {
  */
 
 export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
-  // The option is fixed to `adaptive`, so an options object that carries it at
-  // runtime cannot reach the press-to-pin path.
-  return useTooltipWithTriggerBehavior({
-    ...options,
-    triggerBehavior: 'adaptive',
-  });
-}
-
-/**
- * Module-only options for `useTooltipWithTriggerBehavior`. Not exported from
- * the package.
- */
-export interface TooltipWithTriggerBehaviorOptions extends TooltipOptions {
-  /**
-   * How the trigger opens the tooltip:
-   * - `adaptive` (the default): hover and focus preview it. `touchTrigger`
-   *   decides taps.
-   * - `toggle`: on a button trigger, a click, a tap, Enter, or Space pins the
-   *   tooltip open, and the same press closes it. Hover and keyboard focus
-   *   still preview it. A pinned tooltip stays until Escape, a second press,
-   *   a press outside, or focus leaving. The trigger reports `aria-expanded`
-   *   and `aria-controls`, and the tooltip's text is announced once when it
-   *   pins. `touchTrigger` is ignored. InfoTip uses it.
-   *
-   * @default 'adaptive'
-   */
-  triggerBehavior?: LayerTriggerBehavior;
-}
-
-/**
- * `useTooltip` with a trigger behavior. Module-only: InfoTip's press-to-pin
- * goes through it, and the package does not export it.
- */
-export function useTooltipWithTriggerBehavior(
-  options: TooltipWithTriggerBehaviorOptions = {},
-): TooltipReturn {
   const {
     placement = 'above',
     alignment = 'center',
@@ -310,7 +276,6 @@ export function useTooltipWithTriggerBehavior(
     hideDelay = 0,
     focusTrigger = 'auto',
     touchTrigger = 'auto',
-    triggerBehavior = 'adaptive',
     isEnabled = true,
     isOpen,
     isDefaultOpen = false,
@@ -368,39 +333,122 @@ export function useTooltipWithTriggerBehavior(
     hideLayer();
   }, [clearTimeouts, hideLayer]);
 
-  // A press pins the tooltip under `triggerBehavior="toggle"`. The pin also
-  // owns the tooltip's touch trigger, so this one call wires both.
+  // DOM listeners read the latest controlled state through a ref.
+  const latestRef = useRef({isOpen, isLayerOpen, onShow, onHide});
+  latestRef.current = {isOpen, isLayerOpen, onShow, onHide};
+
+  // The app's show() holds the tooltip open until hide(), Escape, a press or
+  // scroll outside, or focus leaving the trigger and the tooltip.
+  const isHeldRef = useRef(false);
+  const [isHeldState, setIsHeldState] = useState(false);
+  const setHeld = useCallback((next: boolean) => {
+    isHeldRef.current = next;
+    setIsHeldState(next);
+  }, []);
+
+  // Whether the current hold began during a press on the trigger. Such a
+  // hold ends with the press when the press ends off the trigger, as no click
+  // pins it. The hover rules then decide. isHoldInThisTaskRef covers a show()
+  // that runs before the hook's own pointerdown listener.
+  const isHoldFromPressRef = useRef(false);
+  const isHoldInThisTaskRef = useRef(false);
+  const handleReleaseInLayer = useCallback(() => {
+    if (isHoldFromPressRef.current && isHeldRef.current) {
+      isHoldFromPressRef.current = false;
+      setHeld(false);
+    }
+  }, [setHeld]);
+
+  // The touch trigger's outside dismissal (a press or scroll outside) ends a
+  // hold with the tooltip.
+  const hideFromTouch = useCallback(() => {
+    if (isHeldRef.current) {
+      setHeld(false);
+      const latest = latestRef.current;
+      if (latest.isOpen !== undefined) {
+        latest.onHide?.();
+        return;
+      }
+    }
+    hideNow();
+  }, [setHeld, hideNow]);
+
   const {
-    isToggleTrigger,
-    isHeldOpen: isPressHeldOpen,
-    attach: attachPressPin,
-    unpin: unpinPress,
-    isPinShown,
-    touch: {
-      isTouchPointerRef,
-      isTouchInteraction,
-      handlePointerEnter,
-      handlePointerDown: handleTouchPointerDown,
-      clearTapOpen,
+    isTouchPointerRef,
+    isTouchInteraction,
+    handlePointerEnter,
+    handlePointerDown: handleTouchPointerDown,
+    clearTapOpen,
+    armOutsideDismiss,
+  } = useTouchTriggerInternal(
+    {
+      touchTrigger,
+      isEnabled,
+      isControlled: isOpen !== undefined,
+      isOpen: isLayerOpen,
+      layerId,
+      triggerRef,
+      show: showNow,
+      hide: hideFromTouch,
     },
-  } = usePressPin({
-    triggerBehavior,
-    touchTrigger,
-    isEnabled,
-    isOpen,
-    isLayerOpen,
-    layerId,
-    triggerRef,
-    component: 'Tooltip',
-    show: showNow,
-    hide: hideNow,
-    report: next => (next ? onShow?.() : onHide?.()),
-  });
+    handleReleaseInLayer,
+  );
 
-  // Only a pin announces the text: a preview is already the trigger's
+  const isHeldOpen = useCallback(() => {
+    const latest = latestRef.current;
+    return isHeldRef.current && latest.isLayerOpen && latest.isOpen !== false;
+  }, []);
+
+  const releaseHold = useCallback(() => {
+    clearTapOpen();
+    setHeld(false);
+    const latest = latestRef.current;
+    if (latest.isOpen !== undefined) {
+      latest.onHide?.();
+      return;
+    }
+    hideNow();
+  }, [clearTapOpen, setHeld, hideNow]);
+
+  const dropHold = useCallback(() => {
+    if (isHeldRef.current) {
+      setHeld(false);
+    }
+  }, [setHeld]);
+
+  // Focus leaving the trigger and the tooltip ends a hold, whatever
+  // `focusTrigger` is. Focus that leaves for no element is a press's to
+  // decide. The trigger can sit in another document, so the check uses its
+  // own window.
+  const handleHeldFocusOut = useCallback(
+    (event: FocusEvent) => {
+      if (!isHeldOpen()) {
+        return;
+      }
+      const next = event.relatedTarget;
+      const trigger = triggerRef.current;
+      const view = trigger?.ownerDocument.defaultView;
+      if (view == null || !(next instanceof view.Node)) {
+        return;
+      }
+      const surface = trigger?.ownerDocument.getElementById(layerId) ?? null;
+      if (
+        trigger?.contains(next) === true ||
+        surface?.contains(next) === true
+      ) {
+        return;
+      }
+      releaseHold();
+    },
+    [isHeldOpen, layerId, releaseHold],
+  );
+
+  const isHoldShown = isHeldState && isLayerOpen && isOpen !== false;
+
+  // Only a hold announces the text: a preview is already the trigger's
   // description.
   const contentRef = useRef<HTMLDivElement | null>(null);
-  useAnnounceRenderedText(contentRef, isPinShown, 'pinned');
+  useAnnounceRenderedText(contentRef, isHoldShown, 'pinned');
   const contentRefs = useMergedRefs<HTMLDivElement>(
     contentRef,
     registerLayerSurface,
@@ -433,7 +481,7 @@ export function useTooltipWithTriggerBehavior(
   // trigger onto the tooltip surface without the tooltip vanishing — required
   // for WCAG 1.4.13 (Content on Hover or Focus: hoverable).
   const scheduleHide = useCallback(() => {
-    if (isOpen === true || isPressHeldOpen()) {
+    if (isOpen === true || isHeldOpen()) {
       return;
     }
     clearTimeouts();
@@ -441,7 +489,7 @@ export function useTooltipWithTriggerBehavior(
     hideTimeoutRef.current = setTimeout(() => {
       hideLayer();
     }, effectiveHideDelay);
-  }, [isOpen, isPressHeldOpen, clearTimeouts, hideLayer, hideDelay]);
+  }, [isOpen, isHeldOpen, clearTimeouts, hideLayer, hideDelay]);
 
   // Cancel a pending hide (e.g. the pointer entered the tooltip surface).
   const cancelHide = useCallback(() => {
@@ -485,32 +533,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,26 +560,26 @@ export function useTooltipWithTriggerBehavior(
       showLayer();
     },
     [
+      focusGate,
+      focusTrigger,
       isEnabled,
-      isFocusForTrigger,
       isTouchInteraction,
       clearTimeouts,
       showLayer,
     ],
   );
 
-  // A pinned tooltip's focus-leave close is the pin's own: it listens on the
-  // trigger whatever `focusTrigger` is. This schedules the unpinned hide,
-  // which a held tooltip skips.
+  // A held tooltip's focus-leave close is the hold's own: it listens on the
+  // trigger whatever `focusTrigger` is. This schedules the unheld hide, 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
@@ -560,14 +589,56 @@ export function useTooltipWithTriggerBehavior(
   // is owned by the consumer. `hideLayer()` self-guards when already closed.
   // A touch press is a different gesture (it may be the only way to open the
   // tooltip at all), so the touch path answers it first.
+  // Whether a press on the trigger is down, from the hook's pointerdown to
+  // the press's end.
+  const isTriggerPressedRef = useRef(false);
+  const stopPressTrackingRef = useRef<(() => void) | null>(null);
+  const trackTriggerPress = useCallback(() => {
+    stopPressTrackingRef.current?.();
+    const view = triggerRef.current?.ownerDocument.defaultView;
+    if (view == null) {
+      return;
+    }
+    isTriggerPressedRef.current = true;
+    const trigger = triggerRef.current;
+    const stop = (event?: Event) => {
+      // A press that ends on the trigger keeps its hold, as a click does.
+      if (
+        event?.type === 'pointerup' &&
+        event.target instanceof view.Node &&
+        trigger?.contains(event.target) === true
+      ) {
+        isHoldFromPressRef.current = false;
+      }
+      view.removeEventListener('pointerup', stop, true);
+      view.removeEventListener('pointercancel', stop, true);
+      isTriggerPressedRef.current = false;
+      stopPressTrackingRef.current = null;
+    };
+    view.addEventListener('pointerup', stop, true);
+    view.addEventListener('pointercancel', stop, true);
+    stopPressTrackingRef.current = stop;
+  }, []);
+
   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)) {
+      trackTriggerPress();
+      // The app's hide() closes a held tooltip. A press neither hides it here
+      // nor waits for a tap verdict. A show() in a capture handler of this
+      // press runs before this listener. Tie that hold to the press.
+      if (isHeldRef.current) {
+        if (isHoldInThisTaskRef.current) {
+          isHoldFromPressRef.current = true;
+        }
         return;
       }
       if (handleTouchPointerDown(event)) {
+        // A pen in range starts the hover show before it lands. Left pending,
+        // that show opens the layer during the press. The tap then closes it.
+        if (showTimeoutRef.current) {
+          clearTimeout(showTimeoutRef.current);
+          showTimeoutRef.current = null;
+        }
         return;
       }
       if (isOpen !== undefined) {
@@ -576,7 +647,13 @@ export function useTooltipWithTriggerBehavior(
       clearTimeouts();
       hideLayer();
     },
-    [isToggleTrigger, handleTouchPointerDown, isOpen, clearTimeouts, hideLayer],
+    [
+      handleTouchPointerDown,
+      trackTriggerPress,
+      isOpen,
+      clearTimeouts,
+      hideLayer,
+    ],
   );
 
   // Interaction ref that handles event listeners only
@@ -588,6 +665,8 @@ export function useTooltipWithTriggerBehavior(
         triggerRef.current.removeEventListener('mouseleave', handleMouseLeave);
         triggerRef.current.removeEventListener('focusin', handleFocusIn);
         triggerRef.current.removeEventListener('focusout', handleFocusOut);
+        triggerRef.current.removeEventListener('focusout', handleHeldFocusOut);
+        stopPressTrackingRef.current?.();
         triggerRef.current.removeEventListener(
           'pointerenter',
           handlePointerEnter,
@@ -609,18 +688,19 @@ 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);
         }
       }
 
+      // Its own focus-leave listener: `focusTrigger="never"` attaches none.
+      el?.addEventListener('focusout', handleHeldFocusOut);
       triggerRef.current = el;
-      attachPressPin(el);
     },
     [
-      attachPressPin,
+      handleHeldFocusOut,
       focusTrigger,
       handleMouseEnter,
       handleMouseLeave,
@@ -665,9 +745,11 @@ export function useTooltipWithTriggerBehavior(
       showLayer();
     } else {
       clearTimeouts();
+      // A hold ends when the consumer closes the tooltip.
+      dropHold();
       hideLayer();
     }
-  }, [isOpen, clearTimeouts, showLayer, hideLayer]);
+  }, [isOpen, clearTimeouts, showLayer, hideLayer, dropHold]);
 
   // 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
@@ -708,7 +790,7 @@ export function useTooltipWithTriggerBehavior(
     onDismiss: () => {
       clearTimeouts();
       clearTapOpen();
-      unpinPress();
+      dropHold();
       if (isOpen !== undefined) {
         onHide?.();
         return;
@@ -745,7 +827,7 @@ export function useTooltipWithTriggerBehavior(
         // something else in the shared interactive-ancestor walk, so a
         // clickable container around the trigger leaves the press alone while
         // document listeners still see it.
-        // The pin's announcement reads this element's text.
+        // The hold's announcement reads this element's text.
         <div ref={contentRefs} {...stylex.props(styles.content)}>
           {children}
         </div>,
@@ -763,6 +845,31 @@ export function useTooltipWithTriggerBehavior(
     ],
   );
 
+  const show = useCallback(() => {
+    clearTimeouts();
+    if (!isEnabled) {
+      return;
+    }
+    setHeld(true);
+    armOutsideDismiss();
+    isHoldFromPressRef.current = isTriggerPressedRef.current;
+    isHoldInThisTaskRef.current = true;
+    triggerRef.current?.ownerDocument.defaultView?.setTimeout(() => {
+      isHoldInThisTaskRef.current = false;
+    }, 0);
+    const latest = latestRef.current;
+    if (latest.isOpen !== undefined) {
+      latest.onShow?.();
+      return;
+    }
+    showLayer();
+  }, [clearTimeouts, isEnabled, setHeld, armOutsideDismiss, showLayer]);
+
+  const hide = useCallback(() => {
+    clearTimeouts();
+    releaseHold();
+  }, [clearTimeouts, releaseHold]);
+
   return {
     ref,
     positionRef: layerRef,
@@ -770,5 +877,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;
 }