eurostat-map 4.3.58 → 4.4.0

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/InsetConfig.d.ts

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

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

@@ -0,0 +1,85 @@
+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'
+
+/**
+ * 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
+    containerId?: string
+
+    // Geographic settings
+    proj?: string // NUTS2json geometries projection: '3035', '3857', '4326'. For custom projections use 4326, then set the desired projection with projectionFunction()
+    projectionFunction?: () => any // Function to set a custom projection. See d3-geo projections for examples.
+    scale?: '60M' | '20M' | '10M' | '03M' | '01M' // Scale of the map, for NUTSjson geometries
+    nutsLevel?: number // 0, 1, 2, 3
+    nutsYear?: number | string
+    geoCenter?: [number, number]
+    pixSize?: number
+
+    // Geometry settings
+    geo?: string // NUTS2JSON Geographic focus (e.g., 'EUR', 'WORLD', 'IC', 'GF') see https://github.com/eurostat/Nuts2json#overseas-territories---map-insets
+
+    // Map dimensions
+    width?: number
+    height?: number
+
+    // map texts
+    title?: string
+    subtitle?: string
+    bottomText?: string
+    botTxtFontSize?: number
+    botTxtPadding?: number
+    botTxtTooltipMessage?: string
+    footnote?: string
+    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]
+
+    // UI Controls
+    showBtns?: boolean // Show zoom buttons
+
+    // Coastal margin
+    coastal?: boolean
+    coastalMarginWidth?: number
+    coastalMarginColor?: string
+
+    // Graticule
+    drawGraticule?: boolean
+    graticuleStyle?: any
+
+    // Borders
+    borderWidth?: number
+    borderColor?: string
+
+    // Labels
+    labelling?: boolean
+    labelSizeThreshold?: number
+    labelOpacity?: number
+
+    // Logo
+    logoURL?: string
+
+    // Callbacks
+    onBuild?: (map: EurostatMap) => void
+
+    // Allow additional properties for extensibility
+    [key: string]: any
+}

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

@@ -0,0 +1,354 @@
+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'
+
+/**
+ * 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 & 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 & 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
+
+    // ==================== 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(): object
+    coastalMarginSettings(settings: object): 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
+
+    /** Animate the Dorling simulation. @default true */
+    animateDorling(): boolean
+    animateDorling(animate: boolean): this
+
+    /** Dorling simulation gravity strength. @default { x: 1, y: 1 } */
+    dorlingStrength(): { x: number; y: number }
+    dorlingStrength(strength: { x: number; y: number }): this
+
+    /** Number of Dorling collision detection iterations. @default 1 */
+    dorlingIterations(): number
+    dorlingIterations(n: number): this
+
+    /** Minimum distance between Dorling circles. Negative allows overlap. @default 0 */
+    dorlingPadding(): number
+    dorlingPadding(padding: number): 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 & 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,13 @@
+import type { MapInstance as EurostatMap } from './MapInstance'
+
+/**
+ * Configuration for tooltips
+ */
+export interface TooltipConfig {
+    textFunction?: (region: any, map: EurostatMap) => string
+    omitRegions?: string[]
+    maxWidth?: number
+    fontSize?: number
+
+    [key: string]: any
+}

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

@@ -0,0 +1,48 @@
+export interface ScalebarConfig {
+    /**
+     * Whether to show the scalebar.
+     * Replaces showScalebar(true/false).
+     */
+    show?: boolean
+
+    /**
+     * Scalebar anchor position in SVG pixels: [x, y]
+     */
+    position?: [number, number]
+
+    /**
+     * Label suffix, usually " km", but can also be " m", " mi", etc.
+     * Note: current implementation still computes values in metres internally.
+     */
+    units?: string
+
+    /**
+     * Label offset from the tick position: [x, y]
+     */
+    textOffset?: [number, number]
+
+    /**
+     * Maximum width of the scalebar in pixels.
+     */
+    maxWidth?: number
+
+    /**
+     * Total height reserved for the scalebar group in pixels.
+     */
+    height?: number
+
+    /**
+     * Stroke width used by scalebar lines.
+     */
+    strokeWidth?: number
+
+    /**
+     * Height of the horizontal middle segment line.
+     */
+    segmentHeight?: number
+
+    /**
+     * Height of the vertical ticks.
+     */
+    tickHeight?: number
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Configuration for a stamp/watermark annotation rendered on the map.
+ * @example
+ * map.stamp({ x: 230, y: 100, text: 'DRAFT', shape: 'circle', size: 60 })
+ */
+export interface StampConfig {
+    /** Text content of the stamp. Use ¶ for forced line breaks, ~ for non-breaking spaces. */
+    text: string
+
+    /** Horizontal centre position in SVG pixels. @default 230 */
+    x?: number
+
+    /** Vertical centre position in SVG pixels. @default 100 */
+    y?: number
+
+    /**
+     * Shape of the stamp border.
+     * @default 'circle'
+     */
+    shape?: 'circle' | 'square' | 'rectangle' | 'eu-stars'
+
+    /**
+     * Size of the stamp in SVG pixels.
+     * For circle/square: diameter. For rectangle: controls text fit height.
+     * Ignored when fontSize is set.
+     * @default 60
+     */
+    size?: number
+
+    /**
+     * Fix the rendered font size in pixels and let the shape grow to contain
+     * the text, instead of scaling text to fit a fixed shape size.
+     */
+    fontSize?: number
+
+    /** Text colour. @default '#585858' */
+    textColor?: string
+
+    /** Border/shape colour. @default '#9e9e9e' */
+    stampColor?: string
+
+    /** Border stroke width in pixels. @default 1 */
+    strokeWidth?: number
+
+    /** Line height of the unscaled text element in pixels. @default 15 */
+    lineHeight?: number
+
+    /**
+     * Text horizontal alignment.
+     * 'middle': stamp is centred on x (default).
+     * 'start': stamp's left edge is at x, growing rightward.
+     * @default 'middle'
+     */
+    textAnchor?: 'middle' | 'start'
+
+    /**
+     * Padding between the text and the shape border in pixels.
+     * @default 0 for circle/square/eu-stars, 1 for rectangle
+     */
+    padding?: number
+
+    /** Corner radius for square and rectangle shapes (SVG rx attribute). @default 0 */
+    rx?: number
+
+    /**
+     * Size multiplier for individual stars in the 'eu-stars' shape.
+     * Does not affect the ring radius.
+     * @default 1
+     */
+    starSize?: number
+}