add PaymentMethodChangeEvent event (#695)

marcoscaceres · web-flow · commit b3368917fc9c · 2018-06-21T11:55:19.000-04:00
Also adds: 
* PaymentRequest.prototype.onpaymentmethodchange
diff --git a/index.html b/index.html
@@ -171,7 +171,7 @@ <h2>
       </p>
       <dl>
         <dt>
-          A <dfn>can make payment</dfn> algorithm:
+          <dfn>Steps to check if a payment can be made</dfn>:
         </dt>
         <dd>
           How a payment handler determines whether it, or the user, can
@@ -184,14 +184,23 @@ <h2>
           <dfn>Steps to respond to a payment request</dfn>:
         </dt>
         <dd>
-          An algorithm that returns an object or <a data-cite=
+          Steps that return an object or <a data-cite=
           "!WEBIDL#idl-dictionary">dictionary</a> that a merchant uses to
           process or validate the transaction. The structure of this object is
           specific to each <a>payment method</a>. For an example of such an
           object, see the <code><a data-cite=
           "payment-method-basic-card#dom-basiccardresponse">BasicCardResponse</a></code>
           dictionary of [[payment-method-basic-card]].
         </dd>
+        <dt>
+          <dfn>Steps for when a user changes payment method</dfn> (optional)
+        </dt>
+        <dd>
+          Steps that describe how to handle the user changing payment method or
+          monetary instrument (e.g., from a debit card to a credit card) that
+          results in a <a data-cite="!WEBIDL#idl-dictionary">dictionary</a> or
+          <a data-cite="!WEBIDL#idl-object">object</a> or null.
+        </dd>
       </dl>
       <p>
         This API also enables web sites to take advantage of more secure
@@ -575,8 +584,8 @@ <h2>
           readonly attribute PaymentShippingType? shippingType;
 
           attribute EventHandler onshippingaddresschange;
-
           attribute EventHandler onshippingoptionchange;
+          attribute EventHandler onpaymentmethodchange;
         };
       </pre>
       <div class="note">
@@ -997,8 +1006,8 @@ <h2>
               <li>For each <var>handler</var> in <var>registeredHandlers</var>:
                 <ol>
                   <li>Let <var>canMakePayment</var> be the result of running
-                  <var>handler</var>'s <a>can make payment</a> algorithm with
-                  <var>data</var>.
+                  <var>handler</var>'s <a>steps to check if a payment can be
+                  made</a> with <var>data</var>.
                   </li>
                   <li>If <var>canMakePayment</var> is true, then append
                   <var>handler</var> to <var>handlers</var>.
@@ -1219,8 +1228,8 @@ <h2>
               <li>For each <var>handler</var> in <var>handlers</var>:
                 <ol>
                   <li>Let <var>canMakePayment</var> be the result of running
-                  <var>handler</var>'s <a>can make payment</a> algorithm with
-                  <var>data</var>.
+                  <var>handler</var>'s <a>steps to check if a payment can be
+                  made</a> with <var>data</var>.
                   </li>
                   <li>If <var>canMakePayment</var> is true, resolve
                   <var>promise</var> with true, and return.
@@ -1292,6 +1301,16 @@ <h2>
           <a>shippingoptionchange</a>.
         </p>
       </section>
+      <section data-dfn-for="PaymentRequest" data-link-for="PaymentRequest">
+        <h2>
+          <dfn>onpaymentmethodchange</dfn> attribute
+        </h2>
+        <p data-tests="onpaymentmenthodchange-attribute.https.html">
+          A <a>PaymentRequest</a>'s <a>onpaymentmethodchange</a> attribute is
+          an <a>EventHandler</a> for a <a>PaymentRequestUpdateEvent</a> named
+          "<a>paymentmethodchange</a>".
+        </p>
+      </section>
       <section>
         <h2>
           Internal Slots
@@ -3402,8 +3421,80 @@ <h2>
               The user chooses a new shipping option.
             </td>
           </tr>
+          <tr>
+            <td>
+              <code><dfn>paymentmethodchange</dfn></code>
+            </td>
+            <td>
+              <a>PaymentMethodChangeEvent</a>
+            </td>
+            <td>
+              The user chooses a different <a>payment method</a> within a
+              <a>payment handler</a>.
+            </td>
+          </tr>
         </table>
       </section>
