Sfoglia il codice sorgente

Merge branch 'master' into t/ckeditor5/1005

Piotrek Koszuliński 7 anni fa
parent
commit
2231b85c7b

+ 3 - 1
packages/ckeditor5-core/README.md

@@ -14,7 +14,9 @@ This package implements CKEditor 5's core editor architecture — a set of c
 
 ## Documentation
 
-See the [`@ckeditor/ckeditor5-core` package](https://docs.ckeditor.com/ckeditor5/latest/api/core.html) page in [CKEditor 5 documentation](https://docs.ckeditor.com/ckeditor5/latest/).
+For general introduction see the [Overview of CKEditor 5 framework](https://docs.ckeditor.com/ckeditor5/latest/framework/guides/overview.html) guide and then the [Core editor architecture](https://docs.ckeditor.com/ckeditor5/latest/framework/guides/architecture/core-editor-architecture.html) guide.
+
+Additionally, see the [`@ckeditor/ckeditor5-core` package](https://docs.ckeditor.com/ckeditor5/latest/api/core.html) page in [CKEditor 5 documentation](https://docs.ckeditor.com/ckeditor5/latest/) for even more information.
 
 ## License
 

+ 5 - 9
packages/ckeditor5-core/package.json

@@ -1,17 +1,14 @@
 {
   "name": "@ckeditor/ckeditor5-core",
   "version": "10.1.0",
-  "description": "CKEditor 5 core editor architecture.",
+  "description": "The core architecture of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "ckeditor5-lib",
-    "CKEditor",
+    "ckeditor",
     "ckeditor5",
     "ckeditor 5",
-    "WYSIWYG",
-    "WYSIWYM",
-    "text",
-    "rich-text",
-    "richtext",
+    "wysiwyg",
+    "rich text",
     "editor",
     "html",
     "contentEditable",
@@ -21,7 +18,6 @@
     "collaboration",
     "collaborative",
     "real-time",
-    "virtual dom",
     "framework"
   ],
   "dependencies": {
@@ -46,7 +42,7 @@
     "lint-staged": "^7.0.0"
   },
   "engines": {
-    "node": ">=6.0.0",
+    "node": ">=6.9.0",
     "npm": ">=3.0.0"
   },
   "author": "CKSource (http://cksource.com/)",

+ 9 - 9
packages/ckeditor5-core/src/editor/editorconfig.jsdoc

@@ -10,7 +10,7 @@
 /**
  * CKEditor configuration options.
  *
- * The object defining editor configuration can be passed when initializing the editor:
+ * An object defining the editor configuration can be passed when initializing the editor:
  *
  *		EditorClass
  *			.create( {
@@ -34,7 +34,7 @@
  * The list of plugins to load.
  *
  * If you use an {@glink builds/guides/overview editor build} you can define the list of plugins to load
- * using names of plugins which are available:
+ * using the names of plugins that are available:
  *
  *		const config = {
  *			plugins: [ 'Bold', 'Italic', 'Typing', 'Enter', ... ]
@@ -76,7 +76,7 @@
  */
 
 /**
- * Editor toolbar configuration.
+ * The editor toolbar configuration.
  *
  * Simple format (specifies only toolbar items):
  *
@@ -96,7 +96,7 @@
  *
  * Options which can be set using the extended format:
  *
- * * **`toolbar.items`** – Array of toolbar items names. The components (buttons, dropdowns, etc.) which can be used
+ * * **`toolbar.items`** – An array of toolbar item names. The components (buttons, dropdowns, etc.) which can be used
  * as toolbar items are defined in `editor.ui.componentFactory` and can be listed using the following snippet:
  *
  *		Array.from( editor.ui.componentFactory.names() );
@@ -105,20 +105,20 @@
  *
  *		toolbar: [ 'bold', 'italic', '|', 'undo', 'redo' ]
  *
- * * **`toolbar.viewportTopOffset`**  The offset (in pixels) from the top of the viewport used when positioning a sticky toolbar.
+ * * **`toolbar.viewportTopOffset`** – The offset (in pixels) from the top of the viewport used when positioning a sticky toolbar.
  * Useful when a page with which the editor is being integrated has some other sticky or fixed elements
- * (e.g. the top menu). Thanks to setting the toolbar offset the toolbar won't be positioned underneath or above the page's UI.
+ * (e.g. the top menu). Thanks to setting the toolbar offset the toolbar will not be positioned underneath or above the page's UI.
  *
  * @member {Array.<String>|Object} module:core/editor/editorconfig~EditorConfig#toolbar
  */
 
 /**
- * Editor UI's language.
+ * The editor UI's language.
  *
  * The language code is defined in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) standard.
  * CKEditor 5 currently supports around 20 languages and the number is growing.
  *
- * Note: You don't have to specify this option if your build is optimized for one language or if it's the default language
+ * Note: You do not have to specify this option if your build is optimized for one language or if it is the default language
  * (English is the default language for CDN builds).
  *
  * Simple usage:
@@ -134,7 +134,7 @@
  *				console.error( error );
  *			} );
  *
- * After this step you need to attach the corresponding translation file. Translation files are available at CDN for predefined builds:
+ * After this step you need to attach the corresponding translation file. Translation files are available on CDN for predefined builds:
  *		`<script src="https://cdn.ckeditor.com/ckeditor5/[version.number]/[distribution]/lang/[lang].js"></script>`
  *
  * But you can add them manually by coping from the `node_modules/@ckeditor/ckeditor5-build-[name]/build/lang/[lang].js'`.

+ 11 - 11
packages/ckeditor5-core/src/editor/editorwithui.jsdoc

@@ -11,34 +11,34 @@
  * Interface defining a type of {@link module:core/editor/editor~Editor editor} which has a UI.
  *
  * Most editors (like {@link module:editor-classic/classiceditor~ClassicEditor} or
- * {@link module:editor-inline/inlineeditor~InlineEditor}) implement this interface, however it is not required to do so.
+ * {@link module:editor-inline/inlineeditor~InlineEditor}) implement this interface, however, it is not required to do so.
  *
- * Editors with external UI (i.e. Bootstrap based) or headless editor may not implement this interface.
- * When developing editor features you can consider this by splitting them into two parts the "editing" part,
- * which bases on {@link module:core/editor/editor~Editor} itself and the UI part which bases on the this interface.
+ * Editors with an external UI (i.e. Bootstrap-based) or a headless editor may not implement this interface.
+ * When developing editor features you can consider this by splitting them into two parts: the "editing" part,
+ * which bases on {@link module:core/editor/editor~Editor} itself, and the UI part which bases on this interface.
  * This will make your features compatible with more types of editors.
  *
  * @interface EditorWithUI
  */
 
 /**
- * Editor UI instance.
+ * The editor UI instance.
  *
  * @readonly
  * @member {module:core/editor/editorui~EditorUI} #ui
  */
 
  /**
-  * The main (outermost) DOM element of the editor's UI.
+  * The main (outermost) DOM element of the editor UI.
   *
-  * For example, in the {@link module:editor-classic/classiceditor~ClassicEditor} it is a `<div>` which
-  * wraps the editable element and the toolbar. In the {@link module:editor-inline/inlineeditor~InlineEditor}
-  * it is the editable element itself (as there is no other wrapper). However, in the
+  * For example, in {@link module:editor-classic/classiceditor~ClassicEditor} it is a `<div>` which
+  * wraps the editable element and the toolbar. In {@link module:editor-inline/inlineeditor~InlineEditor}
+  * it is the editable element itself (as there is no other wrapper). However, in
   * {@link module:editor-decoupled/decouplededitor~DecoupledEditor} it is set to `null` because this editor does not
   * come with a single "main" HTML element (its editable element and toolbar are separate).
   *
-  * This property can be understood as a shorthand for retrieving the element which specific editor integration
-  * considers to be its main DOM element. There are always other ways to access these elements too
+  * This property can be understood as a shorthand for retrieving the element that a specific editor integration
+  * considers to be its main DOM element. There are always other ways to access these elements, too
   * (e.g. via {@link #ui `editor.ui`}).
   *
   * @readonly

+ 5 - 5
packages/ckeditor5-core/src/editor/utils/attachtoform.js

@@ -11,21 +11,21 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  */
 
 /**
- * Checks if editor is initialized on textarea element that belongs to a form. If yes - updates editor's element
- * contents before submitting the form.
+ * Checks if the editor is initialized on a `<textarea>` element that belongs to a form. If yes, it updates the editor's element
+ * content before submitting the form.
  *
- * This helper requires {@link module:core/editor/utils/elementapimixin~ElementApi ElementApi interface}.
+ * This helper requires the {@link module:core/editor/utils/elementapimixin~ElementApi ElementApi interface}.
  *
  * @param {module:core/editor/editor~Editor} editor Editor instance.
  */
 export default function attachToForm( editor ) {
 	if ( !isFunction( editor.updateSourceElement ) ) {
 		/**
-		 * {@link module:core/editor/utils/elementapimixin~ElementApi ElementApi interface} is required.
+		 * The {@link module:core/editor/utils/elementapimixin~ElementApi ElementApi interface} is required.
 		 *
 		 * @error attachtoform-missing-elementapi-interface
 		 */
-		throw new CKEditorError( 'attachtoform-missing-elementapi-interface: ElementApi interface is required.' );
+		throw new CKEditorError( 'attachtoform-missing-elementapi-interface: The ElementApi interface is required.' );
 	}
 
 	const sourceElement = editor.sourceElement;

+ 5 - 5
packages/ckeditor5-core/src/editor/utils/dataapimixin.js

@@ -32,11 +32,11 @@ const DataApiMixin = {
 export default DataApiMixin;
 
 /**
- * Interface defining an editor methods for setting and getting data to/from the editor's main root element
+ * Interface defining editor methods for setting and getting data to and from the editor's main root element
  * using the {@link module:core/editor/editor~Editor#data data pipeline}.
  *
- * This interface is not part of the {@link module:core/editor/editor~Editor} class because one may want to implement
- * an editor with multiple root elements, in which case the methods for setting/getting data will need to be implemented
+ * This interface is not a part of the {@link module:core/editor/editor~Editor} class because one may want to implement
+ * an editor with multiple root elements, in which case the methods for setting and getting data will need to be implemented
  * differently.
  *
  * @interface DataApi
@@ -48,7 +48,7 @@ export default DataApiMixin;
  *		editor.setData( '<p>This is editor!</p>' );
  *
  * By default the editor accepts HTML. This can be controlled by injecting a different data processor.
- * See {@glink features/markdown Markdown output} guide for more details.
+ * See the {@glink features/markdown Markdown output} guide for more details.
  *
  * Note: Not only is the format of the data configurable, but the type of the `setData()`'s parameter does not
  * have to be a string either. You can e.g. accept an object or a DOM `DocumentFragment` if you consider this
@@ -64,7 +64,7 @@ export default DataApiMixin;
  *		editor.getData(); // -> '<p>This is editor!</p>'
  *
  * By default the editor outputs HTML. This can be controlled by injecting a different data processor.
- * See {@glink features/markdown Markdown output} guide for more details.
+ * See the {@glink features/markdown Markdown output} guide for more details.
  *
  * Note: Not only is the format of the data configurable, but the type of the `getData()`'s return value does not
  * have to be a string either. You can e.g. return an object or a DOM `DocumentFragment`  if you consider this

+ 1 - 1
packages/ckeditor5-core/src/editor/utils/elementapimixin.js

@@ -40,7 +40,7 @@ const ElementApiMixin = {
 export default ElementApiMixin;
 
 /**
- * Interface describing an editor which replaced a DOM element (was "initialized on an element").
+ * Interface describing an editor that replaced a DOM element (was "initialized on an element").
  *
  * Such an editor should provide a method to
  * {@link module:core/editor/utils/elementapimixin~ElementApi#updateSourceElement update the replaced element with the current data}.

+ 11 - 13
packages/ckeditor5-core/src/plugincollection.js

@@ -83,11 +83,11 @@ export default class PluginCollection {
 	 * Loads a set of plugins and adds them to the collection.
 	 *
 	 * @param {Array.<Function|String>} plugins An array of {@link module:core/plugin~PluginInterface plugin constructors}
-	 * or {@link module:core/plugin~PluginInterface.pluginName plugin names}. The second option (names) work only if
+	 * or {@link module:core/plugin~PluginInterface.pluginName plugin names}. The second option (names) works only if
 	 * `availablePlugins` were passed to the {@link #constructor}.
 	 * @param {Array.<String|Function>} [removePlugins] Names of plugins or plugin constructors
-	 * which should not be loaded (despite being specified in the `plugins` array).
-	 * @returns {Promise} A promise which gets resolved once all plugins are loaded and available into the
+	 * that should not be loaded (despite being specified in the `plugins` array).
+	 * @returns {Promise} A promise which gets resolved once all plugins are loaded and available in the
 	 * collection.
 	 * @returns {Promise.<Array.<module:core/plugin~PluginInterface>>} returns.loadedPlugins The array of loaded plugins.
 	 */
@@ -102,8 +102,6 @@ export default class PluginCollection {
 		const missingPlugins = getMissingPluginNames( plugins );
 
 		if ( missingPlugins ) {
-			// TODO update this error docs with links to docs because it will be a frequent problem.
-
 			/**
 			 * Some plugins are not available and could not be loaded.
 			 *
@@ -111,9 +109,9 @@ export default class PluginCollection {
 			 * This is usually done by the builder by setting the {@link module:core/editor/editor~Editor.build}
 			 * property.
 			 *
-			 * **If you see this warning when using one of the {@glink builds/index CKEditor 5 Builds}** it means
-			 * that you try to enable a plugin which was not included into that build. This may a be due to a typo
-			 * in the plugin name or simply because that plugin is not part of this build. In the latter scenario,
+			 * **If you see this warning when using one of the {@glink builds/index CKEditor 5 Builds}**, it means
+			 * that you try to enable a plugin which was not included in that build. This may be due to a typo
+			 * in the plugin name or simply because that plugin is not a part of this build. In the latter scenario,
 			 * read more about {@glink builds/guides/development/custom-builds custom builds}.
 			 *
 			 * **If you see this warning when using one of the editor creators directly** (not a build), then it means
@@ -151,11 +149,11 @@ export default class PluginCollection {
 					/**
 					 * It was not possible to load the plugin.
 					 *
-					 * This is a generic error logged to the console when a JavaSript error is thrown during one of
-					 * the plugins initialization.
+					 * This is a generic error logged to the console when a JavaSript error is thrown during the initialization
+					 * of one of the plugins.
 					 *
-					 * If you correctly handled a promise returned by the editor's `create()` method (like shown below)
-					 * you will find the original error logged on the console too:
+					 * If you correctly handled the promise returned by the editor's `create()` method (like shown below)
+					 * you will find the original error logged to the console, too:
 					 *
 					 *		ClassicEditor.create( document.getElementById( 'editor' ) )
 					 *			.then( editor => {
@@ -270,7 +268,7 @@ export default class PluginCollection {
 			/**
 			 * Two plugins with the same {@link module:core/plugin~PluginInterface.pluginName} were loaded.
 			 * This may lead to runtime conflicts between these plugins. This usually means that incorrect
-			 * params were passed to {@link module:core/editor/editor~Editor.create}.
+			 * parameters were passed to {@link module:core/editor/editor~Editor.create}.
 			 *
 			 * @error plugincollection-plugin-name-conflict
 			 * @param {String} pluginName The duplicated plugin name.

+ 2 - 2
packages/ckeditor5-core/tests/_utils-tests/classictesteditor.js

@@ -22,11 +22,11 @@ import RootElement from '@ckeditor/ckeditor5-engine/src/model/rootelement';
 import { getData } from '@ckeditor/ckeditor5-engine/src/dev-utils/model';
 import testUtils from '../../tests/_utils/utils';
 
-testUtils.createSinonSandbox();
-
 describe( 'ClassicTestEditor', () => {
 	let editorElement;
 
+	testUtils.createSinonSandbox();
+
 	beforeEach( () => {
 		editorElement = document.createElement( 'div' );
 		document.body.appendChild( editorElement );

+ 2 - 2
packages/ckeditor5-core/tests/_utils-tests/createsinonsandbox.js

@@ -11,9 +11,9 @@ const obj = {
 const origMethod = obj.method;
 let spy;
 
-testUtils.createSinonSandbox();
-
 describe( 'testUtils.createSinonSandbox()', () => {
+	testUtils.createSinonSandbox();
+
 	it( 'creates a sandbox', () => {
 		expect( testUtils.sinon ).to.be.an( 'object' );
 		expect( testUtils.sinon ).to.have.property( 'spy' );

+ 2 - 2
packages/ckeditor5-core/tests/_utils-tests/modeltesteditor.js

@@ -15,9 +15,9 @@ import { getData, setData } from '@ckeditor/ckeditor5-engine/src/dev-utils/model
 
 import testUtils from '../../tests/_utils/utils';
 
-testUtils.createSinonSandbox();
-
 describe( 'ModelTestEditor', () => {
+	testUtils.createSinonSandbox();
+
 	describe( 'constructor()', () => {
 		it( 'creates an instance of editor', () => {
 			const editor = new ModelTestEditor( { foo: 1 } );

+ 2 - 2
packages/ckeditor5-core/tests/_utils-tests/utils.js

@@ -6,9 +6,9 @@
 import testUtils from '../_utils/utils';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
 
-testUtils.createSinonSandbox();
-
 describe( 'utils', () => {
+	testUtils.createSinonSandbox();
+
 	describe( 'checkAssertions()', () => {
 		it( 'does not throw an error if at least one assertion passed', () => {
 			const assertionRed = testUtils.sinon.stub().callsFake( () => {

+ 2 - 2
packages/ckeditor5-core/tests/_utils-tests/virtualtesteditor.js

@@ -12,9 +12,9 @@ import RootElement from '@ckeditor/ckeditor5-engine/src/model/rootelement';
 
 import testUtils from '../../tests/_utils/utils';
 
-testUtils.createSinonSandbox();
-
 describe( 'VirtualTestEditor', () => {
+	testUtils.createSinonSandbox();
+
 	describe( 'constructor()', () => {
 		it( 'creates an instance of editor', () => {
 			const editor = new VirtualTestEditor( { foo: 1 } );

+ 14 - 7
packages/ckeditor5-core/tests/_utils/utils.js

@@ -8,20 +8,27 @@
  */
 const utils = {
 	/**
-	 * Creates Sinon sandbox in {@link bender#sinon} and plugs `afterEach()` callback which
+	 * Creates Sinon sandbox in {@link utils#sinon} and plugs `afterEach()` callback which
 	 * restores all spies and stubs created in this sandbox.
 	 *
 	 * See https://github.com/ckeditor/ckeditor5-design/issues/72 and http://sinonjs.org/docs/#sinon-sandbox
 	 *
 	 * Usage:
 	 *
-	 *		// Directly in the test file:
-	 *		testUtils.createSinonSandbox();
+	 *		import testUtils from '@ckeditor/ckeditor5-utils/tests/_utils/utils';
 	 *
-	 *		// Then inside tests you can use bender.sinon:
-	 *		it( 'does something', () => {
-	 *			testUtils.sinon.spy( obj, 'method' );
-	 *		} );
+	 *		describe( 'MyClass', () => {
+	 *			// Create Sinon sandbox inside top-level describe block:
+	 *			testUtils.createSinonSandbox();
+	 *
+	 *			// Then inside tests you can use testUtils.sinon:
+	 *			it( 'does something', () => {
+	 *				testUtils.sinon.spy( obj, 'method' );
+	 *			} );
+	 *		}
+	 *
+	 * **Note**: Do not use `testUtils.createSinonSandbox()` outside `describe()` block as it will attach `afterEach()` calls
+	 * to all test - not only those in current file.
 	 */
 	createSinonSandbox() {
 		before( () => {

+ 2 - 2
packages/ckeditor5-core/tests/editor/editorui.js

@@ -12,11 +12,11 @@ import View from '@ckeditor/ckeditor5-ui/src/view';
 
 import testUtils from '../_utils/utils';
 
-testUtils.createSinonSandbox();
-
 describe( 'EditorUI', () => {
 	let editor, view, ui;
 
+	testUtils.createSinonSandbox();
+
 	beforeEach( () => {
 		editor = new Editor();
 		view = new View();

+ 35 - 35
packages/ckeditor5-core/tests/plugincollection.js

@@ -18,42 +18,42 @@ class TestError extends Error {}
 class ChildPlugin extends Plugin {}
 class GrandPlugin extends ChildPlugin {}
 
-testUtils.createSinonSandbox();
-
-before( () => {
-	PluginA = createPlugin( 'A' );
-	PluginB = createPlugin( 'B' );
-	PluginC = createPlugin( 'C' );
-	PluginD = createPlugin( 'D' );
-	PluginE = createPlugin( 'E' );
-	PluginF = createPlugin( 'F' );
-	PluginG = createPlugin( 'G', GrandPlugin );
-	PluginH = createPlugin( 'H' );
-	PluginI = createPlugin( 'I' );
-	PluginJ = createPlugin( 'J' );
-	PluginK = createPlugin( 'K' );
-	PluginX = class extends Plugin {
-		constructor( editor ) {
-			super( editor );
-
-			throw new TestError( 'Some error inside a plugin' );
-		}
-	};
-	PluginFoo = createPlugin( 'Foo' );
-	AnotherPluginFoo = createPlugin( 'Foo' );
-
-	PluginC.requires = [ PluginB ];
-	PluginD.requires = [ PluginA, PluginC ];
-	PluginF.requires = [ PluginE ];
-	PluginE.requires = [ PluginF ];
-	PluginH.requires = [ PluginI ];
-	PluginJ.requires = [ 'K' ];
-	PluginK.requires = [ PluginA ];
-
-	editor = new Editor();
-} );
-
 describe( 'PluginCollection', () => {
+	testUtils.createSinonSandbox();
+
+	before( () => {
+		PluginA = createPlugin( 'A' );
+		PluginB = createPlugin( 'B' );
+		PluginC = createPlugin( 'C' );
+		PluginD = createPlugin( 'D' );
+		PluginE = createPlugin( 'E' );
+		PluginF = createPlugin( 'F' );
+		PluginG = createPlugin( 'G', GrandPlugin );
+		PluginH = createPlugin( 'H' );
+		PluginI = createPlugin( 'I' );
+		PluginJ = createPlugin( 'J' );
+		PluginK = createPlugin( 'K' );
+		PluginX = class extends Plugin {
+			constructor( editor ) {
+				super( editor );
+
+				throw new TestError( 'Some error inside a plugin' );
+			}
+		};
+		PluginFoo = createPlugin( 'Foo' );
+		AnotherPluginFoo = createPlugin( 'Foo' );
+
+		PluginC.requires = [ PluginB ];
+		PluginD.requires = [ PluginA, PluginC ];
+		PluginF.requires = [ PluginE ];
+		PluginE.requires = [ PluginF ];
+		PluginH.requires = [ PluginI ];
+		PluginJ.requires = [ 'K' ];
+		PluginK.requires = [ PluginA ];
+
+		editor = new Editor();
+	} );
+
 	beforeEach( () => {
 		availablePlugins = [
 			PluginA,

+ 1 - 1
packages/ckeditor5-core/theme/icons/pilcrow.svg

@@ -1 +1 @@
-<svg width="20" height="20" xmlns="http://www.w3.org/2000/svg"><path d="M15.442 3H8.481a3.48 3.48 0 0 0 0 6.961v6.962h1.74V4.74h1.74v12.183h1.74V4.74h1.741V3z"/></svg>
+<svg width="20" height="20" xmlns="http://www.w3.org/2000/svg"><path d="M6.999 2H15a1 1 0 0 1 0 2h-1.004v13a1 1 0 1 1-2 0V4H8.999v13a1 1 0 1 1-2 0v-7A4 4 0 0 1 3 6a4 4 0 0 1 3.999-4z" fill="#2E2E2E" fill-rule="evenodd"/></svg>