@player-tools/dsl 0.5.0--canary.62.1176 → 0.5.0-next.0

package/types/auto-id.d.ts

@@ -0,0 +1,33 @@
+import React from "react";
+import type { JsonNode } from "react-json-reconciler";
+import type { WithChildren } from "./types";
+export declare const IndexSuffixStopContext: React.Context<boolean>;
+/** Get the generated id */
+export declare const useGetIdPrefix: () => string;
+/** Add a suffix to a generated id */
+export declare const IDSuffixProvider: (props: WithChildren<{
+    /** The suffix to append */
+    suffix: string;
+}>) => React.JSX.Element;
+/** Override the generated id with the supplied one */
+export declare const IDProvider: (props: WithChildren<{
+    /** The new id to use  */
+    id?: string;
+}>) => React.JSX.Element;
+/** Get the index of an item in a slot */
+export declare const useIndexInSlot: (ref: React.RefObject<JsonNode>) => number;
+/** Add the index to the id path when in an array slot */
+export declare const IDSuffixIndexProvider: (props: WithChildren<{
+    /** The ref to use */
+    wrapperRef: React.RefObject<JsonNode>;
+    /** if the suffix is in a template, the id to use */
+    templateIndex?: string;
+}>) => React.JSX.Element;
+/** Wrap a slot with the index if in an array slot */
+export declare const OptionalIDSuffixProvider: (props: WithChildren<{
+    /** The ref to walk upwards and use as an index */
+    wrapperRef: React.RefObject<JsonNode>;
+    /** if the suffix is in a template, the id to use */
+    templateIndex?: string;
+}>) => React.JSX.Element;
+//# sourceMappingURL=auto-id.d.ts.map

package/types/compiler/compiler.d.ts

@@ -0,0 +1,27 @@
+import type { Flow } from "@player-ui/types";
+import { AsyncSeriesHook, AsyncSeriesWaterfallHook, SyncHook } from "tapable-ts";
+import type { LoggingInterface, CompilerReturn, SerializeContext } from "./types";
+import { SchemaGenerator } from "./schema";
+/**
+ * Argument passed to the DSLCompiler onEnd hook
+ * Defined as an object so additional fields can be added later without breaking API
+ * */
+export interface OnEndArg {
+    /** target output directory **/
+    output: string;
+}
+/** A compiler for transforming DSL content into JSON */
+export declare class DSLCompiler {
+    readonly logger: LoggingInterface;
+    hooks: {
+        schemaGenerator: SyncHook<[SchemaGenerator], Record<string, any>>;
+        preProcessFlow: AsyncSeriesWaterfallHook<[object], Record<string, any>>;
+        postProcessFlow: AsyncSeriesWaterfallHook<[Flow<import("@player-ui/types").Asset<string>>], Record<string, any>>;
+        onEnd: AsyncSeriesHook<[OnEndArg], Record<string, any>>;
+    };
+    private schemaGenerator?;
+    constructor(logger?: LoggingInterface);
+    /** Convert an object (flow, view, schema, etc) into it's JSON representation */
+    serialize(value: unknown, context?: SerializeContext): Promise<CompilerReturn>;
+}
+//# sourceMappingURL=compiler.d.ts.map

package/types/compiler/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./compiler";
+export * from "./types";
+export * from "./utils";
+//# sourceMappingURL=index.d.ts.map

package/types/compiler/schema.d.ts

