@ckeditor/ckeditor5-widget 36.0.1 → 37.0.0-alpha.0

package/src/widgetresize/resizerstate.js

@@ -8,105 +8,49 @@
 import { ObservableMixin, Rect } from '@ckeditor/ckeditor5-utils';
 /**
  * Stores the internal state of a single resizable object.
- *
  */
 export default class ResizeState extends ObservableMixin() {
     /**
-     * @param {module:widget/widgetresize~ResizerOptions} options Resizer options.
+     * @param options Resizer options.
      */
     constructor(options) {
         super();
-        /**
-         * The original width (pixels) of the resized object when the resize process was started.
-         *
-         * @readonly
-         * @member {Number} #originalWidth
-         */
-        /**
-         * The original height (pixels) of the resized object when the resize process was started.
-         *
-         * @readonly
-         * @member {Number} #originalHeight
-         */
-        /**
-         * The original width (percents) of the resized object when the resize process was started.
-         *
-         * @readonly
-         * @member {Number} #originalWidthPercents
-         */
-        /**
-         * The position of the handle that initiated the resizing. E.g. `"top-left"`, `"bottom-right"` etc. or `null`
-         * if unknown.
-         *
-         * @readonly
-         * @observable
-         * @member {String|null} #activeHandlePosition
-         */
         this.set('activeHandlePosition', null);
-        /**
-         * The width (percents) proposed, but not committed yet, in the current resize process.
-         *
-         * @readonly
-         * @observable
-         * @member {Number|null} #proposedWidthPercents
-         */
         this.set('proposedWidthPercents', null);
-        /**
-         * The width (pixels) proposed, but not committed yet, in the current resize process.
-         *
-         * @readonly
-         * @observable
-         * @member {Number|null} #proposedWidthPixels
-         */
         this.set('proposedWidth', null);
-        /**
-         * The height (pixels) proposed, but not committed yet, in the current resize process.
-         *
-         * @readonly
-         * @observable
-         * @member {Number|null} #proposedHeightPixels
-         */
         this.set('proposedHeight', null);
         this.set('proposedHandleHostWidth', null);
         this.set('proposedHandleHostHeight', null);
-        /**
-         * A width to height ratio of the resized image.
-         *
-         * @readonly
-         * @member {Number} #aspectRatio
-         */
-        /**
-         * @private
-         * @type {module:widget/widgetresize~ResizerOptions}
-         */
         this._options = options;
-        /**
-         * The reference point of the resizer where the dragging started. It is used to measure the distance the user cursor
-         * traveled, so how much the image should be enlarged.
-         * This information is only known after the DOM was rendered, so it will be updated later.
-         *
-         * @private
-         * @type {Object}
-         */
         this._referenceCoordinates = null;
     }
+    /**
+     * The original width (pixels) of the resized object when the resize process was started.
+     */
     get originalWidth() {
         return this._originalWidth;
     }
+    /**
+     * The original height (pixels) of the resized object when the resize process was started.
+     */
     get originalHeight() {
         return this._originalHeight;
     }
+    /**
+     * The original width (percents) of the resized object when the resize process was started.
+     */
     get originalWidthPercents() {
         return this._originalWidthPercents;
     }
+    /**
+     * A width to height ratio of the resized image.
+     */
     get aspectRatio() {
         return this._aspectRatio;
     }
     /**
      *
-     * @param {HTMLElement} domResizeHandle The handle used to calculate the reference point.
-     * @param {HTMLElement} domHandleHost
-     * @param {HTMLElement} domResizeHost
+     * @param domResizeHandle The handle used to calculate the reference point.
      */
     begin(domResizeHandle, domHandleHost, domResizeHost) {
         const clientRect = new Rect(domHandleHost);
@@ -131,26 +75,20 @@ export default class ResizeState extends ObservableMixin() {
         this.proposedHandleHostHeight = newSize.handleHostHeight;
     }
 }
-// Calculates a relative width of a `domResizeHost` compared to it's parent in percents.
-//
-// @private
-// @param {HTMLElement} domResizeHost
-// @param {module:utils/dom/rect~Rect} resizeHostRect
-// @returns {Number}
+/**
+ * Calculates a relative width of a `domResizeHost` compared to it's parent in percents.
+ */
 function calculateHostPercentageWidth(domResizeHost, resizeHostRect) {
     const domResizeHostParent = domResizeHost.parentElement;
     // Need to use computed style as it properly excludes parent's paddings from the returned value.
     const parentWidth = parseFloat(domResizeHostParent.ownerDocument.defaultView.getComputedStyle(domResizeHostParent).width);
     return resizeHostRect.width / parentWidth * 100;
 }
-// Returns coordinates of the top-left corner of an element, relative to the document's top-left corner.
-//
-// @private
-// @param {HTMLElement} element
-// @param {String} resizerPosition The position of the resize handle, e.g. `"top-left"`, `"bottom-right"`.
-// @returns {Object} return
-// @returns {Number} return.x
-// @returns {Number} return.y
+/**
+ * Returns coordinates of the top-left corner of an element, relative to the document's top-left corner.
+ *
+ * @param resizerPosition The position of the resize handle, e.g. `"top-left"`, `"bottom-right"`.
+ */
 function getAbsoluteBoundaryPoint(element, resizerPosition) {
     const elementRect = new Rect(element);
     const positionParts = resizerPosition.split('-');
@@ -162,17 +100,19 @@ function getAbsoluteBoundaryPoint(element, resizerPosition) {
     ret.y += element.ownerDocument.defaultView.scrollY;
     return ret;
 }
-// @private
-// @param {String} resizerPosition The expected resizer position, like `"top-left"`, `"bottom-right"`.
-// @returns {String} A prefixed HTML class name for the resizer element.
+/**
+ * @param resizerPosition The expected resizer position, like `"top-left"`, `"bottom-right"`.
+ * @returns A prefixed HTML class name for the resizer element.
+ */
 function getResizerHandleClass(resizerPosition) {
     return `ck-widget__resizer__handle-${resizerPosition}`;
 }
-// Determines the position of a given resize handle.
-//
-// @private
-// @param {HTMLElement} domHandle Handle used to calculate the reference point.
-// @returns {String|undefined} Returns a string like `"top-left"` or `undefined` if not matched.
+/**
+ * Determines the position of a given resize handle.
+ *
+ * @param domHandle Handle used to calculate the reference point.
+ * @returns Returns a string like `"top-left"` or `undefined` if not matched.
+ */
 function getHandlePosition(domHandle) {
     const resizerPositions = ['top-left', 'top-right', 'bottom-right', 'bottom-left'];
     for (const position of resizerPositions) {
@@ -181,9 +121,10 @@ function getHandlePosition(domHandle) {
         }
     }
 }
-// @private
-// @param {String} position Like `"top-left"`.
-// @returns {String} Inverted `position`, e.g. it returns `"bottom-right"` if `"top-left"` was given as `position`.
+/**
+ * @param position Like `"top-left"`.
+ * @returns Inverted `position`, e.g. it returns `"bottom-right"` if `"top-left"` was given as `position`.
+ */
 function getOppositePosition(position) {
     const parts = position.split('-');
     const replacements = {

package/src/widgetresize/sizeview.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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 widget/widgetresize/sizeview
+ */
+import { View } from '@ckeditor/ckeditor5-ui';
+import type { ResizerOptions } from '../widgetresize';
+import type ResizeState from './resizerstate';
+/**
+ * A view displaying the proposed new element size during the resizing.
+ */
+export default class SizeView extends View {
+    /**
+     * The visibility of the view defined based on the existence of the host proposed dimensions.
+     *
+     * @internal
+     * @observable
+     * @readonly
+     */
+    _isVisible: boolean;
+    /**
+     * The text that will be displayed in the `SizeView` child.
+     * It can be formatted as the pixel values (e.g. 10x20) or the percentage value (e.g. 10%).
+     *
+     * @internal
+     * @observable
+     * @readonly
+     */
+    _label: string;
+    /**
+     * The position of the view defined based on the host size and active handle position.
+     *
+     * @internal
+     * @observable
+     * @readonly
+     */
+    _viewPosition: string;
+    constructor();
+    /**
+     * A method used for binding the `SizeView` instance properties to the `ResizeState` instance observable properties.
+     *
+     * @internal
+     * @param options An object defining the resizer options, used for setting the proper size label.
+     * @param resizeState The `ResizeState` class instance, used for keeping the `SizeView` state up to date.
+     */
+    _bindToState(options: ResizerOptions, resizeState: ResizeState): void;
+    /**
+     * A method used for cleaning up. It removes the bindings and hides the view.
+     *
+     * @internal
+     */
+    _dismiss(): void;
+}

package/src/widgetresize/sizeview.js

@@ -8,38 +8,10 @@
 import { View } from '@ckeditor/ckeditor5-ui';
 /**
  * A view displaying the proposed new element size during the resizing.
- *
- * @protected
- * @extends {module:ui/view~View}
  */
 export default class SizeView extends View {
     constructor() {
         super();
-        /**
-         * The visibility of the view defined based on the existence of the host proposed dimensions.
-         *
-         * @private
-         * @observable
-         * @readonly
-         * @member {Boolean} #_isVisible
-         */
-        /**
-         * The text that will be displayed in the `SizeView` child.
-         * It can be formatted as the pixel values (e.g. 10x20) or the percentage value (e.g. 10%).
-         *
-         * @private
-         * @observable
-         * @readonly
-         * @member {Boolean} #_label
-         */
-        /**
-         * The position of the view defined based on the host size and active handle position.
-         *
-         * @private
-         * @observable
-         * @readonly
-         * @member {String} #_viewPosition
-         */
         const bind = this.bindTemplate;
         this.setTemplate({
             tag: 'div',
@@ -61,12 +33,9 @@ export default class SizeView extends View {
     /**
      * A method used for binding the `SizeView` instance properties to the `ResizeState` instance observable properties.
      *
-     * @protected
      * @internal
-     * @param {module:widget/widgetresize~ResizerOptions} options
-     * An object defining the resizer options, used for setting the proper size label.
-     * @param {module:widget/widgetresize/resizerstate~ResizeState} resizeState
-     * The `ResizeState` class instance, used for keeping the `SizeView` state up to date.
+     * @param options An object defining the resizer options, used for setting the proper size label.
+     * @param resizeState The `ResizeState` class instance, used for keeping the `SizeView` state up to date.
      */
     _bindToState(options, resizeState) {
         this.bind('_isVisible').to(resizeState, 'proposedWidth', resizeState, 'proposedHeight', (width, height) => width !== null && height !== null);
@@ -85,7 +54,6 @@ export default class SizeView extends View {
     /**
      * A method used for cleaning up. It removes the bindings and hides the view.
      *
-     * @protected
      * @internal
      */
     _dismiss() {

package/src/widgetresize.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @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 widget/widgetresize
+ */
+import Resizer from './widgetresize/resizer';
+import { Plugin, type Editor } from '@ckeditor/ckeditor5-core';
+import { type Element, type ViewContainerElement } from '@ckeditor/ckeditor5-engine';
+import '../theme/widgetresize.css';
+/**
+ * The widget resize feature plugin.
+ *
+ * Use the {@link module:widget/widgetresize~WidgetResize#attachTo} method to create a resizer for the specified widget.
+ */
+export default class WidgetResize extends Plugin {
+    /**
+     * The currently selected resizer.
+     *
+     * @observable
+     */
+    selectedResizer: Resizer | null;
+    /**
+     * References an active resizer.
+     *
+     * Active resizer means a resizer which handle is actively used by the end user.
+     *
+     * @internal
+     * @observable
+     */
+    _activeResizer: Resizer | null;
+    /**
+     * A map of resizers created using this plugin instance.
+     */
+    private _resizers;
+    private _observer;
+    private _redrawSelectedResizerThrottled;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'WidgetResize';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Redraws the selected resizer if there is any selected resizer and if it is visible.
+     */
+    redrawSelectedResizer(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Marks resizer as selected.
+     */
+    select(resizer: Resizer): void;
+    /**
+     * Deselects currently set resizer.
+     */
+    deselect(): void;
+    /**
+     * @param options Resizer options.
+     */
+    attachTo(options: ResizerOptions): Resizer;
+    /**
+     * Returns a resizer created for a given view element (widget element).
+     *
+     * @param viewElement View element associated with the resizer.
+     */
+    getResizerByViewElement(viewElement: ViewContainerElement): Resizer | undefined;
+    /**
+     * Returns a resizer that contains a given resize handle.
+     */
+    private _getResizerByHandle;
+    /**
+     * @param domEventData Native DOM event.
+     */
+    private _mouseDownListener;
+    /**
+     * @param domEventData Native DOM event.
+     */
+    private _mouseMoveListener;
+    private _mouseUpListener;
+}
+/**
+ * Interface describing a resizer. It allows to specify the resizing host, custom logic for calculating aspect ratio, etc.
+ */
+export interface ResizerOptions {
+    /**
+     * Editor instance associated with the resizer.
+     */
+    editor: Editor;
+    modelElement: Element;
+    /**
+     * A view of an element to be resized. Typically it's the main widget's view instance.
+     */
+    viewElement: ViewContainerElement;
+    unit?: 'px' | '%';
+    /**
+     * A callback to be executed once the resizing process is done.
+     *
+     * It receives a `Number` (`newValue`) as a parameter.
+     *
+     * For example, {@link module:image/imageresize~ImageResize} uses it to execute the resize image command
+     * which puts the new value into the model.
+     *
+     * ```ts
+     * {
+     *	editor,
+     *	modelElement: data.item,
+     *	viewElement: widget,
+     *
+     *	onCommit( newValue ) {
+     *		editor.execute( 'resizeImage', { width: newValue } );
+     *	}
+     * };
+     * ```
+     */
+    onCommit: (newValue: string) => void;
+    getResizeHost: (widgetWrapper: HTMLElement) => HTMLElement;
+    getHandleHost: (widgetWrapper: HTMLElement) => HTMLElement;
+    isCentered?: (resizer: Resizer) => boolean;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [WidgetResize.pluginName]: WidgetResize;
+    }
+}

package/src/widgetresize.js

@@ -15,11 +15,15 @@ import '../theme/widgetresize.css';
  * The widget resize feature plugin.
  *
  * Use the {@link module:widget/widgetresize~WidgetResize#attachTo} method to create a resizer for the specified widget.
- *
- * @extends module:core/plugin~Plugin
- * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class WidgetResize extends Plugin {
+    constructor() {
+        super(...arguments);
+        /**
+         * A map of resizers created using this plugin instance.
+         */
+        this._resizers = new Map();
+    }
     /**
      * @inheritDoc
      */
@@ -32,30 +36,8 @@ export default class WidgetResize extends Plugin {
     init() {
         const editing = this.editor.editing;
         const domDocument = global.window.document;
-        /**
-         * The currently selected resizer.
-         *
-         * @observable
-         * @member {module:widget/widgetresize/resizer~Resizer|null} #selectedResizer
-         */
         this.set('selectedResizer', null);
-        /**
-         * References an active resizer.
-         *
-         * Active resizer means a resizer which handle is actively used by the end user.
-         *
-         * @protected
-         * @observable
-         * @member {module:widget/widgetresize/resizer~Resizer|null} #_activeResizer
-         */
         this.set('_activeResizer', null);
-        /**
-         * A map of resizers created using this plugin instance.
-         *
-         * @protected
-         * @type {Map.<module:engine/view/containerelement~ContainerElement, module:widget/widgetresize/resizer~Resizer>}
-         */
-        this._resizers = new Map();
         editing.view.addObserver(MouseObserver);
         this._observer = new (DomEmitterMixin())();
         this.listenTo(editing.view.document, 'mousedown', this._mouseDownListener.bind(this), { priority: 'high' });
@@ -110,8 +92,6 @@ export default class WidgetResize extends Plugin {
     }
     /**
      * Marks resizer as selected.
-     *
-     * @param {module:widget/widgetresize/resizer~Resizer} resizer
      */
     select(resizer) {
         this.deselect();
@@ -128,8 +108,7 @@ export default class WidgetResize extends Plugin {
         this.selectedResizer = null;
     }
     /**
-     * @param {module:widget/widgetresize~ResizerOptions} [options] Resizer options.
-     * @returns {module:widget/widgetresize/resizer~Resizer}
+     * @param options Resizer options.
      */
     attachTo(options) {
         const resizer = new Resizer(options);
@@ -161,18 +140,13 @@ export default class WidgetResize extends Plugin {
     /**
      * Returns a resizer created for a given view element (widget element).
      *
-     * @param {module:engine/view/containerelement~ContainerElement} viewElement View element associated with the resizer.
-     * @returns {module:widget/widgetresize/resizer~Resizer|undefined}
+     * @param viewElement View element associated with the resizer.
      */
     getResizerByViewElement(viewElement) {
         return this._resizers.get(viewElement);
     }
     /**
      * Returns a resizer that contains a given resize handle.
-     *
-     * @protected
-     * @param {HTMLElement} domResizeHandle
-     * @returns {module:widget/widgetresize/resizer~Resizer}
      */
     _getResizerByHandle(domResizeHandle) {
         for (const resizer of this._resizers.values()) {
@@ -182,9 +156,7 @@ export default class WidgetResize extends Plugin {
         }
     }
     /**
-     * @protected
-     * @param {module:utils/eventinfo~EventInfo} event
-     * @param {Event} domEventData Native DOM event.
+     * @param domEventData Native DOM event.
      */
     _mouseDownListener(event, domEventData) {
         const resizeHandle = domEventData.domTarget;
@@ -200,18 +172,13 @@ export default class WidgetResize extends Plugin {
         }
     }
     /**
-     * @protected
-     * @param {module:utils/eventinfo~EventInfo} event
-     * @param {Event} domEventData Native DOM event.
+     * @param domEventData Native DOM event.
      */
     _mouseMoveListener(event, domEventData) {
         if (this._activeResizer) {
             this._activeResizer.updateSize(domEventData);
         }
     }
-    /**
-     * @protected
-     */
     _mouseUpListener() {
         if (this._activeResizer) {
             this._activeResizer.commit();

package/src/widgettoolbarrepository.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @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 widget/widgettoolbarrepository
+ */
+import { Plugin, type PluginDependencies, type ToolbarConfigItem } from '@ckeditor/ckeditor5-core';
+import type { ViewDocumentSelection, ViewElement } from '@ckeditor/ckeditor5-engine';
+/**
+ * Widget toolbar repository plugin. A central point for registering widget toolbars. This plugin handles the whole
+ * toolbar rendering process and exposes a concise API.
+ *
+ * To add a toolbar for your widget use the {@link ~WidgetToolbarRepository#register `WidgetToolbarRepository#register()`} method.
+ *
+ * The following example comes from the {@link module:image/imagetoolbar~ImageToolbar} plugin:
+ *
+ * ```ts
+ * class ImageToolbar extends Plugin {
+ * 	static get requires() {
+ * 		return [ WidgetToolbarRepository ];
+ * 	}
+ *
+ * 	afterInit() {
+ * 		const editor = this.editor;
+ * 		const widgetToolbarRepository = editor.plugins.get( WidgetToolbarRepository );
+ *
+ * 		widgetToolbarRepository.register( 'image', {
+ * 			items: editor.config.get( 'image.toolbar' ),
+ * 			getRelatedElement: getClosestSelectedImageWidget
+ * 		} );
+ * 	}
+ * }
+ * ```
+ */
+export default class WidgetToolbarRepository extends Plugin {
+    /**
+     * A map of toolbar definitions.
+     */
+    private _toolbarDefinitions;
+    private _balloon;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'WidgetToolbarRepository';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    destroy(): void;
+    /**
+     * Registers toolbar in the WidgetToolbarRepository. It renders it in the `ContextualBalloon` based on the value of the invoked
+     * `getRelatedElement` function. Toolbar items are gathered from `items` array.
+     * The balloon's CSS class is by default `ck-toolbar-container` and may be override with the `balloonClassName` option.
+     *
+     * Note: This method should be called in the {@link module:core/plugin~PluginInterface#afterInit `Plugin#afterInit()`}
+     * callback (or later) to make sure that the given toolbar items were already registered by other plugins.
+     *
+     * @param toolbarId An id for the toolbar. Used to
+     * @param options.ariaLabel Label used by assistive technologies to describe this toolbar element.
+     * @param options.items Array of toolbar items.
+     * @param options.getRelatedElement Callback which returns an element the toolbar should be attached to.
+     * @param options.balloonClassName CSS class for the widget balloon.
+     */
+    register(toolbarId: string, { ariaLabel, items, getRelatedElement, balloonClassName }: {
+        ariaLabel?: string;
+        items: Array<ToolbarConfigItem>;
+        getRelatedElement: (selection: ViewDocumentSelection) => (ViewElement | null);
+        balloonClassName?: string;
+    }): void;
+    /**
+     * Iterates over stored toolbars and makes them visible or hidden.
+     */
+    private _updateToolbarsVisibility;
+    /**
+     * Hides the given toolbar.
+     */
+    private _hideToolbar;
+    /**
+     * Shows up the toolbar if the toolbar is not visible.
+     * Otherwise, repositions the toolbar's balloon when toolbar's view is the most top view in balloon stack.
+     *
+     * It might happen here that the toolbar's view is under another view. Then do nothing as the other toolbar view
+     * should be still visible after the {@link module:core/editor/editorui~EditorUI#event:update}.
+     */
+    private _showToolbar;
+    private _isToolbarVisible;
+    private _isToolbarInBalloon;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [WidgetToolbarRepository.pluginName]: WidgetToolbarRepository;
+    }
+}