@luigi-project/core-modular 0.0.7-dev.20260520101 → 0.0.7-dev.202605270112

package/package.json

@@ -18,5 +18,5 @@
     "micro-frontends",
     "microfrontends"
   ],
-  "version": "0.0.7-dev.20260520101"
+  "version": "0.0.7-dev.202605270112"
 }

package/services/dirty-status.service.d.ts

@@ -1,4 +1,6 @@
+import { Luigi } from '../core-api/luigi';
 export declare class DirtyStatusService {
+    private luigi;
     unsavedChanges: {
         isDirty?: boolean;
         persistUrl?: string | null;
@@ -8,7 +10,7 @@ export declare class DirtyStatusService {
      * Initializes the `unsavedChanges` property with default values.
      * Sets `isDirty` to `false` and `persistUrl` to `null`, indicating that there are no unsaved changes initially.
      */
-    constructor();
+    constructor(luigi: Luigi);
     /**
      * Updates the dirty status of a given source and manages the set of unsaved changes.
      *
@@ -38,4 +40,6 @@ export declare class DirtyStatusService {
      * @returns {boolean} `true` if there are unsaved changes, otherwise `false`.
      */
     readDirtyStatus(): boolean;
+    getUnsavedChangesModalPromise(source?: any): Promise<void>;
+    shouldShowUnsavedChangesModal(source?: any): boolean;
 }

package/services/i18n.service.d.ts

@@ -1,4 +1,3 @@
-import { LuigiContainer, LuigiCompoundContainer } from '@luigi-project/container';
 import { Luigi } from '../core-api/luigi';
 /**
  * Localization-related functions
@@ -21,7 +20,7 @@ export declare class i18nService {
      * Sets current locale to the specified one.
      * @param {string} locale locale to be set as the current locale
      */
-    setCurrentLocale(locale: string, containerElement?: LuigiContainer | LuigiCompoundContainer): void;
+    setCurrentLocale(locale: string): void;
     /**
      * Registers a listener for locale changes.
      * @param {Function} listener function called on every locale change with the new locale as argument

package/services/modal.service.d.ts

@@ -49,4 +49,5 @@ export declare class ModalService {
      * Removes the last modal from the stack.
      */
     removeLastModalFromStack(): void;
+    closeModalsWithDirtyCheck(): Promise<boolean>;
 }

package/services/navigation.service.d.ts

@@ -26,7 +26,7 @@ export declare class NavigationService {
     getTruncatedChildren(children: Node[]): Node[];
     applyNavGroups(items: NavItem[]): NavItem[];
     getLeftNavData(path: string, pData?: PathData): Promise<LeftNavData>;
-    navItemClick(node: Node, pathData?: PathData): void;
+    navItemClick(node: Node, pathData?: PathData): Promise<void>;
     getTopNavData(path: string, pData?: PathData): Promise<TopNavData>;
     getParentNode(node: Node | undefined, pathData: PathData): Node | undefined;
     getAppSwitcherData(appSwitcherData: AppSwitcher, headerSettings: any): AppSwitcher | undefined;

package/services/preloading.service.d.ts

@@ -0,0 +1,58 @@
+import { Luigi } from '../core-api/luigi';
+import { ViewGroupSettings } from '../types/navigation';
+/**
+ * Service responsible for preloading view group containers in the background.
+ *
+ * Preloading creates hidden luigi-container elements for configured view groups
+ * so that navigating to those groups later is near-instant (the MFE is already initialized).
+ * The service adapts its batch size dynamically based on observed MFE load times.
+ */
+export declare class PreloadingService {
+    private luigi;
+    private preloadBatchSize;
+    shouldPreload: boolean;
+    constructor(luigi: Luigi);
+    /**
+     * Preloads view group containers based on the `navigation.viewGroupSettings` configuration.
+     * Skips view groups that already have a container in the DOM or are currently being preloaded.
+     *
+     * @param batchSize - Maximum number of view groups to preload in this cycle (default: 3).
+     * @param backgroundMfeOnly - If true, only preloads view groups with `loadOnStartup: true`.
+     *   Used during application init to load critical MFEs without competing with the main navigation.
+     */
+    preloadViewGroups(batchSize?: number, backgroundMfeOnly?: boolean): void;
+    /**
+     * Creates a hidden luigi-container for the given view group and appends it to the DOM.
+     * The container loads the `preloadUrl` MFE in the background with `display: none`.
+     *
+     * @param settings - The view group settings containing the preloadUrl.
+     * @param name - The view group name (used as identifier on the container).
+     * @param containerWrapper - The DOM element to append the hidden container to.
+     */
+    preloadContainerOnBackground(settings: ViewGroupSettings, name: string, containerWrapper: HTMLElement): void;
+    /**
+     * Schedules a preload cycle. Uses a flag-based mechanism to skip the very first invocation
+     * and only trigger preloading from the second call onwards.
+     *
+     * @param backgroundMfeOnly - If true, only `loadOnStartup` view groups are preloaded.
+     *   Passed through to `preloadViewGroups`.
+     */
+    preload(backgroundMfeOnly?: boolean): void;
+    /**
+     * Called when a preloaded container has finished initializing (INITIALIZED event).
+     * Measures load time and adapts the batch size for subsequent preload cycles:
+     * - < 500ms  → batchSize 3 (fast connection)
+     * - 500–1000ms → batchSize 2
+     * - > 1000ms → batchSize 1 (slow, be conservative)
+     *
+     * Also schedules clearing the `_luigiPreloading` flag after a short delay,
+     * freeing the container for the next preload cycle.
+     *
+     * @param container - The container element that finished loading.
+     */
+    viewGroupLoaded(container: any): void;
+    /**
+     * Returns all containers in the wrapper that are currently in a preloading state.
+     */
+    private getPreloadingContainers;
+}

package/services/routing.service.d.ts

@@ -2,9 +2,11 @@ import { Luigi } from '../core-api/luigi';
 import { Route } from '../types/routing';
 import { ModalSettings, Node, PathData } from '../types/navigation';
 import { NavigationService } from './navigation.service';
+import { DirtyStatusService } from './dirty-status.service';
 export declare class RoutingService {
     private luigi;
     navigationService?: NavigationService;
+    dirtyStatusService?: DirtyStatusService;
     previousNode: Node | undefined;
     currentRoute?: Route;
     modalSettings?: ModalSettings;
@@ -123,4 +125,14 @@ export declare class RoutingService {
      * @returns {Promise<void>} A promise that resolves when error handling is complete.
      */
     showPageNotFoundError(pathToRedirect: string, notFoundPath: string, isAnyPathMatched?: boolean): Promise<void>;
+    /**
+     * Handles viewUrl misconfiguration scenario. If a node has no viewUrl, no children,
+     * and is not a compound node, it redirects to the root default child node.
+     * @param node - active node data
+     * @param viewUrl - the url of the current mf view
+     * @param previousPathData - previous path data
+     * @param pathUrlRaw - path url without hash
+     * @returns true if misconfiguration was detected and handled
+     */
+    handleViewUrlMisconfigured(node: Node, viewUrl: string, previousPathData: PathData, pathUrlRaw: string): Promise<boolean>;
 }

package/types/connector.d.ts

@@ -6,7 +6,7 @@ export interface LuigiConnector {
     renderLeftNav(data: LeftNavData): void;
     getContainerWrapper(): HTMLElement;
     renderModal(content: HTMLElement, modalSettings: ModalSettings, onCloseCallback?: () => void, onCloseRequest?: () => void): any;
-    renderDrawer(content: HTMLElement, modalSettings: DrawerSettings, onCloseCallback?: () => void): any;
+    renderDrawer(content: HTMLElement, drawerSettings: DrawerSettings, onCloseCallback?: () => void, onCloseRequest?: () => void): any;
     renderTabNav(data: TabNavData): void;
     renderBreadcrumbs(data: BreadcrumbData): void;
     renderAlert(alertSettings: AlertSettings, alertHandler: AlertHandler): void;
@@ -29,5 +29,6 @@ export interface LuigiConnector {
         getLuigiContainer(): HTMLElement | null;
         getNavFooterContainer(): HTMLElement | null;
     };
+    unload(): void;
 }
 export type { Node };

package/types/navigation.d.ts

@@ -5,7 +5,7 @@ export interface TopNavData {
     productSwitcher?: ProductSwitcher;
     profile?: ProfileSettings;
     appSwitcher?: AppSwitcher;
-    navClick?: (item: NavItem) => void;
+    navClick?: (item: NavItem) => Promise<void>;
 }
 export interface AppSwitcher {
     showMainAppEntry?: boolean;
@@ -33,8 +33,13 @@ export interface ProfileSettings {
     items?: ProfileItem[];
     staticUserInfoFn?: () => Promise<UserInfo>;
     onUserInfoUpdate: (fn: (uInfo: UserInfo) => void) => void;
+    settings: UserSettingsProfileMenuEntry;
     itemClick: (item: ProfileItem) => void;
 }
+export interface UserSettingsProfileMenuEntry {
+    label?: string;
+    link?: string;
+}
 export interface ProfileLogout {
     label?: string;
     icon?: string;
@@ -63,7 +68,7 @@ export interface LeftNavData {
     items: NavItem[];
     basePath: string;
     sideNavFooterText?: string;
-    navClick?: (item: NavItem) => void;
+    navClick?: (item: NavItem) => Promise<void>;
 }
 export interface PathData {
     context?: Record<string, any>;
@@ -98,9 +103,11 @@ export interface Node {
     hideFromNav?: boolean;
     hideSideNav?: boolean;
     icon?: string;
+    intendToHaveEmptyViewUrl?: boolean;
     isRootNode?: boolean;
     keepSelectedForChildren?: boolean;
     label?: string;
+    link?: string;
     loadingIndicator?: {
         enabled: boolean;
     };
@@ -128,6 +135,7 @@ export interface Node {
     _virtualTree?: Node;
     _virtualPathIndex?: number;
     _virtualViewUrl?: string;
+    _rawContext?: Record<string, any>;
 }
 export interface PageErrorHandler {
     timeout: number;
@@ -158,6 +166,7 @@ export interface BreadcrumbItem {
 export interface NavItem {
     altText?: string;
     category?: Category;
+    href?: string;
     icon?: string;
     node?: Node;
     label?: string;
@@ -168,7 +177,7 @@ export interface TabNavData {
     selectedNode?: any;
     items?: NavItem[];
     basePath?: string;
-    navClick?: (item: NavItem) => void;
+    navClick?: (item: NavItem) => Promise<void>;
 }
 export interface BreadcrumbData {
     basePath?: string;
@@ -229,6 +238,7 @@ export interface NavigationRequestBase {
 }
 export interface NavigationRequestParams extends NavigationRequestBase {
     drawerSettings?: any;
+    intent?: boolean;
     modalSettings?: any;
     newTab?: boolean;
     path: string;
@@ -465,4 +475,8 @@ export interface TitleResolver {
     /** @internal runtime cache – not user-configured */
     _cache?: TitleResolverCache;
 }
+export interface ViewGroupSettings {
+    preloadUrl?: string;
+    loadOnStartup?: boolean;
+}
 export type HistoryMethod = 'pushState' | 'replaceState';

package/utilities/helpers/generic-helpers.d.ts

@@ -124,7 +124,7 @@ export declare const GenericHelpers: {
      * @param parenthesis
      * @returns
      */
-    replaceVars(inputString: string, params: Record<string, any>, prefix: string, parenthesis?: boolean): string;
+    replaceVars(inputString: string, params: Record<string, any>, prefix: string, parenthesis?: boolean, slashStop?: boolean): string;
     /**
      *  Escapes special characters in a string for use in a regular expression.
      * @param string

package/utilities/helpers/i18n-helpers.d.ts

@@ -0,0 +1,3 @@
+export declare class I18nHelpers {
+    static hasLocaleChangePermission(containerElement: any): boolean;
+}

package/utilities/helpers/navigation-helpers.d.ts

@@ -8,10 +8,9 @@ export declare const NavigationHelpers: {
     checkVisibleForFeatureToggles: (nodeToCheckPermission: any, featureToggles: FeatureToggles) => boolean;
     generateTooltipText: (node: Node, translation: string, luigi: Luigi) => string;
     isNodeAccessPermitted: (nodeToCheckPermissionFor: Node, parentNode: Node | undefined, currentContext: Record<string, any>, luigi: Luigi) => boolean;
-    applyContext: (context: Record<string, any>, addition: Record<string, any>, navigationContext: any) => Record<string, any>;
     updateHeaderTitle: (appSwitcherData: AppSwitcher, pathData: PathData) => string | undefined;
     buildPath(pathToLeftNavParent: Node[], pathData?: PathData): string;
-    mergeContext(...objs: Record<string, any>[]): Record<string, any>;
+    mergeContext(base: Record<string, any>, addition?: Record<string, any>, navigationContext?: string): Record<string, any>;
     prepareForTests(...parts: string[]): string;
     /**
      * Finds the virtual tree root node for a given node by traversing up the node hierarchy until it finds a node with the virtualTree property set to true. If no such node is found, it returns undefined.

package/utilities/helpers/routing-helpers.d.ts

@@ -80,19 +80,100 @@ export declare const RoutingHelpers: {
      * @returns An object containing only the permitted search parameters for the client.
      */
     prepareSearchParamsForClient(currentNode: Node, luigi: Luigi): {};
+    /**
+     * Checks if given path contains intent navigation special syntax
+     * @param {string} path - path to be checked
+     */
+    hasIntent(path: string): boolean;
+    /**
+     * This function takes an intentLink and parses it conforming certain limitations in characters usage.
+     * Limitations include:
+     *  - `semanticObject` allows only alphanumeric characters
+     *  - `action` allows alphanumeric characters and the '_' sign
+     *
+     * Example of resulting output:
+     * ```
+     *  {
+     *    semanticObject: "Sales",
+     *    action: "order",
+     *    params: {param1: "value1",param2: "value2"}
+     *  };
+     * ```
+     * @param {string} intentLink - the intent link represents the semantic intent defined by the user, i.e.: #?intent=semanticObject-action?param=value
+     */
+    getIntentObject(intentLink: string): Record<string, any> | undefined;
+    /**
+     * This function compares the intentLink parameter with the configuration intentMapping
+     * and returns the path segment that is matched together with the parameters, if any
+     *
+     * Example:
+     *
+     * For intentLink = `#?intent=Sales-order?foo=bar`
+     * and Luigi configuration:
+     * ```
+     * intentMapping: [{
+     *   semanticObject: 'Sales',
+     *   action: 'order',
+     *   pathSegment: '/projects/pr2/order'
+     * }]
+     *
+     * ```
+     * the given intentLink is matched with the configuration's same semanticObject and action,
+     * resulting in pathSegment `/projects/pr2/order` being returned. The parameter is also added in
+     * this case resulting in: `/projects/pr2/order?~foo=bar`
+     *
+     * Or for external intent links: intentLink = `#?intent=External-view`
+     * and Luigi configuration:
+     * ```
+     * intentMapping: [{
+     *   semanticObject: 'External',
+     *   action: 'view',
+     *   externalLink: { url: 'https://www.sap.com', openInNewTab: true }
+     * }]
+     * ```
+     * The resulting will be returned from this function:
+     * ```
+     * {
+     *   url: 'https://www.sap.com',
+     *   openInNewTab: true,
+     *   external: true
+     * }
+     * ```
+     * @param {string} intentLink - the intentLink represents the semantic intent defined by the user, i.e.: #?intent=semanticObject-action?param=value
+     * @param luigi - Luigi instance used to access configuration values
+     */
+    getIntentPath(intentLink: string, luigi: Luigi): boolean | string | Record<string, any>;
+    /**
+     * This function takes a path which contains dynamic parameters and a list parameters and replaces the dynamic parameters
+     * with the given parameters if any. The input path remains unchanged if the parameters list
+     * does not contain the respective dynamic parameter name.
+     * e.g.:
+     * Assume either of these two calls are made:
+     * 1. `LuigiClient.linkManager().navigateToIntent('Sales-settings', {project: 'pr2', user: 'john'})`
+     * 2. `LuigiClient.linkManager().navigate('/#?intent=Sales-settings?project=pr2&user=john')`
+     * For both 1. and 2., the following dynamic input path: `/projects/:project/details/:user`
+     * is resolved through this method to `/projects/pr2/details/john`
+     *
+     * @param {string} path - the path containing the potential dynamic parameter
+     * @param {Object} parameters - a list of objects consisting of passed parameters
+     */
+    resolveDynamicIntentPath(path: string, parameters: object): string;
     /**
      * Retrieves the current path and query string from the browser's location hash.
      *
+     * @param hashRouting - true if hash routing is active, false if path routing is active
+     * @param luigi - Luigi instance used to access configuration values
      * @returns An object containing the normalized path and the query string.
      * @remarks
      * - The path is normalized using `NavigationHelpers.normalizePath`.
      * - The query string is extracted from the portion after the '?' in the hash.
      * - If there is no query string, `query` will be `undefined`.
      */
-    getCurrentPath(hashRouting?: boolean): {
+    getCurrentPath(luigi: Luigi, hashRouting?: boolean, checkIntent?: boolean): {
         path: string;
         query: string;
     };
+    handleExternalIntentPath(intentPath: Record<string, any>): void;
     /**
      * Retrieves the modal path from the current URL's query parameters based on the provided Luigi instance.
      *
@@ -163,7 +244,7 @@ export declare const RoutingHelpers: {
     getModalParamsFromPath(luigi: Luigi): any;
     /**
      * Get the query param separator which is used with hashRouting
-     * Default: :
+     * Default:
      * @example /home?modal=(urlencoded)/some-modal?modalParams=(urlencoded){...}&otherParam=hmhm
      * @returns the first query param separator (like ? for path routing)
      */
@@ -323,7 +404,31 @@ export declare const RoutingHelpers: {
      * @returns a string representing the full route from the root to the given node, including query parameters if provided.
      */
     buildRoute(node: Node, path: string, params?: string): string;
-    substituteViewUrl(node: Node, pathParams: Record<string, string>, luigi: Luigi): string;
+    /**
+     * Resolves the final view URL for a given node by substituting dynamic placeholders with actual values.
+     *
+     * Performs the following substitutions in order:
+     * 1. Removes `{virtualTreePath}` if the node is a virtual tree.
+     * 2. Replaces path parameters (e.g. `:id`) with their concrete values from `pathParams`.
+     * 3. Replaces context variables (e.g. `{context.myVar}`) with values from `node.context`.
+     * 4. Replaces node parameter variables (e.g. `{nodeParams.myParam}`) with values from `nodeParams`.
+     * 5. Replaces `{i18n.currentLocale}` with the current locale.
+     * 6. Replaces `{routing.queryParams.<key>}` with the corresponding search parameter value,
+     *    or removes the query parameter from the URL if the value is not present.
+     *
+     * @param node - The navigation node containing the `viewUrl` template and optional `context`/`virtualTree` properties.
+     * @param pathParams - A map of path parameter names to their resolved values (e.g. `{ id: '42' }`).
+     * @param nodeParams - A map of node-specific parameters passed to the micro frontend.
+     * @param luigi - The Luigi instance used to access i18n, routing, and configuration.
+     * @returns The fully resolved view URL string, or an empty string if `node.viewUrl` is not defined.
+     */
+    substituteViewUrl(node: Node, pathParams: Record<string, string>, nodeParams: Record<string, any>, luigi: Luigi): string;
+    /**
+     * Returns the viewUrl with current locale, e.g. luigi/{i18n.currentLocale}/ -> luigi/en
+     * if viewUrl contains {i18n.currentLocale} term, it will be replaced by current locale
+     * @param viewUrl
+     */
+    getI18nViewUrl(viewUrl: string, luigi: Luigi): string;
     /**
      *  Generates a sub-path for a given node by replacing dynamic parameters in the node's path with actual values from pathParams.
      * @param node - The node for which to generate the sub-path. It is expected to have a `pathSegment` property and optionally a `parent` property pointing to its parent node.
@@ -343,4 +448,31 @@ export declare const RoutingHelpers: {
      * @returns A string representing the concatenated path, with exactly one '/' character between the base and relative paths.
      */
     concatenatePath(basePath: any, relativePath?: any): string;
+    /**
+     * Returns the resolved route link for a navigation node. If the node has an external link, its URL is returned directly.
+     * If the node has an internal link, the prefix is prepended. Otherwise, the full route is built from the node's path
+     * segments and path parameters are substituted.
+     * @param node - The navigation node to resolve the link for
+     * @param pathParams - Dynamic path parameters to substitute in the route
+     * @param relativePathPrefix - Prefix to prepend to relative paths (e.g. '#' for hash routing)
+     * @returns The resolved route link as a string
+     */
+    getRouteLink(node: Node, pathParams: Record<string, any>, relativePathPrefix: string): string;
+    /**
+     * Calculates the full href for a navigation node, taking hash routing and i18n view URLs into account.
+     * @param node - The navigation node to calculate the href for
+     * @param pathParams - Dynamic path parameters to substitute in the route
+     * @param luigi - The Luigi instance used to read routing configuration
+     * @returns The fully resolved href string for the node
+     */
+    calculateNodeHref(node: Node, pathParams: Record<string, any>, luigi: Luigi): string;
+    /**
+     * Returns the href for a navigation node if the `navigation.addNavHrefs` configuration is enabled.
+     * This is used to populate anchor `href` attributes for accessibility and native browser behavior.
+     * @param node - The navigation node to get the href for
+     * @param pathParams - Dynamic path parameters to substitute in the route
+     * @param luigi - The Luigi instance used to read configuration
+     * @returns The node href string if `addNavHrefs` is enabled, otherwise `undefined`
+     */
+    getNodeHref(node: Node, pathParams: Record<string, any>, luigi: Luigi): string | undefined;
 };