@player-tools/dsl 0.0.2-next.0

package/src/template.tsx

@@ -0,0 +1,186 @@
+import React from 'react';
+import type { ObjectNode, JsonNode } from 'react-json-reconciler';
+import {
+  ArrayNode,
+  PropertyNode,
+  ValueNode,
+  createPortal,
+  ProxyNode,
+  toJSON,
+} from 'react-json-reconciler';
+import { OptionalIDSuffixProvider } from './auto-id';
+import type { BindingTemplateInstance } from './string-templates';
+import type { WithChildren } from './types';
+
+export interface TemplateContextType {
+  /** The number of nested templates */
+  depth: number;
+}
+
+export const TemplateContext = React.createContext<TemplateContextType>({
+  depth: 0,
+});
+
+export interface TemplateProps {
+  /** The source binding */
+  data: BindingTemplateInstance;
+
+  /** The target property */
+  output?: string;
+
+  /** The template value */
+  children: React.ReactNode;
+}
+
+/** Add a template instance to the object */
+function addTemplateToObject(
+  obj: ObjectNode,
+  templateObj: ObjectNode,
+  templateParentNodeType: string
+): () => void {
+  // find a template property
+  // add one if none exists
+
+  let templateProp = obj.properties.find(
+    (p) => p.keyNode.value === 'template' && p.valueNode?.type === 'array'
+  );
+
+  if (!templateProp) {
+    templateProp = new PropertyNode(new ValueNode('template'), new ArrayNode());
+    templateProp.parent = obj;
+    obj.properties.push(templateProp);
+  }
+
+  const templateItems = templateProp.valueNode as ArrayNode;
+
+  templateItems.items.push(templateObj);
+  // eslint-disable-next-line no-param-reassign
+  templateObj.parent = templateItems;
+
+  const templateParentProp = obj.properties.find(
+    (p) =>
+      p.keyNode.value === templateParentNodeType &&
+      p.valueNode?.type === 'array'
+  );
+
+  if (templateParentProp) {
+    const indexOfTemplateParent = obj.properties.indexOf(templateParentProp, 1);
+    const templateParentValueNode =
+      obj.properties[indexOfTemplateParent]?.valueNode;
+    if (templateParentValueNode) {
+      const templateParentArray = toJSON(templateParentValueNode);
+
+      // Delete the parent of template if it is an empty array
+      if (
+        Array.isArray(templateParentArray) &&
+        templateParentArray.length === 0
+      ) {
+        obj.properties.splice(indexOfTemplateParent, 1);
+      }
+    }
+  }
+
+  return () => {
+    // Remove the template item from the list
+    templateItems.items = templateItems.items.filter((t) => t !== templateObj);
+
+    // Clean up the whole template if it's removed
+    if (templateItems.children.length === 0 && templateProp) {
+      obj.properties.splice(obj.properties.indexOf(templateProp, 1));
+    }
+  };
+}
+
+/** Context provider wrapper to handle nested templates */
+const TemplateProvider = (props: WithChildren) => {
+  const baseContext = React.useContext(TemplateContext);
+
+  return (
+    <TemplateContext.Provider value={{ depth: baseContext.depth + 1 }}>
+      {props.children}
+    </TemplateContext.Provider>
+  );
+};
+
+/** Find the first object node in the tree */
+const getParentObject = (node: JsonNode): ObjectNode | undefined => {
+  if (node.type === 'object') {
+    return node;
+  }
+
+  if (node.parent) {
+    return getParentObject(node.parent);
+  }
+};
+
+/** Find the property of the node on the parent */
+const getParentProperty = (node: JsonNode): PropertyNode | undefined => {
+  if (node.type === 'property') {
+    return node;
+  }
+
+  if (node.parent) {
+    return getParentProperty(node.parent);
+  }
+};
+
+/** A template allows users to dynamically map over an array of data */
+export const Template = (props: TemplateProps) => {
+  const baseContext = React.useContext(TemplateContext);
+  const [outputProp, setOutputProp] = React.useState<string | undefined>(
+    props.output
+  );
+  const proxyRef = React.useRef<ProxyNode>(null);
+  const valueRef = React.useRef<ValueNode>(null);
+  const outputElement = React.useMemo(() => new ProxyNode(), []);
+
+  React.useLayoutEffect(() => {
+    // Get the output prop
+    const propNode = proxyRef.current && getParentProperty(proxyRef.current);
+
+    if (outputProp === undefined && propNode) {
+      setOutputProp(propNode.keyNode.value);
+    }
+  }, [proxyRef, outputProp]);
+
+  React.useEffect(() => {
+    const templateObj = outputElement.items[0] as ObjectNode;
+    if (proxyRef.current) {
+      const parentObject = getParentObject(proxyRef.current);
+
+      if (!parentObject) {
+        throw new Error('Unable to find parent to add template to');
+      }
+
+      if (!outputProp) {
+        return;
+      }
+
+      // remove the template when unmounted
+      return addTemplateToObject(parentObject, templateObj, outputProp);
+    }
+  }, [proxyRef, outputProp, outputElement.items]);
+
+  return (
+    <proxy ref={proxyRef}>
+      {createPortal(
+        <OptionalIDSuffixProvider
+          wrapperRef={valueRef}
+          templateIndex={`_index${
+            baseContext.depth === 0 ? '' : baseContext.depth
+          }_`}
+        >
+          <TemplateProvider>
+            <object>
+              <property name="data">{props.data.toValue()}</property>
+              <property name="output">{outputProp}</property>
+              <property name="value">{props.children}</property>
+            </object>
+          </TemplateProvider>
+        </OptionalIDSuffixProvider>,
+        outputElement
+      )}
+      <value ref={valueRef} value={undefined} />
+    </proxy>
+  );
+};

