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

package/src/utils/ui/table-propertiesexperimental.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @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/utils/ui/table-propertiesexperimental
+ */
+import { type ColorOption, type LabeledFieldView, type ListDropdownItemDefinition, type NormalizedColorOption, type ToolbarView, type View, type ColorPickerConfig } from 'ckeditor5/src/ui.js';
+import { Collection, type LocaleTranslate } from 'ckeditor5/src/utils.js';
+import { type TableCellPropertiesViewExperimental } from '../../tablecellproperties/ui/tablecellpropertiesviewexperimental.js';
+import { type TablePropertiesViewExperimental } from '../../tableproperties/ui/tablepropertiesviewexperimental.js';
+import { ColorInputView } from '../../ui/colorinputview.js';
+/**
+ * Returns an object containing pairs of CSS border style values and their localized UI
+ * labels. Used by {@link module:table/tablecellproperties/ui/tablecellpropertiesview~TableCellPropertiesView}
+ * and {@link module:table/tableproperties/ui/tablepropertiesview~TablePropertiesView}.
+ *
+ * @internal
+ * @param t The "t" function provided by the editor that is used to localize strings.
+ */
+export declare function getBorderStyleLabels(t: LocaleTranslate): Record<string, string>;
+/**
+ * Returns a localized error string that can be displayed next to color (background, border)
+ * fields that have an invalid value.
+ *
+ * @internal
+ * @param t The "t" function provided by the editor that is used to localize strings.
+ */
+export declare function getLocalizedColorErrorText(t: LocaleTranslate): string;
+/**
+ * Returns a localized error string that can be displayed next to length (padding, border width)
+ * fields that have an invalid value.
+ *
+ * @internal
+ * @param t The "t" function provided by the editor that is used to localize strings.
+ */
+export declare function getLocalizedLengthErrorText(t: LocaleTranslate): string;
+/**
+ * Returns `true` when the passed value is an empty string or a valid CSS color expression.
+ * Otherwise, `false` is returned.
+ *
+ * See {@link module:engine/view/styles/utils~isColorStyleValue}.
+ *
+ * @internal
+ */
+export declare function colorFieldValidator(value: string): boolean;
+/**
+ * Returns `true` when the passed value is an empty string, a number without a unit or a valid CSS length expression.
+ * Otherwise, `false` is returned.
+ *
+ * See {@link module:engine/view/styles/utils~isLengthStyleValue}.
+ * See {@link module:engine/view/styles/utils~isPercentageStyleValue}.
+ *
+ * @internal
+ */
+export declare function lengthFieldValidator(value: string): boolean;
+/**
+ * Returns `true` when the passed value is an empty string, a number without a unit or a valid CSS length expression.
+ * Otherwise, `false` is returned.
+ *
+ * See {@link module:engine/view/styles/utils~isLengthStyleValue}.
+ *
+ * @internal
+ */
+export declare function lineWidthFieldValidator(value: string): boolean;
+/**
+ * Generates item definitions for a UI dropdown that allows changing the border style of a table or a table cell.
+ *
+ * @internal
+ * @param defaultStyle The default border.
+ */
+export declare function getBorderStyleDefinitions(view: TableCellPropertiesViewExperimental | TablePropertiesViewExperimental, defaultStyle: string): Collection<ListDropdownItemDefinition>;
+/**
+ * A helper that fills a toolbar with buttons that:
+ *
+ * * have some labels,
+ * * have some icons,
+ * * set a certain UI view property value upon execution.
+ *
+ * @internal
+ * @param options Configuration options
+ * @param options.view The view that has the observable property.
+ * @param options.icons Object with button icons.
+ * @param options.toolbar The toolbar to fill with buttons.
+ * @param options.labels Object with button labels.
+ * @param options.propertyName The name of the observable property in the view.
+ * @param options.nameToValue A function that maps a button name to a value. By default names are the same as values.
+ * @param options.defaultValue Default value for the property.
+ */
+export declare function fillToolbar<TView extends View, TPropertyName extends keyof TView>(options: {
+    view: TView;
+    icons: Record<string, string>;
+    toolbar: ToolbarView;
+    labels: Record<number, string>;
+    propertyName: TPropertyName;
+    nameToValue?: (name: string) => string;
+    defaultValue?: string;
+}): void;
+/**
+ * A default color palette used by various user interfaces related to tables, for instance,
+ * by {@link module:table/tablecellproperties/tablecellpropertiesui~TableCellPropertiesUI} or
+ * {@link module:table/tableproperties/tablepropertiesui~TablePropertiesUI}.
+ *
+ * The color palette follows the {@link module:table/tableconfig~TableColorConfig table color configuration format}
+ * and contains the following color definitions:
+ *
+ * ```ts
+ * const defaultColors = [
+ *   {
+ *     color: 'hsl(0, 0%, 0%)',
+ *     label: 'Black'
+ *   },
+ *   {
+ *     color: 'hsl(0, 0%, 30%)',
+ *     label: 'Dim grey'
+ *   },
+ *   {
+ *     color: 'hsl(0, 0%, 60%)',
+ *     label: 'Grey'
+ *   },
+ *   {
+ *     color: 'hsl(0, 0%, 90%)',
+ *     label: 'Light grey'
+ *   },
+ *   {
+ *     color: 'hsl(0, 0%, 100%)',
+ *     label: 'White',
+ *     hasBorder: true
+ *   },
+ *   {
+ *     color: 'hsl(0, 75%, 60%)',
+ *     label: 'Red'
+ *   },
+ *   {
+ *     color: 'hsl(30, 75%, 60%)',
+ *     label: 'Orange'
+ *   },
+ *   {
+ *     color: 'hsl(60, 75%, 60%)',
+ *     label: 'Yellow'
+ *   },
+ *   {
+ *     color: 'hsl(90, 75%, 60%)',
+ *     label: 'Light green'
+ *   },
+ *   {
+ *     color: 'hsl(120, 75%, 60%)',
+ *     label: 'Green'
+ *   },
+ *   {
+ *     color: 'hsl(150, 75%, 60%)',
+ *     label: 'Aquamarine'
+ *   },
+ *   {
+ *     color: 'hsl(180, 75%, 60%)',
+ *     label: 'Turquoise'
+ *   },
+ *   {
+ *     color: 'hsl(210, 75%, 60%)',
+ *     label: 'Light blue'
+ *   },
+ *   {
+ *     color: 'hsl(240, 75%, 60%)',
+ *     label: 'Blue'
+ *   },
+ *   {
+ *     color: 'hsl(270, 75%, 60%)',
+ *     label: 'Purple'
+ *   }
+ * ];
+ * ```
+ *
+ * @internal
+ */
+export declare const defaultColors: Array<ColorOption>;
+/**
+ * Returns a creator for a color input with a label.
+ *
+ * For given options, it returns a function that creates an instance of a
+ * {@link module:table/ui/colorinputview~ColorInputView color input} logically related to
+ * a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled view} in the DOM.
+ *
+ * The helper does the following:
+ *
+ * * It sets the color input `id` and `ariaDescribedById` attributes.
+ * * It binds the color input `isReadOnly` to the labeled view.
+ * * It binds the color input `hasError` to the labeled view.
+ * * It enables a logic that cleans up the error when the user starts typing in the color input.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const colorInputCreator = getLabeledColorInputCreator( {
+ *   colorConfig: [ ... ],
+ *   columns: 3,
+ * } );
+ *
+ * const labeledInputView = new LabeledFieldView( locale, colorInputCreator );
+ * console.log( labeledInputView.view ); // A color input instance.
+ * ```
+ *
+ * @internal
+ * @param options Color input options.
+ * @param options.colorConfig The configuration of the color palette displayed in the input's dropdown.
+ * @param options.columns The configuration of the number of columns the color palette consists of in the input's dropdown.
+ * @param options.defaultColorValue If specified, the color input view will replace the "Remove color" button with
+ * the "Restore default" button. Instead of clearing the input field, the default color value will be set.
+ * @param options.colorPickerConfig The configuration of the color picker. You could disable it or define your output format.
+ */
+export declare function getLabeledColorInputCreator(options: {
+    colorConfig: Array<NormalizedColorOption>;
+    columns: number;
+    defaultColorValue?: string;
+    colorPickerConfig: false | ColorPickerConfig;
+}): (labeledFieldView: LabeledFieldView, viewUid: string, statusUid: string) => ColorInputView;

