@ckeditor/ckeditor5-alignment 0.0.0-internal-20241017.0

package/src/alignmentui.js

@@ -0,0 +1,194 @@
+/**
+ * @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 alignment/alignmentui
+ */
+import { Plugin, icons } from 'ckeditor5/src/core.js';
+import { ButtonView, createDropdown, addToolbarToDropdown, MenuBarMenuListItemView, MenuBarMenuListItemButtonView, MenuBarMenuView, MenuBarMenuListView } from 'ckeditor5/src/ui.js';
+import { isSupported, normalizeAlignmentOptions } from './utils.js';
+const iconsMap = /* #__PURE__ */ (() => new Map([
+    ['left', icons.alignLeft],
+    ['right', icons.alignRight],
+    ['center', icons.alignCenter],
+    ['justify', icons.alignJustify]
+]))();
+/**
+ * The default alignment UI plugin.
+ *
+ * It introduces the `'alignment:left'`, `'alignment:right'`, `'alignment:center'` and `'alignment:justify'` buttons
+ * and the `'alignment'` dropdown.
+ */
+export default class AlignmentUI extends Plugin {
+    /**
+     * Returns the localized option titles provided by the plugin.
+     *
+     * The following localized titles corresponding with
+     * {@link module:alignment/alignmentconfig~AlignmentConfig#options} are available:
+     *
+     * * `'left'`,
+     * * `'right'`,
+     * * `'center'`,
+     * * `'justify'`.
+     *
+     * @readonly
+     */
+    get localizedOptionTitles() {
+        const t = this.editor.t;
+        return {
+            'left': t('Align left'),
+            'right': t('Align right'),
+            'center': t('Align center'),
+            'justify': t('Justify')
+        };
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'AlignmentUI';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const options = normalizeAlignmentOptions(editor.config.get('alignment.options'));
+        options
+            .map(option => option.name)
+            .filter(isSupported)
+            .forEach(option => this._addButton(option));
+        this._addToolbarDropdown(options);
+        this._addMenuBarMenu(options);
+    }
+    /**
+     * Helper method for initializing the button and linking it with an appropriate command.
+     *
+     * @param option The name of the alignment option for which the button is added.
+     */
+    _addButton(option) {
+        const editor = this.editor;
+        editor.ui.componentFactory.add(`alignment:${option}`, locale => this._createButton(locale, option));
+    }
+    /**
+     * Helper method for creating the button view element.
+     *
+     * @param locale Editor locale.
+     * @param option The name of the alignment option for which the button is added.
+     * @param buttonAttrs Optional parameters passed to button view instance.
+     */
+    _createButton(locale, option, buttonAttrs = {}) {
+        const editor = this.editor;
+        const command = editor.commands.get('alignment');
+        const buttonView = new ButtonView(locale);
+        buttonView.set({
+            label: this.localizedOptionTitles[option],
+            icon: iconsMap.get(option),
+            tooltip: true,
+            isToggleable: true,
+            ...buttonAttrs
+        });
+        // Bind button model to command.
+        buttonView.bind('isEnabled').to(command);
+        buttonView.bind('isOn').to(command, 'value', value => value === option);
+        // Execute command.
+        this.listenTo(buttonView, 'execute', () => {
+            editor.execute('alignment', { value: option });
+            editor.editing.view.focus();
+        });
+        return buttonView;
+    }
+    /**
+     * Helper method for initializing the toolnar dropdown and linking it with an appropriate command.
+     *
+     * @param option The name of the alignment option for which the button is added.
+     */
+    _addToolbarDropdown(options) {
+        const editor = this.editor;
+        const factory = editor.ui.componentFactory;
+        factory.add('alignment', locale => {
+            const dropdownView = createDropdown(locale);
+            const tooltipPosition = locale.uiLanguageDirection === 'rtl' ? 'w' : 'e';
+            const t = locale.t;
+            // Add existing alignment buttons to dropdown's toolbar.
+            addToolbarToDropdown(dropdownView, () => options.map(option => this._createButton(locale, option.name, { tooltipPosition })), {
+                enableActiveItemFocusOnDropdownOpen: true,
+                isVertical: true,
+                ariaLabel: t('Text alignment toolbar')
+            });
+            // Configure dropdown properties an behavior.
+            dropdownView.buttonView.set({
+                label: t('Text alignment'),
+                tooltip: true
+            });
+            dropdownView.extendTemplate({
+                attributes: {
+                    class: 'ck-alignment-dropdown'
+                }
+            });
+            // The default icon depends on the direction of the content.
+            const defaultIcon = locale.contentLanguageDirection === 'rtl' ? iconsMap.get('right') : iconsMap.get('left');
+            const command = editor.commands.get('alignment');
+            // Change icon to reflect current selection's alignment.
+            dropdownView.buttonView.bind('icon').to(command, 'value', value => iconsMap.get(value) || defaultIcon);
+            // Enable button if any of the buttons is enabled.
+            dropdownView.bind('isEnabled').to(command, 'isEnabled');
+            // Focus the editable after executing the command.
+            // Overrides a default behaviour where the focus is moved to the dropdown button (#12125).
+            this.listenTo(dropdownView, 'execute', () => {
+                editor.editing.view.focus();
+            });
+            return dropdownView;
+        });
+    }
+    /**
+     * Creates a menu for all alignment options to use either in menu bar.
+     *
+     * @param options Normalized alignment options from config.
+     */
+    _addMenuBarMenu(options) {
+        const editor = this.editor;
+        editor.ui.componentFactory.add('menuBar:alignment', locale => {
+            const command = editor.commands.get('alignment');
+            const t = locale.t;
+            const menuView = new MenuBarMenuView(locale);
+            const listView = new MenuBarMenuListView(locale);
+            menuView.bind('isEnabled').to(command);
+            listView.set({
+                ariaLabel: t('Text alignment'),
+                role: 'menu'
+            });
+            menuView.buttonView.set({
+                label: t('Text alignment')
+            });
+            for (const option of options) {
+                const listItemView = new MenuBarMenuListItemView(locale, menuView);
+                const buttonView = new MenuBarMenuListItemButtonView(locale);
+                buttonView.delegate('execute').to(menuView);
+                buttonView.set({
+                    label: this.localizedOptionTitles[option.name],
+                    icon: iconsMap.get(option.name),
+                    role: 'menuitemcheckbox',
+                    isToggleable: true
+                });
+                buttonView.on('execute', () => {
+                    editor.execute('alignment', { value: option.name });
+                    editor.editing.view.focus();
+                });
+                buttonView.bind('isOn').to(command, 'value', value => value === option.name);
+                buttonView.bind('isEnabled').to(command, 'isEnabled');
+                listItemView.children.add(buttonView);
+                listView.items.add(listItemView);
+            }
+            menuView.panelView.children.add(listView);
+            return menuView;
+        });
+    }
+}

