@ckeditor/ckeditor5-ui 40.0.0 → 40.2.0

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/augmentation.d.ts

@@ -1,86 +1,86 @@
-/**
- * @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 type { BalloonToolbar, BlockToolbar, ContextualBalloon, Notification } from './index';
-import type { ToolbarConfig } from '@ckeditor/ckeditor5-core';
-declare module '@ckeditor/ckeditor5-core' {
-    interface EditorConfig {
-        /**
-         * Contextual toolbar configuration. Used by the {@link module:ui/toolbar/balloon/balloontoolbar~BalloonToolbar}
-         * feature.
-         *
-         * ## Configuring toolbar items
-         *
-         * ```ts
-         * const config = {
-         * 	balloonToolbar: [ 'bold', 'italic', 'undo', 'redo' ]
-         * };
-         * ```
-         *
-         * You can also use `'|'` to create a separator between groups of items:
-         *
-         * ```ts
-         * const config = {
-         * 	balloonToolbar: [ 'bold', 'italic', '|', 'undo', 'redo' ]
-         * };
-         * ```
-         *
-         * Read also about configuring the main editor toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
-         *
-         * ## Configuring items grouping
-         *
-         * You can prevent automatic items grouping by setting the `shouldNotGroupWhenFull` option:
-         *
-         * ```ts
-         * const config = {
-         * 	balloonToolbar: {
-         * 		items: [ 'bold', 'italic', 'undo', 'redo' ],
-         * 		shouldNotGroupWhenFull: true
-         * 	},
-         * };
-         * ```
-         */
-        balloonToolbar?: ToolbarConfig;
-        /**
-         * The block toolbar configuration. Used by the {@link module:ui/toolbar/block/blocktoolbar~BlockToolbar}
-         * feature.
-         *
-         * ```ts
-         * const config = {
-         * 	blockToolbar: [ 'paragraph', 'heading1', 'heading2', 'bulletedList', 'numberedList' ]
-         * };
-         * ```
-         *
-         * You can also use `'|'` to create a separator between groups of items:
-         *
-         * ```ts
-         * const config = {
-         * 	blockToolbar: [ 'paragraph', 'heading1', 'heading2', '|', 'bulletedList', 'numberedList' ]
-         * };
-         * ```
-         *
-         * ## Configuring items grouping
-         *
-         * You can prevent automatic items grouping by setting the `shouldNotGroupWhenFull` option:
-         *
-         * ```ts
-         * const config = {
-         * 	blockToolbar: {
-         * 		items: [ 'paragraph', 'heading1', 'heading2', '|', 'bulletedList', 'numberedList' ],
-         * 		shouldNotGroupWhenFull: true
-         * 	},
-         * };
-         * ```
-         *
-         * Read more about configuring the main editor toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
-         */
-        blockToolbar?: ToolbarConfig;
-    }
-    interface PluginsMap {
-        [BalloonToolbar.pluginName]: BalloonToolbar;
-        [BlockToolbar.pluginName]: BlockToolbar;
-        [ContextualBalloon.pluginName]: ContextualBalloon;
-        [Notification.pluginName]: Notification;
-    }
-}
+/**
+ * @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 type { BalloonToolbar, BlockToolbar, ContextualBalloon, Notification } from './index';
+import type { ToolbarConfig } from '@ckeditor/ckeditor5-core';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * Contextual toolbar configuration. Used by the {@link module:ui/toolbar/balloon/balloontoolbar~BalloonToolbar}
+         * feature.
+         *
+         * ## Configuring toolbar items
+         *
+         * ```ts
+         * const config = {
+         * 	balloonToolbar: [ 'bold', 'italic', 'undo', 'redo' ]
+         * };
+         * ```
+         *
+         * You can also use `'|'` to create a separator between groups of items:
+         *
+         * ```ts
+         * const config = {
+         * 	balloonToolbar: [ 'bold', 'italic', '|', 'undo', 'redo' ]
+         * };
+         * ```
+         *
+         * Read also about configuring the main editor toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
+         *
+         * ## Configuring items grouping
+         *
+         * You can prevent automatic items grouping by setting the `shouldNotGroupWhenFull` option:
+         *
+         * ```ts
+         * const config = {
+         * 	balloonToolbar: {
+         * 		items: [ 'bold', 'italic', 'undo', 'redo' ],
+         * 		shouldNotGroupWhenFull: true
+         * 	},
+         * };
+         * ```
+         */
+        balloonToolbar?: ToolbarConfig;
+        /**
+         * The block toolbar configuration. Used by the {@link module:ui/toolbar/block/blocktoolbar~BlockToolbar}
+         * feature.
+         *
+         * ```ts
+         * const config = {
+         * 	blockToolbar: [ 'paragraph', 'heading1', 'heading2', 'bulletedList', 'numberedList' ]
+         * };
+         * ```
+         *
+         * You can also use `'|'` to create a separator between groups of items:
+         *
+         * ```ts
+         * const config = {
+         * 	blockToolbar: [ 'paragraph', 'heading1', 'heading2', '|', 'bulletedList', 'numberedList' ]
+         * };
+         * ```
+         *
+         * ## Configuring items grouping
+         *
+         * You can prevent automatic items grouping by setting the `shouldNotGroupWhenFull` option:
+         *
+         * ```ts
+         * const config = {
+         * 	blockToolbar: {
+         * 		items: [ 'paragraph', 'heading1', 'heading2', '|', 'bulletedList', 'numberedList' ],
+         * 		shouldNotGroupWhenFull: true
+         * 	},
+         * };
+         * ```
+         *
+         * Read more about configuring the main editor toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
+         */
+        blockToolbar?: ToolbarConfig;
+    }
+    interface PluginsMap {
+        [BalloonToolbar.pluginName]: BalloonToolbar;
+        [BlockToolbar.pluginName]: BlockToolbar;
+        [ContextualBalloon.pluginName]: ContextualBalloon;
+        [Notification.pluginName]: Notification;
+    }
+}

package/src/augmentation.js

@@ -1,5 +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 {};
+/**
+ * @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/autocomplete/autocompleteview.d.ts

@@ -1,81 +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;
-}
+/**
+ * @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;
+}