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

package/src/plaintableoutput.js

@@ -2,150 +2,122 @@
  * @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/plaintableoutput
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import Table from './table';
-
 /**
  * The plain table output feature.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class PlainTableOutput extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'PlainTableOutput';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ Table ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	init() {
-		const editor = this.editor;
-
-		// Override default table data downcast converter.
-		editor.conversion.for( 'dataDowncast' ).elementToStructure( {
-			model: 'table',
-			view: downcastTableElement,
-			converterPriority: 'high'
-		} );
-
-		// Make sure table <caption> is downcasted into <caption> in the data pipeline when necessary.
-		if ( editor.plugins.has( 'TableCaption' ) ) {
-			editor.conversion.for( 'dataDowncast' ).elementToElement( {
-				model: 'caption',
-				view: ( modelElement, { writer } ) => {
-					if ( modelElement.parent.name === 'table' ) {
-						return writer.createContainerElement( 'caption' );
-					}
-				},
-				converterPriority: 'high'
-			} );
-		}
-
-		// Handle border-style, border-color, border-width and background-color table attributes.
-		if ( editor.plugins.has( 'TableProperties' ) ) {
-			downcastTableBorderAndBackgroundAttributes( editor );
-		}
-	}
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'PlainTableOutput';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [Table];
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        // Override default table data downcast converter.
+        editor.conversion.for('dataDowncast').elementToStructure({
+            model: 'table',
+            view: downcastTableElement,
+            converterPriority: 'high'
+        });
+        // Make sure table <caption> is downcasted into <caption> in the data pipeline when necessary.
+        if (editor.plugins.has('TableCaption')) {
+            editor.conversion.for('dataDowncast').elementToElement({
+                model: 'caption',
+                view: (modelElement, { writer }) => {
+                    if (modelElement.parent.name === 'table') {
+                        return writer.createContainerElement('caption');
+                    }
+                },
+                converterPriority: 'high'
+            });
+        }
+        // Handle border-style, border-color, border-width and background-color table attributes.
+        if (editor.plugins.has('TableProperties')) {
+            downcastTableBorderAndBackgroundAttributes(editor);
+        }
+    }
 }
-
-// The plain table downcast converter callback.
-//
-// @private
-// @param {module:engine/model/element~Element} Table model element.
-// @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi The conversion API object.
-// @returns {module:engine/view/containerelement~ContainerElement} Created element.
-function downcastTableElement( table, { writer } ) {
-	const headingRows = table.getAttribute( 'headingRows' ) || 0;
-
-	// Table head rows slot.
-	const headRowsSlot = writer.createSlot( element =>
-		element.is( 'element', 'tableRow' ) && element.index < headingRows
-	);
-
-	// Table body rows slot.
-	const bodyRowsSlot = writer.createSlot( element =>
-		element.is( 'element', 'tableRow' ) && element.index >= headingRows
-	);
-
-	// Table children slot.
-	const childrenSlot = writer.createSlot( element => !element.is( 'element', 'tableRow' ) );
-
-	// Table <thead> element with all the heading rows.
-	const theadElement = writer.createContainerElement( 'thead', null, headRowsSlot );
-
-	// Table <tbody> element with all the body rows.
-	const tbodyElement = writer.createContainerElement( 'tbody', null, bodyRowsSlot );
-
-	// Table contents element containing <thead> and <tbody> when necessary.
-	const tableContentElements = [];
-
-	if ( headingRows ) {
-		tableContentElements.push( theadElement );
-	}
-
-	if ( headingRows < table.childCount ) {
-		tableContentElements.push( tbodyElement );
-	}
-
-	// Create table structure.
-	//
-	// <table>
-	//    {children-slot-like-caption}
-	//    <thead>
-	//        {table-head-rows-slot}
-	//    </thead>
-	//    <tbody>
-	//        {table-body-rows-slot}
-	//    </tbody>
-	// </table>
-	return writer.createContainerElement( 'table', null, [ childrenSlot, ...tableContentElements ] );
+/**
+ * The plain table downcast converter callback.
+ *
+ * @param table Table model element.
+ * @param conversionApi The conversion API object.
+ * @returns Created element.
+ */
+function downcastTableElement(table, { writer }) {
+    const headingRows = table.getAttribute('headingRows') || 0;
+    // Table head rows slot.
+    const headRowsSlot = writer.createSlot((element) => element.is('element', 'tableRow') && element.index < headingRows);
+    // Table body rows slot.
+    const bodyRowsSlot = writer.createSlot((element) => element.is('element', 'tableRow') && element.index >= headingRows);
+    // Table children slot.
+    const childrenSlot = writer.createSlot((element) => !element.is('element', 'tableRow'));
+    // Table <thead> element with all the heading rows.
+    const theadElement = writer.createContainerElement('thead', null, headRowsSlot);
+    // Table <tbody> element with all the body rows.
+    const tbodyElement = writer.createContainerElement('tbody', null, bodyRowsSlot);
+    // Table contents element containing <thead> and <tbody> when necessary.
+    const tableContentElements = [];
+    if (headingRows) {
+        tableContentElements.push(theadElement);
+    }
+    if (headingRows < table.childCount) {
+        tableContentElements.push(tbodyElement);
+    }
+    // Create table structure.
+    //
+    // <table>
+    //    {children-slot-like-caption}
+    //    <thead>
+    //        {table-head-rows-slot}
+    //    </thead>
+    //    <tbody>
+    //        {table-body-rows-slot}
+    //    </tbody>
+    // </table>
+    return writer.createContainerElement('table', null, [childrenSlot, ...tableContentElements]);
 }
