@player-ui/storybook 0.0.1-next.2

package/src/player/PlayerStory.tsx

@@ -0,0 +1,198 @@
+import React from 'react';
+import type { WebPlayerPlugin, PlayerFlowStatus, Flow } from '@player-ui/react';
+import { WebPlayer } from '@player-ui/react';
+import { ChakraProvider, Spinner } from '@chakra-ui/react';
+import { makeFlow } from '@player-ui/make-flow';
+import addons from '@storybook/addons';
+import type { AsyncImportFactory, RenderTarget } from '../types';
+import { useEditorFlow } from './hooks';
+import { Appetize } from './Appetize';
+import { StorybookPlayerPlugin } from './storybookWebPlayerPlugin';
+import { useStateActions, subscribe } from '../state/hooks';
+import { PlayerFlowSummary } from './PlayerFlowSummary';
+
+interface LocalPlayerStory {
+  /** the mock to load */
+  flow: Flow;
+
+  /** plugins to the player */
+  webPlugins?: Array<WebPlayerPlugin>;
+}
+
+export const WebPlayerPluginContext = React.createContext<{
+  /** Plugins to use for the player */
+  plugins?: Array<WebPlayerPlugin>;
+}>({ plugins: [] });
+
+export const PlayerRenderContext = React.createContext<RenderTarget>({
+  platform: 'web',
+});
+
+export const StorybookControlsContext = React.createContext<{
+  /** any storybook controls to include */
+  controls?: Flow['data'];
+}>({
+  controls: {},
+});
+
+/** A component to render a player + flow */
+const LocalPlayerStory = (props: LocalPlayerStory) => {
+  let flow = useEditorFlow(props.flow);
+
+  const renderContext = React.useContext(PlayerRenderContext);
+  const pluginContext = React.useContext(WebPlayerPluginContext);
+  const controlsContext = React.useContext(StorybookControlsContext);
+  const stateActions = useStateActions(addons.getChannel());
+  const plugins = props.webPlugins ?? pluginContext?.plugins ?? [];
+  const [playerState, setPlayerState] =
+    React.useState<PlayerFlowStatus>('not-started');
+
+  const wp = React.useMemo(() => {
+    return new WebPlayer({
+      plugins: [new StorybookPlayerPlugin(stateActions), ...plugins],
+    });
+  }, [plugins]);
+
+  /** A callback to start the flow */
+  const startFlow = () => {
+    setPlayerState('in-progress');
+    wp.start(flow)
+      .then(() => {
+        setPlayerState('completed');
+      })
+      .catch((e) => {
+        console.error('Error starting flow', e);
+        setPlayerState('error');
+      });
+  };
+
+  React.useEffect(() => {
+    startFlow();
+  }, [wp, flow]);
+
+  React.useEffect(() => {
+    // merge new data from storybook controls
+    if (controlsContext) {
+      flow = {
+        ...flow,
+        data: {
+          ...(flow.data ?? {}),
+          ...controlsContext,
+        },
+      };
+      stateActions.setFlow(flow);
+    }
+  }, [controlsContext]);
+
+  React.useEffect(() => {
+    return subscribe(addons.getChannel(), '@@player/flow/reset', () => {
+      startFlow();
+    });
+  }, [wp, flow]);
+
+  if (renderContext.platform !== 'web' && renderContext.token) {
+    return (
+      <Appetize
+        flow={flow}
+        platform={renderContext.platform}
+        token={renderContext.token}
+        baseUrl={renderContext.baseUrl}
+        osVersions={renderContext.appetizeVersions}
+      />
+    );
+  }
+
+  const currentState = wp.player.getState();
+
+  if (playerState === 'completed' && currentState.status === 'completed') {
+    return (
+      <PlayerFlowSummary
+        reset={startFlow}
+        outcome={currentState.endState.outcome}
+      />
+    );
+  }
+
+  if (playerState === 'error' && currentState.status === 'error') {
+    return <PlayerFlowSummary reset={startFlow} error={currentState.error} />;
+  }
+
+  return <wp.Component />;
+};
+
+type Mock = Record<string, unknown>;
+type MockFactory = () => Mock;
+type MockFactoryOrPromise = MockFactory | Mock;
+
+/** Wrap the component in a lazy type to trigger suspense */
+function wrapInLazy(
+  /** The component to load */
+  Component: React.ComponentType<{
+    /** the flow */
+    flow: Flow;
+  }>,
+
+  /** A mock or a promise that resolve to a mock */
+  flowFactory: AsyncImportFactory<MockFactoryOrPromise> | MockFactoryOrPromise,
+
+  /** Any other props to pass */
+  other?: any
+) {
+  /** an async loader to wrap the mock as a player component */
+  const asPlayer = async () => {
+    const mock =
+      typeof flowFactory === 'function' ? await flowFactory() : flowFactory;
+
+    /** The component to load */
+    const Comp = () => {
+      const flow = {
+        ...makeFlow('default' in mock ? mock.default : mock),
+        ...(other ?? {}),
+      };
+      return <Component flow={flow} />;
+    };
+
+    return {
+      default: Comp,
+    };
+  };
+
+  return React.lazy(asPlayer);
+}
+
+export interface PlayerStoryProps {
+  /** The mock to load */
+  flow: AsyncImportFactory<MockFactoryOrPromise> | MockFactoryOrPromise;
+  /** Custom data to use in the flow */
+  data?: Flow['data'];
+  /** props from storybook controls */
+  storybookControls?: Flow['data'];
+}
+
+/**
+ * Takes an initial flow and renders it as a story in storybook.
+ * This handles all of the wiring of the mock into the flow editor, events, etc
+ */
+export const PlayerStory = (props: PlayerStoryProps) => {
+  const { flow, storybookControls, ...other } = props;
+  const MockComp = React.useMemo(
+    () => wrapInLazy(LocalPlayerStory, flow, other),
+    []
+  );
+
+  return (
+    <div>
+      <ChakraProvider>
+        <React.Suspense fallback={<Spinner />}>
+          <StorybookControlsContext.Provider
+            value={{
+              ...storybookControls,
+            }}
+          >
+            <MockComp />
+          </StorybookControlsContext.Provider>
+        </React.Suspense>
+      </ChakraProvider>
+    </div>
+  );
+};

