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

package/src/ui/linkpropertiesview.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+ */
+/**
+ * @module link/ui/linkpropertiesview
+ */
+import { ButtonView, View, ViewCollection, type SwitchButtonView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import '../../theme/linkproperties.css';
+/**
+ * The link properties view controller class.
+ *
+ * See {@link module:link/ui/linkpropertiesview~LinkPropertiesView}.
+ */
+export default class LinkPropertiesView extends View {
+    /**
+     * Tracks information about DOM focus in the form.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * The Back button view displayed in the header.
+     */
+    backButtonView: ButtonView;
+    /**
+     * A collection of child views.
+     */
+    readonly children: ViewCollection;
+    /**
+     * A collection of {@link module:ui/button/switchbuttonview~SwitchButtonView},
+     * which corresponds to {@link module:link/linkcommand~LinkCommand#manualDecorators manual decorators}
+     * configured in the editor.
+     */
+    readonly listChildren: ViewCollection<SwitchButtonView>;
+    /**
+     * A collection of views that can be focused in the form.
+     */
+    private readonly _focusables;
+    /**
+     * Helps cycling over {@link #_focusables} in the form.
+     */
+    private readonly _focusCycler;
+    /**
+     * Creates an instance of the {@link module:link/ui/linkpropertiesview~LinkPropertiesView} class.
+     *
+     * Also see {@link #render}.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the fist {@link #_focusables} in the form.
+     */
+    focus(): void;
+    /**
+     * Creates a back button view.
+     */
+    private _createBackButton;
+    /**
+     * Creates a header view for the form.
+     */
+    private _createHeaderView;
+    /**
+     * Creates a form view that displays the {@link #listChildren} collection.
+     */
+    private _createListView;
+}
+/**
+ * Fired when the {@link ~LinkPropertiesView#backButtonView} is pressed.
+ *
+ * @eventName ~LinkPropertiesView#back
+ */
+export type BackEvent = {
+    name: 'back';
+    args: [];
+};

package/src/ui/linkpropertiesview.js

@@ -0,0 +1,170 @@
+/**
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+ */
+/**
+ * @module link/ui/linkpropertiesview
+ */
+import { ButtonView, FocusCycler, FormHeaderView, View, ViewCollection, ListView, ListItemView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler } from 'ckeditor5/src/utils.js';
+import { IconPreviousArrow } from '@ckeditor/ckeditor5-icons';
+import '../../theme/linkproperties.css';
+/**
+ * The link properties view controller class.
+ *
+ * See {@link module:link/ui/linkpropertiesview~LinkPropertiesView}.
+ */
+export default class LinkPropertiesView extends View {
+    /**
+     * Tracks information about DOM focus in the form.
+     */
+    focusTracker = new FocusTracker();
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    keystrokes = new KeystrokeHandler();
+    /**
+     * The Back button view displayed in the header.
+     */
+    backButtonView;
+    /**
+     * A collection of child views.
+     */
+    children;
+    /**
+     * A collection of {@link module:ui/button/switchbuttonview~SwitchButtonView},
+     * which corresponds to {@link module:link/linkcommand~LinkCommand#manualDecorators manual decorators}
+     * configured in the editor.
+     */
+    listChildren;
+    /**
+     * A collection of views that can be focused in the form.
+     */
+    _focusables = new ViewCollection();
+    /**
+     * Helps cycling over {@link #_focusables} in the form.
+     */
+    _focusCycler;
+    /**
+     * Creates an instance of the {@link module:link/ui/linkpropertiesview~LinkPropertiesView} class.
+     *
+     * Also see {@link #render}.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale) {
+        super(locale);
+        this.backButtonView = this._createBackButton();
+        this.listChildren = this.createCollection();
+        this.children = this.createCollection([
+            this._createHeaderView(),
+            this._createListView()
+        ]);
+        this._focusCycler = new FocusCycler({
+            focusables: this._focusables,
+            focusTracker: this.focusTracker,
+            keystrokeHandler: this.keystrokes,
+            actions: {
+                // Navigate form fields backwards using the Shift + Tab keystroke.
+                focusPrevious: 'shift + tab',
+                // Navigate form fields forwards using the Tab key.
+                focusNext: 'tab'
+            }
+        });
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-link-properties'
+                ],
+                // https://github.com/ckeditor/ckeditor5-link/issues/90
+                tabindex: '-1'
+            },
+            children: this.children
+        });
+        // Close the panel on esc key press when the **form has focus**.
+        this.keystrokes.set('Esc', (data, cancel) => {
+            this.fire('back');
+            cancel();
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        const childViews = [
+            ...this.listChildren,
+            this.backButtonView
+        ];
+        childViews.forEach(v => {
+            // Register the view as focusable.
+            this._focusables.add(v);
+            // Register the view in the focus tracker.
+            this.focusTracker.add(v.element);
+        });
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Focuses the fist {@link #_focusables} in the form.
+     */
+    focus() {
+        this._focusCycler.focusFirst();
+    }
+    /**
+     * Creates a back button view.
+     */
+    _createBackButton() {
+        const t = this.locale.t;
+        const backButton = new ButtonView(this.locale);
+        // TODO: maybe we should have a dedicated BackButtonView in the UI library.
+        backButton.set({
+            class: 'ck-button-back',
+            label: t('Back'),
+            icon: IconPreviousArrow,
+            tooltip: true
+        });
+        backButton.delegate('execute').to(this, 'back');
+        return backButton;
+    }
+    /**
+     * Creates a header view for the form.
+     */
+    _createHeaderView() {
+        const t = this.locale.t;
+        const header = new FormHeaderView(this.locale, {
+            label: t('Link properties')
+        });
+        header.children.add(this.backButtonView, 0);
+        return header;
+    }
+    /**
+     * Creates a form view that displays the {@link #listChildren} collection.
+     */
+    _createListView() {
+        const listView = new ListView(this.locale);
+        listView.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-link__list'
+                ]
+            }
+        });
+        listView.items.bindTo(this.listChildren).using(item => {
+            const listItemView = new ListItemView(this.locale);
+            listItemView.children.add(item);
+            return listItemView;
+        });
+        return listView;
+    }
+}

