@ckeditor/ckeditor5-table 0.0.0-internal-20241017.0

package/src/tablecaption/tablecaptionediting.js

@@ -0,0 +1,128 @@
+/**
+ * @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/tablecaption/tablecaptionediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { Element, enablePlaceholder } from 'ckeditor5/src/engine.js';
+import { toWidgetEditable } from 'ckeditor5/src/widget.js';
+import injectTableCaptionPostFixer from '../converters/table-caption-post-fixer.js';
+import ToggleTableCaptionCommand from './toggletablecaptioncommand.js';
+import { isTable, matchTableCaptionViewElement } from './utils.js';
+/**
+ * The table caption editing plugin.
+ */
+export default class TableCaptionEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'TableCaptionEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        super(editor);
+        this._savedCaptionsMap = new WeakMap();
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const schema = editor.model.schema;
+        const view = editor.editing.view;
+        const t = editor.t;
+        if (!schema.isRegistered('caption')) {
+            schema.register('caption', {
+                allowIn: 'table',
+                allowContentOf: '$block',
+                isLimit: true
+            });
+        }
+        else {
+            schema.extend('caption', {
+                allowIn: 'table'
+            });
+        }
+        editor.commands.add('toggleTableCaption', new ToggleTableCaptionCommand(this.editor));
+        // View -> model converter for the data pipeline.
+        editor.conversion.for('upcast').elementToElement({
+            view: matchTableCaptionViewElement,
+            model: 'caption'
+        });
+        // Model -> view converter for the data pipeline.
+        editor.conversion.for('dataDowncast').elementToElement({
+            model: 'caption',
+            view: (modelElement, { writer }) => {
+                if (!isTable(modelElement.parent)) {
+                    return null;
+                }
+                return writer.createContainerElement('figcaption');
+            }
+        });
+        // Model -> view converter for the editing pipeline.
+        editor.conversion.for('editingDowncast').elementToElement({
+            model: 'caption',
+            view: (modelElement, { writer }) => {
+                if (!isTable(modelElement.parent)) {
+                    return null;
+                }
+                const figcaptionElement = writer.createEditableElement('figcaption');
+                writer.setCustomProperty('tableCaption', true, figcaptionElement);
+                figcaptionElement.placeholder = t('Enter table caption');
+                enablePlaceholder({
+                    view,
+                    element: figcaptionElement,
+                    keepOnFocus: true
+                });
+                return toWidgetEditable(figcaptionElement, writer);
+            }
+        });
+        injectTableCaptionPostFixer(editor.model);
+    }
+    /**
+     * Returns the saved {@link module:engine/model/element~Element#toJSON JSONified} caption
+     * of a table model element.
+     *
+     * See {@link #_saveCaption}.
+     *
+     * @internal
+     * @param tableModelElement The model element the caption should be returned for.
+     * @returns The model caption element or `null` if there is none.
+     */
+    _getSavedCaption(tableModelElement) {
+        const jsonObject = this._savedCaptionsMap.get(tableModelElement);
+        return jsonObject ? Element.fromJSON(jsonObject) : null;
+    }
+    /**
+     * Saves a {@link module:engine/model/element~Element#toJSON JSONified} caption for
+     * a table element to allow restoring it in the future.
+     *
+     * A caption is saved every time it gets hidden. The
+     * user should be able to restore it on demand.
+     *
+     * **Note**: The caption cannot be stored in the table model element attribute because,
+     * for instance, when the model state propagates to collaborators, the attribute would get
+     * lost (mainly because it does not convert to anything when the caption is hidden) and
+     * the states of collaborators' models would de-synchronize causing numerous issues.
+     *
+     * See {@link #_getSavedCaption}.
+     *
+     * @internal
+     * @param tableModelElement The model element the caption is saved for.
+     * @param caption The caption model element to be saved.
+     */
+    _saveCaption(tableModelElement, caption) {
+        this._savedCaptionsMap.set(tableModelElement, caption.toJSON());
+    }
+}

package/src/tablecaption/tablecaptionui.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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/tablecaption/tablecaptionui
+*/
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+  * The table caption UI plugin. It introduces the `'toggleTableCaption'` UI button.
+  */
+export default class TableCaptionUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableCaptionUI";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/src/tablecaption/tablecaptionui.js

