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

package/dist/types/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
+ */
+/**
+ * @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,38 @@
+/**
+ * @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
+ */
+/**
+ * @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,76 @@
+/**
+ * @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
+ */
+/**
+ * @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/dist/types/ui/stylegroupview.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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
+ */
+/**
+ * @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/stylegroupview
+ */
+import { LabelView, View } from 'ckeditor5/src/ui.js';
+import type { Locale } from 'ckeditor5/src/utils.js';
+import StyleGridView from './stylegridview.js';
+import type { NormalizedStyleDefinition } from '../styleutils.js';
+import '../../theme/stylegroup.css';
+/**
+ * A class representing a group of styles (e.g. "block" or "inline").
+ *
+ * Renders a {@link module:style/ui/stylegridview~StyleGridView style grid} and a label.
+ */
+export default class StyleGroupView extends View<HTMLDivElement> {
+    /**
+     * The styles grid of the group.
+     */
+    readonly gridView: StyleGridView;
+    /**
+     * The label of the group.
+     */
+    readonly labelView: LabelView;
+    /**
+     * Creates an instance of the {@link module:style/ui/stylegroupview~StyleGroupView} class.
+     *
+     * @param locale The localization services instance.
+     * @param label The localized label of the group.
+     * @param styleDefinitions Definitions of the styles in the group.
+     */
+    constructor(locale: Locale, label: string, styleDefinitions: Array<NormalizedStyleDefinition>);
+}

package/dist/types/ui/stylepanelview.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @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
+ */
+/**
+ * @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/stylepanelview
+ */
+import { FocusCycler, View, ViewCollection } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import StyleGroupView from './stylegroupview.js';
+import type StyleGridView from './stylegridview.js';
+import type { NormalizedStyleDefinitions } from '../styleutils.js';
+import '../../theme/stylepanel.css';
+/**
+ * A class representing a panel with available content styles. It renders styles in button grids, grouped
+ * in categories.
+ */
+export default class StylePanelView extends View<HTMLDivElement> {
+    /**
+     * Tracks information about DOM focus in the panel.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * A collection of panel children.
+     */
+    readonly children: ViewCollection<StyleGroupView>;
+    /**
+     * A view representing block styles group.
+     */
+    readonly blockStylesGroupView: StyleGroupView;
+    /**
+     * A view representing inline styles group
+     */
+    readonly inlineStylesGroupView: StyleGroupView;
+    /**
+     * 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>;
+    /**
+     * A collection of views that can be focused in the panel.
+     */
+    protected readonly _focusables: ViewCollection<StyleGridView>;
+    /**
+     * Helps cycling over {@link #_focusables} in the panel.
+     */
+    protected readonly _focusCycler: FocusCycler;
+    /**
+     * Creates an instance of the {@link module:style/ui/stylegroupview~StyleGroupView} class.
+     *
+     * @param locale The localization services instance.
+     * @param styleDefinitions Normalized definitions of the styles.
+     */
+    constructor(locale: Locale, styleDefinitions: NormalizedStyleDefinitions);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the first focusable element in the panel.
+     */
+    focus(): void;
+    /**
+     * Focuses the last focusable element in the panel.
+     */
+    focusLast(): void;
+}
+/**
+ * Fired when a style was selected (clicked) by the user.
+ *
+ * @eventName ~StylePanelView#execute
+ */
+export type StylePanelViewExecuteEvent = {
+    name: 'execute';
+    args: [];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-style",
-  "version": "41.3.0",
+  "version": "41.4.0-alpha.0",
   "description": "Style feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -13,7 +13,7 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "41.3.0",
+    "ckeditor5": "41.4.0-alpha.0",
     "lodash-es": "4.17.21"
   },
   "author": "CKSource (http://cksource.com/)",
@@ -26,6 +26,7 @@
     "directory": "packages/ckeditor5-style"
   },
   "files": [
+    "dist",
     "lang",
     "src/**/*.js",
     "src/**/*.d.ts",