@player-ui/react 0.8.0--canary.307.9621 → 0.8.0-next.0

package/types/manager/types.d.ts

@@ -0,0 +1,125 @@
+import type React from "react";
+import type { CompletedState, Flow, FlowResult } from "@player-ui/player";
+import type { ReactPlayer, ReactPlayerOptions } 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 ReactPlayerOptions {
+    /** 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 */
+    reactPlayer: ReactPlayer;
+    /** The config for Player */
+    playerConfig: ReactPlayerOptions;
+};
+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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/types/player.d.ts

@@ -0,0 +1,86 @@
+import React from "react";
+import { SyncWaterfallHook, AsyncParallelHook } from "tapable-ts";
+import type { CompletedState, PlayerPlugin, Flow } from "@player-ui/player";
+import { Player } from "@player-ui/player";
+import type { AssetRegistryType } from "./asset";
+import type { ReactPlayerProps } from "./app";
+export interface DevtoolsGlobals {
+    /** A global for a plugin to load to Player for devtools */
+    __PLAYER_DEVTOOLS_PLUGIN?: {
+        new (): ReactPlayerPlugin;
+    };
+}
+export type DevtoolsWindow = typeof window & DevtoolsGlobals;
+export interface ReactPlayerInfo {
+    /** Version of the running player */
+    playerVersion: string;
+    /** Version of the running reactPlayer */
+    reactPlayerVersion: 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 reactPlayer version */
+    reactPlayerCommit: string;
+}
+export interface ReactPlayerPlugin extends Partial<PlayerPlugin> {
+    /** The name of this plugin */
+    name: string;
+    /**
+     * Attach listeners to the web-player instance
+     */
+    applyReact?: (reactPlayer: ReactPlayer) => void;
+}
+export interface ReactPlayerOptions {
+    /** A headless player instance to use */
+    player?: Player;
+    /** A set of plugins to apply to this player */
+    plugins?: Array<ReactPlayerPlugin>;
+}
+export type ReactPlayerComponentProps = Record<string, unknown>;
+/** A Player that renders UI through React */
+export declare class ReactPlayer {
+    readonly options: ReactPlayerOptions;
+    readonly player: Player;
+    readonly assetRegistry: AssetRegistryType;
+    readonly Component: React.ComponentType<ReactPlayerComponentProps>;
+    readonly hooks: {
+        /**
+         * 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>>;
+        /**
+         * 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<ReactPlayerProps>], Record<string, any>>;
+        /**
+         * A hook to execute async tasks before the view resets to undefined
+         */
+        onBeforeViewReset: AsyncParallelHook<[], Record<string, any>>;
+    };
+    private viewUpdateSubscription;
+    private reactPlayerInfo;
+    constructor(options?: ReactPlayerOptions);
+    /** 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 ReactPlayerPlugin>(symbol: symbol): Plugin | undefined;
+    /** Register and apply [Plugin] if one with the same symbol is not already registered. */
+    registerPlugin(plugin: ReactPlayerPlugin): void;
+    /** Returns the current version of the running React Player */
+    getReactPlayerVersion(): string;
+    /** Returns the git commit used to build the React Player version */
+    getReactPlayerCommit(): string;
+    private createReactPlayerComponent;
+    private createReactComp;
+    /**
+     * Call this method to force the ReactPlayer 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>;
+}
+export declare const WebPlayer: typeof ReactPlayer;
+//# sourceMappingURL=player.d.ts.map

package/types/plugins/onupdate-plugin.d.ts

@@ -0,0 +1,12 @@
+import type { Player, PlayerPlugin } from "@player-ui/player";
+export type OnUpdateCallback = (update: any) => void;
+/**
+ * A plugin that listens for view updates and publishes an event for when a view is updated
+ */
+export default class OnUpdatePlugin implements PlayerPlugin {
+    name: string;
+    private readonly onUpdateCallback;
+    constructor(onUpdate: OnUpdateCallback);
+    apply(player: Player): void;
+}
+//# sourceMappingURL=onupdate-plugin.d.ts.map

package/types/plugins/tapstate-plugin.d.ts

@@ -0,0 +1,12 @@
+import type { PlayerFlowState, Player } from "@player-ui/player";
+import type { ReactPlayerPlugin } from "../player";
+/**
+ * A plugin to tap into state transition changes and call an arbitrary update function
+ */
+export declare class StateTapPlugin implements ReactPlayerPlugin {
+    name: string;
+    private callbackFunction;
+    constructor(callback: (state: PlayerFlowState) => void);
+    apply(player: Player): void;
+}
+//# sourceMappingURL=tapstate-plugin.d.ts.map

package/types/utils/helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Trim leading and trailing slashes from string
+ */
+export declare function trimSlashes(str: string): string;
+/**
+ * Removes any key: value pairs from an object when the value is null or undefined
+ */
+export declare function removeEmptyValuesFromObject(obj: Record<string, any>): Record<string, NonNullable<any>>;
+/** Check if the object has no keys */
+export declare function isEmptyObject(obj: Record<string, unknown>): boolean;
+/** Check if the argument is a function */
+export declare function isFunction<ReturnType>(maybeFn: ReturnType | ((...args: unknown[]) => ReturnType)): maybeFn is (...args: unknown[]) => ReturnType;
+/**
+ * Calls function with provided data or returns original value
+ */
+export declare function callOrReturn<ReturnType, FnArgs extends Array<unknown> = unknown[], FnType = (...args: FnArgs) => ReturnType>(maybeFn: FnType | ReturnType, fnArgs: FnArgs): ReturnType;
+//# sourceMappingURL=helpers.d.ts.map

package/types/utils/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./player-context";
+export * from "./use-logger";
+export * from "./use-asset-props";
+export * from "./helpers";
+export * from "./url";
+export * from "./shared-constants";
+//# sourceMappingURL=index.d.ts.map

package/types/utils/player-context.d.ts

@@ -0,0 +1,16 @@
+import React from "react";
+import type { Player, NavigationFlowViewState } from "@player-ui/player";
+export interface PlayerContextType {
+    /**
+     * An instance of a headless player
+     */
+    player?: Player;
+    /** The currently rendered view state */
+    viewState?: NavigationFlowViewState;
+}
+export declare const PlayerContext: React.Context<PlayerContextType>;
+/**
+ * A hook to get the current player
+ */
+export declare const usePlayer: () => Player | undefined;
+//# sourceMappingURL=player-context.d.ts.map

package/types/utils/shared-constants.d.ts

@@ -0,0 +1,5 @@
+/** Hook to get a constant under a specific namespace */
+export declare function useGetConstantByType(type: string, key: string): unknown;
+/** Get a constant under the default namespace */
+export declare function useGetConstant(key: string): unknown;
+//# sourceMappingURL=shared-constants.d.ts.map

package/types/utils/url.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Combines a URL with any additional parameters
+ */
+export declare function buildUrl(url: string, params?: Record<string, unknown>): string;
+//# sourceMappingURL=url.d.ts.map

package/types/utils/use-asset-props.d.ts

@@ -0,0 +1,7 @@
+import type { Asset } from "@player-ui/player";
+/** Common props for any dom node */
+export declare function useAssetProps(asset: Asset): {
+    id: string;
+    "data-asset-type": string;
+};
+//# sourceMappingURL=use-asset-props.d.ts.map

package/types/utils/use-logger.d.ts

@@ -0,0 +1,6 @@
+import type { Logger } from "@player-ui/player";
+/**
+ * A hook to get the logger instance from the current player
+ */
+export declare function useLogger(): Logger;
+//# sourceMappingURL=use-logger.d.ts.map