@ckeditor/ckeditor5-image 41.1.0 → 41.3.0-alpha.0

package/dist/types/image.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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/image
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import ImageBlock from './imageblock.js';
+import ImageInline from './imageinline.js';
+import '../theme/image.css';
+/**
+ * The image plugin.
+ *
+ * For a detailed overview, check the {@glink features/images/images-overview image feature} documentation.
+ *
+ * This is a "glue" plugin which loads the following plugins:
+ *
+ * * {@link module:image/imageblock~ImageBlock},
+ * * {@link module:image/imageinline~ImageInline},
+ *
+ * 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 Image extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageBlock, typeof ImageInline];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Image";
+}

package/dist/types/imageblock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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/imageblock
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { Widget } from 'ckeditor5/src/widget.js';
+import ImageTextAlternative from './imagetextalternative.js';
+import ImageBlockEditing from './image/imageblockediting.js';
+import ImageInsertUI from './imageinsert/imageinsertui.js';
+import '../theme/image.css';
+/**
+ * The image block plugin.
+ *
+ * This is a "glue" plugin which loads the following plugins:
+ *
+ * * {@link module:image/image/imageblockediting~ImageBlockEditing},
+ * * {@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 ImageBlock extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageBlockEditing, typeof Widget, typeof ImageTextAlternative, typeof ImageInsertUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageBlock";
+}

package/dist/types/imagecaption/imagecaptionediting.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @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/imagecaptionediting
+ */
+import { type Editor, Plugin } from 'ckeditor5/src/core.js';
+import { Element } from 'ckeditor5/src/engine.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 default class ImageCaptionEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ImageUtils, typeof ImageCaptionUtils];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ImageCaptionEditing";
+    /**
+     * 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}.
+     */
+    private _savedCaptionsMap;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Configures conversion pipelines to support upcasting and downcasting
+     * image captions.
+     */
+    private _setupConversion;
+    /**
+     * 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.
+     */
+    private _setupImageTypeCommandsIntegration;
+    /**
+     * Returns the saved {@link module:engine/model/element~Element#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: Element): Element | null;
+    /**
+     * Saves a {@link module:engine/model/element~Element#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: Element, caption: Element): void;
+    /**
+     * Reconverts image caption when image alt attribute changes.
+     * The change of alt attribute is reflected in caption's aria-label attribute.
+     */
+    private _registerCaptionReconversion;
+}

package/dist/types/imagecaption/imagecaptionui.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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
+     */
+    init(): void;
+}

package/dist/types/imagecaption/imagecaptionutils.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
+ */
+/**
+ * @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 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/dist/types/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/dist/types/imagecaption.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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";
+}