eurostat-map 4.3.58 → 4.4.0

package/build/types/core/geo/centroids.d.ts

@@ -0,0 +1,33 @@
+import type { MapInstance } from '../MapInstance'
+
+/**
+ * Adds centroid features to the map for proportional symbol rendering.
+ * Centroids are either loaded from pre-computed data or calculated from geometries.
+ * @param map - The map instance
+ */
+export function addCentroidsToMap(map: MapInstance): void
+
+/**
+ * Returns the D3 selection for the proportional symbols (centroids) container.
+ * Uses a map-specific ID to avoid collisions with insets.
+ * @param map - The map instance
+ * @returns D3 selection of the centroids group
+ */
+export function getCentroidsGroup(map: MapInstance): any
+
+/**
+ * Refreshes the centroids display by filtering to only show regions with statistical data.
+ * Removes centroids without data and adds centroids for regions that just received data.
+ * @param map - The map instance
+ * @returns The map instance for chaining
+ */
+export function refreshCentroids(map: MapInstance): MapInstance
+
+/**
+ * Checks if a region has statistical data attached.
+ * Used to filter which centroids should be displayed.
+ * @param id - The region ID
+ * @param map - The map instance
+ * @returns True if the region has statistical data
+ */
+export function centroidHasStatData(id: string, map: MapInstance): boolean

package/build/types/core/geo/geometries.d.ts

@@ -0,0 +1,56 @@
+import type { MapInstance } from '../MapInstance'
+
+/**
+ * Geometries class for managing geographic data loading and rendering.
+ * Handles NUTS regions, country boundaries, centroids, and custom geometries.
+ */
+export interface GeometriesClass {
+    /** Default geographic data (NUTS regions, countries, etc.) */
+    defaultGeoData: any
+    /** All NUTS level data (for mixed level maps) */
+    allNUTSGeoData: any
+    /** Centroid point data */
+    centroidsData: any
+    /** Processed GeoJSON features organized by type */
+    geoJSONs: {
+        nutsrg?: any[]
+        nutsbn?: any[]
+        cntrg?: any[]
+        cntbn?: any[]
+        worldrg?: any[]
+        graticule?: any[]
+        mixed?: any
+    }
+    /** User-provided custom geometries */
+    userGeometries: boolean
+    /** Centroid features with projected coordinates */
+    centroidsFeatures: any[]
+    /** Master copy of all centroid features before filtering */
+    _allCentroidsFeatures: any[]
+
+    /** Fetches default geographic data from NUTS2JSON */
+    getDefaultGeoData(geo: string, filterFunction: any, nutsLevel: number | string): Promise<void>
+    /** Sets user-defined custom geometries */
+    setUserGeometries(geometries: any[]): void
+    /** Adds default NUTS geometries to the map */
+    addDefaultGeometriesToMap(
+        zoomGroup: any,
+        drawGraticule: boolean,
+        pathFunction: any,
+        nutsLevel: number | string,
+        nutsYear: number,
+        geo: string,
+        proj: string,
+        scale: string
+    ): void
+    /** Adds user-defined geometries to the map */
+    addUserGeometriesToMap(geometries: any[], zoomGroup: any, pathFunction: any): void
+}
+
+/**
+ * Factory function that creates a Geometries instance for a map.
+ * @param map - The map instance
+ * @param withCenterPoints - Whether to load centroid data
+ * @returns Geometries instance
+ */
+export function Geometries(map: MapInstance, withCenterPoints: boolean): GeometriesClass

package/build/types/core/geo/kosovo.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Kosovo boundary features for different NUTS years.
+ * Used to add Kosovo boundaries to maps since they are not included in standard NUTS datasets.
+ */
+export const kosovoBnFeatures: {
+    [year: number]: {
+        type: 'FeatureCollection'
+        features: any[]
+    }
+}

package/build/types/core/geo/proj4.d.ts

