@atlaskit/tooltip 18.8.5 → 18.9.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @atlaskit/tooltip
 
+## 18.9.1
+
+### Patch Changes
+
+- [#164322](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/164322)
+  [`e9317ed13ba40`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/e9317ed13ba40) -
+  Internal refactors to state to reduce the number of JavaScript event listeners.
+
+## 18.9.0
+
+### Minor Changes
+
+- [`be6f923511512`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/be6f923511512) - -
+  Added new prop: `canAppear`, which can be used to _conditionally_ show tooltips.
+  - Added new prop: `isScreenReaderAnnouncementDisabled` which can be used to disable hidden text
+    for tooltips. This is useful when the Tooltip `content` matches the Tooltip trigger content as
+    hidden text is not required.
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 18.8.5
 
 ### Patch Changes

package/dist/cjs/tooltip.js

@@ -14,6 +14,7 @@ var _bindEventListener = require("bind-event-listener");
 var _analyticsNext = require("@atlaskit/analytics-next");
 var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
 var _useCloseOnEscapePress = _interopRequireDefault(require("@atlaskit/ds-lib/use-close-on-escape-press"));
+var _useStableRef = _interopRequireDefault(require("@atlaskit/ds-lib/use-stable-ref"));
 var _openLayerObserver = require("@atlaskit/layering/experimental/open-layer-observer");
 var _motion = require("@atlaskit/motion");
 var _durations = require("@atlaskit/motion/durations");
@@ -33,7 +34,7 @@ var tooltipZIndex = _constants.layers.tooltip();
 var analyticsAttributes = {
   componentName: 'tooltip',
   packageName: "@atlaskit/tooltip",
-  packageVersion: "18.8.5"
+  packageVersion: "18.9.1"
 };
 
 // Inverts motion direction
@@ -78,6 +79,7 @@ function Tooltip(_ref) {
     onShow = _ref$onShow === void 0 ? _noop.default : _ref$onShow,
     _ref$onHide = _ref.onHide,
     onHide = _ref$onHide === void 0 ? _noop.default : _ref$onHide,
+    canAppear = _ref.canAppear,
     _ref$hideTooltipOnCli = _ref.hideTooltipOnClick,
     hideTooltipOnClick = _ref$hideTooltipOnCli === void 0 ? false : _ref$hideTooltipOnCli,
     _ref$hideTooltipOnMou = _ref.hideTooltipOnMouseDown,
@@ -86,7 +88,9 @@ function Tooltip(_ref) {
     _ref$strategy = _ref.strategy,
     strategy = _ref$strategy === void 0 ? 'fixed' : _ref$strategy,
     _ref$ignoreTooltipPoi = _ref.ignoreTooltipPointerEvents,
-    ignoreTooltipPointerEvents = _ref$ignoreTooltipPoi === void 0 ? false : _ref$ignoreTooltipPoi;
+    ignoreTooltipPointerEvents = _ref$ignoreTooltipPoi === void 0 ? false : _ref$ignoreTooltipPoi,
+    _ref$isScreenReaderAn = _ref.isScreenReaderAnnouncementDisabled,
+    isScreenReaderAnnouncementDisabled = _ref$isScreenReaderAn === void 0 ? false : _ref$isScreenReaderAn;
   var tooltipPosition = position === 'mouse' ? mousePosition : position;
   var onShowHandler = (0, _analyticsNext.usePlatformLeafSyntheticEventHandler)(_objectSpread({
     fn: onShow,
@@ -119,21 +123,15 @@ function Tooltip(_ref) {
   }, []);
 
   // Putting a few things into refs so that we don't have to break memoization
-  var lastState = (0, _react.useRef)(state);
-  var lastDelay = (0, _react.useRef)(delay);
-  var lastHandlers = (0, _react.useRef)({
-    onShowHandler: onShowHandler,
-    onHideHandler: onHideHandler
-  });
+  var stableState = (0, _useStableRef.default)(state);
+  // These props are placed in separate refs instead of a single object to reduce memory usage.
+  // Placing them in the same object previously caused an increase in the number of JavaScript event listeners
+  // before garbage collection.
+  var onShowHandlerStable = (0, _useStableRef.default)(onShowHandler);
+  var onHideHandlerStable = (0, _useStableRef.default)(onHideHandler);
+  var delayStable = (0, _useStableRef.default)(delay);
+  var canAppearStable = (0, _useStableRef.default)(canAppear);
   var hasCalledShowHandler = (0, _react.useRef)(false);
-  (0, _react.useEffect)(function () {
-    lastState.current = state;
-    lastDelay.current = delay;
-    lastHandlers.current = {
-      onShowHandler: onShowHandler,
-      onHideHandler: onHideHandler
-    };
-  }, [delay, onHideHandler, onShowHandler, state]);
   var start = (0, _react.useCallback)(function (api) {
     // @ts-ignore
     apiRef.current = api;
@@ -145,7 +143,7 @@ function Tooltip(_ref) {
     }
     // Only call onHideHandler if we have called onShowHandler
     if (hasCalledShowHandler.current) {
-      lastHandlers.current.onHideHandler();
+      onHideHandlerStable.current();
     }
     // @ts-ignore
     apiRef.current = null;
@@ -153,7 +151,7 @@ function Tooltip(_ref) {
     hasCalledShowHandler.current = false;
     // just in case
     setState('hide');
-  }, []);
+  }, [onHideHandlerStable]);
   var abort = (0, _react.useCallback)(function () {
     if (!apiRef.current) {
       return;
@@ -161,11 +159,11 @@ function Tooltip(_ref) {
     apiRef.current.abort();
     // Only call onHideHandler if we have called onShowHandler
     if (hasCalledShowHandler.current) {
-      lastHandlers.current.onHideHandler();
+      onHideHandlerStable.current();
     }
     // @ts-ignore
     apiRef.current = null;
-  }, []);
+  }, [onHideHandlerStable]);
   (0, _react.useEffect)(function mount() {
     return function unmount() {
       if (apiRef.current) {
@@ -196,7 +194,8 @@ function Tooltip(_ref) {
       }
     });
   }, []);
-  var showTooltip = (0, _react.useCallback)(function (source) {
+  var tryShowTooltip = (0, _react.useCallback)(function (source) {
+    var _canAppearStable$curr;
     /**
      * Prevent tooltips from being shown during a drag. This can occur with
      * the native drag and drop API, where some pointer events can fire
@@ -205,24 +204,45 @@ function Tooltip(_ref) {
     if (isDraggingRef.current) {
       return;
     }
+
+    // Another tooltip is has been active but we still have the old `api`
+    // around. We need to finish up the last usage.
+    // Note: just being safe - this should not happen
     if (apiRef.current && !apiRef.current.isActive()) {
       abort();
     }
 
-    // Tell the tooltip to keep showing
+    // This tooltip is already active, we can exit
     if (apiRef.current && apiRef.current.isActive()) {
       apiRef.current.keep();
       return;
     }
+
+    /**
+     * Check if tooltip is allowed to show.
+     *
+     * Once a tooltip has started, or has scheduled to start
+     * we won't be checking `canAppear` again.
+     *
+     * - We don't want tooltips to disappear once they are shown
+     * - For consistency, we start after a single positive `canAppear`.
+     *   Otherwise the amount of times we ask consumers would depend on
+     *   how many times we get a "mousemove", which _could_ lead to situations
+     *   where moving the mouse could result in a different outcome to if
+     *   the mouse was not moved.
+     */
+    if (canAppearStable.current && !((_canAppearStable$curr = canAppearStable.current) !== null && _canAppearStable$curr !== void 0 && _canAppearStable$curr.call(canAppearStable))) {
+      return;
+    }
     var entry = {
       source: source,
-      delay: lastDelay.current,
+      delay: delayStable.current,
       show: function show(_ref3) {
         var isImmediate = _ref3.isImmediate;
         // Call the onShow handler if it hasn't been called yet
         if (!hasCalledShowHandler.current) {
           hasCalledShowHandler.current = true;
-          lastHandlers.current.onShowHandler();
+          onShowHandlerStable.current();
         }
         setState(isImmediate ? 'show-immediate' : 'fade-in');
       },
@@ -238,7 +258,7 @@ function Tooltip(_ref) {
     };
     var api = (0, _tooltipManager.show)(entry);
     start(api);
-  }, [abort, done, start]);
+  }, [canAppearStable, delayStable, done, start, abort, onShowHandlerStable]);
   var hideTooltipOnEsc = (0, _react.useCallback)(function () {
     var _apiRef$current2;
     (_apiRef$current2 = apiRef.current) === null || _apiRef$current2 === void 0 || _apiRef$current2.requestHide({
@@ -314,8 +334,8 @@ function Tooltip(_ref) {
     } : {
       type: 'keyboard'
     };
-    showTooltip(source);
-  }, [position, showTooltip]);
+    tryShowTooltip(source);
+  }, [position, tryShowTooltip]);
 
   // Ideally we would be using onMouseEnter here, but
   // because we are binding the event to the target parent
@@ -355,10 +375,12 @@ function Tooltip(_ref) {
     }
   }, []);
   var onFocus = (0, _react.useCallback)(function () {
-    showTooltip({
+    // TODO: this does not play well with `hideTooltipOnMouseDown`
+    // as "focus" will occur after the "mousedown".
+    tryShowTooltip({
       type: 'keyboard'
     });
-  }, [showTooltip]);
+  }, [tryShowTooltip]);
   var onBlur = (0, _react.useCallback)(function () {
     if (apiRef.current) {
       apiRef.current.requestHide({
@@ -368,18 +390,19 @@ function Tooltip(_ref) {
   }, []);
   var onAnimationFinished = (0, _react.useCallback)(function (transition) {
     // Using lastState here because motion is not picking up the latest value
-    if (transition === 'exiting' && lastState.current === 'fade-out' && apiRef.current) {
+    if (transition === 'exiting' && stableState.current === 'fade-out' && apiRef.current) {
       // @ts-ignore: refs are writeable
       apiRef.current.finishHideAnimation();
     }
-  }, []);
+  }, [stableState]);
 
   // Doing a cast because typescript is struggling to narrow the type
   var CastTargetContainer = TargetContainer;
-  var shouldRenderTooltipContainer = state !== 'hide' && Boolean(content);
+  var shouldRenderTooltipPopup = state !== 'hide' && Boolean(content);
+  var shouldRenderHiddenContent = !isScreenReaderAnnouncementDisabled && shouldRenderTooltipPopup;
   var shouldRenderTooltipChildren = state !== 'hide' && state !== 'fade-out';
   (0, _openLayerObserver.useNotifyOpenLayerObserver)({
-    isOpen: shouldRenderTooltipContainer
+    isOpen: shouldRenderTooltipPopup
   });
   var getReferenceElement = function getReferenceElement() {
     var _apiRef$current4;
@@ -389,7 +412,7 @@ function Tooltip(_ref) {
     }
     return targetRef.current || undefined;
   };
-  var tooltipId = (0, _useUniqueId.default)('tooltip', shouldRenderTooltipContainer);
+  var tooltipIdForHiddenContent = (0, _useUniqueId.default)('tooltip', shouldRenderHiddenContent);
   var tooltipTriggerProps = {
     onMouseOver: onMouseOver,
     onMouseOut: onMouseOut,
@@ -408,38 +431,47 @@ function Tooltip(_ref) {
 
   // This useEffect is purely for managing the aria attribute when using the
   // wrapped children approach.
+  var isChildrenAFunction = typeof children === 'function';
   (0, _react.useEffect)(function () {
-    // If there is no container element, we should exit early, because that
-    // means they are using the render prop API, and that is implemented in a
-    // different way. If there is no target element yet or tooltipId, we also
-    // shouldn't do anything because there is nothing to operate on or with.
-    if (!containerRef.current || !targetRef.current || !tooltipId) {
+    if (isChildrenAFunction) {
       return;
     }
+
+    // If `children` is _not_ a function, we are stepping outside of the public
+    // API to add a `aria-describedby` attribute.
+
     var target = targetRef.current;
-    if (shouldRenderTooltipContainer) {
-      target.setAttribute('aria-describedby', tooltipId);
-    } else {
-      target.removeAttribute('aria-describedby');
+    if (!target || !tooltipIdForHiddenContent) {
+      return;
     }
-  }, [shouldRenderTooltipContainer, tooltipId]);
-  var hiddenContent = /*#__PURE__*/_react.default.createElement("span", {
+    target.setAttribute('aria-describedby', tooltipIdForHiddenContent);
+    return function () {
+      return target.removeAttribute('aria-describedby');
+    };
+  }, [isChildrenAFunction, tooltipIdForHiddenContent]);
+  var hiddenContent = shouldRenderHiddenContent ? /*#__PURE__*/_react.default.createElement("span", {
     "data-testid": testId ? "".concat(testId, "-hidden") : undefined,
     hidden: true,
-    id: tooltipId
-  }, typeof content === 'function' ? content({}) : content);
+    id: tooltipIdForHiddenContent
+  }, typeof content === 'function' ? content({}) : content) : null;
   return /*#__PURE__*/_react.default.createElement(_react.default.Fragment, null, typeof children === 'function' ?
   /*#__PURE__*/
   // once we deprecate the wrapped approach, we can put the aria
   // attribute back into the tooltipTriggerProps and make it required
   // instead of optional in `types`
   _react.default.createElement(_react.default.Fragment, null, children(_objectSpread(_objectSpread({}, tooltipTriggerProps), {}, {
-    'aria-describedby': tooltipId,
+    'aria-describedby': tooltipIdForHiddenContent,
     ref: setDirectRef
-  })), shouldRenderTooltipContainer && hiddenContent) : /*#__PURE__*/_react.default.createElement(CastTargetContainer, (0, _extends2.default)({}, tooltipTriggerProps, {
-    ref: setImplicitRefFromChildren,
+  })), hiddenContent) : /*#__PURE__*/_react.default.createElement(CastTargetContainer, (0, _extends2.default)({}, tooltipTriggerProps, {
+    ref: setImplicitRefFromChildren
+    /**
+     * TODO: Why is role="presentation" added?
+     * - Is it only to "remove" the `Container` from screen readers?
+     * - Why is it added only to the `Container` but not to `tooltipTriggerProps`?
+     * - Should `role="presentation"` only be used if `shouldRenderHiddenContent == false`?
+     */,
     role: "presentation"
-  }), children, shouldRenderTooltipContainer && hiddenContent), shouldRenderTooltipContainer ? /*#__PURE__*/_react.default.createElement(_portal.default, {
+  }), children, hiddenContent), shouldRenderTooltipPopup ? /*#__PURE__*/_react.default.createElement(_portal.default, {
     zIndex: tooltipZIndex
   }, /*#__PURE__*/_react.default.createElement(_popper.Popper, {
     placement: tooltipPosition,

package/dist/es2019/tooltip.js

@@ -4,6 +4,7 @@ import { bind } from 'bind-event-listener';
 import { usePlatformLeafSyntheticEventHandler } from '@atlaskit/analytics-next';
 import noop from '@atlaskit/ds-lib/noop';
 import useCloseOnEscapePress from '@atlaskit/ds-lib/use-close-on-escape-press';
+import useStableRef from '@atlaskit/ds-lib/use-stable-ref';
 import { useNotifyOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
 import { ExitingPersistence, FadeIn } from '@atlaskit/motion';
 import { mediumDurationMs } from '@atlaskit/motion/durations';
@@ -19,7 +20,7 @@ const tooltipZIndex = layers.tooltip();
 const analyticsAttributes = {
   componentName: 'tooltip',
   packageName: "@atlaskit/tooltip",
-  packageVersion: "18.8.5"
+  packageVersion: "18.9.1"
 };
 
 // Inverts motion direction
@@ -55,11 +56,13 @@ function Tooltip({
   delay = 300,
   onShow = noop,
   onHide = noop,
+  canAppear,
   hideTooltipOnClick = false,
   hideTooltipOnMouseDown = false,
   analyticsContext,
   strategy = 'fixed',
-  ignoreTooltipPointerEvents = false
+  ignoreTooltipPointerEvents = false,
+  isScreenReaderAnnouncementDisabled = false
 }) {
   const tooltipPosition = position === 'mouse' ? mousePosition : position;
   const onShowHandler = usePlatformLeafSyntheticEventHandler({
@@ -92,21 +95,15 @@ function Tooltip({
   }, []);
 
   // Putting a few things into refs so that we don't have to break memoization
-  const lastState = useRef(state);
-  const lastDelay = useRef(delay);
-  const lastHandlers = useRef({
-    onShowHandler,
-    onHideHandler
-  });
+  const stableState = useStableRef(state);
+  // These props are placed in separate refs instead of a single object to reduce memory usage.
+  // Placing them in the same object previously caused an increase in the number of JavaScript event listeners
+  // before garbage collection.
+  const onShowHandlerStable = useStableRef(onShowHandler);
+  const onHideHandlerStable = useStableRef(onHideHandler);
+  const delayStable = useStableRef(delay);
+  const canAppearStable = useStableRef(canAppear);
   const hasCalledShowHandler = useRef(false);
-  useEffect(() => {
-    lastState.current = state;
-    lastDelay.current = delay;
-    lastHandlers.current = {
-      onShowHandler,
-      onHideHandler
-    };
-  }, [delay, onHideHandler, onShowHandler, state]);
   const start = useCallback(api => {
     // @ts-ignore
     apiRef.current = api;
@@ -118,7 +115,7 @@ function Tooltip({
     }
     // Only call onHideHandler if we have called onShowHandler
     if (hasCalledShowHandler.current) {
-      lastHandlers.current.onHideHandler();
+      onHideHandlerStable.current();
     }
     // @ts-ignore
     apiRef.current = null;
@@ -126,7 +123,7 @@ function Tooltip({
     hasCalledShowHandler.current = false;
     // just in case
     setState('hide');
-  }, []);
+  }, [onHideHandlerStable]);
   const abort = useCallback(() => {
     if (!apiRef.current) {
       return;
@@ -134,11 +131,11 @@ function Tooltip({
     apiRef.current.abort();
     // Only call onHideHandler if we have called onShowHandler
     if (hasCalledShowHandler.current) {
-      lastHandlers.current.onHideHandler();
+      onHideHandlerStable.current();
     }
     // @ts-ignore
     apiRef.current = null;
-  }, []);
+  }, [onHideHandlerStable]);
   useEffect(function mount() {
     return function unmount() {
       if (apiRef.current) {
@@ -170,7 +167,8 @@ function Tooltip({
       }
     });
   }, []);
-  const showTooltip = useCallback(source => {
+  const tryShowTooltip = useCallback(source => {
+    var _canAppearStable$curr;
     /**
      * Prevent tooltips from being shown during a drag. This can occur with
      * the native drag and drop API, where some pointer events can fire
@@ -179,25 +177,46 @@ function Tooltip({
     if (isDraggingRef.current) {
       return;
     }
+
+    // Another tooltip is has been active but we still have the old `api`
+    // around. We need to finish up the last usage.
+    // Note: just being safe - this should not happen
     if (apiRef.current && !apiRef.current.isActive()) {
       abort();
     }
 
-    // Tell the tooltip to keep showing
+    // This tooltip is already active, we can exit
     if (apiRef.current && apiRef.current.isActive()) {
       apiRef.current.keep();
       return;
     }
+
+    /**
+     * Check if tooltip is allowed to show.
+     *
+     * Once a tooltip has started, or has scheduled to start
+     * we won't be checking `canAppear` again.
+     *
+     * - We don't want tooltips to disappear once they are shown
+     * - For consistency, we start after a single positive `canAppear`.
+     *   Otherwise the amount of times we ask consumers would depend on
+     *   how many times we get a "mousemove", which _could_ lead to situations
+     *   where moving the mouse could result in a different outcome to if
+     *   the mouse was not moved.
+     */
+    if (canAppearStable.current && !((_canAppearStable$curr = canAppearStable.current) !== null && _canAppearStable$curr !== void 0 && _canAppearStable$curr.call(canAppearStable))) {
+      return;
+    }
     const entry = {
       source,
-      delay: lastDelay.current,
+      delay: delayStable.current,
       show: ({
         isImmediate
       }) => {
         // Call the onShow handler if it hasn't been called yet
         if (!hasCalledShowHandler.current) {
           hasCalledShowHandler.current = true;
-          lastHandlers.current.onShowHandler();
+          onShowHandlerStable.current();
         }
         setState(isImmediate ? 'show-immediate' : 'fade-in');
       },
@@ -210,11 +229,11 @@ function Tooltip({
           setState('before-fade-out');
         }
       },
-      done: done
+      done
     };
     const api = show(entry);
     start(api);
-  }, [abort, done, start]);
+  }, [canAppearStable, delayStable, done, start, abort, onShowHandlerStable]);
   const hideTooltipOnEsc = useCallback(() => {
     var _apiRef$current2;
     (_apiRef$current2 = apiRef.current) === null || _apiRef$current2 === void 0 ? void 0 : _apiRef$current2.requestHide({
@@ -290,8 +309,8 @@ function Tooltip({
     } : {
       type: 'keyboard'
     };
-    showTooltip(source);
-  }, [position, showTooltip]);
+    tryShowTooltip(source);
+  }, [position, tryShowTooltip]);
 
   // Ideally we would be using onMouseEnter here, but
   // because we are binding the event to the target parent
@@ -331,10 +350,12 @@ function Tooltip({
     }
   }, []);
   const onFocus = useCallback(() => {
-    showTooltip({
+    // TODO: this does not play well with `hideTooltipOnMouseDown`
+    // as "focus" will occur after the "mousedown".
+    tryShowTooltip({
       type: 'keyboard'
     });
-  }, [showTooltip]);
+  }, [tryShowTooltip]);
   const onBlur = useCallback(() => {
     if (apiRef.current) {
       apiRef.current.requestHide({
@@ -344,18 +365,19 @@ function Tooltip({
   }, []);
   const onAnimationFinished = useCallback(transition => {
     // Using lastState here because motion is not picking up the latest value
-    if (transition === 'exiting' && lastState.current === 'fade-out' && apiRef.current) {
+    if (transition === 'exiting' && stableState.current === 'fade-out' && apiRef.current) {
       // @ts-ignore: refs are writeable
       apiRef.current.finishHideAnimation();
     }
-  }, []);
+  }, [stableState]);
 
   // Doing a cast because typescript is struggling to narrow the type
   const CastTargetContainer = TargetContainer;
-  const shouldRenderTooltipContainer = state !== 'hide' && Boolean(content);
+  const shouldRenderTooltipPopup = state !== 'hide' && Boolean(content);
+  const shouldRenderHiddenContent = !isScreenReaderAnnouncementDisabled && shouldRenderTooltipPopup;
   const shouldRenderTooltipChildren = state !== 'hide' && state !== 'fade-out';
   useNotifyOpenLayerObserver({
-    isOpen: shouldRenderTooltipContainer
+    isOpen: shouldRenderTooltipPopup
   });
   const getReferenceElement = () => {
     var _apiRef$current4;
@@ -365,7 +387,7 @@ function Tooltip({
     }
     return targetRef.current || undefined;
   };
-  const tooltipId = useUniqueId('tooltip', shouldRenderTooltipContainer);
+  const tooltipIdForHiddenContent = useUniqueId('tooltip', shouldRenderHiddenContent);
   const tooltipTriggerProps = {
     onMouseOver,
     onMouseOut,
@@ -384,26 +406,27 @@ function Tooltip({
 
   // This useEffect is purely for managing the aria attribute when using the
   // wrapped children approach.
+  const isChildrenAFunction = typeof children === 'function';
   useEffect(() => {
-    // If there is no container element, we should exit early, because that
-    // means they are using the render prop API, and that is implemented in a
-    // different way. If there is no target element yet or tooltipId, we also
-    // shouldn't do anything because there is nothing to operate on or with.
-    if (!containerRef.current || !targetRef.current || !tooltipId) {
+    if (isChildrenAFunction) {
       return;
     }
+
+    // If `children` is _not_ a function, we are stepping outside of the public
+    // API to add a `aria-describedby` attribute.
+
     const target = targetRef.current;
-    if (shouldRenderTooltipContainer) {
-      target.setAttribute('aria-describedby', tooltipId);
-    } else {
-      target.removeAttribute('aria-describedby');
+    if (!target || !tooltipIdForHiddenContent) {
+      return;
     }
-  }, [shouldRenderTooltipContainer, tooltipId]);
-  const hiddenContent = /*#__PURE__*/React.createElement("span", {
+    target.setAttribute('aria-describedby', tooltipIdForHiddenContent);
+    return () => target.removeAttribute('aria-describedby');
+  }, [isChildrenAFunction, tooltipIdForHiddenContent]);
+  const hiddenContent = shouldRenderHiddenContent ? /*#__PURE__*/React.createElement("span", {
     "data-testid": testId ? `${testId}-hidden` : undefined,
     hidden: true,
-    id: tooltipId
-  }, typeof content === 'function' ? content({}) : content);
+    id: tooltipIdForHiddenContent
+  }, typeof content === 'function' ? content({}) : content) : null;
   return /*#__PURE__*/React.createElement(React.Fragment, null, typeof children === 'function' ?
   /*#__PURE__*/
   // once we deprecate the wrapped approach, we can put the aria
@@ -411,12 +434,18 @@ function Tooltip({
   // instead of optional in `types`
   React.createElement(React.Fragment, null, children({
     ...tooltipTriggerProps,
-    'aria-describedby': tooltipId,
+    'aria-describedby': tooltipIdForHiddenContent,
     ref: setDirectRef
-  }), shouldRenderTooltipContainer && hiddenContent) : /*#__PURE__*/React.createElement(CastTargetContainer, _extends({}, tooltipTriggerProps, {
-    ref: setImplicitRefFromChildren,
+  }), hiddenContent) : /*#__PURE__*/React.createElement(CastTargetContainer, _extends({}, tooltipTriggerProps, {
+    ref: setImplicitRefFromChildren
+    /**
+     * TODO: Why is role="presentation" added?
+     * - Is it only to "remove" the `Container` from screen readers?
+     * - Why is it added only to the `Container` but not to `tooltipTriggerProps`?
+     * - Should `role="presentation"` only be used if `shouldRenderHiddenContent == false`?
+     */,
     role: "presentation"
-  }), children, shouldRenderTooltipContainer && hiddenContent), shouldRenderTooltipContainer ? /*#__PURE__*/React.createElement(Portal, {
+  }), children, hiddenContent), shouldRenderTooltipPopup ? /*#__PURE__*/React.createElement(Portal, {
     zIndex: tooltipZIndex
   }, /*#__PURE__*/React.createElement(Popper, {
     placement: tooltipPosition,

package/dist/esm/tooltip.js

@@ -8,6 +8,7 @@ import { bind } from 'bind-event-listener';
 import { usePlatformLeafSyntheticEventHandler } from '@atlaskit/analytics-next';
 import noop from '@atlaskit/ds-lib/noop';
 import useCloseOnEscapePress from '@atlaskit/ds-lib/use-close-on-escape-press';
+import useStableRef from '@atlaskit/ds-lib/use-stable-ref';
 import { useNotifyOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
 import { ExitingPersistence, FadeIn } from '@atlaskit/motion';
 import { mediumDurationMs } from '@atlaskit/motion/durations';
@@ -23,7 +24,7 @@ var tooltipZIndex = layers.tooltip();
 var analyticsAttributes = {
   componentName: 'tooltip',
   packageName: "@atlaskit/tooltip",
-  packageVersion: "18.8.5"
+  packageVersion: "18.9.1"
 };
 
 // Inverts motion direction
@@ -68,6 +69,7 @@ function Tooltip(_ref) {
     onShow = _ref$onShow === void 0 ? noop : _ref$onShow,
     _ref$onHide = _ref.onHide,
     onHide = _ref$onHide === void 0 ? noop : _ref$onHide,
+    canAppear = _ref.canAppear,
     _ref$hideTooltipOnCli = _ref.hideTooltipOnClick,
     hideTooltipOnClick = _ref$hideTooltipOnCli === void 0 ? false : _ref$hideTooltipOnCli,
     _ref$hideTooltipOnMou = _ref.hideTooltipOnMouseDown,
@@ -76,7 +78,9 @@ function Tooltip(_ref) {
     _ref$strategy = _ref.strategy,
     strategy = _ref$strategy === void 0 ? 'fixed' : _ref$strategy,
     _ref$ignoreTooltipPoi = _ref.ignoreTooltipPointerEvents,
-    ignoreTooltipPointerEvents = _ref$ignoreTooltipPoi === void 0 ? false : _ref$ignoreTooltipPoi;
+    ignoreTooltipPointerEvents = _ref$ignoreTooltipPoi === void 0 ? false : _ref$ignoreTooltipPoi,
+    _ref$isScreenReaderAn = _ref.isScreenReaderAnnouncementDisabled,
+    isScreenReaderAnnouncementDisabled = _ref$isScreenReaderAn === void 0 ? false : _ref$isScreenReaderAn;
   var tooltipPosition = position === 'mouse' ? mousePosition : position;
   var onShowHandler = usePlatformLeafSyntheticEventHandler(_objectSpread({
     fn: onShow,
@@ -109,21 +113,15 @@ function Tooltip(_ref) {
   }, []);
 
   // Putting a few things into refs so that we don't have to break memoization
-  var lastState = useRef(state);
-  var lastDelay = useRef(delay);
-  var lastHandlers = useRef({
-    onShowHandler: onShowHandler,
-    onHideHandler: onHideHandler
-  });
+  var stableState = useStableRef(state);
+  // These props are placed in separate refs instead of a single object to reduce memory usage.
+  // Placing them in the same object previously caused an increase in the number of JavaScript event listeners
+  // before garbage collection.
+  var onShowHandlerStable = useStableRef(onShowHandler);
+  var onHideHandlerStable = useStableRef(onHideHandler);
+  var delayStable = useStableRef(delay);
+  var canAppearStable = useStableRef(canAppear);
   var hasCalledShowHandler = useRef(false);
-  useEffect(function () {
-    lastState.current = state;
-    lastDelay.current = delay;
-    lastHandlers.current = {
-      onShowHandler: onShowHandler,
-      onHideHandler: onHideHandler
-    };
-  }, [delay, onHideHandler, onShowHandler, state]);
   var start = useCallback(function (api) {
     // @ts-ignore
     apiRef.current = api;
@@ -135,7 +133,7 @@ function Tooltip(_ref) {
     }
     // Only call onHideHandler if we have called onShowHandler
     if (hasCalledShowHandler.current) {
-      lastHandlers.current.onHideHandler();
+      onHideHandlerStable.current();
     }
     // @ts-ignore
     apiRef.current = null;
@@ -143,7 +141,7 @@ function Tooltip(_ref) {
     hasCalledShowHandler.current = false;
     // just in case
     setState('hide');
-  }, []);
+  }, [onHideHandlerStable]);
   var abort = useCallback(function () {
     if (!apiRef.current) {
       return;
@@ -151,11 +149,11 @@ function Tooltip(_ref) {
     apiRef.current.abort();
     // Only call onHideHandler if we have called onShowHandler
     if (hasCalledShowHandler.current) {
-      lastHandlers.current.onHideHandler();
+      onHideHandlerStable.current();
     }
     // @ts-ignore
     apiRef.current = null;
-  }, []);
+  }, [onHideHandlerStable]);
   useEffect(function mount() {
     return function unmount() {
       if (apiRef.current) {
@@ -186,7 +184,8 @@ function Tooltip(_ref) {
       }
     });
   }, []);
-  var showTooltip = useCallback(function (source) {
+  var tryShowTooltip = useCallback(function (source) {
+    var _canAppearStable$curr;
     /**
      * Prevent tooltips from being shown during a drag. This can occur with
      * the native drag and drop API, where some pointer events can fire
@@ -195,24 +194,45 @@ function Tooltip(_ref) {
     if (isDraggingRef.current) {
       return;
     }
+
+    // Another tooltip is has been active but we still have the old `api`
+    // around. We need to finish up the last usage.
+    // Note: just being safe - this should not happen
     if (apiRef.current && !apiRef.current.isActive()) {
       abort();
     }
 
-    // Tell the tooltip to keep showing
+    // This tooltip is already active, we can exit
     if (apiRef.current && apiRef.current.isActive()) {
       apiRef.current.keep();
       return;
     }
+
+    /**
+     * Check if tooltip is allowed to show.
+     *
+     * Once a tooltip has started, or has scheduled to start
+     * we won't be checking `canAppear` again.
+     *
+     * - We don't want tooltips to disappear once they are shown
+     * - For consistency, we start after a single positive `canAppear`.
+     *   Otherwise the amount of times we ask consumers would depend on
+     *   how many times we get a "mousemove", which _could_ lead to situations
+     *   where moving the mouse could result in a different outcome to if
+     *   the mouse was not moved.
+     */
+    if (canAppearStable.current && !((_canAppearStable$curr = canAppearStable.current) !== null && _canAppearStable$curr !== void 0 && _canAppearStable$curr.call(canAppearStable))) {
+      return;
+    }
     var entry = {
       source: source,
-      delay: lastDelay.current,
+      delay: delayStable.current,
       show: function show(_ref3) {
         var isImmediate = _ref3.isImmediate;
         // Call the onShow handler if it hasn't been called yet
         if (!hasCalledShowHandler.current) {
           hasCalledShowHandler.current = true;
-          lastHandlers.current.onShowHandler();
+          onShowHandlerStable.current();
         }
         setState(isImmediate ? 'show-immediate' : 'fade-in');
       },
@@ -228,7 +248,7 @@ function Tooltip(_ref) {
     };
     var api = show(entry);
     start(api);
-  }, [abort, done, start]);
+  }, [canAppearStable, delayStable, done, start, abort, onShowHandlerStable]);
   var hideTooltipOnEsc = useCallback(function () {
     var _apiRef$current2;
     (_apiRef$current2 = apiRef.current) === null || _apiRef$current2 === void 0 || _apiRef$current2.requestHide({
@@ -304,8 +324,8 @@ function Tooltip(_ref) {
     } : {
       type: 'keyboard'
     };
-    showTooltip(source);
-  }, [position, showTooltip]);
+    tryShowTooltip(source);
+  }, [position, tryShowTooltip]);
 
   // Ideally we would be using onMouseEnter here, but
   // because we are binding the event to the target parent
@@ -345,10 +365,12 @@ function Tooltip(_ref) {
     }
   }, []);
   var onFocus = useCallback(function () {
-    showTooltip({
+    // TODO: this does not play well with `hideTooltipOnMouseDown`
+    // as "focus" will occur after the "mousedown".
+    tryShowTooltip({
       type: 'keyboard'
     });
-  }, [showTooltip]);
+  }, [tryShowTooltip]);
   var onBlur = useCallback(function () {
     if (apiRef.current) {
       apiRef.current.requestHide({
@@ -358,18 +380,19 @@ function Tooltip(_ref) {
   }, []);
   var onAnimationFinished = useCallback(function (transition) {
     // Using lastState here because motion is not picking up the latest value
-    if (transition === 'exiting' && lastState.current === 'fade-out' && apiRef.current) {
+    if (transition === 'exiting' && stableState.current === 'fade-out' && apiRef.current) {
       // @ts-ignore: refs are writeable
       apiRef.current.finishHideAnimation();
     }
-  }, []);
+  }, [stableState]);
 
   // Doing a cast because typescript is struggling to narrow the type
   var CastTargetContainer = TargetContainer;
-  var shouldRenderTooltipContainer = state !== 'hide' && Boolean(content);
+  var shouldRenderTooltipPopup = state !== 'hide' && Boolean(content);
+  var shouldRenderHiddenContent = !isScreenReaderAnnouncementDisabled && shouldRenderTooltipPopup;
   var shouldRenderTooltipChildren = state !== 'hide' && state !== 'fade-out';
   useNotifyOpenLayerObserver({
-    isOpen: shouldRenderTooltipContainer
+    isOpen: shouldRenderTooltipPopup
   });
   var getReferenceElement = function getReferenceElement() {
     var _apiRef$current4;
@@ -379,7 +402,7 @@ function Tooltip(_ref) {
     }
     return targetRef.current || undefined;
   };
-  var tooltipId = useUniqueId('tooltip', shouldRenderTooltipContainer);
+  var tooltipIdForHiddenContent = useUniqueId('tooltip', shouldRenderHiddenContent);
   var tooltipTriggerProps = {
     onMouseOver: onMouseOver,
     onMouseOut: onMouseOut,
@@ -398,38 +421,47 @@ function Tooltip(_ref) {
 
   // This useEffect is purely for managing the aria attribute when using the
   // wrapped children approach.
+  var isChildrenAFunction = typeof children === 'function';
   useEffect(function () {
-    // If there is no container element, we should exit early, because that
-    // means they are using the render prop API, and that is implemented in a
-    // different way. If there is no target element yet or tooltipId, we also
-    // shouldn't do anything because there is nothing to operate on or with.
-    if (!containerRef.current || !targetRef.current || !tooltipId) {
+    if (isChildrenAFunction) {
       return;
     }
+
+    // If `children` is _not_ a function, we are stepping outside of the public
+    // API to add a `aria-describedby` attribute.
+
     var target = targetRef.current;
-    if (shouldRenderTooltipContainer) {
-      target.setAttribute('aria-describedby', tooltipId);
-    } else {
-      target.removeAttribute('aria-describedby');
+    if (!target || !tooltipIdForHiddenContent) {
+      return;
     }
-  }, [shouldRenderTooltipContainer, tooltipId]);
-  var hiddenContent = /*#__PURE__*/React.createElement("span", {
+    target.setAttribute('aria-describedby', tooltipIdForHiddenContent);
+    return function () {
+      return target.removeAttribute('aria-describedby');
+    };
+  }, [isChildrenAFunction, tooltipIdForHiddenContent]);
+  var hiddenContent = shouldRenderHiddenContent ? /*#__PURE__*/React.createElement("span", {
     "data-testid": testId ? "".concat(testId, "-hidden") : undefined,
     hidden: true,
-    id: tooltipId
-  }, typeof content === 'function' ? content({}) : content);
+    id: tooltipIdForHiddenContent
+  }, typeof content === 'function' ? content({}) : content) : null;
   return /*#__PURE__*/React.createElement(React.Fragment, null, typeof children === 'function' ?
   /*#__PURE__*/
   // once we deprecate the wrapped approach, we can put the aria
   // attribute back into the tooltipTriggerProps and make it required
   // instead of optional in `types`
   React.createElement(React.Fragment, null, children(_objectSpread(_objectSpread({}, tooltipTriggerProps), {}, {
-    'aria-describedby': tooltipId,
+    'aria-describedby': tooltipIdForHiddenContent,
     ref: setDirectRef
-  })), shouldRenderTooltipContainer && hiddenContent) : /*#__PURE__*/React.createElement(CastTargetContainer, _extends({}, tooltipTriggerProps, {
-    ref: setImplicitRefFromChildren,
+  })), hiddenContent) : /*#__PURE__*/React.createElement(CastTargetContainer, _extends({}, tooltipTriggerProps, {
+    ref: setImplicitRefFromChildren
+    /**
+     * TODO: Why is role="presentation" added?
+     * - Is it only to "remove" the `Container` from screen readers?
+     * - Why is it added only to the `Container` but not to `tooltipTriggerProps`?
+     * - Should `role="presentation"` only be used if `shouldRenderHiddenContent == false`?
+     */,
     role: "presentation"
-  }), children, shouldRenderTooltipContainer && hiddenContent), shouldRenderTooltipContainer ? /*#__PURE__*/React.createElement(Portal, {
+  }), children, hiddenContent), shouldRenderTooltipPopup ? /*#__PURE__*/React.createElement(Portal, {
     zIndex: tooltipZIndex
   }, /*#__PURE__*/React.createElement(Popper, {
     placement: tooltipPosition,

package/dist/types/tooltip.d.ts

@@ -5,7 +5,7 @@ import { type TooltipProps } from './types';
  *
  * A tooltip is a floating, non-actionable label used to explain a user interface element or feature.
  */
-declare function Tooltip({ children, position, mousePosition, content, truncate, component: Container, tag: TargetContainer, testId, delay, onShow, onHide, hideTooltipOnClick, hideTooltipOnMouseDown, analyticsContext, strategy, ignoreTooltipPointerEvents, }: TooltipProps): JSX.Element;
+declare function Tooltip({ children, position, mousePosition, content, truncate, component: Container, tag: TargetContainer, testId, delay, onShow, onHide, canAppear, hideTooltipOnClick, hideTooltipOnMouseDown, analyticsContext, strategy, ignoreTooltipPointerEvents, isScreenReaderAnnouncementDisabled, }: TooltipProps): JSX.Element;
 declare namespace Tooltip {
     var displayName: string;
 }

package/dist/types/types.d.ts

@@ -22,6 +22,11 @@ export interface TooltipProps {
      * 2. Function which returns a `ReactNode`
      * The benefit of the second approach is that it allows you to consume the `update` render prop.
      * This `update` function can be called to manually recalculate the position of the tooltip.
+     *
+     * This content will be rendered into two places:
+     * 1. Into the tooltip
+     * 2. Into a hidden element for screen readers (unless `isScreenReaderAnnouncementDisabled` is set to `true`)
+     *
      */
     content: ReactNode | (({ update }: {
         update?: () => void;
@@ -55,6 +60,25 @@ export interface TooltipProps {
      * When interacting with the target element using a keyboard, it will use this position against the target element instead.
      */
     mousePosition?: PositionTypeBase;
+    /**
+     * Whether or not the tooltip can be displayed. Once a tooltip
+     * is scheduled to be displayed, or is already displayed, it will
+     * continue to be shown.
+     *
+     * @description
+     *
+     * `canAppear()` is called in response to user events, and
+     * not during the rendering of components.
+     *
+     */
+    canAppear?: () => boolean;
+    /**
+     * By default tooltip content will be duplicated into a hidden element so
+     * it can be read out by a screen reader. Sometimes this is not ideal as
+     * it can result in the same content be announced twice. For those situations,
+     * you can leverage this prop to disable the duplicate hidden text.
+     */
+    isScreenReaderAnnouncementDisabled?: boolean;
     /**
      * Function to be called when the tooltip will be shown. It's called when the
      * tooltip begins to animate in.

package/dist/types-ts4.5/tooltip.d.ts

@@ -5,7 +5,7 @@ import { type TooltipProps } from './types';
  *
  * A tooltip is a floating, non-actionable label used to explain a user interface element or feature.
  */
-declare function Tooltip({ children, position, mousePosition, content, truncate, component: Container, tag: TargetContainer, testId, delay, onShow, onHide, hideTooltipOnClick, hideTooltipOnMouseDown, analyticsContext, strategy, ignoreTooltipPointerEvents, }: TooltipProps): JSX.Element;
+declare function Tooltip({ children, position, mousePosition, content, truncate, component: Container, tag: TargetContainer, testId, delay, onShow, onHide, canAppear, hideTooltipOnClick, hideTooltipOnMouseDown, analyticsContext, strategy, ignoreTooltipPointerEvents, isScreenReaderAnnouncementDisabled, }: TooltipProps): JSX.Element;
 declare namespace Tooltip {
     var displayName: string;
 }

package/dist/types-ts4.5/types.d.ts

@@ -22,6 +22,11 @@ export interface TooltipProps {
      * 2. Function which returns a `ReactNode`
      * The benefit of the second approach is that it allows you to consume the `update` render prop.
      * This `update` function can be called to manually recalculate the position of the tooltip.
+     *
+     * This content will be rendered into two places:
+     * 1. Into the tooltip
+     * 2. Into a hidden element for screen readers (unless `isScreenReaderAnnouncementDisabled` is set to `true`)
+     *
      */
     content: ReactNode | (({ update }: {
         update?: () => void;
@@ -55,6 +60,25 @@ export interface TooltipProps {
      * When interacting with the target element using a keyboard, it will use this position against the target element instead.
      */
     mousePosition?: PositionTypeBase;
+    /**
+     * Whether or not the tooltip can be displayed. Once a tooltip
+     * is scheduled to be displayed, or is already displayed, it will
+     * continue to be shown.
+     *
+     * @description
+     *
+     * `canAppear()` is called in response to user events, and
+     * not during the rendering of components.
+     *
+     */
+    canAppear?: () => boolean;
+    /**
+     * By default tooltip content will be duplicated into a hidden element so
+     * it can be read out by a screen reader. Sometimes this is not ideal as
+     * it can result in the same content be announced twice. For those situations,
+     * you can leverage this prop to disable the duplicate hidden text.
+     */
+    isScreenReaderAnnouncementDisabled?: boolean;
     /**
      * Function to be called when the tooltip will be shown. It's called when the
      * tooltip begins to animate in.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/tooltip",
-	"version": "18.8.5",
+	"version": "18.9.1",
 	"description": "A tooltip is a floating, non-actionable label used to explain a user interface element or feature.",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -40,13 +40,13 @@
 	},
 	"dependencies": {
 		"@atlaskit/analytics-next": "^10.1.0",
-		"@atlaskit/ds-lib": "^3.1.0",
-		"@atlaskit/layering": "^0.7.0",
+		"@atlaskit/ds-lib": "^3.2.0",
+		"@atlaskit/layering": "^0.7.3",
 		"@atlaskit/motion": "^1.9.0",
 		"@atlaskit/popper": "^6.3.0",
 		"@atlaskit/portal": "^4.9.0",
 		"@atlaskit/theme": "^14.0.0",
-		"@atlaskit/tokens": "^2.0.0",
+		"@atlaskit/tokens": "^2.2.0",
 		"@babel/runtime": "^7.0.0",
 		"@emotion/react": "^11.7.1",
 		"bind-event-listener": "^3.0.0"
@@ -57,7 +57,8 @@
 	},
 	"devDependencies": {
 		"@af/accessibility-testing": "*",
-		"@atlaskit/button": "^20.2.0",
+		"@af/integration-testing": "*",
+		"@atlaskit/button": "^20.3.0",
 		"@atlaskit/ssr": "*",
 		"@atlaskit/visual-regression": "*",
 		"@emotion/styled": "^11.0.0",
@@ -67,7 +68,7 @@
 		"jest-in-case": "^1.0.2",
 		"react-dom": "^16.8.0",
 		"react-redux": "^5.1.2",
-		"storybook-addon-performance": "^0.16.0",
+		"storybook-addon-performance": "^0.17.3",
 		"typescript": "~5.4.2",
 		"wait-for-expect": "^1.2.0"
 	},