@atlaskit/spotlight 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @atlaskit/spotlight
 
+## 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/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/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/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/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/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.4",
 	"description": "A spotlight introduces users to points of interest, from focused messages to multi-step tours.",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",