feat(visualization): add per-map option for top labels (#4487)

When more than one map is selected in standard mode, a new
'All maps | Per map' toggle in the label settings splits the
node-selecting label computations per map: top-N labels are picked
separately for each map (Height and Color mode), and overlapping
labels are only grouped within the same map. Hidden for a single
map and in delta mode; defaults to the previous global behavior.

Co-authored-by: Christian Hühn <christian.huehn@maibornwolff.de>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

plans/2026-06-11-per-map-top-labels.md

@@ -0,0 +1,76 @@
+---
+name: per-map-top-labels
+issue: -
+state: complete
+version: 1
+---
+
+## Goal
+
+When more than one map is selected (standard mode), a new "per map" radio option in the label
+settings splits all node-selecting label computations per map: Top-N labels are picked per map
+(N labels each), color-mode label selection runs per map, and overlapping-label grouping only
+groups labels belonging to the same map. Default stays "across all maps" (current behavior).
+
+## Tasks
+
+### 1. New appSettings slice `labelsPerMap` (boolean, default false)
+- actions/reducer/selector in `state/store/appSettings/labelsPerMap/`, mirroring `amountOfTopLabels`
+- register in appSettings reducer, `AppSettings` model type, default state
+
+### 2. Feature wiring in `features/labelSettings`
+- `labelsPerMap.store.ts` + `labelsPerMap.service.ts` following existing store/service pattern
+- export selector from `labelSettings.selectors.ts`
+- add `appSettings.labelsPerMap` to `resetSettingsKeys` in the panel
+
+### 3. UI radio in labelSettingsPanel
+- radio group under the Top Labels slider: `(•) across all maps  ( ) per map`, styled like the
+  existing Height/Color join radio
+- only visible when 2+ maps are visible in standard mode (hidden for single map and delta mode):
+  expose a `isMultipleMapsView$` via StateAccessStore based on visibleFileStates count + isDeltaState
+
+### 4. Per-map top-N selection in `codeMap.render.service.ts` `setLabels`
+- helper to derive a map key from `node.path` (top-level segment under root; AggregationGenerator
+  prefixes paths with `/root/<fileName>/` when maps are merged)
+- height mode: partition leaf nodes by map key, `selectTopNByValue` per partition (N each)
+- color mode: same partitioning applied to the selected color nodes
+- ignore the setting (keep global behavior) when only one map is visible or in delta mode
+
+### 5. Per-map collision grouping in `labelCollision.service.ts`
+- when per-map mode is active, `buildCollisionGroups` only unions overlapping labels that share
+  the same map key
+
+### 6. Tests
+- reducer default/toggle
+- render service: per-map vs global selection (height + color mode), single-map/delta fallback
+- panel: radio visibility and dispatch
+- collision service: overlapping labels from different maps are not grouped in per-map mode
+
+### 7. Housekeeping
+- CHANGELOG.md entry
+
+## Steps
+
+- [x] Complete Task 1: state slice `labelsPerMap`
+- [x] Complete Task 2: feature store/service/selector wiring
+- [x] Complete Task 3: UI radio with multi-map visibility
+- [x] Complete Task 4: per-map top-N selection in render service
+- [x] Complete Task 5: per-map collision grouping
+- [x] Complete Task 6: tests
+- [x] Complete Task 7: changelog
+
+## Notes
+
+- Clarified with user: one shared set of setting values; only node-selecting computations split
+  per map ("N per map", so top 10 with 3 maps = up to 30 labels). No independent per-map settings.
+- Option hidden (not just disabled) for single map and delta mode.
+- Branch from `main`: `feature/per-map-top-labels`.
+- New `labelsPerMapActiveSelector` (state/selectors) gates the behavior; the labelSettings feature
+  reaches it via `StateAccessStore.isLabelsPerMapActive()` because `ui/` may not import feature
+  internals (dependency-cruiser rules).
+- `loadInitialFile.service.ts` needed the new key in `optionalAppSettingsKeys` plus a
+  `mapAppSettingToAction` case — its switch throws on unknown saved-config keys.
+- Scenarios intentionally left untouched: persisting the flag would break previously saved
+  scenarios (undefined patch values) and was not requested.
+- Verification: `tsc --noEmit` clean, full unit suite green (381 suites / 2222 tests),
+  `npm run lint:architecture` 0 errors, Biome clean.

visualization/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/)
 
 ### Added 🚀
 
