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

package/src/tableproperties/commands/tableheightcommand.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/tableproperties/commands/tableheightcommand
  */
-
 import TablePropertyCommand from './tablepropertycommand';
 import { addDefaultUnitToNumericValue } from '../../utils/table-properties';
-
 /**
  * The table height command.
  *
@@ -18,41 +15,40 @@ import { addDefaultUnitToNumericValue } from '../../utils/table-properties';
  *
  * To change the height of the selected table, execute the command:
  *
- *		editor.execute( 'tableHeight', {
- *			value: '500px'
- *		} );
+ * ```ts
+ * editor.execute( 'tableHeight', {
+ *   value: '500px'
+ * } );
+ * ```
  *
  * **Note**: This command adds the default `'px'` unit to numeric values. Executing:
  *
- *		editor.execute( 'tableHeight', {
- *			value: '50'
- *		} );
+ * ```ts
+ * editor.execute( 'tableHeight', {
+ *   value: '50'
+ * } );
+ * ```
  *
  * will set the `height` attribute to `'50px'` in the model.
- *
- * @extends module:table/tableproperties/commands/tablepropertycommand~TablePropertyCommand
  */
 export default class TableHeightCommand extends TablePropertyCommand {
-	/**
-	 * Creates a new `TableHeightCommand` 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, 'tableHeight', defaultValue );
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	_getValueToSet( value ) {
-		value = addDefaultUnitToNumericValue( value, 'px' );
-
-		if ( value === this._defaultValue ) {
-			return null;
-		}
-
-		return value;
-	}
+    /**
+     * Creates a new `TableHeightCommand` 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, 'tableHeight', defaultValue);
+    }
+    /**
+     * @inheritDoc
+     */
+    _getValueToSet(value) {
+        value = addDefaultUnitToNumericValue(value, 'px');
+        if (value === this._defaultValue) {
+            return;
+        }
+        return value;
+    }
 }

package/src/tableproperties/commands/tablepropertycommand.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @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/commands/tablepropertycommand
+ */
+import type { Batch, Element } from 'ckeditor5/src/engine';
+import { Command, type Editor } from 'ckeditor5/src/core';
+export interface TablePropertyCommandExecuteOptions {
+    batch?: Batch;
+    columnWidths?: string;
+    table?: Element;
+    tableWidth?: string;
+    value?: string;
+}
+/**
+ * The table cell attribute command.
+ *
+ * This command is a base command for other table property commands.
+ */
+export default class TablePropertyCommand extends Command {
+    /**
+     * The attribute that will be set by the command.
+     */
+    readonly attributeName: string;
+    /**
+     * The default value for the attribute.
+     */
+    protected readonly _defaultValue: string | undefined;
+    /**
+     * Creates a new `TablePropertyCommand` 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 the selected table.
+     * If not set, the command will remove the attribute from the selected table.
+     * @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?: TablePropertyCommandExecuteOptions): void;
+    /**
+     * Returns the attribute value for a table.
+     */
+    protected _getValue(table: Element): 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;
+}

package/src/tableproperties/commands/tablepropertycommand.js

@@ -2,123 +2,79 @@
  * @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/commands/tablepropertycommand
- */
-
 import { Command } from 'ckeditor5/src/core';
-
 /**
  * The table cell attribute command.
  *
  * This command is a base command for other table property commands.
- *
- * @extends module:core/command~Command
  */
 export default class TablePropertyCommand extends Command {
-	/**
-	 * Creates a new `TablePropertyCommand` 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 selection = editor.model.document.selection;
-
-		const table = selection.getFirstPosition().findAncestor( 'table' );
-
-		this.isEnabled = !!table;
-		this.value = this._getValue( table );
-	}
-
-	/**
-	 * Executes the command.
-	 *
-	 * @fires execute
-	 * @param {Object} [options]
-	 * @param {*} [options.value] If set, the command will set the attribute on the selected table.
-	 * If not set, the command will remove the attribute from the selected table.
-	 * @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 model = this.editor.model;
-		const selection = model.document.selection;
-
-		const { value, batch } = options;
-
-		const table = selection.getFirstPosition().findAncestor( 'table' );
-		const valueToSet = this._getValueToSet( value );
-
-		model.enqueueChange( batch, writer => {
-			if ( valueToSet ) {
-				writer.setAttribute( this.attributeName, valueToSet, table );
-			} else {
-				writer.removeAttribute( this.attributeName, table );
-			}
-		} );
-	}
-
-	/**
-	 * Returns the attribute value for a table.
-	 *
-	 * @param {module:engine/model/element~Element} table
-	 * @returns {String|undefined}
-	 * @private
-	 */
-	_getValue( table ) {
-		if ( !table ) {
-			return;
-		}
-
-		const value = table.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;
-	}
+    /**
+     * Creates a new `TablePropertyCommand` 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 selection = editor.model.document.selection;
+        const table = selection.getFirstPosition().findAncestor('table');
+        this.isEnabled = !!table;
+        this.value = this._getValue(table);
+    }
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options.value If set, the command will set the attribute on the selected table.
+     * If not set, the command will remove the attribute from the selected table.
+     * @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 model = this.editor.model;
+        const selection = model.document.selection;
+        const { value, batch } = options;
+        const table = selection.getFirstPosition().findAncestor('table');
+        const valueToSet = this._getValueToSet(value);
+        model.enqueueChange(batch, writer => {
+            if (valueToSet) {
+                writer.setAttribute(this.attributeName, valueToSet, table);
+            }
+            else {
+                writer.removeAttribute(this.attributeName, table);
+            }
+        });
+    }
+    /**
+     * Returns the attribute value for a table.
+     */
+    _getValue(table) {
+        if (!table) {
+            return;
+        }
+        const value = table.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;
+    }
 }

