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

package/src/constants/index.ts

@@ -0,0 +1,32 @@
+import type { ExtensionState } from "@player-tools/devtools-types";
+import type { Flow } from "@player-ui/react";
+
+export const INITIAL_FLOW: Flow = {
+  id: "initial-flow",
+  views: [
+    {
+      id: "view-1",
+      type: "text",
+      value: "connecting...",
+    },
+  ],
+  navigation: {
+    BEGIN: "FLOW_1",
+    FLOW_1: {
+      startState: "VIEW_1",
+      VIEW_1: {
+        state_type: "VIEW",
+        ref: "view-1",
+        transitions: {},
+      },
+    },
+  },
+};
+
+export const INITIAL_EXTENSION_STATE: ExtensionState = {
+  current: {
+    player: null,
+    plugin: null,
+  },
+  players: {},
+};

package/src/helpers/__tests__/flowDiff.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect } from "vitest";
+import type { Flow } from "@player-ui/react";
+import { flowDiff } from "../flowDiff";
+
+const mockFlow1: Flow = {
+  id: "flow",
+  views: [
+    {
+      id: "view",
+      type: "info",
+    },
+  ],
+  data: {
+    foo: "bar",
+  },
+  navigation: {
+    BEGIN: "BEGIN",
+  },
+};
+
+const mockFlow2: Flow = {
+  id: "flow",
+  views: [
+    {
+      id: "view",
+      type: "info",
+    },
+  ],
+  data: {
+    foo: "bar",
+    something: "else",
+  },
+  navigation: {
+    BEGIN: "BEGIN",
+  },
+};
+
+const mockFlow3: Flow = {
+  id: "another_flow",
+  views: [
+    {
+      id: "view",
+      type: "info",
+    },
+  ],
+  data: {
+    foo: "bar",
+  },
+  navigation: {
+    BEGIN: "BEGIN",
+  },
+};
+
+describe("flowDiff", () => {
+  test("returns null if no changes", () => {
+    const result = flowDiff({ curr: mockFlow1, next: mockFlow1 });
+
+    expect(result).toBeNull();
+  });
+
+  test("returns flow change if base flow is different", () => {
+    const result = flowDiff({ curr: mockFlow1, next: mockFlow3 });
+
+    expect(result).toEqual({ change: "flow", value: mockFlow3 });
+  });
+
+  test("returns data change if data is different", () => {
+    const result = flowDiff({ curr: mockFlow1, next: mockFlow2 });
+
+    expect(result).toEqual({ change: "data", value: mockFlow2.data });
+  });
+});

package/src/helpers/flowDiff.ts

