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

package/src/linkui.d.ts

@@ -6,9 +6,12 @@
  * @module link/linkui
  */
 import { Plugin } from 'ckeditor5/src/core.js';
-import { ContextualBalloon, type ViewWithCssTransitionDisabler } from 'ckeditor5/src/ui.js';
+import { ContextualBalloon, ToolbarView, type ViewWithCssTransitionDisabler } from 'ckeditor5/src/ui.js';
+import LinkEditing from './linkediting.js';
 import LinkFormView from './ui/linkformview.js';
-import LinkActionsView from './ui/linkactionsview.js';
+import LinkProviderItemsView from './ui/linkprovideritemsview.js';
+import LinkPropertiesView from './ui/linkpropertiesview.js';
+import '../theme/linktoolbar.css';
 /**
  * The link UI plugin. It introduces the `'link'` and `'unlink'` buttons and support for the <kbd>Ctrl+K</kbd> keystroke.
  *
@@ -17,21 +20,43 @@ import LinkActionsView from './ui/linkactionsview.js';
  */
 export default class LinkUI extends Plugin {
     /**
-     * The actions view displayed inside of the balloon.
+     * The toolbar view displayed inside of the balloon.
      */
-    actionsView: LinkActionsView | null;
+    toolbarView: ToolbarView | null;
     /**
      * The form view displayed inside the balloon.
      */
     formView: LinkFormView & ViewWithCssTransitionDisabler | null;
+    /**
+     * The view displaying links list.
+     */
+    linkProviderItemsView: LinkProviderItemsView | null;
+    /**
+     * The form view displaying properties link settings.
+     */
+    propertiesView: LinkPropertiesView & ViewWithCssTransitionDisabler | null;
+    /**
+     * The selected text of the link or text that is selected and can become a link.
+     *
+     * Note: It is `undefined` when the current selection does not allow for text,
+     * for example any non text node is selected or multiple blocks are selected.
+     *
+     * @observable
+     * @readonly
+     */
+    selectedLinkableText: string | undefined;
     /**
      * The contextual balloon plugin instance.
      */
     private _balloon;
+    /**
+     * The collection of the link providers.
+     */
+    private _linksProviders;
     /**
      * @inheritDoc
      */
-    static get requires(): readonly [typeof ContextualBalloon];
+    static get requires(): readonly [typeof ContextualBalloon, typeof LinkEditing];
     /**
      * @inheritDoc
      */
@@ -48,23 +73,51 @@ export default class LinkUI extends Plugin {
      * @inheritDoc
      */
     destroy(): void;
+    /**
+     * Registers list of buttons below the link form view that
+     * open a list of links provided by the clicked provider.
+     */
+    registerLinksListProvider(provider: LinksProvider): void;
     /**
      * Creates views.
      */
     private _createViews;
     /**
-     * Creates the {@link module:link/ui/linkactionsview~LinkActionsView} instance.
+     * Creates the ToolbarView instance.
      */
-    private _createActionsView;
+    private _createToolbarView;
     /**
      * Creates the {@link module:link/ui/linkformview~LinkFormView} instance.
      */
     private _createFormView;
     /**
-     * Creates a toolbar Link button. Clicking this button will show
-     * a {@link #_balloon} attached to the selection.
+     * Creates a sorted array of buttons with link names.
      */
-    private _createToolbarLinkButton;
+    private _createLinkProviderListView;
+    /**
+     * Creates a view for links provider.
+     */
+    private _createLinkProviderItemsView;
+    /**
+     * Creates the {@link module:link/ui/linkpropertiesview~LinkPropertiesView} instance.
+     */
+    private _createPropertiesView;
+    /**
+     * Obtains the state of the manual decorators.
+     */
+    private _getDecoratorSwitchesState;
+    /**
+     * Registers listeners used in editing plugin, used to open links.
+     */
+    private _registerEditingOpeners;
+    /**
+     * Registers components in the ComponentFactory.
+     */
+    private _registerComponents;
+    /**
+     * Creates a links button view.
+     */
+    private _createLinksListProviderButton;
     /**
      * Creates a button for link command to use either in toolbar or in menu bar.
      */
@@ -80,29 +133,46 @@ export default class LinkUI extends Plugin {
      */
     private _enableUserBalloonInteractions;
     /**
-     * Adds the {@link #actionsView} to the {@link #_balloon}.
+     * Adds the {@link #toolbarView} to the {@link #_balloon}.
      *
      * @internal
      */
-    _addActionsView(): void;
+    _addToolbarView(): void;
     /**
      * Adds the {@link #formView} to the {@link #_balloon}.
      */
     private _addFormView;
+    /**
+     * Adds the {@link #propertiesView} to the {@link #_balloon}.
+     */
+    private _addPropertiesView;
+    /**
+     * Shows the view with links provided by the given provider.
+     */
+    private _showLinksProviderView;
+    /**
+     * Adds the {@link #linkProviderItemsView} to the {@link #_balloon}.
+     */
+    private _addLinkProviderItemsView;
     /**
      * Closes the form view. Decides whether the balloon should be hidden completely or if the action view should be shown. This is
      * decided upon the link command value (which has a value if the document selection is in the link).
-     *
-     * Additionally, if any {@link module:link/linkconfig~LinkConfig#decorators} are defined in the editor configuration, the state of
-     * switch buttons responsible for manual decorator handling is restored.
      */
     private _closeFormView;
+    /**
+     * Removes the {@link #propertiesView} from the {@link #_balloon}.
+     */
+    private _removePropertiesView;
+    /**
+     * Removes the {@link #linkProviderItemsView} from the {@link #_balloon}.
+     */
+    private _removeLinksProviderView;
     /**
      * Removes the {@link #formView} from the {@link #_balloon}.
      */
     private _removeFormView;
     /**
-     * Shows the correct UI type. It is either {@link #formView} or {@link #actionsView}.
+     * Shows the correct UI type. It is either {@link #formView} or {@link #toolbarView}.
      *
      * @internal
      */
@@ -110,7 +180,7 @@ export default class LinkUI extends Plugin {
     /**
      * Removes the {@link #formView} from the {@link #_balloon}.
      *
-     * See {@link #_addFormView}, {@link #_addActionsView}.
+     * See {@link #_addFormView}, {@link #_addToolbarView}.
      */
     private _hideUI;
     /**
@@ -120,27 +190,46 @@ export default class LinkUI extends Plugin {
      * See: {@link #_hideUI} to learn when the UI stops reacting to the `update` event.
      */
     private _startUpdatingUI;
+    /**
+     * Returns `true` when {@link #propertiesView} is in the {@link #_balloon}.
+     */
+    private get _arePropertiesInPanel();
+    /**
+     * Returns `true` when {@link #linkProviderItemsView} is in the {@link #_balloon}.
+     */
+    private get _isLinksListInPanel();
     /**
      * Returns `true` when {@link #formView} is in the {@link #_balloon}.
      */
     private get _isFormInPanel();
     /**
-     * Returns `true` when {@link #actionsView} is in the {@link #_balloon}.
+     * Returns `true` when {@link #toolbarView} is in the {@link #_balloon}.
      */
-    private get _areActionsInPanel();
+    private get _isToolbarInPanel();
     /**
-     * Returns `true` when {@link #actionsView} is in the {@link #_balloon} and it is
+     * Returns `true` when {@link #propertiesView} is in the {@link #_balloon} and it is
      * currently visible.
      */
-    private get _areActionsVisible();
+    private get _isPropertiesVisible();
     /**
-     * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon}.
+     * Returns `true` when {@link #formView} is in the {@link #_balloon} and it is
+     * currently visible.
      */
-    private get _isUIInPanel();
+    private get _isFormVisible();
     /**
-     * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon} and it is
+     * Returns `true` when {@link #toolbarView} is in the {@link #_balloon} and it is
      * currently visible.
      */
+    private get _isToolbarVisible();
+    /**
+     * Returns `true` when {@link #propertiesView}, {@link #toolbarView}, {@link #linkProviderItemsView}
+     * or {@link #formView} is in the {@link #_balloon}.
+     */
+    private get _isUIInPanel();
+    /**
+     * Returns `true` when {@link #propertiesView}, {@link #linkProviderItemsView}, {@link #toolbarView}
+     * or {@link #formView} is in the {@link #_balloon} and it is currently visible.
+     */
     private get _isUIVisible();
     /**
      * Returns positioning options for the {@link #_balloon}. They control the way the balloon is attached
@@ -160,6 +249,19 @@ export default class LinkUI extends Plugin {
      * a linked widget is selected.
      */
     private _getSelectedLinkElement;
+    /**
+     * Returns selected link text content.
+     * If link is not selected it returns the selected text.
+     * If selection or link includes non text node (inline object or block) then returns undefined.
+     */
+    private _getSelectedLinkableText;
+    /**
+     * Returns a provider by its URL.
+     *
+     * @param href URL of the link.
+     * @returns Link provider and item or `null` if not found.
+     */
+    private _getLinkProviderLinkByHref;
     /**
      * Displays a fake visual selection when the contextual balloon is displayed.
      *
@@ -171,3 +273,92 @@ export default class LinkUI extends Plugin {
      */
     private _hideFakeVisualSelection;
 }
+/**
+ * Link list item that represents a single link in the provider's list.
+ * It's displayed after the user clicks the button that opens the list in the link form view.
+ */
+export type LinksProviderListItem = {
+    /**
+     * Unique identifier of the item. Avoids collection malfunction when there are links with the same labels.
+     */
+    id: string;
+    /**
+     * URL of the link.
+     */
+    href: string;
+    /**
+     * Label that is used as a text for the list item.
+     */
+    label: string;
+    /**
+     * Optional icon displayed for the item.
+     */
+    icon?: string;
+};
+/**
+ * Link list item with additional attributes that will be used when:
+ *
+ * 	* The item is selected and the preview of the item is displayed.
+ * 	* The user selects the item and the link is created.
+ * 	* The user navigates to the item using editing.
+ *
+ * It can be used to perform additional lookups in the database or to provide additional information about the link.
+ */
+export type LinksProviderDetailedItem = {
+    /**
+     * URL of the link.
+     */
+    href: string;
+    /**
+     * Optional icon displayed when the user opens toolbar with the item preview.
+     */
+    icon?: string;
+    /**
+     * Optional label shown in the link preview. If not passed then the `href` is used as the label.
+     */
+    label?: string;
+    /**
+     * Optional tooltip shown in the link preview.
+     */
+    tooltip?: string;
+};
+/**
+ * Interface for a provider that provides a list of links to be displayed in the link form view.
+ */
+export type LinksProvider = {
+    /**
+     * Label that serves two purposes:
+     *
+     * 	* As a text for the button that opens this link list from within link form view.
+     * 	* As a text for the header when the list of links from this provider is displayed.
+     */
+    label: string;
+    /**
+     * Message to be displayed when there are no items in the list.
+     * It's optional and if not provided, a default message will be displayed.
+     */
+    emptyListPlaceholder?: string;
+    /**
+     * Weight used for ordering providers in the list. Higher weight means the provider will be displayed lower in the list.
+     *
+     * @default 0
+     */
+    order?: number;
+    /**
+     * Callback for retrieving an static array of items which is being called every time the list is displayed.
+     * It's not required to provide all links at once, it's possible to pass only slice of links.
+     */
+    getListItems(): Array<LinksProviderListItem>;
+    /**
+     * Optional callback for retrieving an item by its URL.
+     * If not provided the item from the list will be used.
+     */
+    getItem?(href: string): LinksProviderDetailedItem | null;
+    /**
+     * Callback called when user clicked the link in the list.
+     *
+     * @param item Item that was clicked.
+     * @returns `true` if the link was handled by the provider, `false` otherwise. It'll prevent the default action if `true`.
+     */
+    navigate?(item: LinksProviderDetailedItem): boolean;
+};