@decaf-ts/for-angular 0.0.3 → 0.0.5

package/dist/lib/engine/NgxRenderingEngine2.d.ts

@@ -0,0 +1,251 @@
+import { FieldDefinition, RenderingEngine } from '@decaf-ts/ui-decorators';
+import { AngularDynamicOutput, AngularFieldDefinition, KeyValue } from './types';
+import { Constructor, Model } from '@decaf-ts/decorator-validation';
+import { ComponentMirror, ComponentRef, Injector, TemplateRef, Type, ViewContainerRef } from '@angular/core';
+/**
+ * @description Angular implementation of the RenderingEngine with enhanced features
+ * @summary This class extends the base RenderingEngine to provide Angular-specific rendering capabilities
+ * with additional features compared to NgxRenderingEngine. It handles the conversion of field definitions
+ * to Angular components, manages component registration, and provides utilities for component creation
+ * and input handling. This implementation uses Angular's newer component APIs.
+ *
+ * @template AngularFieldDefinition - Type for Angular-specific field definitions
+ * @template AngularDynamicOutput - Type for Angular-specific component output
+ *
+ * @class NgxRenderingEngine2
+ * @example
+ * ```typescript
+ * const engine = NgxRenderingEngine2.get();
+ * engine.initialize();
+ * const output = engine.render(myModel, {}, viewContainerRef, injector, templateRef);
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant Engine as NgxRenderingEngine2
+ *   participant Components as RegisteredComponents
+ *
+ *   Client->>Engine: get()
+ *   Client->>Engine: initialize()
+ *   Client->>Engine: render(model, props, vcr, injector, tpl)
+ *   Engine->>Engine: toFieldDefinition(model, props)
+ *   Engine->>Engine: fromFieldDefinition(fieldDef, vcr, injector, tpl)
+ *   Engine->>Components: components(fieldDef.tag)
+ *   Components-->>Engine: component constructor
+ *   Engine->>Engine: createComponent(component, inputs, metadata, vcr, injector, template)
+ *   Engine-->>Client: return AngularDynamicOutput
+ */
+export declare class NgxRenderingEngine2 extends RenderingEngine<AngularFieldDefinition, AngularDynamicOutput> {
+    /**
+     * @description Registry of registered components
+     * @summary Static registry that maps component names to their constructors.
+     * This allows the engine to look up components by name when rendering.
+     * @type {Record<string, { constructor: Constructor<unknown> }>}
+     */
+    private static _components;
+    /**
+     * @description Collection of child component outputs
+     * @summary Stores the outputs of child components during rendering.
+     * @type {AngularDynamicOutput[]}
+     */
+    private _childs;
+    /**
+     * @description Current model being rendered
+     * @summary Reference to the model currently being processed by the rendering engine.
+     * @type {Model}
+     */
+    private _model;
+    /**
+     * @description Static reference to the current instance
+     * @summary Singleton instance reference for the rendering engine.
+     * @type {Type<unknown> | undefined}
+     */
+    private static _instance;
+    /**
+     * @description Creates a new instance of NgxRenderingEngine2
+     * @summary Initializes the rendering engine with the 'angular' engine type.
+     * This constructor sets up the base configuration needed for Angular-specific rendering.
+     */
+    constructor();
+    /**
+     * @description Converts a field definition to an Angular component output
+     * @summary This private method takes a field definition and creates the corresponding Angular component.
+     * It handles component instantiation, input property mapping, and child component rendering.
+     * The method validates input properties against the component's metadata and processes
+     * child components recursively.
+     *
+     * @param {FieldDefinition<AngularFieldDefinition>} fieldDef - The field definition to convert
+     * @param {ViewContainerRef} vcr - The view container reference for component creation
+     * @param {Injector} injector - The Angular injector for dependency injection
+     * @param {TemplateRef<any>} tpl - The template reference for content projection
+     * @param {string} registryFormId - Form identifier for the component renderer
+     * @return {AngularDynamicOutput} The Angular component output with component reference and inputs
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Method as fromFieldDefinition
+     *   participant Components as NgxRenderingEngine2.components
+     *   participant Angular as Angular Core
+     *   participant Process as processChild
+     *
+     *   Method->>Components: components(fieldDef.tag)
+     *   Components-->>Method: component constructor
+     *   Method->>Angular: reflectComponentType(component)
+     *   Angular-->>Method: componentMetadata
+     *   Method->>Method: Validate input properties
+     *   Method->>Method: Create result object
+     *   alt Has children
+     *     Method->>Process: Process children recursively
+     *     Process->>Method: Return processed children
+     *     Method->>Angular: Create embedded view
+     *     Method->>Method: Create component instance
+     *   end
+     *   Method-->>Caller: return AngularDynamicOutput
+     */
+    private fromFieldDefinition;
+    /**
+     * @description Creates an Angular component instance
+     * @summary This static utility method creates an Angular component instance with the specified
+     * inputs and template. It uses Angular's component creation API to instantiate the component
+     * and then sets the input properties using the provided metadata.
+     *
+     * @param {Type<unknown>} component - The component type to create
+     * @param {KeyValue} [inputs={}] - The input properties to set on the component
+     * @param {ComponentMirror<unknown>} metadata - The component metadata for input validation
+     * @param {ViewContainerRef} vcr - The view container reference for component creation
+     * @param {Injector} injector - The Angular injector for dependency injection
+     * @param {any} [template=[]] - The template nodes to project into the component
+     * @return {ComponentRef<unknown>} The created component reference
+     */
+    static createComponent(component: Type<unknown>, inputs: KeyValue | undefined, metadata: ComponentMirror<unknown>, vcr: ViewContainerRef, injector: Injector, template?: any): ComponentRef<unknown>;
+    /**
+     * @description Extracts decorator metadata from a model
+     * @summary This method provides access to the field definition generated from a model's
+     * decorators. It's a convenience wrapper around the toFieldDefinition method that
+     * converts a model to a field definition based on its decorators and the provided
+     * global properties.
+     *
+     * @param {Model} model - The model to extract decorators from
+     * @param {Record<string, unknown>} globalProps - Global properties to include in the field definition
+     * @return {FieldDefinition<AngularFieldDefinition>} The field definition generated from the model
+     */
+    getDecorators(model: Model, globalProps: Record<string, unknown>): FieldDefinition<AngularFieldDefinition>;
+    /**
+     * @description Destroys the current engine instance
+     * @summary This static method clears the current instance reference, effectively
+     * destroying the singleton instance of the rendering engine. This can be used
+     * to reset the engine state or to prepare for a new instance creation.
+     *
+     * @return {Promise<void>} A promise that resolves when the instance is destroyed
+     */
+    static destroy(): Promise<void>;
+    /**
+     * @description Renders a model into an Angular component output
+     * @summary This method takes a model and converts it to an Angular component output.
+     * It first stores a reference to the model, then converts it to a field definition
+     * using the base RenderingEngine's toFieldDefinition method, and finally converts
+     * that field definition to an Angular component output using fromFieldDefinition.
+     *
+     * @template M - Type extending Model
+     * @param {M} model - The model to render
+     * @param {Record<string, unknown>} globalProps - Global properties to pass to the component
+     * @param {ViewContainerRef} vcr - The view container reference for component creation
+     * @param {Injector} injector - The Angular injector for dependency injection
+     * @param {TemplateRef<any>} tpl - The template reference for content projection
+     * @return {AngularDynamicOutput} The Angular component output with component reference and inputs
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Client as Client Code
+     *   participant Render as render method
+     *   participant ToField as toFieldDefinition
+     *   participant FromField as fromFieldDefinition
+     *
+     *   Client->>Render: render(model, globalProps, vcr, injector, tpl)
+     *   Render->>Render: Store model reference
+     *   Render->>ToField: toFieldDefinition(model, globalProps)
+     *   ToField-->>Render: fieldDef
+     *   Render->>FromField: fromFieldDefinition(fieldDef, vcr, injector, tpl)
+     *   FromField-->>Render: AngularDynamicOutput
+     *   Render-->>Client: return AngularDynamicOutput
+     */
+    render<M extends Model>(model: M, globalProps: Record<string, unknown>, vcr: ViewContainerRef, injector: Injector, tpl: TemplateRef<any>): AngularDynamicOutput;
+    /**
+     * @description Initializes the rendering engine
+     * @summary This method initializes the rendering engine. It checks if the engine is already initialized
+     * and sets the initialized flag to true. This method is called before the engine is used
+     * to ensure it's properly set up for rendering operations.
+     *
+     * @param {...any[]} args - Initialization arguments
+     * @return {Promise<void>} A promise that resolves when initialization is complete
+     */
+    initialize(...args: any[]): Promise<void>;
+    /**
+     * @description Registers a component with the rendering engine
+     * @summary This static method registers a component constructor with the rendering engine
+     * under a specific name. It initializes the components registry if needed and throws
+     * an error if a component is already registered under the same name to prevent
+     * accidental overrides.
+     *
+     * @param {string} name - The name to register the component under
+     * @param {Constructor<unknown>} constructor - The component constructor
+     * @return {void}
+     */
+    static registerComponent(name: string, constructor: Constructor<unknown>): void;
+    /**
+     * @description Retrieves registered components from the rendering engine
+     * @summary This static method retrieves either all registered components or a specific component
+     * by its selector. When called without a selector, it returns an array of all registered
+     * components. When called with a selector, it returns the specific component if found,
+     * or throws an error if the component is not registered.
+     *
+     * @param {string} [selector] - Optional selector to retrieve a specific component
+     * @return {Object|Array} Either a specific component or an array of all components
+     */
+    static components(selector?: string): object | any[];
+    /**
+     * @description Generates a key for reflection metadata
+     * @summary This static method generates a key for reflection metadata by prefixing the input key
+     * with the Angular engine's reflection prefix. This is used for storing and retrieving
+     * metadata in a namespaced way to avoid conflicts with other metadata.
+     *
+     * @param {string} key - The base key to prefix
+     * @return {string} The prefixed key for reflection metadata
+     */
+    static key(key: string): string;
+    /**
+     * @description Sets input properties on a component instance
+     * @summary This static utility method sets input properties on a component instance
+     * based on the provided inputs object and component metadata. It handles both simple
+     * values and nested objects, recursively processing object properties. The method
+     * validates each input against the component's metadata to ensure only valid inputs
+     * are set.
+     *
+     * @param {ComponentRef<unknown>} component - The component reference to set inputs on
+     * @param {KeyValue} inputs - The input properties to set
+     * @param {ComponentMirror<unknown>} metadata - The component metadata for input validation
+     * @return {void}
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant SetInputs as setInputs
+     *   participant Parse as parseInputValue
+     *   participant Component as ComponentRef
+     *
+     *   Caller->>SetInputs: setInputs(component, inputs, metadata)
+     *   SetInputs->>SetInputs: Iterate through inputs
+     *   loop For each input
+     *     SetInputs->>SetInputs: Check if input exists in metadata
+     *     alt Input is 'props'
+     *       SetInputs->>Parse: parseInputValue(component, value)
+     *       Parse->>Parse: Recursively process nested objects
+     *       Parse->>Component: setInput(key, value)
+     *     else Input is valid
+     *       SetInputs->>Component: setInput(key, value)
+     *     end
+     *   end
+     */
+    static setInputs(component: ComponentRef<unknown>, inputs: KeyValue, metadata: ComponentMirror<unknown>): void;
+}

