turbogui-angular 17.0.0 → 18.0.0

package/fesm2022/turbogui-angular.mjs

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
 import { EventEmitter, Output, Directive, HostListener, NgModule, inject, Injectable, Component, Inject, HostBinding, Input } from '@angular/core';
-import { Subject } from 'rxjs';
+import { Subject, BehaviorSubject } from 'rxjs';
 import { ArrayUtils, NumericUtils, HTTPManager, StringUtils, HTTPManagerGetRequest, HTTPManagerPostRequest, BrowserManager, ConversionUtils } from 'turbocommons-ts';
 import * as i1 from '@angular/material/dialog';
 import { MAT_DIALOG_DATA } from '@angular/material/dialog';
@@ -14,6 +14,10 @@ import * as i2$1 from '@angular/material/datepicker';
 import { MatDatepickerModule } from '@angular/material/datepicker';
 import { MatNativeDateModule } from '@angular/material/core';
 import * as i1$1 from '@angular/material/snack-bar';
+import * as i1$2 from '@angular/router';
+import { NavigationEnd } from '@angular/router';
+import { filter } from 'rxjs/operators';
+import * as i2$2 from '@angular/platform-browser';
 import { MatFormFieldModule } from '@angular/material/form-field';
 import * as i4 from '@angular/material/input';
 import { MatInputModule } from '@angular/material/input';
@@ -450,7 +454,7 @@ class LocalesService extends SingletoneStrictClass {
         return value;
     }
     /**
-     * Defines the behaviour for get(), getStartCase(), etc... methods when a key is not found on
+     * Defines the behaviour for t(), tStartCase(), etc... methods when a key is not found on
      * a bundle or the bundle does not exist
      *
      * If missingKeyFormat is an empty string, all missing keys will return an empty value (not recommended)
@@ -476,6 +480,43 @@ class LocalesService extends SingletoneStrictClass {
     getMissingKeyFormat() {
         return this._missingKeyFormat;
     }
+    /**
+     * Initializes the translation system by loading and parsing bundle files from the specified JSON object.
+     * After the method finishes, the class will contain all the translation data and will be ready to translate any provided key.
+     *
+     * @param translations A JSON object containing the translation data. The structure must be as follows:
+     *       { library_name: { bundle_name: { locale_code: { key1: "translation1", key2: "translation2" } } } ... }
+     *
+     * @param locales An array of locale codes (e.g., ['en_US', 'es_ES', 'fr_FR']) to load into this class. The order of this array
+     *        will determine the translation priority
+     *
+     * @return True if the translations get correctly loaded. Any unsuccessful initialization will throw an exception
+     */
+    initializeFromJson(translations, locales) {
+        this._isInitialized = false;
+        // Validate received locales are correct
+        for (const locale of locales) {
+            this._validateLocaleString(locale);
+        }
+        // Validate the translations object follows the right structure
+        let isTranslationsValid = false;
+        for (const library in translations) {
+            for (const bundle in translations[library]) {
+                for (const locale in translations[library][bundle]) {
+                    this._validateLocaleString(locale);
+                    isTranslationsValid = true;
+                }
+            }
+        }
+        if (!isTranslationsValid) {
+            throw new Error('translations must be a non empty object with the structure: { library: { bundle: { xx_XX: { key: translation } } } }');
+        }
+        this._loadedTranslations = translations;
+        this._locales = locales;
+        this._languages = locales.map((l) => l.substring(0, 2));
+        this._cacheHashBaseString = this._wildCardsFormat + this._missingKeyFormat + this._locales[0];
+        return this._isInitialized = true;
+    }
     /**
      * Initializes the translation system by loading and parsing bundle files from the specified translations path.
      * After the promise finishes, the class will contain all the translation data and will be ready to translate any
@@ -489,14 +530,9 @@ class LocalesService extends SingletoneStrictClass {
      *
      * @return A promise that will resolve if the translations get correctly loaded, or reject with an error if load fails
      */
