@ckeditor/ckeditor5-widget 0.0.0-internal-20241017.0

package/src/widgetresize/resizerstate.js

@@ -0,0 +1,129 @@
+/**
+ * @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/resizerstate
+ */
+import { ObservableMixin, Rect } from '@ckeditor/ckeditor5-utils';
+import { calculateResizeHostPercentageWidth } from '../utils.js';
+/**
+ * Stores the internal state of a single resizable object.
+ */
+export default class ResizeState extends /* #__PURE__ */ ObservableMixin() {
+    /**
+     * @param options Resizer options.
+     */
+    constructor(options) {
+        super();
+        this.set('activeHandlePosition', null);
+        this.set('proposedWidthPercents', null);
+        this.set('proposedWidth', null);
+        this.set('proposedHeight', null);
+        this.set('proposedHandleHostWidth', null);
+        this.set('proposedHandleHostHeight', null);
+        this._options = options;
+        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 domResizeHandle The handle used to calculate the reference point.
+     */
+    begin(domResizeHandle, domHandleHost, domResizeHost) {
+        const clientRect = new Rect(domHandleHost);
+        this.activeHandlePosition = getHandlePosition(domResizeHandle);
+        this._referenceCoordinates = getAbsoluteBoundaryPoint(domHandleHost, getOppositePosition(this.activeHandlePosition));
+        this._originalWidth = clientRect.width;
+        this._originalHeight = clientRect.height;
+        this._aspectRatio = clientRect.width / clientRect.height;
+        const widthStyle = domResizeHost.style.width;
+        if (widthStyle && widthStyle.match(/^\d+(\.\d*)?%$/)) {
+            this._originalWidthPercents = parseFloat(widthStyle);
+        }
+        else {
+            this._originalWidthPercents = calculateResizeHostPercentageWidth(domResizeHost, clientRect);
+        }
+    }
+    update(newSize) {
+        this.proposedWidth = newSize.width;
+        this.proposedHeight = newSize.height;
+        this.proposedWidthPercents = newSize.widthPercents;
+        this.proposedHandleHostWidth = newSize.handleHostWidth;
+        this.proposedHandleHostHeight = newSize.handleHostHeight;
+    }
+}
+/**
+ * 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('-');
+    const ret = {
+        x: positionParts[1] == 'right' ? elementRect.right : elementRect.left,
+        y: positionParts[0] == 'bottom' ? elementRect.bottom : elementRect.top
+    };
+    ret.x += element.ownerDocument.defaultView.scrollX;
+    ret.y += element.ownerDocument.defaultView.scrollY;
+    return ret;
+}
+/**
+ * @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.
+ *
+ * @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) {
+        if (domHandle.classList.contains(getResizerHandleClass(position))) {
+            return 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 = {
+        top: 'bottom',
+        bottom: 'top',
+        left: 'right',
+        right: 'left'
+    };
+    return `${replacements[parts[0]]}-${replacements[parts[1]]}`;
+}

package/src/widgetresize/sizeview.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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/sizeview
+ */
+import { View } from '@ckeditor/ckeditor5-ui';
+import type { ResizerOptions } from '../widgetresize.js';
+import type ResizeState from './resizerstate.js';
+/**
+ * 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

@@ -0,0 +1,63 @@
+/**
+ * @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/sizeview
+ */
+import { View } from '@ckeditor/ckeditor5-ui';
+/**
+ * A view displaying the proposed new element size during the resizing.
+ */
+export default class SizeView extends View {
+    constructor() {
+        super();
+        const bind = this.bindTemplate;
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-size-view',
+                    bind.to('_viewPosition', value => value ? `ck-orientation-${value}` : '')
+                ],
+                style: {
+                    display: bind.if('_isVisible', 'none', visible => !visible)
+                }
+            },
+            children: [{
+                    text: bind.to('_label')
+                }]
+        });
+    }
+    /**
+     * 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, resizeState) {
+        this.bind('_isVisible').to(resizeState, 'proposedWidth', resizeState, 'proposedHeight', (width, height) => width !== null && height !== null);
+        this.bind('_label').to(resizeState, 'proposedHandleHostWidth', resizeState, 'proposedHandleHostHeight', resizeState, 'proposedWidthPercents', (width, height, widthPercents) => {
+            if (options.unit === 'px') {
+                return `${width}×${height}`;
+            }
+            else {
+                return `${widthPercents}%`;
+            }
+        });
+        this.bind('_viewPosition').to(resizeState, 'activeHandlePosition', resizeState, 'proposedHandleHostWidth', resizeState, 'proposedHandleHostHeight', 
+        // If the widget is too small to contain the size label, display the label above.
+        (position, width, height) => width < 50 || height < 50 ? 'above-center' : position);
+    }
+    /**
+     * A method used for cleaning up. It removes the bindings and hides the view.
+     *
+     * @internal
+     */
+    _dismiss() {
+        this.unbind();
+        this._isVisible = false;
+    }
+}

