keyborg 1.0.0-alpha.0 → 1.1.0-alpha.1

package/README.md

@@ -0,0 +1,66 @@
+# Keyborg ⌨️🤖
+
+Keyborg is a library that tracks the state of current keyboard input on a web page through focus events.
+
+**It does not do anything invasive to the DOM** but provides an event subscription system that allows users to choose how they want to react to changes in focus.
+
+## Getting started
+
+### Installation
+
+```bash
+# NPM
+npm install --save keyborg
+# Yarn
+yarn add keyborg
+```
+
+### Usage
+
+```js
+import { createKeyborg } from "keyborg";
+
+// initializes keyborg on the current window
+const keyborg = createKeyborg(window);
+
+// This is called every time the keyboard input state changes
+const handler = (isUsingKeyboard) => {
+  if (isUsingKeyboard) {
+    document.body.setAttribute("data-is-keyboard", "true");
+  } else {
+    document.body.removeAttribute("data-is-keyboard");
+  }
+};
+
+keyborg.subscribe(handler);
+keyborg.unsubscribe(handler);
+```
+
+## Contributing
+
+Pretty simple currently, you only need to know about theese commands
+
+- `npm install` - install dependencies
+- `npm run build` - builds the library
+- `npm run format:fix` - runs prettier to format code
+- `npm run lint:fix` - runs eslint and fixes issues
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.

package/lib/FocusEvent.d.ts

@@ -0,0 +1,26 @@
+export declare const KEYBORG_FOCUSIN = "keyborg:focusin";
+export interface KeyborgFocusInEventDetails {
+    relatedTarget?: HTMLElement;
+    isFocusedProgrammatically?: boolean;
+}
+export interface KeyborgFocusInEvent extends Event {
+    details: KeyborgFocusInEventDetails;
+}
+/**
+ * Guarantees that the native `focus` will be used
+ */
+export declare function nativeFocus(element: HTMLElement): void;
+/**
+ * Overrides the native `focus` and setups the keyborg focus event
+ */
+export declare function setupFocusEvent(win: Window): void;
+/**
+ * Removes keyborg event listeners and custom focus override
+ * @param win The window that stores keyborg focus events
+ */
+export declare function disposeFocusEvent(win: Window): void;
+/**
+ * @param win The window that stores keyborg focus events
+ * @returns The last element focused with element.focus()
+ */
+export declare function getLastFocusedProgrammatically(win: Window): HTMLElement | null | undefined;

package/lib/FocusEvent.js

