@ckeditor/ckeditor5-image 47.6.1 → 48.0.0-alpha.1

package/src/imagecaption/imagecaptionediting.js

@@ -1,238 +0,0 @@
-/**
- * @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 { Plugin } from 'ckeditor5/src/core.js';
-import { ModelElement, enableViewPlaceholder } from 'ckeditor5/src/engine.js';
-import { toWidgetEditable } from 'ckeditor5/src/widget.js';
-import { ToggleImageCaptionCommand } from './toggleimagecaptioncommand.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 class ImageCaptionEditing extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get requires() {
-        return [ImageUtils, ImageCaptionUtils];
-    }
-    /**
-     * @inheritDoc
-     */
-    static get pluginName() {
-        return 'ImageCaptionEditing';
-    }
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin() {
-        return 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}.
-     */
-    _savedCaptionsMap;
-    /**
-     * @inheritDoc
-     */
-    constructor(editor) {
-        super(editor);
-        this._savedCaptionsMap = new WeakMap();
-    }
-    /**
-     * @inheritDoc
-     */
-    init() {
-        const editor = this.editor;
-        const schema = editor.model.schema;
-        // Schema configuration.
-        if (!schema.isRegistered('caption')) {
-            schema.register('caption', {
-                allowIn: 'imageBlock',
-                allowContentOf: '$block',
-                isLimit: true
-            });
-        }
-        else {
-            schema.extend('caption', {
-                allowIn: 'imageBlock'
-            });
-        }
-        editor.commands.add('toggleImageCaption', new ToggleImageCaptionCommand(this.editor));
-        this._setupConversion();
-        this._setupImageTypeCommandsIntegration();
-        this._registerCaptionReconversion();
-    }
-    /**
-     * Configures conversion pipelines to support upcasting and downcasting
-     * image captions.
-     */
-    _setupConversion() {
-        const editor = this.editor;
-        const view = editor.editing.view;
-        const imageUtils = editor.plugins.get('ImageUtils');
-        const imageCaptionUtils = editor.plugins.get('ImageCaptionUtils');
-        const t = editor.t;
-        // View -> model converter for the data pipeline.
-        editor.conversion.for('upcast').elementToElement({
-            view: element => imageCaptionUtils.matchImageCaptionViewElement(element),
-            model: 'caption'
-        });
-        // Model -> view converter for the data pipeline.
-        editor.conversion.for('dataDowncast').elementToElement({
-            model: 'caption',
-            view: (modelElement, { writer }) => {
-                if (!imageUtils.isBlockImage(modelElement.parent)) {
-                    return null;
-                }
-                return writer.createContainerElement('figcaption');
-            }
-        });
-        // Model -> view converter for the editing pipeline.
-        editor.conversion.for('editingDowncast').elementToElement({
-            model: 'caption',
-            view: (modelElement, { writer }) => {
-                if (!imageUtils.isBlockImage(modelElement.parent)) {
-                    return null;
-                }
-                const figcaptionElement = writer.createEditableElement('figcaption');
-                writer.setCustomProperty('imageCaption', true, figcaptionElement);
-                figcaptionElement.placeholder = t('Enter image caption');
-                enableViewPlaceholder({
-                    view,
-                    element: figcaptionElement,
-                    keepOnFocus: true
-                });
-                const imageAlt = modelElement.parent.getAttribute('alt');
-                const label = imageAlt ? t('Caption for image: %0', [imageAlt]) : t('Caption for the image');
-                return toWidgetEditable(figcaptionElement, writer, { label });
-            }
-        });
-    }
-    /**
-     * 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.
-     */
-    _setupImageTypeCommandsIntegration() {
-        const editor = this.editor;
-        const imageUtils = editor.plugins.get('ImageUtils');
-        const imageCaptionUtils = editor.plugins.get('ImageCaptionUtils');
-        const imageTypeInlineCommand = editor.commands.get('imageTypeInline');
-        const imageTypeBlockCommand = editor.commands.get('imageTypeBlock');
-        const handleImageTypeChange = evt => {
-            // The image type command execution can be unsuccessful.
-            if (!evt.return) {
-                return;
-            }
-            const { oldElement, newElement } = evt.return;
-            /* istanbul ignore if: paranoid check -- @preserve */
-            if (!oldElement) {
-                return;
-            }
-            if (imageUtils.isBlockImage(oldElement)) {
-                const oldCaptionElement = imageCaptionUtils.getCaptionFromImageModelElement(oldElement);
-                // If the old element was a captioned block image (the caption was visible),
-                // simply save it so it can be restored.
-                if (oldCaptionElement) {
-                    this._saveCaption(newElement, oldCaptionElement);
-                    return;
-                }
-            }
-            const savedOldElementCaption = this._getSavedCaption(oldElement);
-            // If either:
-            //
-            // * the block image didn't have a visible caption,
-            // * the block image caption was hidden (and already saved),
-            // * the inline image was passed
-            //
-            // just try to "pass" the saved caption from the old image to the new image
-            // so it can be retrieved in the future if the user wants it back.
-            if (savedOldElementCaption) {
-                // Note: Since we're writing to a WeakMap, we don't bother with removing the
-                // [ oldElement, savedOldElementCaption ] pair from it.
-                this._saveCaption(newElement, savedOldElementCaption);
-            }
-        };
-        // Presence of the commands depends on the Image(Inline|Block)Editing plugins loaded in the editor.
-        if (imageTypeInlineCommand) {
-            this.listenTo(imageTypeInlineCommand, 'execute', handleImageTypeChange, { priority: 'low' });
-        }
-        if (imageTypeBlockCommand) {
-            this.listenTo(imageTypeBlockCommand, 'execute', handleImageTypeChange, { priority: 'low' });
-        }
-    }
-    /**
-     * 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) {
-        const jsonObject = this._savedCaptionsMap.get(imageModelElement);
-        return jsonObject ? ModelElement.fromJSON(jsonObject) : 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, caption) {
-        this._savedCaptionsMap.set(imageModelElement, caption.toJSON());
-    }
-    /**
-     * Reconverts image caption when image alt attribute changes.
-     * The change of alt attribute is reflected in caption's aria-label attribute.
-     */
-    _registerCaptionReconversion() {
-        const editor = this.editor;
-        const model = editor.model;
-        const imageUtils = editor.plugins.get('ImageUtils');
-        const imageCaptionUtils = editor.plugins.get('ImageCaptionUtils');
-        model.document.on('change:data', () => {
-            const changes = model.document.differ.getChanges();
-            for (const change of changes) {
-                if (change.attributeKey !== 'alt') {
-                    continue;
-                }
-                const image = change.range.start.nodeAfter;
-                if (imageUtils.isBlockImage(image)) {
-                    const caption = imageCaptionUtils.getCaptionFromImageModelElement(image);
-                    if (!caption) {
-                        return;
-                    }
-                    editor.editing.reconvertItem(caption);
-                }
-            }
-        });
-    }
-}

