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

package/src/converters/downcast.js

@@ -2,104 +2,85 @@
  * @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/downcast
  */
-
-import TableWalker from './../tablewalker';
 import { toWidget, toWidgetEditable } from 'ckeditor5/src/widget';
-
+import TableWalker from './../tablewalker';
 /**
  * Model table element to view table element conversion helper.
- *
- * @param {module:table/tableutils~TableUtils} tableUtils The `TableUtils` plugin instance.
- * @param {Object} [options]
- * @param {Boolean} [options.asWidget] If set to `true`, the downcast conversion will produce a widget.
- * @returns {Function} Element creator.
  */
-export function downcastTable( tableUtils, options = {} ) {
-	return ( table, { writer } ) => {
-		const headingRows = table.getAttribute( 'headingRows' ) || 0;
-		const tableSections = [];
-
-		// Table head slot.
-		if ( headingRows > 0 ) {
-			tableSections.push(
-				writer.createContainerElement( 'thead', null,
-					writer.createSlot( element => element.is( 'element', 'tableRow' ) && element.index < headingRows )
-				)
-			);
-		}
-
-		// Table body slot.
-		if ( headingRows < tableUtils.getRows( table ) ) {
-			tableSections.push(
-				writer.createContainerElement( 'tbody', null,
-					writer.createSlot( element => element.is( 'element', 'tableRow' ) && element.index >= headingRows )
-				)
-			);
-		}
-
-		const figureElement = writer.createContainerElement( 'figure', { class: 'table' }, [
-			// Table with proper sections (thead, tbody).
-			writer.createContainerElement( 'table', null, tableSections ),
-
-			// Slot for the rest (for example caption).
-			writer.createSlot( element => !element.is( 'element', 'tableRow' ) )
-		] );
-
-		return options.asWidget ? toTableWidget( figureElement, writer ) : figureElement;
-	};
+export function downcastTable(tableUtils, options) {
+    return (table, { writer }) => {
+        const headingRows = table.getAttribute('headingRows') || 0;
+        const tableElement = writer.createContainerElement('table', null, []);
+        const figureElement = writer.createContainerElement('figure', { class: 'table' }, tableElement);
+        // Table head slot.
+        if (headingRows > 0) {
+            writer.insert(writer.createPositionAt(tableElement, 'end'), writer.createContainerElement('thead', null, writer.createSlot(element => element.is('element', 'tableRow') && element.index < headingRows)));
+        }
+        // Table body slot.
+        if (headingRows < tableUtils.getRows(table)) {
+            writer.insert(writer.createPositionAt(tableElement, 'end'), writer.createContainerElement('tbody', null, writer.createSlot(element => element.is('element', 'tableRow') && element.index >= headingRows)));
+        }
+        // Dynamic slots.
+        for (const { positionOffset, filter } of options.additionalSlots) {
+            writer.insert(writer.createPositionAt(tableElement, positionOffset), writer.createSlot(filter));
+        }
+        // Create a slot with items that don't fit into the table.
+        writer.insert(writer.createPositionAt(tableElement, 'after'), writer.createSlot(element => {
+            if (element.is('element', 'tableRow')) {
+                return false;
+            }
+            return !options.additionalSlots.some(({ filter }) => filter(element));
+        }));
+        return options.asWidget ? toTableWidget(figureElement, writer) : figureElement;
+    };
 }
-
 /**
  * Model table row element to view `<tr>` element conversion helper.
  *
- * @returns {Function} Element creator.
+ * @returns Element creator.
  */
 export function downcastRow() {
-	return ( tableRow, { writer } ) => {
-		return tableRow.isEmpty ?
-			writer.createEmptyElement( 'tr' ) :
-			writer.createContainerElement( 'tr' );
-	};
+    return (tableRow, { writer }) => {
+        return tableRow.isEmpty ?
+            writer.createEmptyElement('tr') :
+            writer.createContainerElement('tr');
+    };
 }
-
 /**
  * Model table cell element to view `<td>` or `<th>` element conversion helper.
  *
  * This conversion helper will create proper `<th>` elements for table cells that are in the heading section (heading row or column)
  * and `<td>` otherwise.
  *
- * @param {Object} [options]
- * @param {Boolean} [options.asWidget] If set to `true`, the downcast conversion will produce a widget.
- * @returns {Function} Element creator.
+ * @param options.asWidget If set to `true`, the downcast conversion will produce a widget.
+ * @returns Element creator.
  */
-export function downcastCell( options = {} ) {
-	return ( tableCell, { writer } ) => {
-		const tableRow = tableCell.parent;
-		const table = tableRow.parent;
-		const rowIndex = table.getChildIndex( tableRow );
-
-		const tableWalker = new TableWalker( table, { row: rowIndex } );
-		const headingRows = table.getAttribute( 'headingRows' ) || 0;
-		const headingColumns = table.getAttribute( 'headingColumns' ) || 0;
-
-		// We need to iterate over a table in order to get proper row & column values from a walker.
-		for ( const tableSlot of tableWalker ) {
-			if ( tableSlot.cell == tableCell ) {
-				const isHeading = tableSlot.row < headingRows || tableSlot.column < headingColumns;
-				const cellElementName = isHeading ? 'th' : 'td';
-
-				return options.asWidget ?
-					toWidgetEditable( writer.createEditableElement( cellElementName ), writer ) :
-					writer.createContainerElement( cellElementName );
-			}
-		}
-	};
+export function downcastCell(options = {}) {
+    return (tableCell, { writer }) => {
+        const tableRow = tableCell.parent;
+        const table = tableRow.parent;
+        const rowIndex = table.getChildIndex(tableRow);
+        const tableWalker = new TableWalker(table, { row: rowIndex });
+        const headingRows = table.getAttribute('headingRows') || 0;
+        const headingColumns = table.getAttribute('headingColumns') || 0;
+        let result = null;
+        // We need to iterate over a table in order to get proper row & column values from a walker.
+        for (const tableSlot of tableWalker) {
+            if (tableSlot.cell == tableCell) {
+                const isHeading = tableSlot.row < headingRows || tableSlot.column < headingColumns;
+                const cellElementName = isHeading ? 'th' : 'td';
+                result = options.asWidget ?
+                    toWidgetEditable(writer.createEditableElement(cellElementName), writer) :
+                    writer.createContainerElement(cellElementName);
+                break;
+            }
+        }
+        return result;
+    };
 }
-
 /**
  * Overrides paragraph inside table cell conversion.
  *
@@ -109,33 +90,28 @@ export function downcastCell( options = {} ) {
  * * For a single paragraph without attributes it returns `<span>` to simulate data table.
  * * For all other cases it returns `<p>` element.
  *
- * @param {Object} [options]
- * @param {Boolean} [options.asWidget] If set to `true`, the downcast conversion will produce a widget.
- * @returns {Function} Element creator.
+ * @param options.asWidget If set to `true`, the downcast conversion will produce a widget.
+ * @returns Element creator.
  */
-export function convertParagraphInTableCell( options = {} ) {
-	return ( modelElement, { writer } ) => {
-		if ( !modelElement.parent.is( 'element', 'tableCell' ) ) {
-			return;
-		}
-
-		if ( !isSingleParagraphWithoutAttributes( modelElement ) ) {
-			return;
-		}
-
-		if ( options.asWidget ) {
-			return writer.createContainerElement( 'span', { class: 'ck-table-bogus-paragraph' } );
-		} else {
-			// Using `<p>` in case there are some markers on it and transparentRendering will render it anyway.
-			const viewElement = writer.createContainerElement( 'p' );
-
-			writer.setCustomProperty( 'dataPipeline:transparentRendering', true, viewElement );
-
-			return viewElement;
-		}
-	};
+export function convertParagraphInTableCell(options = {}) {
+    return (modelElement, { writer }) => {
+        if (!modelElement.parent.is('element', 'tableCell')) {
+            return null;
+        }
+        if (!isSingleParagraphWithoutAttributes(modelElement)) {
+            return null;
+        }
+        if (options.asWidget) {
+            return writer.createContainerElement('span', { class: 'ck-table-bogus-paragraph' });
+        }
+        else {
+            // Using `<p>` in case there are some markers on it and transparentRendering will render it anyway.
+            const viewElement = writer.createContainerElement('p');
+            writer.setCustomProperty('dataPipeline:transparentRendering', true, viewElement);
+            return viewElement;
+        }
+    };
 }
-
 /**
  * Checks if given model `<paragraph>` is an only child of a parent (`<tableCell>`) and if it has any attribute set.
  *
@@ -143,36 +119,28 @@ export function convertParagraphInTableCell( options = {} ) {
  *
  * * If returned `true` - to a `<span class="ck-table-bogus-paragraph">`
  * * If returned `false` - to a `<p>`
- *
- * @param {module:engine/model/element~Element} modelElement
- * @returns {Boolean}
  */
-export function isSingleParagraphWithoutAttributes( modelElement ) {
-	const tableCell = modelElement.parent;
-
-	const isSingleParagraph = tableCell.childCount == 1;
-
-	return isSingleParagraph && !hasAnyAttribute( modelElement );
+export function isSingleParagraphWithoutAttributes(modelElement) {
+    const tableCell = modelElement.parent;
+    const isSingleParagraph = tableCell.childCount == 1;
+    return isSingleParagraph && !hasAnyAttribute(modelElement);
 }
-
-// Converts a given {@link module:engine/view/element~Element} to a table widget:
-// * Adds a {@link module:engine/view/element~Element#_setCustomProperty custom property} allowing to recognize the table widget element.
-// * Calls the {@link module:widget/utils~toWidget} function with the proper element's label creator.
-//
-// @param {module:engine/view/element~Element} viewElement
-// @param {module:engine/view/downcastwriter~DowncastWriter} writer An instance of the view writer.
-// @param {String} label The element's label. It will be concatenated with the table `alt` attribute if one is present.
-// @returns {module:engine/view/element~Element}
-function toTableWidget( viewElement, writer ) {
-	writer.setCustomProperty( 'table', true, viewElement );
-
-	return toWidget( viewElement, writer, { hasSelectionHandle: true } );
+/**
+ * Converts a given {@link module:engine/view/element~Element} to a table widget:
+ * * Adds a {@link module:engine/view/element~Element#_setCustomProperty custom property} allowing to recognize the table widget element.
+ * * Calls the {@link module:widget/utils~toWidget} function with the proper element's label creator.
+ *
+ * @param writer An instance of the view writer.
+ * @param label The element's label. It will be concatenated with the table `alt` attribute if one is present.
+ */
+function toTableWidget(viewElement, writer) {
+    writer.setCustomProperty('table', true, viewElement);
+    return toWidget(viewElement, writer, { hasSelectionHandle: true });
 }
-
-// Checks if an element has any attributes set.
-//
-// @param {module:engine/model/element~Element element
-// @returns {Boolean}
-function hasAnyAttribute( element ) {
-	return !![ ...element.getAttributeKeys() ].length;
+/**
+ * Checks if an element has any attributes set.
+ */
+function hasAnyAttribute(element) {
+    const iteratorItem = element.getAttributeKeys().next();
+    return !iteratorItem.done;
 }

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;