@ckeditor/ckeditor5-image 39.0.2 → 40.0.0

package/src/imageupload/utils.js

@@ -1,112 +1,112 @@
-/**
- * @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 { global } from 'ckeditor5/src/utils';
-/**
- * Creates a regular expression used to test for image files.
- *
- * ```ts
- * const imageType = createImageTypeRegExp( [ 'png', 'jpeg', 'svg+xml', 'vnd.microsoft.icon' ] );
- *
- * console.log( 'is supported image', imageType.test( file.type ) );
- * ```
- */
-export function createImageTypeRegExp(types) {
-    // Sanitize the MIME type name which may include: "+", "-" or ".".
-    const regExpSafeNames = types.map(type => type.replace('+', '\\+'));
-    return new RegExp(`^image\\/(${regExpSafeNames.join('|')})$`);
-}
-/**
- * Creates a promise that fetches the image local source (Base64 or blob) and resolves with a `File` object.
- *
- * @param image Image whose source to fetch.
- * @returns A promise which resolves when an image source is fetched and converted to a `File` instance.
- * It resolves with a `File` object. If there were any errors during file processing, the promise will be rejected.
- */
-export function fetchLocalImage(image) {
-    return new Promise((resolve, reject) => {
-        const imageSrc = image.getAttribute('src');
-        // Fetch works asynchronously and so does not block browser UI when processing data.
-        fetch(imageSrc)
-            .then(resource => resource.blob())
-            .then(blob => {
-            const mimeType = getImageMimeType(blob, imageSrc);
-            const ext = mimeType.replace('image/', '');
-            const filename = `image.${ext}`;
-            const file = new File([blob], filename, { type: mimeType });
-            resolve(file);
-        })
-            .catch(err => {
-            // Fetch fails only, if it can't make a request due to a network failure or if anything prevented the request
-            // from completing, i.e. the Content Security Policy rules. It is not possible to detect the exact cause of failure,
-            // so we are just trying the fallback solution, if general TypeError is thrown.
-            return err && err.name === 'TypeError' ?
-                convertLocalImageOnCanvas(imageSrc).then(resolve).catch(reject) :
-                reject(err);
-        });
-    });
-}
-/**
- * Checks whether a given node is an image element with a local source (Base64 or blob).
- *
- * @param node The node to check.
- */
-export function isLocalImage(imageUtils, node) {
-    if (!imageUtils.isInlineImageView(node) || !node.getAttribute('src')) {
-        return false;
-    }
-    return !!node.getAttribute('src').match(/^data:image\/\w+;base64,/g) ||
-        !!node.getAttribute('src').match(/^blob:/g);
-}
-/**
- * Extracts an image type based on its blob representation or its source.
- * @param blob Image blob representation.
- * @param src Image `src` attribute value.
- */
-function getImageMimeType(blob, src) {
-    if (blob.type) {
-        return blob.type;
-    }
-    else if (src.match(/data:(image\/\w+);base64/)) {
-        return src.match(/data:(image\/\w+);base64/)[1].toLowerCase();
-    }
-    else {
-        // Fallback to 'jpeg' as common extension.
-        return 'image/jpeg';
-    }
-}
-/**
- * Creates a promise that converts the image local source (Base64 or blob) to a blob using canvas and resolves
- * with a `File` object.
- * @param imageSrc Image `src` attribute value.
- * @returns A promise which resolves when an image source is converted to a `File` instance.
- * It resolves with a `File` object. If there were any errors during file processing, the promise will be rejected.
- */
-function convertLocalImageOnCanvas(imageSrc) {
-    return getBlobFromCanvas(imageSrc).then(blob => {
-        const mimeType = getImageMimeType(blob, imageSrc);
-        const ext = mimeType.replace('image/', '');
-        const filename = `image.${ext}`;
-        return new File([blob], filename, { type: mimeType });
-    });
-}
-/**
- * Creates a promise that resolves with a `Blob` object converted from the image source (Base64 or blob).
- * @param imageSrc Image `src` attribute value.
- */
-function getBlobFromCanvas(imageSrc) {
-    return new Promise((resolve, reject) => {
-        const image = global.document.createElement('img');
-        image.addEventListener('load', () => {
-            const canvas = global.document.createElement('canvas');
-            canvas.width = image.width;
-            canvas.height = image.height;
-            const ctx = canvas.getContext('2d');
-            ctx.drawImage(image, 0, 0);
-            canvas.toBlob(blob => blob ? resolve(blob) : reject());
-        });
-        image.addEventListener('error', () => reject());
-        image.src = imageSrc;
-    });
-}
+/**
+ * @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 { global } from 'ckeditor5/src/utils';
+/**
+ * Creates a regular expression used to test for image files.
+ *
+ * ```ts
+ * const imageType = createImageTypeRegExp( [ 'png', 'jpeg', 'svg+xml', 'vnd.microsoft.icon' ] );
+ *
+ * console.log( 'is supported image', imageType.test( file.type ) );
+ * ```
+ */
+export function createImageTypeRegExp(types) {
+    // Sanitize the MIME type name which may include: "+", "-" or ".".
+    const regExpSafeNames = types.map(type => type.replace('+', '\\+'));
+    return new RegExp(`^image\\/(${regExpSafeNames.join('|')})$`);
+}
+/**
+ * Creates a promise that fetches the image local source (Base64 or blob) and resolves with a `File` object.
+ *
+ * @param image Image whose source to fetch.
+ * @returns A promise which resolves when an image source is fetched and converted to a `File` instance.
+ * It resolves with a `File` object. If there were any errors during file processing, the promise will be rejected.
+ */
+export function fetchLocalImage(image) {
+    return new Promise((resolve, reject) => {
+        const imageSrc = image.getAttribute('src');
+        // Fetch works asynchronously and so does not block browser UI when processing data.
+        fetch(imageSrc)
+            .then(resource => resource.blob())
+            .then(blob => {
+            const mimeType = getImageMimeType(blob, imageSrc);
+            const ext = mimeType.replace('image/', '');
+            const filename = `image.${ext}`;
+            const file = new File([blob], filename, { type: mimeType });
+            resolve(file);
+        })
+            .catch(err => {
+            // Fetch fails only, if it can't make a request due to a network failure or if anything prevented the request
+            // from completing, i.e. the Content Security Policy rules. It is not possible to detect the exact cause of failure,
+            // so we are just trying the fallback solution, if general TypeError is thrown.
+            return err && err.name === 'TypeError' ?
+                convertLocalImageOnCanvas(imageSrc).then(resolve).catch(reject) :
+                reject(err);
+        });
+    });
+}
+/**
+ * Checks whether a given node is an image element with a local source (Base64 or blob).
+ *
+ * @param node The node to check.
+ */
+export function isLocalImage(imageUtils, node) {
+    if (!imageUtils.isInlineImageView(node) || !node.getAttribute('src')) {
+        return false;
+    }
+    return !!node.getAttribute('src').match(/^data:image\/\w+;base64,/g) ||
+        !!node.getAttribute('src').match(/^blob:/g);
+}
+/**
+ * Extracts an image type based on its blob representation or its source.
+ * @param blob Image blob representation.
+ * @param src Image `src` attribute value.
+ */
+function getImageMimeType(blob, src) {
+    if (blob.type) {
+        return blob.type;
+    }
+    else if (src.match(/data:(image\/\w+);base64/)) {
+        return src.match(/data:(image\/\w+);base64/)[1].toLowerCase();
+    }
+    else {
+        // Fallback to 'jpeg' as common extension.
+        return 'image/jpeg';
+    }
+}
+/**
+ * Creates a promise that converts the image local source (Base64 or blob) to a blob using canvas and resolves
+ * with a `File` object.
+ * @param imageSrc Image `src` attribute value.
+ * @returns A promise which resolves when an image source is converted to a `File` instance.
+ * It resolves with a `File` object. If there were any errors during file processing, the promise will be rejected.
+ */
+function convertLocalImageOnCanvas(imageSrc) {
+    return getBlobFromCanvas(imageSrc).then(blob => {
+        const mimeType = getImageMimeType(blob, imageSrc);
+        const ext = mimeType.replace('image/', '');
+        const filename = `image.${ext}`;
+        return new File([blob], filename, { type: mimeType });
+    });
+}
+/**
+ * Creates a promise that resolves with a `Blob` object converted from the image source (Base64 or blob).
+ * @param imageSrc Image `src` attribute value.
+ */
+function getBlobFromCanvas(imageSrc) {
+    return new Promise((resolve, reject) => {
+        const image = global.document.createElement('img');
+        image.addEventListener('load', () => {
+            const canvas = global.document.createElement('canvas');
+            canvas.width = image.width;
+            canvas.height = image.height;
+            const ctx = canvas.getContext('2d');
+            ctx.drawImage(image, 0, 0);
+            canvas.toBlob(blob => blob ? resolve(blob) : reject());
+        });
+        image.addEventListener('error', () => reject());
+        image.src = imageSrc;
+    });
+}

