what-input 5.2.12 → 6.0.0

package/README.md

@@ -2,21 +2,66 @@
 
 **A global utility for tracking the current input method (mouse, keyboard or touch).**
 
-## _What Input_ is now v5
+## _What Input_ is now v6
 
-Now with more information and less opinion!
+Rebuilt for the modern web: Pointer Events, `KeyboardEvent.key`, TypeScript, native ES modules, and an `EventTarget` API. The outputs are the same as v5, so it's a drop-in upgrade for existing sites. See the [changelog](#changelog) for the few things that changed.
 
-_What Input_ adds data attributes to the `window` based on the type of input being used. It also exposes a simple API that can be used for scripting interactions.
+_What Input_ adds data attributes to the `<html>` element based on the type of input being used. It also exposes a simple API that can be used for scripting interactions.
 
 ## How it works
 
-_What Input_ uses event bubbling on the `window` to watch for mouse, keyboard and touch events (via `mousedown`, `keydown` and `touchstart`). It then sets or updates a `data-whatinput` attribute.
+_What Input_ listens on the `window` (in the capture phase, so local `stopPropagation()` calls don't hide anything) for:
 
-Pointer Events are supported but note that `pen` inputs are remapped to `touch`.
+- `pointerdown` – a direct interaction. `pointerType` decides whether it's `mouse` or `touch` (`pen` is reported as `touch`).
+- `keydown` / `keyup` – a direct `keyboard` interaction, unless the key is on the ignore list (modifiers by default).
+- `pointermove` / `wheel` – an _indirect_ signal that a mouse is present.
+- `focusin` / `focusout` – which element currently has focus.
 
-_What Input_ also exposes a tiny API that allows the developer to ask for the current input, set custom ignore keys, and set and remove custom callback functions.
+It then sets or updates these attributes on `<html>`:
 
-_What Input does not make assumptions about the input environment before the page is interacted with._ However, the `mousemove` and `pointermove` events are used to set a `data-whatintent="mouse"` attribute to indicate that a mouse is being used _indirectly_.
+| Attribute          | Values                                      | Updated by                                             |
+| ------------------ | ------------------------------------------- | ------------------------------------------------------ |
+| `data-whatinput`   | `initial`, `mouse`, `keyboard`, `touch`     | `pointerdown`, `keydown`, `keyup`                      |
+| `data-whatintent`  | `initial`, `mouse`, `keyboard`, `touch`     | everything above plus `pointermove` and `wheel`        |
+| `data-whatelement` | the focused element's tag name, e.g. `a`    | `focusin` / `focusout`                                 |
+| `data-whatclasses` | the focused element's classes, e.g. `a,b,c` | `focusin` / `focusout` (only when the element has any) |
+
+_What Input does not make assumptions about the input environment before the page is interacted with._ However, the `pointermove` and `wheel` events are used to set `data-whatintent="mouse"` to indicate that a mouse is being used _indirectly_.
+
+### Interacting with forms
+
+Since interacting with a form _always_ requires use of the keyboard, _What Input_ uses the `data-whatintent` attribute to display a "buffered" version of input events while `<input>`s, `<select>`s, `<textarea>`s, `contenteditable` elements, [form-associated custom elements](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals) and `<button>`s inside a `<form>` are being interacted with (i.e. a mouse user's `data-whatintent` will be preserved as `mouse` while typing). `data-whatinput` always reflects the actual last input.
+
+Checkboxes and radio buttons are toggled rather than typed into, so pressing a key on one _does_ switch the intent to `keyboard`.
+
+The same buffering can be opted into for any other element by adding a `data-whatfreeze` attribute to it or to a container. This is handy for custom controls that are operated with the arrow keys, like a slider or a video scrubber, where pressing a key is not a change of intent:
+
+```html
+<div class="scrubber" data-whatfreeze>
+  <div class="scrubber-handle" role="slider" tabindex="0" ...></div>
+</div>
+```
+
+### Device hint
+
+Before anyone interacts with the page, `data-whatinput` and `data-whatintent` are `initial` on purpose. When a best guess is still useful (sizing hit targets on first paint, say), the `data-whathint` attribute carries what the device's _primary_ pointer suggests, read from the [`pointer` interaction media feature](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/pointer):
+
+| `data-whathint` | Media query         | Typically                    |
+| --------------- | ------------------- | ---------------------------- |
+| `touch`         | `(pointer: coarse)` | phones, tablets              |
+| `mouse`         | `(pointer: fine)`   | desktops, laptops, trackpads |
+| `unknown`       | neither             | keyboard-only devices, TVs   |
+
+The hint follows the device live (a mouse paired with a tablet, a keyboard detached from one) and is never persisted. It is only a hint: an iPad with a trackpad still reports `touch`, and a touch-screen laptop reports `mouse`. `data-whatinput` and `data-whatintent` never use it.
+
+### Isn't this what `:focus-visible` is for?
+
+Partly. [`:focus-visible`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible) is a great default for focus rings and you should use it. _What Input_ is still useful when you want to:
+
+- style anything other than focus (hover affordances, hit targets, tooltips) based on how the page is being used;
+- know the input method from JavaScript;
+- tell `mouse` and `touch` apart;
+- remember the input method across page loads so the first render is already right.
 
 ## Demo
 
@@ -24,35 +69,31 @@ Check out the demo to see _What Input_ in action.
 
 https://ten1seven.github.io/what-input
 
-### Interacting with Forms
-
-Since interacting with a form _always_ requires use of the keyboard, _What Input_ uses the `data-whatintent` attribute to display a "buffered" version of input events while form `<input>`s, `<select>`s, and `<textarea>`s are being interacted with (i.e. mouse user's `data-whatintent` will be preserved as `mouse` while typing).
-
 ## Installing
 
-Download the file directly.
-
-Install via Yarn:
+Install via npm (or your package manager of choice):
 
 ```shell
-yarn add what-input
+npm install what-input
 ```
 
-Install via NPM:
+Or load it from a CDN:
 
-```shell
-npm install what-input
+```html
+<script src="https://unpkg.com/what-input@6"></script>
 ```
 
+Or download `dist/what-input.js` and include it directly.
+
 ## Usage
 
-Include the script directly in your project.
+Include the script directly in your project. It exposes a global `whatInput`.
 
 ```html
 <script src="path/to/what-input.js"></script>
 ```
 
-Or require with a script loader.
+Or import it. The package ships as an ES module (`dist/what-input.mjs`), as a UMD build (`dist/what-input.js`, which also covers CommonJS and AMD) and with TypeScript declarations.
 
 ```javascript
 import 'what-input'
@@ -63,28 +104,16 @@ import whatInput from 'what-input'
 
 // or
 
-require('what-input')
-
-// or
-
-var whatInput = require('what-input')
-
-// or
-
-requirejs.config({
-  paths: {
-    whatInput: 'path/to/what-input',
-  },
-})
-
-require(['whatInput'], function () {})
+const whatInput = require('what-input')
 ```
 
 _What Input_ will start doing its thing while you do yours.
 
-### Default Behavior
+> **Bundlers:** importing the module has the side effect of starting _What Input_. The package declares `"sideEffects": true` so a bare `import 'what-input'` is never tree-shaken away.
+
+### Default behavior
 
-#### Persisting Input/Intent Across Pages
+#### Persisting input/intent across pages
 
 By default, _What Input_ uses [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) to persist the input and intent values across pages. The benefit is that once a visitor has interacted with the page, subsequent pages won't have to wait for interactions to know the input method.
 
@@ -110,7 +139,7 @@ Session storage can be cleared at any time with:
 whatInput.clearStorage()
 ```
 
-### Basic Styling
+### Basic styling
 
 ```css
 /*
@@ -123,13 +152,27 @@ whatInput.clearStorage()
 }
 ```
 
-**Note:** If you remove outlines with `outline: none;`, be sure to provide clear visual `:focus` styles so the user can see which element they are on at any time for greater accessibility. Visit [W3C's WCAG 2.0 2.4.7 Guideline](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-focus-visible.html) to learn more.
+A more modern take pairs _What Input_ with `:focus-visible` and only reaches for the data attributes where the browser heuristic isn't enough:
+
+```css
+:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 2px;
+}
+
+/* bigger hit areas while a touch screen is being used */
+[data-whatintent='touch'] .toolbar button {
+  min-block-size: 44px;
+}
+```
+
+**Note:** If you remove outlines with `outline: none;`, be sure to provide clear visual `:focus` styles so the user can see which element they are on at any time for greater accessibility. Visit [W3C's WCAG 2.2 2.4.7 Guideline](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) to learn more.
 
 ### Scripting
 
-#### Current Input
+#### Current input
 
-Ask _What Input_ what the current input method is. This works best if asked after the events _What Input_ is bound to (`mousedown`, `keydown` and `touchstart`).
+Ask _What Input_ what the current input method is. This works best if asked after the events _What Input_ is bound to (`pointerdown` and `keydown`).
 
 ```javascript
 whatInput.ask() // returns `mouse`, `keyboard` or `touch`
@@ -143,7 +186,7 @@ myButton.addEventListener('click', () => {
 })
 ```
 
-If it's necessary to know if `mousemove` is being used, use the `'intent'` option. For example:
+If it's necessary to know if `pointermove` is being used, use the `'intent'` option. For example:
 
 ```javascript
 /*
@@ -161,47 +204,61 @@ whatInput.ask() // returns `keyboard` because the keyboard was the last direct p
 whatInput.ask('intent') // returns `mouse` because mouse movement was the most recent action detected
 ```
 
-### Current Element
+Since `click` events are `PointerEvent`s in current browsers, a single click handler can also read `event.pointerType` directly: it's `mouse`, `pen` or `touch`, and empty when the click came from the keyboard.
+
+#### Device hint
+
+```javascript
+whatInput.ask('hint') // returns `mouse`, `touch` or `unknown`
+```
+
+#### Current element
 
 Ask _What Input_ the currently focused DOM element.
 
 ```javascript
-whatInput.element() // returns a string, like `input` or null
+whatInput.element() // returns a string, like `input`, or null
 ```
 
-#### Ignore Keys
+#### Ignore keys
 
-Set a custom array of [keycodes](http://keycode.info/) that will be ignored (will not switch over to `keyboard`) when pressed. _A custom list will overwrite the default values._
+Set a custom list of keys that will be ignored (will not switch over to `keyboard`) when pressed. Keys can be [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) values, [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values) values or legacy [keycodes](https://www.toptal.com/developers/keycode). _A custom list will overwrite the default values._
 
 ```javascript
 /*
  * default ignored keys:
- * 16, // shift
- * 17, // control
- * 18, // alt
- * 91, // Windows key / left Apple cmd
- * 93  // Windows menu / right Apple cmd
+ * 'Shift'
+ * 'Control'
+ * 'Alt'
+ * 'Meta'        // Windows key / Apple cmd
+ * 'ContextMenu' // Windows menu key
  */
 
-whatInput.ignoreKeys([1, 2, 3])
+whatInput.ignoreKeys(['Shift', 'CapsLock', 'F11'])
+
+// legacy keycodes still work
+whatInput.ignoreKeys([16, 20, 122])
 ```
 
-#### Specific Keys
+#### Specific keys
 
-Set a custom array of [keycodes](http://keycode.info/) that will trigger the keyboard pressed intent (will not switch to `keyboard` unless these keys are pressed). _This overrides ignoreKeys._
+Set a custom list of keys that will trigger the keyboard pressed intent (will not switch to `keyboard` unless these keys are pressed). _This overrides ignoreKeys._
 
 ```javascript
 // only listen to tab keyboard press
-whatInput.specificKeys([9])
+whatInput.specificKeys(['Tab'])
+
+// go back to using the ignore list
+whatInput.specificKeys([])
 ```
 
-#### Custom Callbacks
+#### Custom callbacks
 
 Fire a function when the input or intent changes.
 
 ```javascript
 // create a function to be fired
-var myFunction = function (type) {
+const myFunction = (type) => {
   console.log(type)
 }
 
@@ -211,16 +268,148 @@ whatInput.registerOnChange(myFunction, 'intent')
 // fire `myFunction` when the input changes
 whatInput.registerOnChange(myFunction, 'input')
 
+// fire `myFunction` when the device hint changes
+whatInput.registerOnChange(myFunction, 'hint')
+
 // remove custom event
 whatInput.unRegisterOnChange(myFunction)
 ```
 
+#### Events
+
+`whatInput` is an [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget). It dispatches `input`, `intent` and `hint` [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)s whose `detail` is the new value, so all the usual listener options (`once`, `signal`, ...) are available.
+
+```javascript
+whatInput.addEventListener('intent', (event) => {
+  console.log(event.detail) // `mouse`, `keyboard` or `touch`
+})
+
+// listen until a component unmounts
+const controller = new AbortController()
+
+whatInput.addEventListener('input', update, { signal: controller.signal })
+
+controller.abort()
+```
+
+In browsers that ship the [Observable API](https://developer.mozilla.org/en-US/docs/Web/API/Observable), `whatInput.when('intent')` works too, for free.
+
+#### Tearing down
+
+Stop listening, remove the `data-what*` attributes and drop every callback. Mostly useful in tests and when an app is unmounted.
+
+```javascript
+whatInput.destroy()
+```
+
+### TypeScript
+
+Types ship with the package.
+
+```typescript
+import whatInput, { type InputMethod, type Strategy } from 'what-input'
+
+const current: InputMethod = whatInput.ask('intent')
+```
+
+### Server-side rendering
+
+_What Input_ can be imported in Node, workers and other environments without a DOM. It won't observe anything, `ask()` always answers `initial` and `element()` always answers `null`.
+
+### Shadow DOM
+
+_What Input_ reports focus inside open shadow roots and knows when a keypress lands in a field inside one. The attributes still live on `<html>`, and selectors in the main document don't reach into a shadow tree, so style from inside the component instead. `:host-context()` works in Chromium and Safari; for every browser, mirror the state onto the host with the events:
+
+```javascript
+class MyField extends HTMLElement {
+  connectedCallback() {
+    this.controller = new AbortController()
+
+    whatInput.addEventListener(
+      'intent',
+      (event) => this.setAttribute('data-whatintent', event.detail),
+      { signal: this.controller.signal },
+    )
+  }
+
+  disconnectedCallback() {
+    this.controller.abort()
+  }
+}
+```
+
+```css
+/* inside the shadow root */
+:host([data-whatintent='mouse']) :focus {
+  outline: none;
+}
+```
+
+### Testing
+
+The state only changes in response to real events, which is also the easiest way to drive it in tests. In a DOM test environment that implements `PointerEvent` (jsdom 22+, happy-dom, every browser):
+
+```javascript
+window.dispatchEvent(new PointerEvent('pointerdown', { pointerType: 'touch' }))
+whatInput.ask() // `touch`
+
+window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab' }))
+whatInput.ask() // `keyboard`
+```
+
+Or mock the module entirely:
+
+```javascript
+vi.mock('what-input', () => ({ default: { ask: () => 'touch' } }))
+```
+
 ## Compatibility
 
-_What Input_ works in all modern browsers.
+_What Input_ v6 works in all evergreen browsers: Chrome and Edge 90+, Firefox 90+ and Safari 15+ (2021 and newer). It relies on Pointer Events, `AbortSignal` support in `addEventListener()`, `EventTarget` subclassing and class private fields, none of which are polyfilled.
+
+If you need to support older browsers, stay on [v5](https://github.com/ten1seven/what-input/tree/v5.2.12).
+
+## Contributing
+
+```shell
+npm install   # install dependencies
+npm run dev   # run the demo with hot reloading
+npm test      # build the library and run the tests
+npm run lint  # prettier and type checks
+npm run build # build the library and the demo site
+```
 
 ## Changelog
 
+### v6.0.0
+
+A rewrite in TypeScript on modern browser APIs. The data attributes, the session storage keys, the API and the `dist/what-input.js` file path are unchanged, so for most sites this is a drop-in upgrade.
+
+- **Breaking:** Drops support for Internet Explorer and other legacy browsers. The build targets ES2022 and is no longer transpiled.
+- **Breaking:** Detection is built on Pointer Events only. The `mousedown`, `mousemove`, `touchstart`, `touchend`, `MSPointerDown`, `MSPointerMove`, `mousewheel` and `DOMMouseScroll` listeners (and the 200ms touch-versus-mouse buffer they required) are gone.
+- **Breaking:** `clearStorage()` now removes only _What Input_'s own `what-input` and `what-intent` keys instead of wiping the entire session storage.
+- **Breaking:** `pointerdown` now updates the intent as well as the input, even while a form field has focus. Only keyboard use inside form fields is buffered.
+- **Breaking:** `unRegisterOnChange(fn)` removes `fn` from both the `input` and `intent` lists.
+- **Breaking:** The `InputMethod` type no longer includes `pointer`, which was never actually reported.
+- **Breaking:** Requires Node 20+ for development. The build uses esbuild, the demo uses Vite and the tests use Vitest; Gulp, Webpack, Babel, Sass and Yarn are gone.
+- **Added:** A `data-whathint` attribute, `ask('hint')` and a `hint` event report what the device's primary pointer suggests (`mouse`, `touch` or `unknown`) from the `pointer` interaction media feature, before any interaction and live as devices are attached or removed. The existing attributes never use it.
+- **Added:** A `data-whatfreeze` attribute opts any element (or container) into the same intent buffering that form fields get, for custom controls driven by the arrow keys ([#123](https://github.com/ten1seven/what-input/issues/123)).
+- **Added:** An ES module build (`dist/what-input.mjs`) with a proper `exports` map, `module` and `unpkg` fields. The UMD build (`dist/what-input.js`) and the minified build remain for `<script>` tags, CommonJS and AMD.
+- **Added:** `whatInput` is an `EventTarget` and dispatches `input` and `intent` events.
+- **Added:** `whatInput.destroy()` tears everything down (listeners are bound with an `AbortController`).
+- **Added:** `ignoreKeys()` and `specificKeys()` accept `KeyboardEvent.key` and `KeyboardEvent.code` strings alongside legacy keycodes. The defaults are now key names.
+- **Added:** Typing inside `contenteditable` elements and form-associated custom elements no longer changes the intent, just like form fields.
+- **Fixed:** Pressing a key on a checkbox or radio button switches the intent to `keyboard`; they are toggled, not typed into ([#128](https://github.com/ten1seven/what-input/issues/128)).
+- **Fixed:** Long-presses in Firefox for Android no longer flash `data-whatintent="mouse"`, because the emulated mouse events are no longer listened to ([#94](https://github.com/ten1seven/what-input/issues/94)).
+- **Added:** Focus inside open shadow roots is reported for the inner element (via `composedPath()`), and the active-element check follows shadow roots when deciding whether a keypress is text entry.
+- **Added:** Persisted session storage values are validated before they are used.
+- **Changed:** Type declarations are generated from the source and shipped in `dist/`.
+- **Changed:** `pointerdown` and `keydown` are observed in the capture phase on `window`, so `whatInput.ask()` is already up to date inside any element's own event handler, even one that calls `preventDefault()` or `stopPropagation()` ([#80](https://github.com/ten1seven/what-input/issues/80)).
+- **Changed:** When the script runs after `DOMContentLoaded` (dynamic `import()`, late-loaded scripts) the initial state is published immediately instead of never.
+- **Changed:** An interaction that happens before `DOMContentLoaded` is no longer overwritten by the persisted value.
+- **Fixed:** `data-whatclasses` separates _all_ classes with commas (`a,b,c`); previously only the first space was replaced.
+- **Fixed:** `data-whatclasses` is removed when focus moves to an element without classes.
+
 ### v5.2.12
 
 - **Fixed:** Improved detection and respect for of `data-whatpersist` before `DOMContentLoaded`. Fix via [FanFataL](https://github.com/FanFataL).
@@ -310,7 +499,7 @@ _What Input_ works in all modern browsers.
 
 ## Acknowledgments
 
-Special thanks to [Viget](http://viget.com/) for their encouragement and commitment to open source projects. Visit [code.viget.com](http://code.viget.com/) to see more projects from [Viget](http://viget.com).
+Special thanks to [Viget](https://viget.com/) for their encouragement and commitment to open source projects. Visit [code.viget.com](https://code.viget.com/) to see more projects from [Viget](https://viget.com).
 
 Thanks to [mAAdhaTTah](https://github.com/mAAdhaTTah) for the initial conversion to Webpack. Thanks to [greypants](https://github.com/greypants) for adding TypeScript definitions.
 

package/dist/what-input.d.mts

@@ -0,0 +1,88 @@
+/**
+ * What Input?
+ *
+ * A global utility for tracking the current input method (mouse, keyboard or
+ * touch). It writes `data-whatinput`, `data-whatintent`, `data-whatelement`
+ * and `data-whatclasses` attributes to the `<html>` element and exposes a
+ * small API for scripting against the same information.
+ */
+/** The input methods What Input can report. */
+export type InputMethod = 'initial' | 'mouse' | 'keyboard' | 'touch';
+/**
+ * `input` is the last *direct* interaction (`pointerdown`, `keydown`).
+ * `intent` also includes *indirect* signals (`pointermove`, `wheel`) and is
+ * preserved while typing into form fields.
+ */
+export type Strategy = 'input' | 'intent';
+/**
+ * What the device's *primary* pointer suggests before (or regardless of) any
+ * interaction, read from the `pointer` interaction media feature. It is a
+ * hint only: `data-whatinput` and `data-whatintent` never use it.
+ */
+export type Hint = 'mouse' | 'touch' | 'unknown';
+/** A callback registered with `registerOnChange()`. */
+export type ChangeCallback = (type: InputMethod) => void;
+/** A callback registered with `registerOnChange(callback, 'hint')`. */
+export type HintCallback = (hint: Hint) => void;
+type Callback = ChangeCallback | HintCallback;
+/**
+ * A key to ignore or require. Strings are matched against `KeyboardEvent.key`
+ * and `KeyboardEvent.code` (`'Shift'`, `'Tab'`, `'KeyA'`); numbers are matched
+ * against the legacy `KeyboardEvent.keyCode` for backwards compatibility.
+ */
+export type KeyMatcher = string | number;
+/** The events dispatched by the `whatInput` EventTarget. */
+export interface WhatInputEventMap {
+    input: CustomEvent<InputMethod>;
+    intent: CustomEvent<InputMethod>;
+    hint: CustomEvent<Hint>;
+}
+declare class WhatInput extends EventTarget {
+    #private;
+    constructor();
+    /**
+     * The current input method.
+     *
+     * - `'input'` (default): the same value as the `data-whatinput` attribute
+     * - `'intent'`: the same value as the `data-whatintent` attribute
+     * - `'hint'`: the same value as the `data-whathint` attribute
+     */
+    ask(strategy?: Strategy): InputMethod;
+    ask(strategy: 'hint'): Hint;
+    /** The tag name of the currently focused element, or `null`. */
+    element(): string | null;
+    /**
+     * Replaces the list of keys that are ignored (do not switch to `keyboard`)
+     * when pressed. Defaults to the modifier keys.
+     */
+    ignoreKeys(keys: readonly KeyMatcher[]): void;
+    /**
+     * Replaces the list of keys that are the *only* keys that switch to
+     * `keyboard`. When set, this overrides `ignoreKeys()`. Pass an empty array
+     * to restore the `ignoreKeys()` behavior.
+     */
+    specificKeys(keys: readonly KeyMatcher[]): void;
+    /** Fires `callback` whenever the input (default), intent or hint changes. */
+    registerOnChange(callback: ChangeCallback, strategy?: Strategy): void;
+    registerOnChange(callback: HintCallback, strategy: 'hint'): void;
+    /** Removes a callback added with `registerOnChange()`. */
+    unRegisterOnChange(callback: Callback): void;
+    /** Removes the persisted input and intent from session storage. */
+    clearStorage(): void;
+    /**
+     * Stops listening, removes the `data-what*` attributes from `<html>` and
+     * drops every registered callback. Useful for tests and app teardown.
+     */
+    destroy(): void;
+}
+/** Typed listeners for the `input`, `intent` and `hint` events (types only). */
+interface WhatInput {
+    addEventListener<K extends keyof WhatInputEventMap>(type: K, listener: ((this: WhatInput, event: WhatInputEventMap[K]) => void) | null, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof WhatInputEventMap>(type: K, listener: ((this: WhatInput, event: WhatInputEventMap[K]) => void) | null, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
+}
+export type { WhatInput };
+/** The shared What Input instance. It starts observing as soon as it is imported. */
+declare const whatInput: WhatInput;
+export default whatInput;

package/dist/what-input.d.ts

@@ -0,0 +1,88 @@
+/**
+ * What Input?
+ *
+ * A global utility for tracking the current input method (mouse, keyboard or
+ * touch). It writes `data-whatinput`, `data-whatintent`, `data-whatelement`
+ * and `data-whatclasses` attributes to the `<html>` element and exposes a
+ * small API for scripting against the same information.
+ */
+/** The input methods What Input can report. */
+export type InputMethod = 'initial' | 'mouse' | 'keyboard' | 'touch';
+/**
+ * `input` is the last *direct* interaction (`pointerdown`, `keydown`).
+ * `intent` also includes *indirect* signals (`pointermove`, `wheel`) and is
+ * preserved while typing into form fields.
+ */
+export type Strategy = 'input' | 'intent';
+/**
+ * What the device's *primary* pointer suggests before (or regardless of) any
+ * interaction, read from the `pointer` interaction media feature. It is a
+ * hint only: `data-whatinput` and `data-whatintent` never use it.
+ */
+export type Hint = 'mouse' | 'touch' | 'unknown';
+/** A callback registered with `registerOnChange()`. */
+export type ChangeCallback = (type: InputMethod) => void;
+/** A callback registered with `registerOnChange(callback, 'hint')`. */
+export type HintCallback = (hint: Hint) => void;
+type Callback = ChangeCallback | HintCallback;
+/**
+ * A key to ignore or require. Strings are matched against `KeyboardEvent.key`
+ * and `KeyboardEvent.code` (`'Shift'`, `'Tab'`, `'KeyA'`); numbers are matched
+ * against the legacy `KeyboardEvent.keyCode` for backwards compatibility.
+ */
+export type KeyMatcher = string | number;
+/** The events dispatched by the `whatInput` EventTarget. */
+export interface WhatInputEventMap {
+    input: CustomEvent<InputMethod>;
+    intent: CustomEvent<InputMethod>;
+    hint: CustomEvent<Hint>;
+}
+declare class WhatInput extends EventTarget {
+    #private;
+    constructor();
+    /**
+     * The current input method.
+     *
+     * - `'input'` (default): the same value as the `data-whatinput` attribute
+     * - `'intent'`: the same value as the `data-whatintent` attribute
+     * - `'hint'`: the same value as the `data-whathint` attribute
+     */
+    ask(strategy?: Strategy): InputMethod;
+    ask(strategy: 'hint'): Hint;
+    /** The tag name of the currently focused element, or `null`. */
+    element(): string | null;
+    /**
+     * Replaces the list of keys that are ignored (do not switch to `keyboard`)
+     * when pressed. Defaults to the modifier keys.
+     */
+    ignoreKeys(keys: readonly KeyMatcher[]): void;
+    /**
+     * Replaces the list of keys that are the *only* keys that switch to
+     * `keyboard`. When set, this overrides `ignoreKeys()`. Pass an empty array
+     * to restore the `ignoreKeys()` behavior.
+     */
+    specificKeys(keys: readonly KeyMatcher[]): void;
+    /** Fires `callback` whenever the input (default), intent or hint changes. */
+    registerOnChange(callback: ChangeCallback, strategy?: Strategy): void;
+    registerOnChange(callback: HintCallback, strategy: 'hint'): void;
+    /** Removes a callback added with `registerOnChange()`. */
+    unRegisterOnChange(callback: Callback): void;
+    /** Removes the persisted input and intent from session storage. */
+    clearStorage(): void;
+    /**
+     * Stops listening, removes the `data-what*` attributes from `<html>` and
+     * drops every registered callback. Useful for tests and app teardown.
+     */
+    destroy(): void;
+}
+/** Typed listeners for the `input`, `intent` and `hint` events (types only). */
+interface WhatInput {
+    addEventListener<K extends keyof WhatInputEventMap>(type: K, listener: ((this: WhatInput, event: WhatInputEventMap[K]) => void) | null, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof WhatInputEventMap>(type: K, listener: ((this: WhatInput, event: WhatInputEventMap[K]) => void) | null, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
+}
+export type { WhatInput };
+/** The shared What Input instance. It starts observing as soon as it is imported. */
+declare const whatInput: WhatInput;
+export default whatInput;