pixijs-input-devices 0.3.0 → 0.5.0

package/README.md

@@ -1,47 +1,98 @@
-# 🕹️ pixijs-input-devices  [![NPM version](https://img.shields.io/npm/v/pixijs-input-devices.svg)](https://www.npmjs.com/package/pixijs-input-devices) [![Minzipped](https://badgen.net/bundlephobia/minzip/pixijs-input-devices@latest)](https://bundlephobia.com/package/pixijs-input-devices) [![Downloads per month](https://img.shields.io/npm/dm/pixijs-input-devices.svg)](https://www.npmjs.com/package/pixijs-input-devices) [![Tests](https://github.com/reececomo/pixijs-input-devices/actions/workflows/tests.yml/badge.svg)](https://github.com/reececomo/pixijs-input-devices/actions/workflows/tests.yml) [![License](https://badgen.net/npm/license/pixijs-input-devices)](https://github.com/reececomo/pixijs-input-devices/blob/main/LICENSE)
+# 🕹️ pixijs-input-devices  [![License](https://badgen.net/npm/license/pixijs-input-devices)](https://github.com/reececomo/pixijs-input-devices/blob/main/LICENSE) [![Tests](https://github.com/reececomo/pixijs-input-devices/actions/workflows/tests.yml/badge.svg)](https://github.com/reececomo/pixijs-input-devices/actions/workflows/tests.yml) [![Downloads per month](https://img.shields.io/npm/dm/pixijs-input-devices.svg)](https://www.npmjs.com/package/pixijs-input-devices) [![NPM version](https://img.shields.io/npm/v/pixijs-input-devices.svg)](https://www.npmjs.com/package/pixijs-input-devices)
 
-🚧 WIP - This API is a work in progress, and is subject to change.
+⚡ Powerful, high-performance input device management for PixiJS
 
