@ckeditor/ckeditor5-image 0.0.0-internal-20241017.0

package/src/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
+ */
+/**
+ * @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
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/src/imagecaption/imagecaptionui.js

@@ -0,0 +1,67 @@
+/**
+ * @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, icons } from 'ckeditor5/src/core.js';
+import { ButtonView } from 'ckeditor5/src/ui.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() {
+        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: icons.caption,
+                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.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
+ */
+/**
+ * @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 isOfficialPlugin(): true;
+    /**
+     * @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/src/imagecaption/imagecaptionutils.js

@@ -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
+ */
+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() {
+        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.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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/src/imagecaption/toggleimagecaptioncommand.js

@@ -0,0 +1,138 @@
+/**
+ * @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';
+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 default 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.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
+ */
+/**
+ * @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";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+}

package/src/imagecaption.js

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