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

package/src/converters/table-caption-post-fixer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @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/converters/table-caption-post-fixer
+ */
+import type { Model } from 'ckeditor5/src/engine';
+/**
+ * Injects a table caption post-fixer into the model.
+ *
+ * The role of the table caption post-fixer is to ensure that the table with caption have the correct structure
+ * after a {@link module:engine/model/model~Model#change `change()`} block was executed.
+ *
+ * The correct structure means that:
+ *
+ * * If there are many caption model element, they are merged into one model.
+ * * A final, merged caption model is placed at the end of the table.
+ */
+export default function injectTableCaptionPostFixer(model: Model): void;

package/src/converters/table-caption-post-fixer.js

@@ -2,11 +2,6 @@
  * @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/converters/table-caption-post-fixer
- */
-
 /**
  * Injects a table caption post-fixer into the model.
  *
@@ -17,53 +12,42 @@
  *
  * * If there are many caption model element, they are merged into one model.
  * * A final, merged caption model is placed at the end of the table.
- *
- * @param {module:engine/model/model~Model} model
  */
-export default function injectTableCaptionPostFixer( model ) {
-	model.document.registerPostFixer( writer => tableCaptionPostFixer( writer, model ) );
+export default function injectTableCaptionPostFixer(model) {
+    model.document.registerPostFixer(writer => tableCaptionPostFixer(writer, model));
 }
-
-// The table caption post-fixer.
-//
-// @param {module:engine/model/writer~Writer} writer
-// @param {module:engine/model/model~Model} model
-function tableCaptionPostFixer( writer, model ) {
-	const changes = model.document.differ.getChanges();
-	let wasFixed = false;
-
-	for ( const entry of changes ) {
-		if ( entry.type != 'insert' ) {
-			continue;
-		}
-
-		const positionParent = entry.position.parent;
-
-		if ( positionParent.is( 'element', 'table' ) || entry.name == 'table' ) {
-			const table = entry.name == 'table' ? entry.position.nodeAfter : entry.position.parent;
-			const captionsToMerge = Array.from( table.getChildren() ).filter( child => child.is( 'element', 'caption' ) );
-			const firstCaption = captionsToMerge.shift();
-
-			if ( !firstCaption ) {
-				continue;
-			}
-
-			// Move all the contents of the captions to the first one.
-			for ( const caption of captionsToMerge ) {
-				writer.move( writer.createRangeIn( caption ), firstCaption, 'end' );
-				writer.remove( caption );
-			}
-
-			// Make sure the final caption is at the end of the table.
-			if ( firstCaption.nextSibling ) {
-				writer.move( writer.createRangeOn( firstCaption ), table, 'end' );
-				wasFixed = true;
-			}
-
-			// Do we merged captions and/or moved the single caption to the end of the table?
-			wasFixed = !!captionsToMerge.length || wasFixed;
-		}
-	}
-
-	return wasFixed;
+/**
+ * The table caption post-fixer.
+ */
+function tableCaptionPostFixer(writer, model) {
+    const changes = model.document.differ.getChanges();
+    let wasFixed = false;
+    for (const entry of changes) {
+        if (entry.type != 'insert') {
+            continue;
+        }
+        const positionParent = entry.position.parent;
+        if (positionParent.is('element', 'table') || entry.name == 'table') {
+            const table = (entry.name == 'table' ? entry.position.nodeAfter : positionParent);
+            const captionsToMerge = Array.from(table.getChildren())
+                .filter((child) => child.is('element', 'caption'));
+            const firstCaption = captionsToMerge.shift();
+            if (!firstCaption) {
+                continue;
+            }
+            // Move all the contents of the captions to the first one.
+            for (const caption of captionsToMerge) {
+                writer.move(writer.createRangeIn(caption), firstCaption, 'end');
+                writer.remove(caption);
+            }
+            // Make sure the final caption is at the end of the table.
+            if (firstCaption.nextSibling) {
+                writer.move(writer.createRangeOn(firstCaption), table, 'end');
+                wasFixed = true;
+            }
+            // Do we merged captions and/or moved the single caption to the end of the table?
+            wasFixed = !!captionsToMerge.length || wasFixed;
+        }
+    }
+    return wasFixed;
 }

package/src/converters/table-cell-paragraph-post-fixer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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/converters/table-cell-paragraph-post-fixer
+ */
+import type { Model } from 'ckeditor5/src/engine';
+/**
+ * Injects a table cell post-fixer into the model which inserts a `paragraph` element into empty table cells.
+ *
+ * A table cell must contain at least one block element as a child. An empty table cell will have an empty `paragraph` as a child.
+ *
+ * ```xml
+ * <table>
+ *   <tableRow>
+ *      <tableCell></tableCell>
+ *   </tableRow>
+ * </table>
+ * ```
+ *
+ * Will be fixed to:
+ *
+ * ```xml
+ * <table>
+ *   <tableRow>
+ *      <tableCell><paragraph></paragraph></tableCell>
+ *   </tableRow>
+ * </table>
+ * ```
+ */
+export default function injectTableCellParagraphPostFixer(model: Model): void;

package/src/converters/table-cell-paragraph-post-fixer.js

@@ -2,137 +2,106 @@
  * @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/converters/table-cell-paragraph-post-fixer
- */
-
 /**
  * Injects a table cell post-fixer into the model which inserts a `paragraph` element into empty table cells.
  *
  * A table cell must contain at least one block element as a child. An empty table cell will have an empty `paragraph` as a child.
  *
- *		<table>
- *			<tableRow>
- *				<tableCell></tableCell>
- *			</tableRow>
- *		</table>
+ * ```xml
+ * <table>
+ *   <tableRow>
+ *      <tableCell></tableCell>
+ *   </tableRow>
+ * </table>
+ * ```
  *
  * Will be fixed to:
  *
- *		<table>
- *			<tableRow>
- *				<tableCell><paragraph></paragraph></tableCell>
- *			</tableRow>
- *		</table>
- *
- * @param {module:engine/model/model~Model} model
+ * ```xml
+ * <table>
+ *   <tableRow>
+ *      <tableCell><paragraph></paragraph></tableCell>
+ *   </tableRow>
+ * </table>
+ * ```
  */
-export default function injectTableCellParagraphPostFixer( model ) {
-	model.document.registerPostFixer( writer => tableCellContentsPostFixer( writer, model ) );
+export default function injectTableCellParagraphPostFixer(model) {
+    model.document.registerPostFixer(writer => tableCellContentsPostFixer(writer, model));
 }
-
-// The table cell contents post-fixer.
-//
-// @param {module:engine/model/writer~Writer} writer
-// @param {module:engine/model/model~Model} model
-function tableCellContentsPostFixer( writer, model ) {
-	const changes = model.document.differ.getChanges();
-
-	let wasFixed = false;
-
-	for ( const entry of changes ) {
-		if ( entry.type == 'insert' && entry.name == 'table' ) {
-			wasFixed = fixTable( entry.position.nodeAfter, writer ) || wasFixed;
-		}
-
-		if ( entry.type == 'insert' && entry.name == 'tableRow' ) {
-			wasFixed = fixTableRow( entry.position.nodeAfter, writer ) || wasFixed;
-		}
-
-		if ( entry.type == 'insert' && entry.name == 'tableCell' ) {
-			wasFixed = fixTableCellContent( entry.position.nodeAfter, writer ) || wasFixed;
-		}
-
-		if ( checkTableCellChange( entry ) ) {
-			wasFixed = fixTableCellContent( entry.position.parent, writer ) || wasFixed;
-		}
-	}
-
-	return wasFixed;
+/**
+ * The table cell contents post-fixer.
+ */
+function tableCellContentsPostFixer(writer, model) {
+    const changes = model.document.differ.getChanges();
+    let wasFixed = false;
+    for (const entry of changes) {
+        if (entry.type == 'insert' && entry.name == 'table') {
+            wasFixed = fixTable(entry.position.nodeAfter, writer) || wasFixed;
+        }
+        if (entry.type == 'insert' && entry.name == 'tableRow') {
+            wasFixed = fixTableRow(entry.position.nodeAfter, writer) || wasFixed;
+        }
+        if (entry.type == 'insert' && entry.name == 'tableCell') {
+            wasFixed = fixTableCellContent(entry.position.nodeAfter, writer) || wasFixed;
+        }
+        if ((entry.type == 'remove' || entry.type == 'insert') && checkTableCellChange(entry)) {
+            wasFixed = fixTableCellContent(entry.position.parent, writer) || wasFixed;
+        }
+    }
+    return wasFixed;
 }
-
-// Fixes all table cells in a table.
-//
-// @param {module:engine/model/element~Element} table
-// @param {module:engine/model/writer~Writer} writer
-function fixTable( table, writer ) {
-	let wasFixed = false;
-
-	for ( const row of table.getChildren() ) {
-		if ( row.is( 'element', 'tableRow' ) ) {
-			wasFixed = fixTableRow( row, writer ) || wasFixed;
-		}
-	}
-
-	return wasFixed;
+/**
+ * Fixes all table cells in a table.
+ */
+function fixTable(table, writer) {
+    let wasFixed = false;
+    for (const row of table.getChildren()) {
+        if (row.is('element', 'tableRow')) {
+            wasFixed = fixTableRow(row, writer) || wasFixed;
+        }
+    }
+    return wasFixed;
 }
-
-// Fixes all table cells in a table row.
-//
-// @param {module:engine/model/element~Element} tableRow
-// @param {module:engine/model/writer~Writer} writer
-function fixTableRow( tableRow, writer ) {
-	let wasFixed = false;
-
-	for ( const tableCell of tableRow.getChildren() ) {
-		wasFixed = fixTableCellContent( tableCell, writer ) || wasFixed;
-	}
-
-	return wasFixed;
+/**
+ * Fixes all table cells in a table row.
+ */
+function fixTableRow(tableRow, writer) {
+    let wasFixed = false;
+    for (const tableCell of tableRow.getChildren()) {
+        wasFixed = fixTableCellContent(tableCell, writer) || wasFixed;
+    }
+    return wasFixed;
 }
-
-// Fixes all table cell content by:
-// - Adding a paragraph to a table cell without any child.
-// - Wrapping direct $text in a `<paragraph>`.
-//
-// @param {module:engine/model/element~Element} table
-// @param {module:engine/model/writer~Writer} writer
-// @returns {Boolean}
-function fixTableCellContent( tableCell, writer ) {
-	// Insert paragraph to an empty table cell.
-	if ( tableCell.childCount == 0 ) {
-		// @if CK_DEBUG_TABLE // console.log( 'Post-fixing table: insert paragraph in empty cell.' );
-
-		writer.insertElement( 'paragraph', tableCell );
-
-		return true;
-	}
-
-	// Check table cell children for directly placed text nodes.
-	// Temporary solution. See https://github.com/ckeditor/ckeditor5/issues/1464.
-	const textNodes = Array.from( tableCell.getChildren() ).filter( child => child.is( '$text' ) );
-
-	// @if CK_DEBUG_TABLE // textNodes.length && console.log( 'Post-fixing table: wrap cell content with paragraph.' );
-
-	for ( const child of textNodes ) {
-		writer.wrap( writer.createRangeOn( child ), 'paragraph' );
-	}
-
-	// Return true when there were text nodes to fix.
-	return !!textNodes.length;
+/**
+ * Fixes all table cell content by:
+ * - Adding a paragraph to a table cell without any child.
+ * - Wrapping direct $text in a `<paragraph>`.
+ */
+function fixTableCellContent(tableCell, writer) {
+    // Insert paragraph to an empty table cell.
+    if (tableCell.childCount == 0) {
+        // @if CK_DEBUG_TABLE // console.log( 'Post-fixing table: insert paragraph in empty cell.' );
+        writer.insertElement('paragraph', tableCell);
+        return true;
+    }
+    // Check table cell children for directly placed text nodes.
+    // Temporary solution. See https://github.com/ckeditor/ckeditor5/issues/1464.
+    const textNodes = Array.from(tableCell.getChildren()).filter(child => child.is('$text'));
+    // @if CK_DEBUG_TABLE // textNodes.length && console.log( 'Post-fixing table: wrap cell content with paragraph.' );
+    for (const child of textNodes) {
+        writer.wrap(writer.createRangeOn(child), 'paragraph');
+    }
+    // Return true when there were text nodes to fix.
+    return !!textNodes.length;
 }
-
-// Checks if a differ change should fix the table cell. This happens on:
-// - Removing content from the table cell (i.e. `tableCell` can be left empty).
-// - Adding a text node directly into a table cell.
-//
-// @param {Object} differ change entry
-// @returns {Boolean}
-function checkTableCellChange( entry ) {
-	if ( !entry.position || !entry.position.parent.is( 'element', 'tableCell' ) ) {
-		return false;
-	}
-
-	return entry.type == 'insert' && entry.name == '$text' || entry.type == 'remove';
+/**
+ * Checks if a differ change should fix the table cell. This happens on:
+ * - Removing content from the table cell (i.e. `tableCell` can be left empty).
+ * - Adding a text node directly into a table cell.
+ */
+function checkTableCellChange(entry) {
+    if (!entry.position.parent.is('element', 'tableCell')) {
+        return false;
+    }
+    return entry.type == 'insert' && entry.name == '$text' || entry.type == 'remove';
 }

package/src/converters/table-cell-refresh-handler.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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/converters/table-cell-refresh-handler
+ */
+import type { EditingController, Model } from 'ckeditor5/src/engine';
+/**
+ * A table cell refresh handler which marks the table cell in the differ to have it re-rendered.
+ *
+ * Model `paragraph` inside a table cell can be rendered as `<span>` or `<p>`. It is rendered as `<span>` if this is the only block
+ * element in that table cell and it does not have any attributes. It is rendered as `<p>` otherwise.
+ *
+ * When table cell content changes, for example a second `paragraph` element is added, we need to ensure that the first `paragraph` is
+ * re-rendered so it changes from `<span>` to `<p>`. The easiest way to do it is to re-render the entire table cell.
+ */
+export default function tableCellRefreshHandler(model: Model, editing: EditingController): void;

package/src/converters/table-cell-refresh-handler.js

@@ -2,13 +2,7 @@
  * @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/converters/table-cell-refresh-post-fixer
- */
-
 import { isSingleParagraphWithoutAttributes } from './downcast';
-
 /**
  * A table cell refresh handler which marks the table cell in the differ to have it re-rendered.
  *
@@ -17,48 +11,35 @@ import { isSingleParagraphWithoutAttributes } from './downcast';
  *
  * When table cell content changes, for example a second `paragraph` element is added, we need to ensure that the first `paragraph` is
  * re-rendered so it changes from `<span>` to `<p>`. The easiest way to do it is to re-render the entire table cell.
- *
- * @param {module:engine/model/model~Model} model
- * @param {module:engine/controller/editingcontroller~EditingController} editing
  */
-export default function tableCellRefreshHandler( model, editing ) {
-	const differ = model.document.differ;
-
-	// Stores cells to be refreshed, so the table cell will be refreshed once for multiple changes.
-	const cellsToCheck = new Set();
-
-	for ( const change of differ.getChanges() ) {
-		const parent = change.type == 'attribute' ? change.range.start.parent : change.position.parent;
-
-		if ( parent.is( 'element', 'tableCell' ) ) {
-			cellsToCheck.add( parent );
-		}
-	}
-
-	for ( const tableCell of cellsToCheck.values() ) {
-		const paragraphsToRefresh = Array.from( tableCell.getChildren() ).filter( child => shouldRefresh( child, editing.mapper ) );
-
-		for ( const paragraph of paragraphsToRefresh ) {
-			editing.reconvertItem( paragraph );
-		}
-	}
+export default function tableCellRefreshHandler(model, editing) {
+    const differ = model.document.differ;
+    // Stores cells to be refreshed, so the table cell will be refreshed once for multiple changes.
+    const cellsToCheck = new Set();
+    for (const change of differ.getChanges()) {
+        const parent = change.type == 'attribute' ? change.range.start.parent : change.position.parent;
+        if (parent.is('element', 'tableCell')) {
+            cellsToCheck.add(parent);
+        }
+    }
+    for (const tableCell of cellsToCheck.values()) {
+        const paragraphsToRefresh = Array.from(tableCell.getChildren())
+            .filter(child => shouldRefresh(child, editing.mapper));
+        for (const paragraph of paragraphsToRefresh) {
+            editing.reconvertItem(paragraph);
+        }
+    }
 }
-
-// Check if given model element needs refreshing.
-//
-// @param {module:engine/model/element~Element} modelElement
-// @param {module:engine/conversion/mapper~Mapper} mapper
-// @returns {Boolean}
-function shouldRefresh( child, mapper ) {
-	if ( !child.is( 'element', 'paragraph' ) ) {
-		return false;
-	}
-
-	const viewElement = mapper.toViewElement( child );
-
-	if ( !viewElement ) {
-		return false;
-	}
-
-	return isSingleParagraphWithoutAttributes( child ) !== viewElement.is( 'element', 'span' );
+/**
+ * Check if given model element needs refreshing.
+ */
+function shouldRefresh(child, mapper) {
+    if (!child.is('element', 'paragraph')) {
+        return false;
+    }
+    const viewElement = mapper.toViewElement(child);
+    if (!viewElement) {
+        return false;
+    }
+    return isSingleParagraphWithoutAttributes(child) !== viewElement.is('element', 'span');
 }

package/src/converters/table-headings-refresh-handler.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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/converters/table-headings-refresh-handler
+ */
+import type { EditingController, Model } from 'ckeditor5/src/engine';
+/**
+ * A table headings refresh handler which marks the table cells or rows in the differ to have it re-rendered
+ * if the headings attribute changed.
+ *
+ * Table heading rows and heading columns are represented in the model by a `headingRows` and `headingColumns` attributes.
+ *
+ * When table headings attribute changes, all the cells/rows are marked to re-render to change between `<td>` and `<th>`.
+ */
+export default function tableHeadingsRefreshHandler(model: Model, editing: EditingController): void;

package/src/converters/table-headings-refresh-handler.js

@@ -2,13 +2,7 @@
  * @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/converters/table-heading-rows-refresh-post-fixer
- */
-
 import TableWalker from '../tablewalker';
-
 /**
  * A table headings refresh handler which marks the table cells or rows in the differ to have it re-rendered
  * if the headings attribute changed.
@@ -16,53 +10,40 @@ import TableWalker from '../tablewalker';
  * Table heading rows and heading columns are represented in the model by a `headingRows` and `headingColumns` attributes.
  *
  * When table headings attribute changes, all the cells/rows are marked to re-render to change between `<td>` and `<th>`.
- *
- * @param {module:engine/model/model~Model} model
- * @param {module:engine/controller/editingcontroller~EditingController} editing
  */
-export default function tableHeadingsRefreshHandler( model, editing ) {
-	const differ = model.document.differ;
-
-	for ( const change of differ.getChanges() ) {
-		let table;
-		let isRowChange = false;
-
-		if ( change.type == 'attribute' ) {
-			const element = change.range.start.nodeAfter;
-
-			if ( !element || !element.is( 'element', 'table' ) ) {
-				continue;
-			}
-
-			if ( change.attributeKey != 'headingRows' && change.attributeKey != 'headingColumns' ) {
-				continue;
-			}
-
-			table = element;
-			isRowChange = change.attributeKey == 'headingRows';
-		} else if ( change.name == 'tableRow' || change.name == 'tableCell' ) {
-			table = change.position.findAncestor( 'table' );
-			isRowChange = change.name == 'tableRow';
-		}
-
-		if ( !table ) {
-			continue;
-		}
-
-		const headingRows = table.getAttribute( 'headingRows' ) || 0;
-		const headingColumns = table.getAttribute( 'headingColumns' ) || 0;
-
-		const tableWalker = new TableWalker( table );
-
-		for ( const tableSlot of tableWalker ) {
-			const isHeading = tableSlot.row < headingRows || tableSlot.column < headingColumns;
-			const expectedElementName = isHeading ? 'th' : 'td';
-
-			const viewElement = editing.mapper.toViewElement( tableSlot.cell );
-
-			if ( viewElement && viewElement.is( 'element' ) && viewElement.name != expectedElementName ) {
-				editing.reconvertItem( isRowChange ? tableSlot.cell.parent : tableSlot.cell );
-			}
-		}
-	}
+export default function tableHeadingsRefreshHandler(model, editing) {
+    const differ = model.document.differ;
+    for (const change of differ.getChanges()) {
+        let table;
+        let isRowChange = false;
+        if (change.type == 'attribute') {
+            const element = change.range.start.nodeAfter;
+            if (!element || !element.is('element', 'table')) {
+                continue;
+            }
+            if (change.attributeKey != 'headingRows' && change.attributeKey != 'headingColumns') {
+                continue;
+            }
+            table = element;
+            isRowChange = change.attributeKey == 'headingRows';
+        }
+        else if (change.name == 'tableRow' || change.name == 'tableCell') {
+            table = change.position.findAncestor('table');
+            isRowChange = change.name == 'tableRow';
+        }
+        if (!table) {
+            continue;
+        }
+        const headingRows = table.getAttribute('headingRows') || 0;
+        const headingColumns = table.getAttribute('headingColumns') || 0;
+        const tableWalker = new TableWalker(table);
+        for (const tableSlot of tableWalker) {
+            const isHeading = tableSlot.row < headingRows || tableSlot.column < headingColumns;
+            const expectedElementName = isHeading ? 'th' : 'td';
+            const viewElement = editing.mapper.toViewElement(tableSlot.cell);
+            if (viewElement && viewElement.is('element') && viewElement.name != expectedElementName) {
+                editing.reconvertItem((isRowChange ? tableSlot.cell.parent : tableSlot.cell));
+            }
+        }
+    }
 }