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

package/dist/types/linkimageediting.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @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/linkimageediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import LinkEditing from './linkediting.js';
+/**
+ * The link image engine feature.
+ *
+ * It accepts the `linkHref="url"` attribute in the model for the {@link module:image/image~Image `<imageBlock>`} element
+ * which allows linking images.
+ */
+export default class LinkImageEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly ["ImageEditing", "ImageUtils", typeof LinkEditing];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LinkImageEditing";
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    /**
+     * Processes {@link module:link/linkconfig~LinkDecoratorAutomaticDefinition automatic decorators} definitions and
+     * attaches proper converters that will work when linking an image.`
+     */
+    private _enableAutomaticDecorators;
+    /**
+     * Processes transformed {@link module:link/utils/manualdecorator~ManualDecorator} instances and attaches proper converters
+     * that will work when linking an image.
+     */
+    private _enableManualDecorators;
+}

package/dist/types/linkimageui.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @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
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import LinkUI from './linkui.js';
+import LinkEditing from './linkediting.js';
+/**
+ * The link image UI plugin.
+ *
+ * This plugin provides the `'linkImage'` button that can be displayed in the {@link module:image/imagetoolbar~ImageToolbar}.
+ * It can be used to wrap images in links.
+ */
+export default class LinkImageUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof LinkEditing, typeof LinkUI, "ImageBlockEditing"];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LinkImageUI";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates a `LinkImageUI` button view.
+     *
+     * Clicking this button shows a {@link module:link/linkui~LinkUI#_balloon} attached to the selection.
+     * When an image is already linked, the view shows {@link module:link/linkui~LinkUI#actionsView} or
+     * {@link module:link/linkui~LinkUI#formView} if it is not.
+     */
+    private _createToolbarLinkImageButton;
+    /**
+     * Returns true if a linked image (either block or inline) is the only selected element
+     * in the model document.
+     */
+    private _isSelectedLinkedImage;
+}

package/dist/types/linkui.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @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/linkui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { ContextualBalloon, type ViewWithCssTransitionDisabler } from 'ckeditor5/src/ui.js';
+import LinkFormView from './ui/linkformview.js';
+import LinkActionsView from './ui/linkactionsview.js';
+/**
+ * The link UI plugin. It introduces the `'link'` and `'unlink'` buttons and support for the <kbd>Ctrl+K</kbd> keystroke.
+ *
+ * It uses the
+ * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon plugin}.
+ */
+export default class LinkUI extends Plugin {
+    /**
+     * The actions view displayed inside of the balloon.
+     */
+    actionsView: LinkActionsView | null;
+    /**
+     * The form view displayed inside the balloon.
+     */
+    formView: LinkFormView & ViewWithCssTransitionDisabler | null;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ContextualBalloon];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LinkUI";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates views.
+     */
+    private _createViews;
+    /**
+     * Creates the {@link module:link/ui/linkactionsview~LinkActionsView} instance.
+     */
+    private _createActionsView;
+    /**
+     * 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.
+     */
+    private _createToolbarLinkButton;
+    /**
+     * Creates a button for link command to use either in toolbar or in menu bar.
+     */
+    private _createButton;
+    /**
+     * Attaches actions that control whether the balloon panel containing the
+     * {@link #formView} should be displayed.
+     */
+    private _enableBalloonActivators;
+    /**
+     * Attaches actions that control whether the balloon panel containing the
+     * {@link #formView} is visible or not.
+     */
+    private _enableUserBalloonInteractions;
+    /**
+     * Adds the {@link #actionsView} to the {@link #_balloon}.
+     *
+     * @internal
+     */
+    _addActionsView(): void;
+    /**
+     * Adds the {@link #formView} to the {@link #_balloon}.
+     */
+    private _addFormView;
+    /**
+     * 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 #formView} from the {@link #_balloon}.
+     */
+    private _removeFormView;
+    /**
+     * Shows the correct UI type. It is either {@link #formView} or {@link #actionsView}.
+     *
+     * @internal
+     */
+    _showUI(forceVisible?: boolean): void;
+    /**
+     * Removes the {@link #formView} from the {@link #_balloon}.
+     *
+     * See {@link #_addFormView}, {@link #_addActionsView}.
+     */
+    private _hideUI;
+    /**
+     * Makes the UI react to the {@link module:ui/editorui/editorui~EditorUI#event:update} event to
+     * reposition itself when the editor UI should be refreshed.
+     *
+     * See: {@link #_hideUI} to learn when the UI stops reacting to the `update` event.
+     */
+    private _startUpdatingUI;
+    /**
+     * Returns `true` when {@link #formView} is in the {@link #_balloon}.
+     */
+    private get _isFormInPanel();
+    /**
+     * Returns `true` when {@link #actionsView} is in the {@link #_balloon}.
+     */
+    private get _areActionsInPanel();
+    /**
+     * Returns `true` when {@link #actionsView} is in the {@link #_balloon} and it is
+     * currently visible.
+     */
+    private get _areActionsVisible();
+    /**
+     * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon}.
+     */
+    private get _isUIInPanel();
+    /**
+     * Returns `true` when {@link #actionsView} 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
+     * to the target element or selection.
+     *
+     * If the selection is collapsed and inside a link element, the panel will be attached to the
+     * entire link element. Otherwise, it will be attached to the selection.
+     */
+    private _getBalloonPositionData;
+    /**
+     * Returns the link {@link module:engine/view/attributeelement~AttributeElement} under
+     * the {@link module:engine/view/document~Document editing view's} selection or `null`
+     * if there is none.
+     *
+     * **Note**: For a non–collapsed selection, the link element is returned when **fully**
+     * selected and the **only** element within the selection boundaries, or when
+     * a linked widget is selected.
+     */
+    private _getSelectedLinkElement;
+    /**
+     * Displays a fake visual selection when the contextual balloon is displayed.
+     *
+     * This adds a 'link-ui' marker into the document that is rendered as a highlight on selected text fragment.
+     */
+    private _showFakeVisualSelection;
+    /**
+     * Hides the fake visual selection created in {@link #_showFakeVisualSelection}.
+     */
+    private _hideFakeVisualSelection;
+}

package/dist/types/ui/linkactionsview.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @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/ui/linkactionsview
+ */
+import { ButtonView, View } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type LocaleTranslate, type Locale } from 'ckeditor5/src/utils.js';
+import '@ckeditor/ckeditor5-ui/theme/components/responsive-form/responsiveform.css';
+import '../../theme/linkactions.css';
+import type { LinkConfig } from '../linkconfig.js';
+/**
+ * The link actions view class. This view displays the link preview, allows
+ * unlinking or editing the link.
+ */
+export default class LinkActionsView extends View {
+    /**
+     * Tracks information about DOM focus in the actions.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * The href preview view.
+     */
+    previewButtonView: ButtonView;
+    /**
+     * The unlink button view.
+     */
+    unlinkButtonView: ButtonView;
+    /**
+     * The edit link button view.
+     */
+    editButtonView: ButtonView;
+    /**
+     * The value of the "href" attribute of the link to use in the {@link #previewButtonView}.
+     *
+     * @observable
+     */
+    href: string | undefined;
+    /**
+     * A collection of views that can be focused in the view.
+     */
+    private readonly _focusables;
+    /**
+     * Helps cycling over {@link #_focusables} in the view.
+     */
+    private readonly _focusCycler;
+    private readonly _linkConfig;
+    t: LocaleTranslate;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, linkConfig?: LinkConfig);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the fist {@link #_focusables} in the actions.
+     */
+    focus(): void;
+    /**
+     * Creates a button view.
+     *
+     * @param label The button label.
+     * @param icon The button icon.
+     * @param eventName An event name that the `ButtonView#execute` event will be delegated to.
+     * @returns The button view instance.
+     */
+    private _createButton;
+    /**
+     * Creates a link href preview button.
+     *
+     * @returns The button view instance.
+     */
+    private _createPreviewButton;
+}
+/**
+ * Fired when the {@link ~LinkActionsView#editButtonView} is clicked.
+ *
+ * @eventName ~LinkActionsView#edit
+ */
+export type EditEvent = {
+    name: 'edit';
+    args: [];
+};
+/**
+ * Fired when the {@link ~LinkActionsView#unlinkButtonView} is clicked.
+ *
+ * @eventName ~LinkActionsView#unlink
+ */
+export type UnlinkEvent = {
+    name: 'unlink';
+    args: [];
+};

