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

package/src/utils/manualdecorator.js

@@ -2,100 +2,46 @@
  * @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/manualdecorator
  */
-
-import { ObservableMixin, mix } from 'ckeditor5/src/utils';
-
+import { ObservableMixin } from 'ckeditor5/src/utils';
 /**
  * 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}.
- *
- * @mixes module:utils/observablemixin~ObservableMixin
  */
-export default class ManualDecorator {
-	/**
-	 * Creates a new instance of {@link module:link/utils~ManualDecorator}.
-	 *
-	 * @param {Object} config
-	 * @param {String} config.id The name of the attribute used in the model that represents a given manual decorator.
-	 * For example: `'linkIsExternal'`.
-	 * @param {String} config.label The label used in the user interface to toggle the manual decorator.
-	 * @param {Object} 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 {Boolean} [config.defaultValue] Controls whether the decorator is "on" by default.
-	 */
-	constructor( { id, label, attributes, classes, styles, defaultValue } ) {
-		/**
-		 * An ID of a manual decorator which is the name of the attribute in the model, for example: 'linkManualDecorator0'.
-		 *
-		 * @type {String}
-		 */
-		this.id = id;
-
-		/**
-		 * The value of the current manual decorator. It reflects its state from the UI.
-		 *
-		 * @observable
-		 * @member {Boolean} module:link/utils~ManualDecorator#value
-		 */
-		this.set( 'value' );
-
-		/**
-		 * The default value of manual decorator.
-		 *
-		 * @type {Boolean}
-		 */
-		this.defaultValue = defaultValue;
-
-		/**
-		 * The label used in the user interface to toggle the manual decorator.
-		 *
-		 * @type {String}
-		 */
-		this.label = label;
-
-		/**
-		 * 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}.
-		 *
-		 * @type {Object}
-		 */
-		this.attributes = attributes;
-
-		/**
-		 * 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}.
-		 *
-		 * @type {Object}
-		 */
-		this.classes = classes;
-
-		/**
-		 * 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}.
-		 *
-		 * @type {Object}
-		 */
-		this.styles = styles;
-	}
-
-	/**
-	 * Returns {@link module:engine/view/matcher~MatcherPattern} with decorator attributes.
-	 *
-	 * @protected
-	 * @returns {module:engine/view/matcher~MatcherPattern}
-	 */
-	_createPattern() {
-		return {
-			attributes: this.attributes,
-			classes: this.classes,
-			styles: this.styles
-		};
-	}
+export default class ManualDecorator extends ObservableMixin() {
+    /**
+     * 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 }) {
+        super();
+        this.id = id;
+        this.set('value', undefined);
+        this.defaultValue = defaultValue;
+        this.label = label;
+        this.attributes = attributes;
+        this.classes = classes;
+        this.styles = styles;
+    }
+    /**
+     * Returns {@link module:engine/view/matcher~MatcherPattern} with decorator attributes.
+     *
+     * @internal
+     */
+    _createPattern() {
+        return {
+            attributes: this.attributes,
+            classes: this.classes,
+            styles: this.styles
+        };
+    }
 }
-
-mix( ManualDecorator, ObservableMixin );

package/src/utils.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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
+ */
+import type { DowncastConversionApi, Element, Schema, ViewAttributeElement, ViewNode, ViewDocumentFragment } from 'ckeditor5/src/engine';
+import type { LocaleTranslate } from 'ckeditor5/src/utils';
+import type { LinkDecoratorAutomaticDefinition, LinkDecoratorDefinition, LinkDecoratorManualDefinition } from './linkconfig';
+/**
+ * A keystroke used by the {@link module:link/linkui~LinkUI link UI feature}.
+ */
+export declare const LINK_KEYSTROKE = "Ctrl+K";
+/**
+ * Returns `true` if a given view node is the link element.
+ */
+export declare function isLinkElement(node: ViewNode | ViewDocumentFragment): boolean;
+/**
+ * Creates a link {@link module:engine/view/attributeelement~AttributeElement} with the provided `href` attribute.
+ */
+export declare function createLinkElement(href: string, { writer }: DowncastConversionApi): ViewAttributeElement;
+/**
+ * Returns a safe URL based on a given value.
+ *
+ * A URL is considered safe if it is safe for the user (does not contain any malicious code).
+ *
+ * If a URL is considered unsafe, a simple `"#"` is returned.
+ *
+ * @internal
+ */
+export declare function ensureSafeUrl(url: unknown): string;
+/**
+ * Returns the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration processed
+ * to respect the locale of the editor, i.e. to display the {@link module:link/link~LinkDecoratorManualDefinition label}
+ * in the correct language.
+ *
+ * **Note**: Only the few most commonly used labels are translated automatically. Other labels should be manually
+ * translated in the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration.
+ *
+ * @param t Shorthand for {@link module:utils/locale~Locale#t Locale#t}.
+ * @param decorators The decorator reference where the label values should be localized.
+ */
+export declare function getLocalizedDecorators(t: LocaleTranslate, decorators: Array<NormalizedLinkDecoratorDefinition>): Array<NormalizedLinkDecoratorDefinition>;
+/**
+ * Converts an object with defined decorators to a normalized array of decorators. The `id` key is added for each decorator and
+ * is used as the attribute's name in the model.
+ */
+export declare function normalizeDecorators(decorators?: Record<string, LinkDecoratorDefinition>): Array<NormalizedLinkDecoratorDefinition>;
+/**
+ * Returns `true` if the specified `element` can be linked (the element allows the `linkHref` attribute).
+ */
+export declare function isLinkableElement(element: Element | null, schema: Schema): element is Element;
+/**
+ * Returns `true` if the specified `value` is an email.
+ */
+export declare function isEmail(value: string): boolean;
+/**
+ * Adds the protocol prefix to the specified `link` when:
+ *
+ * * it does not contain it already, and there is a {@link module:link/link~LinkConfig#defaultProtocol `defaultProtocol` }
+ * configuration value provided,
+ * * or the link is an email address.
+ */
+export declare function addLinkProtocolIfApplicable(link: string, defaultProtocol?: string): string;
+/**
+ * Checks if protocol is already included in the link.
+ */
+export declare function linkHasProtocol(link: string): boolean;
+/**
+ * Opens the link in a new browser tab.
+ */
+export declare function openLink(link: string): void;
+export type NormalizedLinkDecoratorAutomaticDefinition = LinkDecoratorAutomaticDefinition & {
+    id: string;
+};
+export type NormalizedLinkDecoratorManualDefinition = LinkDecoratorManualDefinition & {
+    id: string;
+};
+export type NormalizedLinkDecoratorDefinition = NormalizedLinkDecoratorAutomaticDefinition | NormalizedLinkDecoratorManualDefinition;

package/src/utils.js

@@ -2,55 +2,33 @@
  * @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
- */
-
-/* global window */
-
 import { upperFirst } from 'lodash-es';
-
 const ATTRIBUTE_WHITESPACES = /[\u0000-\u0020\u00A0\u1680\u180E\u2000-\u2029\u205f\u3000]/g; // eslint-disable-line no-control-regex
 const SAFE_URL = /^(?:(?:https?|ftps?|mailto):|[^a-z]|[a-z+.-]+(?:[^a-z+.:-]|$))/i;
-
 // Simplified email test - should be run over previously found URL.
 const EMAIL_REG_EXP = /^[\S]+@((?![-_])(?:[-\w\u00a1-\uffff]{0,63}[^-_]\.))+(?:[a-z\u00a1-\uffff]{2,})$/i;
-
 // The regex checks for the protocol syntax ('xxxx://' or 'xxxx:')
 // or non-word characters at the beginning of the link ('/', '#' etc.).
 const PROTOCOL_REG_EXP = /^((\w+:(\/{2,})?)|(\W))/i;
-
 /**
  * A keystroke used by the {@link module:link/linkui~LinkUI link UI feature}.
  */
 export const LINK_KEYSTROKE = 'Ctrl+K';
-
 /**
  * Returns `true` if a given view node is the link element.
- *
- * @param {module:engine/view/node~Node} node
- * @returns {Boolean}
  */
-export function isLinkElement( node ) {
-	return node.is( 'attributeElement' ) && !!node.getCustomProperty( 'link' );
+export function isLinkElement(node) {
+    return node.is('attributeElement') && !!node.getCustomProperty('link');
 }
-
 /**
  * Creates a link {@link module:engine/view/attributeelement~AttributeElement} with the provided `href` attribute.
- *
- * @param {String} href
- * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi
- * @returns {module:engine/view/attributeelement~AttributeElement}
  */
-export function createLinkElement( href, { writer } ) {
-	// Priority 5 - https://github.com/ckeditor/ckeditor5-link/issues/121.
-	const linkElement = writer.createAttributeElement( 'a', { href }, { priority: 5 } );
-	writer.setCustomProperty( 'link', true, linkElement );
-
-	return linkElement;
+export function createLinkElement(href, { writer }) {
+    // Priority 5 - https://github.com/ckeditor/ckeditor5-link/issues/121.
+    const linkElement = writer.createAttributeElement('a', { href }, { priority: 5 });
+    writer.setCustomProperty('link', true, linkElement);
+    return linkElement;
 }
-
 /**
  * Returns a safe URL based on a given value.
  *
@@ -58,25 +36,19 @@ export function createLinkElement( href, { writer } ) {
  *
  * If a URL is considered unsafe, a simple `"#"` is returned.
  *
- * @protected
- * @param {*} url
- * @returns {String} Safe URL.
+ * @internal
  */
-export function ensureSafeUrl( url ) {
-	url = String( url );
-
-	return isSafeUrl( url ) ? url : '#';
+export function ensureSafeUrl(url) {
+    const urlString = String(url);
+    return isSafeUrl(urlString) ? urlString : '#';
 }
-
-// Checks whether the given URL is safe for the user (does not contain any malicious code).
-//
-// @param {String} url URL to check.
-function isSafeUrl( url ) {
-	const normalizedUrl = url.replace( ATTRIBUTE_WHITESPACES, '' );
-
-	return normalizedUrl.match( SAFE_URL );
+/**
+ * Checks whether the given URL is safe for the user (does not contain any malicious code).
+ */
+function isSafeUrl(url) {
+    const normalizedUrl = url.replace(ATTRIBUTE_WHITESPACES, '');
+    return !!normalizedUrl.match(SAFE_URL);
 }
-
 /**
  * Returns the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration processed
  * to respect the locale of the editor, i.e. to display the {@link module:link/link~LinkDecoratorManualDefinition label}
@@ -85,110 +57,72 @@ function isSafeUrl( url ) {
  * **Note**: Only the few most commonly used labels are translated automatically. Other labels should be manually
  * translated in the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration.
  *
- * @param {module:utils/locale~Locale#t} t shorthand for {@link module:utils/locale~Locale#t Locale#t}
- * @param {Array.<module:link/link~LinkDecoratorDefinition>} The decorator reference
- * where the label values should be localized.
- * @returns {Array.<module:link/link~LinkDecoratorDefinition>}
+ * @param t Shorthand for {@link module:utils/locale~Locale#t Locale#t}.
+ * @param decorators The decorator reference where the label values should be localized.
  */
-export function getLocalizedDecorators( t, decorators ) {
-	const localizedDecoratorsLabels = {
-		'Open in a new tab': t( 'Open in a new tab' ),
-		'Downloadable': t( 'Downloadable' )
-	};
-
-	decorators.forEach( decorator => {
-		if ( decorator.label && localizedDecoratorsLabels[ decorator.label ] ) {
-			decorator.label = localizedDecoratorsLabels[ decorator.label ];
-		}
-		return decorator;
-	} );
-
-	return decorators;
+export function getLocalizedDecorators(t, decorators) {
+    const localizedDecoratorsLabels = {
+        'Open in a new tab': t('Open in a new tab'),
+        'Downloadable': t('Downloadable')
+    };
+    decorators.forEach(decorator => {
+        if ('label' in decorator && localizedDecoratorsLabels[decorator.label]) {
+            decorator.label = localizedDecoratorsLabels[decorator.label];
+        }
+        return decorator;
+    });
+    return decorators;
 }
-
 /**
  * Converts an object with defined decorators to a normalized array of decorators. The `id` key is added for each decorator and
  * is used as the attribute's name in the model.
- *
- * @param {Object.<String, module:link/link~LinkDecoratorDefinition>} decorators
- * @returns {Array.<module:link/link~LinkDecoratorDefinition>}
  */
-export function normalizeDecorators( decorators ) {
-	const retArray = [];
-
-	if ( decorators ) {
-		for ( const [ key, value ] of Object.entries( decorators ) ) {
-			const decorator = Object.assign(
-				{},
-				value,
-				{ id: `link${ upperFirst( key ) }` }
-			);
-			retArray.push( decorator );
-		}
-	}
-
-	return retArray;
+export function normalizeDecorators(decorators) {
+    const retArray = [];
+    if (decorators) {
+        for (const [key, value] of Object.entries(decorators)) {
+            const decorator = Object.assign({}, value, { id: `link${upperFirst(key)}` });
+            retArray.push(decorator);
+        }
+    }
+    return retArray;
 }
-
 /**
  * Returns `true` if the specified `element` can be linked (the element allows the `linkHref` attribute).
- *
- * @params {module:engine/model/element~Element|null} element
- * @params {module:engine/model/schema~Schema} schema
- * @returns {Boolean}
  */
-export function isLinkableElement( element, schema ) {
-	if ( !element ) {
-		return false;
-	}
-
-	return schema.checkAttribute( element.name, 'linkHref' );
+export function isLinkableElement(element, schema) {
+    if (!element) {
+        return false;
+    }
+    return schema.checkAttribute(element.name, 'linkHref');
 }
-
 /**
  * Returns `true` if the specified `value` is an email.
- *
- * @params {String} value
- * @returns {Boolean}
  */
-export function isEmail( value ) {
-	return EMAIL_REG_EXP.test( value );
+export function isEmail(value) {
+    return EMAIL_REG_EXP.test(value);
 }
-
 /**
  * Adds the protocol prefix to the specified `link` when:
  *
  * * it does not contain it already, and there is a {@link module:link/link~LinkConfig#defaultProtocol `defaultProtocol` }
  * configuration value provided,
  * * or the link is an email address.
- *
- *
- * @params {String} link
- * @params {String} defaultProtocol
- * @returns {String}
  */
-export function addLinkProtocolIfApplicable( link, defaultProtocol ) {
-	const protocol = isEmail( link ) ? 'mailto:' : defaultProtocol;
-	const isProtocolNeeded = !!protocol && !linkHasProtocol( link );
-
-	return link && isProtocolNeeded ? protocol + link : link;
+export function addLinkProtocolIfApplicable(link, defaultProtocol) {
+    const protocol = isEmail(link) ? 'mailto:' : defaultProtocol;
+    const isProtocolNeeded = !!protocol && !linkHasProtocol(link);
+    return link && isProtocolNeeded ? protocol + link : link;
 }
-
 /**
  * Checks if protocol is already included in the link.
- *
- * @param {String} link
- * @returns {Boolean}
  */
-export function linkHasProtocol( link ) {
-	return PROTOCOL_REG_EXP.test( link );
+export function linkHasProtocol(link) {
+    return PROTOCOL_REG_EXP.test(link);
 }
-
 /**
  * Opens the link in a new browser tab.
- *
- * @param {String} link
  */
-export function openLink( link ) {
-	window.open( link, '_blank', 'noopener' );
+export function openLink(link) {
+    window.open(link, '_blank', 'noopener');
 }