[cssom-view] Make scroll() et al be able to request smooth or instant scrolling

Author: Simon Pieters

cssom-view/Overview.html

@@ -272,12 +272,17 @@ <h2 id="common-infrastructure"><span class="secno">4 </span>Common Infrastructur
 <h3 id="scrolling"><span class="secno">4.1 </span>Scrolling</h3>
 
 <p>When a user agent is to <dfn id="perform-a-scroll">perform a scroll</dfn> of a scrolling box <var title="">box</var>, to a given position <var title="">position</var>, with a set of 
-steps <var title="">task</var>, and an associated element <var title="">element</var> the following steps must be run:
+steps <var title="">task</var>, an associated element <var title="">element</var> and a scroll behavior <var title="">behavior</var>, the following steps must be run:
 
 <ol>
  <li><p><a href="#concept-smooth-scroll-aborted" title="concept-smooth-scroll-aborted">Abort</a> any ongoing <a href="#concept-smooth-scroll" title="concept-smooth-scroll">smooth scroll</a> for <var title="">box</var>.
- <li><p>If <var title="">element</var> is not null and its computed value of the '<code><a href="#scroll-behavior">scroll-behavior</a></code>' property is
- '<code title="scroll-behavior-smooth"><a href="#scroll-behavior-smooth">smooth</a></code>', and the user agent honors the '<code><a href="#scroll-behavior">scroll-behavior</a></code>' property, then follow these substeps:
+ <li><p>If the user agent honors the '<code><a href="#scroll-behavior">scroll-behavior</a></code>' property and one of the following are true:
+  <ul>
+   <li><p><var title="">behavior</var> is <code title="">auto</code> and <var title="">element</var> is not null and its computed value of the '<code><a href="#scroll-behavior">scroll-behavior</a></code>'
+   property is '<code title="scroll-behavior-smooth"><a href="#scroll-behavior-smooth">smooth</a></code>'
+   <li><p><var title="">behavior</var> is <code title="">smooth</code>
+  </ul>
+  <p>...then follow these substeps:
   <ol>
    <li><p>Perform a <a href="#concept-smooth-scroll" title="concept-smooth-scroll">smooth scroll</a> of <var title="">box</var> to <var title="">position</var>.
    <li><p><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">Queue a task</a> to run <var title="">task</var>, unless a <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-task" title="concept-task">task</a> to
@@ -305,7 +310,15 @@ <h3 id="scrolling"><span class="secno">4.1 </span>Scrolling</h3>
 
 <h2 id="extensions-to-the-window-interface"><span class="secno">5 </span>Extensions to the <code title="">Window</code> Interface</h2>
 
