@ckeditor/ckeditor5-image 27.1.0 → 29.2.0

package/src/image/imageinlineediting.js

@@ -0,0 +1,204 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module image/image/imageinlineediting
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+import { ClipboardPipeline } from 'ckeditor5/src/clipboard';
+import { UpcastWriter } from 'ckeditor5/src/engine';
+
+import {
+	downcastImageAttribute,
+	downcastSrcsetAttribute
+} from './converters';
+
+import ImageEditing from './imageediting';
+import ImageTypeCommand from './imagetypecommand';
+import ImageUtils from '../imageutils';
+import {
+	getImgViewElementMatcher,
+	createImageViewElement,
+	determineImageTypeForInsertionAtSelection
+} from '../image/utils';
+
+/**
+ * The image inline plugin.
+ *
+ * It registers:
+ *
+ * * `<imageInline>` as an inline element in the document schema, and allows `alt`, `src` and `srcset` attributes.
+ * * converters for editing and data pipelines.
+ * * {@link module:image/image/imagetypecommand~ImageTypeCommand `'imageTypeInline'`} command that converts block images into
+ * inline images.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class ImageInlineEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ ImageEditing, ImageUtils, ClipboardPipeline ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'ImageInlineEditing';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		const editor = this.editor;
+		const schema = editor.model.schema;
+
+		// Converters 'alt' and 'srcset' are added in 'ImageEditing' plugin.
+		schema.register( 'imageInline', {
+			isObject: true,
+			isInline: true,
+			allowWhere: '$text',
+			allowAttributes: [ 'alt', 'src', 'srcset' ]
+		} );
+
+		// Disallow inline images in captions (for now). This is the best spot to do that because
+		// independent packages can introduce captions (ImageCaption, TableCaption, etc.) so better this
+		// be future-proof.
+		schema.addChildCheck( ( context, childDefinition ) => {
+			if ( context.endsWith( 'caption' ) && childDefinition.name === 'imageInline' ) {
+				return false;
+			}
+		} );
+
+		this._setupConversion();
+
+		if ( editor.plugins.has( 'ImageBlockEditing' ) ) {
+			editor.commands.add( 'imageTypeInline', new ImageTypeCommand( this.editor, 'imageInline' ) );
+
+			this._setupClipboardIntegration();
+		}
+	}
+
+	/**
+	 * Configures conversion pipelines to support upcasting and downcasting
+	 * inline images (inline image widgets) and their attributes.
+	 *
+	 * @private
+	 */
+	_setupConversion() {
+		const editor = this.editor;
+		const t = editor.t;
+		const conversion = editor.conversion;
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
+
+		conversion.for( 'dataDowncast' )
+			.elementToElement( {
+				model: 'imageInline',
+				view: ( modelElement, { writer } ) => writer.createEmptyElement( 'img' )
+			} );
+
+		conversion.for( 'editingDowncast' )
+			.elementToElement( {
+				model: 'imageInline',
+				view: ( modelElement, { writer } ) => imageUtils.toImageWidget(
+					createImageViewElement( writer, 'imageInline' ), writer, t( 'image widget' )
+				)
+			} );
+
+		conversion.for( 'downcast' )
+			.add( downcastImageAttribute( imageUtils, 'imageInline', 'src' ) )
+			.add( downcastImageAttribute( imageUtils, 'imageInline', 'alt' ) )
+			.add( downcastSrcsetAttribute( imageUtils, 'imageInline' ) );
+
+		// More image related upcasts are in 'ImageEditing' plugin.
+		conversion.for( 'upcast' )
+			.elementToElement( {
+				view: getImgViewElementMatcher( editor, 'imageInline' ),
+				model: ( viewImage, { writer } ) => writer.createElement( 'imageInline', { src: viewImage.getAttribute( 'src' ) } )
+			} );
+	}
+
+	/**
+	 * Integrates the plugin with the clipboard pipeline.
+	 *
+	 * Idea is that the feature should recognize the user's intent when an **block** image is
+	 * pasted or dropped. If such an image is pasted/dropped into a non-empty block
+	 * (e.g. a paragraph with some text) it gets converted into an inline image on the fly.
+	 *
+	 * We assume this is the user's intent if they decided to put their image there.
+	 *
+	 * **Note**: If a block image has a caption, it will not be converted to an inline image
+	 * to avoid the confusion. Captions are added on purpose and they should never be lost
+	 * in the clipboard pipeline.
+	 *
+	 * See the `ImageBlockEditing` for the similar integration that works in the opposite direction.
+	 *
+	 * @private
+	 */
+	_setupClipboardIntegration() {
+		const editor = this.editor;
+		const model = editor.model;
+		const editingView = editor.editing.view;
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
+
+		this.listenTo( editor.plugins.get( 'ClipboardPipeline' ), 'inputTransformation', ( evt, data ) => {
+			const docFragmentChildren = Array.from( data.content.getChildren() );
+			let modelRange;
+
+			// Make sure only <figure class="image"></figure> elements are dropped or pasted. Otherwise, if there some other HTML
+			// mixed up, this should be handled as a regular paste.
+			if ( !docFragmentChildren.every( imageUtils.isBlockImageView ) ) {
+				return;
+			}
+
+			// When drag and dropping, data.targetRanges specifies where to drop because
+			// this is usually a different place than the current model selection (the user
+			// uses a drop marker to specify the drop location).
+			if ( data.targetRanges ) {
+				modelRange = editor.editing.mapper.toModelRange( data.targetRanges[ 0 ] );
+			}
+			// Pasting, however, always occurs at the current model selection.
+			else {
+				modelRange = model.document.selection.getFirstRange();
+			}
+
+			const selection = model.createSelection( modelRange );
+
+			// Convert block images into inline images only when pasting or dropping into non-empty blocks
+			// and when the block is not an object (e.g. pasting to replace another widget).
+			if ( determineImageTypeForInsertionAtSelection( model.schema, selection ) === 'imageInline' ) {
+				const writer = new UpcastWriter( editingView.document );
+
+				// Unwrap <figure class="image"><img .../></figure> -> <img ... />
+				// but <figure class="image"><img .../><figcaption>...</figcaption></figure> -> stays the same
+				const inlineViewImages = docFragmentChildren.map( blockViewImage => {
+					// If there's just one child, it can be either <img /> or <a><img></a>.
+					// If there are other children than <img>, this means that the block image
+					// has a caption or some other features and this kind of image should be
+					// pasted/dropped without modifications.
+					if ( blockViewImage.childCount === 1 ) {
+						// Pass the attributes which are present only in the <figure> to the <img>
+						// (e.g. the style="width:10%" attribute applied by the ImageResize plugin).
+						Array.from( blockViewImage.getAttributes() )
+							.forEach( attribute => writer.setAttribute(
+								...attribute,
+								imageUtils.findViewImgElement( blockViewImage )
+							) );
+
+						return blockViewImage.getChild( 0 );
+					} else {
+						return blockViewImage;
+					}
+				} );
+
+				data.content = writer.createDocumentFragment( inlineViewImages );
+			}
+		} );
+	}
+}

