@zambon-dev/library 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -23,6 +23,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### ⚠ Breaking Changes / Migration
 
+## [1.5.0] - 2026-09-09
+
+### Added
+
+- **`SidebarConfigs.shouldDeriveAreasFromRootMenus`** — derive region headers from the menu tree
+  instead of from `SidebarMenu.region`. Off by default, so nothing changes until you opt in.
+
+  With it on, a top-level menu that has children **and no URL** stops being a collapsible node and
+  becomes an area header, with its children rendered flat beneath it as top-level items — icons
+  included. A top-level menu that has its own URL stays an item, and a parent that carries a URL
+  stays collapsible, so only the menus that were already acting purely as groups change shape.
+
+  The point is where the grouping lives. `region` is a label repeated on every item that belongs to
+  a group, matched by exact string equality: a typo silently splits one area into two, and the
+  area has no row of its own to carry an order or a translation. Derived from the tree, the area
+  *is* a menu row — it already has a translated label and an order — and nothing has to be
+  duplicated across its items.
+
+  The children of an area are fetched **eagerly**, at load, because they are rendered without a
+  click and the lazy load a collapsible parent relies on would never fire. That is one extra
+  request per area. `region` keeps working exactly as before for anyone who prefers it; the two
+  mechanisms are independent and the flag chooses between them.
+
+- **`SidebarService.loadChildrenFor(parentMenu)`** — loads a parent’s children and returns them as
+  an observable, for callers that need them before the user clicks. `loadChildren` is unchanged: it
+  is still the fire-and-forget variant that raises `childrenLoading` and `childrenFailed`, and it
+  now delegates to this one.
+
+### ⚠ Breaking Changes / Migration
+
+None. `shouldDeriveAreasFromRootMenus` defaults to `false`, so a sidebar keeps grouping by
+`region` and keeps rendering top-level parents as collapsible nodes until you set it.
+
 ## [1.4.1] - 2026-09-08
 
 - Maintenance release (no consumer-facing changes were documented).
