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

package/dist/types/tablecellproperties/ui/tablecellpropertiesview.d.ts

@@ -0,0 +1,232 @@
+/**
+ * @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
+ */
+/**
+ * @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/ui/tablecellpropertiesview
+ */
+import { ButtonView, FocusCycler, LabeledFieldView, ToolbarView, View, ViewCollection, type FocusableView, type NormalizedColorOption, type ColorPickerConfig } from 'ckeditor5/src/ui.js';
+import { KeystrokeHandler, FocusTracker, type Locale } from 'ckeditor5/src/utils.js';
+import type ColorInputView from '../../ui/colorinputview.js';
+import type { TableCellPropertiesOptions } from '../../tableconfig.js';
+import '../../../theme/form.css';
+import '../../../theme/tableform.css';
+import '../../../theme/tablecellproperties.css';
+export interface TableCellPropertiesViewOptions {
+    borderColors: Array<NormalizedColorOption>;
+    backgroundColors: Array<NormalizedColorOption>;
+    defaultTableCellProperties: TableCellPropertiesOptions;
+    colorPickerConfig: false | ColorPickerConfig;
+}
+/**
+ * The class representing a table cell properties form, allowing users to customize
+ * certain style aspects of a table cell, for instance, border, padding, text alignment, etc..
+ */
+export default class TableCellPropertiesView extends View {
+    /**
+     * The value of the cell border style.
+     *
+     * @observable
+     * @default ''
+     */
+    borderStyle: string;
+    /**
+     * The value of the cell border width style.
+     *
+     * @observable
+     * @default ''
+     */
+    borderWidth: string;
+    /**
+     * The value of the cell border color style.
+     *
+     * @observable
+     * @default ''
+     */
+    borderColor: string;
+    /**
+     * The value of the cell padding style.
+     *
+     * @observable
+     * @default ''
+     */
+    padding: string;
+    /**
+     * The value of the cell background color style.
+     *
+     * @observable
+     * @default ''
+     */
+    backgroundColor: string;
+    /**
+     * The value of the table cell width style.
+     *
+     * @observable
+     * @default ''
+     */
+    width: string;
+    /**
+     * The value of the table cell height style.
+     *
+     * @observable
+     * @default ''
+     */
+    height: string;
+    /**
+     * The value of the horizontal text alignment style.
+     *
+     * @observable
+     * @default ''
+     */
+    horizontalAlignment: string;
+    /**
+     * The value of the vertical text alignment style.
+     *
+     * @observable
+     * @default ''
+     */
+    verticalAlignment: string;
+    /**
+     * Options passed to the view. See {@link #constructor} to learn more.
+     */
+    readonly options: TableCellPropertiesViewOptions;
+    /**
+     * Tracks information about the DOM focus in the form.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * A collection of child views in the form.
+     */
+    readonly children: ViewCollection;
+    /**
+     * A dropdown that allows selecting the style of the table cell border.
+     */
+    readonly borderStyleDropdown: LabeledFieldView<FocusableView>;
+    /**
+     * An input that allows specifying the width of the table cell border.
+     */
+    readonly borderWidthInput: LabeledFieldView<FocusableView>;
+    /**
+     * An input that allows specifying the color of the table cell border.
+     */
+    readonly borderColorInput: LabeledFieldView<ColorInputView>;
+    /**
+     * An input that allows specifying the table cell background color.
+     */
+    readonly backgroundInput: LabeledFieldView<ColorInputView>;
+    /**
+     * An input that allows specifying the table cell padding.
+     */
+    readonly paddingInput: LabeledFieldView;
+    /**
+     * An input that allows specifying the table cell width.
+     */
+    readonly widthInput: LabeledFieldView<FocusableView>;
+    /**
+     * An input that allows specifying the table cell height.
+     */
+    readonly heightInput: LabeledFieldView<FocusableView>;
+    /**
+     * A toolbar with buttons that allow changing the horizontal text alignment in a table cell.
+     */
+    readonly horizontalAlignmentToolbar: ToolbarView;
+    /**
+     * A toolbar with buttons that allow changing the vertical text alignment in a table cell.
+     */
+    readonly verticalAlignmentToolbar: ToolbarView;
+    /**
+     * The "Save" button view.
+     */
+    saveButtonView: ButtonView;
+    /**
+     * The "Cancel" button view.
+     */
+    cancelButtonView: ButtonView;
+    /**
+     * A collection of views that can be focused in the form.
+     */
+    protected readonly _focusables: ViewCollection<FocusableView>;
+    /**
+     * Helps cycling over {@link #_focusables} in the form.
+     */
+    protected readonly _focusCycler: FocusCycler;
+    /**
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param options Additional configuration of the view.
+     * @param options.borderColors A configuration of the border color palette used by the
+     * {@link module:table/tablecellproperties/ui/tablecellpropertiesview~TableCellPropertiesView#borderColorInput}.
+     * @param options.backgroundColors A configuration of the background color palette used by the
+     * {@link module:table/tablecellproperties/ui/tablecellpropertiesview~TableCellPropertiesView#backgroundInput}.
+     * @param options.defaultTableCellProperties The default table cell properties.
+     */
+    constructor(locale: Locale, options: TableCellPropertiesViewOptions);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the fist focusable field in the form.
+     */
+    focus(): void;
+    /**
+     * Creates the following form fields:
+     *
+     * * {@link #borderStyleDropdown},
+     * * {@link #borderWidthInput},
+     * * {@link #borderColorInput}.
+     */
+    private _createBorderFields;
+    /**
+     * Creates the following form fields:
+     *
+     * * {@link #backgroundInput}.
+     */
+    private _createBackgroundFields;
+    /**
+     * Creates the following form fields:
+     *
+     * * {@link #widthInput}.
+     * * {@link #heightInput}.
+     */
+    private _createDimensionFields;
+    /**
+     * Creates the following form fields:
+     *
+     * * {@link #paddingInput}.
+     */
+    private _createPaddingField;
+    /**
+     * Creates the following form fields:
+     *
+     * * {@link #horizontalAlignmentToolbar},
+     * * {@link #verticalAlignmentToolbar}.
+     */
+    private _createAlignmentFields;
+    /**
+     * Creates the following form controls:
+     *
+     * * {@link #saveButtonView},
+     * * {@link #cancelButtonView}.
+     */
+    private _createActionButtons;
+    /**
+     * Provides localized labels for {@link #horizontalAlignmentToolbar} buttons.
+     */
+    private get _horizontalAlignmentLabels();
+    /**
+     * Provides localized labels for {@link #verticalAlignmentToolbar} buttons.
+     */
+    private get _verticalAlignmentLabels();
+}

