@ckeditor/ckeditor5-table 36.0.1 → 37.0.0-alpha.0

package/src/tablecolumnresize/tablewidthscommand.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import { Command } from 'ckeditor5/src/core';
+/**
+ * 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/src/tablecolumnresize/tablewidthscommand.js

@@ -0,0 +1,61 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Command } from 'ckeditor5/src/core';
+import { normalizeColumnWidths } from './utils';
+/**
+ * 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() {
+        // The command is always enabled as it doesn't care about the actual selection - table can be resized
+        // even if the selection is elsewhere.
+        this.isEnabled = true;
+    }
+    /**
+     * Updated the `tableWidth` attribute of the table and the `columnWidth` attribute of the columns of that table.
+     */
+    execute(options = {}) {
+        const { model, plugins } = this.editor;
+        let { table = model.document.selection.getSelectedElement(), columnWidths, tableWidth } = options;
+        if (columnWidths) {
+            // For backwards compatibility, columnWidths might be an array or a string of comma-separated values.
+            columnWidths = Array.isArray(columnWidths) ?
+                columnWidths :
+                columnWidths.split(',');
+        }
+        model.change(writer => {
+            if (tableWidth) {
+                writer.setAttribute('tableWidth', tableWidth, table);
+            }
+            else {
+                writer.removeAttribute('tableWidth', table);
+            }
+            const tableColumnGroup = plugins
+                .get('TableColumnResizeEditing')
+                .getColumnGroupElement(table);
+            if (!columnWidths && !tableColumnGroup) {
+                return;
+            }
+            if (!columnWidths) {
+                return writer.remove(tableColumnGroup);
+            }
+            const widths = normalizeColumnWidths(columnWidths);
+            if (!tableColumnGroup) {
+                const colGroupElement = writer.createElement('tableColumnGroup');
+                widths.forEach(columnWidth => writer.appendElement('tableColumn', { columnWidth }, colGroupElement));
+                writer.append(colGroupElement, table);
+            }
+            else {
+                Array
+                    .from(tableColumnGroup.getChildren())
+                    .forEach((column, index) => writer.setAttribute('columnWidth', widths[index], column));
+            }
+        });
+    }
+}

package/src/tablecolumnresize/utils.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import type { Element, Model, Writer } from 'ckeditor5/src/engine';
+import type TableUtils from '../tableutils';
+/**
+ * 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.
+ *
+ * Currently, only widths provided as percentage values are supported.
+ *
+ * @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.
+ *
+ * @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>;