package/src/augmentation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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 type { Alignment, AlignmentEditing, AlignmentUI, AlignmentCommand, AlignmentConfig } from './index.js';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The configuration of the {@link module:alignment/alignment~Alignment alignment feature}.
+         *
+         * Read more in {@link module:alignment/alignmentconfig~AlignmentConfig}.
+         */
+        alignment?: AlignmentConfig;
+    }
+    interface PluginsMap {
+        [Alignment.pluginName]: Alignment;
+        [AlignmentUI.pluginName]: AlignmentUI;
+        [AlignmentEditing.pluginName]: AlignmentEditing;
+    }
+    interface CommandsMap {
+        alignment: AlignmentCommand;
+    }
+}

package/src/augmentation.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/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @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 alignment
+ */
+export { default as Alignment } from './alignment.js';
+export { default as AlignmentEditing } from './alignmentediting.js';
+export { default as AlignmentUI } from './alignmentui.js';
+export type { default as AlignmentCommand } from './alignmentcommand.js';
+export type { AlignmentConfig } from './alignmentconfig.js';
+import './augmentation.js';

package/src/index.js

@@ -0,0 +1,11 @@
+/**
+ * @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 alignment
+ */
+export { default as Alignment } from './alignment.js';
+export { default as AlignmentEditing } from './alignmentediting.js';
+export { default as AlignmentUI } from './alignmentui.js';
+import './augmentation.js';

package/src/utils.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
+ */
+import { type Locale } from 'ckeditor5/src/utils.js';
+import type { AlignmentFormat, SupportedOption } from './alignmentconfig.js';
+/**
+ * @module alignment/utils
+ */
+/**
+ * The list of supported alignment options:
+ *
+ * * `'left'`,
+ * * `'right'`,
+ * * `'center'`,
+ * * `'justify'`
+ */
+export declare const supportedOptions: ReadonlyArray<SupportedOption>;
+/**
+ * Checks whether the passed option is supported by {@link module:alignment/alignmentediting~AlignmentEditing}.
+ *
+ * @param option The option value to check.
+ */
+export declare function isSupported(option: string): boolean;
+/**
+ * Checks whether alignment is the default one considering the direction
+ * of the editor content.
+ *
+ * @param alignment The name of the alignment to check.
+ * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+ */
+export declare function isDefault(alignment: string, locale: Locale): boolean;
+/**
+ * Brings the configuration to the common form, an array of objects.
+ *
+ * @param configuredOptions Alignment plugin configuration.
+ * @returns Normalized object holding the configuration.
+ */
+export declare function normalizeAlignmentOptions(configuredOptions: Array<string | AlignmentFormat>): Array<AlignmentFormat>;

