@decaf-ts/for-angular 0.0.16 → 0.0.17

package/engine/NgxFormService.d.ts

@@ -1,6 +1,8 @@
 import { FieldProperties } from '@decaf-ts/ui-decorators';
-import { ComponentConfig, FieldUpdateMode } from './types';
-import { AbstractControl, FormControl, FormGroup } from '@angular/forms';
+import { FieldUpdateMode } from './types';
+import { IComponentConfig } from './interfaces';
+import { AbstractControl, FormArray, FormControl, FormGroup } from '@angular/forms';
+import { OperationKeys } from '@decaf-ts/db-decorators';
 /**
  * @description Service for managing Angular forms and form controls.
  * @summary The NgxFormService provides utility methods for creating, managing, and validating Angular forms and form controls. It includes functionality for registering forms, adding controls, validating fields, and handling form data.
@@ -40,7 +42,27 @@ import { AbstractControl, FormControl, FormGroup } from '@angular/forms';
  *   NFS-->>C: Return form data
  */
 export declare class NgxFormService {
+    /**
+     * @description WeakMap that stores control properties for form controls.
+     * @summary A WeakMap that associates AbstractControl instances with their corresponding FieldProperties.
+     * This allows the service to track metadata for form controls without creating memory leaks.
+     *
+     * @type {WeakMap<AbstractControl, FieldProperties>}
+     * @private
+     * @static
+     * @memberOf NgxFormService
+     */
     private static controls;
+    /**
+     * @description Registry of form groups indexed by their unique identifiers.
+     * @summary A Map that stores FormGroup instances with their unique string identifiers.
+     * This allows global access to registered forms throughout the application.
+     *
+     * @type {Map<string, FormGroup>}
+     * @private
+     * @static
+     * @memberOf NgxFormService
+     */
     private static formRegistry;
     /**
      * @description Adds a form to the registry.
@@ -65,10 +87,89 @@ export declare class NgxFormService {
      */
     private static resolveParentGroup;
     /**
-     * @description Adds a form control to a form group.
-     * @summary Creates and adds a form control to the specified form group based on the provided component properties.
-     * @param {FormGroup} formGroup - The form group to add the control to.
-     * @param {ComponentInput} componentProps - The properties of the component to create the control from.
+     * @description Retrieves component properties from a FormGroup or FormArray.
+     * @summary Extracts component properties stored in the form group metadata. If a FormGroup is provided
+     * and groupArrayName is specified, it will look for the FormArray within the form structure.
+     *
+     * @param {FormGroup | FormArray} formGroup - The form group or form array to extract properties from
+     * @param {string} [key] - Optional key to retrieve a specific property
+     * @param {string} [groupArrayName] - Optional name of the group array if formGroup is not a FormArray
+     * @return {Partial<FieldProperties>} The component properties or a specific property if key is provided
+     *
+     * @static
+     * @memberOf NgxFormService
+     */
+    static getComponentPropsFromGroupArray(formGroup: FormGroup | FormArray, key?: string, groupArrayName?: string | undefined): Partial<FieldProperties>;
+    /**
+     * @description Adds a new group to a parent FormArray.
+     * @summary Creates and adds a new FormGroup to the specified parent FormArray based on the
+     * component properties stored in the parent's metadata. This is used for dynamic form arrays
+     * where new groups need to be added at runtime.
+     *
+     * @param {FormGroup} formGroup - The root form group containing the parent FormArray
+     * @param {string} parentName - The name of the parent FormArray to add the group to
+     * @param {number} [index=1] - The index position where the new group should be added
+     * @return {FormGroup} The newly created and added FormGroup
+     *
+     * @static
+     * @memberOf NgxFormService
+     */
+    static addGroupToParent(formGroup: FormGroup, parentName: string, index?: number): FormGroup;
+    /**
+     * @description Retrieves a FormGroup from a parent FormArray at the specified index.
+     * @summary Gets a FormGroup from the specified parent FormArray. If the group doesn't exist
+     * at the given index, it will create a new one using addGroupToParent.
+     *
+     * @param {FormGroup} formGroup - The root form group containing the parent FormArray
+     * @param {string} parentName - The name of the parent FormArray to retrieve the group from
+     * @param {number} [index=1] - The index of the group to retrieve
+     * @return {FormGroup} The FormGroup at the specified index
+     *
+     * @static
+     * @memberOf NgxFormService
+     */
+    static getGroupFromParent(formGroup: FormGroup, parentName: string, index?: number): FormGroup;
+    /**
+     * @description Checks if a value is unique within a FormArray group.
+     * @summary Validates that the primary key value in a FormGroup is unique among all groups
+     * in the parent FormArray. The uniqueness check behavior differs based on the operation type.
+     *
+     * @param {FormGroup} formGroup - The FormGroup to check for uniqueness
+     * @param {number} index - The index of the current group within the FormArray
+     * @param {OperationKeys} [operation=OperationKeys.CREATE] - The type of operation being performed
+     * @return {boolean} True if the value is unique, false otherwise
+     *
+     * @static
+     * @memberOf NgxFormService
+     */
+    static isUniqueOnGroup(formGroup: FormGroup, index: number, operation?: OperationKeys): boolean;
+    /**
+     * @description Enables all controls within a FormGroup or FormArray.
+     * @summary Recursively enables all form controls within the provided FormGroup or FormArray.
+     * This is useful for making all controls interactive after they have been disabled.
+     *
+     * @param {FormArray | FormGroup} formGroup - The FormGroup or FormArray to enable all controls for
+     * @return {void}
+     *
+     * @static
+     * @memberOf NgxFormService
+     */
+    static enableAllGroupControls(formGroup: FormArray | FormGroup): void;
+    /**
+     * @description Adds a form control to a form group based on component properties.
+     * @summary Creates and configures a FormControl within the specified FormGroup using the provided
+     * component properties. Handles nested paths, multiple controls (FormArrays), and control registration.
+     * This method supports complex form structures with nested groups and arrays.
+     *
+     * @param {FormGroup} formGroup - The form group to add the control to
+     * @param {IComponentInput} componentProps - The component properties defining the control configuration
+     * @param {KeyValue} [parentProps={}] - Properties from the parent component for context
+     * @param {number} [index=0] - The index for multiple controls in FormArrays
+     * @return {void}
+     *
+     * @private
+     * @static
+     * @memberOf NgxFormService
      */
     private static addFormControl;
     /**
@@ -84,11 +185,11 @@ export declare class NgxFormService {
      * @description Creates a form from component configurations.
      * @summary Generates a FormGroup based on an array of component configurations and optionally registers it.
      * @param {string} id - The unique identifier for the form.
-     * @param {ComponentConfig[]} components - An array of component configurations.
+     * @param {IComponentConfig[]} components - An array of component configurations.
      * @param {boolean} [registry=false] - Whether to register the created form.
      * @return {FormGroup} The created FormGroup.
      */
-    static createFormFromComponents(id: string, components: ComponentConfig[], registry?: boolean): FormGroup;
+    static createFormFromComponents(id: string, components: IComponentConfig[], registry?: boolean): FormGroup;
     /**
      * @description Adds a control to a form based on component properties.
      * @summary Creates and adds a form control to a form (existing or new) based on the provided component properties.
@@ -96,7 +197,7 @@ export declare class NgxFormService {
      * @param {FieldProperties} componentProperties - The properties of the component to create the control from.
      * @return {AbstractControl} The form or created control.
      */
-    static addControlFromProps(id: string, componentProperties: FieldProperties): AbstractControl;
+    static addControlFromProps(id: string, componentProperties: FieldProperties, parentProps?: FieldProperties): AbstractControl;
     /**
      * @description Retrieves form data from a FormGroup.
      * @summary Extracts and processes the data from a FormGroup, handling different input types and nested form groups.
@@ -112,7 +213,7 @@ export declare class NgxFormService {
      * @return {boolean} True if all fields are valid, false otherwise.
      * @throws {Error} If no control is found at the specified path or if the control type is unknown.
      */
-    static validateFields(control: AbstractControl, path?: string): boolean;
+    static validateFields(control: AbstractControl, pk?: string, path?: string): boolean;
     /**
      * @description Generates validators from component properties.
      * @summary Creates an array of ValidatorFn based on the supported validation keys in the component properties.
@@ -134,7 +235,7 @@ export declare class NgxFormService {
      * @param {FormControl} control - The FormControl to get properties for.
      * @return {FieldProperties} The properties associated with the control.
      */
-    static getPropsFromControl(control: FormControl): FieldProperties;
+    static getPropsFromControl(control: FormControl | FormArray | FormGroup): FieldProperties;
     /**
      * @description Finds a parent element with a specific tag.
      * @summary Traverses up the DOM tree to find the nearest parent element with the specified tag.
@@ -163,5 +264,5 @@ export declare class NgxFormService {
      * @summary Recursively resets all controls in a form group, clearing values, errors, and marking them as pristine and untouched.
      * @param {FormGroup} formGroup - The form group to reset.
      */
-    static reset(formGroup: FormGroup): void;
+    static reset(formGroup: FormGroup | FormControl): void;
 }

