@player-ui/react 0.0.1-next.1

package/src/manager/managed-player.tsx

@@ -0,0 +1,319 @@
+import React from 'react';
+import type {
+  FlowManager,
+  ManagedPlayerProps,
+  ManagedPlayerState,
+  ManagerMiddleware,
+  ManagedPlayerContext,
+} from './types';
+import { useRequestTime } from './request-time';
+import type { WebPlayerOptions } from '../player';
+import { WebPlayer } from '../player';
+
+/** noop middleware */
+function identityMiddleware<T>(next: Promise<T>) {
+  return next;
+}
+
+interface ManagedPlayerStateKey {
+  /** the storage key for the state (outside of the react tree) */
+  _key: symbol;
+}
+
+export interface StateChangeCallback {
+  /** Trigger for state changes */
+  onState: (s: ManagedPlayerState) => void;
+}
+
+/**
+ * An object to store the state of the managed player
+ */
+class ManagedState {
+  public state?: ManagedPlayerState;
+  private callbacks: Array<StateChangeCallback>;
+  private middleware?: ManagerMiddleware;
+
+  constructor({
+    middleware,
+  }: {
+    /** middleware to use in the managed player */
+    middleware?: ManagerMiddleware;
+  }) {
+    this.middleware = middleware;
+    this.callbacks = [];
+  }
+
+  /** Add a listener to state changes */
+  public addListener(callback: StateChangeCallback): () => void {
+    this.callbacks.push(callback);
+
+    return () => {
+      this.callbacks = this.callbacks.filter((s) => s !== callback);
+    };
+  }
+
+  /** start the managed flow */
+  public start(options: {
+    /** the flow manager to use */
+    manager: FlowManager;
+
+    /** the config to use when creating a player */
+    playerConfig: WebPlayerOptions;
+  }) {
+    const playerConfig: WebPlayerOptions = {
+      ...options.playerConfig,
+      suspend: true,
+    };
+
+    const initialState: ManagedPlayerState = {
+      value: 'not_started',
+      context: {
+        playerConfig,
+        webPlayer: new WebPlayer(playerConfig),
+        manager: options.manager,
+      },
+    };
+
+    this.setState(initialState);
+
+    return this;
+  }
+
+  /** reset starts from nothing */
+  public reset() {
+    if (this.state?.value === 'error') {
+      const { playerConfig, manager } = this.state.context;
+      this.start({ playerConfig, manager });
+    } else {
+      throw new Error('Flow must be in error state to reset');
+    }
+  }
+
+  /** restart starts from the last result */
+  public restart() {
+    if (this.state?.value === 'error') {
+      const { playerConfig, manager, prevResult, webPlayer } =
+        this.state.context;
+      this.setState({
+        value: 'completed',
+        context: {
+          playerConfig,
+          manager,
+          result: prevResult,
+          webPlayer,
+        },
+      });
+    } else {
+      throw new Error('Flow must be in error state to restart');
+    }
+  }
+
+  private async setState(state: ManagedPlayerState) {
+    this.state = state;
+    this.callbacks.forEach((c) => {
+      c.onState(state);
+    });
+
+    const { manager, webPlayer, playerConfig } = state.context;
+
+    try {
+      const nextState = await this.processState(state, {
+        manager,
+        webPlayer,
+        playerConfig,
+      });
+
+      if (nextState) {
+        this.setState(nextState);
+      }
+    } catch (e) {
+      this.setState({
+        value: 'error',
+        context: {
+          manager,
+          webPlayer,
+          playerConfig,
+          error: e as Error,
+        },
+      });
+    }
+  }
+
+  private async processState(
+    state: ManagedPlayerState,
+    context: ManagedPlayerContext
+  ): Promise<ManagedPlayerState | undefined> {
+    if (state.value === 'not_started' || state.value === 'completed') {
+      const prevResult =
+        state.value === 'completed' ? state.context.result : undefined;
+
+      const middleware = this.middleware?.next ?? identityMiddleware;
+
+      return {
+        value: 'pending',
+        context: {
+          ...context,
+          prevResult,
+          next: middleware(state.context.manager.next(prevResult)),
+        },
+      };
+    }
+
+    if (state.value === 'pending') {
+      const nextResult = await state.context.next;
+
+      if (nextResult.done) {
+        return {
+          value: 'ended',
+          context: {
+            ...context,
+            result: state.context.prevResult,
+          },
+        };
+      }
+
+      return {
+        value: 'loaded',
+        context: {
+          ...context,
+          prevResult: state.context.prevResult,
+          flow: nextResult.value,
+        },
+      };
+    }
+
+    if (state.value === 'loaded') {
+      return {
+        value: 'running',
+        context: {
+          ...context,
+          flow: state.context.flow,
+          prevResult: state.context.prevResult,
+          result: state.context.webPlayer.start(state.context.flow),
+        },
+      };
+    }
+
+    if (state.value === 'running') {
+      const result = await state.context.result;
+
+      return {
+        value: 'completed',
+        context: {
+          ...context,
+          result,
+        },
+      };
+    }
+  }
+}
+
+const managedPlayerStateMachines = new WeakMap<
+  ManagedPlayerStateKey,
+  ManagedState
+>();
+
+/** Creates an x-state state machine that persists when this component is no longer renders (due to Suspense) */
+export const usePersistentStateMachine = (options: {
+  /** the flow manager to use */
+  manager: FlowManager;
+
+  /** Player config  */
+  playerConfig: WebPlayerOptions;
+
+  /** Any middleware for the manager */
+  middleware?: ManagerMiddleware;
+}) => {
+  const keyRef = React.useRef<ManagedPlayerStateKey>({
+    _key: Symbol('managed-player'),
+  });
+
+  const managedState =
+    managedPlayerStateMachines.get(keyRef.current) ??
+    new ManagedState({ middleware: options.middleware });
+  managedPlayerStateMachines.set(keyRef.current, managedState);
+  const [state, setState] = React.useState(managedState.state);
+
+  React.useEffect(() => {
+    const unsub = managedState.addListener({
+      onState: (s) => {
+        setState(s);
+      },
+    });
+
+    if (managedState.state === undefined) {
+      managedState.start(options);
+    }
+
+    return unsub;
+  }, []);
+
+  return { managedState, state };
+};
+
+/**
+ * A ManagedPlayer is a component responsible for orchestrating multi-flow experiences using Player.
+ * Provide a valid `FlowManager` to handle fetching the next flow.
+ *
+ * `suspense` must be enabled to wait for results in flight.
+ */
+export const ManagedPlayer = (props: ManagedPlayerProps) => {
+  const { withRequestTime, RequestTimeMetricsPlugin } = useRequestTime();
+
+  const { state, managedState } = usePersistentStateMachine({
+    manager: props.manager,
+    middleware: { next: withRequestTime },
+    playerConfig: {
+      plugins: [...(props?.plugins ?? []), RequestTimeMetricsPlugin],
+      player: props.player,
+    },
+  });
+
+  React.useEffect(() => {
+    if (state?.value === 'ended') {
+      props.onComplete?.(state?.context.result);
+    } else if (state?.value === 'error') {
+      props.onError?.(state?.context.error);
+    } else if (state?.value === 'running') {
+      props.onStartedFlow?.();
+    }
+  }, [state]);
+
+  React.useEffect(() => {
+    return () => {
+      const playerState = state?.context.webPlayer.player.getState();
+
+      if (state?.value === 'running' && playerState?.status === 'in-progress') {
+        props.manager.terminate?.(playerState.controllers.data.serialize());
+      }
+    };
+  }, [props.manager, state?.context.webPlayer.player, state?.value]);
+
+  if (state?.value === 'error') {
+    if (props.fallbackComponent) {
+      return (
+        <props.fallbackComponent
+          reset={() => {
+            managedState.reset();
+          }}
+          retry={() => {
+            managedState.restart();
+          }}
+          error={state.context.error}
+        />
+      );
+    }
+
+    if (!props.onError) {
+      throw state.context.error;
+    }
+  }
+
+  if (state?.context.webPlayer) {
+    const { Component } = state.context.webPlayer;
+
+    return <Component />;
+  }
+
+  return null;
+};

