@ckeditor/ckeditor5-table 0.0.0-internal-20241017.0

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

@@ -0,0 +1,40 @@
+/**
+ * @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/tablecellproperties/commands/tablecellverticalalignmentcommand
+ */
+import type { Editor } from 'ckeditor5/src/core.js';
+import TableCellPropertyCommand from './tablecellpropertycommand.js';
+/**
+ * The table cell vertical alignment command.
+ *
+ * The command is registered by the {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing} as
+ * the `'tableCellVerticalAlignment'` editor command.
+ *
+ * To change the vertical text alignment of selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableCellVerticalAlignment', {
+ *   value: 'top'
+ * } );
+ * ```
+ *
+ * The following values, corresponding to the
+ * [`vertical-align` CSS attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align), are allowed:
+ *
+ * * `'top'`
+ * * `'bottom'`
+ *
+ * The `'middle'` value is the default one so there is no need to set it.
+ */
+export default class TableCellVerticalAlignmentCommand extends TableCellPropertyCommand {
+    /**
+     * Creates a new `TableCellVerticalAlignmentCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param defaultValue The default value for the "alignment" attribute.
+     */
+    constructor(editor: Editor, defaultValue: string);
+}

package/src/tablecellproperties/commands/tablecellverticalalignmentcommand.js

@@ -0,0 +1,38 @@
+/**
+ * @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 TableCellPropertyCommand from './tablecellpropertycommand.js';
+/**
+ * The table cell vertical alignment command.
+ *
+ * The command is registered by the {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing} as
+ * the `'tableCellVerticalAlignment'` editor command.
+ *
+ * To change the vertical text alignment of selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableCellVerticalAlignment', {
+ *   value: 'top'
+ * } );
+ * ```
+ *
+ * The following values, corresponding to the
+ * [`vertical-align` CSS attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align), are allowed:
+ *
+ * * `'top'`
+ * * `'bottom'`
+ *
+ * The `'middle'` value is the default one so there is no need to set it.
+ */
+export default class TableCellVerticalAlignmentCommand extends TableCellPropertyCommand {
+    /**
+     * Creates a new `TableCellVerticalAlignmentCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param defaultValue The default value for the "alignment" attribute.
+     */
+    constructor(editor, defaultValue) {
+        super(editor, 'tableCellVerticalAlignment', defaultValue);
+    }
+}

package/src/tablecellproperties/tablecellpropertiesediting.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
+ */
+/**
+ * @module table/tablecellproperties/tablecellpropertiesediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import TableEditing from './../tableediting.js';
+import TableCellWidthEditing from '../tablecellwidth/tablecellwidthediting.js';
+/**
+ * The table cell properties editing feature.
+ *
+ * Introduces table cell model attributes and their conversion:
+ *
+ * - border: `tableCellBorderStyle`, `tableCellBorderColor` and `tableCellBorderWidth`
+ * - background color: `tableCellBackgroundColor`
+ * - cell padding: `tableCellPadding`
+ * - horizontal and vertical alignment: `tableCellHorizontalAlignment`, `tableCellVerticalAlignment`
+ * - cell width and height: `tableCellWidth`, `tableCellHeight`
+ *
+ * It also registers commands used to manipulate the above attributes:
+ *
+ * - border: the `'tableCellBorderStyle'`, `'tableCellBorderColor'` and `'tableCellBorderWidth'` commands
+ * - background color: the `'tableCellBackgroundColor'` command
+ * - cell padding: the `'tableCellPadding'` command
+ * - horizontal and vertical alignment: the `'tableCellHorizontalAlignment'` and `'tableCellVerticalAlignment'` commands
+ * - width and height: the `'tableCellWidth'` and `'tableCellHeight'` commands
+ */
+export default class TableCellPropertiesEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableCellPropertiesEditing";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableEditing, typeof TableCellWidthEditing];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/src/tablecellproperties/tablecellpropertiesediting.js

