Merge stable into master

packages/ckeditor5-widget/docs/api/widget.md

@@ -16,21 +16,21 @@ Browse the API documentation of this package by using the module tree on the lef
 
 The widget API consists of two layers:
 
-* The {@link module:widget/widget~Widget} plugin which enables base support for this feature. Usually, your plugin which implements a specific widget will define its reliance on the `Widget` plugin via its {@link module:core/plugin~Plugin.requires `Plugin.requires`} property.
-* The {@link module:widget/utils~toWidget `toWidget()`} {@link module:widget/utils~toWidgetEditable `toWidgetEditable()`} functions which need to be used during the conversion in order to make a specific element either a widget or a widget's nested editable. See their documentation for more details.
+* The {@link module:widget/widget~Widget} plugin that enables base support for this feature. Usually, your plugin which implements a specific widget will define its reliance on the `Widget` plugin via its {@link module:core/plugin~Plugin.requires `Plugin.requires`} property.
+* The {@link module:widget/utils~toWidget `toWidget()`} and {@link module:widget/utils~toWidgetEditable `toWidgetEditable()`} functions that need to be used during the conversion in order to make a specific element either a widget or a widget's nested editable. See their documentation for more details.
 
-Besides the above mentioned core functionalities, this package implements the following utils:
+Besides the above mentioned core functionalities, this package implements the following utilities:
 
 * The {@link module:widget/widgettoolbarrepository~WidgetToolbarRepository `WidgetToolbarRepository`} plugin which exposes a nice API for registering widget toolbars.
-* A couple of helper functions for managing widgets in the {@link module:widget/utils `@ckeditor/ckeditor5-widget/utils`} module.
+* A few helper functions for managing widgets in the {@link module:widget/utils `@ckeditor/ckeditor5-widget/utils`} module.
 
 <info-box>
-	The widget API is proposed in a very different way than it was in CKEditor 4. It is just a set of utilities that allow you to implement typical object-like entities. Most of the work actually happens in the {@link api/engine engine} and this API's role is only to properly conduct the engine.
+	The widget API is proposed in a very different way than it was in CKEditor 4. It is just a set of utilities that allow you to implement typical object-like entities. Most of the work actually happens in the {@link api/engine engine} and this API's only role is to control it.
 </info-box>
 
 ## Installation
 
-```bash
+```plaintext
 npm install --save @ckeditor/ckeditor5-widget
 ```
 

packages/ckeditor5-widget/docs/framework/guides/deep-dive/widget-internals.md

@@ -7,38 +7,38 @@ menu-title: Widget internals
 
 ## Disabling the widget type around feature
 
-The {@link module:widget/widgettypearound~WidgetTypeAround `WidgetTypeAround`} plugin allows users to type around widgets where normally it is impossible to place the caret due to limitations of web browsers. Although this feature boosts the productivity, some integrations may not want or need it, for instance:
+The {@link module:widget/widgettypearound~WidgetTypeAround `WidgetTypeAround`} plugin allows users to type around the widgets, in places where it is normally impossible to place the caret due to limitations of the web browsers. Although this feature boosts the productivity and ease of typing, some integrations may not want or need it, for instance:
 
-* when the UI of the feature collides with the integration,
-* when typing outside widgets should be impossible (content made exclusively of widgets),
-* when certain widgets have a fixed location in the document that should never change.
+* When the UI of the feature collides with the integration.
+* When typing outside widgets should be impossible (content made exclusively of widgets).
+* When certain widgets have a fixed location in the document that should never change.
 
-In the sections that follows, you will learn how to configure the editor to address these specific cases.
+In the sections that follow, you will learn how to configure CKEditor 5 WYSIWYG editor to address these specific needs.
 
-### Hiding the buttons that insert paragraphs
+### Hiding the buttons that insert paragraphs around widgets
 
 {@img assets/img/framework-deep-dive-widget-type-around-buttons.gif A screenshot showing the location of the buttons that insert paragraphs around widgets.}
 
-The easiest way to get rid of the type around buttons is to hide them using CSS. Put the following code snippet anywhere in your application and the buttons will no longer bother the users:
+The easiest way to get rid of the type around widget buttons is to hide them using CSS. Put the following code snippet anywhere in your application and the buttons will no longer be displayed:
 
 ```css
 .ck.ck-editor__editable .ck-widget .ck-widget__type-around__button {
 	display: none;
 }
 ```
 
-If you only want to customize the type around buttons you can use the same CSS selector to modify their look or the position.
+If you only want to customize the type around widget buttons, you can use the same CSS selector to modify their look or position.
 
 <info-box hint>
-	Hiding the type around buttons does not disable the feature. Users will still be able to activate the caret before or after individual widgets using the keyboard and start typing. [Learn how to disable the entire feature](#disabling-the-entire-feature).
+	Hiding the type around widget buttons does not disable the feature. Users will still be able to activate the caret before or after individual widgets using the arrow keys and typing. [Learn how to disable the entire feature](#disabling-the-entire-feature).
 </info-box>
 
 ### Disabling the entire feature
 
-Although the {@link module:widget/widgettypearound~WidgetTypeAround `WidgetTypeAround`} plugin is an integral part of the {@link module:widget/widget~Widget widget} sub–system and loaded by default whenever an editor feature uses widgets (for instance, {@link features/image images} or {@link features/table tables}), you can still disable on the fly. Disabling the feature will both hide the buttons in the widgets and disable other behaviors, for instance:
+Although the {@link module:widget/widgettypearound~WidgetTypeAround `WidgetTypeAround`} plugin is an integral part of the {@link module:widget/widget~Widget widget} subsystem and is loaded by default whenever an editor feature uses widgets (for instance, for {@link features/image images} or {@link features/table tables}), you can still disable it on the fly. Turning off the feature will both hide the widget buttons and disable other behaviors, for instance:
 
-* the caret will not be rendered before or after a widget when a user navigates the document using arrow keys,
-* the <kbd>Enter</kbd> and <kbd>Shift</kbd>+<kbd>Enter</kbd> keystrokes will no longer insert paragraphs if pressed when a widget is selected.
+* The caret will not be rendered before or after a widget when the user navigates the document using arrow keys.
+* The <kbd>Enter</kbd> and <kbd>Shift</kbd>+<kbd>Enter</kbd> keystrokes will no longer insert paragraphs if pressed when a widget is selected.
 
 Use the {@link module:core/plugin~Plugin#forceDisabled `forceDisabled()`} method of the plugin to disable it on the fly like in the snippet below:
 
@@ -50,18 +50,18 @@ ClassicEditor
 	.then( editor => {
 		const widgetTypeAroundPlugin = editor.plugins.get( 'WidgetTypeAround' );
 
-		// Disable the WidgetTypeAround plugin.
+		// Disable the widget type around plugin.
 		widgetTypeAroundPlugin.forceDisabled( 'MyApplication' );
 	} )
 	.catch( err => {
 		console.error( err.stack );
 	} );
 ```
 
