merge

Author: fantasai

css-scroll-snap/Overview.bs

@@ -452,8 +452,7 @@ Scroll Snapping Alignment: the 'scroll-snap-align' property {#scroll-snap-align}
 	its <a>snap area</a> (as the <a>alignment subject</a>)
 	within the viewport's <a>snap viewport</a> (as the <a>alignment container</a>).
 	The <a>scroll alignment values</a> can be specified per-axis,
-	or as a simultaneous 2D alignment position,
-	by using a <a>scroll axis keyword</a>.
+	or as a simultaneous 2D alignment position.
 
 	<pre class="prod">
 		<dfn for=scroll-snap-align><<snap-alignment>></dfn> = center | [ start | end ] <<percentage>>?
@@ -483,7 +482,50 @@ Scroll Snapping Alignment: the 'scroll-snap-align' property {#scroll-snap-align}
 		<pre>img { scroll-snap-align: center; }</pre>
 	</div>
 
-	The <dfn>scroll alignment values</dfn> are defined as follows:
+	'scroll-snap-align' has four distinct families of values,
+	depending on what <a>snap positions</a> you wish the element to declare:
+
+	<dl>
+		<dt id=scroll-snap-align-none>none
+		<dd>
+			The element does not declare any <a>snap positions</a> at all.
+
+		<dt id=scroll-snap-align-single>[ block | inline ]? [ edges | <<snap-alignment>> ]
+		<dd>
+			The element declares a single <a>1D snap position</a>,
+			in either the <a>block</a> or <a>inline</a> axis.
+
+			If neither <css>block</css> nor <css>inline</css> is specified,
+			the axis is automatically chosen:
+
+			* If the element is only scrollable in one axis
+				(only one axis has its 'overflow' set to ''overflow/auto'' or ''overflow/scroll'')
+				the scrollable axis is chosen.
+			* Otherwise, the <a>block</a> axis is chosen.
+
+		<dt id=scroll-snap-align-double>[ none | edges | <<snap-alignment>> ]{2}
+		<dd>
+			The element declares two <a>1D snap positions</a>,
+			one in each axis.
+			The first value is in the <a>block</a> axis,
+			and the second is in the <a>inline</a> axis.
+
+		<dt id=scroll-snap-align-2d>point <<snap-alignment>>{1,2}
+		<dd>
+			The element declares a <a>2D snap position</a>.
+
+			If both alignments are given,
+			the first refers to the <a>block</a> axis
+			and the second refers to the <a>inline</a> axis.
+			If only one is given,
+			the position refers to both axises.
+	</dl>
+
+	For all of these values,
+	the <a>block</a> or <a>inline</a> axis
+	is relative to the element's parent's <a>writing mode</a>.
+
+	The <dfn export>scroll alignment values</dfn> are defined as follows:
 
 	<dl dfn-for=scroll-snap-align dfn-type=value>
 		<dt><dfn>none</dfn>
@@ -524,47 +566,6 @@ Scroll Snapping Alignment: the 'scroll-snap-align' property {#scroll-snap-align}
 			are valid <a>snap positions</a>.
 	</dl>
 
-	The <dfn>scroll axis keywords</dfn>
-	allow explicitly targeting a specific axis
-	or requesting simultaneous 2D alignment,
-	and are defined as follows:
-
-	<dl dfn-type=value dfn-for=scroll-snap-align>
-		<dt><dfn>inline</dfn>
-		<dt><dfn>block</dfn>
-		<dd>
-			The specified alignment applies to the inline or block axis, respectively.
-			The computed alignment of the opposite axis is set to ''scroll-snap-align/none''.
-
-			<div class="example">
-				The following two declarations are equivalent:
-				<pre>
-					scroll-snap-align: none start;
-					scroll-snap-align: block start;
-				</pre>
-			</div>
-
-		<dt><dfn>point</dfn>
-		<dd>
-			Specifies 2D snapping:
-			the <a>snap position</a> is only valid when both axes are aligned as specified;
-			otherwise the <a>snap position</a> in each axis
-			is independent of alignment in the other axis.
-	</dl>
-
-	If two <<snap-alignment>> values are specified, then
-	the first value specifies alignment in the inline axis;
-	and the second value (if any) specifies alignment in the block axis.
-
-	If only one value is specified
-	and no <a>scroll axis keyword</a> is specified, then
-	the <<snap-alignment>> value
-	applies to the scrollable axis of the affected <a>scroll container</a>.
-	If both axes are scrollable
-	(i.e. both 'overflow-x' and 'overflow-y' are either ''overflow/scroll'' or ''overflow/auto''),
-	then it applies to the block axis of the affected <a>scroll container</a>
-	(as determined by the <a>scroll container</a>’s <a>writing mode</a>).
-
 	Note: Remember that in <a>vertical writing modes</a> the block and inline axes
 	correspond to the x and y axes, and not the y and x axes, respectively.
 
@@ -591,6 +592,7 @@ Scroll Snapping Alignment: the 'scroll-snap-align' property {#scroll-snap-align}
 
 	<details class="why">
 		<summary>Why no <<length>> or <<position>> values?</summary>
+
 		The values here represent alignments
 		(in the sense of 'align-self' and 'justify-self'),
 		so are consistent with that syntax.