@player-tools/devtools-client 0.5.3-next.0 → 0.6.0-next.0

package/src/state/__tests__/reducer.test.ts

@@ -0,0 +1,362 @@
+import { describe, expect, test } from "vitest";
+import type {
+  Transaction,
+  DevtoolsDataChangeEvent,
+  PlayerInitEvent,
+  DevtoolsFlowChangeEvent,
+  DevtoolsEventsBatchEvent,
+  PlayerStoppedEvent,
+  ExtensionSelectedPlayerEvent,
+  ExtensionSelectedPluginEvent,
+} from "@player-tools/devtools-types";
+import { reducer } from "../reducer";
+import { INITIAL_EXTENSION_STATE, INITIAL_FLOW } from "../../constants";
+
+const mockPlayerInitTransaction: Transaction<PlayerInitEvent> = {
+  id: 1,
+  timestamp: Date.now(),
+  sender: "sender-id",
+  target: "target-id",
+  context: "player",
+  _messenger_: true,
+  type: "PLAYER_DEVTOOLS_PLAYER_INIT",
+  payload: {
+    plugins: {
+      "plugin-id": {
+        id: "plugin-id",
+        description: "Plugin Description",
+        flow: INITIAL_FLOW,
+        name: "Plugin Name",
+        version: "1.0.0",
+      },
+    },
+  },
+};
+
+const mockPlayerFlowChangeTransaction: Transaction<DevtoolsFlowChangeEvent> = {
+  id: 2,
+  timestamp: Date.now(),
+  sender: "sender-id",
+  target: "target-id",
+  context: "player",
+  _messenger_: true,
+  type: "PLAYER_DEVTOOLS_PLUGIN_FLOW_CHANGE",
+  payload: {
+    flow: {
+      ...INITIAL_FLOW,
+      data: {
+        key: "value",
+      },
+    },
+    pluginID: "plugin-id",
+  },
+};
+
+const mockPluginDataChangeTransaction: Transaction<DevtoolsDataChangeEvent> = {
+  id: 2,
+  timestamp: Date.now(),
+  sender: "sender-id",
+  target: "target-id",
+  context: "player",
+  _messenger_: true,
+  type: "PLAYER_DEVTOOLS_PLUGIN_DATA_CHANGE",
+  payload: {
+    data: {
+      key: "value",
+    },
+    pluginID: "plugin-id",
+  },
+};
+
+const mockEventBatchTransaction: Transaction<DevtoolsEventsBatchEvent> = {
+  id: 4,
+  timestamp: Date.now(),
+  sender: "sender-id",
+  target: "target-id",
+  context: "player",
+  _messenger_: true,
+  type: "MESSENGER_EVENT_BATCH",
+  payload: {
+    events: [
+      mockPlayerInitTransaction,
+      mockPlayerFlowChangeTransaction,
+      mockPluginDataChangeTransaction,
+    ],
+  },
+};
+
+const mockPlayerStoppedTransaction: Transaction<PlayerStoppedEvent> = {
+  id: 5,
+  timestamp: Date.now(),
+  sender: "sender-id",
+  target: "target-id",
+  context: "player",
+  _messenger_: true,
+  type: "PLAYER_DEVTOOLS_PLAYER_STOPPED",
+  payload: null,
+};
+
+const mockPlayerSelectedTransaction: Transaction<ExtensionSelectedPlayerEvent> =
+  {
+    id: 6,
+    timestamp: Date.now(),
+    sender: "sender-id",
+    target: "target-id",
+    context: "player",
+    _messenger_: true,
+    type: "PLAYER_DEVTOOLS_PLAYER_SELECTED",
+    payload: {
+      playerID: "player-id",
+    },
+  };
+
+const mockPluginSelectedTransaction: Transaction<ExtensionSelectedPluginEvent> =
+  {
+    id: 7,
+    timestamp: Date.now(),
+    sender: "sender-id",
+    target: "target-id",
+    context: "player",
+    _messenger_: true,
+    type: "PLAYER_DEVTOOLS_PLUGIN_SELECTED",
+    payload: {
+      pluginID: "plugin-id",
+    },
+  };
+
+describe("reducer", () => {
+  test("PLAYER_DEVTOOLS_PLAYER_INIT", () => {
+    const newState = reducer(
+      INITIAL_EXTENSION_STATE,
+      mockPlayerInitTransaction
+    );
+
+    expect(newState).toMatchInlineSnapshot(`
+      {
+        "current": {
+          "player": "sender-id",
+          "plugin": "plugin-id",
+        },
+        "players": {
+          "sender-id": {
+            "active": true,
+            "plugins": {
+              "plugin-id": {
+                "description": "Plugin Description",
+                "flow": {
+                  "id": "initial-flow",
+                  "navigation": {
+                    "BEGIN": "FLOW_1",
+                    "FLOW_1": {
+                      "VIEW_1": {
+                        "ref": "view-1",
+                        "state_type": "VIEW",
+                        "transitions": {},
+                      },
+                      "startState": "VIEW_1",
+                    },
+                  },
+                  "views": [
+                    {
+                      "id": "view-1",
+                      "type": "text",
+                      "value": "connecting...",
+                    },
+                  ],
+                },
+                "id": "plugin-id",
+                "name": "Plugin Name",
+                "version": "1.0.0",
+              },
+            },
+          },
+        },
+      }
+    `);
+  });
+
+  test("PLAYER_DEVTOOLS_PLUGIN_FLOW_CHANGE", () => {
+    const newState = reducer(
+      INITIAL_EXTENSION_STATE,
+      mockPlayerFlowChangeTransaction
+    );
+
+    expect(newState).toMatchInlineSnapshot(`
+      {
+        "current": {
+          "player": null,
+          "plugin": null,
+        },
+        "players": {
+          "sender-id": {
+            "plugins": {
+              "plugin-id": {
+                "flow": {
+                  "data": {
+                    "key": "value",
+                  },
+                  "id": "initial-flow",
+                  "navigation": {
+                    "BEGIN": "FLOW_1",
+                    "FLOW_1": {
+                      "VIEW_1": {
+                        "ref": "view-1",
+                        "state_type": "VIEW",
+                        "transitions": {},
+                      },
+                      "startState": "VIEW_1",
+                    },
+                  },
+                  "views": [
+                    {
+                      "id": "view-1",
+                      "type": "text",
+                      "value": "connecting...",
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      }
+    `);
+  });
+
+  test("PLAYER_DEVTOOLS_PLUGIN_DATA_CHANGE", () => {
+    const newState = reducer(
+      INITIAL_EXTENSION_STATE,
+      mockPluginDataChangeTransaction
+    );
+
+    expect(newState).toMatchInlineSnapshot(`
+      {
+        "current": {
+          "player": null,
+          "plugin": null,
+        },
+        "players": {
+          "sender-id": {
+            "plugins": {
+              "plugin-id": {
+                "flow": {
+                  "data": {
+                    "key": "value",
+                  },
+                },
+              },
+            },
+          },
+        },
+      }
+    `);
+  });
+
+  test("MESSENGER_EVENT_BATCH", () => {
+    const newState = reducer(
+      INITIAL_EXTENSION_STATE,
+      mockEventBatchTransaction
+    );
+
+    expect(newState).toMatchInlineSnapshot(`
+      {
+        "current": {
+          "player": "sender-id",
+          "plugin": "plugin-id",
+        },
+        "players": {
+          "sender-id": {
+            "active": true,
+            "plugins": {
+              "plugin-id": {
+                "description": "Plugin Description",
+                "flow": {
+                  "data": {
+                    "key": "value",
+                  },
+                  "id": "initial-flow",
+                  "navigation": {
+                    "BEGIN": "FLOW_1",
+                    "FLOW_1": {
+                      "VIEW_1": {
+                        "ref": "view-1",
+                        "state_type": "VIEW",
+                        "transitions": {},
+                      },
+                      "startState": "VIEW_1",
+                    },
+                  },
+                  "views": [
+                    {
+                      "id": "view-1",
+                      "type": "text",
+                      "value": "connecting...",
+                    },
+                  ],
+                },
+                "id": "plugin-id",
+                "name": "Plugin Name",
+                "version": "1.0.0",
+              },
+            },
+          },
+        },
+      }
+    `);
+  });
+
+  test("PLAYER_DEVTOOLS_PLAYER_STOPPED", () => {
+    const newState = reducer(
+      INITIAL_EXTENSION_STATE,
+      mockPlayerStoppedTransaction
+    );
+
+    expect(newState).toMatchInlineSnapshot(`
+      {
+        "current": {
+          "player": null,
+          "plugin": null,
+        },
+        "players": {
+          "sender-id": {
+            "active": false,
+          },
+        },
+      }
+    `);
+  });
+
+  test("PLAYER_DEVTOOLS_PLAYER_SELECTED", () => {
+    const newState = reducer(
+      INITIAL_EXTENSION_STATE,
+      mockPlayerSelectedTransaction
+    );
+
+    expect(newState).toMatchInlineSnapshot(`
+      {
+        "current": {
+          "player": "player-id",
+          "plugin": null,
+        },
+        "players": {},
+      }
+    `);
+  });
+
+  test("PLAYER_DEVTOOLS_PLUGIN_SELECTED", () => {
+    const newState = reducer(
+      INITIAL_EXTENSION_STATE,
+      mockPluginSelectedTransaction
+    );
+
+    expect(newState).toMatchInlineSnapshot(`
+      {
+        "current": {
+          "player": null,
+          "plugin": "plugin-id",
+        },
+        "players": {},
+      }
+    `);
+  });
+});

