@ckeditor/ckeditor5-style 0.0.0-internal-20241017.0

package/src/style.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module style/style
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import StyleUI from './styleui.js';
+import StyleEditing from './styleediting.js';
+/**
+ * The style plugin.
+ *
+ * This is a "glue" plugin that loads the {@link module:style/styleediting~StyleEditing style editing feature}
+ * and {@link module:style/styleui~StyleUI style UI feature}.
+ */
+export default class Style extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Style";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof StyleEditing, typeof StyleUI];
+}

package/src/style.js

@@ -0,0 +1,36 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module style/style
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import StyleUI from './styleui.js';
+import StyleEditing from './styleediting.js';
+/**
+ * The style plugin.
+ *
+ * This is a "glue" plugin that loads the {@link module:style/styleediting~StyleEditing style editing feature}
+ * and {@link module:style/styleui~StyleUI style UI feature}.
+ */
+export default class Style extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'Style';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [StyleEditing, StyleUI];
+    }
+}

package/src/stylecommand.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+import { type NormalizedStyleDefinitions } from './styleutils.js';
+/**
+ * Style command.
+ *
+ * Applies and removes styles from selection and elements.
+ */
+export default class StyleCommand extends Command {
+    /**
+     * Set of currently applied styles on the current selection.
+     *
+     * Names of styles correspond to the `name` property of
+     * {@link module:style/styleconfig~StyleDefinition configured definitions}.
+     *
+     * @observable
+     */
+    value: Array<string>;
+    /**
+     * 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/styleconfig~StyleDefinition configured definitions}.
+     *
+     * @observable
+     */
+    enabledStyles: Array<string>;
+    /**
+     * Normalized definitions of the styles.
+     */
+    private readonly _styleDefinitions;
+    /**
+     * The StyleUtils plugin.
+     */
+    private _styleUtils;
+    /**
+     * Creates an instance of the command.
+     *
+     * @param editor Editor on which this command will be used.
+     * @param styleDefinitions Normalized definitions of the styles.
+     */
+    constructor(editor: Editor, styleDefinitions: NormalizedStyleDefinitions);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command &ndash; 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}.
+     *
+     * * When applying block styles:
+     *   * If the selection is on a range, the command applies the style classes to the nearest block parent element.
+     *
+     * @fires execute
+     * @param options Command options.
+     * @param options.styleName Style name matching the one defined in the
+     * {@link module:style/styleconfig~StyleConfig#definitions configuration}.
+     * @param options.forceValue Whether the command should add given style (`true`) or remove it (`false`) from the selection.
+     * If not set (default), the command will toggle the style basing on the first selected node. Note, that this will not force
+     * setting a style on an element that cannot receive given style.
+     */
+    execute({ styleName, forceValue }: {
+        styleName: string;
+        forceValue?: boolean;
+    }): void;
+    /**
+     * Returns a set of elements that should be affected by the block-style change.
+     */
+    private _findAffectedBlocks;
+}

package/src/stylecommand.js

