@luigi-project/core-modular 0.0.10 → 0.0.11-dev.20260720111

package/modules/ux-module.d.ts

@@ -1,42 +1,14 @@
 import { LuigiCompoundContainer, LuigiContainer } from '@luigi-project/container';
 import { Luigi } from '../core-api/luigi';
-export interface AlertSettings {
-    closeAfter?: number;
-    id?: string;
-    links?: Record<string, Link>;
-    text?: string;
-    ttl?: number;
-    type?: string;
-}
-export interface AlertHandler {
-    openFromClient: boolean;
-    close(): void;
-    link(linkKey: string): boolean;
-}
+import { AlertSettings, ConfirmationModalSettings, Link } from '../types/ux';
+export type { AlertHandler, AlertSettings, ConfirmationModalHandler, ConfirmationModalSettings, Link } from '../types/ux';
 export interface ProcessedAlertSettings {
     settings: AlertSettings;
 }
-export interface Link {
-    elemId: string;
-    url?: string;
-    dismissKey?: string;
-}
 export interface ProcessedTextAndLinks {
     sanitizedText: string;
     links: Link[];
 }
-export interface ConfirmationModalSettings {
-    icon?: string;
-    type?: string;
-    header?: string;
-    body?: string;
-    buttonConfirm?: string;
-    buttonDismiss?: string;
-}
-export interface ConfirmationModalHandler {
-    confirm(): void;
-    dismiss(): void;
-}
 export interface UserSettings {
     [key: string]: number | string | boolean;
 }

package/package.json

@@ -18,5 +18,5 @@
     "micro-frontends",
     "microfrontends"
   ],
-  "version": "0.0.10"
+  "version": "0.0.11-dev.20260720111"
 }

package/services/global-search.service.d.ts

@@ -0,0 +1,21 @@
+import { GlobalSearchProvider, SearchResultItem } from '../types/global-search';
+import { Luigi } from '../core-api/luigi';
+export declare class GlobalSearchService {
+    private luigi;
+    isSearchFieldVisible: boolean;
+    isSearchResultVisible: boolean;
+    searchQuery: string;
+    searchResult: SearchResultItem[];
+    constructor(luigi: Luigi);
+    get searchProvider(): GlobalSearchProvider;
+    private getHandler;
+    hasSearchProvider(): boolean;
+    getFieldVisibility(): boolean;
+    setFieldVisibility(value: boolean): void;
+    showSearchResult(searchResultItems: SearchResultItem[]): void;
+    closeSearchResult(): void;
+    getSearchQuery(): string;
+    setSearchQuery(value: string): void;
+    setSearchInputPlaceholder(placeholder?: string): void;
+    toggleSearch(): void;
+}

package/services/navigation.service.d.ts

@@ -1,5 +1,5 @@
 import { Luigi } from '../core-api/luigi';