-
-// Register table border and background attributes converters.
-//
-// @private
-// @param {module:core/editor/editor~Editor} editor
-function downcastTableBorderAndBackgroundAttributes( editor ) {
-	const modelAttributes = {
-		'border-width': 'tableBorderWidth',
-		'border-color': 'tableBorderColor',
-		'border-style': 'tableBorderStyle',
-		'background-color': 'tableBackgroundColor'
-	};
-
-	for ( const [ styleName, modelAttribute ] of Object.entries( modelAttributes ) ) {
-		editor.conversion.for( 'dataDowncast' ).add( dispatcher => {
-			return dispatcher.on( `attribute:${ modelAttribute }:table`, ( evt, data, conversionApi ) => {
-				const { item, attributeNewValue } = data;
-				const { mapper, writer } = conversionApi;
-
-				if ( !conversionApi.consumable.consume( item, evt.name ) ) {
-					return;
-				}
-
-				const table = mapper.toViewElement( item );
-
-				if ( attributeNewValue ) {
-					writer.setStyle( styleName, attributeNewValue, table );
-				} else {
-					writer.removeStyle( styleName, table );
-				}
-			}, { priority: 'high' } );
-		} );
-	}
+/**
+ * Register table border and background attributes converters.
+ */
+function downcastTableBorderAndBackgroundAttributes(editor) {
+    const modelAttributes = {
+        'border-width': 'tableBorderWidth',
+        'border-color': 'tableBorderColor',
+        'border-style': 'tableBorderStyle',
+        'background-color': 'tableBackgroundColor'
+    };
+    for (const [styleName, modelAttribute] of Object.entries(modelAttributes)) {
+        editor.conversion.for('dataDowncast').add(dispatcher => {
+            return dispatcher.on(`attribute:${modelAttribute}:table`, (evt, data, conversionApi) => {
+                const { item, attributeNewValue } = data;
+                const { mapper, writer } = conversionApi;
+                if (!conversionApi.consumable.consume(item, evt.name)) {
+                    return;
+                }
+                const table = mapper.toViewElement(item);
+                if (attributeNewValue) {
+                    writer.setStyle(styleName, attributeNewValue, table);
+                }
+                else {
+                    writer.removeStyle(styleName, table);
+                }
+            }, { priority: 'high' });
+        });
+    }
 }

package/src/table.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @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/table
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import '../theme/table.css';
+/**
+ * The table plugin.
+ *
+ * For a detailed overview, check the {@glink features/table Table feature documentation}.
+ *
+ * This is a "glue" plugin that loads the following table features:
+ *
+ * * {@link module:table/tableediting~TableEditing editing feature},
+ * * {@link module:table/tableselection~TableSelection selection feature},
+ * * {@link module:table/tablekeyboard~TableKeyboard keyboard navigation feature},
+ * * {@link module:table/tablemouse~TableMouse mouse selection feature},
+ * * {@link module:table/tableclipboard~TableClipboard clipboard feature},
+ * * {@link module:table/tableui~TableUI UI feature}.
+ */
+export default class Table extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Table';
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [Table.pluginName]: Table;
+    }
+}

