CSS Scroll Snap Diff Annotations

This is a list of differences between the CSS Scroll Snap Module as maintained by Matt Rakow and the CSS Scroll Snap Module Change Proposal maintained by Tab and fantasai.

At the most recent F2F the group agreed to accept a bunch of changes from Fantasai and Tab. Microsoft asked for some time to do a final review.

While we don't have immediate plans to implement, it would be nice to get the specification stable soon. Can we set a deadline for review, after which we go ahead with the resolution from the meeting?

I'm not sure how much time is necessary. Microsoft?

Dean Jackson, www-style, 10 December 2015

Suggested Process

In the interests of F2F time, we are requesting that the WG adopt the following rapid-decision format for resolution of these changes:

  1. First, a quick presentation of the change.
  2. Second, a few minutes for people to peruse the change (if necessary), and to enter a straw poll in IRC:
    +1 I agree with adopting the new wording.
    -1 I disagree with adopting the new wording.
    +2 I think the new wording is better than the old one, but I would like to see further improvements, which I will file as a follow-up issue.
    0 I need more time to decide, please revisit this after the break (during which I promise to review the change, obviously).
    T I need more time to decide, please revisit this tomorrow morning (at which point I promise to have an opinion or a damned good reason outside of my control to ask for more time).
    Abstentions shall be recorded by omission. The chairs will ask by a show of hands if anyone needs another minute or two to decide, and otherwise swiftly end the poll.
  3. If the straw poll results are reasonably conclusive, the chairs will record a resolution to adopt the change. If they are not conclusive, the chairs will open discussion.

Our goal in presenting this list is to close, by the end of the F2F, on all outstanding technical and editorial issues, and by formally adopting the exact wording changes necessary to resolve these issues, remove the need for any further spec-editor discretion in updating the spec. This will allow somebody who actually has the time (i.e. not Matt Rakow) to make the edits so that the spec can be 100% up-to-date by next week rather than sometime in the next six months maybe.

(Of course, not all of these edits are perfect, but insofar as they are better we would like the CSSWG to formally adopt them. Further review, edits, and improvements can then be made once there is a fully up-to-date consensus spec on /TR.)

Specific Changes

Title Change Merged
Robert O'Callahan requested a change to the name of the spec, because (with his requested changes) it's not about snappoing points, but about snapping box edges. (Issue 43 filed December 2013)

CSS Scroll Snap Points Module Level 1

http://www.w3.org/TR/css-snappointsscroll-snap-1/

Terminology Change: Scroll Snap Area Merged
Tab and I introduced the term “scroll snap area” to refer to the rectangle being aligned within the viewport. Matt's version uses “scroll snap margin” to refer to this area. However the term “scroll snap margin” is misleading because the margin area of a box is the area inside the margin edges and outside its border box whereas the area of concern here includes the entire area of the defined rectangle.
s/scroll snap margin/scroll snap area/g;
Error: border-box vs. margin-box Partially Merged
Matt's spec parenthetically mentions that the scroll snap area defaults to the margin box. However, the spec actually defines that it defaults to the border box. This change corrects this error.

Snap positions can be specified as a particular alignment (scroll-snap-align) of an element’s scroll snap area (scroll-snap-margin, defaulting to its margin box its border box, as modified by scroll-snap-margin) within …

(In the most recent changes, “margin box” has been replaced with “border box”, but the resulting text is awkward.)
Move: Undefined Animations and Physics Merged
There is a statement in the definition of scroll-snap-type that, since it applies generally to scroll-snapping, we felt belonged in Overview section that defines the overall scroll-snapping model rather than specifically in scroll-snap-type.

It The CSS Scroll Snap Module intentionally does not specify nor mandate any precise animations or physics used to enforce snap positions; this is left up to the user agent.

Specifying Scroll-snap Axes Partially Merged
The WG resolved on 2 December 2015 to specify, on a property applied to the scroll container, which axis(es) would be honored in scroll snapping. he following changes implement this:
Name: scroll-snap-type
Value none | [ proximity | mandatory ] || [ x | y | block | inline | both ]

