@atlaskit/editor-plugin-media 12.4.1 → 12.5.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @atlaskit/editor-plugin-media
 
+## 12.5.1
+
+### Patch Changes
+
+- Updated dependencies
+
+## 12.5.0
+
+### Minor Changes
+
+- [`76dff28130c6a`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/76dff28130c6a) -
+  Add replace-media button to media plugin
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 12.4.1
 
 ### Patch Changes

package/dist/cjs/nodeviews/helpers.js

@@ -5,5 +5,9 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.hasPrivateAttrsChanged = void 0;
 var hasPrivateAttrsChanged = exports.hasPrivateAttrsChanged = function hasPrivateAttrsChanged(currentAttrs, newAttrs) {
-  return currentAttrs.__fileName !== newAttrs.__fileName || currentAttrs.__fileMimeType !== newAttrs.__fileMimeType || currentAttrs.__fileSize !== newAttrs.__fileSize || currentAttrs.__contextId !== newAttrs.__contextId;
+  return currentAttrs.__fileName !== newAttrs.__fileName || currentAttrs.__fileMimeType !== newAttrs.__fileMimeType || currentAttrs.__fileSize !== newAttrs.__fileSize || currentAttrs.__contextId !== newAttrs.__contextId ||
+  // A changed id means the media source was replaced — always re-initialise
+  // the updater so getRemoteDimensions fetches dimensions for the new file.
+  // Only check when id is explicitly present on the new attrs (it's Partial).
+  'id' in newAttrs && currentAttrs.id !== newAttrs.id;
 };

package/dist/cjs/nodeviews/mediaNodeUpdater.js

@@ -12,8 +12,10 @@ var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/cl
 var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _v = _interopRequireDefault(require("uuid/v4"));
+var _steps = require("@atlaskit/adf-schema/steps");
 var _analytics = require("@atlaskit/editor-common/analytics");
 var _mediaSingle = require("@atlaskit/editor-common/media-single");
+var _state = require("@atlaskit/editor-prosemirror/state");
 var _mediaClient = require("@atlaskit/media-client");
 var _mediaClientReact = require("@atlaskit/media-client-react");
 var _mediaCommon = require("@atlaskit/media-common");
@@ -22,10 +24,11 @@ var _helpers = require("../pm-plugins/commands/helpers");
 var _pluginKey = require("../pm-plugins/plugin-key");
 var _batchMediaNodeAttrs = require("../pm-plugins/utils/batchMediaNodeAttrs");
 var _mediaCommon2 = require("../pm-plugins/utils/media-common");
+var _nodeviewHelpers = require("./nodeviewHelpers");
 var _excluded = ["authProvider"],
-  _excluded2 = ["authProvider"]; // eslint-disable-next-line @atlaskit/platform/prefer-crypto-random-uuid -- Use crypto.randomUUID instead
+  _excluded2 = ["authProvider"];
 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; }
