@ckeditor/ckeditor5-ui 41.3.1 → 41.4.0

package/dist/types/toolbar/toolbarview.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @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/toolbar/toolbarview
+ */
+import View from '../view.js';
+import { type FocusableView } from '../focuscycler.js';
+import type ComponentFactory from '../componentfactory.js';
+import type ViewCollection from '../viewcollection.js';
+import type DropdownPanelFocusable from '../dropdown/dropdownpanelfocusable.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from '@ckeditor/ckeditor5-utils';
+import { type ToolbarConfig } from '@ckeditor/ckeditor5-core';
+import '../../theme/components/toolbar/toolbar.css';
+export declare const NESTED_TOOLBAR_ICONS: Record<string, string | undefined>;
+/**
+ * The toolbar view class.
+ */
+export default class ToolbarView extends View implements DropdownPanelFocusable {
+    /**
+     * A reference to the options object passed to the constructor.
+     */
+    readonly options: ToolbarOptions;
+    /**
+     * A collection of toolbar items (buttons, dropdowns, etc.).
+     */
+    readonly items: ViewCollection;
+    /**
+     * Tracks information about the DOM focus in the toolbar.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}
+     * to handle keyboard navigation in the toolbar.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * A (child) view containing {@link #items toolbar items}.
+     */
+    readonly itemsView: ItemsView;
+    /**
+     * A top–level collection aggregating building blocks of the toolbar.
+     *
+     *	┌───────────────── ToolbarView ─────────────────┐
+     *	| ┌──────────────── #children ────────────────┐ |
+     *	| |   ┌──────────── #itemsView ───────────┐   | |
+     *	| |   | [ item1 ] [ item2 ] ... [ itemN ] |   | |
+     *	| |   └──────────────────────────────────-┘   | |
+     *	| └───────────────────────────────────────────┘ |
+     *	└───────────────────────────────────────────────┘
+     *
+     * By default, it contains the {@link #itemsView} but it can be extended with additional
+     * UI elements when necessary.
+     */
+    readonly children: ViewCollection;
+    /**
+     * A collection of {@link #items} that take part in the focus cycling
+     * (i.e. navigation using the keyboard). Usually, it contains a subset of {@link #items} with
+     * some optional UI elements that also belong to the toolbar and should be focusable
+     * by the user.
+     */
+    readonly focusables: ViewCollection<FocusableView>;
+    locale: Locale;
+    /**
+     * Label used by assistive technologies to describe this toolbar element.
+     *
+     * @observable
+     * @default 'Editor toolbar'
+     */
+    ariaLabel: string;
+    /**
+     * The maximum width of the toolbar element.
+     *
+     * **Note**: When set to a specific value (e.g. `'200px'`), the value will affect the behavior of the
+     * {@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull}
+     * option by changing the number of {@link #items} that will be displayed in the toolbar at a time.
+     *
+     * @observable
+     * @default 'auto'
+     */
+    maxWidth: string;
+    /**
+     * An additional CSS class added to the {@link #element}.
+     *
+     * @observable
+     * @member {String} #class
+     */
+    class: string | undefined;
+    /**
+     * When set true, makes the toolbar look compact with {@link #element}.
+     *
+     * @observable
+     * @default false
+     */
+    isCompact: boolean;
+    /**
+     * Controls the orientation of toolbar items. Only available when
+     * {@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull dynamic items grouping}
+     * is **disabled**.
+     *
+     * @observable
+     */
+    isVertical: boolean;
+    /**
+     * Helps cycling over {@link #focusables focusable items} in the toolbar.
+     */
+    private readonly _focusCycler;
+    /**
+     * An instance of the active toolbar behavior that shapes its look and functionality.
+     *
+     * See {@link module:ui/toolbar/toolbarview~ToolbarBehavior} to learn more.
+     */
+    private readonly _behavior;
+    /**
+     * Creates an instance of the {@link module:ui/toolbar/toolbarview~ToolbarView} class.
+     *
+     * Also see {@link #render}.
+     *
+     * @param locale The localization services instance.
+     * @param options Configuration options of the toolbar.
+     */
+    constructor(locale: Locale, options?: ToolbarOptions);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the first focusable in {@link #focusables}.
+     */
+    focus(): void;
+    /**
+     * Focuses the last focusable in {@link #focusables}.
+     */
+    focusLast(): void;
+    /**
+     * A utility that expands the plain toolbar configuration into
+     * {@link module:ui/toolbar/toolbarview~ToolbarView#items} using a given component factory.
+     *
+     * @param itemsOrConfig The toolbar items or the entire toolbar configuration object.
+     * @param factory A factory producing toolbar items.
+     * @param removeItems An array of items names to be removed from the configuration. When present, applies
+     * to this toolbar and all nested ones as well.
+     */
+    fillFromConfig(itemsOrConfig: ToolbarConfig | undefined, factory: ComponentFactory, removeItems?: Array<string>): void;
+    /**
+     * A utility that expands the plain toolbar configuration into a list of view items using a given component factory.
+     *
+     * @param itemsOrConfig The toolbar items or the entire toolbar configuration object.
+     * @param factory A factory producing toolbar items.
+     * @param removeItems An array of items names to be removed from the configuration. When present, applies
+     * to this toolbar and all nested ones as well.
+     */
+    private _buildItemsFromConfig;
+    /**
+     * Cleans up the {@link module:ui/toolbar/toolbarview~ToolbarView#items} of the toolbar by removing unwanted items and
+     * duplicated (obsolete) separators or line breaks.
+     *
+     * @param items The toolbar items configuration.
+     * @param factory A factory producing toolbar items.
+     * @param removeItems An array of items names to be removed from the configuration.
+     * @returns Items after the clean-up.
+     */
+    private _cleanItemsConfiguration;
+    /**
+     * Remove leading, trailing, and duplicated separators (`-` and `|`).
+     *
+     * @returns Toolbar items after the separator and line break clean-up.
+     */
+    private _cleanSeparatorsAndLineBreaks;
+    /**
+     * Creates a user-defined dropdown containing a toolbar with items.
+     *
+     * @param definition A definition of the nested toolbar dropdown.
+     * @param definition.label A label of the dropdown.
+     * @param definition.icon An icon of the drop-down. One of 'bold', 'plus', 'text', 'importExport', 'alignLeft',
+     * 'paragraph' or an SVG string. When `false` is passed, no icon will be used.
+     * @param definition.withText When set `true`, the label of the dropdown will be visible. See
+     * {@link module:ui/button/buttonview~ButtonView#withText} to learn more.
+     * @param definition.tooltip A tooltip of the dropdown button. See
+     * {@link module:ui/button/buttonview~ButtonView#tooltip} to learn more. Defaults to `true`.
+     * @param componentFactory Component factory used to create items
+     * of the nested toolbar.
+     */
+    private _createNestedToolbarDropdown;
+}
+/**
+ * Fired when some toolbar {@link ~ToolbarView#items} were grouped or ungrouped as a result of some change
+ * in the toolbar geometry.
+ *
+ * **Note**: This event is always fired **once** regardless of the number of items that were be
+ * grouped or ungrouped at a time.
+ *
+ * **Note**: This event is fired only if the items grouping functionality was enabled in
+ * the first place (see {@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull}).
+ *
+ * @eventName ~ToolbarView#groupedItemsUpdate
+ */
+export type ToolbarViewGroupedItemsUpdateEvent = {
+    name: 'groupedItemsUpdate';
+    args: [];
+};
+/**
+ * An inner block of the {@link module:ui/toolbar/toolbarview~ToolbarView} hosting its
+ * {@link module:ui/toolbar/toolbarview~ToolbarView#items}.
+ */
+declare class ItemsView extends View {
+    /**
+     * A collection of items (buttons, dropdowns, etc.).
+     */
+    readonly children: ViewCollection;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}
+/**
+ * Options passed to the {@link module:ui/toolbar/toolbarview~ToolbarView#constructor} of the toolbar.
+ */
+export interface ToolbarOptions {
+    /**
+     * When set to `true`, the toolbar will automatically group {@link module:ui/toolbar/toolbarview~ToolbarView#items} that
+     * would normally wrap to the next line when there is not enough space to display them in a single row, for
+     * instance, if the parent container of the toolbar is narrow. For toolbars in absolutely positioned containers
+     * without width restrictions also the {@link module:ui/toolbar/toolbarview~ToolbarOptions#isFloating} option is required to be `true`.
+     *
+     * See also: {@link module:ui/toolbar/toolbarview~ToolbarView#maxWidth}.
+     */
+    shouldGroupWhenFull?: boolean;
+    /**
+     * This option should be enabled for toolbars in absolutely positioned containers without width restrictions
+     * to enable automatic {@link module:ui/toolbar/toolbarview~ToolbarView#items} grouping.
+     * When this option is set to `true`, the items will stop wrapping to the next line
+     * and together with {@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull},
+     * this will allow grouping them when there is not enough space in a single row.
+     */
+    isFloating?: boolean;
+}
+/**
+ * A class interface defining the behavior of the {@link module:ui/toolbar/toolbarview~ToolbarView}.
+ *
+ * Toolbar behaviors extend its look and functionality and have an impact on the
+ * {@link module:ui/toolbar/toolbarview~ToolbarView#element} template or
+ * {@link module:ui/toolbar/toolbarview~ToolbarView#render rendering}. They can be enabled
+ * conditionally, e.g. depending on the configuration of the toolbar.
+ */
+export interface ToolbarBehavior {
+    /**
+     * A method called after the toolbar has been {@link module:ui/toolbar/toolbarview~ToolbarView#render rendered}.
+     * It can be used to, for example, customize the behavior of the toolbar when its
+     * {@link module:ui/toolbar/toolbarview~ToolbarView#element} is available.
+     *
+     * @param view An instance of the toolbar being rendered.
+     */
+    render(view: ToolbarView): void;
+    /**
+     * A method called after the toolbar has been {@link module:ui/toolbar/toolbarview~ToolbarView#destroy destroyed}.
+     * It allows cleaning up after the toolbar behavior, for instance, this is the right place to detach
+     * event listeners, free up references, etc.
+     */
+    destroy(): void;
+}
+export {};

package/dist/types/tooltipmanager.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @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/tooltipmanager
+ */
+import View from './view.js';
+import BalloonPanelView from './panel/balloon/balloonpanelview.js';
+import { type PositioningFunction } from '@ckeditor/ckeditor5-utils';
+import type { Editor } from '@ckeditor/ckeditor5-core';
+import '../theme/components/tooltip/tooltip.css';
+declare const TooltipManager_base: {
+    new (): import("@ckeditor/ckeditor5-utils").DomEmitter;
+    prototype: import("@ckeditor/ckeditor5-utils").DomEmitter;
+};
+/**
+ * A tooltip manager class for the UI of the editor.
+ *
+ * **Note**: Most likely you do not have to use the `TooltipManager` API listed below in order to display tooltips. Popular
+ * {@glink framework/architecture/ui-library UI components} support tooltips out-of-the-box via observable properties
+ * (see {@link module:ui/button/buttonview~ButtonView#tooltip} and {@link module:ui/button/buttonview~ButtonView#tooltipPosition}).
+ *
+ * # Displaying tooltips
+ *
+ * To display a tooltip, set `data-cke-tooltip-text` attribute on any DOM element:
+ *
+ * ```ts
+ * domElement.dataset.ckeTooltipText = 'My tooltip';
+ * ```
+ *
+ * The tooltip will show up whenever the user moves the mouse over the element or the element gets focus in DOM.
+ *
+ * # Positioning tooltips
+ *
+ * To change the position of the tooltip, use the `data-cke-tooltip-position` attribute (`s`, `se`, `sw`, `n`, `e`, or `w`):
+ *
+ * ```ts
+ * domElement.dataset.ckeTooltipText = 'Tooltip to the north';
+ * domElement.dataset.ckeTooltipPosition = 'n';
+ * ```
+ *
+ * # Disabling tooltips
+ *
+ * In order to disable the tooltip  temporarily, use the `data-cke-tooltip-disabled` attribute:
+ *
+ * ```ts
+ * domElement.dataset.ckeTooltipText = 'Disabled. For now.';
+ * domElement.dataset.ckeTooltipDisabled = 'true';
+ * ```
+ *
+ * # Styling tooltips
+ *
+ * By default, the tooltip has `.ck-tooltip` class and its text inner `.ck-tooltip__text`.
+ *
+ * If your tooltip requires custom styling, using `data-cke-tooltip-class` attribute will add additional class to the balloon
+ * displaying the tooltip:
+ *
+ * ```ts
+ * domElement.dataset.ckeTooltipText = 'Tooltip with a red text';
+ * domElement.dataset.ckeTooltipClass = 'my-class';
+ * ```
+ *
+ * ```css
+ * .ck.ck-tooltip.my-class { color: red }
+ * ```
+ *
+ * **Note**: This class is a singleton. All editor instances re-use the same instance loaded by
+ * {@link module:ui/editorui/editorui~EditorUI} of the first editor.
+ */
+export default class TooltipManager extends TooltipManager_base {
+    /**
+     * The view rendering text of the tooltip.
+     */
+    readonly tooltipTextView: View & {
+        text: string;
+    };
+    /**
+     * The instance of the balloon panel that renders and positions the tooltip.
+     */
+    readonly balloonPanelView: BalloonPanelView;
+    /**
+     * A set of default {@link module:utils/dom/position~PositioningFunction positioning functions} used by the `TooltipManager`
+     * to pin tooltips in different positions.
+     */
+    static defaultBalloonPositions: Record<string, PositioningFunction>;
+    /**
+     * Stores the reference to the DOM element the tooltip is attached to. `null` when there's no tooltip
+     * in the UI.
+     */
+    private _currentElementWithTooltip;
+    /**
+     * Stores the current tooltip position. `null` when there's no tooltip in the UI.
+     */
+    private _currentTooltipPosition;
+    /**
+     * An instance of the resize observer that keeps track on target element visibility,
+     * when it hides the tooltip should also disappear.
+     *
+     * {@link module:core/editor/editorconfig~EditorConfig#balloonToolbar configuration}.
+     */
+    private _resizeObserver;
+    /**
+     * An instance of the mutation observer that keeps track on target element attributes changes.
+     */
+    private _mutationObserver;
+    /**
+     * A debounced version of {@link #_pinTooltip}. Tooltips show with a delay to avoid flashing and
+     * to improve the UX.
+     */
+    private _pinTooltipDebounced;
+    /**
+     * A debounced version of {@link #_unpinTooltip}. Tooltips hide with a delay to allow hovering of their titles.
+     */
+    private _unpinTooltipDebounced;
+    private readonly _watchdogExcluded;
+    /**
+     * A set of editors the single tooltip manager instance must listen to.
+     * This is mostly to handle `EditorUI#update` listeners from individual editors.
+     */
+    private static _editors;
+    /**
+     * A reference to the `TooltipManager` instance. The class is a singleton and as such,
+     * successive attempts at creating instances should return this instance.
+     */
+    private static _instance;
+    /**
+     * Creates an instance of the tooltip manager.
+     */
+    constructor(editor: Editor);
+    /**
+     * Destroys the tooltip manager.
+     *
+     * **Note**: The manager singleton cannot be destroyed until all editors that use it are destroyed.
+     *
+     * @param editor The editor the manager was created for.
+     */
+    destroy(editor: Editor): void;
+    /**
+     * Returns {@link #balloonPanelView} {@link module:utils/dom/position~PositioningFunction positioning functions} for a given position
+     * name.
+     *
+     * @param position Name of the position (`s`, `se`, `sw`, `n`, `e`, or `w`).
+     * @returns Positioning functions to be used by the {@link #balloonPanelView}.
+     */
+    static getPositioningFunctions(position: TooltipPosition): Array<PositioningFunction>;
+    /**
+     * Handles hiding tooltips on `keydown` in DOM.
+     *
+     * @param evt An object containing information about the fired event.
+     * @param domEvent The DOM event.
+     */
+    private _onKeyDown;
+    /**
+     * Handles displaying tooltips on `mouseenter` and `focus` in DOM.
+     *
+     * @param evt An object containing information about the fired event.
+     * @param domEvent The DOM event.
+     */
+    private _onEnterOrFocus;
+    /**
+     * Handles hiding tooltips on `mouseleave` and `blur` in DOM.
+     *
+     * @param evt An object containing information about the fired event.
+     * @param domEvent The DOM event.
+     */
+    private _onLeaveOrBlur;
+    /**
+     * Handles hiding tooltips on `scroll` in DOM.
+     *
+     * @param evt An object containing information about the fired event.
+     * @param domEvent The DOM event.
+     */
+    private _onScroll;
+    /**
+     * Pins the tooltip to a specific DOM element.
+     *
+     * @param options.text Text of the tooltip to display.
+     * @param options.position The position of the tooltip.
+     * @param options.cssClass Additional CSS class of the balloon with the tooltip.
+     */
+    private _pinTooltip;
+    /**
+     * Unpins the tooltip and cancels all queued pinning.
+     */
+    private _unpinTooltip;
+    /**
+     * Updates the position of the tooltip so it stays in sync with the element it is pinned to.
+     *
+     * Hides the tooltip when the element is no longer visible in DOM or the tooltip text was removed.
+     */
+    private _updateTooltipPosition;
+}
+export type TooltipPosition = 's' | 'n' | 'e' | 'w' | 'sw' | 'se';
+export {};