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

package/src/tableproperties/tablepropertiesediting.js

@@ -6,9 +6,10 @@
  * @module table/tableproperties/tablepropertiesediting
  */
 import { Plugin } from 'ckeditor5/src/core.js';
-import { addBackgroundStylesRules, addBorderStylesRules } from 'ckeditor5/src/engine.js';
+import { addBackgroundStylesRules, addBorderStylesRules, addMarginStylesRules } from 'ckeditor5/src/engine.js';
+import { first } from 'ckeditor5/src/utils.js';
 import { TableEditing } from '../tableediting.js';
-import { downcastAttributeToStyle, downcastTableAttribute, getDefaultValueAdjusted, upcastBorderStyles, upcastStyleToAttribute } from '../converters/tableproperties.js';
+import { downcastAttributeToStyle, downcastTableAttribute, getDefaultValueAdjusted, upcastBorderStyles, upcastStyleToAttribute, upcastTableAlignmentConfig, DEFAULT_TABLE_ALIGNMENT_OPTIONS } from '../converters/tableproperties.js';
 import { TableBackgroundColorCommand } from './commands/tablebackgroundcolorcommand.js';
 import { TableBorderColorCommand } from './commands/tablebordercolorcommand.js';
 import { TableBorderStyleCommand } from './commands/tableborderstylecommand.js';
@@ -17,8 +18,7 @@ import { TableWidthCommand } from './commands/tablewidthcommand.js';
 import { TableHeightCommand } from './commands/tableheightcommand.js';
 import { TableAlignmentCommand } from './commands/tablealignmentcommand.js';
 import { getNormalizedDefaultTableProperties } from '../utils/table-properties.js';
-const ALIGN_VALUES_REG_EXP = /^(left|center|right)$/;
-const FLOAT_VALUES_REG_EXP = /^(left|none|right)$/;
+import { getViewTableFromWrapper } from '../utils/structure.js';
 /**
  * The table properties editing feature.
  *
@@ -79,8 +79,10 @@ export class TablePropertiesEditing extends Plugin {
         const defaultTableProperties = getNormalizedDefaultTableProperties(editor.config.get('table.tableProperties.defaultProperties'), {
             includeAlignmentProperty: true
         });
+        const useInlineStyles = editor.config.get('table.tableProperties.alignment.useInlineStyles') !== false;
+        editor.data.addStyleProcessorRules(addMarginStylesRules);
         editor.data.addStyleProcessorRules(addBorderStylesRules);
-        enableBorderProperties(schema, conversion, {
+        enableBorderProperties(editor, {
             color: defaultTableProperties.borderColor,
             style: defaultTableProperties.borderStyle,
             width: defaultTableProperties.borderWidth
@@ -88,7 +90,12 @@ export class TablePropertiesEditing extends Plugin {
         editor.commands.add('tableBorderColor', new TableBorderColorCommand(editor, defaultTableProperties.borderColor));
         editor.commands.add('tableBorderStyle', new TableBorderStyleCommand(editor, defaultTableProperties.borderStyle));
         editor.commands.add('tableBorderWidth', new TableBorderWidthCommand(editor, defaultTableProperties.borderWidth));
-        enableAlignmentProperty(schema, conversion, defaultTableProperties.alignment);
+        if (editor.config.get('experimentalFlags.useExtendedTableBlockAlignment')) {
+            enableExtendedAlignmentProperty(schema, conversion, defaultTableProperties.alignment, useInlineStyles);
+        }
+        else {
+            enableAlignmentProperty(schema, conversion, defaultTableProperties.alignment);
+        }
         editor.commands.add('tableAlignment', new TableAlignmentCommand(editor, defaultTableProperties.alignment));
         enableTableToFigureProperty(schema, conversion, {
             modelAttribute: 'tableWidth',
@@ -115,8 +122,50 @@ export class TablePropertiesEditing extends Plugin {
             defaultValue: defaultTableProperties.backgroundColor
         });
         editor.commands.add('tableBackgroundColor', new TableBackgroundColorCommand(editor, defaultTableProperties.backgroundColor));
+        if (editor.config.get('experimentalFlags.useExtendedTableBlockAlignment')) {
+            const viewDoc = editor.editing.view.document;
+            // Adjust clipboard output to wrap tables in divs if needed (for alignment).
+            this.listenTo(viewDoc, 'clipboardOutput', (evt, data) => {
+                editor.editing.view.change(writer => {
+                    for (const { item } of writer.createRangeIn(data.content)) {
+                        wrapInDivIfNeeded(item, writer);
+                    }
+                    data.dataTransfer.setData('text/html', this.editor.data.htmlProcessor.toData(data.content));
+                });
+            }, { priority: 'lowest' });
+        }
     }
 }
+/**
+ * Checks whether the view element is a table and if it needs to be wrapped in a div for alignment purposes.
+ * If so, it wraps it in a div and inserts it into the data content.
+ */
+function wrapInDivIfNeeded(viewItem, writer) {
+    if (!viewItem.is('element', 'table')) {
+        return;
+    }
+    const alignAttribute = viewItem.getAttribute('align');
+    const floatAttribute = viewItem.getStyle('float');
+    const marginLeft = viewItem.getStyle('margin-left');
+    const marginRight = viewItem.getStyle('margin-right');
+    if (
+    // Align center.
+    (alignAttribute && alignAttribute === 'center') ||
+        // Align right with text wrapping.
+        (floatAttribute && floatAttribute === 'right' && alignAttribute && alignAttribute === 'right')) {
+        insertWrapperWithAlignment(writer, alignAttribute, viewItem);
+        return;
+    }
+    // Align right with no text wrapping.
+    if (floatAttribute === undefined && marginLeft === 'auto' && marginRight === '0') {
+        insertWrapperWithAlignment(writer, 'right', viewItem);
+    }
+}
+function insertWrapperWithAlignment(writer, align, table) {
+    const position = writer.createPositionBefore(table);
+    const wrapper = writer.createContainerElement('div', { align }, table);
+    writer.insert(position, wrapper);
+}
 /**
  * Enables `tableBorderStyle'`, `tableBorderColor'` and `tableBorderWidth'` attributes for table.
  *
@@ -125,7 +174,9 @@ export class TablePropertiesEditing extends Plugin {
  * @param defaultBorder.style The default `tableBorderStyle` value.
  * @param defaultBorder.width The default `tableBorderWidth` value.
  */
