@ckeditor/ckeditor5-image 36.0.0 → 37.0.0-alpha.0

package/src/image/imagetypecommand.js

@@ -2,104 +2,76 @@
  * @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/imagetypecommand
- */
-
 import { Command } from 'ckeditor5/src/core';
-
 /**
  * The image type command. It changes the type of a selected image, depending on the configuration.
- *
- * @extends module:core/command~Command
  */
 export default class ImageTypeCommand extends Command {
-	/**
-	 * @inheritDoc
-	 *
-	 * @param {module:core/editor/editor~Editor} editor
-	 * @param {'imageBlock'|'imageInline'} modelElementName Model element name the command converts to.
-	 */
-	constructor( editor, modelElementName ) {
-		super( editor );
-
-		/**
-		 * Model element name the command converts to.
-		 *
-		 * @readonly
-		 * @private
-		 * @member {'imageBlock'|'imageInline'}
-		 */
-		this._modelElementName = modelElementName;
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	refresh() {
-		const editor = this.editor;
-		const imageUtils = editor.plugins.get( 'ImageUtils' );
-		const element = imageUtils.getClosestSelectedImageElement( this.editor.model.document.selection );
-
-		if ( this._modelElementName === 'imageBlock' ) {
-			this.isEnabled = imageUtils.isInlineImage( element );
-		} else {
-			this.isEnabled = imageUtils.isBlockImage( element );
-		}
-	}
-
-	/**
-	 * Executes the command and changes the type of a selected image.
-	 *
-	 * @fires execute
-	 * @returns {Object|null} An object containing references to old and new model image elements
-	 * (for before and after the change) so external integrations can hook into the decorated
-	 * `execute` event and handle this change. `null` if the type change failed.
-	 */
-	execute() {
-		const editor = this.editor;
-		const model = this.editor.model;
-		const imageUtils = editor.plugins.get( 'ImageUtils' );
-		const oldElement = imageUtils.getClosestSelectedImageElement( model.document.selection );
-		const attributes = Object.fromEntries( oldElement.getAttributes() );
-
-		// Don't change image type if "src" is missing (a broken image), unless there's "uploadId" set.
-		// This state may happen during image upload (before it finishes) and it should be possible to change type
-		// of the image in the meantime.
-		if ( !attributes.src && !attributes.uploadId ) {
-			return null;
-		}
-
-		return model.change( writer => {
-			// Get all markers that contain the old image element.
-			const markers = Array.from( model.markers )
-				.filter( marker => marker.getRange().containsItem( oldElement ) );
-
-			const newElement = imageUtils.insertImage( attributes, model.createSelection( oldElement, 'on' ), this._modelElementName );
-
-			if ( !newElement ) {
-				return null;
-			}
-
-			const newElementRange = writer.createRangeOn( newElement );
-
-			// Expand the previously intersecting markers' ranges to include the new image element.
-			for ( const marker of markers ) {
-				const markerRange = marker.getRange();
-
-				// Join the survived part of the old marker range with the new element range
-				// (loosely because there could be some new paragraph or the existing one might got split).
-				const range = markerRange.root.rootName != '$graveyard' ?
-					markerRange.getJoined( newElementRange, true ) : newElementRange;
-
-				writer.updateMarker( marker, { range } );
-			}
-
-			return {
-				oldElement,
-				newElement
-			};
-		} );
-	}
+    /**
+     * @inheritDoc
+     *
+     * @param modelElementName Model element name the command converts to.
+     */
+    constructor(editor, modelElementName) {
+        super(editor);
+        this._modelElementName = modelElementName;
+    }
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const editor = this.editor;
+        const imageUtils = editor.plugins.get('ImageUtils');
+        const element = imageUtils.getClosestSelectedImageElement(this.editor.model.document.selection);
+        if (this._modelElementName === 'imageBlock') {
+            this.isEnabled = imageUtils.isInlineImage(element);
+        }
+        else {
+            this.isEnabled = imageUtils.isBlockImage(element);
+        }
+    }
+    /**
+     * Executes the command and changes the type of a selected image.
+     *
+     * @fires execute
+     * @returns An object containing references to old and new model image elements
+     * (for before and after the change) so external integrations can hook into the decorated
+     * `execute` event and handle this change. `null` if the type change failed.
+     */
+    execute() {
+        const editor = this.editor;
+        const model = this.editor.model;
+        const imageUtils = editor.plugins.get('ImageUtils');
+        const oldElement = imageUtils.getClosestSelectedImageElement(model.document.selection);
+        const attributes = Object.fromEntries(oldElement.getAttributes());
+        // Don't change image type if "src" is missing (a broken image), unless there's "uploadId" set.
+        // This state may happen during image upload (before it finishes) and it should be possible to change type
+        // of the image in the meantime.
+        if (!attributes.src && !attributes.uploadId) {
+            return null;
+        }
+        return model.change(writer => {
+            // Get all markers that contain the old image element.
+            const markers = Array.from(model.markers)
+                .filter(marker => marker.getRange().containsItem(oldElement));
+            const newElement = imageUtils.insertImage(attributes, model.createSelection(oldElement, 'on'), this._modelElementName);
+            if (!newElement) {
+                return null;
+            }
+            const newElementRange = writer.createRangeOn(newElement);
+            // Expand the previously intersecting markers' ranges to include the new image element.
+            for (const marker of markers) {
+                const markerRange = marker.getRange();
+                // Join the survived part of the old marker range with the new element range
+                // (loosely because there could be some new paragraph or the existing one might got split).
+                const range = markerRange.root.rootName != '$graveyard' ?
+                    markerRange.getJoined(newElementRange, true) : newElementRange;
+                writer.updateMarker(marker, { range });
+            }
+            return {
+                oldElement,
+                newElement
+            };
+        });
+    }
 }