package/src/utils.js

@@ -0,0 +1,118 @@
+/**
+ * @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 { CKEditorError, logWarning } from 'ckeditor5/src/utils.js';
+/**
+ * @module alignment/utils
+ */
+/**
+ * The list of supported alignment options:
+ *
+ * * `'left'`,
+ * * `'right'`,
+ * * `'center'`,
+ * * `'justify'`
+ */
+export const supportedOptions = ['left', 'right', 'center', 'justify'];
+/**
+ * Checks whether the passed option is supported by {@link module:alignment/alignmentediting~AlignmentEditing}.
+ *
+ * @param option The option value to check.
+ */
+export function isSupported(option) {
+    return supportedOptions.includes(option);
+}
+/**
+ * Checks whether alignment is the default one considering the direction
+ * of the editor content.
+ *
+ * @param alignment The name of the alignment to check.
+ * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+ */
+export function isDefault(alignment, locale) {
+    // Right now only LTR is supported so the 'left' value is always the default one.
+    if (locale.contentLanguageDirection == 'rtl') {
+        return alignment === 'right';
+    }
+    else {
+        return alignment === 'left';
+    }
+}
+/**
+ * Brings the configuration to the common form, an array of objects.
+ *
+ * @param configuredOptions Alignment plugin configuration.
+ * @returns Normalized object holding the configuration.
+ */
+export function normalizeAlignmentOptions(configuredOptions) {
+    const normalizedOptions = configuredOptions
+        .map(option => {
+        let result;
+        if (typeof option == 'string') {
+            result = { name: option };
+        }
+        else {
+            result = option;
+        }
+        return result;
+    })
+        // Remove all unknown options.
+        .filter(option => {
+        const isNameValid = supportedOptions.includes(option.name);
+        if (!isNameValid) {
+            /**
+             * The `name` in one of the `alignment.options` is not recognized.
+             * The available options are: `'left'`, `'right'`, `'center'` and `'justify'`.
+             *
+             * @error alignment-config-name-not-recognized
+             * @param option Options with unknown value of the `name` property.
+             */
+            logWarning('alignment-config-name-not-recognized', { option });
+        }
+        return isNameValid;
+    });
+    const classNameCount = normalizedOptions.filter(option => Boolean(option.className)).length;
+    // We either use classes for all styling options or for none.
+    if (classNameCount && classNameCount < normalizedOptions.length) {
+        /**
+         * The `className` property has to be defined for all options once at least one option declares `className`.
+         *
+         * @error alignment-config-classnames-are-missing
+         * @param configuredOptions Contents of `alignment.options`.
+         */
+        throw new CKEditorError('alignment-config-classnames-are-missing', { configuredOptions });
+    }
+    // Validate resulting config.
+    normalizedOptions.forEach((option, index, allOptions) => {
+        const succeedingOptions = allOptions.slice(index + 1);
+        const nameAlreadyExists = succeedingOptions.some(item => item.name == option.name);
+        if (nameAlreadyExists) {
+            /**
+             * The same `name` in one of the `alignment.options` was already declared.
+             * Each `name` representing one alignment option can be set exactly once.
+             *
+             * @error alignment-config-name-already-defined
+             * @param option First option that declares given `name`.
+             * @param configuredOptions Contents of `alignment.options`.
+             */
+            throw new CKEditorError('alignment-config-name-already-defined', { option, configuredOptions });
+        }
+        // The `className` property is present. Check for duplicates then.
+        if (option.className) {
+            const classNameAlreadyExists = succeedingOptions.some(item => item.className == option.className);
+            if (classNameAlreadyExists) {
+                /**
+                 * The same `className` in one of the `alignment.options` was already declared.
+                 *
+                 * @error alignment-config-classname-already-defined
+                 * @param option First option that declares given `className`.
+                 * @param configuredOptions
+                 * Contents of `alignment.options`.
+                 */
+                throw new CKEditorError('alignment-config-classname-already-defined', { option, configuredOptions });
+            }
+        }
+    });
+    return normalizedOptions;
+}