eurostat-map 4.4.4 → 4.5.0

package/build/package.json

@@ -1,87 +1,87 @@
-{
-    "name": "eurostat-map",
-    "version": "4.4.4",
-    "description": "Reusable library to quickly create and customise web maps showing Eurostat data directly retrieved from Eurostat database.",
-    "keywords": [
-        "eurostat",
-        "statistics",
-        "europe",
-        "SVG",
-        "NUTS",
-        "map",
-        "D3",
-        "cartography",
-        "thematic",
-        "mapping",
-        "eurostat-map",
-        "dataviz",
-        "data visualization"
-    ],
-    "homepage": "https://github.com/eurostat/eurostat-map",
-    "author": "",
-    "license": "EUPL-1.2",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/eurostat/eurostat-map.git"
-    },
-    "main": "build/eurostatmap.min.js",
-    "unpkg": "build/eurostatmap.min.js",
-    "module": "build/eurostatmap.js",
-    "types": "build/types/index.d.ts",
-    "typings": "build/types/index.d.ts",
-    "files": [
-        "build"
-    ],
-    "scripts": {
-        "start": "webpack --config webpack/webpack.config.dev.js",
-        "server": "webpack-dev-server --open --watch",
-        "build-types": "tsc --project tsconfig.json",
-        "build-prod": "npm run build-types && webpack --config webpack/webpack.config.prod.js",
-        "build-prod-debug": "webpack --config webpack/webpack.config.debug-size.js",
-        "format": "prettier --write .",
-        "test": "jest",
-        "type-check": "tsc --noEmit"
-    },
-    "dependencies": {
-        "d3-array": "^3.2.4",
-        "d3-axis": "^3.0.0",
-        "d3-ease": "^3.0.1",
-        "d3-fetch": "^3.0.1",
-        "d3-force": "^3.0.0",
-        "d3-format": "^3.1.0",
-        "d3-geo": "^3.1.1",
-        "d3-geo-projection": "^3.0.0",
-        "d3-interpolate": "^3.0.1",
-        "d3-scale": "^4.0.2",
-        "d3-scale-chromatic": "^3.1.0",
-        "d3-selection": "^3.0.0",
-        "d3-shape": "^3.2.0",
-        "d3-svg-annotation": "^2.5.1",
-        "d3-zoom": "^3.0.0",
-        "idb-keyval": "^6.2.2",
-        "jsonstat-toolkit": "^1.0.8",
-        "proj4": "^2.17.0",
-        "simple-statistics": "^7.8.8",
-        "topojson-client": "^3.1.0"
-    },
-    "overrides": {
-        "d3-color": "3.1.0"
-    },
-    "devDependencies": {
-        "@babel/core": "^7.22.6",
-        "@babel/plugin-transform-runtime": "^7.22.6",
-        "@babel/preset-env": "^7.22.6",
-        "@babel/runtime": "^7.12.1",
-        "babel-loader": "^9.1.2",
-        "css-loader": "^7.1.2",
-        "prettier": "^3.4.1",
-        "style-loader": "^4.0.0",
-        "ts-loader": "^9.5.4",
-        "typescript": "^5.9.3",
-        "webpack": "^5.88.1",
-        "webpack-bundle-analyzer": "^4.10.2",
-        "webpack-cli": "^5.0.0",
-        "webpack-dev-server": "^5.2.2",
-        "webpack-livereload-plugin": "^3.0.2"
-    }
-}
+{
+    "name": "eurostat-map",
+    "version": "4.5.0",
+    "description": "Reusable library to quickly create and customise web maps showing Eurostat data directly retrieved from Eurostat database.",
+    "keywords": [
+        "eurostat",
+        "statistics",
+        "europe",
+        "SVG",
+        "NUTS",
+        "map",
+        "D3",
+        "cartography",
+        "thematic",
+        "mapping",
+        "eurostat-map",
+        "dataviz",
+        "data visualization"
+    ],
+    "homepage": "https://github.com/eurostat/eurostat-map",
+    "author": "",
+    "license": "EUPL-1.2",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/eurostat/eurostat-map.git"
+    },
+    "main": "build/eurostatmap.min.js",
+    "unpkg": "build/eurostatmap.min.js",
+    "module": "build/eurostatmap.js",
+    "types": "build/types/index.d.ts",
+    "typings": "build/types/index.d.ts",
+    "files": [
+        "build"
+    ],
+    "scripts": {
+        "start": "webpack --config webpack/webpack.config.dev.js",
+        "server": "webpack-dev-server --open --watch",
+        "build-types": "tsc --project tsconfig.json",
+        "build-prod": "npm run build-types && webpack --config webpack/webpack.config.prod.js",
+        "build-prod-debug": "webpack --config webpack/webpack.config.debug-size.js",
+        "format": "prettier --write .",
+        "test": "jest",
+        "type-check": "tsc --noEmit"
+    },
+    "dependencies": {
+        "d3-array": "^3.2.4",
+        "d3-axis": "^3.0.0",
+        "d3-ease": "^3.0.1",
+        "d3-fetch": "^3.0.1",
+        "d3-force": "^3.0.0",
+        "d3-format": "^3.1.0",
+        "d3-geo": "^3.1.1",
+        "d3-geo-projection": "^3.0.0",
+        "d3-interpolate": "^3.0.1",
+        "d3-scale": "^4.0.2",
+        "d3-scale-chromatic": "^3.1.0",
+        "d3-selection": "^3.0.0",
+        "d3-shape": "^3.2.0",
+        "d3-svg-annotation": "^2.5.1",
+        "d3-zoom": "^3.0.0",
+        "idb-keyval": "^6.2.2",
+        "jsonstat-toolkit": "^1.0.8",
+        "proj4": "^2.17.0",
+        "simple-statistics": "^7.8.8",
+        "topojson-client": "^3.1.0"
+    },
+    "overrides": {
+        "d3-color": "3.1.0"
+    },
+    "devDependencies": {
+        "@babel/core": "^7.22.6",
+        "@babel/plugin-transform-runtime": "^7.22.6",
+        "@babel/preset-env": "^7.22.6",
+        "@babel/runtime": "^7.12.1",
+        "babel-loader": "^9.1.2",
+        "css-loader": "^7.1.2",
+        "prettier": "^3.4.1",
+        "style-loader": "^4.0.0",
+        "ts-loader": "^9.5.4",
+        "typescript": "^5.9.3",
+        "webpack": "^5.88.1",
+        "webpack-bundle-analyzer": "^4.10.2",
+        "webpack-cli": "^5.0.0",
+        "webpack-dev-server": "^5.2.2",
+        "webpack-livereload-plugin": "^3.0.2"
+    }
+}

