@ckeditor/ckeditor5-image 27.1.0 → 29.2.0

package/src/imagecaption/toggleimagecaptioncommand.js

@@ -0,0 +1,165 @@
+/**
+ * @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/imagecaption/toggleimagecaptioncommand
+ */
+
+import { Command } from 'ckeditor5/src/core';
+
+import ImageBlockEditing from '../image/imageblockediting';
+import { getCaptionFromImageModelElement, getCaptionFromModelSelection } from './utils';
+
+/**
+ * The toggle image caption command.
+ *
+ * This command is registered by {@link module:image/imagecaption/imagecaptionediting~ImageCaptionEditing} as the
+ * `'toggleImageCaption'` editor command.
+ *
+ * Executing this command:
+ *
+ * * either adds or removes the image caption of a selected image (depending on whether the caption is present or not),
+ * * removes the image caption if the selection is anchored in one.
+ *
+ *		// Toggle the presence of the caption.
+ *		editor.execute( 'toggleImageCaption' );
+ *
+ * **Note**: Upon executing this command, the selection will be set on the image if previously anchored in the caption element.
+ *
+ * **Note**: You can move the selection to the caption right away as it shows up upon executing this command by using
+ * the `focusCaptionOnShow` option:
+ *
+ *		editor.execute( 'toggleImageCaption', { focusCaptionOnShow: true } );
+ *
+ * @extends module:core/command~Command
+ */
+export default class ToggleImageCaptionCommand extends Command {
+	/**
+	 * @inheritDoc
+	 */
+	refresh() {
+		const editor = this.editor;
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
+
+		// Only block images can get captions.
+		if ( !editor.plugins.has( ImageBlockEditing ) ) {
+			this.isEnabled = false;
+			this.value = false;
+
+			return;
+		}
+
+		const selection = editor.model.document.selection;
+		const selectedElement = selection.getSelectedElement();
+
+		if ( !selectedElement ) {
+			const ancestorCaptionElement = getCaptionFromModelSelection( imageUtils, selection );
+
+			this.isEnabled = !!ancestorCaptionElement;
+			this.value = !!ancestorCaptionElement;
+
+			return;
+		}
+
+		// Block images support captions by default but the command should also be enabled for inline
+		// images because toggling the caption when one is selected should convert it into a block image.
+		this.isEnabled = this.editor.plugins.get( 'ImageUtils' ).isImage( selectedElement );
+
+		if ( !this.isEnabled ) {
+			this.value = false;
+		} else {
+			this.value = !!getCaptionFromImageModelElement( selectedElement );
+		}
+	}
+
+	/**
+	 * Executes the command.
+	 *
+	 *		editor.execute( 'toggleImageCaption' );
+	 *
+	 * @param {Object} [options] Options for the executed command.
+	 * @param {String} [options.focusCaptionOnShow] When true and the caption shows up, the selection will be moved into it straight away.
+	 * @fires execute
+	 */
+	execute( options = {} ) {
+		const { focusCaptionOnShow } = options;
+
+		this.editor.model.change( writer => {
+			if ( this.value ) {
+				this._hideImageCaption( writer );
+			} else {
+				this._showImageCaption( writer, focusCaptionOnShow );
+			}
+		} );
+	}
+
+	/**
+	 * Shows the caption of the `<imageBlock>` or `<imageInline>`. Also:
+	 *
+	 * * it converts `<imageInline>` to `<imageBlock>` to show the caption,
+	 * * it attempts to restore the caption content from the `ImageCaptionEditing` caption registry,
+	 * * it moves the selection to the caption right away, it the `focusCaptionOnShow` option was set.
+	 *
+	 * @private
+	 * @param {module:engine/model/writer~Writer} writer
+	 */
+	_showImageCaption( writer, focusCaptionOnShow ) {
+		const model = this.editor.model;
+		const selection = model.document.selection;
+		const imageCaptionEditing = this.editor.plugins.get( 'ImageCaptionEditing' );
+
+		let selectedImage = selection.getSelectedElement();
+
+		const savedCaption = imageCaptionEditing._getSavedCaption( selectedImage );
+
+		// Convert imageInline -> image first.
+		if ( this.editor.plugins.get( 'ImageUtils' ).isInlineImage( selectedImage ) ) {
+			this.editor.execute( 'imageTypeBlock' );
+
+			// Executing the command created a new model element. Let's pick it again.
+			selectedImage = selection.getSelectedElement();
+		}
+
+		// Try restoring the caption from the ImageCaptionEditing plugin storage.
+		const newCaptionElement = savedCaption || writer.createElement( 'caption' );
+
+		writer.append( newCaptionElement, selectedImage );
+
+		if ( focusCaptionOnShow ) {
+			writer.setSelection( newCaptionElement, 'in' );
+		}
+	}
+
+	/**
+	 * Hides the caption of a selected image (or an image caption the selection is anchored to).
+	 *
+	 * The content of the caption is stored in the `ImageCaptionEditing` caption registry to make this
+	 * a reversible action.
+	 *
+	 * @private
+	 * @param {module:engine/model/writer~Writer} writer
+	 */
+	_hideImageCaption( writer ) {
+		const editor = this.editor;
+		const selection = editor.model.document.selection;
+		const imageCaptionEditing = editor.plugins.get( 'ImageCaptionEditing' );
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
+		let selectedImage = selection.getSelectedElement();
+		let captionElement;
+
+		if ( selectedImage ) {
+			captionElement = getCaptionFromImageModelElement( selectedImage );
+		} else {
+			captionElement = getCaptionFromModelSelection( imageUtils, selection );
+			selectedImage = captionElement.parent;
+		}
+
+		// Store the caption content so it can be restored quickly if the user changes their mind even if they toggle image<->imageInline.
+		imageCaptionEditing._saveCaption( selectedImage, captionElement );
+
+		writer.setSelection( selectedImage, 'on' );
+		writer.remove( captionElement );
+	}
+}

