@ckeditor/ckeditor5-style 41.2.0 → 41.3.0-alpha.0

package/dist/types/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @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
+ */
+export { default as Style } from './style.js';
+export { default as StyleEditing } from './styleediting.js';
+export { default as StyleUI } from './styleui.js';
+export { default as StyleUtils } from './styleutils.js';
+export type { StyleConfig, StyleDefinition } from './styleconfig.js';
+export type { default as StyleCommand } from './stylecommand.js';
+import './augmentation.js';

package/dist/types/integrations/link.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/integrations/link
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import StyleUtils from '../styleutils.js';
+export default class LinkStyleSupport extends Plugin {
+    private _styleUtils;
+    private _htmlSupport;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LinkStyleSupport";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof StyleUtils, "GeneralHtmlSupport"];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Verifies if the given style is applicable to the provided document selection.
+     */
+    private _isStyleEnabled;
+    /**
+     * Returns true if the given style is applied to the specified document selection.
+     */
+    private _isStyleActive;
+    /**
+     * Returns a selectable that given style should be applied to.
+     */
+    private _getAffectedSelectable;
+}

package/dist/types/integrations/list.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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/integrations/list
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import StyleUtils from '../styleutils.js';
+export default class ListStyleSupport extends Plugin {
+    private _listUtils;
+    private _styleUtils;
+    private _htmlSupport;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ListStyleSupport";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof StyleUtils, "GeneralHtmlSupport"];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Verifies if the given style is applicable to the provided block element.
+     */
+    private _isStyleEnabledForBlock;
+    /**
+     * Returns true if the given style is applied to the specified block element.
+     */
+    private _isStyleActiveForBlock;
+    /**
+     * Returns an array of block elements that style should be applied to.
+     */
+    private _getAffectedBlocks;
+    /**
+     * Returns a view template definition for the style preview.
+     */
+    private _getStylePreview;
+}

package/dist/types/integrations/table.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @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/integrations/table
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import StyleUtils from '../styleutils.js';
+export default class TableStyleSupport extends Plugin {
+    private _tableUtils;
+    private _styleUtils;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableStyleSupport";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof StyleUtils];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Checks if this plugin's custom logic should be applied for defintion-block pair.
+     *
+     * @param definition Style definition that is being considered.
+     * @param block Block element to check if should be styled.
+     * @returns True if the defintion-block pair meet the plugin criteria, false otherwise.
+     */
+    private _isApplicable;
+    /**
+     * Checks if the style definition should be applied to selected block.
+     *
+     * @param definition Style definition that is being considered.
+     * @param block Block element to check if should be styled.
+     * @returns True if the block should be style with the style description, false otherwise.
+     */
+    private _isStyleEnabledForBlock;
+    /**
+     * Gets all blocks that the style should be applied to.
+     *
+     * @param definition Style definition that is being considered.
+     * @param block A block element from selection.
+     * @returns An array with the block that was passed as an argument if meets the criteria, null otherwise.
+     */
+    private _getAffectedBlocks;
+}

package/dist/types/style.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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 requires(): readonly [typeof StyleEditing, typeof StyleUI];
+}

package/dist/types/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/dist/types/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/dist/types/styleediting.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @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 requires(): readonly ["GeneralHtmlSupport", typeof StyleUtils, typeof ListStyleSupport, typeof TableStyleSupport, typeof LinkStyleSupport];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/styleui.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/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 requires(): readonly [typeof StyleUtils];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/styleutils.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @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
+     */
+    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/dist/types/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/dist/types/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: [];
+};