@ckeditor/ckeditor5-table 47.2.0-alpha.7 → 47.3.0-alpha.0

package/src/converters/upcasttable.js

@@ -3,6 +3,7 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 import { createEmptyTableCell } from '../utils/common.js';
+import { getViewTableFromWrapper } from '../utils/structure.js';
 import { first } from 'ckeditor5/src/utils.js';
 /**
  * Returns a function that converts the table view representation:
@@ -27,7 +28,7 @@ export function upcastTableFigure() {
                 return;
             }
             // Find a table element inside the figure element.
-            const viewTable = getViewTableFromFigure(data.viewItem);
+            const viewTable = getViewTableFromWrapper(data.viewItem);
             // Do not convert if table element is absent or was already converted.
             if (!viewTable || !conversionApi.consumable.test(viewTable, { name: true })) {
                 return;
@@ -152,16 +153,6 @@ export function ensureParagraphInTableCell(elementName) {
         }, { priority: 'low' });
     };
 }
-/**
- * Get view `<table>` element from the view widget (`<figure>`).
- */
-function getViewTableFromFigure(figureView) {
-    for (const figureChild of figureView.getChildren()) {
-        if (figureChild.is('element', 'table')) {
-            return figureChild;
-        }
-    }
-}
 /**
  * Scans table rows and extracts required metadata from the table:
  *
@@ -223,11 +214,6 @@ function scanTable(viewTable) {
             }
             else {
                 bodyRows.push(tr);
-                // For other rows check how many column headings this row has.
-                const headingCols = scanRowForHeadingColumns(tr);
-                if (!headingColumns || headingCols < headingColumns) {
-                    headingColumns = headingCols;
-                }
             }
             // We use the maximum number of columns to avoid false positives when detecting
             // multiple rows with single column within `rowspan`. Without it the last row of `rowspan=3`
@@ -235,6 +221,22 @@ function scanTable(viewTable) {
             maxPrevColumns = Math.max(maxPrevColumns || 0, trColumns.length);
         }
     }
+    // Generate the cell matrix so we can calculate the heading columns.
+    const bodyMatrix = generateCellMatrix(bodyRows);
+    for (const rowSlots of bodyMatrix) {
+        // Look for the first non-`<th>` entry (either a `<td>` or a missing cell).
+        let index = 0;
+        while (index < rowSlots.length) {
+            if (rowSlots[index]?.name !== 'th') {
+                break;
+            }
+            index += 1;
+        }
+        // Update headingColumns.
+        if (!headingColumns || index < headingColumns) {
+            headingColumns = index;
+        }
+    }
     return {
         headingRows,
         headingColumns: headingColumns || 0,
@@ -242,26 +244,135 @@ function scanTable(viewTable) {
     };
 }
 /**
- * Scans a `<tr>` element and its children for metadata:
- * - For heading row:
- *     - Adds this row to either the heading or the body rows.
- *     - Updates the number of heading rows.
- * - For body rows:
- *     - Calculates the number of column headings.
+ * Takes an array of `<tr>` elements and generates a "matrix" (square
+ * two-dimensional array) describing which `<th>`s and `<td>`s fill which
+ * "slots", factoring in `rowspan`s and `colspan`s. For example, given
+ *
+ * ```xml
+ * <table>
+ *   <tr> <td>11</td> <td rowspan="2">12-22</td> <td>13</td> </tr>
+ *   <tr> <td>21</td> <td>23</td> </tr>
+ *   <tr> <td colspan="2">31-32</td> <td>33</rd> </tr>
+ * </table>
+ * ```
+ *
+ * The result would be (with cell elements' text content in place of the element
+ * objects for readability):
+ *
+ * ```js
+ * [
+ *   [ '11', '12-22', '13' ],
+ *   [ '21', '12-22', '23' ],
+ *   [ '31-32', '31-32', '33' ],
+ * ]
+ * ```
+ *
+ * This allows for a computation of heading columns that factors in the case
+ * where a cell from a previous rows with a `rowspan` attribute effectively adds
+ * an additional header cell to a subsequent row.
+ *
+ * There are also cases where cells are "missing" from a row. A simple one is
+ * the case where a row simply has fewer cells than another row in the same
+ * table. But another is one where a row has a cell with a `rowspan` that
+ * effectively adds a cell to a subsequent row "off the end" of the row. In this
+ * case, there will be a `null` value instead of an element object in that
+ * position. For example,
+ *
+ * ```xml
+ * <table>
+ *   <tr> <td>11</td> <td>12</td> <td rowspan="2">13-23</td> </tr>
+ *   <tr> <td>21</td> </tr>
+ *   <tr> <td>31</td> </tr>
+ * </table>
+ * ```
+ *
+ * would result in
+ *
+ * ```js
+ * [
+ *   [ '11', '12', '13-23' ],
+ *   [ '21', null, '13-23' ],
+ *   [ '31', null, null ]
+ * ]
+ * ```
+ *
+ * @param trs the array of `<tr>` elements
+ * @returns the cell matrix
  */
