docs(core): Add event-dispatch README.md

Co-authored-by: Andrew Kushnir <[email protected]>

packages/core/primitives/event-dispatch/README.md

@@ -1,5 +1,9 @@
 # JSAction
 
+> [!CAUTION] This document serves as a technical documentation of an internal
+> library used within Angular. This is **not** a public API that Angular
+> provides, avoid using it directly in Angular applications.
+
 JSAction is a tiny, low-level event delegation library that decouples the
 registration of event listeners from the JavaScript code for the listeners
 themselves. This enables capturing user interactions before the application is
@@ -122,7 +126,7 @@ In this example, there are two event bindings:
 First, we need to set up the EventContract, which installs the global handlers
 for JSAction. The contract can be configured as follows:
 
-```
+```javascript
 import {EventContract} from '@angular/core/primitives/event-dispatch/src/eventcontract';
 import {EventContractContainer} from '@angular/core/primitives/event-dispatch/src/event_contract_container';
 
@@ -172,7 +176,7 @@ to register with JSAction. If you're embedding JSAction into a framework, you
 would probably update your event handling APIs to automatically render these
 attributes for your users.
 
-```
+```html
 <button type="button" jsaction="click:handleClick">Buy now!</button>
 ```
 
@@ -185,7 +189,7 @@ EventContract that has been queueing events.
 TODO(tbondwilkinson): Update this once the BaseDispatcher is renamed to be just
 Dispatcher
 
-```
+```javascript
 import {BaseDispatcher, registerDispatcher} from '@angular/core/primitives/event-dispatch/src/base_dispatcher';
 
 function handleEvent(eventInfoWrapper) {
@@ -212,16 +216,17 @@ application does to handle the dispatched events is up to you. It can be as
 simple as calling methods in a map keyed by handler name, or as complicated as a
 dynamic lazy loading system to load a handler based on the handler name.
 
-### 5. [optional] Delete jsaction attributes
+### 5. [optional] Cleanup event contract
 
-Optionally, you can choose to replace the jsaction attributes with native event
-listeners. There are some tradeoffs to doing this:
+Optionally, you can clean up and remove the event contract from the app if you
+plan to replace all jsaction attributes with native event handlers. There are
+some tradeoffs to doing this:
 
-Pros of deleting jsaction attributes:
+Pros of cleaning up event contract:
 
  - Native handlers avoid the [quirks](#known-caveats) of JSAction dispatching
 
-Pros of keeping jsaction attributes:
+Pros of keeping event contract:
 
  - JSAction's event delegation drastically reduces the number of event
  listeners registered with the browser. In extreme cases, registering
@@ -230,6 +235,12 @@ Pros of keeping jsaction attributes:
  JSAction vs native event listeners. Always using JSAction dispatch keeps
  things consistent.
 
+<!-- end list -->
+
+```javascript
+window['__ec'].cleanUp();
+```
+
 ## Known caveats
 
 Because JSAction may potentially replay queued events some time after the events
@@ -239,4 +250,3 @@ handled synchronously, the nature of delegating the event handling to the root
 global JSAction handlers means APIs like
 
 <!-- TODO: Add a comprehensive list of known behavior differences for both replayed and delegated events. There are also plans to emulate some browser behavior (i.e. stopPropagation) that may fix some of these. -->
-