@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/autocomplete/autocompleteview.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @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/autocomplete/autocompleteview
+*/
+import { type PositioningFunction, type Locale } from '@ckeditor/ckeditor5-utils';
+import SearchTextView, { type SearchTextViewConfig } from '../search/text/searchtextview.js';
+import type SearchResultsView from '../search/searchresultsview.js';
+import type InputBase from '../input/inputbase.js';
+import '../../theme/components/autocomplete/autocomplete.css';
+/**
+ * The autocomplete component's view class. It extends the {@link module:ui/search/text/searchtextview~SearchTextView} class
+ * with a floating {@link #resultsView} that shows up when the user starts typing and hides when they blur
+ * the component.
+ */
+export default class AutocompleteView<TQueryFieldView extends InputBase<HTMLInputElement | HTMLTextAreaElement>> extends SearchTextView<TQueryFieldView> {
+    /**
+     * The configuration of the autocomplete view.
+     */
+    protected _config: AutocompleteViewConfig<TQueryFieldView>;
+    resultsView: AutocompleteResultsView;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, config: AutocompleteViewConfig<TQueryFieldView>);
+    /**
+     * Updates the position of the results view on demand.
+     */
+    private _updateResultsViewWidthAndPosition;
+    /**
+     * Updates the visibility of the results view on demand.
+     */
+    private _updateResultsVisibility;
+    /**
+     * Positions for the autocomplete results view. Two positions are defined by default:
+     * * `s` - below the search field,
+     * * `n` - above the search field.
+     */
+    static defaultResultsPositions: Array<PositioningFunction>;
+    /**
+     * A function used to calculate the optimal position for the dropdown panel.
+     */
+    private static _getOptimalPosition;
+}
+/**
+ * An interface describing additional properties of the floating search results view used by the autocomplete plugin.
+ */
+export interface AutocompleteResultsView extends SearchResultsView {
+    /**
+     * Controls the visibility of the results view.
+     *
+     * @observable
+     */
+    isVisible: boolean;
+    /**
+     * Controls the position (CSS class suffix) of the results view.
+     *
+     * @internal
+    */
+    _position?: string;
+    /**
+     * The observable property determining the CSS width of the results view.
+     *
+     * @internal
+     */
+    _width: number;
+}
+export interface AutocompleteViewConfig<TConfigInputCreator extends InputBase<HTMLInputElement | HTMLTextAreaElement>> extends SearchTextViewConfig<TConfigInputCreator> {
+    /**
+     * When set `true`, the query view will be reset when the autocomplete view loses focus.
+     */
+    resetOnBlur?: boolean;
+    /**
+     * Minimum number of characters that need to be typed before the search is performed.
+     *
+     * @default 0
+     */
+    queryMinChars?: number;
+}

package/src/autocomplete/autocompleteview.js

