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

package/dist/types/tableproperties/tablepropertiesui.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @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/tablepropertiesui
+ */
+import { type Editor, Plugin } from 'ckeditor5/src/core.js';
+import { ContextualBalloon } from 'ckeditor5/src/ui.js';
+import TablePropertiesView from './ui/tablepropertiesview.js';
+/**
+ * The table properties UI plugin. It introduces the `'tableProperties'` button
+ * that opens a form allowing to specify visual styling of an entire table.
+ *
+ * It uses the {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon plugin}.
+ */
+export default class TablePropertiesUI extends Plugin {
+    /**
+     * The default table properties.
+     */
+    private _defaultTableProperties;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    private _balloon;
+    /**
+     * The properties form view displayed inside the balloon.
+     */
+    view: TablePropertiesView | null;
+    /**
+     * The batch used to undo all changes made by the form (which are live, as the user types)
+     * when "Cancel" was pressed. Each time the view is shown, a new batch is created.
+     */
+    private _undoStepBatch?;
+    /**
+     * Flag used to indicate whether view is ready to execute update commands
+     * (it finished loading initial data).
+     */
+    private _isReady?;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ContextualBalloon];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TablePropertiesUI";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates the {@link module:table/tableproperties/ui/tablepropertiesview~TablePropertiesView} instance.
+     *
+     * @returns The table properties form view instance.
+     */
+    private _createPropertiesView;
+    /**
+     * In this method the "editor data -> UI" binding is happening.
+     *
+     * When executed, this method obtains selected table property values from various table commands
+     * and passes them to the {@link #view}.
+     *
+     * This way, the UI stays up–to–date with the editor data.
+     */
+    private _fillViewFormFromCommandValues;
+    /**
+     * Shows the {@link #view} in the {@link #_balloon}.
+     *
+     * **Note**: Each time a view is shown, the new {@link #_undoStepBatch} is created that contains
+     * all changes made to the document when the view is visible, allowing a single undo step
+     * for all of them.
+     */
+    protected _showView(): void;
+    /**
+     * Removes the {@link #view} from the {@link #_balloon}.
+     */
+    protected _hideView(): void;
+    /**
+     * Repositions the {@link #_balloon} or hides the {@link #view} if a table is no longer selected.
+     */
+    protected _updateView(): void;
+    /**
+     * Returns `true` when the {@link #view} is the visible in the {@link #_balloon}.
+     */
+    private get _isViewVisible();
+    /**
+     * Returns `true` when the {@link #view} is in the {@link #_balloon}.
+     */
+    private get _isViewInBalloon();
+    /**
+     * Creates a callback that when executed upon {@link #view view's} property change
+     * executes a related editor command with the new property value.
+     *
+     * If new value will be set to the default value, the command will not be executed.
+     *
+     * @param commandName The command that will be executed.
+     */
+    private _getPropertyChangeCallback;
+    /**
+     * Creates a callback that when executed upon {@link #view view's} property change:
+     * * executes a related editor command with the new property value if the value is valid,
+     * * or sets the error text next to the invalid field, if the value did not pass the validation.
+     */
+    private _getValidatedPropertyChangeCallback;
+}

package/dist/types/tableproperties/ui/tablepropertiesview.d.ts

