@microsoft/windows-admin-center-sdk
Version:
Microsoft - Windows Admin Center Shell
477 lines (475 loc) • 20.8 kB
JavaScript
import { LogLevel } from '../diagnostics/log-level';
import { Logging } from '../diagnostics/logging';
import { Dom } from '../dom/dom';
/**
* Class for accessibility manager
*/
export class AccessibilityManager {
/**
* Indicates that body focus class handlers have already been setup and should not be setup again
*/
hiddenFocusHandlersInitialized = false;
/**
* The set of events for element focusing.
*/
elementFocusingEvents = [];
/**
* The CSS class to disable the focus rectangle even in keyboard mode
*/
hiddenFocusClass = 'sme-hidden-focus';
/**
* The CSS class to enable mouse specific accessibility styles
*/
mouseNavigationModeClass = 'sme-accessibility-mode-mouse';
/**
* The CSS class to enable keyboard specific accessibility styles
*/
keyboardNavigationModeClass = 'sme-accessibility-mode-keyboard';
/**
* The set of elements that have had the hiddenFocusClass applied
*/
hiddenFocusElements = [];
/**
* The object of ctrl+alt+a key.
*/
ctrlAltAShortKey;
constructor() {
// hookup global handlers
this.hookupGlobalHandlers();
this.ctrlAltAShortKey = new KeyResolver('Ctrl+Alt+A');
}
/**
* Registers the event handler for ElementFocusingEvent
*/
registerElementFocusingEvent(handler) {
const unregisterEventFunction = () => {
const index = this.elementFocusingEvents.indexOf(handler);
if (index !== -1) {
this.elementFocusingEvents.splice(index, 1);
}
};
this.elementFocusingEvents.push(handler);
return unregisterEventFunction;
}
/**
* focus on given element and prevent the default of the event
* @param element the element to focus on
* @param event the event that triggered the focus
* @param allowBrowserFocusHandling it indicates whether to allow browser to handle focus.
*/
focusOnElement(element, event, allowBrowserFocusHandling) {
if (element) {
// this change needs to be taken in any snap-in implementations
// use param {preventScroll: true} if element is in an extension iframe
// TODO: try below code with snap-ins that use new snap-in listener code
element.focus();
if (!allowBrowserFocusHandling) {
event.preventDefault();
}
}
}
/**
* Find the first focusable descendant of an element and focus on it
* @param element the element to work with
* @param event the event that triggered the focus
*/
focusOnFirstFocusableDescendant(element, event) {
const firstFocusableDescendant = Dom.getFirstFocusableDescendent(element);
this.focusOnElement(firstFocusableDescendant, event);
}
/**
* Handlers the element focusing in either the default way or custom ways based on ElementFocusingEvent handler.
*/
processElementFocusing(event, elementToFocus, sourceZone, targetZone, allowBrowserFocusHandling) {
let useCustomFocusHandling = false;
let preventDefaultEvent = false;
this.elementFocusingEvents.forEach(focusEvent => {
focusEvent({
nativeEvent: event,
sourceZone: sourceZone,
targetZone: targetZone,
targetElement: elementToFocus,
preventDefaultFocusBehavior: () => {
useCustomFocusHandling = true;
},
preventDefaultEvent: () => {
preventDefaultEvent = true;
}
});
});
if (useCustomFocusHandling) {
if (preventDefaultEvent) {
event.stopPropagation();
event.preventDefault();
}
}
else {
this.focusOnElement(elementToFocus, event, allowBrowserFocusHandling);
}
}
/**
* click on given element and prevent the default of the event
* @param element the element to click
* @param event the event that triggered the click
*/
clickOnElement(element, event) {
if (element) {
element.click();
event.preventDefault();
}
}
/**
* Changes the Accessibility Mode to mouse or keyboard
* @param keyboardMode indicates that keyboard mode should be set
*/
changeAccessibilityMode(keyboardMode) {
// toggle accessibility mode across all iframes in the document
// only works for same origin iframes
// TODO: support cross origin iframes and replace this with RPC broadcasting to all iframes
const allBodys = Dom.getAllBodys();
for (let i = 0; i < allBodys.length; i++) {
const currentBody = allBodys[i];
currentBody.classList.toggle(this.mouseNavigationModeClass, !keyboardMode);
currentBody.classList.toggle(this.keyboardNavigationModeClass, keyboardMode);
}
// register accessibility mode with self so RPC can use it
const self = MsftSme.self();
self.Resources.accessibilityMode = keyboardMode;
}
/**
* Query the accessibility mode of parent
*/
queryAccessibilityMode() {
return !MsftSme.isNullOrUndefined(Dom.getSpecificAncestor(document.body, (x) => Dom.isBody(x) && x.classList.contains(this.keyboardNavigationModeClass)));
}
/**
* Hooks up the global event handlers
*/
hookupGlobalHandlers() {
// hookup body focus class handlers.
// We do not need to unhook these as they last the entire applications lifecycle.
if (!this.hiddenFocusHandlersInitialized) {
// ensure this is only called once
this.hiddenFocusHandlersInitialized = true;
// apply the mouse navigation class to the body of the document as default
this.changeAccessibilityMode(false);
// when the user clicks on the page, we need to exit keyboard mode and enter mouse mode again
document.body.addEventListener('mousedown', (event) => {
// If event.buttons is 0, it means this mouse action is triggered by narrator.
// If event.buttons is greater than 0, it means this mouse action is triggered by actual mouse device.
// Then exit accessibility mode.
if (event.buttons) {
this.changeAccessibilityMode(false);
setTimeout(() => Dom.checkActiveTab(), 0);
}
});
document.body.addEventListener('keydown', (event) => {
const isKeyboardMode = this.queryAccessibilityMode();
this.changeAccessibilityMode(isKeyboardMode);
const currentElement = event.target;
const currentElementProperties = Dom.getElementProperties(currentElement);
const currentTrap = currentElementProperties.currentTrap;
const allowCustomArrowKeyFunctionality = Dom.allowCustomArrowKeyFunctionality(currentElementProperties);
const allowCustomHomeEndKeyFunctionality = Dom.allowCustomHomeEndKeyFunctionality(currentElement, currentElementProperties);
const currentZone = currentElementProperties.currentZone;
const keyCode = event.keyCode;
setTimeout(() => Dom.checkActiveTab(), 0);
if (event.shiftKey && keyCode === KeyCode.Tab) {
// shift tab - go back to previous zone
let focusOn = Dom.getPreviousZoneElement(currentElement);
const targetZone = Dom.getAncestorZone(focusOn);
if (Dom.isTablist(targetZone)) {
focusOn = Dom.getFirstActiveOrSelectedDescendant(targetZone) || focusOn;
}
if (!currentElementProperties.withinTrap || Dom.getAncestorTrap(targetZone) === currentElementProperties.currentTrap) {
this.processElementFocusing(event, focusOn, currentZone, targetZone);
}
else {
event.preventDefault();
}
// else we are at the beginning of the page and want shift tab to perform its default action
}
else if (keyCode === KeyCode.Tab) {
// when the user presses 'tab' we will enter keyboard mode
this.changeAccessibilityMode(true);
const focusOn = Dom.getNextZoneElement(currentElement);
const targetZone = Dom.getAncestorZone(focusOn);
if (focusOn && targetZone !== currentZone) {
// go to next zone
let newFocusOn = focusOn;
if (Dom.isTablist(targetZone)) {
newFocusOn = Dom.getFirstActiveOrSelectedDescendant(targetZone);
}
if (!currentElementProperties.withinTrap
|| Dom.getAncestorTrap(targetZone) === currentElementProperties.currentTrap) {
this.processElementFocusing(event, newFocusOn, currentZone, targetZone);
}
else {
// we are at the end of the trap so go back to the beginning of the trap
this.focusOnFirstFocusableDescendant(currentTrap, event);
event.preventDefault();
}
}
else if (!currentElementProperties.withinTrap) {
// else we are at the end of the page and want tab to perform its default action
const lastElement = Dom.getLastElementInZone(currentElement);
if (lastElement) {
this.processElementFocusing(event, lastElement, currentZone, targetZone, true);
}
}
else {
// we are at the end of the trap so go back to the beginning of the trap
this.focusOnFirstFocusableDescendant(currentTrap, event);
}
}
else if (keyCode === KeyCode.RightArrow && allowCustomArrowKeyFunctionality) {
// use default if the cursor is in the middle of search box text
const useArrowKeys = Dom.useArrowKeysWithinSearchbox(currentElement, true);
if (!useArrowKeys && isKeyboardMode) {
// go to next focusable element within current zone
this.focusOnElement(Dom.getNextFocusableElement(currentElement), event);
}
}
else if (keyCode === KeyCode.DownArrow && allowCustomArrowKeyFunctionality) {
// go to next focusable element within current zone
this.focusOnElement(Dom.getNextFocusableElement(currentElement), event);
}
else if (keyCode === KeyCode.UpArrow && allowCustomArrowKeyFunctionality) {
// go to previous focusable element within current zone
this.focusOnElement(Dom.getPreviousFocusableElement(currentElement), event);
}
else if (event.keyCode === KeyCode.LeftArrow && allowCustomArrowKeyFunctionality) {
// use default if the cursor is in the middle of search box text
const useArrowKeys = Dom.useArrowKeysWithinSearchbox(currentElement, false);
if (!useArrowKeys && isKeyboardMode) {
// go to previous focusable element within current zone
this.focusOnElement(Dom.getPreviousFocusableElement(currentElement), event);
}
}
else if (event.keyCode === KeyCode.Enter) {
if (document.body.classList.contains(this.keyboardNavigationModeClass)) {
if ((currentZone || currentElementProperties.isZone)
&& (!currentElementProperties.withinForm || Dom.shouldTreatEnterAsClick(currentElement))) {
this.clickOnElement(currentElement, event);
}
}
}
else if (event.keyCode === KeyCode.End && allowCustomHomeEndKeyFunctionality) {
this.focusOnElement(Dom.getLastElementInZone(currentElement), event);
}
else if (event.keyCode === KeyCode.Home && allowCustomHomeEndKeyFunctionality) {
this.focusOnElement(Dom.getFirstElementInZone(currentElement), event);
}
else if (this.ctrlAltAShortKey.matchesWith(event)) {
let targetElement;
if (Dom.isInActionBar(currentElement)) {
targetElement = Dom.getNextActionBar(currentElement);
}
else {
targetElement = Dom.getFirstActionBar(currentElement);
}
if (!MsftSme.isNullOrUndefined(targetElement)) {
this.changeAccessibilityMode(true);
this.focusOnElement(targetElement, event, false);
}
}
});
}
}
}
/**
* Class to resolve keys.
*/
export class KeyResolver {
/**
* Whether has shift key.
*/
hasShiftKey = false;
/**
* Whether has alt key.
*/
hasAltKey = false;
/**
* Whether has ctrl key.
*/
hasCtrlKey = false;
/**
* The main key code for key combination.
*/
keyCode;
/**
* Initializes an instance of KeyLocalizer
* @param inputkeys Input keys.
*/
constructor(inputkeys) {
if (!MsftSme.isNullOrWhiteSpace(inputkeys)) {
this.resolveKeys(inputkeys);
}
}
/**
* Resolves localized keys in to this class structure.
* @param inputKeys Input keys.
*/
resolveKeys(inputKeys) {
if (inputKeys === '+') {
this.keyCode = KeyCode.Add;
return;
}
const keys = inputKeys.split('+');
if (keys.length > 0 && keys.length === 1) {
this.setModifierKeyFlags(keys[0]);
this.setKeycode(keys[0]);
}
else {
for (let i = 0; i < keys.length - 1; i++) {
this.setModifierKeyFlags(keys[i]);
}
this.setKeycode(keys[keys.length - 1]);
}
}
/**
* Sets modifier key flags if found in key combinations.
* @param key The key.
*/
setModifierKeyFlags(key) {
// These should always be passed as english keys.
if (key === 'Ctrl') {
this.hasCtrlKey = true;
}
else if (key === 'Alt') {
this.hasAltKey = true;
}
else if (key === 'Shift') {
this.hasShiftKey = true;
}
}
/**
* Set the key code extracted from the input key.
* @param key the key string.
*/
setKeycode(key) {
const keyCode = KeyCode[key];
this.keyCode = keyCode;
if (this.keyCode === undefined) {
Logging.log({
level: LogLevel.Error,
message: 'Could not resolve key ' + key,
source: KeyResolver.name
});
}
}
/**
* Checks if keyboard event matches with resolved keys.
* @param event The keyboard event containing pressed key information.
*/
matchesWith(event) {
return this.hasCtrlKey === event.ctrlKey &&
this.hasAltKey === event.altKey &&
this.hasShiftKey === event.shiftKey &&
this.keyCode === event.keyCode;
}
}
// Keyboard codes
export var KeyCode;
(function (KeyCode) {
KeyCode[KeyCode["Backspace"] = 8] = "Backspace";
KeyCode[KeyCode["Tab"] = 9] = "Tab";
KeyCode[KeyCode["Enter"] = 13] = "Enter";
KeyCode[KeyCode["Shift"] = 16] = "Shift";
KeyCode[KeyCode["Ctrl"] = 17] = "Ctrl";
KeyCode[KeyCode["Alt"] = 18] = "Alt";
KeyCode[KeyCode["Pause"] = 19] = "Pause";
KeyCode[KeyCode["CapsLock"] = 20] = "CapsLock";
KeyCode[KeyCode["Escape"] = 27] = "Escape";
KeyCode[KeyCode["Space"] = 32] = "Space";
KeyCode[KeyCode["PageUp"] = 33] = "PageUp";
KeyCode[KeyCode["PageDown"] = 34] = "PageDown";
KeyCode[KeyCode["End"] = 35] = "End";
KeyCode[KeyCode["Home"] = 36] = "Home";
KeyCode[KeyCode["LeftArrow"] = 37] = "LeftArrow";
KeyCode[KeyCode["UpArrow"] = 38] = "UpArrow";
KeyCode[KeyCode["RightArrow"] = 39] = "RightArrow";
KeyCode[KeyCode["DownArrow"] = 40] = "DownArrow";
KeyCode[KeyCode["Insert"] = 45] = "Insert";
KeyCode[KeyCode["Delete"] = 46] = "Delete";
KeyCode[KeyCode["Num0"] = 48] = "Num0";
KeyCode[KeyCode["Num1"] = 49] = "Num1";
KeyCode[KeyCode["Num2"] = 50] = "Num2";
KeyCode[KeyCode["Num3"] = 51] = "Num3";
KeyCode[KeyCode["Num4"] = 52] = "Num4";
KeyCode[KeyCode["Num5"] = 53] = "Num5";
KeyCode[KeyCode["Num6"] = 54] = "Num6";
KeyCode[KeyCode["Num7"] = 55] = "Num7";
KeyCode[KeyCode["Num8"] = 56] = "Num8";
KeyCode[KeyCode["Num9"] = 57] = "Num9";
KeyCode[KeyCode["A"] = 65] = "A";
KeyCode[KeyCode["B"] = 66] = "B";
KeyCode[KeyCode["C"] = 67] = "C";
KeyCode[KeyCode["D"] = 68] = "D";
KeyCode[KeyCode["E"] = 69] = "E";
KeyCode[KeyCode["F"] = 70] = "F";
KeyCode[KeyCode["G"] = 71] = "G";
KeyCode[KeyCode["H"] = 72] = "H";
KeyCode[KeyCode["I"] = 73] = "I";
KeyCode[KeyCode["J"] = 74] = "J";
KeyCode[KeyCode["K"] = 75] = "K";
KeyCode[KeyCode["L"] = 76] = "L";
KeyCode[KeyCode["M"] = 77] = "M";
KeyCode[KeyCode["N"] = 78] = "N";
KeyCode[KeyCode["O"] = 79] = "O";
KeyCode[KeyCode["P"] = 80] = "P";
KeyCode[KeyCode["Q"] = 81] = "Q";
KeyCode[KeyCode["R"] = 82] = "R";
KeyCode[KeyCode["S"] = 83] = "S";
KeyCode[KeyCode["T"] = 84] = "T";
KeyCode[KeyCode["U"] = 85] = "U";
KeyCode[KeyCode["V"] = 86] = "V";
KeyCode[KeyCode["W"] = 87] = "W";
KeyCode[KeyCode["X"] = 88] = "X";
KeyCode[KeyCode["Y"] = 89] = "Y";
KeyCode[KeyCode["Z"] = 90] = "Z";
KeyCode[KeyCode["LeftWindows"] = 91] = "LeftWindows";
KeyCode[KeyCode["RightWindows"] = 92] = "RightWindows";
KeyCode[KeyCode["Select"] = 93] = "Select";
KeyCode[KeyCode["Numpad0"] = 96] = "Numpad0";
KeyCode[KeyCode["Numpad1"] = 97] = "Numpad1";
KeyCode[KeyCode["Numpad2"] = 98] = "Numpad2";
KeyCode[KeyCode["Numpad3"] = 99] = "Numpad3";
KeyCode[KeyCode["Numpad4"] = 100] = "Numpad4";
KeyCode[KeyCode["Numpad5"] = 101] = "Numpad5";
KeyCode[KeyCode["Numpad6"] = 102] = "Numpad6";
KeyCode[KeyCode["Numpad7"] = 103] = "Numpad7";
KeyCode[KeyCode["Numpad8"] = 104] = "Numpad8";
KeyCode[KeyCode["Numpad9"] = 105] = "Numpad9";
KeyCode[KeyCode["Multiply"] = 106] = "Multiply";
KeyCode[KeyCode["Add"] = 107] = "Add";
KeyCode[KeyCode["Subtract"] = 109] = "Subtract";
KeyCode[KeyCode["DecimaPoint"] = 110] = "DecimaPoint";
KeyCode[KeyCode["Divide"] = 111] = "Divide";
KeyCode[KeyCode["F1"] = 112] = "F1";
KeyCode[KeyCode["F2"] = 113] = "F2";
KeyCode[KeyCode["F3"] = 114] = "F3";
KeyCode[KeyCode["F4"] = 115] = "F4";
KeyCode[KeyCode["F5"] = 116] = "F5";
KeyCode[KeyCode["F6"] = 117] = "F6";
KeyCode[KeyCode["F7"] = 118] = "F7";
KeyCode[KeyCode["F8"] = 119] = "F8";
KeyCode[KeyCode["F9"] = 120] = "F9";
KeyCode[KeyCode["F10"] = 121] = "F10";
KeyCode[KeyCode["F11"] = 122] = "F11";
KeyCode[KeyCode["F12"] = 123] = "F12";
KeyCode[KeyCode["NumLock"] = 144] = "NumLock";
KeyCode[KeyCode["ScrollLock"] = 145] = "ScrollLock";
KeyCode[KeyCode["SemiColon"] = 186] = "SemiColon";
KeyCode[KeyCode["EqualSign"] = 187] = "EqualSign";
KeyCode[KeyCode["Comma"] = 188] = "Comma";
KeyCode[KeyCode["Dash"] = 189] = "Dash";
KeyCode[KeyCode["Period"] = 190] = "Period";
KeyCode[KeyCode["ForwardSlash"] = 191] = "ForwardSlash";
KeyCode[KeyCode["GraveAccent"] = 192] = "GraveAccent";
KeyCode[KeyCode["OpenBracket"] = 219] = "OpenBracket";
KeyCode[KeyCode["BackSlash"] = 220] = "BackSlash";
KeyCode[KeyCode["CloseBraket"] = 221] = "CloseBraket";
KeyCode[KeyCode["SingleQuote"] = 222] = "SingleQuote";
})(KeyCode || (KeyCode = {}));
//# sourceMappingURL=accessibility-manager.js.map