gridviz 3.0.37 → 3.0.38

package/package.json

@@ -1,74 +1,74 @@
-{
-    "name": "gridviz",
-    "version": "3.0.37",
-    "description": "Visualization tool for gridded statistics",
-    "keywords": [
-        "statistics",
-        "grid",
-        "gridded",
-        "grids",
-        "gridded statistics",
-        "dataviz",
-        "csv",
-        "GIS",
-        "WebGL",
-        "d3",
-        "cartography",
-        "bertin",
-        "geospatial",
-        "mapping"
-    ],
-    "homepage": "https://github.com/eurostat/gridviz",
-    "author": "Joseph Davies, Julien Gaffuri",
-    "license": "EUPL-1.2",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/eurostat/gridviz.git"
-    },
-    "bugs": {
-        "url": "https://github.com/eurostat/gridviz/issues",
-        "email": "Joseph.DAVIES@ext.ec.europa.eu"
-    },
-    "type": "module",
-    "main": "dist/gridviz.min.js",
-    "module": "dist/gridviz.min.js",
-    "exports": {
-        "umd": "./dist/gridviz.min.js",
-        "default": "./src/index.js"
-    },
-    "scripts": {
-        "start": "webpack --config webpack.config.dev.cjs",
-        "server": "webpack serve -c webpack.config.dev.cjs",
-        "doc": "jsdoc -c docs/jsdoc/jsdoc.conf.json",
-        "build-prod": "webpack --config webpack.config.prod.cjs",
-        "test": "jest",
-        "format": "prettier --write ."
-    },
-    "files": [
-        "dist/**/*.js",
-        "src/**/*.js"
-    ],
-    "dependencies": {
-        "d3-array": "^3.2.4",
-        "d3-color": "^3.1.0",
-        "d3-fetch": "^3.0.1",
-        "d3-random": "^3.0.1",
-        "d3-scale": "^4.0.2",
-        "d3-selection": "^3.0.0",
-        "d3-zoom": "^3.0.0",
-        "jsdoc": "^4.0.4"
-    },
-    "devDependencies": {
-        "@babel/preset-env": "^7.25.4",
-        "babel-loader": "^8.1.0",
-        "jshint": "^2.12.0",
-        "prettier": "^2.8.8",
-        "webpack": "^5.96.1",
-        "webpack-cli": "^5.1.4",
-        "webpack-dev-server": "^5.1.0",
-        "webpack-livereload-plugin": "^3.0.2"
-    },
-    "engines": {
-        "node": ">=14"
-    }
-}
+{
+    "name": "gridviz",
+    "version": "3.0.38",
+    "description": "Visualization tool for gridded statistics",
+    "keywords": [
+        "statistics",
+        "grid",
+        "gridded",
+        "grids",
+        "gridded statistics",
+        "dataviz",
+        "csv",
+        "GIS",
+        "WebGL",
+        "d3",
+        "cartography",
+        "bertin",
+        "geospatial",
+        "mapping"
+    ],
+    "homepage": "https://github.com/eurostat/gridviz",
+    "author": "Joseph Davies, Julien Gaffuri",
+    "license": "EUPL-1.2",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/eurostat/gridviz.git"
+    },
+    "bugs": {
+        "url": "https://github.com/eurostat/gridviz/issues",
+        "email": "Joseph.DAVIES@ext.ec.europa.eu"
+    },
+    "type": "module",
+    "main": "dist/gridviz.min.js",
+    "module": "dist/gridviz.min.js",
+    "exports": {
+        "umd": "./dist/gridviz.min.js",
+        "default": "./src/index.js"
+    },
+    "scripts": {
+        "start": "webpack --config webpack.config.dev.cjs",
+        "server": "webpack serve -c webpack.config.dev.cjs",
+        "doc": "jsdoc -c docs/jsdoc/jsdoc.conf.json",
+        "build-prod": "webpack --config webpack.config.prod.cjs",
+        "test": "jest",
+        "format": "prettier --write ."
+    },
+    "files": [
+        "dist/**/*.js",
+        "src/**/*.js"
+    ],
+    "dependencies": {
+        "d3-array": "^3.2.4",
+        "d3-color": "^3.1.0",
+        "d3-fetch": "^3.0.1",
+        "d3-random": "^3.0.1",
+        "d3-scale": "^4.0.2",
+        "d3-selection": "^3.0.0",
+        "d3-zoom": "^3.0.0",
+        "jsdoc": "^4.0.4"
+    },
+    "devDependencies": {
+        "@babel/preset-env": "^7.25.4",
+        "babel-loader": "^8.1.0",
+        "jshint": "^2.12.0",
+        "prettier": "^2.8.8",
+        "webpack": "^5.96.1",
+        "webpack-cli": "^5.1.4",
+        "webpack-dev-server": "^5.1.0",
+        "webpack-livereload-plugin": "^3.0.2"
+    },
+    "engines": {
+        "node": ">=14"
+    }
+}