@@ -0,0 +1,200 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Command } from 'ckeditor5/src/core.js';
+import { logWarning, first } from 'ckeditor5/src/utils.js';
+import StyleUtils from './styleutils.js';
+/**
+ * Style command.
+ *
+ * Applies and removes styles from selection and elements.
+ */
+export default class StyleCommand extends Command {
+    /**
+     * Creates an instance of the command.
+     *
+     * @param editor Editor on which this command will be used.
+     * @param styleDefinitions Normalized definitions of the styles.
+     */
+    constructor(editor, styleDefinitions) {
+        super(editor);
+        this.set('value', []);
+        this.set('enabledStyles', []);
+        this._styleDefinitions = styleDefinitions;
+        this._styleUtils = this.editor.plugins.get(StyleUtils);
+    }
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const model = this.editor.model;
+        const selection = model.document.selection;
+        const value = new Set();
+        const enabledStyles = new Set();
+        // Inline styles.
+        for (const definition of this._styleDefinitions.inline) {
+            // Check if this inline style is enabled.
+            if (this._styleUtils.isStyleEnabledForInlineSelection(definition, selection)) {
+                enabledStyles.add(definition.name);
+            }
+            // Check if this inline style is active.
+            if (this._styleUtils.isStyleActiveForInlineSelection(definition, selection)) {
+                value.add(definition.name);
+            }
+        }
+        // Block styles.
+        const firstBlock = first(selection.getSelectedBlocks()) || selection.getFirstPosition().parent;
+        if (firstBlock) {
+            const ancestorBlocks = firstBlock.getAncestors({ includeSelf: true, parentFirst: true });
+            for (const block of ancestorBlocks) {
+                if (block.is('rootElement')) {
+                    break;
+                }
+                for (const definition of this._styleDefinitions.block) {
+                    // Check if this block style is enabled.
+                    if (!this._styleUtils.isStyleEnabledForBlock(definition, block)) {
+                        continue;
+                    }
+                    enabledStyles.add(definition.name);
+                    // Check if this block style is active.
+                    if (this._styleUtils.isStyleActiveForBlock(definition, block)) {
+                        value.add(definition.name);
+                    }
+                }
+                // E.g. reached a model table when the selection is in a cell. The command should not modify
+                // ancestors of a table.
+                if (model.schema.isObject(block)) {
+                    break;
+                }
+            }
+        }
+        this.enabledStyles = Array.from(enabledStyles).sort();
+        this.isEnabled = this.enabledStyles.length > 0;
+        this.value = this.isEnabled ? Array.from(value).sort() : [];
+    }
+    /**
+     * Executes the command – 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}.
+     *
+     * * When applying block styles:
+     *   * If the selection is on a range, the command applies the style classes to the nearest block parent element.
+     *
+     * @fires execute
+     * @param options Command options.
+     * @param options.styleName Style name matching the one defined in the
+     * {@link module:style/styleconfig~StyleConfig#definitions configuration}.
+     * @param options.forceValue Whether the command should add given style (`true`) or remove it (`false`) from the selection.
+     * If not set (default), the command will toggle the style basing on the first selected node. Note, that this will not force
+     * setting a style on an element that cannot receive given style.
+     */
+    execute({ styleName, forceValue }) {
+        if (!this.enabledStyles.includes(styleName)) {
+            /**
+             * Style command can be executed only with a correct style name.
+             *
+             * This warning may be caused by:
+             *
+             * * passing a name that is not specified in the {@link module:style/styleconfig~StyleConfig#definitions configuration}
+             * (e.g. a CSS class name),
+             * * when trying to apply a style that is not allowed on a given element.
+             *
+             * @error style-command-executed-with-incorrect-style-name
+             */
+            logWarning('style-command-executed-with-incorrect-style-name');
+            return;
+        }
+        const model = this.editor.model;
+        const selection = model.document.selection;
+        const htmlSupport = this.editor.plugins.get('GeneralHtmlSupport');
+        const allDefinitions = [
+            ...this._styleDefinitions.inline,
+            ...this._styleDefinitions.block
+        ];
+        const activeDefinitions = allDefinitions.filter(({ name }) => this.value.includes(name));
+        const definition = allDefinitions.find(({ name }) => name == styleName);
+        const shouldAddStyle = forceValue === undefined ? !this.value.includes(definition.name) : forceValue;
+        model.change(() => {
+            let selectables;
+            if (isBlockStyleDefinition(definition)) {
+                selectables = this._findAffectedBlocks(getBlocksFromSelection(selection), definition);
+            }
+            else {
+                selectables = [this._styleUtils.getAffectedInlineSelectable(definition, selection)];
+            }
+            for (const selectable of selectables) {
+                if (shouldAddStyle) {
+                    htmlSupport.addModelHtmlClass(definition.element, definition.classes, selectable);
+                }
+                else {
+                    htmlSupport.removeModelHtmlClass(definition.element, getDefinitionExclusiveClasses(activeDefinitions, definition), selectable);
+                }
+            }
+        });
+    }
+    /**
+     * Returns a set of elements that should be affected by the block-style change.
+     */
+    _findAffectedBlocks(selectedBlocks, definition) {
+        const blocks = new Set();
+        for (const selectedBlock of selectedBlocks) {
+            const ancestorBlocks = selectedBlock.getAncestors({ includeSelf: true, parentFirst: true });
+            for (const block of ancestorBlocks) {
+                if (block.is('rootElement')) {
+                    break;
+                }
+                const affectedBlocks = this._styleUtils.getAffectedBlocks(definition, block);
+                if (affectedBlocks) {
+                    for (const affectedBlock of affectedBlocks) {
+                        blocks.add(affectedBlock);
+                    }
+                    break;
+                }
+            }
+        }
+        return blocks;
+    }
+}
+/**
+ * Returns classes that are defined only in the supplied definition and not in any other active definition. It's used
+ * to ensure that classes used by other definitions are preserved when a style is removed. See #11748.
+ *
+ * @param activeDefinitions All currently active definitions affecting selected element(s).
+ * @param definition Definition whose classes will be compared with all other active definition classes.
+ * @returns Array of classes exclusive to the supplied definition.
+ */
+function getDefinitionExclusiveClasses(activeDefinitions, definition) {
+    return activeDefinitions.reduce((classes, currentDefinition) => {
+        if (currentDefinition.name === definition.name) {
+            return classes;
+        }
+        return classes.filter(className => !currentDefinition.classes.includes(className));
+    }, definition.classes);
+}
+/**
+ * Checks if provided style definition is of type block.
+ */
+function isBlockStyleDefinition(definition) {
+    return 'isBlock' in definition;
+}
+/**
+ * Gets block elements from selection. If there are none, returns first selected element.
+ * @param selection Current document's selection.
+ * @returns Selected blocks if there are any, first selected element otherwise.
+ */
+function getBlocksFromSelection(selection) {
+    const blocks = Array.from(selection.getSelectedBlocks());
+    if (blocks.length) {
+        return blocks;
+    }
+    return [selection.getFirstPosition().parent];
+}