@@ -0,0 +1,154 @@
+/**
+ * @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/autocomplete/autocompleteview
+*/
+import { getOptimalPosition, global, toUnit, Rect } from '@ckeditor/ckeditor5-utils';
+import SearchTextView from '../search/text/searchtextview.js';
+import '../../theme/components/autocomplete/autocomplete.css';
+/**
+ * The autocomplete component's view class. It extends the {@link module:ui/search/text/searchtextview~SearchTextView} class
+ * with a floating {@link #resultsView} that shows up when the user starts typing and hides when they blur
+ * the component.
+ */
+class AutocompleteView extends SearchTextView {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale, config) {
+        super(locale, config);
+        this._config = config;
+        const toPx = toUnit('px');
+        this.extendTemplate({
+            attributes: {
+                class: ['ck-autocomplete']
+            }
+        });
+        const bindResultsView = this.resultsView.bindTemplate;
+        this.resultsView.set('isVisible', false);
+        this.resultsView.set('_position', 's');
+        this.resultsView.set('_width', 0);
+        this.resultsView.extendTemplate({
+            attributes: {
+                class: [
+                    bindResultsView.if('isVisible', 'ck-hidden', value => !value),
+                    bindResultsView.to('_position', value => `ck-search__results_${value}`)
+                ],
+                style: {
+                    width: bindResultsView.to('_width', toPx)
+                }
+            }
+        });
+        // Update the visibility of the results view when the user focuses or blurs the component.
+        // This is also integration for the `resetOnBlur` configuration.
+        this.focusTracker.on('change:isFocused', (evt, name, isFocused) => {
+            this._updateResultsVisibility();
+            if (isFocused) {
+                // Reset the scroll position of the results view whenever the autocomplete reopens.
+                this.resultsView.element.scrollTop = 0;
+            }
+            else if (config.resetOnBlur) {
+                this.queryView.reset();
+            }
+        });
+        // Update the visibility of the results view when the user types in the query field.
+        // This is an integration for `queryMinChars` configuration.
+        // This is an integration for search results changing length and the #resultsView requiring to be repositioned.
+        this.on('search', () => {
+            this._updateResultsVisibility();
+            this._updateResultsViewWidthAndPosition();
+        });
+        // Hide the results view when the user presses the ESC key.
+        this.keystrokes.set('esc', (evt, cancel) => {
+            // Let the DOM event pass through if the focus is in the query view.
+            if (!this.resultsView.isVisible) {
+                return;
+            }
+            // Focus the query view first and only then close the results view. Otherwise, if the focus
+            // was in the results view, it will get lost.
+            this.queryView.focus();
+            this.resultsView.isVisible = false;
+            cancel();
+        });
+        // Update the position of the results view when the user scrolls the page.
+        // TODO: This needs to be debounced down the road.
+        this.listenTo(global.document, 'scroll', () => {
+            this._updateResultsViewWidthAndPosition();
+        });
+        // Hide the results when the component becomes disabled.
+        this.on('change:isEnabled', () => {
+            this._updateResultsVisibility();
+        });
+        // Update the value of the query field when the user selects a result.
+        this.filteredView.on('execute', (evt, { value }) => {
+            // Focus the query view first to avoid losing the focus.
+            this.focus();
+            // Resetting the view will ensure that the #queryView will update its empty state correctly.
+            // This prevents bugs related to dynamic labels or auto-grow when re-setting the same value
+            // to #queryView.fieldView.value (which does not trigger empty state change) to an
+            // #queryView.fieldView.element that has been changed by the user.
+            this.reset();
+            // Update the value of the query field.
+            this.queryView.fieldView.value = this.queryView.fieldView.element.value = value;
+            // Finally, hide the results view. The focus has been moved earlier so this is safe.
+            this.resultsView.isVisible = false;
+        });
+        // Update the position and width of the results view when it becomes visible.
+        this.resultsView.on('change:isVisible', () => {
+            this._updateResultsViewWidthAndPosition();
+        });
+    }
+    /**
+     * Updates the position of the results view on demand.
+     */
+    _updateResultsViewWidthAndPosition() {
+        if (!this.resultsView.isVisible) {
+            return;
+        }
+        this.resultsView._width = new Rect(this.queryView.fieldView.element).width;
+        const optimalResultsPosition = AutocompleteView._getOptimalPosition({
+            element: this.resultsView.element,
+            target: this.queryView.element,
+            fitInViewport: true,
+            positions: AutocompleteView.defaultResultsPositions
+        });
+        // _getOptimalPosition will return null if there is no optimal position found (e.g. target is off the viewport).
+        this.resultsView._position = optimalResultsPosition ? optimalResultsPosition.name : 's';
+    }
+    /**
+     * Updates the visibility of the results view on demand.
+     */
+    _updateResultsVisibility() {
+        const queryMinChars = typeof this._config.queryMinChars === 'undefined' ? 0 : this._config.queryMinChars;
+        const queryLength = this.queryView.fieldView.element.value.length;
+        this.resultsView.isVisible = this.focusTracker.isFocused && this.isEnabled && queryLength >= queryMinChars;
+    }
+}
+/**
+ * Positions for the autocomplete results view. Two positions are defined by default:
+ * * `s` - below the search field,
+ * * `n` - above the search field.
+ */
+AutocompleteView.defaultResultsPositions = [
+    (fieldRect => {
+        return {
+            top: fieldRect.bottom,
+            left: fieldRect.left,
+            name: 's'
+        };
+    }),
+    ((fieldRect, resultsRect) => {
+        return {
+            top: fieldRect.top - resultsRect.height,
+            left: fieldRect.left,
+            name: 'n'
+        };
+    })
+];
+/**
+ * A function used to calculate the optimal position for the dropdown panel.
+ */
+AutocompleteView._getOptimalPosition = getOptimalPosition;
+export default AutocompleteView;

