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

package/dist/types/tablecolumnresize/tablecolumnresizeediting.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @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 { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import type { Element } from 'ckeditor5/src/engine.js';
+import TableEditing from '../tableediting.js';
+import TableUtils from '../tableutils.js';
+/**
+ * The table column resize editing plugin.
+ */
+export default class TableColumnResizeEditing extends Plugin {
+    /**
+     * A flag indicating if the column resizing is in progress.
+     */
+    private _isResizingActive;
+    /**
+     * A flag indicating if the column resizing is allowed. It is not allowed if the editor is in read-only
+     * or comments-only mode or the `TableColumnResize` plugin is disabled.
+     *
+     * @observable
+     * @internal
+     */
+    _isResizingAllowed: boolean;
+    /**
+     * A temporary storage for the required data needed to correctly calculate the widths of the resized columns. This storage is
+     * initialized when column resizing begins, and is purged upon completion.
+     */
+    private _resizingData;
+    /**
+     * DOM emitter.
+     */
+    private _domEmitter;
+    /**
+     * A local reference to the {@link module:table/tableutils~TableUtils} plugin.
+     */
+    private _tableUtilsPlugin;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableEditing, typeof TableUtils];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableColumnResizeEditing";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Returns a 'tableColumnGroup' element from the 'table'.
+     *
+     * @param element A 'table' or 'tableColumnGroup' element.
+     * @returns A 'tableColumnGroup' element.
+     */
+    getColumnGroupElement(element: Element): Element | undefined;
+    /**
+     * Returns an array of 'tableColumn' elements.
+     *
+     * @param element A 'table' or 'tableColumnGroup' element.
+     * @returns An array of 'tableColumn' elements.
+     */
+    getTableColumnElements(element: Element): Array<Element>;
+    /**
+     * Returns an array of table column widths.
+     *
+     * @param element A 'table' or 'tableColumnGroup' element.
+     * @returns An array of table column widths.
+     */
+    getTableColumnsWidths(element: Element): Array<string>;
+    /**
+     * Registers new attributes for a table model element.
+     */
+    private _extendSchema;
+    /**
+     * Registers table column resize post-fixer.
+     *
+     * It checks if the change from the differ concerns a table-related element or attribute. For detected changes it:
+     *  * Adjusts the `columnWidths` attribute to guarantee that the sum of the widths from all columns is 100%.
+     *  * Checks if the `columnWidths` attribute gets updated accordingly after columns have been added or removed.
+     */
+    private _registerPostFixer;
+    /**
+     * Registers table column resize converters.
+     */
+    private _registerConverters;
+    /**
+     * Registers listeners to handle resizing process.
+     */
+    private _registerResizingListeners;
+    /**
+     * Handles the `mousedown` event on column resizer element:
+     *  * calculates the initial column pixel widths,
+     *  * inserts the `<colgroup>` element if it is not present in the `<table>`,
+     *  * puts the necessary data in the temporary storage,
+     *  * applies the attributes to the `<table>` view element.
+     *
+     * @param eventInfo An object containing information about the fired event.
+     * @param domEventData The data related to the DOM event.
+     */
+    private _onMouseDownHandler;
+    /**
+     * Handles the `mousemove` event.
+     *  * If resizing process is not in progress, it does nothing.
+     *  * If resizing is active but not allowed, it stops the resizing process instantly calling the `mousedown` event handler.
+     *  * Otherwise it dynamically updates the widths of the resized columns.
+     *
+     * @param eventInfo An object containing information about the fired event.
+     * @param mouseEventData The native DOM event.
+     */
+    private _onMouseMoveHandler;
+    /**
+     * Handles the `mouseup` event.
+     *  * If resizing process is not in progress, it does nothing.
+     *  * If resizing is active but not allowed, it cancels the resizing process restoring the original widths.
+     *  * Otherwise it propagates the changes from view to the model by executing the adequate commands.
+     */
+    private _onMouseUpHandler;
+    /**
+     * Retrieves and returns required data needed for the resizing process.
+     *
+     * @param domEventData The data of the `mousedown` event.
+     * @param columnWidths The current widths of the columns.
+     * @returns The data needed for the resizing process.
+     */
+    private _getResizingData;
+    /**
+     * Registers a listener ensuring that each resizable cell have a resizer handle.
+     */
+    private _registerResizerInserter;
+}

package/dist/types/tablecolumnresize/tablewidthscommand.d.ts

