feat(legend): derive discrete swatch legends from a match recolor (#334) (#339)

Author: cboettig

app/legend-helpers.js

@@ -31,6 +31,62 @@ export function primaryColorValue(paint) {
     return undefined;
 }
 
+/**
+ * Derive a discrete legend (one swatch per category) from a vector layer's
+ * paint, by parsing a data-driven `match` color expression.
+ *
+ * The categorical counterpart to {@link deriveContinuousLegend}. An agent that
+ * codes categories as integers in SQL and recolors with `match` produces a map
+ * whose colors are discrete, and a continuous colorbar over the code range
+ * describes it wrongly (#334). The value→color pairs are already in the paint;
+ * this reads them back out so the legend mirrors the map.
+ *
+ * Only `match` qualifies. `step` is a numeric ramp binned into classes and is
+ * already handled as continuous, and `case` carries arbitrary predicates with
+ * no value to label a swatch with.
+ *
+ * @param {Object} paint - A MapLibre paint object.
+ * @returns {{ classes: Array<{ value: *, color: string }> } | null}
+ *   One entry per `match` label, in expression order. Returns null when the
+ *   primary color is not a flat `match` over scalar labels — including the
+ *   `case`-wrapped per-resolution expression hex layers register with, whose
+ *   `match` arms are nested expressions rather than colors.
+ */
+export function deriveCategoricalLegend(paint) {
+    if (!paint || typeof paint !== 'object') return null;
+
+    let expr = null;
+    for (const key of COLOR_PAINT_KEYS) {
+        if (Array.isArray(paint[key])) { expr = paint[key]; break; }
+    }
+    if (!expr || expr[0] !== 'match') return null;
+
+    // ["match", <input>, label0, color0, label1, color1, ..., <fallback>]
+    // Pairs start at index 2; the trailing lone element is the fallback color,
+    // which the loop bound excludes. The fallback gets no swatch on purpose —
+    // it stands for "everything not enumerated", which commonly matches no
+    // feature at all, and a legend row for it would claim a category the map
+    // may not contain.
+    const classes = [];
+    const isScalar = v => typeof v === 'number' || typeof v === 'string';
+    for (let i = 2; i + 1 < expr.length; i += 2) {
+        const value = expr[i];
+        const color = expr[i + 1];
+        // Bail on the whole expression rather than skipping arms: a partial
+        // swatch list is a legend that silently omits colors that are on screen.
+        if (typeof color !== 'string') return null;
+        // A label may be one value or an array of values sharing a color.
+        if (Array.isArray(value) ? value.length > 0 && value.every(isScalar) : isScalar(value)) {
+            classes.push({ value, color });
+        } else {
+            return null;
+        }
+    }
+    if (classes.length === 0) return null;
+
+    return { classes };
+}
+
 /**
  * Derive a continuous legend (gradient + value range) from a vector layer's
  * paint, by parsing a data-driven `interpolate` or `step` color expression.

app/map-manager.js

@@ -13,7 +13,7 @@
  */
 
 import { extractHashFromUrl, buildFillColorExpression, buildFlatFillColorExpression, rewriteValueColumn, PALETTES, buildHeightExpression, buildFlatHeightExpression, defaultExtrusionMaxHeight } from './hex-layer-helpers.js';
-import { deriveContinuousLegend, primaryColorValue } from './legend-helpers.js';
+import { deriveCategoricalLegend, deriveContinuousLegend, primaryColorValue } from './legend-helpers.js';
 
 const BASEMAPS = {
     natgeo: {
@@ -1758,20 +1758,30 @@ export class MapManager {
     }
 
     /**
-     * Give a vector layer restyled into a graduated choropleth a colorbar even
-     * when its config never declared `legend_type` — the agent can build such a
-     * ramp with `set_style` on any layer, and without this it renders with
-     * nothing explaining it (#333). Flagged `legendTypeAuto` so resetStyle and
-     * switchVersion can undo it; layers whose config *does* declare a legend
-     * type are left alone, as are hex layers (`legendType: 'hex'`).
+     * Give a vector layer restyled into a choropleth a legend even when its
+     * config never declared `legend_type` — the agent can build one with
+     * `set_style` on any layer, and without this it renders with nothing
+     * explaining it (#333). A `match` recolor yields discrete swatches, a
+     * graduated ramp a colorbar (#334). Flagged `legendTypeAuto` so resetStyle
+     * and switchVersion can undo it; layers whose config *does* declare a
+     * legend type are left alone, as are hex layers (`legendType: 'hex'`) —
+     * for those the legend still follows the paint, via `_categoricalLegend`
+     * and `_hexLegend`, without the declared type being rewritten.
      */
     _promoteLegendType(state) {
         if (state.type !== 'vector') return;
         if (state.legendType && !state.legendTypeAuto) return;
-        const derivable = this._colorPaintChanged(state)
-            && !!deriveContinuousLegend(this._effectivePaint(state));
-        if (derivable) {
-            state.legendType = 'continuous';
+
+        let promoted = null;
+        if (this._colorPaintChanged(state)) {
+            const paint = this._effectivePaint(state);
+            // Mutually exclusive by operator; categorical first as the narrower match.
+            if (deriveCategoricalLegend(paint)) promoted = 'categorical';
+            else if (deriveContinuousLegend(paint)) promoted = 'continuous';
+        }
+
+        if (promoted) {
+            state.legendType = promoted;
             state.legendTypeAuto = true;
         } else if (state.legendTypeAuto) {
             state.legendType = null;
@@ -1820,17 +1830,60 @@ export class MapManager {
 
     /**
      * Whether a layer contributes a legend entry: continuous rasters (colorbar),
-     * any layer with a categorical class list, and continuous vector layers
-     * (graduated choropleths) whose colorbar can be sourced from config or
-     * derived from their paint expression (#258).
+     * any layer resolving to a categorical class list (config or derived from a
+     * `match` recolor, #334), and continuous vector layers (graduated
+     * choropleths) whose colorbar can be sourced from config or derived from
+     * their paint expression (#258).
+     *
+     * The categorical check runs before the type-gated ones because a `match`
+     * restyle can turn *any* vector layer discrete — including one whose config
+     * declared `continuous` or which is a hex layer.
      */
     _hasLegend(state) {
         return state.type === 'raster'
-            || (state.legendType === 'categorical' && state.legendClasses?.length > 0)
+            || !!this._categoricalLegend(state)
             || (state.legendType === 'continuous' && !!this._continuousVectorLegend(state))
             || (state.legendType === 'hex' && !!this._hexLegend(state));
     }
 
+    /**
+     * Resolve a layer's discrete swatch rows, or null when it isn't a
+     * categorical legend.
+     *
+     * Once a restyle has replaced the color expression, a `match` in the new
+     * paint is the only truthful source: config `legend_classes` described the
+     * colors the layer shipped with, and a restyle that recolors past them
+     * leaves them describing nothing on screen (#334). So a changed paint means
+     * derived-or-nothing — config classes are never shown over a recolor.
+     *
+     * @returns {{ classes: Array<Object>, derived: boolean } | null} `classes`
+     *   are in the shape `_showLegend` renders (`name` + `color-hint`).
+     */
+    _categoricalLegend(state) {
+        // Derivation is vector-only — a raster's colors come from its TiTiler
+        // colormap, never a paint expression — so a categorical raster always
+        // takes the config path below (STAC `classification:classes`).
+        if (state.type === 'vector' && this._colorPaintChanged(state)) {
+            const derived = deriveCategoricalLegend(this._effectivePaint(state));
+            if (!derived) return null;
+            const classes = derived.classes.map(c => ({
+                value: c.value,
+                // No name exists to show: the tiles carry the code, and what it
+                // means lives in the SQL that produced it. Label with the value
+                // itself — honest and discrete, and `set_legend` can name it.
+                name: Array.isArray(c.value)
+                    ? c.value.map(v => this._fmtLegendValue(v)).join(', ')
+                    : this._fmtLegendValue(c.value),
+                'color-hint': c.color,
+            }));
+            return { classes, derived: true };
+        }
+
+        return (state.legendType === 'categorical' && state.legendClasses?.length > 0)
+            ? { classes: state.legendClasses, derived: false }
+            : null;
+    }
+
     /**
      * Determine which H3 resolution a hex layer is currently rendering, so its
      * legend can show the matching value domain. The server pyramid serves one
@@ -2030,12 +2083,16 @@ export class MapManager {
         const item = document.createElement('div');
         item.className = 'legend-section';
 
+        const categorical = this._categoricalLegend(state);
+
         // 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;
+        // Only for config classes: a derived row is labelled with a bare value,
+        // which restates nothing, so its layer still needs its heading (#334).
+        const singleCategorical = categorical && !categorical.derived
+            && categorical.classes.length === 1;
 
         // Display name, class names, and color hints come from STAC metadata
         // (untrusted) — build the legend via textContent and validate colors
@@ -2050,8 +2107,8 @@ export class MapManager {
             ? this._continuousVectorLegend(state)
             : null;
 
-        if (state.legendType === 'categorical' && state.legendClasses?.length) {
-            for (const cls of state.legendClasses) {
+        if (categorical) {
+            for (const cls of categorical.classes) {
                 const row = document.createElement('div');
                 row.className = 'legend-item';
                 const swatch = document.createElement('span');

docs/guide/configuration.md

@@ -126,6 +126,18 @@ A vector layer styled with a graduated `default_style` — an `interpolate` or `
 
 Use `legend_range` and/or `legend_gradient` only to override the derived values (e.g. when the paint expression doesn't cleanly map to the labels you want, or the color stops aren't plain hex). If neither config nor a parseable color expression is present, the layer shows no legend.
 
+### Legends follow runtime restyles
+
+The config above describes the layer as it loads. The agent can recolor any layer at runtime with `set_style`, and the legend follows the paint that is actually on the map rather than the paint the layer was registered with:
+
+- An `interpolate` or `step` recolor renders a **colorbar** over the new stops. This overrides `legend_range` / `legend_gradient`, which described the original ramp.
+- A `match` recolor renders **discrete swatches**, one per match arm, using the colors from the expression. This applies even to a layer configured as `continuous` or to a dynamic hex layer, and it overrides `legend_classes`.
+- A recolor with no describable structure (a flat color, a `case` expression) removes the legend rather than leaving a stale one behind.
+
+A layer with no `legend_type` at all gains a legend when the agent recolors it into a choropleth, and `reset_style` removes it again along with the restyle.
+
+Swatches derived from a `match` are labelled with the matched value itself (`1`, `2`, …), because the vector tiles carry only the code — what the code *means* usually lives in the SQL that produced the layer. Author-supplied `legend_classes` labels are used whenever the layer has not been recolored past them.
+
 ## Asset config — raster (COG)
 
 | Field | Type | Description |

test/legend-helpers.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { deriveContinuousLegend, primaryColorValue } from '../app/legend-helpers.js';
+import { deriveCategoricalLegend, deriveContinuousLegend, primaryColorValue } from '../app/legend-helpers.js';
 
 describe('deriveContinuousLegend', () => {
     it('derives gradient + range from an interpolate fill-color expression', () => {
@@ -97,3 +97,76 @@ describe('primaryColorValue', () => {
         expect(primaryColorValue(null)).toBeUndefined();
     });
 });
+
+describe('deriveCategoricalLegend', () => {
+    it('derives value+color pairs from a match fill-color expression', () => {
+        // The expression from the session that motivated #334: taxon codes 1-5.
+        const paint = {
+            'fill-color': ['match', ['get', 'dominant_taxon'],
+                1, '#1f77b4', 2, '#ff7f0e', 3, '#2ca02c', 4, '#9467bd', 5, '#8c564b', '#cccccc'],
+            'fill-opacity': 0.7,
+        };
+        expect(deriveCategoricalLegend(paint)).toEqual({
+            classes: [
+                { value: 1, color: '#1f77b4' },
+                { value: 2, color: '#ff7f0e' },
+                { value: 3, color: '#2ca02c' },
+                { value: 4, color: '#9467bd' },
+                { value: 5, color: '#8c564b' },
+            ],
+        });
+    });
+
+    it('excludes the trailing fallback color', () => {
+        const paint = { 'fill-color': ['match', ['get', 'g'], 'a', '#111', '#fallback'] };
+        expect(deriveCategoricalLegend(paint).classes).toEqual([{ value: 'a', color: '#111' }]);
+    });
+
+    it('keeps a multi-value match arm as one entry', () => {
+        const paint = { 'fill-color': ['match', ['get', 'g'], [1, 2], '#111', 3, '#222', '#ccc'] };
+        expect(deriveCategoricalLegend(paint).classes).toEqual([
+            { value: [1, 2], color: '#111' },
+            { value: 3, color: '#222' },
+        ]);
+    });
+
+    it('reads other layer-type color keys', () => {
+        expect(deriveCategoricalLegend({ 'circle-color': ['match', ['get', 'g'], 1, '#111', '#ccc'] }).classes)
+            .toEqual([{ value: 1, color: '#111' }]);
+        expect(deriveCategoricalLegend({ 'fill-extrusion-color': ['match', ['get', 'g'], 1, '#111', '#ccc'] }).classes)
+            .toEqual([{ value: 1, color: '#111' }]);
+    });
+
+    it('returns null for expressions that are not a flat match', () => {
+        // step and interpolate are continuous ramps, handled by the other helper.
+        expect(deriveCategoricalLegend({ 'fill-color': ['step', ['get', 'v'], '#a', 10, '#b'] })).toBeNull();
+        expect(deriveCategoricalLegend({ 'fill-color': ['interpolate', ['linear'], ['get', 'v'], 0, '#a', 1, '#b'] })).toBeNull();
+        expect(deriveCategoricalLegend({ 'fill-color': '#2E7D32' })).toBeNull();
+        expect(deriveCategoricalLegend({ 'fill-opacity': 0.5 })).toBeNull();
+        expect(deriveCategoricalLegend(null)).toBeNull();
+    });
+
+    it('returns null for the case-wrapped per-resolution expression hex layers register with', () => {
+        // Its `match` arms are nested interpolate expressions, not colors — deriving
+        // from it would caption a hex layer with H3 resolutions as if categories.
+        const ramp = ['interpolate', ['linear'], ['get', 'v'], 0, '#eee', 100, '#333'];
+        const paint = {
+            'fill-color': ['case', ['==', ['get', 'v'], null], 'rgba(0,0,0,0)',
+                ['match', ['get', 'res'], 5, ramp, 6, ramp, 'rgba(0,0,0,0)']],
+        };
+        expect(deriveCategoricalLegend(paint)).toBeNull();
+    });
+
+    it('rejects the whole expression when any arm carries a non-color', () => {
+        // A partial swatch list silently omits colors that are on screen.
+        const paint = {
+            'fill-color': ['match', ['get', 'g'],
+                1, '#111', 2, ['interpolate', ['linear'], ['get', 'v'], 0, '#a', 1, '#b'], '#ccc'],
+        };
+        expect(deriveCategoricalLegend(paint)).toBeNull();
+    });
+
+    it('returns null for a match with no arms', () => {
+        expect(deriveCategoricalLegend({ 'fill-color': ['match', ['get', 'g'], '#ccc'] })).toBeNull();
+    });
+});