Feature: Emitted Events from Actionable Components; Extended Types and Interfaces of the Component Configuration

Author: plc-dev

src/Util/Util.ts

@@ -12,3 +12,10 @@ export type KeyOfType<T, KeyType extends string | number | symbol = KeyTypes<T>>
   keyof T,
   KeyType
 >;
+
+export type TypeOfLastTupleElement<T extends any[]> = T extends [...any[], infer R] ? R : never;
+
+export type ValueOf<T> = T[keyof T];
+
+// https://stackoverflow.com/a/75088992/14804461
+export type StringLiteralList<T, K extends keyof T> = T[keyof Pick<T, K>];

src/components/BaseComponent/BaseComponent.ts

@@ -1,7 +1,8 @@
 import type { StoreAPI, JSONPathExpression } from "@/stores/Store";
 import { ensurePathExists } from "@/stores/Store";
 import { unref, computed, ref } from "vue";
-import type { Ref, ComputedRef, StyleValue } from "vue";
+import type { Ref, ComputedRef, StyleValue, EmitFn } from "vue";
+import type { TypeOfLastTupleElement } from "@/Util/Util";
 
 /**
  * A description of a user-facing method of a component.
@@ -56,11 +57,34 @@ export interface ComponentProps {
   style?: StyleValue;
 }
 
+/**
+ * Base-type of a private emitted event of a component. Private events are meant to be consumed only by other components.
+ */
+export type PrivateComponentEmit = [];
+
+/**
+ * The payload of an public action-event.
+ */
+export interface ActionPayload {}
+
+/**
+ * Base-type of a public emitted event of a component.
+ * Public events are meant to be consumed by the execution engine that executes the component.
+ */
+export type PublicComponentEmit = [type: string, action: string, payload: ActionPayload] &
+  PrivateComponentEmit;
+
 /**
  * Eventual emitted events of a component. Parent components can listen to these events.
- * Especially useful when nesting components.
+ *
+ * These should be consumed by the execution engine for the individual components.
+ *
+ * Also useful when nesting components.
  */
-export type ComponentEmits = Record<string, any[]>;
+export interface ComponentEmits {
+  [key: string]: PrivateComponentEmit;
+}
+// Record<string, PrivateComponentEmit>;
 
 /**
  * The type of a component.
@@ -86,6 +110,20 @@ export type SerialisedContextMenu = {
  */
 export type ValidationConfiguration = {};
 
+/**
+ * There may be multiple validation strategies for a component.
+ * It is advised to utilize the ValidationStrategy-interface and its type property to distinguish between different strategies.
+ */
+export interface ValidationStrategy extends ValidationConfiguration {
+  type: string;
+}
+
+/**
+ * If multiple strategies are used, the strategies are to be acessed via the InputFieldValidationConfigurationMap-type.
+ */
+// export type ValidationConfigurationMap = Record<string, ValidationStrategy>;
+export interface ValidationConfigurationMap {}
+
 /**
  * Serialised dependencies of a component.
  */
@@ -136,6 +174,28 @@ export type ComponentState = {
   isCorrect: boolean;
 };
 
+/**
+ * The serialized configuration of a component action.
+ */
+export interface ComponentAction {
+  type: string;
+  action: string;
+}
+
+/**
+ * The fetch action is a special action that is used to fetch data from an external source.
+ */
+export interface FetchAction extends ComponentAction {
+  type: "fetch";
+}
+
+/**
+ * The serialized configuration for the actions of a component.
+ */
+export interface ComponentActions {
+  [key: string]: ComponentAction;
+}
+
 /**
  * Generic type description with defaults of a serialised base component.
  */
@@ -176,6 +236,10 @@ export interface SerializedBaseComponent<T extends BaseComponentType = BaseCompo
    * Optional: Nested components of the component.
    */
   nestedComponents?: NestedComponents;
