@ckeditor/ckeditor5-html-support 34.0.0 → 35.0.0

package/src/datafilter.js

@@ -7,6 +7,8 @@
  * @module html-support/datafilter
  */
 
+/* globals document */
+
 import DataSchema from './dataschema';
 
 import { Plugin } from 'ckeditor5/src/core';
@@ -53,6 +55,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 +111,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 +182,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 +226,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 );
@@ -288,6 +319,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.
 	 *
@@ -438,14 +554,14 @@ export default class DataFilter extends Plugin {
 	 * as an event namespace, e.g. `register:span`.
 	 *
 	 * 		dataFilter.on( 'register', ( evt, definition ) => {
-	 * 			editor.schema.register( definition.model, definition.modelSchema );
+	 * 			editor.model.schema.register( definition.model, definition.modelSchema );
 	 * 			editor.conversion.elementToElement( { model: definition.model, view: definition.view } );
 	 *
 	 * 			evt.stop();
 	 * 		} );
 	 *
 	 * 		dataFilter.on( 'register:span', ( evt, definition ) => {
-	 * 			editor.schema.extend( '$text', { allowAttributes: 'htmlSpan' } );
+	 * 			editor.model.schema.extend( '$text', { allowAttributes: 'htmlSpan' } );
 	 *
 	 * 			editor.conversion.for( 'upcast' ).elementToAttribute( { view: 'span', model: 'htmlSpan' } );
 	 * 			editor.conversion.for( 'downcast' ).attributeToElement( { view: 'span', model: 'htmlSpan' } );
@@ -462,7 +578,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
@@ -473,6 +589,15 @@ function consumeAttributes( viewElement, conversionApi, matcher ) {
 	const { attributes, styles, classes } = mergeMatchResults( matches );
 	const viewAttributes = {};
 
+	// Remove invalid DOM element attributes.
+	if ( attributes.size ) {
+		for ( const key of attributes ) {
+			if ( !isValidAttributeName( key ) ) {
+				attributes.delete( key );
+			}
+		}
+	}
+
 	if ( attributes.size ) {
 		viewAttributes.attributes = iterableToObject( attributes, key => viewElement.getAttribute( key ) );
 	}
@@ -496,7 +621,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 ) {
@@ -509,9 +634,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;
@@ -521,7 +645,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' ] ) {
@@ -531,7 +655,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 );
 			}
@@ -638,3 +763,14 @@ function splitRules( rules ) {
 
 	return splittedRules;
 }
+
+// Returns true if name is valid for a DOM attribute name.
+function isValidAttributeName( name ) {
+	try {
+		document.createAttribute( name );
+	} catch ( error ) {
+		return false;
+	}
+
+	return true;
+}

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
  */

package/src/generalhtmlsupport.js

@@ -20,6 +20,7 @@ import ScriptElementSupport from './integrations/script';
 import TableElementSupport from './integrations/table';
 import StyleElementSupport from './integrations/style';
 import DocumentListElementSupport from './integrations/documentlist';
+import CustomElementSupport from './integrations/customelement';
 
 /**
  * The General HTML Support feature.
@@ -51,7 +52,8 @@ export default class GeneralHtmlSupport extends Plugin {
 			ScriptElementSupport,
 			TableElementSupport,
 			StyleElementSupport,
-			DocumentListElementSupport
+			DocumentListElementSupport,
+			CustomElementSupport
 		];
 	}
 
@@ -86,7 +88,7 @@ export default class GeneralHtmlSupport extends Plugin {
 	}
 
 	/**
-	 * Updates GHS model attribute for a specified view element name, so it includes a given class name.
+	 * Updates GHS model attribute for a specified view element name, so it includes the given class name.
 	 *
 	 * @protected
 	 * @param {String} viewElementName A view element name.
@@ -109,7 +111,7 @@ export default class GeneralHtmlSupport extends Plugin {
 	}
 
 	/**
-	 * Updates GHS model attribute for a specified view element name, so it does not include a given class name.
+	 * Updates GHS model attribute for a specified view element name, so it does not include the given class name.
 	 *
 	 * @protected
 	 * @param {String} viewElementName A view element name.
@@ -132,7 +134,7 @@ export default class GeneralHtmlSupport extends Plugin {
 	}
 
 	/**
-	 * Updates GHS model attribute for a specified view element name, so it includes a given attribute.
+	 * Updates GHS model attribute for a specified view element name, so it includes the given attribute.
 	 *
 	 * @protected
 	 * @param {String} viewElementName A view element name.
@@ -155,7 +157,7 @@ export default class GeneralHtmlSupport extends Plugin {
 	}
 
 	/**
-	 * Updates GHS model attribute for a specified view element name, so it does not include a given attribute.
+	 * Updates GHS model attribute for a specified view element name, so it does not include the given attribute.
 	 *
 	 * @protected
 	 * @param {String} viewElementName A view element name.

package/src/integrations/codeblock.js

@@ -25,6 +25,13 @@ export default class CodeBlockElementSupport extends Plugin {
 		return [ DataFilter ];
 	}
 
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'CodeBlockElementSupport';
+	}
+
 	/**
 	 * @inheritDoc
 	 */
@@ -79,7 +86,7 @@ function viewToModelCodeBlockAttributeConverter( dataFilter ) {
 			preserveElementAttributes( viewCodeElement, 'htmlContentAttributes' );
 
 			function preserveElementAttributes( viewElement, attributeName ) {
-				const viewAttributes = dataFilter._consumeAllowedAttributes( viewElement, conversionApi );
+				const viewAttributes = dataFilter.processViewAttributes( viewElement, conversionApi );
 
 				if ( viewAttributes ) {
 					conversionApi.writer.setAttribute( attributeName, viewAttributes, data.modelRange );

package/src/integrations/customelement.js

@@ -0,0 +1,179 @@
+/**
+ * @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 html-support/integrations/customelement
+ */
+
+/* globals document */
+
+import { Plugin } from 'ckeditor5/src/core';
+import { UpcastWriter } from 'ckeditor5/src/engine';
+
+import DataSchema from '../dataschema';
+import DataFilter from '../datafilter';
+import { setViewAttributes } from '../conversionutils';
+
+/**
+ * Provides the General HTML Support for custom elements (not registered in the {@link module:html-support/dataschema~DataSchema}).
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class CustomElementSupport extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ DataFilter, DataSchema ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'CustomElementSupport';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		const dataFilter = this.editor.plugins.get( DataFilter );
+		const dataSchema = this.editor.plugins.get( DataSchema );
+
+		dataFilter.on( 'register:$customElement', ( evt, definition ) => {
+			evt.stop();
+
+			const editor = this.editor;
+			const schema = editor.model.schema;
+			const conversion = editor.conversion;
+			const unsafeElements = editor.editing.view.domConverter.unsafeElements;
+			const preLikeElements = editor.data.htmlProcessor.domConverter.preElements;
+
+			schema.register( definition.model, definition.modelSchema );
+			schema.extend( definition.model, {
+				allowAttributes: [ 'htmlElementName', 'htmlAttributes', 'htmlContent' ],
+				isContent: true
+			} );
+
+			// Being executed on the low priority, it will catch all elements that were not caught by other converters.
+			conversion.for( 'upcast' ).elementToElement( {
+				view: /.*/,
+				model: ( viewElement, conversionApi ) => {
+					// Do not try to convert $comment fake element.
+					if ( viewElement.name == '$comment' ) {
+						return;
+					}
+
+					if ( !isValidElementName( viewElement.name ) ) {
+						return;
+					}
+
+					// Allow for fallback only if this element is not defined in data schema to make sure
+					// that this will handle only custom elements not registered in the data schema.
+					if ( dataSchema.getDefinitionsForView( viewElement.name ).size ) {
+						return;
+					}
+
+					// Make sure that this element will not render in the editing view.
+					if ( !unsafeElements.includes( viewElement.name ) ) {
+						unsafeElements.push( viewElement.name );
+					}
+
+					// Make sure that whitespaces will not be trimmed or replaced by nbsps while stringify content.
+					if ( !preLikeElements.includes( viewElement.name ) ) {
+						preLikeElements.push( viewElement.name );
+					}
+
+					const modelElement = conversionApi.writer.createElement( definition.model, {
+						htmlElementName: viewElement.name
+					} );
+
+					const htmlAttributes = dataFilter.processViewAttributes( viewElement, conversionApi );
+
+					if ( htmlAttributes ) {
+						conversionApi.writer.setAttribute( 'htmlAttributes', htmlAttributes, modelElement );
+					}
+
+					// Store the whole element in the attribute so that DomConverter will be able to use the pre like element context.
+					const viewWriter = new UpcastWriter( viewElement.document );
+					const documentFragment = viewWriter.createDocumentFragment( viewElement );
+					const htmlContent = editor.data.processor.toData( documentFragment );
+
+					conversionApi.writer.setAttribute( 'htmlContent', htmlContent, modelElement );
+
+					// Consume the content of the element.
+					for ( const { item } of editor.editing.view.createRangeIn( viewElement ) ) {
+						conversionApi.consumable.consume( item, { name: true } );
+					}
+
+					return modelElement;
+				},
+				converterPriority: 'low'
+			} );
+
+			// Because this element is unsafe (DomConverter#unsafeElements), it will render as a transparent <span> but it must
+			// be rendered anyway for the mapping between the model and the view to exist.
+			conversion.for( 'editingDowncast' ).elementToElement( {
+				model: {
+					name: definition.model,
+					attributes: [ 'htmlElementName', 'htmlAttributes', 'htmlContent' ]
+				},
+				view: ( modelElement, { writer } ) => {
+					const viewName = modelElement.getAttribute( 'htmlElementName' );
+					const viewElement = writer.createRawElement( viewName );
+
+					if ( modelElement.hasAttribute( 'htmlAttributes' ) ) {
+						setViewAttributes( writer, modelElement.getAttribute( 'htmlAttributes' ), viewElement );
+					}
+
+					return viewElement;
+				}
+			} );
+
+			conversion.for( 'dataDowncast' ).elementToElement( {
+				model: {
+					name: definition.model,
+					attributes: [ 'htmlElementName', 'htmlAttributes', 'htmlContent' ]
+				},
+				view: ( modelElement, { writer } ) => {
+					const viewName = modelElement.getAttribute( 'htmlElementName' );
+					const htmlContent = modelElement.getAttribute( 'htmlContent' );
+
+					const viewElement = writer.createRawElement( viewName, null, ( domElement, domConverter ) => {
+						domConverter.setContentOf( domElement, htmlContent );
+
+						// Unwrap the custom element content (it was stored in the attribute as the whole custom element).
+						// See the upcast conversion for the "htmlContent" attribute to learn more.
+						const customElement = domElement.firstChild;
+
+						customElement.remove();
+
+						while ( customElement.firstChild ) {
+							domElement.appendChild( customElement.firstChild );
+						}
+					} );
+
+					if ( modelElement.hasAttribute( 'htmlAttributes' ) ) {
+						setViewAttributes( writer, modelElement.getAttribute( 'htmlAttributes' ), viewElement );
+					}
+
+					return viewElement;
+				}
+			} );
+		} );
+	}
+}
+
+// Returns true if name is valid for a DOM element name.
+function isValidElementName( name ) {
+	try {
+		document.createElement( name );
+	} catch ( error ) {
+		return false;
+	}
+
+	return true;
+}

