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

package/src/dropdown/dropdownview.js

@@ -14,20 +14,22 @@ import '../../theme/components/dropdown/dropdown.css';
  * In most cases, the easiest way to create a dropdown is by using the {@link module:ui/dropdown/utils~createDropdown}
  * util:
  *
- *		const dropdown = createDropdown( locale );
+ * ```ts
+ * const dropdown = createDropdown( locale );
  *
- *		// Configure dropdown's button properties:
- *		dropdown.buttonView.set( {
- *			label: 'A dropdown',
- *			withText: true
- *		} );
+ * // Configure dropdown's button properties:
+ * dropdown.buttonView.set( {
+ * 	label: 'A dropdown',
+ * 	withText: true
+ * } );
  *
- *		dropdown.render();
+ * dropdown.render();
  *
- *		dropdown.panelView.element.textContent = 'Content of the panel';
+ * dropdown.panelView.element.textContent = 'Content of the panel';
  *
- *		// Will render a dropdown with a panel containing a "Content of the panel" text.
- *		document.body.appendChild( dropdown.element );
+ * // Will render a dropdown with a panel containing a "Content of the panel" text.
+ * document.body.appendChild( dropdown.element );
+ * ```
  *
  * If you want to add a richer content to the dropdown panel, you can use the {@link module:ui/dropdown/utils~addListToDropdown}
  * and {@link module:ui/dropdown/utils~addToolbarToDropdown} helpers. See more examples in
@@ -35,28 +37,28 @@ import '../../theme/components/dropdown/dropdown.css';
  *
  * If you want to create a completely custom dropdown, then you can compose it manually:
  *
