@ckeditor/ckeditor5-link 0.0.0-internal-20241017.0

package/src/linkimage.js

@@ -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
+ */
+/**
+ * @module link/linkimage
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import LinkImageEditing from './linkimageediting.js';
+import LinkImageUI from './linkimageui.js';
+import '../theme/linkimage.css';
+/**
+ * The `LinkImage` plugin.
+ *
+ * This is a "glue" plugin that loads the {@link module:link/linkimageediting~LinkImageEditing link image editing feature}
+ * and {@link module:link/linkimageui~LinkImageUI link image UI feature}.
+ */
+export default class LinkImage extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [LinkImageEditing, LinkImageUI];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'LinkImage';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+}

package/src/linkimageediting.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @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 link/linkimageediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import LinkEditing from './linkediting.js';
+/**
+ * The link image engine feature.
+ *
+ * It accepts the `linkHref="url"` attribute in the model for the {@link module:image/image~Image `<imageBlock>`} element
+ * which allows linking images.
+ */
+export default class LinkImageEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly ["ImageEditing", "ImageUtils", typeof LinkEditing];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LinkImageEditing";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    /**
+     * Processes {@link module:link/linkconfig~LinkDecoratorAutomaticDefinition automatic decorators} definitions and
+     * attaches proper converters that will work when linking an image.`
+     */
+    private _enableAutomaticDecorators;
+    /**
+     * Processes transformed {@link module:link/utils/manualdecorator~ManualDecorator} instances and attaches proper converters
+     * that will work when linking an image.
+     */
+    private _enableManualDecorators;
+}

package/src/linkimageediting.js

@@ -0,0 +1,251 @@
+/**
+ * @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 link/linkimageediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { Matcher } from 'ckeditor5/src/engine.js';
+import { toMap } from 'ckeditor5/src/utils.js';
+import LinkEditing from './linkediting.js';
+/**
+ * The link image engine feature.
+ *
+ * It accepts the `linkHref="url"` attribute in the model for the {@link module:image/image~Image `<imageBlock>`} element
+ * which allows linking images.
+ */
+export default class LinkImageEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return ['ImageEditing', 'ImageUtils', LinkEditing];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'LinkImageEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    afterInit() {
+        const editor = this.editor;
+        const schema = editor.model.schema;
+        if (editor.plugins.has('ImageBlockEditing')) {
+            schema.extend('imageBlock', { allowAttributes: ['linkHref'] });
+        }
+        editor.conversion.for('upcast').add(upcastLink(editor));
+        editor.conversion.for('downcast').add(downcastImageLink(editor));
+        // Definitions for decorators are provided by the `link` command and the `LinkEditing` plugin.
+        this._enableAutomaticDecorators();
+        this._enableManualDecorators();
+    }
+    /**
+     * Processes {@link module:link/linkconfig~LinkDecoratorAutomaticDefinition automatic decorators} definitions and
+     * attaches proper converters that will work when linking an image.`
+     */
+    _enableAutomaticDecorators() {
+        const editor = this.editor;
+        const command = editor.commands.get('link');
+        const automaticDecorators = command.automaticDecorators;
+        if (automaticDecorators.length) {
+            editor.conversion.for('downcast').add(automaticDecorators.getDispatcherForLinkedImage());
+        }
+    }
+    /**
+     * Processes transformed {@link module:link/utils/manualdecorator~ManualDecorator} instances and attaches proper converters
+     * that will work when linking an image.
+     */
+    _enableManualDecorators() {
+        const editor = this.editor;
+        const command = editor.commands.get('link');
+        for (const decorator of command.manualDecorators) {
+            if (editor.plugins.has('ImageBlockEditing')) {
+                editor.model.schema.extend('imageBlock', { allowAttributes: decorator.id });
+            }
+            if (editor.plugins.has('ImageInlineEditing')) {
+                editor.model.schema.extend('imageInline', { allowAttributes: decorator.id });
+            }
+            editor.conversion.for('downcast').add(downcastImageLinkManualDecorator(decorator));
+            editor.conversion.for('upcast').add(upcastImageLinkManualDecorator(editor, decorator));
+        }
+    }
+}
+/**
+ * Returns a converter for linked block images that consumes the "href" attribute
+ * if a link contains an image.
+ *
+ * @param editor The editor instance.
+ */
+function upcastLink(editor) {
+    const isImageInlinePluginLoaded = editor.plugins.has('ImageInlineEditing');
+    const imageUtils = editor.plugins.get('ImageUtils');
+    return dispatcher => {
+        dispatcher.on('element:a', (evt, data, conversionApi) => {
+            const viewLink = data.viewItem;
+            const imageInLink = imageUtils.findViewImgElement(viewLink);
+            if (!imageInLink) {
+                return;
+            }
+            const blockImageView = imageInLink.findAncestor(element => imageUtils.isBlockImageView(element));
+            // There are four possible cases to consider here
+            //
+            // 1. A "root > ... > figure.image > a > img" structure.
+            // 2. A "root > ... > figure.image > a > picture > img" structure.
+            // 3. A "root > ... > block > a > img" structure.
+            // 4. A "root > ... > block > a > picture > img" structure.
+            //
+            // but the last 2 cases should only be considered by this converter when the inline image plugin
+            // is NOT loaded in the editor (because otherwise, that would be a plain, linked inline image).
+            if (isImageInlinePluginLoaded && !blockImageView) {
+                return;
+            }
+            // There's an image inside an <a> element - we consume it so it won't be picked up by the Link plugin.
+            const consumableAttributes = { attributes: ['href'] };
+            // Consume the `href` attribute so the default one will not convert it to $text attribute.
+            if (!conversionApi.consumable.consume(viewLink, consumableAttributes)) {
+                // Might be consumed by something else - i.e. other converter with priority=highest - a standard check.
+                return;
+            }
+            const linkHref = viewLink.getAttribute('href');
+            // Missing the 'href' attribute.
+            if (!linkHref) {
+                return;
+            }
+            // A full definition of the image feature.
+            // figure > a > img: parent of the view link element is an image element (figure).
+            let modelElement = data.modelCursor.parent;
+            if (!modelElement.is('element', 'imageBlock')) {
+                // a > img: parent of the view link is not the image (figure) element. We need to convert it manually.
+                const conversionResult = conversionApi.convertItem(imageInLink, data.modelCursor);
+                // Set image range as conversion result.
+                data.modelRange = conversionResult.modelRange;
+                // Continue conversion where image conversion ends.
+                data.modelCursor = conversionResult.modelCursor;
+                modelElement = data.modelCursor.nodeBefore;
+            }
+            if (modelElement && modelElement.is('element', 'imageBlock')) {
+                // Set the linkHref attribute from link element on model image element.
+                conversionApi.writer.setAttribute('linkHref', linkHref, modelElement);
+            }
+        }, { priority: 'high' });
+        // Using the same priority that `upcastImageLinkManualDecorator()` converter guarantees
+        // that manual decorators will decorate the proper element.
+    };
+}
+/**
+ * Creates a converter that adds `<a>` to linked block image view elements.
+ */
+function downcastImageLink(editor) {
+    const imageUtils = editor.plugins.get('ImageUtils');
+    return dispatcher => {
+        dispatcher.on('attribute:linkHref:imageBlock', (evt, data, conversionApi) => {
+            if (!conversionApi.consumable.consume(data.item, evt.name)) {
+                return;
+            }
+            // The image will be already converted - so it will be present in the view.
+            const viewFigure = conversionApi.mapper.toViewElement(data.item);
+            const writer = conversionApi.writer;
+            // But we need to check whether the link element exists.
+            const linkInImage = Array.from(viewFigure.getChildren())
+                .find((child) => child.is('element', 'a'));
+            const viewImage = imageUtils.findViewImgElement(viewFigure);
+            // <picture>...<img/></picture> or <img/>
+            const viewImgOrPicture = viewImage.parent.is('element', 'picture') ? viewImage.parent : viewImage;
+            // If so, update the attribute if it's defined or remove the entire link if the attribute is empty.
+            if (linkInImage) {
+                if (data.attributeNewValue) {
+                    writer.setAttribute('href', data.attributeNewValue, linkInImage);
+                }
+                else {
+                    writer.move(writer.createRangeOn(viewImgOrPicture), writer.createPositionAt(viewFigure, 0));
+                    writer.remove(linkInImage);
+                }
+            }
+            else {
+                // But if it does not exist. Let's wrap already converted image by newly created link element.
+                // 1. Create an empty link element.
+                const linkElement = writer.createContainerElement('a', { href: data.attributeNewValue });
+                // 2. Insert link inside the associated image.
+                writer.insert(writer.createPositionAt(viewFigure, 0), linkElement);
+                // 3. Move the image to the link.
+                writer.move(writer.createRangeOn(viewImgOrPicture), writer.createPositionAt(linkElement, 0));
+            }
+        }, { priority: 'high' });
+    };
+}
+/**
+ * Returns a converter that decorates the `<a>` element when the image is the link label.
+ */
+function downcastImageLinkManualDecorator(decorator) {
+    return dispatcher => {
+        dispatcher.on(`attribute:${decorator.id}:imageBlock`, (evt, data, conversionApi) => {
+            const viewFigure = conversionApi.mapper.toViewElement(data.item);
+            const linkInImage = Array.from(viewFigure.getChildren())
+                .find((child) => child.is('element', 'a'));
+            // The <a> element was removed by the time this converter is executed.
+            // It may happen when the base `linkHref` and decorator attributes are removed
+            // at the same time (see #8401).
+            if (!linkInImage) {
+                return;
+            }
+            for (const [key, val] of toMap(decorator.attributes)) {
+                conversionApi.writer.setAttribute(key, val, linkInImage);
+            }
+            if (decorator.classes) {
+                conversionApi.writer.addClass(decorator.classes, linkInImage);
+            }
+            for (const key in decorator.styles) {
+                conversionApi.writer.setStyle(key, decorator.styles[key], linkInImage);
+            }
+        });
+    };
+}
+/**
+ * Returns a converter that checks whether manual decorators should be applied to the link.
+ */
+function upcastImageLinkManualDecorator(editor, decorator) {
+    const isImageInlinePluginLoaded = editor.plugins.has('ImageInlineEditing');
+    const imageUtils = editor.plugins.get('ImageUtils');
+    return dispatcher => {
+        dispatcher.on('element:a', (evt, data, conversionApi) => {
+            const viewLink = data.viewItem;
+            const imageInLink = imageUtils.findViewImgElement(viewLink);
+            // We need to check whether an image is inside a link because the converter handles
+            // only manual decorators for linked images. See #7975.
+            if (!imageInLink) {
+                return;
+            }
+            const blockImageView = imageInLink.findAncestor(element => imageUtils.isBlockImageView(element));
+            if (isImageInlinePluginLoaded && !blockImageView) {
+                return;
+            }
+            const matcher = new Matcher(decorator._createPattern());
+            const result = matcher.match(viewLink);
+            // The link element does not have required attributes or/and proper values.
+            if (!result) {
+                return;
+            }
+            // Check whether we can consume those attributes.
+            if (!conversionApi.consumable.consume(viewLink, result.match)) {
+                return;
+            }
+            // At this stage we can assume that we have the `<imageBlock>` element.
+            // `nodeBefore` comes after conversion: `<a><img></a>`.
+            // `parent` comes with full image definition: `<figure><a><img></a></figure>.
+            // See the body of the `upcastLink()` function.
+            const modelElement = data.modelCursor.nodeBefore || data.modelCursor.parent;
+            conversionApi.writer.setAttribute(decorator.id, true, modelElement);
+        }, { priority: 'high' });
+        // Using the same priority that `upcastLink()` converter guarantees that the linked image was properly converted.
+    };
+}