+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; } // eslint-disable-next-line @atlaskit/platform/prefer-crypto-random-uuid -- Use crypto.randomUUID instead
 var isMediaTypeSupported = function isMediaTypeSupported(type) {
   if (type) {
     return ['image', 'file'].includes(type);
@@ -324,7 +327,73 @@ var MediaNodeUpdater = exports.MediaNodeUpdater = /*#__PURE__*/function () {
       return attrs.__contextId || null;
     });
     (0, _defineProperty2.default)(this, "updateDimensions", function (dimensions) {
-      (0, _batchMediaNodeAttrs.batchMediaNodeAttrsUpdate)(_this.props.view, {
+      var view = _this.props.view;
+      var mediaPluginState = _pluginKey.stateKey.getState(view.state);
+      var targetDisplayHeight = mediaPluginState === null || mediaPluginState === void 0 ? void 0 : mediaPluginState.replaceMediaTargetDisplayHeight;
+      if (targetDisplayHeight !== null && targetDisplayHeight !== undefined && dimensions.width > 0) {
+        var _this$props$lineLengt, _mediaSingleNode$attr, _mediaSingleNode;
+        // Replace mode: combine intrinsic dimension update on the media node AND
+        // display width update on the mediaSingle into a single transaction so they
+        // are never out of sync and don't cause two separate renders/layout shifts.
+
+        // Clear the stored target height — this is a one-shot adjustment
+        if (mediaPluginState) {
+          mediaPluginState.replaceMediaTargetDisplayHeight = null;
+        }
+
+        // Clamp to the layout's maximum width so the image never overflows its container.
+        var lineLength = (_this$props$lineLengt = _this.props.lineLength) !== null && _this$props$lineLengt !== void 0 ? _this$props$lineLengt : 760;
+        var state = view.state;
+        var mediaSingle = state.schema.nodes.mediaSingle;
+        // Typed explicitly because TypeScript can't track mutations inside
+        // the descendants callback closure and would narrow these to `never`.
+        var mediaSinglePos = null;
+        var mediaSingleNode = null;
+        var mediaPos = null;
+        state.doc.descendants(function (node, pos) {
+          if (mediaSinglePos !== null) {
+            return false;
+          }
+          if (node.type === mediaSingle) {
+            var mediaChild = node.firstChild;
+            if (mediaChild && mediaChild.attrs.id === dimensions.id) {
+              mediaSinglePos = pos;
+              mediaSingleNode = node;
+              mediaPos = pos + 1;
+            }
+          }
+          return true;
+        });
+        var layout = (_mediaSingleNode$attr = (_mediaSingleNode = mediaSingleNode) === null || _mediaSingleNode === void 0 || (_mediaSingleNode = _mediaSingleNode.attrs) === null || _mediaSingleNode === void 0 ? void 0 : _mediaSingleNode.layout) !== null && _mediaSingleNode$attr !== void 0 ? _mediaSingleNode$attr : 'center';
+        var newDisplayWidth = (0, _nodeviewHelpers.computeReplacementDisplayWidth)(targetDisplayHeight, dimensions.width, dimensions.height, layout, lineLength);
+        if (mediaSinglePos !== null && mediaSingleNode !== null && mediaPos !== null) {
+          var tr = state.tr;
+
+          // Update intrinsic dimensions on the media child node
+          tr.step(new _steps.SetAttrsStep(mediaPos, {
+            height: dimensions.height,
+            width: dimensions.width
+          }));
+
+          // Update display width on the mediaSingle parent
+          tr.setNodeMarkup(mediaSinglePos, undefined, _objectSpread(_objectSpread({}, mediaSingleNode.attrs), {}, {
+            width: Math.round(newDisplayWidth),
+            widthType: 'pixel'
+          }));
+
+          // Re-create the NodeSelection so the floating toolbar picks up
+          // the updated node and renders the full set of controls.
+          if (state.selection instanceof _state.NodeSelection) {
+            tr.setSelection(_state.NodeSelection.create(tr.doc, mediaSinglePos));
+          }
+          tr.setMeta('scrollIntoView', false);
+          view.dispatch(tr);
+          return;
+        }
+      }
+
+      // Normal (non-replace) path: use the existing batched update mechanism
+      (0, _batchMediaNodeAttrs.batchMediaNodeAttrsUpdate)(view, {
         id: dimensions.id,
         nextAttributes: {
           height: dimensions.height,

package/dist/cjs/nodeviews/mediaSingleNext.js

@@ -151,7 +151,8 @@ var useMediaAsyncOperations = function useMediaAsyncOperations(_ref3) {
   var mediaNode = _ref3.mediaNode,
     mediaNodeUpdater = _ref3.mediaNodeUpdater,
     addPendingTask = _ref3.addPendingTask,
-    getPos = _ref3.getPos;
+    getPos = _ref3.getPos,
+    mediaChildNodeId = _ref3.mediaChildNodeId;
   _react.default.useEffect(function () {
     if (!mediaNodeUpdater) {
       return;
@@ -168,7 +169,11 @@ var useMediaAsyncOperations = function useMediaAsyncOperations(_ref3) {
       mediaNode: mediaNode,
       addPendingTask: addPendingTask
     });
-  }, [mediaNode, addPendingTask, mediaNodeUpdater, getPos]);
+    // mediaChildNodeId is included so this effect re-runs when the media source
+    // is replaced (id changes), ensuring getRemoteDimensions fires for the new file
+    // with up-to-date updater props after setProps has been called.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [mediaNode, addPendingTask, mediaNodeUpdater, getPos, mediaChildNodeId]);
 };
 var noop = function noop() {};
 
@@ -287,7 +292,7 @@ var useUpdateSizeCallback = function useUpdateSizeCallback(_ref5) {
  */
 var FALLBACK_MOST_COMMON_WIDTH = 760;
 var MediaSingleNodeNext = exports.MediaSingleNodeNext = function MediaSingleNodeNext(mediaSingleNodeNextProps) {
-  var _pluginInjectionApi$m, _mediaNode$firstChild;
+  var _mediaNode$firstChild, _pluginInjectionApi$m, _mediaNode$firstChild2;
   var selected = mediaSingleNodeNextProps.selected,
     getPos = mediaSingleNodeNextProps.getPos,
     nextMediaNode = mediaSingleNodeNextProps.node,
@@ -334,7 +339,8 @@ var MediaSingleNodeNext = exports.MediaSingleNodeNext = function MediaSingleNode
     mediaNodeUpdater: mediaNodeUpdater,
     getPos: getPos,
     mediaNode: mediaNode,
-    addPendingTask: addPendingTask || noop
+    addPendingTask: addPendingTask || noop,
+    mediaChildNodeId: (_mediaNode$firstChild = mediaNode.firstChild) === null || _mediaNode$firstChild === void 0 ? void 0 : _mediaNode$firstChild.attrs.id
   });
   _react.default.useLayoutEffect(function () {
     mountedRef.current = true;
@@ -429,7 +435,7 @@ var MediaSingleNodeNext = exports.MediaSingleNodeNext = function MediaSingleNode
   }, [mediaSingleWidthAttribute, widthType, width, layout, contentWidthForLegacyExperience, containerWidth]);
   var currentMaxWidth = isSelected ? pluginInjectionApi === null || pluginInjectionApi === void 0 || (_pluginInjectionApi$m = pluginInjectionApi.media) === null || _pluginInjectionApi$m === void 0 || (_pluginInjectionApi$m = _pluginInjectionApi$m.sharedState.currentState()) === null || _pluginInjectionApi$m === void 0 ? void 0 : _pluginInjectionApi$m.currentMaxWidth : undefined;
   var contentWidth = currentMaxWidth || lineLength;
-  var isCurrentNodeDrafting = Boolean(isDrafting && targetNodeId === (mediaNode === null || mediaNode === void 0 || (_mediaNode$firstChild = mediaNode.firstChild) === null || _mediaNode$firstChild === void 0 ? void 0 : _mediaNode$firstChild.attrs.id));
+  var isCurrentNodeDrafting = Boolean(isDrafting && targetNodeId === (mediaNode === null || mediaNode === void 0 || (_mediaNode$firstChild2 = mediaNode.firstChild) === null || _mediaNode$firstChild2 === void 0 ? void 0 : _mediaNode$firstChild2.attrs.id));
   var mediaSingleWrapperRef = /*#__PURE__*/_react.default.createRef();
   var captionPlaceHolderRef = /*#__PURE__*/_react.default.createRef();
   var browser = (0, _browser.getBrowserInfo)();

package/dist/cjs/nodeviews/nodeviewHelpers.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.computeReplacementDisplayWidth = void 0;
+var _editorSharedStyles = require("@atlaskit/editor-shared-styles");
+var MIN_MEDIA_DISPLAY_WIDTH = 24;
+/**
+ * Computes the new mediaSingle display width that preserves the original display height
+ * when a media node is replaced with a file of a different aspect ratio, clamped to valid bounds.
+ *
+ * @param targetDisplayHeight - The display height to preserve (from the old image)
+ * @param newIntrinsicWidth - The new file's intrinsic pixel width
+ * @param newIntrinsicHeight - The new file's intrinsic pixel height
+ * @param layout - The mediaSingle layout (affects max width)
+ * @param lineLength - The editor content column width in pixels
+ */
+var computeReplacementDisplayWidth = exports.computeReplacementDisplayWidth = function computeReplacementDisplayWidth(targetDisplayHeight, newIntrinsicWidth, newIntrinsicHeight, layout, lineLength) {
+  if (newIntrinsicHeight <= 0) {
+    return MIN_MEDIA_DISPLAY_WIDTH;
+  }
+  var unclamped = targetDisplayHeight * (newIntrinsicWidth / newIntrinsicHeight);
+  var maxWidth = layout === 'full-width' ? _editorSharedStyles.akEditorFullWidthLayoutWidth : layout === 'wide' ? _editorSharedStyles.akEditorWideLayoutWidth : lineLength;
+  return Math.max(MIN_MEDIA_DISPLAY_WIDTH, Math.min(unclamped, maxWidth));
+};

package/dist/cjs/pm-plugins/main.js

@@ -15,6 +15,7 @@ var _assert = _interopRequireDefault(require("assert"));
 var _react = _interopRequireDefault(require("react"));
 var _reactIntl = require("react-intl");
 var _uuid = _interopRequireDefault(require("uuid"));
+var _steps = require("@atlaskit/adf-schema/steps");
 var _analytics = require("@atlaskit/editor-common/analytics");
 var _browser = require("@atlaskit/editor-common/browser");
 var _mediaInline = require("@atlaskit/editor-common/media-inline");
@@ -24,11 +25,12 @@ var _utils = require("@atlaskit/editor-common/utils");
 var _state2 = require("@atlaskit/editor-prosemirror/state");
 var _transform = require("@atlaskit/editor-prosemirror/transform");
 var _utils2 = require("@atlaskit/editor-prosemirror/utils");
-var _view2 = require("@atlaskit/editor-prosemirror/view");
+var _view3 = require("@atlaskit/editor-prosemirror/view");
 var _cellSelection = require("@atlaskit/editor-tables/cell-selection");
 var _mediaClient = require("@atlaskit/media-client");
 var _mediaCommon = require("@atlaskit/media-common");
 var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
+var _mediaNodeUpdater = require("../nodeviews/mediaNodeUpdater");
 var _helpers = _interopRequireWildcard(require("../pm-plugins/commands/helpers"));
 var helpers = _helpers;
 var _mediaCommon2 = require("../pm-plugins/utils/media-common");
@@ -95,6 +97,15 @@ var MediaPluginStateImplementation = exports.MediaPluginStateImplementation = /*
     (0, _defineProperty2.default)(this, "destroyed", false);
     (0, _defineProperty2.default)(this, "removeOnCloseListener", function () {});
     (0, _defineProperty2.default)(this, "onPopupToggleCallback", function () {});
+    // When non-null, holds the file ID of the media node being replaced. Used both as a
+    // flag (non-null = replace mode) and as a cross-check to ensure the correct node is
+    // updated if the selection moves between the picker opening and the file being picked.
+    (0, _defineProperty2.default)(this, "replaceMediaFileId", null);
+    // The display height (in pixels) of the mediaSingle being replaced, computed at replace time
+    // from its display width and the old media node's intrinsic aspect ratio.
+    // Used by the nodeview to recompute display width from the new file's aspect ratio after
+    // dimensions are fetched, preserving visual height rather than visual width.
+    (0, _defineProperty2.default)(this, "replaceMediaTargetDisplayHeight", null);
     (0, _defineProperty2.default)(this, "identifierCount", new Map());
     // This is to enable mediaShallowCopySope to enable only shallow copying media referenced within the edtior
     // see: trackOutOfScopeIdentifier
@@ -130,7 +141,7 @@ var MediaPluginStateImplementation = exports.MediaPluginStateImplementation = /*
      * called when we insert a new file via the picker (connected via pickerfacade)
      */
     (0, _defineProperty2.default)(this, "insertFile", function (mediaState, onMediaStateChanged, pickerType, insertMediaVia) {
-      var _this$pluginInjection, _mediaState$collectio, _this$pluginInjection2;
+      var _this$pluginInjection, _mediaState$collectio, _this$pluginInjection3;
       var state = _this.view.state;
       var editorAnalyticsAPI = (_this$pluginInjection = _this.pluginInjectionApi) === null || _this$pluginInjection === void 0 || (_this$pluginInjection = _this$pluginInjection.analytics) === null || _this$pluginInjection === void 0 ? void 0 : _this$pluginInjection.actions;
       var mediaStateWithContext = _objectSpread(_objectSpread({}, mediaState), {}, {
@@ -141,6 +152,19 @@ var MediaPluginStateImplementation = exports.MediaPluginStateImplementation = /*
         return;
       }
 
+      // If replace mode was set but the selection has moved away from a mediaSingle
+      // (e.g. the user cancelled the replace picker and then inserted media elsewhere),
+      // clear replace state so this insertion proceeds as a normal insert.
+      if (_this.replaceMediaFileId !== null) {
+        var _state$selection$node;
+        var mediaSingle = state.schema.nodes.mediaSingle;
+        var isStillOnTargetMedia = state.selection instanceof _state2.NodeSelection && state.selection.node.type === mediaSingle && ((_state$selection$node = state.selection.node.firstChild) === null || _state$selection$node === void 0 ? void 0 : _state$selection$node.attrs.id) === _this.replaceMediaFileId;
+        if (!isStillOnTargetMedia) {
+          _this.replaceMediaFileId = null;
+          _this.replaceMediaTargetDisplayHeight = null;
+        }
+      }
+
       // We need to dispatch the change to event dispatcher only for successful files
       if (mediaState.status !== 'error') {
         _this.updateAndDispatch({
@@ -153,13 +177,124 @@ var MediaPluginStateImplementation = exports.MediaPluginStateImplementation = /*
         });
         _this.uploadInProgressSubscriptionsNotified = true;
       }
+
+      // Replace mode: if a media node is being replaced, update its attrs in-place
+      // rather than inserting a new node. This preserves layout, width, and caption.
+      if (_this.replaceMediaFileId !== null) {
+        var _mediaState$fileMimeT, _mediaState$fileName, _mediaState$fileSize;
+        // Clear replace mode immediately so subsequent insertions behave normally
+        _this.replaceMediaFileId = null;
+        var currentState = _this.view.state;
+        var mediaSinglePos = currentState.selection.from;
+        var mediaPos = mediaSinglePos + 1;
+        var mediaNode = currentState.doc.nodeAt(mediaPos);
+        if (!mediaNode || mediaNode.type.name !== 'media') {
+          return;
+        }
+
+        // Build a single transaction that:
+        // 1. Updates the media child node attrs (new file identity + cleared dimensions)
+        // 2. Re-creates the NodeSelection so the toolbar picks up the fresh node
+        var tr = currentState.tr;
+        tr.step(new _steps.SetAttrsStep(mediaPos, {
+          id: mediaState.id,
+          collection: collection,
+          type: 'file',
+          __fileMimeType: (_mediaState$fileMimeT = mediaState.fileMimeType) !== null && _mediaState$fileMimeT !== void 0 ? _mediaState$fileMimeT : null,
+          __fileName: (_mediaState$fileName = mediaState.fileName) !== null && _mediaState$fileName !== void 0 ? _mediaState$fileName : null,
+          __fileSize: (_mediaState$fileSize = mediaState.fileSize) !== null && _mediaState$fileSize !== void 0 ? _mediaState$fileSize : null,
+          __mediaTraceId: null,
+          // Clear intrinsic dimensions — they'll be fetched once the file
+          // is processed and applied via updateDimensions in a single tx
+          // with the height-preserving mediaSingle width adjustment.
+          width: null,
+          height: null
+        }));
+        // Re-create the selection so the floating toolbar picks up
+        // the updated node and renders the full set of controls.
+        tr.setSelection(_state2.NodeSelection.create(tr.doc, mediaSinglePos));
+        tr.setMeta('scrollIntoView', false);
+        _this.view.dispatch(tr);
+
+        // Still register the state-change listener so upload completion is tracked
+        onMediaStateChanged(_this.handleMediaState);
+        var _isEndState = function _isEndState(state) {
+          return state.status && MEDIA_RESOLVED_STATES.includes(state.status);
+        };
+
+        // After the file finishes uploading/processing, trigger a dimension fetch.
+        // getRemoteDimensions may fail if called too early (isImageRepresentationReady
+        // returns false while processing), so we wait for the ready state first.
+        var triggerDimensionFetch = function triggerDimensionFetch() {
+          // Find the media node in the doc by id and create a temporary
+          // MediaNodeUpdater to fetch and apply dimensions
+          var editorState = _this.view.state;
+          var mediaSingleType = editorState.schema.nodes.mediaSingle;
+          var mediaChildNode = null;
+          editorState.doc.descendants(function (node) {
+            if (mediaChildNode) {
+              return false;
+            }
+            if (node.type === mediaSingleType) {
+              var child = node.firstChild;
+              if (child && child.attrs.id === mediaState.id) {
+                mediaChildNode = child;
+              }
+            }
+            return true;
+          });
+          if (mediaChildNode) {
+            var _this$pluginInjection2;
+            var updater = (0, _mediaNodeUpdater.createMediaNodeUpdater)({
+              view: _this.view,
+              mediaProvider: _this.mediaProvider ? Promise.resolve(_this.mediaProvider) : undefined,
+              contextIdentifierProvider: _this.contextIdentifierProvider ? Promise.resolve(_this.contextIdentifierProvider) : undefined,
+              node: mediaChildNode,
+              isMediaSingle: true,
+              lineLength: (_this$pluginInjection2 = _this.pluginInjectionApi) === null || _this$pluginInjection2 === void 0 || (_this$pluginInjection2 = _this$pluginInjection2.width) === null || _this$pluginInjection2 === void 0 || (_this$pluginInjection2 = _this$pluginInjection2.sharedState.currentState()) === null || _this$pluginInjection2 === void 0 ? void 0 : _this$pluginInjection2.lineLength
+            });
+            updater.getRemoteDimensions().then(function (dims) {
+              if (dims) {
+                updater.updateDimensions(dims);
+              }
+            }).catch(function () {
+              // Silently ignore — if dimensions can't be fetched (e.g. network error),
+              // the image will render at its current size without the height-preserving
+              // width adjustment. This is an acceptable degraded experience.
+            });
+          }
+        };
+        if (!_isEndState(mediaStateWithContext)) {
+          var uploadingPromise = new Promise(function (resolve) {
+            onMediaStateChanged(function (newState) {
+              if (_isEndState(newState)) {
+                resolve(newState);
+              }
+            });
+          });
+          _this.taskManager.addPendingTask(uploadingPromise, mediaStateWithContext.id).then(function () {
+            _this.updateAndDispatch({
+              allUploadsFinished: true
+            });
+            triggerDimensionFetch();
+          });
+        } else {
+          // File is already in a resolved state — fetch dimensions immediately
+          triggerDimensionFetch();
+        }
+        var _view = _this.view;
+        if (!_view.hasFocus()) {
+          _view.focus();
+        }
+        return;
+      }
       switch ((0, _mediaInline2.getMediaNodeInsertionType)(state, _this.mediaOptions, mediaStateWithContext.fileMimeType)) {
         case 'inline':
           (0, _mediaFiles.insertMediaInlineNode)(editorAnalyticsAPI)(_this.view, mediaStateWithContext, collection, _this.allowInlineImages, _this.getInputMethod(pickerType), insertMediaVia);
           break;
         case 'block':
           // read width state right before inserting to get up-to-date and define values
-          var widthPluginState = (_this$pluginInjection2 = _this.pluginInjectionApi) === null || _this$pluginInjection2 === void 0 || (_this$pluginInjection2 = _this$pluginInjection2.width) === null || _this$pluginInjection2 === void 0 ? void 0 : _this$pluginInjection2.sharedState.currentState();
+          var widthPluginState = (_this$pluginInjection3 = _this.pluginInjectionApi) === null || _this$pluginInjection3 === void 0 || (_this$pluginInjection3 = _this$pluginInjection3.width) === null || _this$pluginInjection3 === void 0 ? void 0 : _this$pluginInjection3.sharedState.currentState();
           (0, _mediaSingle2.insertMediaSingleNode)(_this.view, mediaStateWithContext, _this.getInputMethod(pickerType), collection, _this.mediaOptions && _this.mediaOptions.alignLeftOnInsert, widthPluginState, editorAnalyticsAPI, _this.onNodeInserted, insertMediaVia, _this.mediaOptions && _this.mediaOptions.allowPixelResizing);
           break;
         case 'group':
@@ -175,7 +310,7 @@ var MediaPluginStateImplementation = exports.MediaPluginStateImplementation = /*
         return state.status && MEDIA_RESOLVED_STATES.indexOf(state.status) !== -1;
       };
       if (!isEndState(mediaStateWithContext)) {
-        var uploadingPromise = new Promise(function (resolve) {
+        var _uploadingPromise = new Promise(function (resolve) {
           onMediaStateChanged(function (newState) {
             // When media item reaches its final state, remove listener and resolve
             if (isEndState(newState)) {
@@ -184,7 +319,7 @@ var MediaPluginStateImplementation = exports.MediaPluginStateImplementation = /*
           });
         });
         if ((0, _platformFeatureFlags.fg)('platform_editor_media_disable_save_during_upload')) {
-          _this.taskManager.addPendingTask(uploadingPromise, mediaStateWithContext.id).then(function () {
+          _this.taskManager.addPendingTask(_uploadingPromise, mediaStateWithContext.id).then(function () {
             _this.updateAndDispatch({
               allUploadsFinished: true
             });
@@ -198,7 +333,7 @@ var MediaPluginStateImplementation = exports.MediaPluginStateImplementation = /*
             });
           });
         } else {
-          _this.taskManager.addPendingTask(uploadingPromise, mediaStateWithContext.id).then(function () {
+          _this.taskManager.addPendingTask(_uploadingPromise, mediaStateWithContext.id).then(function () {
             _this.updateAndDispatch({
               allUploadsFinished: true
             });
@@ -240,6 +375,64 @@ var MediaPluginStateImplementation = exports.MediaPluginStateImplementation = /*
       }
       _this.onPopupToggleCallback(true);
     });
+    /**
+     * Opens the media picker in "replace" mode. The next file selected/uploaded
+     * will replace the currently selected mediaSingle node's media child in-place,
+     * preserving layout, width, and caption.
+     *
+     * The display height is computed and stored so that after the new file's intrinsic
+     * dimensions are fetched, the mediaSingle display width can be adjusted to maintain
+     * visual height stability rather than width stability.
+     */
+    (0, _defineProperty2.default)(this, "showMediaPickerForReplace", function () {
+      var _this$pluginInjection4, _this$pluginInjection5;
+      var state = _this.view.state;
+      var mediaSingle = state.schema.nodes.mediaSingle;
+      var selection = state.selection;
+
+      // Only activate replace mode when a mediaSingle is selected
+      if (!(selection instanceof _state2.NodeSelection) || selection.node.type !== mediaSingle) {
+        return;
+      }
+      var mediaSingleNode = selection.node;
+      var mediaNode = mediaSingleNode.firstChild;
+      if (!mediaNode) {
+        return;
+      }
+
+      // Store the current media node's id so insertFile can identify and replace it
+      _this.replaceMediaFileId = mediaNode.attrs.id;
+
+      // Compute and store the current display height so we can preserve it after
+      // the new file's intrinsic dimensions are known.
+      // displayHeight = displayWidth * (intrinsicHeight / intrinsicWidth)
+      var widthAttr = mediaSingleNode.attrs.width;
+      var widthType = mediaSingleNode.attrs.widthType;
+      var intrinsicWidth = mediaNode.attrs.width;
+      var intrinsicHeight = mediaNode.attrs.height;
+
+      // Resolve actual pixel display width from mediaSingle attrs.
+      var lineLength = (_this$pluginInjection4 = (_this$pluginInjection5 = _this.pluginInjectionApi) === null || _this$pluginInjection5 === void 0 || (_this$pluginInjection5 = _this$pluginInjection5.width) === null || _this$pluginInjection5 === void 0 || (_this$pluginInjection5 = _this$pluginInjection5.sharedState.currentState()) === null || _this$pluginInjection5 === void 0 ? void 0 : _this$pluginInjection5.lineLength) !== null && _this$pluginInjection4 !== void 0 ? _this$pluginInjection4 : 760;
+      var displayWidth = null;
+      if (widthAttr && widthType === 'pixel') {
+        displayWidth = widthAttr;
+      } else if (widthAttr) {
+        // Default widthType is 'percentage' — convert to pixels
+        displayWidth = widthAttr / 100 * lineLength;
+      } else if (intrinsicWidth) {
+        // No width set at all (never resized) — fall back to intrinsic width
+        displayWidth = intrinsicWidth;
+      }
+      if (displayWidth && intrinsicWidth && intrinsicHeight && intrinsicWidth > 0) {
+        _this.replaceMediaTargetDisplayHeight = displayWidth * (intrinsicHeight / intrinsicWidth);
+      } else {
+        // Can't compute display height — fall back to preserving width
+        _this.replaceMediaTargetDisplayHeight = null;
+      }
+
+      // Finally, show the media picker
+      _this.showMediaPicker();
+    });
     (0, _defineProperty2.default)(this, "setBrowseFn", function (browseFn) {
       _this.openMediaPickerBrowser = browseFn;
     });
@@ -695,8 +888,8 @@ var MediaPluginStateImplementation = exports.MediaPluginStateImplementation = /*
   }, {
     key: "contextIdentifierProvider",
     get: function get() {
-      var _this$pluginInjection3;
-      return (_this$pluginInjection3 = this.pluginInjectionApi) === null || _this$pluginInjection3 === void 0 || (_this$pluginInjection3 = _this$pluginInjection3.contextIdentifier) === null || _this$pluginInjection3 === void 0 || (_this$pluginInjection3 = _this$pluginInjection3.sharedState.currentState()) === null || _this$pluginInjection3 === void 0 ? void 0 : _this$pluginInjection3.contextIdentifierProvider;
+      var _this$pluginInjection6;
+      return (_this$pluginInjection6 = this.pluginInjectionApi) === null || _this$pluginInjection6 === void 0 || (_this$pluginInjection6 = _this$pluginInjection6.contextIdentifier) === null || _this$pluginInjection6 === void 0 || (_this$pluginInjection6 = _this$pluginInjection6.sharedState.currentState()) === null || _this$pluginInjection6 === void 0 ? void 0 : _this$pluginInjection6.contextIdentifierProvider;
     }
   }, {
     key: "selectLastAddedMediaNode",
@@ -931,9 +1124,9 @@ var createPlugin = exports.createPlugin = function createPlugin(_schema, options
       return;
     },
     key: _pluginKey.stateKey,
-    view: function view(_view) {
-      var pluginState = getMediaPluginState(_view.state);
-      pluginState.setView(_view);
+    view: function view(_view2) {
+      var pluginState = getMediaPluginState(_view2.state);
+      pluginState.setView(_view2);
       pluginState.updateElement();
       return {
         update: function update() {
@@ -953,7 +1146,7 @@ var createPlugin = exports.createPlugin = function createPlugin(_schema, options
         if (state.selection instanceof _state2.TextSelection || state.selection instanceof _state2.AllSelection || state.selection instanceof _cellSelection.CellSelection) {
           doc.nodesBetween(state.selection.from, state.selection.to, function (node, pos) {
             if (node.type === schema.nodes.media) {
-              mediaNodes.push(_view2.Decoration.node(pos, pos + node.nodeSize, {}, {
+              mediaNodes.push(_view3.Decoration.node(pos, pos + node.nodeSize, {}, {
                 type: 'media',
                 selected: true
               }));
@@ -968,7 +1161,7 @@ var createPlugin = exports.createPlugin = function createPlugin(_schema, options
           if (node.type === schema.nodes.mediaSingle || node.type === schema.nodes.mediaGroup) {
             doc.nodesBetween($from.pos, $from.pos + node.nodeSize, function (mediaNode, mediaPos) {
               if (mediaNode.type === schema.nodes.media) {
-                mediaNodes.push(_view2.Decoration.node(mediaPos, mediaPos + mediaNode.nodeSize, {}, {
+                mediaNodes.push(_view3.Decoration.node(mediaPos, mediaPos + mediaNode.nodeSize, {}, {
                   type: 'media',
                   selected: true
                 }));
@@ -980,30 +1173,30 @@ var createPlugin = exports.createPlugin = function createPlugin(_schema, options
         }
         var pluginState = getMediaPluginState(state);
         if (!pluginState.showDropzone) {
-          return _view2.DecorationSet.create(state.doc, mediaNodes);
+          return _view3.DecorationSet.create(state.doc, mediaNodes);
         }
 
         // When a media is already selected
         if (state.selection instanceof _state2.NodeSelection) {
           var _node = state.selection.node;
           if (_node.type === schema.nodes.mediaSingle) {
-            var deco = _view2.Decoration.node(state.selection.from, state.selection.to, {
+            var deco = _view3.Decoration.node(state.selection.from, state.selection.to, {
               class: 'richMedia-selected'
             });
-            return _view2.DecorationSet.create(state.doc, [deco].concat(mediaNodes));
+            return _view3.DecorationSet.create(state.doc, [deco].concat(mediaNodes));
           }
-          return _view2.DecorationSet.create(state.doc, mediaNodes);
+          return _view3.DecorationSet.create(state.doc, mediaNodes);
         }
         var pos = $anchor.pos;
         if ($anchor.parent.type !== schema.nodes.paragraph && $anchor.parent.type !== schema.nodes.codeBlock) {
           pos = (0, _transform.insertPoint)(state.doc, pos, schema.nodes.mediaGroup);
         }
         if (pos === null || pos === undefined) {
-          return _view2.DecorationSet.create(state.doc, mediaNodes);
+          return _view3.DecorationSet.create(state.doc, mediaNodes);
         }
         // eslint-disable-next-line @atlaskit/platform/prefer-crypto-random-uuid -- Use crypto.randomUUID instead
         var dropPlaceholderKey = (0, _uuid.default)();
-        var dropPlaceholders = [_view2.Decoration.widget(pos, function () {
+        var dropPlaceholders = [_view3.Decoration.widget(pos, function () {
           return createDropPlaceholder(intl, nodeViewPortalProviderAPI, dropPlaceholderKey, mediaOptions && mediaOptions.allowDropzoneDropLine);
         }, {
           key: 'drop-placeholder',
@@ -1013,7 +1206,7 @@ var createPlugin = exports.createPlugin = function createPlugin(_schema, options
             }
           }
         })].concat(mediaNodes);
-        return _view2.DecorationSet.create(state.doc, dropPlaceholders);
+        return _view3.DecorationSet.create(state.doc, dropPlaceholders);
       },
       nodeViews: options.nodeViews,
       handleTextInput: function handleTextInput(view, from, to, text) {

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

@@ -29,6 +29,7 @@ var _imageFullscreen = _interopRequireDefault(require("@atlaskit/icon/core/image
 var _imageInline = _interopRequireDefault(require("@atlaskit/icon/core/image-inline"));
 var _maximize = _interopRequireDefault(require("@atlaskit/icon/core/maximize"));
 var _smartLinkCard = _interopRequireDefault(require("@atlaskit/icon/core/smart-link-card"));
+var _upload = _interopRequireDefault(require("@atlaskit/icon/core/upload"));
 var _mediaFilmstrip = require("@atlaskit/media-filmstrip");
 var _mediaUi = require("@atlaskit/media-ui");
 var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
@@ -892,6 +893,7 @@ var floatingToolbar = exports.floatingToolbar = function floatingToolbar(state,
   if (!mediaPluginState.isResizing && (0, _toolbarFlagCheck.areToolbarFlagsEnabled)(Boolean(pluginInjectionApi === null || pluginInjectionApi === void 0 ? void 0 : pluginInjectionApi.toolbar))) {
     var _pluginInjectionApi$a0, _pluginInjectionApi$a1, _pluginInjectionApi$a10;
     (0, _utils2.updateToFullHeightSeparator)(items);
+    var showReplaceOption = !isViewOnly && mediaPluginState.allowsUploads && (0, _expValEquals.expValEquals)('platform_editor_inline_media_replacement', 'isEnabled', true) && selectedNodeType === mediaSingle;
     var customOptions = [].concat((0, _toConsumableArray2.default)((0, _linking3.getLinkingDropdownOptions)(state, intl, mediaLinkingState, allowMediaInline && selectedNodeType && selectedNodeType === mediaInline, allowLinking, isViewOnly)), (0, _toConsumableArray2.default)((0, _altText2.getAltTextDropdownOption)(state, intl.formatMessage, allowAltTextOnImages, selectedNodeType, pluginInjectionApi === null || pluginInjectionApi === void 0 || (_pluginInjectionApi$a0 = pluginInjectionApi.analytics) === null || _pluginInjectionApi$a0 === void 0 ? void 0 : _pluginInjectionApi$a0.actions)), (0, _toConsumableArray2.default)((0, _pixelResizing2.getResizeDropdownOption)(options, state, intl.formatMessage, selectedNodeType)));
     if (customOptions.length) {
       customOptions.push({
@@ -910,7 +912,17 @@ var floatingToolbar = exports.floatingToolbar = function floatingToolbar(state,
       type: 'overflow-dropdown',
       id: 'media',
       testId: overflowDropdwonBtnTriggerTestId,
-      options: [].concat((0, _toConsumableArray2.default)(customOptions), [_objectSpread({
+      options: [].concat((0, _toConsumableArray2.default)(customOptions), (0, _toConsumableArray2.default)(showReplaceOption ? [{
+        title: intl.formatMessage(_messages.mediaAndEmbedToolbarMessages.replaceMedia),
+        onClick: function onClick() {
+          mediaPluginState.showMediaPickerForReplace();
+          return true;
+        },
+        icon: /*#__PURE__*/_react.default.createElement(_upload.default, {
+          label: ""
+        }),
+        testId: 'media-replace-toolbar-button'
+      }] : []), [_objectSpread({
         title: intl === null || intl === void 0 ? void 0 : intl.formatMessage(_messages.default.copyToClipboard),
         onClick: function onClick() {
           var _pluginInjectionApi$c4, _pluginInjectionApi$f3;

package/dist/es2019/nodeviews/helpers.js

@@ -1,3 +1,7 @@
 export const hasPrivateAttrsChanged = (currentAttrs, newAttrs) => {
-  return currentAttrs.__fileName !== newAttrs.__fileName || currentAttrs.__fileMimeType !== newAttrs.__fileMimeType || currentAttrs.__fileSize !== newAttrs.__fileSize || currentAttrs.__contextId !== newAttrs.__contextId;
+  return currentAttrs.__fileName !== newAttrs.__fileName || currentAttrs.__fileMimeType !== newAttrs.__fileMimeType || currentAttrs.__fileSize !== newAttrs.__fileSize || currentAttrs.__contextId !== newAttrs.__contextId ||
+  // A changed id means the media source was replaced — always re-initialise
+  // the updater so getRemoteDimensions fetches dimensions for the new file.
+  // Only check when id is explicitly present on the new attrs (it's Partial).
+  'id' in newAttrs && currentAttrs.id !== newAttrs.id;
 };