trackCursorAxis, extend useTooltipRoot

mui · Sep 13, 2024 · d398556 · d398556
1 parent fb9d0e2
commit d398556
Show file tree

Hide file tree

Showing 6 changed files with 43 additions and 92 deletions.
diff --git a/docs/data/api/tooltip-root.json b/docs/data/api/tooltip-root.json
@@ -2,22 +2,22 @@
   "props": {
     "animated": { "type": { "name": "bool" }, "default": "true" },
     "closeDelay": { "type": { "name": "number" }, "default": "0" },
-    "defaultOpen": { "type": { "name": "bool" } },
+    "defaultOpen": { "type": { "name": "bool" }, "default": "false" },
     "delay": { "type": { "name": "number" }, "default": "600" },
     "delayType": {
       "type": { "name": "enum", "description": "'hover'<br>&#124;&nbsp;'rest'" },
       "default": "'rest'"
     },
-    "followCursorAxis": {
+    "hoverable": { "type": { "name": "bool" }, "default": "true" },
+    "onOpenChange": { "type": { "name": "func" } },
+    "open": { "type": { "name": "bool" }, "default": "false" },
+    "trackCursorAxis": {
       "type": {
         "name": "enum",
         "description": "'both'<br>&#124;&nbsp;'none'<br>&#124;&nbsp;'x'<br>&#124;&nbsp;'y'"
       },
       "default": "'none'"
-    },
-    "hoverable": { "type": { "name": "bool" }, "default": "true" },
-    "onOpenChange": { "type": { "name": "func" } },
-    "open": { "type": { "name": "bool" } }
+    }
   },
   "name": "TooltipRoot",
   "imports": [

diff --git a/docs/data/translations/api-docs/tooltip-root/tooltip-root.json b/docs/data/translations/api-docs/tooltip-root/tooltip-root.json
@@ -6,23 +6,21 @@
     },
     "closeDelay": { "description": "The delay in milliseconds until the tooltip popup is closed." },
     "defaultOpen": {
-      "description": "Specifies whether the tooltip is open initially when uncontrolled."
+      "description": "Whether the tooltip popup is open by default. Use when uncontrolled."
     },
     "delay": { "description": "The delay in milliseconds until the tooltip popup is opened." },
     "delayType": {
       "description": "The delay type to use. <code>rest</code> means the <code>delay</code> represents how long the user&#39;s cursor must rest on the trigger before the tooltip popup is opened. <code>hover</code> means the <code>delay</code> represents how long to wait as soon as the user&#39;s cursor has entered the trigger."
     },
-    "followCursorAxis": {
-      "description": "Determines which axis the tooltip should follow the cursor on."
-    },
     "hoverable": {
-      "description": "Whether the user can move their cursor from the trigger to the tooltip popup without it closing."
+      "description": "Whether the can move their cursor from the trigger element toward the tooltip popup element without it closing using a &quot;safe polygon&quot; technique."
     },
     "onOpenChange": {
-      "description": "Callback fired when the tooltip popup is requested to be opened or closed. Use when controlled."
+      "description": "Callback fired when the tooltip popup is requested to be opened or closed."
     },
-    "open": {
-      "description": "If <code>true</code>, the tooltip popup is open. Use when controlled."
+    "open": { "description": "Whether the tooltip popup is open. Use when controlled." },
+    "trackCursorAxis": {
+      "description": "Determines which axis the tooltip should track the cursor on."
     }
   },
   "classDescriptions": {}

diff --git a/packages/mui-base/src/Tooltip/Positioner/useTooltipPositioner.ts b/packages/mui-base/src/Tooltip/Positioner/useTooltipPositioner.ts
@@ -7,7 +7,7 @@ import type { GenericHTMLProps } from '../../utils/types';
 export function useTooltipPositioner(
   params: useTooltipPositioner.Parameters,
 ): useTooltipPositioner.ReturnValue {
-  const { open = false, keepMounted = false, followCursorAxis = 'none' } = params;
+  const { open = false, keepMounted = false, trackCursorAxis = 'none' } = params;
 
   const {
     positionerStyles,
@@ -28,7 +28,7 @@ export function useTooltipPositioner(
           hiddenStyles.pointerEvents = 'none';
         }
 
-        if (followCursorAxis === 'both') {
+        if (trackCursorAxis === 'both') {
           hiddenStyles.pointerEvents = 'none';
         }
 
@@ -43,7 +43,7 @@ export function useTooltipPositioner(
           },
         });
       },
