@player-ui/react 0.16.0--canary.866.36538 → 1.0.0-next.0

package/src/manager/__tests__/__snapshots__/managed-player.test.tsx.snap

@@ -0,0 +1,249 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ManagedPlayer with React 17 > handles new manager 1`] = `
+{
+  "data": {},
+  "id": "generated-flow",
+  "navigation": {
+    "BEGIN": "FLOW_1",
+    "FLOW_1": {
+      "END_Done": {
+        "outcome": "done",
+        "state_type": "END",
+      },
+      "VIEW_1": {
+        "ref": "flow-1-1",
+        "state_type": "VIEW",
+        "transitions": {
+          "*": "END_Done",
+        },
+      },
+      "startState": "VIEW_1",
+    },
+  },
+  "views": [
+    {
+      "id": "flow-1-1",
+      "type": "collection",
+      "values": [
+        {
+          "asset": {
+            "id": "action",
+            "label": "Continue",
+            "type": "action",
+            "value": "Next",
+          },
+        },
+      ],
+    },
+  ],
+}
+`;
+
+exports[`ManagedPlayer with React 17 > handles new manager 2`] = `
+{
+  "data": {},
+  "id": "generated-flow",
+  "navigation": {
+    "BEGIN": "FLOW_1",
+    "FLOW_1": {
+      "END_Done": {
+        "outcome": "done",
+        "state_type": "END",
+      },
+      "VIEW_1": {
+        "ref": "flow-1-2",
+        "state_type": "VIEW",
+        "transitions": {
+          "*": "END_Done",
+        },
+      },
+      "startState": "VIEW_1",
+    },
+  },
+  "views": [
+    {
+      "id": "flow-1-2",
+      "type": "collection",
+      "values": [
+        {
+          "asset": {
+            "id": "action",
+            "label": "Continue",
+            "type": "action",
+            "value": "Next",
+          },
+        },
+      ],
+    },
+  ],
+}
+`;
+
+exports[`ManagedPlayer with React 17 > handles terminating with data 1`] = `
+{
+  "data": {
+    "returns": {
+      "id": "123",
+    },
+  },
+  "id": "generated-flow",
+  "navigation": {
+    "BEGIN": "FLOW_1",
+    "FLOW_1": {
+      "END_Done": {
+        "outcome": "done",
+        "state_type": "END",
+      },
+      "VIEW_1": {
+        "ref": "flow-1",
+        "state_type": "VIEW",
+        "transitions": {
+          "*": "END_Done",
+        },
+      },
+      "startState": "VIEW_1",
+    },
+  },
+  "views": [
+    {
+      "id": "flow-1",
+      "type": "collection",
+      "values": [
+        {
+          "asset": {
+            "id": "action",
+            "label": "Continue",
+            "type": "action",
+            "value": "Next",
+          },
+        },
+      ],
+    },
+  ],
+}
+`;
+
+exports[`ManagedPlayer with React 18 > handles new manager 1`] = `
+{
+  "data": {},
+  "id": "generated-flow",
+  "navigation": {
+    "BEGIN": "FLOW_1",
+    "FLOW_1": {
+      "END_Done": {
+        "outcome": "done",
+        "state_type": "END",
+      },
+      "VIEW_1": {
+        "ref": "flow-1-1",
+        "state_type": "VIEW",
+        "transitions": {
+          "*": "END_Done",
+        },
+      },
+      "startState": "VIEW_1",
+    },
+  },
+  "views": [
+    {
+      "id": "flow-1-1",
+      "type": "collection",
+      "values": [
+        {
+          "asset": {
+            "id": "action",
+            "label": "Continue",
+            "type": "action",
+            "value": "Next",
+          },
+        },
+      ],
+    },
+  ],
+}
+`;
+
+exports[`ManagedPlayer with React 18 > handles new manager 2`] = `
+{
+  "data": {},
+  "id": "generated-flow",
+  "navigation": {
+    "BEGIN": "FLOW_1",
+    "FLOW_1": {
+      "END_Done": {
+        "outcome": "done",
+        "state_type": "END",
+      },
+      "VIEW_1": {
+        "ref": "flow-1-2",
+        "state_type": "VIEW",
+        "transitions": {
+          "*": "END_Done",
+        },
+      },
+      "startState": "VIEW_1",
+    },
+  },
+  "views": [
+    {
+      "id": "flow-1-2",
+      "type": "collection",
+      "values": [
+        {
+          "asset": {
+            "id": "action",
+            "label": "Continue",
+            "type": "action",
+            "value": "Next",
+          },
+        },
+      ],
+    },
+  ],
+}
+`;
+
+exports[`ManagedPlayer with React 18 > handles terminating with data 1`] = `
+{
+  "data": {
+    "returns": {
+      "id": "123",
+    },
+  },
+  "id": "generated-flow",
+  "navigation": {
+    "BEGIN": "FLOW_1",
+    "FLOW_1": {
+      "END_Done": {
+        "outcome": "done",
+        "state_type": "END",
+      },
+      "VIEW_1": {
+        "ref": "flow-1",
+        "state_type": "VIEW",
+        "transitions": {
+          "*": "END_Done",
+        },
+      },
+      "startState": "VIEW_1",
+    },
+  },
+  "views": [
+    {
+      "id": "flow-1",
+      "type": "collection",
+      "values": [
+        {
+          "asset": {
+            "id": "action",
+            "label": "Continue",
+            "type": "action",
+            "value": "Next",
+          },
+        },
+      ],
+    },
+  ],
+}
+`;

package/src/manager/__tests__/managed-player.test.tsx

@@ -10,6 +10,7 @@ import {
 import { ManagedPlayer } from "../managed-player";
 import type { FlowManager, FallbackProps } from "../types";
 import { SimpleAssetPlugin } from "../../__tests__/helpers/simple-asset-plugin";
+import { InProgressState } from "@player-ui/player";
 
 vitest.mock("@player-ui/metrics-plugin", async () => {
   const actual: object = await vitest.importActual("@player-ui/metrics-plugin");
@@ -452,7 +453,11 @@ describe.each([
 
     await screen.findByTestId("flow-1");
     result.unmount();
-    expect(manager.terminate).toBeCalledWith({ returns: { id: "123" } });
+
+    const terminateArgument: InProgressState =
+      manager.terminate?.mock.calls[0][0];
+    expect(terminateArgument.flow).toMatchSnapshot();
+    expect(terminateArgument.status).toBe("in-progress");
   });
 
   test("handles new manager", async () => {
@@ -557,7 +562,13 @@ describe.each([
     let newManagerBtn = await screen.findByTestId("newManager");
     await user.click(newManagerBtn);
 
-    expect(previousManager.current.terminate).toBeCalledWith({});
+    // terminate should receive an InProgressState
+    expect(previousManager.current.terminate).toBeCalled();
+    const terminateArgument1: InProgressState =
+      previousManager.current.terminate?.mock.calls[0][0];
+    expect(terminateArgument1.flow).toMatchSnapshot();
+    expect(terminateArgument1.status).toBe("in-progress");
+
     expect(previousManager.current.next).toBeCalledTimes(1);
     expect(manager.next).toBeCalledTimes(1);
     await screen.findByTestId("flow-1-2");
@@ -566,7 +577,13 @@ describe.each([
     await user.click(newManagerBtn);
 
     const prevMan = previousManager.current;
-    expect(prevMan.terminate).toBeCalledWith({});
+    // terminate should receive an InProgressState
+    expect(prevMan.terminate).toBeCalled();
+    const terminateArgument2: InProgressState =
+      prevMan.terminate?.mock.calls[0][0];
+    expect(terminateArgument2.flow).toMatchSnapshot();
+    expect(terminateArgument2.status).toBe("in-progress");
+
     expect(prevMan.next).toBeCalledTimes(1);
     expect(manager.next).toBeCalledTimes(1);
     await screen.findByTestId("flow-1-3");

package/src/manager/managed-player.tsx

@@ -252,9 +252,7 @@ export const usePersistentStateMachine = (options: {
         oldManagedState.state?.value === "running" &&
         playerState?.status === "in-progress"
       ) {
-        previousManager.current.terminate?.(
-          playerState.controllers.data.serialize(),
-        );
+        previousManager.current.terminate?.(playerState);
       }
     }
 
@@ -341,7 +339,7 @@ export const ManagedPlayer = (
     } else if (state?.value === "error") {
       props.onError?.(state?.context.error);
     } else if (state?.value === "running") {
-      props.onStartedFlow?.();
+      props.onStartedFlow?.(state.context.flow);
     }
   }
 
@@ -352,7 +350,7 @@ export const ManagedPlayer = (
       const playerState = state?.context.reactPlayer.player.getState();
 
       if (state?.value === "running" && playerState?.status === "in-progress") {
-        props.manager.terminate?.(playerState.controllers.data.serialize());
+        props.manager.terminate?.(playerState);
       }
     };
   }, [props.manager, state?.context.reactPlayer.player, state?.value]);

package/src/manager/types.ts

@@ -1,5 +1,5 @@
 import type React from "react";
-import type { CompletedState, Flow, FlowResult } from "@player-ui/player";
+import type { CompletedState, Flow, InProgressState } from "@player-ui/player";
 import type { ReactPlayer, ReactPlayerOptions } from "../player";
 
 export interface FinalState {
@@ -7,14 +7,16 @@ export interface FinalState {
   done: true;
 }
 
-export interface NextState<T> {
+export interface NextState {
   /** Optional mark the iteration as _not_ completed */
-  done?: false;
+  done: false;
 
   /** The next value in the iteration */
-  value: T;
+  value: Flow;
 }
 
+/** A JS Iterator that returns a new flow or completion marker
+ * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator */
 export interface FlowManager {
   /**
    * An iterator implementation that takes the result of the previous flow and returns a new one or completion marker.
@@ -23,15 +25,13 @@ export interface FlowManager {
    *
    * @param previousValue - The result of the previous flow.
    */
-  next: (
-    previousValue?: CompletedState,
-  ) => Promise<FinalState | NextState<Flow>>;
+  next: (result?: CompletedState) => Promise<FinalState | NextState>;
 
   /**
    * Called when the flow is ended early (the react tree is torn down)
    * Allows clients the opportunity to save-data before destroying the tree
    */
-  terminate?: (data?: FlowResult["data"]) => void;
+  terminate?: (state?: InProgressState) => void;
 }
 
 export interface FallbackProps {
@@ -50,7 +50,7 @@ export interface ManagedPlayerProps extends ReactPlayerOptions {
   manager: FlowManager;
 
   /** A callback when a flow is started */
-  onStartedFlow?: () => void;
+  onStartedFlow?: (flow: Flow) => void;
 
   /** A callback when the entire async iteration is completed */
   onComplete?: (finalState?: CompletedState) => void;
@@ -91,7 +91,7 @@ export type ManagedPlayerState =
         prevResult?: CompletedState;
 
         /** A promise from the flow manager for the next state */
-        next: Promise<FinalState | NextState<Flow>>;
+        next: Promise<FinalState | NextState>;
       };
     }
   | {

package/src/player.tsx

@@ -1,18 +1,20 @@
 import React from "react";
 import { SyncWaterfallHook, AsyncParallelHook } from "tapable-ts";
-import { Subscribe, useSubscribedState } from "@player-ui/react-subscribe";
+import {
+  Subscribe,
+  useSubscribedState,
+  useSubscriber,
+} from "@player-ui/react-subscribe";
 import { Registry } from "@player-ui/partial-match-registry";
 import type {
-  A2UISnapshot,
   CompletedState,
   PlayerPlugin,
   Flow,
   View,
   PlayerInfo,
-  StartOptions,
 } from "@player-ui/player";
 import { Player } from "@player-ui/player";
-import { ErrorBoundary } from "react-error-boundary";
+import { ErrorBoundary, FallbackProps } from "react-error-boundary";
 import type { AssetRegistryType } from "./asset";
 import { AssetContext } from "./asset";
 import { PlayerContext } from "./utils";
@@ -21,6 +23,10 @@ import type { ReactPlayerProps } from "./app";
 import { ReactPlayer as PlayerComp } from "./app";
 import { OnUpdatePlugin } from "./plugins/onupdate-plugin";
 
+/** Backup context for receiving ReactPlayerComponentProps when components setup in the webComponent call don't pass the props down to their inner components. */
+export const ReactPlayerPropsContext: React.Context<ReactPlayerComponentProps> =
+  React.createContext<ReactPlayerComponentProps>({ isInErrorState: false });
+
 export interface DevtoolsGlobals {
   /** A global for a plugin to load to Player for devtools */
   __PLAYER_DEVTOOLS_PLUGIN?: {
@@ -54,7 +60,11 @@ export interface ReactPlayerOptions {
   plugins?: Array<ReactPlayerPlugin>;
 }
 
-export type ReactPlayerComponentProps = Record<string, unknown>;
+export type ReactPlayerComponentProps = {
+  /** Whether or not player is currently recovering from an error. */
+  isInErrorState?: boolean;
+  [key: string]: unknown;
+};
 
 /** A Player that renders UI through React */
 export class ReactPlayer {
@@ -66,7 +76,10 @@ export class ReactPlayer {
     /**
      * A hook to create a React Component to be used for Player, regardless of the current flow state
      */
-    webComponent: SyncWaterfallHook<[React.ComponentType], Record<string, any>>;
+    webComponent: SyncWaterfallHook<
+      [React.ComponentType<any>],
+      Record<string, any>
+    >;
     /**
      * A hook to create a React Component that's used to render a specific view.
      * It will be called for each view update from the core player.
@@ -99,7 +112,8 @@ export class ReactPlayer {
     onBeforeViewReset: new AsyncParallelHook(),
   };
 
-  public readonly viewUpdateSubscription = new Subscribe<View>();
+  public readonly viewUpdateSubscription: Subscribe<View> =
+    new Subscribe<View>();
   private reactPlayerInfo: ReactPlayerInfo;
 
   constructor(options?: ReactPlayerOptions) {
@@ -155,11 +169,20 @@ export class ReactPlayer {
   }
 
   /** Register and apply [Plugin] if one with the same symbol is not already registered. */
-  public registerPlugin(plugin: ReactPlayerPlugin): void {
-    if (!plugin.applyReact) return;
+  public registerPlugin(plugin: ReactPlayerPlugin | PlayerPlugin): void {
+    if (plugin.apply) {
+      this.player.registerPlugin(plugin as PlayerPlugin);
+    }
+
+    if ((plugin as ReactPlayerPlugin).applyReact) {
+      (plugin as ReactPlayerPlugin).applyReact?.(this);
+    }
+
+    if (!this.options.plugins) {
+      this.options.plugins = [];
+    }
 
-    plugin.applyReact(this);
-    this.options.plugins?.push(plugin);
+    this.options.plugins.push(plugin);
   }
 
   /**
@@ -183,20 +206,118 @@ export class ReactPlayer {
 
     /** Wrap the Error boundary and context provider after the hook call to catch anything wrapped by the hook */
     const ReactPlayerComponent = (props: ReactPlayerComponentProps) => {
+      const trackedErrors = React.useRef(new Map<Error, boolean>());
+      const [errorSubId, setErrorSubId] = React.useState<number | undefined>(
+        undefined,
+      );
+      const { subscribe, unsubscribe } = useSubscriber(
+        this.viewUpdateSubscription,
+      );
+
+      const componentProps: ReactPlayerComponentProps = React.useMemo(
+        () => ({
+          ...props,
+          isInErrorState: errorSubId !== undefined,
+        }),
+        [props, errorSubId],
+      );
+
+      /** Callback to remove all tracked errors and unsub from  */
+      const clearErrorTracking = React.useCallback(() => {
+        trackedErrors.current.clear();
+        setErrorSubId((prev) => {
+          if (prev !== undefined) {
+            unsubscribe(prev);
+          }
+
+          return undefined;
+        });
+      }, []);
+
+      React.useEffect(() => {
+        // Clear errors and error subscription on unmount
+        return clearErrorTracking;
+      }, [clearErrorTracking]);
+
+      /** capture error and return true or false to represent if we are recovering from the error or not. */
+      const captureError = React.useCallback(
+        (err: Error) => {
+          // If player isn't in progress we can't actually render anything so render errors are irrelevant.
+          const playerState = this.player.getState();
+          if (playerState.status !== "in-progress") {
+            this.player.logger.warn(
+              `[ReactPlayer]: An error occurred during rendering but was ignored due to a change in the player state (current state: '${playerState.status}'). Error Details:`,
+              err,
+            );
+            return false;
+          }
+
+          // Only capture each error once.
+          const currentError = trackedErrors.current.get(err);
+          if (currentError !== undefined) {
+            return currentError;
+          }
+
+          let isRecovering = false;
+          setErrorSubId((prev) => {
+            // subscribe only if no subscription available.
+            // Needs to happen before capture error to ensure error recovery isn't missed
+            const subId =
+              prev === undefined
+                ? subscribe(clearErrorTracking, {
+                    initializeWithPreviousValue: false,
+                  })
+                : prev;
+
+            // Get skipped state after trying to capture.
+            isRecovering = playerState.controllers.error.captureError(err);
+            trackedErrors.current.set(err, isRecovering);
+
+            // If we can't recover from the error, avoid updating state to stay in error boundary
+            if (!isRecovering) {
+              // Unsub if not previously subbed since we don't need to reset the view
+              if (subId !== prev) {
+                unsubscribe(subId);
+              }
+              return prev;
+            }
+
+            return subId;
+          });
+
+          return isRecovering;
+        },
+        [errorSubId],
+      );
+
       return (
         <ErrorBoundary
-          fallbackRender={() => null}
-          onError={(err) => {
-            const playerState = this.player.getState();
+          fallbackRender={(fallbackProps: FallbackProps) => {
+            const isRecovering = captureError(fallbackProps.error);
 
-            if (playerState.status === "in-progress") {
-              playerState.fail(err);
+            if (!isRecovering) {
+              // Display nothing if not recovering. Let the player state fail and handle what the view will be.
+              return null;
             }
+            fallbackProps.resetErrorBoundary();
+
+            // Render the same as on success when recovering to preserve the react tree.
+            return (
+              <ReactPlayerPropsContext.Provider
+                value={{ ...componentProps, isInErrorState: true }}
+              >
+                <PlayerContext.Provider value={{ player: this.player }}>
+                  <BaseComp {...componentProps} isInErrorState />
+                </PlayerContext.Provider>
+              </ReactPlayerPropsContext.Provider>
+            );
           }}
         >
-          <PlayerContext.Provider value={{ player: this.player }}>
-            <BaseComp {...props} />
-          </PlayerContext.Provider>
+          <ReactPlayerPropsContext.Provider value={{ ...componentProps }}>
+            <PlayerContext.Provider value={{ player: this.player }}>
+              <BaseComp {...componentProps} />
+            </PlayerContext.Provider>
+          </ReactPlayerPropsContext.Provider>
         </ErrorBoundary>
       );
     };
@@ -208,17 +329,27 @@ export class ReactPlayer {
     const ActualPlayerComp = this.hooks.playerComponent.call(PlayerComp);
 
     /** the component to use to render the player */
-    const WebPlayerComponent = () => {
+    const WebPlayerComponent: React.ComponentType = (): React.ReactElement => {
+      const { isInErrorState } = React.useContext(ReactPlayerPropsContext);
       const view = useSubscribedState<View>(this.viewUpdateSubscription);
+      const lastSuccessfulView = React.useRef<View | undefined>(undefined);
       this.viewUpdateSubscription.suspend();
 
+      React.useEffect(() => {
+        if (!isInErrorState) {
+          lastSuccessfulView.current = view;
+        }
+      }, [isInErrorState, view]);
+
+      const displayedView = isInErrorState ? lastSuccessfulView.current : view;
+
       return (
         <AssetContext.Provider
           value={{
             registry: this.assetRegistry,
           }}
         >
-          {view && <ActualPlayerComp view={view} />}
+          {displayedView && <ActualPlayerComp view={displayedView} />}
         </AssetContext.Provider>
       );
     };
@@ -238,13 +369,10 @@ export class ReactPlayer {
     );
   }
 
-  public start(
-    payload: Flow | A2UISnapshot,
-    options?: StartOptions,
-  ): Promise<CompletedState> {
+  public start(flow: Flow): Promise<CompletedState> {
     this.setWaitForNextViewUpdate();
 
-    return this.player.start(payload, options).finally(async () => {
+    return this.player.start(flow).finally(async () => {
       await this.setWaitForNextViewUpdate();
     });
   }

package/types/asset/AssetRenderError.d.ts

@@ -1,10 +1,16 @@
-import type { Asset } from "@player-ui/player";
-export declare class AssetRenderError extends Error {
+import { ErrorSeverity, type Asset, type PlayerErrorMetadata } from "@player-ui/player";
+export type AssetRenderErrorMetadata = {
+    assetId: string;
+};
+export declare class AssetRenderError extends Error implements PlayerErrorMetadata<AssetRenderErrorMetadata> {
     readonly rootAsset: Asset;
     readonly innerException?: unknown | undefined;
     private assetParentPath;
     initialMessage: string;
     innerExceptionMessage: string;
+    readonly type: string;
+    readonly severity: ErrorSeverity;
+    readonly metadata: AssetRenderErrorMetadata;
     constructor(rootAsset: Asset, message?: string, innerException?: unknown | undefined);
     private updateMessage;
     getAssetPathMessage(): string;