@player-ui/player 0.3.0-next.2 → 0.3.0-next.4

package/src/view/parser/index.ts

@@ -0,0 +1,318 @@
+import { setIn } from 'timm';
+import { SyncBailHook, SyncWaterfallHook } from 'tapable-ts';
+import type { Template } from '@player-ui/types';
+import type { Node, AnyAssetType } from './types';
+import { NodeType } from './types';
+
+export * from './types';
+
+export const EMPTY_NODE: Node.Empty = {
+  type: NodeType.Empty,
+};
+
+export interface ParseObjectOptions {
+  /** how nested the templated is */
+  templateDepth?: number;
+}
+
+interface NestedObj {
+  /** The values of a nested local object */
+  children: Node.Child[];
+
+  value: any;
+}
+/**
+ * The Parser is the way to take an incoming view from the user and parse it into an AST.
+ * It provides a few ways to interact with the parsing, including mutating an object before and after creation of an AST node
+ */
+export class Parser {
+  public readonly hooks = {
+    /**
+     * A hook to interact with an object _before_ parsing it into an AST
+     *
+     * @param value - The object we're are about to parse
+     * @returns - A new value to parse.
+     *  If undefined, the original value is used.
+     *  If null, we stop parsing this node.
+     */
+    onParseObject: new SyncWaterfallHook<[object, NodeType]>(),
+
+    /**
+     * A callback to interact with an AST _after_ we parse it into the AST
+     *
+     * @param value - The object we parsed
+     * @param node - The AST node we generated
+     * @returns - A new AST node to use
+     *   If undefined, the original value is used.
+     *   If null, we ignore this node all together
+     */
+    onCreateASTNode: new SyncWaterfallHook<
+      [Node.Node | undefined | null, object]
+    >(),
+
+    determineNodeType: new SyncBailHook<[object | string], NodeType>(),
+
+    parseNode: new SyncBailHook<
+      [
+        obj: object,
+        nodeType: Node.ChildrenTypes,
+        parseOptions: ParseObjectOptions,
+        determinedNodeType: NodeType | null
+      ],
+      Node.Node
+    >(),
+  };
+
+  public parseView(value: AnyAssetType): Node.View {
+    const viewNode = this.parseObject(value, NodeType.View);
+
+    if (!viewNode) {
+      throw new Error('Unable to parse object into a view');
+    }
+
+    return viewNode as Node.View;
+  }
+
+  public createASTNode(node: Node.Node | null, value: any): Node.Node | null {
+    const tapped = this.hooks.onCreateASTNode.call(node, value);
+
+    if (tapped === undefined) {
+      return node;
+    }
+
+    return tapped;
+  }
+
+  public parseObject(
+    obj: object,
+    type: Node.ChildrenTypes = NodeType.Value,
+    options: ParseObjectOptions = { templateDepth: 0 }
+  ): Node.Node | null {
+    const nodeType = this.hooks.determineNodeType.call(obj);
+
+    if (nodeType !== undefined) {
+      const parsedNode = this.hooks.parseNode.call(
+        obj,
+        type,
+        options,
+        nodeType
+      );
+      if (parsedNode) {
+        return parsedNode;
+      }
+    }
+
+    const parseLocalObject = (
+      currentValue: any,
+      objToParse: unknown,
+      path: string[] = []
+    ): NestedObj => {
+      if (typeof objToParse !== 'object' || objToParse === null) {
+        // value = objToParse;
+        return { value: objToParse, children: [] };
+      }
+
+      const localObj = this.hooks.onParseObject.call(objToParse, type);
+
+      if (!localObj) {
+        return currentValue;
+      }
+
+      const objEntries = Array.isArray(localObj)
+        ? localObj.map((v, i) => [i, v])
+        : Object.entries(localObj);
+
+      const defaultValue: NestedObj = {
+        children: [],
+        value: currentValue,
+      };
+
+      const newValue = objEntries.reduce((accumulation, current): NestedObj => {
+        const { children, ...rest } = accumulation;
+        const [localKey, localValue] = current;
+        if (localKey === 'asset' && typeof localValue === 'object') {
+          const assetAST = this.parseObject(
+            localValue,
+            NodeType.Asset,
+            options
+          );
+
+          if (assetAST) {
+            return {
+              ...rest,
+              children: [
+                ...children,
+                {
+                  path: [...path, 'asset'],
+                  value: assetAST,
+                },
+              ],
+            };
+          }
+        } else if (
+          this.hooks.determineNodeType.call(localKey) === NodeType.Template &&
+          Array.isArray(localValue)
+        ) {
+          const templateChildren = localValue
+            .map((template: Template) => {
+              const templateAST = this.hooks.onCreateASTNode.call(
+                {
+                  type: NodeType.Template,
+                  depth: options.templateDepth ?? 0,
+                  data: template.data,
+                  template: template.value,
+                  dynamic: template.dynamic ?? false,
+                },
+                template
+              );
+
+              if (templateAST) {
+                return {
+                  path: [...path, template.output],
+                  value: templateAST,
+                };
+              }
+
+              // eslint-disable-next-line no-useless-return
+              return;
+            })
+            .filter((element) => !!element);
+
+          return {
+            ...rest,
+            children: [...children, ...templateChildren],
+          } as NestedObj;
+        } else if (
+          localValue &&
+          this.hooks.determineNodeType.call(localValue) === NodeType.Switch
+        ) {
+          const localSwitch = this.hooks.parseNode.call(
+            localValue,
+            NodeType.Value,
+            options,
+            NodeType.Switch
+          );
+
+          if (localSwitch) {
+            return {
+              ...rest,
+              children: [
+                ...children,
+                {
+                  path: [...path, localKey],
+                  value: localSwitch,
+                },
+              ],
+            };
+          }
+        } else if (localValue && Array.isArray(localValue)) {
+          const childValues = localValue
+            .map((childVal) =>
+              this.parseObject(childVal, NodeType.Value, options)
+            )
+            .filter((child): child is Node.Node => !!child);
+
+          if (childValues.length > 0) {
+            const multiNode = this.hooks.onCreateASTNode.call(
+              {
+                type: NodeType.MultiNode,
+                override: true,
+                values: childValues,
+              },
+              localValue
+            );
+
+            if (multiNode?.type === NodeType.MultiNode) {
+              multiNode.values.forEach((v) => {
+                // eslint-disable-next-line no-param-reassign
+                v.parent = multiNode;
+              });
+            }
+
+            if (multiNode) {
+              return {
+                ...rest,
+                children: [
+                  ...children,
+                  {
+                    path: [...path, localKey],
+                    value: multiNode,
+                  },
+                ],
+              };
+            }
+          }
+        } else if (localValue && typeof localValue === 'object') {
+          const determineNodeType =
+            this.hooks.determineNodeType.call(localValue);
+
+          if (determineNodeType === NodeType.Applicability) {
+            const parsedNode = this.hooks.parseNode.call(
+              localValue,
+              type,
+              options,
+              determineNodeType
+            );
+            if (parsedNode) {
+              return {
+                ...rest,
+                children: [
+                  ...children,
+                  {
+                    path: [...path, localKey],
+                    value: parsedNode,
+                  },
+                ],
+              };
+            }
+          } else {
+            const result = parseLocalObject(accumulation.value, localValue, [
+              ...path,
+              localKey,
+            ]);
+            return {
+              value: result.value,
+              children: [...children, ...result.children],
+            };
+          }
+        } else {
+          const value = setIn(
+            accumulation.value,
+            [...path, localKey],
+            localValue
+          );
+
+          return {
+            children,
+            value,
+          };
+        }
+
+        return accumulation;
+      }, defaultValue);
+
+      return newValue;
+    };
+
+    const { value, children } = parseLocalObject(undefined, obj);
+
+    const baseAst =
+      value === undefined && children.length === 0
+        ? undefined
+        : {
+            type,
+            value,
+          };
+
+    if (baseAst !== undefined && children.length > 0) {
+      const parent = baseAst as Node.BaseWithChildren<any>;
+      parent.children = children;
+      children.forEach((child) => {
+        // eslint-disable-next-line no-param-reassign
+        child.value.parent = parent;
+      });
+    }
+
+    return this.hooks.onCreateASTNode.call(baseAst, obj) ?? null;
+  }
+}

