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

package/src/fontcommand.js

@@ -2,90 +2,66 @@
  * @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 font/fontcommand
  */
-
 import { Command } from 'ckeditor5/src/core';
-
 /**
  * The base font command.
- *
- * @extends module:core/command~Command
  */
 export default class FontCommand extends Command {
-	/**
-	 * Creates an instance of the command.
-	 *
-	 * @param {module:core/editor/editor~Editor} editor Editor instance.
-	 * @param {String} attributeKey The name of a model attribute on which this command operates.
-	 */
-	constructor( editor, attributeKey ) {
-		super( editor );
-
-		/**
-		 * When set, it reflects the {@link #attributeKey} value of the selection.
-		 *
-		 * @observable
-		 * @readonly
-		 * @member {String} module:font/fontcommand~FontCommand#value
-		 */
-
-		/**
-		 * A model attribute on which this command operates.
-		 *
-		 * @readonly
-		 * @member {Boolean} module:font/fontcommand~FontCommand#attributeKey
-		 */
-		this.attributeKey = attributeKey;
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	refresh() {
-		const model = this.editor.model;
-		const doc = model.document;
-
-		this.value = doc.selection.getAttribute( this.attributeKey );
-		this.isEnabled = model.schema.checkAttributeInSelection( doc.selection, this.attributeKey );
-	}
-
-	/**
-	 * Executes the command. Applies the `value` of the {@link #attributeKey} to the selection.
-	 * If no `value` is passed, it removes the attribute from the selection.
-	 *
-	 * @protected
-	 * @param {Object} [options] Options for the executed command.
-	 * @param {String} [options.value] The value to apply.
-	 * @fires execute
-	 */
-	execute( options = {} ) {
-		const model = this.editor.model;
-		const document = model.document;
-		const selection = document.selection;
-
-		const value = options.value;
-
-		model.change( writer => {
-			if ( selection.isCollapsed ) {
-				if ( value ) {
-					writer.setSelectionAttribute( this.attributeKey, value );
-				} else {
-					writer.removeSelectionAttribute( this.attributeKey );
-				}
-			} else {
-				const ranges = model.schema.getValidRanges( selection.getRanges(), this.attributeKey );
-
-				for ( const range of ranges ) {
-					if ( value ) {
-						writer.setAttribute( this.attributeKey, value, range );
-					} else {
-						writer.removeAttribute( this.attributeKey, range );
-					}
-				}
-			}
-		} );
-	}
+    /**
+     * Creates an instance of the command.
+     *
+     * @param editor Editor instance.
+     * @param attributeKey The name of a model attribute on which this command operates.
+     */
+    constructor(editor, attributeKey) {
+        super(editor);
+        this.attributeKey = attributeKey;
+    }
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const model = this.editor.model;
+        const doc = model.document;
+        this.value = doc.selection.getAttribute(this.attributeKey);
+        this.isEnabled = model.schema.checkAttributeInSelection(doc.selection, this.attributeKey);
+    }
+    /**
+     * Executes the command. Applies the `value` of the {@link #attributeKey} to the selection.
+     * If no `value` is passed, it removes the attribute from the selection.
+     *
+     * @param options Options for the executed command.
+     * @param options.value The value to apply.
+     * @fires execute
+     */
+    execute(options = {}) {
+        const model = this.editor.model;
+        const document = model.document;
+        const selection = document.selection;
+        const value = options.value;
+        model.change(writer => {
+            if (selection.isCollapsed) {
+                if (value) {
+                    writer.setSelectionAttribute(this.attributeKey, value);
+                }
+                else {
+                    writer.removeSelectionAttribute(this.attributeKey);
+                }
+            }
+            else {
+                const ranges = model.schema.getValidRanges(selection.getRanges(), this.attributeKey);
+                for (const range of ranges) {
+                    if (value) {
+                        writer.setAttribute(this.attributeKey, value, range);
+                    }
+                    else {
+                        writer.removeAttribute(this.attributeKey, range);
+                    }
+                }
+            }
+        });
+    }
 }

package/src/fontconfig.d.ts