package/src/imagecaption/imagecaptionui.js

@@ -1,68 +0,0 @@
-/**
- * @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 'ckeditor5/src/core.js';
-import { ButtonView } from 'ckeditor5/src/ui.js';
-import { IconCaption } from 'ckeditor5/src/icons.js';
-import { ImageCaptionUtils } from './imagecaptionutils.js';
-/**
- * The image caption UI plugin. It introduces the `'toggleImageCaption'` UI button.
- */
-export class ImageCaptionUI extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get requires() {
-        return [ImageCaptionUtils];
-    }
-    /**
-     * @inheritDoc
-     */
-    static get pluginName() {
-        return 'ImageCaptionUI';
-    }
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin() {
-        return true;
-    }
-    /**
-     * @inheritDoc
-     */
-    init() {
-        const editor = this.editor;
-        const editingView = editor.editing.view;
-        const imageCaptionUtils = editor.plugins.get('ImageCaptionUtils');
-        const t = editor.t;
-        editor.ui.componentFactory.add('toggleImageCaption', locale => {
-            const command = editor.commands.get('toggleImageCaption');
-            const view = new ButtonView(locale);
-            view.set({
-                icon: IconCaption,
-                tooltip: true,
-                isToggleable: true
-            });
-            view.bind('isOn', 'isEnabled').to(command, 'value', 'isEnabled');
-            view.bind('label').to(command, 'value', value => value ? t('Toggle caption off') : t('Toggle caption on'));
-            this.listenTo(view, 'execute', () => {
-                editor.execute('toggleImageCaption', { focusCaptionOnShow: true });
-                // Scroll to the selection and highlight the caption if the caption showed up.
-                const modelCaptionElement = imageCaptionUtils.getCaptionFromModelSelection(editor.model.document.selection);
-                if (modelCaptionElement) {
-                    const figcaptionElement = editor.editing.mapper.toViewElement(modelCaptionElement);
-                    editingView.scrollToTheSelection();
-                    editingView.change(writer => {
-                        writer.addClass('image__caption_highlighted', figcaptionElement);
-                    });
-                }
-                editor.editing.view.focus();
-            });
-            return view;
-        });
-    }
-}

