From 653832dc33ba1f667be05b24d9608829abdc716f Mon Sep 17 00:00:00 2001
From: Carlos Bravo <37012961+c4rl0sbr4v0@users.noreply.github.com>
Date: Thu, 18 Jan 2024 20:02:43 +0100
Subject: [PATCH] Interactivity API: Add `wp-data-on-window` and
 `wp-data-on-document` directives (#57931)

* Add wp-data-on-window and wp-data-on-document directives

* Update changelog

* Rename directives tests files to unify them

* Use callbacks instead of actions, remove not needed counter

* Add event listener removal tests

* Add documentation

* Test that events are reattached

* Fix docs typos

* Fix docs typos

* Fix indentation in docs

* Fix e2e test
---
 .../directive-on-document/block.json          |  15 ++
 .../directive-on-document/render.php          |  18 ++
 .../directive-on-document/view.js             |  34 ++++
 .../directive-on-window/block.json            |  15 ++
 .../directive-on-window/render.php            |  18 ++
 .../directive-on-window/view.js               |  34 ++++
 packages/interactivity/CHANGELOG.md           |   1 +
 .../interactivity/docs/2-api-reference.md     | 160 +++++++++++++-----
 packages/interactivity/src/directives.js      |  98 +++++++----
 ...es-body.spec.ts => directive-body.spec.ts} |   0
 ...-class.spec.ts => directive-class.spec.ts} |   0
 ...text.spec.ts => directive-context.spec.ts} |   0
 .../directive-on-document.spec.ts             |  47 +++++
 .../interactivity/directive-on-window.spec.ts |  45 +++++
 ...-style.spec.ts => directive-style.spec.ts} |   0
 ...es-text.spec.ts => directive-text.spec.ts} |   0
 16 files changed, 404 insertions(+), 81 deletions(-)
 create mode 100644 packages/e2e-tests/plugins/interactive-blocks/directive-on-document/block.json
 create mode 100644 packages/e2e-tests/plugins/interactive-blocks/directive-on-document/render.php
 create mode 100644 packages/e2e-tests/plugins/interactive-blocks/directive-on-document/view.js
 create mode 100644 packages/e2e-tests/plugins/interactive-blocks/directive-on-window/block.json
 create mode 100644 packages/e2e-tests/plugins/interactive-blocks/directive-on-window/render.php
 create mode 100644 packages/e2e-tests/plugins/interactive-blocks/directive-on-window/view.js
 rename test/e2e/specs/interactivity/{directives-body.spec.ts => directive-body.spec.ts} (100%)
 rename test/e2e/specs/interactivity/{directives-class.spec.ts => directive-class.spec.ts} (100%)
 rename test/e2e/specs/interactivity/{directives-context.spec.ts => directive-context.spec.ts} (100%)
 create mode 100644 test/e2e/specs/interactivity/directive-on-document.spec.ts
 create mode 100644 test/e2e/specs/interactivity/directive-on-window.spec.ts
 rename test/e2e/specs/interactivity/{directives-style.spec.ts => directive-style.spec.ts} (100%)
 rename test/e2e/specs/interactivity/{directives-text.spec.ts => directive-text.spec.ts} (100%)