package/src/state/index.ts

@@ -0,0 +1,117 @@
+import { Messenger } from "@player-tools/devtools-messenger";
+import type {
+  ExtensionSupportedEvents,
+  MessengerOptions,
+} from "@player-tools/devtools-types";
+import { useCallback, useEffect, useMemo, useReducer } from "react";
+
+import { INITIAL_EXTENSION_STATE } from "../constants";
+import { reducer } from "./reducer";
+
+const NOOP_ID = -1;
+
+/**
+ * Custom React hook for managing the state of the devtools extension.
+ *
+ * This hook initializes the extension's state and sets up a communication layer
+ * using the `Messenger` class. It provides methods to select a player or plugin,
+ * and handle interactions, which dispatch actions to update the state accordingly.
+ *
+ */
+export const useExtensionState = ({
+  communicationLayer,
+}: {
+  /** the communication layer to use for the extension */
+  communicationLayer: Pick<
+    MessengerOptions<ExtensionSupportedEvents>,
+    "sendMessage" | "addListener" | "removeListener"
+  >;
+}) => {
+  const [state, dispatch] = useReducer(reducer, INITIAL_EXTENSION_STATE);
+
+  const messengerOptions = useMemo<MessengerOptions<ExtensionSupportedEvents>>(
+    () => ({
+      context: "devtools",
+      target: "player",
+      messageCallback: (message) => {
+        dispatch(message);
+      },
+      ...communicationLayer,
+      logger: console,
+    }),
+    [dispatch, communicationLayer]
+  );
+
+  const messenger = useMemo(
+    () => new Messenger(messengerOptions),
+    [messengerOptions]
+  );
+
+  useEffect(() => {
+    return () => {
+      messenger.destroy();
+    };
+  }, []);
+
+  const selectPlayer = useCallback(
+    (playerID: string) => {
+      dispatch({
+        id: NOOP_ID,
+        sender: "internal",
+        context: "devtools",
+        _messenger_: false,
+        timestamp: Date.now(),
+        type: "PLAYER_DEVTOOLS_PLAYER_SELECTED",
+        payload: {
+          playerID,
+        },
+      });
+    },
+    [dispatch]
+  );
+
+  const selectPlugin = useCallback(
+    (pluginID: string) => {
+      dispatch({
+        id: NOOP_ID,
+        sender: "internal",
+        context: "devtools",
+        _messenger_: false,
+        timestamp: Date.now(),
+        type: "PLAYER_DEVTOOLS_PLUGIN_SELECTED",
+        payload: {
+          pluginID,
+        },
+      });
+    },
+    [dispatch]
+  );
+
+  /**
+   * Plugin authors can add interactive elements to the Player-UI content by leveraging
+   * the pub-sub plugin and having the handle interaction proxy the message to the inspected
+   * Player-UI instance.
+   */
+  const handleInteraction = useCallback(
+    ({
+      type,
+      payload,
+    }: {
+      /** interaction type */
+      type: string;
+      /** interaction payload */
+      payload?: string;
+    }) => {
+      messenger.sendMessage({
+        type: "PLAYER_DEVTOOLS_PLUGIN_INTERACTION",
+        payload: {
+          type,
+          payload,
+        },
+      });
+    },
+    [messenger]
+  );
+
+  return { state, selectPlayer, selectPlugin, handleInteraction };
+};

