@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/button/switchbuttonview.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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 ui/button/switchbuttonview
+ */
+import View from '../view.js';
+import ButtonView from './buttonview.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/button/switchbutton.css';
+/**
+ * The switch button view class.
+ *
+ * ```ts
+ * const view = new SwitchButtonView();
+ *
+ * view.set( {
+ * 	withText: true,
+ * 	label: 'Switch me!'
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ */
+export default class SwitchButtonView extends ButtonView {
+    /**
+     * The toggle switch of the button.
+     */
+    readonly toggleSwitchView: View;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Creates a toggle child view.
+     */
+    private _createToggleView;
+}

package/src/button/switchbuttonview.js

@@ -0,0 +1,75 @@
+/**
+ * @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 ui/button/switchbuttonview
+ */
+import View from '../view.js';
+import ButtonView from './buttonview.js';
+import '../../theme/components/button/switchbutton.css';
+/**
+ * The switch button view class.
+ *
+ * ```ts
+ * const view = new SwitchButtonView();
+ *
+ * view.set( {
+ * 	withText: true,
+ * 	label: 'Switch me!'
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ */
+export default class SwitchButtonView extends ButtonView {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        this.isToggleable = true;
+        this.toggleSwitchView = this._createToggleView();
+        this.extendTemplate({
+            attributes: {
+                class: 'ck-switchbutton'
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.children.add(this.toggleSwitchView);
+    }
+    /**
+     * Creates a toggle child view.
+     */
+    _createToggleView() {
+        const toggleSwitchView = new View();
+        toggleSwitchView.setTemplate({
+            tag: 'span',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-button__toggle'
+                ]
+            },
+            children: [
+                {
+                    tag: 'span',
+                    attributes: {
+                        class: [
+                            'ck',
+                            'ck-button__toggle__inner'
+                        ]
+                    }
+                }
+            ]
+        });
+        return toggleSwitchView;
+    }
+}

package/src/collapsible/collapsibleview.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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 ui/collapsible/collapsibleview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import View from '../view.js';
+import ButtonView from '../button/buttonview.js';
+import type ViewCollection from '../viewcollection.js';
+import type { FocusableView } from '../focuscycler.js';
+import '../../theme/components/collapsible/collapsible.css';
+/**
+ * A collapsible UI component. Consists of a labeled button and a container which can be collapsed
+ * by clicking the button. The collapsible container can be a host to other UI views.
+ *
+ * @internal
+ */
+export default class CollapsibleView extends View {
+    /**
+     * `true` when the container with {@link #children} is collapsed. `false` otherwise.
+     *
+     * @observable
+     */
+    isCollapsed: boolean;
+    /**
+     * The text label of the {@link #buttonView}.
+     *
+     * @observable
+     * @default 'Show more'
+     */
+    label: string;
+    /**
+     * The ID of the label inside the {@link #buttonView} that describes the collapsible
+     * container for assistive technologies. Set after the button was {@link #render rendered}.
+     *
+     * @internal
+     * @readonly
+     * @observable
+     */
+    _collapsibleAriaLabelUid: string | undefined;
+    /**
+     * The main button that, when clicked, collapses or expands the container with {@link #children}.
+     */
+    readonly buttonView: ButtonView;
+    /**
+     * A collection of the child views that can be collapsed by clicking the {@link #buttonView}.
+     */
+    readonly children: ViewCollection<FocusableView>;
+    /**
+     * Creates an instance of the collapsible view.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param childViews An optional array of initial child views to be inserted into the collapsible.
+     */
+    constructor(locale: Locale, childViews?: Array<FocusableView>);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the first focusable.
+     */
+    focus(): void;
+    /**
+     * Creates the main {@link #buttonView} of the collapsible.
+     */
+    private _createButtonView;
+}

package/src/collapsible/collapsibleview.js

