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

package/src/schema/types.ts

@@ -0,0 +1,60 @@
+import type { Formatting } from '@player-ui/types';
+
+export type FormatOptions = Omit<Formatting.Reference, 'type'>;
+
+/**
+ * The return types for the schema don't include options.
+ * These are already sent to the generic formatter function for that type
+ */
+export type FormatFunction<From, To = From, Options = unknown> = (
+  val: From,
+  options?: Options
+) => To | undefined;
+
+export type FormatHandler<From, To = From> = (val: From) => To;
+
+export interface FormatDefinition<DataModelType, UserDisplayType> {
+  /**
+   * A function to format data (from the data-model to the user).
+   * Defaults to the identify function
+   */
+  format: FormatHandler<DataModelType, UserDisplayType>;
+
+  /**
+   * A function to invert the formatting (from the user to the data-model)
+   * Defaults to the identify function.
+   */
+  deformat: FormatHandler<UserDisplayType, DataModelType>;
+}
+
+export interface FormatType<
+  DataModelType,
+  UserDisplayType = DataModelType,
+  Options = undefined
+> {
+  /**
+   * The name of the formatter.
+   * This corresponds to the 'type' format property when creating a DataType
+   */
+  name: string;
+
+  /**
+   * An optional function to format data for display to the user.
+   * This goes from dataModel -> UI display
+   */
+  format?: FormatFunction<
+    DataModelType | UserDisplayType,
+    UserDisplayType,
+    Options
+  >;
+
+  /**
+   * An optional function for undo the action of a format function for storage.
+   * This goes from UI -> dataModel
+   */
+  deformat?: FormatFunction<
+    UserDisplayType | DataModelType,
+    DataModelType,
+    Options
+  >;
+}

package/src/string-resolver/index.ts