@@ -0,0 +1,63 @@
+/**
+ * @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/tablecaption/tablecaptionui
+*/
+import { Plugin, icons } from 'ckeditor5/src/core.js';
+import { ButtonView } from 'ckeditor5/src/ui.js';
+import { getCaptionFromModelSelection } from './utils.js';
+/**
+  * The table caption UI plugin. It introduces the `'toggleTableCaption'` UI button.
+  */
+export default class TableCaptionUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'TableCaptionUI';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const editingView = editor.editing.view;
+        const t = editor.t;
+        editor.ui.componentFactory.add('toggleTableCaption', locale => {
+            const command = editor.commands.get('toggleTableCaption');
+            const view = new ButtonView(locale);
+            view.set({
+                icon: icons.caption,
+                tooltip: true,
+                isToggleable: true
+            });
+            view.bind('isOn', 'isEnabled').to(command, 'value', 'isEnabled');
+            view.bind('label').to(command, 'value', value => value ? t('Toggle caption off') : t('Toggle caption on'));
+            this.listenTo(view, 'execute', () => {
+                editor.execute('toggleTableCaption', { focusCaptionOnShow: true });
+                // Scroll to the selection and highlight the caption if the caption showed up.
+                if (command.value) {
+                    const modelCaptionElement = getCaptionFromModelSelection(editor.model.document.selection);
+                    const figcaptionElement = editor.editing.mapper.toViewElement(modelCaptionElement);
+                    if (!figcaptionElement) {
+                        return;
+                    }
+                    editingView.scrollToTheSelection();
+                    editingView.change(writer => {
+                        writer.addClass('table__caption_highlighted', figcaptionElement);
+                    });
+                }
+                editor.editing.view.focus();
+            });
+            return view;
+        });
+    }
+}

package/src/tablecaption/toggletablecaptioncommand.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/tablecaption/toggletablecaptioncommand
+*/
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The toggle table caption command.
+ *
+ * This command is registered by {@link module:table/tablecaption/tablecaptionediting~TableCaptionEditing} as the
+ * `'toggleTableCaption'` editor command.
+ *
+ * Executing this command:
+ *
+ * * either adds or removes the table caption of a selected table (depending on whether the caption is present or not),
+ * * removes the table caption if the selection is anchored in one.
+ *
+ * ```ts
+ * // Toggle the presence of the caption.
+ * editor.execute( 'toggleTableCaption' );
+ * ```
+ *
+ * **Note**: You can move the selection to the caption right away as it shows up upon executing this command by using
+ * the `focusCaptionOnShow` option:
+ *
+ * ```ts
+ * editor.execute( 'toggleTableCaption', { focusCaptionOnShow: true } );
+ * ```
+ */
+export default class ToggleTableCaptionCommand extends Command {
+    value: boolean;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * ```ts
+     * editor.execute( 'toggleTableCaption' );
+     * ```
+     *
+     * @param options Options for the executed command.
+     * @param options.focusCaptionOnShow When true and the caption shows up, the selection will be moved into it straight away.
+     * @fires execute
+     */
+    execute({ focusCaptionOnShow }?: {
+        focusCaptionOnShow?: boolean;
+    }): void;
+    /**
+     * Shows the table caption. Also:
+     *
+     * * it attempts to restore the caption content from the `TableCaptionEditing` caption registry,
+     * * it moves the selection to the caption right away, it the `focusCaptionOnShow` option was set.
+     *
+     * @param focusCaptionOnShow Default focus behavior when showing the caption.
+     */
+    private _showTableCaption;
+    /**
+     * Hides the caption of a selected table (or an table caption the selection is anchored to).
+     *
+     * The content of the caption is stored in the `TableCaptionEditing` caption registry to make this
+     * a reversible action.
+     */
+    private _hideTableCaption;
+}

package/src/tablecaption/toggletablecaptioncommand.js

