Editorial review: Add docs for scroll snap events (#36057)

* Add docs for scroll snap events

* Add scroll snap events guide

* Fixes for estelle review comments

* Fixes for estelle review comments and guide example improvements

* Fixes for estelle review comments

* More tweaks and additions

files/en-us/web/api/document/index.md

@@ -364,6 +364,10 @@ Listen to these events using `addEventListener()` or by assigning an event liste
   - : Fired when the document view or an element has been scrolled.
 - {{DOMxRef("Document/scrollend_event", "scrollend")}}
   - : Fired when the document view or an element has completed scrolling.
+- {{domxref("Document/scrollsnapchange_event", "scrollsnapchange")}} {{experimental_inline}}
+  - : Fired on the scroll container at the end of a scrolling operation when a new scroll snap target has been selected.
+- {{domxref("Document/scrollsnapchanging_event", "scrollsnapchanging")}} {{experimental_inline}}
+  - : Fired on the scroll container when the browser determines a new scroll snap target is pending, i.e. it will be selected when the current scroll gesture ends.
 
 ### Selection events
 

files/en-us/web/api/document/scrollsnapchange_event/index.md

@@ -0,0 +1,85 @@
+---
+title: "Document: scrollsnapchange event"
+short-title: scrollsnapchange
+slug: Web/API/Document/scrollsnapchange_event
+page-type: web-api-event
+status:
+  - experimental
+browser-compat: api.Document.scrollsnapchange_event
+---
+
+{{APIRef}}{{SeeCompatTable}}
+
+The **`scrollsnapchange`** event of the {{domxref("Document")}} interface is fired on the document [scroll container](/en-US/docs/Glossary/Scroll_container) at the end of a scrolling operation when a new scroll snap target is selected.
+
+This event works in much the same way as the {{domxref("Element")}} interface's [`scrollsnapchange`](/en-US/docs/Web/API/Element/scrollsnapchange_event) event, except that the overall HTML document has to be set as the scroll snap container (i.e., {{cssxref("scroll-snap-type")}} is set on the {{htmlelement("html")}} element).
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener("scrollsnapchange", (event) => {});
+
+onscrollsnapchange = (event) => {};
+```
+
+## Event type
+
+A {{domxref("SnapEvent")}}, which inherits from the generic {{domxref("Event")}} type.
+
+## Examples
+
+### Basic usage
+
+Let's say we have a {{htmlelement("main")}} element containing significant content that causes it to scroll:
+
+```html
+<main>
+  <!-- Significant content -->
+</main>
+```
+
+The `<main>` element can be turned into a scroll container using a combination of CSS properties, for example:
+
+```css
+main {
+  width: 250px;
+  height: 450px;
+  overflow: scroll;
+}
+```
+
+We can then implement scroll snapping behavior on the scrolling content by specifying the {{cssxref("scroll-snap-type")}} property on the {{htmlelement("html")}} element:
+
+```css
+html {
+  scroll-snap-type: block mandatory;
+}
+```
+
+The following JavaScript snippet would cause the `scrollsnapchange` event to fire on the HTML document when a child of the `<main>` element becomes a newly-selected snap target. In the handler function, we set a `selected` class on the child referenced by the {{domxref("SnapEvent.snapTargetBlock")}}, which could be used to style it to look like it has been selected (for example, with an animation) when the event fires.
+
+```js
+document.addEventListener("scrollsnapchange", (event) => {
+  event.snapTargetBlock.classList.add("selected");
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("Document/scrollsnapchanging_event", "scrollsnapchanging")}} event
+- {{DOMxRef("Document/scrollend_event", "scrollend")}} event
+- {{domxref("SnapEvent")}}
+- CSS {{cssxref("scroll-snap-type")}} property
+- [CSS scroll snap module](/en-US/docs/Web/CSS/CSS_scroll_snap)
+- [Using scroll snap events](/en-US/docs/Web/CSS/CSS_scroll_snap/Using_scroll_snap_events)
+- [Scroll Snap Events](https://developer.chrome.com/blog/scroll-snap-events) on developer.chrome.com (2024)

files/en-us/web/api/document/scrollsnapchanging_event/index.md

@@ -0,0 +1,94 @@
+---
+title: "Document: scrollsnapchanging event"
+short-title: scrollsnapchanging
+slug: Web/API/Document/scrollsnapchanging_event
+page-type: web-api-event
+status:
+  - experimental
+browser-compat: api.Document.scrollsnapchanging_event
+---
+
+{{APIRef}}{{SeeCompatTable}}
+
+The **`scrollsnapchanging`** event of the {{domxref("Document")}} interface is fired on the [scroll container](/en-US/docs/Glossary/Scroll_container) when the browser determines a new scroll snap target is pending, i.e. it will be selected when the current scroll gesture ends.
+
+This event works in much the same way as the {{domxref("Element")}} interface's [`scrollsnapchanging`](/en-US/docs/Web/API/Element/scrollsnapchanging_event) event, except that the overall HTML document has to be set as the scroll snap container (i.e., {{cssxref("scroll-snap-type")}} is set on the {{htmlelement("html")}} element).
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener("scrollsnapchanging", (event) => {});
+
+onscrollsnapchanging = (event) => {};
+```
+
+## Event type
+
+A {{domxref("SnapEvent")}}, which inherits from the generic {{domxref("Event")}} type.
+
+## Examples
+
+### Basic usage
+
+Let's say we have a {{htmlelement("main")}} element containing significant content that causes it to scroll:
+
+```html
+<main>
+  <!-- Significant content -->
+</main>
+```
+
+The `<main>` element can be turned into a scroll container using a combination of CSS properties, for example:
+
+```css
+main {
+  width: 250px;
+  height: 450px;
+  overflow: scroll;
+}
+```
+
+We can then implement scroll snapping behavior on the scrolling content by specifying the {{cssxref("scroll-snap-type")}} property on the {{htmlelement("html")}} element:
+
+```css
+html {
+  scroll-snap-type: block mandatory;
+}
+```
+
+The following JavaScript snippet would cause the `scrollsnapchanging` event to fire on the HTML document when a child of the `<main>` element becomes a pending snap target. In the handler function, we set a `pending` class on the child referenced by the {{domxref("SnapEvent.snapTargetBlock", "snapTargetBlock")}} property, which could be used to style it differently when the event fires.
+
+```js
+document.addEventListener("scrollsnapchanging", (event) => {
+  // remove previously-set "pending" classes
+  const pendingElems = document.querySelectorAll(".pending");
+  pendingElems.forEach((elem) => {
+    elem.classList.remove("pending");
+  });
+
+  // Set current pending snap target class to "pending"
+  event.snapTargetBlock.classList.add("pending");
+});
+```
+
+At the start of the function, we select all elements that previously had the `pending` class applied and remove it, so that only the most recent pending snap target is styled.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("Document/scrollsnapchange_event", "scrollsnapchange")}} event
+- {{DOMxRef("Document/scrollend_event", "scrollend")}} event
+- {{domxref("SnapEvent")}}
+- CSS {{cssxref("scroll-snap-type")}} property
+- [CSS scroll snap module](/en-US/docs/Web/CSS/CSS_scroll_snap)
+- [Using scroll snap events](/en-US/docs/Web/CSS/CSS_scroll_snap/Using_scroll_snap_events)
+- [Scroll Snap Events](https://developer.chrome.com/blog/scroll-snap-events) on developer.chrome.com (2024)

files/en-us/web/api/element/index.md

@@ -307,10 +307,6 @@ Listen to these events using `addEventListener()` or by assigning an event liste
   - : Fired before WebXR select events ({{domxref("XRSession/select_event", "select")}}, {{domxref("XRSession/selectstart_event", "selectstart")}}, {{domxref("XRSession/selectend_event", "selectend")}}) are dispatched.
 - {{domxref("Element/contentvisibilityautostatechange_event", "contentvisibilityautostatechange")}}
   - : Fires on any element with {{cssxref("content-visibility", "content-visibility: auto")}} set on it when it starts or stops being [relevant to the user](/en-US/docs/Web/CSS/CSS_containment/Using_CSS_containment#relevant_to_the_user) and [skipping its contents](/en-US/docs/Web/CSS/CSS_containment/Using_CSS_containment#skips_its_contents).
-- {{domxref("Element/scroll_event", "scroll")}}
-  - : Fired when the document view or an element has been scrolled.
-- {{domxref("Element/scrollend_event", "scrollend")}}
-  - : Fires when the document view has completed scrolling.
 - {{domxref("Element/securitypolicyviolation_event","securitypolicyviolation")}}
   - : Fired when a [Content Security Policy](/en-US/docs/Web/HTTP/CSP) is violated.
 - {{domxref("Element/wheel_event","wheel")}}
@@ -438,6 +434,17 @@ Listen to these events using `addEventListener()` or by assigning an event liste
 - {{domxref("Element/pointerup_event", "pointerup")}}
   - : Fired when a pointer is no longer active.
 
+### Scroll events
+
+- {{domxref("Element/scroll_event", "scroll")}}
+  - : Fired when the document view or an element has been scrolled.
+- {{domxref("Element/scrollend_event", "scrollend")}}
+  - : Fires when the document view has completed scrolling.
+- {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}} {{experimental_inline}}
+  - : Fired on the scroll container at the end of a scrolling operation when a new scroll snap target has been selected.
+- {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} {{experimental_inline}}
+  - : Fired on the scroll container when the browser determines a new scroll snap target is pending, i.e. it will be selected when the current scroll gesture ends.
+
 ### Touch events
 
 - {{domxref("Element/gesturechange_event","gesturechange")}} {{Non-standard_Inline}}

files/en-us/web/api/element/scrollsnapchange_event/index.md

@@ -0,0 +1,80 @@
+---
+title: "Element: scrollsnapchange event"
+short-title: scrollsnapchange
+slug: Web/API/Element/scrollsnapchange_event
+page-type: web-api-event
+status:
+  - experimental
+browser-compat: api.Element.scrollsnapchange_event
+---
+
+{{APIRef}}{{SeeCompatTable}}
+
+The **`scrollsnapchange`** event of the {{domxref("Element")}} interface is fired on the [scroll container](/en-US/docs/Glossary/Scroll_container) at the end of a scrolling operation when a new scroll snap target has been selected, just before the corresponding {{domxref("Element/scrollend_event", "scrollend")}} event fires.
+
+A scrolling operation ends when the user finishes scrolling within a scroll container — for example using a touch gesture or by dragging the mouse pointer on a scroll bar — and releases the gesture.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener("scrollsnapchange", (event) => {});
+
+onscrollsnapchange = (event) => {};
+```
+
+## Event type
+
+A {{domxref("SnapEvent")}}, which inherits from the generic {{domxref("Event")}} type.
+
+## Examples
+
+### Basic usage
+
+Let's say we have a {{htmlelement("main")}} element containing significant content that causes it to scroll:
+
+```html
+<main>
+  <!-- Significant content -->
+</main>
+```
+
+The `<main>` element can be turned into a scroll container that snaps to its children when scrolled using a combination of the CSS {{cssxref("scroll-snap-type")}} property and other properties. For example:
+
+```css
+main {
+  width: 250px;
+  height: 450px;
+  overflow: scroll;
+  scroll-snap-type: block mandatory;
+}
+```
+
+The following JavaScript snippet would cause the `scrollsnapchange` event to fire on the `<main>` element when one of its children becomes a newly-selected snap target. In the handler function, we set a `selected` class on the child referenced by the {{domxref("SnapEvent.snapTargetBlock")}} property, which could be used to style it to look like it has been selected (for example, with an animation) when the event fires.
+
+```js
+const scrollingElem = document.querySelector("main");
+
+scrollingElem.addEventListener("scrollsnapchange", (event) => {
+  event.snapTargetBlock.classList.add("selected");
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} event
+- {{DOMxRef("Document/scrollend_event", "scrollend")}} event
+- {{domxref("SnapEvent")}}
+- CSS {{cssxref("scroll-snap-type")}} property
+- [CSS scroll snap module](/en-US/docs/Web/CSS/CSS_scroll_snap)
+- [Using scroll snap events](/en-US/docs/Web/CSS/CSS_scroll_snap/Using_scroll_snap_events)
+- [Scroll Snap Events](https://developer.chrome.com/blog/scroll-snap-events) on developer.chrome.com (2024)

files/en-us/web/api/element/scrollsnapchanging_event/index.md

@@ -0,0 +1,89 @@
+---
+title: "Element: scrollsnapchanging event"
+short-title: scrollsnapchanging
+slug: Web/API/Element/scrollsnapchanging_event
+page-type: web-api-event
+status:
+  - experimental
+browser-compat: api.Element.scrollsnapchanging_event
+---
+
+{{APIRef}}{{SeeCompatTable}}
+
+The **`scrollsnapchanging`** event of the {{domxref("Element")}} interface is fired on the [scroll container](/en-US/docs/Glossary/Scroll_container) when the browser determines a new scroll snap target is pending, i.e. it will be selected when the current scroll gesture ends.
+
+Specifically, this event fires during a scrolling gesture, each time the user moves over potential new snap targets. For example, the user could scroll slowly by dragging their finger on a touch screen device, or hold down the mouse button on a scroll bar and move the mouse. `scrollsnapchanging` can therefore fire multiple times for each scrolling gesture.
+
+However, it does not fire on all potential snap targets for a scrolling gesture that moves over multiple snap targets. Rather, it fires just for the last target that the snapping will potentially rest on.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener("scrollsnapchanging", (event) => {});
+
+onscrollsnapchanging = (event) => {};
+```
+
+## Event type
+
+A {{domxref("SnapEvent")}}, which inherits from the generic {{domxref("Event")}} type.
+
+## Examples
+
+### Basic usage
+
+Let's say we have a {{htmlelement("main")}} element containing significant content that causes it to scroll:
+
+```html
+<main>
+  <!-- Significant content -->
+</main>
+```
+
+The `<main>` element can be turned into a scroll container that snaps to its children when scrolled using a combination of the CSS {{cssxref("scroll-snap-type")}} property and other properties. For example:
+
+```css
+main {
+  width: 250px;
+  height: 450px;
+  overflow: scroll;
+  scroll-snap-type: block mandatory;
+}
+```
+
+The following JavaScript snippet would cause the `scrollsnapchanging` event to fire on the `<main>` element when one of its children becomes a pending snap target. In the handler function, we set a `pending` class on the child referenced by the {{domxref("SnapEvent.snapTargetBlock", "snapTargetBlock")}} property, which could be used to style it differently when the event fires.
+
+```js
+scrollingElem.addEventListener("scrollsnapchanging", (event) => {
+  // remove previously-set "pending" classes
+  const pendingElems = document.querySelectorAll(".pending");
+  pendingElems.forEach((elem) => {
+    elem.classList.remove("pending");
+  });
+
+  // Set current pending snap target class to "pending"
+  event.snapTargetBlock.classList.add("pending");
+});
+```
+
+At the start of the function, we select all elements that previously had the `pending` class applied and remove it, so that only the most recent pending snap target is styled.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}} event
+- {{DOMxRef("Document/scrollend_event", "scrollend")}} event
+- {{domxref("SnapEvent")}}
+- CSS {{cssxref("scroll-snap-type")}} property
+- [CSS scroll snap module](/en-US/docs/Web/CSS/CSS_scroll_snap)
+- [Using scroll snap events](/en-US/docs/Web/CSS/CSS_scroll_snap/Using_scroll_snap_events)
+- [Scroll Snap Events](https://developer.chrome.com/blog/scroll-snap-events) on developer.chrome.com (2024)