package/src/image/insertimagecommand.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @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, type Editor } from 'ckeditor5/src/core';
+import { type ArrayOrItem } from 'ckeditor5/src/utils';
+import '../imageconfig';
+/**
+ * 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: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * 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: {
+        source: ArrayOrItem<string | Record<string, unknown>>;
+    }): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        insertImage: InsertImageCommand;
+    }
+}

package/src/image/insertimagecommand.js

@@ -2,14 +2,12 @@
  * @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';
-import { logWarning, toArray } from 'ckeditor5/src/utils';
-
 /**
  * @module image/image/insertimagecommand
  */
-
+import { Command } from 'ckeditor5/src/core';
+import { logWarning, toArray } from 'ckeditor5/src/utils';
+import '../imageconfig';
 /**
  * Insert image command.
  *
@@ -20,108 +18,104 @@ import { logWarning, toArray } from 'ckeditor5/src/utils';
  * (according to the {@link module:widget/utils~findOptimalInsertionRange} algorithm),
  * execute the command and specify the image source:
  *
- *		editor.execute( 'insertImage', { source: 'http://url.to.the/image' } );
+ * ```ts
+ * editor.execute( 'insertImage', { source: 'http://url.to.the/image' } );
+ * ```
  *
  * It is also possible to insert multiple images at once:
  *
- *		editor.execute( 'insertImage', {
- *			source:  [
- *				'path/to/image.jpg',
- *				'path/to/other-image.jpg'
- *			]
- *		} );
+ * ```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:
  *
- *		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' }
- *			]
- *		} );
- *
- * @extends module:core/command~Command
+ * ```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/imageinsert~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/imageinsert~ImageInsertConfig#type} to learn more.
-				 *
-				 * @error image-inline-plugin-required
-				 */
-				logWarning( 'image-inline-plugin-required' );
-			}
-		}
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	refresh() {
-		this.isEnabled = this.editor.plugins.get( 'ImageUtils' ).isImageAllowed();
-	}
-
-	/**
-	 * Executes the command.
-	 *
-	 * @fires execute
-	 * @param {Object} options Options for the executed command.
-	 * @param {String|Array.<String>|Array.<Object>} 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 } );
-			}
-		} );
-	}
+    /**
+     * @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

@@ -0,0 +1,39 @@
+/**
+ * @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;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        replaceImageSource: ReplaceImageSourceCommand;
+    }
+}

package/src/image/replaceimagesourcecommand.js

@@ -2,48 +2,43 @@
  * @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:
  *
- *		editor.execute( 'replaceImageSource', { source: 'http://url.to.the/image' } );
- *
- * @extends module:core/command~Command
+ * ```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 {Object} options Options for the executed command.
-	 * @param {String} [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 );
-		} );
-	}
+    /**
+     * @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);
+        });
+    }
 }

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

@@ -0,0 +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>;