The scroll-snap-type property defines … and which axes are considered.

The strictness values (none, proximity, mandatory) specify how strictly snap positions are enforced on the scroll container (by forcing an adjustment to the scroll offset). Values are defined as follows:

The axis values specify what axis(es) are affected by snap positions, and whether snap positions are evaluated independently per axis, or together as a 2D point. Values are defined as follows:

x
The scroll container axis-snaps to snap positions in its horizontal axis only.
y
The scroll container axis-snaps to snap positions in its vertical axis only.
block
The scroll container axis-snaps to snap positions in its block axis only.
inline
The scroll container axis-snaps to snap positions in its inline axis only.
both
The scroll container axis-snaps to snap positions in both of its axises independently (potentially snapping to different elements in each axis).

If no axis value is specified, then the axis is automatically computed:

There remains an open issue on whether there should be longhands for this and if so, what the shorthand/longhand names should be.

Trapping Merged
In Sapporo, the WG resolved (27 October 2015) to have non-none values of the scroll-snap-type property “trap” descendant scroll snap positions in order to provide authors a way of blocking upward propagation of snap positions within a box’s content. (Issue 82 resolved TPAC 2015)

In order to fix this, Tab and I adjusted the definitions of the scroll-snap-type strictness values as follows:

none

If specified on a scroll container,

If specified on a non-scroll container, this value has no effect.

proximity

If specified on a scroll container,

If specified on a non-scroll container, this value “traps” descendant boxes’ snap positions, preventing them from affecting any ancestor scroll containers.

mandatory
If specified on a scroll container,

If specified on a non-scroll container, this value “traps” descendant boxes’ snap positions, preventing them from affecting any ancestor scroll containers.

We also introduced the term “scroll snap container” (“snap container” for short) to represent the scroll container associated to a particular snap position. This term allows us to give a straightforward definition, in one single place, that accounts for the fact that the relevant box is found along the containing block chain, and also that it is intercepted by any intervening elements with a none-none value for scroll-snap-type.

The scroll-snap-type property specifies whether a scroll container is a scroll snap container

A box captures snap positions if it is a scroll container or has a value other than none for scroll-snap-type. If a box’s nearest snap-position capturing ancestor on its containing block chain is a scroll container with a non-none value for scroll-snap-type, then that is the box’s scroll snap container. Otherwise, the box has no scroll snap container, and its specified snap positions do not trigger snapping.

This also allows the following fix for some imprecise wording in the definition of scroll-snap-align:

The scroll-snap-align property specifies how an element’s scroll snap margin should align with its ancestor scroll container’s snap alignment container the box’s snap position as an alignment of its snap area (as the alignment subject) within its snap container’s snapport (as the alignment container).

RFC2119 Terminology Merged
As much as I like the word “guarantee” in the description of mandatory, it seems more appropriate to use RFC2119’s “requirement”.

… the scroll container is guaranteed required

Author Warning wrt Mandatory Snapping Merged
Based on CSSWG discussions, we added a warning to authors about how despite our best efforts, they can still totally screw up the accessibility of the document, and should therefore avoid doing that.

Authors should use mandatory snap positions with consideration of varyingly-sized screens and (if applicable) varying-sized content. In particular, although access to snapped elements larger than the viewport is handled by the UA, if authors assign mandatory snapping to non-adjacent siblings, content in between can become inaccessible in cases where it is longer than the screen. 7

Resnapping Requirements
Clarification: Corresponding Dimensions Merged
Clarify that percentages are calculated with respect to their corresponding dimensions.
Name: scroll-snap-padding
Percentages: relative to the corresponding dimension of the scroll container’s visual viewport
Fix Animatable Lines Merged
Fix the Animatable lines
Name: scroll-snap-padding
Animatable: yes as length, percentage, or calc
Name: scroll-snap-margin
Name: yes as length
Defining the Scroll Snap Area Merged
This wording explicitly hooks into the way margin and border-image-outset are defined, which ensures that the assignment of values is fully defined (by reference). It also clarifies that the bounding box is axis-aligned in the scroll container’s coordinate space.

