@ckeditor/ckeditor5-image 27.1.0 → 29.2.0

package/src/imagestyle.js

@@ -14,10 +14,14 @@ import ImageStyleUI from './imagestyle/imagestyleui';
 /**
  * The image style plugin.
  *
- * For a detailed overview, check the {@glink features/image#image-styles image styles} documentation.
+ * For a detailed overview of the image styles feature, check the {@glink features/images/images-styles documentation}.
  *
- * This is a "glue" plugin which loads the {@link module:image/imagestyle/imagestyleediting~ImageStyleEditing}
- * and {@link module:image/imagestyle/imagestyleui~ImageStyleUI} plugins.
+ * This is a "glue" plugin which loads the following plugins:
+ * * {@link module:image/imagestyle/imagestyleediting~ImageStyleEditing},
+ * * {@link module:image/imagestyle/imagestyleui~ImageStyleUI}
+ *
+ * It provides a default configuration, which can be extended or overwritten.
+ * Read more about the {@link module:image/image~ImageConfig#styles image styles configuration}.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -38,76 +42,243 @@ export default class ImageStyle extends Plugin {
 }
 
 /**
- * Available image styles.
+ * The configuration for the {@link module:image/imagestyle~ImageStyle} plugin that should be provided
+ * while creating the editor instance.
+ *
+ * A detailed information about the default configuration and customization can be found in
+ * {@link module:image/image~ImageConfig#styles `ImageConfig#styles`}.
+ *
+ * @interface ImageStyleConfig
+ */
+
+/**
+ * A list of the image style options.
+ *
+ * @member {Array.<module:image/imagestyle~ImageStyleOptionDefinition>} module:image/imagestyle~ImageStyleConfig#options
+ */
+
+/**
+ * The {@link module:image/imagestyle `ImageStyle`} plugin requires a list of the
+ * {@link module:image/imagestyle~ImageStyleConfig#options image style options} to work properly.
+ * The default configuration is provided (listed below) and can be customized while creating the editor instance.
+ *
+ * # **Command**
+ *
+ * The {@link module:image/imagestyle/imagestylecommand~ImageStyleCommand `imageStyleCommand`}
+ * is configured based on the defined options,
+ * so you can change the style of the selected image by executing the following command:
  *
- * The default value is:
+ *		editor.execute( 'imageStyle' { value: 'alignLeft' } );
  *
- *		const imageConfig = {
- *			styles: [ 'full', 'side' ]
+ * # **Buttons**
+ *
+ * All of the image style options provided in the configuration are registered
+ * in the {@link module:ui/componentfactory~ComponentFactory UI components factory} with the "imageStyle:" prefixes and can be used
+ * in the {@link module:image/image~ImageConfig#toolbar image toolbar configuration}. The buttons available by default depending
+ * on the loaded plugins are listed in the next section.
+ *
+ * Read more about styling images in the {@glink features/images/images-styles Image styles guide}.
+ *
+ * # **Default options and buttons**
+ *
+ * If the custom configuration is not provided, the default configuration will be used depending on the loaded
+ * image editing plugins.
+ *
+ * * If both {@link module:image/image/imageblockediting~ImageBlockEditing `ImageBlockEditing`} and
+ * {@link module:image/image/imageinlineediting~ImageInlineEditing `ImageInlineEditing`} plugins are loaded
+ * (which is usually the default editor configuration), the following options will be available for the toolbar
+ * configuration. These options will be registered as the buttons with the "imageStyle:" prefixes.
+ *
+ *		const imageDefaultConfig = {
+ *			styles: {
+ *				options: [
+ *					'inline', 'alignLeft', 'alignRight',
+ *					'alignCenter', 'alignBlockLeft', 'alignBlockRight',
+ *					'block', 'side'
+ *				]
+ *			}
  *		};
  *
- * which configures two default styles:
+ * * If only the {@link module:image/image/imageblockediting~ImageBlockEditing `ImageBlockEditing`} plugin is loaded,
+ * the following buttons (options) and groups will be available for the toolbar configuration.
+ * These options will be registered as the buttons with the "imageStyle:" prefixes.
+ *
+ *		const imageDefaultConfig = {
+ *			styles: {
+ *				options: [ 'block', 'side' ]
+ *			}
+ *		};
+ *
+ * * If only the {@link module:image/image/imageinlineediting~ImageInlineEditing `ImageInlineEditing`} plugin is loaded,
+ * the following buttons (options) and groups will available for the toolbar configuration.
+ * These options will be registered as the buttons with the "imageStyle:" prefixes.
+ *
+ *		const imageDefaultConfig = {
+ *			styles: {
+ *				options: [ 'inline', 'alignLeft', 'alignRight' ]
+ *			}
+ *		};
  *
- *  * the "full" style which does not apply any class, e.g. for images styled to span 100% width of the content,
- *  * the "side" style with the `.image-style-side` CSS class.
+ * Read more about the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options}.
  *
- * See {@link module:image/imagestyle/utils~defaultStyles} to learn more about default
- * styles provided by the image feature.
+ * # **Custom configuration**
  *
- * The {@link module:image/imagestyle/utils~defaultStyles default styles} can be customized,
- * e.g. to change the icon, title or CSS class of the style. The feature also provides several
- * {@link module:image/imagestyle/utils~defaultIcons default icons} to choose from.
+ * The image styles configuration can be customized in several ways:
+ *
+ * * Any of the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options}
+ * can be loaded by the reference to its name as follows:
+ *
+ *		ClassicEditor
+ *			.create( editorElement, {
+ *				image: {
+ *					styles: {
+ *						options: [ 'alignLeft', 'alignRight' ]
+ *					}
+ *				}
+ *			} );
+ *
+ * * Each of the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default image style options} can be customized,
+ * e.g. to change the `icon`, `title` or CSS `className` of the style. The feature also provides several
+ * {@link module:image/imagestyle/utils~DEFAULT_ICONS default icons} to choose from.
  *
  *		import customIcon from 'custom-icon.svg';
  *
  *		// ...
  *
- *		const imageConfig = {
- *			styles: [
- *				// This will only customize the icon of the "full" style.
- *				// Note: 'right' is one of default icons provided by the feature.
- *				{ name: 'full', icon: 'right' },
+ *		ClassicEditor.create( editorElement, { image:
+ *			styles: {
+ *				options: {
+ *					// This will only customize the icon of the "block" style.
+ *					// Note: 'right' is one of default icons provided by the feature.
+ *					{
+ *						name: 'block',
+ *						icon: 'right'
+ *					},
  *
- *				// This will customize the icon, title and CSS class of the default "side" style.
- *				{ name: 'side', icon: customIcon, title: 'My side style', className: 'custom-side-image' }
- *			]
- *		};
+ *					// This will customize the icon, title and CSS class of the default "side" style.
+ *					{
+ *						name: 'side',
+ *						icon: customIcon,
+ *						title: 'My side style',
+ *						className: 'custom-side-image'
+ *					}
+ *				}
+ *			}
+ *		} );
  *
- * If none of the default styles is good enough, it is possible to define independent custom styles, too:
+ * * If none of the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default image style options}
+ * works for the integration, it is possible to define independent custom styles, too.
  *
- *		import { icons } from 'ckeditor5/src/core';
+ * See the documentation about the image style {@link module:image/imagestyle~ImageStyleOptionDefinition options}
+ * to define the custom image style configuration properly.
  *
- *		const fullSizeIcon = icons.objectCenter';
- *		const sideIcon = icons.objectRight';
+ *		import redIcon from 'red-icon.svg';
+ *		import blueIcon from 'blue-icon.svg';
  *
  *		// ...
  *
- *		const imageConfig = {
- *			styles: [
- *				// A completely custom full size style with no class, used as a default.
- *				{ name: 'fullSize', title: 'Full size', icon: fullSizeIcon, isDefault: true },
+ *		ClassicEditor.create( editorElement, { image:
+ *			styles: {
+ *				// A list of completely custom styling options.
+ *				options: [
+ *					{
+ *						name: 'regular',
+ *						modelElements: [ 'imageBlock', 'imageInline' ],
+ *						title: 'Regular image',
+ *						icon: 'full',
+ *						isDefault: true
+ *					}, {
+ *						name: 'blue',
+ *						modelElements: [ 'imageInline' ],
+ *						title: 'Blue image',
+ *						icon: blueIcon,
+ *						className: 'image-blue'
+ *					}, {
+ *						name: 'red',
+ *						modelElements: [ 'imageBlock' ],
+ *						title: 'Red image',
+ *						icon: redIcon,
+ *						className: 'image-red'
+ *					}
+ *				]
+ *			}
+ *		} );
  *
- *				{ name: 'side', title: 'To the side', icon: sideIcon, className: 'side-image' }
- *			]
- *		};
+ * @member {module:image/imagestyle~ImageStyleConfig} module:image/image~ImageConfig#styles
+ */
+
+/**
+ * The image styling option definition descriptor.
+ *
+ * This definition should be implemented in the `Image` plugin {@link module:image/image~ImageConfig#styles configuration} for:
+ *
+ * * customizing one of the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} by providing the proper name
+ * of the default style and the properties that should be overridden,
+ * * or defining a completely custom styling option by providing a custom name and implementing the following properties.
+ *
+ *		import fullSizeIcon from 'path/to/icon.svg';
  *
- * Note: Setting `title` to one of {@link module:image/imagestyle/imagestyleui~ImageStyleUI#localizedDefaultStylesTitles}
+ *		const imageStyleOptionDefinition = {
+ *			name: 'fullSize',
+ *			icon: fullSizeIcon,
+ *			title: 'Full size image',
+ *			className: 'image-full-size',
+ *			modelElements: [ 'imageBlock', 'imageInline' ]
+ *		}
+ *
+ * The styling option will be registered as the button under the name `'imageStyle:{name}'` in the
+ * {@link module:ui/componentfactory~ComponentFactory UI components factory} (this functionality is provided by the
+ * {@link module:image/imagestyle/imagestyleui~ImageStyleUI} plugin).
+ *
+ * @property {String} name The unique name of the styling option. It will be used to:
+ *
+ * * refer to one of the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} or define the custom style,
+ * * store the chosen style in the model by setting the `imageStyle` attribute of the model image element,
+ * * as a value of the {@link module:image/imagestyle/imagestylecommand~ImageStyleCommand#execute `imageStyle` command},
+ * * when registering a button for the style in the following manner: (`'imageStyle:{name}'`).
+ *
+ * @property {Boolean} [isDefault] When set, the style will be used as the default one for the model elements
+ * listed in the `modelElements` property. A default style does not apply any CSS class to the view element.
+ *
+ * If this property is not defined, its value is inherited
+ * from the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} addressed in the name property.
+ *
+ * @property {String} icon One of the following to be used when creating the styles's button:
+ *
+ * * an SVG icon source (as an XML string),
+ * * one of the keys in {@link module:image/imagestyle/utils~DEFAULT_ICONS} to use one of default icons provided by the plugin.
+ *
+ * If this property is not defined, its value is inherited
+ * from the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} addressed in the name property.
+ *
+ * @property {String} title The styles's title. Setting `title` to one of
+ * {@link module:image/imagestyle/imagestyleui~ImageStyleUI#localizedDefaultStylesTitles}
  * will automatically translate it to the language of the editor.
  *
- * Read more about styling images in the {@glink features/image#image-styles Image styles guide}.
+ * If this property is not defined, its value is inherited
+ * from the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} addressed in the name property.
  *
- * The feature creates commands based on defined styles, so you can change the style of a selected image by executing
- * the following command:
+ * @property {String} [className] The CSS class used to represent the style in the view.
+ * It should be used only for the non-default styles.
  *
- *		editor.execute( 'imageStyle' { value: 'side' } );
+ * If this property is not defined, its value is inherited
+ * from the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} addressed in the name property.
  *
- * The feature also creates buttons that execute the commands. So, assuming that you use the
- * default image styles setting, you can {@link module:image/image~ImageConfig#toolbar configure the image toolbar}
- * (or any other toolbar) to contain these options:
+ * @property {Array.<String>} modelElements The list of the names of the model elements that are supported by the style.
+ * The possible values are:
+ * * `[ 'imageBlock' ]` if the style can be applied to the image type introduced by the
+ * {@link module:image/image/imageblockediting~ImageBlockEditing `ImageBlockEditing`} plugin,
+ * * `[ 'imageInline' ]` if the style can be applied to the image type introduced by the
+ * {@link module:image/image/imageinlineediting~ImageInlineEditing `ImageInlineEditing`} plugin,
+ * * `[ 'imageInline', 'imageBlock' ]` if the style can be applied to both image types introduced by the plugins mentioned above.
  *
- *		const imageConfig = {
- *			toolbar: [ 'imageStyle:full', 'imageStyle:side' ]
- *		};
+ * This property determines which model element names work with the style. If the model element name of the currently selected
+ * image is different, upon executing the
+ * {@link module:image/imagestyle/imagestylecommand~ImageStyleCommand#execute `imageStyle`} command the image type (model element name)
+ * will automatically change.
+ *
+ * If this property is not defined, its value is inherited
+ * from the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} addressed in the name property.
  *
- * @member {Array.<module:image/imagestyle/imagestyleediting~ImageStyleFormat>} module:image/image~ImageConfig#styles
+ * @typedef {Object} module:image/imagestyle~ImageStyleOptionDefinition
  */

