@ckeditor/ckeditor5-ui 39.0.1 → 40.0.0

package/src/search/searchresultsview.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/search/searchresultsview
+ */
+import View from '../view';
+import type ViewCollection from '../viewcollection';
+import { FocusTracker, type Locale } from '@ckeditor/ckeditor5-utils';
+import { default as FocusCycler, type FocusableView } from '../focuscycler';
+/**
+ * A sub-component of {@link module:ui/search/text/searchtextview~SearchTextView}. It hosts the filtered and the information views.
+ */
+export default class SearchResultsView extends View implements FocusableView {
+    /**
+     * Tracks information about the DOM focus in the view.
+     *
+     * @readonly
+     */
+    focusTracker: FocusTracker;
+    /**
+     * The collection of the child views inside of the list item {@link #element}.
+     *
+     * @readonly
+     */
+    children: ViewCollection;
+    /**
+     * Provides the focus management (keyboard navigation) in the view.
+     *
+     * @readonly
+     */
+    protected _focusCycler: FocusCycler;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the view.
+     */
+    focus(): void;
+    /**
+     * Focuses the first child view.
+     */
+    focusFirst(): void;
+    /**
+     * Focuses the last child view.
+     */
+    focusLast(): void;
+}

package/src/search/searchresultsview.js

@@ -0,0 +1,65 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/search/searchresultsview
+ */
+import View from '../view';
+import { FocusTracker } from '@ckeditor/ckeditor5-utils';
+import { default as FocusCycler } from '../focuscycler';
+/**
+ * A sub-component of {@link module:ui/search/text/searchtextview~SearchTextView}. It hosts the filtered and the information views.
+ */
+export default class SearchResultsView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        this.children = this.createCollection();
+        this.focusTracker = new FocusTracker();
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-search__results'
+                ],
+                tabindex: -1
+            },
+            children: this.children
+        });
+        this._focusCycler = new FocusCycler({
+            focusables: this.children,
+            focusTracker: this.focusTracker
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        for (const child of this.children) {
+            this.focusTracker.add(child.element);
+        }
+    }
+    /**
+     * Focuses the view.
+     */
+    focus() {
+        this._focusCycler.focusFirst();
+    }
+    /**
+     * Focuses the first child view.
+     */
+    focusFirst() {
+        this._focusCycler.focusFirst();
+    }
+    /**
+     * Focuses the last child view.
+     */
+    focusLast() {
+        this._focusCycler.focusLast();
+    }
+}

package/src/search/text/searchtextqueryview.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/search/text/searchtextqueryview
+ */
+import ButtonView from '../../button/buttonview';
+import IconView from '../../icon/iconview';
+import LabeledFieldView, { type LabeledFieldViewCreator } from '../../labeledfield/labeledfieldview';
+import type InputBase from '../../input/inputbase';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * A search input field for the {@link module:ui/search/text/searchtextview~SearchTextView} component.
+ *
+ * @internal
+ * @extends module:ui/labeledfield/labeledfieldview~LabeledFieldView
+ */
+export default class SearchTextQueryView<TQueryFieldView extends InputBase<HTMLInputElement | HTMLTextAreaElement>> extends LabeledFieldView<TQueryFieldView> {
+    /**
+     * The loupe icon displayed next to the {@link #fieldView}.
+     */
+    iconView?: IconView;
+    /**
+     * The button that clears and focuses the {@link #fieldView}.
+     */
+    resetButtonView?: ButtonView;
+    /**
+     * A reference to the view configuration.
+     */
+    private readonly _viewConfig;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, config: SearchTextQueryViewConfig<TQueryFieldView>);
+    /**
+     * Resets the search field to its default state.
+     */
+    reset(): void;
+}
+/**
+ * An event fired when the field is reset using the
+ * {@link module:ui/search/text/searchtextqueryview~SearchTextQueryView#resetButtonView}.
+ *
+ * @eventName ~SearchTextQueryView#reset
+ */
+export type SearchTextQueryViewResetEvent = {
+    name: 'reset';
+    args: [];
+};
+/**
+ * The configuration of the {@link module:ui/search/text/searchtextqueryview~SearchTextQueryView} view.
+ */
+export interface SearchTextQueryViewConfig<TConfigSearchField extends InputBase<HTMLInputElement | HTMLTextAreaElement>> {
+    /**
+     * The human-readable label of the search field.
+     */
+    label: string;
+    /**
+     * Determines whether the button that resets the search should be visible.
+     *
+     * @default true
+     */
+    showResetButton?: boolean;
+    /**
+     * Determines whether the loupe icon should be visible.
+     *
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * The function that creates the search field input view. By default, a plain
+     * {@link module:ui/inputtext/inputtextview~InputTextView} is used for this purpose.
+     */
+    creator?: LabeledFieldViewCreator<TConfigSearchField>;
+}

