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

package/src/widget.js

@@ -25,10 +25,15 @@ import '../theme/widget.css';
  * {@link module:engine/view/selection~Selection#isFake fake}. Additionally, the `ck-widget_selected` CSS class
  * is added to indicate that widget has been selected.
  * * The mouse and keyboard events handling on and around widget elements.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class Widget extends Plugin {
+    constructor() {
+        super(...arguments);
+        /**
+         * Holds previously selected widgets.
+         */
+        this._previouslySelected = new Set();
+    }
     /**
      * @inheritDoc
      */
@@ -48,13 +53,6 @@ export default class Widget extends Plugin {
         const editor = this.editor;
         const view = editor.editing.view;
         const viewDocument = view.document;
-        /**
-         * Holds previously selected widgets.
-         *
-         * @private
-         * @type {Set.<module:engine/view/element~Element>}
-         */
-        this._previouslySelected = new Set();
         // Model to view selection converter.
         // Converts selection placed over widget element to fake selection.
         //
@@ -150,10 +148,6 @@ export default class Widget extends Plugin {
     }
     /**
      * Handles {@link module:engine/view/document~Document#event:mousedown mousedown} events on widget elements.
-     *
-     * @private
-     * @param {module:utils/eventinfo~EventInfo} eventInfo
-     * @param {module:engine/view/observer/domeventdata~DomEventData} domEventData
      */
     _onMousedown(eventInfo, domEventData) {
         const editor = this.editor;
@@ -205,10 +199,6 @@ export default class Widget extends Plugin {
      * * the selection is next to a widget and the widget should become selected upon the arrow key press.
      *
      * See {@link #_preventDefaultOnArrowKeyPress}.
-     *
-     * @private
-     * @param {module:utils/eventinfo~EventInfo} eventInfo
-     * @param {module:engine/view/observer/domeventdata~DomEventData} domEventData
      */
     _handleSelectionChangeOnArrowKeyPress(eventInfo, domEventData) {
         const keyCode = domEventData.keyCode;
@@ -270,10 +260,6 @@ export default class Widget extends Plugin {
      * container.
      *
      * See {@link #_handleSelectionChangeOnArrowKeyPress}.
-     *
-     * @private
-     * @param {module:utils/eventinfo~EventInfo} eventInfo
-     * @param {module:engine/view/observer/domeventdata~DomEventData} domEventData
      */
     _preventDefaultOnArrowKeyPress(eventInfo, domEventData) {
         const model = this.editor.model;
@@ -288,9 +274,8 @@ export default class Widget extends Plugin {
     /**
      * Handles delete keys: backspace and delete.
      *
-     * @private
-     * @param {Boolean} isForward Set to true if delete was performed in forward direction.
-     * @returns {Boolean|undefined} Returns `true` if keys were handled correctly.
+     * @param isForward Set to true if delete was performed in forward direction.
+     * @returns Returns `true` if keys were handled correctly.
      */
     _handleDelete(isForward) {
         // Do nothing when the read only mode is enabled.
@@ -322,8 +307,6 @@ export default class Widget extends Plugin {
      * Sets {@link module:engine/model/selection~Selection document's selection} over given element.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/element~Element} element
      */
     _setSelectionOverElement(element) {
         this.editor.model.change(writer => {
@@ -336,9 +319,7 @@ export default class Widget extends Plugin {
      * {@link module:engine/model/schema~Schema schema} as `object`.
      *
      * @internal
-     * @protected
-     * @param {Boolean} forward Direction of checking.
-     * @returns {module:engine/model/element~Element|null}
+     * @param forward Direction of checking.
      */
     _getObjectElementNextToSelection(forward) {
         const model = this.editor.model;
@@ -360,9 +341,6 @@ export default class Widget extends Plugin {
     }
     /**
      * Removes CSS class from previously selected widgets.
-     *
-     * @private
-     * @param {module:engine/view/downcastwriter~DowncastWriter} writer
      */
     _clearPreviouslySelectedWidgets(writer) {
         for (const widget of this._previouslySelected) {
@@ -371,10 +349,9 @@ export default class Widget extends Plugin {
         this._previouslySelected.clear();
     }
 }
-// Returns `true` when element is a nested editable or is placed inside one.
-//
-// @param {module:engine/view/element~Element}
-// @returns {Boolean}
+/**
+ * Returns `true` when element is a nested editable or is placed inside one.
+ */
 function isInsideNestedEditable(element) {
     let currentElement = element;
     while (currentElement) {
@@ -389,11 +366,12 @@ function isInsideNestedEditable(element) {
     }
     return false;
 }
-// Checks whether the specified `element` is a child of the `parent` element.
-//
-// @param {module:engine/view/element~Element} element An element to check.
-// @param {module:engine/view/element~Element|null} parent A parent for the element.
-// @returns {Boolean}
+/**
+ * Checks whether the specified `element` is a child of the `parent` element.
+ *
+ * @param element An element to check.
+ * @param parent A parent for the element.
+ */
 function isChild(element, parent) {
     if (!parent) {
         return false;

package/src/widgetresize/resizer.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @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 { Rect, type DecoratedMethodEvent } from '@ckeditor/ckeditor5-utils';
+import ResizeState from './resizerstate';
+import type { ResizerOptions } from '../widgetresize';
+declare const Resizer_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * Represents a resizer for a single resizable object.
+ */
+export default class Resizer extends Resizer_base {
+    /**
+     * Flag that indicates whether resizer can be used.
+     *
+     * @observable
+     */
+    isEnabled: boolean;
+    /**
+     * Flag that indicates that resizer is currently focused.
+     *
+     * @observable
+     */
+    isSelected: boolean;
+    /**
+     * Flag that indicates whether resizer is rendered (visible on the screen).
+     *
+     * @readonly
+     * @observable
+     */
+    isVisible: boolean;
+    /**
+     * Stores the state of the resizable host geometry, such as the original width, the currently proposed height, etc.
+     *
+     * Note that a new state is created for each resize transaction.
+     */
+    private _state;
+    /**
+     * A view displaying the proposed new element size during the resizing.
+     */
+    private _sizeView;
+    /**
+     * Options passed to the {@link #constructor}.
+     */
+    private _options;
+    /**
+     * A wrapper that is controlled by the resizer. This is usually a widget element.
+     */
+    private _viewResizerWrapper;
+    /**
+     * The width of the resized {@link module:widget/widgetresize~ResizerOptions#viewElement viewElement} before the resizing started.
+     */
+    private _initialViewWidth;
+    /**
+     * @param options Resizer options.
+     */
+    constructor(options: ResizerOptions);
+    /**
+     * Stores the state of the resizable host geometry, such as the original width, the currently proposed height, etc.
+     *
+     * Note that a new state is created for each resize transaction.
+     */
+    get state(): ResizeState;
+    /**
+     * Makes resizer visible in the UI.
+     */
+    show(): void;
+    /**
+     * Hides resizer in the UI.
+     */
+    hide(): void;
+    /**
+     * Attaches the resizer to the DOM.
+     */
+    attach(): void;
+    /**
+     * Starts the resizing process.
+     *
+     * Creates a new {@link #state} for the current process.
+     *
+     * @fires begin
+     * @param domResizeHandle Clicked handle.
+     */
+    begin(domResizeHandle: HTMLElement): void;
+    /**
+     * Updates the proposed size based on `domEventData`.
+     *
+     * @fires updateSize
+     */
+    updateSize(domEventData: MouseEvent): void;
+    /**
+     * Applies the geometry proposed with the resizer.
+     *
+     * @fires commit
+     */
+    commit(): void;
+    /**
+     * Cancels and rejects the proposed resize dimensions, hiding the UI.
+     *
+     * @fires cancel
+     */
+    cancel(): void;
+    /**
+     * Destroys the resizer.
+     */
+    destroy(): void;
+    /**
+     * Redraws the resizer.
+     *
+     * @param handleHostRect Handle host rectangle might be given to improve performance.
+     */
+    redraw(handleHostRect?: Rect): void;
+    containsHandle(domElement: HTMLElement): boolean;
+    static isResizeHandle(domElement: HTMLElement): boolean;
+    /**
+     * Cleans up the context state.
+     */
+    private _cleanup;
+    /**
+     * Calculates the proposed size as the resize handles are dragged.
+     *
+     * @param domEventData Event data that caused the size update request. It should be used to calculate the proposed size.
+     */
+    private _proposeNewSize;
+    /**
+     * Obtains the resize host.
+     *
+     * Resize host is an object that receives dimensions which are the result of resizing.
+     */
+    private _getResizeHost;
+    /**
+     * Obtains the handle host.
+     *
+     * Handle host is an object that the handles are aligned to.
+     *
+     * Handle host will not always be an entire widget itself. Take an image as an example. The image widget
+     * contains an image and a caption. Only the image should be surrounded with handles.
+     */
+    private _getHandleHost;
+    /**
+     * DOM container of the entire resize UI.
+     *
+     * Note that this property will have a value only after the element bound with the resizer is rendered
+     * (otherwise `null`).
+     */
+    private get _domResizerWrapper();
+    /**
+     * Renders the resize handles in the DOM.
+     *
+     * @param domElement The resizer wrapper.
+     */
+    private _appendHandles;
+    /**
+     * Sets up the {@link #_sizeView} property and adds it to the passed `domElement`.
+     */
+    private _appendSizeUI;
+}
+/**
+ * @eventName ~Resizer#begin
+ */
+export type ResizerBeginEvent = DecoratedMethodEvent<Resizer, 'begin'>;
+/**
+ * @eventName ~Resizer#cancel
+ */
+export type ResizerCancelEvent = DecoratedMethodEvent<Resizer, 'cancel'>;
+/**
+ * @eventName ~Resizer#commit
+ */
+export type ResizerCommitEvent = DecoratedMethodEvent<Resizer, 'commit'>;
+/**
+ * @eventName ~Resizer#updateSize
+ */
+export type ResizerUpdateSizeEvent = DecoratedMethodEvent<Resizer, 'updateSize'>;
+export {};

package/src/widgetresize/resizer.js

@@ -11,68 +11,20 @@ import ResizeState from './resizerstate';
 import SizeView from './sizeview';
 /**
  * Represents a resizer for a single resizable object.
- *
- * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class Resizer extends ObservableMixin() {
     /**
-     * @param {module:widget/widgetresize~ResizerOptions} options Resizer options.
+     * @param options Resizer options.
      */
     constructor(options) {
         super();
-        /**
-         * Stores the state of the resizable host geometry, such as the original width, the currently proposed height, etc.
-         *
-         * Note that a new state is created for each resize transaction.
-         *
-         * @readonly
-         * @member {module:widget/widgetresize/resizerstate~ResizerState} #state
-         */
-        /**
-         * A view displaying the proposed new element size during the resizing.
-         *
-         * @protected
-         * @readonly
-         * @member {module:widget/widgetresize/sizeview~SizeView} #_sizeView
-         */
-        /**
-         * Options passed to the {@link #constructor}.
-         *
-         * @private
-         * @type {module:widget/widgetresize~ResizerOptions}
-         */
-        this._options = options;
         /**
          * A wrapper that is controlled by the resizer. This is usually a widget element.
-         *
-         * @private
-         * @type {module:engine/view/element~Element|null}
          */
         this._viewResizerWrapper = null;
-        /**
-         * The width of the resized {@link module:widget/widgetresize~ResizerOptions#viewElement viewElement} before the resizing started.
-         *
-         * @private
-         * @member {Number|String|undefined} #_initialViewWidth
-         */
-        /**
-         * Flag that indicates whether resizer can be used.
-         *
-         * @observable
-         */
+        this._options = options;
         this.set('isEnabled', true);
-        /**
-         * Flag that indicates that resizer is currently focused.
-         *
-         * @observable
-         */
         this.set('isSelected', false);
-        /**
-         * Flag that indicates whether resizer is rendered (visible on the screen).
-         *
-         * @readonly
-         * @observable
-         */
         this.bind('isVisible').to(this, 'isEnabled', this, 'isSelected', (isEnabled, isSelected) => isEnabled && isSelected);
         this.decorate('begin');
         this.decorate('cancel');
@@ -87,6 +39,11 @@ export default class Resizer extends ObservableMixin() {
             }
         }, { priority: 'high' });
     }
+    /**
+     * Stores the state of the resizable host geometry, such as the original width, the currently proposed height, etc.
+     *
+     * Note that a new state is created for each resize transaction.
+     */
     get state() {
         return this._state;
     }
@@ -149,7 +106,7 @@ export default class Resizer extends ObservableMixin() {
      * Creates a new {@link #state} for the current process.
      *
      * @fires begin
-     * @param {HTMLElement} domResizeHandle Clicked handle.
+     * @param domResizeHandle Clicked handle.
      */
     begin(domResizeHandle) {
         this._state = new ResizeState(this._options);
@@ -161,7 +118,6 @@ export default class Resizer extends ObservableMixin() {
      * Updates the proposed size based on `domEventData`.
      *
      * @fires updateSize
-     * @param {Event} domEventData
      */
     updateSize(domEventData) {
         const newSize = this._proposeNewSize(domEventData);
@@ -220,7 +176,7 @@ export default class Resizer extends ObservableMixin() {
     /**
      * Redraws the resizer.
      *
-     * @param {module:utils/dom/rect~Rect} [handleHostRect] Handle host rectangle might be given to improve performance.
+     * @param handleHostRect Handle host rectangle might be given to improve performance.
      */
     redraw(handleHostRect) {
         const domWrapper = this._domResizerWrapper;
@@ -283,8 +239,6 @@ export default class Resizer extends ObservableMixin() {
     }
     /**
      * Cleans up the context state.
-     *
-     * @protected
      */
     _cleanup() {
         this._sizeView._dismiss();
@@ -296,11 +250,7 @@ export default class Resizer extends ObservableMixin() {
     /**
      * Calculates the proposed size as the resize handles are dragged.
      *
-     * @private
-     * @param {Event} domEventData Event data that caused the size update request. It should be used to calculate the proposed size.
-     * @returns {Object} return
-     * @returns {Number} return.width Proposed width.
-     * @returns {Number} return.height Proposed height.
+     * @param domEventData Event data that caused the size update request. It should be used to calculate the proposed size.
      */
     _proposeNewSize(domEventData) {
         const state = this.state;
@@ -352,9 +302,6 @@ export default class Resizer extends ObservableMixin() {
      * Obtains the resize host.
      *
      * Resize host is an object that receives dimensions which are the result of resizing.
-     *
-     * @protected
-     * @returns {HTMLElement}
      */
     _getResizeHost() {
         const widgetWrapper = this._domResizerWrapper.parentElement;
@@ -367,9 +314,6 @@ export default class Resizer extends ObservableMixin() {
      *
      * Handle host will not always be an entire widget itself. Take an image as an example. The image widget
      * contains an image and a caption. Only the image should be surrounded with handles.
-     *
-     * @protected
-     * @returns {HTMLElement}
      */
     _getHandleHost() {
         const widgetWrapper = this._domResizerWrapper.parentElement;
@@ -380,9 +324,6 @@ export default class Resizer extends ObservableMixin() {
      *
      * Note that this property will have a value only after the element bound with the resizer is rendered
      * (otherwise `null`).
-     *
-     * @private
-     * @member {HTMLElement|null}
      */
     get _domResizerWrapper() {
         return this._options.editor.editing.view.domConverter.mapViewToDom(this._viewResizerWrapper);
@@ -390,8 +331,7 @@ export default class Resizer extends ObservableMixin() {
     /**
      * Renders the resize handles in the DOM.
      *
-     * @private
-     * @param {HTMLElement} domElement The resizer wrapper.
+     * @param domElement The resizer wrapper.
      */
     _appendHandles(domElement) {
         const resizerPositions = ['top-left', 'top-right', 'bottom-right', 'bottom-left'];
@@ -406,9 +346,6 @@ export default class Resizer extends ObservableMixin() {
     }
     /**
      * Sets up the {@link #_sizeView} property and adds it to the passed `domElement`.
-     *
-     * @private
-     * @param {HTMLElement} domElement
      */
     _appendSizeUI(domElement) {
         this._sizeView = new SizeView();
@@ -417,9 +354,10 @@ export default class Resizer extends ObservableMixin() {
         domElement.appendChild(this._sizeView.element);
     }
 }
-// @private
-// @param {String} resizerPosition Expected resizer position like `"top-left"`, `"bottom-right"`.
-// @returns {String} A prefixed HTML class name for the resizer element
+/**
+ * @param resizerPosition Expected resizer position like `"top-left"`, `"bottom-right"`.
+ * @returns A prefixed HTML class name for the resizer element
+ */
 function getResizerClass(resizerPosition) {
     return `ck-widget__resizer__handle-${resizerPosition}`;
 }

package/src/widgetresize/resizerstate.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @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 { ResizerOptions } from '../widgetresize';
+declare const ResizeState_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * Stores the internal state of a single resizable object.
+ */
+export default class ResizeState extends ResizeState_base {
+    /**
+     * The position of the handle that initiated the resizing. E.g. `"top-left"`, `"bottom-right"` etc. or `null`
+     * if unknown.
+     *
+     * @readonly
+     * @observable
+     */
+    activeHandlePosition: string | null;
+    /**
+     * The width (percents) proposed, but not committed yet, in the current resize process.
+     *
+     * @readonly
+     * @observable
+     */
+    proposedWidthPercents: number | null;
+    /**
+     * The width (pixels) proposed, but not committed yet, in the current resize process.
+     *
+     * @readonly
+     * @observable
+     */
+    proposedWidth: number | null;
+    /**
+     * The height (pixels) proposed, but not committed yet, in the current resize process.
+     *
+     * @readonly
+     * @observable
+     */
+    proposedHeight: number | null;
+    /**
+     * @readonly
+     * @observable
+     */
+    proposedHandleHostWidth: number | null;
+    /**
+     * @readonly
+     * @observable
+     */
+    proposedHandleHostHeight: number | null;
+    /**
+     * 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.
+     *
+     * @internal
+     */
+    _referenceCoordinates: {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Resizer options.
+     */
+    private readonly _options;
+    /**
+     * The original width (pixels) of the resized object when the resize process was started.
+     *
+     * @readonly
+     */
+    private _originalWidth?;
+    /**
+     * The original height (pixels) of the resized object when the resize process was started.
+     *
+     * @readonly
+     */
+    private _originalHeight?;
+    /**
+     * The original width (percents) of the resized object when the resize process was started.
+     *
+     * @readonly
+     */
+    private _originalWidthPercents?;
+    /**
+     * A width to height ratio of the resized image.
+     *
+     * @readonly
+     */
+    private _aspectRatio?;
+    /**
+     * @param options Resizer options.
+     */
+    constructor(options: ResizerOptions);
+    /**
+     * The original width (pixels) of the resized object when the resize process was started.
+     */
+    get originalWidth(): number | undefined;
+    /**
+     * The original height (pixels) of the resized object when the resize process was started.
+     */
+    get originalHeight(): number | undefined;
+    /**
+     * The original width (percents) of the resized object when the resize process was started.
+     */
+    get originalWidthPercents(): number | undefined;
+    /**
+     * A width to height ratio of the resized image.
+     */
+    get aspectRatio(): number | undefined;
+    /**
+     *
+     * @param domResizeHandle The handle used to calculate the reference point.
+     */
+    begin(domResizeHandle: HTMLElement, domHandleHost: HTMLElement, domResizeHost: HTMLElement): void;
+    update(newSize: {
+        width: number;
+        height: number;
+        widthPercents: number;
+        handleHostWidth: number;
+        handleHostHeight: number;
+    }): void;
+}
+export {};