@@ -0,0 +1,26 @@
+import type { MapInstance } from '../MapInstance'
+
+/**
+ * Initializes proj4 with common projection definitions.
+ * Loads EPSG definitions for dynamic minimap projections and placename labels.
+ */
+export function initProj4(): void
+
+/**
+ * Projects geographic coordinates (lon, lat) to map coordinates (x, y)
+ * based on the map's projection.
+ * @param map - The map instance
+ * @param lon - Longitude in degrees
+ * @param lat - Latitude in degrees
+ * @returns Projected coordinates [x, y] or null if projection fails
+ */
+export function projectToMap(map: MapInstance, lon: number, lat: number): [number, number] | null
+
+/**
+ * Inverse projects map coordinates (x, y) to geographic coordinates (lon, lat).
+ * @param map - The map instance
+ * @param x - X coordinate in the map's projection
+ * @param y - Y coordinate in the map's projection
+ * @returns Geographic coordinates [lon, lat] or null if projection fails
+ */
+export function projectFromMap(map: MapInstance, x: number, y: number): [number, number] | null

package/build/types/core/geo/projection.d.ts

@@ -0,0 +1,29 @@
+import type { MapInstance } from '../MapInstance'
+
+/**
+ * Defines the D3 projection for the map based on geographic context.
+ * Sets up Robinson projection for world maps or identity projection for regional maps.
+ * @param map - The map instance
+ */
+export function defineProjection(map: MapInstance): void
+
+/**
+ * Defines the D3 path function using the map's projection.
+ * Used to render geographic features as SVG paths.
+ * @param map - The map instance
+ */
+export function definePathFunction(map: MapInstance): void
+
+/**
+ * Sets the default position (center coordinates and zoom level) for the map
+ * based on the geographic area and projection.
+ * @param map - The map instance
+ */
+export function defineDefaultPosition(map: MapInstance): void
+
+/**
+ * Gets the default zoom level (z value) for a given map configuration.
+ * @param map - The map instance
+ * @returns The default z value (pixel size in map units)
+ */
+export function getDefaultZ(map: MapInstance): number

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

@@ -0,0 +1,16 @@
+import type { MapInstance } from './MapInstance'
+
+/**
+ * Builds inset maps based on the configuration in the map instance.
+ * Creates sub-maps for specific geographic regions (e.g., islands, overseas territories).
+ * @param map - The map instance
+ * @param withCenterPoints - Whether to include region centroids
+ * @param mapType - The type of map (e.g., 'choropleth', 'proportional-symbol')
+ */
+export function buildInsets(map: MapInstance, withCenterPoints: boolean, mapType: string): void
+
+/**
+ * Removes all existing insets from a map instance.
+ * @param map - The map instance
+ */
+export function removeInsets(map: MapInstance): void

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

@@ -0,0 +1,23 @@
+import type { MapInstance } from './MapInstance'
+
+/**
+ * Creates or retrieves the main SVG element for a map.
+ * @param map - The map instance
+ * @returns The D3 selection of the SVG element
+ */
+export function createMapSVG(map: MapInstance): any
+
+/**
+ * Wraps the map SVG in a container div to enable HTML overlays
+ * (spinner, tooltip) to sit above the SVG.
+ * @param svg - The D3 selection of the SVG element
+ * @returns The wrapper element
+ */
+export function wrapMapSvg(svg: any): HTMLElement
+
+/**
+ * Recalculates and applies the layout for header, drawing area, and footer.
+ * Adjusts clip paths and positioning based on content.
+ * @param map - The map instance
+ */
+export function recalculateLayout(map: MapInstance): void

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

@@ -0,0 +1,55 @@
+import type { MapInstance } from './MapInstance'
+
+/**
+ * Available location marker shapes
+ */
+export const LOCATION_SHAPES: {
+    CIRCLE: 'circle'
+    SQUARE: 'square'
+    DIAMOND: 'diamond'
+    TRIANGLE: 'triangle'
+    STAR: 'star'
+    CROSS: 'cross'
+    PLUS: 'plus'
+}
+
+/**
+ * Configuration for a single location marker
+ */
+export interface LocationConfig {
+    /** Unique identifier for the location */
+    id?: string
+    /** Longitude coordinate */
+    lon: number
+    /** Latitude coordinate */
+    lat: 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
+    /** Stroke color. @default '#fff' */
+    stroke?: string
+    /** Stroke width in pixels. @default 1 */
+    strokeWidth?: number
+    /** Custom CSS class */
+    class?: string
+    /** Custom data attached to the location */
+    data?: any
+}
+
+/**
+ * Updates and redraws location markers on the map.
+ * @param map - The map instance
+ */
+export function updateLocations(map: MapInstance): void
+
+/**
+ * Attaches the locations API methods to a map instance.
+ * Adds methods like addLocation(), removeLocation(), etc.
+ * @param map - The map instance
+ */
+export function attachLocationsApi(map: MapInstance): void

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

