@ckeditor/ckeditor5-ui 36.0.0 → 37.0.0-alpha.0

package/src/editorui/editoruiview.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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/editorui/editoruiview
+ */
+import View from '../view';
+import BodyCollection from './bodycollection';
+import type EditableUIView from '../editableui/editableuiview';
+import type { Locale, LocaleTranslate } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/editorui/editorui.css';
+/**
+ * The editor UI view class. Base class for the editor main views.
+ */
+export default abstract class EditorUIView extends View {
+    /**
+     * Collection of the child views, detached from the DOM
+     * structure of the editor, like panels, icons etc.
+     */
+    readonly body: BodyCollection;
+    locale: Locale;
+    t: LocaleTranslate;
+    abstract get editable(): EditableUIView;
+    /**
+     * Creates an instance of the editor UI view class.
+     *
+     * @param locale The locale instance.
+     */
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}

package/src/editorui/editoruiview.js

@@ -10,24 +10,15 @@ import BodyCollection from './bodycollection';
 import '../../theme/components/editorui/editorui.css';
 /**
  * The editor UI view class. Base class for the editor main views.
- *
- * @extends module:ui/view~View
  */
 export default class EditorUIView extends View {
     /**
      * Creates an instance of the editor UI view class.
      *
-     * @param {module:utils/locale~Locale} [locale] The locale instance.
+     * @param locale The locale instance.
      */
     constructor(locale) {
         super(locale);
-        /**
-         * Collection of the child views, detached from the DOM
-         * structure of the editor, like panels, icons etc.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection} #body
-         */
         this.body = new BodyCollection(locale);
     }
     /**

package/src/focuscycler.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @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 { type ArrayOrItem, type FocusTracker, type KeystrokeHandler } from '@ckeditor/ckeditor5-utils';
+import type View from './view';
+import type ViewCollection from './viewcollection';
+/**
+ * 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 {
+    /**
+     * A {@link module:ui/view~View view} collection that the cycler operates on.
+     */
+    readonly focusables: ViewCollection;
+    /**
+     * A focus tracker instance that the cycler uses to determine the current focus
+     * state in {@link #focusables}.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}
+     * which can respond to certain keystrokes and cycle the focus.
+     */
+    readonly keystrokeHandler?: KeystrokeHandler;
+    /**
+     * Actions that the cycler can take when a keystroke is pressed. Requires
+     * `options.keystrokeHandler` to be passed and working. When an action is
+     * performed, `preventDefault` and `stopPropagation` will be called on the event
+     * the keystroke fired in the DOM.
+     *
+     * ```ts
+     * actions: {
+     * 	// Will call #focusPrevious() when arrowleft or arrowup is pressed.
+     * 	focusPrevious: [ 'arrowleft', 'arrowup' ],
+     *
+     * 	// Will call #focusNext() when arrowdown is pressed.
+     * 	focusNext: 'arrowdown'
+     * }
+     * ```
+     */
+    readonly actions?: FocusCyclerActions;
+    /**
+     * Creates an instance of the focus cycler utility.
+     *
+     * @param options Configuration options.
+     */
+    constructor(options: {
+        focusables: ViewCollection;
+        focusTracker: FocusTracker;
+        keystrokeHandler?: KeystrokeHandler;
+        actions?: FocusCyclerActions;
+    });
+    /**
+     * 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(): FocusableView | 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(): FocusableView | 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(): FocusableView | null;
+    /**
+     * 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(): FocusableView | null;
+    /**
+     * 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(): number | null;
+    /**
+     * Focuses the {@link #first} item in {@link #focusables}.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    focusFirst(): void;
+    /**
+     * Focuses the {@link #last} item in {@link #focusables}.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    focusLast(): void;
+    /**
+     * Focuses the {@link #next} item in {@link #focusables}.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    focusNext(): void;
+    /**
+     * Focuses the {@link #previous} item in {@link #focusables}.
+     *
+     * **Note**: Hidden views (e.g. with `display: none`) are ignored.
+     */
+    focusPrevious(): void;
+    /**
+     * Focuses the given view if it exists.
+     */
+    private _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.
+     */
+    private _getFocusableItem;
+}
+export type FocusableView = View & {
+    focus(): void;
+};
+export interface FocusCyclerActions {
+    focusFirst?: ArrayOrItem<string>;
+    focusLast?: ArrayOrItem<string>;
+    focusNext?: ArrayOrItem<string>;
+    focusPrevious?: ArrayOrItem<string>;
+}

package/src/focuscycler.js

@@ -18,92 +18,57 @@ import { isVisible } from '@ckeditor/ckeditor5-utils';
  *
  * A simple cycler setup can look like this:
  *