package/src/linkimageui.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @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 LinkUI from './linkui.js';
+import LinkEditing from './linkediting.js';
+/**
+ * The link image UI plugin.
+ *
+ * This plugin provides the `'linkImage'` button that can be displayed in the {@link module:image/imagetoolbar~ImageToolbar}.
+ * It can be used to wrap images in links.
+ */
+export default class LinkImageUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof LinkEditing, typeof LinkUI, "ImageBlockEditing"];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LinkImageUI";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates a `LinkImageUI` button view.
+     *
+     * Clicking this button shows a {@link module:link/linkui~LinkUI#_balloon} attached to the selection.
+     * When an image is already linked, the view shows {@link module:link/linkui~LinkUI#actionsView} or
+     * {@link module:link/linkui~LinkUI#formView} if it is not.
+     */
+    private _createToolbarLinkImageButton;
+    /**
+     * Returns true if a linked image (either block or inline) is the only selected element
+     * in the model document.
+     */
+    private _isSelectedLinkedImage;
+}

package/src/linkimageui.js

@@ -0,0 +1,102 @@
+/**
+ * @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 link/linkimageui
+ */
+import { ButtonView } from 'ckeditor5/src/ui.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+import LinkUI from './linkui.js';
+import LinkEditing from './linkediting.js';
+import { LINK_KEYSTROKE } from './utils.js';
+import linkIcon from '../theme/icons/link.svg';
+/**
+ * The link image UI plugin.
+ *
+ * This plugin provides the `'linkImage'` button that can be displayed in the {@link module:image/imagetoolbar~ImageToolbar}.
+ * It can be used to wrap images in links.
+ */
+export default class LinkImageUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [LinkEditing, LinkUI, 'ImageBlockEditing'];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'LinkImageUI';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const viewDocument = editor.editing.view.document;
+        this.listenTo(viewDocument, 'click', (evt, data) => {
+            if (this._isSelectedLinkedImage(editor.model.document.selection)) {
+                // Prevent browser navigation when clicking a linked image.
+                data.preventDefault();
+                // Block the `LinkUI` plugin when an image was clicked.
+                // In such a case, we'd like to display the image toolbar.
+                evt.stop();
+            }
+        }, { priority: 'high' });
+        this._createToolbarLinkImageButton();
+    }
+    /**
+     * Creates a `LinkImageUI` button view.
+     *
+     * Clicking this button shows a {@link module:link/linkui~LinkUI#_balloon} attached to the selection.
+     * When an image is already linked, the view shows {@link module:link/linkui~LinkUI#actionsView} or
+     * {@link module:link/linkui~LinkUI#formView} if it is not.
+     */
+    _createToolbarLinkImageButton() {
+        const editor = this.editor;
+        const t = editor.t;
+        editor.ui.componentFactory.add('linkImage', locale => {
+            const button = new ButtonView(locale);
+            const plugin = editor.plugins.get('LinkUI');
+            const linkCommand = editor.commands.get('link');
+            button.set({
+                isEnabled: true,
+                label: t('Link image'),
+                icon: linkIcon,
+                keystroke: LINK_KEYSTROKE,
+                tooltip: true,
+                isToggleable: true
+            });
+            // Bind button to the command.
+            button.bind('isEnabled').to(linkCommand, 'isEnabled');
+            button.bind('isOn').to(linkCommand, 'value', value => !!value);
+            // Show the actionsView or formView (both from LinkUI) on button click depending on whether the image is linked already.
+            this.listenTo(button, 'execute', () => {
+                if (this._isSelectedLinkedImage(editor.model.document.selection)) {
+                    plugin._addActionsView();
+                }
+                else {
+                    plugin._showUI(true);
+                }
+            });
+            return button;
+        });
+    }
+    /**
+     * Returns true if a linked image (either block or inline) is the only selected element
+     * in the model document.
+     */
+    _isSelectedLinkedImage(selection) {
+        const selectedModelElement = selection.getSelectedElement();
+        const imageUtils = this.editor.plugins.get('ImageUtils');
+        return imageUtils.isImage(selectedModelElement) && selectedModelElement.hasAttribute('linkHref');
+    }
+}

