Skip to content

Commit f253ab7

Browse files
DavMilaDavMila
committed
[css-scroll-snap-2] Add SnapEvent Definition
Patchset 6: - Specify snapchanged & snapchanging algorithm (Appendix B). - Improve text clarity.
1 parent 6aa3150 commit f253ab7

File tree

1 file changed

+162
-48
lines changed

1 file changed

+162
-48
lines changed

‎css-scroll-snap-2/Overview.bs

Lines changed: 162 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -293,9 +293,9 @@ Snap Events {#snap-events}
293293
<tr>
294294
<th><dfn for="snapchanging" event>snapchanging</dfn></th>
295295
<td>{{SnapEvent}}</td>
296-
<td>snap containers</td>
297-
<td>Fired at the scrolling element or {{Document}} during scrolling (similar to {{scroll}} events),
298-
(before a {{snapchanged}} event, if one fires) if the scrolling will lead to a change in the
296+
<td>scroll containers</td>
297+
<td>Fired at the scrolling element or {{Document}} during scrolling (before a {{scroll}} event),
298+
if the scrolling would lead to a change in the
299299
element that the scrolling element or Document is snapped to.</td>
300300
</tr>
301301
</tbody>
@@ -307,56 +307,59 @@ Snap Events {#snap-events}
307307

308308
<ol>
309309
<li>
310-
at the end of a scrolling operation, after the user agent has completed its
311-
snapping, if either:
312-
<ul>
313-
<li> the snap area which the snap container is snapped to (TODO: link spec on how the target is picked) in the block axis is different
314-
from the snap area it most recently snapped to in the block axis, or
315-
</li>
316-
<li> the snap area it is snapped to in the inline axis is different
317-
from the snap area it most recently snapped to in the inline axis.
318-
</li>
319-
</ul>
320-
</li>
321-
<li> (for snap containers with ''scroll-snap-type/proximity'' strictness) at the end of a scroll in which
322-
the snap container scrolls and settles into (or out of) a
323-
snap area's range of proximity snap positions in either axis.
310+
when a scrolling operation is <a spec="cssom-view-1" lt="scroll completed">completed</a>
311+
if, for either the block or inline axis, the
312+
element which the snap container is snapped to is different from the element
313+
it most recently snapped to in that axis. For snap containers with
314+
''scroll-snap-type/proximity'' strictness, the scroll may result in the snap
315+
container no longer being snapped to any element. [[css-scroll-snap-1#choosing]]
316+
describes the method a UA follows when choosing between elements which are
317+
<a spec="css-scroll-snap-1" lt="scroll snap area">snap areas</a>.
324318
</li>
325-
<li> if there is a change to a snap container's style such that it goes from having a
326-
non-'none' value for scroll-snap-type to having a 'none' value or vice versa.
319+
<li> if there is a change to a snap container's style such that it goes from
320+
having a non-'none' value for [[css-scroll-snap-1#scroll-snap-type|scroll-snap-type]]
321+
to having a 'none' value or vice versa.
327322
</li>
328-
<li> if, after a <a href="https://drafts.csswg.org/css-scroll-snap-1/#re-snap">layout change</a>, the snap area to which a snap container is
329-
snapped to changes, regardless of whether there is a change in scroll position
330-
after the layout change.
323+
<li> if, after a [[css-scroll-snap-1#re-snap|layout change]], the element to
324+
which a snap container is snapped to changes, regardless of whether there is
325+
a change in scroll position after the layout change.
331326
</li>
332327
</ol>
333328

334-
Although, snapping occurs when a snap container is first
335-
laid out, {{snapchanged}} should not be triggered by this initial layout snap.
336-
Scrolling operations always lead to {{scrollend}} events being fired. If a scrolling operation
337-
also results in a {{snapchanged}} event being fired, the {{snapchanged}} event should be fired
338-
before the {{scrollend}} event.
329+
Although, snapping occurs when a snap container is first laid out, {{snapchanged}}
330+
should not be triggered by this initial layout snap. Scrolling operations
331+
always lead to {{scrollend}} events being fired. If a scrolling operation also
332+
results in a {{snapchanged}} event being fired, the {{snapchanged}} event
333+
should be fired before the {{scrollend}} event.
339334

340335
<h4 id="snapchanging"> snapchanging </h4>
341-
{{snapchanging}} is dispatched when the snap area to which a
336+
{{snapchanging}} is dispatched when the element to which a
342337
snap container would snap (in either axis) during a scrolling operation changes.
343338
A scrolling operation may animate towards a particular position (e.g.
344-
scrollbar arrow clicks, arrow key presses, "behavior: smooth" programmatic scrolls)
345-
or may directly track a user's input (e.g. touch scrolling, scrollbar dragging).
339+
scrollbar arrow clicks, arrow key presses, "behavior: smooth" programmatic
340+
scrolls) or may directly track a user's input (e.g. touch scrolling, scrollbar
341+
dragging).
342+
* In the former case, the user agent should evaluate whether snapchanging is
343+
occurring based on the
344+
<a spec="css-scroll-snap-1" lt="scroll snap position">snap position</a>
345+
that will eventually be snapped to after the scroll animation's target offset
346+
is reached.
347+
* In the latter case, the user agent should evaluate whether snapchanging
348+
should be triggered based on the
349+
<a spec="css-scroll-snap-1" lt="scroll snap position">snap position</a> that
350+
would be snapped to if the scroll is ended at the current scroll position
351+
(determined by the user's input).
352+
346353
{{snapchanging}} aims to let the web page know, as early as possible,
347-
that the scrolling operation will result in a change in the snap area
348-
the snap container is snapped to.
349-
* In the former case, the user agent should evaluate whether snapchanging is occurring based on
350-
the snap position that will eventually be snapped to after the scroll animation's
351-
target offset is reached.
352-
* In the latter case, the user agent should evaluate whether snapchanging should
353-
be triggered based on the snap position that would be snapped to if
354-
the scroll is ended at the current scroll position (determined by the user's input).
354+
that the scrolling operation will result in a change in the element the snap
355+
container is snapped to.
355356

356-
Note that since snapchanging gives the web page hints about future snapping,
357-
the snapping hinted at by a snapchanging event may not materialize since it will be
358-
possible for subsequent scrolling input to further alter the snap container's
359-
scroll position and result in a different eventual snap position.
357+
{{snapchanging}} events should fire before {{scroll}} events.
358+
359+
Note: Since snapchanging gives the web page hints about future snapping,
360+
the snapping hinted at by a snapchanging event may not materialize since it
361+
will be possible for subsequent scrolling input to further alter the snap
362+
container's scroll position and result in a different eventual snap position.
360363

361364

362365
SnapEvent interface
@@ -375,20 +378,20 @@ SnapEvent interface
375378
: <dfn>snapTargetBlock</dfn>
376379
::
377380
The element that the snap container is snapped to in the block axis
378-
at the snap position for the associated snap event.
381+
at the <a spec="css-scroll-snap-1" lt="scroll snap position">snap position</a>
382+
for the associated snap event.
379383
</div>
380384
<div dfn-type=attribute class=attributes dfn-for="SnapEvent">
381385
: <dfn>snapTargetInline</dfn>
382386
::
383387
The element that the snap container is snapped to in the inline axis
384-
at the snap position for the associated snap event.
388+
at the <a spec="css-scroll-snap-1" lt="scroll snap position">snap position</a>
389+
for the associated snap event.
385390
</div>
386391

387-
(TODO: link spec on how snap containers pick snap targets).
388-
389392
For {{snapchanged}} events, the snap position is the position already
390393
realized by the snap container after a scroll snap. For {{snapchanging}}
391-
events it is the snap position that the scroller will eventually
394+
events it is the snap position that the snap container will eventually
392395
snap to when the scrolling operation ends.
393396

394397
</dl>
@@ -475,4 +478,115 @@ Physical Longhands for 'scroll-start-target' {#scroll-start-target-longhands-phy
475478
Animation type: not animatable
476479
</pre>
477480

478-
...
481+
...
482+
483+
Appendix B: Snap Events Timing {#snap-events-timing}
484+
==================================
485+
486+
This appendix describes the algorithm UAs should follow to dispatch {{snapchanged}}
487+
and {{snapchanging}} events in response to a scrolling operation on a
488+
<a spec=css-scroll-snap lt="scroll snap container">snap container</a>.
489+
490+
Each {{Document}} has an associated list of
491+
<dfn export for=Document>pending snapchanging event targets</dfn>, initially
492+
empty.
493+
494+
Each {{Document}} associates each of its
495+
<a spec=css-scroll-snap lt="scroll snap container">snap containers</a>
496+
with at most one <dfn>snapchangingTargetBlock</dfn> and at most one
497+
<dfn>snapchangingTargetInline</dfn> in the block and inline axes respectively.
498+
499+
When a <a spec=css-scroll-snap lt="scroll snap container">snap container</a> is
500+
scrolled, run these steps:
501+
502+
0. Let <var>doc</var> be the
503+
<a spec=css-scroll-snap lt="scroll snap container">snap container</a>'s
504+
associated {{Document}}.
505+
1. Let <var>scrollPosition</var> be the scroll offset resulting from applying
506+
all pending scroll updates to the snap container.
507+
2. Let <var>blockTarget</var> be the
508+
<a>snapchangingTargetBlock</a> that <var>doc</var> associates with the snap
509+
container.
510+
3. Let <var>inlineTarget</var> be the <a>snapchangingTargetInline</a> that
511+
<var>doc</var> associates with the snap container.
512+
4. Let <var>newBlockTarget</var> be the element that the UA would snap the snap
513+
container to from <var>scrollPosition</var> (or null if it would not snap to
514+
any element) along the block axis.
515+
5. Let <var>newInlineTarget</var> be the element that the UA would snap the snap
516+
container to from <var>scrollPosition</var> (or null if it would not snap to
517+
any element) along the inline axis.
518+
6. If <var>newBlockTarget</var> is not the same element as
519+
<var>blockTarget</var>:
520+
521+
1. Set <var>doc</var>'s <a>snapchangingTargetBlock</a> for the snap container
522+
to <var>newBlockTarget</var>.
523+
2. Append the snap container to <var>doc</var>'s
524+
<a>pending snapchanging event targets</a>
525+
7. If <var>newInlineTarget</var> is not the same element as
526+
<var>inlineTarget</var>:
527+
528+
1. Set <var>doc</var>'s <a>snapchangingTargetInline</a> for the snap container
529+
to <var>newInlineTarget</var>.
530+
2. Append the snap container to <var>doc</var>'s pending snapchanging event
531+
targets.
532+
533+
When the <a spec=cssom-view lt="run the scroll steps">scroll steps</a> are run
534+
for a {{Document}} <var>doc</var>, run these steps:
535+
536+
1. For each item <var>target</target> in <var>doc</var>'s
537+
<a>pending snapchanging event targets</a>:
538+
539+
1. Fire a {{SnapEvent}} named snapchanging whose {{snapTargetBlock}} and
540+
{{snapTargetInline}} are the <a>snapchangingTargetBlock</a> and the
541+
<a>snapchangingTargetInline</a>, respectively, that <var>doc</var>
542+
associates with <var>target</var>.
543+
2. Empty <var>doc</var>'s <a>pending snapchanging event targets</a>.
544+
545+
Each {{Document}} has an associated list of
546+
<dfn export for=Document>pending snapchanged event targets</dfn>, initially
547+
empty.
548+
549+
Each {{Document}} associates each of its
550+
<a spec=css-scroll-snap lt="scroll snap container">snap containers</a>
551+
with at most one <dfn>snapchangedTargetBlock</dfn> and at most one
552+
<dfn>snapchangedTargetInline</dfn> in the block and inline axes respectively.
553+
554+
When the scroll on a snap container is
555+
<a spec="cssom-view" lt="scroll completed"> completed</a>, run these steps:
556+
557+
0. Let <var>doc</var> be the
558+
<a spec=css-scroll-snap lt="scroll snap container">snap container</a>'s
559+
associated {{Document}}.
560+
1. Let <var>blockTarget</var> be the <a>snapchangedTargetBlock</a> that
561+
<var>doc</var> associates with the snap container.
562+
2. Let <var>inlineTarget</var> be the <a>snapchangedTargetInline</a> that
563+
<var>doc</var> associates with the snap container.
564+
3. Let <var>blockSnapchangingTarget</var> be the <a>snapchangingTargetBlock</a>
565+
that <var>doc</var> associates with the snap container.
566+
4. Let <var>inlineSnapchangingTarget</var> be the
567+
<a>snapchangingTargetInline</a> that <var>doc</var> associates with the snap
568+
container.
569+
5. If <var>blockTarget</var> is not the same element as
570+
<var>blockSnapchangingTarget</var>:
571+
1. Set <var>doc</var>'s <a>snapchangedTargetBlock</a> for the snap container
572+
to <var>blockSnapchangingTarget</var>.
573+
2. Append the snap container to <var>doc</var>'s
574+
<a>pending snapchanged event targets</a>.
575+
6. If <var>inlineTarget</var> is not the same element as
576+
<var>inlineSnapchangingTarget</var>:
577+
1. Set <var>doc</var>'s <a>snapchangedTargetInline</a> for the snap container
578+
to <var>inlineSnapchangingTarget</var>.
579+
2. Append the snap container to <var>doc</var>'s
580+
<a>pending snapchanged event targets</a>.
581+
582+
When the <a spec=cssom-view lt="run the scroll steps">scroll steps</a> are run
583+
for a {{Document}} <var>doc</var>, run these steps:
584+
585+
1. For each item <var>target</var> in <var>doc</var>'s
586+
<a>pending snapchanged event targets</a>:
587+
588+
1. Fire a {{SnapEvent}} named snapchanged whose {{snapTargetBlock}} and
589+
{{snapTargetInline}} are the <a>snapchangedTargetBlock</a> and the
590+
<a>snapchangedTargetInline</a>, respectively, that <var>doc</var>
591+
associates with <var>target</var>.
592+
2. Empty <var>doc</var>'s <a>pending snapchanged event targets</a>.

0 commit comments

Comments
 (0)