@@ -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
+ */
+/**
+ * @module table/tablecolumnresize/tablewidthscommand
+ */
+import type { Element } from 'ckeditor5/src/engine.js';
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * Command used by the {@link module:table/tablecolumnresize~TableColumnResize Table column resize feature} that
+ * updates the width of the whole table as well as its individual columns.
+ */
+export default class TableWidthsCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Updated the `tableWidth` attribute of the table and the `columnWidth` attribute of the columns of that table.
+     */
+    execute(options?: TableWidthsCommandOptions): void;
+}
+export interface TableWidthsCommandOptions {
+    /**
+     * New value of the `columnWidths` attribute. Must be array of strings or string with comma-separated values.
+     * If skipped, the column widths information will be deleted.
+     */
+    columnWidths?: Array<string> | string;
+    /**
+     * The new table width. If skipped, the model attribute will be removed.
+     */
+    tableWidth?: string;
+    /**
+     * The table that is having the columns resized.
+     */
+    table?: Element;
+}

package/dist/types/tablecolumnresize/utils.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @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/tablecolumnresize/utils
+ */
+import type { Editor } from 'ckeditor5/src/core.js';
+import type { Element, Model, Writer } from 'ckeditor5/src/engine.js';
+import type TableUtils from '../tableutils.js';
+/**
+ * Returns all the inserted or changed table model elements in a given change set. Only the tables
+ * with 'columnsWidth' attribute are taken into account. The returned set may be empty.
+ *
+ * Most notably if an entire table is removed it will not be included in returned set.
+ *
+ * @param model The model to collect the affected elements from.
+ * @returns A set of table model elements.
+ */
+export declare function getChangedResizedTables(model: Model): Set<Element>;
+/**
+ * Calculates the percentage of the minimum column width given in pixels for a given table.
+ *
+ * @param modelTable A table model element.
+ * @param editor The editor instance.
+ * @returns The minimal column width in percentage.
+ */
+export declare function getColumnMinWidthAsPercentage(modelTable: Element, editor: Editor): number;
+/**
+ * Calculates the table width in pixels.
+ *
+ * @param modelTable A table model element.
+ * @param editor The editor instance.
+ * @returns The width of the table in pixels.
+ */
+export declare function getTableWidthInPixels(modelTable: Element, editor: Editor): number;
+/**
+ * Returns the computed width (in pixels) of the DOM element without padding and borders.
+ *
+ * @param domElement A DOM element.
+ * @returns The width of the DOM element in pixels.
+ */
+export declare function getElementWidthInPixels(domElement: HTMLElement): number;
+/**
+ * Returns the column indexes on the left and right edges of a cell. They differ if the cell spans
+ * across multiple columns.
+ *
+ * @param cell A table cell model element.
+ * @param tableUtils The Table Utils plugin instance.
+ * @returns An object containing the indexes of the left and right edges of the cell.
+ */
+export declare function getColumnEdgesIndexes(cell: Element, tableUtils: TableUtils): {
+    leftEdge: number;
+    rightEdge: number;
+};
+/**
+ * Rounds the provided value to a fixed-point number with defined number of digits after the decimal point.
+ *
+ * @param value A number to be rounded.
+ * @returns The rounded number.
+ */
+export declare function toPrecision(value: number | string): number;
+/**
+ * Clamps the number within the inclusive lower (min) and upper (max) bounds. Returned number is rounded using the
+ * {@link ~toPrecision `toPrecision()`} function.
+ *
+ * @param number A number to be clamped.
+ * @param min A lower bound.
+ * @param max An upper bound.
+ * @returns The clamped number.
+ */
+export declare function clamp(number: number, min: number, max: number): number;
+/**
+ * Creates an array with defined length and fills all elements with defined value.
+ *
+ * @param length The length of the array.
+ * @param value The value to fill the array with.
+ * @returns An array with defined length and filled with defined value.
+ */
+export declare function createFilledArray<T>(length: number, value: T): Array<T>;
+/**
+ * Sums all array values that can be parsed to a float.
+ *
+ * @param array An array of numbers.
+ * @returns The sum of all array values.
+ */
+export declare function sumArray(array: Array<number | string>): number;
+/**
+ * Makes sure that the sum of the widths from all columns is 100%. If the sum of all the widths is not equal 100%, all the widths are
+ * changed proportionally so that they all sum back to 100%. If there are columns without specified width, the amount remaining
+ * after assigning the known widths will be distributed equally between them.
+ *
+ * @param columnWidths An array of column widths.
+ * @returns An array of column widths guaranteed to sum up to 100%.
+ */
+export declare function normalizeColumnWidths(columnWidths: Array<string>): Array<string>;
+/**
+ * Calculates the total horizontal space taken by the cell. That includes:
+ *  * width,
+ *  * left and red padding,
+ *  * border width.
+ *
+ * @param domCell A DOM cell element.
+ * @returns Width in pixels without `px` at the end.
+ */
+export declare function getDomCellOuterWidth(domCell: HTMLElement): number;
+/**
+ * Updates column elements to match columns widths.
+ *
+ * @param columns
+ * @param tableColumnGroup
+ * @param normalizedWidths
+ * @param writer
+ */
+export declare function updateColumnElements(columns: Array<Element>, tableColumnGroup: Element, normalizedWidths: Array<string>, writer: Writer): void;
+/**
+ * Returns a 'tableColumnGroup' element from the 'table'.
+ *
+ * @internal
+ * @param element A 'table' or 'tableColumnGroup' element.
+ * @returns A 'tableColumnGroup' element.
+ */
+export declare function getColumnGroupElement(element: Element): Element;
+/**
+ * Returns an array of 'tableColumn' elements. It may be empty if there's no `tableColumnGroup` element.
+ *
+ * @internal
+ * @param element A 'table' or 'tableColumnGroup' element.
+ * @returns An array of 'tableColumn' elements.
+ */
+export declare function getTableColumnElements(element: Element): Array<Element>;
+/**
+ * Returns an array of table column widths.
+ *
+ * @internal
+ * @param element A 'table' or 'tableColumnGroup' element.
+ * @returns An array of table column widths.
+ */
+export declare function getTableColumnsWidths(element: Element): Array<string>;
+/**
+ * Translates the `colSpan` model attribute into additional column widths and returns the resulting array.
+ *
+ * @internal
+ * @param element A 'table' or 'tableColumnGroup' element.
+ * @param writer A writer instance.
+ * @returns An array of table column widths.
+ */
+export declare function translateColSpanAttribute(element: Element, writer: Writer): Array<string>;