package/src/search/text/searchtextqueryview.js

@@ -0,0 +1,75 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/search/text/searchtextqueryview
+ */
+import ButtonView from '../../button/buttonview';
+import IconView from '../../icon/iconview';
+import LabeledFieldView from '../../labeledfield/labeledfieldview';
+import { createLabeledInputText } from '../../labeledfield/utils';
+import { icons } from '@ckeditor/ckeditor5-core';
+/**
+ * A search input field for the {@link module:ui/search/text/searchtextview~SearchTextView} component.
+ *
+ * @internal
+ * @extends module:ui/labeledfield/labeledfieldview~LabeledFieldView
+ */
+export default class SearchTextQueryView extends LabeledFieldView {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale, config) {
+        const t = locale.t;
+        const viewConfig = Object.assign({}, {
+            showResetButton: true,
+            showIcon: true,
+            creator: createLabeledInputText
+        }, config);
+        super(locale, viewConfig.creator);
+        this.label = config.label;
+        this._viewConfig = viewConfig;
+        if (this._viewConfig.showIcon) {
+            this.iconView = new IconView();
+            this.iconView.content = icons.loupe;
+            this.fieldWrapperChildren.add(this.iconView, 0);
+            this.extendTemplate({
+                attributes: {
+                    class: 'ck-search__query_with-icon'
+                }
+            });
+        }
+        if (this._viewConfig.showResetButton) {
+            this.resetButtonView = new ButtonView(locale);
+            this.resetButtonView.set({
+                label: t('Clear'),
+                icon: icons.cancel,
+                class: 'ck-search__reset',
+                isVisible: false,
+                tooltip: true
+            });
+            this.resetButtonView.on('execute', () => {
+                this.reset();
+                this.focus();
+                this.fire('reset');
+            });
+            this.resetButtonView.bind('isVisible').to(this.fieldView, 'isEmpty', isEmpty => !isEmpty);
+            this.fieldWrapperChildren.add(this.resetButtonView);
+            this.extendTemplate({
+                attributes: {
+                    class: 'ck-search__query_with-reset'
+                }
+            });
+        }
+    }
+    /**
+     * Resets the search field to its default state.
+     */
+    reset() {
+        this.fieldView.reset();
+        if (this._viewConfig.showResetButton) {
+            this.resetButtonView.isVisible = false;
+        }
+    }
+}

package/src/search/text/searchtextview.d.ts