package/src/view/parser/types.ts

@@ -0,0 +1,141 @@
+import type { Asset as AssetType, Expression, Binding } from '@player-ui/types';
+
+export type AnyAssetType = AssetType<string>;
+export enum NodeType {
+  Asset = 'asset',
+  View = 'view',
+  Applicability = 'applicability',
+  Template = 'template',
+  Value = 'value',
+  MultiNode = 'multi-node',
+  Switch = 'switch',
+  Unknown = 'unknown',
+  Empty = 'empty',
+}
+export declare namespace Node {
+  export type ChildrenTypes = NodeType.Asset | NodeType.Value | NodeType.View;
+
+  export interface Base<T extends NodeType> {
+    /** Every node contains a type to distinguish it from other nodes */
+    type: T;
+
+    /** Every node (outside of the root) contains a reference to it's parent */
+    parent?: Node;
+  }
+
+  export type PathSegment = string | number;
+
+  export interface Child {
+    /** The path of the child relative to the parent */
+    path: PathSegment[];
+
+    /** If true, the path points to an array, and the value will be appended to it result */
+    array?: boolean;
+
+    /** The child node */
+    value: Node;
+  }
+
+  export interface BaseWithChildren<T extends NodeType> extends Base<T> {
+    /** Any node that contains a list of children underneath it */
+    children?: Child[];
+  }
+
+  export interface Asset<T extends AnyAssetType = AnyAssetType>
+    extends BaseWithChildren<NodeType.Asset>,
+      PluginOptions {
+    /** Any asset nested within a view */
+    value: T;
+  }
+
+  export interface View<T extends AnyAssetType = AnyAssetType>
+    extends BaseWithChildren<NodeType.View>,
+      PluginOptions {
+    /** The root of the parsed view */
+    value: T;
+  }
+
+  export interface Applicability extends Base<NodeType.Applicability> {
+    /** The expression to execute that determines applicability of the target node */
+    expression: Expression;
+
+    /** The node to use if the expression is truthy */
+    value: Node;
+  }
+
+  export interface Template extends Base<NodeType.Template> {
+    /** The location of an array in the model */
+    data: Binding;
+
+    /** The template to use when mapping over the data */
+    template: unknown;
+
+    /** The number of nested templates so far */
+    depth: number;
+
+    /** should the template recomputed when data changes */
+    dynamic?: boolean;
+  }
+
+  export interface Value
+    extends BaseWithChildren<NodeType.Value>,
+      PluginOptions {
+    /** A simple node representing a value */
+    value: any;
+  }
+
+  export interface MultiNode extends Base<NodeType.MultiNode> {
+    /**
+     * Should this list override the target node if they overlap?
+     * If not amend the existing list
+     */
+    override?: boolean;
+
+    /** A list of values that comprise this node */
+    values: Array<Node>;
+  }
+
+  export interface Switch extends Base<NodeType.Switch> {
+    /** Should this list be re-computed when data changes */
+    dynamic?: boolean;
+
+    /** A list of cases to evaluate in order */
+    cases: SwitchCase[];
+  }
+
+  export interface SwitchCase {
+    /** The expression to evaluate for a single case statement */
+    case: Expression | true;
+    /** The value to use if this case is true */
+    value: Value;
+  }
+
+  export interface PluginOptions {
+    /** A list of plugins */
+    plugins?: {
+      /** StringResolverPlugin options */
+      stringResolver?: {
+        /**
+         * An optional array of node properties to skip during string resolution
+         * Specified in the AssetTransformPlugin
+         */
+        propertiesToSkip?: string[];
+      };
+    };
+  }
+
+  export type Unknown = Base<NodeType.Unknown>;
+  export type Empty = Base<NodeType.Empty>;
+  export type ViewOrAsset = View | Asset;
+
+  export type Node =
+    | Asset
+    | Applicability
+    | Template
+    | Value
+    | View
+    | MultiNode
+    | Switch
+    | Unknown
+    | Empty;
+}

