Merge branch 'release'

package.json

@@ -93,6 +93,7 @@
     "@webspellchecker/wproofreader-ckeditor5": "^1.0.5",
     "@wiris/mathtype-ckeditor5": "^7.24.0",
     "babel-standalone": "^6.26.0",
+    "cli-table": "^0.3.1",
     "coveralls": "^3.1.0",
     "css-loader": "^3.5.3",
     "eslint": "^7.1.0",

packages/ckeditor5-engine/src/conversion/downcastdispatcher.js

@@ -314,6 +314,9 @@ export default class DowncastDispatcher {
 			}
 		}
 
+		// After reconversion is done we can unbind the old view.
+		mapper.unbindViewElement( currentView );
+
 		this._clearConversionApi();
 	}
 

packages/ckeditor5-engine/tests/conversion/downcasthelpers.js

@@ -38,6 +38,8 @@ import { expectToThrowCKEditorError } from '@ckeditor/ckeditor5-utils/tests/_uti
 import { StylesProcessor } from '../../src/view/stylesmap';
 import DowncastWriter from '../../src/view/downcastwriter';
 
+import { toWidget } from '@ckeditor/ckeditor5-widget/src/utils';
+
 describe( 'DowncastHelpers', () => {
 	let model, modelRoot, viewRoot, downcastHelpers, controller, modelRootStart;
 
@@ -192,6 +194,53 @@ describe( 'DowncastHelpers', () => {
 					expectResult( '<div class="is-classy"></div>' );
 				} );
 
+				it( 'should properly re-bind mapper mappings and retain markers', () => {
+					downcastHelpers.elementToElement( {
+						model: 'simpleBlock',
+						view: ( modelElement, { writer } ) => {
+							const viewElement = writer.createContainerElement( 'div', getViewAttributes( modelElement ) );
+
+							return toWidget( viewElement, writer );
+						},
+						triggerBy: {
+							attributes: [ 'toStyle', 'toClass' ]
+						},
+						converterPriority: 'high'
+					} );
+
+					const mapper = controller.mapper;
+
+					downcastHelpers.markerToHighlight( {
+						model: 'myMarker',
+						view: { classes: 'foo' }
+					} );
+
+					setModelData( model, '<simpleBlock></simpleBlock>' );
+
+					const modelElement = modelRoot.getChild( 0 );
+					const [ viewBefore ] = getNodes();
+
+					model.change( writer => {
+						writer.addMarker( 'myMarker', { range: writer.createRangeOn( modelElement ), usingOperation: false } );
+					} );
+
+					expect( mapper.toViewElement( modelElement ) ).to.equal( viewBefore );
+					expect( mapper.toModelElement( viewBefore ) ).to.equal( modelElement );
+					expect( mapper.markerNameToElements( 'myMarker' ).has( viewBefore ) ).to.be.true;
+
+					model.change( writer => {
+						writer.setAttribute( 'toStyle', 'display:block', modelElement );
+					} );
+
+					const [ viewAfter ] = getNodes();
+
+					expect( mapper.toViewElement( modelElement ) ).to.equal( viewAfter );
+					expect( mapper.toModelElement( viewBefore ) ).to.be.undefined;
+					expect( mapper.toModelElement( viewAfter ) ).to.equal( modelElement );
+					expect( mapper.markerNameToElements( 'myMarker' ).has( viewAfter ) ).to.be.true;
+					expect( mapper.markerNameToElements( 'myMarker' ).has( viewBefore ) ).to.be.false;
+				} );
+
 				it( 'should do nothing if non-triggerBy attribute has changed', () => {
 					setModelData( model, '<simpleBlock></simpleBlock>' );
 

packages/ckeditor5-html-embed/docs/features/html-embed.md

@@ -5,11 +5,30 @@ menu-title: HTML embed
 
 # HTML embed
 
-The {@link module:html-embed/htmlembed~HtmlEmbed} plugin provides the possibility to insert a HTML codeinto the rich-text editor.
+The {@link module:html-embed/htmlembed~HtmlEmbed} plugin allows embedding an arbitrary HTML snippet in the editor. The feature is targeted at more advanced users who want to directly interact with HTML fragments.
+
+This feature can be used to embed any HTML code and bypass CKEditor 5's filtering mechanisms. Thanks to that it is possible to enrich content produced by CKEditor 5 with fragments of HTML that are not supported by any other CKEditor 5 feature.
+
+Example of content that can be embedded thanks to the HTML embed feature:
+
+* analytics code (that usually require embedding `<script>` elements),
+* social page widgets (that also require embedding `<script>` elements),
+* content embeddable by `<iframe>`s,
+* HTML media elements such as audio and video,
+* HTML snippets produced by external tools (e.g reports),
+* interactive content that requires a combination of rich HTML and scripts.
+
+It is recommended to use the {@link features/media-embed media embed} feature for embeddable media that are supported by this feature. The HTML embed feature can be used to handle remaining content.
+
+<info-box warning>
+	Read the [Security](#security) section before installing this plugin.
+
+	Incorrect configuration may **lead to security issues**.
+</info-box>
 
 ## Demo
 
-Use the editor below to see the {@link module:html-embed/htmlembed~HtmlEmbed} plugin in action.
+Use the editor below to see the plugin in action.
 
 {@snippet features/html-embed}
 
@@ -39,10 +58,69 @@ ClassicEditor
 	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
 </info-box>
 
+## Configuration
+
+### Content previews
+
+The feature is by default configured to not show previews of the HTML snippets. The previews can be enabled by setting the {@link module:html-embed/htmlembed~HtmlEmbedConfig#showPreviews `config.htmlEmbed.showPreviews`} option to `true`.
+
+However, by showing previews of embedded HTML snippets you expose the users of your system to the risk of executing malicious JavaScript code inside the editor. Therefore, it is highly recommended to plug an HTML sanitizier that will strip the malicious code from create snippets before rendering their previous. The sanitizer can be plugged by defining the {@link module:html-embed/htmlembed~HtmlEmbedConfig#sanitizeHtml `config.htmlEmbed.sanitizeHtml`} option.
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ HtmlEmbed, ... ],
+		toolbar: [ 'htmlEmbed', ... ],
+		htmlEmbed: {
+			showPreviews: true,
+			sanitizeHtml: ( inputHtml ) => {
+				// Strip unsafe elements and attributes, e.g.:
+				// the `<script>` elements and `on*` attributes.
+				const outputHtml = sanitize( inputHtml );
+
+				return {
+					html: outputHtml,
+					// true or false depending on whether the sanitizer stripped anything.
+					hasChanged: true
+				};
+			}
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+Currently, the [feature does not execute `<script>` tags](https://github.com/ckeditor/ckeditor5/issues/8326) so content that requires executing JavaScript in order to generate a preview will not show in the editor. However, other JavaScript code – e.g. used in `on*` observers and `scr="javascript:..."` attributes will be executed and therefore a sanitizer still needs to be enabled.
+
+Read more about the security aspect in the next section.
+
 ### Security
 
-TODO
-Note: it's mentioned in the config.htmlEmbed.* options so if we'll decide to rename this section we'll need to change it there.
+If the HTML embed feature is configured to [show content previews](#content-previews), the HTML that the user inserts into the HTML embed widget is then rendered back to the user. If the HTML was rendered as-is, any JavaScript code included in these HTML snippets would be executed by the browser in context of your website.
+
+This, in turn, is a plain security risk. The HTML provided by the user might be mistakenly copied from a malicious website or end up in the users clipboard (as it would usually be copied and pasted) by any other mean.
+
+In some cases, advanced users can be instructed to never paste HTML code from untrusted sources. However, in most cases, it is highly recommended to properly secure the system by configuring the HTML embed feature to use an HTML sanitizer and, optionally, setting strict CSP rules.
+
+<info-box>
+	The HTML embed feature [does not currently execute code in `<script>` tags](https://github.com/ckeditor/ckeditor5/issues/8326). However, it will execute code in `on*` and `scr="javascript:..."` attributes.
+
+	The tricky part is that some HTML snippets require JavaScript to be executed to render any meaningful previews (e.g. Facebook embeds). Some, in turn, does not make sense to be executed (analytics code).
+
+	Therefore, when configuring the sanitizer and CSP rules, you can take those situations into consideration and for instance allow `<script>` tags pointing only to certain domains (e.g. a trusted external page that requires JavaScript).
+</info-box>
+
+#### Sanitizer
+
+The {@link module:html-embed/htmlembed~HtmlEmbedConfig#sanitizeHtml `config.htmlEmbed.sanitizeHtml`} option allow plugging an external sanitizer.
+
+Some popular JavaScript libraries that can be used include [sanitize-html](https://www.npmjs.com/package/sanitize-html) and [DOMPurify](https://www.npmjs.com/package/dompurify).
+
+The default settings of these libraries usually strip all potentially malicious content including `<iframe>`, `<video>`, etc. elements and JavaScript code coming from trusted sources so you may need to adjust their settings to match your needs.
+
+#### CSP
+
+In addition to using a sanitizer you can use the built browser mechanism called [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). By using CSP you can let the browser know what sources and means to execute JavaScript code and include other resources such as stylesheets, images and fonts are allowed.
 
 ## Common API
 
@@ -51,10 +129,11 @@ The {@link module:html-embed/htmlembed~HtmlEmbed} plugin registers:
 * the `'updateHtmlEmbed'` command implemented by {@link module:html-embed/updatehtmlembedcommand~UpdateHtmlEmbedCommand}.
 * the `'insertHtmlEmbed'` command implemented by {@link module:html-embed/inserthtmlembedcommand~InsertHtmlEmbedCommand}.
 
-The command can be executed using the {@link module:core/editor/editor~Editor#execute `editor.execute()`} method:
+Both commands can be executed using the {@link module:core/editor/editor~Editor#execute `editor.execute()`} method:
 
 ```js
-editor.execute( 'htmlEmbed', { html: 'HTML to insert.' } );
+editor.execute( 'insertHtmlEmbed' );
+editor.execute( 'updateHtmlEmbed', '<p>HTML string</p>' );
 ```
 
 <info-box>

packages/ckeditor5-html-embed/src/htmlembed.js

@@ -88,8 +88,9 @@ export default class HtmlEmbed extends Plugin {
  *
  * 						return {
  * 							html: outputHtml,
+ *							// true or false depending on whether the sanitizer stripped anything.
  * 							hasChanged: ...
- * 						}
+ * 						};
  * 					},
  * 				}
  * 			} )

packages/ckeditor5-media-embed/src/mediaembedui.js

@@ -41,7 +41,6 @@ export default class MediaEmbedUI extends Plugin {
 		const command = editor.commands.get( 'mediaEmbed' );
 		const registry = editor.plugins.get( MediaEmbedEditing ).registry;
 
-		// Setup `imageUpload` button.
 		editor.ui.componentFactory.add( 'mediaEmbed', locale => {
 			const dropdown = createDropdown( locale );