I/7560: Update Image feature docs and change the image alignment styles behaviour.

packages/ckeditor5-image/docs/_snippets/features/image-resize-px.js

@@ -11,7 +11,36 @@ ClassicEditor
 	.create( document.querySelector( '#snippet-image-resize-px' ), {
 		removePlugins: [ 'LinkImage' ],
 		image: {
-			resizeUnit: 'px'
+			resizeUnit: 'px',
+			resizeOptions: [
+				{
+					name: 'imageResize:original',
+					label: 'Original',
+					value: null
+				},
+				{
+					name: 'imageResize:250',
+					label: '250px',
+					value: '250'
+				},
+				{
+					name: 'imageResize:400',
+					label: '400px',
+					value: '400'
+				}
+			],
+			styles: [
+				'alignLeft',
+				'alignCenter',
+				'alignRight'
+			],
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:alignCenter',
+				'imageStyle:alignRight',
+				'|',
+				'imageResize'
+			]
 		},
 		toolbar: {
 			viewportTopOffset: window.getViewportTopOffsetConfig()

packages/ckeditor5-image/docs/_snippets/features/image-resize.js

@@ -13,6 +13,20 @@ ClassicEditor
 		toolbar: {
 			viewportTopOffset: window.getViewportTopOffsetConfig()
 		},
+		image: {
+			styles: [
+				'alignLeft',
+				'alignCenter',
+				'alignRight'
+			],
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:alignCenter',
+				'imageStyle:alignRight',
+				'|',
+				'imageTextAlternative'
+			]
+		},
 		cloudServices: CS_CONFIG
 	} )
 	.then( editor => {

packages/ckeditor5-image/docs/_snippets/features/image-resizeui.html

@@ -5,10 +5,4 @@ <h3>Resize me using image toolbar buttons!</h3>
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
 		<figcaption>Autumn fields by Aleksander Nowodziński</figcaption>
 	</figure>
-
-	<h3>Resized image (width: 75%):</h3>
-
-	<figure class="image image_resized" style="width:75%;">
-		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
-	</figure>
 </div>

packages/ckeditor5-image/docs/_snippets/features/image-resizeui.js

@@ -34,9 +34,16 @@ ClassicEditor
 					icon: 'large'
 				}
 			],
+			styles: [
+				'alignLeft',
+				'alignCenter',
+				'alignRight'
+			],
 			toolbar: [
-				'imageStyle:full',
-				'imageStyle:side', '|',
+				'imageStyle:alignLeft',
+				'imageStyle:alignCenter',
+				'imageStyle:alignRight',
+				'|',
 				'imageResize:50',
 				'imageResize:75',
 				'imageResize:original'

packages/ckeditor5-image/docs/_snippets/features/image-resizeuidropdown.html

@@ -5,10 +5,4 @@ <h3>Resize me using the dropdown!</h3>
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
 		<figcaption>Autumn fields by Aleksander Nowodziński</figcaption>
 	</figure>
-
-	<h3>Resized image (width: 75%):</h3>
-
-	<figure class="image image_resized" style="width:75%;">
-		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
-	</figure>
 </div>

packages/ckeditor5-image/docs/_snippets/features/image-resizeuidropdown.js

@@ -31,7 +31,18 @@ ClassicEditor
 					value: '75'
 				}
 			],
-			toolbar: [ 'imageStyle:full', 'imageStyle:side', '|', 'imageResize' ]
+			styles: [
+				'alignLeft',
+				'alignCenter',
+				'alignRight'
+			],
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:alignCenter',
+				'imageStyle:alignRight',
+				'|',
+				'imageResize'
+			]
 		},
 		cloudServices: CS_CONFIG
 	} )

packages/ckeditor5-image/docs/_snippets/features/image-style-custom.html → packages/ckeditor5-image/docs/_snippets/features/image-style-presentational.html

@@ -1,9 +1,15 @@
 <div id="snippet-image-style-custom">
-	<p>An image to play with:</p>
+	<p>This is a default image (no style):</p>
 
 	<figure class="image">
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
 	</figure>
 
