-
Notifications
You must be signed in to change notification settings - Fork 790
Expand file tree
/
Copy pathdiff-notes.html
More file actions
706 lines (628 loc) · 43.5 KB
/
diff-notes.html
File metadata and controls
706 lines (628 loc) · 43.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
F7FC
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
<!DOCTYPE html>
<title>CSS Scroll Snap Diff Annotations</title>
<meta charset=utf-8>
<link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/2016/W3C-UD">
<style>
html, body { background-image: none; }
.changes > dt:before {
content: counter(changes) " ";
}
.changes > dt {
counter-increment: changes;
margin: 2em 0 1em;
}
dt > strong,
ins, del {
color: inherit;
border-radius: 0.5em;
padding: 0 0.25em;
background: inherit;
}
ins { background: #AFA; }
del { background: #FBB; }
.move { background: #FF0; }
.up::after { content: "⇑"; }
.down::after { content: "⇓"; }
.block { display: block; }
dt > strong {
background: yellow;
}
th {
text-align: right;
}
</style>
<body class="toc-inline">
<h1>CSS Scroll Snap Diff Annotations</h1>
<p>This is a list of <a href="diff">differences</a>
between the <a href="http://www.w3.org/TR/css-snappoints-1/">CSS Scroll Snap Module</a> as maintained by Matt Rakow
and the <a href="http://drafts.csswg.org/css-scroll-snap/">CSS Scroll Snap Module Change Proposal</a> maintained by Tab and fantasai.
<blockquote cite="https://www.w3.org/mid/796F6DC1-B229-41A4-A0A0-D1E1E04799C4@apple.com">
<p>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.
<p>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?
<p>I'm not sure how much time is necessary. Microsoft?
<address>Dean Jackson, www-style, 10 December 2015</address>
</blockquote>
<h2>Suggested Process</h2>
<p>In the interests of F2F time, we are requesting that the WG adopt the following rapid-decision format for resolution of these changes:
<ol>
<li>First, a quick presentation of the change.
<li>Second, a few minutes for people to peruse the change (if necessary),
and to enter a straw poll in IRC:
<table class="data">
<tr>
<th>+1
<td>I agree with adopting the new wording.
<tr>
<th>-1
<td>I disagree with adopting the new wording.
<tr>
<th>+2
<td>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.
<tr>
<th>0
<td>I need more time to decide, please revisit this after the break
(during which I promise to review the change, obviously).
<tr>
<th>T
<td>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 <em>outside of my control</em> to ask for more time).
</li>
</table>
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.
<li>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.
</ol>
<p>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 <em>maybe</em>.
<p>(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.)
<h2>Specific Changes</h2>
<dl class="changes">
<dt id=change-title>Title Change <strong>Merged</strong>
<dd>
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.
(<a href="issues-by-issue#issue-43">Issue 43</a> filed December 2013)
<blockquote>
<p>CSS Scroll Snap <del>Points</del> Module Level 1
<p>http://www.w3.org/TR/css-<del>snappoints</del><ins>scroll-snap</ins>-1/
</blockquote>
<dt id=change-margin-area>Terminology Change: Scroll Snap Area <strong>Merged</strong>
<dd>
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 <em>and outside its border box</em>
whereas the area of concern here includes the entire area of the defined rectangle.
<pre>s/<del>scroll snap margin</del>/<ins>scroll snap area</ins>/g;</pre>
<dt id=change-margin-border-box>Error: border-box vs. margin-box
<strong>Partially Merged</strong>
<dd>
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.
<blockquote>
<p>Snap positions can be specified as a particular alignment (scroll-snap-align) of an element’s scroll snap area
(<del><code>scroll-snap-margin</code>, defaulting to its margin box</del>
<ins>its border box, as modified by <code>scroll-snap-margin</code></ins>)
within …
</blockquote>
(In the most recent changes, “margin box” has been replaced with “border box”,
but the resulting text is awkward.)
<dt id="change-physics">Move: Undefined Animations and Physics
<strong>Merged</strong>
<dd>
There is a statement in the definition of <code>scroll-snap-type</code>
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 <code>scroll-snap-type</code>.
<blockquote>
<p><ins class="move"><del>It</del> <ins>The CSS Scroll Snap Module</ins> intentionally does not specify nor mandate any precise animations or physics used to enforce snap positions; this is left up to the user agent.</ins>
</blockquote>
<dt id=change-axes>Specifying Scroll-snap Axes
<strong>Partially Merged</strong>
<dd>
The WG <a href="https://www.w3.org/mid/CADhPm3t9_fcrr8mZ9eYzkghmkJ0pnmOK5_c10w6RAv51T-28AQ@mail.gmail.com">resolved on 2 December 2015</a>
to specify, on a property applied to the scroll container, which axis(es) would be honored in scroll snapping.
he following changes implement this:
<blockquote>
<table class="def">
<tr>
<th>Name:
<td><dfn>scroll-snap-type</dfn>
<tr>
<th>Value
<td>none <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> <ins>[</ins> proximity <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> mandatory <ins>] <a href="https://drafts.csswg.org/css-values-3/#comb-any">||</a> [ x <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> y <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> block <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> inline <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> both ]</ins>
</table>
</blockquote>
<blockquote>
<p>The scroll-snap-type property defines … <ins>and which axes are considered</ins>.</p>
<ins class="block">
<p>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:</p>
</ins>
<p>…</p>
<ins class="block">
<p>The axis values specify what axis(es) are affected by <a href="#scroll-snap-position">snap positions</a>,
and whether <a href="#scroll-snap-position">snap positions</a> are evaluated independently per axis,
or together as a 2D point.
Values are defined as follows:
<dl>
<dt><dfn class="css" id="valdef-scroll-snap-type-x">x<a class="self-link" href="#valdef-scroll-snap-type-x"></a></dfn>
<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#axis-snapping">axis-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in its horizontal axis only.
<dt><dfn class="css" id="valdef-scroll-snap-type-y">y<a class="self-link" href="#valdef-scroll-snap-type-y"></a></dfn>
<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#axis-snapping">axis-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in its vertical axis only.
<dt><dfn class="css" id="valdef-scroll-snap-type-block">block<a class="self-link" href="#valdef-scroll-snap-type-block"></a></dfn>
<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#axis-snapping">axis-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in its block axis only.
<dt><dfn class="css" id="valdef-scroll-snap-type-inline">inline<a class="self-link" href="#valdef-scroll-snap-type-inline"></a></dfn>
<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#axis-snapping">axis-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in its inline axis only.
<dt><dfn class="css" id="valdef-scroll-snap-type-both">both<a class="self-link" href="#valdef-scroll-snap-type-both"></a></dfn>
<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#axis-snapping">axis-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in both of its axises independently
(potentially snapping to different elements in each axis).
</dl>
<p>If no axis value is specified, then the axis is automatically computed:
<ul>
<li><p>If the <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> is only scrollable in one axis
(only one axis has its <a class="property" href="https://drafts.csswg.org/css-overflow-4/#propdef-overflow">overflow</a> set to <a class="css" href="https://drafts.csswg.org/css-overflow-4/#valdef-overflow-auto">auto</a> or <a class="css" href="https://drafts.csswg.org/css-overflow-4/#valdef-overflow-scroll">scroll</a>)
it <a href="#axis-snapping">axis-snaps</a> in the scrollable axis only.
<li><p>Otherwise, it <a href="#axis-snapping">axis-snaps</a> in its <a href="https://drafts.csswg.org/css-writing-modes-3/#block-axis">block axis</a> only.
</ul>
</ins>
</blockquote>
<p>There remains an <a href="https://lists.w3.org/Archives/Public/www-style/2015Nov/0328.html">open issue</a>
on whether there should be longhands for this and if so, what the shorthand/longhand names should be.
<dt id=change-trap>Trapping
<strong>Merged</strong>
<dd>
In Sapporo, the WG <a href="https://www.w3.org/mid/CADhPm3t9Y_L3sUAfmGXbVE7LdgYUcsDXpaRMXfXxxdkpKAtzWw@mail.gmail.com">resolved (27 October 2015)</a>
to have non-<code>none</code> values of the <code>scroll-snap-type</code> 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.
(<a href="issues-by-issue#issue-82">Issue 82</a> resolved TPAC 2015)
<p>In order to fix this,
Tab and I adjusted the definitions of the <code>scroll-snap-type</code> strictness values as follows:
<blockquote>
<dl>
<dt><dfn class="css" id="valdef-scroll-snap-type-none">none</dfn>
<dd>
<p><ins>If specified on a <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,</ins> …</p>
<ins class="block"><p>If specified on a non-<a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,
this value has no effect.</p></ins>
<dt><dfn class="css" id="valdef-scroll-snap-type-proximity">proximity</dfn>
<dd>
<p><ins>If specified on a <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,</ins> …</p>
<ins class="block"><p>If specified on a non-<a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,
this value “traps” descendant boxes’ <a href="#scroll-snap-position">snap positions</a>,
preventing them from affecting any ancestor <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll containers</a>.</p></ins>
<p>…
<dt><dfn class="css" id="valdef-scroll-snap-type-mandatory">mandatory</dfn>
<dd>
<ins>If specified on a <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,</ins>
…
<ins class="block"><p>If specified on a non-<a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,
this value “traps” descendant boxes’ <a href="#scroll-snap-position">snap positions</a>,
preventing them from affecting any ancestor <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll containers</a>.</p></ins>
<p>…
</dl>
</blockquote>
<p>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-<code>none</code> value for <code>scroll-snap-type</code>.
<blockquote>
<p>The <code>scroll-snap-type</code> property specifies <ins>whether a scroll container is a scroll snap container</ins> …
</blockquote>
<blockquote>
<ins class="block"><p>A box <dfn>captures snap positions</dfn>
if it is a scroll container <em>or</em> has a value other than <code>none</code> for <code>scroll-snap-type</code>.
If a box’s nearest snap-position capturing ancestor on its containing block chain is a scroll container with a non-<code>none</code> value for <code>scroll-snap-type</code>,
then that is the box’s <dfn>scroll snap container</dfn>.
Otherwise, the box has no scroll snap container,
and its specified <a>snap positions</a> do not trigger <a>snapping</a>.</p></ins>
</blockquote>
<p>This also allows the following fix for some imprecise wording in the definition of <code>scroll-snap-align</code>:
<blockquote>
<p>The <code>scroll-snap-align</code> property specifies
<del>how an element’s scroll snap margin should align with its ancestor scroll container’s snap alignment container</del>
<ins>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)</ins>.
</blockquote>
<dt id=change-rfc2119>RFC2119 Terminology
<strong>Merged</strong>
<dd>
As much as I like the word “guarantee” in the description of <code>mandatory</code>,
it seems more appropriate to use RFC2119’s “requirement”.
<blockquote>
<p>… the scroll container is <del>guaranteed</del> <ins>required</ins> …
</blockquote>
<dt id=change-warn>Author Warning wrt Mandatory Snapping
<strong>Merged</strong>
<dd>
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.
<blockquote>
<ins class="block"><p><strong class="advisement">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 <a href="#snap-overflow">handled by the UA</a>,
if authors assign mandatory snapping to non-adjacent siblings,
content in between can become inaccessible
in cases where it is longer than the screen.</strong>
<a class="footnote" href="diff#change-warn">7</a></p></ins>
</blockquote>
<dt id="change-resnap">Resnapping Requirements
<dd>
<ul>
<li>The first change here is to move the resnapping requirements to the end of the section.
This is so that this deep technical detail does not get in the way of understanding what,
overall, the <code>scroll-snap-type</code> values do.
(This editorial movement is particularly important for authors reading the spec.)
This also allows us to merge the two paragraphs, which are nearly identical,
making the spec overall easier to read and less likely to contain inconsistencies.
<li>As <a href="https://www.w3.org/mid/CADhPm3vtvwTPWfYRWvbb=LePjFJft3JnXLpdTFVO30Muiuxpzg@mail.gmail.com">Resolved 20 January 2016</a>,
if the content changes,
and we were either not previously snapped to a snap position
or that snap position no longer exists,
the UA must behave as if the user explicitly scrolled to that position,
i.e. snapping if required.
The following edits implement this requirement:
<blockquote>
<p>If the content changes (e.g. content is added, moved, deleted, resized), the UA must <ins>re-evaluate, and potentially re-snap if necessary, the resulting scroll offset once the positions of the content have restabilized</ins>. … (stuff about resnapping to the same position) … <ins>Otherwise, the scroll container must be re-snapped as if the user had scrolled to its current scroll offset (as an explicit scroll, if no other scroll operation is active).</ins>
</blockquote>
<li>Given those changes, and the fact that reachableness of snap positions is handled more generally elsewhere, the following edits clean up the ensuing prose so that the paragraph reads cleanly:
<blockquote>
<p>… If the content changes …
<del>such that the scroll container would no longer be snapped 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</del>
<p>… If the content changes …
changes such that the scroll container would no longer be snapped (e.g. content is added, moved, deleted, resized) to the same snap position it was snapped to before the content change, the scroll container must be re-snapped. If the same snap position it was snapped to before the content change 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.
<p>… If the content changes (e.g. content is added, moved, deleted, resized), the UA must re-evaluate, and potentially re-snap if necessary, the resulting scroll offset once the positions of the content have restabilized. <ins>However, if there was a previously-snapped snap position (associated with the same element) that still exists after such changes, the UA must remain snapped to it.</ins>
</blockquote>
<li>And this last set of insertions add some clarifications.
<blockquote>
<p>If the content <ins>or layout of the scroll container</ins> changes e.g. content is added, moved, deleted, resized), the UA must re-evaluate, and potentially re-snap if necessary, the resulting scroll offset once the positions of the content have restabilized. <ins>This can result in no snapping, (e.g. if there are no nearby snap positions for a proximitiy-snapping scroll container).</ins> However, if there was a previously-snapped snap position (associated with the same element) that still exists after such changes, the UA must remain snapped to it<ins>—even if the changes would have placed a different snap position closer to the current scroll offset</ins>. Otherwise, the scroll container must be re-snapped as if the user had scrolled to its current scroll offset (as an explicit scroll, if no other scroll operation is active).
</blockquote>
</ul>
<dt id=change-relxy>Clarification: Corresponding Dimensions
<strong>Merged</strong>
<dd>
Clarify that percentages are calculated with respect to their corresponding dimensions.
<blockquote>
<table class="def">
<tr>
<th>Name:
<td>scroll-snap-padding
<tr>
<th>Percentages:</th>
<td>relative to <ins>the corresponding dimension of</ins> the scroll container’s visual viewport
</table>
</blockquote>
<dt id=change-animatable>Fix Animatable Lines
<strong>Merged</strong>
<dd>
Fix the Animatable lines
<blockquote>
<table class="def">
<tr>
<th>Name:
<td>scroll-snap-padding
<tr>
<th>Animatable:</th>
<td><del>yes</del> <ins>as length, percentage, or calc</ins>
</table>
</blockquote>
<blockquote>
<table class="def">
<tr>
<th>Name:
<td>scroll-snap-margin
<tr>
<th>Name:</th>
<td><del>yes</del> <ins>as length</ins>
</table>
</blockquote>
<dt id=change-length-14>Defining the Scroll Snap Area
<strong>Merged</strong>
<dd>
This wording explicitly hooks into the way <code>margin</code> and <code>border-image-outset</code> are defined,
which ensures that the assignment of values is fully defined (by reference).
It also clarifies that the bounding box is axis-aligned <em>in the scroll container’s coordinate space</em>.
<blockquote>
<p><ins>The <a class="production css" href="https://drafts.csswg.org/css-values-3/#length-value" title= "Expands to: em | advance measure | ch | vmin | cm | pc | pixel unit | in | rem | q | vh | ex | pt | vw | vmax | mm"><length></a> values give outsets (interpreted as for <a class="property" href="https://drafts.csswg.org/css2/box.html#propdef-margin">margin</a> or <a class="property" href="https://drafts.csswg.org/css-backgrounds-3/#border-image-outset">border-image-outset</a>).
The <a href="#scroll-snap-area">scroll snap area</a> is the rectangular bounding box of the transformed border box, plus the specified outsets, axis-aligned in the <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container’s</a> coordinate space.</ins></p>
<del class="block">
<dl>
<dt><dfn class="css" id="valdef-scroll-snap-margin-length1-4"><a class="production css" href="https://drafts.csswg.org/css-values-3/#length-value" title="Expands to: em | advance measure | ch | vmin | cm | pc | pixel unit | in | rem | q | vh | ex | pt | vw | vmax | mm"><length></a>{1,4}<a class="self-link" href="#valdef-scroll-snap-margin-length1-4"></a></dfn>
<dd>
Specifies the outset of the element’s snap margin from the axis-aligned bounding box of the transformed border box, in the <a href="#scroll-container">scroll container’s</a> coordinate space. Outsets are applied to this bounding box, not the border box.
</dl>
</del>
</blockquote>
<dt id=change-alignment>Definition of <code>scroll-snap-align</code>
<strong>Merged</strong>
<dd>
The following definition is more concise and more concrete,
because it hooks into the proper terminology.
<blockquote>
The <a class="property" href="#propdef-scroll-snap-align">scroll-snap-align</a> property specifies
<del>how an element’s scroll snap margin should align with its ancestor scroll container’s snapport</del>
<ins>the box’s <a data-link-type="dfn" href="#scroll-snap-position">snap position</a>
as an alignment of its <a data-link-type="dfn" href="#scroll-snap-area">snap area</a>
(as the <a data-link-type="dfn" href="https://drafts.csswg.org/css-align-3/#alignment-subject">alignment subject</a>)
within its <a data-link-type="dfn" href="#scroll-snap-container">snap container’s</a> <a data-link-type="dfn" href="#scroll-snapport">snapport</a>
as the <a data-link-type="dfn" href="https://drafts.csswg.org/css-align-3/#alignment-container">alignment container</a>)</ins>.
</blockquote>
<dt id=change-align-axes>Alignment Axes
<dd>
Tab and I intentionally used the logical axes for <code>scroll-snap-align</code>
in the proposal we prepared for the WG.
See <a href="https://lists.w3.org/Archives/Public/www-style/2016Jan/0133.html">further</a> <a href="https://lists.w3.org/Archives/Public/www-style/2016Jan/0138.html">explanation</a>.
The following changes are due to this difference:
<blockquote>
<p>The two values specify the snapping behavior in the <del>x</del> <ins>block</ins> and <del>y</del> <ins>inline</ins> axes, respectively.</p>
</blockquote>
<blockquote>
<ins class="block">
<p>For all of these values,
the <a href="https://drafts.csswg.org/css-display-3/#block">block</a> or <a href="https://drafts.csswg.org/css-display-3/#inline">inline</a> axis
is relative to the element’s parent’s <a href="https://drafts.csswg.org/css-writing-modes-3/#writing-mode">writing mode</a>.</p>
</ins>
</blockquote>
<!--
<dt id=change-valid>Valid snap positions
<dd>
We make a distinction between snap positions in general and valid snap positions.
I can't remember why.
-->
<dt id=change-subheads>Descriptive Subheadings
<strong>Merged</strong>
<dd>
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.)
<ul>
<li><ins>Capturing Scroll Snap Areas:</ins> Properties on the scroll container
<li>Scroll <del>Snap Types</del> <ins>Snapping Rules</ins>: the <code>scroll-snap-type</code> property
<li>Scroll <del>Snap Padding</del> <ins>Snapping Window</ins>: the <code>scroll-snap-padding</code> property
<li><ins>Aligning Scroll Snap Areas:</ins> Properties on the element
<li>Scroll <del>Snap Margin</del> <ins>Snapping Area</ins>: the <code>scroll-snap-margin</code> property
<li>Scroll <del>Snap</del> <ins>Snapping</ins> Alignment: the <code>scroll-snap-align</code> property
</ul>
<dt id=change-terms>Inlining Definitions
<strong>Merged</strong>
<dd>
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:
<ul>
<li>It keeps normative prose defining a concept all in one place, so that by landing on the term definition it can be understood completely.
<li>It avoids repetition, and thus the definitions going out-of-sync and conflicting with each other—as demonstrated here, where the (normative) definition of “snap margin” fails to account for fragmentation or transforms.
</ul>
We therefore recommend folding these definitions back into the prose.
The following changes implement this:
<ul type=a>
<li>Shift <code><dfn></code> markup for “snap position” back to the first paragraph of the overview and delete the (redundant) definition from the definition list:
<blockquote>
<p>This module introduces control over <ins class="move">scroll snap positions</ins>, which are scroll positions that produce particular alignments of content ithin a scrollable viewport. Using the scroll-snap-type property n the relevant scroll container, the author can request a particular bias for the viewport to land on a valid 2 snap position after scrolling operations.
</blockquote>
<blockquote>
<del class="block">
<dl>
<dt>snap position
<dd>For a scroll container, a particular value for its scroll offset is a snap position if when scrolled to that offset the visual viewport of the scroll container would align with a descendent element in the manner specified by the scroll snap properties.
</dl>
</del>
</blockquote>
<li>Likewise, remove the definitions for the “snap area” and “snapport” and instead make their defining instance the ones in <code>scroll-snap-margin</code> and <code>scroll-snap-padding</code>, respectively:
<blockquote>
<del class="block">
<dl>
<dt>snap alignment container
<dd>A scroll container’s snap alignment container is the rectangle obtained by reducing its visual viewport by its scroll-snap-padding. ISSUE: better name for this concept?
<dt>snap margin
<dd>An element’s snap margin is the rectangle obtained by expanding its border box by its scroll-snap-margin.
</dl>
</del>
</blockquote>
<li>Shift the definition of “snapping” up into the Overview:
<blockquote>
<ins class="block"><p>The act of adjusting the scroll offset of a scroll container’s visual viewport such that it is aligned to a snap position is called <dfn>snapping</dfn>, and a scroll container is said to be <dfn>snapped</dfn> to a snap position if its visual viewport’s scroll offset is that snap position and there is no active scrolling operation.</p>
</blockquote>
<blockquote>
<del class="block">
<dl>
<dt>snapped
<dd>A scroll container is said to be snapped to a snap position if its visual viewport’s scroll offset is that snap position and there is no active scrolling operation.
<dt>snap
<dd>The act of adjusting the scroll offset of a scroll container’s visual viewport such that it is snapped to a snap position is called snapping.
</dl>
</del>
</blockquote>
<li>Work with editors of <a href="https://www.w3.org/TR/css-overflow-3/">CSS Overflow</a> to define “scroll container” or an equivalent term and link to that. (Currently the ED of CSS Overflow Level 3 defines “scrollable box” as a term. This could be changed to “scroll container” or “scrollable container” if desired.)
</ul>
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:
<blockquote>
<p>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.</p>
</blockquote>
<dt id=change-reword>Rewordings
<dd>
The following rewordings are recommended, as they seem somewhat less awkward than the original wording:
<ul type=a>
<li><strong>Merged</strong>
This rewording is less grammatically complex, and maintains parallelism with the previous parenthetical.
<blockquote>
<p>Snap positions can be specified as a particular alignment (<code>scroll-snap-align</code>) of an element’s scroll snap area (its border bounding box, as modified by <code>scroll-snap-margin</code>) within the scroll container’s snapport
(<del>the rectangle obtained by reducing its visual viewport</del> <ins>its visual viewport, as reduced by its scroll-snap-padding</ins>).
</blockquote>
<li><strong>Merged</strong>
This one drops the (in CSS specs) unnecessary “must”,
and shifts the parenthetical to the end so it doesn't interrupt the connection between the adjective “nearest ancestor” and the noun it describes.
<blockquote>
<p><a href="#scroll-snap-position">Snap positions</a> <del>must</del> only affect the nearest ancestor
<del class="move down">(on the element’s<a href="https://drafts.csswg.org/css-display-3/#containing-block-chain">containing block chain</a>)</del>
<a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>
<ins class="move up">on the element’s<a href="https://drafts.csswg.org/css-display-3/#containing-block-chain">containing block chain</a></ins>.</p>
</blockquote>
<li>
This rewording maintains parallel structure with the equivalent sentence in the definition for <code>proximity</code> (the concerns about reachability apply to equally to <code>proximity</code>, and are therefore handled in the general requirements for “snap positions”):
<blockquote>
<p>the scroll container is
required
to be snapped to a valid <a href="#scroll-snap-position">snap position</a> when there are no active scrolling operations.
<del>If a reachable snap position exists, then the scroll container must snap at the termination of a scroll.</del>
<ins>That is, it must <a>snap</a> to a valid <a href="#scroll-snap-position">snap position</a> at the termination of a scroll, if any exist.</ins>
</blockquote>
Adding parentheses to the following sentence (and simplifying it by using a pronoun) helps the reader to know that this case is considered exceptional:
<blockquote>
<p><ins>(</ins>If <del>no reachable snap position</del> <ins>none</ins> exist<del>s</del>, then no snapping occurs.<ins>)</ins></p>
</blockquote>
<li><strong>Merged</strong>
This rewording is more concise, but conveys the same thing.
<blockquote>
<p>The <a class="property" href="#propdef-scroll-snap-padding">scroll-snap-padding</a> property defines the <dfn id="scroll-snapport">scroll snapport</dfn>—<!--
--><del>a region inset from the visual viewport of a <a href="#scroll-container">scroll container</a> used in calculating its <a href="#scroll-snap-position">snap positions</a>. The snapport is used as the alignment container when calculating <a href="#scroll-snap-position">snap positions</a>.</del>
<ins>the area of the scrollport that is used as the <a href="https://drafts.csswg.org/css-align-3/#alignment-container">alignment container</a> of the <a href="#scroll-snap-area">scroll snap areas</a> when calculating their <a href="#scroll-snap-position">snap positions</a></ins>.
</blockquote>
<li><strong>Merged</strong>
The definition here is essentially redundant with the previous paragraph;
Tab and I think this bit of text therefore doesn't need to exist.
<blockquote>
<dl>
<dt><del><dfn class="css" id="valdef-scroll-snap-padding--length--percentage-1-4">[ <a class="production css" href="https://drafts.csswg.org/css-values-3/#length-value" title="Expands to: em | advance measure | ch | vmin | cm | pc | pixel unit | in | rem | q | vh | ex | pt | vw | vmax | mm"><length></a> | <a class="production css" href="https://drafts.csswg.org/css-values-3/#percentage-value"><percentage></a> ]{1,4}<a class="self-link" href="#valdef-scroll-snap-padding--length--percentage-1-4"></a></dfn></del>
<dd><del>Specifies the region inset from the visual viewport.</del> Values are interpreted as for <a class="property" href="https://drafts.csswg.org/css2/box.html#propdef-padding">padding</a>, and specify inward offsets from each edge of the visual viewport.
</dl>
</blockquote>
<li><strong>Merged</strong>
This rewording is more concise, but conveys the same thing with as much precision.
<blockquote>
<p>The <a class="property" href="#propdef-scroll-snap-margin">scroll-snap-margin</a> property
defines the <dfn id="scroll-snap-area">scroll snap area</dfn>
<del>on elements within a <a href="#scroll-container">scroll container</a>, used in calculating <a href="#scroll-snap-position">snap positions</a> for that scroll container</del>
<ins>that is used for snapping this box to the <a href="#scroll-snapport">snapport</a></ins>.
</blockquote>
<li><strong>Merged</strong>
This rewording uses terminology previously defined in order to present more concise definitions with simpler sentence structure:
<blockquote>
<p><ins>Values are defined as follows:</ins>
<dl>
<dt><dfn class="css" id="valdef-scroll-snap-align-none">none<a class="self-link" href="#valdef-scroll-snap-align-none"></a></dfn>
</dt><dd>This box does not define a <a href="#scroll-snap-position">snap position</a> in the specified axis.
</dd><dt><dfn class="css" id="valdef-scroll-snap-align-start">start<a class="self-link" href="#valdef-scroll-snap-align-start"></a></dfn>
</dt><dd><del class="block">The scroll offset which aligns the start edge of this box’s scroll snap margin with the start edge of its ancestor scroll container’s region defined by <a class="property" href="#propdef-scroll-snap-padding">scroll-snap-padding</a> in the specified axis is a <a href="#scroll-snap-position">snap position</a> in that axis.</del>
</dd><dd><ins class="block">Start alignment of this box’s <a href="#scroll-snap-area">scroll snap area</a> within the <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>’s <a href="#scroll-snapport">snapport</a> is a valid <a href="#scroll-snap-position">snap position</a> in the specified axis.</ins>
</dd><dt><dfn class="css" id="valdef-scroll-snap-align-end">end<a class="self-link" href="#valdef-scroll-snap-align-end"></a></dfn>
</dt><dd><del class="block">The scroll offset which aligns the end edge of this box’s scroll snap margin with the end edge of its ancestor scroll container’s region defined by <a class="property" href="#propdef-scroll-snap-padding">scroll-snap-padding</a> in the specified axis is a <a href="#scroll-snap-position">snap position</a> in that axis.</del>
</dd><dd><ins class="block">End alignment of this box’s <a href="#scroll-snap-area">scroll snap area</a> within the <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>’s <a href="#scroll-snapport">snapport</a> is a valid <a href="#scroll-snap-position">snap position</a> in the specified axis.</ins>
</dd><dt><dfn class="css" id="valdef-scroll-snap-align-center">center<a class="self-link" href="#valdef-scroll-snap-align-center"></a></dfn>
</dt><dd><del class="block">The scroll offset which aligns the center of this box’s scroll snap margin with the center of its ancestor scroll container’s region defined by <a class="property" href="#propdef-scroll-snap-padding">scroll-snap-padding</a> in the specified axis is a <a href="#scroll-snap-position">snap position</a> in that axis.</del>
</dd><dd><ins class="block">Center alignment of this box’s <a href="#scroll-snap-area">scroll snap area</a> within the <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>’s <a href="#scroll-snapport">snapport</a> is a valid <a href="#scroll-snap-position">snap position</a> in the specified axis.</ins>
</dl>
</blockquote>
</ul>
<dt id=change-clarify>Clarifying Additions
<dd>
The following insertions, we believe, clarify the text:
<ul type=a>
<li>Since the model of snap positions is founded on the concept of “valid” and “invalid” scrolled views, this rephrasing helps to explain <code>scroll-snap-type: none</code> in that mental model:
<blockquote>
<p>&hellip the scroll container must not snap<ins>: all scroll positions are equally valid</ins>.
</blockquote>
<li><strong>Merged</strong>
This phrase provides something a little more concrete for the reader to relate to, making it less necessary for a casual reader to follow the definition link for “snap” to figure out what that means:
<blockquote>
<p>… the scroll container may snap <ins>to a valid snap position</ins> at the termination of a scroll …
</blockquote>
<blockquote>
<p>… the scroll container is guaranteed to be snapped <ins>to a valid snap position</ins> when there are no active scrolling operations …
</blockquote>
<li><strong>Merged</strong>
This comma breaks up a very long string of (4) prepositional phrases
by splitting off the UA discretion part:
<blockquote>
the scroll container may snap to a valid snap position at the termination of a scroll<ins>,</ins> at the discretion of the UA given the parameters of the scroll.
</blockquote>
</ul>
</dd>
<dt id=change-point>Point Snapping
<strong>Merged</strong>
<dd>
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 <code>point</code> value,
as well as a section about how it works.
(This is, as you can see, clearly labelled as “to be deferred”, however.)
<blockquote>
<table class="def">
<tr>
<th>Name:
<td><dfn>scroll-snap-type</dfn>
<tr>
<th>Value
<td>none <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> [ proximity <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> mandatory <ins>] <a href="https://drafts.csswg.org/css-values-3/#comb-any">||</a> [ x <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> y <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> block <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> inline <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> both <ins><a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> point</ins> ]
</table>
</blockquote>
<blockquote>
<ins class="block">
<dl>
<dt><dfn class="css" id="valdef-scroll-snap-type-point">point<a class="self-link" href="#valdef-scroll-snap-type-point"></a></dfn>
<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#point-snapping">point-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in both axises simultaneously,
treating each element’s <a href="#scroll-snap-position">snap position</a> as a single 2D position
(rather than potentially snapping to different elements in each axis).
</dl>
</ins>
</blockquote>
<blockquote>
<ins class="block">
<h3 class="heading settled" data-level="7.2" id="snap-dimensions"><span class="secno">7.2. </span><span class="content">Axis vs Point-Snapping</span><a class="self-link" href="#snap-dimensions"></a></h3>
<p class="issue" id="issue-323279de"><a class="self-link" href="#issue-323279de"></a> 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.</p>
<p>…</p>
</ins>
</blockquote>
<p>(A likely use case for point snapping is tiled galleries that do not form a strict grid,
as in <a href="http://labs.jensimmons.com/examples/image-gallery-flexbox-1.html">this example</a> (Flexbox)
or <a href="http://labs.jensimmons.com/examples/image-gallery-grid-1.html">this one</a> (Grid).
Again, we're happy to leave this to level 2, but do want the feature design published for future reference.)
<dt id="change-ack">Acknowledgements Update
<strong>Merged</strong>
<dd>
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.
<blockquote>
<p>Many thanks to <del>lots of people for their proposals and recommendations,
some of which are incorporated into this document.</del>
<ins>
David Baron,
Simon Fraser,
Håkon Wium Lie,
Theresa O'Connor,
François Remy,
Majid Valpour,
potentially some anonymous Microsoft engineers (?),
and most especially to Robert O'Callahan
for their proposals and recommendations,
<strong>which have been incorporated into this document</strong>.</ins>
</blockquote>
</dl>
<hr>
<blockquote cite="https://lists.w3.org/Archives/Public/www-style/2014Jan/0591.html">
<p>Anyway, here is some feedback about the new draft. I hope it's not ignored again.
<address>Robert O'Callahan, www-style, 30 January 2014</address>
</blockquote>