@decaf-ts/for-angular 0.0.16 → 0.0.18

package/helpers/utils.d.ts

@@ -152,22 +152,7 @@ export declare function isNotUndefined(prop: StringOrBoolean | undefined): boole
  * @function getLocaleFromClassName
  * @memberOf module:for-angular
  */
-export declare function getLocaleFromClassName(instance: string | FunctionLike | object, suffix?: string): string;
-/**
- * @description Generates a localized string by combining locale and phrase
- * @summary This utility function creates a properly formatted locale string by combining
- * a locale identifier with a phrase. It handles edge cases such as empty phrases,
- * missing locales, and phrases that already include the locale prefix. This function
- * is useful for ensuring consistent formatting of localized strings throughout the application.
- *
- * @param {string} locale - The locale identifier (e.g., 'en', 'fr')
- * @param {string | undefined} phrase - The phrase to localize
- * @return {string} The formatted locale string, or empty string if phrase is undefined
- *
- * @function generateLocaleFromString
- * @memberOf module:for-angular
- */
-export declare function generateLocaleFromString(locale: string, phrase: string | undefined): string;
+export declare function getLocaleFromClassName(instance: string | FunctionLike | KeyValue, suffix?: string): string;
 /**
  * @description Retrieves the current locale language
  * @summary This utility function gets the current locale language based on the user's browser settings.
@@ -250,4 +235,45 @@ export declare function itemMapper(item: KeyValue, mapper: KeyValue, props?: Key
  * the original item is returned instead.
  */
 export declare function dataMapper<T>(data: T[], mapper: KeyValue, props?: KeyValue): T[];
+/**
+ * @description Removes focus from the currently active DOM element
+ * @summary This utility function blurs the currently focused element in the document,
+ * effectively removing focus traps that might prevent proper navigation or keyboard
+ * interaction. It safely accesses the document's activeElement and calls blur() if
+ * an element is currently focused. This is useful for accessibility and user experience
+ * improvements, particularly when closing modals or dialogs.
+ *
+ * @return {void}
+ *
+ * @function removeFocusTrap
+ * @memberOf module:for-angular
+ */
 export declare function removeFocusTrap(): void;
+/**
+ * @description Cleans and normalizes whitespace in a string value
+ * @summary This utility function trims leading and trailing whitespace from a string
+ * and replaces multiple consecutive whitespace characters with a single space.
+ * Optionally converts the result to lowercase for consistent text processing.
+ * This is useful for normalizing user input, search terms, or data sanitization.
+ *
+ * @param {string} value - The string value to clean and normalize
+ * @param {boolean} [lowercase=false] - Whether to convert the result to lowercase
+ * @return {string} The cleaned and normalized string
+ *
+ * @function cleanSpaces
+ * @memberOf module:for-angular
+ */
+export declare function cleanSpaces(value?: string, lowercase?: boolean): string;
+/**
+ * @description Determines if the user's system is currently in dark mode
+ * @summary This function checks the user's color scheme preference using the CSS media query
+ * '(prefers-color-scheme: dark)'. It returns a boolean indicating whether the system is
+ * currently set to dark mode. This is useful for implementing theme-aware functionality
+ * and adjusting UI elements based on the user's preferred color scheme.
+ *
+ * @return {Promise<boolean>} True if the system is in dark mode, false otherwise
+ *
+ * @function isDarkMode
+ * @memberOf module:for-angular
+ */
+export declare function isDarkMode(): Promise<boolean>;

package/i18n/Loader.d.ts