package/dist/types/ui/linkformview.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @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/ui/linkformview
+ */
+import { ButtonView, LabeledFieldView, View, ViewCollection, type InputTextView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import type LinkCommand from '../linkcommand.js';
+import '@ckeditor/ckeditor5-ui/theme/components/responsive-form/responsiveform.css';
+import '../../theme/linkform.css';
+/**
+ * The link form view controller class.
+ *
+ * See {@link module:link/ui/linkformview~LinkFormView}.
+ */
+export default class LinkFormView 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 URL input view.
+     */
+    urlInputView: LabeledFieldView<InputTextView>;
+    /**
+     * The Save button view.
+     */
+    saveButtonView: ButtonView;
+    /**
+     * The Cancel button view.
+     */
+    cancelButtonView: ButtonView;
+    /**
+     * A collection of {@link module:ui/button/switchbuttonview~SwitchButtonView},
+     * which corresponds to {@link module:link/linkcommand~LinkCommand#manualDecorators manual decorators}
+     * configured in the editor.
+     */
+    private readonly _manualDecoratorSwitches;
+    /**
+     * 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.
+     */
+    private readonly _focusables;
+    /**
+     * Helps cycling over {@link #_focusables} in the form.
+     */
+    private readonly _focusCycler;
+    /**
+     * Creates an instance of the {@link module:link/ui/linkformview~LinkFormView} class.
+     *
+     * Also see {@link #render}.
+     *
+     * @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, 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}
+     * in the {@link module:link/ui/linkformview~LinkFormView}.
+     *
+     * @returns Key-value pairs, where the key is the name of the decorator and the value is its state.
+     */
+    getDecoratorSwitchesState(): Record<string, boolean>;
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * 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.
+     *
+     * @returns Labeled field view instance.
+     */
+    private _createUrlInput;
+    /**
+     * Creates a button view.
+     *
+     * @param label The button label.
+     * @param icon The button icon.
+     * @param className The additional button CSS class name.
+     * @param eventName An event name that the `ButtonView#execute` event will be delegated to.
+     * @returns The button view instance.
+     */
+    private _createButton;
+    /**
+     * Populates {@link module:ui/viewcollection~ViewCollection} of {@link module:ui/button/switchbuttonview~SwitchButtonView}
+     * made based on {@link module:link/linkcommand~LinkCommand#manualDecorators}.
+     *
+     * @param linkCommand A reference to the link command.
+     * @returns ViewCollection of switch buttons.
+     */
+    private _createManualDecoratorSwitches;
+    /**
+     * Populates the {@link #children} collection of the form.
+     *
+     * If {@link module:link/linkcommand~LinkCommand#manualDecorators manual decorators} are configured in the editor, it creates an
+     * additional `View` wrapping all {@link #_manualDecoratorSwitches} switch buttons corresponding
+     * to these decorators.
+     *
+     * @param manualDecorators A reference to
+     * the collection of manual decorators stored in the link command.
+     * @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}.
+ *
+ * @eventName ~LinkFormView#submit
+ */
+export type SubmitEvent = {
+    name: 'submit';
+    args: [];
+};
+/**
+ * Fired when the form view is canceled, for example with a click on {@link ~LinkFormView#cancelButtonView}.
+ *
+ * @eventName ~LinkFormView#cancel
+ */
+export type CancelEvent = {
+    name: 'cancel';
+    args: [];
+};

package/dist/types/unlinkcommand.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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/unlinkcommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The unlink command. It is used by the {@link module:link/link~Link link plugin}.
+ */
+export default class UnlinkCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * When the selection is collapsed, it removes the `linkHref` attribute from each node with the same `linkHref` attribute value.
+     * When the selection is non-collapsed, it removes the `linkHref` attribute from each node in selected ranges.
+     *
+     * # Decorators
+     *
+     * If {@link module:link/linkconfig~LinkConfig#decorators `config.link.decorators`} is specified,
+     * all configured decorators are removed together with the `linkHref` attribute.
+     *
+     * @fires execute
+     */
+    execute(): void;
+}

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

@@ -0,0 +1,49 @@
+/**
+ * @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/automaticdecorators
+ */
+import { type ArrayOrItem } from 'ckeditor5/src/utils.js';
+import type { DowncastDispatcher } from 'ckeditor5/src/engine.js';
+import type { NormalizedLinkDecoratorAutomaticDefinition } from '../utils.js';
+/**
+ * Helper class that ties together all {@link module:link/linkconfig~LinkDecoratorAutomaticDefinition} and provides
+ * the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement downcast dispatchers} for them.
+ */
+export default class AutomaticDecorators {
+    /**
+     * 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.
+     */
+    private _definitions;
+    /**
+     * Gives information about the number of decorators stored in the {@link module:link/utils/automaticdecorators~AutomaticDecorators}
+     * instance.
+     */
+    get length(): number;
+    /**
+     * Adds automatic decorator objects or an array with them to be used during downcasting.
+     *
+     * @param item A configuration object of automatic rules for decorating links. It might also be an array of such objects.
+     */
+    add(item: ArrayOrItem<NormalizedLinkDecoratorAutomaticDefinition>): void;
+    /**
+     * Provides the conversion helper used in the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method.
+     *
+     * @returns A dispatcher function used as conversion helper in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}.
+     */
+    getDispatcher(): (dispatcher: DowncastDispatcher) => void;
+    /**
+     * Provides the conversion helper used in the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method
+     * when linking images.
+     *
+     * @returns A dispatcher function used as conversion helper in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}.
+     */
+    getDispatcherForLinkedImage(): (dispatcher: DowncastDispatcher) => void;
+}