-    initialize(translationsPath, locales, parameters) {
+    initializeFromUrl(translationsPath, locales, parameters) {
         this._isInitialized = false;
-        this._loadedTranslations = {};
-        // Validate received locales are correct
-        for (const locale of locales) {
-            this._validateLocaleString(locale);
-        }
-        let translationsFullPath = translationsPath + '/' + locales.join('-') + '/' + parameters.join('/');
+        const translationsFullPath = translationsPath + '/' + locales.join('-') + '/' + parameters.join('/');
         return new Promise((resolve, reject) => {
             fetch(translationsFullPath).then(response => {
                 if (!response.ok) {
@@ -504,11 +540,7 @@ class LocalesService extends SingletoneStrictClass {
                 }
                 return response.json();
             }).then(data => {
-                this._loadedTranslations = data;
-                this._isInitialized = true;
-                this._locales = locales;
-                this._languages = locales.map((l) => l.substring(0, 2));
-                this._cacheHashBaseString = this._wildCardsFormat + this._missingKeyFormat + this._locales[0];
+                this.initializeFromJson(data, locales);
                 resolve(undefined);
             }).catch(error => {
                 reject(new Error(`ERROR LOADING LOCALES FROM: ${translationsFullPath}\n` + error));
@@ -526,7 +558,7 @@ class LocalesService extends SingletoneStrictClass {
      */
     _validateInitialized() {
         if (!this._isInitialized) {
-            throw new Error('LocalesManager not initialized');
+            throw new Error('Translation service not initialized');
         }
     }
     /**
@@ -609,7 +641,7 @@ class LocalesService extends SingletoneStrictClass {
             }
             // Check if an exception needs to be thrown if the specified key is not found on this bundle
             if (this._missingKeyFormat.includes('$exception')) {
-                throw new Error(`key <${key}> not found on ${bundlePath}`);
+                throw new Error(`Translation key <${key}> not found on <${bundlePath}>`);
             }
             this._keyValuesCache[cacheKey] = this._replace(this._missingKeyFormat, '$key', key);
         }
@@ -667,7 +699,7 @@ class LocalesService extends SingletoneStrictClass {
      * list for a translated text. If missing, the next one will be used, and so. This list is constructed after initialize
      * methods is called.
      *
-     * @example: After loading the following list of locales ['en_US', 'es_ES', 'fr_FR'] if we call LocalesManager.t('HELLO', 'lib1/greetings')
+     * @example: After loading the following list of locales ['en_US', 'es_ES', 'fr_FR'] if we call t('HELLO', 'lib1/greetings')
      * the localization manager will try to locate the en_US value for the HELLO tag on the greetings bundle for the library lib1.
      * If the tag is not found for the specified locale and bundle, the same search will be performed for the es_ES locale, and so, till a
      * value is found or no more locales are defined.
@@ -1228,22 +1260,29 @@ class DialogService extends SingletoneStrictClass {
      * @param action If not empty, the text to place on the snackbar confirmation button
      * @param actionCallback A method to execute once the user clicks into the action button.
      *
-     * @return void
+     * @return A promise that will be resolved once the snackbar is closed.
      */
-    addSnackBar(config, message, action = '', actionCallback = null) {
+    addSnackBar(config, message, action = '') {
         if (!this._isEnabled) {
-            return;
+            return Promise.reject(new Error('Dialog service is disabled'));
         }
         if (this._isShowingSnackBar) {
             throw new Error('Trying to show a snackbar while another one is still visible');
         }
         this._isShowingSnackBar = true;
-        const snackBarRef = this.matSnackBar.open(message, action === '' ? undefined : action, config);
-        if (actionCallback !== null) {
+        return new Promise((resolve) => {
+            const snackBarRef = this.matSnackBar.open(message, action === '' ? undefined : action, config);
+            // Handle action button click
             snackBarRef.onAction().subscribe(() => {
-                actionCallback();
+                this._isShowingSnackBar = false;
+                resolve(true);
             });
-        }
+            // Handle dismiss
+            snackBarRef.afterDismissed().subscribe(() => {
+                this._isShowingSnackBar = false;
+                resolve(false);
+            });
+        });
     }
     /**
      * Tells if the application is currently showing a snackbar or not
@@ -1286,60 +1325,61 @@ class DialogService extends SingletoneStrictClass {
      *            - viewContainerRef: This is important if we want to propagate providers from a parent component to this dialog. We must specify
      *              this reference to make sure the same services injected on the parent are available too at the child dialog
      *
-     * @param callback A function that will be called after the dialog is closed. It will receive a selection object with two properties: index and value. Those
-     *        will contain the index and value from the options array that's selected by the user. if no option selected, index will be -1 and value null
+     * @return A promise that will be resolved once the dialog is closed.
+     *         The promise will receive a selection object with two properties which will correspond to the index and value from the options
+     *         array that's selected by the user. If no option selected, index will be -1 and value null
      */
-    addDialog(dialogComponentClass, properties, callback = null) {
+    addDialog(dialogComponentClass, properties) {
         if (!this._isEnabled) {
-            return;
-        }
-        // Set the default values for non specified properties
-        properties.modal = properties.modal ?? true;
-        properties.texts = properties.texts ?? [];
-        properties.options = properties.options ?? [];
-        properties.data = properties.data ?? {};
-        // Generate a string to uniquely identify this dialog on the list of active dialogs
-        // A dialog is considered as unique if the dialog id and texts are exactly the same. We do not take options into consideration
-        // as there may be dialogs with a big amount of options available.
-        let className = dialogComponentClass.DIALOG_CLASS_NAME;
-        if (className === '') {
-            throw new Error(`The static property DIALOG_CLASS_NAME is not defined or is empty for this dialog component (${dialogComponentClass})`);
-        }
-        const dialogHash = className + properties.texts.join('');
-        // identical dialogs won't be allowed at the same time
-        if (this._activeDialogs.includes(dialogHash)) {
-            return;
-        }
-        const dialogRef = this.matDialog.open(dialogComponentClass, {
-            width: properties.width ?? "50%",
-            maxWidth: properties.maxWidth ?? "96vw",
-            disableClose: properties.modal,
-            autoFocus: false,
-            closeOnNavigation: !properties.modal,
-            viewContainerRef: properties.viewContainerRef,
-            data: { texts: properties.texts, options: properties.options, data: properties.data }
-        });
-        // Assign the dialog ID only if specifically set on properties
-        if (properties.id && properties.id !== undefined) {
-            dialogRef.id = properties.id;
-        }
-        this._activeDialogs.push(dialogHash);
-        this._activeDialogInstances.push(dialogRef);
-        dialogRef.beforeClosed().subscribe((selection) => {
-            this._activeDialogs = ArrayUtils.removeElement(this._activeDialogs, dialogHash);
-            this._activeDialogInstances = ArrayUtils.removeElement(this._activeDialogInstances, dialogRef);
-            if (!properties.modal && selection === undefined) {
-                selection = { index: -1 };
+            return Promise.reject(new Error('Dialog service is disabled'));
+        }
+        return new Promise((resolve) => {
+            // Set the default values for non specified properties
+            properties.modal = properties.modal ?? true;
+            properties.texts = properties.texts ?? [];
+            properties.options = properties.options ?? [];
+            properties.data = properties.data ?? {};
+            // Generate a string to uniquely identify this dialog on the list of active dialogs
+            // A dialog is considered as unique if the dialog id and texts are exactly the same. We do not take options into consideration
+            // as there may be dialogs with a big amount of options available.
+            let className = dialogComponentClass.DIALOG_CLASS_NAME;
+            if (className === '') {
+                throw new Error(`The static property DIALOG_CLASS_NAME is not defined or is empty for this dialog component (${dialogComponentClass})`);
+            }
+            const dialogHash = className + properties.texts.join('');
+            // identical dialogs won't be allowed at the same time
+            if (this._activeDialogs.includes(dialogHash)) {
+                return resolve({ index: -1 });
             }
-            else if (!NumericUtils.isInteger(selection.index)) {
-                throw new Error(`closeDialog() expects index to be an integer`);
+            const dialogRef = this.matDialog.open(dialogComponentClass, {
+                width: properties.width ?? "50%",
+                maxWidth: properties.maxWidth ?? "96vw",
+                disableClose: properties.modal,
+                autoFocus: false,
+                closeOnNavigation: !properties.modal,
+                viewContainerRef: properties.viewContainerRef,
+                data: { texts: properties.texts, options: properties.options, data: properties.data }
+            });
+            // Assign the dialog ID only if specifically set on properties
+            if (properties.id && properties.id !== undefined) {
+                dialogRef.id = properties.id;
             }
-            if (callback !== null) {
+            this._activeDialogs.push(dialogHash);
+            this._activeDialogInstances.push(dialogRef);
+            dialogRef.beforeClosed().subscribe((selection) => {
+                this._activeDialogs = ArrayUtils.removeElement(this._activeDialogs, dialogHash);
+                this._activeDialogInstances = ArrayUtils.removeElement(this._activeDialogInstances, dialogRef);
+                if (!properties.modal && selection === undefined) {
+                    selection = { index: -1 };
+                }
+                else if (!NumericUtils.isInteger(selection.index)) {
+                    throw new Error(`closeDialog() expects index to be an integer`);
+                }
                 if (selection.index >= 0 && selection.value === null) {
                     selection.value = properties.options[selection.index];
                 }
-                callback(selection);
-            }
+                resolve(selection);
+            });
         });
     }
     /**
@@ -1359,13 +1399,14 @@ class DialogService extends SingletoneStrictClass {
      *            - title: An optional dialog title
      *            - viewContainerRef: This is important to propagate providers from a parent component to this dialog. We must specify
      *              this reference to make sure the same services injected on the parent are available too at the child dialog
-     * @param callback A function to be called after the dialog is closed. It will receive a Date() object selected by the user or null if no selection happened
+     *
+     * @returns A Promise that resolves to a Date() object selected by the user or null if no selection was made
      */
-    addDateSelectionDialog(properties, callback) {
+    async addDateSelectionDialog(properties) {
         if (!this._isEnabled) {
-            return;
+            return null;
         }
-        this.addDialog(DialogDateSelectionComponent, {
+        const selection = await this.addDialog(DialogDateSelectionComponent, {
             id: properties.id ?? undefined,
             width: properties.width ?? "50%",
             maxWidth: properties.maxWidth ?? "96vw",
@@ -1374,9 +1415,8 @@ class DialogService extends SingletoneStrictClass {
             modal: properties.modal ?? false,
             texts: [properties.title ?? ''],
             viewContainerRef: properties.viewContainerRef
-        }, (selection) => {
-            callback(selection.index === -1 ? null : selection.value);
         });
+        return selection.index === -1 ? null : selection.value;
     }
     /**
      * Force the removal of all the dialogs that are currently visible.
@@ -2025,6 +2065,132 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.5", ngImpor
                 }]
         }], ctorParameters: () => [{ type: DialogService }, { type: BrowserService }] });
 
+/**
+ * TurboGUI is A library that helps with the most common and generic UI elements and functionalities
+ *
+ * Website : -> http://www.turbogui.org
+ * License : -> Licensed under the Apache License, Version 2.0. You may not use this file except in compliance with the License.
+ * License Url : -> http://www.apache.org/licenses/LICENSE-2.0
+ * CopyRight : -> Copyright 2018 Edertone Advanded Solutions. https://www.edertone.com
+ */
+/**
+ * Global service that helps with application routing and related functionalities.
+ * It is defined as an abstract class so it must be extended in our application to be used.
+ * We must declare a static array of routes that will be used to define the routes of the application.
+ */
+class RouterBaseService {
+    constructor(router, titleService, ls) {
+        this.router = router;
+        this.titleService = titleService;
+        this.ls = ls;
+        /**
+         * Indicates whether the title manager has been initialized.
+         * This should only be done once, typically at application startup.
+         */
+        this._isTitleManagerInitialized = false;
+        /**
+         * BehaviorSubject that holds the current route URL.
+         * This allows components to reactively subscribe to route changes.
+         */
+        this._currentRoute = new BehaviorSubject(this.router.url);
+        // Initial update in case the service loads after the first NavigationEnd
+        this._updateCurrentRoute();
+    }
+    /**
+     * Updates the current route URL in the BehaviorSubject.
+     * This is called internally after each navigation event.
+     */
+    _updateCurrentRoute() {
+        this._currentRoute.next(this.router.url);
+    }
+    /**
+     * Checks if the current route matches the specified route.
+     *
+     * @param route The route to check against the current route.
+     *
+     * @returns True if we are actually at the specified route, false otherwise.
+     */
+    isRouteCurrent(route) {
+        return this.getCurrentRoute() === '/' + route;
+    }
+    /**
+     * Gets the current value of the route URL synchronously.
+     */
+    getCurrentRoute() {
+        return this._currentRoute.getValue();
+    }
+    /**
+     * Initializes the title management feature to automatically refresh the browser title based on the current
+     * URL route. It Must be called once, typically at application startup
+     *
+     * To correctly translate the route title, We expect the route definitions to have the following properties:
+     *
+     * - titleKey: The key to be used to get the title from the translation bundle.
+     * - titleBundle: The bundle to be used to get the title from the translation bundle.
+     *
+     * (Translations will be done using the LocalesService from this same library).
+     *
+     * Example of a Route using this feature:
+     *   // Home route
+     *   { path: '', component: HomePageComponent,
+     *     data: { titleKey: 'HOME',  titleBundle: 'turbodepot/user-interface'} },
+     *
+     * @param prefix A text to be added before the computed title.
+     * @param sufix A text to be added after the computed title.
+     */
+    initializeAutoTranslateTitleByRoute(prefix = '', sufix = '') {
+        if (this._isTitleManagerInitialized) {
+            throw new Error('Title refresh from routes has already been initialized. Can only be done once.');
+        }
+        // Set initial title based on current route data immediately
+        this.updateTitleFromCurrentRoute(prefix, sufix);
+        // Subscribe to future navigation events
+        this._routerSubscription = this.router.events.pipe(filter(event => event instanceof NavigationEnd)).subscribe(() => {
+            this._updateCurrentRoute();
+            this.updateTitleFromCurrentRoute(prefix, sufix);
+        });
+        this._isTitleManagerInitialized = true;
+    }
+    /**
+     * Aux method: Updates the browser title based on the current route's data properties.
+     * This is called after each navigation event to ensure the title is always up-to-date.
+     *
+     * @param prefix A text to be added before the computed title.
+     * @param sufix A text to be added after the computed title.
+     */
+    updateTitleFromCurrentRoute(prefix, sufix) {
+        let currentRoute = this.router.routerState.snapshot.root;
+        while (currentRoute.firstChild) {
+            currentRoute = currentRoute.firstChild;
+        }
+        const data = currentRoute.data;
+        if (data['titleKey'] && data['titleBundle']) {
+            this.titleService.setTitle(prefix + this.ls.t(data['titleKey'], data['titleBundle']) + sufix);
+        }
+    }
+    /**
+     * Navigates to the specified route.
+     *
+     * @param route The route to navigate to.
+     */
+    navigateTo(route) {
+        this.router.navigate(['/' + route]);
+    }
+    ngOnDestroy() {
+        this._routerSubscription?.unsubscribe();
+        // Clean up BehaviorSubject
+        this._currentRoute.complete();
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.5", ngImport: i0, type: RouterBaseService, deps: [{ token: i1$2.Router }, { token: i2$2.Title }, { token: LocalesService }], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.5", ngImport: i0, type: RouterBaseService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.5", ngImport: i0, type: RouterBaseService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }], ctorParameters: () => [{ type: i1$2.Router }, { type: i2$2.Title }, { type: LocalesService }] });
+
 /**
  * TurboGUI is A library that helps with the most common and generic UI elements and functionalities
  *
@@ -2557,6 +2723,7 @@ class ButtonContainerComponent extends ButtonBaseComponent {
         super(...arguments);
         /**
          * This is used to attach the fade animation directly to this component so it fades in and out when created and removed from the app
+         * TODO: THIS IS NOT A GOOD IDEA
          */
         this.buttonFade = true;
     }
@@ -2612,18 +2779,29 @@ class GUINotification {
  * CopyRight : -> Copyright 2018 Edertone Advanded Solutions. https://www.edertone.com
  */
 /**
- * Defines an application view.
- * This is a base class that helps managing our application views. We should extend this class to create our views, as it forces us
- * to set the viewContainerRef and the viewService, which are both used when working with views.
+ * This is a base class that helps managing our application pages.
+ * We should extend this class to create our application pages, as it forces us to set the viewContainerRef and the viewService,
+ * which are both used when working with pages.
+ *
+ * IMPORTANT!!! View services are created and destroyed when the page is created and destroyed. It is vital to specify the view service
+ * as a provider for the page to ensure that it will be created and destroyed when the view is created and destroyed.
  *
- * When using view services, it is important to specify the view service as a provider for the view component to ensure that it will
- * be created and destroyed when the view is created and destroyed.
+ * Example:
+ *
+ * @Component({
+ *   ...
+ *   selector: 'app-my-view-page',
+ *   providers: [MyViewService]
+ *   ...
+ *})
  */
 class View {
     /**
-     * This constructor is specifically designed to force the view to set the viewContainerRef which will be automatically assigned
-     * to the respective view service. If the view has no service, we can set it to null, but it is recommended to always use a service with a view,
-     * to store the view state and global methods that can be used by other components loaded in the view.
+     * This constructor is specifically designed to force the following:
+     *
+     * - Set the viewContainerRef which will be automatically assigned to the respective view service.
+     *
+     * - If the view has no service, we can set it to null, but it is recommended to always use a service with a view, to store the view state and global methods
      */
     constructor(viewContainerRef, viewService) {
         this.viewContainerRef = viewContainerRef;
@@ -2764,5 +2942,5 @@ class ValidatorsPlus extends Validators {
  * Generated bundle index. Do not edit.
  */
 
-export { AutoFocusOnDisplayDirective, AutoSelectTextOnFocusDirective, BrowserService, BusyStateBaseComponent, ButtonContainerComponent, ButtonImageComponent, DelayedMethodCallManager, DialogBaseComponent, DialogDateSelectionComponent, DialogErrorComponent, DialogMultipleOptionComponent, DialogService, DialogSingleInputComponent, DialogSingleOptionComponent, DialogSingleSelectionListComponent, DialogTwoOptionComponent, ElementCreatedDirective, ElementDestroyedDirective, FadeAnimationClass, GUINotification, GlobalErrorService, HTTPService, HTTPServiceGetRequest, HTTPServicePostRequest, LocalesService, NotificationService, SingletoneStrictClass, TurboApiCallerService, TurboGuiAngularModule, ValidatorsPlus, View, ViewService };
+export { AutoFocusOnDisplayDirective, AutoSelectTextOnFocusDirective, BrowserService, BusyStateBaseComponent, ButtonContainerComponent, ButtonImageComponent, DelayedMethodCallManager, DialogBaseComponent, DialogDateSelectionComponent, DialogErrorComponent, DialogMultipleOptionComponent, DialogService, DialogSingleInputComponent, DialogSingleOptionComponent, DialogSingleSelectionListComponent, DialogTwoOptionComponent, ElementCreatedDirective, ElementDestroyedDirective, FadeAnimationClass, GUINotification, GlobalErrorService, HTTPService, HTTPServiceGetRequest, HTTPServicePostRequest, LocalesService, NotificationService, RouterBaseService, SingletoneStrictClass, TurboApiCallerService, TurboGuiAngularModule, ValidatorsPlus, View, ViewService };
 //# sourceMappingURL=turbogui-angular.mjs.map