Exports Tooltip event handler utils

.changeset/tooltip-named-export.md

@@ -0,0 +1,5 @@
+---
+'@leafygreen-ui/tooltip': minor
+---
+
+Exports `Tooltip` as a named export (as well as default)

.changeset/tooltip-trigger-handlers.md

@@ -0,0 +1,27 @@
+---
+'@leafygreen-ui/tooltip': minor
+---
+
+Exports `useTooltipTriggerEventHandlers` to enable handling external tooltip triggers.
+
+```tsx
+const [open, setOpen] = useState(false);
+const tooltipEventHandlers = useTooltipTriggerEventHandlers({
+  triggerEvent: TriggerEvent.Hover,
+  setState: setOpen,
+  onFocus: (e) => { console.log(e) } // side effects called on focus of the trigger
+});
+
+return (
+<>
+  <Button ref={triggerRef} {...tooltipEventHandlers}>
+    Button
+  </Button>
+  <Tooltip
+    refEl={triggerRef}
+    open={open}
+    setOpen={setOpen}
+  >Content</Tooltip>
+</>
+)
+```

packages/tooltip/README.md

@@ -78,3 +78,30 @@ import Tooltip from '@leafygreen-ui/tooltip';
 | `popoverZIndex`   | `number`                                  | Sets the z-index CSS property for the popover.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                             |
 | `baseFontSize`    | `13` \| `16`                              | font-size applied to typography element                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | default to value set by LeafyGreen Provider |
 | ...               | native `div` attributes                   | Any other props will be spread on the root `div` element                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                             |
+
+### External tooltip triggers
+
+When defining a tooltip trigger as a separate element, ensure the `refEl` is defined on the `<Tooltip>` element, and use the `useTooltipTriggerEventHandlers` hook to create tooltip event handlers.
+
+```tsx
+const triggerRef = useRef();
+const [open, setOpen] = useState(false);
+const tooltipEventHandlers = useTooltipTriggerEventHandlers({
+  triggerEvent: TriggerEvent.Hover,
+  setState: setOpen,
+  onFocus: e => {
+    console.log(e);
+  }, // side effects called on focus of the trigger
+});
+
+return (
+  <>
+    <Button ref={triggerRef} {...tooltipEventHandlers}>
+      Button
+    </Button>
+    <Tooltip refEl={triggerRef} open={open} setOpen={setOpen}>
+      Content
+    </Tooltip>
+  </>
+);
+```

packages/tooltip/src/Tooltip/Tooltip.tsx

@@ -5,8 +5,6 @@ import React, {
   useRef,
   useState,
 } from 'react';
