@ckeditor/ckeditor5-ui 41.3.1 → 41.4.0

package/dist/types/dialog/dialogactionsview.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @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 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. It 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;
+    /**
+     * Adds 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 is 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/dist/types/dialog/dialogcontentview.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
+ */
+/**
+ * @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/dist/types/dialog/dialogview.d.ts

@@ -0,0 +1,260 @@
+/**
+ * @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 ui/dialog/dialogview
+ */
+import { KeystrokeHandler, FocusTracker, type Locale, type DecoratedMethodEvent } from '@ckeditor/ckeditor5-utils';
+import ViewCollection from '../viewcollection.js';
+import View from '../view.js';
+import FormHeaderView from '../formheader/formheaderview.js';
+import ButtonView from '../button/buttonview.js';
+import { type DraggableView } from '../bindings/draggableviewmixin.js';
+import DialogActionsView, { type DialogActionButtonDefinition } from './dialogactionsview.js';
+import DialogContentView from './dialogcontentview.js';
+import type EditorUI from '../editorui/editorui.js';
+import '../../theme/components/dialog/dialog.css';
+/**
+ * Available dialog view positions:
+ *
+ * * `DialogViewPosition.SCREEN_CENTER` – A fixed position in the center of the screen.
+ * * `DialogViewPosition.EDITOR_CENTER` – A dynamic position in the center of the editor editable area.
+ * * `DialogViewPosition.EDITOR_TOP_SIDE` – A dynamic position at the top-right (for the left-to-right languages)
+ * or top-left (for right-to-left languages) corner of the editor editable area.
+ * * `DialogViewPosition.EDITOR_TOP_CENTER` – A dynamic position at the top-center of the editor editable area.
+ * * `DialogViewPosition.EDITOR_BOTTOM_CENTER` – A dynamic position at the bottom-center of the editor editable area.
+ * * `DialogViewPosition.EDITOR_ABOVE_CENTER` – A dynamic position centered above the editor editable area.
+ * * `DialogViewPosition.EDITOR_BELOW_CENTER` – A dynamic position centered below the editor editable area.
+ *
+ * The position of a dialog is specified by a {@link module:ui/dialog/dialog~DialogDefinition#position `position` property} of a
+ * definition passed to the {@link module:ui/dialog/dialog~Dialog#show} method.
+ */
+export declare const DialogViewPosition: {
+    readonly SCREEN_CENTER: "screen-center";
+    readonly EDITOR_CENTER: "editor-center";
+    readonly EDITOR_TOP_SIDE: "editor-top-side";
+    readonly EDITOR_TOP_CENTER: "editor-top-center";
+    readonly EDITOR_BOTTOM_CENTER: "editor-bottom-center";
+    readonly EDITOR_ABOVE_CENTER: "editor-above-center";
+    readonly EDITOR_BELOW_CENTER: "editor-below-center";
+};
+declare const DialogView_base: import("@ckeditor/ckeditor5-utils").Mixed<typeof View, DraggableView>;
+/**
+ * A dialog view class.
+ */
+export default class DialogView extends DialogView_base implements DraggableView {
+    /**
+     * A collection of the child views inside of the dialog.
+     * A dialog can have 3 optional parts: header, content, and actions.
+     */
+    readonly parts: ViewCollection;
+    /**
+     * A header view of the dialog. It is also a drag handle of the dialog.
+     */
+    headerView?: FormHeaderView;
+    /**
+     * A close button view. It is automatically added to the header view if present.
+     */
+    closeButtonView?: ButtonView;
+    /**
+     * A view with the action buttons available to the user.
+     */
+    actionsView?: DialogActionsView;
+    /**
+     * A default dialog element offset from the reference element (e.g. editor editable area).
+     */
+    static defaultOffset: number;
+    /**
+     * A view with the dialog content.
+     */
+    contentView?: DialogContentView;
+    /**
+     * A keystroke handler instance.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * A focus tracker instance.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * A flag indicating if the dialog was moved manually. If so, its position
+     * will not be updated automatically upon window resize or document scroll.
+     */
+    wasMoved: boolean;
+    /**
+     * A flag indicating if this dialog view is a modal.
+     *
+     * @observable
+     */
+    isModal: boolean;
+    /**
+     * A label for the view dialog element to be used by the assistive technologies.
+     *
+     * @observable
+     */
+    ariaLabel: string;
+    /**
+     * A custom class name to be added to the dialog element.
+     *
+     * @observable
+     */
+    className: string | undefined;
+    /**
+     * The position of the dialog view.
+     *
+     * @observable
+     */
+    position: typeof DialogViewPosition[keyof typeof DialogViewPosition];
+    /**
+     * A flag indicating that the dialog should be shown. Once set to `true`, the dialog will be shown
+     * after its position is calculated. Until then, the dialog is transparent and not visible.
+     *
+     * See {@link #_isTransparent} property.
+     *
+     * @observable
+     * @internal
+     */
+    _isVisible: boolean;
+    /**
+     * A flag indicating if a dialog is transparent. It is used to prevent the dialog from being visible
+     * before its position is calculated.
+     *
+     * @observable
+     * @internal
+     */
+    _isTransparent: boolean;
+    /**
+     * The calculated dialog `top` CSS property used for positioning.
+     *
+     * @observable
+     * @internal
+     */
+    _top: number;
+    /**
+     * The calculated dialog `left` CSS property used for positioning.
+     *
+     * @observable
+     * @internal
+     */
+    _left: number;
+    /**
+     * A callback returning the DOM root that requested the dialog.
+     */
+    private _getCurrentDomRoot;
+    /**
+     * A callback returning the configured editor viewport offset.
+     */
+    private _getViewportOffset;
+    /**
+     * The list of the focusable elements inside the dialog view.
+     */
+    private readonly _focusables;
+    /**
+     * The focus cycler instance.
+     */
+    private readonly _focusCycler;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, { getCurrentDomRoot, getViewportOffset }: {
+        getCurrentDomRoot: () => HTMLElement;
+        getViewportOffset: () => EditorUI['viewportOffset'];
+    });
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Returns the element that should be used as a drag handle.
+     */
+    get dragHandleElement(): HTMLElement | null;
+    /**
+     * Creates the dialog parts. Which of them are created depends on the arguments passed to the method.
+     * There are no rules regarding the dialog construction, that is, no part is mandatory.
+     * Each part can only be created once.
+     *
+     * @internal
+     */
+    setupParts({ icon, title, hasCloseButton, content, actionButtons }: {
+        icon?: string;
+        title?: string;
+        hasCloseButton?: boolean;
+        content?: View | Array<View>;
+        actionButtons?: Array<DialogActionButtonDefinition>;
+    }): void;
+    /**
+     * Focuses the first focusable element inside the dialog.
+     */
+    focus(): void;
+    /**
+     * Normalizes the passed coordinates to make sure the dialog view
+     * is displayed within the visible viewport and moves it there.
+     *
+     * @internal
+     */
+    moveTo(left: number, top: number): void;
+    /**
+     * Moves the dialog to the specified coordinates.
+     */
+    private _moveTo;
+    /**
+     * Moves the dialog by the specified offset.
+     *
+     * @internal
+     */
+    moveBy(left: number, top: number): void;
+    /**
+     * Moves the dialog view to the off-screen position.
+     * Used when there is no space to display the dialog.
+     */
+    private _moveOffScreen;
+    /**
+     * Recalculates the dialog according to the set position and viewport,
+     * and moves it to the new position.
+     */
+    updatePosition(): void;
+    /**
+     * Calculates the visible DOM root part.
+     */
+    private _getVisibleDomRootRect;
+    /**
+     * Calculates the dialog element rect.
+     */
+    private _getDialogRect;
+    /**
+     * Calculates the viewport rect.
+     */
+    private _getViewportRect;
+    /**
+     * Collects all focusable elements inside the dialog parts
+     * and adds them to the focus tracker and focus cycler.
+     */
+    private _updateFocusCyclableItems;
+    /**
+     * Creates the close button view that is displayed in the header view corner.
+     */
+    private _createCloseButton;
+}
+/**
+ * An event fired when the dialog is closed.
+ *
+ * @eventName ~DialogView#close
+ */
+export type DialogViewCloseEvent = {
+    name: 'close';
+    args: [{
+        source: 'closeButton' | 'escKeyPress';
+    }];
+};
+/**
+ * An event fired when the dialog is moved.
+ *
+ * @eventName ~DialogView#moveTo
+ */
+export type DialogViewMoveToEvent = DecoratedMethodEvent<DialogView, 'moveTo'>;
+export {};

