@ckeditor/ckeditor5-widget 41.3.1 → 41.4.0

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

@@ -0,0 +1,233 @@
+/**
+ * @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/widgettypearound/widgettypearound
+ */
+import { Plugin } from '@ckeditor/ckeditor5-core';
+import { Enter } from '@ckeditor/ckeditor5-enter';
+import { Delete } from '@ckeditor/ckeditor5-typing';
+import '../../theme/widgettypearound.css';
+/**
+ * A plugin that allows users to type around widgets where normally it is impossible to place the caret due
+ * to limitations of web browsers. These "tight spots" occur, for instance, before (or after) a widget being
+ * the first (or last) child of its parent or between two block widgets.
+ *
+ * This plugin extends the {@link module:widget/widget~Widget `Widget`} plugin and injects the user interface
+ * with two buttons into each widget instance in the editor. Each of the buttons can be clicked by the
+ * user if the widget is next to the "tight spot". Once clicked, a paragraph is created with the selection anchored
+ * in it so that users can type (or insert content, paste, etc.) straight away.
+ */
+export default class WidgetTypeAround extends Plugin {
+    /**
+     * A reference to the model widget element that has the fake caret active
+     * on either side of it. It is later used to remove CSS classes associated with the fake caret
+     * when the widget no longer needs it.
+     */
+    private _currentFakeCaretModelElement;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "WidgetTypeAround";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof Enter, typeof Delete];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Inserts a new paragraph next to a widget element with the selection anchored in it.
+     *
+     * **Note**: This method is heavily user-oriented and will both focus the editing view and scroll
+     * the viewport to the selection in the inserted paragraph.
+     *
+     * @param widgetModelElement The model widget element next to which a paragraph is inserted.
+     * @param position The position where the paragraph is inserted. Either `'before'` or `'after'` the widget.
+     */
+    private _insertParagraph;
+    /**
+     * A wrapper for the {@link module:utils/emittermixin~Emitter#listenTo} method that executes the callbacks only
+     * when the plugin {@link #isEnabled is enabled}.
+     *
+     * @param emitter The object that fires the event.
+     * @param event The name of the event.
+     * @param callback The function to be called on event.
+     * @param options Additional options.
+     * @param options.priority The priority of this event callback. The higher the priority value the sooner
+     * the callback will be fired. Events having the same priority are called in the order they were added.
+     */
+    private _listenToIfEnabled;
+    /**
+     * Similar to {@link #_insertParagraph}, this method inserts a paragraph except that it
+     * does not expect a position. Instead, it performs the insertion next to a selected widget
+     * according to the `widget-type-around` model selection attribute value (fake caret position).
+     *
+     * Because this method requires the `widget-type-around` attribute to be set,
+     * the insertion can only happen when the widget's fake caret is active (e.g. activated
+     * using the keyboard).
+     *
+     * @returns Returns `true` when the paragraph was inserted (the attribute was present) and `false` otherwise.
+     */
+    private _insertParagraphAccordingToFakeCaretPosition;
+    /**
+     * Creates a listener in the editing conversion pipeline that injects the widget type around
+     * UI into every single widget instance created in the editor.
+     *
+     * The UI is delivered as a {@link module:engine/view/uielement~UIElement}
+     * wrapper which renders DOM buttons that users can use to insert paragraphs.
+     */
+    private _enableTypeAroundUIInjection;
+    /**
+     * Brings support for the fake caret that appears when either:
+     *
+     * * the selection moves to a widget from a position next to it using arrow keys,
+     * * the arrow key is pressed when the widget is already selected.
+     *
+     * The fake caret lets the user know that they can start typing or just press
+     * <kbd>Enter</kbd> to insert a paragraph at the position next to a widget as suggested by the fake caret.
+     *
+     * The fake caret disappears when the user changes the selection or the editor
+     * gets blurred.
+     *
+     * The whole idea is as follows:
+     *
+     * 1. A user does one of the 2 scenarios described at the beginning.
+     * 2. The "keydown" listener is executed and the decision is made whether to show or hide the fake caret.
+     * 3. If it should show up, the `widget-type-around` model selection attribute is set indicating
+     *    on which side of the widget it should appear.
+     * 4. The selection dispatcher reacts to the selection attribute and sets CSS classes responsible for the
+     *    fake caret on the view widget.
+     * 5. If the fake caret should disappear, the selection attribute is removed and the dispatcher
+     *    does the CSS class clean-up in the view.
+     * 6. Additionally, `change:range` and `FocusTracker#isFocused` listeners also remove the selection
+     *    attribute (the former also removes widget CSS classes).
+     */
+    private _enableTypeAroundFakeCaretActivationUsingKeyboardArrows;
+    /**
+     * A listener executed on each "keydown" in the view document, a part of
+     * {@link #_enableTypeAroundFakeCaretActivationUsingKeyboardArrows}.
+     *
+     * It decides whether the arrow keypress should activate the fake caret or not (also whether it should
+     * be deactivated).
+     *
+     * The fake caret activation is done by setting the `widget-type-around` model selection attribute
+     * in this listener, and stopping and preventing the event that would normally be handled by the widget
+     * plugin that is responsible for the regular keyboard navigation near/across all widgets (that
+     * includes inline widgets, which are ignored by the widget type around plugin).
+     */
+    private _handleArrowKeyPress;
+    /**
+     * Handles the keyboard navigation on "keydown" when a widget is currently selected and activates or deactivates
+     * the fake caret for that widget, depending on the current value of the `widget-type-around` model
+     * selection attribute and the direction of the pressed arrow key.
+     *
+     * @param isForward `true` when the pressed arrow key was responsible for the forward model selection movement
+     * as in {@link module:utils/keyboard~isForwardArrowKeyCode}.
+     * @returns Returns `true` when the keypress was handled and no other keydown listener of the editor should
+     * process the event any further. Returns `false` otherwise.
+     */
+    private _handleArrowKeyPressOnSelectedWidget;
+    /**
+     * Handles the keyboard navigation on "keydown" when **no** widget is selected but the selection is **directly** next
+     * to one and upon the fake caret should become active for this widget upon arrow keypress
+     * (AKA entering/selecting the widget).
+     *
+     * **Note**: This code mirrors the implementation from the widget plugin but also adds the selection attribute.
+     * Unfortunately, there is no safe way to let the widget plugin do the selection part first and then just set the
+     * selection attribute here in the widget type around plugin. This is why this code must duplicate some from the widget plugin.
+     *
+     * @param isForward `true` when the pressed arrow key was responsible for the forward model selection movement
+     * as in {@link module:utils/keyboard~isForwardArrowKeyCode}.
+     * @returns Returns `true` when the keypress was handled and no other keydown listener of the editor should
+     * process the event any further. Returns `false` otherwise.
+     */
+    private _handleArrowKeyPressWhenSelectionNextToAWidget;
+    /**
+     * Handles the keyboard navigation on "keydown" when a widget is currently selected (together with some other content)
+     * and the widget is the first or last element in the selection. It activates or deactivates the fake caret for that widget.
+     *
+     * @param isForward `true` when the pressed arrow key was responsible for the forward model selection movement
+     * as in {@link module:utils/keyboard~isForwardArrowKeyCode}.
+     * @returns Returns `true` when the keypress was handled and no other keydown listener of the editor should
+     * process the event any further. Returns `false` otherwise.
+     */
+    private _handleArrowKeyPressWhenNonCollapsedSelection;
+    /**
+     * Registers a `mousedown` listener for the view document which intercepts events
+     * coming from the widget type around UI, which happens when a user clicks one of the buttons
+     * that insert a paragraph next to a widget.
+     */
+    private _enableInsertingParagraphsOnButtonClick;
+    /**
+     * Creates the <kbd>Enter</kbd> key listener on the view document that allows the user to insert a paragraph
+     * near the widget when either:
+     *
+     * * The fake caret was first activated using the arrow keys,
+     * * The entire widget is selected in the model.
+     *
+     * In the first case, the new paragraph is inserted according to the `widget-type-around` selection
+     * attribute (see {@link #_handleArrowKeyPress}).
+     *
+     * In the second case, the new paragraph is inserted based on whether a soft (<kbd>Shift</kbd>+<kbd>Enter</kbd>) keystroke
+     * was pressed or not.
+     */
+    private _enableInsertingParagraphsOnEnterKeypress;
+    /**
+     * Similar to the {@link #_enableInsertingParagraphsOnEnterKeypress}, it allows the user
+     * to insert a paragraph next to a widget when the fake caret was activated using arrow
+     * keys but it responds to typing instead of <kbd>Enter</kbd>.
+     *
+     * Listener enabled by this method will insert a new paragraph according to the `widget-type-around`
+     * model selection attribute as the user simply starts typing, which creates the impression that the fake caret
+     * behaves like a real one rendered by the browser (AKA your text appears where the caret was).
+     *
+     * **Note**: At the moment this listener creates 2 undo steps: one for the `insertParagraph` command
+     * and another one for actual typing. It is not a disaster but this may need to be fixed
+     * sooner or later.
+     */
+    private _enableInsertingParagraphsOnTypingKeystroke;
+    /**
+     * It creates a "delete" event listener on the view document to handle cases when the <kbd>Delete</kbd> or <kbd>Backspace</kbd>
+     * is pressed and the fake caret is currently active.
+     *
+     * The fake caret should create an illusion of a real browser caret so that when it appears before or after
+     * a widget, pressing <kbd>Delete</kbd> or <kbd>Backspace</kbd> should remove a widget or delete the content
+     * before or after a widget (depending on the content surrounding the widget).
+     */
+    private _enableDeleteIntegration;
+    /**
+     * Attaches the {@link module:engine/model/model~Model#event:insertContent} event listener that, for instance, allows the user to paste
+     * content near a widget when the fake caret is first activated using the arrow keys.
+     *
+     * The content is inserted according to the `widget-type-around` selection attribute (see {@link #_handleArrowKeyPress}).
+     */
+    private _enableInsertContentIntegration;
+    /**
+     * Attaches the {@link module:engine/model/model~Model#event:insertObject} event listener that modifies the
+     * `options.findOptimalPosition`parameter to position of fake caret in relation to selected element
+     * to reflect user's intent of desired insertion position.
+     *
+     * The object is inserted according to the `widget-type-around` selection attribute (see {@link #_handleArrowKeyPress}).
+     */
+    private _enableInsertObjectIntegration;
+    /**
+     * Attaches the {@link module:engine/model/model~Model#event:deleteContent} event listener to block the event when the fake
+     * caret is active.
+     *
+     * This is required for cases that trigger {@link module:engine/model/model~Model#deleteContent `model.deleteContent()`}
+     * before calling {@link module:engine/model/model~Model#insertContent `model.insertContent()`} like, for instance,
+     * plain text pasting.
+     */
+    private _enableDeleteContentIntegration;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-widget",
-  "version": "41.3.1",
+  "version": "41.4.0",
   "description": "Widget API for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -12,12 +12,12 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-core": "41.3.1",
