@ckeditor/ckeditor5-image 40.0.0 → 40.2.0

package/src/image/insertimagecommand.js

@@ -1,120 +1,120 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @module image/image/insertimagecommand
- */
-import { Command } from 'ckeditor5/src/core';
-import { logWarning, toArray } from 'ckeditor5/src/utils';
-/**
- * Insert image command.
- *
- * The command is registered by the {@link module:image/image/imageediting~ImageEditing} plugin as `insertImage`
- * and it is also available via aliased `imageInsert` name.
- *
- * In order to insert an image at the current selection position
- * (according to the {@link module:widget/utils~findOptimalInsertionRange} algorithm),
- * execute the command and specify the image source:
- *
- * ```ts
- * editor.execute( 'insertImage', { source: 'http://url.to.the/image' } );
- * ```
- *
- * It is also possible to insert multiple images at once:
- *
- * ```ts
- * editor.execute( 'insertImage', {
- * 	source:  [
- * 		'path/to/image.jpg',
- * 		'path/to/other-image.jpg'
- * 	]
- * } );
- * ```
- *
- * If you want to take the full control over the process, you can specify individual model attributes:
- *
- * ```ts
- * editor.execute( 'insertImage', {
- * 	source:  [
- * 		{ src: 'path/to/image.jpg', alt: 'First alt text' },
- * 		{ src: 'path/to/other-image.jpg', alt: 'Second alt text', customAttribute: 'My attribute value' }
- * 	]
- * } );
- * ```
- */
-export default class InsertImageCommand extends Command {
-    /**
-     * @inheritDoc
-     */
-    constructor(editor) {
-        super(editor);
-        const configImageInsertType = editor.config.get('image.insert.type');
-        if (!editor.plugins.has('ImageBlockEditing')) {
-            if (configImageInsertType === 'block') {
-                /**
-                 * The {@link module:image/imageblock~ImageBlock} plugin must be enabled to allow inserting block images. See
-                 * {@link module:image/imageconfig~ImageInsertConfig#type} to learn more.
-                 *
-                 * @error image-block-plugin-required
-                 */
-                logWarning('image-block-plugin-required');
-            }
-        }
-        if (!editor.plugins.has('ImageInlineEditing')) {
-            if (configImageInsertType === 'inline') {
-                /**
-                 * The {@link module:image/imageinline~ImageInline} plugin must be enabled to allow inserting inline images. See
-                 * {@link module:image/imageconfig~ImageInsertConfig#type} to learn more.
-                 *
-                 * @error image-inline-plugin-required
-                 */
-                logWarning('image-inline-plugin-required');
-            }
-        }
-    }
-    /**
-     * @inheritDoc
-     */
-    refresh() {
-        const imageUtils = this.editor.plugins.get('ImageUtils');
-        this.isEnabled = imageUtils.isImageAllowed();
-    }
-    /**
-     * Executes the command.
-     *
-     * @fires execute
-     * @param options Options for the executed command.
-     * @param options.source The image source or an array of image sources to insert.
-     * See the documentation of the command to learn more about accepted formats.
-     */
-    execute(options) {
-        const sourceDefinitions = toArray(options.source);
-        const selection = this.editor.model.document.selection;
-        const imageUtils = this.editor.plugins.get('ImageUtils');
-        // In case of multiple images, each image (starting from the 2nd) will be inserted at a position that
-        // follows the previous one. That will move the selection and, to stay on the safe side and make sure
-        // all images inherit the same selection attributes, they are collected beforehand.
-        //
-        // Applying these attributes ensures, for instance, that inserting an (inline) image into a link does
-        // not split that link but preserves its continuity.
-        //
-        // Note: Selection attributes that do not make sense for images will be filtered out by insertImage() anyway.
-        const selectionAttributes = Object.fromEntries(selection.getAttributes());
-        sourceDefinitions.forEach((sourceDefinition, index) => {
-            const selectedElement = selection.getSelectedElement();
-            if (typeof sourceDefinition === 'string') {
-                sourceDefinition = { src: sourceDefinition };
-            }
-            // Inserting of an inline image replace the selected element and make a selection on the inserted image.
-            // Therefore inserting multiple inline images requires creating position after each element.
-            if (index && selectedElement && imageUtils.isImage(selectedElement)) {
-                const position = this.editor.model.createPositionAfter(selectedElement);
-                imageUtils.insertImage({ ...sourceDefinition, ...selectionAttributes }, position);
-            }
-            else {
-                imageUtils.insertImage({ ...sourceDefinition, ...selectionAttributes });
-            }
-        });
-    }
-}
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module image/image/insertimagecommand
+ */
+import { Command } from 'ckeditor5/src/core';
+import { logWarning, toArray } from 'ckeditor5/src/utils';
+/**
+ * Insert image command.
+ *
+ * The command is registered by the {@link module:image/image/imageediting~ImageEditing} plugin as `insertImage`
+ * and it is also available via aliased `imageInsert` name.
+ *
+ * In order to insert an image at the current selection position
+ * (according to the {@link module:widget/utils~findOptimalInsertionRange} algorithm),
+ * execute the command and specify the image source:
+ *
+ * ```ts
+ * editor.execute( 'insertImage', { source: 'http://url.to.the/image' } );
+ * ```
+ *
+ * It is also possible to insert multiple images at once:
+ *
+ * ```ts
+ * editor.execute( 'insertImage', {
+ * 	source:  [
+ * 		'path/to/image.jpg',
+ * 		'path/to/other-image.jpg'
+ * 	]
+ * } );
+ * ```
+ *
+ * If you want to take the full control over the process, you can specify individual model attributes:
+ *
+ * ```ts
+ * editor.execute( 'insertImage', {
+ * 	source:  [
+ * 		{ src: 'path/to/image.jpg', alt: 'First alt text' },
+ * 		{ src: 'path/to/other-image.jpg', alt: 'Second alt text', customAttribute: 'My attribute value' }
+ * 	]
+ * } );
+ * ```
+ */
+export default class InsertImageCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        super(editor);
+        const configImageInsertType = editor.config.get('image.insert.type');
+        if (!editor.plugins.has('ImageBlockEditing')) {
+            if (configImageInsertType === 'block') {
+                /**
+                 * The {@link module:image/imageblock~ImageBlock} plugin must be enabled to allow inserting block images. See
+                 * {@link module:image/imageconfig~ImageInsertConfig#type} to learn more.
+                 *
+                 * @error image-block-plugin-required
+                 */
+                logWarning('image-block-plugin-required');
+            }
+        }
+        if (!editor.plugins.has('ImageInlineEditing')) {
+            if (configImageInsertType === 'inline') {
+                /**
+                 * The {@link module:image/imageinline~ImageInline} plugin must be enabled to allow inserting inline images. See
+                 * {@link module:image/imageconfig~ImageInsertConfig#type} to learn more.
+                 *
+                 * @error image-inline-plugin-required
+                 */
+                logWarning('image-inline-plugin-required');
+            }
+        }
+    }
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const imageUtils = this.editor.plugins.get('ImageUtils');
+        this.isEnabled = imageUtils.isImageAllowed();
+    }
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options Options for the executed command.
+     * @param options.source The image source or an array of image sources to insert.
+     * See the documentation of the command to learn more about accepted formats.
+     */
+    execute(options) {
+        const sourceDefinitions = toArray(options.source);
+        const selection = this.editor.model.document.selection;
+        const imageUtils = this.editor.plugins.get('ImageUtils');
+        // In case of multiple images, each image (starting from the 2nd) will be inserted at a position that
+        // follows the previous one. That will move the selection and, to stay on the safe side and make sure
+        // all images inherit the same selection attributes, they are collected beforehand.
+        //
+        // Applying these attributes ensures, for instance, that inserting an (inline) image into a link does
+        // not split that link but preserves its continuity.
+        //
+        // Note: Selection attributes that do not make sense for images will be filtered out by insertImage() anyway.
+        const selectionAttributes = Object.fromEntries(selection.getAttributes());
+        sourceDefinitions.forEach((sourceDefinition, index) => {
+            const selectedElement = selection.getSelectedElement();
+            if (typeof sourceDefinition === 'string') {
+                sourceDefinition = { src: sourceDefinition };
+            }
+            // Inserting of an inline image replace the selected element and make a selection on the inserted image.
+            // Therefore inserting multiple inline images requires creating position after each element.
+            if (index && selectedElement && imageUtils.isImage(selectedElement)) {
+                const position = this.editor.model.createPositionAfter(selectedElement);
+                imageUtils.insertImage({ ...sourceDefinition, ...selectionAttributes }, position);
+            }
+            else {
+                imageUtils.insertImage({ ...sourceDefinition, ...selectionAttributes });
+            }
+        });
+    }
+}