package/src/core/Legend.js

@@ -54,13 +54,30 @@ export class Legend {
             if (this.id) this.div.attr('id', this.id)
         }
 
+        // Which style options the caller set. The ones they didn't set are written as a CSS variable with the
+        // usual value as its fallback (--gridviz-legend-font-family, ...): nothing changes unless a page defines the variable.
+        /** @private */
+        this._set = {
+            padding: opts.padding !== undefined,
+            fontFamily: opts['font-family'] !== undefined,
+            titleFontSize: opts.titleFontSize !== undefined,
+            titleFontWeight: opts.titleFontWeight !== undefined,
+            labelFontSize: opts.labelFontSize !== undefined,
+        }
+
+        // CSS classes, to style legends from a stylesheet: gridviz-legend on every legend, a modifier for the
+        // type (see each legend class), and whatever the caller asks for with the className option.
+        this.div.classed('gridviz-legend', true)
+        if (opts.className)
+            for (const c of String(opts.className).split(/\s+/)) if (c) this.div.classed(c, true)
+
         //set style
         this.div.style('background', this.background)
-        this.div.style('padding', this.padding)
+        this.div.style('padding', this._css('padding', this.padding, this._set.padding))
         this.div.style('border', this.border)
         this.div.style('border-radius', this['border-radius'])
         this.div.style('box-shadow', this['box-shadow'])
-        this.div.style('font-family', this['font-family'])
+        this.div.style('font-family', this._css('font-family', this['font-family'], this._set.fontFamily))
 
         //if (this.width) this.div.style('width', this.width)
         //if (this.height) this.div.style('height', this.height)