@@ -0,0 +1,188 @@
+import { setIn } from 'timm';
+import type { Expression } from '@player-ui/types';
+import type { DataModelWithParser } from '../data';
+
+const DOUBLE_OPEN_CURLY = '{{';
+const DOUBLE_CLOSE_CURLY = '}}';
+
+export interface Options {
+  /** The model to use when resolving refs */
+  model: DataModelWithParser;
+
+  /** A function to evaluate an expression */
+  evaluate: (exp: Expression) => any;
+}
+
+/** Search the given string for the coordinates of the next expression to resolve */
+export function findNextExp(str: string) {
+  const expStart = str.indexOf(DOUBLE_OPEN_CURLY);
+
+  if (expStart === -1) {
+    return undefined;
+  }
+
+  let count = 1;
+  let offset = expStart + DOUBLE_OPEN_CURLY.length;
+  let workingString = str.substring(expStart + DOUBLE_OPEN_CURLY.length);
+
+  while (count > 0 && workingString.length > 0) {
+    // Find the next open or close curly
+    const nextCloseCurly = workingString.indexOf(DOUBLE_CLOSE_CURLY);
+
+    // We can't close anything, so there's no point in going on with life.
+    if (nextCloseCurly === -1) {
+      break;
+    }
+
+    const nextOpenCurly = workingString.indexOf(DOUBLE_OPEN_CURLY);
+
+    if (nextOpenCurly !== -1 && nextOpenCurly < nextCloseCurly) {
+      // We've hit another open bracket before closing out the one we want
+      // Move everything over and bump our close count by 1
+      count++;
+      workingString = workingString.substring(
+        nextOpenCurly + DOUBLE_OPEN_CURLY.length
+      );
+      offset += nextOpenCurly + DOUBLE_OPEN_CURLY.length;
+    } else {
+      // We've hit another closing bracket
+      // Decrement our count and updates offsets
+      count--;
+      workingString = workingString.substring(
+        nextCloseCurly + DOUBLE_CLOSE_CURLY.length
+      );
+      offset += nextCloseCurly + DOUBLE_CLOSE_CURLY.length;
+    }
+  }
+
+  if (count !== 0) {
+    throw new Error(`Unbalanced {{ and }} in exp: ${str}`);
+  }
+
+  return {
+    start: expStart,
+    end: offset,
+  };
+}
+
+/** Finds any subset of the string wrapped in @[]@ and evaluates it as an expression */
+export function resolveExpressionsInString(
+  val: string,
+  { evaluate }: Options
+): string {
+  const expMatch = /@\[.*?\]@/;
+  let newVal = val;
+  let match = newVal.match(expMatch);
+
+  while (match !== null) {
+    const expStrWithBrackets = match[0];
+    const matchStart = newVal.indexOf(expStrWithBrackets);
+
+    const expString = expStrWithBrackets.substr(
+      '@['.length,
+      expStrWithBrackets.length - '@['.length - ']@'.length
+    );
+    const expValue = evaluate(expString);
+
+    // The string is only the expression, return the raw value.
+    if (
+      matchStart === 0 &&
+      expStrWithBrackets === val &&
+      typeof expValue !== 'string'
+    ) {
+      return expValue;
+    }
+
+    newVal =
+      newVal.substr(0, matchStart) +
+      expValue +
+      newVal.substr(matchStart + expStrWithBrackets.length);
+    // remove the surrounding @[]@ to get the expression
+    match = newVal.match(expMatch);
+  }
+
+  return newVal;
+}
+
+/** Return a string with all data model references resolved */
+export function resolveDataRefsInString(val: string, options: Options): string {
+  const { model } = options;
+  let workingString = resolveExpressionsInString(val, options);
+
+  if (
+    typeof workingString !== 'string' ||
+    workingString.indexOf(DOUBLE_OPEN_CURLY) === -1
+  ) {
+    return workingString;
+  }
+
+  while (workingString.indexOf(DOUBLE_OPEN_CURLY) !== -1) {
+    const expLocation = findNextExp(workingString);
+
+    if (!expLocation) {
+      return workingString;
+    }
+
+    const { start, end } = expLocation;
+
+    // Strip out the wrapping curlies from {{binding}} before passing to the model
+    const binding = workingString
+      .substring(
+        start + DOUBLE_OPEN_CURLY.length,
+        end - DOUBLE_OPEN_CURLY.length
+      )
+      .trim();
+
+    const evaledVal = model.get(binding, { formatted: true });
+
+    // Exit early if the string is _just_ a model lookup
+    // If the result is a string, we may need further processing for nested bindings
+    if (
+      start === 0 &&
+      end === workingString.length &&
+      typeof evaledVal !== 'string'
+    ) {
+      return evaledVal;
+    }
+
+    workingString =
+      workingString.substr(0, start) + evaledVal + workingString.substr(end);
+  }
+
+  return workingString;
+}
+
+/** Traverse the thing and replace any model refs */
+function traverseObject<T>(val: T, options: Options): T {
+  switch (typeof val) {
+    case 'string': {
+      return resolveDataRefsInString(val as string, options) as unknown as T;
+    }
+
+    case 'object': {
+      // TODO: Do we care refs in keys?
+      const keys = Object.keys(val);
+      let newVal = val;
+
+      if (keys.length > 0) {
+        for (const key of keys) {
+          newVal = setIn(
+            newVal as any,
+            [key],
+            traverseObject((val as any)[key], options)
+          ) as any;
+        }
+      }
+
+      return newVal;
+    }
+
+    default:
+      return val;
+  }
+}
+
+/** Recursively resolve all model refs in whatever you pass in */
+export function resolveDataRefs<T>(val: T, options: Options): T {
+  return traverseObject(val, options);
+}

package/src/types.ts

@@ -1,17 +1,15 @@
 import type { Flow, FlowResult } from '@player-ui/types';
-import { Expression } from '@player-ui/types';
-import type { DataModelWithParser } from '@player-ui/data';
-import { DataModelOptions } from '@player-ui/data';
-import type { FlowController } from '@player-ui/flow';
-import { NamedState, TransitionFunction } from '@player-ui/flow';
-import { ViewInstance } from '@player-ui/view';
-import type { BindingParser, BindingLike } from '@player-ui/binding';
-import type { SchemaController } from '@player-ui/schema';
-import type { ExpressionEvaluator } from '@player-ui/expressions';
-import type { Logger } from '@player-ui/logger';
-import type { ViewController } from './view';
-import type { DataController } from './data';
-import type { ValidationController } from './validation';
+import type { DataModelWithParser } from './data';
+import type { BindingParser, BindingLike } from './binding';
+import type { SchemaController } from './schema';
+import type { ExpressionEvaluator } from './expressions';
+import type { Logger } from './logger';
+import type {
+  ViewController,
+  DataController,
+  ValidationController,
+  FlowController,
+} from './controllers';
 
 /** The status for a flow's execution state */
 export type PlayerFlowStatus =

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './replaceParams';

package/src/utils/replaceParams.ts

@@ -0,0 +1,17 @@
+const ANY_CHAR_REGEX = /%([a-zA-Z]+)/g;
+
+/**
+ * Replaces %num in message with the provided parameters in order.
+ *
+ * @param message - Parameterized string like "This is a %1"
+ * @param params - Parameters to replace in message E.g. ['tax2021.amount']
+ * @returns A message with the parameters replaced.
+ */
+export function replaceParams(
+  message: string,
+  params: Record<string, any>
+): string {
+  return message
+    .slice()
+    .replace(ANY_CHAR_REGEX, (keyExpr) => params[keyExpr.slice(1)] || keyExpr);
+}

