@astryxdesign/core 0.7.8 → 0.7.9-canary.0a64fdb

package/src/RadioList/RadioListItem.doc.mjs

@@ -8,7 +8,7 @@ export const docs = {
   displayName: 'Radio List Item',
   isHiddenFromOverview: true,
   description:
-    'Individual radio item with label, description, and content slots.',
+    'Individual radio item with label, description, and content slots. Under a coarse pointer an enabled option’s target grows toward 44 px through an invisible hit area. It never shrinks below the row and stops at half the gap to a closer neighbour; the row keeps its size. That hit area is the row’s `::after`, so decorate a row with a child.',
   // RadioListItem requires RadioList context; wrap it so the preview doesn't throw.
   playground: {
     defaults: {value: 'option-1', label: 'Option'},
@@ -97,7 +97,8 @@ export const docsZh = {
   name: 'RadioListItem',
   isHiddenFromOverview: true,
   displayName: 'Radio List Item',
-  description: '单个单选选项，包含标签、描述和内容插槽。',
+  description:
+    '单个单选选项，包含标签、描述和内容插槽。在粗指针（触摸）下，已启用选项的目标通过不可见的点击区域向 44 px 扩展。它不小于所在行，与相邻控件较近时止于间距的一半；行尺寸不变。该点击区域是行的 `::after`，因此请用子元素装饰行。',
   props: [
     {
       name: 'label',

package/src/RadioList/RadioListItem.tsx

@@ -18,7 +18,7 @@
  * - /packages/cli/assets/templates/blocks/components/RadioList/ (showcase blocks)
  */
 
-import React, {use, useId, useRef, type ReactNode} from 'react';
+import React, {use, useCallback, useId, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
@@ -32,9 +32,13 @@ import {rtlStyles} from '../utils/rtlStyles';
 import {indicatorScope} from '../Indicator/indicator.markers.stylex';
 import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
 import {usePressFeedback} from '../hooks/usePressFeedback';
+import {useMergedRefs} from '../hooks/useMergedRefs';
+import {watchHitArea, writeHitInsets} from '../utils/hitArea';
+import {touchHitAreaStyles} from '../utils/touchHitArea.stylex';
 import {useIndicator} from '../Indicator/useIndicator';
 import {Item, type ItemAlign} from '../Item/Item';
 import {themeProps} from '../utils/themeProps';
+import {rowPressLayerStyles} from '../privateAttributes/press.stylex';
 
 // The touch press's paint, declared by the shared overlay styles on the
 // element the controller writes to (`pressedAlpha`) at the press's strength,
@@ -147,11 +151,6 @@ const rowStyles = stylex.create({
     // Suppress Item's interactive hover/press background so the resting and
     // hovered row look identical by default (a theme can restyle either).
     backgroundColor: 'transparent',
-    // ...and the touch press's overlay image, for the same reason: under a
-    // finger only the radio circle paints, as under a mouse. The press's
-    // strength still lands on the row, which is where the layer over the
-    // circle reads it.
-    backgroundImage: 'none',
   },
   // The mouse press (a finger's lives on `data-astryx-press`): the row is
   // pressed, but not through a nested link or button, which keep their own
@@ -309,6 +308,21 @@ export function RadioListItem({
   // `<label htmlFor>` would double-fire under delegation.
   const radioRef = useRef<HTMLInputElement>(null);
 
+  // Under a coarse pointer an option's row grows toward 44 px through an
+  // invisible band, and the row keeps its size. A tap on the band lands on
+  // the row, which hands it to the radio. The watch lives as long as the row
+  // is attached: the ref's cleanup stops it.
+  const watchRowHitArea = useCallback(
+    (row: HTMLDivElement | null) => {
+      if (row == null || isDisabled) {
+        return;
+      }
+      return watchHitArea(row, insets => writeHitInsets(row, insets));
+    },
+    [isDisabled],
+  );
+  const mergedRowRef = useMergedRefs(ref, watchRowHitArea);
+
   const radioCircle = (
     <div
       {...stylex.props(
@@ -391,7 +405,7 @@ export function RadioListItem({
 
   return (
     <Item
-      ref={ref}
+      ref={mergedRowRef}
       {...(isDisabled ? undefined : pressable)}
       startContent={mediaContent}
       // Delegate row-surface clicks (label text, description, and the empty
@@ -414,12 +428,16 @@ export function RadioListItem({
           // the painting row element (Item), the same element that carries the
           // theme target, so a theme's hover styling stays in step with the tint.
           !isDisabled && indicatorScope,
+          // The row keeps no press paint of its own: the circle paints, and
+          // reads the strength whose release the row keeps.
+          rowPressLayerStyles.cellWithoutLayer,
           // Restore the bare default look: zero Item's padding/radius and its
           // interactive hover/press background. Applied after Item's own base
           // styles so it wins within the base layer; a `radio-list-item` theme
           // still overrides it from the higher `astryx-theme` layer.
           rowStyles.root,
           !isDisabled && rowStyles.press,
+          !isDisabled && touchHitAreaStyles.layer,
           xstyle,
         ] as StyleXStyles
       }

package/src/SelectableCard/SelectableCard.tsx

@@ -44,6 +44,7 @@ import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import type {Elevation, SizeValue, SpacingStep} from '../utils/types';
 import {isImeKeyEvent, mergeProps} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
 import {Card} from '../Card/Card';
 import type {CardVariant} from '../Card/Card';
 import {useClickableContainer} from '../hooks/useClickableContainer';
@@ -398,6 +399,7 @@ export function SelectableCard({
   onChange,
   onClick: onClickProp,
   onMouseUp: onMouseUpProp,
+  onPointerDown: onPointerDownProp,
   isDisabled = false,
   children,
   padding,
@@ -458,7 +460,7 @@ export function SelectableCard({
     [isDisabled, requestChange],
   );
 
-  const {onClick, onMouseUp} = useClickableContainer({
+  const {onClick, onMouseUp, onPointerDown} = useClickableContainer({
     containerRef,
     interactiveRef,
     onClick: handleClick,
@@ -530,6 +532,11 @@ export function SelectableCard({
       }
       onClick={!isDisabled ? composedOnClick : undefined}
       onMouseUp={!isDisabled ? composedOnMouseUp : undefined}
+      onPointerDown={
+        !isDisabled
+          ? chainEventHandlers(onPointerDown, onPointerDownProp)
+          : onPointerDownProp
+      }
       {...props}
       onClickCapture={
         !isDisabled && handleLayerClickCapture

package/src/Spinner/Spinner.tsx

@@ -211,6 +211,16 @@ function syncRotationPhase(
 // Animation
 // =============================================================================
 
+/**
+ * Full turns in one iteration of the rotation.
+ *
+ * Chromium wakes the main thread at each iteration boundary while the
+ * document listens for `animationiteration`. React listens for it on every
+ * root. One iteration holds 100 turns, so the wake comes once in 100 turns.
+ * Each turn is 360 degrees, so the ring looks the same.
+ */
+const TURNS_PER_ITERATION = 100;
+
 /**
  * A `transform` animation runs on the compositor, so the ring keeps turning
  * while a script runs. A `stroke-dashoffset` animation would repaint the arc
@@ -218,7 +228,7 @@ function syncRotationPhase(
  */
 const rotation = stylex.keyframes({
   '0%': {transform: 'rotate(0deg)'},
-  '100%': {transform: 'rotate(360deg)'},
+  '100%': {transform: `rotate(${360 * TURNS_PER_ITERATION}deg)`},
 });
 
 // =============================================================================
@@ -307,8 +317,8 @@ const styles = stylex.create({
     // broken. The status role and its name still say that work is busy.
     animationDuration: {
       // The loop reads the duration before a theme's tempo scales it.
-      default: `var(--_astryx-pre-tempo-duration-slow-min, ${durationVars['--duration-slow-min']})`,
-      '@media (prefers-reduced-motion: reduce)': '3s',
+      default: `calc(var(--_astryx-pre-tempo-duration-slow-min, ${durationVars['--duration-slow-min']}) * ${TURNS_PER_ITERATION})`,
+      '@media (prefers-reduced-motion: reduce)': `calc(3s * ${TURNS_PER_ITERATION})`,
     },
     animationIterationCount: 'infinite',
     animationName: rotation,

package/src/Stack/Stack.doc.mjs

@@ -524,7 +524,7 @@ export const docs = {
           name: 'isScrollable',
           type: 'boolean',
           description:
-            'Enables scrollable overflow (overflow: auto). StackItem already applies the flex min-height/min-width reset, so <StackItem size="fill" isScrollable> is a complete scroll region. Matches isScrollable on LayoutContent and LayoutPanel.',
+            'Enables scrollable overflow (overflow: auto). StackItem already applies the flex min-height/min-width reset, so <StackItem size="fill" isScrollable> is a complete scroll region. Matches isScrollable on LayoutContent and LayoutPanel. While its content overflows, a div or span item is a group named by aria-label, or by a translated "Content"; another element keeps its own role.',
           default: 'false',
         },
         {

package/src/Stack/StackItem.tsx

@@ -2,9 +2,11 @@
 
 /**
  * @file StackItem.tsx
- * @input Uses React, ElementType, stackItem utility
+ * @input Uses React, ElementType, stackItem utility, StackItemScrollRegion
  * @output Exports StackItem polymorphic component and StackItemProps
- * @position Layout/Stack component; uses stackItem.stylex.ts
+ * @position Layout/Stack component; uses stackItem.stylex.ts. A scrollable
+ *   `div` or `span` item renders through StackItemScrollRegion, which names
+ *   it while it scrolls.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
@@ -21,6 +23,7 @@ import {
 } from './stackItem.stylex';
 import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
+import {StackItemScrollRegion} from '../hooks/StackItemScrollRegion';
 
 const overflowStyles = stylex.create({
   scrollable: {
@@ -53,7 +56,9 @@ export interface StackItemProps extends BaseProps<HTMLElement> {
    * reset, so `<StackItem size="fill" isScrollable>` is a complete scroll
    * region — it grows to fill the stack and scrolls its own overflow with
    * no extra style plumbing. Matches `isScrollable` on `LayoutContent`
-   * and `LayoutPanel`.
+   * and `LayoutPanel`. While its content overflows, a `div` or `span` item
+   * is a group named by the caller's `aria-label`, or by a translated
+   * "Content". Another element keeps its own role.
    * @default false
    */
   isScrollable?: boolean;
@@ -102,18 +107,27 @@ export function StackItem({
     xstyle,
   );
 
+  const elementProps = {
+    ...mergeProps(
+      themeProps('stack-item', {size}),
+      stylexProps,
+      className,
+      style,
+    ),
+    ...props,
+  };
+
+  if (isScrollable && (element === 'div' || element === 'span')) {
+    return createElement(
+      StackItemScrollRegion,
+      {as: element, ref, elementProps},
+      children,
+    );
+  }
+
   return createElement(
     element,
-    {
-      ref: ref as Ref<Element>,
-      ...mergeProps(
-        themeProps('stack-item', {size}),
-        stylexProps,
-        className,
-        style,
-      ),
-      ...props,
-    },
+    {ref: ref as Ref<Element>, ...elementProps},
     children,
   );
 }

package/src/Table/plugins/sortable/useTableSortable.tsx

@@ -168,7 +168,7 @@ const sortStyles = stylex.create({
     fontSize: 10,
     // eslint-disable-next-line @astryx/no-hardcoded-styles -- no token for lineHeight:1 (tight badge)
     lineHeight: '1',
-    color: colorVars['--color-accent'],
+    color: colorVars['--color-text-accent'],
   },
 });
 

package/src/Token/Token.tsx

@@ -39,6 +39,7 @@ import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
+import {cancelNestedTouchPress} from '../hooks/useClickableContainer';
 import type {TokenColorMap} from './index';
 import {disabledInteractionProps} from '../utils/disabledInteraction';
 import {TokenNamingContext} from './TokenNamingContext';
@@ -510,6 +511,19 @@ export function Token({
       }
       effectiveOnClick(e);
     };
+    // A finger press on Remove or a control in end content does not run the
+    // token's action, so the token shows no press for it. The inner button,
+    // the first button child, is the token's own action.
+    const handleContainerPointerDown = (
+      e: React.PointerEvent<HTMLSpanElement>,
+    ) => {
+      rest.onPointerDown?.(e);
+      cancelNestedTouchPress(
+        e,
+        e.currentTarget,
+        e.currentTarget.querySelector(':scope > button'),
+      );
+    };
 
     return (
       <span
@@ -535,7 +549,10 @@ export function Token({
           style,
         )}
         {...rest}
-        {...sharedProps}>
+        {...sharedProps}
+        onPointerDown={
+          isDisabled ? rest.onPointerDown : handleContainerPointerDown
+        }>
         {icon}
         <button
           type="button"

package/src/Token/TokenLink.tsx

@@ -90,12 +90,13 @@ export function TokenLink({
   removeButton,
   onClick: onClickProp,
   onMouseUp: onMouseUpProp,
+  onPointerDown: onPointerDownProp,
   ...containerProps
 }: TokenLinkProps) {
   const containerRef = useRef<HTMLElement | null>(null);
   const linkRef = useRef<HTMLElement | null>(null);
 
-  const {onClick, onMouseUp} = useClickableContainer({
+  const {onClick, onMouseUp, onPointerDown} = useClickableContainer({
     containerRef,
     interactiveRef: linkRef,
     href,
@@ -113,6 +114,11 @@ export function TokenLink({
         isDisabled
           ? onMouseUpProp
           : composeEventHandlers(onMouseUpProp, onMouseUp)
+      }
+      onPointerDown={
+        isDisabled
+          ? onPointerDownProp
+          : composeEventHandlers(onPointerDownProp, onPointerDown)
       }>
       {icon}
       {isDisabled ? (

package/src/Tooltip/useTooltip.tsx

@@ -21,7 +21,7 @@ import {
   type ReactNode,
   type RefCallback,
 } from 'react';
-import {createTriggerFocusGate} from '../utils/triggerFocus';
+import {createTriggerFocusGate, isFocusOnTrigger} from '../utils/triggerFocus';
 import * as stylex from '@stylexjs/stylex';
 import {
   useLayerInternal,
@@ -308,6 +308,17 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const triggerRef = useRef<HTMLElement | null>(null);
+  // Whether the tooltip is enabled now, for a show that runs after a render
+  // (a pending hover show) and for the trigger ref callback.
+  const isEnabledRef = useRef(isEnabled);
+  isEnabledRef.current = isEnabled;
+  // Counts the renders in which the tooltip is disabled. A pending show
+  // records it, so a show scheduled before a disable is dropped even when
+  // the tooltip is enabled again before the timer fires.
+  const disabledRendersRef = useRef(0);
+  if (!isEnabled) {
+    disabledRendersRef.current += 1;
+  }
 
   // Clear all timeouts
   const clearTimeouts = useCallback(() => {
@@ -460,22 +471,16 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       return;
     }
     clearTimeouts();
+    const disabledRenders = disabledRendersRef.current;
     showTimeoutRef.current = setTimeout(() => {
-      showLayer();
+      // A show runs only if the tooltip stayed enabled since it was
+      // scheduled: nothing would close a tooltip that opens after a disable.
+      if (disabledRendersRef.current === disabledRenders) {
+        showLayer();
+      }
     }, delay);
   }, [isEnabled, isOpen, clearTimeouts, showLayer, delay]);
 
-  // A show scheduled while the triggers were enabled must not outlive them:
-  // disabling also detaches the leave listener that would have cancelled it,
-  // so the timer would open a tooltip that nothing ever closes. Only the
-  // pending show is dropped; a pending hide still runs.
-  useEffect(() => {
-    if (!isEnabled && showTimeoutRef.current) {
-      clearTimeout(showTimeoutRef.current);
-      showTimeoutRef.current = null;
-    }
-  }, [isEnabled]);
-
   // Schedule hide with delay (suppressed when isOpen is true).
   // A small hover bridge (when hideDelay is 0) lets the pointer travel from the
   // trigger onto the tooltip surface without the tooltip vanishing — required
@@ -537,23 +542,25 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // focus that counted still hides on blur (utils/triggerFocus.ts).
   const [focusGate] = useState(createTriggerFocusGate);
 
+  // Whether focus on `target` opens the tooltip. With a `trigger`, its
+  // `focusTrigger` rule applies too. Only `:focus-visible` focus opens it, and
+  // a tap never does: a tapped `<input>` also matches `:focus-visible`.
+  const opensOnFocus = useCallback(
+    (target: HTMLElement, trigger: HTMLElement | null): boolean => {
+      if (trigger != null && !isFocusOnTrigger(target, trigger, focusTrigger)) {
+        return false;
+      }
+      return !isTouchInteraction() && target.matches(':focus-visible');
+    },
+    [focusTrigger, isTouchInteraction],
+  );
+
   const handleFocusIn = useCallback(
     (e: Event) => {
       if (!focusGate.focusIn(e, focusTrigger) || !isEnabled) {
         return;
       }
-      // A tap focuses the trigger it activates, and `:focus-visible` does not
-      // filter that out on every element: a tapped `<input>` or contenteditable
-      // matches it. Those are exactly the action triggers `auto` just decided
-      // to keep shut, so without this the focus reopens what the tap
-      // suppressed, over the field the user is trying to type into.
-      if (isTouchInteraction()) {
-        return;
-      }
-      // Only show tooltip for keyboard focus (:focus-visible),
-      // not programmatic focus (e.g. dialog auto-focus, touch tap)
-      const target = e.target as HTMLElement;
-      if (!target.matches(':focus-visible')) {
+      if (!opensOnFocus(e.target as HTMLElement, null)) {
         return;
       }
       clearTimeouts();
@@ -563,7 +570,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       focusGate,
       focusTrigger,
       isEnabled,
-      isTouchInteraction,
+      opensOnFocus,
       clearTimeouts,
       showLayer,
     ],
@@ -656,66 +663,155 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     ],
   );
 
-  // Interaction ref that handles event listeners only
-  const interactionRef: RefCallback<HTMLElement> = useCallback(
-    (el: HTMLElement | null) => {
-      // Cleanup previous element
-      if (triggerRef.current) {
-        triggerRef.current.removeEventListener('mouseenter', handleMouseEnter);
-        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,
-        );
-        triggerRef.current.removeEventListener(
-          'pointerdown',
-          handlePointerDown,
-        );
-      }
+  // The trigger's listeners call the latest handlers through this ref, so the
+  // trigger ref callback keeps one identity.
+  const handlersRef = useRef({
+    handleMouseEnter,
+    handleMouseLeave,
+    handleFocusIn,
+    handleFocusOut,
+    handleHeldFocusOut,
+    handlePointerEnter,
+    handlePointerDown,
+    focusTrigger,
+    isOpen,
+    dropHold,
+    hideNow,
+    showNow,
+    opensOnFocus,
+  });
+  handlersRef.current = {
+    handleMouseEnter,
+    handleMouseLeave,
+    handleFocusIn,
+    handleFocusOut,
+    handleHeldFocusOut,
+    handlePointerEnter,
+    handlePointerDown,
+    focusTrigger,
+    isOpen,
+    dropHold,
+    hideNow,
+    showNow,
+    opensOnFocus,
+  };
 
-      if (el) {
-        // Attach hover listeners. `pointerenter` runs before the synthesized
-        // `mouseenter` a tap produces, which is what lets the hover path know
-        // it is looking at a finger.
-        el.addEventListener('pointerenter', handlePointerEnter);
-        el.addEventListener('mouseenter', handleMouseEnter);
-        el.addEventListener('mouseleave', handleMouseLeave);
-        // Press-to-dismiss on a mouse; tap-to-open on a touch pointer.
-        el.addEventListener('pointerdown', handlePointerDown);
-
-        // Focus listeners unless focus never opens the tooltip; `auto` decides
-        // per event (utils/triggerFocus.ts).
-        if (focusTrigger !== 'never') {
-          el.addEventListener('focusin', handleFocusIn);
-          el.addEventListener('focusout', handleFocusOut);
-        }
+  // Removes the attached trigger's listeners (the trigger ref callback's
+  // cleanup).
+  const detachTriggerRef = useRef<(() => void) | null>(null);
+  // Set when the trigger detached while the tooltip was disabled: the
+  // caller removed the wiring (DropdownMenu's Button while its menu is
+  // open), so the next enabled attach reads the focus that arrived meanwhile.
+  const wasSuppressedRef = useRef(false);
+
+  // The trigger's ref callback owns every trigger listener, and reads the
+  // trigger's state when it attaches and detaches.
+  const interactionRef = useCallback((el: HTMLElement | null) => {
+    // A caller that reports `null` by hand detaches the trigger, as the
+    // returned cleanup does.
+    if (el == null) {
+      detachTriggerRef.current?.();
+      return;
+    }
+    if (el === triggerRef.current) {
+      return;
+    }
+    detachTriggerRef.current?.();
+    const latest = () => handlersRef.current;
+    // `pointerenter` runs before the synthesized `mouseenter` a tap produces,
+    // which is what lets the hover path know it is looking at a finger.
+    const onPointerEnter = (e: PointerEvent) => latest().handlePointerEnter(e);
+    const onMouseEnter = () => latest().handleMouseEnter();
+    const onMouseLeave = (e: Event) => latest().handleMouseLeave(e);
+    // Press-to-dismiss on a mouse; tap-to-open on a touch pointer.
+    const onPointerDown = (e: PointerEvent) => latest().handlePointerDown(e);
+    // Focus counts unless focus never opens the tooltip; `auto` decides per
+    // event (isFocusForTrigger).
+    const onFocusIn = (e: Event) => {
+      if (latest().focusTrigger !== 'never') {
+        latest().handleFocusIn(e);
+      }
+    };
+    const onFocusOut = (e: Event) => {
+      if (latest().focusTrigger !== 'never') {
+        latest().handleFocusOut(e);
       }
+    };
+    // A held tooltip's own focus-leave close, whatever `focusTrigger` is.
+    const onHeldFocusOut = (e: FocusEvent) => latest().handleHeldFocusOut(e);
+    el.addEventListener('pointerenter', onPointerEnter);
+    el.addEventListener('mouseenter', onMouseEnter);
+    el.addEventListener('mouseleave', onMouseLeave);
+    el.addEventListener('pointerdown', onPointerDown);
+    el.addEventListener('focusin', onFocusIn);
+    el.addEventListener('focusout', onFocusOut);
+    el.addEventListener('focusout', onHeldFocusOut);
+    triggerRef.current = el;
+
+    // A trigger that attaches again after its wiring was removed
+    // (DropdownMenu's Button as its menu closes) missed the focus that
+    // arrived meanwhile. Show for it only if it would open the tooltip:
+    // returned keyboard focus does, focus returned after a pointer pick does
+    // not. Any other attach leaves the tooltip as it is, so a tooltip
+    // dismissed with Escape stays closed.
+    const focused = el.ownerDocument.activeElement;
+    const wasSuppressed = wasSuppressedRef.current;
+    if (isEnabledRef.current) {
+      wasSuppressedRef.current = false;
+    }
+    if (
+      wasSuppressed &&
+      isEnabledRef.current &&
+      latest().isOpen === undefined &&
+      latest().focusTrigger !== 'never' &&
+      focused instanceof HTMLElement &&
+      el.contains(focused) &&
+      latest().opensOnFocus(focused, el)
+    ) {
+      latest().showNow();
+    }
 
-      // Its own focus-leave listener: `focusTrigger="never"` attaches none.
-      el?.addEventListener('focusout', handleHeldFocusOut);
-      triggerRef.current = el;
-    },
-    [
-      handleHeldFocusOut,
-      focusTrigger,
-      handleMouseEnter,
-      handleMouseLeave,
-      handleFocusIn,
-      handleFocusOut,
-      handlePointerEnter,
-      handlePointerDown,
-    ],
-  );
+    const detach = () => {
+      if (detachTriggerRef.current === detach) {
+        detachTriggerRef.current = null;
+      }
+      el.removeEventListener('pointerenter', onPointerEnter);
+      el.removeEventListener('mouseenter', onMouseEnter);
+      el.removeEventListener('mouseleave', onMouseLeave);
+      el.removeEventListener('pointerdown', onPointerDown);
+      el.removeEventListener('focusin', onFocusIn);
+      el.removeEventListener('focusout', onFocusOut);
+      el.removeEventListener('focusout', onHeldFocusOut);
+      stopPressTrackingRef.current?.();
+      if (triggerRef.current === el) {
+        triggerRef.current = null;
+      }
+      // A caller removes the wiring as it disables the tooltip. Close an
+      // uncontrolled tooltip then, or the next attach shows a stale tooltip.
+      // A detach while enabled, such as a merged ref that changes identity
+      // on a re-render, keeps a hovered or held tooltip open.
+      if (!isEnabledRef.current && latest().isOpen === undefined) {
+        wasSuppressedRef.current = true;
+        latest().dropHold();
+        latest().hideNow();
+      }
+    };
+    detachTriggerRef.current = detach;
+    return detach;
+  }, []);
 
   // Combined ref - shorthand for calling both positionRef and interactionRef
-  const ref: RefCallback<HTMLElement> = useCallback(
+  const ref = useCallback(
     (el: HTMLElement | null) => {
       layerRef(el);
-      interactionRef(el);
+      const detachInteraction = interactionRef(el);
+      if (el == null) {
+        return;
+      }
+      return () => {
+        detachInteraction?.();
+        layerRef(null);
+      };
     },
     [layerRef, interactionRef],
   );