@@ -0,0 +1,44 @@
+import type { Flow } from "@player-ui/react";
+import { dequal } from "dequal";
+
+/**
+ * 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 const flowDiff = ({
+  curr,
+  next,
+}: {
+  curr: Flow;
+  next: Flow;
+}):
+  | { change: "data"; value: Flow["data"] }
+  | { change: "flow"; value: Flow }
+  | null => {
+  // compare flows except for the `data` property
+  const currCopy = { ...curr, data: null };
+  const nextCopy = { ...next, data: null };
+
+  const baseFlowIsEqual = dequal(currCopy, nextCopy);
+
+  if (!baseFlowIsEqual) {
+    return { change: "flow", value: next };
+  }
+
+  // compare data
+  const currData = curr.data;
+  const nextData = next.data;
+
+  const dataIsEqual = dequal(currData, nextData);
+
+  if (!dataIsEqual) {
+    return { change: "data", value: nextData };
+  }
+
+  return null;
+};

package/src/index.ts

@@ -1,3 +1 @@
-export * from "./redux";
-export * from "./rpc";
-export * from "@player-tools/devtools-common";
+export { Panel } from "./panel";

package/src/panel/index.tsx

@@ -0,0 +1,212 @@
+import React, { useRef } from "react";
+import type {
+  MessengerOptions,
+  ExtensionSupportedEvents,
+} from "@player-tools/devtools-types";
+import { DataController, Flow, useReactPlayer } from "@player-ui/react";
+import { useEffect } from "react";
+import { ErrorBoundary } from "react-error-boundary";
+import {
+  Card,
+  CardBody,
+  CardHeader,
+  ChakraProvider,
+  Container,
+  Flex,
+  FormControl,
+  FormLabel,
+  Heading,
+  HStack,
+  Select,
+  Text,
+  VStack,
+} from "@chakra-ui/react";
+import { ThemeProvider } from "@devtools-ds/themes";
+
+import { INITIAL_FLOW } from "../constants";
+import { PLAYER_PLUGINS, PUBSUB_PLUGIN } from "../plugins";
+import { useExtensionState } from "../state";
+import { flowDiff } from "../helpers/flowDiff";
+import { theme } from "./theme";
+
+const fallbackRender: ErrorBoundary["props"]["fallbackRender"] = ({
+  error,
+}) => {
+  return (
+    <Container centerContent>
+      <Card>
+        <CardHeader>
+          <Heading>Ops, something went wrong.</Heading>
+        </CardHeader>
+      </Card>
+      <CardBody>
+        <Text as="pre">{error.message}</Text>
+      </CardBody>
+    </Container>
+  );
+};
+
+/**
+ * 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 const Panel = ({
+  communicationLayer,
+}: {
+  /** the communication layer to use for the extension */
+  readonly communicationLayer: Pick<
+    MessengerOptions<ExtensionSupportedEvents>,
+    "sendMessage" | "addListener" | "removeListener"
+  >;
+}) => {
+  const { state, selectPlayer, selectPlugin, handleInteraction } =
+    useExtensionState({
+      communicationLayer,
+    });
+
+  const { reactPlayer } = useReactPlayer({
+    plugins: PLAYER_PLUGINS,
+  });
+
+  const dataController = useRef<WeakRef<DataController> | null>(null);
+
+  const currentFlow = useRef<Flow | null>(null);
+
+  useEffect(() => {
+    reactPlayer.player.hooks.dataController.tap("devtools-panel", (d) => {
+      dataController.current = new WeakRef(d);
+    });
+  }, [reactPlayer]);
+
+  useEffect(() => {
+    // we subscribe to all messages from the devtools plugin
+    // so the plugin author can define their own events
+    PUBSUB_PLUGIN.subscribe("*", (type: string, payload: string) => {
+      handleInteraction({
+        type,
+        payload,
+      });
+    });
+  }, []);
+
+  useEffect(() => {
+    const { player, plugin } = state.current;
+
+    const flow =
+      player && plugin
+        ? state.players[player]?.plugins?.[plugin]?.flow || INITIAL_FLOW
+        : INITIAL_FLOW;
+
+    if (!currentFlow.current) {
+      currentFlow.current = flow;
+      reactPlayer.start(flow);
+      return;
+    }
+
+    const diff = flowDiff({
+      curr: currentFlow.current as Flow,
+      next: flow,
+    });
+
+    if (diff) {
+      const { change, value } = diff;
+
+      if (change === "flow") {
+        currentFlow.current = value;
+        reactPlayer.start(value);
+      } else if (change === "data") {
+        dataController.current
+          ? dataController.current
+              .deref()
+              ?.set(value as Record<string, unknown>)
+          : reactPlayer.start(flow);
+      }
+    }
+  }, [reactPlayer, state]);
+
+  const Component = reactPlayer.Component as React.FC;
+
+  return (
+    <ChakraProvider theme={theme}>
+      <ThemeProvider colorScheme="dark">
+        <ErrorBoundary fallbackRender={fallbackRender}>
+          <VStack w="100vw" h="100vh">
+            {state.current.player ? (
+              <Flex direction="column" marginTop="4">
+                <HStack spacing="4">
+                  <FormControl>
+                    <FormLabel>Player</FormLabel>
+                    <Select
+                      id="player"
+                      value={state.current.player || ""}
+                      onChange={(event) => selectPlayer(event.target.value)}
+                    >
+                      {Object.keys(state.players).map((playerID) => (
+                        <option key={playerID} value={playerID}>
+                          {playerID}
+                        </option>
+                      ))}
+                    </Select>
+                  </FormControl>
+                  <FormControl>
+                    <FormLabel>Plugin</FormLabel>
+                    <Select
+                      id="plugin"
+                      value={state.current.plugin || ""}
+                      onChange={(event) => selectPlugin(event.target.value)}
+                    >
+                      {Object.keys(
+                        state.players[state.current.player].plugins
+                      ).map((pluginID) => (
+                        <option key={pluginID} value={pluginID}>
+                          {pluginID}
+                        </option>
+                      ))}
+                    </Select>
+                  </FormControl>
+                </HStack>
+                <Container marginY="6">
+                  <Component />
+                </Container>
+                <details>
+                  <summary>Debug</summary>
+                  <pre>{JSON.stringify(state, null, 2)}</pre>
+                </details>
+              </Flex>
+            ) : (
+              <Flex justifyContent="center" padding="6">
+                <Text>
+                  No Player-UI instance or devtools plugin detected. Visit{" "}
+                  <a href="https://player-ui.github.io/">
+                    https://player-ui.github.io/
+                  </a>{" "}
+                  for more info.
+                </Text>
+              </Flex>
+            )}
+          </VStack>
+        </ErrorBoundary>
+      </ThemeProvider>
+    </ChakraProvider>
+  );
+};

package/src/panel/theme.ts

@@ -0,0 +1,8 @@
+import { extendTheme, type ThemeConfig } from "@chakra-ui/react";
+
+const config: ThemeConfig = {
+  initialColorMode: "dark",
+  useSystemColorMode: false,
+};
+
+export const theme = extendTheme({ config });

package/src/plugins/index.ts

@@ -0,0 +1,10 @@
+import DevtoolsUIAssetsPlugin from "@devtools-ui/plugin";
+import { PubSubPlugin } from "@player-ui/pubsub-plugin";
+import type { ReactPlayerPlugin } from "@player-ui/react";
+
+export const PUBSUB_PLUGIN = new PubSubPlugin();
+
+export const PLAYER_PLUGINS: ReactPlayerPlugin[] = [
+  new DevtoolsUIAssetsPlugin(),
+  PUBSUB_PLUGIN,
+];