@ckeditor/ckeditor5-table 36.0.1 → 37.0.0-alpha.0

package/src/commands/mergecellcommand.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/commands/mergecellcommand
+ */
+import type { Node } from 'ckeditor5/src/engine';
+import { Command, type Editor } from 'ckeditor5/src/core';
+import type { ArrowKeyCodeDirection } from 'ckeditor5/src/utils';
+/**
+ * The merge cell command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'mergeTableCellRight'`, `'mergeTableCellLeft'`,
+ * `'mergeTableCellUp'` and `'mergeTableCellDown'` editor commands.
+ *
+ * To merge a table cell at the current selection with another cell, execute the command corresponding with the preferred direction.
+ *
+ * For example, to merge with a cell to the right:
+ *
+ * ```ts
+ * editor.execute( 'mergeTableCellRight' );
+ * ```
+ *
+ * **Note**: If a table cell has a different [`rowspan`](https://www.w3.org/TR/html50/tabular-data.html#attr-tdth-rowspan)
+ * (for `'mergeTableCellRight'` and `'mergeTableCellLeft'`) or [`colspan`](https://www.w3.org/TR/html50/tabular-data.html#attr-tdth-colspan)
+ * (for `'mergeTableCellUp'` and `'mergeTableCellDown'`), the command will be disabled.
+ */
+export default class MergeCellCommand extends Command {
+    /**
+     * The direction that indicates which cell will be merged with the currently selected one.
+     */
+    readonly direction: ArrowKeyCodeDirection;
+    /**
+     * Whether the merge is horizontal (left/right) or vertical (up/down).
+     */
+    readonly isHorizontal: boolean;
+    /**
+     * @inheritDoc
+     */
+    value: Node | undefined;
+    /**
+     * Creates a new `MergeCellCommand` instance.
+     *
+     * @param editor The editor on which this command will be used.
+     * @param options.direction Indicates which cell to merge with the currently selected one.
+     * Possible values are: `'left'`, `'right'`, `'up'` and `'down'`.
+     */
+    constructor(editor: Editor, options: {
+        direction: ArrowKeyCodeDirection;
+    });
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * Depending on the command's {@link #direction} value, it will merge the cell that is to the `'left'`, `'right'`, `'up'` or `'down'`.
+     *
+     * @fires execute
+     */
+    execute(): void;
+    /**
+     * Returns a cell that can be merged with the current cell depending on the command's direction.
+     */
+    private _getMergeableCell;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        mergeTableCellRight: MergeCellCommand;
+        mergeTableCellLeft: MergeCellCommand;
+        mergeTableCellDown: MergeCellCommand;
+        mergeTableCellUp: MergeCellCommand;
+    }
+}

package/src/commands/mergecellcommand.js

@@ -2,16 +2,10 @@
  * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
-/**
- * @module table/commands/mergecellcommand
- */
-
 import { Command } from 'ckeditor5/src/core';
 import TableWalker from '../tablewalker';
 import { isHeadingColumnCell } from '../utils/common';
 import { removeEmptyRowsColumns } from '../utils/structure';
