@zambon-dev/library 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -23,6 +23,43 @@ 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).
+
 ## [1.4.0] - 2026-09-08
 
 ### Added
@@ -113,6 +150,18 @@ and want external items too, add a subscription to `menuExternalUrlSelected`.
   only the last one saved just that row, because `onSaveClick` validates the current selection only,
   so the earlier rows silently vanished on refresh. `newData()`'s values are now registered when the
   row is added.
+- **`lib-catalog-select` no longer renders an empty caption after a form reset.** `FormService.resetForm()`
+  clears every control and then patches the model back, so the component receives the value it already
+  held. It skipped refreshing the caption in that case, on the assumption that an unchanged value means
+  the caption is still on screen — but the reset had emptied the display control a moment earlier. The
+  field therefore rendered blank whenever the stored value equalled the control's initial value, which
+  is why it only ever showed on the entry the form defaults to: a `nonNullable` control declared as
+  `new FormControl(0)` bound to an enum whose first member is `0`, for instance. Values differing from
+  the initial one refreshed normally and always looked right, which made the fault read like a
+  translation or data problem rather than a reset one. The caption is now rewritten whenever it has
+  drifted from the selected entry, so the value alone no longer decides. Selects backed by a
+  `searchEndpoint` are unaffected, since their caption comes from the server-side selection rather than
+  `entriesList`. No consumer changes are required.
 
 ### ⚠ Breaking Changes / Migration
 
@@ -200,7 +249,9 @@ 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.0...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
 [1.3.1]: https://github.com/RicardoZambon/ZLibraries/releases/tag/library-v1.3.1

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));
@@ -1682,7 +1700,7 @@ class CatalogSelectComponent extends BaseComponent {
             .pipe(takeUntil(this.destroy$))
             .subscribe((value) => {
             this.syncFormControlsEnabledDisabled();
-            if (this.selectedValue === value) {
+            if (!this.shouldRefreshDisplay(value)) {
                 return;
             }
             this.selectedValue = value;
@@ -1692,8 +1710,7 @@ class CatalogSelectComponent extends BaseComponent {
                 }
             }
             else {
-                const display = this.entriesDataSource.filter((entry) => entry.value === value)[0]?.display ?? '';
-                this.displayControl?.setValue(display, { emitEvent: false });
+                this.displayControl?.setValue(this.resolveDisplay(value), { emitEvent: false });
             }
         });
         // Initial sync: if the form control already has a value (e.g., the model was loaded
@@ -1972,17 +1989,37 @@ class CatalogSelectComponent extends BaseComponent {
         this.showNoResultsMessage = false;
         this.showMinimumCharactersMessage = false;
     }
+    resolveDisplay(value) {
+        return this.entriesDataSource.filter((entry) => entry.value === value)[0]?.display ?? '';
+    }
     syncDisplayFromCurrentValue() {
         const currentValue = this.formControl?.value;
-        if (currentValue == null || this.selectedValue === currentValue) {
+        if (currentValue == null || !this.shouldRefreshDisplay(currentValue)) {
             return;
         }
         this.selectedValue = currentValue;
         if (!this.hasSearchEndpoint) {
-            const display = this.entriesDataSource.filter((entry) => entry.value === currentValue)[0]?.display ?? '';
-            this.displayControl?.setValue(display, { emitEvent: false });
+            this.displayControl?.setValue(this.resolveDisplay(currentValue), { emitEvent: false });
         }
     }
+    /**
+     * Decides whether the display control has to be written again.
+     *
+     * The value on its own is not enough. Resetting a form clears the display control and then
+     * patches the same value back, so an unchanged value can still leave the display empty. That
+     * only happens when the stored value equals the control's initial value, which is why it used
+     * to show up on the default entry alone.
+     */
+    shouldRefreshDisplay(value) {
+        if (this.selectedValue !== value) {
+            return true;
+        }
+        if (this.hasSearchEndpoint) {
+            return false;
+        }
+        const display = this.resolveDisplay(value);
+        return display.length > 0 && this.displayControl?.value !== display;
+    }
     syncFormControlsEnabledDisabled() {
         if (this.formControl.enabled !== this.displayControl.enabled) {
             if (this.formControl.disabled) {
@@ -3391,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;
@@ -3420,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) => {
@@ -3436,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;