@ckeditor/ckeditor5-widget 41.3.1 → 41.4.0

package/dist/types/widgetresize/resizerstate.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
+ */
+/**
+ * @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 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 {};

package/dist/types/widgetresize/sizeview.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module 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/dist/types/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
+ */
+/**
+ * @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
+     */
+    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/dist/types/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
+ */
+/**
+ * @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
+     */
+    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;
+}

package/dist/types/widgettypearound/utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type { DocumentSelection, DomConverter, Element, Schema, Selection, ViewElement } from '@ckeditor/ckeditor5-engine';
+/**
+ * The name of the type around model selection attribute responsible for
+ * displaying a fake caret next to a selected widget.
+ */
+export declare const TYPE_AROUND_SELECTION_ATTRIBUTE = "widget-type-around";
+/**
+ * Checks if an element is a widget that qualifies to get the widget type around UI.
+ */
+export declare function isTypeAroundWidget(viewElement: ViewElement | undefined, modelElement: Element, schema: Schema): boolean;
+/**
+ * For the passed HTML element, this helper finds the closest widget type around button ancestor.
+ */
+export declare function getClosestTypeAroundDomButton(domElement: HTMLElement): HTMLElement | null;
+/**
+ * For the passed widget type around button element, this helper determines at which position
+ * the paragraph would be inserted into the content if, for instance, the button was
+ * clicked by the user.
+ *
+ * @returns The position of the button.
+ */
+export declare function getTypeAroundButtonPosition(domElement: HTMLElement): 'before' | 'after';
+/**
+ * For the passed HTML element, this helper returns the closest view widget ancestor.
+ */
+export declare function getClosestWidgetViewElement(domElement: HTMLElement, domConverter: DomConverter): ViewElement;
+/**
+ * For the passed selection instance, it returns the position of the fake caret displayed next to a widget.
+ *
+ * **Note**: If the fake caret is not currently displayed, `null` is returned.
+ *
+ * @returns The position of the fake caret or `null` when none is present.
+ */
+export declare function getTypeAroundFakeCaretPosition(selection: Selection | DocumentSelection): 'before' | 'after' | null;