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

package/src/bindings/submithandler.js

@@ -2,43 +2,42 @@
  * @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/bindings/submithandler
- */
 /**
  * A handler useful for {@link module:ui/view~View views} working as HTML forms. It intercepts a native DOM
  * `submit` event, prevents the default web browser behavior (navigation and page reload) and
  * fires the `submit` event on a view instead. Such a custom event can be then used by any
  * {@link module:utils/dom/emittermixin~Emitter emitter}, e.g. to serialize the form data.
  *
- *		import submitHandler from '@ckeditor/ckeditor5-ui/src/bindings/submithandler';
+ * ```ts
+ * import submitHandler from '@ckeditor/ckeditor5-ui/src/bindings/submithandler';
  *
- *		// ...
+ * // ...
  *
- *		class AnyFormView extends View {
- *			constructor() {
- *				super();
+ * class AnyFormView extends View {
+ * 	constructor() {
+ * 		super();
  *
- *				// ...
+ * 		// ...
  *
- *				submitHandler( {
- *					view: this
- *				} );
- *			}
- *		}
+ * 		submitHandler( {
+ * 			view: this
+ * 		} );
+ * 	}
+ * }
  *
- *		// ...
+ * // ...
  *
- *		const view = new AnyFormView();
+ * const view = new AnyFormView();
  *
- *		// A sample listener attached by an emitter working with the view.
- *		this.listenTo( view, 'submit', () => {
- *			saveTheFormData();
- *			hideTheForm();
- *		} );
+ * // A sample listener attached by an emitter working with the view.
+ * this.listenTo( view, 'submit', () => {
+ * 	saveTheFormData();
+ * 	hideTheForm();
+ * } );
+ * ```
  *
- * @param {Object} [options] Configuration options.
- * @param {module:ui/view~View} options.view The view which DOM `submit` events should be handled.
+ * @param options Configuration options.
+ * @param options.view The view which DOM `submit` events should be handled.
  */
 export default function submitHandler({ view }) {
     view.listenTo(view.element, 'submit', (evt, domEvt) => {

package/src/button/button.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @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/button/button
+ */
+/**
+ * The button interface. Implemented by, among others, {@link module:ui/button/buttonview~ButtonView},
+ * {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView} and
+ * {@link module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView}.
+ */
+export default interface Button {
+    /**
+     * The label of the button view visible to the user when {@link #withText} is `true`.
+     * It can also be used to create a {@link #tooltip}.
+     *
+     * @observable
+     */
+    label: string | undefined;
+    /**
+     * (Optional) The keystroke associated with the button, i.e. <kbd>CTRL+B</kbd>,
+     * in the string format compatible with {@link module:utils/keyboard}.
+     *
+     * **Note**: Use {@link module:ui/button/button~Button#withKeystroke} if you want to display
+     * the keystroke information next to the {@link module:ui/button/button~Button#label label}.
+     *
+     * @observable
+     */
+    keystroke: string | undefined;
+    /**
+     * (Optional) Tooltip of the button, i.e. displayed when hovering the button with the mouse cursor.
+     *
+     * * If defined as a `Boolean` (e.g. `true`), then combination of `label` and `keystroke` will be set as a tooltip.
+     * * If defined as a `String`, tooltip will equal the exact text of that `String`.
+     * * If defined as a `Function`, `label` and `keystroke` will be passed to that function, which is to return
+     * a string with the tooltip text.
+     *
+     * ```ts
+     * const view = new ButtonView( locale );
+     * view.tooltip = ( label, keystroke ) => `A tooltip for ${ label } and ${ keystroke }.`
+     * ```
+     *
+     * @observable
+     * @default false
+     */
+    tooltip: boolean | string | ((label: string, keystroke: string | undefined) => string);
+    /**
+     * (Optional) The position of the tooltip. See {@link module:ui/tooltipmanager~TooltipManager}
+     * to learn more about the tooltip system.
+     *
+     * **Note:** It makes sense only when the {@link #tooltip `tooltip` attribute} is defined.
+     *
+     * @observable
+     * @default 's'
+     */
+    tooltipPosition: 's' | 'n' | 'e' | 'w' | 'sw' | 'se';
+    /**
+     * The HTML type of the button.
+     *
+     * @observable
+     * @default 'button'
+     */
+    type: 'button' | 'submit' | 'reset' | 'menu';
+    /**
+     * Controls whether the button view is "on". It makes sense when a feature it represents
+     * is currently active, e.g. a bold button is "on" when the selection is in the bold text.
+     *
+     * To disable the button, use {@link #isEnabled} instead.
+     *
+     * @observable
+     * @default true
+     */
+    isOn: boolean;
+    /**
+     * Controls whether the button view is enabled, i.e. it can be clicked and execute an action.
+     *
+     * To change the "on" state of the button, use {@link #isOn} instead.
+     *
+     * @observable
+     * @default true
+     */
+    isEnabled: boolean;
+    /**
+     * Controls whether the button view is visible. Visible by default, buttons are hidden
+     * using a CSS class.
+     *
+     * @observable
+     * @default true
+     */
+    isVisible: boolean;
+    /**
+     * Controls whether the button view is a toggle button (two–state) for assistive technologies.
+     *
+     * @observable
+     * @default false
+     */
+    isToggleable: boolean;
+    /**
+     * (Optional) Controls whether the label of the button is hidden (e.g. an icon–only button).
+     *
+     * @observable
+     * @default false
+     */
+    withText: boolean;
+    /**
+     * (Optional) Controls whether the keystroke of the button is displayed next to its
+     * {@link module:ui/button/button~Button#label label}.
+     *
+     * **Note**: This property requires a {@link module:ui/button/button~Button#keystroke keystroke}
+     * to be defined in the first place.
+     *
+     * @observable
+     * @default false
+     */
+    withKeystroke: boolean;
+    /**
+     * (Optional) An XML {@link module:ui/icon/iconview~IconView#content content} of the icon.
+     * When defined, an `iconView` should be added to the button.
+     *
+     * @observable
+     */
+    icon: string | undefined;
+    /**
+     * (Optional) Controls the `tabindex` HTML attribute of the button. By default, the button is focusable
+     * but does not included in the <kbd>Tab</kbd> order.
+     *
+     * @observable
+     * @default -1
+     */
+    tabindex: number;
+    /**
+     * (Optional) The additional CSS class set on the button.
+     *
+     * @observable
+     */
+    class: string | undefined;
+    /**
+     * (Optional) The value of the `style` attribute of the label.
+     *
+     * @observable
+     */
+    labelStyle: string | undefined;
+}
+/**
+ * Fired when the button view is clicked. It won't be fired when the button {@link #isEnabled}
+ * is `false`.
+ *
+ * @eventName execute
+ */
+export type ButtonExecuteEvent = {
+    name: 'execute';
+    args: [];
+};

package/src/button/buttonview.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @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/button/buttonview
+ */
+import View from '../view';
+import IconView from '../icon/iconview';
+import type ViewCollection from '../viewcollection';
+import type { default as Button } from './button';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/button/button.css';
+/**
+ * The button view class.
+ *
+ * ```ts
+ * const view = new ButtonView();
+ *
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true,
+ * 	withText: true
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ */
+export default class ButtonView extends View<HTMLButtonElement> implements Button {
+    /**
+     * Collection of the child views inside of the button {@link #element}.
+     */
+    readonly children: ViewCollection;
+    /**
+     * Label of the button view. It is configurable using the {@link #label label attribute}.
+     */
+    readonly labelView: View;
+    /**
+     * The icon view of the button. Will be added to {@link #children} when the
+     * {@link #icon icon attribute} is defined.
+     */
+    readonly iconView: IconView;
+    /**
+     * A view displaying the keystroke of the button next to the {@link #labelView label}.
+     * Added to {@link #children} when the {@link #withKeystroke `withKeystroke` attribute}
+     * is defined.
+     */
+    readonly keystrokeView: View;
+    /**
+     * @inheritDoc
+     */
+    class: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    labelStyle: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    icon: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    isEnabled: boolean;
+    /**
+     * @inheritDoc
+     */
+    isOn: boolean;
+    /**
+     * @inheritDoc
+     */
+    isVisible: boolean;
+    /**
+     * @inheritDoc
+     */
+    isToggleable: boolean;
+    /**
+     * @inheritDoc
+     */
+    keystroke: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    label: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    tabindex: number;
+    /**
+     * @inheritDoc
+     */
+    tooltip: Button['tooltip'];
+    /**
+     * @inheritDoc
+     */
+    tooltipPosition: Button['tooltipPosition'];
+    /**
+     * @inheritDoc
+     */
+    type: Button['type'];
+    /**
+     * @inheritDoc
+     */
+    withText: boolean;
+    /**
+     * @inheritDoc
+     */
+    withKeystroke: boolean;
+    /**
+     * Tooltip of the button bound to the template.
+     *
+     * @see #tooltip
+     * @see #_getTooltipString
+     * @internal
+     * @observable
+     */
+    _tooltipString: string;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the {@link #element} of the button.
+     */
+    focus(): void;
+    /**
+     * Creates a label view instance and binds it with button attributes.
+     *
+     * @param ariaLabelUid The aria label UID.
+     */
+    private _createLabelView;
+    /**
+     * Creates a view that displays a keystroke next to a {@link #labelView label }
+     * and binds it with button attributes.
+     */
+    private _createKeystrokeView;
+    /**
+     * Gets the text for the tooltip from the combination of
+     * {@link #tooltip}, {@link #label} and {@link #keystroke} attributes.
+     *
+     * @see #tooltip
+     * @see #_tooltipString
+     * @param tooltip Button tooltip.
+     * @param label Button label.
+     * @param keystroke Button keystroke.
+     */
+    private _getTooltipString;
+}

package/src/button/buttonview.js

@@ -12,21 +12,20 @@ import '../../theme/components/button/button.css';
 /**
  * The button view class.
  *
- *		const view = new ButtonView();
+ * ```ts
+ * const view = new ButtonView();
  *
- *		view.set( {
- *			label: 'A button',
- *			keystroke: 'Ctrl+B',
- *			tooltip: true,
- *			withText: true
- *		} );
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true,
+ * 	withText: true
+ * } );
  *
- *		view.render();
+ * view.render();
  *
- *		document.body.append( view.element );
- *
- * @extends module:ui/view~View
- * @implements module:ui/button/button~Button
+ * document.body.append( view.element );
+ * ```
  */
 export default class ButtonView extends View {
     /**
@@ -52,51 +51,15 @@ export default class ButtonView extends View {
         this.set('type', 'button');
         this.set('withText', false);
         this.set('withKeystroke', false);
-        /**
-         * Collection of the child views inside of the button {@link #element}.
-         *
-         * @readonly
-         * @member {module:ui/viewcollection~ViewCollection}
-         */
         this.children = this.createCollection();
-        /**
-         * Label of the button view. It is configurable using the {@link #label label attribute}.
-         *
-         * @readonly
-         * @member {module:ui/view~View} #labelView
-         */
         this.labelView = this._createLabelView(ariaLabelUid);
-        /**
-         * The icon view of the button. Will be added to {@link #children} when the
-         * {@link #icon icon attribute} is defined.
-         *
-         * @readonly
-         * @member {module:ui/icon/iconview~IconView} #iconView
-         */
         this.iconView = new IconView();
         this.iconView.extendTemplate({
             attributes: {
                 class: 'ck-button__icon'
             }
         });
-        /**
-         * A view displaying the keystroke of the button next to the {@link #labelView label}.
-         * Added to {@link #children} when the {@link #withKeystroke `withKeystroke` attribute}
-         * is defined.
-         *
-         * @readonly
-         * @member {module:ui/view/view~View} #keystrokeView
-         */
         this.keystrokeView = this._createKeystrokeView();
-        /**
-         * Tooltip of the button bound to the template.
-         *
-         * @see #tooltip
-         * @see #_getTooltipString
-         * @private
-         * @observable
-         * @member {String|undefined} #_tooltipString
-         */
         this.bind('_tooltipString').to(this, 'tooltip', this, 'label', this, 'keystroke', this._getTooltipString.bind(this));
         const template = {
             tag: 'button',
@@ -168,9 +131,7 @@ export default class ButtonView extends View {
     /**
      * Creates a label view instance and binds it with button attributes.
      *
-     * @private
-     * @param {String} ariaLabelUid The aria label UID.
-     * @returns {module:ui/view~View}
+     * @param ariaLabelUid The aria label UID.
      */
     _createLabelView(ariaLabelUid) {
         const labelView = new View();
@@ -187,7 +148,7 @@ export default class ButtonView extends View {
             },
             children: [
                 {
-                    text: this.bindTemplate.to('label')
+                    text: bind.to('label')
                 }
             ]
         });
@@ -196,9 +157,6 @@ export default class ButtonView extends View {
     /**
      * Creates a view that displays a keystroke next to a {@link #labelView label }
      * and binds it with button attributes.
-     *
-     * @private
-     * @returns {module:ui/view~View}
      */
     _createKeystrokeView() {
         const keystrokeView = new View();
@@ -222,13 +180,11 @@ export default class ButtonView extends View {
      * Gets the text for the tooltip from the combination of
      * {@link #tooltip}, {@link #label} and {@link #keystroke} attributes.
      *
-     * @private
      * @see #tooltip
      * @see #_tooltipString
-     * @param {Boolean|String|Function} tooltip Button tooltip.
-     * @param {String} label Button label.
-     * @param {String} keystroke Button keystroke.
-     * @returns {String}
+     * @param tooltip Button tooltip.
+     * @param label Button label.
+     * @param keystroke Button keystroke.
      */
     _getTooltipString(tooltip, label, keystroke) {
         if (tooltip) {

package/src/button/switchbuttonview.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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/button/switchbuttonview
+ */
+import View from '../view';
+import ButtonView from './buttonview';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/button/switchbutton.css';
+/**
+ * The switch button view class.
+ *
+ * ```ts
+ * const view = new SwitchButtonView();
+ *
+ * view.set( {
+ * 	withText: true,
+ * 	label: 'Switch me!'
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ */
+export default class SwitchButtonView extends ButtonView {
+    /**
+     * The toggle switch of the button.
+     */
+    readonly toggleSwitchView: View;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Creates a toggle child view.
+     */
+    private _createToggleView;
+}

package/src/button/switchbuttonview.js

@@ -11,18 +11,18 @@ import '../../theme/components/button/switchbutton.css';
 /**
  * The switch button view class.
  *
- *		const view = new SwitchButtonView();
+ * ```ts
+ * const view = new SwitchButtonView();
  *
- *		view.set( {
- *			withText: true,
- *			label: 'Switch me!'
- *		} );
+ * view.set( {
+ * 	withText: true,
+ * 	label: 'Switch me!'
+ * } );
  *
- *		view.render();
+ * view.render();
  *
- *		document.body.append( view.element );
- *
- * @extends module:ui/button/buttonview~ButtonView
+ * document.body.append( view.element );
+ * ```
  */
 export default class SwitchButtonView extends ButtonView {
     /**
@@ -31,12 +31,6 @@ export default class SwitchButtonView extends ButtonView {
     constructor(locale) {
         super(locale);
         this.isToggleable = true;
-        /**
-         * The toggle switch of the button.
-         *
-         * @readonly
-         * @member {module:ui/view~View} #toggleSwitchView
-         */
         this.toggleSwitchView = this._createToggleView();
         this.extendTemplate({
             attributes: {
@@ -53,9 +47,6 @@ export default class SwitchButtonView extends ButtonView {
     }
     /**
      * Creates a toggle child view.
-     *
-     * @private
-     * @returns {module:ui/view~View}
      */
     _createToggleView() {
         const toggleSwitchView = new View();