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

package/src/tablecaption/toggletablecaptioncommand.js

@@ -2,15 +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/tablecaption/toggletablecaptioncommand
 */
-
 import { Command } from 'ckeditor5/src/core';
-
 import { getCaptionFromTableModelElement, getSelectionAffectedTable } from './utils';
-
 /**
  * The toggle table caption command.
  *
@@ -22,98 +18,87 @@ import { getCaptionFromTableModelElement, getSelectionAffectedTable } from './ut
  * * either adds or removes the table caption of a selected table (depending on whether the caption is present or not),
  * * removes the table caption if the selection is anchored in one.
  *
- *		// Toggle the presence of the caption.
- *		editor.execute( 'toggleTableCaption' );
+ * ```ts
+ * // Toggle the presence of the caption.
+ * editor.execute( 'toggleTableCaption' );
+ * ```
  *
  * **Note**: You can move the selection to the caption right away as it shows up upon executing this command by using
  * the `focusCaptionOnShow` option:
  *
- *		editor.execute( 'toggleTableCaption', { focusCaptionOnShow: true } );
- *
- * @extends module:core/command~Command
+ * ```ts
+ * editor.execute( 'toggleTableCaption', { focusCaptionOnShow: true } );
+ * ```
  */
 export default class ToggleTableCaptionCommand extends Command {
-	/**
-	 * @inheritDoc
-	 */
-	refresh() {
-		const editor = this.editor;
-		const tableElement = getSelectionAffectedTable( editor.model.document.selection );
-
-		this.isEnabled = !!tableElement;
-
-		if ( !this.isEnabled ) {
-			this.value = false;
-		} else {
-			this.value = !!getCaptionFromTableModelElement( tableElement );
-		}
-	}
-
-	/**
-	 * Executes the command.
-	 *
-	 *		editor.execute( 'toggleTableCaption' );
-	 *
-	 * @param {Object} [options] Options for the executed command.
-	 * @param {String} [options.focusCaptionOnShow] When true and the caption shows up, the selection will be moved into it straight away.
-	 * @fires execute
-	 */
-	execute( options = {} ) {
-		const { focusCaptionOnShow } = options;
-
-		this.editor.model.change( writer => {
-			if ( this.value ) {
-				this._hideTableCaption( writer );
-			} else {
-				this._showTableCaption( writer, focusCaptionOnShow );
-			}
-		} );
-	}
-
-	/**
-	 * Shows the table caption. Also:
-	 *
-	 * * it attempts to restore the caption content from the `TableCaptionEditing` caption registry,
-	 * * it moves the selection to the caption right away, it the `focusCaptionOnShow` option was set.
-	 *
-	 * @private
-	 * @param {module:engine/model/writer~Writer} writer
-	 * @param {Boolean} focusCaptionOnShow Default focus behavior when showing the caption.
-	 */
-	_showTableCaption( writer, focusCaptionOnShow ) {
-		const model = this.editor.model;
-		const tableElement = getSelectionAffectedTable( model.document.selection );
-		const tableCaptionEditing = this.editor.plugins.get( 'TableCaptionEditing' );
-		const savedCaptionElement = tableCaptionEditing._getSavedCaption( tableElement );
-
-		// Try restoring the caption from the TableCaptionEditing plugin storage.
-		const newCaptionElement = savedCaptionElement || writer.createElement( 'caption' );
-
-		model.insertContent( newCaptionElement, tableElement, 'end' );
-
-		if ( focusCaptionOnShow ) {
-			writer.setSelection( newCaptionElement, 'in' );
-		}
-	}
-
-	/**
-	 * Hides the caption of a selected table (or an table caption the selection is anchored to).
-	 *
-	 * The content of the caption is stored in the `TableCaptionEditing` caption registry to make this
-	 * a reversible action.
-	 *
-	 * @private
-	 * @param {module:engine/model/writer~Writer} writer
-	 */
-	_hideTableCaption( writer ) {
-		const model = this.editor.model;
-		const tableElement = getSelectionAffectedTable( model.document.selection );
-		const tableCaptionEditing = this.editor.plugins.get( 'TableCaptionEditing' );
-		const captionElement = getCaptionFromTableModelElement( tableElement );
-
-		// Store the caption content so it can be restored quickly if the user changes their mind.
-		tableCaptionEditing._saveCaption( tableElement, captionElement );
-
-		model.deleteContent( writer.createSelection( captionElement, 'on' ) );
-	}
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const editor = this.editor;
+        const tableElement = getSelectionAffectedTable(editor.model.document.selection);
+        this.isEnabled = !!tableElement;
+        if (!this.isEnabled) {
+            this.value = false;
+        }
+        else {
+            this.value = !!getCaptionFromTableModelElement(tableElement);
+        }
+    }
+    /**
+     * Executes the command.
+     *
+     * ```ts
+     * editor.execute( 'toggleTableCaption' );
+     * ```
+     *
+     * @param options Options for the executed command.
+     * @param options.focusCaptionOnShow When true and the caption shows up, the selection will be moved into it straight away.
+     * @fires execute
+     */
+    execute({ focusCaptionOnShow = false } = {}) {
+        this.editor.model.change(writer => {
+            if (this.value) {
+                this._hideTableCaption(writer);
+            }
+            else {
+                this._showTableCaption(writer, focusCaptionOnShow);
+            }
+        });
+    }
+    /**
+     * Shows the table caption. Also:
+     *
+     * * it attempts to restore the caption content from the `TableCaptionEditing` caption registry,
+     * * it moves the selection to the caption right away, it the `focusCaptionOnShow` option was set.
+     *
+     * @param focusCaptionOnShow Default focus behavior when showing the caption.
+     */
+    _showTableCaption(writer, focusCaptionOnShow) {
+        const model = this.editor.model;
+        const tableElement = getSelectionAffectedTable(model.document.selection);
+        const tableCaptionEditing = this.editor.plugins.get('TableCaptionEditing');
+        const savedCaptionElement = tableCaptionEditing._getSavedCaption(tableElement);
+        // Try restoring the caption from the TableCaptionEditing plugin storage.
+        const newCaptionElement = savedCaptionElement || writer.createElement('caption');
+        model.insertContent(newCaptionElement, tableElement, 'end');
+        if (focusCaptionOnShow) {
+            writer.setSelection(newCaptionElement, 'in');
+        }
+    }
+    /**
+     * Hides the caption of a selected table (or an table caption the selection is anchored to).
+     *
+     * The content of the caption is stored in the `TableCaptionEditing` caption registry to make this
+     * a reversible action.
+     */
+    _hideTableCaption(writer) {
+        const model = this.editor.model;
+        const tableElement = getSelectionAffectedTable(model.document.selection);
+        const tableCaptionEditing = this.editor.plugins.get('TableCaptionEditing');
+        const captionElement = getCaptionFromTableModelElement(tableElement);
+        // Store the caption content so it can be restored quickly if the user changes their mind.
+        tableCaptionEditing._saveCaption(tableElement, captionElement);
+        model.deleteContent(writer.createSelection(captionElement, 'on'));
+    }
 }