package/dist/types/dropdown/button/dropdownbutton.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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 ui/dropdown/button/dropdownbutton
+ */
+import type Button from '../../button/button.js';
+import type ViewCollection from '../../viewcollection.js';
+/**
+ * The dropdown button interface.
+ */
+export default interface DropdownButton extends Button {
+    children: ViewCollection;
+}
+/**
+ * Fired when the dropdown should be opened.
+ * It will not be fired when the button {@link module:ui/dropdown/button/dropdownbutton~DropdownButton#isEnabled is disabled}.
+ *
+ * @eventName ~DropdownButton#open
+ */
+export type DropdownButtonOpenEvent = {
+    name: 'open';
+    args: [];
+};

package/dist/types/dropdown/button/dropdownbuttonview.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @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 ui/dropdown/button/dropdownbuttonview
+ */
+import ButtonView from '../../button/buttonview.js';
+import type DropdownButton from './dropdownbutton.js';
+import IconView from '../../icon/iconview.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The default dropdown button view class.
+ *
+ * ```ts
+ * const view = new DropdownButtonView();
+ *
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ *
+ * Also see the {@link module:ui/dropdown/utils~createDropdown `createDropdown()` util}.
+ */
+export default class DropdownButtonView extends ButtonView implements DropdownButton {
+    /**
+     * An icon that displays arrow to indicate a dropdown button.
+     */
+    readonly arrowView: IconView;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Creates a {@link module:ui/icon/iconview~IconView} instance as {@link #arrowView}.
+     */
+    private _createArrowView;
+}

package/dist/types/dropdown/button/splitbuttonview.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @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 ui/dropdown/button/splitbuttonview
+ */
+import View from '../../view.js';
+import ButtonView from '../../button/buttonview.js';
+import type ViewCollection from '../../viewcollection.js';
+import type Button from '../../button/button.js';
+import type DropdownButton from './dropdownbutton.js';
+import type { FocusableView } from '../../focuscycler.js';
+import { KeystrokeHandler, FocusTracker, type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../../theme/components/dropdown/splitbutton.css';
+/**
+ * The split button view class.
+ *
+ * ```ts
+ * const view = new SplitButtonView();
+ *
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ *
+ * Also see the {@link module:ui/dropdown/utils~createDropdown `createDropdown()` util}.
+ */
+export default class SplitButtonView extends View<HTMLDivElement> implements DropdownButton {
+    /**
+     * Collection of the child views inside of the split button {@link #element}.
+     */
+    readonly children: ViewCollection;
+    /**
+     * A main button of split button.
+     */
+    readonly actionView: ButtonView;
+    /**
+     * A secondary button of split button that opens dropdown.
+     */
+    readonly arrowView: ButtonView;
+    /**
+     * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}. It manages
+     * keystrokes of the split button:
+     *
+     * * <kbd>▶</kbd> moves focus to arrow view when action view is focused,
+     * * <kbd>◀</kbd> moves focus to action view when arrow view is focused.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Tracks information about DOM focus in the dropdown.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * @inheritDoc
+     */
+    label: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    keystroke: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    tooltip: Button['tooltip'];
+    /**
+     * @inheritDoc
+     */
+    tooltipPosition: Button['tooltipPosition'];
+    /**
+     * @inheritDoc
+     */
+    type: Button['type'];
+    /**
+     * @inheritDoc
+     */
+    isOn: boolean;
+    /**
+     * @inheritDoc
+     */
+    isEnabled: boolean;
+    /**
+     * @inheritDoc
+     */
+    isVisible: boolean;
+    /**
+     * @inheritDoc
+     */
+    isToggleable: boolean;
+    /**
+     * @inheritDoc
+     */
+    withText: boolean;
+    /**
+     * @inheritDoc
+     */
+    withKeystroke: boolean;
+    /**
+     * @inheritDoc
+     */
+    icon: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    tabindex: number;
+    /**
+     * @inheritDoc
+     */
+    class: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    labelStyle: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    role: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaChecked: boolean | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaLabel?: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaLabelledBy: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale, actionButton?: ButtonView & FocusableView);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the {@link module:ui/button/buttonview~ButtonView#element} of the action part of split button.
+     */
+    focus(): void;
+    /**
+     * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #actionView} and binds it with main split button
+     * attributes.
+     */
+    private _createActionView;
+    /**
+     * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #arrowView} and binds it with main split button
+     * attributes.
+     */
+    private _createArrowView;
+}

package/dist/types/dropdown/dropdownpanelfocusable.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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 ui/dropdown/dropdownpanelfocusable
+ */
+/**
+ * The dropdown panel interface for focusable contents. It provides two methods for managing focus of the contents
+ * of dropdown's panel.
+ */
+export default interface DropdownPanelFocusable {
+    /**
+     * Focuses the view element or first item in view collection on opening dropdown's panel.
+     */
+    focus(): void;
+    /**
+     * Focuses the view element or last item in view collection on opening dropdown's panel.
+     */
+    focusLast(): void;
+}