Feat: allow show() to take optional detailsPromise

marcoscaceres · marcoscaceres · commit 22195c710bae · 2018-02-28T16:26:06.000+11:00
* closes #645
diff --git a/index.html b/index.html
@@ -499,7 +499,7 @@ <h2>
         [Constructor(sequence&lt;PaymentMethodData&gt; methodData, PaymentDetailsInit details, optional PaymentOptions options),
         SecureContext, Exposed=Window]
         interface PaymentRequest : EventTarget {
-          Promise&lt;PaymentResponse&gt; show();
+          Promise&lt;PaymentResponse&gt; show(optional Promise&lt;PaymentDetailsUpdate&gt; detailsPromise);
           Promise&lt;void&gt; abort();
           Promise&lt;boolean&gt; canMakePayment();
 
@@ -824,7 +824,8 @@ <h2>
           </p>
         </div>
         <p data-tests="payment-request-show-method.https.html">
-          The <a>show()</a> method MUST act as follows:
+          The <code><a data-lt="show()">show(detailsPromise)</a></code> method
+          MUST act as follows:
         </p>
         <ol class="algorithm">
           <li>Let <var>request</var> be the <a>PaymentRequest</a> object on
@@ -937,6 +938,37 @@ <h2>
           <a>DOMException</a>, and set the <a>user agent</a>'s <a>payment
           request is showing</a> boolean to false.
           </li>
+          <li>Otherwise, present a user interface that will allow the user to
+          interact with the <var>handlers</var>. The user agent SHOULD
+          prioritize the preference of the user when presenting payment
+          methods.
+          </li>
+          <li data-tests=
+          "show-method-optional-promise-rejects-manual.https.html, show-method-optional-promise-resolves-manual.https.html">
+          If <var>detailsPromise</var> was passed, then:
+            <ol>
+              <li>Set <var>request</var>.<a>[[\updating]]</a> to true.
+              </li>
+              <li>Disable the user interface user interface that will allow the
+              user to interact with the <var>handlers</var>
+              </li>
+              <li>Run the <a>update a <code>PaymentRequest</code>'s details
+              algorithm</a> with <var>detailsPromise</var> and
+              <var>request</var>.
+              </li>
+              <li>Wait for the <var>detailsPromise</var> to settle.
+                <p class="note">
+                  Based on how the <var>detailsPromise</var> settles, the
+                  <a>update a <code>PaymentRequest</code>'s details
+                  algorithm</a> determines how the payment UI behaves. That is,
+                  <a>upon rejection</a> of the <var>detailsPromise</var>, the
+                  payment request aborts. Otherwise, <a>upon fulfillment</a>
+                  <var>detailsPromise</var>, the user agent re-enables the
+                  payment request UI and the payment flow can continue.
+                </p>
+              </li>
+            </ol>
+          </li>
           <li>
             <p>
               Otherwise, present a user interface to allow the user to interact
@@ -3346,9 +3378,9 @@ <h2>
               <li>Set <var>request</var>.<a>[[\updating]]</a> to false.
               </li>
               <li>The <a>user agent</a> SHOULD update the user interface based
-              on any changed values in <var>request</var>. The user agent
-              SHOULD re-enable user interface elements that might have been
-              disabled in the steps above if appropriate.
+              on any changed values in <var>request</var>. If appropriate, the
+              user agent SHOULD re-enable user interface elements that might
+              have been disabled prior to running this algorithm.
               </li>
             </ol>
           </li>