-
 /**
  * The merge cell command.
  *
@@ -22,252 +16,183 @@ import { removeEmptyRowsColumns } from '../utils/structure';
  *
  * For example, to merge with a cell to the right:
  *
- *		editor.execute( 'mergeTableCellRight' );
+ * ```ts
+ * editor.execute( 'mergeTableCellRight' );
+ * ```
  *
  * **Note**: If a table cell has a different [`rowspan`](https://www.w3.org/TR/html50/tabular-data.html#attr-tdth-rowspan)
  * (for `'mergeTableCellRight'` and `'mergeTableCellLeft'`) or [`colspan`](https://www.w3.org/TR/html50/tabular-data.html#attr-tdth-colspan)
  * (for `'mergeTableCellUp'` and `'mergeTableCellDown'`), the command will be disabled.
- *
- * @extends module:core/command~Command
  */
 export default class MergeCellCommand extends Command {
-	/**
-	 * Creates a new `MergeCellCommand` instance.
-	 *
-	 * @param {module:core/editor/editor~Editor} editor The editor on which this command will be used.
-	 * @param {Object} options
-	 * @param {String} options.direction Indicates which cell to merge with the currently selected one.
-	 * Possible values are: `'left'`, `'right'`, `'up'` and `'down'`.
-	 */
-	constructor( editor, options ) {
-		super( editor );
-
-		/**
-		 * The direction that indicates which cell will be merged with the currently selected one.
-		 *
-		 * @readonly
-		 * @member {String} #direction
-		 */
-		this.direction = options.direction;
-
-		/**
-		 * Whether the merge is horizontal (left/right) or vertical (up/down).
-		 *
-		 * @readonly
-		 * @member {Boolean} #isHorizontal
-		 */
-		this.isHorizontal = this.direction == 'right' || this.direction == 'left';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	refresh() {
-		const cellToMerge = this._getMergeableCell();
-
-		this.value = cellToMerge;
-		this.isEnabled = !!cellToMerge;
-	}
-
-	/**
-	 * Executes the command.
-	 *
-	 * Depending on the command's {@link #direction} value, it will merge the cell that is to the `'left'`, `'right'`, `'up'` or `'down'`.
-	 *
-	 * @fires execute
-	 */
-	execute() {
-		const model = this.editor.model;
-		const doc = model.document;
-		const tableUtils = this.editor.plugins.get( 'TableUtils' );
-		const tableCell = tableUtils.getTableCellsContainingSelection( doc.selection )[ 0 ];
-
-		const cellToMerge = this.value;
-		const direction = this.direction;
-
-		model.change( writer => {
-			const isMergeNext = direction == 'right' || direction == 'down';
-
-			// The merge mechanism is always the same so sort cells to be merged.
-			const cellToExpand = isMergeNext ? tableCell : cellToMerge;
-			const cellToRemove = isMergeNext ? cellToMerge : tableCell;
-
-			// Cache the parent of cell to remove for later check.
-			const removedTableCellRow = cellToRemove.parent;
-
-			mergeTableCells( cellToRemove, cellToExpand, writer );
-
-			const spanAttribute = this.isHorizontal ? 'colspan' : 'rowspan';
-			const cellSpan = parseInt( tableCell.getAttribute( spanAttribute ) || 1 );
-			const cellToMergeSpan = parseInt( cellToMerge.getAttribute( spanAttribute ) || 1 );
-
-			// Update table cell span attribute and merge set selection on merged contents.
-			writer.setAttribute( spanAttribute, cellSpan + cellToMergeSpan, cellToExpand );
-			writer.setSelection( writer.createRangeIn( cellToExpand ) );
-
-			const tableUtils = this.editor.plugins.get( 'TableUtils' );
-			const table = removedTableCellRow.findAncestor( 'table' );
-
-			// Remove empty rows and columns after merging.
-			removeEmptyRowsColumns( table, tableUtils );
-		} );
-	}
-
-	/**
-	 * Returns a cell that can be merged with the current cell depending on the command's direction.
-	 *
-	 * @returns {module:engine/model/element~Element|undefined}
-	 * @private
-	 */
-	_getMergeableCell() {
-		const model = this.editor.model;
-		const doc = model.document;
-		const tableUtils = this.editor.plugins.get( 'TableUtils' );
-		const tableCell = tableUtils.getTableCellsContainingSelection( doc.selection )[ 0 ];
-
-		if ( !tableCell ) {
-			return;
-		}
-
-		// First get the cell on proper direction.
-		const cellToMerge = this.isHorizontal ?
-			getHorizontalCell( tableCell, this.direction, tableUtils ) :
-			getVerticalCell( tableCell, this.direction, tableUtils );
-
-		if ( !cellToMerge ) {
-			return;
-		}
-
-		// If found check if the span perpendicular to merge direction is equal on both cells.
-		const spanAttribute = this.isHorizontal ? 'rowspan' : 'colspan';
-		const span = parseInt( tableCell.getAttribute( spanAttribute ) || 1 );
-
-		const cellToMergeSpan = parseInt( cellToMerge.getAttribute( spanAttribute ) || 1 );
-
-		if ( cellToMergeSpan === span ) {
-			return cellToMerge;
-		}
-	}
+    /**
+     * Creates a new `MergeCellCommand` instance.
+     *
+     * @param editor The editor on which this command will be used.
+     * @param options.direction Indicates which cell to merge with the currently selected one.
+     * Possible values are: `'left'`, `'right'`, `'up'` and `'down'`.
+     */
+    constructor(editor, options) {
+        super(editor);
+        this.direction = options.direction;
+        this.isHorizontal = this.direction == 'right' || this.direction == 'left';
+    }
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const cellToMerge = this._getMergeableCell();
+        this.value = cellToMerge;
+        this.isEnabled = !!cellToMerge;
+    }
+    /**
+     * Executes the command.
+     *
+     * Depending on the command's {@link #direction} value, it will merge the cell that is to the `'left'`, `'right'`, `'up'` or `'down'`.
+     *
+     * @fires execute
+     */
+    execute() {
+        const model = this.editor.model;
+        const doc = model.document;
+        const tableUtils = this.editor.plugins.get('TableUtils');
+        const tableCell = tableUtils.getTableCellsContainingSelection(doc.selection)[0];
+        const cellToMerge = this.value;
+        const direction = this.direction;
+        model.change(writer => {
+            const isMergeNext = direction == 'right' || direction == 'down';
+            // The merge mechanism is always the same so sort cells to be merged.
+            const cellToExpand = (isMergeNext ? tableCell : cellToMerge);
+            const cellToRemove = (isMergeNext ? cellToMerge : tableCell);
+            // Cache the parent of cell to remove for later check.
+            const removedTableCellRow = cellToRemove.parent;
+            mergeTableCells(cellToRemove, cellToExpand, writer);
+            const spanAttribute = this.isHorizontal ? 'colspan' : 'rowspan';
+            const cellSpan = parseInt(tableCell.getAttribute(spanAttribute) || '1');
+            const cellToMergeSpan = parseInt(cellToMerge.getAttribute(spanAttribute) || '1');
+            // Update table cell span attribute and merge set selection on merged contents.
+            writer.setAttribute(spanAttribute, cellSpan + cellToMergeSpan, cellToExpand);
+            writer.setSelection(writer.createRangeIn(cellToExpand));
+            const tableUtils = this.editor.plugins.get('TableUtils');
+            const table = removedTableCellRow.findAncestor('table');
+            // Remove empty rows and columns after merging.
+            removeEmptyRowsColumns(table, tableUtils);
+        });
+    }
+    /**
+     * Returns a cell that can be merged with the current cell depending on the command's direction.
+     */
+    _getMergeableCell() {
+        const model = this.editor.model;
+        const doc = model.document;
+        const tableUtils = this.editor.plugins.get('TableUtils');
+        const tableCell = tableUtils.getTableCellsContainingSelection(doc.selection)[0];
+        if (!tableCell) {
+            return;
+        }
+        // First get the cell on proper direction.
+        const cellToMerge = this.isHorizontal ?
+            getHorizontalCell(tableCell, this.direction, tableUtils) :
+            getVerticalCell(tableCell, this.direction, tableUtils);
+        if (!cellToMerge) {
+            return;
+        }
+        // If found check if the span perpendicular to merge direction is equal on both cells.
+        const spanAttribute = this.isHorizontal ? 'rowspan' : 'colspan';
+        const span = parseInt(tableCell.getAttribute(spanAttribute) || '1');
+        const cellToMergeSpan = parseInt(cellToMerge.getAttribute(spanAttribute) || '1');
+        if (cellToMergeSpan === span) {
+            return cellToMerge;
+        }
+    }
 }