package/src/validator/index.ts

@@ -0,0 +1,3 @@
+export * from './validation-middleware';
+export * from './types';
+export * from './registry';

package/src/validator/registry.ts

@@ -0,0 +1,20 @@
+import type { ValidatorFunction } from './types';
+
+/** A registry that tracks validators  */
+export class ValidatorRegistry {
+  private registry: Map<string, ValidatorFunction<any>>;
+
+  constructor() {
+    this.registry = new Map();
+  }
+
+  /** Use the given validator name to fetch the handler */
+  public get(name: string): ValidatorFunction | undefined {
+    return this.registry.get(name);
+  }
+
+  /** Register a new validator */
+  public register<T>(name: string, handler: ValidatorFunction<T>) {
+    this.registry.set(name, handler);
+  }
+}

package/src/validator/types.ts

@@ -0,0 +1,75 @@
+import type { Validation } from '@player-ui/types';
+
+import type { BindingInstance, BindingFactory } from '../binding';
+import type { DataModelWithParser } from '../data';
+import type { ExpressionEvaluatorFunction } from '../expressions';
+import type { Logger } from '../logger';
+import type { ConstantsProvider } from '../controllers';
+
+interface BaseValidationResponse<T = Validation.Severity> {
+  /** The validation message to show to the user */
+  message: string;
+
+  /** List of parameters associated with a validation. These can be replaced into a templatized message string. */
+  parameters?: Record<string, any>;
+
+  /** How serious is this violation */
+  severity: T;
+
+  /** Where this validation should be displayed */
+  displayTarget?: Validation.DisplayTarget;
+
+  /** The blocking state of this validation */
+  blocking?: boolean | 'once';
+}
+
+export interface WarningValidationResponse
+  extends BaseValidationResponse<'warning'> {
+  /** Warning validations can be dismissed without correcting the error */
+  dismiss?: () => void;
+}
+
+export type ErrorValidationResponse = BaseValidationResponse<'error'>;
+
+export type ValidationResponse =
+  | ErrorValidationResponse
+  | WarningValidationResponse;
+
+type RequiredValidationKeys = 'severity' | 'trigger';
+
+export type ValidationObject = Validation.Reference &
+  Required<Pick<Validation.Reference, RequiredValidationKeys>>;
+
+export interface ValidationProvider {
+  getValidationsForBinding?(
+    binding: BindingInstance
+  ): Array<ValidationObject> | undefined;
+
+  getValidationsForView?(): Array<ValidationObject> | undefined;
+}
+
+export interface ValidatorContext {
+  /** The data to set or get data from */
+  model: DataModelWithParser;
+
+  /** A means of parsing a binding */
+  parseBinding: BindingFactory;
+
+  /** Execute the expression and return it's result */
+  evaluate: ExpressionEvaluatorFunction;
+
+  /** Logger instance to use */
+  logger: Logger;
+
+  /** The validation object that triggered this function */
+  validation: ValidationObject;
+
+  /** The constants for messages */
+  constants: ConstantsProvider;
+}
+
+export type ValidatorFunction<Options = unknown> = (
+  context: ValidatorContext,
+  value: any,
+  options?: Options
+) => Omit<BaseValidationResponse, 'severity'> | undefined;

package/src/validator/validation-middleware.ts

