@ckeditor/ckeditor5-link 41.3.1 → 41.4.0-alpha.0

package/dist/types/utils/manualdecorator.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @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
+ */
+/**
+ * @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/utils/manualdecorator
+ */
+import { type ArrayOrItem } from 'ckeditor5/src/utils.js';
+import type { MatcherObjectPattern } from 'ckeditor5/src/engine.js';
+import type { NormalizedLinkDecoratorManualDefinition } from '../utils.js';
+declare const ManualDecorator_base: {
+    new (): import("ckeditor5/src/utils.js").Observable;
+    prototype: import("ckeditor5/src/utils.js").Observable;
+};
+/**
+ * Helper class that stores manual decorators with observable {@link module:link/utils/manualdecorator~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~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 {};

package/dist/types/utils.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @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
+ */
+/**
+ * @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/utils
+ */
+import type { DowncastConversionApi, Element, Schema, ViewAttributeElement, ViewNode, ViewDocumentFragment } from 'ckeditor5/src/engine.js';
+import type { LocaleTranslate } from 'ckeditor5/src/utils.js';
+import type { LinkDecoratorAutomaticDefinition, LinkDecoratorDefinition, LinkDecoratorManualDefinition } from './linkconfig.js';
+/**
+ * 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, allowedProtocols?: Array<string>): string;
+/**
+ * Returns the {@link module:link/linkconfig~LinkConfig#decorators `config.link.decorators`} configuration processed
+ * to respect the locale of the editor, i.e. to display the {@link module:link/linkconfig~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/linkconfig~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/linkconfig~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/lang/contexts.json

@@ -2,6 +2,7 @@
 	"Unlink": "Toolbar button tooltip for the Unlink feature.",
 	"Link": "Toolbar button tooltip for the Link feature.",
 	"Link URL": "Label for the URL input in the Link URL editing balloon.",
+	"Link URL must not be empty.": "An error text displayed when user attempted to enter an empty URL.",
 	"Link image": "Label for the image link button.",
 	"Edit link": "Button opening the Link URL editing balloon.",
 	"Open link in new tab": "Button opening the link in new browser tab.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-link",
-  "version": "41.3.1",
+  "version": "41.4.0-alpha.0",
   "description": "Link feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -13,8 +13,8 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-ui": "41.3.1",
-    "ckeditor5": "41.3.1",
+    "@ckeditor/ckeditor5-ui": "41.4.0-alpha.0",
+    "ckeditor5": "41.4.0-alpha.0",
     "lodash-es": "4.17.21"
   },
   "author": "CKSource (http://cksource.com/)",
@@ -27,6 +27,7 @@
     "directory": "packages/ckeditor5-link"
   },
   "files": [
+    "dist",
     "lang",
     "src/**/*.js",
     "src/**/*.d.ts",

package/src/index.d.ts

@@ -12,7 +12,7 @@ export { default as LinkImage } from './linkimage.js';
 export { default as LinkImageEditing } from './linkimageediting.js';
 export { default as LinkImageUI } from './linkimageui.js';
 export { default as AutoLink } from './autolink.js';
-export { LinkConfig, type LinkDecoratorDefinition } from './linkconfig.js';
+export type { LinkConfig, LinkDecoratorDefinition } from './linkconfig.js';
 export { default as LinkCommand } from './linkcommand.js';
 export { default as UnlinkCommand } from './unlinkcommand.js';
 import './augmentation.js';

package/src/linkui.js

