Overview.bs

<pre class='metadata'>
Title: CSS Scroll Snap Module Level 2
Group: csswg
Shortname: css-scroll-snap
Level: 2
Status: ED
Implementation Report: https://wpt.fyi/results/css/css-scroll-snap
Work Status: Testing
ED: https://drafts.csswg.org/css-scroll-snap-2/
Editor: Matt Rakow, Microsoft, w3cid 62267
Editor: Jacob Rossi, Microsoft, w3cid 45616
Editor: Tab Atkins-Bittner, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Adam Argyle, Google, https://nerdy.dev, w3cid 112669
Abstract: This module contains features to control panning and scrolling behavior with “snap positions”.
Status Text:
 A test suite and an implementation report will be produced during the
 CR period.
</pre>

Introduction {#intro}
=====================

	<em>This section is not normative.</em>

	<em>This is currently a draft spec over Scroll Snap 1.</em>

	Scroll experiences don't always start at the beginning. Interactions with
	carousels, swipe controls, and listviews often start somewhere in the middle,
	and each require JavaScript to set this position on page load.
	By enabling CSS to specify this scroll start position,
	both users, page authors and browsers benefit.

	In addition to setting an initial scroll position,
	developers need insights and events into Scroll Snap.
	Events like which element is snapped on which axis,
	when the snap event is changing,
	when snap completes and conveniences for
	snapping to children programmatically.

  First Layout
  ------------

  This event should follow the Animation code path. When animation objects are created and fire events, this is when a box has it's first layout.

<!--
████████ ██     ██    ███    ██     ██ ████████  ██       ████████  ██████
██        ██   ██    ██ ██   ███   ███ ██     ██ ██       ██       ██    ██
██         ██ ██    ██   ██  ████ ████ ██     ██ ██       ██       ██
██████      ███    ██     ██ ██ ███ ██ ████████  ██       ██████    ██████
██         ██ ██   █████████ ██     ██ ██        ██       ██             ██
██        ██   ██  ██     ██ ██     ██ ██        ██       ██       ██    ██
████████ ██     ██ ██     ██ ██     ██ ██        ████████ ████████  ██████
-->

Motivating Examples {#examples}
===============================

    <div class="example">
        A carousel that starts in the middle:

        <pre class="lang-css">
            .carousel {
                overflow-inline: auto;
                scroll-start: center;
            }
        </pre>

        <pre class="lang-html">
            &lt;div class="carousel">
                &lt;img src="img1.jpg">
                &lt;img src="img2.jpg">
                &lt;img src="img3.jpg">
                &lt;img src="img4.jpg">
                &lt;img src="img5.jpg">
            &lt;/div>
        </pre>

        <!-- <figure>
            <img src="images/element_snap_positions.png" alt="">

            <figcaption>
                The layout of the scroll container’s contents in the example.
                The snapport is represented by the red rectangle, and the snap area is represented by the yellow rectangle.  Since the scroll-snap-align is “center” in the inline (horizontal) axis, a snap position is established at each scroll position which aligns the X-center of the snapport (represented by a red dotted line) with the X-center of a snap area (represented by a yellow dotted line).
            </figcaption>
        </figure> -->
    </div>

    <div class="example">
        A search bar is available when the user scrolls back to the top:

        <pre class="lang-css">
            .scrollport {
                overflow-block: auto;
            }

            main {
                scroll-start-target: auto;
            }
        </pre>

        <pre class="lang-html">
            &lt;div class="scrollport">
                &lt;nav>
                    ...
                &lt;/nav>
                &lt;main>
                    ...
                &lt;/main>
            &lt;/div>
        </pre>

        <!-- <figure>
            <img src="images/element_snap_positions.png" alt="">

            <figcaption>
                The layout of the scroll container’s contents in the example.
                The snapport is represented by the red rectangle, and the snap area is represented by the yellow rectangle.  Since the scroll-snap-align is “center” in the inline (horizontal) axis, a snap position is established at each scroll position which aligns the X-center of the snapport (represented by a red dotted line) with the X-center of a snap area (represented by a yellow dotted line).
            </figcaption>
        </figure> -->
    </div>

Setting Where Scroll Starts {#properties-on-the-scroll-container}
=================================================================

<!-- BIG TEXT: SCROLL START -->

The 'scroll-start' property {#scroll-start}
-------------------------------------------

	<pre class="propdef shorthand">
	Name: scroll-start
	Value: [ auto | start | end | center | left | right | top | bottom | <<length-percentage [0,∞]>> ]{1,2}
	</pre>

	This property is a shorthand property that sets all of the scroll-start-* longhands in one declaration.
	The first value defines the scroll starting point in the block axis,
	the second sets it in the inline axis. If the second value is omitted, it defaults to ''scroll-start/start''. If ''scroll-start-target'' is set on any child, ''scroll-start'' is not used, in favor of using the element as the offset.

	Values are defined as follows:

	<dl dfn-type=value dfn-for="scroll-start, scroll-start-x, scroll-start-y, scroll-start-block, scroll-start-inline">
		<dt><dfn>auto</dfn>
		<dd>
			...

		<dt><dfn><<length-percentage [0,∞]>></dfn>
		<dd>
			...

			Negative values are invalid.
			Values corresponding to a length greater than the width/height of the scrollport
			are valid,
			but clamped to the width/height of the scrollport.

		<dt><dfn>start</dfn>
		<dt><dfn>center</dfn>
		<dt><dfn>end</dfn>
		<dd>
			Equivalent to ''0%'', ''50%'', and ''100%'', respectively.
	</dl>

<h4 id="display-none-behavior">Interaction with ''display: none'' and initial creation</h4>
  Same behavior that animations follow with <a href="#first-layout">first layout</a>.

<h4 id="slow-page-load-behavior">Slow page loading or document streaming behavior</h4>
  TODO

<h4 id="fragment-navigation-behavior">Interaction with ''fragment navigation''</h4>
  TODO
  If the scrollport has a in-page '':target'' via a URL fragment or a previous scroll position, then ''scroll-start'' is unused. Existing target logic should go unchanged. This makes ''scroll-start'' a soft request in the scroll position resolution routines.  

<h4 id="place-content-behavior">Interaction with ''place-content''</h4>
  TODO  
  Side note: While ''place-content'' can make a scroller appear to start in the center
  or end, no browser supports it and it appears complicated to resolve.

<h4 id="find-in-page-behavior">Interaction with "find in page"</h4>
  TODO

<h4 id="scroll-snap-container-behavior">Interaction ''scroll-snap'' containers</h4>
  This effectively will layout and start scroll at the snapped child, thus negating / cancelling ''scroll-start''. ''scroll-start'' will only work if nothing else has effected the scroll position.

<h4 id="nested-scrollers">Nested scrollers with ''scroll-start''</h4>
  Should follow patterns that scroll snap has set.

<h4 id="toggling-display-none">Interaction when ''display'' is toggled</h4>
  Same behavior that animations follow with ''first layout''.

<h4 id="rtl">Interaction with RTL and LTR</h4>
  Logical properties are offered for length offsets that should be flow relative. Furthermore, the ''end'' and ''start'' keywords are always logical.

The 'scroll-start-target' property {#scroll-start-target}
-------------------------------------------

  <pre class="propdef shorthand">
  Name: scroll-start-target
  Value: [ none | auto ]{1,2}
  </pre>

  This property is a shorthand property that sets all of the scroll-start-target-* longhands in one declaration.
  The first value defines the scroll starting point in the block axis,
  the second sets it in the inline axis.
  If the second value is omitted, it defaults to ''none''.

  Values are defined as follows:

  <dl dfn-type=value dfn-for="scroll-start-target, scroll-start-target-x, scroll-start-target-y, scroll-start-target-block, scroll-start-target-inline">
    <dt><dfn>none</dfn>
    <dd>Element is not a ''scroll-start-target''.
    <dt><dfn>auto</dfn>
    <dd>Element is used to calculate the ''scroll-start'' position, 
    taking into account ''scroll-padding'' or ''scroll-margin'' ,
    same as a ''scroll-snap'' target.
  </dl>

Styling Snapped Items {#todo}
=============================

The Snapped-element Pseudo-class: '':snapped'' {#snapped}
-------------------------------------------------------

The <dfn selector>:snapped</dfn> pseudo-class matches any scroll snap targets,
regardless of axis.
The longform physical and logical pseudo-class selectors
allow for more finite snapped children styling
as they can target an individual axis.

More specific options are defined as follows:

	<dl dfn-type=selector>
		<dt><dfn>:snapped-x</dfn>
		<dd>
			Matches the child snapped on the horizontal axis.

		<dt><dfn>:snapped-y</dfn>
		<dd>
			Matches the child snapped on the vertical axis.

		<dt><dfn>:snapped-inline</dfn>
		<dd>
			Matches the child snapped on the [=inline=] axis.

		<dt><dfn>:snapped-block</dfn>
		<dd>
			Matches the child snapped on the [=block=] axis.
	</dl>

Note: <a href="https://github.com/w3c/csswg-drafts/issues/6985#issuecomment-1049036401">Issue #6985</a><br>
Need to figure out resolution of the initial frame.

Snap Events {#snap-events}
===================

<!--
████████ ██     ██ ████████ ██    ██ ████████  ██████
██       ██     ██ ██       ███   ██    ██    ██    ██
██       ██     ██ ██       ████  ██    ██    ██
██████   ██     ██ ██████   ██ ██ ██    ██     ██████
██        ██   ██  ██       ██  ████    ██          ██
██         ██ ██   ██       ██   ███    ██    ██    ██
████████    ███    ████████ ██    ██    ██     ██████
-->

{{snapChanged}} and {{snapChanging}} {#snapchanged-and-snapchanging}
--------------------------------------------

	CSS scroll snap points are often used as a mechanism to
	create scroll interactive "selection" components,
	where selection is determined with JavaScript intersection observers
	and a scroll end guestimate. By creating a built-in event,
	the invisible state will become actionable,
	at the right time, and always correct.

	<table class="data" id="eventhandlers">
		<thead>
			<tr>
				<th>Event handler
				<th>Event handler event type
		<tbody>
			<tr>
				<th><dfn event>snapChanged</dfn>
				<td>{{scroll!!event}}
			<tr>
				<th><dfn event>snapChanging</dfn>
				<td>{{scroll!!event}}
	</table>
	<h4>SnapEvents</h4>
	<pre class="idl">
			[Exposed=Window]
			interface SnapEvent : Event {
				constructor(DOMString type, optional SnapEventInit eventInitDict = {});
				readonly attribute EventTarget? target;
				readonly attribute SnapTargetList snappedTargets;
				readonly attribute SnapTargetList snapTargets;
				readonly attribute boolean invokedProgrammatically;
				readonly attribute boolean smoothlyScrolled;
			};

			[Exposed=Window]
			interface SnapTargetList {
			    readonly attribute SnapTargetArray x;
			    readonly attribute SnapTargetArray y;
			};

			[Exposed=Window]
			interface SnapTargetArray {
			    readonly attribute unsigned long length;
			    getter EventTarget? item (unsigned long index);
			};

			dictionary SnapEventInit : EventModifierInit {
			    sequence&lt;EventTarget> snappedTargetsX = [];
			    sequence&lt;EventTarget> snappedTargetsY = [];
			    sequence&lt;EventTarget> snapTargetsListX = [];
			    sequence&lt;EventTarget> snapTargetsListY = [];
			};
	</pre>

	<dl>
		<dt><code>SnapEvent . target</code></dt>
		<dd>
			This is the scroll container of the snapped-to element.
		</dd>
		<dt><code>SnapEvent . snappedTargets</code></dt>
		<dd>
			An object with 2 keys for each axis, each key returns an array of snapped targets.
		</dd>
		<dt><code>SnapEvent . snapTargets</code></dt>
		<dd>
			An object with 2 keys for each axis, each key returns an array of the aggregated snap children.
		</dd>
		<dt><code>SnapEvent . invokedProgrammatically</code></dt>
		<dd>
			A boolean informing developers if a user or script invoked scroll that caused <a>snapChanged</a>.
		</dd>
		<dt><code>SnapEvent . smoothlyScrolled</code></dt>
		<dd>
			A boolean informing developers if the snap change was instant or interpolated.
		</dd>
	</dl>

	<h4> snapChanged </h4>

		The event is dispatched when a new snap target has been snapped to, providing what caused it.
		It should be dispatched:

		*	if user scroll interaction has ended and a new item has been rested on. If a user is still touching the screen or the touchpad, this event should not fire, even if the scroll position is exactly at a snapped element's position.
		*	if animations or transitions change the snapped style of the container or children, IF they have in fact changed the snap target.

		<table>
		<tr><th>Type</th><td><strong><code>snapChanged</code></strong></td></tr>
		<tr><th>Interface</th><td>{{SnapEvent}}</td></tr>
		<tr><th>Sync / Async</th><td>Async</td></tr>
		<tr><th>Bubbles</th><td>Yes</td></tr>
		<tr><th>Trusted Targets</th><td><code>Element</code></td></tr>
		<tr><th>Cancelable</th><td>No</td></tr>
		<tr><th>Composed</th><td>Yes</td></tr>
		<tr><th>Default action</th><td>None</td></tr>
		<tr><th>Context<br/>(trusted events)</th><td><ul>
													 <li>{{Event}}.{{Event/target}} : scroll container of the snapped-to element</li>
													 <li>{{SnapEvent}}.{{snappedTargets}} : an object with 2 keys for each axis, each key returns an array of snapped targets</li>
													 <li>{{SnapEvent}}.{{snapTargets}} : an object with 2 keys for each axis, each key returns an array of the aggregated snap children</li>
													 <li>{{SnapEvent}}.{{invokedProgrammatically}} : a boolean informing developers if a user or script invoked scroll that caused <a>snapChanged</a></li>
													 <li>{{SnapEvent}}.{{smoothlyScrolled}} : a boolean informing developers if the snap change was instant or interpolated</li>
													 </ul></td></tr>
		</table>

	<h4> snapChanging </h4>

		Should fire every time, and as soon as, the UA has determined a new snap child until the new child is snapped to.

		<table>
		<tr><th>Type</th><td><strong><code>snapChanging</code></strong></td></tr>
		<tr><th>Interface</th><td>{{SnapEvent}}</td></tr>
		<tr><th>Sync / Async</th><td>Async</td></tr>
		<tr><th>Bubbles</th><td>Yes</td></tr>
		<tr><th>Trusted Targets</th><td><code>Element</code></td></tr>
		<tr><th>Cancelable</th><td>No</td></tr>
		<tr><th>Composed</th><td>Yes</td></tr>
		<tr><th>Default action</th><td>None</td></tr>
		<tr><th>Context<br/>(trusted events)</th><td><ul>
													 <li>{{Event}}.{{Event/target}} : scroll container of the snapped-to element.</li>
													 <li>{{SnapEvent}}.{{snappedTargets}}
													 <li>{{SnapEvent}}.{{snapTargets}} : an object with 2 keys for each axis, each key returns an array of the aggregated snap children.</li>
													 <li>{{SnapEvent}}.{{invokedProgrammatically}} : a boolean informing developers if a user or script invoked scroll that caused <a>snapChanged.</a></li>
													 <li>{{SnapEvent}}.{{smoothlyScrolled}} : a boolean informing developers if the snap change was instant or interpolated.</li>
													 </ul></td></tr>
		</table>

<!--
██        ███████  ██    ██  ██████   ██     ██    ███    ██    ██ ████████   ██████
██       ██     ██ ███   ██ ██    ██  ██     ██   ██ ██   ███   ██ ██     ██ ██    ██
██       ██     ██ ████  ██ ██        ██     ██  ██   ██  ████  ██ ██     ██ ██
██       ██     ██ ██ ██ ██ ██   ████ █████████ ██     ██ ██ ██ ██ ██     ██  ██████
██       ██     ██ ██  ████ ██    ██  ██     ██ █████████ ██  ████ ██     ██       ██
██       ██     ██ ██   ███ ██    ██  ██     ██ ██     ██ ██   ███ ██     ██ ██    ██
████████  ███████  ██    ██  ██████   ██     ██ ██     ██ ██    ██ ████████   ██████
-->

Appendix A: Longhands {#longhands}
==================================

The physical and logical longhands (and their shorthands)
interact as defined in [[!CSS-LOGICAL-1]].

Physical Longhands for 'scroll-start' {#scroll-start-longhands-physical}
----------------------------------------------------------------------

	<pre class="propdef">
	Name: scroll-start-x, scroll-start-y
	Value: auto | start | end | center | <<length-percentage [0,∞]>>
	Initial: auto
	Applies to: <a>scroll containers</a>
	Inherited: no
	Logical property group: scroll-start
	Percentages: relative to the corresponding axis of the scroll container’s scrollport
	Computed value: the keyword ''scroll-start/auto'' or a computed <<length-percentage>> value
	Animation type: by computed value type
	</pre>

	...

Flow-relative Longhands for 'scroll-start'  {#scroll-start-longhands-logical}
--------------------------------------------------------------------------

	<pre class="propdef">
	Name: scroll-start-inline, scroll-start-block
	Value: auto | start | end | center | <<length-percentage [0,∞]>>
	Initial: auto
	Applies to: <a>scroll containers</a>
	Inherited: no
	Logical property group: scroll-start
	Percentages: relative to the corresponding axis of the scroll container’s scrollport
	Computed value: the keyword ''scroll-start/auto'' or a computed <<length-percentage>> value
	Animation type: by computed value type
	</pre>

	...
Flow-relative Longhands for 'scroll-start-target'  {#scroll-start-target-longhands-logical}
--------------------------------------------------------------------------

	<pre class="propdef">
	Name: scroll-start-target-block, scroll-start-target-inline
	Value: auto | none
	Initial: none
	Applies to: all elements
	Inherited: no
	Logical property group: scroll-start-target
	Percentages: n/a
	Computed Value: either of the keywords "none" or "auto"
	Animation type: not animatable
	</pre>

	...

Physical Longhands for 'scroll-start-target' {#scroll-start-target-longhands-physical}
----------------------------------------------------------------------

	<pre class="propdef">
	Name: scroll-start-target-x, scroll-start-target-y
	Value: none | auto
	Initial: none
	Applies to: all elements
	Inherited: no
	Logical property group: scroll-start-target
	Percentages: n/a
	Computed value: either of the keywords "none" or "auto"
	Animation type: not animatable
	</pre>

	...