package/src/tablecaption/utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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/tablecaption/utils
+ */
+import type { DocumentFragment, DocumentSelection, Element, ViewElement } from 'ckeditor5/src/engine';
+/**
+ * Checks if the provided model element is a `table`.
+ *
+ * @param modelElement Element to check if it is a table.
+ */
+export declare function isTable(modelElement: Element | DocumentFragment | null): boolean;
+/**
+ * Returns the caption model element from a given table element. Returns `null` if no caption is found.
+ *
+ * @param tableModelElement Table element in which we will try to find a caption element.
+ */
+export declare function getCaptionFromTableModelElement(tableModelElement: Element): Element | null;
+/**
+ * Returns the caption model element for a model selection. Returns `null` if the selection has no caption element ancestor.
+ *
+ * @param selection The selection checked for caption presence.
+ */
+export declare function getCaptionFromModelSelection(selection: DocumentSelection): Element | null;
+/**
+ * {@link module:engine/view/matcher~Matcher} pattern. Checks if a given element is a caption.
+ *
+ * There are two possible forms of the valid caption:
+ *  - A `<figcaption>` element inside a `<figure class="table">` element.
+ *  - A `<caption>` inside a <table>.
+ *
+ * @returns Returns the object accepted by {@link module:engine/view/matcher~Matcher} or `null` if the element cannot be matched.
+ */
+export declare function matchTableCaptionViewElement(element: ViewElement): {
+    name: true;
+} | null;
+/**
+ * Depending on the position of the selection we either return the table under cursor or look for the table higher in the hierarchy.
+ */
+export declare function getSelectionAffectedTable(selection: DocumentSelection): Element;

package/src/tablecaption/utils.js

@@ -2,54 +2,39 @@
  * @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/tablecaption/utils
- */
-
 /**
  * Checks if the provided model element is a `table`.
  *
- * @param {module:engine/model/element~Element} modelElement Element to check if it is a table.
- * @returns {Boolean}
+ * @param modelElement Element to check if it is a table.
  */
