gridviz 3.0.36 → 3.0.38

package/package.json

@@ -1,74 +1,74 @@
-{
-    "name": "gridviz",
-    "version": "3.0.36",
-    "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/Dataset.js

@@ -120,6 +120,32 @@ export class Dataset {
 
         /** @type {number} */
         const r = this.getResolution()
+
+        // Look the cell up in an index of the cells by grid position, built once per cell
+        // list (the view cache is a new array after each redraw) instead of scanning every
+        // cell on every mouse move.
+        const index = this.cellIndex(cells, r)
+        if (index) {
+            const fx = (posGeo.x - index.ox) / r
+            const fy = (posGeo.y - index.oy) / r
+            const ix = Math.floor(fx)
+            const iy = Math.floor(fy)
+            // a position on a cell's right/top edge also belongs to that cell (inclusive
+            // bounds, as in the scan below): check the cells left of and below it too
+            for (const [dx, dy] of [
+                [0, 0],
+                [-1, 0],
+                [0, -1],
+                [-1, -1],
+            ]) {
+                if (dx && fx !== ix) continue
+                if (dy && fy !== iy) continue
+                const cell = index.cells.get(cellKey(ix + dx, iy + dy))
+                if (cell) return cell
+            }
+            return undefined
+        }
+
         for (const cell of cells) {
             if (posGeo.x < cell.x) continue
             else if (cell.x + r < posGeo.x) continue
@@ -130,6 +156,47 @@ export class Dataset {
         return undefined
     }
 
+    /**
+     * An index of cells by their position on the grid of resolution r, or null when some
+     * cell isn't on a common grid (then the caller scans the cells). Cached for the last
+     * cell list given.
+     *
+     * @param {Array.<Cell>} cells
+     * @param {number} r
+     * @returns {{cells: Map<number, Cell>, ox: number, oy: number} | null}
+     * @protected
+     */
+    cellIndex(cells, r) {
+        if (this._index && this._indexCells === cells && this._indexLength === cells.length && this._indexR === r)
+            return this._index
+        let index = null
+        if (cells.length && r > 0) {
+            const ox = +cells[0].x
+            const oy = +cells[0].y
+            const map = new Map()
+            index = { cells: map, ox, oy }
+            for (const cell of cells) {
+                const fx = (+cell.x - ox) / r
+                const fy = (+cell.y - oy) / r
+                const ix = Math.round(fx)
+                const iy = Math.round(fy)
+                // not on the grid: no index, scan instead
+                if (Math.abs(fx - ix) > 1e-6 || Math.abs(fy - iy) > 1e-6) {
+                    index = null
+                    break
+                }
+                const key = cellKey(ix, iy)
+                // the first cell at a position wins, as in the scan
+                if (!map.has(key)) map.set(key, cell)
+            }
+        }
+        this._index = index
+        this._indexCells = cells
+        this._indexLength = cells.length
+        this._indexR = r
+        return index
+    }
+
     //getters and setters
 
     /** @returns {number} */
@@ -152,3 +219,14 @@ export class Dataset {
         return this
     }
 }
+
+/**
+ * One number per grid position: cell positions relative to the first cell stay well
+ * within +-2^21, so x * 2^22 + y is exact.
+ * @param {number} ix
+ * @param {number} iy
+ * @returns {number}
+ */
+function cellKey(ix, iy) {
+    return ix * 4194304 + iy
+}

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

@@ -30,6 +30,16 @@ export class Map {
          * */
         this.layers = opts.layers || []
 
+        /**
+         * When true, redraw() schedules one redraw for the next animation frame instead of
+         * drawing at once, so the many redraw requests of a busy moment (every tile that
+         * arrives, every info.json, every setting change) are drawn once. redrawNow() still
+         * draws at once. Off by default: redraw() stays synchronous, as it always was.
+         * @type {boolean} */
+        this.asyncRedraw = !!opts.asyncRedraw
+        /** @private @type {number|null} */
+        this._redrawFrame = null
+
         //get container element
         this.container = container || document.getElementById('gridviz')
         if (!this.container) {
@@ -77,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
@@ -96,10 +113,31 @@ export class Map {
          * @type {boolean} */
         this.digForTooltip = opts.digForTooltip || false
 
-        // add event listeners to container
-        this.mouseOverHandler = (e) => this.focusCell(e)
-        this.mouseMoveHandler = (e) => this.focusCell(e)
-        this.mouseOutHandler = (e) => this.tooltip.hide()
+        // add event listeners to the canvas. Mouse moves are handled at most once per
+        // animation frame (the latest one): finding the cell and redrawing the highlight
+        // for every intermediate event only delays the one that's shown.
+        /** @private */
+        this._focusFrame = null
+        /** @private */
+        this._focusEvent = null
+        const scheduleFocus = (e) => {
+            this._focusEvent = e
+            if (this._focusFrame) return
+            this._focusFrame = requestAnimationFrame(() => {
+                this._focusFrame = null
+                const ev = this._focusEvent
+                this._focusEvent = null
+                if (ev) this.focusCell(ev)
+            })
+        }
+        this.mouseOverHandler = scheduleFocus
+        this.mouseMoveHandler = scheduleFocus
+        this.mouseOutHandler = (e) => {
+            if (this._focusFrame) cancelAnimationFrame(this._focusFrame)
+            this._focusFrame = null
+            this._focusEvent = null
+            this.tooltip.hide()
+        }
         this.geoCanvas.canvas.addEventListener('mouseover', this.mouseOverHandler)
         this.geoCanvas.canvas.addEventListener('mousemove', this.mouseMoveHandler)
         this.geoCanvas.canvas.addEventListener('mouseout', this.mouseOutHandler)
@@ -176,10 +214,34 @@ export class Map {
         return this
     }
 
-    /** @returns {this} */
+    /**
+     * Redraws the map: at once, or, with the asyncRedraw option, once at the next
+     * animation frame however many times it's called before then.
+     * @returns {this} */
     redraw() {
-        //remove legend elements
-        if (this.legend) this.legend.selectAll('*').remove()
+        if (this.asyncRedraw) {
+            if (!this._redrawFrame && !this._destroyed)
+                this._redrawFrame = requestAnimationFrame(() => {
+                    this._redrawFrame = null
+                    this.redrawNow()
+                })
+            return this
+        }
+        return this.redrawNow()
+    }
+
+    /**
+     * Redraws the map at once, whatever the asyncRedraw option (and cancels a scheduled redraw).
+     * @returns {this} */
+    redrawNow() {
+        if (this._redrawFrame) cancelAnimationFrame(this._redrawFrame)
+        this._redrawFrame = null
+        // a destroyed map can still be asked to redraw by a dataset it shared (see destroy)
+        if (this._destroyed) return this
+
+        //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()
@@ -220,6 +282,11 @@ export class Map {
         this.geoCanvas.ctx.drawImage(this.geoCanvas.offscreenCanvas, 0, 0)
 
         this.canvasSave = null
+        // 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
     }
@@ -246,6 +313,18 @@ export class Map {
         /** @type {{cell:import('./Dataset.js').Cell,html:string,resolution:number} | undefined} */
         const focus = this.getCellFocusInfo(mousePositionGeo)
 
+        // Same cell as the one already highlighted (or still no cell): the canvas is right
+        // as it is, only the tooltip follows the mouse. Saves a full-canvas copy per move.
+        const focusedCell = focus ? focus.cell : null
+        if (focusedCell === this._focusedCell) {
+            if (focus) {
+                this.tooltip.setPosition(e)
+                this.tooltip.show()
+            } else this.tooltip.hide()
+            return
+        }
+        this._focusedCell = focusedCell
+
         // Transparent background (Leaflet): redraw base, then draw focus rect directly on the visible canvas
         if (this.transparentBackground) {
             // Always restore the base (offscreen) into the visible canvas
@@ -536,6 +615,8 @@ export class Map {
         })
 
         resizeObserver.observe(this.container)
+        /** @private */
+        this._resizeObserver = resizeObserver
     }
 
     /**
@@ -544,14 +625,26 @@ export class Map {
      * @memberof App
      */
     destroy() {
+        this._destroyed = true
+
         // clear layers
         this.layers = []
         this.bgLayers = []
 
-        // remove event listeners from container
-        this.container.removeEventListener('mouseover', this.mouseOverHandler)
-        this.container.removeEventListener('mousemove', this.mouseMoveHandler)
-        this.container.removeEventListener('mouseout', this.mouseOutHandler)
+        // cancel scheduled work
+        if (this._redrawFrame) cancelAnimationFrame(this._redrawFrame)
+        this._redrawFrame = null
+        if (this._focusFrame) cancelAnimationFrame(this._focusFrame)
+        this._focusFrame = null
+
+        // stop observing the container: the observer would otherwise keep this map alive
+        if (this._resizeObserver) this._resizeObserver.disconnect()
+        this._resizeObserver = null
+
+        // remove event listeners, from the canvas they were added to
+        this.geoCanvas.canvas.removeEventListener('mouseover', this.mouseOverHandler)
+        this.geoCanvas.canvas.removeEventListener('mousemove', this.mouseMoveHandler)
+        this.geoCanvas.canvas.removeEventListener('mouseout', this.mouseOutHandler)
 
         // remove canvas
         this.geoCanvas.canvas.remove()

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()