From 776f2d4c443707113e99a144d74e332bcf26a645 Mon Sep 17 00:00:00 2001
From: Carlos Bravo <carlos.bravo@automattic.com>
Date: Mon, 4 Mar 2024 10:15:53 +0100
Subject: [PATCH 1/2] Add withScope description

---
 packages/interactivity/docs/api-reference.md | 34 +++++++++++++++++---
 1 file changed, 29 insertions(+), 5 deletions(-)

diff --git a/packages/interactivity/docs/api-reference.md b/packages/interactivity/docs/api-reference.md
index 319a3974430140..e2cb6da206950f 100644
--- a/packages/interactivity/docs/api-reference.md
+++ b/packages/interactivity/docs/api-reference.md
@@ -125,7 +125,7 @@ Different contexts can be defined at different levels, and deeper levels will me
 
 ### `wp-bind`
 
-This directive allows setting HTML attributes on elements based on a boolean or string value. It follows the syntax `data-wp-bind--attribute`. 
+This directive allows setting HTML attributes on elements based on a boolean or string value. It follows the syntax `data-wp-bind--attribute`.
 
 ```html
 <li data-wp-context='{ "isMenuOpen": false }'>
@@ -225,7 +225,7 @@ The boolean value received by the directive is used to toggle (add when `true` o
 
 ### `wp-style`
 
-This directive adds or removes inline style to an HTML element, depending on its value. It follows the syntax `data-wp-style--css-property`. 
+This directive adds or removes inline style to an HTML element, depending on its value. It follows the syntax `data-wp-style--css-property`.
 
 ```html
 <div data-wp-context='{ "color": "red" }' >
@@ -299,7 +299,7 @@ The returned value is used to change the inner content of the element: `<div>val
 
 ### `wp-on`
 
-This directive runs code on dispatched DOM events like `click` or `keyup`. The syntax is `data-wp-on--[event]` (like `data-wp-on--click` or `data-wp-on--keyup`). 
+This directive runs code on dispatched DOM events like `click` or `keyup`. The syntax is `data-wp-on--[event]` (like `data-wp-on--click` or `data-wp-on--keyup`).
 
 ```php
 <button data-wp-on--click="actions.logTime" >
@@ -387,7 +387,7 @@ The callback passed as the reference receives [the event](https://developer.mozi
 
 It runs a callback **when the node is created and runs it again when the state or context changes**.
 
-You can attach several side effects to the same DOM element by using the syntax `data-wp-watch--[unique-id]`. 
+You can attach several side effects to the same DOM element by using the syntax `data-wp-watch--[unique-id]`.
 
 The `unique-id` doesn't need to be unique globally. It just needs to be different from the other unique IDs of the `wp-watch` directives of that DOM element.
 
@@ -491,7 +491,7 @@ This directive runs the passed callback **during the node's render execution**.
 
 You can use and compose hooks like `useState`, `useWatch`, or `useEffect` inside the passed callback and create your own logic, providing more flexibility than previous directives.
 
-You can attach several `wp-run` to the same DOM element by using the syntax `data-wp-run--[unique-id]`. 
+You can attach several `wp-run` to the same DOM element by using the syntax `data-wp-run--[unique-id]`.
 
 The `unique-id` doesn't need to be unique globally. It just needs to be different from the other unique IDs of the `wp-run` directives of that DOM element.
 
@@ -1042,6 +1042,30 @@ The code will log:
 }
 ```
 
+### useScope()
+
+Actions can depend on the scope when they are called, e.g., when you call `getContext()` or `getElement()`.
+When the Interactivity API runtime execute callbacks, the scope is set automatically. However, if you call an action from a callback that is not executed by the runtime, like `setInterval()`, you need to ensure that callback sets the scope. The way of doing so is by wrapping the callback with `withScope()` function.
+
+An example, where `actions.nextImage` would trigger an undefined error without the wrapper:
+
+```js
+store('mySliderPlugin', {
+	callbacks: {
+		initSlideShow: () => {
+			const ctx = getContext();
+			if ( ctx.autoplay ) {
+				setInterval(
+					withScope( () => {
+						actions.nextImage();
+					} ),
+					state.transitionsSpeed
+				);
+			}
+		},
+})
+```
+
 ## Server functions
 
 The Interactivity API comes with handy functions on the PHP part. Apart from [setting the store via server](#on-the-server-side), there is also a function to get and set Interactivity related config variables.

From e1de939a33d9266ef8a3f9b8484b84efa30090fd Mon Sep 17 00:00:00 2001
From: Carlos Bravo <carlos.bravo@automattic.com>
Date: Mon, 4 Mar 2024 11:17:21 +0100
Subject: [PATCH 2/2] Address feedback

---
 packages/interactivity/docs/api-reference.md | 20 +++++++++-----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/packages/interactivity/docs/api-reference.md b/packages/interactivity/docs/api-reference.md
index e2cb6da206950f..119bbbfcca92e2 100644
--- a/packages/interactivity/docs/api-reference.md
+++ b/packages/interactivity/docs/api-reference.md
@@ -1042,10 +1042,11 @@ The code will log:
 }
 ```
 
-### useScope()
+### withScope()
 
 Actions can depend on the scope when they are called, e.g., when you call `getContext()` or `getElement()`.
-When the Interactivity API runtime execute callbacks, the scope is set automatically. However, if you call an action from a callback that is not executed by the runtime, like `setInterval()`, you need to ensure that callback sets the scope. The way of doing so is by wrapping the callback with `withScope()` function.
+
+When the Interactivity API runtime execute callbacks, the scope is set automatically. However, if you call an action from a callback that is not executed by the runtime, like in a `setInterval()` callback, you need to ensure that the scope is properly set. Use the `withScope()` function to ensure the scope is properly set in these cases.
 
 An example, where `actions.nextImage` would trigger an undefined error without the wrapper:
 
@@ -1053,15 +1054,12 @@ An example, where `actions.nextImage` would trigger an undefined error without t
 store('mySliderPlugin', {
 	callbacks: {
 		initSlideShow: () => {
-			const ctx = getContext();
-			if ( ctx.autoplay ) {
-				setInterval(
-					withScope( () => {
-						actions.nextImage();
-					} ),
-					state.transitionsSpeed
-				);
-			}
+			setInterval(
+				withScope( () => {
+					actions.nextImage();
+				} ),
+				3_000
+			);
 		},
 })
 ```