package/src/ui/linkprovideritemsview.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+ */
+/**
+ * @module link/ui/linkprovideritemsview
+ */
+import { ButtonView, View, ListView, ViewCollection } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import '../../theme/linkprovideritems.css';
+/**
+ * The link provider items view.
+ */
+export default class LinkProviderItemsView extends View {
+    /**
+     * Tracks information about the list of links.
+     *
+     * @observable
+     */
+    hasItems: boolean;
+    /**
+     * The header label of the view.
+     *
+     * @observable
+     */
+    title: string;
+    /**
+     * The text displayed when no links are available.
+     *
+     * @observable
+     */
+    emptyListPlaceholder: string;
+    /**
+     * Tracks information about DOM focus in the form.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * The Back button view displayed in the header.
+     */
+    backButtonView: ButtonView;
+    /**
+     * The List view of links buttons.
+     */
+    listView: ListView;
+    /**
+     * The collection of child views, which is bind with the `listView`.
+     */
+    readonly listChildren: ViewCollection<ButtonView>;
+    /**
+     * The view displayed when the list is empty.
+     */
+    emptyListInformation: View;
+    /**
+     * A collection of child views.
+     */
+    children: ViewCollection;
+    /**
+     * A collection of views that can be focused in the form.
+     */
+    private readonly _focusables;
+    /**
+     * Helps cycling over {@link #_focusables} in the form.
+     */
+    private readonly _focusCycler;
+    /**
+     * Creates an instance of the {@link module:link/ui/linkprovideritemsview~LinkProviderItemsView} class.
+     *
+     * Also see {@link #render}.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the fist {@link #_focusables} in the form.
+     */
+    focus(): void;
+    /**
+     * Creates a view for the list at the bottom.
+     */
+    private _createListView;
+    /**
+     * Creates a back button view that cancels the form.
+     */
+    private _createBackButton;
+    /**
+     * Creates a header view for the form.
+     */
+    private _createHeaderView;
+    /**
+     * Creates an info view for an empty list.
+     */
+    private _createEmptyLinksListItemView;
+}
+/**
+ * Fired when the links view is canceled, for example with a click on {@link ~LinkProviderItemsView#backButtonView}.
+ *
+ * @eventName ~LinkProviderItemsView#cancel
+ */
+export type CancelEvent = {
+    name: 'cancel';
+    args: [];
+};

