@ckeditor/ckeditor5-link 41.1.0 → 41.3.0-alpha.0

package/dist/types/linkimageediting.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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,40 @@
+/**
+ * @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,165 @@
+/**
+ * @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;
+    /**
+     * 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,103 @@
+/**
+ * @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,141 @@
+/**
+ * @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;
+    /**
+     * 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}.
+     */
+    constructor(locale: Locale, linkCommand: LinkCommand);
+    /**
+     * 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;
+    /**
+     * 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;
+}
+/**
+ * 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,31 @@
+/**
+ * @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,45 @@
+/**
+ * @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;
+}

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

@@ -0,0 +1,72 @@
+/**
+ * @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 {};