@ckeditor/ckeditor5-ui 40.2.0 → 41.1.0

package/src/dropdown/dropdownview.js

@@ -1,11 +1,11 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/dropdown/dropdownview
  */
-import View from '../view';
+import View from '../view.js';
 import { KeystrokeHandler, FocusTracker, getOptimalPosition } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/dropdown/dropdown.css';
 /**
@@ -60,7 +60,7 @@ import '../../theme/components/dropdown/dropdown.css';
  * (which should close it) and support for arrow keys inside the panel. Therefore, unless you really know what
  * you do and you really need to do it, it is recommended to use the {@link module:ui/dropdown/utils~createDropdown} helper.
  */
-export default class DropdownView extends View {
+class DropdownView extends View {
     /**
      * Creates an instance of the dropdown.
      *
@@ -295,7 +295,7 @@ export default class DropdownView extends View {
  *		       [ Button ]
  * ```
  *
- * Positioning functions are compatible with {@link module:utils/dom/position~Position}.
+ * Positioning functions are compatible with {@link module:utils/dom/position~DomPoint}.
  *
  * The name that position function returns will be reflected in dropdown panel's class that
  * controls its placement. See {@link module:ui/dropdown/dropdownview~DropdownView#panelPosition}
@@ -377,3 +377,4 @@ DropdownView.defaultPanelPositions = {
  * A function used to calculate the optimal position for the dropdown panel.
  */
 DropdownView._getOptimalPosition = getOptimalPosition;
+export default DropdownView;

package/src/dropdown/utils.d.ts

@@ -1,14 +1,14 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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 DropdownView from './dropdownview';
-import ViewCollection from '../viewcollection';
-import type { default as View } from '../view';
-import type Model from '../model';
-import type DropdownButton from './button/dropdownbutton';
-import type { FocusableView } from '../focuscycler';
-import type { FalsyValue } from '../template';
+import DropdownView from './dropdownview.js';
+import ViewCollection from '../viewcollection.js';
+import type { default as View } from '../view.js';
+import type Model from '../model.js';
+import type DropdownButton from './button/dropdownbutton.js';
+import type { FocusableView } from '../focuscycler.js';
+import type { FalsyValue } from '../template.js';
 import { type Collection, type Locale } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/dropdown/toolbardropdown.css';
 import '../../theme/components/dropdown/listdropdown.css';
@@ -137,7 +137,7 @@ export declare function addToolbarToDropdown(dropdownView: DropdownView, buttons
  * Adds an instance of {@link module:ui/list/listview~ListView} to a dropdown.
  *
  * ```ts
- * const items = new Collection();
+ * const items = new Collection<ListDropdownItemDefinition>();
  *
  * items.add( {
  * 	type: 'button',

package/src/dropdown/utils.js

@@ -1,26 +1,26 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/dropdown/utils
  */
-import DropdownPanelView from './dropdownpanelview';
-import DropdownView from './dropdownview';
-import DropdownButtonView from './button/dropdownbuttonview';
-import ToolbarView from '../toolbar/toolbarview';
-import ListView from '../list/listview';
-import ListItemView from '../list/listitemview';
-import ListSeparatorView from '../list/listseparatorview';
-import ButtonView from '../button/buttonview';
-import SplitButtonView from './button/splitbuttonview';
-import SwitchButtonView from '../button/switchbuttonview';
-import ViewCollection from '../viewcollection';
-import clickOutsideHandler from '../bindings/clickoutsidehandler';
+import DropdownPanelView from './dropdownpanelview.js';
+import DropdownView from './dropdownview.js';
+import DropdownButtonView from './button/dropdownbuttonview.js';
+import ToolbarView from '../toolbar/toolbarview.js';
+import ListView from '../list/listview.js';
+import ListItemView from '../list/listitemview.js';
+import ListSeparatorView from '../list/listseparatorview.js';
+import ButtonView from '../button/buttonview.js';
+import SplitButtonView from './button/splitbuttonview.js';
+import SwitchButtonView from '../button/switchbuttonview.js';
+import ViewCollection from '../viewcollection.js';
+import clickOutsideHandler from '../bindings/clickoutsidehandler.js';
 import { global, priorities, logWarning } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/dropdown/toolbardropdown.css';
 import '../../theme/components/dropdown/listdropdown.css';
-import ListItemGroupView from '../list/listitemgroupview';
+import ListItemGroupView from '../list/listitemgroupview.js';
 /**
  * A helper for creating dropdowns. It creates an instance of a {@link module:ui/dropdown/dropdownview~DropdownView dropdown},
  * with a {@link module:ui/dropdown/button/dropdownbutton~DropdownButton button},
@@ -198,7 +198,7 @@ function addToolbarToOpenDropdown(dropdownView, buttonsOrCallback, options) {
  * Adds an instance of {@link module:ui/list/listview~ListView} to a dropdown.
  *
  * ```ts
- * const items = new Collection();
+ * const items = new Collection<ListDropdownItemDefinition>();
  *
  * items.add( {
  * 	type: 'button',

package/src/editableui/editableuiview.d.ts

@@ -1,12 +1,12 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editableui/editableuiview
  */
-import View from '../view';
-import type { View as EditingView } from '@ckeditor/ckeditor5-engine';
+import View from '../view.js';
+import type { EditingView } from '@ckeditor/ckeditor5-engine';
 import type { Locale } from '@ckeditor/ckeditor5-utils';
 /**
  * The editable UI view class.

package/src/editableui/editableuiview.js

@@ -1,11 +1,11 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editableui/editableuiview
  */
-import View from '../view';
+import View from '../view.js';
 /**
  * The editable UI view class.
  */

package/src/editableui/inline/inlineeditableuiview.d.ts

@@ -1,12 +1,12 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editableui/inline/inlineeditableuiview
  */
-import EditableUIView from '../editableuiview';
-import type { View } from '@ckeditor/ckeditor5-engine';
+import EditableUIView from '../editableuiview.js';
+import type { EditingView } from '@ckeditor/ckeditor5-engine';
 import type { Locale } from '@ckeditor/ckeditor5-utils';
 /**
  * The inline editable UI class implementing an inline {@link module:ui/editableui/editableuiview~EditableUIView}.
@@ -30,7 +30,7 @@ export default class InlineEditableUIView extends EditableUIView {
      * and should return a string that represents the label of the editable for assistive technologies. If not provided,
      * a default label generator is used.
      */
-    constructor(locale: Locale, editingView: View, editableElement?: HTMLElement, options?: {
+    constructor(locale: Locale, editingView: EditingView, editableElement?: HTMLElement, options?: {
         label?: (view: InlineEditableUIView) => string;
     });
     /**

package/src/editableui/inline/inlineeditableuiview.js

@@ -1,11 +1,11 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editableui/inline/inlineeditableuiview
  */
-import EditableUIView from '../editableuiview';
+import EditableUIView from '../editableuiview.js';
 /**
  * The inline editable UI class implementing an inline {@link module:ui/editableui/editableuiview~EditableUIView}.
  */

package/src/editorui/bodycollection.d.ts

@@ -1,9 +1,9 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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 ViewCollection from '../viewcollection';
-import type View from '../view';
+import ViewCollection from '../viewcollection.js';
+import type View from '../view.js';
 import { type Locale } from '@ckeditor/ckeditor5-utils';
 /**
  * This is a special {@link module:ui/viewcollection~ViewCollection} dedicated to elements that are detached

package/src/editorui/bodycollection.js

@@ -1,13 +1,13 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editorui/bodycollection
  */
 /* globals document */
-import Template from '../template';
-import ViewCollection from '../viewcollection';
+import Template from '../template.js';
+import ViewCollection from '../viewcollection.js';
 import { createElement } from '@ckeditor/ckeditor5-utils';
 /**
  * This is a special {@link module:ui/viewcollection~ViewCollection} dedicated to elements that are detached

package/src/editorui/boxed/boxededitoruiview.d.ts

@@ -1,12 +1,12 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editorui/boxed/boxededitoruiview
  */
-import EditorUIView from '../editoruiview';
-import type ViewCollection from '../../viewcollection';
+import EditorUIView from '../editoruiview.js';
+import type ViewCollection from '../../viewcollection.js';
 import type { Locale } from '@ckeditor/ckeditor5-utils';
 /**
  * The boxed editor UI view class. This class represents an editor interface

package/src/editorui/boxed/boxededitoruiview.js

@@ -1,12 +1,12 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editorui/boxed/boxededitoruiview
  */
-import EditorUIView from '../editoruiview';
-import LabelView from '../../label/labelview';
+import EditorUIView from '../editoruiview.js';
+import LabelView from '../../label/labelview.js';
 /**
  * The boxed editor UI view class. This class represents an editor interface
  * consisting of a toolbar and an editable area, enclosed within a box.

package/src/editorui/editorui.d.ts

@@ -1,16 +1,16 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editorui/editorui
  */
-import ComponentFactory from '../componentfactory';
-import TooltipManager from '../tooltipmanager';
-import PoweredBy from './poweredby';
-import AriaLiveAnnouncer from '../arialiveannouncer';
-import type EditorUIView from './editoruiview';
-import type ToolbarView from '../toolbar/toolbarview';
+import ComponentFactory from '../componentfactory.js';
+import TooltipManager from '../tooltipmanager.js';
+import PoweredBy from './poweredby.js';
+import AriaLiveAnnouncer from '../arialiveannouncer.js';
+import type EditorUIView from './editoruiview.js';
+import type ToolbarView from '../toolbar/toolbarview.js';
 import { FocusTracker } from '@ckeditor/ckeditor5-utils';
 import type { Editor } from '@ckeditor/ckeditor5-core';
 declare const EditorUI_base: {

package/src/editorui/editorui.js

@@ -1,15 +1,15 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editorui/editorui
  */
 /* globals console */
-import ComponentFactory from '../componentfactory';
-import TooltipManager from '../tooltipmanager';
-import PoweredBy from './poweredby';
-import AriaLiveAnnouncer from '../arialiveannouncer';
+import ComponentFactory from '../componentfactory.js';
+import TooltipManager from '../tooltipmanager.js';
+import PoweredBy from './poweredby.js';
+import AriaLiveAnnouncer from '../arialiveannouncer.js';
 import { ObservableMixin, isVisible, FocusTracker } from '@ckeditor/ckeditor5-utils';
 /**
  * A class providing the minimal interface that is required to successfully bootstrap any editor UI.

package/src/editorui/editoruiview.d.ts

@@ -1,13 +1,13 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editorui/editoruiview
  */
-import View from '../view';
-import BodyCollection from './bodycollection';
-import type EditableUIView from '../editableui/editableuiview';
+import View from '../view.js';
+import BodyCollection from './bodycollection.js';
+import type EditableUIView from '../editableui/editableuiview.js';
 import type { Locale, LocaleTranslate } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/editorui/editorui.css';
 /**

package/src/editorui/editoruiview.js

@@ -1,12 +1,12 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/editorui/editoruiview
  */
-import View from '../view';
-import BodyCollection from './bodycollection';
+import View from '../view.js';
+import BodyCollection from './bodycollection.js';
 import '../../theme/components/editorui/editorui.css';
 /**
  * The editor UI view class. Base class for the editor main views.

package/src/editorui/poweredby.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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
  */
 /**

package/src/editorui/poweredby.js

@@ -1,11 +1,11 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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 { DomEmitterMixin, Rect, verifyLicense } from '@ckeditor/ckeditor5-utils';
-import BalloonPanelView from '../panel/balloon/balloonpanelview';
-import IconView from '../icon/iconview';
-import View from '../view';
+import BalloonPanelView from '../panel/balloon/balloonpanelview.js';
+import IconView from '../icon/iconview.js';
+import View from '../view.js';
 import { throttle } from 'lodash-es';
 import poweredByIcon from '../../theme/icons/project-logo.svg';
 const ICON_WIDTH = 53;

package/src/focuscycler.d.ts

@@ -1,19 +1,19 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/focuscycler
  */
 import { type ArrayOrItem, type FocusTracker, type KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
-import type View from './view';
-import type ViewCollection from './viewcollection';
+import type View from './view.js';
+import type ViewCollection from './viewcollection.js';
 declare const FocusCycler_base: {
     new (): import("@ckeditor/ckeditor5-utils").Emitter;
     prototype: import("@ckeditor/ckeditor5-utils").Emitter;
 };
 /**
- * A utility class that helps cycling over focusable {@link module:ui/view~View views} in a
+ * A utility class that helps cycling over {@link module:ui/focuscycler~FocusableView focusable views} in a
  * {@link module:ui/viewcollection~ViewCollection} when the focus is tracked by the
  * {@link module:utils/focustracker~FocusTracker} instance. It helps implementing keyboard
  * navigation in HTML forms, toolbars, lists and the like.
@@ -25,7 +25,7 @@ declare const FocusCycler_base: {
  * A simple cycler setup can look like this:
  *
  * ```ts
- * const focusables = new ViewCollection();
+ * const focusables = new ViewCollection<FocusableView>();
  * const focusTracker = new FocusTracker();
  *
  * // Add focusable views to the focus tracker.
@@ -66,9 +66,9 @@ declare const FocusCycler_base: {
  */
 export default class FocusCycler extends FocusCycler_base {
     /**
-     * A {@link module:ui/view~View view} collection that the cycler operates on.
+     * A {@link module:ui/focuscycler~FocusableView focusable views} collection that the cycler operates on.
      */
-    readonly focusables: ViewCollection;
+    readonly focusables: ViewCollection<FocusableView>;
     /**
      * A focus tracker instance that the cycler uses to determine the current focus
      * state in {@link #focusables}.
@@ -102,7 +102,7 @@ export default class FocusCycler extends FocusCycler_base {
      * @param options Configuration options.
      */
     constructor(options: {
-        focusables: ViewCollection;
+        focusables: ViewCollection<FocusableView>;
         focusTracker: FocusTracker;
         keystrokeHandler?: KeystrokeHandler;
         actions?: FocusCyclerActions;
@@ -178,10 +178,10 @@ export default class FocusCycler extends FocusCycler_base {
      *
      * @param step Either `1` for checking forward from {@link #current} or `-1` for checking backwards.
      */
-    private _getFocusableItem;
+    private _getDomFocusableItem;
 }
 /**
- * A view that can be focused.
+ * A {@link module:ui/view~View} that can be focused (e.g. has `focus()` method).
  */
 export type FocusableView = View & {
     /**
@@ -197,6 +197,13 @@ export type FocusableView = View & {
      */
     focus(direction?: 1 | -1): void;
 };
+/**
+ * A {@link module:ui/view~View} that hosts one or more of focusable children being managed by a {@link module:ui/focuscycler~FocusCycler}
+ * instance exposed under `focusCycler` property.
+ */
+export type ViewWithFocusCycler = FocusableView & {
+    focusCycler: FocusCycler;
+};
 export interface FocusCyclerActions {
     focusFirst?: ArrayOrItem<string>;
     focusLast?: ArrayOrItem<string>;
@@ -223,4 +230,16 @@ export type FocusCyclerBackwardCycleEvent = {
     name: 'backwardCycle';
     args: [];
 };
+/**
+ * Checks whether a view is {@link ~FocusableView}.
+ *
+ * @param view A view to be checked.
+ */
+export declare function isFocusable(view: View): view is FocusableView;
+/**
+ * Checks whether a view is an instance of {@link ~ViewWithFocusCycler}.
+ *
+ * @param view A view to be checked.
+ */
+export declare function isViewWithFocusCycler(view: View): view is ViewWithFocusCycler;
 export {};

package/src/focuscycler.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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
  */
 /**
@@ -7,7 +7,7 @@
  */
 import { isVisible, EmitterMixin } from '@ckeditor/ckeditor5-utils';
 /**
- * A utility class that helps cycling over focusable {@link module:ui/view~View views} in a
+ * A utility class that helps cycling over {@link module:ui/focuscycler~FocusableView focusable views} in a
  * {@link module:ui/viewcollection~ViewCollection} when the focus is tracked by the
  * {@link module:utils/focustracker~FocusTracker} instance. It helps implementing keyboard
  * navigation in HTML forms, toolbars, lists and the like.
@@ -19,7 +19,7 @@ import { isVisible, EmitterMixin } from '@ckeditor/ckeditor5-utils';
  * A simple cycler setup can look like this:
  *
  * ```ts
- * const focusables = new ViewCollection();
+ * const focusables = new ViewCollection<FocusableView>();
  * const focusTracker = new FocusTracker();
  *
  * // Add focusable views to the focus tracker.
@@ -94,7 +94,7 @@ export default class FocusCycler extends EmitterMixin() {
      * **Note**: Hidden views (e.g. with `display: none`) are ignored.
      */
     get first() {
-        return (this.focusables.find(isFocusable) || null);
+        return (this.focusables.find(isDomFocusable) || null);
     }
     /**
      * Returns the last focusable view in {@link #focusables}.
@@ -103,7 +103,7 @@ export default class FocusCycler extends EmitterMixin() {
      * **Note**: Hidden views (e.g. with `display: none`) are ignored.
      */
     get last() {
-        return (this.focusables.filter(isFocusable).slice(-1)[0] || null);
+        return (this.focusables.filter(isDomFocusable).slice(-1)[0] || null);
     }
     /**
      * Returns the next focusable view in {@link #focusables} based on {@link #current}.
@@ -112,7 +112,7 @@ export default class FocusCycler extends EmitterMixin() {
      * **Note**: Hidden views (e.g. with `display: none`) are ignored.
      */
     get next() {
-        return this._getFocusableItem(1);
+        return this._getDomFocusableItem(1);
     }
     /**
      * Returns the previous focusable view in {@link #focusables} based on {@link #current}.
@@ -121,7 +121,7 @@ export default class FocusCycler extends EmitterMixin() {
      * **Note**: Hidden views (e.g. with `display: none`) are ignored.
      */
     get previous() {
-        return this._getFocusableItem(-1);
+        return this._getDomFocusableItem(-1);
     }
     /**
      * An index of the view in the {@link #focusables} which is focused according
@@ -165,7 +165,12 @@ export default class FocusCycler extends EmitterMixin() {
      */
     focusNext() {
         const next = this.next;
+        // If there's only one focusable item, we need to let the outside world know
+        // that the next cycle is about to happen. This may be useful
+        // e.g. if you want to move the focus to the parent focus cycler.
+        // Note that the focus is not actually moved in this case.
         if (next && this.focusables.getIndex(next) === this.current) {
+            this.fire('forwardCycle');
             return;
         }
         if (next === this.first) {
@@ -183,6 +188,7 @@ export default class FocusCycler extends EmitterMixin() {
     focusPrevious() {
         const previous = this.previous;
         if (previous && this.focusables.getIndex(previous) === this.current) {
+            this.fire('backwardCycle');
             return;
         }
         if (previous === this.last) {
@@ -200,7 +206,11 @@ export default class FocusCycler extends EmitterMixin() {
      * @returns
      */
     _focus(view, direction) {
-        if (view) {
+        // Don't fire focus events if the view is already focused.
+        // Such attempt may occur when cycling with only one focusable item:
+        // even though `focusNext()` method returns without changing focus,
+        // the `forwardCycle` event is fired, triggering the `focusFirst()` method.
+        if (view && this.focusTracker.focusedElement !== view.element) {
             view.focus(direction);
         }
     }
@@ -210,36 +220,55 @@ export default class FocusCycler extends EmitterMixin() {
      *
      * @param step Either `1` for checking forward from {@link #current} or `-1` for checking backwards.
      */
-    _getFocusableItem(step) {
+    _getDomFocusableItem(step) {
         // Cache for speed.
-        const current = this.current;
         const collectionLength = this.focusables.length;
         if (!collectionLength) {
             return null;
         }
+        const current = this.current;
         // Start from the beginning if no view is focused.
         // https://github.com/ckeditor/ckeditor5-ui/issues/206
         if (current === null) {
             return this[step === 1 ? 'first' : 'last'];
         }
+        // Note: If current is the only focusable view, it will also be returned for the given step.
+        let focusableItem = this.focusables.get(current);
         // Cycle in both directions.
         let index = (current + collectionLength + step) % collectionLength;
         do {
-            const view = this.focusables.get(index);
-            if (isFocusable(view)) {
-                return view;
+            const focusableItemCandidate = this.focusables.get(index);
+            if (isDomFocusable(focusableItemCandidate)) {
+                focusableItem = focusableItemCandidate;
+                break;
             }
             // Cycle in both directions.
             index = (index + collectionLength + step) % collectionLength;
         } while (index !== current);
-        return null;
+        return focusableItem;
     }
 }
 /**
- * Checks whether a view is focusable.
+ * Checks whether a view can be focused (has `focus()` method and is visible).
+ *
+ * @param view A view to be checked.
+ */
+function isDomFocusable(view) {
+    return isFocusable(view) && isVisible(view.element);
+}
+/**
+ * Checks whether a view is {@link ~FocusableView}.
+ *
+ * @param view A view to be checked.
+ */
+export function isFocusable(view) {
+    return !!('focus' in view && typeof view.focus == 'function');
+}
+/**
+ * Checks whether a view is an instance of {@link ~ViewWithFocusCycler}.
  *
  * @param view A view to be checked.
  */
-function isFocusable(view) {
-    return !!('focus' in view && isVisible(view.element));
+export function isViewWithFocusCycler(view) {
+    return isFocusable(view) && 'focusCycler' in view && view.focusCycler instanceof FocusCycler;
 }

package/src/formheader/formheaderview.d.ts

@@ -1,13 +1,13 @@
 /**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * @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/formheader/formheaderview
  */
-import View from '../view';
-import type ViewCollection from '../viewcollection';
-import IconView from '../icon/iconview';
+import View from '../view.js';
+import type ViewCollection from '../viewcollection.js';
+import IconView from '../icon/iconview.js';
 import type { Locale } from '@ckeditor/ckeditor5-utils';
 import '../../theme/components/formheader/formheader.css';
 /**