@player-tools/dsl 0.0.2-next.0

package/src/components.tsx

@@ -0,0 +1,234 @@
+import React from 'react';
+import flattenChildren from 'react-flatten-children';
+import type { ObjectNode, PropertyNode } from 'react-json-reconciler';
+import mergeRefs from 'react-merge-refs';
+import type { PlayerApplicability, WithChildren } from './types';
+import {
+  IDProvider,
+  IDSuffixProvider,
+  IndexSuffixStopContext,
+  OptionalIDSuffixProvider,
+  useGetIdPrefix,
+} from './auto-id';
+import {
+  normalizeText,
+  normalizeToCollection,
+  toJsonProperties,
+} from './utils';
+
+export const SlotContext = React.createContext<
+  | {
+      /** The property name for the slot */
+      propertyName: string;
+      /** If the slot represents an array */
+      isArray: boolean;
+      /** If the items in the slot should be wrapped in an "asset" object */
+      wrapInAsset: boolean;
+      /** Other props to add to the slot */
+      additionalProperties?: any;
+      /** The ref to the property node */
+      ref: React.RefObject<PropertyNode>;
+      /** A text component if we hit a string but expect an asset */
+      TextComp?: React.ComponentType;
+      /** A component to create a collection asset is we get an array but need a single element */
+      CollectionComp?: React.ComponentType;
+    }
+  | undefined
+>(undefined);
+
+/**
+ * Wraps the children in an `asset` object.
+ * Additional props are added to the top level object
+ */
+export const AssetWrapper = React.forwardRef<
+  ObjectNode,
+  WithChildren<{ [key: string]: any }>
+>((props, ref) => {
+  const { children, ...rest } = props;
+
+  return (
+    <obj ref={ref}>
+      {toJsonProperties(rest)}
+      <property name="asset">{children}</property>
+    </obj>
+  );
+});
+
+/** Create a ID property for a node */
+export const GeneratedIDProperty = (props: {
+  /** the id to use if supplied by the user */
+  id?: string;
+}) => {
+  const currentPrefixId = useGetIdPrefix();
+  return <property name="id">{props.id ?? currentPrefixId}</property>;
+};
+
+/** An asset */
+export const Asset = React.forwardRef<
+  ObjectNode,
+  {
+    /** id of the asset */
+    id?: string;
+
+    /** the asset type */
+    type: string;
+
+    /** Any other properties on the asset */
+    children?: React.ReactNode;
+
+    /** other things that we don't know about */
+    [key: string]: unknown;
+  } & PlayerApplicability
+>((props, ref) => {
+  const { id, type, applicability, children, ...rest } = props;
+  const slotContext = React.useContext(SlotContext);
+  const localRef = React.useRef<ObjectNode>(null);
+  const Wrapper = slotContext?.wrapInAsset ? AssetWrapper : React.Fragment;
+
+  return (
+    <Wrapper
+      ref={slotContext?.wrapInAsset ? mergeRefs([ref, localRef]) : undefined}
+      {...(slotContext?.wrapInAsset && slotContext?.additionalProperties
+        ? slotContext?.additionalProperties
+        : {})}
+    >
+      <OptionalIDSuffixProvider wrapperRef={localRef}>
+        <SlotContext.Provider value={undefined}>
+          <IDProvider id={id}>
+            <obj
+              ref={
+                slotContext?.wrapInAsset
+                  ? undefined
+                  : mergeRefs([ref, localRef])
+              }
+            >
+              <GeneratedIDProperty id={id} />
+              <property name="type">{type}</property>
+              {applicability !== undefined && (
+                <property name="applicability">
+                  <value
+                    value={
+                      typeof applicability === 'boolean'
+                        ? applicability
+                        : applicability.toRefString()
+                    }
+                  />
+                </property>
+              )}
+              {toJsonProperties(rest)}
+              {children}
+            </obj>
+          </IDProvider>
+        </SlotContext.Provider>
+      </OptionalIDSuffixProvider>
+    </Wrapper>
+  );
+});
+
+Asset.defaultProps = {
+  id: undefined,
+  children: undefined,
+};
+
+/** A component to generate a named property slot */
+export const Slot = (props: {
+  /** The name of the slot */
+  name: string;
+
+  /** if the slot is an array or single object */
+  isArray?: boolean;
+
+  /** if each item should be wrapped in an asset */
+  wrapInAsset?: boolean;
+
+  /** Any children to render in the slot */
+  children?: React.ReactNode;
+
+  /** Other properties to add to the slot */
+  additionalProperties?: any;
+
+  /** A text component if we hit a string but expect an asset */
+  TextComp?: React.ComponentType;
+
+  /** A component to create a collection asset is we get an array but need a single element */
+  CollectionComp?: React.ComponentType;
+}) => {
+  const { TextComp, CollectionComp } = props;
+  const children = flattenChildren(props.children);
+  const propRef = React.useRef<PropertyNode>(null);
+
+  return (
+    <property ref={propRef} name={props.name}>
+      <IDSuffixProvider suffix={props.name}>
+        <IndexSuffixStopContext.Provider value={false}>
+          <SlotContext.Provider
+            value={{
+              ref: propRef,
+              propertyName: props.name,
+              wrapInAsset: props.wrapInAsset ?? false,
+              isArray: props.isArray ?? false,
+              additionalProperties: props.additionalProperties,
+              TextComp,
+              CollectionComp,
+            }}
+          >
+            {props.isArray && (
+              <array>
+                {React.Children.map(children, (child, index) => {
+                  return (
+                    // eslint-disable-next-line react/no-array-index-key
+                    <React.Fragment key={`${props.name}-${index}`}>
+                      {normalizeText({ node: child, TextComp })}
+                    </React.Fragment>
+                  );
+                })}
+              </array>
+            )}
+
+            {!props.isArray &&
+              normalizeToCollection({
+                node: children,
+                TextComp,
+                CollectionComp,
+              })}
+          </SlotContext.Provider>
+        </IndexSuffixStopContext.Provider>
+      </IDSuffixProvider>
+    </property>
+  );
+};
+
+/** Create a slot for a given property */
+export function createSlot<SlotProps = unknown>(options: {
+  /** The name of the slot */
+  name: string;
+
+  /** if the slot is an array or single object */
+  isArray?: boolean;
+
+  /** if each item should be wrapped in an asset */
+  wrapInAsset?: boolean;
+
+  /** Any children to render in the slot */
+  children?: React.ReactNode;
+
+  /** A text component if we hit a string but expect an asset */
+  TextComp?: React.ComponentType;
+
+  /** A component to create a collection asset is we get an array but need a single element */
+  CollectionComp?: React.ComponentType;
+}) {
+  return (
+    props: {
+      /** An object to include in this property */
+      children?: React.ReactNode;
+    } & SlotProps
+  ) => {
+    const { children, ...other } = props;
+    return (
+      <Slot {...options} additionalProperties={other}>
+        {children}
+      </Slot>
+    );
+  };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './components';
+export * from './auto-id';
+export * from './types';
+export * from './string-templates';
+export * from './utils';
+export * from './switch';
+export * from './template';
+export * from 'react-json-reconciler';
+export * from './compiler/schema';
+export * from './compiler';

package/src/string-templates/index.ts

@@ -0,0 +1,172 @@
+import React from 'react';
+
+export type TemplateInstanceRefStringContext = 'binding' | 'expression';
+export interface TemplateRefStringOptions {
+  /** If this template string is inside of another binding or expression */
+  nestedContext?: TemplateInstanceRefStringContext;
+}
+export interface TemplateInstanceRefStringOptions {
+  /** The array of strings for the template */
+  strings: TemplateStringsArray;
+  /** the other data that's present in the template */
+  other: Array<string | TemplateStringType>;
+
+  /** If this template string is inside of another binding or expression */
+  nestedContext?: TemplateInstanceRefStringContext;
+
+  /** Convert the value to a reference nested in the given context */
+  toRefString: (
+    options: TemplateRefStringOptions | undefined,
+    value: string
+  ) => string;
+}
+
+const OpaqueIdentifier = Symbol('TemplateStringType');
+
+export type TemplateStringType = React.ReactElement & {
+  /** An identifier to show that this is a template type */
+  [OpaqueIdentifier]: true;
+  /** The value of the template string when in another string */
+  toString: () => string;
+  /** the raw value of the template string */
+  toValue: () => string;
+  /** the dereferenced value when used in another */
+  toRefString: (options?: TemplateRefStringOptions) => string;
+};
+
+export type BindingTemplateInstance = TemplateStringType & {
+  /** An identifier for a binding instance */
+  __type: 'binding';
+};
+
+export type ExpressionTemplateInstance = TemplateStringType & {
+  /** The identifier for an expression instance */
+  __type: 'expression';
+};
+
+/** A react component for rendering a template string type */
+export const TemplateStringComponent = (props: {
+  /** The string value of the child template string */
+  value: string;
+}) => {
+  return React.createElement(
+    'value',
+    {
+      value: props.value,
+    },
+    null
+  );
+};
+
+/** The generic template string handler */
+const createTemplateInstance = (
+  options: TemplateInstanceRefStringOptions
+): TemplateStringType => {
+  const value = options.strings.reduce((sum, next, i) => {
+    const element = options.other[i];
+    if (typeof element === 'string') {
+      return sum + next + element;
+    }
+
+    return sum + next + (element?.toRefString(options) ?? '');
+  }, '');
+
+  /** get the unwrapped version */
+  const toString = () => {
+    return options.toRefString({}, value);
+  };
+
+  /** get the raw value of the template */
+  const toValue = () => {
+    return value;
+  };
+
+  /** This lets us use it directly as a child element in React */
+  const element = React.createElement(
+    TemplateStringComponent,
+    {
+      value: toString(),
+    },
+    null
+  ) as TemplateStringType;
+
+  return {
+    ...element,
+    [OpaqueIdentifier]: true,
+    toString,
+    toValue,
+    toRefString: (refStringOptions?: TemplateRefStringOptions) => {
+      return options.toRefString(refStringOptions, value);
+    },
+  };
+};
+
+/** Creating an instance of a handler for bindings */
+const createBindingTemplateInstance = (
+  options: Omit<TemplateInstanceRefStringOptions, 'toRefString'>
+): BindingTemplateInstance => {
+  const templateInstance = createTemplateInstance({
+    ...options,
+    toRefString: (context, value) => {
+      return `{{${value}}}`;
+    },
+  }) as BindingTemplateInstance;
+
+  templateInstance.__type = 'binding';
+
+  return templateInstance;
+};
+
+/** Creating an instance of a handler for bindings */
+const createExpressionTemplateInstance = (
+  options: Omit<TemplateInstanceRefStringOptions, 'toRefString'>
+) => {
+  const templateInstance = createTemplateInstance({
+    ...options,
+    toRefString: (contextOptions, value) => {
+      if (contextOptions?.nestedContext === 'expression') {
+        return value;
+      }
+
+      const inBinding = contextOptions?.nestedContext === 'binding';
+      return `${inBinding ? '`' : '@['}${value}${inBinding ? '`' : ']@'}`;
+    },
+  }) as ExpressionTemplateInstance;
+
+  templateInstance.__type = 'expression';
+
+  return templateInstance;
+};
+
+/** A tagged-template constructor for a binding  */
+export const binding = (
+  strings: TemplateStringsArray,
+  ...nested: Array<TemplateStringType | string>
+): BindingTemplateInstance => {
+  return createBindingTemplateInstance({
+    strings,
+    other: nested,
+    nestedContext: 'binding',
+  });
+};
+
+/** A tagged-template constructor for an expression */
+export const expression = (
+  strings: TemplateStringsArray,
+  ...nested: Array<
+    ExpressionTemplateInstance | BindingTemplateInstance | string
+  >
+): ExpressionTemplateInstance => {
+  return createExpressionTemplateInstance({
+    strings,
+    other: nested,
+    nestedContext: 'expression',
+  });
+};
+
+/** Check if a value is a template string */
+export const isTemplateStringInstance = (
+  val: unknown
+): val is ExpressionTemplateInstance | BindingTemplateInstance => {
+  return typeof val === 'object' && (val as any)[OpaqueIdentifier] === true;
+};

package/src/switch.tsx

@@ -0,0 +1,136 @@
+import type { PropsWithChildren } from 'react';
+import React from 'react';
+import type { ArrayNode, JsonNode, ObjectNode } from 'react-json-reconciler';
+import { flattenNodes, PropertyNode } from 'react-json-reconciler';
+import { SlotContext } from '.';
+import { IDSuffixProvider, OptionalIDSuffixProvider } from './auto-id';
+import type {
+  BindingTemplateInstance,
+  ExpressionTemplateInstance,
+} from './string-templates';
+import { isTemplateStringInstance } from './string-templates';
+import { normalizeToCollection, toJsonProperties } from './utils';
+
+export interface SwitchProps {
+  /** defaults to a staticSwitch */
+  isDynamic?: boolean;
+}
+
+const SwitchContext = React.createContext<
+  SwitchProps & {
+    /** A text component if we hit a string but expect an asset */
+    TextComp?: React.ComponentType;
+
+    /** A component to create a collection asset is we get an array but need a single element */
+    CollectionComp?: React.ComponentType;
+  }
+>({});
+
+/**
+ * Switches allow users to fork content between 1 or more assets
+ */
+export const Switch = (props: PropsWithChildren<SwitchProps>) => {
+  const slotContext = React.useContext(SlotContext);
+  const propertyNode = React.useRef<ObjectNode>(null);
+
+  return (
+    <obj ref={propertyNode}>
+      <SwitchContext.Provider
+        value={{
+          ...props,
+          TextComp: slotContext?.TextComp,
+          CollectionComp: slotContext?.CollectionComp,
+        }}
+      >
+        <OptionalIDSuffixProvider wrapperRef={propertyNode}>
+          <property name={props.isDynamic ? 'dynamicSwitch' : 'staticSwitch'}>
+            <SlotContext.Provider value={undefined}>
+              <array>{props.children}</array>
+            </SlotContext.Provider>
+          </property>
+        </OptionalIDSuffixProvider>
+      </SwitchContext.Provider>
+      {slotContext?.additionalProperties &&
+        toJsonProperties(slotContext.additionalProperties)}
+    </obj>
+  );
+};
+
+export interface CaseProps {
+  /** the test for this case statement */
+  exp?: ExpressionTemplateInstance | BindingTemplateInstance | boolean;
+}
+
+/** Find the first parent array */
+const findParentArray = (node: JsonNode): ArrayNode => {
+  if (node.type === 'array') {
+    return node;
+  }
+
+  if (node.parent) {
+    return findParentArray(node.parent);
+  }
+
+  throw new Error("can't find parent array");
+};
+
+/** Find the index of the item in an array */
+const findArrayIndex = (node: JsonNode): number => {
+  const parentArray = findParentArray(node);
+  const allSearch = flattenNodes(parentArray.children);
+  return allSearch.indexOf(node);
+};
+
+/** A case for a switch */
+const Case = (props: PropsWithChildren<CaseProps>) => {
+  const slotContext = React.useContext(SlotContext);
+  const switchContext = React.useContext(SwitchContext);
+  const [caseIndex, setCaseIndex] = React.useState(-1);
+  const caseNode = React.useRef<ObjectNode>(null);
+
+  React.useLayoutEffect(() => {
+    if (caseNode.current) {
+      const index = findArrayIndex(caseNode.current);
+      if (index !== caseIndex) {
+        setCaseIndex(index);
+      }
+    }
+  }, [caseIndex]);
+
+  let expValue: string | boolean = true;
+
+  if (props.exp !== undefined) {
+    expValue = isTemplateStringInstance(props.exp)
+      ? props.exp.toValue()
+      : props.exp;
+  }
+
+  return (
+    <obj ref={caseNode}>
+      <property name="case">
+        <value value={expValue} />
+      </property>
+      <IDSuffixProvider
+        suffix={`${
+          switchContext.isDynamic ? 'dynamicSwitch' : 'staticSwitch'
+        }-${caseIndex}`}
+      >
+        <SlotContext.Provider
+          value={
+            slotContext ? { ...slotContext, wrapInAsset: false } : undefined
+          }
+        >
+          <property name="asset">
+            {normalizeToCollection({
+              node: props.children,
+              TextComp: switchContext?.TextComp,
+              CollectionComp: switchContext?.CollectionComp,
+            })}
+          </property>
+        </SlotContext.Provider>
+      </IDSuffixProvider>
+    </obj>
+  );
+};
+
+Switch.Case = Case;