@ckeditor/ckeditor5-html-support 32.0.0 → 34.1.0

package/src/conversionutils.js

@@ -10,12 +10,30 @@
 import { cloneDeep } from 'lodash-es';
 
 /**
-* Helper function for downcast converter. Sets attributes on the given view element.
+* Helper function for the downcast converter. Updates attributes on the given view element.
 *
-* @param {module:engine/view/downcastwriter~DowncastWriter} writer
-* @param {Object} viewAttributes
-* @param {module:engine/view/element~Element} viewElement
+* @param {module:engine/view/downcastwriter~DowncastWriter} writer The view writer.
+* @param {Object} oldViewAttributes The previous GHS attribute value.
+* @param {Object} newViewAttributes The current GHS attribute value.
+* @param {module:engine/view/element~Element} viewElement The view element to update.
 */
+export function updateViewAttributes( writer, oldViewAttributes, newViewAttributes, viewElement ) {
+	if ( oldViewAttributes ) {
+		removeViewAttributes( writer, oldViewAttributes, viewElement );
+	}
+
+	if ( newViewAttributes ) {
+		setViewAttributes( writer, newViewAttributes, viewElement );
+	}
+}
+
+/**
+ * Helper function for the downcast converter. Sets attributes on the given view element.
+ *
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer The view writer.
+ * @param {Object} viewAttributes The GHS attribute value.
+ * @param {module:engine/view/element~Element} viewElement The view element to update.
+ */
 export function setViewAttributes( writer, viewAttributes, viewElement ) {
 	if ( viewAttributes.attributes ) {
 		for ( const [ key, value ] of Object.entries( viewAttributes.attributes ) ) {
@@ -32,6 +50,31 @@ export function setViewAttributes( writer, viewAttributes, viewElement ) {
 	}
 }
 
+/**
+ * Helper function for the downcast converter. Removes attributes on the given view element.
+ *
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer The view writer.
+ * @param {Object} viewAttributes The GHS attribute value.
+ * @param {module:engine/view/element~Element} viewElement The view element to update.
+ */
+export function removeViewAttributes( writer, viewAttributes, viewElement ) {
+	if ( viewAttributes.attributes ) {
+		for ( const [ key ] of Object.entries( viewAttributes.attributes ) ) {
+			writer.removeAttribute( key, viewElement );
+		}
+	}
+
+	if ( viewAttributes.styles ) {
+		for ( const style of Object.keys( viewAttributes.styles ) ) {
+			writer.removeStyle( style, viewElement );
+		}
+	}
+
+	if ( viewAttributes.classes ) {
+		writer.removeClass( viewAttributes.classes, viewElement );
+	}
+}
+
 /**
 * Merges view element attribute objects.
 *
@@ -45,7 +88,7 @@ export function mergeViewElementAttributes( target, source ) {
 	for ( const key in source ) {
 		// Merge classes.
 		if ( Array.isArray( source[ key ] ) ) {
-			result[ key ] = Array.from( new Set( [ ...target[ key ], ...source[ key ] ] ) );
+			result[ key ] = Array.from( new Set( [ ...( target[ key ] || [] ), ...source[ key ] ] ) );
 		}
 
 		// Merge attributes or styles.

package/src/converters.js

@@ -8,7 +8,11 @@
  */
 
 import { toWidget } from 'ckeditor5/src/widget';
-import { setViewAttributes, mergeViewElementAttributes } from './conversionutils';
+import {
+	setViewAttributes,
+	mergeViewElementAttributes,
+	updateViewAttributes
+} from './conversionutils';
 
 /**
  * View-to-model conversion helper for object elements.
@@ -28,7 +32,7 @@ export function viewToModelObjectConverter( { model: modelName } ) {
 }
 
 /**
- * Conversion helper converting object element to HTML object widget.
+ * Conversion helper converting an object element to an HTML object widget.
  *
  * @param {module:core/editor/editor~Editor} editor
  * @param {module:html-support/dataschema~DataSchemaInlineElementDefinition} definition
@@ -37,27 +41,27 @@ export function viewToModelObjectConverter( { model: modelName } ) {
 export function toObjectWidgetConverter( editor, { view: viewName, isInline } ) {
 	const t = editor.t;
 
-	return ( modelElement, { writer, consumable } ) => {
+	return ( modelElement, { writer } ) => {
 		const widgetLabel = t( 'HTML object' );
 
-		// Widget cannot be a raw element because the widget system would not be able
-		// to add its UI to it. Thus, we need separate view container.
-		const viewContainer = writer.createContainerElement( isInline ? 'span' : 'div', {
-			class: 'html-object-embed',
-			'data-html-object-embed-label': widgetLabel
-		}, {
-			isAllowedInsideAttributeElement: isInline
-		} );
-
 		const viewElement = createObjectView( viewName, modelElement, writer );
+		const viewAttributes = modelElement.getAttribute( 'htmlAttributes' );
+
 		writer.addClass( 'html-object-embed__content', viewElement );
 
-		const viewAttributes = modelElement.getAttribute( 'htmlAttributes' );
-		if ( viewAttributes && consumable.consume( modelElement, `attribute:htmlAttributes:${ modelElement.name }` ) ) {
+		if ( viewAttributes ) {
 			setViewAttributes( writer, viewAttributes, viewElement );
 		}
 
-		writer.insert( writer.createPositionAt( viewContainer, 0 ), viewElement );
+		// Widget cannot be a raw element because the widget system would not be able
+		// to add its UI to it. Thus, we need separate view container.
+		const viewContainer = writer.createContainerElement( isInline ? 'span' : 'div',
+			{
+				class: 'html-object-embed',
+				'data-html-object-embed-label': widgetLabel
+			},
+			viewElement
+		);
 
 		return toWidget( viewContainer, writer, { widgetLabel } );
 	};
@@ -87,7 +91,19 @@ export function createObjectView( viewName, modelElement, writer ) {
 export function viewToAttributeInlineConverter( { view: viewName, model: attributeKey }, dataFilter ) {
 	return dispatcher => {
 		dispatcher.on( `element:${ viewName }`, ( evt, data, conversionApi ) => {
-			const viewAttributes = dataFilter._consumeAllowedAttributes( data.viewItem, conversionApi );
+			let viewAttributes = dataFilter.processViewAttributes( data.viewItem, conversionApi );
+
+			// Do not apply the attribute if the element itself is already consumed and there are no view attributes to store.
+			if ( !viewAttributes && !conversionApi.consumable.test( data.viewItem, { name: true } ) ) {
+				return;
+			}
+
+			// Otherwise, we might need to convert it to an empty object just to preserve element itself,
+			// for example `<cite>` => <$text htmlCite="{}">.
+			viewAttributes = viewAttributes || {};
+
+			// Consume the element itself if it wasn't consumed by any other converter.
+			conversionApi.consumable.consume( data.viewItem, { name: true } );
 
 			// Since we are converting to attribute we need a range on which we will set the attribute.
 			// If the range is not created yet, we will create it.
@@ -101,7 +117,7 @@ export function viewToAttributeInlineConverter( { view: viewName, model: attribu
 					// Node's children are converted recursively, so node can already include model attribute.
 					// We want to extend it, not replace.
 					const nodeAttributes = node.getAttribute( attributeKey );
-					const attributesToAdd = mergeViewElementAttributes( viewAttributes || {}, nodeAttributes || {} );
+					const attributesToAdd = mergeViewElementAttributes( viewAttributes, nodeAttributes || {} );
 
 					conversionApi.writer.setAttribute( attributeKey, attributesToAdd, node );
 				}
@@ -143,11 +159,15 @@ export function attributeToViewInlineConverter( { priority, view: viewName } ) {
 export function viewToModelBlockAttributeConverter( { view: viewName }, dataFilter ) {
 	return dispatcher => {
 		dispatcher.on( `element:${ viewName }`, ( evt, data, conversionApi ) => {
-			if ( !data.modelRange ) {
+			// Converting an attribute of an element that has not been converted to anything does not make sense
+			// because there will be nowhere to set that attribute on. At this stage, the element should've already
+			// been converted. A collapsed range can show up in to-do lists (<input>) or complex widgets (e.g. table).
+			// (https://github.com/ckeditor/ckeditor5/issues/11000).
+			if ( !data.modelRange || data.modelRange.isCollapsed ) {
 				return;
 			}
 
-			const viewAttributes = dataFilter._consumeAllowedAttributes( data.viewItem, conversionApi );
+			const viewAttributes = dataFilter.processViewAttributes( data.viewItem, conversionApi );
 
 			if ( viewAttributes ) {
 				conversionApi.writer.setAttribute( 'htmlAttributes', viewAttributes, data.modelRange );
@@ -166,16 +186,15 @@ export function viewToModelBlockAttributeConverter( { view: viewName }, dataFilt
 export function modelToViewBlockAttributeConverter( { model: modelName } ) {
 	return dispatcher => {
 		dispatcher.on( `attribute:htmlAttributes:${ modelName }`, ( evt, data, conversionApi ) => {
-			const viewAttributes = data.attributeNewValue;
-
 			if ( !conversionApi.consumable.consume( data.item, evt.name ) ) {
 				return;
 			}
 
+			const { attributeOldValue, attributeNewValue } = data;
 			const viewWriter = conversionApi.writer;
 			const viewElement = conversionApi.mapper.toViewElement( data.item );
 
-			setViewAttributes( viewWriter, viewAttributes, viewElement );
+			updateViewAttributes( viewWriter, attributeOldValue, attributeNewValue, viewElement );
 		} );
 	};
 }

package/src/datafilter.js

@@ -53,6 +53,9 @@ import '../theme/datafilter.css';
  *			}
  *		} );
  *
+ * To apply the information about allowed and disallowed attributes in custom integration plugin,
+ * use the {@link module:html-support/datafilter~DataFilter#processViewAttributes `processViewAttributes()`} method.
+ *
  * @extends module:core/plugin~Plugin
  */
 export default class DataFilter extends Plugin {
@@ -106,8 +109,18 @@ export default class DataFilter extends Plugin {
 		*/
 		this._dataInitialized = false;
 
+		/**
+		 * Cached map of coupled attributes. Keys are the feature attributes names
+		 * and values are arrays with coupled GHS attributes names.
+		 *
+		 * @private
+		 * @member {Map.<String,Array>}
+		 */
+		this._coupledAttributes = null;
+
 		this._registerElementsAfterInit();
 		this._registerElementHandlers();
+		this._registerModelPostFixer();
 	}
 
 	/**
@@ -167,6 +180,9 @@ export default class DataFilter extends Plugin {
 			if ( this._dataInitialized ) {
 				this._fireRegisterEvent( definition );
 			}
+
+			// Reset cached map to recalculate it on the next usage.
+			this._coupledAttributes = null;
 		}
 	}
 
@@ -208,17 +224,30 @@ export default class DataFilter extends Plugin {
 	}
 
 	/**
-	 * Matches and consumes allowed and disallowed view attributes and returns the allowed ones.
+	 * Processes all allowed and disallowed attributes on the view element by consuming them and returning the allowed ones.
 	 *
-	 * @protected
+	 * This method applies the configuration set up by {@link #allowAttributes `allowAttributes()`}
+	 * and {@link #disallowAttributes `disallowAttributes()`} over the given view element by consuming relevant attributes.
+	 * It returns the allowed attributes that were found on the given view element for further processing by integration code.
+	 *
+	 *		dispatcher.on( 'element:myElement', ( evt, data, conversionApi ) => {
+	 *			// Get rid of disallowed and extract all allowed attributes from a viewElement.
+	 *			const viewAttributes = dataFilter.processViewAttributes( data.viewItem, conversionApi );
+	 *			// Do something with them, i.e. store inside a model as a dictionary.
+	 *			if ( viewAttributes ) {
+	 *				conversionApi.writer.setAttribute( 'htmlAttributesOfMyElement', viewAttributes, data.modelRange );
+	 *			}
+	 *		} );
+	 *
+	 * @see module:engine/conversion/viewconsumable~ViewConsumable#consume
 	 * @param {module:engine/view/element~Element} viewElement
-	 * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi
+	 * @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi
 	 * @returns {Object} [result]
 	 * @returns {Object} result.attributes Set with matched attribute names.
 	 * @returns {Object} result.styles Set with matched style names.
 	 * @returns {Array.<String>} result.classes Set with matched class names.
 	 */
-	_consumeAllowedAttributes( viewElement, conversionApi ) {
+	processViewAttributes( viewElement, conversionApi ) {
 		// Make sure that the disabled attributes are handled before the allowed attributes are called.
 		// For example, for block images the <figure> converter triggers conversion for <img> first and then for other elements, i.e. <a>.
 		consumeAttributes( viewElement, conversionApi, this._disallowedAttributes );
@@ -240,10 +269,14 @@ export default class DataFilter extends Plugin {
 				this._fireRegisterEvent( definition );
 			}
 		}, {
-			// With high priority listener we are able to register elements right before
-			// running data conversion. Make also sure that priority is higher than the one
-			// used by `RealTimeCollaborationClient`, as RTC is stopping event propagation.
-			priority: priorities.get( 'high' ) + 1
+			// With highest priority listener we are able to register elements right before
+			// running data conversion. Also:
+			// * Make sure that priority is higher than the one used by `RealTimeCollaborationClient`,
+			// as RTC is stopping event propagation.
+			// * Make sure no other features hook into this event before GHS because otherwise the
+			// downcast conversion (for these features) could run before GHS registered its converters
+			// (https://github.com/ckeditor/ckeditor5/issues/11356).
+			priority: priorities.get( 'highest' ) + 1
 		} );
 	}
 
@@ -284,6 +317,91 @@ export default class DataFilter extends Plugin {
 		}, { priority: 'lowest' } );
 	}
 