+- **Per-map top labels**: When more than one map is selected, the Label Settings panel offers a new `All maps | Per map` toggle below the Top Labels slider. In `Per map` mode the top-N labels are picked separately for each map (Height and Color label mode alike), and overlapping labels are only grouped within the same map. The toggle is hidden for a single map and in delta mode.
 - **Label Size slider**: New slider in the Label Settings panel scales floating label text (name, metric value, and "+N more" badge) between 0.75× and 2.5×. The setting is preserved in scenarios.
 - **File Explorer sidebar**: The file tree was redesigned as a dedicated left-side sidebar drawer that overlays the codemap. The drawer adds a Shown/Flattened/Hidden chip row at the top, a sort control, and click-to-edit popovers for the active flatten and exclude rules.
 - **Collapsible File Explorer**: The sidebar can now be collapsed via the `«` button in the header. Collapsed mode shows a small floating search box (with the kebab Flatten/Exclude menu) pinned at the top-left, freeing the full viewport for the codemap. Re-expand with the folder-tree button.

visualization/app/codeCharta/codeCharta.model.ts

@@ -171,6 +171,7 @@ export interface AppSettings {
     colorLabels: ColorLabelOptions
     labelMode: LabelMode
     groupLabelCollisions: boolean
+    labelsPerMap: boolean
     isColorMetricLinkedToHeightMetric: boolean
     enableFloorLabels: boolean
 }

visualization/app/codeCharta/features/labelSettings/components/labelSettingsPanel/labelSettingsPanel.component.html

@@ -1,4 +1,4 @@
-<div [title]="'Display the labels of the ' + amountOfTopLabels() + ' highest buildings'">
+<div [title]="topLabelsTitle()">
     <span class="text-sm">Top Labels</span>
     <div class="flex items-center gap-2">
         <input type="range" class="range range-primary range-sm flex-1"
@@ -10,6 +10,22 @@
     </div>
 </div>
 
+@if (areMultipleMapsVisible()) {
+    <div class="join w-full" aria-label="Top labels scope"
+        title="Pick the top labels across all maps combined or separately for each map">
+        <input type="radio" name="labelsPerMap"
+            class="join-item btn btn-sm flex-1"
+            aria-label="All maps"
+            [checked]="!labelsPerMap()"
+            (change)="setLabelsPerMap(false)" />
+        <input type="radio" name="labelsPerMap"
+            class="join-item btn btn-sm flex-1"
+            aria-label="Per map"
+            [checked]="labelsPerMap()"
+            (change)="setLabelsPerMap(true)" />
+    </div>
+}
+
 <div title="Scale floating label font size">
     <span class="text-sm">Label Size</span>
     <div class="flex items-center gap-2">

visualization/app/codeCharta/features/labelSettings/components/labelSettingsPanel/labelSettingsPanel.component.spec.ts

@@ -4,6 +4,9 @@ import userEvent from "@testing-library/user-event"
 import { setColorLabels } from "../../../../state/store/appSettings/colorLabels/colorLabels.actions"
 import { setLabelMode } from "../../../../state/store/appSettings/labelMode/labelMode.actions"
 import { setLabelSize } from "../../../../state/store/appSettings/labelSize/labelSize.actions"
+import { setLabelsPerMap } from "../../../../state/store/appSettings/labelsPerMap/labelsPerMap.actions"
+import { setDelta, setFiles } from "../../../../state/store/files/files.actions"
+import { FILE_STATES_TWO_FILES, TEST_FILE_DATA, TEST_FILE_DATA_JAVA } from "../../../../util/dataMocks"
 import { fireEvent } from "@testing-library/angular"
 import { LabelSettingsPanelComponent } from "./labelSettingsPanel.component"
 import { Store, StoreModule } from "@ngrx/store"
@@ -154,6 +157,58 @@ describe("LabelSettingsPanelComponent", () => {
         expect(positiveCheckbox.disabled).toBe(false)
     })
 
