Update the trigger-rumble explainer to match the latest spec version (MicrosoftEdge#757)

* Update the explainer to match the latest spec version

* Addressing PR review feedback

Author: gabrielsanbrito

Diff for: GamepadHapticsActuatorTriggerRumble/explainer.md

@@ -54,14 +54,15 @@ dictionary GamepadEffectParameters {
 };
 ```
 
-Since not every gamepad has the trigger-rumble feature, the developer must use the "canPlay" method to query the device's capabilities. This method should take a GamepadHapticEffectType string and return true if the selected gamepad can play an effect of the specified type. Otherwise, it should return false. It should be noted that devices with trigger-rumble support should also be capable to provide dual-rumble feedback.
+Since not every gamepad has the trigger-rumble feature, the developer must check the `effects` array to query the device's capabilities. This array should contain all the `GamepadHapticEffectType` strings that the gamepad device supports. We propose implementing an array like this, because it also allow applications to detect and discover new types of haptics effects - please refer to the [Alternative Solutions](#alternative-solutions) section for more info on other options considered. It should be noted that devices with trigger-rumble support should also be capable to provide dual-rumble feedback.
 
 ```js
 interface GamepadHapticActuator {
-    boolean canPlay(GamepadHapticEffectType type);
+    [SameObject] readonly attribute FrozenArray<GamepadHapticEffectType> effects;
 };
 ```
 
+
 ## Use Cases
 
 The trigger-rumble effect could be activated for both triggers of a gamepad at index 0 using the code below (1 second, 50% intensity on left trigger and full on right), given that the device has support for it. Moreover, if the device is not able to play trigger rumble feedback, it should be capable to fallback to dual rumble.
@@ -71,7 +72,7 @@ let gamepads = navigator.getGamepads();
 if (gamepads.length > 0) {
   let gamepad = gamepads[0];
   if (gamepad.vibrationActuator) {
-    if (gamepad.vibrationActuator.canPlay && gamepad.vibrationActuator.canPlay("trigger-rumble")) {
+    if (gamepad.vibrationActuator.effects && gamepad.vibrationActuator.effects.includes("trigger-rumble")) {
       gamepad.vibrationActuator.playEffect("trigger-rumble", {
         duration: 1000,
         leftTrigger: 0.5,
@@ -96,9 +97,11 @@ Allowing websites to query for Gamepads' haptic capabilities might raise fingerp
 
 ## Alternative Solutions
 
-### `canPlay` versus a new `GamepadHapticActuatorType` entry
+### `GamepadHapticActuatorType` entry for effect support detection
+Adding a new entry entry, e.g. "trigger-rumble" to GamepadHapticActuatorType might be difficult to accomplish without breaking existing apps. For example, an app that always checks for "dual-rumble" may break if Xbox controllers suddenly begin to return "trigger rumble" as their `GamepadHapticActuatorType`. Therefore, it may be better to let the web applications do the required capability detection using a different route - e.g., by checking the `effects` array -; and always define `GamepadHapticActuator.type` to be "dual-rumble", so apps cannot rely on it, then deprecate, and eventually remove it.
 
-Adding a new entry entry, e.g. "trigger-rumble" to GamepadHapticActuatorType might be difficult to accomplish without breaking existing apps. For example, an app that always checks for "dual-rumble" may break if Xbox controllers suddenly begin to return "trigger rumble" as their `GamepadHapticActuatorType`. Therefore, it may be better to let the web applications do the required capability detection by calling `canPlay`; and always define `GamepadHapticActuator.type` to be "dual-rumble", so apps cannot rely on it, then deprecate, and eventually remove it.
+### `canPlay` method
+A new `canPlay` method that takes a `GamepadHapticEffectType` string and returns a `boolean` could also be used to query a gamepad's haptics capabilities. However, this requires a new call to be made for every `GamepadHapticEffectType` we would like to check for support. Moreover, implementing a method like this could affect legacy engines, in case effect types need to be deprecated or renamed.
 
 ## Future Plans for this API
 The extension to the `GamepadHapticsActuator` is a short-term solution to unblock developers from being limited to 2-motor rumble on current generation hardware. In the long-term, we plan to invest in the [HapticsDevice API](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/HapticsDevice/explainer.md), which will supercede this API, the [Vibration API](https://w3c.github.io/vibration/#dom-navigator-vibrate), and will generalize haptics behaviors across many devices and applications. This new `HapticsDevice` API will be applied to Gamepad to support rumble and haptic effects in previous and next generation hardware.