@ckeditor/ckeditor5-ui 41.2.0 → 41.3.0-alpha.0

package/dist/types/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;

package/dist/types/colorpicker/colorpickerview.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @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/colorpicker/colorpickerview
+ */
+import { type ColorPickerViewConfig } from './utils.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import View from '../view.js';
+import type ViewCollection from '../viewcollection.js';
+import { HexBase } from 'vanilla-colorful/lib/entrypoints/hex';
+import '../../theme/components/colorpicker/colorpicker.css';
+declare global {
+    interface HTMLElementTagNameMap {
+        'hex-color-picker': HexBase;
+    }
+}
+/**
+ * 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.
+     */
+    picker: HexBase;
+    /**
+     * Container for a `#` sign prefix and an input for displaying and defining custom colors
+     * in HEX format.
+     */
+    hexInputRow: ColorPickerInputRowView;
+    /**
+     * 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;
+    /**
+     * List of slider views of the color picker.
+     */
+    slidersView: ViewCollection<SliderView>;
+    /**
+     * An internal representation of a color.
+     *
+     * Since the picker uses a hex format, that's how we store it.
+     *
+     * Since this is unified color format it won't fire a change event if color is changed
+     * from `#f00` to `#ff0000` (same value, different format).
+     *
+     * @observable
+     * @private
+     */
+    _hexColor: string;
+    /**
+     * 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;
+    /**
+     * A reference to the configuration of the color picker specified in the constructor.
+     *
+     * @private
+     */
+    private _config;
+    /**
+     * Creates a view of color picker.
+     *
+     * @param locale
+     * @param config
+     */
+    constructor(locale: Locale | undefined, config?: ColorPickerViewConfig);
+    /**
+     * Renders color picker in the view.
+     */
+    render(): void;
+    /**
+     * Focuses the first pointer in color picker.
+     *
+     */
+    focus(): void;
+    /**
+     * Creates collection of sliders in color picker.
+     *
+     * @private
+     */
+    private _createSlidersView;
+    /**
+     * Creates input row for defining custom colors in color picker.
+     *
+     * @private
+     */
+    private _createInputRow;
+    /**
+     * Creates the input where user can type or paste the color in hex format.
+     *
+     * @private
+     */
+    private _createColorInput;
+}
+declare class SliderView extends View {
+    /**
+     * @param element HTML element of slider in color picker.
+     */
+    constructor(element: HTMLElement);
+    /**
+     * Focuses element.
+     */
+    focus(): void;
+}
+declare class ColorPickerInputRowView extends View {
+    /**
+     * A collection of row items (buttons, dropdowns, etc.).
+     */
+    readonly children: ViewCollection;
+    /**
+     * Creates an instance of the form row class.
+     *
+     * @param locale The locale instance.
+     */
+    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/dist/types/colorpicker/utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @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
+ */
+/**
+ * Color formats handled by color converter.
+ */
+export type ColorPickerOutputFormat = 'hex' | 'rgb' | 'hsl' | 'hwb' | 'lab' | 'lch';
+/**
+ * Configuration of the color picker feature.
+ *
+ * It can be forced to apply colors in the editor in a particular format.
+ *
+ * @default `{
+ * 	format: 'hsl'
+ * }`
+ */
+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`.
+ *
+ * @param color
+ * @returns A color string.
+ */
+export declare function convertColor(color: string, outputFormat: ColorPickerOutputFormat): string;
+/**
+ * Converts a color string to hex format.
+ *
+ * @param color
+ * @returns A color string.
+ */
+export declare function convertToHex(color: string): string;
+/**
+ * Registers the custom element in the
+ * [CustomElementsRegistry](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry).
+ */
+export declare function registerCustomElement(elementName: string, constructor: CustomElementConstructor): void;

package/dist/types/colorselector/colorgridsfragmentview.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @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/colorgridsfragmentview
+ */
+import View from '../view.js';
+import ButtonView from '../button/buttonview.js';
+import ColorGridView, { type ColorDefinition } from '../colorgrid/colorgridview.js';
+import DocumentColorCollection from './documentcolorcollection.js';
+import type { Model } from '@ckeditor/ckeditor5-engine';
+import type { FocusTracker, Locale } from '@ckeditor/ckeditor5-utils';
+import type ViewCollection from '../viewcollection.js';
+import type { FocusableView } from '../focuscycler.js';
+/**
+ * One of the fragments of {@link module:ui/colorselector/colorselectorview~ColorSelectorView}.
+ *
+ * It provides a UI that allows users to select colors from the a predefined set and from existing document colors.
+ *
+ * It consists of the following sub–components:
+ *
+ * * A "Remove color" button,
+ * * A static {@link module:ui/colorgrid/colorgridview~ColorGridView} of colors defined in the configuration,
+ * * A dynamic {@link module:ui/colorgrid/colorgridview~ColorGridView} of colors used in the document.
+ * * If color picker is configured, the "Color Picker" button is visible too.
+ */
+export default class ColorGridsFragmentView extends View {
+    /**
+     * A collection of the children of the table.
+     */
+    readonly items: ViewCollection;
+    /**
+     * An array with objects representing colors to be displayed in the grid.
+     */
+    colorDefinitions: Array<ColorDefinition>;
+    /**
+     * Tracks information about the DOM focus in the list.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * The number of columns in the color grid.
+     */
+    columns: number;
+    /**
+     * Preserves the reference to {@link module:ui/colorselector/documentcolorcollection~DocumentColorCollection} used to collect
+     * definitions that store the document colors.
+     *
+     * @readonly
+     */
+    documentColors: DocumentColorCollection;
+    /**
+     * The maximum number of colors in the document colors section.
+     * If it equals 0, the document colors section is not added.
+     *
+     * @readonly
+     */
+    documentColorsCount?: number;
+    /**
+     * Keeps the value of the command associated with the table for the current selection.
+     */
+    selectedColor: string;
+    /**
+     * Preserves the reference to {@link module:ui/colorgrid/colorgridview~ColorGridView} used to create
+     * the default (static) color set.
+     *
+     * The property is loaded once the the parent dropdown is opened the first time.
+     *
+     * @readonly
+     */
+    staticColorsGrid: ColorGridView | undefined;
+    /**
+     * Preserves the reference to {@link module:ui/colorgrid/colorgridview~ColorGridView} used to create
+     * the document colors. It remains undefined if the document colors feature is disabled.
+     *
+     * The property is loaded once the the parent dropdown is opened the first time.
+     *
+     * @readonly
+     */
+    documentColorsGrid: ColorGridView | undefined;
+    /**
+     * The "Color picker" button view.
+     */
+    colorPickerButtonView?: ButtonView;
+    /**
+     * The "Remove color" button view.
+     */
+    removeColorButtonView: ButtonView;
+    /**
+     * The property which is responsible for is component visible or not.
+     */
+    isVisible: boolean;
+    /**
+     * A collection of views that can be focused in the view.
+     *
+     * @readonly
+     */
+    protected _focusables: ViewCollection<FocusableView>;
+    /**
+     * Document color section's label.
+     *
+     * @readonly
+     */
+    private _documentColorsLabel?;
+    /**
+     * The label of the button responsible for removing color attributes.
+     */
+    private _removeButtonLabel;
+    /**
+     * The label of the button responsible for switching to the color picker component.
+     */
+    private _colorPickerLabel;
+    /**
+     * Creates an instance of the view.
+     *
+     * @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 focusTracker Tracks information about the DOM focus in the list.
+     * @param focusables A collection of views that can be focused in the view.
+     */
+    constructor(locale: Locale, { colors, columns, removeButtonLabel, documentColorsLabel, documentColorsCount, colorPickerLabel, focusTracker, focusables }: {
+        colors: Array<ColorDefinition>;
+        columns: number;
+        removeButtonLabel: string;
+        colorPickerLabel: string;
+        documentColorsLabel?: string;
+        documentColorsCount?: number;
+        focusTracker: FocusTracker;
+        focusables: ViewCollection<FocusableView>;
+    });
+    /**
+     * Scans through the editor model and searches for text node attributes with the given attribute name.
+     * Found entries are set as document colors.
+     *
+     * 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: Model, attributeName: string): void;
+    /**
+     * Refreshes the state of the selected color in one or both {@link module:ui/colorgrid/colorgridview~ColorGridView}s
+     * available in the {@link module:ui/colorselector/colorselectorview~ColorSelectorView}. It guarantees that the selection will
+     * occur only in one of them.
+     */
+    updateSelectedColors(): void;
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the component.
+     */
+    focus(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Handles displaying the color picker button (if it was previously created) and making it focusable.
+     */
+    addColorPickerButton(): void;
+    /**
+     * Adds color selector elements to focus tracker.
+     */
+    private _addColorSelectorElementsToFocusTracker;
+    /**
+     * Creates the button responsible for displaying the color picker component.
+     */
+    private _createColorPickerButton;
+    /**
+     * Adds the remove color button as a child of the current view.
+     */
+    private _createRemoveColorButton;
+    /**
+     * Creates a static color grid based on the editor configuration.
+     */
+    private _createStaticColorsGrid;
+    /**
+     * Creates the document colors section view and binds it to {@link #documentColors}.
+     */
+    private _createDocumentColorsGrid;
+    /**
+     * Adds a given color to the document colors list. If possible, the method will attempt to use
+     * data from the {@link #colorDefinitions} (label, color options).
+     *
+     * @param color A string that stores the value of the recently applied color.
+     */
+    private _addColorToDocumentColors;
+}

package/dist/types/colorselector/colorpickerfragmentview.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @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/colorpickerfragmentview
+ */
+import View from '../view.js';
+import ButtonView from '../button/buttonview.js';
+import type ViewCollection from '../viewcollection.js';
+import type { FocusableView } from '../focuscycler.js';
+import { default as ColorPickerView } from '../colorpicker/colorpickerview.js';
+import type { FocusTracker, KeystrokeHandler, Locale } from '@ckeditor/ckeditor5-utils';
+import type { ColorPickerViewConfig } from '../colorpicker/utils.js';
+/**
+ * One of the fragments of {@link module:ui/colorselector/colorselectorview~ColorSelectorView}.
+ *
+ * It allows users to select a color from a color picker.
+ *
+ * It consists of the following sub–components:
+ *
+ * * A color picker saturation and hue sliders,
+ * * A text input accepting colors in HEX format,
+ * * "Save" and "Cancel" action buttons.
+ */
+export default class ColorPickerFragmentView extends View {
+    /**
+     * A collection of component's children.
+     */
+    readonly items: ViewCollection;
+    /**
+     * A view with saturation and hue sliders and color input.
+     */
+    colorPickerView?: ColorPickerView;
+    /**
+     * The "Save" button view.
+     */
+    saveButtonView: ButtonView;
+    /**
+     * The "Cancel" button view.
+     */
+    cancelButtonView: ButtonView;
+    /**
+     * The action bar where are "Save" button and "Cancel" button.
+     */
+    actionBarView: View;
+    /**
+     * Tracks information about the DOM focus in the list.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Indicates whether the component is visible or not.
+     */
+    isVisible: boolean;
+    /**
+     * Keeps the value of the command associated with the component for the current selection.
+     */
+    selectedColor?: string;
+    /**
+     * A collection of views that can be focused in the view.
+     *
+     * @readonly
+     */
+    protected _focusables: ViewCollection<FocusableView>;
+    /**
+     * A reference to the configuration of {@link #colorPickerView}. `false` when the view was
+     * configured without a color picker.
+     *
+     * @readonly
+     */
+    private _colorPickerViewConfig;
+    /**
+     * Creates an instance of the view.
+     *
+     * @param locale The localization services instance.
+     * @param focusTracker Tracks information about the DOM focus in the list.
+     * @param focusables A collection of views that can be focused in the view..
+     * @param keystrokes An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     * @param colorPickerViewConfig The configuration of color picker feature. If set to `false`, the color picker
+     * will not be rendered.
+     */
+    constructor(locale: Locale, { focusTracker, focusables, keystrokes, colorPickerViewConfig }: {
+        focusTracker: FocusTracker;
+        focusables: ViewCollection<FocusableView>;
+        keystrokes: KeystrokeHandler;
+        colorPickerViewConfig: ColorPickerViewConfig | false;
+    });
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the color picker.
+     */
+    focus(): void;
+    /**
+     * When color picker is focused and "enter" is pressed it executes command.
+     */
+    private _executeOnEnterPress;
+    /**
+     * Removes default behavior of arrow keys in dropdown.
+     */
+    private _stopPropagationOnArrowsKeys;
+    /**
+     * Adds color picker elements to focus tracker.
+     */
+    private _addColorPickersElementsToFocusTracker;
+    /**
+     * Creates bar containing "Save" and "Cancel" buttons.
+     */
+    private _createActionBarView;
+    /**
+     * Creates "Save" and "Cancel" buttons.
+     */
+    private _createActionButtons;
+    /**
+     * Fires the `execute` event if color in color picker has been changed
+     * by the user.
+     */
+    private _executeUponColorChange;
+}