Merge pull request #304 from player-ui/docs/DSLSchemaUpdates

[Docs] Update: DSLSchema

docs/site/pages/dsl/index.mdx

@@ -158,11 +158,11 @@ const stringWithExp = `Some expr: ${myExpression}`; // 'Some expr: @[foo()]@'
 
 ### View
 
-Please refer to the [Views](./views) section for a detailed overview of how to write DSL Views
+Please refer to the [Views](../dsl/views) section for a detailed overview of how to write DSL Views
 
 ### Schema
 
-Please refer to the [Schema](./schema) section for a detailed overview of how to write DSL Schemas
+Please refer to the [Schema](../dsl/schema) section for a detailed overview of how to write DSL Schemas
 
 ## Compiling DSL Content
 

docs/site/pages/dsl/schema.mdx

@@ -194,6 +194,74 @@ and like this in the final schema:
 }
 ```
 
+# DSLSchema Type
+
+A `DSLSchema` Type is provided in order be able to customize a set of the acceptable data types and validator functions to be used for authoring the DSL data schema in your workspace. This is useful as it allows content authors to get realtime feedback on their data schema. It can catch any structural issues that may produce an invalid schema at compile time or produce a schema that uses functionality thats not available at runtime.
+
+We'll start out by importing the `DSLSchema` type and the relevant helper types and utilities from `@player-tools/dsl`. For this example we are importing the `common-types-plugin` in order to use its data types and validators. Our first step would be to generate the data type object types and references:
+
+```typescript
+import { 
+  DSLSchema,
+  DataTypeReference 
+  DataTypeRefs,
+  ValidatorFunctionRefs,
+  getObjectReferences
+} from "@player-tools/dsl"
+import {
+  dataTypes as commonDataTypes,
+  validators as commonValidators
+} from "@player-ui/common-types-plugin";
+
+/** Abstracting the types from commonDataTypes to be passed as generic to the DataTypeRefs type for dynamically generating the data type reference Types */
+type myCommonDataTypesRefs = DataTypeRefs<typeof commonDataTypes>
+
+/** Using getObjectReferences helper to generate the actual data type references to be used in your schema by passing inferred types from commonDataTypes and myCommonDataTypesRefs */
+export const dataRefs = getObjectReferences<typeof commonDataTypes, myCommonDataTypesRefs>(
+  coreDataSet
+);
+```
+
+We'll proceed generating the validation function types:
+
+```typescript
+/** Abstracting types from coreValidators and using as generic of ValidatorFunctionRefs for dynamically generating the data validation function reference Types */
+type commonValidatorRefs = ValidatorFunctionRefs<typeof commonValidators>
+```
+
+The final step is to provide the data Types set and validator function reference Types as generics for the `DataTypeReference` type which is the sole generic type we pass into the `DSLSchema` instance:
+```typescript
+type CommonDSLSchema = DSLSchema<
+  DataTypeReference<typeof commonDataTypes, commonValidatorRefs>
+>
+```
+
+Finally, this is how to use the custom schema type to type check your schema. By adding the `satisfies` keyword followed by your `DSLSchema` generated type, your editor's LSP will show if there is anything not compliant with the data types and validation functions we defined in the schema:
+
+```typescript
+import { CommonDSLSchema, dataRefs } from "./MyTypes"
+
+const { BooleanTypeRef } = dataRefs
+
+const exampleSchema = {
+  myDataSet = {
+    /** Simply using the BooleanTypeReference to define "firstPath" type to Boolean */
+    firstPath: BooleanTypeRef
+    secondPath: {
+      /** For adding custom validation for "secondPath", we pass an object definition with the data "type" property, which is "TextType" for this example */
+      type: "TextType",
+      /**  In the validation array open another object definition specifying the use of the "required" validator with the "type" property, with a custom "message" value */
+      validation: [
+        {
+          type: "required",
+          message: "This field is required"
+        }
+      ]
+    }
+  }
+} satisfies CommonDSLSchema
+```
+
 # Using the Schema Object in JSX/TSX Content
 
 As the schema is now a TypeScript obejct, you can now directly reference the schema anywhere in content. The `makeBindingsForObject()` function takes your schema object and constructs the bindings opaquely within the object. This allows the use of the native path in your authored content and for the actual underlying binding to be used when the content is compiled. Additionally, as the underlying bindings are exposed, can you can use the native object path with functions like `.toString()`, `.toValue()`, and `toRefString()` like you could with regular string template bindings.
@@ -229,4 +297,4 @@ export default {
 
 ## Format
 
-## Ease of Use
+## Ease of Use