-<pre class="idl">partial interface <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a> {
+<pre class="idl">enum <dfn id="scrollbehavior">ScrollBehavior</dfn> { "auto", "instant", "smooth" };
+
+dictionary <dfn id="scrolloptions">ScrollOptions</dfn> {
+  double x;
+  double y;
+  <a href="#scrollbehavior">ScrollBehavior</a> behavior = "auto";
+};
+
+partial interface <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a> {
   <a href="#mediaquerylist">MediaQueryList</a> <a href="#dom-window-matchmedia" title="dom-Window-matchMedia">matchMedia</a>(DOMString query);
   readonly attribute <a href="#screen">Screen</a> <a href="#dom-window-screen" title="dom-Window-screen">screen</a>;
 
@@ -318,9 +331,9 @@ <h2 id="extensions-to-the-window-interface"><span class="secno">5 </span>Extensi
   readonly attribute double <a href="#dom-window-pagexoffset" title="dom-Window-pageXOffset">pageXOffset</a>;
   readonly attribute double <a href="#dom-window-scrolly" title="dom-Window-scrollY">scrollY</a>;
   readonly attribute double p<a href="#dom-window-pageyoffset" title="dom-Window-pageYOffset">pageYOffset</a>;
-  void <a href="#dom-window-scroll" title="dom-Window-scroll">scroll(double x, double y)</a>;
-  void <a href="#dom-window-scrollto" title="dom-Window-scrollTo">scrollTo(double x, double y)</a>;
-  void <a href="#dom-window-scrollby" title="dom-Window-scrollBy">scrollBy(double x, double y)</a>;
+  void <a href="#dom-window-scroll" title="dom-Window-scroll">scroll</a>(double x, double y, optional <a href="#scrolloptions">ScrollOptions</a> options);
+  void <a href="#dom-window-scrollto" title="dom-Window-scrollTo">scrollTo</a>(double x, double y, optional <a href="#scrolloptions">ScrollOptions</a> options);
+  void <a href="#dom-window-scrollby" title="dom-Window-scrollBy">scrollBy</a>(double x, double y, optional <a href="#scrolloptions">ScrollOptions</a> options);
 
   // client
   readonly attribute double <a href="#dom-window-screenx" title="dom-Window-screenX">screenX</a>;
@@ -368,7 +381,7 @@ <h2 id="extensions-to-the-window-interface"><span class="secno">5 </span>Extensi
 
 <p>The <dfn id="dom-window-pageyoffset" title="dom-Window-pageYOffset"><code>pageYOffset</code></dfn> attribute must return the value returned by the <code>scrollY</code> attribute.</p>
 
-<p>When the <dfn id="dom-window-scroll" title="dom-Window-scroll"><code>scroll(<var title="">x</var>, <var title="">y</var>)</code></dfn> method is invoked these steps must be run:</p>
+<p>When the <dfn id="dom-window-scroll" title="dom-Window-scroll"><code>scroll(<var title="">x</var>, <var title="">y</var>, <var title="">options</var>)</code></dfn> method is invoked these steps must be run:</p>
 <ol>
  <li><p>If there is no <a href="#viewport">viewport</a>, abort these steps.
   <dl>
@@ -397,13 +410,13 @@ <h2 id="extensions-to-the-window-interface"><span class="secno">5 </span>Extensi
    <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> object.
   </ol>
  <li><p><a href="#perform-a-scroll">Perform a scroll</a> of the <a href="#viewport">viewport</a> to <var title="">position</var>, with the set of steps <var title="">task</var>, and the
- <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code>'s root element as the associated element, if there is one, or <code>null</code> otherwise.
+ <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code>'s root element as the associated element, if there is one, or <code>null</code> otherwise, and the scroll behavior being the value of the <code title="">behavior</code> dictionary member of <var title="">options</var>.
 </ol>
 
-<p>When the <dfn id="dom-window-scrollto" title="dom-Window-scrollTo"><code>scrollTo(<var title="">x</var>, <var title="">y</var>)</code></dfn> method is invoked, the user agent must act as if
+<p>When the <dfn id="dom-window-scrollto" title="dom-Window-scrollTo"><code>scrollTo(<var title="">x</var>, <var title="">y</var>, <var title="">options</var>)</code></dfn> method is invoked, the user agent must act as if
 the <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> method was invoked with the same arguments.</p>
 
-<p>When the <dfn id="dom-window-scrollby" title="dom-Window-scrollBy"><code>scrollBy(<var title="">x</var>, <var title="">y</var>)</code></dfn> method is invoked, the user agent must act as if
+<p>When the <dfn id="dom-window-scrollby" title="dom-Window-scrollBy"><code>scrollBy(<var title="">x</var>, <var title="">y</var>, <var title="">options</var>)</code></dfn> method is invoked, the user agent must act as if
 the <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> method was invoked with
 <var title="">x</var> plus <code title="dom-Window-scrollX"><a href="#dom-window-scrollx">scrollX</a></code>
 as first argument and <var title="">y</var> plus
@@ -604,9 +617,9 @@ <h2 id="extensions-to-the-element-interface"><span class="secno">7 </span>Extens
 <pre class="idl">partial interface <a class="external" href="http://dom.spec.whatwg.org/#element">Element</a> {
   <a href="#clientrectlist">ClientRectList</a> <a href="#dom-element-getclientrects" title="dom-Element-getClientRects">getClientRects</a>();
   <a href="#clientrect">ClientRect</a> <a href="#dom-element-getboundingclientrect" title="dom-Element-getBoundingClientRect">getBoundingClientRect</a>();
-  void <span title="dom-Element-scrollIntoView">scrollIntoView</span>(optional boolean top);
-  attribute double <a href="#dom-element-scrolltop" title="dom-Element-scrollTop">scrollTop</a>;
-  attribute double <a href="#dom-element-scrollleft" title="dom-Element-scrollLeft">scrollLeft</a>;
+  void <span title="dom-Element-scrollIntoView">scrollIntoView</span>(optional boolean top, optional <a href="#scrolloptions">ScrollOptions</a> options);
+  attribute (double or <a href="#scrolloptions">ScrollOptions</a>) <a href="#dom-element-scrolltop" title="dom-Element-scrollTop">scrollTop</a>;
+  attribute (double or <a href="#scrolloptions">ScrollOptions</a>) <a href="#dom-element-scrollleft" title="dom-Element-scrollLeft">scrollLeft</a>;
   readonly attribute double <a href="#dom-element-scrollwidth" title="dom-Element-scrollWidth">scrollWidth</a>;
   readonly attribute double <a href="#dom-element-scrollheight" title="dom-Element-scrollHeight">scrollHeight</a>;
   readonly attribute double <a href="#dom-element-clienttop" title="dom-Element-clientTop">clientTop</a>;
@@ -671,11 +684,12 @@ <h2 id="extensions-to-the-element-interface"><span class="secno">7 </span>Extens
 var exampleHeight = example.height;</code></pre>
 </div>
 
-<p>The <dfn id="dom-element-scrollintroview" title="dom-Element-scrollIntroView"><code>scrollIntoView(<var title="">top</var>)</code></dfn> method must run these steps:</p>
+<p>The <dfn id="dom-element-scrollintroview" title="dom-Element-scrollIntroView"><code>scrollIntoView(<var title="">top</var>, <var title="">options</var>)</code></dfn> method must run these steps:</p>
 <ol>
  <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a> terminate these steps.</li>
  <li><p><a href="#scroll-an-element-into-view" title="scroll an element into view">Scroll the element into view</a> with the
- <i title="">align to top flag</i> set if <var title="">top</var> is true or omitted.</li>
+ <i title="">align to top flag</i> set if <var title="">top</var> is true or omitted, and the scroll behavior being the value of the <code title="">behavior</code>
+ dictionary member of <var title="">options</var>.</li>
 </ol>
 
 <p>The <dfn id="dom-element-scrolltop" title="dom-Element-scrollTop"><code>scrollTop</code></dfn> attribute must return the result of running these steps:</p>
@@ -695,22 +709,25 @@ <h2 id="extensions-to-the-element-interface"><span class="secno">7 </span>Extens
 </ol>
 <p>When setting the <code title="dom-Element-scrollTop"><a href="#dom-element-scrolltop">scrollTop</a></code> attribute these steps must be run:</p>
 <ol>
- <li><p>Let <var title="">y</var> be the given value.</li>
+ <li><p>If the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, and the <code title="">y</code> dictionary member is not present, abort these steps.
+ <li><p>If the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, let <var title="">y</var> be the value of the <code title="">y</code> dictionary member. Otherwise,
+ let <var title="">y</var> be the given value.</li>
  <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a>, the
  element is the root element and the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in
  <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>, or the element has no overflow, terminate these
  steps.</li>
  <li><p>If the element is the root element invoke
  <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> with zero as first
- argument and <var title="">y</var> as second.</li>
+ argument and <var title="">y</var> as second, and, if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, the given value as the third argument.</li>
  <li><p>If the element is <a href="#the-html-body-element">the HTML <code>body</code> element</a>,
  the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>, and the element
  does not have any vertical overflow, invoke
  <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> with
  <code title="dom-Window-scrollX"><a href="#dom-window-scrollx">scrollX</a></code> as first
- argument and <var title="">y</var> as second.</li>
+ argument and <var title="">y</var> as second, and, if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, the given value as the third argument.</li>
  <li><p><a href="#scroll-an-element" title="scroll an element">Scroll the element</a> to
- <code title="dom-Element-scrollLeft"><a href="#dom-element-scrollleft">scrollLeft</a></code>,<var title="">y</var>.
+ <code title="dom-Element-scrollLeft"><a href="#dom-element-scrollleft">scrollLeft</a></code>,<var title="">y</var>, with the scroll behavior being the value of the <code title="">behavior</code> dictionary
+ member if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, or <code title="">auto</code> otherwise.
 </ol>
 
 <p>The <dfn id="dom-element-scrollleft" title="dom-Element-scrollLeft"><code>scrollLeft</code></dfn> attribute must return the result of running these steps:</p>
@@ -730,22 +747,27 @@ <h2 id="extensions-to-the-element-interface"><span class="secno">7 </span>Extens
 </ol>
 <p>When setting the <code title="dom-Element-scrollLeft"><a href="#dom-element-scrollleft">scrollLeft</a></code> attribute these steps must be run:</p>
 <ol>
- <li><p>Let <var title="">x</var> be the given value.</li>
+ <li><p>If the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, and the <code title="">x</code> dictionary member is not present, abort these steps.
+ <li><p>If the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, let <var title="">x</var> be the value of the <code title="">x</code> dictionary member. Otherwise,
+ let <var title="">x</var> be the given value.</li>
  <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a>, the
  element is the root element and the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in
  <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>, or the element has no overflow, terminate these
  steps.</li>
  <li><p>If the element is the root element invoke
  <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> with
- <var title="">x</var> as first argument and zero as second.</li>
+ <var title="">x</var> as first argument and zero as second, and, if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, the given value as the third
+ argument.</li>
  <li><p>If the element is <a href="#the-html-body-element">the HTML <code>body</code> element</a>,
  the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>, and the element
  does not have any vertical overflow, invoke
  <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> with
  <var title="">x</var> as first argument and
- <code title="dom-Window-scrollY"><a href="#dom-window-scrolly">scrollY</a></code> as second.</li>
+ <code title="dom-Window-scrollY"><a href="#dom-window-scrolly">scrollY</a></code> as second, and, if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, the given value as the third
+ argument.</li>
  <li><p><a href="#scroll-an-element" title="Scroll an element">Scroll the element</a> to
- <var title="">x</var>,<code title="dom-Element-scrollTop"><a href="#dom-element-scrolltop">scrollTop</a></code>.
+ <var title="">x</var>,<code title="dom-Element-scrollTop"><a href="#dom-element-scrolltop">scrollTop</a></code>, with the scroll behavior being the value of the <code title="">behavior</code> dictionary
+ member if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, or <code title="">auto</code> otherwise.
 </ol>
 
 <p>The <dfn id="dom-element-scrollwidth" title="dom-Element-scrollWidth"><code>scrollWidth</code></dfn> attribute must return the result of running these steps:</p>
@@ -827,7 +849,7 @@ <h3 id="the-getclientrects-and-getboundingclientrect-methods"><span class="secno
 <h3 id="element-scrolling-members"><span class="secno">7.2 </span><code title="">Element</code> Scrolling Members</h3>
 
 <p>To <dfn id="scroll-an-element-into-view">scroll an element into view</dfn>, optionally with an
-<i title="">align to top flag</i> set, means to run these steps for each
+<i title="">align to top flag</i> set, and with a scroll behavior <var title="">behavior</var>, means to run these steps for each
 ancestor element or <a href="#viewport">viewport</a> that establishes a
 scrolling box <var title="">box</var>, in order of innermost to outermost scrolling box:</p>
 
@@ -884,12 +906,12 @@ <h3 id="element-scrolling-members"><span class="secno">7.2 </span><code title=""
    </dd>
   </dl>
  </li>
- <li><p><a href="#perform-a-scroll">Perform a scroll</a> of <var title="">box</var> to <var title="">position</var>, with the set of steps <var title="">task</var>, and
- <var title="">element</var> as the associated element.
+ <li><p><a href="#perform-a-scroll">Perform a scroll</a> of <var title="">box</var> to <var title="">position</var>, with the set of steps <var title="">task</var>,
+ <var title="">element</var> as the associated element and <var title="">behavior</var> as the scroll behavior.
 
 </ol>
 
-<p>To <dfn id="scroll-an-element">scroll an element</dfn> to <var title="">x</var>,<var title="">y</var> means to:</p>
+<p>To <dfn id="scroll-an-element">scroll an element</dfn> to <var title="">x</var>,<var title="">y</var> with a scroll behavior <var title="">behavior</var> means to:</p>
 
 <ol>
  <li><p>Let <var title="">element</var> be the element.
@@ -927,8 +949,8 @@ <h3 id="element-scrolling-members"><span class="secno">7.2 </span><code title=""
    <code title="event-scroll">scroll</code> at the element.</li>
   </ol>
 
- <li><p><a href="#perform-a-scroll">Perform a scroll</a> of <var title="">box</var> to <var title="">position</var>, with the set of steps <var title="">task</var>, and
- <var title="">element</var> as the associated element.
+ <li><p><a href="#perform-a-scroll">Perform a scroll</a> of <var title="">box</var> to <var title="">position</var>, with the set of steps <var title="">task</var>,
+ <var title="">element</var> as the associated element and <var title="">behavior</var> as the scroll behavior.
 
 </ol>