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

package/src/imageresize/resizeimagecommand.js

@@ -2,67 +2,60 @@
  * @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 image/imageresize/resizeimagecommand
  */
-
 import { Command } from 'ckeditor5/src/core';
-
 /**
  * The resize image command. Currently, it only supports the width attribute.
- *
- * @extends module:core/command~Command
  */
 export default class ResizeImageCommand extends Command {
-	/**
-	 * @inheritDoc
-	 */
-	refresh() {
-		const editor = this.editor;
-		const imageUtils = editor.plugins.get( 'ImageUtils' );
-		const element = imageUtils.getClosestSelectedImageElement( editor.model.document.selection );
-
-		this.isEnabled = !!element;
-
-		if ( !element || !element.hasAttribute( 'width' ) ) {
-			this.value = null;
-		} else {
-			this.value = {
-				width: element.getAttribute( 'width' ),
-				height: null
-			};
-		}
-	}
-
-	/**
-	 * Executes the command.
-	 *
-	 *		// Sets the width to 50%:
-	 *		editor.execute( 'resizeImage', { width: '50%' } );
-	 *
-	 *		// Removes the width attribute:
-	 *		editor.execute( 'resizeImage', { width: null } );
-	 *
-	 * @param {Object} options
-	 * @param {String|null} options.width The new width of the image.
-	 * @fires execute
-	 */
-	execute( options ) {
-		const editor = this.editor;
-		const model = editor.model;
-		const imageUtils = editor.plugins.get( 'ImageUtils' );
-		const imageElement = imageUtils.getClosestSelectedImageElement( model.document.selection );
-
-		this.value = {
-			width: options.width,
-			height: null
-		};
-
-		if ( imageElement ) {
-			model.change( writer => {
-				writer.setAttribute( 'width', options.width, imageElement );
-			} );
-		}
-	}
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const editor = this.editor;
+        const imageUtils = editor.plugins.get('ImageUtils');
+        const element = imageUtils.getClosestSelectedImageElement(editor.model.document.selection);
+        this.isEnabled = !!element;
+        if (!element || !element.hasAttribute('width')) {
+            this.value = null;
+        }
+        else {
+            this.value = {
+                width: element.getAttribute('width'),
+                height: null
+            };
+        }
+    }
+    /**
+     * Executes the command.
+     *
+     * ```ts
+     * // Sets the width to 50%:
+     * editor.execute( 'resizeImage', { width: '50%' } );
+     *
+     * // Removes the width attribute:
+     * editor.execute( 'resizeImage', { width: null } );
+     * ```
+     *
+     * @param options
+     * @param options.width The new width of the image.
+     * @fires execute
+     */
+    execute(options) {
+        const editor = this.editor;
+        const model = editor.model;
+        const imageUtils = editor.plugins.get('ImageUtils');
+        const imageElement = imageUtils.getClosestSelectedImageElement(model.document.selection);
+        this.value = {
+            width: options.width,
+            height: null
+        };
+        if (imageElement) {
+            model.change(writer => {
+                writer.setAttribute('width', options.width, imageElement);
+            });
+        }
+    }
 }

package/src/imageresize.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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 image/imageresize
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import '../theme/imageresize.css';
+/**
+ * The image resize plugin.
+ *
+ * It adds a possibility to resize each image using handles.
+ */
+export default class ImageResize extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'ImageResize';
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [ImageResize.pluginName]: ImageResize;
+    }
+}

package/src/imageresize.js

@@ -2,227 +2,30 @@
  * @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 image/imageresize
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import ImageResizeButtons from './imageresize/imageresizebuttons';
 import ImageResizeEditing from './imageresize/imageresizeediting';
 import ImageResizeHandles from './imageresize/imageresizehandles';
-
 import '../theme/imageresize.css';
