Merge pull request #15232 from ckeditor/ck/15158

Other (image): Changes default `image.insert.type` configuration to `"block"` and adds `"auto"` option. Closes #15158.

MINOR BREAKING CHANGE (image): By default, images are inserted as block images (not inline). To switch to the previous behavior (determining image type by insertion context), set the editor config image.insert.type to "auto".

packages/ckeditor5-ckbox/tests/ckboxcommand.js

@@ -1201,6 +1201,7 @@ function createTestEditor( config = {} ) {
 		substitutePlugins: [
 			CloudServicesCoreMock
 		],
+		image: { insert: { type: 'auto' } },
 		...config
 	} );
 }

packages/ckeditor5-image/docs/features/images-installation.md

@@ -1,7 +1,7 @@
 ---
 category: features-images
 menu-title: Installation
-meta-title: Installation and configuration of image features | CKEditor 5 Documentation
+meta-title: Installation and configuration of the image features | CKEditor 5 Documentation
 meta-description: Learn how to install and configure various image-related CKEdiotr 5 plugins.
 order: 15
 modified_at: 2021-06-17
@@ -17,7 +17,7 @@ npm install --save @ckeditor/ckeditor5-image
 	You may want to install the [`@ckeditor/ckeditor5-link`](https://www.npmjs.com/package/@ckeditor/ckeditor5-link) package if you want to use the {@link features/images-linking `LinkImage`} plugin in your editor.
 </info-box>
 
-Next add the {@link features/images-overview#image-features plugins that you need} to your plugin list. You also need to set the desired image toolbar items. Notice the {@link features/toolbar#separating-toolbar-items separators} used to organize the toolbar.
+Next, add the {@link features/images-overview#image-features plugins that you need} to your plugin list. You also need to set the desired image toolbar items. Notice the {@link features/toolbar#separating-toolbar-items separators} used to organize the toolbar.
 
 ```js
 import { Image, ImageCaption, ImageResize, ImageStyle, ImageToolbar } from '@ckeditor/ckeditor5-image';
@@ -35,7 +35,12 @@ ClassicEditor
 				'imageTextAlternative',
 				'|',
 				'linkImage'
-			]
+			],
+			insert: { 
+				// If this setting is omitted, the editor defaults to 'block'.
+				// See explanation below.
+				type: 'auto'
+			}
 		}
 	} )
 	.then( /* ... */ )
@@ -84,11 +89,29 @@ By default, the {@link module:image/image~Image} plugin available in all {@link
 	</table>
 </figure>
 
-<info-box info>
-	Up to CKEditor&nbsp;5 v[27.1.0], only **block** images were supported. The support for **inline** images started in v[28.0.0] in all editor builds loading the `Image` plugin.
+By default, if the `image.insert.type` configuration is not specified, all images inserted into the content will be treated as block images. This means that inserting an image inside a paragraph (or other content blocks) will create a new block for the image immediately below or above the current paragraph or block. After insertion, you can transform the block image into an inline image using the {@link features/images-overview#image-contextual-toolbar contextual toolbar}.
 
-	If your integration depends on a ready–to–use editor build and you want to take advantage of updated CKEditor&nbsp;5 but **without the support for inline images** (e.g. to maintain content compatibility), check out the {@link updating/update-to-29 official migration guide} that will help you configure the editor.
-</info-box>
+If you wish to modify this behavior, the `type` setting in the editor configuration can be used:
+
+```js
+ClassicEditor.create( element, {
+	image: {
+		insert: {
+			type: 'auto'
+		}
+	}
+} );
+```
+
+The `type` setting accepts the following three values:
+
+* `'auto'`: The editor determines the image type based on the cursor's position. For example, if you insert an image in the middle of a paragraph, it will be inserted as inline. If you insert it at the end or beginning of a paragraph, it becomes a block image.
+* `'block'`: Always insert images as block elements, placing them below or above the current paragraph or block.
+* `'inline'`: Always insert images as inline elements within the current paragraph or block.
+
+If the `type` setting is omitted from the configuration, the behavior defaults to inserting images as a block.
+
+**Important**: If only one type of image plugin is enabled (e.g., `ImageInline` is enabled but `ImageBlock` is not), the `image.insert.type` configuration will be effectively ignored and the supported image type will be used.
 
 ## Contribute
 

packages/ckeditor5-image/docs/features/images-overview.md

@@ -2,7 +2,7 @@
 category: features-images
 menu-title: Basics
 meta-title: Image features overview | CKEditor 5 Documentation
-meta-description: Find out all about images in CKEditor 5.
+meta-description: Find out all about images in CKEditor 5 - available image features, attributes, or the image toolbar.
 order: 10
 modified_at: 2021-06-17
 ---
@@ -37,7 +37,7 @@ The [`@ckeditor/ckeditor5-image`](https://www.npmjs.com/package/@ckeditor/ckedit
 * {@link features/images-resizing Image resizing} lets the user control the dimensions of images in the content.
 * {@link features/images-linking Linking images} makes it possible to use them as URL anchors.
 * A selection of {@link features/image-upload image upload methods} allows for the most convenient way of adding images. These include support for {@link features/images-inserting#inserting-images-via-pasting-a-url-into-the-editor inserting an image via a URL} and even {@link features/images-inserting#inserting-images-via-a-source-url via pasting a URL into the editor} along with custom integrations.
-* Support for {@link features/images-responsive responsive images} in CKEditor 5 is brought by the {@link features/ckbox CKBox} management platform. Responsive images will display properly on any viewport, enhancing the accessibility, reach and user experience.
+* Support for {@link features/images-responsive responsive images} in CKEditor 5 is brought by the {@link features/ckbox CKBox} management platform. Responsive images will display properly on any viewport, enhancing the accessibility, reach, and user experience.
 
 The availability of these plugins varies in different {@link installation/getting-started/predefined-builds predefined editor builds} but the most important ones are present in all builds as presented in the table below:
 

packages/ckeditor5-image/src/imageconfig.ts

@@ -484,16 +484,19 @@ export interface ImageInsertConfig {
 	integrations: Array<string>;
 
 	/**
-	 * 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)
+	 * This option 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, all images inserted into the editor will be block
+	 * if {@link module:image/imageblock~ImageBlock} is loaded. To let the editor decide the image type, choose `'auto'`.
 	 *
 	 * 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).
+	 * * `'inline'` – all images inserted into the editor will be inline (requires the {@link module:image/imageinline~ImageInline} plugin),
+	 * * `'auto'` – the editor will choose the optimal image type based on the context of the insertion and availability of plugins.
+	 *
+	 * @default 'block'
 	 */
-	type?: 'inline' | 'block';
+	type?: 'inline' | 'block' | 'auto';
 }
 
 /**

packages/ckeditor5-image/src/imageutils.ts

@@ -105,7 +105,7 @@ export default class ImageUtils extends Plugin {
 		const model = editor.model;
 		const selection = model.document.selection;
 
-		imageType = determineImageTypeForInsertion( editor, selectable || selection, imageType );
+		const determinedImageType = 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
@@ -116,20 +116,20 @@ export default class ImageUtils extends Plugin {
 		};
 
 		for ( const attributeName in attributes ) {
-			if ( !model.schema.checkAttribute( imageType, attributeName ) ) {
+			if ( !model.schema.checkAttribute( determinedImageType, attributeName ) ) {
 				delete attributes[ attributeName ];
 			}
 		}
 
 		return model.change( writer => {
 			const { setImageSizes = true } = options;
-			const imageElement = writer.createElement( imageType!, attributes );
+			const imageElement = writer.createElement( determinedImageType, attributes );
 
 			model.insertObject( imageElement, selectable, null, {
 				setSelection: 'on',
 				// 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).
-				findOptimalPosition: !selectable && imageType != 'imageInline' ? 'auto' : undefined
+				findOptimalPosition: !selectable && determinedImageType != 'imageInline' ? 'auto' : undefined
 			} );
 
 			// Inserting an image might've failed due to schema regulations.
@@ -381,7 +381,7 @@ function determineImageTypeForInsertion(
 		return 'imageInline';
 	}
 
-	if ( configImageInsertType === 'block' ) {
+	if ( configImageInsertType !== 'auto' ) {
 		return 'imageBlock';
 	}
 

packages/ckeditor5-image/tests/autoimage.js

@@ -31,7 +31,8 @@ describe( 'AutoImage - integration', () => {
 
 		return ClassicTestEditor
 			.create( editorElement, {
-				plugins: [ Typing, Paragraph, Link, Image, LinkImage, ImageCaption, AutoImage ]
+				plugins: [ Typing, Paragraph, Link, Image, LinkImage, ImageCaption, AutoImage ],
+				image: { insert: { type: 'auto' } }
 			} )
 			.then( newEditor => {
 				editor = newEditor;

packages/ckeditor5-image/tests/image/insertimagecommand.js

@@ -17,7 +17,8 @@ describe( 'InsertImageCommand', () => {
 	beforeEach( () => {
 		return VirtualTestEditor
 			.create( {
-				plugins: [ ImageBlockEditing, ImageInlineEditing, Paragraph ]
+				plugins: [ ImageBlockEditing, ImageInlineEditing, Paragraph ],
+				image: { insert: { type: 'auto' } }
 			} )
 			.then( newEditor => {
 				editor = newEditor;

packages/ckeditor5-image/tests/imageupload/imageuploadediting.js

@@ -64,7 +64,8 @@ describe( 'ImageUploadEditing', () => {
 				plugins: [
 					ImageBlockEditing, ImageInlineEditing, ImageUploadEditing,
 					Paragraph, UndoEditing, UploadAdapterPluginMock, ClipboardPipeline
-				]
+				],
+				image: { insert: { type: 'auto' } }
 			} )
 			.then( newEditor => {
 				editor = newEditor;

packages/ckeditor5-image/tests/imageupload/imageuploadprogress.js

@@ -52,7 +52,8 @@ describe( 'ImageUploadProgress', () => {
 				plugins: [
 					ImageBlockEditing, ImageInlineEditing, Paragraph, ImageUploadEditing,
 					ImageUploadProgress, UploadAdapterPluginMock, ClipboardPipeline
-				]
+				],
+				image: { insert: { type: 'auto' } }
 			} )
 			.then( newEditor => {
 				editor = newEditor;

packages/ckeditor5-image/tests/imageupload/imageuploadui.js

@@ -140,9 +140,8 @@ describe( 'ImageUploadUI', () => {
 		const id = fileRepository.getLoader( files[ 0 ] ).id;
 
 		expect( getModelData( model ) ).to.equal(
-			'<paragraph>' +
-				`f[<imageInline uploadId="${ id }" uploadStatus="reading"></imageInline>]oo` +
-			'</paragraph>'
+			`[<imageBlock uploadId="${ id }" uploadStatus="reading"></imageBlock>]` +
+			'<paragraph>foo</paragraph>'
 		);
 	} );
 
@@ -158,10 +157,9 @@ describe( 'ImageUploadUI', () => {
 		const id2 = fileRepository.getLoader( files[ 1 ] ).id;
 
 		expect( getModelData( model ) ).to.equal(
-			'<paragraph>' +
-				`foo<imageInline uploadId="${ id1 }" uploadStatus="reading"></imageInline>` +
-				`[<imageInline uploadId="${ id2 }" uploadStatus="reading"></imageInline>]` +
-			'</paragraph>' +
+			'<paragraph>foo</paragraph>' +
+			`<imageBlock uploadId="${ id1 }" uploadStatus="reading"></imageBlock>` +
+			`[<imageBlock uploadId="${ id2 }" uploadStatus="reading"></imageBlock>]` +
 			'<paragraph>bar</paragraph>'
 		);
 	} );

packages/ckeditor5-image/tests/imageupload/uploadimagecommand.js

@@ -33,7 +33,8 @@ describe( 'UploadImageCommand', () => {
 	beforeEach( () => {
 		return VirtualTestEditor
 			.create( {
-				plugins: [ FileRepository, ImageBlockEditing, ImageInlineEditing, Paragraph, UploadAdapterPluginMock ]
+				plugins: [ FileRepository, ImageBlockEditing, ImageInlineEditing, Paragraph, UploadAdapterPluginMock ],
+				image: { insert: { type: 'auto' } }
 			} )
 			.then( newEditor => {
 				editor = newEditor;