@@ -0,0 +1,130 @@
+import { WeakRefInstance } from './WeakRefInstance.js';
+
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+const KEYBORG_FOCUSIN = "keyborg:focusin";
+
+function canOverrideNativeFocus(win) {
+  const HTMLElement = win.HTMLElement;
+  const origFocus = HTMLElement.prototype.focus;
+  let isCustomFocusCalled = false;
+
+  HTMLElement.prototype.focus = function focus() {
+    isCustomFocusCalled = true;
+  };
+
+  const btn = win.document.createElement("button");
+  btn.focus();
+  HTMLElement.prototype.focus = origFocus;
+  return isCustomFocusCalled;
+}
+
+let _canOverrideNativeFocus = false;
+/**
+ * Guarantees that the native `focus` will be used
+ */
+
+function nativeFocus(element) {
+  const focus = element.focus;
+
+  if (focus.__keyborgNativeFocus) {
+    focus.__keyborgNativeFocus.call(element);
+  } else {
+    element.focus();
+  }
+}
+/**
+ * Overrides the native `focus` and setups the keyborg focus event
+ */
+
+function setupFocusEvent(win) {
+  const kwin = win;
+
+  if (!_canOverrideNativeFocus) {
+    _canOverrideNativeFocus = canOverrideNativeFocus(kwin);
+  }
+
+  const origFocus = kwin.HTMLElement.prototype.focus;
+
+  if (origFocus.__keyborgNativeFocus) {
+    // Already set up.
+    return;
+  }
+
+  kwin.HTMLElement.prototype.focus = focus;
+  const data = kwin.__keyborgData = {
+    focusInHandler: e => {
+      var _a;
+
+      const target = e.target;
+
+      if (!target) {
+        return;
+      }
+
+      const event = document.createEvent("HTMLEvents");
+      event.initEvent(KEYBORG_FOCUSIN, true, true);
+      const details = {
+        relatedTarget: e.relatedTarget || undefined
+      };
+
+      if (_canOverrideNativeFocus || data.lastFocusedProgrammatically) {
+        details.isFocusedProgrammatically = target === ((_a = data.lastFocusedProgrammatically) === null || _a === void 0 ? void 0 : _a.deref());
+        data.lastFocusedProgrammatically = undefined;
+      }
+
+      event.details = details;
+      target.dispatchEvent(event);
+    }
+  };
+  kwin.document.addEventListener("focusin", kwin.__keyborgData.focusInHandler, true);
+
+  function focus() {
+    const keyborgNativeFocusEvent = kwin.__keyborgData;
+
+    if (keyborgNativeFocusEvent) {
+      keyborgNativeFocusEvent.lastFocusedProgrammatically = new WeakRefInstance(this);
+    } // eslint-disable-next-line prefer-rest-params
+
+
+    return origFocus.apply(this, arguments);
+  }
+
+  focus.__keyborgNativeFocus = origFocus;
+}
+/**
+ * Removes keyborg event listeners and custom focus override
+ * @param win The window that stores keyborg focus events
+ */
+
+function disposeFocusEvent(win) {
+  const kwin = win;
+  const proto = kwin.HTMLElement.prototype;
+  const origFocus = proto.focus.__keyborgNativeFocus;
+  const keyborgNativeFocusEvent = kwin.__keyborgData;
+
+  if (keyborgNativeFocusEvent) {
+    kwin.document.removeEventListener("focusin", keyborgNativeFocusEvent.focusInHandler, true);
+    delete kwin.__keyborgData;
+  }
+
+  if (origFocus) {
+    proto.focus = origFocus;
+  }
+}
+/**
+ * @param win The window that stores keyborg focus events
+ * @returns The last element focused with element.focus()
+ */
+
+function getLastFocusedProgrammatically(win) {
+  var _a;
+
+  const keyborgNativeFocusEvent = win.__keyborgData;
+  return keyborgNativeFocusEvent ? ((_a = keyborgNativeFocusEvent.lastFocusedProgrammatically) === null || _a === void 0 ? void 0 : _a.deref()) || null : undefined;
+}
+
+export { KEYBORG_FOCUSIN, disposeFocusEvent, getLastFocusedProgrammatically, nativeFocus, setupFocusEvent };
+//# sourceMappingURL=FocusEvent.js.map

package/lib/FocusEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FocusEvent.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/lib/Keyborg.d.ts

