@ckeditor/ckeditor5-link 36.0.0 → 37.0.0-alpha.0

package/src/unlinkcommand.js

@@ -2,79 +2,65 @@
  * @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 link/unlinkcommand
  */
-
 import { Command } from 'ckeditor5/src/core';
 import { findAttributeRange } from 'ckeditor5/src/typing';
-
 import { isLinkableElement } from './utils';
-
 /**
  * The unlink command. It is used by the {@link module:link/link~Link link plugin}.
- *
- * @extends module:core/command~Command
  */
 export default class UnlinkCommand extends Command {
-	/**
-	 * @inheritDoc
-	 */
-	refresh() {
-		const model = this.editor.model;
-		const selection = model.document.selection;
-		const selectedElement = selection.getSelectedElement();
-
-		// A check for any integration that allows linking elements (e.g. `LinkImage`).
-		// Currently the selection reads attributes from text nodes only. See #7429 and #7465.
-		if ( isLinkableElement( selectedElement, model.schema ) ) {
-			this.isEnabled = model.schema.checkAttribute( selectedElement, 'linkHref' );
-		} else {
-			this.isEnabled = model.schema.checkAttributeInSelection( selection, 'linkHref' );
-		}
-	}
-
-	/**
-	 * Executes the command.
-	 *
-	 * When the selection is collapsed, it removes the `linkHref` attribute from each node with the same `linkHref` attribute value.
-	 * When the selection is non-collapsed, it removes the `linkHref` attribute from each node in selected ranges.
-	 *
-	 * # Decorators
-	 *
-	 * If {@link module:link/link~LinkConfig#decorators `config.link.decorators`} is specified,
-	 * all configured decorators are removed together with the `linkHref` attribute.
-	 *
-	 * @fires execute
-	 */
-	execute() {
-		const editor = this.editor;
-		const model = this.editor.model;
-		const selection = model.document.selection;
-		const linkCommand = editor.commands.get( 'link' );
-
-		model.change( writer => {
-			// Get ranges to unlink.
-			const rangesToUnlink = selection.isCollapsed ?
-				[ findAttributeRange(
-					selection.getFirstPosition(),
-					'linkHref',
-					selection.getAttribute( 'linkHref' ),
-					model
-				) ] :
-				model.schema.getValidRanges( selection.getRanges(), 'linkHref' );
-
-			// Remove `linkHref` attribute from specified ranges.
-			for ( const range of rangesToUnlink ) {
-				writer.removeAttribute( 'linkHref', range );
-				// If there are registered custom attributes, then remove them during unlink.
-				if ( linkCommand ) {
-					for ( const manualDecorator of linkCommand.manualDecorators ) {
-						writer.removeAttribute( manualDecorator.id, range );
-					}
-				}
-			}
-		} );
-	}
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const model = this.editor.model;
+        const selection = model.document.selection;
+        const selectedElement = selection.getSelectedElement();
+        // A check for any integration that allows linking elements (e.g. `LinkImage`).
+        // Currently the selection reads attributes from text nodes only. See #7429 and #7465.
+        if (isLinkableElement(selectedElement, model.schema)) {
+            this.isEnabled = model.schema.checkAttribute(selectedElement, 'linkHref');
+        }
+        else {
+            this.isEnabled = model.schema.checkAttributeInSelection(selection, 'linkHref');
+        }
+    }
+    /**
+     * Executes the command.
+     *
+     * When the selection is collapsed, it removes the `linkHref` attribute from each node with the same `linkHref` attribute value.
+     * When the selection is non-collapsed, it removes the `linkHref` attribute from each node in selected ranges.
+     *
+     * # Decorators
+     *
+     * If {@link module:link/link~LinkConfig#decorators `config.link.decorators`} is specified,
+     * all configured decorators are removed together with the `linkHref` attribute.
+     *
+     * @fires execute
+     */
+    execute() {
+        const editor = this.editor;
+        const model = this.editor.model;
+        const selection = model.document.selection;
+        const linkCommand = editor.commands.get('link');
+        model.change(writer => {
+            // Get ranges to unlink.
+            const rangesToUnlink = selection.isCollapsed ?
+                [findAttributeRange(selection.getFirstPosition(), 'linkHref', selection.getAttribute('linkHref'), model)] :
+                model.schema.getValidRanges(selection.getRanges(), 'linkHref');
+            // Remove `linkHref` attribute from specified ranges.
+            for (const range of rangesToUnlink) {
+                writer.removeAttribute('linkHref', range);
+                // If there are registered custom attributes, then remove them during unlink.
+                if (linkCommand) {
+                    for (const manualDecorator of linkCommand.manualDecorators) {
+                        writer.removeAttribute(manualDecorator.id, range);
+                    }
+                }
+            }
+        });
+    }
 }

