@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/focuscycler.js

@@ -0,0 +1,352 @@
+/**
+ * @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 { isVisible, EmitterMixin } from '@ckeditor/ckeditor5-utils';
+/**
+ * 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.
+ *
+ * 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<FocusableView>();
+ * 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 /* #__PURE__ */ 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();
+                    }, options.keystrokeHandlerOptions);
+                }
+            }
+        }
+        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(isDomFocusable) || 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(isDomFocusable).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._getDomFocusableItem(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._getDomFocusableItem(-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 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) {
+            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) {
+            this.fire('backwardCycle');
+            return;
+        }
+        if (previous === this.last) {
+            this.fire('backwardCycle');
+        }
+        else {
+            this._focus(previous, -1);
+        }
+    }
+    /**
+     * Allows for creating continuous focus cycling across multiple focus cyclers and their collections of {@link #focusables}.
+     *
+     * It starts listening to the {@link module:ui/focuscycler~FocusCyclerForwardCycleEvent} and
+     * {@link module:ui/focuscycler~FocusCyclerBackwardCycleEvent} events of the chained focus cycler and engages,
+     * whenever the user reaches the last (forwards navigation) or first (backwards navigation) focusable view
+     * and would normally start over. Instead, the navigation continues on the higher level (flattens).
+     *
+     * For instance, for the following nested focus navigation structure, the focus would get stuck the moment
+     * the AB gets focused and its focus cycler starts managing it:
+     *
+     *	   ┌────────────┐   ┌──────────────────────────────────┐   ┌────────────┐
+     *	   │ AA         │   │ AB                               │   │ AC         │
+     *	   │            │   │                                  │   │            │
+     *	   │            │   │    ┌─────┐  ┌─────┐  ┌─────┐     │   │            │
+     *	   │            │   │ ┌──► ABA ├──► ABB ├──► ABC ├───┐ │   │            │
+     *	   │            ├───► │  └─────┘  └─────┘  └─────┘   │ │   │            │
+     *	   │            │   │ │                              │ │   │            │
+     *	   │            │   │ │                              │ │   │            │
+     *	   │            │   │ └──────────────────────────────┘ │   │            │
+     *	   │            │   │                                  │   │            │
+     *	   └────────────┘   └──────────────────────────────────┘   └────────────┘
+     *
+     * Chaining a focus tracker that manages AA, AB, and AC with the focus tracker that manages ABA, ABB, and ABC
+     * creates a seamless navigation experience instead:
+     *
+     *	   ┌────────────┐   ┌──────────────────────────────────┐   ┌────────────┐
+     *	   │ AA         │   │ AB                               │   │ AC         │
+     *	   │            │   │                                  │   │            │
+     *	   │            │   │    ┌─────┐  ┌─────┐  ┌─────┐     │   │            │
+     *	   │            │   │ ┌──► ABA ├──► ABB ├──► ABC ├──┐  │   │            │
+     *	┌──►            ├───┼─┘  └─────┘  └─────┘  └─────┘  └──┼───►            ├──┐
+     *	│  │            │   │                                  │   │            │  │
+     *	│  │            │   │                                  │   │            │  │
+     *	│  │            │   │                                  │   │            │  │
+     *	│  │            │   │                                  │   │            │  │
+     *	│  └────────────┘   └──────────────────────────────────┘   └────────────┘  │
+     *	│                                                                          │
+     *	│                                                                          │
+     *	└──────────────────────────────────────────────────────────────────────────┘
+     *
+     * See {@link #unchain} to reverse the chaining.
+     */
+    chain(chainedFocusCycler) {
+        const getCurrentFocusedView = () => {
+            // This may happen when one focus cycler does not include focusables of the other (horizontal case).
+            if (this.current === null) {
+                return null;
+            }
+            return this.focusables.get(this.current);
+        };
+        this.listenTo(chainedFocusCycler, 'forwardCycle', evt => {
+            const oldCurrent = getCurrentFocusedView();
+            this.focusNext();
+            // Stop the event propagation only if an attempt at focusing the view actually moved the focus.
+            // If not, let the otherFocusCycler handle the event.
+            if (oldCurrent !== getCurrentFocusedView()) {
+                evt.stop();
+            }
+            // The priority is critical for cycling across multiple chain levels when there's a single view at some of them only.
+        }, { priority: 'low' });
+        this.listenTo(chainedFocusCycler, 'backwardCycle', evt => {
+            const oldCurrent = getCurrentFocusedView();
+            this.focusPrevious();
+            // Stop the event propagation only if an attempt at focusing the view actually moved the focus.
+            // If not, let the otherFocusCycler handle the event.
+            if (oldCurrent !== getCurrentFocusedView()) {
+                evt.stop();
+            }
+            // The priority is critical for cycling across multiple chain levels when there's a single view at some of them only.
+        }, { priority: 'low' });
+    }
+    /**
+     * Reverses a chaining made by {@link #chain}.
+     */
+    unchain(otherFocusCycler) {
+        this.stopListening(otherFocusCycler);
+    }
+    /**
+     * 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) {
+        // 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);
+        }
+    }
+    /**
+     * 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.
+     */
+    _getDomFocusableItem(step) {
+        // Cache for speed.
+        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 focusableItemCandidate = this.focusables.get(index);
+            if (isDomFocusable(focusableItemCandidate)) {
+                focusableItem = focusableItemCandidate;
+                break;
+            }
+            // Cycle in both directions.
+            index = (index + collectionLength + step) % collectionLength;
+        } while (index !== current);
+        return focusableItem;
+    }
+}
+/**
+ * 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.
+ */
+export function isViewWithFocusCycler(view) {
+    return isFocusable(view) && 'focusCycler' in view && view.focusCycler instanceof FocusCycler;
+}

