@ckeditor/ckeditor5-ui 39.0.2 → 40.1.0

package/src/arialiveannouncer.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @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/arialiveannouncer
+ */
+import type { Editor } from '@ckeditor/ckeditor5-core';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import type ViewCollection from './viewcollection';
+import View from './view';
+import '../theme/components/arialiveannouncer/arialiveannouncer.css';
+/**
+ * The politeness level of an `aria-live` announcement.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions#Politeness_levels
+ */
+export declare enum AriaLiveAnnouncerPoliteness {
+    POLITE = "polite",
+    ASSERTIVE = "assertive"
+}
+/**
+ * An accessibility helper that manages all ARIA live regions associated with an editor instance. ARIA live regions announce changes
+ * to the state of the editor features.
+ *
+ * These announcements are consumed and propagated by screen readers and give users a better understanding of the current
+ * state of the editor.
+ *
+ * To announce a state change to an editor feature named `'Some feature'`, use the {@link #announce} method:
+ * ```ts
+ * editor.ui.ariaLiveAnnouncer.announce( 'Some feature', 'Text of an announcement.' );
+ * ```
+ */
+export default class AriaLiveAnnouncer {
+    /**
+     * The editor instance.
+     */
+    readonly editor: Editor;
+    /**
+     * The view that aggregates all `aria-live` regions.
+     */
+    view?: AriaLiveAnnouncerView;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * Sets an announcement text to an aria region associated with a specific editor feature. The text is then
+     * announced by a screen reader to the user.
+     *
+     * If the aria region of a given name does not exist, it will be created and can be re-used later. The name of the region
+     * groups announcements originating from a specific editor feature and does not get announced by a screen reader.
+     *
+     * Using multiple regions allows for many announcements to be emitted in a short period of time. Changes to ARIA-live announcements
+     * are captured by a screen reader and read out in the order they were emitted.
+     *
+     * The default announcement politeness level is `'polite'`.
+     *
+     * ```ts
+     * // Most screen readers will queue announcements from multiple aria-live regions and read them out in the order they were emitted.
+     * editor.ui.ariaLiveAnnouncer.announce( 'image', 'Image uploaded.' );
+     * editor.ui.ariaLiveAnnouncer.announce( 'network', 'Connection lost. Reconnecting.' );
+     * ```
+     */
+    announce(regionName: string, announcementText: string, politeness?: AriaLiveAnnouncerPoliteness): void;
+}
+/**
+ * The view that aggregates all `aria-live` regions.
+ */
+export declare class AriaLiveAnnouncerView extends View {
+    /**
+     * A collection of all views that represent individual `aria-live` regions.
+     */
+    readonly regionViews: ViewCollection<AriaLiveAnnouncerRegionView>;
+    constructor(locale: Locale);
+}
+/**
+ * The view that represents a single `aria-live` region (e.g. for a specific editor feature) and its text.
+ */
+export declare class AriaLiveAnnouncerRegionView extends View {
+    /**
+     * Current text of the region.
+     */
+    text: string;
+    /**
+     * Current politeness level of the region.
+     */
+    politeness: AriaLiveAnnouncerPoliteness;
+    /**
+     * A unique name of the region, usually associated with a specific editor feature or system.
+     */
+    regionName: string;
+    constructor(locale: Locale);
+}

package/src/arialiveannouncer.js

