@ckeditor/ckeditor5-alignment 36.0.0 → 37.0.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-alignment",
-  "version": "36.0.0",
+  "version": "37.0.0-alpha.0",
   "description": "Text alignment feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -12,21 +12,21 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "^36.0.0"
+    "ckeditor5": "^37.0.0-alpha.0"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-block-quote": "^36.0.0",
-    "@ckeditor/ckeditor5-core": "^36.0.0",
-    "@ckeditor/ckeditor5-dev-utils": "^32.0.0",
-    "@ckeditor/ckeditor5-editor-classic": "^36.0.0",
-    "@ckeditor/ckeditor5-engine": "^36.0.0",
-    "@ckeditor/ckeditor5-enter": "^36.0.0",
-    "@ckeditor/ckeditor5-heading": "^36.0.0",
-    "@ckeditor/ckeditor5-image": "^36.0.0",
-    "@ckeditor/ckeditor5-list": "^36.0.0",
-    "@ckeditor/ckeditor5-paragraph": "^36.0.0",
-    "@ckeditor/ckeditor5-theme-lark": "^36.0.0",
-    "@ckeditor/ckeditor5-typing": "^36.0.0",
+    "@ckeditor/ckeditor5-block-quote": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-dev-utils": "^34.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-engine": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-enter": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-heading": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-image": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-list": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-paragraph": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-theme-lark": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-typing": "^37.0.0-alpha.0",
     "typescript": "^4.8.4",
     "webpack": "^5.58.1",
     "webpack-cli": "^4.9.0"
@@ -57,5 +57,6 @@
     "dll:build": "webpack",
     "build": "tsc -p ./tsconfig.release.json",
     "postversion": "npm run build"
-  }
+  },
+  "types": "src/index.d.ts"
 }

package/src/alignment.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license Copyright (c) 2003-2023, 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, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * 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(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Alignment';
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [Alignment.pluginName]: Alignment;
+    }
+}

package/src/alignment.js

@@ -11,7 +11,7 @@ import AlignmentUI from './alignmentui';
 /**
  * The text alignment plugin.
  *
- * For a detailed overview, check the {@glink features/text-alignment Text alignment feature documentation}
+ * 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

package/src/alignmentcommand.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import type { SupportedOption } from './alignmentconfig';
+/**
+ * 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;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        alignment: AlignmentCommand;
+    }
+}

package/src/alignmentconfig.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @license Copyright (c) 2003-2023, 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 type 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 features/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';
+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;
+    }
+}

package/src/alignmentconfig.js

@@ -0,0 +1,5 @@
+/**
+ * @license Copyright (c) 2003-2023, 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,31 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+/**
+ * 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
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [AlignmentEditing.pluginName]: AlignmentEditing;
+    }
+}

package/src/alignmentui.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import type { SupportedOption } from './alignmentconfig';
+/**
+ * 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
+     */
+    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;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [AlignmentUI.pluginName]: AlignmentUI;
+    }
+}

package/src/alignmentui.js

@@ -25,7 +25,7 @@ export default class AlignmentUI extends Plugin {
      * Returns the localized option titles provided by the plugin.
      *
      * The following localized titles corresponding with
-     * {@link module:alignment/alignment~AlignmentConfig#options} are available:
+     * {@link module:alignment/alignmentconfig~AlignmentConfig#options} are available:
      *
      * * `'left'`,
      * * `'right'`,

package/src/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+export { default as AlignmentEditing } from './alignmentediting';
+export { default as AlignmentUI } from './alignmentui';

package/src/utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import type { AlignmentFormat, SupportedOption } from './alignmentconfig';
+/**
+ * @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>;