@@ -0,0 +1,95 @@
+/**
+ * @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 View from '../view.js';
+import ButtonView from '../button/buttonview.js';
+import dropdownArrowIcon from '../../theme/icons/dropdown-arrow.svg';
+import '../../theme/components/collapsible/collapsible.css';
+/**
+ * A collapsible UI component. Consists of a labeled button and a container which can be collapsed
+ * by clicking the button. The collapsible container can be a host to other UI views.
+ *
+ * @internal
+ */
+export default class CollapsibleView extends View {
+    /**
+     * Creates an instance of the collapsible view.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param childViews An optional array of initial child views to be inserted into the collapsible.
+     */
+    constructor(locale, childViews) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set('isCollapsed', false);
+        this.set('label', '');
+        this.buttonView = this._createButtonView();
+        this.children = this.createCollection();
+        this.set('_collapsibleAriaLabelUid', undefined);
+        if (childViews) {
+            this.children.addMany(childViews);
+        }
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-collapsible',
+                    bind.if('isCollapsed', 'ck-collapsible_collapsed')
+                ]
+            },
+            children: [
+                this.buttonView,
+                {
+                    tag: 'div',
+                    attributes: {
+                        class: [
+                            'ck',
+                            'ck-collapsible__children'
+                        ],
+                        role: 'region',
+                        hidden: bind.if('isCollapsed', 'hidden'),
+                        'aria-labelledby': bind.to('_collapsibleAriaLabelUid')
+                    },
+                    children: this.children
+                }
+            ]
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this._collapsibleAriaLabelUid = this.buttonView.labelView.element.id;
+    }
+    /**
+     * Focuses the first focusable.
+     */
+    focus() {
+        this.buttonView.focus();
+    }
+    /**
+     * Creates the main {@link #buttonView} of the collapsible.
+     */
+    _createButtonView() {
+        const buttonView = new ButtonView(this.locale);
+        const bind = buttonView.bindTemplate;
+        buttonView.set({
+            withText: true,
+            icon: dropdownArrowIcon
+        });
+        buttonView.extendTemplate({
+            attributes: {
+                'aria-expanded': bind.to('isOn', value => String(value))
+            }
+        });
+        buttonView.bind('label').to(this);
+        buttonView.bind('isOn').to(this, 'isCollapsed', isCollapsed => !isCollapsed);
+        buttonView.on('execute', () => {
+            this.isCollapsed = !this.isCollapsed;
+        });
+        return buttonView;
+    }
+}

package/src/colorgrid/colorgridview.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @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 ui/colorgrid/colorgridview
+ */
+import View from '../view.js';
+import ColorTileView from './colortileview.js';
+import type DropdownPanelFocusable from '../dropdown/dropdownpanelfocusable.js';
+import type ViewCollection from '../viewcollection.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/colorgrid/colorgrid.css';
+/**
+ * A grid of {@link module:ui/colorgrid/colortileview~ColorTileView color tiles}.
+ */
+export default class ColorGridView extends View implements DropdownPanelFocusable {
+    /**
+     * A number of columns for the tiles grid.
+     */
+    readonly columns: number;
+    /**
+     * Collection of the child tile views.
+     */
+    readonly items: ViewCollection<ColorTileView>;
+    /**
+     * Tracks information about DOM focus in the grid.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * The color of the currently selected color tile in {@link #items}.
+     *
+     * @observable
+     */
+    selectedColor: string | undefined | null;
+    /**
+     * Creates an instance of a color grid containing {@link module:ui/colorgrid/colortileview~ColorTileView tiles}.
+     *
+     * @fires execute
+     * @param locale The localization services instance.
+     * @param options Component configuration
+     * @param options.colorDefinitions Array with definitions
+     * required to create the {@link module:ui/colorgrid/colortileview~ColorTileView tiles}.
+     * @param options.columns A number of columns to display the tiles.
+     */
+    constructor(locale?: Locale, options?: {
+        colorDefinitions?: Array<ColorDefinition>;
+        columns?: number;
+    });
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focus(): void;
+    /**
+     * Focuses the last focusable in {@link #items}.
+     */
+    focusLast(): void;
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}
+/**
+ * A color definition used to create a {@link module:ui/colorgrid/colortileview~ColorTileView}.
+ *
+ * ```json
+ * {
+ * 	color: 'hsl(0, 0%, 75%)',
+ * 	label: 'Light Grey',
+ * 	options: {
+ * 		hasBorder: true
+ * 	}
+ * }
+ * ```
+ */
+export interface ColorDefinition {
+    /**
+     * String representing a color.
+     * It is used as value of background-color style in {@link module:ui/colorgrid/colortileview~ColorTileView}.
+     */
+    color: string;
+    /**
+     * String used as label for {@link module:ui/colorgrid/colortileview~ColorTileView}.
+     */
+    label: string;
+    /**
+     * Additional options passed to create a {@link module:ui/colorgrid/colortileview~ColorTileView}.
+     */
+    options: {
+        /**
+         * A flag that indicates if special a CSS class should be added
+         * to {@link module:ui/colorgrid/colortileview~ColorTileView}, which renders a border around it.
+         */
+        hasBorder: boolean;
+    };
+}
+/**
+ * Fired when the `ColorTileView` for the picked item is executed.
+ *
+ * @eventName ~ColorGridView#execute
+ * @param data Additional information about the event.
+*/
+export type ColorGridViewExecuteEvent = {
+    name: 'execute';
+    args: [data: ColorGridViewExecuteEventData];
+};
+/**
+ * The data of {@link ~ColorGridViewExecuteEvent execute event}.
+ */
+export interface ColorGridViewExecuteEventData {
+    /**
+     * The value of the selected color ({@link module:ui/colorgrid/colorgridview~ColorDefinition#color `color.color`}).
+     */
+    value: string;
+    /**
+     * The `hasBorder` property of the selected color
+     * ({@link module:ui/colorgrid/colorgridview~ColorDefinition#options `color.options.hasBorder`}).
+     */
+    hasBorder: boolean;
+    /**
+     * The label of the selected color ({@link module:ui/colorgrid/colorgridview~ColorDefinition#label `color.label`})
+     */
+    label: string;
+}

