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

package/src/tablecellproperties/commands/tablecellpaddingcommand.js

@@ -2,14 +2,8 @@
  * @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/commands/tablecellpaddingcommand
- */
-
 import TableCellPropertyCommand from './tablecellpropertycommand';
 import { addDefaultUnitToNumericValue, getSingleValue } from '../../utils/table-properties';
-
 /**
  * The table cell padding command.
  *
@@ -18,58 +12,53 @@ import { addDefaultUnitToNumericValue, getSingleValue } from '../../utils/table-
  *
  * To change the padding of selected cells, execute the command:
  *
- *		editor.execute( 'tableCellPadding', {
- *			value: '5px'
- *		} );
+ * ```ts
+ * editor.execute( 'tableCellPadding', {
+ *   value: '5px'
+ * } );
+ * ```
  *
  * **Note**: This command adds the default `'px'` unit to numeric values. Executing:
  *
- *		editor.execute( 'tableCellPadding', {
- *			value: '5'
- *		} );
+ * ```ts
+ * editor.execute( 'tableCellPadding', {
+ *   value: '5'
+ * } );
+ * ```
  *
  * will set the `padding` attribute to `'5px'` in the model.
- *
- * @extends module:table/tablecellproperties/commands/tablecellpropertycommand~TableCellPropertyCommand
  */
 export default class TableCellPaddingCommand extends TableCellPropertyCommand {
-	/**
-	 * Creates a new `TableCellPaddingCommand` instance.
-	 *
-	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
-	 * @param {String} defaultValue The default value of the attribute.
-	 */
-	constructor( editor, defaultValue ) {
-		super( editor, 'tableCellPadding', defaultValue );
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	_getAttribute( tableCell ) {
-		if ( !tableCell ) {
-			return;
-		}
-
-		const value = getSingleValue( tableCell.getAttribute( this.attributeName ) );
-
-		if ( value === this._defaultValue ) {
-			return;
-		}
-
-		return value;
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	_getValueToSet( value ) {
-		value = addDefaultUnitToNumericValue( value, 'px' );
-
-		if ( value === this._defaultValue ) {
-			return;
-		}
-
-		return value;
-	}
+    /**
+     * Creates a new `TableCellPaddingCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param defaultValue The default value of the attribute.
+     */
+    constructor(editor, defaultValue) {
+        super(editor, 'tableCellPadding', defaultValue);
+    }
+    /**
+     * @inheritDoc
+     */
+    _getAttribute(tableCell) {
+        if (!tableCell) {
+            return;
+        }
+        const value = getSingleValue(tableCell.getAttribute(this.attributeName));
+        if (value === this._defaultValue) {
+            return;
+        }
+        return value;
+    }
+    /**
+     * @inheritDoc
+     */
+    _getValueToSet(value) {
+        const newValue = addDefaultUnitToNumericValue(value, 'px');
+        if (newValue === this._defaultValue) {
+            return;
+        }
+        return newValue;
+    }
 }

package/src/tablecellproperties/commands/tablecellpropertycommand.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @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/commands/tablecellpropertycommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core';
+import type { Element, Batch } from 'ckeditor5/src/engine';
+/**
+ * The table cell attribute command.
+ *
+ * The command is a base command for other table cell property commands.
+ */
+export default class TableCellPropertyCommand extends Command {
+    /**
+     * The attribute that will be set by the command.
+     */
+    readonly attributeName: string;
+    /**
+     * The default value for the attribute.
+     */
+    protected readonly _defaultValue: string;
+    /**
+     * Creates a new `TableCellPropertyCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param attributeName Table cell attribute name.
+     * @param defaultValue The default value of the attribute.
+     */
+    constructor(editor: Editor, attributeName: string, defaultValue: string);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options.value If set, the command will set the attribute on selected table cells.
+     * If it is not set, the command will remove the attribute from the selected table cells.
+     * @param options.batch Pass the model batch instance to the command to aggregate changes,
+     * for example to allow a single undo step for multiple executions.
+     */
+    execute(options?: {
+        value?: string | number;
+        batch?: Batch;
+    }): void;
+    /**
+     * Returns the attribute value for a table cell.
+     */
+    protected _getAttribute(tableCell: Element | undefined): unknown;
+    /**
+     * Returns the proper model value. It can be used to add a default unit to numeric values.
+     */
+    protected _getValueToSet(value: string | number | undefined): unknown;
+    /**
+     * Returns a single value for all selected table cells. If the value is the same for all cells,
+     * it will be returned (`undefined` otherwise).
+     */
+    private _getSingleValue;
+}

package/src/tablecellproperties/commands/tablecellpropertycommand.js

@@ -2,136 +2,91 @@
  * @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/commands/tablecellpropertycommand
  */
-
 import { Command } from 'ckeditor5/src/core';
-
 /**
  * The table cell attribute command.
  *
  * The command is a base command for other table cell property commands.
- *
- * @extends module:core/command~Command
  */
 export default class TableCellPropertyCommand extends Command {
-	/**
-	 * Creates a new `TableCellPropertyCommand` instance.
-	 *
-	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
-	 * @param {String} attributeName Table cell attribute name.
-	 * @param {String} defaultValue The default value of the attribute.
-	 */
-	constructor( editor, attributeName, defaultValue ) {
-		super( editor );
-
-		/**
-		 * The attribute that will be set by the command.
-		 *
-		 * @readonly
-		 * @member {String}
-		 */
-		this.attributeName = attributeName;
-
-		/**
-		 * The default value for the attribute.
-		 *
-		 * @readonly
-		 * @protected
-		 * @member {String}
-		 */
-		this._defaultValue = defaultValue;
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	refresh() {
-		const editor = this.editor;
-		const tableUtils = this.editor.plugins.get( 'TableUtils' );
-		const selectedTableCells = tableUtils.getSelectionAffectedTableCells( editor.model.document.selection );
-
-		this.isEnabled = !!selectedTableCells.length;
-		this.value = this._getSingleValue( selectedTableCells );
-	}
-
-	/**
-	 * Executes the command.
-	 *
-	 * @fires execute
-	 * @param {Object} [options]
-	 * @param {*} [options.value] If set, the command will set the attribute on selected table cells.
-	 * If it is not set, the command will remove the attribute from the selected table cells.
-	 * @param {module:engine/model/batch~Batch} [options.batch] Pass the model batch instance to the command to aggregate changes,
-	 * for example to allow a single undo step for multiple executions.
-	 */
-	execute( options = {} ) {
-		const { value, batch } = options;
-		const model = this.editor.model;
-		const tableUtils = this.editor.plugins.get( 'TableUtils' );
-		const tableCells = tableUtils.getSelectionAffectedTableCells( model.document.selection );
-		const valueToSet = this._getValueToSet( value );
-
-		model.enqueueChange( batch, writer => {
-			if ( valueToSet ) {
-				tableCells.forEach( tableCell => writer.setAttribute( this.attributeName, valueToSet, tableCell ) );
-			} else {
-				tableCells.forEach( tableCell => writer.removeAttribute( this.attributeName, tableCell ) );
-			}
-		} );
-	}
-
-	/**
-	 * Returns the attribute value for a table cell.
-	 *
-	 * @param {module:engine/model/element~Element} tableCell
-	 * @returns {String|undefined}
-	 * @private
-	 */
-	_getAttribute( tableCell ) {
-		if ( !tableCell ) {
-			return;
-		}
-
-		const value = tableCell.getAttribute( this.attributeName );
-
-		if ( value === this._defaultValue ) {
-			return;
-		}
-
-		return value;
-	}
-
-	/**
-	 * Returns the proper model value. It can be used to add a default unit to numeric values.
-	 *
-	 * @private
-	 * @param {*} value
-	 * @returns {*}
-	 */
-	_getValueToSet( value ) {
-		if ( value === this._defaultValue ) {
-			return;
-		}
-
-		return value;
-	}
-
-	/**
-	 * Returns a single value for all selected table cells. If the value is the same for all cells,
-	 * it will be returned (`undefined` otherwise).
-	 *
-	 * @param {Array.<module:engine/model/element~Element>} tableCell
-	 * @returns {*}
-	 * @private
-	 */
-	_getSingleValue( tableCell ) {
-		const firstCellValue = this._getAttribute( tableCell[ 0 ] );
-
-		const everyCellHasAttribute = tableCell.every( tableCell => this._getAttribute( tableCell ) === firstCellValue );
-
-		return everyCellHasAttribute ? firstCellValue : undefined;
-	}
+    /**
+     * Creates a new `TableCellPropertyCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param attributeName Table cell attribute name.
+     * @param defaultValue The default value of the attribute.
+     */
+    constructor(editor, attributeName, defaultValue) {
+        super(editor);
+        this.attributeName = attributeName;
+        this._defaultValue = defaultValue;
+    }
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const editor = this.editor;
+        const tableUtils = this.editor.plugins.get('TableUtils');
+        const selectedTableCells = tableUtils.getSelectionAffectedTableCells(editor.model.document.selection);
+        this.isEnabled = !!selectedTableCells.length;
+        this.value = this._getSingleValue(selectedTableCells);
+    }
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options.value If set, the command will set the attribute on selected table cells.
+     * If it is not set, the command will remove the attribute from the selected table cells.
+     * @param options.batch Pass the model batch instance to the command to aggregate changes,
+     * for example to allow a single undo step for multiple executions.
+     */
+    execute(options = {}) {
+        const { value, batch } = options;
+        const model = this.editor.model;
+        const tableUtils = this.editor.plugins.get('TableUtils');
+        const tableCells = tableUtils.getSelectionAffectedTableCells(model.document.selection);
+        const valueToSet = this._getValueToSet(value);
+        model.enqueueChange(batch, writer => {
+            if (valueToSet) {
+                tableCells.forEach(tableCell => writer.setAttribute(this.attributeName, valueToSet, tableCell));
+            }
+            else {
+                tableCells.forEach(tableCell => writer.removeAttribute(this.attributeName, tableCell));
+            }
+        });
+    }
+    /**
+     * Returns the attribute value for a table cell.
+     */
+    _getAttribute(tableCell) {
+        if (!tableCell) {
+            return;
+        }
+        const value = tableCell.getAttribute(this.attributeName);
+        if (value === this._defaultValue) {
+            return;
+        }
+        return value;
+    }
+    /**
+     * Returns the proper model value. It can be used to add a default unit to numeric values.
+     */
+    _getValueToSet(value) {
+        if (value === this._defaultValue) {
+            return;
+        }
+        return value;
+    }
+    /**
+     * Returns a single value for all selected table cells. If the value is the same for all cells,
+     * it will be returned (`undefined` otherwise).
+     */
+    _getSingleValue(tableCells) {
+        const firstCellValue = this._getAttribute(tableCells[0]);
+        const everyCellHasAttribute = tableCells.every(tableCells => this._getAttribute(tableCells) === firstCellValue);
+        return everyCellHasAttribute ? firstCellValue : undefined;
+    }
 }

package/src/tablecellproperties/commands/tablecellverticalalignmentcommand.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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/commands/tablecellverticalalignmentcommand
+ */
+import type { Editor } from 'ckeditor5/src/core';
+import TableCellPropertyCommand from './tablecellpropertycommand';
+/**
+ * The table cell vertical alignment command.
+ *
+ * The command is registered by the {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing} as
+ * the `'tableCellVerticalAlignment'` editor command.
+ *
+ * To change the vertical text alignment of selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableCellVerticalAlignment', {
+ *   value: 'top'
+ * } );
+ * ```
+ *
+ * The following values, corresponding to the
+ * [`vertical-align` CSS attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align), are allowed:
+ *
+ * * `'top'`
+ * * `'bottom'`
+ *
+ * The `'middle'` value is the default one so there is no need to set it.
+ */
+export default class TableCellVerticalAlignmentCommand extends TableCellPropertyCommand {
+    /**
+     * Creates a new `TableCellVerticalAlignmentCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param defaultValue The default value for the "alignment" attribute.
+     */
+    constructor(editor: Editor, defaultValue: string);
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        tableCellVerticalAlignment: TableCellVerticalAlignmentCommand;
+    }
+}

package/src/tablecellproperties/commands/tablecellverticalalignmentcommand.js

@@ -2,13 +2,7 @@
  * @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/commands/tablecellverticalalignmentcommand
- */
-
 import TableCellPropertyCommand from './tablecellpropertycommand';
-
 /**
  * The table cell vertical alignment command.
  *
@@ -17,9 +11,11 @@ import TableCellPropertyCommand from './tablecellpropertycommand';
  *
  * To change the vertical text alignment of selected cells, execute the command:
  *
- *		editor.execute( 'tableCellVerticalAlignment', {
- *			value: 'top'
- *		} );
+ * ```ts
+ * editor.execute( 'tableCellVerticalAlignment', {
+ *   value: 'top'
+ * } );
+ * ```
  *
  * The following values, corresponding to the
  * [`vertical-align` CSS attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align), are allowed:
@@ -28,17 +24,15 @@ import TableCellPropertyCommand from './tablecellpropertycommand';
  * * `'bottom'`
  *
  * The `'middle'` value is the default one so there is no need to set it.
- *
- * @extends module:table/tablecellproperties/commands/tablecellpropertycommand~TableCellPropertyCommand
  */
 export default class TableCellVerticalAlignmentCommand extends TableCellPropertyCommand {
-	/**
-	 * Creates a new `TableCellVerticalAlignmentCommand` instance.
-	 *
-	 * @param {module:core/editor/editor~Editor} editor An editor in which this command will be used.
-	 * @param {String} defaultValue The default value for the "alignment" attribute.
-	 */
-	constructor( editor, defaultValue ) {
-		super( editor, 'tableCellVerticalAlignment', defaultValue );
-	}
+    /**
+     * Creates a new `TableCellVerticalAlignmentCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param defaultValue The default value for the "alignment" attribute.
+     */
+    constructor(editor, defaultValue) {
+        super(editor, 'tableCellVerticalAlignment', defaultValue);
+    }
 }

package/src/tablecellproperties/tablecellpropertiesediting.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @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, type PluginDependencies } from 'ckeditor5/src/core';
+import '../tableconfig';
+/**
+ * The table cell properties editing feature.
+ *
+ * Introduces table cell model attributes and their conversion:
+ *
+ * - border: `tableCellBorderStyle`, `tableCellBorderColor` and `tableCellBorderWidth`
+ * - background color: `tableCellBackgroundColor`
+ * - cell padding: `tableCellPadding`
+ * - horizontal and vertical alignment: `tableCellHorizontalAlignment`, `tableCellVerticalAlignment`
+ * - cell width and height: `tableCellWidth`, `tableCellHeight`
+ *
+ * It also registers commands used to manipulate the above attributes:
+ *
+ * - border: the `'tableCellBorderStyle'`, `'tableCellBorderColor'` and `'tableCellBorderWidth'` commands
+ * - background color: the `'tableCellBackgroundColor'` command
+ * - cell padding: the `'tableCellPadding'` command
+ * - horizontal and vertical alignment: the `'tableCellHorizontalAlignment'` and `'tableCellVerticalAlignment'` commands
+ * - width and height: the `'tableCellWidth'` and `'tableCellHeight'` commands
+ */
+export default class TableCellPropertiesEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'TableCellPropertiesEditing';
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [TableCellPropertiesEditing.pluginName]: TableCellPropertiesEditing;
+    }
+}