@@ -0,0 +1,20 @@
+import type { MapInstance } from './MapInstance'
+
+/**
+ * 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]
+}
+
+/**
+ * Appends a minimap (globe visualization) to the map.
+ * Shows the current map viewport on a world globe.
+ * @param map - The map instance
+ */
+export function appendMinimap(map: MapInstance): void

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

@@ -0,0 +1,30 @@
+/**
+ * Creates a square root scale for proportional symbol sizing.
+ * Good for area-based symbols like circles where visual size should be
+ * proportional to the square root of the data value.
+ * @param rawData - Array of numeric values to scale
+ * @param maxSize - Maximum output size in pixels. @default 20
+ * @param minSize - Minimum output size in pixels. @default 0
+ * @returns D3 scale function
+ */
+export function createSqrtScale(rawData?: number[], maxSize?: number, minSize?: number): any
+
+/**
+ * Creates a radial scale for circular symbol sizing.
+ * Maps data values directly to radii.
+ * @param rawData - Array of numeric values to scale
+ * @param maxSize - Maximum output radius in pixels. @default 20
+ * @param minSize - Minimum output radius in pixels. @default 0
+ * @returns D3 scale function
+ */
+export function createRadialScale(rawData?: number[], maxSize?: number, minSize?: number): any
+
+/**
+ * Creates a linear scale for proportional symbol sizing.
+ * Maps data values linearly to visual sizes.
+ * @param rawData - Array of numeric values to scale
+ * @param maxSize - Maximum output size in pixels. @default 20
+ * @param minSize - Minimum output size in pixels. @default 0
+ * @returns D3 scale function
+ */
+export function createLinearScale(rawData?: number[], maxSize?: number, minSize?: number): any

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

@@ -0,0 +1,27 @@
+/**
+ * Configuration for a statistical data source.
+ * Pass this to map.stat() or as the config argument to statData().
+ */
+export interface StatConfig {
+    /** Eurostat dataset code. e.g. 'demo_r_d3dens' */
+    eurostatDatasetCode?: string
+    /**
+     * Filters for the Eurostat API query.
+     * @example { TIME: '2024', UNIT: 'EUR_HAB' }
+     */
+    filters?: Record<string, string>
+    /** Number of decimal places for Eurostat API data. @default 2 */
+    precision?: number
+    /** URL of a CSV file to use as the data source. */
+    csvURL?: string
+    /** CSV column containing NUTS region IDs. @default 'geo' */
+    geoCol?: string
+    /** CSV column containing statistical values. @default 'value' */
+    valueCol?: string
+    /** Unit of measure label shown in tooltips. e.g. 'people/km²' */
+    unitText?: string
+    /** 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. */
+    label?: string
+}

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

