@ckeditor/ckeditor5-ui 39.0.2 → 40.0.0

package/src/focuscycler.js

@@ -1,220 +1,245 @@
-/**
- * @license Copyright (c) 2003-2023, 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 { isVisible } from '@ckeditor/ckeditor5-utils';
-/**
- * A utility class that helps cycling over focusable {@link module:ui/view~View 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.
- *
- * To work properly it requires:
- * * a collection of focusable (HTML `tabindex` attribute) views that implement the `focus()` method,
- * * an associated focus tracker to determine which view is focused.
- *
- * A simple cycler setup can look like this:
- *
- * ```ts
- * const focusables = new ViewCollection();
- * const focusTracker = new FocusTracker();
- *
- * // Add focusable views to the focus tracker.
- * focusTracker.add( ... );
- * ```
- *
- * Then, the cycler can be used manually:
- *
- * ```ts
- * const cycler = new FocusCycler( { focusables, focusTracker } );
- *
- * // Will focus the first focusable view in #focusables.
- * cycler.focusFirst();
- *
- * // Will log the next focusable item in #focusables.
- * console.log( cycler.next );
- * ```
- *
- * Alternatively, it can work side by side with the {@link module:utils/keystrokehandler~KeystrokeHandler}:
- *
- * ```ts
- * const keystrokeHandler = new KeystrokeHandler();
- *
- * // Activate the keystroke handler.
- * keystrokeHandler.listenTo( sourceOfEvents );
- *
- * const cycler = new FocusCycler( {
- * 	focusables, focusTracker, keystrokeHandler,
- * 	actions: {
- * 		// When arrowup of arrowleft is detected by the #keystrokeHandler,
- * 		// focusPrevious() will be called on the cycler.
- * 		focusPrevious: [ 'arrowup', 'arrowleft' ],
- * 	}
- * } );
- * ```
- *
- * Check out the {@glink framework/deep-dive/ui/focus-tracking "Deep dive into focus tracking"} guide to learn more.
- */
-export default class FocusCycler {
-    /**
-     * Creates an instance of the focus cycler utility.
-     *
-     * @param options Configuration options.
-     */
-    constructor(options) {
-        this.focusables = options.focusables;
-        this.focusTracker = options.focusTracker;
-        this.keystrokeHandler = options.keystrokeHandler;
-        this.actions = options.actions;
-        if (options.actions && options.keystrokeHandler) {
-            for (const methodName in options.actions) {
-                let actions = options.actions[methodName];
-                if (typeof actions == 'string') {
-                    actions = [actions];
-                }
-                for (const keystroke of actions) {
-                    options.keystrokeHandler.set(keystroke, (data, cancel) => {
-                        this[methodName]();
-                        cancel();
-                    });
-                }
-            }
-        }
-    }
-    /**
-     * Returns the first focusable view in {@link #focusables}.
-     * Returns `null` if there is none.
-     *
-     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     */
-    get first() {
-        return (this.focusables.find(isFocusable) || null);
-    }
-    /**
-     * Returns the last focusable view in {@link #focusables}.
-     * Returns `null` if there is none.
-     *
-     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     */
-    get last() {
-        return (this.focusables.filter(isFocusable).slice(-1)[0] || null);
-    }
-    /**
-     * Returns the next focusable view in {@link #focusables} based on {@link #current}.
-     * Returns `null` if there is none.
-     *
-     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     */
-    get next() {
-        return this._getFocusableItem(1);
-    }
-    /**
-     * Returns the previous focusable view in {@link #focusables} based on {@link #current}.
-     * Returns `null` if there is none.
-     *
-     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     */
-    get previous() {
-        return this._getFocusableItem(-1);
-    }
-    /**
-     * An index of the view in the {@link #focusables} which is focused according
-     * to {@link #focusTracker}. Returns `null` when there is no such view.
-     */
-    get current() {
-        let index = null;
-        // There's no focused view in the focusables.
-        if (this.focusTracker.focusedElement === null) {
-            return null;
-        }
-        this.focusables.find((view, viewIndex) => {
-            const focused = view.element === this.focusTracker.focusedElement;
-            if (focused) {
-                index = viewIndex;
-            }
-            return focused;
-        });
-        return index;
-    }
-    /**
-     * Focuses the {@link #first} item in {@link #focusables}.
-     *
-     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     */
-    focusFirst() {
-        this._focus(this.first);
-    }
-    /**
-     * Focuses the {@link #last} item in {@link #focusables}.
-     *
-     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     */
-    focusLast() {
-        this._focus(this.last);
-    }
-    /**
-     * Focuses the {@link #next} item in {@link #focusables}.
-     *
-     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     */
-    focusNext() {
-        this._focus(this.next);
-    }
-    /**
-     * Focuses the {@link #previous} item in {@link #focusables}.
-     *
-     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     */
-    focusPrevious() {
-        this._focus(this.previous);
-    }
-    /**
-     * Focuses the given view if it exists.
-     */
-    _focus(view) {
-        if (view) {
-            view.focus();
-        }
-    }
-    /**
-     * Returns the next or previous focusable view in {@link #focusables} with respect
-     * to {@link #current}.
-     *
-     * @param step Either `1` for checking forward from {@link #current} or `-1` for checking backwards.
-     */
-    _getFocusableItem(step) {
-        // Cache for speed.
-        const current = this.current;
-        const collectionLength = this.focusables.length;
-        if (!collectionLength) {
-            return null;
-        }
-        // 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'];
-        }
-        // Cycle in both directions.
-        let index = (current + collectionLength + step) % collectionLength;
-        do {
-            const view = this.focusables.get(index);
-            if (isFocusable(view)) {
-                return view;
-            }
-            // Cycle in both directions.
-            index = (index + collectionLength + step) % collectionLength;
-        } while (index !== current);
-        return null;
-    }
-}
-/**
- * Checks whether a view is focusable.
- *
- * @param view A view to be checked.
- */
-function isFocusable(view) {
-    return !!(view.focus && isVisible(view.element));
-}
+/**
+ * @license Copyright (c) 2003-2023, 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 { isVisible, EmitterMixin } from '@ckeditor/ckeditor5-utils';
+/**
+ * A utility class that helps cycling over focusable {@link module:ui/view~View 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.
+ *
+ * To work properly it requires:
+ * * a collection of focusable (HTML `tabindex` attribute) views that implement the `focus()` method,
+ * * an associated focus tracker to determine which view is focused.
+ *
+ * A simple cycler setup can look like this:
+ *
+ * ```ts
+ * const focusables = new ViewCollection();
+ * const focusTracker = new FocusTracker();
+ *
+ * // Add focusable views to the focus tracker.
+ * focusTracker.add( ... );
+ * ```
+ *
+ * Then, the cycler can be used manually:
+ *
+ * ```ts
+ * const cycler = new FocusCycler( { focusables, focusTracker } );
+ *
+ * // Will focus the first focusable view in #focusables.
+ * cycler.focusFirst();
+ *
+ * // Will log the next focusable item in #focusables.
+ * console.log( cycler.next );
+ * ```
+ *
+ * Alternatively, it can work side by side with the {@link module:utils/keystrokehandler~KeystrokeHandler}:
+ *
+ * ```ts
+ * const keystrokeHandler = new KeystrokeHandler();
+ *
+ * // Activate the keystroke handler.
+ * keystrokeHandler.listenTo( sourceOfEvents );
+ *
+ * const cycler = new FocusCycler( {
+ * 	focusables, focusTracker, keystrokeHandler,
+ * 	actions: {
+ * 		// When arrowup of arrowleft is detected by the #keystrokeHandler,
+ * 		// focusPrevious() will be called on the cycler.
+ * 		focusPrevious: [ 'arrowup', 'arrowleft' ],
+ * 	}
+ * } );
+ * ```
+ *
+ * Check out the {@glink framework/deep-dive/ui/focus-tracking "Deep dive into focus tracking"} guide to learn more.
+ */
+export default class FocusCycler extends EmitterMixin() {
+    /**
+     * Creates an instance of the focus cycler utility.
+     *
+     * @param options Configuration options.
+     */
+    constructor(options) {
+        super();
+        this.focusables = options.focusables;
+        this.focusTracker = options.focusTracker;
+        this.keystrokeHandler = options.keystrokeHandler;
+        this.actions = options.actions;
+        if (options.actions && options.keystrokeHandler) {
+            for (const methodName in options.actions) {
+                let actions = options.actions[methodName];
+                if (typeof actions == 'string') {
+                    actions = [actions];
+                }
+                for (const keystroke of actions) {
+                    options.keystrokeHandler.set(keystroke, (data, cancel) => {
+                        this[methodName]();
+                        cancel();
+                    });
+                }
+            }
+        }
+        this.on('forwardCycle', () => this.focusFirst(), { priority: 'low' });
+        this.on('backwardCycle', () => this.focusLast(), { priority: 'low' });
+    }
+    /**
+     * Returns the first focusable view in {@link #focusables}.
+     * Returns `null` if there is none.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    get first() {
+        return (this.focusables.find(isFocusable) || null);
+    }
+    /**
+     * Returns the last focusable view in {@link #focusables}.
+     * Returns `null` if there is none.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    get last() {
+        return (this.focusables.filter(isFocusable).slice(-1)[0] || null);
+    }
+    /**
+     * Returns the next focusable view in {@link #focusables} based on {@link #current}.
+     * Returns `null` if there is none.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    get next() {
+        return this._getFocusableItem(1);
+    }
+    /**
+     * Returns the previous focusable view in {@link #focusables} based on {@link #current}.
+     * Returns `null` if there is none.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    get previous() {
+        return this._getFocusableItem(-1);
+    }
+    /**
+     * An index of the view in the {@link #focusables} which is focused according
+     * to {@link #focusTracker}. Returns `null` when there is no such view.
+     */
+    get current() {
+        let index = null;
+        // There's no focused view in the focusables.
+        if (this.focusTracker.focusedElement === null) {
+            return null;
+        }
+        this.focusables.find((view, viewIndex) => {
+            const focused = view.element === this.focusTracker.focusedElement;
+            if (focused) {
+                index = viewIndex;
+            }
+            return focused;
+        });
+        return index;
+    }
+    /**
+     * Focuses the {@link #first} item in {@link #focusables}.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    focusFirst() {
+        this._focus(this.first, 1);
+    }
+    /**
+     * Focuses the {@link #last} item in {@link #focusables}.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    focusLast() {
+        this._focus(this.last, -1);
+    }
+    /**
+     * Focuses the {@link #next} item in {@link #focusables}.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    focusNext() {
+        const next = this.next;
+        if (next && this.focusables.getIndex(next) === this.current) {
+            return;
+        }
+        if (next === this.first) {
+            this.fire('forwardCycle');
+        }
+        else {
+            this._focus(next, 1);
+        }
+    }
+    /**
+     * Focuses the {@link #previous} item in {@link #focusables}.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    focusPrevious() {
+        const previous = this.previous;
+        if (previous && this.focusables.getIndex(previous) === this.current) {
+            return;
+        }
+        if (previous === this.last) {
+            this.fire('backwardCycle');
+        }
+        else {
+            this._focus(previous, -1);
+        }
+    }
+    /**
+     * Focuses the given view if it exists.
+     *
+     * @param view The view to be focused
+     * @param direction The direction of the focus if the view has focusable children.
+     * @returns
+     */
+    _focus(view, direction) {
+        if (view) {
+            view.focus(direction);
+        }
+    }
+    /**
+     * Returns the next or previous focusable view in {@link #focusables} with respect
+     * to {@link #current}.
+     *
+     * @param step Either `1` for checking forward from {@link #current} or `-1` for checking backwards.
+     */
+    _getFocusableItem(step) {
+        // Cache for speed.
+        const current = this.current;
+        const collectionLength = this.focusables.length;
+        if (!collectionLength) {
+            return null;
+        }
+        // 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'];
+        }
+        // Cycle in both directions.
+        let index = (current + collectionLength + step) % collectionLength;
+        do {
+            const view = this.focusables.get(index);
+            if (isFocusable(view)) {
+                return view;
+            }
+            // Cycle in both directions.
+            index = (index + collectionLength + step) % collectionLength;
+        } while (index !== current);
+        return null;
+    }
+}
+/**
+ * Checks whether a view is focusable.
+ *
+ * @param view A view to be checked.
+ */
+function isFocusable(view) {
+    return !!('focus' in view && isVisible(view.element));
+}

