Add table cell type support (CKEditor v47.x)

.changelog/20251126125431_ck_19431.md

@@ -0,0 +1,11 @@
+---
+type: Fix
+scope:
+  - ckeditor5-table
+closes:
+  - https://github.com/ckeditor/ckeditor5/issues/19431
+---
+
+Add experimental fix for incorrect table rows marking and moving as header row when preceding rows are not header rows.
+
+This change needs to be enabled by setting `experimentalFlags.tableCellTypeSupport` to `true`. In the next major release, this flag will be removed and the fix will be enabled by default.

packages/ckeditor5-engine/tests/model/operation/transform/utils.js

@@ -33,7 +33,7 @@ export class Client {
 		this.name = name;
 	}
 
-	init() {
+	init( editorConfig = {} ) {
 		return ModelTestEditor.create( {
 			// Typing is needed for delete command.
 			// UndoEditing is needed for undo command.
@@ -42,7 +42,8 @@ export class Client {
 			plugins: [
 				Typing, Paragraph, LegacyListEditing, UndoEditing, BlockQuoteEditing, HeadingEditing, BoldEditing, TableEditing,
 				ImageBlockEditing
-			]
+			],
+			...editorConfig
 		} ).then( editor => {
 			this.editor = editor;
 			this.document = editor.model.document;
@@ -87,15 +88,19 @@ export class Client {
 		this.syncedVersion = this.document.version;
 	}
 
-	setSelection( start, end ) {
+	setSelection( start, end, { bufferOperations } = {} ) {
 		if ( !end ) {
 			end = start.slice();
 		}
 
 		const startPos = this._getPosition( start );
 		const endPos = this._getPosition( end );
 
-		this.editor.model.document.selection._setTo( new ModelRange( startPos, endPos ) );
+		if ( bufferOperations ) {
+			this._processAction( 'setSelection', new ModelRange( startPos, endPos ) );
+		} else {
+			this.editor.model.document.selection._setTo( new ModelRange( startPos, endPos ) );
+		}
 	}
 
 	insert( itemString, path ) {
@@ -243,6 +248,10 @@ export class Client {
 			return this._getPositionFromSelection( type );
 		}
 
+		if ( path instanceof ModelPosition ) {
+			return path.clone();
+		}
+
 		return new ModelPosition( this.document.getRoot(), path );
 	}
 
@@ -272,13 +281,13 @@ export class Client {
 		bufferOperations( operations, this );
 	}
 
-	static get( clientName ) {
+	static get( clientName, { editorConfig } = {} ) {
 		const client = new Client( clientName );
 		client.orderNumber = clients.size;
 
 		clients.add( client );
 
-		return client.init();
+		return client.init( editorConfig ?? {} );
 	}
 }
 

packages/ckeditor5-table/lang/contexts.json

@@ -23,6 +23,9 @@
 	"Table toolbar": "The label used by assistive technologies describing a table toolbar attached to a table widget.",
 	"Table properties": "The label describing the form allowing to specify the properties of a selected table.",
 	"Cell properties": "The label describing the form allowing to specify the properties of a selected table cell.",
+	"Cell type": "The label for the dropdown that allows configuring the type of a table cell (data or header).",
+	"Data cell": "The label for the dropdown option for a data table cell.",
+	"Header cell": "The label for the dropdown option for a header table cell.",
 	"Border": "The label describing a group of border–related form fields (border style, color, etc.).",
 	"Style": "The label for the dropdown that allows configuring the border style of a table or a table cell.",
 	"Width": "The label for the input that allows configuring the width of a table or a table cell or the width of a border.",

packages/ckeditor5-table/src/augmentation.ts

@@ -64,7 +64,8 @@ import type {
 	TableBorderStyleCommand,
 	TableBorderWidthCommand,
 	TableHeightCommand,
-	TableWidthCommand
+	TableWidthCommand,
+	TableCellTypeCommand
 } from './index.js';
 
 declare module '@ckeditor/ckeditor5-engine' {
@@ -88,6 +89,15 @@ declare module '@ckeditor/ckeditor5-engine' {
 		 * This will be enabled by default in the future CKEditor 5 releases.
 		 */
 		useExtendedTableBlockAlignment?: boolean;
+
+		/**
+		 * When enabled, the
+		 * {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing table cell properties feature}
+		 * will introduce a special selector for table cell types (i.e. header and data cells) in the cell properties dropdown.
+		 *
+		 * This will be enabled by default in the future CKEditor 5 releases.
+		 */
+		tableCellTypeSupport?: boolean;
 	}
 }
 
@@ -159,6 +169,7 @@ declare module '@ckeditor/ckeditor5-core' {
 		tableCellPadding: TableCellPaddingCommand;
 		tableCellVerticalAlignment: TableCellVerticalAlignmentCommand;
 		tableCellWidth: TableCellWidthCommand;
+		tableCellType: TableCellTypeCommand;
 		tableAlignment: TableAlignmentCommand;
 		tableBackgroundColor: TableBackgroundColorCommand;
 		tableBorderColor: TableBorderColorCommand;

packages/ckeditor5-table/src/commands/setheadercolumncommand.ts

@@ -10,10 +10,7 @@
 import { Command } from 'ckeditor5/src/core.js';
 import { type TableUtils } from '../tableutils.js';
 
-import {
-	isHeadingColumnCell,
-	updateNumericAttribute
-} from '../utils/common.js';
+import { isHeadingColumnCell } from '../utils/common.js';
 import { getHorizontallyOverlappingCells, splitVertically } from '../utils/structure.js';
 
 /**
@@ -97,7 +94,7 @@ export class SetHeaderColumnCommand extends Command {
 				}
 			}
 
-			updateNumericAttribute( 'headingColumns', headingColumnsToSet, table, writer, 0 );
+			tableUtils.setHeadingColumnsCount( writer, table, headingColumnsToSet );
 		} );
 	}
 }

packages/ckeditor5-table/src/commands/setheaderrowcommand.ts

@@ -11,7 +11,6 @@ import { Command } from 'ckeditor5/src/core.js';
 import type { ModelElement } from 'ckeditor5/src/engine.js';
 import { type TableUtils } from '../tableutils.js';
 
-import { updateNumericAttribute } from '../utils/common.js';
 import { getVerticallyOverlappingCells, splitHorizontally } from '../utils/structure.js';
 
 /**
@@ -97,7 +96,7 @@ export class SetHeaderRowCommand extends Command {
 				}
 			}
 
-			updateNumericAttribute( 'headingRows', headingRowsToSet, table, writer, 0 );
+			tableUtils.setHeadingRowsCount( writer, table, headingRowsToSet );
 		} );
 	}
 

packages/ckeditor5-table/src/converters/downcast.ts

@@ -20,11 +20,12 @@ import type {
 	DowncastConversionApi
 } from 'ckeditor5/src/engine.js';
 
-import { TableWalker } from './../tablewalker.js';
 import { type TableUtils } from '../tableutils.js';
 import type { TableConversionAdditionalSlot } from '../tableediting.js';
 import { downcastTableAlignmentConfig, type TableAlignmentValues } from './tableproperties.js';
 import { getNormalizedDefaultTableProperties } from '../utils/table-properties.js';
+import { isTableCellTypeEnabled } from '../utils/common.js';
+import { TableWalker } from '../tablewalker.js';
 
 /**
  * Model table element to view table element conversion helper.
@@ -106,11 +107,29 @@ export function downcastRow(): DowncastElementCreatorFunction {
  * and `<td>` otherwise.
  *
  * @internal
+ * @param editor The editor instance.
  * @param options.asWidget If set to `true`, the downcast conversion will produce a widget.
  * @returns Element creator.
  */
-export function downcastCell( options: { asWidget?: boolean } = {} ): DowncastElementCreatorFunction {
+export function downcastCell( editor: Editor, options: { asWidget?: boolean } = {} ): DowncastElementCreatorFunction {
+	let cellTypeEnabled: boolean | null = null;
+
 	return ( tableCell, { writer } ) => {
+		cellTypeEnabled ??= isTableCellTypeEnabled( editor );
+
+		// If the table cell type feature is enabled, then we can simply check the cell type attribute.
+		if ( cellTypeEnabled ) {
+			const cellElementName: 'td' | 'th' = (
+				tableCell.getAttribute( 'tableCellType' ) === 'header' ?
+					'th' :
+					'td'
+			);
+
+			return createCellElement( writer, cellElementName );
+		}
+
+		// If the the table cell type feature is not enabled, we should iterate through the table structure
+		// to determine whether the cell is in the heading section.
 		const tableRow = tableCell.parent as ModelElement;
 		const table = tableRow.parent as ModelElement;
 		const rowIndex = table.getChildIndex( tableRow )!;
@@ -125,17 +144,22 @@ export function downcastCell( options: { asWidget?: boolean } = {} ): DowncastEl
 		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, { withAriaRole: false } ) :
-					writer.createContainerElement( cellElementName );
+				result = createCellElement( writer, isHeading ? 'th' : 'td' );
 				break;
 			}
 		}
 
 		return result;
 	};
+
+	function createCellElement( writer: ViewDowncastWriter, name: string ) {
+		return (
+			options.asWidget ?
+				toWidgetEditable( writer.createEditableElement( name ), writer, { withAriaRole: false } ) :
+				writer.createContainerElement( name )
+		);
+	}
 }
 
 /**

packages/ckeditor5-table/src/converters/upcasttable.ts

@@ -8,6 +8,7 @@
  */
 
 import type { ModelElement, UpcastDispatcher, UpcastElementEvent, ViewElement, ViewNode } from 'ckeditor5/src/engine.js';
+import type { Editor } from 'ckeditor5/src/core.js';
 
 import { createEmptyTableCell } from '../utils/common.js';
 import { getViewTableFromWrapper } from '../utils/structure.js';
@@ -81,7 +82,9 @@ export function upcastTableFigure() {
  * @returns Conversion helper.
  * @internal
  */
-export function upcastTable() {
+export function upcastTable( editor: Editor ) {
+	const ignoreHeaderRowMoveIfNormalRowsBefore = !!editor.config.get( 'experimentalFlags.tableCellTypeSupport' );
+
 	return ( dispatcher: UpcastDispatcher ): void => {
 		dispatcher.on<UpcastElementEvent>( 'element:table', ( evt, data, conversionApi ) => {
 			const viewTable = data.viewItem;
@@ -91,7 +94,7 @@ export function upcastTable() {
 				return;
 			}
 
-			const { rows, headingRows, headingColumns } = scanTable( viewTable );
+			const { rows, headingRows, headingColumns } = scanTable( viewTable, ignoreHeaderRowMoveIfNormalRowsBefore );
 
 			// Only set attributes if values is greater then 0.
 			const attributes: { headingColumns?: number; headingRows?: number } = {};
@@ -200,10 +203,16 @@ export function ensureParagraphInTableCell( elementName: string ) {
  * 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.
+ *
+ * @param viewTable The view table element.
+ * @param ignoreHeaderRowMoveIfNormalRowsBefore If set to `true`, then heading rows detection will stop
+ * once a normal row is found between heading rows. If set to `false`, then heading rows will be detected
+ * even if normal rows are between them.
+ * @returns The table metadata.
  */
-function scanTable( viewTable: ViewElement ) {
-	let headingRows = 0;
+function scanTable( viewTable: ViewElement, ignoreHeaderRowMoveIfNormalRowsBefore: boolean ) {
 	let headingColumns: number | undefined = undefined;
+	let shouldAccumulateHeadingRows: boolean | null = null;
 
 	// The `<tbody>` and `<thead>` sections in the DOM do not have to be in order `<thead>` -> `<tbody>` and there might be more than one
 	// of them.
@@ -232,8 +241,9 @@ function scanTable( viewTable: ViewElement ) {
 		}
 
 		// Save the first `<thead>` in the table as table header - all other ones will be converted to table body rows.
-		if ( tableChild.name === 'thead' && !firstTheadElement ) {
-			firstTheadElement = tableChild;
+		if ( tableChild.name === 'thead' ) {
+			shouldAccumulateHeadingRows = null;
+			firstTheadElement ||= tableChild;
 		}
 
 		// There might be some extra empty text nodes between the `<tr>`s.
@@ -261,13 +271,17 @@ function scanTable( viewTable: ViewElement ) {
 					// of the cell span from the previous row.
 					// Issue: https://github.com/ckeditor/ckeditor5/issues/17556
 					( maxPrevColumns === null || trColumns.length === maxPrevColumns ) &&
-					trColumns.every( e => e.is( 'element', 'th' ) )
+					trColumns.every( e => e.is( 'element', 'th' ) ) &&
+					// If there is at least one "normal" table row between heading rows, then stop accumulating heading rows.
+					// However, if flag `ignoreHeaderRowMoveIfNormalRowsBefore` is set to `false`, then ignore this rule.
+					( !ignoreHeaderRowMoveIfNormalRowsBefore || shouldAccumulateHeadingRows === null || shouldAccumulateHeadingRows )
 				)
 			) {
-				headingRows++;
 				headRows.push( tr );
+				shouldAccumulateHeadingRows = true;
 			} else {
 				bodyRows.push( tr );
+				shouldAccumulateHeadingRows = false;
 			}
 
 			// We use the maximum number of columns to avoid false positives when detecting
@@ -293,13 +307,13 @@ function scanTable( viewTable: ViewElement ) {
 		}
 
 		// Update headingColumns.
-		if ( !headingColumns || index < headingColumns ) {
+		if ( headingColumns === undefined || index < headingColumns ) {
 			headingColumns = index;
 		}
 	}
 
 	return {
-		headingRows,
+		headingRows: headRows.length,
 		headingColumns: headingColumns || 0,
 		rows: [ ...headRows, ...bodyRows ]
 	};

packages/ckeditor5-table/src/index.ts

@@ -72,7 +72,6 @@ export { TableCellHeightCommand } from './tablecellproperties/commands/tablecell
 export { TableCellHorizontalAlignmentCommand } from './tablecellproperties/commands/tablecellhorizontalalignmentcommand.js';
 export { TableCellPaddingCommand } from './tablecellproperties/commands/tablecellpaddingcommand.js';
 export { TableCellVerticalAlignmentCommand } from './tablecellproperties/commands/tablecellverticalalignmentcommand.js';
-export { TableCellPropertyCommand } from './tablecellproperties/commands/tablecellpropertycommand.js';
 export { TableCellWidthCommand } from './tablecellwidth/commands/tablecellwidthcommand.js';
 export { TableAlignmentCommand } from './tableproperties/commands/tablealignmentcommand.js';
 export { TableBackgroundColorCommand } from './tableproperties/commands/tablebackgroundcolorcommand.js';
@@ -82,6 +81,11 @@ export { TableBorderWidthCommand } from './tableproperties/commands/tableborderw
 export { TableHeightCommand } from './tableproperties/commands/tableheightcommand.js';
 export { TableWidthCommand } from './tableproperties/commands/tablewidthcommand.js';
 export { TablePropertyCommand, type TablePropertyCommandExecuteOptions } from './tableproperties/commands/tablepropertycommand.js';
+export { TableCellTypeCommand, type TableCellType } from './tablecellproperties/commands/tablecelltypecommand.js';
+export {
+	TableCellPropertyCommand,
+	type TableCellPropertyCommandAfterExecuteEvent
+} from './tablecellproperties/commands/tablecellpropertycommand.js';
 
 export type { ViewDocumentTableMouseMoveEvent, ViewDocumentTableMouseLeaveEvent } from './tablemouse/mouseeventsobserver.js';
 

packages/ckeditor5-table/src/tablecellproperties/commands/tablecellpropertycommand.ts

@@ -8,7 +8,7 @@
  */
 
 import { Command, type Editor } from 'ckeditor5/src/core.js';
-import type { ModelElement, Batch } from 'ckeditor5/src/engine.js';
+import type { ModelElement, Batch, ModelWriter } from 'ckeditor5/src/engine.js';
 import { type TableUtils } from '../../tableutils.js';
 import { getSelectionAffectedTable } from '../../utils/common.js';
 
@@ -55,6 +55,10 @@ export class TableCellPropertyCommand extends Command {
 
 		// Hardcoded defaults for layout table.
 		switch ( attributeName ) {
+			case 'tableCellType':
+				this._defaultLayoutTableValue = 'data';
+				break;
+
 			case 'tableCellBorderStyle':
 				this._defaultLayoutTableValue = 'none';
 				break;
@@ -113,6 +117,12 @@ export class TableCellPropertyCommand extends Command {
 			} else {
 				tableCells.forEach( tableCell => writer.removeAttribute( this.attributeName, tableCell ) );
 			}
+
+			this.fire<TableCellPropertyCommandAfterExecuteEvent>( 'afterExecute', {
+				writer,
+				tableCells,
+				valueToSet
+			} );
 		} );
 	}
 
@@ -156,3 +166,17 @@ export class TableCellPropertyCommand extends Command {
 		return everyCellHasAttribute ? firstCellValue : undefined;
 	}
 }
+
+/**
+ * Fired after the the {@link module:table/tablecellproperties/commands/tablecellpropertycommand~TableCellPropertyCommand}
+ *
+ * @eventName ~TableCellPropertyCommand#afterExecute
+ */
+export type TableCellPropertyCommandAfterExecuteEvent = {
+	name: 'afterExecute';
+	args: [ {
+		writer: ModelWriter;
+		tableCells: Array<ModelElement>;
+		valueToSet: unknown;
+	} ];
+};