@@ -0,0 +1,105 @@
+/**
+ * @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/tablecaption/toggletablecaptioncommand
+*/
+import { Command } from 'ckeditor5/src/core.js';
+import { getCaptionFromTableModelElement } from './utils.js';
+import { getSelectionAffectedTable } from '../utils/common.js';
+/**
+ * The toggle table caption command.
+ *
+ * This command is registered by {@link module:table/tablecaption/tablecaptionediting~TableCaptionEditing} as the
+ * `'toggleTableCaption'` editor command.
+ *
+ * Executing this command:
+ *
+ * * either adds or removes the table caption of a selected table (depending on whether the caption is present or not),
+ * * removes the table caption if the selection is anchored in one.
+ *
+ * ```ts
+ * // Toggle the presence of the caption.
+ * editor.execute( 'toggleTableCaption' );
+ * ```
+ *
+ * **Note**: You can move the selection to the caption right away as it shows up upon executing this command by using
+ * the `focusCaptionOnShow` option:
+ *
+ * ```ts
+ * editor.execute( 'toggleTableCaption', { focusCaptionOnShow: true } );
+ * ```
+ */
+export default class ToggleTableCaptionCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        const editor = this.editor;
+        const tableElement = getSelectionAffectedTable(editor.model.document.selection);
+        this.isEnabled = !!tableElement;
+        if (!this.isEnabled) {
+            this.value = false;
+        }
+        else {
+            this.value = !!getCaptionFromTableModelElement(tableElement);
+        }
+    }
+    /**
+     * Executes the command.
+     *
+     * ```ts
+     * editor.execute( 'toggleTableCaption' );
+     * ```
+     *
+     * @param options Options for the executed command.
+     * @param options.focusCaptionOnShow When true and the caption shows up, the selection will be moved into it straight away.
+     * @fires execute
+     */
+    execute({ focusCaptionOnShow = false } = {}) {
+        this.editor.model.change(writer => {
+            if (this.value) {
+                this._hideTableCaption(writer);
+            }
+            else {
+                this._showTableCaption(writer, focusCaptionOnShow);
+            }
+        });
+    }
+    /**
+     * Shows the table caption. Also:
+     *
+     * * it attempts to restore the caption content from the `TableCaptionEditing` caption registry,
+     * * it moves the selection to the caption right away, it the `focusCaptionOnShow` option was set.
+     *
+     * @param focusCaptionOnShow Default focus behavior when showing the caption.
+     */
+    _showTableCaption(writer, focusCaptionOnShow) {
+        const model = this.editor.model;
+        const tableElement = getSelectionAffectedTable(model.document.selection);
+        const tableCaptionEditing = this.editor.plugins.get('TableCaptionEditing');
+        const savedCaptionElement = tableCaptionEditing._getSavedCaption(tableElement);
+        // Try restoring the caption from the TableCaptionEditing plugin storage.
+        const newCaptionElement = savedCaptionElement || writer.createElement('caption');
+        model.insertContent(newCaptionElement, tableElement, 'end');
+        if (focusCaptionOnShow) {
+            writer.setSelection(newCaptionElement, 'in');
+        }
+    }
+    /**
+     * Hides the caption of a selected table (or an table caption the selection is anchored to).
+     *
+     * The content of the caption is stored in the `TableCaptionEditing` caption registry to make this
+     * a reversible action.
+     */
+    _hideTableCaption(writer) {
+        const model = this.editor.model;
+        const tableElement = getSelectionAffectedTable(model.document.selection);
+        const tableCaptionEditing = this.editor.plugins.get('TableCaptionEditing');
+        const captionElement = getCaptionFromTableModelElement(tableElement);
+        // Store the caption content so it can be restored quickly if the user changes their mind.
+        tableCaptionEditing._saveCaption(tableElement, captionElement);
+        model.deleteContent(writer.createSelection(captionElement, 'on'));
+    }
+}

package/src/tablecaption/utils.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/tablecaption/utils
+ */
+import type { DocumentFragment, DocumentSelection, Element, ViewElement } from 'ckeditor5/src/engine.js';
+/**
+ * Checks if the provided model element is a `table`.
+ *
+ * @param modelElement Element to check if it is a table.
+ */
+export declare function isTable(modelElement: Element | DocumentFragment | null): boolean;
+/**
+ * Returns the caption model element from a given table element. Returns `null` if no caption is found.
+ *
+ * @param tableModelElement Table element in which we will try to find a caption element.
+ */
+export declare function getCaptionFromTableModelElement(tableModelElement: Element): Element | null;
+/**
+ * Returns the caption model element for a model selection. Returns `null` if the selection has no caption element ancestor.
+ *
+ * @param selection The selection checked for caption presence.
+ */
+export declare function getCaptionFromModelSelection(selection: DocumentSelection): Element | null;
+/**
+ * {@link module:engine/view/matcher~Matcher} pattern. Checks if a given element is a caption.
+ *
+ * There are two possible forms of the valid caption:
+ *  - A `<figcaption>` element inside a `<figure class="table">` element.
+ *  - A `<caption>` inside a <table>.
+ *
+ * @returns Returns the object accepted by {@link module:engine/view/matcher~Matcher} or `null` if the element cannot be matched.
+ */
+export declare function matchTableCaptionViewElement(element: ViewElement): {
+    name: true;
+} | null;

package/src/tablecaption/utils.js

