Implement UI event dispatcher/listener (stashapp#4492)

* page change event
* expose event to plugin api
* Update UIPluginApi.md
* Add to example plugin
---------
Co-authored-by: WithoutPants <[email protected]>

pkg/plugin/examples/react-component/src/testReact.tsx

@@ -1,6 +1,9 @@
 interface IPluginApi {
   React: typeof React;
   GQL: any;
+  Event: {
+    addEventListener: (event: string, callback: (e: CustomEvent) => void) => void;
+  };
   libraries: {
     ReactRouterDOM: {
       Link: React.FC<any>;
@@ -53,6 +56,8 @@ interface IPluginApi {
     NavUtils
   } = PluginApi.utils;
 
+  PluginApi.Event.addEventListener("stash:location", (e) => console.log("Page Changed", e.detail.data.location.pathname, e.detail.data.location.search))
+
   const ScenePerformer: React.FC<{
     performer: any;
   }> = ({ performer }) => {

ui/v2.5/src/App.tsx

@@ -42,6 +42,7 @@ import { lazyComponent } from "./utils/lazyComponent";
 import { isPlatformUniquelyRenderedByApple } from "./utils/apple";
 import useScript, { useCSS } from "./hooks/useScript";
 import { useMemoOnce } from "./hooks/state";
+import Event from "./hooks/event";
 import { uniq } from "lodash-es";
 
 import { PluginRoutes } from "./plugins";
@@ -249,6 +250,11 @@ export const App: React.FC = () => {
   const history = useHistory();
   const setupMatch = useRouteMatch(["/setup", "/migrate"]);
 
+  // dispatch event when location changes
+  useEffect(() => {
+    Event.dispatch("location", "", { location });
+  }, [location]);
+
   // redirect to setup or migrate as needed
   useEffect(() => {
     if (!systemStatusData) {

ui/v2.5/src/docs/en/Manual/UIPluginApi.md

@@ -136,3 +136,11 @@ Registers an after function. An after function is called after the render functi
 | `fn` | `Function` | The after function. It accepts the same arguments as the original render function, plus the result of the original render function, and is expected to return the rendered component. |
 
 Returns `void`.
+
+#### `PluginApi.Event`
+
+Allows plugins to listen for Stash's events.
+
+```js
+PluginApi.Event.addEventListener("stash:location", (e) => console.log("Page Changed", e.detail.data.location.pathname))
+```

ui/v2.5/src/hooks/event.ts

@@ -0,0 +1,19 @@
+class StashEvent extends EventTarget {
+  dispatch(event: string, id?: string, data?: object) {
+    event = `stash:${event}${id ? `:${id}` : ""}`;
+
+    this.dispatchEvent(
+      new CustomEvent(event, {
+        detail: {
+          event: event,
+          ...(id ? { id } : {}),
+          ...(data ? { data } : {}),
+        },
+      })
+    );
+  }
+}
+
+const Event = new StashEvent();
+
+export default Event;

ui/v2.5/src/pluginApi.tsx

@@ -13,6 +13,7 @@ import * as FontAwesomeSolid from "@fortawesome/free-solid-svg-icons";
 import * as FontAwesomeRegular from "@fortawesome/free-regular-svg-icons";
 import { useSpriteInfo } from "./hooks/sprite";
 import { useToast } from "./hooks/Toast";
+import Event from "./hooks/event";
 import { before, instead, after, components, RegisterComponent } from "./patch";
 
 // due to code splitting, some components may not have been loaded when a plugin
@@ -106,6 +107,7 @@ export const PluginApi = {
     // and the result of the original function
     after,
   },
+  Event: Event,
 };
 
 export default PluginApi;