-
 /**
  * The image resize plugin.
  *
  * It adds a possibility to resize each image using handles.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class ImageResize extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ ImageResizeEditing, ImageResizeHandles, ImageResizeButtons ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'ImageResize';
-	}
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [ImageResizeEditing, ImageResizeHandles, ImageResizeButtons];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'ImageResize';
+    }
 }
-
-/**
- * The available options are `'px'` or `'%'`.
- *
- * Determines the size unit applied to the resized image.
- *
- *		ClassicEditor
- *			.create( editorElement, {
- *				image: {
- *					resizeUnit: 'px'
- *				}
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- *
- * This option is used by the {@link module:image/imageresize~ImageResize} feature.
- *
- * @default '%'
- * @member {String} module:image/image~ImageConfig#resizeUnit
- */
-
-/**
- * The image resize options.
- *
- * Each option should have at least these two properties:
- *
- * * name: The name of the UI component registered in the global
- * {@link module:core/editor/editorui~EditorUI#componentFactory component factory} of the editor,
- * representing the button a user can click to change the size of an image,
- * * value: An actual image width applied when a user clicks the mentioned button
- * ({@link module:image/imageresize/resizeimagecommand~ResizeImageCommand} gets executed).
- * The value property is combined with the {@link module:image/image~ImageConfig#resizeUnit `config.image.resizeUnit`} (`%` by default).
- * For instance: `value: '50'` and `resizeUnit: '%'` will render as `'50%'` in the UI.
- *
- * **Resetting the image size**
- *
- * If you want to set an option that will reset image to its original size, you need to pass a `null` value
- * to one of the options. The `:original` token is not mandatory, you can call it anything you wish, but it must reflect
- * in the standalone buttons configuration for the image toolbar.
- *
- *		ClassicEditor
- *			.create( editorElement, {
- *				image: {
- *					resizeUnit: "%",
- *					resizeOptions: [ {
- *						name: 'resizeImage:original',
- *						value: null
- *					},
- *					{
- *						name: 'resizeImage:50',
- *						value: '50'
- *					},
- *					{
- *						name: 'resizeImage:75',
- *						value: '75'
- *					} ]
- *				}
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * **Resizing images using a dropdown**
- *
- * With resize options defined, you can decide whether you want to display them as a dropdown or as standalone buttons.
- * For the dropdown, you need to pass only the `resizeImage` token to the
-{@link module:image/image~ImageConfig#toolbar `config.image.toolbar`}. The dropdown contains all defined options by default:
- *
- *		ClassicEditor
- *			.create( editorElement, {
- *				image: {
- *					resizeUnit: "%",
- *					resizeOptions: [ {
- *						name: 'resizeImage:original',
- *						value: null
- *					},
- *					{
- *						name: 'resizeImage:50',
- *						value: '50'
- *					},
- *					{
- *						name: 'resizeImage:75',
- *						value: '75'
- *					} ],
- *					toolbar: [ 'resizeImage', ... ],
- *				}
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * **Resizing images using individual buttons**
- *
- * If you want to have separate buttons for {@link module:image/imageresize/imageresizebuttons~ImageResizeOption each option},
- * pass their names to the {@link module:image/image~ImageConfig#toolbar `config.image.toolbar`} instead. Please keep in mind
- * that this time **you must define the additional
- * {@link module:image/imageresize/imageresizebuttons~ImageResizeOption `icon` property}**:
- *
- *		ClassicEditor
- *			.create( editorElement, {
- *				image: {
- *					resizeUnit: "%",
- *					resizeOptions: [ {
- *						name: 'resizeImage:original',
- *						value: null,
- *						icon: 'original'
- *					},
- *					{
- *						name: 'resizeImage:25',
- *						value: '25',
- *						icon: 'small'
- *					},
- *					{
- *						name: 'resizeImage:50',
- *						value: '50',
- *						icon: 'medium'
- *					},
- *					{
- *						name: 'resizeImage:75',
- *						value: '75',
- *						icon: 'large'
- *					} ],
- *					toolbar: [ 'resizeImage:25', 'resizeImage:50', 'resizeImage:75', 'resizeImage:original', ... ],
- *				}
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * **Customizing resize button labels**
- *
- * You can set your own label for each resize button. To do that, add the `label` property like in the example below.
- *
- * * When using the **dropdown**, the labels are displayed on the list of all options when you open the dropdown.
- * * When using **standalone buttons**, the labels will are displayed as tooltips when a user hovers over the button.
- *
- *		ClassicEditor
- *			.create( editorElement, {
- *				image: {
- *					resizeUnit: "%",
- *					resizeOptions: [ {
- *						name: 'resizeImage:original',
- *						value: null,
- *						label: 'Original size'
- *						// Note: add the "icon" property if you're configuring a standalone button.
- *					},
- *					{
- *						name: 'resizeImage:50',
- *						value: '50',
- *						label: 'Medium size'
- *						// Note: add the "icon" property if you're configuring a standalone button.
- *					},
- *					{
- *						name: 'resizeImage:75',
- *						value: '75',
- *						label: 'Large size'
- *						// Note: add the "icon" property if you're configuring a standalone button.
- *					} ]
- *				}
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * **Default value**
- *
- * The following configuration is used by default:
- *
- *		resizeOptions = [
- *			{
- *				name: 'resizeImage:original',
- *				value: null,
- *				icon: 'original'
- *			},
- *			{
- *				name: 'resizeImage:25',
- *				value: '25',
- *				icon: 'small'
- *			},
- *			{
- *				name: 'resizeImage:50',
- *				value: '50',
- *				icon: 'medium'
- *			},
- *			{
- *				name: 'resizeImage:75',
- *				value: '75',
- *				icon: 'large'
- *			}
- *		];
- *
- * @member {Array.<module:image/imageresize/imageresizebuttons~ImageResizeOption>} module:image/image~ImageConfig#resizeOptions
- */