package/src/imagecaption/utils.js

@@ -7,48 +7,13 @@
  * @module image/imagecaption/utils
  */
 
-import { enablePlaceholder } from 'ckeditor5/src/engine';
-import { toWidgetEditable } from 'ckeditor5/src/widget';
-
-/**
- * Returns a function that creates a caption editable element for the given {@link module:engine/view/document~Document}.
- *
- * @param {module:engine/view/view~View} view
- * @param {String} placeholderText The text to be displayed when the caption is empty.
- * @returns {Function}
- */
-export function captionElementCreator( view, placeholderText ) {
-	return writer => {
-		const editable = writer.createEditableElement( 'figcaption' );
-		writer.setCustomProperty( 'imageCaption', true, editable );
-
-		enablePlaceholder( {
-			view,
-			element: editable,
-			text: placeholderText
-		} );
-
-		return toWidgetEditable( editable, writer );
-	};
-}
-
-/**
- * Returns `true` if a given view element is the image caption editable.
- *
- * @param {module:engine/view/element~Element} viewElement
- * @returns {Boolean}
- */
-export function isCaption( viewElement ) {
-	return !!viewElement.getCustomProperty( 'imageCaption' );
-}
-
 /**
  * Returns the caption model element from a given image element. Returns `null` if no caption is found.
  *
  * @param {module:engine/model/element~Element} imageModelElement
  * @returns {module:engine/model/element~Element|null}
  */
