@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/labeledinput/labeledinputview.js

@@ -0,0 +1,125 @@
+/**
+ * @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 { uid } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/labeledinput/labeledinput.css';
+/**
+ * The labeled input view class.
+ */
+export default class LabeledInputView extends View {
+    /**
+     * Creates an instance of the labeled input view class.
+     *
+     * @param locale The locale instance.
+     * @param InputView Constructor of the input view.
+     */
+    constructor(locale, InputView) {
+        super(locale);
+        const inputUid = `ck-input-${uid()}`;
+        const statusUid = `ck-status-${uid()}`;
+        this.set('label', undefined);
+        this.set('value', undefined);
+        this.set('isReadOnly', false);
+        this.set('errorText', null);
+        this.set('infoText', null);
+        this.labelView = this._createLabelView(inputUid);
+        this.inputView = this._createInputView(InputView, inputUid, statusUid);
+        this.statusView = this._createStatusView(statusUid);
+        this.bind('_statusText').to(this, 'errorText', this, 'infoText', (errorText, infoText) => errorText || infoText);
+        const bind = this.bindTemplate;
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-labeled-input',
+                    bind.if('isReadOnly', 'ck-disabled')
+                ]
+            },
+            children: [
+                this.labelView,
+                this.inputView,
+                this.statusView
+            ]
+        });
+    }
+    /**
+     * Creates label view class instance and bind with view.
+     *
+     * @param id Unique id to set as labelView#for attribute.
+     */
+    _createLabelView(id) {
+        const labelView = new LabelView(this.locale);
+        labelView.for = id;
+        labelView.bind('text').to(this, 'label');
+        return labelView;
+    }
+    /**
+     * 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.
+     */
+    _createInputView(InputView, inputUid, statusUid) {
+        const inputView = new InputView(this.locale, statusUid);
+        inputView.id = inputUid;
+        inputView.ariaDescribedById = statusUid;
+        inputView.bind('value').to(this);
+        inputView.bind('isReadOnly').to(this);
+        inputView.bind('hasError').to(this, 'errorText', value => !!value);
+        inputView.on('input', () => {
+            // UX: Make the error text disappear and disable the error indicator as the user
+            // starts fixing the errors.
+            this.errorText = null;
+        });
+        return inputView;
+    }
+    /**
+     * 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.
+     */
+    _createStatusView(statusUid) {
+        const statusView = new View(this.locale);
+        const bind = this.bindTemplate;
+        statusView.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-labeled-input__status',
+                    bind.if('errorText', 'ck-labeled-input__status_error'),
+                    bind.if('_statusText', 'ck-hidden', value => !value)
+                ],
+                id: statusUid,
+                role: bind.if('errorText', 'alert')
+            },
+            children: [
+                {
+                    text: bind.to('_statusText')
+                }
+            ]
+        });
+        return statusView;
+    }
+    /**
+     * Moves the focus to the input and selects the value.
+     */
+    select() {
+        this.inputView.select();
+    }
+    /**
+     * Focuses the input.
+     */
+    focus() {
+        this.inputView.focus();
+    }
+}

package/src/list/listitemgroupview.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @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/src/list/listitemgroupview.js

@@ -0,0 +1,67 @@
+/**
+ * @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 ListView from './listview.js';
+import LabelView from '../label/labelview.js';
+import ListSeparatorView from './listseparatorview.js';
+/**
+ * The list item group view class.
+ */
+export default class ListItemGroupView extends View {
+    /**
+     * 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, labelView = new LabelView()) {
+        super(locale);
+        const bind = this.bindTemplate;
+        const nestedList = new ListView(locale);
+        this.set({
+            label: '',
+            isVisible: true
+        });
+        this.labelView = labelView;
+        this.labelView.bind('text').to(this, 'label');
+        this.children = this.createCollection();
+        this.children.addMany([this.labelView, nestedList]);
+        nestedList.set({
+            role: 'group',
+            ariaLabelledBy: labelView.id
+        });
+        // Disable focus tracking and accessible navigation in the child list.
+        nestedList.focusTracker.destroy();
+        nestedList.keystrokes.destroy();
+        this.items = nestedList.items;
+        this.setTemplate({
+            tag: 'li',
+            attributes: {
+                role: 'presentation',
+                class: [
+                    'ck',
+                    'ck-list__group',
+                    bind.if('isVisible', 'ck-hidden', value => !value)
+                ]
+            },
+            children: this.children
+        });
+    }
+    /**
+     * Focuses the list item (which is not a separator).
+     */
+    focus() {
+        if (this.items) {
+            const firstListItem = this.items.find(item => !(item instanceof ListSeparatorView));
+            if (firstListItem) {
+                firstListItem.focus();
+            }
+        }
+    }
+}

package/src/list/listitemview.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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/src/list/listitemview.js

@@ -0,0 +1,42 @@
+/**
+ * @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';
+/**
+ * The list item view class.
+ */
+export default class ListItemView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set('isVisible', true);
+        this.children = this.createCollection();
+        this.setTemplate({
+            tag: 'li',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-list__item',
+                    bind.if('isVisible', 'ck-hidden', value => !value)
+                ],
+                role: 'presentation'
+            },
+            children: this.children
+        });
+    }
+    /**
+     * Focuses the list item.
+     */
+    focus() {
+        if (this.children.first) {
+            this.children.first.focus();
+        }
+    }
+}