package/src/imageupload.d.ts

@@ -1,32 +1,32 @@
-/**
- * @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/imageupload
- */
-import { Plugin } from 'ckeditor5/src/core';
-import ImageUploadUI from './imageupload/imageuploadui';
-import ImageUploadProgress from './imageupload/imageuploadprogress';
-import ImageUploadEditing from './imageupload/imageuploadediting';
-/**
- * The image upload plugin.
- *
- * For a detailed overview, check the {@glink features/images/image-upload/image-upload image upload feature} documentation.
- *
- * This plugin does not do anything directly, but it loads a set of specific plugins to enable image uploading:
- *
- * * {@link module:image/imageupload/imageuploadediting~ImageUploadEditing},
- * * {@link module:image/imageupload/imageuploadui~ImageUploadUI},
- * * {@link module:image/imageupload/imageuploadprogress~ImageUploadProgress}.
- */
-export default class ImageUpload extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "ImageUpload";
-    /**
-     * @inheritDoc
-     */
-    static get requires(): readonly [typeof ImageUploadEditing, typeof ImageUploadUI, typeof ImageUploadProgress];
-}
+/**
+ * @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/imageupload
+ */
+import { Plugin } from 'ckeditor5/src/core';
+import ImageUploadUI from './imageupload/imageuploadui';
+import ImageUploadProgress from './imageupload/imageuploadprogress';
+import ImageUploadEditing from './imageupload/imageuploadediting';
+/**
+ * The image upload plugin.
+ *
+ * For a detailed overview, check the {@glink features/images/image-upload/image-upload image upload feature} documentation.
+ *
+ * This plugin does not do anything directly, but it loads a set of specific plugins to enable image uploading:
+ *
+ * * {@link module:image/imageupload/imageuploadediting~ImageUploadEditing},
+ * * {@link module:image/imageupload/imageuploadui~ImageUploadUI},
+ * * {@link module:image/imageupload/imageuploadprogress~ImageUploadProgress}.
+ */
+export default class ImageUpload extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageUpload";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageUploadEditing, typeof ImageUploadUI, typeof ImageUploadProgress];
+}