-export function getCaptionFromImage( imageModelElement ) {
+export function getCaptionFromImageModelElement( imageModelElement ) {
 	for ( const node of imageModelElement.getChildren() ) {
 		if ( !!node && node.is( 'element', 'caption' ) ) {
 			return node;
@@ -58,19 +23,39 @@ export function getCaptionFromImage( imageModelElement ) {
 	return null;
 }
 
+/**
+ * Returns the caption model element for a model selection. Returns `null` if the selection has no caption element ancestor.
+ *
+ * @param {module:image/imageutils~ImageUtils} imageUtils
+ * @param {module:engine/model/selection~Selection} selection
+ * @returns {module:engine/model/element~Element|null}
+ */
+export function getCaptionFromModelSelection( imageUtils, selection ) {
+	const captionElement = selection.getFirstPosition().findAncestor( 'caption' );
+
+	if ( !captionElement ) {
+		return null;
+	}
+
+	if ( imageUtils.isBlockImage( captionElement.parent ) ) {
+		return captionElement;
+	}
+
+	return null;
+}
+
 /**
  * {@link module:engine/view/matcher~Matcher} pattern. Checks if a given element is a `<figcaption>` element that is placed
  * inside the image `<figure>` element.
  *
+ * @param {module:image/imageutils~ImageUtils} imageUtils
  * @param {module:engine/view/element~Element} element
  * @returns {Object|null} Returns the object accepted by {@link module:engine/view/matcher~Matcher} or `null` if the element
  * cannot be matched.
  */
-export function matchImageCaption( element ) {
-	const parent = element.parent;
-
+export function matchImageCaptionViewElement( imageUtils, element ) {
 	// Convert only captions for images.
-	if ( element.name == 'figcaption' && parent && parent.name == 'figure' && parent.hasClass( 'image' ) ) {
+	if ( element.name == 'figcaption' && imageUtils.isBlockImageView( element.parent ) ) {
 		return { name: true };
 	}
 

package/src/imagecaption.js

@@ -9,13 +9,14 @@
 
 import { Plugin } from 'ckeditor5/src/core';
 import ImageCaptionEditing from './imagecaption/imagecaptionediting';
+import ImageCaptionUI from './imagecaption/imagecaptionui';
 
 import '../theme/imagecaption.css';
 
 /**
  * The image caption plugin.
  *
- * For a detailed overview, check the {@glink features/image#image-captions image caption} documentation.
+ * For a detailed overview, check the {@glink features/images/images-captions image caption} documentation.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -24,7 +25,7 @@ export default class ImageCaption extends Plugin {
 	 * @inheritDoc
 	 */
 	static get requires() {
-		return [ ImageCaptionEditing ];
+		return [ ImageCaptionEditing, ImageCaptionUI ];
 	}
 
 	/**

package/src/imageinline.js

@@ -0,0 +1,46 @@
+/**
+ * @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/imageinline
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+import { Widget } from 'ckeditor5/src/widget';
+
+import ImageTextAlternative from './imagetextalternative';
+import ImageInlineEditing from './image/imageinlineediting';
+
+import '../theme/image.css';
+
+/**
+ * The image inline plugin.
+ *
+ * This is a "glue" plugin which loads the following plugins:
+ *
+ * * {@link module:image/image/imageinlineediting~ImageInlineEditing},
+ * * {@link module:image/imagetextalternative~ImageTextAlternative}.
+ *
+ * Usually, it is used in conjunction with other plugins from this package. See the {@glink api/image package page}
+ * for more information.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class ImageInline extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ ImageInlineEditing, Widget, ImageTextAlternative ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'ImageInline';
+	}
+}
+

package/src/imageinsert/imageinsertui.js

@@ -11,13 +11,11 @@ import { Plugin } from 'ckeditor5/src/core';
 import ImageInsertPanelView from './ui/imageinsertpanelview';
 import { prepareIntegrations } from './utils';
 
-import { isImage } from '../image/utils';
-
 /**
  * The image insert dropdown plugin.
  *
- * For a detailed overview, check the {@glink features/image-upload/image-upload Image upload feature}
- * and {@glink features/image#inserting-images-via-source-url Insert images via source URL} documentation.
+ * For a detailed overview, check the {@glink features/images/image-upload/image-upload Image upload feature}
+ * and {@glink features/images/image-upload/images-inserting#inserting-images-via-source-url Insert images via source URL} documentation.
  *
  * Adds the `'insertImage'` dropdown to the {@link module:ui/componentfactory~ComponentFactory UI component factory}
  * and also the `imageInsert` dropdown as an alias for backward compatibility.
@@ -92,6 +90,7 @@ export default class ImageInsertUI extends Plugin {
 		const insertButtonView = imageInsertView.insertButtonView;
 		const insertImageViaUrlForm = imageInsertView.getIntegration( 'insertImageViaUrl' );
 		const panelView = dropdownView.panelView;
+		const imageUtils = this.editor.plugins.get( 'ImageUtils' );
 
 		dropdownView.bind( 'isEnabled' ).to( command );
 
@@ -107,7 +106,7 @@ export default class ImageInsertUI extends Plugin {
 			if ( dropdownView.isOpen ) {
 				imageInsertView.focus();
 
-				if ( isImage( selectedElement ) ) {
+				if ( imageUtils.isImage( selectedElement ) ) {
 					imageInsertView.imageURLInputValue = selectedElement.getAttribute( 'src' );
 					insertButtonView.label = t( 'Update' );
 					insertImageViaUrlForm.label = t( 'Update image URL' );
@@ -137,7 +136,7 @@ export default class ImageInsertUI extends Plugin {
 		function onSubmit() {
 			const selectedElement = editor.model.document.selection.getSelectedElement();
 
-			if ( isImage( selectedElement ) ) {
+			if ( imageUtils.isImage( selectedElement ) ) {
 				editor.model.change( writer => {
 					writer.setAttribute( 'src', imageInsertView.imageURLInputValue, selectedElement );
 					writer.removeAttribute( 'srcset', selectedElement );

package/src/imageinsert.js

@@ -14,8 +14,8 @@ import ImageInsertUI from './imageinsert/imageinsertui';
 /**
  * The image insert plugin.
  *
- * For a detailed overview, check the {@glink features/image-upload/image-upload Image upload feature}
- * and {@glink features/image#inserting-images-via-source-url Insert images via source URL} documentation.
+ * For a detailed overview, check the {@glink features/images/image-upload/image-upload Image upload feature}
+ * and {@glink features/images/image-upload/images-inserting#inserting-images-via-source-url Insert images via source URL} documentation.
  *
  * This plugin does not do anything directly, but it loads a set of specific plugins
  * to enable image uploading or inserting via implemented integrations:
@@ -44,7 +44,6 @@ export default class ImageInsert extends Plugin {
 /**
  * The image insert configuration.
  *
- * @protected
  * @member {module:image/imageinsert~ImageInsertConfig} module:image/image~ImageConfig#insert
  */
 
@@ -64,7 +63,6 @@ export default class ImageInsert extends Plugin {
  *
  * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
  *
- * @protected
  * @interface module:image/imageinsert~ImageInsertConfig
  */
 
@@ -90,6 +88,20 @@ export default class ImageInsert extends Plugin {
  *			}
  *		};
  *
+ * @protected
  * @member {Array.<String>} module:image/imageinsert~ImageInsertConfig#integrations
  * @default [ 'insertImageViaUrl' ]
  */
+
+/**
+ * This options allows to override the image type used by the {@link module:image/image/insertimagecommand~InsertImageCommand} when the user
+ * inserts new images into the editor content. By default, this option is unset which means the editor will choose the optimal image type
+ * based on the context of the insertion (e.g. the current selection and availability of plugins)
+ *
+ * Available options are:
+ *
+ * * `'block'` – all images inserted into the editor will be block (requires the {@link module:image/imageblock~ImageBlock} plugin),
+ * * `'inline'` – all images inserted into the editor will be inline (requires the {@link module:image/imageinline~ImageInline} plugin).
+ *
+ * @member {'inline'|'block'|undefined} module:image/imageinsert~ImageInsertConfig#type
+ */

package/src/imageresize/imageresizebuttons.js

@@ -268,7 +268,7 @@ function getIsOnButtonCallback( value ) {
  * * If you configure the feature using the resize dropdown, this name will be used for a list item in the dropdown.
  * @property {String} value The value of the resize option without the unit
  * ({@link module:image/image~ImageConfig#resizeUnit configured separately}). `null` resets an image to its original size.
- * @property {String} [resizeOptions.icon] An icon used by an individual resize button (see the `name` property to learn more).
+ * @property {String} [icon] An icon used by an individual resize button (see the `name` property to learn more).
  * Available icons are: `'small'`, `'medium'`, `'large'`, `'original'`.
  * @property {String} [label] An option label displayed in the dropdown or, if the feature is configured using
  * individual buttons, a {@link module:ui/button/buttonview~ButtonView#tooltip} and an ARIA attribute of a button.

package/src/imageresize/imageresizeediting.js

@@ -8,6 +8,7 @@
  */
 
 import { Plugin } from 'ckeditor5/src/core';
+import ImageUtils from '../imageutils';
 import ResizeImageCommand from './resizeimagecommand';
 
 /**
@@ -19,6 +20,13 @@ import ResizeImageCommand from './resizeimagecommand';
  * @extends module:core/plugin~Plugin
  */
 export default class ImageResizeEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ ImageUtils ];
+	}
+
 	/**
 	 * @inheritDoc
 	 */
@@ -65,7 +73,8 @@ export default class ImageResizeEditing extends Plugin {
 		const resizeImageCommand = new ResizeImageCommand( editor );
 
 		this._registerSchema();
-		this._registerConverters();
+		this._registerConverters( 'imageBlock' );
+		this._registerConverters( 'imageInline' );
 
 		// Register `resizeImage` command and add `imageResize` command as an alias for backward compatibility.
 		editor.commands.add( 'resizeImage', resizeImageCommand );
@@ -76,23 +85,27 @@ export default class ImageResizeEditing extends Plugin {
 	 * @private
 	 */
 	_registerSchema() {
-		this.editor.model.schema.extend( 'image', { allowAttributes: 'width' } );
-		this.editor.model.schema.setAttributeProperties( 'width', {
-			isFormatting: true
-		} );
+		if ( this.editor.plugins.has( 'ImageBlockEditing' ) ) {
+			this.editor.model.schema.extend( 'imageBlock', { allowAttributes: 'width' } );
+		}
+
+		if ( this.editor.plugins.has( 'ImageInlineEditing' ) ) {
+			this.editor.model.schema.extend( 'imageInline', { allowAttributes: 'width' } );
+		}
 	}
 
 	/**
 	 * Registers image resize converters.
 	 *
 	 * @private
+	 * @param {'imageBlock'|'imageInline'} imageType The type of the image.
 	 */
-	_registerConverters() {
+	_registerConverters( imageType ) {
 		const editor = this.editor;
 
 		// Dedicated converter to propagate image's attribute to the img tag.
 		editor.conversion.for( 'downcast' ).add( dispatcher =>
-			dispatcher.on( 'attribute:width:image', ( evt, data, conversionApi ) => {
+			dispatcher.on( `attribute:width:${ imageType }`, ( evt, data, conversionApi ) => {
 				if ( !conversionApi.consumable.consume( data.item, evt.name ) ) {
 					return;
 				}
@@ -113,7 +126,7 @@ export default class ImageResizeEditing extends Plugin {
 		editor.conversion.for( 'upcast' )
 			.attributeToAttribute( {
 				view: {
-					name: 'figure',
+					name: imageType === 'imageBlock' ? 'figure' : 'img',
 					styles: {
 						width: /.+/
 					}

package/src/imageresize/imageresizehandles.js

@@ -12,6 +12,18 @@ import { WidgetResize } from 'ckeditor5/src/widget';
 
 import ImageLoadObserver from '../image/imageloadobserver';
 
+const RESIZABLE_IMAGES_CSS_SELECTOR =
+	'figure.image.ck-widget > img,' +
+	'figure.image.ck-widget > picture > img,' +
+	'figure.image.ck-widget > a > img,' +
+	'figure.image.ck-widget > a > picture > img,' +
+	'span.image-inline.ck-widget > img,' +
+	'span.image-inline.ck-widget > picture > img';
+
+const IMAGE_WIDGETS_CLASSES_MATCH_REGEXP = /(image|image-inline)/;
+
+const RESIZED_IMAGE_CLASS = 'image_resized';
+
 /**
  * The image resize by handles feature.
  *
@@ -58,12 +70,13 @@ export default class ImageResizeHandles extends Plugin {
 
 		this.listenTo( editingView.document, 'imageLoaded', ( evt, domEvent ) => {
 			// The resizer must be attached only to images loaded by the `ImageInsert`, `ImageUpload` or `LinkImage` plugins.
-			if ( !domEvent.target.matches( 'figure.image.ck-widget > img, figure.image.ck-widget > a > img' ) ) {
+			if ( !domEvent.target.matches( RESIZABLE_IMAGES_CSS_SELECTOR ) ) {
 				return;
 			}
 
-			const imageView = editor.editing.view.domConverter.domToView( domEvent.target );
-			const widgetView = imageView.findAncestor( 'figure' );
+			const domConverter = editor.editing.view.domConverter;
+			const imageView = domConverter.domToView( domEvent.target );
+			const widgetView = imageView.findAncestor( { classes: IMAGE_WIDGETS_CLASSES_MATCH_REGEXP } );
 			let resizer = this.editor.plugins.get( WidgetResize ).getResizerByViewElement( widgetView );
 
 			if ( resizer ) {
@@ -89,25 +102,34 @@ export default class ImageResizeHandles extends Plugin {
 					getHandleHost( domWidgetElement ) {
 						return domWidgetElement.querySelector( 'img' );
 					},
-					getResizeHost( domWidgetElement ) {
-						return domWidgetElement;
+					getResizeHost() {
+						// Return the model image element parent to avoid setting an inline element (<a>/<span>) as a resize host.
+						return domConverter.viewToDom( mapper.toViewElement( imageModel.parent ) );
 					},
 					// TODO consider other positions.
 					isCentered() {
 						const imageStyle = imageModel.getAttribute( 'imageStyle' );
 
-						return !imageStyle || imageStyle == 'full' || imageStyle == 'alignCenter';
+						return !imageStyle || imageStyle == 'block' || imageStyle == 'alignCenter';
 					},
 
 					onCommit( newValue ) {
+						// Get rid of the CSS class in case the command execution that follows is unsuccessful
+						// (e.g. Track Changes can override it and the new dimensions will not apply). Otherwise,
+						// the presence of the class and the absence of the width style will cause it to take 100%
+						// of the horizontal space.
+						editingView.change( writer => {
+							writer.removeClass( RESIZED_IMAGE_CLASS, widgetView );
+						} );
+
 						editor.execute( 'resizeImage', { width: newValue } );
 					}
 				} );
 
 			resizer.on( 'updateSize', () => {
-				if ( !widgetView.hasClass( 'image_resized' ) ) {
+				if ( !widgetView.hasClass( RESIZED_IMAGE_CLASS ) ) {
 					editingView.change( writer => {
-						writer.addClass( 'image_resized', widgetView );
+						writer.addClass( RESIZED_IMAGE_CLASS, widgetView );
 					} );
 				}
 			} );

package/src/imageresize/resizeimagecommand.js

@@ -8,7 +8,6 @@
  */
 
 import { Command } from 'ckeditor5/src/core';
-import { isImage } from '../image/utils';
 
 /**
  * The resize image command. Currently, it only supports the width attribute.
@@ -20,9 +19,11 @@ export default class ResizeImageCommand extends Command {
 	 * @inheritDoc
 	 */
 	refresh() {
-		const element = this.editor.model.document.selection.getSelectedElement();
+		const editor = this.editor;
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
+		const element = imageUtils.getClosestSelectedImageElement( editor.model.document.selection );
 
-		this.isEnabled = isImage( element );
+		this.isEnabled = !!element;
 
 		if ( !element || !element.hasAttribute( 'width' ) ) {
 			this.value = null;
@@ -48,8 +49,10 @@ export default class ResizeImageCommand extends Command {
 	 * @fires execute
 	 */
 	execute( options ) {
-		const model = this.editor.model;
-		const imageElement = model.document.selection.getSelectedElement();
+		const editor = this.editor;
+		const model = editor.model;
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
+		const imageElement = imageUtils.getClosestSelectedImageElement( model.document.selection );
 
 		this.value = {
 			width: options.width,