@ckeditor/ckeditor5-alignment 0.0.0-internal-20241017.0

package/lang/translations/zh.po

@@ -0,0 +1,42 @@
+# Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+#
+#                                     !!! IMPORTANT !!!
+#
+#         Before you edit this file, please keep in mind that contributing to the project
+#                translations is possible ONLY via the Transifex online service.
+#
+#         To submit your translations, visit https://www.transifex.com/ckeditor/ckeditor5.
+#
+#                   To learn more, check out the official contributor's guide:
+#     https://ckeditor.com/docs/ckeditor5/latest/framework/guides/contributing/contributing.html
+#
+msgid ""
+msgstr ""
+"Language-Team: Chinese (Taiwan) (https://app.transifex.com/ckeditor/teams/11143/zh_TW/)\n"
+"Language: zh_TW\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+
+msgctxt "Toolbar button tooltip for aligning the text to the left."
+msgid "Align left"
+msgstr "靠左對齊"
+
+msgctxt "Toolbar button tooltip for aligning the text to the right."
+msgid "Align right"
+msgstr "靠右對齊"
+
+msgctxt "Toolbar button tooltip for aligning the text to center."
+msgid "Align center"
+msgstr "置中對齊"
+
+msgctxt "Toolbar button tooltip for making the text justified."
+msgid "Justify"
+msgstr "左右對齊"
+
+msgctxt "Dropdown button tooltip for the text alignment feature."
+msgid "Text alignment"
+msgstr "文字對齊"
+
+msgctxt "Label used by assistive technologies describing the text alignment feature toolbar."
+msgid "Text alignment toolbar"
+msgstr "文字對齊"

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ckeditor/ckeditor5-alignment",
+  "version": "0.0.0-internal-20241017.0",
+  "description": "Text alignment feature for CKEditor 5.",
+  "keywords": [
+    "ckeditor",
+    "ckeditor5",
+    "ckeditor 5",
+    "ckeditor5-feature",
+    "ckeditor5-plugin",
+    "ckeditor5-dll"
+  ],
+  "type": "module",
+  "main": "src/index.js",
+  "dependencies": {
+    "@ckeditor/ckeditor5-core": "0.0.0-internal-20241017.0",
+    "@ckeditor/ckeditor5-ui": "0.0.0-internal-20241017.0",
+    "@ckeditor/ckeditor5-utils": "0.0.0-internal-20241017.0",
+    "ckeditor5": "0.0.0-internal-20241017.0"
+  },
+  "author": "CKSource (http://cksource.com/)",
+  "license": "GPL-2.0-or-later",
+  "homepage": "https://ckeditor.com/ckeditor-5",
+  "bugs": "https://github.com/ckeditor/ckeditor5/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ckeditor/ckeditor5.git",
+    "directory": "packages/ckeditor5-alignment"
+  },
+  "files": [
+    "dist",
+    "lang",
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "theme",
+    "build",
+    "ckeditor5-metadata.json",
+    "CHANGELOG.md"
+  ],
+  "types": "src/index.d.ts"
+}

package/src/alignment.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 alignment/alignment
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import AlignmentEditing from './alignmentediting.js';
+import AlignmentUI from './alignmentui.js';
+/**
+ * The text alignment plugin.
+ *
+ * For a detailed overview, check the {@glink features/text-alignment Text alignment} feature guide
+ * and the {@glink api/alignment package page}.
+ *
+ * This is a "glue" plugin which loads the {@link module:alignment/alignmentediting~AlignmentEditing} and
+ * {@link module:alignment/alignmentui~AlignmentUI} plugins.
+ */
+export default class Alignment extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof AlignmentEditing, typeof AlignmentUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Alignment";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+}

package/src/alignment.js

@@ -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
+ */
+/**
+ * @module alignment/alignment
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import AlignmentEditing from './alignmentediting.js';
+import AlignmentUI from './alignmentui.js';
+/**
+ * The text alignment plugin.
+ *
+ * For a detailed overview, check the {@glink features/text-alignment Text alignment} feature guide
+ * and the {@glink api/alignment package page}.
+ *
+ * This is a "glue" plugin which loads the {@link module:alignment/alignmentediting~AlignmentEditing} and
+ * {@link module:alignment/alignmentui~AlignmentUI} plugins.
+ */
+export default class Alignment extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [AlignmentEditing, AlignmentUI];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'Alignment';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+}

package/src/alignmentcommand.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @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/alignmentcommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+import type { SupportedOption } from './alignmentconfig.js';
+/**
+ * The alignment command plugin.
+ */
+export default class AlignmentCommand extends Command {
+    /**
+     * A value of the current block's alignment.
+     *
+     * @observable
+     * @readonly
+     */
+    value: SupportedOption;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command. Applies the alignment `value` to the selected blocks.
+     * If no `value` is passed, the `value` is the default one or it is equal to the currently selected block's alignment attribute,
+     * the command will remove the attribute from the selected blocks.
+     *
+     * @param options Options for the executed command.
+     * @param options.value The value to apply.
+     * @fires execute
+     */
+    execute(options?: {
+        value?: SupportedOption;
+    }): void;
+    /**
+     * Checks whether a block can have alignment set.
+     *
+     * @param block The block to be checked.
+     */
+    private _canBeAligned;
+}