package/src/widgetresize.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @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
+ */
+import Resizer from './widgetresize/resizer.js';
+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
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @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;
+}

package/src/widgetresize.js

@@ -0,0 +1,194 @@
+/**
+ * @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
+ */
+import Resizer from './widgetresize/resizer.js';
+import { Plugin } from '@ckeditor/ckeditor5-core';
+import { MouseObserver } from '@ckeditor/ckeditor5-engine';
+import { DomEmitterMixin, global } from '@ckeditor/ckeditor5-utils';
+import { throttle } from 'lodash-es';
+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 {
+    constructor() {
+        super(...arguments);
+        /**
+         * A map of resizers created using this plugin instance.
+         */
+        this._resizers = new Map();
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'WidgetResize';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editing = this.editor.editing;
+        const domDocument = global.window.document;
+        this.set('selectedResizer', null);
+        this.set('_activeResizer', null);
+        editing.view.addObserver(MouseObserver);
+        this._observer = new (DomEmitterMixin())();
+        this.listenTo(editing.view.document, 'mousedown', this._mouseDownListener.bind(this), { priority: 'high' });
+        this._observer.listenTo(domDocument, 'mousemove', this._mouseMoveListener.bind(this));
+        this._observer.listenTo(domDocument, 'mouseup', this._mouseUpListener.bind(this));
+        this._redrawSelectedResizerThrottled = throttle(() => this.redrawSelectedResizer(), 200);
+        // Redrawing on any change of the UI of the editor (including content changes).
+        this.editor.ui.on('update', this._redrawSelectedResizerThrottled);
+        // Remove view widget-resizer mappings for widgets that have been removed from the document.
+        // https://github.com/ckeditor/ckeditor5/issues/10156
+        // https://github.com/ckeditor/ckeditor5/issues/10266
+        this.editor.model.document.on('change', () => {
+            for (const [viewElement, resizer] of this._resizers) {
+                if (!viewElement.isAttached()) {
+                    this._resizers.delete(viewElement);
+                    resizer.destroy();
+                }
+            }
+        }, { priority: 'lowest' });
+        // Resizers need to be redrawn upon window resize, because new window might shrink resize host.
+        this._observer.listenTo(global.window, 'resize', this._redrawSelectedResizerThrottled);
+        const viewSelection = this.editor.editing.view.document.selection;
+        viewSelection.on('change', () => {
+            const selectedElement = viewSelection.getSelectedElement();
+            const resizer = this.getResizerByViewElement(selectedElement) || null;
+            if (resizer) {
+                this.select(resizer);
+            }
+            else {
+                this.deselect();
+            }
+        });
+    }
+    /**
+     * Redraws the selected resizer if there is any selected resizer and if it is visible.
+     */
+    redrawSelectedResizer() {
+        if (this.selectedResizer && this.selectedResizer.isVisible) {
+            this.selectedResizer.redraw();
+        }
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this._observer.stopListening();
+        for (const resizer of this._resizers.values()) {
+            resizer.destroy();
+        }
+        this._redrawSelectedResizerThrottled.cancel();
+    }
+    /**
+     * Marks resizer as selected.
+     */
+    select(resizer) {
+        this.deselect();
+        this.selectedResizer = resizer;
+        this.selectedResizer.isSelected = true;
+    }
+    /**
+     * Deselects currently set resizer.
+     */
+    deselect() {
+        if (this.selectedResizer) {
+            this.selectedResizer.isSelected = false;
+        }
+        this.selectedResizer = null;
+    }
+    /**
+     * @param options Resizer options.
+     */
+    attachTo(options) {
+        const resizer = new Resizer(options);
+        const plugins = this.editor.plugins;
+        resizer.attach();
+        if (plugins.has('WidgetToolbarRepository')) {
+            // Hiding widget toolbar to improve the performance
+            // (https://github.com/ckeditor/ckeditor5-widget/pull/112#issuecomment-564528765).
+            const widgetToolbarRepository = plugins.get('WidgetToolbarRepository');
+            resizer.on('begin', () => {
+                widgetToolbarRepository.forceDisabled('resize');
+            }, { priority: 'lowest' });
+            resizer.on('cancel', () => {
+                widgetToolbarRepository.clearForceDisabled('resize');
+            }, { priority: 'highest' });
+            resizer.on('commit', () => {
+                widgetToolbarRepository.clearForceDisabled('resize');
+            }, { priority: 'highest' });
+        }
+        this._resizers.set(options.viewElement, resizer);
+        const viewSelection = this.editor.editing.view.document.selection;
+        const selectedElement = viewSelection.getSelectedElement();
+        // If the element the resizer is created for is currently focused, it should become visible.
+        if (this.getResizerByViewElement(selectedElement) == resizer) {
+            this.select(resizer);
+        }
+        return resizer;
+    }
+    /**
+     * Returns a resizer created for a given view element (widget element).
+     *
+     * @param viewElement View element associated with the resizer.
+     */
+    getResizerByViewElement(viewElement) {
+        return this._resizers.get(viewElement);
+    }
+    /**
+     * Returns a resizer that contains a given resize handle.
+     */
+    _getResizerByHandle(domResizeHandle) {
+        for (const resizer of this._resizers.values()) {
+            if (resizer.containsHandle(domResizeHandle)) {
+                return resizer;
+            }
+        }
+    }
+    /**
+     * @param domEventData Native DOM event.
+     */
+    _mouseDownListener(event, domEventData) {
+        const resizeHandle = domEventData.domTarget;
+        if (!Resizer.isResizeHandle(resizeHandle)) {
+            return;
+        }
+        this._activeResizer = this._getResizerByHandle(resizeHandle) || null;
+        if (this._activeResizer) {
+            this._activeResizer.begin(resizeHandle);
+            // Do not call other events when resizing. See: #6755.
+            event.stop();
+            domEventData.preventDefault();
+        }
+    }
+    /**
+     * @param domEventData Native DOM event.
+     */
+    _mouseMoveListener(event, domEventData) {
+        if (this._activeResizer) {
+            this._activeResizer.updateSize(domEventData);
+        }
+    }
+    _mouseUpListener() {
+        if (this._activeResizer) {
+            this._activeResizer.commit();
+            this._activeResizer = null;
+        }
+    }
+}

package/src/widgettoolbarrepository.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @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/widgettoolbarrepository
+ */
+import { Plugin, type ToolbarConfigItem } from '@ckeditor/ckeditor5-core';
+import type { ViewDocumentSelection, ViewElement } from '@ckeditor/ckeditor5-engine';
+import { ContextualBalloon } from '@ckeditor/ckeditor5-ui';
+/**
+ * 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(): readonly [typeof ContextualBalloon];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "WidgetToolbarRepository";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @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:ui/editorui/editorui~EditorUI#event:update}.
+     */
+    private _showToolbar;
+    private _isToolbarVisible;
+    private _isToolbarInBalloon;
+}