Merge branch 'stable'

docs/_snippets/features/image-style.html

@@ -1,11 +1,11 @@
 <div id="snippet-image-style">
-	<p>This is full width image (default style):</p>
+	<p>This is a full-width image (default style):</p>
 
 	<figure class="image">
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
 	</figure>
 
-	<p>This is side image:</p>
+	<p>This is a side image:</p>
 
 	<figure class="image image-style-side">
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">

docs/features/image.md

@@ -16,9 +16,9 @@ The [`@ckeditor/ckeditor5-image`](https://www.npmjs.com/package/@ckeditor/ckedit
 * {@link module:image/imageresize~ImageResize} adds support for resizing images.
 
 <info-box info>
-	All features listed above expect image resize are enabled by default in all builds.
+	All features listed above except the image resize are enabled by default in all WYSIWYG editor builds.
 
-	Check the documentation of each sub-feature to learn more about it.
+	Check the documentation of each subfeature to learn more about it.
 </info-box>
 
 ## Base image support
@@ -35,7 +35,7 @@ The {@link module:image/image~Image} feature adds support for plain images with
 	This feature follows the markup proposed by the [Editor Recommendations](https://ckeditor.github.io/editor-recommendations/features/image.html) project.
 </info-box>
 
-You can see the demo of an editor with the base image feature enabled below:
+You can see the demo of a WYSIWYG editor with the base image feature enabled below:
 
 {@snippet features/image}
 
@@ -47,7 +47,7 @@ You can see the demo of an editor with the base image feature enabled below:
 
 The {@link module:image/imagetoolbar~ImageToolbar} plugin introduces a contextual toolbar for images. The toolbar appears when an image is selected and can be configured to contain any buttons you want. Usually, these will be image-related options such as the text alternative (which is introduced by the base image plugin) button and [image styles buttons](#image-styles).
 
-See a demo of an editor with the contextual toolbar enabled:
+See a demo of a WYSIWYG editor with the contextual toolbar enabled:
 
 {@snippet features/image-toolbar}
 
@@ -85,9 +85,9 @@ In more advanced scenarios, the user may need to be able to decide whether the i
 
 This is what the {@link module:image/imagestyle~ImageStyle} feature is designed for.
 
-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 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.
+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.
 
-A style is applied to the image in form of a class. By default, the editor 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).
+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).
 
 A normal (full width) image:
 
@@ -102,20 +102,20 @@ A side image:
 ```
 
 <info-box>
-	The actual styling of the images is the developer's job. The 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 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.
 
 	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).
 </info-box>
 
-Below you can see a demo of the 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 image styles feature enabled. The default configuration is used. You can change the styles of images through the image's contextual toolbar.
 
 {@snippet features/image-style}
 
 ### Configuring image styles
 
 The available image styles can be configured using the {@link module:image/image~ImageConfig#styles `image.styles`} option.
 
-The following editor supports the default full image style plus left- and right-aligned images:
+The following WYSIWYG editor supports the default full image style plus left- and right-aligned images:
 
 ```js
 ClassicEditor
@@ -147,12 +147,12 @@ See the result below:
 {@snippet features/image-style-custom}
 
 <info-box hint>
-	In the example above the options used represent simple "align left" and "align right" styles. Most text editors support left, center and right alignments, however, try 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.
+	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>
 
 ### Defining custom styles
 
-Besides using the {@link module:image/imagestyle/utils~defaultStyles 5 predefined styles}:
+Besides using the {@link module:image/imagestyle/utils~defaultStyles five predefined styles}:
 
 * `'full'`,
 * `'side'`,
@@ -163,7 +163,7 @@ Besides using the {@link module:image/imagestyle/utils~defaultStyles 5 predefine
 you can also define your own styles or modify the existing ones.
 
 <info-box>
-	Reusing (or modifying) predefined styles has this advantage that CKEditor 5 will use its official translations for the defined button titles.
+	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.
@@ -176,23 +176,23 @@ See the {@link features/image-upload Image upload} guide.
 
 ## Responsive images
 
-Responsive images support 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.
+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
 
-While the [image styles](#image-styles) feature is meant to give the user a choice between a set of styling options provided by the system (this is &mdash; by the developer/administrator who created it) there are also scenarios in which the user should be able to freely set the width of an image. And that is where the image resize feature come to play.
+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.
 
-It is implemented by the {@link module:image/imageresize~ImageResize} plugin and enables 4 "resize handles" displayed over a selected image. The user can freely resize the image by dragging them. The feature can be configured to use either percentage (default) or pixel values.
+It is implemented by the {@link module:image/imageresize~ImageResize} plugin and enables four "resize handles" displayed over the selected image. The user can freely resize the image by dragging them. The feature can be configured to use either percentage (default) or pixel values.
 
 {@snippet features/image-resize}
 
 ### Enabling image resizing
 
-The resize image is not enabled by default in any of the builds. In order to enable it you need to load the {@link module:image/imageresize~ImageResize} plugin. Read more in the [Installation](#installation) section.
+The image resize feature is not enabled by default in any of the editor builds. In order to enable it, you need to load the {@link module:image/imageresize~ImageResize} plugin. Read more in the [Installation](#installation) section.
 
 ### Markup and styling
 
-When you resize an image the inline `width` style is used and the `<figure>` is assigned the `image_resized` class:
+When you resize an image, the inline `width` style is used and the `<figure>` is assigned the `image_resized` class:
 
 ```html
 <figure class="image image_resized" style="width: 75%;">
@@ -218,7 +218,7 @@ And the `max-width` gets overridden by the following rule:
 }
 ```
 
-The other concern when styling resized images is that by default CKEditor 5 uses `display: table` on `<figure class="image">` to make it take the size of the `<img>` element inside it. Unfortunately, [browsers do not support yet using `max-width` and `width` on the same element if it is styled with `display: table`](https://stackoverflow.com/questions/4019604/chrome-safari-ignoring-max-width-in-table/14420691#14420691). Therefore, `display: block` needs to be used when the image is resized:
+Another concern when styling resized images is that by default, CKEditor 5 uses `display: table` on `<figure class="image">` to make it take the size of the `<img>` element inside it. Unfortunately, [browsers do not yet support using `max-width` and `width` on the same element if it is styled with `display: table`](https://stackoverflow.com/questions/4019604/chrome-safari-ignoring-max-width-in-table/14420691#14420691). Therefore, `display: block` needs to be used when the image is resized:
 
 ```css
 .ck-content .image.image_resized {
@@ -237,11 +237,11 @@ The other concern when styling resized images is that by default CKEditor 5 uses
 
 ### Using pixels instead of percentage width
 
-Using percentage widths ensures that content stays responsive when displayed in different places than in the editor. If the user made an image take 60% of the content's width in the editor, if you will ever change the width of the target page (where this content is displayed), the image will still take 60% of that space. The same is true if this page is responsive and adjusts to the viewport's width.
+Using percentage widths ensures that content stays responsive when displayed in different places than in the WYSIWYG editor. If the user made an image take 60% of the content's width in the editor, if you ever change the width of the target page (where this content is displayed), the image will still take 60% of that space. The same is true if the page is responsive and adjusts to the viewport's width.
 
-If you would configure the editor to use pixel values, the image could take, for example, too much space after you introduced a new layout for your website.
+If you configured the editor to use pixel values, the image could take, for example, too much space after you introduced a new layout for your website.
 
-However, there are cases where pixel values may be preferred. If so, you can configure the editor to use them by setting the {@link module:image/image~ImageConfig#resizeUnit `config.image.resizeUnit`} option:
+However, there are cases where pixel values may be preferred. You can thus configure the editor to use them by setting the {@link module:image/image~ImageConfig#resizeUnit `config.image.resizeUnit`} option:
 
 ```js
 ClassicEditor
@@ -256,15 +256,20 @@ ClassicEditor
 
 {@snippet features/image-resize-px}
 
-<!--
+### Future development
 
-* a note about followups? a dialog, a toggle predefined sizes (e.g. 40%, 50%, 75%, 100%)
+Resizing by dragging handles displayed over the image is the first option provided, but we consider implementing more with time. Some of the possible next steps include:
 
--->
+* [Buttons such as "50%", "75%" and "100%" in the image toolbar](https://github.com/ckeditor/ckeditor5-image/issues/322), allowing the user to choose only from predefined widths.
+* [A traditional "width" input](https://github.com/ckeditor/ckeditor5-image/issues/319). Or an option to set both width and height separately.
+* [An option to restore the original image size](https://github.com/ckeditor/ckeditor5-image/issues/318).
+* [Limiting image resize](https://github.com/ckeditor/ckeditor5-image/issues/320) with min and max values.
+
+We count on your feedback. React with 👍 under the respective tickets or [report new ones](https://github.com/ckeditor/ckeditor5-image/issues) if you have different ideas.
 
 ## Installation
 
-To add image features to your editor, install the [`@ckeditor/ckeditor5-image`](https://www.npmjs.com/package/@ckeditor/ckeditor5-image) package:
+To add image features to your rich-text editor, install the [`@ckeditor/ckeditor5-image`](https://www.npmjs.com/package/@ckeditor/ckeditor5-image) package:
 
 ```bash
 npm install --save @ckeditor/ckeditor5-image

src/imageresize.js

@@ -145,7 +145,7 @@ export default class ImageResize extends Plugin {
 /**
  * The available options are `'px'` or `'%'`.
  *
- * Determines size unit applied to resized image.
+ * Determines the size unit applied to the resized image.
  *
  *		ClassicEditor
  *			.create( editorElement, {

theme/imageresize.css

@@ -6,20 +6,20 @@
 .ck-content .image.image_resized {
 	max-width: 100%;
 	/*
-	The figure element for resized images must not use `display:table` as browsers doesn't support `max-width` for it well.
+	The `<figure>` element for resized images must not use `display:table` as browsers do not support `max-width` for it well.
 	See https://stackoverflow.com/questions/4019604/chrome-safari-ignoring-max-width-in-table/14420691#14420691 for more.
-	Fortunately, since we control width, there's no risk that the image will look bad.
+	Fortunately, since we control the width, there is no risk that the image will look bad.
 	*/
 	display: block;
 	box-sizing: border-box;
 
 	& img {
-		/* For resized images it's the figure that determines the image's width. */
+		/* For resized images it is the `<figure>` element that determines the image width. */
 		width: 100%;
 	}
 
 	& > figcaption {
-		/* Figure uses display block, so figcaption also has to. */
+		/* The `<figure>` element uses `display:block`, so `<figcaption>` also has to. */
 		display: block;
 	}
 }