package/src/player/hooks.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { Flow } from '@player-ui/player';
+import addons from '@storybook/addons';
+import { DocsContext } from '@storybook/addon-docs';
+import { useStateActions, useFlowState } from '../state/hooks';
+
+/** Use the flow from the editor or the original one */
+export function useEditorFlow(initialFlow: Flow) {
+  const stateActions = useStateActions(addons.getChannel());
+  const flow = useFlowState(addons.getChannel());
+
+  const docsContext = React.useContext(DocsContext);
+
+  React.useEffect(() => {
+    stateActions.setFlow(initialFlow);
+  }, [initialFlow]);
+
+  React.useEffect(() => {
+    if (!flow) {
+      stateActions.setFlow(initialFlow);
+    }
+  }, [flow]);
+
+  if (docsContext.id) {
+    return initialFlow;
+  }
+
+  return flow ?? initialFlow;
+}

package/src/player/index.ts

@@ -0,0 +1 @@
+export * from './PlayerStory';

package/src/player/storybookWebPlayerPlugin.ts

@@ -0,0 +1,113 @@
+import type { WebPlayer, Player, WebPlayerPlugin } from '@player-ui/react';
+import type { Timing } from '@player-ui/metrics-plugin-react';
+import { MetricsPlugin } from '@player-ui/metrics-plugin-react';
+import type {
+  StateActions,
+  DataChangeEventType,
+  LogEventType,
+  StateChangeEventType,
+  MetricChangeEventType,
+} from '../state';
+import { createEvent } from '../state';
+
+/**
+ *
+ * A web plugin for interacting with storybook
+ */
+export class StorybookPlayerPlugin implements WebPlayerPlugin {
+  public readonly name = 'Storybook';
+
+  private actions: StateActions;
+  private metricsPlugin: MetricsPlugin;
+
+  constructor(actions: StateActions) {
+    this.actions = actions;
+    this.metricsPlugin = new MetricsPlugin({
+      onUpdate: (metrics) => {
+        actions.setMetrics(metrics);
+      },
+      onRenderEnd: (timing) => {
+        this.onMetricChange(timing, 'render');
+      },
+      onUpdateEnd: (timing) => {
+        this.onMetricChange(timing, 'update');
+      },
+    });
+  }
+
+  apply(player: Player) {
+    player.registerPlugin(this.metricsPlugin);
+  }
+
+  applyWeb(wp: WebPlayer) {
+    wp.registerPlugin(this.metricsPlugin);
+
+    wp.player.hooks.dataController.tap(this.name, (dc) => {
+      this.actions.clearEvents();
+
+      dc.hooks.onUpdate.tap(this.name, (dataUpdates) => {
+        const events: Array<DataChangeEventType> = dataUpdates.map(
+          (dataUpdate) =>
+            createEvent({
+              type: 'dataChange',
+              binding: dataUpdate.binding.asString(),
+              from: dataUpdate.oldValue,
+              to: dataUpdate.newValue,
+            })
+        );
+        this.actions.addEvents(events);
+      });
+    });
+
+    wp.player.logger.hooks.log.tap(this.name, (severity, data) => {
+      this.actions.addEvents([
+        createEvent<LogEventType>({
+          type: 'log',
+          message: data,
+          severity,
+        }),
+      ]);
+    });
+
+    wp.player.hooks.state.tap(this.name, (newState) => {
+      if ('error' in newState) {
+        this.actions.addEvents([
+          createEvent<StateChangeEventType>({
+            type: 'stateChange',
+            state: newState.status,
+            error: newState.error.message,
+          }),
+        ]);
+      } else if (newState.status === 'completed') {
+        this.actions.addEvents([
+          createEvent<StateChangeEventType>({
+            type: 'stateChange',
+            state: newState.status,
+            outcome: newState.endState.outcome,
+          }),
+        ]);
+      } else {
+        this.actions.addEvents([
+          createEvent<StateChangeEventType>({
+            type: 'stateChange',
+            state: newState.status,
+          }),
+        ]);
+      }
+    });
+  }
+
+  onMetricChange(timing: Timing, metricType: string) {
+    if (!timing.completed) {
+      return;
+    }
+
+    this.actions.addEvents([
+      createEvent<MetricChangeEventType>({
+        type: 'metric',
+        metricType,
+        message: `Duration: ${timing.duration.toFixed(0)} ms`,
+      }),
+    ]);
+  }
+}

