@ckeditor/ckeditor5-image 41.3.1 → 41.4.0

package/dist/types/imageinline.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/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 default class ImageInline extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageInlineEditing, typeof Widget, typeof ImageTextAlternative, typeof ImageInsertUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageInline";
+}

package/dist/types/imageinsert/imageinsertui.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @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/imageinsert/imageinsertui
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import { type Observable } from 'ckeditor5/src/utils.js';
+import { type ButtonView, type DropdownView, type FocusableView } from 'ckeditor5/src/ui.js';
+import ImageUtils from '../imageutils.js';
+/**
+ * The image insert dropdown plugin.
+ *
+ * For a detailed overview, check the {@glink features/images/image-upload/image-upload Image upload feature}
+ * and {@glink features/images/images-inserting Insert images via source URL} documentation.
+ *
+ * Adds the `'insertImage'` dropdown to the {@link module:ui/componentfactory~ComponentFactory UI component factory}
+ * and also the `imageInsert` dropdown as an alias for backward compatibility.
+ */
+export default class ImageInsertUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageInsertUI";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageUtils];
+    /**
+     * The dropdown view responsible for displaying the image insert UI.
+     */
+    dropdownView?: DropdownView;
+    /**
+     * Observable property used to alter labels while some image is selected and when it is not.
+     *
+     * @observable
+     */
+    isImageSelected: boolean;
+    /**
+     * Registered integrations map.
+     */
+    private _integrations;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Registers the insert image dropdown integration.
+     */
+    registerIntegration({ name, observable, buttonViewCreator, formViewCreator, requiresForm }: {
+        name: string;
+        observable: (Observable & {
+            isEnabled: boolean;
+        }) | (() => Observable & {
+            isEnabled: boolean;
+        });
+        buttonViewCreator: (isOnlyOne: boolean) => ButtonView;
+        formViewCreator: (isOnlyOne: boolean) => FocusableView;
+        requiresForm?: boolean;
+    }): void;
+    /**
+     * Creates the toolbar component.
+     */
+    private _createToolbarComponent;
+    /**
+     * Validates the integrations list.
+     */
+    private _prepareIntegrations;
+}

package/dist/types/imageinsert/imageinsertviaurlui.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/imageinsert/imageinsertviaurlui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import ImageInsertUI from './imageinsertui.js';
+/**
+ * The image insert via URL plugin (UI part).
+ *
+ * For a detailed overview, check the {@glink features/images/images-inserting
+ * Insert images via source URL} documentation.
+ *
+ * This plugin registers the {@link module:image/imageinsert/imageinsertui~ImageInsertUI} integration for `url`.
+ */
+export default class ImageInsertViaUrlUI extends Plugin {
+    private _imageInsertUI;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageInsertViaUrlUI";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageInsertUI];
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    /**
+     * Creates the view displayed in the dropdown.
+     */
+    private _createInsertUrlView;
+    /**
+     * Creates the toolbar button.
+     */
+    private _createInsertUrlButton;
+    /**
+     * Closes the dropdown.
+     */
+    private _closePanel;
+}

