@ckeditor/ckeditor5-ui 40.1.0 → 41.0.0

package/src/dialog/dialogview.d.ts

@@ -0,0 +1,256 @@
+/**
+ * @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 {@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.
+     * Dialog can have 3 optional parts: header, content and actions.
+     */
+    readonly parts: ViewCollection;
+    /**
+     * A header view of the dialog. It's also a drag handle of the dialog.
+     */
+    headerView?: FormHeaderView;
+    /**
+     * A close button view. It's 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
+     * won't be updated automatically upon window resize or document scroll.
+     */
+    wasMoved: boolean;
+    /**
+     * A flag indicating if this DialogView 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 dialog is transparent. It is used to prevent the dialog from being visible
+     * before its position is calculated.
+     *
+     * @observable
+     * @internal
+     */
+    _isTransparent: boolean;
+    /**
+     * The calculated `top` CSS dialog property used for positioning.
+     *
+     * @observable
+     * @internal
+     */
+    _top: number;
+    /**
+     * The calculated `left` CSS dialog property used for positioning.
+     *
+     * @observable
+     * @internal
+     */
+    _left: number;
+    /**
+     * Callback returning the DOM root that requested the dialog.
+     */
+    private _getCurrentDomRoot;
+    /**
+     * 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, i.e. 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;
+    /**
+     * Normalises 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's 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 a 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 {};