@@ -0,0 +1,113 @@
+/**
+ * @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
+ */
+import View from './view';
+import '../theme/components/arialiveannouncer/arialiveannouncer.css';
+/**
+ * The politeness level of an `aria-live` announcement.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions#Politeness_levels
+ */
+export var AriaLiveAnnouncerPoliteness;
+(function (AriaLiveAnnouncerPoliteness) {
+    AriaLiveAnnouncerPoliteness["POLITE"] = "polite";
+    AriaLiveAnnouncerPoliteness["ASSERTIVE"] = "assertive";
+})(AriaLiveAnnouncerPoliteness || (AriaLiveAnnouncerPoliteness = {}));
+/**
+ * An accessibility helper that manages all ARIA live regions associated with an editor instance. ARIA live regions announce changes
+ * to the state of the editor features.
+ *
+ * These announcements are consumed and propagated by screen readers and give users a better understanding of the current
+ * state of the editor.
+ *
+ * To announce a state change to an editor feature named `'Some feature'`, use the {@link #announce} method:
+ * ```ts
+ * editor.ui.ariaLiveAnnouncer.announce( 'Some feature', 'Text of an announcement.' );
+ * ```
+ */
+export default class AriaLiveAnnouncer {
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        this.editor = editor;
+    }
+    /**
+     * Sets an announcement text to an aria region associated with a specific editor feature. The text is then
+     * announced by a screen reader to the user.
+     *
+     * If the aria region of a given name does not exist, it will be created and can be re-used later. The name of the region
+     * groups announcements originating from a specific editor feature and does not get announced by a screen reader.
+     *
+     * Using multiple regions allows for many announcements to be emitted in a short period of time. Changes to ARIA-live announcements
+     * are captured by a screen reader and read out in the order they were emitted.
+     *
+     * The default announcement politeness level is `'polite'`.
+     *
+     * ```ts
+     * // Most screen readers will queue announcements from multiple aria-live regions and read them out in the order they were emitted.
+     * editor.ui.ariaLiveAnnouncer.announce( 'image', 'Image uploaded.' );
+     * editor.ui.ariaLiveAnnouncer.announce( 'network', 'Connection lost. Reconnecting.' );
+     * ```
+     */
+    announce(regionName, announcementText, politeness = AriaLiveAnnouncerPoliteness.POLITE) {
+        const editor = this.editor;
+        if (!this.view) {
+            this.view = new AriaLiveAnnouncerView(editor.locale);
+            editor.ui.view.body.add(this.view);
+        }
+        let regionView = this.view.regionViews.find(view => view.regionName === regionName);
+        if (!regionView) {
+            regionView = new AriaLiveAnnouncerRegionView(this.view.locale);
+            this.view.regionViews.add(regionView);
+        }
+        regionView.set({
+            regionName,
+            text: announcementText,
+            politeness
+        });
+    }
+}
+/**
+ * The view that aggregates all `aria-live` regions.
+ */
+export class AriaLiveAnnouncerView extends View {
+    constructor(locale) {
+        super(locale);
+        this.regionViews = this.createCollection();
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-aria-live-announcer'
+                ]
+            },
+            children: this.regionViews
+        });
+    }
+}
+/**
+ * The view that represents a single `aria-live` region (e.g. for a specific editor feature) and its text.
+ */
+export class AriaLiveAnnouncerRegionView extends View {
+    constructor(locale) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set('regionName', '');
+        this.set('text', '');
+        this.set('politeness', AriaLiveAnnouncerPoliteness.POLITE);
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                role: 'region',
+                'data-region': bind.to('regionName'),
+                'aria-live': bind.to('politeness')
+            },
+            children: [
+                { text: bind.to('text') }
+            ]
+        });
+    }
+}

package/src/autocomplete/autocompleteview.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @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/autocomplete/autocompleteview
+*/
+import { type PositioningFunction, type Locale } from '@ckeditor/ckeditor5-utils';
+import SearchTextView, { type SearchTextViewConfig } from '../search/text/searchtextview';
+import type SearchResultsView from '../search/searchresultsview';
+import type InputBase from '../input/inputbase';
+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,153 @@
+/**
+ * @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/autocomplete/autocompleteview
+*/
+import { getOptimalPosition, global, toUnit, Rect } from '@ckeditor/ckeditor5-utils';
+import SearchTextView from '../search/text/searchtextview';
+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 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;

package/src/button/button.d.ts