+	<p>This is a right-aligned image:</p>
+
+	<figure class="image image-style-align-right">
+		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
+	</figure>
+
 	<p>Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here.</p>
 </div>

packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js → packages/ckeditor5-image/docs/_snippets/features/image-style-presentational.js

@@ -12,17 +12,17 @@ ClassicEditor
 		removePlugins: [ 'ImageResize', 'LinkImage' ],
 		image: {
 			styles: [
-				// This option is equal to a situation where no style is applied.
-				'full',
-
-				// This represents an image aligned to left.
 				'alignLeft',
-
-				// This represents an image aligned to right.
+				'alignCenter',
 				'alignRight'
 			],
-
-			toolbar: [ 'imageTextAlternative', '|', 'imageStyle:alignLeft', 'imageStyle:full', 'imageStyle:alignRight' ]
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:alignCenter',
+				'imageStyle:alignRight',
+				'|',
+				'imageTextAlternative'
+			]
 		},
 		toolbar: {
 			viewportTopOffset: window.getViewportTopOffsetConfig()

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

@@ -78,17 +78,31 @@ By default, if the image caption is empty, the `<figcaption>` element is not vis
 
 {@snippet features/image-caption}
 
+## Image upload
+
+See the {@link features/image-upload Image upload} guide.
+
+## Responsive images
+
+Support for responsive images in CKEditor 5 is brought by the {@link features/easy-image Easy Image} feature without any additional configuration. Learn more how to use the feature in your project in the {@link features/easy-image#responsive-images Easy Image integration} guide.
+
 ## Image styles
 
 In simple integrations it is enough to let the user insert images, set their text alternative and the editor's job is done. An example of such a simple solution are e.g. [GitHub](https://github.com) comments. The styling of the images (for example, their maximum width and margins) is controlled by GitHub through stylesheets.
 
 In more advanced scenarios, the user may need to be able to decide whether the image should take the whole width (if it is the article's main photo) or it should take, for example, 50% of the width and be pulled out of the content (so called "pulled images"). Various integration scenarios require different types of images to be used.
 
-This is what the {@link module:image/imagestyle~ImageStyle} feature is designed for.
+Finally, in certain situations, the user should be able to granularly control how an image is presented so they should be able to set the size and alignment separately.
 
-However, unlike in CKEditor 4, in CKEditor 5 the end user does not set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the WYSIWYG editor integration. This gives the developer control over how the users style images and makes the user's life easier by setting multiple properties at once.
+The {@link module:image/imagestyle~ImageStyle} feature solves the last two scenarios. The former is handled by so-called ["semantical styles"](#semantical-styles) and the latter by ["presentational styles"](#presentational-styles) in combination with [image resize](#resizing-images).
 
-A style is applied to the image in form of a class. By default, CKEditor 5 is configured to support two styles: "full width" (which does not apply any class &mdash; it is the default style) and "side image" (which applies the `image-style-side` class).
+The available image styles can be configured using the {@link module:image/image~ImageConfig#styles `config.image.styles`} option. Respective buttons should also be added to the image toolbar via {@link module:image/image~ImageConfig#toolbar `config.image.toolbar`}.
+
+### Semantical styles
+
+A semantical style let the user choose from a predefined "types" of images. The user is not able to set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the WYSIWYG editor integration. This gives the developer control over how the users style images and makes the user's life easier by setting multiple properties at once.
+
+A style is applied to the image in form of a class. By default, CKEditor 5 is configured to support two default semantical styles: **"full width"** (which does not apply any class &mdash; it is the default style) and **"side image"** (which applies the `image-style-side` class).
 
 A normal (full width) image:
 
@@ -103,53 +117,84 @@ A side image:
 ```
 
 <info-box>
-	The actual styling of the images is the developer's job. CKEditor 5 WYSIWYG editor comes with some default styles, but they will only be applied to images inside the editor. The developer needs to style them appropriately on the target pages.
+	The actual styling of the images is the integrator's job. CKEditor 5 WYSIWYG editor comes with some default styles, but they will only be applied to images inside the editor. The integrator needs to style them appropriately on the target pages.
+
+	You can find the source of the default styles applied by the editor here: [`ckeditor5-image/theme/imagestyle.css`](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-image/theme/imagestyle.css).
 
-	You can find the source of the default styles applied by the editor here: [`ckeditor5-image/theme/imagestyle.css`](https://github.com/ckeditor/ckeditor5-image/blob/master/theme/imagestyle.css).
+	Read more about {@link builds/guides/integration/content-styles styling the content of the editor}.
 </info-box>
 
-Below you can see a demo of the WYSIWYG editor with the image styles feature enabled. The default configuration is used. You can change the styles of images through the image's contextual toolbar.
+Below you can see a demo of the WYSIWYG editor with the semantical image styles. The "full" and "side" styles are the default value of {@link module:image/image~ImageConfig#styles `config.image.styles`} so you do not need to set it.
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Image, ImageToolbar, ImageCaption, ImageStyle ],
+		image: {
+			toolbar: [
+				'imageStyle:full',
+				'imageStyle:side',
+				'|',
+				'imageTextAlternative'
+			],
+
+			// The default value,
+			styles: [
+				'full',
+				'side'
+			]
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+See the result below. You can change the styles of images through the image's contextual toolbar.
 
 {@snippet features/image-style}
 
-### Configuring image styles
+<info-box hint>
+Try to understand what use cases the system needs to support and define semantic options accordingly. Defining useful and clear styles is one of the steps towards a good user experience and clear, portable output. For example, the "side image" style can be displayed as a floated image on wide screens and as a normal image on low resolution screens (e.g. mobile browsers).
+</info-box>
+
+<info-box warning>
+	While semantical styles can be combined with manual [image resizing](#resizing-images), these features were not designed to be used together.
 
-The available image styles can be configured using the {@link module:image/image~ImageConfig#styles `image.styles`} option.
+	If you want to enable image resizing, use [presentational image styles](#presentational-styles).
+</info-box>
+
+### Presentational styles
 
-The following WYSIWYG editor supports the default full image style plus left- and right-aligned images:
+Presentational styles do not add any special meaning to the content. They directly control the visual aspect of an image.
+
+Currently, the available presentational styles are "align center", "align left" and "align right".
 
 ```js
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		image: {
-			// You need to configure the image toolbar, too, so it uses the new style buttons.
-			toolbar: [ 'imageTextAlternative', '|', 'imageStyle:alignLeft', 'imageStyle:full', 'imageStyle:alignRight' ],
-
+			// Configure the available styles.
 			styles: [
-				// This option is equal to a situation where no style is applied.
-				'full',
-
-				// This represents an image aligned to the left.
-				'alignLeft',
+				'alignLeft', 'alignCenter', 'alignRight'
+			],
 
-				// This represents an image aligned to the right.
-				'alignRight'
+			// You need to configure the image toolbar, too, so it shows the new style buttons.
+			toolbar: [
+				'imageStyle:alignLeft', 'imageStyle:alignCenter', 'imageStyle:alignRight',
+				'|',
+				'imageTextAlternative'
 			]
 		}
 	} )
 	.then( ... )
 	.catch( ... );
 ```
 
-The code sample above uses predefined image styles: `'full'`, `'alignLeft'` and `'alignRight'`. The latter two apply, respectively, the `.image-style-align-left` and  `.image-style-align-right` classes to the `<figure>` element.
+The code sample above uses predefined presentational image styles: `'alignLeft'`, `'alignCenter'` and `'alignRight'`. They apply, respectively, the `.image-style-align-left`, `.image-style-align-center` and  `.image-style-align-right` classes to the `<figure>` element.
 
 See the result below:
 
-{@snippet features/image-style-custom}
-
-<info-box hint>
-	In the example above the options represent simple "align left" and "align right" styles. Most text editors support left, center and right alignments, however, it is better not to think about CKEditor 5's image styles in this way. Try to understand what use cases the system needs to support and define semantic options accordingly. Defining useful and clear styles is one of the steps towards a good user experience and clear, portable output. For example, the "side image" style can be displayed as a floated image on wide screens and as a normal image on low resolution screens.
-</info-box>
+{@snippet features/image-style-presentational}
 
 ### Defining custom styles
 
@@ -167,18 +212,10 @@ you can also define your own styles or modify the existing ones.
 	Reusing (or modifying) predefined styles has the following advantage: CKEditor 5 will use its official translations for the defined button titles.
 </info-box>
 
-You can find advanced examples in the {@link module:image/image~ImageConfig#styles `image.styles`} configuration option documentation.
+You can find advanced examples in the {@link module:image/image~ImageConfig#styles `config.image.styles`} configuration option documentation.
 
 <!-- TODO (live example)... -->
 
-## Image upload
-
-See the {@link features/image-upload Image upload} guide.
-
-## Responsive images
-
-Support for responsive images in CKEditor 5 is brought by the {@link features/easy-image Easy Image} feature without any additional configuration. Learn more how to use the feature in your project in the {@link features/easy-image#responsive-images Easy Image integration} guide.
-
 ## Resizing images
 
 The [image styles](#image-styles) feature is meant to give the user the choice between a set of styling options provided by the system (so by the developer or administrator who created it). There are also scenarios where the user should be able to freely set the width of an image. And that is where the image resize feature comes to play.
@@ -187,11 +224,21 @@ It is implemented by the {@link module:image/imageresize~ImageResize} plugin and
 
 The plugin also gives you an ability to change the size of the image through the image toolbar. You can set an optional static configuration with {@link module:image/image~ImageConfig#resizeOptions} and choose whether you want to use a dropdown or set of the standalone buttons.
 
-### Resize image using handles
+### Methods to resize images
+
+The editor offers three ways to resize images. One of them (resize handles) is
+
+#### Using handles
+
+In this case, the user is able to resize images via dragging square handles displayed in each corner of the image. Once [image resizing was enabled](#enabling-image-resizing), this option does not require any additional configuration.
 
 {@snippet features/image-resize}
 
-### Resize image using the plugin dropdown
+#### Using the dropdown
+
+In this case, the user is able to choose from a set of predefined options. These options can be displayed in the image toolbar in form of a dropdown.
+
+To use this option, you need to [enable image resizing](#enabling-image-resizing) and configure the available {@link module:image/image~ImageConfig#resizeOptions resize options}.
 
 ```js
 const imageConfiguration = {
@@ -212,13 +259,17 @@ const imageConfiguration = {
 			value: '75'
 		}
 	],
-	toolbar: [ ... , 'imageResize' ]
+	toolbar: [ ..., 'imageResize' ]
 }
 ```
 
 {@snippet features/image-resizeuidropdown}
 
-### Resize image using the standalone buttons
+#### Using standalone buttons
+
+In this case, the resize options are displayed in form of separate buttons. The benefit of this solution is the smoothest UX as the user needs just one click to resize an image.
+
+To use this option, you need to [enabling image resizing](#enabling-image-resizing) and configure the available {@link module:image/image~ImageConfig#resizeOptions resize options}.
 
 ```js
 const imageConfiguration = {
@@ -240,7 +291,7 @@ const imageConfiguration = {
 		}
 	],
 	toolbar: [
-		// ...,
+		...,
 		'imageResize:original',
 		'imageResize:50',
 		'imageResize:75'

packages/ckeditor5-image/tests/manual/imageresize.js

@@ -25,11 +25,11 @@ const commonConfig = {
 	toolbar: [ 'heading', '|', 'bold', 'italic', 'link',
 		'bulletedList', 'numberedList', 'blockQuote', 'insertTable', 'undo', 'redo', 'outdent', 'indent' ],
 	image: {
-		toolbar: [ 'imageStyle:alignLeft', 'imageStyle:full', 'imageStyle:side' ],
+		toolbar: [ 'imageStyle:alignLeft', 'imageStyle:alignCenter', 'imageStyle:alignRight', '|', 'imageResize' ],
 		styles: [
-			'full',
 			'alignLeft',
-			'side' // Purposely using side image instead right aligned image to make sure it works well with both style types.
+			'alignCenter',
+			'alignRight'
 		]
 	},
 	table: {