package/src/imageupload.js

@@ -1,36 +1,36 @@
-/**
- * @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/imageupload
- */
-import { Plugin } from 'ckeditor5/src/core';
-import ImageUploadUI from './imageupload/imageuploadui';
-import ImageUploadProgress from './imageupload/imageuploadprogress';
-import ImageUploadEditing from './imageupload/imageuploadediting';
-/**
- * The image upload plugin.
- *
- * For a detailed overview, check the {@glink features/images/image-upload/image-upload image upload feature} documentation.
- *
- * This plugin does not do anything directly, but it loads a set of specific plugins to enable image uploading:
- *
- * * {@link module:image/imageupload/imageuploadediting~ImageUploadEditing},
- * * {@link module:image/imageupload/imageuploadui~ImageUploadUI},
- * * {@link module:image/imageupload/imageuploadprogress~ImageUploadProgress}.
- */
-export default class ImageUpload extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get pluginName() {
-        return 'ImageUpload';
-    }
-    /**
-     * @inheritDoc
-     */
-    static get requires() {
-        return [ImageUploadEditing, ImageUploadUI, ImageUploadProgress];
-    }
-}
+/**
+ * @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/imageupload
+ */
+import { Plugin } from 'ckeditor5/src/core';
+import ImageUploadUI from './imageupload/imageuploadui';
+import ImageUploadProgress from './imageupload/imageuploadprogress';
+import ImageUploadEditing from './imageupload/imageuploadediting';
+/**
+ * The image upload plugin.
+ *
+ * For a detailed overview, check the {@glink features/images/image-upload/image-upload image upload feature} documentation.
+ *
+ * This plugin does not do anything directly, but it loads a set of specific plugins to enable image uploading:
+ *
+ * * {@link module:image/imageupload/imageuploadediting~ImageUploadEditing},
+ * * {@link module:image/imageupload/imageuploadui~ImageUploadUI},
+ * * {@link module:image/imageupload/imageuploadprogress~ImageUploadProgress}.
+ */
+export default class ImageUpload extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'ImageUpload';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [ImageUploadEditing, ImageUploadUI, ImageUploadProgress];
+    }
+}

package/src/imageutils.d.ts