package/dist/types/imageinsert/ui/imageinsertformview.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @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/imageinsert/ui/imageinsertformview
+ */
+import { View, ViewCollection, FocusCycler, type FocusableView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import '../../../theme/imageinsert.css';
+/**
+ * The view displayed in the insert image dropdown.
+ *
+ * See {@link module:image/imageinsert/imageinsertui~ImageInsertUI}.
+ */
+export default class ImageInsertFormView extends View {
+    /**
+     * Tracks information about DOM focus in the form.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * A collection of views that can be focused in the form.
+     */
+    protected readonly _focusables: ViewCollection<FocusableView>;
+    /**
+     * Helps cycling over {@link #_focusables} in the form.
+     */
+    protected readonly _focusCycler: FocusCycler;
+    /**
+     * A collection of the defined integrations for inserting the images.
+     */
+    private readonly children;
+    /**
+     * Creates a view for the dropdown panel of {@link module:image/imageinsert/imageinsertui~ImageInsertUI}.
+     *
+     * @param locale The localization services instance.
+     * @param integrations An integrations object that contains components (or tokens for components) to be shown in the panel view.
+     */
+    constructor(locale: Locale, integrations?: Array<FocusableView>);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the first {@link #_focusables focusable} in the form.
+     */
+    focus(): void;
+}

package/dist/types/imageinsert/ui/imageinserturlview.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @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 { ButtonView, View, FocusCycler, LabeledFieldView, type InputTextView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+/**
+ * The insert an image via URL view.
+ *
+ * See {@link module:image/imageinsert/imageinsertviaurlui~ImageInsertViaUrlUI}.
+ */
+export default class ImageInsertUrlView extends View {
+    /**
+     * The URL input field view.
+     */
+    urlInputView: LabeledFieldView<InputTextView>;
+    /**
+     * The "insert/update" button view.
+     */
+    insertButtonView: ButtonView;
+    /**
+     * The "cancel" button view.
+     */
+    cancelButtonView: ButtonView;
+    /**
+     * The value of the URL input.
+     *
+     * @observable
+     */
+    imageURLInputValue: string;
+    /**
+     * Observable property used to alter labels while some image is selected and when it is not.
+     *
+     * @observable
+     */
+    isImageSelected: boolean;
+    /**
+     * Observable property indicating whether the form interactive elements should be enabled.
+     *
+     * @observable
+     */
+    isEnabled: boolean;
+    /**
+     * Tracks information about DOM focus in the form.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Helps cycling over {@link #_focusables} in the form.
+     */
+    readonly focusCycler: FocusCycler;
+    /**
+     * A collection of views that can be focused in the form.
+     */
+    private readonly _focusables;
+    /**
+     * Creates a view for the dropdown panel of {@link module:image/imageinsert/imageinsertui~ImageInsertUI}.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates the {@link #urlInputView}.
+     */
+    private _createUrlInputView;
+    /**
+     * Creates the {@link #insertButtonView}.
+     */
+    private _createInsertButton;
+    /**
+     * Creates the {@link #cancelButtonView}.
+     */
+    private _createCancelButton;
+    /**
+     * Focuses the view.
+     */
+    focus(direction: 1 | -1): void;
+}
+/**
+ * Fired when the form view is submitted.
+ *
+ * @eventName ~ImageInsertUrlView#submit
+ */
+export type ImageInsertUrlViewSubmitEvent = {
+    name: 'submit';
+    args: [];
+};
+/**
+ * Fired when the form view is canceled.
+ *
+ * @eventName ~ImageInsertUrlView#cancel
+ */
+export type ImageInsertUrlViewCancelEvent = {
+    name: 'cancel';
+    args: [];
+};

package/dist/types/imageinsert.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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/imageinsert
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import ImageUpload from './imageupload.js';
+import ImageInsertViaUrl from './imageinsertviaurl.js';
+import ImageInsertUI from './imageinsert/imageinsertui.js';
+/**
+ * The image insert plugin.
+ *
+ * For a detailed overview, check the {@glink features/images/image-upload/image-upload Image upload feature}
+ * and {@glink features/images/images-inserting Insert images via source URL} documentation.
+ *
+ * This plugin does not do anything directly, but it loads a set of specific plugins
+ * to enable image uploading or inserting via implemented integrations:
+ *
+ * * {@link module:image/imageupload~ImageUpload}
+ * * {@link module:image/imageinsert/imageinsertui~ImageInsertUI}
+ */
+export default class ImageInsert extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageInsert";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageUpload, typeof ImageInsertViaUrl, typeof ImageInsertUI];
+}

package/dist/types/imageinsertviaurl.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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/imageinsertviaurl
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import ImageInsertUI from './imageinsert/imageinsertui.js';
+import ImageInsertViaUrlUI from './imageinsert/imageinsertviaurlui.js';
+/**
+ * The image insert via URL plugin.
+ *
+ * For a detailed overview, check the {@glink features/images/images-inserting
+ * Insert images via source URL} documentation.
+ *
+ * This plugin does not do anything directly, but it loads a set of specific plugins
+ * to enable image inserting via implemented integrations:
+ *
+ * * {@link module:image/imageinsert/imageinsertui~ImageInsertUI},
+ */
+export default class ImageInsertViaUrl extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageInsertViaUrl";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageInsertViaUrlUI, typeof ImageInsertUI];
+}

package/dist/types/imageresize/imagecustomresizeui.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @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/imageresize/imagecustomresizeui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { ContextualBalloon } from 'ckeditor5/src/ui.js';
+/**
+ * The custom resize image UI plugin.
+ *
+ * The plugin uses the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon}.
+ */
+export default class ImageCustomResizeUI extends Plugin {
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon?;
+    /**
+     * A form containing a textarea and buttons, used to change the `alt` text value.
+     */
+    private _form?;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ContextualBalloon];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageCustomResizeUI";
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates the {@link module:image/imageresize/ui/imagecustomresizeformview~ImageCustomResizeFormView}
+     * form.
+     */
+    private _createForm;
+    /**
+     * Shows the {@link #_form} in the {@link #_balloon}.
+     *
+     * @internal
+     */
+    _showForm(unit: string): void;
+    /**
+     * Removes the {@link #_form} from the {@link #_balloon}.
+     *
+     * @param focusEditable Controls whether the editing view is focused afterwards.
+     */
+    private _hideForm;
+    /**
+     * Returns `true` when the {@link #_form} is the visible view in the {@link #_balloon}.
+     */
+    private get _isVisible();
+    /**
+     * Returns `true` when the {@link #_form} is in the {@link #_balloon}.
+     */
+    private get _isInBalloon();
+}

