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

package/dist/types/tableediting.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @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/tableediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import type { PositionOffset, SlotFilter } from 'ckeditor5/src/engine.js';
+import TableUtils from '../src/tableutils.js';
+import '../theme/tableediting.css';
+/**
+ * The table editing feature.
+ */
+export default class TableEditing extends Plugin {
+    /**
+     * Handlers for creating additional slots in the table.
+     */
+    private _additionalSlots;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableEditing";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableUtils];
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Registers downcast handler for the additional table slot.
+     */
+    registerAdditionalSlot(slotHandler: AdditionalSlot): void;
+}
+/**
+ * By default, only the `tableRow` elements from the `table` model are downcast inside the `<table>` and
+ * all other elements are pushed outside the table. This handler allows creating additional slots inside
+ * the table for other elements.
+ *
+ * Take this model as an example:
+ *
+ * ```xml
+ * <table>
+ *   <tableRow>...</tableRow>
+ *   <tableRow>...</tableRow>
+ *   <tableColumnGroup>...</tableColumnGroup>
+ * </table>
+ * ```
+ *
+ * By default, downcasting result will be:
+ *
+ * ```xml
+ * <table>
+ *   <tbody>
+ *     <tr>...</tr>
+ *     <tr>...</tr>
+ *   </tbody>
+ * </table>
+ * <colgroup>...</colgroup>
+ * ```
+ *
+ * To allow the `tableColumnGroup` element at the end of the table, use the following configuration:
+ *
+ * ```ts
+ * const additionalSlot = {
+ *   filter: element => element.is( 'element', 'tableColumnGroup' ),
+ *   positionOffset: 'end'
+ * }
+ * ```
+ *
+ * Now, the downcast result will be:
+ *
+ * ```xml
+ * <table>
+ *   <tbody>
+ *     <tr>...</tr>
+ *     <tr>...</tr>
+ *   </tbody>
+ *   <colgroup>...</colgroup>
+ * </table>
+ * ```
+ */
+export interface AdditionalSlot {
+    /**
+     * Filter for elements that should be placed inside given slot.
+     */
+    filter: SlotFilter;
+    /**
+     * Position of the slot within the table.
+     */
+    positionOffset: PositionOffset;
+}

package/dist/types/tablekeyboard.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @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/tablekeyboard
+ */
+import TableSelection from './tableselection.js';
+import TableUtils from './tableutils.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+import { type ArrowKeyCodeDirection } from 'ckeditor5/src/utils.js';
+import type { Element } from 'ckeditor5/src/engine.js';
+/**
+ * This plugin enables keyboard navigation for tables.
+ * It is loaded automatically by the {@link module:table/table~Table} plugin.
+ */
+export default class TableKeyboard extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableKeyboard";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableSelection, typeof TableUtils];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Handles {@link module:engine/view/document~Document#event:tab tab} events for the <kbd>Tab</kbd> key executed
+     * when the table widget is selected.
+     */
+    private _handleTabOnSelectedTable;
+    /**
+     * Handles {@link module:engine/view/document~Document#event:tab tab} events for the <kbd>Tab</kbd> key executed
+     * inside table cells.
+     */
+    private _handleTab;
+    /**
+     * Handles {@link module:engine/view/document~Document#event:keydown keydown} events.
+     */
+    private _onArrowKey;
+    /**
+     * Handles arrow keys to move the selection around the table.
+     *
+     * @param direction The direction of the arrow key.
+     * @param expandSelection If the current selection should be expanded.
+     * @returns Returns `true` if key was handled.
+     */
+    private _handleArrowKeys;
+    /**
+     * Returns `true` if the selection is at the boundary of a table cell according to the navigation direction.
+     *
+     * @param selection The current selection.
+     * @param tableCell The current table cell element.
+     * @param isForward The expected navigation direction.
+     */
+    private _isSelectionAtCellEdge;
+    /**
+     * Moves the selection from the given table cell in the specified direction.
+     *
+     * @param focusCell The table cell that is current multi-cell selection focus.
+     * @param direction Direction in which selection should move.
+     * @param expandSelection If the current selection should be expanded. Default value is false.
+     */
+    protected _navigateFromCellInDirection(focusCell: Element, direction: ArrowKeyCodeDirection, expandSelection?: boolean): void;
+}

