@ckeditor/ckeditor5-table 27.1.0 → 29.2.0

package/src/converters/upcasttable.js

@@ -8,6 +8,51 @@
  */
 
 import { createEmptyTableCell } from '../utils/common';
+import { first } from 'ckeditor5/src/utils';
+
+/**
+ * Returns a function that converts the table view representation:
+ *
+ *		<figure class="table"><table>...</table></figure>
+ *
+ * to the model representation:
+ *
+ *		<table></table>
+ *
+ * @returns {Function}
+ */
+export function upcastTableFigure() {
+	return dispatcher => {
+		dispatcher.on( 'element:figure', ( evt, data, conversionApi ) => {
+			// Do not convert if this is not a "table figure".
+			if ( !conversionApi.consumable.test( data.viewItem, { name: true, classes: 'table' } ) ) {
+				return;
+			}
+
+			// Find an table element inside the figure element.
+			const viewTable = getViewTableFromFigure( data.viewItem );
+
+			// Do not convert if table element is absent or was already converted.
+			if ( !viewTable || !conversionApi.consumable.test( viewTable, { name: true } ) ) {
+				return;
+			}
+
+			// Convert view table to model table.
+			const conversionResult = conversionApi.convertItem( viewTable, data.modelCursor );
+
+			// Get table element from conversion result.
+			const modelTable = first( conversionResult.modelRange.getItems() );
+
+			// When table wasn't successfully converted then finish conversion.
+			if ( !modelTable ) {
+				return;
+			}
+
+			conversionApi.convertChildren( data.viewItem, conversionApi.writer.createPositionAt( modelTable, 'end' ) );
+			conversionApi.updateConversionResult( modelTable, data );
+		} );
+	};
+}
 
 /**
  * View table element to model table element conversion helper.
@@ -50,6 +95,9 @@ export default function upcastTable() {
 			// Upcast table rows in proper order (heading rows first).
 			rows.forEach( row => conversionApi.convertItem( row, conversionApi.writer.createPositionAt( table, 'end' ) ) );
 
+			// Convert everything else.
+			conversionApi.convertChildren( viewTable, conversionApi.writer.createPositionAt( table, 'end' ) );
+
 			// Create one row and one table cell for empty table.
 			if ( table.isEmpty ) {
 				const row = conversionApi.writer.createElement( 'tableRow' );
@@ -109,12 +157,26 @@ export function ensureParagraphInTableCell( elementName ) {
 	};
 }
 
+// Get view `<table>` element from the view widget (`<figure>`).
+//
+// @private
+// @param {module:engine/view/element~Element} figureView
+// @returns {module:engine/view/element~Element}
+function getViewTableFromFigure( figureView ) {
+	for ( const figureChild of figureView.getChildren() ) {
+		if ( figureChild.is( 'element', 'table' ) ) {
+			return figureChild;
+		}
+	}
+}
+
 // Scans table rows and extracts required metadata from the table:
 //
 // headingRows    - The number of rows that go as table headers.
 // headingColumns - The maximum number of row headings.
 // rows           - Sorted `<tr>` elements as they should go into the model - ie. if `<thead>` is inserted after `<tbody>` in the view.
 //
+// @private
 // @param {module:engine/view/element~Element} viewTable
 // @returns {{headingRows, headingColumns, rows}}
 function scanTable( viewTable ) {
@@ -186,6 +248,7 @@ function scanTable( viewTable ) {
 // - For body rows:
 //     - Calculates the number of column headings.
 //
+// @private
 // @param {module:engine/view/element~Element} tr
 // @returns {Number}
 function scanRowForHeadingColumns( tr ) {

package/src/index.js

@@ -7,36 +7,21 @@
  * @module table
  */
 