@@ -0,0 +1,81 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Disposable } from "./WeakRefInstance";
+interface WindowWithKeyborg extends Window {
+    __keyborg?: {
+        core: KeyborgCore;
+        refs: {
+            [id: string]: Keyborg;
+        };
+    };
+}
+export declare type KeyborgCallback = (isNavigatingWithKeyboard: boolean) => void;
+/**
+ * Source of truth for all the keyborg core instances and the current keyboard navigation state
+ */
+export declare class KeyborgState {
+    private __keyborgCoreRefs;
+    private _isNavigatingWithKeyboard;
+    add(keyborg: KeyborgCore): void;
+    remove(id: string): void;
+    setVal(isNavigatingWithKeyboard: boolean): void;
+    getVal(): boolean;
+}
+/**
+ * Manages a collection of Keyborg instances in a window/document and updates keyborg state
+ */
+declare class KeyborgCore implements Disposable {
+    readonly id: string;
+    private _win?;
+    private _isMouseUsed;
+    private _dismissTimer;
+    constructor(win: WindowWithKeyborg);
+    dispose(): void;
+    isDisposed(): boolean;
+    /**
+     * Updates all keyborg instances with the keyboard navigation state
+     */
+    update(isNavigatingWithKeyboard: boolean): void;
+    private _onFocusIn;
+    private _onMouseDown;
+    private _onKeyDown;
+    private _scheduleDismiss;
+}
+/**
+ * Used to determine the keyboard navigation state
+ */
+export declare class Keyborg {
+    private _id;
+    private _win?;
+    private _core?;
+    private _cb;
+    static create(win: WindowWithKeyborg): Keyborg;
+    static dispose(instance: Keyborg): void;
+    /**
+     * Updates all subscribed callbacks with the keyboard navigation state
+     */
+    static update(instance: Keyborg, isNavigatingWithKeyboard: boolean): void;
+    private constructor();
+    private dispose;
+    /**
+     * @returns Whether the user is navigating with keyboard
+     */
+    isNavigatingWithKeyboard(): boolean;
+    /**
+     * @param callback - Called when the keyboard navigation state changes
+     */
+    subscribe(callback: KeyborgCallback): void;
+    /**
+     * @param callback - Registered with subscribe
+     */
+    unsubscribe(callback: KeyborgCallback): void;
+    /**
+     * Manually set the keyboard navigtion state
+     */
+    setVal(isNavigatingWithKeyboard: boolean): void;
+}
+export declare function createKeyborg(win: Window): Keyborg;
+export declare function disposeKeyborg(instance: Keyborg): void;
+export {};

package/lib/Keyborg.js

