@player-ui/react 0.0.1-next.1

package/dist/index.d.ts

@@ -0,0 +1,330 @@
+import React from 'react';
+import * as _player_ui_player from '@player-ui/player';
+import { Asset, PlayerPlugin, Player, Flow, CompletedState, PlayerFlowState, FlowResult } from '@player-ui/player';
+export * from '@player-ui/player';
+import { AssetRegistryType } from '@player-ui/react-asset';
+import { SyncWaterfallHook, AsyncParallelHook } from 'tapable';
+import * as _player_ui_types from '@player-ui/types';
+
+interface WebPlayerProps {
+    /**
+     * The Content view object to render
+     */
+    view: Asset;
+}
+
+interface DevtoolsGlobals {
+    /** A global for a plugin to load to Player for devtools */
+    __PLAYER_DEVTOOLS_PLUGIN?: {
+        new (): WebPlayerPlugin;
+    };
+}
+declare type DevtoolsWindow = typeof window & DevtoolsGlobals;
+interface WebPlayerInfo {
+    /** Version of the running player */
+    playerVersion: string;
+    /** Version of the running webplayer */
+    webplayerVersion: string;
+    /** Hash of the HEAD commit used to build the current player version */
+    playerCommit: string;
+    /** Hash of the HEAD commit used to build the current webplayer version */
+    webplayerCommit: string;
+}
+interface WebPlayerPlugin extends Partial<PlayerPlugin> {
+    /** The name of this plugin */
+    name: string;
+    /**
+     * Attach listeners to the web-player instance
+     */
+    applyWeb?: (webPlayer: WebPlayer) => void;
+}
+interface WebPlayerOptions {
+    /** A headless player instance to use */
+    player?: Player;
+    /** A set of plugins to apply to this player */
+    plugins?: Array<WebPlayerPlugin>;
+    /**
+     * If the underlying webPlayer.Component should use `React.Suspense` to trigger a loading state while waiting for content or content updates.
+     * It requires that a `React.Suspense` component handler be somewhere in the `webPlayer.Component` hierarchy.
+     */
+    suspend?: boolean;
+}
+declare type WebPlayerComponentProps = Record<string, unknown>;
+/** The React webplayer */
+declare class WebPlayer {
+    readonly options: WebPlayerOptions;
+    readonly player: Player;
+    readonly assetRegistry: AssetRegistryType;
+    readonly Component: React.ComponentType<WebPlayerComponentProps>;
+    readonly hooks: {
+        /**
+         * A hook to create a React Component to be used for Player, regardless of the current flow state
+         */
+        webComponent: SyncWaterfallHook<React.ComponentType<{}>, any, 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.
+         * Typically this will just be `Asset`
+         */
+        playerComponent: SyncWaterfallHook<React.ComponentType<WebPlayerProps>, any, any>;
+        /**
+         * A hook to execute async tasks before the view resets to undefined
+         */
+        onBeforeViewReset: AsyncParallelHook<any, any, any>;
+    };
+    private viewUpdateSubscription;
+    private webplayerInfo;
+    constructor(options?: WebPlayerOptions);
+    /** Returns the current version of the underlying core Player */
+    getPlayerVersion(): string;
+    /** Returns the git commit used to build this core Player version */
+    getPlayerCommit(): string;
+    /** Find instance of [Plugin] that has been registered to the web player */
+    findPlugin<Plugin extends WebPlayerPlugin>(symbol: symbol): Plugin | undefined;
+    /** Register and apply [Plugin] if one with the same symbol is not already registered. */
+    registerPlugin(plugin: WebPlayerPlugin): void;
+    /** Returns the current version of the running React Player */
+    getWebPlayerVersion(): string;
+    /** Returns the git commit used to build the React Player version */
+    getWebPlayerCommit(): string;
+    private createReactComp;
+    /**
+     * Call this method to force the WebPlayer to wait for the next view-update before performing the next render.
+     * If the `suspense` option is set, this will suspend while an update is pending, otherwise nothing will be rendered.
+     */
+    setWaitForNextViewUpdate(): Promise<void>;
+    start(flow: Flow): Promise<CompletedState>;
+}
+
+interface UseWebPlayerReturn {
+    /** The web-player instance */
+    webPlayer: WebPlayer;
+    /** Player instance */
+    player: Player;
+    /** The state of Player */
+    playerState: PlayerFlowState;
+}
+/**
+ * The `useWebPlayer` hook is an easy way to integrate the web-player into your React app.
+ * Simply supply your config, plugins, and an optional flow, which will be automatically started for you when changed.
+ */
+declare const useWebPlayer: (options?: WebPlayerOptions | undefined) => UseWebPlayerReturn;
+
+interface FinalState {
+    /** Mark the iteration as complete */
+    done: true;
+}
+interface NextState<T> {
+    /** Optional mark the iteration as _not_ completed */
+    done?: false;
+    /** The next value in the iteration */
+    value: T;
+}
+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;
+}
+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;
+}
+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>;
+}
+declare type ManagedPlayerContext = {
+    /** The flow manager */
+    manager: FlowManager;
+    /** The web-player */
+    webPlayer: WebPlayer;
+    /** The config for Player */
+    playerConfig: WebPlayerOptions;
+};
+declare 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;
+    };
+};
+interface ManagerMiddleware {
+    /** Middleware for a response from the managed-player */
+    next?: <Type>(nextPromise: Promise<Type>) => Promise<Type>;
+}
+
+interface StateChangeCallback {
+    /** Trigger for state changes */
+    onState: (s: ManagedPlayerState) => void;
+}
+/**
+ * An object to store the state of the managed player
+ */
+declare class ManagedState {
+    state?: ManagedPlayerState;
+    private callbacks;
+    private middleware?;
+    constructor({ middleware, }: {
+        /** middleware to use in the managed player */
+        middleware?: ManagerMiddleware;
+    });
+    /** Add a listener to state changes */
+    addListener(callback: StateChangeCallback): () => void;
+    /** start the managed flow */
+    start(options: {
+        /** the flow manager to use */
+        manager: FlowManager;
+        /** the config to use when creating a player */
+        playerConfig: WebPlayerOptions;
+    }): this;
+    /** reset starts from nothing */
+    reset(): void;
+    /** restart starts from the last result */
+    restart(): void;
+    private setState;
+    private processState;
+}
+/** Creates an x-state state machine that persists when this component is no longer renders (due to Suspense) */
+declare const usePersistentStateMachine: (options: {
+    /** the flow manager to use */
+    manager: FlowManager;
+    /** Player config  */
+    playerConfig: WebPlayerOptions;
+    /** Any middleware for the manager */
+    middleware?: ManagerMiddleware;
+}) => {
+    managedState: ManagedState;
+    state: {
+        value: "not_started";
+        context: ManagedPlayerContext;
+    } | {
+        value: "pending";
+        context: ManagedPlayerContext & {
+            prevResult?: _player_ui_player.CompletedState | undefined;
+            next: Promise<FinalState | NextState<_player_ui_types.Flow<_player_ui_types.Asset<string>>>>;
+        };
+    } | {
+        value: "loaded";
+        context: ManagedPlayerContext & {
+            flow: _player_ui_types.Flow<_player_ui_types.Asset<string>>;
+            prevResult?: _player_ui_player.CompletedState | undefined;
+        };
+    } | {
+        value: "running";
+        context: ManagedPlayerContext & {
+            flow: _player_ui_types.Flow<_player_ui_types.Asset<string>>;
+            result: Promise<_player_ui_player.CompletedState>;
+            prevResult?: _player_ui_player.CompletedState | undefined;
+        };
+    } | {
+        value: "completed";
+        context: ManagedPlayerContext & {
+            result?: _player_ui_player.CompletedState | undefined;
+        };
+    } | {
+        value: "ended";
+        context: ManagedPlayerContext & {
+            result?: _player_ui_player.CompletedState | undefined;
+        };
+    } | {
+        value: "error";
+        context: ManagedPlayerContext & {
+            error: Error;
+            prevResult?: _player_ui_player.CompletedState | undefined;
+        };
+    } | undefined;
+};
+/**
+ * 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.
+ */
+declare const ManagedPlayer: (props: ManagedPlayerProps) => JSX.Element | null;
+
+/** hook to time a promise and add it to the metrics plugin */
+declare const useRequestTime: () => {
+    withRequestTime: <Type>(nextPromise: Promise<Type>) => Promise<Type>;
+    RequestTimeMetricsPlugin: WebPlayerPlugin;
+};
+
+export { DevtoolsGlobals, DevtoolsWindow, FallbackProps, FinalState, FlowManager, ManagedPlayer, ManagedPlayerContext, ManagedPlayerProps, ManagedPlayerState, ManagerMiddleware, NextState, StateChangeCallback, UseWebPlayerReturn, WebPlayer, WebPlayerComponentProps, WebPlayerInfo, WebPlayerOptions, WebPlayerPlugin, usePersistentStateMachine, useRequestTime, useWebPlayer };