+	/**
+	 * Registers a model post-fixer that is removing coupled GHS attributes of inline elements. Those attributes
+	 * are removed if a coupled feature attribute is removed.
+	 *
+	 * For example, consider following HTML:
+	 *
+	 *		<a href="foo.html" id="myId">bar</a>
+	 *
+	 * Which would be upcasted to following text node in the model:
+	 *
+	 *		<$text linkHref="foo.html" htmlA="{ attributes: { id: 'myId' } }">bar</$text>
+	 *
+	 * When the user removes the link from that text (using UI), only `linkHref` attribute would be removed:
+	 *
+	 *		<$text htmlA="{ attributes: { id: 'myId' } }">bar</$text>
+	 *
+	 * The `htmlA` attribute would stay in the model and would cause GHS to generate an `<a>` element.
+	 * This is incorrect from UX point of view, as the user wanted to remove the whole link (not only `href`).
+	 *
+	 * @private
+	 */
+	_registerModelPostFixer() {
+		const model = this.editor.model;
+
+		model.document.registerPostFixer( writer => {
+			const changes = model.document.differ.getChanges();
+			let changed = false;
+
+			const coupledAttributes = this._getCoupledAttributesMap();
+
+			for ( const change of changes ) {
+				// Handle only attribute removals.
+				if ( change.type != 'attribute' || change.attributeNewValue !== null ) {
+					continue;
+				}
+
+				// Find a list of coupled GHS attributes.
+				const attributeKeys = coupledAttributes.get( change.attributeKey );
+
+				if ( !attributeKeys ) {
+					continue;
+				}
+
+				// Remove the coupled GHS attributes on the same range as the feature attribute was removed.
+				for ( const { item } of change.range.getWalker( { shallow: true } ) ) {
+					for ( const attributeKey of attributeKeys ) {
+						if ( item.hasAttribute( attributeKey ) ) {
+							writer.removeAttribute( attributeKey, item );
+							changed = true;
+						}
+					}
+				}
+			}
+
+			return changed;
+		} );
+	}
+
+	/**
+	 * Collects the map of coupled attributes. The returned map is keyed by the feature attribute name
+	 * and coupled GHS attribute names are stored in the value array .
+	 *
+	 * @private
+	 * @returns {Map.<String,Array>}
+	 */
+	_getCoupledAttributesMap() {
+		if ( this._coupledAttributes ) {
+			return this._coupledAttributes;
+		}
+
+		this._coupledAttributes = new Map();
+
+		for ( const definition of this._allowedElements ) {
+			if ( definition.coupledAttribute && definition.model ) {
+				const attributeNames = this._coupledAttributes.get( definition.coupledAttribute );
+
+				if ( attributeNames ) {
+					attributeNames.push( definition.model );
+				} else {
+					this._coupledAttributes.set( definition.coupledAttribute, [ definition.model ] );
+				}
+			}
+		}
+	}
+
 	/**
 	 * Fires `register` event for the given element definition.
 	 *
@@ -308,6 +426,7 @@ export default class DataFilter extends Plugin {
 
 		schema.register( modelName, definition.modelSchema );
 
+		/* istanbul ignore next: paranoid check */
 		if ( !viewName ) {
 			return;
 		}
