Skip to content

Commit b7f1e87

Browse files
DavMilaDavMila
committed
[css-scroll-snap-2] Add SnapEvent definition
SnapEvent defines the interface of scroll-snap-related JavaScript events, snapchanged and snapchanging.
1 parent 16e42ed commit b7f1e87

File tree

1 file changed

+230
-7
lines changed

1 file changed

+230
-7
lines changed

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

Lines changed: 230 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -262,7 +262,7 @@ Snap Events {#snap-events}
262262
████████ ███ ████████ ██ ██ ██ ██████
263263
-->
264264

265-
{{snapChanged}} and {{snapChanging}} {#snapchanged-and-snapchanging}
265+
{{snapchanged}} and {{snapchanging}} {#snapchanged-and-snapchanging}
266266
--------------------------------------------
267267

268268
CSS scroll snap points are often used as a mechanism to
@@ -275,15 +275,30 @@ Snap Events {#snap-events}
275275
<table class="data" id="eventhandlers">
276276
<thead>
277277
<tr>
278-
<th>Event handler
279-
<th>Event handler event type
278+
<th>Event</th>
279+
<th>Interface</th>
280+
<th>Targets</th>
281+
<th>Description</th>
282+
</tr>
283+
</thead>
280284
<tbody>
281285
<tr>
282-
<th><dfn event>snapChanged</dfn>
283-
<td>{{scroll!!event}}
286+
<th><dfn for="snapchanged" event>snapchanged</dfn></th>
287+
<td>{{SnapEvent}}</td>
288+
<td>scroll containers</td>
289+
<td>Fired at the scrolling element or {{Document}} at the end of a scroll (before a {{scrollend}} event)
290+
or after a <a href="https://drafts.csswg.org/css-scroll-snap-1/#re-snap">layout snap</a>
291+
if the element that the scrolling element or Document is snapped to changed.</td>
292+
</tr>
284293
<tr>
285-
<th><dfn event>snapChanging</dfn>
286-
<td>{{scroll!!event}}
294+
<th><dfn for="snapchanging" event>snapchanging</dfn></th>
295+
<td>{{SnapEvent}}</td>
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
299+
element that the scrolling element or Document is snapped to.</td>
300+
</tr>
301+
</tbody>
287302
</table>
288303
<h4>SnapEvents</h4>
289304
<pre class="idl">
@@ -388,6 +403,103 @@ Snap Events {#snap-events}
388403
</ul></td></tr>
389404
</table>
390405

406+
<h4 for="snapchanged" id="snapchanged"> snapchanged </h4>
407+
{{snapchanged}} indicates that the snap area to which a snap container is snapped along either axis has changed.
408+
{{snapchanged}} should be dispatched:
409+
410+
<ol>
411+
<li>
412+
when a scrolling operation is <a spec="cssom-view-1" lt="scroll completed">completed</a>
413+
if, for either the block or inline axis, the
414+
element which the snap container is snapped to is different from the element
415+
it most recently snapped to in that axis. For snap containers with
416+
''scroll-snap-type/proximity'' strictness, the scroll may result in the snap
417+
container no longer being snapped to any element. [[css-scroll-snap-1#choosing]]
418+
describes the method a UA follows when choosing between elements which are
419+
<a spec="css-scroll-snap-1" lt="scroll snap area">snap areas</a>.
420+
</li>
421+
<li> if there is a change to a snap container's style such that it goes from
422+
having a non-'none' value for [[css-scroll-snap-1#scroll-snap-type|scroll-snap-type]]
423+
to having a 'none' value or vice versa.
424+
</li>
425+
<li> if, after a [[css-scroll-snap-1#re-snap|layout change]], the element to
426+
which a snap container is snapped to changes, regardless of whether there is
427+
a change in scroll position after the layout change.
428+
</li>
429+
</ol>
430+
431+
Although, snapping occurs when a snap container is first laid out, {{snapchanged}}
432+
should not be triggered by this initial layout.
433+
434+
Scrolling operations always lead to {{scrollend}} events being fired. If a
435+
scrolling operation also results in a {{snapchanged}} event being fired, the
436+
{{snapchanged}} event should be fired before the {{scrollend}} event.
437+
438+
<h4 id="snapchanging"> snapchanging </h4>
439+
{{snapchanging}} is dispatched when the element to which a
440+
snap container would snap (in either axis) during a scrolling operation changes.
441+
A scrolling operation may animate towards a particular position (e.g.
442+
scrollbar arrow clicks, arrow key presses, "behavior: smooth" programmatic
443+
scrolls) or may directly track a user's input (e.g. touch scrolling, scrollbar
444+
dragging).
445+
* In the former case, the user agent should evaluate whether snapchanging is
446+
occurring based on the
447+
<a spec="css-scroll-snap-1" lt="scroll snap position">snap position</a>
448+
that will eventually be snapped to after the scroll animation's target offset
449+
is reached.
450+
* In the latter case, the user agent should evaluate whether snapchanging
451+
should be triggered based on the
452+
<a spec="css-scroll-snap-1" lt="scroll snap position">snap position</a> that
453+
would be snapped to if the scroll is ended at the current scroll position
454+
(determined by the user's input).
455+
456+
{{snapchanging}} aims to let the web page know, as early as possible,
457+
that the scrolling operation will result in a change in the element the snap
458+
container is snapped to.
459+
460+
{{snapchanging}} events should fire before {{scroll}} events.
461+
462+
Note: Since snapchanging gives the web page hints about future snapping,
463+
the snapping hinted at by a snapchanging event may not materialize since it
464+
will be possible for subsequent scrolling input to further alter the snap
465+
container's scroll position and result in a different eventual snap position.
466+
467+
468+
SnapEvent interface
469+
-------------------
470+
471+
<pre class="idl">
472+
[Exposed=Window]
473+
interface SnapEvent : Event {
474+
readonly attribute Node snapTargetBlock;
475+
readonly attribute Node snapTargetInline;
476+
};
477+
</pre>
478+
479+
<dl>
480+
<div dfn-type=attribute class=attributes dfn-for="SnapEvent">
481+
: <dfn>snapTargetBlock</dfn>
482+
::
483+
The element that the snap container is snapped to in the block axis
484+
at the <a spec="css-scroll-snap-1" lt="scroll snap position">snap position</a>
485+
for the associated snap event.
486+
</div>
487+
<div dfn-type=attribute class=attributes dfn-for="SnapEvent">
488+
: <dfn>snapTargetInline</dfn>
489+
::
490+
The element that the snap container is snapped to in the inline axis
491+
at the <a spec="css-scroll-snap-1" lt="scroll snap position">snap position</a>
492+
for the associated snap event.
493+
</div>
494+
495+
For {{snapchanged}} events, the snap position is the position already
496+
realized by the snap container after a scroll snap. For {{snapchanging}}
497+
events it is the snap position that the snap container will eventually
498+
snap to when the scrolling operation ends.
499+
500+
</dl>
501+
502+
A {{SnapEvent}} should not bubble and should not be cancellable.
391503
<!--
392504
██ ███████ ██ ██ ██████ ██ ██ ███ ██ ██ ████████ ██████
393505
██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ██ ██
@@ -470,3 +582,114 @@ Physical Longhands for 'scroll-start-target' {#scroll-start-target-longhands-phy
470582
</pre>
471583

472584
...
585+
586+
Appendix B: Snap Events Timing {#snap-events-timing}
587+
==================================
588+
589+
This appendix describes the algorithm UAs should follow to dispatch {{snapchanged}}
590+
and {{snapchanging}} events in response to a scrolling operation on a
591+
<a spec=css-scroll-snap lt="scroll snap container">snap container</a>.
592+
593+
Each {{Document}} has an associated list of
594+
<dfn export for=Document>pending snapchanging event targets</dfn>, initially
595+
empty.
596+
597+
Each {{Document}} associates each of its
598+
<a spec=css-scroll-snap lt="scroll snap container">snap containers</a>
599+
with at most one <dfn>snapchangingTargetBlock</dfn> and at most one
600+
<dfn>snapchangingTargetInline</dfn> in the block and inline axes respectively.
601+
602+
When a <a spec=css-scroll-snap lt="scroll snap container">snap container</a> is
603+
scrolled, run these steps:
604+
605+
0. Let <var>doc</var> be the
606+
<a spec=css-scroll-snap lt="scroll snap container">snap container</a>'s
607+
associated {{Document}}.
608+
1. Let <var>scrollPosition</var> be the scroll offset resulting from applying
609+
all pending scroll updates to the snap container.
610+
2. Let <var>blockTarget</var> be the
611+
<a>snapchangingTargetBlock</a> that <var>doc</var> associates with the snap
612+
container.
613+
3. Let <var>inlineTarget</var> be the <a>snapchangingTargetInline</a> that
614+
<var>doc</var> associates with the snap container.
615+
4. Let <var>newBlockTarget</var> be the element that the UA would snap the snap
616+
container to from <var>scrollPosition</var> (or null if it would not snap to
617+
any element) along the block axis.
618+
5. Let <var>newInlineTarget</var> be the element that the UA would snap the snap
619+
container to from <var>scrollPosition</var> (or null if it would not snap to
620+
any element) along the inline axis.
621+
6. If <var>newBlockTarget</var> is not the same element as
622+
<var>blockTarget</var>:
623+
624+
1. Set <var>doc</var>'s <a>snapchangingTargetBlock</a> for the snap container
625+
to <var>newBlockTarget</var>.
626+
2. Append the snap container to <var>doc</var>'s
627+
<a>pending snapchanging event targets</a>
628+
7. If <var>newInlineTarget</var> is not the same element as
629+
<var>inlineTarget</var>:
630+
631+
1. Set <var>doc</var>'s <a>snapchangingTargetInline</a> for the snap container
632+
to <var>newInlineTarget</var>.
633+
2. Append the snap container to <var>doc</var>'s pending snapchanging event
634+
targets.
635+
636+
When the <a spec=cssom-view lt="run the scroll steps">scroll steps</a> are run
637+
for a {{Document}} <var>doc</var>, run these steps:
638+
639+
1. For each item <var>target</target> in <var>doc</var>'s
640+
<a>pending snapchanging event targets</a>:
641+
642+
1. Fire a {{SnapEvent}} named snapchanging whose {{snapTargetBlock}} and
643+
{{snapTargetInline}} are the <a>snapchangingTargetBlock</a> and the
644+
<a>snapchangingTargetInline</a>, respectively, that <var>doc</var>
645+
associates with <var>target</var>.
646+
2. Empty <var>doc</var>'s <a>pending snapchanging event targets</a>.
647+
648+
Each {{Document}} has an associated list of
649+
<dfn export for=Document>pending snapchanged event targets</dfn>, initially
650+
empty.
651+
652+
Each {{Document}} associates each of its
653+
<a spec=css-scroll-snap lt="scroll snap container">snap containers</a>
654+
with at most one <dfn>snapchangedTargetBlock</dfn> and at most one
655+
<dfn>snapchangedTargetInline</dfn> in the block and inline axes respectively.
656+
657+
When the scroll on a snap container is
658+
<a spec="cssom-view" lt="scroll completed"> completed</a>, run these steps:
659+
660+
0. Let <var>doc</var> be the
661+
<a spec=css-scroll-snap lt="scroll snap container">snap container</a>'s
662+
associated {{Document}}.
663+
1. Let <var>blockTarget</var> be the <a>snapchangedTargetBlock</a> that
664+
<var>doc</var> associates with the snap container.
665+
2. Let <var>inlineTarget</var> be the <a>snapchangedTargetInline</a> that
666+
<var>doc</var> associates with the snap container.
667+
3. Let <var>blockSnapchangingTarget</var> be the <a>snapchangingTargetBlock</a>
668+
that <var>doc</var> associates with the snap container.
669+
4. Let <var>inlineSnapchangingTarget</var> be the
670+
<a>snapchangingTargetInline</a> that <var>doc</var> associates with the snap
671+
container.
672+
5. If <var>blockTarget</var> is not the same element as
673+
<var>blockSnapchangingTarget</var>:
674+
1. Set <var>doc</var>'s <a>snapchangedTargetBlock</a> for the snap container
675+
to <var>blockSnapchangingTarget</var>.
676+
2. Append the snap container to <var>doc</var>'s
677+
<a>pending snapchanged event targets</a>.
678+
6. If <var>inlineTarget</var> is not the same element as
679+
<var>inlineSnapchangingTarget</var>:
680+
1. Set <var>doc</var>'s <a>snapchangedTargetInline</a> for the snap container
681+
to <var>inlineSnapchangingTarget</var>.
682+
2. Append the snap container to <var>doc</var>'s
683+
<a>pending snapchanged event targets</a>.
684+
685+
When the <a spec=cssom-view lt="run the scroll steps">scroll steps</a> are run
686+
for a {{Document}} <var>doc</var>, run these steps:
687+
688+
1. For each item <var>target</var> in <var>doc</var>'s
689+
<a>pending snapchanged event targets</a>:
690+
691+
1. Fire a {{SnapEvent}} named snapchanged whose {{snapTargetBlock}} and
692+
{{snapTargetInline}} are the <a>snapchangedTargetBlock</a> and the
693+
<a>snapchangedTargetInline</a>, respectively, that <var>doc</var>
694+
associates with <var>target</var>.
695+
2. Empty <var>doc</var>'s <a>pending snapchanged event targets</a>.

0 commit comments

Comments
 (0)