@ckeditor/ckeditor5-image 41.3.0 → 41.4.0-alpha.0

package/dist/types/image/imagetypecommand.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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/imagetypecommand
+ */
+import type { Element } from 'ckeditor5/src/engine.js';
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+/**
+ * The image type command. It changes the type of a selected image, depending on the configuration.
+ */
+export default class ImageTypeCommand extends Command {
+    /**
+     * Model element name the command converts to.
+     */
+    private readonly _modelElementName;
+    /**
+     * @inheritDoc
+     *
+     * @param modelElementName Model element name the command converts to.
+     */
+    constructor(editor: Editor, modelElementName: 'imageBlock' | 'imageInline');
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command and changes the type of a selected image.
+     *
+     * @fires execute
+     * @param options.setImageSizes Specifies whether the image `width` and `height` attributes should be set automatically.
+     * The default is `true`.
+     * @returns An object containing references to old and new model image elements
+     * (for before and after the change) so external integrations can hook into the decorated
+     * `execute` event and handle this change. `null` if the type change failed.
+     */
+    execute(options?: {
+        setImageSizes?: boolean;
+    }): {
+        oldElement: Element;
+        newElement: Element;
+    } | null;
+}

package/dist/types/image/insertimagecommand.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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/insertimagecommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+import { type ArrayOrItem } from 'ckeditor5/src/utils.js';
+/**
+ * Insert image command.
+ *
+ * The command is registered by the {@link module:image/image/imageediting~ImageEditing} plugin as `insertImage`
+ * and it is also available via aliased `imageInsert` name.
+ *
+ * In order to insert an image at the current selection position
+ * (according to the {@link module:widget/utils~findOptimalInsertionRange} algorithm),
+ * execute the command and specify the image source:
+ *
+ * ```ts
+ * editor.execute( 'insertImage', { source: 'http://url.to.the/image' } );
+ * ```
+ *
+ * It is also possible to insert multiple images at once:
+ *
+ * ```ts
+ * editor.execute( 'insertImage', {
+ * 	source:  [
+ * 		'path/to/image.jpg',
+ * 		'path/to/other-image.jpg'
+ * 	]
+ * } );
+ * ```
+ *
+ * If you want to take the full control over the process, you can specify individual model attributes:
+ *
+ * ```ts
+ * editor.execute( 'insertImage', {
+ * 	source:  [
+ * 		{ src: 'path/to/image.jpg', alt: 'First alt text' },
+ * 		{ src: 'path/to/other-image.jpg', alt: 'Second alt text', customAttribute: 'My attribute value' }
+ * 	]
+ * } );
+ * ```
+ */
+export default class InsertImageCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options Options for the executed command.
+     * @param options.source The image source or an array of image sources to insert.
+     * See the documentation of the command to learn more about accepted formats.
+     */
+    execute(options: {
+        source: ArrayOrItem<string | Record<string, unknown>>;
+    }): void;
+}

package/dist/types/image/replaceimagesourcecommand.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+import type { Writer, Element } from 'ckeditor5/src/engine.js';
+/**
+ * @module image/image/replaceimagesourcecommand
+ */
+/**
+ * Replace image source command.
+ *
+ * Changes image source to the one provided. Can be executed as follows:
+ *
+ * ```ts
+ * editor.execute( 'replaceImageSource', { source: 'http://url.to.the/image' } );
+ * ```
+ */
+export default class ReplaceImageSourceCommand extends Command {
+    value: string | null;
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options Options for the executed command.
+     * @param options.source The image source to replace.
+     */
+    execute(options: {
+        source: string;
+    }): void;
+    /**
+     * Cleanup image attributes that are not relevant to the new source.
+     *
+     * Removed attributes are: 'srcset', 'sizes', 'sources', 'width', 'height', 'alt'.
+     *
+     * This method is decorated, to allow custom cleanup logic.
+     * For example, to remove 'myImageId' attribute after 'src' has changed:
+     *
+     * ```ts
+     * replaceImageSourceCommand.on( 'cleanupImage', ( eventInfo, [ writer, image ] ) => {
+     * 	writer.removeAttribute( 'myImageId', image );
+     * } );
+     * ```
+     */
+    cleanupImage(writer: Writer, image: Element): void;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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 type { PositionOptions } from 'ckeditor5/src/utils.js';
+import type { Editor } from 'ckeditor5/src/core.js';
+/**
+ * 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.
+ */
+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.
+ */
+export declare function getBalloonPositionData(editor: Editor): Partial<PositionOptions>;

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

@@ -0,0 +1,68 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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, ViewElement } from 'ckeditor5/src/engine.js';
+import type { Editor } from 'ckeditor5/src/core.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
+ */
+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';
+/**
+ * Returns parsed value of the size, but only if it contains unit: px.
+ */
+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.
+ */
+export declare function widthAndHeightStylesAreBothSet(viewElement: ViewElement): boolean;