package/src/imagetextalternative/imagetextalternativecommand.js

@@ -8,10 +8,9 @@
  */
 
 import { Command } from 'ckeditor5/src/core';
-import { isImage } from '../image/utils';
 
 /**
- * The image text alternative command. It is used to change the `alt` attribute of `<image>` elements.
+ * The image text alternative command. It is used to change the `alt` attribute of `<imageBlock>` and `<imageInline>` model elements.
  *
  * @extends module:core/command~Command
  */
@@ -28,11 +27,13 @@ export default class ImageTextAlternativeCommand extends Command {
 	 * @inheritDoc
 	 */
 	refresh() {
-		const element = this.editor.model.document.selection.getSelectedElement();
+		const editor = this.editor;
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
+		const element = imageUtils.getClosestSelectedImageElement( this.editor.model.document.selection );
 
-		this.isEnabled = isImage( element );
+		this.isEnabled = !!element;
 
-		if ( isImage( element ) && element.hasAttribute( 'alt' ) ) {
+		if ( this.isEnabled && element.hasAttribute( 'alt' ) ) {
 			this.value = element.getAttribute( 'alt' );
 		} else {
 			this.value = false;
@@ -47,8 +48,10 @@ export default class ImageTextAlternativeCommand extends Command {
 	 * @param {String} options.newValue The new value of the `alt` attribute to set.
 	 */
 	execute( options ) {
-		const model = this.editor.model;
-		const imageElement = model.document.selection.getSelectedElement();
+		const editor = this.editor;
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
+		const model = editor.model;
+		const imageElement = imageUtils.getClosestSelectedImageElement( model.document.selection );
 
 		model.change( writer => {
 			writer.setAttribute( 'alt', options.newValue, imageElement );

package/src/imagetextalternative/imagetextalternativeediting.js

@@ -7,8 +7,9 @@
  * @module image/imagetextalternative/imagetextalternativeediting
  */
 
-import ImageTextAlternativeCommand from './imagetextalternativecommand';
 import { Plugin } from 'ckeditor5/src/core';
+import ImageTextAlternativeCommand from './imagetextalternativecommand';
+import ImageUtils from '../imageutils';
 
 /**
  * The image text alternative editing plugin.
@@ -18,6 +19,13 @@ import { Plugin } from 'ckeditor5/src/core';
  * @extends module:core/plugin~Plugin
  */
 export default class ImageTextAlternativeEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ ImageUtils ];
+	}
+
 	/**
 	 * @inheritDoc
 	 */

package/src/imagetextalternative/imagetextalternativeui.js

@@ -12,7 +12,6 @@ import { ButtonView, ContextualBalloon, clickOutsideHandler } from 'ckeditor5/sr
 
 import TextAlternativeFormView from './ui/textalternativeformview';
 import { repositionContextualBalloon, getBalloonPositionData } from '../image/ui/utils';
-import { getSelectedImageWidget } from '../image/utils';
 
 /**
  * The image text alternative UI plugin.
@@ -94,6 +93,7 @@ export default class ImageTextAlternativeUI extends Plugin {
 		const editor = this.editor;
 		const view = editor.editing.view;
 		const viewDocument = view.document;
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
 
 		/**
 		 * The contextual balloon plugin instance.
@@ -133,7 +133,7 @@ export default class ImageTextAlternativeUI extends Plugin {
 
 		// Reposition the balloon or hide the form if an image widget is no longer selected.
 		this.listenTo( editor.ui, 'update', () => {
-			if ( !getSelectedImageWidget( viewDocument.selection ) ) {
+			if ( !imageUtils.getClosestSelectedImageWidget( viewDocument.selection ) ) {
 				this._hideForm( true );
 			} else if ( this._isVisible ) {
 				repositionContextualBalloon( editor );

package/src/imagetextalternative.js

@@ -14,7 +14,7 @@ import ImageTextAlternativeUI from './imagetextalternative/imagetextalternativeu
 /**
  * The image text alternative plugin.
  *
- * For a detailed overview, check the {@glink features/image#image-styles image styles} documentation.
+ * For a detailed overview, check the {@glink features/images/images-styles image styles} documentation.
  *
  * This is a "glue" plugin which loads the
  *  {@link module:image/imagetextalternative/imagetextalternativeediting~ImageTextAlternativeEditing}

package/src/imagetoolbar.js

@@ -9,13 +9,13 @@
 
 import { Plugin } from 'ckeditor5/src/core';
 import { WidgetToolbarRepository } from 'ckeditor5/src/widget';
-
-import { getSelectedImageWidget } from './image/utils';
+import ImageUtils from './imageutils';
+import { isObject } from 'lodash-es';
 
 /**
  * The image toolbar plugin. It creates and manages the image toolbar (the toolbar displayed when an image is selected).
  *
- * For a detailed overview, check the {@glink features/image#image-contextual-toolbar image contextual toolbar} documentation.
+ * For an overview, check the {@glink features/images/images-overview#image-contextual-toolbar image contextual toolbar} documentation.
  *
  * Instances of toolbar components (e.g. buttons) are created using the editor's
  * {@link module:ui/componentfactory~ComponentFactory component factory}
@@ -30,7 +30,7 @@ export default class ImageToolbar extends Plugin {
 	 * @inheritDoc
 	 */
 	static get requires() {
-		return [ WidgetToolbarRepository ];
+		return [ WidgetToolbarRepository, ImageUtils ];
 	}
 
 	/**
@@ -47,11 +47,12 @@ export default class ImageToolbar extends Plugin {
 		const editor = this.editor;
 		const t = editor.t;
 		const widgetToolbarRepository = editor.plugins.get( WidgetToolbarRepository );
+		const imageUtils = editor.plugins.get( 'ImageUtils' );
 
 		widgetToolbarRepository.register( 'image', {
 			ariaLabel: t( 'Image toolbar' ),
-			items: editor.config.get( 'image.toolbar' ) || [],
-			getRelatedElement: getSelectedImageWidget
+			items: normalizeDeclarativeConfig( editor.config.get( 'image.toolbar' ) || [] ),
+			getRelatedElement: selection => imageUtils.getClosestSelectedImageWidget( selection )
 		} );
 	}
 }
@@ -64,18 +65,39 @@ export default class ImageToolbar extends Plugin {
  *
  * * {@link module:image/imagestyle~ImageStyle} (with a default configuration),
  * * {@link module:image/imagetextalternative~ImageTextAlternative},
+ * * {@link module:image/imagecaption~ImageCaption},
+ *
+ * the following toolbar items will be available in {@link module:ui/componentfactory~ComponentFactory}:
+ * * `'imageTextAlternative'`,
+ * * `'toggleImageCaption'`,
+ * * {@link module:image/image~ImageConfig#styles buttons provided by the `ImageStyle` plugin},
+ * * {@link module:image/imagestyle/utils~DEFAULT_DROPDOWN_DEFINITIONS drop-downs provided by the `ImageStyle` plugin},
  *
- * three toolbar items will be available in {@link module:ui/componentfactory~ComponentFactory}:
- * `'imageStyle:full'`, `'imageStyle:side'`, and `'imageTextAlternative'` so you can configure the toolbar like this:
+ * so you can configure the toolbar like this:
  *
  *		const imageConfig = {
- *			toolbar: [ 'imageStyle:full', 'imageStyle:side', '|', 'imageTextAlternative' ]
+ *			toolbar: [
+ *	 			'imageStyle:inline', 'imageStyle:wrapText', 'imageStyle:breakText', '|',
+ *				'toggleImageCaption', 'imageTextAlternative'
+ *			]
  *		};
  *
- * Of course, the same buttons can also be used in the
- * {@link module:core/editor/editorconfig~EditorConfig#toolbar main editor toolbar}.
+ * Besides that, the `ImageStyle` plugin allows to define a
+ * {@link module:image/imagestyle/imagestyleui~ImageStyleDropdownDefinition custom drop-down} while configuring the toolbar.
+ *
+ * The same items can also be used in the {@link module:core/editor/editorconfig~EditorConfig#toolbar main editor toolbar}.
  *
  * Read more about configuring toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
  *
  * @member {Array.<String>} module:image/image~ImageConfig#toolbar
  */
+
+// Convert the dropdown definitions to their keys registered in the ComponentFactory.
+// The registration precess should be handled by the plugin which handles the UI of a particular feature.
+//
+// @param {Array.<String|module:image/imagestyle/imagestyleui~ImageStyleDropdownDefinition>} config
+//
+// @returns {Array.<String>}
+function normalizeDeclarativeConfig( config ) {
+	return config.map( item => isObject( item ) ? item.name : item );
+}