@@ -0,0 +1,107 @@
+import type { StatConfig } from './StatConfig'
+
+/**
+ * A statistical dataset indexed by NUTS region ID.
+ * Returned by map.statData() and created internally by statData().
+ */
+export interface StatData {
+    /**
+     * Returns the stat entry {value, status} for a given NUTS ID.
+     * If called with no argument, returns the entire data index.
+     * @example map.statData().get('DE')  // → { value: 120, status: 'e' }
+     */
+    get(nutsId?: string): { value: any; status?: string } | Record<string, { value: any; status?: string }> | undefined
+
+    /**
+     * Returns the raw value for a given NUTS ID.
+     * @example map.statData().getValue('DE')  // → 120
+     */
+    getValue(nutsId: string): any
+
+    /**
+     * Sets a stat value for a given NUTS ID.
+     * @param nutsId - The NUTS region ID.
+     * @param stat - Either a value directly or an object { value, status }.
+     * @example map.statData().set('DE', 120)
+     * @example map.statData().set('DE', { value: 120, status: 'e' })
+     */
+    set(nutsId: string, stat: any): this
+
+    /**
+     * Sets the entire dataset at once, indexed by NUTS ID.
+     * Overwrites any previously loaded data.
+     * @example
+     * map.statData().setData({ DE: 120, FR: 95, IT: 88 })
+     * // or with status:
+     * map.statData().setData({ DE: { value: 120, status: 'e' }, FR: 95 })
+     */
+    setData(data: Record<string, number | string | { value: any; status?: string }>): this
+
+    /**
+     * Sets multi-date data for sparkline maps.
+     * @example
+     * map.statData().setManualMultiDate({ DE: { '2020': 100, '2021': 110 } })
+     */
+    setManualMultiDate(data: Record<string, Record<string, number>>): this
+
+    /** Returns true if data has been loaded. */
+    hasData(): boolean
+
+    /** Returns true if the loaded data contains at least one finite numeric value. */
+    hasNumericData(): boolean
+
+    /** Returns all stat values as a flat array, for use in classification. */
+    getArray(): any[]
+
+    /** Returns all unique stat values, for use in categorical maps. */
+    getUniqueValues(): any[]
+
+    /** Returns the minimum numeric value in the dataset. */
+    getMin(): number | undefined
+
+    /** Returns the maximum numeric value in the dataset. */
+    getMax(): number | undefined
+
+    /** Returns the NUTS ID of the region with the highest value. */
+    getMaxRegionId(): string | undefined
+
+    /** Returns the NUTS ID of the region with the lowest value. */
+    getMinRegionId(): string | undefined
+
+    /** Returns true if the data is ready to be used for rendering. */
+    isReady(): boolean
+
+    /**
+     * Returns the time stamp of the loaded Eurostat dataset.
+     * Reflects the 'time' filter if set, otherwise the first time dimension in the API response.
+     */
+    getTime(): string | undefined
+
+    /** Unit of measure label shown in tooltips. e.g. 'people/km²' */
+    unitText(): string | undefined
+    unitText(text: string): this
+
+    /** Metadata from the Eurostat API response or CSV source. */
+    metadata?: {
+        label?: string
+        href?: string
+        source?: string
+        updated?: string
+        time?: string
+        extension?: any
+    }
+
+    /** Eurostat dataset code. */
+    eurostatDatasetCode_?: string
+    /** CSV source URL. */
+    csvURL_?: string
+
+    /**
+     * Fetches data from the configured remote source (Eurostat API or CSV).
+     * Called internally by the map build pipeline.
+     * @param nutsLevel - NUTS level (0–3).
+     * @param lang - BCP 47 language code. e.g. 'en'
+     * @param callback - Called when data is ready.
+     */
+    retrieveFromRemote(nutsLevel: number, lang: string, callback: () => void): this
+}

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

