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

package/src/link.js

@@ -2,259 +2,31 @@
  * @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/link
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import LinkEditing from './linkediting';
 import LinkUI from './linkui';
 import AutoLink from './autolink';
-
+import './linkconfig';
 /**
  * The link plugin.
  *
  * This is a "glue" plugin that loads the {@link module:link/linkediting~LinkEditing link editing feature}
  * and {@link module:link/linkui~LinkUI link UI feature}.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class Link extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ LinkEditing, LinkUI, AutoLink ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'Link';
-	}
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [LinkEditing, LinkUI, AutoLink];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'Link';
+    }
 }
-
-/**
- * The configuration of the {@link module:link/link~Link} feature.
- *
- * Read more in {@link module:link/link~LinkConfig}.
- *
- * @member {module:link/link~LinkConfig} module:core/editor/editorconfig~EditorConfig#link
- */
-
-/**
- * The configuration of the {@link module:link/link~Link link feature}.
- *
- *		ClassicEditor
- *			.create( editorElement, {
- * 				link:  ... // Link feature configuration.
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
- * @interface LinkConfig
- */
-
-/**
- * When set, the editor will add the given protocol to the link when the user creates a link without one.
- * For example, when the user is creating a link and types `ckeditor.com` in the link form input, during link submission
- * the editor will automatically add the `http://` protocol, so the link will look as follows: `http://ckeditor.com`.
- *
- * The feature also provides email address auto-detection. When you submit `hello@example.com`,
- * the plugin will automatically change it to `mailto:hello@example.com`.
- *
- * 		ClassicEditor
- *			.create( editorElement, {
- * 				link: {
- * 					defaultProtocol: 'http://'
- * 				}
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * **NOTE:** If no configuration is provided, the editor will not auto-fix the links.
- *
- * @member {String} module:link/link~LinkConfig#defaultProtocol
- */
-
-/**
- * When set to `true`, the `target="blank"` and `rel="noopener noreferrer"` attributes are automatically added to all external links
- * in the editor. "External links" are all links in the editor content starting with `http`, `https`, or `//`.
- *
- *		ClassicEditor
- *			.create( editorElement, {
- *				link: {
- *					addTargetToExternalLinks: true
- *				}
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * Internally, this option activates a predefined {@link module:link/link~LinkConfig#decorators automatic link decorator}
- * that extends all external links with the `target` and `rel` attributes.
- *
- * **Note**: To control the `target` and `rel` attributes of specific links in the edited content, a dedicated
- * {@link module:link/link~LinkDecoratorManualDefinition manual} decorator must be defined in the
- * {@link module:link/link~LinkConfig#decorators `config.link.decorators`} array. In such scenario,
- * the `config.link.addTargetToExternalLinks` option should remain `undefined` or `false` to not interfere with the manual decorator.
- *
- * It is possible to add other {@link module:link/link~LinkDecoratorAutomaticDefinition automatic}
- * or {@link module:link/link~LinkDecoratorManualDefinition manual} link decorators when this option is active.
- *
- * More information about decorators can be found in the {@link module:link/link~LinkConfig#decorators decorators configuration}
- * reference.
- *
- * @default false
- * @member {Boolean} module:link/link~LinkConfig#addTargetToExternalLinks
- */
-
-/**
- * Decorators provide an easy way to configure and manage additional link attributes in the editor content. There are
- * two types of link decorators:
- *
- * * {@link module:link/link~LinkDecoratorAutomaticDefinition Automatic} – They match links against pre–defined rules and
- * manage their attributes based on the results.
- * * {@link module:link/link~LinkDecoratorManualDefinition Manual} – They allow users to control link attributes individually,
- *  using the editor UI.
- *
- * Link decorators are defined as objects with key-value pairs, where the key is the name provided for a given decorator and the
- * value is the decorator definition.
- *
- * The name of the decorator also corresponds to the {@glink framework/guides/architecture/editing-engine#text-attributes text attribute}
- * in the model. For instance, the `isExternal` decorator below is represented as a `linkIsExternal` attribute in the model.
- *
- *		ClassicEditor
- *			.create( editorElement, {
- *				link: {
- *					decorators: {
- *						isExternal: {
- *							mode: 'automatic',
- *							callback: url => url.startsWith( 'http://' ),
- *							attributes: {
- *								target: '_blank',
- *								rel: 'noopener noreferrer'
- *							}
- *						},
- *						isDownloadable: {
- *							mode: 'manual',
- *							label: 'Downloadable',
- *							attributes: {
- *								download: 'file.png',
- *							}
- *						},
- *						// ...
- *					}
- *				}
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * To learn more about the configuration syntax, check out the {@link module:link/link~LinkDecoratorAutomaticDefinition automatic}
- * and {@link module:link/link~LinkDecoratorManualDefinition manual} decorator option reference.
- *
- * **Warning:** Currently, link decorators work independently of one another and no conflict resolution mechanism exists.
- * For example, configuring the `target` attribute using both an automatic and a manual decorator at the same time could end up with
- * quirky results. The same applies if multiple manual or automatic decorators were defined for the same attribute.
- *
- * **Note**: Since the `target` attribute management for external links is a common use case, there is a predefined automatic decorator
- * dedicated for that purpose which can be enabled by turning a single option on. Check out the
- * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}
- * configuration description to learn more.
- *
- * See also the {@glink features/link#custom-link-attributes-decorators link feature guide} for more information.
- *
- * @member {Object.<String, module:link/link~LinkDecoratorDefinition>} module:link/link~LinkConfig#decorators
- */
-
-/**
- * A link decorator definition. Two types implement this defition:
- *
- * * {@link module:link/link~LinkDecoratorManualDefinition}
- * * {@link module:link/link~LinkDecoratorAutomaticDefinition}
- *
- * Refer to their document for more information about available options or to the
- * {@glink features/link#custom-link-attributes-decorators link feature guide} for general information.
- *
- * @interface LinkDecoratorDefinition
- */
-
-/**
- * Link decorator type.
- *
- * Check out the {@glink features/link#custom-link-attributes-decorators link feature guide} for more information.
- *
- * @member {'manual'|'automatic'} module:link/link~LinkDecoratorDefinition#mode
- */
-
-/**
- * Describes an automatic {@link module:link/link~LinkConfig#decorators link decorator}. This decorator type matches
- * all links in the editor content against a function that decides whether the link should receive a pre–defined set of attributes.
- *
- * It takes an object with key-value pairs of attributes and a callback function that must return a Boolean value based on the link's
- * `href` (URL). When the callback returns `true`, attributes are applied to the link.
- *
- * For example, to add the `target="_blank"` attribute to all links in the editor starting with `http://`, the
- * configuration could look like this:
- *
- *		{
- *			mode: 'automatic',
- *			callback: url => url.startsWith( 'http://' ),
- *			attributes: {
- *				target: '_blank'
- *			}
- *		}
- *
- * **Note**: Since the `target` attribute management for external links is a common use case, there is a predefined automatic decorator
- * dedicated for that purpose that can be enabled by turning a single option on. Check out the
- * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}
- * configuration description to learn more.
- *
- * @typedef {Object} module:link/link~LinkDecoratorAutomaticDefinition
- * @property {'automatic'} mode Link decorator type. It is `'automatic'` for all automatic decorators.
- * @property {Function} callback Takes a `url` as a parameter and returns `true` if the `attributes` should be applied to the link.
- * @property {Object} [attributes] Key-value pairs used as link attributes added to the output during the
- * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
- * Attributes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
- * @property {Object} [styles] Key-value pairs used as link styles added to the output during the
- * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
- * Styles should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
- * @property {String|Array.<String>} [classes] Class names used as link classes added to the output during the
- * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
- * Classes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
- */
-
-/**
- * Describes a manual {@link module:link/link~LinkConfig#decorators link decorator}. This decorator type is represented in
- * the link feature's {@link module:link/linkui user interface} as a switch that the user can use to control the presence
- * of a predefined set of attributes.
- *
- * For instance, to allow the users to manually control the presence of the `target="_blank"` and
- * `rel="noopener noreferrer"` attributes on specific links, the decorator could look as follows:
- *
- *		{
- *			mode: 'manual',
- *			label: 'Open in a new tab',
- *			defaultValue: true,
- *			attributes: {
- *				target: '_blank',
- *				rel: 'noopener noreferrer'
- *			}
- *		}
- *
- * @typedef {Object} module:link/link~LinkDecoratorManualDefinition
- * @property {'manual'} mode Link decorator type. It is `'manual'` for all manual decorators.
- * @property {String} label The label of the UI button that the user can use to control the presence of link attributes.
- * @property {Object} [attributes] Key-value pairs used as link attributes added to the output during the
- * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
- * Attributes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
- * @property {Object} [styles] Key-value pairs used as link styles added to the output during the
- * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
- * Styles should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
- * @property {String|Array.<String>} [classes] Class names used as link classes added to the output during the
- * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
- * Classes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
- * @property {Boolean} [defaultValue] Controls whether the decorator is "on" by default.
- */