-- Adds comprehensive support for ⌨️ **Keyboard**, 🎮 **Gamepads**, and other human-interface devices
-- High-performance, easy-to-use, sensible defaults
-- Supports either real-time or event driven APIs
-- Built-in `Navigation` API to navigate pointer/mouse based menus _(optional)_
+| | |
+| ------ | ------ |
+| 🎮 Handles [keyboards](#keyboarddevice), [gamepads](#gamepaddevice), and [more](#custom-devices)! | 🚀 Flexible [update](#real-time) and [event-driven](#keyboarddevice-events) APIs |
+| ⚡ Optimized for [INP performance](https://web.dev/articles/inp) | 🪄 Built-in [named binds](#named-binds) |
+| 🔮 Highly configurable | 🌐 Built-in [international keyboard](#keyboard-layout---detection) support |
+| ✅ Cross-platform &amp; mobile-friendly <sup>[[1]](https://caniuse.com/mdn-api_keyboardlayoutmap) [[2]](https://caniuse.com/mdn-api_gamepad_vibrationactuator) [[3]](https://chromestatus.com/feature/5989275208253440)</sup>  | 🧭 Built-in [UI navigation](#navigation-api) _(optional)_ |
+| 🍃 Zero dependencies & tree-shakeable | ✨ Supports PixiJS v8, v7, v6.3+ |
 
-<hr/>
 
-## 💿 Install
+## Sample Usage
+
+*Handle device inputs with ease.*
+
+```ts
+import { InputDevice } from "pixijs-input-devices";
+
+// Iterative
+let jump = false
+
+for (const device of InputDevice.devices) {
+  if (device.type === "keyboard" && device.key.Space) jump = true
+  if (device.type === "gamepad" && device.button.A) jump = true
+}
+
+// Event-driven
+const gamepad = InputDevice.gamepads[0]
+
+gamepad?.on("LeftShoulder", (e) => {
+    e.device.playVibration({ duration: 100 })
+});
+```
+
+## Getting Started with PixiJS Input Devices
+
+*Everything you need to quickly integrate powerful device management.*
+
+**PixiJS Input Devices** adds first-class support for input device management and input handling. It also provides an optional navigation manager
+that can enable input devices to traverse pointer-based UIs.
+
+The core concepts are:
+
+1. **Devices:** _Any human interface device_
+2. **Binds:** _Custom, named input actions that can be triggered by assigned keys or buttons_
+3. **UINavigation:** _A global controller that allows non-pointer devices to navigate UIs_
+
+> [!NOTE]
+> _See [UINavigation API](#uinavigation-api) for more information._
+
+
+## Installation
+
+*Quick start guide.*
+
+**1.** Install the latest `pixijs-input-devices` package:
 
 ```sh
-npm i pixijs-input-devices
+# npm
+npm install pixijs-input-devices -D
+
+# yarn
+yarn add pixijs-input-devices --dev
 ```
 
-### Setup
+**2.** Register the update loop:
 
 ```ts
-import { InputDevice } from "pixijs-input-devices"
+import { Ticker } from 'pixi.js';
+import { InputDevice } from 'pixijs-input-devices';
 
-Ticker.shared.add( () => InputDevice.update() )
+Ticker.shared.add(ticker => InputDevice.update());
 ```
 
-_(Optional)_ Enable the Navigation API:
+> [!TIP]
+> **Input polling:** In the context of a video game, you may want to put the input update at the start of your game event loop instead.
+
+**3.** (Optional) enable the UINavigation API
 
 ```ts
-import { Navigation } from "pixijs-input-devices"
+import * as PIXI from 'pixi.js';
+import { UINavigation, registerPixiJSNavigationMixin } from 'pixijs-input-devices';
 
-// set root node
-Navigation.stage = app.stage
+const app = new PIXI.Application(/*…*/)
 
-// register mixin
-registerPixiJSInputDeviceMixin( Container )
+// enable the navigation API
+UINavigation.configureWithRoot( app.stage )
+registerPixiJSNavigationMixin( PIXI.Container )
 ```
 
-## Overview
-
-There are a few very simple themes:
+✨ You are now ready to use inputs!
 
-- All devices are accessed through the `InputDevice` manager
-- There are three supported device types: ⌨️ `"keyboard"`, 🎮 `"gamepad"` and 👻 `"custom"`
-- Inputs can be accessed directly, or configured by [Named Groups](#named-input-groups)
+## Features
 
 ### InputDevice Manager
 
@@ -56,7 +107,7 @@ InputDevice.custom    // Array<CustomDevice>
 You can access all **active/connected** devices using `.devices`:
 
 ```ts
-for ( const device of InputDevice.devices ) {  // ...
+for ( const device of InputDevice.devices ) {  // …
 ```
 
 #### InputDevice - properties
@@ -76,18 +127,18 @@ for ( const device of InputDevice.devices ) {  // ...
 Access global events directly through the manager:
 
 ```ts
-InputDevice.on( "deviceconnected", ({ device }) => {
+InputDevice.on( "deviceadded", ({ device }) => {
     // a device was connected
     // do additional setup here, show a dialog, etc.
 })
 
-InputDevice.off( "deviceconnected" ) // stop listening
+InputDevice.off( "deviceadded" ) // stop listening
 ```
 
 | Event | Description | Payload |
 |---|---|---|
-| `"deviceconnected"` | `{device}` | A device has become available. |
-| `"devicedisconnected"` | `{device}` | A device has been removed. |
+| `"deviceadded"` | `{device}` | A device has been added. |
+| `"deviceremoved"` | `{device}` | A device has been removed. |
 
 
 ### KeyboardDevice
@@ -97,7 +148,7 @@ Unlike gamepads & custom devices, there is a single global keyboard device.
 ```ts
 let keyboard = InputDevice.keyboard
 
-if ( keyboard.key.ControlLeft ) {  // ...
+if ( keyboard.key.ControlLeft ) {  // …
 ```
 
 > [!NOTE]
@@ -141,12 +192,12 @@ InputDevice.keyboard.layoutSource  // "manual"
 | Event | Description | Payload |
 |---|---|---|
 | `"layoutdetected"` | `{layout,layoutSource,device}` | The keyboard layout (`"QWERTY"`, `"QWERTZ"`, `"AZERTY"`, or `"JCUKEN"`) has been detected, either from the native API or from keypresses. |
-| `"group"` | `{groupName,event,keyCode,keyLabel,device}` | A **named input group** key was pressed. |
+| `"bind"` | `{name,event,keyCode,keyLabel,device}` | A **named bind** key was pressed. |
 | **Key presses:** | | |
 | `"KeyA"` | `{event,keyCode,keyLabel,device}` | The `"KeyA"` was pressed. |
 | `"KeyB"` | `{event,keyCode,keyLabel,device}` | The `"KeyB"` was pressed. |
 | `"KeyC"` | `{event,keyCode,keyLabel,device}` | The `"KeyC"` was pressed. |
-| ... | ... | ... |
+| … | … | … |
 
 
 ### GamepadDevice
@@ -158,9 +209,9 @@ Gamepad accessors are modelled around the "Standard Controller Layout":
 ```ts
 let gamepad = InputDevice.gamepads[0]
 
-if ( gamepad.button.Start ) {  // ...
-if ( gamepad.leftTrigger > 0.25 ) {  // ...
-if ( gamepad.leftJoystick.x > 0.5 ) {  // ...
+if ( gamepad.button.Start ) {  // …
+if ( gamepad.leftTrigger > 0.25 ) {  // …
+if ( gamepad.leftJoystick.x > 0.5 ) {  // …
 ```
 
 > [!TIP]
@@ -172,12 +223,11 @@ if ( gamepad.leftJoystick.x > 0.5 ) {  // ...
 Use the `playVibration()` method to play a haptic vibration, in supported browsers.
 
 ```ts
-gamepad.playVibration()
-
 gamepad.playVibration({
-  duration: 150,
-  weakMagnitude: 0.25,
-  strongMagnitude: 0.65,
+    duration: 150,
+    weakMagnitude: 0.75,
+    strongMagnitude: 0.25,
+    // …
 })
 ```
 
@@ -185,31 +235,40 @@ gamepad.playVibration({
 
 The gamepad buttons reference **Standard Controller Layout**:
 
-| Button # | ButtonCode | Standard | Nintendo* | Playstation | Xbox |
+| Button | BindableCode | Standard | Nintendo <sup>[[1]](#gamepad---nintendo-layout-remapping)</sup> | Playstation | Xbox |
 |:---:|:---:|:---:|:---:|:---:|:---:|
-| `0` | `"A"` | **A** | A | Cross | A |
-| `1` | `"B"` | **B** | X | Circle | B |
-| `2` | `"X"` | **X** | B | Square | X |
-| `3` | `"Y"` | **Y** | Y | Triangle | Y |
+| `0` | `"A"` | **A / FaceButton1** | A | Cross | A |
+| `1` | `"B"` | **B / FaceButton2** | X | Circle | B |
+| `2` | `"X"` | **X / FaceButton3** | B | Square | X |
+| `3` | `"Y"` | **Y / FaceButton4** | Y | Triangle | Y |
 | `4` | `"LeftShoulder"` | **Left Shoulder** | L | L1 | LB |
 | `5` | `"RightShoulder"` | **Right Shoulder** | R | R1 | RB |
 | `6` | `"LeftTrigger"` | **Left Trigger** | L2 | ZL | LT |
 | `7` | `"RightTrigger"` | **Right Trigger** | R2 | ZR | RT |
 | `8` | `"Back"` | **Back** | Minus | Options | Back |
 | `9` | `"Start"` | **Start** | Plus | Select | Start |
-| `10` | `"LeftStick"` | **Left Stick (click)** | L3 | L3 | LSB |
-| `11` | `"RightStick"` | **Right Stick (click)** | R3 | R3 | RSB |
+| `10` | `"LeftStickClick"` | **Left Stick Click** | L3 | L3 | LSB |
+| `11` | `"RightStickClick"` | **Right Stick Click** | R3 | R3 | RSB |
 | `12` | `"DPadUp"` | **D-Pad Up** | ⬆️ | ⬆️ | ⬆️ |
 | `13` | `"DPadDown"` | **D-Pad Down** | ⬇️ | ⬇️ | ⬇️ |
 | `14` | `"DPadLeft"` | **D-Pad Left** |  ⬅️ | ⬅️ | ⬅️ |
 | `15` | `"DPadRight"` | **D-Pad Right** | ➡️ | ➡️ | ➡️ |
 
-*See [Nintendo Layout Remapping](#gamepad---nintendo-layout-remapping) for more context
+#### Gamepad Axis Codes
+
+Bindable helpers are available for the joysticks.
+
+| Axis # | AxisCode | Standard | Layout
+|:---:|:---:|:---:|:---:|
+| `0` | `"LeftStickLeft"`<br/>`"LeftStickRight"` | **Left Stick (Left/Right)** | ⬅️➡️ |
+| `1` | `"LeftStickUp"`<br/>`"LeftStickDown"` | **Left Stick (Up/Down)** | ⬆️⬇️ |
+| `2` | `"RightStickLeft"`<br/>`"RightStickRight"` | **Right Stick (Left/Right)** | ⬅️➡️ |
+| `3` | `"RightStickUp"`<br/>`"RightStickDown"` | **Right Stick (Up/Down)** | ⬆️⬇️ |
 
 #### Gamepad Layouts
 
 ```ts
-gamepad.layout  // "nintendo" | "xbox" | "playstation" | "logitech" | "steam" | "generic"
+gamepad.layout  // "nintendo" | "xbox" | "playstation" | "logitech" | "steam" | "standard"
 ```
 
 Layout detection is **highly non-standard** across major browsers, it should generally be used for aesthetic
@@ -224,10 +283,10 @@ only major brand controller that deviates from the standard.
 > ***Nintendo:** Both the labels and physical positions of the A,B,X,Y buttons are different
 > on Nintendo controllers.
 >
-> Set `GamepadDevice.defaultOptions.remapNintendoMode` to apply the remapping as required.
+> Set `GamepadDevice.defaultOptions.nintendoRemapMode` to apply the remapping as required.
 >
-> - `"physical"` _**(default)**_ &ndash; The A,B,X,Y button codes will refer the physical layout of a standard controller (Left=X, Top=Y, Bottom=A, Right=B).
-> - `"accurate"` &ndash; The A,B,X,Y button codes will correspond to the exact Nintendo labels (Left=Y, Top=X, Bottom=B, Right=A).
+> - `"physical"` _**(default)**_ &ndash; The A,B,X,Y button codes will refer the standard face button positions (Left=X, Top=Y, Bottom=A, Right=B).
+> - `"accurate"` &ndash; The A,B,X,Y button codes will refer to the exact Nintendo labels (Left=Y, Top=X, Bottom=B, Right=A).
 > - `"none"` &ndash; The A,B,X,Y button codes mapping stay at the default indices (Left=Y, Top=B, Bottom=X, Right=A).
 >
 > ```
@@ -247,25 +306,28 @@ only major brand controller that deviates from the standard.
 You can manually override this per-gamepad, or for all gamepads:
 
 ```ts
-gamepad.options.remapNintendoMode = "none"
-GamepadDevice.defaultOptions.remapNintendoMode = "none"
+// set default
+GamepadDevice.defaultOptions.nintendoRemapMode = "none"
+
+// set for a single gamepad
+gamepad.options.nintendoRemapMode = "accurate"
 ```
 
 #### GamepadDevice Events
 
 | Event | Description | Payload |
 |---|---|---|
-| `"group"` | `{groupName,button,buttonCode,device}` | A **named input group** button was pressed. |
+| `"bind"` | `{name,button,buttonCode,device}` | A **named bind** button was pressed. |
 | **Button presses:** | | |
 | `"A"` | `{button,buttonCode,device}` | Standard layout button `"A"` was pressed. Equivalent to `0`. |
 | `"B"` | `{button,buttonCode,device}` | Standard layout button `"B"` was pressed. Equivalent to `1`. |
 | `"X"` | `{button,buttonCode,device}` | Standard layout button `"X"` was pressed. Equivalent to `2`. |
-| ... | ... | ... |
+| … | … | … |
 | **Button presses (no label):** | | |
 | `0` or `Button.A` | `{button,buttonCode,device}` | Button at offset `0` was pressed. |
 | `1` or `Button.B` | `{button,buttonCode,device}` | Button at offset `1` was pressed. |
 | `2` or `Button.X` | `{button,buttonCode,device}` | Button at offset `2` was pressed. |
-| ... | ... | ... |
+| … | … | … |
 
 ### Custom Devices
 
@@ -287,26 +349,26 @@ export const myDevice: CustomDevice = {
 InputDevice.add( myDevice )
 ```
 
-## Named Input Groups
+## Named Binds
 
-Use named "groups" to create named inputs that can be referenced.
+Use _named binds_ to create mappings between abstract inputs and the keys/buttons that trigger those inputs.
 
 This allows you to change the keys/buttons later (e.g. allow users to override inputs).
 
 ```ts
 // keyboard:
-InputDevice.keyboard.options.namedGroups = {
+InputDevice.keyboard.configureBinds({
     jump: [ "ArrowUp", "Space", "KeyW" ],
     crouch: [ "ArrowDown", "KeyS" ],
     toggleGraphics: [ "KeyB" ],
-}
+})
 
 // all gamepads:
-GamepadDevice.defaultOptions.namedGroups = {
-    jump: [ "A" ],
+GamepadDevice.configureDefaultBinds({
+    jump: [ "A", "LeftStickUp" ],
     crouch: [ "B", "X", "RightTrigger" ],
-    toggleGraphics: [ "RightStick" ],
-}
+    toggleGraphics: [ "RightStickUp", "RightStickDown" ],
+})
 ```
 
 These can then be used with either the real-time and event-based APIs.
@@ -315,11 +377,11 @@ These can then be used with either the real-time and event-based APIs.
 
 ```ts
 // listen to all devices:
-InputDevice.onGroup( "toggleGraphics", ( e ) => toggleGraphics() )
+InputDevice.onBind( "toggleGraphics", ( e ) => toggleGraphics() )
 
 // listen to specific devices:
-InputDevice.keyboard.onGroup( "jump", ( e ) => doJump() )
-InputDevice.gamepads[0].onGroup( "jump", ( e ) => doJump() )
+InputDevice.keyboard.onBind( "jump", ( e ) => doJump() )
+InputDevice.gamepads[0].onBind( "jump", ( e ) => doJump() )
 ```
 
 #### Real-time:
@@ -328,14 +390,14 @@ InputDevice.gamepads[0].onGroup( "jump", ( e ) => doJump() )
 let jump = false, crouch = false, moveX = 0
 
 const keyboard = InputDevice.keyboard
-if ( keyboard.groupPressed( "jump" ) ) jump = true
-if ( keyboard.groupPressed( "crouch" ) ) crouch = true
+if ( keyboard.pressedBind( "jump" ) ) jump = true
+if ( keyboard.pressedBind( "crouch" ) ) crouch = true
 if ( keyboard.key.ArrowLeft ) moveX = -1
 else if ( keyboard.key.ArrowRight ) moveX = 1
 
 for ( const gamepad of InputDevice.gamepads ) {
-    if ( gamepad.groupPressed( "jump" ) ) jump = true
-    if ( gamepad.groupPressed( "crouch" ) ) crouch = true
+    if ( gamepad.pressedBind( "jump" ) ) jump = true
+    if ( gamepad.pressedBind( "crouch" ) ) crouch = true
 
     // gamepads have additional analog inputs
     // we're going to apply these only if touched
@@ -344,123 +406,69 @@ for ( const gamepad of InputDevice.gamepads ) {
 }
 ```
 
-## Navigation API
-
-Automatically traverse existing pointer/mouse based menus using the `Navigation` API.
-
-```ts
-// set root container
-Navigation.stage = app.stage
-
-const button = new ButtonSprite()
-button.on( "mousedown", () => button.run( clickAnimation ) )
-button.on( "mouseout", () => button.run( resetAnimation ) )
-button.on( "mouseover", () => button.run( hoverAnimation ) )
-
-app.stage.addChild( button )
-
-button.isNavigatable  // true
-```
-
-> [!NOTE]
-> **isNavigatable:** By default, any element with `"mousedown"` or `"pointerdown"` handlers is navigatable.
+## UINavigation API
 
-> [!WARNING]
-> **Fallback Hover Effect:** If there is no `"pointerover"` or `"mouseover"` handler detected on a container, `Navigation`
->  will apply abasic alpha effect to the selected item to indicate which container is currently the navigation target. This
-> can be disabled by setting `Navigation.options.useFallbackHoverEffect` to `false`.
-
-### Disable Navigation
-
-You can **disable** the navigation API - either permanently or temporarily - like so:
+_Traverse a UI using input devices._
 
 ```ts
-Navigation.options.enabled = false
+UINavigation.configureWithRoot( app.stage )  // (or any Container)
 ```
 
-### NavigationResponders
-
-UIs can be complex! The Navigation API allows you to take over some - or all - of the navigation elements.
-
-You can create **NavigationResponder** controllers, which can be a `Container` that becomes the
-"root" node for navigation. It can also just be any object (like a custom manager class).
-
-It has a method called `handledNavigationIntent(): boolean` which can return a boolean saying whether
-the navigation event was handled. If you return false here, it is bubbled up to the next parent in the
-stack.
-
-To add a responder, just use `Navigation.pushResponder( responder )` - and then remove it with `Navigation.popResponder()`.
+You can manually take control of navigation using:
 
 ```ts
-class MyVerticalMenu implements NavigationResponder
-{
-    handledNavigationIntent( intent, device ): boolean {
-        if ( intent === "navigateUp" ) this.moveCursorUp()
-        else if ( intent === "navigateDown" ) this.moveCursorDown()
-        else if ( intent === "navigateBack" ) this.loseFocus()
-        else if ( intent === "trigger" ) this.clickCursorItem()
-
-        // we are going to return false here, which will propagates unhandled
-        // intents ("navigateLeft", "navigateRight") up to the next responder
-        // in the stack - which could be a parent view, etc.
-        return false
-    }
+// take control
+UINavigation.pushResponder( myModalView )
 
-    becameFirstResponder() {
-        console.log( "I'm in charge now!" )
-    }
+// relinquish control
+UINavigation.popResponder()
+```
 
-    resignedAsFirstResponder() {
-        console.log( "Nooo! My power is gone!" )
-    }
-}
+The Navigation API is centered around the **UINavigation** manager, which
+receives navigation intents from devices and forwards it to the UI context.
 
-const myMenu = new MyVerticalMenu()
-Navigation.pushResponder( myMenu )
-```
+The **UINavigation** manager maintains a stack of responders, which can be a
+`Container`, or any object that implements the `NavigationResponder` interface.
 
-In a game, you might use this to disable navigation outside of menus:
+When a device sends a navigation intent, the **UINavigation** manager is
+responsible for asking the **first responder** whether it can handle the intent.
 
-```ts
-class GameScene implements NavigationResponder
-{
-    handledNavigationIntent( intent, device ) {
-        // ignore navigation intents, but allow other navigatable
-        // views to be pushed on top of me - e.g. a dialog window:
-        return true
-    }
-}
-```
+If it returns `false`, any other responders are checked (if they exist),
+otherwise the default global navigation behavior kicks in.
 
-### Default Navigation Binds
+### Default Global Navigation Behaviors
 
-Keyboard and gamepad devices are configured with a few default binds for navigation.
+When a navigation intent is **not** handled manually by a responder, it is handled in one of the following ways:
 
-The default binds are below:
+| Intent | Behavior |
+|---|---|
+|`"navigate.back"`|<ul><li>No action.</li></ul>|
+|`"navigate.left"`, `"navigate.right"`, `"navigate.up"`, `"navigate.down"`|<ul><li>Looks for the nearest `Container` where `container.isNavigatable` in the direction given, and if found, receives a `"deviceover"` event.</li><li>Additionally, if the newly focused container has registered an event handler for either `"pointerover"` or `"mouseover"` (in that order), it will fire that too.</li><li>If we were previously focused on a container, that previous container receives a `"deviceout"` event.</li><li>If the blurred container has register an event handler for either `"pointerout"` or `"mouseout"` (in that order), that event handler will be fired too.</li></ul>|
+|`"navigate.trigger"`|<ul><li>Checks if we are currently focused on a container, and then issue a `"devicedown"` event.</li><li>If the focused container has registered an event handler for either `"pointerdown"` or `"mousedown"` (in that order), that event handler will be fired too.</li></ul>|
 
-Navigation Intent | Keyboard               | Gamepad
-------------------|------------------------|-----------------------------------
-`"navigateLeft"`  | `ArrowLeft`, `KeyA`    | Left Joystick (Left), `DPadLeft`
-`"navigateRight"` | `ArrowRight`, `KeyD`   | Left Joystick (Right), `DPadRight`
-`"navigateUp"`    | `ArrowUp`, `KeyW`      | Left Joystick (Up), `DPadDown`
-`"navigateDown"`  | `ArrowDown`, `KeyS`    | Left Joystick (Down), `DPadUp`
-`"navigateBack"`  | `Escape`, `Backspace`  | `B`, `Back`
-`"trigger"`       | `Enter,` `Space`       | `A`
+Container event  | Description | Compatibility
+-----------------|--------------------------------------------------------
+`"devicedown"`   | Target was triggered. | `"pointerdown"`, `"mousedown"`
+`"deviceover"`   | Target became focused. | `"pointerover"`, `"mouseover"`
+`"deviceout"`    | Target lost focus. | `"pointerout"`, `"mouseout"`
 
-These can be manually configured in `<device>.options.navigation.binds`.
+### Container Navigatability
 
-#### Container Mixin
+Containers are extended with a few properties/accessors:
 
 Container properties | type | default | description
 ---------------------|------|---------|--------------
-`isNavigatable`      | `boolean` | `false` | returns `true` if `navigationMode` is set to `"target"`, or is `"auto"` and a `"pointerdown"` or `"mousedown"` event handler is registered.
+`isNavigatable`      | `get(): boolean` | `false` | returns `true` if `navigationMode` is set to `"target"`, or is `"auto"` and a `"pointerdown"` or `"mousedown"` event handler is registered.
 `navigationMode`     | `"auto"` \| `"disabled"` \| `"target"` | `"auto"` | When set to `"auto"`, a `Container` can be navigated to if it has a `"pointerdown"` or `"mousedown"` event handler registered.
 `navigationPriority` | `number` | `0` | The priority relative to other navigation items in this group.
 
-Container events  | description
-------------------|--------------------------------------------------------
-`focus`           | Target became focused.
-`blur`            | Target lost focus.
+> [!NOTE]
+> **isNavigatable:** By default, any element with `"pointerdown"` or `"mousedown"` handlers is navigatable.
+
+> [!WARNING]
+> **Fallback Hover Effect:** If there is no `"pointerover"` or `"mouseover"` handler detected on a container, `UINavigation`
+>  will apply abasic alpha effect to the selected item to indicate which container is currently the navigation target. This
+> can be disabled by setting `UINavigation.options.useFallbackHoverEffect` to `false`.
 
 
 ## Advanced usage
@@ -519,7 +527,7 @@ InputDevice.remove( onscreen )
 You could set up multiple named inputs:
 
 ```ts
-InputDevice.keyboard.options.namedGroups = {
+InputDevice.keyboard.configureBinds({
     jump: [ "ArrowUp", "KeyW" ],
     defend: [ "ArrowDown", "KeyS" ],
     left: [ "ArrowLeft", "KeyA" ],
@@ -534,31 +542,31 @@ InputDevice.keyboard.options.namedGroups = {
     p2_defend: [ "ArrowDown" ],
     p2_left: [ "ArrowLeft" ],
     p2_right: [ "ArrowRight" ],
-}
+})
 ```
 
 and then switch groups depending on the mode:
 
 ```ts
-if ( gameMode === "2p" )
+if ( gameMode === "multiplayer" )
 {
-    // multiplayer
-    player1.jump = device.pressedGroup( "p1_jump" )
-    player1.defend = device.pressedGroup( "p1_defend" )
-    player1.moveX += device.pressedGroup( "p1_left" ) ? -1 : 0
-    player1.moveX += device.pressedGroup( "p1_right" ) ? 1 : 0
-    player2.jump = device.pressedGroup( "p2_jump" )
-    player2.defend = device.pressedGroup( "p2_defend" )
-    player2.moveX += device.pressedGroup( "p2_left" ) ? -1 : 0
-    player2.moveX += device.pressedGroup( "p2_right" ) ? 1 : 0
+    player1.jump   = device.pressedBind( "p1_jump" )
+    player1.defend = device.pressedBind( "p1_defend" )
+    player1.moveX += device.pressedBind( "p1_left" ) ? -1 : 0
+    player1.moveX += device.pressedBind( "p1_right" ) ? 1 : 0
+
+    player2.jump   = device.pressedBind( "p2_jump" )
+    player2.defend = device.pressedBind( "p2_defend" )
+    player2.moveX += device.pressedBind( "p2_left" ) ? -1 : 0
+    player2.moveX += device.pressedBind( "p2_right" ) ? 1 : 0
 }
 else
 {
-    // single player
-    player1.jump = device.pressedGroup( "jump" )
-    player1.defend = device.pressedGroup( "defend" )
-    player1.moveX += device.pressedGroup( "left" ) ? -1 : 0
-    player1.moveX += device.pressedGroup( "right" ) ? 1 : 0
-    player2.updateComputerPlayer()
+    player1.jump   = device.pressedBind( "jump" )
+    player1.defend = device.pressedBind( "defend" )
+    player1.moveX += device.pressedBind( "left" ) ? -1 : 0
+    player1.moveX += device.pressedBind( "right" ) ? 1 : 0
+
+    updateComputerPlayerInput( player2 )
 }
 ```