package/src/state/reducer.ts

@@ -0,0 +1,80 @@
+import type {
+  ExtensionState,
+  ExtensionSupportedEvents,
+  Transaction,
+} from "@player-tools/devtools-types";
+import { dset } from "dset/merge";
+import { produce } from "immer";
+
+/** Extension state reducer */
+export const reducer = (
+  state: ExtensionState,
+  transaction: Transaction<ExtensionSupportedEvents>
+): ExtensionState => {
+  switch (transaction.type) {
+    case "PLAYER_DEVTOOLS_PLAYER_INIT":
+      return produce(state, (draft) => {
+        const {
+          sender,
+          payload: { plugins },
+        } = transaction;
+        const { player, plugin } = draft.current;
+
+        if (!player && !plugin) {
+          // if there is no player and plugin selected, select the first one:
+          dset(draft, ["current", "player"], sender);
+          dset(
+            draft,
+            ["current", "plugin"],
+            plugins[Object.keys(plugins)[0]].id
+          );
+        }
+
+        dset(draft, ["players", sender, "plugins"], plugins);
+        dset(draft, ["players", sender, "active"], true);
+      });
+    case "PLAYER_DEVTOOLS_PLUGIN_FLOW_CHANGE":
+      return produce(state, (draft) => {
+        const {
+          sender,
+          payload: { flow, pluginID },
+        } = transaction;
+
+        dset(draft, ["players", sender, "plugins", pluginID, "flow"], flow);
+      });
+    case "PLAYER_DEVTOOLS_PLUGIN_DATA_CHANGE":
+      return produce(state, (draft) => {
+        const {
+          sender,
+          payload: { data, pluginID },
+        } = transaction;
+        dset(
+          draft,
+          ["players", sender, "plugins", pluginID, "flow", "data"],
+          data
+        );
+      });
+    case "MESSENGER_EVENT_BATCH":
+      return produce(state, (draft) => {
+        return transaction.payload.events.reduce(reducer, draft);
+      });
+    case "PLAYER_DEVTOOLS_PLAYER_STOPPED":
+      return produce(state, (draft) => {
+        const { sender } = transaction;
+
+        dset(draft, ["players", sender, "active"], false);
+      });
+    case "PLAYER_DEVTOOLS_PLAYER_SELECTED":
+      return produce(state, (draft) => {
+        const { playerID } = transaction.payload;
+        dset(draft, ["current", "player"], playerID);
+      });
+    case "PLAYER_DEVTOOLS_PLUGIN_SELECTED":
+      return produce(state, (draft) => {
+        const { pluginID } = transaction.payload;
+        dset(draft, ["current", "plugin"], pluginID);
+      });
+    default:
+      return state;
+  }
+};