@@ -74,16 +91,133 @@ export class Legend {
         this.labelFontSize = opts.labelFontSize || '0.8em'
         this.labelUnitText = opts.labelUnitText || ''
         this.labelFormat = opts.labelFormat
+
+        /**
+         * Whether the title and the labels are HTML (to italicise a word, for example) instead of plain text.
+         * Off by default, which is plain text. Only turn it on for text you trust: it is not escaped.
+         * @type {boolean} */
+        this.labelsAsHTML = opts.labelsAsHTML === true
+
+        /**
+         * Whether hovering a swatch of the legend shows only the matching cells on the map.
+         * @type {boolean} */
+        this.interactive = opts.interactive !== false
+
+        /**
+         * The style the legend belongs to, and a function to redraw the map. Both set by the layer when it draws.
+         * @type {import('./Style.js').Style|undefined} */
+        this.style_ = undefined
+        /** @type {function|undefined} */
+        this.redraw = undefined
+        /**
+         * The element the legends are drawn in, set by the layer when it draws.
+         * @type {HTMLElement|undefined} */
+        this.container = undefined
+
+        /**
+         * Draw at the width of the container instead of this.width (width:'fill').
+         * @type {boolean} @protected */
+        this.fill = opts.width === 'fill'
+    }
+
+    /**
+     * Show only the cells drawn in some colours on the map, or all of them again.
+     * @param {Array.<string>|null} colors
+     */
+    highlight(colors) {
+        if (!this.interactive || !this.style_) return
+        const before = this.style_.highlightColors
+        this.style_.setHighlight(colors)
+        // nothing to redraw when the highlight didn't change (mouse moving between a swatch's parts)
+        if (before === null && this.style_.highlightColors === null) return
+        if (this.redraw) this.redraw()
+    }
+
+    /**
+     * Make a swatch react to the mouse: hovering it highlights the cells of a colour on the map.
+     * @param {*} selection The d3 selection of the swatch (any element)
+     * @param {string} color The colour the swatch stands for
+     * @param {{enter?:function, leave?:function}} [extra] Extra feedback on the swatch itself
+     */
+    bindHover(selection, color, extra) {
+        if (!this.interactive) return
+        selection
+            .style('cursor', 'pointer')
+            .on('mouseenter', () => {
+                if (extra && extra.enter) extra.enter()
+                this.highlight([color])
+            })
+            .on('mouseleave', () => {
+                if (extra && extra.leave) extra.leave()
+                this.highlight(null)
+            })
+    }
+
+    /**
+     * A style value with a CSS variable around it, unless the caller set the option themselves.
+     * @param {string} name The variable's name, after --gridviz-legend-
+     * @param {string} value The value to use when the variable isn't defined
+     * @param {boolean} custom
+     * @returns {string}
+     * @protected
+     */
+    _css(name, value, custom) {
+        return custom ? value : `var(--gridviz-legend-${name}, ${value})`
+    }
+
+    /** The font size of the labels, for the style() of a label element.
+     * @returns {string}
+     * @protected */
+    labelFontSizeCSS() {
+        return this._css('label-font-size', this.labelFontSize, this._set.labelFontSize)
+    }
+
+    /**
+     * Mark the root element as a type of legend: the CSS class gridviz-legend--<type>.
+     * @param {string} type
+     * @protected
+     */
+    setType(type) {
+        this.div.classed('gridviz-legend--' + type, true)
+    }
+
+    /**
+     * The width to draw at: this.width, or with width:'fill' the width of the container the legends are in
+     * (the legendContainer of the map), less this legend's own padding.
+     * @param {number} fallback Used when the container has no width (yet, or hidden)
+     * @returns {number}
+     * @protected
+     */
+    availableWidth(fallback) {
+        if (!this.fill) return this.width
+        const container = this.container
+        const w = container && container.clientWidth
+        if (!w) return fallback
+        const p = parseFloat(this.padding) || 0
+        return Math.max(60, Math.floor(w - 2 * p))
+    }
+
+    /**
+     * Set the text of a d3 selection: as HTML if the legend has labelsAsHTML, as plain text otherwise.
+     * @param {*} selection
+     * @param {string} text
+     * @protected
+     */
+    setText(selection, text) {
+        return this.labelsAsHTML ? selection.html(text) : selection.text(text)
     }
 
     makeTitle() {
         if (!this.title) return
-        this.div
-            .append('div')
-            .style('font-size', this.titleFontSize)
-            .style('font-weight', this.titleFontWeight)
-            .style('margin-bottom', '7px')
-            .text(this.title)
+        this.setText(
+            this.div
+                .append('div')
+                .classed('gridviz-legend-title', true)
+                .style('font-size', this._css('title-font-size', this.titleFontSize, this._set.titleFontSize))
+                .style('font-weight', this._css('title-font-weight', this.titleFontWeight, this._set.titleFontWeight))
+                .style('margin-bottom', '7px'),
+            this.title
+        )
     }
 
     /**

package/src/core/Map.js

@@ -87,6 +87,13 @@ export class Map {
             ? select(opts.legendContainer) // Wrap the provided HTML node in a D3 selection
             : null
         this._legendProvidedByUser = !!opts.legendContainer
+
+        /**
+         * Called with the legend container (an HTML element) each time the map has drawn and its legends
+         * are in the container, for a host that needs to adjust them (fit their width, restyle...).
+         * It can also be set after the map is created.
+         * @type {function(HTMLElement):void|undefined} */
+        this.onLegendUpdate = opts.onLegendUpdate
         if (!this.legend) this.initialiseLegend()
 
         //tooltip
