@ckeditor/ckeditor5-ui 41.3.1 → 41.4.0

package/dist/types/menubar/utils.d.ts

@@ -0,0 +1,443 @@
+/**
+ * @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
+ */
+/**
+ * @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
+ */
+import type MenuBarMenuView from './menubarmenuview.js';
+import type { default as MenuBarView, MenuBarConfig, MenuBarConfigObject, NormalizedMenuBarConfigObject } from './menubarview.js';
+import type ComponentFactory from '../componentfactory.js';
+import type { Editor } from '@ckeditor/ckeditor5-core';
+import { type Locale, type PositioningFunction } from '@ckeditor/ckeditor5-utils';
+type DeepReadonly<T> = Readonly<{
+    [K in keyof T]: T[K] extends string ? Readonly<T[K]> : T[K] extends Array<infer A> ? Readonly<Array<DeepReadonly<A>>> : DeepReadonly<T[K]>;
+}>;
+/**
+ * Behaviors of the {@link module:ui/menubar/menubarview~MenuBarView} component.
+ */
+export declare const MenuBarBehaviors: {
+    /**
+     * When the bar is already open:
+     * * Opens the menu when the user hovers over its button.
+     * * Closes open menu when another menu's button gets hovered.
+     */
+    toggleMenusAndFocusItemsOnHover(menuBarView: MenuBarView): void;
+    /**
+     * Moves between top-level menus using the arrow left and right keys.
+     *
+     * If the menubar has already been open, the arrow keys move focus between top-level menu buttons and open them.
+     * If the menubar is closed, the arrow keys only move focus between top-level menu buttons.
+     */
+    focusCycleMenusOnArrows(menuBarView: MenuBarView): void;
+    /**
+     * Closes the entire sub-menu structure when the bar is closed. This prevents sub-menus from being open if the user
+     * closes the entire bar, and then re-opens some top-level menu.
+     */
+    closeMenusWhenTheBarCloses(menuBarView: MenuBarView): void;
+    /**
+     * Handles the following case:
+     * 1. Hover to open a sub-menu (A). The button has focus.
+     * 2. Press arrow up/down to move focus to another sub-menu (B) button.
+     * 3. Press arrow right to open the sub-menu (B).
+     * 4. The sub-menu (A) should close as it would with `toggleMenusAndFocusItemsOnHover()`.
+     */
+    closeMenuWhenAnotherOnTheSameLevelOpens(menuBarView: MenuBarView): void;
+    /**
+     * Closes the bar when the user clicked outside of it (page body, editor root, etc.).
+     */
+    closeOnClickOutside(menuBarView: MenuBarView): void;
+};
+/**
+ * Behaviors of the {@link module:ui/menubar/menubarmenuview~MenuBarMenuView} component.
+ */
+export declare const MenuBarMenuBehaviors: {
+    /**
+     * If the button of the menu is focused, pressing the arrow down key should open the panel and focus it.
+     * This is analogous to the {@link module:ui/dropdown/dropdownview~DropdownView}.
+     */
+    openAndFocusPanelOnArrowDownKey(menuView: MenuBarMenuView): void;
+    /**
+     * Open the menu on the right arrow key press. This allows for navigating to sub-menus using the keyboard.
+     */
+    openOnArrowRightKey(menuView: MenuBarMenuView): void;
+    /**
+     * Opens the menu on its button click. Note that this behavior only opens but never closes the menu (unlike
+     * {@link module:ui/dropdown/dropdownview~DropdownView}).
+     */
+    openOnButtonClick(menuView: MenuBarMenuView): void;
+    /**
+     * Toggles the menu on its button click. This behavior is analogous to {@link module:ui/dropdown/dropdownview~DropdownView}.
+     */
+    toggleOnButtonClick(menuView: MenuBarMenuView): void;
+    /**
+     * Closes the menu on the right left key press. This allows for navigating to sub-menus using the keyboard.
+     */
+    closeOnArrowLeftKey(menuView: MenuBarMenuView): void;
+    /**
+     * Closes the menu on the esc key press. This allows for navigating to sub-menus using the keyboard.
+     */
+    closeOnEscKey(menuView: MenuBarMenuView): void;
+    /**
+     * Closes the menu when its parent menu also closed. This prevents from orphaned open menus when the parent menu re-opens.
+     */
+    closeOnParentClose(menuView: MenuBarMenuView): void;
+};
+/**
+ * Contains every positioning function used by {@link module:ui/menubar/menubarmenuview~MenuBarMenuView} that decides where the
+ * {@link module:ui/menubar/menubarmenuview~MenuBarMenuView#panelView} should be placed.
+ *
+ * Top-level menu positioning functions:
+ *
+ *	┌──────┐
+ *	│      │
+ *	├──────┴────────┐
+ *	│               │
+ *	│               │
+ *	│               │
+ *	│            SE │
+ *	└───────────────┘
+ *
+ *	         ┌──────┐
+ *	         │      │
+ *	┌────────┴──────┤
+ *	│               │
+ *	│               │
+ *	│               │
+ *	│ SW            │
+ *	└───────────────┘
+ *
+ *	┌───────────────┐
+ *	│ NW            │
+ *	│               │
+ *	│               │
+ *	│               │
+ *	└────────┬──────┤
+ *	         │      │
+ *	         └──────┘
+ *
+ *	┌───────────────┐
+ *	│            NE │
+ *	│               │
+ *	│               │
+ *	│               │
+ *	├──────┬────────┘
+ *	│      │
+ *	└──────┘
+ *
+ * Sub-menu positioning functions:
+ *
+ *	┌──────┬───────────────┐
+ *	│      │               │
+ *	└──────┤               │
+ *	       │               │
+ *	       │            ES │
+ *	       └───────────────┘
+ *
+ *	┌───────────────┬──────┐
+ *	│               │      │
+ *	│               ├──────┘
+ *	│               │
+ *	│ WS            │
+ *	└───────────────┘
+ *
+ *	       ┌───────────────┐
+ *	       │            EN │
+ *	       │               │
+ *	┌──────┤               │
+ *	│      │               │
+ *	└──────┴───────────────┘
+ *
+ *	┌───────────────┐
+ *	│ WN            │
+ *	│               │
+ *	│               ├──────┐
+ *	│               │      │
+ *	└───────────────┴──────┘
+ */
+export declare const MenuBarMenuViewPanelPositioningFunctions: Record<string, PositioningFunction>;
+/**
+ * The default items {@link module:core/editor/editorconfig~EditorConfig#menuBar configuration} of the
+ * {@link module:ui/menubar/menubarview~MenuBarView} component. It contains names of all menu bar components
+ * registered in the {@link module:ui/componentfactory~ComponentFactory component factory} (available in the project).
+ *
+ * **Note**: Menu bar component names provided by core editor features are prefixed with `menuBar:` in order to distinguish
+ * them from components referenced by the {@link module:core/editor/editorconfig~EditorConfig#toolbar toolbar configuration}, for instance,
+ * `'menuBar:bold'` is a menu bar button but `'bold'` is a toolbar button.
+ *
+ * Below is the preset menu bar structure (the default value of `config.menuBar.items` property):
+ *
+ * ```ts
+ * [
+ * 	{
+ * 		menuId: 'file',
+ * 		label: 'File',
+ * 		groups: [
+ * 			{
+ * 				groupId: 'export',
+ * 				items: [
+ * 					'menuBar:exportPdf',
+ * 					'menuBar:exportWord'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'import',
+ * 				items: [
+ * 					'menuBar:importWord'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'revisionHistory',
+ * 				items: [
+ * 					'menuBar:revisionHistory'
+ * 				]
+ * 			}
+ * 		]
+ * 	},
+ * 	{
+ * 		menuId: 'edit',
+ * 		label: 'Edit',
+ * 		groups: [
+ * 			{
+ * 				groupId: 'undo',
+ * 				items: [
+ * 					'menuBar:undo',
+ * 					'menuBar:redo'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'selectAll',
+ * 				items: [
+ * 					'menuBar:selectAll'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'findAndReplace',
+ * 				items: [
+ * 					'menuBar:findAndReplace'
+ * 				]
+ * 			}
+ * 		]
+ * 	},
+ * 	{
+ * 		menuId: 'view',
+ * 		label: 'View',
+ * 		groups: [
+ * 			{
+ * 				groupId: 'sourceEditing',
+ * 				items: [
+ * 					'menuBar:sourceEditing'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'showBlocks',
+ * 				items: [
+ * 					'menuBar:showBlocks'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'restrictedEditingException',
+ * 				items: [
+ * 					'menuBar:restrictedEditingException'
+ * 				]
+ * 			}
+ * 		]
+ * 	},
+ * 	{
+ * 		menuId: 'insert',
+ * 		label: 'Insert',
+ * 		groups: [
+ * 			{
+ * 				groupId: 'insertMainWidgets',
+ * 				items: [
+ * 					'menuBar:uploadImage',
+ * 					'menuBar:ckbox',
+ * 					'menuBar:ckfinder',
+ * 					'menuBar:insertTable'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'insertInline',
+ * 				items: [
+ * 					'menuBar:link',
+ * 					'menuBar:comment'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'insertMinorWidgets',
+ * 				items: [
+ * 					'menuBar:insertTemplate',
+ * 					'menuBar:blockQuote',
+ * 					'menuBar:codeBlock',
+ * 					'menuBar:htmlEmbed'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'insertStructureWidgets',
+ * 				items: [
+ * 					'menuBar:horizontalLine',
+ * 					'menuBar:pageBreak',
+ * 					'menuBar:tableOfContents'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'restrictedEditing',
+ * 				items: [
+ * 					'menuBar:restrictedEditing'
+ * 				]
+ * 			}
+ * 		]
+ * 	},
+ * 	{
+ * 		menuId: 'format',
+ * 		label: 'Format',
+ * 		groups: [
+ * 			{
+ * 				groupId: 'textAndFont',
+ * 				items: [
+ * 					{
+ * 						menuId: 'text',
+ * 						label: 'Text',
+ * 						groups: [
+ * 							{
+ * 								groupId: 'basicStyles',
+ * 								items: [
+ * 									'menuBar:bold',
+ * 									'menuBar:italic',
+ * 									'menuBar:underline',
+ * 									'menuBar:strikethrough',
+ * 									'menuBar:superscript',
+ * 									'menuBar:subscript',
+ * 									'menuBar:code'
+ * 								]
+ * 							},
+ * 							{
+ * 								groupId: 'textPartLanguage',
+ * 								items: [
+ * 									'menuBar:textPartLanguage'
+ * 								]
+ * 							}
+ * 						]
+ * 					},
+ * 					{
+ * 						menuId: 'font',
+ * 						label: 'Font',
+ * 						groups: [
+ * 							{
+ * 								groupId: 'fontProperties',
+ * 								items: [
+ * 									'menuBar:fontSize',
+ * 									'menuBar:fontFamily'
+ * 								]
+ * 							},
+ * 							{
+ * 								groupId: 'fontColors',
+ * 								items: [
+ * 									'menuBar:fontColor',
+ * 									'menuBar:fontBackgroundColor'
+ * 								]
+ * 							},
+ * 							{
+ * 								groupId: 'highlight',
+ * 								items: [
+ * 									'menuBar:highlight'
+ * 								]
+ * 							}
+ * 						]
+ * 					},
+ * 					'menuBar:heading'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'list',
+ * 				items: [
+ * 					'menuBar:bulletedList',
+ * 					'menuBar:numberedList',
+ * 					'menuBar:todoList'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'indent',
+ * 				items: [
+ * 					'menuBar:alignment',
+ * 					'menuBar:indent',
+ * 					'menuBar:outdent'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'caseChange',
+ * 				items: [
+ * 					'menuBar:caseChange'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'removeFormat',
+ * 				items: [
+ * 					'menuBar:removeFormat'
+ * 				]
+ * 			}
+ * 		]
+ * 	},
+ * 	{
+ * 		menuId: 'tools',
+ * 		label: 'Tools',
+ * 		groups: [
+ * 			{
+ * 				groupId: 'aiTools',
+ * 				items: [
+ * 					'menuBar:aiAssistant',
+ * 					'menuBar:aiCommands'
+ * 				]
+ * 			},
+ * 			{
+ * 				groupId: 'tools',
+ * 				items: [
+ * 					'menuBar:trackChanges',
+ * 					'menuBar:commentsArchive'
+ * 				]
+ * 			}
+ * 		]
+ * 	},
+ * 	{
+ * 		menuId: 'help',
+ * 		label: 'Help',
+ * 		groups: [
+ * 			{
+ * 				groupId: 'help',
+ * 				items: [
+ * 					'menuBar:accessibilityHelp'
+ * 				]
+ * 			}
+ * 		]
+ * 	}
+ * ];
+ * ```
+ *
+ * The menu bar can be customized using the `config.menuBar.removeItems` and `config.menuBar.addItems` properties.
+ */
+export declare const DefaultMenuBarItems: DeepReadonly<MenuBarConfigObject['items']>;
+/**
+ * Performs a cleanup and normalization of the menu bar configuration.
+ */
+export declare function normalizeMenuBarConfig(config: Readonly<MenuBarConfig>): NormalizedMenuBarConfigObject;
+/**
+ * Processes a normalized menu bar config and returns a config clone with the following modifications:
+ *
+ * * Removed components that are not available in the component factory,
+ * * Removed obsolete separators,
+ * * Purged empty menus,
+ * * Localized top-level menu labels.
+ */
+export declare function processMenuBarConfig({ normalizedConfig, locale, componentFactory }: {
+    normalizedConfig: NormalizedMenuBarConfigObject;
+    locale: Locale;
+    componentFactory: ComponentFactory;
+}): NormalizedMenuBarConfigObject;
+/**
+ * Initializes menu bar for given editor.
+ *
+ * @internal
+ */
+export declare function _initMenuBar(editor: Editor, menuBarView: MenuBarView): void;
+export {};

package/dist/types/model.d.ts

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