package/src/imagestyle/converters.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 type { DowncastAttributeEvent, UpcastElementEvent } from 'ckeditor5/src/engine';
+import { type GetCallback } from 'ckeditor5/src/utils';
+import type { ImageStyleOptionDefinition } from '../imageconfig';
+/**
+ * @module image/imagestyle/converters
+ */
+/**
+ * Returns a converter for the `imageStyle` attribute. It can be used for adding, changing and removing the attribute.
+ *
+ * @param styles An array containing available image style options.
+ * @returns A model-to-view attribute converter.
+ */
+export declare function modelToViewStyleAttribute(styles: Array<ImageStyleOptionDefinition>): GetCallback<DowncastAttributeEvent>;
+/**
+ * Returns a view-to-model converter converting image CSS classes to a proper value in the model.
+ *
+ * @param styles Image style options for which the converter is created.
+ * @returns A view-to-model converter.
+ */
+export declare function viewToModelStyleAttribute(styles: Array<ImageStyleOptionDefinition>): GetCallback<UpcastElementEvent>;

package/src/imagestyle/converters.js

@@ -2,96 +2,78 @@
  * @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 { first } from 'ckeditor5/src/utils';
-
 /**
  * @module image/imagestyle/converters
  */
-
 /**
  * Returns a converter for the `imageStyle` attribute. It can be used for adding, changing and removing the attribute.
  *
- * @param {Array.<module:image/imagestyle~ImageStyleOptionDefinition>} styles
- * An array containing available image style options.
- * @returns {Function} A model-to-view attribute converter.
+ * @param styles An array containing available image style options.
+ * @returns A model-to-view attribute converter.
  */
