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

package/src/imagecaption/imagecaptionutils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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/imagecaptionutils/utils
+ */
+import type { DocumentSelection, Element, Selection, ViewElement, Match } from 'ckeditor5/src/engine';
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * The image caption utilities plugin.
+ */
+export default class ImageCaptionUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'ImageCaptionUtils';
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * 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;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [ImageCaptionUtils.pluginName]: ImageCaptionUtils;
+    }
+}

package/src/imagecaption/imagecaptionutils.js

@@ -2,88 +2,61 @@
  * @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/imagecaptionutils/utils
- */
-
 import { Plugin } from 'ckeditor5/src/core';
-
 import ImageUtils from '../imageutils';
-
 /**
  * The image caption utilities plugin.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class ImageCaptionUtils extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'ImageCaptionUtils';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ ImageUtils ];
-	}
-
-	/**
-	 * Returns the caption model element from a given image element. Returns `null` if no caption is found.
-	 *
-	 * @param {module:engine/model/element~Element} imageModelElement
-	 * @returns {module:engine/model/element~Element|null}
-	 */
-	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.
-	 *
-	 * @param {module:engine/model/selection~Selection} selection
-	 * @returns {module:engine/model/element~Element|null}
-	 */
-	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.
-	 *
-	 * @param {module:engine/view/element~Element} element
-	 * @returns {Object|null} 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;
-	}
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'ImageCaptionUtils';
+    }
+    /**
+     * @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,71 @@
+/**
+ * @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
+ */
+import { Command } from 'ckeditor5/src/core';
+/**
+ * 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;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        toggleImageCaption: ToggleImageCaptionCommand;
+    }
+}

package/src/imagecaption/toggleimagecaptioncommand.js

@@ -2,15 +2,8 @@
  * @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/toggleimagecaptioncommand
- */
-
 import { Command } from 'ckeditor5/src/core';
-
 import ImageBlockEditing from '../image/imageblockediting';
-
 /**
  * The toggle image caption command.
  *
@@ -22,143 +15,124 @@ import ImageBlockEditing from '../image/imageblockediting';
  * * 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.
  *
- *		// Toggle the presence of the caption.
- *		editor.execute( 'toggleImageCaption' );
+ * ```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:
  *
- *		editor.execute( 'toggleImageCaption', { focusCaptionOnShow: true } );
- *
- * @extends module:core/command~Command
+ * ```ts
+ * editor.execute( 'toggleImageCaption', { focusCaptionOnShow: true } );
+ * ```
  */
 export default class ToggleImageCaptionCommand extends Command {
-	/**
-	 * @inheritDoc
-	 */
-	refresh() {
-		const editor = this.editor;
-		const imageCaptionUtils = editor.plugins.get( 'ImageCaptionUtils' );
-
-		// 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 = this.editor.plugins.get( 'ImageUtils' ).isImage( selectedElement );
-
-		if ( !this.isEnabled ) {
-			this.value = false;
-		} else {
-			this.value = !!imageCaptionUtils.getCaptionFromImageModelElement( selectedElement );
-		}
-	}
-
-	/**
-	 * Executes the command.
-	 *
-	 *		editor.execute( 'toggleImageCaption' );
-	 *
-	 * @param {Object} [options] Options for the executed command.
-	 * @param {String} [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.
-	 *
-	 * @private
-	 * @param {module:engine/model/writer~Writer} writer
-	 */
-	_showImageCaption( writer, focusCaptionOnShow ) {
-		const model = this.editor.model;
-		const selection = model.document.selection;
-		const imageCaptionEditing = this.editor.plugins.get( 'ImageCaptionEditing' );
-
-		let selectedImage = selection.getSelectedElement();
-
-		const savedCaption = imageCaptionEditing._getSavedCaption( selectedImage );
-
-		// Convert imageInline -> image first.
-		if ( this.editor.plugins.get( '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.
-	 *
-	 * @private
-	 * @param {module:engine/model/writer~Writer} writer
-	 */
-	_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 );
-	}
+    /**
+     * @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,29 @@
+/**
+ * @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
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+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(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'ImageCaption';
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [ImageCaption.pluginName]: ImageCaption;
+    }
+}

package/src/imagecaption.js

@@ -2,36 +2,29 @@
  * @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
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import ImageCaptionEditing from './imagecaption/imagecaptionediting';
 import ImageCaptionUI from './imagecaption/imagecaptionui';
-
 import '../theme/imagecaption.css';
-
 /**
  * The image caption plugin.
  *
  * For a detailed overview, check the {@glink features/images/images-captions image caption} documentation.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class ImageCaption extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ ImageCaptionEditing, ImageCaptionUI ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'ImageCaption';
-	}
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [ImageCaptionEditing, ImageCaptionUI];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'ImageCaption';
+    }
 }