@ckeditor/ckeditor5-ui 38.2.0-alpha.0 → 38.2.0-alpha.1

package/lang/contexts.json

@@ -23,5 +23,6 @@
 	"Purple": "Label of a button that applies a purple color in color pickers.",
 	"Editor block content toolbar": "Accessible label of a toolbar that shows up next to the blocks of content (e.g. headings, paragraphs).",
 	"Editor contextual toolbar": "Accessible label of a balloon toolbar that shows up right next to the user selection (the caret).",
-	"HEX": "Label of an input field for typing colors in the HEX color format."
+	"HEX": "Label of an input field for typing colors in the HEX color format.",
+	"Accept": "Label of the button closing the color picker and confirming the changes done in the color selector component."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-ui",
-  "version": "38.2.0-alpha.0",
+  "version": "38.2.0-alpha.1",
   "description": "The UI framework and standard UI library of CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -12,8 +12,8 @@
   "main": "src/index.js",
   "type": "module",
   "dependencies": {
-    "@ckeditor/ckeditor5-core": "38.2.0-alpha.0",
-    "@ckeditor/ckeditor5-utils": "38.2.0-alpha.0",
+    "@ckeditor/ckeditor5-core": "38.2.0-alpha.1",
+    "@ckeditor/ckeditor5-utils": "38.2.0-alpha.1",
     "color-convert": "2.0.1",
     "color-parse": "1.4.2",
     "lodash-es": "^4.17.15",

package/src/augmentation.d.ts

@@ -2,7 +2,7 @@
  * @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
  */
-import type { BalloonToolbar, BlockToolbar, ContextualBalloon, Notification } from './index';
+import type { BalloonToolbar, BlockToolbar, ContextualBalloon, Notification } from './index.js';
 import type { ToolbarConfig } from '@ckeditor/ckeditor5-core';
 declare module '@ckeditor/ckeditor5-core' {
     interface EditorConfig {

package/src/bindings/addkeyboardhandlingforgrid.d.ts

@@ -6,7 +6,7 @@
  * @module ui/bindings/addkeyboardhandlingforgrid
  */
 import type { FocusTracker, KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
-import type ViewCollection from '../viewcollection';
+import type ViewCollection from '../viewcollection.js';
 /**
  * A helper that adds a keyboard navigation support (arrow up/down/left/right) for grids.
  *

package/src/bindings/csstransitiondisablermixin.d.ts

@@ -6,7 +6,7 @@
  * @module ui/bindings/csstransitiondisablermixin
  */
 import type { Constructor, Mixed } from '@ckeditor/ckeditor5-utils';
-import type View from '../view';
+import type View from '../view.js';
 /**
  * A mixin that brings the possibility to temporarily disable CSS transitions using
  * {@link module:ui/view~View} methods. It is helpful when, for instance, the transitions should not happen

package/src/bindings/injectcsstransitiondisabler.d.ts

@@ -5,7 +5,7 @@
 /**
  * @module ui/bindings/injectcsstransitiondisabler
  */
-import type View from '../view';
+import type View from '../view.js';
 /**
  * A decorator that brings the possibility to temporarily disable CSS transitions using
  * {@link module:ui/view~View} methods. It is helpful when, for instance, the transitions should not happen
@@ -21,7 +21,7 @@ import type View from '../view';
  * {@link module:ui/view~View#setTemplate} is called:
  *
  * ```ts
- * import injectCssTransitionDisabler from '@ckeditor/ckeditor5-ui/src/bindings/injectcsstransitiondisabler';
+ * import injectCssTransitionDisabler from '@ckeditor/ckeditor5-ui/src/bindings/injectcsstransitiondisabler.js';
  *
  * class MyView extends View {
  * 	constructor() {

package/src/bindings/injectcsstransitiondisabler.js

@@ -17,7 +17,7 @@
  * {@link module:ui/view~View#setTemplate} is called:
  *
  * ```ts
- * import injectCssTransitionDisabler from '@ckeditor/ckeditor5-ui/src/bindings/injectcsstransitiondisabler';
+ * import injectCssTransitionDisabler from '@ckeditor/ckeditor5-ui/src/bindings/injectcsstransitiondisabler.js';
  *
  * class MyView extends View {
  * 	constructor() {

package/src/bindings/preventdefault.d.ts

@@ -5,8 +5,8 @@
 /**
  * @module ui/bindings/preventdefault
  */
-import type { ListenerBinding } from '../template';
-import type View from '../view';
+import type { ListenerBinding } from '../template.js';
+import type View from '../view.js';
 /**
  * A helper which executes a native `Event.preventDefault()` if the target of an event equals the
  * {@link module:ui/view~View#element element of the view}. It shortens the definition of a
@@ -14,7 +14,7 @@ import type View from '../view';
  *
  * ```ts
  * // In a class extending View.
- * import preventDefault from '@ckeditor/ckeditor5-ui/src/bindings/preventdefault';
+ * import preventDefault from '@ckeditor/ckeditor5-ui/src/bindings/preventdefault.js';
  *
  * // ...
  *

package/src/bindings/preventdefault.js

@@ -9,7 +9,7 @@
  *
  * ```ts
  * // In a class extending View.
- * import preventDefault from '@ckeditor/ckeditor5-ui/src/bindings/preventdefault';
+ * import preventDefault from '@ckeditor/ckeditor5-ui/src/bindings/preventdefault.js';
  *
  * // ...
  *

package/src/bindings/submithandler.d.ts

@@ -5,7 +5,7 @@
 /**
  * @module ui/bindings/submithandler
  */
-import type View from '../view';
+import type View from '../view.js';
 /**
  * A handler useful for {@link module:ui/view~View views} working as HTML forms. It intercepts a native DOM
  * `submit` event, prevents the default web browser behavior (navigation and page reload) and
@@ -13,7 +13,7 @@ import type View from '../view';
  * {@link module:utils/dom/emittermixin~DomEmitter emitter}, e.g. to serialize the form data.
  *
  * ```ts
- * import submitHandler from '@ckeditor/ckeditor5-ui/src/bindings/submithandler';
+ * import submitHandler from '@ckeditor/ckeditor5-ui/src/bindings/submithandler.js';
  *
  * // ...
  *

package/src/bindings/submithandler.js

@@ -9,7 +9,7 @@
  * {@link module:utils/dom/emittermixin~DomEmitter emitter}, e.g. to serialize the form data.
  *
  * ```ts
- * import submitHandler from '@ckeditor/ckeditor5-ui/src/bindings/submithandler';
+ * import submitHandler from '@ckeditor/ckeditor5-ui/src/bindings/submithandler.js';
  *
  * // ...
  *

package/src/button/buttonview.d.ts

@@ -5,10 +5,10 @@
 /**
  * @module ui/button/buttonview
  */
-import View from '../view';
-import IconView from '../icon/iconview';
-import type ViewCollection from '../viewcollection';
-import type { default as Button } from './button';
+import View from '../view.js';
+import IconView from '../icon/iconview.js';
+import type ViewCollection from '../viewcollection.js';
+import type { default as Button } from './button.js';
 import { type Locale } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/button/button.css';
 /**

package/src/button/buttonview.js

@@ -5,8 +5,8 @@
 /**
  * @module ui/button/buttonview
  */
-import View from '../view';
-import IconView from '../icon/iconview';
+import View from '../view.js';
+import IconView from '../icon/iconview.js';
 import { env, getEnvKeystrokeText, uid, delay } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/button/button.css';
 /**

package/src/button/switchbuttonview.d.ts

@@ -5,8 +5,8 @@
 /**
  * @module ui/button/switchbuttonview
  */
-import View from '../view';
-import ButtonView from './buttonview';
+import View from '../view.js';
+import ButtonView from './buttonview.js';
 import type { Locale } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/button/switchbutton.css';
 /**

package/src/button/switchbuttonview.js

@@ -5,8 +5,8 @@
 /**
  * @module ui/button/switchbuttonview
  */
-import View from '../view';
-import ButtonView from './buttonview';
+import View from '../view.js';
+import ButtonView from './buttonview.js';
 import '../../theme/components/button/switchbutton.css';
 /**
  * The switch button view class.

package/src/colorgrid/colorgridview.d.ts

@@ -5,10 +5,10 @@
 /**
  * @module ui/colorgrid/colorgridview
  */
-import View from '../view';
-import ColorTileView from './colortileview';
-import type DropdownPanelFocusable from '../dropdown/dropdownpanelfocusable';
-import type ViewCollection from '../viewcollection';
+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';
 /**

package/src/colorgrid/colorgridview.js

@@ -5,9 +5,9 @@
 /**
  * @module ui/colorgrid/colorgridview
  */
-import View from '../view';
-import ColorTileView from './colortileview';
-import addKeyboardHandlingForGrid from '../bindings/addkeyboardhandlingforgrid';
+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';
 /**

package/src/colorgrid/colortileview.d.ts

@@ -5,7 +5,7 @@
 /**
  * @module ui/colorgrid/colortileview
  */
-import ButtonView from '../button/buttonview';
+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}.

package/src/colorgrid/colortileview.js

@@ -5,7 +5,7 @@
 /**
  * @module ui/colorgrid/colortileview
  */
-import ButtonView from '../button/buttonview';
+import ButtonView from '../button/buttonview.js';
 import checkIcon from '../../theme/icons/color-tile-check.svg';
 /**
  * This class represents a single color tile in the {@link module:ui/colorgrid/colorgridview~ColorGridView}.
@@ -25,7 +25,7 @@ export default class ColorTileView extends ButtonView {
                 class: [
                     'ck',
                     'ck-color-grid__tile',
-                    bind.if('hasBorder', 'ck-color-table__color-tile_bordered')
+                    bind.if('hasBorder', 'ck-color-selector__color-tile_bordered')
                 ]
             }
         });

package/src/colorpicker/colorpickerview.d.ts

@@ -5,12 +5,15 @@
 /**
  * @module ui/colorpicker/colorpickerview
  */
-import { type ColorPickerConfig } from './utils';
+import { type ColorPickerViewConfig } from './utils.js';
 import { type Locale } from '@ckeditor/ckeditor5-utils';
-import View from '../view';
-import type ViewCollection from '../viewcollection';
+import View from '../view.js';
+import type ViewCollection from '../viewcollection.js';
 import 'vanilla-colorful/hex-color-picker.js';
 import '../../theme/components/colorpicker/colorpicker.css';
+/**
+ * A class which represents a color picker with an input field for defining custom colors.
+ */
 export default class ColorPickerView extends View {
     /**
      * Element with saturation and hue sliders.
@@ -22,7 +25,8 @@ export default class ColorPickerView extends View {
      */
     hexInputRow: ColorPickerInputRowView;
     /**
-     * Current color state in color picker.
+     * Current color selected in the color picker. It can be set by the component itself
+     * (through the palette or input) or from the outside (e.g. to reflect the current selection color).
      */
     color: string;
     /**
@@ -42,21 +46,26 @@ export default class ColorPickerView extends View {
      */
     _hexColor: string;
     /**
-    * Debounced event method. The `colorPickerEvent()` method is called the specified `waitingTime` after
-    * `debouncedPickerEvent()` is called, unless a new action happens in the meantime.
-    */
+     * Debounced function updating the `color` property in the component
+     * and firing the `ColorPickerColorSelectedEvent`. Executed whenever color in component
+     * is changed by the user interaction (through the palette or input).
+     *
+     * @private
+     */
     private _debounceColorPickerEvent;
     /**
-     * The output format (the one in which colors are applied in the model) of color picker.
+     * A reference to the configuration of the color picker specified in the constructor.
+     *
+     * @private
      */
-    private _format;
+    private _config;
     /**
      * Creates a view of color picker.
      *
      * @param locale
      * @param config
      */
-    constructor(locale: Locale | undefined, config: ColorPickerConfig);
+    constructor(locale: Locale | undefined, config?: ColorPickerViewConfig);
     /**
      * Renders color picker in the view.
      */
@@ -107,4 +116,22 @@ declare class ColorPickerInputRowView extends View {
      */
     constructor(locale: Locale, children?: Array<View>);
 }
+/**
+ * An event fired whenever the color was selected through the color picker palette
+ * or the color picker input.
+ *
+ * This even fires only when the user changes the color. It does not fire when the color
+ * is changed programmatically, e.g. via
+ * {@link module:ui/colorpicker/colorpickerview~ColorPickerView#color}.
+ *
+ * @eventName ~ColorPickerView#colorSelected
+ */
+export type ColorPickerColorSelectedEvent = {
+    name: 'colorSelected';
+    args: [
+        {
+            color: string;
+        }
+    ];
+};
 export {};

package/src/colorpicker/colorpickerview.js

@@ -5,15 +5,18 @@
 /**
  * @module ui/colorpicker/colorpickerview
  */
-import { convertColor, convertToHex } from './utils';
+import { convertColor, convertToHex } from './utils.js';
 import { global, env } from '@ckeditor/ckeditor5-utils';
 import { debounce } from 'lodash-es';
-import View from '../view';
-import LabeledFieldView from '../labeledfield/labeledfieldview';
-import { createLabeledInputText } from '../labeledfield/utils';
+import View from '../view.js';
+import LabeledFieldView from '../labeledfield/labeledfieldview.js';
+import { createLabeledInputText } from '../labeledfield/utils.js';
 import 'vanilla-colorful/hex-color-picker.js';
 import '../../theme/components/colorpicker/colorpicker.css';
 const waitingTime = 150;
+/**
+ * A class which represents a color picker with an input field for defining custom colors.
+ */
 export default class ColorPickerView extends View {
     /**
      * Creates a view of color picker.
@@ -21,14 +24,17 @@ export default class ColorPickerView extends View {
      * @param locale
      * @param config
      */
-    constructor(locale, config) {
+    constructor(locale, config = {}) {
         super(locale);
-        this.set('color', '');
-        this.set('_hexColor', '');
-        this._format = config.format || 'hsl';
+        this.set({
+            color: '',
+            _hexColor: ''
+        });
         this.hexInputRow = this._createInputRow();
         const children = this.createCollection();
-        children.add(this.hexInputRow);
+        if (!config.hideInput) {
+            children.add(this.hexInputRow);
+        }
         this.setTemplate({
             tag: 'div',
             attributes: {
@@ -37,21 +43,27 @@ export default class ColorPickerView extends View {
             },
             children
         });
+        this._config = config;
         this._debounceColorPickerEvent = debounce((color) => {
+            // At first, set the color internally in the component. It's converted to the configured output format.
             this.set('color', color);
+            // Then let the outside world know that the user changed the color.
+            this.fire('colorSelected', { color: this.color });
         }, waitingTime, {
             leading: true
         });
-        // Sets color in the picker if color was updated.
+        // The `color` property holds the color in the configured output format.
+        // Ensure it before actually setting the value.
         this.on('set:color', (evt, propertyName, newValue) => {
-            // The color needs always to be kept in the output format.
-            evt.return = convertColor(newValue, this._format);
+            evt.return = convertColor(newValue, this._config.format || 'hsl');
         });
+        // The `_hexColor` property is bound to the `color` one, but requires conversion.
         this.on('change:color', () => {
             this._hexColor = convertColorToCommonHexFormat(this.color);
         });
         this.on('change:_hexColor', () => {
-            // Should update color in color picker when its not focused
+            // Update the selected color in the color picker palette when it's not focused.
+            // It means the user typed the color in the input.
             if (document.activeElement !== this.picker) {
                 this.picker.setAttribute('color', this._hexColor);
             }
@@ -72,7 +84,12 @@ export default class ColorPickerView extends View {
         this.picker.setAttribute('tabindex', '-1');
         this._createSlidersView();
         if (this.element) {
-            this.element.insertBefore(this.picker, this.hexInputRow.element);
+            if (this.hexInputRow.element) {
+                this.element.insertBefore(this.picker, this.hexInputRow.element);
+            }
+            else {
+                this.element.appendChild(this.picker);
+            }
             // Create custom stylesheet with a look of focused pointer in color picker and append it into the color picker shadowDom
             const styleSheetForFocusedColorPicker = document.createElement('style');
             styleSheetForFocusedColorPicker.textContent = '[role="slider"]:focus [part$="pointer"] {' +
@@ -101,7 +118,7 @@ export default class ColorPickerView extends View {
         // See: https://github.com/cksource/ckeditor5-internal/issues/3245, https://github.com/ckeditor/ckeditor5/issues/14119,
         // https://github.com/cksource/ckeditor5-internal/issues/3268.
         /* istanbul ignore next -- @preserve */
-        if (env.isGecko || env.isiOS || env.isSafari) {
+        if (!this._config.hideInput && (env.isGecko || env.isiOS || env.isSafari)) {
             const input = this.hexInputRow.children.get(1);
             input.focus();
         }
@@ -209,7 +226,7 @@ class SliderView extends View {
         this.element.focus();
     }
 }
-// View abstaction over the `#` character before color input.
+// View abstraction over the `#` character before color input.
 class HashView extends View {
     constructor(locale) {
         super(locale);

package/src/colorpicker/utils.d.ts

@@ -18,6 +18,14 @@ export type ColorPickerOutputFormat = 'hex' | 'rgb' | 'hsl' | 'hwb' | 'lab' | 'l
 export type ColorPickerConfig = {
     format?: ColorPickerOutputFormat;
 };
+/**
+ * Configuration of the color picker view.
+ *
+ * It can be used to enforce a particular color format or hide the color input.
+ */
+export type ColorPickerViewConfig = ColorPickerConfig & {
+    hideInput?: boolean;
+};
 /**
  * Parses and converts the color string to requested format. Handles variety of color spaces
  * like `hsl`, `hex` or `rgb`.