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

package/src/tableproperties/tablepropertiesediting.js

@@ -2,21 +2,13 @@
  * @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/tableproperties/tablepropertiesediting
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import { addBackgroundRules, addBorderRules } from 'ckeditor5/src/engine';
-
 import TableEditing from '../tableediting';
-import {
-	downcastAttributeToStyle,
-	downcastTableAttribute,
-	upcastBorderStyles,
-	upcastStyleToAttribute
-} from '../converters/tableproperties';
+import { downcastAttributeToStyle, downcastTableAttribute, upcastBorderStyles, upcastStyleToAttribute } from '../converters/tableproperties';
 import TableBackgroundColorCommand from './commands/tablebackgroundcolorcommand';
 import TableBorderColorCommand from './commands/tablebordercolorcommand';
 import TableBorderStyleCommand from './commands/tableborderstylecommand';
@@ -25,10 +17,8 @@ import TableWidthCommand from './commands/tablewidthcommand';
 import TableHeightCommand from './commands/tableheightcommand';
 import TableAlignmentCommand from './commands/tablealignmentcommand';
 import { getNormalizedDefaultProperties } from '../utils/table-properties';
-
 const ALIGN_VALUES_REG_EXP = /^(left|center|right)$/;
 const FLOAT_VALUES_REG_EXP = /^(left|none|right)$/;
-
 /**
  * The table properties editing feature.
  *
@@ -45,209 +35,172 @@ const FLOAT_VALUES_REG_EXP = /^(left|none|right)$/;
  * - background color: `'tableBackgroundColor'`
  * - horizontal alignment: `'tableAlignment'`
  * - width & height: `'tableWidth'` & `'tableHeight'`
- *
- * @extends module:core/plugin~Plugin
  */
 export default class TablePropertiesEditing extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'TablePropertiesEditing';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ TableEditing ];
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	init() {
-		const editor = this.editor;
-		const schema = editor.model.schema;
-		const conversion = editor.conversion;
-
-		editor.config.define( 'table.tableProperties.defaultProperties', {} );
-
-		const defaultTableProperties = getNormalizedDefaultProperties( editor.config.get( 'table.tableProperties.defaultProperties' ), {
-			includeAlignmentProperty: true
-		} );
-
-		editor.data.addStyleProcessorRules( addBorderRules );
-		enableBorderProperties( schema, conversion, {
-			color: defaultTableProperties.borderColor,
-			style: defaultTableProperties.borderStyle,
-			width: defaultTableProperties.borderWidth
-		} );
-		editor.commands.add( 'tableBorderColor', new TableBorderColorCommand( editor, defaultTableProperties.borderColor ) );
-		editor.commands.add( 'tableBorderStyle', new TableBorderStyleCommand( editor, defaultTableProperties.borderStyle ) );
-		editor.commands.add( 'tableBorderWidth', new TableBorderWidthCommand( editor, defaultTableProperties.borderWidth ) );
-
-		enableAlignmentProperty( schema, conversion, defaultTableProperties.alignment );
-		editor.commands.add( 'tableAlignment', new TableAlignmentCommand( editor, defaultTableProperties.alignment ) );
-
-		enableTableToFigureProperty( schema, conversion, {
-			modelAttribute: 'tableWidth',
-			styleName: 'width',
-			defaultValue: defaultTableProperties.width
-		} );
-		editor.commands.add( 'tableWidth', new TableWidthCommand( editor, defaultTableProperties.width ) );
-
-		enableTableToFigureProperty( schema, conversion, {
-			modelAttribute: 'tableHeight',
-			styleName: 'height',
-			defaultValue: defaultTableProperties.height
-		} );
-		editor.commands.add( 'tableHeight', new TableHeightCommand( editor, defaultTableProperties.height ) );
-
-		editor.data.addStyleProcessorRules( addBackgroundRules );
-		enableProperty( schema, conversion, {
-			modelAttribute: 'tableBackgroundColor',
-			styleName: 'background-color',
-			defaultValue: defaultTableProperties.backgroundColor
-		} );
-		editor.commands.add(
-			'tableBackgroundColor',
-			new TableBackgroundColorCommand( editor, defaultTableProperties.backgroundColor )
-		);
-	}
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'TablePropertiesEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [TableEditing];
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const schema = editor.model.schema;
+        const conversion = editor.conversion;
+        editor.config.define('table.tableProperties.defaultProperties', {});
+        const defaultTableProperties = getNormalizedDefaultProperties(editor.config.get('table.tableProperties.defaultProperties'), {
+            includeAlignmentProperty: true
+        });
+        editor.data.addStyleProcessorRules(addBorderRules);
+        enableBorderProperties(schema, conversion, {
+            color: defaultTableProperties.borderColor,
+            style: defaultTableProperties.borderStyle,
+            width: defaultTableProperties.borderWidth
+        });
+        editor.commands.add('tableBorderColor', new TableBorderColorCommand(editor, defaultTableProperties.borderColor));
+        editor.commands.add('tableBorderStyle', new TableBorderStyleCommand(editor, defaultTableProperties.borderStyle));
+        editor.commands.add('tableBorderWidth', new TableBorderWidthCommand(editor, defaultTableProperties.borderWidth));
+        enableAlignmentProperty(schema, conversion, defaultTableProperties.alignment);
+        editor.commands.add('tableAlignment', new TableAlignmentCommand(editor, defaultTableProperties.alignment));
+        enableTableToFigureProperty(schema, conversion, {
+            modelAttribute: 'tableWidth',
+            styleName: 'width',
+            defaultValue: defaultTableProperties.width
+        });
+        editor.commands.add('tableWidth', new TableWidthCommand(editor, defaultTableProperties.width));
+        enableTableToFigureProperty(schema, conversion, {
+            modelAttribute: 'tableHeight',
+            styleName: 'height',
+            defaultValue: defaultTableProperties.height
+        });
+        editor.commands.add('tableHeight', new TableHeightCommand(editor, defaultTableProperties.height));
+        editor.data.addStyleProcessorRules(addBackgroundRules);
+        enableProperty(schema, conversion, {
+            modelAttribute: 'tableBackgroundColor',
+            styleName: 'background-color',
+            defaultValue: defaultTableProperties.backgroundColor
+        });
+        editor.commands.add('tableBackgroundColor', new TableBackgroundColorCommand(editor, defaultTableProperties.backgroundColor));
+    }
 }