package/src/utils/ui/table-propertiesexperimental.js

@@ -0,0 +1,391 @@
+/**
+ * @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/utils/ui/table-propertiesexperimental
+ */
+/* istanbul ignore file -- @preserve */
+import { ButtonView, UIModel } from 'ckeditor5/src/ui.js';
+import { Collection } from 'ckeditor5/src/utils.js';
+import { isColorStyleValue, isLengthStyleValue, isPercentageStyleValue } from 'ckeditor5/src/engine.js';
+import { ColorInputView } from '../../ui/colorinputview.js';
+const isEmpty = (val) => val === '';
+/**
+ * Returns an object containing pairs of CSS border style values and their localized UI
+ * labels. Used by {@link module:table/tablecellproperties/ui/tablecellpropertiesview~TableCellPropertiesView}
+ * and {@link module:table/tableproperties/ui/tablepropertiesview~TablePropertiesView}.
+ *
+ * @internal
+ * @param t The "t" function provided by the editor that is used to localize strings.
+ */
+export function getBorderStyleLabels(t) {
+    return {
+        none: t('None'),
+        solid: t('Solid'),
+        dotted: t('Dotted'),
+        dashed: t('Dashed'),
+        double: t('Double'),
+        groove: t('Groove'),
+        ridge: t('Ridge'),
+        inset: t('Inset'),
+        outset: t('Outset')
+    };
+}
+/**
+ * Returns a localized error string that can be displayed next to color (background, border)
+ * fields that have an invalid value.
+ *
+ * @internal
+ * @param t The "t" function provided by the editor that is used to localize strings.
+ */
+export function getLocalizedColorErrorText(t) {
+    return t('The color is invalid. Try "#FF0000" or "rgb(255,0,0)" or "red".');
+}
+/**
+ * Returns a localized error string that can be displayed next to length (padding, border width)
+ * fields that have an invalid value.
+ *
+ * @internal
+ * @param t The "t" function provided by the editor that is used to localize strings.
+ */
+export function getLocalizedLengthErrorText(t) {
+    return t('The value is invalid. Try "10px" or "2em" or simply "2".');
+}
+/**
+ * Returns `true` when the passed value is an empty string or a valid CSS color expression.
+ * Otherwise, `false` is returned.
+ *
+ * See {@link module:engine/view/styles/utils~isColorStyleValue}.
+ *
+ * @internal
+ */
+export function colorFieldValidator(value) {
+    value = value.trim().toLowerCase();
+    return isEmpty(value) || isColorStyleValue(value);
+}
+/**
+ * Returns `true` when the passed value is an empty string, a number without a unit or a valid CSS length expression.
+ * Otherwise, `false` is returned.
+ *
+ * See {@link module:engine/view/styles/utils~isLengthStyleValue}.
+ * See {@link module:engine/view/styles/utils~isPercentageStyleValue}.
+ *
+ * @internal
+ */
+export function lengthFieldValidator(value) {
+    value = value.trim();
+    return isEmpty(value) || isNumberString(value) || isLengthStyleValue(value) || isPercentageStyleValue(value);
+}
+/**
+ * Returns `true` when the passed value is an empty string, a number without a unit or a valid CSS length expression.
+ * Otherwise, `false` is returned.
+ *
+ * See {@link module:engine/view/styles/utils~isLengthStyleValue}.
+ *
+ * @internal
+ */
+export function lineWidthFieldValidator(value) {
+    value = value.trim();
+    return isEmpty(value) || isNumberString(value) || isLengthStyleValue(value);
+}
+/**
+ * Generates item definitions for a UI dropdown that allows changing the border style of a table or a table cell.
+ *
+ * @internal
+ * @param defaultStyle The default border.
+ */
+export function getBorderStyleDefinitions(view, defaultStyle) {
+    const itemDefinitions = new Collection();
+    const styleLabels = getBorderStyleLabels(view.t);
+    for (const style in styleLabels) {
+        const definition = {
+            type: 'button',
+            model: new UIModel({
+                _borderStyleValue: style,
+                label: styleLabels[style],
+                role: 'menuitemradio',
+                withText: true
+            })
+        };
+        if (style === 'none') {
+            definition.model.bind('isOn').to(view, 'borderStyle', value => {
+                if (defaultStyle === 'none') {
+                    return !value;
+                }
+                return value === style;
+            });
+        }
+        else {
+            definition.model.bind('isOn').to(view, 'borderStyle', value => {
+                return value === style;
+            });
+        }
+        itemDefinitions.add(definition);
+    }
+    return itemDefinitions;
+}
+/**
+ * A helper that fills a toolbar with buttons that:
+ *
+ * * have some labels,
+ * * have some icons,
+ * * set a certain UI view property value upon execution.
+ *
+ * @internal
+ * @param options Configuration options
+ * @param options.view The view that has the observable property.
+ * @param options.icons Object with button icons.
+ * @param options.toolbar The toolbar to fill with buttons.
+ * @param options.labels Object with button labels.
+ * @param options.propertyName The name of the observable property in the view.
+ * @param options.nameToValue A function that maps a button name to a value. By default names are the same as values.
+ * @param options.defaultValue Default value for the property.
+ */
+export function fillToolbar(options) {
+    const { view, icons, toolbar, labels, propertyName, nameToValue, defaultValue } = options;
+    for (const name in labels) {
+        const button = new ButtonView(view.locale);
+        button.set({
+            role: 'radio',
+            isToggleable: true,
+            label: labels[name],
+            icon: icons[name],
+            tooltip: labels[name]
+        });
+        // If specified the `nameToValue()` callback, map the value based on the option's name.
+        const buttonValue = nameToValue ? nameToValue(name) : name;
+        button.bind('isOn').to(view, propertyName, value => {
+            // `value` comes from `view[ propertyName ]`.
+            let valueToCompare = value;
+            // If it's empty, and the `defaultValue` is specified, use it instead.
+            if (value === '' && defaultValue) {
+                valueToCompare = defaultValue;
+            }
+            return buttonValue === valueToCompare;
+        });
+        button.on('execute', () => {
+            // Allow toggling alignment if there is no default value specified (especially for layout tables).
+            if (!defaultValue && buttonValue && view[propertyName] === buttonValue) {
+                view[propertyName] = undefined;
+            }
+            else {
+                view[propertyName] = buttonValue;
+            }
+        });
+        toolbar.items.add(button);
+    }
+}
+/**
+ * A default color palette used by various user interfaces related to tables, for instance,
+ * by {@link module:table/tablecellproperties/tablecellpropertiesui~TableCellPropertiesUI} or
+ * {@link module:table/tableproperties/tablepropertiesui~TablePropertiesUI}.
+ *
+ * The color palette follows the {@link module:table/tableconfig~TableColorConfig table color configuration format}
+ * and contains the following color definitions:
+ *
+ * ```ts
+ * const defaultColors = [
+ *   {
+ *     color: 'hsl(0, 0%, 0%)',
+ *     label: 'Black'
+ *   },
+ *   {
+ *     color: 'hsl(0, 0%, 30%)',
+ *     label: 'Dim grey'
+ *   },
+ *   {
+ *     color: 'hsl(0, 0%, 60%)',
+ *     label: 'Grey'
+ *   },
+ *   {
+ *     color: 'hsl(0, 0%, 90%)',
+ *     label: 'Light grey'
+ *   },
+ *   {
+ *     color: 'hsl(0, 0%, 100%)',
+ *     label: 'White',
+ *     hasBorder: true
+ *   },
+ *   {
+ *     color: 'hsl(0, 75%, 60%)',
+ *     label: 'Red'
+ *   },
+ *   {
+ *     color: 'hsl(30, 75%, 60%)',
+ *     label: 'Orange'
+ *   },
+ *   {
+ *     color: 'hsl(60, 75%, 60%)',
+ *     label: 'Yellow'
+ *   },
+ *   {
+ *     color: 'hsl(90, 75%, 60%)',
+ *     label: 'Light green'
+ *   },
+ *   {
+ *     color: 'hsl(120, 75%, 60%)',
+ *     label: 'Green'
+ *   },
+ *   {
+ *     color: 'hsl(150, 75%, 60%)',
+ *     label: 'Aquamarine'
+ *   },
+ *   {
+ *     color: 'hsl(180, 75%, 60%)',
+ *     label: 'Turquoise'
+ *   },
+ *   {
+ *     color: 'hsl(210, 75%, 60%)',
+ *     label: 'Light blue'
+ *   },
+ *   {
+ *     color: 'hsl(240, 75%, 60%)',
+ *     label: 'Blue'
+ *   },
+ *   {
+ *     color: 'hsl(270, 75%, 60%)',
+ *     label: 'Purple'
+ *   }
+ * ];
+ * ```
+ *
+ * @internal
+ */
+export const defaultColors = [
+    {
+        color: 'hsl(0, 0%, 0%)',
+        label: 'Black'
+    },
+    {
+        color: 'hsl(0, 0%, 30%)',
+        label: 'Dim grey'
+    },
+    {
+        color: 'hsl(0, 0%, 60%)',
+        label: 'Grey'
+    },
+    {
+        color: 'hsl(0, 0%, 90%)',
+        label: 'Light grey'
+    },
+    {
+        color: 'hsl(0, 0%, 100%)',
+        label: 'White',
+        hasBorder: true
+    },
+    {
+        color: 'hsl(0, 75%, 60%)',
+        label: 'Red'
+    },
+    {
+        color: 'hsl(30, 75%, 60%)',
+        label: 'Orange'
+    },
+    {
+        color: 'hsl(60, 75%, 60%)',
+        label: 'Yellow'
+    },
+    {
+        color: 'hsl(90, 75%, 60%)',
+        label: 'Light green'
+    },
+    {
+        color: 'hsl(120, 75%, 60%)',
+        label: 'Green'
+    },
+    {
+        color: 'hsl(150, 75%, 60%)',
+        label: 'Aquamarine'
+    },
+    {
+        color: 'hsl(180, 75%, 60%)',
+        label: 'Turquoise'
+    },
+    {
+        color: 'hsl(210, 75%, 60%)',
+        label: 'Light blue'
+    },
+    {
+        color: 'hsl(240, 75%, 60%)',
+        label: 'Blue'
+    },
+    {
+        color: 'hsl(270, 75%, 60%)',
+        label: 'Purple'
+    }
+];
+/**
+ * Returns a creator for a color input with a label.
+ *
+ * For given options, it returns a function that creates an instance of a
+ * {@link module:table/ui/colorinputview~ColorInputView color input} logically related to
+ * a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled view} in the DOM.
+ *
+ * The helper does the following:
+ *
+ * * It sets the color input `id` and `ariaDescribedById` attributes.
+ * * It binds the color input `isReadOnly` to the labeled view.
+ * * It binds the color input `hasError` to the labeled view.
+ * * It enables a logic that cleans up the error when the user starts typing in the color input.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const colorInputCreator = getLabeledColorInputCreator( {
+ *   colorConfig: [ ... ],
+ *   columns: 3,
+ * } );
+ *
+ * const labeledInputView = new LabeledFieldView( locale, colorInputCreator );
+ * console.log( labeledInputView.view ); // A color input instance.
+ * ```
+ *
+ * @internal
+ * @param options Color input options.
+ * @param options.colorConfig The configuration of the color palette displayed in the input's dropdown.
+ * @param options.columns The configuration of the number of columns the color palette consists of in the input's dropdown.
+ * @param options.defaultColorValue If specified, the color input view will replace the "Remove color" button with
+ * the "Restore default" button. Instead of clearing the input field, the default color value will be set.
+ * @param options.colorPickerConfig The configuration of the color picker. You could disable it or define your output format.
+ */
+export function getLabeledColorInputCreator(options) {
+    return (labeledFieldView, viewUid, statusUid) => {
+        const colorInputView = new ColorInputView(labeledFieldView.locale, {
+            colorDefinitions: colorConfigToColorGridDefinitions(options.colorConfig),
+            columns: options.columns,
+            defaultColorValue: options.defaultColorValue,
+            colorPickerConfig: options.colorPickerConfig
+        });
+        colorInputView.inputView.set({
+            id: viewUid,
+            ariaDescribedById: statusUid
+        });
+        colorInputView.bind('isReadOnly').to(labeledFieldView, 'isEnabled', value => !value);
+        colorInputView.bind('hasError').to(labeledFieldView, 'errorText', value => !!value);
+        colorInputView.on('input', () => {
+            // UX: Make the error text disappear and disable the error indicator as the user
+            // starts fixing the errors.
+            labeledFieldView.errorText = null;
+        });
+        labeledFieldView.bind('isEmpty', 'isFocused').to(colorInputView);
+        return colorInputView;
+    };
+}
+/**
+ * A simple helper method to detect number strings.
+ * I allows full number notation, so omitting 0 is not allowed:
+ */
+function isNumberString(value) {
+    const parsedValue = parseFloat(value);
+    return !Number.isNaN(parsedValue) && value === String(parsedValue);
+}
+function colorConfigToColorGridDefinitions(colorConfig) {
+    return colorConfig.map(item => ({
+        color: item.model,
+        label: item.label,
+        options: {
+            hasBorder: item.hasBorder
+        }
+    }));
+}