- *		const focusables = new ViewCollection();
- *		const focusTracker = new FocusTracker();
+ * ```ts
+ * const focusables = new ViewCollection();
+ * const focusTracker = new FocusTracker();
  *
- *		// Add focusable views to the focus tracker.
- *		focusTracker.add( ... );
+ * // Add focusable views to the focus tracker.
+ * focusTracker.add( ... );
+ * ```
  *
  * Then, the cycler can be used manually:
  *
- *		const cycler = new FocusCycler( { focusables, focusTracker } );
+ * ```ts
+ * const cycler = new FocusCycler( { focusables, focusTracker } );
  *
- *		// Will focus the first focusable view in #focusables.
- *		cycler.focusFirst();
+ * // Will focus the first focusable view in #focusables.
+ * cycler.focusFirst();
  *
- *		// Will log the next focusable item in #focusables.
- *		console.log( cycler.next );
+ * // 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}:
  *
- *		const keystrokeHandler = new KeystrokeHandler();
+ * ```ts
+ * const keystrokeHandler = new KeystrokeHandler();
  *
- *		// Activate the keystroke handler.
- *		keystrokeHandler.listenTo( sourceOfEvents );
+ * // 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' ],
- *			}
- *		} );
+ * 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/guides/deep-dive/ui/focus-tracking "Deep dive into focus tracking" guide} to learn more.
+ * 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 {Object} options Configuration options.
-     * @param {module:utils/collection~Collection|Object} options.focusables
-     * @param {module:utils/focustracker~FocusTracker} options.focusTracker
-     * @param {module:utils/keystrokehandler~KeystrokeHandler} [options.keystrokeHandler]
-     * @param {Object} [options.actions]
+     * @param options Configuration options.
      */
     constructor(options) {
         this.focusables = options.focusables;
         this.focusTracker = options.focusTracker;
         this.keystrokeHandler = options.keystrokeHandler;
         this.actions = options.actions;
-        /**
-         * A {@link module:ui/view~View view} collection that the cycler operates on.
-         *
-         * @readonly
-         * @member {module:utils/collection~Collection} #focusables
-         */
-        /**
-         * A focus tracker instance that the cycler uses to determine the current focus
-         * state in {@link #focusables}.
-         *
-         * @readonly
-         * @member {module:utils/focustracker~FocusTracker} #focusTracker
-         */
-        /**
-         * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}
-         * which can respond to certain keystrokes and cycle the focus.
-         *
-         * @readonly
-         * @member {module:utils/keystrokehandler~KeystrokeHandler} #keystrokeHandler
-         */
-        /**
-         * Actions that the cycler can take when a keystroke is pressed. Requires
-         * `options.keystrokeHandler` to be passed and working. When an action is
-         * performed, `preventDefault` and `stopPropagation` will be called on the event
-         * the keystroke fired in the DOM.
-         *
-         *		actions: {
-         *			// Will call #focusPrevious() when arrowleft or arrowup is pressed.
-         *			focusPrevious: [ 'arrowleft', 'arrowup' ],
-         *
-         *			// Will call #focusNext() when arrowdown is pressed.
-         *			focusNext: 'arrowdown'
-         *		}
-         *
-         * @readonly
-         * @member {Object} #actions
-         */
         if (options.actions && options.keystrokeHandler) {
             for (const methodName in options.actions) {
                 let actions = options.actions[methodName];
@@ -124,9 +89,6 @@ export default class FocusCycler {
      * Returns `null` if there is none.
      *
      * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     *
-     * @readonly
-     * @member {module:ui/view~View|null} #first
      */
     get first() {
         return (this.focusables.find(isFocusable) || null);
@@ -136,9 +98,6 @@ export default class FocusCycler {
      * Returns `null` if there is none.
      *
      * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     *
-     * @readonly
-     * @member {module:ui/view~View|null} #last
      */
     get last() {
         return (this.focusables.filter(isFocusable).slice(-1)[0] || null);
@@ -148,9 +107,6 @@ export default class FocusCycler {
      * Returns `null` if there is none.
      *
      * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     *
-     * @readonly
-     * @member {module:ui/view~View|null} #next
      */
     get next() {
         return this._getFocusableItem(1);
@@ -160,9 +116,6 @@ export default class FocusCycler {
      * Returns `null` if there is none.
      *
      * **Note**: Hidden views (e.g. with `display: none`) are ignored.
-     *
-     * @readonly
-     * @member {module:ui/view~View|null} #previous
      */
     get previous() {
         return this._getFocusableItem(-1);
@@ -170,9 +123,6 @@ export default class FocusCycler {
     /**
      * An index of the view in the {@link #focusables} which is focused according
      * to {@link #focusTracker}. Returns `null` when there is no such view.
-     *
-     * @readonly
-     * @member {Number|null} #current
      */
     get current() {
         let index = null;
@@ -223,9 +173,6 @@ export default class FocusCycler {
     }
     /**
      * Focuses the given view if it exists.
-     *
-     * @protected
-     * @param {module:ui/view~View} view
      */
     _focus(view) {
         if (view) {
@@ -236,10 +183,7 @@ export default class FocusCycler {
      * Returns the next or previous focusable view in {@link #focusables} with respect
      * to {@link #current}.
      *
-     * @protected
-     * @param {Number} step Either `1` for checking forward from {@link #current} or
-     * `-1` for checking backwards.
-     * @returns {module:ui/view~View|null}
+     * @param step Either `1` for checking forward from {@link #current} or `-1` for checking backwards.
      */
     _getFocusableItem(step) {
         // Cache for speed.
@@ -266,11 +210,11 @@ export default class FocusCycler {
         return null;
     }
 }
-// Checks whether a view is focusable.
-//
-// @private
-// @param {module:ui/view~View} view A view to be checked.
-// @returns {Boolean}
+/**
+ * Checks whether a view is focusable.
+ *
+ * @param view A view to be checked.
+ */
 function isFocusable(view) {
     return !!(view.focus && isVisible(view.element));
 }

package/src/formheader/formheaderview.d.ts

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

package/src/formheader/formheaderview.js

@@ -19,41 +19,20 @@ import '../../theme/components/formheader/formheader.css';
  * 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.
- *
- * @extends module:ui/view~View
  */
 export default class FormHeaderView extends View {
     /**
      * Creates an instance of the form header class.
      *
-     * @param {module:utils/locale~Locale} locale The locale instance.
-     * @param {Object} options
-     * @param {String} options.label A label.
-     * @param {String} [options.class] An additional 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;
-        /**
-         * The label of the header.
-         *
-         * @observable
-         * @member {String} #label
-         */
         this.set('label', options.label || '');
-        /**
-         * An additional CSS class added to the {@link #element}.
-         *
-         * @observable
-         * @member {String} #class
-         */
         this.set('class', options.class || null);
-        /**
-         * A collection of header items.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.children = this.createCollection();
         this.setTemplate({
             tag: 'div',

package/src/icon/iconview.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @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/icon/iconview
+ */
+import View from '../view';
+import '../../theme/components/icon/icon.css';
+/**
+ * The icon view class.
+ */
+export default class IconView extends View {
+    /**
+     * The SVG source of the icon.
+     *
+     * @observable
+     */
+    content: string | undefined;
+    /**
+     * This attribute specifies the boundaries to which the
+     * icon content should stretch.
+     *
+     * @observable
+     * @default '0 0 20 20'
+     */
+    viewBox: string;
+    /**
+     * The fill color of the child `path.ck-icon__fill`.
+     *
+     * @observable
+     * @default ''
+     */
+    fillColor: string;
+    /**
+     * When set true (default), all parts of the icon inherit the fill color from the CSS `color` property of the
+     * icon's DOM parent.
+     *
+     * This effectively makes the icon monochromatic and allows it to change its fill color dynamically, for instance,
+     * when a {@link module:ui/button/buttonview~ButtonView} displays an icon and it switches between different states
+     * (pushed, hovered, etc.) the icon will follow along.
+     *
+     * **Note**: For the monochromatic icon to render properly, it must be made up of shapes that can be filled
+     * with color instead of, for instance, paths with strokes. Be sure to use the *outline stroke* tool
+     * (the name could be different in your vector graphics editor) before exporting your icon. Also, remove any
+     * excess `fill="..."` attributes that could break the color inheritance.
+     *
+     * **Note**: If you want to preserve the original look of your icon and disable dynamic color inheritance,
+     * set this flag to `false`.
+     *
+     * @observable
+     * @default true
+     */
+    isColorInherited: boolean;
+    /**
+     * A list of presentational attributes that can be set on the `<svg>` element and should be preserved
+     * when the icon {@link module:ui/icon/iconview~IconView#content content} is loaded.
+     *
+     * See the [specification](https://www.w3.org/TR/SVG/styling.html#TermPresentationAttribute) to learn more.
+     */
+    private static presentationalAttributeNames;
+    /**
+     * @inheritDoc
+     */
+    constructor();
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Updates the {@link #element} with the value of {@link #content}.
+     */
+    private _updateXMLContent;
+    /**
+     * Fills all child `path.ck-icon__fill` with the `#fillColor`.
+     */
+    private _colorFillPaths;
+}