Polish Input Mapping V2 gesture help and combo actions - PR_26140_102-polish-input-mapping-v2-gesture-help-and-combo-actions

Author: DavidQ

docs/dev/reports/input_mapping_v2_gesture_help_combo_actions_report.md

@@ -0,0 +1,72 @@
+# Input Mapping V2 Gesture Help And Combo Actions Report
+
+PR: `PR_26140_102-polish-input-mapping-v2-gesture-help-and-combo-actions`
+
+## Source Of Truth
+- Read `docs/dev/PROJECT_INSTRUCTIONS.md` before execution.
+- The active `docs/pr/BUILD_PR.md` did not describe this PR. Used the explicit PR102 user request as the build source of truth.
+- No schema changes were required.
+- No sample JSON files were touched.
+
+## Changes
+- Added hover/title help to gesture descriptors with concrete use-case guidance for mouse drag, mouse drag release, wheel, keyboard combo, mouse combo, game controller combo, and cross-device combo.
+- Added a cross-device combo descriptor so Input Mapping V2 can present combo capture across enabled keyboard, mouse, and game controller sources.
+- Refined combo capture copy and flow so keyboard + keyboard, keyboard + mouse, game controller + keyboard, and game controller + mouse combos can add multiple captured inputs to one selected mapping/action.
+- Preserved gamepad capture behavior while improving combo polling so mocked or detected gamepad input can be paired with keyboard/mouse input.
+- Removed click-to-delete behavior from captured mapping tokens. Tokens are now display items, not delete controls.
+- Added Captured Mappings action controls after an `<hr>` separator:
+  - `Delete Action`
+  - `Delete Mappings`
+  - existing `Delete All`
+- `Delete Action` removes the selected action tile.
+- `Delete Mappings` clears mappings from the selected action tile while keeping the action tile.
+- Reduced captured mapping action button border radius so taller buttons read as buttons instead of oval pills.
+
+## Playwright Impact
+Playwright impacted: Yes.
+
+Behavior validated:
+- Gesture hover/title help exists and includes use-case guidance.
+- Cross-device combo gesture is surfaced when multiple compatible devices are enabled.
+- `Shift + Mouse Right Button` combo can be represented.
+- `Joystick Button 1 + Keyboard Alt` combo can be represented with mocked gamepad plus keyboard input.
+- Clicking captured mapping tokens no longer deletes them.
+- `Delete Action` removes the selected action tile.
+- `Delete Mappings` clears mappings while preserving the selected action tile.
+- `<hr>` appears before the Captured Mappings action buttons.
+- Captured Mappings action buttons use reduced border radius.
+- Existing selected tile, combo display, and gamepad capture behavior remain covered by the Input Mapping V2 workspace tests.
+
+Expected pass behavior:
+- All focused Input Mapping V2 assertions pass under `npm run test:workspace-v2`.
+- Gesture help is discoverable via title attributes.
+- Combo mappings show all captured inputs on the same selected action tile.
+
+Expected fail behavior:
+- Tests fail if gesture help text is missing, tokens delete on click, combo pairings are not represented, or delete controls do not perform their scoped action.
+
+## Validation
+- Targeted syntax/import validation: PASS.
+- Targeted engine input unit validation: PASS.
+- Focused Input Mapping V2 Playwright coverage: PASS, 2 tests.
+- `npm run test:workspace-v2`: PASS, 61 tests.
+- Playwright V8 coverage report for changed runtime JS: PASS, advisory only.
+- `git diff --check`: PASS, line-ending warnings only.
+- HTML inline script/style/handler scan: PASS, no matches.
+- Sample/JSON diff scan: PASS, no changed sample or JSON files.
+- Full samples smoke test: not run, per request and project instructions.
+
+## Manual Validation
+1. Open Workspace Manager V2 and launch Input Mapping V2.
+2. Hover each visible gesture button and confirm the title explains the intended use case.
+3. Create an action, capture a keyboard combo such as `Ctrl + R`, then confirm both inputs display on one tile.
+4. Capture `Shift + Mouse Right Button` and confirm the combo displays without deleting when tokens are clicked.
+5. With a game controller available or mocked, capture `Game Controller Button 1 + Keyboard Alt`.
+6. Select a tile and use `Delete Mappings`; expected: mappings clear while the tile remains.
+7. Select a tile and use `Delete Action`; expected: the selected action tile is removed.
+8. Confirm `Delete All` is still available and not duplicated with `Delete Action` or `Delete Mappings`.
+
+## Out Of Scope
+- Sample JSON alignment.
+- Full samples smoke test.
+- Schema changes.

