@ckeditor/ckeditor5-ui 41.3.1 → 41.4.0

package/dist/types/labeledinput/labeledinputview.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
+ */
+/**
+ * @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/labeledinput/labeledinputview
+ */
+import View from '../view.js';
+import LabelView from '../label/labelview.js';
+import type { default as InputView } from '../input/inputview.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/labeledinput/labeledinput.css';
+/**
+ * The labeled input view class.
+ */
+export default class LabeledInputView extends View {
+    /**
+     * The label view.
+     */
+    readonly labelView: LabelView;
+    /**
+     * The input view.
+     */
+    readonly inputView: InputView;
+    /**
+     * The status view for the {@link #inputView}. It displays {@link #errorText} and
+     * {@link #infoText}.
+     */
+    readonly statusView: View;
+    /**
+     * The text of the label.
+     *
+     * @observable
+     */
+    label: string | undefined;
+    /**
+     * The value of the input.
+     *
+     * @observable
+     */
+    value: string | undefined;
+    /**
+     * Controls whether the component is in read-only mode.
+     *
+     * @observable
+     */
+    isReadOnly: boolean;
+    /**
+     * The validation error text. When set, it will be displayed
+     * next to the {@link #inputView} as a typical validation error message.
+     * Set it to `null` to hide the message.
+     *
+     * **Note:** Setting this property to anything but `null` will automatically
+     * make the {@link module:ui/inputtext/inputtextview~InputTextView#hasError `hasError`}
+     * of the {@link #inputView} `true`.
+     *
+     * **Note:** Typing in the {@link #inputView} which fires the
+     * {@link module:ui/inputtext/inputtextview~InputTextView#event:input `input` event}
+     * resets this property back to `null`, indicating that the input field can be re–validated.
+     *
+     * @observable
+     */
+    errorText: string | null;
+    /**
+     * The additional information text displayed next to the {@link #inputView} which can
+     * be used to inform the user about the purpose of the input, provide help or hints.
+     *
+     * Set it to `null` to hide the message.
+     *
+     * **Note:** This text will be displayed in the same place as {@link #errorText} but the
+     * latter always takes precedence: if the {@link #errorText} is set, it replaces
+     * {@link #errorText} for as long as the value of the input is invalid.
+     *
+     * @observable
+     */
+    infoText: string | null;
+    /**
+     * The combined status text made of {@link #errorText} and {@link #infoText}.
+     * Note that when present, {@link #errorText} always takes precedence in the
+     * status.
+     *
+     * @see #errorText
+     * @see #infoText
+     * @see #statusView
+     * @private
+     * @observable
+     */
+    _statusText: string | null;
+    /**
+     * Creates an instance of the labeled input view class.
+     *
+     * @param locale The locale instance.
+     * @param InputView Constructor of the input view.
+     */
+    constructor(locale: Locale | undefined, InputView: new (locale: Locale | undefined, statusUid: string) => InputView);
+    /**
+     * Creates label view class instance and bind with view.
+     *
+     * @param id Unique id to set as labelView#for attribute.
+     */
+    private _createLabelView;
+    /**
+     * Creates input view class instance and bind with view.
+     *
+     * @param InputView Input view constructor.
+     * @param inputUid Unique id to set as inputView#id attribute.
+     * @param statusUid Unique id of the status for the input's `aria-describedby` attribute.
+     */
+    private _createInputView;
+    /**
+     * Creates the status view instance. It displays {@link #errorText} and {@link #infoText}
+     * next to the {@link #inputView}. See {@link #_statusText}.
+     *
+     * @param statusUid Unique id of the status, shared with the input's `aria-describedby` attribute.
+     */
+    private _createStatusView;
+    /**
+     * Moves the focus to the input and selects the value.
+     */
+    select(): void;
+    /**
+     * Focuses the input.
+     */
+    focus(): void;
+}

package/dist/types/list/listitemgroupview.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @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/list/listitemgroupview
+ */
+import View from '../view.js';
+import type ViewCollection from '../viewcollection.js';
+import ListView from './listview.js';
+import LabelView from '../label/labelview.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The list item group view class.
+ */
+export default class ListItemGroupView extends View {
+    /**
+     * The visible label of the group.
+     *
+     * @observable
+     * @default ''
+     */
+    label: string;
+    /**
+     * Label of the group view. Its text is configurable using the {@link #label label attribute}.
+     *
+     * If a custom label view is not passed in `ListItemGroupView` constructor, the label is an instance
+     * of {@link module:ui/label/labelview~LabelView}.
+     */
+    readonly labelView: LabelView;
+    /**
+     * Collection of the child list items inside this group.
+     */
+    readonly items: ListView['items'];
+    /**
+     * Collection of the child elements of the group.
+     */
+    readonly children: ViewCollection;
+    /**
+     * Controls whether the item view is visible. Visible by default, list items are hidden
+     * using a CSS class.
+     *
+     * @observable
+     * @default true
+     */
+    isVisible: boolean;
+    /**
+     * Creates an instance of the list item group view class.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param labelView The instance of the group's label. If not provided, an instance of
+     * {@link module:ui/label/labelview~LabelView} is used.
+     */
+    constructor(locale?: Locale, labelView?: LabelView);
+    /**
+     * Focuses the list item (which is not a separator).
+     */
+    focus(): void;
+}