@@ -0,0 +1,219 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/search/text/searchtextview
+*/
+import { FocusTracker, KeystrokeHandler, type Locale } from '@ckeditor/ckeditor5-utils';
+import View from '../../view';
+import { default as SearchTextQueryView, type SearchTextQueryViewConfig } from './searchtextqueryview';
+import SearchResultsView from '../searchresultsview';
+import FocusCycler from '../../focuscycler';
+import type FilteredView from '../filteredview';
+import type ViewCollection from '../../viewcollection';
+import type InputBase from '../../input/inputbase';
+import type InputTextView from '../../inputtext/inputtextview';
+import '../../../theme/components/search/search.css';
+/**
+ * A search component that allows filtering of an arbitrary view based on a search query
+ * specified by the user in a text field.
+ *
+ *```ts
+ * // This view must specify the `filter()` and `focus()` methods.
+ * const filteredView = ...;
+ *
+ * const searchView = new SearchTextView( locale, {
+ * 	searchFieldLabel: 'Search list items',
+ * 	filteredView
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ */
+export default class SearchTextView<TQueryFieldView extends InputBase<HTMLInputElement | HTMLTextAreaElement> = InputTextView> extends View {
+    /**
+     * Tracks information about the DOM focus in the view.
+     *
+     * @readonly
+     */
+    focusTracker: FocusTracker;
+    /**
+     * An instance of the keystroke handler managing user interaction and accessibility.
+     *
+     * @readonly
+     */
+    keystrokes: KeystrokeHandler;
+    /**
+     * A view hosting the {@link #filteredView} passed in the configuration and the {@link #infoView}.
+     */
+    resultsView: SearchResultsView;
+    /**
+     * The view that is filtered by the search query.
+     */
+    filteredView: FilteredView;
+    /**
+     * The view that displays the information about the search results.
+     */
+    infoView: View | undefined;
+    /**
+     * The view that allows the user to enter the search query.
+     */
+    queryView: SearchTextQueryView<TQueryFieldView>;
+    /**
+     * Controls whether the component is in read-only mode.
+     *
+     * @default true
+     * @observable
+     */
+    isEnabled: boolean;
+    /**
+     * The number of results found for the current search query. Updated upon the {@link #search} event.
+     *
+     * @default 0
+     * @observable
+     */
+    resultsCount: number;
+    /**
+     * The number of the items that can be searched in the {@link #filteredView}. Updated upon the {@link #search} event.
+     *
+     * @default 0
+     * @observable
+     */
+    totalItemsCount: number;
+    /**
+     * The collection of children of the view.
+     *
+     * @readonly
+     */
+    readonly children: ViewCollection;
+    /**
+     * The collection of focusable children of the view. Used by the focus management logic.
+     *
+     * @readonly
+     */
+    readonly focusableChildren: ViewCollection;
+    locale: Locale;
+    /**
+     * Provides the focus management (keyboard navigation) between {@link #queryView} and {@link #filteredView}.
+     *
+     * @readonly
+     */
+    focusCycler: FocusCycler;
+    /**
+     * The cached configuration object.
+     *
+     * @internal
+     */
+    protected _config: SearchTextViewConfig<TQueryFieldView>;
+    /**
+     * Creates an instance of the {@link module:ui/search/text/searchtextview~SearchTextView} class.
+     *
+     * @param locale The localization services instance.
+     * @param config Configuration of the view.
+     */
+    constructor(locale: Locale, config: SearchTextViewConfig<TQueryFieldView>);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the {@link #queryView}.
+     */
+    focus(): void;
+    /**
+     * Resets the component to its initial state.
+     */
+    reset(): void;
+    /**
+     * Searches the {@link #filteredView} for the given query.
+     *
+     * @internal
+     * @param query The search query string.
+     */
+    search(query: string): void;
+    /**
+     * Creates a search field view based on configured creator..
+     */
+    private _createSearchTextQueryView;
+    /**
+     * Initializes the default {@link #infoView} behavior with default text labels when no custom info view
+     * was specified in the view config.
+     */
+    private _enableDefaultInfoViewBehavior;
+}
+/**
+ * The configuration of the {@link module:ui/search/text/searchtextview~SearchTextView} class.
+ */
+export interface SearchTextViewConfig<TConfigSearchField extends InputBase<HTMLInputElement | HTMLTextAreaElement>> {
+    /**
+     * The configuration of the view's query field.
+     */
+    queryView: SearchTextQueryViewConfig<TConfigSearchField>;
+    /**
+     * The view that is filtered by the search query.
+     */
+    filteredView: FilteredView;
+    /**
+     * The view that displays the information about the search results.
+     */
+    infoView?: {
+        /**
+         * The view that displays the information about the search results. If not specified,
+         * {@link module:ui/search/searchinfoview~SearchInfoView} is used.
+         */
+        instance?: View;
+        /**
+         * The configuration of text labels displayed in the {@link #infoView} in different states
+         * of the search component.
+         *
+         * **Note**: This configuration is only used when the {@link #infoView} is **not** specified.
+         * In other cases, please use the {@link module:ui/search/searchview~SearchTextViewSearchEvent} to bring about
+         * your own info text logic.
+         */
+        text?: {
+            notFound?: {
+                primary: SearchTextViewDefaultInfoText;
+                secondary?: SearchTextViewDefaultInfoText;
+            };
+            noSearchableItems?: {
+                primary: SearchTextViewDefaultInfoText;
+                secondary?: SearchTextViewDefaultInfoText;
+            };
+        };
+    };
+    /**
+     * The custom CSS class name to be added to the search view element.
+     */
+    class?: string;
+}
+/**
+ * Describes value of a info text configuration in {@link module:ui/search/text/searchtextview~SearchTextViewConfig}.
+ * A string or a function that returns a string with the information about the search results.
+ */
+export type SearchTextViewDefaultInfoText = string | ((query: string, resultsCount: number, totalItemsCount: number) => string);
+/**
+ * An event fired when the search query changes fired by {@link module:ui/search/text/searchtextview~SearchTextView#search}.
+ *
+ * @eventName ~SearchTextView#search
+ */
+export type SearchTextViewSearchEvent = {
+    name: 'search';
+    args: [SearchTextViewSearchEventData];
+};
+export type SearchTextViewSearchEventData = {
+    /**
+     * The search query string.
+     */
+    query: string;
+    /**
+     * The number of results found for the current search query.
+     */
+    resultsCount: number;
+    /**
+     * The number of the items that can be searched.
+     */
+    totalItemsCount: number;
+};

package/src/search/text/searchtextview.js

@@ -0,0 +1,201 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/search/text/searchtextview
+*/
+import { FocusTracker, KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
+import View from '../../view';
+import { default as SearchTextQueryView } from './searchtextqueryview';
+import SearchInfoView from '../searchinfoview';
+import SearchResultsView from '../searchresultsview';
+import FocusCycler from '../../focuscycler';
+import { escapeRegExp } from 'lodash-es';
+import '../../../theme/components/search/search.css';
+/**
+ * A search component that allows filtering of an arbitrary view based on a search query
+ * specified by the user in a text field.
+ *
+ *```ts
+ * // This view must specify the `filter()` and `focus()` methods.
+ * const filteredView = ...;
+ *
+ * const searchView = new SearchTextView( locale, {
+ * 	searchFieldLabel: 'Search list items',
+ * 	filteredView
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ */
+export default class SearchTextView extends View {
+    /**
+     * Creates an instance of the {@link module:ui/search/text/searchtextview~SearchTextView} class.
+     *
+     * @param locale The localization services instance.
+     * @param config Configuration of the view.
+     */
+    constructor(locale, config) {
+        super(locale);
+        this._config = config;
+        this.filteredView = config.filteredView;
+        this.queryView = this._createSearchTextQueryView();
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        this.resultsView = new SearchResultsView(locale);
+        this.children = this.createCollection();
+        this.focusableChildren = this.createCollection([this.queryView, this.resultsView]);
+        this.set('isEnabled', true);
+        this.set('resultsCount', 0);
+        this.set('totalItemsCount', 0);
+        if (config.infoView && config.infoView.instance) {
+            this.infoView = config.infoView.instance;
+        }
+        else {
+            this.infoView = new SearchInfoView();
+            this._enableDefaultInfoViewBehavior();
+            this.on('render', () => {
+                // Initial search that determines if there are any searchable items
+                // and displays the corresponding info text.
+                this.search('');
+            });
+        }
+        this.resultsView.children.addMany([this.infoView, this.filteredView]);
+        this.focusCycler = new FocusCycler({
+            focusables: this.focusableChildren,
+            focusTracker: this.focusTracker,
+            keystrokeHandler: this.keystrokes,
+            actions: {
+                // Navigate form fields backwards using the Shift + Tab keystroke.
+                focusPrevious: 'shift + tab',
+                // Navigate form fields forwards using the Tab key.
+                focusNext: 'tab'
+            }
+        });
+        this.on('search', (evt, { resultsCount, totalItemsCount }) => {
+            this.resultsCount = resultsCount;
+            this.totalItemsCount = totalItemsCount;
+        });
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-search',
+                    config.class || null
+                ],
+                tabindex: '-1'
+            },
+            children: this.children
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.children.addMany([
+            this.queryView,
+            this.resultsView
+        ]);
+        const stopPropagation = (data) => data.stopPropagation();
+        for (const focusableChild of this.focusableChildren) {
+            this.focusTracker.add(focusableChild.element);
+        }
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+        // Since the form is in the dropdown panel which is a child of the toolbar, the toolbar's
+        // keystroke handler would take over the key management in the URL input. We need to prevent
+        // this ASAP. Otherwise, the basic caret movement using the arrow keys will be impossible.
+        this.keystrokes.set('arrowright', stopPropagation);
+        this.keystrokes.set('arrowleft', stopPropagation);
+        this.keystrokes.set('arrowup', stopPropagation);
+        this.keystrokes.set('arrowdown', stopPropagation);
+    }
+    /**
+     * Focuses the {@link #queryView}.
+     */
+    focus() {
+        this.queryView.focus();
+    }
+    /**
+     * Resets the component to its initial state.
+     */
+    reset() {
+        this.queryView.reset();
+        this.search('');
+    }
+    /**
+     * Searches the {@link #filteredView} for the given query.
+     *
+     * @internal
+     * @param query The search query string.
+     */
+    search(query) {
+        const regExp = query ? new RegExp(escapeRegExp(query), 'ig') : null;
+        const filteringResults = this.filteredView.filter(regExp);
+        this.fire('search', { query, ...filteringResults });
+    }
+    /**
+     * Creates a search field view based on configured creator..
+     */
+    _createSearchTextQueryView() {
+        const queryView = new SearchTextQueryView(this.locale, this._config.queryView);
+        this.listenTo(queryView.fieldView, 'input', () => {
+            this.search(queryView.fieldView.element.value);
+        });
+        queryView.on('reset', () => this.reset());
+        queryView.bind('isEnabled').to(this);
+        return queryView;
+    }
+    /**
+     * Initializes the default {@link #infoView} behavior with default text labels when no custom info view
+     * was specified in the view config.
+     */
+    _enableDefaultInfoViewBehavior() {
+        const t = this.locale.t;
+        const infoView = this.infoView;
+        this.on('search', (evt, data) => {
+            if (!data.resultsCount) {
+                const defaultTextConfig = this._config.infoView && this._config.infoView.text;
+                let primaryText, secondaryText;
+                if (data.totalItemsCount) {
+                    if (defaultTextConfig && defaultTextConfig.notFound) {
+                        primaryText = defaultTextConfig.notFound.primary;
+                        secondaryText = defaultTextConfig.notFound.secondary;
+                    }
+                    else {
+                        primaryText = t('No results found');
+                        secondaryText = '';
+                    }
+                }
+                else {
+                    if (defaultTextConfig && defaultTextConfig.noSearchableItems) {
+                        primaryText = defaultTextConfig.noSearchableItems.primary;
+                        secondaryText = defaultTextConfig.noSearchableItems.secondary;
+                    }
+                    else {
+                        primaryText = t('No searchable items');
+                        secondaryText = '';
+                    }
+                }
+                infoView.set({
+                    primaryText: normalizeInfoText(primaryText, data),
+                    secondaryText: normalizeInfoText(secondaryText, data),
+                    isVisible: true
+                });
+            }
+            else {
+                infoView.set({
+                    isVisible: false
+                });
+            }
+        });
+        function normalizeInfoText(text, { query, resultsCount, totalItemsCount }) {
+            return typeof text === 'function' ? text(query, resultsCount, totalItemsCount) : text;
+        }
+    }
+}