package/src/integrations/documentlist.js

@@ -14,7 +14,7 @@ import { setViewAttributes } from '../conversionutils.js';
 import DataFilter from '../datafilter';
 
 /**
- * Provides the General HTML Support integration with {@link module:list/documentlist~DocumentList Document List} feature.
+ * Provides the General HTML Support integration with the {@link module:list/documentlist~DocumentList Document List} feature.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -26,6 +26,13 @@ export default class DocumentListElementSupport extends Plugin {
 		return [ DataFilter ];
 	}
 
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'DocumentListElementSupport';
+	}
+
 	/**
 	 * @inheritDoc
 	 */
@@ -85,7 +92,7 @@ export default class DocumentListElementSupport extends Plugin {
 		} );
 
 		// Make sure that all items in a single list (items at the same level & listType) have the same properties.
-		// Note: This is almost exact copy from DocumentListPropertiesEditing.
+		// Note: This is almost an exact copy from DocumentListPropertiesEditing.
 		documentListEditing.on( 'postFixer', ( evt, { listNodes, writer } ) => {
 			const previousNodesByIndent = []; // Last seen nodes of lower indented lists.
 
@@ -180,7 +187,7 @@ function viewToModelListAttributeConverter( attributeName, dataFilter ) {
 			Object.assign( data, conversionApi.convertChildren( data.viewItem, data.modelCursor ) );
 		}
 
-		const viewAttributes = dataFilter._consumeAllowedAttributes( viewElement, conversionApi );
+		const viewAttributes = dataFilter.processViewAttributes( viewElement, conversionApi );
 
 		for ( const item of data.modelRange.getItems( { shallow: true } ) ) {
 			// Apply only to list item blocks.

package/src/integrations/dualcontent.js

@@ -43,6 +43,13 @@ export default class DualContentModelElementSupport extends Plugin {
 		return [ DataFilter ];
 	}
 
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'DualContentModelElementSupport';
+	}
+
 	/**
 	 * @inheritDoc
 	 */
@@ -111,10 +118,19 @@ export default class DualContentModelElementSupport extends Plugin {
 	 * @returns {Boolean}
 	 */
 	_hasBlockContent( viewElement ) {
-		const blockElements = this.editor.editing.view.domConverter.blockElements;
+		const view = this.editor.editing.view;
+		const blockElements = view.domConverter.blockElements;
+
+		// Traversing the viewElement subtree looking for block elements.
+		// Especially for the cases like <div><a href="#"><p>foo</p></a></div>.
+		// https://github.com/ckeditor/ckeditor5/issues/11513
+		for ( const viewItem of view.createRangeIn( viewElement ).getItems() ) {
+			if ( viewItem.is( 'element' ) && blockElements.includes( viewItem.name ) ) {
+				return true;
+			}
+		}
 
-		return Array.from( viewElement.getChildren() )
-			.some( node => blockElements.includes( node.name ) );
+		return false;
 	}
 
 	/**

package/src/integrations/heading.js

@@ -24,6 +24,13 @@ export default class HeadingElementSupport extends Plugin {
 		return [ DataSchema ];
 	}
 
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'HeadingElementSupport';
+	}
+
 	/**
 	 * @inheritDoc
 	 */