[css-snappoints] Adding point snapping and axis syntax to scroll-snap-type with alternative syntax proposal based loosely on suggestion from Tab, for discussion in f2f tomorrow

Author: ChumpChief

css-snappoints/Overview.bs

@@ -252,12 +252,12 @@ Capturing Scroll Snap Areas:  Properties on the scroll container {#properties-on
    ██       ██    ██        ████████
 -->
 
-Snapping Rules: the 'scroll-snap-type' property {#scroll-snap-type}
+Scroll Snapping Rules: the 'scroll-snap-type' property {#scroll-snap-type}
 -------------------------------------------------------------------
 
     <pre class="propdef">
     Name: scroll-snap-type
-    Value: none | mandatory | proximity
+    Value: none | [ [ mandatory | proximity ] [ x | y | block | inline ]? ]{1,2} | [ mandatory | proximity ] point
     Initial: none
     Applies to: all elements
     Inherited: no
@@ -267,7 +267,14 @@ Snapping Rules: the 'scroll-snap-type' property {#scroll-snap-type}
     Animatable: no
     </pre>
 
-    The 'scroll-snap-type' property defines how strictly a <a>scroll container</a> should <a>snap</a>.
+    The 'scroll-snap-type' property specifies how strictly a <a>scroll container</a> should <a>snap</a>, and which axes are considered.
+
+    The <dfn noexport lt="strictness value">strictness values</dfn>
+    (''scroll-snap-type/none'', ''proximity'', ''mandatory'')
+    specify how strictly
+    <a>snap positions</a> are enforced on the <a>scroll container</a>
+    (by forcing an adjustment to the scroll offset).
+    Values are defined as follows:
 
     Issue: <a href="https://lists.w3.org/Archives/Public/www-style/2015Nov/0328.html">Open issue</a> on whether to enhance the scroll-snap-type property for specifying the axis or adding a second property.  We have <a href="https://lists.w3.org/Archives/Public/www-style/2015Dec/0048.html">resolved</a> that this functionality be added once the issue is resolved.
 
@@ -291,6 +298,42 @@ Snapping Rules: the 'scroll-snap-type' property {#scroll-snap-type}
             If the content changes such that the scroll container would no longer be <a>snapped</a> (e.g. content is added, moved, deleted, resized) to the same snap position it was snapped to before the content change and that same snap position still exists (e.g. its associated element was not deleted) and is reachable, the scroll container must be re-snapped to that same snap position after the content change.
     </dl>
 
+    The <dfn noexport lt="axis value">axis values</dfn>
+    specify what axis(es) are affected by <a>snap positions</a>,
+    and whether <a>snap positions</a> are evaluated independently per axis,
+    or together as a 2D point.
+    Values are defined as follows:
+
+    <dl dfn-type=value dfn-for="scroll-snap-type">
+        <dt><dfn>x</dfn>
+        <dd>
+            The <a>scroll container</a> <a>axis-snaps</a> to <a>snap positions</a> in its horizontal axis using the corresponding <a>strictness value</a>.
+
+        <dt><dfn>y</dfn>
+        <dd>
+            The <a>scroll container</a> <a>axis-snaps</a> to <a>snap positions</a> in its vertical axis using the corresponding <a>strictness value</a>.
+
+        <dt><dfn>block</dfn>
+        <dd>
+            The <a>scroll container</a> <a>axis-snaps</a> to <a>snap positions</a> in its block axis using the corresponding <a>strictness value</a>.
+
+        <dt><dfn>inline</dfn>
+        <dd>
+            The <a>scroll container</a> <a>axis-snaps</a> to <a>snap positions</a> in its inline axis using the corresponding <a>strictness value</a>.
+
+        <dt><dfn>point</dfn>
+        <dd>
+            The <a>scroll container</a> <a>point-snaps</a> to <a>snap positions</a> in both axises simultaneously,
+            treating each element’s <a>snap position</a> as a single 2D position
+            (rather than potentially snapping to different elements in each axis).
+    </dl>
+
+    If <a>axis values</a> are not specified, then the axis is automatically computed:
+
+    *   If only one <a>strictness value</a> is specified, the <a>scroll container</a> <a>axis-snaps</a> in both axes using that <a>strictness value</a>.
+    *   If two <a>strictness values</a> are specified and no <a>axis values</a> are specified, the <a>scroll container</a> <a>axis-snaps</a> in the horizontal axis using the first <a>strictness value</a> and in the vertical axis using the second <a>strictness value</a>.
+    *   If two <a>strictness values</a> are specified and one <a>axis value</a> is specified, the axis perpendicular to the specified <a>axis value</a> is used for the other <a>strictness value</a>.
+
     Advisement:
     Authors should use mandatory snap positions with consideration of
     varyingly-sized screens and (if applicable) varying-sized content.
@@ -444,6 +487,61 @@ Scroll Snapping Alignment: the 'scroll-snap-align' property {#scroll-snap-align}
             The scroll offset which aligns the center of this box's scroll snap area with the center of its ancestor scroll container's region defined by 'scroll-snap-padding' in the specified axis is a <a>snap position</a> in that axis.
     </dl>
 
+<!--
+   ██   ████████         ███████  ████████
+ ████   ██     ██       ██     ██ ██     ██
+   ██   ██     ██              ██ ██     ██
+   ██   ██     ██        ███████  ██     ██
+   ██   ██     ██       ██        ██     ██
+   ██   ██     ██       ██        ██     ██
+ ██████ ████████        █████████ ████████
+-->
+
+Axis vs Point-Snapping {#snap-dimensions}
+-----------------------------------------
+
+    Issue: 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.
+
+    There are two distinct <dfn lt="snap behavior|snapping behavior">snapping behaviors</dfn> that a <a>scroll container</a> might engage in:
+
+    : <dfn export local-lt="axis" lt="axis-snapping|axis-snap">axis-snapping</dfn>
+    :: If a <a>scroll container</a> is <a>axis-snapping</a>,
+        its descendants indicate a desired scroll position
+        in each axis of the <a>scroll container</a> independently,
+        with no dependent preference for what the other axis's scroll position should be.
+
+        Note: This is the “default” type of <a>snap behavior</a>
+        that most <a>scroll containers</a> will want to use,
+        and so the ''scroll-snap-type'' property intentionally defaults to it.
+
+        Note: An element in an <a>axis-snapping</a> <a>scroll container</a>
+        can declare two <a>snap positions</a>,
+        one in each axis.
+        If one of the element's <a>snap positions</a> is chosen in one axis,
+        this has no bearing on the other dimension's <a>snap position</a>--
+        it might be chosen,
+        or a different element's <a>snap position</a> might be chosen for that axis,
+        or that axis might not snap at all.
+
+    : <dfn export local-lt="point" lt="point-snapping|point-snap">point-snapping</dfn>
+    :: If a <a>scroll container</a> is <a>point-snapping</a>,
+        its descendants indicate a desired scroll position
+        in both axises of the <a>scroll container</a> simultaneously--
+        in other words,
+        some point in the descendant must be aligned to a corresponding point in the <a>scroll container</a>.
+
+        This type of <a>snapping behavior</a> is intended for "two-dimensional" panning-type layouts,
+        such as cities on a map
+        (using ''proximity'' 2D snap positions to snap a city to the center of the display when it gets close),
+        or a tiled image gallery
+        (using ''mandatory'' 2D snap positions to force each image to be centered on the screen).
+        In both of these cases,
+        it would look weird if the horizontal scrolling was aligned to one element
+        while the vertical was aligned to a different element
+        (which is the behavior you'd get if the <a>scroll container</a> was <a>axis-snapping</a>).
+
 <!--
 ██        ███████  ██    ██  ██████   ██     ██    ███    ██    ██ ████████   ██████
 ██       ██     ██ ███   ██ ██    ██  ██     ██   ██ ██   ███   ██ ██     ██ ██    ██