package/types/constants/index.d.ts

@@ -0,0 +1,5 @@
+import type { ExtensionState } from "@player-tools/devtools-types";
+import type { Flow } from "@player-ui/react";
+export declare const INITIAL_FLOW: Flow;
+export declare const INITIAL_EXTENSION_STATE: ExtensionState;
+//# sourceMappingURL=index.d.ts.map

package/types/helpers/flowDiff.d.ts

@@ -0,0 +1,21 @@
+import type { Flow } from "@player-ui/react";
+/**
+ * Compares two Flow objects and identifies if there's a change in their structure or data.
+ *
+ * This function takes two Flow objects as input, `curr` (current) and `next` (next), and compares them
+ * to determine if there's a change in the flow's structure or its data. If there's a change in the flow's
+ * structure (excluding the `data` property), it returns an object indicating a "flow" change along with the
+ * new flow. If there's a change in the `data` property, it returns an object indicating a "data" change along
+ * with the new data. If there are no changes, it returns null.
+ */
+export declare const flowDiff: ({ curr, next, }: {
+    curr: Flow;
+    next: Flow;
+}) => {
+    change: "data";
+    value: Flow["data"];
+} | {
+    change: "flow";
+    value: Flow;
+} | null;
+//# sourceMappingURL=flowDiff.d.ts.map

