@ckeditor/ckeditor5-table 47.2.0 → 47.3.0-alpha.1

package/src/tableconfig.d.ts

@@ -23,7 +23,7 @@ import type { ColorOption, ColorPickerConfig } from 'ckeditor5/src/ui.js';
  */
 export interface TableConfig {
     /**
-     * Number of rows and columns to render by table heading when inserting new tables.
+     * Number of rows and columns to render by the table heading when inserting new tables.
      *
      * You can configure it like this:
      *
@@ -36,7 +36,7 @@ export interface TableConfig {
      * };
      * ```
      *
-     * Both rows and columns properties are optional defaulting to 0 (no heading).
+     * Both rows and columns properties are optional, defaulting to 0 (no heading).
      */
     defaultHeadings?: {
         rows?: number;
@@ -86,7 +86,7 @@ export interface TableConfig {
      */
     tableToolbar?: Array<ToolbarConfigItem>;
     /**
-     * The configuration of the table properties user interface (balloon). It allows to define:
+     * The configuration of the table properties user interface (balloon). It allows us to define:
      *
      * * The color palette for the table border color style field (`tableProperties.borderColors`),
      * * The color palette for the table background style field (`tableProperties.backgroundColors`).
@@ -130,9 +130,9 @@ export interface TableConfig {
      * {@link module:table/tableconfig~TablePropertiesOptions Read more about the supported properties.}
      *
      * **Note**: The `borderColors` and `backgroundColors` options do not impact the data loaded into the editor,
-     * i.e. they do not limit or filter the colors in the data. They are used only in the user interface
-     * allowing users to pick colors in a more convenient way. The `defaultProperties` option does impact the data.
-     * Default values will not be kept in the editor model.
+     * i.e., they do not limit or filter the colors in the data. They are used only in the user interface,
+     * allowing users to pick colors more conveniently. The `defaultProperties` option does impact the data.
+     * The editor model will not keep the default values.
      *
      * The default color palettes for the table background and the table border are the same
      * ({@link module:table/utils/ui/table-properties#defaultColors check out their content}).
@@ -144,7 +144,7 @@ export interface TableConfig {
      */
     tableProperties?: TablePropertiesConfig;
     /**
-     * The configuration of the table cell properties user interface (balloon). It allows to define:
+     * The configuration of the table cell properties user interface (balloon). It allows us to define:
      *
      * * The color palette for the cell border color style field (`tableCellProperties.borderColors`),
      * * The color palette for the cell background style field (`tableCellProperties.backgroundColors`).
@@ -187,11 +187,11 @@ export interface TableConfig {
      * {@link module:table/tableconfig~TablePropertiesOptions Read more about the supported properties.}
      *
      * **Note**: The `borderColors` and `backgroundColors` options do not impact the data loaded into the editor,
-     * i.e. they do not limit or filter the colors in the data. They are used only in the user interface
+     * i.e., they do not limit or filter the colors in the data. They are used only in the user interface,
      * allowing users to pick colors in a more convenient way. The `defaultProperties` option does impact the data.
-     * Default values will not be kept in the editor model.
+     * The editor model will not keep the default values.
      *
-     * The default color palettes for the cell background and the cell border are the same
+     * The default color palettes for the cell background and the cell border are identical
      * ({@link module:table/utils/ui/table-properties#defaultColors check out their content}).
      *
      * Both color palette configurations must follow the
@@ -225,9 +225,99 @@ export interface TableConfig {
  * The configuration of the table properties user interface (balloon).
  */
 export interface TablePropertiesConfig {
+    /**
+     * The color palette for the table border color picker.
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableProperties: {
+     * 		borderColors: [
+     * 			{
+     * 				color: 'hsl(0, 0%, 0%)',
+     * 				label: 'Black'
+     * 			},
+     * 			{
+     * 				color: 'hsl(0, 0%, 100%)',
+     * 				label: 'White',
+     * 				hasBorder: true
+     * 			}
+     * 		]
+     * 	}
+     * };
+     * ```
+     *
+     * **Note**: This configuration only affects the UI. It does not limit or filter the colors in the data.
+     *
+     * Defaults to {@link module:table/utils/ui/table-properties#defaultColors}.
+     *
+     * @see {@link module:table/tableconfig~TableColorConfig}
+     */
     borderColors?: TableColorConfig;
+    /**
+     * The color palette for the table background color picker.
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableProperties: {
+     * 		backgroundColors: [
+     * 			{
+     * 				color: 'hsl(0, 0%, 100%)',
+     * 				label: 'White',
+     * 				hasBorder: true
+     * 			},
+     * 			{
+     * 				color: 'hsl(120, 75%, 60%)',
+     * 				label: 'Green'
+     * 			}
+     * 		]
+     * 	}
+     * };
+     * ```
+     *
+     * **Note**: This configuration only affects the UI. It does not limit or filter the colors in the data.
+     *
+     * Defaults to {@link module:table/utils/ui/table-properties#defaultColors}.
+     *
+     * @see {@link module:table/tableconfig~TableColorConfig}
+     */
     backgroundColors?: TableColorConfig;
+    /**
+     * Default styles for newly created tables.
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableProperties: {
+     * 		defaultProperties: {
+     * 			borderStyle: 'dashed',
+     * 			borderColor: 'hsl(0, 0%, 90%)',
+     * 			borderWidth: '3px',
+     * 			alignment: 'left',
+     * 			width: '550px',
+     * 			height: '450px'
+     * 		}
+     * 	}
+     * }
+     * ```
+     *
+     * **Note**: The model does not store the default values. The editor will only keep values that differ from the defaults.
+     *
+     * See {@link module:table/tableconfig~TablePropertiesOptions} for the full list of properties.
+     */
     defaultProperties?: TablePropertiesOptions;
+    /**
+     * Configuration of the table alignment behavior in the editor output.
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableProperties: {
+     * 		alignment: {
+     * 			useInlineStyles: false // Use CSS classes instead of inline styles
+     * 		}
+     * 	}
+     * };
+     * ```
+     */
+    alignment?: TableAlignmentConfig;
     /**
      * Configuration of the color picker in the table properties balloon.
      *
@@ -276,8 +366,84 @@ export interface TablePropertiesOptions {
  * The configuration of the table cell properties user interface (balloon).
  */
 export interface TableCellPropertiesConfig {
+    /**
+     * The color palette for the table cell border color picker.
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableCellProperties: {
+     * 		borderColors: [
+     * 			{
+     * 				color: 'hsl(0, 0%, 0%)',
+     * 				label: 'Black'
+     * 			},
+     * 			{
+     * 				color: 'hsl(0, 0%, 100%)',
+     * 				label: 'White',
+     * 				hasBorder: true
+     * 			}
+     * 		]
+     * 	}
+     * };
+     * ```
+     *
+     * **Note**: This configuration only affects the UI. It does not limit or filter the colors in the data.
+     *
+     * Defaults to {@link module:table/utils/ui/table-properties#defaultColors}.
+     *
+     * @see {@link module:table/tableconfig~TableColorConfig}
+     */
     borderColors?: TableColorConfig;
+    /**
+     * The color palette for the table cell background color picker.
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableCellProperties: {
+     * 		backgroundColors: [
+     * 			{
+     * 				color: 'hsl(0, 0%, 100%)',
+     * 				label: 'White',
+     * 				hasBorder: true
+     * 			},
+     * 			{
+     * 				color: 'hsl(120, 75%, 60%)',
+     * 				label: 'Green'
+     * 			}
+     * 		]
+     * 	}
+     * };
+     * ```
+     *
+     * **Note**: This configuration only affects the UI. It does not limit or filter the colors in the data.
+     *
+     * Defaults to {@link module:table/utils/ui/table-properties#defaultColors}.
+     *
+     * @see {@link module:table/tableconfig~TableColorConfig}
+     */
     backgroundColors?: TableColorConfig;
+    /**
+     * Default styles for newly created table cells.
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableCellProperties: {
+     * 		defaultProperties: {
+     * 			borderStyle: 'dashed',
+     * 			borderColor: 'hsl(0, 0%, 90%)',
+     * 			borderWidth: '3px',
+     * 			horizontalAlignment: 'center',
+     * 			verticalAlignment: 'middle',
+     * 			padding: '10px'
+     * 		}
+     * 	}
+     * }
+     * ```
+     *
+     * **Note**: The model does not store the default values. The editor will only keep values that differ from the defaults.
+     *
+     * See {@link module:table/tableconfig~TableCellPropertiesOptions} for the full list of properties.
+     */
     defaultProperties?: TableCellPropertiesOptions;
     /**
      * Configuration of the color picker in the table cell properties balloon.
@@ -433,3 +599,14 @@ export interface TableCaptionConfig {
  * The type of the table.
  */
 export type TableType = 'content' | 'layout';
+export interface TableAlignmentConfig {
+    /**
+     * Whether to use inline styles for table alignment in the editor output.
+     *
+     * * When `true` (default), the alignment is rendered as inline styles.
+     * * When `false`, the alignment is rendered as CSS classes.
+     *
+     * @default true
+     */
+    useInlineStyles?: boolean;
+}

package/src/tableediting.d.ts

@@ -41,6 +41,11 @@ export declare class TableEditing extends Plugin {
      * Registers downcast handler for the additional table slot.
      */
     registerAdditionalSlot(slotHandler: TableConversionAdditionalSlot): void;
+    /**
+     * Adds converters for plain table output. These converters are used either when the `PlainTableOutput` plugin is loaded
+     * or when content is processed by the clipboard pipeline, ensuring that pasted tables are not wrapped in a <figure> element.
+     */
+    private _addPlainTableOutputConverters;
 }
 /**
  * By default, only the `tableRow` elements from the `table` model are downcast inside the `<table>` and

package/src/tableediting.js

@@ -7,7 +7,7 @@
  */
 import { Plugin } from 'ckeditor5/src/core.js';
 import { upcastTable, ensureParagraphInTableCell, skipEmptyTableRow, upcastTableFigure } from './converters/upcasttable.js';
-import { convertParagraphInTableCell, downcastCell, downcastRow, downcastTable } from './converters/downcast.js';
+import { convertParagraphInTableCell, downcastCell, downcastRow, downcastTable, downcastTableBorderAndBackgroundAttributes, convertPlainTable, convertPlainTableCaption } from './converters/downcast.js';
 import { InsertTableCommand } from './commands/inserttablecommand.js';
 import { InsertRowCommand } from './commands/insertrowcommand.js';
 import { InsertColumnCommand } from './commands/insertcolumncommand.js';
@@ -148,6 +148,8 @@ export class TableEditing extends Plugin {
             model: { key: 'rowspan', value: upcastCellSpan('rowspan') },
             view: 'rowspan'
         });
+        // Plain table output converters (also used in the clipboard pipeline).
+        this._addPlainTableOutputConverters();
         // Define the config.
         editor.config.define('table.defaultHeadings.rows', 0);
         editor.config.define('table.defaultHeadings.columns', 0);
@@ -183,6 +185,31 @@ export class TableEditing extends Plugin {
     registerAdditionalSlot(slotHandler) {
         this._additionalSlots.push(slotHandler);
     }
+    /**
+     * Adds converters for plain table output. These converters are used either when the `PlainTableOutput` plugin is loaded
+     * or when content is processed by the clipboard pipeline, ensuring that pasted tables are not wrapped in a <figure> element.
+     */
+    _addPlainTableOutputConverters() {
+        const editor = this.editor;
+        // Override default table data downcast converter.
+        editor.conversion.for('dataDowncast').elementToStructure({
+            model: 'table',
+            view: convertPlainTable(editor),
+            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: convertPlainTableCaption(editor),
+                converterPriority: 'high'
+            });
+        }
+        // Handle border-style, border-color, border-width and background-color table attributes.
+        if (editor.plugins.has('TableProperties')) {
+            downcastTableBorderAndBackgroundAttributes(editor);
+        }
+    }
 }
 /**
  * Returns fixed colspan and rowspan attrbutes values.

package/src/tablelayout/tablelayoutediting.js

@@ -80,7 +80,7 @@ export class TableLayoutEditing extends Plugin {
         const { editor } = this;
         const { conversion } = editor;
         const preferredExternalTableType = editor.config.get('table.tableLayout.preferredExternalTableType');
-        conversion.for('upcast').add(upcastLayoutTable(preferredExternalTableType));
+        conversion.for('upcast').add(upcastLayoutTable(editor, preferredExternalTableType));
         conversion.for('dataDowncast').add(dataDowncastLayoutTable());
         conversion.for('editingDowncast').attributeToAttribute({
             model: {
@@ -176,9 +176,10 @@ export class TableLayoutEditing extends Plugin {
  *
  * This conversion helper overrides the default table converter to meet table layout conditions.
  *
+ * @param editor Editor instance.
  * @returns Conversion helper.
  */
-function upcastLayoutTable(preferredExternalTableType) {
+function upcastLayoutTable(editor, preferredExternalTableType) {
     return (dispatcher) => {
         dispatcher.on('element:table', (evt, data, conversionApi) => {
             const viewTable = data.viewItem;
@@ -197,6 +198,11 @@ function upcastLayoutTable(preferredExternalTableType) {
             conversionApi.consumable.consume(viewTable, { name: true });
             conversionApi.consumable.consume(viewTable, { attributes: ['role'] });
             conversionApi.consumable.consume(viewTable, { classes: ['layout-table'] });
+            // Layout tables have no border, so it's equitable to consume the border="0" attribute.
+            if (editor.config.get('experimentalFlags.upcastTableBorderZeroAttributes') &&
+                viewTable.getAttribute('border') === '0') {
+                conversionApi.consumable.consume(viewTable, { attributes: ['border'] });
+            }
             // Get all rows from the table and convert them.
             // While looping over the children of `<table>` we can be sure that first will be `<tbody>`
             // and optionally `<thead>` and `<tfoot>`, and in these elements are the table rows found.