@ckeditor/ckeditor5-core 30.0.0

package/src/editor/utils/dataapimixin.js

@@ -0,0 +1,81 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module core/editor/utils/dataapimixin
+ */
+
+/**
+ * Implementation of the {@link module:core/editor/utils/dataapimixin~DataApi}.
+ *
+ * @mixin DataApiMixin
+ * @implements module:core/editor/utils/dataapimixin~DataApi
+ */
+const DataApiMixin = {
+	/**
+	 * @inheritDoc
+	 */
+	setData( data ) {
+		this.data.set( data );
+	},
+
+	/**
+	 * @inheritDoc
+	 */
+	getData( options ) {
+		return this.data.get( options );
+	}
+};
+
+export default DataApiMixin;
+
+/**
+ * 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 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
+ */
+
+/**
+ * Sets the data in the editor.
+ *
+ *		editor.setData( '<p>This is editor!</p>' );
+ *
+ * By default the editor accepts HTML. This can be controlled by injecting a different data processor.
+ * 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
+ * the right format for you.
+ *
+ * @method #setData
+ * @param {String} data Input data.
+ */
+
+/**
+ * Gets the data from the editor.
+ *
+ *		editor.getData(); // -> '<p>This is editor!</p>'
+ *
+ * By default the editor outputs HTML. This can be controlled by injecting a different data processor.
+ * 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
+ * the right format for you.
+ *
+ * @method #getData
+ * @param {Object} [options] Additional configuration for the retrieved data.
+ * Editor features may introduce more configuration options that can be set through this parameter.
+ * @param {String} [options.rootName='main'] Root name.
+ * @param {String} [options.trim='empty'] Whether returned data should be trimmed. This option is set to `'empty'` by default,
+ * which means that whenever editor content is considered empty, an empty string is returned. To turn off trimming
+ * use `'none'`. In such cases exact content will be returned (for example `'<p>&nbsp;</p>'` for an empty editor).
+ * @returns {String} Output data.
+ */

package/src/editor/utils/elementapimixin.js

@@ -0,0 +1,65 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import setDataInElement from '@ckeditor/ckeditor5-utils/src/dom/setdatainelement';
+
+/**
+ * @module core/editor/utils/elementapimixin
+ */
+
+/**
+ * Implementation of the {@link module:core/editor/utils/elementapimixin~ElementApi}.
+ *
+ * @mixin ElementApiMixin
+ * @implements module:core/editor/utils/elementapimixin~ElementApi
+ */
+const ElementApiMixin = {
+	/**
+	 * @inheritDoc
+	 */
+	updateSourceElement() {
+		if ( !this.sourceElement ) {
+			/**
+			 * Cannot update the source element of a detached editor.
+			 *
+			 * The {@link ~ElementApi#updateSourceElement `updateSourceElement()`} method cannot be called if you did not
+			 * pass an element to `Editor.create()`.
+			 *
+			 * @error editor-missing-sourceelement
+			 */
+			throw new CKEditorError(
+				'editor-missing-sourceelement',
+				this
+			);
+		}
+
+		setDataInElement( this.sourceElement, this.data.get() );
+	}
+};
+
+export default ElementApiMixin;
+
+/**
+ * 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}.
+ *
+ * @interface ElementApi
+ */
+
+/**
+ * The element on which the editor has been initialized.
+ *
+ * @readonly
+ * @member {HTMLElement} #sourceElement
+ */
+
+/**
+ * Updates the {@link #sourceElement editor source element}'s content with the data.
+ *
+ * @method #updateSourceElement
+ */

package/src/editor/utils/securesourceelement.js

@@ -0,0 +1,49 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+/**
+ * @module core/editor/utils/securesourceelement
+ */
+
+/**
+ * Marks the source element on which the editor was initialized. This prevents other editor instances from using this element.
+ *
+ * Running multiple editor instances on the same source element causes various issues and it is
+ * crucial this helper is called as soon as the source element is known to prevent collisions.
+ *
+ * @param {module:core/editor/editor~Editor} editor Editor instance.
+ */
+export default function secureSourceElement( editor ) {
+	const sourceElement = editor.sourceElement;
+
+	// If the editor was initialized without specifying an element, we don't need to secure anything.
+	if ( !sourceElement ) {
+		return;
+	}
+
+	if ( sourceElement.ckeditorInstance ) {
+		/**
+		 * A DOM element used to create the editor (e.g.
+		 * {@link module:editor-inline/inlineeditor~InlineEditor.create `InlineEditor.create()`})
+		 * has already been used to create another editor instance. Make sure each editor is
+		 * created with an unique DOM element.
+		 *
+		 * @error editor-source-element-already-used
+		 * @param {HTMLElement} element DOM element that caused the collision.
+		 */
+		throw new CKEditorError(
+			'editor-source-element-already-used',
+			editor
+		);
+	}
+
+	sourceElement.ckeditorInstance = editor;
+
+	editor.once( 'destroy', () => {
+		delete sourceElement.ckeditorInstance;
+	} );
+}

package/src/index.js

