@zambon-dev/library 1.4.1 → 1.6.0

package/CHANGELOG.md

@@ -23,6 +23,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### ⚠ Breaking Changes / Migration
 
+## [1.6.0] - 2026-09-16
+
+### Added
+
+- **`DisplayControls`**, which records the form controls that exist only to show a catalog
+  selection's label. `lib-catalog-select` works in pairs — `controlName` holds the identifier,
+  `displayControlName` holds the text — and it creates the second itself when a screen does not
+  declare one, so a form carries controls nobody wrote down. It now marks whichever control it
+  drives as its display, and `framework-button-filters` reads that mark to keep those out of what
+  it submits.
+
+  The mark is held in a `WeakSet` keyed by the control instance, not by its name: two forms may
+  each have an `employeeName`, and only the one a catalog select drives is a display control.
+  Nothing about an application changes — declaring the display control yourself still works, and
+  it is marked just the same.
+
+## [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 +265,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.1...HEAD
+[Unreleased]: https://github.com/RicardoZambon/ZLibraries/compare/library-v1.6.0...HEAD
+[1.6.0]: https://github.com/RicardoZambon/ZLibraries/releases/tag/library-v1.6.0
+[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

@@ -38,6 +38,95 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.1.6", ngImpor
             args: [{ template: '' }]
         }] });
 
+class DateHelpers {
+    //#region Public methods
+    static diffDays(initialDate, finalDate) {
+        const initialDateOnly = new Date(initialDate.getFullYear(), initialDate.getMonth(), initialDate.getDate());
+        const finalDateOnly = new Date(finalDate.getFullYear(), finalDate.getMonth(), finalDate.getDate());
+        const diff = initialDateOnly.getTime() - finalDateOnly.getTime();
+        return Math.floor(diff / (1000 * 60 * 60 * 24));
+    }
+}
+
+/**
+ * Tracks the form controls that exist only to show a catalog selection's label.
+ *
+ * `lib-catalog-select` works in pairs: the control named by `controlName` holds the identifier, and
+ * the one named by `displayControlName` holds the text the user reads. The second is created by the
+ * component itself when a screen does not declare it, so a form ends up carrying controls nobody
+ * wrote down — and a filters form then submits them alongside the real filters.
+ *
+ * The mark lives in a `WeakSet` keyed by the control instance rather than by its name. That is the
+ * only scope that is actually correct: two forms may each have an `employeeName`, and only the one
+ * a catalog select drives is a display control. It also keeps nothing alive.
+ */
+class DisplayControls {
+    //#region Variables
+    static marked = new WeakSet();
+    //#endregion
+    //#region Public methods
+    /**
+     * Whether the control exists only to display a catalog selection's label.
+     *
+     * @param control The control, which may be absent.
+     * @returns `true` when a catalog select drives it as its display control.
+     */
+    static isDisplayControl(control) {
+        return !!control && DisplayControls.marked.has(control);
+    }
+    /**
+     * Marks the control as existing only to display a catalog selection's label.
+     *
+     * @param control The control, which may be absent.
+     */
+    static markAsDisplayControl(control) {
+        if (control) {
+            DisplayControls.marked.add(control);
+        }
+    }
+}
+
+class GuidHelper {
+    static generateGUID() {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+            const r = (Math.random() * 16) | 0;
+            const v = c === 'x' ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+}
+
+class RouterFormatter {
+    //#region ViewChilds, Inputs, Outputs
+    //#endregion
+    //#region Variables
+    //#endregion
+    //#region Properties
+    //#endregion
+    //#region Constructor and Angular life cycle methods
+    //#endregion
+    //#region Event handlers
+    //#endregion
+    //#region Public methods
+    static getURL(route) {
+        let parentRoute = '';
+        if (route.parent) {
+            parentRoute = this.getURL(route.parent);
+        }
+        let path = route.routeConfig?.path ?? '';
+        route.paramMap.keys
+            .forEach(k => {
+            path = path.replace(':' + k, k === 'view'
+                ? ''
+                : (route.paramMap.get(k) ?? ''));
+        });
+        if (!route.parent || (parentRoute !== '' && parentRoute !== '/' && route.routeConfig?.path && path)) {
+            parentRoute += '/';
+        }
+        return parentRoute + path;
+    }
+}
+
 class CatalogService {
     //#region ViewChilds, Inputs, Outputs
     //#endregion
@@ -193,57 +282,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.1.6", ngImpor
             type: Injectable
         }], ctorParameters: () => [] });
 
