@ckeditor/ckeditor5-ui 40.1.0 → 41.0.0

package/src/dialog/dialog.js

@@ -0,0 +1,261 @@
+/**
+ * @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 '@ckeditor/ckeditor5-core';
+import DialogView, { DialogViewPosition } from './dialogview.js';
+/**
+ * The dialog controller class. It is used to show and hide the {@link module:ui/dialog/dialogview~DialogView}.
+ */
+export default class Dialog extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'Dialog';
+    }
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        super(editor);
+        this._initShowHideListeners();
+        this._initFocusToggler();
+        this._initMultiRootIntegration();
+        this.set('id', null);
+    }
+    /**
+     * Initiates listeners for the `show` and `hide` events emitted by this plugin.
+     *
+     * We couldn't simply decorate the {@link #show} and {@link #hide} methods to fire events,
+     * because they would be fired in the wrong order - first would be `show` and then `hide`
+     * (because showing the dialog actually starts with hiding the previously visible one).
+     * Hence, we added private methods {@link #_show} and {@link #_hide} which are called on events
+     * in the desired sequence.
+     */
+    _initShowHideListeners() {
+        this.on('show', (evt, args) => {
+            this._show(args);
+        });
+        // 'low' priority allows to add custom callback between `_show()` and `onShow()`.
+        this.on('show', (evt, args) => {
+            if (args.onShow) {
+                args.onShow(this);
+            }
+        }, { priority: 'low' });
+        this.on('hide', () => {
+            if (Dialog._visibleDialogPlugin) {
+                Dialog._visibleDialogPlugin._hide();
+            }
+        });
+        // 'low' priority allows to add custom callback between `_hide()` and `onHide()`.
+        this.on('hide', () => {
+            if (this._onHide) {
+                this._onHide(this);
+                this._onHide = undefined;
+            }
+        }, { priority: 'low' });
+    }
+    /**
+     * Initiates keystroke handler for toggling the focus between the editor and dialog view.
+     */
+    _initFocusToggler() {
+        const editor = this.editor;
+        editor.keystrokes.set('Ctrl+F6', (data, cancel) => {
+            if (!this.isOpen || this.view.isModal) {
+                return;
+            }
+            if (this.view.focusTracker.isFocused) {
+                editor.editing.view.focus();
+            }
+            else {
+                this.view.focus();
+            }
+            cancel();
+        });
+    }
+    /**
+     * Provides an integration between the root attaching and detaching and positioning of the view.
+     */
+    _initMultiRootIntegration() {
+        const model = this.editor.model;
+        model.document.on('change:data', () => {
+            if (!this.view) {
+                return;
+            }
+            const changedRoots = model.document.differ.getChangedRoots();
+            for (const changes of changedRoots) {
+                if (changes.state) {
+                    this.view.updatePosition();
+                }
+            }
+        });
+    }
+    /**
+     * Displays a dialog window.
+     *
+     * This method requires a {@link ~DialogDefinition} that defines dialog's content, title, icon, action buttons, etc.
+     *
+     * For example, the following definition will create a dialog with:
+     * * a header consisting of an icon, a title and a "Close" button (it's added by default),
+     * * a content consisting of a view with a single paragraph,
+     * * a footer consisting of two buttons: "Yes" and "No".
+     *
+     * ```js
+     * // Create the view that will be used as the dialog's content.
+     * const textView = new View( locale );
+     *
+     * textView.setTemplate( {
+     * 	tag: 'div',
+     * 	attributes: {
+     * 		style: {
+     * 			padding: 'var(--ck-spacing-large)',
+     * 			whiteSpace: 'initial',
+     * 			width: '100%',
+     * 			maxWidth: '500px'
+     * 		},
+     * 		tabindex: -1
+     * 	},
+     * 	children: [
+     * 		'Lorem ipsum dolor sit amet...'
+     * 	]
+     * } );
+     *
+     * // Show the dialog.
+     * editor.plugins.get( 'Dialog' ).show( {
+     *	id: 'myDialog',
+     * 	icon: 'myIcon', // this should be an SVG string
+     * 	title: 'My dialog',
+     * 	content: textView,
+     * 	actionButtons: [
+     *		{
+     *			label: t( 'Yes' ),
+     *			class: 'ck-button-action',
+     *			withText: true,
+     *			onExecute: () => dialog.hide()
+     *		},
+     *		{
+     *			label: t( 'No' ),
+     *			withText: true,
+     *			onExecute: () => dialog.hide()
+     *		}
+     *	]
+     * } );
+     * ```
+     *
+     * By specifying the {@link ~DialogDefinition#onShow} and {@link ~DialogDefinition#onHide} callbacks
+     * it's also possible to add callbacks that will be called when the dialog is shown or hidden.
+     *
+     * For example, the callbacks in the following definition:
+     * * disable the default behavior of the `Esc` key,
+     * * fire a custom event when the dialog gets hidden.
+     *
+     * ```js
+     * editor.plugins.get( 'Dialog' ).show( {
+     * 	// ...
+     * 	onShow: dialog => {
+     * 		dialog.view.on( 'close', ( evt, data ) => {
+     * 			// Only prevent the event from `Esc` key - don't affect the other ways of closing the dialog.
+     * 			if ( data.source === 'escKeyPress' ) {
+     * 				evt.stop();
+     * 			}
+     * 		} );
+     * 	},
+     * 	onHide: dialog => {
+     * 		dialog.fire( 'dialogDestroyed' );
+     * 	}
+     * } );
+     * ```
+     *
+     * Internally, calling this method:
+     * 1. Hides the currently visible dialog (if any) calling the {@link #hide} method
+     * (fires the {@link ~DialogHideEvent hide event}).
+     * 2. Fires the {@link ~DialogShowEvent show event} which allows for adding callbacks that customize the
+     * behavior of the dialog.
+     * 3. Shows the dialog.
+     */
+    show(dialogDefinition) {
+        this.hide();
+        this.fire(`show:${dialogDefinition.id}`, dialogDefinition);
+    }
+    /**
+     * Handles creating the {@link module:ui/dialog/dialogview~DialogView} instance and making it visible.
+     */
+    _show({ id, icon, title, hasCloseButton = true, content, actionButtons, className, isModal, position, onHide }) {
+        const editor = this.editor;
+        this.view = new DialogView(editor.locale, {
+            getCurrentDomRoot: () => {
+                return editor.editing.view.getDomRoot(editor.model.document.selection.anchor.root.rootName);
+            },
+            getViewportOffset: () => {
+                return editor.ui.viewportOffset;
+            }
+        });
+        const view = this.view;
+        view.on('close', () => {
+            this.hide();
+        });
+        editor.ui.view.body.add(view);
+        editor.ui.focusTracker.add(view.element);
+        editor.keystrokes.listenTo(view.element);
+        // Unless the user specified a position, modals should always be centered on the screen.
+        // Otherwise, let's keep dialogs centered in the editing root by default.
+        if (!position) {
+            position = isModal ? DialogViewPosition.SCREEN_CENTER : DialogViewPosition.EDITOR_CENTER;
+        }
+        view.set({
+            position,
+            _isVisible: true,
+            className,
+            isModal
+        });
+        view.setupParts({
+            icon,
+            title,
+            hasCloseButton,
+            content,
+            actionButtons
+        });
+        this.id = id;
+        if (onHide) {
+            this._onHide = onHide;
+        }
+        this.isOpen = true;
+        Dialog._visibleDialogPlugin = this;
+    }
+    /**
+     * Hides the dialog. This method is decorated to enable interacting on the {@link ~DialogHideEvent hide event}.
+     *
+     * See {@link #show}.
+     */
+    hide() {
+        if (Dialog._visibleDialogPlugin) {
+            Dialog._visibleDialogPlugin.fire(`hide:${Dialog._visibleDialogPlugin.id}`);
+        }
+    }
+    /**
+     * Destroys the {@link module:ui/dialog/dialogview~DialogView} and cleans up the stored dialog state.
+     */
+    _hide() {
+        if (!this.view) {
+            return;
+        }
+        const editor = this.editor;
+        const view = this.view;
+        // Reset the content view to prevent its children from being destroyed in the standard
+        // View#destroy() (and collections) chain. If the content children were left in there,
+        // they would have to be re-created by the feature using the dialog every time the dialog
+        // shows up.
+        if (view.contentView) {
+            view.contentView.reset();
+        }
+        editor.ui.view.body.remove(view);
+        editor.ui.focusTracker.remove(view.element);
+        editor.keystrokes.stopListening(view.element);
+        view.destroy();
+        editor.editing.view.focus();
+        this.id = null;
+        this.isOpen = false;
+        Dialog._visibleDialogPlugin = null;
+    }
+}