package/src/formheader/formheaderview.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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.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';
+/**
+ * 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}.
+ *
+ * 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;
+    });
+}

package/src/formheader/formheaderview.js

@@ -0,0 +1,69 @@
+/**
+ * @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.js';
+import IconView from '../icon/iconview.js';
+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}.
+ *
+ * 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 {
+    /**
+     * 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, options = {}) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set('label', options.label || '');
+        this.set('class', options.class || null);
+        this.children = this.createCollection();
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-form__header',
+                    bind.to('class')
+                ]
+            },
+            children: this.children
+        });
+        if (options.icon) {
+            this.iconView = new IconView();
+            this.iconView.content = options.icon;
+            this.children.add(this.iconView);
+        }
+        const label = new View(locale);
+        label.setTemplate({
+            tag: 'h2',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-form__header__label'
+                ],
+                role: 'presentation'
+            },
+            children: [
+                { text: bind.to('label') }
+            ]
+        });
+        this.children.add(label);
+    }
+}

package/src/highlightedtext/buttonlabelwithhighlightview.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @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/highlightedtext/buttonlabelwithhighlightview
+ */
+import type ButtonLabel from '../button/buttonlabel.js';
+import HighlightedTextView from './highlightedtextview.js';
+/**
+ * A button label view that can highlight a text fragment.
+ */
+export default class ButtonLabelWithHighlightView extends HighlightedTextView implements ButtonLabel {
+    /**
+     * @inheritDoc
+     */
+    style: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    text: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    id: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    constructor();
+}

package/src/highlightedtext/buttonlabelwithhighlightview.js

@@ -0,0 +1,31 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import HighlightedTextView from './highlightedtextview.js';
+/**
+ * A button label view that can highlight a text fragment.
+ */
+export default class ButtonLabelWithHighlightView extends HighlightedTextView {
+    /**
+     * @inheritDoc
+     */
+    constructor() {
+        super();
+        this.set({
+            style: undefined,
+            text: undefined,
+            id: undefined
+        });
+        const bind = this.bindTemplate;
+        this.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-button__label'
+                ],
+                style: bind.to('style'),
+                id: bind.to('id')
+            }
+        });
+    }
+}