package/src/image/imagetypecommand.js

@@ -0,0 +1,105 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. 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
+			};
+		} );
+	}
+}

package/src/image/insertimagecommand.js

@@ -4,9 +4,7 @@
  */
 
 import { Command } from 'ckeditor5/src/core';
-import { toArray } from 'ckeditor5/src/utils';
-
-import { insertImage, isImageAllowed } from './utils';
+import { logWarning, toArray } from 'ckeditor5/src/utils';
 
 /**
  * @module image/image/insertimagecommand
@@ -19,7 +17,7 @@ import { insertImage, isImageAllowed } from './utils';
  * 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~findOptimalInsertionPosition} algorithm),
+ * (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' } );
@@ -33,14 +31,56 @@ import { insertImage, isImageAllowed } from './utils';
  *			]
  *		} );
  *
+ * 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
  */
 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 = isImageAllowed( this.editor.model );
+		this.isEnabled = this.editor.plugins.get( 'ImageUtils' ).isImageAllowed();
 	}
 
 	/**
@@ -48,13 +88,40 @@ export default class InsertImageCommand extends Command {
 	 *
 	 * @fires execute
 	 * @param {Object} options Options for the executed command.
-	 * @param {String|Array.<String>} options.source The image source or an array of image sources to insert.
+	 * @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 model = this.editor.model;
+		const sourceDefinitions = toArray( options.source );
+		const selection = this.editor.model.document.selection;
+		const imageUtils = this.editor.plugins.get( 'ImageUtils' );
 
-		for ( const src of toArray( options.source ) ) {
-			insertImage( model, { src } );
-		}
+		// 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/ui/utils.js

@@ -8,7 +8,6 @@
  */
 
 import { BalloonPanelView } from 'ckeditor5/src/ui';
-import { getSelectedImageWidget } from '../utils';
 
 /**
  * A helper utility that positions the
@@ -20,7 +19,7 @@ import { getSelectedImageWidget } from '../utils';
 export function repositionContextualBalloon( editor ) {
 	const balloon = editor.plugins.get( 'ContextualBalloon' );
 
-	if ( getSelectedImageWidget( editor.editing.view.document.selection ) ) {
+	if ( editor.plugins.get( 'ImageUtils' ).getClosestSelectedImageWidget( editor.editing.view.document.selection ) ) {
 		const position = getBalloonPositionData( editor );
 
 		balloon.updatePosition( position );
@@ -38,9 +37,10 @@ export function repositionContextualBalloon( editor ) {
 export function getBalloonPositionData( editor ) {
 	const editingView = editor.editing.view;
 	const defaultPositions = BalloonPanelView.defaultPositions;
+	const imageUtils = editor.plugins.get( 'ImageUtils' );
 
 	return {
-		target: editingView.domConverter.viewToDom( editingView.document.selection.getSelectedElement() ),
+		target: editingView.domConverter.viewToDom( imageUtils.getClosestSelectedImageWidget( editingView.document.selection ) ),
 		positions: [
 			defaultPositions.northArrowSouth,
 			defaultPositions.northArrowSouthWest,