@ckeditor/ckeditor5-ui 41.3.1 → 41.4.0

package/dist/types/textarea/textareaview.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @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/textarea/textareaview
+ */
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import InputBase from '../input/inputbase.js';
+import '../../theme/components/input/input.css';
+import '../../theme/components/textarea/textarea.css';
+/**
+ * The textarea view class.
+ *
+ * ```ts
+ * const textareaView = new TextareaView();
+ *
+ * textareaView.minRows = 2;
+ * textareaView.maxRows = 10;
+ *
+ * textareaView.render();
+ *
+ * document.body.append( textareaView.element );
+ * ```
+ */
+export default class TextareaView extends InputBase<HTMLTextAreaElement> {
+    /**
+     * Specifies the visible height of a text area, in lines.
+     *
+     * @observable
+     * @default 2
+     */
+    minRows: number;
+    /**
+     * Specifies the maximum number of rows.
+     *
+     * @observable
+     * @default 5
+     */
+    maxRows: number;
+    /**
+     * Specifies the value of HTML attribute that indicates whether the user can resize the element.
+     *
+     * @observable
+     * @default 'none'
+    */
+    resize: 'both' | 'horizontal' | 'vertical' | 'none';
+    /**
+     * An internal property that stores the current height of the textarea. Used for the DOM binding.
+     *
+     * @observable
+     * @default null
+     * @internal
+     */
+    _height: number | null;
+    /**
+     * An instance of the resize observer used to detect when the view is visible or not and update
+     * its height if any changes that affect it were made while it was invisible.
+     *
+     * **Note:** Created in {@link #render}.
+     */
+    private _resizeObserver;
+    /**
+     * A flag that indicates whether the {@link #_updateAutoGrowHeight} method should be called when the view becomes
+     * visible again. See {@link #_resizeObserver}.
+     */
+    private _isUpdateAutoGrowHeightPending;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * @inheritDoc
+     */
+    reset(): void;
+    /**
+     * Updates the {@link #_height} of the view depending on {@link #minRows}, {@link #maxRows}, and the current content size.
+     *
+     * **Note**: This method overrides manual resize done by the user using a handle. It's a known bug.
+     */
+    private _updateAutoGrowHeight;
+    /**
+     * Validates the {@link #minRows} and {@link #maxRows} properties and warns in the console if the configuration is incorrect.
+     */
+    private _validateMinMaxRows;
+}
+/**
+ * Fired every time the layout of the {@link module:ui/textarea/textareaview~TextareaView} possibly changed as a result
+ * of the user input or the value change via {@link module:ui/textarea/textareaview~TextareaView#value}.
+ *
+ * @eventName ~TextareaView#update
+ */
+export type TextareaViewUpdateEvent = {
+    name: 'update';
+    args: [];
+};

