@ckeditor/ckeditor5-table 41.3.0 → 41.4.0-alpha.0

package/dist/types/commands/mergecellcommand.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/commands/mergecellcommand
+ */
+import type { Node } from 'ckeditor5/src/engine.js';
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+import type { ArrowKeyCodeDirection } from 'ckeditor5/src/utils.js';
+/**
+ * The merge cell command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'mergeTableCellRight'`, `'mergeTableCellLeft'`,
+ * `'mergeTableCellUp'` and `'mergeTableCellDown'` editor commands.
+ *
+ * To merge a table cell at the current selection with another cell, execute the command corresponding with the preferred direction.
+ *
+ * For example, to merge with a cell to the right:
+ *
+ * ```ts
+ * editor.execute( 'mergeTableCellRight' );
+ * ```
+ *
+ * **Note**: If a table cell has a different [`rowspan`](https://www.w3.org/TR/html50/tabular-data.html#attr-tdth-rowspan)
+ * (for `'mergeTableCellRight'` and `'mergeTableCellLeft'`) or [`colspan`](https://www.w3.org/TR/html50/tabular-data.html#attr-tdth-colspan)
+ * (for `'mergeTableCellUp'` and `'mergeTableCellDown'`), the command will be disabled.
+ */
+export default class MergeCellCommand extends Command {
+    /**
+     * The direction that indicates which cell will be merged with the currently selected one.
+     */
+    readonly direction: ArrowKeyCodeDirection;
+    /**
+     * Whether the merge is horizontal (left/right) or vertical (up/down).
+     */
+    readonly isHorizontal: boolean;
+    /**
+     * @inheritDoc
+     */
+    value: Node | undefined;
+    /**
+     * Creates a new `MergeCellCommand` instance.
+     *
+     * @param editor The editor on which this command will be used.
+     * @param options.direction Indicates which cell to merge with the currently selected one.
+     * Possible values are: `'left'`, `'right'`, `'up'` and `'down'`.
+     */
+    constructor(editor: Editor, options: {
+        direction: ArrowKeyCodeDirection;
+    });
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * Depending on the command's {@link #direction} value, it will merge the cell that is to the `'left'`, `'right'`, `'up'` or `'down'`.
+     *
+     * @fires execute
+     */
+    execute(): void;
+    /**
+     * Returns a cell that can be merged with the current cell depending on the command's direction.
+     */
+    private _getMergeableCell;
+}

