@ckeditor/ckeditor5-style 0.0.0-internal-20241017.0

package/src/styleutils.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @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/styleutils
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import type { Element, DocumentSelection, Selectable } from 'ckeditor5/src/engine.js';
+import type { DecoratedMethodEvent } from 'ckeditor5/src/utils.js';
+import type { TemplateDefinition } from 'ckeditor5/src/ui.js';
+import type { DataSchema } from '@ckeditor/ckeditor5-html-support';
+import type { StyleDefinition } from './styleconfig.js';
+export default class StyleUtils extends Plugin {
+    private _htmlSupport;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "StyleUtils";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Normalizes {@link module:style/styleconfig~StyleConfig#definitions} in the configuration of the styles feature.
+     * The structure of normalized styles looks as follows:
+     *
+     * ```ts
+     * {
+     * 	block: [
+     * 		<module:style/style~StyleDefinition>,
+     * 		<module:style/style~StyleDefinition>,
+     * 		...
+     * 	],
+     * 	inline: [
+     * 		<module:style/style~StyleDefinition>,
+     * 		<module:style/style~StyleDefinition>,
+     * 		...
+     * 	]
+     * }
+     * ```
+     *
+     * @returns An object with normalized style definitions grouped into `block` and `inline` categories (arrays).
+     */
+    normalizeConfig(dataSchema: DataSchema, styleDefinitions?: Array<StyleDefinition>): NormalizedStyleDefinitions;
+    /**
+     * Verifies if the given style is applicable to the provided block element.
+     *
+     * @internal
+     */
+    isStyleEnabledForBlock(definition: BlockStyleDefinition, block: Element): boolean;
+    /**
+     * Returns true if the given style is applied to the specified block element.
+     *
+     * @internal
+     */
+    isStyleActiveForBlock(definition: BlockStyleDefinition, block: Element): boolean;
+    /**
+     * Returns an array of block elements that style should be applied to.
+     *
+     * @internal
+     */
+    getAffectedBlocks(definition: BlockStyleDefinition, block: Element): Array<Element> | null;
+    /**
+     * Verifies if the given style is applicable to the provided document selection.
+     *
+     * @internal
+     */
+    isStyleEnabledForInlineSelection(definition: InlineStyleDefinition, selection: DocumentSelection): boolean;
+    /**
+     * Returns true if the given style is applied to the specified document selection.
+     *
+     * @internal
+     */
+    isStyleActiveForInlineSelection(definition: InlineStyleDefinition, selection: DocumentSelection): boolean;
+    /**
+     * Returns a selectable that given style should be applied to.
+     *
+     * @internal
+     */
+    getAffectedInlineSelectable(definition: InlineStyleDefinition, selection: DocumentSelection): Selectable;
+    /**
+     * Returns the `TemplateDefinition` used by styles dropdown to render style preview.
+     *
+     * @internal
+     */
+    getStylePreview(definition: StyleDefinition, children: Iterable<TemplateDefinition>): TemplateDefinition;
+    /**
+     * Verifies if all classes are present in the given GHS attribute.
+     *
+     * @internal
+     */
+    hasAllClasses(ghsAttributeValue: unknown, classes: Array<string>): boolean;
+    /**
+     * This is where the styles feature configures the GHS feature. This method translates normalized
+     * {@link module:style/styleconfig~StyleDefinition style definitions} to
+     * {@link module:engine/view/matcher~MatcherObjectPattern matcher patterns} and feeds them to the GHS
+     * {@link module:html-support/datafilter~DataFilter} plugin.
+     *
+     * @internal
+     */
+    configureGHSDataFilter({ block, inline }: NormalizedStyleDefinitions): void;
+    /**
+     * Checks the attribute value of the first node in the selection that allows the attribute.
+     * For the collapsed selection, returns the selection attribute.
+     *
+     * @param selection The document selection.
+     * @param attributeName Name of the GHS attribute.
+     * @returns The attribute value.
+     */
+    private _getValueFromFirstAllowedNode;
+}
+export interface NormalizedStyleDefinitions {
+    block: Array<BlockStyleDefinition>;
+    inline: Array<InlineStyleDefinition>;
+}
+export interface BlockStyleDefinition extends StyleDefinition {
+    isBlock: true;
+    modelElements: Array<string>;
+    previewTemplate: TemplateDefinition;
+}
+export interface InlineStyleDefinition extends StyleDefinition {
+    ghsAttributes: Array<string>;
+    previewTemplate: TemplateDefinition;
+}
+export type NormalizedStyleDefinition = BlockStyleDefinition | InlineStyleDefinition;
+export type StyleUtilsIsEnabledForBlockEvent = DecoratedMethodEvent<StyleUtils, 'isStyleEnabledForBlock'>;
+export type StyleUtilsIsActiveForBlockEvent = DecoratedMethodEvent<StyleUtils, 'isStyleActiveForBlock'>;
+export type StyleUtilsGetAffectedBlocksEvent = DecoratedMethodEvent<StyleUtils, 'getAffectedBlocks'>;
+export type StyleUtilsIsStyleEnabledForInlineSelectionEvent = DecoratedMethodEvent<StyleUtils, 'isStyleEnabledForInlineSelection'>;
+export type StyleUtilsIsStyleActiveForInlineSelectionEvent = DecoratedMethodEvent<StyleUtils, 'isStyleActiveForInlineSelection'>;
+export type StyleUtilsGetAffectedInlineSelectableEvent = DecoratedMethodEvent<StyleUtils, 'getAffectedInlineSelectable'>;
+export type StyleUtilsGetStylePreviewEvent = DecoratedMethodEvent<StyleUtils, 'getStylePreview'>;
+export type StyleUtilsConfigureGHSDataFilterEvent = DecoratedMethodEvent<StyleUtils, 'configureGHSDataFilter'>;

package/src/styleutils.js

@@ -0,0 +1,274 @@
+/**
+ * @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/styleutils
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { isObject } from 'lodash-es';
+// 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'
+];
+export default class StyleUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'StyleUtils';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        super(editor);
+        this.decorate('isStyleEnabledForBlock');
+        this.decorate('isStyleActiveForBlock');
+        this.decorate('getAffectedBlocks');
+        this.decorate('isStyleEnabledForInlineSelection');
+        this.decorate('isStyleActiveForInlineSelection');
+        this.decorate('getAffectedInlineSelectable');
+        this.decorate('getStylePreview');
+        this.decorate('configureGHSDataFilter');
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        this._htmlSupport = this.editor.plugins.get('GeneralHtmlSupport');
+    }
+    /**
+     * Normalizes {@link module:style/styleconfig~StyleConfig#definitions} in the configuration of the styles feature.
+     * The structure of normalized styles looks as follows:
+     *
+     * ```ts
+     * {
+     * 	block: [
+     * 		<module:style/style~StyleDefinition>,
+     * 		<module:style/style~StyleDefinition>,
+     * 		...
+     * 	],
+     * 	inline: [
+     * 		<module:style/style~StyleDefinition>,
+     * 		<module:style/style~StyleDefinition>,
+     * 		...
+     * 	]
+     * }
+     * ```
+     *
+     * @returns An object with normalized style definitions grouped into `block` and `inline` categories (arrays).
+     */
+    normalizeConfig(dataSchema, styleDefinitions = []) {
+        const normalizedDefinitions = {
+            block: [],
+            inline: []
+        };
+        for (const definition of styleDefinitions) {
+            const modelElements = [];
+            const ghsAttributes = [];
+            for (const ghsDefinition of dataSchema.getDefinitionsForView(definition.element)) {
+                const appliesToBlock = 'appliesToBlock' in ghsDefinition ? ghsDefinition.appliesToBlock : false;
+                if (ghsDefinition.isBlock || appliesToBlock) {
+                    if (typeof appliesToBlock == 'string') {
+                        modelElements.push(appliesToBlock);
+                    }
+                    else if (ghsDefinition.isBlock) {
+                        const ghsBlockDefinition = ghsDefinition;
+                        modelElements.push(ghsDefinition.model);
+                        if (ghsBlockDefinition.paragraphLikeModel) {
+                            modelElements.push(ghsBlockDefinition.paragraphLikeModel);
+                        }
+                    }
+                }
+                else {
+                    ghsAttributes.push(ghsDefinition.model);
+                }
+            }
+            const previewTemplate = this.getStylePreview(definition, [
+                { text: 'AaBbCcDdEeFfGgHhIiJj' }
+            ]);
+            if (modelElements.length) {
+                normalizedDefinitions.block.push({
+                    ...definition,
+                    previewTemplate,
+                    modelElements,
+                    isBlock: true
+                });
+            }
+            else {
+                normalizedDefinitions.inline.push({
+                    ...definition,
+                    previewTemplate,
+                    ghsAttributes
+                });
+            }
+        }
+        return normalizedDefinitions;
+    }
+    /**
+     * Verifies if the given style is applicable to the provided block element.
+     *
+     * @internal
+     */
+    isStyleEnabledForBlock(definition, block) {
+        const model = this.editor.model;
+        const attributeName = this._htmlSupport.getGhsAttributeNameForElement(definition.element);
+        if (!model.schema.checkAttribute(block, attributeName)) {
+            return false;
+        }
+        return definition.modelElements.includes(block.name);
+    }
+    /**
+     * Returns true if the given style is applied to the specified block element.
+     *
+     * @internal
+     */
+    isStyleActiveForBlock(definition, block) {
+        const attributeName = this._htmlSupport.getGhsAttributeNameForElement(definition.element);
+        const ghsAttributeValue = block.getAttribute(attributeName);
+        return this.hasAllClasses(ghsAttributeValue, definition.classes);
+    }
+    /**
+     * Returns an array of block elements that style should be applied to.
+     *
+     * @internal
+     */
+    getAffectedBlocks(definition, block) {
+        if (definition.modelElements.includes(block.name)) {
+            return [block];
+        }
+        return null;
+    }
+    /**
+     * Verifies if the given style is applicable to the provided document selection.
+     *
+     * @internal
+     */
+    isStyleEnabledForInlineSelection(definition, selection) {
+        const model = this.editor.model;
+        for (const ghsAttributeName of definition.ghsAttributes) {
+            if (model.schema.checkAttributeInSelection(selection, ghsAttributeName)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Returns true if the given style is applied to the specified document selection.
+     *
+     * @internal
+     */
+    isStyleActiveForInlineSelection(definition, selection) {
+        for (const ghsAttributeName of definition.ghsAttributes) {
+            const ghsAttributeValue = this._getValueFromFirstAllowedNode(selection, ghsAttributeName);
+            if (this.hasAllClasses(ghsAttributeValue, definition.classes)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Returns a selectable that given style should be applied to.
+     *
+     * @internal
+     */
+    getAffectedInlineSelectable(definition, selection) {
+        return selection;
+    }
+    /**
+     * Returns the `TemplateDefinition` used by styles dropdown to render style preview.
+     *
+     * @internal
+     */
+    getStylePreview(definition, children) {
+        const { element, classes } = definition;
+        return {
+            tag: isPreviewable(element) ? element : 'div',
+            attributes: {
+                class: classes
+            },
+            children
+        };
+    }
+    /**
+     * Verifies if all classes are present in the given GHS attribute.
+     *
+     * @internal
+     */
+    hasAllClasses(ghsAttributeValue, classes) {
+        return isObject(ghsAttributeValue) &&
+            hasClassesProperty(ghsAttributeValue) &&
+            classes.every(className => ghsAttributeValue.classes.includes(className));
+    }
+    /**
+     * This is where the styles feature configures the GHS feature. This method translates normalized
+     * {@link module:style/styleconfig~StyleDefinition style definitions} to
+     * {@link module:engine/view/matcher~MatcherObjectPattern matcher patterns} and feeds them to the GHS
+     * {@link module:html-support/datafilter~DataFilter} plugin.
+     *
+     * @internal
+     */
+    configureGHSDataFilter({ block, inline }) {
+        const ghsDataFilter = this.editor.plugins.get('DataFilter');
+        ghsDataFilter.loadAllowedConfig(block.map(normalizedStyleDefinitionToMatcherPattern));
+        ghsDataFilter.loadAllowedConfig(inline.map(normalizedStyleDefinitionToMatcherPattern));
+    }
+    /**
+     * Checks the attribute value of the first node in the selection that allows the attribute.
+     * For the collapsed selection, returns the selection attribute.
+     *
+     * @param selection The document selection.
+     * @param attributeName Name of the GHS attribute.
+     * @returns The attribute value.
+     */
+    _getValueFromFirstAllowedNode(selection, attributeName) {
+        const model = this.editor.model;
+        const schema = model.schema;
+        if (selection.isCollapsed) {
+            return selection.getAttribute(attributeName);
+        }
+        for (const range of selection.getRanges()) {
+            for (const item of range.getItems()) {
+                if (schema.checkAttribute(item, attributeName)) {
+                    return item.getAttribute(attributeName);
+                }
+            }
+        }
+        return null;
+    }
+}
+/**
+ * Checks if given object has `classes` property which is an array.
+ *
+ * @param obj Object to check.
+ */
+function hasClassesProperty(obj) {
+    return Boolean(obj.classes) && Array.isArray(obj.classes);
+}
+/**
+ * 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.
+ *
+ * @param elementName Name of the element
+ * @returns Boolean indicating whether the element can be rendered.
+ */
+function isPreviewable(elementName) {
+    return !NON_PREVIEWABLE_ELEMENT_NAMES.includes(elementName);
+}
+/**
+ * Translates a normalized style definition to a view matcher pattern.
+ */
+function normalizedStyleDefinitionToMatcherPattern({ element, classes }) {
+    return {
+        name: element,
+        classes
+    };
+}

package/src/ui/stylegridbuttonview.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/ui/stylegridbuttonview
+ */
+import type { Locale } from 'ckeditor5/src/utils.js';
+import { ButtonView, View } from 'ckeditor5/src/ui.js';
+import type { NormalizedStyleDefinition } from '../styleutils.js';
+/**
+ * A class representing an individual button (style) in the grid. Renders a rich preview of the style.
+ */
+export default class StyleGridButtonView extends ButtonView {
+    /**
+     * Definition of the style the button will apply when executed.
+     */
+    readonly styleDefinition: NormalizedStyleDefinition;
+    /**
+     * The view rendering the preview of the style.
+     */
+    readonly previewView: View;
+    /**
+     * Creates an instance of the {@link module:style/ui/stylegridbuttonview~StyleGridButtonView} class.
+     *
+     * @param locale The localization services instance.
+     * @param styleDefinition Definition of the style.
+     */
+    constructor(locale: Locale, styleDefinition: NormalizedStyleDefinition);
+    /**
+     * Creates the view representing the preview of the style.
+     */
+    private _createPreview;
+}

package/src/ui/stylegridbuttonview.js

@@ -0,0 +1,55 @@
+/**
+ * @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 { ButtonView, View } from 'ckeditor5/src/ui.js';
+/**
+ * A class representing an individual button (style) in the grid. Renders a rich preview of the style.
+ */
+export default class StyleGridButtonView extends ButtonView {
+    /**
+     * Creates an instance of the {@link module:style/ui/stylegridbuttonview~StyleGridButtonView} class.
+     *
+     * @param locale The localization services instance.
+     * @param styleDefinition Definition of the style.
+     */
+    constructor(locale, styleDefinition) {
+        super(locale);
+        this.styleDefinition = styleDefinition;
+        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.
+     */
+    _createPreview() {
+        const previewView = new View(this.locale);
+        previewView.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-reset_all-excluded',
+                    'ck-style-grid__button__preview',
+                    'ck-content'
+                ],
+                // The preview "AaBbCcDdEeFfGgHhIiJj" should not be read by screen readers because it is purely presentational.
+                'aria-hidden': 'true'
+            },
+            children: [
+                this.styleDefinition.previewTemplate
+            ]
+        });
+        return previewView;
+    }
+}

package/src/ui/stylegridview.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @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/ui/stylegridview
+ */
+import { View, type ViewCollection, type FocusableView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import StyleGridButtonView from './stylegridbuttonview.js';
+import type { NormalizedStyleDefinition } from '../styleutils.js';
+import '../../theme/stylegrid.css';
+/**
+ * A class representing a grid of styles ({@link module:style/ui/stylegridbuttonview~StyleGridButtonView buttons}).
+ * Allows users to select a style.
+ */
+export default class StyleGridView extends View<HTMLDivElement> implements FocusableView {
+    /**
+     * Tracks information about the DOM focus in the view.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * A collection of style {@link module:style/ui/stylegridbuttonview~StyleGridButtonView buttons}.
+     */
+    readonly children: ViewCollection<StyleGridButtonView>;
+    /**
+     * Array of active style names. They must correspond to the names of styles from
+     * definitions passed to the {@link #constructor}.
+     *
+     * @observable
+     */
+    readonly activeStyles: Array<string>;
+    /**
+     * Array of enabled style names. They must correspond to the names of styles from
+     * definitions passed to the {@link #constructor}.
+     *
+     * @observable
+     */
+    readonly enabledStyles: Array<string>;
+    /**
+     * Creates an instance of the {@link module:style/ui/stylegridview~StyleGridView} class.
+     *
+     * @param locale The localization services instance.
+     * @param styleDefinitions Definitions of the styles.
+     */
+    constructor(locale: Locale, styleDefinitions: Array<NormalizedStyleDefinition>);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the first style button in the grid.
+     */
+    focus(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}
+/**
+ * Fired when a {@link module:style/ui/stylegridbuttonview~StyleGridButtonView style} was selected (clicked) by the user.
+ *
+ * @eventName ~StyleGridView#execute
+ */
+export type StyleGridViewExecuteEvent = {
+    name: 'execute';
+    args: [];
+};

package/src/ui/stylegridview.js

@@ -0,0 +1,89 @@
+/**
+ * @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/ui/stylegridview
+ */
+import { View, addKeyboardHandlingForGrid } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler } from 'ckeditor5/src/utils.js';
+import StyleGridButtonView from './stylegridbuttonview.js';
+import '../../theme/stylegrid.css';
+/**
+ * A class representing a grid of styles ({@link module:style/ui/stylegridbuttonview~StyleGridButtonView buttons}).
+ * Allows users to select a style.
+ */
+export default class StyleGridView extends View {
+    /**
+     * Creates an instance of the {@link module:style/ui/stylegridview~StyleGridView} class.
+     *
+     * @param locale The localization services instance.
+     * @param styleDefinitions Definitions of the styles.
+     */
+    constructor(locale, styleDefinitions) {
+        super(locale);
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        this.set('activeStyles', []);
+        this.set('enabledStyles', []);
+        this.children = this.createCollection();
+        this.children.delegate('execute').to(this);
+        for (const definition of styleDefinitions) {
+            const gridTileView = new StyleGridButtonView(locale, definition);
+            this.children.add(gridTileView);
+        }
+        this.on('change:activeStyles', () => {
+            for (const child of this.children) {
+                child.isOn = this.activeStyles.includes(child.styleDefinition.name);
+            }
+        });
+        this.on('change:enabledStyles', () => {
+            for (const child of this.children) {
+                child.isEnabled = this.enabledStyles.includes(child.styleDefinition.name);
+            }
+        });
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-style-grid'
+                ],
+                role: 'listbox'
+            },
+            children: this.children
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        for (const child of this.children) {
+            this.focusTracker.add(child.element);
+        }
+        addKeyboardHandlingForGrid({
+            keystrokeHandler: this.keystrokes,
+            focusTracker: this.focusTracker,
+            gridItems: this.children,
+            numberOfColumns: 3,
+            uiLanguageDirection: this.locale && this.locale.uiLanguageDirection
+        });
+        // Start listening for the keystrokes coming from the grid view.
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * Focuses the first style button in the grid.
+     */
+    focus() {
+        this.children.first.focus();
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+}