@@ -0,0 +1,313 @@
+import { KEYBORG_FOCUSIN, setupFocusEvent, disposeFocusEvent } from './FocusEvent.js';
+import { WeakRefInstance } from './WeakRefInstance.js';
+
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+const KeyTab = 9;
+const KeyEsc = 27;
+const _dismissTimeout = 500; // When Esc is pressed and the focused is not moved
+// during _dismissTimeout time, dismiss the keyboard
+// navigation mode.
+
+let _lastId = 0;
+/**
+ * Source of truth for all the keyborg core instances and the current keyboard navigation state
+ */
+
+class KeyborgState {
+  constructor() {
+    this.__keyborgCoreRefs = {};
+    this._isNavigatingWithKeyboard = false;
+  }
+
+  add(keyborg) {
+    const id = keyborg.id;
+
+    if (!(id in this.__keyborgCoreRefs)) {
+      this.__keyborgCoreRefs[id] = new WeakRefInstance(keyborg);
+    }
+  }
+
+  remove(id) {
+    delete this.__keyborgCoreRefs[id];
+
+    if (Object.keys(this.__keyborgCoreRefs).length === 0) {
+      this._isNavigatingWithKeyboard = false;
+    }
+  }
+
+  setVal(isNavigatingWithKeyboard) {
+    if (this._isNavigatingWithKeyboard === isNavigatingWithKeyboard) {
+      return;
+    }
+
+    this._isNavigatingWithKeyboard = isNavigatingWithKeyboard;
+
+    for (const id of Object.keys(this.__keyborgCoreRefs)) {
+      const ref = this.__keyborgCoreRefs[id];
+      const keyborg = ref.deref();
+
+      if (keyborg) {
+        keyborg.update(isNavigatingWithKeyboard);
+      } else {
+        this.remove(id);
+      }
+    }
+  }
+
+  getVal() {
+    return this._isNavigatingWithKeyboard;
+  }
+
+}
+
+const _state = /*#__PURE__*/new KeyborgState();
+/**
+ * Manages a collection of Keyborg instances in a window/document and updates keyborg state
+ */
+
+
+class KeyborgCore {
+  constructor(win) {
+    this._isMouseUsed = false;
+
+    this._onFocusIn = e => {
+      if (this._isMouseUsed) {
+        this._isMouseUsed = false;
+        return;
+      }
+
+      if (_state.getVal()) {
+        return;
+      }
+
+      const details = e.details;
+
+      if (!details.relatedTarget) {
+        return;
+      }
+
+      if (details.isFocusedProgrammatically || details.isFocusedProgrammatically === undefined) {
+        // The element is focused programmatically, or the programmatic focus detection
+        // is not working.
+        return;
+      }
+
+      _state.setVal(true);
+    };
+
+    this._onMouseDown = e => {
+      if (e.buttons === 0 || e.clientX === 0 && e.clientY === 0 && e.screenX === 0 && e.screenY === 0) {
+        // This is most likely an event triggered by the screen reader to perform
+        // an action on an element, do not dismiss the keyboard navigation mode.
+        return;
+      }
+
+      this._isMouseUsed = true;
+
+      _state.setVal(false);
+    };
+
+    this._onKeyDown = e => {
+      const isNavigatingWithKeyboard = _state.getVal();
+
+      if (!isNavigatingWithKeyboard && e.keyCode === KeyTab) {
+        _state.setVal(true);
+      } else if (isNavigatingWithKeyboard && e.keyCode === KeyEsc) {
+        this._scheduleDismiss();
+      }
+    };
+
+    this.id = "c" + ++_lastId;
+    this._win = win;
+    const doc = win.document;
+    doc.addEventListener(KEYBORG_FOCUSIN, this._onFocusIn, true); // Capture!
+
+    doc.addEventListener("mousedown", this._onMouseDown, true); // Capture!
+
+    win.addEventListener("keydown", this._onKeyDown, true); // Capture!
+
+    setupFocusEvent(win);
+
+    _state.add(this);
+  }
+
+  dispose() {
+    const win = this._win;
+
+    if (win) {
+      if (this._dismissTimer) {
+        win.clearTimeout(this._dismissTimer);
+        this._dismissTimer = undefined;
+      }
+
+      disposeFocusEvent(win);
+      const doc = win.document;
+      doc.removeEventListener(KEYBORG_FOCUSIN, this._onFocusIn, true); // Capture!
+
+      doc.removeEventListener("mousedown", this._onMouseDown, true); // Capture!
+
+      win.removeEventListener("keydown", this._onKeyDown, true); // Capture!
+
+      delete this._win;
+
+      _state.remove(this.id);
+    }
+  }
+
+  isDisposed() {
+    return !!this._win;
+  }
+  /**
+   * Updates all keyborg instances with the keyboard navigation state
+   */
+
+
+  update(isNavigatingWithKeyboard) {
+    var _a, _b;
+
+    const keyborgs = (_b = (_a = this._win) === null || _a === void 0 ? void 0 : _a.__keyborg) === null || _b === void 0 ? void 0 : _b.refs;
+
+    if (keyborgs) {
+      for (const id of Object.keys(keyborgs)) {
+        Keyborg.update(keyborgs[id], isNavigatingWithKeyboard);
+      }
+    }
+  }
+
+  _scheduleDismiss() {
+    const win = this._win;
+
+    if (win) {
+      if (this._dismissTimer) {
+        win.clearTimeout(this._dismissTimer);
+        this._dismissTimer = undefined;
+      }
+
+      const was = win.document.activeElement;
+      this._dismissTimer = win.setTimeout(() => {
+        this._dismissTimer = undefined;
+        const cur = win.document.activeElement;
+
+        if (was && cur && was === cur) {
+          // Esc was pressed, currently focused element hasn't changed.
+          // Just dismiss the keyboard navigation mode.
+          _state.setVal(false);
+        }
+      }, _dismissTimeout);
+    }
+  }
+
+}
+/**
+ * Used to determine the keyboard navigation state
+ */
+
+
+class Keyborg {
+  constructor(win) {
+    this._cb = [];
+    this._id = "k" + ++_lastId;
+    this._win = win;
+    const current = win.__keyborg;
+
+    if (current) {
+      this._core = current.core;
+      current.refs[this._id] = this;
+    } else {
+      this._core = new KeyborgCore(win);
+      win.__keyborg = {
+        core: this._core,
+        refs: {
+          [this._id]: this
+        }
+      };
+    }
+  }
+
+  static create(win) {
+    return new Keyborg(win);
+  }
+
+  static dispose(instance) {
+    instance.dispose();
+  }
+  /**
+   * Updates all subscribed callbacks with the keyboard navigation state
+   */
+
+
+  static update(instance, isNavigatingWithKeyboard) {
+    instance._cb.forEach(callback => callback(isNavigatingWithKeyboard));
+  }
+
+  dispose() {
+    var _a;
+
+    const current = (_a = this._win) === null || _a === void 0 ? void 0 : _a.__keyborg;
+
+    if (current === null || current === void 0 ? void 0 : current.refs[this._id]) {
+      delete current.refs[this._id];
+
+      if (Object.keys(current.refs).length === 0) {
+        current.core.dispose(); // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+
+        delete this._win.__keyborg;
+      }
+    } else if (process.env.NODE_ENV === 'development') {
+      console.error("Keyborg instance " + this._id + " is being disposed incorrectly.");
+    }
+
+    this._cb = [];
+    delete this._core;
+    delete this._win;
+  }
+  /**
+   * @returns Whether the user is navigating with keyboard
+   */
+
+
+  isNavigatingWithKeyboard() {
+    return _state.getVal();
+  }
+  /**
+   * @param callback - Called when the keyboard navigation state changes
+   */
+
+
+  subscribe(callback) {
+    this._cb.push(callback);
+  }
+  /**
+   * @param callback - Registered with subscribe
+   */
+
+
+  unsubscribe(callback) {
+    const index = this._cb.indexOf(callback);
+
+    if (index >= 0) {
+      this._cb.splice(index, 1);
+    }
+  }
+  /**
+   * Manually set the keyboard navigtion state
+   */
+
+
+  setVal(isNavigatingWithKeyboard) {
+    _state.setVal(isNavigatingWithKeyboard);
+  }
+
+}
+function createKeyborg(win) {
+  return Keyborg.create(win);
+}
+function disposeKeyborg(instance) {
+  Keyborg.dispose(instance);
+}
+
+export { Keyborg, KeyborgState, createKeyborg, disposeKeyborg };
+//# sourceMappingURL=Keyborg.js.map

