@atlaskit/media-viewer 54.8.44 → 54.9.1

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @atlaskit/media-viewer
 
+## 54.9.1
+
+### Patch Changes
+
+- Updated dependencies
+
+## 54.9.0
+
+### Minor Changes
+
+- [`a432278c5cb5c`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/a432278c5cb5c) -
+  [ux] Add opt-in consumer extension points so a product can host its own sidebar content — such as
+  Confluence comments — inside Media Viewer, and restore that viewer state across remounts. All of
+  the new behaviour is gated behind the `cc_comments_media_viewer_sidebar` experiment; with the
+  experiment off both packages behave exactly as before.
+
+  `@atlaskit/media-viewer` adds nine optional fields to `MediaViewerExtensions` and exports the new
+  `MediaViewerNavigationDirection` type. Consumers can intercept the close and navigate paths with
+  `onPreviewClose`, `onSidebarClose` and `onNavigation` — each receives a `proceed()` callback, so a
+  consumer can defer or swallow the action while, for example, prompting about an unsaved comment.
+  Viewer state can be persisted and restored through `getMediaViewerSelectedItem`,
+  `onSelectedItemChange`, `defaultSidebarVisible` and `onSidebarVisibilityChange`, and the existing
+  `sidebar` extension accepts `label` and `title`. The previously shipped `sidebar` and
+  `headerActions` fields are unchanged and are not gated.
+
+  `@atlaskit/media-card` adds no new prop of its own, but `Card`/`FileCard` consumers can now pass
+  `getMediaViewerSelectedItem` and `onSelectedItemChange` through the existing
+  `mediaViewerExtensions` prop to seed the Media Viewer selected item on mount and be notified when
+  it opens or closes — new remount-restore behaviour that also requires this release of
+  `@atlaskit/media-viewer` to typecheck.
+
+  Both packages add `@atlaskit/platform-feature-experiments` as a runtime dependency.
+
+### Patch Changes
+
+- [`ae39a248bd118`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/ae39a248bd118) -
+  FFCLEANUP-147994 clean up fg relating to fallback media name fetcher
+  platform_editor_media_name_fallback, platform_editor_media_file_rename_on_fallback,
+  platform_editor_media_file_rename_on_fallback, platform_editor_media_name_fallback_viewer_card
+- Updated dependencies
+
 ## 54.8.44
 
 ### Patch Changes

package/dist/cjs/analytics/ufoExperiences.js

