@ckeditor/ckeditor5-font 41.2.0 → 41.3.0-alpha.1

package/dist/types/fontconfig.d.ts

@@ -0,0 +1,373 @@
+/**
+ * @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 font/fontconfig
+ */
+import type { ColorOption, ColorPickerConfig } from 'ckeditor5/src/ui.js';
+import type { MatcherPattern, ViewElementDefinition } from 'ckeditor5/src/engine.js';
+/**
+ * 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;
+    /**
+     * Configuration of the color picker feature.
+     *
+     * If set to `false` the picker will not appear.
+     */
+    colorPicker?: false | ColorPickerConfig;
+}
+/**
+ * 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>;
+}

package/dist/types/fontfamily/fontfamilycommand.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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 font/fontfamily/fontfamilycommand
+ */
+import type { Editor } from 'ckeditor5/src/core.js';
+import FontCommand from '../fontcommand.js';
+/**
+ * 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);
+}

package/dist/types/fontfamily/fontfamilyediting.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
+ */
+/**
+ * @module font/fontfamily/fontfamilyediting
+ */
+import { type Editor, Plugin } from 'ckeditor5/src/core.js';
+/**
+ * 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;
+}

package/dist/types/fontfamily/fontfamilyui.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 font/fontfamily/fontfamilyui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * The font family UI plugin. It introduces the `'fontFamily'` dropdown.
+ */
+export default class FontFamilyUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "FontFamilyUI";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Returns options as defined in `config.fontFamily.options` but processed to account for
+     * editor localization, i.e. to display {@link module:font/fontconfig~FontFamilyOption}
+     * in the correct language.
+     *
+     * Note: The reason behind this method is that there is no way to use {@link module:utils/locale~Locale#t}
+     * when the user configuration is defined because the editor does not exist yet.
+     */
+    private _getLocalizedOptions;
+}

package/dist/types/fontfamily/utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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 { FontFamilyOption } from '../fontconfig.js';
+/**
+ * @module font/fontfamily/utils
+ */
+/**
+ * Normalizes the {@link module:font/fontconfig~FontFamilyConfig#options configuration options}
+ * to the {@link module:font/fontconfig~FontFamilyOption} format.
+ *
+ * @param configuredOptions An array of options taken from the configuration.
+ */
+export declare function normalizeOptions(configuredOptions: Array<string | FontFamilyOption>): Array<FontFamilyOption>;

package/dist/types/fontfamily.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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 font/fontfamily
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import FontFamilyEditing from './fontfamily/fontfamilyediting.js';
+import FontFamilyUI from './fontfamily/fontfamilyui.js';
+/**
+ * The font family plugin.
+ *
+ * For a detailed overview, check the {@glink features/font font feature} documentatiom
+ * and the {@glink api/font package page}.
+ *
+ * This is a "glue" plugin which loads the {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing} and
+ * {@link module:font/fontfamily/fontfamilyui~FontFamilyUI} features in the editor.
+ */
+export default class FontFamily extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof FontFamilyEditing, typeof FontFamilyUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "FontFamily";
+}

package/dist/types/fontsize/fontsizecommand.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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 font/fontsize/fontsizecommand
+ */
+import type { Editor } from 'ckeditor5/src/core.js';
+import FontCommand from '../fontcommand.js';
+/**
+ * The font size command. It is used by {@link module:font/fontsize/fontsizeediting~FontSizeEditing}
+ * to apply the font size.
+ *
+ * ```ts
+ * editor.execute( 'fontSize', { value: 'small' } );
+ * ```
+ *
+ * **Note**: Executing the command without the value removes the attribute from the model.
+ */
+export default class FontSizeCommand extends FontCommand {
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+}

package/dist/types/fontsize/fontsizeediting.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @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 font/fontsize/fontsizeediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+/**
+ * The font size editing feature.
+ *
+ * It introduces the {@link module:font/fontsize/fontsizecommand~FontSizeCommand command} and the `fontSize`
+ * attribute in the {@link module:engine/model/model~Model model} which renders in the {@link module:engine/view/view view}
+ * as a `<span>` element with either:
+ * * a style attribute (`<span style="font-size:12px">...</span>`),
+ * * or a class attribute (`<span class="text-small">...</span>`)
+ *
+ * depending on the {@link module:font/fontconfig~FontSizeConfig configuration}.
+ */
+export default class FontSizeEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "FontSizeEditing";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * These converters enable keeping any value found as `style="font-size: *"` as a value of an attribute on a text even
+     * if it is not defined in the plugin configuration.
+     *
+     * @param definition Converter definition out of input data.
+     */
+    private _prepareAnyValueConverters;
+    /**
+     * Adds support for legacy `<font size="..">` formatting.
+     */
+    private _prepareCompatibilityConverter;
+}

package/dist/types/fontsize/fontsizeui.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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 font/fontsize/fontsizeui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import '../../theme/fontsize.css';
+/**
+ * The font size UI plugin. It introduces the `'fontSize'` dropdown.
+ */
+export default class FontSizeUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "FontSizeUI";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Returns options as defined in `config.fontSize.options` but processed to account for
+     * editor localization, i.e. to display {@link module:font/fontconfig~FontSizeOption}
+     * in the correct language.
+     *
+     * Note: The reason behind this method is that there is no way to use {@link module:utils/locale~Locale#t}
+     * when the user configuration is defined because the editor does not exist yet.
+     */
+    private _getLocalizedOptions;
+}

package/dist/types/fontsize/utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @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 FontSizeOption } from '../fontconfig.js';
+/**
+ * Normalizes and translates the {@link module:font/fontconfig~FontSizeConfig#options configuration options}
+ * to the {@link module:font/fontconfig~FontSizeOption} format.
+ *
+ * @param configuredOptions An array of options taken from the configuration.
+ */
+export declare function normalizeOptions(configuredOptions: Array<string | number | FontSizeOption>): Array<FontSizeOption>;

package/dist/types/fontsize.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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 font/fontsize
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import FontSizeEditing from './fontsize/fontsizeediting.js';
+import FontSizeUI from './fontsize/fontsizeui.js';
+import type { FontSizeOption } from './fontconfig.js';
+/**
+ * The font size plugin.
+ *
+ * For a detailed overview, check the {@glink features/font font feature} documentation
+ * and the {@glink api/font package page}.
+ *
+ * This is a "glue" plugin which loads the {@link module:font/fontsize/fontsizeediting~FontSizeEditing} and
+ * {@link module:font/fontsize/fontsizeui~FontSizeUI} features in the editor.
+ */
+export default class FontSize extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof FontSizeEditing, typeof FontSizeUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "FontSize";
+    /**
+     * Normalizes and translates the {@link module:font/fontconfig~FontSizeConfig#options configuration options}
+     * to the {@link module:font/fontconfig~FontSizeOption} format.
+     *
+     * @param configuredOptions An array of options taken from the configuration.
+     */
+    normalizeSizeOptions(options: Array<string | number | FontSizeOption>): Array<FontSizeOption>;
+}