@@ -1,102 +1,125 @@
-/**
- * @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/imageutils
- */
-import type { Element, ViewElement, DocumentSelection, ViewDocumentSelection, Selection, ViewSelection, DowncastWriter, Position } from 'ckeditor5/src/engine';
-import { Plugin } from 'ckeditor5/src/core';
-/**
- * A set of helpers related to images.
- */
-export default class ImageUtils extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "ImageUtils";
-    /**
-     * Checks if the provided model element is an `image` or `imageInline`.
-     */
-    isImage(modelElement?: Element | null): modelElement is Element & {
-        name: 'imageInline' | 'imageBlock';
-    };
-    /**
-     * Checks if the provided view element represents an inline image.
-     *
-     * Also, see {@link module:image/imageutils~ImageUtils#isImageWidget}.
-     */
-    isInlineImageView(element?: ViewElement | null): boolean;
-    /**
-     * Checks if the provided view element represents a block image.
-     *
-     * Also, see {@link module:image/imageutils~ImageUtils#isImageWidget}.
-     */
-    isBlockImageView(element?: ViewElement | null): boolean;
-    /**
-     * Handles inserting single file. This method unifies image insertion using {@link module:widget/utils~findOptimalInsertionRange}
-     * method.
-     *
-     * ```ts
-     * const imageUtils = editor.plugins.get( 'ImageUtils' );
-     *
-     * imageUtils.insertImage( { src: 'path/to/image.jpg' } );
-     * ```
-     *
-     * @param attributes Attributes of the inserted image.
-     * This method filters out the attributes which are disallowed by the {@link module:engine/model/schema~Schema}.
-     * @param selectable Place to insert the image. If not specified,
-     * the {@link module:widget/utils~findOptimalInsertionRange} logic will be applied for the block images
-     * and `model.document.selection` for the inline images.
-     *
-     * **Note**: If `selectable` is passed, this helper will not be able to set selection attributes (such as `linkHref`)
-     * and apply them to the new image. In this case, make sure all selection attributes are passed in `attributes`.
-     *
-     * @param imageType Image type of inserted image. If not specified,
-     * it will be determined automatically depending of editor config or place of the insertion.
-     * @return The inserted model image element.
-     */
-    insertImage(attributes?: Record<string, unknown>, selectable?: Selection | Position | null, imageType?: ('imageBlock' | 'imageInline' | null)): Element | null;
-    /**
-     * Returns an image widget editing view element if one is selected or is among the selection's ancestors.
-     */
-    getClosestSelectedImageWidget(selection: ViewSelection | ViewDocumentSelection): ViewElement | null;
-    /**
-     * Returns a image model element if one is selected or is among the selection's ancestors.
-     */
-    getClosestSelectedImageElement(selection: Selection | DocumentSelection): Element | null;
-    /**
-     * Checks if image can be inserted at current model selection.
-     *
-     * @internal
-     */
-    isImageAllowed(): boolean;
-    /**
-     * Converts a given {@link module:engine/view/element~Element} to an image widget:
-     * * Adds a {@link module:engine/view/element~Element#_setCustomProperty custom property} allowing to recognize the image widget
-     * element.
-     * * Calls the {@link module:widget/utils~toWidget} function with the proper element's label creator.
-     *
-     * @param writer An instance of the view writer.
-     * @param label The element's label. It will be concatenated with the image `alt` attribute if one is present.
-     */
-    toImageWidget(viewElement: ViewElement, writer: DowncastWriter, label: string): ViewElement;
-    /**
-     * Checks if a given view element is an image widget.
-     */
-    protected isImageWidget(viewElement: ViewElement): boolean;
-    /**
-     * Checks if the provided model element is an `image`.
-     */
-    isBlockImage(modelElement?: Element | null): boolean;
-    /**
-     * Checks if the provided model element is an `imageInline`.
-     */
-    isInlineImage(modelElement?: Element | null): boolean;
-    /**
-     * Get the view `<img>` from another view element, e.g. a widget (`<figure class="image">`), a link (`<a>`).
-     *
-     * The `<img>` can be located deep in other elements, so this helper performs a deep tree search.
-     */
-    findViewImgElement(figureView: ViewElement): ViewElement | undefined;
-}
+/**
+ * @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/imageutils
+ */
+import type { Element, ViewElement, DocumentSelection, ViewDocumentSelection, Selection, ViewSelection, DowncastWriter, Position, ViewContainerElement } from 'ckeditor5/src/engine';
+import { Plugin } from 'ckeditor5/src/core';
+/**
+ * A set of helpers related to images.
+ */
+export default class ImageUtils extends Plugin {
+    /**
+     * DOM Emitter.
+     */
+    private _domEmitter;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageUtils";
+    /**
+     * Checks if the provided model element is an `image` or `imageInline`.
+     */
+    isImage(modelElement?: Element | null): modelElement is Element & {
+        name: 'imageInline' | 'imageBlock';
+    };
+    /**
+     * Checks if the provided view element represents an inline image.
+     *
+     * Also, see {@link module:image/imageutils~ImageUtils#isImageWidget}.
+     */
+    isInlineImageView(element?: ViewElement | null): boolean;
+    /**
+     * Checks if the provided view element represents a block image.
+     *
+     * Also, see {@link module:image/imageutils~ImageUtils#isImageWidget}.
+     */
+    isBlockImageView(element?: ViewElement | null): boolean;
+    /**
+     * Handles inserting single file. This method unifies image insertion using {@link module:widget/utils~findOptimalInsertionRange}
+     * method.
+     *
+     * ```ts
+     * const imageUtils = editor.plugins.get( 'ImageUtils' );
+     *
+     * imageUtils.insertImage( { src: 'path/to/image.jpg' } );
+     * ```
+     *
+     * @param attributes Attributes of the inserted image.
+     * This method filters out the attributes which are disallowed by the {@link module:engine/model/schema~Schema}.
+     * @param selectable Place to insert the image. If not specified,
+     * the {@link module:widget/utils~findOptimalInsertionRange} logic will be applied for the block images
+     * and `model.document.selection` for the inline images.
+     *
+     * **Note**: If `selectable` is passed, this helper will not be able to set selection attributes (such as `linkHref`)
+     * and apply them to the new image. In this case, make sure all selection attributes are passed in `attributes`.
+     *
+     * @param imageType Image type of inserted image. If not specified,
+     * it will be determined automatically depending of editor config or place of the insertion.
+     * @param options.setImageSizes Specifies whether the image `width` and `height` attributes should be set automatically.
+     * The default is `true`.
+     * @return The inserted model image element.
+     */
+    insertImage(attributes?: Record<string, unknown>, selectable?: Selection | Position | null, imageType?: ('imageBlock' | 'imageInline' | null), options?: {
+        setImageSizes?: boolean;
+    }): Element | null;
+    /**
+     * Reads original image sizes and sets them as `width` and `height`.
+     *
+     * The `src` attribute may not be available if the user is using an upload adapter. In such a case,
+     * this method is called again after the upload process is complete and the `src` attribute is available.
+     */
+    setImageNaturalSizeAttributes(imageElement: Element): void;
+    /**
+     * Returns an image widget editing view element if one is selected or is among the selection's ancestors.
+     */
+    getClosestSelectedImageWidget(selection: ViewSelection | ViewDocumentSelection): ViewElement | null;
+    /**
+     * Returns a image model element if one is selected or is among the selection's ancestors.
+     */
+    getClosestSelectedImageElement(selection: Selection | DocumentSelection): Element | null;
+    /**
+     * Returns an image widget editing view based on the passed image view.
+     */
+    getImageWidgetFromImageView(imageView: ViewElement): ViewContainerElement | null;
+    /**
+     * Checks if image can be inserted at current model selection.
+     *
+     * @internal
+     */
+    isImageAllowed(): boolean;
+    /**
+     * Converts a given {@link module:engine/view/element~Element} to an image widget:
+     * * Adds a {@link module:engine/view/element~Element#_setCustomProperty custom property} allowing to recognize the image widget
+     * element.
+     * * Calls the {@link module:widget/utils~toWidget} function with the proper element's label creator.
+     *
+     * @param writer An instance of the view writer.
+     * @param label The element's label. It will be concatenated with the image `alt` attribute if one is present.
+     */
+    toImageWidget(viewElement: ViewElement, writer: DowncastWriter, label: string): ViewElement;
+    /**
+     * Checks if a given view element is an image widget.
+     */
+    protected isImageWidget(viewElement: ViewElement): boolean;
+    /**
+     * Checks if the provided model element is an `image`.
+     */
+    isBlockImage(modelElement?: Element | null): boolean;
+    /**
+     * Checks if the provided model element is an `imageInline`.
+     */
+    isInlineImage(modelElement?: Element | null): boolean;
+    /**
+     * Get the view `<img>` from another view element, e.g. a widget (`<figure class="image">`), a link (`<a>`).
+     *
+     * The `<img>` can be located deep in other elements, so this helper performs a deep tree search.
+     */
+    findViewImgElement(figureView: ViewElement): ViewElement | undefined;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}