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

package/src/tablecellproperties/tablecellpropertiesediting.js

@@ -2,14 +2,11 @@
  * @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/tablecellproperties/tablecellpropertiesediting
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import { addBorderRules, addPaddingRules, addBackgroundRules } from 'ckeditor5/src/engine';
-
 import { downcastAttributeToStyle, upcastBorderStyles } from './../converters/tableproperties';
 import TableEditing from './../tableediting';
 import TableCellWidthEditing from '../tablecellwidth/tablecellwidthediting';
@@ -23,10 +20,8 @@ import TableCellBorderColorCommand from './commands/tablecellbordercolorcommand'
 import TableCellBorderWidthCommand from './commands/tablecellborderwidthcommand';
 import { getNormalizedDefaultProperties } from '../utils/table-properties';
 import { enableProperty } from '../utils/common';
-
 const VALIGN_VALUES_REG_EXP = /^(top|middle|bottom)$/;
 const ALIGN_VALUES_REG_EXP = /^(left|center|right|justify)$/;
-
 /**
  * The table cell properties editing feature.
  *
@@ -45,240 +40,202 @@ const ALIGN_VALUES_REG_EXP = /^(left|center|right|justify)$/;
  * - cell padding: the `'tableCellPadding'` command
  * - horizontal and vertical alignment: the `'tableCellHorizontalAlignment'` and `'tableCellVerticalAlignment'` commands
  * - width and height: the `'tableCellWidth'` and `'tableCellHeight'` commands
- *
- * @extends module:core/plugin~Plugin
  */
 export default class TableCellPropertiesEditing extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'TableCellPropertiesEditing';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ TableEditing, TableCellWidthEditing ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	init() {
-		const editor = this.editor;
-		const schema = editor.model.schema;
-		const conversion = editor.conversion;
-
-		editor.config.define( 'table.tableCellProperties.defaultProperties', {} );
-
-		const defaultTableCellProperties = getNormalizedDefaultProperties(
-			editor.config.get( 'table.tableCellProperties.defaultProperties' ),
-			{
-				includeVerticalAlignmentProperty: true,
-				includeHorizontalAlignmentProperty: true,
-				includePaddingProperty: true,
-				isRightToLeftContent: editor.locale.contentLanguageDirection === 'rtl'
-			}
-		);
-
-		editor.data.addStyleProcessorRules( addBorderRules );
-		enableBorderProperties( schema, conversion, {
-			color: defaultTableCellProperties.borderColor,
-			style: defaultTableCellProperties.borderStyle,
-			width: defaultTableCellProperties.borderWidth
-		} );
-		editor.commands.add( 'tableCellBorderStyle', new TableCellBorderStyleCommand( editor, defaultTableCellProperties.borderStyle ) );
-		editor.commands.add( 'tableCellBorderColor', new TableCellBorderColorCommand( editor, defaultTableCellProperties.borderColor ) );
-		editor.commands.add( 'tableCellBorderWidth', new TableCellBorderWidthCommand( editor, defaultTableCellProperties.borderWidth ) );
-
-		enableProperty( schema, conversion, {
-			modelAttribute: 'tableCellHeight',
-			styleName: 'height',
-			defaultValue: defaultTableCellProperties.height
-		} );
-		editor.commands.add( 'tableCellHeight', new TableCellHeightCommand( editor, defaultTableCellProperties.height ) );
-
-		editor.data.addStyleProcessorRules( addPaddingRules );
-		enableProperty( schema, conversion, {
-			modelAttribute: 'tableCellPadding',
-			styleName: 'padding',
-			reduceBoxSides: true,
-			defaultValue: defaultTableCellProperties.padding
-		} );
-		editor.commands.add( 'tableCellPadding', new TableCellPaddingCommand( editor, defaultTableCellProperties.padding ) );
-
-		editor.data.addStyleProcessorRules( addBackgroundRules );
-		enableProperty( schema, conversion, {
-			modelAttribute: 'tableCellBackgroundColor',
-			styleName: 'background-color',
-			defaultValue: defaultTableCellProperties.backgroundColor
-		} );
-		editor.commands.add(
-			'tableCellBackgroundColor',
-			new TableCellBackgroundColorCommand( editor, defaultTableCellProperties.backgroundColor )
-		);
-
-		enableHorizontalAlignmentProperty( schema, conversion, defaultTableCellProperties.horizontalAlignment );
-		editor.commands.add(
-			'tableCellHorizontalAlignment',
-			new TableCellHorizontalAlignmentCommand( editor, defaultTableCellProperties.horizontalAlignment )
-		);
-
-		enableVerticalAlignmentProperty( schema, conversion, defaultTableCellProperties.verticalAlignment );
-		editor.commands.add(
-			'tableCellVerticalAlignment',
-			new TableCellVerticalAlignmentCommand( editor, defaultTableCellProperties.verticalAlignment )
-		);
-	}
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'TableCellPropertiesEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [TableEditing, TableCellWidthEditing];
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const schema = editor.model.schema;
+        const conversion = editor.conversion;
+        editor.config.define('table.tableCellProperties.defaultProperties', {});
+        const defaultTableCellProperties = getNormalizedDefaultProperties(editor.config.get('table.tableCellProperties.defaultProperties'), {
+            includeVerticalAlignmentProperty: true,
+            includeHorizontalAlignmentProperty: true,
+            includePaddingProperty: true,
+            isRightToLeftContent: editor.locale.contentLanguageDirection === 'rtl'
+        });
+        editor.data.addStyleProcessorRules(addBorderRules);
+        enableBorderProperties(schema, conversion, {
+            color: defaultTableCellProperties.borderColor,
+            style: defaultTableCellProperties.borderStyle,
+            width: defaultTableCellProperties.borderWidth
+        });
+        editor.commands.add('tableCellBorderStyle', new TableCellBorderStyleCommand(editor, defaultTableCellProperties.borderStyle));
+        editor.commands.add('tableCellBorderColor', new TableCellBorderColorCommand(editor, defaultTableCellProperties.borderColor));
+        editor.commands.add('tableCellBorderWidth', new TableCellBorderWidthCommand(editor, defaultTableCellProperties.borderWidth));
+        enableProperty(schema, conversion, {
+            modelAttribute: 'tableCellHeight',
+            styleName: 'height',
+            defaultValue: defaultTableCellProperties.height
+        });
+        editor.commands.add('tableCellHeight', new TableCellHeightCommand(editor, defaultTableCellProperties.height));
+        editor.data.addStyleProcessorRules(addPaddingRules);
+        enableProperty(schema, conversion, {
+            modelAttribute: 'tableCellPadding',
+            styleName: 'padding',
+            reduceBoxSides: true,
+            defaultValue: defaultTableCellProperties.padding
+        });
+        editor.commands.add('tableCellPadding', new TableCellPaddingCommand(editor, defaultTableCellProperties.padding));
+        editor.data.addStyleProcessorRules(addBackgroundRules);
+        enableProperty(schema, conversion, {
+            modelAttribute: 'tableCellBackgroundColor',
+            styleName: 'background-color',
+            defaultValue: defaultTableCellProperties.backgroundColor
+        });
+        editor.commands.add('tableCellBackgroundColor', new TableCellBackgroundColorCommand(editor, defaultTableCellProperties.backgroundColor));
+        enableHorizontalAlignmentProperty(schema, conversion, defaultTableCellProperties.horizontalAlignment);
+        editor.commands.add('tableCellHorizontalAlignment', new TableCellHorizontalAlignmentCommand(editor, defaultTableCellProperties.horizontalAlignment));
+        enableVerticalAlignmentProperty(schema, conversion, defaultTableCellProperties.verticalAlignment);
+        editor.commands.add('tableCellVerticalAlignment', new TableCellVerticalAlignmentCommand(editor, defaultTableCellProperties.verticalAlignment));
+    }
 }
