Initial specification draft

Author: bgirard

index.bs

@@ -0,0 +1,115 @@
+<pre class='metadata'>
+Title: CSS Scroll Boundary Behavior Module Level 1
+Shortname: scroll-boundary-behavior
+Level: 1
+Status: CG-DRAFT
+Work Status: Exploring
+Group: WICG
+URL: https://wicg.github.io/scroll-boundary-behavior/
+Editor: Benoit Girard, Facebook, bgirard@fb.com
+Abstract: This module defines 'scroll-boundary-behavior' to control the behavior when a scroll position of a <a>potentially scrollable</a> element reaches the edge of the <a>scrollport</a>.
+Abstract: This allows content authors to hint that the <a>boundary default actions</a>,
+Abstract: such as scroll chaining and overscroll, should not be triggered.
+</pre>
+
+<pre class='anchors'>
+urlPrefix: https://www.w3.org/TR/css-display-3/
+    type: dfn; text: containing block chain
+urlPrefix: https://www.w3.org/TR/cssom-view-1/
+    type: dfn; text: potentially scrollable
+urlPrefix: https://www.w3.org/TR/uievents/
+    type: dfn; text: default action
+    type: dfn; text: default actions
+url: https://dom.spec.whatwg.org/#dom-event-preventdefault
+    type: dfn; text: preventDefault
+</pre>
+
+Introduction {#intro}
+=====================
+
+<em>This section is not normative.</em>
+
+A content author does not necessarily want <a>scroll chaining</a> to occur for all scrollable containers. Some scroll containers may be part of a <a>containing block chain</a> but may serve a different logical purpose in the document and may want to prevent scrolling from continuing up the <a>scroll chain</a>. To achieve this, a content author will install event listeners without the passive flag set and will use <a>preventDefault</a> when there is a risk that scroll chaining will occur. This is detrimental for the following reasons:
+* The user agent may in the future introduce new input methods for scrolling that are not supported by the content author's event listeners.
+* A non passive event listener will delay scrolling because the user agent will have to wait for the result of the event listener to determine if <a>preventDefault</a> was called causing increased scroll latency.
+* When scrolling is performed near the edge of the <a>scroll boundary<a> the <a>default action</a> may cause both scrolling to the edge of the scrollable container and a <a>boundary default action</a>. Calling <a>preventDefault</a> will not only cancel the <a>boundary default action</a> but also the scroll to the edge of the <a>scrollport</a>.
+* The <a>default action</a> for the event may also provide additional behavior that the author does not want to cancel such as an overscroll affordance. <a>preventDefault</a> doesn't allow the content author to cancel only some of the <a>default actions</a> such as scroll chaining.
+
+Thus, it is not possible for a content author to control <a>scroll chaining</a> and overscroll in a robust, performant and forward compatible way. The <a>scroll-boundary-behavior</a> property fixes this shortcoming.
+
+<pre class=example>
+A 'position: fixed' left navigation bar may not want to hand off scrolling to the
+document but does not want to prevent native overscroll affordances.
+</pre>
+
+Scroll chaining and boundary default actions {#scroll-chaining-and-boundary-default-actions}
+==========================
+
+<em>Operating Systems have rules for scrolling such as scroll chaining and overscroll affordances. This specification does not mandate if and how scroll chaining or overscroll affordances be implemented. This specification only allows the content author to disable them if any are implemented.</em>
+
+<dfn>Scroll chaining</dfn> is when scrolling is propagated from one scrollable container to an ancestor scrollable container following the <a>scroll chain</a>. Typically scroll chaining is performed starting at the event target recursing up the <a>containing block chain</a>. When a <a>potentially scrollable</a> element in this chain receives a scrollable event or gesture it may act on it and/or pass it up the chain. Chaining typically occurs when the <a>scrollport</a> has reached its boundary.
+
+A <dfn>scroll chain</dfn> is the order in which scrolling is propagated from one scrollable container to another.
+
+<dfn>Scroll boundary</dfn> refers to when the scroll position of a <a>potentially scrollable</a> element reaches the edge of the <a>scrollport<a>. In the non-scrollable case the element is always considered to be at the scroll boundary. 
+
+<dfn>Boundary default action</dfn> refers to the user-agent-defined <a>default action</a> performed when scrolling against the edge of the <a>scrollport</a>. This may be scroll chaining, showing an overscroll affordance and/or performing a navigation action.
+
+Issue(WICG/scroll-boundary-behavior#4): Should this specification apply to a scrollable element, potentially scrollable element or any element.
+
+Overview {#overview}
+==========================
+
+This module introduces control over the behavior of a <a>potentially scrollable</a> element when its <a>scrollport</a> reaches the boundary of its scroll box. It allows the content author to specify that a <a>potentially scrollable</a> element must prevent scroll chaining and/or overscroll affordances.
+
+Scroll Boundary Behavior Properties {#scroll-boundary-behavior-properties}
+==========================
+
+These properties specify how a <a>potentially scrollable</a> element must behave when scrolling. A element that is not <a>potentially scrollable</a> must accept but ignore the values of this property. This property must be applied to all input methods supported by the user agent.
+
+Note: This property should provide guarantees that are, at least, as strong as <a>preventDefault</a> for preventing both scroll chaining and overscroll. Doing otherwise would cause content authors to use <a>preventDefault</a> instead.
+
+<pre class=propdef>
+Name: scroll-boundary-behavior-x, scroll-boundary-behavior-y
+Value: ''contain'' | ''none'' | ''auto''
+Initial: ''auto''
+Applies to: <a>potentially scrollable</a> elements
+Inherited: no
+Percentages: N/A
+Media: visual
+Computed value: see individual properties
+Animatable: no
+Canonical order: <abbr title="follows order of property value definition">per grammar</abbr>
+</pre>
+
+The 'scroll-boundary-behavior-x' property specifies the behavior of the 'scroll-boundary-behavior' in the horizontal direction and the 'scroll-boundary-behavior-y' property specifies the handling of the 'scroll-boundary-behavior' in the vertical direction. When scrolling is performed along both the horizontal and vertical axes at the same time, the 'scroll-boundary-behavior' of each respective axis should be considered independently.
+
+<pre class=propdef>
+Name: scroll-boundary-behavior
+Value: ''contain'' | ''none'' | ''auto''
+Initial: ''auto''
+Applies to: <a>potentially scrollable</a> elements
+Inherited: no
+Media: visual
+Computed value: see individual properties
+Animatable: no
+Canonical order: <abbr title="follows order of property value definition">per grammar</abbr>
+</pre>
+
+Values have the following meanings:
+
+<dl dfn-for="scroll-boundary-behavior, scroll-boundary-behavior-x, scroll-boundary-behavior-y" dfn-type="value">
+  <dt><dfn>contain</dfn>
+  <dd>
+    This value indicates that the element must not perform <a>scroll chaining</a> to any ancestor along the scroll chain regardless of whether the scroll originated at this element or one of its descendants.
+  <dt><dfn>none</dfn>
+  <dd>
+    This value implies the same behavior as <a>contain</a> and in addition this element must also not show any overscroll affordances.
+  <dt><dfn>auto</dfn>
+  <dd>
+    This value indicates that the element should perform the usual <a>default action</a> with respect to both <a>scroll chaining</a> and overscroll.
+</dl>
+
+Note: In the case where a user agent does not implement scroll chaining and overscroll affordances, these values will have no side effects for a compliant implementation.
+
+Issue(WICG/scroll-boundary-behavior#6): Right now the specification does not mention programmatic scrolling. How should it be handled?