package/src/state/events.ts

@@ -0,0 +1,62 @@
+import { v4 as uuid } from 'uuid';
+import type { PlayerFlowStatus } from '@player-ui/player';
+import type { Severity } from '@player-ui/player';
+
+interface BaseEventType<T extends string> {
+  /** A timestamp for the event */
+  time: number;
+  /** the event id */
+  id: string;
+  /** the event type */
+  type: T;
+}
+
+export interface LogEventType extends BaseEventType<'log'> {
+  /** the message */
+  message: Array<unknown>;
+  /** the log severity */
+  severity: Severity;
+}
+
+export interface DataChangeEventType extends BaseEventType<'dataChange'> {
+  /** The binding */
+  binding: string;
+  /** the old value */
+  from: unknown;
+  /** the new value */
+  to: unknown;
+}
+
+export interface StateChangeEventType extends BaseEventType<'stateChange'> {
+  /** The state type */
+  state: PlayerFlowStatus;
+  /** The error message */
+  error?: string;
+  /** The outcome */
+  outcome?: string;
+}
+
+export interface MetricChangeEventType extends BaseEventType<'metric'> {
+  /** The metric type */
+  metricType: string;
+
+  /** The message for the metrics change type */
+  message: string;
+}
+
+export type EventType =
+  | LogEventType
+  | DataChangeEventType
+  | StateChangeEventType
+  | MetricChangeEventType;
+
+/** Create an event for the timeline */
+export function createEvent<T extends EventType>(
+  base: Omit<T, 'id' | 'time'>
+): T {
+  return {
+    id: uuid(),
+    time: Date.now(),
+    ...base,
+  } as T;
+}

package/src/state/hooks.ts

