@decaf-ts/for-angular 0.0.16 → 0.0.18

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';

package/engine/interfaces.d.ts

@@ -0,0 +1,271 @@
+import { FormArray, FormControl, FormGroup } from '@angular/forms';
+import { ElementRef, EnvironmentInjector, Injector, Type } from '@angular/core';
+import { OrderDirection } from '@decaf-ts/core';
+import { AngularFieldDefinition, FieldUpdateMode, KeyValue, StringOrBoolean } from './types';
+import { FieldProperties } from '@decaf-ts/ui-decorators';
+/**
+ * @description Interface for components that hold an ElementRef
+ * @summary Defines a component holder interface that provides access to the underlying DOM element through ElementRef
+ * @interface IComponentHolder
+ * @memberOf module:engine
+ */
+export interface IComponentHolder {
+    /**
+     * @description Reference to the component's DOM element
+     * @property {ElementRef} component - The ElementRef instance providing access to the native DOM element
+     */
+    component: ElementRef;
+}
+/**
+ * @description Interface for form components that hold both an ElementRef and a FormGroup
+ * @summary Extends IComponentHolder to include a FormGroup for form handling capabilities
+ * @interface IFormElement
+ * @memberOf module:engine
+ */
+export interface IFormElement extends IComponentHolder {
+    /**
+     * @description The Angular FormGroup associated with this form element
+     * @property {FormGroup|undefined} formGroup - The form group instance for managing form controls and validation
+     */
+    formGroup: FormGroup | undefined;
+}
+/**
+ * @description Interface for fieldset item representation in the UI.
+ * @summary Defines the structure for items displayed in the reorderable list within the fieldset.
+ * Each item represents a value added to the fieldset with display properties for the UI.
+ * @memberOf module:engine
+ */
+export interface IFieldSetItem {
+    /** @description Sequential index number for ordering items in the list */
+    index: number;
+    /** @description Primary display text for the item */
+    title: string;
+    /** @description Optional secondary text providing additional item details */
+    description?: string;
+}
+/**
+ * @description Interface for fieldset validation event data.
+ * @summary Defines the structure of validation events emitted when form validation occurs.
+ * Used for communication between form components and the fieldset container.
+ * @memberOf module:engine
+ */
+export interface IFieldSetValidationEvent {
+    /** @description The FormGroup containing the validated form controls */
+    formGroup: FormArray | FormGroup;
+    /** @description The current form value being validated */
+    value: unknown;
+    /** @description Whether the form validation passed or failed */
+    isValid: boolean;
+}
+/**
+ * @description Interface for individual filter query items
+ * @summary Defines the structure of a single filter criterion in a filter query.
+ * Each item represents one condition to be applied to the data, consisting of
+ * an index (field name), a condition (comparison operator), and a value to compare against.
+ * @interface IFilterQueryItem
+ * @property {string} [index] - Optional field name or index to filter on
+ * @property {string} [condition] - Optional comparison condition (e.g., 'Equal', 'Contains', 'Greater Than')
+ * @property {string} [value] - Optional value to compare the field against
+ * @memberOf module:engine
+ */
+export interface IFilterQueryItem {
+    index?: string;
+    condition?: string;
+    value?: string;
+}
+/**
+ * @description Interface for sorting configuration objects
+ * @summary Defines the structure for specifying sort criteria including the field
+ * to sort by and the direction of the sort (ascending or descending).
+ * @interface ISortObject
+ * @property {string} value - The field name or property to sort by
+ * @property {OrderDirection} direction - The sort direction (ASC or DSC)
+ * @memberOf module:engine
+ */
+export interface ISortObject {
+    value: string;
+    direction: OrderDirection;
+}
+/**
+ * @description Interface for complete filter query configuration
+ * @summary Defines the complete structure for filter and sort operations.
+ * Combines multiple filter criteria with sorting configuration to provide
+ * comprehensive data filtering and ordering capabilities.
+ * @interface IFilterQuery
+ * @property {IFilterQueryItem[] | undefined} query - Array of filter criteria or undefined for no filtering
+ * @property {ISortObject} sort - Sorting configuration specifying field and direction
+ * @memberOf module:engine
+ */
+export interface IFilterQuery {
+    query: IFilterQueryItem[] | undefined;
+    sort: ISortObject;
+}
+/**
+ * @description Component input properties
+ * @summary Extends FieldProperties with additional properties specific to Angular components.
+ * Includes update mode for form controls and optional FormGroup and FormControl references.
+ * @interface IComponentInput
+ * @property {FieldUpdateMode} [updateMode] - When the field value should be updated
+ * @property {FormGroup} [formGroup] - Optional FormGroup reference
+ * @property {FormControl} [formControl] - Optional FormControl reference
+ * @memberOf module:engine
+ */
+export interface IComponentInput extends FieldProperties {
+    updateMode?: FieldUpdateMode;
+    formGroup?: FormGroup;
+    formControl?: FormControl;
+}
+/**
+ * @description Component configuration structure
+ * @summary Defines the configuration for dynamically creating Angular components.
+ * Contains the component name, input properties, injector, and optional child components.
+ * @interface IComponentConfig
+ * @property {string} component - The name of the component to render
+ * @property {IComponentInput} inputs - The input properties for the component
+ * @property {EnvironmentInjector | Injector} injector - The Angular injector for dependency injection
+ * @property {IComponentConfig[]} [children] - Optional child component configurations
+ * @memberOf module:engine
+ */
+export interface IComponentConfig {
+    component: string;
+    inputs: IComponentInput;
+    injector: EnvironmentInjector | Injector;
+    children?: IComponentConfig[];
+}
+/**
+ * @description Metadata structure for Angular components
+ * @summary Defines the structure of metadata for Angular components, including
+ * change detection strategy, selector, standalone status, imports, template, and styles.
+ * This is used for reflection and dynamic component creation.
+ * @interface ComponentMetadata
+ * @property {number} changeDetection - The change detection strategy number
+ * @property {string} selector - The CSS selector for the component
+ * @property {boolean} standalone - Whether the component is standalone
+ * @property imports - Array of imported modules/components
+ * @property {string} template - The HTML template for the component
+ * @property {string[]} styles - Array of CSS styles for the component
+ * @memberOf module:engine
+ */
+export interface ComponentMetadata {
+    changeDetection: number;
+    selector: string;
+    standalone: boolean;
+    imports: (new (...args: unknown[]) => unknown)[];
+    template: string;
+    styles: string[];
+}
+/**
+ * @description Output structure from the Angular rendering engine
+ * @summary Defines the structure of the output produced by the NgxRenderingEngine
+ * when rendering a component. Contains the component type, inputs, injector,
+ * content nodes, and child components.
+ * @typedef {Object} AngularDynamicOutput
+ * @property {Type<unknown>} component - The Angular component type
+ * @property {string} [rendererId] - Optional unique ID for the rendered component
+ * @property {Record<string, unknown>} [inputs] - Optional input properties for the component
+ * @property {Injector} [injector] - Optional Angular injector for dependency injection
+ * @property {Node[][]} [content] - Optional content nodes for projection
+ * @property {AngularDynamicOutput[]} [children] - Optional child components
+ * @property {Type<unknown>} [instance] - Optional component instance
+ * @property {FormGroup} [formGroup] - Optional component FormGroup
+ * @property {FormControl} [formControl] - Optional component FormControl
+ * @memberOf module:engine
+ */
+export interface AngularDynamicOutput {
+    component?: Type<unknown>;
+    rendererId?: string;
+    inputs?: Record<string, unknown>;
+    injector?: Injector;
+    content?: Node[][];
+    children?: AngularDynamicOutput[];
+    instance?: Type<unknown>;
+    formGroup?: FormGroup;
+    formControl?: FormControl;
+}
+/**
+ * @description Base option type for input components
+ * @summary Defines the common structure for options used in select, radio, and checkbox inputs.
+ * Contains properties for the display text, value, disabled state, CSS class, and icon.
+ * @interface InputOption
+ * @property {string} text - The display text for the option
+ * @property {string|number} value - The value associated with the option
+ * @property {StringOrBoolean} [disabled] - Whether the option is disabled
+ * @property {string} [className] - CSS class name for styling the option
+ * @property {string} [icon] - Icon to display with the option
+ * @memberOf module:engine
+ */
+export interface InputOption {
+    text: string;
+    value: string | number;
+    disabled?: StringOrBoolean;
+    className?: string;
+    icon?: string;
+}
+/**
+ * @description Interface for list component refresh events
+ * @summary Defines the structure of a refresh event for list components.
+ * Contains an array of key-value pairs representing the new data for the list.
+ * @interface IListComponentRefreshEvent
+ * @property {KeyValue[]} data - Array of key-value pairs representing the new data
+ * @memberOf module:engine
+ */
+export interface IListComponentRefreshEvent {
+    data: KeyValue[];
+}
+/**
+ * @description Form service control structure
+ * @summary Defines the structure for a form control managed by the form service.
+ * Contains the FormGroup control and the associated field properties for rendering.
+ * @interface FormServiceControl
+ * @property {FormGroup} control - The Angular FormGroup for the control
+ * @property {AngularFieldDefinition} props - The field properties for rendering the control
+ * @memberOf module:engine
+ */
+export interface FormServiceControl {
+    control: FormGroup;
+    props: AngularFieldDefinition;
+}
+/**
+ * @description Interface for list item custom events
+ * @summary Defines the structure of custom events triggered by list items.
+ * Extends BaseCustomEvent with additional properties for the action and primary key.
+ * @interface ListItemCustomEvent
+ * @property {string} action - The action performed on the list item
+ * @property {string} [pk] - Optional primary key of the affected item
+ * @property {any} data - The data associated with the event (inherited from BaseCustomEvent)
+ * @property {HTMLElement} [target] - The target element (inherited from BaseCustomEvent)
+ * @property {string} [name] - The name of the event (inherited from BaseCustomEvent)
+ * @property {string} component - The component that triggered the event (inherited from BaseCustomEvent)
+ * @memberOf module:engine
+ */
+export interface ListItemCustomEvent extends BaseCustomEvent {
+    action: string;
+    pk?: string;
+}
+/**
+ * @description Base interface for custom events
+ * @summary Defines the base structure for custom events in the application.
+ * Contains properties for the event data, target element, name, and component.
+ * @interface BaseCustomEvent
+ * @property {any} data - The data associated with the event
+ * @property {HTMLElement} [target] - The target element that triggered the event
+ * @property {string} [name] - The name of the event
+ * @property {string} component - The component that triggered the event
+ * @memberOf module:engine
+ */
+export interface BaseCustomEvent {
+    name: string;
+    component: string;
+    data?: unknown;
+    target?: HTMLElement;
+}
+/**
+ * Configuration for internationalization (i18n) resource file paths.
+ *
+ * @property prefix - The prefix to be used for the resource file path.
+ * @property suffix - The suffix to be appended to the resource file path.
+ */
+export interface I18nResourceConfig {
+    prefix: string;
+    suffix: string;
+}