-import Table from './table';
-import TableEditing from './tableediting';
-import TableUI from './tableui';
-import TableToolbar from './tabletoolbar';
-import TableCellProperties from './tablecellproperties';
-import TableCellPropertiesEditing from './tablecellproperties/tablecellpropertiesediting';
-import TableCellPropertiesUI from './tablecellproperties/tablecellpropertiesui';
-import TableProperties from './tableproperties';
-import TablePropertiesEditing from './tableproperties/tablepropertiesediting';
-import TablePropertiesUI from './tableproperties/tablepropertiesui';
-import TableClipboard from './tableclipboard';
-import TableMouse from './tablemouse';
-import TableKeyboard from './tablekeyboard';
-import TableSelection from './tableselection';
-import TableUtils from './tableutils';
-
-export default {
-	Table,
-	TableEditing,
-	TableUI,
-	TableToolbar,
-	TableCellProperties,
-	TableCellPropertiesEditing,
-	TableCellPropertiesUI,
-	TableProperties,
-	TablePropertiesEditing,
-	TablePropertiesUI,
-	TableMouse,
-	TableClipboard,
-	TableKeyboard,
-	TableSelection,
-	TableUtils
-};
+export { default as Table } from './table';
+export { default as TableEditing } from './tableediting';
+export { default as TableUI } from './tableui';
+export { default as TableToolbar } from './tabletoolbar';
+export { default as TableCellProperties } from './tablecellproperties';
+export { default as TableCellPropertiesEditing } from './tablecellproperties/tablecellpropertiesediting';
+export { default as TableCellPropertiesUI } from './tablecellproperties/tablecellpropertiesui';
+export { default as TableProperties } from './tableproperties';
+export { default as TablePropertiesEditing } from './tableproperties/tablepropertiesediting';
+export { default as TablePropertiesUI } from './tableproperties/tablepropertiesui';
+export { default as TableCaption } from './tablecaption';
+export { default as TableCaptionEditing } from './tablecaption/tablecaptionediting';
+export { default as TableCaptionUI } from './tablecaption/tablecaptionui';
+export { default as TableClipboard } from './tableclipboard';
+export { default as TableMouse } from './tablemouse';
+export { default as TableKeyboard } from './tablekeyboard';
+export { default as TableSelection } from './tableselection';
+export { default as TableUtils } from './tableutils';

package/src/table.js

@@ -74,6 +74,23 @@ export default class Table extends Plugin {
  * @member {module:table/table~TableConfig} module:core/editor/editorconfig~EditorConfig#table
  */
 
+/**
+ * Number of rows and columns to render by default as table heading when inserting new tables.
+ *
+ * You can configure it like this:
+ *
+ *		const tableConfig = {
+ *			defaultHeadings: {
+ *				rows: 1,
+ *				columns: 1
+ *			}
+ *		};
+ *
+ * Both rows and columns properties are optional defaulting to 0 (no heading).
+ *
+ * @member {Object} module:table/table~TableConfig#defaultHeadings
+ */
+
 /**
  * An array of color definitions (either strings or objects).
  *

package/src/tablecaption/tablecaptionediting.js

@@ -0,0 +1,153 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module table/tablecaption/tablecaptionediting
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+import { Element, enablePlaceholder } from 'ckeditor5/src/engine';
+import { toWidgetEditable } from 'ckeditor5/src/widget';
+
+import injectTableCaptionPostFixer from '../converters/table-caption-post-fixer';
+import ToggleTableCaptionCommand from './toggletablecaptioncommand';
+import { isTable, matchTableCaptionViewElement } from './utils';
+
+/**
+ * The table caption editing plugin.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class TableCaptionEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'TableCaptionEditing';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	constructor( editor ) {
+		super( editor );
+
+		/**
+		 * A map that keeps saved JSONified table captions and table model elements they are
+		 * associated with.
+		 *
+		 * To learn more about this system, see {@link #_saveCaption}.
+		 *
+		 * @member {WeakMap.<module:engine/model/element~Element,Object>}
+		 */
+		this._savedCaptionsMap = new WeakMap();
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		const editor = this.editor;
+		const schema = editor.model.schema;
+		const view = editor.editing.view;
+		const t = editor.t;
+
+		if ( !schema.isRegistered( 'caption' ) ) {
+			schema.register( 'caption', {
+				allowIn: 'table',
+				allowContentOf: '$block',
+				isLimit: true
+			} );
+		} else {
+			schema.extend( 'caption', {
+				allowIn: 'table'
+			} );
+		}
+
+		editor.commands.add( 'toggleTableCaption', new ToggleTableCaptionCommand( this.editor ) );
+
+		// View -> model converter for the data pipeline.
+		editor.conversion.for( 'upcast' ).elementToElement( {
+			view: matchTableCaptionViewElement,
+			model: 'caption'
+		} );
+
+		// Model -> view converter for the data pipeline.
+		editor.conversion.for( 'dataDowncast' ).elementToElement( {
+			model: 'caption',
+			view: ( modelElement, { writer } ) => {
+				if ( !isTable( modelElement.parent ) ) {
+					return null;
+				}
+
+				return writer.createContainerElement( 'figcaption' );
+			}
+		} );
+
+		// Model -> view converter for the editing pipeline.
+		editor.conversion.for( 'editingDowncast' ).elementToElement( {
+			model: 'caption',
+			view: ( modelElement, { writer } ) => {
+				if ( !isTable( modelElement.parent ) ) {
+					return null;
+				}
+
+				const figcaptionElement = writer.createEditableElement( 'figcaption' );
+				writer.setCustomProperty( 'tableCaption', true, figcaptionElement );
+
+				enablePlaceholder( {
+					view,
+					element: figcaptionElement,
+					text: t( 'Enter table caption' ),
+					keepOnFocus: true
+				} );
+
+				return toWidgetEditable( figcaptionElement, writer );
+			}
+		} );
+
+		injectTableCaptionPostFixer( editor.model );
+	}
+
+	/**
+	 * Returns the saved {@link module:engine/model/element~Element#toJSON JSONified} caption
+	 * of a table model element.
+	 *
+	 * See {@link #_saveCaption}.
+	 *
+	 * @protected
+	 * @param {module:engine/model/element~Element} tableModelElement The model element the
+	 * caption should be returned for.
+	 * @returns {module:engine/model/element~Element|null} The model caption element or `null` if there is none.
+	 */
+	_getSavedCaption( tableModelElement ) {
+		const jsonObject = this._savedCaptionsMap.get( tableModelElement );
+
+		return jsonObject ? Element.fromJSON( jsonObject ) : null;
+	}
+
+	/**
+	 * Saves a {@link module:engine/model/element~Element#toJSON JSONified} caption for
+	 * a table element to allow restoring it in the future.
+	 *
+	 * A caption is saved every time it gets hidden. The
+	 * user should be able to restore it on demand.
+	 *
+	 * **Note**: The caption cannot be stored in the table model element attribute because,
+	 * for instance, when the model state propagates to collaborators, the attribute would get
+	 * lost (mainly because it does not convert to anything when the caption is hidden) and
+	 * the states of collaborators' models would de-synchronize causing numerous issues.
+	 *
+	 * See {@link #_getSavedCaption}.
+	 *
+	 * @protected
+	 * @param {module:engine/model/element~Element} tableModelElement The model element the
+	 * caption is saved for.
+	 * @param {module:engine/model/element~Element} caption The caption model element to be saved.
+	 */
+	_saveCaption( tableModelElement, caption ) {
+		this._savedCaptionsMap.set( tableModelElement, caption.toJSON() );
+	}
+}

