feat(legend): group legend entries by layer group (#328) (#329)

* feat(legend): group legend entries by layer group (#328)

The legend rendered one flat section per visible layer with no grouping,
even though the layer panel already groups by the layer `group` property.
This forced apps like utah-public-lands to collapse per-era boundary
layers into a single match-colored layer (losing per-era toggling) just to
get a grouped legend.

Cluster visible legend sections under a lazily-created .legend-group
heading matching state.group, mirroring generateControls. Ungrouped layers
append flat to #legend-content as before (backward compatible), and a group
heading is hidden once all its members are hidden and restored when one
returns.

Keys off the existing, general `group` config field, so any app that groups
its layers gets a matching grouped legend.

* fix(legend): drop redundant heading for single-class categorical layers

A per-era boundary layer is a single-class categorical whose class label
restates the display name, so a grouped legend showed the name twice — once
as the section <h4> heading and once as the swatch row label. Skip the
per-layer heading when a categorical layer has exactly one class: the lone
swatch row (and, when grouped, the group heading) already labels it.

Author: cassiebuhler

app/map-manager.js

@@ -61,6 +61,7 @@ export class MapManager {
         this._legendEl = null;
         this._legendContent = null;
         this._legendItems = new Map();   // layerId → DOM element
+        this._legendGroups = new Map();  // groupName → group wrapper element (grouped legend sections)
         this._colormapCache = new Map(); // colormap name → CSS gradient string
         this._hexLegendRefs = new Map(); // layerId → { minSpan, maxSpan, resNote } for zoom-reactive relabeling
         this._hexLegendReactive = false; // moveend handler registered lazily on first hex legend
@@ -1867,6 +1868,34 @@ export class MapManager {
         }
     }
 
+    /**
+     * Resolve the element a layer's legend section should append into, mirroring
+     * the layer panel's grouping (`generateControls`). Layers with a `group` are
+     * clustered under one lazily-created `.legend-group` wrapper (heading = group
+     * name); ungrouped layers append straight into `#legend-content` (flat,
+     * backward compatible). Also un-hides the wrapper so a re-shown member brings
+     * its group heading back.
+     * @param {Object} state - entry from this.layers
+     * @returns {HTMLElement}
+     */
+    _legendParentFor(state) {
+        if (!state.group) return this._legendContent;
+        let wrapper = this._legendGroups.get(state.group);
+        if (!wrapper) {
+            wrapper = document.createElement('div');
+            wrapper.className = 'legend-group';
+            // Group name comes from config (untrusted) — textContent, never HTML.
+            const title = document.createElement('h4');
+            title.className = 'legend-group-title';
+            title.textContent = state.group;
+            wrapper.appendChild(title);
+            this._legendGroups.set(state.group, wrapper);
+            this._legendContent.appendChild(wrapper);
+        }
+        wrapper.style.display = '';
+        return wrapper;
+    }
+
     async _showLegend(layerId) {
         const state = this.layers.get(layerId);
         if (!state) return;
@@ -1876,18 +1905,28 @@ export class MapManager {
 
         if (this._legendItems.has(layerId)) {
             this._legendItems.get(layerId).style.display = '';
+            if (state.group) this._legendParentFor(state); // re-show group wrapper
             return;
         }
 
         const item = document.createElement('div');
         item.className = 'legend-section';
 
+        // A single-class categorical layer would render a redundant heading plus
+        // one identically-labelled swatch row (the class label usually restates
+        // the display name). Drop the per-layer heading in that case — the lone
+        // swatch row (and, when grouped, the group heading) already labels it (#328).
+        const singleCategorical = state.legendType === 'categorical'
+            && state.legendClasses?.length === 1;
+
         // Display name, class names, and color hints come from STAC metadata
         // (untrusted) — build the legend via textContent and validate colors
         // before they reach a style attribute.
-        const heading = document.createElement('h4');
-        heading.textContent = state.displayName;
-        item.appendChild(heading);
+        if (!singleCategorical) {
+            const heading = document.createElement('h4');
+            heading.textContent = state.displayName;
+            item.appendChild(heading);
+        }
 
         const continuousVector = state.legendType === 'continuous'
             ? this._continuousVectorLegend(state)
@@ -1972,13 +2011,23 @@ export class MapManager {
             item.appendChild(labels);
         }
 
-        this._legendContent.appendChild(item);
+        this._legendParentFor(state).appendChild(item);
         this._legendItems.set(layerId, item);
     }
 
     _hideLegend(layerId) {
         const item = this._legendItems.get(layerId);
         if (item) item.style.display = 'none';
+        // Hide a group wrapper once all its member sections are hidden
+        const state = this.layers.get(layerId);
+        if (state?.group) {
+            const wrapper = this._legendGroups.get(state.group);
+            if (wrapper) {
+                const anyMemberVisible = [...wrapper.querySelectorAll('.legend-section')]
+                    .some(el => el.style.display !== 'none');
+                wrapper.style.display = anyMemberVisible ? '' : 'none';
+            }
+        }
         // Hide the whole panel when nothing is visible
         if (this._legendEl) {
             const anyVisible = [...this._legendItems.values()].some(el => el.style.display !== 'none');

app/style.css

@@ -437,6 +437,43 @@ details.layer-group:not([open]) .layer-group-title::before {
     letter-spacing: 0.5px;
 }
 
+/* Grouped legend sections: one heading over its member layers (mirrors the
+   layer panel). The group title is the prominent heading; per-layer section
+   headings inside become lighter, indented sub-headings. */
+.legend-group {
+    margin-bottom: 15px;
+}
+
+.legend-group:last-child {
+    margin-bottom: 0;
+}
+
+.legend-group-title {
+    margin: 0 0 8px 0;
+    font-size: 12px;
+    font-weight: 600;
+    color: #555;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+}
+
+.legend-group .legend-section {
+    margin-bottom: 10px;
+    padding-left: 8px;
+}
+
+.legend-group .legend-section:last-child {
+    margin-bottom: 0;
+}
+
+.legend-group .legend-section h4 {
+    font-size: 11px;
+    font-weight: 500;
+    color: #666;
+    text-transform: none;
+    letter-spacing: 0;
+}
+
 .legend-colorbar {
     height: 12px;
     border-radius: 2px;

test/map-manager.legend-group.test.js

@@ -0,0 +1,109 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { MapManager } from '../app/map-manager.js';
+
+/**
+ * Legend grouping (#328): visible legend sections cluster under a `.legend-group`
+ * heading matching their layer `group`, mirroring the layer panel. Ungrouped
+ * layers stay flat (backward compatible), and a group heading disappears once all
+ * its members are hidden.
+ */
+
+function createLegendManager(states) {
+    const mm = Object.create(MapManager.prototype);
+    mm.layers = new Map(Object.entries(states));
+    mm._legendEl = document.createElement('div');
+    mm._legendContent = document.createElement('div');
+    mm._legendItems = new Map();
+    mm._legendGroups = new Map();
+    mm._ensureLegend = () => {};
+    return mm;
+}
+
+// Mirrors the utah-public-lands per-era boundary layers: a single-class
+// categorical whose class label restates the display name.
+const categorical = (displayName, group) => ({
+    displayName,
+    group,
+    visible: true,
+    legendType: 'categorical',
+    legendClasses: [{ name: displayName, 'color-hint': 'ff0000' }],
+});
+
+describe('MapManager legend grouping (#328)', () => {
+    it('clusters same-group layers under one heading; ungrouped stays flat', async () => {
+        const mm = createLegendManager({
+            A: categorical('2021 restored', 'Bears Ears'),
+            B: categorical('2026 proposed', 'Bears Ears'),
+            C: categorical('Statewide layer', null),
+        });
+        await mm._showLegend('A');
+        await mm._showLegend('B');
+        await mm._showLegend('C');
+
+        // One group wrapper for "Bears Ears" holding both member sections.
+        const groups = mm._legendContent.querySelectorAll('.legend-group');
+        expect(groups).toHaveLength(1);
+        expect(groups[0].querySelector('.legend-group-title').textContent).toBe('Bears Ears');
+        expect(groups[0].querySelectorAll('.legend-section')).toHaveLength(2);
+
+        // Ungrouped section is a direct child of #legend-content, not inside a group.
+        const flatSections = [...mm._legendContent.children].filter(el => el.classList.contains('legend-section'));
+        expect(flatSections).toHaveLength(1);
+        expect(flatSections[0].textContent).toContain('Statewide layer');
+    });
+
+    it('collapses a single-class categorical to one row, no redundant heading (#328)', async () => {
+        const mm = createLegendManager({
+            A: categorical('2021 restored', 'Bears Ears'),
+        });
+        await mm._showLegend('A');
+        const section = mm._legendContent.querySelector('.legend-section');
+        // No per-layer <h4> heading (it would duplicate the sole class label)...
+        expect(section.querySelector('h4')).toBeNull();
+        // ...just one swatch row, labelled once.
+        const rows = section.querySelectorAll('.legend-item');
+        expect(rows).toHaveLength(1);
+        expect(section.textContent.match(/2021 restored/g)).toHaveLength(1);
+    });
+
+    it('renders separate wrappers for distinct groups', async () => {
+        const mm = createLegendManager({
+            A: categorical('2021 restored', 'Bears Ears'),
+            B: categorical('2021 restored', 'Grand Staircase-Escalante'),
+        });
+        await mm._showLegend('A');
+        await mm._showLegend('B');
+        expect(mm._legendContent.querySelectorAll('.legend-group')).toHaveLength(2);
+        expect(mm._legendGroups.size).toBe(2);
+    });
+
+    it('hides the group heading only once every member is hidden, and restores it', async () => {
+        const mm = createLegendManager({
+            A: categorical('2021 restored', 'Bears Ears'),
+            B: categorical('2026 proposed', 'Bears Ears'),
+        });
+        await mm._showLegend('A');
+        await mm._showLegend('B');
+        const wrapper = mm._legendGroups.get('Bears Ears');
+
+        mm._hideLegend('A');
+        expect(wrapper.style.display).not.toBe('none'); // B still visible
+
+        mm._hideLegend('B');
+        expect(wrapper.style.display).toBe('none'); // all hidden
+
+        await mm._showLegend('A'); // reuse path re-shows the wrapper
+        expect(wrapper.style.display).not.toBe('none');
+    });
+
+    it('escapes an untrusted group name (textContent, no HTML injection)', async () => {
+        const mm = createLegendManager({
+            A: categorical('2021 restored', '<img src=x onerror=alert(1)>'),
+        });
+        await mm._showLegend('A');
+        const wrapper = mm._legendContent.querySelector('.legend-group');
+        expect(wrapper.querySelector('img')).toBeNull();
+        expect(wrapper.querySelector('.legend-group-title').textContent).toContain('<img');
+    });
+});

test/map-manager.tooltip-legend.test.js

@@ -88,10 +88,15 @@ describe('MapManager raster legend (SEC-3)', () => {
     });
 
     it('renders HTML in the display name as inert text (both branches)', async () => {
+        // Multi-class categorical keeps the per-layer <h4> heading (a single-class
+        // categorical drops it — #328), so this still exercises heading escaping.
         const mm = createLegendManager({
             displayName: '<script>alert(1)</script>Cover',
             legendType: 'categorical',
-            legendClasses: [{ name: 'Forest', 'color-hint': '00ff00' }],
+            legendClasses: [
+                { name: 'Forest', 'color-hint': '00ff00' },
+                { name: 'Water', 'color-hint': '0000ff' },
+            ],
         });
         await mm._showLegend('A');
         expect(mm._legendContent.querySelector('script')).toBeNull();