@nu-art/thunderstorm-frontend 0.400.10 → 0.400.13

package/modules/ModuleFE_Thunderstorm.d.ts

@@ -1,4 +1,5 @@
 import { Module, TypedMap } from '@nu-art/ts-common';
+import { GenericUpdate } from '@nu-art/thunderstorm-shared';
 type Config = {
     appName: string;
     themeColor: string;
@@ -26,6 +27,7 @@ declare class ModuleFE_Thunderstorm_Class extends Module<Config> {
         params?: TypedMap<(() => string) | string | undefined>;
     }, target?: UrlTarget): void;
     downloadFile(props: FileDownloadProps): void;
+    performGenericUpdate: (updateData: GenericUpdate[]) => Promise<void>;
 }
 export declare const ModuleFE_Thunderstorm: ModuleFE_Thunderstorm_Class;
 export {};

package/modules/ModuleFE_Thunderstorm.js

@@ -18,9 +18,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { _keys, BadImplementationException, Module } from '@nu-art/ts-common';
+import { _keys, BadImplementationException, Module, MUSTNeverHappenException, Promise_all_sequentially, RuntimeModules } from '@nu-art/ts-common';
 import { ModuleFE_Toaster } from '../component-modules/ModuleFE_Toaster.js';
-import { composeURL } from './ModuleFE_BrowserHistory.js';
+import { composeURL } from './routing/ModuleFE_RoutingV2.js';
 import { HttpMethod } from '@nu-art/thunderstorm-shared';
 import { base64ToBlob } from '../utils/tools.js';
 import { ModuleFE_XHR } from './http/ModuleFE_XHR.js';
@@ -118,5 +118,18 @@ class ModuleFE_Thunderstorm_Class extends Module {
         element.setAttribute('download', `${props.fileName}`);
         element.click();
     }
+    performGenericUpdate = async (updateData) => {
+        const promises = [];
+        updateData.forEach(update => {
+            const module = RuntimeModules().find(module => module.dbDef?.dbKey === update.dbKey);
+            if (!module)
+                throw new MUSTNeverHappenException(`Trying to perform a generic update without an existing module for dbKey ${update.dbKey}`);
+            if (update.data.toUpdate?.length)
+                promises.push(() => module.onEntriesUpdated(update.data.toUpdate));
+            if (update.data.toDelete?.length)
+                promises.push(() => module.onEntriesDeleted(update.data.toDelete));
+        });
+        await Promise_all_sequentially(promises);
+    };
 }
 export const ModuleFE_Thunderstorm = new ModuleFE_Thunderstorm_Class();

package/modules/component-loader/entry-component-loading-module.js

@@ -21,14 +21,14 @@
 import { Module } from '@nu-art/ts-common';
 // noinspection TypeScriptPreferShortImport
 import { ModuleFE_XHR } from '../http/ModuleFE_XHR.js';
