@decaf-ts/ui-decorators 0.9.0 → 0.11.0

package/lib/types/ui/DecafTranslateService.d.cts

@@ -0,0 +1,5 @@
+import { LoggedClass } from "@decaf-ts/logging";
+export declare class DecafTranslateService extends LoggedClass {
+    translate(key: string, params?: Record<string, any>): any;
+    instant(key: string, params?: Record<string, any>): any;
+}

package/lib/types/ui/DecafTranslateService.d.mts

@@ -0,0 +1,5 @@
+import { LoggedClass } from "@decaf-ts/logging";
+export declare class DecafTranslateService extends LoggedClass {
+    translate(key: string, params?: Record<string, any>): any;
+    instant(key: string, params?: Record<string, any>): any;
+}

package/lib/types/ui/Rendering.d.cts

@@ -0,0 +1,202 @@
+import { FieldDefinition } from "./types.cjs";
+import { Model, ValidationMetadata } from "@decaf-ts/decorator-validation";
+/**
+ * @description Abstract class for rendering UI components based on model metadata.
+ * @summary The RenderingEngine class provides a framework for converting model metadata into UI field definitions.
+ * It handles the translation of model properties to UI elements, applies validation rules, and manages different rendering flavors.
+ * This class is designed to be extended by specific rendering implementations.
+ *
+ * @template T The type of the rendering result, defaults to void
+ * @template R The type of the field definition, defaults to FieldDefinition<T>
+ *
+ * @param {string} flavour - The flavor of the rendering engine.
+ *
+ * @class RenderingEngine
+ */
+/**
+ * Represents the base abstraction for decaf rendering engines, handling engine registration,
+ * initialization, model-to-field translation, and runtime rendering orchestration.
+ * Implementations must provide initialization and rendering logic while leveraging the shared
+ * metadata-driven conversion utilities supplied here.
+ */
+export declare abstract class RenderingEngine<T = void, R = FieldDefinition<T>> {
+    readonly flavour: string;
+    /**
+     * @description Cache for storing rendering engine instances or constructors.
+     * @private
+     * @static
+     */
+    private static cache;
+    /**
+     * @description The currently active rendering engine.
+     * @private
+     * @static
+     */
+    private static current;
+    /**
+     * Flag indicating whether the rendering engine has been initialized.
+     */
+    protected initialized: boolean;
+    protected constructor(flavour: string);
+    /**
+     * @description Initializes the rendering engine.
+     * @summary Abstract method to be implemented by subclasses for specific initialization logic.
+     *
+     * @param {...any[]} args - Any additional arguments needed for initialization.
+     * @returns {Promise<void>} A promise that resolves when initialization is complete.
+     *
+     * @abstract
+     */
+    abstract initialize(...args: any[]): Promise<void>;
+    /**
+     * @description Translates between model types and HTML input types.
+     * @summary Converts model data types to appropriate HTML input types and vice versa.
+     *
+     * @param {string} key - The key to translate.
+     * @param {boolean} [toView=true] - Direction of translation (true for model to view, false for view to model).
+     * @returns {string} The translated type.
+     */
+    translate(key: string, toView?: boolean): string;
+    /**
+     * @description Retrieves class decorator metadata for a model instance
+     * @summary Extracts UI-related class decorators from a model and returns them as an array
+     * This method collects metadata from various UI class decorators including @uimodel,
+     * @uilistmodel, @uihandlers, and @uilayout applied to the model class.
+     *
+     * @template M Type extending Model
+     * @param {M} model - The model instance to extract metadata from
+     * @returns {UIClassMetadata[]} Array of UI class metadata objects
+     *
+     * @private
+     */
+    private getClassDecoratorsMetadata;
+    private sortChildrenByOrder;
+    /**
+     * @description Checks if a validation key represents a custom validator (i.e., not a built-in validation or UI key).
+     * @summary Determines whether the provided key corresponds to a user-defined validator by excluding all built-in ValidationKeys and UIKeys.
+     *
+     * @param {string} key - The validation key to check.
+     * @returns {boolean} True if the key is a custom validator, false otherwise.
+     * @returns {boolean} True if the key is not a built-in validation key or UI key (i.e. is custom), false otherwise.
+     */
+    protected isCustomValidator(key: string): boolean;
+    /**
+     * @description Checks if a type is validatable by its nature.
+     * @summary Determines if a given UI key represents a type that is inherently validatable.
+     *
+     * @param {string} key - The UI key to check.
+     * @returns {boolean} True if the type is validatable, false otherwise.
+     */
+    protected isValidatableByType(key: string): boolean;
+    /**
+     * @description Checks if a type is validatable by attribute.
+     * @summary Determines if a given UI key represents a validation that can be applied as an attribute.
+     *
+     * @param {string} key - The UI key to check.
+     * @returns {boolean} True if the type is validatable by attribute, false otherwise.
+     */
+    protected isValidatableByAttribute(key: string): boolean;
+    /**
+     * @description Converts validation metadata to an attribute value.
+     * @summary Transforms validation metadata into a value suitable for use as an HTML attribute.
+     *
+     * @param {string} key - The validation key.
+     * @param {ValidationMetadata} value - The validation metadata.
+     * @returns {string | number | boolean} The converted attribute value.
+     * @throws {Error} If the given key is not validatable by attribute.
+     */
+    protected toAttributeValue(key: string, value: ValidationMetadata): string | number | boolean;
+    /**
+     * @description Converts a model to a field definition.
+     * @summary Processes a model instance, extracting UI-related metadata and validation rules to create a field definition.
+     *
+     * @template M Type extending Model
+     * @template T Type referencing the specific Rendering engine field properties/inputs
+     * @param {M} model - The model instance to convert.
+     * @param {Record<string, unknown>} [globalProps={}] - Global properties to apply to all child elements.
+     * @param {boolean} [generateId=true] - Flag indicating whether to populate the rendererId property.
+     * @returns {FieldDefinition<T>} A field definition object representing the UI structure of the model.
+     * @throws {RenderingError} If no UI definitions are set for the model or if there are invalid decorators.
+     *
+     * @mermaid
+     * sequenceDiagram
+     *  participant C as Client
+     *  participant RE as RenderingEngine
+     *  participant R as Reflection
+     *  participant M as Model
+     *  C->>RE: toFieldDefinition(model, globalProps)
+     *  RE->>R: getMetadata(UIKeys.UIMODEL, model.constructor)
+     *  R-->>RE: UIModelMetadata
+     *  RE->>R: getAllPropertyDecorators(model, UIKeys.REFLECT)
+     *  R-->>RE: Record<string, DecoratorMetadata[]>
+     *  RE->>R: getAllPropertyDecorators(model, ValidationKeys.REFLECT)
+     *  R-->>RE: Record<string, DecoratorMetadata<ValidationMetadata>[]>
+     *  loop For each property
+     *    RE->>RE: Process UI decorators
+     *    RE->>RE: Apply validation rules
+     *  end
+     *  RE-->>C: FieldDefinition<T>
+     */
+    protected toFieldDefinition<M extends Model>(model: M, globalProps?: Record<string, unknown>, generateId?: boolean): FieldDefinition<T>;
+    /**
+     * @description Renders a model with global properties and additional arguments.
+     * @summary Abstract method to be implemented by subclasses to define specific rendering behavior.
+     *
+     * @template M Type extending Model
+     * @template R Rendering engine implementation specific output type
+     * @param {M} model - The model to be rendered.
+     * @param {Record<string, unknown>} globalProps - Global properties to be applied to all elements during rendering.
+     * @param {...any[]} args - Additional arguments that may be required for specific rendering implementations.
+     * @returns {R} The rendered result, type depends on the specific implementation.
+     *
+     * @abstract
+     */
+    abstract render<M extends Model>(model: M, globalProps: Record<string, unknown>, ...args: any[]): R;
+    /**
+     * @description Registers a rendering engine instance.
+     * @summary Adds a rendering engine to the static cache and sets it as the current engine.
+     *
+     * @param {RenderingEngine<unknown, unknown>} engine - The rendering engine to register.
+     * @throws {InternalError} If an engine with the same flavor already exists.
+     *
+     * @static
+     */
+    static register(engine: RenderingEngine<unknown, unknown>): void;
+    /**
+     * @description Retrieves or initializes a rendering engine.
+     * @summary Gets an existing engine instance or creates and initializes a new one if given a constructor.
+     *
+     * @template O The type of the rendering engine output
+     * @param {Constructor<RenderingEngine<O>> | RenderingEngine<O>} obj - The engine instance or constructor.
+     * @returns {RenderingEngine<O>} The initialized rendering engine.
+     *
+     * @private
+     * @static
+     */
+    private static getOrBoot;
+    /**
+     * @description Retrieves a rendering engine by flavor.
+     * @summary Gets the current rendering engine or a specific one by flavor.
+     *
+     * @template O The type of the rendering engine output
+     * @param {string} [flavour] - The flavor of the rendering engine to retrieve.
+     * @returns {RenderingEngine<O>} The requested rendering engine.
+     * @throws {InternalError} If the requested flavor does not exist.
+     *
+     * @static
+     */
+    static get<O>(flavour?: string): RenderingEngine<O>;
+    /**
+     * @description Renders a model using the appropriate rendering engine.
+     * @summary Determines the correct rendering engine for a model and invokes its render method.
+     *
+     * @template M Type extending Model
+     * @param {M} model - The model to render.
+     * @param {...any[]} args - Additional arguments to pass to the render method.
+     * @returns {any} The result of the rendering process.
+     * @throws {InternalError} If no registered model is found.
+     *
+     * @static
+     */
+    static render<M extends Model>(model: M, ...args: any[]): any;
+}

