@ckeditor/ckeditor5-ui 41.2.0 → 41.3.0-alpha.1

package/dist/types/list/listview.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @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/list/listview
+ */
+import View from '../view.js';
+import { type FocusableView } from '../focuscycler.js';
+import ListItemView from './listitemview.js';
+import ListItemGroupView from './listitemgroupview.js';
+import type ListSeparatorView from './listseparatorview.js';
+import type DropdownPanelFocusable from '../dropdown/dropdownpanelfocusable.js';
+import ViewCollection from '../viewcollection.js';
+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 {
+    /**
+     * The collection of focusable views in the list. It is used to determine accessible navigation
+     * between the {@link module:ui/list/listitemview~ListItemView list items} and
+     * {@link module:ui/list/listitemgroupview~ListItemGroupView list groups}.
+     */
+    readonly focusables: ViewCollection<FocusableView>;
+    /**
+     * Collection of the child list views.
+     */
+    readonly items: ViewCollection<ListItemView | ListItemGroupView | ListSeparatorView>;
+    /**
+     * 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;
+    /**
+     * (Optional) The ARIA property reflected by the `aria-ariaLabelledBy` DOM attribute used by assistive technologies.
+     *
+     * @observable
+     */
+    ariaLabelledBy?: string | undefined;
+    /**
+     * The property reflected by the `role` DOM attribute to be used by assistive technologies.
+     *
+     * @observable
+     */
+    role: string | undefined;
+    /**
+     * Helps cycling over focusable {@link #items} in the list.
+     */
+    private readonly _focusCycler;
+    /**
+     * A cached map of {@link module:ui/list/listitemgroupview~ListItemGroupView} to `change` event listeners for their `items`.
+     * Used for accessibility and keyboard navigation purposes.
+     */
+    private readonly _listItemGroupToChangeListeners;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focus(): void;
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focusFirst(): void;
+    /**
+     * Focuses the last focusable in {@link #items}.
+     */
+    focusLast(): void;
+    /**
+     * Registers a list item view in the focus tracker.
+     *
+     * @param item The list item view to be registered.
+     * @param index Index of the list item view in the {@link #items} collection. If not specified, the item will be added at the end.
+     */
+    private _registerFocusableListItem;
+    /**
+     * Removes a list item view from the focus tracker.
+     *
+     * @param item The list item view to be removed.
+     */
+    private _deregisterFocusableListItem;
+    /**
+     * Gets a callback that will be called when the `items` collection of a {@link module:ui/list/listitemgroupview~ListItemGroupView}
+     * change.
+     *
+     * @param groupView The group view for which the callback will be created.
+     * @returns The callback function to be used for the items `change` event listener in a group.
+     */
+    private _getOnGroupItemsChangeCallback;
+    /**
+     * Registers a list item group view (and its children) in the focus tracker.
+     *
+     * @param groupView A group view to be registered.
+     * @param groupIndex Index of the group view in the {@link #items} collection. If not specified, the group will be added at the end.
+     */
+    private _registerFocusableItemsGroup;
+    /**
+     * Removes a list item group view (and its children) from the focus tracker.
+     *
+     * @param groupView The group view to be removed.
+     */
+    private _deregisterFocusableItemsGroup;
+}

package/dist/types/model.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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
+ */
+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/dist/types/notification/notification.d.ts

@@ -0,0 +1,211 @@
+/**
+ * @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/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 ~Notification#show
+ * @param data The notification data.
+ */
+export type NotificationShowEvent = {
+    name: 'show';
+    args: [data: NotificationShowEventData];
+};
+/**
+ * Fired when the `showSuccess()` method is called.
+ *
+ * @eventName ~Notification#show:success
+ * @param data The notification data.
+ */
+export type NotificationShowSuccessEvent = NotificationShowTypeEvent<'success'>;
+/**
+ * Fired when the `showInfo()` method is called.
+ *
+ * @eventName ~Notification#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 ~Notification#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;
+};