@atlaskit/spotlight 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @atlaskit/spotlight
 
+## 0.5.1
+
+### Patch Changes
+
+- [`4f9f525caaa13`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/4f9f525caaa13) -
+  Implement 'dismiss on escape key press' functionality. Escape will cause the current spotlight to
+  call the `dismiss` function passed to `PopoverContent`. Implementation of the `dismiss` function
+  is up to the consumer of the package.
+- Updated dependencies
+
+## 0.5.0
+
+### Minor Changes
+
+- [`72526321aecd0`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/72526321aecd0) -
+  Create UNSAFE_UpdateOnChange component to test strategies for recalculating PopoverContent
+  position when the DOM changes.
+
 ## 0.4.1
 
 ### Patch Changes

package/dist/cjs/controllers/context.js

@@ -10,21 +10,53 @@ exports.SpotlightContextProvider = exports.SpotlightContext = void 0;
 var _react = _interopRequireWildcard(require("react"));
 var React = _react;
 var _runtime = require("@compiled/react/runtime");
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
 // eslint-disable-next-line @repo/internal/react/consistent-types-definitions
 
 // eslint-disable-next-line @repo/internal/react/require-jsdoc
 var SpotlightContext = exports.SpotlightContext = /*#__PURE__*/(0, _react.createContext)({
-  placement: 'bottom-end',
-  setPlacement: function setPlacement() {
-    return undefined;
+  card: {
+    placement: 'bottom-end',
+    setPlacement: function setPlacement() {
+      return undefined;
+    }
   },
   heading: {
     id: '',
     setId: function setId() {
       return undefined;
     }
+  },
+  popoverContent: {
+    ref: undefined,
+    setRef: function setRef() {
+      return undefined;
+    },
+    update: function update() {
+      return function () {
+        return new Promise(function () {
+          return null;
+        });
+      };
+    },
+    setUpdate: function setUpdate() {
+      return function () {
+        return new Promise(function () {
+          return null;
+        });
+      };
+    },
+    dismiss: function dismiss() {
+      return undefined;
+    },
+    setDismiss: function setDismiss() {
+      return function () {
+        return undefined;
+      };
+    }
   }
 });
 
@@ -40,13 +72,49 @@ var SpotlightContextProvider = exports.SpotlightContextProvider = function Spotl
     _useState4 = (0, _slicedToArray2.default)(_useState3, 2),
     headingId = _useState4[0],
     setHeadingId = _useState4[1];
+  var _useState5 = (0, _react.useState)(function () {
+      return /*#__PURE__*/(0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee() {
+        return _regenerator.default.wrap(function _callee$(_context) {
+          while (1) switch (_context.prev = _context.next) {
+            case 0:
+              return _context.abrupt("return", undefined);
+            case 1:
+            case "end":
+              return _context.stop();
+          }
+        }, _callee);
+      }));
+    }),
+    _useState6 = (0, _slicedToArray2.default)(_useState5, 2),
+    update = _useState6[0],
+    setUpdate = _useState6[1];
+  var _useState7 = (0, _react.useState)(),
+    _useState8 = (0, _slicedToArray2.default)(_useState7, 2),
+    ref = _useState8[0],
+    setRef = _useState8[1];
+  var _useState9 = (0, _react.useState)(function () {
+      return undefined;
+    }),
+    _useState0 = (0, _slicedToArray2.default)(_useState9, 2),
+    dismiss = _useState0[0],
+    setDismiss = _useState0[1];
   return /*#__PURE__*/React.createElement(SpotlightContext.Provider, {
     value: {
-      placement: placement,
-      setPlacement: setPlacement,
+      card: {
+        placement: placement,
+        setPlacement: setPlacement
+      },
       heading: {
         id: headingId,
         setId: setHeadingId
+      },
+      popoverContent: {
+        ref: ref,
+        setRef: setRef,
+        update: update,
+        setUpdate: setUpdate,
+        dismiss: dismiss,
+        setDismiss: setDismiss
       }
     }
   }, children);

package/dist/cjs/index.js

@@ -99,6 +99,12 @@ Object.defineProperty(exports, "SpotlightStepCount", {
     return _stepCount.SpotlightStepCount;
   }
 });
+Object.defineProperty(exports, "UNSAFE_UpdateOnChange", {
+  enumerable: true,
+  get: function get() {
+    return _UNSAFE_updateOnChange.UNSAFE_UpdateOnChange;
+  }
+});
 var _card = require("./ui/card");
 var _body = require("./ui/body");
 var _header = require("./ui/header");
@@ -114,4 +120,5 @@ var _showMoreControl = require("./ui/show-more-control");
 var _media = require("./ui/media");
 var _popoverProvider = require("./ui/popover-provider");
 var _popoverContent = require("./ui/popover-content");
-var _popoverTarget = require("./ui/popover-target");
+var _popoverTarget = require("./ui/popover-target");
+var _UNSAFE_updateOnChange = require("./ui/UNSAFE_update-on-change");

package/dist/cjs/ui/UNSAFE_update-on-change/index.js

