@ckeditor/ckeditor5-ui 36.0.1 → 37.0.0-alpha.0

package/src/colorgrid/colorgridview.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @license Copyright (c) 2003-2023, 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/colorgrid
+ */
+import View from '../view';
+import ColorTileView from './colortileview';
+import type DropdownPanelFocusable from '../dropdown/dropdownpanelfocusable';
+import type ViewCollection from '../viewcollection';
+import { FocusTracker, KeystrokeHandler, type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/colorgrid/colorgrid.css';
+/**
+ * A grid of {@link module:ui/colorgrid/colortile~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/colortile~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/colortile~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/colortile~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/colortile~ColorTileView}.
+     */
+    color: string;
+    /**
+     * String used as label for {@link module:ui/colorgrid/colortile~ColorTileView}.
+     */
+    label: string;
+    /**
+     * Additional options passed to create a {@link module:ui/colorgrid/colortile~ColorTileView}.
+     */
+    options: {
+        /**
+         * A flag that indicates if special a CSS class should be added
+         * to {@link module:ui/colorgrid/colortile~ColorTileView}, which renders a border around it.
+         */
+        hasBorder: boolean;
+    };
+}
+/**
+ * Fired when the `ColorTileView` for the picked item is executed.
+ *
+ * @eventName 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/colorgrid~ColorDefinition#color `color.color`}).
+     */
+    value: string;
+    /**
+     * The `hasBorder` property of the selected color
+     * ({@link module:ui/colorgrid/colorgrid~ColorDefinition#options `color.options.hasBorder`}).
+     */
+    hasBorder: boolean;
+    /**
+     * The label of the selected color ({@link module:ui/colorgrid/colorgrid~ColorDefinition#label `color.label`})
+     */
+    label: string;
+}

package/src/colorgrid/colorgridview.js

@@ -7,65 +7,33 @@
  */
 import View from '../view';
 import ColorTileView from './colortileview';
-import KeystrokeHandler from '@ckeditor/ckeditor5-utils/src/keystrokehandler';
 import addKeyboardHandlingForGrid from '../bindings/addkeyboardhandlingforgrid';
