Merge pull request w3c#7990 from vmpstr/startviewtransition

[css-view-transitions-1] Rename starting function and add callback instead of opts dict

Author: khushalsagar

css-view-transitions-1/Overview.bs

@@ -123,14 +123,13 @@ Note that because these APIs are an enhancement to the DOM change, some principl
     href="https://wicg.github.io/navigation-api/#navigate-event-class">`signal`
     on `NavigateEvent`</a> is an example of a feature developers could use to
     handle this.
-* Although the transition API allows DOM changes to be asynchronous via the
-    {{ViewTransitionInit/updateDOM}} callback, the transition API is not
-    responsible for queuing or otherwise scheduling the DOM changes, beyond the
-    scheduling needed for the transition itself. Some asynchronous DOM changes
-    can happen concurrently (e.g if they're happening within independent
-    components), whereas others need to queue, or abort an earlier change. This
-    is best left to a feature or framework that has a more holistic view of the
-    update.
+* Although the transition API allows DOM changes to be asynchronous via the [=callback=], the transition
+    API is not responsible for queuing or otherwise scheduling the DOM changes,
+    beyond the scheduling needed for the transition itself. Some asynchronous
+    DOM changes can happen concurrently (e.g if they're happening within
+    independent components), whereas others need to queue, or abort an earlier
+    change. This is best left to a feature or framework that has a more
+    holistic view of the update.
 
 # CSS properties # {#css-properties}
 
@@ -449,26 +448,27 @@ A {{Document}} additionally has:
 
 <script type=idl>
 partial interface Document {
-    ViewTransition createTransition(ViewTransitionInit init);
-};
-
-dictionary ViewTransitionInit {
-    required UpdateDOMCallback updateDOM;
+    ViewTransition startViewTransition(optional UpdateDOMCallback? callback = null);
 };
 
 callback UpdateDOMCallback = Promise<any> ();
 </script>
 
-### {{Document/createTransition()}} ### {#ViewTransition-prepare}
+<dl>
+    : <dfn>callback</dfn>
+    :: An asynchronous callback used to change the old DOM state into new DOM state.
+</dl>
+
+### {{Document/startViewTransition()}} ### {#ViewTransition-prepare}
 
 <div algorithm>
     The [=method steps=] for
-    <dfn method for=Document>createTransition(|init|)</dfn>
+    <dfn method for=Document>startViewTransition([=callback=])</dfn>
     are as follows:
 
     1. Let |transition| be a new {{ViewTransition}} object in [=this's=] [=relevant Realm=].
 
-    1. Set |transition|'s [=ViewTransition/DOM update callback=] to |init|[{{ViewTransitionInit/updateDOM}}].
+    1. Set |transition|'s [=ViewTransition/DOM update callback=] to [=callback=].
 
     1. Let |document| be [=this's=] [=relevant global object's=] [=associated document=].
 
@@ -496,10 +496,8 @@ callback UpdateDOMCallback = Promise<any> ();
     and a single line of script to start it:
 
     <pre highlight=js>
-        document.createTransition({
-            updateDOM() {
-                coolFramework.changeTheDOMToPageB();
-            }
+        document.startViewTransition(async () => {
+            coolFramework.changeTheDOMToPageB();
         });
     </pre>
 
@@ -513,22 +511,20 @@ callback UpdateDOMCallback = Promise<any> ();
             // the transitioning pseudo-element.
             document.querySelector('.old-message').style.pageTransitionTag = 'message';
 
-            const transition = document.createTransition({
-                async updateDOM() {
-                    // This callback is invoked by the browser when "outgoing"
-                    // capture finishes and the DOM can be switched to the new
-                    // state. No frames are rendered until this callback returns.
-
-                    // DOM changes may be asynchronous
-                    await coolFramework.changeTheDOMToPageB();
-
-                    // Tagging elements during the updateDOM() callback marks them as
-                    // "incoming", to be matched up with the same-tagged "outgoing"
-                    // elements marked previously and transitioned between.
-                    document.querySelector('.new-message').style.pageTransitionTag =
-                        'message';
-                },
-            });
+            const transition = document.startViewTransition(async () => {
+                // This callback is invoked by the browser when "outgoing"
+                // capture finishes and the DOM can be switched to the new
+                // state. No frames are rendered until this callback returns.
+
+                // DOM changes may be asynchronous
+                await coolFramework.changeTheDOMToPageB();
+
+                // Tagging elements during the callback marks them as
+                // "incoming", to be matched up with the same-tagged "outgoing"
+                // elements marked previously and transitioned between.
+                document.querySelector('.new-message').style.pageTransitionTag =
+                    'message';
+              });
 
             // When ready resolves, all pseudo-elements for this transition have
             // been generated.
@@ -759,7 +755,7 @@ The {{ViewTransition/domUpdated}} [=getter steps=] are to return [=this's=] [=Vi
 
                 1. [=Skip the page transition=] |transition| with a "{{TimeoutError}}" {{DOMException}}.
 
-            * If the promise was fulfilled, then:
+            * If the promise was resolved, then:
 
                 1. If |transition|'s [=ViewTransition/phase=] is "`done`", then return.
 
@@ -1121,13 +1117,17 @@ The {{ViewTransition/domUpdated}} [=getter steps=] are to return [=this's=] [=Vi
 
     1. [=Assert=]: |transition|'s [=ViewTransition/phase=] is [=phases/before=] "`dom-update-callback-called`".
 
-    1. Let |callbackPromise| be the result of [=/invoking=] |transition|'s [=ViewTransition/DOM update callback=].
+    1. Let |callbackPromise| be [=a new promise=] in |transition|'s [=relevant Realm=].
+
+        * If |transition|'s [=ViewTransition/DOM update callback=] is null, then resolve |callbackPromise|.
+
+        * Otherwise, let |callbackPromise| be the result of [=/invoking=] |transition|'s [=ViewTransition/DOM update callback=].
 
     1. Set |transition|'s [=ViewTransition/phase=] to "`dom-update-callback-called`".
 
     1. [=promise/React=] to |callbackPromise|:
 
-        * If |callbackPromise| was fulfilled, then [=resolve=] |transition|'s [=ViewTransition/DOM updated promise=].
+        * If |callbackPromise| was resolved, then [=resolve=] |transition|'s [=ViewTransition/DOM updated promise=].
 
         * If |callbackPromise| was rejected with reason |r|, then [=reject=] |transition|'s [=ViewTransition/DOM updated promise=] with |r|.