package/src/view/plugins/applicability.ts

@@ -0,0 +1,78 @@
+import { omit } from 'timm';
+import type { ViewPlugin, View } from './plugin';
+import type { Options } from './options';
+import type { Resolver } from '../resolver';
+import type { Node, ParseObjectOptions, Parser } from '../parser';
+import { NodeType } from '../parser';
+
+/** A view plugin to remove inapplicable assets from the tree */
+export default class ApplicabilityPlugin implements ViewPlugin {
+  applyResolver(resolver: Resolver) {
+    resolver.hooks.beforeResolve.tap(
+      'applicability',
+      (node: Node.Node | null, options: Options) => {
+        let newNode = node;
+
+        if (node?.type === NodeType.Applicability) {
+          const isApplicable = options.evaluate(node.expression);
+
+          if (!isApplicable) {
+            return null;
+          }
+
+          newNode = node.value;
+        }
+
+        return newNode;
+      }
+    );
+  }
+
+  applyParser(parser: Parser) {
+    /** Switches resolved during the parsing phase are static */
+    parser.hooks.determineNodeType.tap('applicability', (obj: any) => {
+      if (Object.prototype.hasOwnProperty.call(obj, 'applicability')) {
+        return NodeType.Applicability;
+      }
+    });
+
+    parser.hooks.parseNode.tap(
+      'applicability',
+      (
+        obj: any,
+        nodeType: Node.ChildrenTypes,
+        options: ParseObjectOptions,
+        determinedNodeType: null | NodeType
+      ) => {
+        if (determinedNodeType === NodeType.Applicability) {
+          const parsedApplicability = parser.parseObject(
+            omit(obj, 'applicability'),
+            nodeType,
+            options
+          );
+          if (parsedApplicability !== null) {
+            const applicabilityNode = parser.createASTNode(
+              {
+                type: NodeType.Applicability,
+                expression: (obj as any).applicability,
+                value: parsedApplicability,
+              },
+              obj
+            );
+
+            if (applicabilityNode?.type === NodeType.Applicability) {
+              applicabilityNode.value.parent = applicabilityNode;
+            }
+
+            return applicabilityNode;
+          }
+        }
+      }
+    );
+  }
+
+  apply(view: View) {
+    view.hooks.resolver.tap('applicability', this.applyResolver.bind(this));
+    view.hooks.parser.tap('applicability', this.applyParser.bind(this));
+  }
+}

package/src/view/plugins/index.ts

@@ -0,0 +1,5 @@
+export { default as TemplatePlugin } from './template-plugin';
+export { default as StringResolverPlugin } from './string-resolver';
+export { default as ApplicabilityPlugin } from './applicability';
+export { default as SwitchPlugin } from './switch';
+export type { ViewPlugin } from './plugin';

package/src/view/plugins/options.ts

@@ -0,0 +1,4 @@
+import type { Resolve } from '../resolver';
+
+/** Config options that are required to resolve/update a view */
+export type Options = Resolve.NodeResolveOptions;

package/src/view/plugins/plugin.ts

@@ -0,0 +1,21 @@
+import type { SyncHook } from 'tapable-ts';
+import type { Resolver } from '../resolver';
+import type { Parser } from '../parser';
+
+/** The basic view api */
+export interface View {
+  /** The hooks for a view */
+  hooks: {
+    /** A hook when a parser is created for this view */
+    parser: SyncHook<[Parser]>;
+
+    /** A hook when a resolver is created for this view */
+    resolver: SyncHook<[Resolver]>;
+  };
+}
+
+/** A plugin for a view */
+export interface ViewPlugin {
+  /** Called with a view instance */
+  apply(view: View): void;
+}