-
-// Enables `tableBorderStyle'`, `tableBorderColor'` and `tableBorderWidth'` attributes for table.
-//
-// @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 `tableBorderColor` value.
-// @param {String} defaultBorder.style The default `tableBorderStyle` value.
-// @param {String} defaultBorder.width The default `tableBorderWidth` value.
-function enableBorderProperties( schema, conversion, defaultBorder ) {
-	const modelAttributes = {
-		width: 'tableBorderWidth',
-		color: 'tableBorderColor',
-		style: 'tableBorderStyle'
-	};
-
-	schema.extend( 'table', {
-		allowAttributes: Object.values( modelAttributes )
-	} );
-
-	upcastBorderStyles( conversion, 'table', modelAttributes, defaultBorder );
-
-	downcastTableAttribute( conversion, { modelAttribute: modelAttributes.color, styleName: 'border-color' } );
-	downcastTableAttribute( conversion, { modelAttribute: modelAttributes.style, styleName: 'border-style' } );
-	downcastTableAttribute( conversion, { modelAttribute: modelAttributes.width, styleName: 'border-width' } );
+/**
+ * Enables `tableBorderStyle'`, `tableBorderColor'` and `tableBorderWidth'` attributes for table.
+ *
+ * @param defaultBorder The default border values.
+ * @param defaultBorder.color The default `tableBorderColor` value.
+ * @param defaultBorder.style The default `tableBorderStyle` value.
+ * @param defaultBorder.width The default `tableBorderWidth` value.
+ */
+function enableBorderProperties(schema, conversion, defaultBorder) {
+    const modelAttributes = {
+        width: 'tableBorderWidth',
+        color: 'tableBorderColor',
+        style: 'tableBorderStyle'
+    };
+    schema.extend('table', {
+        allowAttributes: Object.values(modelAttributes)
+    });
+    upcastBorderStyles(conversion, 'table', modelAttributes, defaultBorder);
+    downcastTableAttribute(conversion, { modelAttribute: modelAttributes.color, styleName: 'border-color' });
+    downcastTableAttribute(conversion, { modelAttribute: modelAttributes.style, styleName: 'border-style' });
+    downcastTableAttribute(conversion, { modelAttribute: modelAttributes.width, styleName: 'border-width' });
 }
-
-// Enables the `'alignment'` attribute for table.
-//
-// @param {module:engine/model/schema~Schema} schema
-// @param {module:engine/conversion/conversion~Conversion} conversion
-// @param {String} defaultValue The default alignment value.
-function enableAlignmentProperty( schema, conversion, defaultValue ) {
-	schema.extend( 'table', {
-		allowAttributes: [ 'tableAlignment' ]
-	} );
-
-	conversion.for( 'downcast' )
-		.attributeToAttribute( {
-			model: {
-				name: 'table',
-				key: 'tableAlignment'
-			},
-			view: alignment => ( {
-				key: 'style',
-				value: {
-					// Model: `alignment:center` => CSS: `float:none`.
-					float: alignment === 'center' ? 'none' : alignment
-				}
-			} ),
-			converterPriority: 'high'
-		} );
-
-	conversion.for( 'upcast' )
-		// Support for the `float:*;` CSS definition for the table alignment.
-		.attributeToAttribute( {
-			view: {
-				name: /^(table|figure)$/,
-				styles: {
-					float: FLOAT_VALUES_REG_EXP
-				}
-			},
-			model: {
-				key: 'tableAlignment',
-				value: viewElement => {
-					let align = viewElement.getStyle( 'float' );
-
-					// CSS: `float:none` => Model: `alignment:center`.
-					if ( align === 'none' ) {
-						align = 'center';
-					}
-
-					return align === defaultValue ? null : align;
-				}
-			}
-		} )
-		// Support for the `align` attribute as the backward compatibility while pasting from other sources.
-		.attributeToAttribute( {
-			view: {
-				attributes: {
-					align: ALIGN_VALUES_REG_EXP
-				}
-			},
-			model: {
-				name: 'table',
-				key: 'tableAlignment',
-				value: viewElement => {
-					const align = viewElement.getAttribute( 'align' );
-
-					return align === defaultValue ? null : align;
-				}
-			}
-		} );
+/**
+ * Enables the `'alignment'` attribute for table.
+ *
+ * @param defaultValue The default alignment value.
+ */
+function enableAlignmentProperty(schema, conversion, defaultValue) {
+    schema.extend('table', {
+        allowAttributes: ['tableAlignment']
+    });
+    conversion.for('downcast')
+        .attributeToAttribute({
+        model: {
+            name: 'table',
+            key: 'tableAlignment'
+        },
+        view: alignment => ({
+            key: 'style',
+            value: {
+                // Model: `alignment:center` => CSS: `float:none`.
+                float: alignment === 'center' ? 'none' : alignment
+            }
+        }),
+        converterPriority: 'high'
+    });
+    conversion.for('upcast')
+        // Support for the `float:*;` CSS definition for the table alignment.
+        .attributeToAttribute({
+        view: {
+            name: /^(table|figure)$/,
+            styles: {
+                float: FLOAT_VALUES_REG_EXP
+            }
+        },
+        model: {
+            key: 'tableAlignment',
+            value: (viewElement) => {
+                let align = viewElement.getStyle('float');
+                // CSS: `float:none` => Model: `alignment:center`.
+                if (align === 'none') {
+                    align = 'center';
+                }
+                return align === defaultValue ? null : align;
+            }
+        }
+    })
+        // Support for the `align` attribute as the backward compatibility while pasting from other sources.
+        .attributeToAttribute({
+        view: {
+            attributes: {
+                align: ALIGN_VALUES_REG_EXP
+            }
+        },
+        model: {
+            name: 'table',
+            key: 'tableAlignment',
+            value: (viewElement) => {
+                const align = viewElement.getAttribute('align');
+                return align === defaultValue ? null : align;
+            }
+        }
+    });
 }
-
-// Enables conversion for an attribute for simple view-model mappings.
-//
-// @param {module:engine/model/schema~Schema} schema
-// @param {module:engine/conversion/conversion~Conversion} conversion
-// @param {Object} options
-// @param {String} options.modelAttribute
-// @param {String} options.styleName
-// @param {String} options.defaultValue The default value for the specified `modelAttribute`.
-function enableProperty( schema, conversion, options ) {
-	const { modelAttribute } = options;
-
-	schema.extend( 'table', {
-		allowAttributes: [ modelAttribute ]
-	} );
-	upcastStyleToAttribute( conversion, { viewElement: 'table', ...options } );
-	downcastTableAttribute( conversion, options );
+/**
+ * Enables conversion for an attribute for simple view-model mappings.
+ *
+ * @param options.defaultValue The default value for the specified `modelAttribute`.
+ */
+function enableProperty(schema, conversion, options) {
+    const { modelAttribute } = options;
+    schema.extend('table', {
+        allowAttributes: [modelAttribute]
+    });
+    upcastStyleToAttribute(conversion, { viewElement: 'table', ...options });
+    downcastTableAttribute(conversion, options);
 }
-
-// Enables conversion for an attribute for simple view (figure) to model (table) mappings.
-//
-// @param {module:engine/model/schema~Schema} schema
-// @param {module:engine/conversion/conversion~Conversion} conversion
-// @param {Object} options
-// @param {String} options.modelAttribute
-// @param {String} options.styleName
-function enableTableToFigureProperty( schema, conversion, options ) {
-	const { modelAttribute } = options;
-
-	schema.extend( 'table', {
-		allowAttributes: [ modelAttribute ]
-	} );
-
-	upcastStyleToAttribute( conversion, {
-		viewElement: /^(table|figure)$/,
-		shouldUpcast: element => !( element.name == 'table' && element.parent.name == 'figure' ),
-		...options
-	} );
-
-	downcastAttributeToStyle( conversion, { modelElement: 'table', ...options } );
+/**
+ * Enables conversion for an attribute for simple view (figure) to model (table) mappings.
+ */
+function enableTableToFigureProperty(schema, conversion, options) {
+    const { modelAttribute } = options;
+    schema.extend('table', {
+        allowAttributes: [modelAttribute]
+    });
+    upcastStyleToAttribute(conversion, {
+        viewElement: /^(table|figure)$/,
+        shouldUpcast: (element) => !(element.name == 'table' && element.parent.name == 'figure'),
+        ...options
+    });
+    downcastAttributeToStyle(conversion, { modelElement: 'table', ...options });
 }

package/src/tableproperties/tablepropertiesui.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @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/tableproperties/tablepropertiesui
+ */
+import { type Editor, Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import TablePropertiesView from './ui/tablepropertiesview';
+/**
+ * The table properties UI plugin. It introduces the `'tableProperties'` button
+ * that opens a form allowing to specify visual styling of an entire table.
+ *
+ * It uses the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon plugin}.
+ */
+export default class TablePropertiesUI extends Plugin {
+    /**
+     * The default table properties.
+     */
+    private _defaultTableProperties;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon;
+    /**
+     * The properties form view displayed inside the balloon.
+     */
+    view: TablePropertiesView | 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(): 'TablePropertiesUI';
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates the {@link module:table/tableproperties/ui/tablepropertiesview~TablePropertiesView} instance.
+     *
+     * @returns The table properties form view instance.
+     */
+    private _createPropertiesView;
+    /**
+     * In this method the "editor data -> UI" binding is happening.
+     *
+     * When executed, this method obtains selected table 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, the new {@link #_undoStepBatch} is created that 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 is no longer selected.
+     */
+    protected _updateView(): void;
+    /**
+     * Returns `true` when the {@link #view} is the 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 {@link #view view's} property change
+     * executes a related editor command with the new property value.
+     *
+     * If new value will be set to the default value, the command will not be executed.
+     *
+     * @param commandName The command that will be executed.
+     */
+    private _getPropertyChangeCallback;
+    /**
+     * Creates a callback that when executed upon {@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;
+}