diff --git a/packages/e2e-tests/plugins/interactive-blocks/directive-on-document/block.json b/packages/e2e-tests/plugins/interactive-blocks/directive-on-document/block.json
new file mode 100644
index 00000000000000..296a9b2f041905
--- /dev/null
+++ b/packages/e2e-tests/plugins/interactive-blocks/directive-on-document/block.json
@@ -0,0 +1,15 @@
+{
+	"$schema": "https://schemas.wp.org/trunk/block.json",
+	"apiVersion": 2,
+	"name": "test/directive-on-document",
+	"title": "E2E Interactivity tests - directive on document",
+	"category": "text",
+	"icon": "heart",
+	"description": "",
+	"supports": {
+		"interactivity": true
+	},
+	"textdomain": "e2e-interactivity",
+	"viewScript": "directive-on-document-view",
+	"render": "file:./render.php"
+}
diff --git a/packages/e2e-tests/plugins/interactive-blocks/directive-on-document/render.php b/packages/e2e-tests/plugins/interactive-blocks/directive-on-document/render.php
new file mode 100644
index 00000000000000..d04cb79ea58522
--- /dev/null
+++ b/packages/e2e-tests/plugins/interactive-blocks/directive-on-document/render.php
@@ -0,0 +1,18 @@
+<?php
+/**
+ * HTML for testing the directive `data-wp-on`.
+ *
+ * @package gutenberg-test-interactive-blocks
+ */
+
+gutenberg_enqueue_module( 'directive-on-document-view' );
+?>
+
+<div data-wp-interactive='{ "namespace": "directive-on-document" }' data-wp-context='{"isVisible":true}'>
+	<button data-wp-on--click="actions.visibilityHandler" data-testid="visibility">Switch visibility</button>
+	<div data-wp-show-mock="context.isVisible">
+		<div data-wp-on-document--keydown="callbacks.keydownHandler">
+			<p data-wp-text="state.counter" data-testid="counter">0</p>
+		</div>
+	</div>
+</div>
diff --git a/packages/e2e-tests/plugins/interactive-blocks/directive-on-document/view.js b/packages/e2e-tests/plugins/interactive-blocks/directive-on-document/view.js
new file mode 100644
index 00000000000000..b3cb891e4d6cb5
--- /dev/null
+++ b/packages/e2e-tests/plugins/interactive-blocks/directive-on-document/view.js
@@ -0,0 +1,34 @@
+/**
+ * WordPress dependencies
+ */
+import { store, directive, getContext } from '@wordpress/interactivity';
+
+// Mock `data-wp-show` directive to test when things are removed from the
+// DOM.  Replace with `data-wp-show` when it's ready.
+directive(
+	'show-mock',
+	( { directives: { 'show-mock': showMock }, element, evaluate } ) => {
+		const entry = showMock.find( ( { suffix } ) => suffix === 'default' );
+		if ( ! evaluate( entry ) ) {
+			return null;
+		}
+		return element;
+	}
+);
+
+const { state } = store( 'directive-on-document', {
+	state: {
+		counter: 0,
+	},
+	callbacks: {
+		keydownHandler: ( ) => {
+			state.counter += 1;
+		},
+	},
+	actions: {
+		visibilityHandler: () => {
+			const context = getContext();
+			context.isVisible = ! context.isVisible;
+		},
+	}
+} );
diff --git a/packages/e2e-tests/plugins/interactive-blocks/directive-on-window/block.json b/packages/e2e-tests/plugins/interactive-blocks/directive-on-window/block.json
new file mode 100644
index 00000000000000..9d55395b087a68
--- /dev/null
+++ b/packages/e2e-tests/plugins/interactive-blocks/directive-on-window/block.json
@@ -0,0 +1,15 @@
+{
+	"$schema": "https://schemas.wp.org/trunk/block.json",
+	"apiVersion": 2,
+	"name": "test/directive-on-window",
+	"title": "E2E Interactivity tests - directive on window",
+	"category": "text",
+	"icon": "heart",
+	"description": "",
+	"supports": {
+		"interactivity": true
+	},
+	"textdomain": "e2e-interactivity",
+	"viewScript": "directive-on-window-view",
+	"render": "file:./render.php"
+}
diff --git a/packages/e2e-tests/plugins/interactive-blocks/directive-on-window/render.php b/packages/e2e-tests/plugins/interactive-blocks/directive-on-window/render.php
new file mode 100644
index 00000000000000..e9c8792354e2a5
--- /dev/null
+++ b/packages/e2e-tests/plugins/interactive-blocks/directive-on-window/render.php
@@ -0,0 +1,18 @@
+<?php
+/**
+ * HTML for testing the directive `data-wp-on`.
+ *
+ * @package gutenberg-test-interactive-blocks
+ */
+
+gutenberg_enqueue_module( 'directive-on-window-view' );
+?>
+
+<div data-wp-interactive='{ "namespace": "directive-on-window" }' data-wp-context='{"isVisible":true}'>
+	<button data-wp-on--click="actions.visibilityHandler" data-testid="visibility">Switch visibility</button>
+	<div data-wp-show-mock="context.isVisible">
+		<div data-wp-on-window--resize="callbacks.resizeHandler">
+			<p data-wp-text="state.counter" data-testid="counter">0</p>
+		</div>
+	</div>
+</div>
diff --git a/packages/e2e-tests/plugins/interactive-blocks/directive-on-window/view.js b/packages/e2e-tests/plugins/interactive-blocks/directive-on-window/view.js
new file mode 100644
index 00000000000000..11d01b7a216d1c
--- /dev/null
+++ b/packages/e2e-tests/plugins/interactive-blocks/directive-on-window/view.js
@@ -0,0 +1,34 @@
+/**
+ * WordPress dependencies
+ */
+import { store, directive, getContext } from '@wordpress/interactivity';
+
+// Mock `data-wp-show` directive to test when things are removed from the
+// DOM.  Replace with `data-wp-show` when it's ready.
+directive(
+	'show-mock',
+	( { directives: { 'show-mock': showMock }, element, evaluate } ) => {
+		const entry = showMock.find( ( { suffix } ) => suffix === 'default' );
+		if ( ! evaluate( entry ) ) {
+			return null;
+		}
+		return element;
+	}
+);
+
+const { state } = store( 'directive-on-window', {
+	state: {
+		counter: 0,
+	},
+	callbacks: {
+		resizeHandler: ( ) => {
+			state.counter += 1;
+		},
+	},
+	actions: {
+		visibilityHandler: () => {
+			const context = getContext();
+			context.isVisible = ! context.isVisible;
+		},
+	}
+} );
diff --git a/packages/interactivity/CHANGELOG.md b/packages/interactivity/CHANGELOG.md
index 71ec27e50a87e4..d660032cbc0381 100644
--- a/packages/interactivity/CHANGELOG.md
+++ b/packages/interactivity/CHANGELOG.md
@@ -10,6 +10,7 @@
 ### New Features
 
 -   Add the `data-wp-run` directive along with the `useInit` and `useWatch` hooks. ([57805](https://github.com/WordPress/gutenberg/pull/57805))
+-   Add `wp-data-on-window` and `wp-data-on-document` directives. ([57931](https://github.com/WordPress/gutenberg/pull/57931))
 
 ### Breaking Changes
 
diff --git a/packages/interactivity/docs/2-api-reference.md b/packages/interactivity/docs/2-api-reference.md
index 7980c31b984f8d..922662c10a8e2b 100644
--- a/packages/interactivity/docs/2-api-reference.md
+++ b/packages/interactivity/docs/2-api-reference.md
@@ -20,6 +20,8 @@ DOM elements are connected to data stored in the state and context through direc
     - [`wp-style`](#wp-style) ![](https://img.shields.io/badge/ATTRIBUTES-afd2e3.svg)
     - [`wp-text`](#wp-text) ![](https://img.shields.io/badge/CONTENT-afd2e3.svg)
     - [`wp-on`](#wp-on) ![](https://img.shields.io/badge/EVENT_HANDLERS-afd2e3.svg)
+    - [`wp-on-window`](#wp-on-window) ![](https://img.shields.io/badge/EVENT_HANDLERS-afd2e3.svg)
+    - [`wp-on-document`](#wp-on-document) ![](https://img.shields.io/badge/EVENT_HANDLERS-afd2e3.svg)
     - [`wp-watch`](#wp-watch) ![](https://img.shields.io/badge/SIDE_EFFECTS-afd2e3.svg)
     - [`wp-init`](#wp-init) ![](https://img.shields.io/badge/SIDE_EFFECTS-afd2e3.svg)
     - [`wp-run`](#wp-run) ![](https://img.shields.io/badge/SIDE_EFFECTS-afd2e3.svg)
@@ -55,7 +57,7 @@ _Example of directives used in the HTML markup_
   >
     Toggle
   </button>
- 
+
   <p id="p-1" data-bind--hidden="!context.isOpen">
     This element is now visible!
   </p>
@@ -68,13 +70,13 @@ Directives can also be injected dynamically using the [HTML Tag Processor](https
 
 With directives, we can directly manage behavior related to things such as side effects, state, event handlers, attributes or content.
 
-#### `wp-interactive` 
+#### `wp-interactive`
 
 The `wp-interactive` directive "activates" the interactivity for the DOM element and its children through the Interactivity API (directives and store). It includes a namespace to reference a specific store.
 
 ```html
 <!-- Let's make this element and its children interactive and set the namespace -->
-<div 
+<div
   data-wp-interactive='{ "namespace": "myPlugin" }'
   data-wp-context='{ "myColor" : "red", "myBgColor": "yellow" }'
 >
@@ -88,13 +90,13 @@ The `wp-interactive` directive "activates" the interactivity for the DOM element
 > **Note**
 > The use of `data-wp-interactive` is a requirement for the Interactivity API "engine" to work. In the following examples the `data-wp-interactive` has not been added for the sake of simplicity. Also, the `data-wp-interactive` directive will be injected automatically in the future.
 
-#### `wp-context` 
+#### `wp-context`
 
 It provides a **local** state available to a specific HTML node and its children.
 
 The `wp-context` directive accepts a stringified JSON as a value.
 
-_Example of `wp-context` directive_ 
+_Example of `wp-context` directive_
 
 ```php
 //render.php
@@ -139,13 +141,13 @@ Different contexts can be defined at different levels, and deeper levels will me
 </div>
 ```
 
-#### `wp-bind` 
+#### `wp-bind`
 
 It allows setting HTML attributes on elements based on a boolean or string value.
 
 > This directive follows the syntax `data-wp-bind--attribute`.
 
-_Example of `wp-bind` directive_ 
+_Example of `wp-bind` directive_
 
 ```html
 <li data-wp-context='{ "isMenuOpen": false }'>
@@ -183,10 +185,10 @@ store( "myPlugin", {
 
 The `wp-bind` directive is executed:
 
-- When the element is created. 
+- When the element is created.
 - Each time there's a change on any of the properties of the `state` or `context` involved in getting the final value of the directive (inside the callback or the expression passed as reference).
 
-When `wp-bind` directive references a callback to get its final value: 
+When `wp-bind` directive references a callback to get its final value:
 
 - The `wp-bind` directive will be executed each time there's a change on any of the properties of the `state` or `context` used inside this callback.
 - The returned value in the callback function is used to change the value of the associated attribute.
@@ -198,24 +200,24 @@ The `wp-bind` will do different things over the DOM element is applied, dependin
   - If the value is a string, the attribute is added with its value assigned: `<div attribute="value"`.
   - If the attribute name starts with `aria-` or `data-` and the value is boolean (either `true` or `false`), the attribute is added to the DOM with the boolean value assigned as a string: `<div aria-attribute="true">`.
 
-#### `wp-class` 
+#### `wp-class`
 
 It adds or removes a class to an HTML element, depending on a boolean value.
 
 > This directive follows the syntax `data-wp-class--classname`.
 
-_Example of `wp-class` directive_ 
+_Example of `wp-class` directive_
 
 ```html
 <div>
-  <li 
+  <li
     data-wp-context='{ "isSelected": false }'
     data-wp-on--click="actions.toggleSelection"
     data-wp-class--selected="context.isSelected"
   >
     Option 1
   </li>
-  <li 
+  <li
     data-wp-context='{ "isSelected": false }'
     data-wp-on--click="actions.toggleSelection"
     data-wp-class--selected="context.isSelected"
@@ -251,13 +253,13 @@ When `wp-class` directive references a callback to get its final boolean value,
 
 The boolean value received by the directive is used to toggle (add when `true` or remove when `false`) the associated class name from the `class` attribute.
 
-#### `wp-style` 
+#### `wp-style`
 
 It adds or removes inline style to an HTML element, depending on its value.
 
 > This directive follows the syntax `data-wp-style--css-property`.
 
-_Example of `wp-style` directive_ 
+_Example of `wp-style` directive_
 
 ```html
 <div data-wp-context='{ "color": "red" }' >
@@ -296,7 +298,7 @@ The value received by the directive is used to add or remove the style attribute
 - If the value is `false`, the style attribute is removed: `<div>`.
 - If the value is a string, the attribute is added with its value assigned: `<div style="css-property: value;">`.
 
-#### `wp-text` 
+#### `wp-text`
 
 It sets the inner text of an HTML element.
 
@@ -333,13 +335,13 @@ The `wp-text` directive is executed:
 
 The returned value is used to change the inner content of the element: `<div>value</div>`.
 
-#### `wp-on` 
+#### `wp-on`
 
-It runs code on dispatched DOM events like `click` or `keyup`. 
+It runs code on dispatched DOM events like `click` or `keyup`.
 
 > The syntax of this directive is `data-wp-on--[event]` (like `data-wp-on--click` or `data-wp-on--keyup`).
 
-_Example of `wp-on` directive_ 
+_Example of `wp-on` directive_
 
 ```php
 <button data-wp-on--click="actions.logTime" >
@@ -363,20 +365,86 @@ store( "myPlugin", {
 </details>
 <br/>
 
-The `wp-on` directive is executed each time the associated event is triggered. 
+The `wp-on` directive is executed each time the associated event is triggered.
 
 The callback passed as the reference receives [the event](https://developer.mozilla.org/en-US/docs/Web/API/Event) (`event`), and the returned value by this callback is ignored.
 
-#### `wp-watch` 
+#### `wp-on-window`
+
+It allows to attach global window events like `resize`, `copy`, `focus` and then execute a defined callback when those happen.
+
+[List of supported window events.](https://developer.mozilla.org/en-US/docs/Web/API/Window#events)
+
+> The syntax of this directive is `data-wp-on-window--[window-event]` (like `data-wp-on-window--resize`
+or `data-wp-on-window--languagechange`).
+
+_Example of `wp-on-window` directive_
+
+```php
+<div data-wp-on-window--resize="callbacks.logWidth"></div>
+```
+
+<details>
+	<summary><em>See store used with the directive above</em></summary>
+
+```js
+store( "myPlugin", {
+	callbacks: {
+		logWidth() {
+			console.log( 'Window width: ', window.innerWidth );
+		},
+	},
+} );
+```
+
+</details>
+<br/>
+
+The callback passed as the reference receives [the event](https://developer.mozilla.org/en-US/docs/Web/API/Event) (`event`), and the returned value by this callback is ignored. When the element is removed from the DOM, the event listener is also removed.
+
+#### `wp-on-document`
+
+It allows to attach global document events like `scroll`, `mousemove`, `keydown` and then execute a defined callback when those happen.
 
-It runs a callback **when the node is created and runs it again when the state or context changes**. 
+[List of supported document events.](https://developer.mozilla.org/en-US/docs/Web/API/Document#events)
+
+> The syntax of this directive is `data-wp-on-document--[document-event]` (like `data-wp-on-document--keydown`
+or `data-wp-on-document--selectionchange`).
+
+_Example of `wp-on-document` directive_
+
+```php
+<div data-wp-on-document--keydown="callbacks.logKeydown"></div>
+```
+
+<details>
+	<summary><em>See store used with the directive above</em></summary>
+
+```js
+store( "myPlugin", {
+	callbacks: {
+		logKeydown(event) {
+			console.log( 'Key pressed: ', event.key );
+		},
+  },
+} );
+```
+
+</details>
+<br/>
+
+The callback passed as the reference receives [the event](https://developer.mozilla.org/en-US/docs/Web/API/Event) (`event`), and the returned value by this callback is ignored. When the element is removed from the DOM, the event listener is also removed.
+
+#### `wp-watch`
+
+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]`. _The unique id doesn't need to be unique globally, it just needs to be different than the other unique ids of the `wp-watch` directives of that DOM element._
 
 _Example of `wp-watch` directive_
 
 ```html
-<div 
+<div
   data-wp-context='{ "counter": 0 }'
   data-wp-watch="callbacks.logCounter"
 >
@@ -396,14 +464,14 @@ store( "myPlugin", {
       const context = getContext();
       context.counter++;
     },
-    decreaseCounter: () => {	
+    decreaseCounter: () => {
       const context = getContext();
       context.counter--;
     },
   },
   callbacks: {
     logCounter: () => {
-      const { counter } = getContext(); 
+      const { counter } = getContext();
       console.log("Counter is " + counter + " at " + new Date() );
     },
   },
@@ -427,13 +495,13 @@ As a reference, some use cases for this directive may be:
 - Setting the focus on an element with `.focus()`.
 - Changing the state or context when certain conditions are met.
 
-#### `wp-init` 
+#### `wp-init`
 
 It runs a callback **only when the node is created**.
 
 You can attach several `wp-init` to the same DOM element by using the syntax `data-wp-init--[unique-id]`. _The unique id doesn't need to be unique globally, it just needs to be different than the other unique ids of the `wp-init` directives of that DOM element._
 
-_Example of `data-wp-init` directive_ 
+_Example of `data-wp-init` directive_
 
 ```html
 <div data-wp-init="callbacks.logTimeInit">
@@ -444,8 +512,8 @@ _Example of `data-wp-init` directive_
 _Example of several `wp-init` directives on the same DOM element_
 
 ```html
-<form 
-  data-wp-init--log="callbacks.logTimeInit" 
+<form
+  data-wp-init--log="callbacks.logTimeInit"
   data-wp-init--focus="callbacks.focusFirstElement"
 >
   <input type="text">
@@ -472,7 +540,7 @@ store( "myPlugin", {
 
 The `wp-init` can return a function. If it does, the returned function will run when the element is removed from the DOM.
 
-#### `wp-run` 
+#### `wp-run`
 
 It runs the passed callback **during node's render execution**.
 
@@ -480,7 +548,7 @@ You can use and compose hooks like `useState`, `useWatch` or `useEffect` inside
 
 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 than the other unique ids of the `wp-run` directives of that DOM element._
 
-_Example of `data-wp-run` directive_ 
+_Example of `data-wp-run` directive_
 
 ```html
 <div data-wp-run="callbacks.logInView">
@@ -528,7 +596,7 @@ store( 'myPlugin', {
 </details>
 <br/>
 
-#### `wp-key` 
+#### `wp-key`
 
 The `wp-key` directive assigns a unique key to an element to help the Interactivity API identify it when iterating through arrays of elements. This becomes important if your array elements can move (e.g., due to sorting), get inserted, or get deleted. A well-chosen key value helps the Interactivity API infer what exactly has changed in the array, allowing it to make the correct updates to the DOM.
 
@@ -536,18 +604,18 @@ The key should be a string that uniquely identifies the element among its siblin
 
 ```html
 <ul>
-  <li data-wp-key="unique-id-1">Item 1</li> 
+  <li data-wp-key="unique-id-1">Item 1</li>
   <li data-wp-key="unique-id-2">Item 2</li>
-</ul>  
+</ul>
 ```
 
 But it can also be used on other elements:
 
 ```html
 <div>
-  <a data-wp-key="previous-page" ...>Previous page</a> 
+  <a data-wp-key="previous-page" ...>Previous page</a>
   <a data-wp-key="next-page" ...>Next page</a>
-</div>  
+</div>
 ```
 
 When the list is re-rendered, the Interactivity API will match elements by their keys to determine if an item was added/removed/reordered. Elements without keys might be recreated unnecessarily.
@@ -564,7 +632,7 @@ const { state } = store( "myPlugin", {
     currentVideo: '',
     get isPlaying() {
       return state.currentVideo !== '';
-    } 
+    }
   },
 } );
 ```
@@ -599,13 +667,13 @@ The store is used to create the logic (actions, side effects…) linked to the d
 
 ### Elements of the store
 
-#### State 
+#### State
 
 It defines data available to the HTML nodes of the page. It is important to differentiate between two ways to define the data:
 
 - **Global state**:  It is defined using the `store()` function with the `state` property, and the data is available to all the HTML nodes of the page.
 - **Context/Local State**: It is defined using the `data-wp-context` directive in an HTML node, and the data is available to that HTML node and its children. It can be accessed using the `getContext` function inside of an action, derived state or side effect.
-  
+
 ```html
 <div data-wp-context='{ "someText": "Hello World!" }'>
 
@@ -634,11 +702,11 @@ const { state } = store( "myPlugin", {
 } )
 ```
 
-#### Actions 
+#### Actions
 
 Usually triggered by the `data-wp-on` directive (using event listeners) or other actions.
 
-#### Side Effects 
+#### Side Effects
 
 Automatically react to state changes. Usually triggered by `data-wp-watch` or `data-wp-init` directives.
 
@@ -647,7 +715,7 @@ Automatically react to state changes. Usually triggered by `data-wp-watch` or `d
 They return a computed version of the state. They can access both `state` and `context`.
 
 ```js
-// view.js  
+// view.js
 const { state } = store( "myPlugin", {
   state: {
     amount: 34,
@@ -698,7 +766,7 @@ const { state } = store( "myPlugin", {
 > **Note**
 > All `store()` calls with the same namespace return the same references, i.e., the same `state`, `actions`, etc., containing the result of merging all the store parts passed.
 
-- To access the context inside an action, derived state, or side effect, you can use the `getContext` function. 
+- To access the context inside an action, derived state, or side effect, you can use the `getContext` function.
 - To access the reference, you can use the `getElement` function.
 
 ```js
@@ -740,7 +808,7 @@ This approach enables some functionalities that make directives flexible and pow
 
 *In the `view.js` file of each block* we can define both the state and the elements of the store referencing functions like actions, side effects or derived state.
 
-The `store` method used to set the store in javascript can be imported from `@wordpress/interactivity`.  
+The `store` method used to set the store in javascript can be imported from `@wordpress/interactivity`.
 
 ```js
 // store
@@ -768,11 +836,11 @@ store( "myPlugin", {
 > **Note**
 > We will rename `wp_store` to `wp_initial_state` in a future version.
 
-The state can also be initialized on the server using the `wp_store()` function. You would typically do this in the `render.php` file of your block (the `render.php` templates were [introduced](https://make.wordpress.org/core/2022/10/12/block-api-changes-in-wordpress-6-1/) in WordPress 6.1). 
+The state can also be initialized on the server using the `wp_store()` function. You would typically do this in the `render.php` file of your block (the `render.php` templates were [introduced](https://make.wordpress.org/core/2022/10/12/block-api-changes-in-wordpress-6-1/) in WordPress 6.1).
 
 The state defined on the server with `wp_store()` gets merged with the stores defined in the view.js files.
 
-The `wp_store` function receives an [associative array](https://www.php.net/manual/en/language.types.array.php) as a parameter. 
+The `wp_store` function receives an [associative array](https://www.php.net/manual/en/language.types.array.php) as a parameter.
 
 _Example of store initialized from the server with a `state` = `{ someValue: 123 }`_
 
diff --git a/packages/interactivity/src/directives.js b/packages/interactivity/src/directives.js
index e8fec14be75387..25ba92808614d1 100644
--- a/packages/interactivity/src/directives.js
+++ b/packages/interactivity/src/directives.js
@@ -28,6 +28,64 @@ const mergeDeepSignals = ( target, source, overwrite ) => {
 	}
 };
 
+const newRule =
+	/(?:([\u0080-\uFFFF\w-%@]+) *:? *([^{;]+?);|([^;}{]*?) *{)|(}\s*)/g;
+const ruleClean = /\/\*[^]*?\*\/|  +/g;
+const ruleNewline = /\n+/g;
+const empty = ' ';
+
+/**
+ * Convert a css style string into a object.
+ *
+ * Made by Cristian Bote (@cristianbote) for Goober.
+ * https://unpkg.com/browse/goober@2.1.13/src/core/astish.js
+ *
+ * @param {string} val CSS string.
+ * @return {Object} CSS object.
+ */
+const cssStringToObject = ( val ) => {
+	const tree = [ {} ];
+	let block, left;
+
+	while ( ( block = newRule.exec( val.replace( ruleClean, '' ) ) ) ) {
+		if ( block[ 4 ] ) {
+			tree.shift();
+		} else if ( block[ 3 ] ) {
+			left = block[ 3 ].replace( ruleNewline, empty ).trim();
+			tree.unshift( ( tree[ 0 ][ left ] = tree[ 0 ][ left ] || {} ) );
+		} else {
+			tree[ 0 ][ block[ 1 ] ] = block[ 2 ]
+				.replace( ruleNewline, empty )
+				.trim();
+		}
+	}
+
+	return tree[ 0 ];
+};
+
+/**
+ * Creates a directive that adds an event listener to the global window or
+ * document object.
+ *
+ * @param {string} type 'window' or 'document'
+ * @return {void}
+ */
+const getGlobalEventDirective =
+	( type ) =>
+	( { directives, evaluate } ) => {
+		directives[ `on-${ type }` ]
+			.filter( ( { suffix } ) => suffix !== 'default' )
+			.forEach( ( entry ) => {
+				useInit( () => {
+					const cb = ( event ) => evaluate( entry, event );
+					const globalVar = type === 'window' ? window : document;
+					globalVar.addEventListener( entry.suffix, cb );
+					return () =>
+						globalVar.removeEventListener( entry.suffix, cb );
+				}, [] );
+			} );
+	};
+
 export default () => {
 	// data-wp-context
 	directive(
@@ -89,6 +147,11 @@ export default () => {
 		);
 	} );
 
+	// data-wp-on-window--[event]
+	directive( 'on-window', getGlobalEventDirective( 'window' ) );
+	// data-wp-on-document--[event]
+	directive( 'on-document', getGlobalEventDirective( 'document' ) );
+
 	// data-wp-class--[classname]
 	directive(
 		'class',
@@ -126,41 +189,6 @@ export default () => {
 		}
 	);
 
-	const newRule =
-		/(?:([\u0080-\uFFFF\w-%@]+) *:? *([^{;]+?);|([^;}{]*?) *{)|(}\s*)/g;
-	const ruleClean = /\/\*[^]*?\*\/|  +/g;
-	const ruleNewline = /\n+/g;
-	const empty = ' ';
-
-	/**
-	 * Convert a css style string into a object.
-	 *
-	 * Made by Cristian Bote (@cristianbote) for Goober.
-	 * https://unpkg.com/browse/goober@2.1.13/src/core/astish.js
-	 *
-	 * @param {string} val CSS string.
-	 * @return {Object} CSS object.
-	 */
-	const cssStringToObject = ( val ) => {
-		const tree = [ {} ];
-		let block, left;
-
-		while ( ( block = newRule.exec( val.replace( ruleClean, '' ) ) ) ) {
-			if ( block[ 4 ] ) {
-				tree.shift();
-			} else if ( block[ 3 ] ) {
-				left = block[ 3 ].replace( ruleNewline, empty ).trim();
-				tree.unshift( ( tree[ 0 ][ left ] = tree[ 0 ][ left ] || {} ) );
-			} else {
-				tree[ 0 ][ block[ 1 ] ] = block[ 2 ]
-					.replace( ruleNewline, empty )
-					.trim();
-			}
-		}
-
-		return tree[ 0 ];
-	};
-
 	// data-wp-style--[style-key]
 	directive( 'style', ( { directives: { style }, element, evaluate } ) => {
 		style
diff --git a/test/e2e/specs/interactivity/directives-body.spec.ts b/test/e2e/specs/interactivity/directive-body.spec.ts
similarity index 100%
rename from test/e2e/specs/interactivity/directives-body.spec.ts
rename to test/e2e/specs/interactivity/directive-body.spec.ts
diff --git a/test/e2e/specs/interactivity/directives-class.spec.ts b/test/e2e/specs/interactivity/directive-class.spec.ts
similarity index 100%
rename from test/e2e/specs/interactivity/directives-class.spec.ts
rename to test/e2e/specs/interactivity/directive-class.spec.ts
diff --git a/test/e2e/specs/interactivity/directives-context.spec.ts b/test/e2e/specs/interactivity/directive-context.spec.ts
similarity index 100%
rename from test/e2e/specs/interactivity/directives-context.spec.ts
rename to test/e2e/specs/interactivity/directive-context.spec.ts
diff --git a/test/e2e/specs/interactivity/directive-on-document.spec.ts b/test/e2e/specs/interactivity/directive-on-document.spec.ts
new file mode 100644
index 00000000000000..824e217f087146
--- /dev/null
+++ b/test/e2e/specs/interactivity/directive-on-document.spec.ts
@@ -0,0 +1,47 @@
+/**
+ * Internal dependencies
+ */
+import { test, expect } from './fixtures';
+
+test.describe( 'data-wp-on-document', () => {
+	test.beforeAll( async ( { interactivityUtils: utils } ) => {
+		await utils.activatePlugins();
+		await utils.addPostWithBlock( 'test/directive-on-document' );
+	} );
+
+	test.beforeEach( async ( { interactivityUtils: utils, page } ) => {
+		await page.goto( utils.getLink( 'test/directive-on-document' ) );
+	} );
+
+	test.afterAll( async ( { interactivityUtils: utils } ) => {
+		await utils.deactivatePlugins();
+		await utils.deleteAllPosts();
+	} );
+
+	test( 'callbacks should run whenever the specified event is dispatched', async ( {
+		page,
+	} ) => {
+		const counter = page.getByTestId( 'counter' );
+		await expect( counter ).toHaveText( '0' );
+		await page.keyboard.press( 'ArrowDown' );
+		await expect( counter ).toHaveText( '1' );
+	} );
+	test( 'the event listener is removed when the element is removed', async ( {
+		page,
+	} ) => {
+		const counter = page.getByTestId( 'counter' );
+		const visibilityButton = page.getByTestId( 'visibility' );
+		await expect( counter ).toHaveText( '0' );
+		await page.keyboard.press( 'ArrowDown' );
+		await expect( counter ).toHaveText( '1' );
+		// Remove the element.
+		await visibilityButton.click();
+		// This keyboard press should not increase the counter.
+		await page.keyboard.press( 'ArrowDown' );
+		// Add the element back.
+		await visibilityButton.click();
+		await expect( counter ).toHaveText( '1' );
+		await page.keyboard.press( 'ArrowDown' );
+		await expect( counter ).toHaveText( '2' );
+	} );
+} );
diff --git a/test/e2e/specs/interactivity/directive-on-window.spec.ts b/test/e2e/specs/interactivity/directive-on-window.spec.ts
new file mode 100644
index 00000000000000..e1d59e09cd35f4
--- /dev/null
+++ b/test/e2e/specs/interactivity/directive-on-window.spec.ts
@@ -0,0 +1,45 @@
+/**
+ * Internal dependencies
+ */
+import { test, expect } from './fixtures';
+
+test.describe( 'data-wp-on-window', () => {
+	test.beforeAll( async ( { interactivityUtils: utils } ) => {
+		await utils.activatePlugins();
+		await utils.addPostWithBlock( 'test/directive-on-window' );
+	} );
+
+	test.beforeEach( async ( { interactivityUtils: utils, page } ) => {
+		await page.goto( utils.getLink( 'test/directive-on-window' ) );
+	} );
+
+	test.afterAll( async ( { interactivityUtils: utils } ) => {
+		await utils.deactivatePlugins();
+		await utils.deleteAllPosts();
+	} );
+
+	test( 'callbacks should run whenever the specified event is dispatched', async ( {
+		page,
+	} ) => {
+		await page.setViewportSize( { width: 600, height: 600 } );
+		const counter = page.getByTestId( 'counter' );
+		await expect( counter ).toHaveText( '1' );
+	} );
+	test( 'the event listener is removed when the element is removed', async ( {
+		page,
+	} ) => {
+		const counter = page.getByTestId( 'counter' );
+		const visibilityButton = page.getByTestId( 'visibility' );
+		await page.setViewportSize( { width: 600, height: 600 } );
+		await expect( counter ).toHaveText( '1' );
+		// Remove the element.
+		await visibilityButton.click();
+		// This resize should not increase the counter.
+		await page.setViewportSize( { width: 300, height: 600 } );
+		// Add the element back.
+		await visibilityButton.click();
+		await expect( counter ).toHaveText( '1' );
+		await page.setViewportSize( { width: 200, height: 600 } );
+		await expect( counter ).toHaveText( '2' );
+	} );
+} );
diff --git a/test/e2e/specs/interactivity/directives-style.spec.ts b/test/e2e/specs/interactivity/directive-style.spec.ts
similarity index 100%
rename from test/e2e/specs/interactivity/directives-style.spec.ts
rename to test/e2e/specs/interactivity/directive-style.spec.ts
diff --git a/test/e2e/specs/interactivity/directives-text.spec.ts b/test/e2e/specs/interactivity/directive-text.spec.ts
similarity index 100%
rename from test/e2e/specs/interactivity/directives-text.spec.ts
rename to test/e2e/specs/interactivity/directive-text.spec.ts