package/engine/NgxRenderingEngine.d.ts

@@ -1,71 +1,154 @@
-import { RenderingEngine } from '@decaf-ts/ui-decorators';
-import { AngularDynamicOutput, AngularFieldDefinition } from './types';
+import { FieldDefinition, RenderingEngine } from '@decaf-ts/ui-decorators';
+import { AngularFieldDefinition, KeyValue } from './types';
+import { AngularDynamicOutput } from './interfaces';
 import { Constructor, Model } from '@decaf-ts/decorator-validation';
-import { Injector, TemplateRef, ViewContainerRef } from '@angular/core';
+import { ComponentMirror, ComponentRef, Injector, TemplateRef, Type, ViewContainerRef } from '@angular/core';
 /**
- * @description Angular implementation of the RenderingEngine
- * @summary This class extends the base RenderingEngine to provide Angular-specific rendering capabilities.
- * It handles the conversion of field definitions to Angular components and manages component registration.
+ * @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
- * @param {Injector} injector - Angular injector for dependency injection
- * @param {ViewContainerRef} vcr - View container reference for component creation
- * @param {TemplateRef<any>} tpl - Template reference for content projection
+ *
  * @class NgxRenderingEngine
  * @example
  * ```typescript
- * const engine = new NgxRenderingEngine();
+ * const engine = NgxRenderingEngine.get();
  * engine.initialize();
  * const output = engine.render(myModel, {}, viewContainerRef, injector, templateRef);
  * ```
+ *
  * @mermaid
  * sequenceDiagram
  *   participant Client
  *   participant Engine as NgxRenderingEngine
  *   participant Components as RegisteredComponents
  *
- *   Client->>Engine: new NgxRenderingEngine()
+ *   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->>Client: return AngularDynamicOutput
+ *   Engine->>Engine: createComponent(component, inputs, metadata, vcr, injector, template)
+ *   Engine-->>Client: return AngularDynamicOutput
  */
 export declare class NgxRenderingEngine 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;