src/engine/input/InputCapabilityDescriptors.js

@@ -65,24 +65,25 @@ const DEVICE_DEFINITIONS = Object.freeze([
 ]);
 
 const GESTURE_DEFINITIONS = Object.freeze([
-    keyboardGesture('KeyboardPress', 'Press', 'Keyboard key press', 'keyboard'),
-    keyboardGesture('KeyboardRelease', 'Release', 'Keyboard key release', 'keyboard'),
-    keyboardGesture('KeyboardHold', 'Hold', 'Keyboard key hold', 'keyboard'),
-    comboGesture('KeyboardCombo', 'Keyboard', ['keyboard']),
-    mouseGesture('MouseClick', 'Click', 'Mouse click', 'mouse'),
-    mouseGesture('MouseDoubleClick', 'Double Click', 'Mouse double click', 'mouse'),
-    pointerGesture('MousePrimaryDrag', 'Drag', 'Mouse drag', 'mouse'),
-    pointerGesture('MousePrimaryDragRelease', 'Drag Release', 'Mouse drag release', 'mouse'),
-    wheelGesture('MouseWheelUp', 'Wheel Up', 'Mouse wheel up'),
-    wheelGesture('MouseWheelDown', 'Wheel Down', 'Mouse wheel down'),
-    wheelGesture('MouseWheelLeft', 'Wheel Left', 'Mouse wheel left'),
-    wheelGesture('MouseWheelRight', 'Wheel Right', 'Mouse wheel right'),
-    comboGesture('MouseCombo', 'Mouse', ['mouse']),
-    gameControllerGesture('GameControllerButton', 'Button', 'Game controller button', 'gameController'),
-    gameControllerGesture('GameControllerTrigger', 'Trigger', 'Game controller trigger', 'gameController'),
-    gameControllerGesture('GameControllerStick', 'Stick', 'Game controller stick', 'gameController'),
-    gameControllerGesture('GameControllerDPad', 'DPad', 'Game controller DPad', 'gameController'),
-    comboGesture('GameControllerCombo', 'Game Controller', ['gameController'])
+    keyboardGesture('KeyboardPress', 'Press', 'Keyboard key press. Use for one-shot actions such as jump, confirm, or fire.', 'keyboard'),
+    keyboardGesture('KeyboardRelease', 'Release', 'Keyboard key release. Use for actions that trigger when a key is lifted.', 'keyboard'),
+    keyboardGesture('KeyboardHold', 'Hold', 'Keyboard key hold. Use for continuous movement while a key remains down.', 'keyboard'),
+    comboGesture('KeyboardCombo', 'Keyboard', ['keyboard'], 'Keyboard Combo. Use for shortcuts such as Ctrl + R. Capture two keyboard inputs for one selected action.'),
+    mouseGesture('MouseClick', 'Click', 'Mouse click. Use for direct pointing actions such as select, confirm, or fire.', 'mouse'),
+    mouseGesture('MouseDoubleClick', 'Double Click', 'Mouse double click. Use for quick repeated pointer actions such as open, focus, or inspect.', 'mouse'),
+    pointerGesture('MousePrimaryDrag', 'Drag', 'Mouse Drag. Use for continuous movement while held, such as panning or scrolling a map.', 'mouse'),
+    pointerGesture('MousePrimaryDragRelease', 'Drag Release', 'Mouse Drag Release. Use for completed drag gestures, such as box-selecting objects from start/end positions.', 'mouse'),
+    wheelGesture('MouseWheelUp', 'Wheel Up', 'Mouse Wheel Up. Use for zoom, scrolling, or cycling selections.'),
+    wheelGesture('MouseWheelDown', 'Wheel Down', 'Mouse Wheel Down. Use for zoom, scrolling, or cycling selections.'),
+    wheelGesture('MouseWheelLeft', 'Wheel Left', 'Mouse Wheel Left. Use for horizontal scrolling or cycling selections.'),
+    wheelGesture('MouseWheelRight', 'Wheel Right', 'Mouse Wheel Right. Use for horizontal scrolling or cycling selections.'),
+    comboGesture('MouseCombo', 'Mouse', ['mouse'], 'Mouse Combo. Use for combinations such as Shift + Mouse Right Button. Capture keyboard, mouse, wheel, or controller inputs for one selected action.'),
+    gameControllerGesture('GameControllerButton', 'Button', 'Game controller button. Use for face buttons, shoulder buttons, and digital controller controls.', 'gameController'),
+    gameControllerGesture('GameControllerTrigger', 'Trigger', 'Game controller trigger. Use for analog trigger actions such as accelerate, brake, or charge.', 'gameController'),
+    gameControllerGesture('GameControllerStick', 'Stick', 'Game controller stick. Use for analog movement, aiming, or steering.', 'gameController'),
+    gameControllerGesture('GameControllerDPad', 'DPad', 'Game controller DPad. Use for directional menu or movement actions.', 'gameController'),
+    comboGesture('GameControllerCombo', 'Game Controller', ['gameController'], 'Game Controller Combo. Use for controller combinations such as Button 1 + Button 2.'),
+    crossDeviceComboGesture()
 ]);
 
 export function inputDeviceCapabilities({
@@ -157,6 +158,7 @@ export function inputGestureDescriptors({
     const enabled = new Set(enabledDeviceIds);
     return GESTURE_DEFINITIONS.filter((gesture) => (
         gesture.requiredDeviceIds.every((deviceId) => enabled.has(deviceId))
+        && (!gesture.anyOfDeviceIds || gesture.anyOfDeviceIds.filter((deviceId) => enabled.has(deviceId)).length >= gesture.minimumEnabledDevices)
         && (gesture.captureKind !== 'wheel' || wheelAvailable || advancedModeAvailable)
     )).map((gesture) => ({ ...gesture }));
 }
@@ -243,7 +245,7 @@ function wheelGesture(binding, label, title) {
     };
 }
 
-function comboGesture(binding, deviceLabel, requiredDeviceIds) {
+function comboGesture(binding, deviceLabel, requiredDeviceIds, title) {
     return {
         binding,
         captureKind: 'combo',
@@ -253,7 +255,23 @@ function comboGesture(binding, deviceLabel, requiredDeviceIds) {
         label: 'Combo',
         requiredDeviceIds,
         source: requiredDeviceIds[0] === 'gameController' ? 'gamepad' : requiredDeviceIds[0],
-        title: `${deviceLabel} combo`
+        title
+    };
+}
+
+function crossDeviceComboGesture() {
+    return {
+        binding: 'CrossDeviceCombo',
+        captureKind: 'combo',
+        deviceLabel: 'Cross-device',
+        displayLabelLines: ['Cross-device', 'Combo'],
+        engine: 'InputService Combo',
+        label: 'Combo',
+        anyOfDeviceIds: ['keyboard', 'mouse', 'gameController'],
+        minimumEnabledDevices: 2,
+        requiredDeviceIds: [],
+        source: 'keyboard',
+        title: 'Cross-device Combo. Use for combinations such as Joystick Button 1 + Keyboard Alt. Capture any two keyboard, mouse, wheel, or game controller inputs for one selected action.'
     };
 }
 

tests/input/InputService.test.mjs

@@ -85,6 +85,11 @@ export function run() {
     assert(!capabilities.some((device) => device.label === 'Wheel'), 'Input capabilities should treat wheel as mouse input instead of a device.');
     const gestures = input.getInputGestureDescriptors({ enabledDeviceIds: ['keyboard', 'mouse'] });
     assert(gestures.some((gesture) => gesture.binding === 'MouseWheelUp'), 'Input gestures should expose wheel descriptors through Mouse when wheel is available.');
+    assert(gestures.some((gesture) => gesture.binding === 'CrossDeviceCombo'), 'Input gestures should expose cross-device combos when two combo-capable devices are enabled.');
+    assert(
+        gestures.find((gesture) => gesture.binding === 'MousePrimaryDrag').title.includes('continuous movement while held'),
+        'Gesture descriptors should expose use-case title help.'
+    );
     const gesturesWithoutWheelSupport = input.getInputGestureDescriptors({ enabledDeviceIds: ['keyboard', 'mouse'], wheelAvailable: false });
     assert(!gesturesWithoutWheelSupport.some((gesture) => gesture.binding === 'MouseWheelUp'), 'Input gestures should hide wheel descriptors when wheel support is unavailable.');
     assert(!gestures.some((gesture) => gesture.binding === 'MousePrimaryDragRectangle'), 'Visible input gestures should not expose Drag Rectangle.');