- *		const button = new DropdownButtonView( locale );
- *		const panel = new DropdownPanelView( locale );
- *		const dropdown = new DropdownView( locale, button, panel );
+ * ```ts
+ * const button = new DropdownButtonView( locale );
+ * const panel = new DropdownPanelView( locale );
+ * const dropdown = new DropdownView( locale, button, panel );
  *
- *		button.set( {
- *			label: 'A dropdown',
- *			withText: true
- *		} );
+ * button.set( {
+ * 	label: 'A dropdown',
+ * 	withText: true
+ * } );
  *
- *		dropdown.render();
+ * dropdown.render();
  *
- *		panel.element.textContent = 'Content of the panel';
+ * panel.element.textContent = 'Content of the panel';
  *
- *		// Will render a dropdown with a panel containing a "Content of the panel" text.
- *		document.body.appendChild( dropdown.element );
+ * // Will render a dropdown with a panel containing a "Content of the panel" text.
+ * document.body.appendChild( dropdown.element );
+ * ```
  *
  * However, dropdown created this way will contain little behavior. You will need to implement handlers for actions
  * such as {@link module:ui/bindings/clickoutsidehandler~clickOutsideHandler clicking outside an open dropdown}
  * (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.
- *
- * @extends module:ui/view~View
  */
 export default class DropdownView extends View {
     /**
@@ -64,102 +66,19 @@ export default class DropdownView extends View {
      *
      * Also see {@link #render}.
      *
-     * @param {module:utils/locale~Locale} [locale] The localization services instance.
-     * @param {module:ui/dropdown/button/dropdownbutton~DropdownButton} buttonView
-     * @param {module:ui/dropdown/dropdownpanelview~DropdownPanelView} panelView
+     * @param locale The localization services instance.
      */
     constructor(locale, buttonView, panelView) {
         super(locale);
         const bind = this.bindTemplate;
-        /**
-         * Button of the dropdown view. Clicking the button opens the {@link #panelView}.
-         *
-         * @readonly
-         * @member {module:ui/button/buttonview~ButtonView} #buttonView
-         */
         this.buttonView = buttonView;
-        /**
-         * Panel of the dropdown. It opens when the {@link #buttonView} is
-         * {@link module:ui/button/buttonview~ButtonView#event:execute executed} (i.e. clicked).
-         *
-         * Child views can be added to the panel's `children` collection:
-         *
-         *		dropdown.panelView.children.add( childView );
-         *
-         * See {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#children} and
-         * {@link module:ui/viewcollection~ViewCollection#add}.
-         *
-         * @readonly
-         * @member {module:ui/dropdown/dropdownpanelview~DropdownPanelView} #panelView
-         */
         this.panelView = panelView;
-        /**
-         * Controls whether the dropdown view is open, i.e. shows or hides the {@link #panelView panel}.
-         *
-         * **Note**: When the dropdown gets open, it will attempt to call `focus()` on the first child of its {@link #panelView}.
-         * See {@link module:ui/dropdown/utils~addToolbarToDropdown}, {@link module:ui/dropdown/utils~addListToDropdown}, and
-         * {@link module:ui/dropdown/utils~focusChildOnDropdownOpen} to learn more about focus management in dropdowns.
-         *
-         * @observable
-         * @member {Boolean} #isOpen
-         */
         this.set('isOpen', false);
-        /**
-         * Controls whether the dropdown is enabled, i.e. it can be clicked and execute an action.
-         *
-         * See {@link module:ui/button/buttonview~ButtonView#isEnabled}.
-         *
-         * @observable
-         * @member {Boolean} #isEnabled
-         */
         this.set('isEnabled', true);
-        /**
-         * (Optional) The additional CSS class set on the dropdown {@link #element}.
-         *
-         * @observable
-         * @member {String} #class
-         */
         this.set('class', undefined);
-        /**
-         * (Optional) The `id` attribute of the dropdown (i.e. to pair with a `<label>` element).
-         *
-         * @observable
-         * @member {String} #id
-         */
         this.set('id', undefined);
-        /**
-         * The position of the panel, relative to the dropdown.
-         *
-         * **Note**: When `'auto'`, the panel will use one of the remaining positions to stay
-         * in the viewport, visible to the user. The positions correspond directly to
-         * {@link module:ui/dropdown/dropdownview~DropdownView.defaultPanelPositions default panel positions}.
-         *
-         * **Note**: This value has an impact on the
-         * {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#position} property
-         * each time the panel becomes {@link #isOpen open}.
-         *
-         * @observable
-         * @default 'auto'
-         * @member {'auto'|'s'|'se'|'sw'|'sme'|'smw'|'n'|'ne'|'nw'|'nme'|'nmw'} #panelPosition
-         */
         this.set('panelPosition', 'auto');
-        /**
-         * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}. It manages
-         * keystrokes of the dropdown:
-         *
-         * * <kbd>▼</kbd> opens the dropdown,
-         * * <kbd>◀</kbd> and <kbd>Esc</kbd> closes the dropdown.
-         *
-         * @readonly
-         * @member {module:utils/keystrokehandler~KeystrokeHandler}
-         */
         this.keystrokes = new KeystrokeHandler();
-        /**
-         * Tracks information about the DOM focus in the dropdown.
-         *
-         * @readonly
-         * @member {module:utils/focustracker~FocusTracker}
-         */
         this.focusTracker = new FocusTracker();
         this.setTemplate({
             tag: 'div',
@@ -186,38 +105,6 @@ export default class DropdownView extends View {
                 'data-cke-tooltip-disabled': bind.to('isOpen')
             }
         });
-        /**
-         * A child {@link module:ui/list/listview~ListView list view} of the dropdown located
-         * in its {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel}.
-         *
-         * **Note**: Only supported when dropdown has list view added using {@link module:ui/dropdown/utils~addListToDropdown}.
-         *
-         * @readonly
-         * @member {module:ui/list/listview~ListView} #listView
-         */
-        /**
-         * A child toolbar of the dropdown located in the
-         * {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel}.
-         *
-         * **Note**: Only supported when dropdown has list view added using {@link module:ui/dropdown/utils~addToolbarToDropdown}.
-         *
-         * @readonly
-         * @member {module:ui/toolbar/toolbarview~ToolbarView} #toolbarView
-         */
-        /**
-         * Fired when the toolbar button or list item is executed.
-         *
-         * For {@link #listView} It fires when a child of some {@link module:ui/list/listitemview~ListItemView}
-         * fired `execute`.
-         *
-         * For {@link #toolbarView} It fires when one of the buttons has been
-         * {@link module:ui/button/buttonview~ButtonView#event:execute executed}.
-         *
-         * **Note**: Only supported when dropdown has list view added using {@link module:ui/dropdown/utils~addListToDropdown}
-         * or {@link module:ui/dropdown/utils~addToolbarToDropdown}.
-         *
-         * @event execute
-         */
     }
     /**
      * @inheritDoc
@@ -288,9 +175,6 @@ export default class DropdownView extends View {
      * Returns {@link #panelView panel} positions to be used by the
      * {@link module:utils/dom/position~getOptimalPosition `getOptimalPosition()`}
      * utility considering the direction of the language the UI of the editor is displayed in.
-     *
-     * @type {module:utils/dom/position~Options#positions}
-     * @private
      */
     get _panelPositions() {
         const { south, north, southEast, southWest, northEast, northWest, southMiddleEast, southMiddleWest, northMiddleEast, northMiddleWest } = DropdownView.defaultPanelPositions;
@@ -320,84 +204,102 @@ export default class DropdownView extends View {
  *
  * * `south`
  *
+ * ```
  *			[ Button ]
-*		+-----------------+
-*		|      Panel      |
-*		+-----------------+
-*
-* * `southEast`
-*
-*		[ Button ]
-*		+-----------------+
-*		|      Panel      |
-*		+-----------------+
-*
-* * `southWest`
-*
-*		         [ Button ]
-*		+-----------------+
-*		|      Panel      |
-*		+-----------------+
-*
-* * `southMiddleEast`
-*
-*		  [ Button ]
-*		+-----------------+
-*		|      Panel      |
-*		+-----------------+
-*
-* * `southMiddleWest`
-*
-*		       [ Button ]
-*		+-----------------+
-*		|      Panel      |
-*		+-----------------+
-*
-* **North**
-*
-* * `north`
-*
-*		+-----------------+
-*		|      Panel      |
-*		+-----------------+
-*		    [ Button ]
-*
-* * `northEast`
-*
-*		+-----------------+
-*		|      Panel      |
-*		+-----------------+
-*		[ Button ]
-*
-* * `northWest`
-*
-*		+-----------------+
-*		|      Panel      |
-*		+-----------------+
-*		         [ Button ]
-*
-* * `northMiddleEast`
-*
-*		+-----------------+
-*		|      Panel      |
-*		+-----------------+
-*		  [ Button ]
-*
-* * `northMiddleWest`
-*
-*		+-----------------+
-*		|      Panel      |
-*		+-----------------+
-*		       [ Button ]
-*
-* Positioning functions are compatible with {@link module:utils/dom/position~Position}.
-*
-* 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}
-* to learn more.
-*
-* @member {Object} module:ui/dropdown/dropdownview~DropdownView.defaultPanelPositions
-*/
+ *		+-----------------+
+ *		|      Panel      |
+ *		+-----------------+
+ * ```
+ *
+ * * `southEast`
+ *
+ * ```
+ *		[ Button ]
+ *		+-----------------+
+ *		|      Panel      |
+ *		+-----------------+
+ * ```
+ *
+ * * `southWest`
+ *
+ * ```
+ *		         [ Button ]
+ *		+-----------------+
+ *		|      Panel      |
+ *		+-----------------+
+ * ```
+ *
+ * * `southMiddleEast`
+ *
+ * ```
+ *		  [ Button ]
+ *		+-----------------+
+ *		|      Panel      |
+ *		+-----------------+
+ * ```
+ *
+ * * `southMiddleWest`
+ *
+ * ```
+ *		       [ Button ]
+ *		+-----------------+
+ *		|      Panel      |
+ *		+-----------------+
+ * ```
+ *
+ * **North**
+ *
+ * * `north`
+ *
+ * ```
+ *		+-----------------+
+ *		|      Panel      |
+ *		+-----------------+
+ *		    [ Button ]
+ * ```
+ *
+ * * `northEast`
+ *
+ * ```
+ *		+-----------------+
+ *		|      Panel      |
+ *		+-----------------+
+ *		[ Button ]
+ * ```
+ *
+ * * `northWest`
+ *
+ * ```
+ *		+-----------------+
+ *		|      Panel      |
+ *		+-----------------+
+ *		         [ Button ]
+ * ```
+ *
+ * * `northMiddleEast`
+ *
+ * ```
+ *		+-----------------+
+ *		|      Panel      |
+ *		+-----------------+
+ *		  [ Button ]
+ * ```
+ *
+ * * `northMiddleWest`
+ *
+ * ```
+ *		+-----------------+
+ *		|      Panel      |
+ *		+-----------------+
+ *		       [ Button ]
+ * ```
+ *
+ * Positioning functions are compatible with {@link module:utils/dom/position~Position}.
+ *
+ * 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}
+ * to learn more.
+ */
 DropdownView.defaultPanelPositions = {
     south: (buttonRect, panelRect) => {
         return {
@@ -472,8 +374,5 @@ DropdownView.defaultPanelPositions = {
 };
 /**
  * A function used to calculate the optimal position for the dropdown panel.
- *
- * @protected
- * @member {Function} module:ui/dropdown/dropdownview~DropdownView._getOptimalPosition
  */
 DropdownView._getOptimalPosition = getOptimalPosition;

package/src/dropdown/utils.d.ts

@@ -0,0 +1,219 @@
+/**
+ * @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
+ */
+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 { type Collection, type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/dropdown/toolbardropdown.css';
+import '../../theme/components/dropdown/listdropdown.css';
+/**
+ * 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},
+ * {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView panel} and all standard dropdown's behaviors.
+ *
+ * # Creating dropdowns
+ *
+ * By default, the default {@link module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView} class is used as
+ * definition of the button:
+ *
+ * ```ts
+ * const dropdown = createDropdown( model );
+ *
+ * // Configure dropdown's button properties:
+ * dropdown.buttonView.set( {
+ * 	label: 'A dropdown',
+ * 	withText: true
+ * } );
+ *
+ * dropdown.render();
+ *
+ * // Will render a dropdown labeled "A dropdown" with an empty panel.
+ * document.body.appendChild( dropdown.element );
+ * ```
+ *
+ * You can also provide other button views (they need to implement the
+ * {@link module:ui/dropdown/button/dropdownbutton~DropdownButton} interface). For instance, you can use
+ * {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView} to create a dropdown with a split button.
+ *
+ * ```ts
+ * const dropdown = createDropdown( locale, SplitButtonView );
+ *
+ * // Configure dropdown's button properties:
+ * dropdown.buttonView.set( {
+ * 	label: 'A dropdown',
+ * 	withText: true
+ * } );
+ *
+ * dropdown.buttonView.on( 'execute', () => {
+ * 	// Add the behavior of the "action part" of the split button.
+ * 	// Split button consists of the "action part" and "arrow part".
+ * 	// The arrow opens the dropdown while the action part can have some other behavior.
+ * } );
+ *
+ * dropdown.render();
+ *
+ * // Will render a dropdown labeled "A dropdown" with an empty panel.
+ * document.body.appendChild( dropdown.element );
+ * ```
+ *
+ * # Adding content to the dropdown's panel
+ *
+ * The content of the panel can be inserted directly into the `dropdown.panelView.element`:
+ *
+ * ```ts
+ * dropdown.panelView.element.textContent = 'Content of the panel';
+ * ```
+ *
+ * However, most of the time you will want to add there either a {@link module:ui/list/listview~ListView list of options}
+ * or a list of buttons (i.e. a {@link module:ui/toolbar/toolbarview~ToolbarView toolbar}).
+ * To simplify the task, you can use, respectively, {@link module:ui/dropdown/utils~addListToDropdown} or
+ * {@link module:ui/dropdown/utils~addToolbarToDropdown} utils.
+ *
+ * @param locale The locale instance.
+ * @param ButtonClass The dropdown button view class. Needs to implement the
+ * {@link module:ui/dropdown/button/dropdownbutton~DropdownButton} interface.
+ * @returns The dropdown view instance.
+ */
+export declare function createDropdown(locale: Locale | undefined, ButtonClass?: new (locale?: Locale) => DropdownButton & FocusableView): DropdownView;
+/**
+ * Adds an instance of {@link module:ui/toolbar/toolbarview~ToolbarView} to a dropdown.
+ *
+ * ```ts
+ * const buttonsCreator = () => {
+ * 	const buttons = [];
+ *
+ * 	// Either create a new ButtonView instance or create existing.
+ * 	buttons.push( new ButtonView() );
+ * 	buttons.push( editor.ui.componentFactory.create( 'someButton' ) );
+ * };
+ *
+ * const dropdown = createDropdown( locale );
+ *
+ * addToolbarToDropdown( dropdown, buttonsCreator, { isVertical: true } );
+ *
+ * // Will render a vertical button dropdown labeled "A button dropdown"
+ * // with a button group in the panel containing two buttons.
+ * // Buttons inside the dropdown will be created on first dropdown panel open.
+ * dropdown.render()
+ * document.body.appendChild( dropdown.element );
+ * ```
+ *
+ * **Note:** To improve the accessibility, you can tell the dropdown to focus the first active button of the toolbar when the dropdown
+ * {@link module:ui/dropdown/dropdownview~DropdownView#isOpen gets open}. See the documentation of `options` to learn more.
+ *
+ * **Note:** Toolbar view will be created on first open of the dropdown.
+ *
+ * See {@link module:ui/dropdown/utils~createDropdown} and {@link module:ui/toolbar/toolbarview~ToolbarView}.
+ *
+ * @param dropdownView A dropdown instance to which `ToolbarView` will be added.
+ * @param options.enableActiveItemFocusOnDropdownOpen When set `true`, the focus will automatically move to the first
+ * active {@link module:ui/toolbar/toolbarview~ToolbarView#items item} of the toolbar upon
+ * {@link module:ui/dropdown/dropdownview~DropdownView#isOpen opening} the dropdown. Active items are those with the `isOn` property set
+ * `true` (for instance {@link module:ui/button/buttonview~ButtonView buttons}). If no active items is found, the toolbar will be focused
+ * as a whole resulting in the focus moving to its first focusable item (default behavior of
+ * {@link module:ui/dropdown/dropdownview~DropdownView}).
+ * @param options.ariaLabel Label used by assistive technologies to describe toolbar element.
+ * @param options.maxWidth The maximum width of the toolbar element.
+ * Details: {@link module:ui/toolbar/toolbarview~ToolbarView#maxWidth}.
+ * @param options.class An additional CSS class added to the toolbar element.
+ * @param options.isCompact When set true, makes the toolbar look compact with toolbar element.
+ * @param options.isVertical Controls the orientation of toolbar items.
+ */
+export declare function addToolbarToDropdown(dropdownView: DropdownView, buttonsOrCallback: Array<View> | ViewCollection | (() => Array<View> | ViewCollection), options?: {
+    enableActiveItemFocusOnDropdownOpen?: boolean;
+    ariaLabel?: string;
+    maxWidth?: string;
+    class?: string;
+    isCompact?: boolean;
+    isVertical?: boolean;
+}): void;
+/**
+ * Adds an instance of {@link module:ui/list/listview~ListView} to a dropdown.
+ *
+ * ```ts
+ * const items = new Collection();
+ *
+ * items.add( {
+ * 	type: 'button',
+ * 	model: new Model( {
+ * 		withText: true,
+ * 		label: 'First item',
+ * 		labelStyle: 'color: red'
+ * 	} )
+ * } );
+ *
+ * items.add( {
+ * 	 type: 'button',
+ * 	 model: new Model( {
+ * 		withText: true,
+ * 		label: 'Second item',
+ * 		labelStyle: 'color: green',
+ * 		class: 'foo'
+ * 	} )
+ * } );
+ *
+ * const dropdown = createDropdown( locale );
+ *
+ * addListToDropdown( dropdown, items );
+ *
+ * // Will render a dropdown with a list in the panel containing two items.
+ * dropdown.render()
+ * document.body.appendChild( dropdown.element );
+ * ```
+ *
+ * The `items` collection passed to this methods controls the presence and attributes of respective
+ * {@link module:ui/list/listitemview~ListItemView list items}.
+ *
+ * **Note:** To improve the accessibility, when a list is added to the dropdown using this helper the dropdown will automatically attempt
+ * to focus the first active item (a host to a {@link module:ui/button/buttonview~ButtonView} with
+ * {@link module:ui/button/buttonview~ButtonView#isOn} set `true`) or the very first item when none are active.
+ *
+ * **Note:** List view will be created on first open of the dropdown.
+ *
+ * See {@link module:ui/dropdown/utils~createDropdown} and {@link module:list/list~List}.
+ *
+ * @param dropdownView A dropdown instance to which `ListVIew` will be added.
+ * @param itemsOrCallback A collection of the list item definitions or a callback returning a list item definitions to populate the list.
+ * @param options.ariaLabel Label used by assistive technologies to describe list element.
+ */
+export declare function addListToDropdown(dropdownView: DropdownView, itemsOrCallback: Collection<ListDropdownItemDefinition> | (() => Collection<ListDropdownItemDefinition>), options?: {
+    ariaLabel?: string;
+}): void;
+/**
+ * A helper to be used on an existing {@link module:ui/dropdown/dropdownview~DropdownView} that focuses
+ * a specific child in DOM when the dropdown {@link module:ui/dropdown/dropdownview~DropdownView#isOpen gets open}.
+ *
+ * @param dropdownView A dropdown instance to which the focus behavior will be added.
+ * @param childSelectorCallback A callback executed when the dropdown gets open. It should return a {@link module:ui/view~View}
+ * instance (child of {@link module:ui/dropdown/dropdownview~DropdownView#panelView}) that will get focused or a falsy value.
+ * If falsy value is returned, a default behavior of the dropdown will engage focusing the first focusable child in
+ * the {@link module:ui/dropdown/dropdownview~DropdownView#panelView}.
+ */
+export declare function focusChildOnDropdownOpen(dropdownView: DropdownView, childSelectorCallback: () => View | FalsyValue): void;
+/**
+ * A definition of the list item used by the {@link module:ui/dropdown/utils~addListToDropdown}
+ * utility.
+ */
+export type ListDropdownItemDefinition = ListDropdownSeparatorDefinition | ListDropdownButtonDefinition;
+/**
+ * A definition of the 'separator' list item.
+ */
+export type ListDropdownSeparatorDefinition = {
+    type: 'separator';
+};
+/**
+ * A definition of the 'button' or 'switchbutton' list item.
+ */
+export type ListDropdownButtonDefinition = {
+    type: 'button' | 'switchbutton';
+    /**
+     * Model of the item. Its properties fuel the newly created list item (or its children, depending on the `type`).
+     */
+    model: Model;
+};