@ckeditor/ckeditor5-utils 35.3.2 → 35.4.0

package/src/translation-service.js

@@ -22,70 +22,80 @@ if (!global.window.CKEDITOR_TRANSLATIONS) {
  * Since the editor displays only the message string, the message ID can be found either in the source code or in the
  * built translations for another language.
  *
- *		add( 'pl', {
- *			'Cancel': 'Anuluj',
- *			'IMAGE': 'obraz', // Note that the `IMAGE` comes from the message ID, while the string can be `image`.
- *		} );
+ * ```ts
+ * add( 'pl', {
+ * 	'Cancel': 'Anuluj',
+ * 	'IMAGE': 'obraz', // Note that the `IMAGE` comes from the message ID, while the string can be `image`.
+ * } );
+ * ```
  *
  * If the message is supposed to support various plural forms, make sure to provide an array with the singular form and all plural forms:
  *
- *		add( 'pl', {
- *	 		'Add space': [ 'Dodaj spację', 'Dodaj %0 spacje', 'Dodaj %0 spacji' ]
- * 		} );
+ * ```ts
+ * add( 'pl', {
+ * 	'Add space': [ 'Dodaj spację', 'Dodaj %0 spacje', 'Dodaj %0 spacji' ]
+ * } );
+ * ```
  *
  * You should also specify the third argument (the `getPluralForm()` function) that will be used to determine the plural form if no
  * language file was loaded for that language. All language files coming from CKEditor 5 sources will have this option set, so
  * these plural form rules will be reused by other translations added to the registered languages. The `getPluralForm()` function
  * can return either a Boolean or a number.
  *
- * 		add( 'en', {
- *	 		// ... Translations.
- * 		}, n => n !== 1 );
- * 		add( 'pl', {
- *	 		// ... Translations.
- * 		}, n => n == 1 ? 0 : n % 10 >= 2 && n % 10 <= 4 && ( n % 100 < 10 || n % 100 >= 20 ) ? 1 : 2 );
+ * ```ts
+ * add( 'en', {
+ * 	// ... Translations.
+ * }, n => n !== 1 );
+ * add( 'pl', {
+ * 	// ... Translations.
+ * }, n => n == 1 ? 0 : n % 10 >= 2 && n % 10 <= 4 && ( n % 100 < 10 || n % 100 >= 20 ) ? 1 : 2 );
+ * ```
  *
  * All translations extend the global `window.CKEDITOR_TRANSLATIONS` object. An example of this object can be found below:
  *
- * 		{
- * 			pl: {
- *				dictionary: {
- *					'Cancel': 'Anuluj',
- *					'Add space': [ 'Dodaj spację', 'Dodaj %0 spacje', 'Dodaj %0 spacji' ]
- *				},
- *				// A function that returns the plural form index.
- *				getPluralForm: n => n !==1
- *			}
- *			// Other languages.
- *		}
+ * ```ts
+ * {
+ * 	pl: {
+ * 		dictionary: {
+ * 			'Cancel': 'Anuluj',
+ * 			'Add space': [ 'Dodaj spację', 'Dodaj %0 spacje', 'Dodaj %0 spacji' ]
+ * 		},
+ * 		// A function that returns the plural form index.
+ * 		getPluralForm: n => n == 1 ? 0 : n % 10 >= 2 && n % 10 <= 4 && ( n % 100 < 10 || n % 100 >= 20 ) ? 1 : 2 );
+ * 	}
+ * 	// Other languages.
+ * 	}
+ * ```
  *
  * If you cannot import this function from this module (e.g. because you use a CKEditor 5 build), you can
  * still add translations by extending the global `window.CKEDITOR_TRANSLATIONS` object by using a function like
  * the one below:
  *
- *		function addTranslations( language, translations, getPluralForm ) {
- *			if ( !global.window.CKEDITOR_TRANSLATIONS ) {
- *				global.window.CKEDITOR_TRANSLATIONS = {};
- *			}
+ * ```ts
+ * function addTranslations( language, translations, getPluralForm ) {
+ * 	if ( !global.window.CKEDITOR_TRANSLATIONS ) {
+ * 		global.window.CKEDITOR_TRANSLATIONS = {};
+ * 	}
 
- *			if ( !global.window.CKEDITOR_TRANSLATIONS[ language ] ) {
- *				global.window.CKEDITOR_TRANSLATIONS[ language ] = {};
- *			}
+ * 	if ( !global.window.CKEDITOR_TRANSLATIONS[ language ] ) {
+ * 		global.window.CKEDITOR_TRANSLATIONS[ language ] = {};
+ * 	}
  *
- *			const languageTranslations = global.window.CKEDITOR_TRANSLATIONS[ language ];
+ * 	const languageTranslations = global.window.CKEDITOR_TRANSLATIONS[ language ];
  *
- * 			languageTranslations.dictionary = languageTranslations.dictionary || {};
- * 			languageTranslations.getPluralForm = getPluralForm || languageTranslations.getPluralForm;
+ * 	languageTranslations.dictionary = languageTranslations.dictionary || {};
+ * 	languageTranslations.getPluralForm = getPluralForm || languageTranslations.getPluralForm;
  *
- *			// Extend the dictionary for the given language.
- *			Object.assign( languageTranslations.dictionary, translations );
- *		}
+ * 	// Extend the dictionary for the given language.
+ * 	Object.assign( languageTranslations.dictionary, translations );
+ * }
+ * ```
  *
- * @param {String} language Target language.
- * @param {Object.<String,*>} translations An object with translations which will be added to the dictionary.
+ * @param language Target language.
+ * @param translations An object with translations which will be added to the dictionary.
  * For each message ID the value should be either a translation or an array of translations if the message
  * should support plural forms.
- * @param {Function} [getPluralForm] A function that returns the plural form index (a number).
+ * @param getPluralForm A function that returns the plural form index (a number).
  */
 export function add(language, translations, getPluralForm) {
     if (!global.window.CKEDITOR_TRANSLATIONS[language]) {
@@ -107,25 +117,31 @@ export function add(language, translations, getPluralForm) {
  * When no translation is defined in the dictionary or the dictionary does not exist, this function returns
  * the original message string or the message plural depending on the number of elements.
  *
- *		translate( 'pl', { string: 'Cancel' } ); // 'Cancel'
+ * ```ts
+ * translate( 'pl', { string: 'Cancel' } ); // 'Cancel'
+ * ```
  *
  * The third optional argument is the number of elements, based on which the single form or one of the plural forms
  * should be picked when the message is supposed to support various plural forms.
  *
- * 		translate( 'en', { string: 'Add a space', plural: 'Add %0 spaces' }, 1 ); // 'Add a space'
- * 		translate( 'en', { string: 'Add a space', plural: 'Add %0 spaces' }, 3 ); // 'Add %0 spaces'
+ * ```ts
+ * translate( 'en', { string: 'Add a space', plural: 'Add %0 spaces' }, 1 ); // 'Add a space'
+ * translate( 'en', { string: 'Add a space', plural: 'Add %0 spaces' }, 3 ); // 'Add %0 spaces'
+ * ```
  *
  * The message should provide an ID using the `id` property when the message strings are not unique and their
  * translations should be different.
  *
- *		translate( 'en', { string: 'image', id: 'ADD_IMAGE' } );
- *		translate( 'en', { string: 'image', id: 'AN_IMAGE' } );
+ * ```ts
+ * translate( 'en', { string: 'image', id: 'ADD_IMAGE' } );
+ * translate( 'en', { string: 'image', id: 'AN_IMAGE' } );
+ * ```
  *
- * @protected
- * @param {String} language Target language.
- * @param {module:utils/translation-service~Message} message A message that will be translated.
- * @param {Number} [quantity] The number of elements for which a plural form should be picked from the target language dictionary.
- * @returns {String} Translated sentence.
+ * @internal
+ * @param language Target language.
+ * @param message A message that will be translated.
+ * @param quantity The number of elements for which a plural form should be picked from the target language dictionary.
+ * @returns Translated sentence.
  */
 export function _translate(language, message, quantity = 1) {
     if (typeof quantity !== 'number') {
@@ -165,12 +181,14 @@ export function _translate(language, message, quantity = 1) {
 /**
  * Clears dictionaries for test purposes.
  *
- * @protected
+ * @internal
  */
 export function _clear() {
     global.window.CKEDITOR_TRANSLATIONS = {};
 }
-// Checks whether the dictionary exists and translation in that dictionary exists.
+/**
+ * Checks whether the dictionary exists and translation in that dictionary exists.
+ */
 function hasTranslation(language, messageId) {
     return (!!global.window.CKEDITOR_TRANSLATIONS[language] &&
         !!global.window.CKEDITOR_TRANSLATIONS[language].dictionary[messageId]);

package/src/uid.js

@@ -5,8 +5,10 @@
 /**
  * @module utils/uid
  */
-// A hash table of hex numbers to avoid using toString() in uid() which is costly.
-// [ '00', '01', '02', ..., 'fe', 'ff' ]
+/**
+ * A hash table of hex numbers to avoid using toString() in uid() which is costly.
+ * [ '00', '01', '02', ..., 'fe', 'ff' ]
+ */
 const HEX_NUMBERS = new Array(256).fill('')
     .map((_, index) => ('0' + (index).toString(16)).slice(-2));
 /**
@@ -17,7 +19,7 @@ const HEX_NUMBERS = new Array(256).fill('')
  * (from "0" to "9", from "a" to "f"). In other words, each id corresponds to an "e" followed
  * by 16 8-bit numbers next to each other.
  *
- * @returns {String} An unique id string.
+ * @returns An unique id string.
  */
 export default function uid() {
     // Let's create some positive random 32bit integers first.

package/src/unicode.js

@@ -10,8 +10,7 @@
 /**
  * Checks whether given `character` is a combining mark.
  *
- * @param {String} character Character to check.
- * @returns {Boolean}
+ * @param character Character to check.
  */
 export function isCombiningMark(character) {
     // eslint-disable-next-line no-misleading-character-class
@@ -23,8 +22,7 @@ export function isCombiningMark(character) {
  * Using UTF-16 terminology, a surrogate pair denotes UTF-16 character using two UTF-8 characters. The surrogate pair
  * consist of high surrogate pair character followed by low surrogate pair character.
  *
- * @param {String} character Character to check.
- * @returns {Boolean}
+ * @param character Character to check.
  */
 export function isHighSurrogateHalf(character) {
     return !!character && character.length == 1 && /[\ud800-\udbff]/.test(character);
@@ -35,8 +33,7 @@ export function isHighSurrogateHalf(character) {
  * Using UTF-16 terminology, a surrogate pair denotes UTF-16 character using two UTF-8 characters. The surrogate pair
  * consist of high surrogate pair character followed by low surrogate pair character.
  *
- * @param {String} character Character to check.
- * @returns {Boolean}
+ * @param character Character to check.
  */
 export function isLowSurrogateHalf(character) {
     return !!character && character.length == 1 && /[\udc00-\udfff]/.test(character);
@@ -44,9 +41,8 @@ export function isLowSurrogateHalf(character) {
 /**
  * Checks whether given offset in a string is inside a surrogate pair (between two surrogate halves).
  *
- * @param {String} string String to check.
- * @param {Number} offset Offset to check.
- * @returns {Boolean}
+ * @param string String to check.
+ * @param offset Offset to check.
  */
 export function isInsideSurrogatePair(string, offset) {
     return isHighSurrogateHalf(string.charAt(offset - 1)) && isLowSurrogateHalf(string.charAt(offset));
@@ -54,9 +50,8 @@ export function isInsideSurrogatePair(string, offset) {
 /**
  * Checks whether given offset in a string is between base character and combining mark or between two combining marks.
  *
- * @param {String} string String to check.
- * @param {Number} offset Offset to check.
- * @returns {Boolean}
+ * @param string String to check.
+ * @param offset Offset to check.
  */
 export function isInsideCombinedSymbol(string, offset) {
     return isCombiningMark(string.charAt(offset));
@@ -65,9 +60,8 @@ const EMOJI_PATTERN = buildEmojiRegexp();
 /**
  * Checks whether given offset in a string is inside multi-character emoji sequence.
  *
- * @param {String} string String to check.
- * @param {Number} offset Offset to check.
- * @returns {Boolean}
+ * @param string String to check.
+ * @param offset Offset to check.
  */
 export function isInsideEmojiSequence(string, offset) {
     const matches = String(string).matchAll(EMOJI_PATTERN);

package/src/version.js

@@ -7,7 +7,7 @@
  */
 /* globals window, global */
 import CKEditorError from './ckeditorerror';
-const version = '35.3.2';
+const version = '35.4.0';
 export default version;
 /* istanbul ignore next */
 const windowOrGlobal = typeof window === 'object' ? window : global;
@@ -25,8 +25,10 @@ if (windowOrGlobal.CKEDITOR_VERSION) {
      *
      * If you import an existing CKEditor 5 build and a plugin like this:
      *
-     *		import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
-     *		import Highlight from '@ckeditor/ckeditor5-highlight/src/highlight';
+     * ```ts
+     * import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
+     * import Highlight from '@ckeditor/ckeditor5-highlight/src/highlight';
+     * ```
      *
      * Then your project loads some CKEditor 5 packages twice. How does it happen?
      *
@@ -54,32 +56,36 @@ if (windowOrGlobal.CKEDITOR_VERSION) {
      *
      * The correct way to do so is to import an editor and plugins and run them together like this:
      *
-     *		import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
-     *		import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
-     *		import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
-     *		import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
-     *		import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
-     *
-     *		ClassicEditor
-     *			.create( document.querySelector( '#editor' ), {
-     *				plugins: [ Essentials, Paragraph, Bold, Italic ],
-     *				toolbar: [ 'bold', 'italic' ]
-     *			} )
-     *			.then( editor => {
-     *				console.log( 'Editor was initialized', editor );
-     *			} )
-     *			.catch( error => {
-     *				console.error( error.stack );
-     *			} );
+     * ```ts
+     * import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
+     * import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
+     * import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
+     * import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
+     * import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
+     *
+     * ClassicEditor
+     * 	.create( document.querySelector( '#editor' ), {
+     * 		plugins: [ Essentials, Paragraph, Bold, Italic ],
+     * 		toolbar: [ 'bold', 'italic' ]
+     * 	} )
+     * 	.then( editor => {
+     * 		console.log( 'Editor was initialized', editor );
+     * 	} )
+     * 	.catch( error => {
+     * 		console.error( error.stack );
+     * 	} );
+     * ```
      *
      * However, you might have mistakenly imported a build instead of the source `ClassicEditor`. In this case
      * your imports will look like this:
      *
-     *		import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
-     *		import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
-     *		import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
-     *		import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
-     *		import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
+     * ```ts
+     * import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
+     * import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
+     * import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
+     * import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
+     * import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
+     * ```
      *
      * This creates the same situation as in the previous section because you use a build together with source plugins.
      *
@@ -117,7 +123,7 @@ if (windowOrGlobal.CKEDITOR_VERSION) {
      * **Note:** All official CKEditor 5 packages (excluding integrations and `ckeditor5-dev-*` packages) are released in the
      * same major version. This is — in the `x.y.z`, the `x` is the same for all packages. This is the simplest way to check
      * whether you use packages coming from the same CKEditor 5 version. You can read more about versioning in the
-     * {@glink support/versioning-policy Versioning policy} guide.
+     * {@glink updating/versioning-policy Versioning policy} guide.
      *
      * # Packages were duplicated in `node_modules`
      *