package/dist/types/tablemouse/mouseeventsobserver.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @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/tablemouse/mouseeventsobserver
+ */
+import { DomEventObserver, type DomEventData } from 'ckeditor5/src/engine.js';
+/**
+ * The mouse selection event observer.
+ *
+ * It registers listeners for the following DOM events:
+ *
+ * - `'mousemove'`
+ * - `'mouseleave'`
+ *
+ * Note that this observer is disabled by default. To enable this observer, it needs to be added to
+ * {@link module:engine/view/view~View} using the {@link module:engine/view/view~View#addObserver} method.
+ *
+ * The observer is registered by the {@link module:table/tableselection~TableSelection} plugin.
+ */
+export default class MouseEventsObserver extends DomEventObserver<'mousemove' | 'mouseleave'> {
+    readonly domEventType: readonly ["mousemove", "mouseleave"];
+    /**
+     * @inheritDoc
+     */
+    onDomEvent(domEvent: MouseEvent): void;
+}
+/**
+ * Fired when the mouse is moved over one of the editables.
+ *
+ * Introduced by {@link module:table/tablemouse/mouseeventsobserver~MouseEventsObserver}.
+ *
+ * Note that this event is not available by default. To make it available,
+ * {@link module:table/tablemouse/mouseeventsobserver~MouseEventsObserver} needs to be added
+ * to {@link module:engine/view/view~View} using the {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @see module:table/tablemouse/mouseeventsobserver~MouseEventsObserver
+ * @eventName module:engine/view/document~Document#mousemove
+ * @param data Event data.
+ */
+export type ViewDocumentMouseMoveEvent = {
+    name: 'mousemove';
+    args: [data: DomEventData<MouseEvent>];
+};
+/**
+ * Fired when the mouse is moved out of one of the editables.
+ *
+ * Introduced by {@link module:table/tablemouse/mouseeventsobserver~MouseEventsObserver}.
+ *
+ * Note that this event is not available by default. To make it available,
+ * {@link module:table/tablemouse/mouseeventsobserver~MouseEventsObserver} needs to be added
+ * to {@link module:engine/view/view~View} using the {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @see module:table/tablemouse/mouseeventsobserver~MouseEventsObserver
+ * @eventName module:engine/view/document~Document#mouseleave
+ * @param data Event data.
+ */
+export type ViewDocumentMouseLeaveEvent = {
+    name: 'mouseleave';
+    args: [data: DomEventData<MouseEvent>];
+};

package/dist/types/tablemouse.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @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/tablemouse
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import TableSelection from './tableselection.js';
+import TableUtils from './tableutils.js';
+/**
+ * This plugin enables a table cells' selection with the mouse.
+ * It is loaded automatically by the {@link module:table/table~Table} plugin.
+ */
+export default class TableMouse extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableMouse";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableSelection, typeof TableUtils];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Enables making cells selection by <kbd>Shift</kbd>+click. Creates a selection from the cell which previously held
+     * the selection to the cell which was clicked. It can be the same cell, in which case it selects a single cell.
+     */
+    private _enableShiftClickSelection;
+    /**
+     * Enables making cells selection by dragging.
+     *
+     * The selection is made only on mousemove. Mouse tracking is started on mousedown.
+     * However, the cells selection is enabled only after the mouse cursor left the anchor cell.
+     * Thanks to that normal text selection within one cell works just fine. However, you can still select
+     * just one cell by leaving the anchor cell and moving back to it.
+     */
+    private _enableMouseDragSelection;
+    /**
+     * Returns the model table cell element based on the target element of the passed DOM event.
+     *
+     * @returns Returns the table cell or `undefined`.
+     */
+    private _getModelTableCellFromDomEvent;
+}