package/src/tablecaption/tablecaptionui.js

@@ -0,0 +1,71 @@
+/**
+* @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+*/
+
+/**
+* @module table/tablecaption/tablecaptionui
+*/
+
+import { Plugin, icons } from 'ckeditor5/src/core';
+import { ButtonView } from 'ckeditor5/src/ui';
+
+import { getCaptionFromModelSelection } from './utils';
+
+/**
+  * The table caption UI plugin. It introduces the `'toggleTableCaption'` UI button.
+  *
+  * @extends module:core/plugin~Plugin
+  */
+export default class TableCaptionUI extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'TableCaptionUI';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		const editor = this.editor;
+		const editingView = editor.editing.view;
+		const t = editor.t;
+
+		editor.ui.componentFactory.add( 'toggleTableCaption', locale => {
+			const command = editor.commands.get( 'toggleTableCaption' );
+			const view = new ButtonView( locale );
+
+			view.set( {
+				icon: icons.caption,
+				tooltip: true,
+				isToggleable: true
+			} );
+
+			view.bind( 'isOn', 'isEnabled' ).to( command, 'value', 'isEnabled' );
+			view.bind( 'label' ).to( command, 'value', value => value ? t( 'Toggle caption off' ) : t( 'Toggle caption on' ) );
+
+			this.listenTo( view, 'execute', () => {
+				editor.execute( 'toggleTableCaption', { focusCaptionOnShow: true } );
+
+				// Scroll to the selection and highlight the caption if the caption showed up.
+				if ( command.value ) {
+					const modelCaptionElement = getCaptionFromModelSelection( editor.model.document.selection );
+					const figcaptionElement = editor.editing.mapper.toViewElement( modelCaptionElement );
+
+					if ( !figcaptionElement ) {
+						return;
+					}
+
+					editingView.scrollToTheSelection();
+					editingView.change( writer => {
+						writer.addClass( 'table__caption_highlighted', figcaptionElement );
+					} );
+				}
+			} );
+
+			return view;
+		} );
+	}
+}

package/src/tablecaption/toggletablecaptioncommand.js