package/dist/types/list/listitemview.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @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/list/listitemview
+ */
+import View from '../view.js';
+import type { FocusableView } from '../focuscycler.js';
+import type ViewCollection from '../viewcollection.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The list item view class.
+ */
+export default class ListItemView extends View {
+    /**
+     * Collection of the child views inside of the list item {@link #element}.
+     */
+    readonly children: ViewCollection<FocusableView>;
+    /**
+     * Controls whether the item view is visible. Visible by default, list items are hidden
+     * using a CSS class.
+     *
+     * @observable
+     * @default true
+     */
+    isVisible: boolean;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * Focuses the list item.
+     */
+    focus(): void;
+}

package/dist/types/list/listseparatorview.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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/list/listseparatorview
+ */
+import View from '../view.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The list separator view class.
+ */
+export default class ListSeparatorView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}

package/dist/types/list/listview.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @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/list/listview
+ */
+import View from '../view.js';
+import { type FocusableView } from '../focuscycler.js';
+import ListItemView from './listitemview.js';
+import ListItemGroupView from './listitemgroupview.js';
+import type ListSeparatorView from './listseparatorview.js';
+import type DropdownPanelFocusable from '../dropdown/dropdownpanelfocusable.js';
+import ViewCollection from '../viewcollection.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/list/list.css';
+/**
+ * The list view class.
+ */
+export default class ListView extends View<HTMLUListElement> implements DropdownPanelFocusable {
+    /**
+     * The collection of focusable views in the list. It is used to determine accessible navigation
+     * between the {@link module:ui/list/listitemview~ListItemView list items} and
+     * {@link module:ui/list/listitemgroupview~ListItemGroupView list groups}.
+     */
+    readonly focusables: ViewCollection<FocusableView>;
+    /**
+     * Collection of the child list views.
+     */
+    readonly items: ViewCollection<ListItemView | ListItemGroupView | ListSeparatorView>;
+    /**
+     * Tracks information about DOM focus in the list.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Label used by assistive technologies to describe this list element.
+     *
+     * @observable
+     */
+    ariaLabel: string | undefined;
+    /**
+     * (Optional) The ARIA property reflected by the `aria-ariaLabelledBy` DOM attribute used by assistive technologies.
+     *
+     * @observable
+     */
+    ariaLabelledBy?: string | undefined;
+    /**
+     * The property reflected by the `role` DOM attribute to be used by assistive technologies.
+     *
+     * @observable
+     */
+    role: string | undefined;
+    /**
+     * Helps cycling over focusable {@link #items} in the list.
+     */
+    private readonly _focusCycler;
+    /**
+     * A cached map of {@link module:ui/list/listitemgroupview~ListItemGroupView} to `change` event listeners for their `items`.
+     * Used for accessibility and keyboard navigation purposes.
+     */
+    private readonly _listItemGroupToChangeListeners;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focus(): void;
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focusFirst(): void;
+    /**
+     * Focuses the last focusable in {@link #items}.
+     */
+    focusLast(): void;
+    /**
+     * Registers a list item view in the focus tracker.
+     *
+     * @param item The list item view to be registered.
+     * @param index Index of the list item view in the {@link #items} collection. If not specified, the item will be added at the end.
+     */
+    private _registerFocusableListItem;
+    /**
+     * Removes a list item view from the focus tracker.
+     *
+     * @param item The list item view to be removed.
+     */
+    private _deregisterFocusableListItem;
+    /**
+     * Gets a callback that will be called when the `items` collection of a {@link module:ui/list/listitemgroupview~ListItemGroupView}
+     * change.
+     *
+     * @param groupView The group view for which the callback will be created.
+     * @returns The callback function to be used for the items `change` event listener in a group.
+     */
+    private _getOnGroupItemsChangeCallback;
+    /**
+     * Registers a list item group view (and its children) in the focus tracker.
+     *
+     * @param groupView A group view to be registered.
+     * @param groupIndex Index of the group view in the {@link #items} collection. If not specified, the group will be added at the end.
+     */
+    private _registerFocusableItemsGroup;
+    /**
+     * Removes a list item group view (and its children) from the focus tracker.
+     *
+     * @param groupView The group view to be removed.
+     */
+    private _deregisterFocusableItemsGroup;
+}