@@ -216,7 +249,8 @@ config options and the `getUserProfile()` method still exist but are no longer c
   available via [GitHub Releases](https://github.com/RicardoZambon/ZLibraries/releases) and the
   `library-v*` tags.
 
-[Unreleased]: https://github.com/RicardoZambon/ZLibraries/compare/library-v1.4.1...HEAD
+[Unreleased]: https://github.com/RicardoZambon/ZLibraries/compare/library-v1.5.0...HEAD
+[1.5.0]: https://github.com/RicardoZambon/ZLibraries/releases/tag/library-v1.5.0
 [1.4.1]: https://github.com/RicardoZambon/ZLibraries/releases/tag/library-v1.4.1
 [1.4.0]: https://github.com/RicardoZambon/ZLibraries/releases/tag/library-v1.4.0
 [1.3.2]: https://github.com/RicardoZambon/ZLibraries/releases/tag/library-v1.3.2

package/fesm2022/zambon-dev-library.mjs

@@ -977,6 +977,17 @@ class SidebarConfigs {
     /** Tooltip for items that open in a new browser tab. Rendered as-is, like {@link errorText}. */
     externalLinkText = 'Opens in a new browser tab';
     loadingText = 'Loading';
+    /**
+     * Derive region headers from the menu tree instead of from {@link SidebarMenu.region}.
+     *
+     * With this on, a top-level menu that has children and no URL stops being a collapsible node
+     * and becomes an area header, with its children rendered flat beneath it as top-level items --
+     * icons included. The area is then a real menu row, so it carries its own translated label and
+     * its own order, and no `region` label has to be repeated across every item that belongs to it.
+     *
+     * Off by default: without it a top-level parent stays the collapsible group it has always been.
+     */
+    shouldDeriveAreasFromRootMenus = false;
     logoCollapsedPath;
     logoExpandedPath;
     constructor(options = {}) {
@@ -1088,19 +1099,26 @@ class SidebarService {
     }
     loadChildren(parentMenu) {
         this.childrenLoading.emit(parentMenu);
-        this.loadMenus(parentMenu)
-            .pipe(take(1), map((menus) => menus.map((menu) => new SidebarMenu(menu))))
+        this.loadChildrenFor(parentMenu)
             .subscribe({
-            next: (childrenMenus) => {
-                parentMenu.children = childrenMenus;
-                childrenMenus.forEach((childMenu) => childMenu.parent = parentMenu);
-            },
             error: (exception) => {
                 this.childrenFailed.emit(parentMenu);
                 throw exception;
             }
         });
     }
+    /**
+     * Loads a parent's children and hands them back, for callers that need them before the user
+     * clicks -- a sidebar rendering areas flat has to have them up front. {@link loadChildren} is
+     * the fire-and-forget variant that also raises the loading and failure events.
+     */
+    loadChildrenFor(parentMenu) {
+        return this.loadMenus(parentMenu)
+            .pipe(take(1), map((menus) => menus.map((menu) => new SidebarMenu(menu))), tap((childrenMenus) => {
+            parentMenu.children = childrenMenus;
+            childrenMenus.forEach((childMenu) => childMenu.parent = parentMenu);
+        }));
+    }
     loadRoot() {
         return this.loadMenus(null)
             .pipe(take(1), map((menus) => menus.map((menu) => new SidebarMenu(menu))), tap((menus) => this.menus = menus));
@@ -3410,7 +3428,7 @@ class SidebarComponent extends BaseComponent {
             .pipe(takeUntil(this.destroy$))
             .subscribe((_menu) => this.deactivate());
         this.sidebarService.loadRoot()
-            .pipe(take(1))
+            .pipe(take(1), switchMap((menus) => this.loadAreaChildren(menus)))
             .subscribe({
             next: (menus) => {
                 this.menus = menus;
@@ -3439,9 +3457,13 @@ class SidebarComponent extends BaseComponent {
     trackByRegion(_index, region) {
         return region.name ?? '';
     }
+    /** Whether this top-level menu stands for an area rather than a destination of its own. */
+    isArea(menu) {
+        return menu.childCount > 0 && (menu.url?.length ?? 0) === 0;
+    }
     // Group top-level menus into regions by their optional `region` label, preserving
     // first-appearance order. Ungrouped menus fall into a single header-less region.
-    groupIntoRegions(menus) {
+    groupByRegionLabel(menus) {
         const regions = [];
         const byName = new Map();
         menus.forEach((menu) => {
@@ -3455,6 +3477,47 @@ class SidebarComponent extends BaseComponent {
         });
         return regions;
     }
+    // Derive the regions from the tree: an area menu becomes a header and lends the group its own
+    // children, so the area carries one translated label and one order instead of a string repeated
+    // across every item. Anything that is not an area keeps falling into a header-less region, which
+    // is created where the first such item appears so the original ordering still holds.
+    groupByRootMenus(menus) {
+        const regions = [];
+        let ungrouped;
+        menus.forEach((menu) => {
+            if (this.isArea(menu)) {
+                regions.push({ name: menu.label, items: menu.children });
+                return;
+            }
+            if (!ungrouped) {
+                ungrouped = { name: undefined, items: [] };
+                regions.push(ungrouped);
+            }
+            ungrouped.items.push(menu);
+        });
+        return regions;
+    }
+    groupIntoRegions(menus) {
+        return this.sidebarConfigs.shouldDeriveAreasFromRootMenus
+            ? this.groupByRootMenus(menus)
+            : this.groupByRegionLabel(menus);
+    }
+    /**
+     * Fetches the children of every area up front, because they are rendered flat rather than
+     * behind a click, so the lazy load a collapsible parent relies on would never be triggered.
+     */
+    loadAreaChildren(menus) {
+        if (!this.sidebarConfigs.shouldDeriveAreasFromRootMenus) {
+            return of(menus);
+        }
+        const areas = menus.filter((menu) => this.isArea(menu));
+        // forkJoin never emits on an empty array, so a menu with no areas has to short-circuit.
+        if (areas.length === 0) {
+            return of(menus);
+        }
+        return forkJoin(areas.map((area) => this.sidebarService.loadChildrenFor(area)))
+            .pipe(map(() => menus));
+    }
     deactivate() {
         if (this.sidebarService.isActive) {
             this.sidebarService.isActive = false;