@decaf-ts/for-angular 0.0.3 → 0.0.5

package/dist/{for-angular → lib}/engine/NgxCrudFormField.d.ts

@@ -1,17 +1,18 @@
-import { CrudFormField } from '@decaf-ts/ui-decorators';
-import { AngularFieldDefinition, FieldUpdateMode } from './types';
+import { FieldProperties } from '@decaf-ts/ui-decorators';
+import { PossibleInputTypes } from './types';
 import { CrudOperations } from '@decaf-ts/db-decorators';
-import { ControlValueAccessor, FormGroup } from '@angular/forms';
+import { ControlValueAccessor, FormControl, FormGroup } from '@angular/forms';
 import { ElementRef } from '@angular/core';
 /**
  * @class NgxCrudFormField
- * @implements {CrudFormField<AngularFieldDefinition>}
+ * @implements {FieldProperties}
  * @implements {ControlValueAccessor}
  * @summary Abstract class representing a CRUD form field for Angular applications
  * @description This class provides the base implementation for CRUD form fields in Angular,
  * implementing both CrudFormField and ControlValueAccessor interfaces.
  */
-export declare abstract class NgxCrudFormField implements CrudFormField<AngularFieldDefinition>, ControlValueAccessor {
+export declare abstract class NgxCrudFormField implements ControlValueAccessor, FieldProperties {
+    protected elementRef: ElementRef;
     /**
      * @summary Reference to the component's element
      * @description ElementRef representing the component's native element
@@ -22,26 +23,35 @@ export declare abstract class NgxCrudFormField implements CrudFormField<AngularF
      * @description Represents the current CRUD operation being performed
      */
     operation: CrudOperations;
-    /**
-     * @summary Field properties
-     * @description Angular-specific field definition properties
-     */
-    props: AngularFieldDefinition;
     /**
      * @summary Form group for the field
      * @description Angular FormGroup instance for the field
      */
-    formGroup: FormGroup;
-    /**
-     * @summary Field name
-     * @description Name of the form field
-     */
+    formGroup: FormGroup | undefined;
+    formControl: FormControl;
     name: string;
-    /**
-     * @summary Field value
-     * @description Current value of the form field
-     */
-    value: string;
+    path: string;
+    childOf?: string;
+    type: PossibleInputTypes;
+    disabled?: boolean;
+    format?: string;
+    hidden?: boolean;
+    max?: number | Date;
+    maxlength?: number;
+    min?: number | Date;
+    minlength?: number;
+    pattern?: string | undefined;
+    readonly?: boolean;
+    required?: boolean;
+    step?: number;
+    equals?: string;
+    different?: string;
+    lessThan?: string;
+    lessThanOrEqual?: string;
+    greaterThan?: string;
+    greaterThanOrEqual?: string;
+    value: string | number | Date;
+    protected constructor(elementRef: ElementRef);
     /**
      * @summary Parent HTML element
      * @description Reference to the parent HTML element of the field
@@ -50,16 +60,19 @@ export declare abstract class NgxCrudFormField implements CrudFormField<AngularF
     /**
      * @summary String formatting function
      * @description Provides access to the sf function for error message formatting
+     * @prop {function(string, ...string): string} sf - String formatting function
      */
     sf: typeof import("@decaf-ts/decorator-validation").stringFormat;
     /**
      * @summary Change callback function
      * @description Function called when the field value changes
+     * @property {function(): unknown} onChange - onChange event handler
      */
     onChange: () => unknown;
     /**
      * @summary Touch callback function
      * @description Function called when the field is touched
+     * @property {function(): unknown} onTouch - onTouch event handler
      */
     onTouch: () => unknown;
     /**
@@ -71,13 +84,13 @@ export declare abstract class NgxCrudFormField implements CrudFormField<AngularF
     /**
      * @summary Register change callback
      * @description Registers a function to be called when the field value changes
-     * @param {() => unknown} fn - The function to be called on change
+     * @param {function(): unknown} fn - The function to be called on change
      */
     registerOnChange(fn: () => unknown): void;
     /**
      * @summary Register touch callback
      * @description Registers a function to be called when the field is touched
-     * @param {() => unknown} fn - The function to be called on touch
+     * @param {function(): unknown} fn - The function to be called on touch
      */
     registerOnTouched(fn: () => unknown): void;
     /**
@@ -97,18 +110,12 @@ export declare abstract class NgxCrudFormField implements CrudFormField<AngularF
      * @description Unregisters the field when the component is destroyed
      */
     onDestroy(): void;
-    /**
-     * @summary Initialize the field
-     * @description Sets up the form group and field name
-     * @param {FieldUpdateMode} updateOn - The update mode for the field
-     */
-    onInit(updateOn: FieldUpdateMode): void;
     /**
      * @summary Get field errors
      * @description Retrieves all errors associated with the field
-     * @returns {{key: string, message: string}[]} An array of error objects
+     * @returns {Array<{key: string, message: string}>} An array of error objects
      */
-    getErrors(): {
+    getErrors(parent: HTMLElement): {
         key: string;
         message: string;
     }[];

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

@@ -0,0 +1,167 @@
+import { FieldProperties } from '@decaf-ts/ui-decorators';
+import { ComponentConfig, FieldUpdateMode } from './types';
+import { AbstractControl, FormControl, FormGroup } from '@angular/forms';
+/**
+ * @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.
+ *
+ * @class
+ * @param {WeakMap<AbstractControl, FieldProperties>} controls - A WeakMap to store control properties.
+ * @param {Map<string, FormGroup>} formRegistry - A Map to store registered forms.
+ *
+ * @example
+ * // Creating a form from components
+ * const components = [
+ *   { inputs: { name: 'username', type: 'text', required: true } },
+ *   { inputs: { name: 'password', type: 'password', minLength: 8 } }
+ * ];
+ * const form = NgxFormService.createFormFromComponents('loginForm', components, true);
+ *
+ * // Validating fields
+ * NgxFormService.validateFields(form);
+ *
+ * // Getting form data
+ * const formData = NgxFormService.getFormData(form);
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Component
+ *   participant NFS as NgxFormService
+ *   participant AF as Angular Forms
+ *   C->>NFS: createFormFromComponents()
+ *   NFS->>AF: new FormGroup()
+ *   NFS->>NFS: addFormControl()
+ *   NFS->>AF: addControl()
+ *   NFS-->>C: Return FormGroup
+ *   C->>NFS: validateFields()
+ *   NFS->>AF: markAsTouched(), markAsDirty(), updateValueAndValidity()
+ *   C->>NFS: getFormData()
+ *   NFS->>AF: Get control values
+ *   NFS-->>C: Return form data
+ */
+export declare class NgxFormService {
+    private static controls;
+    private static formRegistry;
+    /**
+     * @description Adds a form to the registry.
+     * @summary Registers a FormGroup with a unique identifier. Throws an error if the identifier is already in use.
+     * @param {string} formId - The unique identifier for the form.
+     * @param {FormGroup} formGroup - The FormGroup to be registered.
+     * @throws {Error} If a FormGroup with the given id is already registered.
+     */
+    static addRegistry(formId: string, formGroup: FormGroup): void;
+    /**
+     * @description Removes a form from the registry.
+     * @summary Deletes a FormGroup from the registry using its unique identifier.
+     * @param {string} formId - The unique identifier of the form to be removed.
+     */
+    static removeRegistry(formId: string): void;
+    /**
+     * @description Resolves the parent group and control name from a path.
+     * @summary Traverses the form group structure to find the parent group and control name for a given path.
+     * @param {FormGroup} formGroup - The root FormGroup.
+     * @param {string} path - The path to the control.
+     * @return {FormParentGroup} A tuple containing the parent FormGroup and the control name.
+     */
+    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.
+     */
+    private static addFormControl;
+    /**
+     * @description Retrieves a control from a registered form.
+     * @summary Finds and returns an AbstractControl from a registered form using the form id and optional path.
+     * @param {string} formId - The unique identifier of the form.
+     * @param {string} [path] - The path to the control within the form.
+     * @return {AbstractControl} The requested AbstractControl.
+     * @throws {Error} If the form is not found in the registry or the control is not found in the form.
+     */
+    static getControlFromForm(formId: string, path?: string): AbstractControl;
+    /**
+     * @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 {boolean} [registry=false] - Whether to register the created form.
+     * @return {FormGroup} The created FormGroup.
+     */
+    static createFormFromComponents(id: string, components: ComponentConfig[], 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.
+     * @param {string} id - The unique identifier of the form.
+     * @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;
+    /**
+     * @description Retrieves form data from a FormGroup.
+     * @summary Extracts and processes the data from a FormGroup, handling different input types and nested form groups.
+     * @param {FormGroup} formGroup - The FormGroup to extract data from.
+     * @return {Record<string, unknown>} An object containing the form data.
+     */
+    static getFormData(formGroup: FormGroup): Record<string, unknown>;
+    /**
+     * @description Validates fields in a form control or form group.
+     * @summary Recursively validates all fields in a form control or form group, marking them as touched and dirty.
+     * @param {AbstractControl} control - The control or form group to validate.
+     * @param {string} [path] - The path to the control within the form.
+     * @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;
+    /**
+     * @description Generates validators from component properties.
+     * @summary Creates an array of ValidatorFn based on the supported validation keys in the component properties.
+     * @param {FieldProperties} props - The component properties.
+     * @return {ValidatorFn[]} An array of validator functions.
+     */
+    private static validatorsFromProps;
+    /**
+     * @description Creates a FormControl from component properties.
+     * @summary Generates a FormControl with validators based on the provided component properties.
+     * @param {FieldProperties} props - The component properties.
+     * @param {FieldUpdateMode} [updateMode='change'] - The update mode for the control.
+     * @return {FormControl} The created FormControl.
+     */
+    static fromProps(props: FieldProperties, updateMode?: FieldUpdateMode): FormControl;
+    /**
+     * @description Retrieves properties from a FormControl.
+     * @summary Gets the FieldProperties associated with a FormControl from the internal WeakMap.
+     * @param {FormControl} control - The FormControl to get properties for.
+     * @return {FieldProperties} The properties associated with the control.
+     */
+    static getPropsFromControl(control: FormControl): 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.
+     * @param {HTMLElement} el - The starting element.
+     * @param {string} tag - The tag name to search for.
+     * @return {HTMLElement} The found parent element.
+     * @throws {Error} If no parent with the specified tag is found.
+     */
+    static getParentEl(el: HTMLElement, tag: string): HTMLElement;
+    /**
+     * @description Registers a control with its properties.
+     * @summary Associates a control with its properties in the internal WeakMap.
+     * @param {AbstractControl} control - The control to register.
+     * @param {FieldProperties} props - The properties to associate with the control.
+     */
+    static register(control: AbstractControl, props: FieldProperties): void;
+    /**
+     * @description Unregisters a control.
+     * @summary Removes a control and its associated properties from the internal WeakMap.
+     * @param {AbstractControl} control - The control to unregister.
+     * @return {boolean} True if the control was successfully unregistered, false otherwise.
+     */
+    static unregister(control: AbstractControl): boolean;
+    /**
+     * @description Resets a form group.
+     * @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;
+}

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

@@ -0,0 +1,128 @@
+import { RenderingEngine } from '@decaf-ts/ui-decorators';
+import { AngularDynamicOutput, AngularFieldDefinition } from './types';
+import { Constructor, Model } from '@decaf-ts/decorator-validation';
+import { Injector, TemplateRef, 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.
+ * @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();
+ * 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: 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
+ */
+export declare class NgxRenderingEngine extends RenderingEngine<AngularFieldDefinition, AngularDynamicOutput> {
+    private static _components;
+    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.
+     * @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
+     * @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
+     *
+     *   Method->>Components: components(fieldDef.tag)
+     *   Components-->>Method: component constructor
+     *   Method->>Angular: reflectComponentType(component)
+     *   Angular-->>Method: componentMetadata
+     *   Method->>Method: Check input properties
+     *   Method->>Method: Create result object
+     *   Method->>Method: Process children if any
+     *   Method-->>Caller: return AngularDynamicOutput
+     */
+    private fromFieldDefinition;
+    /**
+     * @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.
+     * @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->>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.
+     * @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 throws an error if a component is already registered under the same name.
+     * @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. It throws an error if the requested 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>;
+    }[];
+    /**
+     * @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.
+     * @param {string} key - The base key to prefix
+     * @return {string} The prefixed key for reflection metadata
+     */
+    static key(key: string): string;
+}