@ckeditor/ckeditor5-ui 36.0.1 → 37.0.0-alpha.1

package/src/panel/balloon/contextualballoon.js

@@ -5,10 +5,10 @@
 /**
  * @module ui/panel/balloon/contextualballoon
  */
-import { Plugin } from '@ckeditor/ckeditor5-core';
 import BalloonPanelView from './balloonpanelview';
 import View from '../../view';
 import ButtonView from '../../button/buttonview';
+import { Plugin } from '@ckeditor/ckeditor5-core';
 import { CKEditorError, FocusTracker, Rect, toUnit } from '@ckeditor/ckeditor5-utils';
 import prevIcon from '../../../theme/icons/previous-arrow.svg';
 import nextIcon from '../../../theme/icons/next-arrow.svg';
@@ -48,8 +48,6 @@ const toPx = toUnit('px');
  * used to manage multiple panel stacks. Rotator view is a child of the balloon panel view and the parent of the specific
  * view you want to display. If there is more than one panel stack to be displayed, the rotator view will add a
  * navigation bar. If there is only one stack, the rotator view is transparent (it does not add any UI elements).
- *
- * @extends module:core/plugin~Plugin
  */
 export default class ContextualBalloon extends Plugin {
     /**
@@ -63,84 +61,39 @@ export default class ContextualBalloon extends Plugin {
      */
     constructor(editor) {
         super(editor);
-        this._view = null;
-        this._rotatorView = null;
-        this._fakePanelsView = null;
-        /**
-         * The {@link module:utils/dom/position~Options#limiter position limiter}
-         * for the {@link #view balloon}, used when no `limiter` has been passed into {@link #add}
-         * or {@link #updatePosition}.
-         *
-         * By default, a function that obtains the farthest DOM
-         * {@link module:engine/view/rooteditableelement~RootEditableElement}
-         * of the {@link module:engine/view/document~Document#selection}.
-         *
-         * @member {module:utils/dom/position~Options#limiter} #positionLimiter
-         */
-        this.positionLimiter = () => {
-            const view = this.editor.editing.view;
-            const viewDocument = view.document;
-            const editableElement = viewDocument.selection.editableElement;
-            if (editableElement) {
-                return view.domConverter.mapViewToDom(editableElement.root);
-            }
-            return null;
-        };
-        /**
-         * The currently visible view or `null` when there are no views in any stack.
-         *
-         * @readonly
-         * @observable
-         * @member {module:ui/view~View|null} #visibleView
-         */
-        this.set('visibleView', null);
         /**
          * The map of views and their stacks.
-         *
-         * @private
-         * @type {Map.<module:ui/view~View,Set>}
          */
         this._viewToStack = new Map();
         /**
          * The map of IDs and stacks.
-         *
-         * @private
-         * @type {Map.<String,Set>}
          */
         this._idToStack = new Map();
         /**
-         * A total number of all stacks in the balloon.
-         *
-         * @private
-         * @readonly
-         * @observable
-         * @member {Number} #_numberOfStacks
+         * The common balloon panel view.
          */
-        this.set('_numberOfStacks', 0);
-        /**
-         * A flag that controls the single view mode.
-         *
-         * @private
-         * @readonly
-         * @observable
-         * @member {Boolean} #_singleViewMode
-         */
-        this.set('_singleViewMode', false);
+        this._view = null;
         /**
          * Rotator view embedded in the contextual balloon.
          * Displays the currently visible view in the balloon and provides navigation for switching stacks.
-         *
-         * @private
-         * @type {module:ui/panel/balloon/contextualballoon~RotatorView}
          */
         this._rotatorView = null;
         /**
          * Displays fake panels under the balloon panel view when multiple stacks are added to the balloon.
-         *
-         * @private
-         * @type {module:ui/view~View}
          */
         this._fakePanelsView = null;
+        this.positionLimiter = () => {
+            const view = this.editor.editing.view;
+            const viewDocument = view.document;
+            const editableElement = viewDocument.selection.editableElement;
+            if (editableElement) {
+                return view.domConverter.mapViewToDom(editableElement.root);
+            }
+            return null;
+        };
+        this.set('visibleView', null);
+        this.set('_numberOfStacks', 0);
+        this.set('_singleViewMode', false);
     }
     /**
      * @inheritDoc
@@ -168,9 +121,6 @@ export default class ContextualBalloon extends Plugin {
     }
     /**
      * Returns `true` when the given view is in one of the stacks. Otherwise returns `false`.
-     *
-     * @param {module:ui/view~View} view
-     * @returns {Boolean}
      */
     hasView(view) {
         return Array.from(this._viewToStack.keys()).includes(view);
@@ -179,13 +129,13 @@ export default class ContextualBalloon extends Plugin {
      * Adds a new view to the stack and makes it visible if the current stack is visible
      * or it is the first view in the balloon.
      *
-     * @param {Object} data The configuration of the view.
-     * @param {String} [data.stackId='main'] The ID of the stack that the view is added to.
-     * @param {module:ui/view~View} [data.view] The content of the balloon.
-     * @param {module:utils/dom/position~Options} [data.position] Positioning options.
-     * @param {String} [data.balloonClassName] An additional CSS class added to the {@link #view balloon} when visible.
-     * @param {Boolean} [data.withArrow=true] Whether the {@link #view balloon} should be rendered with an arrow.
-     * @param {Boolean} [data.singleViewMode=false] Whether the view should be the only visible view even if other stacks were added.
+     * @param data The configuration of the view.
+     * @param data.stackId The ID of the stack that the view is added to. Defaults to `'main'`.
+     * @param data.view The content of the balloon.
+     * @param data.position Positioning options.
+     * @param data.balloonClassName An additional CSS class added to the {@link #view balloon} when visible.
+     * @param data.withArrow Whether the {@link #view balloon} should be rendered with an arrow. Defaults to `true`.
+     * @param data.singleViewMode Whether the view should be the only visible view even if other stacks were added. Defaults to `false`.
      */
     add(data) {
         if (!this._view) {
@@ -228,7 +178,7 @@ export default class ContextualBalloon extends Plugin {
      * When there is no view in the stack, the next stack will be displayed.
      * When there are no more stacks, the balloon will hide.
      *
-     * @param {module:ui/view~View} view A view to be removed from the balloon.
+     * @param view A view to be removed from the balloon.
      */
     remove(view) {
         if (!this.hasView(view)) {
@@ -273,7 +223,7 @@ export default class ContextualBalloon extends Plugin {
      * Updates the position of the balloon using the position data of the first visible view in the stack.
      * When new position data is given, the position data of the currently visible view will be updated.
      *
-     * @param {module:utils/dom/position~Options} [position] position options.
+     * @param position Position options.
      */
     updatePosition(position) {
         if (position) {
@@ -284,8 +234,6 @@ export default class ContextualBalloon extends Plugin {
     }
     /**
      * Shows the last view from the stack of a given ID.
-     *
-     * @param {String} id
      */
     showStack(id) {
         this.visibleStack = id;
@@ -315,19 +263,12 @@ export default class ContextualBalloon extends Plugin {
     }
     /**
      * Returns the stack of the currently visible view.
-     *
-     * @private
-     * @type {Set}
      */
     get _visibleStack() {
         return this._viewToStack.get(this.visibleView);
     }
     /**
      * Returns the ID of the given stack.
-     *
-     * @private
-     * @param {Set} stack
-     * @returns {String}
      */
     _getStackId(stack) {
         const entry = Array.from(this._idToStack.entries()).find(entry => entry[1] === stack);
@@ -335,8 +276,6 @@ export default class ContextualBalloon extends Plugin {
     }
     /**
      * Shows the last view from the next stack.
-     *
-     * @private
      */
     _showNextStack() {
         const stacks = Array.from(this._idToStack.values());
@@ -348,8 +287,6 @@ export default class ContextualBalloon extends Plugin {
     }
     /**
      * Shows the last view from the previous stack.
-     *
-     * @private
      */
     _showPrevStack() {
         const stacks = Array.from(this._idToStack.values());
@@ -361,9 +298,6 @@ export default class ContextualBalloon extends Plugin {
     }
     /**
      * Creates a rotator view.
-     *
-     * @private
-     * @returns {module:ui/panel/balloon/contextualballoon~RotatorView}
      */
     _createRotatorView() {
         const view = new RotatorView(this.editor.locale);
@@ -402,8 +336,7 @@ export default class ContextualBalloon extends Plugin {
         return view;
     }
     /**
-     * @private
-     * @returns {module:ui/view~View}
+     * Creates a fake panels view.
      */
     _createFakePanelsView() {
         const view = new FakePanelsView(this.editor.locale, this.view);
@@ -420,11 +353,10 @@ export default class ContextualBalloon extends Plugin {
      * Sets the view as the content of the balloon and attaches the balloon using position
      * options of the first view.
      *
-     * @private
-     * @param {Object} data Configuration.
-     * @param {module:ui/view~View} [data.view] The view to show in the balloon.
-     * @param {String} [data.balloonClassName=''] Additional class name which will be added to the {@link #view balloon}.
-     * @param {Boolean} [data.withArrow=true] Whether the {@link #view balloon} should be rendered with an arrow.
+     * @param data Configuration.
+     * @param data.view The view to show in the balloon.
+     * @param data.balloonClassName Additional class name which will be added to the {@link #view balloon}.
+     * @param data.withArrow Whether the {@link #view balloon} should be rendered with an arrow.
      */
     _showView({ view, balloonClassName = '', withArrow = true, singleViewMode = false }) {
         this.view.class = balloonClassName;
@@ -440,9 +372,6 @@ export default class ContextualBalloon extends Plugin {
     /**
      * Returns position options of the last view in the stack.
      * This keeps the balloon in the same position when the view is changed.
-     *
-     * @private
-     * @returns {module:utils/dom/position~Options}
      */
     _getBalloonPosition() {
         let position = Array.from(this._visibleStack.values()).pop().position;
@@ -466,10 +395,8 @@ export default class ContextualBalloon extends Plugin {
  * Rotator view is a helper class for the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon ContextualBalloon}.
  * It is used for displaying the last view from the current stack and providing navigation buttons for switching stacks.
  * See the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon ContextualBalloon} documentation to learn more.
- *
- * @extends module:ui/view~View
  */
-class RotatorView extends View {
+export class RotatorView extends View {
     /**
      * @inheritDoc
      */
@@ -477,36 +404,10 @@ class RotatorView extends View {
         super(locale);
         const t = locale.t;
         const bind = this.bindTemplate;
-        /**
-         * Defines whether navigation is visible or not.
-         *
-         * @member {Boolean} #isNavigationVisible
-         */
         this.set('isNavigationVisible', true);
-        /**
-         * Used for checking if a view is focused or not.
-         *
-         * @type {module:utils/focustracker~FocusTracker}
-         */
         this.focusTracker = new FocusTracker();
-        /**
-         * Navigation button for switching the stack to the previous one.
-         *
-         * @type {module:ui/button/buttonview~ButtonView}
-         */
         this.buttonPrevView = this._createButtonView(t('Previous'), prevIcon);
-        /**
-         * Navigation button for switching the stack to the next one.
-         *
-         * @type {module:ui/button/buttonview~ButtonView}
-         */
         this.buttonNextView = this._createButtonView(t('Next'), nextIcon);
-        /**
-         * A collection of the child views that creates the rotator content.
-         *
-         * @readonly
-         * @type {module:ui/viewcollection~ViewCollection}
-         */
         this.content = this.createCollection();
         this.setTemplate({
             tag: 'div',
@@ -571,7 +472,7 @@ class RotatorView extends View {
     /**
      * Shows a given view.
      *
-     * @param {module:ui/view~View} view The view to show.
+     * @param view The view to show.
      */
     showView(view) {
         this.hideView();
@@ -586,10 +487,8 @@ class RotatorView extends View {
     /**
      * Creates a navigation button view.
      *
-     * @private
-     * @param {String} label The button label.
-     * @param {String} icon The button icon.
-     * @returns {module:ui/button/buttonview~ButtonView}
+     * @param label The button label.
+     * @param icon The button icon.
      */
     _createButtonView(label, icon) {
         const view = new ButtonView(this.locale);
@@ -601,49 +500,22 @@ class RotatorView extends View {
         return view;
     }
 }
-// Displays additional layers under the balloon when multiple stacks are added to the balloon.
-//
-// @private
-// @extends module:ui/view~View
+/**
+ * Displays additional layers under the balloon when multiple stacks are added to the balloon.
+ */
 class FakePanelsView extends View {
-    // @inheritDoc
+    /**
+     * @inheritDoc
+     */
     constructor(locale, balloonPanelView) {
         super(locale);
         const bind = this.bindTemplate;
-        // Fake panels top offset.
-        //
-        // @observable
-        // @member {Number} #top
         this.set('top', 0);
-        // Fake panels left offset.
-        //
-        // @observable
-        // @member {Number} #left
         this.set('left', 0);
-        // Fake panels height.
-        //
-        // @observable
-        // @member {Number} #height
         this.set('height', 0);
-        // Fake panels width.
-        //
-        // @observable
-        // @member {Number} #width
         this.set('width', 0);
-        // Number of rendered fake panels.
-        //
-        // @observable
-        // @member {Number} #numberOfPanels
         this.set('numberOfPanels', 0);
-        // Collection of the child views which creates fake panel content.
-        //
-        // @readonly
-        // @type {module:ui/viewcollection~ViewCollection}
         this.content = this.createCollection();
-        // Context.
-        //
-        // @private
-        // @type {module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
         this._balloonPanelView = balloonPanelView;
         this.setTemplate({
             tag: 'div',
@@ -671,8 +543,6 @@ class FakePanelsView extends View {
             this.updatePosition();
         });
     }
-    // @private
-    // @param {Number} number
     _addPanels(number) {
         while (number--) {
             const view = new View();
@@ -681,8 +551,6 @@ class FakePanelsView extends View {
             this.registerChild(view);
         }
     }
-    // @private
-    // @param {Number} number
     _removePanels(number) {
         while (number--) {
             const view = this.content.last;
@@ -691,7 +559,9 @@ class FakePanelsView extends View {
             view.destroy();
         }
     }
-    // Updates coordinates of fake panels.
+    /**
+     * Updates coordinates of fake panels.
+     */
     updatePosition() {
         if (this.numberOfPanels) {
             const { top, left } = this._balloonPanelView;

package/src/panel/sticky/stickypanelview.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @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/panel/sticky/stickypanelview
+ */
+import View from '../../view';
+import type ViewCollection from '../../viewcollection';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../../theme/components/panel/stickypanel.css';
+/**
+ * The sticky panel view class.
+ */
+export default class StickyPanelView extends View {
+    /**
+     * Collection of the child views which creates balloon panel contents.
+     */
+    readonly content: ViewCollection;
+    /**
+     * Controls whether the sticky panel should be active.
+     *
+     * @readonly
+     * @observable
+     */
+    isActive: boolean;
+    /**
+     * Controls whether the sticky panel is in the "sticky" state.
+     *
+     * @readonly
+     * @observable
+     */
+    isSticky: boolean;
+    /**
+     * The limiter element for the sticky panel instance. Its bounding rect limits
+     * the "stickyness" of the panel, i.e. when the panel reaches the bottom
+     * edge of the limiter, it becomes sticky to that edge and does not float
+     * off the limiter. It is mandatory for the panel to work properly and once
+     * set, it cannot be changed.
+     *
+     * @readonly
+     * @observable
+     */
+    limiterElement: HTMLElement | null;
+    /**
+     * The offset from the bottom edge of {@link #limiterElement}
+     * which stops the panel from stickying any further to prevent limiter's content
+     * from being completely covered.
+     *
+     * @readonly
+     * @observable
+     * @default 50
+     */
+    limiterBottomOffset: number;
+    /**
+     * The offset from the top edge of the web browser's viewport which makes the
+     * panel become sticky. The default value is `0`, which means the panel becomes
+     * sticky when it's upper edge touches the top of the page viewport.
+     *
+     * This attribute is useful when the web page has UI elements positioned to the top
+     * either using `position: fixed` or `position: sticky`, which would cover the
+     * sticky panel or vice–versa (depending on the `z-index` hierarchy).
+     *
+     * Bound to {@link module:ui/editorui/editorui~EditorUI#viewportOffset `EditorUI#viewportOffset`}.
+     *
+     * If {@link module:core/editor/editorconfig~EditorConfig#ui `EditorConfig#ui.viewportOffset.top`} is defined, then
+     * it will override the default value.
+     *
+     * @observable
+     * @default 0
+     */
+    viewportTopOffset: number;
+    /**
+     * Controls the `margin-left` CSS style of the panel.
+     *
+     * @private
+     * @readonly
+     * @observable
+     */
+    _marginLeft: string | null;
+    /**
+     * Set `true` if the sticky panel reached the bottom edge of the
+     * {@link #limiterElement}.
+     *
+     * @private
+     * @readonly
+     * @observable
+     */
+    _isStickyToTheLimiter: boolean;
+    /**
+     * Set `true` if the sticky panel uses the {@link #viewportTopOffset},
+     * i.e. not {@link #_isStickyToTheLimiter} and the {@link #viewportTopOffset}
+     * is not `0`.
+     *
+     * @private
+     * @readonly
+     * @observable
+     */
+    _hasViewportTopOffset: boolean;
+    /**
+     * The DOM bounding client rect of the {@link module:ui/view~View#element} of the panel.
+     */
+    private _panelRect?;
+    /**
+     * The DOM bounding client rect of the {@link #limiterElement}
+     * of the panel.
+     */
+    private _limiterRect?;
+    /**
+     * A dummy element which visually fills the space as long as the
+     * actual panel is sticky. It prevents flickering of the UI.
+     */
+    private _contentPanelPlaceholder;
+    /**
+     * The panel which accepts children into {@link #content} collection.
+     * Also an element which is positioned when {@link #isSticky}.
+     */
+    private _contentPanel;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Analyzes the environment to decide whether the panel should
+     * be sticky or not.
+     */
+    private _checkIfShouldBeSticky;
+}

package/src/panel/sticky/stickypanelview.js

@@ -20,121 +20,15 @@ export default class StickyPanelView extends View {
     constructor(locale) {
         super(locale);
         const bind = this.bindTemplate;
-        /**
-         * Controls whether the sticky panel should be active.
-         *
-         * @readonly
-         * @observable
-         * @member {Boolean} #isActive
-         */
         this.set('isActive', false);
-        /**
-         * Controls whether the sticky panel is in the "sticky" state.
-         *
-         * @readonly
-         * @observable
-         * @member {Boolean} #isSticky
-         */
         this.set('isSticky', false);
-        /**
-         * The limiter element for the sticky panel instance. Its bounding rect limits
-         * the "stickyness" of the panel, i.e. when the panel reaches the bottom
-         * edge of the limiter, it becomes sticky to that edge and does not float
-         * off the limiter. It is mandatory for the panel to work properly and once
-         * set, it cannot be changed.
-         *
-         * @readonly
-         * @observable
-         * @member {HTMLElement} #limiterElement
-         */
         this.set('limiterElement', null);
-        /**
-         * The offset from the bottom edge of {@link #limiterElement}
-         * which stops the panel from stickying any further to prevent limiter's content
-         * from being completely covered.
-         *
-         * @readonly
-         * @observable
-         * @default 50
-         * @member {Number} #limiterBottomOffset
-         */
         this.set('limiterBottomOffset', 50);
-        /**
-         * The offset from the top edge of the web browser's viewport which makes the
-         * panel become sticky. The default value is `0`, which means the panel becomes
-         * sticky when it's upper edge touches the top of the page viewport.
-         *
-         * This attribute is useful when the web page has UI elements positioned to the top
-         * either using `position: fixed` or `position: sticky`, which would cover the
-         * sticky panel or vice–versa (depending on the `z-index` hierarchy).
-         *
-         * Bound to {@link module:core/editor/editorui~EditorUI#viewportOffset `EditorUI#viewportOffset`}.
-         *
-         * If {@link module:core/editor/editorconfig~EditorConfig#ui `EditorConfig#ui.viewportOffset.top`} is defined, then
-         * it will override the default value.
-         *
-         * @observable
-         * @default 0
-         * @member {Number} #viewportTopOffset
-         */
         this.set('viewportTopOffset', 0);
-        /**
-         * Controls the `margin-left` CSS style of the panel.
-         *
-         * @protected
-         * @readonly
-         * @observable
-         * @member {String} #_marginLeft
-         */
         this.set('_marginLeft', null);
-        /**
-         * Set `true` if the sticky panel reached the bottom edge of the
-         * {@link #limiterElement}.
-         *
-         * @protected
-         * @readonly
-         * @observable
-         * @member {Boolean} #_isStickyToTheLimiter
-         */
         this.set('_isStickyToTheLimiter', false);
-        /**
-         * Set `true` if the sticky panel uses the {@link #viewportTopOffset},
-         * i.e. not {@link #_isStickyToTheLimiter} and the {@link #viewportTopOffset}
-         * is not `0`.
-         *
-         * @protected
-         * @readonly
-         * @observable
-         * @member {Boolean} #_hasViewportTopOffset
-         */
         this.set('_hasViewportTopOffset', false);
-        /**
-         * Collection of the child views which creates balloon panel contents.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.content = this.createCollection();
-        /**
-         * The DOM bounding client rect of the {@link module:ui/view~View#element} of the panel.
-         *
-         * @protected
-         * @member {Object} #_panelRect
-         */
-        /**
-         * The DOM bounding client rect of the {@link #limiterElement}
-         * of the panel.
-         *
-         * @protected
-         * @member {Object} #_limiterRect
-         */
-        /**
-         * A dummy element which visually fills the space as long as the
-         * actual panel is sticky. It prevents flickering of the UI.
-         *
-         * @protected
-         * @property {HTMLElement}
-         */
         this._contentPanelPlaceholder = new Template({
             tag: 'div',
             attributes: {
@@ -150,13 +44,6 @@ export default class StickyPanelView extends View {
                 }
             }
         }).render();
-        /**
-         * The panel which accepts children into {@link #content} collection.
-         * Also an element which is positioned when {@link #isSticky}.
-         *
-         * @protected
-         * @property {HTMLElement}
-         */
         this._contentPanel = new Template({
             tag: 'div',
             attributes: {
@@ -215,8 +102,6 @@ export default class StickyPanelView extends View {
     /**
      * Analyzes the environment to decide whether the panel should
      * be sticky or not.
-     *
-     * @protected
      */
     _checkIfShouldBeSticky() {
         const panelRect = this._panelRect = this._contentPanel.getBoundingClientRect();