+      <section data-dfn-for="PaymentMethodChangeEvent" data-link-for=
+      "PaymentMethodChangeEvent">
+        <h2>
+          <dfn>PaymentMethodChangeEvent</dfn> interface
+        </h2>
+        <pre class="idl">
+          [Constructor(DOMString type, optional PaymentMethodChangeEventInit eventInitDict), SecureContext, Exposed=Window]
+          interface PaymentMethodChangeEvent : PaymentRequestUpdateEvent {
+            readonly attribute DOMString methodName;
+            readonly attribute object? methodDetails;
+          };
+        </pre>
+        <section>
+          <h2>
+            <dfn>methodDetails</dfn> attribute
+          </h2>
+          <p data-link-for="PaymentMethodChangeEventInit">
+            When getting, returns the value it was initialized with. See
+            <a>methodDetails</a> member of <a>PaymentMethodChangeEventInit</a>
+            for more information.
+          </p>
+        </section>
+        <section>
+          <h2>
+            <dfn>methodName</dfn> attribute
+          </h2>
+          <p data-link-for="PaymentMethodChangeEventInit">
+            When getting, returns the value it was initialized with. See
+            <a>methodName</a> member of <a>PaymentMethodChangeEventInit</a> for
+            more information.
+          </p>
+        </section>
+        <section data-dfn-for="PaymentMethodChangeEventInit" data-link-for=
+        "PaymentMethodChangeEventInit">
+          <h3>
+            <dfn>PaymentMethodChangeEventInit</dfn> dictionary
+          </h3>
+          <pre class="idl">
+            dictionary PaymentMethodChangeEventInit : PaymentRequestUpdateEventInit {
+              required DOMString methodName;
+              object? methodDetails;
+            };
+          </pre>
+          <dl>
+            <dt>
+              <dfn>methodName</dfn> member
+            </dt>
+            <dd>
+              A DOMString representing the <a>payment method identifier</a>.
+            </dd>
+            <dt>
+              <dfn>methodDetails</dfn> member
+            </dt>
+            <dd>
+              An object representing the some data from the payment method, or
+              null.
+            </dd>
+          </dl>
+        </section>
+      </section>
       <section data-dfn-for="PaymentRequestUpdateEvent" data-link-for=
       "PaymentRequestUpdateEvent">
         <h2>
@@ -3672,6 +3763,49 @@ <h2>
           </li>
         </ol>
       </section>
+      <section>
+        <h2>
+          Payment method changed algorithm
+        </h2>
+        <p>
+          A <a>payment handler</a> MAY run the <dfn>payment method changed
+          algorithm</dfn> when the user changes <a>payment method</a> with
+          <var>methodDetails</var>, which is either <a data-cite=
+          "!WEBIDL#idl-dictionary">dictionary</a> or an <a data-cite=
+          "!WEBIDL#idl-object">object</a> or null, and a <var>methodName</var>,
+          which is a DOMString that represents the <a>payment method
+          identifier</a> of the <a>payment handler</a> the user is interacting
+          with:
+        </p>
+        <ol class="algorithm">
+          <li>Let <var>request</var> be the <a>PaymentRequest</a> object that
+          the user is interacting with.
+          </li>
+          <li>
+            <a>Queue a task</a> on the <a>user interaction task source</a> to
+            run the following steps:
+            <ol>
+              <li>If the <var>request</var>.<a>[[\updating]]</a> is true, then
+              terminate this algorithm and take no further action. Only one
+              update may take place at a time. The <a>user agent</a> SHOULD
+              ensure that this never occurs.
+              </li>
+              <li>If the <var>request</var>.<a>[[\state]]</a> is not set to
+              "<a>interactive</a>", then terminate this algorithm and take no
+              further action. The <a>user agent</a> user interface SHOULD
+              ensure that this never occurs.
+              </li>
+              <li data-link-for="PaymentMethodChangeEvent">
+                <a>Fire an event</a> named "<a>paymentmethodchange</a>" at
+                <var>request</var> using <a>PaymentMethodChangeEvent</a>, with
+                its <a>methodName</a> attribute initialized to
+                <var>methodName</var>, and its <a>methodDetails</a> attribute
+                initialized to <var>methodDetails</var>.
+              </li>
+            </ol>
+          </li>
+        </ol>
+      </section>
       <section>
         <h2>
           PaymentRequest updated algorithm