package/src/styleconfig.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module style/styleconfig
+ */
+/**
+ * The configuration of the style feature.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     style: ... // Style feature config.
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface StyleConfig {
+    /**
+     * The available style definitions.
+     *
+     * Style definitions are displayed in the `'style'` UI dropdown and get applied by the
+     * {@link module:style/stylecommand~StyleCommand style command} to the content of the document.
+     *
+     * In the `'style'` UI dropdown, definitions are automatically grouped into two categories based on the of the `element` property:
+     *
+     * * **Block styles**: Can be applied to entire {@link module:html-support/dataschema~DataSchema#registerBlockElement block elements}
+     * only (e.g. headings, paragraphs, divs).
+     * * **Text styles**: Can by applied to any {@link module:html-support/dataschema~DataSchema#registerInlineElement text} in any element
+     * in the document.
+     *
+     * An example configuration:
+     *
+     * ```ts
+     * [
+     *   // Definitions of block styles.
+     *   {
+     *     name: 'Red heading',
+     *     element: 'h2',
+     *     classes: [ 'red-heading' ]
+     *   },
+     *   {
+     *     name: 'Vibrant code',
+     *     element: 'pre',
+     *     classes: [ 'vibrant-code' ]
+     *   },
+     *
+     *   // Definitions of text (inline) styles.
+     *   {
+     *     name: 'Marker',
+     *     element: 'span',
+     *     classes: [ 'marker' ]
+     *   },
+     *
+     *   // ...
+     * ]
+     * ```
+     *
+     * **Note**: Configuring style definitions will automatically configure the
+     * {@glink features/html/general-html-support General HTML Support feature}. **You do not need to repeat the configuration in
+     * {@link module:html-support/generalhtmlsupportconfig~GeneralHtmlSupportConfig}**.
+     */
+    definitions?: Array<StyleDefinition>;
+}
+/**
+ * Style definition.
+ *
+ * An object describing a style definition. It contains the style `name`, `element` name and an array of CSS `classes`.
+ *
+ * ```ts
+ * // This style will create <h2 class="foo">...</h2> in the document data.
+ * {
+ *   name: 'Example style',
+ *   element: 'h2',
+ *   classes: [ 'foo' ]
+ * }
+ * ```
+ */
+export interface StyleDefinition {
+    name: string;
+    element: string;
+    classes: Array<string>;
+}

package/src/styleconfig.js

@@ -0,0 +1,5 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+export {};