-
-// Returns the cell that can be merged horizontally.
-//
-// @param {module:engine/model/element~Element} tableCell
-// @param {String} direction
-// @param {module:table/tableutils~TableUtils} tableUtils
-// @returns {module:engine/model/node~Node|null}
-function getHorizontalCell( tableCell, direction, tableUtils ) {
-	const tableRow = tableCell.parent;
-	const table = tableRow.parent;
-	const horizontalCell = direction == 'right' ? tableCell.nextSibling : tableCell.previousSibling;
-	const hasHeadingColumns = ( table.getAttribute( 'headingColumns' ) || 0 ) > 0;
-
-	if ( !horizontalCell ) {
-		return;
-	}
-
-	// Sort cells:
-	const cellOnLeft = direction == 'right' ? tableCell : horizontalCell;
-	const cellOnRight = direction == 'right' ? horizontalCell : tableCell;
-
-	// Get their column indexes:
-	const { column: leftCellColumn } = tableUtils.getCellLocation( cellOnLeft );
-	const { column: rightCellColumn } = tableUtils.getCellLocation( cellOnRight );
-
-	const leftCellSpan = parseInt( cellOnLeft.getAttribute( 'colspan' ) || 1 );
-
-	const isCellOnLeftInHeadingColumn = isHeadingColumnCell( tableUtils, cellOnLeft, table );
-	const isCellOnRightInHeadingColumn = isHeadingColumnCell( tableUtils, cellOnRight, table );
-
-	// We cannot merge heading columns cells with regular cells.
-	if ( hasHeadingColumns && isCellOnLeftInHeadingColumn != isCellOnRightInHeadingColumn ) {
-		return;
-	}
-
-	// The cell on the right must have index that is distant to the cell on the left by the left cell's width (colspan).
-	const cellsAreTouching = leftCellColumn + leftCellSpan === rightCellColumn;
-
-	// If the right cell's column index is different it means that there are rowspanned cells between them.
-	return cellsAreTouching ? horizontalCell : undefined;
+/**
+ * Returns the cell that can be merged horizontally.
+ */
+function getHorizontalCell(tableCell, direction, tableUtils) {
+    const tableRow = tableCell.parent;
+    const table = tableRow.parent;
+    const horizontalCell = direction == 'right' ? tableCell.nextSibling : tableCell.previousSibling;
+    const hasHeadingColumns = (table.getAttribute('headingColumns') || 0) > 0;
+    if (!horizontalCell) {
+        return;
+    }
+    // Sort cells:
+    const cellOnLeft = (direction == 'right' ? tableCell : horizontalCell);
+    const cellOnRight = (direction == 'right' ? horizontalCell : tableCell);
+    // Get their column indexes:
+    const { column: leftCellColumn } = tableUtils.getCellLocation(cellOnLeft);
+    const { column: rightCellColumn } = tableUtils.getCellLocation(cellOnRight);
+    const leftCellSpan = parseInt(cellOnLeft.getAttribute('colspan') || '1');
+    const isCellOnLeftInHeadingColumn = isHeadingColumnCell(tableUtils, cellOnLeft);
+    const isCellOnRightInHeadingColumn = isHeadingColumnCell(tableUtils, cellOnRight);
+    // We cannot merge heading columns cells with regular cells.
+    if (hasHeadingColumns && isCellOnLeftInHeadingColumn != isCellOnRightInHeadingColumn) {
+        return;
+    }
+    // The cell on the right must have index that is distant to the cell on the left by the left cell's width (colspan).
+    const cellsAreTouching = leftCellColumn + leftCellSpan === rightCellColumn;
+    // If the right cell's column index is different it means that there are rowspanned cells between them.
+    return cellsAreTouching ? horizontalCell : undefined;
 }
-
-// Returns the cell that can be merged vertically.
-//
-// @param {module:engine/model/element~Element} tableCell
-// @param {String} direction
-// @param {module:table/tableutils~TableUtils} tableUtils
-// @returns {module:engine/model/node~Node|null}
-function getVerticalCell( tableCell, direction, tableUtils ) {
-	const tableRow = tableCell.parent;
-	const table = tableRow.parent;
-
-	const rowIndex = table.getChildIndex( tableRow );
-
-	// Don't search for mergeable cell if direction points out of the table.
-	if ( ( direction == 'down' && rowIndex === tableUtils.getRows( table ) - 1 ) || ( direction == 'up' && rowIndex === 0 ) ) {
-		return;
-	}
-
-	const rowspan = parseInt( tableCell.getAttribute( 'rowspan' ) || 1 );
-	const headingRows = table.getAttribute( 'headingRows' ) || 0;
-
-	const isMergeWithBodyCell = direction == 'down' && ( rowIndex + rowspan ) === headingRows;
-	const isMergeWithHeadCell = direction == 'up' && rowIndex === headingRows;
-
-	// Don't search for mergeable cell if direction points out of the current table section.
-	if ( headingRows && ( isMergeWithBodyCell || isMergeWithHeadCell ) ) {
-		return;
-	}
-
-	const currentCellRowSpan = parseInt( tableCell.getAttribute( 'rowspan' ) || 1 );
-	const rowOfCellToMerge = direction == 'down' ? rowIndex + currentCellRowSpan : rowIndex;
-
-	const tableMap = [ ...new TableWalker( table, { endRow: rowOfCellToMerge } ) ];
-
-	const currentCellData = tableMap.find( value => value.cell === tableCell );
-	const mergeColumn = currentCellData.column;
-
-	const cellToMergeData = tableMap.find( ( { row, cellHeight, column } ) => {
-		if ( column !== mergeColumn ) {
-			return false;
-		}
-
-		if ( direction == 'down' ) {
-			// If merging a cell below the mergeRow is already calculated.
-			return row === rowOfCellToMerge;
-		} else {
-			// If merging a cell above calculate if it spans to mergeRow.
-			return rowOfCellToMerge === row + cellHeight;
-		}
-	} );
-
-	return cellToMergeData && cellToMergeData.cell;
+/**
+ * Returns the cell that can be merged vertically.
+ */
+function getVerticalCell(tableCell, direction, tableUtils) {
+    const tableRow = tableCell.parent;
+    const table = tableRow.parent;
+    const rowIndex = table.getChildIndex(tableRow);
+    // Don't search for mergeable cell if direction points out of the table.
+    if ((direction == 'down' && rowIndex === tableUtils.getRows(table) - 1) || (direction == 'up' && rowIndex === 0)) {
+        return null;
+    }
+    const rowspan = parseInt(tableCell.getAttribute('rowspan') || '1');
+    const headingRows = table.getAttribute('headingRows') || 0;
+    const isMergeWithBodyCell = direction == 'down' && (rowIndex + rowspan) === headingRows;
+    const isMergeWithHeadCell = direction == 'up' && rowIndex === headingRows;
+    // Don't search for mergeable cell if direction points out of the current table section.
+    if (headingRows && (isMergeWithBodyCell || isMergeWithHeadCell)) {
+        return null;
+    }
+    const currentCellRowSpan = parseInt(tableCell.getAttribute('rowspan') || '1');
+    const rowOfCellToMerge = direction == 'down' ? rowIndex + currentCellRowSpan : rowIndex;
+    const tableMap = [...new TableWalker(table, { endRow: rowOfCellToMerge })];
+    const currentCellData = tableMap.find(value => value.cell === tableCell);
+    const mergeColumn = currentCellData.column;
+    const cellToMergeData = tableMap.find(({ row, cellHeight, column }) => {
+        if (column !== mergeColumn) {
+            return false;
+        }
+        if (direction == 'down') {
+            // If merging a cell below the mergeRow is already calculated.
+            return row === rowOfCellToMerge;
+        }
+        else {
+            // If merging a cell above calculate if it spans to mergeRow.
+            return rowOfCellToMerge === row + cellHeight;
+        }
+    });
+    return cellToMergeData && cellToMergeData.cell ? cellToMergeData.cell : null;
 }
-
-// Merges two table cells. It will ensure that after merging cells with an empty paragraph, the resulting table cell will only have one
-// paragraph. If one of the merged table cells is empty, the merged table cell will have the contents of the non-empty table cell.
-// If both are empty, the merged table cell will have only one empty paragraph.
-//
-// @param {module:engine/model/element~Element} cellToRemove
-// @param {module:engine/model/element~Element} cellToExpand
-// @param {module:engine/model/writer~Writer} writer
-function mergeTableCells( cellToRemove, cellToExpand, writer ) {
-	if ( !isEmpty( cellToRemove ) ) {
-		if ( isEmpty( cellToExpand ) ) {
-			writer.remove( writer.createRangeIn( cellToExpand ) );
-		}
-
-		writer.move( writer.createRangeIn( cellToRemove ), writer.createPositionAt( cellToExpand, 'end' ) );
-	}
-
-	// Remove merged table cell.
-	writer.remove( cellToRemove );
+/**
+ * Merges two table cells. It will ensure that after merging cells with an empty paragraph, the resulting table cell will only have one
+ * paragraph. If one of the merged table cells is empty, the merged table cell will have the contents of the non-empty table cell.
+ * If both are empty, the merged table cell will have only one empty paragraph.
+ */
+function mergeTableCells(cellToRemove, cellToExpand, writer) {
+    if (!isEmpty(cellToRemove)) {
+        if (isEmpty(cellToExpand)) {
+            writer.remove(writer.createRangeIn(cellToExpand));
+        }
+        writer.move(writer.createRangeIn(cellToRemove), writer.createPositionAt(cellToExpand, 'end'));
+    }
+    // Remove merged table cell.
+    writer.remove(cellToRemove);
 }
-
-// Checks if the passed table cell contains an empty paragraph.
-//
-// @param {module:engine/model/element~Element} tableCell
-// @returns {Boolean}
-function isEmpty( tableCell ) {
-	return tableCell.childCount == 1 && tableCell.getChild( 0 ).is( 'element', 'paragraph' ) && tableCell.getChild( 0 ).isEmpty;
+/**
+ * Checks if the passed table cell contains an empty paragraph.
+ */
+function isEmpty(tableCell) {
+    const firstTableChild = tableCell.getChild(0);
+    return tableCell.childCount == 1 && firstTableChild.is('element', 'paragraph') && firstTableChild.isEmpty;
 }

package/src/commands/mergecellscommand.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Command } from 'ckeditor5/src/core';
+/**
+ * The merge cells command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'mergeTableCells'` editor command.
+ *
+ * For example, to merge selected table cells:
+ *
+ * ```ts
+ * editor.execute( 'mergeTableCells' );
+ * ```
+ */
+export default class MergeCellsCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     */
+    execute(): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        mergeTableCells: MergeCellsCommand;
+    }
+}