@@ -0,0 +1,399 @@
+/**
+ * @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 font/fontconfig
+ */
+import type { ColorOption } from 'ckeditor5/src/ui';
+import type { MatcherPattern, ViewElementDefinition } from 'ckeditor5/src/engine';
+/**
+ * The configuration of the font color and font background color features.
+ * This option is used by the {@link module:font/fontcolor/fontcolorediting~FontColorEditing} and
+ * {@link module:font/fontbackgroundcolor/fontbackgroundcolorediting~FontBackgroundColorEditing} features.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( {
+ * 		fontColor: ... // Font color feature configuration.
+ * 		fontBackgroundColor: ... // Font background color feature configuration.
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface FontColorConfig {
+    /**
+     * Available font colors defined as an array of strings or objects.
+     *
+     * The default value registers the following colors:
+     *
+     * ```ts
+     * const fontColorConfig = {
+     * 	colors: [
+     * 		{
+     * 			color: 'hsl(0, 0%, 0%)',
+     * 			label: 'Black'
+     * 		},
+     * 		{
+     * 			color: 'hsl(0, 0%, 30%)',
+     * 			label: 'Dim grey'
+     * 		},
+     * 		{
+     * 			color: 'hsl(0, 0%, 60%)',
+     * 			label: 'Grey'
+     * 		},
+     * 		{
+     * 			color: 'hsl(0, 0%, 90%)',
+     * 			label: 'Light grey'
+     * 		},
+     * 		{
+     * 			color: 'hsl(0, 0%, 100%)',
+     * 			label: 'White',
+     * 			hasBorder: true
+     * 		},
+     * 		{
+     * 			color: 'hsl(0, 75%, 60%)',
+     * 			label: 'Red'
+     * 		},
+     * 		{
+     * 			color: 'hsl(30, 75%, 60%)',
+     * 			label: 'Orange'
+     * 		},
+     * 		{
+     * 			color: 'hsl(60, 75%, 60%)',
+     * 			label: 'Yellow'
+     * 		},
+     * 		{
+     * 			color: 'hsl(90, 75%, 60%)',
+     * 			label: 'Light green'
+     * 		},
+     * 		{
+     * 			color: 'hsl(120, 75%, 60%)',
+     * 			label: 'Green'
+     * 		},
+     * 		{
+     * 			color: 'hsl(150, 75%, 60%)',
+     * 			label: 'Aquamarine'
+     * 		},
+     * 		{
+     * 			color: 'hsl(180, 75%, 60%)',
+     * 			label: 'Turquoise'
+     * 		},
+     * 		{
+     * 			color: 'hsl(210, 75%, 60%)',
+     * 			label: 'Light blue'
+     * 		},
+     * 		{
+     * 			color: 'hsl(240, 75%, 60%)',
+     * 			label: 'Blue'
+     * 		},
+     * 		{
+     * 			color: 'hsl(270, 75%, 60%)',
+     * 			label: 'Purple'
+     * 		}
+     * 	]
+     * };
+     * ```
+     *
+     * **Note**: The colors are displayed in the `'fontColor'` dropdown.
+     */
+    colors?: Array<string | ColorOption>;
+    /**
+     * Determines the maximum number of available document colors.
+     * Setting it to `0` will disable the document colors feature.
+     *
+     * By default it equals to the {@link module:font/fontconfig~FontColorConfig#columns} value.
+     *
+     * Examples:
+     *
+     * ```ts
+     * // 1) Neither document colors nor columns are defined in the configuration.
+     * // Document colors will equal 5,
+     * // because the value will be inherited from columns,
+     * // which has a predefined value of 5.
+     * const fontColorConfig = {}
+     *
+     * // 2) Document colors will equal 8, because the value will be inherited from columns.
+     * const fontColorConfig = {
+     * 	columns: 8
+     * }
+     *
+     * // 3) Document colors will equal 24, because it has its own value defined.
+     * const fontColorConfig = {
+     * 	columns: 8,
+     * 	documentColors: 24
+     * }
+     *
+     * // 4) The document colors feature will be disabled.
+     * const fontColorConfig = {
+     * 	columns: 8,
+     * 	documentColors: 0
+     * }
+     * ```
+     */
+    documentColors?: number;
+    /**
+     * Represents the number of columns in the font color dropdown.
+     *
+     * The default value is:
+     *
+     * ```ts
+     * const fontColorConfig = {
+     * 	columns: 5
+     * }
+     * ```
+     */
+    columns?: number;
+}
+/**
+ * The configuration of the font family feature.
+ * This option is used by the {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing} feature.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( {
+ * 		fontFamily: ... // Font family feature configuration.
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface FontFamilyConfig {
+    /**
+     * Available font family options defined as an array of strings. The default value is:
+     *
+     * ```ts
+     * const fontFamilyConfig = {
+     * 	options: [
+     * 		'default',
+     * 		'Arial, Helvetica, sans-serif',
+     * 		'Courier New, Courier, monospace',
+     * 		'Georgia, serif',
+     * 		'Lucida Sans Unicode, Lucida Grande, sans-serif',
+     * 		'Tahoma, Geneva, sans-serif',
+     * 		'Times New Roman, Times, serif',
+     * 		'Trebuchet MS, Helvetica, sans-serif',
+     * 		'Verdana, Geneva, sans-serif'
+     * 	]
+     * };
+     * ```
+     *
+     * which configures 8 font family options. Each option consists of one or more comma–separated font family names. The first font name is
+     * used as the dropdown item description in the UI.
+     *
+     * **Note:** The family names that consist of spaces should not have quotes (as opposed to the CSS standard). The necessary quotes
+     * will be added automatically in the view. For example, the `"Lucida Sans Unicode"` will render as follows:
+     *
+     * ```html
+     * <span style="font-family:'Lucida Sans Unicode', 'Lucida Grande', sans-serif">...</span>
+     * ```
+     *
+     * The "default" option removes the `fontFamily` attribute from the selection. In such case, the text will
+     * be rendered in the view using the default font family defined in the styles of the web page.
+     *
+     * Font family can be applied using the command API. To do that, use the `fontFamily` command and pass the desired family as a `value`.
+     * For example, the following code will apply the `fontFamily` attribute with the `'Arial'` `value` to the current selection:
+     *
+     * ```ts
+     * editor.execute( 'fontFamily', { value: 'Arial' } );
+     * ```
+     *
+     * Executing the `'fontFamily'` command without any value will remove the `fontFamily` attribute from the current selection.
+     */
+    options?: Array<string | FontFamilyOption>;
+    /**
+     * By default the plugin removes any `font-family` value that does not match the plugin's configuration.
+     * It means that if you paste content with font families that the editor does not understand, the `font-family` attribute
+     * will be removed and the content will be displayed with the default font.
+     *
+     * You can preserve pasted font family values by switching the `supportAllValues` option to `true`:
+     *
+     * ```ts
+     * const fontFamilyConfig = {
+     * 	supportAllValues: true
+     * };
+     * ```
+     *
+     * With this configuration font families not specified in the editor configuration will not be removed when pasting the content.
+     */
+    supportAllValues?: boolean;
+}
+/**
+ * The font family option descriptor.
+ */
+export interface FontFamilyOption {
+    /**
+     * The user-readable title of the option.
+     */
+    title: string;
+    /**
+     * The attribute's unique value in the model.
+     */
+    model?: string;
+    /**
+     * View element configuration.
+     */
+    view?: ViewElementDefinition;
+    /**
+     * An array with all matched elements that the view-to-model conversion should also accept.
+     */
+    upcastAlso?: Array<MatcherPattern>;
+}
+/**
+ * The configuration of the font size feature.
+ * This option is used by the {@link module:font/fontsize/fontsizeediting~FontSizeEditing} feature.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( {
+ * 		fontSize: ... // Font size feature configuration.
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface FontSizeConfig {
+    /**
+     * Available font size options. Expressed as predefined presets, numerical "pixel" values
+     * or the {@link module:font/fontconfig~FontSizeOption}.
+     *
+     * The default value is:
+     *
+     * ```ts
+     * const fontSizeConfig = {
+     * 	options: [
+     * 		'tiny',
+     * 		'small',
+     * 		'default',
+     * 		'big',
+     * 		'huge'
+     * 	]
+     * };
+     * ```
+     *
+     * It defines 4 sizes: **tiny**, **small**, **big**, and **huge**. These values will be rendered as `<span>` elements in the view.
+     * The **default** defines a text without the `fontSize` attribute.
+     *
+     * Each `<span>` has the the `class` attribute set to the corresponding size name. For instance, this is what the **small** size looks
+     * like in the view:
+     *
+     * ```html
+     * <span class="text-small">...</span>
+     * ```
+     *
+     * As an alternative, the font size might be defined using numerical values (either as a `Number` or as a `String`):
+     *
+     * ```ts
+     * const fontSizeConfig = {
+     * 	options: [ 9, 10, 11, 12, 13, 14, 15 ]
+     * };
+     * ```
+     *
+     * Also, you can define a label in the dropdown for numerical values:
+     *
+     * ```ts
+     * const fontSizeConfig = {
+     * 	options: [
+     * 		{
+     * 			title: 'Small',
+     * 			model: '8px'
+     * 		},
+     * 		'default',
+     * 		{
+     * 		 	title: 'Big',
+     * 		 	model: '14px'
+     * 		}
+     * 	]
+     * };
+     * ```
+     *
+     * Font size can be applied using the command API. To do that, use the `'fontSize'` command and pass the desired font size as a `value`.
+     * For example, the following code will apply the `fontSize` attribute with the **tiny** value to the current selection:
+     *
+     * ```ts
+     * editor.execute( 'fontSize', { value: 'tiny' } );
+     * ```
+     *
+     * Executing the `fontSize` command without value will remove the `fontSize` attribute from the current selection.
+     */
+    options?: Array<string | number | FontSizeOption>;
+    /**
+     * By default the plugin removes any `font-size` value that does not match the plugin's configuration.
+     * It means that if you paste content with font sizes that the editor does not understand, the `font-size` attribute
+     * will be removed and the content will be displayed with the default size.
+     *
+     * You can preserve pasted font size values by switching the `supportAllValues` option to `true`:
+     *
+     * ```ts
+     * const fontSizeConfig = {
+     * 	options: [ 9, 10, 11, 12, 'default', 14, 15 ],
+     * 	supportAllValues: true
+     * };
+     * ```
+     *
+     * **Note:** This option can only be used with numerical values as font size options.
+     *
+     * With this configuration font sizes not specified in the editor configuration will not be removed when pasting the content.
+     */
+    supportAllValues?: boolean;
+}
+/**
+ * The font size option descriptor.
+ */
+export interface FontSizeOption {
+    /**
+     * The user-readable title of the option.
+     */
+    title: string;
+    /**
+     * The attribute's unique value in the model.
+     */
+    model?: string;
+    /**
+     * View element configuration.
+     */
+    view?: ViewElementDefinition;
+    /**
+     * An array with all matched elements that the view-to-model conversion should also accept.
+     */
+    upcastAlso?: Array<MatcherPattern>;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The configuration of the font background color feature.
+         * It is introduced by the {@link module:font/fontbackgroundcolor/fontbackgroundcolorediting~FontBackgroundColorEditing} feature.
+         *
+         * Read more in {@link module:font/fontconfig~FontColorConfig}.
+         */
+        fontBackgroundColor?: FontColorConfig;
+        /**
+         * The configuration of the font color feature.
+         * It is introduced by the {@link module:font/fontcolor/fontcolorediting~FontColorEditing} feature.
+         *
+         * Read more in {@link module:font/fontconfig~FontColorConfig}.
+         */
+        fontColor?: FontColorConfig;
+        /**
+         * The configuration of the font family feature.
+         * It is introduced by the {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing} feature.
+         *
+         * Read more in {@link module:font/fontconfig~FontFamilyConfig}.
+         */
+        fontFamily?: FontFamilyConfig;
+        /**
+         * The configuration of the font size feature.
+         * It is introduced by the {@link module:font/fontsize/fontsizeediting~FontSizeEditing} feature.
+         *
+         * Read more in {@link module:font/fontconfig~FontSizeConfig}.
+         */
+        fontSize?: FontSizeConfig;
+    }
+}

