@ckeditor/ckeditor5-widget 0.0.0-internal-20241017.0

package/src/widgetresize/resizer.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @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
+ */
+import { Rect, type DecoratedMethodEvent } from '@ckeditor/ckeditor5-utils';
+import ResizeState from './resizerstate.js';
+import type { ResizerOptions } from '../widgetresize.js';
+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 /* #__PURE__ */ 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

@@ -0,0 +1,372 @@
+/**
+ * @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 widget/widgetresize/resizer
+ */
+import { Template } from '@ckeditor/ckeditor5-ui';
+import { Rect, ObservableMixin, compareArrays } from '@ckeditor/ckeditor5-utils';
+import ResizeState from './resizerstate.js';
+import SizeView from './sizeview.js';
+/**
+ * Represents a resizer for a single resizable object.
+ */
+export default class Resizer extends /* #__PURE__ */ ObservableMixin() {
+    /**
+     * @param options Resizer options.
+     */
+    constructor(options) {
+        super();
+        /**
+         * A wrapper that is controlled by the resizer. This is usually a widget element.
+         */
+        this._viewResizerWrapper = null;
+        this._options = options;
+        this.set('isEnabled', true);
+        this.set('isSelected', false);
+        this.bind('isVisible').to(this, 'isEnabled', this, 'isSelected', (isEnabled, isSelected) => isEnabled && isSelected);
+        this.decorate('begin');
+        this.decorate('cancel');
+        this.decorate('commit');
+        this.decorate('updateSize');
+        this.on('commit', event => {
+            // State might not be initialized yet. In this case, prevent further handling and make sure that the resizer is
+            // cleaned up (#5195).
+            if (!this.state.proposedWidth && !this.state.proposedWidthPercents) {
+                this._cleanup();
+                event.stop();
+            }
+        }, { 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;
+    }
+    /**
+     * Makes resizer visible in the UI.
+     */
+    show() {
+        const editingView = this._options.editor.editing.view;
+        editingView.change(writer => {
+            writer.removeClass('ck-hidden', this._viewResizerWrapper);
+        });
+    }
+    /**
+     * Hides resizer in the UI.
+     */
+    hide() {
+        const editingView = this._options.editor.editing.view;
+        editingView.change(writer => {
+            writer.addClass('ck-hidden', this._viewResizerWrapper);
+        });
+    }
+    /**
+     * Attaches the resizer to the DOM.
+     */
+    attach() {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const that = this;
+        const widgetElement = this._options.viewElement;
+        const editingView = this._options.editor.editing.view;
+        editingView.change(writer => {
+            const viewResizerWrapper = writer.createUIElement('div', {
+                class: 'ck ck-reset_all ck-widget__resizer'
+            }, function (domDocument) {
+                const domElement = this.toDomElement(domDocument);
+                that._appendHandles(domElement);
+                that._appendSizeUI(domElement);
+                return domElement;
+            });
+            // Append the resizer wrapper to the widget's wrapper.
+            writer.insert(writer.createPositionAt(widgetElement, 'end'), viewResizerWrapper);
+            writer.addClass('ck-widget_with-resizer', widgetElement);
+            this._viewResizerWrapper = viewResizerWrapper;
+            if (!this.isVisible) {
+                this.hide();
+            }
+        });
+        this.on('change:isVisible', () => {
+            if (this.isVisible) {
+                this.show();
+                this.redraw();
+            }
+            else {
+                this.hide();
+            }
+        });
+    }
+    /**
+     * Starts the resizing process.
+     *
+     * Creates a new {@link #state} for the current process.
+     *
+     * @fires begin
+     * @param domResizeHandle Clicked handle.
+     */
+    begin(domResizeHandle) {
+        this._state = new ResizeState(this._options);
+        this._sizeView._bindToState(this._options, this.state);
+        this._initialViewWidth = this._options.viewElement.getStyle('width');
+        this.state.begin(domResizeHandle, this._getHandleHost(), this._getResizeHost());
+    }
+    /**
+     * Updates the proposed size based on `domEventData`.
+     *
+     * @fires updateSize
+     */
+    updateSize(domEventData) {
+        const newSize = this._proposeNewSize(domEventData);
+        const editingView = this._options.editor.editing.view;
+        editingView.change(writer => {
+            const unit = this._options.unit || '%';
+            const newWidth = (unit === '%' ? newSize.widthPercents : newSize.width) + unit;
+            writer.setStyle('width', newWidth, this._options.viewElement);
+        });
+        // Get an actual image width, and:
+        // * reflect this size to the resize wrapper
+        // * apply this **real** size to the state
+        const domHandleHost = this._getHandleHost();
+        const domHandleHostRect = new Rect(domHandleHost);
+        const handleHostWidth = Math.round(domHandleHostRect.width);
+        const handleHostHeight = Math.round(domHandleHostRect.height);
+        // Handle max-width limitation.
+        const domResizeHostRect = new Rect(domHandleHost);
+        newSize.width = Math.round(domResizeHostRect.width);
+        newSize.height = Math.round(domResizeHostRect.height);
+        this.redraw(domHandleHostRect);
+        this.state.update({
+            ...newSize,
+            handleHostWidth,
+            handleHostHeight
+        });
+    }
+    /**
+     * Applies the geometry proposed with the resizer.
+     *
+     * @fires commit
+     */
+    commit() {
+        const unit = this._options.unit || '%';
+        const newValue = (unit === '%' ? this.state.proposedWidthPercents : this.state.proposedWidth) + unit;
+        // Both cleanup and onCommit callback are very likely to make view changes. Ensure that it is made in a single step.
+        this._options.editor.editing.view.change(() => {
+            this._cleanup();
+            this._options.onCommit(newValue);
+        });
+    }
+    /**
+     * Cancels and rejects the proposed resize dimensions, hiding the UI.
+     *
+     * @fires cancel
+     */
+    cancel() {
+        this._cleanup();
+    }
+    /**
+     * Destroys the resizer.
+     */
+    destroy() {
+        this.cancel();
+    }
+    /**
+     * Redraws the resizer.
+     *
+     * @param handleHostRect Handle host rectangle might be given to improve performance.
+     */
+    redraw(handleHostRect) {
+        const domWrapper = this._domResizerWrapper;
+        // Refresh only if resizer exists in the DOM.
+        if (!existsInDom(domWrapper)) {
+            return;
+        }
+        const widgetWrapper = domWrapper.parentElement;
+        const handleHost = this._getHandleHost();
+        const resizerWrapper = this._viewResizerWrapper;
+        const currentDimensions = [
+            resizerWrapper.getStyle('width'),
+            resizerWrapper.getStyle('height'),
+            resizerWrapper.getStyle('left'),
+            resizerWrapper.getStyle('top')
+        ];
+        let newDimensions;
+        if (widgetWrapper.isSameNode(handleHost)) {
+            const clientRect = handleHostRect || new Rect(handleHost);
+            newDimensions = [
+                clientRect.width + 'px',
+                clientRect.height + 'px',
+                undefined,
+                undefined
+            ];
+        }
+        // In case a resizing host is not a widget wrapper, we need to compensate
+        // for any additional offsets the resize host might have. E.g. wrapper padding
+        // or simply another editable. By doing that the border and resizers are shown
+        // only around the resize host.
+        else {
+            newDimensions = [
+                handleHost.offsetWidth + 'px',
+                handleHost.offsetHeight + 'px',
+                handleHost.offsetLeft + 'px',
+                handleHost.offsetTop + 'px'
+            ];
+        }
+        // Make changes to the view only if the resizer should actually get new dimensions.
+        // Otherwise, if View#change() was always called, this would cause EditorUI#update
+        // loops because the WidgetResize plugin listens to EditorUI#update and updates
+        // the resizer.
+        // https://github.com/ckeditor/ckeditor5/issues/7633
+        if (compareArrays(currentDimensions, newDimensions) !== 'same') {
+            this._options.editor.editing.view.change(writer => {
+                writer.setStyle({
+                    width: newDimensions[0],
+                    height: newDimensions[1],
+                    left: newDimensions[2],
+                    top: newDimensions[3]
+                }, resizerWrapper);
+            });
+        }
+    }
+    containsHandle(domElement) {
+        return this._domResizerWrapper.contains(domElement);
+    }
+    static isResizeHandle(domElement) {
+        return domElement.classList.contains('ck-widget__resizer__handle');
+    }
+    /**
+     * Cleans up the context state.
+     */
+    _cleanup() {
+        this._sizeView._dismiss();
+        const editingView = this._options.editor.editing.view;
+        editingView.change(writer => {
+            writer.setStyle('width', this._initialViewWidth, this._options.viewElement);
+        });
+    }
+    /**
+     * 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.
+     */
+    _proposeNewSize(domEventData) {
+        const state = this.state;
+        const currentCoordinates = extractCoordinates(domEventData);
+        const isCentered = this._options.isCentered ? this._options.isCentered(this) : true;
+        // Enlargement defines how much the resize host has changed in a given axis. Naturally it could be a negative number
+        // meaning that it has been shrunk.
+        //
+        // +----------------+--+
+        // |                |  |
+        // |       img      |  |
+        // |  /handle host  |  |
+        // +----------------+  | ^
+        // |                   | | - enlarge y
+        // +-------------------+ v
+        // 					<-->
+        // 					 enlarge x
+        const enlargement = {
+            x: state._referenceCoordinates.x - (currentCoordinates.x + state.originalWidth),
+            y: (currentCoordinates.y - state.originalHeight) - state._referenceCoordinates.y
+        };
+        if (isCentered && state.activeHandlePosition.endsWith('-right')) {
+            enlargement.x = currentCoordinates.x - (state._referenceCoordinates.x + state.originalWidth);
+        }
+        // Objects needs to be resized twice as much in horizontal axis if centered, since enlargement is counted from
+        // one resized corner to your cursor. It needs to be duplicated to compensate for the other side too.
+        if (isCentered) {
+            enlargement.x *= 2;
+        }
+        // const resizeHost = this._getResizeHost();
+        // The size proposed by the user. It does not consider the aspect ratio.
+        let width = Math.abs(state.originalWidth + enlargement.x);
+        let height = Math.abs(state.originalHeight + enlargement.y);
+        // Dominant determination must take the ratio into account.
+        const dominant = width / state.aspectRatio > height ? 'width' : 'height';
+        if (dominant == 'width') {
+            height = width / state.aspectRatio;
+        }
+        else {
+            width = height * state.aspectRatio;
+        }
+        return {
+            width: Math.round(width),
+            height: Math.round(height),
+            widthPercents: Math.min(Math.round(state.originalWidthPercents / state.originalWidth * width * 100) / 100, 100)
+        };
+    }
+    /**
+     * Obtains the resize host.
+     *
+     * Resize host is an object that receives dimensions which are the result of resizing.
+     */
+    _getResizeHost() {
+        const widgetWrapper = this._domResizerWrapper.parentElement;
+        return this._options.getResizeHost(widgetWrapper);
+    }
+    /**
+     * 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.
+     */
+    _getHandleHost() {
+        const widgetWrapper = this._domResizerWrapper.parentElement;
+        return this._options.getHandleHost(widgetWrapper);
+    }
+    /**
+     * 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`).
+     */
+    get _domResizerWrapper() {
+        return this._options.editor.editing.view.domConverter.mapViewToDom(this._viewResizerWrapper);
+    }
+    /**
+     * Renders the resize handles in the DOM.
+     *
+     * @param domElement The resizer wrapper.
+     */
+    _appendHandles(domElement) {
+        const resizerPositions = ['top-left', 'top-right', 'bottom-right', 'bottom-left'];
+        for (const currentPosition of resizerPositions) {
+            domElement.appendChild((new Template({
+                tag: 'div',
+                attributes: {
+                    class: `ck-widget__resizer__handle ${getResizerClass(currentPosition)}`
+                }
+            }).render()));
+        }
+    }
+    /**
+     * Sets up the {@link #_sizeView} property and adds it to the passed `domElement`.
+     */
+    _appendSizeUI(domElement) {
+        this._sizeView = new SizeView();
+        // Make sure icon#element is rendered before passing to appendChild().
+        this._sizeView.render();
+        domElement.appendChild(this._sizeView.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}`;
+}
+function extractCoordinates(event) {
+    return {
+        x: event.pageX,
+        y: event.pageY
+    };
+}
+function existsInDom(element) {
+    return element && element.ownerDocument && element.ownerDocument.contains(element);
+}

package/src/widgetresize/resizerstate.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @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
+ */
+import type { ResizerOptions } from '../widgetresize.js';
+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 /* #__PURE__ */ 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 {};