@ckeditor/ckeditor5-ui 41.3.1 → 41.4.0

package/dist/types/panel/balloon/balloonpanelview.d.ts

@@ -0,0 +1,689 @@
+/**
+ * @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/panel/balloon/balloonpanelview
+ */
+import View from '../../view.js';
+import type ViewCollection from '../../viewcollection.js';
+import { type Locale, type PositionOptions, type PositioningFunction } from '@ckeditor/ckeditor5-utils';
+import '../../../theme/components/panel/balloonpanel.css';
+/**
+ * The balloon panel view class.
+ *
+ * A floating container which can
+ * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#pin pin} to any
+ * {@link module:utils/dom/position~Options#target target} in the DOM and remain in that position
+ * e.g. when the web page is scrolled.
+ *
+ * The balloon panel can be used to display contextual, non-blocking UI like forms, toolbars and
+ * the like in its {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#content} view
+ * collection.
+ *
+ * There is a number of {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}
+ * that the balloon can use, automatically switching from one to another when the viewport space becomes
+ * scarce to keep the balloon visible to the user as long as it is possible. The balloon will also
+ * accept any custom position set provided by the user compatible with the
+ * {@link module:utils/dom/position~Options options}.
+ *
+ * ```ts
+ * const panel = new BalloonPanelView( locale );
+ * const childView = new ChildView();
+ * const positions = BalloonPanelView.defaultPositions;
+ *
+ * panel.render();
+ *
+ * // Add a child view to the panel's content collection.
+ * panel.content.add( childView );
+ *
+ * // Start pinning the panel to an element with the "target" id DOM.
+ * // The balloon will remain pinned until unpin() is called.
+ * panel.pin( {
+ * 	target: document.querySelector( '#target' ),
+ * 	positions: [
+ * 		positions.northArrowSouth,
+ * 		positions.southArrowNorth
+ * 	]
+ * } );
+ * ```
+ */
+export default class BalloonPanelView extends View {
+    /**
+     * A collection of the child views that creates the balloon panel contents.
+     */
+    readonly content: ViewCollection;
+    /**
+     * The absolute top position of the balloon panel in pixels.
+     *
+     * @observable
+     * @default 0
+     */
+    top: number;
+    /**
+     * The absolute left position of the balloon panel in pixels.
+     *
+     * @observable
+     * @default 0
+     */
+    left: number;
+    /**
+     * The balloon panel's current position. The position name is reflected in the CSS class set
+     * to the balloon, i.e. `.ck-balloon-panel_arrow_nw` for the "arrow_nw" position. The class
+     * controls the minor aspects of the balloon's visual appearance like the placement
+     * of an {@link #withArrow arrow}. To support a new position, an additional CSS must be created.
+     *
+     * Default position names correspond with
+     * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
+     *
+     * See the {@link #attachTo} and {@link #pin} methods to learn about custom balloon positions.
+     *
+     * @observable
+     * @default 'arrow_nw'
+     */
+    position: 'arrow_nw' | 'arrow_ne' | 'arrow_sw' | 'arrow_se';
+    /**
+     * Controls whether the balloon panel is visible or not.
+     *
+     * @observable
+     * @default false
+     */
+    isVisible: boolean;
+    /**
+     * Controls whether the balloon panel has an arrow. The presence of the arrow
+     * is reflected in the `ck-balloon-panel_with-arrow` CSS class.
+     *
+     * @observable
+     * @default true
+     */
+    withArrow: boolean;
+    /**
+     * An additional CSS class added to the {@link #element}.
+     *
+     * @observable
+     */
+    class: string | undefined;
+    /**
+     * A callback that starts pinning the panel when {@link #isVisible} gets
+     * `true`. Used by {@link #pin}.
+     *
+     * @private
+     */
+    private _pinWhenIsVisibleCallback;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * Shows the panel.
+     *
+     * See {@link #isVisible}.
+     */
+    show(): void;
+    /**
+     * Hides the panel.
+     *
+     * See {@link #isVisible}.
+     */
+    hide(): void;
+    /**
+     * Attaches the panel to a specified {@link module:utils/dom/position~Options#target} with a
+     * smart positioning heuristics that chooses from available positions to make sure the panel
+     * is visible to the user i.e. within the limits of the viewport.
+     *
+     * This method accepts configuration {@link module:utils/dom/position~Options options}
+     * to set the `target`, optional `limiter` and `positions` the balloon should choose from.
+     *
+     * ```ts
+     * const panel = new BalloonPanelView( locale );
+     * const positions = BalloonPanelView.defaultPositions;
+     *
+     * panel.render();
+     *
+     * // Attach the panel to an element with the "target" id DOM.
+     * panel.attachTo( {
+     * 	target: document.querySelector( '#target' ),
+     * 	positions: [
+     * 		positions.northArrowSouth,
+     * 		positions.southArrowNorth
+     * 	]
+     * } );
+     * ```
+     *
+     * **Note**: Attaching the panel will also automatically {@link #show} it.
+     *
+     * **Note**: An attached panel will not follow its target when the window is scrolled or resized.
+     * See the {@link #pin} method for a more permanent positioning strategy.
+     *
+     * @param options Positioning options compatible with {@link module:utils/dom/position~getOptimalPosition}.
+     * Default `positions` array is {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
+     */
+    attachTo(options: Partial<PositionOptions>): void;
+    /**
+     * Works the same way as the {@link #attachTo} method except that the position of the panel is
+     * continuously updated when:
+     *
+     * * any ancestor of the {@link module:utils/dom/position~Options#target}
+     * or {@link module:utils/dom/position~Options#limiter} is scrolled,
+     * * the browser window gets resized or scrolled.
+     *
+     * Thanks to that, the panel always sticks to the {@link module:utils/dom/position~Options#target}
+     * and is immune to the changing environment.
+     *
+     * ```ts
+     * const panel = new BalloonPanelView( locale );
+     * const positions = BalloonPanelView.defaultPositions;
+     *
+     * panel.render();
+     *
+     * // Pin the panel to an element with the "target" id DOM.
+     * panel.pin( {
+     * 	target: document.querySelector( '#target' ),
+     * 	positions: [
+     * 		positions.northArrowSouth,
+     * 		positions.southArrowNorth
+     * 	]
+     * } );
+     * ```
+     *
+     * To leave the pinned state, use the {@link #unpin} method.
+     *
+     * **Note**: Pinning the panel will also automatically {@link #show} it.
+     *
+     * @param options Positioning options compatible with {@link module:utils/dom/position~getOptimalPosition}.
+     * Default `positions` array is {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
+     */
+    pin(options: Partial<PositionOptions>): void;
+    /**
+     * Stops pinning the panel, as set up by {@link #pin}.
+     */
+    unpin(): void;
+    /**
+     * Starts managing the pinned state of the panel. See {@link #pin}.
+     *
+     * @param options Positioning options compatible with {@link module:utils/dom/position~getOptimalPosition}.
+     */
+    private _startPinning;
+    /**
+     * Stops managing the pinned state of the panel. See {@link #pin}.
+     */
+    private _stopPinning;
+    /**
+     * A side offset of the arrow tip from the edge of the balloon. Controlled by CSS.
+     *
+     * ```
+     *		 ┌───────────────────────┐
+     *		 │                       │
+     *		 │         Balloon       │
+     *		 │         Content       │
+     *		 │                       │
+     *		 └──+    +───────────────┘
+     *		 |   \  /
+     *		 |    \/
+     *		>┼─────┼< ─────────────────────── side offset
+     *
+     * ```
+     *
+     * @default 25
+     */
+    static arrowSideOffset: number;
+    /**
+     * A height offset of the arrow from the edge of the balloon. Controlled by CSS.
+     *
+     * ```
+     *		 ┌───────────────────────┐
+     *		 │                       │
+     *		 │         Balloon       │
+     *		 │         Content       │      ╱-- arrow height offset
+     *		 │                       │      V
+     *		 └──+    +───────────────┘ --- ─┼───────
+     *		     \  /                       │
+     *		      \/                        │
+     *		────────────────────────────────┼───────
+     *		                                ^
+     *
+     *
+     *		>┼────┼<  arrow height offset
+     *		 │    │
+     *		 │    ┌────────────────────────┐
+     *		 │    │                        │
+     *		 │   ╱                         │
+     *		 │ ╱            Balloon        │
+     *		 │ ╲            Content        │
+     *		 │   ╲                         │
+     *		 │    │                        │
+     *		 │    └────────────────────────┘
+     * ```
+     *
+     * @default 10
+    */
+    static arrowHeightOffset: number;
+    /**
+     * A vertical offset of the balloon panel from the edge of the viewport if sticky.
+     * It helps in accessing toolbar buttons underneath the balloon panel.
+     *
+     * ```
+     *		  ┌───────────────────────────────────────────────────┐
+     *		  │                      Target                       │
+     *		  │                                                   │
+     *		  │                            /── vertical offset    │
+     *		┌─────────────────────────────V─────────────────────────┐
+     *		│ Toolbar            ┌─────────────┐                    │
+     *		├────────────────────│   Balloon   │────────────────────┤
+     *		│ │                  └─────────────┘                  │ │
+     *		│ │                                                   │ │
+     *		│ │                                                   │ │
+     *		│ │                                                   │ │
+     *		│ └───────────────────────────────────────────────────┘ │
+     *		│                        Viewport                       │
+     *		└───────────────────────────────────────────────────────┘
+     * ```
+     *
+     * @default 20
+     */
+    static stickyVerticalOffset: number;
+    /**
+     * Function used to calculate the optimal position for the balloon.
+     */
+    private static _getOptimalPosition;
+    /**
+     * A default set of positioning functions used by the balloon panel view
+     * when attaching using the {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#attachTo} method.
+     *
+     * The available positioning functions are as follows:
+     *
+     * **North west**
+     *
+     * * `northWestArrowSouthWest`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		 V
+     *		 [ Target ]
+     * ```
+     *
+     * * `northWestArrowSouthMiddleWest`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		    V
+     *		    [ Target ]
+     * ```
+     *
+     * * `northWestArrowSouth`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		         V
+     *		         [ Target ]
+     * ```
+     *
+     * * `northWestArrowSouthMiddleEast`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		             V
+     *		             [ Target ]
+     * ```
+     *
+     * * `northWestArrowSouthEast`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		                 V
+     *		                 [ Target ]
+     * ```
+     *
+     * **North**
+     *
+     * * `northArrowSouthWest`
+     *
+     * ```
+     *		    +-----------------+
+     *		    |     Balloon     |
+     *		    +-----------------+
+     *		     V
+     *		[ Target ]
+     * ```
+     *
+     * * `northArrowSouthMiddleWest`
+     *
+     * ```
+     *		 +-----------------+
+     *		 |     Balloon     |
+     *		 +-----------------+
+     *		     V
+     *		[ Target ]
+     * ```
+     * * `northArrowSouth`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		         V
+     *		    [ Target ]
+     * ```
+     *
+     * * `northArrowSouthMiddleEast`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		             V
+     *		        [ Target ]
+     * ```
+     *
+     * * `northArrowSouthEast`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		                V
+     *		           [ Target ]
+     * ```
+     *
+     * **North east**
+     *
+     * * `northEastArrowSouthWest`
+     *
+     * ```
+     *		        +-----------------+
+     *		        |     Balloon     |
+     *		        +-----------------+
+     *		         V
+     *		[ Target ]
+     * ```
+     *
+     * * `northEastArrowSouthMiddleWest`
+     *
+     * ```
+     *		     +-----------------+
+     *		     |     Balloon     |
+     *		     +-----------------+
+     *		         V
+     *		[ Target ]
+     * ```
+     *
+     * * `northEastArrowSouth`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		         V
+     *		[ Target ]
+     * ```
+     *
+     * * `northEastArrowSouthMiddleEast`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		             V
+     *		    [ Target ]
+     * ```
+     *
+     * * `northEastArrowSouthEast`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     *		                 V
+     *		        [ Target ]
+     * ```
+     *
+     * **South**
+     *
+     * * `southArrowNorthWest`
+     *
+     * ```
+     *		[ Target ]
+     *		     ^
+     *		    +-----------------+
+     *		    |     Balloon     |
+     *		    +-----------------+
+     * ```
+     *
+     * * `southArrowNorthMiddleWest`
+     *
+     * ```
+     *		   [ Target ]
+     *		        ^
+     *		    +-----------------+
+     *		    |     Balloon     |
+     *		    +-----------------+
+     * ```
+     *
+     * * `southArrowNorth`
+     *
+     * ```
+     *		    [ Target ]
+     *		         ^
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     * ```
+     *
+     * * `southArrowNorthMiddleEast`
+     *
+     * ```
+     *		            [ Target ]
+     *		                 ^
+     *		   +-----------------+
+     *		   |     Balloon     |
+     *		   +-----------------+
+     * ```
+     *
+     * * `southArrowNorthEast`
+     *
+     * ```
+     *		            [ Target ]
+     *		                 ^
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     * ```
+     *
+     * **South west**
+     *
+     * * `southWestArrowNorthWest`
+     *
+     *
+     * ```
+     *		 [ Target ]
+     *		 ^
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     * ```
+     *
+     * * `southWestArrowNorthMiddleWest`
+     *
+     * ```
+     *		     [ Target ]
+     *		     ^
+     *		 +-----------------+
+     *		 |     Balloon     |
+     *		 +-----------------+
+     * ```
+     *
+     * * `southWestArrowNorth`
+     *
+     * ```
+     *		         [ Target ]
+     *		         ^
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     * ```
+     *
+     * * `southWestArrowNorthMiddleEast`
+     *
+     * ```
+     *		              [ Target ]
+     *		              ^
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     * ```
+     *
+     * * `southWestArrowNorthEast`
+     *
+     * ```
+     *		                 [ Target ]
+     *		                 ^
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     * ```
+     *
+     * **South east**
+     *
+     * * `southEastArrowNorthWest`
+     *
+     * ```
+     *		[ Target ]
+     *		         ^
+     *		        +-----------------+
+     *		        |     Balloon     |
+     *		        +-----------------+
+     * ```
+     *
+     * * `southEastArrowNorthMiddleWest`
+     *
+     * ```
+     *		   [ Target ]
+     *		            ^
+     *		        +-----------------+
+     *		        |     Balloon     |
+     *		        +-----------------+
+     * ```
+     *
+     * * `southEastArrowNorth`
+     *
+     * ```
+     *		[ Target ]
+     *		         ^
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     * ```
+     *
+     * * `southEastArrowNorthMiddleEast`
+     *
+     * ```
+     *		     [ Target ]
+     *		              ^
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     * ```
+     *
+     * * `southEastArrowNorthEast`
+     *
+     * ```
+     *		        [ Target ]
+     *		                 ^
+     *		+-----------------+
+     *		|     Balloon     |
+     *		+-----------------+
+     * ```
+     *
+     * **West**
+     *
+     * * `westArrowEast`
+     *
+     * ```
+     *		+-----------------+
+     *		|     Balloon     |>[ Target ]
+     *		+-----------------+
+     * ```
+     *
+     * **East**
+     *
+     * * `eastArrowWest`
+     *
+     * ```
+     *		           +-----------------+
+     *		[ Target ]<|     Balloon     |
+     *		           +-----------------+
+     * ```
+     *
+     * **Sticky**
+     *
+     * * `viewportStickyNorth`
+     *
+     * ```
+     *		    +---------------------------+
+     *		    |        [ Target ]         |
+     *		    |                           |
+     *		+-----------------------------------+
+     *		|   |    +-----------------+    |   |
+     *		|   |    |     Balloon     |    |   |
+     *		|   |    +-----------------+    |   |
+     *		|   |                           |   |
+     *		|   |                           |   |
+     *		|   |                           |   |
+     *		|   |                           |   |
+     *		|   +---------------------------+   |
+     *		|             Viewport              |
+     *		+-----------------------------------+
+     * ```
+     *
+     * See {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#attachTo}.
+     *
+     * Positioning functions must be compatible with {@link module:utils/dom/position~DomPoint}.
+     *
+     * Default positioning functions with customized offsets can be generated using
+     * {@link module:ui/panel/balloon/balloonpanelview~generatePositions}.
+     *
+     * The name that the position function returns will be reflected in the balloon panel's class that
+     * controls the placement of the "arrow". See {@link #position} to learn more.
+     */
+    static defaultPositions: Record<string, PositioningFunction>;
+}
+/**
+ * Returns available {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
+ * {@link module:utils/dom/position~PositioningFunction positioning functions} adjusted by the specific offsets.
+ *
+ * @internal
+ * @param options Options to generate positions. If not specified, this helper will simply return
+ * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
+ * @param options.sideOffset A custom side offset (in pixels) of each position. If
+ * not specified, {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.arrowSideOffset the default value}
+ * will be used.
+ * @param options.heightOffset A custom height offset (in pixels) of each position. If
+ * not specified, {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.arrowHeightOffset the default value}
+ * will be used.
+ * @param options.stickyVerticalOffset A custom offset (in pixels) of the `viewportStickyNorth` positioning function.
+ * If not specified, {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.stickyVerticalOffset the default value}
+ * will be used.
+ * @param options.config Additional configuration of the balloon balloon panel view.
+ * Currently only {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#withArrow} is supported. Learn more
+ * about {@link module:utils/dom/position~PositioningFunction positioning functions}.
+ */
+export declare function generatePositions(options?: {
+    sideOffset?: number;
+    heightOffset?: number;
+    stickyVerticalOffset?: number;
+    config?: object;
+}): Record<string, PositioningFunction>;