@ckeditor/ckeditor5-image 48.2.0 → 48.3.0-alpha.0

package/dist/image/ui/utils.d.ts

@@ -1,27 +1,27 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
 /**
- * @module image/image/ui/utils
- */
-import type { DomOptimalPositionOptions } from '@ckeditor/ckeditor5-utils';
-import type { Editor } from '@ckeditor/ckeditor5-core';
+* @module image/image/ui/utils
+*/
+import type { DomOptimalPositionOptions } from "@ckeditor/ckeditor5-utils";
+import type { Editor } from "@ckeditor/ckeditor5-core";
 /**
- * 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 editor The editor instance.
- * @internal
- */
+* 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 editor The editor instance.
+* @internal
+*/
 export declare function repositionContextualBalloon(editor: Editor): void;
 /**
- * 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 editor The editor instance.
- * @internal
- */
+* 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 editor The editor instance.
+* @internal
+*/
 export declare function getBalloonPositionData(editor: Editor): Partial<DomOptimalPositionOptions>;

package/dist/image/utils.d.ts

@@ -1,68 +1,101 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
 /**
- * @module image/image/utils
- */
-import type { ModelDocumentSelection, MatcherPattern, ModelSchema, ModelSelection, ViewContainerElement, ViewDowncastWriter, ViewElement } from '@ckeditor/ckeditor5-engine';
-import type { Editor } from '@ckeditor/ckeditor5-core';
+* @module image/image/utils
+*/
+import { type ModelDocumentSelection, type MatcherPattern, type ModelPosition, type ModelSchema, type ModelSelection, type ViewContainerElement, type ViewDowncastWriter, type ViewElement } from "@ckeditor/ckeditor5-engine";
+import type { Editor } from "@ckeditor/ckeditor5-core";
+import { type ImageUtils } from "../imageutils.js";
 /**
- * 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
- */
+* 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: ViewDowncastWriter): 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
- */
+* 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: ViewDowncastWriter): 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;
+* A function returning a `MatcherPattern` for a particular type of View images.
+*
+* @deprecated
+* @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: ModelSchema, selection: ModelSelection | ModelDocumentSelection): 'imageBlock' | 'imageInline';
+* Resolves the model image type (`'imageBlock'` or `'imageInline'`) that a given `<img>` view element represents,
+* based purely on its view structure.
+*
+* An `<img>` is treated as a block image when it has a `display: block` style or is wrapped in a block image figure
+* (`<figure class="image">`, also `<figure class="image"><a>...</a></figure>` added by the `LinkImage` plugin).
+* Otherwise it is treated as an inline image.
+*
+* Note that this only reflects the view representation - it does not check whether the resolved type is allowed by the
+* schema at the insertion position.
+*
+* @internal
+* @param element The `<img>` view element to resolve the type for.
+* @param imageUtils The `ImageUtils` plugin instance.
+*/
+export declare function getViewImageType(element: ViewElement, imageUtils: ImageUtils): "imageBlock" | "imageInline";
 /**
- * Returns parsed value of the size, but only if it contains unit: px.
- *
- * @internal
- */
+* Checks whether the given image type can be placed at the specified position - either directly (or after hoisting
+* to an allowed ancestor) or, for inline images, wrapped in an auto-created paragraph.
+*
+* This is the predicate that decides whether a block image may land at a position or must degrade to an inline image
+* (for example, inside an `$inlineRoot` that disallows block content) and, symmetrically, whether an inline image may
+* become a block image. `isParagraphable()` is always `false` for `imageBlock` (a block object never fits in a
+* paragraph), so the auto-paragraph relaxation only applies to the inline target.
+*
+* @internal
+* @param schema The model schema to check against.
+* @param position The position at which the image type should be placed.
+* @param imageType The image type to check.
+*/
+export declare function isImageTypePlaceable(schema: ModelSchema, position: ModelPosition, imageType: "imageBlock" | "imageInline"): boolean;
+/**
+* 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: ModelSchema, selection: ModelSelection | ModelDocumentSelection): "imageBlock" | "imageInline";
+/**
+* Returns parsed value of the size, but only if it contains unit: px.
+*
+* @internal
+*/
 export declare function getSizeValueIfInPx(size: string | undefined): number | null;
 /**
- * Returns true if both styles (width and height) are set.
- *
- * If both image styles: width & height are set, they will override the image width & height attributes in the
- * browser. In this case, the image looks the same as if these styles were applied to attributes instead of styles.
- * That's why we can upcast these styles to width & height attributes instead of resizedWidth and resizedHeight.
- *
- * @internal
- */
+* Returns true if both styles (width and height) are set.
+*
+* If both image styles: width & height are set, they will override the image width & height attributes in the
+* browser. In this case, the image looks the same as if these styles were applied to attributes instead of styles.
+* That's why we can upcast these styles to width & height attributes instead of resizedWidth and resizedHeight.
+*
+* @internal
+*/
 export declare function widthAndHeightStylesAreBothSet(viewElement: ViewElement): boolean;

