|
| 1 | +/* |
| 2 | +Toolbox Aid |
| 3 | +David Quesenberry |
| 4 | +05/22/2026 |
| 5 | +InputCapabilityDescriptors.js |
| 6 | +*/ |
| 7 | + |
| 8 | +const DEVICE_DEFINITIONS = Object.freeze([ |
| 9 | + { |
| 10 | + id: 'keyboard', |
| 11 | + label: 'Keyboard', |
| 12 | + engine: 'InputService + KeyboardState', |
| 13 | + supported: true, |
| 14 | + defaultEnabled: true, |
| 15 | + detail: 'Keyboard key states are captured from browser keydown and keyup events.' |
| 16 | + }, |
| 17 | + { |
| 18 | + id: 'mouse', |
| 19 | + label: 'Mouse', |
| 20 | + engine: 'InputService + MouseState + PointerDragState', |
| 21 | + supported: true, |
| 22 | + defaultEnabled: true, |
| 23 | + detail: 'Mouse buttons, movement, and drag state are captured from browser mouse and pointer events.' |
| 24 | + }, |
| 25 | + { |
| 26 | + id: 'gameController', |
| 27 | + label: 'Game Controller', |
| 28 | + engine: 'InputService + GamepadState + GamepadInputAdapter', |
| 29 | + supported: true, |
| 30 | + defaultEnabled: true, |
| 31 | + detail: 'Browser Gamepad API devices are auto-polled while the tool is active.' |
| 32 | + }, |
| 33 | + { |
| 34 | + id: 'touch', |
| 35 | + label: 'Touch', |
| 36 | + engine: 'PointerEvent capability descriptor', |
| 37 | + supported: true, |
| 38 | + defaultEnabled: false, |
| 39 | + detail: 'Touch support depends on browser PointerEvent input. This tool exposes capability status only until touch capture is testable here.' |
| 40 | + }, |
| 41 | + { |
| 42 | + id: 'pen', |
| 43 | + label: 'Pen', |
| 44 | + engine: 'PointerEvent capability descriptor', |
| 45 | + supported: true, |
| 46 | + defaultEnabled: false, |
| 47 | + detail: 'Pen support depends on browser PointerEvent input. This tool exposes capability status only until pen capture is testable here.' |
| 48 | + }, |
| 49 | + { |
| 50 | + id: 'wheel', |
| 51 | + label: 'Wheel', |
| 52 | + engine: 'InputService wheel descriptor', |
| 53 | + supported: true, |
| 54 | + defaultEnabled: true, |
| 55 | + detail: 'Mouse wheel directions can be captured directly or as combo inputs.' |
| 56 | + }, |
| 57 | + { |
| 58 | + id: 'flightStick', |
| 59 | + label: 'Flight Stick', |
| 60 | + engine: 'GamepadInputAdapter capability descriptor', |
| 61 | + supported: true, |
| 62 | + defaultEnabled: false, |
| 63 | + detail: 'Flight sticks are represented through the Gamepad API when the browser exposes them.' |
| 64 | + }, |
| 65 | + { |
| 66 | + id: 'vrController', |
| 67 | + label: 'VR Controller', |
| 68 | + engine: 'WebXR capability descriptor', |
| 69 | + supported: false, |
| 70 | + defaultEnabled: false, |
| 71 | + detail: 'VR controller capture requires WebXR input sources and is not available in this tool context.' |
| 72 | + } |
| 73 | +]); |
| 74 | + |
| 75 | +const GESTURE_DEFINITIONS = Object.freeze([ |
| 76 | + keyboardGesture('KeyboardPress', 'Press', 'Keyboard key press', 'keyboard'), |
| 77 | + keyboardGesture('KeyboardRelease', 'Release', 'Keyboard key release', 'keyboard'), |
| 78 | + keyboardGesture('KeyboardHold', 'Hold', 'Keyboard key hold', 'keyboard'), |
| 79 | + comboGesture('KeyboardCombo', 'Keyboard', ['keyboard']), |
| 80 | + mouseGesture('MouseClick', 'Click', 'Mouse click', 'mouse'), |
| 81 | + mouseGesture('MouseDoubleClick', 'Double Click', 'Mouse double click', 'mouse'), |
| 82 | + pointerGesture('MousePrimaryDrag', 'Drag', 'Mouse drag', 'mouse'), |
| 83 | + pointerGesture('MousePrimaryDragRelease', 'Drag Release', 'Mouse drag release', 'mouse'), |
| 84 | + pointerGesture('MousePrimaryDragRectangle', 'Drag Rectangle', 'Mouse drag rectangle', 'mouse'), |
| 85 | + wheelGesture('MouseWheelUp', 'Wheel Up', 'Mouse wheel up', ['mouse', 'wheel']), |
| 86 | + wheelGesture('MouseWheelDown', 'Wheel Down', 'Mouse wheel down', ['mouse', 'wheel']), |
| 87 | + wheelGesture('MouseWheelLeft', 'Wheel Left', 'Mouse wheel left', ['mouse', 'wheel']), |
| 88 | + wheelGesture('MouseWheelRight', 'Wheel Right', 'Mouse wheel right', ['mouse', 'wheel']), |
| 89 | + comboGesture('MouseCombo', 'Mouse', ['mouse']), |
| 90 | + gameControllerGesture('GameControllerButton', 'Button', 'Game controller button', 'gameController'), |
| 91 | + gameControllerGesture('GameControllerTrigger', 'Trigger', 'Game controller trigger', 'gameController'), |
| 92 | + gameControllerGesture('GameControllerStick', 'Stick', 'Game controller stick', 'gameController'), |
| 93 | + gameControllerGesture('GameControllerDPad', 'DPad', 'Game controller DPad', 'gameController'), |
| 94 | + comboGesture('GameControllerCombo', 'Game Controller', ['gameController']) |
| 95 | +]); |
| 96 | + |
| 97 | +export function inputDeviceCapabilities({ |
| 98 | + gamepadCount = 0, |
| 99 | + gamepadWarning = '', |
| 100 | + pointerEventsAvailable = false, |
| 101 | + touchAvailable = false, |
| 102 | + penAvailable = false, |
| 103 | + wheelAvailable = true, |
| 104 | + webXrAvailable = false |
| 105 | +} = {}) { |
| 106 | + return DEVICE_DEFINITIONS.map((device) => { |
| 107 | + if (device.id === 'gameController') { |
| 108 | + return { |
| 109 | + ...device, |
| 110 | + available: !gamepadWarning, |
| 111 | + detail: gamepadWarning || `${gamepadCount} connected game controller${gamepadCount === 1 ? '' : 's'} detected.`, |
| 112 | + emptyState: gamepadCount |
| 113 | + ? '' |
| 114 | + : 'No game controllers are currently exposed. Click inside this page, press a controller button, and wait for auto-polling.' |
| 115 | + }; |
| 116 | + } |
| 117 | + if (device.id === 'touch') { |
| 118 | + return { |
| 119 | + ...device, |
| 120 | + available: pointerEventsAvailable && touchAvailable, |
| 121 | + emptyState: pointerEventsAvailable |
| 122 | + ? 'Touch capability is exposed only when the browser reports a touch pointer.' |
| 123 | + : 'Touch capture requires browser PointerEvent support.' |
| 124 | + }; |
| 125 | + } |
| 126 | + if (device.id === 'pen') { |
| 127 | + return { |
| 128 | + ...device, |
| 129 | + available: pointerEventsAvailable && penAvailable, |
| 130 | + emptyState: pointerEventsAvailable |
| 131 | + ? 'Pen capability is exposed only when the browser reports a pen pointer.' |
| 132 | + : 'Pen capture requires browser PointerEvent support.' |
| 133 | + }; |
| 134 | + } |
| 135 | + if (device.id === 'wheel') { |
| 136 | + return { |
| 137 | + ...device, |
| 138 | + available: wheelAvailable, |
| 139 | + emptyState: wheelAvailable ? '' : 'Wheel input requires browser wheel event support.' |
| 140 | + }; |
| 141 | + } |
| 142 | + if (device.id === 'flightStick') { |
| 143 | + return { |
| 144 | + ...device, |
| 145 | + available: !gamepadWarning, |
| 146 | + detail: gamepadWarning || device.detail, |
| 147 | + emptyState: gamepadCount |
| 148 | + ? 'Use the game controller capture buttons for browser-exposed flight stick inputs.' |
| 149 | + : 'No browser-exposed flight stick is currently visible through the Gamepad API.' |
| 150 | + }; |
| 151 | + } |
| 152 | + if (device.id === 'vrController') { |
| 153 | + return { |
| 154 | + ...device, |
| 155 | + available: webXrAvailable, |
| 156 | + emptyState: webXrAvailable |
| 157 | + ? 'WebXR is present, but this tool does not open an XR session for capture.' |
| 158 | + : device.detail |
| 159 | + }; |
| 160 | + } |
| 161 | + return { |
| 162 | + ...device, |
| 163 | + available: true, |
| 164 | + emptyState: '' |
| 165 | + }; |
| 166 | + }); |
| 167 | +} |
| 168 | + |
| 169 | +export function inputGestureDescriptors({ enabledDeviceIds = [] } = {}) { |
| 170 | + const enabled = new Set(enabledDeviceIds); |
| 171 | + return GESTURE_DEFINITIONS.filter((gesture) => ( |
| 172 | + gesture.requiredDeviceIds.every((deviceId) => enabled.has(deviceId)) |
| 173 | + )).map((gesture) => ({ ...gesture })); |
| 174 | +} |
| 175 | + |
| 176 | +export function getInputGestureDescriptor(binding, options = {}) { |
| 177 | + return inputGestureDescriptors(options).find((gesture) => gesture.binding === binding) ?? null; |
| 178 | +} |
| 179 | + |
| 180 | +export function mouseButtonLabel(button) { |
| 181 | + const buttonNumber = Number(button); |
| 182 | + if (buttonNumber === 0) { |
| 183 | + return 'Mouse Left Button'; |
| 184 | + } |
| 185 | + if (buttonNumber === 1) { |
| 186 | + return 'Mouse Middle Button'; |
| 187 | + } |
| 188 | + if (buttonNumber === 2) { |
| 189 | + return 'Mouse Right Button'; |
| 190 | + } |
| 191 | + if (buttonNumber === 3) { |
| 192 | + return 'Mouse Button 4'; |
| 193 | + } |
| 194 | + if (buttonNumber === 4) { |
| 195 | + return 'Mouse Button 5'; |
| 196 | + } |
| 197 | + return `Mouse Button ${buttonNumber + 1}`; |
| 198 | +} |
| 199 | + |
| 200 | +export function wheelDescriptorFromEvent(event = {}) { |
| 201 | + const deltaX = Number(event.deltaX) || 0; |
| 202 | + const deltaY = Number(event.deltaY) || 0; |
| 203 | + if (Math.abs(deltaX) > Math.abs(deltaY)) { |
| 204 | + return deltaX < 0 |
| 205 | + ? wheelInputDescriptor('MouseWheelLeft', 'Wheel Left') |
| 206 | + : wheelInputDescriptor('MouseWheelRight', 'Wheel Right'); |
| 207 | + } |
| 208 | + return deltaY < 0 |
| 209 | + ? wheelInputDescriptor('MouseWheelUp', 'Wheel Up') |
| 210 | + : wheelInputDescriptor('MouseWheelDown', 'Wheel Down'); |
| 211 | +} |
| 212 | + |
| 213 | +export function wheelInputDescriptor(binding, detail) { |
| 214 | + return { |
| 215 | + source: 'mouse', |
| 216 | + binding, |
| 217 | + displayLabelLines: ['Mouse', detail], |
| 218 | + label: `Mouse ${detail}`, |
| 219 | + title: `Mouse\n${detail}`, |
| 220 | + engine: 'InputService Wheel' |
| 221 | + }; |
| 222 | +} |
| 223 | + |
| 224 | +function keyboardGesture(binding, label, title, deviceId) { |
| 225 | + return patternGesture({ binding, deviceLabel: 'Keyboard', label, title, deviceId }); |
| 226 | +} |
| 227 | + |
| 228 | +function mouseGesture(binding, label, title, deviceId) { |
| 229 | + return patternGesture({ binding, deviceLabel: 'Mouse', label, title, deviceId }); |
| 230 | +} |
| 231 | + |
| 232 | +function gameControllerGesture(binding, label, title, deviceId) { |
| 233 | + return patternGesture({ binding, deviceLabel: 'Game Controller', label, title, deviceId }); |
| 234 | +} |
| 235 | + |
| 236 | +function pointerGesture(binding, label, title, deviceId) { |
| 237 | + return { |
| 238 | + ...patternGesture({ binding, deviceLabel: 'Mouse', label, title, deviceId }), |
| 239 | + captureKind: 'pointer-drag', |
| 240 | + source: 'mouse' |
| 241 | + }; |
| 242 | +} |
| 243 | + |
| 244 | +function wheelGesture(binding, label, title, requiredDeviceIds) { |
| 245 | + return { |
| 246 | + binding, |
| 247 | + captureKind: 'wheel', |
| 248 | + deviceLabel: 'Mouse', |
| 249 | + displayLabelLines: ['Mouse', label], |
| 250 | + engine: 'InputService Wheel', |
| 251 | + label, |
| 252 | + requiredDeviceIds, |
| 253 | + source: 'mouse', |
| 254 | + title |
| 255 | + }; |
| 256 | +} |
| 257 | + |
| 258 | +function comboGesture(binding, deviceLabel, requiredDeviceIds) { |
| 259 | + return { |
| 260 | + binding, |
| 261 | + captureKind: 'combo', |
| 262 | + deviceLabel, |
| 263 | + displayLabelLines: [deviceLabel, 'Combo'], |
| 264 | + engine: 'InputService Combo', |
| 265 | + label: 'Combo', |
| 266 | + requiredDeviceIds, |
| 267 | + source: requiredDeviceIds[0] === 'gameController' ? 'gamepad' : requiredDeviceIds[0], |
| 268 | + title: `${deviceLabel} combo` |
| 269 | + }; |
| 270 | +} |
| 271 | + |
| 272 | +function patternGesture({ binding, deviceLabel, label, title, deviceId }) { |
| 273 | + return { |
| 274 | + binding, |
| 275 | + captureKind: 'descriptor', |
| 276 | + deviceLabel, |
| 277 | + displayLabelLines: [deviceLabel, label], |
| 278 | + engine: 'InputService Capability', |
| 279 | + label, |
| 280 | + requiredDeviceIds: [deviceId], |
| 281 | + source: deviceId === 'gameController' ? 'gamepad' : deviceId, |
| 282 | + title |
| 283 | + }; |
| 284 | +} |
0 commit comments