package/src/tableproperties/commands/tablewidthcommand.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @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/commands/tablewidthcommand
+ */
+import TablePropertyCommand from './tablepropertycommand';
+import type { Editor } from 'ckeditor5/src/core';
+/**
+ * The table width command.
+ *
+ * The command is registered by the {@link module:table/tableproperties/tablepropertiesediting~TablePropertiesEditing} as
+ * the `'tableWidth'` editor command.
+ *
+ * To change the width of the selected table, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableWidth', {
+ *   value: '400px'
+ * } );
+ * ```
+ *
+ * **Note**: This command adds the default `'px'` unit to numeric values. Executing:
+ *
+ * ```ts
+ * editor.execute( 'tableWidth', {
+ *   value: '50'
+ * } );
+ * ```
+ *
+ * will set the `width` attribute to `'50px'` in the model.
+ */
+export default class TableWidthCommand extends TablePropertyCommand {
+    /**
+     * Creates a new `TableWidthCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param defaultValue The default value of the attribute.
+     */
+    constructor(editor: Editor, defaultValue: string);
+    /**
+     * @inheritDoc
+     */
+    _getValueToSet(value: string | number | undefined): unknown;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        tableWidth: TableWidthCommand;
+    }
+}

package/src/tableproperties/commands/tablewidthcommand.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/tableproperties/commands/tablewidthcommand
  */
-
 import TablePropertyCommand from './tablepropertycommand';
 import { addDefaultUnitToNumericValue } from '../../utils/table-properties';
-
 /**
  * The table width command.
  *
@@ -18,41 +15,40 @@ import { addDefaultUnitToNumericValue } from '../../utils/table-properties';
  *
  * To change the width of the selected table, execute the command:
  *
- *		editor.execute( 'tableWidth', {
- *			value: '400px'
- *		} );
+ * ```ts
+ * editor.execute( 'tableWidth', {
+ *   value: '400px'
+ * } );
+ * ```
  *
  * **Note**: This command adds the default `'px'` unit to numeric values. Executing:
  *
- *		editor.execute( 'tableWidth', {
- *			value: '50'
- *		} );
+ * ```ts
+ * editor.execute( 'tableWidth', {
+ *   value: '50'
+ * } );
+ * ```
  *
  * will set the `width` attribute to `'50px'` in the model.
- *
- * @extends module:table/tableproperties/commands/tablepropertycommand~TablePropertyCommand
  */
 export default class TableWidthCommand extends TablePropertyCommand {
-	/**
-	 * Creates a new `TableWidthCommand` 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, 'tableWidth', defaultValue );
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	_getValueToSet( value ) {
-		value = addDefaultUnitToNumericValue( value, 'px' );
-
-		if ( value === this._defaultValue ) {
-			return;
-		}
-
-		return value;
-	}
+    /**
+     * Creates a new `TableWidthCommand` 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, 'tableWidth', defaultValue);
+    }
+    /**
+     * @inheritDoc
+     */
+    _getValueToSet(value) {
+        value = addDefaultUnitToNumericValue(value, 'px');
+        if (value === this._defaultValue) {
+            return;
+        }
+        return value;
+    }
 }

package/src/tableproperties/tablepropertiesediting.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/tableproperties/tablepropertiesediting
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import '../tableconfig';
+/**
+ * The table properties editing feature.
+ *
+ * Introduces table's model attributes and their conversion:
+ *
+ * - border: `tableBorderStyle`, `tableBorderColor` and `tableBorderWidth`
+ * - background color: `tableBackgroundColor`
+ * - horizontal alignment: `tableAlignment`
+ * - width & height: `tableWidth` & `tableHeight`
+ *
+ * It also registers commands used to manipulate the above attributes:
+ *
+ * - border: `'tableBorderStyle'`, `'tableBorderColor'` and `'tableBorderWidth'` commands
+ * - background color: `'tableBackgroundColor'`
+ * - horizontal alignment: `'tableAlignment'`
+ * - width & height: `'tableWidth'` & `'tableHeight'`
+ */
+export default class TablePropertiesEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'TablePropertiesEditing';
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [TablePropertiesEditing.pluginName]: TablePropertiesEditing;
+    }
+}