package/src/utils/automaticdecorators.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @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 link/utils/automaticdecorators
+ */
+import { type ArrayOrItem } from 'ckeditor5/src/utils';
+import type { DowncastDispatcher } from 'ckeditor5/src/engine';
+import type { NormalizedLinkDecoratorAutomaticDefinition } from '../utils';
+/**
+ * Helper class that ties together all {@link module:link/link~LinkDecoratorAutomaticDefinition} and provides
+ * the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement downcast dispatchers} for them.
+ */
+export default class AutomaticDecorators {
+    /**
+     * Stores the definition of {@link module:link/link~LinkDecoratorAutomaticDefinition automatic decorators}.
+     * This data is used as a source for a downcast dispatcher to create a proper conversion to output data.
+     */
+    private _definitions;
+    /**
+     * Gives information about the number of decorators stored in the {@link module:link/utils~AutomaticDecorators} instance.
+     */
+    get length(): number;
+    /**
+     * Adds automatic decorator objects or an array with them to be used during downcasting.
+     *
+     * @param item A configuration object of automatic rules for decorating links. It might also be an array of such objects.
+     */
+    add(item: ArrayOrItem<NormalizedLinkDecoratorAutomaticDefinition>): void;
+    /**
+     * Provides the conversion helper used in the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method.
+     *
+     * @returns A dispatcher function used as conversion helper in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}.
+     */
+    getDispatcher(): (dispatcher: DowncastDispatcher) => void;
+    /**
+     * Provides the conversion helper used in the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method
+     * when linking images.
+     *
+     * @returns A dispatcher function used as conversion helper in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}.
+     */
+    getDispatcherForLinkedImage(): (dispatcher: DowncastDispatcher) => void;
+}

package/src/utils/automaticdecorators.js

@@ -2,160 +2,138 @@
  * @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 link/utils
+ * @module link/utils/automaticdecorators
  */
-
 import { toMap } from 'ckeditor5/src/utils';