package/src/ui/linkprovideritemsview.js

@@ -0,0 +1,207 @@
+/**
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+ */
+/**
+ * @module link/ui/linkprovideritemsview
+ */
+import { ButtonView, FocusCycler, FormHeaderView, View, ListView, ListItemView, ViewCollection } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler } from 'ckeditor5/src/utils.js';
+import { IconPreviousArrow } from '@ckeditor/ckeditor5-icons';
+import '../../theme/linkprovideritems.css';
+/**
+ * The link provider items view.
+ */
+export default class LinkProviderItemsView extends View {
+    /**
+     * Tracks information about DOM focus in the form.
+     */
+    focusTracker = new FocusTracker();
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    keystrokes = new KeystrokeHandler();
+    /**
+     * The Back button view displayed in the header.
+     */
+    backButtonView;
+    /**
+     * The List view of links buttons.
+     */
+    listView;
+    /**
+     * The collection of child views, which is bind with the `listView`.
+     */
+    listChildren;
+    /**
+     * The view displayed when the list is empty.
+     */
+    emptyListInformation;
+    /**
+     * A collection of child views.
+     */
+    children;
+    /**
+     * A collection of views that can be focused in the form.
+     */
+    _focusables = new ViewCollection();
+    /**
+     * Helps cycling over {@link #_focusables} in the form.
+     */
+    _focusCycler;
+    /**
+     * Creates an instance of the {@link module:link/ui/linkprovideritemsview~LinkProviderItemsView} class.
+     *
+     * Also see {@link #render}.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale) {
+        super(locale);
+        this.listChildren = this.createCollection();
+        this.backButtonView = this._createBackButton();
+        this.listView = this._createListView();
+        this.emptyListInformation = this._createEmptyLinksListItemView();
+        this.children = this.createCollection([
+            this._createHeaderView(),
+            this.emptyListInformation
+        ]);
+        this.set('title', '');
+        this.set('emptyListPlaceholder', '');
+        this.set('hasItems', false);
+        this.listenTo(this.listChildren, 'change', () => {
+            this.hasItems = this.listChildren.length > 0;
+        });
+        this.on('change:hasItems', (evt, propName, hasItems) => {
+            if (hasItems) {
+                this.children.remove(this.emptyListInformation);
+                this.children.add(this.listView);
+            }
+            else {
+                this.children.remove(this.listView);
+                this.children.add(this.emptyListInformation);
+            }
+        });
+        // Close the panel on esc key press when the **form has focus**.
+        this.keystrokes.set('Esc', (data, cancel) => {
+            this.fire('cancel');
+            cancel();
+        });
+        this._focusCycler = new FocusCycler({
+            focusables: this._focusables,
+            focusTracker: this.focusTracker,
+            keystrokeHandler: this.keystrokes,
+            actions: {
+                // Navigate form fields backwards using the Shift + Tab keystroke.
+                focusPrevious: 'shift + tab',
+                // Navigate form fields forwards using the Tab key.
+                focusNext: 'tab'
+            }
+        });
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-link-providers'
+                ],
+                // https://github.com/ckeditor/ckeditor5-link/issues/90
+                tabindex: '-1'
+            },
+            children: this.children
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        const childViews = [
+            this.listView,
+            this.backButtonView
+        ];
+        childViews.forEach(v => {
+            // Register the view as focusable.
+            this._focusables.add(v);
+            // Register the view in the focus tracker.
+            this.focusTracker.add(v.element);
+        });
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Focuses the fist {@link #_focusables} in the form.
+     */
+    focus() {
+        this._focusCycler.focusFirst();
+    }
+    /**
+     * Creates a view for the list at the bottom.
+     */
+    _createListView() {
+        const listView = new ListView(this.locale);
+        listView.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-link-providers__list'
+                ]
+            }
+        });
+        listView.items.bindTo(this.listChildren).using(button => {
+            const listItemView = new ListItemView(this.locale);
+            listItemView.children.add(button);
+            return listItemView;
+        });
+        return listView;
+    }
+    /**
+     * Creates a back button view that cancels the form.
+     */
+    _createBackButton() {
+        const t = this.locale.t;
+        const backButton = new ButtonView(this.locale);
+        backButton.set({
+            class: 'ck-button-back',
+            label: t('Back'),
+            icon: IconPreviousArrow,
+            tooltip: true
+        });
+        backButton.delegate('execute').to(this, 'cancel');
+        return backButton;
+    }
+    /**
+     * Creates a header view for the form.
+     */
+    _createHeaderView() {
+        const header = new FormHeaderView(this.locale);
+        header.bind('label').to(this, 'title');
+        header.children.add(this.backButtonView, 0);
+        return header;
+    }
+    /**
+     * Creates an info view for an empty list.
+     */
+    _createEmptyLinksListItemView() {
+        const view = new View(this.locale);
+        view.setTemplate({
+            tag: 'p',
+            attributes: {
+                class: ['ck', 'ck-link__empty-list-info']
+            },
+            children: [
+                {
+                    text: this.bindTemplate.to('emptyListPlaceholder')
+                }
+            ]
+        });
+        return view;
+    }
+}