package/src/table.js

@@ -2,23 +2,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/table
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import { Widget } from 'ckeditor5/src/widget';
-
 import TableEditing from './tableediting';
 import TableUI from './tableui';
 import TableSelection from './tableselection';
 import TableClipboard from './tableclipboard';
 import TableKeyboard from './tablekeyboard';
 import TableMouse from './tablemouse';
-
 import '../theme/table.css';
-
 /**
  * The table plugin.
  *
@@ -32,89 +27,18 @@ import '../theme/table.css';
  * * {@link module:table/tablemouse~TableMouse mouse selection feature},
  * * {@link module:table/tableclipboard~TableClipboard clipboard feature},
  * * {@link module:table/tableui~TableUI UI feature}.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class Table extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ TableEditing, TableUI, TableSelection, TableMouse, TableKeyboard, TableClipboard, Widget ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'Table';
-	}
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [TableEditing, TableUI, TableSelection, TableMouse, TableKeyboard, TableClipboard, Widget];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'Table';
+    }
 }
-
-/**
- * The configuration of the table feature. Used by the table feature in the `@ckeditor/ckeditor5-table` package.
- *
- *		ClassicEditor
- *			.create( editorElement, {
- * 				table: ... // Table feature options.
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
- *
- * @interface TableConfig
- */
-
-/**
- * The configuration of the {@link module:table/table~Table} feature.
- *
- * Read more in {@link module:table/table~TableConfig}.
- *
- * @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).
- *
- *		const colors = [
- *			{
- *				color: 'hsl(0, 0%, 60%)',
- *				label: 'Grey'
- *			},
- *			'hsl(0, 0%, 80%)',
- *			{
- *				color: 'hsl(0, 0%, 90%)',
- *				label: 'Light grey'
- *			},
- *			{
- *				color: 'hsl(0, 0%, 100%)',
- *				label: 'White',
- *				hasBorder: true
- *			},
- *			'#FF0000'
- *		]
- *
- * Usually used as a configuration parameter, for instance in
- * {@link module:table/table~TableConfig#tableProperties `config.table.tableProperties`}
- * or {@link module:table/table~TableConfig#tableCellProperties `config.table.tableCellProperties`}.
- *
- * @typedef {Array.<String|Object>} module:table/table~TableColorConfig
- */

package/src/tablecaption/tablecaptionediting.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @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/tablecaption/tablecaptionediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core';
+import { Element } from 'ckeditor5/src/engine';
+/**
+ * The table caption editing plugin.
+ */
+export default class TableCaptionEditing extends Plugin {
+    /**
+     * 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}.
+     */
+    private _savedCaptionsMap;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'TableCaptionEditing';
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Returns the saved {@link module:engine/model/element~Element#toJSON JSONified} caption
+     * of a table model element.
+     *
+     * See {@link #_saveCaption}.
+     *
+     * @internal
+     * @param tableModelElement The model element the caption should be returned for.
+     * @returns The model caption element or `null` if there is none.
+     */
+    _getSavedCaption(tableModelElement: Element): Element | 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}.
+     *
+     * @internal
+     * @param tableModelElement The model element the caption is saved for.
+     * @param caption The caption model element to be saved.
+     */
+    _saveCaption(tableModelElement: Element, caption: Element): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [TableCaptionEditing.pluginName]: TableCaptionEditing;
+    }
+}