@ckeditor/ckeditor5-style 34.0.0

package/src/stylecommand.js

@@ -0,0 +1,267 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module style/stylecommand
+ */
+
+import { Command } from 'ckeditor5/src/core';
+import { logWarning, first } from 'ckeditor5/src/utils';
+
+/**
+ * Style command.
+ *
+ * Applies and removes styles from selection and elements.
+ *
+ * @extends module:core/command~Command
+ */
+export default class StyleCommand extends Command {
+	constructor( editor, styles ) {
+		super( editor );
+
+		/**
+		 * Set of currently applied styles on current selection.
+		 *
+		 * Names of styles correspond to the `name` property of
+		 * {@link module:style/style~StyleDefinition configured definitions}.
+		 *
+		 * @observable
+		 * @readonly
+		 * @member {Boolean|String} #value
+		 */
+
+		/**
+		 * Styles object. Helps in getting styles definitions by
+		 * class name, style name and model element name.
+		 *
+		 * @private
+		 * @readonly
+		 * @member {module:style/styleediting~Styles}
+		 */
+		this.styles = styles;
+
+		/**
+		 * Names of enabled styles (styles that can be applied to the current selection).
+		 *
+		 * Names of enabled styles correspond to the `name` property of
+		 * {@link module:style/style~StyleDefinition configured definitions}.
+		 *
+		 * @readonly
+		 * @observable
+		 * @member {Array.<String>} #enabledStyles
+		 */
+		this.set( 'enabledStyles', [] );
+
+		/**
+		 * Refresh state.
+		 */
+		this.refresh();
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	refresh() {
+		let value = [];
+		const editor = this.editor;
+		const selection = editor.model.document.selection;
+		const block = first( selection.getSelectedBlocks() );
+
+		this.enabledStyles = [];
+
+		if ( !block || !editor.model.schema.isObject( block ) ) {
+			value = this._prepareNewInlineElementValue( value, selection );
+			this.enabledStyles = this.styles.getInlineElementsNames();
+
+			if ( block ) {
+				value = this._prepareNewBlockElementValue( value, block );
+			}
+		}
+
+		this.isEnabled = this.enabledStyles.length > 0;
+		this.value = this.isEnabled ? value : [];
+	}
+
+	/**
+	 * Executes the command &mdash; applies the style classes to the selection or removes it from the selection.
+	 *
+	 * If the command value already contains the requested style, it will remove the style classes. Otherwise, it will set it.
+	 *
+	 * The execution result differs, depending on the {@link module:engine/model/document~Document#selection} and the
+	 * style type (inline or block):
+	 *
+	 * * When applying inline styles:
+	 *   * If the selection is on a range, the command applies the style classes to all nodes in that range.
+	 *   * If the selection is collapsed in a non-empty node, the command applies the style classes to the
+	 * {@link module:engine/model/document~Document#selection} itself (note that typed characters copy style classes from the selection).
+	 *
+	 * * When applying block styles:
+	 *   * If the selection is on a range, the command applies the style classes to the nearest block parent element.
+	 *
+	 * * When selection is set on a widget object:
+	 *   * Do nothing. Widgets are not yet supported by the style command.
+	 *
+	 * @fires execute
+	 * @param {String} styleName Style name matching the one defined in the config.
+	 */
+	execute( styleName ) {
+		if ( !this.enabledStyles.includes( styleName ) ) {
+			/**
+			 * Style command can be executed only on a correct style name.
+			 * This warning may be caused by passing name that it not specified in any of the
+			 * definitions in the styles config, when trying to apply style that is not allowed
+			 * on given element or passing class name instead of the style name.
+			 *
+			 * @error style-command-executed-with-incorrect-style-name
+			 */
+			logWarning( 'style-command-executed-with-incorrect-style-name' );
+			return;
+		}
+
+		const editor = this.editor;
+		const model = editor.model;
+		const doc = model.document;
+		const selection = doc.selection;
+
+		const selectedBlockElement = first( selection.getSelectedBlocks() );
+		const definition = this.styles.getDefinitionsByName( styleName );
+
+		if ( selectedBlockElement && definition.isBlock ) {
+			this._handleStyleUpdate( definition, selectedBlockElement );
+		} else {
+			this._handleStyleUpdate( definition, selection );
+		}
+	}
+
+	/**
+	 * Adds or removes classes to element, range or selection.
+	 *
+	 * @private
+	 * @param {Object} definition Style definition object.
+	 * @param {module:engine/model/selection~Selectable} selectable Selection, range or element to update the style on.
+	 */
+	_handleStyleUpdate( definition, selectable ) {
+		const { name, element, classes } = definition;
+		const htmlSupport = this.editor.plugins.get( 'GeneralHtmlSupport' );
+
+		if ( this.value.includes( name ) ) {
+			htmlSupport.removeModelHtmlClass( element, classes, selectable );
+		} else {
+			htmlSupport.addModelHtmlClass( element, classes, selectable );
+		}
+	}
+
+	/**
+	 * Returns inline element value.
+	 *
+	 * @private
+	 * @param {Array} value
+	 * @param {module:engine/model/selection~Selection} selection
+	 */
+	_prepareNewInlineElementValue( value, selection ) {
+		let newValue = [ ...value ];
+
+		const attributes = selection.getAttributes();
+
+		for ( const [ attribute ] of attributes ) {
+			newValue = [ ...newValue, ...this._getAttributeValue( attribute ) ];
+		}
+
+		return newValue;
+	}
+
+	/**
+	 * Returns element value and sets enabled styles.
+	 *
+	 * @private
+	 * @param {Array} value
+	 * @param {Object|null} element
+	 * @return {Array} Current block element styles value.
+	 */
+	_prepareNewBlockElementValue( value, element ) {
+		const availableDefinitions = this.styles.getDefinitionsByElementName( element.name );
+
+		if ( availableDefinitions ) {
+			const blockStyleNames = availableDefinitions.map( ( { name } ) => name );
+			this.enabledStyles = [ ...this.enabledStyles, ...blockStyleNames ];
+		}
+
+		return [ ...value, ...this._getAttributeValue( 'htmlAttributes' ) ];
+	}
+
+	/**
+	 * Get classes attribute value.
+	 *
+	 * @private
+	 * @param {String} attribute
+	 */
+	_getAttributeValue( attribute ) {
+		const value = [];
+		const classes = attribute === 'htmlAttributes' ?
+			this._getValueFromBlockElement() :
+			this._getValueFromFirstAllowedNode( attribute );
+
+		for ( const htmlClass of classes ) {
+			const { name } = this.styles.getDefinitionsByClassName( htmlClass ) || {};
+
+			value.push( name );
+		}
+
+		return value;
+	}
+
+	/**
+	 * Gets classes from currently selected block element.
+	 *
+	 * @private
+	 */
+	_getValueFromBlockElement() {
+		const selection = this.editor.model.document.selection;
+		const block = first( selection.getSelectedBlocks() );
+		const attributes = block.getAttribute( 'htmlAttributes' );
+
+		if ( attributes ) {
+			return attributes.classes;
+		}
+
+		return [];
+	}
+
+	/**
+	 * Gets classes from currently selected text element.
+	 *
+	 * @private
+	 * @param {String} attributeName Text attribute name.
+	 */
+	_getValueFromFirstAllowedNode( attributeName ) {
+		const model = this.editor.model;
+		const schema = model.schema;
+		const selection = model.document.selection;
+
+		if ( selection.isCollapsed ) {
+			/* istanbul ignore next */
+			const { classes } = selection.getAttribute( attributeName ) || {};
+
+			/* istanbul ignore next */
+			return classes || [];
+		}
+
+		for ( const range of selection.getRanges() ) {
+			for ( const item of range.getItems() ) {
+				/* istanbul ignore else */
+				if ( schema.checkAttribute( item, attributeName ) ) {
+					/* istanbul ignore next */
+					const { classes } = item.getAttribute( attributeName ) || {};
+
+					/* istanbul ignore next */
+					return classes || [];
+				}
+			}
+		}
+
+		/* istanbul ignore next */
+		return [];
+	}
+}

package/src/styleediting.js

@@ -0,0 +1,161 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module style/styleediting
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+import { normalizeConfig } from './utils';
+
+import StyleCommand from './stylecommand';
+
+/**
+ * The style engine feature.
+ *
+ * It configures the {@glink features/general-html-support General HTML Support feature} based on
+ * {@link module:style/style~StyleConfig#definitions configured style definitions} and introduces the
+ * {@link module:style/stylecommand~StyleCommand style command} that applies styles to the content of the document.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class StyleEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'StyleEditing';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ 'GeneralHtmlSupport' ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		const editor = this.editor;
+		const dataSchema = editor.plugins.get( 'DataSchema' );
+		const normalizedStyleDefinitions = normalizeConfig( dataSchema, editor.config.get( 'style.definitions' ) );
+		const styles = new Styles( normalizedStyleDefinitions );
+
+		editor.commands.add( 'style', new StyleCommand( editor, styles ) );
+
+		this._configureGHSDataFilter( normalizedStyleDefinitions );
+	}
+
+	/**
+	 * This is where the styles feature configures the GHS feature. This method translates normalized
+	 * {@link module:style/style~StyleDefinition style definitions} to {@link module:engine/view/matcher~MatcherPattern matcher patterns}
+	 * and feeds them to the GHS {@link module:html-support/datafilter~DataFilter} plugin.
+	 *
+	 * @private
+	 * @param {Object} normalizedStyleDefinitions
+	 */
+	_configureGHSDataFilter( { block: blockDefinitions, inline: inlineDefinitions } ) {
+		const ghsDataFilter = this.editor.plugins.get( 'DataFilter' );
+
+		ghsDataFilter.loadAllowedConfig( blockDefinitions.map( normalizedStyleDefinitionToMatcherPattern ) );
+		ghsDataFilter.loadAllowedConfig( inlineDefinitions.map( normalizedStyleDefinitionToMatcherPattern ) );
+	}
+}
+
+/**
+ * The helper class storing various mappings based on
+ * {@link module:style/style~StyleConfig#definitions configured style definitions}. Used internally by
+ * {@link module:style/stylecommand~StyleCommand}.
+ *
+ * @private
+ */
+class Styles {
+	/**
+	 * @param {Object} An object with normalized style definitions grouped into `block` and `inline` categories (arrays).
+	 */
+	constructor( styleDefinitions ) {
+		this.styleTypes = [ 'inline', 'block' ];
+		this.styleDefinitions = styleDefinitions;
+		this.elementToDefinition = new Map();
+		this.classToDefinition = new Map();
+		this.nameToDefinition = new Map();
+
+		this._prepareDefinitionsMapping();
+	}
+
+	/**
+	 * Populates various maps to simplify getting config definitions
+	 * by model name,class name and style name.
+	 *
+	 * @private
+	 */
+	_prepareDefinitionsMapping() {
+		for ( const type of this.styleTypes ) {
+			for ( const { modelElements, name, element, classes, isBlock } of this.styleDefinitions[ type ] ) {
+				for ( const modelElement of modelElements ) {
+					const currentValue = this.elementToDefinition.get( modelElement ) || [];
+					const newValue = [ ...currentValue, { name, element, classes } ];
+					this.elementToDefinition.set( modelElement, newValue );
+				}
+
+				this.classToDefinition.set( classes.join( ' ' ), { name, element, classes } );
+				this.nameToDefinition.set( name, { name, element, classes, isBlock } );
+			}
+		}
+	}
+
+	/**
+	 * Returns all inline definitions elements names.
+	 *
+	 * @protected
+	 * @return {Array.<String>} Inline elements names.
+	 */
+	getInlineElementsNames() {
+		return this.styleDefinitions.inline.map( ( { name } ) => name );
+	}
+
+	/**
+	 * Returns the style config definitions by the model element name.
+	 *
+	 * @protected
+	 * @return {Object} Style config definition.
+	 */
+	getDefinitionsByElementName( elementName ) {
+		return this.elementToDefinition.get( elementName );
+	}
+
+	/**
+	 * Returns the style config definitions by the style name.
+	 *
+	 * @protected
+	 * @return {Object} Style config definition.
+	 */
+	getDefinitionsByName( name ) {
+		return this.nameToDefinition.get( name );
+	}
+
+	/**
+	 * Returns the style config definitions by the style name.
+	 *
+	 * @protected
+	 * @return {Object} Style config definition.
+	 */
+	getDefinitionsByClassName( className ) {
+		return this.classToDefinition.get( className );
+	}
+}
+
+// Translates a normalized style definition to a view matcher pattern.
+//
+// @param {Object} definition A normalized style definition.
+// @returns {module:engine/view/matcher~MatcherPattern}
+function normalizedStyleDefinitionToMatcherPattern( { element, classes } ) {
+	return {
+		name: element,
+		classes
+	};
+}