package/dist/types/tableproperties/commands/tablealignmentcommand.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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/tableproperties/commands/tablealignmentcommand
+ */
+import type { Editor } from 'ckeditor5/src/core.js';
+import TablePropertyCommand from './tablepropertycommand.js';
+/**
+ * The table alignment command.
+ *
+ * The command is registered by the {@link module:table/tableproperties/tablepropertiesediting~TablePropertiesEditing} as
+ * the `'tableAlignment'` editor command.
+ *
+ * To change the alignment of the selected table, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableAlignment', {
+ *   value: 'right'
+ * } );
+ * ```
+ */
+export default class TableAlignmentCommand extends TablePropertyCommand {
+    /**
+     * Creates a new `TableAlignmentCommand` 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/dist/types/tableproperties/commands/tablebackgroundcolorcommand.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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/tableproperties/commands/tablebackgroundcolorcommand
+ */
+import type { Editor } from 'ckeditor5/src/core.js';
+import TablePropertyCommand from './tablepropertycommand.js';
+/**
+ * The table background color command.
+ *
+ * The command is registered by the {@link module:table/tableproperties/tablepropertiesediting~TablePropertiesEditing} as
+ * the `'tableBackgroundColor'` editor command.
+ *
+ * To change the background color of the selected table, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableBackgroundColor', {
+ *   value: '#f00'
+ * } );
+ * ```
+ */
+export default class TableBackgroundColorCommand extends TablePropertyCommand {
+    /**
+     * Creates a new `TableBackgroundColorCommand` 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);
+}

package/dist/types/tableproperties/commands/tablebordercolorcommand.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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/tableproperties/commands/tablebordercolorcommand
+ */
+import type { Element } from 'ckeditor5/src/engine.js';
+import type { Editor } from 'ckeditor5/src/core.js';
+import TablePropertyCommand from './tablepropertycommand.js';
+/**
+ * The table border color command.
+ *
+ * The command is registered by the {@link module:table/tableproperties/tablepropertiesediting~TablePropertiesEditing} as
+ * the `'tableBorderColor'` editor command.
+ *
+ * To change the border color of the selected table, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableBorderColor', {
+ *   value: '#f00'
+ * } );
+ * ```
+ */
+export default class TableBorderColorCommand extends TablePropertyCommand {
+    /**
+     * Creates a new `TableBorderColorCommand` 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
+     */
+    protected _getValue(table: Element): unknown;
+}

package/dist/types/tableproperties/commands/tableborderstylecommand.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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/tableproperties/commands/tableborderstylecommand
+ */
+import type { Element } from 'ckeditor5/src/engine.js';
+import TablePropertyCommand from './tablepropertycommand.js';
+import type { Editor } from 'ckeditor5/src/core.js';
+/**
+ * The table style border command.
+ *
+ * The command is registered by the {@link module:table/tableproperties/tablepropertiesediting~TablePropertiesEditing} as
+ * the `'tableBorderStyle'` editor command.
+ *
+ * To change the border style of the selected table, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableBorderStyle', {
+ *   value: 'dashed'
+ * } );
+ * ```
+ */
+export default class TableBorderStyleCommand extends TablePropertyCommand {
+    /**
+     * Creates a new `TableBorderStyleCommand` 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
+     */
+    protected _getValue(table: Element): unknown;
+}

package/dist/types/tableproperties/commands/tableborderwidthcommand.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @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/tableproperties/commands/tableborderwidthcommand
+ */
+import type { Element } from 'ckeditor5/src/engine.js';
+import type { Editor } from 'ckeditor5/src/core.js';
+import TablePropertyCommand from './tablepropertycommand.js';
+/**
+ * The table width border command.
+ *
+ * The command is registered by the {@link module:table/tableproperties/tablepropertiesediting~TablePropertiesEditing} as
+ * the `'tableBorderWidth'` editor command.
+ *
+ * To change the border width of the selected table, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableBorderWidth', {
+ *   value: '5px'
+ * } );
+ * ```
+ *
+ * **Note**: This command adds the default `'px'` unit to numeric values. Executing:
+ *
+ * ```ts
+ * editor.execute( 'tableBorderWidth', {
+ *   value: '5'
+ * } );
+ * ```
+ *
+ * will set the `borderWidth` attribute to `'5px'` in the model.
+ */
+export default class TableBorderWidthCommand extends TablePropertyCommand {
+    /**
+     * Creates a new `TableBorderWidthCommand` 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
+     */
+    protected _getValue(table: Element): string | undefined;
+    /**
+     * @inheritDoc
+     */
+    protected _getValueToSet(value: string | number | undefined): unknown;
+}

package/dist/types/tableproperties/commands/tableheightcommand.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @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/tableproperties/commands/tableheightcommand
+ */
+import TablePropertyCommand from './tablepropertycommand.js';
+import type { Editor } from 'ckeditor5/src/core.js';
+/**
+ * The table height command.
+ *
+ * The command is registered by the {@link module:table/tableproperties/tablepropertiesediting~TablePropertiesEditing} as
+ * the `'tableHeight'` editor command.
+ *
+ * To change the height of the selected table, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableHeight', {
+ *   value: '500px'
+ * } );
+ * ```
+ *
+ * **Note**: This command adds the default `'px'` unit to numeric values. Executing:
+ *
+ * ```ts
+ * editor.execute( 'tableHeight', {
+ *   value: '50'
+ * } );
+ * ```
+ *
+ * will set the `height` attribute to `'50px'` in the model.
+ */
+export default class TableHeightCommand extends TablePropertyCommand {
+    /**
+     * Creates a new `TableHeightCommand` 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
+     */
+    protected _getValueToSet(value: string | number | undefined): unknown;
+}

package/dist/types/tableproperties/commands/tablepropertycommand.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @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/tableproperties/commands/tablepropertycommand
+ */
+import type { Batch, Element } from 'ckeditor5/src/engine.js';
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+export interface TablePropertyCommandExecuteOptions {
+    batch?: Batch;
+    columnWidths?: string;
+    table?: Element;
+    tableWidth?: string;
+    value?: string;
+}
+/**
+ * The table cell attribute command.
+ *
+ * This command is a base command for other table property commands.
+ */
+export default class TablePropertyCommand extends Command {
+    /**
+     * The attribute that will be set by the command.
+     */
+    readonly attributeName: string;
+    /**
+     * The default value for the attribute.
+     */
+    protected readonly _defaultValue: string | undefined;
+    /**
+     * Creates a new `TablePropertyCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param attributeName Table cell attribute name.
+     * @param defaultValue The default value of the attribute.
+     */
+    constructor(editor: Editor, attributeName: string, defaultValue?: string);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options.value If set, the command will set the attribute on the selected table.
+     * If not set, the command will remove the attribute from the selected table.
+     * @param options.batch Pass the model batch instance to the command to aggregate changes,
+     * for example, to allow a single undo step for multiple executions.
+     */
+    execute(options?: TablePropertyCommandExecuteOptions): void;
+    /**
+     * Returns the attribute value for a table.
+     */
+    protected _getValue(table: Element): unknown;
+    /**
+     * Returns the proper model value. It can be used to add a default unit to numeric values.
+     */
+    protected _getValueToSet(value: string | number | undefined): unknown;
+}

package/dist/types/tableproperties/commands/tablewidthcommand.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @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/tableproperties/commands/tablewidthcommand
+ */
+import TablePropertyCommand from './tablepropertycommand.js';
+import type { Editor } from 'ckeditor5/src/core.js';
+/**
+ * The table width command.
+ *
+ * The command is registered by the {@link module:table/tableproperties/tablepropertiesediting~TablePropertiesEditing} as
+ * the `'tableWidth'` editor command.
+ *
+ * To change the width of the selected table, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableWidth', {
+ *   value: '400px'
+ * } );
+ * ```
+ *
+ * **Note**: This command adds the default `'px'` unit to numeric values. Executing:
+ *
+ * ```ts
+ * editor.execute( 'tableWidth', {
+ *   value: '50'
+ * } );
+ * ```
+ *
+ * will set the `width` attribute to `'50px'` in the model.
+ */
+export default class TableWidthCommand extends TablePropertyCommand {
+    /**
+     * Creates a new `TableWidthCommand` 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/tableproperties/tablepropertiesediting.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/tableproperties/tablepropertiesediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import TableEditing from '../tableediting.js';
+/**
+ * The table properties editing feature.
+ *
+ * Introduces table's model attributes and their conversion:
+ *
+ * - border: `tableBorderStyle`, `tableBorderColor` and `tableBorderWidth`
+ * - background color: `tableBackgroundColor`
+ * - horizontal alignment: `tableAlignment`
+ * - width & height: `tableWidth` & `tableHeight`
+ *
+ * It also registers commands used to manipulate the above attributes:
+ *
+ * - border: `'tableBorderStyle'`, `'tableBorderColor'` and `'tableBorderWidth'` commands
+ * - background color: `'tableBackgroundColor'`
+ * - horizontal alignment: `'tableAlignment'`
+ * - width & height: `'tableWidth'` & `'tableHeight'`
+ */
+export default class TablePropertiesEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TablePropertiesEditing";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableEditing];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}