@ckeditor/ckeditor5-image 28.0.0 → 30.0.0

package/src/imageutils.js

@@ -0,0 +1,342 @@
+/**
+ * @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/imageutils
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+import { findOptimalInsertionRange, isWidget, toWidget } from 'ckeditor5/src/widget';
+import { determineImageTypeForInsertionAtSelection } from './image/utils';
+
+/**
+ * A set of helpers related to images.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class ImageUtils extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'ImageUtils';
+	}
+
+	/**
+	 * Checks if the provided model element is an `image` or `imageInline`.
+	 *
+	 * @param {module:engine/model/element~Element} modelElement
+	 * @returns {Boolean}
+	 */
+	isImage( modelElement ) {
+		return this.isInlineImage( modelElement ) || this.isBlockImage( modelElement );
+	}
+
+	/**
+	 * Checks if the provided view element represents an inline image.
+	 *
+	 * Also, see {@link module:image/imageutils~ImageUtils#isImageWidget}.
+	 *
+	 * @param {module:engine/view/element~Element} element
+	 * @returns {Boolean}
+	 */
+	isInlineImageView( element ) {
+		return !!element && element.is( 'element', 'img' );
+	}
+
+	/**
+	 * Checks if the provided view element represents a block image.
+	 *
+	 * Also, see {@link module:image/imageutils~ImageUtils#isImageWidget}.
+	 *
+	 * @param {module:engine/view/element~Element} element
+	 * @returns {Boolean}
+	 */
+	isBlockImageView( element ) {
+		return !!element && element.is( 'element', 'figure' ) && element.hasClass( 'image' );
+	}
+
+	/**
+	 * Handles inserting single file. This method unifies image insertion using {@link module:widget/utils~findOptimalInsertionRange}
+	 * method.
+	 *
+	 *		const imageUtils = editor.plugins.get( 'ImageUtils' );
+	 *
+	 *		imageUtils.insertImage( { src: 'path/to/image.jpg' } );
+	 *
+	 * @param {Object} [attributes={}] Attributes of the inserted image.
+	 * This method filters out the attributes which are disallowed by the {@link module:engine/model/schema~Schema}.
+	 * @param {module:engine/model/selection~Selectable} [selectable] Place to insert the image. If not specified,
+	 * the {@link module:widget/utils~findOptimalInsertionRange} logic will be applied for the block images
+	 * and `model.document.selection` for the inline images.
+	 *
+	 * **Note**: If `selectable` is passed, this helper will not be able to set selection attributes (such as `linkHref`)
+	 * and apply them to the new image. In this case, make sure all selection attributes are passed in `attributes`.
+	 *
+	 * @param {'imageBlock'|'imageInline'} [imageType] Image type of inserted image. If not specified,
+	 * it will be determined automatically depending of editor config or place of the insertion.
+	 * @return {module:engine/view/element~Element|null} The inserted model image element.
+	 */
+	insertImage( attributes = {}, selectable = null, imageType = null ) {
+		const editor = this.editor;
+		const model = editor.model;
+		const selection = model.document.selection;
+
+		imageType = determineImageTypeForInsertion( editor, selectable || selection, imageType );
+
+		// Mix declarative attributes with selection attributes because the new image should "inherit"
+		// the latter for best UX. For instance, inline images inserted into existing links
+		// should not split them. To do that, they need to have "linkHref" inherited from the selection.
+		attributes = {
+			...Object.fromEntries( selection.getAttributes() ),
+			...attributes
+		};
+
+		for ( const attributeName in attributes ) {
+			if ( !model.schema.checkAttribute( imageType, attributeName ) ) {
+				delete attributes[ attributeName ];
+			}
+		}
+
+		return model.change( writer => {
+			const imageElement = writer.createElement( imageType, attributes );
+
+			// If we want to insert a block image (for whatever reason) then we don't want to split text blocks.
+			// This applies only when we don't have the selectable specified (i.e., we insert multiple block images at once).
+			if ( !selectable && imageType != 'imageInline' ) {
+				selectable = findOptimalInsertionRange( selection, model );
+			}
+
+			model.insertContent( imageElement, selectable );
+
+			// Inserting an image might've failed due to schema regulations.
+			if ( imageElement.parent ) {
+				writer.setSelection( imageElement, 'on' );
+
+				return imageElement;
+			}
+
+			return null;
+		} );
+	}
+
+	/**
+	 * Returns an image widget editing view element if one is selected or is among the selection's ancestors.
+	 *
+	 * @protected
+	 * @param {module:engine/view/selection~Selection|module:engine/view/documentselection~DocumentSelection} selection
+	 * @returns {module:engine/view/element~Element|null}
+	 */
+	getClosestSelectedImageWidget( selection ) {
+		const viewElement = selection.getSelectedElement();
+
+		if ( viewElement && this.isImageWidget( viewElement ) ) {
+			return viewElement;
+		}
+
+		let parent = selection.getFirstPosition().parent;
+
+		while ( parent ) {
+			if ( parent.is( 'element' ) && this.isImageWidget( parent ) ) {
+				return parent;
+			}
+
+			parent = parent.parent;
+		}
+
+		return null;
+	}
+
+	/**
+	 * Returns a image model element if one is selected or is among the selection's ancestors.
+	 *
+	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+	 * @returns {module:engine/model/element~Element|null}
+	 */
+	getClosestSelectedImageElement( selection ) {
+		const selectedElement = selection.getSelectedElement();
+
+		return this.isImage( selectedElement ) ? selectedElement : selection.getFirstPosition().findAncestor( 'imageBlock' );
+	}
+
+	/**
+	 * Checks if image can be inserted at current model selection.
+	 *
+	 * @protected
+	 * @returns {Boolean}
+	 */
+	isImageAllowed() {
+		const model = this.editor.model;
+		const selection = model.document.selection;
+
+		return isImageAllowedInParent( this.editor, selection ) && isNotInsideImage( selection );
+	}
+
+	/**
+	 * Converts a given {@link module:engine/view/element~Element} to an image widget:
+	 * * Adds a {@link module:engine/view/element~Element#_setCustomProperty custom property} allowing to recognize the image widget
+	 * element.
+	 * * Calls the {@link module:widget/utils~toWidget} function with the proper element's label creator.
+	 *
+	 * @protected
+	 * @param {module:engine/view/element~Element} viewElement
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer An instance of the view writer.
+	 * @param {String} label The element's label. It will be concatenated with the image `alt` attribute if one is present.
+	 * @returns {module:engine/view/element~Element}
+	 */
+	toImageWidget( viewElement, writer, label ) {
+		writer.setCustomProperty( 'image', true, viewElement );
+
+		const labelCreator = () => {
+			const imgElement = this.findViewImgElement( viewElement );
+			const altText = imgElement.getAttribute( 'alt' );
+
+			return altText ? `${ altText } ${ label }` : label;
+		};
+
+		return toWidget( viewElement, writer, { label: labelCreator } );
+	}
+
+	/**
+	 * Checks if a given view element is an image widget.
+	 *
+	 * @protected
+	 * @param {module:engine/view/element~Element} viewElement
+	 * @returns {Boolean}
+	 */
+	isImageWidget( viewElement ) {
+		return !!viewElement.getCustomProperty( 'image' ) && isWidget( viewElement );
+	}
+
+	/**
+	 * Checks if the provided model element is an `image`.
+	 *
+	 * @param {module:engine/model/element~Element} modelElement
+	 * @returns {Boolean}
+	 */
+	isBlockImage( modelElement ) {
+		return !!modelElement && modelElement.is( 'element', 'imageBlock' );
+	}
+
+	/**
+	 * Checks if the provided model element is an `imageInline`.
+	 *
+	 * @param {module:engine/model/element~Element} modelElement
+	 * @returns {Boolean}
+	 */
+	isInlineImage( modelElement ) {
+		return !!modelElement && modelElement.is( 'element', 'imageInline' );
+	}
+
+	/**
+	 * Get the view `<img>` from another view element, e.g. a widget (`<figure class="image">`), a link (`<a>`).
+	 *
+	 * The `<img>` can be located deep in other elements, so this helper performs a deep tree search.
+	 *
+	 * @param {module:engine/view/element~Element} figureView
+	 * @returns {module:engine/view/element~Element}
+	 */
+	findViewImgElement( figureView ) {
+		if ( this.isInlineImageView( figureView ) ) {
+			return figureView;
+		}
+
+		const editingView = this.editor.editing.view;
+
+		for ( const { item } of editingView.createRangeIn( figureView ) ) {
+			if ( this.isInlineImageView( item ) ) {
+				return item;
+			}
+		}
+	}
+}
+
+// Checks if image is allowed by schema in optimal insertion parent.
+//
+// @private
+// @param {module:core/editor/editor~Editor} editor
+// @param {module:engine/model/selection~Selection} selection
+// @returns {Boolean}
+function isImageAllowedInParent( editor, selection ) {
+	const imageType = determineImageTypeForInsertion( editor, selection );
+
+	if ( imageType == 'imageBlock' ) {
+		const parent = getInsertImageParent( selection, editor.model );
+
+		if ( editor.model.schema.checkChild( parent, 'imageBlock' ) ) {
+			return true;
+		}
+	} else if ( editor.model.schema.checkChild( selection.focus, 'imageInline' ) ) {
+		return true;
+	}
+
+	return false;
+}
+
+// Checks if selection is not placed inside an image (e.g. its caption).
+//
+// @private
+// @param {module:engine/model/selection~Selectable} selection
+// @returns {Boolean}
+function isNotInsideImage( selection ) {
+	return [ ...selection.focus.getAncestors() ].every( ancestor => !ancestor.is( 'element', 'imageBlock' ) );
+}
+
+// Returns a node that will be used to insert image with `model.insertContent`.
+//
+// @private
+// @param {module:engine/model/selection~Selection} selection
+// @param {module:engine/model/model~Model} model
+// @returns {module:engine/model/element~Element}
+function getInsertImageParent( selection, model ) {
+	const insertionRange = findOptimalInsertionRange( selection, model );
+	const parent = insertionRange.start.parent;
+
+	if ( parent.isEmpty && !parent.is( 'element', '$root' ) ) {
+		return parent.parent;
+	}
+
+	return parent;
+}
+
+// Determine image element type name depending on editor config or place of insertion.
+//
+// @private
+// @param {module:core/editor/editor~Editor} editor
+// @param {module:engine/model/selection~Selectable} selectable
+// @param {'imageBlock'|'imageInline'} [imageType] Image element type name. Used to force return of provided element name,
+// but only if there is proper plugin enabled.
+// @returns {'imageBlock'|'imageInline'} imageType
+function determineImageTypeForInsertion( editor, selectable, imageType ) {
+	const schema = editor.model.schema;
+	const configImageInsertType = editor.config.get( 'image.insert.type' );
+
+	if ( !editor.plugins.has( 'ImageBlockEditing' ) ) {
+		return 'imageInline';
+	}
+
+	if ( !editor.plugins.has( 'ImageInlineEditing' ) ) {
+		return 'imageBlock';
+	}
+
+	if ( imageType ) {
+		return imageType;
+	}
+
+	if ( configImageInsertType === 'inline' ) {
+		return 'imageInline';
+	}
+
+	if ( configImageInsertType === 'block' ) {
+		return 'imageBlock';
+	}
+
+	// Try to replace the selected widget (e.g. another image).
+	if ( selectable.is( 'selection' ) ) {
+		return determineImageTypeForInsertionAtSelection( schema, selectable );
+	}
+
+	return schema.checkChild( selectable, 'imageInline' ) ? 'imageInline' : 'imageBlock';
+}