The <length> values give outsets (interpreted as for margin or border-image-outset). The scroll snap area is the rectangular bounding box of the transformed border box, plus the specified outsets, axis-aligned in the scroll container’s coordinate space.

<length>{1,4}
Specifies the outset of the element’s snap margin from the axis-aligned bounding box of the transformed border box, in the scroll container’s coordinate space. Outsets are applied to this bounding box, not the border box.
Definition of scroll-snap-align Merged
The following definition is more concise and more concrete, because it hooks into the proper terminology.
The scroll-snap-align property specifies how an element’s scroll snap margin should align with its ancestor scroll container’s snapport the box’s snap position as an alignment of its snap area (as the alignment subject) within its snap container’s snapport as the alignment container).
Alignment Axes
Tab and I intentionally used the logical axes for scroll-snap-align in the proposal we prepared for the WG. See further explanation. The following changes are due to this difference:

The two values specify the snapping behavior in the x block and y inline axes, respectively.

For all of these values, the block or inline axis is relative to the element’s parent’s writing mode.

Descriptive Subheadings Merged
Tab and I try to use the subheadings as a way of describing what happens, preferably using words other than those that appear in the property name itself. We feel this helps people find the section they are looking for and better understand the concept represented in the section. The following changes bring the subheadings in line with this style. (We're open to alternative wording.)
Inlining Definitions Merged
While having a glossary appendix is sometimes nice, Tab and I tend to put the defining instance of terms inline in the prose: either in the prose description of the model, or in the description of the property that defines exactly how the term works. In some ways this is a stylistic preference, but it has some concrete advantages: We therefore recommend folding these definitions back into the prose. The following changes implement this: Note: In order to preserve readability of the spec top-to-bottom, we generally provide a parenthetical gloss of a term up front if it is used before its defining instance. In this spec, this is provided in the Overview section:

Snap positions are specified as a particular alignment (scroll-snap-align) of an element’s scroll snap area (its border box, as modified by scroll-snap-margin) within the scroll container’s snapport (its visual viewport, as reduced by scroll-snap-padding). This is conceptually equivalent to specifying the alignment of an alignment subject within an alignment container. A scroll position that satisfies the specified alignment is a valid snap position.

Rewordings
The following rewordings are recommended, as they seem somewhat less awkward than the original wording:
Clarifying Additions
The following insertions, we believe, clarify the text:
Point Snapping Merged
While Tab and I can accept for point-snapping to be deferred to the next level, we would like for at least the next (fully complete) publication to include this feature in its definition, for archiving (and future discussion). Our copy therefore includes definitions for the point value, as well as a section about how it works. (This is, as you can see, clearly labelled as “to be deferred”, however.)
Name: scroll-snap-type
Value none | [ proximity | mandatory ] || [ x | y | block | inline | both | point ]
point
The scroll container point-snaps to snap positions in both axises simultaneously, treating each element’s snap position as a single 2D position (rather than potentially snapping to different elements in each axis).

7.2. Axis vs Point-Snapping

This feature is planned to be removed in the next publication in order to reduce the feature-set of Level 1. It is included here for future reference in defining Level 2.

(A likely use case for point snapping is tiled galleries that do not form a strict grid, as in this example (Flexbox) or this one (Grid). Again, we're happy to leave this to level 2, but do want the feature design published for future reference.)

Acknowledgements Update Merged
We've added a list of the people who have contributed the spec, and noted that their proposals were mostly accepted rather than mostly ignored.

Many thanks to lots of people for their proposals and recommendations, some of which are incorporated into this document. David Baron, Simon Fraser, Håkon Wium Lie, Edward O'Connor, François Remy, Majid Valpour, potentially some anonymous Microsoft engineers (?), and most especially to Robert O'Callahan for their proposals and recommendations, which have been incorporated into this document.


Anyway, here is some feedback about the new draft. I hope it's not ignored again.

Robert O'Callahan, www-style, 30 January 2014