@@ -0,0 +1,59 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.UNSAFE_UpdateOnChange = void 0;
+var _react = require("react");
+var _browserApis = require("@atlaskit/browser-apis");
+var _context = require("../../controllers/context");
+var defaultOptions = {
+  childList: true,
+  subtree: true
+};
+var UNSAFE_UpdateOnChange = exports.UNSAFE_UpdateOnChange = function UNSAFE_UpdateOnChange(_ref) {
+  var _ref$selectors = _ref.selectors,
+    selectors = _ref$selectors === void 0 ? ['body'] : _ref$selectors,
+    _ref$options = _ref.options,
+    options = _ref$options === void 0 ? defaultOptions : _ref$options;
+  var _useContext = (0, _react.useContext)(_context.SpotlightContext),
+    popoverContent = _useContext.popoverContent;
+  var update = popoverContent.update;
+  (0, _react.useEffect)(function () {
+    if (!update || selectors.length === 0) {
+      return;
+    }
+    var doc = (0, _browserApis.getDocument)();
+    if (!doc) {
+      return;
+    }
+    var elements = new Set();
+    selectors.forEach(function (selector) {
+      var element = doc.querySelector(selector);
+      if (!element) {
+        return;
+      }
+      elements.add(element);
+    });
+    if (elements.size === 0) {
+      return;
+    }
+    var observers = [];
+    elements.forEach(function (element) {
+      var observer = new MutationObserver(function (mutations) {
+        if (mutations.length === 0) {
+          return;
+        }
+        update();
+      });
+      observer.observe(element, options);
+      observers.push(observer);
+    });
+    return function () {
+      observers.forEach(function (observer) {
+        return observer.disconnect();
+      });
+    };
+  }, [selectors, options, update]);
+  return null;
+};

package/dist/cjs/ui/card/caret/index.js

@@ -34,10 +34,10 @@ var styles = {
 var Caret = exports.Caret = /*#__PURE__*/(0, _react.forwardRef)(function (_ref, ref) {
   var testId = _ref.testId;
   var _useContext = (0, _react.useContext)(_context.SpotlightContext),
-    placement = _useContext.placement;
+    card = _useContext.card;
   return /*#__PURE__*/React.createElement("div", {
     "data-testid": testId,
     ref: ref,
-    className: (0, _runtime.ax)([styles.root, styles[placement]])
+    className: (0, _runtime.ax)([styles.root, styles[card.placement]])
   });
 });

package/dist/cjs/ui/card/index.js

@@ -41,13 +41,13 @@ var SpotlightCard = exports.SpotlightCard = /*#__PURE__*/(0, _react.forwardRef)(
   var children = _ref.children,
     testId = _ref.testId;
   var _useContext = (0, _react.useContext)(_context.SpotlightContext),
-    placement = _useContext.placement;
+    card = _useContext.card;
   return /*#__PURE__*/React.createElement("div", {
     "data-testid": testId,
     ref: ref,
     className: (0, _runtime.ax)([styles.root])
   }, /*#__PURE__*/React.createElement(_caret.Caret, null), /*#__PURE__*/React.createElement(_compiled.Box, {
     backgroundColor: "color.background.neutral.bold",
-    xcss: (0, _css.cx)(styles.card, placementStyles[placement])
+    xcss: (0, _css.cx)(styles.card, placementStyles[card.placement])
   }, children));
 });

package/dist/cjs/ui/popover-content/index.js

