eurostat-map 4.3.58 → 4.4.1

package/build/package.json

@@ -0,0 +1,87 @@
+{
+    "name": "eurostat-map",
+    "version": "4.3.58",
+    "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/DorlingSettings.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Strength settings for Dorling force simulation.
+ */
+export interface DorlingStrength {
+    /** X-axis attraction strength. */
+    x: number
+    /** Y-axis attraction strength. */
+    y: number
+}
+
+/**
+ * Settings for Dorling cartogram simulation behavior.
+ */
+export interface DorlingSettings {
+    /** Animate simulation ticks in real time. */
+    animate: boolean
+    /** Gravity strength toward original centroids. */
+    strength: DorlingStrength
+    /** Collision force iterations per tick. */
+    iterations: number
+    /** Extra collision padding between symbols. */
+    padding: number
+    /** Progress callback used by worker-based simulation. */
+    onProgress?: (progress: number, map: any) => void
+    /** Run non-animated simulation in a Web Worker. */
+    worker: boolean
+    /** URL of the D3 bundle used by Dorling worker mode. */
+    workerD3URL?: string
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Margins used to place and center grid cartograms.
+ */
+export interface GridCartogramMargins {
+    /** Top margin in pixels. */
+    top: number
+    /** Right margin in pixels. */
+    right: number
+    /** Bottom margin in pixels. */
+    bottom: number
+    /** Left margin in pixels. */
+    left: number
+}
+
+/**
+ * Settings for grid cartogram layout and geometry.
+ */
+export interface GridCartogramSettings {
+    /** Grid cell shape. */
+    shape: 'square' | 'hexagon'
+    /** Margins around the grid drawing area. */
+    margins: GridCartogramMargins
+    /** Extra spacing between grid cells in pixels. */
+    cellPadding: number
+    /**
+     * Custom grid layout CSV string.
+     * If undefined, the built-in layout for the selected shape is used.
+     */
+    positions?: string
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Configuration for map insets (smaller additional maps)
+ */
+export interface InsetConfig {
+    /** Geographic code (e.g., 'MT', 'PT20', 'CARIB'). */
+    geo?: string
+    /** Title. */
+    title?: string
+    /** Scale. */
+    scale?: string | number
+    /** Width. */
+    width?: number
+    /** Height. */
+    height?: number
+    /** X. */
+    x?: number
+    /** Y. */
+    y?: number
+    /** Proj. */
+    proj?: string
+
+    [key: string]: any
+}

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

@@ -0,0 +1,95 @@
+import type { StatConfig } from './stat/StatConfig'
+import type { LegendConfig } from '../legend/LegendConfig'
+import type { TooltipConfig } from './TooltipConfig'
+import type { InsetConfig } from './InsetConfig'
+import type { MapInstance as EurostatMap } from './MapInstance'
+import type { CoastalMarginSettings } from './decoration/CoastalMarginSettings'
+import type { GridCartogramSettings } from './GridCartogramSettings'
+import type { DorlingSettings } from './DorlingSettings'
+
+/**
+ * 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.
+ */
+export interface MapConfig {
+    /** Container settings. */
+    svgId?: string
+    /** ID of the container element used to host the map. */
+    containerId?: string
+
+    /** Geographic settings. */
+    /**
+     * NUTS2json geometries projection: '3035', '3857', '4326'.
+     * For custom projections, use 4326 and then set projectionFunction().
+     */
+    proj?: string
+    /** Function to set a custom projection. See d3-geo projections for examples. */
+    projectionFunction?: () => any
+    /** Scale of the map, for NUTSjson geometries. */
+    scale?: '60M' | '20M' | '10M' | '03M' | '01M'
+    /** NUTS level (0, 1, 2, 3). */
+    nutsLevel?: number
+    /** NUTS boundary year. */
+    nutsYear?: number | string
+    /** Geographic center as [longitude, latitude]. */
+    geoCenter?: [number, number]
+
+    /** Geometry settings. */
+    /**
+     * NUTS2JSON geographic focus (e.g., 'EUR', 'WORLD', 'IC', 'GF').
+     * See https://github.com/eurostat/Nuts2json#overseas-territories---map-insets
+     */
+    geo?: string
+
+    /** Map dimensions. */
+    width?: number
+    /** Map height in pixels. */
+    height?: number
+
+    /** Map texts. */
+    /** Map title. */
+    title?: string
+    /** Map subtitle. */
+    subtitle?: string
+    /** Footnote text shown below the map. */
+    footnote?: string
+    /** Data source text. */
+    source?: string
+
+    /** Statistical data configuration. */
+    stat?: StatConfig
+
+    /** Legend configuration. */
+    legend?: LegendConfig
+
+    /** Tooltip configuration. */
+    tooltip?: TooltipConfig
+
+    /** Insets (small additional maps). */
+    insets?: InsetConfig[]
+
+    /** Zoom and pan settings. */
+    zoomExtent?: [number, number]
+
+    /** Grid cartogram layout settings. */
+    gridCartogramSettings?: Partial<GridCartogramSettings>
+
+    /** Dorling simulation settings. */
+    dorlingSettings?: Partial<DorlingSettings>
+
+    /** Show or hide the coastal margin effect. */
+    drawCoastalMargin?: boolean
+    /** Coastal margin settings to override defaults. */
+    coastalMarginSettings?: Partial<CoastalMarginSettings>
+
+    /** Graticule. */
+    drawGraticule?: boolean
+
+    /** Labels. */
+    labelling?: boolean
+
+    /** Fires once the map is built. */
+    onBuild?: (map: EurostatMap) => void
+
+    /** Allow additional properties for extensibility. */
+    [key: string]: any
+}

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

@@ -0,0 +1,349 @@
+import type { StatConfig } from './stat/StatConfig'
+import type { StatData } from './stat/StatData'
+import type { LegendConfig } from '../legend/LegendConfig'
+import type { TooltipConfig } from './TooltipConfig'
+import type { InsetConfig } from './InsetConfig'
+import type { CoastalMarginSettings } from './decoration/CoastalMarginSettings'
+import type { GridCartogramSettings } from './GridCartogramSettings'
+import type { DorlingSettings } from './DorlingSettings'
+
+/**
+ * A eurostat-map instance. Created by eurostatmap.map() and extended
+ * by each concrete map type. All getter/setter methods follow the same
+ * pattern: call with no argument to get, call with a value to set and
+ * return the instance for chaining.
+ */
+export interface MapInstance {
+    /** Container. */
+
+    /** ID of the target SVG element. @default 'map' */
+    svgId(): string
+    svgId(id: string): this
+
+    /** ID of the wrapper container element. */
+    containerId(): string
+    containerId(id: string): this
+
+    /** Dimensions. */
+
+    /** Map width in pixels. @default min(795, window.innerWidth) */
+    width(): number
+    width(w: number): this
+
+    /** Map height in pixels. 0 = auto (85% of width). */
+    height(): number
+    height(h: number): this
+
+    /** Geography. */
+
+    /**
+     * NUTS2JSON geographic focus area.
+     * @example 'EUR' | 'WORLD' | 'PT' | 'MT' | 'IC'
+     */
+    geo(): string
+    geo(g: string): this
+
+    /**
+     * EPSG projection code for NUTS2JSON geometries.
+     * Use '4326' when setting a custom projectionFunction.
+     * @default '3035'
+     */
+    proj(): string
+    proj(p: string): this
+
+    /**
+     * NUTS2JSON geometry resolution.
+     * @default '20M'
+     */
+    scale(): string
+    scale(s: '60M' | '20M' | '10M' | '03M' | '01M'): this
+
+    /** NUTS level to display. @default 3 */
+    nutsLevel(): number | 'mixed'
+    nutsLevel(level: number | 'mixed'): this
+
+    /** NUTS boundaries year. @default 2024 */
+    nutsYear(): number
+    nutsYear(year: number): this
+
+    /**
+     * Initial map viewport. x/y in projected coordinates, z is pixel size
+     * (map units per screen pixel — smaller = more zoomed in).
+     * @example map.position({ x: 4800000, y: 3400000, z: 6000 })
+     */
+    position(v: { x?: number; y?: number; z?: number }): this
+    position(): { x: number; y: number; z: number }
+
+    /**
+     * Custom D3 projection function. When set, also call proj('4326').
+     * @example map.projectionFunction(d3.geoAzimuthalEquidistant().rotate([-10, -52]))
+     */
+    projectionFunction(): any
+    projectionFunction(fn: any): this
+
+    /** Text and labels. */
+
+    /** Map title. */
+    title(): string
+    title(t: string): this
+
+    /** Map subtitle. */
+    subtitle(): string
+    subtitle(t: string): this
+
+    /**
+     * Footnote text shown at the bottom of the map.
+     * Defaults to the standard EuroGeographics copyright notice.
+     */
+    footnote(): string | false
+    footnote(text: string | false): this
+
+    /** Tooltip text shown when hovering over the footnote. */
+    footnoteTooltipText(): string | false
+    footnoteTooltipText(text: string | false): this
+
+    /** Wrap footnote text at this many characters. */
+    footnoteWrap(): number | false
+    footnoteWrap(chars: number | false): this
+
+    /** Statistical data. */
+
+    /**
+     * Get or set statistical data configuration.
+     * - `map.stat()` → returns the default stat config
+     * - `map.stat(config)` → sets the default stat config
+     * - `map.stat('v1')` → returns the stat config for key 'v1'
+     * - `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
+
+    /**
+     * Get or set the StatData instance for a given key.
+     * Use setData() on the returned instance to supply custom data.
+     * @example map.statData().setData({ DE: 120, FR: 95 })
+     */
+    statData(): StatData
+    statData(key: string): StatData
+    statData(key: string, data: StatData): this
+
+    /**
+     * Returns the time dimension value from the loaded Eurostat dataset.
+     * Useful for displaying the data period in the map title.
+     * @example map.onBuild(() => map.title('Population ' + map.getTime()))
+     */
+    getTime(): string | undefined
+
+    /** Text shown for regions with no data. @default 'No data available' */
+    noDataText(): string
+    noDataText(text: string): this
+
+    /** BCP 47 language tag for Eurostat API labels. @default 'en' */
+    language(): string
+    language(lang: string): this
+
+    /** Legend. */
+
+    /**
+     * Get or set legend configuration. Pass false to remove the legend.
+     * @example map.legend({ x: 10, y: 90, title: 'Density, people/km²' })
+     */
+    legend(): LegendConfig
+    legend(config: LegendConfig | false): this
+
+    /** Force-update the legend after data or style changes. */
+    updateLegend(): this
+
+    /** Tooltip. */
+
+    /** Get or set tooltip configuration. */
+    tooltip(): TooltipConfig
+    tooltip(config: TooltipConfig): this
+
+    /** Zoom and pan. */
+
+    /**
+     * D3 zoom scale extent [min, max].
+     * @example map.zoomExtent([1, 10])
+     */
+    zoomExtent(): [number, number]
+    zoomExtent(extent: [number, number]): this
+
+    /** Show zoom +/- buttons. @default true */
+    zoomButtons(): boolean
+    zoomButtons(show: boolean): this
+
+    /** Grid cartogram settings (shape, margins, cell padding, layout positions). */
+    gridCartogramSettings(): GridCartogramSettings
+    gridCartogramSettings(settings: Partial<GridCartogramSettings>): this
+
+    /** Insets. */
+
+    /**
+     * Inset map configurations. Pass 'default' for the standard
+     * eurostat overseas territory insets, false to disable.
+     * @example map.insets('default')
+     * @example map.insets([{ geo: 'MT' }, { geo: 'LI' }])
+     */
+    insets(): InsetConfig[] | 'default' | false
+    insets(config: InsetConfig[] | 'default' | false): this
+
+    /** Decoration. */
+
+    /** Show/hide the graticule (coordinate grid lines). */
+    drawGraticule(): boolean
+    drawGraticule(show: boolean): this
+
+    /** Show/hide the coastal margin shadow effect. */
+    drawCoastalMargin(): boolean
+    drawCoastalMargin(show: boolean): this
+
+    /** Coastal margin appearance settings. */
+    coastalMarginSettings(): CoastalMarginSettings
+    coastalMarginSettings(settings: Partial<CoastalMarginSettings>): this
+
+    /** Show/hide placename labels loaded from the placenames layer. */
+    placenames(): boolean
+    placenames(show: boolean): this
+
+    /** Geographic label configuration. See docs/reference.md#labelling */
+    labels(): object | undefined
+    labels(config: object): this
+
+    /** Annotation configuration for d3-svg-annotation. */
+    annotations(): any
+    annotations(config: any): this
+
+    /** Stamp/watermark annotation. @example { x: 10, y: 10, text: 'DRAFT', size: 40 } */
+    stamp(): object | undefined
+    stamp(config: { x: number; y: number; text: string; size?: number }): this
+
+    /** Scalebar visibility. */
+    showScalebar(): boolean
+    showScalebar(show: boolean): this
+
+    /** Scalebar position [x, y] in pixels. */
+    scalebarPosition(): [number, number]
+    scalebarPosition(pos: [number, number]): this
+
+    /** Show the Eurostat logo. */
+    showEstatLogo(): boolean
+    showEstatLogo(show: boolean): this
+
+    /** Show the Eurostat ribbon banner. */
+    showEstatRibbon(): boolean
+    showEstatRibbon(show: boolean): this
+
+    /** Dorling. */
+
+    /** Enable Dorling cartogram layout for proportional symbol maps. */
+    dorling(): boolean
+    dorling(enable: boolean): this
+
+    /** Dorling simulation settings. */
+    dorlingSettings(): DorlingSettings
+    dorlingSettings(settings: Partial<DorlingSettings>): this
+
+    /** Events. */
+
+    /** Called when the user finishes a zoom gesture. */
+    onZoomEnd(): ((event: any) => void) | undefined
+    onZoomEnd(fn: (event: any) => void): this
+
+    /** Called continuously while the user is zooming. */
+    onZoom(): ((event: any) => void) | undefined
+    onZoom(fn: (event: any) => void): this
+
+    /** Called when the pointer enters a NUTS region. */
+    onRegionMouseOver(): ((event: MouseEvent, regionId: string, props: any) => void) | undefined
+    onRegionMouseOver(fn: (event: MouseEvent, regionId: string, props: any) => void): this
+
+    /** Called when the pointer moves over a NUTS region. */
+    onRegionMouseMove(): ((event: MouseEvent, regionId: string, props: any) => void) | undefined
+    onRegionMouseMove(fn: (event: MouseEvent, regionId: string, props: any) => void): this
+
+    /** Called when the pointer leaves a NUTS region. */
+    onRegionMouseOut(): ((event: MouseEvent, regionId: string, props: any) => void) | undefined
+    onRegionMouseOut(fn: (event: MouseEvent, regionId: string, props: any) => void): this
+
+    /** Called when a NUTS region is clicked. */
+    onRegionClick(): ((event: MouseEvent, regionId: string, props: any) => void) | undefined
+    onRegionClick(fn: (event: MouseEvent, regionId: string, props: any) => void): this
+
+    /**
+     * Callback fired once after the map has fully built (geo + stat data loaded).
+     * Receives the map instance as its only argument.
+     * @example map.onBuild(m => console.log('Map ready', m))
+     */
+    onBuild(): ((map: MapInstance) => void) | undefined
+    onBuild(callback: (map: MapInstance) => void): this
+
+    /** Build and update. */
+
+    /**
+     * Builds the map from scratch. Call once after initial configuration.
+     * @example
+     * eurostatmap.map('choropleth')
+     *   .stat({ eurostatDatasetCode: 'demo_r_d3dens' })
+     *   .build()
+     */
+    build(): this
+
+    /** Re-fetches geo data and rebuilds map geometry. */
+    updateGeoData(): this
+
+    /** Re-fetches all stat datasets and refreshes the map. */
+    updateStatData(): this
+
+    /** Re-applies classification and styling from currently loaded data. */
+    updateStatValues(): this
+
+    /** Updates data classification (class breaks, thresholds). */
+    updateClassification(): this
+
+    /** Re-applies visual styling (colors, symbol sizes). */
+    updateStyle(): this
+
+    /** Recalculates header/footer layout and resizes the SVG. */
+    recalculateLayout(): void
+
+    /** Export. */
+
+    /**
+     * Exports the map as an SVG file and triggers a browser download.
+     * Computed CSS styles are inlined before export.
+     */
+    exportMapToSVG(): this
+
+    /**
+     * Exports the map as a PNG file and triggers a browser download.
+     * @param width - Output width in pixels. Defaults to SVG width.
+     * @param height - Output height in pixels. Defaults to SVG height.
+     */
+    exportMapToPNG(width?: number, height?: number): Promise<this>
+
+    /** Misc. */
+
+    /**
+     * Sets map attributes from URL parameters.
+     * Supported params: w, h, x, y, z, s, lvl, time, proj, geo, ny, language, numberOfClasses
+     */
+    setFromURL(): this
+
+    /** D3 transition duration in milliseconds for map updates. @default 500 */
+    transitionDuration(): number
+    transitionDuration(ms: number): this
+
+    /** SVG filter/pattern definition function for fill patterns. */
+    filtersDefinitionFunction(): ((svg: any, numberOfClasses: number) => void) | undefined
+    filtersDefinitionFunction(fn: (svg: any, numberOfClasses: number) => void): this
+
+    /** Returns region centroids as an array of projected coordinate pairs. */
+    regionCentroids(): Array<{ id: string; x: number; y: number }>
+
+    /** Allow additional map-type-specific properties and methods. */
+    [key: string]: any
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Configuration for the minimap globe feature.
+ */
+export interface MinimapConfig {
+    /** Size of the minimap in pixels. @default 150 */
+    size?: number
+    /** Debounce delay in milliseconds for updating the minimap during zoom/pan. @default 3 */
+    debounce?: number
+    /** Position [x, y] in pixels. If not specified, positioned in top-left corner */
+    position?: [number, number]
+}

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

@@ -0,0 +1,16 @@
+import type { MapInstance as EurostatMap } from './MapInstance'
+
+/**
+ * Configuration for tooltips
+ */
+export interface TooltipConfig {
+    textFunction?: (region: any, map: EurostatMap) => string
+    /** Omit regions. */
+    omitRegions?: string[]
+    /** Max width. */
+    maxWidth?: number
+    /** Font size. */
+    fontSize?: number
+
+    [key: string]: any
+}

package/build/types/core/decoration/CoastalMarginSettings.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Visual settings for the coastal margin effect.
+ */
+export interface CoastalMarginSettings {
+    /** Gaussian blur standard deviation. */
+    standardDeviation: number
+    /** Filter x bound (SVG filter coordinate space). */
+    x: string
+    /** Filter y bound (SVG filter coordinate space). */
+    y: string
+    /** Filter width (SVG filter coordinate space). */
+    width: string
+    /** Filter height (SVG filter coordinate space). */
+    height: string
+    /** Coastal stroke width. */
+    strokeWidth: number
+    /** Coastal stroke color. */
+    color: string
+    /** Coastal stroke opacity. */
+    opacity: number
+}