package/src/styleui.js

@@ -0,0 +1,99 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module style/styleui
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+import { createDropdown } from 'ckeditor5/src/ui';
+
+import StylePanelView from './ui/stylepanelview';
+import { normalizeConfig } from './utils';
+
+import '../theme/style.css';
+
+/**
+ * The UI plugin of the style feature .
+ *
+ * It registers the `'style'` UI dropdown in the editor's {@link module:ui/componentfactory~ComponentFactory component factory}
+ * that displays a grid of styles and allows changing styles of the content.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class StyleUI extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'StyleUI';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		const editor = this.editor;
+		const dataSchema = editor.plugins.get( 'DataSchema' );
+		const normalizedStyleDefinitions = normalizeConfig( dataSchema, editor.config.get( 'style.definitions' ) );
+
+		// Add the dropdown fo the component factory.
+		editor.ui.componentFactory.add( 'style', locale => {
+			const t = locale.t;
+			const dropdown = createDropdown( locale );
+			const panelView = new StylePanelView( locale, normalizedStyleDefinitions );
+			const styleCommand = editor.commands.get( 'style' );
+
+			// The entire dropdown will be disabled together with the command (e.g. when the editor goes read-only).
+			dropdown.bind( 'isEnabled' ).to( styleCommand );
+
+			// Put the styles panel is the dropdown.
+			dropdown.panelView.children.add( panelView );
+
+			// This dropdown has no icon. It displays text label depending on the selection.
+			dropdown.buttonView.withText = true;
+
+			// The label of the dropdown is dynamic and depends on how many styles are active at a time.
+			dropdown.buttonView.bind( 'label' ).to( styleCommand, 'value', value => {
+				if ( value.length > 1 ) {
+					return t( 'Multiple styles' );
+				} else if ( value.length === 1 ) {
+					return value[ 0 ];
+				} else {
+					return t( 'Styles' );
+				}
+			} );
+
+			// The dropdown has a static CSS class for easy customization. There's another CSS class
+			// that gets displayed when multiple styles are active at a time allowing visual customization of
+			// the label.
+			dropdown.bind( 'class' ).to( styleCommand, 'value', value => {
+				const classes = [
+					'ck-style-dropdown'
+				];
+
+				if ( value.length > 1 ) {
+					classes.push( 'ck-style-dropdown_multiple-active' );
+				}
+
+				return classes.join( ' ' );
+			} );
+
+			// Close the dropdown when a style is selected in the styles panel.
+			panelView.delegate( 'execute' ).to( dropdown );
+
+			// Execute the command when a style is selected in the styles panel.
+			panelView.on( 'execute', evt => {
+				editor.execute( 'style', evt.source.styleDefinition.name );
+			} );
+
+			// Bind the state of the styles panel to the command.
+			panelView.bind( 'activeStyles' ).to( styleCommand, 'value' );
+			panelView.bind( 'enabledStyles' ).to( styleCommand, 'enabledStyles' );
+
+			return dropdown;
+		} );
+	}
+}

package/src/ui/stylegridbuttonview.js

@@ -0,0 +1,118 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module style/ui/stylegridbuttonview
+ */
+
+import {
+	ButtonView,
+	View
+} from 'ckeditor5/src/ui';
+
+// These are intermediate element names that can't be rendered as style preview because they don't make sense standalone.
+const NON_PREVIEWABLE_ELEMENT_NAMES = [
+	'caption', 'colgroup', 'dd', 'dt', 'figcaption', 'legend', 'li', 'optgroup', 'option', 'rp',
+	'rt', 'summary', 'tbody', 'td', 'tfoot', 'th', 'thead', 'tr'
+];
+
+/**
+ * A class representing an individual button (style) in the grid. Renders a rich preview of the style.
+ *
+ * @protected
+ * @extends {module:ui/button/buttonview~ButtonView}
+ */
+export default class StyleGridButtonView extends ButtonView {
+	/**
+	 * Creates an instance of the {@link module:style/ui/stylegridbuttonview~StyleGridButtonView} class.
+	 *
+	 * @param {module:utils/locale~Locale} locale The localization services instance.
+	 * @param {module:style/style~StyleDefinition} styleDefinition Definition of the style.
+	 */
+	constructor( locale, styleDefinition ) {
+		super( locale );
+
+		/**
+		 * Definition of the style the button will apply when executed.
+		 *
+		 * @readonly
+		 * @member {module:style/style~StyleDefinition} #styleDefinition
+		 */
+		this.styleDefinition = styleDefinition;
+
+		/**
+		 * The view rendering the preview of the style.
+		 *
+		 * @protected
+		 * @readonly
+		 * @member {module:ui/view~View} #previewView
+		 */
+		this.previewView = this._createPreview();
+
+		this.set( {
+			label: styleDefinition.name,
+			class: 'ck-style-grid__button',
+			withText: true
+		} );
+
+		this.extendTemplate( {
+			attributes: {
+				role: 'option'
+			}
+		} );
+
+		this.children.add( this.previewView, 0 );
+	}
+
+	/**
+	 * Creates the view representing the preview of the style.
+	 *
+	 * @private
+	 * @returns {module:ui/view~View}
+	 */
+	_createPreview() {
+		const { element, classes } = this.styleDefinition;
+		const previewView = new View( this.locale );
+
+		previewView.setTemplate( {
+			tag: 'div',
+
+			attributes: {
+				class: [
+					'ck',
+					'ck-reset_all-excluded',
+					'ck-style-grid__button__preview',
+					'ck-content'
+				]
+			},
+
+			children: [
+				{
+					tag: this._isPreviewable( element ) ? element : 'div',
+					attributes: {
+						class: classes
+					},
+					children: [
+						{ text: 'AaBbCcDdEeFfGgHhIiJj' }
+					]
+				}
+			]
+		} );
+
+		return previewView;
+	}
+
+	/**
+	 * Decides whether an element should be created in the preview or a substitute `<div>` should
+	 * be used instead. This avoids previewing a standalone `<td>`, `<li>`, etc. without a parent.
+	 *
+	 * @private
+	 * @param {module:style/style~StyleDefinition} styleDefinition
+	 * @returns {Boolean} `true` when the element can be rendered. `false` otherwise.
+	 */
+	_isPreviewable( elementName ) {
+		return !NON_PREVIEWABLE_ELEMENT_NAMES.includes( elementName );
+	}
+}