package/dist/types/commands/mergecellscommand.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The merge cells command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'mergeTableCells'` editor command.
+ *
+ * For example, to merge selected table cells:
+ *
+ * ```ts
+ * editor.execute( 'mergeTableCells' );
+ * ```
+ */
+export default class MergeCellsCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     */
+    execute(): void;
+}

package/dist/types/commands/removecolumncommand.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/commands/removecolumncommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The remove column command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'removeTableColumn'` editor command.
+ *
+ * To remove the column containing the selected cell, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'removeTableColumn' );
+ * ```
+ */
+export default class RemoveColumnCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * @inheritDoc
+     */
+    execute(): void;
+}

package/dist/types/commands/removerowcommand.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/commands/removerowcommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The remove row command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'removeTableRow'` editor command.
+ *
+ * To remove the row containing the selected cell, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'removeTableRow' );
+ * ```
+ */
+export default class RemoveRowCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * @inheritDoc
+     */
+    execute(): void;
+}

package/dist/types/commands/selectcolumncommand.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/commands/selectcolumncommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+/**
+ * The select column command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'selectTableColumn'` editor command.
+ *
+ * To select the columns containing the selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'selectTableColumn' );
+ * ```
+ */
+export default class SelectColumnCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * @inheritDoc
+     */
+    execute(): void;
+}

package/dist/types/commands/selectrowcommand.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/commands/selectrowcommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+/**
+ * The select row command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'selectTableRow'` editor command.
+ *
+ * To select the rows containing the selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'selectTableRow' );
+ * ```
+ */
+export default class SelectRowCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * @inheritDoc
+     */
+    execute(): void;
+}

package/dist/types/commands/setheadercolumncommand.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/commands/setheadercolumncommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The header column command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'setTableColumnHeader'` editor command.
+ *
+ * You can make the column containing the selected cell a [header](https://www.w3.org/TR/html50/tabular-data.html#the-th-element)
+ * by executing:
+ *
+ * ```ts
+ * editor.execute( 'setTableColumnHeader' );
+ * ```
+ *
+ * **Note:** All preceding columns will also become headers. If the current column is already a header, executing this command
+ * will make it a regular column back again (including the following columns).
+ */
+export default class SetHeaderColumnCommand extends Command {
+    /**
+     * Flag indicating whether the command is active. The command is active when the
+     * {@link module:engine/model/selection~Selection} is in a header column.
+     *
+     * @observable
+     */
+    value: boolean;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * When the selection is in a non-header column, the command will set the `headingColumns` table attribute to cover that column.
+     *
+     * When the selection is already in a header column, it will set `headingColumns` so the heading section will end before that column.
+     *
+     * @fires execute
+     * @param options.forceValue If set, the command will set (`true`) or unset (`false`) the header columns according to
+     * the `forceValue` parameter instead of the current model state.
+     */
+    execute(options?: {
+        forceValue?: boolean;
+    }): void;
+}

package/dist/types/commands/setheaderrowcommand.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/commands/setheaderrowcommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The header row command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'setTableColumnHeader'` editor command.
+ *
+ * You can make the row containing the selected cell a [header](https://www.w3.org/TR/html50/tabular-data.html#the-th-element) by executing:
+ *
+ * ```ts
+ * editor.execute( 'setTableRowHeader' );
+ * ```
+ *
+ * **Note:** All preceding rows will also become headers. If the current row is already a header, executing this command
+ * will make it a regular row back again (including the following rows).
+ */
+export default class SetHeaderRowCommand extends Command {
+    /**
+     * Flag indicating whether the command is active. The command is active when the
+     * {@link module:engine/model/selection~Selection} is in a header row.
+     *
+     * @observable
+     */
+    value: boolean;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * When the selection is in a non-header row, the command will set the `headingRows` table attribute to cover that row.
+     *
+     * When the selection is already in a header row, it will set `headingRows` so the heading section will end before that row.
+     *
+     * @fires execute
+     * @param options.forceValue If set, the command will set (`true`) or unset (`false`) the header rows according to
+     * the `forceValue` parameter instead of the current model state.
+     */
+    execute(options?: {
+        forceValue?: boolean;
+    }): void;
+    /**
+     * Checks if a table cell is in the heading section.
+     */
+    private _isInHeading;
+}

package/dist/types/commands/splitcellcommand.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/commands/splitcellcommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+/**
+ * The split cell command.
+ *
+ * The command is registered by {@link module:table/tableediting~TableEditing} as the `'splitTableCellVertically'`
+ * and `'splitTableCellHorizontally'`  editor commands.
+ *
+ * You can split any cell vertically or horizontally by executing this command. For example, to split the selected table cell vertically:
+ *
+ * ```ts
+ * editor.execute( 'splitTableCellVertically' );
+ * ```
+ */
+export default class SplitCellCommand extends Command {
+    /**
+     * The direction that indicates which cell will be split.
+     */
+    readonly direction: 'horizontally' | 'vertically';
+    /**
+     * Creates a new `SplitCellCommand` instance.
+     *
+     * @param editor The editor on which this command will be used.
+     * @param options.direction Indicates whether the command should split cells `'horizontally'` or `'vertically'`.
+     */
+    constructor(editor: Editor, options?: {
+        direction?: 'horizontally' | 'vertically';
+    });
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * @inheritDoc
+     */
+    execute(): void;
+}

package/dist/types/converters/downcast.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type { Element, ElementCreatorFunction } from 'ckeditor5/src/engine.js';
+import type TableUtils from '../tableutils.js';
+import type { AdditionalSlot } from '../tableediting.js';
+/**
+ * Model table element to view table element conversion helper.
+ */
+export declare function downcastTable(tableUtils: TableUtils, options: DowncastTableOptions): ElementCreatorFunction;
+/**
+ * Model table row element to view `<tr>` element conversion helper.
+ *
+ * @returns Element creator.
+ */
+export declare function downcastRow(): ElementCreatorFunction;
+/**
+ * Model table cell element to view `<td>` or `<th>` element conversion helper.
+ *
+ * This conversion helper will create proper `<th>` elements for table cells that are in the heading section (heading row or column)
+ * and `<td>` otherwise.
+ *
+ * @param options.asWidget If set to `true`, the downcast conversion will produce a widget.
+ * @returns Element creator.
+ */
+export declare function downcastCell(options?: {
+    asWidget?: boolean;
+}): ElementCreatorFunction;
+/**
+ * Overrides paragraph inside table cell conversion.
+ *
+ * This converter:
+ * * should be used to override default paragraph conversion.
+ * * It will only convert `<paragraph>` placed directly inside `<tableCell>`.
+ * * For a single paragraph without attributes it returns `<span>` to simulate data table.
+ * * For all other cases it returns `<p>` element.
+ *
+ * @param options.asWidget If set to `true`, the downcast conversion will produce a widget.
+ * @returns Element creator.
+ */
+export declare function convertParagraphInTableCell(options?: {
+    asWidget?: boolean;
+}): ElementCreatorFunction;
+/**
+ * Checks if given model `<paragraph>` is an only child of a parent (`<tableCell>`) and if it has any attribute set.
+ *
+ * The paragraph should be converted in the editing view to:
+ *
+ * * If returned `true` - to a `<span class="ck-table-bogus-paragraph">`
+ * * If returned `false` - to a `<p>`
+ */
+export declare function isSingleParagraphWithoutAttributes(modelElement: Element): boolean;
+export interface DowncastTableOptions {
+    /**
+     * If set to `true`, the downcast conversion will produce a widget.
+     */
+    asWidget?: boolean;
+    /**
+     * Array of additional slot handlers.
+     */
+    additionalSlots: Array<AdditionalSlot>;
+}

package/dist/types/converters/table-caption-post-fixer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/converters/table-caption-post-fixer
+ */
+import type { Model } from 'ckeditor5/src/engine.js';
+/**
+ * Injects a table caption post-fixer into the model.
+ *
+ * The role of the table caption post-fixer is to ensure that the table with caption have the correct structure
+ * after a {@link module:engine/model/model~Model#change `change()`} block was executed.
+ *
+ * The correct structure means that:
+ *
+ * * If there are many caption model element, they are merged into one model.
+ * * A final, merged caption model is placed at the end of the table.
+ */
+export default function injectTableCaptionPostFixer(model: Model): void;

package/dist/types/converters/table-cell-paragraph-post-fixer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/converters/table-cell-paragraph-post-fixer
+ */
+import type { Model } from 'ckeditor5/src/engine.js';
+/**
+ * Injects a table cell post-fixer into the model which inserts a `paragraph` element into empty table cells.
+ *
+ * A table cell must contain at least one block element as a child. An empty table cell will have an empty `paragraph` as a child.
+ *
+ * ```xml
+ * <table>
+ *   <tableRow>
+ *      <tableCell></tableCell>
+ *   </tableRow>
+ * </table>
+ * ```
+ *
+ * Will be fixed to:
+ *
+ * ```xml
+ * <table>
+ *   <tableRow>
+ *      <tableCell><paragraph></paragraph></tableCell>
+ *   </tableRow>
+ * </table>
+ * ```
+ */
+export default function injectTableCellParagraphPostFixer(model: Model): void;

package/dist/types/converters/table-cell-refresh-handler.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/converters/table-cell-refresh-handler
+ */
+import type { EditingController, Model } from 'ckeditor5/src/engine.js';
+/**
+ * A table cell refresh handler which marks the table cell in the differ to have it re-rendered.
+ *
+ * Model `paragraph` inside a table cell can be rendered as `<span>` or `<p>`. It is rendered as `<span>` if this is the only block
+ * element in that table cell and it does not have any attributes. It is rendered as `<p>` otherwise.
+ *
+ * When table cell content changes, for example a second `paragraph` element is added, we need to ensure that the first `paragraph` is
+ * re-rendered so it changes from `<span>` to `<p>`. The easiest way to do it is to re-render the entire table cell.
+ */
+export default function tableCellRefreshHandler(model: Model, editing: EditingController): void;

package/dist/types/converters/table-headings-refresh-handler.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module table/converters/table-headings-refresh-handler
+ */
+import type { EditingController, Model } from 'ckeditor5/src/engine.js';
+/**
+ * A table headings refresh handler which marks the table cells or rows in the differ to have it re-rendered
+ * if the headings attribute changed.
+ *
+ * Table heading rows and heading columns are represented in the model by a `headingRows` and `headingColumns` attributes.
+ *
+ * When table headings attribute changes, all the cells/rows are marked to re-render to change between `<td>` and `<th>`.
+ */
+export default function tableHeadingsRefreshHandler(model: Model, editing: EditingController): void;