package/src/list/listseparatorview.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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/src/list/listseparatorview.js

@@ -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/list/listseparatorview
+ */
+import View from '../view.js';
+/**
+ * The list separator view class.
+ */
+export default class ListSeparatorView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        this.setTemplate({
+            tag: 'li',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-list__separator'
+                ]
+            }
+        });
+    }
+}

package/src/list/listview.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @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/src/list/listview.js

@@ -0,0 +1,188 @@
+/**
+ * @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 FocusCycler from '../focuscycler.js';
+import ListItemView from './listitemview.js';
+import ListItemGroupView from './listitemgroupview.js';
+import ViewCollection from '../viewcollection.js';
+import { FocusTracker, KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/list/list.css';
+/**
+ * The list view class.
+ */
+export default class ListView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        /**
+         * A cached map of {@link module:ui/list/listitemgroupview~ListItemGroupView} to `change` event listeners for their `items`.
+         * Used for accessibility and keyboard navigation purposes.
+         */
+        this._listItemGroupToChangeListeners = new WeakMap();
+        const bind = this.bindTemplate;
+        this.focusables = new ViewCollection();
+        this.items = this.createCollection();
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        this._focusCycler = new FocusCycler({
+            focusables: this.focusables,
+            focusTracker: this.focusTracker,
+            keystrokeHandler: this.keystrokes,
+            actions: {
+                // Navigate list items backwards using the arrowup key.
+                focusPrevious: 'arrowup',
+                // Navigate toolbar items forwards using the arrowdown key.
+                focusNext: 'arrowdown'
+            }
+        });
+        this.set('ariaLabel', undefined);
+        this.set('ariaLabelledBy', undefined);
+        this.set('role', undefined);
+        this.setTemplate({
+            tag: 'ul',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-reset',
+                    'ck-list'
+                ],
+                role: bind.to('role'),
+                'aria-label': bind.to('ariaLabel'),
+                'aria-labelledby': bind.to('ariaLabelledBy')
+            },
+            children: this.items
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        // Items added before rendering should be known to the #focusTracker.
+        for (const item of this.items) {
+            if (item instanceof ListItemGroupView) {
+                this._registerFocusableItemsGroup(item);
+            }
+            else if (item instanceof ListItemView) {
+                this._registerFocusableListItem(item);
+            }
+        }
+        this.items.on('change', (evt, data) => {
+            for (const removed of data.removed) {
+                if (removed instanceof ListItemGroupView) {
+                    this._deregisterFocusableItemsGroup(removed);
+                }
+                else if (removed instanceof ListItemView) {
+                    this._deregisterFocusableListItem(removed);
+                }
+            }
+            for (const added of Array.from(data.added).reverse()) {
+                if (added instanceof ListItemGroupView) {
+                    this._registerFocusableItemsGroup(added, data.index);
+                }
+                else {
+                    this._registerFocusableListItem(added, data.index);
+                }
+            }
+        });
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focus() {
+        this._focusCycler.focusFirst();
+    }
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focusFirst() {
+        this._focusCycler.focusFirst();
+    }
+    /**
+     * Focuses the last focusable in {@link #items}.
+     */
+    focusLast() {
+        this._focusCycler.focusLast();
+    }
+    /**
+     * 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.
+     */
+    _registerFocusableListItem(item, index) {
+        this.focusTracker.add(item.element);
+        this.focusables.add(item, index);
+    }
+    /**
+     * Removes a list item view from the focus tracker.
+     *
+     * @param item The list item view to be removed.
+     */
+    _deregisterFocusableListItem(item) {
+        this.focusTracker.remove(item.element);
+        this.focusables.remove(item);
+    }
+    /**
+     * 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.
+     */
+    _getOnGroupItemsChangeCallback(groupView) {
+        return (evt, data) => {
+            for (const removed of data.removed) {
+                this._deregisterFocusableListItem(removed);
+            }
+            for (const added of Array.from(data.added).reverse()) {
+                this._registerFocusableListItem(added, this.items.getIndex(groupView) + data.index);
+            }
+        };
+    }
+    /**
+     * 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.
+     */
+    _registerFocusableItemsGroup(groupView, groupIndex) {
+        Array.from(groupView.items).forEach((child, childIndex) => {
+            const registeredChildIndex = typeof groupIndex !== 'undefined' ? groupIndex + childIndex : undefined;
+            this._registerFocusableListItem(child, registeredChildIndex);
+        });
+        const groupItemsChangeCallback = this._getOnGroupItemsChangeCallback(groupView);
+        // Cache the reference to the callback in case the group is removed (see _deregisterFocusableItemsGroup()).
+        this._listItemGroupToChangeListeners.set(groupView, groupItemsChangeCallback);
+        groupView.items.on('change', groupItemsChangeCallback);
+    }
+    /**
+     * Removes a list item group view (and its children) from the focus tracker.
+     *
+     * @param groupView The group view to be removed.
+     */
+    _deregisterFocusableItemsGroup(groupView) {
+        for (const child of groupView.items) {
+            this._deregisterFocusableListItem(child);
+        }
+        groupView.items.off('change', this._listItemGroupToChangeListeners.get(groupView));
+        this._listItemGroupToChangeListeners.delete(groupView);
+    }
+}