@@ -232,8 +239,9 @@ export class Map {
         // a destroyed map can still be asked to redraw by a dataset it shared (see destroy)
         if (this._destroyed) return this
 
-        //remove legend elements
-        if (this.legend) this.legend.selectAll('*').remove()
+        //remove legend elements: the legends themselves only, not what is inside them
+        //(a legend keeps its content while one of its swatches is hovered, see Style.updateLegends)
+        if (this.legend) this.legend.selectAll(':scope > *').remove()
 
         //clear
         this.geoCanvas.initCanvasTransform()
@@ -277,6 +285,9 @@ export class Map {
         // the canvas holds no focus rectangle any more
         this._focusedCell = undefined
 
+        // the legends are in the container now
+        if (this.onLegendUpdate && this.legend) this.onLegendUpdate(this.legend.node())
+
         return this
     }
 

package/src/core/Style.js

@@ -1,6 +1,7 @@
 //@ts-check
 'use strict'
 
+import { color as d3color } from 'd3-color'
 import { Drawable } from './Drawable.js'
 
 /** @typedef {"square"|"circle"|"diamond"|"donut"|"triangle_up"|"triangle_down"|"triangle_left"|"triangle_right"|"none"} Shape */
@@ -47,6 +48,48 @@ export class Style extends Drawable {
          * @public
          * @type {Array.<import("./Legend").Legend>} */
         this.legends = []
+
+        /**
+         * The colours of the cells to show while a legend swatch is hovered (see Legend.highlight),
+         * normalised with Style.normalizeColor. Null when nothing is highlighted.
+         * Styles that draw cells in a colour per class honour it with isHighlighted.
+         * @type {Array.<string>|null} */
+        this.highlightColors = null
+    }
+
+    /**
+     * A colour as a canonical string, so that '#ccc', 'rgb(204,204,204)' and '#cccccc' compare equal.
+     * @param {string} c
+     * @returns {string}
+     */
+    static normalizeColor(c) {
+        let n = Style._normalizedColors.get(c)
+        if (n === undefined) {
+            const parsed = d3color(c)
+            n = parsed ? parsed.formatRgb() : String(c)
+            // a style drawing millions of distinct colours must not grow this without bound
+            if (Style._normalizedColors.size > 10000) Style._normalizedColors.clear()
+            Style._normalizedColors.set(c, n)
+        }
+        return n
+    }
+
+    /**
+     * Show only the cells drawn in some colours: what hovering a legend swatch does.
+     * The map has to be redrawn for it to show (Legend.highlight does).
+     * @param {Array.<string>|null|undefined} colors The colours to show, or null to show everything again
+     * @returns {this} */
+    setHighlight(colors) {
+        this.highlightColors = colors && colors.length ? colors.map(Style.normalizeColor) : null
+        return this
+    }
+
+    /**
+     * Whether cells drawn in a colour are shown: always, unless a legend swatch is hovered and it is another colour.
+     * @param {string} c
+     * @returns {boolean} */
+    isHighlighted(c) {
+        return !this.highlightColors || this.highlightColors.includes(Style.normalizeColor(c))
     }
 
     /**
@@ -78,6 +121,8 @@ export class Style extends Drawable {
      * @param {object} opts
      * @returns {this} */
     updateLegends(opts) {
+        // the legend being hovered must keep its elements, or it would lose the mouse
+        if (this.highlightColors) return this
         Style.updateLegendsRecursive(this.legends, opts)
         return this
     }
@@ -96,3 +141,6 @@ export class Style extends Drawable {
         return this
     }
 }
+
+/** @type {Map<string,string>} */
+Style._normalizedColors = new Map()

package/src/layer/GridLayer.js

@@ -68,6 +68,9 @@ export class GridLayer extends Layer {
             if (this.blendOperation) ctx.globalCompositeOperation = this.blendOperation(z)
         }
 
