@ckeditor/ckeditor5-image 27.1.0 → 29.2.0

package/src/image/converters.js

@@ -8,7 +8,6 @@
  */
 
 import { first } from 'ckeditor5/src/utils';
-import { getViewImgFromWidget } from './utils';
 
 /**
  * Returns a function that converts the image view representation:
@@ -17,14 +16,16 @@ import { getViewImgFromWidget } from './utils';
  *
  * to the model representation:
  *
- *		<image src="..." alt="..."></image>
+ *		<imageBlock src="..." alt="..."></imageBlock>
  *
  * The entire content of the `<figure>` element except the first `<img>` is being converted as children
- * of the `<image>` model element.
+ * of the `<imageBlock>` model element.
  *
+ * @protected
+ * @param {module:image/imageutils~ImageUtils} imageUtils
  * @returns {Function}
  */
-export function viewFigureToModel() {
+export function upcastImageFigure( imageUtils ) {
 	return dispatcher => {
 		dispatcher.on( 'element:figure', converter );
 	};
@@ -36,7 +37,7 @@ export function viewFigureToModel() {
 		}
 
 		// Find an image element inside the figure element.
-		const viewImage = getViewImgFromWidget( data.viewItem );
+		const viewImage = imageUtils.findViewImgElement( data.viewItem );
 
 		// Do not convert if image element is absent, is missing src attribute or was already converted.
 		if ( !viewImage || !viewImage.hasAttribute( 'src' ) || !conversionApi.consumable.test( viewImage, { name: true } ) ) {
@@ -61,14 +62,116 @@ export function viewFigureToModel() {
 	}
 }
 
+/**
+ * Returns a function that converts the image view representation:
+ *
+ *		<picture><source ... /><source ... />...<img ... /></picture>
+ *
+ * to the model representation as the `sources` attribute:
+ *
+ *		<image[Block|Inline] ... sources="..."></image[Block|Inline]>
+ *
+ * @protected
+ * @param {module:image/imageutils~ImageUtils} imageUtils
+ * @returns {Function}
+ */
+export function upcastPicture( imageUtils ) {
+	const sourceAttributeNames = [ 'srcset', 'media', 'type' ];
+
+	return dispatcher => {
+		dispatcher.on( 'element:picture', converter );
+	};
+
+	function converter( evt, data, conversionApi ) {
+		const pictureViewElement = data.viewItem;
+
+		// Do not convert <picture> if already consumed.
+		if ( !conversionApi.consumable.test( pictureViewElement, { name: true } ) ) {
+			return;
+		}
+
+		const sources = new Map();
+
+		// Collect all <source /> elements attribute values.
+		for ( const childSourceElement of pictureViewElement.getChildren() ) {
+			if ( childSourceElement.is( 'element', 'source' ) ) {
+				const attributes = {};
+
+				for ( const name of sourceAttributeNames ) {
+					if ( childSourceElement.hasAttribute( name ) ) {
+						// Don't collect <source /> attribute if already consumed somewhere else.
+						if ( conversionApi.consumable.test( childSourceElement, { attributes: name } ) ) {
+							attributes[ name ] = childSourceElement.getAttribute( name );
+						}
+					}
+				}
+
+				if ( Object.keys( attributes ).length ) {
+					sources.set( childSourceElement, attributes );
+				}
+			}
+		}
+
+		const imgViewElement = imageUtils.findViewImgElement( pictureViewElement );
+
+		// Don't convert when a picture has no <img/> inside (it is broken).
+		if ( !imgViewElement ) {
+			return;
+		}
+
+		let modelImage = data.modelCursor.parent;
+
+		// - In case of an inline image (cursor parent in a <paragraph>), the <img/> must be converted right away
+		// because no converter handled it yet and otherwise there would be no model element to set the sources attribute on.
+		// - In case of a block image, the <figure class="image"> converter (in ImageBlockEditing) converts the
+		// <img/> right away on its own and the modelCursor is already inside an imageBlock and there's nothing special
+		// to do here.
+		if ( !modelImage.is( 'element', 'imageBlock' ) ) {
+			const conversionResult = conversionApi.convertItem( imgViewElement, data.modelCursor );
+
+			// Set image range as conversion result.
+			data.modelRange = conversionResult.modelRange;
+
+			// Continue conversion where image conversion ends.
+			data.modelCursor = conversionResult.modelCursor;
+
+			modelImage = first( conversionResult.modelRange.getItems() );
+
+			// It could be that the <img/> was broken (e.g. missing "src"). There's no point in converting
+			// <picture> any further around a broken <img/>.
+			if ( !modelImage ) {
+				return;
+			}
+		}
+
+		conversionApi.consumable.consume( pictureViewElement, { name: true } );
+
+		// Consume only these <source/> attributes that were actually collected and will be passed on
+		// to the image model element.
+		for ( const [ sourceElement, attributes ] of sources ) {
+			conversionApi.consumable.consume( sourceElement, { attributes: Object.keys( attributes ) } );
+		}
+
+		if ( sources.size ) {
+			conversionApi.writer.setAttribute( 'sources', Array.from( sources.values() ), modelImage );
+		}
+
+		// Convert rest of the <picture> children as an image children. Other converters may want to consume them.
+		conversionApi.convertChildren( pictureViewElement, modelImage );
+	}
+}
+
 /**
  * Converter used to convert the `srcset` model image attribute to the `srcset`, `sizes` and `width` attributes in the view.
  *
+ * @protected
+ * @param {module:image/imageutils~ImageUtils} imageUtils
+ * @param {'imageBlock'|'imageInline'} imageType The type of the image.
  * @returns {Function}
  */
-export function srcsetAttributeConverter() {
+export function downcastSrcsetAttribute( imageUtils, imageType ) {
 	return dispatcher => {
-		dispatcher.on( 'attribute:srcset:image', converter );
+		dispatcher.on( `attribute:srcset:${ imageType }`, converter );
 	};
 
 	function converter( evt, data, conversionApi ) {
@@ -77,8 +180,8 @@ export function srcsetAttributeConverter() {
 		}
 
 		const writer = conversionApi.writer;
-		const figure = conversionApi.mapper.toViewElement( data.item );
-		const img = getViewImgFromWidget( figure );
+		const element = conversionApi.mapper.toViewElement( data.item );
+		const img = imageUtils.findViewImgElement( element );
 
 		if ( data.attributeNewValue === null ) {
 			const srcset = data.attributeOldValue;
@@ -107,9 +210,84 @@ export function srcsetAttributeConverter() {
 	}
 }
 
-export function modelToViewAttributeConverter( attributeKey ) {
+/**
+ * Converts the `source` model attribute to the `<picture><source /><source />...<img /></picture>`
+ * view structure.
+ *
+ * @protected
+ * @param {module:image/imageutils~ImageUtils} imageUtils
+ * @returns {Function}
+ */
+export function downcastSourcesAttribute( imageUtils ) {
+	return dispatcher => {
+		dispatcher.on( 'attribute:sources:imageBlock', converter );
+		dispatcher.on( 'attribute:sources:imageInline', converter );
+	};
+
+	function converter( evt, data, conversionApi ) {
+		if ( !conversionApi.consumable.consume( data.item, evt.name ) ) {
+			return;
+		}
+
+		const viewWriter = conversionApi.writer;
+		const element = conversionApi.mapper.toViewElement( data.item );
+		const imgElement = imageUtils.findViewImgElement( element );
+
+		if ( data.attributeNewValue && data.attributeNewValue.length ) {
+			// Make sure <picture> does not break attribute elements, for instance <a> in linked images.
+			const pictureElement = viewWriter.createContainerElement( 'picture', {}, { isAllowedInsideAttributeElement: true } );
+
+			for ( const sourceAttributes of data.attributeNewValue ) {
+				const sourceElement = viewWriter.createEmptyElement( 'source', sourceAttributes );
+
+				viewWriter.insert( viewWriter.createPositionAt( pictureElement, 'end' ), sourceElement );
+			}
+
+			// Collect all wrapping attribute elements.
+			const attributeElements = [];
+			let viewElement = imgElement.parent;
+
+			while ( viewElement && viewElement.is( 'attributeElement' ) ) {
+				const parentElement = viewElement.parent;
+
+				viewWriter.unwrap( viewWriter.createRangeOn( imgElement ), viewElement );
+
+				attributeElements.unshift( viewElement );
+				viewElement = parentElement;
+			}
+
+			// Insert the picture and move img into it.
+			viewWriter.insert( viewWriter.createPositionBefore( imgElement ), pictureElement );
+			viewWriter.move( viewWriter.createRangeOn( imgElement ), viewWriter.createPositionAt( pictureElement, 'end' ) );
+
+			// Apply collected attribute elements over the new picture element.
+			for ( const attributeElement of attributeElements ) {
+				viewWriter.wrap( viewWriter.createRangeOn( pictureElement ), attributeElement );
+			}
+		}
+		// Both setting "sources" to an empty array and removing the attribute should unwrap the <img />.
+		// Unwrap once if the latter followed the former, though.
+		else if ( imgElement.parent.is( 'element', 'picture' ) ) {
+			const pictureElement = imgElement.parent;
+
+			viewWriter.move( viewWriter.createRangeOn( imgElement ), viewWriter.createPositionBefore( pictureElement ) );
+			viewWriter.remove( pictureElement );
+		}
+	}
+}
+
+/**
+ * Converter used to convert a given image attribute from the model to the view.
+ *
+ * @protected
+ * @param {module:image/imageutils~ImageUtils} imageUtils
+ * @param {'imageBlock'|'imageInline'} imageType The type of the image.
+ * @param {String} attributeKey The name of the attribute to convert.
+ * @returns {Function}
+ */
+export function downcastImageAttribute( imageUtils, imageType, attributeKey ) {
 	return dispatcher => {
-		dispatcher.on( `attribute:${ attributeKey }:image`, converter );
+		dispatcher.on( `attribute:${ attributeKey }:${ imageType }`, converter );
 	};
 
 	function converter( evt, data, conversionApi ) {
@@ -118,9 +296,10 @@ export function modelToViewAttributeConverter( attributeKey ) {
 		}
 
 		const viewWriter = conversionApi.writer;
-		const figure = conversionApi.mapper.toViewElement( data.item );
-		const img = getViewImgFromWidget( figure );
+		const element = conversionApi.mapper.toViewElement( data.item );
+		const img = imageUtils.findViewImgElement( element );
 
 		viewWriter.setAttribute( data.attributeKey, data.attributeNewValue || '', img );
 	}
 }
+

package/src/image/imageblockediting.js

@@ -0,0 +1,179 @@
+/**
+ * @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/imageblockediting
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+import { ClipboardPipeline } from 'ckeditor5/src/clipboard';
+import { UpcastWriter } from 'ckeditor5/src/engine';
+
+import {
+	downcastImageAttribute,
+	downcastSrcsetAttribute,
+	upcastImageFigure
+} from './converters';
+
+import ImageEditing from './imageediting';
+import ImageTypeCommand from './imagetypecommand';
+import ImageUtils from '../imageutils';
+import {
+	getImgViewElementMatcher,
+	createImageViewElement,
+	determineImageTypeForInsertionAtSelection
+} from '../image/utils';
+
+/**
+ * The image block plugin.
+ *
+ * It registers:
+ *
+ * * `<imageBlock>` as a block element in the document schema, and allows `alt`, `src` and `srcset` attributes.
+ * * converters for editing and data pipelines.,
+ * * {@link module:image/image/imagetypecommand~ImageTypeCommand `'imageTypeBlock'`} command that converts inline images into
+ * block images.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class ImageBlockEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ ImageEditing, ImageUtils, ClipboardPipeline ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'ImageBlockEditing';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		const editor = this.editor;
+		const schema = editor.model.schema;
+
+		// Converters 'alt' and 'srcset' are added in 'ImageEditing' plugin.
+		schema.register( 'imageBlock', {
+			isObject: true,
+			isBlock: true,
+			allowWhere: '$block',
+			allowAttributes: [ 'alt', 'src', 'srcset' ]
+		} );
+
+		this._setupConversion();
+
+		if ( editor.plugins.has( 'ImageInlineEditing' ) ) {
+			editor.commands.add( 'imageTypeBlock', new ImageTypeCommand( this.editor, 'imageBlock' ) );
+
+			this._setupClipboardIntegration();
+		}
+	}
+
+	/**
+	 * Configures conversion pipelines to support upcasting and downcasting
+	 * block images (block 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: 'imageBlock',
+				view: ( modelElement, { writer } ) => createImageViewElement( writer, 'imageBlock' )
+			} );
+
+		conversion.for( 'editingDowncast' )
+			.elementToElement( {
+				model: 'imageBlock',
+				view: ( modelElement, { writer } ) => imageUtils.toImageWidget(
+					createImageViewElement( writer, 'imageBlock' ), writer, t( 'image widget' )
+				)
+			} );
+
+		conversion.for( 'downcast' )
+			.add( downcastImageAttribute( imageUtils, 'imageBlock', 'src' ) )
+			.add( downcastImageAttribute( imageUtils, 'imageBlock', 'alt' ) )
+			.add( downcastSrcsetAttribute( imageUtils, 'imageBlock' ) );
+
+		// More image related upcasts are in 'ImageEditing' plugin.
+		conversion.for( 'upcast' )
+			.elementToElement( {
+				view: getImgViewElementMatcher( editor, 'imageBlock' ),
+				model: ( viewImage, { writer } ) => writer.createElement( 'imageBlock', { src: viewImage.getAttribute( 'src' ) } )
+			} )
+			.add( upcastImageFigure( imageUtils ) );
+	}
+
+	/**
+	 * Integrates the plugin with the clipboard pipeline.
+	 *
+	 * Idea is that the feature should recognize the user's intent when an **inline** image is
+	 * pasted or dropped. If such an image is pasted/dropped:
+	 *
+	 * * into an empty block (e.g. an empty paragraph),
+	 * * on another object (e.g. some block widget).
+	 *
+	 * it gets converted into a block image on the fly. We assume this is the user's intent
+	 * if they decided to put their image there.
+	 *
+	 * See the `ImageInlineEditing` 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 <img> 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.isInlineImageView ) ) {
+				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 inline images into block images only when the currently selected block is empty
+			// (e.g. an empty paragraph) or some object is selected (to replace it).
+			if ( determineImageTypeForInsertionAtSelection( model.schema, selection ) === 'imageBlock' ) {
+				const writer = new UpcastWriter( editingView.document );
+
+				// Wrap <img ... /> -> <figure class="image"><img .../></figure>
+				const blockViewImages = docFragmentChildren.map(
+					inlineViewImage => writer.createElement( 'figure', { class: 'image' }, inlineViewImage )
+				);
+
+				data.content = writer.createDocumentFragment( blockViewImages );
+			}
+		} );
+	}
+}

package/src/image/imageediting.js

@@ -9,30 +9,26 @@
 
 import { Plugin } from 'ckeditor5/src/core';
 import ImageLoadObserver from './imageloadobserver';
-
-import {
-	viewFigureToModel,
-	modelToViewAttributeConverter,
-	srcsetAttributeConverter
-} from './converters';
-
-import { toImageWidget } from './utils';
-
 import InsertImageCommand from './insertimagecommand';
+import ImageUtils from '../imageutils';
 
 /**
- * The image engine plugin.
+ * The image engine plugin. This module loads common code shared between
+ * {@link module:image/image/imageinlineediting~ImageInlineEditing} and
+ * {@link module:image/image/imageblockediting~ImageBlockEditing} plugins.
  *
- * It registers:
- *
- * * `<image>` as a block element in the document schema, and allows `alt`, `src` and `srcset` attributes.
- * * converters for editing and data pipelines.
- * * `'insertImage'` command.
- * * `'imageInsert'` command as an alias for `insertImage` command.
+ * This plugin registers the {@link module:image/image/insertimagecommand~InsertImageCommand 'insertImage'} command.
  *
  * @extends module:core/plugin~Plugin
  */
 export default class ImageEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ ImageUtils ];
+	}
+
 	/**
 	 * @inheritDoc
 	 */
@@ -45,46 +41,12 @@ export default class ImageEditing extends Plugin {
 	 */
 	init() {
 		const editor = this.editor;
-		const schema = editor.model.schema;
-		const t = editor.t;
 		const conversion = editor.conversion;
 
 		// See https://github.com/ckeditor/ckeditor5-image/issues/142.
 		editor.editing.view.addObserver( ImageLoadObserver );
 
-		// Configure schema.
-		schema.register( 'image', {
-			isObject: true,
-			isBlock: true,
-			allowWhere: '$block',
-			allowAttributes: [ 'alt', 'src', 'srcset' ]
-		} );
-
-		conversion.for( 'dataDowncast' ).elementToElement( {
-			model: 'image',
-			view: ( modelElement, { writer } ) => createImageViewElement( writer )
-		} );
-
-		conversion.for( 'editingDowncast' ).elementToElement( {
-			model: 'image',
-			view: ( modelElement, { writer } ) => toImageWidget( createImageViewElement( writer ), writer, t( 'image widget' ) )
-		} );
-
-		conversion.for( 'downcast' )
-			.add( modelToViewAttributeConverter( 'src' ) )
-			.add( modelToViewAttributeConverter( 'alt' ) )
-			.add( srcsetAttributeConverter() );
-
 		conversion.for( 'upcast' )
-			.elementToElement( {
-				view: {
-					name: 'img',
-					attributes: {
-						src: true
-					}
-				},
-				model: ( viewImage, { writer } ) => writer.createElement( 'image', { src: viewImage.getAttribute( 'src' ) } )
-			} )
 			.attributeToAttribute( {
 				view: {
 					name: 'img',
@@ -111,8 +73,7 @@ export default class ImageEditing extends Plugin {
 						return value;
 					}
 				}
-			} )
-			.add( viewFigureToModel() );
+			} );
 
 		const insertImageCommand = new InsertImageCommand( editor );
 
@@ -121,21 +82,3 @@ export default class ImageEditing extends Plugin {
 		editor.commands.add( 'imageInsert', insertImageCommand );
 	}
 }
-
-// Creates a view element representing the image.
-//
-//		<figure class="image"><img></img></figure>
-//
-// Note that `alt` and `src` attributes are converted separately, so they are not included.
-//
-// @private
-// @param {module:engine/view/downcastwriter~DowncastWriter} writer
-// @returns {module:engine/view/containerelement~ContainerElement}
-export function createImageViewElement( writer ) {
-	const emptyElement = writer.createEmptyElement( 'img' );
-	const figure = writer.createContainerElement( 'figure', { class: 'image' } );
-
-	writer.insert( writer.createPositionAt( figure, 0 ), emptyElement );
-
-	return figure;
-}