@ardimedia/angular-portal-azure 0.3.18 → 0.3.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ardimedia/angular-portal-azure",
-  "version": "0.3.18",
+  "version": "0.3.25",
   "peerDependencies": {
     "@angular/common": "^21.1.0",
     "@angular/core": "^21.1.0"

package/types/ardimedia-angular-portal-azure.d.ts

@@ -47,6 +47,8 @@ declare function statusBarInfo(text: string): StatusBarState;
 declare function statusBarError(text: string): StatusBarState;
 declare function statusBarSuccess(text: string): StatusBarState;
 
+/** @internal */
+declare function nextBladeUid(): number;
 /**
  * Base blade definition used by BladeService to manage the blade stack.
  * Ported from Blade class in v0.2.346 — flattened from the UserControlBase → Blade hierarchy.
@@ -55,6 +57,8 @@ declare function statusBarSuccess(text: string): StatusBarState;
  * In v0.3.0 commands are a BladeCommand[] array and blade state is managed by the service.
  */
 interface BladeDefinition {
+    /** Auto-incrementing unique ID for @for track identity */
+    readonly uid: number;
     /** Unique path identifying this blade (lowercased) */
     path: string;
     /** Blade header title */
@@ -69,10 +73,12 @@ interface BladeDefinition {
     commands: BladeCommand[];
     /** Status bar state */
     statusBar: StatusBarState;
+    /** URL-persisted parameters for this blade (e.g., { id: '1' }) */
+    params: Record<string, string>;
 }
 /** Creates a blade definition with sensible defaults.
- *  statusBar uses a getter/setter backed by a signal for zoneless change detection. */
-declare function createBlade(path: string, title: string, width?: number): BladeDefinition;
+ *  statusBar and title use getter/setter pairs backed by signals for zoneless change detection. */
+declare function createBlade(path: string, title: string, width?: number, params?: Record<string, string>, uid?: number): BladeDefinition;
 /**
  * Event args for blade navigation.
  * Ported from IAddBladeEventArgs in v0.2.346.
@@ -196,9 +202,9 @@ interface BladeDataDefinition<T> extends BladeDefinition {
     lifecycle: BladeDataLifecycle<T>;
 }
 /** Creates a data blade definition with sensible defaults.
- *  statusBar, item, items use getter/setter pairs backed by signals for zoneless change detection.
+ *  statusBar, title, item, items use getter/setter pairs backed by signals for zoneless change detection.
  *  Note: cannot use ...createBlade() spread here — spread copies getter values, not getter/setter pairs. */
-declare function createDataBlade<T>(path: string, title: string, width?: number): BladeDataDefinition<T>;
+declare function createDataBlade<T>(path: string, title: string, width?: number, params?: Record<string, string>, uid?: number): BladeDataDefinition<T>;
 /**
  * Execute a load-item operation with lifecycle hooks and status bar updates.
  * Replaces the BladeData.loadItem() template method from v0.2.346.
@@ -282,6 +288,8 @@ interface TileDefinition {
     size: TileSize;
     /** Optional CSS class for tile icon/content */
     cssClass?: string;
+    /** Whether the tile is disabled (grayed out, not clickable) */
+    disabled?: boolean;
 }
 declare function createTile(title: string, bladePath: string, size?: TileSize): TileDefinition;
 
@@ -302,6 +310,15 @@ declare function getUserDisplayName(account: UserAccount): string;
  * Notification panel definition.
  * Ported from AreaNotification in v0.2.346.
  */
+/** Lifecycle hooks for the notification panel */
+interface NotificationLifecycle {
+    /** Called before hide; return false to prevent hiding */
+    onHide?: () => boolean;
+    /** Called before showing */
+    onShow?: () => void;
+    /** Called after the panel is shown */
+    onShowed?: () => void;
+}
 interface NotificationDefinition {
     /** Path/identifier for the content shown in the notification area */
     path: string;
@@ -311,15 +328,8 @@ interface NotificationDefinition {
     isVisible: boolean;
     /** Background color (default '#32383f') */
     backgroundColor: string;
-}
-/** Lifecycle hooks for the notification panel */
-interface NotificationLifecycle {
-    /** Called before hide; return false to prevent hiding */
-    onHide?: () => boolean;
-    /** Called before showing */
-    onShow?: () => void;
-    /** Called after the panel is shown */
-    onShowed?: () => void;
+    /** Optional lifecycle hooks invoked during show/hide transitions */
+    lifecycle?: NotificationLifecycle;
 }
 declare function createNotificationPanel(): NotificationDefinition;
 
@@ -474,8 +484,8 @@ declare class PortalService {
     /** Clear the blade parameter back to defaults */
     clearParameter(): void;
     /** Show the notification panel */
-    showNotification(path: string, width?: number): void;
-    /** Hide the notification panel */
+    showNotification(path: string, width?: number, lifecycle?: NotificationLifecycle): void;
+    /** Hide the notification panel. Aborted if onHide() returns false. */
     hideNotification(): void;
     /** Toggle avatar menu open/close. Closes settings if opening. */
     toggleAvatarMenu(): void;
@@ -493,9 +503,13 @@ declare class PortalService {
  *
  * Manages the blade stack: adding, removing, cascade-closing,
  * and panorama visibility toggling.
+ *
+ * When a BladeRegistry is available, metadata (title, width) from the
+ * registry is used as defaults — explicit arguments take precedence.
  */
 declare class BladeService {
     private readonly portal;
+    private readonly registry;
     /**
      * Set the first blade (e.g., when opening a top-level item from a tile).
      * Clears all existing blades, hides panorama, and adds the new blade.
@@ -509,7 +523,7 @@ declare class BladeService {
      *
      * Ported from AreaBlades.addBlade() in v0.2.346.
      */
-    addBlade(path: string, senderPath?: string, title?: string, width?: number): BladeDefinition | undefined;
+    addBlade(path: string, senderPath?: string, title?: string, width?: number, params?: Record<string, string>): BladeDefinition | undefined;
     /**
      * Open a blade from a navigation event (e.g., tile click, nav item click).
      * Wraps addBlade with AddBladeEventArgs for compatibility.
@@ -557,10 +571,23 @@ declare class BladeService {
      * Check if a blade with the given path is currently open.
      */
     isBladeOpen(path: string): boolean;
+    /**
+     * Get URL-persisted parameters for a blade by path.
+     * Returns empty object if blade not found or has no params.
+     */
+    getBladeParams(path: string): Record<string, string>;
     static ɵfac: i0.ɵɵFactoryDeclaration<BladeService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<BladeService>;
 }
 
+/** Entry in the blade registry: component + optional metadata for URL restoration */
+interface BladeRegistryEntry {
+    component: Type<unknown>;
+    title?: string;
+    width?: number;
+    /** Parameter names this blade expects from the URL (e.g., ['id']) */
+    params?: string[];
+}
 /**
  * Registry for mapping blade paths to Angular components.
  *
@@ -572,7 +599,7 @@ declare class BladeService {
  * ```typescript
  * const registry = inject(BladeRegistry);
  * registry.register('customers', CustomerNavComponent);
- * registry.register('customers/list', CustomerListComponent);
+ * registry.register('customers/list', CustomerListComponent, { title: 'All Customers', width: 585 });
  * ```
  *
  * Or register multiple at once:
@@ -585,18 +612,86 @@ declare class BladeService {
  */
 declare class BladeRegistry {
     private readonly registry;
-    /** Register a component for a blade path */
-    register(path: string, component: Type<unknown>): void;
+    /** Register a component for a blade path with optional metadata (title, width, params) */
+    register(path: string, component: Type<unknown>, metadata?: {
+        title?: string;
+        width?: number;
+        params?: string[];
+    }): void;
     /** Register multiple blade path → component mappings */
     registerAll(mappings: Record<string, Type<unknown>>): void;
     /** Get the component registered for a path, if any */
     get(path: string): Type<unknown> | undefined;
+    /** Get the full registry entry (component + metadata) for a path */
+    getEntry(path: string): BladeRegistryEntry | undefined;
     /** Check if a component is registered for a path */
     has(path: string): boolean;
     static ɵfac: i0.ɵɵFactoryDeclaration<BladeRegistry, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<BladeRegistry>;
 }
 
+/**
+ * Optional service that syncs the blade stack with the browser URL.
+ *
+ * When enabled, blade paths are stored as URL path segments with matrix params:
+ *   `/crm/customers/list/detail;id=1`
+ *
+ * This makes blade states bookmarkable, shareable, and back-button navigable.
+ *
+ * Opt-in: add `provideBladeRouter()` to your app providers alongside `provideRouter()`.
+ * Without it, blade navigation remains purely in-memory (no URL changes).
+ */
+declare class BladeRouterService {
+    private readonly router;
+    private readonly portal;
+    private readonly registry;
+    private readonly destroyRef;
+    private _syncingFromUrl;
+    private _initialRestoreDone;
+    constructor();
+    /**
+     * Encode the blade stack into URL path segments.
+     * Each blade contributes its "short name" (suffix after parent prefix).
+     * Blades with params get Angular matrix params appended.
+     *
+     * Example: [customers, customers/list, customers/detail{id:1}]
+     *   → "customers/list/detail;id=1"
+     */
+    private encodeBladesToPath;
+    /**
+     * Decode URL path segments into blade definitions.
+     * Resolves short segment names to full blade paths using the registry.
+     *
+     * Example: "customers/list/detail;id=1" with route prefix "crm"
+     *   → [customers, customers/list, customers/detail] with detail.params={id:'1'}
+     */
+    private decodeBladesFromPath;
+    /**
+     * Parse a URL segment into its name and matrix parameters.
+     * "detail;id=1;mode=edit" → { name: "detail", params: { id: "1", mode: "edit" } }
+     */
+    private parseSegment;
+    /**
+     * Resolve a short segment name to a full blade path using the registry.
+     * Tries parent/segment first, then walks up ancestors.
+     */
+    private resolveSegment;
+    /** Restore blade stack from a path-based URL */
+    private restoreFromPath;
+    /** Check if params match between two blade arrays */
+    private paramsMatch;
+    /** Get the route prefix from the current URL (e.g., 'crm' from '/crm/...') */
+    private getRoutePrefix;
+    /** Normalize URL for comparison (strip trailing slashes) */
+    private normalizeUrl;
+    /** Extract legacy `blades` query parameter from URL */
+    private extractLegacyBladesParam;
+    /** Handle legacy ?blades= URL by redirecting to new path format */
+    private handleLegacyUrl;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BladeRouterService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<BladeRouterService>;
+}
+
 /**
  * Provide the angular-portal-azure library configuration.
  *
@@ -617,6 +712,27 @@ declare class BladeRegistry {
  */
 declare function providePortalAzure(config: PortalConfig): EnvironmentProviders;
 
+/**
+ * Enables opt-in URL synchronization for the blade stack.
+ *
+ * Add alongside `provideRouter()` and `providePortalAzure()`:
+ * ```typescript
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideRouter(routes),
+ *     providePortalAzure({ title: 'My Portal', ... }),
+ *     provideBladeRouter(),
+ *   ],
+ * };
+ * ```
+ *
+ * When enabled, blade paths sync to the URL as a query parameter:
+ *   `?blades=customers,customers/list,customers/1`
+ *
+ * Without this provider, blade navigation remains purely in-memory.
+ */
+declare function provideBladeRouter(): EnvironmentProviders;
+
 /**
  * Individual dashboard tile.
  * Ported from the tile section in home.html (v0.2.346).
@@ -641,18 +757,27 @@ declare class TileComponent {
  * Displays tiles on the startboard. When a tile is clicked, it opens
  * the first blade via BladeService.setFirstBlade().
  *
+ * When `autoNavigate` is true (default), clicking a tile automatically
+ * opens the first blade. Set it to false to handle tile clicks manually
+ * via the `(tileClick)` output.
+ *
  * Usage:
  * ```html
  * <apa-panorama />
+ * <apa-panorama [autoNavigate]="false" (tileClick)="onTileClick($event)" />
  * ```
  */
 declare class PanoramaComponent {
     protected readonly portal: PortalService;
     private readonly bladeService;
+    /** When false, tile clicks only emit tileClick without opening a blade. */
+    readonly autoNavigate: i0.InputSignal<boolean>;
+    /** Emitted when a tile is clicked (always, regardless of autoNavigate). */
+    readonly tileClick: i0.OutputEmitterRef<PositionedTile>;
     protected panorama: i0.WritableSignal<_ardimedia_angular_portal_azure.PanoramaDefinition>;
     onTileClick(tile: PositionedTile): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<PanoramaComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<PanoramaComponent, "apa-panorama", never, {}, {}, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<PanoramaComponent, "apa-panorama", never, { "autoNavigate": { "alias": "autoNavigate"; "required": false; "isSignal": true; }; }, { "tileClick": "tileClick"; }, never, never, true, never>;
 }
 
 /**
@@ -812,6 +937,8 @@ declare class BladeGridComponent {
     readonly senderPath: i0.InputSignal<string>;
     readonly displayField: i0.InputSignal<string>;
     readonly bladePathField: i0.InputSignal<string>;
+    readonly idField: i0.InputSignal<string>;
+    readonly iconClass: i0.InputSignal<string>;
     readonly searchable: i0.InputSignal<boolean>;
     readonly itemClick: i0.OutputEmitterRef<any>;
     searchText: string;
@@ -822,7 +949,7 @@ declare class BladeGridComponent {
     onSearchInput(event: Event): void;
     onRowClick(item: any): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<BladeGridComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<BladeGridComponent, "apa-blade-grid", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "senderPath": { "alias": "senderPath"; "required": false; "isSignal": true; }; "displayField": { "alias": "displayField"; "required": false; "isSignal": true; }; "bladePathField": { "alias": "bladePathField"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; }, { "itemClick": "itemClick"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<BladeGridComponent, "apa-blade-grid", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "senderPath": { "alias": "senderPath"; "required": false; "isSignal": true; }; "displayField": { "alias": "displayField"; "required": false; "isSignal": true; }; "bladePathField": { "alias": "bladePathField"; "required": false; "isSignal": true; }; "idField": { "alias": "idField"; "required": false; "isSignal": true; }; "iconClass": { "alias": "iconClass"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; }, { "itemClick": "itemClick"; }, never, never, true, never>;
 }
 
 /**
@@ -876,6 +1003,8 @@ declare function createDetailCommands(handlers: {
  */
 declare class NotificationPanelComponent {
     protected readonly portal: PortalService;
+    private wasVisible;
+    constructor();
     onClose(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NotificationPanelComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NotificationPanelComponent, "apa-notification-panel", never, {}, {}, never, ["*"], true, never>;
@@ -928,5 +1057,5 @@ declare class SidebarComponent {
     static ɵcmp: i0.ɵɵComponentDeclaration<SidebarComponent, "apa-sidebar", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "collapsedWidth": { "alias": "collapsedWidth"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { AvatarMenuComponent, BladeComponent, BladeDetailComponent, BladeGridComponent, BladeHostComponent, BladeNavComponent, BladeRegistry, BladeService, CommandBarComponent, DEFAULT_LABELS, LABELS_DE_CH, LABELS_DE_DE, LABELS_EN, LABELS_ES, LABELS_FR, LABELS_IT, LANGUAGE_PRESETS, NotificationPanelComponent, PanoramaComponent, PortalLayoutComponent, PortalService, SidebarComponent, TILE_DIMENSIONS, TileComponent, TileSize, clearStatusBar, createAvatarMenu, createBlade, createCommand, createDataBlade, createDetailCommands, createNavItem, createNotificationPanel, createPanorama, createTile, executeDeleteItem, executeLoadItem, executeLoadItems, executeSaveItem, filterItems, getUserDisplayName, layoutTiles, providePortalAzure, registerLanguagePreset, statusBarError, statusBarInfo, statusBarSuccess };
-export type { AddBladeEventArgs, ApiException, AvatarMenuDefinition, AvatarMenuItem, BladeCommand, BladeDataDefinition, BladeDataLifecycle, BladeDefinition, BladeNavItem, BladeParameter, LanguagePreset, NotificationDefinition, NotificationLifecycle, PanoramaDefinition, PortalConfig, PortalLabels, PositionedTile, StandardCommandKey, StatusBarState, StatusBarStyle, TileDefinition, UserAccount };
+export { AvatarMenuComponent, BladeComponent, BladeDetailComponent, BladeGridComponent, BladeHostComponent, BladeNavComponent, BladeRegistry, BladeRouterService, BladeService, CommandBarComponent, DEFAULT_LABELS, LABELS_DE_CH, LABELS_DE_DE, LABELS_EN, LABELS_ES, LABELS_FR, LABELS_IT, LANGUAGE_PRESETS, NotificationPanelComponent, PanoramaComponent, PortalLayoutComponent, PortalService, SidebarComponent, TILE_DIMENSIONS, TileComponent, TileSize, clearStatusBar, createAvatarMenu, createBlade, createCommand, createDataBlade, createDetailCommands, createNavItem, createNotificationPanel, createPanorama, createTile, executeDeleteItem, executeLoadItem, executeLoadItems, executeSaveItem, filterItems, getUserDisplayName, layoutTiles, nextBladeUid, provideBladeRouter, providePortalAzure, registerLanguagePreset, statusBarError, statusBarInfo, statusBarSuccess };
+export type { AddBladeEventArgs, ApiException, AvatarMenuDefinition, AvatarMenuItem, BladeCommand, BladeDataDefinition, BladeDataLifecycle, BladeDefinition, BladeNavItem, BladeParameter, BladeRegistryEntry, LanguagePreset, NotificationDefinition, NotificationLifecycle, PanoramaDefinition, PortalConfig, PortalLabels, PositionedTile, StandardCommandKey, StatusBarState, StatusBarStyle, TileDefinition, UserAccount };