@@ -0,0 +1,120 @@
+/**
+* @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+*/
+
+/**
+* @module table/tablecaption/toggletablecaptioncommand
+*/
+
+import { Command } from 'ckeditor5/src/core';
+
+import { getCaptionFromTableModelElement, getSelectionAffectedTable } from './utils';
+
+/**
+ * The toggle table caption command.
+ *
+ * This command is registered by {@link module:table/tablecaption/tablecaptionediting~TableCaptionEditing} as the
+ * `'toggleTableCaption'` editor command.
+ *
+ * Executing this command:
+ *
+ * * either adds or removes the table caption of a selected table (depending on whether the caption is present or not),
+ * * removes the table caption if the selection is anchored in one.
+ *
+ *		// Toggle the presence of the caption.
+ *		editor.execute( 'toggleTableCaption' );
+ *
+ * **Note**: You can move the selection to the caption right away as it shows up upon executing this command by using
+ * the `focusCaptionOnShow` option:
+ *
+ *		editor.execute( 'toggleTableCaption', { focusCaptionOnShow: true } );
+ *
+ * @extends module:core/command~Command
+ */
+export default class ToggleTableCaptionCommand extends Command {
+	/**
+	 * @inheritDoc
+	 */
+	refresh() {
+		const editor = this.editor;
+		const tableElement = getSelectionAffectedTable( editor.model.document.selection );
+
+		this.isEnabled = !!tableElement;
+
+		if ( !this.isEnabled ) {
+			this.value = false;
+		} else {
+			this.value = !!getCaptionFromTableModelElement( tableElement );
+		}
+	}
+
+	/**
+	 * Executes the command.
+	 *
+	 *		editor.execute( 'toggleTableCaption' );
+	 *
+	 * @param {Object} [options] Options for the executed command.
+	 * @param {String} [options.focusCaptionOnShow] When true and the caption shows up, the selection will be moved into it straight away.
+	 * @fires execute
+	 */
+	execute( options = {} ) {
+		const { focusCaptionOnShow } = options;
+
+		this.editor.model.change( writer => {
+			if ( this.value ) {
+				this._hideTableCaption( writer );
+			} else {
+				this._showTableCaption( writer, focusCaptionOnShow );
+			}
+		} );
+	}
+
+	/**
+	 * Shows the table caption. Also:
+	 *
+	 * * it attempts to restore the caption content from the `TableCaptionEditing` caption registry,
+	 * * it moves the selection to the caption right away, it the `focusCaptionOnShow` option was set.
+	 *
+	 * @private
+	 * @param {module:engine/model/writer~Writer} writer
+	 * @param {Boolean} focusCaptionOnShow Default focus behavior when showing the caption.
+	 */
+	_showTableCaption( writer, focusCaptionOnShow ) {
+		const model = this.editor.model;
+		const tableElement = getSelectionAffectedTable( model.document.selection );
+		const tableCaptionEditing = this.editor.plugins.get( 'TableCaptionEditing' );
+		const savedCaptionElement = tableCaptionEditing._getSavedCaption( tableElement );
+
+		// Try restoring the caption from the TableCaptionEditing plugin storage.
+		const newCaptionElement = savedCaptionElement || writer.createElement( 'caption' );
+
+		writer.append( newCaptionElement, tableElement );
+
+		if ( focusCaptionOnShow ) {
+			writer.setSelection( newCaptionElement, 'in' );
+		}
+	}
+
+	/**
+	 * Hides the caption of a selected table (or an table caption the selection is anchored to).
+	 *
+	 * The content of the caption is stored in the `TableCaptionEditing` caption registry to make this
+	 * a reversible action.
+	 *
+	 * @private
+	 * @param {module:engine/model/writer~Writer} writer
+	 */
+	_hideTableCaption( writer ) {
+		const model = this.editor.model;
+		const tableElement = getSelectionAffectedTable( model.document.selection );
+		const tableCaptionEditing = this.editor.plugins.get( 'TableCaptionEditing' );
+		const captionElement = getCaptionFromTableModelElement( tableElement );
+
+		// Store the caption content so it can be restored quickly if the user changes their mind.
+		tableCaptionEditing._saveCaption( tableElement, captionElement );
+
+		writer.setSelection( writer.createRangeIn( tableElement.getChild( 0 ).getChild( 0 ) ) );
+		writer.remove( captionElement );
+	}
+}

package/src/tablecaption/utils.js