package/dist/lib/engine/ValidatorFactory.d.ts

@@ -0,0 +1,15 @@
+import { AbstractControl, ValidatorFn } from '@angular/forms';
+import { PathProxy } from '@decaf-ts/decorator-validation';
+import { FieldProperties } from '@decaf-ts/ui-decorators';
+export declare class ValidatorFactory {
+    static spawn(fieldProps: FieldProperties, key: string): ValidatorFn;
+    /**
+     * @summary Creates a proxy wrapper for an Angular AbstractControl to assist with custom validation logic.
+     * @description Returns a structured proxy object that simulates a hierarchical tree of form values.
+     * Enables Validators handling method to access parent and child properties using consistent dot-notation in Angular forms.
+     *
+     * @param {AbstractControl} control - The control to wrap in a proxy.
+     * @returns {PathProxy<any>} A proxy object exposing form values and enabling recursive parent access.
+     */
+    static createProxy(control: AbstractControl): PathProxy<any>;
+}

package/dist/lib/engine/constants.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @description Angular engine key constants
+ * @summary Contains key strings used by the Angular rendering engine for reflection,
+ * dynamic component creation, and other engine operations.
+ * @typedef {Object} AngularEngineKeys
+ * @property {string} REFLECT - Prefix for reflection metadata keys
+ * @property {string} DYNAMIC - Key for dynamic component identification
+ * @property {string} ANNOTATIONS - Key for component annotations
+ * @property {string} ECMP - Key for embedded components
+ * @property {string} NG_REFLECT - Prefix for Angular reflection attributes
+ * @property {string} RENDERED - Prefix for rendered component markers
+ * @property {string} MAPPER - Key for property mappers
+ * @property {string} CHILDREN - Key for child components
+ * @property {string} LISTABLE - Key for listable components
+ * @property {string} RENDER - Key for renderable components
+ * @property {string} RENDERED_ID - Template for rendered component IDs
+ * @property {string} PARENT - Key for comparison decorators and validators
+ * @const AngularEngineKeys
+ * @memberOf module:engine
+ */
+export declare const AngularEngineKeys: {
+    REFLECT: string;
+    DYNAMIC: string;
+    ANNOTATIONS: string;
+    ECMP: string;
+    NG_REFLECT: string;
+    RENDERED: string;
+    MAPPER: string;
+    CHILDREN: string;
+    LISTABLE: string;
+    RENDER: string;
+    RENDERED_ID: string;
+    PARENT: string;
+    VALIDATION_PARENT_KEY: symbol;
+};
+/**
+ * @description Form validation state constants
+ * @summary Contains constants representing the possible validation states of a form.
+ * These are used to check and handle form validation throughout the application.
+ * @typedef {Object} FormConstants
+ * @property {string} VALID - Constant representing a valid form state
+ * @property {string} INVALID - Constant representing an invalid form state
+ * @const FormConstants
+ * @memberOf module:engine
+ */
+export declare const FormConstants: {
+    VALID: string;
+    INVALID: string;
+};
+/**
+ * @description Event name constants
+ * @summary Enum containing constants for event names used throughout the application.
+ * These are used to standardize event naming and handling.
+ * @enum {string}
+ * @readonly
+ * @property {string} BACK_BUTTON_NAVIGATION - Event fired when back button navigation ends
+ * @property {string} REFRESH_EVENT - Event fired when a refresh action occurs
+ * @property {string} CLICK_EVENT - Event fired when a click action occurs
+ * @property {string} SUBMIT_EVENT - Event fired when a form submission occurs
+ * @memberOf module:engine
+ */
+export declare enum EventConstants {
+    BACK_BUTTON_NAVIGATION = "backButtonNavigationEndEvent",
+    REFRESH_EVENT = "RefreshEvent",
+    CLICK_EVENT = "ClickEvent",
+    SUBMIT_EVENT = "SubmitEvent"
+}
+/**
+ * @description Logger level constants
+ * @summary Enum defining the logging levels used in the application's logging system.
+ * Lower values represent more verbose logging, while higher values represent more critical logs.
+ * @enum {number}
+ * @readonly
+ * @property {number} ALL - Log everything (most verbose)
+ * @property {number} DEBUG - Log debug information
+ * @property {number} INFO - Log informational messages
+ * @property {number} WARN - Log warnings
+ * @property {number} ERROR - Log errors
+ * @property {number} CRITICAL - Log critical errors (least verbose)
+ * @memberOf module:engine
+ */
+export declare enum LoggerLevels {
+    ALL = 0,
+    DEBUG = 1,
+    INFO = 2,
+    WARN = 3,
+    ERROR = 4,
+    CRITICAL = 5
+}
+/**
+ * @description Route direction constants
+ * @summary Enum defining the possible navigation directions in the application.
+ * Used for controlling navigation flow and animation directions.
+ * @enum {string}
+ * @readonly
+ * @property {string} BACK - Navigate back to the previous page
+ * @property {string} FORWARD - Navigate forward to the next page
+ * @property {string} ROOT - Navigate to the root/home page
+ * @memberOf module:engine
+ */
+export declare enum RouteDirections {
+    BACK = "back",
+    FORWARD = "forward",
+    ROOT = "root"
+}
+/**
+ * @description Component tag name constants
+ * @summary Enum defining the tag names for custom components used in the application.
+ * These tag names are used for component registration and rendering.
+ * @enum {string}
+ * @readonly
+ * @property {string} LIST_ITEM - Tag name for list item component
+ * @property {string} LIST_INFINITE - Tag name for infinite scrolling list component
+ * @property {string} LIST_PAGINATED - Tag name for paginated list component
+ * @memberOf module:engine
+ */
+export declare enum ComponentsTagNames {
+    LIST_ITEM = "ngx-decaf-list-item",
+    LIST_INFINITE = "ngx-decaf-list-infinite",
+    LIST_PAGINATED = "ngx-decaf-list-paginated"
+}
+/**
+ * @description Base component property name constants
+ * @summary Enum defining the standard property names used by base components in the application.
+ * These property names are used for consistent property access across components.
+ * @enum {string}
+ * @readonly
+ * @property {string} MODEL - Property name for the component's data model
+ * @property {string} LOCALE - Property name for localization settings
+ * @property {string} PK - Property name for primary key
+ * @property {string} ITEMS - Property name for collection items
+ * @property {string} ROUTE - Property name for routing information
+ * @property {string} OPERATIONS - Property name for available operations
+ * @property {string} UID - Property name for unique identifier
+ * @property {string} TRANSLATABLE - Property name for translation flag
+ * @property {string} MAPPER - Property name for property mapper
+ * @property {string} INITIALIZED - Property name for initialization state
+ * @memberOf module:engine
+ */
+export declare enum BaseComponentProps {
+    MODEL = "model",
+    LOCALE = "locale",
+    PK = "pk",
+    ITEMS = "items",
+    ROUTE = "route",
+    OPERATIONS = "operations",
+    UID = "uid",
+    TRANSLATABLE = "translatable",
+    MAPPER = "mapper",
+    INITIALIZED = "initialized"
+}