@@ -1,6 +1,7 @@
 /* index.tsx generated by @compiled/babel-plugin v0.38.1 */
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 var _typeof = require("@babel/runtime/helpers/typeof");
 Object.defineProperty(exports, "__esModule", {
   value: true
@@ -10,8 +11,11 @@ require("./index.compiled.css");
 var _react = _interopRequireWildcard(require("react"));
 var React = _react;
 var _runtime = require("@compiled/react/runtime");
+var _mergeRefs = _interopRequireDefault(require("@atlaskit/ds-lib/merge-refs"));
 var _popper = require("@atlaskit/popper");
 var _context = require("../../controllers/context");
+var _useFocusWithin = require("../../utils/use-focus-within");
+var _useOnEscape = require("../../utils/use-on-escape");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
 var styles = {
   root: "_1pby1fw0"
@@ -22,7 +26,7 @@ var styles = {
  * the caret extending beyond the bounding box (by roughly 2px). So, apply an offset to ensure
  * the caret points to the very edge of the target element.
  *
- * Note: `@atlaskit/popper` maps the offset to to the placement, so we only need to define `[0, 2]` and
+ * Note: `@atlaskit/popper` maps the offset to the placement, so we only need to define `[0, 2]` and
  * the offset will get correctly rotated depending on the placement.
  */
 var offset = [0, 2];
@@ -55,27 +59,57 @@ var PopoverContent = exports.PopoverContent = function PopoverContent(_ref) {
     placement = _ref.placement,
     _ref$isVisible = _ref.isVisible,
     isVisible = _ref$isVisible === void 0 ? true : _ref$isVisible,
+    dismiss = _ref.dismiss,
     testId = _ref.testId;
+  var updateRef = (0, _react.useRef)(function () {
+    return new Promise(function () {
+      return undefined;
+    });
+  });
+  var ref = (0, _react.useRef)();
   var _useContext = (0, _react.useContext)(_context.SpotlightContext),
-    setPlacement = _useContext.setPlacement,
-    heading = _useContext.heading;
+    heading = _useContext.heading,
+    popoverContent = _useContext.popoverContent,
+    card = _useContext.card;
+  var focusWithin = (0, _useFocusWithin.useFocusWithin)(popoverContent.ref);
+  (0, _react.useEffect)(function () {
+    popoverContent.setRef(ref);
+  }, [ref, popoverContent]);
+  (0, _react.useEffect)(function () {
+    card.setPlacement(placement);
+  }, [placement, card]);
   (0, _react.useEffect)(function () {
-    setPlacement(placement);
-  }, [placement, setPlacement]);
+    if (updateRef.current) {
+      popoverContent.setUpdate(function () {
+        return updateRef.current;
+      });
+    }
+  }, [popoverContent]);
+  (0, _useOnEscape.useOnEscape)(function (event) {
+    if (!focusWithin) {
+      return;
+    }
+    if (!dismiss) {
+      return;
+    }
+    dismiss(event);
+  });
   return /*#__PURE__*/React.createElement(_popper.Popper, {
     offset: offset,
     placement: popperPlacementMap[placement]
   }, function (_ref2) {
-    var ref = _ref2.ref,
-      style = _ref2.style;
+    var localRef = _ref2.ref,
+      style = _ref2.style,
+      update = _ref2.update;
     if (!isVisible) {
       return;
     }
+    updateRef.current = update;
     return /*#__PURE__*/React.createElement("div", {
       role: "dialog",
       "data-testid": testId,
       "aria-labelledby": heading.id,
-      ref: ref
+      ref: (0, _mergeRefs.default)([ref, localRef])
       // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop
       ,
       style: style,

package/dist/cjs/utils/use-focus-within/index.js

@@ -0,0 +1,51 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useFocusWithin = void 0;
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _react = require("react");
+var _bindEventListener = require("bind-event-listener");
+var _browserApis = require("@atlaskit/browser-apis");
+var useFocusWithin = exports.useFocusWithin = function useFocusWithin(ref) {
+  var _useState = (0, _react.useState)(null),
+    _useState2 = (0, _slicedToArray2.default)(_useState, 2),
+    active = _useState2[0],
+    setActive = _useState2[1];
+  var updateFocusedElement = (0, _react.useCallback)(function () {
+    var doc = (0, _browserApis.getDocument)();
+    var activeElement = (doc === null || doc === void 0 ? void 0 : doc.activeElement) || null;
+    if (!ref || !ref.current) {
+      setActive(null);
+      return;
+    }
+    if (!activeElement) {
+      setActive(null);
+      return;
+    }
+
+    // Check if the focused element is within the ref element
+    if (!ref.current.contains(activeElement)) {
+      setActive(null);
+      return;
+    }
+    setActive(activeElement);
+  }, [ref]);
+  (0, _react.useEffect)(function () {
+    var doc = (0, _browserApis.getDocument)();
+    if (!doc) {
+      return;
+    }
+    updateFocusedElement();
+    var unbindFocusIn = (0, _bindEventListener.bind)(doc, {
+      type: 'focusin',
+      listener: updateFocusedElement
+    });
+    return function () {
+      unbindFocusIn();
+    };
+  }, [updateFocusedElement]);
+  return active;
+};

package/dist/cjs/utils/use-on-escape/index.js

@@ -0,0 +1,40 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useOnEscape = void 0;
+var _react = require("react");
+var _bindEventListener = require("bind-event-listener");
+var _browserApis = require("@atlaskit/browser-apis");
+var onKeyDown = function onKeyDown(event, _ref) {
+  var onEscape = _ref.onEscape;
+  switch (event.key) {
+    case 'Escape':
+      onEscape();
+      break;
+    default:
+      break;
+  }
+};
+var useOnEscape = exports.useOnEscape = function useOnEscape(_onEscape) {
+  (0, _react.useEffect)(function () {
+    var doc = (0, _browserApis.getDocument)();
+    if (!doc) {
+      return;
+    }
+    var unbindFocusIn = (0, _bindEventListener.bind)(doc, {
+      type: 'keydown',
+      listener: function listener(event) {
+        return onKeyDown(event, {
+          onEscape: function onEscape() {
+            return _onEscape(event);
+          }
+        });
+      }
+    });
+    return function () {
+      unbindFocusIn();
+    };
+  }, [_onEscape]);
+};

package/dist/es2019/controllers/context.js

@@ -7,11 +7,21 @@ import { createContext, useId, useState } from 'react';
 
 // eslint-disable-next-line @repo/internal/react/require-jsdoc
 export const SpotlightContext = /*#__PURE__*/createContext({
-  placement: 'bottom-end',
-  setPlacement: () => undefined,
+  card: {
+    placement: 'bottom-end',
+    setPlacement: () => undefined
+  },
   heading: {
     id: '',
     setId: () => undefined
+  },
+  popoverContent: {
+    ref: undefined,
+    setRef: () => undefined,
+    update: () => () => new Promise(() => null),
+    setUpdate: () => () => new Promise(() => null),
+    dismiss: () => undefined,
+    setDismiss: () => () => undefined
   }
 });
 
@@ -22,13 +32,26 @@ export const SpotlightContextProvider = ({
   const id = useId();
   const [placement, setPlacement] = useState('bottom-end');
   const [headingId, setHeadingId] = useState(`${id}-heading`);
+  const [update, setUpdate] = useState(() => async () => undefined);
+  const [ref, setRef] = useState();
+  const [dismiss, setDismiss] = useState(() => undefined);
   return /*#__PURE__*/React.createElement(SpotlightContext.Provider, {
     value: {
-      placement,
-      setPlacement,
+      card: {
+        placement,
+        setPlacement
+      },
       heading: {
         id: headingId,
         setId: setHeadingId
+      },
+      popoverContent: {
+        ref,
+        setRef,
+        update,
+        setUpdate,
+        dismiss,
+        setDismiss
       }
     }
   }, children);

package/dist/es2019/index.js

@@ -13,4 +13,5 @@ export { SpotlightShowMoreControl } from './ui/show-more-control';
 export { SpotlightMedia } from './ui/media';
 export { PopoverProvider } from './ui/popover-provider';
 export { PopoverContent } from './ui/popover-content';
-export { PopoverTarget } from './ui/popover-target';
+export { PopoverTarget } from './ui/popover-target';
+export { UNSAFE_UpdateOnChange } from './ui/UNSAFE_update-on-change';

package/dist/es2019/ui/UNSAFE_update-on-change/index.js

@@ -0,0 +1,53 @@
+import { useContext, useEffect } from 'react';
+import { getDocument } from '@atlaskit/browser-apis';
+import { SpotlightContext } from '../../controllers/context';
+const defaultOptions = {
+  childList: true,
+  subtree: true
+};
+export const UNSAFE_UpdateOnChange = ({
+  selectors = ['body'],
+  options = defaultOptions
+}) => {
+  const {
+    popoverContent
+  } = useContext(SpotlightContext);
+  const {
+    update
+  } = popoverContent;
+  useEffect(() => {
+    if (!update || selectors.length === 0) {
+      return;
+    }
+    const doc = getDocument();
+    if (!doc) {
+      return;
+    }
+    const elements = new Set();
+    selectors.forEach(selector => {
+      const element = doc.querySelector(selector);
+      if (!element) {
+        return;
+      }
+      elements.add(element);
+    });
+    if (elements.size === 0) {
+      return;
+    }
+    const observers = [];
+    elements.forEach(element => {
+      const observer = new MutationObserver(mutations => {
+        if (mutations.length === 0) {
+          return;
+        }
+        update();
+      });
+      observer.observe(element, options);
+      observers.push(observer);
+    });
+    return () => {
+      observers.forEach(observer => observer.disconnect());
+    };
+  }, [selectors, options, update]);
+  return null;
+};

package/dist/es2019/ui/card/caret/index.js

@@ -27,11 +27,11 @@ export const Caret = /*#__PURE__*/forwardRef(({
   testId
 }, ref) => {
   const {
-    placement
+    card
   } = useContext(SpotlightContext);
   return /*#__PURE__*/React.createElement("div", {
     "data-testid": testId,
     ref: ref,
-    className: ax([styles.root, styles[placement]])
+    className: ax([styles.root, styles[card.placement]])
   });
 });

package/dist/es2019/ui/card/index.js

@@ -34,7 +34,7 @@ export const SpotlightCard = /*#__PURE__*/forwardRef(({
   testId
 }, ref) => {
   const {
-    placement
+    card
   } = useContext(SpotlightContext);
   return /*#__PURE__*/React.createElement("div", {
     "data-testid": testId,
@@ -42,6 +42,6 @@ export const SpotlightCard = /*#__PURE__*/forwardRef(({
     className: ax([styles.root])
   }, /*#__PURE__*/React.createElement(Caret, null), /*#__PURE__*/React.createElement(Box, {
     backgroundColor: "color.background.neutral.bold",
-    xcss: cx(styles.card, placementStyles[placement])
+    xcss: cx(styles.card, placementStyles[card.placement])
   }, children));
 });

package/dist/es2019/ui/popover-content/index.js

@@ -2,9 +2,12 @@
 import "./index.compiled.css";
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
-import { useContext, useEffect } from 'react';
+import { useContext, useEffect, useRef } from 'react';
+import mergeRefs from '@atlaskit/ds-lib/merge-refs';
 import { Popper } from '@atlaskit/popper';
 import { SpotlightContext } from '../../controllers/context';
+import { useFocusWithin } from '../../utils/use-focus-within';
+import { useOnEscape } from '../../utils/use-on-escape';
 const styles = {
   root: "_1pby1fw0"
 };
@@ -14,7 +17,7 @@ const styles = {
  * the caret extending beyond the bounding box (by roughly 2px). So, apply an offset to ensure
  * the caret points to the very edge of the target element.
  *
- * Note: `@atlaskit/popper` maps the offset to to the placement, so we only need to define `[0, 2]` and
+ * Note: `@atlaskit/popper` maps the offset to the placement, so we only need to define `[0, 2]` and
  * the offset will get correctly rotated depending on the placement.
  */
 const offset = [0, 2];
@@ -46,30 +49,54 @@ export const PopoverContent = ({
   children,
   placement,
   isVisible = true,
+  dismiss,
   testId
 }) => {
+  const updateRef = useRef(() => new Promise(() => undefined));
+  const ref = useRef();
   const {
-    setPlacement,
-    heading
+    heading,
+    popoverContent,
+    card
   } = useContext(SpotlightContext);
+  const focusWithin = useFocusWithin(popoverContent.ref);
   useEffect(() => {
-    setPlacement(placement);
-  }, [placement, setPlacement]);
+    popoverContent.setRef(ref);
+  }, [ref, popoverContent]);
+  useEffect(() => {
+    card.setPlacement(placement);
+  }, [placement, card]);
+  useEffect(() => {
+    if (updateRef.current) {
+      popoverContent.setUpdate(() => updateRef.current);
+    }
+  }, [popoverContent]);
+  useOnEscape(event => {
+    if (!focusWithin) {
+      return;
+    }
+    if (!dismiss) {
+      return;
+    }
+    dismiss(event);
+  });
   return /*#__PURE__*/React.createElement(Popper, {
     offset: offset,
     placement: popperPlacementMap[placement]
   }, ({
-    ref,
-    style
+    ref: localRef,
+    style,
+    update
   }) => {
     if (!isVisible) {
       return;
     }
+    updateRef.current = update;
     return /*#__PURE__*/React.createElement("div", {
       role: "dialog",
       "data-testid": testId,
       "aria-labelledby": heading.id,
-      ref: ref
+      ref: mergeRefs([ref, localRef])
       // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop
       ,
       style: style,

package/dist/es2019/utils/use-focus-within/index.js

@@ -0,0 +1,40 @@
+import { useCallback, useEffect, useState } from 'react';
+import { bind } from 'bind-event-listener';
+import { getDocument } from '@atlaskit/browser-apis';
+export const useFocusWithin = ref => {
+  const [active, setActive] = useState(null);
+  const updateFocusedElement = useCallback(() => {
+    const doc = getDocument();
+    const activeElement = (doc === null || doc === void 0 ? void 0 : doc.activeElement) || null;
+    if (!ref || !ref.current) {
+      setActive(null);
+      return;
+    }
+    if (!activeElement) {
+      setActive(null);
+      return;
+    }
+
+    // Check if the focused element is within the ref element
+    if (!ref.current.contains(activeElement)) {
+      setActive(null);
+      return;
+    }
+    setActive(activeElement);
+  }, [ref]);
+  useEffect(() => {
+    const doc = getDocument();
+    if (!doc) {
+      return;
+    }
+    updateFocusedElement();
+    const unbindFocusIn = bind(doc, {
+      type: 'focusin',
+      listener: updateFocusedElement
+    });
+    return () => {
+      unbindFocusIn();
+    };
+  }, [updateFocusedElement]);
+  return active;
+};

package/dist/es2019/utils/use-on-escape/index.js

@@ -0,0 +1,31 @@
+import { useEffect } from 'react';
+import { bind } from 'bind-event-listener';
+import { getDocument } from '@atlaskit/browser-apis';
+const onKeyDown = (event, {
+  onEscape
+}) => {
+  switch (event.key) {
+    case 'Escape':
+      onEscape();
+      break;
+    default:
+      break;
+  }
+};
+export const useOnEscape = onEscape => {
+  useEffect(() => {
+    const doc = getDocument();
+    if (!doc) {
+      return;
+    }
+    const unbindFocusIn = bind(doc, {
+      type: 'keydown',
+      listener: event => onKeyDown(event, {
+        onEscape: () => onEscape(event)
+      })
+    });
+    return () => {
+      unbindFocusIn();
+    };
+  }, [onEscape]);
+};

package/dist/esm/controllers/context.js

@@ -1,22 +1,54 @@
 /* context.tsx generated by @compiled/babel-plugin v0.38.1 */
+import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
 import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
+import _regeneratorRuntime from "@babel/runtime/regenerator";
 import { createContext, useId, useState } from 'react';
 
 // eslint-disable-next-line @repo/internal/react/consistent-types-definitions
 
 // eslint-disable-next-line @repo/internal/react/require-jsdoc
 export var SpotlightContext = /*#__PURE__*/createContext({
-  placement: 'bottom-end',
-  setPlacement: function setPlacement() {
-    return undefined;
+  card: {
+    placement: 'bottom-end',
+    setPlacement: function setPlacement() {
+      return undefined;
+    }
   },
   heading: {
     id: '',
     setId: function setId() {
       return undefined;
     }
+  },
+  popoverContent: {
+    ref: undefined,
+    setRef: function setRef() {
+      return undefined;
+    },
+    update: function update() {
+      return function () {
+        return new Promise(function () {
+          return null;
+        });
+      };
+    },
+    setUpdate: function setUpdate() {
+      return function () {
+        return new Promise(function () {
+          return null;
+        });
+      };
+    },
+    dismiss: function dismiss() {
+      return undefined;
+    },
+    setDismiss: function setDismiss() {
+      return function () {
+        return undefined;
+      };
+    }
   }
 });
 
@@ -32,13 +64,49 @@ export var SpotlightContextProvider = function SpotlightContextProvider(_ref) {
     _useState4 = _slicedToArray(_useState3, 2),
     headingId = _useState4[0],
     setHeadingId = _useState4[1];
+  var _useState5 = useState(function () {
+      return /*#__PURE__*/_asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee() {
+        return _regeneratorRuntime.wrap(function _callee$(_context) {
+          while (1) switch (_context.prev = _context.next) {
+            case 0:
+              return _context.abrupt("return", undefined);
+            case 1:
+            case "end":
+              return _context.stop();
+          }
+        }, _callee);
+      }));
+    }),
+    _useState6 = _slicedToArray(_useState5, 2),
+    update = _useState6[0],
+    setUpdate = _useState6[1];
+  var _useState7 = useState(),
+    _useState8 = _slicedToArray(_useState7, 2),
+    ref = _useState8[0],
+    setRef = _useState8[1];
+  var _useState9 = useState(function () {
+      return undefined;
+    }),
+    _useState0 = _slicedToArray(_useState9, 2),
+    dismiss = _useState0[0],
+    setDismiss = _useState0[1];
   return /*#__PURE__*/React.createElement(SpotlightContext.Provider, {
     value: {
-      placement: placement,
-      setPlacement: setPlacement,
+      card: {
+        placement: placement,
+        setPlacement: setPlacement
+      },
       heading: {
         id: headingId,
         setId: setHeadingId
+      },
+      popoverContent: {
+        ref: ref,
+        setRef: setRef,
+        update: update,
+        setUpdate: setUpdate,
+        dismiss: dismiss,
+        setDismiss: setDismiss
       }
     }
   }, children);

package/dist/esm/index.js

@@ -13,4 +13,5 @@ export { SpotlightShowMoreControl } from './ui/show-more-control';
 export { SpotlightMedia } from './ui/media';
 export { PopoverProvider } from './ui/popover-provider';
 export { PopoverContent } from './ui/popover-content';
-export { PopoverTarget } from './ui/popover-target';
+export { PopoverTarget } from './ui/popover-target';
+export { UNSAFE_UpdateOnChange } from './ui/UNSAFE_update-on-change';

package/dist/esm/ui/UNSAFE_update-on-change/index.js

@@ -0,0 +1,53 @@
+import { useContext, useEffect } from 'react';
+import { getDocument } from '@atlaskit/browser-apis';
+import { SpotlightContext } from '../../controllers/context';
+var defaultOptions = {
+  childList: true,
+  subtree: true
+};
+export var UNSAFE_UpdateOnChange = function UNSAFE_UpdateOnChange(_ref) {
+  var _ref$selectors = _ref.selectors,
+    selectors = _ref$selectors === void 0 ? ['body'] : _ref$selectors,
+    _ref$options = _ref.options,
+    options = _ref$options === void 0 ? defaultOptions : _ref$options;
+  var _useContext = useContext(SpotlightContext),
+    popoverContent = _useContext.popoverContent;
+  var update = popoverContent.update;
+  useEffect(function () {
+    if (!update || selectors.length === 0) {
+      return;
+    }
+    var doc = getDocument();
+    if (!doc) {
+      return;
+    }
+    var elements = new Set();
+    selectors.forEach(function (selector) {
+      var element = doc.querySelector(selector);
+      if (!element) {
+        return;
+      }
+      elements.add(element);
+    });
+    if (elements.size === 0) {
+      return;
+    }
+    var observers = [];
+    elements.forEach(function (element) {
+      var observer = new MutationObserver(function (mutations) {
+        if (mutations.length === 0) {
+          return;
+        }
+        update();
+      });
+      observer.observe(element, options);
+      observers.push(observer);
+    });
+    return function () {
+      observers.forEach(function (observer) {
+        return observer.disconnect();
+      });
+    };
+  }, [selectors, options, update]);
+  return null;
+};

package/dist/esm/ui/card/caret/index.js

@@ -26,10 +26,10 @@ var styles = {
 export var Caret = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var testId = _ref.testId;
   var _useContext = useContext(SpotlightContext),
-    placement = _useContext.placement;
+    card = _useContext.card;
   return /*#__PURE__*/React.createElement("div", {
     "data-testid": testId,
     ref: ref,
-    className: ax([styles.root, styles[placement]])
+    className: ax([styles.root, styles[card.placement]])
   });
 });

package/dist/esm/ui/card/index.js

@@ -33,13 +33,13 @@ export var SpotlightCard = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var children = _ref.children,
     testId = _ref.testId;
   var _useContext = useContext(SpotlightContext),
-    placement = _useContext.placement;
+    card = _useContext.card;
   return /*#__PURE__*/React.createElement("div", {
     "data-testid": testId,
     ref: ref,
     className: ax([styles.root])
   }, /*#__PURE__*/React.createElement(Caret, null), /*#__PURE__*/React.createElement(Box, {
     backgroundColor: "color.background.neutral.bold",
-    xcss: cx(styles.card, placementStyles[placement])
+    xcss: cx(styles.card, placementStyles[card.placement])
   }, children));
 });

package/dist/esm/ui/popover-content/index.js

@@ -2,9 +2,12 @@
 import "./index.compiled.css";
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
-import { useContext, useEffect } from 'react';
+import { useContext, useEffect, useRef } from 'react';
+import mergeRefs from '@atlaskit/ds-lib/merge-refs';
 import { Popper } from '@atlaskit/popper';
 import { SpotlightContext } from '../../controllers/context';
+import { useFocusWithin } from '../../utils/use-focus-within';
+import { useOnEscape } from '../../utils/use-on-escape';
 var styles = {
   root: "_1pby1fw0"
 };
@@ -14,7 +17,7 @@ var styles = {
  * the caret extending beyond the bounding box (by roughly 2px). So, apply an offset to ensure
  * the caret points to the very edge of the target element.
  *
- * Note: `@atlaskit/popper` maps the offset to to the placement, so we only need to define `[0, 2]` and
+ * Note: `@atlaskit/popper` maps the offset to the placement, so we only need to define `[0, 2]` and
  * the offset will get correctly rotated depending on the placement.
  */
 var offset = [0, 2];
@@ -47,27 +50,57 @@ export var PopoverContent = function PopoverContent(_ref) {
     placement = _ref.placement,
     _ref$isVisible = _ref.isVisible,
     isVisible = _ref$isVisible === void 0 ? true : _ref$isVisible,
+    dismiss = _ref.dismiss,
     testId = _ref.testId;
+  var updateRef = useRef(function () {
+    return new Promise(function () {
+      return undefined;
+    });
+  });
+  var ref = useRef();
   var _useContext = useContext(SpotlightContext),
-    setPlacement = _useContext.setPlacement,
-    heading = _useContext.heading;
+    heading = _useContext.heading,
+    popoverContent = _useContext.popoverContent,
+    card = _useContext.card;
+  var focusWithin = useFocusWithin(popoverContent.ref);
+  useEffect(function () {
+    popoverContent.setRef(ref);
+  }, [ref, popoverContent]);
+  useEffect(function () {
+    card.setPlacement(placement);
+  }, [placement, card]);
   useEffect(function () {
-    setPlacement(placement);
-  }, [placement, setPlacement]);
+    if (updateRef.current) {
+      popoverContent.setUpdate(function () {
+        return updateRef.current;
+      });
+    }
+  }, [popoverContent]);
+  useOnEscape(function (event) {
+    if (!focusWithin) {
+      return;
+    }
+    if (!dismiss) {
+      return;
+    }
+    dismiss(event);
+  });
   return /*#__PURE__*/React.createElement(Popper, {
     offset: offset,
     placement: popperPlacementMap[placement]
   }, function (_ref2) {
-    var ref = _ref2.ref,
-      style = _ref2.style;
+    var localRef = _ref2.ref,
+      style = _ref2.style,
+      update = _ref2.update;
     if (!isVisible) {
       return;
     }
+    updateRef.current = update;
     return /*#__PURE__*/React.createElement("div", {
       role: "dialog",
       "data-testid": testId,
       "aria-labelledby": heading.id,
-      ref: ref
+      ref: mergeRefs([ref, localRef])
       // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop
       ,
       style: style,

package/dist/esm/utils/use-focus-within/index.js

@@ -0,0 +1,44 @@
+import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
+import { useCallback, useEffect, useState } from 'react';
+import { bind } from 'bind-event-listener';
+import { getDocument } from '@atlaskit/browser-apis';
+export var useFocusWithin = function useFocusWithin(ref) {
+  var _useState = useState(null),
+    _useState2 = _slicedToArray(_useState, 2),
+    active = _useState2[0],
+    setActive = _useState2[1];
+  var updateFocusedElement = useCallback(function () {
+    var doc = getDocument();
+    var activeElement = (doc === null || doc === void 0 ? void 0 : doc.activeElement) || null;
+    if (!ref || !ref.current) {
+      setActive(null);
+      return;
+    }
+    if (!activeElement) {
+      setActive(null);
+      return;
+    }
+
+    // Check if the focused element is within the ref element
+    if (!ref.current.contains(activeElement)) {
+      setActive(null);
+      return;
+    }
+    setActive(activeElement);
+  }, [ref]);
+  useEffect(function () {
+    var doc = getDocument();
+    if (!doc) {
+      return;
+    }
+    updateFocusedElement();
+    var unbindFocusIn = bind(doc, {
+      type: 'focusin',
+      listener: updateFocusedElement
+    });
+    return function () {
+      unbindFocusIn();
+    };
+  }, [updateFocusedElement]);
+  return active;
+};

package/dist/esm/utils/use-on-escape/index.js

@@ -0,0 +1,34 @@
+import { useEffect } from 'react';
+import { bind } from 'bind-event-listener';
+import { getDocument } from '@atlaskit/browser-apis';
+var onKeyDown = function onKeyDown(event, _ref) {
+  var onEscape = _ref.onEscape;
+  switch (event.key) {
+    case 'Escape':
+      onEscape();
+      break;
+    default:
+      break;
+  }
+};
+export var useOnEscape = function useOnEscape(_onEscape) {
+  useEffect(function () {
+    var doc = getDocument();
+    if (!doc) {
+      return;
+    }
+    var unbindFocusIn = bind(doc, {
+      type: 'keydown',
+      listener: function listener(event) {
+        return onKeyDown(event, {
+          onEscape: function onEscape() {
+            return _onEscape(event);
+          }
+        });
+      }
+    });
+    return function () {
+      unbindFocusIn();
+    };
+  }, [_onEscape]);
+};

package/dist/types/controllers/context.d.ts

@@ -2,18 +2,27 @@
  * @jsxRuntime classic
  * @jsx jsx
  */
-import { type Dispatch, type ReactNode, type SetStateAction } from 'react';
+import { type Dispatch, type MutableRefObject, type ReactNode, type SetStateAction } from 'react';
 import type { Placement } from '../types';
-interface SpotlightContextType {
-    placement: Placement;
-    setPlacement: Dispatch<SetStateAction<Placement>>;
+export interface SpotlightContextType {
+    card: {
+        placement: Placement;
+        setPlacement: Dispatch<SetStateAction<Placement>>;
+    };
     heading: {
         id: string;
         setId: Dispatch<SetStateAction<string>>;
     };
+    popoverContent: {
+        ref: MutableRefObject<HTMLDivElement | undefined> | undefined;
+        setRef: Dispatch<SetStateAction<MutableRefObject<HTMLDivElement | undefined> | undefined>>;
+        update: () => () => Promise<any>;
+        setUpdate: Dispatch<SetStateAction<() => () => Promise<any>>>;
+        dismiss: () => void;
+        setDismiss: Dispatch<SetStateAction<() => void>>;
+    };
 }
 export declare const SpotlightContext: import("react").Context<SpotlightContextType>;
 export declare const SpotlightContextProvider: ({ children }: {
     children: ReactNode;
 }) => JSX.Element;
-export {};

package/dist/types/index.d.ts

@@ -15,3 +15,4 @@ export { PopoverProvider } from './ui/popover-provider';
 export { PopoverContent, type PopoverContentProps } from './ui/popover-content';
 export { PopoverTarget } from './ui/popover-target';
 export { type Placement } from './types';
+export { UNSAFE_UpdateOnChange } from './ui/UNSAFE_update-on-change';

package/dist/types/ui/UNSAFE_update-on-change/index.d.ts

@@ -0,0 +1,6 @@
+interface UpdateOnChangeProps {
+    selectors?: string[];
+    options?: MutationObserverInit;
+}
+export declare const UNSAFE_UpdateOnChange: ({ selectors, options, }: UpdateOnChangeProps) => null;
+export {};

package/dist/types/ui/popover-content/index.d.ts

@@ -13,6 +13,7 @@ export interface PopoverContentProps {
     testId?: string;
     placement: Placement;
     isVisible?: boolean;
+    dismiss?: (event: KeyboardEvent) => void;
     children: ReactNode;
 }
 /**
@@ -20,4 +21,4 @@ export interface PopoverContentProps {
  *
  * A `PopoverContent` is the element that is shown as a popover.
  */
-export declare const PopoverContent: ({ children, placement, isVisible, testId, }: PopoverContentProps) => JSX.Element;
+export declare const PopoverContent: ({ children, placement, isVisible, dismiss, testId, }: PopoverContentProps) => JSX.Element;

package/dist/types/utils/use-focus-within/index.d.ts

@@ -0,0 +1,2 @@
+import { type MutableRefObject } from 'react';
+export declare const useFocusWithin: (ref: MutableRefObject<HTMLDivElement | undefined> | undefined) => Element | null;

package/dist/types/utils/use-on-escape/index.d.ts

@@ -0,0 +1 @@
+export declare const useOnEscape: (onEscape: (event: KeyboardEvent) => void) => void;

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

@@ -2,18 +2,27 @@
  * @jsxRuntime classic
  * @jsx jsx
  */
-import { type Dispatch, type ReactNode, type SetStateAction } from 'react';
+import { type Dispatch, type MutableRefObject, type ReactNode, type SetStateAction } from 'react';
 import type { Placement } from '../types';
-interface SpotlightContextType {
-    placement: Placement;
-    setPlacement: Dispatch<SetStateAction<Placement>>;
+export interface SpotlightContextType {
+    card: {
+        placement: Placement;
+        setPlacement: Dispatch<SetStateAction<Placement>>;
+    };
     heading: {
         id: string;
         setId: Dispatch<SetStateAction<string>>;
     };
+    popoverContent: {
+        ref: MutableRefObject<HTMLDivElement | undefined> | undefined;
+        setRef: Dispatch<SetStateAction<MutableRefObject<HTMLDivElement | undefined> | undefined>>;
+        update: () => () => Promise<any>;
+        setUpdate: Dispatch<SetStateAction<() => () => Promise<any>>>;
+        dismiss: () => void;
+        setDismiss: Dispatch<SetStateAction<() => void>>;
+    };
 }
 export declare const SpotlightContext: import("react").Context<SpotlightContextType>;
 export declare const SpotlightContextProvider: ({ children }: {
     children: ReactNode;
 }) => JSX.Element;
-export {};

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

@@ -15,3 +15,4 @@ export { PopoverProvider } from './ui/popover-provider';
 export { PopoverContent, type PopoverContentProps } from './ui/popover-content';
 export { PopoverTarget } from './ui/popover-target';
 export { type Placement } from './types';
+export { UNSAFE_UpdateOnChange } from './ui/UNSAFE_update-on-change';

package/dist/types-ts4.5/ui/UNSAFE_update-on-change/index.d.ts

@@ -0,0 +1,6 @@
+interface UpdateOnChangeProps {
+    selectors?: string[];
+    options?: MutationObserverInit;
+}
+export declare const UNSAFE_UpdateOnChange: ({ selectors, options, }: UpdateOnChangeProps) => null;
+export {};

package/dist/types-ts4.5/ui/popover-content/index.d.ts

@@ -13,6 +13,7 @@ export interface PopoverContentProps {
     testId?: string;
     placement: Placement;
     isVisible?: boolean;
+    dismiss?: (event: KeyboardEvent) => void;
     children: ReactNode;
 }
 /**
@@ -20,4 +21,4 @@ export interface PopoverContentProps {
  *
  * A `PopoverContent` is the element that is shown as a popover.
  */
-export declare const PopoverContent: ({ children, placement, isVisible, testId, }: PopoverContentProps) => JSX.Element;
+export declare const PopoverContent: ({ children, placement, isVisible, dismiss, testId, }: PopoverContentProps) => JSX.Element;

package/dist/types-ts4.5/utils/use-focus-within/index.d.ts

@@ -0,0 +1,2 @@
+import { type MutableRefObject } from 'react';
+export declare const useFocusWithin: (ref: MutableRefObject<HTMLDivElement | undefined> | undefined) => Element | null;

package/dist/types-ts4.5/utils/use-on-escape/index.d.ts

@@ -0,0 +1 @@
+export declare const useOnEscape: (onEscape: (event: KeyboardEvent) => void) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/spotlight",
-	"version": "0.4.1",
+	"version": "0.5.1",
 	"description": "A spotlight introduces users to various points of interest across Atlassian through focused messages or multi-step tours.",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -26,17 +26,20 @@
 	],
 	"atlaskit:src": "src/index.tsx",
 	"dependencies": {
-		"@atlaskit/button": "^23.4.0",
+		"@atlaskit/browser-apis": "^0.0.1",
+		"@atlaskit/button": "^23.5.0",
 		"@atlaskit/css": "^0.14.0",
+		"@atlaskit/ds-lib": "^5.1.0",
 		"@atlaskit/heading": "^5.2.0",
-		"@atlaskit/icon": "^28.3.0",
+		"@atlaskit/icon": "^28.5.0",
 		"@atlaskit/image": "^3.0.0",
 		"@atlaskit/popper": "^7.1.0",
 		"@atlaskit/primitives": "^14.15.0",
 		"@atlaskit/tokens": "^6.4.0",
 		"@atlaskit/visually-hidden": "^3.0.0",
 		"@babel/runtime": "^7.0.0",
-		"@compiled/react": "^0.18.3"
+		"@compiled/react": "^0.18.3",
+		"bind-event-listener": "^3.0.0"
 	},
 	"peerDependencies": {
 		"react": "^18.2.0"