package/src/colorgrid/colorgridview.js

@@ -0,0 +1,124 @@
+/**
+ * @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 ui/colorgrid/colorgridview
+ */
+import View from '../view.js';
+import ColorTileView from './colortileview.js';
+import addKeyboardHandlingForGrid from '../bindings/addkeyboardhandlingforgrid.js';
+import { FocusTracker, KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/colorgrid/colorgrid.css';
+/**
+ * A grid of {@link module:ui/colorgrid/colortileview~ColorTileView color tiles}.
+ */
+export default class ColorGridView extends View {
+    /**
+     * Creates an instance of a color grid containing {@link module:ui/colorgrid/colortileview~ColorTileView tiles}.
+     *
+     * @fires execute
+     * @param locale The localization services instance.
+     * @param options Component configuration
+     * @param options.colorDefinitions Array with definitions
+     * required to create the {@link module:ui/colorgrid/colortileview~ColorTileView tiles}.
+     * @param options.columns A number of columns to display the tiles.
+     */
+    constructor(locale, options) {
+        super(locale);
+        const colorDefinitions = options && options.colorDefinitions ? options.colorDefinitions : [];
+        this.columns = options && options.columns ? options.columns : 5;
+        const viewStyleAttribute = {
+            gridTemplateColumns: `repeat( ${this.columns}, 1fr)`
+        };
+        this.set('selectedColor', undefined);
+        this.items = this.createCollection();
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        this.items.on('add', (evt, colorTile) => {
+            colorTile.isOn = colorTile.color === this.selectedColor;
+        });
+        colorDefinitions.forEach(color => {
+            const colorTile = new ColorTileView();
+            colorTile.set({
+                color: color.color,
+                label: color.label,
+                tooltip: true,
+                hasBorder: color.options.hasBorder
+            });
+            colorTile.on('execute', () => {
+                this.fire('execute', {
+                    value: color.color,
+                    hasBorder: color.options.hasBorder,
+                    label: color.label
+                });
+            });
+            this.items.add(colorTile);
+        });
+        this.setTemplate({
+            tag: 'div',
+            children: this.items,
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-color-grid'
+                ],
+                style: viewStyleAttribute
+            }
+        });
+        this.on('change:selectedColor', (evt, name, selectedColor) => {
+            for (const item of this.items) {
+                item.isOn = item.color === selectedColor;
+            }
+        });
+    }
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focus() {
+        if (this.items.length) {
+            this.items.first.focus();
+        }
+    }
+    /**
+     * Focuses the last focusable in {@link #items}.
+     */
+    focusLast() {
+        if (this.items.length) {
+            this.items.last.focus();
+        }
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        // Items added before rendering should be known to the #focusTracker.
+        for (const item of this.items) {
+            this.focusTracker.add(item.element);
+        }
+        this.items.on('add', (evt, item) => {
+            this.focusTracker.add(item.element);
+        });
+        this.items.on('remove', (evt, item) => {
+            this.focusTracker.remove(item.element);
+        });
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+        addKeyboardHandlingForGrid({
+            keystrokeHandler: this.keystrokes,
+            focusTracker: this.focusTracker,
+            gridItems: this.items,
+            numberOfColumns: this.columns,
+            uiLanguageDirection: this.locale && this.locale.uiLanguageDirection
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+}

package/src/colorgrid/colortileview.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 ui/colorgrid/colortileview
+ */
+import ButtonView from '../button/buttonview.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * This class represents a single color tile in the {@link module:ui/colorgrid/colorgridview~ColorGridView}.
+ */
+export default class ColorTileView extends ButtonView {
+    /**
+     * String representing a color shown as tile's background.
+     */
+    color: string | undefined;
+    /**
+     * A flag that toggles a special CSS class responsible for displaying
+     * a border around the button.
+     */
+    hasBorder: boolean;
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+}

package/src/colorgrid/colortileview.js

@@ -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
+ */
+/**
+ * @module ui/colorgrid/colortileview
+ */
+import ButtonView from '../button/buttonview.js';
+import { env } from '@ckeditor/ckeditor5-utils';
+import checkIcon from '../../theme/icons/color-tile-check.svg';
+/**
+ * This class represents a single color tile in the {@link module:ui/colorgrid/colorgridview~ColorGridView}.
+ */
+export default class ColorTileView extends ButtonView {
+    constructor(locale) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set('color', undefined);
+        this.set('hasBorder', false);
+        this.icon = checkIcon;
+        this.extendTemplate({
+            attributes: {
+                style: {
+                    // https://github.com/ckeditor/ckeditor5/issues/14907
+                    backgroundColor: bind.to('color', color => env.isMediaForcedColors ? null : color)
+                },
+                class: [
+                    'ck',
+                    'ck-color-grid__tile',
+                    bind.if('hasBorder', 'ck-color-selector__color-tile_bordered')
+                ]
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.iconView.fillColor = 'hsl(0, 0%, 100%)';
+    }
+}

package/src/colorgrid/utils.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @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 ui/colorgrid/utils
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+export type ColorOption = string | {
+    color: string;
+    label?: string;
+    hasBorder?: boolean;
+};
+export interface NormalizedColorOption {
+    model: string;
+    label: string;
+    hasBorder: boolean;
+    view: {
+        name: string;
+        styles: {
+            color: string;
+        };
+    };
+}
+/**
+ * Returns color configuration options as defined in `editor.config.(fontColor|fontBackgroundColor).colors` or
+ * `editor.config.table.(tableProperties|tableCellProperties).(background|border).colors
+ * but processed to account for editor localization in the correct language.
+ *
+ * Note: The reason behind this method is that there is no way to use {@link module:utils/locale~Locale#t}
+ * when the user configuration is defined because the editor does not exist yet.
+ *
+ * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+ */
+export declare function getLocalizedColorOptions(locale: Locale, options: Array<NormalizedColorOption>): Array<NormalizedColorOption>;
+/**
+ * Creates a unified color definition object from color configuration options.
+ * The object contains the information necessary to both render the UI and initialize the conversion.
+ */
+export declare function normalizeColorOptions(options: Array<ColorOption>): Array<NormalizedColorOption>;
+/**
+ * Creates a normalized color definition from the user-defined configuration.
+ * The "normalization" means it will create full
+ * {@link module:ui/colorgrid/colorgridview~ColorDefinition `ColorDefinition-like`}
+ * object for string values, and add a `view` property, for each definition.
+ */
+export declare function normalizeSingleColorDefinition(color: ColorOption): NormalizedColorOption;