package/src/manager/request-time.tsx

@@ -0,0 +1,63 @@
+import { useCallback, useEffect, useRef, useMemo } from 'react';
+import type { Player } from '@player-ui/player';
+import type { MetricsCorePlugin } from '@player-ui/metrics-plugin';
+import {
+  MetricsCorePluginSymbol,
+  RequestTimeWebPlugin,
+} from '@player-ui/metrics-plugin';
+import type { WebPlayerPlugin } from '../player';
+
+type RequestTime = {
+  /** request start time */
+  start?: number;
+  /** request end time */
+  end?: number;
+};
+
+/** hook to time a promise and add it to the metrics plugin */
+export const useRequestTime = () => {
+  const requestTimeRef = useRef<RequestTime>({});
+
+  useEffect(() => {
+    return () => {
+      requestTimeRef.current = {};
+    };
+  }, [requestTimeRef]);
+
+  const getRequestTime = useCallback(() => {
+    const { end, start } = requestTimeRef.current;
+
+    if (end && start) {
+      return end - start;
+    }
+  }, [requestTimeRef]);
+
+  /** wrap a promise with tracking it's time in flight */
+  function withRequestTime<Type>(nextPromise: Promise<Type>): Promise<Type> {
+    const getTime = typeof performance === 'undefined' ? Date : performance;
+    requestTimeRef.current = { start: getTime.now() };
+
+    return nextPromise.finally(() => {
+      requestTimeRef.current = {
+        ...requestTimeRef.current,
+        end: getTime.now(),
+      };
+    });
+  }
+
+  const RequestTimeMetricsPlugin: WebPlayerPlugin = useMemo(() => {
+    return {
+      name: 'RequestTimeMetricsPlugin',
+      apply(player: Player): void {
+        player.applyTo<MetricsCorePlugin>(
+          MetricsCorePluginSymbol,
+          (metricsCorePlugin) => {
+            new RequestTimeWebPlugin(getRequestTime).apply(metricsCorePlugin);
+          }
+        );
+      },
+    };
+  }, [getRequestTime]);
+
+  return { withRequestTime, RequestTimeMetricsPlugin };
+};