package/lib/Keyborg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Keyborg.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/lib/WeakRefInstance.d.ts

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export declare const _canUseWeakRef: boolean;
+/**
+ * Allows disposable instances to be used
+ */
+export interface Disposable {
+    isDisposed?(): boolean;
+}
+/**
+ * WeakRef wrapper around a HTMLElement that also supports IE11
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef}
+ * @internal
+ */
+export declare class WeakRefInstance<T extends Disposable | object> {
+    private _weakRef?;
+    private _instance?;
+    constructor(instance: T);
+    /**
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef/deref}
+     */
+    deref(): T | undefined;
+}

package/lib/WeakRefInstance.js

@@ -0,0 +1,51 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+// IE11 compat, checks if WeakRef is supported
+const _canUseWeakRef = typeof WeakRef !== "undefined";
+/**
+ * WeakRef wrapper around a HTMLElement that also supports IE11
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef}
+ * @internal
+ */
+
+class WeakRefInstance {
+  constructor(instance) {
+    if (_canUseWeakRef && typeof instance === "object") {
+      this._weakRef = new WeakRef(instance);
+    } else {
+      this._instance = instance;
+    }
+  }
+  /**
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef/deref}
+   */
+
+
+  deref() {
+    var _a, _b, _c;
+
+    let instance;
+
+    if (this._weakRef) {
+      instance = (_a = this._weakRef) === null || _a === void 0 ? void 0 : _a.deref();
+
+      if (!instance) {
+        delete this._weakRef;
+      }
+    } else {
+      instance = this._instance;
+
+      if ((_c = (_b = instance) === null || _b === void 0 ? void 0 : _b.isDisposed) === null || _c === void 0 ? void 0 : _c.call(_b)) {
+        delete this._instance;
+      }
+    }
+
+    return instance;
+  }
+
+}
+
+export { WeakRefInstance, _canUseWeakRef };
+//# sourceMappingURL=WeakRefInstance.js.map

package/lib/WeakRefInstance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WeakRefInstance.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}