microsoft / keyborg

A library that tracks browser keyboard focus state that powers tabster

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

# NPM
npm install --save keyborg
# Yarn
yarn add keyborg

Usage

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. For more information see the Code of Conduct FAQ or contact [email protected] 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. 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.

keyborg's Issues

Any keypress from editable elements does not set keyboard navigation mode

keyborg/src/Keyborg.ts

Lines 244 to 253 in 197b994

	if (
	activeElement &&
	(activeElement.tagName === "INPUT" ||
	activeElement.tagName === "TEXTAREA" ||
	activeElement.contentEditable === "true")
	) {
	// We're inside an input, textarea or contenteditable, it's not
	// keyboard navigation, it is text editing scenario.
	return;
	}

The current keyboard navigation check is done so that any keypress (even ones explicitly set by the user) will not trigger keyboard navigation mode. This results in keys like Tab not triggering keyboard navigation mode:

Repro: https://codesandbox.io/p/sandbox/laughing-julien-fzkln2?file=%2Fsrc%2Fexample.tsx

1. Click on the input
2. Press tab
3. First button does not have a focus outline

Add export maps

Avoid users deep importing internals

Keyboard navigation state is triggered when user types in an input field

Repro: https://codesandbox.io/s/mutable-https-bcgblb?file=/example.tsx

• focus input field
• type inside input field
• hover over menu items
• there is a focus ring on menu items 🚨

The above is caused because keyborg detects keydown events on input fields as keyboard interaction

Cover base scenarios with Playwright tests

Currently repository has zero test coverage. We need to solve this and cover base scenarios including Shadow DOM support.

KeyborgState not updated when render two react projects

Describe the issue:

There are two separate React projects, each bundled with the FluentUI library. Consequently, the Keyborg library is also divided and bundled separately in these two projects on the same page.

Both projects feature a Dialog component. However, when attempting to open the Dialog in the second project (which loaded after the first project), the buttons inside it cannot be focused using the tab key. This issue arises because the focus ring style is lost.

Reproduction in Codepen: https://codesandbox.io/s/fluentui-bug-report-dqkq5q?file=/example.tsx

The related Bug item in Azure Board: Bug 16980: [Dialog]: [button in dialog do not have focus ring] button in dialog do not have focus ring when render two react project

Root cause I found:

Quick summary:
There are two Keyborg scripts bundled separately on the same page, and both bundles share the same global variable window.__keyborg, as well as the same KeyborgCore instance, KeyborgCore adds focus event listeners to the document to control the updation of _isNavigatingWithKeyboard variable in KeyborgState. However, the KeyborgState is not designed to be shared between the two projects. As a result, when a focus event occurs in the second project, it triggers a change of state in the first project instead of affecting the second project itself.

Proposal:
To resolve the issue, make KeyborgState sharable by converting it into a private variable within the KeyborgCore class.

Keyborg focusin event should include information if the focus was moved as a result of pressing `Tab`

The keyborg event should include information if the focus was moved as result of pressing the Tab key or not. This means that :focus-visible can be reliably applied.

This information is useful since if focus was moved using other ways, there might need to be extra handling to provide the functionality of :focus-visible

KeyborgCallback not exported

Libraries that want to type callbacks for keyborg don't have the appropriate type and are resorting to deep imports microsoft/fluentui#20892

bug: DTS breaking changes starting v2.4.x - errors on typescript 3.9

Looks like after switch to tsup leveraging their dts rolluping, the emit is transforming output in a way that breaks older TS versions that are supported in fluent.

export type {
  KeyborgFocusInEvent,
  KeyborgFocusInEventDetails,
} from "./FocusEvent";
export {
  getLastFocusedProgrammatically,
  nativeFocus,
  KEYBORG_FOCUSIN,
} from "./FocusEvent";

transforms to ⬇⬇⬇

export { 
KEYBORG_FOCUSIN, 
Keyborg, 
- type KeyborgCallback, 
- type KeyborgFocusInEvent, 
- type KeyborgFocusInEventDetails, 
createKeyborg, 
disposeKeyborg, 
getLastFocusedProgrammatically, 
nativeFocus, 
version 
};

This is currently breaking every pipeline in fluent monorepo, which will break any partner that is on TS lower than 4.5

https://uifabric.visualstudio.com/fabricpublic/_build/results?buildId=329898&view=logs&j=e51d397b-0a7b-5b89-4b48-0052e021371d&t=88c41216-94ff-5ca8-d686-48ce16c1eefc

Fix:

quickest fix ATM is to transform final dts output. either on your own by using TS AST or you can use https://github.com/sandersn/downlevel-dts

Remarks:

Going forward there is an initiative going on in fluent v-build to unify all repos around fluent to adhere to same tools, standards etc so things like this could never happen again. We should talk about this offline.

Keyborg instance is being disposed incorrectly.

I have @fluentui/react-components v9.47.4 running, on top of

• React v18.2.0
• Typescript v5.4.4
• vite v5.2.8.

While using FluentUI's Combobox, if I open the Listbox, but close it by clicking anywhere else in the page (making no changes in the option selection), I get following error in the console.

Keyborg instance k92 is being disposed incorrectly. 
Listbox<@http://localhost:3000/node_modules/.vite/deps/@fluentui_react-components.js?v=b3261b54:2087:36
span
Portal@http://localhost:3000/node_modules/.vite/deps/chunk-CYIF2TGV.js?v=c6d9a24b:241:35 [my-data:13441:25](http://localhost:3000/XXX)
    overrideMethod my-component:13441
    dispose Keyborg.ts:311
    dispose Keyborg.ts:271
    disposeKeyborg Keyborg.ts:361
    useKeyborg useKeyborg.js:14
   ...

This also has caused the Combobox lose its ability to show the border around the it's options if I navigate through those using ⬆️⬇️ arrows.

Above error doesn't surface if I change the Combobox selected options.

Not sure if this is FluentUI's issue, but being unable to reproduce this issue somewhere else, I prefer posting it here.