package/build/types/core/GridCartogramSettings.d.ts

@@ -12,6 +12,14 @@ export interface GridCartogramMargins {
     left: number
 }
 
+/** Shared chart offset for symbols drawn inside each grid cell. */
+export interface GridCartogramChartOffset {
+    /** Horizontal offset in pixels. Positive moves right. */
+    x: number
+    /** Vertical offset in pixels. Positive moves down. */
+    y: number
+}
+
 /**
  * Settings for grid cartogram layout and geometry.
  */
@@ -22,6 +30,31 @@ export interface GridCartogramSettings {
     margins: GridCartogramMargins
     /** Extra spacing between grid cells in pixels. */
     cellPadding: number
+    /** Country-label rendering settings for grid cartograms. */
+    countryLabelSettings?: {
+        /** Show country labels as codes, names, or a custom string. */
+        countryLabels?: 'code' | 'name' | ((id: string, name: string | undefined, region?: any) => string)
+        /** Base font size for country labels in grid cartograms. */
+        countryLabelFontSize?: number
+        /** Minimum font size allowed when shrinking labels to avoid overlap. */
+        countryLabelMinFontSize?: number
+        /** Extra padding subtracted from the available label width before fitting. */
+        countryLabelPadding?: { x: number; y: number }
+        /** Disable automatic label shrinking/stretching to avoid overlap. @default false */
+        countryLabelAvoidOverlap?: boolean
+    }
+    /** @deprecated Use countryLabelSettings.countryLabels instead. */
+    countryLabels?: 'code' | 'name' | ((id: string, name: string | undefined, region?: any) => string)
+    /** @deprecated Use countryLabelSettings.countryLabelFontSize instead. */
+    countryLabelFontSize?: number
+    /** @deprecated Use countryLabelSettings.countryLabelMinFontSize instead. */
+    countryLabelMinFontSize?: number
+    /** @deprecated Use countryLabelSettings.countryLabelPadding instead. */
+    countryLabelPadding?: { x: number; y: number }
+    /** @deprecated Use countryLabelSettings.countryLabelAvoidOverlap instead. */
+    countryLabelAvoidOverlap?: boolean
+    /** Shared chart offset in grid cells for chart-based map types. */
+    chartOffset: GridCartogramChartOffset
     /**
      * Custom grid layout CSV string.
      * If undefined, the built-in layout for the selected shape is used.

package/build/types/core/MapConfig.d.ts

@@ -1,4 +1,5 @@
 import type { StatConfig } from './stat/StatConfig'
+import type { CompositionStatConfig } from '../layers/composition/CompositionStatConfig'
 import type { LegendConfig } from '../legend/LegendConfig'
 import type { TooltipConfig } from './TooltipConfig'
 import type { InsetConfig } from './InsetConfig'
@@ -7,6 +8,7 @@ import type { CoastalMarginSettings } from './decoration/CoastalMarginSettings'
 import type { GridCartogramSettings } from './GridCartogramSettings'
 import type { DorlingSettings } from './DorlingSettings'
 import type { ScalebarConfig } from './decoration/ScalebarConfig'
+import type { EncodingConfig } from './encoding/EncodingConfig'
 
 /**
  * Base configuration for all map types. Each specific map type will extend this with its own properties, but these are the common ones that apply to all maps.
@@ -56,8 +58,17 @@ export interface MapConfig {
     /** Data source text. */
     source?: string
 
-    /** Statistical data configuration. */
-    stat?: StatConfig
+    /**
+     * Statistical data configuration.
+     *
+     * Preferred for multi-dataset maps:
+     *  - set named datasets via `stat` dictionary
+     *  - bind channels via `encoding`
+     */
+    stat?: StatConfig | CompositionStatConfig | Record<string, StatConfig | CompositionStatConfig>
+
+    /** Optional visual encoding configuration by channel (size, color, fill, composition, etc.). */
+    encoding?: Record<string, EncodingConfig>
 
     /** Legend configuration. */
     legend?: LegendConfig | false

package/build/types/core/MapInstance.d.ts

@@ -1,5 +1,8 @@
 import type { StatConfig } from './stat/StatConfig'
 import type { StatData } from './stat/StatData'
+import type { Layer } from './layer/Layer'
+import type { LayerConfig } from './layer/LayerConfig'
+import type { CompositionStatConfig } from '../layers/composition/CompositionStatConfig'
 import type { LegendConfig } from '../legend/LegendConfig'
 import type { TooltipConfig } from './TooltipConfig'
 import type { InsetConfig } from './InsetConfig'
@@ -7,6 +10,8 @@ import type { CoastalMarginSettings } from './decoration/CoastalMarginSettings'
 import type { GridCartogramSettings } from './GridCartogramSettings'
 import type { DorlingSettings } from './DorlingSettings'
 import type { ScalebarConfig } from './decoration/ScalebarConfig'
+import type { EncodingConfig } from './encoding/EncodingConfig'
+import type { LocationConfig } from './locations'
 
 /**
  * A eurostat-map instance. Created by eurostatmap.map() and extended
@@ -117,10 +122,50 @@ export interface MapInstance {
      * - `map.stat('v1', config)` → sets the stat config for key 'v1'
      * @example map.stat({ eurostatDatasetCode: 'demo_r_d3dens', filters: { TIME: '2024' } })
      */
-    stat(): StatConfig
-    stat(config: StatConfig): this
-    stat(key: string): StatConfig
-    stat(key: string, config: StatConfig): this
+    stat(): StatConfig | CompositionStatConfig | undefined
+    stat(config: StatConfig | CompositionStatConfig): this
+    stat(key: string): StatConfig | CompositionStatConfig | undefined
+    stat(key: string, config: StatConfig | CompositionStatConfig): this
+    /**
+     * Legacy compatibility overload for composition channels.
+     * Preferred: pass category fields directly inside config.
+     */
+    stat(
+        key: string,
+        config: StatConfig | CompositionStatConfig,
+        categoryParameter: string,
+        categoryCodes?: string[],
+        categoryLabels?: string[],
+        categoryColors?: string[],
+        totalCode?: string
+    ): this
+
+    /**
+     * Get or set visual encodings that map named stats to visual variables.
+     * @example map.encoding('size', { stat: 'population', scale: 'sqrt', range: [4, 30] })
+     */
+    encoding(): Record<string, EncodingConfig>
+    encoding(channel: string): EncodingConfig | undefined
+    encoding(channel: string, config: EncodingConfig): this
+    encoding(configs: Record<string, EncodingConfig>): this
+
+    /** Returns the stat name for an encoding channel, or fallback when unset. */
+    getEncodingStat(channel: string, fallback?: string): string | undefined
+
+    /** Returns stat names for an encoding channel (`stats` or single `stat`). */
+    getEncodingStats(channel: string, fallback?: string[]): string[] | undefined
+
+    /** Returns the concrete statData key for a channel/category combination. */
+    getEncodingStatKey(channel: string, categoryCode?: string, fallbackStat?: string): string | undefined
+
+    /** Returns the StatData source bound to a channel/category. */
+    getEncodingStatData(channel: string, categoryCode?: string, fallbackStat?: string): StatData | undefined
+
+    /** Returns a region value through encoding lookup. */
+    getEncodingValue(channel: string, regionId: string, categoryCode?: string, fallbackStat?: string): number | string | undefined
+
+    /** Returns unit text through encoding lookup. */
+    getEncodingUnitText(channel: string, categoryCode?: string, fallbackStat?: string): string
 
     /**
      * Get or set the StatData instance for a given key.
@@ -246,6 +291,22 @@ export interface MapInstance {
     svg(): any
     svg(s: any): this
 
+    /** Add or replace a custom point location marker. */
+    addLocation(config: LocationConfig): this
+
+    /** Remove a custom point location marker by id. */
+    removeLocation(id: string): this
+
+    /** Remove all custom point location markers. */
+    clearLocations(): this
+
+    /** Get or replace all custom point location markers. */
+    locations(): LocationConfig[]
+    locations(configs: LocationConfig[] | null | undefined): this
+
+    /** Redraw custom point location markers. */
+    updateLocations(): this
+
     /** Custom geometry filtering function. */
     filterGeometriesFunction(): ((geometry: any) => boolean) | undefined
     filterGeometriesFunction(fn: (geometry: any) => boolean): this
@@ -445,6 +506,21 @@ export interface MapInstance {
     /** Returns region centroids as an array of projected coordinate pairs. */
     regionCentroids(): Array<{ id: string; x: number; y: number }>
 
+    /** Ordered thematic layer stack (bottom → top). */
+    layers_: Layer[]
+    activeLayerIndex_: number
+
+    activeLayer(): Layer
+    layer(ref?: number | string): Layer | undefined
+    layers(): Layer[]
+    layers(configs: LayerConfig[]): this
+    addLayer(type: string, config?: LayerConfig): Layer
+    addLayer(config: LayerConfig): Layer
+    removeLayer(ref: number | string): this
+    activeLayerIndex(): number
+    activeLayerIndex(i: number): this
+    updateAllLayers(): this
+
     /** Allow additional map-type-specific properties and methods. */
     [key: string]: any
 }

package/build/types/core/encoding/EncodingConfig.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Configuration for mapping a named stat dataset to a visual channel.
+ */
+export interface EncodingConfig {
+    /** Name of a dataset registered with map.stat(name, config). */
+    stat?: string
+    /** Names of datasets for multi-stat encodings such as bivariate color. */
+    stats?: string[]
+    /** Whether the encoding is based on raw values or category codes. */
+    by?: 'value' | 'category'
+    /** Encoding type. */
+    type?: 'linear' | 'sqrt' | 'threshold' | 'quantile' | 'categorical' | 'bivariate' | 'trivariate'
+    /** Scale type. */
+    scale?: 'linear' | 'sqrt' | 'quantile' | 'threshold'
+    /** Numeric or color output range. */
+    range?: [number, number] | string[]
+    /** Explicit encoded values, for example category colors. */
+    values?: Record<string, string | number> | Array<string | number>
+    /** Labels keyed by category code or value. */
+    labels?: Record<string, string> | string[]
+    /** Category codes when using array-based values or labels. */
+    categoryCodes?: string[]
+    /** Number of classes for classified encodings. */
+    classes?: number
+    /** Threshold values for threshold encodings. */
+    thresholds?: number[]
+    /** Color scheme name or function. */
+    scheme?: string | Function
+    /** Optional unit override for this encoding. */
+    unitText?: string
+}

package/build/types/core/layer/Layer.d.ts

@@ -0,0 +1,31 @@
+import type { MapInstance } from '../MapInstance'
+import type { EncodingConfig } from '../encoding/EncodingConfig'
+import type { StatData } from '../stat/StatData'
+import type { LayerRole } from './LayerRole'
+
+export interface Layer {
+    map: MapInstance
+    isLayer: true
+    id: string
+    type: string
+    role: LayerRole
+
+    encodings_: Record<string, EncodingConfig>
+
+    encoding(): Record<string, EncodingConfig>
+    encoding(channel: string): EncodingConfig | undefined
+    encoding(channel: string, config: EncodingConfig): Layer
+    encoding(map: Record<string, EncodingConfig>): Layer
+
+    getEncodingStat(channel: string, fallback?: string): string | undefined
+    getEncodingStats(channel: string, fallback?: string[]): string[] | undefined
+    getEncodingStatKey(channel: string, categoryCode?: string, fallbackStat?: string): string
+    getEncodingStatData(channel: string, categoryCode?: string, fallbackStat?: string): StatData
+    getEncodingValue(channel: string, regionId: string, categoryCode?: string, fallbackStat?: string): number | string | undefined
+    getEncodingUnitText(channel: string, categoryCode?: string, fallbackStat?: string): string
+
+    updateClassification(): Layer
+    updateStyle(): Layer
+    getLegendConstructor(): (map: MapInstance, config?: any) => any
+    group(): any // d3 selection
+}

package/build/types/core/layer/LayerConfig.d.ts

@@ -0,0 +1,19 @@
+import type { MapType } from '../../layers/MapType'
+import type { EncodingConfig } from '../encoding/EncodingConfig'
+import type { LegendConfig } from '../../legend/LegendConfig'
+import type { LayerRole } from './LayerRole'
+
+export interface LayerConfig {
+    /** Stable id; auto-generated if omitted. */
+    id?: string
+    /** Layer type (same identifiers as map types). */
+    type: MapType
+    /** Explicit role; defaults from the type. */
+    role?: LayerRole
+    /** Keyed visual encodings: fill, size, color, stroke, … */
+    encoding?: Record<string, EncodingConfig>
+    /** Per-layer legend config. */
+    legend?: LegendConfig
+    /** Type-specific settings are also accepted. */
+    [key: string]: any
+}

package/build/types/core/layer/LayerRole.d.ts

@@ -0,0 +1 @@
+export type LayerRole = 'base' | 'overlay'

package/build/types/core/locations.d.ts

@@ -6,11 +6,37 @@ import type { MapInstance } from './MapInstance'
 export const LOCATION_SHAPES: {
     CIRCLE: 'circle'
     SQUARE: 'square'
+    PIN: 'pin'
     DIAMOND: 'diamond'
-    TRIANGLE: 'triangle'
     STAR: 'star'
     CROSS: 'cross'
-    PLUS: 'plus'
+}
+
+/**
+ * Available location marker shapes
+ */
+export type LocationShape = 'circle' | 'square' | 'pin' | 'diamond' | 'cross' | 'star'
+
+/**
+ * Text label style for a location marker
+ */
+export interface LocationLabelStyle {
+    /** CSS font size. @default '12px' */
+    fontSize?: string
+    /** CSS font family. @default 'inherit' */
+    fontFamily?: string
+    /** CSS font weight. @default 'normal' */
+    fontWeight?: string | number
+    /** Text fill color. @default '#222' */
+    fill?: string
+    /** Text opacity. @default 1 */
+    opacity?: number
+    /** Label halo color. @default '#fff' */
+    haloColor?: string
+    /** Label halo width in pixels. @default 3 */
+    haloWidth?: number
+    /** SVG text-anchor value. @default 'start' */
+    textAnchor?: 'start' | 'middle' | 'end'
 }
 
 /**
@@ -19,26 +45,28 @@ export const LOCATION_SHAPES: {
 export interface LocationConfig {
     /** Unique identifier for the location */
     id?: string
-    /** Longitude coordinate */
-    lon: number
-    /** Latitude coordinate */
-    lat: number
+    /** Geographic X coordinate (longitude / easting) */
+    x: number
+    /** Geographic Y coordinate (latitude / northing) */
+    y: number
     /** Label text to display */
     label?: string
     /** Marker shape. @default 'circle' */
-    shape?: 'circle' | 'square' | 'diamond' | 'triangle' | 'star' | 'cross' | 'plus'
-    /** Marker size in pixels. @default 8 */
-    size?: number
-    /** Fill color. @default '#e74c3c' */
-    color?: string
+    shape?: LocationShape
+    /** Marker radius in pixels. @default 6 */
+    radius?: number
+    /** Fill color. @default '#e84040' */
+    fill?: string
+    /** Fill opacity. @default 1 */
+    opacity?: number
     /** Stroke color. @default '#fff' */
     stroke?: string
-    /** Stroke width in pixels. @default 1 */
+    /** Stroke width in pixels. @default 1.5 */
     strokeWidth?: number
-    /** Custom CSS class */
-    class?: string
-    /** Custom data attached to the location */
-    data?: any
+    /** Label offset from projected point in pixels. @default [7, -6] */
+    labelOffset?: [number, number]
+    /** Label text style overrides */
+    labelStyle?: LocationLabelStyle
 }
 
 /**

package/build/types/core/stat/StatConfig.d.ts

@@ -1,8 +1,13 @@
 /**
  * Configuration for a statistical data source.
  * Pass this to map.stat() or as the config argument to statData().
+ *
+ * Preferred for multi-channel maps: register named datasets with
+ * `map.stat('datasetName', config)` and map them with `map.encoding(...)`.
  */
 export interface StatConfig {
+    /** Custom data keyed by region ID. Use instead of a remote data source. */
+    customData?: Record<string, number | string | { value: number | string; status?: string }>
     /** Eurostat dataset code. e.g. 'demo_r_d3dens' */
     eurostatDatasetCode?: string
     /**
@@ -20,6 +25,8 @@ export interface StatConfig {
     valueCol?: string
     /** Unit of measure label shown in tooltips. e.g. 'people/km²' */
     unitText?: string
+    /** Optional preprocessing hook called with (regionId, value) before transform. Return null/undefined/false to filter out the region. */
+    preprocess?: (regionId: string, value: any) => any
     /** Optional transform function applied to raw values after data loads. e.g. v => v * 1000 */
     transform?: (value: number) => number
     /** Dataset label/name from the Eurostat API response. */