package/engine/types.d.ts

@@ -1,9 +1,8 @@
 import { IonCheckbox, IonInput, IonSelect, IonTextarea } from '@ionic/angular';
 import { TextFieldTypes } from '@ionic/core';
-import { EnvironmentInjector, Injector, Type } from '@angular/core';
-import { FormControl, FormGroup } from '@angular/forms';
-import { FieldProperties } from '@decaf-ts/ui-decorators';
-import { OrderDirection } from '@decaf-ts/core';
+import { FormGroup } from '@angular/forms';
+import { BaseCustomEvent, FormServiceControl, InputOption } from './interfaces';
+export type HandlerLike = Record<string, (...args: unknown[]) => unknown | Promise<unknown>>;
 /**
  * @description Generic key-value pair type
  * @summary Represents a generic object with string keys and any type of values.
@@ -55,56 +54,6 @@ export type FlexPositions = ElementPositions | 'stretch' | 'middle' | 'around' |
  * @memberOf module:engine
  */
 export type FieldUpdateMode = 'change' | 'blur' | 'submit';
-/**
- * @description Metadata structure for Angular components
- * @summary Defines the structure of metadata for Angular components, including
- * change detection strategy, selector, standalone status, imports, template, and styles.
- * This is used for reflection and dynamic component creation.
- * @interface ComponentMetadata
- * @property {number} changeDetection - The change detection strategy number
- * @property {string} selector - The CSS selector for the component
- * @property {boolean} standalone - Whether the component is standalone
- * @property imports - Array of imported modules/components
- * @property {string} template - The HTML template for the component
- * @property {string[]} styles - Array of CSS styles for the component
- * @memberOf module:engine
- */
-export interface ComponentMetadata {
-    changeDetection: number;
-    selector: string;
-    standalone: boolean;
-    imports: (new (...args: unknown[]) => unknown)[];
-    template: string;
-    styles: string[];
-}
-/**
- * @description Output structure from the Angular rendering engine
- * @summary Defines the structure of the output produced by the NgxRenderingEngine
- * when rendering a component. Contains the component type, inputs, injector,
- * content nodes, and child components.
- * @typedef {Object} AngularDynamicOutput
- * @property {Type<unknown>} component - The Angular component type
- * @property {string} [rendererId] - Optional unique ID for the rendered component
- * @property {Record<string, unknown>} [inputs] - Optional input properties for the component
- * @property {Injector} [injector] - Optional Angular injector for dependency injection
- * @property {Node[][]} [content] - Optional content nodes for projection
- * @property {AngularDynamicOutput[]} [children] - Optional child components
- * @property {Type<unknown>} [instance] - Optional component instance
- * @property {FormGroup} [formGroup] - Optional component FormGroup
- * @property {FormControl} [formControl] - Optional component FormControl
- * @memberOf module:engine
- */
-export interface AngularDynamicOutput {
-    component: Type<unknown>;
-    rendererId?: string;
-    inputs?: Record<string, unknown>;
-    injector?: Injector;
-    content?: Node[][];
-    children?: AngularDynamicOutput[];
-    instance?: Type<unknown>;
-    formGroup?: FormGroup;
-    formControl?: FormControl;
-}
 /**
  * @description Interface for models that can be rendered
  * @summary Defines the basic structure for models that can be rendered by the engine.
@@ -157,6 +106,14 @@ export type AngularFieldDefinition = Omit<IonInput, 'ionInput' | 'ionFocus' | 'i
  * @memberOf module:engine
  */
 export type StringOrBoolean = 'true' | 'false' | boolean;