@@ -0,0 +1,114 @@
+import { setIn } from 'timm';
+import type { BindingInstance } from '../binding';
+import type {
+  BatchSetTransaction,
+  DataModelImpl,
+  DataModelOptions,
+  DataModelMiddleware,
+  Updates,
+} from '../data';
+import { toModel } from '../data';
+import type { Logger } from '../logger';
+
+import type { ValidationResponse } from './types';
+
+/**
+ * Returns a validation object if the data is invalid or an set of BindingsInstances if the binding itself is a weak ref of another invalid validation
+ */
+export type MiddlewareChecker = (
+  binding: BindingInstance,
+  model: DataModelImpl
+) => ValidationResponse | Set<BindingInstance> | undefined;
+
+/**
+ * Middleware for the data-model that caches the results of invalid data
+ */
+export class ValidationMiddleware implements DataModelMiddleware {
+  public validator: MiddlewareChecker;
+  public shadowModelPaths: Map<BindingInstance, any>;
+  private logger?: Logger;
+
+  constructor(
+    validator: MiddlewareChecker,
+    options?: {
+      /** A logger instance */
+      logger?: Logger;
+    }
+  ) {
+    this.validator = validator;
+    this.shadowModelPaths = new Map();
+    this.logger = options?.logger;
+  }
+
+  public set(
+    transaction: BatchSetTransaction,
+    options?: DataModelOptions,
+    next?: DataModelImpl
+  ): Updates {
+    const asModel = toModel(this, { ...options, includeInvalid: true }, next);
+    const nextTransaction: BatchSetTransaction = [];
+
+    transaction.forEach(([binding, value]) => {
+      this.shadowModelPaths.set(binding, value);
+    });
+
+    const invalidBindings: Array<BindingInstance> = [];
+
+    this.shadowModelPaths.forEach((value, binding) => {
+      const validations = this.validator(binding, asModel);
+
+      if (validations === undefined) {
+        nextTransaction.push([binding, value]);
+      } else if (validations instanceof Set) {
+        invalidBindings.push(...validations);
+      } else {
+        this.logger?.debug(
+          `Invalid value for path: ${binding.asString()} - ${
+            validations.severity
+          } - ${validations.message}`
+        );
+      }
+    });
+
+    if (next && nextTransaction.length > 0) {
+      // defer clearing the shadow model to prevent validations that are run twice due to weak binding refs still needing the data
+      nextTransaction.forEach(([binding]) =>
+        this.shadowModelPaths.delete(binding)
+      );
+      return next.set(nextTransaction, options);
+    }
+
+    return invalidBindings.map((binding) => {
+      return {
+        binding,
+        oldValue: asModel.get(binding),
+        newValue: asModel.get(binding),
+        force: true,
+      };
+    });
+  }
+
+  public get(
+    binding: BindingInstance,
+    options?: DataModelOptions,
+    next?: DataModelImpl
+  ) {
+    let val = next?.get(binding, options);
+
+    if (options?.includeInvalid === true) {
+      this.shadowModelPaths.forEach((shadowValue, shadowBinding) => {
+        if (shadowBinding === binding) {
+          val = shadowValue;
+
+          return;
+        }
+
+        if (binding.contains(shadowBinding)) {
+          val = setIn(val, shadowBinding.relative(binding), shadowValue);
+        }
+      });
+    }
+
+    return val;
+  }
+}

package/src/view/builder/index.ts

@@ -0,0 +1,81 @@
+import type { Node, AnyAssetType } from '../parser';
+import { NodeType } from '../parser';
+
+/**
+ * Functions for building AST nodes (relatively) easily
+ */
+export class Builder {
+  /**
+   * Creates an asset node
+   *
+   * @param value - the value to put in the asset node
+   */
+  static asset<T extends AnyAssetType>(value: T): Node.Asset<T> {
+    return {
+      type: NodeType.Asset,
+      value,
+    };
+  }
+
+  /**
+   * Creates a value node
+   *
+   * @param v - The object to put in the value node
+   */
+  static value(v?: object): Node.Value {
+    return {
+      type: NodeType.Value,
+      value: v,
+    };
+  }
+
+  /**
+   * Creates a multiNode and associates the multiNode as the parent
+   * of all the value nodes
+   *
+   * @param values - the value or applicability nodes to put in the multinode
+   */
+  static multiNode(
+    ...values: (Node.Value | Node.Applicability)[]
+  ): Node.MultiNode {
+    const m: Node.MultiNode = {
+      type: NodeType.MultiNode,
+      override: true,
+      values,
+    };
+
+    values.forEach((v) => {
+      // eslint-disable-next-line no-param-reassign
+      v.parent = m;
+    });
+
+    return m;
+  }
+
+  /**
+   * Adds a child node to a node
+   *
+   * @param node - The node to add a child to
+   * @param path - The path at which to add the child
+   * @param child - The child node
+   */
+  static addChild<N extends Node.BaseWithChildren<NT>, NT extends NodeType>(
+    node: N,
+    path: Node.PathSegment | Node.PathSegment[],
+    child: Node.Node
+  ) {
+    // eslint-disable-next-line no-param-reassign
+    child.parent = node as Node.Node;
+
+    const newChild: Node.Child = {
+      path: Array.isArray(path) ? path : [path],
+      value: child,
+    };
+
+    // eslint-disable-next-line no-param-reassign
+    node.children = node.children || [];
+    node.children.push(newChild);
+
+    return node;
+  }
+}

package/src/view/index.ts

@@ -1,4 +1,5 @@
-export * from './asset-transform';
-export * from './controller';
-export * from './store';
-export * from './types';
+export * from './view';
+export * from './resolver';
+export * from './parser';
+export * from './builder';
+export * from './plugins';