-import { ModuleFE_BrowserHistory } from '../ModuleFE_BrowserHistory.js';
+import { ModuleFE_RoutingV2 } from '../routing/ModuleFE_RoutingV2.js';
 import { HttpMethod } from '@nu-art/thunderstorm-shared';
 export class PageLoadingModule_Class extends Module {
     injected = {};
     loadScript(src, progressListener) {
         const apiDef = {
             method: HttpMethod.GET,
-            baseUrl: ModuleFE_BrowserHistory.getOrigin(),
+            baseUrl: ModuleFE_RoutingV2.getOrigin(),
             path: src
         };
         ModuleFE_XHR

package/modules/routing/ModuleFE_Routing.d.ts

@@ -1,7 +1,34 @@
+/**
+ * @deprecated This module is deprecated. Use ModuleFE_RoutingV2 instead.
+ *
+ * Migration Guide:
+ *
+ * ModuleFE_Routing uses an imperative API (addRoute, clearRoutes) while ModuleFE_RoutingV2 uses a declarative
+ * route object API (TS_Route). Migration requires refactoring route definitions.
+ *
+ * Key Differences:
+ * - Old: ModuleFE_Routing.addRoute(key, path, component)
+ * - New: Define TS_Route objects with key, path, Component properties
+ *
+ * - Old: ModuleFE_Routing.goToRoute(key, params)
+ * - New: ModuleFE_RoutingV2.goToRoute(routeObject, params)
+ *
+ * - Old: ModuleFE_Routing.getRoutesMap()
+ * - New: ModuleFE_RoutingV2.generateRoutes(rootRoute) - returns JSX
+ *
+ * See ModuleFE_RoutingV2 and TS_Route type for the new API.
+ *
+ * This module will be removed in a future version. Please migrate to ModuleFE_RoutingV2.
+ */
 import { Module, RouteParams } from '@nu-art/ts-common';
 import * as React from 'react';
 import { RoutePath } from './route.js';
 import { QueryParams } from '@nu-art/thunderstorm-shared';
+/**
+ * @deprecated Use ModuleFE_RoutingV2 instead. This class will be removed in a future version.
+ *
+ * All functionality has been migrated to ModuleFE_RoutingV2. See file-level deprecation notice for migration guide.
+ */
 declare class ModuleFE_Routing_Class extends Module<{}> {
     private readonly routes;
     private readonly ordinalRoutes;
@@ -10,21 +37,148 @@ declare class ModuleFE_Routing_Class extends Module<{}> {
     private readonly createLinkNode;
     constructor();
     init(): void;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2 with TS_Route objects instead
+     *
+     * Migration: Define routes as TS_Route objects and pass to ModuleFE_RoutingV2.generateRoutes()
+     */
     clearRoutes(): void;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2 with TS_Route objects instead
+     *
+     * Migration:
+     * // Old:
+     * ModuleFE_Routing.addRoute('home', '/', HomeComponent);
+     *
+     * // New:
+     * const route: TS_Route = { key: 'home', path: '/', Component: HomeComponent };
+     * // Then use ModuleFE_RoutingV2.generateRoutes(rootRoute) where rootRoute contains this route
+     */
     addRoute(key: string, route: string, component: React.ComponentClass<any, any> | string): RoutePath;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.getRouteByKey() instead
+     *
+     * Migration:
+     * // Old:
+     * const route = ModuleFE_Routing.getRoute(key);
+     *
+     * // New:
+     * const route = ModuleFE_RoutingV2.getRouteByKey(key);
+     */
     getRoute(key: string): RoutePath;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.getFullPath() instead
+     *
+     * Migration:
+     * // Old:
+     * const path = ModuleFE_Routing.getPath(key);
+     *
+     * // New:
+     * const path = ModuleFE_RoutingV2.getFullPath(key);
+     */
     getPath(key: string): string;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.goToRoute() instead
+     *
+     * Migration:
+     * // Old:
+     * ModuleFE_Routing.goToRoute(key, params);
+     *
+     * // New:
+     * const route = ModuleFE_RoutingV2.getRouteByKey(key);
+     * if (route) ModuleFE_RoutingV2.goToRoute(route, params);
+     */
     goToRoute(key: string, params?: RouteParams): void;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.redirect() instead
+     *
+     * Migration:
+     * // Old:
+     * return ModuleFE_Routing.redirect(key);
+     *
+     * // New:
+     * const route = ModuleFE_RoutingV2.getRouteByKey(key);
+     * if (route) return ModuleFE_RoutingV2.redirect(route);
+     */
     redirect(key: string): import("react/jsx-runtime").JSX.Element;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.getCurrentRouteKey() instead
+     *
+     * Migration:
+     * // Old:
+     * const key = ModuleFE_Routing.getMyRouteKey();
+     *
+     * // New:
+     * const route = ModuleFE_RoutingV2.getCurrentRouteKey();
+     * const key = route?.key;
+     */
     getMyRouteKey: () => string | undefined;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2 with TS_NavLink component instead
+     *
+     * Migration: Use TS_NavLink component from ModuleFE_RoutingV2 with route objects
+     */
     getNavLinks(keys: string[]): React.ReactElement<any, string | React.JSXElementConstructor<any>>[];
+    /**
+     * @deprecated Use TS_NavLink from ModuleFE_RoutingV2 instead
+     *
+     * Migration: Use <TS_NavLink route={routeObject}> component
+     */
     getNavLink(key: string): React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+    /**
+     * @deprecated Use standard React Router Link or TS_NavLink from ModuleFE_RoutingV2
+     */
     getLink(key: string): React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.generateRoutes() instead
+     *
+     * Migration:
+     * // Old:
+     * {ModuleFE_Routing.getRoutesMap()}
+     *
+     * // New:
+     * {ModuleFE_RoutingV2.generateRoutes(rootRoute)}
+     */
     getRoutesMap(keys?: string[]): import("react/jsx-runtime").JSX.Element;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.getCurrentUrl() instead
+     *
+     * Migration:
+     * // Old:
+     * const url = ModuleFE_Routing.getCurrentUrl();
+     *
+     * // New:
+     * const url = ModuleFE_RoutingV2.getCurrentUrl();
+     */
     getCurrentUrl: () => string;
     private getEncodedQueryParams;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.getQueryParams() instead
+     *
+     * Migration:
+     * // Old:
+     * const params = ModuleFE_Routing.getSearch();
+     *
+     * // New:
+     * const params = ModuleFE_RoutingV2.getQueryParams();
+     */
     getSearch(): QueryParams;
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.push() or ModuleFE_RoutingV2.goToRoute() instead
+     *
+     * Migration:
+     * // Old:
+     * ModuleFE_Routing.goToUrl('/path');
+     *
+     * // New:
+     * ModuleFE_RoutingV2.push({pathname: '/path'});
+     */
     goToUrl: (url: string) => string;
 }
+/**
+ * @deprecated Use ModuleFE_RoutingV2 instead. This export will be removed in a future version.
+ *
+ * See file-level deprecation notice for migration guide.
+ */
 export declare const ModuleFE_Routing: ModuleFE_Routing_Class;
 export {};

package/modules/routing/ModuleFE_Routing.js

@@ -19,10 +19,37 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * @deprecated This module is deprecated. Use ModuleFE_RoutingV2 instead.
+ *
+ * Migration Guide:
+ *
+ * ModuleFE_Routing uses an imperative API (addRoute, clearRoutes) while ModuleFE_RoutingV2 uses a declarative
+ * route object API (TS_Route). Migration requires refactoring route definitions.
+ *
+ * Key Differences:
+ * - Old: ModuleFE_Routing.addRoute(key, path, component)
+ * - New: Define TS_Route objects with key, path, Component properties
+ *
+ * - Old: ModuleFE_Routing.goToRoute(key, params)
+ * - New: ModuleFE_RoutingV2.goToRoute(routeObject, params)
+ *
+ * - Old: ModuleFE_Routing.getRoutesMap()
+ * - New: ModuleFE_RoutingV2.generateRoutes(rootRoute) - returns JSX
+ *
+ * See ModuleFE_RoutingV2 and TS_Route type for the new API.
+ *
+ * This module will be removed in a future version. Please migrate to ModuleFE_RoutingV2.
+ */
 import { _keys, addItemToArray, BadImplementationException, composeQueryParams, Module } from '@nu-art/ts-common';
 import { defaultLinkNode, defaultNavLinkNode, defaultRouteNode, RoutePath } from './route.js';
-import { ModuleFE_BrowserHistory } from '../ModuleFE_BrowserHistory.js';
+import { ModuleFE_RoutingV2 } from './ModuleFE_RoutingV2.js';
 import { Navigate, Routes } from 'react-router-dom';
+/**
+ * @deprecated Use ModuleFE_RoutingV2 instead. This class will be removed in a future version.
+ *
+ * All functionality has been migrated to ModuleFE_RoutingV2. See file-level deprecation notice for migration guide.
+ */
 class ModuleFE_Routing_Class extends Module {
     routes = {};
     ordinalRoutes = [];
@@ -37,12 +64,28 @@ class ModuleFE_Routing_Class extends Module {
     }
     init() {
     }
+    /**
+     * @deprecated Use ModuleFE_RoutingV2 with TS_Route objects instead
+     *
+     * Migration: Define routes as TS_Route objects and pass to ModuleFE_RoutingV2.generateRoutes()
+     */
     clearRoutes() {
         for (const item of this.ordinalRoutes) {
             delete this.routes[item];
         }
         this.ordinalRoutes.splice(0);
     }
+    /**
+     * @deprecated Use ModuleFE_RoutingV2 with TS_Route objects instead
+     *
+     * Migration:
+     * // Old:
+     * ModuleFE_Routing.addRoute('home', '/', HomeComponent);
+     *
+     * // New:
+     * const route: TS_Route = { key: 'home', path: '/', Component: HomeComponent };
+     * // Then use ModuleFE_RoutingV2.generateRoutes(rootRoute) where rootRoute contains this route
+     */
     addRoute(key, route, component) {
         const previousRoute = this.routes[key];
         if (previousRoute)
@@ -50,37 +93,123 @@ class ModuleFE_Routing_Class extends Module {
         addItemToArray(this.ordinalRoutes, key);
         return this.routes[key] = new RoutePath(key, route, component);
     }
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.getRouteByKey() instead
+     *
+     * Migration:
+     * // Old:
+     * const route = ModuleFE_Routing.getRoute(key);
+     *
+     * // New:
+     * const route = ModuleFE_RoutingV2.getRouteByKey(key);
+     */
     getRoute(key) {
         const route = this.routes[key];
         if (!route)
             throw new BadImplementationException(`No Route for key '${key}'... Did you forget to add it??`);
         return route;
     }
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.getFullPath() instead
+     *
+     * Migration:
+     * // Old:
+     * const path = ModuleFE_Routing.getPath(key);
+     *
+     * // New:
+     * const path = ModuleFE_RoutingV2.getFullPath(key);
+     */
     getPath(key) {
         return this.getRoute(key).path;
     }
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.goToRoute() instead
+     *
+     * Migration:
+     * // Old:
+     * ModuleFE_Routing.goToRoute(key, params);
+     *
+     * // New:
+     * const route = ModuleFE_RoutingV2.getRouteByKey(key);
+     * if (route) ModuleFE_RoutingV2.goToRoute(route, params);
+     */
     goToRoute(key, params) {
         const pathname = this.getPath(key);
         const search = composeQueryParams(params);
-        ModuleFE_BrowserHistory.push({ pathname, search });
+        ModuleFE_RoutingV2.push({ pathname, search: search ? `?${search}` : '' });
     }
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.redirect() instead
+     *
+     * Migration:
+     * // Old:
+     * return ModuleFE_Routing.redirect(key);
+     *
+     * // New:
+     * const route = ModuleFE_RoutingV2.getRouteByKey(key);
+     * if (route) return ModuleFE_RoutingV2.redirect(route);
+     */
     redirect(key) {
         return _jsx(Navigate, { to: ModuleFE_Routing.getPath(key) });
     }
-    getMyRouteKey = () => Object.keys(this.routes).find(key => this.routes[key].path === ModuleFE_BrowserHistory.getCurrent().pathname);
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.getCurrentRouteKey() instead
+     *
+     * Migration:
+     * // Old:
+     * const key = ModuleFE_Routing.getMyRouteKey();
+     *
+     * // New:
+     * const route = ModuleFE_RoutingV2.getCurrentRouteKey();
+     * const key = route?.key;
+     */
+    getMyRouteKey = () => Object.keys(this.routes).find(key => this.routes[key].path === ModuleFE_RoutingV2.getCurrent().pathname);
+    /**
+     * @deprecated Use ModuleFE_RoutingV2 with TS_NavLink component instead
+     *
+     * Migration: Use TS_NavLink component from ModuleFE_RoutingV2 with route objects
+     */
     // need to figure out how to create parameterized urls from this call !!
     getNavLinks(keys) {
         return keys.map(key => this.getRoute(key)).filter(route => route.visible && route.visible()).map(route => this.createNavLinkNode(route));
     }
+    /**
+     * @deprecated Use TS_NavLink from ModuleFE_RoutingV2 instead
+     *
+     * Migration: Use <TS_NavLink route={routeObject}> component
+     */
     getNavLink(key) {
         return this.createNavLinkNode(this.getRoute(key));
     }
+    /**
+     * @deprecated Use standard React Router Link or TS_NavLink from ModuleFE_RoutingV2
+     */
     getLink(key) {
         return this.createLinkNode(this.getRoute(key));
     }
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.generateRoutes() instead
+     *
+     * Migration:
+     * // Old:
+     * {ModuleFE_Routing.getRoutesMap()}
+     *
+     * // New:
+     * {ModuleFE_RoutingV2.generateRoutes(rootRoute)}
+     */
     getRoutesMap(keys) {
         return _jsx(Routes, { children: (keys || this.ordinalRoutes).map(key => this.createRouteNode(this.getRoute(key))) });
     }
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.getCurrentUrl() instead
+     *
+     * Migration:
+     * // Old:
+     * const url = ModuleFE_Routing.getCurrentUrl();
+     *
+     * // New:
+     * const url = ModuleFE_RoutingV2.getCurrentUrl();
+     */
     getCurrentUrl = () => window.location.href;
     getEncodedQueryParams = () => {
         const queryParams = {};
@@ -105,6 +234,16 @@ class ModuleFE_Routing_Class extends Module {
             return toRet;
         }, queryParams);
     };
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.getQueryParams() instead
+     *
+     * Migration:
+     * // Old:
+     * const params = ModuleFE_Routing.getSearch();
+     *
+     * // New:
+     * const params = ModuleFE_RoutingV2.getQueryParams();
+     */
     getSearch() {
         const params = this.getEncodedQueryParams();
         _keys(params).forEach(key => {
@@ -117,6 +256,21 @@ class ModuleFE_Routing_Class extends Module {
         });
         return params;
     }
+    /**
+     * @deprecated Use ModuleFE_RoutingV2.push() or ModuleFE_RoutingV2.goToRoute() instead
+     *
+     * Migration:
+     * // Old:
+     * ModuleFE_Routing.goToUrl('/path');
+     *
+     * // New:
+     * ModuleFE_RoutingV2.push({pathname: '/path'});
+     */
     goToUrl = (url) => window.location.href = url;
 }
+/**
+ * @deprecated Use ModuleFE_RoutingV2 instead. This export will be removed in a future version.
+ *
+ * See file-level deprecation notice for migration guide.
+ */
 export const ModuleFE_Routing = new ModuleFE_Routing_Class();

package/modules/routing/ModuleFE_RoutingV2.d.ts

@@ -1,7 +1,7 @@
 import { NavigateFunction, NavLinkProps } from 'react-router-dom';
 import { TS_Route } from './types.js';
 import { Module } from '@nu-art/ts-common';
-import { QueryParams } from '@nu-art/thunderstorm-shared';
+import { QueryParams, UrlQueryParams } from '@nu-art/thunderstorm-shared';
 declare class ModuleFE_RoutingV2_Class extends Module<{}> {
     private routesMapByKey;
     private routesMapByPath;
@@ -16,10 +16,100 @@ declare class ModuleFE_RoutingV2_Class extends Module<{}> {
     getFullPath(routeKey: string): string;
     getCurrentRouteKey(): TS_Route;
     setNavigate(navigate: NavigateFunction): void;
+    /**
+     * Get all query parameters from the current URL (decoded)
+     */
+    getQueryParams(): UrlQueryParams;
+    /**
+     * Get a single query parameter from the current URL
+     * @param key - The query parameter key
+     * @returns The decoded value, null if key exists but value is empty, or undefined if key doesn't exist
+     */
+    getQueryParameter(key: string): string | null | undefined;
+    /**
+     * Replace all query parameters on the current route
+     * @param queryParams - The query parameters to set
+     */
+    setQuery(queryParams: UrlQueryParams): void;
+    /**
+     * Add or update a single query parameter on the current route
+     * @param key - The query parameter key
+     * @param value - The query parameter value
+     */
+    addQueryParam(key: string, value: string): void;
+    /**
+     * Remove a single query parameter from the current route
+     * @param key - The query parameter key to remove
+     */
+    removeQueryParam(key: string): void;
+    /**
+     * Get the current location object (compatible with BrowserHistory.getCurrent())
+     * @returns Object with pathname and search properties
+     */
+    getCurrent(): {
+        pathname: string;
+        search: string;
+        hash?: string;
+        state?: any;
+        key?: string;
+    };
+    /**
+     * Get the current URL pathname
+     * @returns The current pathname
+     */
+    getCurrentUrl(): string;
+    /**
+     * Get the window origin
+     * @returns The origin (protocol + hostname + port)
+     */
+    getOrigin(): string;
+    /**
+     * Navigate to a pathname with optional query params (adds to history)
+     * @param location - Location descriptor with pathname and optional search
+     */
+    push(location: {
+        pathname: string;
+        search?: string;
+        hash?: string;
+    }): void;
+    /**
+     * Replace current history entry with new pathname and optional query params
+     * @param location - Location descriptor with pathname and optional search
+     */
+    replace(location: {
+        pathname: string;
+        search?: string;
+        hash?: string;
+    }): void;
+    private getEncodedQueryParams;
+    private composeQuery;
+    private encodeUrlParams;
+    private createLocationDataFromQueryParams;
+    private updateQueryParams;
+    private composeLocationUrl;
 }
 export declare const TS_NavLink: (props: {
     route: TS_Route;
     ignoreClickOnSameRoute?: boolean;
 } & Partial<NavLinkProps>) => import("react/jsx-runtime").JSX.Element;
 export declare const ModuleFE_RoutingV2: ModuleFE_RoutingV2_Class;
+/**
+ * Encode URL query parameters
+ * @param queryParams - Query parameters to encode
+ * @returns Encoded query parameters
+ */
+export declare function encodeUrlParams(queryParams?: UrlQueryParams): UrlQueryParams;
+/**
+ * Compose a query string from query parameters
+ * @param queryParams - Query parameters to compose
+ * @returns Query string (without leading ?)
+ */
+export declare function composeQuery(queryParams?: UrlQueryParams): string;
+/**
+ * Compose a full URL with query parameters
+ * @param url - Base URL
+ * @param queryParams - Optional query parameters
+ * @returns Full URL with query string
+ */
+export declare function composeURL(url: string, queryParams?: UrlQueryParams): string;
 export {};