@@ -0,0 +1,93 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module table/tablecaption/utils
+ */
+
+/**
+ * Checks if the provided model element is a `table`.
+ *
+ * @param {module:engine/model/element~Element} modelElement Element to check if it is a table.
+ * @returns {Boolean}
+ */
+export function isTable( modelElement ) {
+	return !!modelElement && modelElement.is( 'element', 'table' );
+}
+
+/**
+ * Returns the caption model element from a given table element. Returns `null` if no caption is found.
+ *
+ * @param {module:engine/model/element~Element} tableModelElement Table element in which we will try to find a caption element.
+ * @returns {module:engine/model/element~Element|null}
+ */
+export function getCaptionFromTableModelElement( tableModelElement ) {
+	for ( const node of tableModelElement.getChildren() ) {
+		if ( node.is( 'element', 'caption' ) ) {
+			return node;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Returns the caption model element for a model selection. Returns `null` if the selection has no caption element ancestor.
+ *
+ * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+ * The selection checked for caption presence.
+ * @returns {module:engine/model/element~Element|null}
+ */
+export function getCaptionFromModelSelection( selection ) {
+	const tableElement = getSelectionAffectedTable( selection );
+
+	if ( !tableElement ) {
+		return null;
+	}
+
+	return getCaptionFromTableModelElement( tableElement );
+}
+
+/**
+ * {@link module:engine/view/matcher~Matcher} pattern. Checks if a given element is a caption.
+ *
+ * There are two possible forms of the valid caption:
+ *  - A `<figcaption>` element inside a `<figure class="table">` element.
+ *  - A `<caption>` inside a <table>.
+ *
+ * @param {module:engine/view/element~Element} element
+ * @returns {Object|null} Returns the object accepted by {@link module:engine/view/matcher~Matcher} or `null` if the element
+ * cannot be matched.
+ */
+export function matchTableCaptionViewElement( element ) {
+	const parent = element.parent;
+
+	if ( element.name == 'figcaption' && parent && parent.name == 'figure' && parent.hasClass( 'table' ) ) {
+		return { name: true };
+	}
+
+	if ( element.name == 'caption' && parent && parent.name == 'table' ) {
+		return { name: true };
+	}
+
+	return null;
+}
+
+/**
+ * Depending on the position of the selection we either return the table under cursor or look for the table higher in the hierarchy.
+ *
+ * @param {module:engine/model/position~Position} position
+ * @returns {module:engine/model/element~Element}
+ */
+export function getSelectionAffectedTable( selection ) {
+	const selectedElement = selection.getSelectedElement();
+
+	// Is the command triggered from the `tableToolbar`?
+	if ( selectedElement && selectedElement.is( 'element', 'table' ) ) {
+		return selectedElement;
+	}
+
+	return selection.getFirstPosition().findAncestor( 'table' );
+}

package/src/tablecaption.js

@@ -0,0 +1,35 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module table/tablecaption
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+import TableCaptionEditing from './tablecaption/tablecaptionediting';
+import TableCaptionUI from './tablecaption/tablecaptionui';
+
+import '../theme/tablecaption.css';
+
+/**
+ * The table caption plugin.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class TableCaption extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'TableCaption';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ TableCaptionEditing, TableCaptionUI ];
+	}
+}

package/src/tablecellproperties/commands/tablecellbackgroundcolorcommand.js

@@ -28,8 +28,9 @@ export default class TableCellBackgroundColorCommand extends TableCellPropertyCo
 	 * Creates a new `TableCellBackgroundColorCommand` instance.
 	 *
 	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
+	 * @param {String} defaultValue The default value of the attribute.
 	 */
-	constructor( editor ) {
-		super( editor, 'backgroundColor' );
+	constructor( editor, defaultValue ) {
+		super( editor, 'backgroundColor', defaultValue );
 	}
 }

package/src/tablecellproperties/commands/tablecellbordercolorcommand.js

@@ -29,9 +29,10 @@ export default class TableCellBorderColorCommand extends TableCellPropertyComman
 	 * Creates a new `TableCellBorderColorCommand` instance.
 	 *
 	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
+	 * @param {String} defaultValue The default value of the attribute.
 	 */
-	constructor( editor ) {
-		super( editor, 'borderColor' );
+	constructor( editor, defaultValue ) {
+		super( editor, 'borderColor', defaultValue );
 	}
 
 	/**
@@ -42,6 +43,12 @@ export default class TableCellBorderColorCommand extends TableCellPropertyComman
 			return;
 		}
 
-		return getSingleValue( tableCell.getAttribute( this.attributeName ) );
+		const value = getSingleValue( tableCell.getAttribute( this.attributeName ) );
+
+		if ( value === this._defaultValue ) {
+			return;
+		}
+
+		return value;
 	}
 }