@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/colorselector/colorselectorview.js

@@ -0,0 +1,257 @@
+/**
+ * @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/colorselector/colorselectorview
+ */
+import FocusCycler from '../focuscycler.js';
+import View from '../view.js';
+import ViewCollection from '../viewcollection.js';
+import { FocusTracker, KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
+import ColorGridsFragmentView from './colorgridsfragmentview.js';
+import ColorPickerFragmentView from './colorpickerfragmentview.js';
+import '../../theme/components/colorselector/colorselector.css';
+/**
+ * The configurable color selector view class. It allows users to select colors from a predefined set of colors as well as from
+ * a color picker.
+ *
+ * This meta-view is is made of two components (fragments):
+ *
+ * * {@link module:ui/colorselector/colorselectorview~ColorSelectorView#colorGridsFragmentView},
+ * * {@link module:ui/colorselector/colorselectorview~ColorSelectorView#colorPickerFragmentView}.
+ *
+ * ```ts
+ * const colorDefinitions = [
+ * 	{ color: '#000', label: 'Black', options: { hasBorder: false } },
+ * 	{ color: 'rgb(255, 255, 255)', label: 'White', options: { hasBorder: true } },
+ * 	{ color: 'red', label: 'Red', options: { hasBorder: false } }
+ * ];
+ *
+ * const selectorView = new ColorSelectorView( locale, {
+ * 	colors: colorDefinitions,
+ * 	columns: 5,
+ * 	removeButtonLabel: 'Remove color',
+ * 	documentColorsLabel: 'Document colors',
+ * 	documentColorsCount: 4,
+ * 	colorPickerViewConfig: {
+ * 		format: 'hsl'
+ * 	}
+ * } );
+ *
+ * selectorView.appendUI();
+ * selectorView.selectedColor = 'red';
+ * selectorView.updateSelectedColors();
+ *
+ * selectorView.on<ColorSelectorExecuteEvent>( 'execute', ( evt, data ) => {
+ * 	console.log( 'Color changed', data.value, data.source );
+ * } );
+ *
+ * selectorView.on<ColorSelectorColorPickerShowEvent>( 'colorPicker:show', ( evt ) => {
+ * 	console.log( 'Color picker showed up', evt );
+ * } );
+ *
+ * selectorView.on<ColorSelectorColorPickerCancelEvent>( 'colorPicker:cancel', ( evt ) => {
+ * 	console.log( 'Color picker cancel', evt );
+ * } );
+ *
+ * selectorView.render();
+ *
+ * document.body.appendChild( selectorView.element );
+ * ```
+ */
+export default class ColorSelectorView extends View {
+    /**
+     * Creates a view to be inserted as a child of {@link module:ui/dropdown/dropdownview~DropdownView}.
+     *
+     * @param locale The localization services instance.
+     * @param colors An array with definitions of colors to be displayed in the table.
+     * @param columns The number of columns in the color grid.
+     * @param removeButtonLabel The label of the button responsible for removing the color.
+     * @param colorPickerLabel The label of the button responsible for color picker appearing.
+     * @param documentColorsLabel The label for the section with the document colors.
+     * @param documentColorsCount The number of colors in the document colors section inside the color dropdown.
+     * @param colorPickerViewConfig The configuration of color picker feature. If set to `false`, the color picker will be hidden.
+     */
+    constructor(locale, { colors, columns, removeButtonLabel, documentColorsLabel, documentColorsCount, colorPickerLabel, colorPickerViewConfig }) {
+        super(locale);
+        this.items = this.createCollection();
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        this._focusables = new ViewCollection();
+        this._colorPickerViewConfig = colorPickerViewConfig;
+        this._focusCycler = new FocusCycler({
+            focusables: this._focusables,
+            focusTracker: this.focusTracker,
+            keystrokeHandler: this.keystrokes,
+            actions: {
+                // Navigate list items backwards using the <kbd>Shift</kbd> + <kbd>Tab</kbd> keystroke.
+                focusPrevious: 'shift + tab',
+                // Navigate list items forwards using the <kbd>Tab</kbd> key.
+                focusNext: 'tab'
+            }
+        });
+        this.colorGridsFragmentView = new ColorGridsFragmentView(locale, {
+            colors, columns, removeButtonLabel, documentColorsLabel, documentColorsCount, colorPickerLabel,
+            focusTracker: this.focusTracker,
+            focusables: this._focusables
+        });
+        this.colorPickerFragmentView = new ColorPickerFragmentView(locale, {
+            focusables: this._focusables,
+            focusTracker: this.focusTracker,
+            keystrokes: this.keystrokes,
+            colorPickerViewConfig
+        });
+        this.set('_isColorGridsFragmentVisible', true);
+        this.set('_isColorPickerFragmentVisible', false);
+        this.set('selectedColor', undefined);
+        this.colorGridsFragmentView.bind('isVisible').to(this, '_isColorGridsFragmentVisible');
+        this.colorPickerFragmentView.bind('isVisible').to(this, '_isColorPickerFragmentVisible');
+        /**
+         * This is kind of bindings. Unfortunately we could not use this.bind() method because the same property
+         * can not be bound twice. So this is work around how to bind 'selectedColor' property between components.
+         */
+        this.on('change:selectedColor', (evt, evtName, data) => {
+            this.colorGridsFragmentView.set('selectedColor', data);
+            this.colorPickerFragmentView.set('selectedColor', data);
+        });
+        this.colorGridsFragmentView.on('change:selectedColor', (evt, evtName, data) => {
+            this.set('selectedColor', data);
+        });
+        this.colorPickerFragmentView.on('change:selectedColor', (evt, evtName, data) => {
+            this.set('selectedColor', data);
+        });
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-color-selector'
+                ]
+            },
+            children: this.items
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Renders the internals of the component on demand:
+     * * {@link #colorPickerFragmentView},
+     * * {@link #colorGridsFragmentView}.
+     *
+     * It allows for deferring component initialization to improve the performance.
+     *
+     * See {@link #showColorPickerFragment}, {@link #showColorGridsFragment}.
+     */
+    appendUI() {
+        this._appendColorGridsFragment();
+        if (this._colorPickerViewConfig) {
+            this._appendColorPickerFragment();
+        }
+    }
+    /**
+     * Shows the {@link #colorPickerFragmentView} and hides the {@link #colorGridsFragmentView}.
+     *
+     * **Note**: It requires {@link #appendUI} to be called first.
+     *
+     * See {@link #showColorGridsFragment}, {@link ~ColorSelectorView#event:colorPicker:show}.
+     */
+    showColorPickerFragment() {
+        if (!this.colorPickerFragmentView.colorPickerView || this._isColorPickerFragmentVisible) {
+            return;
+        }
+        this._isColorPickerFragmentVisible = true;
+        this.colorPickerFragmentView.focus();
+        this.colorPickerFragmentView.resetValidationStatus();
+        this._isColorGridsFragmentVisible = false;
+    }
+    /**
+     * Shows the {@link #colorGridsFragmentView} and hides the {@link #colorPickerFragmentView}.
+     *
+     * See {@link #showColorPickerFragment}.
+     *
+     * **Note**: It requires {@link #appendUI} to be called first.
+     */
+    showColorGridsFragment() {
+        if (this._isColorGridsFragmentVisible) {
+            return;
+        }
+        this._isColorGridsFragmentVisible = true;
+        this.colorGridsFragmentView.focus();
+        this._isColorPickerFragmentVisible = false;
+    }
+    /**
+     * Focuses the first focusable element in {@link #items}.
+     */
+    focus() {
+        this._focusCycler.focusFirst();
+    }
+    /**
+     * Focuses the last focusable element in {@link #items}.
+     */
+    focusLast() {
+        this._focusCycler.focusLast();
+    }
+    /**
+     * Scans through the editor model and searches for text node attributes with the given `attributeName`.
+     * Found entries are set as document colors in {@link #colorGridsFragmentView}.
+     *
+     * All the previously stored document colors will be lost in the process.
+     *
+     * @param model The model used as a source to obtain the document colors.
+     * @param attributeName Determines the name of the related model's attribute for a given dropdown.
+     */
+    updateDocumentColors(model, attributeName) {
+        this.colorGridsFragmentView.updateDocumentColors(model, attributeName);
+    }
+    /**
+     * Refreshes the state of the selected color in one or both grids located in {@link #colorGridsFragmentView}.
+     *
+     * It guarantees that the selection will occur only in one of them.
+     */
+    updateSelectedColors() {
+        this.colorGridsFragmentView.updateSelectedColors();
+    }
+    /**
+     * Appends the view containing static and document color grid views.
+     */
+    _appendColorGridsFragment() {
+        if (this.items.length) {
+            return;
+        }
+        this.items.add(this.colorGridsFragmentView);
+        this.colorGridsFragmentView.delegate('execute').to(this);
+        this.colorGridsFragmentView.delegate('colorPicker:show').to(this);
+    }
+    /**
+     * Appends the view with the color picker.
+     */
+    _appendColorPickerFragment() {
+        if (this.items.length === 2) {
+            return;
+        }
+        this.items.add(this.colorPickerFragmentView);
+        if (this.colorGridsFragmentView.colorPickerButtonView) {
+            this.colorGridsFragmentView.colorPickerButtonView.on('execute', () => {
+                this.showColorPickerFragment();
+            });
+        }
+        this.colorGridsFragmentView.addColorPickerButton();
+        this.colorPickerFragmentView.delegate('execute').to(this);
+        this.colorPickerFragmentView.delegate('colorPicker:cancel').to(this);
+    }
+}

package/src/colorselector/documentcolorcollection.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/colorselector/documentcolorcollection
+ */
+import type { ColorDefinition } from '../colorgrid/colorgridview.js';
+import { Collection, type CollectionAddEvent, type CollectionRemoveEvent, type CollectionChangeEvent } from '@ckeditor/ckeditor5-utils';
+declare const DocumentColorCollection_base: import("@ckeditor/ckeditor5-utils").Mixed<{
+    new (options?: {
+        readonly idProperty?: string | undefined;
+    } | undefined): Collection<ColorDefinition>;
+    new (initialItems: Iterable<ColorDefinition>, options?: {
+        readonly idProperty?: string | undefined;
+    } | undefined): Collection<ColorDefinition>;
+}, import("@ckeditor/ckeditor5-utils").Observable>;
+/**
+ * A collection to store document colors. It enforces colors to be unique.
+ */
+export default class DocumentColorCollection extends /* #__PURE__ */ DocumentColorCollection_base {
+    /**
+     * Indicates whether the document color collection is empty.
+     *
+     * @observable
+     */
+    readonly isEmpty: boolean;
+    constructor(options?: any);
+    /**
+     * Adds a color to the document color collection.
+     *
+     * This method ensures that no color duplicates are inserted (compared using
+     * the color value of the {@link module:ui/colorgrid/colorgridview~ColorDefinition}).
+     *
+     * If the item does not have an ID, it will be automatically generated and set on the item.
+     *
+     * @param index The position of the item in the collection. The item is pushed to the collection when `index` is not specified.
+     * @fires add
+     * @fires change
+     */
+    add(item: ColorDefinition, index?: number): this;
+    /**
+     * Checks if an object with given colors is present in the document color collection.
+     */
+    hasColor(color: string): boolean;
+}
+/**
+ * Fired when the collection was changed due to adding or removing items.
+ *
+ * @eventName ~DocumentColorCollection#change
+ * @param data Changed items.
+ */
+export type DocumentColorCollectionChangeEvent = CollectionChangeEvent;
+/**
+ * Fired when an item is added to the collection.
+ *
+ * @eventName ~DocumentColorCollection#add
+ * @param item The added item.
+ * @param index An index where the addition occurred.
+ */
+export type DocumentColorCollectionAddEvent = CollectionAddEvent;
+/**
+ * Fired when an item is removed from the collection.
+ *
+ * @eventName ~DocumentColorCollection#remove
+ * @param item The removed item.
+ * @param index Index from which item was removed.
+ */
+export type DocumentColorCollectionRemoveEvent = CollectionRemoveEvent;
+export {};

package/src/colorselector/documentcolorcollection.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
+ */
+import { Collection, ObservableMixin } from '@ckeditor/ckeditor5-utils';
+/**
+ * A collection to store document colors. It enforces colors to be unique.
+ */
+export default class DocumentColorCollection extends /* #__PURE__ */ ObservableMixin((Collection)) {
+    constructor(options) {
+        super(options);
+        this.set('isEmpty', true);
+        this.on('change', () => {
+            this.set('isEmpty', this.length === 0);
+        });
+    }
+    /**
+     * Adds a color to the document color collection.
+     *
+     * This method ensures that no color duplicates are inserted (compared using
+     * the color value of the {@link module:ui/colorgrid/colorgridview~ColorDefinition}).
+     *
+     * If the item does not have an ID, it will be automatically generated and set on the item.
+     *
+     * @param index The position of the item in the collection. The item is pushed to the collection when `index` is not specified.
+     * @fires add
+     * @fires change
+     */
+    add(item, index) {
+        if (this.find(element => element.color === item.color)) {
+            // No duplicates are allowed.
+            return this;
+        }
+        return super.add(item, index);
+    }
+    /**
+     * Checks if an object with given colors is present in the document color collection.
+     */
+    hasColor(color) {
+        return !!this.find(item => item.color === color);
+    }
+}

package/src/componentfactory.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @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/componentfactory
+ */
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import type { Editor } from '@ckeditor/ckeditor5-core';
+import type View from './view.js';
+/**
+ * A helper class implementing the UI component ({@link module:ui/view~View view}) factory.
+ *
+ * It allows functions producing specific UI components to be registered under their unique names
+ * in the factory. A registered component can be then instantiated by providing its name.
+ * Note that the names are case insensitive.
+ *
+ * ```ts
+ * // The editor provides localization tools for the factory.
+ * const factory = new ComponentFactory( editor );
+ *
+ * factory.add( 'foo', locale => new FooView( locale ) );
+ * factory.add( 'bar', locale => new BarView( locale ) );
+ *
+ * // An instance of FooView.
+ * const fooInstance = factory.create( 'foo' );
+ *
+ * // Names are case insensitive so this is also allowed:
+ * const barInstance = factory.create( 'Bar' );
+ * ```
+ *
+ * The {@link module:core/editor/editor~Editor#locale editor locale} is passed to the factory
+ * function when {@link module:ui/componentfactory~ComponentFactory#create} is called.
+ */
+export default class ComponentFactory {
+    /**
+     * The editor instance that the factory belongs to.
+     */
+    readonly editor: Editor;
+    /**
+     * Registered component factories.
+     */
+    private readonly _components;
+    /**
+     * Creates an instance of the factory.
+     *
+     * @param editor The editor instance.
+     */
+    constructor(editor: Editor);
+    /**
+     * Returns an iterator of registered component names. Names are returned in lower case.
+     */
+    names(): IterableIterator<string>;
+    /**
+     * Registers a component factory function that will be used by the
+     * {@link #create create} method and called with the
+     * {@link module:core/editor/editor~Editor#locale editor locale} as an argument,
+     * allowing localization of the {@link module:ui/view~View view}.
+     *
+     * @param name The name of the component.
+     * @param callback The callback that returns the component.
+     */
+    add(name: string, callback: (locale: Locale) => View): void;
+    /**
+     * Creates an instance of a component registered in the factory under a specific name.
+     *
+     * When called, the {@link module:core/editor/editor~Editor#locale editor locale} is passed to
+     * the previously {@link #add added} factory function, allowing localization of the
+     * {@link module:ui/view~View view}.
+     *
+     * @param name The name of the component.
+     * @returns The instantiated component view.
+     */
+    create(name: string): View;
+    /**
+     * Checks if a component of a given name is registered in the factory.
+     *
+     * @param name The name of the component.
+     */
+    has(name: string): boolean;
+}

package/src/componentfactory.js

@@ -0,0 +1,104 @@
+/**
+ * @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/componentfactory
+ */
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
+/**
+ * A helper class implementing the UI component ({@link module:ui/view~View view}) factory.
+ *
+ * It allows functions producing specific UI components to be registered under their unique names
+ * in the factory. A registered component can be then instantiated by providing its name.
+ * Note that the names are case insensitive.
+ *
+ * ```ts
+ * // The editor provides localization tools for the factory.
+ * const factory = new ComponentFactory( editor );
+ *
+ * factory.add( 'foo', locale => new FooView( locale ) );
+ * factory.add( 'bar', locale => new BarView( locale ) );
+ *
+ * // An instance of FooView.
+ * const fooInstance = factory.create( 'foo' );
+ *
+ * // Names are case insensitive so this is also allowed:
+ * const barInstance = factory.create( 'Bar' );
+ * ```
+ *
+ * The {@link module:core/editor/editor~Editor#locale editor locale} is passed to the factory
+ * function when {@link module:ui/componentfactory~ComponentFactory#create} is called.
+ */
+export default class ComponentFactory {
+    /**
+     * Creates an instance of the factory.
+     *
+     * @param editor The editor instance.
+     */
+    constructor(editor) {
+        /**
+         * Registered component factories.
+         */
+        this._components = new Map();
+        this.editor = editor;
+    }
+    /**
+     * Returns an iterator of registered component names. Names are returned in lower case.
+     */
+    *names() {
+        for (const value of this._components.values()) {
+            yield value.originalName;
+        }
+    }
+    /**
+     * Registers a component factory function that will be used by the
+     * {@link #create create} method and called with the
+     * {@link module:core/editor/editor~Editor#locale editor locale} as an argument,
+     * allowing localization of the {@link module:ui/view~View view}.
+     *
+     * @param name The name of the component.
+     * @param callback The callback that returns the component.
+     */
+    add(name, callback) {
+        this._components.set(getNormalized(name), { callback, originalName: name });
+    }
+    /**
+     * Creates an instance of a component registered in the factory under a specific name.
+     *
+     * When called, the {@link module:core/editor/editor~Editor#locale editor locale} is passed to
+     * the previously {@link #add added} factory function, allowing localization of the
+     * {@link module:ui/view~View view}.
+     *
+     * @param name The name of the component.
+     * @returns The instantiated component view.
+     */
+    create(name) {
+        if (!this.has(name)) {
+            /**
+             * The required component is not registered in the component factory. Please make sure
+             * the provided name is correct and the component has been correctly
+             * {@link module:ui/componentfactory~ComponentFactory#add added} to the factory.
+             *
+             * @error componentfactory-item-missing
+             * @param name The name of the missing component.
+             */
+            throw new CKEditorError('componentfactory-item-missing', this, { name });
+        }
+        return this._components.get(getNormalized(name)).callback(this.editor.locale);
+    }
+    /**
+     * Checks if a component of a given name is registered in the factory.
+     *
+     * @param name The name of the component.
+     */
+    has(name) {
+        return this._components.has(getNormalized(name));
+    }
+}
+/**
+ * Ensures that the component name used as the key in the internal map is in lower case.
+ */
+function getNormalized(name) {
+    return String(name).toLowerCase();
+}