@@ -0,0 +1,48 @@
+import { HttpClient } from '@angular/common/http';
+import { TranslateLoader, TranslationObject } from '@ngx-translate/core';
+import { Observable } from 'rxjs';
+import { I18nResourceConfig } from '../engine/interfaces';
+import { InjectionToken } from '@angular/core';
+import { FunctionLike } from '../engine';
+export declare class I18nLoader {
+    static loadFromHttp(http: HttpClient): TranslateLoader;
+}
+export declare function getLocaleContext(clazz: FunctionLike | object | string, suffix?: string): string;
+/**
+ * @description Generates a localized string by combining locale and phrase
+ * @summary This utility function creates a properly formatted locale string by combining
+ * a locale identifier with a phrase. It handles edge cases such as empty phrases,
+ * missing locales, and phrases that already include the locale prefix. This function
+ * is useful for ensuring consistent formatting of localized strings throughout the application.
+ *
+ * @param {string} locale - The locale identifier (e.g., 'en', 'fr')
+ * @param {string | undefined} phrase - The phrase to localize
+ * @return {string} The formatted locale string, or empty string if phrase is undefined
+ *
+ * @function generateLocaleFromString
+ * @memberOf module:for-angular
+ */
+export declare function getLocaleContextByKey(locale: string, phrase: string | undefined): string;
+export declare const I18N_CONFIG_TOKEN: InjectionToken<{
+    resources: I18nResourceConfig[];
+    versionedSuffix: false;
+}>;
+export declare function I18nLoaderFactory(http: HttpClient): TranslateLoader;
+export declare function getI18nLoaderFactoryProviderConfig(resources?: I18nResourceConfig | I18nResourceConfig[], versionedSuffix?: boolean): {
+    provide: InjectionToken<{
+        resources: I18nResourceConfig[];
+        versionedSuffix: false;
+    }>;
+    useValue: {
+        resources: I18nResourceConfig[];
+        versionedSuffix: boolean;
+    };
+};
+export declare class MultiI18nLoader implements I18nLoader {
+    private http;
+    private resources;
+    private versionedSuffix;
+    constructor(http: HttpClient, resources?: I18nResourceConfig[], versionedSuffix?: boolean);
+    private getSuffix;
+    getTranslation(lang: string): Observable<TranslationObject>;
+}

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "@decaf-ts/for-angular",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "author": "Tiago Venceslau",
   "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/decaf-ts/for-angular.git"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
   "peerDependencies": {
     "@angular/animations": "^18.2.13",
+    "@angular/cdk": "^18.2.14",
     "@angular/common": "^18.2.13",
     "@angular/compiler": "^18.2.13",
     "@angular/core": "^18.2.13",
@@ -18,6 +27,7 @@
     "@decaf-ts/decorator-validation": "^1.6.4",
     "@decaf-ts/for-http": "latest",
     "@decaf-ts/reflection": "latest",
+    "@decaf-ts/styles": "^0.0.3",
     "@decaf-ts/ui-decorators": "latest",
     "@ionic/angular": "^8.5.5",
     "@ngx-translate/core": "^16.0.4",

package/engine/NgxRenderingEngine2.d.ts

@@ -1,250 +0,0 @@
-import { FieldDefinition, RenderingEngine } from '@decaf-ts/ui-decorators';
-import { AngularDynamicOutput, AngularFieldDefinition, KeyValue } from './types';
-import { Constructor, Model } from '@decaf-ts/decorator-validation';
-import { ComponentMirror, ComponentRef, Injector, TemplateRef, Type, ViewContainerRef } from '@angular/core';
-/**
- * @description Angular implementation of the RenderingEngine with enhanced features
- * @summary This class extends the base RenderingEngine to provide Angular-specific rendering capabilities
- * with additional features compared to NgxRenderingEngine. It handles the conversion of field definitions
- * to Angular components, manages component registration, and provides utilities for component creation
- * and input handling. This implementation uses Angular's newer component APIs.
- *
- * @template AngularFieldDefinition - Type for Angular-specific field definitions
- * @template AngularDynamicOutput - Type for Angular-specific component output
- *
- * @class NgxRenderingEngine2
- * @example
- * ```typescript
- * const engine = NgxRenderingEngine2.get();
- * engine.initialize();
- * const output = engine.render(myModel, {}, viewContainerRef, injector, templateRef);
- * ```
- *
- * @mermaid
- * sequenceDiagram
- *   participant Client
- *   participant Engine as NgxRenderingEngine2
- *   participant Components as RegisteredComponents
- *
- *   Client->>Engine: get()
- *   Client->>Engine: initialize()
- *   Client->>Engine: render(model, props, vcr, injector, tpl)
- *   Engine->>Engine: toFieldDefinition(model, props)
- *   Engine->>Engine: fromFieldDefinition(fieldDef, vcr, injector, tpl)
- *   Engine->>Components: components(fieldDef.tag)
- *   Components-->>Engine: component constructor
- *   Engine->>Engine: createComponent(component, inputs, metadata, vcr, injector, template)
- *   Engine-->>Client: return AngularDynamicOutput
- */
-export declare class NgxRenderingEngine2 extends RenderingEngine<AngularFieldDefinition, AngularDynamicOutput> {
-    /**
-     * @description Registry of registered components
-     * @summary Static registry that maps component names to their constructors.
-     * This allows the engine to look up components by name when rendering.
-     * @type {Record<string, { constructor: Constructor<unknown> }>}
-     */
-    private static _components;
-    /**
-     * @description Collection of child component outputs
-     * @summary Stores the outputs of child components during rendering.
-     * @type {AngularDynamicOutput[]}
-     */
-    private _childs;
-    /**
-     * @description Current model being rendered
-     * @summary Reference to the model currently being processed by the rendering engine.
-     * @type {Model}
-     */
-    private _model;
-    /**
-     * @description Static reference to the current instance
-     * @summary Singleton instance reference for the rendering engine.
-     * @type {Type<unknown> | undefined}
-     */
-    private static _instance;
-    /**
-     * @description Creates a new instance of NgxRenderingEngine2
-     * @summary Initializes the rendering engine with the 'angular' engine type.
-     * This constructor sets up the base configuration needed for Angular-specific rendering.
-     */
-    constructor();
-    /**
-     * @description Converts a field definition to an Angular component output
-     * @summary This private method takes a field definition and creates the corresponding Angular component.
-     * It handles component instantiation, input property mapping, and child component rendering.
-     * The method validates input properties against the component's metadata and processes
-     * child components recursively.
-     *
-     * @param {FieldDefinition<AngularFieldDefinition>} fieldDef - The field definition to convert
-     * @param {ViewContainerRef} vcr - The view container reference for component creation
-     * @param {Injector} injector - The Angular injector for dependency injection
-     * @param {TemplateRef<any>} tpl - The template reference for content projection
-     * @param {string} registryFormId - Form identifier for the component renderer
-     * @return {AngularDynamicOutput} The Angular component output with component reference and inputs
-     *
-     * @mermaid
-     * sequenceDiagram
-     *   participant Method as fromFieldDefinition
-     *   participant Components as NgxRenderingEngine2.components
-     *   participant Angular as Angular Core
-     *   participant Process as processChild
-     *
-     *   Method->>Components: components(fieldDef.tag)
-     *   Components-->>Method: component constructor
-     *   Method->>Angular: reflectComponentType(component)
-     *   Angular-->>Method: componentMetadata
-     *   Method->>Method: Validate input properties
-     *   Method->>Method: Create result object
-     *   alt Has children
-     *     Method->>Process: Process children recursively
-     *     Process->>Method: Return processed children
-     *     Method->>Angular: Create embedded view
-     *     Method->>Method: Create component instance
-     *   end
-     *   Method-->>Caller: return AngularDynamicOutput
-     */
-    private fromFieldDefinition;
-    /**
-     * @description Creates an Angular component instance
-     * @summary This static utility method creates an Angular component instance with the specified
-     * inputs and template. It uses Angular's component creation API to instantiate the component
-     * and then sets the input properties using the provided metadata.
-     *
-     * @param {Type<unknown>} component - The component type to create
-     * @param {KeyValue} [inputs={}] - The input properties to set on the component
-     * @param {ComponentMirror<unknown>} metadata - The component metadata for input validation
-     * @param {ViewContainerRef} vcr - The view container reference for component creation
-     * @param {Injector} injector - The Angular injector for dependency injection
-     * @param {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 stores a reference to the model, then converts it to a field definition
-     * using the base RenderingEngine's toFieldDefinition method, and finally converts
-     * that field definition to an Angular component output using fromFieldDefinition.
-     *
-     * @template M - Type extending Model
-     * @param {M} model - The model to render
-     * @param {Record<string, unknown>} globalProps - Global properties to pass to the component
-     * @param {ViewContainerRef} vcr - The view container reference for component creation
-     * @param {Injector} injector - The Angular injector for dependency injection
-     * @param {TemplateRef<any>} tpl - The template reference for content projection
-     * @return {AngularDynamicOutput} The Angular component output with component reference and inputs
-     *
-     * @mermaid
-     * sequenceDiagram
-     *   participant Client as Client Code
-     *   participant Render as render method
-     *   participant ToField as toFieldDefinition
-     *   participant FromField as fromFieldDefinition
-     *
-     *   Client->>Render: render(model, globalProps, vcr, injector, tpl)
-     *   Render->>Render: Store model reference
-     *   Render->>ToField: toFieldDefinition(model, globalProps)
-     *   ToField-->>Render: fieldDef
-     *   Render->>FromField: fromFieldDefinition(fieldDef, vcr, injector, tpl)
-     *   FromField-->>Render: AngularDynamicOutput
-     *   Render-->>Client: return AngularDynamicOutput
-     */
-    render<M extends Model>(model: M, globalProps: Record<string, unknown>, vcr: ViewContainerRef, injector: Injector, tpl: TemplateRef<unknown>): AngularDynamicOutput;
-    /**
-     * @description Initializes the rendering engine
-     * @summary This method initializes the rendering engine. It checks if the engine is already initialized
-     * and sets the initialized flag to true. This method is called before the engine is used
-     * to ensure it's properly set up for rendering operations.
-     *
-     * @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 initializes the components registry if needed and throws
-     * an error if a component is already registered under the same name to prevent
-     * accidental overrides.
-     *
-     * @param {string} name - The name to register the component under
-     * @param {Constructor<unknown>} constructor - The component constructor
-     * @return {void}
-     */
-    static registerComponent(name: string, constructor: Constructor<unknown>): void;
-    /**
-     * @description Retrieves registered components from the rendering engine
-     * @summary This static method retrieves either all registered components or a specific component
-     * by its selector. When called without a selector, it returns an array of all registered
-     * components. When called with a selector, it returns the specific component if found,
-     * or throws an error if the component is not registered.
-     *
-     * @param {string} [selector] - Optional selector to retrieve a specific component
-     * @return {Object|Array} Either a specific component or an array of all components
-     */
-    static components(selector?: string): object | 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 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;
-}