package/src/badge/badge.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @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/badge/badge
+ */
+import type { Editor } from '@ckeditor/ckeditor5-core';
+import type View from '../view.js';
+declare const Badge_base: {
+    new (): import("@ckeditor/ckeditor5-utils").DomEmitter;
+    prototype: import("@ckeditor/ckeditor5-utils").DomEmitter;
+};
+/**
+ * A helper that enables the badge feature in the editor and renders a custom view next to the bottom of the editable element
+ * (editor root, source editing area, etc.) when the editor is focused.
+ *
+ * @private
+ */
+export default abstract class Badge extends /* #__PURE__ */ Badge_base {
+    /**
+     * Editor instance the helper was created for.
+     */
+    protected readonly editor: Editor;
+    /**
+     * A reference to the balloon panel hosting and positioning the badge content.
+     */
+    private _balloonView;
+    /**
+     * A throttled version of the {@link #_showBalloon} method meant for frequent use to avoid performance loss.
+     */
+    private _showBalloonThrottled;
+    /**
+     * A reference to the last editable element (root, source editing area, etc.) focused by the user.
+     * Since the focus can move to other focusable elements in the UI, this reference allows positioning the balloon over the
+     * right element whether the user is typing or using the UI.
+     */
+    private _lastFocusedEditableElement;
+    /**
+     * An additional CSS class added to the `BalloonView`.
+     */
+    private readonly _balloonClass;
+    /**
+     * Creates a badge for a given editor. The feature is initialized on Editor#ready
+     * event.
+     */
+    protected constructor(editor: Editor, options?: {
+        balloonClass?: string;
+    });
+    /**
+     * Destroys the badge along with its view.
+     */
+    destroy(): void;
+    /**
+     * Enables badge label once the editor (ui) is ready.
+     */
+    protected _handleEditorReady(): void;
+    /**
+     * Returns normalized configuration for the badge.
+     */
+    protected _getNormalizedConfig(): BadgeConfig;
+    /**
+     * Creates the badge content.
+     */
+    protected abstract _createBadgeContent(): View<HTMLElement>;
+    /**
+     * Enables the badge feature.
+     */
+    protected abstract _isEnabled(): boolean;
+    /**
+     * Attempts to display the balloon with the badge view.
+     */
+    private _showBalloon;
+    /**
+     * Hides the badge balloon if already visible.
+     */
+    private _hideBalloon;
+    /**
+     * Creates an instance of the {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView balloon panel}
+     * with the badge view inside ready for positioning.
+     */
+    private _createBalloonView;
+    /**
+     * Returns the options for attaching the balloon to the focused editable element.
+     */
+    private _getBalloonAttachOptions;
+    /**
+     * Updates the {@link #_lastFocusedEditableElement} based on the state of the global focus tracker.
+     */
+    private _updateLastFocusedEditableElement;
+}
+/**
+ * The badge configuration options.
+ **/
+export interface BadgeConfig {
+    /**
+     * The position of the badge.
+     *
+     * * When `'inside'`, the badge will be displayed within the boundaries of the editing area.
+     * * When `'border'`, the basge will be displayed over the bottom border of the editing area.
+     *
+     * @default 'border'
+     */
+    position: 'inside' | 'border';
+    /**
+     * Allows choosing the side of the editing area where the badge will be displayed.
+     *
+     * **Note:** If {@link module:core/editor/editorconfig~EditorConfig#language `config.language`} is set to an RTL (right-to-left)
+     * language, the side switches to `'left'` by default.
+     *
+     * @default 'right'
+     */
+    side: 'left' | 'right';
+    /**
+     * The vertical distance the badge can be moved away from its default position.
+     *
+     * **Note:** If `position` is `'border'`, the offset is measured from the (vertical) center of the badge.
+     *
+     * @default 5
+     */
+    verticalOffset: number;
+    /**
+     * The horizontal distance between the side of the editing root and the nearest side of the badge.
+     *
+     * @default 5
+     */
+    horizontalOffset: number;
+}
+export {};

package/src/badge/badge.js