package/theme/formrow-experimental.css

@@ -0,0 +1,15 @@
+/*
+ * 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
+ */
+
+.ck.ck-form__row {
+	&.ck-table-form__action-row {
+		justify-content: flex-end;
+
+		& .ck-button-save,
+		& .ck-button-cancel {
+			justify-content: center;
+		}
+	}
+}

package/theme/table.css

@@ -102,9 +102,9 @@
 		 * 	* The table has `display: table` style set.
 		 * 	* The block element is placed directly after the table.
 		 */
-		&:not(.layout-table):not(:has(> figcaption)) {
-			display: block;
+		&:not(.layout-table) {
 			width: fit-content;
+			height: fit-content;
 		}
 
 		/**

package/theme/tableform-experimental.css

@@ -0,0 +1,61 @@
+/*
+ * 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
+ */
+
+.ck.ck-table-form {
+	& .ck-form__row {
+		&.ck-table-form__border-row {
+			flex-wrap: wrap;
+		}
+
+		&.ck-table-form__background-row {
+			flex-wrap: wrap;
+		}
+
+		&.ck-table-form__dimensions-row {
+			flex-wrap: wrap;
+			align-items: center;
+
+			& .ck-labeled-field-view {
+				display: flex;
+				flex-direction: column-reverse;
+				align-items: center;
+
+				& .ck.ck-dropdown {
+					flex-grow: 0;
+				}
+			}
+		}
+
+		/* Ignore labels that work as fieldset legends */
+		/* Fallback for table dimension operator */
+		&:not(.ck-table-form__action-row) > *:not(.ck-label, .ck-table-form__dimension-operator) {
+			flex-grow: 1;
+		}
+	}
+
+	& .ck.ck-labeled-field-view {
+		/* Allow absolute positioning of the status (error) balloons. */
+		position: relative;
+
+		& .ck.ck-labeled-field-view__status {
+			position: absolute;
+			left: 50%;
+			bottom: calc( -1 * var(--ck-table-properties-error-arrow-size) );
+			transform: translate(-50%,100%);
+
+			/* Make sure the balloon status stays on top of other form elements. */
+			z-index: 1;
+
+			/* The arrow pointing towards the field. */
+			&::after {
+				content: "";
+				position: absolute;
+				top: calc( -1 * var(--ck-table-properties-error-arrow-size) );
+				left: 50%;
+				transform: translateX( -50% );
+			}
+		}
+	}
+}