gridviz 3.0.37 → 3.0.39

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.39",
+    "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/button/Button.js

@@ -30,7 +30,8 @@ export class Button {
         }
 
         if (opts.title) this.div.attr('title', opts.title)
-        if (opts.class) this.div.attr('class', opts.class)
+        this.div.classed('gridviz-button', true)
+        if (opts.class) for (const c of String(opts.class).split(/\s+/)) if (c) this.div.classed(c, true)
 
         // add events
         if (opts.onClickFunction) this.div.on('click', opts.onClickFunction)

package/src/button/FullscreenButton.js

@@ -24,10 +24,12 @@ export class FullscreenButton extends Button {
 
     constructor(opts) {
         super(opts)
+        this.div.classed('gridviz-fullscreen-button', true)
 
         // append fullscreen icon to button container
         this.div.node().innerHTML = `
         <svg
+            class="gridviz-fullscreen-icon"
             style="height: 1.2rem; width: 1.2rem; fill:black; margin:0;"
             focusable="false"
             aria-hidden="true"

package/src/button/ZoomButtons.js

@@ -15,11 +15,12 @@ export class ZoomButtons extends Button {
 
         this.onZoom = opts.onZoom // custom user event handler
         this.delta = opts.delta || 0.2
+        this.div.classed('gridviz-zoom-buttons', true)
 
         // Create zoom in button
         this.zoomInBtn = document.createElement('a')
         this.zoomInBtn.id = 'zoom-in'
-        this.zoomInBtn.className = 'gridviz-zoom-button'
+        this.zoomInBtn.className = 'gridviz-zoom-button gridviz-zoom-button--in'
         this.zoomInBtn.title = 'Zoom in'
         this.zoomInBtn.textContent = '+'
         this.zoomInBtn.addEventListener('click', (e) => {
@@ -35,7 +36,7 @@ export class ZoomButtons extends Button {
         // Create zoom out button
         this.zoomOutBtn = document.createElement('a')
         this.zoomOutBtn.id = 'zoom-out'
-        this.zoomOutBtn.className = 'gridviz-zoom-button'
+        this.zoomOutBtn.className = 'gridviz-zoom-button gridviz-zoom-button--out'
         this.zoomOutBtn.title = 'Zoom out'
         this.zoomOutBtn.textContent = '-'
         this.zoomOutBtn.addEventListener('click', (e) => {

package/src/core/GeoCanvas.js

@@ -114,6 +114,7 @@ export class GeoCanvas {
                     this.canvasSave.dx = 0
                     this.canvasSave.dy = 0
                     this.canvasSave.f = 1
+                    this.canvasSave.view = { x: this.view.x, y: this.view.y, z: this.view.z }
                     if (this.onZoomStartFun) this.onZoomStartFun(e)
                 })
                 .on('end', (e) => {
@@ -179,7 +180,7 @@ export class GeoCanvas {
         this.zoomExtent = opts.zoomExtent || [0, Infinity]
 
         /** Canvas state, to be used to avoid unnecessary redraws on zoom/pan
-         *  @type {{c:HTMLCanvasElement|null,dx:number,dy:number,f:number}} */
+         *  @type {{c:HTMLCanvasElement|null,dx:number,dy:number,f:number,view?:{x:number,y:number,z:number}}} */
         this.canvasSave = { c: null, dx: 0, dy: 0, f: 1 }
     }
 
@@ -200,21 +201,7 @@ export class GeoCanvas {
         this.updateExtentGeo()
 
         if (this.canvasSave.c) {
-            const scale = 1 / this.view.z
-
-            // Update saved canvas offset
-            this.canvasSave.dx -= dxGeo * scale
-            this.canvasSave.dy += dyGeo * scale
-
-            // clear canvas
-            this.clear(this.backgroundColor)
-
-            // this doesnt work on mobile https://github.com/eurostat/gridviz/issues/98
-            //this.ctx.drawImage(this.canvasSave.c, this.canvasSave.dx, this.canvasSave.dy)
-            this.offscreenCtx.drawImage(this.canvasSave.c, this.canvasSave.dx, this.canvasSave.dy)
-
-            // Render the offscreen canvas to the visible context
-            this.ctx.drawImage(this.offscreenCtx.canvas, 0, 0)
+            this._drawSnapshot()
         } else {
             console.log('no canvas save')
         }
@@ -258,29 +245,38 @@ export class GeoCanvas {
         this._drawZoomFrame(f, xGeo, yGeo)
     }
 
-    _drawZoomFrame(f, xGeo, yGeo) {
+    _drawZoomFrame() {
         // zoom in on the current canvas state
-        if (this.canvasSave.c) {
-            this.clear(this.backgroundColor)
-            this.canvasSave.f /= f
-            this.canvasSave.dx = this.geoToPixX(xGeo) * (1 - this.canvasSave.f)
-            this.canvasSave.dy = this.geoToPixY(yGeo) * (1 - this.canvasSave.f)
-            this.clear(this.backgroundColor)
-            this.offscreenCtx.drawImage(
-                this.canvasSave.c,
-                this.canvasSave.dx,
-                this.canvasSave.dy,
-                this.canvasSave.f * this.canvasSave.c.width,
-                this.canvasSave.f * this.canvasSave.c.height
-            )
-            this.ctx.drawImage(
-                this.offscreenCanvas, // Use offscreen canvas as the source
-                0,
-                0, // Position the offscreen canvas at the top-left corner of the main canvas
-                this.canvas.width, // The width of the visible canvas
-                this.canvas.height // The height of the visible canvas
-            )
-        }
+        if (this.canvasSave.c) this._drawSnapshot()
+    }
+
+    /**
+     * Draw the canvas saved when the pan/zoom started where it belongs in the current view.
+     * It is placed from the two views (the one it was taken at and the current one) rather than
+     * accumulated from each step: the zoom anchor follows the mouse, and an accumulation that
+     * assumes it stays put leaves the picture away from where the final redraw puts it.
+     * @private
+     */
+    _drawSnapshot() {
+        const sv = this.canvasSave.view
+        const f = sv ? sv.z / this.view.z : 1
+        // where the saved canvas' top left corner is in the current view
+        const dx = sv ? (sv.x - (this.w * 0.5) * sv.z - this.view.x) / this.view.z + this.w * 0.5 : 0
+        const dy = sv ? this.h * 0.5 - (sv.y + (this.h * 0.5) * sv.z - this.view.y) / this.view.z : 0
+        this.canvasSave.f = f
+        this.canvasSave.dx = dx
+        this.canvasSave.dy = dy
+
+        this.clear(this.backgroundColor)
+        // this doesnt work on mobile https://github.com/eurostat/gridviz/issues/98 : drawn on the offscreen canvas first
+        this.offscreenCtx.drawImage(
+            this.canvasSave.c,
+            dx,
+            dy,
+            f * this.canvasSave.c.width,
+            f * this.canvasSave.c.height
+        )
+        this.ctx.drawImage(this.offscreenCanvas, 0, 0, this.canvas.width, this.canvas.height)
     }
 
     /**

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,136 @@ 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
+        // flag the legend while hovered, so that the map's redraw leaves its element in place:
+        // a hovered element that is detached and appended again never gets its mouseleave
+        if (this.div) this.div.attr('data-gridviz-hovered', colors && colors.length ? '' : null)
+        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

@@ -46,6 +46,7 @@ export class Map {
             console.error('Cannot find gridviz container element.')
             return
         }
+        this.container.classList.add('gridviz-map')
 
         //https://css-tricks.com/absolute-positioning-inside-relative-positioning/
         this.container.style.position = 'relative' // container element must have relative positioning
@@ -87,6 +88,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
@@ -167,6 +175,7 @@ export class Map {
      */
     initialiseCanvas() {
         const canvas = document.createElement('canvas')
+        canvas.classList.add('gridviz-canvas')
         canvas.setAttribute('width', '' + this.w)
         canvas.setAttribute('height', '' + this.h)
         this.container.appendChild(canvas)
@@ -177,6 +186,7 @@ export class Map {
         this.legend = select(this.container)
             .append('div') // Create a new container
             .attr('id', 'gridviz-legend')
+            .classed('gridviz-legends', true)
             .style('position', 'absolute')
             .style('width', 'auto')
             .style('height', 'auto')
@@ -232,8 +242,10 @@ 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)
+        //except the one being hovered, which would lose its mouseleave (see Legend.highlight)
+        if (this.legend) this.legend.selectAll(':scope > *:not([data-gridviz-hovered])').remove()
 
         //clear
         this.geoCanvas.initCanvasTransform()
@@ -277,6 +289,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/core/Tooltip.js

@@ -75,6 +75,9 @@ export class Tooltip {
         this.tooltip.style('left', '0')
         this.tooltip.style('top', '0')
 
+        // a tooltip element given by the user gets the class too
+        this.tooltip.classed('gridviz-tooltip', true)
+
         // aria-labels (thanks to wahlatlas)
         this.tooltip.attr('role', 'tooltip').attr('aria-live', 'polite')
     }