+/**
+ * @description Option type for CRUD field inputs
+ * @summary Represents a union type that can be either a SelectOption or RadioOption.
+ * This is used for defining options in form fields that support both select and radio input types.
+ * @typedef {(SelectOption|RadioOption)} CrudFieldOption
+ * @memberOf module:engine
+ */
+export type CrudFieldOption = SelectOption | RadioOption;
 /**
  * @description Option type for select inputs
  * @summary Extends the InputOption interface with a selected property to indicate
@@ -182,25 +139,6 @@ export type RadioOption = InputOption & {
  * @memberOf module:engine
  */
 export type CheckboxOption = RadioOption;
-/**
- * @description Base option type for input components
- * @summary Defines the common structure for options used in select, radio, and checkbox inputs.
- * Contains properties for the display text, value, disabled state, CSS class, and icon.
- * @interface InputOption
- * @property {string} text - The display text for the option
- * @property {string|number} value - The value associated with the option
- * @property {StringOrBoolean} [disabled] - Whether the option is disabled
- * @property {string} [className] - CSS class name for styling the option
- * @property {string} [icon] - Icon to display with the option
- * @memberOf module:engine
- */
-export interface InputOption {
-    text: string;
-    value: string | number;
-    disabled?: StringOrBoolean;
-    className?: string;
-    icon?: string;
-}
 /**
  * @description Target options for HTML forms
  * @summary Defines the possible target values for HTML forms, including standard targets
@@ -209,30 +147,6 @@ export interface InputOption {
  * @memberOf module:engine
  */
 export type HTMLFormTarget = '_blank' | '_self' | '_parent' | '_top' | string;