package/src/imagecaption/imagecaptionutils.js

@@ -1,68 +0,0 @@
-/**
- * @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
- */
-import { Plugin } from 'ckeditor5/src/core.js';
-import { ImageUtils } from '../imageutils.js';
-/**
- * The image caption utilities plugin.
- */
-export class ImageCaptionUtils extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get pluginName() {
-        return 'ImageCaptionUtils';
-    }
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin() {
-        return true;
-    }
-    /**
-     * @inheritDoc
-     */
-    static get requires() {
-        return [ImageUtils];
-    }
-    /**
-     * Returns the caption model element from a given image element. Returns `null` if no caption is found.
-     */
-    getCaptionFromImageModelElement(imageModelElement) {
-        for (const node of imageModelElement.getChildren()) {
-            if (!!node && node.is('element', 'caption')) {
-                return node;
-            }
-        }
-        return null;
-    }
-    /**
-     * Returns the caption model element for a model selection. Returns `null` if the selection has no caption element ancestor.
-     */
-    getCaptionFromModelSelection(selection) {
-        const imageUtils = this.editor.plugins.get('ImageUtils');
-        const captionElement = selection.getFirstPosition().findAncestor('caption');
-        if (!captionElement) {
-            return null;
-        }
-        if (imageUtils.isBlockImage(captionElement.parent)) {
-            return captionElement;
-        }
-        return 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) {
-        const imageUtils = this.editor.plugins.get('ImageUtils');
-        // Convert only captions for images.
-        if (element.name == 'figcaption' && imageUtils.isBlockImageView(element.parent)) {
-            return { name: true };
-        }
-        return null;
-    }
-}

package/src/imagecaption/toggleimagecaptioncommand.js