package/dist/lib/engine/decorators.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @description Marks an Angular component as dynamically loadable
+ * @summary Decorator that registers an Angular component with the NgxRenderingEngine2 for dynamic loading.
+ * This decorator must be applied before the @Component decorator to properly extract component metadata.
+ * It adds metadata to the component class and registers it with the rendering engine using its selector.
+ * @function Dynamic
+ * @return {Function} A decorator function that can be applied to Angular component classes
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Component Class
+ *   participant D as Dynamic Decorator
+ *   participant R as NgxRenderingEngine2
+ *   participant M as Angular Metadata
+ *   C->>D: Apply decorator
+ *   D->>M: reflectComponentType()
+ *   M-->>D: Return component metadata
+ *   alt No metadata found
+ *     D->>D: Throw InternalError
+ *   else Metadata found
+ *     D->>R: registerComponent(selector, constructor)
+ *     D->>C: Apply metadata
+ *   end
+ * @category Decorators
+ */
+export declare function Dynamic(): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor) => void;

package/dist/lib/engine/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module engine
+ * @description Angular rendering engine for Decaf applications
+ * @summary The engine module provides core functionality for rendering Angular components
+ * in Decaf applications. It includes constants, decorators, rendering engines, and utility types
+ * that enable dynamic component creation, property mapping, and component lifecycle management.
+ * Key exports include {@link NgxRenderingEngine}, {@link DynamicModule}, and various decorators
+ * for component configuration.
+ */
+export * from './constants';
+export * from './decorators';
+export * from './DynamicModule';
+export * from './NgxRenderingEngine';
+export * from './NgxRenderingEngine2';
+export * from './types';