From f251d153d55e43ec84c6012fa09352b251133f20 Mon Sep 17 00:00:00 2001
From: Philipp Fritsche <ph.fritsche@gmail.com>
Date: Tue, 16 Mar 2021 20:14:47 +0100
Subject: [PATCH] feat: add userEvent.keyboard API (#581)

BREAKING CHANGE: `userEvent.type` features a rewritten implementation shared with the new `userEvent.keyboard`. This might break code depending on unintended/undocumented behavior of the previous implementation.

BREAKING CHANGE: `userEvent.type` treats `{` and `[` as special characters.

BREAKING CHANGE: `userEvent.type` returns no Promise if called without `delay`.
---
 .eslintrc.js                                  |  14 +
 README.md                                     |  77 +-
 package.json                                  |   2 +
 src/__tests__/keyboard/getNextKeyDef.ts       |  78 ++
 src/__tests__/keyboard/index.ts               | 137 +++
 src/__tests__/type-modifiers.js               |   5 +-
 src/__tests__/type.js                         |  20 +-
 src/__tests__/type/plugin/arrow.ts            |  45 +
 src/__tests__/type/plugin/character.ts        |  19 +
 src/__tests__/type/plugin/control.ts          |  48 ++
 src/__tests__/type/plugin/functional.ts       |  76 ++
 src/click.d.ts                                |  10 +
 src/index.js                                  |   2 +
 src/keyboard/getEventProps.ts                 |  27 +
 src/keyboard/getNextKeyDef.ts                 | 135 +++
 src/keyboard/index.ts                         |  75 ++
 src/keyboard/keyMap.ts                        |  79 ++
 src/keyboard/keyboardImplementation.ts        | 196 +++++
 src/keyboard/plugins/arrow.ts                 |  30 +
 src/keyboard/plugins/character.ts             | 184 ++++
 src/keyboard/plugins/control.ts               |  45 +
 .../control/calculateNewDeleteValue.ts        |  33 +
 src/keyboard/plugins/functional.ts            | 140 +++
 .../functional/calculateBackspaceValue.ts     |  43 +
 src/keyboard/plugins/index.ts                 |  43 +
 .../shared/fireChangeForInputTimeIfValid.ts   |  12 +
 src/keyboard/shared/fireInputEventIfNeeded.ts |  63 ++
 src/keyboard/shared/index.ts                  |   3 +
 src/keyboard/shared/setSelectionRange.ts      |  30 +
 src/keyboard/specialCharMap.ts                |  15 +
 src/keyboard/types.ts                         |  87 ++
 src/keys/navigation-key.js                    |  71 --
 src/type.js                                   | 800 ------------------
 src/type/index.ts                             |  34 +
 src/type/typeImplementation.ts                |  81 ++
 src/utils.js                                  | 384 ---------
 src/utils/click/getMouseEventOptions.ts       |  75 ++
 src/utils/click/isClickableInput.ts           |  18 +
 src/utils/edit/buildTimeValue.ts              |  32 +
 src/utils/edit/calculateNewValue.ts           | 103 +++
 src/utils/edit/getSelectionRange.ts           |  31 +
 src/utils/edit/getValue.ts                    |  12 +
 src/utils/edit/isContentEditable.ts           |   8 +
 src/utils/edit/isValidDateValue.ts            |   8 +
 src/utils/edit/isValidInputTimeValue.ts       |   8 +
 .../edit/setSelectionRangeIfNecessary.ts      |  46 +
 src/utils/focus/getActiveElement.ts           |  21 +
 src/utils/focus/isFocusable.ts                |   9 +
 src/utils/focus/selector.ts                   |  10 +
 src/utils/index.ts                            |  22 +
 src/utils/misc/eventWrapper.ts                |   9 +
 src/utils/misc/isDisabled.ts                  |   5 +
 src/utils/misc/isInstanceOfElement.ts         |  40 +
 .../isLabelWithInternallyDisabledControl.ts   |  16 +
 src/utils/misc/isVisible.ts                   |  18 +
 src/utils/misc/wait.ts                        |   3 +
 tsconfig.json                                 |   7 +
 typings/dom-helpers.d.ts                      |   3 +
 typings/index.d.ts                            |  60 +-
 typings/test.ts                               |   4 +-
 60 files changed, 2394 insertions(+), 1317 deletions(-)
 create mode 100644 .eslintrc.js
 create mode 100644 src/__tests__/keyboard/getNextKeyDef.ts
 create mode 100644 src/__tests__/keyboard/index.ts
 create mode 100644 src/__tests__/type/plugin/arrow.ts
 create mode 100644 src/__tests__/type/plugin/character.ts
 create mode 100644 src/__tests__/type/plugin/control.ts
 create mode 100644 src/__tests__/type/plugin/functional.ts
 create mode 100644 src/click.d.ts
 create mode 100644 src/keyboard/getEventProps.ts
 create mode 100644 src/keyboard/getNextKeyDef.ts
 create mode 100644 src/keyboard/index.ts
 create mode 100644 src/keyboard/keyMap.ts
 create mode 100644 src/keyboard/keyboardImplementation.ts
 create mode 100644 src/keyboard/plugins/arrow.ts
 create mode 100644 src/keyboard/plugins/character.ts
 create mode 100644 src/keyboard/plugins/control.ts
 create mode 100644 src/keyboard/plugins/control/calculateNewDeleteValue.ts
 create mode 100644 src/keyboard/plugins/functional.ts
 create mode 100644 src/keyboard/plugins/functional/calculateBackspaceValue.ts
 create mode 100644 src/keyboard/plugins/index.ts
 create mode 100644 src/keyboard/shared/fireChangeForInputTimeIfValid.ts
 create mode 100644 src/keyboard/shared/fireInputEventIfNeeded.ts
 create mode 100644 src/keyboard/shared/index.ts
 create mode 100644 src/keyboard/shared/setSelectionRange.ts
 create mode 100644 src/keyboard/specialCharMap.ts
 create mode 100644 src/keyboard/types.ts
 delete mode 100644 src/keys/navigation-key.js
 delete mode 100644 src/type.js
 create mode 100644 src/type/index.ts
 create mode 100644 src/type/typeImplementation.ts
 delete mode 100644 src/utils.js
 create mode 100644 src/utils/click/getMouseEventOptions.ts
 create mode 100644 src/utils/click/isClickableInput.ts
 create mode 100644 src/utils/edit/buildTimeValue.ts
 create mode 100644 src/utils/edit/calculateNewValue.ts
 create mode 100644 src/utils/edit/getSelectionRange.ts
 create mode 100644 src/utils/edit/getValue.ts
 create mode 100644 src/utils/edit/isContentEditable.ts
 create mode 100644 src/utils/edit/isValidDateValue.ts
 create mode 100644 src/utils/edit/isValidInputTimeValue.ts
 create mode 100644 src/utils/edit/setSelectionRangeIfNecessary.ts
 create mode 100644 src/utils/focus/getActiveElement.ts
 create mode 100644 src/utils/focus/isFocusable.ts
 create mode 100644 src/utils/focus/selector.ts
 create mode 100644 src/utils/index.ts
 create mode 100644 src/utils/misc/eventWrapper.ts
 create mode 100644 src/utils/misc/isDisabled.ts
 create mode 100644 src/utils/misc/isInstanceOfElement.ts
 create mode 100644 src/utils/misc/isLabelWithInternallyDisabledControl.ts
 create mode 100644 src/utils/misc/isVisible.ts
 create mode 100644 src/utils/misc/wait.ts
 create mode 100644 tsconfig.json
 create mode 100644 typings/dom-helpers.d.ts

diff --git a/.eslintrc.js b/.eslintrc.js
new file mode 100644
index 00000000..b9e85808
--- /dev/null
+++ b/.eslintrc.js
@@ -0,0 +1,14 @@
+module.exports = {
+  extends: './node_modules/kcd-scripts/eslint.js',
+  settings: {
+    'import/resolver': {
+      node: {
+        extensions: ['.js', '.ts'],
+      },
+    },
+  },
+  rules: {
+    'testing-library/no-dom-import': 0,
+    '@typescript-eslint/non-nullable-type-assertion-style': 0,
+  },
+}
diff --git a/README.md b/README.md
index 3abeee53..751c6418 100644
--- a/README.md
+++ b/README.md
@@ -52,7 +52,8 @@ change the state of the checkbox.
   - [`click(element, eventInit, options)`](#clickelement-eventinit-options)
   - [`dblClick(element, eventInit, options)`](#dblclickelement-eventinit-options)
   - [`type(element, text, [options])`](#typeelement-text-options)
-  - [`upload(element, file, [{ clickInit, changeInit }])`](#uploadelement-file--clickinit-changeinit-)
+  - [`keyboard(text, options)`](#keyboardtext-options)
+  - [`upload(element, file, [{ clickInit, changeInit }], [options])`](#uploadelement-file--clickinit-changeinit--options)
   - [`clear(element)`](#clearelement)
   - [`selectOptions(element, values)`](#selectoptionselement-values)
   - [`deselectOptions(element, values)`](#deselectoptionselement-values)
@@ -178,10 +179,6 @@ are typed. By default it's 0. You can use this option if your component has a
 different behavior for fast or slow users. If you do this, you need to make sure
 to `await`!
 
-> To be clear, `userEvent.type` _always_ returns a promise, but you _only_ need
-> to `await` the promise it returns if you're using the `delay` option.
-> Otherwise everything runs synchronously and you can ignore the promise.
-
 `type` will click the element before typing. To disable this, set the
 `skipClick` option to `true`.
 
@@ -271,6 +268,76 @@ test('types into the input', () => {
 })
 ```
 
+### `keyboard(text, options)`
+
+Simulates the keyboard events described by `text`. This is similar to
+`userEvent.type()` but without any clicking or changing the selection range.
+
+> You should use `userEvent.keyboard` if you want to just simulate pressing
+> buttons on the keyboard. You should use `userEvent.type` if you just want to
+> conveniently insert some text into an input field or textarea.
+
+Keystrokes can be described:
+
+- Per printable character
+  ```js
+  userEvent.keyboard('foo') // translates to: f, o, o
+  ```
+  The brackets `{` and `[` are used as special character and can be referenced
+  by doubling them.
+  ```js
+  userEvent.keyboard('{{a[[') // translates to: {, a, [
+  ```
+- Per
+  [KeyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
+  (only supports alphanumeric values of `key`)
+  ```js
+  userEvent.keyboard('{Shift}{f}{o}{o}') // translates to: Shift, f, o, o
+  ```
+  This does not keep any key pressed. So `Shift` will be lifted before pressing
+  `f`.
+- Per
+  [KeyboardEvent.code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code)
+  ```js
+  userEvent.keyboard('[ShiftLeft][KeyF][KeyO][KeyO]') // translates to: Shift, f, o, o
+  ```
+- Per legacy `userEvent.type` modifier/specialChar The modifiers like `{shift}`
+  (note the lowercase) will automatically be kept pressed, just like before. You
+  can cancel this behavior by adding a `/` to the end of the descriptor.
+  ```js
+  userEvent.keyboard('{shift}{ctrl/}a{/shift}') // translates to: Shift(down), Control(down+up), a, Shift(up)
+  ```
+
+Keys can be kept pressed by adding a `>` to the end of the descriptor - and
+lifted by adding a `/` to the beginning of the descriptor:
+
+```js
+userEvent.keyboard('{Shift>}A{/Shift}') // translates to: Shift(down), A, Shift(up)
+```
+
+`userEvent.keyboard` returns a keyboard state that can be used to continue
+keyboard operations.
+
+```js
+const keyboardState = userEvent.keyboard('[ControlLeft>]') // keydown [ControlLeft]
+// ... inspect some changes ...
+userEvent.keyboard('a', {keyboardState}) // press [KeyA] with active ctrlKey modifier
+```
+
+The mapping of `key` to `code` is performed by a
+[default key map](https://github.com/testing-library/user-event/blob/master/src/keyboard/keyMap.ts)
+portraying a "default" US-keyboard. You can provide your own local keyboard
+mapping per option.
+
+```js
+userEvent.keyboard('?', {keyboardMap: myOwnLocaleKeyboardMap})
+```
+
+> Future versions might try to interpolate the modifiers needed to reach a
+> printable key on the keyboard. E.g. Automatically pressing `{Shift}` when
+> CapsLock is not active and `A` is referenced. If you don't wish this behavior,
+> you can pass `autoModify: false` when using `userEvent.keyboard` in your code.
+
 ### `upload(element, file, [{ clickInit, changeInit }], [options])`
 
 Uploads file to an `<input>`. For uploading multiple files use `<input>` with
diff --git a/package.json b/package.json
index 766de19f..9e4ee802 100644
--- a/package.json
+++ b/package.json
@@ -45,7 +45,9 @@
     "@testing-library/dom": "^7.28.1",
     "@testing-library/jest-dom": "^5.11.6",
     "@types/estree": "0.0.45",
+    "@types/jest-in-case": "^1.0.3",
     "is-ci": "^2.0.0",
+    "jest-in-case": "^1.0.2",
     "jest-serializer-ansi": "^1.0.3",
     "kcd-scripts": "^7.5.1",
     "typescript": "^4.1.2"
diff --git a/src/__tests__/keyboard/getNextKeyDef.ts b/src/__tests__/keyboard/getNextKeyDef.ts
new file mode 100644
index 00000000..fc6344f7
--- /dev/null
+++ b/src/__tests__/keyboard/getNextKeyDef.ts
@@ -0,0 +1,78 @@
+import cases from 'jest-in-case'
+import {getNextKeyDef} from 'keyboard/getNextKeyDef'
+import {defaultKeyMap} from 'keyboard/keyMap'
+import {keyboardKey, keyboardOptions} from 'keyboard/types'
+
+const options: keyboardOptions = {
+  document,
+  keyboardMap: defaultKeyMap,
+  autoModify: false,
+  delay: 123,
+}
+
+cases(
+  'reference key per',
+  ({text, key, code}) => {
+    expect(getNextKeyDef(`${text}foo`, options)).toEqual(
+      expect.objectContaining({
+        keyDef: expect.objectContaining({
+          key,
+          code,
+        }) as keyboardKey,
+      }),
+    )
+  },
+  {
+    code: {text: '[ControlLeft]', key: 'Control', code: 'ControlLeft'},
+    'unimplemented code': {text: '[Foo]', key: 'Unknown', code: 'Foo'},
+    key: {text: '{Control}', key: 'Control', code: 'ControlLeft'},
+    'unimplemented key': {text: '{Foo}', key: 'Foo', code: 'Unknown'},
+    'legacy modifier': {text: '{ctrl}', key: 'Control', code: 'ControlLeft'},
+    'printable character': {text: 'a', key: 'a', code: 'KeyA'},
+    '{ as printable': {text: '{{', key: '{', code: 'Unknown'},
+    '[ as printable': {text: '[[', key: '[', code: 'Unknown'},
+  },
+)
+
+cases(
+  'modifiers',
+  ({text, modifiers}) => {
+    expect(getNextKeyDef(`${text}foo`, options)).toEqual(
+      expect.objectContaining(modifiers),
+    )
+  },
+  {
+    'no releasePrevious': {
+      text: '{Control}',
+      modifiers: {releasePrevious: false},
+    },
+    'releasePrevious per key': {
+      text: '{/Control}',
+      modifiers: {releasePrevious: true},
+    },
+    'releasePrevious per code': {
+      text: '[/ControlLeft]',
+      modifiers: {releasePrevious: true},
+    },
+    'default releaseSelf': {
+      text: '{Control}',
+      modifiers: {releaseSelf: true},
+    },
+    'keep key pressed per key': {
+      text: '{Control>}',
+      modifiers: {releaseSelf: false},
+    },
+    'keep key pressed per code': {
+      text: '[Control>]',
+      modifiers: {releaseSelf: false},
+    },
+    'no releaseSelf on legacy modifier': {
+      text: '{ctrl}',
+      modifiers: {releaseSelf: false},
+    },
+    'release legacy modifier': {
+      text: '{ctrl/}',
+      modifiers: {releaseSelf: true},
+    },
+  },
+)
diff --git a/src/__tests__/keyboard/index.ts b/src/__tests__/keyboard/index.ts
new file mode 100644
index 00000000..a8e4770b
--- /dev/null
+++ b/src/__tests__/keyboard/index.ts
@@ -0,0 +1,137 @@
+import userEvent from '../../index'
+import {addListeners, setup} from '../helpers/utils'
+
+it('type without focus', () => {
+  const {element} = setup('<input/>')
+  const {getEventSnapshot} = addListeners(document.body)
+
+  userEvent.keyboard('foo')
+
+  expect(element).toHaveValue('')
+  expect(getEventSnapshot()).toMatchInlineSnapshot(`
+    Events fired on: body
+
+    body - keydown: f (102)
+    body - keypress: f (102)
+    body - keyup: f (102)
+    body - keydown: o (111)
+    body - keypress: o (111)
+    body - keyup: o (111)
+    body - keydown: o (111)
+    body - keypress: o (111)
+    body - keyup: o (111)
+  `)
+})
+
+it('type with focus', () => {
+  const {element} = setup('<input/>')
+  const {getEventSnapshot} = addListeners(document.body)
+  ;(element as HTMLInputElement).focus()
+
+  userEvent.keyboard('foo')
+
+  expect(element).toHaveValue('foo')
+  expect(getEventSnapshot()).toMatchInlineSnapshot(`
+    Events fired on: body
+
+    input[value=""] - focusin
+    input[value=""] - keydown: f (102)
+    input[value=""] - keypress: f (102)
+    input[value="f"] - input
+    input[value="f"] - keyup: f (102)
+    input[value="f"] - keydown: o (111)
+    input[value="f"] - keypress: o (111)
+    input[value="fo"] - input
+    input[value="fo"] - keyup: o (111)
+    input[value="fo"] - keydown: o (111)
+    input[value="fo"] - keypress: o (111)
+    input[value="foo"] - input
+    input[value="foo"] - keyup: o (111)
+  `)
+})
+
+it('type asynchronous', async () => {
+  const {element} = setup('<input/>')
+  const {getEventSnapshot} = addListeners(document.body)
+  ;(element as HTMLInputElement).focus()
+
+  // eslint-disable-next-line testing-library/no-await-sync-events
+  await userEvent.keyboard('foo', {delay: 1})
+
+  expect(element).toHaveValue('foo')
+  expect(getEventSnapshot()).toMatchInlineSnapshot(`
+    Events fired on: body
+
+    input[value=""] - focusin
+    input[value=""] - keydown: f (102)
+    input[value=""] - keypress: f (102)
+    input[value="f"] - input
+    input[value="f"] - keyup: f (102)
+    input[value="f"] - keydown: o (111)
+    input[value="f"] - keypress: o (111)
+    input[value="fo"] - input
+    input[value="fo"] - keyup: o (111)
+    input[value="fo"] - keydown: o (111)
+    input[value="fo"] - keypress: o (111)
+    input[value="foo"] - input
+    input[value="foo"] - keyup: o (111)
+  `)
+})
+
+describe('error', () => {
+  afterEach(() => {
+    ;(console.error as jest.MockedFunction<typeof console.error>).mockClear()
+  })
+
+  it('error in sync', async () => {
+    const err = jest.spyOn(console, 'error')
+    err.mockImplementation(() => {})
+
+    userEvent.keyboard('{!')
+
+    // the catch will be asynchronous
+    await Promise.resolve()
+
+    expect(err).toHaveBeenCalledWith(expect.any(Error))
+    expect(err.mock.calls[0][0]).toHaveProperty(
+      'message',
+      'Expected key descriptor but found "!" in "{!"',
+    )
+  })
+
+  it('error in async', async () => {
+    const promise = userEvent.keyboard('{!', {delay: 1})
+
+    return expect(promise).rejects.toThrowError(
+      'Expected key descriptor but found "!" in "{!"',
+    )
+  })
+})
+
+it('continue typing with state', () => {
+  const {element, getEventSnapshot, clearEventCalls} = setup('<input/>')
+  ;(element as HTMLInputElement).focus()
+  clearEventCalls()
+
+  const state = userEvent.keyboard('[ShiftRight>]')
+
+  expect(getEventSnapshot()).toMatchInlineSnapshot(`
+    Events fired on: input[value=""]
+
+    input[value=""] - keydown: Shift (16) {shift}
+  `)
+  clearEventCalls()
+
+  userEvent.keyboard('F[/ShiftRight]', {keyboardState: state})
+
+  expect(getEventSnapshot()).toMatchInlineSnapshot(`
+    Events fired on: input[value="F"]
+
+    input[value=""] - keydown: F (70) {shift}
+    input[value=""] - keypress: F (70) {shift}
+    input[value="F"] - input
+      "{CURSOR}" -> "F{CURSOR}"
+    input[value="F"] - keyup: F (70) {shift}
+    input[value="F"] - keyup: Shift (16)
+  `)
+})
diff --git a/src/__tests__/type-modifiers.js b/src/__tests__/type-modifiers.js
index 4bfe28b0..c0a447b2 100644
--- a/src/__tests__/type-modifiers.js
+++ b/src/__tests__/type-modifiers.js
@@ -353,10 +353,11 @@ test('{shift}a{/shift}', () => {
   `)
 })
 
-test('{capslock}a{/capslock}', () => {
+test('{capslock}a{capslock}', () => {
   const {element, getEventSnapshot} = setup('<input />')
 
-  userEvent.type(element, '{capslock}a{/capslock}')
+  // The old behavior to treat {/capslock} like {capslock} makes no sense
+  userEvent.type(element, '{capslock}a{capslock}')
 
   expect(getEventSnapshot()).toMatchInlineSnapshot(`
     Events fired on: input[value="a"]
diff --git a/src/__tests__/type.js b/src/__tests__/type.js
index 9940e78a..7cc35808 100644
--- a/src/__tests__/type.js
+++ b/src/__tests__/type.js
@@ -246,7 +246,7 @@ test('should delay the typing when opts.delay is not 0', async () => {
   await userEvent.type(element, text, {delay})
 
   expect(onInput).toHaveBeenCalledTimes(text.length)
-  for (let index = 1; index < inputValues.length; index++) {
+  for (let index = 2; index < inputValues.length; index++) {
     const {timestamp, value} = inputValues[index]
     expect(timestamp - inputValues[index - 1].timestamp).toBeGreaterThanOrEqual(
       delay,
@@ -792,9 +792,7 @@ test('typing an invalid input value', () => {
   const {element} = setup('<input type="number" />')
   userEvent.type(element, '3-3')
 
-  // TODO: fix this bug
-  // THIS IS A BUG! It should be expect(element.value).toBe('')
-  expect(element).toHaveValue(-3)
+  expect(element).toHaveValue(null)
 
   // THIS IS A LIMITATION OF THE BROWSER
   // It is impossible to programmatically set an input
@@ -805,10 +803,10 @@ test('typing an invalid input value', () => {
 
 test('should not throw error if we are trying to call type on an element without a value', () => {
   const {element} = setup('<div />')
-  expect.assertions(0)
-  return userEvent
-    .type(element, "I'm only a div :(")
-    .catch(e => expect(e).toBeUndefined())
+
+  return expect(userEvent.type(element, ':(', {delay: 1})).resolves.toBe(
+    undefined,
+  )
 })
 
 test('typing on button should not alter its value', () => {
@@ -849,8 +847,10 @@ test('typing on input type submit should not alter its value', () => {
 
 test('typing on input type file should not result in an error', () => {
   const {element} = setup('<input type="file" />')
-  expect.assertions(0)
-  return userEvent.type(element, 'bar').catch(e => expect(e).toBeUndefined())
+
+  return expect(userEvent.type(element, 'bar', {delay: 1})).resolves.toBe(
+    undefined,
+  )
 })
 
 test('should submit a form containing multiple text inputs and an input of type submit', () => {
diff --git a/src/__tests__/type/plugin/arrow.ts b/src/__tests__/type/plugin/arrow.ts
new file mode 100644
index 00000000..3dea28c1
--- /dev/null
+++ b/src/__tests__/type/plugin/arrow.ts
@@ -0,0 +1,45 @@
+import userEvent from 'index'
+import {setup} from '__tests__/helpers/utils'
+
+const setupInput = () =>
+  setup(`<input value="foobar"/>`).element as HTMLInputElement
+
+test('collapse selection to the left', () => {
+  const el = setupInput()
+  el.setSelectionRange(2, 4)
+
+  userEvent.type(el, '[ArrowLeft]')
+
+  expect(el.selectionStart).toBe(2)
+  expect(el.selectionEnd).toBe(2)
+})
+
+test('collapse selection to the right', () => {
+  const el = setupInput()
+  el.setSelectionRange(2, 4)
+
+  userEvent.type(el, '[ArrowRight]')
+
+  expect(el.selectionStart).toBe(4)
+  expect(el.selectionEnd).toBe(4)
+})
+
+test('move cursor left', () => {
+  const el = setupInput()
+  el.setSelectionRange(2, 2)
+
+  userEvent.type(el, '[ArrowLeft]')
+
+  expect(el.selectionStart).toBe(1)
+  expect(el.selectionEnd).toBe(1)
+})
+
+test('move cursor right', () => {
+  const el = setupInput()
+  el.setSelectionRange(2, 2)
+
+  userEvent.type(el, '[ArrowRight]')
+
+  expect(el.selectionStart).toBe(3)
+  expect(el.selectionEnd).toBe(3)
+})
diff --git a/src/__tests__/type/plugin/character.ts b/src/__tests__/type/plugin/character.ts
new file mode 100644
index 00000000..095acea1
--- /dev/null
+++ b/src/__tests__/type/plugin/character.ts
@@ -0,0 +1,19 @@
+import userEvent from 'index'
+import {setup} from '__tests__/helpers/utils'
+
+test('type [Enter] in textarea', () => {
+  const {element} = setup(`<textarea>f</textarea>`)
+
+  userEvent.type(element as HTMLTextAreaElement, 'oo[Enter]bar')
+
+  expect(element).toHaveValue('foo\nbar')
+})
+
+test('type [Enter] in contenteditable', () => {
+  const {element} = setup(`<div contenteditable="true">f</div>`)
+
+  userEvent.type(element as HTMLTextAreaElement, 'oo[Enter]bar')
+
+  expect(element).toHaveTextContent('foo bar')
+  expect(element?.firstChild).toHaveProperty('nodeValue', 'foo\nbar')
+})
diff --git a/src/__tests__/type/plugin/control.ts b/src/__tests__/type/plugin/control.ts
new file mode 100644
index 00000000..9f0e476a
--- /dev/null
+++ b/src/__tests__/type/plugin/control.ts
@@ -0,0 +1,48 @@
+import userEvent from 'index'
+import {setup} from '__tests__/helpers/utils'
+
+test('press [Home] in textarea', () => {
+  const {element} = setup(`<textarea>foo\nbar\baz</textarea>`)
+  ;(element as HTMLTextAreaElement).setSelectionRange(2, 4)
+
+  userEvent.type(element as HTMLTextAreaElement, '[Home]')
+
+  expect(element).toHaveProperty('selectionStart', 0)
+  expect(element).toHaveProperty('selectionEnd', 0)
+})
+
+test('press [Home] in contenteditable', () => {
+  const {element} = setup(`<div contenteditable="true">foo\nbar\baz</div>`)
+  document
+    .getSelection()
+    ?.setPosition((element as HTMLDivElement).firstChild, 2)
+
+  userEvent.type(element as HTMLTextAreaElement, '[Home]')
+
+  const selection = document.getSelection()
+  expect(selection).toHaveProperty('focusNode', element?.firstChild)
+  expect(selection).toHaveProperty('focusOffset', 0)
+})
+
+test('press [End] in textarea', () => {
+  const {element} = setup(`<textarea>foo\nbar\baz</textarea>`)
+  ;(element as HTMLTextAreaElement).setSelectionRange(2, 4)
+
+  userEvent.type(element as HTMLTextAreaElement, '[End]')
+
+  expect(element).toHaveProperty('selectionStart', 10)
+  expect(element).toHaveProperty('selectionEnd', 10)
+})
+
+test('press [End] in contenteditable', () => {
+  const {element} = setup(`<div contenteditable="true">foo\nbar\baz</div>`)
+  document
+    .getSelection()
+    ?.setPosition((element as HTMLDivElement).firstChild, 2)
+
+  userEvent.type(element as HTMLTextAreaElement, '[End]')
+
+  const selection = document.getSelection()
+  expect(selection).toHaveProperty('focusNode', element?.firstChild)
+  expect(selection).toHaveProperty('focusOffset', 10)
+})
diff --git a/src/__tests__/type/plugin/functional.ts b/src/__tests__/type/plugin/functional.ts
new file mode 100644
index 00000000..dbc34938
--- /dev/null
+++ b/src/__tests__/type/plugin/functional.ts
@@ -0,0 +1,76 @@
+import userEvent from 'index'
+import {setup} from '__tests__/helpers/utils'
+
+test('produce extra events for the Control key when AltGraph is pressed', () => {
+  const {element, getEventSnapshot} = setup(`<input/>`)
+
+  userEvent.type(element as Element, '{AltGraph}')
+
+  expect(getEventSnapshot()).toMatchInlineSnapshot(`
+    Events fired on: input[value=""]
+
+    input[value=""] - pointerover
+    input[value=""] - pointerenter
+    input[value=""] - mouseover: Left (0)
+    input[value=""] - mouseenter: Left (0)
+    input[value=""] - pointermove
+    input[value=""] - mousemove: Left (0)
+    input[value=""] - pointerdown
+    input[value=""] - mousedown: Left (0)
+    input[value=""] - focus
+    input[value=""] - focusin
+    input[value=""] - pointerup
+    input[value=""] - mouseup: Left (0)
+    input[value=""] - click: Left (0)
+    input[value=""] - keydown: Control (17)
+    input[value=""] - keydown: AltGraph (0)
+    input[value=""] - keyup: AltGraph (0)
+    input[value=""] - keyup: Control (17)
+  `)
+})
+
+test('backspace to valid value', () => {
+  const {element, getEventSnapshot} = setup(`<input type="number"/>`)
+
+  userEvent.type(element as Element, '5e-[Backspace][Backspace]')
+
+  expect(element).toHaveValue(5)
+  expect(getEventSnapshot()).toMatchInlineSnapshot(`
+    Events fired on: input[value="5"]
+
+    input[value=""] - pointerover
+    input[value=""] - pointerenter
+    input[value=""] - mouseover: Left (0)
+    input[value=""] - mouseenter: Left (0)
+    input[value=""] - pointermove
+    input[value=""] - mousemove: Left (0)
+    input[value=""] - pointerdown
+    input[value=""] - mousedown: Left (0)
+    input[value=""] - focus
+    input[value=""] - focusin
+    input[value=""] - pointerup
+    input[value=""] - mouseup: Left (0)
+    input[value=""] - click: Left (0)
+    input[value=""] - keydown: 5 (53)
+    input[value=""] - keypress: 5 (53)
+    input[value="5"] - input
+      "{CURSOR}" -> "{CURSOR}5"
+    input[value="5"] - keyup: 5 (53)
+    input[value="5"] - keydown: e (101)
+    input[value="5"] - keypress: e (101)
+    input[value=""] - input
+      "{CURSOR}5" -> "{CURSOR}"
+    input[value=""] - keyup: e (101)
+    input[value=""] - keydown: - (45)
+    input[value=""] - keypress: - (45)
+    input[value=""] - input
+    input[value=""] - keyup: - (45)
+    input[value=""] - keydown: Backspace (8)
+    input[value=""] - input
+    input[value=""] - keyup: Backspace (8)
+    input[value=""] - keydown: Backspace (8)
+    input[value="5"] - input
+      "{CURSOR}" -> "{CURSOR}5"
+    input[value="5"] - keyup: Backspace (8)
+  `)
+})
diff --git a/src/click.d.ts b/src/click.d.ts
new file mode 100644
index 00000000..57ac45fc
--- /dev/null
+++ b/src/click.d.ts
@@ -0,0 +1,10 @@
+export declare interface clickOptions {
+  skipHover?: boolean
+  clickCount?: number
+}
+
+export declare function click(
+  element: TargetElement,
+  init?: MouseEventInit,
+  options?: clickOptions,
+): void
diff --git a/src/index.js b/src/index.js
index 2b610d97..28e4750a 100644
--- a/src/index.js
+++ b/src/index.js
@@ -6,6 +6,7 @@ import {hover, unhover} from './hover'
 import {upload} from './upload'
 import {selectOptions, deselectOptions} from './select-options'
 import {paste} from './paste'
+import {keyboard} from './keyboard'
 
 const userEvent = {
   click,
@@ -19,6 +20,7 @@ const userEvent = {
   selectOptions,
   deselectOptions,
   paste,
+  keyboard,
 }
 
 export default userEvent
diff --git a/src/keyboard/getEventProps.ts b/src/keyboard/getEventProps.ts
new file mode 100644
index 00000000..a530c8dd
--- /dev/null
+++ b/src/keyboard/getEventProps.ts
@@ -0,0 +1,27 @@
+import {keyboardKey, keyboardState} from './types'
+
+export function getKeyEventProps(keyDef: keyboardKey, state: keyboardState) {
+  return {
+    key: keyDef.key,
+    code: keyDef.code,
+    altKey: state.modifiers.alt,
+    ctrlKey: state.modifiers.ctrl,
+    metaKey: state.modifiers.meta,
+    shiftKey: state.modifiers.shift,
+
+    /** @deprecated use code instead */
+    keyCode:
+      keyDef.keyCode ??
+      // istanbul ignore next
+      (keyDef.key?.length === 1 ? keyDef.key.charCodeAt(0) : undefined),
+  }
+}
+
+export function getMouseEventProps(state: keyboardState) {
+  return {
+    altKey: state.modifiers.alt,
+    ctrlKey: state.modifiers.ctrl,
+    metaKey: state.modifiers.meta,
+    shiftKey: state.modifiers.shift,
+  }
+}
diff --git a/src/keyboard/getNextKeyDef.ts b/src/keyboard/getNextKeyDef.ts
new file mode 100644
index 00000000..bea29afb
--- /dev/null
+++ b/src/keyboard/getNextKeyDef.ts
@@ -0,0 +1,135 @@
+import {keyboardKey, keyboardOptions} from './types'
+
+/**
+ * Get the next key from keyMap
+ *
+ * Keys can be referenced by `{key}` or `{special}` as well as physical locations per `[code]`.
+ * Everything else will be interpreted as a typed character - e.g. `a`.
+ * Brackets `{` and `[` can be escaped by doubling - e.g. `foo[[bar` translates to `foo[bar`.
+ * Keeping the key pressed can be written as `{key>}`.
+ * Modifiers like `{shift}` imply being kept pressed. This can be turned of per `{shift/}`.
+ */
+export function getNextKeyDef(
+  text: string,
+  options: keyboardOptions,
+): {
+  keyDef: keyboardKey
+  consumedLength: number
+  releasePrevious: boolean
+  releaseSelf: boolean
+} {
+  const startBracket = ['{', '['].includes(text[0]) ? text[0] : ''
+  const startModifier = text[1] === '/' ? '/' : ''
+
+  const descriptorStart = startBracket.length + startModifier.length
+  const descriptor = startBracket
+    ? text[descriptorStart] === startBracket
+      ? startBracket
+      : text.slice(descriptorStart).match(/^\w+/)?.[0]
+    : text[descriptorStart]
+
+  // istanbul ignore if
+  if (!descriptor) {
+    throw new Error(
+      `Expected key descriptor but found "${text[descriptorStart]}" in "${text}"`,
+    )
+  }
+
+  const descriptorEnd = descriptorStart + descriptor.length
+  const endModifier =
+    descriptor !== startBracket && ['/', '>'].includes(text[descriptorEnd])
+      ? text[descriptorEnd]
+      : ''
+
+  const endBracket =
+    !startBracket || descriptor === startBracket
+      ? ''
+      : startBracket === '{'
+      ? '}'
+      : ']'
+
+  // istanbul ignore if
+  if (endBracket && text[descriptorEnd + endModifier.length] !== endBracket) {
+    throw new Error(
+      `Expected closing bracket but found "${
+        text[descriptorEnd + endModifier.length]
+      }" in "${text}"`,
+    )
+  }
+
+  const modifiers = {
+    consumedLength: [
+      startBracket,
+      startModifier,
+      descriptor,
+      endModifier,
+      endBracket,
+    ]
+      .map(c => c.length)
+      .reduce((a, b) => a + b),
+
+    releasePrevious: startModifier === '/',
+    releaseSelf: hasReleaseSelf(startBracket, descriptor, endModifier),
+  }
+
+  if (isPrintableCharacter(startBracket, descriptor)) {
+    return {
+      ...modifiers,
+      keyDef: options.keyboardMap.find(k => k.key === descriptor) ?? {
+        key: descriptor,
+        code: 'Unknown',
+      },
+    }
+  } else if (startBracket === '{') {
+    const key = mapLegacyKey(descriptor)
+    return {
+      ...modifiers,
+      keyDef: options.keyboardMap.find(
+        k => k.key?.toLowerCase() === key.toLowerCase(),
+      ) ?? {key: descriptor, code: 'Unknown'},
+    }
+  } else {
+    return {
+      ...modifiers,
+      keyDef: options.keyboardMap.find(
+        k => k.code?.toLowerCase() === descriptor.toLowerCase(),
+      ) ?? {key: 'Unknown', code: descriptor},
+    }
+  }
+}
+
+function hasReleaseSelf(
+  startBracket: string,
+  descriptor: string,
+  endModifier: string,
+) {
+  if (endModifier === '/' || !startBracket) {
+    return true
+  }
+  if (
+    startBracket === '{' &&
+    ['alt', 'ctrl', 'meta', 'shift'].includes(descriptor.toLowerCase())
+  ) {
+    return false
+  }
+  return endModifier !== '>'
+}
+
+function mapLegacyKey(descriptor: string) {
+  return (
+    {
+      ctrl: 'Control',
+      del: 'Delete',
+      esc: 'Escape',
+      space: ' ',
+    }[descriptor] ?? descriptor
+  )
+}
+
+function isPrintableCharacter(startBracket: string, descriptor: string) {
+  return (
+    !startBracket ||
+    startBracket === descriptor ||
+    (startBracket === '{' && descriptor.length === 1)
+  )
+}
diff --git a/src/keyboard/index.ts b/src/keyboard/index.ts
new file mode 100644
index 00000000..36827e3d
--- /dev/null
+++ b/src/keyboard/index.ts
@@ -0,0 +1,75 @@
+import {getConfig as getDOMTestingLibraryConfig} from '@testing-library/dom'
+import {keyboardImplementation, releaseAllKeys} from './keyboardImplementation'
+import {defaultKeyMap} from './keyMap'
+import {keyboardState, keyboardOptions, keyboardKey} from './types'
+
+export {specialCharMap} from './specialCharMap'
+export type {keyboardOptions, keyboardKey}
+
+export function keyboard(
+  text: string,
+  options?: Partial<keyboardOptions & {keyboardState: keyboardState; delay: 0}>,
+): keyboardState
+export function keyboard(
+  text: string,
+  options: Partial<
+    keyboardOptions & {keyboardState: keyboardState; delay: number}
+  >,
+): Promise<keyboardState>
+export function keyboard(
+  text: string,
+  options?: Partial<keyboardOptions & {keyboardState: keyboardState}>,
+): keyboardState | Promise<keyboardState> {
+  const {promise, state} = keyboardImplementationWrapper(text, options)
+
+  if ((options?.delay ?? 0) > 0) {
+    return getDOMTestingLibraryConfig().asyncWrapper(() =>
+      promise.then(() => state),
+    )
+  } else {
+    // prevent users from dealing with UnhandledPromiseRejectionWarning in sync call
+    promise.catch(console.error)
+
+    return state
+  }
+}
+
+export function keyboardImplementationWrapper(
+  text: string,
+  config: Partial<keyboardOptions & {keyboardState: keyboardState}> = {},
+) {
+  const {
+    keyboardState: state = createKeyboardState(),
+    delay = 0,
+    document: doc = document,
+    autoModify = false,
+    keyboardMap = defaultKeyMap,
+  } = config
+  const options = {
+    delay,
+    document: doc,
+    autoModify,
+    keyboardMap,
+  }
+
+  return {
+    promise: keyboardImplementation(text, options, state),
+    state,
+    releaseAllKeys: () => releaseAllKeys(options, state),
+  }
+}
+
+function createKeyboardState(): keyboardState {
+  return {
+    activeElement: null,
+    pressed: [],
+    carryChar: '',
+    modifiers: {
+      alt: false,
+      caps: false,
+      ctrl: false,
+      meta: false,
+      shift: false,
+    },
+  }
+}
diff --git a/src/keyboard/keyMap.ts b/src/keyboard/keyMap.ts
new file mode 100644
index 00000000..0e0a5520
--- /dev/null
+++ b/src/keyboard/keyMap.ts
@@ -0,0 +1,79 @@
+import {DOM_KEY_LOCATION, keyboardKey} from './types'
+
+/**
+ * Mapping for a default US-104-QWERTY keyboard
+ */
+export const defaultKeyMap: keyboardKey[] = [
+  // alphanumeric keys
+  ...'0123456789'.split('').map(c => ({code: `Digit${c}`, key: c})),
+  ...')!@#$%^&*('
+    .split('')
+    .map((c, i) => ({code: `Digit${i}`, key: c, shiftKey: true})),
+  ...'abcdefghijklmnopqrstuvwxyz'
+    .split('')
+    .map(c => ({code: `Key${c.toUpperCase()}`, key: c})),
+  ...'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+    .split('')
+    .map(c => ({code: `Key${c}`, key: c, shiftKey: true})),
+
+  // alphanumeric block - functional
+  {code: 'Space', key: ' '},
+
+  {code: 'AltLeft', key: 'Alt', location: DOM_KEY_LOCATION.LEFT, keyCode: 18},
+  {code: 'AltRight', key: 'Alt', location: DOM_KEY_LOCATION.RIGHT, keyCode: 18},
+  {
+    code: 'ShiftLeft',
+    key: 'Shift',
+    location: DOM_KEY_LOCATION.LEFT,
+    keyCode: 16,
+  },
+  {
+    code: 'ShiftRight',
+    key: 'Shift',
+    location: DOM_KEY_LOCATION.RIGHT,
+    keyCode: 16,
+  },
+  {
+    code: 'ControlLeft',
+    key: 'Control',
+    location: DOM_KEY_LOCATION.LEFT,
+    keyCode: 17,
+  },
+  {
+    code: 'ControlRight',
+    key: 'Control',
+    location: DOM_KEY_LOCATION.RIGHT,
+    keyCode: 17,
+  },
+  {code: 'MetaLeft', key: 'Meta', location: DOM_KEY_LOCATION.LEFT, keyCode: 93},
+  {
+    code: 'MetaRight',
+    key: 'Meta',
+    location: DOM_KEY_LOCATION.RIGHT,
+    keyCode: 93,
+  },
+
+  {code: 'OSLeft', key: 'OS', location: DOM_KEY_LOCATION.LEFT, keyCode: 91},
+  {code: 'OSRight', key: 'OS', location: DOM_KEY_LOCATION.RIGHT, keyCode: 91},
+
+  {code: 'Escape', key: 'CapsLock', keyCode: 20},
+  {code: 'CapsLock', key: 'CapsLock', keyCode: 20},
+  {code: 'Backspace', key: 'Backspace', keyCode: 8},
+  {code: 'Enter', key: 'Enter', keyCode: 13},
+
+  // function
+  {code: 'Escape', key: 'Escape', keyCode: 27},
+
+  // arrows
+  {code: 'ArrowUp', key: 'ArrowUp', keyCode: 38},
+  {code: 'ArrowDown', key: 'ArrowDown', keyCode: 40},
+  {code: 'ArrowLeft', key: 'ArrowLeft', keyCode: 37},
+  {code: 'ArrowRight', key: 'ArrowRight', keyCode: 39},
+
+  // control pad
+  {code: 'Home', key: 'Home', keyCode: 36},
+  {code: 'End', key: 'End', keyCode: 35},
+  {code: 'Delete', key: 'Delete', keyCode: 46},
+
+  // TODO: add mappings
+]
diff --git a/src/keyboard/keyboardImplementation.ts b/src/keyboard/keyboardImplementation.ts
new file mode 100644
index 00000000..c6626cc6
--- /dev/null
+++ b/src/keyboard/keyboardImplementation.ts
@@ -0,0 +1,196 @@
+import {fireEvent} from '@testing-library/dom'
+import {getActiveElement, wait} from '../utils'
+import {getNextKeyDef} from './getNextKeyDef'
+import {
+  behaviorPlugin,
+  keyboardKey,
+  keyboardState,
+  keyboardOptions,
+} from './types'
+import * as plugins from './plugins'
+import {getKeyEventProps} from './getEventProps'
+
+export async function keyboardImplementation(
+  text: string,
+  options: keyboardOptions,
+  state: keyboardState,
+): Promise<void> {
+  const {document} = options
+  const getCurrentElement = () => getActive(document)
+
+  const {keyDef, consumedLength, releasePrevious, releaseSelf} = getNextKeyDef(
+    text,
+    options,
+  )
+
+  const replace = applyPlugins(
+    plugins.replaceBehavior,
+    keyDef,
+    getCurrentElement(),
+    options,
+    state,
+  )
+  if (!replace) {
+    const pressed = state.pressed.find(p => p.keyDef === keyDef)
+
+    if (pressed) {
+      keyup(
+        keyDef,
+        getCurrentElement,
+        options,
+        state,
+        pressed.unpreventedDefault,
+      )
+    }
+
+    if (!releasePrevious) {
+      const unpreventedDefault = keydown(
+        keyDef,
+        getCurrentElement,
+        options,
+        state,
+      )
+
+      if (
+        unpreventedDefault &&
+        (keyDef.key?.length === 1 || keyDef.key === 'Enter')
+      ) {
+        keypress(keyDef, getCurrentElement, options, state)
+      }
+
+      if (releaseSelf) {
+        keyup(keyDef, getCurrentElement, options, state, unpreventedDefault)
+      }
+    }
+  }
+
+  if (text.length > consumedLength) {
+    if (options.delay > 0) {
+      await wait(options.delay)
+    }
+    return keyboardImplementation(text.slice(consumedLength), options, state)
+  }
+  return void undefined
+}
+
+function getActive(document: Document): Element {
+  return getActiveElement(document) ?? /* istanbul ignore next */ document.body
+}
+
+export function releaseAllKeys(options: keyboardOptions, state: keyboardState) {
+  const getCurrentElement = () => getActive(options.document)
+  for (const k of state.pressed) {
+    keyup(k.keyDef, getCurrentElement, options, state, k.unpreventedDefault)
+  }
+}
+
+function keydown(
+  keyDef: keyboardKey,
+  getCurrentElement: () => Element,
+  options: keyboardOptions,
+  state: keyboardState,
+) {
+  const element = getCurrentElement()
+
+  // clear carried characters when focus is moved
+  if (element !== state.activeElement) {
+    state.carryValue = undefined
+    state.carryChar = ''
+  }
+  state.activeElement = element
+
+  applyPlugins(plugins.preKeydownBehavior, keyDef, element, options, state)
+
+  const unpreventedDefault = fireEvent.keyDown(
+    element,
+    getKeyEventProps(keyDef, state),
+  )
+
+  state.pressed.push({keyDef, unpreventedDefault})
+
+  if (unpreventedDefault) {
+    // all default behavior like keypress/submit etc is applied to the currentElement
+    applyPlugins(
+      plugins.keydownBehavior,
+      keyDef,
+      getCurrentElement(),
+      options,
+      state,
+    )
+  }
+
+  return unpreventedDefault
+}
+
+function keypress(
+  keyDef: keyboardKey,
+  getCurrentElement: () => Element,
+  options: keyboardOptions,
+  state: keyboardState,
+) {
+  const element = getCurrentElement()
+
+  const unpreventedDefault = fireEvent.keyPress(
+    element,
+    getKeyEventProps(keyDef, state),
+  )
+
+  if (unpreventedDefault) {
+    applyPlugins(
+      plugins.keypressBehavior,
+      keyDef,
+      getCurrentElement(),
+      options,
+      state,
+    )
+  }
+}
+
+function keyup(
+  keyDef: keyboardKey,
+  getCurrentElement: () => Element,
+  options: keyboardOptions,
+  state: keyboardState,
+  unprevented: boolean,
+) {
+  const element = getCurrentElement()
+
+  applyPlugins(plugins.preKeyupBehavior, keyDef, element, options, state)
+
+  const unpreventedDefault = fireEvent.keyUp(
+    element,
+    getKeyEventProps(keyDef, state),
+  )
+
+  if (unprevented && unpreventedDefault) {
+    applyPlugins(
+      plugins.keyupBehavior,
+      keyDef,
+      getCurrentElement(),
+      options,
+      state,
+    )
+  }
+
+  state.pressed = state.pressed.filter(k => k.keyDef !== keyDef)
+
+  applyPlugins(plugins.postKeyupBehavior, keyDef, element, options, state)
+}
+
+function applyPlugins(
+  pluginCollection: behaviorPlugin[],
+  keyDef: keyboardKey,
+  element: Element,
+  options: keyboardOptions,
+  state: keyboardState,
+): boolean {
+  const plugin = pluginCollection.find(p =>
+    p.matches(keyDef, element, options, state),
+  )
+
+  if (plugin) {
+    plugin.handle(keyDef, element, options, state)
+  }
+
+  return !!plugin
+}
diff --git a/src/keyboard/plugins/arrow.ts b/src/keyboard/plugins/arrow.ts
new file mode 100644
index 00000000..4455d7f1
--- /dev/null
+++ b/src/keyboard/plugins/arrow.ts
@@ -0,0 +1,30 @@
+/**
+ * This file should contain behavior for arrow keys as described here:
+ * https://w3c.github.io/uievents-code/#key-arrowpad-section
+ */
+
+import {behaviorPlugin} from '../types'
+import {isInstanceOfElement, setSelectionRangeIfNecessary} from '../../utils'
+
+export const keydownBehavior: behaviorPlugin[] = [
+  {
+    // TODO: implement for textarea and contentEditable
+    matches: (keyDef, element) =>
+      (keyDef.key === 'ArrowLeft' || keyDef.key === 'ArrowRight') &&
+      isInstanceOfElement(element, 'HTMLInputElement'),
+    handle: (keyDef, element) => {
+      const {selectionStart, selectionEnd} = element as HTMLInputElement
+
+      const direction = keyDef.key === 'ArrowLeft' ? -1 : 1
+
+      const newPos =
+        (selectionStart === selectionEnd
+          ? (selectionStart ?? /* istanbul ignore next */ 0) + direction
+          : direction < 0
+          ? selectionStart
+          : selectionEnd) ?? /* istanbul ignore next */ 0
+
+      setSelectionRangeIfNecessary(element, newPos, newPos)
+    },
+  },
+]
diff --git a/src/keyboard/plugins/character.ts b/src/keyboard/plugins/character.ts
new file mode 100644
index 00000000..31d523d6
--- /dev/null
+++ b/src/keyboard/plugins/character.ts
@@ -0,0 +1,184 @@
+/**
+ * This file should cover the behavior for keys that produce character input
+ */
+
+import {fireEvent} from '@testing-library/dom'
+import {fireChangeForInputTimeIfValid, fireInputEventIfNeeded} from '../shared'
+import {behaviorPlugin} from '../types'
+import {
+  buildTimeValue,
+  calculateNewValue,
+  getValue,
+  isContentEditable,
+  isInstanceOfElement,
+  isValidDateValue,
+  isValidInputTimeValue,
+} from '../../utils'
+
+export const keypressBehavior: behaviorPlugin[] = [
+  {
+    matches: (keyDef, element) =>
+      keyDef.key?.length === 1 &&
+      isInstanceOfElement(element, 'HTMLInputElement') &&
+      (element as HTMLInputElement).type === 'time',
+    handle: (keyDef, element, options, state) => {
+      let newEntry = keyDef.key as string
+
+      const textToBeTyped = (state.carryValue ?? '') + newEntry
+      const timeNewEntry = buildTimeValue(textToBeTyped)
+      if (
+        isValidInputTimeValue(
+          element as HTMLInputElement & {type: 'time'},
+          timeNewEntry,
+        )
+      ) {
+        newEntry = timeNewEntry
+      }
+
+      const {newValue, newSelectionStart} = calculateNewValue(
+        newEntry,
+        element as HTMLElement,
+      )
+
+      const {prevValue} = fireInputEventIfNeeded({
+        newValue,
+        newSelectionStart,
+        eventOverrides: {
+          data: keyDef.key,
+          inputType: 'insertText',
+        },
+        currentElement: () => element,
+      })
+
+      fireChangeForInputTimeIfValid(
+        element as HTMLInputElement & {type: 'time'},
+        prevValue,
+        timeNewEntry,
+      )
+
+      state.carryValue = textToBeTyped
+    },
+  },
+  {
+    matches: (keyDef, element) =>
+      keyDef.key?.length === 1 &&
+      isInstanceOfElement(element, 'HTMLInputElement') &&
+      (element as HTMLInputElement).type === 'date',
+    handle: (keyDef, element, options, state) => {
+      let newEntry = keyDef.key as string
+
+      const textToBeTyped = (state.carryValue ?? '') + newEntry
+      const isValidToBeTyped = isValidDateValue(
+        element as HTMLInputElement & {type: 'date'},
+        textToBeTyped,
+      )
+      if (isValidToBeTyped) {
+        newEntry = textToBeTyped
+      }
+
+      const {newValue, newSelectionStart} = calculateNewValue(
+        newEntry,
+        element as HTMLElement,
+      )
+
+      fireInputEventIfNeeded({
+        newValue,
+        newSelectionStart,
+        eventOverrides: {
+          data: keyDef.key,
+          inputType: 'insertText',
+        },
+        currentElement: () => element,
+      })
+
+      if (isValidToBeTyped) {
+        fireEvent.change(element, {
+          target: {value: textToBeTyped},
+        })
+      }
+
+      state.carryValue = textToBeTyped
+    },
+  },
+  {
+    matches: (keyDef, element) =>
+      keyDef.key?.length === 1 &&
+      isInstanceOfElement(element, 'HTMLInputElement') &&
+      (element as HTMLInputElement).type === 'number',
+    handle: (keyDef, element, options, state) => {
+      if (!/[\d.\-e]/.test(keyDef.key as string)) {
+        return
+      }
+
+      const oldValue =
+        state.carryValue ?? getValue(element) ?? /* istanbul ignore next */ ''
+
+      const {newValue, newSelectionStart} = calculateNewValue(
+        keyDef.key as string,
+        element as HTMLElement,
+        oldValue,
+      )
+
+      fireInputEventIfNeeded({
+        newValue,
+        newSelectionStart,
+        eventOverrides: {
+          data: keyDef.key,
+          inputType: 'insertText',
+        },
+        currentElement: () => element,
+      })
+
+      const appliedValue = getValue(element)
+      if (appliedValue === newValue) {
+        state.carryValue = undefined
+      } else {
+        state.carryValue = newValue
+      }
+    },
+  },
+  {
+    matches: (keyDef, element) =>
+      keyDef.key?.length === 1 &&
+      (isInstanceOfElement(element, 'HTMLInputElement') ||
+        isInstanceOfElement(element, 'HTMLTextAreaElement') ||
+        isContentEditable(element)),
+    handle: (keyDef, element) => {
+      const {newValue, newSelectionStart} = calculateNewValue(
+        keyDef.key as string,
+        element as HTMLElement,
+      )
+
+      fireInputEventIfNeeded({
+        newValue,
+        newSelectionStart,
+        eventOverrides: {
+          data: keyDef.key,
+          inputType: 'insertText',
+        },
+        currentElement: () => element,
+      })
+    },
+  },
+  {
+    matches: (keyDef, element) =>
+      keyDef.key === 'Enter' &&
+      (isInstanceOfElement(element, 'HTMLTextAreaElement') ||
+        isContentEditable(element)),
+    handle: (keyDef, element) => {
+      const {newValue, newSelectionStart} = calculateNewValue(
+        '\n',
+        element as HTMLElement,
+      )
+
+      fireInputEventIfNeeded({
+        newValue,
+        newSelectionStart,
+        eventOverrides: {
+          inputType: 'insertLineBreak',
+        },
+        currentElement: () => element,
+      })
+    },
+  },
+]
diff --git a/src/keyboard/plugins/control.ts b/src/keyboard/plugins/control.ts
new file mode 100644
index 00000000..304129b7
--- /dev/null
+++ b/src/keyboard/plugins/control.ts
@@ -0,0 +1,45 @@
+/**
+ * This file should contain behavior for arrow keys as described here:
+ * https://w3c.github.io/uievents-code/#key-controlpad-section
+ */
+
+import {behaviorPlugin} from '../types'
+import {
+  getValue,
+  isContentEditable,
+  isInstanceOfElement,
+  setSelectionRangeIfNecessary,
+} from '../../utils'
+import {fireInputEventIfNeeded} from '../shared'
+import {calculateNewDeleteValue} from './control/calculateNewDeleteValue'
+
+export const keydownBehavior: behaviorPlugin[] = [
+  {
+    matches: (keyDef, element) =>
+      (keyDef.key === 'Home' || keyDef.key === 'End') &&
+      (isInstanceOfElement(element, 'HTMLInputElement') ||
+        isInstanceOfElement(element, 'HTMLTextAreaElement') ||
+        isContentEditable(element)),
+    handle: (keyDef, element) => {
+      // This could probably been improved by collapsing a selection range
+      if (keyDef.key === 'Home') {
+        setSelectionRangeIfNecessary(element, 0, 0)
+      } else {
+        const newPos = getValue(element)?.length ?? /* istanbul ignore next */ 0
+        setSelectionRangeIfNecessary(element, newPos, newPos)
+      }
+    },
+  },
+  {
+    matches: keyDef => keyDef.key === 'Delete',
+    handle: (keDef, element) => {
+      fireInputEventIfNeeded({
+        ...calculateNewDeleteValue(element),
+        eventOverrides: {
+          inputType: 'deleteContentForward',
+        },
+        currentElement: () => element,
+      })
+    },
+  },
+]
diff --git a/src/keyboard/plugins/control/calculateNewDeleteValue.ts b/src/keyboard/plugins/control/calculateNewDeleteValue.ts
new file mode 100644
index 00000000..febdde86
--- /dev/null
+++ b/src/keyboard/plugins/control/calculateNewDeleteValue.ts
@@ -0,0 +1,33 @@
+import {getSelectionRange, getValue} from '../../../utils'
+
+export function calculateNewDeleteValue(element: Element) {
+  const {selectionStart, selectionEnd} = getSelectionRange(element)
+
+  // istanbul ignore next
+  const value = getValue(element) ?? ''
+
+  let newValue
+
+  if (selectionStart === null) {
+    // at the end of an input type that does not support selection ranges
+    // https://github.com/testing-library/user-event/issues/316#issuecomment-639744793
+    newValue = value
+  } else if (selectionStart === selectionEnd) {
+    if (selectionStart === 0) {
+      // at the beginning of the input
+      newValue = value.slice(1)
+    } else if (selectionStart === value.length) {
+      // at the end of the input
+      newValue = value
+    } else {
+      // in the middle of the input
+      newValue = value.slice(0, selectionStart) + value.slice(selectionEnd + 1)
+    }
+  } else {
+    // we have something selected
+    const firstPart = value.slice(0, selectionStart)
+    newValue = firstPart + value.slice(selectionEnd as number)
+  }
+
+  return {newValue, newSelectionStart: selectionStart ?? 0}
+}
diff --git a/src/keyboard/plugins/functional.ts b/src/keyboard/plugins/functional.ts
new file mode 100644
index 00000000..66c4c7ac
--- /dev/null
+++ b/src/keyboard/plugins/functional.ts
@@ -0,0 +1,140 @@
+/**
+ * This file should contain behavior for functional keys as described here:
+ * https://w3c.github.io/uievents-code/#key-alphanumeric-functional
+ */
+
+import {fireEvent} from '@testing-library/dom'
+import {getValue, isClickableInput, isInstanceOfElement} from '../../utils'
+import {getKeyEventProps, getMouseEventProps} from '../getEventProps'
+import {fireInputEventIfNeeded} from '../shared'
+import {behaviorPlugin} from '../types'
+import {calculateNewBackspaceValue} from './functional/calculateBackspaceValue'
+
+const modifierKeys = {
+  Alt: 'alt',
+  Control: 'ctrl',
+  Shift: 'shift',
+  Meta: 'meta',
+} as const
+
+export const preKeydownBehavior: behaviorPlugin[] = [
+  // modifierKeys switch on the modifier BEFORE the keydown event
+  ...Object.entries(modifierKeys).map(
+    ([key, modKey]): behaviorPlugin => ({
+      matches: keyDef => keyDef.key === key,
+      handle: (keyDef, element, options, state) => {
+        state.modifiers[modKey] = true
+      },
+    }),
+  ),
+
+  // AltGraph produces an extra keydown for Control
+  // The modifier does not change
+  {
+    matches: keyDef => keyDef.key === 'AltGraph',
+    handle: (keyDef, element, options, state) => {
+      const ctrlKeyDef = options.keyboardMap.find(
+        k => k.key === 'Control',
+      ) ?? /* istanbul ignore next */ {key: 'Control', code: 'Control'}
+      fireEvent.keyDown(element, getKeyEventProps(ctrlKeyDef, state))
+    },
+  },
+]
+
+export const keydownBehavior: behaviorPlugin[] = [
+  {
+    matches: keyDef => keyDef.key === 'CapsLock',
+    handle: (keyDef, element, options, state) => {
+      state.modifiers.caps = !state.modifiers.caps
+    },
+  },
+  {
+    matches: keyDef => keyDef.key === 'Backspace',
+    handle: (keyDef, element, options, state) => {
+      const {newValue, newSelectionStart} = calculateNewBackspaceValue(
+        element,
+        state.carryValue,
+      )
+
+      fireInputEventIfNeeded({
+        newValue,
+        newSelectionStart,
+        eventOverrides: {
+          inputType: 'deleteContentBackward',
+        },
+        currentElement: () => element,
+      })
+
+      if (state.carryValue) {
+        state.carryValue = getValue(element) === newValue ? undefined : newValue
+      }
+    },
+  },
+]
+
+export const keypressBehavior: behaviorPlugin[] = [
+  {
+    matches: (keyDef, element) =>
+      keyDef.key === 'Enter' &&
+      (isClickableInput(element) ||
+        // Links with href defined should handle Enter the same as a click
+        (isInstanceOfElement(element, 'HTMLAnchorElement') &&
+          Boolean((element as HTMLAnchorElement).href))),
+    handle: (keyDef, element, options, state) => {
+      fireEvent.click(element, getMouseEventProps(state))
+    },
+  },
+  {
+    matches: (keyDef, element) =>
+      keyDef.key === 'Enter' &&
+      isInstanceOfElement(element, 'HTMLInputElement'),
+    handle: (keyDef, element) => {
+      const form = (element as HTMLInputElement).form
+
+      if (
+        form &&
+        (form.querySelectorAll('input').length === 1 ||
+          form.querySelector('input[type="submit"]') ||
+          form.querySelector('button[type="submit"]'))
+      ) {
+        fireEvent.submit(form)
+      }
+    },
+  },
+]
+
+export const preKeyupBehavior: behaviorPlugin[] = [
+  // modifierKeys switch off the modifier BEFORE the keyup event
+  ...Object.entries(modifierKeys).map(
+    ([key, modKey]): behaviorPlugin => ({
+      matches: keyDef => keyDef.key === key,
+      handle: (keyDef, element, options, state) => {
+        state.modifiers[modKey] = false
+      },
+    }),
+  ),
+]
+
+export const keyupBehavior: behaviorPlugin[] = [
+  {
+    matches: (keyDef, element) =>
+      keyDef.key === ' ' && isClickableInput(element),
+    handle: (keyDef, element, options, state) => {
+      fireEvent.click(element, getMouseEventProps(state))
+    },
+  },
+]
+
+export const postKeyupBehavior: behaviorPlugin[] = [
+  // AltGraph produces an extra keyup for Control
+  // The modifier does not change
+  {
+    matches: keyDef => keyDef.key === 'AltGraph',
+    handle: (keyDef, element, options, state) => {
+      const ctrlKeyDef = options.keyboardMap.find(
+        k => k.key === 'Control',
+      ) ?? /* istanbul ignore next */ {key: 'Control', code: 'Control'}
+      fireEvent.keyUp(element, getKeyEventProps(ctrlKeyDef, state))
+    },
+  },
+]
diff --git a/src/keyboard/plugins/functional/calculateBackspaceValue.ts b/src/keyboard/plugins/functional/calculateBackspaceValue.ts
new file mode 100644
index 00000000..4e544f61
--- /dev/null
+++ b/src/keyboard/plugins/functional/calculateBackspaceValue.ts
@@ -0,0 +1,43 @@
+import {getSelectionRange, getValue} from '../../../utils'
+
+// yes, calculateNewBackspaceValue and calculateNewValue look extremely similar
+// and you may be tempted to create a shared abstraction.
+// If you, brave soul, decide to so endevor, please increment this count
+// when you inevitably fail: 1
+export function calculateNewBackspaceValue(
+  element: Element,
+  value = getValue(element) ?? /* istanbul ignore next */ '',
+) {
+  const {selectionStart, selectionEnd} = getSelectionRange(element)
+
+  let newValue, newSelectionStart
+
+  if (selectionStart === null) {
+    // at the end of an input type that does not support selection ranges
+    // https://github.com/testing-library/user-event/issues/316#issuecomment-639744793
+    newValue = value.slice(0, value.length - 1)
+
+    newSelectionStart = newValue.length
+  } else if (selectionStart === selectionEnd) {
+    if (selectionStart === 0) {
+      // at the beginning of the input
+      newValue = value
+      newSelectionStart = selectionStart
+    } else if (selectionStart === value.length) {
+      // at the end of the input
+      newValue = value.slice(0, value.length - 1)
+      newSelectionStart = selectionStart - 1
+    } else {
+      // in the middle of the input
+      newValue = value.slice(0, selectionStart - 1) + value.slice(selectionEnd)
+      newSelectionStart = selectionStart - 1
+    }
+  } else {
+    // we have something selected
+    const firstPart = value.slice(0, selectionStart)
+    newValue = firstPart + value.slice(selectionEnd as number)
+    newSelectionStart = firstPart.length
+  }
+
+  return {newValue, newSelectionStart}
+}
diff --git a/src/keyboard/plugins/index.ts b/src/keyboard/plugins/index.ts
new file mode 100644
index 00000000..1cfd9380
--- /dev/null
+++ b/src/keyboard/plugins/index.ts
@@ -0,0 +1,43 @@
+import {behaviorPlugin} from '../types'
+import {isInstanceOfElement} from '../../utils'
+import * as arrowKeys from './arrow'
+import * as controlKeys from './control'
+import * as characterKeys from './character'
+import * as functionalKeys from './functional'
+
+export const replaceBehavior: behaviorPlugin[] = [
+  {
+    matches: (keyDef, element) =>
+      keyDef.key === 'selectall' &&
+      (isInstanceOfElement(element, 'HTMLInputElement') ||
+        isInstanceOfElement(element, 'HTMLTextAreaElement')),
+    handle: (keyDef, element) => {
+      ;(element as HTMLInputElement).select()
+    },
+  },
+]
+
+export const preKeydownBehavior: behaviorPlugin[] = [
+  ...functionalKeys.preKeydownBehavior,
+]
+
+export const keydownBehavior: behaviorPlugin[] = [
+  ...arrowKeys.keydownBehavior,
+  ...controlKeys.keydownBehavior,
+  ...functionalKeys.keydownBehavior,
+]
+
+export const keypressBehavior: behaviorPlugin[] = [
+  ...functionalKeys.keypressBehavior,
+  ...characterKeys.keypressBehavior,
+]
+
+export const preKeyupBehavior: behaviorPlugin[] = [
+  ...functionalKeys.preKeyupBehavior,
+]
+
+export const keyupBehavior: behaviorPlugin[] = [...functionalKeys.keyupBehavior]
+
+export const postKeyupBehavior: behaviorPlugin[] = [
+  ...functionalKeys.postKeyupBehavior,
+]
diff --git a/src/keyboard/shared/fireChangeForInputTimeIfValid.ts b/src/keyboard/shared/fireChangeForInputTimeIfValid.ts
new file mode 100644
index 00000000..3a567698
--- /dev/null
+++ b/src/keyboard/shared/fireChangeForInputTimeIfValid.ts
@@ -0,0 +1,12 @@
+import {fireEvent} from '@testing-library/dom'
+import {isValidInputTimeValue} from '../../utils'
+
+export function fireChangeForInputTimeIfValid(
+  el: HTMLInputElement & {type: 'time'},
+  prevValue: unknown,
+  timeNewEntry: string,
+) {
+  if (isValidInputTimeValue(el, timeNewEntry) && prevValue !== timeNewEntry) {
+    fireEvent.change(el, {target: {value: timeNewEntry}})
+  }
+}
diff --git a/src/keyboard/shared/fireInputEventIfNeeded.ts b/src/keyboard/shared/fireInputEventIfNeeded.ts
new file mode 100644
index 00000000..2c468dc4
--- /dev/null
+++ b/src/keyboard/shared/fireInputEventIfNeeded.ts
@@ -0,0 +1,63 @@
+import {fireEvent} from '@testing-library/dom'
+import {
+  isInstanceOfElement,
+  isClickableInput,
+  getValue,
+  isContentEditable,
+} from '../../utils'
+import {setSelectionRange} from './setSelectionRange'
+
+export function fireInputEventIfNeeded({
+  currentElement,
+  newValue,
+  newSelectionStart,
+  eventOverrides,
+}: {
+  currentElement: () => Element | null
+  newValue: string
+  newSelectionStart: number
+  eventOverrides: Partial<Parameters<typeof fireEvent>[1]> & {
+    [k: string]: unknown
+  }
+}): {
+  prevValue: string | null
+} {
+  const el = currentElement()
+  const prevValue = getValue(el)
+  if (
+    el &&
+    !isReadonly(el) &&
+    !isClickableInput(el) &&
+    newValue !== prevValue
+  ) {
+    if (isContentEditable(el)) {
+      fireEvent.input(el, {
+        target: {textContent: newValue},
+        ...eventOverrides,
+      })
+    } else {
+      fireEvent.input(el, {
+        target: {value: newValue},
+        ...eventOverrides,
+      })
+    }
+
+    setSelectionRange({
+      currentElement,
+      newValue,
+      newSelectionStart,
+    })
+  }
+
+  return {prevValue}
+}
+
+function isReadonly(element: Element): boolean {
+  if (
+    !isInstanceOfElement(element, 'HTMLInputElement') &&
+    !isInstanceOfElement(element, 'HTMLTextAreaElement')
+  ) {
+    return false
+  }
+  return (element as HTMLInputElement | HTMLTextAreaElement).readOnly
+}
diff --git a/src/keyboard/shared/index.ts b/src/keyboard/shared/index.ts
new file mode 100644
index 00000000..d1f33cf7
--- /dev/null
+++ b/src/keyboard/shared/index.ts
@@ -0,0 +1,3 @@
+export * from './fireChangeForInputTimeIfValid'
+export * from './fireInputEventIfNeeded'
+export * from './setSelectionRange'
diff --git a/src/keyboard/shared/setSelectionRange.ts b/src/keyboard/shared/setSelectionRange.ts
new file mode 100644
index 00000000..a25ceb2d
--- /dev/null
+++ b/src/keyboard/shared/setSelectionRange.ts
@@ -0,0 +1,30 @@
+import {getValue, setSelectionRangeIfNecessary} from '../../utils'
+
+export function setSelectionRange({
+  currentElement,
+  newValue,
+  newSelectionStart,
+}: {
+  currentElement: () => Element | null
+  newValue: string
+  newSelectionStart: number
+}): void {
+  // if we *can* change the selection start, then we will if the new value
+  // is the same as the current value (so it wasn't programatically changed
+  // when the fireEvent.input was triggered).
+  // The reason we have to do this at all is because it actually *is*
+  // programmatically changed by fireEvent.input, so we have to simulate the
+  // browser's default behavior
+  const el = currentElement() as Element
+
+  const value = getValue(el) as string
+
+  if (value === newValue) {
+    setSelectionRangeIfNecessary(el, newSelectionStart, newSelectionStart)
+  } else {
+    // If the currentValue is different than the expected newValue and we *can*
+    // change the selection range, than we should set it to the length of the
+    // currentValue to ensure that the browser behavior is mimicked.
+    setSelectionRangeIfNecessary(el, value.length, value.length)
+  }
+}
diff --git a/src/keyboard/specialCharMap.ts b/src/keyboard/specialCharMap.ts
new file mode 100644
index 00000000..b69ffdc6
--- /dev/null
+++ b/src/keyboard/specialCharMap.ts
@@ -0,0 +1,15 @@
+export const specialCharMap = {
+  arrowLeft: '{arrowleft}',
+  arrowRight: '{arrowright}',
+  arrowDown: '{arrowdown}',
+  arrowUp: '{arrowup}',
+  enter: '{enter}',
+  escape: '{esc}',
+  delete: '{del}',
+  backspace: '{backspace}',
+  home: '{home}',
+  end: '{end}',
+  selectAll: '{selectall}',
+  space: '{space}',
+  whitespace: ' ',
+} as const
diff --git a/src/keyboard/types.ts b/src/keyboard/types.ts
new file mode 100644
index 00000000..1fc949d5
--- /dev/null
+++ b/src/keyboard/types.ts
@@ -0,0 +1,87 @@
+/**
+ * @internal Do not create/alter this by yourself as this type might be subject to changes.
+ */
+export type keyboardState = {
+  /**
+      All keys that have been pressed and not been lifted up yet.
+    */
+  pressed: {keyDef: keyboardKey; unpreventedDefault: boolean}[]
+
+  /**
+      Active modifiers
+    */
+  modifiers: {
+    alt: boolean
+    caps: boolean
+    ctrl: boolean
+    meta: boolean
+    shift: boolean
+  }
+
+  /**
+      The element the keyboard input is performed on.
+      Some behavior might differ if the activeElement changes between corresponding keyboard events.
+    */
+  activeElement: Element | null
+
+  /**
+      For HTMLInputElements type='number':
+      If the last input char is '.', '-' or 'e',
+      the IDL value attribute does not reflect the input value.
+    */
+  carryValue?: string
+
+  /**
+      Carry over characters to following key handlers.
+      E.g. ^1
+    */
+  carryChar: string
+}
+
+export type keyboardOptions = {
+  /** Document in which to perform the events */
+  document: Document
+  /** Delay between keystrokes */
+  delay: number
+  /** Add modifiers for given keys - not implemented yet */
+  autoModify: boolean
+  /** Keyboard layout to use */
+  keyboardMap: keyboardKey[]
+}
+
+export enum DOM_KEY_LOCATION {
+  STANDARD = 0,
+  LEFT = 1,
+  RIGHT = 2,
+  NUMPAD = 3,
+}
+
+export interface keyboardKey {
+  /** Physical location on a keyboard */
+  code?: string
+  /** Character or functional key descriptor */
+  key?: string
+  /** Location on the keyboard for keys with multiple representation */
+  location?: DOM_KEY_LOCATION
+  /** keyCode for legacy support */
+  keyCode?: number
+  /** Does the character in `key` require/imply AltRight to be pressed? */
+  altGr?: boolean
+  /** Does the character in `key` require/imply a shiftKey to be pressed? */
+  shift?: boolean
+}
+
+export interface behaviorPlugin {
+  matches: (
+    keyDef: keyboardKey,
+    element: Element,
+    options: keyboardOptions,
+    state: keyboardState,
+  ) => boolean
+  handle: (
+    keyDef: keyboardKey,
+    element: Element,
+    options: keyboardOptions,
+    state: keyboardState,
+  ) => void
+}
diff --git a/src/keys/navigation-key.js b/src/keys/navigation-key.js
deleted file mode 100644
index 2bbcce8c..00000000
--- a/src/keys/navigation-key.js
+++ /dev/null
@@ -1,71 +0,0 @@
-import {fireEvent} from '@testing-library/dom'
-
-import {setSelectionRangeIfNecessary} from '../utils'
-
-const keys = {
-  Home: {
-    keyCode: 36,
-  },
-  End: {
-    keyCode: 35,
-  },
-  ArrowLeft: {
-    keyCode: 37,
-  },
-  ArrowRight: {
-    keyCode: 39,
-  },
-}
-
-function getSelectionRange(currentElement, key) {
-  const {selectionStart, selectionEnd} = currentElement()
-
-  if (key === 'Home') {
-    return {
-      selectionStart: 0,
-      selectionEnd: 0,
-    }
-  }
-
-  if (key === 'End') {
-    return {
-      selectionStart: selectionEnd + 1,
-      selectionEnd: selectionEnd + 1,
-    }
-  }
-
-  const cursorChange = Number(key in keys) * (key === 'ArrowLeft' ? -1 : 1)
-  return {
-    selectionStart: selectionStart + cursorChange,
-    selectionEnd: selectionEnd + cursorChange,
-  }
-}
-
-function navigationKey(key) {
-  const event = {
-    key,
-    keyCode: keys[key].keyCode,
-    which: keys[key].keyCode,
-  }
-
-  return ({currentElement, eventOverrides}) => {
-    fireEvent.keyDown(currentElement(), {
-      ...event,
-      ...eventOverrides,
-    })
-
-    const range = getSelectionRange(currentElement, key)
-    setSelectionRangeIfNecessary(
-      currentElement(),
-      range.selectionStart,
-      range.selectionEnd,
-    )
-
-    fireEvent.keyUp(currentElement(), {
-      ...event,
-      ...eventOverrides,
-    })
-  }
-}
-
-export {navigationKey}
diff --git a/src/type.js b/src/type.js
deleted file mode 100644
index 125c1968..00000000
--- a/src/type.js
+++ /dev/null
@@ -1,800 +0,0 @@
-// TODO: wrap in asyncWrapper
-import {
-  fireEvent,
-  getConfig as getDOMTestingLibraryConfig,
-} from '@testing-library/dom'
-
-import {
-  getActiveElement,
-  calculateNewValue,
-  setSelectionRangeIfNecessary,
-  isClickableInput,
-  isValidDateValue,
-  getSelectionRange,
-  getValue,
-  isContentEditable,
-  isValidInputTimeValue,
-  buildTimeValue,
-  isInstanceOfElement,
-} from './utils'
-import {click} from './click'
-import {navigationKey} from './keys/navigation-key'
-
-const modifierCallbackMap = {
-  ...createModifierCallbackEntries({
-    name: 'shift',
-    key: 'Shift',
-    keyCode: 16,
-    modifierProperty: 'shiftKey',
-  }),
-  ...createModifierCallbackEntries({
-    name: 'ctrl',
-    key: 'Control',
-    keyCode: 17,
-    modifierProperty: 'ctrlKey',
-  }),
-  ...createModifierCallbackEntries({
-    name: 'alt',
-    key: 'Alt',
-    keyCode: 18,
-    modifierProperty: 'altKey',
-  }),
-  ...createModifierCallbackEntries({
-    name: 'meta',
-    key: 'Meta',
-    keyCode: 93,
-    modifierProperty: 'metaKey',
-  }),
-  // capslock is inline because of the need to fire both keydown and keyup on use, while preserving the modifier state.
-  '{capslock}': function capslockOn({currentElement, eventOverrides}) {
-    const newEventOverrides = {modifierCapsLock: true}
-
-    fireEvent.keyDown(currentElement(), {
-      key: 'CapsLock',
-      keyCode: 20,
-      which: 20,
-      ...eventOverrides,
-      ...newEventOverrides,
-    })
-    fireEvent.keyUp(currentElement(), {
-      key: 'CapsLock',
-      keyCode: 20,
-      which: 20,
-      ...eventOverrides,
-      ...newEventOverrides,
-    })
-
-    return {eventOverrides: newEventOverrides}
-  },
-  '{/capslock}': function capslockOff({currentElement, eventOverrides}) {
-    const newEventOverrides = {modifierCapsLock: false}
-
-    fireEvent.keyDown(currentElement(), {
-      key: 'CapsLock',
-      keyCode: 20,
-      which: 20,
-      ...eventOverrides,
-      ...newEventOverrides,
-    })
-    fireEvent.keyUp(currentElement(), {
-      key: 'CapsLock',
-      keyCode: 20,
-      which: 20,
-      ...eventOverrides,
-      ...newEventOverrides,
-    })
-
-    return {eventOverrides: newEventOverrides}
-  },
-}
-
-const specialCharMap = {
-  arrowLeft: '{arrowleft}',
-  arrowRight: '{arrowright}',
-  arrowDown: '{arrowdown}',
-  arrowUp: '{arrowup}',
-  enter: '{enter}',
-  escape: '{esc}',
-  delete: '{del}',
-  backspace: '{backspace}',
-  home: '{home}',
-  end: '{end}',
-  selectAll: '{selectall}',
-  space: '{space}',
-  whitespace: ' ',
-}
-
-const specialCharCallbackMap = {
-  [specialCharMap.arrowLeft]: navigationKey('ArrowLeft'),
-  [specialCharMap.arrowRight]: navigationKey('ArrowRight'),
-  [specialCharMap.arrowDown]: handleArrowDown,
-  [specialCharMap.arrowUp]: handleArrowUp,
-  [specialCharMap.home]: navigationKey('Home'),
-  [specialCharMap.end]: navigationKey('End'),
-  [specialCharMap.enter]: handleEnter,
-  [specialCharMap.escape]: handleEsc,
-  [specialCharMap.delete]: handleDel,
-  [specialCharMap.backspace]: handleBackspace,
-  [specialCharMap.selectAll]: handleSelectall,
-  [specialCharMap.space]: handleSpace,
-  [specialCharMap.whitespace]: handleSpace,
-}
-
-function wait(time) {
-  return new Promise(resolve => setTimeout(() => resolve(), time))
-}
-
-// this needs to be wrapped in the event/asyncWrapper for React's act and angular's change detection
-// depending on whether it will be async.
-async function type(element, text, {delay = 0, ...options} = {}) {
-  // we do not want to wrap in the asyncWrapper if we're not
-  // going to actually be doing anything async, so we only wrap
-  // if the delay is greater than 0
-  let result
-  if (delay > 0) {
-    await getDOMTestingLibraryConfig().asyncWrapper(async () => {
-      result = await typeImpl(element, text, {delay, ...options})
-    })
-  } else {
-    result = typeImpl(element, text, {delay, ...options})
-  }
-  return result
-}
-
-async function typeImpl(
-  element,
-  text,
-  {
-    delay,
-    skipClick = false,
-    skipAutoClose = false,
-    initialSelectionStart,
-    initialSelectionEnd,
-  },
-) {
-  if (element.disabled) return
-
-  if (!skipClick) click(element)
-
-  if (isContentEditable(element) && document.getSelection().rangeCount === 0) {
-    const range = document.createRange()
-    range.setStart(element, 0)
-    range.setEnd(element, 0)
-    document.getSelection().addRange(range)
-  }
-  // The focused element could change between each event, so get the currently active element each time
-  const currentElement = () => getActiveElement(element.ownerDocument)
-
-  // by default, a new element has it's selection start and end at 0
-  // but most of the time when people call "type", they expect it to type
-  // at the end of the current input value. So, if the selection start
-  // and end are both the default of 0, then we'll go ahead and change
-  // them to the length of the current value.
-  // the only time it would make sense to pass the initialSelectionStart or
-  // initialSelectionEnd is if you have an input with a value and want to
-  // explicitely start typing with the cursor at 0. Not super common.
-  const value = getValue(currentElement())
-
-  const {selectionStart, selectionEnd} = getSelectionRange(element)
-
-  if (value != null && selectionStart === 0 && selectionEnd === 0) {
-    setSelectionRangeIfNecessary(
-      currentElement(),
-      initialSelectionStart ?? value.length,
-      initialSelectionEnd ?? value.length,
-    )
-  }
-
-  const eventCallbacks = queueCallbacks()
-  await runCallbacks(eventCallbacks)
-
-  function queueCallbacks() {
-    const callbacks = []
-    let remainingString = text
-
-    while (remainingString) {
-      const {callback, remainingString: newRemainingString} = getNextCallback(
-        remainingString,
-        skipAutoClose,
-      )
-      callbacks.push(callback)
-      remainingString = newRemainingString
-    }
-
-    return callbacks
-  }
-
-  async function runCallbacks(callbacks) {
-    const eventOverrides = {}
-    let prevWasMinus, prevWasPeriod, prevValue, typedValue
-    for (const callback of callbacks) {
-      if (delay > 0) await wait(delay)
-      if (!currentElement().disabled) {
-        const returnValue = callback({
-          currentElement,
-          prevWasMinus,
-          prevWasPeriod,
-          prevValue,
-          eventOverrides,
-          typedValue,
-        })
-        Object.assign(eventOverrides, returnValue?.eventOverrides)
-        prevWasMinus = returnValue?.prevWasMinus
-        prevWasPeriod = returnValue?.prevWasPeriod
-        prevValue = returnValue?.prevValue
-        typedValue = returnValue?.typedValue
-      }
-    }
-  }
-}
-
-function getNextCallback(remainingString, skipAutoClose) {
-  const modifierCallback = getModifierCallback(remainingString, skipAutoClose)
-  if (modifierCallback) {
-    return modifierCallback
-  }
-
-  const specialCharCallback = getSpecialCharCallback(remainingString)
-  if (specialCharCallback) {
-    return specialCharCallback
-  }
-
-  return getTypeCallback(remainingString)
-}
-
-function getModifierCallback(remainingString, skipAutoClose) {
-  const modifierKey = Object.keys(modifierCallbackMap).find(key =>
-    remainingString.startsWith(key),
-  )
-  if (!modifierKey) {
-    return null
-  }
-  const callback = modifierCallbackMap[modifierKey]
-
-  // if this modifier has an associated "close" callback and the developer
-  // doesn't close it themselves, then we close it for them automatically
-  // Effectively if they send in: '{alt}a' then we type: '{alt}a{/alt}'
-  if (
-    !skipAutoClose &&
-    callback.closeName &&
-    !remainingString.includes(callback.closeName)
-  ) {
-    remainingString += callback.closeName
-  }
-  remainingString = remainingString.slice(modifierKey.length)
-  return {
-    callback,
-    remainingString,
-  }
-}
-
-function getSpecialCharCallback(remainingString) {
-  const specialChar = Object.keys(specialCharCallbackMap).find(key =>
-    remainingString.startsWith(key),
-  )
-  if (!specialChar) {
-    return null
-  }
-  return {
-    callback: specialCharCallbackMap[specialChar],
-    remainingString: remainingString.slice(specialChar.length),
-  }
-}
-
-function getTypeCallback(remainingString) {
-  const character = remainingString[0]
-  const callback = context => typeCharacter(character, context)
-  return {
-    callback,
-    remainingString: remainingString.slice(1),
-  }
-}
-
-function setSelectionRange({currentElement, newValue, newSelectionStart}) {
-  // if we *can* change the selection start, then we will if the new value
-  // is the same as the current value (so it wasn't programatically changed
-  // when the fireEvent.input was triggered).
-  // The reason we have to do this at all is because it actually *is*
-  // programmatically changed by fireEvent.input, so we have to simulate the
-  // browser's default behavior
-  const value = getValue(currentElement())
-
-  if (value === newValue) {
-    setSelectionRangeIfNecessary(
-      currentElement(),
-      newSelectionStart,
-      newSelectionStart,
-    )
-  } else {
-    // If the currentValue is different than the expected newValue and we *can*
-    // change the selection range, than we should set it to the length of the
-    // currentValue to ensure that the browser behavior is mimicked.
-    setSelectionRangeIfNecessary(currentElement(), value.length, value.length)
-  }
-}
-
-function fireInputEventIfNeeded({
-  currentElement,
-  newValue,
-  newSelectionStart,
-  eventOverrides,
-}) {
-  const prevValue = getValue(currentElement())
-  if (
-    !currentElement().readOnly &&
-    !isClickableInput(currentElement()) &&
-    newValue !== prevValue
-  ) {
-    if (isContentEditable(currentElement())) {
-      fireEvent.input(currentElement(), {
-        target: {textContent: newValue},
-        ...eventOverrides,
-      })
-    } else {
-      fireEvent.input(currentElement(), {
-        target: {value: newValue},
-        ...eventOverrides,
-      })
-    }
-
-    setSelectionRange({
-      currentElement,
-      newValue,
-      newSelectionStart,
-    })
-  }
-
-  return {prevValue}
-}
-
-function typeCharacter(
-  char,
-  {
-    currentElement,
-    prevWasMinus = false,
-    prevWasPeriod = false,
-    prevValue = '',
-    typedValue = '',
-    eventOverrides,
-  },
-) {
-  const key = char // TODO: check if this also valid for characters with diacritic markers e.g. úé etc
-  const keyCode = char.charCodeAt(0)
-  let nextPrevWasMinus, nextPrevWasPeriod
-  const textToBeTyped = typedValue + char
-  const keyDownDefaultNotPrevented = fireEvent.keyDown(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-
-  if (keyDownDefaultNotPrevented) {
-    const keyPressDefaultNotPrevented = fireEvent.keyPress(currentElement(), {
-      key,
-      keyCode,
-      charCode: keyCode,
-      ...eventOverrides,
-    })
-    if (getValue(currentElement()) != null && keyPressDefaultNotPrevented) {
-      let newEntry = char
-      if (prevWasMinus) {
-        newEntry = `-${char}`
-      } else if (prevWasPeriod) {
-        newEntry = `${prevValue}.${char}`
-      }
-
-      if (isValidDateValue(currentElement(), textToBeTyped)) {
-        newEntry = textToBeTyped
-      }
-
-      const timeNewEntry = buildTimeValue(textToBeTyped)
-      if (isValidInputTimeValue(currentElement(), timeNewEntry)) {
-        newEntry = timeNewEntry
-      }
-
-      const inputEvent = fireInputEventIfNeeded({
-        ...calculateNewValue(newEntry, currentElement()),
-        eventOverrides: {
-          data: key,
-          inputType: 'insertText',
-          ...eventOverrides,
-        },
-        currentElement,
-      })
-      prevValue = inputEvent.prevValue
-
-      if (isValidDateValue(currentElement(), textToBeTyped)) {
-        fireEvent.change(currentElement(), {target: {value: textToBeTyped}})
-      }
-
-      fireChangeForInputTimeIfValid(currentElement, prevValue, timeNewEntry)
-
-      // typing "-" into a number input will not actually update the value
-      // so for the next character we type, the value should be set to
-      // `-${newEntry}`
-      // we also preserve the prevWasMinus when the value is unchanged due
-      // to typing an invalid character (typing "-a3" results in "-3")
-      // same applies for the decimal character.
-      if (currentElement().type === 'number') {
-        const newValue = getValue(currentElement())
-        if (newValue === prevValue && newEntry !== '-') {
-          nextPrevWasMinus = prevWasMinus
-        } else {
-          nextPrevWasMinus = newEntry === '-'
-        }
-        if (newValue === prevValue && newEntry !== '.') {
-          nextPrevWasPeriod = prevWasPeriod
-        } else {
-          nextPrevWasPeriod = newEntry === '.'
-        }
-      }
-    }
-  }
-
-  fireEvent.keyUp(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-
-  return {
-    prevWasMinus: nextPrevWasMinus,
-    prevWasPeriod: nextPrevWasPeriod,
-    prevValue,
-    typedValue: textToBeTyped,
-  }
-}
-
-function fireChangeForInputTimeIfValid(
-  currentElement,
-  prevValue,
-  timeNewEntry,
-) {
-  if (
-    isValidInputTimeValue(currentElement(), timeNewEntry) &&
-    prevValue !== timeNewEntry
-  ) {
-    fireEvent.change(currentElement(), {target: {value: timeNewEntry}})
-  }
-}
-
-// yes, calculateNewBackspaceValue and calculateNewValue look extremely similar
-// and you may be tempted to create a shared abstraction.
-// If you, brave soul, decide to so endevor, please increment this count
-// when you inevitably fail: 1
-function calculateNewBackspaceValue(element) {
-  const {selectionStart, selectionEnd} = getSelectionRange(element)
-  const value = getValue(element)
-  let newValue, newSelectionStart
-
-  if (selectionStart === null) {
-    // at the end of an input type that does not support selection ranges
-    // https://github.com/testing-library/user-event/issues/316#issuecomment-639744793
-    newValue = value.slice(0, value.length - 1)
-    newSelectionStart = selectionStart - 1
-  } else if (selectionStart === selectionEnd) {
-    if (selectionStart === 0) {
-      // at the beginning of the input
-      newValue = value
-      newSelectionStart = selectionStart
-    } else if (selectionStart === value.length) {
-      // at the end of the input
-      newValue = value.slice(0, value.length - 1)
-      newSelectionStart = selectionStart - 1
-    } else {
-      // in the middle of the input
-      newValue = value.slice(0, selectionStart - 1) + value.slice(selectionEnd)
-      newSelectionStart = selectionStart - 1
-    }
-  } else {
-    // we have something selected
-    const firstPart = value.slice(0, selectionStart)
-    newValue = firstPart + value.slice(selectionEnd)
-    newSelectionStart = firstPart.length
-  }
-
-  return {newValue, newSelectionStart}
-}
-
-function calculateNewDeleteValue(element) {
-  const {selectionStart, selectionEnd} = getSelectionRange(element)
-  const value = getValue(element)
-  let newValue
-
-  if (selectionStart === null) {
-    // at the end of an input type that does not support selection ranges
-    // https://github.com/testing-library/user-event/issues/316#issuecomment-639744793
-    newValue = value
-  } else if (selectionStart === selectionEnd) {
-    if (selectionStart === 0) {
-      // at the beginning of the input
-      newValue = value.slice(1)
-    } else if (selectionStart === value.length) {
-      // at the end of the input
-      newValue = value
-    } else {
-      // in the middle of the input
-      newValue = value.slice(0, selectionStart) + value.slice(selectionEnd + 1)
-    }
-  } else {
-    // we have something selected
-    const firstPart = value.slice(0, selectionStart)
-    newValue = firstPart + value.slice(selectionEnd)
-  }
-
-  return {newValue, newSelectionStart: selectionStart}
-}
-
-function createModifierCallbackEntries({name, key, keyCode, modifierProperty}) {
-  const openName = `{${name}}`
-  const closeName = `{/${name}}`
-
-  function open({currentElement, eventOverrides}) {
-    const newEventOverrides = {[modifierProperty]: true}
-
-    fireEvent.keyDown(currentElement(), {
-      key,
-      keyCode,
-      which: keyCode,
-      ...eventOverrides,
-      ...newEventOverrides,
-    })
-
-    return {eventOverrides: newEventOverrides}
-  }
-  open.closeName = closeName
-  function close({currentElement, eventOverrides}) {
-    const newEventOverrides = {[modifierProperty]: false}
-
-    fireEvent.keyUp(currentElement(), {
-      key,
-      keyCode,
-      which: keyCode,
-      ...eventOverrides,
-      ...newEventOverrides,
-    })
-
-    return {eventOverrides: newEventOverrides}
-  }
-  return {
-    [openName]: open,
-    [closeName]: close,
-  }
-}
-
-function handleEnter({currentElement, eventOverrides}) {
-  const key = 'Enter'
-  const keyCode = 13
-
-  const keyDownDefaultNotPrevented = fireEvent.keyDown(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-
-  if (keyDownDefaultNotPrevented) {
-    const keyPressDefaultNotPrevented = fireEvent.keyPress(currentElement(), {
-      key,
-      keyCode,
-      charCode: keyCode,
-      ...eventOverrides,
-    })
-
-    if (keyPressDefaultNotPrevented) {
-      if (
-        isClickableInput(currentElement()) ||
-        // Links with href defined should handle Enter the same as a click
-        (isInstanceOfElement(currentElement(), 'HTMLAnchorElement') &&
-          currentElement().href)
-      ) {
-        fireEvent.click(currentElement(), {
-          ...eventOverrides,
-        })
-      }
-
-      if (currentElement().tagName === 'TEXTAREA') {
-        const {newValue, newSelectionStart} = calculateNewValue(
-          '\n',
-          currentElement(),
-        )
-        fireEvent.input(currentElement(), {
-          target: {value: newValue},
-          inputType: 'insertLineBreak',
-          ...eventOverrides,
-        })
-        setSelectionRange({
-          currentElement,
-          newValue,
-          newSelectionStart,
-        })
-      }
-
-      if (
-        currentElement().tagName === 'INPUT' &&
-        currentElement().form &&
-        (currentElement().form.querySelectorAll('input').length === 1 ||
-          currentElement().form.querySelector('input[type="submit"]') ||
-          currentElement().form.querySelector('button[type="submit"]'))
-      ) {
-        fireEvent.submit(currentElement().form)
-      }
-    }
-  }
-
-  fireEvent.keyUp(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-}
-
-function handleEsc({currentElement, eventOverrides}) {
-  const key = 'Escape'
-  const keyCode = 27
-
-  fireEvent.keyDown(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-
-  // NOTE: Browsers do not fire a keypress on meta key presses
-
-  fireEvent.keyUp(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-}
-
-function handleDel({currentElement, eventOverrides}) {
-  const key = 'Delete'
-  const keyCode = 46
-
-  const keyPressDefaultNotPrevented = fireEvent.keyDown(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-
-  if (keyPressDefaultNotPrevented) {
-    fireInputEventIfNeeded({
-      ...calculateNewDeleteValue(currentElement()),
-      eventOverrides: {
-        inputType: 'deleteContentForward',
-        ...eventOverrides,
-      },
-      currentElement,
-    })
-  }
-
-  fireEvent.keyUp(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-}
-
-function handleBackspace({currentElement, eventOverrides}) {
-  const key = 'Backspace'
-  const keyCode = 8
-
-  const keyPressDefaultNotPrevented = fireEvent.keyDown(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-
-  if (keyPressDefaultNotPrevented) {
-    fireInputEventIfNeeded({
-      ...calculateNewBackspaceValue(currentElement()),
-      eventOverrides: {
-        inputType: 'deleteContentBackward',
-        ...eventOverrides,
-      },
-      currentElement,
-    })
-  }
-
-  fireEvent.keyUp(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-}
-
-function handleSelectall({currentElement}) {
-  currentElement().setSelectionRange(0, getValue(currentElement()).length)
-}
-
-function handleSpace(context) {
-  if (isClickableInput(context.currentElement())) {
-    handleSpaceOnClickable(context)
-    return
-  }
-  typeCharacter(' ', context)
-}
-
-function handleSpaceOnClickable({currentElement, eventOverrides}) {
-  const key = ' '
-  const keyCode = 32
-
-  const keyDownDefaultNotPrevented = fireEvent.keyDown(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-
-  if (keyDownDefaultNotPrevented) {
-    fireEvent.keyPress(currentElement(), {
-      key,
-      keyCode,
-      charCode: keyCode,
-      ...eventOverrides,
-    })
-  }
-
-  const keyUpDefaultNotPrevented = fireEvent.keyUp(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-
-  if (keyDownDefaultNotPrevented && keyUpDefaultNotPrevented) {
-    fireEvent.click(currentElement(), {
-      ...eventOverrides,
-    })
-  }
-}
-
-function handleArrowDown({currentElement, eventOverrides}) {
-  const key = 'ArrowDown'
-  const keyCode = 40
-
-  fireEvent.keyDown(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-
-  fireEvent.keyUp(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-}
-
-function handleArrowUp({currentElement, eventOverrides}) {
-  const key = 'ArrowUp'
-  const keyCode = 38
-
-  fireEvent.keyDown(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-
-  fireEvent.keyUp(currentElement(), {
-    key,
-    keyCode,
-    which: keyCode,
-    ...eventOverrides,
-  })
-}
-
-export {type, specialCharMap}
diff --git a/src/type/index.ts b/src/type/index.ts
new file mode 100644
index 00000000..74c99edd
--- /dev/null
+++ b/src/type/index.ts
@@ -0,0 +1,34 @@
+import {getConfig as getDOMTestingLibraryConfig} from '@testing-library/dom'
+import {typeImplementation, typeOptions} from './typeImplementation'
+
+export function type(
+  element: Element,
+  text: string,
+  options?: typeOptions & {delay?: 0},
+): void
+export function type(
+  element: Element,
+  text: string,
+  options: typeOptions & {delay: number},
+): Promise<void>
+// this needs to be wrapped in the event/asyncWrapper for React's act and angular's change detection
+// depending on whether it will be async.
+export function type(
+  element: Element,
+  text: string,
+  {delay = 0, ...options}: typeOptions = {},
+): Promise<void> | void {
+  // we do not want to wrap in the asyncWrapper if we're not
+  // going to actually be doing anything async, so we only wrap
+  // if the delay is greater than 0
+
+  if (delay > 0) {
+    return getDOMTestingLibraryConfig().asyncWrapper(() =>
+      typeImplementation(element, text, {delay, ...options}),
+    )
+  } else {
+    return void typeImplementation(element, text, {delay, ...options})
+      // prevents users from dealing with UnhandledPromiseRejectionWarning
+      .catch(console.error)
+  }
+}
diff --git a/src/type/typeImplementation.ts b/src/type/typeImplementation.ts
new file mode 100644
index 00000000..864e8d71
--- /dev/null
+++ b/src/type/typeImplementation.ts
@@ -0,0 +1,81 @@
+import {
+  setSelectionRangeIfNecessary,
+  getSelectionRange,
+  getValue,
+  isContentEditable,
+  getActiveElement,
+} from '../utils'
+import {click} from '../click'
+import {keyboardImplementationWrapper} from '../keyboard'
+
+export interface typeOptions {
+  delay?: number
+  skipClick?: boolean
+  skipAutoClose?: boolean
+  initialSelectionStart?: number
+  initialSelectionEnd?: number
+}
+
+export async function typeImplementation(
+  element: Element,
+  text: string,
+  {
+    delay,
+    skipClick = false,
+    skipAutoClose = false,
+    initialSelectionStart = undefined,
+    initialSelectionEnd = undefined,
+  }: typeOptions & {delay: number},
+): Promise<void> {
+  // TODO: properly type guard
+  // we use this workaround for now to prevent changing behavior
+  if ((element as {disabled?: boolean}).disabled) return
+
+  if (!skipClick) click(element)
+
+  if (isContentEditable(element)) {
+    const selection = document.getSelection()
+    // istanbul ignore else
+    if (selection && selection.rangeCount === 0) {
+      const range = document.createRange()
+      range.setStart(element, 0)
+      range.setEnd(element, 0)
+      selection.addRange(range)
+    }
+  }
+  // The focused element could change between each event, so get the currently active element each time
+  const currentElement = () => getActiveElement(element.ownerDocument)
+
+  // by default, a new element has it's selection start and end at 0
+  // but most of the time when people call "type", they expect it to type
+  // at the end of the current input value. So, if the selection start
+  // and end are both the default of 0, then we'll go ahead and change
+  // them to the length of the current value.
+  // the only time it would make sense to pass the initialSelectionStart or
+  // initialSelectionEnd is if you have an input with a value and want to
+  // explicitely start typing with the cursor at 0. Not super common.
+  const value = getValue(currentElement())
+
+  const {selectionStart, selectionEnd} = getSelectionRange(element)
+
+  if (value != null && selectionStart === 0 && selectionEnd === 0) {
+    setSelectionRangeIfNecessary(
+      currentElement() as Element,
+      initialSelectionStart ?? value.length,
+      initialSelectionEnd ?? value.length,
+    )
+  }
+
+  const {promise, releaseAllKeys} = keyboardImplementationWrapper(text, {
+    delay,
+    document: element.ownerDocument,
+  })
+
+  if (delay > 0) {
+    await promise
+  }
+
+  if (!skipAutoClose) {
+    releaseAllKeys()
+  }
+}
diff --git a/src/utils.js b/src/utils.js
deleted file mode 100644
index b4825948..00000000
--- a/src/utils.js
+++ /dev/null
@@ -1,384 +0,0 @@
-import {getConfig} from '@testing-library/dom'
-import {getWindowFromNode} from '@testing-library/dom/dist/helpers'
-
-// isInstanceOfElement can be removed once the peerDependency for @testing-library/dom is bumped to a version that includes https://github.com/testing-library/dom-testing-library/pull/885
-/**
- * Check if an element is of a given type.
- *
- * @param {Element} element The element to test
- * @param {string} elementType Constructor name. E.g. 'HTMLSelectElement'
- */
-function isInstanceOfElement(element, elementType) {
-  try {
-    const window = getWindowFromNode(element)
-    // Window usually has the element constructors as properties but is not required to do so per specs
-    if (typeof window[elementType] === 'function') {
-      return element instanceof window[elementType]
-    }
-  } catch (e) {
-    // The document might not be associated with a window
-  }
-
-  // Fall back to the constructor name as workaround for test environments that
-  // a) not associate the document with a window
-  // b) not provide the constructor as property of window
-  if (/^HTML(\w+)Element$/.test(element.constructor.name)) {
-    return element.constructor.name === elementType
-  }
-
-  // The user passed some node that is not created in a browser-like environment
-  throw new Error(
-    `Unable to verify if element is instance of ${elementType}. Please file an issue describing your test environment: https://github.com/testing-library/dom-testing-library/issues/new`,
-  )
-}
-
-function isMousePressEvent(event) {
-  return (
-    event === 'mousedown' ||
-    event === 'mouseup' ||
-    event === 'click' ||
-    event === 'dblclick'
-  )
-}
-
-function invert(map) {
-  const res = {}
-  for (const key of Object.keys(map)) {
-    res[map[key]] = key
-  }
-
-  return res
-}
-
-// https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons
-const BUTTONS_TO_NAMES = {
-  0: 'none',
-  1: 'primary',
-  2: 'secondary',
-  4: 'auxiliary',
-}
-const NAMES_TO_BUTTONS = invert(BUTTONS_TO_NAMES)
-
-// https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
-const BUTTON_TO_NAMES = {
-  0: 'primary',
-  1: 'auxiliary',
-  2: 'secondary',
-}
-
-const NAMES_TO_BUTTON = invert(BUTTON_TO_NAMES)
-
-function convertMouseButtons(event, init, property, mapping) {
-  if (!isMousePressEvent(event)) {
-    return 0
-  }
-
-  if (init[property] != null) {
-    return init[property]
-  }
-
-  if (init.buttons != null) {
-    // not sure how to test this. Feel free to try and add a test if you want.
-    // istanbul ignore next
-    return mapping[BUTTONS_TO_NAMES[init.buttons]] || 0
-  }
-
-  if (init.button != null) {
-    // not sure how to test this. Feel free to try and add a test if you want.
-    // istanbul ignore next
-    return mapping[BUTTON_TO_NAMES[init.button]] || 0
-  }
-
-  return property != 'button' && isMousePressEvent(event) ? 1 : 0
-}
-
-function getMouseEventOptions(event, init, clickCount = 0) {
-  init = init || {}
-  return {
-    ...init,
-    // https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail
-    detail:
-      event === 'mousedown' || event === 'mouseup' || event === 'click'
-        ? 1 + clickCount
-        : clickCount,
-    buttons: convertMouseButtons(event, init, 'buttons', NAMES_TO_BUTTONS),
-    button: convertMouseButtons(event, init, 'button', NAMES_TO_BUTTON),
-  }
-}
-
-// Absolutely NO events fire on label elements that contain their control
-// if that control is disabled. NUTS!
-// no joke. There are NO events for: <label><input disabled /><label>
-function isLabelWithInternallyDisabledControl(element) {
-  return (
-    element.tagName === 'LABEL' &&
-    element.control?.disabled &&
-    element.contains(element.control)
-  )
-}
-
-function getActiveElement(document) {
-  const activeElement = document.activeElement
-  if (activeElement?.shadowRoot) {
-    return getActiveElement(activeElement.shadowRoot)
-  } else {
-    return activeElement
-  }
-}
-
-function supportsMaxLength(element) {
-  if (element.tagName === 'TEXTAREA') return true
-
-  if (element.tagName === 'INPUT') {
-    const type = element.getAttribute('type')
-
-    // Missing value default is "text"
-    if (!type) return true
-
-    // https://html.spec.whatwg.org/multipage/input.html#concept-input-apply
-    if (type.match(/email|password|search|telephone|text|url/)) return true
-  }
-
-  return false
-}
-
-function getSelectionRange(element) {
-  if (isContentEditable(element)) {
-    const range = element.ownerDocument.getSelection().getRangeAt(0)
-
-    return {selectionStart: range.startOffset, selectionEnd: range.endOffset}
-  }
-
-  return {
-    selectionStart: element.selectionStart,
-    selectionEnd: element.selectionEnd,
-  }
-}
-
-//jsdom is not supporting isContentEditable
-function isContentEditable(element) {
-  return (
-    element.hasAttribute('contenteditable') &&
-    (element.getAttribute('contenteditable') == 'true' ||
-      element.getAttribute('contenteditable') == '')
-  )
-}
-
-function getValue(element) {
-  if (isContentEditable(element)) {
-    return element.textContent
-  }
-  return element.value
-}
-
-function calculateNewValue(newEntry, element) {
-  const {selectionStart, selectionEnd} = getSelectionRange(element)
-  const value = getValue(element)
-
-  // can't use .maxLength property because of a jsdom bug:
-  // https://github.com/jsdom/jsdom/issues/2927
-  const maxLength = Number(element.getAttribute('maxlength') ?? -1)
-  let newValue, newSelectionStart
-
-  if (selectionStart === null) {
-    // at the end of an input type that does not support selection ranges
-    // https://github.com/testing-library/user-event/issues/316#issuecomment-639744793
-    newValue = value + newEntry
-  } else if (selectionStart === selectionEnd) {
-    if (selectionStart === 0) {
-      // at the beginning of the input
-      newValue = newEntry + value
-    } else if (selectionStart === value.length) {
-      // at the end of the input
-      newValue = value + newEntry
-    } else {
-      // in the middle of the input
-      newValue =
-        value.slice(0, selectionStart) + newEntry + value.slice(selectionEnd)
-    }
-    newSelectionStart = selectionStart + newEntry.length
-  } else {
-    // we have something selected
-    const firstPart = value.slice(0, selectionStart) + newEntry
-    newValue = firstPart + value.slice(selectionEnd)
-    newSelectionStart = firstPart.length
-  }
-
-  if (element.type === 'date' && !isValidDateValue(element, newValue)) {
-    newValue = value
-  }
-
-  if (element.type === 'time' && !isValidInputTimeValue(element, newValue)) {
-    if (isValidInputTimeValue(element, newEntry)) {
-      newValue = newEntry
-    } else {
-      newValue = value
-    }
-  }
-
-  if (!supportsMaxLength(element) || maxLength < 0) {
-    return {newValue, newSelectionStart}
-  } else {
-    return {
-      newValue: newValue.slice(0, maxLength),
-      newSelectionStart:
-        newSelectionStart > maxLength ? maxLength : newSelectionStart,
-    }
-  }
-}
-
-function setSelectionRangeIfNecessary(
-  element,
-  newSelectionStart,
-  newSelectionEnd,
-) {
-  const {selectionStart, selectionEnd} = getSelectionRange(element)
-
-  if (
-    !isContentEditable(element) &&
-    (!element.setSelectionRange || selectionStart === null)
-  ) {
-    // cannot set selection
-    return
-  }
-  if (
-    selectionStart !== newSelectionStart ||
-    selectionEnd !== newSelectionStart
-  ) {
-    if (isContentEditable(element)) {
-      const range = element.ownerDocument.createRange()
-      range.selectNodeContents(element)
-      range.setStart(element.firstChild, newSelectionStart)
-      range.setEnd(element.firstChild, newSelectionEnd)
-      element.ownerDocument.getSelection().removeAllRanges()
-      element.ownerDocument.getSelection().addRange(range)
-    } else {
-      element.setSelectionRange(newSelectionStart, newSelectionEnd)
-    }
-  }
-}
-
-const FOCUSABLE_SELECTOR = [
-  'input:not([type=hidden]):not([disabled])',
-  'button:not([disabled])',
-  'select:not([disabled])',
-  'textarea:not([disabled])',
-  '[contenteditable=""]',
-  '[contenteditable="true"]',
-  'a[href]',
-  '[tabindex]:not([disabled])',
-].join(', ')
-
-function isFocusable(element) {
-  return (
-    !isLabelWithInternallyDisabledControl(element) &&
-    element?.matches(FOCUSABLE_SELECTOR)
-  )
-}
-
-const CLICKABLE_INPUT_TYPES = [
-  'button',
-  'color',
-  'file',
-  'image',
-  'reset',
-  'submit',
-]
-
-function isClickableInput(element) {
-  return (
-    element.tagName === 'BUTTON' ||
-    (isInstanceOfElement(element, 'HTMLInputElement') &&
-      CLICKABLE_INPUT_TYPES.includes(element.type))
-  )
-}
-
-function isVisible(element) {
-  const getComputedStyle = getWindowFromNode(element).getComputedStyle
-
-  for(; element && element.ownerDocument; element = element.parentNode) {
-    const display = getComputedStyle(element).display
-    if (display === 'none') {
-      return false
-    }
-  }
-
-  return true
-}
-
-function eventWrapper(cb) {
-  let result
-  getConfig().eventWrapper(() => {
-    result = cb()
-  })
-  return result
-}
-
-function isValidDateValue(element, value) {
-  if (element.type !== 'date') return false
-
-  const clone = element.cloneNode()
-  clone.value = value
-  return clone.value === value
-}
-
-function buildTimeValue(value) {
-  function build(onlyDigitsValue, index) {
-    const hours = onlyDigitsValue.slice(0, index)
-    const validHours = Math.min(parseInt(hours, 10), 23)
-    const minuteCharacters = onlyDigitsValue.slice(index)
-    const parsedMinutes = parseInt(minuteCharacters, 10)
-    const validMinutes = Math.min(parsedMinutes, 59)
-    return `${validHours
-      .toString()
-      .padStart(2, '0')}:${validMinutes.toString().padStart(2, '0')}`
-  }
-
-  const onlyDigitsValue = value.replace(/\D/g, '')
-  if (onlyDigitsValue.length < 2) {
-    return value
-  }
-  const firstDigit = parseInt(onlyDigitsValue[0], 10)
-  const secondDigit = parseInt(onlyDigitsValue[1], 10)
-  if (firstDigit >= 3 || (firstDigit === 2 && secondDigit >= 4)) {
-    let index
-    if (firstDigit >= 3) {
-      index = 1
-    } else {
-      index = 2
-    }
-    return build(onlyDigitsValue, index)
-  }
-  if (value.length === 2) {
-    return value
-  }
-  return build(onlyDigitsValue, 2)
-}
-
-function isValidInputTimeValue(element, timeValue) {
-  if (element.type !== 'time') return false
-
-  const clone = element.cloneNode()
-  clone.value = timeValue
-  return clone.value === timeValue
-}
-
-export {
-  FOCUSABLE_SELECTOR,
-  isFocusable,
-  isClickableInput,
-  getMouseEventOptions,
-  isLabelWithInternallyDisabledControl,
-  getActiveElement,
-  calculateNewValue,
-  setSelectionRangeIfNecessary,
-  eventWrapper,
-  isValidDateValue,
-  isValidInputTimeValue,
-  buildTimeValue,
-  getValue,
-  getSelectionRange,
-  isContentEditable,
-  isInstanceOfElement,
-  isVisible,
-}
diff --git a/src/utils/click/getMouseEventOptions.ts b/src/utils/click/getMouseEventOptions.ts
new file mode 100644
index 00000000..d798a151
--- /dev/null
+++ b/src/utils/click/getMouseEventOptions.ts
@@ -0,0 +1,75 @@
+function isMousePressEvent(event: string) {
+  return (
+    event === 'mousedown' ||
+    event === 'mouseup' ||
+    event === 'click' ||
+    event === 'dblclick'
+  )
+}
+
+// https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons
+const BUTTONS_NAMES = {
+  none: 0,
+  primary: 1,
+  secondary: 2,
+  auxiliary: 4,
+} as const
+
+// https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
+const BUTTON_NAMES = {
+  primary: 0,
+  auxiliary: 1,
+  secondary: 2,
+} as const
+
+function translateButtonNumber(value: number, from: 'button' | 'buttons') {
+  const [mapIn, mapOut] =
+    from === 'button'
+      ? [BUTTON_NAMES, BUTTONS_NAMES]
+      : [BUTTONS_NAMES, BUTTON_NAMES]
+
+  const name = Object.entries(mapIn).find(([, i]) => i === value)?.[0]
+
+  // istanbul ignore next
+  return name && Object.prototype.hasOwnProperty.call(mapOut, name)
+    ? mapOut[name as keyof typeof mapOut]
+    : 0
+}
+
+function convertMouseButtons(
+  event: string,
+  init: MouseEventInit,
+  property: 'button' | 'buttons',
+): number {
+  if (!isMousePressEvent(event)) {
+    return 0
+  }
+
+  if (typeof init[property] === 'number') {
+    return init[property] as number
+  } else if (property === 'button' && typeof init.buttons === 'number') {
+    return translateButtonNumber(init.buttons, 'buttons')
+  } else if (property === 'buttons' && typeof init.button === 'number') {
+    return translateButtonNumber(init.button, 'button')
+  }
+
+  return property != 'button' && isMousePressEvent(event) ? 1 : 0
+}
+
+export function getMouseEventOptions(
+  event: string,
+  init?: MouseEventInit,
+  clickCount = 0,
+) {
+  init = init ?? {}
+  return {
+    ...init,
+    // https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail
+    detail:
+      event === 'mousedown' || event === 'mouseup' || event === 'click'
+        ? 1 + clickCount
+        : clickCount,
+    buttons: convertMouseButtons(event, init, 'buttons'),
+    button: convertMouseButtons(event, init, 'button'),
+  }
+}
diff --git a/src/utils/click/isClickableInput.ts b/src/utils/click/isClickableInput.ts
new file mode 100644
index 00000000..88f47687
--- /dev/null
+++ b/src/utils/click/isClickableInput.ts
@@ -0,0 +1,18 @@
+import {isInstanceOfElement} from '../misc/isInstanceOfElement'
+
+const CLICKABLE_INPUT_TYPES = [
+  'button',
+  'color',
+  'file',
+  'image',
+  'reset',
+  'submit',
+]
+
+export function isClickableInput(element: Element): boolean {
+  return (
+    element.tagName === 'BUTTON' ||
+    (isInstanceOfElement(element, 'HTMLInputElement') &&
+      CLICKABLE_INPUT_TYPES.includes((element as HTMLInputElement).type))
+  )
+}
diff --git a/src/utils/edit/buildTimeValue.ts b/src/utils/edit/buildTimeValue.ts
new file mode 100644
index 00000000..145b65e1
--- /dev/null
+++ b/src/utils/edit/buildTimeValue.ts
@@ -0,0 +1,32 @@
+export function buildTimeValue(value: string): string {
+  const onlyDigitsValue = value.replace(/\D/g, '')
+  if (onlyDigitsValue.length < 2) {
+    return value
+  }
+  const firstDigit = parseInt(onlyDigitsValue[0], 10)
+  const secondDigit = parseInt(onlyDigitsValue[1], 10)
+  if (firstDigit >= 3 || (firstDigit === 2 && secondDigit >= 4)) {
+    let index
+    if (firstDigit >= 3) {
+      index = 1
+    } else {
+      index = 2
+    }
+    return build(onlyDigitsValue, index)
+  }
+  if (value.length === 2) {
+    return value
+  }
+  return build(onlyDigitsValue, 2)
+}
+
+function build(onlyDigitsValue: string, index: number): string {
+  const hours = onlyDigitsValue.slice(0, index)
+  const validHours = Math.min(parseInt(hours, 10), 23)
+  const minuteCharacters = onlyDigitsValue.slice(index)
+  const parsedMinutes = parseInt(minuteCharacters, 10)
+  const validMinutes = Math.min(parsedMinutes, 59)
+  return `${validHours
+    .toString()
+    .padStart(2, '0')}:${validMinutes.toString().padStart(2, '0')}`
+}
diff --git a/src/utils/edit/calculateNewValue.ts b/src/utils/edit/calculateNewValue.ts
new file mode 100644
index 00000000..03e929be
--- /dev/null
+++ b/src/utils/edit/calculateNewValue.ts
@@ -0,0 +1,103 @@
+import {getSelectionRange} from './getSelectionRange'
+import {getValue} from './getValue'
+import {isValidDateValue} from './isValidDateValue'
+import {isValidInputTimeValue} from './isValidInputTimeValue'
+
+export function calculateNewValue(
+  newEntry: string,
+  element: HTMLElement,
+  value = getValue(element),
+  selectionRange = getSelectionRange(element),
+): {
+  newValue: string
+  newSelectionStart: number
+} {
+  const {selectionStart, selectionEnd} = selectionRange
+
+  // can't use .maxLength property because of a jsdom bug:
+  // https://github.com/jsdom/jsdom/issues/2927
+  const maxLength = Number(element.getAttribute('maxlength') ?? -1)
+
+  let newValue: string, newSelectionStart: number
+
+  if (selectionStart === null) {
+    // at the end of an input type that does not support selection ranges
+    // https://github.com/testing-library/user-event/issues/316#issuecomment-639744793
+    newValue = `${value}${newEntry}`
+    newSelectionStart = newValue.length
+  } else if (selectionStart === selectionEnd) {
+    if (selectionStart === 0) {
+      // at the beginning of the input
+      newValue = `${newEntry}${value}`
+    } else if (selectionStart === value?.length) {
+      // at the end of the input
+      newValue = `${value}${newEntry}`
+    } else {
+      // in the middle of the input
+      newValue = `${value?.slice(0, selectionStart)}${newEntry}${value?.slice(
+        selectionEnd,
+      )}`
+    }
+    newSelectionStart = selectionStart + newEntry.length
+  } else {
+    // we have something selected
+    const firstPart = `${value?.slice(0, selectionStart)}${newEntry}`
+    newValue = `${firstPart}${value?.slice(selectionEnd as number)}`
+    newSelectionStart = firstPart.length
+  }
+
+  if (
+    (element as HTMLInputElement).type === 'date' &&
+    !isValidDateValue(element as HTMLInputElement & {type: 'date'}, newValue)
+  ) {
+    newValue = value as string
+  }
+
+  if (
+    (element as HTMLInputElement).type === 'time' &&
+    !isValidInputTimeValue(
+      element as HTMLInputElement & {type: 'time'},
+      newValue,
+    )
+  ) {
+    if (
+      isValidInputTimeValue(
+        element as HTMLInputElement & {type: 'time'},
+        newEntry,
+      )
+    ) {
+      newValue = newEntry
+    } else {
+      newValue = value as string
+    }
+  }
+
+  if (!supportsMaxLength(element) || maxLength < 0) {
+    return {
+      newValue,
+      newSelectionStart,
+    }
+  } else {
+    return {
+      newValue: newValue.slice(0, maxLength),
+      newSelectionStart:
+        newSelectionStart > maxLength ? maxLength : newSelectionStart,
+    }
+  }
+}
+
+function supportsMaxLength(element: Element) {
+  if (element.tagName === 'TEXTAREA') return true
+
+  if (element.tagName === 'INPUT') {
+    const type = element.getAttribute('type')
+
+    // Missing value default is "text"
+    if (!type) return true
+
+    // https://html.spec.whatwg.org/multipage/input.html#concept-input-apply
+    if (type.match(/email|password|search|telephone|text|url/)) return true
+  }
+
+  return false
+}
diff --git a/src/utils/edit/getSelectionRange.ts b/src/utils/edit/getSelectionRange.ts
new file mode 100644
index 00000000..7d8476f6
--- /dev/null
+++ b/src/utils/edit/getSelectionRange.ts
@@ -0,0 +1,31 @@
+import {isContentEditable} from './isContentEditable'
+
+export function getSelectionRange(
+  element: Element,
+): {
+  selectionStart: number | null
+  selectionEnd: number | null
+} {
+  if (isContentEditable(element)) {
+    const selection = element.ownerDocument.getSelection()
+    const range = selection?.getRangeAt(0)
+
+    // istanbul ignore else
+    if (range) {
+      return {
+        selectionStart: range.startOffset,
+        selectionEnd: range.endOffset,
+      }
+    } else {
+      return {
+        selectionStart: null,
+        selectionEnd: null,
+      }
+    }
+  }
+
+  return {
+    selectionStart: (element as HTMLInputElement).selectionStart,
+    selectionEnd: (element as HTMLInputElement).selectionEnd,
+  }
+}
diff --git a/src/utils/edit/getValue.ts b/src/utils/edit/getValue.ts
new file mode 100644
index 00000000..126e258f
--- /dev/null
+++ b/src/utils/edit/getValue.ts
@@ -0,0 +1,12 @@
+import {isContentEditable} from './isContentEditable'
+
+export function getValue(element: Element | null): string | null {
+  // istanbul ignore if
+  if (!element) {
+    return null
+  }
+  if (isContentEditable(element)) {
+    return element.textContent
+  }
+  return (element as HTMLInputElement).value
+}
diff --git a/src/utils/edit/isContentEditable.ts b/src/utils/edit/isContentEditable.ts
new file mode 100644
index 00000000..877e63a8
--- /dev/null
+++ b/src/utils/edit/isContentEditable.ts
@@ -0,0 +1,8 @@
+//jsdom is not supporting isContentEditable
+export function isContentEditable(element: Element): boolean {
+  return (
+    element.hasAttribute('contenteditable') &&
+    (element.getAttribute('contenteditable') == 'true' ||
+      element.getAttribute('contenteditable') == '')
+  )
+}
diff --git a/src/utils/edit/isValidDateValue.ts b/src/utils/edit/isValidDateValue.ts
new file mode 100644
index 00000000..22135b65
--- /dev/null
+++ b/src/utils/edit/isValidDateValue.ts
@@ -0,0 +1,8 @@
+export function isValidDateValue(
+  element: HTMLInputElement & {type: 'date'},
+  value: string,
+): boolean {
+  const clone = element.cloneNode() as HTMLInputElement
+  clone.value = value
+  return clone.value === value
+}
diff --git a/src/utils/edit/isValidInputTimeValue.ts b/src/utils/edit/isValidInputTimeValue.ts
new file mode 100644
index 00000000..1e96146f
--- /dev/null
+++ b/src/utils/edit/isValidInputTimeValue.ts
@@ -0,0 +1,8 @@
+export function isValidInputTimeValue(
+  element: HTMLInputElement & {type: 'time'},
+  timeValue: string,
+): boolean {
+  const clone = element.cloneNode() as HTMLInputElement
+  clone.value = timeValue
+  return clone.value === timeValue
+}
diff --git a/src/utils/edit/setSelectionRangeIfNecessary.ts b/src/utils/edit/setSelectionRangeIfNecessary.ts
new file mode 100644
index 00000000..2a4078ed
--- /dev/null
+++ b/src/utils/edit/setSelectionRangeIfNecessary.ts
@@ -0,0 +1,46 @@
+import {isContentEditable} from './isContentEditable'
+import {getSelectionRange} from './getSelectionRange'
+
+export function setSelectionRangeIfNecessary(
+  element: Element,
+  newSelectionStart: number,
+  newSelectionEnd: number,
+) {
+  const {selectionStart, selectionEnd} = getSelectionRange(element)
+
+  if (
+    !isContentEditable(element) &&
+    (!(element as {setSelectionRange?: unknown}).setSelectionRange ||
+      selectionStart === null)
+  ) {
+    // cannot set selection
+    return
+  }
+  if (
+    selectionStart !== newSelectionStart ||
+    selectionEnd !== newSelectionStart
+  ) {
+    if (isContentEditable(element)) {
+      const range = element.ownerDocument.createRange()
+      range.selectNodeContents(element)
+
+      // istanbul ignore else
+      if (element.firstChild) {
+        range.setStart(element.firstChild, newSelectionStart)
+        range.setEnd(element.firstChild, newSelectionEnd)
+      }
+
+      const selection = element.ownerDocument.getSelection()
+      // istanbul ignore else
+      if (selection) {
+        selection.removeAllRanges()
+        selection.addRange(range)
+      }
+    } else {
+      ;(element as HTMLInputElement).setSelectionRange(
+        newSelectionStart,
+        newSelectionEnd,
+      )
+    }
+  }
+}
diff --git a/src/utils/focus/getActiveElement.ts b/src/utils/focus/getActiveElement.ts
new file mode 100644
index 00000000..b2bd25c5
--- /dev/null
+++ b/src/utils/focus/getActiveElement.ts
@@ -0,0 +1,21 @@
+import {isDisabled} from '../misc/isDisabled'
+
+export function getActiveElement(
+  document: Document | ShadowRoot,
+): Element | null {
+  const activeElement = document.activeElement
+
+  if (activeElement?.shadowRoot) {
+    return getActiveElement(activeElement.shadowRoot)
+  } else {
+    // Browser does not yield disabled elements as document.activeElement - jsdom does
+    if (isDisabled(activeElement)) {
+      return document.ownerDocument
+        ? // TODO: verify behavior in ShadowRoot
+          /* istanbul ignore next */ document.ownerDocument.body
+        : document.body
+    }
+
+    return activeElement
+  }
+}
diff --git a/src/utils/focus/isFocusable.ts b/src/utils/focus/isFocusable.ts
new file mode 100644
index 00000000..b07e1f52
--- /dev/null
+++ b/src/utils/focus/isFocusable.ts
@@ -0,0 +1,9 @@
+import {isLabelWithInternallyDisabledControl} from '../misc/isLabelWithInternallyDisabledControl'
+import {FOCUSABLE_SELECTOR} from './selector'
+
+export function isFocusable(element: Element): element is HTMLElement {
+  return (
+    !isLabelWithInternallyDisabledControl(element) &&
+    element.matches(FOCUSABLE_SELECTOR)
+  )
+}
diff --git a/src/utils/focus/selector.ts b/src/utils/focus/selector.ts
new file mode 100644
index 00000000..52d500fa
--- /dev/null
+++ b/src/utils/focus/selector.ts
@@ -0,0 +1,10 @@
+export const FOCUSABLE_SELECTOR = [
+  'input:not([type=hidden]):not([disabled])',
+  'button:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[contenteditable=""]',
+  '[contenteditable="true"]',
+  'a[href]',
+  '[tabindex]:not([disabled])',
+].join(', ')
diff --git a/src/utils/index.ts b/src/utils/index.ts
new file mode 100644
index 00000000..6d5a2294
--- /dev/null
+++ b/src/utils/index.ts
@@ -0,0 +1,22 @@
+export * from './click/getMouseEventOptions'
+export * from './click/isClickableInput'
+
+export * from './edit/buildTimeValue'
+export * from './edit/calculateNewValue'
+export * from './edit/getSelectionRange'
+export * from './edit/getValue'
+export * from './edit/isContentEditable'
+export * from './edit/isValidDateValue'
+export * from './edit/isValidInputTimeValue'
+export * from './edit/setSelectionRangeIfNecessary'
+
+export * from './focus/getActiveElement'
+export * from './focus/isFocusable'
+export * from './focus/selector'
+
+export * from './misc/eventWrapper'
+export * from './misc/isInstanceOfElement'
+export * from './misc/isLabelWithInternallyDisabledControl'
+export * from './misc/isVisible'
+export * from './misc/isDisabled'
+export * from './misc/wait'
diff --git a/src/utils/misc/eventWrapper.ts b/src/utils/misc/eventWrapper.ts
new file mode 100644
index 00000000..12fc3f27
--- /dev/null
+++ b/src/utils/misc/eventWrapper.ts
@@ -0,0 +1,9 @@
+import {getConfig} from '@testing-library/dom'
+
+export function eventWrapper<T>(cb: () => T): T | undefined {
+  let result
+  getConfig().eventWrapper(() => {
+    result = cb()
+  })
+  return result
+}
diff --git a/src/utils/misc/isDisabled.ts b/src/utils/misc/isDisabled.ts
new file mode 100644
index 00000000..466db942
--- /dev/null
+++ b/src/utils/misc/isDisabled.ts
@@ -0,0 +1,5 @@
+// This should probably be extended with checking the element type
+// https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled
+export function isDisabled(element: Element | null): boolean {
+  return Boolean(element && (element as {disabled?: boolean}).disabled)
+}
diff --git a/src/utils/misc/isInstanceOfElement.ts b/src/utils/misc/isInstanceOfElement.ts
new file mode 100644
index 00000000..a2302c24
--- /dev/null
+++ b/src/utils/misc/isInstanceOfElement.ts
@@ -0,0 +1,40 @@
+import {getWindowFromNode} from '@testing-library/dom/dist/helpers'
+
+// isInstanceOfElement can be removed once the peerDependency for @testing-library/dom is bumped to a version that includes https://github.com/testing-library/dom-testing-library/pull/885
+/**
+ * Check if an element is of a given type.
+ *
+ * @param {Element} element The element to test
+ * @param {string} elementType Constructor name. E.g. 'HTMLSelectElement'
+ */
+export function isInstanceOfElement(
+  element: Element,
+  elementType: string,
+  // TODO: make this a type guard
+  // This should be typed as a type guard, but there is no map with constructor names to element constructors.
+  // Window does not have the constructors as properties.
+): boolean {
+  try {
+    // Window usually has the element constructors as properties but is not required to do so per specs
+    const constructor = getWindowFromNode(element)[
+      elementType as keyof Window
+    ] as unknown
+    if (typeof constructor === 'function') {
+      return element instanceof constructor
+    }
+  } catch {
+    // The document might not be associated with a window
+  }
+
+  // Fall back to the constructor name as workaround for test environments that
+  // a) not associate the document with a window
+  // b) not provide the constructor as property of window
+  if (/^HTML(\w+)Element$/.test(element.constructor.name)) {
+    return element.constructor.name === elementType
+  }
+
+  // The user passed some node that is not created in a browser-like environment
+  throw new Error(
+    `Unable to verify if element is instance of ${elementType}. Please file an issue describing your test environment: https://github.com/testing-library/dom-testing-library/issues/new`,
+  )
+}
diff --git a/src/utils/misc/isLabelWithInternallyDisabledControl.ts b/src/utils/misc/isLabelWithInternallyDisabledControl.ts
new file mode 100644
index 00000000..86020a19
--- /dev/null
+++ b/src/utils/misc/isLabelWithInternallyDisabledControl.ts
@@ -0,0 +1,16 @@
+// Absolutely NO events fire on label elements that contain their control
+// if that control is disabled. NUTS!
+
+import {isDisabled} from './isDisabled'
+import {isInstanceOfElement} from './isInstanceOfElement'
+
+// no joke. There are NO events for: <label><input disabled /><label>
+export function isLabelWithInternallyDisabledControl(
+  element: Element,
+): boolean {
+  if (!isInstanceOfElement(element, 'HTMLLabelElement')) {
+    return false
+  }
+  const control = (element as HTMLLabelElement).control
+  return Boolean(control && element.contains(control) && isDisabled(control))
+}
diff --git a/src/utils/misc/isVisible.ts b/src/utils/misc/isVisible.ts
new file mode 100644
index 00000000..989b6171
--- /dev/null
+++ b/src/utils/misc/isVisible.ts
@@ -0,0 +1,18 @@
+import {getWindowFromNode} from '@testing-library/dom/dist/helpers'
+
+export function isVisible(element: Element): boolean {
+  const window = getWindowFromNode(element)
+
+  for (
+    let el: Element | null = element;
+    el?.ownerDocument;
+    el = el.parentElement
+  ) {
+    const display = window.getComputedStyle(el).display
+    if (display === 'none') {
+      return false
+    }
+  }
+
+  return true
+}
diff --git a/src/utils/misc/wait.ts b/src/utils/misc/wait.ts
new file mode 100644
index 00000000..69ad59b5
--- /dev/null
+++ b/src/utils/misc/wait.ts
@@ -0,0 +1,3 @@
+export function wait(time?: number) {
+  return new Promise<void>(resolve => setTimeout(() => resolve(), time))
+}
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 00000000..e02acdcd
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "extends": "./node_modules/kcd-scripts/shared-tsconfig.json",
+  "compilerOptions": {
+    "allowJs": true
+  },
+  "include": ["./src", "./typings"]
+}
diff --git a/typings/dom-helpers.d.ts b/typings/dom-helpers.d.ts
new file mode 100644
index 00000000..a1945225
--- /dev/null
+++ b/typings/dom-helpers.d.ts
@@ -0,0 +1,3 @@
+declare module '@testing-library/dom/dist/helpers' {
+  export function getWindowFromNode(node: Node): Window
+}
diff --git a/typings/index.d.ts b/typings/index.d.ts
index eae80cde..3d4ae385 100644
--- a/typings/index.d.ts
+++ b/typings/index.d.ts
@@ -1,18 +1,19 @@
-// Definitions by: Wu Haotian <https://github.com/whtsky>
-export interface ITypeOpts {
-  skipClick?: boolean
-  skipAutoClose?: boolean
-  delay?: number
-  initialSelectionStart?: number
-  initialSelectionEnd?: number
-}
+import type {click, clickOptions} from '../src/click'
+import type {
+  keyboard,
+  keyboardOptions,
+  specialCharMap,
+  keyboardKey,
+} from '../src/keyboard'
+import type {type, typeOptions} from '../src/type'
 
+// Definitions by: Wu Haotian <https://github.com/whtsky>
 export interface ITabUserOptions {
   shift?: boolean
   focusTrap?: Document | Element
 }
 
-export type TargetElement = Element | Window
+export type TargetElement = Element
 
 export type FilesArgument = File | File[]
 
@@ -21,22 +22,13 @@ export type UploadInitArgument = {
   changeInit?: Event
 }
 
-export interface IClickOptions {
-  skipHover?: boolean
-  clickCount?: number
-}
-
 export interface IUploadOptions {
   applyAccept?: boolean
 }
 
 declare const userEvent: {
   clear: (element: TargetElement) => void
-  click: (
-    element: TargetElement,
-    init?: MouseEventInit,
-    options?: IClickOptions,
-  ) => void
+  click: typeof click
   dblClick: (
     element: TargetElement,
     init?: MouseEventInit,
@@ -44,12 +36,12 @@ declare const userEvent: {
   ) => void
   selectOptions: (
     element: TargetElement,
-    values: string | string[] | HTMLElement | HTMLElement[],
+    values: HTMLElement | HTMLElement[] | string[] | string,
     init?: MouseEventInit,
   ) => void
   deselectOptions: (
     element: TargetElement,
-    values: string | string[] | HTMLElement | HTMLElement[],
+    values: HTMLElement | HTMLElement[] | string[] | string,
     init?: MouseEventInit,
   ) => void
   upload: (
@@ -58,12 +50,8 @@ declare const userEvent: {
     init?: UploadInitArgument,
     options?: IUploadOptions,
   ) => void
-  type: <T extends ITypeOpts>(
-    element: TargetElement,
-    text: string,
-    userOpts?: T,
-    // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
-  ) => T extends {delay: number} ? Promise<void> : void
+  type: typeof type
+  keyboard: typeof keyboard
   tab: (userOpts?: ITabUserOptions) => void
   paste: (
     element: TargetElement,
@@ -80,18 +68,6 @@ declare const userEvent: {
 
 export default userEvent
 
-export enum specialChars {
-  arrowLeft = '{arrowleft}',
-  arrowRight = '{arrowright}',
-  arrowDown = '{arrowdown}',
-  arrowUp = '{arrowup}',
-  enter = '{enter}',
-  escape = '{esc}',
-  delete = '{del}',
-  backspace = '{backspace}',
-  home = '{home}',
-  end = '{end}',
-  selectAll = '{selectall}',
-  space = '{space}',
-  whitespace = ' ',
-}
+export {keyboardOptions, keyboardKey, specialCharMap as specialChars}
+export {typeOptions, typeOptions as ITypeOpts}
+export {clickOptions, clickOptions as IClickOptions}
diff --git a/typings/test.ts b/typings/test.ts
index 4db2aa03..a0449e4d 100644
--- a/typings/test.ts
+++ b/typings/test.ts
@@ -1,12 +1,10 @@
 import userEvent, {TargetElement} from '.'
 
 declare const element: TargetElement
-type NotVoid = string | number | boolean | object | null
 
 userEvent.type(element, 'foo', {delay: 1}).then(
   // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
   function handleSucces(_nothing: void) {},
   function handleError(_error: Error) {},
 )
-// @ts-expect-error No delay returns void
-userEvent.type(element, 'foo') as NotVoid
+userEvent.type(element, 'foo') as undefined