@ckeditor/ckeditor5-ui 34.2.0 → 35.1.0

package/src/button/buttonview.js

@@ -9,10 +9,10 @@
 
 import View from '../view';
 import IconView from '../icon/iconview';
-import TooltipView from '../tooltip/tooltipview';
 
 import uid from '@ckeditor/ckeditor5-utils/src/uid';
 import { getEnvKeystrokeText } from '@ckeditor/ckeditor5-utils/src/keyboard';
+import env from '@ckeditor/ckeditor5-utils/src/env';
 
 import '../../theme/components/button/button.css';
 
@@ -70,14 +70,6 @@ export default class ButtonView extends View {
 		 */
 		this.children = this.createCollection();
 
-		/**
-		 * Tooltip of the button view. It is configurable using the {@link #tooltip tooltip attribute}.
-		 *
-		 * @readonly
-		 * @member {module:ui/tooltip/tooltipview~TooltipView} #tooltipView
-		 */
-		this.tooltipView = this._createTooltipView();
-
 		/**
 		 * Label of the button view. It is configurable using the {@link #label label attribute}.
 		 *
@@ -118,7 +110,7 @@ export default class ButtonView extends View {
 		 * @see #_getTooltipString
 		 * @private
 		 * @observable
-		 * @member {Boolean} #_tooltipString
+		 * @member {String|undefined} #_tooltipString
 		 */
 		this.bind( '_tooltipString' ).to(
 			this, 'tooltip',
@@ -127,7 +119,7 @@ export default class ButtonView extends View {
 			this._getTooltipString.bind( this )
 		);
 
-		this.setTemplate( {
+		const template = {
 			tag: 'button',
 
 			attributes: {
@@ -145,16 +137,14 @@ export default class ButtonView extends View {
 				tabindex: bind.to( 'tabindex' ),
 				'aria-labelledby': `ck-editor__aria-label_${ ariaLabelUid }`,
 				'aria-disabled': bind.if( 'isEnabled', true, value => !value ),
-				'aria-pressed': bind.to( 'isOn', value => this.isToggleable ? String( value ) : false )
+				'aria-pressed': bind.to( 'isOn', value => this.isToggleable ? String( !!value ) : false ),
+				'data-cke-tooltip-text': bind.to( '_tooltipString' ),
+				'data-cke-tooltip-position': bind.to( 'tooltipPosition' )
 			},
 
 			children: this.children,
 
 			on: {
-				mousedown: bind.to( evt => {
-					evt.preventDefault();
-				} ),
-
 				click: bind.to( evt => {
 					// We can't make the button disabled using the disabled attribute, because it won't be focusable.
 					// Though, shouldn't this condition be moved to the button controller?
@@ -167,7 +157,18 @@ export default class ButtonView extends View {
 					}
 				} )
 			}
-		} );
+		};
+
+		// On Safari we have to force the focus on a button on click as it's the only browser
+		// that doesn't do that automatically. See #12115.
+		if ( env.isSafari ) {
+			template.on.mousedown = bind.to( evt => {
+				this.focus();
+				evt.preventDefault();
+			} );
+		}
+
+		this.setTemplate( template );
 	}
 
 	/**
@@ -181,7 +182,6 @@ export default class ButtonView extends View {
 			this.children.add( this.iconView );
 		}
 
-		this.children.add( this.tooltipView );
 		this.children.add( this.labelView );
 
 		if ( this.withKeystroke && this.keystroke ) {
@@ -196,22 +196,6 @@ export default class ButtonView extends View {
 		this.element.focus();
 	}
 
-	/**
-	 * Creates a {@link module:ui/tooltip/tooltipview~TooltipView} instance and binds it with button
-	 * attributes.
-	 *
-	 * @private
-	 * @returns {module:ui/tooltip/tooltipview~TooltipView}
-	 */
-	_createTooltipView() {
-		const tooltipView = new TooltipView();
-
-		tooltipView.bind( 'text' ).to( this, '_tooltipString' );
-		tooltipView.bind( 'position' ).to( this, 'tooltipPosition' );
-
-		return tooltipView;
-	}
-
 	/**
 	 * Creates a label view instance and binds it with button attributes.
 	 *
@@ -276,7 +260,7 @@ export default class ButtonView extends View {
 	}
 
 	/**
-	 * Gets the text for the {@link #tooltipView} from the combination of
+	 * Gets the text for the tooltip from the combination of
 	 * {@link #tooltip}, {@link #label} and {@link #keystroke} attributes.
 	 *
 	 * @private

package/src/colorgrid/colorgridview.js

@@ -10,8 +10,9 @@
 import View from '../view';
 import ColorTileView from './colortileview';
 import FocusTracker from '@ckeditor/ckeditor5-utils/src/focustracker';
-import FocusCycler from '../focuscycler';
 import KeystrokeHandler from '@ckeditor/ckeditor5-utils/src/keystrokehandler';
+import addKeyboardHandlingForGrid from '../bindings/addkeyboardhandlingforgrid';
+
 import '../../theme/components/colorgrid/colorgrid.css';
 
 /**
@@ -27,7 +28,7 @@ export default class ColorGridView extends View {
 	 * @param {Object} options Component configuration
 	 * @param {Array.<module:ui/colorgrid/colorgrid~ColorDefinition>} [options.colorDefinitions] Array with definitions
 	 * required to create the {@link module:ui/colorgrid/colortile~ColorTileView tiles}.
-	 * @param {Number} options.columns A number of columns to display the tiles.
+	 * @param {Number} [options.columns=5] A number of columns to display the tiles.
 	 */
 	constructor( locale, options ) {
 		super( locale );
@@ -35,9 +36,15 @@ export default class ColorGridView extends View {
 		const colorDefinitions = options && options.colorDefinitions || [];
 		const viewStyleAttribute = {};
 
-		if ( options && options.columns ) {
-			viewStyleAttribute.gridTemplateColumns = `repeat( ${ options.columns }, 1fr)`;
-		}
+		/**
+		 * A number of columns for the tiles grid.
+		 *
+		 * @readonly
+		 * @member {Number}
+		 */
+		this.columns = options && options.columns ? options.columns : 5;
+
+		viewStyleAttribute.gridTemplateColumns = `repeat( ${ this.columns }, 1fr)`;
 
 		/**
 		 * The color of the currently selected color tile in {@link #items}.
@@ -71,26 +78,6 @@ export default class ColorGridView extends View {
 		 */
 		this.keystrokes = new KeystrokeHandler();
 
-		/**
-		 * Helps cycling over focusable {@link #items} in the grid.
-		 *
-		 * @readonly
-		 * @protected
-		 * @member {module:ui/focuscycler~FocusCycler}
-		 */
-		this._focusCycler = new FocusCycler( {
-			focusables: this.items,
-			focusTracker: this.focusTracker,
-			keystrokeHandler: this.keystrokes,
-			actions: {
-				// Navigate grid items backwards using the arrowup key.
-				focusPrevious: 'arrowleft',
-
-				// Navigate grid items forwards using the arrowdown key.
-				focusNext: 'arrowright'
-			}
-		} );
-
 		this.items.on( 'add', ( evt, colorTile ) => {
 			colorTile.isOn = colorTile.color === this.selectedColor;
 		} );
@@ -174,6 +161,13 @@ export default class ColorGridView extends View {
 
 		// Start listening for the keystrokes coming from #element.
 		this.keystrokes.listenTo( this.element );
+
+		addKeyboardHandlingForGrid( {
+			keystrokeHandler: this.keystrokes,
+			focusTracker: this.focusTracker,
+			gridItems: this.items,
+			numberOfColumns: this.columns
+		} );
 	}
 
 	/**

package/src/dropdown/button/dropdownbuttonview.js

@@ -49,7 +49,8 @@ export default class DropdownButtonView extends ButtonView {
 
 		this.extendTemplate( {
 			attributes: {
-				'aria-haspopup': true
+				'aria-haspopup': true,
+				'aria-expanded': this.bindTemplate.to( 'isOn', value => String( value ) )
 			}
 		} );
 

package/src/dropdown/button/splitbuttonview.js

@@ -222,7 +222,10 @@ export default class SplitButtonView extends View {
 
 		arrowView.extendTemplate( {
 			attributes: {
-				class: 'ck-splitbutton__arrow',
+				class: [
+					'ck-splitbutton__arrow'
+				],
+				'data-cke-tooltip-disabled': bind.to( 'isOn' ),
 				'aria-haspopup': true,
 				'aria-expanded': bind.to( 'isOn', value => String( value ) )
 			}

package/src/dropdown/dropdownpanelview.js

@@ -8,6 +8,7 @@
  */
 
 import View from '../view';
+import { logWarning } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 
 /**
  * The dropdown panel view class.
@@ -81,13 +82,32 @@ export default class DropdownPanelView extends View {
 	}
 
 	/**
-	 * Focuses the view element or first item in view collection on opening dropdown's panel.
+	 * Focuses the first view in the {@link #children} collection.
 	 *
 	 * See also {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable}.
 	 */
 	focus() {
 		if ( this.children.length ) {
-			this.children.first.focus();
+			if ( typeof this.children.first.focus === 'function' ) {
+				this.children.first.focus();
+			} else {
+				/**
+				 * The child view of a dropdown could not be focused because it is missing the `focus()` method.
+				 *
+				 * This warning appears when a dropdown {@link module:ui/dropdown/dropdownview~DropdownView#isOpen gets open} and it
+				 * attempts to focus the {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#children first child} of its panel
+				 * but the child does not implement the
+				 * {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable focusable interface}.
+				 *
+				 * Focusing the content of a dropdown on open greatly improves the accessibility. Please make sure the view instance
+				 * 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
+				 */
+				logWarning( 'ui-dropdown-panel-focus-child-missing-focus', { childView: this.children.first, dropdownPanel: this } );
+			}
 		}
 	}
 

package/src/dropdown/dropdownview.js

@@ -106,6 +106,10 @@ export default class DropdownView extends View {
 		/**
 		 * 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
 		 */
@@ -190,7 +194,8 @@ export default class DropdownView extends View {
 			attributes: {
 				class: [
 					'ck-dropdown__button'
-				]
+				],
+				'data-cke-tooltip-disabled': bind.to( 'isOpen' )
 			}
 		} );
 
@@ -248,6 +253,9 @@ export default class DropdownView extends View {
 		// be updated every time the dropdown is open.
 		this.on( 'change:isOpen', () => {
 			if ( !this.isOpen ) {
+				// If the dropdown was closed, move the focus back to the button (#12125).
+				this.focus();
+
 				return;
 			}
 
@@ -263,6 +271,9 @@ export default class DropdownView extends View {
 			} else {
 				this.panelView.position = this.panelPosition;
 			}
+
+			// Focus the first item in the dropdown when the dropdown opened
+			this.panelView.focus();
 		} );
 
 		// Listen for keystrokes coming from within #element.
@@ -270,7 +281,6 @@ export default class DropdownView extends View {
 
 		const closeDropdown = ( data, cancel ) => {
 			if ( this.isOpen ) {
-				this.buttonView.focus();
 				this.isOpen = false;
 				cancel();
 			}

package/src/dropdown/utils.js

@@ -19,6 +19,8 @@ import SwitchButtonView from '../button/switchbuttonview';
 
 import clickOutsideHandler from '../bindings/clickoutsidehandler';
 
+import { logWarning } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
 import '../../theme/components/dropdown/toolbardropdown.css';
 import '../../theme/components/dropdown/listdropdown.css';
 
@@ -123,12 +125,22 @@ export function createDropdown( locale, ButtonClass = DropdownButtonView ) {
  *		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.
+ *
  * See {@link module:ui/dropdown/utils~createDropdown} and {@link module:ui/toolbar/toolbarview~ToolbarView}.
  *
  * @param {module:ui/dropdown/dropdownview~DropdownView} dropdownView A dropdown instance to which `ToolbarView` will be added.
  * @param {Iterable.<module:ui/button/buttonview~ButtonView>} buttons
+ * @param {Object} [options]
+ * @param {Boolean} [options.enableActiveItemFocusOnDropdownOpen=false] 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}).
  */
-export function addToolbarToDropdown( dropdownView, buttons ) {
+export function addToolbarToDropdown( dropdownView, buttons, options = {} ) {
 	const locale = dropdownView.locale;
 	const t = locale.t;
 	const toolbarView = dropdownView.toolbarView = new ToolbarView( locale );
@@ -143,6 +155,11 @@ export function addToolbarToDropdown( dropdownView, buttons ) {
 
 	buttons.map( view => toolbarView.items.add( view ) );
 
+	if ( options.enableActiveItemFocusOnDropdownOpen ) {
+		// Accessibility: Focus the first active button in the toolbar when the dropdown gets open.
+		focusChildOnDropdownOpen( dropdownView, () => toolbarView.items.find( item => item.isOn ) );
+	}
+
 	dropdownView.panelView.children.add( toolbarView );
 	toolbarView.items.delegate( 'execute' ).to( dropdownView );
 }
@@ -182,6 +199,9 @@ export function addToolbarToDropdown( dropdownView, buttons ) {
  * 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.
  *
  * See {@link module:ui/dropdown/utils~createDropdown} and {@link module:list/list~List}.
  *
@@ -219,6 +239,56 @@ export function addListToDropdown( dropdownView, items ) {
 	dropdownView.panelView.children.add( listView );
 
 	listView.items.delegate( 'execute' ).to( dropdownView );
+
+	// Accessibility: Focus the first active button in the list when the dropdown gets open.
+	focusChildOnDropdownOpen( dropdownView, () => listView.items.find( item => {
+		if ( item instanceof ListItemView ) {
+			return item.children.first.isOn;
+		}
+
+		return false;
+	} ) );
+}
+
+/**
+ * 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 {module:ui/dropdown/dropdownview~DropdownView} dropdownView A dropdown instance to which the focus behavior will be added.
+ * @param {Function} 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 function focusChildOnDropdownOpen( dropdownView, childSelectorCallback ) {
+	dropdownView.on( 'change:isOpen', () => {
+		if ( !dropdownView.isOpen ) {
+			return;
+		}
+
+		const childToFocus = childSelectorCallback();
+
+		if ( !childToFocus ) {
+			return;
+		}
+
+		if ( typeof childToFocus.focus === 'function' ) {
+			childToFocus.focus();
+		} else {
+			/**
+			 * The child view of a {@link module:ui/dropdown/dropdownview~DropdownView dropdown} is missing the `focus()` method
+			 * and could not be focused when the dropdown got {@link module:ui/dropdown/dropdownview~DropdownView#isOpen open}.
+			 *
+			 * Making the content of a dropdown focusable in this case greatly improves the accessibility. Please make the view instance
+			 * implements the {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable focusable interface} for the best user
+			 * experience.
+			 *
+			 * @error ui-dropdown-focus-child-on-open-child-missing-focus
+			 * @param {module:ui/view~View} view
+			 */
+			logWarning( 'ui-dropdown-focus-child-on-open-child-missing-focus', { view: childToFocus } );
+		}
+	}, { priority: 'low' } );
 }
 
 // Add a set of default behaviors to dropdown view.

package/src/editableui/inline/inlineeditableuiview.js

@@ -23,16 +23,32 @@ export default class InlineEditableUIView extends EditableUIView {
 	 * @param {HTMLElement} [editableElement] The editable element. If not specified, the
 	 * {@link module:ui/editableui/editableuiview~EditableUIView}
 	 * will create it. Otherwise, the existing element will be used.
+	 * @param {Object} [options] Additional configuration of the view.
+	 * @param {Function} [options.label] A function that gets called with the instance of this view as an argument
+	 * and should return a string that represents the label of the editable for assistive technologies. If not provided,
+	 * a default label generator is used.
 	 */
-	constructor( locale, editingView, editableElement ) {
+	constructor( locale, editingView, editableElement, options = {} ) {
 		super( locale, editingView, editableElement );
 
+		const t = locale.t;
+
 		this.extendTemplate( {
 			attributes: {
 				role: 'textbox',
 				class: 'ck-editor__editable_inline'
 			}
 		} );
+
+		/**
+		 * A function that gets called with the instance of this view as an argument and should return a string that
+		 * represents the label of the editable for assistive technologies.
+		 *
+		 * @private
+		 * @readonly
+		 * @param {Function}
+		 */
+		this._generateLabel = options.label || ( () => t( 'Editor editing area: %0', this.name ) );
 	}
 
 	/**
@@ -42,12 +58,11 @@ export default class InlineEditableUIView extends EditableUIView {
 		super.render();
 
 		const editingView = this._editingView;
-		const t = this.t;
 
 		editingView.change( writer => {
 			const viewRoot = editingView.document.getRoot( this.name );
 
-			writer.setAttribute( 'aria-label', t( 'Rich Text Editor, %0', this.name ), viewRoot );
+			writer.setAttribute( 'aria-label', this._generateLabel( this ), viewRoot );
 		} );
 	}
 }

package/src/icon/iconview.js

@@ -103,7 +103,9 @@ export default class IconView extends View {
 				this.viewBox = viewBox;
 			}
 
-			this.element.innerHTML = '';
+			while ( this.element.firstChild ) {
+				this.element.removeChild( this.element.firstChild );
+			}
 
 			while ( svg.childNodes.length > 0 ) {
 				this.element.appendChild( svg.childNodes[ 0 ] );

package/src/index.js

@@ -10,6 +10,7 @@
 export { default as clickOutsideHandler } from './bindings/clickoutsidehandler';
 export { default as injectCssTransitionDisabler } from './bindings/injectcsstransitiondisabler';
 export { default as submitHandler } from './bindings/submithandler';
+export { default as addKeyboardHandlingForGrid } from './bindings/addkeyboardhandlingforgrid';
 
 export { default as BodyCollection } from './editorui/bodycollection';
 
@@ -52,12 +53,11 @@ export { default as BalloonPanelView } from './panel/balloon/balloonpanelview';
 export { default as ContextualBalloon } from './panel/balloon/contextualballoon';
 export { default as StickyPanelView } from './panel/sticky/stickypanelview';
 
-export { default as TooltipView } from './tooltip/tooltipview';
+export { default as TooltipManager } from './tooltipmanager';
 export { default as Template } from './template';
 
 export { default as ToolbarView } from './toolbar/toolbarview';
 export { default as ToolbarSeparatorView } from './toolbar/toolbarseparatorview';
-export { default as enableToolbarKeyboardFocus } from './toolbar/enabletoolbarkeyboardfocus';
 export { default as normalizeToolbarConfig } from './toolbar/normalizetoolbarconfig';
 export { default as BalloonToolbar } from './toolbar/balloon/balloontoolbar';
 export { default as BlockToolbar } from './toolbar/block/blocktoolbar';

package/src/list/listitemview.js

@@ -21,6 +21,18 @@ export default class ListItemView extends View {
 	constructor( locale ) {
 		super( locale );
 
+		const bind = this.bindTemplate;
+
+		/**
+		 * Controls whether the item view is visible. Visible by default, list items are hidden
+		 * using a CSS class.
+		 *
+		 * @observable
+		 * @default true
+		 * @member {Boolean} #isVisible
+		 */
+		this.set( 'isVisible', true );
+
 		/**
 		 * Collection of the child views inside of the list item {@link #element}.
 		 *
@@ -35,7 +47,8 @@ export default class ListItemView extends View {
 			attributes: {
 				class: [
 					'ck',
-					'ck-list__item'
+					'ck-list__item',
+					bind.if( 'isVisible', 'ck-hidden', value => !value )
 				]
 			},