@@ -0,0 +1,57 @@
+/**
+ * @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 { getSelectionAffectedTable } from '../utils/common.js';
+/**
+ * Checks if the provided model element is a `table`.
+ *
+ * @param modelElement Element to check if it is a table.
+ */
+export function isTable(modelElement) {
+    return !!modelElement && modelElement.is('element', 'table');
+}
+/**
+ * Returns the caption model element from a given table element. Returns `null` if no caption is found.
+ *
+ * @param tableModelElement Table element in which we will try to find a caption element.
+ */
+export function getCaptionFromTableModelElement(tableModelElement) {
+    for (const node of tableModelElement.getChildren()) {
+        if (node.is('element', 'caption')) {
+            return node;
+        }
+    }
+    return null;
+}
+/**
+ * Returns the caption model element for a model selection. Returns `null` if the selection has no caption element ancestor.
+ *
+ * @param selection The selection checked for caption presence.
+ */
+export function getCaptionFromModelSelection(selection) {
+    const tableElement = getSelectionAffectedTable(selection);
+    if (!tableElement) {
+        return null;
+    }
+    return getCaptionFromTableModelElement(tableElement);
+}
+/**
+ * {@link module:engine/view/matcher~Matcher} pattern. Checks if a given element is a caption.
+ *
+ * There are two possible forms of the valid caption:
+ *  - A `<figcaption>` element inside a `<figure class="table">` element.
+ *  - A `<caption>` inside a <table>.
+ *
+ * @returns Returns the object accepted by {@link module:engine/view/matcher~Matcher} or `null` if the element cannot be matched.
+ */
+export function matchTableCaptionViewElement(element) {
+    const parent = element.parent;
+    if (element.name == 'figcaption' && parent && parent.is('element', 'figure') && parent.hasClass('table')) {
+        return { name: true };
+    }
+    if (element.name == 'caption' && parent && parent.is('element', 'table')) {
+        return { name: true };
+    }
+    return null;
+}

package/src/tablecaption.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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/tablecaption
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import TableCaptionEditing from './tablecaption/tablecaptionediting.js';
+import TableCaptionUI from './tablecaption/tablecaptionui.js';
+import '../theme/tablecaption.css';
+/**
+ * The table caption plugin.
+ */
+export default class TableCaption extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TableCaption";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof TableCaptionEditing, typeof TableCaptionUI];
+}

package/src/tablecaption.js

@@ -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
+ */
+/**
+ * @module table/tablecaption
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import TableCaptionEditing from './tablecaption/tablecaptionediting.js';
+import TableCaptionUI from './tablecaption/tablecaptionui.js';
+import '../theme/tablecaption.css';
+/**
+ * The table caption plugin.
+ */
+export default class TableCaption extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'TableCaption';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [TableCaptionEditing, TableCaptionUI];
+    }
+}

package/src/tablecellproperties/commands/tablecellbackgroundcolorcommand.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/tablecellproperties/commands/tablecellbackgroundcolorcommand
+ */
+import type { Editor } from 'ckeditor5/src/core.js';
+import TableCellPropertyCommand from './tablecellpropertycommand.js';
+/**
+ * The table cell background color command.
+ *
+ * The command is registered by the {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing} as
+ * the `'tableCellBackgroundColor'` editor command.
+ *
+ * To change the background color of selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableCellBackgroundColor', {
+ *   value: '#f00'
+ * } );
+ * ```
+ */
+export default class TableCellBackgroundColorCommand extends TableCellPropertyCommand {
+    /**
+     * Creates a new `TableCellBackgroundColorCommand` 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/src/tablecellproperties/commands/tablecellbackgroundcolorcommand.js

@@ -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
+ */
+import TableCellPropertyCommand from './tablecellpropertycommand.js';
+/**
+ * The table cell background color command.
+ *
+ * The command is registered by the {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing} as
+ * the `'tableCellBackgroundColor'` editor command.
+ *
+ * To change the background color of selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableCellBackgroundColor', {
+ *   value: '#f00'
+ * } );
+ * ```
+ */
+export default class TableCellBackgroundColorCommand extends TableCellPropertyCommand {
+    /**
+     * Creates a new `TableCellBackgroundColorCommand` instance.
+     *
+     * @param editor An editor in which this command will be used.
+     * @param defaultValue The default value of the attribute.
+     */
+    constructor(editor, defaultValue) {
+        super(editor, 'tableCellBackgroundColor', defaultValue);
+    }
+}

package/src/tablecellproperties/commands/tablecellbordercolorcommand.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/tablecellproperties/commands/tablecellbordercolorcommand
+ */
+import type { Element } from 'ckeditor5/src/engine.js';
+import type { Editor } from 'ckeditor5/src/core.js';
+import TableCellPropertyCommand from './tablecellpropertycommand.js';
+/**
+ * The table cell border color command.
+ *
+ * The command is registered by the {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing} as
+ * the `'tableCellBorderColor'` editor command.
+ *
+ * To change the border color of selected cells, execute the command:
+ *
+ * ```ts
+ * editor.execute( 'tableCellBorderColor', {
+ *   value: '#f00'
+ * } );
+ * ```
+ */
+export default class TableCellBorderColorCommand extends TableCellPropertyCommand {
+    /**
+     * Creates a new `TableCellBorderColorCommand` 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 _getAttribute(tableCell: Element): unknown;
+}