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

package/src/image/imageblockediting.js

@@ -2,30 +2,17 @@
  * @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/image/imageblockediting
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import { ClipboardPipeline } from 'ckeditor5/src/clipboard';
 import { UpcastWriter } from 'ckeditor5/src/engine';
-
-import {
-	downcastImageAttribute,
-	downcastSrcsetAttribute,
-	upcastImageFigure
-} from './converters';
-
+import { downcastImageAttribute, downcastSrcsetAttribute, upcastImageFigure } from './converters';
 import ImageEditing from './imageediting';
 import ImageTypeCommand from './imagetypecommand';
 import ImageUtils from '../imageutils';
-import {
-	getImgViewElementMatcher,
-	createBlockImageViewElement,
-	determineImageTypeForInsertionAtSelection
-} from '../image/utils';
-
+import { getImgViewElementMatcher, createBlockImageViewElement, determineImageTypeForInsertionAtSelection } from '../image/utils';
 /**
  * The image block plugin.
  *
@@ -35,146 +22,115 @@ import {
  * * converters for editing and data pipelines.,
  * * {@link module:image/image/imagetypecommand~ImageTypeCommand `'imageTypeBlock'`} command that converts inline images into
  * block images.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class ImageBlockEditing extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ ImageEditing, ImageUtils, ClipboardPipeline ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'ImageBlockEditing';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	init() {
-		const editor = this.editor;
-		const schema = editor.model.schema;
-
-		// Converters 'alt' and 'srcset' are added in 'ImageEditing' plugin.
-		schema.register( 'imageBlock', {
-			inheritAllFrom: '$blockObject',
-			allowAttributes: [ 'alt', 'src', 'srcset' ]
-		} );
-
-		this._setupConversion();
-
-		if ( editor.plugins.has( 'ImageInlineEditing' ) ) {
-			editor.commands.add( 'imageTypeBlock', new ImageTypeCommand( this.editor, 'imageBlock' ) );
-
-			this._setupClipboardIntegration();
-		}
-	}
-
-	/**
-	 * Configures conversion pipelines to support upcasting and downcasting
-	 * block images (block image widgets) and their attributes.
-	 *
-	 * @private
-	 */
-	_setupConversion() {
-		const editor = this.editor;
-		const t = editor.t;
-		const conversion = editor.conversion;
-		const imageUtils = editor.plugins.get( 'ImageUtils' );
-
-		conversion.for( 'dataDowncast' )
-			.elementToStructure( {
-				model: 'imageBlock',
-				view: ( modelElement, { writer } ) => createBlockImageViewElement( writer )
-			} );
-
-		conversion.for( 'editingDowncast' )
-			.elementToStructure( {
-				model: 'imageBlock',
-				view: ( modelElement, { writer } ) => imageUtils.toImageWidget(
-					createBlockImageViewElement( writer ), writer, t( 'image widget' )
-				)
-			} );
-
-		conversion.for( 'downcast' )
-			.add( downcastImageAttribute( imageUtils, 'imageBlock', 'src' ) )
-			.add( downcastImageAttribute( imageUtils, 'imageBlock', 'alt' ) )
-			.add( downcastSrcsetAttribute( imageUtils, 'imageBlock' ) );
-
-		// More image related upcasts are in 'ImageEditing' plugin.
-		conversion.for( 'upcast' )
-			.elementToElement( {
-				view: getImgViewElementMatcher( editor, 'imageBlock' ),
-				model: ( viewImage, { writer } ) => writer.createElement(
-					'imageBlock',
-					viewImage.hasAttribute( 'src' ) ? { src: viewImage.getAttribute( 'src' ) } : null
-				)
-			} )
-			.add( upcastImageFigure( imageUtils ) );
-	}
-
-	/**
-	 * Integrates the plugin with the clipboard pipeline.
-	 *
-	 * Idea is that the feature should recognize the user's intent when an **inline** image is
-	 * pasted or dropped. If such an image is pasted/dropped:
-	 *
-	 * * into an empty block (e.g. an empty paragraph),
-	 * * on another object (e.g. some block widget).
-	 *
-	 * it gets converted into a block image on the fly. We assume this is the user's intent
-	 * if they decided to put their image there.
-	 *
-	 * See the `ImageInlineEditing` for the similar integration that works in the opposite direction.
-	 *
-	 * @private
-	 */
-	_setupClipboardIntegration() {
-		const editor = this.editor;
-		const model = editor.model;
-		const editingView = editor.editing.view;
-		const imageUtils = editor.plugins.get( 'ImageUtils' );
-
-		this.listenTo( editor.plugins.get( 'ClipboardPipeline' ), 'inputTransformation', ( evt, data ) => {
-			const docFragmentChildren = Array.from( data.content.getChildren() );
-			let modelRange;
-
-			// Make sure only <img> elements are dropped or pasted. Otherwise, if there some other HTML
-			// mixed up, this should be handled as a regular paste.
-			if ( !docFragmentChildren.every( imageUtils.isInlineImageView ) ) {
-				return;
-			}
-
-			// When drag and dropping, data.targetRanges specifies where to drop because
-			// this is usually a different place than the current model selection (the user
-			// uses a drop marker to specify the drop location).
-			if ( data.targetRanges ) {
-				modelRange = editor.editing.mapper.toModelRange( data.targetRanges[ 0 ] );
-			}
-			// Pasting, however, always occurs at the current model selection.
-			else {
-				modelRange = model.document.selection.getFirstRange();
-			}
-
-			const selection = model.createSelection( modelRange );
-
-			// Convert inline images into block images only when the currently selected block is empty
-			// (e.g. an empty paragraph) or some object is selected (to replace it).
-			if ( determineImageTypeForInsertionAtSelection( model.schema, selection ) === 'imageBlock' ) {
-				const writer = new UpcastWriter( editingView.document );
-
-				// Wrap <img ... /> -> <figure class="image"><img .../></figure>
-				const blockViewImages = docFragmentChildren.map(
-					inlineViewImage => writer.createElement( 'figure', { class: 'image' }, inlineViewImage )
-				);
-
-				data.content = writer.createDocumentFragment( blockViewImages );
-			}
-		} );
-	}
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [ImageEditing, ImageUtils, ClipboardPipeline];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'ImageBlockEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const schema = editor.model.schema;
+        // Converters 'alt' and 'srcset' are added in 'ImageEditing' plugin.
+        schema.register('imageBlock', {
+            inheritAllFrom: '$blockObject',
+            allowAttributes: ['alt', 'src', 'srcset']
+        });
+        this._setupConversion();
+        if (editor.plugins.has('ImageInlineEditing')) {
+            editor.commands.add('imageTypeBlock', new ImageTypeCommand(this.editor, 'imageBlock'));
+            this._setupClipboardIntegration();
+        }
+    }
+    /**
+     * Configures conversion pipelines to support upcasting and downcasting
+     * block images (block image widgets) and their attributes.
+     */
+    _setupConversion() {
+        const editor = this.editor;
+        const t = editor.t;
+        const conversion = editor.conversion;
+        const imageUtils = editor.plugins.get('ImageUtils');
+        conversion.for('dataDowncast')
+            .elementToStructure({
+            model: 'imageBlock',
+            view: (modelElement, { writer }) => createBlockImageViewElement(writer)
+        });
+        conversion.for('editingDowncast')
+            .elementToStructure({
+            model: 'imageBlock',
+            view: (modelElement, { writer }) => imageUtils.toImageWidget(createBlockImageViewElement(writer), writer, t('image widget'))
+        });
+        conversion.for('downcast')
+            .add(downcastImageAttribute(imageUtils, 'imageBlock', 'src'))
+            .add(downcastImageAttribute(imageUtils, 'imageBlock', 'alt'))
+            .add(downcastSrcsetAttribute(imageUtils, 'imageBlock'));
+        // More image related upcasts are in 'ImageEditing' plugin.
+        conversion.for('upcast')
+            .elementToElement({
+            view: getImgViewElementMatcher(editor, 'imageBlock'),
+            model: (viewImage, { writer }) => writer.createElement('imageBlock', viewImage.hasAttribute('src') ? { src: viewImage.getAttribute('src') } : undefined)
+        })
+            .add(upcastImageFigure(imageUtils));
+    }
+    /**
+     * Integrates the plugin with the clipboard pipeline.
+     *
+     * Idea is that the feature should recognize the user's intent when an **inline** image is
+     * pasted or dropped. If such an image is pasted/dropped:
+     *
+     * * into an empty block (e.g. an empty paragraph),
+     * * on another object (e.g. some block widget).
+     *
+     * it gets converted into a block image on the fly. We assume this is the user's intent
+     * if they decided to put their image there.
+     *
+     * See the `ImageInlineEditing` for the similar integration that works in the opposite direction.
+     */
+    _setupClipboardIntegration() {
+        const editor = this.editor;
+        const model = editor.model;
+        const editingView = editor.editing.view;
+        const imageUtils = editor.plugins.get('ImageUtils');
+        const clipboardPipeline = editor.plugins.get('ClipboardPipeline');
+        this.listenTo(clipboardPipeline, 'inputTransformation', (evt, data) => {
+            const docFragmentChildren = Array.from(data.content.getChildren());
+            let modelRange;
+            // Make sure only <img> elements are dropped or pasted. Otherwise, if there some other HTML
+            // mixed up, this should be handled as a regular paste.
+            if (!docFragmentChildren.every(imageUtils.isInlineImageView)) {
+                return;
+            }
+            // When drag and dropping, data.targetRanges specifies where to drop because
+            // this is usually a different place than the current model selection (the user
+            // uses a drop marker to specify the drop location).
+            if (data.targetRanges) {
+                modelRange = editor.editing.mapper.toModelRange(data.targetRanges[0]);
+            }
+            // Pasting, however, always occurs at the current model selection.
+            else {
+                modelRange = model.document.selection.getFirstRange();
+            }
+            const selection = model.createSelection(modelRange);
+            // Convert inline images into block images only when the currently selected block is empty
+            // (e.g. an empty paragraph) or some object is selected (to replace it).
+            if (determineImageTypeForInsertionAtSelection(model.schema, selection) === 'imageBlock') {
+                const writer = new UpcastWriter(editingView.document);
+                // Wrap <img ... /> -> <figure class="image"><img .../></figure>
+                const blockViewImages = docFragmentChildren.map(inlineViewImage => writer.createElement('figure', { class: 'image' }, inlineViewImage));
+                data.content = writer.createDocumentFragment(blockViewImages);
+            }
+        });
+    }
 }