-import { FocusTracker } from '@ckeditor/ckeditor5-utils';
+import { FocusTracker, KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/colorgrid/colorgrid.css';
 /**
  * A grid of {@link module:ui/colorgrid/colortile~ColorTileView color tiles}.
- *
- * @extends module:ui/view~View
  */
 export default class ColorGridView extends View {
     /**
      * Creates an instance of a color grid containing {@link module:ui/colorgrid/colortile~ColorTileView tiles}.
      *
-     * @param {module:utils/locale~Locale} [locale] The localization services instance.
-     * @param {Object} options Component configuration
-     * @param {Array.<module:ui/colorgrid/colorgrid~ColorDefinition>} [options.colorDefinitions] Array with definitions
+     * @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/colortile~ColorTileView tiles}.
-     * @param {Number} [options.columns=5] A number of columns to display the tiles.
+     * @param options.columns A number of columns to display the tiles.
      */
     constructor(locale, options) {
         super(locale);
-        const colorDefinitions = options && options.colorDefinitions || [];
-        /**
-         * A number of columns for the tiles grid.
-         *
-         * @readonly
-         * @member {Number}
-         */
-        this.columns = options && options.columns ? options.columns : 5;
+        const colorDefinitions = options?.colorDefinitions ?? [];
+        this.columns = options?.columns ?? 5;
         const viewStyleAttribute = {
             gridTemplateColumns: `repeat( ${this.columns}, 1fr)`
         };
-        /**
-         * The color of the currently selected color tile in {@link #items}.
-         *
-         * @observable
-         * @type {String}
-         */
         this.set('selectedColor', undefined);
-        /**
-         * Collection of the child tile views.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.items = this.createCollection();
-        /**
-         * Tracks information about DOM focus in the grid.
-         *
-         * @readonly
-         * @member {module:utils/focustracker~FocusTracker}
-         */
         this.focusTracker = new FocusTracker();
-        /**
-         * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
-         *
-         * @readonly
-         * @member {module:utils/keystrokehandler~KeystrokeHandler}
-         */
         this.keystrokes = new KeystrokeHandler();
         this.items.on('add', (evt, colorTile) => {
             colorTile.isOn = colorTile.color === this.selectedColor;

package/src/colorgrid/colortileview.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license Copyright (c) 2003-2023, 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/colortile
+ */
+import ButtonView from '../button/buttonview';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * This class represents a single color tile in the {@link module:ui/colorgrid/colorgrid~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

@@ -9,25 +9,12 @@ import ButtonView from '../button/buttonview';
 import checkIcon from '../../theme/icons/color-tile-check.svg';
 /**
  * This class represents a single color tile in the {@link module:ui/colorgrid/colorgrid~ColorGridView}.
- *
- * @extends module:ui/button/buttonview~ButtonView
  */
 export default class ColorTileView extends ButtonView {
     constructor(locale) {
         super(locale);
         const bind = this.bindTemplate;
-        /**
-         * String representing a color shown as tile's background.
-         *
-         * @type {String}
-         */
         this.set('color', undefined);
-        /**
-         * A flag that toggles a special CSS class responsible for displaying
-         * a border around the button.
-         *
-         * @type {Boolean}
-         */
         this.set('hasBorder', false);
         this.icon = checkIcon;
         this.extendTemplate({

package/src/colorgrid/utils.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license Copyright (c) 2003-2023, 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/colorgrid~ColorDefinition `ColorDefinition-like`}
+ * object for string values, and add a `view` property, for each definition.
+ */
+export declare function normalizeSingleColorDefinition(color: ColorOption): NormalizedColorOption;

package/src/colorgrid/utils.js

@@ -10,9 +10,7 @@
  * 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 {module:utils/locale~Locale} locale The {@link module:core/editor/editor~Editor#locale} instance.
- * @param {Array.<module:ui/colorgrid/colorgrid~ColorDefinition>} options
- * @returns {Array.<module:ui/colorgrid/colorgrid~ColorDefinition>}.
+ * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
  */
 export function getLocalizedColorOptions(locale, options) {
     const t = locale.t;
@@ -44,22 +42,18 @@ export function getLocalizedColorOptions(locale, options) {
 /**
  * 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.
- *
- * @param {module:ui/colorgrid/colorgrid~ColorDefinition} options
- * @returns {Array.<module:ui/colorgrid/colorgrid~ColorDefinition>}
  */
 export function normalizeColorOptions(options) {
     return options
         .map(normalizeSingleColorDefinition)
         .filter(option => !!option);
 }
-// Creates a normalized color definition from the user-defined configuration.
-// The "normalization" means it will create full
-// {@link module:ui/colorgrid/colorgrid~ColorDefinition `ColorDefinition-like`}
-// object for string values, and add a `view` property, for each definition.
-//
-// @param {String|module:ui/colorgrid/colorgrid~ColorDefinition}
-// @returns {module:ui/colorgrid/colorgrid~ColorDefinition}
+/**
+ * Creates a normalized color definition from the user-defined configuration.
+ * The "normalization" means it will create full
+ * {@link module:ui/colorgrid/colorgrid~ColorDefinition `ColorDefinition-like`}
+ * object for string values, and add a `view` property, for each definition.
+ */
 export function normalizeSingleColorDefinition(color) {
     if (typeof color === 'string') {
         return {

package/src/componentfactory.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+/**
+ * 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

@@ -13,17 +13,19 @@ import { CKEditorError } from '@ckeditor/ckeditor5-utils';
  * in the factory. A registered component can be then instantiated by providing its name.
  * Note that the names are case insensitive.
  *
- *		// The editor provides localization tools for the factory.
- *		const factory = new ComponentFactory( editor );
+ * ```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 ) );
+ * factory.add( 'foo', locale => new FooView( locale ) );
+ * factory.add( 'bar', locale => new BarView( locale ) );
  *
- *		// An instance of FooView.
- *		const fooInstance = factory.create( 'foo' );
+ * // An instance of FooView.
+ * const fooInstance = factory.create( 'foo' );
  *
- *		// Names are case insensitive so this is also allowed:
- *		const barInstance = factory.create( 'Bar' );
+ * // 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.
@@ -32,29 +34,17 @@ export default class ComponentFactory {
     /**
      * Creates an instance of the factory.
      *
-     * @constructor
-     * @param {module:core/editor/editor~Editor} editor The editor instance.
+     * @param editor The editor instance.
      */
     constructor(editor) {
-        /**
-         * The editor instance that the factory belongs to.
-         *
-         * @readonly
-         * @member {module:core/editor/editor~Editor}
-         */
-        this.editor = editor;
         /**
          * Registered component factories.
-         *
-         * @private
-         * @member {Map}
          */
         this._components = new Map();
+        this.editor = editor;
     }
     /**
      * Returns an iterator of registered component names. Names are returned in lower case.
-     *
-     * @returns {Iterable.<String>}
      */
     *names() {
         for (const value of this._components.values()) {
@@ -67,8 +57,8 @@ export default class ComponentFactory {
      * {@link module:core/editor/editor~Editor#locale editor locale} as an argument,
      * allowing localization of the {@link module:ui/view~View view}.
      *
-     * @param {String} name The name of the component.
-     * @param {Function} callback The callback that returns the component.
+     * @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 });
@@ -80,8 +70,8 @@ export default class ComponentFactory {
      * the previously {@link #add added} factory function, allowing localization of the
      * {@link module:ui/view~View view}.
      *
-     * @param {String} name The name of the component.
-     * @returns {module:ui/view~View} The instantiated component view.
+     * @param name The name of the component.
+     * @returns The instantiated component view.
      */
     create(name) {
         if (!this.has(name)) {
@@ -91,7 +81,7 @@ export default class ComponentFactory {
              * {@link #add added} to the factory.
              *
              * @error componentfactory-item-missing
-             * @param {String} name The name of the missing component.
+             * @param name The name of the missing component.
              */
             throw new CKEditorError('componentfactory-item-missing', this, { name });
         }
@@ -100,19 +90,15 @@ export default class ComponentFactory {
     /**
      * Checks if a component of a given name is registered in the factory.
      *
-     * @param {String} name The name of the component.
-     * @returns {Boolean}
+     * @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.
-//
-// @private
-// @param {String} name
-// @returns {String}
+/**
+ * Ensures that the component name used as the key in the internal map is in lower case.
+ */
 function getNormalized(name) {
     return String(name).toLowerCase();
 }

package/src/dropdown/button/dropdownbutton.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/dropdown/button/dropdownbutton
+ */
+import type Button from '../../button/button';
+import type ViewCollection from '../../viewcollection';
+/**
+ * The dropdown button interface.
+ */
+export default interface DropdownButton extends Button {
+    children: ViewCollection;
+}
+/**
+ * Fired when the dropdown should be opened.
+ * It will not be fired when the button {@link #isEnabled is disabled}.
+ *
+ * @eventName open
+ */
+export type DropdownButtonOpenEvent = {
+    name: 'open';
+    args: [];
+};

package/src/dropdown/button/dropdownbuttonview.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/dropdown/button/dropdownbuttonview
+ */
+import ButtonView from '../../button/buttonview';
+import type DropdownButton from './dropdownbutton';
+import IconView from '../../icon/iconview';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The default dropdown button view class.
+ *
+ * ```ts
+ * const view = new DropdownButtonView();
+ *
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ *
+ * Also see the {@link module:ui/dropdown/utils~createDropdown `createDropdown()` util}.
+ */
+export default class DropdownButtonView extends ButtonView implements DropdownButton {
+    /**
+     * An icon that displays arrow to indicate a dropdown button.
+     */
+    readonly arrowView: IconView;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Creates a {@link module:ui/icon/iconview~IconView} instance as {@link #arrowView}.
+     */
+    private _createArrowView;
+}

package/src/dropdown/button/dropdownbuttonview.js

@@ -6,27 +6,26 @@
  * @module ui/dropdown/button/dropdownbuttonview
  */
 import ButtonView from '../../button/buttonview';
-import dropdownArrowIcon from '../../../theme/icons/dropdown-arrow.svg';
 import IconView from '../../icon/iconview';
+import dropdownArrowIcon from '../../../theme/icons/dropdown-arrow.svg';
 /**
  * The default dropdown button view class.
  *
- *		const view = new DropdownButtonView();
+ * ```ts
+ * const view = new DropdownButtonView();
  *
- *		view.set( {
- *			label: 'A button',
- *			keystroke: 'Ctrl+B',
- *			tooltip: true
- *		} );
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true
+ * } );
  *
- *		view.render();
+ * view.render();
  *
- *		document.body.append( view.element );
+ * document.body.append( view.element );
+ * ```
  *
  * Also see the {@link module:ui/dropdown/utils~createDropdown `createDropdown()` util}.
- *
- * @implements module:ui/dropdown/button/dropdownbutton~DropdownButton
- * @extends module:ui/button/buttonview~ButtonView
  */
 export default class DropdownButtonView extends ButtonView {
     /**
@@ -34,12 +33,6 @@ export default class DropdownButtonView extends ButtonView {
      */
     constructor(locale) {
         super(locale);
-        /**
-         * An icon that displays arrow to indicate a dropdown button.
-         *
-         * @readonly
-         * @member {module:ui/icon/iconview~IconView}
-         */
         this.arrowView = this._createArrowView();
         this.extendTemplate({
             attributes: {
@@ -59,9 +52,6 @@ export default class DropdownButtonView extends ButtonView {
     }
     /**
      * Creates a {@link module:ui/icon/iconview~IconView} instance as {@link #arrowView}.
-     *
-     * @private
-     * @returns {module:ui/icon/iconview~IconView}
      */
     _createArrowView() {
         const arrowView = new IconView();