-import { flushSync } from 'react-dom';
-import debounce from 'lodash/debounce';
 
 import { css, cx } from '@leafygreen-ui/emotion';
 import {
@@ -26,6 +24,7 @@ import {
 
 import SvgNotch from '../Notch';
 
+import { useTooltipTriggerEventHandlers } from './utils/useTooltipTriggerEventHandlers';
 import {
   baseStyles,
   baseTypeStyle,
@@ -40,7 +39,6 @@ import {
   TooltipProps,
   TriggerEvent,
 } from './Tooltip.types';
-import { hoverDelay } from './tooltipConstants';
 import { notchPositionStyles } from './tooltipUtils';
 
 const stopClickPropagation = (evt: React.MouseEvent) => {
@@ -111,7 +109,6 @@ function Tooltip({
   const setOpen =
     isControlled && controlledSetOpen ? controlledSetOpen : uncontrolledSetOpen;
 
-  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
   const tooltipRef = useRef<HTMLDivElement>(null);
 
   const existingId = id ?? tooltipRef.current?.id;
@@ -127,13 +124,8 @@ function Tooltip({
     }
   }, [trigger]);
 
-  useEffect(() => {
-    return () => {
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current);
-      }
-    };
-  }, [timeoutRef]);
+  const triggerComponent =
+    typeof trigger === 'function' ? trigger({}) : trigger;
 
   const handleClose = useCallback(() => {
     if (typeof shouldClose !== 'function' || shouldClose()) {
@@ -142,70 +134,20 @@ function Tooltip({
     }
   }, [setOpen, shouldClose, onClose]);
 
-  const createTriggerProps = useCallback(
-    (triggerEvent: TriggerEvent, triggerProps?: any) => {
-      switch (triggerEvent) {
-        case TriggerEvent.Hover:
-          return {
-            onMouseEnter: debounce((e: MouseEvent) => {
-              userTriggerHandler('onMouseEnter', e);
-              // Without this the tooltip sometimes opens without a transition. flushSync prevents this state update from automatically batching. Instead updates are made synchronously.
-              // https://react.dev/reference/react-dom/flushSync#flushing-updates-for-third-party-integrations
-              flushSync(() => {
-                timeoutRef.current = setTimeout(() => {
-                  setOpen(true);
-                }, hoverDelay);
-              });
-            }, 35),
-            onMouseLeave: debounce((e: MouseEvent) => {
-              userTriggerHandler('onMouseLeave', e);
-              if (timeoutRef.current) {
-                clearTimeout(timeoutRef.current);
-                timeoutRef.current = null;
-              }
-              handleClose();
-            }, 35),
-            onFocus: (e: MouseEvent) => {
-              userTriggerHandler('onFocus', e);
-              setOpen(true);
-            },
-            onBlur: (e: MouseEvent) => {
-              userTriggerHandler('onBlur', e);
-              handleClose();
-            },
-          };
-        case TriggerEvent.Click:
-        default:
-          return {
-            onClick: (e: MouseEvent) => {
-              // ensure that we don't close the tooltip when content inside tooltip is clicked
-              if (e.target !== tooltipRef.current) {
-                userTriggerHandler('onClick', e);
-                setOpen((curr: boolean) => !curr);
-              }
-            },
-          };
-      }
-
-      function userTriggerHandler(handler: string, e: MouseEvent): void {
-        // call any click handlers already on the trigger
-        if (
-          triggerProps &&
-          triggerProps[handler] &&
-          typeof triggerProps[handler] == 'function'
-        )
-          triggerProps[handler](e);
-      }
-    },
-    [handleClose, setOpen, tooltipRef],
-  );
-
   useEscapeKey(handleClose, { enabled: open });
 
   useBackdropClick(handleClose, [tooltipRef], {
     enabled: open && triggerEvent === 'click',
   });
 
+  const triggerEventHandlers = useTooltipTriggerEventHandlers({
+    setState: setOpen,
+    triggerEvent,
+    tooltipRef,
+    isEnabled: enabled,
+    ...triggerComponent?.props,
+  });
+
   const popoverProps = {
     popoverZIndex,
     refEl,
@@ -291,20 +233,17 @@ function Tooltip({
     </Popover>
   );
 
-  if (trigger) {
-    const originalTrigger =
-      typeof trigger === 'function' ? trigger({}) : trigger;
-
-    return React.cloneElement(originalTrigger, {
-      ...createTriggerProps(triggerEvent, originalTrigger.props),
+  if (triggerComponent) {
+    return React.cloneElement(triggerComponent, {
+      ...triggerEventHandlers,
       'aria-describedby': active ? tooltipId : undefined,
       children: (
         <>
-          {originalTrigger.props.children}
+          {triggerComponent.props.children}
           {tooltip}
         </>
       ),
-      className: cx(positionRelative, originalTrigger.props.className),
+      className: cx(positionRelative, triggerComponent.props.className),
     });
   }
 

packages/tooltip/src/Tooltip/index.ts

@@ -7,12 +7,12 @@ import {
   type TooltipProps,
   TriggerEvent,
 } from './Tooltip.types';
-import { hoverDelay } from './tooltipConstants';
+import { DEFAULT_HOVER_DELAY } from './tooltipConstants';
 
 export {
   Align,
   DismissMode,
-  hoverDelay,
+  DEFAULT_HOVER_DELAY as hoverDelay,
   Justify,
   RenderMode,
   type TooltipProps,

packages/tooltip/src/Tooltip/tooltipConstants.ts

@@ -3,4 +3,6 @@ import { transitionDuration } from '@leafygreen-ui/tokens';
 export const notchHeight = 8;
 export const notchWidth = 26;
 export const borderRadius = 16;
-export const hoverDelay = transitionDuration.slowest;
+
+export const DEFAULT_HOVER_DELAY = transitionDuration.slowest;
+export const CALLBACK_DEBOUNCE = 35; // ms

packages/tooltip/src/Tooltip/utils/tooltipHandlers.types.ts

@@ -0,0 +1,95 @@
+import { FocusEventHandler, MouseEventHandler, RefObject } from 'react';
+
+import type { TriggerEvent } from '../Tooltip.types';
+
+export interface UseTooltipEventsBaseArgs {
+  /**
+   *  The `useState` dispatch method to toggle the tooltip state
+   */
+  setState: React.Dispatch<React.SetStateAction<boolean>>;
+
+  /**
+   * Whether the tooltip event handlers should be enabled
+   */
+  isEnabled?: boolean;
+
+  /**
+   * The delay in milliseconds before the tooltip opens on hover.
+   */
+  delay?: number;
+}
+
+export interface CreateTooltipEventsArgsHover {
+  /**
+   * Whether the tooltip will open/close on `hover` or `click` events.
+   * Note: must match the value passed onto `tooltip`
+   */
+  triggerEvent: typeof TriggerEvent.Hover;
+
+  /**
+   * A ref to the Tooltip element.
+   * Optional when the trigger event is `hover`
+   */
+  tooltipRef?: RefObject<HTMLElement>;
+
+  /** Additional side effects to run on this event */
+  onMouseEnter?: MouseEventHandler<HTMLElement>;
+
+  /** Additional side effects to run on this event */
+  onMouseLeave?: MouseEventHandler<HTMLElement>;
+
+  /** Additional side effects to run on this event */
+  onFocus?: FocusEventHandler<HTMLElement>;
+
+  /** Additional side effects to run on this event */
+  onBlur?: FocusEventHandler<HTMLElement>;
+}
+
+export interface CreateTooltipEventsArgsClick {
+  /**
+   * Whether the tooltip will open/close on `hover` or `click` events.
+   * Note: must match the value passed onto `tooltip`
+   */
+  triggerEvent: typeof TriggerEvent.Click;
+
+  /**
+   * A ref to the Tooltip element.
+   * Optional when the trigger event is `hover`
+   */
+  tooltipRef: RefObject<HTMLElement>;
+
+  /**
+   * Additional side effects to run on this event
+   */
+  onClick?: MouseEventHandler<HTMLElement>;
+}
+
+export type CreateTooltipEventsArgs<Trigger extends TriggerEvent> =
+  UseTooltipEventsBaseArgs &
+    (Trigger extends 'hover'
+      ? CreateTooltipEventsArgsHover
+      : Trigger extends 'click'
+      ? CreateTooltipEventsArgsClick
+      : never);
+
+export interface TooltipHoverEvents {
+  onMouseEnter: MouseEventHandler<HTMLElement>;
+  onMouseLeave: MouseEventHandler<HTMLElement>;
+  onFocus: FocusEventHandler<HTMLElement>;
+  onBlur: FocusEventHandler<HTMLElement>;
+  onClick: undefined;
+}
+export interface TooltipClickEvents {
+  onClick: MouseEventHandler<HTMLElement>;
+  onMouseEnter: undefined;
+  onMouseLeave: undefined;
+  onFocus: undefined;
+  onBlur: undefined;
+}
+
+export type TooltipEventHandlers<Trigger extends TriggerEvent> =
+  Trigger extends 'hover'
+    ? TooltipHoverEvents
+    : Trigger extends 'click'
+    ? TooltipClickEvents
+    : never;