package/dist/types/imageresize/imageresizebuttons.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
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import ImageResizeEditing from './imageresizeediting.js';
+/**
+ * The image resize buttons plugin.
+ *
+ * It adds a possibility to resize images using the toolbar dropdown or individual buttons, depending on the plugin configuration.
+ */
+export default class ImageResizeButtons extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageResizeEditing];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageResizeButtons";
+    /**
+     * The resize unit.
+     * @default '%'
+     */
+    private readonly _resizeUnit;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * A helper function that creates a standalone button component for the plugin.
+     *
+     * @param resizeOption A model of the resize option.
+     */
+    private _registerImageResizeButton;
+    /**
+     * A helper function that creates a dropdown component for the plugin containing all the resize options defined in
+     * the editor configuration.
+     *
+     * @param options An array of configured options.
+     */
+    private _registerImageResizeDropdown;
+    /**
+     * A helper function for creating an option label value string.
+     *
+     * @param option A resize option object.
+     * @param forTooltip An optional flag for creating a tooltip label.
+     * @returns A user-defined label combined from the numeric value and the resize unit or the default label
+     * for reset options (`Original`).
+     */
+    private _getOptionLabelValue;
+    /**
+     * A helper function that parses the resize options and returns list item definitions ready for use in the dropdown.
+     *
+     * @param options The resize options.
+     * @param command The resize image command.
+     * @returns Dropdown item definitions.
+     */
+    private _getResizeDropdownListItemDefinitions;
+}

package/dist/types/imageresize/imageresizeediting.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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 { type Editor, Plugin } from 'ckeditor5/src/core.js';
+import ImageUtils from '../imageutils.js';
+/**
+ * The image resize editing feature.
+ *
+ * It adds the ability to resize each image using handles or manually by
+ * {@link module:image/imageresize/imageresizebuttons~ImageResizeButtons} buttons.
+ */
+export default class ImageResizeEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageUtils];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageResizeEditing";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    private _registerSchema;
+    /**
+     * Registers image resize converters.
+     *
+     * @param imageType The type of the image.
+     */
+    private _registerConverters;
+}

package/dist/types/imageresize/imageresizehandles.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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 { Plugin } from 'ckeditor5/src/core.js';
+import { WidgetResize } from 'ckeditor5/src/widget.js';
+import ImageUtils from '../imageutils.js';
+/**
+ * The image resize by handles feature.
+ *
+ * It adds the ability to resize each image using handles or manually by
+ * {@link module:image/imageresize/imageresizebuttons~ImageResizeButtons} buttons.
+ */
+export default class ImageResizeHandles extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof WidgetResize, typeof ImageUtils];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageResizeHandles";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Attaches the listeners responsible for creating a resizer for each image, except for images inside the HTML embed preview.
+     */
+    private _setupResizerCreator;
+}

package/dist/types/imageresize/resizeimagecommand.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @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/imageresize/resizeimagecommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The resize image command. Currently, it only supports the width attribute.
+ */
+export default class ResizeImageCommand extends Command {
+    /**
+     * Desired image width and height.
+     */
+    value: null | {
+        width: string | null;
+        height: string | null;
+    };
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * ```ts
+     * // Sets the width to 50%:
+     * editor.execute( 'resizeImage', { width: '50%' } );
+     *
+     * // Removes the width attribute:
+     * editor.execute( 'resizeImage', { width: null } );
+     * ```
+     *
+     * @param options
+     * @param options.width The new width of the image.
+     * @fires execute
+     */
+    execute(options: {
+        width: string | null;
+    }): void;
+}