package/src/highlightedtext/highlightedtextview.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @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/highlightedtext/highlightedtextview
+ */
+import View from '../view.js';
+import '../../theme/components/highlightedtext/highlightedtext.css';
+/**
+ * A class representing a view that displays a text which subset can be highlighted using the
+ * {@link #highlightText} method.
+ */
+export default class HighlightedTextView extends View {
+    /**
+     * The text that can be highlighted using the {@link #highlightText} method.
+     *
+     * **Note:** When this property changes, the previous highlighting is removed.
+     *
+     * @observable
+     */
+    text: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    constructor();
+    /**
+     * Highlights view's {@link #text} according to the specified `RegExp`. If the passed RegExp is `null`, the
+     * highlighting is removed
+     *
+     * @param regExp
+     */
+    highlightText(regExp: RegExp | null): void;
+    /**
+     * Updates element's `innerHTML` with the passed content.
+     */
+    private _updateInnerHTML;
+}

package/src/highlightedtext/highlightedtextview.js

@@ -0,0 +1,102 @@
+/**
+ * @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/highlightedtext/highlightedtextview
+ */
+import View from '../view.js';
+import { escape } from 'lodash-es';
+import '../../theme/components/highlightedtext/highlightedtext.css';
+/**
+ * A class representing a view that displays a text which subset can be highlighted using the
+ * {@link #highlightText} method.
+ */
+export default class HighlightedTextView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor() {
+        super();
+        this.set('text', undefined);
+        this.setTemplate({
+            tag: 'span',
+            attributes: {
+                class: ['ck', 'ck-highlighted-text']
+            }
+        });
+        this.on('render', () => {
+            // Classic setTemplate binding for #text will not work because highlightText() replaces the
+            // pre-rendered DOM text node new a new one (and <mark> elements).
+            this.on('change:text', () => {
+                this._updateInnerHTML(this.text);
+            });
+            this._updateInnerHTML(this.text);
+        });
+    }
+    /**
+     * Highlights view's {@link #text} according to the specified `RegExp`. If the passed RegExp is `null`, the
+     * highlighting is removed
+     *
+     * @param regExp
+     */
+    highlightText(regExp) {
+        this._updateInnerHTML(markText(this.text || '', regExp));
+    }
+    /**
+     * Updates element's `innerHTML` with the passed content.
+     */
+    _updateInnerHTML(newInnerHTML) {
+        this.element.innerHTML = newInnerHTML || '';
+    }
+}
+/**
+ * Replaces `regExp` occurrences with `<mark>` tags in a text.
+ *
+ * @param text A text to get marked.
+ * @param regExp An optional `RegExp`. If not passed, this is a pass-through function.
+ * @returns A text with `RegExp` occurrences marked by `<mark>`.
+ */
+function markText(text, regExp) {
+    if (!regExp) {
+        return escape(text);
+    }
+    const textParts = [];
+    let lastMatchEnd = 0;
+    let matchInfo = regExp.exec(text);
+    // Iterate over all matches and create an array of text parts. The idea is to mark which parts are query matches
+    // so that later on they can be highlighted.
+    while (matchInfo !== null) {
+        const curMatchStart = matchInfo.index;
+        // Detect if there was something between last match and this one.
+        if (curMatchStart !== lastMatchEnd) {
+            textParts.push({
+                text: text.substring(lastMatchEnd, curMatchStart),
+                isMatch: false
+            });
+        }
+        textParts.push({
+            text: matchInfo[0],
+            isMatch: true
+        });
+        lastMatchEnd = regExp.lastIndex;
+        matchInfo = regExp.exec(text);
+    }
+    // Your match might not be the last part of a string. Be sure to add any plain text following the last match.
+    if (lastMatchEnd !== text.length) {
+        textParts.push({
+            text: text.substring(lastMatchEnd),
+            isMatch: false
+        });
+    }
+    const outputHtml = textParts
+        // The entire text should be escaped.
+        .map(part => {
+        part.text = escape(part.text);
+        return part;
+    })
+        // Only matched text should be wrapped with HTML mark element.
+        .map(part => part.isMatch ? `<mark>${part.text}</mark>` : part.text)
+        .join('');
+    return outputHtml;
+}