-function enableBorderProperties(schema, conversion, defaultBorder) {
+function enableBorderProperties(editor, defaultBorder) {
+    const { conversion } = editor;
+    const { schema } = editor.model;
     const modelAttributes = {
         width: 'tableBorderWidth',
         color: 'tableBorderColor',
@@ -137,17 +188,115 @@ function enableBorderProperties(schema, conversion, defaultBorder) {
     for (const modelAttribute of Object.values(modelAttributes)) {
         schema.setAttributeProperties(modelAttribute, { isFormatting: true });
     }
-    upcastBorderStyles(conversion, 'table', modelAttributes, defaultBorder);
+    upcastBorderStyles(editor, 'table', modelAttributes, defaultBorder);
     downcastTableAttribute(conversion, { modelAttribute: modelAttributes.color, styleName: 'border-color' });
     downcastTableAttribute(conversion, { modelAttribute: modelAttributes.style, styleName: 'border-style' });
     downcastTableAttribute(conversion, { modelAttribute: modelAttributes.width, styleName: 'border-width' });
 }
+/**
+ * Enables the extended block`'alignment'` attribute for table.
+ *
+ * @param defaultValue The default alignment value.
+ */
+function enableExtendedAlignmentProperty(schema, conversion, defaultValue, useInlineStyles) {
+    schema.extend('table', {
+        allowAttributes: ['tableAlignment']
+    });
+    schema.setAttributeProperties('tableAlignment', { isFormatting: true });
+    conversion.for('downcast')
+        .attributeToAttribute({
+        model: {
+            name: 'table',
+            key: 'tableAlignment',
+            values: ['left', 'center', 'right', 'blockLeft', 'blockRight']
+        },
+        view: {
+            left: useInlineStyles ? {
+                key: 'style',
+                value: {
+                    float: 'left',
+                    'margin-right': 'var(--ck-content-table-style-spacing, 1.5em)'
+                }
+            } : {
+                key: 'class',
+                value: DEFAULT_TABLE_ALIGNMENT_OPTIONS.left.className
+            },
+            right: useInlineStyles ? {
+                key: 'style',
+                value: {
+                    float: 'right',
+                    'margin-left': 'var(--ck-content-table-style-spacing, 1.5em)'
+                }
+            } : {
+                key: 'class',
+                value: DEFAULT_TABLE_ALIGNMENT_OPTIONS.right.className
+            },
+            center: useInlineStyles ? {
+                key: 'style',
+                value: {
+                    'margin-left': 'auto',
+                    'margin-right': 'auto'
+                }
+            } : {
+                key: 'class',
+                value: DEFAULT_TABLE_ALIGNMENT_OPTIONS.center.className
+            },
+            blockLeft: useInlineStyles ? {
+                key: 'style',
+                value: {
+                    'margin-left': '0',
+                    'margin-right': 'auto'
+                }
+            } : {
+                key: 'class',
+                value: DEFAULT_TABLE_ALIGNMENT_OPTIONS.blockLeft.className
+            },
+            blockRight: useInlineStyles ? {
+                key: 'style',
+                value: {
+                    'margin-left': 'auto',
+                    'margin-right': '0'
+                }
+            } : {
+                key: 'class',
+                value: DEFAULT_TABLE_ALIGNMENT_OPTIONS.blockRight.className
+            }
+        },
+        converterPriority: 'high'
+    });
+    /**
+     * Enables upcasting of the `tableAlignment` attribute.
+     */
+    upcastTableAlignmentConfig.forEach(config => {
+        conversion.for('upcast').attributeToAttribute({
+            view: config.view,
+            model: {
+                key: 'tableAlignment',
+                value: (viewElement, conversionApi, data) => {
+                    if (isNonTableFigureElement(viewElement)) {
+                        return;
+                    }
+                    const localDefaultValue = getDefaultValueAdjusted(defaultValue, '', data);
+                    const align = config.getAlign(viewElement);
+                    const consumables = config.getConsumables(viewElement);
+                    conversionApi.consumable.consume(viewElement, consumables);
+                    if (align !== localDefaultValue) {
+                        return align;
+                    }
+                }
+            }
+        });
+    });
+    conversion.for('upcast').add(upcastTableAlignedDiv(defaultValue));
+}
 /**
  * Enables the `'alignment'` attribute for table.
  *
  * @param defaultValue The default alignment value.
  */
 function enableAlignmentProperty(schema, conversion, defaultValue) {
+    const ALIGN_VALUES_REG_EXP = /^(left|center|right)$/;
+    const FLOAT_VALUES_REG_EXP = /^(left|none|right)$/;
     schema.extend('table', {
         allowAttributes: ['tableAlignment']
     });
@@ -266,6 +415,98 @@ function enableAlignmentProperty(schema, conversion, defaultValue) {
         }
     });
 }
+/**
+ * Returns a function that converts the table view representation:
+ *
+ * ```html
+ * <div align="right"><table>...</table></div>
+ * <!-- or -->
+ * <div align="center"><table>...</table></div>
+ * <!-- or -->
+ * <div align="left"><table>...</table></div>
+ * ```
+ *
+ * to the model representation:
+ *
+ * ```xml
+ * <table tableAlignment="right|center|left"></table>
+ * ```
+ *
+ * @internal
+ */
+function upcastTableAlignedDiv(defaultValue) {
+    return (dispatcher) => {
+        dispatcher.on('element:div', (evt, data, conversionApi) => {
+            // Do not convert if this is not a "table wrapped in div with align attribute".
+            if (!conversionApi.consumable.test(data.viewItem, { name: true, attributes: 'align' })) {
+                return;
+            }
+            // Find a table element inside the div element.
+            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;
+            }
+            // Consume the div to prevent other converters from processing it again.
+            conversionApi.consumable.consume(data.viewItem, { name: true, attributes: 'align' });
+            // Convert view table to model table.
+            const conversionResult = conversionApi.convertItem(viewTable, data.modelCursor);
+            // Get table element from conversion result.
+            const modelTable = first(conversionResult.modelRange.getItems());
+            // When table wasn't successfully converted then finish conversion.
+            if (!modelTable || !modelTable.is('element', 'table')) {
+                // Revert consumed div so other features can convert it.
+                conversionApi.consumable.revert(data.viewItem, { name: true, attributes: 'align' });
+                // If anyway some table content was converted, we have to pass the model range and cursor.
+                if (conversionResult.modelRange && !conversionResult.modelRange.isCollapsed) {
+                    data.modelRange = conversionResult.modelRange;
+                    data.modelCursor = conversionResult.modelCursor;
+                }
+                return;
+            }
+            const alignAttributeFromDiv = data.viewItem.getAttribute('align');
+            const alignAttributeFromTable = viewTable.getAttribute('align');
+            const localDefaultValue = getDefaultValueAdjusted(defaultValue, '', data);
+            const align = convertToTableAlignment(alignAttributeFromDiv, alignAttributeFromTable, localDefaultValue);
+            if (align) {
+                conversionApi.writer.setAttribute('tableAlignment', align, modelTable);
+            }
+            conversionApi.convertChildren(data.viewItem, conversionApi.writer.createPositionAt(modelTable, 'end'));
+            conversionApi.updateConversionResult(modelTable, data);
+        });
+    };
+}
+/**
+ * Converts div `align` and table `align` attributes to the model `tableAlignment` attribute.
+ *
+ * @param divAlign The value of the div `align` attribute.
+ * @param tableAlign The value of the table `align` attribute.
+ * @param defaultValue The default alignment value.
+ * @returns The model `tableAlignment` value or `undefined` if no conversion is needed.
+ */
+function convertToTableAlignment(divAlign, tableAlign, defaultValue) {
+    if (divAlign) {
+        switch (divAlign) {
+            case 'right':
+                if (tableAlign === 'right') {
+                    return 'right';
+                }
+                else if (tableAlign === 'left') {
+                    return 'left';
+                }
+                else {
+                    return 'blockRight';
+                }
+            case 'center':
+                return 'center';
+            case 'left':
+                return tableAlign === undefined ? 'blockLeft' : 'left';
+            default:
+                return defaultValue;
+        }
+    }
+    return undefined;
+}
 /**
  * Enables conversion for an attribute for simple view-model mappings.
  *
@@ -297,3 +538,9 @@ function enableTableToFigureProperty(schema, conversion, options) {
     });
     downcastAttributeToStyle(conversion, { modelElement: 'table', ...options });
 }
+/**
+ * Checks whether a given figure element should be ignored when upcasting table properties.
+ */
+function isNonTableFigureElement(viewElement) {
+    return viewElement.name == 'figure' && !viewElement.hasClass('table');
+}

