@ckeditor/ckeditor5-ui 41.3.1 → 41.4.0

package/dist/types/button/buttonlabel.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @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
+ */
+/**
+ * @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/buttonlabel
+*/
+import type View from '../view.js';
+/**
+ * The button label interface. Implemented by the {@link module:ui/button/buttonlabelview~ButtonLabelView}
+ * and any label view that can be used with the {@link module:ui/button/buttonview~ButtonView}.
+ */
+export default interface ButtonLabel extends View {
+    /**
+     * The `id` attribute of the button label. It is used for accessibility purposes
+     * to describe the button.
+     *
+     * @observable
+     */
+    id: string | undefined;
+    /**
+     * The `style` attribute of the button label. It allows customizing the presentation
+     * of the label.
+     *
+     * @observable
+     */
+    style: string | undefined;
+    /**
+     * The human-readable text of the label.
+     *
+     * @observable
+     */
+    text: string | undefined;
+}

package/dist/types/button/buttonlabelview.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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
+ */
+/**
+ * @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/buttonlabelview
+ */
+import View from '../view.js';
+import type ButtonLabel from './buttonlabel.js';
+/**
+ * A default implementation of the button view's label. It comes with a dynamic text support
+ * via {@link module:ui/button/buttonlabelview~ButtonLabelView#text} property.
+ */
+export default class ButtonLabelView extends View implements ButtonLabel {
+    /**
+     * @inheritDoc
+     */
+    id: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    style: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    text: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    constructor();
+}

package/dist/types/button/buttonview.d.ts

@@ -0,0 +1,189 @@
+/**
+ * @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
+ */
+/**
+ * @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/buttonview
+ */
+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 ButtonLabel from './buttonlabel.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/button/button.css';
+/**
+ * The button view class.
+ *
+ * ```ts
+ * const view = new ButtonView();
+ *
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true,
+ * 	withText: true
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ */
+export default class ButtonView extends View<HTMLButtonElement> implements Button {
+    /**
+     * Collection of the child views inside of the button {@link #element}.
+     */
+    readonly children: ViewCollection;
+    /**
+     * Label of the button view. Its text is configurable using the {@link #label label attribute}.
+     *
+     * If not configured otherwise in the `constructor()`, by default the label is an instance
+     * of {@link module:ui/button/buttonlabelview~ButtonLabelView}.
+     */
+    readonly labelView: ButtonLabel;
+    /**
+     * The icon view of the button. Will be added to {@link #children} when the
+     * {@link #icon icon attribute} is defined.
+     */
+    readonly iconView: IconView;
+    /**
+     * A view displaying the keystroke of the button next to the {@link #labelView label}.
+     * Added to {@link #children} when the {@link #withKeystroke `withKeystroke` attribute}
+     * is defined.
+     */
+    readonly keystrokeView: View;
+    /**
+     * @inheritDoc
+     */
+    class: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    labelStyle: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    icon: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    isEnabled: boolean;
+    /**
+     * @inheritDoc
+     */
+    isOn: boolean;
+    /**
+     * @inheritDoc
+     */
+    isVisible: boolean;
+    /**
+     * @inheritDoc
+     */
+    isToggleable: boolean;
+    /**
+     * @inheritDoc
+     */
+    keystroke: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    label: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    tabindex: number;
+    /**
+     * @inheritDoc
+     */
+    tooltip: Button['tooltip'];
+    /**
+     * @inheritDoc
+     */
+    tooltipPosition: Button['tooltipPosition'];
+    /**
+     * @inheritDoc
+     */
+    type: Button['type'];
+    /**
+     * @inheritDoc
+     */
+    withText: boolean;
+    /**
+     * @inheritDoc
+     */
+    withKeystroke: boolean;
+    /**
+     * @inheritDoc
+     */
+    role: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaChecked: boolean | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaLabel?: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaLabelledBy: string | undefined;
+    /**
+     * Tooltip of the button bound to the template.
+     *
+     * @see #tooltip
+     * @see module:ui/button/buttonview~ButtonView#_getTooltipString
+     * @internal
+     * @observable
+     */
+    _tooltipString: string;
+    /**
+     * Delayed focus function for focus handling in Safari.
+     */
+    private _focusDelayed;
+    /**
+     * Creates an instance of the button view class.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param labelView The instance of the button's label. If not provided, an instance of
+     * {@link module:ui/button/buttonlabelview~ButtonLabelView} is used.
+     */
+    constructor(locale?: Locale, labelView?: ButtonLabel);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the {@link #element} of the button.
+     */
+    focus(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Binds the label view instance it with button attributes.
+     */
+    private _setupLabelView;
+    /**
+     * Creates a view that displays a keystroke next to a {@link #labelView label }
+     * and binds it with button attributes.
+     */
+    private _createKeystrokeView;
+    /**
+     * Gets the text for the tooltip from the combination of
+     * {@link #tooltip}, {@link #label} and {@link #keystroke} attributes.
+     *
+     * @see #tooltip
+     * @see #_tooltipString
+     * @param tooltip Button tooltip.
+     * @param label Button label.
+     * @param keystroke Button keystroke.
+     */
+    private _getTooltipString;
+}

package/dist/types/button/filedialogbuttonview.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @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
+ */
+/**
+ * @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 ButtonView from './buttonview.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The file dialog button view.
+ *
+ * This component provides a button that opens the native file selection dialog.
+ * It can be used to implement the UI of a file upload feature.
+ *
+ * ```ts
+ * const view = new FileDialogButtonView( locale );
+ *
+ * view.set( {
+ * 	acceptedType: 'image/*',
+ * 	allowMultipleFiles: true
+ * 	label: t( 'Insert image' ),
+ * 	icon: imageIcon,
+ * 	tooltip: true
+ * } );
+ *
+ * view.on( 'done', ( evt, files ) => {
+ * 	for ( const file of Array.from( files ) ) {
+ * 		console.log( 'Selected file', file );
+ * 	}
+ * } );
+ * ```
+ */
+export default class FileDialogButtonView extends ButtonView {
+    /**
+     * The button view of the component.
+     *
+     * @deprecated
+     */
+    buttonView: ButtonView;
+    /**
+     * A hidden `<input>` view used to execute file dialog.
+     */
+    private _fileInputView;
+    /**
+     * Accepted file types. Can be provided in form of file extensions, media type or one of:
+     * * `audio/*`,
+     * * `video/*`,
+     * * `image/*`.
+     *
+     * @observable
+     */
+    acceptedType: string;
+    /**
+     * Indicates if multiple files can be selected. Defaults to `true`.
+     *
+     * @observable
+     */
+    allowMultipleFiles: boolean;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+}
+/**
+ * Fired when file dialog is closed with file selected.
+ *
+ * ```ts
+ * view.on( 'done', ( evt, files ) => {
+ * 	for ( const file of files ) {
+ * 		console.log( 'Selected file', file );
+ * 	}
+ * }
+ * ```
+ */
+export type FileInputViewDoneEvent = {
+    name: 'done';
+    args: [files: FileList];
+};

package/dist/types/button/switchbuttonview.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @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
+ */
+/**
+ * @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/dist/types/collapsible/collapsibleview.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @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
+ */
+/**
+ * @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/dist/types/colorgrid/colorgridview.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @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
+ */
+/**
+ * @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/dist/types/colorgrid/colortileview.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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
+ */
+/**
+ * @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/dist/types/colorgrid/utils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @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
+ */
+/**
+ * @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;