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

package/types/view/resolver/index.d.ts

@@ -0,0 +1,73 @@
+import { SyncWaterfallHook, SyncHook } from "tapable-ts";
+import type { BindingInstance } from "../../binding";
+import type { Node } from "../parser";
+import type { Resolve } from "./types";
+export * from "./types";
+export * from "./utils";
+interface NodeUpdate extends Resolve.ResolvedNode {
+    /** A flag to track if a node has changed since the last resolution */
+    updated: boolean;
+}
+/**
+ * The Resolver is the way to take a parsed AST graph of a view and resolve it to a concrete representation of the current user state
+ * It combines the ability to mutate ast nodes before resolving, as well as the mutating the resolved objects while parsing
+ */
+export declare class Resolver {
+    readonly hooks: {
+        /** A hook to allow skipping of the resolution tree for a specific node */
+        skipResolve: SyncWaterfallHook<[boolean, Node.Node, Resolve.NodeResolveOptions], Record<string, any>>;
+        /** An event emitted before calculating the next update */
+        beforeUpdate: SyncHook<[Set<BindingInstance> | undefined], Record<string, any>>;
+        /** An event emitted after calculating the next update */
+        afterUpdate: SyncHook<[any], Record<string, any>>;
+        /** The options passed to a node to resolve it to an object */
+        resolveOptions: SyncWaterfallHook<[Resolve.NodeResolveOptions, Node.Node], Record<string, any>>;
+        /** A hook to transform the AST node into a new AST node before resolving it */
+        beforeResolve: SyncWaterfallHook<[Node.Node | null, Resolve.NodeResolveOptions], Record<string, any>>;
+        /**
+         * A hook to transform an AST node into it's resolved value.
+         * This runs _before_ any children are resolved
+         */
+        resolve: SyncWaterfallHook<[any, Node.Node, Resolve.NodeResolveOptions], Record<string, any>>;
+        /**
+         * A hook to transform the resolved value of an AST node.
+         * This runs _after_ all children nodes are resolved
+         */
+        afterResolve: SyncWaterfallHook<[any, Node.Node, Resolve.NodeResolveOptions], Record<string, any>>;
+        /** Called at the very end of a node's tree being updated */
+        afterNodeUpdate: SyncHook<[Node.Node, Node.Node | undefined, NodeUpdate], Record<string, any>>;
+    };
+    /**
+     * The AST tree after beforeResolve is ran mapped to the AST before beforeResolve is ran
+     */
+    private readonly ASTMap;
+    /**
+     * The root node in the AST tree we want to resolve
+     */
+    readonly root: Node.Node;
+    /**
+     * The cache of the last resolved values when walking the tree.
+     * This gets recycled every update to avoid stale data if a node is unused in an update
+     */
+    private resolveCache;
+    /**
+     * Cache of node IDs that have been processed to track if nodes have duplicate IDs
+     */
+    private idCache;
+    /**
+     * The parameters required to resolve AST nodes
+     */
+    private readonly options;
+    /**
+     * Tapable logger for logging errors encountered during view resolution
+     */
+    private logger?;
+    constructor(root: Node.Node, options: Resolve.ResolverOptions);
+    getSourceNode(convertedAST: Node.Node): Node.Node | undefined;
+    update(changes?: Set<BindingInstance>): any;
+    getResolveCache(): Map<Node.Node, Resolve.ResolvedNode>;
+    private getPreviousResult;
+    private cloneNode;
+    private computeTree;
+}
+//# sourceMappingURL=index.d.ts.map

package/types/view/resolver/types.d.ts