+    describe("per-map top labels toggle", () => {
+        it("should hide the toggle when only one map is visible", async () => {
+            // Arrange & Act
+            await render(LabelSettingsPanelComponent)
+
+            // Assert
+            expect(screen.queryByRole("radio", { name: "Per map" })).toBe(null)
+        })
+
+        it("should display the toggle when multiple maps are visible in standard mode", async () => {
+            // Arrange
+            const { detectChanges } = await render(LabelSettingsPanelComponent)
+            const store = TestBed.inject(Store)
+
+            // Act
+            store.dispatch(setFiles({ value: FILE_STATES_TWO_FILES }))
+            detectChanges()
+
+            // Assert
+            expect(screen.getByRole("radio", { name: "All maps" })).not.toBe(null)
+            expect(screen.getByRole("radio", { name: "Per map" })).not.toBe(null)
+        })
+
+        it("should hide the toggle in delta mode", async () => {
+            // Arrange
+            const { detectChanges } = await render(LabelSettingsPanelComponent)
+            const store = TestBed.inject(Store)
+
+            // Act
+            store.dispatch(setDelta({ referenceFile: TEST_FILE_DATA, comparisonFile: TEST_FILE_DATA_JAVA }))
+            detectChanges()
+
+            // Assert
+            expect(screen.queryByRole("radio", { name: "Per map" })).toBe(null)
+        })
+
+        it("should dispatch setLabelsPerMap when clicking Per map", async () => {
+            // Arrange
+            const { detectChanges } = await render(LabelSettingsPanelComponent)
+            const store = TestBed.inject(Store)
+            store.dispatch(setFiles({ value: FILE_STATES_TWO_FILES }))
+            detectChanges()
+            const dispatchSpy = jest.spyOn(store, "dispatch")
+
+            // Act
+            await userEvent.click(screen.getByRole("radio", { name: "Per map" }))
+
+            // Assert
+            expect(dispatchSpy).toHaveBeenCalledWith(setLabelsPerMap({ value: true }))
+        })
+    })
+
     describe("Label Size slider", () => {
         const flushDebounce = () => new Promise(resolve => setTimeout(resolve, 500))
 

visualization/app/codeCharta/features/labelSettings/components/labelSettingsPanel/labelSettingsPanel.component.ts

@@ -8,6 +8,7 @@ import { ShowMetricLabelNodeNameService } from "../../services/showMetricLabelNo
 import { ShowMetricLabelNameValueService } from "../../services/showMetricLabelNameValue.service"
 import { ColorLabelsService } from "../../services/colorLabels.service"
 import { GroupLabelCollisionsService } from "../../services/groupLabelCollisions.service"
+import { LabelsPerMapService } from "../../services/labelsPerMap.service"
 import { StateAccessStore } from "../../stores/stateAccess.store"
 import { CodeMapRenderService } from "../../../../ui/codeMap/codeMap.render.service"
 import { debounce } from "../../../../util/debounce"
@@ -31,6 +32,7 @@ export class LabelSettingsPanelComponent {
     private readonly showMetricLabelNameValueService = inject(ShowMetricLabelNameValueService)
     private readonly colorLabelsService = inject(ColorLabelsService)
     private readonly groupLabelCollisionsService = inject(GroupLabelCollisionsService)
+    private readonly labelsPerMapService = inject(LabelsPerMapService)
     private readonly stateAccessStore = inject(StateAccessStore)
     private readonly codeMapRenderService = inject(CodeMapRenderService)
 
@@ -46,7 +48,8 @@ export class LabelSettingsPanelComponent {
         "appSettings.showMetricLabelNameValue",
         "appSettings.colorLabels",
         "appSettings.labelMode",
-        "appSettings.groupLabelCollisions"
+        "appSettings.groupLabelCollisions",
+        "appSettings.labelsPerMap"
     ]
 
     readonly amountOfTopLabels = toSignal(this.amountOfTopLabelsService.amountOfTopLabels$(), { requireSync: true })
@@ -59,9 +62,16 @@ export class LabelSettingsPanelComponent {
     readonly labelMode = toSignal(this.labelModeService.labelMode$(), { requireSync: true })
     readonly colorCategoryCounts = toSignal(this.codeMapRenderService.colorCategoryCounts$, { requireSync: true })
     readonly groupLabelCollisions = toSignal(this.groupLabelCollisionsService.groupLabelCollisions$(), { requireSync: true })
+    readonly labelsPerMap = toSignal(this.labelsPerMapService.labelsPerMap$(), { requireSync: true })
+    readonly areMultipleMapsVisible = toSignal(this.stateAccessStore.areMultipleMapsVisible$, { requireSync: true })
 
     readonly showColorLabels = computed(() => this.labelMode() === LabelMode.Color && !this.isDeltaState())
 
+    readonly topLabelsTitle = computed(() => {
+        const base = `Display the labels of the ${this.amountOfTopLabels()} highest buildings`
+        return this.labelsPerMap() && this.areMultipleMapsVisible() ? `${base} per map` : base
+    })
+
     readonly applyDebouncedTopLabels = debounce((amountOfTopLabels: number) => {
         this.amountOfTopLabelsService.setAmountOfTopLabels(amountOfTopLabels)
     }, LabelSettingsPanelComponent.DEBOUNCE_TIME)
@@ -118,6 +128,10 @@ export class LabelSettingsPanelComponent {
         this.groupLabelCollisionsService.setGroupLabelCollisions((event.target as HTMLInputElement).checked)
     }
 
+    setLabelsPerMap(value: boolean) {
+        this.labelsPerMapService.setLabelsPerMap(value)
+    }
+
     resetSettings() {
         this.stateAccessStore.resetSettings(this.resetSettingsKeys)
     }

visualization/app/codeCharta/features/labelSettings/selectors/labelSettings.selectors.ts

@@ -14,3 +14,5 @@ export const showMetricLabelNameValueSelector = createSelector(appSettingsSelect
 export const colorLabelsSelector = createSelector(appSettingsSelector, appSettings => appSettings.colorLabels)
 
 export const groupLabelCollisionsSelector = createSelector(appSettingsSelector, appSettings => appSettings.groupLabelCollisions)
+
+export const labelsPerMapSelector = createSelector(appSettingsSelector, appSettings => appSettings.labelsPerMap)

visualization/app/codeCharta/features/labelSettings/services/labelCollision.service.spec.ts

@@ -12,6 +12,9 @@ import { Store, StoreModule } from "@ngrx/store"
 import { appReducers, setStateMiddleware } from "../../../state/store/state.manager"
 import { StateAccessStore } from "../stores/stateAccess.store"
 import { setHeightMetric } from "../../../state/store/dynamicSettings/heightMetric/heightMetric.actions"
+import { setLabelsPerMap } from "../../../state/store/appSettings/labelsPerMap/labelsPerMap.actions"
+import { setFiles } from "../../../state/store/files/files.actions"
+import { FILE_STATES_TWO_FILES } from "../../../util/dataMocks"
 
 describe("LabelCollisionService", () => {
     let store: Store<CcState>
@@ -303,6 +306,70 @@ describe("LabelCollisionService", () => {
         })
     })
 
+    describe("per-map collision grouping", () => {
+        beforeEach(() => {
+            store.dispatch(setShowMetricLabelNodeName({ value: true }))
+            store.dispatch(setHeightMetric({ value: "mcc" }))
+        })
+
+        function addOverlappingLabelsForMaps(pathOfFirst: string, pathOfSecond: string) {
+            const firstLeaf = { ...sampleLeaf, name: "first", path: pathOfFirst, attributes: { mcc: 100 } } as undefined as Node
+            const secondLeaf = { ...otherSampleLeaf, name: "second", path: pathOfSecond, attributes: { mcc: 10 } } as undefined as Node
+            labelCreationService.addLeafLabel(firstLeaf, 0)
+            labelCreationService.addLeafLabel(secondLeaf, 0)
+            const sharedRect = makeRect(100, 120, 50, 150)
+            stubRectsForLabels([sharedRect, sharedRect])
+        }
+
+        it("should not group overlapping labels from different maps when labelsPerMap is active", () => {
+            // Arrange
+            store.dispatch(setFiles({ value: FILE_STATES_TWO_FILES }))
+            store.dispatch(setLabelsPerMap({ value: true }))
+            addOverlappingLabelsForMaps("/root/mapA/first", "/root/mapB/second")
+
+            // Act
+            labelCollisionService.updateLabelLayout()
+
+            // Assert — labels of different maps stay visible side by side
+            const contentFirst = labelCreationService.getLabels()[0].labelElement.getContentElement()
+            const contentSecond = labelCreationService.getLabels()[1].labelElement.getContentElement()
+            expect(contentFirst.style.opacity).toBe("1")
+            expect(contentSecond.style.opacity).toBe("1")
+        })
+
+        it("should still group overlapping labels of the same map when labelsPerMap is active", () => {
+            // Arrange
+            store.dispatch(setFiles({ value: FILE_STATES_TWO_FILES }))
+            store.dispatch(setLabelsPerMap({ value: true }))
+            addOverlappingLabelsForMaps("/root/mapA/first", "/root/mapA/second")
+
+            // Act
+            labelCollisionService.updateLabelLayout()
+
+            // Assert
+            const contentFirst = labelCreationService.getLabels()[0].labelElement.getContentElement()
+            const contentSecond = labelCreationService.getLabels()[1].labelElement.getContentElement()
+            expect(contentFirst.style.opacity).toBe("1")
+            expect(contentSecond.style.opacity).toBe("0")
+        })
+
+        it("should group overlapping labels across maps when labelsPerMap is off", () => {
+            // Arrange
+            store.dispatch(setFiles({ value: FILE_STATES_TWO_FILES }))
+            store.dispatch(setLabelsPerMap({ value: false }))
+            addOverlappingLabelsForMaps("/root/mapA/first", "/root/mapB/second")
+
+            // Act
+            labelCollisionService.updateLabelLayout()
+
+            // Assert
+            const contentFirst = labelCreationService.getLabels()[0].labelElement.getContentElement()
+            const contentSecond = labelCreationService.getLabels()[1].labelElement.getContentElement()
+            expect(contentFirst.style.opacity).toBe("1")
+            expect(contentSecond.style.opacity).toBe("0")
+        })
+    })
+
     describe("tooltip collision padding", () => {
         beforeEach(() => {
             store.dispatch(setShowMetricLabelNodeName({ value: true }))

visualization/app/codeCharta/features/labelSettings/services/labelCollision.service.ts

@@ -6,6 +6,7 @@ import { LabelMode } from "../../../codeCharta.model"
 import { StateAccessStore } from "../stores/stateAccess.store"
 import { ConnectorDrawingService, LabelLayoutInfo } from "./connectorDrawing.service"
 import { LABEL_GAP_PX, MAX_DISPLACEMENT_PX, TOOLTIP_COLLISION_PADDING_PX } from "./label.constants"
+import { getTopLevelMapName } from "../../../util/nodePathHelper"
 
 @Injectable({ providedIn: "root" })
 export class LabelCollisionService {
@@ -94,7 +95,7 @@ export class LabelCollisionService {
             return
         }
 
-        const groups = this.buildCollisionGroups(activeInfos)
+        const groups = this.buildCollisionGroups(activeInfos, this.stateAccessStore.isLabelsPerMapActive())
         const { dynamicSettings } = this.stateAccessStore.getValue()
         const metric = appSettings.labelMode === LabelMode.Color ? dynamicSettings.colorMetric : dynamicSettings.heightMetric
 
@@ -115,9 +116,10 @@ export class LabelCollisionService {
         }
     }
 
-    private buildCollisionGroups(infos: LabelLayoutInfo[]): LabelLayoutInfo[][] {
+    private buildCollisionGroups(infos: LabelLayoutInfo[], groupPerMap: boolean): LabelLayoutInfo[][] {
         const n = infos.length
         const parent = Array.from({ length: n }, (_, i) => i)
+        const mapNames = groupPerMap ? infos.map(info => getTopLevelMapName(info.label.node.path)) : undefined
 
         const find = (x: number): number => {
             while (parent[x] !== x) {
@@ -137,6 +139,9 @@ export class LabelCollisionService {
 
         for (let i = 0; i < n; i++) {
             for (let j = i + 1; j < n; j++) {
+                if (mapNames !== undefined && mapNames[i] !== mapNames[j]) {
+                    continue
+                }
                 if (this.rectsOverlap(infos[i].rect, infos[j].rect)) {
                     union(i, j)
                 }

visualization/app/codeCharta/features/labelSettings/services/labelsPerMap.service.ts

@@ -0,0 +1,17 @@
+import { Injectable } from "@angular/core"
+import { LabelsPerMapStore } from "../stores/labelsPerMap.store"
+
+@Injectable({
+    providedIn: "root"
+})
+export class LabelsPerMapService {
+    constructor(private readonly labelsPerMapStore: LabelsPerMapStore) {}
+
+    labelsPerMap$() {
+        return this.labelsPerMapStore.labelsPerMap$
+    }
+
+    setLabelsPerMap(value: boolean) {
+        this.labelsPerMapStore.setLabelsPerMap(value)
+    }
+}