@@ -0,0 +1,95 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module core
+ */
+
+export { default as Plugin } from './plugin';
+export { default as Command } from './command';
+export { default as MultiCommand } from './multicommand';
+
+export { default as Context } from './context';
+export { default as ContextPlugin } from './contextplugin';
+
+export { default as Editor } from './editor/editor';
+export { default as EditorUI } from './editor/editorui';
+
+export { default as attachToForm } from './editor/utils/attachtoform';
+export { default as DataApiMixin } from './editor/utils/dataapimixin';
+export { default as ElementApiMixin } from './editor/utils/elementapimixin';
+export { default as secureSourceElement } from './editor/utils/securesourceelement';
+
+export { default as PendingActions } from './pendingactions';
+
+import cancel from './../theme/icons/cancel.svg';
+import caption from './../theme/icons/caption.svg';
+import check from './../theme/icons/check.svg';
+import cog from './../theme/icons/cog.svg';
+import eraser from './../theme/icons/eraser.svg';
+import lowVision from './../theme/icons/low-vision.svg';
+import image from './../theme/icons/image.svg';
+
+import alignBottom from './../theme/icons/align-bottom.svg';
+import alignMiddle from './../theme/icons/align-middle.svg';
+import alignTop from './../theme/icons/align-top.svg';
+import alignLeft from './../theme/icons/align-left.svg';
+import alignCenter from './../theme/icons/align-center.svg';
+import alignRight from './../theme/icons/align-right.svg';
+import alignJustify from './../theme/icons/align-justify.svg';
+
+import objectBlockLeft from './../theme/icons/object-left.svg';
+import objectCenter from './../theme/icons/object-center.svg';
+import objectBlockRight from './../theme/icons/object-right.svg';
+import objectFullWidth from './../theme/icons/object-full-width.svg';
+import objectInline from './../theme/icons/object-inline.svg';
+import objectLeft from './../theme/icons/object-inline-left.svg';
+import objectRight from './../theme/icons/object-inline-right.svg';
+
+import objectSizeFull from './../theme/icons/object-size-full.svg';
+import objectSizeLarge from './../theme/icons/object-size-large.svg';
+import objectSizeSmall from './../theme/icons/object-size-small.svg';
+import objectSizeMedium from './../theme/icons/object-size-medium.svg';
+
+import pencil from './../theme/icons/pencil.svg';
+import pilcrow from './../theme/icons/pilcrow.svg';
+import quote from './../theme/icons/quote.svg';
+import threeVerticalDots from './../theme/icons/three-vertical-dots.svg';
+
+export const icons = {
+	cancel,
+	caption,
+	check,
+	cog,
+	eraser,
+	lowVision,
+	image,
+
+	alignBottom,
+	alignMiddle,
+	alignTop,
+	alignLeft,
+	alignCenter,
+	alignRight,
+	alignJustify,
+
+	objectLeft,
+	objectCenter,
+	objectRight,
+	objectFullWidth,
+	objectInline,
+	objectBlockLeft,
+	objectBlockRight,
+
+	objectSizeFull,
+	objectSizeLarge,
+	objectSizeSmall,
+	objectSizeMedium,
+
+	pencil,
+	pilcrow,
+	quote,
+	threeVerticalDots
+};

package/src/multicommand.js