package/src/image/replaceimagesourcecommand.d.ts

@@ -1,34 +1,51 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-import { Command } from 'ckeditor5/src/core';
-/**
- * @module image/image/replaceimagesourcecommand
- */
-/**
- * Replace image source command.
- *
- * Changes image source to the one provided. Can be executed as follows:
- *
- * ```ts
- * editor.execute( 'replaceImageSource', { source: 'http://url.to.the/image' } );
- * ```
- */
-export default class ReplaceImageSourceCommand extends Command {
-    value: string | null;
-    /**
-     * @inheritDoc
-     */
-    refresh(): void;
-    /**
-     * Executes the command.
-     *
-     * @fires execute
-     * @param options Options for the executed command.
-     * @param options.source The image source to replace.
-     */
-    execute(options: {
-        source: string;
-    }): void;
-}
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Command, type Editor } from 'ckeditor5/src/core';
+import type { Writer, Element } from 'ckeditor5/src/engine';
+/**
+ * @module image/image/replaceimagesourcecommand
+ */
+/**
+ * Replace image source command.
+ *
+ * Changes image source to the one provided. Can be executed as follows:
+ *
+ * ```ts
+ * editor.execute( 'replaceImageSource', { source: 'http://url.to.the/image' } );
+ * ```
+ */
+export default class ReplaceImageSourceCommand extends Command {
+    value: string | null;
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options Options for the executed command.
+     * @param options.source The image source to replace.
+     */
+    execute(options: {
+        source: string;
+    }): void;
+    /**
+     * Cleanup image attributes that are not relevant to the new source.
+     *
+     * Removed attributes are: 'srcset', 'sizes', 'sources', 'width', 'height', 'alt'.
+     *
+     * This method is decorated, to allow custom cleanup logic.
+     * For example, to remove 'myImageId' attribute after 'src' has changed:
+     *
+     * ```ts
+     * replaceImageSourceCommand.on( 'cleanupImage', ( eventInfo, [ writer, image ] ) => {
+     * 	writer.removeAttribute( 'myImageId', image );
+     * } );
+     * ```
+     */
+    cleanupImage(writer: Writer, image: Element): void;
+}

