@ckeditor/ckeditor5-ui 36.0.0 → 37.0.0-alpha.0

package/src/labeledinput/labeledinputview.js

@@ -11,103 +11,26 @@ import { uid } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/labeledinput/labeledinput.css';
 /**
  * The labeled input view class.
- *
- * @extends module:ui/view~View
  */
 export default class LabeledInputView extends View {
     /**
      * Creates an instance of the labeled input view class.
      *
-     * @param {module:utils/locale~Locale} locale The locale instance.
-     * @param {Function} InputView Constructor of the input view.
+     * @param locale The locale instance.
+     * @param InputView Constructor of the input view.
      */
     constructor(locale, InputView) {
         super(locale);
         const inputUid = `ck-input-${uid()}`;
         const statusUid = `ck-status-${uid()}`;
-        /**
-         * The text of the label.
-         *
-         * @observable
-         * @member {String} #label
-         */
         this.set('label', undefined);
-        /**
-         * The value of the input.
-         *
-         * @observable
-         * @member {String} #value
-         */
         this.set('value', undefined);
-        /**
-         * Controls whether the component is in read-only mode.
-         *
-         * @observable
-         * @member {Boolean} #isReadOnly
-         */
         this.set('isReadOnly', false);
-        /**
-         * The validation error text. When set, it will be displayed
-         * next to the {@link #inputView} as a typical validation error message.
-         * Set it to `null` to hide the message.
-         *
-         * **Note:** Setting this property to anything but `null` will automatically
-         * make the {@link module:ui/inputtext/inputtextview~InputTextView#hasError `hasError`}
-         * of the {@link #inputView} `true`.
-         *
-         * **Note:** Typing in the {@link #inputView} which fires the
-         * {@link module:ui/inputtext/inputtextview~InputTextView#event:input `input` event}
-         * resets this property back to `null`, indicating that the input field can be re–validated.
-         *
-         * @observable
-         * @member {String|null} #errorText
-         */
         this.set('errorText', null);
-        /**
-         * The additional information text displayed next to the {@link #inputView} which can
-         * be used to inform the user about the purpose of the input, provide help or hints.
-         *
-         * Set it to `null` to hide the message.
-         *
-         * **Note:** This text will be displayed in the same place as {@link #errorText} but the
-         * latter always takes precedence: if the {@link #errorText} is set, it replaces
-         * {@link #errorText} for as long as the value of the input is invalid.
-         *
-         * @observable
-         * @member {String|null} #infoText
-         */
         this.set('infoText', null);
-        /**
-         * The label view.
-         *
-         * @member {module:ui/label/labelview~LabelView} #labelView
-         */
         this.labelView = this._createLabelView(inputUid);
-        /**
-         * The input view.
-         *
-         * @member {module:ui/inputtext/inputtextview~InputTextView} #inputView
-         */
         this.inputView = this._createInputView(InputView, inputUid, statusUid);
-        /**
-         * The status view for the {@link #inputView}. It displays {@link #errorText} and
-         * {@link #infoText}.
-         *
-         * @member {module:ui/view~View} #statusView
-         */
         this.statusView = this._createStatusView(statusUid);
-        /**
-         * The combined status text made of {@link #errorText} and {@link #infoText}.
-         * Note that when present, {@link #errorText} always takes precedence in the
-         * status.
-         *
-         * @see #errorText
-         * @see #infoText
-         * @see #statusView
-         * @private
-         * @observable
-         * @member {String|null} #_statusText
-         */
         this.bind('_statusText').to(this, 'errorText', this, 'infoText', (errorText, infoText) => errorText || infoText);
         const bind = this.bindTemplate;
         this.setTemplate({
@@ -129,9 +52,7 @@ export default class LabeledInputView extends View {
     /**
      * Creates label view class instance and bind with view.
      *
-     * @private
-     * @param {String} id Unique id to set as labelView#for attribute.
-     * @returns {module:ui/label/labelview~LabelView}
+     * @param id Unique id to set as labelView#for attribute.
      */
     _createLabelView(id) {
         const labelView = new LabelView(this.locale);
@@ -142,11 +63,9 @@ export default class LabeledInputView extends View {
     /**
      * Creates input view class instance and bind with view.
      *
-     * @private
-     * @param {Function} InputView Input view constructor.
-     * @param {String} inputUid Unique id to set as inputView#id attribute.
-     * @param {String} statusUid Unique id of the status for the input's `aria-describedby` attribute.
-     * @returns {module:ui/inputtext/inputtextview~InputTextView}
+     * @param InputView Input view constructor.
+     * @param inputUid Unique id to set as inputView#id attribute.
+     * @param statusUid Unique id of the status for the input's `aria-describedby` attribute.
      */
     _createInputView(InputView, inputUid, statusUid) {
         const inputView = new InputView(this.locale, statusUid);
@@ -166,9 +85,7 @@ export default class LabeledInputView extends View {
      * Creates the status view instance. It displays {@link #errorText} and {@link #infoText}
      * next to the {@link #inputView}. See {@link #_statusText}.
      *
-     * @private
-     * @param {String} statusUid Unique id of the status, shared with the input's `aria-describedby` attribute.
-     * @returns {module:ui/view~View}
+     * @param statusUid Unique id of the status, shared with the input's `aria-describedby` attribute.
      */
     _createStatusView(statusUid) {
         const statusView = new View(this.locale);

package/src/list/listitemview.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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/list/listitemview
+ */
+import View from '../view';
+import type ViewCollection from '../viewcollection';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The list item view class.
+ */
+export default class ListItemView extends View {
+    /**
+     * Collection of the child views inside of the list item {@link #element}.
+     */
+    readonly children: ViewCollection;
+    /**
+     * Controls whether the item view is visible. Visible by default, list items are hidden
+     * using a CSS class.
+     *
+     * @observable
+     * @default true
+     */
+    isVisible: boolean;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * Focuses the list item.
+     */
+    focus(): void;
+}

package/src/list/listitemview.js

@@ -8,8 +8,6 @@
 import View from '../view';
 /**
  * The list item view class.
- *
- * @extends module:ui/view~View
  */
 export default class ListItemView extends View {
     /**
@@ -18,21 +16,7 @@ export default class ListItemView extends View {
     constructor(locale) {
         super(locale);
         const bind = this.bindTemplate;
-        /**
-         * Controls whether the item view is visible. Visible by default, list items are hidden
-         * using a CSS class.
-         *
-         * @observable
-         * @default true
-         * @member {Boolean} #isVisible
-         */
         this.set('isVisible', true);
-        /**
-         * Collection of the child views inside of the list item {@link #element}.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.children = this.createCollection();
         this.setTemplate({
             tag: 'li',

package/src/list/listseparatorview.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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/list/listseparatorview
+ */
+import View from '../view';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The list separator view class.
+ */
+export default class ListSeparatorView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}

package/src/list/listseparatorview.js

@@ -8,8 +8,6 @@
 import View from '../view';
 /**
  * The list separator view class.
- *
- * @extends module:ui/view~View
  */
 export default class ListSeparatorView extends View {
     /**

package/src/list/listview.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @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/list/listview
+ */
+import View from '../view';
+import type DropdownPanelFocusable from '../dropdown/dropdownpanelfocusable';
+import type ViewCollection from '../viewcollection';
+import { FocusTracker, KeystrokeHandler, type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/list/list.css';
+/**
+ * The list view class.
+ */
+export default class ListView extends View<HTMLUListElement> implements DropdownPanelFocusable {
+    /**
+     * Collection of the child list views.
+     */
+    readonly items: ViewCollection;
+    /**
+     * Tracks information about DOM focus in the list.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Label used by assistive technologies to describe this list element.
+     *
+     * @observable
+     */
+    ariaLabel: string | undefined;
+    /**
+     * Helps cycling over focusable {@link #items} in the list.
+     */
+    private readonly _focusCycler;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focus(): void;
+    /**
+     * Focuses the last focusable in {@link #items}.
+     */
+    focusLast(): void;
+}

package/src/list/listview.js

@@ -11,9 +11,6 @@ import { FocusTracker, KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/list/list.css';
 /**
  * The list view class.
- *
- * @extends module:ui/view~View
- * @implements module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable
  */
 export default class ListView extends View {
     /**
@@ -22,34 +19,9 @@ export default class ListView extends View {
     constructor(locale) {
         super(locale);
         const bind = this.bindTemplate;
-        /**
-         * Collection of the child list views.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.items = this.createCollection();
-        /**
-         * Tracks information about DOM focus in the list.
-         *
-         * @readonly
-         * @member {module:utils/focustracker~FocusTracker}
-         */
         this.focusTracker = new FocusTracker();
-        /**
-         * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
-         *
-         * @readonly
-         * @member {module:utils/keystrokehandler~KeystrokeHandler}
-         */
         this.keystrokes = new KeystrokeHandler();
-        /**
-         * Helps cycling over focusable {@link #items} in the list.
-         *
-         * @readonly
-         * @protected
-         * @member {module:ui/focuscycler~FocusCycler}
-         */
         this._focusCycler = new FocusCycler({
             focusables: this.items,
             focusTracker: this.focusTracker,
@@ -61,11 +33,6 @@ export default class ListView extends View {
                 focusNext: 'arrowdown'
             }
         });
-        /**
-         * Label used by assistive technologies to describe this list element.
-         *
-         * @member {String} #ariaLabel
-         */
         this.set('ariaLabel', undefined);
         this.setTemplate({
             tag: 'ul',

package/src/model.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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
+ */
+declare const Model_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * The base MVC model class.
+ */
+export default class Model extends Model_base {
+    [x: string]: unknown;
+    /**
+     * Creates a new Model instance.
+     *
+     * @param attributes The model state attributes to be defined during the instance creation.
+     * @param properties The (out of state) properties to be appended to the instance during creation.
+     */
+    constructor(attributes?: Record<string, unknown>, properties?: Record<string, unknown>);
+}
+export {};

package/src/model.js

@@ -9,15 +9,13 @@ import { ObservableMixin } from '@ckeditor/ckeditor5-utils';
 import { extend } from 'lodash-es';
 /**
  * The base MVC model class.
- *
- * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class Model extends ObservableMixin() {
     /**
      * Creates a new Model instance.
      *
-     * @param {Object} [attributes] The model state attributes to be defined during the instance creation.
-     * @param {Object} [properties] The (out of state) properties to be appended to the instance during creation.
+     * @param attributes The model state attributes to be defined during the instance creation.
+     * @param properties The (out of state) properties to be appended to the instance during creation.
      */
     constructor(attributes, properties) {
         super();

package/src/notification/notification.d.ts

@@ -0,0 +1,216 @@
+/**
+ * @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/notification/notification
+ */
+import { ContextPlugin } from '@ckeditor/ckeditor5-core';
+/**
+ * The Notification plugin.
+ *
+ * This plugin sends a few types of notifications: `success`, `info` and `warning`. The notifications need to be
+ * handled and displayed by a plugin responsible for showing the UI of the notifications. Using this plugin for dispatching
+ * notifications makes it possible to switch the notifications UI.
+ *
+ * Note that every unhandled and not stopped `warning` notification will be displayed as a system alert.
+ * See {@link module:ui/notification/notification~Notification#showWarning}.
+ */
+export default class Notification extends ContextPlugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Notification';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Shows a success notification.
+     *
+     * By default, it fires the {@link #event:show:success `show:success` event} with the given `data`. The event namespace can be extended
+     * using the `data.namespace` option. For example:
+     *
+     * ```ts
+     * showSuccess( 'Image is uploaded.', {
+     * 	namespace: 'upload:image'
+     * } );
+     * ```
+     *
+     * will fire the `show:success:upload:image` event.
+     *
+     * You can provide the title of the notification:
+     *
+     * ```ts
+     * showSuccess( 'Image is uploaded.', {
+     * 	title: 'Image upload success'
+     * } );
+     * ```
+     *
+     * @param message The content of the notification.
+     * @param data Additional data.
+     * @param data.namespace Additional event namespace.
+     * @param data.title The title of the notification.
+     */
+    showSuccess(message: string, data?: {
+        namespace?: string;
+        title?: string;
+    }): void;
+    /**
+     * Shows an information notification.
+     *
+     * By default, it fires the {@link #event:show:info `show:info` event} with the given `data`. The event namespace can be extended
+     * using the `data.namespace` option. For example:
+     *
+     * ```ts
+     * showInfo( 'Editor is offline.', {
+     * 	namespace: 'editor:status'
+     * } );
+     * ```
+     *
+     * will fire the `show:info:editor:status` event.
+     *
+     * You can provide the title of the notification:
+     *
+     * ```ts
+     * showInfo( 'Editor is offline.', {
+     * 	title: 'Network information'
+     * } );
+     * ```
+     *
+     * @param message The content of the notification.
+     * @param data Additional data.
+     * @param data.namespace Additional event namespace.
+     * @param data.title The title of the notification.
+     */
+    showInfo(message: string, data?: {
+        namespace?: string;
+        title?: string;
+    }): void;
+    /**
+     * Shows a warning notification.
+     *
+     * By default, it fires the {@link #event:show:warning `show:warning` event}
+     * with the given `data`. The event namespace can be extended using the `data.namespace` option. For example:
+     *
+     * ```ts
+     * showWarning( 'Image upload error.', {
+     * 	namespace: 'upload:image'
+     * } );
+     * ```
+     *
+     * will fire the `show:warning:upload:image` event.
+     *
+     * You can provide the title of the notification:
+     *
+     * ```ts
+     * showWarning( 'Image upload error.', {
+     * 	title: 'Upload failed'
+     * } );
+     * ```
+     *
+     * Note that each unhandled and not stopped `warning` notification will be displayed as a system alert.
+     * The plugin responsible for displaying warnings should `stop()` the event to prevent displaying it as an alert:
+     *
+     * ```ts
+     * notifications.on( 'show:warning', ( evt, data ) => {
+     * 	// Do something with the data.
+     *
+     * 	// Stop this event to prevent displaying it as an alert.
+     * 	evt.stop();
+     * } );
+     * ```
+     *
+     * You can attach many listeners to the same event and `stop()` this event in a listener with a low priority:
+     *
+     * ```ts
+     * notifications.on( 'show:warning', ( evt, data ) => {
+     * 	// Show the warning in the UI, but do not stop it.
+     * } );
+     *
+     * notifications.on( 'show:warning', ( evt, data ) => {
+     * 	// Log the warning to some error tracker.
+     *
+     * 	// Stop this event to prevent displaying it as an alert.
+     * 	evt.stop();
+     * }, { priority: 'low' } );
+     * ```
+     *
+     * @param message The content of the notification.
+     * @param data Additional data.
+     * @param data.namespace Additional event namespace.
+     * @param data.title The title of the notification.
+     */
+    showWarning(message: string, data?: {
+        namespace?: string;
+        title?: string;
+    }): void;
+    /**
+     * Fires the `show` event with the specified type, namespace and message.
+     *
+     * @param data The message data.
+     * @param data.message The content of the notification.
+     * @param data.type The type of the message.
+     * @param data.namespace Additional event namespace.
+     * @param data.title The title of the notification.
+     */
+    private _showNotification;
+}
+export type NotificationEventType = 'success' | 'info' | 'warning';
+/**
+ * Fired when one of the `showSuccess()`, `showInfo()`, `showWarning()` methods is called.
+ *
+ * @eventName show
+ * @param data The notification data.
+ */
+export type NotificationShowEvent = {
+    name: 'show';
+    args: [data: NotificationShowEventData];
+};
+/**
+ * Fired when the `showSuccess()` method is called.
+ *
+ * @eventName show:success
+ * @param data The notification data.
+ */
+export type NotificationShowSuccessEvent = NotificationShowTypeEvent<'success'>;
+/**
+ * Fired when the `showInfo()` method is called.
+ *
+ * @eventName show:info
+ * @param data The notification data.
+ */
+export type NotificationShowInfoEvent = NotificationShowTypeEvent<'info'>;
+/**
+ * Fired when the `showWarning()` method is called.
+ *
+ * When this event is not handled or stopped by `event.stop()`, the `data.message` of this event will
+ * be automatically displayed as a system alert.
+ *
+ * @eventName show:warning
+ * @param data The notification data.
+ */
+export type NotificationShowWarningEvent = NotificationShowTypeEvent<'warning'>;
+export type NotificationShowTypeEvent<NotificationType extends NotificationEventType> = {
+    name: `show:${NotificationType}` | `show:${NotificationType}:${string}`;
+    args: [data: NotificationShowEventData<NotificationType>];
+};
+export type NotificationShowEventData<NotificationType extends NotificationEventType = NotificationEventType> = {
+    /**
+     * The content of the notification.
+     */
+    message: string;
+    /**
+     * The title of the notification.
+     */
+    title: string;
+    /**
+     * The type of the notification.
+     */
+    type: NotificationType;
+};
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [Notification.pluginName]: Notification;
+    }
+}