package/dist/types/toolbar/balloon/balloontoolbar.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @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/toolbar/balloon/balloontoolbar
+ */
+import ContextualBalloon from '../../panel/balloon/contextualballoon.js';
+import ToolbarView from '../toolbarview.js';
+import { Plugin, type Editor } from '@ckeditor/ckeditor5-core';
+import { FocusTracker } from '@ckeditor/ckeditor5-utils';
+/**
+ * The contextual toolbar.
+ *
+ * It uses the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon plugin}.
+ */
+export default class BalloonToolbar extends Plugin {
+    /**
+     * The toolbar view displayed in the balloon.
+     */
+    readonly toolbarView: ToolbarView;
+    /**
+     * Tracks the focus of the {@link module:ui/editorui/editorui~EditorUI#getEditableElement editable element}
+     * and the {@link #toolbarView}. When both are blurred then the toolbar should hide.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * A cached and normalized `config.balloonToolbar` object.
+     */
+    private _balloonConfig;
+    /**
+     * An instance of the resize observer that allows to respond to changes in editable's geometry
+     * so the toolbar can stay within its boundaries (and group toolbar items that do not fit).
+     *
+     * **Note**: Used only when `shouldNotGroupWhenFull` was **not** set in the
+     * {@link module:core/editor/editorconfig~EditorConfig#balloonToolbar configuration}.
+     *
+     * **Note:** Created in {@link #init}.
+     */
+    private _resizeObserver;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private readonly _balloon;
+    /**
+     * Fires `_selectionChangeDebounced` event using `lodash#debounce`.
+     *
+     * This event is an internal plugin event which is fired 200 ms after model selection last change.
+     * This is to makes easy test debounced action without need to use `setTimeout`.
+     *
+     * This function is stored as a plugin property to make possible to cancel
+     * trailing debounced invocation on destroy.
+     */
+    private readonly _fireSelectionChangeDebounced;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "BalloonToolbar";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ContextualBalloon];
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates the toolbar view instance.
+     */
+    private _createToolbarView;
+    /**
+     * Shows the toolbar and attaches it to the selection.
+     *
+     * Fires {@link #event:show} event which can be stopped to prevent the toolbar from showing up.
+     *
+     * @param showForCollapsedSelection When set `true`, the toolbar will show despite collapsed selection in the
+     * editing view.
+     */
+    show(showForCollapsedSelection?: boolean): void;
+    /**
+     * Hides the toolbar.
+     */
+    hide(): void;
+    /**
+     * Returns positioning options for the {@link #_balloon}. They control the way balloon is attached
+     * to the selection.
+     */
+    private _getBalloonPositionData;
+    /**
+     * Updates the position of the {@link #_balloon} to make up for changes:
+     *
+     * * in the geometry of the selection it is attached to (e.g. the selection moved in the viewport or expanded or shrunk),
+     * * or the geometry of the balloon toolbar itself (e.g. the toolbar has grouped or ungrouped some items and it is shorter or longer).
+     */
+    private _updatePosition;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Returns toolbar positions for the given direction of the selection.
+     */
+    private _getBalloonPositions;
+}
+/**
+ * This event is fired just before the toolbar shows up. Stopping this event will prevent this.
+ *
+ * @eventName ~BalloonToolbar#show
+ */
+export type BalloonToolbarShowEvent = {
+    name: 'show';
+    args: [];
+};

package/dist/types/toolbar/block/blockbuttonview.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
+ */
+/**
+ * @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/toolbar/block/blockbuttonview
+ */
+import ButtonView from '../../button/buttonview.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../../theme/components/toolbar/blocktoolbar.css';
+/**
+ * The block button view class.
+ *
+ * This view represents a button attached next to block element where the selection is anchored.
+ *
+ * See {@link module:ui/toolbar/block/blocktoolbar~BlockToolbar}.
+ */
+export default class BlockButtonView extends ButtonView {
+    /**
+     * Top offset.
+     *
+     * @observable
+     */
+    top: number;
+    /**
+     * Left offset.
+     *
+     * @observable
+     */
+    left: number;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}