package/src/alignmentcommand.js

@@ -0,0 +1,88 @@
+/**
+ * @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/alignmentcommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+import { first } from 'ckeditor5/src/utils.js';
+import { isDefault } from './utils.js';
+const ALIGNMENT = 'alignment';
+/**
+ * The alignment command plugin.
+ */
+export default class AlignmentCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const editor = this.editor;
+        const locale = editor.locale;
+        const firstBlock = first(this.editor.model.document.selection.getSelectedBlocks());
+        // As first check whether to enable or disable the command as the value will always be false if the command cannot be enabled.
+        this.isEnabled = Boolean(firstBlock) && this._canBeAligned(firstBlock);
+        if (this.isEnabled && firstBlock.hasAttribute('alignment')) {
+            this.value = firstBlock.getAttribute('alignment');
+        }
+        else {
+            this.value = locale.contentLanguageDirection === 'rtl' ? 'right' : 'left';
+        }
+    }
+    /**
+     * Executes the command. Applies the alignment `value` to the selected blocks.
+     * If no `value` is passed, the `value` is the default one or it is equal to the currently selected block's alignment attribute,
+     * the command will remove the attribute from the selected blocks.
+     *
+     * @param options Options for the executed command.
+     * @param options.value The value to apply.
+     * @fires execute
+     */
+    execute(options = {}) {
+        const editor = this.editor;
+        const locale = editor.locale;
+        const model = editor.model;
+        const doc = model.document;
+        const value = options.value;
+        model.change(writer => {
+            // Get only those blocks from selected that can have alignment set
+            const blocks = Array.from(doc.selection.getSelectedBlocks()).filter(block => this._canBeAligned(block));
+            const currentAlignment = blocks[0].getAttribute('alignment');
+            // Remove alignment attribute if current alignment is:
+            // - default (should not be stored in model as it will bloat model data)
+            // - equal to currently set
+            // - or no value is passed - denotes default alignment.
+            const removeAlignment = isDefault(value, locale) || currentAlignment === value || !value;
+            if (removeAlignment) {
+                removeAlignmentFromSelection(blocks, writer);
+            }
+            else {
+                setAlignmentOnSelection(blocks, writer, value);
+            }
+        });
+    }
+    /**
+     * Checks whether a block can have alignment set.
+     *
+     * @param block The block to be checked.
+     */
+    _canBeAligned(block) {
+        return this.editor.model.schema.checkAttribute(block, ALIGNMENT);
+    }
+}
+/**
+ * Removes the alignment attribute from blocks.
+ */
+function removeAlignmentFromSelection(blocks, writer) {
+    for (const block of blocks) {
+        writer.removeAttribute(ALIGNMENT, block);
+    }
+}
+/**
+ * Sets the alignment attribute on blocks.
+ */
+function setAlignmentOnSelection(blocks, writer, alignment) {
+    for (const block of blocks) {
+        writer.setAttribute(ALIGNMENT, alignment, block);
+    }
+}

package/src/alignmentconfig.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 alignment/alignmentconfig
+ */
+/**
+ * The configuration of the {@link module:alignment/alignment~Alignment alignment feature}.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( editorElement, {
+ *     alignment: {
+ *       options: [ 'left', 'right' ]
+ *     }
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor configuration options}.
+ */
+export interface AlignmentConfig {
+    options?: Array<SupportedOption | AlignmentFormat>;
+}
+/**
+ * Available alignment options.
+ *
+ * The available options are: `'left'`, `'right'`, `'center'` and `'justify'`. Other values are ignored.
+ *
+ * **Note:** It is recommended to always use `'left'` or `'right'` as these are default values which the user should
+ * normally be able to choose depending on the
+ * {@glink getting-started/setup/ui-language#setting-the-language-of-the-content language of the editor content}.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( editorElement, {
+ *     alignment: {
+ *       options: [ 'left', 'right' ]
+ *     }
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ *
+ * By default the alignment is set inline using the `text-align` CSS property. To further customize the alignment,
+ * you can provide names of classes for each alignment option using the `className` property.
+ *
+ * **Note:** Once you define the `className` property for one option, you need to specify it for all other options.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( editorElement, {
+ *     alignment: {
+ *       options: [
+ *         { name: 'left', className: 'my-align-left' },
+ *         { name: 'right', className: 'my-align-right' }
+ *       ]
+ *     }
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ *
+ * See the demo of {@glink features/text-alignment#configuring-alignment-options custom alignment options}.
+ */
+export type AlignmentFormat = {
+    name: SupportedOption;
+    className?: string;
+};
+export type SupportedOption = 'left' | 'right' | 'center' | 'justify';