@@ -0,0 +1,194 @@
+import type { MapInstance } from './MapInstance'
+
+/**
+ * Ensures a <g> element with the specified class exists within the container.
+ * If it exists, clears its contents; if not, creates it.
+ */
+export function ensureGroup(container: any, className: string): any
+
+/**
+ * Updates or creates a CSS rule for a given selector.
+ */
+export function updateCSSRule(selector: string, property: string, value: string): void
+
+/**
+ * Gets the computed font size from a CSS class name.
+ */
+export function getFontSizeFromClass(className: string): number
+
+/**
+ * Gets a computed CSS property value from a CSS class name.
+ */
+export function getCSSPropertyFromClass(className: string, propertyName: string): string
+
+/**
+ * Applies inline styles from computed CSS to an SVG element and its descendants.
+ * Useful for exporting SVGs with CSS styles.
+ */
+export function applyInlineStylesFromCSS(svgElement: SVGElement): void
+
+/**
+ * Applies computed styles to an SVG element for export.
+ */
+export function applyComputedStylesToSVG(svg: SVGElement): void
+
+/**
+ * Ensures an SVG element has explicit width and height attributes.
+ */
+export function ensureSvgSize(svg: SVGSVGElement): void
+
+/**
+ * Converts a bounding box array to a GeoJSON polygon.
+ */
+export function getBBOXAsGeoJSON(bb: [number, number, number, number]): any
+
+/**
+ * Converts a JSON-stat object to an index keyed by geographic codes.
+ */
+export function jsonstatToIndex(jsData: any): Record<string, any>
+
+/**
+ * Converts CSV data to an index keyed by geographic codes.
+ */
+export function csvToIndex(csvData: string, geoCol: string, valueCol: string): Record<string, number>
+
+/**
+ * Formats a number with spaces as thousand separators.
+ */
+export function spaceAsThousandSeparator(number: number): string
+
+/**
+ * Base URL for Eurostat REST API.
+ */
+export const getEstatRestDataURLBase: string
+
+/**
+ * Constructs a URL for fetching Eurostat data.
+ */
+export function getEstatDataURL(datasetCode: string, filters: any, lang?: string, format?: string): string
+
+/**
+ * Gets a URL parameter by name.
+ */
+export function getURLParameterByName(name: string): string | null
+
+/**
+ * Gets a URL parameter by name (alias).
+ */
+export function getParameterByName(name: string): string | null
+
+/**
+ * Checks if a map has a diverging color scheme.
+ */
+export function checkIfDiverging(map: MapInstance): boolean
+
+/**
+ * Centers a diverging color function around a point of divergence.
+ */
+export function centerDivergingColorFunction(colorFunc: any, domain: number[], pointOfDivergence?: number, transform?: (d: number) => number): any
+
+/**
+ * Generates a unique ID with an optional prefix.
+ */
+export function generateUniqueId(prefix: string): string
+
+/**
+ * Eurostat flag codes and descriptions.
+ */
+export const flags: Record<string, string>
+
+/**
+ * Executes a function for all insets recursively.
+ */
+export function executeForAllInsets(
+    insets: any,
+    mainSvgId: string,
+    functionToExecute: (inset: MapInstance, ...args: any[]) => void,
+    parameter?: any,
+    parameter2?: any
+): void
+
+/**
+ * Converts first letter of a string to uppercase.
+ */
+export function upperCaseFirstLetter(string: string): string
+
+/**
+ * Converts a string to lowercase except for first letters of words.
+ */
+export function lowerCaseAllWordsExceptFirstLetters(string: string): string
+
+/**
+ * Creates a download URL for an SVG element.
+ */
+export function getDownloadURL(svgNode: SVGElement): string
+
+/**
+ * Serializes an SVG element to a string.
+ */
+export function serialize(svg: SVGElement): string
+
+/**
+ * Rasterizes an SVG element to a canvas blob.
+ */
+export function rasterize(svg: SVGElement): Promise<Blob>
+
+/**
+ * Converts hex color to RGB object.
+ */
+export function hexToRgb(hex: string): { r: number; g: number; b: number }
+
+/**
+ * Blends multiple colors using multiply blending mode.
+ */
+export function multiplyBlendMultipleHex(colors: string[]): string
+
+/**
+ * Blends colors using average blending.
+ */
+export function averageBlendHex(colors: string[]): string
+
+/**
+ * Interpolates color intensity.
+ */
+export function interpolateIntensity(baseColor: string, idx: number): string
+
+/**
+ * Converts rectangle coordinates to an SVG path string.
+ */
+export function convertRectanglesToPaths(x: number, y: number, width: number, height: number): string
+
+/**
+ * Determines appropriate text color (black/white) for a given background color.
+ */
+export function getTextColorForBackground(backgroundColor: string): string
+
+/**
+ * Gets the CSS selector for data-driven regions on a map.
+ */
+export function getRegionsSelector(map: MapInstance): string
+
+/**
+ * Gets the CSS selector for legend region highlighting.
+ */
+export function getLegendRegionsSelector(map: MapInstance): string
+
+/**
+ * Gets an approximate geographic bounding box for the current map view.
+ */
+export function getApproxCurrentGeoBbox(map: MapInstance): number[]
+
+/**
+ * Gets a region element by ID from the map.
+ */
+export function getRegionById(map: MapInstance, id: string): any
+
+/**
+ * Compact number formatter (e.g., 1000 → "1K").
+ */
+export const compactFormatter: Intl.NumberFormat
+
+/**
+ * Long number formatter.
+ */
+export const longFormatter: Intl.NumberFormat

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

@@ -0,0 +1,21 @@
+import type { MapInstance } from './MapInstance'
+
+/**
+ * Defines the D3 zoom behavior for a map instance.
+ * Handles both geographic zoom and grid cartogram zoom.
+ * @param map - The map instance to add zoom behavior to
+ */
+export function defineMapZoom(map: MapInstance): void
+
+/**
+ * Defines geographic zoom behavior with pan locking and snap-back.
+ * @param map - The map instance
+ */
+export function defineGeographicZoom(map: MapInstance): void
+
+/**
+ * Sets the map view to a specific position and zoom level.
+ * @param map - The map instance
+ * @param pos - Position object with x, y coordinates and z zoom level
+ */
+export function setMapView(map: MapInstance, pos: { x?: number; y?: number; z?: number }): void