package/src/pictureediting.js

@@ -0,0 +1,149 @@
+/**
+ * @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/pictureediting
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+
+import ImageEditing from './image/imageediting';
+import ImageUtils from './imageutils';
+import {
+	downcastSourcesAttribute,
+	upcastPicture
+} from './image/converters';
+
+/**
+ * This plugin enables the [`<picture>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture) element support in the editor.
+ *
+ * * It enables the `sources` model attribute on `imageBlock` and `imageInline` model elements
+ * (brought by {@link module:image/imageblock~ImageBlock} and {@link module:image/imageinline~ImageInline}, respectively).
+ * * It translates the `sources` model element to the view (also: data) structure that may look as follows:
+ *
+ *		<p>Inline image using picture:
+ *			<picture>
+ *				<source media="(min-width: 800px)" srcset="image-large.webp" type="image/webp">
+ *				<source media="(max-width: 800px)" srcset="image-small.webp" type="image/webp">
+ *				<!-- Other sources as specified in the "sources" model attribute... -->
+ *				<img src="image.png" alt="An image using picture" />
+ *			</picture>
+ *		</p>
+ *
+ *		<p>Block image using picture:</p>
+ *		<figure class="image">
+ *			<picture>
+ *				<source media="(min-width: 800px)" srcset="image-large.webp" type="image/webp">
+ *				<source media="(max-width: 800px)" srcset="image-small.webp" type="image/webp">
+ *				<!-- Other sources as specified in the "sources" model attribute... -->
+ *				<img src="image.png" alt="An image using picture" />
+ *			</picture>
+ *			<figcaption>Caption of the image</figcaption>
+ *		</figure>
+ *
+ *	**Note:** The value of the `sources` {@glink framework/guides/architecture/editing-engine#changing-the-model model attribute}
+ * 	in both examples equals:
+ *
+ *		[
+ *			{
+ *				media: '(min-width: 800px)',
+ *				srcset: 'image-large.webp',
+ *				type: 'image/webp'
+ *			},
+ *			{
+ *				media: '(max-width: 800px)',
+ *				srcset: 'image-small.webp',
+ *				type: 'image/webp'
+ *			}
+ * 		]
+ *
+ * * It integrates with the {@link module:image/imageupload~ImageUpload} plugin so images uploaded in the editor
+ * automatically render using `<picture>` if the {@glink features/images/image-upload/image-upload upload adapter}
+ * supports image sources and provides neccessary data.
+ *
+ * @private
+ * @extends module:core/plugin~Plugin
+ */
+export default class PictureEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ ImageEditing, ImageUtils ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'PictureEditing';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	afterInit() {
+		const editor = this.editor;
+
+		if ( editor.plugins.has( 'ImageBlockEditing' ) ) {
+			editor.model.schema.extend( 'imageBlock', {
+				allowAttributes: [ 'sources' ]
+			} );
+		}
+
+		if ( editor.plugins.has( 'ImageInlineEditing' ) ) {
+			editor.model.schema.extend( 'imageInline', {
+				allowAttributes: [ 'sources' ]
+			} );
+		}
+
+		this._setupConversion();
+		this._setupImageUploadEditingIntegration();
+	}
+
+	/**
+	 * Configures conversion pipelines to support upcasting and downcasting images using the `<picture>` view element
+	 * and the model `sources` attribute.
+	 *
+	 * @private
+	 */
+	_setupConversion() {
+		const editor = this.editor;
+		const conversion = editor.conversion;
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
+
+		conversion.for( 'upcast' ).add( upcastPicture( imageUtils ) );
+		conversion.for( 'downcast' ).add( downcastSourcesAttribute( imageUtils ) );
+	}
+
+	/**
+	 * Makes it possible for uploaded images to get the `sources` model attribute and the `<picture>...</picture>`
+	 * view structure out-of-the-box if relevant data is provided along the
+	 * {@link module:image/imageupload/imageuploadediting~ImageUploadEditing#event:uploadComplete} event.
+	 *
+	 * @private
+	 */
+	_setupImageUploadEditingIntegration() {
+		const editor = this.editor;
+
+		if ( !editor.plugins.has( 'ImageUploadEditing' ) ) {
+			return;
+		}
+
+		this.listenTo( editor.plugins.get( 'ImageUploadEditing' ), 'uploadComplete', ( evt, { imageElement, data } ) => {
+			const sources = data.sources;
+
+			if ( !sources ) {
+				return;
+			}
+
+			editor.model.change( writer => {
+				writer.setAttributes( {
+					sources
+				}, imageElement );
+			} );
+		} );
+	}
+}