package/src/alignmentconfig.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/alignmentediting.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 alignment/alignmentediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+/**
+ * The alignment editing feature. It introduces the {@link module:alignment/alignmentcommand~AlignmentCommand command} and adds
+ * the `alignment` attribute for block elements in the {@link module:engine/model/model~Model model}.
+ */
+export default class AlignmentEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "AlignmentEditing";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/src/alignmentediting.js

@@ -0,0 +1,153 @@
+/**
+ * @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/alignmentediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import AlignmentCommand from './alignmentcommand.js';
+import { isDefault, isSupported, normalizeAlignmentOptions, supportedOptions } from './utils.js';
+/**
+ * The alignment editing feature. It introduces the {@link module:alignment/alignmentcommand~AlignmentCommand command} and adds
+ * the `alignment` attribute for block elements in the {@link module:engine/model/model~Model model}.
+ */
+export default class AlignmentEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'AlignmentEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        super(editor);
+        editor.config.define('alignment', {
+            options: supportedOptions.map(option => ({ name: option }))
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const locale = editor.locale;
+        const schema = editor.model.schema;
+        const options = normalizeAlignmentOptions(editor.config.get('alignment.options'));
+        // Filter out unsupported options and those that are redundant, e.g. `left` in LTR / `right` in RTL mode.
+        const optionsToConvert = options.filter(option => isSupported(option.name) && !isDefault(option.name, locale));
+        // Once there is at least one `className` defined, we switch to alignment with classes.
+        const shouldUseClasses = optionsToConvert.some(option => !!option.className);
+        // Allow alignment attribute on all blocks.
+        schema.extend('$block', { allowAttributes: 'alignment' });
+        editor.model.schema.setAttributeProperties('alignment', { isFormatting: true });
+        if (shouldUseClasses) {
+            editor.conversion.attributeToAttribute(buildClassDefinition(optionsToConvert));
+        }
+        else {
+            // Downcast inline styles.
+            editor.conversion.for('downcast').attributeToAttribute(buildDowncastInlineDefinition(optionsToConvert));
+        }
+        const upcastInlineDefinitions = buildUpcastInlineDefinitions(optionsToConvert);
+        // Always upcast from inline styles.
+        for (const definition of upcastInlineDefinitions) {
+            editor.conversion.for('upcast').attributeToAttribute(definition);
+        }
+        const upcastCompatibilityDefinitions = buildUpcastCompatibilityDefinitions(optionsToConvert);
+        // Always upcast from deprecated `align` attribute.
+        for (const definition of upcastCompatibilityDefinitions) {
+            editor.conversion.for('upcast').attributeToAttribute(definition);
+        }
+        editor.commands.add('alignment', new AlignmentCommand(editor));
+    }
+}
+/**
+ * Prepare downcast conversion definition for inline alignment styling.
+ */
+function buildDowncastInlineDefinition(options) {
+    const view = {};
+    for (const { name } of options) {
+        view[name] = {
+            key: 'style',
+            value: {
+                'text-align': name
+            }
+        };
+    }
+    const definition = {
+        model: {
+            key: 'alignment',
+            values: options.map(option => option.name)
+        },
+        view
+    };
+    return definition;
+}
+/**
+ * Prepare upcast definitions for inline alignment styles.
+ */
+function buildUpcastInlineDefinitions(options) {
+    const definitions = [];
+    for (const { name } of options) {
+        definitions.push({
+            view: {
+                key: 'style',
+                value: {
+                    'text-align': name
+                }
+            },
+            model: {
+                key: 'alignment',
+                value: name
+            }
+        });
+    }
+    return definitions;
+}
+/**
+ * Prepare upcast definitions for deprecated `align` attribute.
+ */
+function buildUpcastCompatibilityDefinitions(options) {
+    const definitions = [];
+    for (const { name } of options) {
+        definitions.push({
+            view: {
+                key: 'align',
+                value: name
+            },
+            model: {
+                key: 'alignment',
+                value: name
+            }
+        });
+    }
+    return definitions;
+}
+/**
+ * Prepare conversion definitions for upcast and downcast alignment with classes.
+ */
+function buildClassDefinition(options) {
+    const view = {};
+    for (const option of options) {
+        view[option.name] = {
+            key: 'class',
+            value: option.className
+        };
+    }
+    const definition = {
+        model: {
+            key: 'alignment',
+            values: options.map(option => option.name)
+        },
+        view
+    };
+    return definition;
+}

package/src/alignmentui.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @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 } from 'ckeditor5/src/core.js';
+import type { SupportedOption } from './alignmentconfig.js';
+/**
+ * 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(): Record<SupportedOption, string>;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "AlignmentUI";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * 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.
+     */
+    private _addButton;
+    /**
+     * 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.
+     */
+    private _createButton;
+    /**
+     * 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.
+     */
+    private _addToolbarDropdown;
+    /**
+     * Creates a menu for all alignment options to use either in menu bar.
+     *
+     * @param options Normalized alignment options from config.
+     */
+    private _addMenuBarMenu;
+}