package/src/image/imageediting.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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/image/imageediting
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * The image engine plugin. This module loads common code shared between
+ * {@link module:image/image/imageinlineediting~ImageInlineEditing} and
+ * {@link module:image/image/imageblockediting~ImageBlockEditing} plugins.
+ *
+ * This plugin registers the {@link module:image/image/insertimagecommand~InsertImageCommand 'insertImage'} command.
+ */
+export default class ImageEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'ImageEditing';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [ImageEditing.pluginName]: ImageEditing;
+    }
+}

package/src/image/imageediting.js

@@ -2,87 +2,73 @@
  * @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/image/imageediting
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import ImageLoadObserver from './imageloadobserver';
 import InsertImageCommand from './insertimagecommand';
 import ReplaceImageSourceCommand from './replaceimagesourcecommand';
 import ImageUtils from '../imageutils';
-
 /**
  * The image engine plugin. This module loads common code shared between
  * {@link module:image/image/imageinlineediting~ImageInlineEditing} and
  * {@link module:image/image/imageblockediting~ImageBlockEditing} plugins.
  *
  * This plugin registers the {@link module:image/image/insertimagecommand~InsertImageCommand 'insertImage'} command.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class ImageEditing extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ ImageUtils ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'ImageEditing';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	init() {
-		const editor = this.editor;
-		const conversion = editor.conversion;
-
-		// See https://github.com/ckeditor/ckeditor5-image/issues/142.
-		editor.editing.view.addObserver( ImageLoadObserver );
-
-		conversion.for( 'upcast' )
-			.attributeToAttribute( {
-				view: {
-					name: 'img',
-					key: 'alt'
-				},
-				model: 'alt'
-			} )
-			.attributeToAttribute( {
-				view: {
-					name: 'img',
-					key: 'srcset'
-				},
-				model: {
-					key: 'srcset',
-					value: viewImage => {
-						const value = {
-							data: viewImage.getAttribute( 'srcset' )
-						};
-
-						if ( viewImage.hasAttribute( 'width' ) ) {
-							value.width = viewImage.getAttribute( 'width' );
-						}
-
-						return value;
-					}
-				}
-			} );
-
-		const insertImageCommand = new InsertImageCommand( editor );
-		const replaceImageSourceCommand = new ReplaceImageSourceCommand( editor );
-
-		editor.commands.add( 'insertImage', insertImageCommand );
-		editor.commands.add( 'replaceImageSource', replaceImageSourceCommand );
-
-		// `imageInsert` is an alias for backward compatibility.
-		editor.commands.add( 'imageInsert', insertImageCommand );
-	}
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [ImageUtils];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'ImageEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const conversion = editor.conversion;
+        // See https://github.com/ckeditor/ckeditor5-image/issues/142.
+        editor.editing.view.addObserver(ImageLoadObserver);
+        conversion.for('upcast')
+            .attributeToAttribute({
+            view: {
+                name: 'img',
+                key: 'alt'
+            },
+            model: 'alt'
+        })
+            .attributeToAttribute({
+            view: {
+                name: 'img',
+                key: 'srcset'
+            },
+            model: {
+                key: 'srcset',
+                value: (viewImage) => {
+                    const value = {
+                        data: viewImage.getAttribute('srcset')
+                    };
+                    if (viewImage.hasAttribute('width')) {
+                        value.width = viewImage.getAttribute('width');
+                    }
+                    return value;
+                }
+            }
+        });
+        const insertImageCommand = new InsertImageCommand(editor);
+        const replaceImageSourceCommand = new ReplaceImageSourceCommand(editor);
+        editor.commands.add('insertImage', insertImageCommand);
+        editor.commands.add('replaceImageSource', replaceImageSourceCommand);
+        // `imageInsert` is an alias for backward compatibility.
+        editor.commands.add('imageInsert', insertImageCommand);
+    }
 }

package/src/image/imageinlineediting.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @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/image/imageinlineediting
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * The image inline plugin.
+ *
+ * It registers:
+ *
+ * * `<imageInline>` as an inline element in the document schema, and allows `alt`, `src` and `srcset` attributes.
+ * * converters for editing and data pipelines.
+ * * {@link module:image/image/imagetypecommand~ImageTypeCommand `'imageTypeInline'`} command that converts block images into
+ * inline images.
+ */
+export default class ImageInlineEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'ImageInlineEditing';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Configures conversion pipelines to support upcasting and downcasting
+     * inline images (inline image widgets) and their attributes.
+     */
+    private _setupConversion;
+    /**
+     * Integrates the plugin with the clipboard pipeline.
+     *
+     * Idea is that the feature should recognize the user's intent when an **block** image is
+     * pasted or dropped. If such an image is pasted/dropped into a non-empty block
+     * (e.g. a paragraph with some text) it gets converted into an inline image on the fly.
+     *
+     * We assume this is the user's intent if they decided to put their image there.
+     *
+     * **Note**: If a block image has a caption, it will not be converted to an inline image
+     * to avoid the confusion. Captions are added on purpose and they should never be lost
+     * in the clipboard pipeline.
+     *
+     * See the `ImageBlockEditing` for the similar integration that works in the opposite direction.
+     */
+    private _setupClipboardIntegration;
+}