@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/textarea/textareaview.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @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/src/textarea/textareaview.js

@@ -0,0 +1,182 @@
+/**
+ * @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 { Rect, toUnit, getBorderWidths, global, CKEditorError, isVisible, ResizeObserver } 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 {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        /**
+         * A flag that indicates whether the {@link #_updateAutoGrowHeight} method should be called when the view becomes
+         * visible again. See {@link #_resizeObserver}.
+         */
+        this._isUpdateAutoGrowHeightPending = false;
+        const toPx = toUnit('px');
+        this.set('minRows', 2);
+        this.set('maxRows', 5);
+        this.set('_height', null);
+        this.set('resize', 'none');
+        this._resizeObserver = null;
+        this.on('change:minRows', this._validateMinMaxRows.bind(this));
+        this.on('change:maxRows', this._validateMinMaxRows.bind(this));
+        const bind = this.bindTemplate;
+        this.template.tag = 'textarea';
+        this.extendTemplate({
+            attributes: {
+                class: ['ck-textarea'],
+                style: {
+                    height: bind.to('_height', height => height ? toPx(height) : null),
+                    resize: bind.to('resize')
+                },
+                rows: bind.to('minRows')
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        let wasVisible = false;
+        this.on('input', () => {
+            this._updateAutoGrowHeight(true);
+            this.fire('update');
+        });
+        this.on('change:value', () => {
+            // The content needs to be updated by the browser after the value is changed. It takes a few ms.
+            global.window.requestAnimationFrame(() => {
+                if (!isVisible(this.element)) {
+                    this._isUpdateAutoGrowHeightPending = true;
+                    return;
+                }
+                this._updateAutoGrowHeight();
+                this.fire('update');
+            });
+        });
+        // It may occur that the Textarea size needs to be updated (e.g. because it's content was changed)
+        // when it is not visible or detached from DOM.
+        // In such case, we need to detect the moment when it becomes visible again and update its height then.
+        // We're using ResizeObserver for that as it is the most reliable way to detect when the element becomes visible.
+        // IntersectionObserver didn't work well with the absolute positioned containers.
+        this._resizeObserver = new ResizeObserver(this.element, evt => {
+            const isVisible = !!evt.contentRect.width && !!evt.contentRect.height;
+            if (!wasVisible && isVisible && this._isUpdateAutoGrowHeightPending) {
+                // We're wrapping the auto-grow logic in RAF because otherwise there is an error thrown
+                // by the browser about recursive calls to the ResizeObserver. It used to happen in unit
+                // tests only, though. Since there is no risk of infinite loop here, it can stay here.
+                global.window.requestAnimationFrame(() => {
+                    this._updateAutoGrowHeight();
+                    this.fire('update');
+                });
+            }
+            wasVisible = isVisible;
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        if (this._resizeObserver) {
+            this._resizeObserver.destroy();
+        }
+    }
+    /**
+     * @inheritDoc
+     */
+    reset() {
+        super.reset();
+        this._updateAutoGrowHeight();
+        this.fire('update');
+    }
+    /**
+     * 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.
+     */
+    _updateAutoGrowHeight(shouldScroll) {
+        const viewElement = this.element;
+        if (!viewElement.offsetParent) {
+            this._isUpdateAutoGrowHeightPending = true;
+            return;
+        }
+        this._isUpdateAutoGrowHeightPending = false;
+        const singleLineContentClone = getTextareaElementClone(viewElement, '1');
+        const fullTextValueClone = getTextareaElementClone(viewElement, viewElement.value);
+        const singleLineContentStyles = singleLineContentClone.ownerDocument.defaultView.getComputedStyle(singleLineContentClone);
+        const verticalPaddings = parseFloat(singleLineContentStyles.paddingTop) + parseFloat(singleLineContentStyles.paddingBottom);
+        const borders = getBorderWidths(singleLineContentClone);
+        const lineHeight = parseFloat(singleLineContentStyles.lineHeight);
+        const verticalBorder = borders.top + borders.bottom;
+        const singleLineAreaDefaultHeight = new Rect(singleLineContentClone).height;
+        const numberOfLines = Math.round((fullTextValueClone.scrollHeight - verticalPaddings) / lineHeight);
+        const maxHeight = this.maxRows * lineHeight + verticalPaddings + verticalBorder;
+        // There's a --ck-ui-component-min-height CSS custom property that enforces min height of the component.
+        // This min-height is relevant only when there's one line of text. Other than that, we can rely on line-height.
+        const minHeight = numberOfLines === 1 ? singleLineAreaDefaultHeight : this.minRows * lineHeight + verticalPaddings + verticalBorder;
+        // The size of textarea is controlled by height style instead of rows attribute because event though it is
+        // a more complex solution, it is immune to the layout textarea has been rendered in (gird, flex).
+        this._height = Math.min(Math.max(Math.max(numberOfLines, this.minRows) * lineHeight + verticalPaddings + verticalBorder, minHeight), maxHeight);
+        if (shouldScroll) {
+            viewElement.scrollTop = viewElement.scrollHeight;
+        }
+        singleLineContentClone.remove();
+        fullTextValueClone.remove();
+    }
+    /**
+     * Validates the {@link #minRows} and {@link #maxRows} properties and warns in the console if the configuration is incorrect.
+     */
+    _validateMinMaxRows() {
+        if (this.minRows > this.maxRows) {
+            /**
+             * The minimum number of rows is greater than the maximum number of rows.
+             *
+             * @error ui-textarea-view-min-rows-greater-than-max-rows
+             * @param textareaView The misconfigured textarea view instance.
+             * @param minRows The value of `minRows` property.
+             * @param maxRows The value of `maxRows` property.
+             */
+            throw new CKEditorError('ui-textarea-view-min-rows-greater-than-max-rows', {
+                textareaView: this,
+                minRows: this.minRows,
+                maxRows: this.maxRows
+            });
+        }
+    }
+}
+function getTextareaElementClone(element, value) {
+    const clone = element.cloneNode();
+    clone.style.position = 'absolute';
+    clone.style.top = '-99999px';
+    clone.style.left = '-99999px';
+    clone.style.height = 'auto';
+    clone.style.overflow = 'hidden';
+    clone.style.width = element.ownerDocument.defaultView.getComputedStyle(element).width;
+    clone.tabIndex = -1;
+    clone.rows = 1;
+    clone.value = value;
+    element.parentNode.insertBefore(clone, element);
+    return clone;
+}

package/src/toolbar/balloon/balloontoolbar.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @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 isOfficialPlugin(): true;
+    /**
+     * @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;
+    /**
+     * Add or remove editable elements to the focus tracker. It watches added and removed roots
+     * and adds or removes their editable elements to the focus tracker.
+     */
+    private _trackFocusableEditableElements;
+    /**
+     * 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: [];
+};