@@ -0,0 +1,218 @@
+/**
+ * @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 { Rect, DomEmitterMixin } from '@ckeditor/ckeditor5-utils';
+import BalloonPanelView from '../panel/balloon/balloonpanelview.js';
+import { throttle } from 'lodash-es';
+// ⚠ Note, whenever changing the threshold, make sure to update the docs/support/managing-ckeditor-logo.md docs
+// as this information is also mentioned there ⚠.
+const NARROW_ROOT_HEIGHT_THRESHOLD = 50;
+const NARROW_ROOT_WIDTH_THRESHOLD = 350;
+/**
+ * A helper that enables the badge feature in the editor and renders a custom view next to the bottom of the editable element
+ * (editor root, source editing area, etc.) when the editor is focused.
+ *
+ * @private
+ */
+export default class Badge extends /* #__PURE__ */ DomEmitterMixin() {
+    /**
+     * Creates a badge for a given editor. The feature is initialized on Editor#ready
+     * event.
+     */
+    constructor(editor, options = {}) {
+        super();
+        /**
+         * A reference to the balloon panel hosting and positioning the badge content.
+         */
+        this._balloonView = null;
+        /**
+         * A throttled version of the {@link #_showBalloon} method meant for frequent use to avoid performance loss.
+         */
+        this._showBalloonThrottled = throttle(() => this._showBalloon(), 50, { leading: true });
+        /**
+         * A reference to the last editable element (root, source editing area, etc.) focused by the user.
+         * Since the focus can move to other focusable elements in the UI, this reference allows positioning the balloon over the
+         * right element whether the user is typing or using the UI.
+         */
+        this._lastFocusedEditableElement = null;
+        this.editor = editor;
+        this._balloonClass = options.balloonClass;
+        editor.on('ready', () => this._handleEditorReady());
+    }
+    /**
+     * Destroys the badge along with its view.
+     */
+    destroy() {
+        const balloon = this._balloonView;
+        if (balloon) {
+            // Balloon gets destroyed by the body collection.
+            // The badge view gets destroyed by the balloon.
+            balloon.unpin();
+            this._balloonView = null;
+        }
+        this._showBalloonThrottled.cancel();
+        this.stopListening();
+    }
+    /**
+     * Enables badge label once the editor (ui) is ready.
+     */
+    _handleEditorReady() {
+        const editor = this.editor;
+        if (!this._isEnabled()) {
+            return;
+        }
+        // No view means no body collection to append the badge balloon to.
+        if (!editor.ui.view) {
+            return;
+        }
+        editor.ui.focusTracker.on('change:isFocused', (evt, data, isFocused) => {
+            this._updateLastFocusedEditableElement();
+            if (isFocused) {
+                this._showBalloon();
+            }
+            else {
+                this._hideBalloon();
+            }
+        });
+        editor.ui.focusTracker.on('change:focusedElement', (evt, data, focusedElement) => {
+            this._updateLastFocusedEditableElement();
+            if (focusedElement) {
+                this._showBalloon();
+            }
+        });
+        editor.ui.on('update', () => {
+            this._showBalloonThrottled();
+        });
+    }
+    /**
+     * Returns normalized configuration for the badge.
+     */
+    _getNormalizedConfig() {
+        return {
+            side: this.editor.locale.contentLanguageDirection === 'ltr' ? 'right' : 'left',
+            position: 'border',
+            verticalOffset: 0,
+            horizontalOffset: 5
+        };
+    }
+    /**
+     * Attempts to display the balloon with the badge view.
+     */
+    _showBalloon() {
+        const attachOptions = this._getBalloonAttachOptions();
+        if (!attachOptions) {
+            return;
+        }
+        if (!this._balloonView) {
+            this._balloonView = this._createBalloonView();
+        }
+        this._balloonView.pin(attachOptions);
+    }
+    /**
+     * Hides the badge balloon if already visible.
+     */
+    _hideBalloon() {
+        if (this._balloonView) {
+            this._balloonView.unpin();
+        }
+    }
+    /**
+     * Creates an instance of the {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView balloon panel}
+     * with the badge view inside ready for positioning.
+     */
+    _createBalloonView() {
+        const editor = this.editor;
+        const balloon = new BalloonPanelView();
+        const view = this._createBadgeContent();
+        balloon.content.add(view);
+        if (this._balloonClass) {
+            balloon.class = this._balloonClass;
+        }
+        editor.ui.view.body.add(balloon);
+        return balloon;
+    }
+    /**
+     * Returns the options for attaching the balloon to the focused editable element.
+     */
+    _getBalloonAttachOptions() {
+        if (!this._lastFocusedEditableElement) {
+            return null;
+        }
+        const badgeConfig = this._getNormalizedConfig();
+        const positioningFunction = badgeConfig.side === 'right' ?
+            getLowerRightCornerPosition(this._lastFocusedEditableElement, badgeConfig) :
+            getLowerLeftCornerPosition(this._lastFocusedEditableElement, badgeConfig);
+        return {
+            target: this._lastFocusedEditableElement,
+            positions: [positioningFunction]
+        };
+    }
+    /**
+     * Updates the {@link #_lastFocusedEditableElement} based on the state of the global focus tracker.
+     */
+    _updateLastFocusedEditableElement() {
+        const editor = this.editor;
+        const isFocused = editor.ui.focusTracker.isFocused;
+        const focusedElement = editor.ui.focusTracker.focusedElement;
+        if (!isFocused || !focusedElement) {
+            this._lastFocusedEditableElement = null;
+            return;
+        }
+        const editableEditorElements = Array.from(editor.ui.getEditableElementsNames()).map(name => {
+            return editor.ui.getEditableElement(name);
+        });
+        if (editableEditorElements.includes(focusedElement)) {
+            this._lastFocusedEditableElement = focusedElement;
+        }
+        else {
+            // If it's none of the editable element, then the focus is somewhere in the UI. Let's display the badge
+            // over the first element then.
+            this._lastFocusedEditableElement = editableEditorElements[0];
+        }
+    }
+}
+function getLowerRightCornerPosition(focusedEditableElement, config) {
+    return getLowerCornerPosition(focusedEditableElement, config, (rootRect, balloonRect) => {
+        return rootRect.left + rootRect.width - balloonRect.width - config.horizontalOffset;
+    });
+}
+function getLowerLeftCornerPosition(focusedEditableElement, config) {
+    return getLowerCornerPosition(focusedEditableElement, config, rootRect => rootRect.left + config.horizontalOffset);
+}
+function getLowerCornerPosition(focusedEditableElement, config, getBalloonLeft) {
+    return (visibleEditableElementRect, balloonRect) => {
+        const editableElementRect = new Rect(focusedEditableElement);
+        if (editableElementRect.width < NARROW_ROOT_WIDTH_THRESHOLD || editableElementRect.height < NARROW_ROOT_HEIGHT_THRESHOLD) {
+            return null;
+        }
+        let balloonTop;
+        if (config.position === 'inside') {
+            balloonTop = editableElementRect.bottom - balloonRect.height;
+        }
+        else {
+            balloonTop = editableElementRect.bottom - balloonRect.height / 2;
+        }
+        balloonTop -= config.verticalOffset;
+        const balloonLeft = getBalloonLeft(editableElementRect, balloonRect);
+        // Clone the editable element rect and place it where the balloon would be placed.
+        // This will allow getVisible() to work from editable element's perspective (rect source).
+        // and yield a result as if the balloon was on the same (scrollable) layer as the editable element.
+        const newBalloonPositionRect = visibleEditableElementRect
+            .clone()
+            .moveTo(balloonLeft, balloonTop)
+            .getIntersection(balloonRect.clone().moveTo(balloonLeft, balloonTop));
+        const newBalloonPositionVisibleRect = newBalloonPositionRect.getVisible();
+        if (!newBalloonPositionVisibleRect || newBalloonPositionVisibleRect.getArea() < balloonRect.getArea()) {
+            return null;
+        }
+        return {
+            top: balloonTop,
+            left: balloonLeft,
+            name: `position_${config.position}-side_${config.side}`,
+            config: {
+                withArrow: false
+            }
+        };
+    };
+}

package/src/bindings/addkeyboardhandlingforgrid.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/bindings/addkeyboardhandlingforgrid
+ */
+import type { FocusTracker, KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
+import type ViewCollection from '../viewcollection.js';
+/**
+ * A helper that adds a keyboard navigation support (arrow up/down/left/right) for grids.
+ *
+ * @param options Configuration options.
+ * @param options.keystrokeHandler Keystroke handler to register navigation with arrow keys.
+ * @param options.focusTracker A focus tracker for grid elements.
+ * @param options.gridItems A collection of grid items.
+ * @param options.numberOfColumns Number of columns in the grid. Can be specified as a function that returns
+ * the number (e.g. for responsive grids).
+ * @param options.uiLanguageDirection String of ui language direction.
+ */
+export default function addKeyboardHandlingForGrid({ keystrokeHandler, focusTracker, gridItems, numberOfColumns, uiLanguageDirection }: {
+    keystrokeHandler: KeystrokeHandler;
+    focusTracker: FocusTracker;
+    gridItems: ViewCollection;
+    numberOfColumns: number | (() => number);
+    uiLanguageDirection?: string;
+}): void;