+  /**
+   * Optional: Actions that can be emitted by the component.
+   */
+  actions?: ComponentActions;
 }
 
 /**
@@ -185,6 +249,7 @@ export interface ComponentTypeSpecification {
   SerializedComponent: SerializedBaseComponent;
   Dependencies: ComponentDependencies;
   MethodImplementations: ExposedMethods;
+  Emits: ComponentEmits;
 }
 
 /**
@@ -354,4 +419,32 @@ export abstract class BaseComponent<
       <T["MethodImplementations"]>{}
     );
   };
+
+  /**
+   * Returns the action configuration for a specific action of the component.
+   * @param event String that associates with an action of the component.
+   * @returns
+   */
+  public getActionConfig = (event: string) => {
+    return this.serializedBaseComponent.value.actions?.[event] as ComponentAction;
+  };
+
+  /**
+   * The actionHandler function is used to emit an action event.
+   * @param emit
+   * @param event
+   */
+  public actionHandler = (emit: EmitFn, event: string) => {
+    const payload = this.constructPayload?.();
+    const { type, action } = this.getActionConfig(event);
+
+    emit("action", type, action, payload);
+  };
+
+  /**
+   * The constructPayload function is used to construct the payload of an action event.
+   * The function must be implemented in the derived component class.
+   * @returns
+   */
+  protected constructPayload?(): ActionPayload | TypeOfLastTupleElement<T["Emits"][string]>;
 }

src/components/CodeEditor/CodeEditor.ts

@@ -5,7 +5,10 @@ import type {
   ComponentProps,
   ComponentState,
   ComponentTypeSpecification,
-  ComponentConfiguration
+  ComponentConfiguration,
+  ValidationStrategy,
+  ValidationConfigurationMap,
+  ValidationConfiguration
 } from "@/components/BaseComponent/BaseComponent";
 import { BaseComponent } from "@/components/BaseComponent/BaseComponent";
 import type { JSONPathExpression } from "@/stores/Store";
@@ -25,33 +28,89 @@ export type CodeEditorComponentType = "CodeEditor";
  * The CodeEditor-component requires the following dependencies. The paths to the dependencies are defined here via JSONPathExpression.
  */
 export interface SerializedCodeEditorDependencies extends SerialisedDependencies {
+  /**
+   * The globalDarkMode-property is a JSONPathExpression that may point to the user's dark mode preference.
+   */
   globalDarkMode?: JSONPathExpression;
+  /**
+   * The code-property is a JSONPathExpression that may point to the user's code.
+   */
   code?: JSONPathExpression;
+  /**
+   * The referenceCode-property is a JSONPathExpression that points to the reference code that the user's code will be compared against.
+   */
+  referenceCode?: JSONPathExpression;
 }
 
 /**
  * The CodeEditor-component requires the following dependencies. The types of the dependencies are defined here.
  */
 export interface CodeEditorDependencies extends ComponentDependencies {
+  /**
+   * The globalDarkMode-property is a boolean that may be used to determine the dark mode of the CodeEditor.
+   */
   globalDarkMode?: boolean | undefined;
+  /**
+   * The code-property is a string that may contains the user's code.
+   */
   code?: string;
+  /**
+   * The referenceCode-property is a string that mcontains the reference code that the user's code may be compared against.
+   */
+  referenceCode?: string;
 }
 
 /**
  * The CodeEditor-component may require state handling. This state is defined here.
  */
 export interface CodeEditorComponentState extends ComponentState {
+  /**
+   * The code-property is a string that contains the user's code.
+   */
   code: string;
 }
 
 /**
  * The CodeEditor-component may have configuration options. These options are defined here.
  */
 export interface CodeEditorConfiguration extends ComponentConfiguration {
+  /**
+   * The darkMode-property is a boolean that may be used to determine the dark mode of the CodeEditor.
+   */
   darkMode?: boolean;
+  /**
+   * The language-property is a string that may be used to determine the syntax highlighting of the CodeEditor.
+   */
   language?: SupportedLanguages;
 }
 