package/src/fontconfig.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/fontfamily/fontfamilycommand.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 font/fontfamily/fontfamilycommand
+ */
+import type { Editor } from 'ckeditor5/src/core';
+import FontCommand from '../fontcommand';
+import { FONT_FAMILY } from '../utils';
+/**
+ * The font family command. It is used by {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing}
+ * to apply the font family.
+ *
+ * ```ts
+ * editor.execute( 'fontFamily', { value: 'Arial' } );
+ * ```
+ *
+ * **Note**: Executing the command without the value removes the attribute from the model.
+ */
+export default class FontFamilyCommand extends FontCommand {
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        [FONT_FAMILY]: FontFamilyCommand;
+    }
+}

package/src/fontfamily/fontfamilycommand.js

@@ -2,29 +2,23 @@
  * @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 font/fontfamily/fontfamilycommand
- */
-
 import FontCommand from '../fontcommand';
 import { FONT_FAMILY } from '../utils';
-
 /**
  * The font family command. It is used by {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing}
  * to apply the font family.
  *
- *		editor.execute( 'fontFamily', { value: 'Arial' } );
+ * ```ts
+ * editor.execute( 'fontFamily', { value: 'Arial' } );
+ * ```
  *
  * **Note**: Executing the command without the value removes the attribute from the model.
- *
- * @extends module:font/fontcommand~FontCommand
  */
 export default class FontFamilyCommand extends FontCommand {
-	/**
-	 * @inheritDoc
-	 */
-	constructor( editor ) {
-		super( editor, FONT_FAMILY );
-	}
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        super(editor, FONT_FAMILY);
+    }
 }

package/src/fontfamily/fontfamilyediting.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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 font/fontfamily/fontfamilyediting
+ */
+import { type Editor, Plugin } from 'ckeditor5/src/core';
+import '../fontconfig';
+/**
+ * The font family editing feature.
+ *
+ * It introduces the {@link module:font/fontfamily/fontfamilycommand~FontFamilyCommand command} and
+ * the `fontFamily` attribute in the {@link module:engine/model/model~Model model} which renders
+ * in the {@link module:engine/view/view view} as an inline `<span>` element (`<span style="font-family: Arial">`),
+ * depending on the {@link module:font/fontconfig~FontFamilyConfig configuration}.
+ */
+export default class FontFamilyEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'FontFamilyEditing';
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * These converters enable keeping any value found as `style="font-family: *"` as a value of an attribute on a text even
+     * if it is not defined in the plugin configuration.
+     */
+    private _prepareAnyValueConverters;
+    /**
+     * Adds support for legacy `<font face="..">` formatting.
+     */
+    private _prepareCompatibilityConverter;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [FontFamilyEditing.pluginName]: FontFamilyEditing;
+    }
+}