package/src/linkui.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @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 link/linkui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { ContextualBalloon, type ViewWithCssTransitionDisabler } from 'ckeditor5/src/ui.js';
+import LinkFormView from './ui/linkformview.js';
+import LinkActionsView from './ui/linkactionsview.js';
+/**
+ * The link UI plugin. It introduces the `'link'` and `'unlink'` buttons and support for the <kbd>Ctrl+K</kbd> keystroke.
+ *
+ * It uses the
+ * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon plugin}.
+ */
+export default class LinkUI extends Plugin {
+    /**
+     * The actions view displayed inside of the balloon.
+     */
+    actionsView: LinkActionsView | null;
+    /**
+     * The form view displayed inside the balloon.
+     */
+    formView: LinkFormView & ViewWithCssTransitionDisabler | null;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ContextualBalloon];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LinkUI";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates views.
+     */
+    private _createViews;
+    /**
+     * Creates the {@link module:link/ui/linkactionsview~LinkActionsView} instance.
+     */
+    private _createActionsView;
+    /**
+     * Creates the {@link module:link/ui/linkformview~LinkFormView} instance.
+     */
+    private _createFormView;
+    /**
+     * Creates a toolbar Link button. Clicking this button will show
+     * a {@link #_balloon} attached to the selection.
+     */
+    private _createToolbarLinkButton;
+    /**
+     * Creates a button for link command to use either in toolbar or in menu bar.
+     */
+    private _createButton;
+    /**
+     * Attaches actions that control whether the balloon panel containing the
+     * {@link #formView} should be displayed.
+     */
+    private _enableBalloonActivators;
+    /**
+     * Attaches actions that control whether the balloon panel containing the
+     * {@link #formView} is visible or not.
+     */
+    private _enableUserBalloonInteractions;
+    /**
+     * Adds the {@link #actionsView} to the {@link #_balloon}.
+     *
+     * @internal
+     */
+    _addActionsView(): void;
+    /**
+     * Adds the {@link #formView} to the {@link #_balloon}.
+     */
+    private _addFormView;
+    /**
+     * Closes the form view. Decides whether the balloon should be hidden completely or if the action view should be shown. This is
+     * decided upon the link command value (which has a value if the document selection is in the link).
+     *
+     * Additionally, if any {@link module:link/linkconfig~LinkConfig#decorators} are defined in the editor configuration, the state of
+     * switch buttons responsible for manual decorator handling is restored.
+     */
+    private _closeFormView;
+    /**
+     * Removes the {@link #formView} from the {@link #_balloon}.
+     */
+    private _removeFormView;
+    /**
+     * Shows the correct UI type. It is either {@link #formView} or {@link #actionsView}.
+     *
+     * @internal
+     */
+    _showUI(forceVisible?: boolean): void;
+    /**
+     * Removes the {@link #formView} from the {@link #_balloon}.
+     *
+     * See {@link #_addFormView}, {@link #_addActionsView}.
+     */
+    private _hideUI;
+    /**
+     * Makes the UI react to the {@link module:ui/editorui/editorui~EditorUI#event:update} event to
+     * reposition itself when the editor UI should be refreshed.
+     *
+     * See: {@link #_hideUI} to learn when the UI stops reacting to the `update` event.
+     */
+    private _startUpdatingUI;
+    /**
+     * Returns `true` when {@link #formView} is in the {@link #_balloon}.
+     */
+    private get _isFormInPanel();
+    /**
+     * Returns `true` when {@link #actionsView} is in the {@link #_balloon}.
+     */
+    private get _areActionsInPanel();
+    /**
+     * Returns `true` when {@link #actionsView} is in the {@link #_balloon} and it is
+     * currently visible.
+     */
+    private get _areActionsVisible();
+    /**
+     * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon}.
+     */
+    private get _isUIInPanel();
+    /**
+     * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon} and it is
+     * currently visible.
+     */
+    private get _isUIVisible();
+    /**
+     * Returns positioning options for the {@link #_balloon}. They control the way the balloon is attached
+     * to the target element or selection.
+     *
+     * If the selection is collapsed and inside a link element, the panel will be attached to the
+     * entire link element. Otherwise, it will be attached to the selection.
+     */
+    private _getBalloonPositionData;
+    /**
+     * Returns the link {@link module:engine/view/attributeelement~AttributeElement} under
+     * the {@link module:engine/view/document~Document editing view's} selection or `null`
+     * if there is none.
+     *
+     * **Note**: For a non–collapsed selection, the link element is returned when **fully**
+     * selected and the **only** element within the selection boundaries, or when
+     * a linked widget is selected.
+     */
+    private _getSelectedLinkElement;
+    /**
+     * Displays a fake visual selection when the contextual balloon is displayed.
+     *
+     * This adds a 'link-ui' marker into the document that is rendered as a highlight on selected text fragment.
+     */
+    private _showFakeVisualSelection;
+    /**
+     * Hides the fake visual selection created in {@link #_showFakeVisualSelection}.
+     */
+    private _hideFakeVisualSelection;
+}