@@ -0,0 +1,61 @@
+import type { Schema } from "@player-ui/types";
+import { SyncWaterfallHook } from "tapable-ts";
+import type { LoggingInterface } from "..";
+import type { BindingTemplateInstance } from "../string-templates";
+/** Symbol to indicate that a schema node should be generated with a different name */
+export declare const SchemaTypeName: unique symbol;
+/**
+ * Generator for `Schema.Schema` Objects
+ */
+export declare class SchemaGenerator {
+    private children;
+    private generatedDataTypes;
+    private logger;
+    hooks: {
+        createSchemaNode: SyncWaterfallHook<[node: Schema.DataType<unknown>, originalProperty: Record<string | symbol, unknown>], Record<string, any>>;
+    };
+    constructor(logger?: LoggingInterface);
+    /**
+     * Converts an object to a `Schema.Schema` representation
+     * Note: uses iteration to prevent potentially very deep recursion on large objects
+     */
+    toSchema: (schema: any) => Schema.Schema;
+    /**
+     * Processes the children of an object Node
+     * Newly discovered children get added to the provided array
+     */
+    private processChild;
+    /**
+     * Make an intermediate `Schema.DataType` object given a name
+     */
+    private makePlaceholderType;
+    /**
+     * Make an intermediate `Schema.DataType` object with array support given a name
+     */
+    private makePlaceholderArrayType;
+}
+export type MakeArrayIntoIndexRef<T extends any[]> = {
+    [key: number]: MakeBindingRefable<T[0]>;
+    /** Used when referencing bindings from within a template */
+    _index_: MakeBindingRefable<T[0]>;
+} & BindingTemplateInstance;
+export type MakeBindingRefable<T> = {
+    [P in keyof T]: T[P] extends object[] ? MakeArrayIntoIndexRef<T[P]> : T[P] extends unknown[] ? T[P] : MakeBindingRefable<T[P]>;
+} & BindingTemplateInstance;
+/**
+ * Adds bindings to an object so that the object can be directly used in JSX
+ */
+export declare function makeBindingsForObject<Type>(obj: Type, arrayAccessorKeys?: string[]): MakeBindingRefable<Type>;
+/**
+ * Generates binding for an object property
+ */
+export declare const getBindingFromObject: (obj: any) => BindingTemplateInstance;
+/**
+ * Returns the binding string from an object path
+ */
+export declare const getBindingStringFromObject: (obj: any) => string;
+/**
+ * Returns the ref string from an object path
+ */
+export declare const getRefStringFromObject: (obj: any) => string;
+//# sourceMappingURL=schema.d.ts.map

package/types/compiler/types.d.ts