@@ -148,19 +148,24 @@ export default class LinkUI extends Plugin {
         const editor = this.editor;
         const linkCommand = editor.commands.get('link');
         const defaultProtocol = editor.config.get('link.defaultProtocol');
-        const allowCreatingEmptyLinks = editor.config.get('link.allowCreatingEmptyLinks');
-        const formView = new (CssTransitionDisablerMixin(LinkFormView))(editor.locale, linkCommand);
+        const formView = new (CssTransitionDisablerMixin(LinkFormView))(editor.locale, linkCommand, getFormValidators(editor));
         formView.urlInputView.fieldView.bind('value').to(linkCommand, 'value');
         // Form elements should be read-only when corresponding commands are disabled.
         formView.urlInputView.bind('isEnabled').to(linkCommand, 'isEnabled');
-        // Disable the "save" button if the command is disabled or the input is empty despite being required.
-        formView.saveButtonView.bind('isEnabled').to(linkCommand, 'isEnabled', formView.urlInputView, 'isEmpty', (isCommandEnabled, isInputEmpty) => isCommandEnabled && (allowCreatingEmptyLinks || !isInputEmpty));
+        // Disable the "save" button if the command is disabled.
+        formView.saveButtonView.bind('isEnabled').to(linkCommand, 'isEnabled');
         // Execute link command after clicking the "Save" button.
         this.listenTo(formView, 'submit', () => {
-            const { value } = formView.urlInputView.fieldView.element;
-            const parsedUrl = addLinkProtocolIfApplicable(value, defaultProtocol);
-            editor.execute('link', parsedUrl, formView.getDecoratorSwitchesState());
-            this._closeFormView();
+            if (formView.isValid()) {
+                const { value } = formView.urlInputView.fieldView.element;
+                const parsedUrl = addLinkProtocolIfApplicable(value, defaultProtocol);
+                editor.execute('link', parsedUrl, formView.getDecoratorSwitchesState());
+                this._closeFormView();
+            }
+        });
+        // Update balloon position when form error changes.
+        this.listenTo(formView.urlInputView, 'change:errorText', () => {
+            editor.ui.update();
         });
         // Hide the panel after clicking the "Cancel" button.
         this.listenTo(formView, 'cancel', () => {
@@ -299,6 +304,7 @@ export default class LinkUI extends Plugin {
         const editor = this.editor;
         const linkCommand = editor.commands.get('link');
         this.formView.disableCssTransitions();
+        this.formView.resetFormStatus();
         this._balloon.add({
             view: this.formView,
             position: this._getBalloonPositionData()
@@ -615,3 +621,19 @@ export default class LinkUI extends Plugin {
 function findLinkElementAncestor(position) {
     return position.getAncestors().find((ancestor) => isLinkElement(ancestor)) || null;
 }
+/**
+ * Returns link form validation callbacks.
+ *
+ * @param editor Editor instance.
+ */
+function getFormValidators(editor) {
+    const t = editor.t;
+    const allowCreatingEmptyLinks = editor.config.get('link.allowCreatingEmptyLinks');
+    return [
+        form => {
+            if (!allowCreatingEmptyLinks && !form.url.length) {
+                return t('Link URL must not be empty.');
+            }
+        }
+    ];
+}

package/src/ui/linkformview.d.ts

@@ -46,6 +46,10 @@ export default class LinkFormView extends View {
      * A collection of child views in the form.
      */
     readonly children: ViewCollection;
+    /**
+     * An array of form validators used by {@link #isValid}.
+     */
+    private readonly _validators;
     /**
      * A collection of views that can be focused in the form.
      */
@@ -61,8 +65,9 @@ export default class LinkFormView extends View {
      *
      * @param locale The localization services instance.
      * @param linkCommand Reference to {@link module:link/linkcommand~LinkCommand}.
+     * @param validators  Form validators used by {@link #isValid}.
      */
-    constructor(locale: Locale, linkCommand: LinkCommand);
+    constructor(locale: Locale, linkCommand: LinkCommand, validators: Array<LinkFormValidatorCallback>);
     /**
      * Obtains the state of the {@link module:ui/button/switchbuttonview~SwitchButtonView switch buttons} representing
      * {@link module:link/linkcommand~LinkCommand#manualDecorators manual link decorators}
@@ -83,6 +88,17 @@ export default class LinkFormView extends View {
      * Focuses the fist {@link #_focusables} in the form.
      */
     focus(): void;
+    /**
+     * Validates the form and returns `false` when some fields are invalid.
+     */
+    isValid(): boolean;
+    /**
+     * Cleans up the supplementary error and information text of the {@link #urlInputView}
+     * bringing them back to the state when the form has been displayed for the first time.
+     *
+     * See {@link #isValid}.
+     */
+    resetFormStatus(): void;
     /**
      * Creates a labeled input view.
      *
@@ -119,7 +135,21 @@ export default class LinkFormView extends View {
      * @returns The children of link form view.
      */
     private _createFormChildren;
+    /**
+     * The native DOM `value` of the {@link #urlInputView} element.
+     *
+     * **Note**: Do not confuse it with the {@link module:ui/inputtext/inputtextview~InputTextView#value}
+     * which works one way only and may not represent the actual state of the component in the DOM.
+     */
+    get url(): string | null;
 }
+/**
+ * Callback used by {@link ~LinkFormView} to check if passed form value is valid.
+ *
+ * 	* If `undefined` is returned, it is assumed that the form value is correct and there is no error.
+ * 	* If string is returned, it is assumed that the form value is incorrect and the returned string is displayed in the error label
+ */
+export type LinkFormValidatorCallback = (form: LinkFormView) => string | undefined;
 /**
  * Fired when the form view is submitted (when one of the children triggered the submit event),
  * for example with a click on {@link ~LinkFormView#saveButtonView}.

package/src/ui/linkformview.js

@@ -25,8 +25,9 @@ export default class LinkFormView extends View {
      *
      * @param locale The localization services instance.
      * @param linkCommand Reference to {@link module:link/linkcommand~LinkCommand}.
+     * @param validators  Form validators used by {@link #isValid}.
      */
-    constructor(locale, linkCommand) {
+    constructor(locale, linkCommand, validators) {
         super(locale);
         /**
          * Tracks information about DOM focus in the form.
@@ -41,6 +42,7 @@ export default class LinkFormView extends View {
          */
         this._focusables = new ViewCollection();
         const t = locale.t;
+        this._validators = validators;
         this.urlInputView = this._createUrlInput();
         this.saveButtonView = this._createButton(t('Save'), icons.check, 'ck-button-save');
         this.saveButtonView.type = 'submit';
@@ -124,6 +126,31 @@ export default class LinkFormView extends View {
     focus() {
         this._focusCycler.focusFirst();
     }
+    /**
+     * Validates the form and returns `false` when some fields are invalid.
+     */
+    isValid() {
+        this.resetFormStatus();
+        for (const validator of this._validators) {
+            const errorText = validator(this);
+            // One error per field is enough.
+            if (errorText) {
+                // Apply updated error.
+                this.urlInputView.errorText = errorText;
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Cleans up the supplementary error and information text of the {@link #urlInputView}
+     * bringing them back to the state when the form has been displayed for the first time.
+     *
+     * See {@link #isValid}.
+     */
+    resetFormStatus() {
+        this.urlInputView.errorText = null;
+    }
     /**
      * Creates a labeled input view.
      *
@@ -229,4 +256,17 @@ export default class LinkFormView extends View {
         children.add(this.cancelButtonView);
         return children;
     }
+    /**
+     * The native DOM `value` of the {@link #urlInputView} element.
+     *
+     * **Note**: Do not confuse it with the {@link module:ui/inputtext/inputtextview~InputTextView#value}
+     * which works one way only and may not represent the actual state of the component in the DOM.
+     */
+    get url() {
+        const { element } = this.urlInputView.fieldView;
+        if (!element) {
+            return null;
+        }
+        return element.value.trim();
+    }
 }

package/theme/linkform.css

@@ -7,6 +7,7 @@
 
 .ck.ck-link-form {
 	display: flex;
+	align-items: flex-start;
 
 	& .ck-label {
 		display: none;