-export function modelToViewStyleAttribute( styles ) {
-	return ( evt, data, conversionApi ) => {
-		if ( !conversionApi.consumable.consume( data.item, evt.name ) ) {
-			return;
-		}
-
-		// Check if there is class name associated with given value.
-		const newStyle = getStyleDefinitionByName( data.attributeNewValue, styles );
-		const oldStyle = getStyleDefinitionByName( data.attributeOldValue, styles );
-
-		const viewElement = conversionApi.mapper.toViewElement( data.item );
-		const viewWriter = conversionApi.writer;
-
-		if ( oldStyle ) {
-			viewWriter.removeClass( oldStyle.className, viewElement );
-		}
-
-		if ( newStyle ) {
-			viewWriter.addClass( newStyle.className, viewElement );
-		}
-	};
+export function modelToViewStyleAttribute(styles) {
+    return (evt, data, conversionApi) => {
+        if (!conversionApi.consumable.consume(data.item, evt.name)) {
+            return;
+        }
+        // Check if there is class name associated with given value.
+        const newStyle = getStyleDefinitionByName(data.attributeNewValue, styles);
+        const oldStyle = getStyleDefinitionByName(data.attributeOldValue, styles);
+        const viewElement = conversionApi.mapper.toViewElement(data.item);
+        const viewWriter = conversionApi.writer;
+        if (oldStyle) {
+            viewWriter.removeClass(oldStyle.className, viewElement);
+        }
+        if (newStyle) {
+            viewWriter.addClass(newStyle.className, viewElement);
+        }
+    };
 }
-
 /**
  * Returns a view-to-model converter converting image CSS classes to a proper value in the model.
  *
- * @param {Array.<module:image/imagestyle~ImageStyleOptionDefinition>} styles
- * Image style options for which the converter is created.
- * @returns {Function} A view-to-model converter.
+ * @param styles Image style options for which the converter is created.
+ * @returns A view-to-model converter.
  */
-export function viewToModelStyleAttribute( styles ) {
-	// Convert only non–default styles.
-	const nonDefaultStyles = {
-		imageInline: styles.filter( style => !style.isDefault && style.modelElements.includes( 'imageInline' ) ),
-		imageBlock: styles.filter( style => !style.isDefault && style.modelElements.includes( 'imageBlock' ) )
-	};
-
-	return ( evt, data, conversionApi ) => {
-		if ( !data.modelRange ) {
-			return;
-		}
-
-		const viewElement = data.viewItem;
-		const modelImageElement = first( data.modelRange.getItems() );
-
-		// Run this converter only if an image has been found in the model.
-		// In some cases it may not be found (for example if we run this on a figure with different type than image).
-		if ( !modelImageElement ) {
-			return;
-		}
-
-		// ...and the `imageStyle` attribute is allowed for that element, otherwise stop conversion early.
-		if ( !conversionApi.schema.checkAttribute( modelImageElement, 'imageStyle' ) ) {
-			return;
-		}
-
-		// Convert styles one by one.
-		for ( const style of nonDefaultStyles[ modelImageElement.name ] ) {
-			// Try to consume class corresponding with the style.
-			if ( conversionApi.consumable.consume( viewElement, { classes: style.className } ) ) {
-				// And convert this style to model attribute.
-				conversionApi.writer.setAttribute( 'imageStyle', style.name, modelImageElement );
-			}
-		}
-	};
+export function viewToModelStyleAttribute(styles) {
+    // Convert only non–default styles.
+    const nonDefaultStyles = {
+        imageInline: styles.filter(style => !style.isDefault && style.modelElements.includes('imageInline')),
+        imageBlock: styles.filter(style => !style.isDefault && style.modelElements.includes('imageBlock'))
+    };
+    return (evt, data, conversionApi) => {
+        if (!data.modelRange) {
+            return;
+        }
+        const viewElement = data.viewItem;
+        const modelImageElement = first(data.modelRange.getItems());
+        // Run this converter only if an image has been found in the model.
+        // In some cases it may not be found (for example if we run this on a figure with different type than image).
+        if (!modelImageElement) {
+            return;
+        }
+        // ...and the `imageStyle` attribute is allowed for that element, otherwise stop conversion early.
+        if (!conversionApi.schema.checkAttribute(modelImageElement, 'imageStyle')) {
+            return;
+        }
+        // Convert styles one by one.
+        for (const style of nonDefaultStyles[modelImageElement.name]) {
+            // Try to consume class corresponding with the style.
+            if (conversionApi.consumable.consume(viewElement, { classes: style.className })) {
+                // And convert this style to model attribute.
+                conversionApi.writer.setAttribute('imageStyle', style.name, modelImageElement);
+            }
+        }
+    };
 }
-
-// Returns the style with a given `name` from an array of styles.
-//
-// @param {String} name
-// @param {Array.<module:image/imagestyle~ImageStyleOptionDefinition> } styles
-// @returns {module:image/imagestyle~ImageStyleOptionDefinition|undefined}
-function getStyleDefinitionByName( name, styles ) {
-	for ( const style of styles ) {
-		if ( style.name === name ) {
-			return style;
-		}
-	}
+/**
+ * Returns the style with a given `name` from an array of styles.
+ */
+function getStyleDefinitionByName(name, styles) {
+    for (const style of styles) {
+        if (style.name === name) {
+            return style;
+        }
+    }
 }

package/src/imagestyle/imagestylecommand.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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 image/imagestyle/imagestylecommand
+ */
+import type { Element } from 'ckeditor5/src/engine';
+import { Command, type Editor } from 'ckeditor5/src/core';
+import type { ImageStyleOptionDefinition } from '../imageconfig';
+/**
+ * The image style command. It is used to apply {@link module:image/imageconfig~ImageStyleConfig#options image style option}
+ * to a selected image.
+ *
+ * **Note**: Executing this command may change the image model element if the desired style requires an image of a different
+ * type. See {@link module:image/imagestyle/imagestylecommand~ImageStyleCommand#execute} to learn more.
+ */
+export default class ImageStyleCommand extends Command {
+    /**
+     * An object containing names of default style options for the inline and block images.
+     * If there is no default style option for the given image type in the configuration,
+     * the name will be `false`.
+     */
+    private _defaultStyles;
+    /**
+     * The styles handled by this command.
+     */
+    private _styles;
+    /**
+     * Creates an instance of the image style command. When executed, the command applies one of
+     * {@link module:image/imageconfig~ImageStyleConfig#options style options} to the currently selected image.
+     *
+     * @param editor The editor instance.
+     * @param styles The style options that this command supports.
+     */
+    constructor(editor: Editor, styles: Array<ImageStyleOptionDefinition>);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command and applies the style to the currently selected image:
+     *
+     * ```ts
+     * editor.execute( 'imageStyle', { value: 'side' } );
+     * ```
+     *
+     * **Note**: Executing this command may change the image model element if the desired style requires an image
+     * of a different type. Learn more about {@link module:image/imageconfig~ImageStyleOptionDefinition#modelElements model element}
+     * configuration for the style option.
+     *
+     * @param options.value The name of the style (as configured in {@link module:image/imageconfig~ImageStyleConfig#options}).
+     * @fires execute
+     */
+    execute(options?: {
+        value?: string;
+    }): void;
+    /**
+     * Returns `true` if requested style change would trigger the image type change.
+     *
+     * @param requestedStyle The name of the style (as configured in {@link module:image/imageconfig~ImageStyleConfig#options}).
+     * @param imageElement The image model element.
+     */
+    shouldConvertImageType(requestedStyle: string, imageElement: Element): boolean;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        imageStyle: ImageStyleCommand;
+    }
+}