oip-common 0.6.4 → 0.7.0

package/index.d.ts

@@ -3,7 +3,7 @@ import { OnDestroy, OnInit, DestroyRef, WritableSignal, OnChanges, SimpleChanges
 import * as rxjs from 'rxjs';
 import { Observable, BehaviorSubject, Subscription, Subject } from 'rxjs';
 import { MessageService, ToastMessageOptions, ConfirmationService, MenuItem, FilterMetadata } from 'primeng/api';
-import { Router, ActivatedRoute, QueryParamsHandling, IsActiveMatchOptions, Params, CanActivateChildFn } from '@angular/router';
+import { Router, ActivatedRoute, QueryParamsHandling, IsActiveMatchOptions, Params, CanActivateChildFn, UrlTree, CanActivateFn, Routes, Route } from '@angular/router';
 import { TranslationObject, InterpolationParameters, Translation, TranslateService } from '@ngx-translate/core';
 import { ContextMenu } from 'primeng/contextmenu';
 import { PaletteDesignToken, Preset } from '@primeuix/themes/types';
@@ -349,6 +349,45 @@ interface PutSecurityDto {
     securities: SecurityDto[];
 }
 
+/**
+ * Tracks whether the application is switching between modules.
+ *
+ * Two sources feed the state:
+ * - router navigation, from `NavigationStart` until the navigation ends, is cancelled or fails;
+ * - explicit work registered with {@link begin}/{@link end} or {@link track}, which covers everything
+ *   running after `NavigationEnd`: module instance rights, settings and extension loading.
+ *
+ * The UI blocker rendered by the layout observes {@link loading}.
+ */
+declare class ModuleLoadingService {
+    /** Releases a stuck blocker when a caller never balances its `begin()`. */
+    private static readonly watchdogTimeoutMs;
+    private readonly router;
+    private readonly navigating;
+    private readonly pending;
+    private watchdogHandle?;
+    /** True while a module transition is in progress. */
+    readonly loading: i0.Signal<boolean>;
+    constructor();
+    /**
+     * Registers one unit of loading work. Every call must be balanced with {@link end},
+     * preferably from a `finally` block. Prefer {@link track} when the work is a promise.
+     */
+    begin(): void;
+    /** Releases one unit of loading work registered with {@link begin}. */
+    end(): void;
+    /**
+     * Blocks the UI until `work` settles, and keeps the blocker released when it rejects.
+     *
+     * @example
+     * await this.moduleLoading.track(this.reloadModuleInstance());
+     */
+    track<T>(work: PromiseLike<T>): Promise<T>;
+    private armWatchdog;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ModuleLoadingService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ModuleLoadingService>;
+}
+
 declare abstract class BaseModuleComponent<TBackendStoreSettings, TLocalStoreSettings> implements OnInit, OnDestroy {
     private static readonly readRight;
     private static readonly editRight;
@@ -360,6 +399,7 @@ declare abstract class BaseModuleComponent<TBackendStoreSettings, TLocalStoreSet
     protected securitySettings: SecurityDto[];
     protected readonly destroyRef: DestroyRef;
     protected readonly securityService: SecurityService;
+    protected readonly moduleLoadingService: ModuleLoadingService;
     protected readonly httpClient: HttpClient<any>;
     /**
      * Provide access to app settings
@@ -732,6 +772,10 @@ interface ModuleInstanceDto {
     parentId?: number | null;
     order?: number;
     separator?: boolean;
+    isStart?: boolean;
+}
+interface SetStartModuleParams {
+    id: number;
 }
 interface GetModuleInstanceRightsParams {
     id?: number;
@@ -745,6 +789,8 @@ interface ChangeOrderParams {
 }
 
 interface ContextMenuItemDto {
+    moduleInstanceId: number;
+    isStart?: boolean;
     url: any;
     class: string | string[] | Set<string> | {
         [p: string]: any;
@@ -828,6 +874,8 @@ declare class MenuService {
 
 declare class MenuApi<SecurityDataType = unknown> extends HttpClient<SecurityDataType> {
     get: (params?: RequestParams) => Promise<ModuleInstanceDto[]>;
+    setStartModule: ({ id, ...query }: SetStartModuleParams, params?: RequestParams) => Promise<void>;
+    deleteStartModule: (params?: RequestParams) => Promise<void>;
     getModuleInstanceRights: (query: GetModuleInstanceRightsParams, params?: RequestParams) => Promise<string[]>;
     getAdminMenu: (params?: RequestParams) => Promise<ModuleInstanceDto[]>;
     getModules: (params?: RequestParams) => Promise<IntKeyValueDto[]>;
@@ -876,6 +924,7 @@ declare class MenuItemEditDialogComponent {
     visible: boolean;
     visibleChange: EventEmitter<boolean>;
     roles: string[];
+    moduleName: string;
     iconOptions: PrimeIconOption[];
     item: EditModuleInstanceDto;
     saving: boolean;
@@ -1176,6 +1225,12 @@ declare class AppConfiguratorComponent implements OnInit {
     private readonly themePresets;
     private readonly themePresetsMap;
     private readonly defaultThemePreset;
+    /**
+     * Presets resolved so far, keyed by theme id. Seeded with the eagerly provided ones and filled in
+     * as loaders resolve; it is a signal so the color swatches recompute once a preset arrives.
+     */
+    private readonly resolvedPresets;
+    private readonly pendingPresets;
     private readonly fallbackPrimaryColors;
     presets: {
         label: string;
@@ -1231,12 +1286,21 @@ declare class AppConfiguratorComponent implements OnInit {
     };
     private getThemePresets;
     private getThemeById;
+    /**
+     * The preset of a theme, or `undefined` while its loader is still in flight.
+     */
+    private getResolvedPreset;
+    /**
+     * Resolves a theme preset, running its loader at most once and caching the result.
+     * A failed load falls back to the default preset so the configurator stays usable.
+     */
+    private loadPreset;
     private getPrimaryColorOptions;
     private getSurfaceColorOptions;
     private ensureValidThemeId;
     updateColors(event: MouseEvent, type: string, color: SurfacesType): void;
     applyTheme(type: string, color: SurfacesType): void;
-    onPresetChange(event: string): void;
+    onPresetChange(event: string): Promise<void>;
     onMenuModeChange(event: string): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<AppConfiguratorComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<AppConfiguratorComponent, "app-configurator", never, {}, {}, never, never, true, never>;
@@ -1423,7 +1487,9 @@ declare class ExtensionModuleHostComponent extends BaseModuleComponent<unknown,
     protected onSecurityRightsChange(): void;
     ngOnDestroy(): void;
     private loadExtensionMetadata;
+    /** Blocks the UI while the extension is (re)mounted, including the queued render after the view init. */
     private renderExtension;
+    private renderExtensionInternal;
     private queueRenderExtension;
     private destroyExtensionComponent;
     private renderFederatedExtension;
@@ -1521,6 +1587,51 @@ declare class AppTopbarApplicationSwitcherComponent implements OnInit {
     static ɵcmp: i0.ɵɵComponentDeclaration<AppTopbarApplicationSwitcherComponent, "app-topbar-application-switcher", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Full screen blocker shown while the application switches between modules.
+ *
+ * Render it as a sibling of `.layout-wrapper`, not inside it: while the blocker is visible the
+ * wrapper is marked `inert`, which would also disable an overlay nested in it.
+ *
+ * The blocker appears only when a transition outlasts {@link showDelayMs} and then stays for at
+ * least {@link minVisibleMs}, so quick navigation does not flash a spinner.
+ */
+declare class BlockLoaderComponent implements OnDestroy {
+    private static readonly showDelayMs;
+    private static readonly minVisibleMs;
+    private readonly translations;
+    private readonly moduleLoadingService;
+    private showHandle?;
+    private hideHandle?;
+    private shownAt;
+    protected readonly visible: i0.WritableSignal<boolean>;
+    constructor();
+    ngOnDestroy(): void;
+    private scheduleShow;
+    private scheduleHide;
+    private clearTimer;
+    private clearTimers;
+    /**
+     * Takes the application out of the interaction and accessibility trees while the blocker is up,
+     * so pointer, keyboard and screen reader input cannot reach a module that is still loading.
+     */
+    private blockInteraction;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BlockLoaderComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<BlockLoaderComponent, "block-loader", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Landing page shown when the user has no module instance to open.
+ *
+ * Rendered inside the shell on purpose: the menu and the top bar stay available, so an
+ * administrator can keep working while a regular user sees why the page is empty.
+ */
+declare class NoModulesComponent {
+    private readonly translations;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NoModulesComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<NoModulesComponent, "app-no-modules", never, {}, {}, never, never, true, never>;
+}
+
 /**
  * A route guard that ensures the user is authenticated and has a valid access token.
  * If the access token is expired, it attempts to refresh the session.
@@ -1629,6 +1740,51 @@ declare class TableFilterService {
     static ɵprov: i0.ɵɵInjectableDeclaration<TableFilterService>;
 }
 
+/**
+ * Resolves the module instance the current user lands on when no explicit route is requested.
+ *
+ * The menu returned by the backend is already filtered by the rights of the current user, so the
+ * first navigable leaf of that menu is always a module the user may open. When the user picked a
+ * start module explicitly it comes back marked with `isStart`, and a module that was deleted or
+ * whose rights were revoked simply disappears from the menu, which falls back to the first leaf.
+ *
+ * The resolved url is cached per user and dropped whenever the authenticated user changes or the
+ * start module is reassigned.
+ */
+declare class StartPageService {
+    private readonly menuApi;
+    private readonly router;
+    private readonly securityService;
+    private request;
+    private cachedIdentity;
+    constructor();
+    /**
+     * Gets the url of the start module instance.
+     *
+     * @returns The url tree to navigate to, or `null` when the user has no module available.
+     */
+    resolveStartUrl(): Promise<UrlTree | null>;
+    /**
+     * Makes the module instance the start page of the current user.
+     *
+     * @param moduleInstanceId Module instance to open by default.
+     */
+    setStartModule(moduleInstanceId: number): Promise<void>;
+    /**
+     * Clears the start page of the current user, falling back to the first available module.
+     */
+    clearStartModule(): Promise<void>;
+    /**
+     * Drops the cached url, for example after the menu was changed.
+     */
+    clearCache(): void;
+    private loadStartUrl;
+    private findStartItem;
+    private collectNavigableLeaves;
+    static ɵfac: i0.ɵɵFactoryDeclaration<StartPageService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<StartPageService>;
+}
+
 declare class ExtensionLoaderService {
     private readonly loadedScripts;
     loadScript(scriptUrl: string): Promise<void>;
@@ -1636,10 +1792,22 @@ declare class ExtensionLoaderService {
     static ɵprov: i0.ɵɵInjectableDeclaration<ExtensionLoaderService>;
 }
 
+/**
+ * Defers loading of a theme preset until the theme is actually selected.
+ *
+ * Presets are large, so a preset that is not the application default should be provided as a loader
+ * built on a dynamic import, which keeps it out of the initial bundle:
+ *
+ * ```ts
+ * { id: 'Lara', preset: () => import('@primeng/themes/lara').then((m) => m.default as Preset) }
+ * ```
+ */
+type AppThemePresetLoader = () => Promise<Preset>;
 interface AppThemePreset {
     id: string;
     label?: string;
-    preset: Preset;
+    /** The preset itself, or a {@link AppThemePresetLoader} resolving it on first use. */
+    preset: Preset | AppThemePresetLoader;
     primaryColors?: Record<string, PaletteDesignToken | undefined>;
     surfaceColors?: Record<string, PaletteDesignToken | undefined>;
 }
@@ -1822,7 +1990,9 @@ declare class CustomElementExtensionModuleHostComponent extends BaseModuleCompon
     ngOnDestroy(): void;
     reloadExtension(): Promise<void>;
     private loadExtensionMetadata;
+    /** Blocks the UI while the extension is (re)mounted, including the queued render after the view init. */
     private renderExtension;
+    private renderExtensionInternal;
     private queueRenderExtension;
     private isActiveTab;
     private queueActiveTabSync;
@@ -1839,5 +2009,149 @@ declare class CustomElementExtensionModuleHostComponent extends BaseModuleCompon
     static ɵcmp: i0.ɵɵComponentDeclaration<CustomElementExtensionModuleHostComponent, "ng-component", never, {}, {}, never, never, true, never>;
 }
 
-export { APP_INFO_TOKEN, APP_THEME_PRESETS, APP_THEME_PRESETS_MERGE_MODE, AccessComponent, AppConfiguratorComponent, AppFloatingConfiguratorComponent, AppInfoService, AppLayoutComponent, AppModulesComponent, AppTopbar, AppTopbarApplicationSwitcherComponent, ApplicationRegistryService, ApplicationsApi, ApplicationsComponent, AuthGuardService, BaseModuleComponent, BffSecurityService, ConfigComponent, ContentType, CustomElementExtensionModuleHostComponent, DbMigrationComponent, DiscussionComponent, ErrorComponent, ExtensionLoaderService, ExtensionModuleHostComponent, FolderModuleApi, FooterComponent, HttpClient, IframeModuleApi, IframeModuleComponent, L10nService, LOGO_COMPONENT_TOKEN, LayoutService, LogoComponent, LogoService, MenuComponent, MenuService, ModuleInstanceRightsService, MsgService, NotfoundComponent, NotificationApi, NotificationService, OIP_EXTENSION_EVENTS, SecurityApi, SecurityComponent, SecurityService, SidebarComponent, TableFilterService, TopBarService, UnauthorizedComponent, UserNotificationsComponent, UserProfileApi, UserProfileComponent, UserService, convertToPrimeNgDateFormat, defaultTheme, emitOipContextChange, emitOipError, emitOipNavigate, emitOipNotify, emitOipSettingsChange, emitOipTitleChange, langIntercept, mergeWithDefaults, moduleAccessGuard, provideAppInfo, provideAppThemes, provideLogoComponent, provideOip, provideTranslations, replaceDefaults };
-export type { AppConfig, AppInfo, AppInfoValue, AppThemePreset, AppThemePresetMergeMode, AuthCsrfToken, LanguageDto, MenuChangeEvent, ModuleAccessRouteData, NoSettingsDto, OipExtensionHostContext, OipExtensionLoadType, OipExtensionManifest, OipExtensionModuleMetadata, OipExtensionNavigateEvent, OipExtensionNotifyEvent, PutSecurityDto, RequestParams, SecurityDto, TopBarDto };
+/**
+ * Guard that requires an authenticated session and preserves the requested url as the return url.
+ *
+ * Use it on every application route rendered inside the oip shell instead of repeating the
+ * `inject(AuthGuardService)` lambda.
+ */
+declare const oipAuthGuard: CanActivateFn;
+/**
+ * Route data read by {@link oipStartRedirectGuard}.
+ */
+interface StartRouteData {
+    /** Explicit start route of the host application, taking precedence over the user's own choice. */
+    startRoute?: string;
+    /** Where to go when the user has no module available. */
+    noModulesPath?: string;
+}
+/**
+ * Redirects the empty route to the module instance the user lands on by default.
+ *
+ * The order is: the explicit `startRoute` of the host application, then the module the user marked
+ * as their start page, then the first module available to them, and finally the no modules page.
+ */
+declare const oipStartRedirectGuard: CanActivateFn;
+/**
+ * Page shown when the user has no module instance to open.
+ */
+declare function oipNoModulesRoute(path?: string): Route;
+/**
+ * Empty route redirecting to the start module of the current user.
+ *
+ * Registered last among the shell children so a host application can claim the empty path itself.
+ */
+declare function oipStartRoute(path?: string, data?: StartRouteData): Route;
+/**
+ * Access denied page. Referenced by {@link AuthGuardService} and {@link moduleAccessGuard} redirects,
+ * so keep it registered unless the host application provides its own `access` route.
+ */
+declare function oipAccessRoute(path?: string): Route;
+/** Authentication error page. */
+declare function oipErrorRoute(path?: string): Route;
+/** Current user profile. */
+declare function oipProfileRoute(path?: string): Route;
+/** Application configuration. */
+declare function oipConfigRoute(path?: string): Route;
+/** Registered applications, administrators only. */
+declare function oipApplicationsRoute(path?: string): Route;
+/** Module registry, administrators only. */
+declare function oipModulesRoute(path?: string): Route;
+/** Discussion module. The path must keep an `:id` segment. */
+declare function oipDiscussionRoute(path?: string): Route;
+/** Database migration module. The path must keep an `:id` segment. */
+declare function oipDbMigrationRoute(path?: string): Route;
+/** Iframe module host. The path must keep an `:id` segment. */
+declare function oipIframeModuleRoute(path?: string): Route;
+/** Extension module host. The path must keep the `:extensionKey` and `:id` segments. */
+declare function oipExtensionsRoute(path?: string): Route;
+/**
+ * Switch for a built-in route.
+ *
+ * - `true` enables the route under its default path.
+ * - `false` disables it.
+ * - a string enables it under that path, which must keep the same route parameters as the default.
+ */
+type OipRouteToggle = boolean | string;
+/**
+ * Built-in routes provided by oip-common. Every one of them is enabled by default; disable the ones
+ * a host application does not expose.
+ */
+interface OipRouteFeatures {
+    /** Access denied page. Default path: `access`. */
+    access?: OipRouteToggle;
+    /** Authentication error page. Default path: `error`. */
+    error?: OipRouteToggle;
+    /** Current user profile. Default path: `profile`. */
+    profile?: OipRouteToggle;
+    /** Application configuration. Default path: `config`. */
+    config?: OipRouteToggle;
+    /** Registered applications, administrators only. Default path: `applications`. */
+    applications?: OipRouteToggle;
+    /** Module registry, administrators only. Default path: `modules`. */
+    modules?: OipRouteToggle;
+    /** Discussion module. Default path: `discussion/:id`. */
+    discussion?: OipRouteToggle;
+    /** Database migration module. Default path: `db-migration/:id`. */
+    dbMigration?: OipRouteToggle;
+    /** Iframe module host. Default path: `iframe-module/:id`. */
+    iframeModule?: OipRouteToggle;
+    /** Extension module host. Default path: `extensions/:extensionKey/:id`. */
+    extensions?: OipRouteToggle;
+    /** Page shown when no module is available. Default path: `no-modules`. */
+    noModules?: OipRouteToggle;
+    /** Empty route redirecting to the start module. Default path: `` (the shell root). */
+    start?: OipRouteToggle;
+}
+/**
+ * Options accepted by {@link provideOipRoutes}.
+ */
+interface OipRoutesOptions {
+    /** Application specific routes rendered inside the shell. */
+    children?: Routes;
+    /** Which built-in routes to register, and under which paths. All of them are on by default. */
+    features?: OipRouteFeatures;
+    /**
+     * Route opened by the empty path, overriding the start module of the user. Leave it unset to land
+     * on the module the user chose, or on the first module available to them.
+     */
+    startRoute?: string;
+    /** Shell component wrapping every child route. Default: {@link AppLayoutComponent}. */
+    layout?: Type<unknown>;
+    /** Routes registered outside the shell, before the not found handling. */
+    rootRoutes?: Routes;
+    /** Path of the not found page. Default: `notfound`. */
+    notFoundPath?: string;
+    /** Path of the unauthorized page. Default: `unauthorized`. */
+    unauthorizedPath?: string;
+    /**
+     * Whether to append the `**` route redirecting to the not found page.
+     * Disable it when the host application registers its own catch-all after these routes.
+     * Default: `true`.
+     */
+    wildcard?: boolean;
+}
+/**
+ * Builds the standard oip route tree: an authenticated shell holding the application routes and the
+ * built-in pages, followed by the unauthorized, not found and catch-all routes.
+ *
+ * The returned array is ordered so that the `**` route stays last; concatenating anything after it
+ * makes those routes unreachable.
+ *
+ * @example
+ * export const appRoutes = provideOipRoutes({
+ *   children: [
+ *     {
+ *       path: 'dashboard/:id',
+ *       loadComponent: () => import('./dashboard.component').then((m) => m.DashboardComponent),
+ *       canActivate: [oipAuthGuard]
+ *     }
+ *   ],
+ *   features: { dbMigration: 'legacy-migration/:id', modules: false },
+ *   startRoute: '/dashboard/1'
+ * });
+ */
+declare function provideOipRoutes(options?: OipRoutesOptions): Routes;
+
+export { APP_INFO_TOKEN, APP_THEME_PRESETS, APP_THEME_PRESETS_MERGE_MODE, AccessComponent, AppConfiguratorComponent, AppFloatingConfiguratorComponent, AppInfoService, AppLayoutComponent, AppModulesComponent, AppTopbar, AppTopbarApplicationSwitcherComponent, ApplicationRegistryService, ApplicationsApi, ApplicationsComponent, AuthGuardService, BaseModuleComponent, BffSecurityService, BlockLoaderComponent, ConfigComponent, ContentType, CustomElementExtensionModuleHostComponent, DbMigrationComponent, DiscussionComponent, ErrorComponent, ExtensionLoaderService, ExtensionModuleHostComponent, FolderModuleApi, FooterComponent, HttpClient, IframeModuleApi, IframeModuleComponent, L10nService, LOGO_COMPONENT_TOKEN, LayoutService, LogoComponent, LogoService, MenuComponent, MenuService, ModuleInstanceRightsService, ModuleLoadingService, MsgService, NoModulesComponent, NotfoundComponent, NotificationApi, NotificationService, OIP_EXTENSION_EVENTS, SecurityApi, SecurityComponent, SecurityService, SidebarComponent, StartPageService, TableFilterService, TopBarService, UnauthorizedComponent, UserNotificationsComponent, UserProfileApi, UserProfileComponent, UserService, convertToPrimeNgDateFormat, defaultTheme, emitOipContextChange, emitOipError, emitOipNavigate, emitOipNotify, emitOipSettingsChange, emitOipTitleChange, langIntercept, mergeWithDefaults, moduleAccessGuard, oipAccessRoute, oipApplicationsRoute, oipAuthGuard, oipConfigRoute, oipDbMigrationRoute, oipDiscussionRoute, oipErrorRoute, oipExtensionsRoute, oipIframeModuleRoute, oipModulesRoute, oipNoModulesRoute, oipProfileRoute, oipStartRedirectGuard, oipStartRoute, provideAppInfo, provideAppThemes, provideLogoComponent, provideOip, provideOipRoutes, provideTranslations, replaceDefaults };
+export type { AppConfig, AppInfo, AppInfoValue, AppThemePreset, AppThemePresetLoader, AppThemePresetMergeMode, AuthCsrfToken, LanguageDto, MenuChangeEvent, ModuleAccessRouteData, NoSettingsDto, OipExtensionHostContext, OipExtensionLoadType, OipExtensionManifest, OipExtensionModuleMetadata, OipExtensionNavigateEvent, OipExtensionNotifyEvent, OipRouteFeatures, OipRouteToggle, OipRoutesOptions, PutSecurityDto, RequestParams, SecurityDto, StartRouteData, TopBarDto };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oip-common",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "A template for cross-platform web applications based on sakai-ng and primeNG",
   "main": "index.js",
   "keywords": [