package/theme/image.css

@@ -3,34 +3,114 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
-.ck-content .image {
-	display: table;
-	clear: both;
-	text-align: center;
+.ck-content {
+	& .image {
+		display: table;
+		clear: both;
+		text-align: center;
 
-	/* Make sure there is some space between the content and the image. Center image by default. */
-	margin: 1em auto;
+		/* Make sure there is some space between the content and the image. Center image by default. */
+		/* The first value should be equal to --ck-spacing-large variable if used in the editor context
+	 	to avoid the content jumping (See https://github.com/ckeditor/ckeditor5/issues/9825). */
+		margin: 0.9em auto;
 
-	& img {
-		/* Prevent unnecessary margins caused by line-height (see #44). */
-		display: block;
+		/* Make sure the caption will be displayed properly (See: https://github.com/ckeditor/ckeditor5/issues/1870). */
+		min-width: 50px;
+
+		& img {
+			/* Prevent unnecessary margins caused by line-height (see #44). */
+			display: block;
+
+			/* Center the image if its width is smaller than the content's width. */
+			margin: 0 auto;
+
+			/* Make sure the image never exceeds the size of the parent container (ckeditor/ckeditor5-ui#67). */
+			max-width: 100%;
+
+			/* Make sure the image is never smaller than the parent container (See: https://github.com/ckeditor/ckeditor5/issues/9300). */
+			min-width: 100%
+		}
+	}
 
-		/* Center the image if its width is smaller than the content's width. */
-		margin: 0 auto;
+	& .image-inline {
+		/*
+		 * Normally, the .image-inline would have "display: inline-block" and "img { width: 100% }" (to follow the wrapper while resizing).
+		 * Unfortunately, together with "srcset", it gets automatically stretched up to the width of the editing root.
+		 * This strange behavior does not happen with inline-flex.
+		 */
+		display: inline-flex;
 
-		/* Make sure the image never exceeds the size of the parent container (ckeditor/ckeditor5-ui#67). */
+		/* While being resized, don't allow the image to exceed the width of the editing root. */
 		max-width: 100%;
 
-		/* Make sure the caption will be displayed properly (See: https://github.com/ckeditor/ckeditor5/issues/1870). */
-		min-width: 50px;
+		/* This is required by Safari to resize images in a sensible way. Without this, the browser breaks the ratio. */
+		align-items: flex-start;
+
+		/* When the picture is present it must act as a flex container to let the img resize properly */
+		& picture {
+			display: flex;
+		}
+
+		/* When the picture is present, it must act like a resizable img. */
+		& picture,
+		& img {
+			/* This is necessary for the img to span the entire .image-inline wrapper and to resize properly. */
+			flex-grow: 1;
+			flex-shrink: 1;
+
+			/* Prevents overflowing the editing root boundaries when an inline image is very wide. */
+			max-width: 100%;
+		}
 	}
 }
 
-/*
- * Since the caption placeholder for images disappears when focused, it does not require special treatment
- * and can go with a position that follows text alignment of an .image out-of-the-box (center by default).
- * See https://github.com/ckeditor/ckeditor5/issues/8689.
- */
-.ck.ck-editor__editable .image > figcaption.ck-placeholder::before {
-	position: static;
+.ck.ck-editor__editable {
+	/*
+	 * Inhertit the content styles padding of the <figcaption> in case the integration overrides `text-align: center`
+	 * of `.image` (e.g. to the left/right). This ensures the placeholder stays at the padding just like the native
+	 * caret does, and not at the edge of <figcaption>.
+	 */
+	& .image > figcaption.ck-placeholder::before {
+		padding-left: inherit;
+		padding-right: inherit;
+
+		/*
+		 * Make sure the image caption placeholder doesn't overflow the placeholder area.
+		 * See https://github.com/ckeditor/ckeditor5/issues/9162.
+		 */
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+
+
+	/*
+	 * Make sure the selected inline image always stays on top of its siblings.
+	 * See https://github.com/ckeditor/ckeditor5/issues/9108.
+	 */
+	& .image.ck-widget_selected {
+		z-index: 1;
+	}
+
+	& .image-inline.ck-widget_selected {
+		z-index: 1;
+
+		/*
+		 * Make sure the native browser selection style is not displayed.
+		 * Inline image widgets have their own styles for the selected state and
+		 * leaving this up to the browser is asking for a visual collision.
+		 */
+		& ::selection {
+			display: none;
+		}
+	}
+
+	/* The inline image nested in the table should have its original size if not resized.
+	See https://github.com/ckeditor/ckeditor5/issues/9117. */
+	& td,
+	& th {
+		& .image-inline img {
+			max-width: none;
+		}
+	}
 }

package/theme/imagecaption.css

@@ -3,13 +3,35 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
+:root {
+	--ck-color-image-caption-background: hsl(0, 0%, 97%);
+	--ck-color-image-caption-text: hsl(0, 0%, 20%);
+	--ck-color-image-caption-highligted-background: hsl(52deg 100% 50%);
+}
+
+/* Content styles */
 .ck-content .image > figcaption {
 	display: table-caption;
 	caption-side: bottom;
 	word-break: break-word;
-	color: hsl(0, 0%, 20%);
-	background-color: hsl(0, 0%, 97%);
+	color: var(--ck-color-image-caption-text);
+	background-color: var(--ck-color-image-caption-background);
 	padding: .6em;
 	font-size: .75em;
 	outline-offset: -1px;
 }
+
+/* Editing styles */
+.ck.ck-editor__editable .image > figcaption.image__caption_highlighted {
+	animation: ck-image-caption-highlight .6s ease-out;
+}
+
+@keyframes ck-image-caption-highlight {
+	0% {
+		background-color: var(--ck-color-image-caption-highligted-background);
+	}
+
+	100% {
+		background-color: var(--ck-color-image-caption-background);
+	}
+}

package/theme/imageresize.css

@@ -24,6 +24,17 @@
 	}
 }
 
+.ck.ck-editor__editable {
+	/* The resized inline image nested in the table should respect its parent size.
+	See https://github.com/ckeditor/ckeditor5/issues/9117. */
+	& td,
+	& th {
+		& .image-inline.image_resized img {
+			max-width: 100%;
+		}
+	}
+}
+
 [dir="ltr"] .ck.ck-button.ck-button_with-text.ck-resize-image-button .ck-button__icon {
 	margin-right: var(--ck-spacing-standard);
 }