@@ -1,138 +0,0 @@
-/**
- * @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
- */
-import { Command } from 'ckeditor5/src/core.js';
-import { ImageBlockEditing } from '../image/imageblockediting.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 class ToggleImageCaptionCommand extends Command {
-    /**
-     * @inheritDoc
-     */
-    refresh() {
-        const editor = this.editor;
-        const imageCaptionUtils = editor.plugins.get('ImageCaptionUtils');
-        const imageUtils = editor.plugins.get('ImageUtils');
-        // Only block images can get captions.
-        if (!editor.plugins.has(ImageBlockEditing)) {
-            this.isEnabled = false;
-            this.value = false;
-            return;
-        }
-        const selection = editor.model.document.selection;
-        const selectedElement = selection.getSelectedElement();
-        if (!selectedElement) {
-            const ancestorCaptionElement = imageCaptionUtils.getCaptionFromModelSelection(selection);
-            this.isEnabled = !!ancestorCaptionElement;
-            this.value = !!ancestorCaptionElement;
-            return;
-        }
-        // Block images support captions by default but the command should also be enabled for inline
-        // images because toggling the caption when one is selected should convert it into a block image.
-        this.isEnabled = imageUtils.isImage(selectedElement);
-        if (!this.isEnabled) {
-            this.value = false;
-        }
-        else {
-            this.value = !!imageCaptionUtils.getCaptionFromImageModelElement(selectedElement);
-        }
-    }
-    /**
-     * 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 = {}) {
-        const { focusCaptionOnShow } = options;
-        this.editor.model.change(writer => {
-            if (this.value) {
-                this._hideImageCaption(writer);
-            }
-            else {
-                this._showImageCaption(writer, focusCaptionOnShow);
-            }
-        });
-    }
-    /**
-     * 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.
-     */
-    _showImageCaption(writer, focusCaptionOnShow) {
-        const model = this.editor.model;
-        const selection = model.document.selection;
-        const imageCaptionEditing = this.editor.plugins.get('ImageCaptionEditing');
-        const imageUtils = this.editor.plugins.get('ImageUtils');
-        let selectedImage = selection.getSelectedElement();
-        const savedCaption = imageCaptionEditing._getSavedCaption(selectedImage);
-        // Convert imageInline -> image first.
-        if (imageUtils.isInlineImage(selectedImage)) {
-            this.editor.execute('imageTypeBlock');
-            // Executing the command created a new model element. Let's pick it again.
-            selectedImage = selection.getSelectedElement();
-        }
-        // Try restoring the caption from the ImageCaptionEditing plugin storage.
-        const newCaptionElement = savedCaption || writer.createElement('caption');
-        writer.append(newCaptionElement, selectedImage);
-        if (focusCaptionOnShow) {
-            writer.setSelection(newCaptionElement, 'in');
-        }
-    }
-    /**
-     * 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.
-     */
-    _hideImageCaption(writer) {
-        const editor = this.editor;
-        const selection = editor.model.document.selection;
-        const imageCaptionEditing = editor.plugins.get('ImageCaptionEditing');
-        const imageCaptionUtils = editor.plugins.get('ImageCaptionUtils');
-        let selectedImage = selection.getSelectedElement();
-        let captionElement;
-        if (selectedImage) {
-            captionElement = imageCaptionUtils.getCaptionFromImageModelElement(selectedImage);
-        }
-        else {
-            captionElement = imageCaptionUtils.getCaptionFromModelSelection(selection);
-            selectedImage = captionElement.parent;
-        }
-        // Store the caption content so it can be restored quickly if the user changes their mind even if they toggle image<->imageInline.
-        imageCaptionEditing._saveCaption(selectedImage, captionElement);
-        writer.setSelection(selectedImage, 'on');
-        writer.remove(captionElement);
-    }
-}

package/src/imagecaption.js

@@ -1,36 +0,0 @@
-/**
- * @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
- */
-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 class ImageCaption extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get requires() {
-        return [ImageCaptionEditing, ImageCaptionUI];
-    }
-    /**
-     * @inheritDoc
-     */
-    static get pluginName() {
-        return 'ImageCaption';
-    }
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin() {
-        return true;
-    }
-}

package/src/imageconfig.js

@@ -1,5 +0,0 @@
-/**
- * @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
- */
-export {};

package/src/imageinline.js

@@ -1,44 +0,0 @@
-/**
- * @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/imageinline
- */
-import { Plugin } from 'ckeditor5/src/core.js';
-import { Widget } from 'ckeditor5/src/widget.js';
-import { ImageTextAlternative } from './imagetextalternative.js';
-import { ImageInlineEditing } from './image/imageinlineediting.js';
-import { ImageInsertUI } from './imageinsert/imageinsertui.js';
-import '../theme/image.css';
-/**
- * The image inline plugin.
- *
- * This is a "glue" plugin which loads the following plugins:
- *
- * * {@link module:image/image/imageinlineediting~ImageInlineEditing},
- * * {@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 class ImageInline extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get requires() {
-        return [ImageInlineEditing, Widget, ImageTextAlternative, ImageInsertUI];
-    }
-    /**
-     * @inheritDoc
-     */
-    static get pluginName() {
-        return 'ImageInline';
-    }
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin() {
-        return true;
-    }
-}