package/dist/image.d.ts

@@ -1,38 +1,38 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
 /**
- * @module image/image
- */
-import { Plugin } from '@ckeditor/ckeditor5-core';
-import { ImageBlock } from './imageblock.js';
-import { ImageInline } from './imageinline.js';
-import '../theme/image.css';
+* @module image/image
+*/
+import { Plugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { ImageBlock } from "./imageblock.js";
+import { ImageInline } from "./imageinline.js";
+import "../theme/image.css";
 /**
- * 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.
- */
+* 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 declare class Image extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get requires(): readonly [typeof ImageBlock, typeof ImageInline];
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "Image";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[ImageBlock, ImageInline]>;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "Image";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
 }

package/dist/imageblock.d.ts

@@ -1,38 +1,38 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
 /**
- * @module image/imageblock
- */
-import { Plugin } from '@ckeditor/ckeditor5-core';
-import { Widget } from '@ckeditor/ckeditor5-widget';
-import { ImageTextAlternative } from './imagetextalternative.js';
-import { ImageBlockEditing } from './image/imageblockediting.js';
-import { ImageInsertUI } from './imageinsert/imageinsertui.js';
-import '../theme/image.css';
+* @module image/imageblock
+*/
+import { Plugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { Widget } from "@ckeditor/ckeditor5-widget";
+import { ImageTextAlternative } from "./imagetextalternative.js";
+import { ImageBlockEditing } from "./image/imageblockediting.js";
+import { ImageInsertUI } from "./imageinsert/imageinsertui.js";
+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.
- */
+* 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 declare class ImageBlock extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get requires(): readonly [typeof ImageBlockEditing, typeof Widget, typeof ImageTextAlternative, typeof ImageInsertUI];
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "ImageBlock";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[ImageBlockEditing, Widget, ImageTextAlternative, ImageInsertUI]>;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "ImageBlock";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
 }

package/dist/imagecaption/imagecaptionediting.d.ts

@@ -1,93 +1,93 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
 /**
- * @module image/imagecaption/imagecaptionediting
- */
-import { type Editor, Plugin } from '@ckeditor/ckeditor5-core';
-import { ModelElement } from '@ckeditor/ckeditor5-engine';
-import { ImageUtils } from '../imageutils.js';
-import { ImageCaptionUtils } from './imagecaptionutils.js';
+* @module image/imagecaption/imagecaptionediting
+*/
+import { type Editor, Plugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { ModelElement } from "@ckeditor/ckeditor5-engine";
+import { ImageUtils } from "../imageutils.js";
+import { ImageCaptionUtils } from "./imagecaptionutils.js";
 /**
- * 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.
- */
+* 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 declare class ImageCaptionEditing extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get requires(): readonly [typeof ImageUtils, typeof ImageCaptionUtils];
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "ImageCaptionEditing";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
-    /**
-     * 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~ModelElement#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: ModelElement): ModelElement | null;
-    /**
-     * Saves a {@link module:engine/model/element~ModelElement#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: ModelElement, caption: ModelElement): void;
-    /**
-     * Reconverts image caption when image alt attribute changes.
-     * The change of alt attribute is reflected in caption's aria-label attribute.
-     */
-    private _registerCaptionReconversion;
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[ImageUtils, ImageCaptionUtils]>;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "ImageCaptionEditing";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* 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~ModelElement#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: ModelElement): ModelElement | null;
+	/**
+	* Saves a {@link module:engine/model/element~ModelElement#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: ModelElement, caption: ModelElement): void;
+	/**
+	* Reconverts image caption when image alt attribute changes.
+	* The change of alt attribute is reflected in caption's aria-label attribute.
+	*/
+	private _registerCaptionReconversion;
 }

package/dist/imagecaption/imagecaptionui.d.ts

@@ -1,30 +1,30 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
 /**
- * @module image/imagecaption/imagecaptionui
- */
-import { Plugin } from '@ckeditor/ckeditor5-core';
-import { ImageCaptionUtils } from './imagecaptionutils.js';
+* @module image/imagecaption/imagecaptionui
+*/
+import { Plugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { ImageCaptionUtils } from "./imagecaptionutils.js";
 /**
- * The image caption UI plugin. It introduces the `'toggleImageCaption'` UI button.
- */
+* The image caption UI plugin. It introduces the `'toggleImageCaption'` UI button.
+*/
 export declare class ImageCaptionUI extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get requires(): readonly [typeof ImageCaptionUtils];
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "ImageCaptionUI";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    init(): void;
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[ImageCaptionUtils]>;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "ImageCaptionUI";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	init(): void;
 }