package/src/image/replaceimagesourcecommand.js

@@ -1,44 +1,75 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-import { Command } from 'ckeditor5/src/core';
-/**
- * @module image/image/replaceimagesourcecommand
- */
-/**
- * Replace image source command.
- *
- * Changes image source to the one provided. Can be executed as follows:
- *
- * ```ts
- * editor.execute( 'replaceImageSource', { source: 'http://url.to.the/image' } );
- * ```
- */
-export default class ReplaceImageSourceCommand extends Command {
-    /**
-     * @inheritDoc
-     */
-    refresh() {
-        const editor = this.editor;
-        const imageUtils = editor.plugins.get('ImageUtils');
-        const element = this.editor.model.document.selection.getSelectedElement();
-        this.isEnabled = imageUtils.isImage(element);
-        this.value = this.isEnabled ? element.getAttribute('src') : null;
-    }
-    /**
-     * Executes the command.
-     *
-     * @fires execute
-     * @param options Options for the executed command.
-     * @param options.source The image source to replace.
-     */
-    execute(options) {
-        const image = this.editor.model.document.selection.getSelectedElement();
-        this.editor.model.change(writer => {
-            writer.setAttribute('src', options.source, image);
-            writer.removeAttribute('srcset', image);
-            writer.removeAttribute('sizes', image);
-        });
-    }
-}
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Command } from 'ckeditor5/src/core';
+/**
+ * @module image/image/replaceimagesourcecommand
+ */
+/**
+ * Replace image source command.
+ *
+ * Changes image source to the one provided. Can be executed as follows:
+ *
+ * ```ts
+ * editor.execute( 'replaceImageSource', { source: 'http://url.to.the/image' } );
+ * ```
+ */
+export default class ReplaceImageSourceCommand extends Command {
+    constructor(editor) {
+        super(editor);
+        this.decorate('cleanupImage');
+    }
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const editor = this.editor;
+        const imageUtils = editor.plugins.get('ImageUtils');
+        const element = this.editor.model.document.selection.getSelectedElement();
+        this.isEnabled = imageUtils.isImage(element);
+        this.value = this.isEnabled ? element.getAttribute('src') : null;
+    }
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options Options for the executed command.
+     * @param options.source The image source to replace.
+     */
+    execute(options) {
+        const image = this.editor.model.document.selection.getSelectedElement();
+        const imageUtils = this.editor.plugins.get('ImageUtils');
+        this.editor.model.change(writer => {
+            writer.setAttribute('src', options.source, image);
+            this.cleanupImage(writer, image);
+            imageUtils.setImageNaturalSizeAttributes(image);
+        });
+    }
+    /**
+     * Cleanup image attributes that are not relevant to the new source.
+     *
+     * Removed attributes are: 'srcset', 'sizes', 'sources', 'width', 'height', 'alt'.
+     *
+     * This method is decorated, to allow custom cleanup logic.
+     * For example, to remove 'myImageId' attribute after 'src' has changed:
+     *
+     * ```ts
+     * replaceImageSourceCommand.on( 'cleanupImage', ( eventInfo, [ writer, image ] ) => {
+     * 	writer.removeAttribute( 'myImageId', image );
+     * } );
+     * ```
+     */
+    cleanupImage(writer, image) {
+        writer.removeAttribute('srcset', image);
+        writer.removeAttribute('sizes', image);
+        /**
+         * In case responsive images some attributes should be cleaned up.
+         * Check: https://github.com/ckeditor/ckeditor5/issues/15093
+         */
+        writer.removeAttribute('sources', image);
+        writer.removeAttribute('width', image);
+        writer.removeAttribute('height', image);
+        writer.removeAttribute('alt', image);
+    }
+}