package/src/tableproperties/tablepropertiesuiexperimental.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @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/tableproperties/tablepropertiesuiexperimental
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import { ButtonView, ContextualBalloon } from 'ckeditor5/src/ui.js';
+import { TablePropertiesViewExperimental } from './ui/tablepropertiesviewexperimental.js';
+/**
+ * The table properties UI plugin. It introduces the `'tableProperties'` button
+ * that opens a form allowing to specify visual styling of an entire table.
+ *
+ * It uses the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon plugin}.
+ */
+export declare class TablePropertiesUIExperimental extends Plugin {
+    /**
+     * The default table properties.
+     */
+    private _defaultContentTableProperties;
+    /**
+     * The default layout table properties.
+     */
+    private _defaultLayoutTableProperties;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon;
+    /**
+     * The properties form view displayed inside the balloon.
+     */
+    view: TablePropertiesViewExperimental | null;
+    /**
+     * The properties form view displayed inside the balloon (content table).
+     */
+    private _viewWithContentTableDefaults;
+    /**
+     * The 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(): "TablePropertiesUIExperimental";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates the table properties button.
+     *
+     * @internal
+     */
+    _createTablePropertiesButton(): ButtonView;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates the {@link module:table/tableproperties/ui/tablepropertiesview~TablePropertiesView} instance.
+     *
+     * @returns The table properties form view instance.
+     */
+    private _createPropertiesView;
+    /**
+     * In this method the "editor data -> UI" binding is happening.
+     *
+     * When executed, this method obtains selected table 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, the new {@link #_undoStepBatch} is created that 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 is no longer selected.
+     */
+    protected _updateView(): void;
+    /**
+     * Returns `true` when the {@link #view} is the 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 {@link #view view's} property change
+     * executes a related editor command with the new property value.
+     *
+     * If new value will be set to the default value, the command will not be executed.
+     *
+     * @param commandName The command that will be executed.
+     */
+    private _getPropertyChangeCallback;
+    /**
+     * Creates a callback that when executed upon {@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;
+}