@@ -0,0 +1,207 @@
+/**
+ * @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/ui/tablepropertiesview
+ */
+import { ButtonView, FocusCycler, LabeledFieldView, ToolbarView, View, ViewCollection, type DropdownView, type InputTextView, type NormalizedColorOption, type ColorPickerConfig, type FocusableView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import '../../../theme/form.css';
+import '../../../theme/tableform.css';
+import '../../../theme/tableproperties.css';
+import type ColorInputView from '../../ui/colorinputview.js';
+import type { TablePropertiesOptions } from '../../tableconfig.js';
+/**
+ * Additional configuration of the view.
+ */
+export interface TablePropertiesViewOptions {
+    /**
+     * A configuration of the border color palette used by the
+     * {@link module:table/tableproperties/ui/tablepropertiesview~TablePropertiesView#borderColorInput}.
+     */
+    borderColors: Array<NormalizedColorOption>;
+    /**
+     * A configuration of the background color palette used by the
+     * {@link module:table/tableproperties/ui/tablepropertiesview~TablePropertiesView#backgroundInput}.
+     */
+    backgroundColors: Array<NormalizedColorOption>;
+    /**
+     * The default table properties.
+     */
+    defaultTableProperties: TablePropertiesOptions;
+    /**
+     * The default color picker config.
+     */
+    colorPickerConfig: false | ColorPickerConfig;
+}
+/**
+ * The class representing a table properties form, allowing users to customize
+ * certain style aspects of a table, for instance, border, background color, alignment, etc..
+ */
+export default class TablePropertiesView extends View {
+    /**
+     * The value of the border style.
+     *
+     * @observable
+     * @default ''
+     */
+    borderStyle: string;
+    /**
+     * The value of the border width style.
+     *
+     * @observable
+     * @default ''
+     */
+    borderWidth: string;
+    /**
+     * The value of the border color style.
+     *
+     * @observable
+     * @default ''
+     */
+    borderColor: string;
+    /**
+     * The value of the background color style.
+     *
+     * @observable
+     * @default ''
+     */
+    backgroundColor: string;
+    /**
+     * The value of the table width style.
+     *
+     * @observable
+     * @default ''
+     */
+    width: string;
+    /**
+     * The value of the table height style.
+     *
+     * @observable
+     * @default ''
+     */
+    height: string;
+    /**
+     * The value of the table alignment style.
+     *
+     * @observable
+     * @default ''
+     */
+    alignment: string;
+    /**
+     * Options passed to the view. See {@link #constructor} to learn more.
+     */
+    readonly options: TablePropertiesViewOptions;
+    /**
+     * 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 border.
+     */
+    readonly borderStyleDropdown: LabeledFieldView<DropdownView>;
+    /**
+     * An input that allows specifying the width of the table border.
+     */
+    readonly borderWidthInput: LabeledFieldView<InputTextView>;
+    /**
+     * An input that allows specifying the color of the table border.
+     */
+    readonly borderColorInput: LabeledFieldView<ColorInputView>;
+    /**
+     * An input that allows specifying the table background color.
+     */
+    readonly backgroundInput: LabeledFieldView<ColorInputView>;
+    /**
+     * An input that allows specifying the table width.
+     */
+    readonly widthInput: LabeledFieldView<InputTextView>;
+    /**
+     * An input that allows specifying the table height.
+     */
+    readonly heightInput: LabeledFieldView<InputTextView>;
+    /**
+     * A toolbar with buttons that allow changing the alignment of an entire table.
+     */
+    readonly alignmentToolbar: 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.
+     */
+    constructor(locale: Locale, options: TablePropertiesViewOptions);
+    /**
+     * @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 #alignmentToolbar}.
+     */
+    private _createAlignmentFields;
+    /**
+     * Creates the following form controls:
+     *
+     * * {@link #saveButtonView},
+     * * {@link #cancelButtonView}.
+     */
+    private _createActionButtons;
+    /**
+     * Provides localized labels for {@link #alignmentToolbar} buttons.
+     */
+    private get _alignmentLabels();
+}

package/dist/types/tableproperties.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @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
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import TablePropertiesEditing from './tableproperties/tablepropertiesediting.js';
+import TablePropertiesUI from './tableproperties/tablepropertiesui.js';
+/**
+ * The table properties feature. Enables support for setting properties of tables (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/tablecellproperties~TableCellProperties} plugin.
+ *
+ * This is a "glue" plugin that loads the
+ * {@link module:table/tableproperties/tablepropertiesediting~TablePropertiesEditing table properties editing feature} and
+ * the {@link module:table/tableproperties/tablepropertiesui~TablePropertiesUI table properties UI feature}.
+ */
+export default class TableProperties extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableProperties";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TablePropertiesEditing, typeof TablePropertiesUI];
+}

