@ckeditor/ckeditor5-widget 35.2.0 → 35.3.0

package/src/utils.js

@@ -2,51 +2,40 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module widget/utils
  */
-
 import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 import toArray from '@ckeditor/ckeditor5-utils/src/toarray';
-import {
-	findOptimalInsertionRange as engineFindOptimalInsertionRange
-} from '@ckeditor/ckeditor5-engine/src/model/utils/findoptimalinsertionrange';
-
+import { findOptimalInsertionRange as engineFindOptimalInsertionRange } from '@ckeditor/ckeditor5-engine/src/model/utils/findoptimalinsertionrange';
 import HighlightStack from './highlightstack';
 import { getTypeAroundFakeCaretPosition } from './widgettypearound/utils';
-
 import IconView from '@ckeditor/ckeditor5-ui/src/icon/iconview';
 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' ) ) {
-		return false;
-	}
-
-	return !!node.getCustomProperty( 'widget' );
+export function isWidget(node) {
+    if (!node.is('element')) {
+        return false;
+    }
+    return !!node.getCustomProperty('widget');
 }
-
 /**
  * Converts the given {@link module:engine/view/element~Element} to a widget in the following way:
  *
@@ -93,77 +82,62 @@ export function isWidget( node ) {
  * @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.
  */
-export function toWidget( element, writer, options = {} ) {
-	if ( !element.is( 'containerElement' ) ) {
-		/**
-		 * The element passed to `toWidget()` must be a {@link module:engine/view/containerelement~ContainerElement}
-		 * instance.
-		 *
-		 * @error widget-to-widget-wrong-element-type
-		 * @param {String} element The view element passed to `toWidget()`.
-		 */
-		throw new CKEditorError(
-			'widget-to-widget-wrong-element-type',
-			null,
-			{ element }
-		);
-	}
-
-	writer.setAttribute( 'contenteditable', 'false', element );
-
-	writer.addClass( WIDGET_CLASS_NAME, element );
-	writer.setCustomProperty( 'widget', true, element );
-	element.getFillerOffset = getFillerOffset;
-
-	if ( options.label ) {
-		setLabel( element, options.label, writer );
-	}
-
-	if ( options.hasSelectionHandle ) {
-		addSelectionHandle( element, writer );
-	}
-
-	setHighlightHandling( element, writer );
-
-	return element;
+export function toWidget(element, writer, options = {}) {
+    if (!element.is('containerElement')) {
+        /**
+         * The element passed to `toWidget()` must be a {@link module:engine/view/containerelement~ContainerElement}
+         * instance.
+         *
+         * @error widget-to-widget-wrong-element-type
+         * @param {String} element The view element passed to `toWidget()`.
+         */
+        throw new CKEditorError('widget-to-widget-wrong-element-type', null, { element });
+    }
+    writer.setAttribute('contenteditable', 'false', element);
+    writer.addClass(WIDGET_CLASS_NAME, element);
+    writer.setCustomProperty('widget', true, element);
+    element.getFillerOffset = getFillerOffset;
+    if (options.label) {
+        setLabel(element, options.label, writer);
+    }
+    if (options.hasSelectionHandle) {
+        addSelectionHandle(element, writer);
+    }
+    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
-function addHighlight( element, descriptor, writer ) {
-	if ( descriptor.classes ) {
-		writer.addClass( toArray( descriptor.classes ), element );
-	}
-
-	if ( descriptor.attributes ) {
-		for ( const key in descriptor.attributes ) {
-			writer.setAttribute( key, descriptor.attributes[ key ], element );
-		}
-	}
+function addHighlight(element, descriptor, writer) {
+    if (descriptor.classes) {
+        writer.addClass(toArray(descriptor.classes), element);
+    }
+    if (descriptor.attributes) {
+        for (const key in descriptor.attributes) {
+            writer.setAttribute(key, descriptor.attributes[key], element);
+        }
+    }
 }
-
 // 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
-function removeHighlight( element, descriptor, writer ) {
-	if ( descriptor.classes ) {
-		writer.removeClass( toArray( descriptor.classes ), element );
-	}
-
-	if ( descriptor.attributes ) {
-		for ( const key in descriptor.attributes ) {
-			writer.removeAttribute( key, element );
-		}
-	}
+function removeHighlight(element, descriptor, writer) {
+    if (descriptor.classes) {
+        writer.removeClass(toArray(descriptor.classes), element);
+    }
+    if (descriptor.attributes) {
+        for (const key in descriptor.attributes) {
+            writer.removeAttribute(key, element);
+        }
+    }
 }
-
 /**
  * Sets highlight handling methods. Uses {@link module:widget/highlightstack~HighlightStack} to
  * properly determine which highlight descriptor should be used at given time.
@@ -173,23 +147,21 @@ function removeHighlight( element, descriptor, writer ) {
  * @param {Function} [add]
  * @param {Function} [remove]
  */
-export function setHighlightHandling( element, writer, add = addHighlight, remove = removeHighlight ) {
-	const stack = new HighlightStack();
-
-	stack.on( 'change:top', ( evt, data ) => {
-		if ( data.oldDescriptor ) {
-			remove( element, data.oldDescriptor, data.writer );
-		}
-
-		if ( data.newDescriptor ) {
-			add( element, data.newDescriptor, data.writer );
-		}
-	} );
-
-	writer.setCustomProperty( 'addHighlight', ( element, descriptor, writer ) => stack.add( descriptor, writer ), element );
-	writer.setCustomProperty( 'removeHighlight', ( element, id, writer ) => stack.remove( id, writer ), element );
+export function setHighlightHandling(element, writer, add = addHighlight, remove = removeHighlight) {
+    const stack = new HighlightStack();
+    stack.on('change:top', (evt, data) => {
+        if (data.oldDescriptor) {
+            remove(element, data.oldDescriptor, data.writer);
+        }
+        if (data.newDescriptor) {
+            add(element, data.newDescriptor, data.writer);
+        }
+    });
+    const addHighlightCallback = (element, descriptor, writer) => stack.add(descriptor, writer);
+    const removeHighlightCallback = (element, id, writer) => stack.remove(id, writer);
+    writer.setCustomProperty('addHighlight', addHighlightCallback, element);
+    writer.setCustomProperty('removeHighlight', removeHighlightCallback, element);
 }
-
 /**
  * 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
@@ -199,26 +171,22 @@ export function setHighlightHandling( element, writer, add = addHighlight, remov
  * @param {String|Function} labelOrCreator
  * @param {module:engine/view/downcastwriter~DowncastWriter} writer
  */
-export function setLabel( element, labelOrCreator, writer ) {
-	writer.setCustomProperty( 'widgetLabel', labelOrCreator, element );
+export function setLabel(element, labelOrCreator, writer) {
+    writer.setCustomProperty('widgetLabel', labelOrCreator, element);
 }
-
 /**
  * Returns the label of the provided element.
  *
  * @param {module:engine/view/element~Element} element
  * @returns {String}
  */
-export function getLabel( element ) {
-	const labelCreator = element.getCustomProperty( 'widgetLabel' );
-
-	if ( !labelCreator ) {
-		return '';
-	}
-
-	return typeof labelCreator == 'function' ? labelCreator() : labelCreator;
+export function getLabel(element) {
+    const labelCreator = element.getCustomProperty('widgetLabel');
+    if (!labelCreator) {
+        return '';
+    }
+    return typeof labelCreator == 'function' ? labelCreator() : labelCreator;
 }
-
 /**
  * Adds functionality to the provided {@link module:engine/view/editableelement~EditableElement} to act as a widget's editable:
  *
@@ -261,36 +229,29 @@ export function getLabel( element ) {
  * @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
  */
-export function toWidgetEditable( editable, writer, options = {} ) {
-	writer.addClass( [ 'ck-editor__editable', 'ck-editor__nested-editable' ], editable );
-
-	writer.setAttribute( 'role', 'textbox', editable );
-
-	if ( options.label ) {
-		writer.setAttribute( 'aria-label', options.label, editable );
-	}
-
-	// Set initial contenteditable value.
-	writer.setAttribute( 'contenteditable', editable.isReadOnly ? 'false' : 'true', editable );
-
-	// Bind the contenteditable property to element#isReadOnly.
-	editable.on( 'change:isReadOnly', ( evt, property, is ) => {
-		writer.setAttribute( 'contenteditable', is ? 'false' : 'true', editable );
-	} );
-
-	editable.on( 'change:isFocused', ( evt, property, is ) => {
-		if ( is ) {
-			writer.addClass( 'ck-editor__nested-editable_focused', editable );
-		} else {
-			writer.removeClass( 'ck-editor__nested-editable_focused', editable );
-		}
-	} );
-
-	setHighlightHandling( editable, writer );
-
-	return editable;
+export function toWidgetEditable(editable, writer, options = {}) {
+    writer.addClass(['ck-editor__editable', 'ck-editor__nested-editable'], editable);
+    writer.setAttribute('role', 'textbox', editable);
+    if (options.label) {
+        writer.setAttribute('aria-label', options.label, editable);
+    }
+    // Set initial contenteditable value.
+    writer.setAttribute('contenteditable', editable.isReadOnly ? 'false' : 'true', editable);
+    // Bind the contenteditable property to element#isReadOnly.
+    editable.on('change:isReadOnly', (evt, property, is) => {
+        writer.setAttribute('contenteditable', is ? 'false' : 'true', editable);
+    });
+    editable.on('change:isFocused', (evt, property, is) => {
+        if (is) {
+            writer.addClass('ck-editor__nested-editable_focused', editable);
+        }
+        else {
+            writer.removeClass('ck-editor__nested-editable_focused', editable);
+        }
+    });
+    setHighlightHandling(editable, writer);
+    return editable;
 }
-
 /**
  * Returns a model range which is optimal (in terms of UX) for inserting a widget block.
  *
@@ -307,22 +268,18 @@ export function toWidgetEditable( editable, writer, options = {} ) {
  * @param {module:engine/model/model~Model} model Model instance.
  * @returns {module:engine/model/range~Range} The optimal range.
  */
-export function findOptimalInsertionRange( selection, model ) {
-	const selectedElement = selection.getSelectedElement();
-
-	if ( selectedElement ) {
-		const typeAroundFakeCaretPosition = getTypeAroundFakeCaretPosition( selection );
-
-		// If the WidgetTypeAround "fake caret" is displayed, use its position for the insertion
-		// to provide the most predictable UX (https://github.com/ckeditor/ckeditor5/issues/7438).
-		if ( typeAroundFakeCaretPosition ) {
-			return model.createRange( model.createPositionAt( selectedElement, typeAroundFakeCaretPosition ) );
-		}
-	}
-
-	return engineFindOptimalInsertionRange( selection, model );
+export function findOptimalInsertionRange(selection, model) {
+    const selectedElement = selection.getSelectedElement();
+    if (selectedElement) {
+        const typeAroundFakeCaretPosition = getTypeAroundFakeCaretPosition(selection);
+        // If the WidgetTypeAround "fake caret" is displayed, use its position for the insertion
+        // to provide the most predictable UX (https://github.com/ckeditor/ckeditor5/issues/7438).
+        if (typeAroundFakeCaretPosition) {
+            return model.createRange(model.createPositionAt(selectedElement, typeAroundFakeCaretPosition));
+        }
+    }
+    return engineFindOptimalInsertionRange(selection, model);
 }
-
 /**
  * A util to be used in order to map view positions to correct model positions when implementing a widget
  * which renders non-empty view element for an empty model element.
@@ -366,50 +323,39 @@ export function findOptimalInsertionRange( selection, model ) {
  * should be applied to the given view element.
  * @return {Function}
  */
-export function viewToModelPositionOutsideModelElement( model, viewElementMatcher ) {
-	return ( evt, data ) => {
-		const { mapper, viewPosition } = data;
-
-		const viewParent = mapper.findMappedViewAncestor( viewPosition );
-
-		if ( !viewElementMatcher( viewParent ) ) {
-			return;
-		}
-
-		const modelParent = mapper.toModelElement( viewParent );
-
-		data.modelPosition = model.createPositionAt( modelParent, viewPosition.isAtStart ? 'before' : 'after' );
-	};
+export function viewToModelPositionOutsideModelElement(model, viewElementMatcher) {
+    return (evt, data) => {
+        const { mapper, viewPosition } = data;
+        const viewParent = mapper.findMappedViewAncestor(viewPosition);
+        if (!viewElementMatcher(viewParent)) {
+            return;
+        }
+        const modelParent = mapper.toModelElement(viewParent);
+        data.modelPosition = model.createPositionAt(modelParent, viewPosition.isAtStart ? 'before' : 'after');
+    };
 }
-
 // Default filler offset function applied to all widget elements.
 //
 // @returns {null}
 function getFillerOffset() {
-	return null;
+    return null;
 }
-
 // Adds a drag handle to the widget.
 //
 // @param {module:engine/view/containerelement~ContainerElement}
 // @param {module:engine/view/downcastwriter~DowncastWriter} writer
-function addSelectionHandle( widgetElement, writer ) {
-	const selectionHandle = writer.createUIElement( 'div', { class: 'ck ck-widget__selection-handle' }, function( domDocument ) {
-		const domElement = this.toDomElement( domDocument );
-
-		// Use the IconView from the ui library.
-		const icon = new IconView();
-		icon.set( 'content', dragHandleIcon );
-
-		// Render the icon view right away to append its #element to the selectionHandle DOM element.
-		icon.render();
-
-		domElement.appendChild( icon.element );
-
-		return domElement;
-	} );
-
-	// Append the selection handle into the widget wrapper.
-	writer.insert( writer.createPositionAt( widgetElement, 0 ), selectionHandle );
-	writer.addClass( [ 'ck-widget_with-selection-handle' ], widgetElement );
+function addSelectionHandle(widgetElement, writer) {
+    const selectionHandle = writer.createUIElement('div', { class: 'ck ck-widget__selection-handle' }, function (domDocument) {
+        const domElement = this.toDomElement(domDocument);
+        // Use the IconView from the ui library.
+        const icon = new IconView();
+        icon.set('content', dragHandleIcon);
+        // Render the icon view right away to append its #element to the selectionHandle DOM element.
+        icon.render();
+        domElement.appendChild(icon.element);
+        return domElement;
+    });
+    // Append the selection handle into the widget wrapper.
+    writer.insert(writer.createPositionAt(widgetElement, 0), selectionHandle);
+    writer.addClass(['ck-widget_with-selection-handle'], widgetElement);
 }