[css-scroll-snap] Better terminology, simplify definition of too-large snap areas and turn the rules into an example

Author: fantasai

css-scroll-snap/Overview.bs

@@ -214,15 +214,21 @@ Scroll Snapping Model {#snap-model}
 	Valid <a>snap positions</a> can be specified
 	as a particular alignment ('scroll-snap-align')
 	of an element's <a>scroll snap area</a> ('scroll-snap-area', defaulting to its margin box)
-	within the <a>scroll container</a>’s viewport
-	(as modified by 'scroll-snap-padding').
+	within the <a>scroll container</a>’s <a>snap target area</a>
+	(its viewport, as reduced by 'scroll-snap-padding').
 	This is conceptually equivalent to specifying the alignment of
 	an <a>alignment subject</a> within an <a>alignment container</a>.
+	The scroll position that satisfies the specified alignment
+	is a valid <a>snap position</a>.
 
 	Valid <a>snap positions</a> can also be specified explicitly
 	as coordinates of the <a>scrollable area</a>
 	with the 'scroll-snap-points-x' and 'scroll-snap-points-y' properties.
 
+	Issue: Discuss <a>intertial</a> vs <a>semantic</a> scrolling concepts (or drop from spec)
+
+	Issue: Discuss 1D vs 2D snapping behaviors... and scoping. (This is all related?)
+
 Scroll Snapping Container {#snap-container}
 =========================
 
@@ -298,7 +304,7 @@ Scroll Snapping Rules: the 'scroll-snap-type' property {#snap-type}
 		<dt><dfn>single</dfn>
 		<dd>
 			This keyword indicates that for <a>inertial scrolls</a>,
-			the next <a>snap position</a>in the direction of the inertia
+			the next <a>snap position</a> in the direction of the inertia
 			captures all remaining inertia.
 	</dl>
 
@@ -322,13 +328,35 @@ Scroll Snapping Window: the 'scroll-snap-padding' property {#snap-padding}
 	Media: interactive
 	</pre>
 
-	The 'scroll-snap-padding' property defines the area of the viewport
-	that is used as the <a>alignment container</a>
-	when aligning <a>scroll snap areas</a> to a <a>snap position</a>.
+	The 'scroll-snap-padding' property defines the <dfn local-lt="snap target area">scroll snap target area</dfn>--
+	the area of the viewport that is used as the <a>alignment container</a>
+	when aligning a <a>scroll snap area</a> to a <a>snap position</a>.
 	Values are interpreted as for 'padding',
-	and specify inward offsets from each side.
+	and specify inward offsets from each side of the viewport.
+
+	<div class="example">
+		In this example, points of interest in a map are centered
+		within the portion of the viewport that does not include the toolbar overlay.
+
+		<pre>
+			map {
+			  overflow: scroll;
+			  scroll-snap-type: proximity;
+			  scroll-snap-padding: 3em 0 0 0;
+			}
+			toolbar {
+				position: absolute;
+				margin: 0.5em;
+				top: 0; left: 0; right: 0;
+				height: 2em;
+			}
+			city {
+				scroll-snap-align: center;
+			}
+		</pre>
+	</div>
 
-	Issue: Add illustration.
+	<div class="example">
 
 Coordinate-based Snapping {#snap-points}
 =========================
@@ -370,13 +398,16 @@ Scroll Snapping Coordinates: the 'scroll-snap-points-x' and 'scroll-snap-points-
 			and clamp the computed value to that minimum.
 	</dl>
 
-	Issue: We changed the initial value to make it so that the start and end of the scrollable area are always reachable and snappable.
+	Coordinates specified by 'scroll-snap-points-x' and 'scroll-snap-points-y'
+	are not affected by 'scroll-snap-padding'/'scroll-snap-destination'.
 
 	Issue: Should we add ''start-edge'' and ''end-edge'' keywords here, so that the start and end of the scrollable area can be defined as reachable?
 	This would be good for e.g. maps. (See <a href="https://lists.w3.org/Archives/Public/www-style/2015Jul/0453.html">Matt Rakow's take</a> on not having ''start'' or ''end'' here.)
 
 	Issue: It was <a href="https://lists.w3.org/Archives/Public/www-style/2015Jul/0453.html">suggested</a> that repeat() be mutually exclusive with element-based snap positions. Is there a better way to integrate this than having the initial value here be "elements"?
 
+	Issue: This needs logical equivalents (-block/-inline instead of -x/-y).
+
 Element-based Snapping {#element}
 ======================
 
@@ -412,37 +443,33 @@ Scroll Snapping Alignment: the 'scroll-snap-align' property {#scroll-snap-align}
 	</pre>
 
 	Specifies the element's <a>snap position</a> as an alignment of
-	its box (as the <a>alignment subject</a>) within the viewport (as the <a>alignment container</a>).
+	its <a>snap area</a> (as the <a>alignment subject</a>)
+	within the viewport's <a>snap target area</a> (as the <a>alignment container</a>).
 
 	The first value specifies alignment in the inline axis;
 	the second value specifies alignment in the block axis.
 	If one value is specified, it is duplicated.
 
-### Snap Alignment in Small Viewports ### {#small-viewports}
+	If the <a>snap area</a> is larger than the <a>snap target area</a> in a particular axis,
+	then any scroll position in which the <a>snap area</a> covers the <a>snap target area</a>
+	is a valid <a>snap position</a> in that axis.
+	The UA may use the specified alignment as a more precise target
+	for certain scroll operations (e.g. inertial scrolling or explicit paging).
 
-	The snapped position of a box is given by its 'scroll-snap-align' property.
-	However, if its <a>scroll snap area</a> is larger than the viewport...
-
-	*       Inertial scrolling (and scroll-adjustment caused by snapping)
-		continues to align to the specified <a>snap position</a> as normal.
-
-	*        For explicit/programmatic (non-fling) scrolling:
-
-		*       While the area fully fills the viewport in a given axis,
-			snapping is ignored in that axis:
-			the container can be scrolled arbitrarily and will not react.
-
-		*       If the container is scrolled such that the area
-			no longer fully fills the viewport in an axis,
-			the area acts as if it has both-edges snapping in that axis,
-			resisting outward scrolling until you fling out
-			or pull it sufficiently to trigger snapping to a different snap-position
-			(with either proximity or mandatory behavior as appropriate).
-
-	As an example, imagine a photo as the area, or a slide in a slideshow.
-	You want mandatory snapping from item to item,
-	but if the item happens to be larger than your viewport,
-	you want to be able to scroll around the whole thing once you're over it.
+	<div class="example">
+		For example, imagine a photo as the area, or a slide in a slideshow.
+		The author wants mandatory snapping from item to item,
+		but if the item happens to be larger than your viewport,
+		you want to be able to scroll around the whole thing once you're over it.
+
+		Since the <a>snap area</a> is larger than the <a>snap target area</a>,
+		while the area fully fills the viewport, 
+		the container can be scrolled arbitrarily and will not try to snap back to its aligned position.
+		However, if the container is scrolled such that the area
+		no longer fully fills the viewport in an axis,
+		the area resisting outward scrolling
+		until you fling out or pull it sufficiently to trigger snapping to a different <a>snap position</a>.
+	</div>
 
 <!--
 ### Combining 1D and 2D Snap Alignments ### {#combo-snapping}