package/src/styleediting.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import StyleUtils from './styleutils.js';
+import ListStyleSupport from './integrations/list.js';
+import TableStyleSupport from './integrations/table.js';
+import LinkStyleSupport from './integrations/link.js';
+/**
+ * The style engine feature.
+ *
+ * It configures the {@glink features/html/general-html-support General HTML Support feature} based on
+ * {@link module:style/styleconfig~StyleConfig#definitions configured style definitions} and introduces the
+ * {@link module:style/stylecommand~StyleCommand style command} that applies styles to the content of the document.
+ */
+export default class StyleEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "StyleEditing";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly ["GeneralHtmlSupport", typeof StyleUtils, typeof ListStyleSupport, typeof TableStyleSupport, typeof LinkStyleSupport];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/src/styleediting.js

@@ -0,0 +1,52 @@
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import StyleCommand from './stylecommand.js';
+import StyleUtils from './styleutils.js';
+import ListStyleSupport from './integrations/list.js';
+import TableStyleSupport from './integrations/table.js';
+import LinkStyleSupport from './integrations/link.js';
+/**
+ * The style engine feature.
+ *
+ * It configures the {@glink features/html/general-html-support General HTML Support feature} based on
+ * {@link module:style/styleconfig~StyleConfig#definitions configured style definitions} and introduces the
+ * {@link module:style/stylecommand~StyleCommand style command} that applies styles to the content of the document.
+ */
+export default class StyleEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'StyleEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return ['GeneralHtmlSupport', StyleUtils, ListStyleSupport, TableStyleSupport, LinkStyleSupport];
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const dataSchema = editor.plugins.get('DataSchema');
+        const styleUtils = editor.plugins.get('StyleUtils');
+        const styleDefinitions = editor.config.get('style.definitions');
+        const normalizedStyleDefinitions = styleUtils.normalizeConfig(dataSchema, styleDefinitions);
+        editor.commands.add('style', new StyleCommand(editor, normalizedStyleDefinitions));
+        styleUtils.configureGHSDataFilter(normalizedStyleDefinitions);
+    }
+}

package/src/styleui.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import StyleUtils from './styleutils.js';
+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.
+ */
+export default class StyleUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "StyleUI";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof StyleUtils];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/src/styleui.js

@@ -0,0 +1,100 @@
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import { createDropdown } from 'ckeditor5/src/ui.js';
+import StylePanelView from './ui/stylepanelview.js';
+import StyleUtils from './styleutils.js';
+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.
+ */
+export default class StyleUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'StyleUI';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [StyleUtils];
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const dataSchema = editor.plugins.get('DataSchema');
+        const styleUtils = editor.plugins.get('StyleUtils');
+        const styleDefinitions = editor.config.get('style.definitions');
+        const normalizedStyleDefinitions = styleUtils.normalizeConfig(dataSchema, styleDefinitions);
+        // Add the dropdown to the component factory.
+        editor.ui.componentFactory.add('style', locale => {
+            const t = locale.t;
+            const dropdown = createDropdown(locale);
+            const styleCommand = editor.commands.get('style');
+            dropdown.once('change:isOpen', () => {
+                const panelView = new StylePanelView(locale, normalizedStyleDefinitions);
+                // Put the styles panel is the dropdown.
+                dropdown.panelView.children.add(panelView);
+                // Close the dropdown when a style is selected in the styles panel.
+                panelView.delegate('execute').to(dropdown);
+                // Bind the state of the styles panel to the command.
+                panelView.bind('activeStyles').to(styleCommand, 'value');
+                panelView.bind('enabledStyles').to(styleCommand, 'enabledStyles');
+            });
+            // The entire dropdown will be disabled together with the command (e.g. when the editor goes read-only).
+            dropdown.bind('isEnabled').to(styleCommand);
+            // 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(' ');
+            });
+            // Execute the command when a style is selected in the styles panel.
+            // Also focus the editable after executing the command.
+            // It overrides a default behaviour where the focus is moved to the dropdown button (#12125).
+            dropdown.on('execute', evt => {
+                editor.execute('style', { styleName: evt.source.styleDefinition.name });
+                editor.editing.view.focus();
+            });
+            return dropdown;
+        });
+    }
+}