package/dist/types/tablecellproperties.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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
+ */
+/**
+ * @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
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import TableCellPropertiesUI from './tablecellproperties/tablecellpropertiesui.js';
+import TableCellPropertiesEditing from './tablecellproperties/tablecellpropertiesediting.js';
+/**
+ * The table cell properties feature. Enables support for setting properties of table cells (size, border, background, etc.).
+ *
+ * Read more in the {@glink features/tables/tables-styling Table and cell styling tools} section.
+ * See also the {@link module:table/tableproperties~TableProperties} plugin.
+ *
+ * This is a "glue" plugin that loads the
+ * {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing table cell properties editing feature} and
+ * the {@link module:table/tablecellproperties/tablecellpropertiesui~TableCellPropertiesUI table cell properties UI feature}.
+ */
+export default class TableCellProperties extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableCellProperties";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableCellPropertiesEditing, typeof TableCellPropertiesUI];
+}

package/dist/types/tablecellwidth/commands/tablecellwidthcommand.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @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
+ */
+/**
+ * @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/tablecellwidth/commands/tablecellwidthcommand
+ */
+import type { Editor } from 'ckeditor5/src/core.js';
+import TableCellPropertyCommand from '../../tablecellproperties/commands/tablecellpropertycommand.js';
+/**
+ * The table cell width command.
+ *
+ * The command is registered by the {@link module:table/tablecellwidth/tablecellwidthediting~TableCellWidthEditing} as
+ * the `'tableCellWidth'` editor command.
+ *
+ * To change the width of selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableCellWidth', {
+ *   value: '50px'
+ * } );
+ * ```
+ *
+ * **Note**: This command adds a default `'px'` unit to numeric values. Executing:
+ *
+ * ```ts
+ * editor.execute( 'tableCellWidth', {
+ *   value: '50'
+ * } );
+ * ```
+ *
+ * will set the `width` attribute to `'50px'` in the model.
+ */
+export default class TableCellWidthCommand extends TableCellPropertyCommand {
+    /**
+     * Creates a new `TableCellWidthCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param defaultValue The default value of the attribute.
+     */
+    constructor(editor: Editor, defaultValue: string);
+    /**
+     * @inheritDoc
+     */
+    _getValueToSet(value: string | number | undefined): unknown;
+}