package/src/manager/types.ts

@@ -0,0 +1,162 @@
+import type React from 'react';
+import type { CompletedState, Flow, FlowResult } from '@player-ui/player';
+import type { WebPlayer, WebPlayerOptions } from '../player';
+
+export interface FinalState {
+  /** Mark the iteration as complete */
+  done: true;
+}
+
+export interface NextState<T> {
+  /** Optional mark the iteration as _not_ completed */
+  done?: false;
+
+  /** The next value in the iteration */
+  value: T;
+}
+
+export interface FlowManager {
+  /**
+   * An iterator implementation that takes the result of the previous flow and returns a new one or completion marker.
+   *
+   * If `done: true` is passed, the multi-flow experience is completed.
+   *
+   * @param previousValue - The result of the previous flow.
+   */
+  next: (
+    previousValue?: CompletedState
+  ) => Promise<FinalState | NextState<Flow>>;
+
+  /**
+   * 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;
+}
+
+export interface FallbackProps {
+  /** A callback to reset the flow iteration from the start */
+  reset?: () => void;
+
+  /** A callback to retry the last failed segment of the iteration */
+  retry?: () => void;
+
+  /** The error that caused the failure */
+  error?: Error;
+}
+
+export interface ManagedPlayerProps extends WebPlayerOptions {
+  /** The manager for populating the next flows */
+  manager: FlowManager;
+
+  /** A callback when a flow is started */
+  onStartedFlow?: () => void;
+
+  /** A callback when the entire async iteration is completed */
+  onComplete?: (finalState?: CompletedState) => void;
+
+  /** A callback for any errors */
+  onError?: (e: Error) => void;
+
+  /** A component to render when there are errors */
+  fallbackComponent?: React.ComponentType<FallbackProps>;
+}
+
+export type ManagedPlayerContext = {
+  /** The flow manager */
+  manager: FlowManager;
+
+  /** The web-player */
+  webPlayer: WebPlayer;
+
+  /** The config for Player */
+  playerConfig: WebPlayerOptions;
+};
+
+export type ManagedPlayerState =
+  | {
+      /** The managed player hasn't started yet */
+      value: 'not_started';
+
+      /** The context for the managed state */
+      context: ManagedPlayerContext;
+    }
+  | {
+      /** The managed-player is awaiting a response from the flow manager */
+      value: 'pending';
+
+      /** The context for the managed state */
+      context: ManagedPlayerContext & {
+        /** The previous completed state */
+        prevResult?: CompletedState;
+
+        /** A promise from the flow manager for the next state */
+        next: Promise<FinalState | NextState<Flow>>;
+      };
+    }
+  | {
+      /** A flow was retrieved from the flow manager, but hasn't been processed yet */
+      value: 'loaded';
+
+      /** The context for the managed state */
+      context: ManagedPlayerContext & {
+        /** The next flow to load */
+        flow: Flow;
+
+        /** The previous completed state */
+        prevResult?: CompletedState;
+      };
+    }
+  | {
+      /** Player is currently executing a flow */
+      value: 'running';
+      /** The context for the managed state */
+      context: ManagedPlayerContext & {
+        /** The currently running flow */
+        flow: Flow;
+
+        /** A promise for the completed result */
+        result: Promise<CompletedState>;
+
+        /** The previous completed result */
+        prevResult?: CompletedState;
+      };
+    }
+  | {
+      /** Player has completed a flow */
+      value: 'completed';
+
+      /** The context for the managed state */
+      context: ManagedPlayerContext & {
+        /** The result of the completed flow */
+        result?: CompletedState;
+      };
+    }
+  | {
+      /** The entire flow iteration has completed */
+      value: 'ended';
+
+      /** The context for the managed state */
+      context: ManagedPlayerContext & {
+        /** The result of the last completed flow */
+        result?: CompletedState;
+      };
+    }
+  | {
+      /** One of the steps in the flow has resulted in an error */
+      value: 'error';
+
+      /** The context for the managed state */
+      context: ManagedPlayerContext & {
+        /** The error that caused the flow to halt */
+        error: Error;
+
+        /** the result of the last completed flow */
+        prevResult?: CompletedState;
+      };
+    };
+
+export interface ManagerMiddleware {
+  /** Middleware for a response from the managed-player */
+  next?: <Type>(nextPromise: Promise<Type>) => Promise<Type>;
+}