@@ -0,0 +1,152 @@
+import React from 'react';
+import type { Channel } from '@storybook/channels';
+import type { Flow } from '@player-ui/react';
+import type { PlayerFlowMetrics } from '@player-ui/metrics-plugin-react';
+import type { EventType } from './events';
+import type { RenderTarget } from '../types';
+
+export interface StateActions {
+  addEvents(events: Array<EventType>): void;
+  clearEvents(): void;
+  setFlow(flow: Flow): void;
+  setMetrics(metrics: PlayerFlowMetrics): void;
+  resetFlow(): void;
+  setPlatform(platform: RenderTarget['platform']): void;
+}
+
+interface BasePublishedEvent<T extends string> {
+  /** The base event type */
+  type: T;
+}
+
+type EventClearType = BasePublishedEvent<'@@player/event/clear'>;
+
+interface EventAddType extends BasePublishedEvent<'@@player/event/add'> {
+  /** The events to append */
+  events: Array<EventType>;
+}
+
+interface FlowSetType extends BasePublishedEvent<'@@player/flow/set'> {
+  /** the flow to use */
+  flow: Flow;
+}
+
+type FlowResetType = BasePublishedEvent<'@@player/flow/reset'>;
+
+interface MetricsSetEventType
+  extends BasePublishedEvent<'@@player/metrics/set'> {
+  /** the metrics data */
+  metrics: PlayerFlowMetrics;
+}
+
+export interface PlatformSetType
+  extends BasePublishedEvent<'@@player/platform/set'> {
+  /** The platform to render on */
+  platform: RenderTarget['platform'];
+}
+
+export type PlayerEventType =
+  | EventClearType
+  | EventAddType
+  | FlowSetType
+  | MetricsSetEventType
+  | FlowResetType
+  | PlatformSetType;
+
+/** Subscribe to player events in storybook */
+export function subscribe<T extends PlayerEventType>(
+  chan: Channel,
+  eventName: T['type'],
+  callback: (evt: T) => void
+): () => void {
+  /** The handler to call */
+  const handler = (payload: string) => {
+    callback(JSON.parse(payload));
+  };
+
+  chan.addListener(eventName, handler);
+
+  return () => {
+    chan.removeListener(eventName, handler);
+  };
+}
+
+/** publish an event to storybook */
+export function publish(chan: Channel, event: PlayerEventType) {
+  chan.emit(event.type, JSON.stringify(event));
+}
+
+/** wrapper to emit events */
+export function useStateActions(chan: Channel): StateActions {
+  return React.useMemo<StateActions>(
+    () => ({
+      addEvents: (events) => {
+        publish(chan, {
+          type: '@@player/event/add',
+          events,
+        });
+      },
+      setMetrics: (metrics) => {
+        publish(chan, {
+          type: '@@player/metrics/set',
+          metrics,
+        });
+      },
+      clearEvents: () => {
+        publish(chan, {
+          type: '@@player/event/clear',
+        });
+      },
+      setFlow: (flow) => {
+        publish(chan, {
+          type: '@@player/flow/set',
+          flow,
+        });
+      },
+      resetFlow: () => {
+        publish(chan, { type: '@@player/flow/reset' });
+      },
+      setPlatform: (platform) => {
+        publish(chan, { type: '@@player/platform/set', platform });
+      },
+    }),
+    [chan]
+  );
+}
+
+/** react hook to subscribe to events */
+export function useEventState(chan: Channel) {
+  const [events, setEvents] = React.useState<Array<EventType>>([]);
+
+  React.useEffect(() => {
+    const unsubAdd = subscribe<EventAddType>(
+      chan,
+      '@@player/event/add',
+      (evt) => setEvents((old) => [...old, ...evt.events])
+    );
+
+    const unsubClear = subscribe(chan, '@@player/event/clear', () => {
+      setEvents([]);
+    });
+
+    return () => {
+      unsubAdd();
+      unsubClear();
+    };
+  }, [chan]);
+
+  return events;
+}
+
+/** hook to subscribe to flow events */
+export function useFlowState(chan: Channel) {
+  const [flow, setFlow] = React.useState<Flow | undefined>();
+
+  React.useEffect(() => {
+    return subscribe<FlowSetType>(chan, '@@player/flow/set', (evt) => {
+      setFlow(evt.flow);
+    });
+  }, [chan]);
+
+  return flow;
+}

package/src/state/index.ts

@@ -0,0 +1,2 @@
+export * from './events';
+export * from './hooks';

package/src/types.ts

@@ -0,0 +1,41 @@
+import type { WebPlayerPlugin } from '@player-ui/react';
+import type { AppetizeVersions } from './player/Appetize';
+
+export interface PlayerParametersType {
+  /** plugins to use for any loaded player */
+  webplayerPlugins?: Array<WebPlayerPlugin>;
+
+  /** Appetize tokens to use */
+  appetizeTokens?: {
+    /** the ios token */
+    ios?: string;
+
+    /** the android token */
+    android?: string;
+  };
+
+  /** The base URL to use for appetize if it is not the default */
+  appetizeBaseUrl?: string;
+
+  /** The OS Versions to use for appetize */
+  appetizeVersions?: AppetizeVersions;
+}
+
+export type AsyncImportFactory<T> = () => Promise<{
+  /** default export of the module */
+  default: T;
+}>;
+
+export type RenderTarget = {
+  /** platform to render on */
+  platform: 'ios' | 'android' | 'web';
+
+  /** the token to use if applicable */
+  token?: string;
+
+  /** A different base URL for appetize if necessary */
+  baseUrl?: string;
+
+  /** The OS Versions to use for appetize */
+  appetizeVersions?: AppetizeVersions;
+};