@@ -0,0 +1,55 @@
+/// <reference types="react" />
+import type { Schema, Navigation, Flow, Expression, ExpressionObject, NavigationFlow, NavigationFlowState, NavigationFlowViewState } from "@player-ui/types";
+import type { JsonType } from "react-json-reconciler";
+import type { RemoveUnknownIndex, AddUnknownIndex } from "../types";
+export type NavigationFlowReactViewState = Omit<NavigationFlowViewState, "ref"> & {
+    /** The view element */
+    ref: React.ReactElement | string;
+};
+export type NavFlowState = Exclude<NavigationFlowState, NavigationFlowViewState> | NavigationFlowReactViewState;
+export type NavigationFlowWithReactView = Pick<NavigationFlow, "startState" | "onStart" | "onEnd"> & {
+    [key: string]: undefined | string | Expression | ExpressionObject | NavFlowState;
+};
+export type NavigationWithReactViews = Pick<Navigation, "BEGIN"> & Record<string, string | NavigationFlowWithReactView>;
+export type FlowWithoutUnknown = RemoveUnknownIndex<Flow>;
+export type FlowWithReactViews = AddUnknownIndex<Omit<FlowWithoutUnknown, "views" | "navigation"> & {
+    /** An array of JSX view elements */
+    views?: Array<React.ReactElement>;
+    /** The navigation element */
+    navigation?: NavigationWithReactViews;
+}>;
+export type DSLFlow = Omit<FlowWithReactViews, "schema"> & {
+    /** A DSL compliant schema */
+    schema?: DSLSchema;
+};
+export interface DSLSchema {
+    [key: string]: Schema.DataType | DSLSchema;
+}
+export type SerializeType = "view" | "flow" | "schema" | "navigation";
+export type SerializablePlayerExportTypes = React.ReactElement | FlowWithReactViews | Schema.Schema | Navigation;
+export type LoggingInterface = Pick<Console, "warn" | "error" | "log">;
+export type CompilationResult = {
+    /** What type of file is generated */
+    contentType: string;
+    /** The output path */
+    outputFile: string;
+    /** the input file */
+    inputFile: string;
+};
+export type CompilerReturn = {
+    /** the JSON value of the source */
+    value: JsonType | undefined;
+    /** The sourcemap of the content */
+    sourceMap?: string;
+};
+/** The different type of default content items the compiler handles */
+declare const DefaultCompilerContentTypes: readonly ["view", "flow", "schema"];
+export type DefaultCompilerContentType = (typeof DefaultCompilerContentTypes)[number];
+/** Helper function to determine whether a content type is compiler default */
+export declare function isDefaultCompilerContentType(t: string): t is DefaultCompilerContentType;
+export interface SerializeContext {
+    /** The type of the content being compiled */
+    type: DefaultCompilerContentType;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/types/compiler/utils.d.ts

@@ -0,0 +1,4 @@
+import type { DefaultCompilerContentType } from "./types";
+/** Basic way of identifying the type of file based on the default content export */
+export declare const fingerprintContent: (content: unknown, filename?: string) => DefaultCompilerContentType | undefined;
+//# sourceMappingURL=utils.d.ts.map

package/types/components.d.ts

@@ -0,0 +1,90 @@
+import React from "react";
+import type { ObjectNode, PropertyNode } from "react-json-reconciler";
+import type { PlayerApplicability, WithChildren } from "./types";
+export type AssetProps = PlayerApplicability & {
+    /** 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;
+};
+export declare const SlotContext: React.Context<{
+    /** 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<{}> | undefined;
+    /** 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 declare const AssetWrapper: React.ForwardRefExoticComponent<Omit<WithChildren<{
+    [key: string]: unknown;
+}>, "ref"> & React.RefAttributes<ObjectNode>>;
+/** Create a ID property for a node */
+export declare const GeneratedIDProperty: (props: {
+    /** the id to use if supplied by the user */
+    id?: string;
+}) => React.JSX.Element;
+/** An asset */
+export declare const Asset: React.ForwardRefExoticComponent<Omit<AssetProps, "ref"> & React.RefAttributes<ObjectNode>>;
+export declare const View: React.ForwardRefExoticComponent<Omit<PlayerApplicability & {
+    [key: string]: unknown;
+    /** id of the asset */
+    id?: string | undefined;
+    /** the asset type */
+    type: string;
+    /** Any other properties on the asset */
+    children?: React.ReactNode;
+} & import("@player-ui/types").Asset<string> & {
+    validation?: import("@player-ui/types").Validation.CrossfieldReference[] | undefined;
+}, "ref"> & React.RefAttributes<ObjectNode>>;
+/** A component to generate a named property slot */
+export declare 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;
+}) => React.JSX.Element;
+/** Create a slot for a given property */
+export declare 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;
+}): (props: {
+    /** An object to include in this property */
+    children?: React.ReactNode;
+} & SlotProps) => React.JSX.Element;
+//# sourceMappingURL=components.d.ts.map

package/types/index.d.ts

@@ -0,0 +1,12 @@
+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";
+export * from "./compiler/types";
+//# sourceMappingURL=index.d.ts.map

package/types/string-templates/index.d.ts

@@ -0,0 +1,50 @@
+import * as 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: ReadonlyArray<string>;
+    /** 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;
+}
+declare const OpaqueIdentifier: unique symbol;
+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 declare const TemplateStringComponent: (props: {
+    /** The string value of the child template string */
+    value: string;
+}) => React.ReactElement<{
+    value: string;
+}, string | React.JSXElementConstructor<any>>;
+/** A tagged-template constructor for a binding  */
+export declare const binding: (strings: TemplateStringsArray, ...nested: Array<TemplateStringType | string>) => BindingTemplateInstance;
+/** A tagged-template constructor for an expression */
+export declare const expression: (strings: TemplateStringsArray, ...nested: Array<ExpressionTemplateInstance | BindingTemplateInstance | string>) => ExpressionTemplateInstance;
+/** Check if a value is a template string */
+export declare const isTemplateStringInstance: (val: unknown) => val is BindingTemplateInstance | ExpressionTemplateInstance;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/types/switch.d.ts

