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

package/src/dropdown/button/dropdownbuttonview.js

@@ -6,27 +6,26 @@
  * @module ui/dropdown/button/dropdownbuttonview
  */
 import ButtonView from '../../button/buttonview';
-import dropdownArrowIcon from '../../../theme/icons/dropdown-arrow.svg';
 import IconView from '../../icon/iconview';
+import dropdownArrowIcon from '../../../theme/icons/dropdown-arrow.svg';
 /**
  * The default dropdown button view class.
  *
- *		const view = new DropdownButtonView();
+ * ```ts
+ * const view = new DropdownButtonView();
  *
- *		view.set( {
- *			label: 'A button',
- *			keystroke: 'Ctrl+B',
- *			tooltip: true
- *		} );
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true
+ * } );
  *
- *		view.render();
+ * view.render();
  *
- *		document.body.append( view.element );
+ * document.body.append( view.element );
+ * ```
  *
  * Also see the {@link module:ui/dropdown/utils~createDropdown `createDropdown()` util}.
- *
- * @implements module:ui/dropdown/button/dropdownbutton~DropdownButton
- * @extends module:ui/button/buttonview~ButtonView
  */
 export default class DropdownButtonView extends ButtonView {
     /**
@@ -34,12 +33,6 @@ export default class DropdownButtonView extends ButtonView {
      */
     constructor(locale) {
         super(locale);
-        /**
-         * An icon that displays arrow to indicate a dropdown button.
-         *
-         * @readonly
-         * @member {module:ui/icon/iconview~IconView}
-         */
         this.arrowView = this._createArrowView();
         this.extendTemplate({
             attributes: {
@@ -59,9 +52,6 @@ export default class DropdownButtonView extends ButtonView {
     }
     /**
      * Creates a {@link module:ui/icon/iconview~IconView} instance as {@link #arrowView}.
-     *
-     * @private
-     * @returns {module:ui/icon/iconview~IconView}
      */
     _createArrowView() {
         const arrowView = new IconView();

package/src/dropdown/button/splitbuttonview.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @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/dropdown/button/splitbuttonview
+ */
+import View from '../../view';
+import ButtonView from '../../button/buttonview';
+import type ViewCollection from '../../viewcollection';
+import type Button from '../../button/button';
+import type DropdownButton from './dropdownbutton';
+import { KeystrokeHandler, FocusTracker, type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../../theme/components/dropdown/splitbutton.css';
+/**
+ * The split button view class.
+ *
+ * ```ts
+ * const view = new SplitButtonView();
+ *
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ *
+ * Also see the {@link module:ui/dropdown/utils~createDropdown `createDropdown()` util}.
+ */
+export default class SplitButtonView extends View<HTMLDivElement> implements DropdownButton {
+    /**
+     * Collection of the child views inside of the split button {@link #element}.
+     */
+    readonly children: ViewCollection;
+    /**
+     * A main button of split button.
+     */
+    readonly actionView: ButtonView;
+    /**
+     * A secondary button of split button that opens dropdown.
+     */
+    readonly arrowView: ButtonView;
+    /**
+     * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}. It manages
+     * keystrokes of the split button:
+     *
+     * * <kbd>▶</kbd> moves focus to arrow view when action view is focused,
+     * * <kbd>◀</kbd> moves focus to action view when arrow view is focused.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Tracks information about DOM focus in the dropdown.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * @inheritDoc
+     */
+    label: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    keystroke: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    tooltip: Button['tooltip'];
+    /**
+     * @inheritDoc
+     */
+    tooltipPosition: Button['tooltipPosition'];
+    /**
+     * @inheritDoc
+     */
+    type: Button['type'];
+    /**
+     * @inheritDoc
+     */
+    isOn: boolean;
+    /**
+     * @inheritDoc
+     */
+    isEnabled: boolean;
+    /**
+     * @inheritDoc
+     */
+    isVisible: boolean;
+    /**
+     * @inheritDoc
+     */
+    isToggleable: boolean;
+    /**
+     * @inheritDoc
+     */
+    withText: boolean;
+    /**
+     * @inheritDoc
+     */
+    withKeystroke: boolean;
+    /**
+     * @inheritDoc
+     */
+    icon: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    tabindex: number;
+    /**
+     * @inheritDoc
+     */
+    class: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    labelStyle: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the {@link module:ui/button/buttonview~ButtonView#element} of the action part of split button.
+     */
+    focus(): void;
+    /**
+     * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #actionView} and binds it with main split button
+     * attributes.
+     */
+    private _createActionView;
+    /**
+     * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #arrowView} and binds it with main split button
+     * attributes.
+     */
+    private _createArrowView;
+}

package/src/dropdown/button/splitbuttonview.js

@@ -13,22 +13,21 @@ import '../../../theme/components/dropdown/splitbutton.css';
 /**
  * The split button view class.
  *
- *		const view = new SplitButtonView();
+ * ```ts
+ * const view = new SplitButtonView();
  *
- *		view.set( {
- *			label: 'A button',
- *			keystroke: 'Ctrl+B',
- *			tooltip: true
- *		} );
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true
+ * } );
  *
- *		view.render();
+ * view.render();
  *
- *		document.body.append( view.element );
+ * document.body.append( view.element );
+ * ```
  *
  * Also see the {@link module:ui/dropdown/utils~createDropdown `createDropdown()` util}.
- *
- * @implements module:ui/dropdown/button/dropdownbutton~DropdownButton
- * @extends module:ui/view~View
  */
 export default class SplitButtonView extends View {
     /**
@@ -53,44 +52,10 @@ export default class SplitButtonView extends View {
         this.set('tooltipPosition', 's');
         this.set('type', 'button');
         this.set('withText', false);
-        /**
-         * Collection of the child views inside of the split button {@link #element}.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.children = this.createCollection();
-        /**
-         * A main button of split button.
-         *
-         * @readonly
-         * @member {module:ui/button/buttonview~ButtonView}
-         */
         this.actionView = this._createActionView();
-        /**
-         * A secondary button of split button that opens dropdown.
-         *
-         * @readonly
-         * @member {module:ui/button/buttonview~ButtonView}
-         */
         this.arrowView = this._createArrowView();
-        /**
-         * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}. It manages
-         * keystrokes of the split button:
-         *
-         * * <kbd>▶</kbd> moves focus to arrow view when action view is focused,
-         * * <kbd>◀</kbd> moves focus to action view when arrow view is focused.
-         *
-         * @readonly
-         * @member {module:utils/keystrokehandler~KeystrokeHandler}
-         */
         this.keystrokes = new KeystrokeHandler();
-        /**
-         * Tracks information about DOM focus in the dropdown.
-         *
-         * @readonly
-         * @member {module:utils/focustracker~FocusTracker}
-         */
         this.focusTracker = new FocusTracker();
         this.setTemplate({
             tag: 'div',
@@ -140,7 +105,7 @@ export default class SplitButtonView extends View {
         this.keystrokes.destroy();
     }
     /**
-     * Focuses the {@link #actionView#element} of the action part of split button.
+     * Focuses the {@link module:ui/button/buttonview~ButtonView#element} of the action part of split button.
      */
     focus() {
         this.actionView.focus();
@@ -148,9 +113,6 @@ export default class SplitButtonView extends View {
     /**
      * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #actionView} and binds it with main split button
      * attributes.
-     *
-     * @private
-     * @returns {module:ui/button/buttonview~ButtonView}
      */
     _createActionView() {
         const actionView = new ButtonView();
@@ -166,9 +128,6 @@ export default class SplitButtonView extends View {
     /**
      * Creates a {@link module:ui/button/buttonview~ButtonView} instance as {@link #arrowView} and binds it with main split button
      * attributes.
-     *
-     * @private
-     * @returns {module:ui/button/buttonview~ButtonView}
      */
     _createArrowView() {
         const arrowView = new ButtonView();

package/src/dropdown/dropdownpanelfocusable.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @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/dropdown/dropdownpanelfocusable
+ */
+/**
+ * The dropdown panel interface for focusable contents. It provides two methods for managing focus of the contents
+ * of dropdown's panel.
+ */
+export default interface DropdownPanelFocusable {
+    /**
+     * Focuses the view element or first item in view collection on opening dropdown's panel.
+     */
+    focus(): void;
+    /**
+     * Focuses the view element or last item in view collection on opening dropdown's panel.
+     */
+    focusLast(): void;
+}

package/src/dropdown/dropdownpanelview.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @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/dropdown/dropdownpanelview
+ */
+import View from '../view';
+import type ViewCollection from '../viewcollection';
+import type DropdownPanelFocusable from './dropdownpanelfocusable';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The dropdown panel view class.
+ *
+ * See {@link module:ui/dropdown/dropdownview~DropdownView} to learn about the common usage.
+ */
+export default class DropdownPanelView extends View implements DropdownPanelFocusable {
+    /**
+     * Collection of the child views in this panel.
+     *
+     * A common child type is the {@link module:ui/list/listview~ListView} and {@link module:ui/toolbar/toolbarview~ToolbarView}.
+     * See {@link module:ui/dropdown/utils~addListToDropdown} and
+     * {@link module:ui/dropdown/utils~addToolbarToDropdown} to learn more about child views of dropdowns.
+     */
+    readonly children: ViewCollection;
+    /**
+     * Controls whether the panel is visible.
+     *
+     * @observable
+     */
+    isVisible: boolean;
+    /**
+     * The position of the panel, relative to the parent.
+     *
+     * This property is reflected in the CSS class set to {@link #element} that controls
+     * the position of the panel.
+     *
+     * @observable
+     * @default 'se'
+     */
+    position: PanelPosition;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * Focuses the first view in the {@link #children} collection.
+     *
+     * See also {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable}.
+     */
+    focus(): void;
+    /**
+     * Focuses the view element or last item in view collection on opening dropdown's panel.
+     *
+     * See also {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable}.
+     */
+    focusLast(): void;
+}
+/**
+ * The position of the panel, relative to the parent.
+ */
+export type PanelPosition = 's' | 'se' | 'sw' | 'sme' | 'smw' | 'n' | 'ne' | 'nw' | 'nme' | 'nmw';

package/src/dropdown/dropdownpanelview.js

@@ -11,8 +11,6 @@ import { logWarning } from '@ckeditor/ckeditor5-utils';
  * The dropdown panel view class.
  *
  * See {@link module:ui/dropdown/dropdownview~DropdownView} to learn about the common usage.
- *
- * @extends module:ui/view~View
  */
 export default class DropdownPanelView extends View {
     /**
@@ -21,34 +19,8 @@ export default class DropdownPanelView extends View {
     constructor(locale) {
         super(locale);
         const bind = this.bindTemplate;
-        /**
-         * Controls whether the panel is visible.
-         *
-         * @observable
-         * @member {Boolean} #isVisible
-         */
         this.set('isVisible', false);
-        /**
-         * The position of the panel, relative to the parent.
-         *
-         * This property is reflected in the CSS class set to {@link #element} that controls
-         * the position of the panel.
-         *
-         * @observable
-         * @default 'se'
-         * @member {'s'|'se'|'sw'|'sme'|'smw'|'n'|'ne'|'nw'|'nme'|'nmw'} #position
-         */
         this.set('position', 'se');
-        /**
-         * Collection of the child views in this panel.
-         *
-         * A common child type is the {@link module:ui/list/listview~ListView} and {@link module:ui/toolbar/toolbarview~ToolbarView}.
-         * See {@link module:ui/dropdown/utils~addListToDropdown} and
-         * {@link module:ui/dropdown/utils~addToolbarToDropdown} to learn more about child views of dropdowns.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.children = this.createCollection();
         this.setTemplate({
             tag: 'div',
@@ -93,8 +65,8 @@ export default class DropdownPanelView extends View {
                  * provides the `focus()` method for the best user experience.
                  *
                  * @error ui-dropdown-panel-focus-child-missing-focus
-                 * @param {module:ui/view~View} childView
-                 * @param {module:ui/dropdown/dropdownpanelview~DropdownPanelView} dropdownPanel
+                 * @param childView
+                 * @param dropdownPanel
                  */
                 logWarning('ui-dropdown-panel-focus-child-missing-focus', { childView: this.children.first, dropdownPanel: this });
             }