package/src/dialog/dialogactionsview.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @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 ui/dialog/dialogactionsview
+ */
+import { KeystrokeHandler, type Locale } from '@ckeditor/ckeditor5-utils';
+import type { default as Button } from '../button/button.js';
+import ButtonView from '../button/buttonview.js';
+import View from '../view.js';
+import ViewCollection from '../viewcollection.js';
+import FocusCycler, { type FocusableView } from '../focuscycler.js';
+import '../../theme/components/dialog/dialogactions.css';
+/**
+ * A dialog actions view class. Contains button views which are used to execute dialog actions.
+ */
+export default class DialogActionsView extends View {
+    /**
+     * A collection of button views.
+     */
+    readonly children: ViewCollection<FocusableView>;
+    /**
+     * A keystroke handler instance.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * A focus cycler instance.
+     */
+    readonly focusCycler: FocusCycler;
+    /**
+     * A focus tracker instance.
+     */
+    private readonly _focusTracker;
+    /**
+     * A collection of focusable views.
+     */
+    private readonly _focusables;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Creates the button views based on the given definitions.
+     * Then adds them to the {@link #children} collection and to the focus cycler.
+     */
+    setButtons(definitions: Array<DialogActionButtonDefinition>): void;
+    /**
+     * @inheritDoc
+     */
+    focus(direction?: 1 | -1): void;
+    /**
+     * Add all elements from the {@link #children} collection to the {@link #_focusables} collection
+     * and to the {@link #_focusTracker} instance.
+     */
+    private _updateFocusCyclableItems;
+}
+/**
+ * A dialog action button definition. It's a slightly modified version
+ * of the {@link module:ui/button/button~Button} definition.
+ */
+export type DialogActionButtonDefinition = Pick<Button, 'label'> & Partial<Pick<Button, 'withText' | 'class' | 'icon'>> & {
+    onExecute: Function;
+    onCreate?: (button: ButtonView) => void;
+};

package/src/dialog/dialogactionsview.js

@@ -0,0 +1,98 @@
+/**
+ * @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 ui/dialog/dialogactionsview
+ */
+import { FocusTracker, KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
+import ButtonView from '../button/buttonview.js';
+import View from '../view.js';
+import ViewCollection from '../viewcollection.js';
+import FocusCycler from '../focuscycler.js';
+import '../../theme/components/dialog/dialogactions.css';
+/**
+ * A dialog actions view class. Contains button views which are used to execute dialog actions.
+ */
+export default class DialogActionsView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        this.children = this.createCollection();
+        this.keystrokes = new KeystrokeHandler();
+        this._focusTracker = new FocusTracker();
+        this._focusables = new ViewCollection();
+        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-dialog__actions'
+                ]
+            },
+            children: this.children
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * Creates the button views based on the given definitions.
+     * Then adds them to the {@link #children} collection and to the focus cycler.
+     */
+    setButtons(definitions) {
+        for (const definition of definitions) {
+            const button = new ButtonView(this.locale);
+            let property;
+            button.on('execute', () => definition.onExecute());
+            if (definition.onCreate) {
+                definition.onCreate(button);
+            }
+            for (property in definition) {
+                if (property != 'onExecute' && property != 'onCreate') {
+                    button.set(property, definition[property]);
+                }
+            }
+            this.children.add(button);
+        }
+        this._updateFocusCyclableItems();
+    }
+    /**
+     * @inheritDoc
+     */
+    focus(direction) {
+        if (direction === -1) {
+            this.focusCycler.focusLast();
+        }
+        else {
+            this.focusCycler.focusFirst();
+        }
+    }
+    /**
+     * Add all elements from the {@link #children} collection to the {@link #_focusables} collection
+     * and to the {@link #_focusTracker} instance.
+     */
+    _updateFocusCyclableItems() {
+        Array.from(this.children).forEach(v => {
+            this._focusables.add(v);
+            this._focusTracker.add(v.element);
+        });
+    }
+}

package/src/dialog/dialogcontentview.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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 ui/dialog/dialogcontentview
+ */
+import View from '../view.js';
+import type ViewCollection from '../viewcollection.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * A dialog content view class.
+ */
+export default class DialogContentView extends View {
+    /**
+     * A collection of content items.
+     */
+    readonly children: ViewCollection;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale | undefined);
+    /**
+     * Removes all the child views.
+     */
+    reset(): void;
+}

package/src/dialog/dialogcontentview.js

@@ -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
+ */
+/**
+ * @module ui/dialog/dialogcontentview
+ */
+import View from '../view.js';
+/**
+ * A dialog content view class.
+ */
+export default class DialogContentView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        this.children = this.createCollection();
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: ['ck', 'ck-dialog__content']
+            },
+            children: this.children
+        });
+    }
+    /**
+     * Removes all the child views.
+     */
+    reset() {
+        while (this.children.length) {
+            this.children.remove(0);
+        }
+    }
+}