package/dist/types/tablecolumnresize.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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/tablecolumnresize
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import TableColumnResizeEditing from './tablecolumnresize/tablecolumnresizeediting.js';
+import TableCellWidthEditing from './tablecellwidth/tablecellwidthediting.js';
+import '../theme/tablecolumnresize.css';
+/**
+ * The table column resize feature.
+ *
+ * It provides the possibility to set the width of each column in a table using a resize handler.
+ */
+export default class TableColumnResize extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableColumnResizeEditing, typeof TableCellWidthEditing];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableColumnResize";
+}

package/dist/types/tableconfig.d.ts

@@ -0,0 +1,343 @@
+/**
+ * @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/tableconfig
+ */
+import type { ToolbarConfigItem } from 'ckeditor5/src/core.js';
+import type { ColorOption, ColorPickerConfig } from 'ckeditor5/src/ui.js';
+/**
+ * The configuration of the table feature. Used by the table feature in the `@ckeditor/ckeditor5-table` package.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		table: ... // Table feature options.
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface TableConfig {
+    /**
+     * Number of rows and columns to render by default as table heading when inserting new tables.
+     *
+     * You can configure it like this:
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	defaultHeadings: {
+     * 		rows: 1,
+     * 		columns: 1
+     * 	}
+     * };
+     * ```
+     *
+     * Both rows and columns properties are optional defaulting to 0 (no heading).
+     */
+    defaultHeadings?: {
+        rows?: number;
+        columns?: number;
+    };
+    /**
+     * Items to be placed in the table content toolbar.
+     * The {@link module:table/tabletoolbar~TableToolbar} plugin is required to make this toolbar work.
+     *
+     * Assuming that you use the {@link module:table/tableui~TableUI} feature, the following toolbar items will be available
+     * in {@link module:ui/componentfactory~ComponentFactory}:
+     *
+     * * `'tableRow'`,
+     * * `'tableColumn'`,
+     * * `'mergeTableCells'`.
+     *
+     * You can thus configure the toolbar like this:
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	contentToolbar: [ 'tableRow', 'tableColumn', 'mergeTableCells' ]
+     * };
+     * ```
+     *
+     * Of course, the same buttons can also be used in the
+     * {@link module:core/editor/editorconfig~EditorConfig#toolbar main editor toolbar}.
+     *
+     * Read more about configuring the toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
+     */
+    contentToolbar?: Array<ToolbarConfigItem>;
+    /**
+     * Items to be placed in the table toolbar.
+     * The {@link module:table/tabletoolbar~TableToolbar} plugin is required to make this toolbar work.
+     *
+     * You can thus configure the toolbar like this:
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableToolbar: [ 'blockQuote' ]
+     * };
+     * ```
+     *
+     * Of course, the same buttons can also be used in the
+     * {@link module:core/editor/editorconfig~EditorConfig#toolbar main editor toolbar}.
+     *
+     * Read more about configuring the toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
+     */
+    tableToolbar?: Array<ToolbarConfigItem>;
+    /**
+     * The configuration of the table properties user interface (balloon). It allows to define:
+     *
+     * * The color palette for the table border color style field (`tableProperties.borderColors`),
+     * * The color palette for the table background style field (`tableProperties.backgroundColors`).
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableProperties: {
+     * 		borderColors: [
+     * 			{
+     * 				color: 'hsl(0, 0%, 90%)',
+     * 				label: 'Light grey'
+     * 			},
+     * 			// ...
+     * 		],
+     * 		backgroundColors: [
+     * 			{
+     * 				color: 'hsl(120, 75%, 60%)',
+     * 				label: 'Green'
+     * 			},
+     * 			// ...
+     * 		]
+     * 	}
+     * };
+     * ```
+     *
+     * * The default styles for tables (`tableProperties.defaultProperties`):
+     *
+     * ```
+     * const tableConfig = {
+     * 	tableProperties: {
+     * 		defaultProperties: {
+     * 			borderStyle: 'dashed',
+     * 			borderColor: 'hsl(0, 0%, 90%)',
+     * 			borderWidth: '3px',
+     * 			alignment: 'left'
+     * 		}
+     * 	}
+     * }
+     * ```
+     *
+     * {@link module:table/tableconfig~TablePropertiesOptions Read more about the supported properties.}
+     *
+     * **Note**: The `borderColors` and `backgroundColors` options do not impact the data loaded into the editor,
+     * i.e. they do not limit or filter the colors in the data. They are used only in the user interface
+     * allowing users to pick colors in a more convenient way. The `defaultProperties` option does impact the data.
+     * Default values will not be kept in the editor model.
+     *
+     * The default color palettes for the table background and the table border are the same
+     * ({@link module:table/utils/ui/table-properties#defaultColors check out their content}).
+     *
+     * Both color palette configurations must follow the
+     * {@link module:table/tableconfig~TableColorConfig table color configuration format}.
+     *
+     * Read more about configuring the table feature in {@link module:table/tableconfig~TableConfig}.
+     */
+    tableProperties?: TablePropertiesConfig;
+    /**
+     * The configuration of the table cell properties user interface (balloon). It allows to define:
+     *
+     * * The color palette for the cell border color style field (`tableCellProperties.borderColors`),
+     * * The color palette for the cell background style field (`tableCellProperties.backgroundColors`).
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableCellProperties: {
+     * 		borderColors: [
+     * 			{
+     * 				color: 'hsl(0, 0%, 90%)',
+     * 				label: 'Light grey'
+     * 			},
+     * 			// ...
+     * 		],
+     * 		backgroundColors: [
+     * 			{
+     * 				color: 'hsl(120, 75%, 60%)',
+     * 				label: 'Green'
+     * 			},
+     * 			// ...
+     * 		]
+     * 	}
+     * };
+     * ```
+     *
+     * * The default styles for table cells (`tableCellProperties.defaultProperties`):
+     *
+     * ```ts
+     * const tableConfig = {
+     * 	tableCellProperties: {
+     * 		defaultProperties: {
+     * 			horizontalAlignment: 'right',
+     * 			verticalAlignment: 'bottom',
+     * 			padding: '5px'
+     * 		}
+     * 	}
+     * }
+     * ```
+     *
+     * {@link module:table/tableconfig~TablePropertiesOptions Read more about the supported properties.}
+     *
+     * **Note**: The `borderColors` and `backgroundColors` options do not impact the data loaded into the editor,
+     * i.e. they do not limit or filter the colors in the data. They are used only in the user interface
+     * allowing users to pick colors in a more convenient way. The `defaultProperties` option does impact the data.
+     * Default values will not be kept in the editor model.
+     *
+     * The default color palettes for the cell background and the cell border are the same
+     * ({@link module:table/utils/ui/table-properties#defaultColors check out their content}).
+     *
+     * Both color palette configurations must follow the
+     * {@link module:table/tableconfig~TableColorConfig table color configuration format}.
+     *
+     * Read more about configuring the table feature in {@link module:table/tableconfig~TableConfig}.
+     */
+    tableCellProperties?: TableCellPropertiesConfig;
+}
+/**
+ * The configuration of the table properties user interface (balloon).
+ */
+export interface TablePropertiesConfig {
+    borderColors?: TableColorConfig;
+    backgroundColors?: TableColorConfig;
+    defaultProperties?: TablePropertiesOptions;
+    /**
+     * Configuration of the color picker in the table properties balloon.
+     *
+     * If set to `false` the picker will not appear.
+     */
+    colorPicker?: false | ColorPickerConfig;
+}
+/**
+ * The configuration of the table default properties feature.
+ */
+export interface TablePropertiesOptions {
+    /**
+     * The default `width` of the table.
+     */
+    width?: string;
+    /**
+     * The default `height` of the table.
+     */
+    height?: string;
+    /**
+     * The default `background-color` of the table.
+     */
+    backgroundColor?: string;
+    /**
+     * The default `border-color` of the table.
+     */
+    borderColor?: string;
+    /**
+     * The default `border-width` of the table.
+     */
+    borderWidth?: string;
+    /**
+     * The default `border-style` of the table.
+     *
+     * @default 'none'
+     */
+    borderStyle?: string;
+    /**
+     * The default `alignment` of the table.
+     *
+     * @default 'center'
+     */
+    alignment?: string;
+}
+/**
+ * The configuration of the table cell properties user interface (balloon).
+ */
+export interface TableCellPropertiesConfig {
+    borderColors?: TableColorConfig;
+    backgroundColors?: TableColorConfig;
+    defaultProperties?: TableCellPropertiesOptions;
+    /**
+     * Configuration of the color picker in the table cell properties balloon.
+     *
+     * If set to `false` the picker will not appear.
+     */
+    colorPicker?: false | ColorPickerConfig;
+}
+/**
+ * An array of color definitions (either strings or objects).
+ *
+ * ```ts
+ * const colors = [
+ * 	{
+ * 		color: 'hsl(0, 0%, 60%)',
+ * 		label: 'Grey'
+ * 	},
+ * 	'hsl(0, 0%, 80%)',
+ * 	{
+ * 		color: 'hsl(0, 0%, 90%)',
+ * 		label: 'Light grey'
+ * 	},
+ * 	{
+ * 		color: 'hsl(0, 0%, 100%)',
+ * 		label: 'White',
+ * 		hasBorder: true
+ * 	},
+ * 	'#FF0000'
+ * ]
+ * ```
+ *
+ * Usually used as a configuration parameter, for instance in
+ * {@link module:table/tableconfig~TableConfig#tableProperties `config.table.tableProperties`}
+ * or {@link module:table/tableconfig~TableConfig#tableCellProperties `config.table.tableCellProperties`}.
+ */
+export type TableColorConfig = Array<ColorOption>;
+/**
+ * The configuration of the table cell default properties feature.
+ */
+export interface TableCellPropertiesOptions {
+    /**
+     * The default `width` of the table cell.
+     */
+    width?: string;
+    /**
+     * The default `height` of the table cell.
+     */
+    height?: string;
+    /**
+     * The default `padding` of the table cell.
+     */
+    padding?: string;
+    /**
+     * The default `background-color` of the table cell.
+     */
+    backgroundColor?: string;
+    /**
+     * The default `border-color` of the table cell.
+     */
+    borderColor?: string;
+    /**
+     * The default `border-width` of the table cell.
+     */
+    borderWidth?: string;
+    /**
+     * The default `border-style` of the table cell.
+     *
+     * @default 'none'
+     */
+    borderStyle?: string;
+    /**
+     * The default `horizontalAlignment` of the table cell.
+     *
+     * @default 'center'
+     */
+    horizontalAlignment?: string;
+    /**
+     * The default `verticalAlignment` of the table cell.
+     *
+     * @default 'middle'
+     */
+    verticalAlignment?: string;
+}