@@ -0,0 +1,247 @@
+/**
+ * @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/tablecellproperties/tablecellpropertiesediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { addBorderRules, addPaddingRules, addBackgroundRules } from 'ckeditor5/src/engine.js';
+import { downcastAttributeToStyle, upcastBorderStyles } from './../converters/tableproperties.js';
+import TableEditing from './../tableediting.js';
+import TableCellWidthEditing from '../tablecellwidth/tablecellwidthediting.js';
+import TableCellPaddingCommand from './commands/tablecellpaddingcommand.js';
+import TableCellHeightCommand from './commands/tablecellheightcommand.js';
+import TableCellBackgroundColorCommand from './commands/tablecellbackgroundcolorcommand.js';
+import TableCellVerticalAlignmentCommand from './commands/tablecellverticalalignmentcommand.js';
+import TableCellHorizontalAlignmentCommand from './commands/tablecellhorizontalalignmentcommand.js';
+import TableCellBorderStyleCommand from './commands/tablecellborderstylecommand.js';
+import TableCellBorderColorCommand from './commands/tablecellbordercolorcommand.js';
+import TableCellBorderWidthCommand from './commands/tablecellborderwidthcommand.js';
+import { getNormalizedDefaultCellProperties } from '../utils/table-properties.js';
+import { enableProperty } from '../utils/common.js';
+const VALIGN_VALUES_REG_EXP = /^(top|middle|bottom)$/;
+const ALIGN_VALUES_REG_EXP = /^(left|center|right|justify)$/;
+/**
+ * The table cell properties editing feature.
+ *
+ * Introduces table cell model attributes and their conversion:
+ *
+ * - border: `tableCellBorderStyle`, `tableCellBorderColor` and `tableCellBorderWidth`
+ * - background color: `tableCellBackgroundColor`
+ * - cell padding: `tableCellPadding`
+ * - horizontal and vertical alignment: `tableCellHorizontalAlignment`, `tableCellVerticalAlignment`
+ * - cell width and height: `tableCellWidth`, `tableCellHeight`
+ *
+ * It also registers commands used to manipulate the above attributes:
+ *
+ * - border: the `'tableCellBorderStyle'`, `'tableCellBorderColor'` and `'tableCellBorderWidth'` commands
+ * - background color: the `'tableCellBackgroundColor'` command
+ * - cell padding: the `'tableCellPadding'` command
+ * - horizontal and vertical alignment: the `'tableCellHorizontalAlignment'` and `'tableCellVerticalAlignment'` commands
+ * - width and height: the `'tableCellWidth'` and `'tableCellHeight'` commands
+ */
+export default class TableCellPropertiesEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'TableCellPropertiesEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [TableEditing, TableCellWidthEditing];
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const schema = editor.model.schema;
+        const conversion = editor.conversion;
+        editor.config.define('table.tableCellProperties.defaultProperties', {});
+        const defaultTableCellProperties = getNormalizedDefaultCellProperties(editor.config.get('table.tableCellProperties.defaultProperties'), {
+            includeVerticalAlignmentProperty: true,
+            includeHorizontalAlignmentProperty: true,
+            includePaddingProperty: true,
+            isRightToLeftContent: editor.locale.contentLanguageDirection === 'rtl'
+        });
+        editor.data.addStyleProcessorRules(addBorderRules);
+        enableBorderProperties(schema, conversion, {
+            color: defaultTableCellProperties.borderColor,
+            style: defaultTableCellProperties.borderStyle,
+            width: defaultTableCellProperties.borderWidth
+        });
+        editor.commands.add('tableCellBorderStyle', new TableCellBorderStyleCommand(editor, defaultTableCellProperties.borderStyle));
+        editor.commands.add('tableCellBorderColor', new TableCellBorderColorCommand(editor, defaultTableCellProperties.borderColor));
+        editor.commands.add('tableCellBorderWidth', new TableCellBorderWidthCommand(editor, defaultTableCellProperties.borderWidth));
+        enableProperty(schema, conversion, {
+            modelAttribute: 'tableCellHeight',
+            styleName: 'height',
+            defaultValue: defaultTableCellProperties.height
+        });
+        editor.commands.add('tableCellHeight', new TableCellHeightCommand(editor, defaultTableCellProperties.height));
+        editor.data.addStyleProcessorRules(addPaddingRules);
+        enableProperty(schema, conversion, {
+            modelAttribute: 'tableCellPadding',
+            styleName: 'padding',
+            reduceBoxSides: true,
+            defaultValue: defaultTableCellProperties.padding
+        });
+        editor.commands.add('tableCellPadding', new TableCellPaddingCommand(editor, defaultTableCellProperties.padding));
+        editor.data.addStyleProcessorRules(addBackgroundRules);
+        enableProperty(schema, conversion, {
+            modelAttribute: 'tableCellBackgroundColor',
+            styleName: 'background-color',
+            defaultValue: defaultTableCellProperties.backgroundColor
+        });
+        editor.commands.add('tableCellBackgroundColor', new TableCellBackgroundColorCommand(editor, defaultTableCellProperties.backgroundColor));
+        enableHorizontalAlignmentProperty(schema, conversion, defaultTableCellProperties.horizontalAlignment);
+        editor.commands.add('tableCellHorizontalAlignment', new TableCellHorizontalAlignmentCommand(editor, defaultTableCellProperties.horizontalAlignment));
+        enableVerticalAlignmentProperty(schema, conversion, defaultTableCellProperties.verticalAlignment);
+        editor.commands.add('tableCellVerticalAlignment', new TableCellVerticalAlignmentCommand(editor, defaultTableCellProperties.verticalAlignment));
+    }
+}
+/**
+ * Enables the `'tableCellBorderStyle'`, `'tableCellBorderColor'` and `'tableCellBorderWidth'` attributes for table cells.
+ *
+ * @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) {
+    const modelAttributes = {
+        width: 'tableCellBorderWidth',
+        color: 'tableCellBorderColor',
+        style: 'tableCellBorderStyle'
+    };
+    schema.extend('tableCell', {
+        allowAttributes: Object.values(modelAttributes)
+    });
+    upcastBorderStyles(conversion, 'td', modelAttributes, defaultBorder);
+    upcastBorderStyles(conversion, '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' });
+}
+/**
+ * Enables the `'tableCellHorizontalAlignment'` attribute for table cells.
+ *
+ * @param defaultValue The default horizontal alignment value.
+ */
+function enableHorizontalAlignmentProperty(schema, conversion, defaultValue) {
+    schema.extend('tableCell', {
+        allowAttributes: ['tableCellHorizontalAlignment']
+    });
+    conversion.for('downcast')
+        .attributeToAttribute({
+        model: {
+            name: 'tableCell',
+            key: 'tableCellHorizontalAlignment'
+        },
+        view: alignment => ({
+            key: 'style',
+            value: {
+                'text-align': alignment
+            }
+        })
+    });
+    conversion.for('upcast')
+        // Support for the `text-align:*;` CSS definition for the table cell alignment.
+        .attributeToAttribute({
+        view: {
+            name: /^(td|th)$/,
+            styles: {
+                'text-align': ALIGN_VALUES_REG_EXP
+            }
+        },
+        model: {
+            key: 'tableCellHorizontalAlignment',
+            value: (viewElement) => {
+                const align = viewElement.getStyle('text-align');
+                return align === defaultValue ? null : align;
+            }
+        }
+    })
+        // Support for the `align` attribute as the backward compatibility while pasting from other sources.
+        .attributeToAttribute({
+        view: {
+            name: /^(td|th)$/,
+            attributes: {
+                align: ALIGN_VALUES_REG_EXP
+            }
+        },
+        model: {
+            key: 'tableCellHorizontalAlignment',
+            value: (viewElement) => {
+                const align = viewElement.getAttribute('align');
+                return align === defaultValue ? null : align;
+            }
+        }
+    });
+}
+/**
+ * Enables the `'verticalAlignment'` attribute for table cells.
+ *
+ * @param defaultValue The default vertical alignment value.
+ */
+function enableVerticalAlignmentProperty(schema, conversion, defaultValue) {
+    schema.extend('tableCell', {
+        allowAttributes: ['tableCellVerticalAlignment']
+    });
+    conversion.for('downcast')
+        .attributeToAttribute({
+        model: {
+            name: 'tableCell',
+            key: 'tableCellVerticalAlignment'
+        },
+        view: alignment => ({
+            key: 'style',
+            value: {
+                'vertical-align': alignment
+            }
+        })
+    });
+    conversion.for('upcast')
+        // Support for the `vertical-align:*;` CSS definition for the table cell alignment.
+        .attributeToAttribute({
+        view: {
+            name: /^(td|th)$/,
+            styles: {
+                'vertical-align': VALIGN_VALUES_REG_EXP
+            }
+        },
+        model: {
+            key: 'tableCellVerticalAlignment',
+            value: (viewElement) => {
+                const align = viewElement.getStyle('vertical-align');
+                return align === defaultValue ? null : align;
+            }
+        }
+    })
+        // Support for the `align` attribute as the backward compatibility while pasting from other sources.
+        .attributeToAttribute({
+        view: {
+            name: /^(td|th)$/,
+            attributes: {
+                valign: VALIGN_VALUES_REG_EXP
+            }
+        },
+        model: {
+            key: 'tableCellVerticalAlignment',
+            value: (viewElement) => {
+                const valign = viewElement.getAttribute('valign');
+                return valign === defaultValue ? null : valign;
+            }
+        }
+    });
+}

package/src/tablecellproperties/tablecellpropertiesui.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @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/tablecellproperties/tablecellpropertiesui
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import { ContextualBalloon } from 'ckeditor5/src/ui.js';
+import TableCellPropertiesView from './ui/tablecellpropertiesview.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 default class TableCellPropertiesUI extends Plugin {
+    /**
+     * The default table cell properties.
+     */
+    private _defaultTableCellProperties;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon?;
+    /**
+     * The cell properties form view displayed inside the balloon.
+     */
+    view?: TableCellPropertiesView | null;
+    /**
+     * 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(): "TableCellPropertiesUI";
+    /**
+     * @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 defaultValue 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;
+}