package/src/types.ts

@@ -0,0 +1,81 @@
+import type {
+  Asset,
+  Expression,
+  Navigation as PlayerNav,
+} from '@player-ui/types';
+import type {
+  BindingTemplateInstance,
+  ExpressionTemplateInstance,
+} from './string-templates';
+
+export type WithChildren<T = Record<string, unknown>> = T & {
+  /** child nodes */
+  children?: React.ReactNode;
+};
+
+export type RemoveUnknownIndex<T> = {
+  [P in keyof T as T[P] extends unknown
+    ? unknown extends T[P]
+      ? never
+      : P
+    : P]: T[P];
+};
+
+export type AddUnknownIndex<T> = T & {
+  [key: string]: unknown;
+};
+
+/** Make an ID prop optional an a type */
+export type OmitProp<T, K extends string> = {
+  [P in keyof T as P extends K ? never : P]: T[P];
+};
+
+export interface PlayerApplicability {
+  /** An expression to evaluate to determine if this node should appear in a view or not */
+  applicability?:
+    | BindingTemplateInstance
+    | ExpressionTemplateInstance
+    | boolean;
+}
+
+export type AssetPropsWithChildren<T extends Asset> = WithChildren<
+  WithTemplateTypes<
+    OmitProp<RemoveUnknownIndex<T>, 'id' | 'type'> & Partial<Pick<Asset, 'id'>>
+  > &
+    PlayerApplicability
+>;
+
+export type SwapKeysToType<T, K extends keyof T, NewType> = {
+  [P in keyof T]: P extends K ? NewType : T[P];
+};
+
+export type WithTemplateTypes<T> = T extends Record<any, any>
+  ? {
+      [P in keyof T]: WithTemplateTypes<T[P]>;
+    }
+  : T | BindingTemplateInstance | ExpressionTemplateInstance;
+
+type ValidKeys = 'exp' | 'onStart' | 'onEnd';
+
+type DeepReplace<T, Old, New> = {
+  [P in keyof T]: T[P] extends Old
+    ? P extends ValidKeys
+      ? New
+      : DeepReplace<T[P], Old, New> // Set to new if one of the valid keys: replace with `? New` for all keys
+    : T[P] extends (infer R)[] // Is this a Tuple or array
+    ? DeepReplace<R, Old, New>[] // Replace the type of the tuple/array
+    : T[P] extends object
+    ? DeepReplace<T[P], Old, New>
+    : Extract<T[P], Old> extends Old // Is this a union with the searched for type?
+    ?
+        | DeepReplace<Extract<T[P], object>, Old, New> // Replace all object types of the union
+        | Exclude<T[P], Old | object> // Get all types that are not objects (handled above) or Old (handled below
+        | New // Direct Replacement of Old
+    : T[P];
+};
+
+export type Navigation = DeepReplace<
+  PlayerNav,
+  Expression,
+  ExpressionTemplateInstance | ExpressionTemplateInstance[] | Expression
+>;