package/dist/types/menubar/menubarmenubuttonview.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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/menubar/menubarmenubuttonview
+ */
+import IconView from '../icon/iconview.js';
+import ButtonView from '../button/buttonview.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/menubar/menubarmenubutton.css';
+/**
+ * A menu {@link module:ui/menubar/menubarmenuview~MenuBarMenuView#buttonView} class. Buttons like this one
+ * open both top-level bar menus as well as sub-menus.
+ */
+export default class MenuBarMenuButtonView extends ButtonView {
+    /**
+     * An icon that displays an arrow to indicate a direction of the menu.
+     */
+    readonly arrowView: IconView;
+    /**
+     * Creates an instance of the menu bar button view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Creates the {@link #arrowView} instance.
+     */
+    private _createArrowView;
+}

package/dist/types/menubar/menubarmenulistitembuttonview.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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/menubar/menubarmenulistitembuttonview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import ButtonView from '../button/buttonview.js';
+import '../../theme/components/menubar/menubarmenulistitembutton.css';
+/**
+ * A menu bar list button view. Buttons like this one execute user actions.
+ */
+export default class MenuBarMenuListItemButtonView extends ButtonView {
+    /**
+     * Creates an instance of the menu bar list button view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+}

package/dist/types/menubar/menubarmenulistitemfiledialogbuttonview.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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/menubar/menubarmenulistitemfiledialogbuttonview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import FileDialogButtonView from '../button/filedialogbuttonview.js';
+import '../../theme/components/menubar/menubarmenulistitembutton.css';
+/**
+ * A menu bar list file dialog button view. Buttons like this one execute user actions.
+ *
+ * This component provides a button that opens the native file selection dialog.
+ */
+export default class MenuBarMenuListItemFileDialogButtonView extends FileDialogButtonView {
+    /**
+     * Creates an instance of the menu bar list button view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+}

package/dist/types/menubar/menubarmenulistitemview.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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/menubar/menubarmenulistitemview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import ListItemView from '../list/listitemview.js';
+import type MenuBarMenuView from './menubarmenuview.js';
+import '../../theme/components/menubar/menubarmenulistitem.css';
+/**
+ * A menu bar list item view, a child of {@link module:ui/menubar/menubarmenulistview~MenuBarMenuListView}.
+ *
+ * Populate this item with a {@link module:ui/menubar/menubarmenulistitembuttonview~MenuBarMenuListItemButtonView} instance
+ * or a {@link module:ui/menubar/menubarmenuview~MenuBarMenuView} instance to create a sub-menu.
+ */
+export default class MenuBarMenuListItemView extends ListItemView {
+    /**
+     * Creates an instance of the list item view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale, parentMenuView: MenuBarMenuView);
+}

package/dist/types/menubar/menubarmenulistview.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
+ */
+/**
+ * @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/menubar/menubarmenulistview
+ */
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import ListView from '../list/listview.js';
+/**
+ * A list of menu bar items, a child of {@link module:ui/menubar/menubarmenuview~MenuBarMenuView#panelView}.
+ *
+ * Use this class to create a list of items (options, buttons) to be displayed in a menu bar.
+ *
+ * To populate this list, use {@link module:ui/menubar/menubarmenulistitemview~MenuBarMenuListItemView} instances.
+ */
+export default class MenuBarMenuListView extends ListView {
+    /**
+     * Creates an instance of the list view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+}

package/dist/types/menubar/menubarmenupanelview.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @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/menubar/menubarmenupanelview
+ */
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import type { FocusableView } from '../focuscycler.js';
+import type ViewCollection from '../viewcollection.js';
+import View from '../view.js';
+import '../../theme/components/menubar/menubarmenupanel.css';
+/**
+ * A view representing a {@link module:ui/menubar/menubarmenuview~MenuBarMenuView#panelView} of a menu.
+ */
+export default class MenuBarMenuPanelView extends View implements FocusableView {
+    /**
+     * Collection of the child views in this panel.
+     */
+    readonly children: ViewCollection<FocusableView>;
+    /**
+     * Controls whether the panel is visible.
+     *
+     * @observable
+     */
+    isVisible: boolean;
+    /**
+     * The name of the position of the panel, relative to the parent.
+     *
+     * This property is reflected in the CSS class suffix set to {@link #element} that controls
+     * the position of the panel.
+     *
+     * @observable
+     * @default 'se'
+     */
+    position: MenuBarMenuPanelPosition;
+    /**
+     * Creates an instance of the menu panel view.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale?: Locale);
+    /**
+     * Focuses the first child of the panel (default) or the last one if the `direction` is `-1`.
+     */
+    focus(direction?: -1 | 1): void;
+}
+/**
+ * The names of the positions of the {@link module:ui/menubar/menubarmenupanelview~MenuBarMenuPanelView}.
+ *
+ * They are reflected as CSS class suffixes on the panel view element.
+ */
+export type MenuBarMenuPanelPosition = 'se' | 'sw' | 'ne' | 'nw' | 'w' | 'e';