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

package/src/tooltipmanager.d.ts

@@ -0,0 +1,180 @@
+/**
+ * @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/tooltipmanager
+ */
+import View from './view';
+import BalloonPanelView from './panel/balloon/balloonpanelview';
+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:core/editor/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;
+    /**
+     * A debounced version of {@link #_pinTooltip}. Tooltips show with a delay to avoid flashing and
+     * to improve the UX.
+     */
+    private _pinTooltipDebounced;
+    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 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.
+     */
+    private _updateTooltipPosition;
+}
+export type TooltipPosition = 's' | 'n' | 'e' | 'w' | 'sw' | 'se';
+export {};

package/src/tooltipmanager.js

@@ -15,14 +15,16 @@ const BALLOON_CLASS = 'ck-tooltip';
  * 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/guides/architecture/ui-library UI components} support tooltips out-of-the-box via observable properties
+ * {@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:
  *
- *		domElement.dataset.ckeTooltipText = 'My tooltip';
+ * ```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.
  *
@@ -30,16 +32,19 @@ const BALLOON_CLASS = 'ck-tooltip';
  *
  * To change the position of the tooltip, use the `data-cke-tooltip-position` attribute (`s`, `se`, `sw`, `n`, `e`, or `w`):
  *
- *		domElement.dataset.ckeTooltipText = 'Tooltip to the north';
- *		domElement.dataset.ckeTooltipPosition = 'n';
+ * ```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:
  *
- *		domElement.dataset.ckeTooltipText = 'Disabled. For now.';
- *		domElement.dataset.ckeTooltipDisabled = 'true';
- *
+ * ```ts
+ * domElement.dataset.ckeTooltipText = 'Disabled. For now.';
+ * domElement.dataset.ckeTooltipDisabled = 'true';
+ * ```
  *
  * # Styling tooltips
  *
@@ -48,24 +53,40 @@ const BALLOON_CLASS = 'ck-tooltip';
  * If your tooltip requires custom styling, using `data-cke-tooltip-class` attribute will add additional class to the balloon
  * displaying the tooltip:
  *
- *		domElement.dataset.ckeTooltipText = 'Tooltip with a red text';
- *		domElement.dataset.ckeTooltipClass = 'my-class';
+ * ```ts
+ * domElement.dataset.ckeTooltipText = 'Tooltip with a red text';
+ * domElement.dataset.ckeTooltipClass = 'my-class';
+ * ```
  *
- *		.ck.ck-tooltip.my-class { color: red }
+ * ```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:core/editor/editorui~EditorUI} of the first editor.
- *
- * @mixes module:utils/domemittermixin~DomEmitterMixin
  */
 export default class TooltipManager extends DomEmitterMixin() {
     /**
      * Creates an instance of the tooltip manager.
-     *
-     * @param {module:core/editor/editor~Editor} editor
      */
     constructor(editor) {
         super();
+        /**
+         * Stores the reference to the DOM element the tooltip is attached to. `null` when there's no tooltip
+         * in the UI.
+         */
+        this._currentElementWithTooltip = null;
+        /**
+         * Stores the current tooltip position. `null` when there's no tooltip in the UI.
+         */
+        this._currentTooltipPosition = null;
+        /**
+         * 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}.
+         */
+        this._resizeObserver = null;
         TooltipManager._editors.add(editor);
         // TooltipManager must be a singleton. Multiple instances would mean multiple tooltips attached
         // to the same DOM element with data-cke-tooltip-* attributes.
@@ -73,12 +94,6 @@ export default class TooltipManager extends DomEmitterMixin() {
             return TooltipManager._instance;
         }
         TooltipManager._instance = this;
-        /**
-         * The view rendering text of the tooltip.
-         *
-         * @readonly
-         * @member {module:ui/view~View} #tooltipTextView
-         */
         this.tooltipTextView = new View(editor.locale);
         this.tooltipTextView.set('text', '');
         this.tooltipTextView.setTemplate({
@@ -95,51 +110,9 @@ export default class TooltipManager extends DomEmitterMixin() {
                 }
             ]
         });
-        /**
-         * The instance of the balloon panel that renders and positions the tooltip.
-         *
-         * @readonly
-         * @member {module:ui/panel/balloon/balloonpanelview~BalloonPanelView} #balloonPanelView
-         */
         this.balloonPanelView = new BalloonPanelView(editor.locale);
         this.balloonPanelView.class = BALLOON_CLASS;
         this.balloonPanelView.content.add(this.tooltipTextView);
-        /**
-         * 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}.
-         *
-         * @protected
-         * @member {module:utils/dom/resizeobserver~ResizeObserver|null}
-         *
-         */
-        this._resizeObserver = null;
-        /**
-         * Stores the reference to the DOM element the tooltip is attached to. `null` when there's no tooltip
-         * in the UI.
-         *
-         * @private
-         * @readonly
-         * @member {HTMLElement|null} #_currentElementWithTooltip
-         */
-        this._currentElementWithTooltip = null;
-        /**
-         * Stores the current tooltip position. `null` when there's no tooltip in the UI.
-         *
-         * @private
-         * @readonly
-         * @member {String|null} #_currentTooltipPosition
-         */
-        this._currentTooltipPosition = null;
-        /**
-         * A debounced version of {@link #_pinTooltip}. Tooltips show with a delay to avoid flashing and
-         * to improve the UX.
-         *
-         * @private
-         * @readonly
-         * @member {Function} #_pinTooltipDebounced
-         */
         this._pinTooltipDebounced = debounce(this._pinTooltip, 600);
         this.listenTo(global.document, 'mouseenter', this._onEnterOrFocus.bind(this), { useCapture: true });
         this.listenTo(global.document, 'mouseleave', this._onLeaveOrBlur.bind(this), { useCapture: true });
@@ -158,7 +131,7 @@ export default class TooltipManager extends DomEmitterMixin() {
      *
      * **Note**: The manager singleton cannot be destroyed until all editors that use it are destroyed.
      *
-     * @param {module:core/editor/editor~Editor} editor The editor the manager was created for.
+     * @param editor The editor the manager was created for.
      */
     destroy(editor) {
         const editorBodyViewCollection = editor.ui.view && editor.ui.view.body;
@@ -180,9 +153,8 @@ export default class TooltipManager extends DomEmitterMixin() {
      * Returns {@link #balloonPanelView} {@link module:utils/dom/position~PositioningFunction positioning functions} for a given position
      * name.
      *
-     * @static
-     * @param {String} position Name of the position (`s`, `se`, `sw`, `n`, `e`, or `w`).
-     * @returns {Array.<module:utils/dom/position~PositioningFunction>} Positioning functions to be used by the {@link #balloonPanelView}.
+     * @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) {
         const defaultPositions = TooltipManager.defaultBalloonPositions;
@@ -203,9 +175,8 @@ export default class TooltipManager extends DomEmitterMixin() {
     /**
      * Handles displaying tooltips on `mouseenter` and `focus` in DOM.
      *
-     * @private
-     * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
-     * @param {Event} domEvent The DOM event.
+     * @param evt An object containing information about the fired event.
+     * @param domEvent The DOM event.
      */
     _onEnterOrFocus(evt, { target }) {
         const elementWithTooltipAttribute = getDescendantWithTooltip(target);
@@ -225,9 +196,8 @@ export default class TooltipManager extends DomEmitterMixin() {
     /**
      * Handles hiding tooltips on `mouseleave` and `blur` in DOM.
      *
-     * @private
-     * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
-     * @param {Event} domEvent The DOM event.
+     * @param evt An object containing information about the fired event.
+     * @param domEvent The DOM event.
      */
     _onLeaveOrBlur(evt, { target, relatedTarget }) {
         if (evt.name === 'mouseleave') {
@@ -264,9 +234,8 @@ export default class TooltipManager extends DomEmitterMixin() {
     /**
      * Handles hiding tooltips on `scroll` in DOM.
      *
-     * @private
-     * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
-     * @param {Event} domEvent The DOM event.
+     * @param evt An object containing information about the fired event.
+     * @param domEvent The DOM event.
      */
     _onScroll(evt, { target }) {
         // No tooltip, no reason to react on scroll.
@@ -284,12 +253,9 @@ export default class TooltipManager extends DomEmitterMixin() {
     /**
      * Pins the tooltip to a specific DOM element.
      *
-     * @private
-     * @param {Element} targetDomElement
-     * @param {Object} options
-     * @param {String} options.text Text of the tooltip to display.
-     * @param {String} options.position The position of the tooltip.
-     * @param {String} options.cssClass Additional CSS class of the balloon with the tooltip.
+     * @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.
      */
     _pinTooltip(targetDomElement, { text, position, cssClass }) {
         // Use the body collection of the first editor.
@@ -323,8 +289,6 @@ export default class TooltipManager extends DomEmitterMixin() {
     }
     /**
      * Unpins the tooltip and cancels all queued pinning.
-     *
-     * @private
      */
     _unpinTooltip() {
         this._pinTooltipDebounced.cancel();
@@ -342,8 +306,6 @@ export default class TooltipManager extends DomEmitterMixin() {
      * 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.
-     *
-     * @private
      */
     _updateTooltipPosition() {
         // This could happen if the tooltip was attached somewhere in a contextual content toolbar and the toolbar
@@ -361,9 +323,6 @@ export default class TooltipManager extends DomEmitterMixin() {
 /**
  * A set of default {@link module:utils/dom/position~PositioningFunction positioning functions} used by the `TooltipManager`
  * to pin tooltips in different positions.
- *
- * @member {Object.<String,module:utils/dom/position~PositioningFunction>}
- * module:ui/tooltipmanager~TooltipManager.defaultBalloonPositions
  */
 TooltipManager.defaultBalloonPositions = generatePositions({
     heightOffset: 5,
@@ -372,17 +331,11 @@ TooltipManager.defaultBalloonPositions = generatePositions({
 /**
  * A set of editors the single tooltip manager instance must listen to.
  * This is mostly to handle `EditorUI#update` listeners from individual editors.
- *
- * @private
- * @member {Set.<module:core/editor/editor~Editor>} module:ui/tooltipmanager~TooltipManager._editors
  */
 TooltipManager._editors = new Set();
 /**
  * A reference to the `TooltipManager` instance. The class is a singleton and as such,
  * successive attempts at creating instances should return this instance.
- *
- * @private
- * @member {module:ui/tooltipmanager~TooltipManager} module:ui/tooltipmanager~TooltipManager._instance
  */
 TooltipManager._instance = null;
 function getDescendantWithTooltip(element) {

package/src/uiconfig.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @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 { ToolbarConfig } from '@ckeditor/ckeditor5-core';
+/**
+ * @module ui/uiconfig
+ */
+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;
+    }
+}

package/src/uiconfig.js

@@ -0,0 +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 {};