@@ -135,12 +135,6 @@ export default interface Button {
      * @observable
      */
     class: string | undefined;
-    /**
-     * (Optional) The ARIA property reflected by the `aria-checked` DOM attribute used by assistive technologies.
-     *
-     * @observable
-     */
-    ariaChecked?: boolean | undefined;
     /**
      * (Optional) The ARIA property reflected by the `aria-label` DOM attribute used by assistive technologies.
      *

package/src/button/buttonlabel.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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/button/buttonlabel
+*/
+import type View from '../view';
+/**
+ * The button label interface. Implemented by the {@link module:ui/button/buttonlabelview~ButtonLabelView}
+ * and any label view that can be used with the {@link module:ui/button/buttonview~ButtonView}.
+ */
+export default interface ButtonLabel extends View {
+    /**
+     * The `id` attribute of the button label. It is used for accessibility purposes
+     * to describe the button.
+     *
+     * @observable
+     */
+    id: string | undefined;
+    /**
+     * The `style` attribute of the button label. It allows customizing the presentation
+     * of the label.
+     *
+     * @observable
+     */
+    style: string | undefined;
+    /**
+     * The human-readable text of the label.
+     *
+     * @observable
+     */
+    text: string | undefined;
+}

package/src/button/buttonlabel.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/button/buttonlabelview.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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/button/buttonlabelview
+ */
+import View from '../view';
+import type ButtonLabel from './buttonlabel';
+/**
+ * A default implementation of the button view's label. It comes with a dynamic text support
+ * via {@link module:ui/button/buttonlabelview~ButtonLabelView#text} property.
+ */
+export default class ButtonLabelView extends View implements ButtonLabel {
+    /**
+     * @inheritDoc
+     */
+    id: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    style: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    text: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    constructor();
+}

package/src/button/buttonlabelview.js

@@ -0,0 +1,42 @@
+/**
+ * @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/button/buttonlabelview
+ */
+import View from '../view';
+/**
+ * A default implementation of the button view's label. It comes with a dynamic text support
+ * via {@link module:ui/button/buttonlabelview~ButtonLabelView#text} property.
+ */
+export default class ButtonLabelView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor() {
+        super();
+        this.set({
+            style: undefined,
+            text: undefined,
+            id: undefined
+        });
+        const bind = this.bindTemplate;
+        this.setTemplate({
+            tag: 'span',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-button__label'
+                ],
+                style: bind.to('style'),
+                id: bind.to('id')
+            },
+            children: [
+                {
+                    text: bind.to('text')
+                }
+            ]
+        });
+    }
+}

package/src/button/buttonview.d.ts

@@ -9,6 +9,7 @@ import View from '../view';
 import IconView from '../icon/iconview';
 import type ViewCollection from '../viewcollection';
 import type { default as Button } from './button';
+import type ButtonLabel from './buttonlabel';
 import { type Locale } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/button/button.css';
 /**
@@ -35,9 +36,12 @@ export default class ButtonView extends View<HTMLButtonElement> implements Butto
      */
     readonly children: ViewCollection;
     /**
-     * Label of the button view. It is configurable using the {@link #label label attribute}.
+     * Label of the button view. Its text is configurable using the {@link #label label attribute}.
+     *
+     * If not configured otherwise in the `constructor()`, by default the label is an instance
+     * of {@link module:ui/button/buttonlabelview~ButtonLabelView}.
      */
-    readonly labelView: View;
+    readonly labelView: ButtonLabel;
     /**
      * The icon view of the button. Will be added to {@link #children} when the
      * {@link #icon icon attribute} is defined.
@@ -113,10 +117,6 @@ export default class ButtonView extends View<HTMLButtonElement> implements Butto
      * @inheritDoc
      */
     role: string | undefined;
-    /**
-     * @inheritDoc
-     */
-    ariaChecked: boolean | undefined;
     /**
      * @inheritDoc
      */
@@ -139,9 +139,13 @@ export default class ButtonView extends View<HTMLButtonElement> implements Butto
      */
     private _focusDelayed;
     /**
-     * @inheritDoc
+     * Creates an instance of the button view class.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param labelView The instance of the button's label. If not provided, an instance of
+     * {@link module:ui/button/buttonlabelview~ButtonLabelView} is used.
      */
-    constructor(locale?: Locale);
+    constructor(locale?: Locale, labelView?: ButtonLabel);
     /**
      * @inheritDoc
      */
@@ -155,9 +159,9 @@ export default class ButtonView extends View<HTMLButtonElement> implements Butto
      */
     destroy(): void;
     /**
-     * Creates a label view instance and binds it with button attributes.
+     * Binds the label view instance it with button attributes.
      */
-    private _createLabelView;
+    private _setupLabelView;
     /**
      * Creates a view that displays a keystroke next to a {@link #labelView label }
      * and binds it with button attributes.