-/**
- * @description Interface for list component refresh events
- * @summary Defines the structure of a refresh event for list components.
- * Contains an array of key-value pairs representing the new data for the list.
- * @interface IListComponentRefreshEvent
- * @property {KeyValue[]} data - Array of key-value pairs representing the new data
- * @memberOf module:engine
- */
-export interface IListComponentRefreshEvent {
-    data: KeyValue[];
-}
-/**
- * @description Form service control structure
- * @summary Defines the structure for a form control managed by the form service.
- * Contains the FormGroup control and the associated field properties for rendering.
- * @interface FormServiceControl
- * @property {FormGroup} control - The Angular FormGroup for the control
- * @property {AngularFieldDefinition} props - The field properties for rendering the control
- * @memberOf module:engine
- */
-export interface FormServiceControl {
-    control: FormGroup;
-    props: AngularFieldDefinition;
-}
 /**
  * @description Type for form service controls
  * @summary Defines the structure of form controls managed by the form service.
@@ -251,40 +165,6 @@ export type FormServiceControls = Record<string, Record<string, FormServiceContr
  * @memberOf module:engine
  */
 export type RendererCustomEvent = BaseCustomEvent & KeyValue;
-/**
- * @description Interface for list item custom events
- * @summary Defines the structure of custom events triggered by list items.
- * Extends BaseCustomEvent with additional properties for the action and primary key.
- * @interface ListItemCustomEvent
- * @property {string} action - The action performed on the list item
- * @property {string} [pk] - Optional primary key of the affected item
- * @property {any} data - The data associated with the event (inherited from BaseCustomEvent)
- * @property {HTMLElement} [target] - The target element (inherited from BaseCustomEvent)
- * @property {string} [name] - The name of the event (inherited from BaseCustomEvent)
- * @property {string} component - The component that triggered the event (inherited from BaseCustomEvent)
- * @memberOf module:engine
- */
-export interface ListItemCustomEvent extends BaseCustomEvent {
-    action: string;
-    pk?: string;
-}
-/**
- * @description Base interface for custom events
- * @summary Defines the base structure for custom events in the application.
- * Contains properties for the event data, target element, name, and component.
- * @interface BaseCustomEvent
- * @property {any} data - The data associated with the event
- * @property {HTMLElement} [target] - The target element that triggered the event
- * @property {string} [name] - The name of the event
- * @property {string} component - The component that triggered the event
- * @memberOf module:engine
- */
-export interface BaseCustomEvent {
-    name: string;
-    component: string;
-    data?: unknown;
-    target?: HTMLElement;
-}
 /**
  * @description CRUD form event type
  * @summary Extends BaseCustomEvent to include optional handlers for CRUD form operations.
@@ -296,38 +176,6 @@ export interface BaseCustomEvent {
 export type CrudFormEvent = BaseCustomEvent & {
     handlers?: Record<string, any>;
 };
-/**
- * @description Component input properties
- * @summary Extends FieldProperties with additional properties specific to Angular components.
- * Includes update mode for form controls and optional FormGroup and FormControl references.
- * @interface ComponentInput
- * @property {FieldUpdateMode} [updateMode] - When the field value should be updated
- * @property {FormGroup} [formGroup] - Optional FormGroup reference
- * @property {FormControl} [formControl] - Optional FormControl reference
- * @memberOf module:engine
- */
-export interface ComponentInput extends FieldProperties {
-    updateMode?: FieldUpdateMode;
-    formGroup?: FormGroup;
-    formControl?: FormControl;
-}
-/**
- * @description Component configuration structure
- * @summary Defines the configuration for dynamically creating Angular components.
- * Contains the component name, input properties, injector, and optional child components.
- * @interface ComponentConfig
- * @property {string} component - The name of the component to render
- * @property {ComponentInput} inputs - The input properties for the component
- * @property {EnvironmentInjector | Injector} injector - The Angular injector for dependency injection
- * @property {ComponentConfig[]} [children] - Optional child component configurations
- * @memberOf module:engine
- */
-export interface ComponentConfig {
-    component: string;
-    inputs: ComponentInput;
-    injector: EnvironmentInjector | Injector;
-    children?: ComponentConfig[];
-}
 /**
  * @description Form parent group tuple
  * @summary Represents a tuple containing a FormGroup and its associated string identifier.
@@ -336,46 +184,3 @@ export interface ComponentConfig {
  * @memberOf module:engine
  */
 export type FormParentGroup = [FormGroup, string];
