@ckeditor/ckeditor5-font 36.0.1 → 37.0.0-alpha.1

package/src/fontfamily/utils.js

@@ -2,92 +2,79 @@
  * @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/utils
  */
-
 /**
- * Normalizes the {@link module:font/fontfamily~FontFamilyConfig#options configuration options}
- * to the {@link module:font/fontfamily~FontFamilyOption} format.
+ * Normalizes the {@link module:font/fontconfig~FontFamilyConfig#options configuration options}
+ * to the {@link module:font/fontconfig~FontFamilyOption} format.
  *
- * @param {Array.<String|Object>} configuredOptions An array of options taken from the configuration.
- * @returns {Array.<module:font/fontfamily~FontFamilyOption>}
+ * @param configuredOptions An array of options taken from the configuration.
  */
-export function normalizeOptions( configuredOptions ) {
-	// Convert options to objects.
-	return configuredOptions
-		.map( getOptionDefinition )
-		// Filter out undefined values that `getOptionDefinition` might return.
-		.filter( option => !!option );
+export function normalizeOptions(configuredOptions) {
+    // Convert options to objects.
+    return configuredOptions
+        .map(getOptionDefinition)
+        // Filter out undefined values that `getOptionDefinition` might return.
+        .filter(option => option !== undefined);
 }
-
-// Returns an option definition either created from string shortcut.
-// If object is passed then this method will return it without alternating it. Returns undefined for item than cannot be parsed.
-//
-// @param {String|Object} option
-// @returns {undefined|module:font/fontfamily~FontFamilyOption}
-function getOptionDefinition( option ) {
-	// Treat any object as full item definition provided by user in configuration.
-	if ( typeof option === 'object' ) {
-		return option;
-	}
-
-	// Handle 'default' string as a special case. It will be used to remove the fontFamily attribute.
-	if ( option === 'default' ) {
-		return {
-			title: 'Default',
-			model: undefined
-		};
-	}
-
-	// Ignore values that we cannot parse to a definition.
-	if ( typeof option !== 'string' ) {
-		return;
-	}
-
-	// Return font family definition from font string.
-	return generateFontPreset( option );
+/**
+ * Returns an option definition either created from string shortcut.
+ * If object is passed then this method will return it without alternating it. Returns undefined for item than cannot be parsed.
+ *
+ */
+function getOptionDefinition(option) {
+    // Treat any object as full item definition provided by user in configuration.
+    if (typeof option === 'object') {
+        return option;
+    }
+    // Handle 'default' string as a special case. It will be used to remove the fontFamily attribute.
+    if (option === 'default') {
+        return {
+            title: 'Default',
+            model: undefined
+        };
+    }
+    // Ignore values that we cannot parse to a definition.
+    if (typeof option !== 'string') {
+        return undefined;
+    }
+    // Return font family definition from font string.
+    return generateFontPreset(option);
 }
-
-// Creates a predefined preset for pixel size. It deconstructs font-family like string into full configuration option.
-// A font definition is passed as coma delimited set of font family names. Font names might be quoted.
-//
-// @param {String} A font definition form configuration.
-function generateFontPreset( fontDefinition ) {
-	// Remove quotes from font names. They will be normalized later.
-	const fontNames = fontDefinition.replace( /"|'/g, '' ).split( ',' );
-
-	// The first matched font name will be used as dropdown list item title and as model value.
-	const firstFontName = fontNames[ 0 ];
-
-	// CSS-compatible font names.
-	const cssFontNames = fontNames.map( normalizeFontNameForCSS ).join( ', ' );
-
-	return {
-		title: firstFontName,
-		model: cssFontNames,
-		view: {
-			name: 'span',
-			styles: {
-				'font-family': cssFontNames
-			},
-			priority: 7
-		}
-	};
+/**
+ * Creates a predefined preset for pixel size. It deconstructs font-family like string into full configuration option.
+ * A font definition is passed as coma delimited set of font family names. Font names might be quoted.
+ *
+ * @param fontDefinition A font definition form configuration.
+ */
+function generateFontPreset(fontDefinition) {
+    // Remove quotes from font names. They will be normalized later.
+    const fontNames = fontDefinition.replace(/"|'/g, '').split(',');
+    // The first matched font name will be used as dropdown list item title and as model value.
+    const firstFontName = fontNames[0];
+    // CSS-compatible font names.
+    const cssFontNames = fontNames.map(normalizeFontNameForCSS).join(', ');
+    return {
+        title: firstFontName,
+        model: cssFontNames,
+        view: {
+            name: 'span',
+            styles: {
+                'font-family': cssFontNames
+            },
+            priority: 7
+        }
+    };
 }
-
-// Normalizes font name for the style attribute. It adds braces (') if font name contains spaces.
-//
-// @param {String} fontName
-// @returns {String}
-function normalizeFontNameForCSS( fontName ) {
-	fontName = fontName.trim();
-
-	// Compound font names should be quoted.
-	if ( fontName.indexOf( ' ' ) > 0 ) {
-		fontName = `'${ fontName }'`;
-	}
-
-	return fontName;
+/**
+ * Normalizes font name for the style attribute. It adds braces (') if font name contains spaces.
+ */
+function normalizeFontNameForCSS(fontName) {
+    fontName = fontName.trim();
+    // Compound font names should be quoted.
+    if (fontName.indexOf(' ') > 0) {
+        fontName = `'${fontName}'`;
+    }
+    return fontName;
 }

package/src/fontfamily.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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 { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * 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(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'FontFamily';
+}

package/src/fontfamily.js

@@ -2,15 +2,9 @@
  * @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
- */
-
 import { Plugin } from 'ckeditor5/src/core';
 import FontFamilyEditing from './fontfamily/fontfamilyediting';
 import FontFamilyUI from './fontfamily/fontfamilyui';
-
 /**
  * The font family plugin.
  *
@@ -19,112 +13,18 @@ import FontFamilyUI from './fontfamily/fontfamilyui';
  *
  * 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.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class FontFamily extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ FontFamilyEditing, FontFamilyUI ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'FontFamily';
-	}
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [FontFamilyEditing, FontFamilyUI];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'FontFamily';
+    }
 }
-
-/**
- * The font family option descriptor.
- *
- * @typedef {Object} module:font/fontfamily~FontFamilyOption
- *
- * @property {String} title The user-readable title of the option.
- * @property {String} model The attribute's unique value in the model.
- * @property {module:engine/view/elementdefinition~ElementDefinition} view View element configuration.
- * @property {Array.<module:engine/view/elementdefinition~ElementDefinition>} [upcastAlso] An array with all matched elements that
- * the view-to-model conversion should also accept.
- */
-
-/**
- * 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/fontfamily~FontFamilyConfig}.
- *
- * @member {module:font/fontfamily~FontFamilyConfig} module:core/editor/editorconfig~EditorConfig#fontFamily
- */
-
-/**
- * The configuration of the font family feature.
- * This option is used by the {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing} feature.
- *
- *		ClassicEditor
- *			.create( {
- * 				fontFamily: ... // Font family feature configuration.
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
- *
- * @interface module:font/fontfamily~FontFamilyConfig
- */
-
-/**
- * Available font family options defined as an array of strings. The default value is:
- *
- *		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:
- *
- * 		<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:
- *
- *		editor.execute( 'fontFamily', { value: 'Arial' } );
- *
- * Executing the `'fontFamily'` command without any value will remove the `fontFamily` attribute from the current selection.
- *
- * @member {Array.<String|module:font/fontfamily~FontFamilyOption>} module:font/fontfamily~FontFamilyConfig#options
- */
-
-/**
- * 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`:
- *
- *		const fontFamilyConfig = {
- *			supportAllValues: true
- *		};
- *
- * With this configuration font families not specified in the editor configuration will not be removed when pasting the content.
- *
- * @member {Boolean} module:font/fontfamily~FontFamilyConfig#supportAllValues
- */

package/src/fontsize/fontsizecommand.d.ts

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

package/src/fontsize/fontsizeediting.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @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/fontsize/fontsizeediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core';
+/**
+ * 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;
+}