package/lib/types/ui/Rendering.d.mts

@@ -0,0 +1,202 @@
+import { FieldDefinition } from "./types.js";
+import { Model, ValidationMetadata } from "@decaf-ts/decorator-validation";
+/**
+ * @description Abstract class for rendering UI components based on model metadata.
+ * @summary The RenderingEngine class provides a framework for converting model metadata into UI field definitions.
+ * It handles the translation of model properties to UI elements, applies validation rules, and manages different rendering flavors.
+ * This class is designed to be extended by specific rendering implementations.
+ *
+ * @template T The type of the rendering result, defaults to void
+ * @template R The type of the field definition, defaults to FieldDefinition<T>
+ *
+ * @param {string} flavour - The flavor of the rendering engine.
+ *
+ * @class RenderingEngine
+ */
+/**
+ * Represents the base abstraction for decaf rendering engines, handling engine registration,
+ * initialization, model-to-field translation, and runtime rendering orchestration.
+ * Implementations must provide initialization and rendering logic while leveraging the shared
+ * metadata-driven conversion utilities supplied here.
+ */
+export declare abstract class RenderingEngine<T = void, R = FieldDefinition<T>> {
+    readonly flavour: string;
+    /**
+     * @description Cache for storing rendering engine instances or constructors.
+     * @private
+     * @static
+     */
+    private static cache;
+    /**
+     * @description The currently active rendering engine.
+     * @private
+     * @static
+     */
+    private static current;
+    /**
+     * Flag indicating whether the rendering engine has been initialized.
+     */
+    protected initialized: boolean;
+    protected constructor(flavour: string);
+    /**
+     * @description Initializes the rendering engine.
+     * @summary Abstract method to be implemented by subclasses for specific initialization logic.
+     *
+     * @param {...any[]} args - Any additional arguments needed for initialization.
+     * @returns {Promise<void>} A promise that resolves when initialization is complete.
+     *
+     * @abstract
+     */
+    abstract initialize(...args: any[]): Promise<void>;
+    /**
+     * @description Translates between model types and HTML input types.
+     * @summary Converts model data types to appropriate HTML input types and vice versa.
+     *
+     * @param {string} key - The key to translate.
+     * @param {boolean} [toView=true] - Direction of translation (true for model to view, false for view to model).
+     * @returns {string} The translated type.
+     */
+    translate(key: string, toView?: boolean): string;
+    /**
+     * @description Retrieves class decorator metadata for a model instance
+     * @summary Extracts UI-related class decorators from a model and returns them as an array
+     * This method collects metadata from various UI class decorators including @uimodel,
+     * @uilistmodel, @uihandlers, and @uilayout applied to the model class.
+     *
+     * @template M Type extending Model
+     * @param {M} model - The model instance to extract metadata from
+     * @returns {UIClassMetadata[]} Array of UI class metadata objects
+     *
+     * @private
+     */
+    private getClassDecoratorsMetadata;
+    private sortChildrenByOrder;
+    /**
+     * @description Checks if a validation key represents a custom validator (i.e., not a built-in validation or UI key).
+     * @summary Determines whether the provided key corresponds to a user-defined validator by excluding all built-in ValidationKeys and UIKeys.
+     *
+     * @param {string} key - The validation key to check.
+     * @returns {boolean} True if the key is a custom validator, false otherwise.
+     * @returns {boolean} True if the key is not a built-in validation key or UI key (i.e. is custom), false otherwise.
+     */
+    protected isCustomValidator(key: string): boolean;
+    /**
+     * @description Checks if a type is validatable by its nature.
+     * @summary Determines if a given UI key represents a type that is inherently validatable.
+     *
+     * @param {string} key - The UI key to check.
+     * @returns {boolean} True if the type is validatable, false otherwise.
+     */
+    protected isValidatableByType(key: string): boolean;
+    /**
+     * @description Checks if a type is validatable by attribute.
+     * @summary Determines if a given UI key represents a validation that can be applied as an attribute.
+     *
+     * @param {string} key - The UI key to check.
+     * @returns {boolean} True if the type is validatable by attribute, false otherwise.
+     */
+    protected isValidatableByAttribute(key: string): boolean;
+    /**
+     * @description Converts validation metadata to an attribute value.
+     * @summary Transforms validation metadata into a value suitable for use as an HTML attribute.
+     *
+     * @param {string} key - The validation key.
+     * @param {ValidationMetadata} value - The validation metadata.
+     * @returns {string | number | boolean} The converted attribute value.
+     * @throws {Error} If the given key is not validatable by attribute.
+     */
+    protected toAttributeValue(key: string, value: ValidationMetadata): string | number | boolean;
+    /**
+     * @description Converts a model to a field definition.
+     * @summary Processes a model instance, extracting UI-related metadata and validation rules to create a field definition.
+     *
+     * @template M Type extending Model
+     * @template T Type referencing the specific Rendering engine field properties/inputs
+     * @param {M} model - The model instance to convert.
+     * @param {Record<string, unknown>} [globalProps={}] - Global properties to apply to all child elements.
+     * @param {boolean} [generateId=true] - Flag indicating whether to populate the rendererId property.
+     * @returns {FieldDefinition<T>} A field definition object representing the UI structure of the model.
+     * @throws {RenderingError} If no UI definitions are set for the model or if there are invalid decorators.
+     *
+     * @mermaid
+     * sequenceDiagram
+     *  participant C as Client
+     *  participant RE as RenderingEngine
+     *  participant R as Reflection
+     *  participant M as Model
+     *  C->>RE: toFieldDefinition(model, globalProps)
+     *  RE->>R: getMetadata(UIKeys.UIMODEL, model.constructor)
+     *  R-->>RE: UIModelMetadata
+     *  RE->>R: getAllPropertyDecorators(model, UIKeys.REFLECT)
+     *  R-->>RE: Record<string, DecoratorMetadata[]>
+     *  RE->>R: getAllPropertyDecorators(model, ValidationKeys.REFLECT)
+     *  R-->>RE: Record<string, DecoratorMetadata<ValidationMetadata>[]>
+     *  loop For each property
+     *    RE->>RE: Process UI decorators
+     *    RE->>RE: Apply validation rules
+     *  end
+     *  RE-->>C: FieldDefinition<T>
+     */
+    protected toFieldDefinition<M extends Model>(model: M, globalProps?: Record<string, unknown>, generateId?: boolean): FieldDefinition<T>;
+    /**
+     * @description Renders a model with global properties and additional arguments.
+     * @summary Abstract method to be implemented by subclasses to define specific rendering behavior.
+     *
+     * @template M Type extending Model
+     * @template R Rendering engine implementation specific output type
+     * @param {M} model - The model to be rendered.
+     * @param {Record<string, unknown>} globalProps - Global properties to be applied to all elements during rendering.
+     * @param {...any[]} args - Additional arguments that may be required for specific rendering implementations.
+     * @returns {R} The rendered result, type depends on the specific implementation.
+     *
+     * @abstract
+     */
+    abstract render<M extends Model>(model: M, globalProps: Record<string, unknown>, ...args: any[]): R;
+    /**
+     * @description Registers a rendering engine instance.
+     * @summary Adds a rendering engine to the static cache and sets it as the current engine.
+     *
+     * @param {RenderingEngine<unknown, unknown>} engine - The rendering engine to register.
+     * @throws {InternalError} If an engine with the same flavor already exists.
+     *
+     * @static
+     */
+    static register(engine: RenderingEngine<unknown, unknown>): void;
+    /**
+     * @description Retrieves or initializes a rendering engine.
+     * @summary Gets an existing engine instance or creates and initializes a new one if given a constructor.
+     *
+     * @template O The type of the rendering engine output
+     * @param {Constructor<RenderingEngine<O>> | RenderingEngine<O>} obj - The engine instance or constructor.
+     * @returns {RenderingEngine<O>} The initialized rendering engine.
+     *
+     * @private
+     * @static
+     */
+    private static getOrBoot;
+    /**
+     * @description Retrieves a rendering engine by flavor.
+     * @summary Gets the current rendering engine or a specific one by flavor.
+     *
+     * @template O The type of the rendering engine output
+     * @param {string} [flavour] - The flavor of the rendering engine to retrieve.
+     * @returns {RenderingEngine<O>} The requested rendering engine.
+     * @throws {InternalError} If the requested flavor does not exist.
+     *
+     * @static
+     */
+    static get<O>(flavour?: string): RenderingEngine<O>;
+    /**
+     * @description Renders a model using the appropriate rendering engine.
+     * @summary Determines the correct rendering engine for a model and invokes its render method.
+     *
+     * @template M Type extending Model
+     * @param {M} model - The model to render.
+     * @param {...any[]} args - Additional arguments to pass to the render method.
+     * @returns {any} The result of the rendering process.
+     * @throws {InternalError} If no registered model is found.
+     *
+     * @static
+     */
+    static render<M extends Model>(model: M, ...args: any[]): any;
+}

package/lib/types/ui/UIValidator.d.cts

@@ -0,0 +1,6 @@
+import { Validator } from "@decaf-ts/decorator-validation";
+import { DecafTranslateService } from "./DecafTranslateService.cjs";
+export declare abstract class UIValidator extends Validator {
+    static translateService: DecafTranslateService;
+    getMessage(message: string, ...args: any[]): string;
+}

package/lib/types/ui/UIValidator.d.mts

@@ -0,0 +1,6 @@
+import { Validator } from "@decaf-ts/decorator-validation";
+import { DecafTranslateService } from "./DecafTranslateService.js";
+export declare abstract class UIValidator extends Validator {
+    static translateService: DecafTranslateService;
+    getMessage(message: string, ...args: any[]): string;
+}