@ckeditor/ckeditor5-widget 36.0.0 → 37.0.0-alpha.0

package/src/utils.js

@@ -13,21 +13,14 @@ import { getTypeAroundFakeCaretPosition } from './widgettypearound/utils';
 import dragHandleIcon from '../theme/icons/drag-handle.svg';
 /**
  * CSS class added to each widget element.
- *
- * @const {String}
  */
 export const WIDGET_CLASS_NAME = 'ck-widget';
 /**
  * CSS class added to currently selected widget element.
- *
- * @const {String}
  */
 export const WIDGET_SELECTED_CLASS_NAME = 'ck-widget_selected';
 /**
  * Returns `true` if given {@link module:engine/view/node~Node} is an {@link module:engine/view/element~Element} and a widget.
- *
- * @param {module:engine/view/node~Node} node
- * @returns {Boolean}
  */
 export function isWidget(node) {
     if (!node.is('element')) {
@@ -52,34 +45,34 @@ export function isWidget(node) {
  * For example, in order to convert a `<widget>` model element to `<div class="widget">` in the view, you can define
  * such converters:
  *
- *		editor.conversion.for( 'editingDowncast' )
- *			.elementToElement( {
- *				model: 'widget',
- *				view: ( modelItem, { writer } ) => {
- *					const div = writer.createContainerElement( 'div', { class: 'widget' } );
- *
- *					return toWidget( div, writer, { label: 'some widget' } );
- *				}
- *			} );
- *
- *		editor.conversion.for( 'dataDowncast' )
- *			.elementToElement( {
- *				model: 'widget',
- *				view: ( modelItem, { writer } ) => {
- *					return writer.createContainerElement( 'div', { class: 'widget' } );
- *				}
- *			} );
+ * ```ts
+ * editor.conversion.for( 'editingDowncast' )
+ * 	.elementToElement( {
+ * 		model: 'widget',
+ * 		view: ( modelItem, { writer } ) => {
+ * 			const div = writer.createContainerElement( 'div', { class: 'widget' } );
+ *
+ * 			return toWidget( div, writer, { label: 'some widget' } );
+ * 		}
+ * 	} );
+ *
+ * editor.conversion.for( 'dataDowncast' )
+ * 	.elementToElement( {
+ * 		model: 'widget',
+ * 		view: ( modelItem, { writer } ) => {
+ * 			return writer.createContainerElement( 'div', { class: 'widget' } );
+ * 		}
+ * 	} );
+ * ```
  *
  * See the full source code of the widget (with a nested editable) schema definition and converters in
  * [this sample](https://github.com/ckeditor/ckeditor5-widget/blob/master/tests/manual/widget-with-nestededitable.js).
  *
- * @param {module:engine/view/element~Element} element
- * @param {module:engine/view/downcastwriter~DowncastWriter} writer
- * @param {Object} [options={}]
- * @param {String|Function} [options.label] Element's label provided to the {@link ~setLabel} function. It can be passed as
+ * @param options Additional options.
+ * @param options.label Element's label provided to the {@link ~setLabel} function. It can be passed as
  * a plain string or a function returning a string. It represents the widget for assistive technologies (like screen readers).
- * @param {Boolean} [options.hasSelectionHandle=false] If `true`, the widget will have a selection handle added.
- * @returns {module:engine/view/element~Element} Returns the same element.
+ * @param options.hasSelectionHandle If `true`, the widget will have a selection handle added.
+ * @returns Returns the same element.
  */
 export function toWidget(element, writer, options = {}) {
     if (!element.is('containerElement')) {
@@ -88,7 +81,7 @@ export function toWidget(element, writer, options = {}) {
          * instance.
          *
          * @error widget-to-widget-wrong-element-type
-         * @param {String} element The view element passed to `toWidget()`.
+         * @param element The view element passed to `toWidget()`.
          */
         throw new CKEditorError('widget-to-widget-wrong-element-type', null, { element });
     }
@@ -106,12 +99,10 @@ export function toWidget(element, writer, options = {}) {
     setHighlightHandling(element, writer);
     return element;
 }
-// Default handler for adding a highlight on a widget.
-// It adds CSS class and attributes basing on the given highlight descriptor.
-//
-// @param {module:engine/view/element~Element} element
-// @param {module:engine/conversion/downcasthelpers~HighlightDescriptor} descriptor
-// @param {module:engine/view/downcastwriter~DowncastWriter} writer
+/**
+ * Default handler for adding a highlight on a widget.
+ * It adds CSS class and attributes basing on the given highlight descriptor.
+ */
 function addHighlight(element, descriptor, writer) {
     if (descriptor.classes) {
         writer.addClass(toArray(descriptor.classes), element);
@@ -122,12 +113,10 @@ function addHighlight(element, descriptor, writer) {
         }
     }
 }
-// Default handler for removing a highlight from a widget.
-// It removes CSS class and attributes basing on the given highlight descriptor.
-//
-// @param {module:engine/view/element~Element} element
-// @param {module:engine/conversion/downcasthelpers~HighlightDescriptor} descriptor
-// @param {module:engine/view/downcastwriter~DowncastWriter} writer
+/**
+ * Default handler for removing a highlight from a widget.
+ * It removes CSS class and attributes basing on the given highlight descriptor.
+ */
 function removeHighlight(element, descriptor, writer) {
     if (descriptor.classes) {
         writer.removeClass(toArray(descriptor.classes), element);
@@ -141,11 +130,6 @@ function removeHighlight(element, descriptor, writer) {
 /**
  * Sets highlight handling methods. Uses {@link module:widget/highlightstack~HighlightStack} to
  * properly determine which highlight descriptor should be used at given time.
- *
- * @param {module:engine/view/element~Element} element
- * @param {module:engine/view/downcastwriter~DowncastWriter} writer
- * @param {Function} [add]
- * @param {Function} [remove]
  */
 export function setHighlightHandling(element, writer, add = addHighlight, remove = removeHighlight) {
     const stack = new HighlightStack();
@@ -166,9 +150,6 @@ export function setHighlightHandling(element, writer, add = addHighlight, remove
  * Sets label for given element.
  * It can be passed as a plain string or a function returning a string. Function will be called each time label is retrieved by
  * {@link ~getLabel `getLabel()`}.
- *
- * @param {module:engine/view/element~Element} element
- * @param {string|Function} labelOrCreator
  */
 export function setLabel(element, labelOrCreator) {
     const widgetLabel = element.getCustomProperty('widgetLabel');
@@ -176,9 +157,6 @@ export function setLabel(element, labelOrCreator) {
 }
 /**
  * Returns the label of the provided element.
- *
- * @param {module:engine/view/element~Element} element
- * @returns {String}
  */
 export function getLabel(element) {
     const widgetLabel = element.getCustomProperty('widgetLabel');
@@ -206,32 +184,32 @@ export function getLabel(element) {
  * For example, in order to convert a `<nested>` model element to `<div class="nested">` in the view, you can define
  * such converters:
  *
- *		editor.conversion.for( 'editingDowncast' )
- *			.elementToElement( {
- *				model: 'nested',
- *				view: ( modelItem, { writer } ) => {
- *					const div = writer.createEditableElement( 'div', { class: 'nested' } );
- *
- *					return toWidgetEditable( nested, writer, { label: 'label for editable' } );
- *				}
- *			} );
- *
- *		editor.conversion.for( 'dataDowncast' )
- *			.elementToElement( {
- *				model: 'nested',
- *				view: ( modelItem, { writer } ) => {
- *					return writer.createContainerElement( 'div', { class: 'nested' } );
- *				}
- *			} );
+ * ```ts
+ * editor.conversion.for( 'editingDowncast' )
+ * 	.elementToElement( {
+ * 		model: 'nested',
+ * 		view: ( modelItem, { writer } ) => {
+ * 			const div = writer.createEditableElement( 'div', { class: 'nested' } );
+ *
+ * 			return toWidgetEditable( nested, writer, { label: 'label for editable' } );
+ * 		}
+ * 	} );
+ *
+ * editor.conversion.for( 'dataDowncast' )
+ * 	.elementToElement( {
+ * 		model: 'nested',
+ * 		view: ( modelItem, { writer } ) => {
+ * 			return writer.createContainerElement( 'div', { class: 'nested' } );
+ * 		}
+ * 	} );
+ * ```
  *
  * See the full source code of the widget (with nested editable) schema definition and converters in
  * [this sample](https://github.com/ckeditor/ckeditor5-widget/blob/master/tests/manual/widget-with-nestededitable.js).
  *
- * @param {module:engine/view/editableelement~EditableElement} editable
- * @param {module:engine/view/downcastwriter~DowncastWriter} writer
- * @param {Object} [options] Additional options.
- * @param {String} [options.label] Editable's label used by assistive technologies (e.g. screen readers).
- * @returns {module:engine/view/editableelement~EditableElement} Returns the same element that was provided in the `editable` parameter
+ * @param options Additional options.
+ * @param options.label Editable's label used by assistive technologies (e.g. screen readers).
+ * @returns Returns the same element that was provided in the `editable` parameter
  */
 export function toWidgetEditable(editable, writer, options = {}) {
     writer.addClass(['ck-editor__editable', 'ck-editor__nested-editable'], editable);
@@ -267,10 +245,9 @@ export function toWidgetEditable(editable, writer, options = {}) {
  * is then passed to {@link module:engine/model/model~Model#insertContent}, the block will be fully replaced
  * by the inserted widget block.
  *
- * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
- * The selection based on which the insertion position should be calculated.
- * @param {module:engine/model/model~Model} model Model instance.
- * @returns {module:engine/model/range~Range} The optimal range.
+ * @param selection The selection based on which the insertion position should be calculated.
+ * @param model Model instance.
+ * @returns The optimal range.
  */
 export function findOptimalInsertionRange(selection, model) {
     const selectedElement = selection.getSelectedElement();
@@ -290,42 +267,49 @@ export function findOptimalInsertionRange(selection, model) {
  *
  * For example:
  *
- *		// Model:
- *		<placeholder type="name"></placeholder>
+ * ```
+ * // Model:
+ * <placeholder type="name"></placeholder>
  *
- *		// View:
- *		<span class="placeholder">name</span>
+ * // View:
+ * <span class="placeholder">name</span>
+ * ```
  *
- * In such case, view positions inside `<span>` cannot be correct mapped to the model (because the model element is empty).
+ * In such case, view positions inside `<span>` cannot be correctly mapped to the model (because the model element is empty).
  * To handle mapping positions inside `<span class="placeholder">` to the model use this util as follows:
  *
- *		editor.editing.mapper.on(
- *			'viewToModelPosition',
- *			viewToModelPositionOutsideModelElement( model, viewElement => viewElement.hasClass( 'placeholder' ) )
- *		);
+ * ```ts
+ * editor.editing.mapper.on(
+ * 	'viewToModelPosition',
+ * 	viewToModelPositionOutsideModelElement( model, viewElement => viewElement.hasClass( 'placeholder' ) )
+ * );
+ * ```
  *
  * The callback will try to map the view offset of selection to an expected model position.
  *
  * 1. When the position is at the end (or in the middle) of the inline widget:
  *
- *		// View:
- *		<p>foo <span class="placeholder">name|</span> bar</p>
+ * ```
+ * // View:
+ * <p>foo <span class="placeholder">name|</span> bar</p>
  *
- *		// Model:
- *		<paragraph>foo <placeholder type="name"></placeholder>| bar</paragraph>
+ * // Model:
+ * <paragraph>foo <placeholder type="name"></placeholder>| bar</paragraph>
+ * ```
  *
  * 2. When the position is at the beginning of the inline widget:
  *
- *		// View:
- *		<p>foo <span class="placeholder">|name</span> bar</p>
+ * ```
+ * // View:
+ * <p>foo <span class="placeholder">|name</span> bar</p>
  *
- *		// Model:
- *		<paragraph>foo |<placeholder type="name"></placeholder> bar</paragraph>
+ * // Model:
+ * <paragraph>foo |<placeholder type="name"></placeholder> bar</paragraph>
+ * ```
  *
- * @param {module:engine/model/model~Model} model Model instance on which the callback operates.
- * @param {Function} viewElementMatcher Function that is passed a view element and should return `true` if the custom mapping
+ * @param model Model instance on which the callback operates.
+ * @param viewElementMatcher Function that is passed a view element and should return `true` if the custom mapping
  * should be applied to the given view element.
- * @return {Function}
  */
 export function viewToModelPositionOutsideModelElement(model, viewElementMatcher) {
     return (evt, data) => {
@@ -338,16 +322,15 @@ export function viewToModelPositionOutsideModelElement(model, viewElementMatcher
         data.modelPosition = model.createPositionAt(modelParent, viewPosition.isAtStart ? 'before' : 'after');
     };
 }
-// Default filler offset function applied to all widget elements.
-//
-// @returns {null}
+/**
+ * Default filler offset function applied to all widget elements.
+ */
 function getFillerOffset() {
     return null;
 }
-// Adds a drag handle to the widget.
-//
-// @param {module:engine/view/containerelement~ContainerElement}
-// @param {module:engine/view/downcastwriter~DowncastWriter} writer
+/**
+ * Adds a drag handle to the widget.
+ */
 function addSelectionHandle(widgetElement, writer) {
     const selectionHandle = writer.createUIElement('div', { class: 'ck ck-widget__selection-handle' }, function (domDocument) {
         const domElement = this.toDomElement(domDocument);

package/src/verticalnavigation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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
+ */
+/**
+ * @module widget/verticalnavigationhandler
+ */
+import { type GetCallback } from '@ckeditor/ckeditor5-utils';
+import type { EditingController, ViewDocumentArrowKeyEvent } from '@ckeditor/ckeditor5-engine';
+/**
+ * Returns 'keydown' handler for up/down arrow keys that modifies the caret movement if it's in a text line next to an object.
+ *
+ * @param editing The editing controller.
+ */
+export default function verticalNavigationHandler(editing: EditingController): GetCallback<ViewDocumentArrowKeyEvent>;

package/src/verticalnavigation.js

@@ -2,15 +2,14 @@
  * @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 { keyCodes, Rect } from '@ckeditor/ckeditor5-utils';
 /**
  * @module widget/verticalnavigationhandler
  */
+import { keyCodes, Rect } from '@ckeditor/ckeditor5-utils';
 /**
  * Returns 'keydown' handler for up/down arrow keys that modifies the caret movement if it's in a text line next to an object.
  *
- * @param {module:engine/controller/editingcontroller~EditingController} editing The editing controller.
- * @returns {Function}
+ * @param editing The editing controller.
  */
 export default function verticalNavigationHandler(editing) {
     const model = editing.model;
@@ -67,16 +66,16 @@ export default function verticalNavigationHandler(editing) {
         }
     };
 }
-// Finds the range between selection and closest limit element (in the direction of navigation).
-// The position next to limit element is adjusted to the closest allowed `$text` position.
-//
-// Returns `null` if, according to the schema, the resulting range cannot contain a `$text` element.
-//
-// @param {module:engine/controller/editingcontroller~EditingController} editing The editing controller.
-// @param {module:engine/model/selection~Selection} selection The current selection.
-// @param {Boolean} isForward The expected navigation direction.
-// @returns {module:engine/model/range~Range|null}
-//
+/**
+ * Finds the range between selection and closest limit element (in the direction of navigation).
+ * The position next to limit element is adjusted to the closest allowed `$text` position.
+ *
+ * Returns `null` if, according to the schema, the resulting range cannot contain a `$text` element.
+ *
+ * @param editing The editing controller.
+ * @param selection The current selection.
+ * @param isForward The expected navigation direction.
+ */
 function findTextRangeFromSelection(editing, selection, isForward) {
     const model = editing.model;
     if (isForward) {
@@ -108,13 +107,11 @@ function findTextRangeFromSelection(editing, selection, isForward) {
         return null;
     }
 }
-// Finds the limit element position that is closest to startPosition.
-//
-// @param {module:engine/model/model~Model} model
-// @param {<module:engine/model/position~Position>} startPosition
-// @param {'forward'|'backward'} direction Search direction.
-// @returns {<module:engine/model/position~Position>|null}
-//
+/**
+ * Finds the limit element position that is closest to startPosition.
+ *
+ * @param direction Search direction.
+ */
 function getNearestNonInlineLimit(model, startPosition, direction) {
     const schema = model.schema;
     const range = model.createRangeIn(startPosition.root);
@@ -130,14 +127,16 @@ function getNearestNonInlineLimit(model, startPosition, direction) {
     }
     return null;
 }
-// Basing on the provided range, finds the first or last (depending on `direction`) position inside the range
-// that can contain `$text` (according to schema).
-//
-// @param {module:engine/model/schema~Schema} schema The schema.
-// @param {module:engine/model/range~Range} range The range to find the position in.
-// @param {'forward'|'backward'} direction Search direction.
-// @returns {module:engine/model/position~Position|null} The nearest selection position.
-//
+/**
+ * Basing on the provided range, finds the first or last (depending on `direction`) position inside the range
+ * that can contain `$text` (according to schema).
+ *
+ * @param schema The schema.
+ * @param range The range to find the position in.
+ * @param direction Search direction.
+ * @returns The nearest selection position.
+ *
+ */
 function getNearestTextPosition(schema, range, direction) {
     const position = direction == 'backward' ? range.end : range.start;
     if (schema.checkChild(position, '$text')) {
@@ -150,14 +149,14 @@ function getNearestTextPosition(schema, range, direction) {
     }
     return null;
 }
-// Checks if the DOM range corresponding to the provided model range renders as a single line by analyzing DOMRects
-// (verifying if they visually wrap content to the next line).
-//
-// @param {module:engine/controller/editingcontroller~EditingController} editing The editing controller.
-// @param {module:engine/model/range~Range} modelRange The current table cell content range.
-// @param {Boolean} isForward The expected navigation direction.
-// @returns {Boolean}
-//
+/**
+ * Checks if the DOM range corresponding to the provided model range renders as a single line by analyzing DOMRects
+ * (verifying if they visually wrap content to the next line).
+ *
+ * @param editing The editing controller.
+ * @param modelRange The current table cell content range.
+ * @param isForward The expected navigation direction.
+ */
 function isSingleLineRange(editing, modelRange, isForward) {
     const model = editing.model;
     const domConverter = editing.view.domConverter;

package/src/widget.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @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
+ */
+/**
+ * @module widget/widget
+ */
+import { Plugin, type PluginDependencies } from '@ckeditor/ckeditor5-core';
+import { type Element, type Node } from '@ckeditor/ckeditor5-engine';
+import '../theme/widget.css';
+/**
+ * The widget plugin. It enables base support for widgets.
+ *
+ * See {@glink api/widget package page} for more details and documentation.
+ *
+ * This plugin enables multiple behaviors required by widgets:
+ *
+ * * The model to view selection converter for the editing pipeline (it handles widget custom selection rendering).
+ * If a converted selection wraps around a widget element, that selection is marked as
+ * {@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.
+ */
+export default class Widget extends Plugin {
+    /**
+     * Holds previously selected widgets.
+     */
+    private _previouslySelected;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Widget';
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Handles {@link module:engine/view/document~Document#event:mousedown mousedown} events on widget elements.
+     */
+    private _onMousedown;
+    /**
+     * Handles {@link module:engine/view/document~Document#event:keydown keydown} events and changes
+     * the model selection when:
+     *
+     * * arrow key is pressed when the widget is selected,
+     * * the selection is next to a widget and the widget should become selected upon the arrow key press.
+     *
+     * See {@link #_preventDefaultOnArrowKeyPress}.
+     */
+    private _handleSelectionChangeOnArrowKeyPress;
+    /**
+     * Handles {@link module:engine/view/document~Document#event:keydown keydown} events and prevents
+     * the default browser behavior to make sure the fake selection is not being moved from a fake selection
+     * container.
+     *
+     * See {@link #_handleSelectionChangeOnArrowKeyPress}.
+     */
+    private _preventDefaultOnArrowKeyPress;
+    /**
+     * Handles delete keys: backspace and delete.
+     *
+     * @param isForward Set to true if delete was performed in forward direction.
+     * @returns Returns `true` if keys were handled correctly.
+     */
+    private _handleDelete;
+    /**
+     * Sets {@link module:engine/model/selection~Selection document's selection} over given element.
+     *
+     * @internal
+     */
+    _setSelectionOverElement(element: Node): void;
+    /**
+     * Checks if {@link module:engine/model/element~Element element} placed next to the current
+     * {@link module:engine/model/selection~Selection model selection} exists and is marked in
+     * {@link module:engine/model/schema~Schema schema} as `object`.
+     *
+     * @internal
+     * @param forward Direction of checking.
+     */
+    _getObjectElementNextToSelection(forward: boolean): Element | null;
+    /**
+     * Removes CSS class from previously selected widgets.
+     */
+    private _clearPreviouslySelectedWidgets;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [Widget.pluginName]: Widget;
+    }
+}