-
-// Enables the `'tableCellBorderStyle'`, `'tableCellBorderColor'` and `'tableCellBorderWidth'` attributes for table cells.
-//
-// @param {module:engine/model/schema~Schema} schema
-// @param {module:engine/conversion/conversion~Conversion} conversion
-// @param {Object} defaultBorder The default border values.
-// @param {String} defaultBorder.color The default `tableCellBorderColor` value.
-// @param {String} defaultBorder.style The default `tableCellBorderStyle` value.
-// @param {String} defaultBorder.width The default `tableCellBorderWidth` value.
-function enableBorderProperties( schema, conversion, defaultBorder ) {
-	const modelAttributes = {
-		width: 'tableCellBorderWidth',
-		color: 'tableCellBorderColor',
-		style: 'tableCellBorderStyle'
-	};
-
-	schema.extend( 'tableCell', {
-		allowAttributes: Object.values( modelAttributes )
-	} );
-
-	upcastBorderStyles( conversion, 'td', modelAttributes, defaultBorder );
-	upcastBorderStyles( conversion, 'th', modelAttributes, defaultBorder );
-	downcastAttributeToStyle( conversion, { modelElement: 'tableCell', modelAttribute: modelAttributes.style, styleName: 'border-style' } );
-	downcastAttributeToStyle( conversion, { modelElement: 'tableCell', modelAttribute: modelAttributes.color, styleName: 'border-color' } );
-	downcastAttributeToStyle( conversion, { modelElement: 'tableCell', modelAttribute: modelAttributes.width, styleName: 'border-width' } );
+/**
+ * Enables the `'tableCellBorderStyle'`, `'tableCellBorderColor'` and `'tableCellBorderWidth'` attributes for table cells.
+ *
+ * @param defaultBorder The default border values.
+ * @param defaultBorder.color The default `tableCellBorderColor` value.
+ * @param defaultBorder.style The default `tableCellBorderStyle` value.
+ * @param defaultBorder.width The default `tableCellBorderWidth` value.
+ */
+function enableBorderProperties(schema, conversion, defaultBorder) {
+    const modelAttributes = {
+        width: 'tableCellBorderWidth',
+        color: 'tableCellBorderColor',
+        style: 'tableCellBorderStyle'
+    };
+    schema.extend('tableCell', {
+        allowAttributes: Object.values(modelAttributes)
+    });
+    upcastBorderStyles(conversion, 'td', modelAttributes, defaultBorder);
+    upcastBorderStyles(conversion, 'th', modelAttributes, defaultBorder);
+    downcastAttributeToStyle(conversion, { modelElement: 'tableCell', modelAttribute: modelAttributes.style, styleName: 'border-style' });
+    downcastAttributeToStyle(conversion, { modelElement: 'tableCell', modelAttribute: modelAttributes.color, styleName: 'border-color' });
+    downcastAttributeToStyle(conversion, { modelElement: 'tableCell', modelAttribute: modelAttributes.width, styleName: 'border-width' });
 }
-
-// Enables the `'tableCellHorizontalAlignment'` attribute for table cells.
-//
-// @param {module:engine/model/schema~Schema} schema
-// @param {module:engine/conversion/conversion~Conversion} conversion
-// @param {module:utils/locale~Locale} locale The {@link module:core/editor/editor~Editor#locale} instance.
-// @param {String} defaultValue The default horizontal alignment value.
-function enableHorizontalAlignmentProperty( schema, conversion, defaultValue ) {
-	schema.extend( 'tableCell', {
-		allowAttributes: [ 'tableCellHorizontalAlignment' ]
-	} );
-
-	conversion.for( 'downcast' )
-		.attributeToAttribute( {
-			model: {
-				name: 'tableCell',
-				key: 'tableCellHorizontalAlignment'
-			},
-			view: alignment => ( {
-				key: 'style',
-				value: {
-					'text-align': alignment
-				}
-			} )
-		} );
-
-	conversion.for( 'upcast' )
-		// Support for the `text-align:*;` CSS definition for the table cell alignment.
-		.attributeToAttribute( {
-			view: {
-				name: /^(td|th)$/,
-				styles: {
-					'text-align': ALIGN_VALUES_REG_EXP
-				}
-			},
-			model: {
-				key: 'tableCellHorizontalAlignment',
-				value: viewElement => {
-					const align = viewElement.getStyle( 'text-align' );
-
-					return align === defaultValue ? null : align;
-				}
-			}
-		} )
-		// Support for the `align` attribute as the backward compatibility while pasting from other sources.
-		.attributeToAttribute( {
-			view: {
-				name: /^(td|th)$/,
-				attributes: {
-					align: ALIGN_VALUES_REG_EXP
-				}
-			},
-			model: {
-				key: 'tableCellHorizontalAlignment',
-				value: viewElement => {
-					const align = viewElement.getAttribute( 'align' );
-
-					return align === defaultValue ? null : align;
-				}
-			}
-		} );
+/**
+ * Enables the `'tableCellHorizontalAlignment'` attribute for table cells.
+ *
+ * @param defaultValue The default horizontal alignment value.
+ */
+function enableHorizontalAlignmentProperty(schema, conversion, defaultValue) {
+    schema.extend('tableCell', {
+        allowAttributes: ['tableCellHorizontalAlignment']
+    });
+    conversion.for('downcast')
+        .attributeToAttribute({
+        model: {
+            name: 'tableCell',
+            key: 'tableCellHorizontalAlignment'
+        },
+        view: alignment => ({
+            key: 'style',
+            value: {
+                'text-align': alignment
+            }
+        })
+    });
+    conversion.for('upcast')
+        // Support for the `text-align:*;` CSS definition for the table cell alignment.
+        .attributeToAttribute({
+        view: {
+            name: /^(td|th)$/,
+            styles: {
+                'text-align': ALIGN_VALUES_REG_EXP
+            }
+        },
+        model: {
+            key: 'tableCellHorizontalAlignment',
+            value: (viewElement) => {
+                const align = viewElement.getStyle('text-align');
+                return align === defaultValue ? null : align;
+            }
+        }
+    })
+        // Support for the `align` attribute as the backward compatibility while pasting from other sources.
+        .attributeToAttribute({
+        view: {
+            name: /^(td|th)$/,
+            attributes: {
+                align: ALIGN_VALUES_REG_EXP
+            }
+        },
+        model: {
+            key: 'tableCellHorizontalAlignment',
+            value: (viewElement) => {
+                const align = viewElement.getAttribute('align');
+                return align === defaultValue ? null : align;
+            }
+        }
+    });
 }
-
-// Enables the `'verticalAlignment'` attribute for table cells.
-//
-// @param {module:engine/model/schema~Schema} schema
-// @param {module:engine/conversion/conversion~Conversion} conversion
-// @param {String} defaultValue The default vertical alignment value.
-function enableVerticalAlignmentProperty( schema, conversion, defaultValue ) {
-	schema.extend( 'tableCell', {
-		allowAttributes: [ 'tableCellVerticalAlignment' ]
-	} );
-
-	conversion.for( 'downcast' )
-		.attributeToAttribute( {
-			model: {
-				name: 'tableCell',
-				key: 'tableCellVerticalAlignment'
-			},
-			view: alignment => ( {
-				key: 'style',
-				value: {
-					'vertical-align': alignment
-				}
-			} )
-		} );
-
-	conversion.for( 'upcast' )
-		// Support for the `vertical-align:*;` CSS definition for the table cell alignment.
-		.attributeToAttribute( {
-			view: {
-				name: /^(td|th)$/,
-				styles: {
-					'vertical-align': VALIGN_VALUES_REG_EXP
-				}
-			},
-			model: {
-				key: 'tableCellVerticalAlignment',
-				value: viewElement => {
-					const align = viewElement.getStyle( 'vertical-align' );
-
-					return align === defaultValue ? null : align;
-				}
-			}
-		} )
-		// Support for the `align` attribute as the backward compatibility while pasting from other sources.
-		.attributeToAttribute( {
-			view: {
-				name: /^(td|th)$/,
-				attributes: {
-					valign: VALIGN_VALUES_REG_EXP
-				}
-			},
-			model: {
-				key: 'tableCellVerticalAlignment',
-				value: viewElement => {
-					const valign = viewElement.getAttribute( 'valign' );
-
-					return valign === defaultValue ? null : valign;
-				}
-			}
-		} );
+/**
+ * Enables the `'verticalAlignment'` attribute for table cells.
+ *
+ * @param defaultValue The default vertical alignment value.
+ */
+function enableVerticalAlignmentProperty(schema, conversion, defaultValue) {
+    schema.extend('tableCell', {
+        allowAttributes: ['tableCellVerticalAlignment']
+    });
+    conversion.for('downcast')
+        .attributeToAttribute({
+        model: {
+            name: 'tableCell',
+            key: 'tableCellVerticalAlignment'
+        },
+        view: alignment => ({
+            key: 'style',
+            value: {
+                'vertical-align': alignment
+            }
+        })
+    });
+    conversion.for('upcast')
+        // Support for the `vertical-align:*;` CSS definition for the table cell alignment.
+        .attributeToAttribute({
+        view: {
+            name: /^(td|th)$/,
+            styles: {
+                'vertical-align': VALIGN_VALUES_REG_EXP
+            }
+        },
+        model: {
+            key: 'tableCellVerticalAlignment',
+            value: (viewElement) => {
+                const align = viewElement.getStyle('vertical-align');
+                return align === defaultValue ? null : align;
+            }
+        }
+    })
+        // Support for the `align` attribute as the backward compatibility while pasting from other sources.
+        .attributeToAttribute({
+        view: {
+            name: /^(td|th)$/,
+            attributes: {
+                valign: VALIGN_VALUES_REG_EXP
+            }
+        },
+        model: {
+            key: 'tableCellVerticalAlignment',
+            value: (viewElement) => {
+                const valign = viewElement.getAttribute('valign');
+                return valign === defaultValue ? null : valign;
+            }
+        }
+    });
 }

package/src/tablecellproperties/tablecellpropertiesui.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @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/tablecellproperties/tablecellpropertiesui
+ */
+import { Plugin, type Editor, type PluginDependencies } from 'ckeditor5/src/core';
+import TableCellPropertiesView from './ui/tablecellpropertiesview';
+/**
+ * The table cell properties UI plugin. It introduces the `'tableCellProperties'` button
+ * that opens a form allowing to specify the visual styling of a table cell.
+ *
+ * It uses the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon plugin}.
+ */
+export default class TableCellPropertiesUI extends Plugin {
+    /**
+     * The default table cell properties.
+     */
+    private _defaultTableCellProperties;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon?;
+    /**
+     * The cell properties form view displayed inside the balloon.
+     */
+    view?: TableCellPropertiesView | null;
+    /**
+     * The batch used to undo all changes made by the form (which are live, as the user types)
+     * when "Cancel" was pressed. Each time the view is shown, a new batch is created.
+     */
+    private _undoStepBatch?;
+    /**
+     * Flag used to indicate whether view is ready to execute update commands
+     * (it finished loading initial data).
+     */
+    private _isReady?;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'TableCellPropertiesUI';
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates the {@link module:table/tablecellproperties/ui/tablecellpropertiesview~TableCellPropertiesView} instance.
+     *
+     * @returns The cell properties form view instance.
+     */
+    private _createPropertiesView;
+    /**
+     * In this method the "editor data -> UI" binding is happening.
+     *
+     * When executed, this method obtains selected cell property values from various table commands
+     * and passes them to the {@link #view}.
+     *
+     * This way, the UI stays up–to–date with the editor data.
+     */
+    private _fillViewFormFromCommandValues;
+    /**
+     * Shows the {@link #view} in the {@link #_balloon}.
+     *
+     * **Note**: Each time a view is shown, a new {@link #_undoStepBatch} is created. It contains
+     * all changes made to the document when the view is visible, allowing a single undo step
+     * for all of them.
+     */
+    protected _showView(): void;
+    /**
+     * Removes the {@link #view} from the {@link #_balloon}.
+     */
+    protected _hideView(): void;
+    /**
+     * Repositions the {@link #_balloon} or hides the {@link #view} if a table cell is no longer selected.
+     */
+    protected _updateView(): void;
+    /**
+     * Returns `true` when the {@link #view} is visible in the {@link #_balloon}.
+     */
+    private get _isViewVisible();
+    /**
+     * Returns `true` when the {@link #view} is in the {@link #_balloon}.
+     */
+    private get _isViewInBalloon();
+    /**
+     * Creates a callback that when executed upon the {@link #view view's} property change
+     * executes a related editor command with the new property value.
+     *
+     * @param defaultValue The default value of the command.
+     */
+    private _getPropertyChangeCallback;
+    /**
+     * Creates a callback that when executed upon the {@link #view view's} property change:
+     * * Executes a related editor command with the new property value if the value is valid,
+     * * Or sets the error text next to the invalid field, if the value did not pass the validation.
+     */
+    private _getValidatedPropertyChangeCallback;
+}