-/**
- * @description Interface for individual filter query items
- * @summary Defines the structure of a single filter criterion in a filter query.
- * Each item represents one condition to be applied to the data, consisting of
- * an index (field name), a condition (comparison operator), and a value to compare against.
- * @interface IFilterQueryItem
- * @property {string} [index] - Optional field name or index to filter on
- * @property {string} [condition] - Optional comparison condition (e.g., 'Equal', 'Contains', 'Greater Than')
- * @property {string} [value] - Optional value to compare the field against
- * @memberOf module:engine
- */
-export interface IFilterQueryItem {
-    index?: string;
-    condition?: string;
-    value?: string;
-}
-/**
- * @description Interface for sorting configuration objects
- * @summary Defines the structure for specifying sort criteria including the field
- * to sort by and the direction of the sort (ascending or descending).
- * @interface ISortObject
- * @property {string} value - The field name or property to sort by
- * @property {OrderDirection} direction - The sort direction (ASC or DSC)
- * @memberOf module:engine
- */
-export interface ISortObject {
-    value: string;
-    direction: OrderDirection;
-}
-/**
- * @description Interface for complete filter query configuration
- * @summary Defines the complete structure for filter and sort operations.
- * Combines multiple filter criteria with sorting configuration to provide
- * comprehensive data filtering and ordering capabilities.
- * @interface IFilterQuery
- * @property {IFilterQueryItem[] | undefined} query - Array of filter criteria or undefined for no filtering
- * @property {ISortObject} sort - Sorting configuration specifying field and direction
- * @memberOf module:engine
- */
-export interface IFilterQuery {
-    query: IFilterQueryItem[] | undefined;
-    sort: ISortObject;
-}