package/src/image/ui/utils.d.ts

@@ -1,25 +1,25 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @module image/image/ui/utils
- */
-import type { PositionOptions } from 'ckeditor5/src/utils';
-import type { Editor } from 'ckeditor5/src/core';
-/**
- * A helper utility that positions the
- * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} instance
- * with respect to the image in the editor content, if one is selected.
- *
- * @param editor The editor instance.
- */
-export declare function repositionContextualBalloon(editor: Editor): void;
-/**
- * Returns the positioning options that control the geometry of the
- * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} with respect
- * to the selected element in the editor content.
- *
- * @param editor The editor instance.
- */
-export declare function getBalloonPositionData(editor: Editor): Partial<PositionOptions>;
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module image/image/ui/utils
+ */
+import type { PositionOptions } from 'ckeditor5/src/utils';
+import type { Editor } from 'ckeditor5/src/core';
+/**
+ * A helper utility that positions the
+ * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} instance
+ * with respect to the image in the editor content, if one is selected.
+ *
+ * @param editor The editor instance.
+ */
+export declare function repositionContextualBalloon(editor: Editor): void;
+/**
+ * Returns the positioning options that control the geometry of the
+ * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} with respect
+ * to the selected element in the editor content.
+ *
+ * @param editor The editor instance.
+ */
+export declare function getBalloonPositionData(editor: Editor): Partial<PositionOptions>;

package/src/image/ui/utils.js

@@ -1,44 +1,44 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-import { BalloonPanelView } from 'ckeditor5/src/ui';
-/**
- * A helper utility that positions the
- * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} instance
- * with respect to the image in the editor content, if one is selected.
- *
- * @param editor The editor instance.
- */
-export function repositionContextualBalloon(editor) {
-    const balloon = editor.plugins.get('ContextualBalloon');
-    const imageUtils = editor.plugins.get('ImageUtils');
-    if (imageUtils.getClosestSelectedImageWidget(editor.editing.view.document.selection)) {
-        const position = getBalloonPositionData(editor);
-        balloon.updatePosition(position);
-    }
-}
-/**
- * Returns the positioning options that control the geometry of the
- * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} with respect
- * to the selected element in the editor content.
- *
- * @param editor The editor instance.
- */
-export function getBalloonPositionData(editor) {
-    const editingView = editor.editing.view;
-    const defaultPositions = BalloonPanelView.defaultPositions;
-    const imageUtils = editor.plugins.get('ImageUtils');
-    return {
-        target: editingView.domConverter.mapViewToDom(imageUtils.getClosestSelectedImageWidget(editingView.document.selection)),
-        positions: [
-            defaultPositions.northArrowSouth,
-            defaultPositions.northArrowSouthWest,
-            defaultPositions.northArrowSouthEast,
-            defaultPositions.southArrowNorth,
-            defaultPositions.southArrowNorthWest,
-            defaultPositions.southArrowNorthEast,
-            defaultPositions.viewportStickyNorth
-        ]
-    };
-}
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { BalloonPanelView } from 'ckeditor5/src/ui';
+/**
+ * A helper utility that positions the
+ * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} instance
+ * with respect to the image in the editor content, if one is selected.
+ *
+ * @param editor The editor instance.
+ */
+export function repositionContextualBalloon(editor) {
+    const balloon = editor.plugins.get('ContextualBalloon');
+    const imageUtils = editor.plugins.get('ImageUtils');
+    if (imageUtils.getClosestSelectedImageWidget(editor.editing.view.document.selection)) {
+        const position = getBalloonPositionData(editor);
+        balloon.updatePosition(position);
+    }
+}
+/**
+ * Returns the positioning options that control the geometry of the
+ * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} with respect
+ * to the selected element in the editor content.
+ *
+ * @param editor The editor instance.
+ */
+export function getBalloonPositionData(editor) {
+    const editingView = editor.editing.view;
+    const defaultPositions = BalloonPanelView.defaultPositions;
+    const imageUtils = editor.plugins.get('ImageUtils');
+    return {
+        target: editingView.domConverter.mapViewToDom(imageUtils.getClosestSelectedImageWidget(editingView.document.selection)),
+        positions: [
+            defaultPositions.northArrowSouth,
+            defaultPositions.northArrowSouthWest,
+            defaultPositions.northArrowSouthEast,
+            defaultPositions.southArrowNorth,
+            defaultPositions.southArrowNorthWest,
+            defaultPositions.southArrowNorthEast,
+            defaultPositions.viewportStickyNorth
+        ]
+    };
+}