package/src/utils.tsx

@@ -0,0 +1,109 @@
+import React from 'react';
+import {
+  isTemplateStringInstance,
+  TemplateStringComponent,
+} from './string-templates';
+
+/** Get an array version of the value */
+export function toArray<T>(val: T | Array<T>): Array<T> {
+  return Array.isArray(val) ? val : [val];
+}
+
+/** Create a component version  */
+export function toJsonElement(value: any, index?: number): React.ReactElement {
+  const keyProp = index === undefined ? null : { key: index };
+
+  if (Array.isArray(value)) {
+    return (
+      <array {...keyProp}>
+        {value.map((item, idx) => toJsonElement(item, idx))}
+      </array>
+    );
+  }
+
+  /** Allow users to pass in BindingTemplateInstance and ExpressionTemplateInstance directly without turning them into strings first */
+  if (isTemplateStringInstance(value)) {
+    return <value {...keyProp}>{value.toRefString()}</value>;
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    return (
+      <obj {...keyProp}>
+        {Object.keys(value).map((key) => (
+          <property key={key} name={key}>
+            {toJsonElement(value[key])}
+          </property>
+        ))}
+      </obj>
+    );
+  }
+
+  return <value {...keyProp} value={value} />;
+}
+
+/** Create a fragment for the properties */
+export function toJsonProperties(value: Record<string, any>) {
+  return Object.keys(value).map((key) => (
+    <property key={key} name={key}>
+      {toJsonElement(value[key])}
+    </property>
+  ));
+}
+
+/** Create a text asset if needed */
+export function normalizeText(options: {
+  /** The current node */
+  node: React.ReactNode;
+
+  /** A component to render a text asset */
+  TextComp?: React.ComponentType;
+}): React.ReactNode {
+  const { node, TextComp } = options;
+
+  const nodeArr = React.Children.toArray(node);
+
+  if (
+    nodeArr.every(
+      (n) => React.isValidElement(n) && n.type !== TemplateStringComponent
+    )
+  ) {
+    return node;
+  }
+
+  if (TextComp) {
+    return <TextComp>{nodeArr}</TextComp>;
+  }
+
+  throw new Error(
+    `Tried to convert node to Text Asset, but no Component was supplied.`
+  );
+}
+
+/** Create a collection if needed */
+export function normalizeToCollection(options: {
+  /** the node to look at */
+  node: React.ReactNode;
+
+  /** A Text asset */
+  TextComp?: React.ComponentType;
+
+  /** A collection asset */
+  CollectionComp?: React.ComponentType;
+}) {
+  const { node, CollectionComp } = options;
+
+  if (
+    React.Children.count(node) > 1 &&
+    React.Children.toArray(node).every((n) => typeof n !== 'string')
+  ) {
+    if (!CollectionComp) {
+      throw new Error(
+        `Tried to convert array to a collection asset, but no Component was given.`
+      );
+    }
+
+    return <CollectionComp>{node}</CollectionComp>;
+  }
+
+  return normalizeText({ ...options, node });
+}