@atlaskit/editor-plugin-media 12.4.1 → 12.5.1

package/dist/es2019/nodeviews/mediaNodeUpdater.js

@@ -1,8 +1,10 @@
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
 // eslint-disable-next-line @atlaskit/platform/prefer-crypto-random-uuid -- Use crypto.randomUUID instead
 import uuidV4 from 'uuid/v4';
+import { SetAttrsStep } from '@atlaskit/adf-schema/steps';
 import { ACTION, ACTION_SUBJECT, EVENT_TYPE } from '@atlaskit/editor-common/analytics';
 import { DEFAULT_IMAGE_HEIGHT, DEFAULT_IMAGE_WIDTH } from '@atlaskit/editor-common/media-single';
+import { NodeSelection } from '@atlaskit/editor-prosemirror/state';
 import { getAttrsFromUrl, isImageRepresentationReady, isMediaBlobUrl } from '@atlaskit/media-client';
 import { getMediaClient } from '@atlaskit/media-client-react';
 import { getClientIdForFile } from '@atlaskit/media-common';
@@ -11,6 +13,7 @@ import { replaceExternalMedia, updateCurrentMediaNodeAttrs, updateMediaNodeAttrs
 import { stateKey as mediaStateKey } from '../pm-plugins/plugin-key';
 import { batchMediaNodeAttrsUpdate } from '../pm-plugins/utils/batchMediaNodeAttrs';
 import { getIdentifier } from '../pm-plugins/utils/media-common';
+import { computeReplacementDisplayWidth } from './nodeviewHelpers';
 const isMediaTypeSupported = type => {
   if (type) {
     return ['image', 'file'].includes(type);
@@ -179,7 +182,80 @@ export class MediaNodeUpdater {
       return attrs.__contextId || null;
     });
     _defineProperty(this, "updateDimensions", dimensions => {
-      batchMediaNodeAttrsUpdate(this.props.view, {
+      const {
+        view
+      } = this.props;
+      const mediaPluginState = mediaStateKey.getState(view.state);
+      const 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, _mediaSingleNode$attr2;
+        // 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.
+        const lineLength = (_this$props$lineLengt = this.props.lineLength) !== null && _this$props$lineLengt !== void 0 ? _this$props$lineLengt : 760;
+        const {
+          state
+        } = view;
+        const {
+          mediaSingle
+        } = state.schema.nodes;
+        // Typed explicitly because TypeScript can't track mutations inside
+        // the descendants callback closure and would narrow these to `never`.
+        let mediaSinglePos = null;
+        let mediaSingleNode = null;
+        let mediaPos = null;
+        state.doc.descendants((node, pos) => {
+          if (mediaSinglePos !== null) {
+            return false;
+          }
+          if (node.type === mediaSingle) {
+            const mediaChild = node.firstChild;
+            if (mediaChild && mediaChild.attrs.id === dimensions.id) {
+              mediaSinglePos = pos;
+              mediaSingleNode = node;
+              mediaPos = pos + 1;
+            }
+          }
+          return true;
+        });
+        const layout = (_mediaSingleNode$attr = (_mediaSingleNode = mediaSingleNode) === null || _mediaSingleNode === void 0 ? void 0 : (_mediaSingleNode$attr2 = _mediaSingleNode.attrs) === null || _mediaSingleNode$attr2 === void 0 ? void 0 : _mediaSingleNode$attr2.layout) !== null && _mediaSingleNode$attr !== void 0 ? _mediaSingleNode$attr : 'center';
+        const newDisplayWidth = computeReplacementDisplayWidth(targetDisplayHeight, dimensions.width, dimensions.height, layout, lineLength);
+        if (mediaSinglePos !== null && mediaSingleNode !== null && mediaPos !== null) {
+          const tr = state.tr;
+
+          // Update intrinsic dimensions on the media child node
+          tr.step(new SetAttrsStep(mediaPos, {
+            height: dimensions.height,
+            width: dimensions.width
+          }));
+
+          // Update display width on the mediaSingle parent
+          tr.setNodeMarkup(mediaSinglePos, undefined, {
+            ...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 NodeSelection) {
+            tr.setSelection(NodeSelection.create(tr.doc, mediaSinglePos));
+          }
+          tr.setMeta('scrollIntoView', false);
+          view.dispatch(tr);
+          return;
+        }
+      }
+
+      // Normal (non-replace) path: use the existing batched update mechanism
+      batchMediaNodeAttrsUpdate(view, {
         id: dimensions.id,
         nextAttributes: {
           height: dimensions.height,

package/dist/es2019/nodeviews/mediaSingleNext.js

@@ -104,7 +104,8 @@ const useMediaAsyncOperations = ({
   mediaNode,
   mediaNodeUpdater,
   addPendingTask,
-  getPos
+  getPos,
+  mediaChildNodeId
 }) => {
   React.useEffect(() => {
     if (!mediaNodeUpdater) {
@@ -122,7 +123,11 @@ const useMediaAsyncOperations = ({
       mediaNode,
       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]);
 };
 const noop = () => {};
 
@@ -248,7 +253,7 @@ const useUpdateSizeCallback = ({
  */
 const FALLBACK_MOST_COMMON_WIDTH = 760;
 export const MediaSingleNodeNext = mediaSingleNodeNextProps => {
-  var _pluginInjectionApi$m, _pluginInjectionApi$m2, _mediaNode$firstChild;
+  var _mediaNode$firstChild, _pluginInjectionApi$m, _pluginInjectionApi$m2, _mediaNode$firstChild2;
   const {
     selected,
     getPos,
@@ -288,7 +293,8 @@ export const MediaSingleNodeNext = mediaSingleNodeNextProps => {
     mediaNodeUpdater,
     getPos,
     mediaNode,
-    addPendingTask: addPendingTask || noop
+    addPendingTask: addPendingTask || noop,
+    mediaChildNodeId: (_mediaNode$firstChild = mediaNode.firstChild) === null || _mediaNode$firstChild === void 0 ? void 0 : _mediaNode$firstChild.attrs.id
   });
   React.useLayoutEffect(() => {
     mountedRef.current = true;
@@ -389,7 +395,7 @@ export const MediaSingleNodeNext = mediaSingleNodeNextProps => {
   }, [mediaSingleWidthAttribute, widthType, width, layout, contentWidthForLegacyExperience, containerWidth]);
   const currentMaxWidth = isSelected ? pluginInjectionApi === null || pluginInjectionApi === void 0 ? void 0 : (_pluginInjectionApi$m = pluginInjectionApi.media) === null || _pluginInjectionApi$m === void 0 ? void 0 : (_pluginInjectionApi$m2 = _pluginInjectionApi$m.sharedState.currentState()) === null || _pluginInjectionApi$m2 === void 0 ? void 0 : _pluginInjectionApi$m2.currentMaxWidth : undefined;
   const contentWidth = currentMaxWidth || lineLength;
-  const isCurrentNodeDrafting = Boolean(isDrafting && targetNodeId === (mediaNode === null || mediaNode === void 0 ? void 0 : (_mediaNode$firstChild = mediaNode.firstChild) === null || _mediaNode$firstChild === void 0 ? void 0 : _mediaNode$firstChild.attrs.id));
+  const isCurrentNodeDrafting = Boolean(isDrafting && targetNodeId === (mediaNode === null || mediaNode === void 0 ? void 0 : (_mediaNode$firstChild2 = mediaNode.firstChild) === null || _mediaNode$firstChild2 === void 0 ? void 0 : _mediaNode$firstChild2.attrs.id));
   const mediaSingleWrapperRef = /*#__PURE__*/React.createRef();
   const captionPlaceHolderRef = /*#__PURE__*/React.createRef();
   const browser = getBrowserInfo();

package/dist/es2019/nodeviews/nodeviewHelpers.js

@@ -0,0 +1,20 @@
+import { akEditorFullWidthLayoutWidth, akEditorWideLayoutWidth } from '@atlaskit/editor-shared-styles';
+const 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
+ */
+export const computeReplacementDisplayWidth = (targetDisplayHeight, newIntrinsicWidth, newIntrinsicHeight, layout, lineLength) => {
+  if (newIntrinsicHeight <= 0) {
+    return MIN_MEDIA_DISPLAY_WIDTH;
+  }
+  const unclamped = targetDisplayHeight * (newIntrinsicWidth / newIntrinsicHeight);
+  const maxWidth = layout === 'full-width' ? akEditorFullWidthLayoutWidth : layout === 'wide' ? akEditorWideLayoutWidth : lineLength;
+  return Math.max(MIN_MEDIA_DISPLAY_WIDTH, Math.min(unclamped, maxWidth));
+};

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

@@ -4,6 +4,7 @@ import React from 'react';
 import { RawIntlProvider } from 'react-intl';
 // eslint-disable-next-line @atlaskit/platform/prefer-crypto-random-uuid -- Use crypto.randomUUID instead
 import uuid from 'uuid';
+import { SetAttrsStep } from '@atlaskit/adf-schema/steps';
 import { ACTION, ACTION_SUBJECT, ACTION_SUBJECT_ID, EVENT_TYPE, INPUT_METHOD } from '@atlaskit/editor-common/analytics';
 import { getBrowserInfo } from '@atlaskit/editor-common/browser';
 import { mediaInlineImagesEnabled } from '@atlaskit/editor-common/media-inline';
@@ -18,6 +19,7 @@ import { CellSelection } from '@atlaskit/editor-tables/cell-selection';
 import { isFileIdentifier } from '@atlaskit/media-client';
 import { getMediaFeatureFlag } from '@atlaskit/media-common';
 import { fg } from '@atlaskit/platform-feature-flags';
+import { createMediaNodeUpdater } from '../nodeviews/mediaNodeUpdater';
 // Ignored via go/ees005
 // eslint-disable-next-line import/no-namespace
 import * as helpers from '../pm-plugins/commands/helpers';
@@ -72,6 +74,15 @@ export class MediaPluginStateImplementation {
     _defineProperty(this, "destroyed", false);
     _defineProperty(this, "removeOnCloseListener", () => {});
     _defineProperty(this, "onPopupToggleCallback", () => {});
+    // 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.
+    _defineProperty(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.
+    _defineProperty(this, "replaceMediaTargetDisplayHeight", null);
     _defineProperty(this, "identifierCount", new Map());
     // This is to enable mediaShallowCopySope to enable only shallow copying media referenced within the edtior
     // see: trackOutOfScopeIdentifier
@@ -107,7 +118,7 @@ export class MediaPluginStateImplementation {
      * called when we insert a new file via the picker (connected via pickerfacade)
      */
     _defineProperty(this, "insertFile", (mediaState, onMediaStateChanged, pickerType, insertMediaVia) => {
-      var _this$pluginInjection, _this$pluginInjection2, _mediaState$collectio, _this$pluginInjection3, _this$pluginInjection4;
+      var _this$pluginInjection, _this$pluginInjection2, _mediaState$collectio, _this$pluginInjection6, _this$pluginInjection7;
       const {
         state
       } = this.view;
@@ -121,6 +132,21 @@ export class 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;
+        const {
+          mediaSingle
+        } = state.schema.nodes;
+        const isStillOnTargetMedia = state.selection instanceof 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({
@@ -131,13 +157,130 @@ export class MediaPluginStateImplementation {
         this.uploadInProgressSubscriptions.forEach(fn => fn(true));
         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;
+        const {
+          state: currentState
+        } = this.view;
+        const mediaSinglePos = currentState.selection.from;
+        const mediaPos = mediaSinglePos + 1;
+        const 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
+        const tr = currentState.tr;
+        tr.step(new SetAttrsStep(mediaPos, {
+          id: mediaState.id,
+          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(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);
+        const isEndState = state => 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.
+        const triggerDimensionFetch = () => {
+          // Find the media node in the doc by id and create a temporary
+          // MediaNodeUpdater to fetch and apply dimensions
+          const {
+            state: editorState
+          } = this.view;
+          const {
+            mediaSingle: mediaSingleType
+          } = editorState.schema.nodes;
+          let mediaChildNode = null;
+          editorState.doc.descendants(node => {
+            if (mediaChildNode) {
+              return false;
+            }
+            if (node.type === mediaSingleType) {
+              const child = node.firstChild;
+              if (child && child.attrs.id === mediaState.id) {
+                mediaChildNode = child;
+              }
+            }
+            return true;
+          });
+          if (mediaChildNode) {
+            var _this$pluginInjection3, _this$pluginInjection4, _this$pluginInjection5;
+            const updater = 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$pluginInjection3 = this.pluginInjectionApi) === null || _this$pluginInjection3 === void 0 ? void 0 : (_this$pluginInjection4 = _this$pluginInjection3.width) === null || _this$pluginInjection4 === void 0 ? void 0 : (_this$pluginInjection5 = _this$pluginInjection4.sharedState.currentState()) === null || _this$pluginInjection5 === void 0 ? void 0 : _this$pluginInjection5.lineLength
+            });
+            updater.getRemoteDimensions().then(dims => {
+              if (dims) {
+                updater.updateDimensions(dims);
+              }
+            }).catch(() => {
+              // 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)) {
+          const uploadingPromise = new Promise(resolve => {
+            onMediaStateChanged(newState => {
+              if (isEndState(newState)) {
+                resolve(newState);
+              }
+            });
+          });
+          this.taskManager.addPendingTask(uploadingPromise, mediaStateWithContext.id).then(() => {
+            this.updateAndDispatch({
+              allUploadsFinished: true
+            });
+            triggerDimensionFetch();
+          });
+        } else {
+          // File is already in a resolved state — fetch dimensions immediately
+          triggerDimensionFetch();
+        }
+        const {
+          view
+        } = this;
+        if (!view.hasFocus()) {
+          view.focus();
+        }
+        return;
+      }
       switch (getMediaNodeInsertionType(state, this.mediaOptions, mediaStateWithContext.fileMimeType)) {
         case 'inline':
           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
-          const widthPluginState = (_this$pluginInjection3 = this.pluginInjectionApi) === null || _this$pluginInjection3 === void 0 ? void 0 : (_this$pluginInjection4 = _this$pluginInjection3.width) === null || _this$pluginInjection4 === void 0 ? void 0 : _this$pluginInjection4.sharedState.currentState();
+          const widthPluginState = (_this$pluginInjection6 = this.pluginInjectionApi) === null || _this$pluginInjection6 === void 0 ? void 0 : (_this$pluginInjection7 = _this$pluginInjection6.width) === null || _this$pluginInjection7 === void 0 ? void 0 : _this$pluginInjection7.sharedState.currentState();
           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':
@@ -212,6 +355,70 @@ export class 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.
+     */
+    _defineProperty(this, "showMediaPickerForReplace", () => {
+      var _this$pluginInjection8, _this$pluginInjection9, _this$pluginInjection0, _this$pluginInjection1;
+      const {
+        state
+      } = this.view;
+      const {
+        mediaSingle
+      } = state.schema.nodes;
+      const {
+        selection
+      } = state;
+
+      // Only activate replace mode when a mediaSingle is selected
+      if (!(selection instanceof NodeSelection) || selection.node.type !== mediaSingle) {
+        return;
+      }
+      const mediaSingleNode = selection.node;
+      const 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)
+      const widthAttr = mediaSingleNode.attrs.width;
+      const widthType = mediaSingleNode.attrs.widthType;
+      const intrinsicWidth = mediaNode.attrs.width;
+      const intrinsicHeight = mediaNode.attrs.height;
+
+      // Resolve actual pixel display width from mediaSingle attrs.
+      const lineLength = (_this$pluginInjection8 = (_this$pluginInjection9 = this.pluginInjectionApi) === null || _this$pluginInjection9 === void 0 ? void 0 : (_this$pluginInjection0 = _this$pluginInjection9.width) === null || _this$pluginInjection0 === void 0 ? void 0 : (_this$pluginInjection1 = _this$pluginInjection0.sharedState.currentState()) === null || _this$pluginInjection1 === void 0 ? void 0 : _this$pluginInjection1.lineLength) !== null && _this$pluginInjection8 !== void 0 ? _this$pluginInjection8 : 760;
+      let 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();
+    });
     _defineProperty(this, "setBrowseFn", browseFn => {
       this.openMediaPickerBrowser = browseFn;
     });
@@ -618,8 +825,8 @@ export class MediaPluginStateImplementation {
     return;
   }
   get contextIdentifierProvider() {
-    var _this$pluginInjection5, _this$pluginInjection6, _this$pluginInjection7;
-    return (_this$pluginInjection5 = this.pluginInjectionApi) === null || _this$pluginInjection5 === void 0 ? void 0 : (_this$pluginInjection6 = _this$pluginInjection5.contextIdentifier) === null || _this$pluginInjection6 === void 0 ? void 0 : (_this$pluginInjection7 = _this$pluginInjection6.sharedState.currentState()) === null || _this$pluginInjection7 === void 0 ? void 0 : _this$pluginInjection7.contextIdentifierProvider;
+    var _this$pluginInjection10, _this$pluginInjection11, _this$pluginInjection12;
+    return (_this$pluginInjection10 = this.pluginInjectionApi) === null || _this$pluginInjection10 === void 0 ? void 0 : (_this$pluginInjection11 = _this$pluginInjection10.contextIdentifier) === null || _this$pluginInjection11 === void 0 ? void 0 : (_this$pluginInjection12 = _this$pluginInjection11.sharedState.currentState()) === null || _this$pluginInjection12 === void 0 ? void 0 : _this$pluginInjection12.contextIdentifierProvider;
   }
   selectLastAddedMediaNode() {
     var _this$mediaOptions5;

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

@@ -19,6 +19,7 @@ import ImageFullscreenIcon from '@atlaskit/icon/core/image-fullscreen';
 import ImageInlineIcon from '@atlaskit/icon/core/image-inline';
 import MaximizeIcon from '@atlaskit/icon/core/maximize';
 import SmartLinkCardIcon from '@atlaskit/icon/core/smart-link-card';
+import UploadIcon from '@atlaskit/icon/core/upload';
 import { mediaFilmstripItemDOMSelector } from '@atlaskit/media-filmstrip';
 import { messages } from '@atlaskit/media-ui';
 import { fg } from '@atlaskit/platform-feature-flags';
@@ -895,6 +896,7 @@ export const floatingToolbar = (state, intl, options = {}, pluginInjectionApi) =
   if (!mediaPluginState.isResizing && areToolbarFlagsEnabled(Boolean(pluginInjectionApi === null || pluginInjectionApi === void 0 ? void 0 : pluginInjectionApi.toolbar))) {
     var _pluginInjectionApi$a0, _pluginInjectionApi$a1, _pluginInjectionApi$a10;
     updateToFullHeightSeparator(items);
+    const showReplaceOption = !isViewOnly && mediaPluginState.allowsUploads && expValEquals('platform_editor_inline_media_replacement', 'isEnabled', true) && selectedNodeType === mediaSingle;
     const customOptions = [...getLinkingDropdownOptions(state, intl, mediaLinkingState, allowMediaInline && selectedNodeType && selectedNodeType === mediaInline, allowLinking, isViewOnly), ...getAltTextDropdownOption(state, intl.formatMessage, allowAltTextOnImages, selectedNodeType, pluginInjectionApi === null || pluginInjectionApi === void 0 ? void 0 : (_pluginInjectionApi$a0 = pluginInjectionApi.analytics) === null || _pluginInjectionApi$a0 === void 0 ? void 0 : _pluginInjectionApi$a0.actions), ...getResizeDropdownOption(options, state, intl.formatMessage, selectedNodeType)];
     if (customOptions.length) {
       customOptions.push({
@@ -911,7 +913,17 @@ export const floatingToolbar = (state, intl, options = {}, pluginInjectionApi) =
       type: 'overflow-dropdown',
       id: 'media',
       testId: overflowDropdwonBtnTriggerTestId,
-      options: [...customOptions, {
+      options: [...customOptions, ...(showReplaceOption ? [{
+        title: intl.formatMessage(mediaAndEmbedToolbarMessages.replaceMedia),
+        onClick: () => {
+          mediaPluginState.showMediaPickerForReplace();
+          return true;
+        },
+        icon: /*#__PURE__*/React.createElement(UploadIcon, {
+          label: ""
+        }),
+        testId: 'media-replace-toolbar-button'
+      }] : []), {
         title: intl === null || intl === void 0 ? void 0 : intl.formatMessage(commonMessages.copyToClipboard),
         onClick: () => {
           var _pluginInjectionApi$c0, _pluginInjectionApi$f5;

package/dist/esm/nodeviews/helpers.js

@@ -1,3 +1,7 @@
 export var 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/esm/nodeviews/mediaNodeUpdater.js

@@ -10,8 +10,10 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
 import _regeneratorRuntime from "@babel/runtime/regenerator";
 // eslint-disable-next-line @atlaskit/platform/prefer-crypto-random-uuid -- Use crypto.randomUUID instead
 import uuidV4 from 'uuid/v4';
+import { SetAttrsStep } from '@atlaskit/adf-schema/steps';
 import { ACTION, ACTION_SUBJECT, EVENT_TYPE } from '@atlaskit/editor-common/analytics';
 import { DEFAULT_IMAGE_HEIGHT, DEFAULT_IMAGE_WIDTH } from '@atlaskit/editor-common/media-single';
+import { NodeSelection } from '@atlaskit/editor-prosemirror/state';
 import { getAttrsFromUrl, isImageRepresentationReady, isMediaBlobUrl as _isMediaBlobUrl } from '@atlaskit/media-client';
 import { getMediaClient } from '@atlaskit/media-client-react';
 import { getClientIdForFile } from '@atlaskit/media-common';
@@ -20,6 +22,7 @@ import { replaceExternalMedia, updateCurrentMediaNodeAttrs, updateMediaNodeAttrs
 import { stateKey as mediaStateKey } from '../pm-plugins/plugin-key';
 import { batchMediaNodeAttrsUpdate } from '../pm-plugins/utils/batchMediaNodeAttrs';
 import { getIdentifier } from '../pm-plugins/utils/media-common';
+import { computeReplacementDisplayWidth } from './nodeviewHelpers';
 var isMediaTypeSupported = function isMediaTypeSupported(type) {
   if (type) {
     return ['image', 'file'].includes(type);
@@ -318,7 +321,73 @@ export var MediaNodeUpdater = /*#__PURE__*/function () {
       return attrs.__contextId || null;
     });
     _defineProperty(this, "updateDimensions", function (dimensions) {
-      batchMediaNodeAttrsUpdate(_this.props.view, {
+      var view = _this.props.view;
+      var mediaPluginState = mediaStateKey.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 = 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 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 NodeSelection) {
+            tr.setSelection(NodeSelection.create(tr.doc, mediaSinglePos));
+          }
+          tr.setMeta('scrollIntoView', false);
+          view.dispatch(tr);
+          return;
+        }
+      }
+
+      // Normal (non-replace) path: use the existing batched update mechanism
+      batchMediaNodeAttrsUpdate(view, {
         id: dimensions.id,
         nextAttributes: {
           height: dimensions.height,

package/dist/esm/nodeviews/mediaSingleNext.js

@@ -145,7 +145,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.useEffect(function () {
     if (!mediaNodeUpdater) {
       return;
@@ -162,7 +163,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() {};
 
@@ -281,7 +286,7 @@ var useUpdateSizeCallback = function useUpdateSizeCallback(_ref5) {
  */
 var FALLBACK_MOST_COMMON_WIDTH = 760;
 export var 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,
@@ -328,7 +333,8 @@ export var MediaSingleNodeNext = function MediaSingleNodeNext(mediaSingleNodeNex
     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.useLayoutEffect(function () {
     mountedRef.current = true;
@@ -423,7 +429,7 @@ export var MediaSingleNodeNext = function MediaSingleNodeNext(mediaSingleNodeNex
   }, [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.createRef();
   var captionPlaceHolderRef = /*#__PURE__*/React.createRef();
   var browser = getBrowserInfo();