-<info-box hint>
-	You can always re–enable the plugin using the following snippet
-	```js
-	widgetTypeAroundPlugin.clearForceDisabled( 'MyApplication' );
-	```
-	Please refer to the {@link module:core/plugin~Plugin#clearForceDisabled API documentation} to learn more.
-</info-box>
+You can always re–enable the plugin using the following snippet
+
+```js
+widgetTypeAroundPlugin.clearForceDisabled( 'MyApplication' );
+```
+
+Refer to the {@link module:core/plugin~Plugin#clearForceDisabled API documentation} to learn more.

packages/ckeditor5-widget/src/widgettypearound/utils.js

@@ -11,12 +11,12 @@ import { isWidget } from '../utils';
 
 /**
  * The name of the type around model selection attribute responsible for
- * displaying a "fake caret" next to a selected widget.
+ * displaying a fake caret next to a selected widget.
  */
 export const TYPE_AROUND_SELECTION_ATTRIBUTE = 'widget-type-around';
 
 /**
- * Checks if an element is a widget that qualifies to get the type around UI.
+ * Checks if an element is a widget that qualifies to get the widget type around UI.
  *
  * @param {module:engine/view/element~Element} viewElement
  * @param {module:engine/model/element~Element} modelElement
@@ -28,7 +28,7 @@ export function isTypeAroundWidget( viewElement, modelElement, schema ) {
 }
 
 /**
- * For the passed HTML element, this helper finds the closest type around button ancestor.
+ * For the passed HTML element, this helper finds the closest widget type around button ancestor.
  *
  * @param {HTMLElement} domElement
  * @returns {HTMLElement|null}
@@ -38,12 +38,12 @@ export function getClosestTypeAroundDomButton( domElement ) {
 }
 
 /**
- * For the passed type around button element, this helper determines at which position
+ * For the passed widget type around button element, this helper determines at which position
  * the paragraph would be inserted into the content if, for instance, the button was
  * clicked by the user.
  *
  * @param {HTMLElement} domElement
- * @returns {'before'|'after'} Position of the button.
+ * @returns {'before'|'after'} The position of the button.
  */
 export function getTypeAroundButtonPosition( domElement ) {
 	return domElement.classList.contains( 'ck-widget__type-around__button_before' ) ? 'before' : 'after';
@@ -63,12 +63,12 @@ export function getClosestWidgetViewElement( domElement, domConverter ) {
 }
 
 /**
- * For the passed selection instance, it returns the position of the "fake caret" displayed next to a widget.
+ * For the passed selection instance, it returns the position of the fake caret displayed next to a widget.
  *
- * **Note**: If the "fake caret" is not currently displayed, `null` is returned.
+ * **Note**: If the fake caret is not currently displayed, `null` is returned.
  *
  * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
- * @returns {'before'|'after'|null} Position of the fake caret or `null` when none is preset.
+ * @returns {'before'|'after'|null} The position of the fake caret or `null` when none is present.
  */
 export function getTypeAroundFakeCaretPosition( selection ) {
 	return selection.getAttribute( TYPE_AROUND_SELECTION_ATTRIBUTE );