Focus and keyboard handling documentation

The Range Slider is now focusable, the elements that gets the focus when
the component is active are the slider's handles and progress tracker.

The full keyboard handling specifications are implemented.

Author: ndeshev

packages/main/src/RangeSlider.hbs

@@ -1,16 +1,14 @@
 {{>include "./SliderBase.hbs"}}
 
 {{#*inline "handles"}}
-	<div class="ui5-slider-handle ui5-slider-handle--start" style="{{styles.startHandle}}" @focusout={{_onfocusout}}
-	@focusin={{_onfocusin}}	tabindex="{{tabIndex}}">
+	<div class="ui5-slider-handle ui5-slider-handle--start" style="{{styles.startHandle}}" tabindex="{{tabIndex}}" @focusout="{{_onfocusout}}" @focusin="{{_onfocusin}}">
 		{{#if showTooltip}}
 			<div class="ui5-slider-tooltip ui5-slider-tooltip--start" style="{{styles.tooltip}}">
 				<span class="ui5-slider-tooltip-value">{{tooltipStartValue}}</span>
 			</div>
 		{{/if}}
 	</div>
-	<div class="ui5-slider-handle ui5-slider-handle--end" style="{{styles.endHandle}}" tabindex="{{tabIndex}}" @focusout={{_onfocusout}}
-	@focusin={{_onfocusin}}>
+	<div class="ui5-slider-handle ui5-slider-handle--end" style="{{styles.endHandle}}" tabindex="{{tabIndex}}" @focusout="{{_onfocusout}}" @focusin="{{_onfocusin}}">
 		{{#if showTooltip}}
 			<div class="ui5-slider-tooltip ui5-slider-tooltip--end" style="{{styles.tooltip}}">
 				<span class="ui5-slider-tooltip-value">{{tooltipEndValue}}</span>

packages/main/src/RangeSlider.js

@@ -162,7 +162,7 @@ class RangeSlider extends SliderBase {
 	}
 
 	_onkeydown(event) {
-		this._onKeyDownBase(event);
+		this._handleKeyDown(event);
 	}
 
 	_handleActionKeyPress(event) {

packages/main/src/Slider.hbs

@@ -1,7 +1,7 @@
 {{>include "./SliderBase.hbs"}}
 
 {{#*inline "handles"}}
-	<div class="ui5-slider-handle" style="{{styles.handle}}">
+	<div class="ui5-slider-handle" style="{{styles.handle}}" tabindex="{{tabIndex}}" @focusout="{{_onfocusout}}" @focusin="{{_onfocusin}}">
 		{{#if showTooltip}}
 			<div class="ui5-slider-tooltip" style="{{styles.tooltip}}">
 				<span class="ui5-slider-tooltip-value">{{tooltipValue}}</span>

packages/main/src/SliderBase.hbs

@@ -23,8 +23,7 @@
 		{{/if}}
 
 		<div class="ui5-slider-progress-container">
-			<div class="ui5-slider-progress" style="{{styles.progress}}" @focusout={{_onfocusout}}
-				@focusin={{_onfocusin}} tabindex="{{tabIndexProgress}}"></div>
+			<div class="ui5-slider-progress" style="{{styles.progress}}" @focusout={{_onfocusout}} @focusin={{_onfocusin}} tabindex="{{tabIndexProgress}}"></div>
 		</div>
 		{{> handles}}
 	</div>

packages/main/src/SliderBase.js

@@ -4,7 +4,9 @@ import Float from "@ui5/webcomponents-base/dist/types/Float.js";
 import Integer from "@ui5/webcomponents-base/dist/types/Integer.js";
 import ResizeHandler from "@ui5/webcomponents-base/dist/delegate/ResizeHandler.js";
 import { isPhone } from "@ui5/webcomponents-base/dist/Device.js";
-import { isEscape, isHome, isEnd, isUp, isDown, isRight, isLeft, isUpCtrl, isDownCtrl, isRightCtrl, isLeftCtrl, isPlus, isMinus, isPageUp, isPageDown, getCtrlKey } from "@ui5/webcomponents-base/dist/Keys.js";
+import {
+	isEscape, isHome, isEnd, isUp, isDown, isRight, isLeft, isUpCtrl, isDownCtrl, isRightCtrl, isLeftCtrl, isPlus, isMinus, isPageUp, isPageDown,
+} from "@ui5/webcomponents-base/dist/Keys.js";
 import { getTheme } from "@ui5/webcomponents-base/dist/config/Theme.js";
 
 // Styles
@@ -292,21 +294,27 @@ class SliderBase extends UI5Element {
 		}
 	}
 
+	/**
+	 * Sets initial value when the component is focused in, can be restored with ESC key
+	 *
+	 * @private
+	 */
 	_setInitialValue(valueType, value) {
 		this[`_${valueType}Initial`] = value;
-	}	
+	}
 
 	_getInitialValue(valueType) {
 		return this[`_${valueType}Initial`];
 	}
 
-	_onKeyDownBase(event) {
+	_handleKeyDown(event) {
 		if (this.disabled) {
 			return;
 		}
 
 		if (SliderBase._isActionKey(event)) {
 			event.preventDefault();
+
 			this._isUserInteraction = true;
 			this._handleActionKeyPress(event);
 		}
@@ -320,18 +328,52 @@ class SliderBase extends UI5Element {
 		this._isUserInteraction = false;
 	}
 
-	static _isActionKey(event) {
-		return this.ACTION_KEYS.some(actionKey => actionKey(event));
+	/**
+	 * Flags if an inner element is currently being focused
+	 *
+	 * @private
+	 */
+	_preserveFocus(isFocusing) {
+		this._isInnerElementFocusing = isFocusing;
 	}
-	
+
+	/**
+	 * Return if an inside element within the component is currently being focused
+	 *
+	 * @private
+	 */
 	_isFocusing() {
-		return this._isInProcessOfFocusing;
+		return this._isInnerElementFocusing;
 	}
 
-	_setIsFocusing(isInProcessOfFocusing) {
-		this._isInProcessOfFocusing = isInProcessOfFocusing;
-	}
+	/**
+	 * Prevent focus out when inner element within the component is currently being in process of focusing in.
+	 * In theory this can be achieved either if the shadow root is focusable and 'delegatesFocus' attribute of
+	 * the .attachShadow() customElement method is set to true, or if we forward it manually.
 
+	 * As we use lit-element as base of our core UI5 element class that 'delegatesFocus' property is not set to 'true' and
+	 * we have to manage the focus here. If at some point in the future this changes, the focus delegating logic could be
+	 * removed as it will become redundant.
+	 *
+	 * When we manually set the focus on mouseDown to the first focusable element inside the shadowDom,
+	 * that inner focus (shadowRoot.activeElement) is set a moment before the global document.activeElement
+	 * is set to the customElement (ui5-slider) causing a 'race condition'.
+	 *
+	 * In order for a element within the shadowRoot to be focused, the global document.activeElement MUST be the parent
+	 * customElement of the shadow root, in our case the ui5-slider component. Because of that after our focusin of the handle,
+	 * a focusout event fired by the browser immidiatly after, resetting the focus. Focus out must be manually prevented
+	 * in both initial focusing and switching the focus between inner elements of the component cases.
+
+	 * Note: If we set the focus to the handle with a timeout or a bit later in time, on a mouseup or click event it will
+	 * work fine and we will avoid the described race condition as our host customElement will be already finished focusing.
+	 * However, that does not work for us as we need the focus to be set to the handle exactly on mousedown,
+	 * because of the nature of the component and its available drag interactions.
+	 *
+	 * @private
+	 */
+	_preventFocusOut() {
+		this._focusInnerElement();
+	}
 
 	/**
 	 * Handle the responsiveness of the Slider's UI elements when resizing
@@ -363,7 +405,6 @@ class SliderBase extends UI5Element {
 			return;
 		}
 
-
 		// Check if there are any overlapping labels.
 		// If so - only the first and the last one should be visible
 		const labelItems = this.shadowRoot.querySelectorAll(".ui5-slider-labels li");
@@ -397,11 +438,24 @@ class SliderBase extends UI5Element {
 		SliderBase.UP_EVENTS.forEach(upEventType => window.addEventListener(upEventType, this._upHandler));
 		window.addEventListener(this._moveEventType, this._moveHandler);
 
-		this._setIsFocusing(true);
-		this._focusInnerElement();
+		this._handleFocusOnMouseDown(event);
 		return newValue;
 	}
 
+	/**
+	 * Forward the focus to an inner inner part within the component on press
+	 *
+	 * @private
+	 */
+	_handleFocusOnMouseDown(event) {
+		const focusedElement = this.shadowRoot.activeElement;
+
+		if (!focusedElement || focusedElement !== event.target) {
+			this._preserveFocus(true);
+			this._focusInnerElement();
+		}
+	}
+
 	/**
 	 * Called when the user finish interacting with the slider
 	 * Fires an <code>change</code> event indicating a final value change, after user interaction is finished.
@@ -418,7 +472,7 @@ class SliderBase extends UI5Element {
 
 		this._moveEventType = null;
 		this._isUserInteraction = false;
-		this._setIsFocusing(false);
+		this._preserveFocus(false);
 	}
 
 	/**
@@ -435,6 +489,15 @@ class SliderBase extends UI5Element {
 		}
 	}
 
+	/**
+	 * Goes through the key shortcuts available for the component and returns 'true' if the event is triggered by one.
+	 *
+	 * @private
+	 */
+	static _isActionKey(event) {
+		return this.ACTION_KEYS.some(actionKey => actionKey(event));
+	}
+
 	/**
 	 * Locks the given value between min and max boundaries based on slider properties
 	 *
@@ -688,7 +751,6 @@ class SliderBase extends UI5Element {
 	}
 
 	_handleActionKeyPress(event, affectedValue) {
-		const isDownAction = SliderBase._isDecreaseValueAction(event);
 		const isUpAction = SliderBase._isIncreaseValueAction(event);
 		const isBigStep = SliderBase._isBigStepAction(event);
 
@@ -707,7 +769,7 @@ class SliderBase extends UI5Element {
 		}
 
 		if (isHome(event)) {
-			return (currentValue - min) * - 1;
+			return (currentValue - min) * -1;
 		}
 
 		return isUpAction ? step : step * -1;