Merge branch 'stable'

README.md

@@ -9,7 +9,7 @@ CKEditor 5 typing feature
 [![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-typing/status.svg)](https://david-dm.org/ckeditor/ckeditor5-typing)
 [![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-typing/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-typing?type=dev)
 
-This package implements support for typing (inputting and deleting text) in CKEditor 5.
+This package implements support for typing (inputting and deleting text) in CKEditor 5. It also includes the automatic text transformations (autocorrect) feature that lets you automatically turn predefined snippets into their improved forms.
 
 ## Documentation
 

docs/_snippets/features/text-transformation-extended.js

@@ -16,7 +16,7 @@ ClassicEditor
  typing: {
  transformations: {
  remove: [
- // Don't use the transformations from the
+ // Do not use the transformations from the
  // 'symbols' and 'quotes' groups.
  'symbols',
  'quotes',
@@ -32,8 +32,8 @@ ClassicEditor
  { from: ':+1:', to: '👍' },
  { from: ':tada:', to: '🎉' },
 
- // You can also define patterns using regexp.
- // Note: the pattern must end with `$` and all its fragments must be wrapped
+ // You can also define patterns using regular expressions.
+ // Note: The pattern must end with `$` and all its fragments must be wrapped
  // with capturing groups.
  // The following rule replaces ` "foo"` with ` «foo»`.
  {
@@ -42,7 +42,7 @@ ClassicEditor
  },
 
  // Finally, you can define `to` as a callback.
- // This (naive) rule will auto-capitalize first word after a period.
+ // This (naive) rule will auto-capitalize the first word after a period.
  {
  from: /(\. )([a-z])$/,
  to: matches => [ null, matches[ 1 ].toUpperCase() ]

docs/api/typing.md

@@ -6,7 +6,7 @@ category: api-reference
 
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-typing.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-typing)
 
-This package implements support for typing (inputting and deleting text) in CKEditor 5.
+This package implements support for typing (inputting and deleting text) in CKEditor 5. It also includes the automatic text transformations (autocorrect) feature that lets you automatically turn predefined snippets into their improved forms.
 
 ## Documentation
 

docs/features/text-transformation.md

@@ -1,18 +1,19 @@
 ---
 category: features
+menu-title: Automatic text transformation
 ---
 
-# Automatic text transformation
+# Automatic text transformation (autocorrect)
 
 {@snippet features/build-text-transformation-source}
 
-The {@link module:typing/texttransformation~TextTransformation} feature brings support for automatically turning predefined snippets into their improved forms. For instance:
+The {@link module:typing/texttransformation~TextTransformation} feature brings support for implementing autocorrection options, i.e. automatically turning predefined snippets into their improved forms. Here are some examples that will be transformed in your WYSIWYG editor:
 
 <table style="width: unset">
  <thead>
   <tr>
-  <th>from</th>
-  <th>to</th>
+  <th>From</th>
+  <th>To</th>
   </tr>
  </thead>
  <tbody>
@@ -39,36 +40,36 @@ The {@link module:typing/texttransformation~TextTransformation} feature brings s
  </tbody>
 </table>
 
-This feature comes pre-configured with a set of the most popular transformations. You can, however, disable existing ones or add your own ones.
+This feature comes pre-configured with a set of the most popular transformations. You can, however, disable existing ones or add your own autocorrect entries.
 
-While, most often this feature is used to allow easily inserting characters which are not present on your keyboard, it can also be used to achieve other goals. For instance, you can improve users' productivity by configuring it to expand some abbreviations (e.g. team or company names) into their full forms.
+While most often this feature is used to easily insert special characters that are not present on your keyboard, it can also be used to achieve other goals. For instance, you can improve the users' productivity by configuring it to expand some abbreviations (e.g. team or company names) into their full forms.
 
 ## Demo
 
-Type snippets such as `(tm)`, `1/2`, `->`, `--`, `"foo"` and see how they get automatically transformed into their nicer typographically forms.
+Type snippets such as `(c)`, `3/4`, `!=`, `---`, `"foo"` into the rich-text editor below and see how they get transformed into their typographically nicer forms. You can see the complete list of predefined transformations in the {@link module:typing/texttransformation~TextTransformationConfig} documentation.
 
 {@snippet features/text-transformation}
 
 ## Related productivity features
 
 In addition to enabling automatic text transformations, you may want to check the following productivity features:
 
-* {@link features/autoformat Autoformatting} &mdash; allows quickly applying formatting to the content you are writing.
-* {@link features/mentions Mentions} &mdash; support for smart autocompletion.
+* {@link features/autoformat Autoformatting} &ndash; It allows to quickly apply formatting to the content you are writing.
+* {@link features/mentions Mentions} &ndash; It brings support for smart autocompletion.
 
 ## Configuring transformations
 
-This feature comes pre-configured with a set of transformations. You can find the list of them in {@link module:typing/texttransformation~TextTransformationConfig} documentation.
+This feature comes pre-configured with a set of transformations. You can find the list of them in the {@link module:typing/texttransformation~TextTransformationConfig} documentation.
 
-By using the below defined options you can extend, limit or override this list:
+By using the options defined below you can extend, limit or override this list:
 
-* {@link module:typing/texttransformation~TextTransformationConfig#include `typing.transformations.include`} &mdash; allows overriding the default configuration. When overriding the default configuration you can reuse the predefined transformations (by using their names, which you can find in the {@link module:typing/texttransformation~TextTransformationConfig} documentation) and write your own transformations
-* {@link module:typing/texttransformation~TextTransformationConfig#remove `typing.transformations.remove`} &mdash; allows disabling predefined transformations.
-* {@link module:typing/texttransformation~TextTransformationConfig#extra `typing.transformations.extra`} &mdash; allows disabling predefined transformations. You can find the names of the predefined transformations in the {@link module:typing/texttransformation~TextTransformationConfig} documentation.
+* {@link module:typing/texttransformation~TextTransformationConfig#include `typing.transformations.include`} &ndash; Overrides the default configuration. When overriding the default configuration you can reuse the predefined transformations (by using their names that can be found in the {@link module:typing/texttransformation~TextTransformationConfig} documentation) and write your own transformations.
+* {@link module:typing/texttransformation~TextTransformationConfig#remove `typing.transformations.remove`} &ndash; Removes predefined transformations.
+* {@link module:typing/texttransformation~TextTransformationConfig#extra `typing.transformations.extra`} &ndash; Adds your custom transformations to the predefined ones.
 
-### Example: using `transformations.include`
+### Example: Using `transformations.include`
 
-For instance, in order to use only the transformations from the "quotes" and "typography" groups and in order to turn `CKE` into `CKEditor`, you can use the `transformations.include` property like this:
+For instance, in order to use only the transformations from the "quotes" and "typography" groups and to turn `CKE` into `CKEditor`, you can use the `transformations.include` property like this:
 
 ```js
 ClassicEditor
@@ -80,7 +81,7 @@ ClassicEditor
  'quotes',
  'typography',
 
- // Plus, some custom transformation.
+ // Plus some custom transformation.
  { from: 'CKE', to: 'CKEditor' }
  ],
  }
@@ -90,17 +91,17 @@ ClassicEditor
  .catch( ... );
 ```
 
-### Example: using `transformations.remove` and `extra`
+### Example: Using `transformations.remove` and `extra`
 
-Another example, removing a couple of transformations and adding a couple of extra ones:
+Another example, removing a few transformations and adding some extra ones:
 
 ```js
 ClassicEditor
  .create( editorElement, {
  typing: {
  transformations: {
  remove: [
- // Don't use the transformations from the
+ // Do not use the transformations from the
  // 'symbols' and 'quotes' groups.
  'symbols',
  'quotes',
@@ -116,8 +117,8 @@ ClassicEditor
  { from: ':+1:', to: '👍' },
  { from: ':tada:', to: '🎉' },
 
- // You can also define patterns using regexp.
- // Note: the pattern must end with `$` and all its fragments must be wrapped
+ // You can also define patterns using regular expressions.
+ // Note: The pattern must end with `$` and all its fragments must be wrapped
  // with capturing groups.
  // The following rule replaces ` "foo"` with ` «foo»`.
  {
@@ -126,7 +127,7 @@ ClassicEditor
  },
 
  // Finally, you can define `to` as a callback.
- // This (naive) rule will auto-capitalize first word after a period.
+ // This (naive) rule will auto-capitalize the first word after a period.
  {
  from: /(\. )([a-z])$/,
  to: matches => [ null, matches[ 1 ].toUpperCase() ]
@@ -141,7 +142,7 @@ ClassicEditor
 
 You can read more about the format of transformation rules in {@link module:typing/texttransformation~TextTransformationDescription}.
 
-Test the rules defined above:
+You can test the custom rules defined above in the demo:
 
 {@snippet features/text-transformation-extended}
 

src/texttransformation.js

@@ -60,7 +60,7 @@ const TRANSFORMATION_GROUPS = {
  quotes: [ 'quotesPrimary', 'quotesSecondary' ]
 };
 
-// Set of default transformations provided by the feature.
+// A set of default transformations provided by the feature.
 const DEFAULT_TRANSFORMATIONS = [
  'symbols',
  'mathematical',
@@ -148,8 +148,9 @@ export default class TextTransformation extends Plugin {
  }
 }
 
-// Normalizes config `from` parameter value.
-// The normalized value for `from` parameter is a RegExp instance. If passed `from` is already a RegExp instance it is returned unchanged.
+// Normalizes the configuration `from` parameter value.
+// The normalized value for the `from` parameter is a RegExp instance. If the passed `from` is already a RegExp instance,
+// it is returned unchanged.
 //
 // @param {String|RegExp} from
 // @returns {RegExp}
@@ -162,9 +163,9 @@ function normalizeFrom( from ) {
  return from;
 }
 
-// Normalizes config `to` parameter value.
-// The normalized value for `to` parameter is a function that takes an array and returns an array. See more in configuration description.
-// If passed `to` is already a function it is returned unchanged.
+// Normalizes the configuration `to` parameter value.
+// The normalized value for the `to` parameter is a function that takes an array and returns an array. See more in the
+// configuration description. If the passed `to` is already a function, it is returned unchanged.
 //
 // @param {String|Array.<null|String>|Function} to
 // @returns {Function}
@@ -237,31 +238,31 @@ function expandGroupsAndRemoveDuplicates( definitions ) {
 }
 
 /**
- * Text transformation definition object. Describes what should be replaced with what.
+ * The text transformation definition object. It describes what should be replaced with what.
  *
- * The input value (`from`) can be passed either as a string or a regexp.
+ * The input value (`from`) can be passed either as a string or as a regular expression.
  *
- * * If a string is passed it will be simply checked if the end of the input matches it.
- * * If a regexp is passed, its entire length must be covered with capturing groups (e.g. `/(foo)(bar)$/`).
+ * * If a string is passed, it will be simply checked if the end of the input matches it.
+ * * If a regular expression is passed, its entire length must be covered with capturing groups (e.g. `/(foo)(bar)$/`).
  * Also, since it is compared against the end of the input, it has to end with `$` to be correctly matched.
  * See examples below.
  *
- * The output value (`to`) can be passed either as a string or an array or a function.
+ * The output value (`to`) can be passed as a string, as an array or as a function.
  *
- * * If a string is passed, it will be used as a replacement value as-is. Note, that a string output value can be used only if
- * the input value is a string too.
- * * If an array is passed it has to have the same number of elements as there are capturing groups in the input value regexp.
- * Each capture group will be replaced by a corresponding string from the passed array. If given capturing group should not be replaced,
+ * * If a string is passed, it will be used as a replacement value as-is. Note that a string output value can be used only if
+ * the input value is a string, too.
+ * * If an array is passed, it has to have the same number of elements as there are capturing groups in the input value regular expression.
+ * Each capture group will be replaced with a corresponding string from the passed array. If a given capturing group should not be replaced,
  * use `null` instead of passing a string.
  * * If a function is used, it should return an array as described above. The function is passed one parameter &mdash; an array with matches
- * by the regexp. See the examples below.
+ * by the regular expression. See the examples below.
  *
- * Simple string-to-string replacement:
+ * A simple string-to-string replacement:
  *
  * { from: '(c)', to: '©' }
  *
- * Change quotes styles using regular expression. Note how all the parts are in separate capturing groups and the space at the beginning and
- * the text inside quotes are not replaced (`null` passed as the first and the third value in `to` parameter):
+ * Change quote styles using a regular expression. Note how all the parts are in separate capturing groups and the space at the beginning
+ * and the text inside quotes are not replaced (`null` passed as the first and the third value in the `to` parameter):
  *
  * {
  * from: /(^|\s)(")([^"]*)(")$/,
@@ -276,8 +277,8 @@ function expandGroupsAndRemoveDuplicates( definitions ) {
  * }
  *
  * @typedef {Object} module:typing/texttransformation~TextTransformationDescription
- * @property {String|RegExp} from The string or RegExp to transform.
- * @property {String} to The text to transform compatible with `String.replace()`
+ * @property {String|RegExp} from The string or regular expression to transform.
+ * @property {String} to The text to transform compatible with `String.replace()`.
  */
 
 /**
@@ -316,16 +317,16 @@ function expandGroupsAndRemoveDuplicates( definitions ) {
  * - `registeredTrademark`: transforms `(r)` to `®`
  * - `copyright`: transforms `(c)` to `©`
  * * Mathematical (group name: `mathematical`)
- * - `oneHalf`: transforms `1/2`, to: `½`
- * - `oneThird`: transforms `1/3`, to: `⅓`
- * - `twoThirds`: transforms `2/3`, to: `⅔`
- * - `oneForth`: transforms `1/4`, to: `¼`
- * - `threeQuarters`: transforms `3/4`, to: `¾`
- * - `lessThanOrEqual`: transforms `<=`, to: `≤`
- * - `greaterThanOrEqual`: transforms `>=`, to: `≥`
- * - `notEqual`: transforms `!=`, to: `≠`
- * - `arrowLeft`: transforms `<-`, to: `←`
- * - `arrowRight`: transforms `->`, to: `→`
+ * - `oneHalf`: transforms `1/2` to: `½`
+ * - `oneThird`: transforms `1/3` to: `⅓`
+ * - `twoThirds`: transforms `2/3` to: `⅔`
+ * - `oneForth`: transforms `1/4` to: `¼`
+ * - `threeQuarters`: transforms `3/4` to: `¾`
+ * - `lessThanOrEqual`: transforms `<=` to: `≤`
+ * - `greaterThanOrEqual`: transforms `>=` to: `≥`
+ * - `notEqual`: transforms `!=` to: `≠`
+ * - `arrowLeft`: transforms `<-` to: `←`
+ * - `arrowRight`: transforms `->` to: `→`
  * * Misc:
  * - `quotesPrimaryEnGb`: transforms `'Foo bar'` to `‘Foo bar’`
  * - `quotesSecondaryEnGb`: transforms `"Foo bar"` to `“Foo bar”`
@@ -365,16 +366,16 @@ function expandGroupsAndRemoveDuplicates( definitions ) {
 /* eslint-disable max-len */
 /**
  * The standard list of text transformations supported by the editor. By default it comes pre-configured with a couple dozen of them
- * (see {@link module:typing/texttransformation~TextTransformationConfig} for the full list of them). You can override this list completely
+ * (see {@link module:typing/texttransformation~TextTransformationConfig} for the full list). You can override this list completely
  * by setting this option or use the other two options
  * ({@link module:typing/texttransformation~TextTransformationConfig#extra `transformations.extra`},
- * {@link module:typing/texttransformation~TextTransformationConfig#remove `transformations.remove`}) to fine tune the default list.
+ * {@link module:typing/texttransformation~TextTransformationConfig#remove `transformations.remove`}) to fine-tune the default list.
  *
  * @member {Array.<module:typing/texttransformation~TextTransformationDescription>} module:typing/texttransformation~TextTransformationConfig#include
  */
 
 /**
- * The extra text transformations that are added to the transformations defined in
+ * Additional text transformations that are added to the transformations defined in
  * {@link module:typing/texttransformation~TextTransformationConfig#include `transformations.include`}.
  *
  * const transformationsConfig = {
@@ -387,14 +388,14 @@ function expandGroupsAndRemoveDuplicates( definitions ) {
  */
 
 /**
- * The text transformations names that are removed from transformations defined in
+ * The text transformation names that are removed from transformations defined in
  * {@link module:typing/texttransformation~TextTransformationConfig#include `transformations.include`} or
  * {@link module:typing/texttransformation~TextTransformationConfig#extra `transformations.extra`}.
  *
  * const transformationsConfig = {
  * remove: [
- * 'ellipsis', // Remove only 'ellipsis' from 'typography' group.
- * 'mathematical' // Remove all transformations from 'mathematical' group.
+ * 'ellipsis', // Remove only 'ellipsis' from the 'typography' group.
+ * 'mathematical' // Remove all transformations from the 'mathematical' group.
  * ]
  * }
  *

src/textwatcher.js

@@ -13,7 +13,7 @@ import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
 /**
  * The text watcher feature.
  *
- * Fires {@link module:typing/textwatcher~TextWatcher#event:matched:data `matched:data`},
+ * Fires the {@link module:typing/textwatcher~TextWatcher#event:matched:data `matched:data`},
  * {@link module:typing/textwatcher~TextWatcher#event:matched:selection `matched:selection`} and
  * {@link module:typing/textwatcher~TextWatcher#event:unmatched `unmatched`} events on typing or selection changes.
  *
@@ -78,7 +78,7 @@ export default class TextWatcher {
  * @fires unmatched
  *
  * @private
- * @param {'data'|'selection'} suffix Suffix used for generating event name.
+ * @param {'data'|'selection'} suffix A suffix used for generating the event name.
  * @param {Object} data Data object for event.
  */
  _evaluateTextBeforeSelection( suffix, data = {} ) {