8
0
فهرست منبع

Merge branch 'master' into t/6

Aleksander Nowodzinski 6 سال پیش
والد
کامیت
7311e17789

+ 3 - 3
packages/ckeditor5-word-count/README.md

@@ -1,4 +1,4 @@
-CKEditor 5 word count feature
+CKEditor 5 word count and character count feature
 ===========================
 
 [![Join the chat at https://gitter.im/ckeditor/ckeditor5](https://badges.gitter.im/ckeditor/ckeditor5.svg)](https://gitter.im/ckeditor/ckeditor5?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
@@ -10,11 +10,11 @@ CKEditor 5 word count feature
 [![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-word-count/status.svg)](https://david-dm.org/ckeditor/ckeditor5-word-count)
 [![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-word-count/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-word-count?type=dev)
 
-This package implements word count support for CKEditor 5.
+This package implements word count and character count support for CKEditor 5.
 
 ## Demo
 
-Check out the demo in the [Word count feature](https://ckeditor.com/docs/ckeditor5/latest/features/word-count.html) guide.
+Check out the demo in the [Word count and character count feature](https://ckeditor.com/docs/ckeditor5/latest/features/word-count.html) guide.
 
 ## Documentation
 

+ 3 - 3
packages/ckeditor5-word-count/docs/_snippets/features/word-count-update.html

@@ -1,7 +1,7 @@
 
 <style>
 	.customized-count__color-box {
-		--hue: 180;
+		--hue: 56;
 		width: 20px;
 		height: 20px;
 		background-color: hsl( var( --hue ), 100%, 50% );
@@ -21,13 +21,13 @@
 </style>
 
 <div id="demo-editor-update">
-		<p>A <strong>black hole</strong> is a region of <a href="https://en.wikipedia.org/wiki/Spacetime">spacetime</a> exhibiting <a href="https://en.wikipedia.org/wiki/Gravitation">gravitational</a> acceleration so strong that nothing—no <a href="https://en.wikipedia.org/wiki/Particle">particles</a> or even <a href="https://en.wikipedia.org/wiki/Electromagnetic_radiation">electromagnetic radiation</a> such as <a href="https://en.wikipedia.org/wiki/Light">light</a>—can escape from it.<a href="https://en.wikipedia.org/wiki/Black_hole#cite_note-6">[6]</a> The theory of <a href="https://en.wikipedia.org/wiki/General_relativity">general relativity</a> predicts that a sufficiently compact <a href="https://en.wikipedia.org/wiki/Mass">mass</a> can deform <a href="https://en.wikipedia.org/wiki/Spacetime">spacetime</a> to form a black hole.</p>
+	<p>Tourists frequently admit that <a href="https://en.wikipedia.org/wiki/Taj_Mahal">Taj Mahal</a> “simply cannot be described with words”.</p>
 </div>
 <div class="word-count customized-count">
 	<div class="customized-count__words">
 		<label>
 			<span>Words:</span>
-			<progress value="42" max="100"></progress>
+			<progress value="12" max="20"></progress>
 		</label>
 	</div>
 	<div class="customized-count__characters">

+ 24 - 4
packages/ckeditor5-word-count/docs/_snippets/features/word-count-update.js

@@ -36,11 +36,31 @@ ClassicEditor
 		const progressBar = document.querySelector( '.customized-count progress' );
 		const colorBox = document.querySelector( '.customized-count__color-box' );
 
-		wordCountPlugin.on( 'update', updateHandler );
+		wordCountPlugin.on( 'update', ( evt, data ) => {
+			const charactersHue = calculateHue( {
+				characters: data.characters,
+				greenUntil: 70,
+				maxCharacters: 120
+			} );
 
-		function updateHandler( evt, payload ) {
-			progressBar.value = payload.words;
-			colorBox.style.setProperty( '--hue', payload.characters * 3 );
+			progressBar.value = data.words;
+			colorBox.style.setProperty( '--hue', charactersHue );
+		} );
+
+		// Calculates the hue based on the number of characters.
+		//
+		// For the character counter:
+		//
+		// * below greenUntil - Returns green.
+		// * between greenUntil and maxCharacters - Returns a hue between green and red.
+		// * above maxCharacters - Returns red.
+		function calculateHue( { characters, greenUntil, maxCharacters } ) {
+			const greenHue = 70;
+			const redHue = 0;
+			const progress = Math.max( 0, Math.min( 1, ( characters - greenUntil ) / ( maxCharacters - greenUntil ) ) ); // 0-1
+			const discreetProgress = Math.floor( progress * 10 ) / 10; // 0, 0.1, 0.2, ..., 1
+
+			return ( redHue - greenHue ) * discreetProgress + greenHue;
 		}
 	} )
 	.catch( err => {

+ 2 - 2
packages/ckeditor5-word-count/docs/_snippets/features/word-count.html

@@ -8,8 +8,8 @@
 	}
 </style>
 <div id="demo-editor">
-	<p>The <strong>Battle of Westerplatte</strong> was one of the first battles in Germany's <a href="https://en.wikipedia.org/wiki/Invasion_of_Poland">invasion of Poland</a>, marking the start of <a href="https://en.wikipedia.org/wiki/World_War_II">World War II</a> in <a href="https://en.wikipedia.org/wiki/Europe">Europe</a>. Beginning on 1 September 1939, <a href="https://en.wikipedia.org/wiki/Nazi_Germany">German</a> <a href="https://en.wikipedia.org/wiki/German_Army_(Wehrmacht)">army</a>, <a href="https://en.wikipedia.org/wiki/Kriegsmarine">naval</a> and <a href="https://en.wikipedia.org/wiki/Luftwaffe">air forces</a> and <a href="https://en.wikipedia.org/wiki/Free_City_of_Danzig_Police">Danzig police</a> assaulted <a href="https://en.wikipedia.org/wiki/Poland">Poland</a>'s Military Transit Depot (<i>Wojskowa Składnica Tranzytowa</i>, or <i>WST</i>) on the <a href="https://en.wikipedia.org/wiki/Westerplatte">Westerplatte</a> peninsula in the harbor of the <a href="https://en.wikipedia.org/wiki/Free_City_of_Danzig">Free City of Danzig</a>. The Poles held out for seven days and repelled 13 assaults that included <a href="https://en.wikipedia.org/wiki/Dive_bomber">dive-bomber</a> attacks and naval shelling.</p>
-	<p>Westerplatte's defense served as an inspiration for the <a href="https://en.wikipedia.org/wiki/Polish_Army">Polish Army</a> and people in the face of German advances elsewhere, and is still regarded as a symbol of resistance in modern Poland.</p>
+	<p><strong>Taj Mahal</strong> is a mausoleum built in Agra between 1631 and 1648 by Emperor Shah Jahan in the memory of his beloved wife, Mumtaz Mahal, whose body lies there. It took 20 000 workers to complete and the excellence of this building is visible in every brick.</p>
+	<p>In 1983, Taj Mahal was appointed <a href="https://en.wikipedia.org/wiki/World_Heritage_Site">UNESCO World Heritage Site</a> for being “the jewel of Muslim art in India and one of the universally admired masterpieces of the world's heritage”.</p>
 </div>
 <div id="demo-word-count" class="word-count">
 </div>

+ 4 - 4
packages/ckeditor5-word-count/docs/api/word-count.md

@@ -2,19 +2,19 @@
 category: api-reference
 ---
 
-# Word count feature for CKEditor 5
+# Word count and character count feature for CKEditor 5
 
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-word-count.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-word-count)
 
-This package implements the word count feature for CKEditor 5. You can use it to obtain amount of words and/or characters from the editor.
+This package implements the word count and character count features for CKEditor 5. You can use it to obtain the number of words or characters from the editor.
 
 ## Demo
 
-Check out the {@link features/word-count#demo demo in the Word count feature} guide.
+Check out the {@link features/word-count#demo demo in the Word count and character count feature} guide.
 
 ## Documentation
 
-See the {@link features/word-count Word count feature} guide and the {@link module:word-count/wordcount~WordCount} plugin documentation.
+See the {@link features/word-count Word count and character count feature} guide and the {@link module:word-count/wordcount~WordCount} plugin documentation.
 
 ## Installation
 

+ 97 - 15
packages/ckeditor5-word-count/docs/features/word-count.md

@@ -1,25 +1,29 @@
 ---
 category: features
+menu-title: Word and character count
 ---
 
 {@snippet features/build-word-count-source}
 
-# Word count
+# Word count and character count
 
-The {@link module:word-count/wordcount~WordCount} feature provides a possibility to track the number of words and characters written in the editor.
+The {@link module:word-count/wordcount~WordCount} feature provides a possibility to track the number of words and characters written in the rich-text editor.
 
 ## Demo
 
 {@snippet features/word-count}
 
+The example above was created by using the following HTML page structure:
+
 ```html
 <div id="editor">
 	<p>Hello world.</p>
 </div>
-<div id="word-count">
-</div>
+<div id="word-count"></div>
 ```
 
+You can use the code below to set up the WYSIWYG editor with the word and character count features as in the example above.
+
 ```js
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
@@ -34,36 +38,112 @@ ClassicEditor
 	.catch( ... );
 ```
 
-## Configuration options
+## Configuration
+
+The word count and character count feature is quite flexible and there are a few configuration options available.
+
+### Configuring the container
+
+There are two ways how you can inject the word count statistics into your page:
+
+* By using the {@link module:word-count/wordcount~WordCount#wordCountContainer `WordCount#wordCountContainer`} property as shown in the example above.
+* Or, by specifying where the word count feature should insert its container which can be done by using {@link module:word-count/wordcount~WordCountConfig#container `config.wordCount.container`}.
+
+The word count plugin renders its output as:
+
+```html
+<div class="ck ck-word-count">
+	<div class="ck-word-count__words">Words: %%</div>
+	<div class="ck-word-count__characters">Characters: %%</div>
+</div>
+```
 
-There are two options which change the output container. If the {@link module:word-count/wordcount~WordCountConfig#displayWords} is set to to `false`, then the section with word count is hidden. Similarly, when the {@link module:word-count/wordcount~WordCountConfig#displayCharacters} is set to `false` it will hide the character counter.
+If you wish to render the statistics differently, see the [`update` event](#the-update-event).
 
-## Update event
+### Changing the output
 
-Word count feature emits an {@link module:word-count/wordcount~WordCount#event:update update event} whenever there is a change in the model. This allows implementing customized behavior that reacts to word count updates.
+There are two configuration options available that change the output of the word count and character count features:
 
-Below you can find an example, where the background color of a square is changed according to the number of characters in the editor. There is also a progress bar which indicates how many words is in it (the maximal value of the progress bar is set to 100, however, you can write further and progress bar remain in the maximal state).
+* If the {@link module:word-count/wordcount~WordCountConfig#displayWords `config.wordCount.displayWords`} option is set to `false`, the word counter will be hidden.
+* If the {@link module:word-count/wordcount~WordCountConfig#displayCharacters `config.wordCount.displayCharacters`} option is set to `false`, the character counter will be hidden.
+
+## The `update` event
+
+The {@link module:word-count/wordcount~WordCount WordCount} plugin emits the {@link module:word-count/wordcount~WordCount#event:update `WordCount#update` event}. It allows implementing customized behaviors that react to word and character count updates.
+
+Below you can find an example where the color of the circle goes from green to red as you approach the limit of 120 characters. The progress bar indicates the number of words.
 
 {@snippet features/word-count-update}
 
 ```js
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
-		// configuration details
+		// Configuration details.
 	} )
 	.then( editor => {
 		const wordCountPlugin = editor.plugins.get( 'WordCount' );
 
+		const progressBar = document.querySelector( '.word-count progress' );
+		const colorBox = document.querySelector( '.word-count__color-box' );
+
 		wordCountPlugin.on( 'update', ( evt, data ) => {
-			// data is an object with "words" and "characters" field
-			doSthWithNewWordsNumber( data.words );
-			doSthWithNewCharactersNumber( data.characters );
+			const charactersHue = calculateHue( {
+				characters: data.characters,
+				greenUntil: 70,
+				maxCharacters: 120
+			} );
+
+			progressBar.value = data.words;
+			colorBox.style.setProperty( '--hue', charactersHue );
 		} );
 
+		// Calculates the hue based on the number of characters.
+		//
+		// For the character counter:
+		//
+		// * below greenUntil - Returns green.
+		// * between greenUntil and maxCharacters - Returns a hue between green and red.
+		// * above maxCharacters - Returns red.
+		function calculateHue( { characters, greenUntil, maxCharacters } ) {
+			const greenHue = 70;
+			const redHue = 0;
+			const progress = Math.max( 0, Math.min( 1, ( characters - greenUntil ) / ( maxCharacters - greenUntil ) ) ); // 0-1
+			const discreetProgress = Math.floor( progress * 10 ) / 10; // 0, 0.1, 0.2, ..., 1
+
+			return ( redHue - greenHue ) * discreetProgress + greenHue;
+		}
 	} )
 	.catch( ... );
 ```
 
+The HTML structure used to create the customized word and character count implementation above:
+
+```html
+<style>
+	.word-count__color-box {
+		width: 20px;
+		height: 20px;
+		background-color: hsl( var( --hue ), 100%, 50% );
+		display: inline-block;
+		vertical-align: middle;
+		border-radius: 100%;
+	}
+</style>
+
+<div class="word-count">
+	<div class="word-count__words">
+		<label>
+			<span>Words:</span>
+			<progress max="20"></progress>
+		</label>
+	</div>
+	<div class="word-count__characters">
+		<span>Characters:</span>
+		<div class="word-count__color-box"></div>
+	</div>
+</div>
+```
+
 ## Installation
 
 To add this feature to your rich-text editor, install the [`@ckeditor/ckeditor5-word-count`](https://www.npmjs.com/package/@ckeditor/ckeditor5-word-count) package:
@@ -92,8 +172,10 @@ ClassicEditor
 ## Common API
 
 The {@link module:word-count/wordcount~WordCount} plugin provides:
-  * {@link module:word-count/wordcount~WordCount#wordCountContainer} getter. It returns a self-updating HTML element which is updated with the current number of words and characters in the editor. There is a possibility to remove "Words" or "Characters" counters with proper configuration of {@link module:word-count/wordcount~WordCountConfig#displayWords} and {@link module:word-count/wordcount~WordCountConfig#displayCharacters},
-  * {@link module:word-count/wordcount~WordCount#event:update update event} which is fired whenever the plugins update the number of counted words and characters. There is a possibility to run own callback function with updated values. Please note that update event is throttled.
+
+* The {@link module:word-count/wordcount~WordCount#wordCountContainer} property. It returns a self-updating HTML element which is updated with the current number of words and characters in the editor. You can remove the "Words" or "Characters" counters with a proper configuration of the {@link module:word-count/wordcount~WordCountConfig#displayWords `config.wordCount.displayWords`} and {@link module:word-count/wordcount~WordCountConfig#displayCharacters `config.wordCount.displayCharacters`} options.
+* The {@link module:word-count/wordcount~WordCount#event:update `update` event}, fired whenever the plugins update the number of counted words and characters. You can run a custom callback function with updated values. Please note that the `update` event is throttled.
+* The {@link module:word-count/wordcount~WordCount#characters} and {@link module:word-count/wordcount~WordCount#words} properties from which you can retrieve the stats at any moment.
 
 <info-box>
 	We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

+ 1 - 1
packages/ckeditor5-word-count/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ckeditor/ckeditor5-word-count",
   "version": "10.0.1",
-  "description": "Word count feature for CKEditor 5.",
+  "description": "Word count and character count features for CKEditor 5.",
   "keywords": [
     "ckeditor",
     "ckeditor5",

+ 1 - 1
packages/ckeditor5-word-count/src/utils.js

@@ -11,7 +11,7 @@
  * Returns a plain text representation of an element and its children.
  *
  * @param {module:engine/model/element~Element} element
- * @returns {String} Plain text representing model's data
+ * @returns {String} Plain text representing the model's data.
  */
 export function modelElementToPlainText( element ) {
 	if ( element.is( 'text' ) || element.is( 'textProxy' ) ) {

+ 27 - 27
packages/ckeditor5-word-count/src/wordcount.js

@@ -18,13 +18,13 @@ import env from '@ckeditor/ckeditor5-utils/src/env';
  * The word count plugin.
  *
  * This plugin calculates all words and characters in all {@link module:engine/model/text~Text text nodes} available in the model.
- * It also provides an HTML element, which updates its states whenever the editor's content is changed.
+ * It also provides an HTML element that updates its state whenever the editor content is changed.
  *
- * Firstly model's data are convert to plain text using {@link module:word-count/utils.modelElementToPlainText}.
- * Based on such created plain text there are determined amount of words and characters in your text. Please keep in mind
- * that every block in the editor is separate with a newline character, which is included in the calculation.
+ * The model's data is first converted to plain text using {@link module:word-count/utils.modelElementToPlainText}.
+ * The number of words and characters in your text are determined based on the created plain text. Please keep in mind
+ * that every block in the editor is separated with a newline character, which is included in the calculation.
  *
- * Few examples of how word and character calculation are made:
+ * Here are some examples of how the word and character calculations are made:
  *
  * 		<paragraph>foo</paragraph>
  * 		<paragraph>bar</paragraph>
@@ -86,7 +86,7 @@ export default class WordCount extends Plugin {
 		} );
 
 		/**
-		 * Label used to display words value in {@link #wordCountContainer output container}
+		 * The label used to display the words value in the {@link #wordCountContainer output container}.
 		 *
 		 * @observable
 		 * @private
@@ -96,7 +96,7 @@ export default class WordCount extends Plugin {
 		this.set( '_wordsLabel' );
 
 		/**
-		 * Label used to display characters value in {@link #wordCountContainer output container}
+		 * The label used to display the characters value in the {@link #wordCountContainer output container}.
 		 *
 		 * @observable
 		 * @private
@@ -106,7 +106,7 @@ export default class WordCount extends Plugin {
 		this.set( '_charactersLabel' );
 
 		/**
-		 * The configuration of this plugins.
+		 * The configuration of this plugin.
 		 *
 		 * @private
 		 * @type {Object}
@@ -114,7 +114,7 @@ export default class WordCount extends Plugin {
 		this._config = editor.config.get( 'wordCount' ) || {};
 
 		/**
-		 * A reference to a {@link module:ui/view~View view object} which contains self-updating HTML container.
+		 * The reference to a {@link module:ui/view~View view object} that contains the self-updating HTML container.
 		 *
 		 * @private
 		 * @readonly
@@ -180,8 +180,8 @@ export default class WordCount extends Plugin {
 	}
 
 	/**
-	 * Creates self-updated HTML element. Repeated executions return the same element.
-	 * Returned element has followed HTML structure:
+	 * Creates a self-updating HTML element. Repeated executions return the same element.
+	 * The returned element has the following HTML structure:
 	 *
 	 * 		<div class="ck ck-word-count">
 	 * 			<div class="ck-word-count__words">Words: 4</div>
@@ -298,12 +298,12 @@ export default class WordCount extends Plugin {
 }
 
 /**
- * Event fired after {@link #words} and {@link #characters} are updated.
+ * An event fired after {@link #words} and {@link #characters} are updated.
  *
  * @event update
  * @param {Object} data
- * @param {Number} data.words number of words in current model
- * @param {Number} data.characters number of characters in current model
+ * @param {Number} data.words The number of words in the current model.
+ * @param {Number} data.characters The number of characters in the current model.
  */
 
 /**
@@ -331,15 +331,15 @@ export default class WordCount extends Plugin {
  */
 
 /**
- * This option allows for hiding the word count. The element obtained through
+ * This option allows for hiding the word counter. The element obtained through
  * {@link module:word-count/wordcount~WordCount#wordCountContainer} will only preserve
- * the characters part. word count is displayed by default when this configuration option is not defined.
+ * the characters part. Word counter is displayed by default when this configuration option is not defined.
  *
  *		const wordCountConfig = {
  *			displayWords: false
- *		}
+ *		};
  *
- * The mentioned configuration will result with the followed container:
+ * The configuration above will result in the following container:
  *
  *		<div class="ck ck-word-count">
  *			<div class="ck-word-count__characters">Characters: 28</div>
@@ -355,9 +355,9 @@ export default class WordCount extends Plugin {
  *
  *		const wordCountConfig = {
  *			displayCharacters: false
- *		}
+ *		};
  *
- * The mentioned configuration will result in the following container
+ * The configuration above will result in the following container:
  *
  *		<div class="ck ck-word-count">
  *			<div class="ck-word-count__words">Words: 4</div>
@@ -367,27 +367,27 @@ export default class WordCount extends Plugin {
  */
 
 /**
- * This configuration takes a function, which is executed whenever the word-count plugin updates its values.
- * This function is called with one argument, which is an object with `words` and `characters` keys containing
- * a number of detected words and characters in the document.
+ * This configuration takes a function that is executed whenever the word count plugin updates its values.
+ * This function is called with one argument, which is an object with the `words` and `characters` keys containing
+ * the number of detected words and characters in the document.
  *
  *		const wordCountConfig = {
  *			onUpdate: function( stats ) {
  *				doSthWithWordNumber( stats.words );
  *				doSthWithCharacterNumber( stats.characters );
  *			}
- *		}
+ *		};
  *
  * @member {Function} module:word-count/wordcount~WordCountConfig#onUpdate
  */
 
 /**
- * This option allows on providing an HTML element where
- * {@link module:word-count/wordcount~WordCount#wordCountContainer word count container} will be appended automatically.
+ * Allows for providing the HTML element that the
+ * {@link module:word-count/wordcount~WordCount#wordCountContainer word count container} will be appended to automatically.
  *
  *		const wordCountConfig = {
  *			container: document.getElementById( 'container-for-word-count' );
- *		}
+ *		};
  *
  * @member {HTMLElement} module:word-count/wordcount~WordCountConfig#container
  */