-      [positionerStyles, hidden, followCursorAxis, open, keepMounted],
+      [positionerStyles, hidden, trackCursorAxis, open, keepMounted],
     );
 
   return React.useMemo(
@@ -145,10 +145,10 @@ export namespace useTooltipPositioner {
      */
     floatingRootContext?: FloatingRootContext;
     /**
-     * Determines which axis the tooltip should follow the cursor on.
+     * Determines which axis the tooltip should track the cursor on.
      * @default 'none'
      */
-    followCursorAxis?: 'none' | 'x' | 'y' | 'both';
+    trackCursorAxis?: 'none' | 'x' | 'y' | 'both';
   }
 
   export interface ReturnValue {

diff --git a/packages/mui-base/src/Tooltip/Root/TooltipRoot.tsx b/packages/mui-base/src/Tooltip/Root/TooltipRoot.tsx
@@ -1,7 +1,6 @@
 'use client';
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { OpenChangeReason } from '@floating-ui/react';
 import { TooltipRootContext } from './TooltipRootContext';
 import { useTooltipRoot } from './useTooltipRoot';
 import { OPEN_DELAY } from '../utils/constants';
@@ -24,7 +23,7 @@ function TooltipRoot(props: TooltipRoot.Props) {
     closeDelay,
     hoverable = true,
     animated = true,
-    followCursorAxis = 'none',
+    trackCursorAxis = 'none',
   } = props;
 
   const delayWithDefault = delay ?? OPEN_DELAY;
@@ -48,7 +47,7 @@ function TooltipRoot(props: TooltipRoot.Props) {
   } = useTooltipRoot({
     hoverable,
     animated,
-    followCursorAxis,
+    trackCursorAxis,
     delay,
     delayType,
     closeDelay,
@@ -75,7 +74,7 @@ function TooltipRoot(props: TooltipRoot.Props) {
       getRootTriggerProps,
       getRootPopupProps,
       floatingRootContext,
-      followCursorAxis,
+      trackCursorAxis,
       transitionStatus,
     }),
     [
@@ -95,7 +94,7 @@ function TooltipRoot(props: TooltipRoot.Props) {
       getRootTriggerProps,
       getRootPopupProps,
       floatingRootContext,
-      followCursorAxis,
+      trackCursorAxis,
       transitionStatus,
     ],
   );
@@ -107,55 +106,8 @@ function TooltipRoot(props: TooltipRoot.Props) {
 
 namespace TooltipRoot {
   export interface OwnerState {}
-  export interface Props {
-    children: React.ReactNode;
-    /**
-     * If `true`, the tooltip popup is open. Use when controlled.
-     */
-    open?: boolean;
-    /**
-     * Callback fired when the tooltip popup is requested to be opened or closed. Use when
-     * controlled.
-     */
-    onOpenChange?: (isOpen: boolean, event?: Event, reason?: OpenChangeReason) => void;
-    /**
-     * Specifies whether the tooltip is open initially when uncontrolled.
-     */
-    defaultOpen?: boolean;
-    /**
-     * The delay in milliseconds until the tooltip popup is opened.
-     * @default 600
-     */
-    delay?: number;
-    /**
-     * The delay in milliseconds until the tooltip popup is closed.
-     * @default 0
-     */
-    closeDelay?: number;
-    /**
-     * The delay type to use. `rest` means the `delay` represents how long the user's cursor must
-     * rest on the trigger before the tooltip popup is opened. `hover` means the `delay` represents
-     * how long to wait as soon as the user's cursor has entered the trigger.
-     * @default 'rest'
-     */
-    delayType?: 'rest' | 'hover';
-    /**
-     * Whether the user can move their cursor from the trigger to the tooltip popup without it
-     * closing.
-     * @default true
-     */
-    hoverable?: boolean;
-    /**
-     * Whether the tooltip can animate, adding animation-related attributes and allowing for exit
-     * animations to play. Useful to disable in tests to remove async behavior.
-     * @default true
-     */
-    animated?: boolean;
-    /**
-     * Determines which axis the tooltip should follow the cursor on.
-     * @default 'none'
-     */
-    followCursorAxis?: 'none' | 'x' | 'y' | 'both';
+  export interface Props extends useTooltipRoot.Parameters {
+    children?: React.ReactNode;
   }
 }
 
@@ -180,7 +132,8 @@ TooltipRoot.propTypes /* remove-proptypes */ = {
    */
   closeDelay: PropTypes.number,
   /**
-   * Specifies whether the tooltip is open initially when uncontrolled.
+   * Whether the tooltip popup is open by default. Use when uncontrolled.
+   * @default false
    */
   defaultOpen: PropTypes.bool,
   /**
@@ -196,25 +149,25 @@ TooltipRoot.propTypes /* remove-proptypes */ = {
    */
   delayType: PropTypes.oneOf(['hover', 'rest']),
   /**
-   * Determines which axis the tooltip should follow the cursor on.
-   * @default 'none'
-   */
-  followCursorAxis: PropTypes.oneOf(['both', 'none', 'x', 'y']),
-  /**
-   * Whether the user can move their cursor from the trigger to the tooltip popup without it
-   * closing.
+   * Whether the can move their cursor from the trigger element toward the tooltip popup element
+   * without it closing using a "safe polygon" technique.
    * @default true
    */
   hoverable: PropTypes.bool,
   /**
-   * Callback fired when the tooltip popup is requested to be opened or closed. Use when
-   * controlled.
+   * Callback fired when the tooltip popup is requested to be opened or closed.
    */
   onOpenChange: PropTypes.func,
   /**
-   * If `true`, the tooltip popup is open. Use when controlled.
+   * Whether the tooltip popup is open. Use when controlled.
+   * @default false
    */
   open: PropTypes.bool,
+  /**
+   * Determines which axis the tooltip should track the cursor on.
+   * @default 'none'
+   */
+  trackCursorAxis: PropTypes.oneOf(['both', 'none', 'x', 'y']),
 } as any;
 
 export { TooltipRoot };
diff --git a/packages/mui-base/src/Tooltip/Root/TooltipRootContext.ts b/packages/mui-base/src/Tooltip/Root/TooltipRootContext.ts
@@ -20,7 +20,7 @@ export interface TooltipRootContext {
   getRootPopupProps: (externalProps?: GenericHTMLProps) => GenericHTMLProps;
   instantType: 'delay' | 'dismiss' | 'focus' | undefined;
   floatingRootContext: FloatingRootContext;
-  followCursorAxis: 'none' | 'x' | 'y' | 'both';
+  trackCursorAxis: 'none' | 'x' | 'y' | 'both';
   transitionStatus: TransitionStatus;
 }
 

diff --git a/packages/mui-base/src/Tooltip/Root/useTooltipRoot.ts b/packages/mui-base/src/Tooltip/Root/useTooltipRoot.ts
@@ -29,7 +29,7 @@ export function useTooltipRoot(params: useTooltipRoot.Parameters): useTooltipRoo
     keepMounted = false,
     hoverable = true,
     animated = true,
-    followCursorAxis = 'none',
+    trackCursorAxis = 'none',
     delayType = 'rest',
     delay,
     closeDelay,
@@ -136,7 +136,7 @@ export function useTooltipRoot(params: useTooltipRoot.Parameters): useTooltipRoo
   const hover = useHover(context, {
     mouseOnly: true,
     move: false,
-    handleClose: hoverable && followCursorAxis !== 'both' ? safePolygon() : null,
+    handleClose: hoverable && trackCursorAxis !== 'both' ? safePolygon() : null,
     restMs: computedRestMs,
     delay: {
       open: computedOpenDelay,
@@ -146,8 +146,8 @@ export function useTooltipRoot(params: useTooltipRoot.Parameters): useTooltipRoo
   const focus = useFocus(context);
   const dismiss = useDismiss(context, { referencePress: true });
   const clientPoint = useClientPoint(context, {
-    enabled: followCursorAxis !== 'none',
-    axis: followCursorAxis === 'none' ? undefined : followCursorAxis,
+    enabled: trackCursorAxis !== 'none',
+    axis: trackCursorAxis === 'none' ? undefined : trackCursorAxis,
   });
 
   const { getReferenceProps: getRootTriggerProps, getFloatingProps: getRootPopupProps } =
@@ -186,7 +186,7 @@ export function useTooltipRoot(params: useTooltipRoot.Parameters): useTooltipRoo
   );
 }
 
-namespace useTooltipRoot {
+export namespace useTooltipRoot {
   export interface Parameters {
     /**
      * Whether the tooltip popup is open by default. Use when uncontrolled.
@@ -215,10 +215,10 @@ namespace useTooltipRoot {
      */
     animated?: boolean;
     /**
-     * Determines which axis the tooltip should follow the cursor on.
+     * Determines which axis the tooltip should track the cursor on.
      * @default 'none'
      */
-    followCursorAxis?: 'none' | 'x' | 'y' | 'both';
+    trackCursorAxis?: 'none' | 'x' | 'y' | 'both';
     /**
      * The delay in milliseconds until the tooltip popup is opened.
      * @default 600