package/src/linkcommand.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @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/linkcommand
+ */
+import { Command } from 'ckeditor5/src/core';
+import { Collection } from 'ckeditor5/src/utils';
+import AutomaticDecorators from './utils/automaticdecorators';
+import type ManualDecorator from './utils/manualdecorator';
+/**
+ * The link command. It is used by the {@link module:link/link~Link link feature}.
+ */
+export default class LinkCommand extends Command {
+    /**
+     * The value of the `'linkHref'` attribute if the start of the selection is located in a node with this attribute.
+     *
+     * @observable
+     * @readonly
+     */
+    value: string | undefined;
+    /**
+     * A collection of {@link module:link/utils~ManualDecorator manual decorators}
+     * corresponding to the {@link module:link/link~LinkConfig#decorators decorator configuration}.
+     *
+     * You can consider it a model with states of manual decorators added to the currently selected link.
+     */
+    readonly manualDecorators: Collection<ManualDecorator>;
+    /**
+     * An instance of the helper that ties together all {@link module:link/link~LinkDecoratorAutomaticDefinition}
+     * that are used by the {@glink features/link link} and the {@glink features/images/images-linking linking images} features.
+     */
+    readonly automaticDecorators: AutomaticDecorators;
+    /**
+     * Synchronizes the state of {@link #manualDecorators} with the currently present elements in the model.
+     */
+    restoreManualDecoratorStates(): void;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * When the selection is non-collapsed, the `linkHref` attribute will be applied to nodes inside the selection, but only to
+     * those nodes where the `linkHref` attribute is allowed (disallowed nodes will be omitted).
+     *
+     * When the selection is collapsed and is not inside the text with the `linkHref` attribute, a
+     * new {@link module:engine/model/text~Text text node} with the `linkHref` attribute will be inserted in place of the caret, but
+     * only if such element is allowed in this place. The `_data` of the inserted text will equal the `href` parameter.
+     * The selection will be updated to wrap the just inserted text node.
+     *
+     * When the selection is collapsed and inside the text with the `linkHref` attribute, the attribute value will be updated.
+     *
+     * # Decorators and model attribute management
+     *
+     * There is an optional argument to this command that applies or removes model
+     * {@glink framework/guides/architecture/editing-engine#text-attributes text attributes} brought by
+     * {@link module:link/utils~ManualDecorator manual link decorators}.
+     *
+     * Text attribute names in the model correspond to the entries in the {@link module:link/link~LinkConfig#decorators configuration}.
+     * For every decorator configured, a model text attribute exists with the "link" prefix. For example, a `'linkMyDecorator'` attribute
+     * corresponds to `'myDecorator'` in the configuration.
+     *
+     * To learn more about link decorators, check out the {@link module:link/link~LinkConfig#decorators `config.link.decorators`}
+     * documentation.
+     *
+     * Here is how to manage decorator attributes with the link command:
+     *
+     * ```ts
+     * const linkCommand = editor.commands.get( 'link' );
+     *
+     * // Adding a new decorator attribute.
+     * linkCommand.execute( 'http://example.com', {
+     * 	linkIsExternal: true
+     * } );
+     *
+     * // Removing a decorator attribute from the selection.
+     * linkCommand.execute( 'http://example.com', {
+     * 	linkIsExternal: false
+     * } );
+     *
+     * // Adding multiple decorator attributes at the same time.
+     * linkCommand.execute( 'http://example.com', {
+     * 	linkIsExternal: true,
+     * 	linkIsDownloadable: true,
+     * } );
+     *
+     * // Removing and adding decorator attributes at the same time.
+     * linkCommand.execute( 'http://example.com', {
+     * 	linkIsExternal: false,
+     * 	linkFoo: true,
+     * 	linkIsDownloadable: false,
+     * } );
+     * ```
+     *
+     * **Note**: If the decorator attribute name is not specified, its state remains untouched.
+     *
+     * **Note**: {@link module:link/unlinkcommand~UnlinkCommand#execute `UnlinkCommand#execute()`} removes all
+     * decorator attributes.
+     *
+     * @fires execute
+     * @param href Link destination.
+     * @param manualDecoratorIds The information about manual decorator attributes to be applied or removed upon execution.
+     */
+    execute(href: string, manualDecoratorIds?: Record<string, boolean>): void;
+    /**
+     * Provides information whether a decorator with a given name is present in the currently processed selection.
+     *
+     * @param decoratorName The name of the manual decorator used in the model
+     * @returns The information whether a given decorator is currently present in the selection.
+     */
+    private _getDecoratorStateFromModel;
+    /**
+     * Checks whether specified `range` is inside an element that accepts the `linkHref` attribute.
+     *
+     * @param range A range to check.
+     * @param allowedRanges An array of ranges created on elements where the attribute is accepted.
+     */
+    private _isRangeToUpdate;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        link: LinkCommand;
+    }
+}