package/dist/types/toolbar/block/blocktoolbar.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @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/toolbar/block/blocktoolbar
+ */
+import { Plugin, type Editor } from '@ckeditor/ckeditor5-core';
+import BlockButtonView from './blockbuttonview.js';
+import BalloonPanelView from '../../panel/balloon/balloonpanelview.js';
+import ToolbarView from '../toolbarview.js';
+/**
+ * The block toolbar plugin.
+ *
+ * This plugin provides a button positioned next to the block of content where the selection is anchored.
+ * Upon clicking the button, a dropdown providing access to editor features shows up, as configured in
+ * {@link module:core/editor/editorconfig~EditorConfig#blockToolbar}.
+ *
+ * By default, the button is displayed next to all elements marked in {@link module:engine/model/schema~Schema}
+ * as `$block` for which the toolbar provides at least one option.
+ *
+ * By default, the button is attached so its right boundary is touching the
+ * {@link module:engine/view/editableelement~EditableElement}:
+ *
+ * ```
+ *  __ |
+ * |  ||  This is a block of content that the
+ *  ¯¯ |  button is attached to. This is a
+ *     |  block of content that the button is
+ *     |  attached to.
+ * ```
+ *
+ * The position of the button can be adjusted using the CSS `transform` property:
+ *
+ * ```css
+ * .ck-block-toolbar-button {
+ * 	transform: translateX( -10px );
+ * }
+ * ```
+ *
+ * ```
+ *  __   |
+ * |  |  |  This is a block of content that the
+ *  ¯¯   |  button is attached to. This is a
+ *       |  block of content that the button is
+ *       |  attached to.
+ * ```
+ *
+ * **Note**: If you plan to run the editor in a right–to–left (RTL) language, keep in mind the button
+ * will be attached to the **right** boundary of the editable area. In that case, make sure the
+ * CSS position adjustment works properly by adding the following styles:
+ *
+ * ```css
+ * .ck[dir="rtl"] .ck-block-toolbar-button {
+ * 	transform: translateX( 10px );
+ * }
+ * ```
+ */
+export default class BlockToolbar extends Plugin {
+    /**
+     * The toolbar view.
+     */
+    readonly toolbarView: ToolbarView;
+    /**
+     * The balloon panel view, containing the {@link #toolbarView}.
+     */
+    readonly panelView: BalloonPanelView;
+    /**
+     * The button view that opens the {@link #toolbarView}.
+     */
+    readonly buttonView: BlockButtonView;
+    /**
+     * An instance of the resize observer that allows to respond to changes in editable's geometry
+     * so the toolbar can stay within its boundaries (and group toolbar items that do not fit).
+     *
+     * **Note**: Used only when `shouldNotGroupWhenFull` was **not** set in the
+     * {@link module:core/editor/editorconfig~EditorConfig#blockToolbar configuration}.
+     */
+    private _resizeObserver;
+    /**
+     * A cached and normalized `config.blockToolbar` object.
+     */
+    private _blockToolbarConfig;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "BlockToolbar";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates the {@link #toolbarView}.
+     */
+    private _createToolbarView;
+    /**
+     * Creates the {@link #panelView}.
+     */
+    private _createPanelView;
+    /**
+     * Creates the {@link #buttonView}.
+     */
+    private _createButtonView;
+    /**
+     * Shows or hides the button.
+     * When all the conditions for displaying the button are matched, it shows the button. Hides otherwise.
+     */
+    private _updateButton;
+    /**
+     * Hides the button.
+     */
+    private _hideButton;
+    /**
+     * Shows the {@link #toolbarView} attached to the {@link #buttonView}.
+     * If the toolbar is already visible, then it simply repositions it.
+     */
+    private _showPanel;
+    /**
+     * Returns currently selected editable, based on the model selection.
+     */
+    private _getSelectedEditableElement;
+    /**
+     * Hides the {@link #toolbarView}.
+     *
+     * @param focusEditable When `true`, the editable will be focused after hiding the panel.
+     */
+    private _hidePanel;
+    /**
+     * Attaches the {@link #buttonView} to the target block of content.
+     *
+     * @param targetElement Target element.
+     */
+    private _attachButtonToElement;
+    /**
+     * Creates a resize observer that observes selected editable and resizes the toolbar panel accordingly.
+     */
+    private _setupToolbarResize;
+    /**
+     * Gets the {@link #toolbarView} max-width, based on given `editableElement` width plus the distance between the farthest
+     * edge of the {@link #buttonView} and the editable.
+     *
+     * @returns A maximum width that toolbar can have, in pixels.
+     */
+    private _getToolbarMaxWidth;
+}

package/dist/types/toolbar/normalizetoolbarconfig.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 type { ToolbarConfig, ToolbarConfigItem } from '@ckeditor/ckeditor5-core';
+/**
+ * @module ui/toolbar/normalizetoolbarconfig
+ */
+/**
+ * Normalizes the toolbar configuration (`config.toolbar`), which:
+ *
+ * * may be defined as an `Array`:
+ *
+ * ```
+ * toolbar: [ 'heading', 'bold', 'italic', 'link', ... ]
+ * ```
+ *
+ * * or an `Object`:
+ *
+ * ```
+ * toolbar: {
+ * 	items: [ 'heading', 'bold', 'italic', 'link', ... ],
+ * 	removeItems: [ 'bold' ],
+ * 	...
+ * }
+ * ```
+ *
+ * * or may not be defined at all (`undefined`)
+ *
+ * and returns it in the object form.
+ *
+ * @param config The value of `config.toolbar`.
+ * @returns A normalized toolbar config object.
+ */
+export default function normalizeToolbarConfig(config: ToolbarConfig | undefined): {
+    items: Array<ToolbarConfigItem>;
+    removeItems: Array<string>;
+    shouldNotGroupWhenFull?: boolean;
+    icon?: string;
+};

package/dist/types/toolbar/toolbarlinebreakview.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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/toolbar/toolbarlinebreakview
+ */
+import View from '../view.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The toolbar line break view class.
+ */
+export default class ToolbarLineBreakView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}

package/dist/types/toolbar/toolbarseparatorview.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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/toolbar/toolbarseparatorview
+ */
+import View from '../view.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The toolbar separator view class.
+ */
+export default class ToolbarSeparatorView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}