package/src/utils/automaticdecorators.js

@@ -11,13 +11,11 @@ import { toMap } from 'ckeditor5/src/utils.js';
  * the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement downcast dispatchers} for them.
  */
 export default class AutomaticDecorators {
-    constructor() {
-        /**
-         * Stores the definition of {@link module:link/linkconfig~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();
-    }
+    /**
+     * Stores the definition of {@link module:link/linkconfig~LinkDecoratorAutomaticDefinition automatic decorators}.
+     * This data is used as a source for a downcast dispatcher to create a proper conversion to output data.
+     */
+    _definitions = new Set();
     /**
      * Gives information about the number of decorators stored in the {@link module:link/utils/automaticdecorators~AutomaticDecorators}
      * instance.

package/src/utils/manualdecorator.js

@@ -12,6 +12,33 @@ import { ObservableMixin } from 'ckeditor5/src/utils.js';
  * These decorators are kept as collections in {@link module:link/linkcommand~LinkCommand#manualDecorators}.
  */
 export default class ManualDecorator extends /* #__PURE__ */ ObservableMixin() {
+    /**
+     * An ID of a manual decorator which is the name of the attribute in the model, for example: 'linkManualDecorator0'.
+     */
+    id;
+    /**
+     * The default value of manual decorator.
+     */
+    defaultValue;
+    /**
+     * The label used in the user interface to toggle the manual decorator.
+     */
+    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}.
+     */
+    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}.
+     */
+    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}.
+     */
+    styles;
     /**
      * Creates a new instance of {@link module:link/utils/manualdecorator~ManualDecorator}.
      *

package/src/utils.d.ts

@@ -5,11 +5,9 @@
 /**
  * @module link/utils
  */
-import type { DowncastConversionApi, Element, Schema, ViewAttributeElement, ViewNode, ViewDocumentFragment } from 'ckeditor5/src/engine.js';
-import type { Editor } from 'ckeditor5/src/core.js';
+import type { DowncastConversionApi, Element, Schema, ViewAttributeElement, ViewNode, ViewDocumentFragment, Range } from 'ckeditor5/src/engine.js';
 import type { LocaleTranslate } from 'ckeditor5/src/utils.js';
 import type { LinkDecoratorAutomaticDefinition, LinkDecoratorDefinition, LinkDecoratorManualDefinition } from './linkconfig.js';
-import type { LinkActionsViewOptions } from './ui/linkactionsview.js';
 /**
  * A keystroke used by the {@link module:link/linkui~LinkUI link UI feature}.
  */
@@ -74,9 +72,11 @@ export declare function linkHasProtocol(link: string): boolean;
  */
 export declare function openLink(link: string): void;
 /**
- * Creates the bookmark callbacks for handling link opening experience.
+ * Returns a text of a link range.
+ *
+ * If the returned value is `undefined`, the range contains elements other than text nodes.
  */
-export declare function createBookmarkCallbacks(editor: Editor): LinkActionsViewOptions;
+export declare function extractTextFromLinkRange(range: Range): string | undefined;
 export type NormalizedLinkDecoratorAutomaticDefinition = LinkDecoratorAutomaticDefinition & {
     id: string;
 };