-function scanRowForHeadingColumns(tr) {
-    let headingColumns = 0;
-    let index = 0;
-    // Filter out empty text nodes from tr children.
-    const children = Array.from(tr.getChildren())
-        .filter(child => child.name === 'th' || child.name === 'td');
-    // Count starting adjacent <th> elements of a <tr>.
-    while (index < children.length && children[index].name === 'th') {
-        const th = children[index];
-        // Adjust columns calculation by the number of spanned columns.
-        const colspan = parseInt(th.getAttribute('colspan') || '1');
-        headingColumns = headingColumns + colspan;
-        index++;
+function generateCellMatrix(trs) {
+    // As we iterate, we keep track of cells with rowspans >1 so later rows can
+    // factor them in. This trackes any such cells from previous rows.
+    let prevRowspans = new Map();
+    // This is the maximum number of columns we've encountered.
+    let maxColumns = 0;
+    const slots = trs.map(tr => {
+        // This will be the slots that are in this row, including cells from
+        // previous rows with a big enough "rowspan" to affect this row.
+        const curSlots = [];
+        // Get the cell elements
+        const children = Array.from(tr.getChildren())
+            .filter(child => child.name === 'th' || child.name === 'td');
+        // This will be any cells in this row that have a rowspan >1, so we can
+        // combine it with `prevRowspans` when we're done processing this row.
+        const curRowspans = new Map();
+        // We need to process all the cells in this row, but also previous rows'
+        // cells with rowspans might add additional slots to the end of this row, so
+        // we need to iterate until we've both consumed all the children _and_
+        // filled out slots to the max number of columns we've encountered so far.
+        while (children.length || curSlots.length < maxColumns) {
+            const rowSpan = prevRowspans.get(curSlots.length);
+            if (rowSpan && rowSpan.remaining > 0) {
+                // We have a cell at this index in a previous row whose rowspan extends
+                // it into this row, so we insert a copy of it here.
+                curSlots.push(rowSpan.cell);
+            }
+            else {
+                // See if we have more cells in the row.
+                const cell = children.shift();
+                if (cell) {
+                    // We do, so process it
+                    const colspan = parseInt(cell.getAttribute('colspan') || '1');
+                    const rowspan = parseInt(cell.getAttribute('rowspan') || '1');
+                    // Process this cell as many times as needed according to its colspan.
+                    for (let i = 0; i < colspan; i++) {
+                        // if we have a >1 rowspan, create a record in the rowSpans map for
+                        // this column index keeping track of it.
+                        if (rowspan > 1) {
+                            curRowspans.set(curSlots.length, { cell, remaining: rowspan - 1 });
+                        }
+                        curSlots.push(cell);
+                    }
+                }
+                else {
+                    // No remaining children in this row, so no cell in this slot.
+                    curSlots.push(null);
+                    continue;
+                }
+            }
+        }
+        // Now update the row spans. In weird edge cases where colspan and rowspan
+        // conflict, we can end up with a cell in a column in this row that
+        // "truncates" a row-spanning cell from a previous column, so make sure in
+        // those cases, the value in `curRowspans` always "wins". We do this by
+        // copying (and decrementing) values from `prevRowspans` into `curRowspans`
+        // as long as there is no conflict, and then re-assigning `prevRowspans`.
+        for (const [index, entry] of prevRowspans.entries()) {
+            entry.remaining -= 1;
+            if (entry.remaining > 0 && !curRowspans.has(index)) {
+                curRowspans.set(index, entry);
+            }
+        }
+        prevRowspans = curRowspans;
+        // Finally, update `maxColumns`.
+        maxColumns = Math.max(maxColumns, curSlots.length);
+        return curSlots;
+    });
+    // Now expand any rows that have fewer than `maxColumns` with nulls so we have
+    // a proper matrix.
+    for (const rowSlots of slots) {
+        while (rowSlots.length < maxColumns) {
+            rowSlots.push(null);
+        }
     }
-    return headingColumns;
+    return slots;
 }

package/src/index.d.ts

@@ -34,6 +34,10 @@ export { TableUtils, type TableIndexesObject } from './tableutils.js';
 export { TableColumnResize } from './tablecolumnresize.js';
 export { TableColumnResizeEditing } from './tablecolumnresize/tablecolumnresizeediting.js';
 export { TableWidthsCommand, type TableWidthsCommandOptions } from './tablecolumnresize/tablewidthscommand.js';
+export { TablePropertiesUIExperimental } from './tableproperties/tablepropertiesuiexperimental.js';
+export { TablePropertiesViewExperimental, type TablePropertiesViewOptionsExperimental } from './tableproperties/ui/tablepropertiesviewexperimental.js';
+export { TableCellPropertiesUIExperimental } from './tablecellproperties/tablecellpropertiesuiexperimental.js';
+export { TableCellPropertiesViewExperimental, type TableCellPropertiesViewOptionsExperimental } from './tablecellproperties/ui/tablecellpropertiesviewexperimental.js';
 export { InsertColumnCommand } from './commands/insertcolumncommand.js';
 export { InsertRowCommand } from './commands/insertrowcommand.js';
 export { InsertTableCommand } from './commands/inserttablecommand.js';
@@ -68,7 +72,7 @@ export { TableHeightCommand } from './tableproperties/commands/tableheightcomman
 export { TableWidthCommand } from './tableproperties/commands/tablewidthcommand.js';
 export { TablePropertyCommand, type TablePropertyCommandExecuteOptions } from './tableproperties/commands/tablepropertycommand.js';
 export type { ViewDocumentTableMouseMoveEvent, ViewDocumentTableMouseLeaveEvent } from './tablemouse/mouseeventsobserver.js';
-export type { TableConfig, TablePropertiesConfig, TablePropertiesOptions, TableCellPropertiesConfig, TableColorConfig, TableCellPropertiesOptions, TableLayoutConfig, TableCaptionConfig, TableType } from './tableconfig.js';
+export type { TableConfig, TableAlignmentConfig, TablePropertiesConfig, TablePropertiesOptions, TableCellPropertiesConfig, TableColorConfig, TableCellPropertiesOptions, TableLayoutConfig, TableCaptionConfig, TableType } from './tableconfig.js';
 export { downcastTable as _downcastTable, downcastRow as _downcastTableRow, downcastCell as _downcastTableCell, convertParagraphInTableCell as _convertParagraphInTableCell, isSingleParagraphWithoutAttributes as _isSingleTableParagraphWithoutAttributes } from './converters/downcast.js';
 export type { DowncastTableOptions as _DowncastTableOptions } from './converters/downcast.js';
 export { injectTableCaptionPostFixer as _injectTableCaptionPostFixer } from './converters/table-caption-post-fixer.js';

package/src/index.js

@@ -34,6 +34,11 @@ export { TableUtils } from './tableutils.js';
 export { TableColumnResize } from './tablecolumnresize.js';
 export { TableColumnResizeEditing } from './tablecolumnresize/tablecolumnresizeediting.js';
 export { TableWidthsCommand } from './tablecolumnresize/tablewidthscommand.js';
+// [experimental] Remove in the v48.
+export { TablePropertiesUIExperimental } from './tableproperties/tablepropertiesuiexperimental.js';
+export { TablePropertiesViewExperimental } from './tableproperties/ui/tablepropertiesviewexperimental.js';
+export { TableCellPropertiesUIExperimental } from './tablecellproperties/tablecellpropertiesuiexperimental.js';
+export { TableCellPropertiesViewExperimental } from './tablecellproperties/ui/tablecellpropertiesviewexperimental.js';
 export { InsertColumnCommand } from './commands/insertcolumncommand.js';
 export { InsertRowCommand } from './commands/insertrowcommand.js';
 export { InsertTableCommand } from './commands/inserttablecommand.js';

package/src/plaintableoutput.js

@@ -37,28 +37,6 @@ export class PlainTableOutput extends Plugin {
      */
     init() {
         const editor = this.editor;
-        // Override default table data downcast converter.
-        editor.conversion.for('dataDowncast').elementToStructure({
-            model: 'table',
-            view: downcastTableElement,
-            converterPriority: 'high'
-        });
-        // Make sure table <caption> is downcasted into <caption> in the data pipeline when necessary.
-        if (editor.plugins.has('TableCaption')) {
-            editor.conversion.for('dataDowncast').elementToElement({
-                model: 'caption',
-                view: (modelElement, { writer }) => {
-                    if (modelElement.parent.name === 'table') {
-                        return writer.createContainerElement('caption');
-                    }
-                },
-                converterPriority: 'high'
-            });
-        }
-        // Handle border-style, border-color, border-width and background-color table attributes.
-        if (editor.plugins.has('TableProperties')) {
-            downcastTableBorderAndBackgroundAttributes(editor);
-        }
         editor.conversion.for('upcast').add(dispatcher => {
             dispatcher.on('element:table', (evt, data, conversionApi) => {
                 // It's not necessary to upcast the `table` class. This class was only added in data downcast
@@ -69,72 +47,3 @@ export class PlainTableOutput extends Plugin {
         });
     }
 }
-/**
- * The plain table downcast converter callback.
- *
- * @param table Table model element.
- * @param conversionApi The conversion API object.
- * @returns Created element.
- */
-function downcastTableElement(table, { writer }) {
-    const headingRows = table.getAttribute('headingRows') || 0;
-    // Table head rows slot.
-    const headRowsSlot = writer.createSlot((element) => element.is('element', 'tableRow') && element.index < headingRows);
-    // Table body rows slot.
-    const bodyRowsSlot = writer.createSlot((element) => element.is('element', 'tableRow') && element.index >= headingRows);
-    // Table children slot.
-    const childrenSlot = writer.createSlot((element) => !element.is('element', 'tableRow'));
-    // Table <thead> element with all the heading rows.
-    const theadElement = writer.createContainerElement('thead', null, headRowsSlot);
-    // Table <tbody> element with all the body rows.
-    const tbodyElement = writer.createContainerElement('tbody', null, bodyRowsSlot);
-    // Table contents element containing <thead> and <tbody> when necessary.
-    const tableContentElements = [];
-    if (headingRows) {
-        tableContentElements.push(theadElement);
-    }
-    if (headingRows < table.childCount) {
-        tableContentElements.push(tbodyElement);
-    }
-    // Create table structure.
-    //
-    // <table>
-    //    {children-slot-like-caption}
-    //    <thead>
-    //        {table-head-rows-slot}
-    //    </thead>
-    //    <tbody>
-    //        {table-body-rows-slot}
-    //    </tbody>
-    // </table>
-    return writer.createContainerElement('table', { class: 'table' }, [childrenSlot, ...tableContentElements]);
-}
-/**
- * Register table border and background attributes converters.
- */
-function downcastTableBorderAndBackgroundAttributes(editor) {
-    const modelAttributes = {
-        'border-width': 'tableBorderWidth',
-        'border-color': 'tableBorderColor',
-        'border-style': 'tableBorderStyle',
-        'background-color': 'tableBackgroundColor'
-    };
-    for (const [styleName, modelAttribute] of Object.entries(modelAttributes)) {
-        editor.conversion.for('dataDowncast').add(dispatcher => {
-            return dispatcher.on(`attribute:${modelAttribute}:table`, (evt, data, conversionApi) => {
-                const { item, attributeNewValue } = data;
-                const { mapper, writer } = conversionApi;
-                if (!conversionApi.consumable.consume(item, evt.name)) {
-                    return;
-                }
-                const table = mapper.toViewElement(item);
-                if (attributeNewValue) {
-                    writer.setStyle(styleName, attributeNewValue, table);
-                }
-                else {
-                    writer.removeStyle(styleName, table);
-                }
-            }, { priority: 'high' });
-        });
-    }
-}

package/src/tablecellproperties/tablecellpropertiesediting.js

@@ -88,7 +88,7 @@ export class TableCellPropertiesEditing extends Plugin {
             isRightToLeftContent: editor.locale.contentLanguageDirection === 'rtl'
         });
         editor.data.addStyleProcessorRules(addBorderStylesRules);
-        enableBorderProperties(schema, conversion, {
+        enableBorderProperties(editor, {
             color: defaultTableCellProperties.borderColor,
             style: defaultTableCellProperties.borderStyle,
             width: defaultTableCellProperties.borderWidth
@@ -130,12 +130,15 @@ export class TableCellPropertiesEditing extends Plugin {
 /**
  * Enables the `'tableCellBorderStyle'`, `'tableCellBorderColor'` and `'tableCellBorderWidth'` attributes for table cells.
  *
+ * @param editor The editor instance.
  * @param defaultBorder The default border values.
  * @param defaultBorder.color The default `tableCellBorderColor` value.
  * @param defaultBorder.style The default `tableCellBorderStyle` value.
  * @param defaultBorder.width The default `tableCellBorderWidth` value.
  */
-function enableBorderProperties(schema, conversion, defaultBorder) {
+function enableBorderProperties(editor, defaultBorder) {
+    const { conversion } = editor;
+    const { schema } = editor.model;
     const modelAttributes = {
         width: 'tableCellBorderWidth',
         color: 'tableCellBorderColor',
@@ -147,8 +150,8 @@ function enableBorderProperties(schema, conversion, defaultBorder) {
     for (const modelAttribute of Object.values(modelAttributes)) {
         schema.setAttributeProperties(modelAttribute, { isFormatting: true });
     }
-    upcastBorderStyles(conversion, 'td', modelAttributes, defaultBorder);
-    upcastBorderStyles(conversion, 'th', modelAttributes, defaultBorder);
+    upcastBorderStyles(editor, 'td', modelAttributes, defaultBorder);
+    upcastBorderStyles(editor, 'th', modelAttributes, defaultBorder);
     downcastAttributeToStyle(conversion, { modelElement: 'tableCell', modelAttribute: modelAttributes.style, styleName: 'border-style' });
     downcastAttributeToStyle(conversion, { modelElement: 'tableCell', modelAttribute: modelAttributes.color, styleName: 'border-color' });
     downcastAttributeToStyle(conversion, { modelElement: 'tableCell', modelAttribute: modelAttributes.width, styleName: 'border-width' });

package/src/tablecellproperties/tablecellpropertiesuiexperimental.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+ */
+/**
+ * @module table/tablecellproperties/tablecellpropertiesuiexperimental
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import { ContextualBalloon } from 'ckeditor5/src/ui.js';
+import { TableCellPropertiesViewExperimental } from './ui/tablecellpropertiesviewexperimental.js';
+/**
+ * The table cell properties UI plugin. It introduces the `'tableCellProperties'` button
+ * that opens a form allowing to specify the visual styling of a table cell.
+ *
+ * It uses the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon plugin}.
+ */
+export declare class TableCellPropertiesUIExperimental extends Plugin {
+    /**
+     * The default table cell properties.
+     */
+    private _defaultContentTableCellProperties;
+    /**
+     * The default layout table cell properties.
+     */
+    private _defaultLayoutTableCellProperties;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon?;
+    /**
+     * The cell properties form view displayed inside the balloon.
+     */
+    view?: TableCellPropertiesViewExperimental | null;
+    /**
+     * The cell properties form view displayed inside the balloon (content table).
+     */
+    private _viewWithContentTableDefaults?;
+    /**
+     * The cell properties form view displayed inside the balloon (layout table).
+     */
+    private _viewWithLayoutTableDefaults?;
+    /**
+     * 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(): readonly [typeof ContextualBalloon];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableCellPropertiesUIExperimental";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates the {@link module:table/tablecellproperties/ui/tablecellpropertiesview~TableCellPropertiesView} instance.
+     *
+     * @returns The cell properties form view instance.
+     */
+    private _createPropertiesView;
+    /**
+     * In this method the "editor data -> UI" binding is happening.
+     *
+     * When executed, this method obtains selected cell 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, a new {@link #_undoStepBatch} is created. It 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 cell is no longer selected.
+     */
+    protected _updateView(): void;
+    /**
+     * Returns `true` when the {@link #view} is 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 the {@link #view view's} property change
+     * executes a related editor command with the new property value.
+     *
+     * @param commandName The default value of the command.
+     */
+    private _getPropertyChangeCallback;
+    /**
+     * Creates a callback that when executed upon the {@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;
+}