@@ -0,0 +1,129 @@
+import type { Schema, Formatting, Validation as ValidationTypes } from "@player-ui/types";
+import type { BindingInstance, BindingLike, BindingFactory } from "../../binding";
+import type { DataModelWithParser, DataModelImpl, DataModelOptions } from "../../data";
+import type { ConstantsProvider } from "../../controllers/constants";
+import type { TransitionFunction } from "../../controllers";
+import type { ExpressionEvaluator, ExpressionType } from "../../expressions";
+import type { ValidationResponse } from "../../validator";
+import type { Logger } from "../../logger";
+import type { SchemaController } from "../../schema";
+import type { Node } from "../parser";
+export interface ValidationGetResolveOptions {
+    /**
+     * If we should ignore any non-blocking validations in the return
+     * @default true
+     */
+    ignoreNonBlocking?: boolean;
+}
+export interface PlayerUtils {
+    findPlugin<Plugin = unknown>(symbol: symbol): Plugin | undefined;
+}
+export declare namespace Resolve {
+    interface Validation {
+        /** Fetch the data-type for the given binding */
+        type(binding: BindingLike): Schema.DataType | undefined;
+        /** Get all currently applicable validation errors */
+        getAll(options?: ValidationGetResolveOptions): Map<BindingInstance, ValidationResponse> | undefined;
+        /** Internal Method to lookup if there is a validation for the given binding */
+        _getValidationForBinding(binding: BindingLike): {
+            /** Get the validation for the given binding */
+            get: (options?: ValidationGetResolveOptions) => ValidationResponse | undefined;
+            /** Get all validations for the given binding */
+            getAll: (options?: ValidationGetResolveOptions) => Array<ValidationResponse>;
+        } | undefined;
+        /** Get field level error for the specific binding */
+        get(binding: BindingLike, options?: {
+            /** If this binding should also be tracked for validations */
+            track?: boolean;
+        } & ValidationGetResolveOptions): ValidationResponse | undefined;
+        getValidationsForBinding(binding: BindingLike, options?: {
+            /** If this binding should also be tracked for validations */
+            track?: boolean;
+        } & ValidationGetResolveOptions): Array<ValidationResponse>;
+        /** Get errors for all children regardless of section */
+        getChildren(type?: ValidationTypes.DisplayTarget): Array<ValidationResponse>;
+        /** Get errors for all children solely in this section */
+        getValidationsForSection(): Array<ValidationResponse>;
+        /** Track errors for this binding, and notify the node of changes */
+        track: (binding: BindingLike) => void;
+        /** Register node as a section */
+        register: (options?: {
+            /** While type of Display Target group it should register as */
+            type: Exclude<ValidationTypes.DisplayTarget, "field">;
+        }) => void;
+    }
+    interface BaseOptions {
+        /** A logger to use */
+        logger?: Logger;
+        /** Utils for various useful operations */
+        utils?: PlayerUtils;
+        /** An optional set of validation features */
+        validation?: Validation;
+        /** Parse a raw valy into an AST node */
+        parseNode?: (node: any) => Node.Node | null;
+        /** A function to move the state to a new place */
+        transition?: TransitionFunction;
+        /** The hub for data invariants and metaData associated with the data model */
+        schema: SchemaController;
+        /** The constants for messages */
+        constants?: ConstantsProvider;
+    }
+    interface NodeDataOptions {
+        /** The data to set or get data from */
+        model: DataModelWithParser<DataModelOptions>;
+        /**
+         * A function to format a given a value (given a binding) for display to the user
+         * Note: this doesn't persist any changes in the model.
+         */
+        format: (binding: BindingLike, value: any) => any;
+        /**
+         * A function to format a given value using a formatting reference.
+         * The default behavior is the identity function.
+         */
+        formatValue: (formatReference: Formatting.Reference, value: any) => any;
+    }
+    type NodeResolveOptions = BaseOptions & {
+        /** Execute the expression and return it's result */
+        evaluate: (exp: ExpressionType) => any;
+        /** All parameters for how to process data */
+        data: NodeDataOptions;
+        /** The data dependencies that were requested during the resolution */
+        getDependencies?(scope?: "core" | "children"): Set<BindingInstance>;
+        /** original node */
+        node?: Node.Node;
+    };
+    type ResolverOptions = BaseOptions & {
+        /** The data model to set or get data from */
+        model: DataModelImpl<DataModelOptions>;
+        /** A formatter function to call */
+        format?: (binding: BindingInstance, value: any) => any;
+        /**
+         * A function to format a given value using a formatting reference.
+         * The default behavior is the identity function.
+         */
+        formatValue?: (formatReference: Formatting.Reference, value: any) => any;
+        /** An evaluator to execute an expression */
+        evaluator: ExpressionEvaluator;
+        /** A fn to parse a raw binding into a binding object */
+        parseBinding: BindingFactory;
+    };
+    interface ResolvedNode {
+        /** The original node */
+        node: Node.Node;
+        /** The data dependencies that were requested during the resolution */
+        dependencies: Set<BindingInstance>;
+        /** The final value */
+        value: any;
+    }
+    type NodeTransformFunction = (node: Node.Node, options: NodeResolveOptions) => Node.Node | null;
+    type NodeResolveFunction = (value: any, node: Node.Node, options: NodeResolveOptions) => any;
+    interface Plugin {
+        /** A transform function to migrate an AST to another AST */
+        beforeResolve?: NodeTransformFunction;
+        /** A function to transform an AST to a resolved value */
+        resolve?: NodeResolveFunction;
+        /** A function to process a resolved value before completing the node */
+        afterResolve?: NodeResolveFunction;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/types/view/resolver/utils.d.ts

@@ -0,0 +1,11 @@
+import type { BindingInstance } from "../../binding";
+import type { Resolve } from "./types";
+/** Check to see if and of the data-changes affect the given dependencies  */
+export declare function caresAboutDataChanges(dataChanges?: Set<BindingInstance>, dependencies?: Set<BindingInstance>): boolean;
+/** Convert the options object for a resolver to one for a node */
+export declare function toNodeResolveOptions(resolverOptions: Resolve.ResolverOptions): Resolve.NodeResolveOptions;
+/**
+ * helper function to flatten a potential nested array and combine with initial array
+ */
+export declare function unpackAndPush(item: any | any[], initial: any[]): void;
+//# sourceMappingURL=utils.d.ts.map

package/types/view/view.d.ts

@@ -0,0 +1,37 @@
+import { SyncHook } from "tapable-ts";
+import type { View as ViewType } from "@player-ui/types";
+import type { BindingInstance } from "../binding";
+import type { ValidationProvider, ValidationObject } from "../validator";
+import type { Resolve } from "./resolver";
+import { Resolver } from "./resolver";
+import { Parser } from "./parser";
+import { TemplatePlugin } from "./plugins";
+/** A stateful view instance from an content */
+export declare class ViewInstance implements ValidationProvider {
+    hooks: {
+        onUpdate: SyncHook<[import("@player-ui/types").Asset<string> & {
+            validation?: import("@player-ui/types").Validation.CrossfieldReference[] | undefined;
+        }], Record<string, any>>;
+        parser: SyncHook<[Parser], Record<string, any>>;
+        resolver: SyncHook<[Resolver], Record<string, any>>;
+        onTemplatePluginCreated: SyncHook<[TemplatePlugin], Record<string, any>>;
+        templatePlugin: SyncHook<[TemplatePlugin], Record<string, any>>;
+    };
+    private resolver?;
+    readonly initialView: ViewType;
+    readonly resolverOptions: Resolve.ResolverOptions;
+    private rootNode?;
+    private validationProvider?;
+    private templatePlugin;
+    lastUpdate: Record<string, any> | undefined;
+    constructor(initialView: ViewType, resolverOptions: Resolve.ResolverOptions);
+    updateAsync(): void;
+    update(changes?: Set<BindingInstance>): any;
+    getValidationsForBinding(binding: BindingInstance): ValidationObject[] | undefined;
+}
+/** A plugin for a view */
+export interface ViewPlugin {
+    /** Called with a view instance */
+    apply(view: ViewInstance): void;
+}
+//# sourceMappingURL=view.d.ts.map