@@ -0,0 +1,101 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+import Command from './command';
+
+/**
+ * @module core/multicommand
+ */
+
+/**
+ * A CKEditor command that aggregates other commands.
+ *
+ * This command is used to proxy multiple commands. The multi-command is enabled when
+ * at least one of its registered child commands is enabled.
+ * When executing a multi-command the first command that is enabled will be executed.
+ *
+ *		const multiCommand = new MultiCommand( editor );
+ *
+ *		const commandFoo = new Command( editor );
+ *		const commandBar = new Command( editor );
+ *
+ *		// Register child commands.
+ *		multiCommand.registerChildCommand( commandFoo );
+ *		multiCommand.registerChildCommand( commandBar );
+ *
+ *		// Enable one of the commands.
+ *		commandBar.isEnabled = true;
+ *
+ *		multiCommand.execute(); // Will execute commandBar.
+ *
+ * @extends module:core/command~Command
+ */
+export default class MultiCommand extends Command {
+	/**
+	 * @inheritDoc
+	 */
+	constructor( editor ) {
+		super( editor );
+
+		/**
+		 * Registered child commands.
+		 *
+		 * @type {Array.<module:core/command~Command>}
+		 * @private
+		 */
+		this._childCommands = [];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	refresh() {
+		// Override base command refresh(): the command's state is changed when one of child commands changes states.
+	}
+
+	/**
+	 * Executes the first of it registered child commands.
+	 *
+	 * @returns {*} The value returned by the {@link module:core/command~Command#execute `command.execute()`}.
+	 */
+	execute( ...args ) {
+		const command = this._getFirstEnabledCommand();
+
+		return command != null && command.execute( args );
+	}
+
+	/**
+	 * Registers a child command.
+	 *
+	 * @param {module:core/command~Command} command
+	 */
+	registerChildCommand( command ) {
+		this._childCommands.push( command );
+
+		// Change multi command enabled state when one of registered commands changes state.
+		command.on( 'change:isEnabled', () => this._checkEnabled() );
+
+		this._checkEnabled();
+	}
+
+	/**
+	 * Checks if any of child commands is enabled.
+	 *
+	 * @private
+	 */
+	_checkEnabled() {
+		this.isEnabled = !!this._getFirstEnabledCommand();
+	}
+
+	/**
+	 * Returns a first enabled command or undefined if none of them is enabled.
+	 *
+	 * @returns {module:core/command~Command|undefined}
+	 * @private
+	 */
+	_getFirstEnabledCommand() {
+		return this._childCommands.find( command => command.isEnabled );
+	}
+}

package/src/pendingactions.js

@@ -0,0 +1,155 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module core/pendingactions
+ */
+
+import ContextPlugin from './contextplugin';
+import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
+import Collection from '@ckeditor/ckeditor5-utils/src/collection';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+/**
+ * The list of pending editor actions.
+ *
+ * This plugin should be used to synchronise plugins that execute long-lasting actions
+ * (e.g. file upload) with the editor integration. It gives the developer who integrates the editor
+ * an easy way to check if there are any actions pending whenever such information is needed.
+ * All plugins that register a pending action also provide a message about the action that is ongoing
+ * which can be displayed to the user. This lets them decide if they want to interrupt the action or wait.
+ *
+ * Adding and updating a pending action:
+ *
+ * 		const pendingActions = editor.plugins.get( 'PendingActions' );
+ * 		const action = pendingActions.add( 'Upload in progress: 0%.' );
+ *
+ *		// You can update the message:
+ * 		action.message = 'Upload in progress: 10%.';
+ *
+ * Removing a pending action:
+ *
+ * 		const pendingActions = editor.plugins.get( 'PendingActions' );
+ * 		const action = pendingActions.add( 'Unsaved changes.' );
+ *
+ * 		pendingActions.remove( action );
+ *
+ * Getting pending actions:
+ *
+ * 		const pendingActions = editor.plugins.get( 'PendingActions' );
+ *
+ * 		const action1 = pendingActions.add( 'Action 1' );
+ * 		const action2 = pendingActions.add( 'Action 2' );
+ *
+ * 		pendingActions.first; // Returns action1
+ * 		Array.from( pendingActions ); // Returns [ action1, action2 ]
+ *
+ * This plugin is used by features like {@link module:upload/filerepository~FileRepository} to register their ongoing actions
+ * and by features like {@link module:autosave/autosave~Autosave} to detect whether there are any ongoing actions.
+ * Read more about saving the data in the {@glink builds/guides/integration/saving-data Saving and getting data} guide.
+ *
+ * @extends module:core/contextplugin~ContextPlugin
+ */
+export default class PendingActions extends ContextPlugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'PendingActions';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		/**
+		 * Defines whether there is any registered pending action.
+		 *
+		 * @readonly
+		 * @observable
+		 * @member {Boolean} #hasAny
+		 */
+		this.set( 'hasAny', false );
+
+		/**
+		 * A list of pending actions.
+		 *
+		 * @private
+		 * @type {module:utils/collection~Collection}
+		 */
+		this._actions = new Collection( { idProperty: '_id' } );
+		this._actions.delegate( 'add', 'remove' ).to( this );
+	}
+
+	/**
+	 * Adds an action to the list of pending actions.
+	 *
+	 * This method returns an action object with an observable message property.
+	 * The action object can be later used in the {@link #remove} method. It also allows you to change the message.
+	 *
+	 * @param {String} message The action message.
+	 * @returns {Object} An observable object that represents a pending action.
+	 */
+	add( message ) {
+		if ( typeof message !== 'string' ) {
+			/**
+			 * The message must be a string.
+			 *
+			 * @error pendingactions-add-invalid-message
+			 */
+			throw new CKEditorError( 'pendingactions-add-invalid-message', this );
+		}
+
+		const action = Object.create( ObservableMixin );
+
+		action.set( 'message', message );
+		this._actions.add( action );
+		this.hasAny = true;
+
+		return action;
+	}
+
+	/**
+	 * Removes an action from the list of pending actions.
+	 *
+	 * @param {Object} action An action object.
+	 */
+	remove( action ) {
+		this._actions.remove( action );
+		this.hasAny = !!this._actions.length;
+	}
+
+	/**
+	 * Returns the first action from the list or null when list is empty
+	 *
+	 * returns {Object|null} The pending action object.
+	 */
+	get first() {
+		return this._actions.get( 0 );
+	}
+
+	/**
+	 * Iterable interface.
+	 *
+	 * @returns {Iterable.<*>}
+	 */
+	[ Symbol.iterator ]() {
+		return this._actions[ Symbol.iterator ]();
+	}
+
+	/**
+	 * Fired when an action is added to the list.
+	 *
+	 * @event add
+	 * @param {Object} action The added action.
+	 */
+
+	/**
+	 * Fired when an action is removed from the list.
+	 *
+	 * @event remove
+	 * @param {Object} action The removed action.
+	 */
+}