package/src/formheader/formheaderview.d.ts

@@ -1,53 +1,59 @@
-/**
- * @license Copyright (c) 2003-2023, 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 type { Locale } from '@ckeditor/ckeditor5-utils';
-import '../../theme/components/formheader/formheader.css';
-/**
- * The class component representing a form header view. It should be used in more advanced forms to
- * describe the main purpose of the form.
- *
- * By default the component contains a bolded label view that has to be set. The label is usually a short (at most 3-word) string.
- * The component can also be extended by any other elements, like: icons, dropdowns, etc.
- *
- * It is used i.a.
- * by {@link module:table/tablecellproperties/ui/tablecellpropertiesview~TableCellPropertiesView}
- * and {@link module:special-characters/ui/specialcharactersnavigationview~SpecialCharactersNavigationView}.
- *
- * The latter is an example, where the component has been extended by {@link module:ui/dropdown/dropdownview~DropdownView} view.
- */
-export default class FormHeaderView extends View {
-    /**
-     * A collection of header items.
-     */
-    readonly children: ViewCollection;
-    /**
-     * The label of the header.
-     *
-     * @observable
-     */
-    label: string;
-    /**
-     * An additional CSS class added to the {@link #element}.
-     *
-     * @observable
-     */
-    class: string | null;
-    /**
-     * Creates an instance of the form header class.
-     *
-     * @param locale The locale instance.
-     * @param options.label A label.
-     * @param options.class An additional class.
-     */
-    constructor(locale: Locale | undefined, options?: {
-        label?: string | null;
-        class?: string | null;
-    });
-}
+/**
+ * @license Copyright (c) 2003-2023, 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 type { Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/formheader/formheader.css';
+/**
+ * The class component representing a form header view. It should be used in more advanced forms to
+ * describe the main purpose of the form.
+ *
+ * By default the component contains a bolded label view that has to be set. The label is usually a short (at most 3-word) string.
+ * The component can also be extended by any other elements, like: icons, dropdowns, etc.
+ *
+ * It is used i.a.
+ * by {@link module:table/tablecellproperties/ui/tablecellpropertiesview~TableCellPropertiesView}
+ * and {@link module:special-characters/ui/specialcharactersnavigationview~SpecialCharactersNavigationView}.
+ *
+ * The latter is an example, where the component has been extended by {@link module:ui/dropdown/dropdownview~DropdownView} view.
+ */
+export default class FormHeaderView extends View {
+    /**
+     * A collection of header items.
+     */
+    readonly children: ViewCollection;
+    /**
+     * The label of the header.
+     *
+     * @observable
+     */
+    label: string;
+    /**
+     * An additional CSS class added to the {@link #element}.
+     *
+     * @observable
+     */
+    class: string | null;
+    /**
+     * The icon view instance. Defined only if icon was passed in the constructor's options.
+     */
+    readonly iconView?: IconView;
+    /**
+     * Creates an instance of the form header class.
+     *
+     * @param locale The locale instance.
+     * @param options.label A label.
+     * @param options.class An additional class.
+     */
+    constructor(locale: Locale | undefined, options?: {
+        label?: string | null;
+        class?: string | null;
+        icon?: string | null;
+    });
+}