package/dist/types/tablecellwidth/tablecellwidthediting.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @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
+ */
+/**
+ * @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/tablecellwidth/tablecellwidthediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import TableEditing from './../tableediting.js';
+/**
+ * The table cell width editing feature.
+ *
+ * Introduces `tableCellWidth` table cell model attribute alongside with its converters
+ * and a command.
+ */
+export default class TableCellWidthEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableCellWidthEditing";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableEditing];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/tableclipboard.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @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
+ */
+/**
+ * @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 { ClipboardPipeline, ClipboardMarkersUtils } from 'ckeditor5/src/clipboard.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+import type { DocumentFragment, Element, Item, Model, Position, Writer } from 'ckeditor5/src/engine.js';
+import TableSelection from './tableselection.js';
+import { type TableSlot } from './tablewalker.js';
+import TableUtils from './tableutils.js';
+/**
+ * This plugin adds support for copying/cutting/pasting fragments of tables.
+ * It is loaded automatically by the {@link module:table/table~Table} plugin.
+ */
+export default class TableClipboard extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableClipboard";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ClipboardMarkersUtils, typeof ClipboardPipeline, typeof TableSelection, typeof TableUtils];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Copies table content to a clipboard on "copy" & "cut" events.
+     *
+     * @param evt An object containing information about the handled event.
+     * @param data Clipboard event data.
+     */
+    private _onCopyCut;
+    /**
+     * Overrides default {@link module:engine/model/model~Model#insertContent `model.insertContent()`} method to handle pasting table inside
+     * selected table fragment.
+     *
+     * Depending on selected table fragment:
+     * - If a selected table fragment is smaller than paste table it will crop pasted table to match dimensions.
+     * - If dimensions are equal it will replace selected table fragment with a pasted table contents.
+     *
+     * @param content The content to insert.
+     * @param selectable The selection into which the content should be inserted.
+     * If not provided the current model document selection will be used.
+     */
+    private _onInsertContent;
+    /**
+     * Inserts provided `selectedTableCells` into `pastedTable`.
+     */
+    private _replaceSelectedCells;
+    /**
+     * Replaces the part of selectedTable with pastedTable.
+     */
+    private _replaceSelectedCellsWithPasted;
+    /**
+     * Replaces a single table slot.
+     *
+     * @returns Inserted table cell or null if slot should remain empty.
+     * @private
+     */
+    _replaceTableSlotCell(tableSlot: TableSlot, cellToInsert: Element | null, insertPosition: Position, writer: Writer): Element | null;
+    /**
+     * Extracts the table for pasting into a table.
+     *
+     * @param content The content to insert.
+     * @param model The editor model.
+     */
+    getTableIfOnlyTableInContent(content: DocumentFragment | Item, model: Model): Element | null;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * @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
+ */
+/**
+ * @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/constants
+ */
+/**
+ * The minimum column width given as a percentage value. Used in situations when the table is not yet rendered, so it is impossible to
+ * calculate how many percentage of the table width would be {@link ~COLUMN_MIN_WIDTH_IN_PIXELS minimum column width in pixels}.
+ */
+export declare const COLUMN_MIN_WIDTH_AS_PERCENTAGE = 5;
+/**
+ * The minimum column width in pixels when the maximum table width is known.
+ */
+export declare const COLUMN_MIN_WIDTH_IN_PIXELS = 40;
+/**
+ * Determines how many digits after the decimal point are used to store the column width as a percentage value.
+ */
+export declare const COLUMN_WIDTH_PRECISION = 2;

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

@@ -0,0 +1,22 @@
+/**
+ * @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
+ */
+/**
+ * @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/converters
+ */
+import type { DowncastDispatcher, UpcastDispatcher } from 'ckeditor5/src/engine.js';
+import type TableUtils from '../tableutils.js';
+/**
+ * Returns a upcast helper that ensures the number of `<tableColumn>` elements corresponds to the actual number of columns in the table,
+ * because the input data might have too few or too many <col> elements.
+ */
+export declare function upcastColgroupElement(tableUtilsPlugin: TableUtils): (dispatcher: UpcastDispatcher) => void;
+/**
+ * Returns downcast helper for adding `ck-table-resized` class if there is a `<tableColumnGroup>` element inside the table.
+ */
+export declare function downcastTableResizedClass(): (dispatcher: DowncastDispatcher) => void;

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

@@ -0,0 +1,143 @@
+/**
+ * @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
+ */
+/**
+ * @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,42 @@
+/**
+ * @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
+ */
+/**
+ * @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;
+}