@@ -14,7 +14,7 @@ var _experienceTypes = require("@atlaskit/ufo/experience-types");
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 var packageName = "@atlaskit/media-viewer";
-var packageVersion = "54.8.43";
+var packageVersion = "54.9.0";
 var ufoExperience;
 var getExperience = function getExperience() {
   if (!ufoExperience) {

package/dist/cjs/createItemDownloader.js

@@ -8,7 +8,6 @@ exports.createItemDownloader = void 0;
 var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 var _mediaClient = require("@atlaskit/media-client");
-var _expValEquals = require("@atlaskit/tmp-editor-statsig/exp-val-equals");
 var _createDownloadFailedEventPayload = require("./analytics/events/operational/createDownloadFailedEventPayload");
 var _createDownloadSucceededEventPayload = require("./analytics/events/operational/createDownloadSucceededEventPayload");
 var _fireAnalytics = require("./analytics/fireAnalytics");
@@ -22,7 +21,7 @@ var createItemDownloader = exports.createItemDownloader = function createItemDow
           collectionName = options.collectionName, traceContext = options.traceContext, createAnalyticsEvent = options.createAnalyticsEvent, fallbackMediaName = options.fallbackMediaName;
           id = file.id;
           fileStateName = !(0, _mediaClient.isErrorFileState)(file) ? file.name : undefined;
-          name = fileStateName || ((0, _expValEquals.expValEquals)('platform_editor_media_download_fallback_name', 'isEnabled', true) ? fallbackMediaName : undefined);
+          name = fileStateName || fallbackMediaName;
           mediaClient.file.downloadBinary(id, name, collectionName, traceContext).then(function () {
             (0, _fireAnalytics.fireAnalytics)((0, _createDownloadSucceededEventPayload.createDownloadSucceededEventPayload)(file, traceContext), createAnalyticsEvent);
           }).catch(function (e) {

package/dist/cjs/header.js

@@ -22,7 +22,6 @@ var _MediaButton = _interopRequireDefault(require("@atlaskit/media-ui/MediaButto
 var _messages = require("@atlaskit/media-ui/messages");
 var _mimeTypeIcon = require("@atlaskit/media-ui/mime-type-icon");
 var _fg = require("@atlaskit/platform-feature-flags/fg");
-var _expValEquals = require("@atlaskit/tmp-editor-statsig/exp-val-equals");
 var _outcome = require("./domain/outcome");
 var _download = require("./download");
 var _MediaViewerError = require("./MediaViewerError");
@@ -109,12 +108,12 @@ var Header = exports.Header = function Header(_ref) {
   (0, _react.useEffect)(function () {
     // Reset fetch state when the file identity changes (e.g. navigating in viewer)
     var currentId = (fileState === null || fileState === void 0 ? void 0 : fileState.status) !== 'error' ? fileState === null || fileState === void 0 ? void 0 : fileState.id : undefined;
-    if (currentId && currentId !== lastFetchedFileId.current && (0, _expValEquals.expValEquals)('platform_editor_media_name_fallback_viewer_card', 'isEnabled', true)) {
+    if (currentId && currentId !== lastFetchedFileId.current) {
       fallbackMediaNameFetchAttempted.current = false;
       setFallbackMediaName(undefined);
       lastFetchedFileId.current = currentId;
     }
-    if (fileState && fileState.status !== 'error' && !fileState.name && fallbackMediaNameFetcher && !fallbackMediaNameFetchAttempted.current && (0, _expValEquals.expValEquals)('platform_editor_media_name_fallback_viewer_card', 'isEnabled', true)) {
+    if (fileState && fileState.status !== 'error' && !fileState.name && fallbackMediaNameFetcher && !fallbackMediaNameFetchAttempted.current) {
       fallbackMediaNameFetchAttempted.current = true;
       fallbackMediaNameFetcher(fileState.id).then(function (name) {
         setFallbackMediaName(name);
@@ -170,7 +169,7 @@ var Header = exports.Header = function Header(_ref) {
         name: item.name
       })), /*#__PURE__*/_react.default.createElement(_styleWrappers.MedatadataTextWrapper, null, /*#__PURE__*/_react.default.createElement(_styleWrappers.MetadataFileName, {
         "data-testid": "media-viewer-file-name"
-      }, item.name || (0, _expValEquals.expValEquals)('platform_editor_media_name_fallback_viewer_card', 'isEnabled', true) && fallbackMediaName || /*#__PURE__*/_react.default.createElement(_reactIntl.FormattedMessage, _messages.messages.unknown)), /*#__PURE__*/_react.default.createElement(_styleWrappers.MetadataSubText, {
+      }, item.name || fallbackMediaName || /*#__PURE__*/_react.default.createElement(_reactIntl.FormattedMessage, _messages.messages.unknown)), /*#__PURE__*/_react.default.createElement(_styleWrappers.MetadataSubText, {
         "data-testid": "media-viewer-file-metadata-text"
       }, /*#__PURE__*/_react.default.createElement(_styleWrappers.FormattedMessageWrapper, null, renderFileTypeText(item)), item.size ? ' · ' + (0, _humanReadableSize.toHumanReadableMediaSize)(item.size) : '')));
     },

package/dist/cjs/list.js

@@ -25,6 +25,7 @@ var List = exports.List = function List(_ref) {
     featureFlags = _ref.featureFlags,
     isSidebarVisible = _ref.isSidebarVisible,
     onNavigationChange = _ref.onNavigationChange,
+    onNavigationRequest = _ref.onNavigationRequest,
     items = _ref.items,
     viewerOptions = _ref.viewerOptions,
     fallbackMediaNameFetcher = _ref.fallbackMediaNameFetcher;
@@ -71,11 +72,18 @@ var List = exports.List = function List(_ref) {
   }), /*#__PURE__*/_react.default.createElement(_navigation.Navigation, {
     items: items,
     selectedItem: selectedItem,
-    onChange: function onChange(selectedItem) {
-      onNavigationChange === null || onNavigationChange === void 0 || onNavigationChange(selectedItem);
-      showControls === null || showControls === void 0 || showControls();
-      setSelectedItem(selectedItem);
-      setPreviewCount(previewCount + 1);
+    onChange: function onChange(nextSelectedItem) {
+      var commit = function commit() {
+        onNavigationChange === null || onNavigationChange === void 0 || onNavigationChange(nextSelectedItem);
+        showControls === null || showControls === void 0 || showControls();
+        setSelectedItem(nextSelectedItem);
+        setPreviewCount(previewCount + 1);
+      };
+      if (onNavigationRequest) {
+        onNavigationRequest(nextSelectedItem, commit);
+      } else {
+        commit();
+      }
     },
     isArchiveSideBarVisible: isArchiveSideBarVisible
   }));

package/dist/cjs/media-viewer.js

@@ -14,7 +14,9 @@ var _reactFocusLock = _interopRequireDefault(require("react-focus-lock"));
 var _reactIntl = require("react-intl");
 var _reactScrolllock = _interopRequireDefault(require("react-scrolllock"));
 var _useAnalyticsEvents2 = require("@atlaskit/analytics-next/useAnalyticsEvents");
+var _mediaClient = require("@atlaskit/media-client");
 var _shortcut = require("@atlaskit/media-ui/shortcut");
+var _isExperimentEnabled = require("@atlaskit/platform-feature-experiments/is-experiment-enabled");
 var _modal = require("./analytics/events/screen/modal");
 var _closed = require("./analytics/events/ui/closed");
 var _fireAnalytics = require("./analytics/fireAnalytics");
@@ -23,21 +25,39 @@ var _content = require("./content");
 var _list = require("./list");
 var _styleWrappers = require("./styleWrappers");
 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 getIdentifierId = function getIdentifierId(identifier) {
+  return (0, _mediaClient.isFileIdentifier)(identifier) ? identifier.id : undefined;
+};
 var MediaViewerComponent = function MediaViewerComponent(_ref) {
   var featureFlags = _ref.featureFlags,
     items = _ref.items,
     extensions = _ref.extensions,
     contextId = _ref.contextId,
     innerRef = _ref.innerRef,
-    _onClose = _ref.onClose,
+    onClose = _ref.onClose,
     selectedItem = _ref.selectedItem,
     intl = _ref.intl,
     viewerOptions = _ref.viewerOptions,
     fallbackMediaNameFetcher = _ref.fallbackMediaNameFetcher;
-  var _useState = (0, _react.useState)(false),
+  // Experiment gate for the Confluence comments-in-media-viewer work. Only the
+  // fields introduced by that series are gated here — `extensions.sidebar` and
+  // `extensions.headerActions` shipped earlier and must keep working with the
+  // experiment off, so `extensions` itself is deliberately *not* nullified.
+  var _ref2 = (0, _isExperimentEnabled.isExperimentEnabled)('cc_comments_media_viewer_sidebar') ? extensions !== null && extensions !== void 0 ? extensions : {} : {},
+    onPreviewClose = _ref2.onPreviewClose,
+    onSidebarClose = _ref2.onSidebarClose,
+    onNavigation = _ref2.onNavigation,
+    onSelectedItemChange = _ref2.onSelectedItemChange,
+    defaultSidebarVisible = _ref2.defaultSidebarVisible,
+    onSidebarVisibilityChange = _ref2.onSidebarVisibilityChange;
+  var _useState = (0, _react.useState)(defaultSidebarVisible !== null && defaultSidebarVisible !== void 0 ? defaultSidebarVisible : false),
     _useState2 = (0, _slicedToArray2.default)(_useState, 2),
     isSidebarVisible = _useState2[0],
-    setIsSidebarVisible = _useState2[1];
+    setIsSidebarVisibleState = _useState2[1];
+  var setIsSidebarVisible = (0, _react.useCallback)(function (isVisible) {
+    setIsSidebarVisibleState(isVisible);
+    onSidebarVisibilityChange === null || onSidebarVisibilityChange === void 0 || onSidebarVisibilityChange(isVisible);
+  }, [onSidebarVisibilityChange]);
   var _useState3 = (0, _react.useState)(),
     _useState4 = (0, _slicedToArray2.default)(_useState3, 2),
     selectedIdentifier = _useState4[0],
@@ -46,19 +66,95 @@ var MediaViewerComponent = function MediaViewerComponent(_ref) {
     createAnalyticsEvent = _useAnalyticsEvents.createAnalyticsEvent;
   var createAnalyticsEventRef = (0, _react.useRef)(createAnalyticsEvent);
   createAnalyticsEventRef.current = createAnalyticsEvent;
+
+  // Delegation helpers: if the consumer provides an interceptor, call it and
+  // let the consumer decide when (or whether) to invoke `proceed`. Otherwise
+  // proceed immediately so behavior is unchanged for consumers that don't
+  // supply the new callbacks.
+  var requestPreviewClose = (0, _react.useCallback)(function (proceed) {
+    if (onPreviewClose) {
+      onPreviewClose(proceed);
+    } else {
+      proceed();
+    }
+  }, [onPreviewClose]);
+  var requestSidebarClose = (0, _react.useCallback)(function (proceed) {
+    if (onSidebarClose) {
+      onSidebarClose(proceed);
+    } else {
+      proceed();
+    }
+  }, [onSidebarClose]);
+  var requestNavigation = (0, _react.useCallback)(function (direction, proceed) {
+    if (onNavigation) {
+      onNavigation(direction, proceed);
+    } else {
+      proceed();
+    }
+  }, [onNavigation]);
   (0, _react.useLayoutEffect)(function () {
     (0, _fireAnalytics.fireAnalytics)((0, _modal.createModalEvent)(), createAnalyticsEventRef.current);
     (0, _perfMarks.start)('MediaViewer.SessionDuration');
   }, []);
   var defaultSelectedItem = selectedItem || items[0];
+
+  // Toggling the sidebar: opening is unconditional; closing goes through the
+  // optional onSidebarClose interceptor.
+  var toggleSidebar = (0, _react.useCallback)(function () {
+    if (isSidebarVisible) {
+      requestSidebarClose(function () {
+        return setIsSidebarVisible(false);
+      });
+    } else {
+      setIsSidebarVisible(true);
+    }
+  }, [isSidebarVisible, requestSidebarClose, setIsSidebarVisible]);
+
+  // The full modal close — used by ESC, the close button, and click-outside.
+  // Always passed through requestPreviewClose so the consumer can intercept.
+  var handlePreviewClose = (0, _react.useCallback)(function (reason) {
+    requestPreviewClose(function () {
+      if (reason !== 'other') {
+        (0, _fireAnalytics.fireAnalytics)((0, _closed.createClosedEvent)(reason), createAnalyticsEventRef.current);
+      }
+      onClose && onClose();
+    });
+  }, [onClose, requestPreviewClose]);
+
+  // Compute the navigation direction by comparing the new identifier's index
+  // in `items` with the current selected identifier's index. Falls back to
+  // 'next' if we can't determine direction (e.g. random jump from a list).
+  var computeNavigationDirection = (0, _react.useCallback)(function (nextIdentifier) {
+    var current = selectedIdentifier || defaultSelectedItem;
+    var currentId = current && getIdentifierId(current);
+    var nextId = getIdentifierId(nextIdentifier);
+    if (!currentId || !nextId) {
+      return 'next';
+    }
+    var currentIndex = items.findIndex(function (it) {
+      return getIdentifierId(it) === currentId;
+    });
+    var nextIndex = items.findIndex(function (it) {
+      return getIdentifierId(it) === nextId;
+    });
+    if (currentIndex === -1 || nextIndex === -1) {
+      return 'next';
+    }
+    return nextIndex < currentIndex ? 'prev' : 'next';
+  }, [items, selectedIdentifier, defaultSelectedItem]);
   var renderSidebar = function renderSidebar() {
     var sidebarSelectedIdentifier = selectedIdentifier || defaultSelectedItem;
-    if (sidebarSelectedIdentifier && isSidebarVisible && extensions && extensions.sidebar) {
+    if (sidebarSelectedIdentifier && isSidebarVisible && extensions !== null && extensions !== void 0 && extensions.sidebar) {
       return /*#__PURE__*/_react.default.createElement(_styleWrappers.SidebarWrapper, {
         "data-testid": "media-viewer-sidebar-content"
       }, extensions.sidebar.renderer(sidebarSelectedIdentifier, {
+        // `close` is what the sidebar renderer calls to dismiss itself.
+        // Route it through the same interceptor so confluence's
+        // unsaved-comment guard runs here too.
         close: function close() {
-          return setIsSidebarVisible(!isSidebarVisible);
+          return requestSidebarClose(function () {
+            return setIsSidebarVisible(false);
+          });
         }
       }));
     }
@@ -73,27 +169,42 @@ var MediaViewerComponent = function MediaViewerComponent(_ref) {
   }, /*#__PURE__*/_react.default.createElement(_shortcut.Shortcut, {
     code: 'Escape',
     handler: function handler() {
-      (0, _fireAnalytics.fireAnalytics)((0, _closed.createClosedEvent)('escKey'), createAnalyticsEventRef.current);
-      _onClose && _onClose();
+      handlePreviewClose('escKey');
     }
   }), /*#__PURE__*/_react.default.createElement(_content.Content, {
     isSidebarVisible: isSidebarVisible,
     onClose: function onClose(_e, analyticsEvent) {
       var _analyticsEvent$paylo;
-      if ((analyticsEvent === null || analyticsEvent === void 0 || (_analyticsEvent$paylo = analyticsEvent.payload) === null || _analyticsEvent$paylo === void 0 ? void 0 : _analyticsEvent$paylo.actionSubject) === 'button') {
-        (0, _fireAnalytics.fireAnalytics)((0, _closed.createClosedEvent)('button'), createAnalyticsEventRef.current);
-      }
-      _onClose && _onClose();
+      var reason = (analyticsEvent === null || analyticsEvent === void 0 || (_analyticsEvent$paylo = analyticsEvent.payload) === null || _analyticsEvent$paylo === void 0 ? void 0 : _analyticsEvent$paylo.actionSubject) === 'button' ? 'button' : 'other';
+      handlePreviewClose(reason);
     }
   }, /*#__PURE__*/_react.default.createElement(_list.List, {
     defaultSelectedItem: defaultSelectedItem || items[0],
-    items: items,
-    onClose: _onClose,
-    extensions: extensions,
-    onNavigationChange: setSelectedIdentifier,
-    onSidebarButtonClick: function onSidebarButtonClick() {
-      return setIsSidebarVisible(!isSidebarVisible);
+    items: items
+    // Note: `onClose` here is what the prev/next list passes down for
+    // "close-the-modal" actions. Route through interceptor too.
+    ,
+    onClose: function onClose() {
+      return handlePreviewClose('other');
+    },
+    extensions: extensions
+    // Notification-only: List has already updated its displayed item
+    // by the time this fires. We use it to keep the parent's
+    // `selectedIdentifier` in sync (consumers may key off it).
+    ,
+    onNavigationChange: function onNavigationChange(identifier) {
+      setSelectedIdentifier(identifier);
+      onSelectedItemChange === null || onSelectedItemChange === void 0 || onSelectedItemChange(identifier);
+    }
+    // Pre-commit gate: consumer can swallow or defer the
+    // nav by not calling `commit`. The image only swaps
+    // once `commit` runs.
+    ,
+    onNavigationRequest: function onNavigationRequest(identifier, commit) {
+      var direction = computeNavigationDirection(identifier);
+      requestNavigation(direction, commit);
     },
+    onSidebarButtonClick: toggleSidebar,
     isSidebarVisible: isSidebarVisible,
     contextId: contextId,
     featureFlags: featureFlags,

package/dist/es2019/analytics/ufoExperiences.js

@@ -4,7 +4,7 @@ import { fg } from '@atlaskit/platform-feature-flags/fg';
 import { UFOExperience } from '@atlaskit/ufo/experience';
 import { ExperiencePerformanceTypes, ExperienceTypes } from '@atlaskit/ufo/experience-types';
 const packageName = "@atlaskit/media-viewer";
-const packageVersion = "54.8.43";
+const packageVersion = "54.9.0";
 let ufoExperience;
 const getExperience = () => {
   if (!ufoExperience) {

package/dist/es2019/createItemDownloader.js

@@ -1,5 +1,4 @@
 import { isErrorFileState } from '@atlaskit/media-client';
-import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
 import { createDownloadFailedEventPayload } from './analytics/events/operational/createDownloadFailedEventPayload';
 import { createDownloadSucceededEventPayload } from './analytics/events/operational/createDownloadSucceededEventPayload';
 import { fireAnalytics } from './analytics/fireAnalytics';
@@ -13,7 +12,7 @@ export const createItemDownloader = (file, mediaClient, options) => async () =>
   } = options;
   const id = file.id;
   const fileStateName = !isErrorFileState(file) ? file.name : undefined;
-  const name = fileStateName || (expValEquals('platform_editor_media_download_fallback_name', 'isEnabled', true) ? fallbackMediaName : undefined);
+  const name = fileStateName || fallbackMediaName;
   mediaClient.file.downloadBinary(id, name, collectionName, traceContext).then(() => {
     fireAnalytics(createDownloadSucceededEventPayload(file, traceContext), createAnalyticsEvent);
   }).catch(e => {

package/dist/es2019/header.js

@@ -13,7 +13,6 @@ import MediaButton from '@atlaskit/media-ui/MediaButton';
 import { messages } from '@atlaskit/media-ui/messages';
 import { MimeTypeIcon } from '@atlaskit/media-ui/mime-type-icon';
 import { fg } from '@atlaskit/platform-feature-flags/fg';
-import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
 import { Outcome } from './domain/outcome';
 import { DisabledToolbarDownloadButton } from './download';
 import { MediaViewerError } from './MediaViewerError';
@@ -96,12 +95,12 @@ export const Header = ({
   useEffect(() => {
     // Reset fetch state when the file identity changes (e.g. navigating in viewer)
     const currentId = (fileState === null || fileState === void 0 ? void 0 : fileState.status) !== 'error' ? fileState === null || fileState === void 0 ? void 0 : fileState.id : undefined;
-    if (currentId && currentId !== lastFetchedFileId.current && expValEquals('platform_editor_media_name_fallback_viewer_card', 'isEnabled', true)) {
+    if (currentId && currentId !== lastFetchedFileId.current) {
       fallbackMediaNameFetchAttempted.current = false;
       setFallbackMediaName(undefined);
       lastFetchedFileId.current = currentId;
     }
-    if (fileState && fileState.status !== 'error' && !fileState.name && fallbackMediaNameFetcher && !fallbackMediaNameFetchAttempted.current && expValEquals('platform_editor_media_name_fallback_viewer_card', 'isEnabled', true)) {
+    if (fileState && fileState.status !== 'error' && !fileState.name && fallbackMediaNameFetcher && !fallbackMediaNameFetchAttempted.current) {
       fallbackMediaNameFetchAttempted.current = true;
       fallbackMediaNameFetcher(fileState.id).then(name => {
         setFallbackMediaName(name);
@@ -158,7 +157,7 @@ export const Header = ({
       name: item.name
     })), /*#__PURE__*/React.createElement(MedatadataTextWrapper, null, /*#__PURE__*/React.createElement(MetadataFileName, {
       "data-testid": "media-viewer-file-name"
-    }, item.name || expValEquals('platform_editor_media_name_fallback_viewer_card', 'isEnabled', true) && fallbackMediaName || /*#__PURE__*/React.createElement(FormattedMessage, messages.unknown)), /*#__PURE__*/React.createElement(MetadataSubText, {
+    }, item.name || fallbackMediaName || /*#__PURE__*/React.createElement(FormattedMessage, messages.unknown)), /*#__PURE__*/React.createElement(MetadataSubText, {
       "data-testid": "media-viewer-file-metadata-text"
     }, /*#__PURE__*/React.createElement(FormattedMessageWrapper, null, renderFileTypeText(item)), item.size ? ' · ' + toHumanReadableMediaSize(item.size) : ''))),
     pending: () => null,

package/dist/es2019/list.js

@@ -15,6 +15,7 @@ export const List = ({
   featureFlags,
   isSidebarVisible,
   onNavigationChange,
+  onNavigationRequest,
   items,
   viewerOptions,
   fallbackMediaNameFetcher
@@ -53,11 +54,18 @@ export const List = ({
   }), /*#__PURE__*/React.createElement(Navigation, {
     items: items,
     selectedItem: selectedItem,
-    onChange: selectedItem => {
-      onNavigationChange === null || onNavigationChange === void 0 ? void 0 : onNavigationChange(selectedItem);
-      showControls === null || showControls === void 0 ? void 0 : showControls();
-      setSelectedItem(selectedItem);
-      setPreviewCount(previewCount + 1);
+    onChange: nextSelectedItem => {
+      const commit = () => {
+        onNavigationChange === null || onNavigationChange === void 0 ? void 0 : onNavigationChange(nextSelectedItem);
+        showControls === null || showControls === void 0 ? void 0 : showControls();
+        setSelectedItem(nextSelectedItem);
+        setPreviewCount(previewCount + 1);
+      };
+      if (onNavigationRequest) {
+        onNavigationRequest(nextSelectedItem, commit);
+      } else {
+        commit();
+      }
     },
     isArchiveSideBarVisible: isArchiveSideBarVisible
   }));

package/dist/es2019/media-viewer.js

@@ -1,11 +1,13 @@
 import _extends from "@babel/runtime/helpers/extends";
-import React, { useState, useLayoutEffect, useRef } from 'react';
+import React, { useState, useLayoutEffect, useRef, useCallback } from 'react';
 import { start } from 'perf-marks';
 import FocusLock from 'react-focus-lock';
 import { IntlProvider, injectIntl } from 'react-intl';
 import ScrollLock from 'react-scrolllock';
 import { useAnalyticsEvents } from '@atlaskit/analytics-next/useAnalyticsEvents';
+import { isFileIdentifier } from '@atlaskit/media-client';
 import { Shortcut } from '@atlaskit/media-ui/shortcut';
+import { isExperimentEnabled } from '@atlaskit/platform-feature-experiments/is-experiment-enabled';
 import { createModalEvent } from './analytics/events/screen/modal';
 import { createClosedEvent } from './analytics/events/ui/closed';
 import { fireAnalytics } from './analytics/fireAnalytics';
@@ -13,6 +15,7 @@ import { mediaViewerPopupClass } from './classnames';
 import { Content } from './content';
 import { List } from './list';
 import { Blanket, SidebarWrapper } from './styleWrappers';
+const getIdentifierId = identifier => isFileIdentifier(identifier) ? identifier.id : undefined;
 const MediaViewerComponent = ({
   featureFlags,
   items,
@@ -25,25 +28,109 @@ const MediaViewerComponent = ({
   viewerOptions,
   fallbackMediaNameFetcher
 }) => {
-  const [isSidebarVisible, setIsSidebarVisible] = useState(false);
+  // Experiment gate for the Confluence comments-in-media-viewer work. Only the
+  // fields introduced by that series are gated here — `extensions.sidebar` and
+  // `extensions.headerActions` shipped earlier and must keep working with the
+  // experiment off, so `extensions` itself is deliberately *not* nullified.
+  const {
+    onPreviewClose,
+    onSidebarClose,
+    onNavigation,
+    onSelectedItemChange,
+    defaultSidebarVisible,
+    onSidebarVisibilityChange
+  } = isExperimentEnabled('cc_comments_media_viewer_sidebar') ? extensions !== null && extensions !== void 0 ? extensions : {} : {};
+  const [isSidebarVisible, setIsSidebarVisibleState] = useState(defaultSidebarVisible !== null && defaultSidebarVisible !== void 0 ? defaultSidebarVisible : false);
+  const setIsSidebarVisible = useCallback(isVisible => {
+    setIsSidebarVisibleState(isVisible);
+    onSidebarVisibilityChange === null || onSidebarVisibilityChange === void 0 ? void 0 : onSidebarVisibilityChange(isVisible);
+  }, [onSidebarVisibilityChange]);
   const [selectedIdentifier, setSelectedIdentifier] = useState();
   const {
     createAnalyticsEvent
   } = useAnalyticsEvents();
   const createAnalyticsEventRef = useRef(createAnalyticsEvent);
   createAnalyticsEventRef.current = createAnalyticsEvent;
+
+  // Delegation helpers: if the consumer provides an interceptor, call it and
+  // let the consumer decide when (or whether) to invoke `proceed`. Otherwise
+  // proceed immediately so behavior is unchanged for consumers that don't
+  // supply the new callbacks.
+  const requestPreviewClose = useCallback(proceed => {
+    if (onPreviewClose) {
+      onPreviewClose(proceed);
+    } else {
+      proceed();
+    }
+  }, [onPreviewClose]);
+  const requestSidebarClose = useCallback(proceed => {
+    if (onSidebarClose) {
+      onSidebarClose(proceed);
+    } else {
+      proceed();
+    }
+  }, [onSidebarClose]);
+  const requestNavigation = useCallback((direction, proceed) => {
+    if (onNavigation) {
+      onNavigation(direction, proceed);
+    } else {
+      proceed();
+    }
+  }, [onNavigation]);
   useLayoutEffect(() => {
     fireAnalytics(createModalEvent(), createAnalyticsEventRef.current);
     start('MediaViewer.SessionDuration');
   }, []);
   const defaultSelectedItem = selectedItem || items[0];
+
+  // Toggling the sidebar: opening is unconditional; closing goes through the
+  // optional onSidebarClose interceptor.
+  const toggleSidebar = useCallback(() => {
+    if (isSidebarVisible) {
+      requestSidebarClose(() => setIsSidebarVisible(false));
+    } else {
+      setIsSidebarVisible(true);
+    }
+  }, [isSidebarVisible, requestSidebarClose, setIsSidebarVisible]);
+
+  // The full modal close — used by ESC, the close button, and click-outside.
+  // Always passed through requestPreviewClose so the consumer can intercept.
+  const handlePreviewClose = useCallback(reason => {
+    requestPreviewClose(() => {
+      if (reason !== 'other') {
+        fireAnalytics(createClosedEvent(reason), createAnalyticsEventRef.current);
+      }
+      onClose && onClose();
+    });
+  }, [onClose, requestPreviewClose]);
+
+  // Compute the navigation direction by comparing the new identifier's index
+  // in `items` with the current selected identifier's index. Falls back to
+  // 'next' if we can't determine direction (e.g. random jump from a list).
+  const computeNavigationDirection = useCallback(nextIdentifier => {
+    const current = selectedIdentifier || defaultSelectedItem;
+    const currentId = current && getIdentifierId(current);
+    const nextId = getIdentifierId(nextIdentifier);
+    if (!currentId || !nextId) {
+      return 'next';
+    }
+    const currentIndex = items.findIndex(it => getIdentifierId(it) === currentId);
+    const nextIndex = items.findIndex(it => getIdentifierId(it) === nextId);
+    if (currentIndex === -1 || nextIndex === -1) {
+      return 'next';
+    }
+    return nextIndex < currentIndex ? 'prev' : 'next';
+  }, [items, selectedIdentifier, defaultSelectedItem]);
   const renderSidebar = () => {
     const sidebarSelectedIdentifier = selectedIdentifier || defaultSelectedItem;
-    if (sidebarSelectedIdentifier && isSidebarVisible && extensions && extensions.sidebar) {
+    if (sidebarSelectedIdentifier && isSidebarVisible && extensions !== null && extensions !== void 0 && extensions.sidebar) {
       return /*#__PURE__*/React.createElement(SidebarWrapper, {
         "data-testid": "media-viewer-sidebar-content"
       }, extensions.sidebar.renderer(sidebarSelectedIdentifier, {
-        close: () => setIsSidebarVisible(!isSidebarVisible)
+        // `close` is what the sidebar renderer calls to dismiss itself.
+        // Route it through the same interceptor so confluence's
+        // unsaved-comment guard runs here too.
+        close: () => requestSidebarClose(() => setIsSidebarVisible(false))
       }));
     }
   };
@@ -57,25 +144,40 @@ const MediaViewerComponent = ({
   }, /*#__PURE__*/React.createElement(Shortcut, {
     code: 'Escape',
     handler: () => {
-      fireAnalytics(createClosedEvent('escKey'), createAnalyticsEventRef.current);
-      onClose && onClose();
+      handlePreviewClose('escKey');
     }
   }), /*#__PURE__*/React.createElement(Content, {
     isSidebarVisible: isSidebarVisible,
     onClose: (_e, analyticsEvent) => {
       var _analyticsEvent$paylo;
-      if ((analyticsEvent === null || analyticsEvent === void 0 ? void 0 : (_analyticsEvent$paylo = analyticsEvent.payload) === null || _analyticsEvent$paylo === void 0 ? void 0 : _analyticsEvent$paylo.actionSubject) === 'button') {
-        fireAnalytics(createClosedEvent('button'), createAnalyticsEventRef.current);
-      }
-      onClose && onClose();
+      const reason = (analyticsEvent === null || analyticsEvent === void 0 ? void 0 : (_analyticsEvent$paylo = analyticsEvent.payload) === null || _analyticsEvent$paylo === void 0 ? void 0 : _analyticsEvent$paylo.actionSubject) === 'button' ? 'button' : 'other';
+      handlePreviewClose(reason);
     }
   }, /*#__PURE__*/React.createElement(List, {
     defaultSelectedItem: defaultSelectedItem || items[0],
-    items: items,
-    onClose: onClose,
-    extensions: extensions,
-    onNavigationChange: setSelectedIdentifier,
-    onSidebarButtonClick: () => setIsSidebarVisible(!isSidebarVisible),
+    items: items
+    // Note: `onClose` here is what the prev/next list passes down for
+    // "close-the-modal" actions. Route through interceptor too.
+    ,
+    onClose: () => handlePreviewClose('other'),
+    extensions: extensions
+    // Notification-only: List has already updated its displayed item
+    // by the time this fires. We use it to keep the parent's
+    // `selectedIdentifier` in sync (consumers may key off it).
+    ,
+    onNavigationChange: identifier => {
+      setSelectedIdentifier(identifier);
+      onSelectedItemChange === null || onSelectedItemChange === void 0 ? void 0 : onSelectedItemChange(identifier);
+    }
+    // Pre-commit gate: consumer can swallow or defer the
+    // nav by not calling `commit`. The image only swaps
+    // once `commit` runs.
+    ,
+    onNavigationRequest: (identifier, commit) => {
+      const direction = computeNavigationDirection(identifier);
+      requestNavigation(direction, commit);
+    },
+    onSidebarButtonClick: toggleSidebar,
     isSidebarVisible: isSidebarVisible,
     contextId: contextId,
     featureFlags: featureFlags,

package/dist/esm/analytics/ufoExperiences.js

@@ -7,7 +7,7 @@ import { fg } from '@atlaskit/platform-feature-flags/fg';
 import { UFOExperience } from '@atlaskit/ufo/experience';
 import { ExperiencePerformanceTypes, ExperienceTypes } from '@atlaskit/ufo/experience-types';
 var packageName = "@atlaskit/media-viewer";
-var packageVersion = "54.8.43";
+var packageVersion = "54.9.0";
 var ufoExperience;
 var getExperience = function getExperience() {
   if (!ufoExperience) {

package/dist/esm/createItemDownloader.js

@@ -1,7 +1,6 @@
 import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
 import _regeneratorRuntime from "@babel/runtime/regenerator";
 import { isErrorFileState } from '@atlaskit/media-client';
-import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
 import { createDownloadFailedEventPayload } from './analytics/events/operational/createDownloadFailedEventPayload';
 import { createDownloadSucceededEventPayload } from './analytics/events/operational/createDownloadSucceededEventPayload';
 import { fireAnalytics } from './analytics/fireAnalytics';
@@ -15,7 +14,7 @@ export var createItemDownloader = function createItemDownloader(file, mediaClien
           collectionName = options.collectionName, traceContext = options.traceContext, createAnalyticsEvent = options.createAnalyticsEvent, fallbackMediaName = options.fallbackMediaName;
           id = file.id;
           fileStateName = !isErrorFileState(file) ? file.name : undefined;
-          name = fileStateName || (expValEquals('platform_editor_media_download_fallback_name', 'isEnabled', true) ? fallbackMediaName : undefined);
+          name = fileStateName || fallbackMediaName;
           mediaClient.file.downloadBinary(id, name, collectionName, traceContext).then(function () {
             fireAnalytics(createDownloadSucceededEventPayload(file, traceContext), createAnalyticsEvent);
           }).catch(function (e) {

package/dist/esm/header.js

@@ -14,7 +14,6 @@ import MediaButton from '@atlaskit/media-ui/MediaButton';
 import { messages } from '@atlaskit/media-ui/messages';
 import { MimeTypeIcon } from '@atlaskit/media-ui/mime-type-icon';
 import { fg } from '@atlaskit/platform-feature-flags/fg';
-import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
 import { Outcome } from './domain/outcome';
 import { DisabledToolbarDownloadButton } from './download';
 import { MediaViewerError } from './MediaViewerError';
@@ -100,12 +99,12 @@ export var Header = function Header(_ref) {
   useEffect(function () {
     // Reset fetch state when the file identity changes (e.g. navigating in viewer)
     var currentId = (fileState === null || fileState === void 0 ? void 0 : fileState.status) !== 'error' ? fileState === null || fileState === void 0 ? void 0 : fileState.id : undefined;
-    if (currentId && currentId !== lastFetchedFileId.current && expValEquals('platform_editor_media_name_fallback_viewer_card', 'isEnabled', true)) {
+    if (currentId && currentId !== lastFetchedFileId.current) {
       fallbackMediaNameFetchAttempted.current = false;
       setFallbackMediaName(undefined);
       lastFetchedFileId.current = currentId;
     }
-    if (fileState && fileState.status !== 'error' && !fileState.name && fallbackMediaNameFetcher && !fallbackMediaNameFetchAttempted.current && expValEquals('platform_editor_media_name_fallback_viewer_card', 'isEnabled', true)) {
+    if (fileState && fileState.status !== 'error' && !fileState.name && fallbackMediaNameFetcher && !fallbackMediaNameFetchAttempted.current) {
       fallbackMediaNameFetchAttempted.current = true;
       fallbackMediaNameFetcher(fileState.id).then(function (name) {
         setFallbackMediaName(name);
@@ -161,7 +160,7 @@ export var Header = function Header(_ref) {
         name: item.name
       })), /*#__PURE__*/React.createElement(MedatadataTextWrapper, null, /*#__PURE__*/React.createElement(MetadataFileName, {
         "data-testid": "media-viewer-file-name"
-      }, item.name || expValEquals('platform_editor_media_name_fallback_viewer_card', 'isEnabled', true) && fallbackMediaName || /*#__PURE__*/React.createElement(FormattedMessage, messages.unknown)), /*#__PURE__*/React.createElement(MetadataSubText, {
+      }, item.name || fallbackMediaName || /*#__PURE__*/React.createElement(FormattedMessage, messages.unknown)), /*#__PURE__*/React.createElement(MetadataSubText, {
         "data-testid": "media-viewer-file-metadata-text"
       }, /*#__PURE__*/React.createElement(FormattedMessageWrapper, null, renderFileTypeText(item)), item.size ? ' · ' + toHumanReadableMediaSize(item.size) : '')));
     },

package/dist/esm/list.js

@@ -16,6 +16,7 @@ export var List = function List(_ref) {
     featureFlags = _ref.featureFlags,
     isSidebarVisible = _ref.isSidebarVisible,
     onNavigationChange = _ref.onNavigationChange,
+    onNavigationRequest = _ref.onNavigationRequest,
     items = _ref.items,
     viewerOptions = _ref.viewerOptions,
     fallbackMediaNameFetcher = _ref.fallbackMediaNameFetcher;
@@ -62,11 +63,18 @@ export var List = function List(_ref) {
   }), /*#__PURE__*/React.createElement(Navigation, {
     items: items,
     selectedItem: selectedItem,
-    onChange: function onChange(selectedItem) {
-      onNavigationChange === null || onNavigationChange === void 0 || onNavigationChange(selectedItem);
-      showControls === null || showControls === void 0 || showControls();
-      setSelectedItem(selectedItem);
-      setPreviewCount(previewCount + 1);
+    onChange: function onChange(nextSelectedItem) {
+      var commit = function commit() {
+        onNavigationChange === null || onNavigationChange === void 0 || onNavigationChange(nextSelectedItem);
+        showControls === null || showControls === void 0 || showControls();
+        setSelectedItem(nextSelectedItem);
+        setPreviewCount(previewCount + 1);
+      };
+      if (onNavigationRequest) {
+        onNavigationRequest(nextSelectedItem, commit);
+      } else {
+        commit();
+      }
     },
     isArchiveSideBarVisible: isArchiveSideBarVisible
   }));

package/dist/esm/media-viewer.js

@@ -1,12 +1,14 @@
 import _extends from "@babel/runtime/helpers/extends";
 import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
-import React, { useState, useLayoutEffect, useRef } from 'react';
+import React, { useState, useLayoutEffect, useRef, useCallback } from 'react';
 import { start } from 'perf-marks';
 import FocusLock from 'react-focus-lock';
 import { IntlProvider, injectIntl } from 'react-intl';
 import ScrollLock from 'react-scrolllock';
 import { useAnalyticsEvents } from '@atlaskit/analytics-next/useAnalyticsEvents';
+import { isFileIdentifier } from '@atlaskit/media-client';
 import { Shortcut } from '@atlaskit/media-ui/shortcut';
+import { isExperimentEnabled } from '@atlaskit/platform-feature-experiments/is-experiment-enabled';
 import { createModalEvent } from './analytics/events/screen/modal';
 import { createClosedEvent } from './analytics/events/ui/closed';
 import { fireAnalytics } from './analytics/fireAnalytics';
@@ -14,21 +16,39 @@ import { mediaViewerPopupClass } from './classnames';
 import { Content } from './content';
 import { List } from './list';
 import { Blanket, SidebarWrapper } from './styleWrappers';
+var getIdentifierId = function getIdentifierId(identifier) {
+  return isFileIdentifier(identifier) ? identifier.id : undefined;
+};
 var MediaViewerComponent = function MediaViewerComponent(_ref) {
   var featureFlags = _ref.featureFlags,
     items = _ref.items,
     extensions = _ref.extensions,
     contextId = _ref.contextId,
     innerRef = _ref.innerRef,
-    _onClose = _ref.onClose,
+    onClose = _ref.onClose,
     selectedItem = _ref.selectedItem,
     intl = _ref.intl,
     viewerOptions = _ref.viewerOptions,
     fallbackMediaNameFetcher = _ref.fallbackMediaNameFetcher;
-  var _useState = useState(false),
+  // Experiment gate for the Confluence comments-in-media-viewer work. Only the
+  // fields introduced by that series are gated here — `extensions.sidebar` and
+  // `extensions.headerActions` shipped earlier and must keep working with the
+  // experiment off, so `extensions` itself is deliberately *not* nullified.
+  var _ref2 = isExperimentEnabled('cc_comments_media_viewer_sidebar') ? extensions !== null && extensions !== void 0 ? extensions : {} : {},
+    onPreviewClose = _ref2.onPreviewClose,
+    onSidebarClose = _ref2.onSidebarClose,
+    onNavigation = _ref2.onNavigation,
+    onSelectedItemChange = _ref2.onSelectedItemChange,
+    defaultSidebarVisible = _ref2.defaultSidebarVisible,
+    onSidebarVisibilityChange = _ref2.onSidebarVisibilityChange;
+  var _useState = useState(defaultSidebarVisible !== null && defaultSidebarVisible !== void 0 ? defaultSidebarVisible : false),
     _useState2 = _slicedToArray(_useState, 2),
     isSidebarVisible = _useState2[0],
-    setIsSidebarVisible = _useState2[1];
+    setIsSidebarVisibleState = _useState2[1];
+  var setIsSidebarVisible = useCallback(function (isVisible) {
+    setIsSidebarVisibleState(isVisible);
+    onSidebarVisibilityChange === null || onSidebarVisibilityChange === void 0 || onSidebarVisibilityChange(isVisible);
+  }, [onSidebarVisibilityChange]);
   var _useState3 = useState(),
     _useState4 = _slicedToArray(_useState3, 2),
     selectedIdentifier = _useState4[0],
@@ -37,19 +57,95 @@ var MediaViewerComponent = function MediaViewerComponent(_ref) {
     createAnalyticsEvent = _useAnalyticsEvents.createAnalyticsEvent;
   var createAnalyticsEventRef = useRef(createAnalyticsEvent);
   createAnalyticsEventRef.current = createAnalyticsEvent;
+
+  // Delegation helpers: if the consumer provides an interceptor, call it and
+  // let the consumer decide when (or whether) to invoke `proceed`. Otherwise
+  // proceed immediately so behavior is unchanged for consumers that don't
+  // supply the new callbacks.
+  var requestPreviewClose = useCallback(function (proceed) {
+    if (onPreviewClose) {
+      onPreviewClose(proceed);
+    } else {
+      proceed();
+    }
+  }, [onPreviewClose]);
+  var requestSidebarClose = useCallback(function (proceed) {
+    if (onSidebarClose) {
+      onSidebarClose(proceed);
+    } else {
+      proceed();
+    }
+  }, [onSidebarClose]);
+  var requestNavigation = useCallback(function (direction, proceed) {
+    if (onNavigation) {
+      onNavigation(direction, proceed);
+    } else {
+      proceed();
+    }
+  }, [onNavigation]);
   useLayoutEffect(function () {
     fireAnalytics(createModalEvent(), createAnalyticsEventRef.current);
     start('MediaViewer.SessionDuration');
   }, []);
   var defaultSelectedItem = selectedItem || items[0];
+
+  // Toggling the sidebar: opening is unconditional; closing goes through the
+  // optional onSidebarClose interceptor.
+  var toggleSidebar = useCallback(function () {
+    if (isSidebarVisible) {
+      requestSidebarClose(function () {
+        return setIsSidebarVisible(false);
+      });
+    } else {
+      setIsSidebarVisible(true);
+    }
+  }, [isSidebarVisible, requestSidebarClose, setIsSidebarVisible]);
+
+  // The full modal close — used by ESC, the close button, and click-outside.
+  // Always passed through requestPreviewClose so the consumer can intercept.
+  var handlePreviewClose = useCallback(function (reason) {
+    requestPreviewClose(function () {
+      if (reason !== 'other') {
+        fireAnalytics(createClosedEvent(reason), createAnalyticsEventRef.current);
+      }
+      onClose && onClose();
+    });
+  }, [onClose, requestPreviewClose]);
+
+  // Compute the navigation direction by comparing the new identifier's index
+  // in `items` with the current selected identifier's index. Falls back to
+  // 'next' if we can't determine direction (e.g. random jump from a list).
+  var computeNavigationDirection = useCallback(function (nextIdentifier) {
+    var current = selectedIdentifier || defaultSelectedItem;
+    var currentId = current && getIdentifierId(current);
+    var nextId = getIdentifierId(nextIdentifier);
+    if (!currentId || !nextId) {
+      return 'next';
+    }
+    var currentIndex = items.findIndex(function (it) {
+      return getIdentifierId(it) === currentId;
+    });
+    var nextIndex = items.findIndex(function (it) {
+      return getIdentifierId(it) === nextId;
+    });
+    if (currentIndex === -1 || nextIndex === -1) {
+      return 'next';
+    }
+    return nextIndex < currentIndex ? 'prev' : 'next';
+  }, [items, selectedIdentifier, defaultSelectedItem]);
   var renderSidebar = function renderSidebar() {
     var sidebarSelectedIdentifier = selectedIdentifier || defaultSelectedItem;
-    if (sidebarSelectedIdentifier && isSidebarVisible && extensions && extensions.sidebar) {
+    if (sidebarSelectedIdentifier && isSidebarVisible && extensions !== null && extensions !== void 0 && extensions.sidebar) {
       return /*#__PURE__*/React.createElement(SidebarWrapper, {
         "data-testid": "media-viewer-sidebar-content"
       }, extensions.sidebar.renderer(sidebarSelectedIdentifier, {
+        // `close` is what the sidebar renderer calls to dismiss itself.
+        // Route it through the same interceptor so confluence's
+        // unsaved-comment guard runs here too.
         close: function close() {
-          return setIsSidebarVisible(!isSidebarVisible);
+          return requestSidebarClose(function () {
+            return setIsSidebarVisible(false);
+          });
         }
       }));
     }
@@ -64,27 +160,42 @@ var MediaViewerComponent = function MediaViewerComponent(_ref) {
   }, /*#__PURE__*/React.createElement(Shortcut, {
     code: 'Escape',
     handler: function handler() {
-      fireAnalytics(createClosedEvent('escKey'), createAnalyticsEventRef.current);
-      _onClose && _onClose();
+      handlePreviewClose('escKey');
     }
   }), /*#__PURE__*/React.createElement(Content, {
     isSidebarVisible: isSidebarVisible,
     onClose: function onClose(_e, analyticsEvent) {
       var _analyticsEvent$paylo;
-      if ((analyticsEvent === null || analyticsEvent === void 0 || (_analyticsEvent$paylo = analyticsEvent.payload) === null || _analyticsEvent$paylo === void 0 ? void 0 : _analyticsEvent$paylo.actionSubject) === 'button') {
-        fireAnalytics(createClosedEvent('button'), createAnalyticsEventRef.current);
-      }
-      _onClose && _onClose();
+      var reason = (analyticsEvent === null || analyticsEvent === void 0 || (_analyticsEvent$paylo = analyticsEvent.payload) === null || _analyticsEvent$paylo === void 0 ? void 0 : _analyticsEvent$paylo.actionSubject) === 'button' ? 'button' : 'other';
+      handlePreviewClose(reason);
     }
   }, /*#__PURE__*/React.createElement(List, {
     defaultSelectedItem: defaultSelectedItem || items[0],
-    items: items,
-    onClose: _onClose,
-    extensions: extensions,
-    onNavigationChange: setSelectedIdentifier,
-    onSidebarButtonClick: function onSidebarButtonClick() {
-      return setIsSidebarVisible(!isSidebarVisible);
+    items: items
+    // Note: `onClose` here is what the prev/next list passes down for
+    // "close-the-modal" actions. Route through interceptor too.
+    ,
+    onClose: function onClose() {
+      return handlePreviewClose('other');
+    },
+    extensions: extensions
+    // Notification-only: List has already updated its displayed item
+    // by the time this fires. We use it to keep the parent's
+    // `selectedIdentifier` in sync (consumers may key off it).
+    ,
+    onNavigationChange: function onNavigationChange(identifier) {
+      setSelectedIdentifier(identifier);
+      onSelectedItemChange === null || onSelectedItemChange === void 0 || onSelectedItemChange(identifier);
+    }
+    // Pre-commit gate: consumer can swallow or defer the
+    // nav by not calling `commit`. The image only swaps
+    // once `commit` runs.
+    ,
+    onNavigationRequest: function onNavigationRequest(identifier, commit) {
+      var direction = computeNavigationDirection(identifier);
+      requestNavigation(direction, commit);
     },
+    onSidebarButtonClick: toggleSidebar,
     isSidebarVisible: isSidebarVisible,
     contextId: contextId,
     featureFlags: featureFlags,

package/dist/types/components/types.d.ts

@@ -10,9 +10,15 @@ export type FileStateFlags = {
 export interface MediaViewerExtensionsActions {
     close: () => void;
 }
+export type MediaViewerNavigationDirection = 'next' | 'prev';
 export interface MediaViewerExtensions {
     sidebar?: {
         icon: ReactNode;
+        /** Accessible label for the sidebar toggle. Falls back to a generic localized string. */
+        label?: string;
+        /** Title rendered by Media Viewer in the inset sidebar header. */
+        title?: string;
+        /** Renders the sidebar body below the Platform-owned inset sidebar header. */
         renderer: (selectedIdentifier: Identifier, actions: MediaViewerExtensionsActions) => ReactNode;
     };
     headerActions?: Array<{
@@ -26,6 +32,55 @@ export interface MediaViewerExtensions {
         /** Optional callback to control per-item visibility. When omitted, button always shows. */
         isVisible?: (selectedIdentifier: Identifier) => boolean;
     }>;
+    /**
+     * Interceptor for the media viewer modal-close path (close button, ESC, click
+     * outside). When provided, the platform calls this instead of immediately
+     * closing — the consumer must invoke `proceed()` to actually close. If
+     * `proceed` is never called, the close is silently swallowed (e.g. while a
+     * confirm prompt is awaiting user input).
+     *
+     * When omitted, the platform proceeds immediately (default behavior).
+     */
+    onPreviewClose?: (proceed: () => void) => void;
+    /**
+     * Interceptor for the sidebar-close path (clicking the sidebar toggle button
+     * while the sidebar is open, or the sidebar's own internal close action).
+     * Called only when the sidebar is currently visible. Same delegation
+     * semantics as `onPreviewClose`.
+     */
+    onSidebarClose?: (proceed: () => void) => void;
+    /**
+     * Interceptor for the prev/next navigation buttons. Receives the requested
+     * direction so the consumer can decide per-direction. Same delegation
+     * semantics as `onPreviewClose`.
+     */
+    onNavigation?: (direction: MediaViewerNavigationDirection, proceed: () => void) => void;
+    /**
+     * Optional selected-item override for a given media card. Consumers can return
+     * an identifier to make this card render MediaViewer, or null to keep it
+     * closed. This lets consumers own remount-restore policy outside media-card.
+     */
+    getMediaViewerSelectedItem?: (identifier: Identifier) => Identifier | null;
+    /**
+     * Called whenever the selected preview item changes, including open, close,
+     * and prev/next navigation. Consumers can persist this value somewhere stable
+     * so a remounted owner card can restore the viewer to the same selected item.
+     */
+    onSelectedItemChange?: (selectedIdentifier: Identifier | null) => void;
+    /**
+     * Optional initial value for the sidebar's open/closed state. Used to persist
+     * the sidebar visibility across MediaViewer remounts (e.g. when the
+     * surrounding renderer re-mounts because its document was updated and the
+     * media node was re-inserted into the tree).
+     */
+    defaultSidebarVisible?: boolean;
+    /**
+     * Called whenever the sidebar's open/closed state changes inside the viewer
+     * (after the on{Sidebar,Preview}Close interceptors have proceeded). The
+     * consumer can persist this value somewhere stable so a subsequent remount
+     * can restore it via `defaultSidebarVisible`.
+     */
+    onSidebarVisibilityChange?: (isVisible: boolean) => void;
 }
 export interface MediaViewerProps {
     readonly mediaClient: MediaClient;

package/dist/types/list.d.ts

@@ -7,6 +7,15 @@ import { type ViewerOptionsProps } from './viewerOptions';
 export type Props = Readonly<{
     onClose?: () => void;
     onNavigationChange?: (selectedItem: Identifier) => void;
+    /**
+     * If provided, the List delegates the decision to advance to the next/prev
+     * item to the consumer. The consumer must call `proceed()` to actually
+     * commit the navigation. If `proceed` is never called, the underlying
+     * displayed item does not change. Used by consumers that need to show a
+     * confirmation prompt (e.g. unsaved comment changes) before allowing
+     * navigation between media items.
+     */
+    onNavigationRequest?: (selectedItem: Identifier, proceed: () => void) => void;
     defaultSelectedItem: Identifier;
     items: Identifier[];
     extensions?: MediaViewerExtensions;
@@ -22,4 +31,4 @@ export type State = {
     previewCount: number;
     isArchiveSideBarVisible: boolean;
 };
-export declare const List: ({ defaultSelectedItem, onClose, showControls, extensions, onSidebarButtonClick, contextId, featureFlags, isSidebarVisible, onNavigationChange, items, viewerOptions, fallbackMediaNameFetcher, }: Props) => React.JSX.Element;
+export declare const List: ({ defaultSelectedItem, onClose, showControls, extensions, onSidebarButtonClick, contextId, featureFlags, isSidebarVisible, onNavigationChange, onNavigationRequest, items, viewerOptions, fallbackMediaNameFetcher, }: Props) => React.JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/media-viewer",
-	"version": "54.8.44",
+	"version": "54.9.1",
 	"description": "MediaViewer is Atlassian's powerful solution for viewing files on the web. It's both powerful and extendable yet easy-to-integrate",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -50,6 +50,7 @@
 		"@atlaskit/media-svg": "^4.0.0",
 		"@atlaskit/media-ui": "^31.0.0",
 		"@atlaskit/menu": "^11.0.0",
+		"@atlaskit/platform-feature-experiments": "^0.3.0",
 		"@atlaskit/platform-feature-flags": "^2.2.0",
 		"@atlaskit/portal": "^7.0.0",
 		"@atlaskit/primitives": "^22.5.0",
@@ -58,7 +59,7 @@
 		"@atlaskit/spinner": "^20.4.0",
 		"@atlaskit/textfield": "^10.2.0",
 		"@atlaskit/theme": "^28.2.0",
-		"@atlaskit/tmp-editor-statsig": "^205.0.0",
+		"@atlaskit/tmp-editor-statsig": "^207.0.0",
 		"@atlaskit/tokens": "^20.0.0",
 		"@atlaskit/tooltip": "^24.3.0",
 		"@atlaskit/ufo": "^2.0.0",
@@ -95,10 +96,11 @@
 		"@atlaskit/media-test-data": "^4.0.0",
 		"@atlaskit/media-test-helpers": "^43.0.0",
 		"@atlaskit/modal-dialog": "^17.0.0",
-		"@atlaskit/select": "^23.0.0",
+		"@atlaskit/select": "^23.1.0",
 		"@atlaskit/ssr": "workspace:^",
 		"@atlaskit/toggle": "^17.3.0",
 		"@atlassian/a11y-jest-testing": "^0.17.0",
+		"@atlassian/experiment-test-utils": "^0.2.0",
 		"@atlassian/feature-flags-test-utils": "^1.3.0",
 		"@atlassian/testing-library": "^0.11.0",
 		"@atlassian/ufo": "^1.0.0",