-
 /**
  * Helper class that ties together all {@link module:link/link~LinkDecoratorAutomaticDefinition} and provides
  * the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement downcast dispatchers} for them.
  */
 export default class AutomaticDecorators {
-	constructor() {
-		/**
-		 * Stores the definition of {@link module:link/link~LinkDecoratorAutomaticDefinition automatic decorators}.
-		 * This data is used as a source for a downcast dispatcher to create a proper conversion to output data.
-		 *
-		 * @private
-		 * @type {Set}
-		 */
-		this._definitions = new Set();
-	}
-
-	/**
-	 * Gives information about the number of decorators stored in the {@link module:link/utils~AutomaticDecorators} instance.
-	 *
-	 * @readonly
-	 * @protected
-	 * @type {Number}
-	 */
-	get length() {
-		return this._definitions.size;
-	}
-
-	/**
-	 * Adds automatic decorator objects or an array with them to be used during downcasting.
-	 *
-	 * @param {module:link/link~LinkDecoratorAutomaticDefinition|Array.<module:link/link~LinkDecoratorAutomaticDefinition>} item
-	 * A configuration object of automatic rules for decorating links. It might also be an array of such objects.
-	 */
-	add( item ) {
-		if ( Array.isArray( item ) ) {
-			item.forEach( item => this._definitions.add( item ) );
-		} else {
-			this._definitions.add( item );
-		}
-	}
-
-	/**
-	 * Provides the conversion helper used in the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method.
-	 *
-	 * @returns {Function} A dispatcher function used as conversion helper
-	 * in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}.
-	 */
-	getDispatcher() {
-		return dispatcher => {
-			dispatcher.on( 'attribute:linkHref', ( evt, data, conversionApi ) => {
-				// There is only test as this behavior decorates links and
-				// it is run before dispatcher which actually consumes this node.
-				// This allows on writing own dispatcher with highest priority,
-				// which blocks both native converter and this additional decoration.
-				if ( !conversionApi.consumable.test( data.item, 'attribute:linkHref' ) ) {
-					return;
-				}
-
-				// Automatic decorators for block links are handled e.g. in LinkImageEditing.
-				if ( !( data.item.is( 'selection' ) || conversionApi.schema.isInline( data.item ) ) ) {
-					return;
-				}
-
-				const viewWriter = conversionApi.writer;
-				const viewSelection = viewWriter.document.selection;
-
-				for ( const item of this._definitions ) {
-					const viewElement = viewWriter.createAttributeElement( 'a', item.attributes, {
-						priority: 5
-					} );
-
-					if ( item.classes ) {
-						viewWriter.addClass( item.classes, viewElement );
-					}
-
-					for ( const key in item.styles ) {
-						viewWriter.setStyle( key, item.styles[ key ], viewElement );
-					}
-
-					viewWriter.setCustomProperty( 'link', true, viewElement );
-					if ( item.callback( data.attributeNewValue ) ) {
-						if ( data.item.is( 'selection' ) ) {
-							viewWriter.wrap( viewSelection.getFirstRange(), viewElement );
-						} else {
-							viewWriter.wrap( conversionApi.mapper.toViewRange( data.range ), viewElement );
-						}
-					} else {
-						viewWriter.unwrap( conversionApi.mapper.toViewRange( data.range ), viewElement );
-					}
-				}
-			}, { priority: 'high' } );
-		};
-	}
-
-	/**
-	 * Provides the conversion helper used in the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method
-	 * when linking images.
-	 *
-	 * @returns {Function} A dispatcher function used as conversion helper
-	 * in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}.
-	 */
-	getDispatcherForLinkedImage() {
-		return dispatcher => {
-			dispatcher.on( 'attribute:linkHref:imageBlock', ( evt, data, { writer, mapper } ) => {
-				const viewFigure = mapper.toViewElement( data.item );
-				const linkInImage = Array.from( viewFigure.getChildren() ).find( child => child.name === 'a' );
-
-				for ( const item of this._definitions ) {
-					const attributes = toMap( item.attributes );
-
-					if ( item.callback( data.attributeNewValue ) ) {
-						for ( const [ key, val ] of attributes ) {
-							// Left for backward compatibility. Since v30 decorator should
-							// accept `classes` and `styles` separately from `attributes`.
-							if ( key === 'class' ) {
-								writer.addClass( val, linkInImage );
-							} else {
-								writer.setAttribute( key, val, linkInImage );
-							}
-						}
-
-						if ( item.classes ) {
-							writer.addClass( item.classes, linkInImage );
-						}
-
-						for ( const key in item.styles ) {
-							writer.setStyle( key, item.styles[ key ], linkInImage );
-						}
-					} else {
-						for ( const [ key, val ] of attributes ) {
-							if ( key === 'class' ) {
-								writer.removeClass( val, linkInImage );
-							} else {
-								writer.removeAttribute( key, linkInImage );
-							}
-						}
-
-						if ( item.classes ) {
-							writer.removeClass( item.classes, linkInImage );
-						}
-
-						for ( const key in item.styles ) {
-							writer.removeStyle( key, linkInImage );
-						}
-					}
-				}
-			} );
-		};
-	}
+    constructor() {
+        /**
+         * Stores the definition of {@link module:link/link~LinkDecoratorAutomaticDefinition automatic decorators}.
+         * This data is used as a source for a downcast dispatcher to create a proper conversion to output data.
+         */
+        this._definitions = new Set();
+    }
+    /**
+     * Gives information about the number of decorators stored in the {@link module:link/utils~AutomaticDecorators} instance.
+     */
+    get length() {
+        return this._definitions.size;
+    }
+    /**
+     * Adds automatic decorator objects or an array with them to be used during downcasting.
+     *
+     * @param item A configuration object of automatic rules for decorating links. It might also be an array of such objects.
+     */
+    add(item) {
+        if (Array.isArray(item)) {
+            item.forEach(item => this._definitions.add(item));
+        }
+        else {
+            this._definitions.add(item);
+        }
+    }
+    /**
+     * Provides the conversion helper used in the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method.
+     *
+     * @returns A dispatcher function used as conversion helper in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}.
+     */
+    getDispatcher() {
+        return dispatcher => {
+            dispatcher.on('attribute:linkHref', (evt, data, conversionApi) => {
+                // There is only test as this behavior decorates links and
+                // it is run before dispatcher which actually consumes this node.
+                // This allows on writing own dispatcher with highest priority,
+                // which blocks both native converter and this additional decoration.
+                if (!conversionApi.consumable.test(data.item, 'attribute:linkHref')) {
+                    return;
+                }
+                // Automatic decorators for block links are handled e.g. in LinkImageEditing.
+                if (!(data.item.is('selection') || conversionApi.schema.isInline(data.item))) {
+                    return;
+                }
+                const viewWriter = conversionApi.writer;
+                const viewSelection = viewWriter.document.selection;
+                for (const item of this._definitions) {
+                    const viewElement = viewWriter.createAttributeElement('a', item.attributes, {
+                        priority: 5
+                    });
+                    if (item.classes) {
+                        viewWriter.addClass(item.classes, viewElement);
+                    }
+                    for (const key in item.styles) {
+                        viewWriter.setStyle(key, item.styles[key], viewElement);
+                    }
+                    viewWriter.setCustomProperty('link', true, viewElement);
+                    if (item.callback(data.attributeNewValue)) {
+                        if (data.item.is('selection')) {
+                            viewWriter.wrap(viewSelection.getFirstRange(), viewElement);
+                        }
+                        else {
+                            viewWriter.wrap(conversionApi.mapper.toViewRange(data.range), viewElement);
+                        }
+                    }
+                    else {
+                        viewWriter.unwrap(conversionApi.mapper.toViewRange(data.range), viewElement);
+                    }
+                }
+            }, { priority: 'high' });
+        };
+    }
+    /**
+     * Provides the conversion helper used in the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method
+     * when linking images.
+     *
+     * @returns A dispatcher function used as conversion helper in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}.
+     */
+    getDispatcherForLinkedImage() {
+        return dispatcher => {
+            dispatcher.on('attribute:linkHref:imageBlock', (evt, data, { writer, mapper }) => {
+                const viewFigure = mapper.toViewElement(data.item);
+                const linkInImage = Array.from(viewFigure.getChildren())
+                    .find((child) => child.is('element', 'a'));
+                for (const item of this._definitions) {
+                    const attributes = toMap(item.attributes);
+                    if (item.callback(data.attributeNewValue)) {
+                        for (const [key, val] of attributes) {
+                            // Left for backward compatibility. Since v30 decorator should
+                            // accept `classes` and `styles` separately from `attributes`.
+                            if (key === 'class') {
+                                writer.addClass(val, linkInImage);
+                            }
+                            else {
+                                writer.setAttribute(key, val, linkInImage);
+                            }
+                        }
+                        if (item.classes) {
+                            writer.addClass(item.classes, linkInImage);
+                        }
+                        for (const key in item.styles) {
+                            writer.setStyle(key, item.styles[key], linkInImage);
+                        }
+                    }
+                    else {
+                        for (const [key, val] of attributes) {
+                            if (key === 'class') {
+                                writer.removeClass(val, linkInImage);
+                            }
+                            else {
+                                writer.removeAttribute(key, linkInImage);
+                            }
+                        }
+                        if (item.classes) {
+                            writer.removeClass(item.classes, linkInImage);
+                        }
+                        for (const key in item.styles) {
+                            writer.removeStyle(key, linkInImage);
+                        }
+                    }
+                }
+            });
+        };
+    }
 }