package/types/index.d.ts

@@ -1,4 +1,2 @@
-export * from "./redux";
-export * from "./rpc";
-export * from "@player-tools/devtools-common";
+export { Panel } from "./panel";
 //# sourceMappingURL=index.d.ts.map

package/types/panel/index.d.ts

@@ -0,0 +1,31 @@
+import React from "react";
+import type { MessengerOptions, ExtensionSupportedEvents } from "@player-tools/devtools-types";
+/**
+ * Panel Component
+ *
+ * This component serves as the main container for the devtools plugin content defined by plugin authors using Player-UI DSL.
+ *
+ * Props:
+ * - `communicationLayer`: An object that allows communication between the devtools and the Player-UI plugins,
+ *   enabling the exchange of data and events.
+ *
+ * Features:
+ * - Error Handling: Utilizes the `ErrorBoundary` component from `react-error-boundary` to gracefully handle and display errors
+ *   that may occur during the rendering of the plugin's content.
+ * - State Management: Integrates with custom hooks such as `useExtensionState` to manage the state of the plugin and its components.
+ * - Player Integration: Uses the `useReactPlayer` hook from `player-ui/react` to render interactive player components based on the
+ *   DSL defined by the plugin authors.
+ *
+ * Example Usage:
+ * ```tsx
+ * <Panel communicationLayer={myCommunicationLayer} />
+ * ```
+ *
+ * Note: The `communicationLayer` prop is essential for the proper functioning of the `Panel` component, as it enables the necessary
+ * communication and data exchange with the player-ui/react library.
+ */
+export declare const Panel: ({ communicationLayer, }: {
+    /** the communication layer to use for the extension */
+    readonly communicationLayer: Pick<MessengerOptions<ExtensionSupportedEvents>, "sendMessage" | "addListener" | "removeListener">;
+}) => React.JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/types/panel/theme.d.ts

@@ -0,0 +1,2 @@
+export declare const theme: Record<string, any>;
+//# sourceMappingURL=theme.d.ts.map

package/types/plugins/index.d.ts

@@ -0,0 +1,5 @@
+import { PubSubPlugin } from "@player-ui/pubsub-plugin";
+import type { ReactPlayerPlugin } from "@player-ui/react";
+export declare const PUBSUB_PLUGIN: PubSubPlugin;
+export declare const PLAYER_PLUGINS: ReactPlayerPlugin[];
+//# sourceMappingURL=index.d.ts.map

package/types/state/index.d.ts

@@ -0,0 +1,24 @@
+import type { ExtensionSupportedEvents, MessengerOptions } from "@player-tools/devtools-types";
+/**
+ * Custom React hook for managing the state of the devtools extension.
+ *
+ * This hook initializes the extension's state and sets up a communication layer
+ * using the `Messenger` class. It provides methods to select a player or plugin,
+ * and handle interactions, which dispatch actions to update the state accordingly.
+ *
+ */
+export declare const useExtensionState: ({ communicationLayer, }: {
+    /** the communication layer to use for the extension */
+    communicationLayer: Pick<MessengerOptions<ExtensionSupportedEvents>, "sendMessage" | "addListener" | "removeListener">;
+}) => {
+    state: import("@player-tools/devtools-types").ExtensionState;
+    selectPlayer: (playerID: string) => void;
+    selectPlugin: (pluginID: string) => void;
+    handleInteraction: ({ type, payload, }: {
+        /** interaction type */
+        type: string;
+        /** interaction payload */
+        payload?: string | undefined;
+    }) => void;
+};
+//# sourceMappingURL=index.d.ts.map

package/types/state/reducer.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionState, ExtensionSupportedEvents, Transaction } from "@player-tools/devtools-types";
+/** Extension state reducer */
+export declare const reducer: (state: ExtensionState, transaction: Transaction<ExtensionSupportedEvents>) => ExtensionState;
+//# sourceMappingURL=reducer.d.ts.map