@@ -0,0 +1,19 @@
+import type { PropsWithChildren } from "react";
+import React from "react";
+import type { BindingTemplateInstance, ExpressionTemplateInstance } from "./string-templates";
+export interface SwitchProps {
+    /** defaults to a staticSwitch */
+    isDynamic?: boolean;
+}
+/**
+ * Switches allow users to fork content between 1 or more assets
+ */
+export declare const Switch: {
+    (props: PropsWithChildren<SwitchProps>): React.JSX.Element;
+    Case: (props: PropsWithChildren<CaseProps>) => React.JSX.Element;
+};
+export interface CaseProps {
+    /** the test for this case statement */
+    exp?: ExpressionTemplateInstance | BindingTemplateInstance | boolean;
+}
+//# sourceMappingURL=switch.d.ts.map

package/types/template.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+import type { BindingTemplateInstance } from "./string-templates";
+export interface TemplateContextType {
+    /** The number of nested templates */
+    depth: number;
+}
+export declare const TemplateContext: React.Context<TemplateContextType>;
+export interface TemplateProps {
+    /** The source binding */
+    data: BindingTemplateInstance;
+    /** The target property */
+    output?: string;
+    /** The template value */
+    children: React.ReactNode;
+    /** boolean that specifies whether template should recompute when data changes */
+    dynamic?: boolean;
+}
+/** A template allows users to dynamically map over an array of data */
+export declare const Template: (props: TemplateProps) => React.JSX.Element;
+//# sourceMappingURL=template.d.ts.map

package/types/types.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="react" />
+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> : T[P] extends (infer R)[] ? DeepReplace<R, Old, New>[] : T[P] extends object ? DeepReplace<T[P], Old, New> : Extract<T[P], Old> extends Old ? DeepReplace<Extract<T[P], object>, Old, New> | Exclude<T[P], Old | object> | New : T[P];
+};
+export type Navigation = DeepReplace<PlayerNav, Expression, ExpressionTemplateInstance | ExpressionTemplateInstance[] | Expression>;
+export interface toJsonOptions {
+    /**
+     * List of string keys that should not be parsed in a special way
+     * default is "applicability"
+     */
+    propertiesToSkip?: string[];
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/types/utils.d.ts

@@ -0,0 +1,33 @@
+import * as React from "react";
+import type { toJsonOptions } from "./types";
+/** Get an array version of the value */
+export declare function toArray<T>(val: T | Array<T>): Array<T>;
+/** Create a component version  */
+export declare function toJsonElement(value: any, indexOrKey?: number | string, options?: toJsonOptions): React.ReactElement;
+/** Create a fragment for the properties */
+export declare function toJsonProperties(value: Record<string, any>, options?: toJsonOptions): React.JSX.Element[];
+/** Create a text asset if needed */
+export declare function normalizeText(options: {
+    /** The current node */
+    node: React.ReactNode;
+    /** A component to render a text asset */
+    TextComp?: React.ComponentType<any>;
+}): React.ReactNode;
+/** Create a collection if needed */
+export declare function normalizeToCollection(options: {
+    /** the node to look at */
+    node: React.ReactNode;
+    /** A Text asset */
+    TextComp?: React.ComponentType;
+    /** A collection asset */
+    CollectionComp?: React.ComponentType<any>;
+}): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
+type ReactChildArray = ReturnType<typeof React.Children.toArray>;
+/**
+ *
+ * Hoisted from https://github.com/gregberge/react-flatten-children/blob/master/src/index.tsx
+ * Peer dependencies were wrong and can't be reasonably patch it everywhere
+ */
+export declare function flattenChildren(children: React.ReactNode): ReactChildArray;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/README.md

@@ -1,9 +0,0 @@
-# DSL
-
-The `@player-ui/dsl` package provides the primitives and build tools to create Player Asset Component libraries, and statically generate Player JSON content using TSX.
-
-## Asset Component Libraries
-
-Similar to React, Vue, or other component libraries, in order for users to take advantage of the JSX capabilities, they need a library of common components to pull from.
-
-As an asset author, you can create and share a library of `Components` for content authors to import and leverage.