package/src/utils/manualdecorator.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @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 link/utils/manualdecorator
+ */
+import { type ArrayOrItem } from 'ckeditor5/src/utils';
+import type { MatcherObjectPattern } from 'ckeditor5/src/engine';
+import type { NormalizedLinkDecoratorManualDefinition } from '../utils';
+declare const ManualDecorator_base: {
+    new (): import("ckeditor5/src/utils").Observable;
+    prototype: import("ckeditor5/src/utils").Observable;
+};
+/**
+ * Helper class that stores manual decorators with observable {@link module:link/utils~ManualDecorator#value}
+ * to support integration with the UI state. An instance of this class is a model with the state of individual manual decorators.
+ * These decorators are kept as collections in {@link module:link/linkcommand~LinkCommand#manualDecorators}.
+ */
+export default class ManualDecorator extends ManualDecorator_base {
+    /**
+     * An ID of a manual decorator which is the name of the attribute in the model, for example: 'linkManualDecorator0'.
+     */
+    id: string;
+    /**
+     * The value of the current manual decorator. It reflects its state from the UI.
+     *
+     * @observable
+     */
+    value: boolean | undefined;
+    /**
+     * The default value of manual decorator.
+     */
+    defaultValue?: boolean;
+    /**
+     * The label used in the user interface to toggle the manual decorator.
+     */
+    label: string;
+    /**
+     * A set of attributes added to downcasted data when the decorator is activated for a specific link.
+     * Attributes should be added in a form of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
+     */
+    attributes?: Record<string, string>;
+    /**
+     * A set of classes added to downcasted data when the decorator is activated for a specific link.
+     * Classes should be added in a form of classes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
+     */
+    classes?: ArrayOrItem<string>;
+    /**
+     * A set of styles added to downcasted data when the decorator is activated for a specific link.
+     * Styles should be added in a form of styles defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
+     */
+    styles?: Record<string, string>;
+    /**
+     * Creates a new instance of {@link module:link/utils~ManualDecorator}.
+     *
+     * @param config.id The name of the attribute used in the model that represents a given manual decorator.
+     * For example: `'linkIsExternal'`.
+     * @param config.label The label used in the user interface to toggle the manual decorator.
+     * @param config.attributes A set of attributes added to output data when the decorator is active for a specific link.
+     * Attributes should keep the format of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
+     * @param [config.defaultValue] Controls whether the decorator is "on" by default.
+     */
+    constructor({ id, label, attributes, classes, styles, defaultValue }: NormalizedLinkDecoratorManualDefinition);
+    /**
+     * Returns {@link module:engine/view/matcher~MatcherPattern} with decorator attributes.
+     *
+     * @internal
+     */
+    _createPattern(): MatcherObjectPattern;
+}
+export {};