-    "@ckeditor/ckeditor5-engine": "41.3.1",
-    "@ckeditor/ckeditor5-enter": "41.3.1",
-    "@ckeditor/ckeditor5-ui": "41.3.1",
-    "@ckeditor/ckeditor5-utils": "41.3.1",
-    "@ckeditor/ckeditor5-typing": "41.3.1",
+    "@ckeditor/ckeditor5-core": "41.4.0",
+    "@ckeditor/ckeditor5-engine": "41.4.0",
+    "@ckeditor/ckeditor5-enter": "41.4.0",
+    "@ckeditor/ckeditor5-ui": "41.4.0",
+    "@ckeditor/ckeditor5-utils": "41.4.0",
+    "@ckeditor/ckeditor5-typing": "41.4.0",
     "lodash-es": "4.17.21"
   },
   "author": "CKSource (http://cksource.com/)",
@@ -30,6 +30,7 @@
     "directory": "packages/ckeditor5-widget"
   },
   "files": [
+    "dist",
     "lang",
     "src/**/*.js",
     "src/**/*.d.ts",

package/src/utils.d.ts

@@ -5,7 +5,7 @@
 /**
  * @module widget/utils
  */
-import { type GetCallback } from '@ckeditor/ckeditor5-utils';
+import { Rect, type GetCallback } from '@ckeditor/ckeditor5-utils';
 import { type HighlightDescriptor, type MapperViewToModelPositionEvent, type DocumentSelection, type DowncastWriter, type Model, type Range, type Selection, type ViewEditableElement, type ViewElement, type ViewTypeCheckable } from '@ckeditor/ckeditor5-engine';
 /**
  * CSS class added to each widget element.
@@ -196,3 +196,20 @@ export declare function findOptimalInsertionRange(selection: Selection | Documen
  * should be applied to the given view element.
  */
 export declare function viewToModelPositionOutsideModelElement(model: Model, viewElementMatcher: (element: ViewElement) => boolean): GetCallback<MapperViewToModelPositionEvent>;
+/**
+ * Starting from a DOM resize host element (an element that receives dimensions as a result of resizing),
+ * this helper returns the width of the found ancestor element.
+ *
+ *	* It searches up to 5 levels of ancestors only.
+ *
+ * @param domResizeHost Resize host DOM element that receives dimensions as a result of resizing.
+ * @returns Width of ancestor element in pixels or 0 if no ancestor with a computed width has been found.
+ */
+export declare function calculateResizeHostAncestorWidth(domResizeHost: HTMLElement): number;
+/**
+ * Calculates a relative width of a `domResizeHost` compared to its ancestor in percents.
+ *
+ * @param domResizeHost Resize host DOM element.
+ * @returns Percentage value between 0 and 100.
+ */
+export declare function calculateResizeHostPercentageWidth(domResizeHost: HTMLElement, resizeHostRect?: Rect): number;

package/src/utils.js

@@ -5,7 +5,7 @@
 /**
  * @module widget/utils
  */
-import { CKEditorError, toArray } from '@ckeditor/ckeditor5-utils';
+import { Rect, CKEditorError, toArray } from '@ckeditor/ckeditor5-utils';
 import { IconView } from '@ckeditor/ckeditor5-ui';
 import HighlightStack from './highlightstack.js';
 import { getTypeAroundFakeCaretPosition } from './widgettypearound/utils.js';
@@ -346,3 +346,51 @@ function addSelectionHandle(widgetElement, writer) {
     writer.insert(writer.createPositionAt(widgetElement, 0), selectionHandle);
     writer.addClass(['ck-widget_with-selection-handle'], widgetElement);
 }
+/**
+ * Starting from a DOM resize host element (an element that receives dimensions as a result of resizing),
+ * this helper returns the width of the found ancestor element.
+ *
+ *	* It searches up to 5 levels of ancestors only.
+ *
+ * @param domResizeHost Resize host DOM element that receives dimensions as a result of resizing.
+ * @returns Width of ancestor element in pixels or 0 if no ancestor with a computed width has been found.
+ */
+export function calculateResizeHostAncestorWidth(domResizeHost) {
+    const getElementComputedWidth = (element) => {
+        const { width, paddingLeft, paddingRight } = element.ownerDocument.defaultView.getComputedStyle(element);
+        return parseFloat(width) - (parseFloat(paddingLeft) || 0) - (parseFloat(paddingRight) || 0);
+    };
+    const domResizeHostParent = domResizeHost.parentElement;
+    if (!domResizeHostParent) {
+        return 0;
+    }
+    // Need to use computed style as it properly excludes parent's paddings from the returned value.
+    let parentWidth = getElementComputedWidth(domResizeHostParent);
+    // Sometimes parent width cannot be accessed. If that happens we should go up in the elements tree
+    // and try to get width from next ancestor.
+    // https://github.com/ckeditor/ckeditor5/issues/10776
+    const ancestorLevelLimit = 5;
+    let currentLevel = 0;
+    let checkedElement = domResizeHostParent;
+    while (isNaN(parentWidth)) {
+        checkedElement = checkedElement.parentElement;
+        if (++currentLevel > ancestorLevelLimit) {
+            return 0;
+        }
+        parentWidth = getElementComputedWidth(checkedElement);
+    }
+    return parentWidth;
+}
+/**
+ * Calculates a relative width of a `domResizeHost` compared to its ancestor in percents.
+ *
+ * @param domResizeHost Resize host DOM element.
+ * @returns Percentage value between 0 and 100.
+ */
+export function calculateResizeHostPercentageWidth(domResizeHost, resizeHostRect = new Rect(domResizeHost)) {
+    const parentWidth = calculateResizeHostAncestorWidth(domResizeHost);
+    if (!parentWidth) {
+        return 0;
+    }
+    return resizeHostRect.width / parentWidth * 100;
+}

package/src/widgetresize/resizerstate.js

@@ -6,6 +6,7 @@
  * @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.
  */
@@ -64,7 +65,7 @@ export default class ResizeState extends ObservableMixin() {
             this._originalWidthPercents = parseFloat(widthStyle);
         }
         else {
-            this._originalWidthPercents = calculateHostPercentageWidth(domResizeHost, clientRect);
+            this._originalWidthPercents = calculateResizeHostPercentageWidth(domResizeHost, clientRect);
         }
     }
     update(newSize) {
@@ -75,28 +76,6 @@ export default class ResizeState extends ObservableMixin() {
         this.proposedHandleHostHeight = newSize.handleHostHeight;
     }
 }
-/**
- * Calculates a relative width of a `domResizeHost` compared to its ancestor 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.
-    let parentWidth = parseFloat(domResizeHostParent.ownerDocument.defaultView.getComputedStyle(domResizeHostParent).width);
-    // Sometimes parent width cannot be accessed. If that happens we should go up in the elements tree
-    // and try to get width from next ancestor.
-    // https://github.com/ckeditor/ckeditor5/issues/10776
-    const ancestorLevelLimit = 5;
-    let currentLevel = 0;
-    let checkedElement = domResizeHostParent;
-    while (isNaN(parentWidth)) {
-        checkedElement = checkedElement.parentElement;
-        if (++currentLevel > ancestorLevelLimit) {
-            return 0;
-        }
-        parentWidth = parseFloat(domResizeHostParent.ownerDocument.defaultView.getComputedStyle(checkedElement).width);
-    }
-    return resizeHostRect.width / parentWidth * 100;
-}
 /**
  * Returns coordinates of the top-left corner of an element, relative to the document's top-left corner.
  *