+        // tell the legends where they are drawn, so that they can fit it (width:'fill')
+        if (legend) for (const s of this.styles) GridLayer.setLegendContainer(legend.node(), s.legends, s['styles'])
+
         //draw cells, style by style
         for (const s of this.styles) {
             //check if style is visible
@@ -102,14 +105,14 @@ export class GridLayer extends Layer {
             for (const s of this.styles) {
                 //check if style is visible
                 if (s.visible && !s.visible(z)) continue
-                GridLayer.addLegends(legend, s.legends)
+                GridLayer.addLegends(legend, s.legends, s, geoCanvas)
 
                 //case for styles of styles, like kernel smoothing
                 //TODO do better
                 if (s['styles']) {
                     for (const s2 of s['styles']) {
                         if (s2.visible && !s2.visible(z)) continue
-                        GridLayer.addLegends(legend, s2.legends)
+                        GridLayer.addLegends(legend, s2.legends, s2, geoCanvas)
                     }
                 }
             }
@@ -117,9 +120,25 @@ export class GridLayer extends Layer {
     }
 
     /** @private */
-    static addLegends(legendComp, lg) {
-        if (Array.isArray(lg)) for (const lg_ of lg) this.addLegends(legendComp, lg_)
-        else legendComp.node().append(lg.div.node())
+    static setLegendContainer(container, legends, subStyles) {
+        // legends can be nested in arrays, like in Style.updateLegendsRecursive
+        const set = (lg) => {
+            if (Array.isArray(lg)) lg.forEach(set)
+            else if (lg) lg.container = container
+        }
+        set(legends)
+        for (const s2 of subStyles || []) GridLayer.setLegendContainer(container, s2.legends, undefined)
+    }
+
+    /** @private */
+    static addLegends(legendComp, lg, style, geoCanvas) {
+        if (Array.isArray(lg)) for (const lg_ of lg) this.addLegends(legendComp, lg_, style, geoCanvas)
+        else {
+            // so that hovering a swatch can highlight the cells of the style on the map
+            lg.style_ = style
+            lg.redraw = () => (geoCanvas.redraw ? geoCanvas.redraw() : undefined)
+            legendComp.node().append(lg.div.node())
+        }
     }
 
     /**

package/src/legend/ColorCategoryLegend.js

@@ -28,6 +28,7 @@ export class ColorCategoryLegend extends Legend {
         this.dimension = opts.dimension || { r: 8 }
         this.strokeColor = opts.strokeColor || 'gray'
         this.strokeWidth = opts.strokeWidth || 1
+        this.setType('category')
     }
 
     /**
@@ -47,7 +48,12 @@ export class ColorCategoryLegend extends Legend {
             const cat = this.colorLabel[i]
 
             //make div for category
-            const d = this.div.append('div')
+            const d = this.div.append('div').classed('gridviz-legend-category', true)
+            // hovering a category shows only its cells on the map
+            this.bindHover(d, cat[0], {
+                enter: () => d.classed('gridviz-legend-category--active', true).select('svg').select('rect, circle').style('stroke', 'red'),
+                leave: () => d.classed('gridviz-legend-category--active', false).select('svg').select('rect, circle').style('stroke', this.strokeColor),
+            })
             //to enable vertical centering
             //.style("position", "relative")
 
@@ -65,6 +71,7 @@ export class ColorCategoryLegend extends Legend {
                     .attr('height', h + 2 * sw)
 
                     .append('rect')
+                    .classed('gridviz-legend-swatch', true)
                     .attr('x', sw)
                     .attr('y', sw)
                     .attr('width', w)
@@ -83,6 +90,7 @@ export class ColorCategoryLegend extends Legend {
                     .attr('height', h)
 
                     .append('circle')
+                    .classed('gridviz-legend-swatch', true)
                     .attr('cx', r + sw)
                     .attr('cy', r + sw)
                     .attr('r', r)
@@ -94,16 +102,20 @@ export class ColorCategoryLegend extends Legend {
             }
 
             //write label text
-            d.append('div')
-                //show on right of graphic
-                .style('display', 'inline')
+            this.setText(
+                d
+                    .append('div')
+                    //show on right of graphic
+                    .style('display', 'inline')
 
-                //center vertically
-                //.style("position", "absolute").style("top", "0").style("bottom", "0")
+                    //center vertically
+                    //.style("position", "absolute").style("top", "0").style("bottom", "0")
 
-                .style('padding-left', '5px')
-                .style('font-size', this.labelFontSize)
-                .text(cat[1])
+                    .classed('gridviz-legend-label', true)
+                    .style('padding-left', '5px')
+                    .style('font-size', this.labelFontSizeCSS()),
+                cat[1]
+            )
         }
     }
 }

package/src/legend/ColorDiscreteLegend.js

@@ -21,8 +21,10 @@ export class ColorDiscreteLegend extends Legend {
         /** @private @type {function(import('../core/Style').ViewScale):Array.<number>} */
         this.breaks = opts.breaks
 
-        this.width = opts.width || 300
+        // a number of pixels, or 'fill' for the width of the container
+        this.width = opts.width === 'fill' ? 300 : opts.width || 300
         this.height = opts.height || 15
+        this.setType('discrete')
 
         this.tickSize = opts.tickSize || 3
 
@@ -48,27 +50,37 @@ export class ColorDiscreteLegend extends Legend {
         //classes
         const nb = colors.length
         if (nb == 0) return
-        const w = this.width / nb
+        const width = this.availableWidth(this.width)
+        const w = width / nb
 
         //make svg element
         const svg = this.div
             .append('svg')
-            .attr('width', this.width)
+            .attr('width', width)
             .attr('height', this.height + this.tickSize + 2 + 10)
 
         //draw graphic elements
         for (let i = 0; i < nb; i++) {
-            svg.append('rect')
+            const rect = svg
+                .append('rect')
+                .classed('gridviz-legend-swatch', true)
                 .attr('x', i * w)
                 .attr('y', 0)
                 .attr('width', w)
                 .attr('height', this.height)
                 .style('fill', colors[i])
+            // hovering a class shows only its cells on the map
+            this.bindHover(rect, colors[i], {
+                // a presentation attribute, so that a stylesheet can restyle the active swatch
+                enter: () => rect.classed('gridviz-legend-swatch--active', true).attr('stroke', 'red'),
+                leave: () => rect.classed('gridviz-legend-swatch--active', false).attr('stroke', null),
+            })
         }
 
         //tick line
         for (let i = 1; i < nb; i++) {
             svg.append('line')
+                .classed('gridviz-legend-tick', true)
                 .attr('x1', w * i)
                 .attr('y1', 0)
                 .attr('x2', w * i)
@@ -84,10 +96,11 @@ export class ColorDiscreteLegend extends Legend {
 
             //label
             svg.append('text')
+                .classed('gridviz-legend-label', true)
                 .attr('id', 'ticklabel_' + i)
                 .attr('x', w * i)
                 .attr('y', this.height + this.tickSize + 2)
-                .style('font-size', this.labelFontSize)
+                .style('font-size', this.labelFontSizeCSS())
                 //.style("font-weight", "bold")
                 //.style("font-family", "Arial")
                 .style('text-anchor', 'middle')

package/src/legend/ColorLegend.js

@@ -35,8 +35,10 @@ export class ColorLegend extends Legend {
         this.fontSize = opts.fontSize || '0.8em'
         this.invert = opts.invert
 
-        this.width = opts.width || 300
+        // a number of pixels, or 'fill' for the width of the container
+        this.width = opts.width === 'fill' ? 300 : opts.width || 300
         this.height = opts.height || 15
+        this.setType('color')
     }
 
     /**
@@ -49,7 +51,8 @@ export class ColorLegend extends Legend {
         //title
         this.makeTitle()
 
-        const svgW = this.width + 2 * this.margin
+        const width = this.availableWidth(this.width)
+        const svgW = width + 2 * this.margin
         const svgH = this.height + this.margin + this.tickSize + 10
         const svg = this.div.append('svg').attr('width', svgW).attr('height', svgH)
         //  <rect width="300" height="100" style="fill:rgb(0,0,255);stroke-width:3;stroke:rgb(0,0,0)" />
@@ -57,13 +60,14 @@ export class ColorLegend extends Legend {
         const g = svg.append('g').attr('transform', 'translate(' + this.margin + ' ' + 0 + ')')
 
         //draw color bar
-        const w = this.width,
+        const w = width,
             h = this.height
         const step = 5
         for (let i = 0; i < w; i += step) {
             let t = i / (w - 1)
             if (this.invert) t = 1 - t
             g.append('rect')
+                .classed('gridviz-legend-swatch', true)
                 .attr('x', i)
                 .attr('y', 0)
                 .attr('width', step)
@@ -76,6 +80,7 @@ export class ColorLegend extends Legend {
 
             //tick line
             g.append('line')
+                .classed('gridviz-legend-tick', true)
                 .attr('x1', w * t)
                 .attr('y1', 0)
                 .attr('x2', w * t)
@@ -84,6 +89,7 @@ export class ColorLegend extends Legend {
 
             //prepare tick label
             g.append('text')
+                .classed('gridviz-legend-label', true)
                 .attr('id', 'ticklabel_' + i)
                 .attr('x', w * t)
                 .attr('y', h + this.tickSize + 2)