@player-ui/player 0.0.1-next.1

package/dist/index.d.ts

@@ -0,0 +1,434 @@
+import * as _player_ui_types from '@player-ui/types';
+import { Asset, Validation, Flow, FlowResult, NavigationFlowViewState, View } from '@player-ui/types';
+export * from '@player-ui/types';
+import { BindingInstance, BindingFactory, BindingParser, BindingLike } from '@player-ui/binding';
+export * from '@player-ui/binding';
+import { DataModelMiddleware, DataModelWithParser, DataModelOptions, DataPipeline, BatchSetTransaction, Updates, PipelinedDataModel } from '@player-ui/data';
+export * from '@player-ui/data';
+import { ExpressionEvaluator } from '@player-ui/expressions';
+export * from '@player-ui/expressions';
+import { FlowController } from '@player-ui/flow';
+export * from '@player-ui/flow';
+import { Logger, TapableLogger } from '@player-ui/logger';
+export * from '@player-ui/logger';
+import { SchemaController } from '@player-ui/schema';
+export * from '@player-ui/schema';
+export * from '@player-ui/string-resolver';
+import { ValidatorRegistry, ValidationResponse, ValidatorContext, ValidationObject, WarningValidationResponse, ErrorValidationResponse } from '@player-ui/validator';
+export * from '@player-ui/validator';
+import { Node, Resolve, ViewPlugin, Resolver, ViewInstance } from '@player-ui/view';
+export * from '@player-ui/view';
+import { SyncHook, SyncWaterfallHook, SyncBailHook } from 'tapable';
+import { ConstantsController } from '@player-ui/constants';
+import { Registry } from '@player-ui/partial-match-registry';
+
+interface Store {
+    useLocalState<T>(initialState: T): readonly [T, (value: T) => void];
+    useSharedState<T>(key: string | symbol): (initialState: T) => readonly [T, (value: T) => void];
+}
+interface SharedStore {
+    getLocalStateFunction<T>(key: string | symbol, countKey: symbol): (initialState: T) => readonly [T, (value: T) => void];
+    useSharedState<T>(key: string | symbol): (initialState: T) => readonly [T, (value: T) => void];
+}
+/** A store that holds on to state for a transform */
+declare class LocalStateStore implements SharedStore {
+    private state;
+    private updateCallback?;
+    constructor(onUpdate?: () => void);
+    removeKey(key: symbol | string): void;
+    reset(): void;
+    useSharedState<T>(key: string | symbol): (initialState: T) => readonly [T, (newState: T) => void];
+    getLocalStateFunction<T>(key: symbol, countKey: symbol): (initialState: T) => readonly [T, (newState: T) => void];
+}
+
+/** Transform function that is ran on the Asset before it's resolved */
+declare type BeforeTransformFunction<AuthoredAsset extends Asset = Asset> = (asset: Node.Asset<AuthoredAsset> | Node.View<AuthoredAsset>, options: Resolve.NodeResolveOptions, store: Store) => Node.Node;
+/** Transform function that is ran on the Asset after it's resolved */
+declare type TransformFunction<AuthoredAsset extends Asset = Asset, TransformedAsset extends Asset = AuthoredAsset> = (asset: AuthoredAsset, options: Resolve.NodeResolveOptions, store: Store) => TransformedAsset;
+interface TransformFunctions {
+    /** A function that is executed as an AST -> AST transform before resolving the node to a value */
+    beforeResolve?: BeforeTransformFunction<any>;
+    /** A function to resolve an AST to a value */
+    resolve?: TransformFunction<any>;
+}
+declare type TransformRegistry = Registry<TransformFunctions>;
+
+interface BindingTracker {
+    /** Get the bindings currently being tracked for validation */
+    getBindings(): Set<BindingInstance>;
+}
+interface Options {
+    /** Parse a binding from a view */
+    parseBinding: BindingFactory;
+    /** Callbacks when events happen */
+    callbacks?: {
+        /** Called when a binding is encountered for the first time in a view */
+        onAdd?: (binding: BindingInstance) => void;
+    };
+}
+/** A view plugin that manages bindings tracked across updates */
+declare class ValidationBindingTrackerViewPlugin implements ViewPlugin, BindingTracker {
+    private options;
+    private trackedBindings;
+    constructor(options: Options);
+    /** Fetch the tracked bindings in the current view */
+    getBindings(): Set<BindingInstance>;
+    /** Attach hooks to the given resolver */
+    applyResolver(resolver: Resolver): void;
+    apply(view: ViewInstance): void;
+}
+
+declare type SimpleValidatorContext = Omit<ValidatorContext, 'validation'>;
+interface BaseActiveValidation<T> {
+    /** The validation is being actively shown */
+    state: 'active';
+    /** The validation response */
+    response: T;
+}
+declare type ActiveWarning = BaseActiveValidation<WarningValidationResponse> & {
+    /** Warnings track if they can be dismissed automatically (by navigating) */
+    dismissable: boolean;
+};
+declare type ActiveError = BaseActiveValidation<ErrorValidationResponse>;
+/**
+ * warnings that keep track of their active state
+ */
+declare type StatefulWarning = {
+    /** A common key to differentiate between errors and warnings */
+    type: 'warning';
+    /** The underlying validation this tracks */
+    value: ValidationObject;
+} & ({
+    /** warnings start with no state, but can active or dismissed */
+    state: 'none' | 'dismissed';
+} | ActiveWarning);
+/** Errors that keep track of their state */
+declare type StatefulError = {
+    /** A common key to differentiate between errors and warnings */
+    type: 'error';
+    /** The underlying validation this tracks */
+    value: ValidationObject;
+} & ({
+    /** Errors start with no state an can be activated */
+    state: 'none';
+} | ActiveError);
+declare type StatefulValidationObject = StatefulWarning | StatefulError;
+declare type ValidationRunner = (obj: ValidationObject) => {
+    /** A validation message */
+    message: string;
+} | undefined;
+/** A class that manages validating bindings across phases */
+declare class ValidatedBinding {
+    private currentPhase?;
+    private applicableValidations;
+    private validationsByState;
+    weakBindings: Set<BindingInstance>;
+    private onDismiss?;
+    constructor(possibleValidations: Array<ValidationObject>, onDismiss?: () => void, log?: Logger, weakBindings?: Set<BindingInstance>);
+    get(): ValidationResponse | undefined;
+    private runApplicableValidations;
+    update(phase: Validation.Trigger, canDismiss: boolean, runner: ValidationRunner): void;
+}
+/**
+ * A controller for orchestrating validation within a running player
+ *
+ * The current validation flow is as follows:
+ *
+ *   - When a binding is first seen, gather all of the possible validations for it from the providers
+ *     - Schema and Crossfield (view) are both providers of possible validations
+ *     - Run all of the applicable validations for that binding for the `load` trigger
+ *
+ *   - When a change occurs, set the phase of the binding to `change`.
+ *     - Run all of the `change` triggered validations for that binding.
+ *
+ *   - When a navigation event occurs, set the phase of the binding to `navigate`.
+ *     - Run all `change` and `navigate` validations for each tracked binding.
+ *     - For any warnings, also keep a state of `shown` or `dismissed`.
+ *       - Set all non-dismissed warnings to `shown`.
+ *       - Set all `shown` warnings to `dismissed`.
+ *     - Allow navigation forward if there are no non-dismissed warnings and no valid errors.
+ */
+declare class ValidationController implements BindingTracker {
+    readonly hooks: {
+        /** A hook called to tap into the validator registry for adding more validators */
+        createValidatorRegistry: SyncHook<ValidatorRegistry, any, any>;
+        /** A callback/event when a new validation is added to the view */
+        onAddValidation: SyncWaterfallHook<ValidationResponse, BindingInstance, any>;
+        /** The inverse of onAddValidation, this is called when a validation is removed from the list */
+        onRemoveValidation: SyncWaterfallHook<ValidationResponse, BindingInstance, any>;
+    };
+    private tracker;
+    private validations;
+    private validatorRegistry?;
+    private schema;
+    private providers;
+    private options?;
+    private weakBindingTracker;
+    private lastActiveBindings;
+    constructor(schema: SchemaController, options?: SimpleValidatorContext);
+    setOptions(options: SimpleValidatorContext): void;
+    /** Return the middleware for the data-model to stop propagation of invalid data */
+    getDataMiddleware(): Array<DataModelMiddleware>;
+    onView(view: ViewInstance): void;
+    private updateValidationsForBinding;
+    private validationRunner;
+    private updateValidationsForView;
+    private setCompare;
+    private get activeBindings();
+    private getValidator;
+    getBindings(): Set<BindingInstance>;
+    /** Executes all known validations for the tracked bindings using the given model */
+    validateView(trigger?: Validation.Trigger): {
+        /** Indicating if the view can proceed without error */
+        canTransition: boolean;
+        /** the validations that are preventing the view from continuing */
+        validations?: Map<BindingInstance, ValidationResponse>;
+    };
+    getValidationForBinding(binding: BindingInstance): ValidatedBinding | undefined;
+    forView(parser: BindingFactory): Resolve.Validation;
+}
+
+/** The status for a flow's execution state */
+declare type PlayerFlowStatus = 'not-started' | 'in-progress' | 'completed' | 'error';
+/** Common interface for the state of Player's flow execution */
+interface BaseFlowState<T extends PlayerFlowStatus> {
+    /** A unique reference for the life-cycle of a flow */
+    ref: symbol;
+    /** The status of the given flow */
+    status: T;
+}
+/** The beginning state of Player, before it's seen a flow  */
+declare type NotStartedState = BaseFlowState<'not-started'>;
+declare const NOT_STARTED_STATE: NotStartedState;
+/** Shared properties for a flow in any state of execution (in-progress, completed successfully, or errored out) */
+interface PlayerFlowExecutionData {
+    /** The currently executing flow */
+    flow: Flow;
+}
+interface ControllerState {
+    /** The manager for data for a flow */
+    data: DataController;
+    /** The view manager for a flow */
+    view: ViewController;
+    /** The schema manager for a flow */
+    schema: SchemaController;
+    /** The validation manager for a flow */
+    validation: ValidationController;
+    /** The expression evaluator for a flow */
+    expression: ExpressionEvaluator;
+    /** The manager for parsing and resolving bindings */
+    binding: BindingParser;
+    /** the manager for the flow state machine */
+    flow: FlowController;
+}
+/** A flow is currently executing */
+declare type InProgressState = BaseFlowState<'in-progress'> & PlayerFlowExecutionData & {
+    /** A promise that resolves when the flow is completed */
+    flowResult: Promise<FlowResult>;
+    /** The underlying state controllers for the current flow */
+    controllers: ControllerState;
+    /** Allow other platforms to abort the current flow with an error  */
+    fail: (error: Error) => void;
+    /**
+     * The Logger for the current player instance
+     */
+    logger: Logger;
+};
+/** The flow completed properly */
+declare type CompletedState = BaseFlowState<'completed'> & PlayerFlowExecutionData & FlowResult & {
+    /** The top-level data-model for the flow */
+    dataModel: DataModelWithParser;
+};
+/** The flow finished but not successfully */
+declare type ErrorState = BaseFlowState<'error'> & {
+    /** The currently executing flow */
+    flow: Flow;
+    /** The error associated with the failed flow */
+    error: Error;
+};
+/** Any Player state  */
+declare type PlayerFlowState = NotStartedState | InProgressState | CompletedState | ErrorState;
+declare type RawSetType = [BindingLike, any];
+declare type RawSetTransaction = Record<string, any> | RawSetType[];
+
+/** The orchestrator for player data */
+declare class DataController implements DataModelWithParser<DataModelOptions> {
+    hooks: {
+        resolve: SyncWaterfallHook<any, any, any>;
+        resolveDataStages: SyncWaterfallHook<DataPipeline, any, any>;
+        resolveDefaultValue: SyncBailHook<BindingInstance, any, any, any>;
+        onDelete: SyncHook<any, void, any>;
+        onSet: SyncHook<BatchSetTransaction, void, any>;
+        onGet: SyncHook<any, any, void>;
+        onUpdate: SyncHook<Updates, any, any>;
+        format: SyncWaterfallHook<any, BindingInstance, any>;
+        deformat: SyncWaterfallHook<any, BindingInstance, any>;
+        serialize: SyncWaterfallHook<any, any, any>;
+    };
+    private model?;
+    private trash;
+    private pathResolver;
+    private baseMiddleware;
+    private logger?;
+    constructor(model: Record<any, unknown> | undefined, options: {
+        /** A means of parsing a raw binding to a Binding object */
+        pathResolver: BindingParser;
+        /** middleware to use. typically for validation */
+        middleware?: Array<DataModelMiddleware>;
+        /** A logger to use  */
+        logger?: Logger;
+    });
+    getModel(): PipelinedDataModel;
+    private resolveDataValue;
+    set(transaction: RawSetTransaction, options?: DataModelOptions): Updates;
+    private resolve;
+    get(binding: BindingLike, options?: DataModelOptions): any;
+    delete(binding: BindingLike): void;
+    getTrash(): Set<BindingInstance>;
+    private addToTrash;
+    private deleteData;
+    serialize(): object;
+}
+
+interface ViewControllerOptions {
+    /** Where to get data from */
+    model: DataController;
+    /** Where to log data */
+    logger?: Logger;
+    /** A flow-controller instance to listen for view changes */
+    flowController: FlowController;
+}
+/** A controller to manage updating/switching views */
+declare class ViewController {
+    readonly hooks: {
+        /** Do any processing before the `View` instance is created */
+        resolveView: SyncWaterfallHook<_player_ui_types.Asset<string> & {
+            validation?: _player_ui_types.Validation.CrossfieldReference[] | undefined;
+        }, string, NavigationFlowViewState>;
+        view: SyncHook<ViewInstance, any, any>;
+    };
+    private readonly viewMap;
+    private readonly viewOptions;
+    private pendingUpdate?;
+    currentView?: ViewInstance;
+    transformRegistry: TransformRegistry;
+    optimizeUpdates: boolean;
+    constructor(initialViews: View[], options: Resolve.ResolverOptions & ViewControllerOptions);
+    private queueUpdate;
+    private getViewForRef;
+    onView(state: NavigationFlowViewState): void;
+}
+
+/**
+ * A plugin to register custom transforms on certain asset types
+ * This allows users to embed stateful data into transforms.
+ */
+declare class AssetTransformCorePlugin {
+    readonly stateStore: Map<Node.Node, LocalStateStore>;
+    private readonly registry;
+    private beforeResolveSymbol;
+    private resolveSymbol;
+    private beforeResolveCountSymbol;
+    private resolveCountSymbol;
+    constructor(registry: TransformRegistry);
+    apply(viewController: ViewController): void;
+}
+
+interface PlayerPlugin {
+    /**
+     * Unique identifier of the plugin.
+     * Enables the plugin to be retrievable from Player.
+     */
+    symbol?: symbol;
+    /** The name of the plugin */
+    name: string;
+    /**
+     * Use this to tap into Player hooks
+     */
+    apply: (player: Player) => void;
+}
+interface PlayerConfigOptions {
+    /** A set of plugins to load  */
+    plugins?: PlayerPlugin[];
+    /** A logger to use */
+    logger?: Logger;
+}
+interface PlayerInfo {
+    /** Version of the running player */
+    version: string;
+    /** Hash of the HEAD commit used to build the current version */
+    commit: string;
+}
+/**
+ * This is it.
+ */
+declare class Player {
+    static readonly info: PlayerInfo;
+    readonly logger: TapableLogger;
+    readonly constantsController: ConstantsController;
+    private config;
+    private state;
+    readonly hooks: {
+        /** The hook that fires every time we create a new flowController (a new Content blob is passed in) */
+        flowController: SyncHook<FlowController, any, any>;
+        /** The hook that updates/handles views */
+        viewController: SyncHook<ViewController, any, any>;
+        /** A hook called every-time there's a new view. This is equivalent to the view hook on the view-controller */
+        view: SyncHook<ViewInstance, any, any>;
+        /** Called when an expression evaluator was created */
+        expressionEvaluator: SyncHook<ExpressionEvaluator, any, any>;
+        /** The hook that creates and manages data */
+        dataController: SyncHook<DataController, any, any>;
+        /** Called after the schema is created for a flow */
+        schema: SyncHook<SchemaController, any, any>;
+        /** Manages validations (schema and x-field ) */
+        validationController: SyncHook<ValidationController, any, any>;
+        /** Manages parsing binding */
+        bindingParser: SyncHook<BindingParser, any, any>;
+        /** A that's called for state changes in the flow execution */
+        state: SyncHook<PlayerFlowState, any, any>;
+        /** A hook to access the current flow */
+        onStart: SyncHook<Flow<_player_ui_types.Asset<string>>, any, any>;
+        /** A hook for when the flow ends either in success or failure */
+        onEnd: SyncHook<any, any, any>;
+        /** Mutate the Content flow before starting */
+        resolveFlowContent: SyncWaterfallHook<Flow<_player_ui_types.Asset<string>>, any, any>;
+    };
+    constructor(config?: PlayerConfigOptions);
+    /** Find instance of [Plugin] that has been registered to Player */
+    findPlugin<Plugin extends PlayerPlugin>(symbol: symbol): Plugin | undefined;
+    /** Retrieve an instance of [Plugin] and conditionally invoke [apply] if it exists */
+    applyTo<Plugin extends PlayerPlugin>(symbol: symbol, apply: (plugin: Plugin) => void): void;
+    /** Register and apply [Plugin] if one with the same symbol is not already registered. */
+    registerPlugin(plugin: PlayerPlugin): void;
+    /** Returns the current version of the running player */
+    getVersion(): string;
+    /** Returns the git commit used to build Player version */
+    getCommit(): string;
+    /**
+     * Fetch the current state of Player.
+     * It will return either `not-started`, `in-progress`, `completed`
+     * with some extra data in each
+     */
+    getState(): PlayerFlowState;
+    /**
+     * A private means of setting the state of Player
+     * Calls the hooks for subscribers to listen for this event
+     */
+    private setState;
+    /** Start Player with the given flow */
+    private setupFlow;
+    start(payload: Flow): Promise<CompletedState>;
+}
+
+/**
+ * A plugin that taps into the flow controller to evaluate available expressions
+ * Expressions can be exposed via lifecycle "hooks" in flow/state nodes
+ * e.g: onStart, onEnd
+ */
+declare class FlowExpPlugin implements PlayerPlugin {
+    name: string;
+    apply(player: Player): void;
+}
+
+export { AssetTransformCorePlugin, BaseFlowState, BeforeTransformFunction, BindingTracker, CompletedState, ControllerState, DataController, ErrorState, FlowExpPlugin, InProgressState, LocalStateStore, NOT_STARTED_STATE, NotStartedState, Player, PlayerConfigOptions, PlayerFlowExecutionData, PlayerFlowState, PlayerFlowStatus, PlayerInfo, PlayerPlugin, RawSetTransaction, RawSetType, StatefulValidationObject, Store, TransformFunction, TransformFunctions, TransformRegistry, ValidationBindingTrackerViewPlugin, ValidationController, ViewController, ViewControllerOptions };