package/dist/types/image.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+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.
+ */
+export default class Image extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageBlock, typeof ImageInline];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Image";
+}

package/dist/types/imageblock.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import { Widget } from 'ckeditor5/src/widget.js';
+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.
+ */
+export default class ImageBlock extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageBlockEditing, typeof Widget, typeof ImageTextAlternative, typeof ImageInsertUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageBlock";
+}

package/dist/types/imagecaption/imagecaptionediting.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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 } from 'ckeditor5/src/core.js';
+import { Element } from 'ckeditor5/src/engine.js';
+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.
+ */
+export default class ImageCaptionEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageUtils, typeof ImageCaptionUtils];
+    /**
+     * @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;
+}

package/dist/types/imagecaption/imagecaptionui.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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/imagecaptionui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import ImageCaptionUtils from './imagecaptionutils.js';
+/**
+ * The image caption UI plugin. It introduces the `'toggleImageCaption'` UI button.
+ */
+export default class ImageCaptionUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageCaptionUtils];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageCaptionUI";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/imagecaption/imagecaptionutils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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/imagecaptionutils
+ */
+import type { DocumentSelection, Element, Selection, ViewElement, Match } from 'ckeditor5/src/engine.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+import ImageUtils from '../imageutils.js';
+/**
+ * The image caption utilities plugin.
+ */
+export default class ImageCaptionUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageCaptionUtils";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageUtils];
+    /**
+     * Returns the caption model element from a given image element. Returns `null` if no caption is found.
+     */
+    getCaptionFromImageModelElement(imageModelElement: Element): Element | null;
+    /**
+     * Returns the caption model element for a model selection. Returns `null` if the selection has no caption element ancestor.
+     */
+    getCaptionFromModelSelection(selection: Selection | DocumentSelection): Element | null;
+    /**
+     * {@link module:engine/view/matcher~Matcher} pattern. Checks if a given element is a `<figcaption>` element that is placed
+     * inside the image `<figure>` element.
+     * @returns Returns the object accepted by {@link module:engine/view/matcher~Matcher} or `null` if the element
+     * cannot be matched.
+     */
+    matchImageCaptionViewElement(element: ViewElement): Match | null;
+}

package/dist/types/imagecaption/toggleimagecaptioncommand.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The toggle image caption command.
+ *
+ * This command is registered by {@link module:image/imagecaption/imagecaptionediting~ImageCaptionEditing} as the
+ * `'toggleImageCaption'` editor command.
+ *
+ * Executing this command:
+ *
+ * * either adds or removes the image caption of a selected image (depending on whether the caption is present or not),
+ * * removes the image caption if the selection is anchored in one.
+ *
+ * ```ts
+ * // Toggle the presence of the caption.
+ * editor.execute( 'toggleImageCaption' );
+ * ```
+ *
+ * **Note**: Upon executing this command, the selection will be set on the image if previously anchored in the caption element.
+ *
+ * **Note**: You can move the selection to the caption right away as it shows up upon executing this command by using
+ * the `focusCaptionOnShow` option:
+ *
+ * ```ts
+ * editor.execute( 'toggleImageCaption', { focusCaptionOnShow: true } );
+ * ```
+ */
+export default class ToggleImageCaptionCommand extends Command {
+    value: boolean;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * ```ts
+     * editor.execute( 'toggleImageCaption' );
+     * ```
+     *
+     * @param options Options for the executed command.
+     * @param options.focusCaptionOnShow When true and the caption shows up, the selection will be moved into it straight away.
+     * @fires execute
+     */
+    execute(options?: {
+        focusCaptionOnShow?: boolean;
+    }): void;
+    /**
+     * Shows the caption of the `<imageBlock>` or `<imageInline>`. Also:
+     *
+     * * it converts `<imageInline>` to `<imageBlock>` to show the caption,
+     * * it attempts to restore the caption content from the `ImageCaptionEditing` caption registry,
+     * * it moves the selection to the caption right away, it the `focusCaptionOnShow` option was set.
+     */
+    private _showImageCaption;
+    /**
+     * Hides the caption of a selected image (or an image caption the selection is anchored to).
+     *
+     * The content of the caption is stored in the `ImageCaptionEditing` caption registry to make this
+     * a reversible action.
+     */
+    private _hideImageCaption;
+}

package/dist/types/imagecaption.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import ImageCaptionEditing from './imagecaption/imagecaptionediting.js';
+import ImageCaptionUI from './imagecaption/imagecaptionui.js';
+import '../theme/imagecaption.css';
+/**
+ * The image caption plugin.
+ *
+ * For a detailed overview, check the {@glink features/images/images-captions image caption} documentation.
+ */
+export default class ImageCaption extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageCaptionEditing, typeof ImageCaptionUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageCaption";
+}