-export function isTable( modelElement ) {
-	return !!modelElement && modelElement.is( 'element', 'table' );
+export function isTable(modelElement) {
+    return !!modelElement && modelElement.is('element', 'table');
 }
-
 /**
  * Returns the caption model element from a given table element. Returns `null` if no caption is found.
  *
- * @param {module:engine/model/element~Element} tableModelElement Table element in which we will try to find a caption element.
- * @returns {module:engine/model/element~Element|null}
+ * @param tableModelElement Table element in which we will try to find a caption element.
  */
-export function getCaptionFromTableModelElement( tableModelElement ) {
-	for ( const node of tableModelElement.getChildren() ) {
-		if ( node.is( 'element', 'caption' ) ) {
-			return node;
-		}
-	}
-
-	return null;
+export function getCaptionFromTableModelElement(tableModelElement) {
+    for (const node of tableModelElement.getChildren()) {
+        if (node.is('element', 'caption')) {
+            return node;
+        }
+    }
+    return null;
 }
-
 /**
  * Returns the caption model element for a model selection. Returns `null` if the selection has no caption element ancestor.
  *
- * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
- * The selection checked for caption presence.
- * @returns {module:engine/model/element~Element|null}
+ * @param selection The selection checked for caption presence.
  */
-export function getCaptionFromModelSelection( selection ) {
-	const tableElement = getSelectionAffectedTable( selection );
-
-	if ( !tableElement ) {
-		return null;
-	}
-
-	return getCaptionFromTableModelElement( tableElement );
+export function getCaptionFromModelSelection(selection) {
+    const tableElement = getSelectionAffectedTable(selection);
+    if (!tableElement) {
+        return null;
+    }
+    return getCaptionFromTableModelElement(tableElement);
 }
-
 /**
  * {@link module:engine/view/matcher~Matcher} pattern. Checks if a given element is a caption.
  *
@@ -57,37 +42,26 @@ export function getCaptionFromModelSelection( selection ) {
  *  - A `<figcaption>` element inside a `<figure class="table">` element.
  *  - A `<caption>` inside a <table>.
  *
- * @param {module:engine/view/element~Element} element
- * @returns {Object|null} Returns the object accepted by {@link module:engine/view/matcher~Matcher} or `null` if the element
- * cannot be matched.
+ * @returns Returns the object accepted by {@link module:engine/view/matcher~Matcher} or `null` if the element cannot be matched.
  */
-export function matchTableCaptionViewElement( element ) {
-	const parent = element.parent;
-
-	if ( element.name == 'figcaption' && parent && parent.name == 'figure' && parent.hasClass( 'table' ) ) {
-		return { name: true };
-	}
-
-	if ( element.name == 'caption' && parent && parent.name == 'table' ) {
-		return { name: true };
-	}
-
-	return null;
+export function matchTableCaptionViewElement(element) {
+    const parent = element.parent;
+    if (element.name == 'figcaption' && parent && parent.is('element', 'figure') && parent.hasClass('table')) {
+        return { name: true };
+    }
+    if (element.name == 'caption' && parent && parent.is('element', 'table')) {
+        return { name: true };
+    }
+    return null;
 }
-
 /**
  * Depending on the position of the selection we either return the table under cursor or look for the table higher in the hierarchy.
- *
- * @param {module:engine/model/position~Position} position
- * @returns {module:engine/model/element~Element}
  */
-export function getSelectionAffectedTable( selection ) {
-	const selectedElement = selection.getSelectedElement();
-
-	// Is the command triggered from the `tableToolbar`?
-	if ( selectedElement && selectedElement.is( 'element', 'table' ) ) {
-		return selectedElement;
-	}
-
-	return selection.getFirstPosition().findAncestor( 'table' );
+export function getSelectionAffectedTable(selection) {
+    const selectedElement = selection.getSelectedElement();
+    // Is the command triggered from the `tableToolbar`?
+    if (selectedElement && selectedElement.is('element', 'table')) {
+        return selectedElement;
+    }
+    return selection.getFirstPosition().findAncestor('table');
 }

package/src/tablecaption.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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/tablecaption
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import '../theme/tablecaption.css';
+/**
+ * The table caption plugin.
+ */
+export default class TableCaption extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'TableCaption';
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [TableCaption.pluginName]: TableCaption;
+    }
+}

package/src/tablecaption.js

@@ -2,34 +2,27 @@
  * @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/tablecaption
  */
-
 import { Plugin } from 'ckeditor5/src/core';
 import TableCaptionEditing from './tablecaption/tablecaptionediting';
 import TableCaptionUI from './tablecaption/tablecaptionui';
-
 import '../theme/tablecaption.css';
-
 /**
  * The table caption plugin.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class TableCaption extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'TableCaption';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	static get requires() {
-		return [ TableCaptionEditing, TableCaptionUI ];
-	}
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'TableCaption';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [TableCaptionEditing, TableCaptionUI];
+    }
 }

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

@@ -0,0 +1,37 @@
+/**
+ * @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/tablecellbackgroundcolorcommand
+ */
+import type { Editor } from 'ckeditor5/src/core';
+import TableCellPropertyCommand from './tablecellpropertycommand';
+/**
+ * The table cell background color command.
+ *
+ * The command is registered by the {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing} as
+ * the `'tableCellBackgroundColor'` editor command.
+ *
+ * To change the background color of selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableCellBackgroundColor', {
+ *   value: '#f00'
+ * } );
+ * ```
+ */
+export default class TableCellBackgroundColorCommand extends TableCellPropertyCommand {
+    /**
+     * Creates a new `TableCellBackgroundColorCommand` 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);
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        tableCellBackgroundColor: TableCellBackgroundColorCommand;
+    }
+}

package/src/tablecellproperties/commands/tablecellbackgroundcolorcommand.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/tablecellbackgroundcolorcommand
- */
-
 import TableCellPropertyCommand from './tablecellpropertycommand';
-
 /**
  * The table cell background color command.
  *
@@ -17,20 +11,20 @@ import TableCellPropertyCommand from './tablecellpropertycommand';
  *
  * To change the background color of selected cells, execute the command:
  *
- *		editor.execute( 'tableCellBackgroundColor', {
- *			value: '#f00'
- *		} );
- *
- * @extends module:table/tablecellproperties/commands/tablecellpropertycommand~TableCellPropertyCommand
+ * ```ts
+ * editor.execute( 'tableCellBackgroundColor', {
+ *   value: '#f00'
+ * } );
+ * ```
  */
 export default class TableCellBackgroundColorCommand extends TableCellPropertyCommand {
-	/**
-	 * Creates a new `TableCellBackgroundColorCommand` 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, 'tableCellBackgroundColor', defaultValue );
-	}
+    /**
+     * Creates a new `TableCellBackgroundColorCommand` 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, 'tableCellBackgroundColor', defaultValue);
+    }
 }

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

@@ -0,0 +1,42 @@
+/**
+ * @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/tablecellbordercolorcommand
+ */
+import type { Element } from 'ckeditor5/src/engine';
+import type { Editor } from 'ckeditor5/src/core';
+import TableCellPropertyCommand from './tablecellpropertycommand';
+/**
+ * The table cell border color command.
+ *
+ * The command is registered by the {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing} as
+ * the `'tableCellBorderColor'` editor command.
+ *
+ * To change the border color of selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableCellBorderColor', {
+ *   value: '#f00'
+ * } );
+ * ```
+ */
+export default class TableCellBorderColorCommand extends TableCellPropertyCommand {
+    /**
+     * Creates a new `TableCellBorderColorCommand` 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
+     */
+    protected _getAttribute(tableCell: Element): unknown;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface CommandsMap {
+        tableCellBorderColor: TableCellBorderColorCommand;
+    }
+}

package/src/tablecellproperties/commands/tablecellbordercolorcommand.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/tablecellbordercolorcommand
- */
-
 import TableCellPropertyCommand from './tablecellpropertycommand';
 import { getSingleValue } from '../../utils/table-properties';
-
 /**
  * The table cell border color command.
  *
@@ -18,37 +12,33 @@ import { getSingleValue } from '../../utils/table-properties';
  *
  * To change the border color of selected cells, execute the command:
  *
- *		editor.execute( 'tableCellBorderColor', {
- *			value: '#f00'
- *		} );
- *
- * @extends module:table/tablecellproperties/commands/tablecellpropertycommand~TableCellPropertyCommand
+ * ```ts
+ * editor.execute( 'tableCellBorderColor', {
+ *   value: '#f00'
+ * } );
+ * ```
  */
 export default class TableCellBorderColorCommand extends TableCellPropertyCommand {
-	/**
-	 * Creates a new `TableCellBorderColorCommand` 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, 'tableCellBorderColor', defaultValue );
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	_getAttribute( tableCell ) {
-		if ( !tableCell ) {
-			return;
-		}
-
-		const value = getSingleValue( tableCell.getAttribute( this.attributeName ) );
-
-		if ( value === this._defaultValue ) {
-			return;
-		}
-
-		return value;
-	}
+    /**
+     * Creates a new `TableCellBorderColorCommand` 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, 'tableCellBorderColor', defaultValue);
+    }
+    /**
+     * @inheritDoc
+     */
+    _getAttribute(tableCell) {
+        if (!tableCell) {
+            return;
+        }
+        const value = getSingleValue(tableCell.getAttribute(this.attributeName));
+        if (value === this._defaultValue) {
+            return;
+        }
+        return value;
+    }
 }