-class DateHelpers {
-    //#region Public methods
-    static diffDays(initialDate, finalDate) {
-        const initialDateOnly = new Date(initialDate.getFullYear(), initialDate.getMonth(), initialDate.getDate());
-        const finalDateOnly = new Date(finalDate.getFullYear(), finalDate.getMonth(), finalDate.getDate());
-        const diff = initialDateOnly.getTime() - finalDateOnly.getTime();
-        return Math.floor(diff / (1000 * 60 * 60 * 24));
-    }
-}
-
-class GuidHelper {
-    static generateGUID() {
-        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-            const r = (Math.random() * 16) | 0;
-            const v = c === 'x' ? r : (r & 0x3) | 0x8;
-            return v.toString(16);
-        });
-    }
-}
-
-class RouterFormatter {
-    //#region ViewChilds, Inputs, Outputs
-    //#endregion
-    //#region Variables
-    //#endregion
-    //#region Properties
-    //#endregion
-    //#region Constructor and Angular life cycle methods
-    //#endregion
-    //#region Event handlers
-    //#endregion
-    //#region Public methods
-    static getURL(route) {
-        let parentRoute = '';
-        if (route.parent) {
-            parentRoute = this.getURL(route.parent);
-        }
-        let path = route.routeConfig?.path ?? '';
-        route.paramMap.keys
-            .forEach(k => {
-            path = path.replace(':' + k, k === 'view'
-                ? ''
-                : (route.paramMap.get(k) ?? ''));
-        });
-        if (!route.parent || (parentRoute !== '' && parentRoute !== '/' && route.routeConfig?.path && path)) {
-            parentRoute += '/';
-        }
-        return parentRoute + path;
-    }
-}
-
 class GridConfigsProvider {
     //#region ViewChilds, Inputs, Outputs
     //#endregion
@@ -977,6 +1015,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 +1137,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));
@@ -1815,6 +1871,10 @@ class CatalogSelectComponent extends BaseComponent {
                 if (!parent.get(name)) {
                     parent.addControl(name, new FormControl(''));
                 }
+                // Marked whether this component created it or the screen declared it: what makes a control
+                // a display control is being driven as one, not who wrote it down. A filters form reads the
+                // mark to keep it out of what it submits.
+                DisplayControls.markAsDisplayControl(parent.get(name));
             }
         });
     }
@@ -3410,7 +3470,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 +3499,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 +3519,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;
@@ -3950,5 +4055,5 @@ class DateValidators {
  * Generated bundle index. Do not edit.
  */
 
-export { BaseComponent, BaseDataset, CatalogSelectComponent, CatalogService, DataGridComponent, DataGridConfigsProvider, DataGridDataset, DataGridRowComponent, DataProviderService, DateHelpers, DateValidators, EnumTranslatePipe, FormGroupComponent, FormGroupService, FormInputComponent, FormInputGroupComponent, FormService, GridConfigsProvider, GridDataset, GroupAccordionComponent, GroupContainerComponent, GroupScrollSpyComponent, GuidHelper, LibraryModule, ModalComponent, MultiEditorComponent, MultiEditorDataset, MultiSelectComponent, MultiSelectResultDataset, MultiSelectResultGridComponent, ReplaceManyPipe, ReplacePipe, RibbonButtonComponent, RibbonComponent, RibbonGroupChild, RibbonGroupComponent, RouterFormatter, SIDEBAR_CONFIGS, ScrollSpyDirective, SidebarComponent, SidebarConfigs, SidebarMenu, SidebarMenuOpenMode, SidebarService, toSidebarMenuOpenMode };
+export { BaseComponent, BaseDataset, CatalogSelectComponent, CatalogService, DataGridComponent, DataGridConfigsProvider, DataGridDataset, DataGridRowComponent, DataProviderService, DateHelpers, DateValidators, DisplayControls, EnumTranslatePipe, FormGroupComponent, FormGroupService, FormInputComponent, FormInputGroupComponent, FormService, GridConfigsProvider, GridDataset, GroupAccordionComponent, GroupContainerComponent, GroupScrollSpyComponent, GuidHelper, LibraryModule, ModalComponent, MultiEditorComponent, MultiEditorDataset, MultiSelectComponent, MultiSelectResultDataset, MultiSelectResultGridComponent, ReplaceManyPipe, ReplacePipe, RibbonButtonComponent, RibbonComponent, RibbonGroupChild, RibbonGroupComponent, RouterFormatter, SIDEBAR_CONFIGS, ScrollSpyDirective, SidebarComponent, SidebarConfigs, SidebarMenu, SidebarMenuOpenMode, SidebarService, toSidebarMenuOpenMode };
 //# sourceMappingURL=zambon-dev-library.mjs.map