@atlaskit/spotlight 0.9.3 → 0.9.5

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @atlaskit/spotlight
 
+## 0.9.5
+
+### Patch Changes
+
+- [`e0d5103c4e6cd`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/e0d5103c4e6cd) -
+  Expose `strategy` prop on `PopoverContent` which is passed through to the underlying
+  `react-popper`.
+
+## 0.9.4
+
+### Patch Changes
+
+- [`063f646d9daec`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/063f646d9daec) -
+  Added `usePreloadMedia` hook to preload video and image assets before they are rendered in the
+  DOM.
+
+  This hook is useful in the context of `@atlaskit/spotlight` where by default media will only load
+  when `PopoverContent.isVisible` is set to true. `usePreloadMedia` preloads the assets for better
+  performance and user experience. The hook accepts a source URL and a MIME type, creates a
+  temporary media element to trigger browser caching, and the cached asset will be used when the
+  actual media element is rendered.
+
+  Supported MIME types:
+  - Videos: `video/mp4`, `video/webm`, `video/ogg`, `video/mpeg`, `video/x-matroska`
+  - Images: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/svg+xml`
+
+  Example usage: usePreloadMedia(videoSrc, { mimetype: 'video/mp4' });
+
 ## 0.9.3
 
 ### Patch Changes

package/constellation/index/usage.mdx

@@ -19,6 +19,8 @@ Spotlights are most effective for onboarding new users, driving feature discover
 important changes. Use them sparingly. If your UI needs frequent spotlights, consider simplifying
 the core experience instead.
 
+[Track and reduce message fatigue with Post Office (Atlassians only)](https://go.atlassian.com/use-post-office)
+
 ### Single-step spotlight
 
 The ideal spotlight experience is lightweight and a single-step. Always try to limit your experience

package/dist/cjs/index.js

@@ -105,6 +105,12 @@ Object.defineProperty(exports, "UNSAFE_UpdateOnChange", {
     return _UNSAFE_updateOnChange.UNSAFE_UpdateOnChange;
   }
 });
+Object.defineProperty(exports, "usePreloadMedia", {
+  enumerable: true,
+  get: function get() {
+    return _usePreloadMedia.usePreloadMedia;
+  }
+});
 var _card = require("./ui/card");
 var _body = require("./ui/body");
 var _header = require("./ui/header");
@@ -121,4 +127,5 @@ var _media = require("./ui/media");
 var _popoverProvider = require("./ui/popover-provider");
 var _popoverContent = require("./ui/popover-content");
 var _popoverTarget = require("./ui/popover-target");
-var _UNSAFE_updateOnChange = require("./ui/UNSAFE_update-on-change");
+var _UNSAFE_updateOnChange = require("./ui/UNSAFE_update-on-change");
+var _usePreloadMedia = require("./utils/use-preload-media");

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

@@ -70,7 +70,8 @@ var PopoverContent = exports.PopoverContent = function PopoverContent(props) {
     back = props.back,
     testId = props.testId,
     _props$offset = props.offset,
-    offset = _props$offset === void 0 ? defaultOffset : _props$offset;
+    offset = _props$offset === void 0 ? defaultOffset : _props$offset,
+    strategy = props.strategy;
 
   /**
    * A user should only be able to pass a `done` or a `next`. Not both.
@@ -140,6 +141,7 @@ var PopoverContent = exports.PopoverContent = function PopoverContent(props) {
   });
   return /*#__PURE__*/React.createElement(_popper.Popper, {
     offset: offset,
+    strategy: strategy,
     placement: popperPlacementMap[placement]
   }, function (_ref) {
     var localRef = _ref.ref,

package/dist/cjs/utils/use-preload-media/index.js

@@ -0,0 +1,62 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.usePreloadMedia = void 0;
+var _react = require("react");
+var _browserApis = require("@atlaskit/browser-apis");
+var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
+// eslint-disable-next-line @repo/internal/react/consistent-types-definitions
+
+/**
+ * Preloads media (video/image) files to be cached by the browser.
+ * Once loaded, the browser cache will be used when rendering the actual media element.
+ *
+ * @param src - The media source URL to preload
+ * @param options - Configuration options including the MIME type
+ */
+var usePreloadMedia = exports.usePreloadMedia = function usePreloadMedia(src, options) {
+  (0, _react.useEffect)(function () {
+    var handler = mimeTypeHandlers[options.mimetype];
+    return handler(src);
+  }, [src, options.mimetype]);
+};
+var preloadVideo = function preloadVideo(src) {
+  var doc = (0, _browserApis.getDocument)();
+  if (!doc) {
+    return _noop.default;
+  }
+  var video = doc.createElement('video');
+  video.src = src;
+  video.preload = 'auto';
+  video.load();
+  return function () {
+    video.src = '';
+    video.load();
+  };
+};
+var preloadImage = function preloadImage(src) {
+  var doc = (0, _browserApis.getDocument)();
+  if (!doc) {
+    return _noop.default;
+  }
+  var img = new Image();
+  img.src = src;
+  return function () {
+    img.src = '';
+  };
+};
+var mimeTypeHandlers = {
+  'video/mp4': preloadVideo,
+  'video/webm': preloadVideo,
+  'video/ogg': preloadVideo,
+  'video/mpeg': preloadVideo,
+  'video/x-matroska': preloadVideo,
+  'image/jpeg': preloadImage,
+  'image/png': preloadImage,
+  'image/gif': preloadImage,
+  'image/webp': preloadImage,
+  'image/svg+xml': preloadImage
+};

package/dist/es2019/index.js

@@ -14,4 +14,5 @@ export { SpotlightMedia } from './ui/media';
 export { PopoverProvider } from './ui/popover-provider';
 export { PopoverContent } from './ui/popover-content';
 export { PopoverTarget } from './ui/popover-target';
-export { UNSAFE_UpdateOnChange } from './ui/UNSAFE_update-on-change';
+export { UNSAFE_UpdateOnChange } from './ui/UNSAFE_update-on-change';
+export { usePreloadMedia } from './utils/use-preload-media';

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

@@ -59,7 +59,8 @@ export const PopoverContent = props => {
     dismiss,
     back,
     testId,
-    offset = defaultOffset
+    offset = defaultOffset,
+    strategy
   } = props;
 
   /**
@@ -125,6 +126,7 @@ export const PopoverContent = props => {
   });
   return /*#__PURE__*/React.createElement(Popper, {
     offset: offset,
+    strategy: strategy,
     placement: popperPlacementMap[placement]
   }, ({
     ref: localRef,

package/dist/es2019/utils/use-preload-media/index.js

@@ -0,0 +1,56 @@
+import { useEffect } from 'react';
+import { getDocument } from '@atlaskit/browser-apis';
+import __noop from '@atlaskit/ds-lib/noop';
+
+// eslint-disable-next-line @repo/internal/react/consistent-types-definitions
+
+/**
+ * Preloads media (video/image) files to be cached by the browser.
+ * Once loaded, the browser cache will be used when rendering the actual media element.
+ *
+ * @param src - The media source URL to preload
+ * @param options - Configuration options including the MIME type
+ */
+export const usePreloadMedia = (src, options) => {
+  useEffect(() => {
+    const handler = mimeTypeHandlers[options.mimetype];
+    return handler(src);
+  }, [src, options.mimetype]);
+};
+const preloadVideo = src => {
+  const doc = getDocument();
+  if (!doc) {
+    return __noop;
+  }
+  const video = doc.createElement('video');
+  video.src = src;
+  video.preload = 'auto';
+  video.load();
+  return () => {
+    video.src = '';
+    video.load();
+  };
+};
+const preloadImage = src => {
+  const doc = getDocument();
+  if (!doc) {
+    return __noop;
+  }
+  const img = new Image();
+  img.src = src;
+  return () => {
+    img.src = '';
+  };
+};
+const mimeTypeHandlers = {
+  'video/mp4': preloadVideo,
+  'video/webm': preloadVideo,
+  'video/ogg': preloadVideo,
+  'video/mpeg': preloadVideo,
+  'video/x-matroska': preloadVideo,
+  'image/jpeg': preloadImage,
+  'image/png': preloadImage,
+  'image/gif': preloadImage,
+  'image/webp': preloadImage,
+  'image/svg+xml': preloadImage
+};

package/dist/esm/index.js

@@ -14,4 +14,5 @@ export { SpotlightMedia } from './ui/media';
 export { PopoverProvider } from './ui/popover-provider';
 export { PopoverContent } from './ui/popover-content';
 export { PopoverTarget } from './ui/popover-target';
-export { UNSAFE_UpdateOnChange } from './ui/UNSAFE_update-on-change';
+export { UNSAFE_UpdateOnChange } from './ui/UNSAFE_update-on-change';
+export { usePreloadMedia } from './utils/use-preload-media';

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

@@ -61,7 +61,8 @@ export var PopoverContent = function PopoverContent(props) {
     back = props.back,
     testId = props.testId,
     _props$offset = props.offset,
-    offset = _props$offset === void 0 ? defaultOffset : _props$offset;
+    offset = _props$offset === void 0 ? defaultOffset : _props$offset,
+    strategy = props.strategy;
 
   /**
    * A user should only be able to pass a `done` or a `next`. Not both.
@@ -131,6 +132,7 @@ export var PopoverContent = function PopoverContent(props) {
   });
   return /*#__PURE__*/React.createElement(Popper, {
     offset: offset,
+    strategy: strategy,
     placement: popperPlacementMap[placement]
   }, function (_ref) {
     var localRef = _ref.ref,

package/dist/esm/utils/use-preload-media/index.js

@@ -0,0 +1,56 @@
+import { useEffect } from 'react';
+import { getDocument } from '@atlaskit/browser-apis';
+import __noop from '@atlaskit/ds-lib/noop';
+
+// eslint-disable-next-line @repo/internal/react/consistent-types-definitions
+
+/**
+ * Preloads media (video/image) files to be cached by the browser.
+ * Once loaded, the browser cache will be used when rendering the actual media element.
+ *
+ * @param src - The media source URL to preload
+ * @param options - Configuration options including the MIME type
+ */
+export var usePreloadMedia = function usePreloadMedia(src, options) {
+  useEffect(function () {
+    var handler = mimeTypeHandlers[options.mimetype];
+    return handler(src);
+  }, [src, options.mimetype]);
+};
+var preloadVideo = function preloadVideo(src) {
+  var doc = getDocument();
+  if (!doc) {
+    return __noop;
+  }
+  var video = doc.createElement('video');
+  video.src = src;
+  video.preload = 'auto';
+  video.load();
+  return function () {
+    video.src = '';
+    video.load();
+  };
+};
+var preloadImage = function preloadImage(src) {
+  var doc = getDocument();
+  if (!doc) {
+    return __noop;
+  }
+  var img = new Image();
+  img.src = src;
+  return function () {
+    img.src = '';
+  };
+};
+var mimeTypeHandlers = {
+  'video/mp4': preloadVideo,
+  'video/webm': preloadVideo,
+  'video/ogg': preloadVideo,
+  'video/mpeg': preloadVideo,
+  'video/x-matroska': preloadVideo,
+  'image/jpeg': preloadImage,
+  'image/png': preloadImage,
+  'image/gif': preloadImage,
+  'image/webp': preloadImage,
+  'image/svg+xml': preloadImage
+};

package/dist/types/index.d.ts

@@ -16,3 +16,4 @@ export { PopoverContent, type PopoverContentProps } from './ui/popover-content';
 export { PopoverTarget } from './ui/popover-target';
 export { type Placement, type DismissEvent } from './types';
 export { UNSAFE_UpdateOnChange } from './ui/UNSAFE_update-on-change';
+export { usePreloadMedia } from './utils/use-preload-media';

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

@@ -8,6 +8,7 @@ import type { BackEvent, DismissEvent, DoneEvent, NextEvent, Placement } from '.
  * Taken from `@atlaskit/popper`
  */
 type Offset = [number | null | undefined, number | null | undefined];
+type Strategy = 'absolute' | 'fixed';
 interface BasePopoverContentProps {
     /**
      * A `testId` prop is provided for specified elements, which is a unique
@@ -48,6 +49,13 @@ interface BasePopoverContentProps {
      * by the `placement` prop.
      */
     offset?: Offset;
+    /**
+     * Describes the positioning strategy to use. By default, it is `absolute`, which in the simplest cases does not require
+     * repositioning of the popper. If your reference element is in a fixed container, use the `fixed` strategy
+     *
+     * For more details see: https://popper.js.org/docs/v2/constructors/#strategy
+     */
+    strategy?: Strategy;
     /**
      * The content to be rendered in `PopoverContent`. This is intended to be a `SpotlightCard`.
      */

package/dist/types/utils/use-preload-media/index.d.ts

@@ -0,0 +1,13 @@
+type MimeType = 'video/mp4' | 'video/webm' | 'video/ogg' | 'video/mpeg' | 'video/x-matroska' | 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp' | 'image/svg+xml';
+interface PreloadMediaOptions {
+    mimetype: MimeType;
+}
+/**
+ * Preloads media (video/image) files to be cached by the browser.
+ * Once loaded, the browser cache will be used when rendering the actual media element.
+ *
+ * @param src - The media source URL to preload
+ * @param options - Configuration options including the MIME type
+ */
+export declare const usePreloadMedia: (src: string, options: PreloadMediaOptions) => void;
+export {};

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

@@ -16,3 +16,4 @@ export { PopoverContent, type PopoverContentProps } from './ui/popover-content';
 export { PopoverTarget } from './ui/popover-target';
 export { type Placement, type DismissEvent } from './types';
 export { UNSAFE_UpdateOnChange } from './ui/UNSAFE_update-on-change';
+export { usePreloadMedia } from './utils/use-preload-media';

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

@@ -11,6 +11,7 @@ type Offset = [
     number | null | undefined,
     number | null | undefined
 ];
+type Strategy = 'absolute' | 'fixed';
 interface BasePopoverContentProps {
     /**
      * A `testId` prop is provided for specified elements, which is a unique
@@ -51,6 +52,13 @@ interface BasePopoverContentProps {
      * by the `placement` prop.
      */
     offset?: Offset;
+    /**
+     * Describes the positioning strategy to use. By default, it is `absolute`, which in the simplest cases does not require
+     * repositioning of the popper. If your reference element is in a fixed container, use the `fixed` strategy
+     *
+     * For more details see: https://popper.js.org/docs/v2/constructors/#strategy
+     */
+    strategy?: Strategy;
     /**
      * The content to be rendered in `PopoverContent`. This is intended to be a `SpotlightCard`.
      */

package/dist/types-ts4.5/utils/use-preload-media/index.d.ts

@@ -0,0 +1,13 @@
+type MimeType = 'video/mp4' | 'video/webm' | 'video/ogg' | 'video/mpeg' | 'video/x-matroska' | 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp' | 'image/svg+xml';
+interface PreloadMediaOptions {
+    mimetype: MimeType;
+}
+/**
+ * Preloads media (video/image) files to be cached by the browser.
+ * Once loaded, the browser cache will be used when rendering the actual media element.
+ *
+ * @param src - The media source URL to preload
+ * @param options - Configuration options including the MIME type
+ */
+export declare const usePreloadMedia: (src: string, options: PreloadMediaOptions) => void;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/spotlight",
-	"version": "0.9.3",
+	"version": "0.9.5",
 	"description": "A spotlight introduces users to points of interest, from focused messages to multi-step tours.",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",