+    private static _operation;
+    /**
+     * @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 NgxRenderingEngine
+     * @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 NgxRenderingEngine.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: Check input properties
+     *   Method->>Method: Validate input properties
      *   Method->>Method: Create result object
-     *   Method->>Method: Process children if any
+     *   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 {Node[]} [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?: Node[]): 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 converts the model to a field definition using the base RenderingEngine's
-     * toFieldDefinition method, then converts that field definition 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
@@ -73,6 +156,7 @@ export declare class NgxRenderingEngine extends RenderingEngine<AngularFieldDefi
      * @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
@@ -81,6 +165,7 @@ export declare class NgxRenderingEngine extends RenderingEngine<AngularFieldDefi
      *   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)
@@ -91,14 +176,19 @@ export declare class NgxRenderingEngine extends RenderingEngine<AngularFieldDefi
     /**
      * @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.
+     * 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.
+     *
      * @return {Promise<void>} A promise that resolves when initialization is complete
      */
     initialize(): 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 throws an error if a component is already registered under the same name.
+     * 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}
@@ -107,21 +197,56 @@ export declare class NgxRenderingEngine extends RenderingEngine<AngularFieldDefi
     /**
      * @description Retrieves registered components from the rendering engine
      * @summary This static method retrieves either all registered components or a specific component
-     * by its selector. It throws an error if the requested component is not registered.
+     * 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): {
-        constructor: Constructor<unknown>;
-    } | {
-        constructor: Constructor<unknown>;
-    }[];
+    static components(selector?: string): object | string[];
     /**
      * @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.
+     * 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/engine/constants.d.ts

@@ -32,6 +32,7 @@ export declare const AngularEngineKeys: {
     RENDERED_ID: string;
     PARENT: string;
     VALIDATION_PARENT_KEY: symbol;
+    FORM_GROUP_COMPONENT_PROPS: string;
 };
 /**
  * @description Form validation state constants
@@ -59,12 +60,16 @@ export declare const FormConstants: {
  * @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"
-}
+export declare const EventConstants: {
+    BACK_BUTTON_NAVIGATION: string;
+    REFRESH: string;
+    CLICK: string;
+    SUBMIT: string;
+    VALIDATION_ERROR: string;
+    FIELDSET_ADD_GROUP: string;
+    FIELDSET_UPDATE_GROUP: string;
+    FIELDSET_REMOVE_GROUP: string;
+};
 /**
  * @description Logger level constants
  * @summary Enum defining the logging levels used in the application's logging system.

package/engine/decorators.d.ts

@@ -1,6 +1,6 @@
 /**
  * @description Marks an Angular component as dynamically loadable
- * @summary Decorator that registers an Angular component with the NgxRenderingEngine2 for dynamic loading.
+ * @summary Decorator that registers an Angular component with the NgxRenderingEngine 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
@@ -9,7 +9,7 @@
  * sequenceDiagram
  *   participant C as Component Class
  *   participant D as Dynamic Decorator
- *   participant R as NgxRenderingEngine2
+ *   participant R as NgxRenderingEngine
  *   participant M as Angular Metadata
  *   C->>D: Apply decorator
  *   D->>M: reflectComponentType()

package/engine/index.d.ts

@@ -9,8 +9,10 @@
  */
 export * from './constants';
 export * from './decorators';
+export * from './types';
+export * from './interfaces';
 export * from './DynamicModule';
 export * from './NgxRenderingEngine';
-export * from './NgxRenderingEngine2';
-export * from './types';
 export * from './NgxBaseComponent';
+export * from './NgxCrudFormField';
+export * from './NgxFormService';