package/dist/types/tableselection.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @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/tableselection
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import type { Element, DocumentFragment } from 'ckeditor5/src/engine.js';
+import TableUtils from './tableutils.js';
+import '../theme/tableselection.css';
+/**
+ * This plugin enables the advanced table cells, rows and columns selection.
+ * It is loaded automatically by the {@link module:table/table~Table} plugin.
+ */
+export default class TableSelection extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableSelection";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableUtils, typeof TableUtils];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Returns the currently selected table cells or `null` if it is not a table cells selection.
+     */
+    getSelectedTableCells(): Array<Element> | null;
+    /**
+     * Returns the selected table fragment as a document fragment.
+     */
+    getSelectionAsFragment(): DocumentFragment | null;
+    /**
+     * Sets the model selection based on given anchor and target cells (can be the same cell).
+     * Takes care of setting the backward flag.
+     *
+     * ```ts
+     * const modelRoot = editor.model.document.getRoot();
+     * const firstCell = modelRoot.getNodeByPath( [ 0, 0, 0 ] );
+     * const lastCell = modelRoot.getNodeByPath( [ 0, 0, 1 ] );
+     *
+     * const tableSelection = editor.plugins.get( 'TableSelection' );
+     * tableSelection.setCellSelection( firstCell, lastCell );
+     * ```
+     */
+    setCellSelection(anchorCell: Element, targetCell: Element): void;
+    /**
+     * Returns the focus cell from the current selection.
+     */
+    getFocusCell(): Element | null;
+    /**
+     * Returns the anchor cell from the current selection.
+     */
+    getAnchorCell(): Element | null;
+    /**
+     * Defines a selection converter which marks the selected cells with a specific class.
+     *
+     * The real DOM selection is put in the last cell. Since the order of ranges is dependent on whether the
+     * selection is backward or not, the last cell will usually be close to the "focus" end of the selection
+     * (a selection has anchor and focus).
+     *
+     * The real DOM selection is then hidden with CSS.
+     */
+    private _defineSelectionConverter;
+    /**
+     * Creates a listener that reacts to changes in {@link #isEnabled} and, if the plugin was disabled,
+     * it collapses the multi-cell selection to a regular selection placed inside a table cell.
+     *
+     * This listener helps features that disable the table selection plugin bring the selection
+     * to a clear state they can work with (for instance, because they don't support multiple cell selection).
+     */
+    private _enablePluginDisabling;
+    /**
+     * Overrides the default `model.deleteContent()` behavior over a selected table fragment.
+     *
+     * @param args Delete content method arguments.
+     */
+    private _handleDeleteContent;
+    /**
+     * This handler makes it possible to remove the content of all selected cells by starting to type.
+     * If you take a look at {@link #_defineSelectionConverter} you will find out that despite the multi-cell selection being set
+     * in the model, the view selection is collapsed in the last cell (because most browsers are unable to render multi-cell selections;
+     * yes, it's a hack).
+     *
+     * When multiple cells are selected in the model and the user starts to type, the
+     * {@link module:engine/view/document~Document#event:insertText} event carries information provided by the
+     * beforeinput DOM  event, that in turn only knows about this collapsed DOM selection in the last cell.
+     *
+     * As a result, the selected cells have no chance to be cleaned up. To fix this, this listener intercepts
+     * the event and injects the custom view selection in the data that translates correctly to the actual state
+     * of the multi-cell selection in the model.
+     *
+     * @param data Insert text event data.
+     */
+    private _handleInsertTextEvent;
+    /**
+     * Returns an array of table cells that should be selected based on the
+     * given anchor cell and target (focus) cell.
+     *
+     * The cells are returned in a reverse direction if the selection is backward.
+     */
+    private _getCellsToSelect;
+}

package/dist/types/tabletoolbar.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/tabletoolbar
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { WidgetToolbarRepository } from 'ckeditor5/src/widget.js';
+/**
+ * The table toolbar class. It creates toolbars for the table feature and its content (for now only for the table cell content).
+ *
+ * The table toolbar shows up when a table widget is selected. Its components (e.g. buttons) are created based on the
+ * {@link module:table/tableconfig~TableConfig#tableToolbar `table.tableToolbar` configuration option}.
+ *
+ * Table content toolbar shows up when the selection is inside the content of a table. It creates its component based on the
+ * {@link module:table/tableconfig~TableConfig#contentToolbar `table.contentToolbar` configuration option}.
+ */
+export default class TableToolbar extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof WidgetToolbarRepository];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableToolbar";
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+}

package/dist/types/tableui.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @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/tableui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * The table UI plugin. It introduces:
+ *
+ * * The `'insertTable'` dropdown,
+ * * The `'tableColumn'` dropdown,
+ * * The `'tableRow'` dropdown,
+ * * The `'mergeTableCells'` split button.
+ *
+ * The `'tableColumn'`, `'tableRow'` and `'mergeTableCells'` dropdowns work best with {@link module:table/tabletoolbar~TableToolbar}.
+ */
+export default class TableUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableUI";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates a dropdown view from a set of options.
+     *
+     * @param label The dropdown button label.
+     * @param icon An icon for the dropdown button.
+     * @param options The list of options for the dropdown.
+     */
+    private _prepareDropdown;
+    /**
+     * Creates a dropdown view with a {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView} for
+     * merge (and split)–related commands.
+     *
+     * @param label The dropdown button label.
+     * @param icon An icon for the dropdown button.
+     * @param options The list of options for the dropdown.
+     */
+    private _prepareMergeSplitButtonDropdown;
+    /**
+     * Injects a {@link module:ui/list/listview~ListView} into the passed dropdown with buttons
+     * which execute editor commands as configured in passed options.
+     *
+     * @param options The list of options for the dropdown.
+     * @returns Commands the list options are interacting with.
+     */
+    private _fillDropdownWithListOptions;
+}