@decaf-ts/for-angular 0.0.4 → 0.0.6

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

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

@@ -0,0 +1,294 @@
+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';
+export type KeyValue = Record<string, any>;
+export type FunctionLike = (...args: any[]) => any;
+/**
+ * @description Element size options for UI components
+ * @summary Defines the possible size values that can be applied to UI elements.
+ * These sizes control the dimensions and layout behavior of components.
+ * @typedef {('small'|'medium'|'large'|'xlarge'|'2xlarge'|'auto'|'expand'|'block')} ElementSizes
+ * @memberOf module:engine
+ */
+export type ElementSizes = 'small' | 'medium' | 'large' | 'xlarge' | '2xlarge' | 'auto' | 'expand' | 'block';
+/**
+ * @description Basic position options for UI elements
+ * @summary Defines the possible position values that can be applied to UI elements.
+ * These positions control the alignment and placement of components.
+ * @typedef {('left'|'center'|'right'|'top'|'bottom')} ElementPositions
+ * @memberOf module:engine
+ */
+export type ElementPositions = 'left' | 'center' | 'right' | 'top' | 'bottom';
+/**
+ * @description Extended position options for flex layouts
+ * @summary Extends the basic ElementPositions with additional flex-specific position values.
+ * These positions are used for controlling alignment and distribution in flex containers.
+ * @typedef {(ElementPositions|'stretch'|'middle'|'around'|'between')} FlexPositions
+ * @memberOf module:engine
+ */
+export type FlexPositions = ElementPositions | 'stretch' | 'middle' | 'around' | 'between';
+/**
+ * @description Update mode options for form fields
+ * @summary Defines when form field values should be updated in the model.
+ * - 'change': Update on every change event
+ * - 'blur': Update when the field loses focus
+ * - 'submit': Update only when the form is submitted
+ * @typedef {('change'|'blur'|'submit')} FieldUpdateMode
+ * @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.
+ * Contains an optional rendererId that uniquely identifies the rendered instance.
+ * @interface RenderedModel
+ * @property {string} [rendererId] - Optional unique ID for the rendered model instance
+ * @memberOf module:engine
+ */
+export interface RenderedModel {
+    rendererId?: string;
+}
+/**
+ * @description Possible input types for form fields
+ * @summary Defines the possible input types that can be used in form fields.
+ * Includes standard HTML input types like checkbox, radio, and select,
+ * as well as Ionic's TextFieldTypes and textarea.
+ * @typedef {('checkbox'|'radio'|'select'|TextFieldTypes|'textarea')} PossibleInputTypes
+ * @memberOf module:engine
+ */
+export type PossibleInputTypes = 'checkbox' | 'radio' | 'select' | TextFieldTypes | 'textarea';
+/**
+ * @description Field definition for Angular components
+ * @summary A comprehensive type that combines properties from various Ionic components
+ * to define the structure of a field in an Angular form. It omits certain properties
+ * from IonInput, picks specific properties from IonSelect, IonTextarea, and IonCheckbox,
+ * and adds custom properties like type and className.
+ * @typedef {Object} AngularFieldDefinition
+ * @property {PossibleInputTypes} type - The type of input field
+ * @property {string|string[]} className - CSS class name(s) for the field
+ * @property {string} [cancelText] - Text for the cancel button (from IonSelect)
+ * @property {string} [interface] - Interface style for select (from IonSelect)
+ * @property {string} [selectedText] - Text for selected option (from IonSelect)
+ * @property {Object} [interfaceOptions] - Options for the interface (from IonSelect)
+ * @property {number} [rows] - Number of rows for textarea (from IonTextarea)
+ * @property {number} [cols] - Number of columns for textarea (from IonTextarea)
+ * @property {string} [alignment] - Alignment of checkbox (from IonCheckbox)
+ * @property {string} [justify] - Justification of checkbox (from IonCheckbox)
+ * @property {boolean} [checked] - Whether checkbox is checked (from IonCheckbox)
+ * @memberOf module:engine
+ */
+export type AngularFieldDefinition = Omit<IonInput, 'ionInput' | 'ionFocus' | 'ionChange' | 'ionBlur' | 'getInputElement' | 'setFocus' | 'label' | 'el' | 'z' | 'type'> & Pick<IonSelect, 'cancelText' | 'interface' | 'selectedText' | 'interfaceOptions'> & Pick<IonTextarea, 'rows' | 'cols'> & Pick<IonCheckbox, 'alignment' | 'justify' | 'checked'> & {
+    type: PossibleInputTypes;
+    className: string | string[];
+} & Record<string, unknown>;
+/**
+ * @description String or boolean representation of a boolean value
+ * @summary Represents a value that can be either a boolean or a string representation of a boolean.
+ * This is useful for handling attribute values that can be specified as either strings or booleans.
+ * @typedef {('true'|'false'|boolean)} StringOrBoolean
+ * @memberOf module:engine
+ */
+export type StringOrBoolean = 'true' | 'false' | boolean;
+/**
+ * @description Option type for select inputs
+ * @summary Extends the InputOption interface with a selected property to indicate
+ * whether the option is selected by default.
+ * @memberOf module:engine
+ */
+export type SelectOption = InputOption & {
+    selected?: boolean;
+};
+/**
+ * @description Option type for radio inputs
+ * @summary Extends the InputOption interface with a checked property to indicate
+ * whether the option is checked by default.
+ * @memberOf module:engine
+ */
+export type RadioOption = InputOption & {
+    checked?: boolean;
+};
+/**
+ * @description Option type for checkbox inputs
+ * @summary Alias for RadioOption, as checkbox options have the same structure as radio options.
+ * @typedef {RadioOption} CheckboxOption
+ * @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
+ * like '_blank', '_self', '_parent', and '_top', as well as custom string values.
+ * @typedef {('_blank'|'_self'|'_parent'|'_top'|string)} HTMLFormTarget
+ * @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[];
+}
+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.
+ * It's a nested record where the outer key is the form group name, the inner key
+ * is the control name, and the value contains the form group and field properties.
+ * @typedef {Record<string, Record<string, { control: FormGroup; props: AngularFieldDefinition }>>} FormServiceControls
+ * @memberOf module:engine
+ */
+export type FormServiceControls = Record<string, Record<string, FormServiceControl>>;
+/**
+ * @description Interface for model render custom events
+ * @summary Defines the structure of custom events triggered during model rendering.
+ * Contains the event detail, component name, and event name.
+ * @interface ModelRenderCustomEvent
+ * @property {BaseCustomEvent} detail - The detailed event information
+ * @property {string} component - The component that triggered the event
+ * @property {string} name - The name of the event
+ * @memberOf module:engine
+ */
+export interface ModelRenderCustomEvent {
+    detail: BaseCustomEvent;
+    component: string;
+    name: string;
+}
+/**
+ * @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 {
+    data: unknown;
+    target?: HTMLElement;
+    name?: string;
+    component: 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 type CrudFormEvent = BaseCustomEvent & {
+    handlers?: Record<string, any>;
+};
+export interface ComponentInput extends FieldProperties {
+    updateMode?: FieldUpdateMode;
+    formGroup?: FormGroup;
+    formControl?: FormControl;
+}
+export interface ComponentConfig {
+    component: string;
+    inputs: ComponentInput;
+    injector: EnvironmentInjector | Injector;
+    children?: ComponentConfig[];
+}
+export type FormParentGroup = [FormGroup, string];