@ckeditor/ckeditor5-link 44.3.0-alpha.7 → 45.0.0-alpha.0

package/src/linkcommand.js

@@ -7,28 +7,26 @@
  */
 import { Command } from 'ckeditor5/src/core.js';
 import { findAttributeRange } from 'ckeditor5/src/typing.js';
-import { Collection, first, toMap } from 'ckeditor5/src/utils.js';
+import { Collection, diff, first, toMap } from 'ckeditor5/src/utils.js';
+import { LivePosition } from 'ckeditor5/src/engine.js';
 import AutomaticDecorators from './utils/automaticdecorators.js';
-import { isLinkableElement } from './utils.js';
+import { extractTextFromLinkRange, isLinkableElement } from './utils.js';
 /**
  * The link command. It is used by the {@link module:link/link~Link link feature}.
  */
 export default class LinkCommand extends Command {
-    constructor() {
-        super(...arguments);
-        /**
-         * A collection of {@link module:link/utils/manualdecorator~ManualDecorator manual decorators}
-         * corresponding to the {@link module:link/linkconfig~LinkConfig#decorators decorator configuration}.
-         *
-         * You can consider it a model with states of manual decorators added to the currently selected link.
-         */
-        this.manualDecorators = new Collection();
-        /**
-         * An instance of the helper that ties together all {@link module:link/linkconfig~LinkDecoratorAutomaticDefinition}
-         * that are used by the {@glink features/link link} and the {@glink features/images/images-linking linking images} features.
-         */
-        this.automaticDecorators = new AutomaticDecorators();
-    }
+    /**
+     * A collection of {@link module:link/utils/manualdecorator~ManualDecorator manual decorators}
+     * corresponding to the {@link module:link/linkconfig~LinkConfig#decorators decorator configuration}.
+     *
+     * You can consider it a model with states of manual decorators added to the currently selected link.
+     */
+    manualDecorators = new Collection();
+    /**
+     * An instance of the helper that ties together all {@link module:link/linkconfig~LinkDecoratorAutomaticDefinition}
+     * that are used by the {@glink features/link link} and the {@glink features/images/images-linking linking images} features.
+     */
+    automaticDecorators = new AutomaticDecorators();
     /**
      * Synchronizes the state of {@link #manualDecorators} with the currently present elements in the model.
      */
@@ -119,11 +117,27 @@ export default class LinkCommand extends Command {
      * **Note**: {@link module:link/unlinkcommand~UnlinkCommand#execute `UnlinkCommand#execute()`} removes all
      * decorator attributes.
      *
+     * An optional parameter called `displayedText` is to add or update text of the link that represents the `href`. For example:
+     *
+     * ```ts
+     * const linkCommand = editor.commands.get( 'link' );
+     *
+     * // Adding a new link with `displayedText` attribute.
+     * linkCommand.execute( 'http://example.com', {}, 'Example' );
+     * ```
+     *
+     * The above code will create an anchor like this:
+     *
+     * ```html
+     * <a href="http://example.com">Example</a>
+     * ```
+     *
      * @fires execute
      * @param href Link destination.
      * @param manualDecoratorIds The information about manual decorator attributes to be applied or removed upon execution.
+     * @param displayedText Text of the link.
      */
-    execute(href, manualDecoratorIds = {}) {
+    execute(href, manualDecoratorIds = {}, displayedText) {
         const model = this.editor.model;
         const selection = model.document.selection;
         // Stores information about manual decorators to turn them on/off when command is applied.
@@ -138,26 +152,82 @@ export default class LinkCommand extends Command {
             }
         }
         model.change(writer => {
+            const updateLinkAttributes = (itemOrRange) => {
+                writer.setAttribute('linkHref', href, itemOrRange);
+                truthyManualDecorators.forEach(item => writer.setAttribute(item, true, itemOrRange));
+                falsyManualDecorators.forEach(item => writer.removeAttribute(item, itemOrRange));
+            };
+            const updateLinkTextIfNeeded = (range, linkHref) => {
+                const linkText = extractTextFromLinkRange(range);
+                if (!linkText) {
+                    return range;
+                }
+                // Make a copy not to override the command param value.
+                let newText = displayedText;
+                if (!newText) {
+                    // Replace the link text with the new href if previously href was equal to text.
+                    // For example: `<a href="http://ckeditor.com/">http://ckeditor.com/</a>`.
+                    newText = linkHref && linkHref == linkText ? href : linkText;
+                }
+                // Only if needed.
+                if (newText != linkText) {
+                    const changes = findChanges(linkText, newText);
+                    let insertsLength = 0;
+                    for (const { offset, actual, expected } of changes) {
+                        const updatedOffset = offset + insertsLength;
+                        const subRange = writer.createRange(range.start.getShiftedBy(updatedOffset), range.start.getShiftedBy(updatedOffset + actual.length));
+                        // Collect formatting attributes from replaced text.
+                        const textNode = getLinkPartTextNode(subRange, range);
+                        const attributes = textNode.getAttributes();
+                        const formattingAttributes = Array
+                            .from(attributes)
+                            .filter(([key]) => model.schema.getAttributeProperties(key).isFormatting);
+                        // Create a new text node.
+                        const newTextNode = writer.createText(expected, formattingAttributes);
+                        // Set link attributes before inserting to document to avoid Differ attributes edge case.
+                        updateLinkAttributes(newTextNode);
+                        // Replace text with formatting.
+                        model.insertContent(newTextNode, subRange);
+                        // Sum of all previous inserts.
+                        insertsLength += expected.length;
+                    }
+                    return writer.createRange(range.start, range.start.getShiftedBy(newText.length));
+                }
+            };
+            const collapseSelectionAtLinkEnd = (linkRange) => {
+                const { plugins } = this.editor;
+                writer.setSelection(linkRange.end);
+                if (plugins.has('TwoStepCaretMovement')) {
+                    // After replacing the text of the link, we need to move the caret to the end of the link,
+                    // override it's gravity to forward to prevent keeping e.g. bold attribute on the caret
+                    // which was previously inside the link.
+                    //
+                    // If the plugin is not available, the caret will be placed at the end of the link and the
+                    // bold attribute will be kept even if command moved caret outside the link.
+                    plugins.get('TwoStepCaretMovement')._handleForwardMovement();
+                }
+                else {
+                    // Remove the `linkHref` attribute and all link decorators from the selection.
+                    // It stops adding a new content into the link element.
+                    for (const key of ['linkHref', ...truthyManualDecorators, ...falsyManualDecorators]) {
+                        writer.removeSelectionAttribute(key);
+                    }
+                }
+            };
             // If selection is collapsed then update selected link or insert new one at the place of caret.
             if (selection.isCollapsed) {
                 const position = selection.getFirstPosition();
                 // When selection is inside text with `linkHref` attribute.
                 if (selection.hasAttribute('linkHref')) {
-                    const linkText = extractTextFromSelection(selection);
-                    // Then update `linkHref` value.
-                    let linkRange = findAttributeRange(position, 'linkHref', selection.getAttribute('linkHref'), model);
-                    if (selection.getAttribute('linkHref') === linkText) {
-                        linkRange = this._updateLinkContent(model, writer, linkRange, href);
+                    const linkHref = selection.getAttribute('linkHref');
+                    const linkRange = findAttributeRange(position, 'linkHref', linkHref, model);
+                    const newLinkRange = updateLinkTextIfNeeded(linkRange, linkHref);
+                    updateLinkAttributes(newLinkRange || linkRange);
+                    // Put the selection at the end of the updated link only when text was changed.
+                    // When text was not altered we keep the original selection.
+                    if (newLinkRange) {
+                        collapseSelectionAtLinkEnd(newLinkRange);
                     }
-                    writer.setAttribute('linkHref', href, linkRange);
-                    truthyManualDecorators.forEach(item => {
-                        writer.setAttribute(item, true, linkRange);
-                    });
-                    falsyManualDecorators.forEach(item => {
-                        writer.removeAttribute(item, linkRange);
-                    });
-                    // Put the selection at the end of the updated link.
-                    writer.setSelection(writer.createPositionAfter(linkRange.end.nodeBefore));
                 }
                 // If not then insert text node with `linkHref` attribute in place of caret.
                 // However, since selection is collapsed, attribute value will be used as data for text node.
@@ -168,21 +238,18 @@ export default class LinkCommand extends Command {
                     truthyManualDecorators.forEach(item => {
                         attributes.set(item, true);
                     });
-                    const { end: positionAfter } = model.insertContent(writer.createText(href, attributes), position);
+                    const newLinkRange = model.insertContent(writer.createText(displayedText || href, attributes), position);
                     // Put the selection at the end of the inserted link.
                     // Using end of range returned from insertContent in case nodes with the same attributes got merged.
-                    writer.setSelection(positionAfter);
+                    collapseSelectionAtLinkEnd(newLinkRange);
                 }
-                // Remove the `linkHref` attribute and all link decorators from the selection.
-                // It stops adding a new content into the link element.
-                ['linkHref', ...truthyManualDecorators, ...falsyManualDecorators].forEach(item => {
-                    writer.removeSelectionAttribute(item);
-                });
             }
             else {
+                // Non-collapsed selection.
                 // If selection has non-collapsed ranges, we change attribute on nodes inside those ranges
                 // omitting nodes where the `linkHref` attribute is disallowed.
-                const ranges = model.schema.getValidRanges(selection.getRanges(), 'linkHref');
+                const selectionRanges = Array.from(selection.getRanges());
+                const ranges = model.schema.getValidRanges(selectionRanges, 'linkHref');
                 // But for the first, check whether the `linkHref` attribute is allowed on selected blocks (e.g. the "image" element).
                 const allowedRanges = [];
                 for (const element of selection.getSelectedBlocks()) {
@@ -199,24 +266,25 @@ export default class LinkCommand extends Command {
                         rangesToUpdate.push(range);
                     }
                 }
-                for (const range of rangesToUpdate) {
-                    let linkRange = range;
-                    if (rangesToUpdate.length === 1) {
-                        // Current text of the link in the document.
-                        const linkText = extractTextFromSelection(selection);
-                        if (selection.getAttribute('linkHref') === linkText) {
-                            linkRange = this._updateLinkContent(model, writer, range, href);
-                            writer.setSelection(writer.createSelection(linkRange));
-                        }
-                    }
-                    writer.setAttribute('linkHref', href, linkRange);
-                    truthyManualDecorators.forEach(item => {
-                        writer.setAttribute(item, true, linkRange);
-                    });
-                    falsyManualDecorators.forEach(item => {
-                        writer.removeAttribute(item, linkRange);
-                    });
+                // Store the selection ranges in a pseudo live range array (stickiness to the outside of the range).
+                const stickyPseudoRanges = selectionRanges.map(range => ({
+                    start: LivePosition.fromPosition(range.start, 'toPrevious'),
+                    end: LivePosition.fromPosition(range.end, 'toNext')
+                }));
+                // Update or set links (including text update if needed).
+                for (let range of rangesToUpdate) {
+                    const linkHref = (range.start.textNode || range.start.nodeAfter).getAttribute('linkHref');
+                    range = updateLinkTextIfNeeded(range, linkHref) || range;
+                    updateLinkAttributes(range);
                 }
+                // The original selection got trimmed by replacing content so we need to restore it.
+                writer.setSelection(stickyPseudoRanges.map(pseudoRange => {
+                    const start = pseudoRange.start.toPosition();
+                    const end = pseudoRange.end.toPosition();
+                    pseudoRange.start.detach();
+                    pseudoRange.end.detach();
+                    return model.createRange(start, end);
+                }));
             }
         });
     }
@@ -252,34 +320,96 @@ export default class LinkCommand extends Command {
         }
         return true;
     }
-    /**
-     * Updates selected link with a new value as its content and as its href attribute.
-     *
-     * @param model Model is need to insert content.
-     * @param writer Writer is need to create text element in model.
-     * @param range A range where should be inserted content.
-     * @param href A link value which should be in the href attribute and in the content.
-     */
-    _updateLinkContent(model, writer, range, href) {
-        const text = writer.createText(href, { linkHref: href });
-        return model.insertContent(text, range);
+}
+/**
+ * Compares two strings and returns an array of changes needed to transform one into another.
+ * Uses the diff utility to find the differences and groups them into chunks containing information
+ * about the offset and actual/expected content.
+ *
+ * @param oldText The original text to compare.
+ * @param newText The new text to compare against.
+ * @returns Array of change objects containing offset and actual/expected content.
+ *
+ * @example
+ * findChanges( 'hello world', 'hi there' );
+ *
+ * Returns:
+ * [
+ * 	{
+ * 		"offset": 1,
+ * 		"actual": "ello",
+ * 		"expected": "i"
+ * 	},
+ * 	{
+ * 		"offset": 2,
+ * 		"actual": "wo",
+ * 		"expected": "the"
+ * 	},
+ * 	{
+ * 		"offset": 3,
+ * 		"actual": "ld",
+ * 		"expected": "e"
+ * 	}
+ * ]
+ */
+function findChanges(oldText, newText) {
+    // Get array of operations (insert/delete/equal) needed to transform oldText into newText.
+    // Example: diff('abc', 'abxc') returns ['equal', 'equal', 'insert', 'equal']
+    const changes = diff(oldText, newText);
+    // Track position in both strings based on operation type.
+    const counter = { equal: 0, insert: 0, delete: 0 };
+    const result = [];
+    // Accumulate consecutive changes into slices before creating change objects.
+    let actualSlice = '';
+    let expectedSlice = '';
+    // Adding null as sentinel value to handle final accumulated changes.
+    for (const action of [...changes, null]) {
+        if (action == 'insert') {
+            // Example: for 'abc' -> 'abxc', at insert position, adds 'x' to expectedSlice.
+            expectedSlice += newText[counter.equal + counter.insert];
+        }
+        else if (action == 'delete') {
+            // Example: for 'abc' -> 'ac', at delete position, adds 'b' to actualSlice.
+            actualSlice += oldText[counter.equal + counter.delete];
+        }
+        else if (actualSlice.length || expectedSlice.length) {
+            // On 'equal' or end: bundle accumulated changes into a single change object.
+            // Example: { offset: 2, actual: "", expected: "x" }
+            result.push({
+                offset: counter.equal,
+                actual: actualSlice,
+                expected: expectedSlice
+            });
+            actualSlice = '';
+            expectedSlice = '';
+        }
+        // Increment appropriate counter for the current operation.
+        if (action) {
+            counter[action]++;
+        }
     }
+    return result;
 }
-// Returns a text of a link under the collapsed selection or a selection that contains the entire link.
-function extractTextFromSelection(selection) {
-    if (selection.isCollapsed) {
-        const firstPosition = selection.getFirstPosition();
-        return firstPosition.textNode && firstPosition.textNode.data;
+/**
+ * Returns text node withing the link range that should be updated.
+ *
+ * @param range Partial link range.
+ * @param linkRange Range of the entire link.
+ * @returns Text node.
+ */
+function getLinkPartTextNode(range, linkRange) {
+    if (!range.isCollapsed) {
+        return first(range.getItems());
+    }
+    const position = range.start;
+    if (position.textNode) {
+        return position.textNode;
+    }
+    // If the range is at the start of a link range then prefer node inside a link range.
+    if (!position.nodeBefore || position.isEqual(linkRange.start)) {
+        return position.nodeAfter;
     }
     else {
-        const rangeItems = Array.from(selection.getFirstRange().getItems());
-        if (rangeItems.length > 1) {
-            return null;
-        }
-        const firstNode = rangeItems[0];
-        if (firstNode.is('$text') || firstNode.is('$textProxy')) {
-            return firstNode.data;
-        }
-        return null;
+        return position.nodeBefore;
     }
 }

package/src/linkconfig.d.ts

@@ -172,6 +172,34 @@ export interface LinkConfig {
      * See also the {@glink features/link#custom-link-attributes-decorators link feature guide} for more information.
      */
     decorators?: Record<string, LinkDecoratorDefinition>;
+    /**
+     * Items to be placed in the link contextual toolbar.
+     *
+     * Assuming that you use the {@link module:link/linkui~LinkUI} feature, the following toolbar items will be available
+     * in {@link module:ui/componentfactory~ComponentFactory}:
+     *
+     * * `'linkPreview'`,
+     * * `'editLink'`,
+     * * `'linkProperties'`
+     * * `'unlink'`.
+     *
+     * The default configuration for link toolbar is:
+     *
+     * ```ts
+     * const linkConfig = {
+     * 	toolbar: [ 'linkPreview', '|', 'editLink', 'linkProperties', 'unlink' ]
+     * };
+     * ```
+     *
+     * The `linkProperties` toolbar item is only available when at least one manual decorator is defined in the
+     * {@link module:link/linkconfig~LinkConfig#decorators decorators configuration}.
+     *
+     * Of course, the same buttons can also be used in the
+     * {@link module:core/editor/editorconfig~EditorConfig#toolbar main editor toolbar}.
+     *
+     * Read more about configuring the toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
+     */
+    toolbar?: Array<string>;
 }
 /**
  * A link decorator definition. Two types implement this definition:

package/src/linkediting.d.ts

@@ -16,6 +16,10 @@ import '../theme/link.css';
  * as well as `'link'` and `'unlink'` commands.
  */
 export default class LinkEditing extends Plugin {
+    /**
+     * A list of functions that handles opening links. If any of them returns `true`, the link is considered to be opened.
+     */
+    private readonly _linkOpeners;
     /**
      * @inheritDoc
      */
@@ -36,6 +40,13 @@ export default class LinkEditing extends Plugin {
      * @inheritDoc
      */
     init(): void;
+    /**
+     * Registers a function that opens links in a new browser tab.
+     *
+     * @param linkOpener The function that opens a link in a new browser tab.
+     * @internal
+     */
+    _registerLinkOpener(linkOpener: LinkOpener): void;
     /**
      * Processes an array of configured {@link module:link/linkconfig~LinkDecoratorAutomaticDefinition automatic decorators}
      * and registers a {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher downcast dispatcher}
@@ -72,3 +83,10 @@ export default class LinkEditing extends Plugin {
      */
     private _enableClipboardIntegration;
 }
+/**
+ * A function that handles opening links. It may be used to define custom link handlers.
+ *
+ * @returns `true` if the link was opened successfully.
+ */
+type LinkOpener = (url: string) => boolean;
+export {};

package/src/linkediting.js

@@ -12,7 +12,7 @@ import { keyCodes, env } from 'ckeditor5/src/utils.js';
 import LinkCommand from './linkcommand.js';
 import UnlinkCommand from './unlinkcommand.js';
 import ManualDecorator from './utils/manualdecorator.js';
-import { createLinkElement, ensureSafeUrl, getLocalizedDecorators, normalizeDecorators, addLinkProtocolIfApplicable, createBookmarkCallbacks, openLink } from './utils.js';
+import { createLinkElement, ensureSafeUrl, getLocalizedDecorators, normalizeDecorators, addLinkProtocolIfApplicable, openLink } from './utils.js';
 import '../theme/link.css';
 const HIGHLIGHT_CLASS = 'ck-link_selected';
 const DECORATOR_AUTOMATIC = 'automatic';
@@ -25,6 +25,10 @@ const EXTERNAL_LINKS_REGEXP = /^(https?:)?\/\//;
  * as well as `'link'` and `'unlink'` commands.
  */
 export default class LinkEditing extends Plugin {
+    /**
+     * A list of functions that handles opening links. If any of them returns `true`, the link is considered to be opened.
+     */
+    _linkOpeners = [];
     /**
      * @inheritDoc
      */
@@ -51,7 +55,8 @@ export default class LinkEditing extends Plugin {
         super(editor);
         editor.config.define('link', {
             allowCreatingEmptyLinks: false,
-            addTargetToExternalLinks: false
+            addTargetToExternalLinks: false,
+            toolbar: ['linkPreview', '|', 'editLink', 'linkProperties', 'unlink']
         });
     }
     /**
@@ -101,6 +106,15 @@ export default class LinkEditing extends Plugin {
         // Handle adding default protocol to pasted links.
         this._enableClipboardIntegration();
     }
+    /**
+     * Registers a function that opens links in a new browser tab.
+     *
+     * @param linkOpener The function that opens a link in a new browser tab.
+     * @internal
+     */
+    _registerLinkOpener(linkOpener) {
+        this._linkOpeners.push(linkOpener);
+    }
     /**
      * Processes an array of configured {@link module:link/linkconfig~LinkDecoratorAutomaticDefinition automatic decorators}
      * and registers a {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher downcast dispatcher}
@@ -193,15 +207,11 @@ export default class LinkEditing extends Plugin {
         const editor = this.editor;
         const view = editor.editing.view;
         const viewDocument = view.document;
-        const bookmarkCallbacks = createBookmarkCallbacks(editor);
-        function handleLinkOpening(url) {
-            if (bookmarkCallbacks.isScrollableToTarget(url)) {
-                bookmarkCallbacks.scrollToTarget(url);
-            }
-            else {
+        const handleLinkOpening = (url) => {
+            if (!this._linkOpeners.some(opener => opener(url))) {
                 openLink(url);
             }
-        }
+        };
         this.listenTo(viewDocument, 'click', (evt, data) => {
             const shouldOpen = env.isMac ? data.domEvent.metaKey : data.domEvent.ctrlKey;
             if (!shouldOpen) {

package/src/linkimageui.d.ts

@@ -32,7 +32,7 @@ export default class LinkImageUI extends Plugin {
      * 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
+     * When an image is already linked, the view shows {@link module:link/linkui~LinkUI#toolbarView} or
      * {@link module:link/linkui~LinkUI#formView} if it is not.
      */
     private _createToolbarLinkImageButton;

package/src/linkimageui.js

@@ -7,10 +7,10 @@
  */
 import { ButtonView } from 'ckeditor5/src/ui.js';
 import { Plugin } from 'ckeditor5/src/core.js';
+import { IconLink } from 'ckeditor5/src/icons.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.
  *
@@ -57,7 +57,7 @@ export default class LinkImageUI extends Plugin {
      * 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
+     * When an image is already linked, the view shows {@link module:link/linkui~LinkUI#toolbarView} or
      * {@link module:link/linkui~LinkUI#formView} if it is not.
      */
     _createToolbarLinkImageButton() {
@@ -70,7 +70,7 @@ export default class LinkImageUI extends Plugin {
             button.set({
                 isEnabled: true,
                 label: t('Link image'),
-                icon: linkIcon,
+                icon: IconLink,
                 keystroke: LINK_KEYSTROKE,
                 tooltip: true,
                 isToggleable: true
@@ -81,7 +81,7 @@ export default class LinkImageUI extends Plugin {
             // 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();
+                    plugin._addToolbarView();
                 }
                 else {
                     plugin._showUI(true);