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, Invited Expert, 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 programatically.

  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 ]
  </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>

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

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
	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
	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>

	...