-import { AppSwitcher, BreadcrumbData, LeftNavData, NavigationOptions, NavigationRequestParams, NavItem, Node, PathData, TabNavData, TopNavData } from '../types/navigation';
+import { AppSwitcher, BadgeCounter, BreadcrumbData, LeftNavData, NavigationOptions, NavigationRequestParams, NavItem, Node, PathData, TabNavData, TopNavData } from '../types/navigation';
 import { ModalService } from './modal.service';
 import { NodeDataManagementService } from './node-data-management.service';
 export declare class NavigationService {
@@ -12,7 +12,10 @@ export declare class NavigationService {
     private getNodeDataManagementService;
     getPathData(path: string): Promise<PathData>;
     findMatchingNode(urlPathElement: string, nodes: Node[]): Node | undefined;
-    buildNavItems(nodes: Node[], selectedNode: Node | undefined, pathData: PathData): NavItem[];
+    buildNavItems(nodes: Node[], selectedNode: Node | undefined, pathData: PathData): Promise<{
+        items: NavItem[];
+        totalBadgeNode: BadgeCounter | undefined;
+    }>;
     getCurrentNode(path: string): Promise<Node | undefined>;
     getPathParams(path: string): Promise<Record<string, any>>;
     /**

package/services/routing.service.d.ts

@@ -134,5 +134,5 @@ export declare class RoutingService {
      * @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>;
+    handleViewUrlMisconfigured(node: Node, viewUrl: string, previousPathData: PathData | undefined, pathUrlRaw: string): Promise<boolean>;
 }

package/types/compound-config.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Configuration for compound web components in Luigi.
+ * Compound allows you to layout multiple web components in one micro frontend.
+ */
+export interface CompoundConfig {
+    /**
+     * Renderer configuration for the compound layout
+     */
+    renderer?: {
+        /**
+         * The renderer to use - can be 'grid', a custom renderer object, or undefined for default
+         */
+        use?: 'grid' | string | {
+            /**
+             * Base renderer to extend (e.g., 'grid')
+             */
+            extends?: string;
+            /**
+             * Custom function to create the compound container
+             * @param config - The renderer configuration
+             * @param renderer - The parent/super renderer (if extending)
+             */
+            createCompoundContainer?: (config: RendererConfig, renderer?: any) => HTMLDivElement;
+            /**
+             * Custom function to create individual compound item containers
+             * @param layoutConfig - Layout configuration for the item
+             * @param config - The overall renderer configuration
+             * @param renderer - The parent/super renderer (if extending)
+             */
+            createCompoundItemContainer?: (layoutConfig?: LayoutConfig, config?: RendererConfig, renderer?: any) => HTMLDivElement;
+            /**
+             * Custom function to attach an item to the compound container
+             * @param compoundCnt - The compound container element
+             * @param compoundItemCnt - The item container to attach
+             * @param renderer - The parent/super renderer (if extending)
+             */
+            attachCompoundItem?: (compoundCnt: HTMLElement, compoundItemCnt: HTMLElement, renderer?: any) => void;
+        };
+        /**
+         * Configuration for the grid layout
+         */
+        config?: {
+            /**
+             * CSS grid-template-columns value (e.g., '1fr 2fr')
+             */
+            columns?: string;
+            /**
+             * CSS grid-template-rows value (e.g., '150px 150px')
+             */
+            rows?: string;
+            /**
+             * CSS grid-gap value (e.g., 'auto', '10px')
+             */
+            gap?: string;
+            /**
+             * Minimum height for the grid container
+             */
+            minHeight?: string;
+            /**
+             * Responsive layout configurations for different viewport sizes
+             */
+            layouts?: Array<{
+                /**
+                 * CSS grid-template-columns for this breakpoint
+                 */
+                columns?: string | number;
+                /**
+                 * CSS grid-template-rows for this breakpoint
+                 */
+                rows?: string | number;
+                /**
+                 * CSS grid-gap for this breakpoint
+                 */
+                gap?: string | number;
+                /**
+                 * Minimum viewport width for this layout (in pixels)
+                 */
+                minWidth?: number;
+                /**
+                 * Maximum viewport width for this layout (in pixels)
+                 */
+                maxWidth?: number;
+            }>;
+        };
+    };
+    /**
+     * Lazy loading configuration for compound children
+     */
+    lazyLoadingOptions?: {
+        /**
+         * Enable lazy loading using IntersectionObserver
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * IntersectionObserver rootMargin option
+         * Controls when children are loaded relative to viewport visibility
+         * @default "0px"
+         */
+        intersectionRootMargin?: string;
+        /**
+         * Default temporary height for child containers before they load
+         * @default "500px"
+         */
+        temporaryContainerHeight?: string;
+        /**
+         * Disable automatic temporary container heights
+         * Useful for custom renderers that manage heights themselves
+         * @default false
+         */
+        noTemporaryContainerHeight?: boolean;
+    };
+    /**
+     * Array of child web component configurations
+     */
+    children?: Array<{
+        /**
+         * Unique identifier for this child web component
+         */
+        id: string;
+        /**
+         * URL pointing to the web component JavaScript file
+         * Supports {i18n.currentLocale} placeholder for localization
+         */
+        viewUrl: string;
+        /**
+         * Context object passed to the web component
+         */
+        context?: Record<string, any>;
+        /**
+         * Layout configuration for positioning this child
+         */
+        layoutConfig?: {
+            /**
+             * CSS grid-row value (e.g., '1 / 3', 'auto')
+             * @default "auto"
+             */
+            row?: string;
+            /**
+             * CSS grid-column value (e.g., '1 / -1', 'auto')
+             * @default "auto"
+             */
+            column?: string;
+            /**
+             * Slot name for nested web components
+             * Use this instead of row/column to plug into a parent's slot
+             */
+            slot?: string;
+            /**
+             * Override the default temporary container height for this specific child
+             * Only used when lazy loading is enabled
+             * * @default undefined
+             */
+            temporaryContainerHeight?: string;
+        };
+        /**
+         * Event listeners for cross-component communication via event bus
+         */
+        eventListeners?: Array<{
+            /**
+             * ID of the source web component (use '*' for any source)
+             */
+            source: string;
+            /**
+             * Name of the event to listen for
+             */
+            name: string;
+            /**
+             * Type of action to perform (e.g., 'update')
+             */
+            action: string;
+            /**
+             * Optional function to convert event data before passing to listener
+             * @param data - The event data
+             */
+            dataConverter?: (data: any) => any;
+        }>;
+    }>;
+}
+/**
+ * Supporting type for layout configuration
+ */
+export interface LayoutConfig {
+    column?: string;
+    row?: string;
+    slot?: string;
+    temporaryContainerHeight?: string;
+}
+/**
+ * Supporting type for renderer configuration
+ */
+export interface RendererConfig {
+    columns?: string;
+    rows?: string;
+    gap?: string;
+    minHeight?: string;
+    layouts?: Array<{
+        columns?: string;
+        rows?: string;
+        gap?: string | number;
+        minWidth?: number;
+        maxWidth?: number;
+    }>;
+}

package/types/connector.d.ts

@@ -1,34 +1,294 @@
-import { AlertHandler, AlertSettings, ConfirmationModalHandler, ConfirmationModalSettings } from '../modules/ux-module';
+import { CoreAPISupportedElements } from './dom-elements';
+import { GlobalSearchHandler } from './global-search';
+import { AlertHandler, AlertSettings, ConfirmationModalHandler, ConfirmationModalSettings } from './ux';
 import { ModalSettings, LeftNavData, Node, TopNavData, TabNavData, BreadcrumbData, DrawerSettings, UserSettingsDialogSettings } from './navigation';
+/**
+ * Integration contract between Luigi's core and a head (shell) implementation.
+ *
+ * A connector adapts Luigi's framework-agnostic core to a concrete UI technology
+ * (UI5 Web Components, Fiori, a custom design system, …). The head implements
+ * this interface and hands an instance to `LuigiEngine.bootstrap(connector)`.
+ *
+ * Core never queries the DOM directly: it asks the connector to render shell
+ * regions, mount micro-frontend containers, and surface alerts/modals/drawers.
+ * In return, core hands the connector either callbacks to invoke (for modal /
+ * drawer lifecycle) or handler objects (for alerts / confirmation modals) so
+ * the connector can report user-driven outcomes back.
+ */
 export interface LuigiConnector {
+    /**
+     * Build the shell chrome (header / side nav / content area / overlays).
+     *
+     * Called once during `UIModule.init`, before any other `render*` method.
+     * The connector should create the DOM slots that subsequent calls will
+     * populate (top nav, left nav, tab nav, breadcrumbs, container wrapper,
+     * alert and confirmation overlays) and should be idempotent — re-invoking
+     * it must not duplicate the layout.
+     */
     renderMainLayout(): void;
+    /**
+     * Render the top navigation (shellbar) from the supplied data.
+     *
+     * Called on initial route resolution and again whenever core's UI update
+     * touches scopes affecting the header (`settings`, `settings.header`,
+     * `navigation`, `navigation.profile`, `navigation.contextSwitcher`,
+     * `navigation.productSwitcher`). Treat the call as a full replace, not an
+     * append — the data describes the complete desired state.
+     *
+     * @param data complete top-nav state to render — title, logo, top-level
+     *   nodes, profile, context/app/product switchers, optional global-search
+     *   config. Any region present should be (re)rendered; absent fields mean
+     *   "hide / remove that region".
+     */
     renderTopNav(data: TopNavData): void;
+    /**
+     * Render the left (side) navigation from the supplied data.
+     *
+     * Called on initial route resolution and on updates touching `navigation`,
+     * `navigation.nodes`, `navigation.viewgroupdata`, `settings`, or
+     * `settings.footer`. Full replace semantics — render `data.items` and
+     * highlight `data.selectedNode`; do not merge with previously rendered
+     * state.
+     *
+     * @param data items to render, the currently selected node to highlight,
+     *   the base path for relative links, an optional footer text, and an
+     *   optional `navClick` handler the connector may invoke on item click in
+     *   place of native navigation.
+     */
     renderLeftNav(data: LeftNavData): void;
+    /**
+     * Return the element into which core appends micro-frontend containers
+     * (`luigi-container` / `luigi-compound-container`).
+     *
+     * Called frequently — on every navigation, by the auth layer, by the
+     * preloading service, and by container helpers. The element should already
+     * exist after `renderMainLayout()`; returning `null`/`undefined` will
+     * suppress mounting and is treated as "no container area available".
+     *
+     * @returns the content-area host element, or `null`/`undefined` if the
+     *   shell has no mount point available yet.
+     */
     getContainerWrapper(): HTMLElement;
-    renderModal(content: HTMLElement, modalSettings: ModalSettings, onCloseCallback?: () => void, onCloseRequest?: () => void): any;
-    renderDrawer(content: HTMLElement, drawerSettings: DrawerSettings, onCloseCallback?: () => void, onCloseRequest?: () => void): any;
+    /**
+     * Render `content` (a `luigi-container` / `luigi-compound-container`) inside
+     * a modal dialog.
+     *
+     * `updateModalSettings` may be called between this method and close to
+     * mutate title / size in place.
+     *
+     * @param content the micro-frontend container element to mount inside the
+     *   dialog. Already constructed by core; the connector only needs to
+     *   append it to its modal DOM.
+     * @param modalSettings dialog presentation — size preset, explicit width /
+     *   height, title, optional `keepPrevious` flag, test-id for the close
+     *   button.
+     * @param onCloseCallback invoked by the connector **once the modal is fully
+     *   closed** (after any dirty-state confirmation has resolved). Drives
+     *   core's modal-stack cleanup and URL bookkeeping.
+     * @param onCloseRequest invoked by the connector **when the user requests
+     *   close** (e.g. clicks the close button). Returns a `Promise<void>` that
+     *   resolves once core has approved the close (dirty-state check passed,
+     *   no unsaved-changes prompt outstanding). The connector should `await`
+     *   this before tearing the modal down.
+     */
+    renderModal(content: HTMLElement, modalSettings: ModalSettings, onCloseCallback?: () => void, onCloseRequest?: () => void): void;
+    /**
+     * Render `content` inside a drawer (slide-in panel).
+     *
+     * @param content the micro-frontend container element to mount inside the
+     *   drawer.
+     * @param drawerSettings drawer presentation — size, overlap mode, optional
+     *   header, whether a backdrop is shown.
+     * @param onCloseCallback invoked by the connector once the drawer has
+     *   closed. See {@link LuigiConnector.renderModal} for the lifecycle
+     *   contract — drawer mirrors modal exactly.
+     * @param onCloseRequest invoked by the connector on user-driven close;
+     *   awaiting the returned promise yields core's approval (dirty-status
+     *   check).
+     */
+    renderDrawer(content: HTMLElement, drawerSettings: DrawerSettings, onCloseCallback?: () => void, onCloseRequest?: () => void): void;
+    /**
+     * Render the tab navigation row for the current node.
+     *
+     * Called alongside `renderLeftNav` whenever the relevant navigation scopes
+     * change. Full replace semantics.
+     *
+     * @param data tab items, the currently selected one, base path for
+     *   relative links, and optional `navClick` handler.
+     */
     renderTabNav(data: TabNavData): void;
+    /**
+     * Render the breadcrumb trail for the current path.
+     *
+     * Called on navigation updates. The `BreadcrumbData` passed in may contain
+     * pending entries whose labels resolve asynchronously — in that case core
+     * calls `renderBreadcrumbs` a second time with the resolved data, so the
+     * connector should accept repeated invocations as a full replace.
+     *
+     * @param data breadcrumb items (each with optional `pending: true` until
+     *   resolved), base path, selected node, and an optional custom renderer.
+     *   `clearBeforeRender` indicates whether the connector should wipe
+     *   existing breadcrumbs before rendering.
+     */
     renderBreadcrumbs(data: BreadcrumbData): void;
+    /**
+     * Surface an alert (toast / message strip) to the user.
+     *
+     * @param alertSettings what to display — text (may contain link tokens
+     *   resolved via `links`), severity `type`, optional auto-close timeout,
+     *   id, and link map.
+     * @param alertHandler connector → core channel for reporting the
+     *   alert's outcome. Invoke `alertHandler.close()` when the alert is
+     *   dismissed (auto-timeout or user action) and
+     *   `alertHandler.link(linkKey)` when the user activates a link embedded
+     *   in the text. `alertHandler.openFromClient` indicates whether the alert
+     *   originated from a micro-frontend (used by core for routing of the
+     *   outcome).
+     */
     renderAlert(alertSettings: AlertSettings, alertHandler: AlertHandler): void;
+    /**
+     * Surface a confirmation modal (yes/no dialog).
+     *
+     * Used both for app-level confirmations (`Luigi.ux().showConfirmationModal`)
+     * and for the dirty-state unsaved-changes flow — the connector does not
+     * need to distinguish.
+     *
+     * @param confirmationModalSettings header, body text, button labels,
+     *   optional icon and semantic `type`.
+     * @param containerHandler connector → core channel. Invoke
+     *   `containerHandler.confirm()` or `containerHandler.dismiss()` based on
+     *   the user's choice; core handles the rest.
+     */
     renderConfirmationModal(confirmationModalSettings: ConfirmationModalSettings, containerHandler: ConfirmationModalHandler): void;
+    /**
+     * Set the browser document title.
+     *
+     * Called from `Luigi.ux().setDocumentTitle()` and on `SET_DOCUMENT_TITLE_REQUEST`
+     * from a micro-frontend. The connector typically forwards to
+     * `document.title`; it may additionally reflect the title in UI (e.g. an
+     * acknowledgement toast).
+     *
+     * @param documentTitle new title string.
+     */
     setDocumentTitle(documentTitle: string): void;
-    getDocumentTitle(): string;
+    /**
+     * Show a loading indicator. Called during navigation, on
+     * `SHOW_LOADING_INDICATOR_REQUEST` from a client, and around modal/drawer
+     * open.
+     *
+     * @param container when provided, scope the indicator to this subtree
+     *   (typically the parent of a micro-frontend container that is still
+     *   handshaking). When omitted, fall back to a shell-wide busy indicator.
+     */
     showLoadingIndicator(container?: HTMLElement): void;
+    /**
+     * Hide a previously shown loading indicator. Called once a micro-frontend
+     * reports `INITIALIZED`, when navigation completes, and on
+     * `HIDE_LOADING_INDICATOR_REQUEST` from a client.
+     *
+     * @param container scoping rules match {@link LuigiConnector.showLoadingIndicator}.
+     */
     hideLoadingIndicator(container?: HTMLElement): void;
+    /**
+     * Show a page-level backdrop, typically dimming the main content while a
+     * micro-frontend displays its own overlay.
+     *
+     * Core does not refcount calls — it mirrors client `ADD_BACKDROP_REQUEST`
+     * events one-to-one. If a connector needs nesting semantics it must
+     * implement them itself.
+     */
     addBackdrop(): void;
+    /**
+     * Hide the page-level backdrop. Counterpart to `addBackdrop`; same
+     * no-refcount caveat applies.
+     */
     removeBackdrop(): void;
-    openUserSettings(dialogSettings: UserSettingsDialogSettings, userSettingData: any[], previousUserSettings: any): void;
+    /**
+     * Open the user-settings dialog.
+     *
+     * Core invokes `dialogSettings.renderMicroFrontendContainer(viewUrl, groupKey)`
+     * (which it installs before calling this method) to mount per-group MFEs
+     * inside the dialog, and `dialogSettings.onCloseCallback(stored, previous)`
+     * when the dialog closes — the connector is responsible for calling both
+     * at the appropriate moments.
+     *
+     * @param dialogSettings dialog header, save/dismiss button labels, plus
+     *   the two core-installed hooks (`renderMicroFrontendContainer`,
+     *   `onCloseCallback`) the connector must invoke.
+     * @param userSettingData static schema describing the available
+     *   user-settings groups (one entry per group).
+     * @param previousUserSettings persisted user-settings state to prefill
+     *   the dialog with, or `null` on first open.
+     */
+    openUserSettings(dialogSettings: UserSettingsDialogSettings, userSettingData: Record<string, any>[], previousUserSettings: Record<string, any> | null): void;
+    /**
+     * Close a user-settings dialog opened via `openUserSettings`.
+     * Called from `Luigi.ux().closeUserSettings()` and on
+     * `CLOSE_USER_SETTINGS_REQUEST` from a client.
+     */
     closeUserSettings(): void;
+    /**
+     * Notify the connector that Luigi's current locale changed.
+     *
+     * Push-only — heads typically use this to re-translate shell chrome or to
+     * reflect the change in their own UI.
+     *
+     * @param locale BCP-47 locale tag (e.g. `'en'`, `'de-DE'`).
+     */
     setCurrentLocale(locale: string): void;
-    getCurrentLocale(): string;
+    /**
+     * Apply updated settings to the currently open modal (title, size, …).
+     *
+     * Called from `Luigi.ux().updateModalSettings()`, from client
+     * `UPDATE_MODAL_SETTINGS_REQUEST`, and from the routing service when
+     * modal-in-URL state changes. No-op if no modal is open (core guards
+     * before forwarding).
+     *
+     * @param modalSettings the **merged** result (existing settings ⊕
+     *   updates) — apply as-is, do not attempt to diff against previous
+     *   state.
+     */
     updateModalSettings(modalSettings: ModalSettings): void;
+    /**
+     * Display an unrecoverable error and halt further interaction.
+     *
+     * Currently invoked only for fatal config-loading failures
+     * (`config-helpers.ts → setErrorMessage`). Not a general runtime-error
+     * channel — those flow through `runTimeErrorHandler` on nodes.
+     *
+     * @param error human-readable error message to display.
+     */
     showFatalError(error: string): void;
-    getCoreAPISupportedElements(): {
-        getShellbarElement(): HTMLElement | null;
-        getShellbarActions(): HTMLElement | null;
-        getLuigiContainer(): HTMLElement | null;
-        getNavFooterContainer(): HTMLElement | null;
-    };
+    /**
+     * Return a bag of getters for shell-owned DOM regions that micro-frontends
+     * can reach via `Luigi.elements()` (shellbar, shellbar actions, the Luigi
+     * container, the side-nav footer area).
+     *
+     * Each getter is invoked lazily on access, so the connector may resolve
+     * elements at call time rather than caching them at construction.
+     *
+     * @returns an object exposing one getter per supported shell region; each
+     *   returns the element if present, or `null` if the region is not part
+     *   of this head's layout.
+     */
+    getCoreAPISupportedElements(): CoreAPISupportedElements;
+    /**
+     * Tear down all shell DOM and listeners created by the connector.
+     *
+     * Called from `Luigi.unload()`. After this, core may later call
+     * `renderMainLayout()` again on a fresh `Luigi.setConfig()` cycle, so the
+     * connector must leave itself in a state where re-bootstrapping works.
+     */
     unload(): void;
+    /**
+     * Return an imperative handle for driving the global-search UI, or omit
+     * this method entirely if the head does not surface global search. Core
+     * calls the returned handler in response to `Luigi.globalSearch().*` API
+     * calls and search-related navigation.
+     *
+     * @returns the global-search handler, or `undefined` if the head exposes
+     *   no search UI at this moment.
+     */
+    getGlobalSearchHandler?(): GlobalSearchHandler;
 }
 export type { Node };

package/types/dom-elements.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DOM elements the connector exposes to Luigi's core API.
+ *
+ * Returned from `LuigiConnector.getCoreAPISupportedElements()` and consumed by
+ * `Luigi.elements()` to give micro-frontend authors access to shell-owned
+ * regions of the page.
+ */
+export interface CoreAPISupportedElements {
+    getShellbarElement(): HTMLElement | null;
+    getShellbarActions(): HTMLElement | null;
+    getLuigiContainer(): HTMLElement | null;
+    getNavFooterContainer(): HTMLElement | null;
+}