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

package/src/image/ui/utils.js

@@ -2,53 +2,43 @@
  * @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/ui/utils
- */
-
 import { BalloonPanelView } from 'ckeditor5/src/ui';
-
 /**
  * A helper utility that positions the
  * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} instance
  * with respect to the image in the editor content, if one is selected.
  *
- * @param {module:core/editor/editor~Editor} editor The editor instance.
+ * @param editor The editor instance.
  */
-export function repositionContextualBalloon( editor ) {
-	const balloon = editor.plugins.get( 'ContextualBalloon' );
-
-	if ( editor.plugins.get( 'ImageUtils' ).getClosestSelectedImageWidget( editor.editing.view.document.selection ) ) {
-		const position = getBalloonPositionData( editor );
-
-		balloon.updatePosition( position );
-	}
+export function repositionContextualBalloon(editor) {
+    const balloon = editor.plugins.get('ContextualBalloon');
+    const imageUtils = editor.plugins.get('ImageUtils');
+    if (imageUtils.getClosestSelectedImageWidget(editor.editing.view.document.selection)) {
+        const position = getBalloonPositionData(editor);
+        balloon.updatePosition(position);
+    }
 }
-
 /**
  * Returns the positioning options that control the geometry of the
  * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} with respect
  * to the selected element in the editor content.
  *
- * @param {module:core/editor/editor~Editor} editor The editor instance.
- * @returns {module:utils/dom/position~Options}
+ * @param editor The editor instance.
  */
-export function getBalloonPositionData( editor ) {
-	const editingView = editor.editing.view;
-	const defaultPositions = BalloonPanelView.defaultPositions;
-	const imageUtils = editor.plugins.get( 'ImageUtils' );
-
-	return {
-		target: editingView.domConverter.mapViewToDom( imageUtils.getClosestSelectedImageWidget( editingView.document.selection ) ),
-		positions: [
-			defaultPositions.northArrowSouth,
-			defaultPositions.northArrowSouthWest,
-			defaultPositions.northArrowSouthEast,
-			defaultPositions.southArrowNorth,
-			defaultPositions.southArrowNorthWest,
-			defaultPositions.southArrowNorthEast,
-			defaultPositions.viewportStickyNorth
-		]
-	};
+export function getBalloonPositionData(editor) {
+    const editingView = editor.editing.view;
+    const defaultPositions = BalloonPanelView.defaultPositions;
+    const imageUtils = editor.plugins.get('ImageUtils');
+    return {
+        target: editingView.domConverter.mapViewToDom(imageUtils.getClosestSelectedImageWidget(editingView.document.selection)),
+        positions: [
+            defaultPositions.northArrowSouth,
+            defaultPositions.northArrowSouthWest,
+            defaultPositions.northArrowSouthEast,
+            defaultPositions.southArrowNorth,
+            defaultPositions.southArrowNorthWest,
+            defaultPositions.southArrowNorthEast,
+            defaultPositions.viewportStickyNorth
+        ]
+    };
 }

package/src/image/utils.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @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/utils
+ */
+import type { DocumentSelection, MatcherPattern, Schema, Selection, ViewContainerElement, DowncastWriter } from 'ckeditor5/src/engine';
+import type { Editor } from 'ckeditor5/src/core';
+/**
+ * Creates a view element representing the inline image.
+ *
+ * ```html
+ * <span class="image-inline"><img></img></span>
+ * ```
+ *
+ * Note that `alt` and `src` attributes are converted separately, so they are not included.
+ *
+ * @internal
+ */
+export declare function createInlineImageViewElement(writer: DowncastWriter): ViewContainerElement;
+/**
+ * Creates a view element representing the block image.
+ *
+ * ```html
+ * <figure class="image"><img></img></figure>
+ * ```
+ *
+ * Note that `alt` and `src` attributes are converted separately, so they are not included.
+ *
+ * @internal
+ */
+export declare function createBlockImageViewElement(writer: DowncastWriter): ViewContainerElement;
+/**
+ * A function returning a `MatcherPattern` for a particular type of View images.
+ *
+ * @internal
+ * @param matchImageType The type of created image.
+ */
+export declare function getImgViewElementMatcher(editor: Editor, matchImageType: 'imageBlock' | 'imageInline'): MatcherPattern;
+/**
+ * Considering the current model selection, it returns the name of the model image element
+ * (`'imageBlock'` or `'imageInline'`) that will make most sense from the UX perspective if a new
+ * image was inserted (also: uploaded, dropped, pasted) at that selection.
+ *
+ * The assumption is that inserting images into empty blocks or on other block widgets should
+ * produce block images. Inline images should be inserted in other cases, e.g. in paragraphs
+ * that already contain some text.
+ *
+ * @internal
+ */
+export declare function determineImageTypeForInsertionAtSelection(schema: Schema, selection: Selection | DocumentSelection): 'imageBlock' | 'imageInline';

package/src/image/utils.js

@@ -2,98 +2,77 @@
  * @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/utils
- */
-
 import { first } from 'ckeditor5/src/utils';
-
 /**
  * Creates a view element representing the inline image.
  *
- *		<span class="image-inline"><img></img></span>
+ * ```html
+ * <span class="image-inline"><img></img></span>
+ * ```
  *
  * Note that `alt` and `src` attributes are converted separately, so they are not included.
  *
- * @protected
- * @param {module:engine/view/downcastwriter~DowncastWriter} writer
- * @returns {module:engine/view/containerelement~ContainerElement}
+ * @internal
  */
-export function createInlineImageViewElement( writer ) {
-	return writer.createContainerElement( 'span', { class: 'image-inline' },
-		writer.createEmptyElement( 'img' )
-	);
+export function createInlineImageViewElement(writer) {
+    return writer.createContainerElement('span', { class: 'image-inline' }, writer.createEmptyElement('img'));
 }
-
 /**
  * Creates a view element representing the block image.
  *
- *		<figure class="image"><img></img></figure>
+ * ```html
+ * <figure class="image"><img></img></figure>
+ * ```
  *
  * Note that `alt` and `src` attributes are converted separately, so they are not included.
  *
- * @protected
- * @param {module:engine/view/downcastwriter~DowncastWriter} writer
- * @returns {module:engine/view/containerelement~ContainerElement}
+ * @internal
  */
-export function createBlockImageViewElement( writer ) {
-	return writer.createContainerElement( 'figure', { class: 'image' }, [
-		writer.createEmptyElement( 'img' ),
-		writer.createSlot()
-	] );
+export function createBlockImageViewElement(writer) {
+    return writer.createContainerElement('figure', { class: 'image' }, [
+        writer.createEmptyElement('img'),
+        writer.createSlot('children')
+    ]);
 }
-
 /**
  * A function returning a `MatcherPattern` for a particular type of View images.
  *
- * @protected
- * @param {module:core/editor/editor~Editor} editor
- * @param {'imageBlock'|'imageInline'} matchImageType The type of created image.
- * @returns {module:engine/view/matcher~MatcherPattern}
+ * @internal
+ * @param matchImageType The type of created image.
  */
-export function getImgViewElementMatcher( editor, matchImageType ) {
-	const imageUtils = editor.plugins.get( 'ImageUtils' );
-	const areBothImagePluginsLoaded = editor.plugins.has( 'ImageInlineEditing' ) && editor.plugins.has( 'ImageBlockEditing' );
-
-	return element => {
-		// Check if the matched view element is an <img>.
-		if ( !imageUtils.isInlineImageView( element ) ) {
-			return null;
-		}
-
-		// If just one of the plugins is loaded (block or inline), it will match all kinds of images.
-		if ( !areBothImagePluginsLoaded ) {
-			return getPositiveMatchPattern( element );
-		}
-
-		// The <img> can be standalone, wrapped in <figure>...</figure> (ImageBlock plugin) or
-		// wrapped in <figure><a>...</a></figure> (LinkImage plugin).
-		const imageType = element.getStyle( 'display' ) == 'block' || element.findAncestor( imageUtils.isBlockImageView ) ?
-			'imageBlock' :
-			'imageInline';
-
-		if ( imageType !== matchImageType ) {
-			return null;
-		}
-
-		return getPositiveMatchPattern( element );
-	};
-
-	function getPositiveMatchPattern( element ) {
-		const pattern = {
-			name: true
-		};
-
-		// This will trigger src consumption (See https://github.com/ckeditor/ckeditor5/issues/11530).
-		if ( element.hasAttribute( 'src' ) ) {
-			pattern.attributes = [ 'src' ];
-		}
-
-		return pattern;
-	}
+export function getImgViewElementMatcher(editor, matchImageType) {
+    const imageUtils = editor.plugins.get('ImageUtils');
+    const areBothImagePluginsLoaded = editor.plugins.has('ImageInlineEditing') && editor.plugins.has('ImageBlockEditing');
+    return element => {
+        // Check if the matched view element is an <img>.
+        if (!imageUtils.isInlineImageView(element)) {
+            return null;
+        }
+        // If just one of the plugins is loaded (block or inline), it will match all kinds of images.
+        if (!areBothImagePluginsLoaded) {
+            return getPositiveMatchPattern(element);
+        }
+        // The <img> can be standalone, wrapped in <figure>...</figure> (ImageBlock plugin) or
+        // wrapped in <figure><a>...</a></figure> (LinkImage plugin).
+        const imageType = element.getStyle('display') == 'block' || element.findAncestor(imageUtils.isBlockImageView) ?
+            'imageBlock' :
+            'imageInline';
+        if (imageType !== matchImageType) {
+            return null;
+        }
+        return getPositiveMatchPattern(element);
+    };
+    function getPositiveMatchPattern(element) {
+        const pattern = {
+            name: true
+        };
+        // This will trigger src consumption (See https://github.com/ckeditor/ckeditor5/issues/11530).
+        if (element.hasAttribute('src')) {
+            pattern.attributes = ['src'];
+        }
+        return pattern;
+    }
 }
-
 /**
  * Considering the current model selection, it returns the name of the model image element
  * (`'imageBlock'` or `'imageInline'`) that will make most sense from the UX perspective if a new
@@ -103,25 +82,19 @@ export function getImgViewElementMatcher( editor, matchImageType ) {
  * produce block images. Inline images should be inserted in other cases, e.g. in paragraphs
  * that already contain some text.
  *
- * @protected
- * @param {module:engine/model/schema~Schema} schema
- * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
- * @returns {'imageBlock'|'imageInline'}
+ * @internal
  */
-export function determineImageTypeForInsertionAtSelection( schema, selection ) {
-	const firstBlock = first( selection.getSelectedBlocks() );
-
-	// Insert a block image if the selection is not in/on block elements or it's on a block widget.
-	if ( !firstBlock || schema.isObject( firstBlock ) ) {
-		return 'imageBlock';
-	}
-
-	// A block image should also be inserted into an empty block element
-	// (that is not an empty list item so the list won't get split).
-	if ( firstBlock.isEmpty && firstBlock.name != 'listItem' ) {
-		return 'imageBlock';
-	}
-
-	// Otherwise insert an inline image.
-	return 'imageInline';
+export function determineImageTypeForInsertionAtSelection(schema, selection) {
+    const firstBlock = first(selection.getSelectedBlocks());
+    // Insert a block image if the selection is not in/on block elements or it's on a block widget.
+    if (!firstBlock || schema.isObject(firstBlock)) {
+        return 'imageBlock';
+    }
+    // A block image should also be inserted into an empty block element
+    // (that is not an empty list item so the list won't get split).
+    if (firstBlock.isEmpty && firstBlock.name != 'listItem') {
+        return 'imageBlock';
+    }
+    // Otherwise insert an inline image.
+    return 'imageInline';
 }

package/src/image.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @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
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import '../theme/image.css';
+import './imageconfig';
+/**
+ * The image plugin.
+ *
+ * For a detailed overview, check the {@glink features/images/images-overview image feature} documentation.
+ *
+ * This is a "glue" plugin which loads the following plugins:
+ *
+ * * {@link module:image/imageblock~ImageBlock},
+ * * {@link module:image/imageinline~ImageInline},
+ *
+ * Usually, it is used in conjunction with other plugins from this package. See the {@glink api/image package page}
+ * for more information.
+ */
+export default class Image extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Image';
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [Image.pluginName]: Image;
+    }
+}

package/src/image.js

@@ -2,18 +2,14 @@
  * @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
  */
-
 import { Plugin } from 'ckeditor5/src/core';
-
 import ImageBlock from './imageblock';
 import ImageInline from './imageinline';
-
 import '../theme/image.css';
-
+import './imageconfig';
 /**
  * The image plugin.
  *
@@ -26,44 +22,18 @@ import '../theme/image.css';
  *
  * Usually, it is used in conjunction with other plugins from this package. See the {@glink api/image package page}
  * for more information.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class Image extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ ImageBlock, ImageInline ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'Image';
-	}
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [ImageBlock, ImageInline];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'Image';
+    }
 }
-
-/**
- * The configuration of the image features. Used by the image features in the `@ckeditor/ckeditor5-image` package.
- *
- * Read more in {@link module:image/image~ImageConfig}.
- *
- * @member {module:image/image~ImageConfig} module:core/editor/editorconfig~EditorConfig#image
- */
-
-/**
- * The configuration of the image features. Used by the image features in the `@ckeditor/ckeditor5-image` package.
- *
- *		ClassicEditor
- *			.create( editorElement, {
- * 				image: ... // Image feature options.
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
- *
- * @interface ImageConfig
- */

package/src/imageblock.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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/imageblock
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import '../theme/image.css';
+/**
+ * The image block plugin.
+ *
+ * This is a "glue" plugin which loads the following plugins:
+ *
+ * * {@link module:image/image/imageblockediting~ImageBlockEditing},
+ * * {@link module:image/imagetextalternative~ImageTextAlternative}.
+ *
+ * Usually, it is used in conjunction with other plugins from this package. See the {@glink api/image package page}
+ * for more information.
+ */
+export default class ImageBlock extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'ImageBlock';
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [ImageBlock.pluginName]: ImageBlock;
+    }
+}

package/src/imageblock.js

@@ -2,19 +2,14 @@
  * @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/imageblock
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import { Widget } from 'ckeditor5/src/widget';
-
 import ImageTextAlternative from './imagetextalternative';
 import ImageBlockEditing from './image/imageblockediting';
-
 import '../theme/image.css';
-
 /**
  * The image block plugin.
  *
@@ -25,22 +20,18 @@ import '../theme/image.css';
  *
  * Usually, it is used in conjunction with other plugins from this package. See the {@glink api/image package page}
  * for more information.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class ImageBlock extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ ImageBlockEditing, Widget, ImageTextAlternative ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'ImageBlock';
-	}
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [ImageBlockEditing, Widget, ImageTextAlternative];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'ImageBlock';
+    }
 }
-

package/src/imagecaption/imagecaptionediting.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @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/imagecaption/imagecaptionediting
+ */
+import { type Editor, Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import { Element } from 'ckeditor5/src/engine';
+/**
+ * The image caption engine plugin. It is responsible for:
+ *
+ * * registering converters for the caption element,
+ * * registering converters for the caption model attribute,
+ * * registering the {@link module:image/imagecaption/toggleimagecaptioncommand~ToggleImageCaptionCommand `toggleImageCaption`} command.
+ */
+export default class ImageCaptionEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'ImageCaptionEditing';
+    /**
+     * A map that keeps saved JSONified image captions and image model elements they are
+     * associated with.
+     *
+     * To learn more about this system, see {@link #_saveCaption}.
+     */
+    private _savedCaptionsMap;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Configures conversion pipelines to support upcasting and downcasting
+     * image captions.
+     */
+    private _setupConversion;
+    /**
+     * Integrates with {@link module:image/image/imagetypecommand~ImageTypeCommand image type commands}
+     * to make sure the caption is preserved when the type of an image changes so it can be restored
+     * in the future if the user decides they want their caption back.
+     */
+    private _setupImageTypeCommandsIntegration;
+    /**
+     * Returns the saved {@link module:engine/model/element~Element#toJSON JSONified} caption
+     * of an image model element.
+     *
+     * See {@link #_saveCaption}.
+     *
+     * @internal
+     * @param imageModelElement The model element the caption should be returned for.
+     * @returns The model caption element or `null` if there is none.
+     */
+    _getSavedCaption(imageModelElement: Element): Element | null;
+    /**
+     * Saves a {@link module:engine/model/element~Element#toJSON JSONified} caption for
+     * an image element to allow restoring it in the future.
+     *
+     * A caption is saved every time it gets hidden and/or the type of an image changes. The
+     * user should be able to restore it on demand.
+     *
+     * **Note**: The caption cannot be stored in the image model element attribute because,
+     * for instance, when the model state propagates to collaborators, the attribute would get
+     * lost (mainly because it does not convert to anything when the caption is hidden) and
+     * the states of collaborators' models would de-synchronize causing numerous issues.
+     *
+     * See {@link #_getSavedCaption}.
+     *
+     * @internal
+     * @param imageModelElement The model element the caption is saved for.
+     * @param caption The caption model element to be saved.
+     */
+    _saveCaption(imageModelElement: Element, caption: Element): void;
+    /**
+     * Reconverts image caption when image alt attribute changes.
+     * The change of alt attribute is reflected in caption's aria-label attribute.
+     */
+    private _registerCaptionReconversion;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [ImageCaptionEditing.pluginName]: ImageCaptionEditing;
+    }
+}