@@ -331,8 +450,13 @@ export default class DataFilter extends Plugin {
 		} );
 		conversion.for( 'upcast' ).add( viewToModelBlockAttributeConverter( definition, this ) );
 
-		conversion.for( 'editingDowncast' ).elementToElement( {
-			model: modelName,
+		conversion.for( 'editingDowncast' ).elementToStructure( {
+			model: {
+				name: modelName,
+				attributes: [
+					'htmlAttributes'
+				]
+			},
 			view: toObjectWidgetConverter( editor, definition )
 		} );
 
@@ -452,7 +576,7 @@ export default class DataFilter extends Plugin {
 //
 // @private
 // @param {module:engine/view/element~Element} viewElement
-// @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi
+// @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi
 // @param {module:engine/view/matcher~Matcher Matcher} matcher
 // @returns {Object} [result]
 // @returns {Object} result.attributes
@@ -486,7 +610,7 @@ function consumeAttributes( viewElement, conversionApi, matcher ) {
 //
 // @private
 // @param {module:engine/view/element~Element} viewElement
-// @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi
+// @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi
 // @param {module:engine/view/matcher~Matcher Matcher} matcher
 // @returns {Array.<Object>} Array with match information about found attributes.
 function consumeAttributeMatches( viewElement, { consumable }, matcher ) {
@@ -499,9 +623,8 @@ function consumeAttributeMatches( viewElement, { consumable }, matcher ) {
 		// We only want to consume attributes, so element can be still processed by other converters.
 		delete match.match.name;
 
-		if ( consumable.consume( viewElement, match.match ) ) {
-			consumedMatches.push( match );
-		}
+		consumable.consume( viewElement, match.match );
+		consumedMatches.push( match );
 	}
 
 	return consumedMatches;
@@ -511,7 +634,7 @@ function consumeAttributeMatches( viewElement, { consumable }, matcher ) {
 //
 // @private
 // @param {module:engine/view/element~Element} viewElement
-// @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable
+// @param {module:engine/conversion/viewconsumable~ViewConsumable} consumable
 // @param {Object} match
 function removeConsumedAttributes( consumable, viewElement, match ) {
 	for ( const key of [ 'attributes', 'classes', 'styles' ] ) {
@@ -521,7 +644,8 @@ function removeConsumedAttributes( consumable, viewElement, match ) {
 			continue;
 		}
 
-		for ( const value of attributes ) {
+		// Iterating over a copy of an array so removing items doesn't influence iteration.
+		for ( const value of Array.from( attributes ) ) {
 			if ( !consumable.test( viewElement, ( { [ key ]: [ value ] } ) ) ) {
 				removeItemFromArray( attributes, value );
 			}

package/src/dataschema.js

@@ -251,5 +251,8 @@ function testViewName( pattern, viewName ) {
  * @property {Number} [priority] Element priority. Decides in what order elements are wrapped by
  * {@link module:engine/view/downcastwriter~DowncastWriter}.
  * Set by {@link module:html-support/dataschema~DataSchema#registerInlineElement} method.
+ * @property {String} [coupledAttribute] The name of the model attribute that generates the same view element. GHS inline attribute
+ * will be removed from the model tree as soon as the coupled attribute is removed. See
+ * {@link module:html-support/datafilter~DataFilter#_registerModelPostFixer GHS post-fixer} for more details.
  * @extends module:html-support/dataschema~DataSchemaDefinition
  */