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

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

@@ -0,0 +1,175 @@
+/**
+ * @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/button
+ */
+/**
+ * The button interface. Implemented by, among others, {@link module:ui/button/buttonview~ButtonView},
+ * {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView} and
+ * {@link module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView}.
+ */
+export default interface Button {
+    /**
+     * The label of the button view visible to the user when {@link #withText} is `true`.
+     * It can also be used to create a {@link #tooltip}.
+     *
+     * @observable
+     */
+    label: string | undefined;
+    /**
+     * (Optional) The keystroke associated with the button, i.e. <kbd>CTRL+B</kbd>,
+     * in the string format compatible with {@link module:utils/keyboard}.
+     *
+     * **Note**: Use {@link module:ui/button/button~Button#withKeystroke} if you want to display
+     * the keystroke information next to the {@link module:ui/button/button~Button#label label}.
+     *
+     * @observable
+     */
+    keystroke: string | undefined;
+    /**
+     * (Optional) Tooltip of the button, i.e. displayed when hovering the button with the mouse cursor.
+     *
+     * * If defined as a `Boolean` (e.g. `true`), then combination of `label` and `keystroke` will be set as a tooltip.
+     * * If defined as a `String`, tooltip will equal the exact text of that `String`.
+     * * If defined as a `Function`, `label` and `keystroke` will be passed to that function, which is to return
+     * a string with the tooltip text.
+     *
+     * ```ts
+     * const view = new ButtonView( locale );
+     * view.tooltip = ( label, keystroke ) => `A tooltip for ${ label } and ${ keystroke }.`
+     * ```
+     *
+     * @observable
+     * @default false
+     */
+    tooltip: boolean | string | ((label: string, keystroke: string | undefined) => string);
+    /**
+     * (Optional) The position of the tooltip. See {@link module:ui/tooltipmanager~TooltipManager}
+     * to learn more about the tooltip system.
+     *
+     * **Note:** It makes sense only when the {@link #tooltip `tooltip` attribute} is defined.
+     *
+     * @observable
+     * @default 's'
+     */
+    tooltipPosition: 's' | 'n' | 'e' | 'w' | 'sw' | 'se';
+    /**
+     * The HTML type of the button.
+     *
+     * @observable
+     * @default 'button'
+     */
+    type: 'button' | 'submit' | 'reset' | 'menu';
+    /**
+     * Controls whether the button view is "on". It makes sense when a feature it represents
+     * is currently active, e.g. a bold button is "on" when the selection is in the bold text.
+     *
+     * To disable the button, use {@link #isEnabled} instead.
+     *
+     * @observable
+     * @default true
+     */
+    isOn: boolean;
+    /**
+     * Controls whether the button view is enabled, i.e. it can be clicked and execute an action.
+     *
+     * To change the "on" state of the button, use {@link #isOn} instead.
+     *
+     * @observable
+     * @default true
+     */
+    isEnabled: boolean;
+    /**
+     * Controls whether the button view is visible. Visible by default, buttons are hidden
+     * using a CSS class.
+     *
+     * @observable
+     * @default true
+     */
+    isVisible: boolean;
+    /**
+     * Controls whether the button view is a toggle button (two–state) for assistive technologies.
+     *
+     * @observable
+     * @default false
+     */
+    isToggleable: boolean;
+    /**
+     * (Optional) Controls whether the label of the button is hidden (e.g. an icon–only button).
+     *
+     * @observable
+     * @default false
+     */
+    withText: boolean;
+    /**
+     * (Optional) Controls whether the keystroke of the button is displayed next to its
+     * {@link module:ui/button/button~Button#label label}.
+     *
+     * **Note**: This property requires a {@link module:ui/button/button~Button#keystroke keystroke}
+     * to be defined in the first place.
+     *
+     * @observable
+     * @default false
+     */
+    withKeystroke: boolean;
+    /**
+     * (Optional) An XML {@link module:ui/icon/iconview~IconView#content content} of the icon.
+     * When defined, an `iconView` should be added to the button.
+     *
+     * The user must provide the entire XML string, not just the path. See the
+     * {@glink framework/architecture/ui-library#setting-label-icon-and-tooltip UI library} guide for details.
+     *
+     * @observable
+     */
+    icon: string | undefined;
+    /**
+     * (Optional) Controls the `tabindex` HTML attribute of the button. By default, the button is focusable
+     * but does not included in the <kbd>Tab</kbd> order.
+     *
+     * @observable
+     * @default -1
+     */
+    tabindex: number;
+    /**
+     * (Optional) The additional CSS class set on the button.
+     *
+     * @observable
+     */
+    class: string | undefined;
+    /**
+     * (Optional) The ARIA property reflected by the `aria-label` DOM attribute used by assistive technologies.
+     *
+     * @observable
+     */
+    ariaLabel?: string | undefined;
+    /**
+     * (Optional) The ARIA property reflected by the `aria-ariaLabelledBy` DOM attribute used by assistive technologies.
+     *
+     * @observable
+     */
+    ariaLabelledBy?: string | undefined;
+    /**
+     * (Optional) The property reflected by the `role` DOM attribute to be used by assistive technologies.
+     *
+     * @observable
+     */
+    role?: string | undefined;
+    /**
+     * (Optional) The value of the `style` attribute of the label.
+     *
+     * @observable
+     */
+    labelStyle: string | undefined;
+}
+/**
+ * Fired when the button view is clicked. It won't be fired when the button {@link module:ui/button/button~Button#isEnabled}
+ * is `false`.
+ *
+ * @eventName ~Button#execute
+ */
+export type ButtonExecuteEvent = {
+    name: 'execute';
+    args: [];
+};

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

@@ -0,0 +1,34 @@
+/**
+ * @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,31 @@
+/**
+ * @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,181 @@
+/**
+ * @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
+     */
+    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/switchbuttonview.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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,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/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,132 @@
+/**
+ * @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,28 @@
+/**
+ * @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;
+}