Initial Tooltip update to support hybrid (un)controlled state

Author: aaronccasanova

polaris-react/src/components/Tooltip/Tooltip.tsx

@@ -7,7 +7,6 @@ import type {
 import {Portal} from '../Portal';
 import {useEphemeralPresenceManager} from '../../utilities/ephemeral-presence-manager';
 import {findFirstFocusableNode} from '../../utilities/focus';
-import {useToggle} from '../../utilities/use-toggle';
 import {classNames} from '../../utilities/css';
 
 import {TooltipOverlay} from './components';
@@ -81,7 +80,7 @@ export function Tooltip({
   children,
   content,
   dismissOnMouseOut,
-  open,
+  open: openProp,
   defaultOpen: defaultOpenProp,
   active: originalActive,
   hoverDelay,
@@ -93,149 +92,148 @@ export function Tooltip({
   borderRadius: borderRadiusProp,
   zIndexOverride,
   hasUnderline,
-  persistOnClick,
+  persistOnClick = false,
   onOpen,
   onClose,
 }: TooltipProps) {
   const borderRadius = borderRadiusProp || '200';
-
-  const WrapperComponent: any = activatorWrapper;
-  const defaultOpen = defaultOpenProp ?? originalActive;
-  const {
-    value: active,
-    setTrue: setActiveTrue,
-    setFalse: handleBlur,
-  } = useToggle(Boolean(defaultOpen));
-
-  const {value: persist, toggle: togglePersisting} = useToggle(
-    Boolean(defaultOpen) && Boolean(persistOnClick),
+  const isControlled = typeof openProp === 'boolean';
+  const defaultOpen = defaultOpenProp ?? originalActive ?? false;
+  const [open, setOpen] = useState(defaultOpen);
+  const [isPersisting, setIsPersisting] = useState(
+    defaultOpen && persistOnClick,
   );
+  const [shouldAnimate, setShouldAnimate] = useState(!defaultOpen);
 
-  const [activatorNode, setActivatorNode] = useState<HTMLElement | null>(null);
-  const {presenceList, addPresence, removePresence} =
-    useEphemeralPresenceManager();
-
-  const id = useId();
-  const activatorContainer = useRef<HTMLElement>(null);
-  const mouseEntered = useRef(false);
-  const [shouldAnimate, setShouldAnimate] = useState(Boolean(!defaultOpen));
+  const isMouseEntered = useRef(false);
   const hoverDelayTimeout = useRef<NodeJS.Timeout | null>(null);
   const hoverOutTimeout = useRef<NodeJS.Timeout | null>(null);
 
-  const handleFocus = useCallback(() => {
-    if (originalActive === false) return;
-
-    setActiveTrue();
-  }, [originalActive, setActiveTrue]);
-
-  useEffect(() => {
-    const firstFocusable = activatorContainer.current
-      ? findFirstFocusableNode(activatorContainer.current)
-      : null;
-    const accessibilityNode = firstFocusable || activatorContainer.current;
+  const id = useId();
+  const WrapperComponent: any = activatorWrapper;
+  const activatorContainer = useRef<HTMLElement>(null);
+  const [activatorNode, setActivatorNode] = useState<HTMLElement | null>(null);
+  const wrapperClassNames = classNames(
+    WrapperComponent === 'div' && styles.TooltipContainer,
+    hasUnderline && styles.HasUnderline,
+  );
 
-    if (!accessibilityNode) return;
+  const {presenceList, addPresence, removePresence} =
+    useEphemeralPresenceManager();
 
-    accessibilityNode.tabIndex = 0;
-    accessibilityNode.setAttribute('aria-describedby', id);
-    accessibilityNode.setAttribute('data-polaris-tooltip-activator', 'true');
-  }, [id, children]);
+  const clearHoverDelayTimeout = useCallback(() => {
+    if (hoverDelayTimeout.current) {
+      clearTimeout(hoverDelayTimeout.current);
+      hoverDelayTimeout.current = null;
+    }
+  }, []);
 
-  useEffect(() => {
-    return () => {
-      if (hoverDelayTimeout.current) {
-        clearTimeout(hoverDelayTimeout.current);
-      }
-      if (hoverOutTimeout.current) {
-        clearTimeout(hoverOutTimeout.current);
-      }
-    };
+  const clearHoverOutTimeout = useCallback(() => {
+    if (hoverOutTimeout.current) {
+      clearTimeout(hoverOutTimeout.current);
+      hoverOutTimeout.current = null;
+    }
   }, []);
 
   const handleOpen = useCallback(() => {
-    setShouldAnimate(!presenceList.tooltip && !active);
+    if (open) return;
+
+    if (!isControlled && originalActive !== false) {
+      setShouldAnimate(!open && !presenceList.tooltip);
+      setOpen(true);
+      addPresence('tooltip');
+    }
+
     onOpen?.();
-    addPresence('tooltip');
-  }, [addPresence, presenceList.tooltip, onOpen, active]);
+  }, [
+    addPresence,
+    isControlled,
+    onOpen,
+    open,
+    originalActive,
+    presenceList.tooltip,
+  ]);
 
   const handleClose = useCallback(() => {
+    if (!open) return;
+
+    if (!isControlled) {
+      setOpen(false);
+      removePresence('tooltip');
+    }
+
     onClose?.();
-    setShouldAnimate(false);
+  }, [isControlled, open, onClose, removePresence]);
+
+  const handleMouseEnter = useCallback(() => {
+    // https://github.com/facebook/react/issues/10109
+    // Mouseenter event not triggered when cursor moves from disabled button
+    if (isMouseEntered.current) return;
+    isMouseEntered.current = true;
+
+    clearHoverOutTimeout();
+
+    if (open) return;
+
+    if (hoverDelay && !presenceList.tooltip) {
+      hoverDelayTimeout.current = setTimeout(() => {
+        handleOpen();
+      }, hoverDelay);
+    } else {
+      handleOpen();
+    }
+  }, [
+    clearHoverOutTimeout,
+    handleOpen,
+    hoverDelay,
+    open,
+    presenceList.tooltip,
+  ]);
+
+  const handleMouseLeave = useCallback(() => {
+    isMouseEntered.current = false;
+
+    clearHoverDelayTimeout();
+
+    if (isPersisting) return;
+
     hoverOutTimeout.current = setTimeout(() => {
-      removePresence('tooltip');
+      handleClose();
     }, HOVER_OUT_TIMEOUT);
-  }, [removePresence, onClose]);
+  }, [clearHoverDelayTimeout, handleClose, isPersisting]);
+
+  const handleFocus = useCallback(() => {
+    if (open) return;
+
+    clearHoverDelayTimeout();
+
+    handleOpen();
+  }, [clearHoverDelayTimeout, handleOpen, open]);
+
+  const handleBlur = useCallback(() => {
+    if (isPersisting) setIsPersisting(false);
+
+    handleClose();
+  }, [handleClose, isPersisting, setIsPersisting]);
 
   const handleKeyUp = useCallback(
     (event: React.KeyboardEvent) => {
       if (event.key !== 'Escape') return;
-      handleClose?.();
-      handleBlur();
-      persistOnClick && togglePersisting();
-    },
-    [handleBlur, handleClose, persistOnClick, togglePersisting],
-  );
 
-  useEffect(() => {
-    if (originalActive === false && active) {
-      handleClose();
-      handleBlur();
-    }
-  }, [originalActive, active, handleClose, handleBlur]);
-
-  const portal = activatorNode ? (
-    <Portal idPrefix="tooltip">
-      <TooltipOverlay
-        id={id}
-        preferredPosition={preferredPosition}
-        activator={activatorNode}
-        active={open ?? active}
-        accessibilityLabel={accessibilityLabel}
-        onClose={noop}
-        preventInteraction={dismissOnMouseOut}
-        width={width}
-        padding={padding}
-        borderRadius={borderRadius}
-        zIndexOverride={zIndexOverride}
-        instant={!shouldAnimate}
-      >
-        {content}
-      </TooltipOverlay>
-    </Portal>
-  ) : null;
+      if (isPersisting) setIsPersisting(false);
 
-  const wrapperClassNames = classNames(
-    activatorWrapper === 'div' && styles.TooltipContainer,
-    hasUnderline && styles.HasUnderline,
+      handleClose();
+    },
+    [handleClose, isPersisting, setIsPersisting],
   );
 
-  return (
-    <WrapperComponent
-      onFocus={() => {
-        handleOpen();
-        handleFocus();
-      }}
-      onBlur={() => {
-        handleClose();
-        handleBlur();
-
-        if (persistOnClick) {
-          togglePersisting();
-        }
-      }}
-      onMouseLeave={handleMouseLeave}
-      onMouseOver={handleMouseEnterFix}
-      onMouseDown={persistOnClick ? togglePersisting : undefined}
-      ref={setActivator}
-      onKeyUp={handleKeyUp}
-      className={wrapperClassNames}
-    >
-      {children}
-      {portal}
-    </WrapperComponent>
-  );
+  const handleMouseDown = useCallback(() => {
+    if (!open) return;
 
-  function setActivator(node: HTMLElement | null) {
+    setIsPersisting((prevIsPersisting) => !prevIsPersisting);
+  }, [open, setIsPersisting]);
+
+  const setActivator = useCallback((node: HTMLElement | null) => {
     const activatorContainerRef: any = activatorContainer;
     if (node == null) {
       activatorContainerRef.current = null;
@@ -247,40 +245,92 @@ export function Tooltip({
       setActivatorNode(node.firstElementChild);
 
     activatorContainerRef.current = node;
-  }
+  }, []);
 
-  function handleMouseEnter() {
-    mouseEntered.current = true;
-    if (hoverDelay && !presenceList.tooltip) {
-      hoverDelayTimeout.current = setTimeout(() => {
-        handleOpen();
-        handleFocus();
-      }, hoverDelay);
+  // Sync controlled state with uncontrolled state
+  useEffect(() => {
+    if (!isControlled || openProp === open) return;
+
+    clearHoverDelayTimeout();
+    clearHoverOutTimeout();
+
+    if (openProp) {
+      setShouldAnimate(!open && !presenceList.tooltip);
+      setOpen(true);
+      addPresence('tooltip');
     } else {
-      handleOpen();
-      handleFocus();
+      setShouldAnimate(false);
+      setOpen(false);
+      removePresence('tooltip');
     }
-  }
+  }, [
+    addPresence,
+    clearHoverDelayTimeout,
+    clearHoverOutTimeout,
+    isControlled,
+    open,
+    openProp,
+    presenceList.tooltip,
+    removePresence,
+  ]);
+
+  // Clear timeouts on unmount
+  useEffect(
+    () => () => {
+      clearHoverDelayTimeout();
+      clearHoverOutTimeout();
+    },
+    [clearHoverDelayTimeout, clearHoverOutTimeout],
+  );
 
-  function handleMouseLeave() {
-    if (hoverDelayTimeout.current) {
-      clearTimeout(hoverDelayTimeout.current);
-      hoverDelayTimeout.current = null;
-    }
+  // Add `tabIndex` and other a11y attributes to the first focusable node
+  useEffect(() => {
+    const firstFocusable = activatorContainer.current
+      ? findFirstFocusableNode(activatorContainer.current)
+      : null;
+    const accessibilityNode = firstFocusable || activatorContainer.current;
 
-    mouseEntered.current = false;
-    handleClose();
+    if (!accessibilityNode) return;
 
-    if (!persist) {
-      handleBlur();
-    }
-  }
+    accessibilityNode.tabIndex = 0;
+    accessibilityNode.setAttribute('aria-describedby', id);
+    accessibilityNode.setAttribute('data-polaris-tooltip-activator', 'true');
+  }, [id, children]);
 
-  // https://github.com/facebook/react/issues/10109
-  // Mouseenter event not triggered when cursor moves from disabled button
-  function handleMouseEnterFix() {
-    !mouseEntered.current && handleMouseEnter();
-  }
+  return (
+    <WrapperComponent
+      ref={setActivator}
+      className={wrapperClassNames}
+      onFocus={handleFocus}
+      onBlur={handleBlur}
+      onMouseOver={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+      onMouseDown={handleMouseDown}
+      onKeyUp={handleKeyUp}
+    >
+      {children}
+      {activatorNode && (
+        <Portal idPrefix="tooltip">
+          <TooltipOverlay
+            id={id}
+            preferredPosition={preferredPosition}
+            activator={activatorNode}
+            active={open}
+            accessibilityLabel={accessibilityLabel}
+            onClose={noop}
+            preventInteraction={dismissOnMouseOut}
+            width={width}
+            padding={padding}
+            borderRadius={borderRadius}
+            zIndexOverride={zIndexOverride}
+            instant={!shouldAnimate}
+          >
+            {content}
+          </TooltipOverlay>
+        </Portal>
+      )}
+    </WrapperComponent>
+  );
 }
 
 function noop() {}