Merge branch 'master' into i/6110

docs/_snippets/features/build-table-source.js

@@ -7,13 +7,40 @@
 
 import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
 
-import Table from '@ckeditor/ckeditor5-table/src/table';
-import TableToolbar from '@ckeditor/ckeditor5-table/src/tabletoolbar';
+import FontFamily from '@ckeditor/ckeditor5-font/src/fontfamily';
+import FontSize from '@ckeditor/ckeditor5-font/src/fontsize';
+import Alignment from '@ckeditor/ckeditor5-alignment/src/alignment';
+import IndentBlock from '@ckeditor/ckeditor5-indent/src/indentblock';
 import TableProperties from '@ckeditor/ckeditor5-table/src/tableproperties';
 import TableCellProperties from '@ckeditor/ckeditor5-table/src/tablecellproperties';
 
-ClassicEditor.builtinPlugins.push( Table );
-ClassicEditor.builtinPlugins.push( TableToolbar );
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor.builtinPlugins.push( FontFamily, FontSize, Alignment, IndentBlock );
+ClassicEditor.defaultConfig = {
+	cloudServices: CS_CONFIG,
+	toolbar: {
+		items: [
+			'insertTable',
+			'|',
+			'fontFamily', 'fontSize',
+			'|',
+			'bold', 'italic',
+			'|',
+			'alignment:left', 'alignment:center', 'alignment:right', 'alignment:justify',
+			'|',
+			'bulletedList', 'numberedList',
+			'|',
+			'indent', 'outdent',
+			'|',
+			'link', 'blockQuote',
+			'|',
+			'undo', 'redo'
+		],
+		viewportTopOffset: window.getViewportTopOffsetConfig()
+	},
+	indentBlock: { offset: 30, unit: 'px' }
+};
 
 window.ClassicEditor = ClassicEditor;
 window.CKEditorPlugins = {

docs/_snippets/features/table-styling-colors.js

@@ -5,8 +5,6 @@
 
 /* globals ClassicEditor, CKEditorPlugins, console, window, document */
 
-import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
-
 const customColorPalette = [
 	{
 		color: 'hsl(4, 90%, 58%)',
@@ -96,13 +94,6 @@ ClassicEditor
 			CKEditorPlugins.TableProperties,
 			CKEditorPlugins.TableCellProperties
 		],
-		cloudServices: CS_CONFIG,
-		toolbar: {
-			items: [
-				'insertTable', '|', 'heading', '|', 'bold', 'italic', '|', 'undo', 'redo'
-			],
-			viewportTopOffset: window.getViewportTopOffsetConfig()
-		},
 		table: {
 			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells', 'tableProperties', 'tableCellProperties' ],
 			tableProperties: {

docs/_snippets/features/table-styling.js

@@ -5,8 +5,6 @@
 
 /* globals ClassicEditor, CKEditorPlugins, console, window, document */
 
-import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
-
 const COLOR_PALETTE = [
 	{
 		color: 'hsl(0, 0%, 0%)',
@@ -97,13 +95,6 @@ ClassicEditor
 			CKEditorPlugins.TableProperties,
 			CKEditorPlugins.TableCellProperties
 		],
-		cloudServices: CS_CONFIG,
-		toolbar: {
-			items: [
-				'insertTable', '|', 'heading', '|', 'bold', 'italic', '|', 'undo', 'redo'
-			],
-			viewportTopOffset: window.getViewportTopOffsetConfig()
-		},
 		table: {
 			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells', 'tableProperties', 'tableCellProperties' ],
 			tableProperties: {

docs/_snippets/features/table.js

@@ -5,17 +5,8 @@
 
 /* globals ClassicEditor, console, window, document */
 
-import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
-
 ClassicEditor
 	.create( document.querySelector( '#snippet-table' ), {
-		cloudServices: CS_CONFIG,
-		toolbar: {
-			items: [
-				'insertTable', '|', 'heading', '|', 'bold', 'italic', '|', 'undo', 'redo'
-			],
-			viewportTopOffset: window.getViewportTopOffsetConfig()
-		},
 		table: {
 			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells' ]
 		}

docs/features/table.md

@@ -31,6 +31,15 @@ Put the caret anywhere inside the table and click the **"Table properties"** but
 	By default, table styling tools are not included in the {@link builds/guides/overview ready–to–use editor builds} and must be installed separately. See the [installation](#table-and-cell-styling-tools-2) section to learn how to enable them in your editor.
 </info-box>
 
+## Table selection
+
+The {@link module:table/tableselection~TableSelection} plugin introduces support for the custom selection system for tables that lets you:
+
+* Select an arbitrary rectangular table fragment &mdash; a few cells from different rows, a column (or a few of them) or a row (or multiple rows).
+* Apply formatting or add a link to all selected cells at once.
+
+The table selection plugin is loaded automatically by the `Table` plugin and can be tested in the [demos above](#demos).
+
 ## Installation
 
 ### Basic table features

src/tableselection.js

@@ -22,7 +22,7 @@ import cropTable from './tableselection/croptable';
 import '../theme/tableselection.css';
 
 /**
- * This plugin enables the advanced table cells/rows/columns selection.
+ * This plugin enables the advanced table cells, rows and columns selection.
  * It is loaded automatically by the {@link module:table/table~Table} plugin.
  *
  * @extends module:core/plugin~Plugin
@@ -58,10 +58,11 @@ export default class TableSelection extends Plugin {
 		this._defineSelectionConverter();
 		this._enableShiftClickSelection();
 		this._enableMouseDragSelection();
+		this._enablePluginDisabling(); // sic!
 	}
 
 	/**
-	 * Returns currently selected table cells or `null` if not a table cells selection.
+	 * Returns the currently selected table cells or `null` if it is not a table cells selection.
 	 *
 	 * @returns {Array.<module:engine/model/element~Element>|null}
 	 */
@@ -75,6 +76,7 @@ export default class TableSelection extends Plugin {
 		}
 
 		// This should never happen, but let's know if it ever happens.
+		// @if CK_DEBUG //	/* istanbul ignore next */
 		// @if CK_DEBUG //	if ( selectedCells.length != selection.rangeCount ) {
 		// @if CK_DEBUG //		console.warn( 'Mixed selection warning. The selection contains table cells and some other ranges.' );
 		// @if CK_DEBUG //	}
@@ -83,7 +85,7 @@ export default class TableSelection extends Plugin {
 	}
 
 	/**
-	 * Returns a selected table fragment as a document fragment.
+	 * Returns the selected table fragment as a document fragment.
 	 *
 	 * @returns {module:engine/model/documentfragment~DocumentFragment|null}
 	 */
@@ -105,10 +107,10 @@ export default class TableSelection extends Plugin {
 	}
 
 	/**
-	 * Defines a selection converter which marks selected cells with a specific class.
+	 * Defines a selection converter which marks the selected cells with a specific class.
 	 *
 	 * The real DOM selection is put in the last cell. Since the order of ranges is dependent on whether the
-	 * selection is backward or not, the last cell with usually be close to the "focus" end of the selection
+	 * selection is backward or not, the last cell will usually be close to the "focus" end of the selection
 	 * (a selection has anchor and focus).
 	 *
 	 * The real DOM selection is then hidden with CSS.
@@ -151,8 +153,8 @@ export default class TableSelection extends Plugin {
 	}
 
 	/**
-	 * Enables making cells selection by Shift+click. Creates a selection from the cell which previously hold
-	 * the selection to the cell which was clicked (can be the same cell, in which case it selects a single cell).
+	 * Enables making cells selection by <kbd>Shift</kbd>+click. Creates a selection from the cell which previously held
+	 * the selection to the cell which was clicked. It can be the same cell, in which case it selects a single cell.
 	 *
 	 * @private
 	 */
@@ -217,7 +219,7 @@ export default class TableSelection extends Plugin {
 	/**
 	 * Enables making cells selection by dragging.
 	 *
-	 * The selection is made only on mousemove. We start tracking the mouse on mousedown.
+	 * The selection is made only on mousemove. Mouse tracking is started on mousedown.
 	 * However, the cells selection is enabled only after the mouse cursor left the anchor cell.
 	 * Thanks to that normal text selection within one cell works just fine. However, you can still select
 	 * just one cell by leaving the anchor cell and moving back to it.
@@ -293,7 +295,35 @@ export default class TableSelection extends Plugin {
 	}
 
 	/**
-	 * It overrides the default `model.deleteContent()` behavior over a selected table fragment.
+	 * Creates a listener that reacts to changes in {@link #isEnabled} and, if the plugin was disabled,
+	 * it collapses the multi-cell selection to a regular selection placed inside a table cell.
+	 *
+	 * This listener helps features that disable the table selection plugin bring the selection
+	 * to a clear state they can work with (for instance, because they don't support multiple cell selection).
+	 */
+	_enablePluginDisabling() {
+		const editor = this.editor;
+
+		this.on( 'change:isEnabled', () => {
+			if ( !this.isEnabled ) {
+				const selectedCells = this.getSelectedTableCells();
+
+				if ( !selectedCells ) {
+					return;
+				}
+
+				editor.model.change( writer => {
+					const position = writer.createPositionAt( selectedCells[ 0 ], 0 );
+					const range = editor.model.schema.getNearestSelectionRange( position );
+
+					writer.setSelection( range );
+				} );
+			}
+		} );
+	}
+
+	/**
+	 * Overrides the default `model.deleteContent()` behavior over a selected table fragment.
 	 *
 	 * @private
 	 * @param {module:utils/eventinfo~EventInfo} event
@@ -322,19 +352,20 @@ export default class TableSelection extends Plugin {
 
 			const rangeToSelect = model.schema.getNearestSelectionRange( writer.createPositionAt( tableCellToSelect, 0 ) );
 
-			if ( rangeToSelect ) {
-				if ( selection.is( 'documentSelection' ) ) {
-					writer.setSelection( rangeToSelect );
-				} else {
-					selection.setTo( rangeToSelect );
-				}
+			// Note: we ignore the case where rangeToSelect may be null because deleteContent() will always (unless someone broke it)
+			// create an empty paragraph to accommodate the selection.
+
+			if ( selection.is( 'documentSelection' ) ) {
+				writer.setSelection( rangeToSelect );
+			} else {
+				selection.setTo( rangeToSelect );
 			}
 		} );
 	}
 
 	/**
 	 * Sets the model selection based on given anchor and target cells (can be the same cell).
-	 * Takes care of setting backward flag.
+	 * Takes care of setting the backward flag.
 	 *
 	 * @protected
 	 * @param {module:engine/model/element~Element} anchorCell
@@ -365,10 +396,6 @@ export default class TableSelection extends Plugin {
 		const modelPosition = this.editor.editing.mapper.toModelPosition( viewPosition );
 		const modelElement = modelPosition.parent;
 
-		if ( !modelElement ) {
-			return;
-		}
-
 		if ( modelElement.is( 'tableCell' ) ) {
 			return modelElement;
 		}

src/tableselection/croptable.js

@@ -10,16 +10,16 @@
 import { findAncestor } from '../commands/utils';
 
 /**
- * Returns cropped table from selected table cells.
+ * Returns a cropped table from the selected table cells.
  *
- * This is to be used with table selection
+ * This function is to be used with the table selection.
  *
  *		tableSelection.startSelectingFrom( startCell )
  *		tableSelection.setSelectingFrom( endCell )
  *
  *		const croppedTable = cropTable( tableSelection.getSelectedTableCells() );
  *
- * **Note**: This function is used also by {@link module:table/tableselection~TableSelection#getSelectionAsFragment}
+ * **Note**: This function is also used by {@link module:table/tableselection~TableSelection#getSelectionAsFragment}.
  *
  * @param {Iterable.<module:engine/model/element~Element>} selectedTableCellsIterator
  * @param {module:table/tableutils~TableUtils} tableUtils

src/tableselection/mouseeventsobserver.js

@@ -10,18 +10,18 @@
 import DomEventObserver from '@ckeditor/ckeditor5-engine/src/view/observer/domeventobserver';
 
 /**
- * The mouse selection events observer.
+ * The mouse selection event observer.
  *
- * It registers listeners for DOM events:
+ * It registers listeners for the following DOM events:
  *
  * - `'mousemove'`
  * - `'mouseup'`
  * - `'mouseleave'`
  *
- * Note that this observer is disabled by default. To enable this observer it needs to be added to
+ * Note that this observer is disabled by default. To enable this observer, it needs to be added to
  * {@link module:engine/view/view~View} using the {@link module:engine/view/view~View#addObserver} method.
  *
- * It is registered by the {@link module:table/tableselection~TableSelection} plugin.
+ * The observer is registered by the {@link module:table/tableselection~TableSelection} plugin.
  *
  * @extends module:engine/view/observer/domeventobserver~DomEventObserver
  */
@@ -48,7 +48,7 @@ export default class MouseEventsObserver extends DomEventObserver {
  *
  * Introduced by {@link module:table/tableselection/mouseeventsobserver~MouseEventsObserver}.
  *
- * Note that this event is not available by default. To make it available
+ * Note that this event is not available by default. To make it available,
  * {@link module:table/tableselection/mouseeventsobserver~MouseEventsObserver} needs to be added
  * to {@link module:engine/view/view~View} using the {@link module:engine/view/view~View#addObserver} method.
  *
@@ -62,7 +62,7 @@ export default class MouseEventsObserver extends DomEventObserver {
  *
  * Introduced by {@link module:table/tableselection/mouseeventsobserver~MouseEventsObserver}.
  *
- * Note that this event is not available by default. To make it available
+ * Note that this event is not available by default. To make it available,
  * {@link module:table/tableselection/mouseeventsobserver~MouseEventsObserver} needs to be added
  * to {@link module:engine/view/view~View} using the {@link module:engine/view/view~View#addObserver} method.
  *
@@ -76,7 +76,7 @@ export default class MouseEventsObserver extends DomEventObserver {
  *
  * Introduced by {@link module:table/tableselection/mouseeventsobserver~MouseEventsObserver}.
  *
- * Note that this event is not available by default. To make it available
+ * Note that this event is not available by default. To make it available,
  * {@link module:table/tableselection/mouseeventsobserver~MouseEventsObserver} needs to be added
  * to {@link module:engine/view/view~View} using the {@link module:engine/view/view~View#addObserver} method.
  *

src/utils.js

@@ -93,7 +93,7 @@ export function getSelectedTableCells( selection ) {
 }
 
 /**
- * Returns all model table cells the provided model selection's ranges
+ * Returns all model table cells that the provided model selection's ranges
  * {@link module:engine/model/range~Range#start} inside.
  *
  * To obtain the cells selected from the outside, use