+/**
+ * The CodeEditor allows for optional validation strategies.
+ * The first strategy is a basic string compare.
+ * The second strategy is a request-based strategy, which may depend on a user-defined strategy (e.g. test-suite, output comparisons, more complex string comparisons, etc.).
+ *    As the second strategy may depend on more than just the code, the entire state is accessible.
+ */
+export type CodeEditorValidationConfiguration<
+  K extends keyof CodeEditorValidationConfigurationMap
+> = { [P in K]: { type: P } & CodeEditorValidationConfigurationMap[P] }[K] &
+  ValidationConfiguration;
+
+export interface StringComparison extends ValidationStrategy {
+  type: "compareToString";
+}
+
+export interface ExternalValidation extends ValidationStrategy {
+  type: "validateExternally";
+}
+
+/**
+ * Map of all available validation strategies for the CodeEditor component.
+ */
+interface CodeEditorValidationConfigurationMap extends ValidationConfigurationMap {
+  validateExternally: ExternalValidation;
+  compareToString: StringComparison;
+}
+
 /**
  * The SerializedCodeEditorComponent interface is used to define the serialised properties of the CodeEditor component.
  */
@@ -60,6 +119,9 @@ export interface SerializedCodeEditorComponent
   dependencies: SerializedCodeEditorDependencies;
   state: CodeEditorComponentState;
   componentConfiguration?: CodeEditorConfiguration;
+  validationConfiguration?: CodeEditorValidationConfiguration<
+    keyof CodeEditorValidationConfigurationMap
+  >;
 }
 
 export interface CodeEditorSpecification extends ComponentTypeSpecification {
@@ -71,13 +133,29 @@ export interface CodeEditorSpecification extends ComponentTypeSpecification {
  * The CodeEditorComponent class is a derived taskComponent, that displays a Graph specified in the Graphviz-DOT language.
  */
 export class CodeEditorComponent extends BaseComponent<CodeEditorSpecification> {
+  private validationStrategies: {
+    [K in keyof CodeEditorValidationConfigurationMap]: (
+      taskState: string,
+      functionConfig: CodeEditorValidationConfiguration<K>
+    ) => boolean;
+  } = {
+    validateExternally: this.externalValidation.bind(this),
+    compareToString: this.stringComparison.bind(this)
+  };
   /**
    * This function determines when a CodeEditorComponent is valid and when it is correct.
    * @returns
    */
-  public validate() {
+  public validate(userCode: string) {
     const validity = { isValid: false, isCorrect: false };
 
     return validity;
   }
+
+  private externalValidation(userCode: string, validationConfiguration: ExternalValidation) {
+    return true;
+  }
+  private stringComparison(userCode: string, validationConfiguration: StringComparison) {
+    return true;
+  }
 }

src/components/GenericButton/GenericButton.ts

@@ -5,7 +5,8 @@ import type {
   ComponentProps,
   ComponentState,
   ComponentTypeSpecification,
-  ComponentConfiguration
+  ComponentConfiguration,
+  ComponentEmits
 } from "@/components/BaseComponent/BaseComponent";
 import { BaseComponent } from "@/components/BaseComponent/BaseComponent";
 import type { IconList } from "@/Util/IconList";
@@ -17,10 +18,17 @@ export interface ButtonProps extends ComponentProps {
   isValid: boolean;
 }
 
+/**
+ * The ClickEmit type is used to define the emitted event of the Button component.
+ */
+export type ClickEmit = [];
+
 /**
  * The Button component emitts an event on click.
  */
-export type ButtonEmits = { buttonClick: [] };
+export type ButtonEmits = {
+  buttonClick: ClickEmit;
+} & ComponentEmits;
 
 /**
  * The type of the Button component.
@@ -89,6 +97,7 @@ export interface SerializedButtonComponent extends SerializedBaseComponent<Butto
 export interface ButtonSpecification extends ComponentTypeSpecification {
   SerializedComponent: SerializedButtonComponent;
   Dependencies: ButtonDependencies;
+  Emits: ButtonEmits;
 }
 
 /**